{"id":29565658,"url":"https://github.com/abilian/smo-monorepo","last_synced_at":"2025-12-31T14:31:27.644Z","repository":{"id":303619381,"uuid":"1015998022","full_name":"abilian/smo-monorepo","owner":"abilian","description":"NEPHELE SMO refactored as a monorepo","archived":false,"fork":false,"pushed_at":"2025-07-08T14:43:07.000Z","size":326,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-08T15:27:52.750Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abilian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-08T10:38:35.000Z","updated_at":"2025-07-08T14:43:11.000Z","dependencies_parsed_at":"2025-07-08T15:40:25.559Z","dependency_job_id":null,"html_url":"https://github.com/abilian/smo-monorepo","commit_stats":null,"previous_names":["abilian/smo-monorepo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/abilian/smo-monorepo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fsmo-monorepo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fsmo-monorepo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fsmo-monorepo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fsmo-monorepo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abilian","download_url":"https://codeload.github.com/abilian/smo-monorepo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fsmo-monorepo/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265837750,"owners_count":23836558,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-18T21:35:04.683Z","updated_at":"2025-12-31T14:31:27.639Z","avatar_url":"https://github.com/abilian.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Synergetic Meta-Orchestrator (SMO) - H3NI Refactoring\n\nThe Synergetic Meta-Orchestrator (SMO) is an advanced, intent-driven control plane for deploying, managing, and optimizing complex, multi-component applications across distributed Kubernetes environments.\n\nThis repository contains the full source code for the SMO project, **refactored into a modular monorepo structure, with additional CLI capacities.**\n\n\n## Core Features\n\n*   **Intent-Based Deployment**: Deploy complex applications, known as Hyper Distributed Application Graphs (HDAGs), from a single declarative YAML descriptor.\n*   **Optimized Placement \u0026 Scaling**: Utilizes mathematical optimization (via CVXPY) to determine the ideal cluster placement for each service and to dynamically adjust replica counts based on real-time metrics.\n*   **Multi-Cluster Orchestration**: Leverages [Karmada](https://karmada.io/) as a robust execution engine to manage resources across a federation of Kubernetes clusters.\n*   **Proactive Observability**: Automatically generates and publishes detailed [Grafana](https://grafana.com/) dashboards and [Prometheus](https://prometheus.io/) alert rules, providing immediate operational visibility for deployed applications.\n*   **Modular Architecture**: The project is cleanly separated into a core logic library (`smo-core`) and distinct user interfaces (`smo-cli` and `smo-web`), promoting reusability and clean design.\n\n\n## Project Architecture\n\nThis monorepo is structured into three distinct Python packages, creating a clean, layered architecture:\n\n1.  **`smo-core`**: The foundational library and engine of the SMO. It contains all the business logic, database models, helper utilities, and orchestration algorithms. It is completely headless and framework-agnostic.\n\n2.  **`smo-cli`**: A powerful command-line interface for interacting with the SMO engine. It provides a direct, scriptable way to manage the entire lifecycle of HDAGs. It depends on `smo-core`.\n\n3.  **`smo-web`**: A modern, API-first web service built with [Connexion](https://connexion.readthedocs.io/). It exposes the SMO's functionality via a REST API defined in an OpenAPI (YAML) specification, complete with an interactive Swagger UI. It also depends on `smo-core`.\n\n4. **`smo-sdk`**: A Python SDK, auto-generated from the smo-web OpenAPI specification. It provides a convenient, type-safe, and pythonic way to interact with the SMO REST API from other applications, tests, or scripts. It supports both synchronous and asynchronous operations. This is still experimental and used mostly as a debugging tool.\n\n=\u003e [Additional technical details and implementation notes can be found in the `NOTES.md` file.](./NOTES.md)\n\n=\u003e [TODO items and future work are tracked in the `TODO.md` file.](./TODO.md)\n\n### Dependency Graph\n\n```mermaid\ngraph TD\n    subgraph User Interfaces\n        A[smo-web]\n        B[smo-cli]\n    end\n\n    subgraph Core Logic\n        C[smo-core]\n    end\n\n    subgraph External Systems\n        D[Karmada]\n        E[Prometheus]\n        F[Grafana]\n        G[OCI Registry]\n        H[Database: PostgreSQL or SQLite]\n    end\n\n    A --\u003e C\n    B --\u003e C\n\n    C --\u003e D\n    C --\u003e E\n    C --\u003e F\n    C --\u003e G\n    C --\u003e H\n```\n\n---\n\n## Development Setup\n\nThis guide assumes you have **Python 3.12+** and `uv` installed.\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://gitlab.eclipse.org/eclipse-research-labs/nephele-project/opencall-2/h3ni/smo-monorepo.git\ncd smo-monorepo\n```\n\n### 2. Create a Virtual Environment and Install Packages\n\n```bash\nuv sync\n```\n\n## Using the Packages\n\n### `smo-cli`\n\nThe command-line interface is the most direct way to interact with the SMO engine. It stores its state in a local SQLite database located in `~/.smo/`.\n\n#### First-Time Setup\n\nBefore first use, you must initialize the CLI. This creates the configuration file and database.\n\n```bash\nsmo-cli init\n```\nAfter running this, **you must edit the configuration file** at `~/.smo/config.yaml` to point to your Karmada kubeconfig, Prometheus, and Grafana instances.\n\n#### Basic Usage\n\n```bash\n# Sync cluster information from Karmada into the local DB\nsmo-cli cluster sync\n\n# List all known clusters\nsmo-cli cluster list\n\n# Deploy a graph from a YAML file into a project\nsmo-cli graph deploy --project my-project /path/to/my-hdag.yaml\n\n# List all deployed graphs\nsmo-cli graph list\n\n# Get detailed information about a specific graph\nsmo-cli graph describe my-test-graph\n\n# Trigger a re-placement optimization for a running graph\nsmo-cli graph re-place my-test-graph\n\n# Completely remove a graph\nsmo-cli graph remove my-test-graph\n```\n\nFor more commands, use `smo-cli --help` or `smo-cli \u003ccommand\u003e --help`.\n\n### `smo-web`\n\nThe web application provides a REST API for the SMO engine. It is designed to run as a containerized service and connect to a PostgreSQL database.\n\n#### Configuration\n\nThe web app uses environment variables for configuration, typically loaded from a `.env` file. You can create a `config/flask.env` file within the `smo-web` directory to configure the database connection, Karmada path, etc.\n\n#### Running Locally for Development\n\nThe recommended way to run the web app for development is with `uvicorn`, which provides live reloading.\n\n```bash\n# Navigate to the web package directory\ncd smo-web\n\n# Run the uvicorn server\nuvicorn smo_web.app:app --reload\n```\n\nThe API will be available at `http://localhost:8000`. The interactive Swagger UI documentation can be accessed at `http://localhost:8000/ui/`.\n\n#### Running in Production\n\nFor production, use a process manager like Gunicorn with the Uvicorn worker class. A `Dockerfile` is provided to build a production-ready container image.\n\n```bash\n# Build the Docker image\ndocker build -t smo-web:latest -f smo-web/Dockerfile .\n\n# Run the container (example)\ndocker run -p 8000:8000 -v ~/.kube:/root/.kube smo-web:latest\n```\n*(Note: You will need a running PostgreSQL instance and will need to configure the container's environment variables to connect to it.)*\n\n\n## Testing\n\nEach package contains its own dedicated test suite.\n\n```bash\nuv run make test\nuv run make lint\n# Or\nuv run nox\n```\n\n## Prerequisites \u0026 Environment\n\nTo fully utilize the SMO, your environment should have the following systems running and accessible:\n\n*   **Kubernetes \u0026 Karmada**: A running Karmada control plane with at least one member Kubernetes cluster joined.\n*   **OCI Registry**: A container registry (like Docker Hub, Harbor, or a local instance) accessible from your Kubernetes clusters.\n*   **Prometheus**: For monitoring metrics that drive the scaling algorithms.\n*   **Grafana**: For visualizing the auto-generated dashboards.\n*   **`hdarctl` \u0026 `helm`**: These CLI tools must be installed and available in the `PATH` of the environment running the SMO (either locally for the CLI or inside the web app's container).\n\nSee the \u003chttps://gitlab.eclipse.org/eclipse-research-labs/nephele-project/opencall-2/h3ni/smo-deploy.git\u003e repository for helpers to install and configure a proper testing environment.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabilian%2Fsmo-monorepo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabilian%2Fsmo-monorepo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabilian%2Fsmo-monorepo/lists"}