3.6 KiB
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 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.
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
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.