# Models and bundles

> A model on Katara is a pinned bundle that every provider serves byte-for-byte.

Section: How it works. Web page: https://docs.katara.com/concepts/models/

Every model behind Katara Cortex is a *bundle*: a published description of exactly which weights, tokenizer, chat template, and runtime a provider must run. Every provider serving a bundle runs the same thing, so when Cortex sends a request to `katara/llama-3.1-8b-instruct@1` it gets that model, whoever serves it.

## Model names in requests

The API serves one model, `katara/cortex`. Any model name in a request is accepted and routed to it: `katara/cortex@1`, a Claude, GPT or Gemini name, a bundle id, or a name Katara has never seen. Replies name `katara/cortex`. Cortex then picks one of the bundles below for each request ([Katara Cortex](https://docs.katara.com/concepts/cortex.txt)).

A request paid per call with x402 may also name `katara/cortex-genius` or `katara/cortex-smart`, which fix the model ([Choosing a model](https://docs.katara.com/developers/x402.txt#choosing-a-model)). A chat completion paid that way names the model it asked for. A request with a key that names either one is refused.

## Why bundles

Marketplaces without this rule end up with quietly different models behind one name. Katara's validators send known prompts to every provider and score the answers against recorded results. That only works when the model is fixed.

It also keeps prices comparable. Providers compete on price and speed for the same bundle, not on what they secretly run.

## Who publishes bundles

Katara does. A new model means writing the bundle, pinning it on reference hardware, recording the validation prompts, and approving it. Providers then choose from the approved list. They cannot add their own.

## Bundle manifests

Each approved bundle's manifest is published at `https://docs.katara.com/bundles/<bundle>.json`, the address recorded on chain with its hash. Providers pass that file to the node. Two bundles take Cortex requests on Katara Community today: `katara/qwen3-coder-30b-a3b@1` (Qwen3-Coder 30B-A3B Instruct, with tool use for coding agents) and `katara/llama-3.1-8b-instruct@1` (Llama 3.1 8B Instruct, chat only). The other published manifests are serving profiles of the same and other open models for the hardware a provider runs.

Which machines can serve which bundle is set out in [Hardware compatibility](https://docs.katara.com/providers/hardware.txt), generated from these manifests.

## Live availability

`/v1/models` lists `katara/cortex` and, marked `billing_methods: ["x402"]`, the two models only x402 requests may name. A bundle takes part in routing while a registered provider has a valid offer and passes the routing health checks, or its managed vendor is configured and available. A short period at full capacity does not take a bundle out; it returns when service recovers. When nothing can take a request, the answer is `503 no_capacity`, so clients must still handle it.

## Capabilities

`/v1/models` lists Cortex's `capabilities`, the union of what its candidates take: whether it streams, takes tools, structured output, reasoning, images, sound, video and documents, and its output cap. `tools: true` carries a `tool_contract` with the accepted `tool_choice` modes and the longest tool name. See [Tool calling](https://docs.katara.com/developers/tools.txt).

Each candidate is checked against the request on its own: a candidate that cannot take a parameter, a tool setting or an attachment is passed over, and the request is refused with `feature_not_supported` only when no candidate can serve it. `supported_params` on the Cortex row lists the parameters every candidate takes. `temperature` takes 0 to 2; a value above a model's own cap is lowered to that cap.

Some fields that OpenAI clients send change nothing a Katara reply can contain, so every model accepts them with any value and drops them: `metadata`, `store`, `service_tier`, `safety_identifier`, `verbosity`, `moderation`, `prediction`, `prompt_cache_options`, `prompt_cache_retention` and a `modalities` list of `["text"]`. `user` is dropped too and never reaches a provider; a vendor sees only an opaque per-account value. `seed` is passed to a model that reads it and dropped elsewhere, since it is best effort everywhere. `prompt_cache_key` keeps a conversation on the model that already holds its prompt in cache, as `katara.session` does. `max_completion_tokens` works as `max_tokens` when that is absent. A `developer` message is sent as `system`. Audio output (`audio`, or `modalities` naming `audio`) is refused.

## Versions

The `@1` in a model id is the bundle version. A new version, for example one that adds a CUDA profile or changes quantisation, gets a new number. Old versions keep working until they are retired.

## Katara Cortex

`katara/cortex` is not a bundle. It is the routing model: every request is served by one of the catalog models, chosen for availability, task and price. See [Katara Cortex](https://docs.katara.com/concepts/cortex.txt).

## Managed models

Some models are served through Katara's own model providers rather than a provider's node. No Community provider runs them. With Katara Community on, they come after it: picked only when no marketplace provider can take the request. Each is charged at the price Katara lists for it, in credits or USDC; a wallet-paid request is quoted at that price and settled for what the reply cost. The Deep, Standard and Light models, and some backup models, always reason before they answer. A request with a smaller `max_tokens` than they need to finish reasoning is still served: the model is given room, and the reply you see ends at your `max_tokens` with `finish_reason: "length"`. That room may be used in full, so the request is held or quoted for it. Their reasoning is billed as output whether or not it is shown. Katara decides how much it reasons; a `reasoning_effort` in the request is accepted and does not change it. The Deep, Standard and Light models read images, sound, video and PDFs ([Images, audio, video and PDFs](https://docs.katara.com/developers/media.txt)). Inside Cortex they serve by tier: Light for light requests, Standard for ordinary ones, Deep for hard ones ([Katara Cortex](https://docs.katara.com/concepts/cortex.txt#light-standard-and-deep)). Each takes 1,048,576 tokens of context and writes up to 65,536, at one price whatever the prompt's length. A prompt that starts the way an earlier one did is partly read from cache, and those tokens are billed at the model's cached input rate ([Caching](https://docs.katara.com/concepts/cortex.txt#caching)).

Two prices rise: the Deep model from 1 December 2026 and the Standard model from 1 January 2027. Each changes at 00:00 UTC that day, in credits and USDC alike. A request is charged at the price in force when it was accepted, even if it finishes after the change. Per million tokens, in credits (USD) or USDC:

| Model | | Input | Cached input | Output | Explicit cache, per hour |
| --- | --- | --- | --- | --- | --- |
| Deep | until 30 November 2026 | 2.40 | 0.12 | 12.00 | not offered |
| | from 1 December 2026 | 4.80 | 0.24 | 24.00 | not offered |
| Standard | until 31 December 2026 | 0.90 | 0.09 | 4.50 | 0.60 |
| | from 1 January 2027 | 1.80 | 0.18 | 9.00 | 1.20 |
| Light | no change scheduled | 0.36 | 0.036 | 3.00 | 1.20 |

## Compatibility and Live Offers

The public `https://docs.katara.com/hardware.json` describes pinned profiles and curated hardware choices. `https://docs.katara.com/setup.json` lists the same published serving manifests. Both carry the same catalog revision. Hardware documentation is generated from that catalog and the same matching rules.

`GET https://api.katara.com/v1/discovery/availability` reports active provider offers separately. Zero means no active offers were observed for that model. A failed, stale or missing observation means availability is unknown. Offers are signed identities and recent activity; routing still checks health, capacity and the requested capabilities.

## Model Identity

Weights, tokenizer, chat template and runtime are pinned by the bundle. Provider setup verifies the selected manifest checksum and model identifier, and the node verifies downloaded artifacts before advertising. Offers, tickets and receipts bind the exact bundle and runtime profile to a registered service key.

These checks detect changed artifacts and identity mismatches. They do not prove that an independently operated provider used those weights for every request. Valid output, metering checks, runtime failure reports and provider feedback identify operational problems. Reference audits remain optional and require a suitable reference system. Performance reports and signed diagnostics are provider observations, not execution attestations.