# 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. 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.