# Capability declaration

> An agent's model requirements as declarative constraints.

`@kindgi/specs/capability.schema.json`, schema version 1.1.0.

An agent's model requirements as declarative constraints. The model router matches capabilities against registered providers, respecting per-tenant policy. `defineCapability` validates a declaration against this schema; a declaration that no registered provider satisfies fails at routing time with `capability-unsatisfiable`.

- `kind` (string): Resource kind this capability requests. Open string: `examples` lists the well-known kinds, and adapters can declare their own. Absent means `llm-inference`. The router only considers providers whose `capabilityKind` equals it (a provider that declares none counts as `llm-inference`). Added in schema-version 1.1.0.
- `needs` (array of [Requirement](https://docs.kindgi.com/v0.1.10/reference/schemas/capability.md#requirement), required)
- `prefer` (array of [Preference](https://docs.kindgi.com/v0.1.10/reference/schemas/capability.md#preference)): Soft preferences: the router picks the highest-scoring model that also satisfies all 'needs'.
- `budget` ([Budget](https://docs.kindgi.com/v0.1.10/reference/schemas/capability.md#budget)): Per-invocation budget. Declarative: carried with the declaration but not enforced by the runtime (per-turn spend is capped by the agent's `budget.maxCostUsd`).

## Definitions

### Requirement

Type: [FeatureRequirement](https://docs.kindgi.com/v0.1.10/reference/schemas/capability.md#featurerequirement) or [ContextRequirement](https://docs.kindgi.com/v0.1.10/reference/schemas/capability.md#contextrequirement) or [CostRequirement](https://docs.kindgi.com/v0.1.10/reference/schemas/capability.md#costrequirement) or [RegionRequirement](https://docs.kindgi.com/v0.1.10/reference/schemas/capability.md#regionrequirement) or [LatencyRequirement](https://docs.kindgi.com/v0.1.10/reference/schemas/capability.md#latencyrequirement) or [ProviderRequirement](https://docs.kindgi.com/v0.1.10/reference/schemas/capability.md#providerrequirement) or [ModelRequirement](https://docs.kindgi.com/v0.1.10/reference/schemas/capability.md#modelrequirement)

### FeatureRequirement

- `feature` (`"structured-output"` | `"vision"` | `"audio-input"` | `"audio-output"` | `"tool-use"` | `"parallel-tool-use"` | `"thinking"` | `"long-context"` | `"code-execution"` | `"web-search"` | `"file-search"` | `"streaming"` | `"batch"`, required)

### ContextRequirement

- `contextWindow` (object, required)

  - `op` (`">="` | `">"` | `"="` | `"<="` | `"<"`, required)
  - `value` (integer, required)

### CostRequirement

- `costPerCall` (object, required)

  - `op` (`">="` | `">"` | `"="` | `"<="` | `"<"`, required)
  - `usd` (number, required)

### RegionRequirement

- `region` (string, required): Geographic region constraint (e.g. 'eu-only', 'us-only', 'us-gov'). Enforced by the router against each provider's declared region; a tenant policy's `regionAllow` can constrain it further.

### LatencyRequirement

- `p95LatencyMs` (object, required)

  - `op` (`"<="` | `"<"`, required)
  - `value` (integer, required)

### ProviderRequirement

Hard constraint on allowed providers (allowlist) or disallowed providers (denylist). Tenant policy can narrow the set further.

- `providers` (object, required)

  - `allow` (array of string)
  - `deny` (array of string)

### ModelRequirement

Hard constraint on allowed models (allowlist) or disallowed models (denylist), matched against each provider's model names (`ModelInfo.name`). Can be combined with a providers requirement. Tenant policy can narrow the set further. Added in schema-version 1.1.0.

- `models` (object, required)

  - `allow` (array of string)
  - `deny` (array of string)

### Preference

- `feature` (string, required): A capability feature or a soft attribute (e.g. 'lower-cost', 'lower-latency', 'higher-accuracy').
- `weight` (number, required)

### Budget

- `maxCostUsd` (number)
- `maxTokens` (integer)
- `maxDurationMs` (integer)