cobrust.toml.example

# Example LLM Router configuration.
# Copy to `cobrust.toml` at your project root and customize.
#
# This file documents the *target* shape of the router config.
# Implementation lands at M3 — see `docs/agent/modules/llm-router.md`.

[router]
default_strategy = "quality"
cache_dir = ".cobrust/llm_cache"
ledger_path = ".cobrust/ledger.jsonl"

# ---- Providers ------------------------------------------------------------
# Each provider declares an API kind ("anthropic" | "openai") and a base_url.
# Any OpenAI-compatible endpoint (DeepSeek, vLLM, Together, OpenRouter, ...)
# fits under kind = "openai".

[providers.anthropic_official]
kind = "anthropic"
base_url = "https://api.anthropic.com"
api_key_env = "ANTHROPIC_API_KEY"
models = ["claude-opus-4-7", "claude-sonnet-4-6"]

[providers.openai_official]
kind = "openai"
base_url = "https://api.openai.com/v1"
api_key_env = "OPENAI_API_KEY"
models = ["gpt-5", "gpt-5-mini"]

[providers.deepseek]
kind = "openai"
base_url = "https://api.deepseek.com/v1"
api_key_env = "DEEPSEEK_API_KEY"
models = ["deepseek-v3"]

[providers.local_vllm]
kind = "openai"
base_url = "http://localhost:8000/v1"
api_key_env = "LOCAL_LLM_KEY"
models = ["qwen3-coder-480b"]

# ---- Routing table --------------------------------------------------------
# Each task picks a strategy and an ordered list of preferred provider:model
# pairs. `consensus` requires `n` and combines results per the strategy
# (majority / structured-diff / verifier-judged best-of-N).

[routing.spec_extract]
strategy = "quality"
preferred = ["anthropic_official:claude-opus-4-7"]

[routing.translate]
strategy = "consensus"
n = 2
preferred = [
    "anthropic_official:claude-opus-4-7",
    "deepseek:deepseek-v3",
]

[routing.repair]
strategy = "cost"
preferred = [
    "openai_official:gpt-5-mini",
    "deepseek:deepseek-v3",
]

# ---- User-supplied OpenAI-compatible endpoint (validation harness) -------
# Mirrors `crates/cobrust-llm-router/tests/real_llm_smoke.rs`. The endpoint
# is a private deployment exposed by the user; the API key lives in
# USER_CODEX_API_KEY (never committed). Wire format is OpenAI-compatible:
# POST /chat/completions, Authorization: Bearer <key>.
#
# Validation finding: docs/agent/findings/m5-m7-real-llm-validation.md.

# WARNING: development-only example. The endpoint below is HTTP (no TLS).
# Do NOT use this provider configuration in production —
# `Authorization: Bearer <key>` will go over the wire in plaintext.
# For production, point base_url at an HTTPS endpoint.
[providers.user_codex]
kind = "openai"
base_url = "<user-codex deployment URL>/v1"
api_key_env = "USER_CODEX_API_KEY"
models = ["gpt-5.5"]

# Routing slot used by the smoke harness only. Production tasks
# (`spec_extract`, `translate`, `repair`) keep their existing routing.
[routing.real_llm_smoke]
strategy = "quality"
preferred = ["user_codex:gpt-5.5"]

# ---- M-AI.0 (α Phase 2): cobrust.llm source-level binding ---------------
# ADR-0048 + spike docs/agent/spike/m-ai-0-cobrust-llm-spike.md (705f592)
# expose three flat-fn intrinsics to Cobrust source.
# These are called as prelude functions in user code today — not as
# `cobrust.llm.*` module-path syntax:
#
#   llm_complete(provider, model, prompt) -> str
#   llm_dispatch(task, prompt) -> str
#   llm_stream(provider, model, prompt) -> list[str]
#
# `llm_dispatch` walks user-declared `[routing.<task>]` entries (e.g. the
# existing `spec_extract` / `translate` / `repair` rows above). Sample
# user-defined dispatch routes for the AI-native stdlib:

[routing.summarize_doc]
strategy = "quality"
preferred = ["anthropic_official:claude-opus-4-7"]

[routing.transform_code]
strategy = "consensus"
n = 2
preferred = [
    "anthropic_official:claude-opus-4-7",
    "deepseek:deepseek-v3",
]

# `llm_complete` / `llm_stream` accept a `(provider, model)` pair directly
# (OQ-3 WRAP) — the stdlib synthesizes `[routing.llm_complete_<provider>_<model>]`
# and `[routing.llm_stream_<provider>_<model>]` entries at bundle-init
# time per declared `(provider, model)` pair, so users do NOT write these
# entries by hand. If you want to specialize the strategy for a given
# direct route, override below (manual entries take precedence over the
# synthesized defaults). Example:
#
#   [routing.llm_complete_anthropic_official_claude-opus-4-7]
#   strategy = "latency"
#   preferred = ["anthropic_official:claude-opus-4-7"]
#
#   [routing.llm_stream_anthropic_official_claude-opus-4-7]
#   strategy = "quality"
#   preferred = ["anthropic_official:claude-opus-4-7"]

# ---- M-AI.1 (α Phase 3): cobrust.prompt source-level binding ---------------
# ADR-0048 §M-AI.1 + spike docs/agent/spike/m-ai-1-cobrust-prompt-spike.md
# adds `llm_complete_structured(prompt, schema_json) -> str` which routes
# through `llm_dispatch(task="structured", augmented_prompt)`. Declare the
# `[routing.structured]` entry to activate it. Users pick the model they
# want for structured JSON outputs (e.g. a model with native JSON mode).
#
# If [routing.structured] is absent, `llm_complete_structured` returns ""
# (Decision 7 empty-on-failure mirror of M-AI.0). In user-facing terms:
# missing route/provider setup currently looks like an empty result, not a
# rich runtime diagnostic.

[routing.structured]
strategy = "quality"
preferred = ["anthropic_official:claude-opus-4-7"]
# Alternative: use a model with native JSON mode for more reliable output:
# preferred = ["openai_official:gpt-5"]
# preferred = ["deepseek:deepseek-v3"]

# ---- M-AI.2 (α Phase 4): cobrust.tool source-level binding -----------------
# ADR-0048 §M-AI.2 + spike docs/agent/spike/m-ai-2-cobrust-tool-spike.md
# add `llm_complete_with_tools(prompt, registry_json) -> str` on top of the
# flat-function tool schema/registry helpers. It prompt-augments with the tool
# registry, then calls `llm_dispatch(task="tools", ...)`, so projects using
# tool-assisted flow should declare `[routing.tools]` explicitly.
#
# If [routing.tools] is absent, `llm_complete_with_tools` returns ""
# (same empty-on-failure α convention as M-AI.0/M-AI.1). In other words,
# a setup failure currently shows up as an empty string result.

[routing.tools]
strategy = "quality"
preferred = ["anthropic_official:claude-opus-4-7"]
# Alternative: use the same JSON-strong model family as `[routing.structured]`
# if you want tool-selection and argument formatting to stay aligned.
# preferred = ["openai_official:gpt-5"]
# preferred = ["deepseek:deepseek-v3"]