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,83 @@
+# Capabilities
+
+A capability is the stable interface a project binds to. `rag.embedding@1` is a promise about input
+and output shape and about semantics — not about which model, node or file satisfies it.
+
+## Why this exists
+
+Bind an application to a model and you have coupled it to a decision you will want to change: a
+better model, a different quantisation, a different node. Every one of those becomes a
+coordinated change across every consumer.
+
+Bind it to a capability and the substitution is ModelForge's problem. That is why
+[SYSTEM_ARCHITECTURE.md](architecture/SYSTEM_ARCHITECTURE.md) establishes that applications bind to capabilities and never to model
+paths, and why nothing in the platform couples project code to a Hugging Face repository name.
+
+## The pieces
+
+| Concept | What it is |
+| --- | --- |
+| **Capability** | A named kind of work: `rag.embedding`, `document.ocr`, `vision.embedding` |
+| **Capability contract** | A version of that capability with a fixed input and output schema |
+| **Capability deployment** | A specific artifact set and runtime profile serving a contract |
+| **Project binding** | A project's declaration that it uses a contract, on a channel |
+| **Service client** | An application's credential, scoped to specific capabilities |
+
+A contract has at most one `stable` deployment at a time. That is enforced by a partial unique index
+in the database *and* asserted by a platform invariant — two layers, because the invariant is there
+for the case where the guard has been bypassed.
+
+## Contracts shipped with v1.0.0
+
+| Capability | Version |
+| --- | --- |
+| `rag.embedding` | 1 |
+| `rag.reranking` | 1 |
+| `document.ocr` | 1 |
+| `vision.embedding` | 1 |
+| `speech.transcription` | 1 |
+| `assistant.general` | 1 |
+| `assistant.vision` | 1 |
+
+A contract being defined in a manifest does **not** mean anything is serving it. A deployment
+requires a model artifact acquired, verified and promoted through the lifecycle. A newly installed
+control plane has contracts available to register and no deployments — see
+[FIRST_RUN.md](FIRST_RUN.md).
+
+## Channels
+
+`stable`, `experimental` and the production flag are separate ideas. A project can bind to
+`experimental` for a capability while another binds to `stable` for the same one, and a deployment
+being production is an explicit, approved, audited state — `no_hidden_auto_promotion` asserts that
+no production deployment exists without a recorded production approval.
+
+## Upgrade classes
+
+Every contract declares what a change to it means:
+
+| Class | Meaning |
+| --- | --- |
+| compatible | The replacement can serve existing consumers unchanged |
+| `requires_reindex` | The embedding space changed; existing vectors are not comparable |
+
+`requires_reindex` is the one that cannot be waved through. A project binding must declare that it
+supports reindex migration before it can bind such a contract, and the migration engine will not
+swap an alias underneath data that has not been reindexed.
+
+## Invoking
+
+See [PROJECT_INTEGRATION.md](PROJECT_INTEGRATION.md).
+
+## What a capability guarantees
+
+- the input and output schema for its version;
+- that only an approved, verified artifact is behind it;
+- that a refusal is named — `NO_ELIGIBLE_NODE`, `CAPACITY_CONSTRAINED`, `CAPABILITY_NOT_AUTHORIZED` —
+  rather than an answer built on something stale.
+
+## What it does not guarantee
+
+- which model answered, or that the same model answers next time;
+- that a deployment exists at all, if nothing has been promoted;
+- latency: that depends on the node, the model and current pressure. The gateway reports queue and
+  inference time per request so you can see which is which.