Skip to main content
Version: MVP

Model providers

4 min readReferenceUpdated 2026-05-22

What you'll find here

The craik.model_provider contract — what it records, the secret boundary, the registry, the provider runtime adapters (OpenAI, Anthropic, Gemini, and OpenAI-compatible local models), the provider-backed runner path, and budget/quota gating.

Design rationale: ADR 0002 · Provider transport and mode families.

What it records​

Stable provider id

Provider name

Provider family

Supported modes

chat · completion · embedding · tool · runner.

Capability declarations

Trust boundary

Non-secret config references

Secret reference names

Budget & quota reference names

Optional runtime path

Docs links

Secret boundary​

References, not values.

Provider metadata must not contain secret-like keys such as API keys, tokens, passwords, credentials, or secrets. Public provider records may name secret references but must not include secret values.

Field
Stores
Notes
config_refs
references
Non-secret configuration names.
secret_ref_names
references
External secret handles.
budget_ref · quota_ref
references
Non-secret budget and quota handles. Never billing credentials.

Registry​

craik.runtime.providers.model_providers.ModelProviderRegistry provides in-memory registration and lookup by stable provider id. Duplicate provider ids are rejected. Missing providers raise a clear lookup error.

Metadata-only.

The registry does not call providers, load credentials, or grant execution authority by itself.

Use the provider commands to inspect configuration and certification without exposing secret values:

craik provider list
craik provider show provider_openai
craik provider certification --provider-id provider_openai

Built-in providers:

Provider
Path
Use for
provider_fixture_local
deterministic
Local workflows and tests.
provider_openai
third-party
OpenAI Responses API-compatible MVP execution.
provider_anthropic
third-party
Anthropic Messages API-compatible MVP execution.
provider_gemini
third-party
Gemini generateContent API-compatible v0.9.0 execution.
provider_local_openai_compatible · provider_local_ollama · provider_local_lm_studio · provider_local_vllm
local
Local OpenAI-compatible chat completions execution through no-secret presets.

OpenAI, Anthropic, and Gemini records use third-party trust boundaries, external secret references, budget and quota references, and runtime adapter paths under craik.runtime.providers.provider_runtime. Default model metadata is non-secret and may be overridden by named configuration references before live use.

Provider config reference​

Provider configuration is reference-only. The registry names the values an operator or deployment must provide, but it does not store those values:

Config surface
Examples
Use
Hosted model
CRAIK_OPENAI_MODEL · CRAIK_ANTHROPIC_MODEL · CRAIK_GEMINI_MODEL
Override the non-secret default model metadata before live use.
Hosted base URL
CRAIK_OPENAI_BASE_URL · CRAIK_ANTHROPIC_BASE_URL · CRAIK_GEMINI_BASE_URL
Override provider API endpoints. Unsafe local URLs are rejected unless the provider explicitly allows local endpoints.
Secret reference
CRAIK_OPENAI_API_KEY · CRAIK_ANTHROPIC_API_KEY · CRAIK_GEMINI_API_KEY
Names an external secret handle. The provider record never stores the raw key.
Local endpoint
LOCAL_OPENAI_COMPATIBLE_BASE_URL
Loopback OpenAI-compatible endpoint for local presets such as Ollama, LM Studio, and vLLM.

Provider runtime​

craik.runtime.providers.provider_runtime defines the provider-neutral request, result, adapter, retry decision, and receipt helpers used by the MVP provider path.

OpenAI adapter

  • System messages → developer messages
  • stream passthrough
  • Function tools with strict JSON schemas
  • Structured output via text.format
  • Normalized usage metadata + tool calls

Anthropic adapter

  • Top-level system instructions
  • User & assistant messages in the message list
  • stream passthrough
  • Client tools with input_schema
  • Structured output as a forced client tool
  • Normalized usage metadata + tool calls

Gemini adapter

  • System instructions via systemInstruction
  • User and model turns via contents
  • Function declarations through Gemini tools
  • Structured output through generationConfig.responseSchema
  • Normalized usage metadata + function calls

Local adapter

  • OpenAI-compatible chat completions payloads
  • Optional marker/no-secret local operation
  • Loopback URLs only when explicitly allowed

Adapters classify retryable API conditions and gate live access behind an explicit live_enabled=true runtime setting. Deterministic tests use fixtures and normalized payloads; they do not contact live providers.

Provider-backed runner path​

craik.runtime.provider_runner connects the provider runtime to the governed single-agent loop.

  1. Build or load the task case file.
  2. Compile a provider-runner prompt from the case file and policy envelope.
  3. Execute the loop through a certified provider id such as provider_openai, provider_anthropic, or provider_gemini.
  4. Record provider receipts for every model step.
  5. Preserve side-effect receipts from the loop.
  6. Persist normalized run outputs.
  7. Create a durable handoff for completed / blocked / failed / interrupted outcomes.

Deterministic by default.

The default provider-backed path certifies Craik handoff, receipt, and output plumbing without contacting live APIs. Live provider transport must be enabled explicitly by future caller configuration.

Budget and quota checks​

craik.runtime.provider_budgets evaluates non-secret provider budget status before routing. Routing is blocked when:

Status belongs to a different provider

Status is explicitly blocked

Remaining budget is zero or below

Remaining quota is zero or below

Allowed decisions preserve provider id, budget ref, quota ref, and remaining budget/quota values for later receipts.

Official docs verified​

Provider assumptions for the runtime were checked against official provider docs:

OpenAI

Responses API · streaming responses · structured outputs · function calling · model docs.

Anthropic

Messages API · streaming messages · tool use · model overview · rate limit docs.

Gemini

generateContent · function calling · structured output · model docs. Verified 2026-05-22.

What's next​

ADR0002 · Provider transport & mode familiesDesign rationale for the family/transport split.GuideProvider routing & sandboxesEnd-to-end routing flow.ReferenceProvider failoverHow fallback rules compose with budgets.