Models & output

Do not guess what a model supports. Ask nvoken before admitting the turn.

Current providers

The accepted provider names are:

• anthropic
• openai
• xai
• google

grok, gemini, and claude are model families, not provider names. Mistral, Ollama, and OpenRouter are not available through the current nvoken Runtime.

Discover a model

List the curated catalog, then inspect the exact provider and model ID you plan to use:

const catalog = await client.listModels({ provider: "anthropic" });
const model = await client.getModel({
  provider: "anthropic",
  id: "claude-sonnet-5",
});
 
console.log(catalog.items, model.controls);

The exact model response reports catalog metadata, input media, portable sampling and reasoning controls, tool support, context size when known, and pricing evidence.

Catalog membership is not an account-access check. A model can be advertised while your provider key, region, or plan cannot use it. A real small Invocation is the final access test.

Exact lookup also accepts uncataloged IDs. Use the TypeScript SDK for IDs that contain /, reserved characters, or Unicode so the whole ID is encoded as one path segment.

Sampling and reasoning fail closed

The portable sampling surface currently centers on temperature. Reasoning controls may expose effort or a token budget for qualified models. Tool choice is also model-qualified.

If the exact model descriptor does not advertise a control, omit it. nvoken rejects unsupported or unknown settings before durable admission rather than quietly changing them.

Omitting a setting preserves the provider default.

Send images and PDFs

Invocation input may be a string or an ordered array of text, image, and document blocks:

[
  { "type": "text", "text": "Summarize this chart." },
  {
    "type": "image",
    "source": {
      "media_type": "image/png",
      "data": "<standard-padded-base64>"
    }
  }
]

Images support GIF, JPEG, PNG, and WebP. Documents are inline PDFs. URLs and provider file IDs are not accepted as media sources.

Admission checks the decoded format, dimensions, size, request total, and the selected model's declared input capability before storing the turn. Current request bounds allow up to eight media blocks and 16 MiB decoded media in total; an image may be at most 5 MiB and 8000 by 8000 pixels, while one PDF may be at most 16 MiB.

Google models currently accept text plus JPEG, PNG, and WebP images through nvoken. GIF and PDF input are not available for Google models. Check the exact descriptor because capability is model-specific.

Request structured output

structured_output asks the model to submit one object that nvoken validates against a bounded JSON Schema:

{
  "structured_output": {
    "schema": {
      "type": "object",
      "properties": {
        "category": {
          "type": "string",
          "enum": ["billing", "technical", "other"]
        },
        "needs_human": { "type": "boolean" }
      },
      "required": ["category", "needs_human"],
      "additionalProperties": false
    }
  }
}

The schema must be self-contained and use nvoken's documented subset. References and unknown keywords are rejected. The TypeScript SDK preflights the same subset before transport.

The model submits the object through a reserved durable tool, then finishes the turn normally. Prose or a fenced JSON block does not count as a structured submission. If no valid object is accepted, the Invocation fails with structured_output_unsatisfied.

Put a cost guardrail on the turn

limits.max_estimated_cost_usd uses nvoken's standard list-price data. It is a guardrail, not a charge reservation or billing ledger.

Inspect the selected model first. Pricing status means:

• priced: nvoken has standard USD pricing for the exact selection.
• unpriced: the catalog knows pricing is absent.
• unknown: the adapter cannot decide before execution.

A cost-capped turn fails closed when usable pricing is unavailable. Omit the cap when intentionally testing a new model whose pricing has not reached the catalog yet.

Provider-side web-search charges are outside this estimate. Bound those with the tool's max_uses setting.

Optional finish-time review

outcome is an experimental self-review. Give it a description and rubric, and the selected model reviews its work once when it would otherwise finish. The review continues the same turn within its ordinary limits; it does not produce an independent score or verdict.

Outcome review cannot currently be combined with structured output.