Initial public ModelForge release

2026-09-01 21:30:16 +02:00
commit 7082ab955a
490 changed files with 104252 additions and 0 deletions
@@ -0,0 +1,141 @@
+# ITWorx ModelForge
+
+ModelForge is a self-hosted control plane for running AI models on hardware you control. Applications
+ask for a stable capability such as `rag.embedding@1`; ModelForge selects an approved model revision,
+places it on an eligible compute node, and retains the evidence needed to explain and roll back that
+decision.
+
+Current release: **1.2.1**
+
+## What you get
+
+- A web console for models, hardware, capabilities, deployments, incidents and recovery.
+- A FastAPI control plane with capability-scoped service credentials.
+- Outbound-only node agents: compute nodes connect to the control plane and need no inbound agent port.
+- Quarantined model acquisition with immutable revisions, SHA-256 evidence and static inspection.
+- GPU-aware placement, leases, load-on-demand residency and typed runtime workers.
+- Approval-gated promotion, canary and rollback workflows with an append-only audit chain.
+- Backup, restore rehearsal, observability and operational runbooks.
+
+ModelForge is designed for a small self-hosted fleet. It uses Docker Compose rather than Kubernetes,
+and a GPU is needed only on nodes that serve GPU-backed capabilities.
+
+## Quick start
+
+Requirements: Docker Engine 24+, Docker Compose 2+, Python 3.12 for the host-side tools, and at least
+50 GiB free plus room for model weights.
+
+```bash
+python scripts/preflight.py
+cp .env.example .env
+# Generate and enter the distinct secrets described in docs/INSTALLATION.md.
+docker compose -f docker-compose.yml -f docker-compose.production.yml up -d --build
+```
+
+Then verify the control plane and open the console:
+
+```bash
+curl http://127.0.0.1:8000/api/v1/health/live
+curl http://127.0.0.1:8000/api/v1/health/ready
+```
+
+- Console: `http://127.0.0.1:3000`
+- API documentation: `http://127.0.0.1:8000/docs`
+
+`docker-compose.yml` by itself is for development. The production overlay requires separate
+bootstrap, migration-owner and runtime database credentials and applies the production startup
+guards. Follow the complete [installation guide](docs/INSTALLATION.md) before exposing an instance.
+
+## First useful workflow
+
+1. Enrol a compute node with a short-lived, single-use token.
+2. Discover a model and resolve it to an immutable upstream commit.
+3. Approve a download plan; the node agent quarantines, verifies and atomically promotes the files.
+4. Register a versioned capability contract and promote an evidence-backed deployment.
+5. Give an application a credential scoped only to the capability it needs.
+
+The application calls a stable endpoint such as:
+
+```bash
+curl -X POST \
+  -H "Authorization: Bearer $MODELFORGE_CLIENT_CREDENTIAL" \
+  -H "Content-Type: application/json" \
+  -d '{"input":["text to embed"]}' \
+  http://127.0.0.1:8000/api/v1/capabilities/rag.embedding@1/invoke
+```
+
+The caller does not need to know the model name, artifact path, runtime or GPU node. See
+[First run](docs/FIRST_RUN.md) and [Project integration](docs/PROJECT_INTEGRATION.md).
+
+## Architecture
+
+```text
+Applications -> Capability Gateway -> Scheduler -> typed runtime workers
+                       |                 ^
+                       v                 |
+                 Control Plane <--- outbound node agents
+                       |
+             PostgreSQL + Redis + verified artifacts
+```
+
+Important boundaries:
+
+- exact model commits and container digests replace mutable names;
+- `trust_remote_code` remains disabled;
+- production changes require evidence and explicit approval;
+- compute agents publish observations but cannot act as operators;
+- runtime workers have no external network access by default;
+- destructive and recovery actions are planned, bounded and audited.
+
+The [system architecture](docs/architecture/SYSTEM_ARCHITECTURE.md),
+[threat model](docs/security/THREAT_MODEL.md) and
+[model supply-chain policy](docs/security/MODEL_SUPPLY_CHAIN_POLICY.md) describe these guarantees in
+detail.
+
+## Documentation
+
+| Goal | Guide |
+| --- | --- |
+| Install or upgrade | [Installation](docs/INSTALLATION.md) · [Upgrade](docs/UPGRADE.md) |
+| Enrol a compute node | [Node Agent](docs/NODE_AGENT.md) |
+| Configure the platform | [Configuration](docs/CONFIGURATION.md) |
+| Integrate an application | [Project integration](docs/PROJECT_INTEGRATION.md) |
+| Operate and recover it | [Operations](docs/OPERATIONS.md) · [Troubleshooting](docs/TROUBLESHOOTING.md) |
+| Review security | [Security](docs/SECURITY.md) · [Threat model](docs/security/THREAT_MODEL.md) |
+| Understand compatibility | [Compatibility](docs/COMPATIBILITY.md) |
+| See release changes | [Changelog](CHANGELOG.md) · [1.2.1 release notes](docs/RELEASE_NOTES_v1.2.1.md) |
+
+## Repository layout
+
+```text
+backend/          FastAPI control plane, persistence and migrations
+frontend/         React operator console
+node-agent/       Outbound compute-node observer and artifact acquirer
+runtime-worker/   Isolated typed model runtime
+config/           Example capability, policy and model manifests
+docs/             User, architecture, operations and security documentation
+scripts/          Preflight, bootstrap, release and recovery tools
+```
+
+## Development
+
+Each component keeps its own pinned dependencies and tests. The protected-branch validation installs
+all four components, runs linting, strict type checks, tests and the frontend build, verifies Compose
+projections, scans for secrets, and audits Python and production npm dependencies.
+
+```bash
+python -m pytest backend/tests -q
+python -m pytest node-agent/tests -q
+python -m pytest runtime-worker/tests -q
+cd frontend && npm ci && npm test -- --run && npm run build
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) before proposing a change and [SECURITY.md](SECURITY.md) for
+private vulnerability reporting.
+
+## License status
+
+ModelForge is licensed under **GNU AGPL-3.0-or-later**. If you run a modified version for users over
+a network, the AGPL requires that those users can obtain the corresponding source. See
+[LICENSE](LICENSE). Downloaded models, model weights and datasets retain their own upstream license
+terms and are not relicensed by ModelForge.