Models & Providers

Choose a model alias in your program, bind it to a provider in your host, and explicitly grant that capability to the session. A provider key or upstream model name alone does not create a binding or grant.

Command Line

The connector and media references in this section describe the native kaya-tool-server. Browser configuration is described in the WebAssembly section.

Kaya requests a logical model alias. The session ToolMap grants its capability, and the Rust tool-server manifest binds the alias to a connector, upstream model, endpoint, credential source, and defaults. This applies to text, image, speech, video, research generation, and finite decisions.

For ordinary text, model: "gemini-fast" requires an admitted kaya.model.gemini-fast route and a provider binding named gemini-fast. Writing an upstream model ID or a provider-looking prefix does not configure that route. A deployment may deliberately use an upstream ID as its alias, but must still bind and grant the exact name.

See Configuration for the local setup from one server manifest and advanced explicit client configuration. Changing public binding configuration produces a new derived revision; retained work cannot silently cross it.

Linked repository manifests and complete example projects require Kaya repository access. The Configuration guide provides inline setup for the included native executables.

Credential references in the checked example

These are the environment references in the kaya-tool-server example manifest, not fixed variables built into the Kaya language. An operator can choose other environment names in credential.env. Provider credentials belong in the tool-server process environment.

A selected connector with a missing required value prevents the tool server from loading that binding. The error names the manifest's environment reference. Restart the tool-server process after changing its environment or manifest. Provider keys do not become session grants, and Kaya does not choose another provider when a key is missing.

The example admission names KAYA_TOOL_SERVER_TOKEN for connection authentication, separately from upstream provider keys. In automatic local setup, an absent dedicated token is generated privately for the supervisor's lifetime; a supplied token retains precedence. Advanced client manifests may reference an endpoint through KAYA_TOOL_SERVER_ENDPOINT. See the checked client manifest.

Text models — generate()

The native model adapter supports explicit protocol families. The following fragments show the relationship between a connector and a logical binding; place them inside one server models entry and add the matching server admission as shown in Configuration. Automatic local setup supplies admitted text defaults for new sessions; explicit client or session grants retain precedence. Replace upstream placeholders with models available to your provider account or local server. Provider catalogs and availability are deployment choices, rather than a permanent list of language-defined model names.

Anthropic

{
  "connectors": {
    "anthropic-direct": { "protocol": "anthropic", "credential": { "env": "ANTHROPIC_API_KEY" } }
  },
  "bindings": {
    "writing": { "connector": "anthropic-direct", "upstream_model": "replace-with-an-anthropic-model-id" }
  }
}

OpenAI

{
  "connectors": {
    "openai-direct": { "protocol": "open_ai_responses", "credential": { "env": "OPENAI_API_KEY" } }
  },
  "bindings": {
    "openai-fast": { "connector": "openai-direct", "upstream_model": "replace-with-an-openai-model-id" }
  }
}

Gemini

{
  "connectors": {
    "gemini-direct": { "protocol": "gemini", "credential": { "env": "GEMINI_API_KEY" } }
  },
  "bindings": {
    "gemini-fast": { "connector": "gemini-direct", "upstream_model": "replace-with-a-gemini-model-id" }
  }
}

Vertex

{
  "connectors": {
    "vertex-enterprise": {
      "protocol": "vertex",
      "endpoint": { "env": "VERTEX_MODEL_ENDPOINT" },
      "credential": { "env": "VERTEX_ACCESS_TOKEN" }
    }
  },
  "bindings": {
    "vertex-gemini": { "connector": "vertex-enterprise", "upstream_model": "gemini-replace-with-an-admitted-model-id" }
  }
}

The native Vertex adapter requires an explicit endpoint. Its upstream model selects the gemini or claude publisher; a vertex- prefix in Kaya source does not configure authentication or select that adapter.

Local Ollama

{
  "connectors": {
    "ollama-local": { "protocol": "ollama", "endpoint": "http://127.0.0.1:11434/" }
  },
  "bindings": {
    "local-chat": { "connector": "ollama-local", "upstream_model": "llama3.2:3b" }
  }
}

Here local-chat is the Kaya alias and llama3.2:3b is an example installed Ollama model. Native model bindings also accept a colon in the alias; using a simple alias keeps the public name independent of upstream model spelling.

Additional native protocol families and their admitted controls are described in the kaya-tool-model README.

Default and quality names

Choose an explicit admitted alias or configure the session's default model. The route resolver uses the exact kaya.model.<alias> grant when present, or the explicitly granted kaya.model.default route when absent. The selected provider must still admit the requested alias. A default grant does not make unknown model names valid.

Names such as highQuality are ordinary text aliases: define their server bindings and session grants. Legacy kayad profile mappings do not route ordinary text calls or provide provider-error fallback.

Coding-agent presets

Reserved agent spellings such as claude-code:<preset>, claude-cli, and opencode:<preset> select the separate kaya:agent/run@1 route. They require a grant for kaya.agent.<selected spelling> or an explicit agent default route, a matching provider preset, a configured executable and its authentication. Installing a CLI alone does not grant a session access. See Native Coding Profiles.

Testing

Attach and grant the scripted Rust model provider for offline tests. That provider can supply named scenarios and the mock <response> canned-text form; a mock-looking name does not install a provider or create a grant. See Testing AI Features.

Decision models — pick(), is() and finite classification

Native decision inference has its own kaya:ai/decision@1 / decide operation and kaya.decision.<alias> grant. It supports the existing pick, semantic is, string-literal union as, and finite typed free-form input paths. Ordinary generation uses its existing model and grant.

The server's decisions groups support four protocol families:

OpenAI appends /decisions; TypeSafe and Ollama append /systemone; OpenRouter appends /decisions to its alpha base. Custom endpoints use the same base-directory convention. A decision binding must explicitly set reviewed_decision_support: true; observed capability metadata and reviewed effective limits can narrow it further. Native Ollama decisions require a decision-capable local model and a compatible server, not a cloud model. OpenRouter discovery requests the decisions output modality and remains advisory: discovering a model grants no execution authority. Its separately admitted kaya:ai/decision-discovery@1 operation is discover_decision_models. A decide grant does not include discovery.

Set tools.default_decision_model in a program's job configuration or default_tool_map.default_decision_model in a daemon client manifest. KAYA_DEFAULT_DECISION_MODEL supplies the captured host default when the session has no selector. Explicit model: has precedence and can select an admitted generation alias. If no decision default is configured, existing generation behavior continues.

See Decision bindings and the runnable routing example. Dedicated Clef, Perplexity, Nimble and Tev1 integrations are deferred; a reviewed generic OpenRouter or local Ollama binding can expose compatible models without a separate vendor adapter.

Research aliases — generateResearch()

Research aliases are deployment-defined rather than a fixed model list. The Rust server supports OpenAI Responses, Gemini Interactions, and Vertex Interactions connectors. Existing source names such as deep-research-pro-preview-12-2025, o3-deep-research, and o4-mini-deep-research continue to work when the server binds that exact name and the session grants kaya.research.<name>.

The program never selects the physical provider. An operator can map the same logical alias to another endpoint or upstream model; the resolved binding gets a new derived revision, so retained recovery and checked caches cannot silently cross the change. See Research bindings.

Image provider families — generateImage()

OpenAI (GPT Image)

An OpenAI connector normally references OPENAI_API_KEY. The manifest may bind an alias such as book-illustration to a current image model such as gpt-image-2; Kaya source sees only the alias.

Google Gemini image models

References GEMINI_API_KEY in the Rust tool-server environment. Gemini image bindings can accept ordered inputImage artifacts for image-to-image work.

Google Imagen (Vertex AI)

References a short-lived GOOGLE_ACCESS_TOKEN and an explicit project/location endpoint in the manifest. Imagen bindings currently provide text-to-image generation; they do not silently accept and drop reference images.

Stock & search photos

• unsplash — requires admitted kaya.image-search.unsplash, kaya.image-select.unsplash, and image-acquisition bindings; the Rust tool server resolves UNSPLASH_API_KEY from its manifest environment.
• google-images — requires admitted kaya.image-search.google-images and image-acquisition bindings; the Rust tool server resolves SERP_API_KEY from its manifest environment.

Search results are untrusted metadata. Kaya obtains their bytes through the separately granted image-acquisition capability before projecting a file into the program filesystem.

Typesetting

• typst — logical deterministic-typesetting alias with no inherent API key. The host must bind it to an admitted local or remote Typst renderer. See typst().

Testing

Bind a test-only alias to the scripted Rust media provider. It returns deterministic valid PNGs whose bytes vary with prompt, size, count, settings, and ordered input identities, with no network or credential.

Audio models — generateAudio()

For audio, model is a stable deployment alias such as narration or character-voice—not necessarily an upstream model ID. The session ToolMap admits kaya.speech.<alias> (or one explicit default), and the tool-server manifest privately maps that alias to a connector, endpoint, credential, upstream model, voice, and output format. The same Kaya program can therefore use OpenAI directly in one deployment and a compatible proxy in another without changing its source.

The Rust speech provider supports these physical connector families:

Google Gemini text-to-speech bindings

Usually references GEMINI_API_KEY in the tool-server manifest. Gemini speech uses protocol: "gemini_interactions" only; the legacy protocol: "gemini" (generateContent) connector is refused for speech bindings:

Both use the same single-speaker Interactions contract. style controls delivery through speech_metadata.style, actor sets the character label in speech_metadata.speaker and speech_config[0].speaker, and voice accepts a featured name or an opaque ID from Google's extended voice library. Language is detected automatically unless languageCode supplies the upstream speech language hint. WAV is the example default; Kaya also admits PCM for this connector.

See the complete Gemini TTS server/client/job example for both models, emotive delivery, character actor labels, and selecting a real catalog voice. Creating and replicating voices are outside that example. These model and voice details were checked on 2026-10-13 against Google's Flash TTS model page, Flash-Lite TTS model page and Voices API.

OpenAI-compatible text-to-speech bindings

Usually references OPENAI_API_KEY in the manifest and returns MP3. A custom endpoint can provide the same wire contract. Voices are prebuilt names (voice: "alloy", "echo", "nova", …). style maps to OpenAI's upstream instructions field; actor is refused before dispatch. Compatible upstream examples:

• gpt-4o-mini-tts (default), tts-1, tts-1-hd

ElevenLabs text-to-speech bindings

Usually references ELEVENLABS_API_KEY in the manifest and returns MP3. Pass an ElevenLabs voice id as voice. Both style and actor are refused before dispatch. Compatible upstream examples:

• eleven_multilingual_v2 (default), eleven_turbo_v2_5, eleven_flash_v2_5, eleven_v3

Testing

• Bind a logical alias to the scripted Rust media provider. It returns a bounded, playable, prompt-scaled silent WAV with no network or credentials.

See the checked speech/connector example in the kaya-tool-server manifest.

Video models — generateVideo()

Google Veo

Bind a stable logical name in the tool-server manifest to a Gemini connector and Veo upstream model. The manifest also owns the credential environment source and any exact download origins; provider model IDs are not part of the Kaya language contract. Video generation is slow and costly, so results are cached across the resolved binding revision, request settings, and optional reference-image digest.

• Example logical aliases: cinematic-video, portrait-video

Testing

• Bind a logical alias to the scripted Rust media provider. It returns a tiny, playable, prompt-sensitive MP4 with no network, credentials, or installed encoder.

WebAssembly

The public browser runtime's configuration.toolServer uses the original native document format with one unscoped admission. Explicit generation endpoints support the direct OpenAI Responses, OpenAI Chat, Anthropic, Gemini, Vertex and Ollama protocols. Other native generation families are refused; protocol support does not imply that a provider permits browser CORS access. Decisions use their supported native connector/binding format and reviewed decision support.

Use the browser example's Model setup for OpenAI Chat Completions or its advanced native document form for other supported bindings. Configure actual model aliases/defaults and original operation grants. runtime.catalog() reports only admitted operations. A catalog read creates no model request and does not grant further dispatch authority.

Your private secrets map resolves named credentials inside the original Worker. Atomic saved setup can explicitly reload with { saved: true }; an omitted configuration remains empty RAM configuration. The saved getter returns presence only. Keep shared application credentials on your backend; never embed them in frontend code, program input or a downloadable public configuration file.

See WebAssembly Setup and WebAssembly Usage for the current status.