The capability contract

The contract is what makes the layers swappable. A client reads it and adapts; it never hard-codes which engine is behind the address.

OdyssAI-X advertises what it can do in two places:

• an engine-wide document at GET /.well-known/inference-engine.json;
• a per-model x_odyssai block on every entry of GET /v1/models.

A client such as Nemo, or the CoeOS box, reads both when it pairs with an engine: which API dialects are served, whether the admin surface needs a token, which models are loaded, how much context each one takes, whether it accepts tools or images. Because the discovery is data, not code, you can put a different engine behind the same address and the client adapts on the next probe.

The engine document

{
  "name": "OdyssAI-X",
  "vendor": "odyssai.eu",
  "version": "<engine version>",
  "api_compat": ["openai/v1", "anthropic/v1"],
  "auth": {
    "required": false,
    "scheme": "bearer",
    "scope": "/admin/*",
    "public_routes": ["/v1/*", "/health", "/.well-known/*"],
    "eventsource_query_fallback": true
  },
  "features": [
    "sse-streaming", "tool-calling", "vision", "prefix-cache",
    "speculative-decoding", "distributed-inference", "kv-cache-q8",
    "openai-models-extended", "cloud-passthrough", "fallback-routing"
  ],
  "limits": { "max_concurrent_requests": 16, "max_prompt_chars": 1000000 },
  "admin": {
    "pools_endpoint": "/admin/pools",
    "clusters_endpoint": "/admin/clusters/{id}",
    "inventory_endpoint": "/admin/inventory",
    "runs_endpoint": "/admin/runs",
    "sync_matrix_endpoint": "/admin/sync/matrix",
    "models_dir_configurable": true,
    "supports_pool_load_unload": true,
    "supports_hot_swap": false
  },
  "extensions": {
    "x_odyssai": { "doc": "…", "fields": ["loaded", "loading", "pool", "…"] }
  }
}

Field	What it tells the client
name, vendor, version	Which engine answers. A client may gate a feature on the version.
api_compat	The dialects served: OpenAI /v1/chat/completions and Anthropic /v1/messages, both at v1.
auth	Whether /admin/* needs a Bearer token (required is true only when the operator set one), and which routes are always public.
features	Engine-wide capabilities: streaming, tool calling, vision, the KV prefix cache, speculative decoding, distributed inference, cloud passthrough, fallback routing.
limits	Concurrency and prompt-size ceilings the client should respect.
admin	Where the management endpoints live and what they support, so a client can offer load and unload without guessing routes.
extensions.x_odyssai	The list of per-model fields the client will find in /v1/models.

The per-model block

Every model listed by /v1/models carries an x_odyssai object. Its fields:

Group	Fields	Meaning
State	loaded, loading, warm, admin_loadable	Whether the model is ready, being loaded, kept warm, or can be loaded on request.
Placement	pool, backend, nodes	Which cluster serves it, over which transport, on how many nodes.
Size	context_length, max_output_tokens, quantization, size_bytes, family	What the client must budget for, and which model family it is.
Abilities	modalities, supports_tools, supports_vision, supports_json_mode, supports_streaming	What the client may offer on this model.
Performance	estimated_tps, estimated_load_s, kv_cache_q8	Expected throughput, expected load time, whether the KV cache is quantised.

A cluster serving a coder MoE and a small vision model advertises supports_vision: true only on the vision entry, each with its own pool and node layout. This is how a client builds an accurate model picker without probing each model by hand, and how the CoeOS box knows which of its axes are servable right now.

Why it matters

• Replaceable layers. Swap a single-node pool for a distributed one behind the same address; the client re-reads the contract and adjusts. No client redeploy.
• Honest routing. A client will not offer a tool call to a model whose block says supports_tools: false, and the box will not route an axis to a model that is not loaded.
• One picker, many engines. Pair several engines; each contract feeds one unified catalogue with correct per-model capabilities.

Read next

• HTTP API — the endpoints the contract describes.
• Architecture overview — where the contract sits in the three layers.
• Nemo — the client that consumes it; CoeOS box — the router that does too.