84 lines
3.6 KiB
Markdown
84 lines
3.6 KiB
Markdown
# 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.
|