Single source of truth for which model to use for which job, consumed by:
- Koder AI Gateway via the
Aliases map (services/ai/gateway/internal/config/config.go) — clients pass an alias like model: "reasoning" and the gateway resolves to the current pick. Updating the pick is a one-line edit; consumers stay untouched.
- Kode (the agentic Koder AI) and other AI agents — read this file when deciding which backend to invoke for a given task.
- Humans — review on every flagship release; promotedemote alternatives based on `k-bench` results.
How to read: "primary" is what the gateway alias resolves to today. "Alternatives" are equally valid choices with different costqualitylatency trade-offs. "Why not the others" notes why something is not primary, so future revisions are informed rather than impulsive.
1. Reasoning pesado · alias reasoning
| Primary |
anthropic/claude-opus-4-8 |
| Alternatives |
openai/o3, xai/grok-4.20-0309-reasoning, deepseek/deepseek-reasoner, kimi/kimi-k2.6 |
| Why primary |
Best raw reasoning quality for high-stakes architectural decisions, RFC analysis, ambiguous bugs. Worth the cost. |
| Why not OpenAI o3 |
Comparable quality; pick Opus when context > 100K or when you need strong code understanding. o3 wins on math-heavy reasoning. |
| Why not DeepSeek-R1 |
~95% as good in many cases at 120 the cost — promote to primary if `k-bench` gap closes further. |
2. Código (arquitetura/refactor) · alias code-arch
| Primary |
anthropic/claude-opus-4-8 |
| Alternatives |
openai/o3, openai/gpt-5, xai/grok-4.3 |
| Why primary |
Best at multi-file refactors, understanding cross-cutting concerns, suggesting policies. Same model as reasoning — same justification. |
3. Código (boilerplate / fast iteration) · alias code-fast
| Primary |
xai/grok-code-fast-1 |
| Alternatives |
mistral/codestral-latest, deepseek/deepseek-chat, openai/gpt-5-mini |
| Why primary |
Specifically tuned for code; sub-second latency; cheap. Pareto-optimal for "scaffold this CRUD endpoint" or "write 50 unit tests". |
| When to escalate |
Logic gets non-trivial → switch to code-arch. |
4. General-purpose conversational · alias general
| Primary |
openai/gpt-5 |
| Alternatives |
anthropic/claude-sonnet-4-6, xai/grok-4.3, kimi/kimi-k2.6 |
| Why primary |
Strong all-rounder; multimodal native (imagesaudio); best ecosystem of toolsfunction-calling. Defaults that "just work". |
5. Cheap commodity · alias cheap
| Primary |
deepseek/deepseek-chat |
| Alternatives |
google/gemini-2.0-flash, openai/gpt-4o-mini, mistral/mistral-small-latest |
| Why primary |
~$0.14/M input with cache hit — 10× cheaper than gpt-4o-mini, comparable quality on common tasks (classification, summarization, simple Q&A). |
| When to switch to gemini-2.0-flash |
Need free tier (1500 req/day no billing) OR Google ecosystem features (grounding, native search). |
6. Vision / multimodal · alias vision
| Primary |
openai/gpt-4o |
| Alternatives |
anthropic/claude-sonnet-4-6, mistral/pixtral-large-latest, kimi/moonshot-v1-128k-vision-preview |
| Why primary |
Best chart/diagram OCR, screenshot understanding, frame-by-frame video analysis (relevant for Koder Konsul, Koru, dek workflows). |
7. Audio / transcription · alias audio
| Primary |
openai/whisper-1 |
| Alternatives |
koder-ai-voice (local, post-VOICE-52 with CUDA backend) |
| Why primary |
Mature, multilingual, accurate for Brazilian Portuguese. |
| Future |
When VOICE-52 ships, default to local for cost savings (T4 GPU = $0/hour); keep whisper-1 as fallback for high-quality batch jobs. |
7a. Local STT models · deployed at s.khost1:aivoice
Self-hosted speech-to-text models running on the Koder Stack infrastructure (/var/lib/koder-ai-voice/models/). Zero cost per call; privacy-first.
Source: Handy (desktop STT app) + upstream repos (ggerganovwhisper.cpp, NVIDIA NeMo, snakers4silero-vad).
| Model |
Size |
Format |
Use case |
Status |
ggml-tiny.bin |
75 MB |
GGML |
Dev/test, low-latency preview |
deployed |
ggml-base.bin |
142 MB |
GGML |
Lightweight transcription |
deployed |
ggml-small.bin |
466 MB |
GGML |
Balanced quality/speed |
deployed |
ggml-medium.bin |
1.5 GB |
GGML |
Good quality, moderate latency |
deployed |
ggml-large-v3-q5_0.bin |
1.1 GB |
GGML |
Highest whisper quality (quantized) |
deployed 2026-05-27 |
ggml-large-v3-turbo-q5_0.bin |
548 MB |
GGML |
Fast large model (speed-optimized) |
deployed 2026-05-27 |
parakeet-tdt-0.6b-v3-int8 |
640 MB |
ONNX |
CPU-only STT (~5× real-time, no GPU) |
deployed 2026-05-27 |
silero_vad.onnx |
2.3 MB |
ONNX |
Voice activity detection (pre-filter) |
deployed 2026-05-27 |
diarization-segmentation.onnx |
5.8 MB |
ONNX |
Speaker diarization segmentation |
deployed |
diarization-speaker-embedding.onnx |
38 MB |
ONNX |
Speaker embedding extraction |
deployed |
Update cadence: check Handy releases and whisper.cpp models quarterly for new model versions. Parakeet updates from blob.handy.computer. Download to aivoice LXC and update this table.
Integration status: Whisper models active via whisper.cpp worker pool. Parakeet backend integration tracked in VOICE-058. Silero VAD integration tracked in VOICE-058 R3.
8. Embeddings · alias embed
| Primary |
openai/text-embedding-3-large |
| Alternatives |
mistral/mistral-embed, google/embedding-001 |
| Why primary |
3072-dim, well-supported by every vector DB. Mature SDKs. |
9. Image generation · alias image
| Primary |
openai/dall-e-3 |
| Alternatives |
xai/grok-imagine-image, xai/grok-imagine-image-pro, stability/... (when key added) |
| Why primary |
Best instruction-following on text-in-image, branded layouts. |
10. Search-augmented · alias search
| Primary |
xai/grok-3 |
| Alternatives |
perplexity/sonar-pro (when key added) |
| Why primary |
Built-in real-time search, no extra setup. Already paid (xAI auto-reload active). |
| Why not Perplexity yet |
Card declined 2026-05-06 — pending payment fix. When paid, sonar-pro likely takes primary because it's purpose-built for citations. |
11. Long context (>200K tokens) · alias long-context
| Primary |
google/gemini-2.5-pro |
| Alternatives |
anthropic/claude-sonnet-4-6 (~1M ctx), kimi/moonshot-v1-128k |
| Why primary |
~2M token context window; cheapest per token at that scale; still on free tier today. |
12. Local zero-cost · alias local
| Primary |
ollama/qwen2.5:3b |
| Alternatives |
future ollama models pulled on demand |
| Why primary |
Already running on Tesla T4 GPU at ~172 toks. Free per-call. Use for: low-stakes classification, embeddings of bulk data, devstaging defaults. |
Tier shortcuts (legacy — back-compat)
These predate the use-case aliases. Kept so existing code doesn't break.
| Alias |
Resolves to |
Notes |
fast |
anthropic/claude-haiku-4-5-20251001 |
cheap fast Anthropic |
smart |
anthropic/claude-sonnet-4-6 |
balanced Anthropic |
best |
anthropic/claude-opus-4-8 |
flagship Anthropic |
claude |
anthropic/claude-sonnet-4-6 |
"I want Claude" |
Update protocol
When updating this registry, also update the Aliases map in services/ai/gateway/internal/config/config.go in the same commit. The gateway's binary needs a rebuild + redeploy for the alias change to take effect (the model name is still hard-coded there).
Trigger conditions for revision:
- New flagship model from any provider → reassess primary in relevant categories
/k-bench results show alternative beats primary by ≥10% on quality OR is ≥2× cheaper at same quality- A provider deprecates the current primary model
- A new use case emerges that doesn't fit any existing alias
Quarterly review minimum even if no triggers fire.
Future: auto-tuned routing
AIGW-31 (smart-router auto-select) plans to populate this dynamically from nightly /k-bench runs against a task_categories SQLite table (currently missing — see AIGW-38 sub-issue 3). When that lands, this file becomes the fallback / human-readable explanation, with the SQLite table being the runtime source-of-truth.