EKOSdocs
Docs / Configuration Build

LLM Providers

Configure Ollama, Anthropic or any OpenAI-compatible host; nothing in the deterministic core needs one.

An LLM is optional and is used only by opt-in or read-side features: ekos ask, SQL semantic naming, document semantics, architecture role classification, [llm-description], [semantics] llm-definitions, ekos check explain, ekos migrate reconstruct, docs generate --prose, and in extensions binary reconstruction, Pentaho translation and lakehouse requirements. The compiler pipeline itself makes no model call unless one of these is turned on; on main, every run log ends with the count.

A [llm] section in a project's ekos.toml turns on SQL semantic naming at ekos recover: one model call per schema file. Leave [llm] out of a project that should compile without one.

[llm]
provider = "ollama"                       # local, no key
model = "llama3:latest"
context-window = 8192                     # sent as num_ctx
[llm]
provider = "anthropic"
model = "…"
api-key-env = "ANTHROPIC_API_KEY"
[llm]
provider = "openai"                        # any OpenAI-compatible Chat Completions host
base-url = "https://opencode.ai/zen/v1"
model = "deepseek-v4-flash"
api-key-env = "OPENCODE_API_KEY"

On main, provider = "zen" reaches OpenCode Zen with one key (OPENCODE_API_KEY by default), choosing the wire format — Messages, Responses or Chat Completions — from the model.

Key Meaning
provider ollama, anthropic, openai or zen
model model name
api-key-env name of the env var holding the key
base-url openai (and zen) only; falls back to OPENAI_BASE_URL
context-window ollama only; falls back to OLLAMA_NUM_CTX, then 8192
max-tokens ceiling for compiler-pass calls; leave unset to let each pass size its budget

Routes per task

[llm]
provider = "ollama"
model = "llama3"
budget-usd = 1.0                 # refuse a metered call that could take one command past $1

[llm.tasks.ask]                  # every field not given is inherited from [llm]
provider = "zen"
model = "claude-haiku-5-5"

fallback = ["<model>", …] lists models tried in order when a route's model answers 429 or 5xx; like every field, a task inherits it from [llm] unless it sets its own.

Tasks: default, sql-naming, doc-semantics, description, semantics, session-capture, ask, architecture, reconstruct, nl-sql, docs-prose, marketing, translate, requirements, xref-triage. Other [llm] keys: prices (per million tokens, overriding the built-in table), prompt-cache, reasoning-effort, allow-data-collection (off: models whose provider may keep or train on input are refused).

ekos llm routes        # each task's provider, models, wire format and price
ekos llm usage --since 2026-10-01   # calls that reached a model: tokens and cost by task and model
ekos llm probe         # one tiny, uncached request per model — this is a model call

The read side: [ai]

[ai] tunes ekos ask: model, max-matches, neighborhood-depth, max-tokens, max-context-chars, source-text-top-k, system-prompt (classic path), reason-system-prompt. Reasoning models spend tokens on hidden reasoning; raise max-tokens (8192 is a good start) if answers truncate.

Cost control

Responses are cached in .ekos/llm-cache/. Steps that make many calls ([llm-description], [document-semantics]) are off by default, show an estimate and ask before spending, and accept --yes for automation. Commands that call a model on request — ekos check explain, ekos migrate reconstruct — refuse a model that is not a local Ollama one without --allow-metered. ekos doctor shows the provider, endpoint and whether the key variable is set; ekos llm usage shows what was actually spent.