# 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, structured Gemini audio inference, 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.
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, operation,
requested and actual model, available provider identifiers, and normalized
metering. `receipts` and `daily_usage` read those 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.