# API
`kcode-intelligence-router` is an in-process typed router for exact-model
operations. `open(Config)` accepts optional OpenAI and Gemini API keys plus the
Codex catalog cache, constructs all provider clients, and returns an
`Intelligence` handle and the configured primary runtime model.
`Intelligence::for_user` binds mandatory per-user accounting before any
provider call.
The user-bound handle supports provider-neutral agent turns, image creation
and reference-image modification, grounded search, page fetches, ordinary
audio transcription, unstructured or schema-constrained Gemini audio analysis,
media annotation, and tool-free Codex text generation. Requests carry exact
model identifiers. Audio transcription and analysis requests also carry an
optional temperature: omission preserves the Gemini provider default, while a
supplied value must be finite and within `0.0..=2.0`. OpenAI transcription
rejects any supplied temperature before making a provider call. Audio
transcription, analysis, and media-annotation prompts must be nonblank; the
router forwards them unchanged without an arbitrary character or byte ceiling.
The router owns
provider selection, model-metadata discovery, parent/child cancellation,
timeouts, error normalization, and durable usage receipts. Every successful
model operation returns `Accounted<T>`, keeping its ordinary typed value
together with the exact `UsageReceipt` that was durably written. When an
attempted call fails, `Error::receipt` exposes that same canonical receipt;
input validation failures that never reach a provider have none.
Agent turns select Codex, OpenAI, or Gemini from the exact model identifier and
normalize provider input, tool calls, completion text, thread identifiers, and
token usage into the `kcode-codex-runtime-v2` event contract. Buffered OpenAI
and Gemini turns accept at most one tool result before continuing. Callers that
want a complete multi-round agent use `kcode-agent-runtime`; direct model
callers use this router.
`UserIntelligence::generate_image` accepts exactly `gpt-image-2` or
`gemini-3-pro-image`. An empty reference list creates an image; a nonempty list
modifies or uses the supplied image media as references. The returned value
contains the generated bytes, output MIME type, actual model, and normalized
usage when the provider reports it.
Each actual model call writes one JSON receipt containing the user, stable
operation identity and causal parent, operation kind, requested and actual
model, available provider identifiers, and normalized metering. Streaming
agent turns expose their receipt after completion through `AgentTurn::receipt`;
an interrupted caller can explicitly finish unavailable metering through
`AgentTurn::finish_unavailable`. `receipts` and `daily_usage` read the files
directly; daily totals deliberately use a linear scan.
Local document extraction and public-page fetching do not create model usage
receipts because they do not call a model provider.