opencode-llmstack 0.6.0__py3-none-any.whl

llmstack/generators/opencode.py

@@ -0,0 +1,291 @@
+"""Generate ``opencode.json`` from ``models.ini``.
+
+Reads the models.ini located by :func:`llmstack.paths.models_ini_path` and
+writes an opencode config to the path given as the first CLI argument
+(or stdout if omitted).
+
+What gets wired:
+
+  provider              single llama.cpp-compatible provider at router_port
+  model                 ``auto``  (FastAPI router classifies and rewrites
+                                  model names)
+  small_model           tier with ``role=fast``  (tab-complete, titles)
+  agent.build           ``auto``                 -- always routed
+  agent.plan            ``role=plan``            -- read-only, no bash
+  agent.plan-nofilter   ``role=plan-uncensored`` -- read-only, no bash
+  command./review,
+  command./nofilter     shortcuts that the router can't auto-classify
+
+What is **deliberately NOT wired**:
+
+  Sampler params (``temperature``, ``top_p``, etc.) are NEVER emitted on
+  any agent or model in opencode.json. Sampling is the *backend's*
+  responsibility, with ``models.ini`` as the single source of truth:
+
+  * gguf tiers -- :mod:`llmstack.generators.llama_swap` bakes the
+    tier's ``sampler = ...`` into the llama-server startup command line
+    (``--temp``/``--top-p``/...). llama-server applies them as defaults
+    for every request.
+  * Bedrock tiers -- :func:`llmstack.app._inject_sampler` adds the
+    tier's sampler keys to each outbound request body (Bedrock has no
+    server-side defaults mechanism). Bedrock models that reject sampler
+    params (e.g. Claude Opus 4.7) declare an empty ``sampler =`` and
+    the router passes requests through untouched.
+
+  Either way, opencode.json never carries sampler params -- one place to
+  edit (``models.ini``), no risk of opencode drifting from the actual
+  tier config, and any other router client (curl, a different IDE) gets
+  the same per-tier behaviour for free.
+"""
+
+from __future__ import annotations
+
+import configparser
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+from llmstack.paths import AGENTS_TEMPLATE, models_ini_path, remote_url
+
+PROVIDER_KEY = "llama.cpp"
+API_KEY      = "sk-no-key-required"
+
+ROLE_MAP: dict[str, tuple[str, str | None]] = {
+    "fast":            ("small_model", None),
+    "agent":           ("agent",       "build"),
+    "plan":            ("agent",       "plan"),
+    "plan-uncensored": ("agent",       "plan-nofilter"),
+}
+
+READ_ONLY_AGENTS = {"plan", "plan-nofilter"}
+
+# Slash-command shortcuts (no `/fast`: `auto` already routes trivial chat).
+COMMANDS = {
+    "review": {
+        "template":    "Review the following for trade-offs, risks, and follow-ups. Be concrete.",
+        "description": "Architectural review via the planning model.",
+        "agent":       "plan",
+    },
+    "nofilter": {
+        "template":    "[nofilter]",
+        "description": "Route to the uncensored planning model.",
+        "agent":       "plan-nofilter",
+    },
+}
+
+SHARE        = os.getenv("OPENCODE_SHARE", "disabled")
+USERNAME     = os.getenv("OPENCODE_USERNAME") or None
+
+# Keep model picker scoped to the local stack even if hosted-API env vars leak in.
+_REMOTE_PROVIDERS = (
+    "anthropic,openai,google,openrouter,xai,groq,deepseek,"
+    "mistral,cerebras,azure,perplexity,vercel,morph,bedrock"
+)
+DISABLED_PROVIDERS = [
+    p.strip() for p in
+    os.getenv("OPENCODE_DISABLED_PROVIDERS", _REMOTE_PROVIDERS).split(",")
+    if p.strip()
+]
+
+
+def _instructions_paths() -> list[str]:
+    """Resolve the ``instructions`` array in opencode.json.
+
+    Honours ``OPENCODE_INSTRUCTIONS`` (colon-separated) for the per-project
+    install path; falls back to the bundled template inside the package.
+    """
+    raw = os.getenv("OPENCODE_INSTRUCTIONS", str(AGENTS_TEMPLATE))
+    return [p for p in raw.split(":") if p]
+
+
+ZERO_COST = {"input": 0, "output": 0, "cache_read": 0, "cache_write": 0}
+DIGITS    = re.compile(r"\d+")
+
+
+def _int(value: str, default: int) -> int:
+    m = DIGITS.search(value or "")
+    return int(m.group()) if m else default
+
+
+def build_config(
+    ini_path: Path | None = None,
+    *,
+    ini_text: str | None = None,
+    remote: str | None = None,
+) -> dict:
+    """Build the opencode.json dict from ``models.ini``.
+
+    Source of the INI is one of (mutually exclusive):
+
+      * ``ini_text`` -- raw INI content as a string. Used by
+        ``llmstack install --external``: it fetches ``models.ini``
+        straight from the router (``GET /models.ini``) and renders the
+        opencode config without writing the file to disk. Thin clients
+        don't keep a local copy of ``models.ini`` -- they re-fetch it
+        on each ``install``.
+      * ``ini_path`` -- explicit path. Used by callers that have a
+        ``Path`` in hand (``check_models``, tests).
+      * neither -- read from :func:`models_ini_path` (canonical
+        per-project location, the local-mode default).
+
+    ``remote`` overrides the router base URL: when given, opencode is
+    pointed at ``{remote}/v1`` (thin-client / external mode). When
+    ``None``, fall back to :func:`llmstack.paths.remote_url` -- which
+    reads the persisted channel marker first, env var second -- and
+    finally to the local router host/port from ``models.ini``.
+
+    Passing ``remote`` explicitly is what ``llmstack install --external
+    [URL]`` does: it has just *decided* the URL from flags + env and
+    needs the renderer to honour that decision rather than looking
+    again at a possibly-stale marker.
+    """
+    if ini_text is not None and ini_path is not None:
+        raise ValueError("build_config: pass ini_text OR ini_path, not both")
+
+    cfg = configparser.ConfigParser(inline_comment_prefixes=(";",), interpolation=None)
+    if ini_text is not None:
+        cfg.read_string(ini_text)
+    else:
+        path = ini_path or models_ini_path()
+        if not path.exists():
+            raise SystemExit(f"models.ini not found at {path}")
+        cfg.read(path)
+
+    defaults = cfg["DEFAULT"]
+    rurl = remote if remote is not None else remote_url()
+    if rurl:
+        # Client mode: send all traffic to the remote router. Keep the
+        # tier / agent wiring derived from the local models.ini -- the
+        # remote stack is expected to expose the same tier names; tier
+        # ``ctx_size`` is a useful client-side hint (used by opencode
+        # for prompt-packing) regardless of where the actual model
+        # lives. Sampling is the *router's* responsibility (it injects
+        # per-tier defaults from its own models.ini), so it never
+        # appears in opencode.json.
+        base_url = f"{rurl}/v1"
+    else:
+        host     = (defaults.get("host") or "127.0.0.1").strip()
+        port     = (defaults.get("router_port") or "10101").strip()
+        base_url = f"http://{host}:{port}/v1"
+
+    tier_sections = [s for s in cfg.sections() if s != "ROUTING"]
+
+    # `auto` context = MIN across all tiers so opencode never packs a prompt
+    # that overflows the tier the router actually picks.
+    auto_ctx = min(
+        (_int(cfg[s].get("ctx_size", ""), 0) for s in tier_sections),
+        default=8192,
+    ) or 8192
+
+    models: dict[str, dict] = {
+        "auto": {
+            "name":      "Auto (router selects: fast / agent / plan / uncensored)",
+            "limit":     {"context": auto_ctx, "output": 16384},
+            "tool_call": True,
+            "cost":      ZERO_COST,
+        }
+    }
+
+    small_model: str | None = None
+    agents: dict[str, dict] = {}
+
+    for sec in tier_sections:
+        s    = cfg[sec]
+        role = (s.get("role") or "").strip()
+        ctx  = _int(s.get("ctx_size", ""), 8192)
+        desc = (s.get("description") or sec).strip()
+
+        model_entry: dict = {
+            "name":      desc,
+            "limit":     {"context": ctx, "output": 32768 if role == "agent" else 8192},
+            "tool_call": True,
+            "cost":      ZERO_COST,
+        }
+        if role in ("agent", "plan-uncensored"):
+            model_entry["reasoning"] = True
+        models[sec] = model_entry
+
+        kind, agent_name = ROLE_MAP.get(role, (None, None))
+        if kind is None:
+            continue
+
+        model_ref = f"{PROVIDER_KEY}/{sec}"
+        if kind == "small_model":
+            small_model = model_ref
+            continue
+
+        # `build` is always wired to the auto router so escalation to
+        # code-ultra (or fallback to code-fast) happens transparently.
+        if agent_name == "build":
+            agent_model_ref = f"{PROVIDER_KEY}/auto"
+        else:
+            agent_model_ref = model_ref
+
+        # Sampler params are intentionally absent here -- the router
+        # injects per-tier defaults from models.ini at request time
+        # (see :func:`llmstack.app._inject_sampler`). See the module
+        # docstring for the rationale.
+        agent: dict = {"model": agent_model_ref}
+        if agent_name in READ_ONLY_AGENTS:
+            agent["permission"] = {"edit": "deny", "write": "deny", "bash": "deny"}
+        agents[agent_name] = agent  # type: ignore[index]
+
+    out: dict = {
+        "$schema":  "https://opencode.ai/config.json",
+        "share":    SHARE,
+        "autoupdate": "notify",
+    }
+    if USERNAME:
+        out["username"] = USERNAME
+    if DISABLED_PROVIDERS:
+        out["disabled_providers"] = DISABLED_PROVIDERS
+
+    instructions = _instructions_paths()
+    if instructions:
+        out["instructions"] = instructions
+
+    out["provider"] = {
+        PROVIDER_KEY: {
+            "npm":  "@ai-sdk/openai-compatible",
+            "name": "llmstack (local llama-swap + auto router)",
+            "options": {"baseURL": base_url, "apiKey": API_KEY},
+            "models": models,
+        }
+    }
+    out["model"] = f"{PROVIDER_KEY}/auto"
+    if small_model:
+        out["small_model"] = small_model
+    if agents:
+        out["agent"] = {k: agents[k] for k in ("build", "plan", "plan-nofilter") if k in agents}
+    out["command"] = COMMANDS
+    return out
+
+
+def render(*, ini_text: str | None = None, remote: str | None = None) -> str:
+    """Return the full opencode.json text (with trailing newline).
+
+    ``ini_text`` and ``remote`` are forwarded to :func:`build_config`;
+    see there for the resolution order.
+    """
+    return json.dumps(build_config(ini_text=ini_text, remote=remote), indent=2) + "\n"
+
+
+def validate(path: Path) -> None:
+    """Cheap structural sanity check: parses cleanly as JSON."""
+    json.loads(path.read_text())
+
+
+def main(argv: list[str]) -> int:
+    target = argv[1] if len(argv) > 1 else "-"
+    text = render()
+    if target == "-":
+        sys.stdout.write(text)
+    else:
+        Path(target).write_text(text)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

llmstack/models.ini

@@ -0,0 +1,304 @@
+; ----------------------------------------------------------------------------
+; models.ini  -  inventory of models served by llmstack/.
+;
+; Runtime config: llmstack/llama-swap.yaml.
+; opencode bindings: ../opencode.json (model + agent.build/plan/plan-nofilter).
+;
+; SUPPORTED TIERS -- canonical names recognised by the router and the
+; opencode / llama-swap generators. ONLY the names listed below should
+; appear as section headers in this file. Any other section name is
+; parsed but ignored by `model: auto` routing and won't be wired into
+; the generated opencode.json -- it would just be dead config. To grow
+; this set, add the new name here AND update llmstack/app.py +
+; llmstack/tiers.py so the router knows about it.
+;
+;   code-fast        always-resident tiny local coder
+;   code-smart       AGENT mode: heavy local coder, tool calls, multi-file edits
+;   code-ultra       AGENT mode: top-tier hosted coder (Claude Opus on Bedrock)
+;                    - shipped commented-out in the bundled template;
+;                      `llmstack install` auto-uncomments it when the
+;                      `bedrock` extra (boto3) is installed.
+;   plan             PLAN mode: chat-tuned, design discussions
+;   plan-uncensored  PLAN mode (no filter): when the topic requires it
+;
+; Per-tier backends:
+;   gguf     local llama-server (managed by llama-swap). Driven by
+;            hf_repo + hf_file. This is the default; auto-detected
+;            when hf_* keys are present.
+;   bedrock  hosted AWS Bedrock model. Identity-only in this file:
+;              aws_model_id            (required)
+;              aws_model_id_next       (optional upgrade target)
+;              aws_region              (optional; some models are
+;                                       region-pinned)
+;              aws_region_next         (optional)
+;              aws_profile             (named profile in ~/.aws/config
+;                                       or ~/.aws/credentials)
+;              aws_endpoint_url        (optional; VPC endpoint, etc.)
+;            Auto-detected from `aws_model_id`; set `backend = bedrock`
+;            only when you want to override auto-detection.
+;
+;            CREDENTIALS NEVER LIVE HERE. This file is meant to be
+;            committable. Anything boto3 can do via a named profile --
+;            long-term keys, SSO, role chaining via `role_arn` +
+;            `source_profile` in ~/.aws/config, MFA, IMDS -- is
+;            supported transparently. Configure once with:
+;              aws configure --profile <my-profile>
+;            and reference the profile by name from the tier.
+;            Without `aws_profile` set, boto3's default credential
+;            chain applies (env vars, default profile, instance role).
+; ----------------------------------------------------------------------------
+
+[DEFAULT]
+host         = 127.0.0.1
+router_port  = 10101        ; FastAPI auto-router (what opencode hits)
+swap_port    = 10102        ; llama-swap manager UI + raw model endpoints
+n_gpu_layers = 999          ; offload everything to Metal on Apple Silicon
+flash_attn   = on
+jinja        = true
+threads      = -1
+cache_type_k = q8_0
+cache_type_v = q8_0
+
+;------------------------------------------------------------------------------
+; CODER tier
+;------------------------------------------------------------------------------
+
+[code-fast]
+tier         = code
+role         = fast
+hf_repo      = bartowski/Qwen2.5-Coder-3B-Instruct-GGUF
+hf_file      = Qwen2.5-Coder-3B-Instruct-Q5_K_M.gguf
+ctx_size     = 131072       ; native 32k extended via YaRN (factor 4)
+rope_scaling = yarn (scale=4, orig_ctx=32768)
+size_gb      = 2.5
+quant        = Q5_K_M
+status       = downloading      ; queued by `llmstack.sh download`
+opencode_use = small_model + auto-fast tier
+sampler      = temp=0.2, top_p=0.95, top_k=40, min_p=0.05      ; deterministic
+description  = Qwen2.5-Coder 3B - autocomplete / FIM / quick Q&A
+
+[code-smart]
+tier         = code
+role         = agent
+hf_repo      = unsloth/Qwen3-Coder-Next-GGUF
+hf_file      = Qwen3-Coder-Next-Q4_K_M.gguf
+hf_file_next = Qwen3-Coder-Next-UD-Q4_K_XL.gguf
+ctx_size     = 65536
+size_gb      = 45
+size_gb_next = 50
+quant        = Q4_K_M
+quant_next   = UD-Q4_K_XL
+status       = ready (Q4_K_M); UD-Q4_K_XL queued
+opencode_use = agent.build + auto-agent tier
+sampler      = temp=0.5, top_p=0.85, top_k=20, min_p=0.05, rep_pen=1.05  ; balanced agent
+description  = Qwen3-Coder-Next 80B-A3B MoE - heavy coder for agent loops
+
+; Top-tier hosted coder. Shipped disabled because it requires boto3 +
+; AWS Bedrock access. `llmstack install` auto-uncomments the block
+; below (by stripping the leading "; " from each line and dropping
+; the BEGIN/END markers) on first seed iff the `bedrock` extra is
+; installed, i.e. `import boto3` succeeds. On a vanilla install the
+; whole block stays inert -- configparser treats `;`-prefixed lines
+; as comments, so the section is invisible to the tier loader.
+;
+; >>> AUTO-ENABLE-WHEN-BEDROCK-AVAILABLE >>>
+; [code-ultra]
+; tier         = code
+; role         = ultra
+; backend      = bedrock
+; aws_model_id = global.anthropic.claude-opus-4-7   ; global.* cross-region inference profile
+; aws_region   = us-east-1                          ; API anchor region; global.* auto-routes inference cross-region
+; aws_profile = bedrock-prod                        ; uncomment + set your own profile name; falls back to default cred chain otherwise
+; ctx_size     = 200000
+; opencode_use = on-demand top-tier coder for hard agent tasks
+; ; NB: no `sampler =` line. Claude Opus 4.7 explicitly rejects all
+; ;     sampler params (temperature, top_p, top_k) -- per the Bedrock
+; ;     model card, "the recommended migration path is to omit these
+; ;     parameters entirely from your requests". Leaving sampler off
+; ;     makes the router pass requests through untouched.
+; description  = Claude Opus 4.7 on Bedrock - top-tier coder for hard agent tasks
+; <<< AUTO-ENABLE-WHEN-BEDROCK-AVAILABLE <<<
+
+;------------------------------------------------------------------------------
+; CHAT tier
+;------------------------------------------------------------------------------
+
+[plan]
+tier         = chat
+role         = plan
+hf_repo      = Jackrong/Qwopus-GLM-18B-Merged-GGUF
+hf_file      = Qwopus-GLM-18B-Healed-Q4_K_M.gguf
+hf_file_next = Qwopus-GLM-18B-Healed-Q6_K.gguf       ; recommended; Q8_0 also exists (16 GB)
+ctx_size     = 65536        ; conservative 2x doubling (it's a merge, no YaRN)
+size_gb      = 9.2
+size_gb_next = 12.1
+quant        = Q4_K_M
+quant_next   = Q6_K
+status       = ready (Q4_K_M); Q6_K queued
+opencode_use = agent.plan + auto-plan tier
+sampler      = temp=0.7, top_p=0.9, top_k=40, min_p=0.05       ; creative thinking
+description  = Qwopus GLM 18B - planning, design discussions, architecture
+
+[plan-uncensored]
+tier         = chat
+role         = plan-uncensored
+hf_repo      = mradermacher/Mistral-Small-3.2-24B-Instruct-2506-ultra-uncensored-heretic-i1-GGUF
+hf_file      = Mistral-Small-3.2-24B-Instruct-2506-ultra-uncensored-heretic.i1-Q4_K_M.gguf
+hf_file_next = Mistral-Small-3.2-24B-Instruct-2506-ultra-uncensored-heretic.i1-Q6_K.gguf
+ctx_size     = 131072       ; native 128k support, no YaRN required
+size_gb      = 13
+size_gb_next = 20
+quant        = i1-Q4_K_M
+quant_next   = i1-Q6_K
+status       = ready (i1-Q4_K_M); i1-Q6_K queued
+opencode_use = agent.plan-nofilter + auto via [nofilter] trigger
+sampler      = temp=0.85, top_p=0.95, top_k=50, min_p=0.05     ; max exploration
+description  = Mistral-Small 3.2 24B Heretic - no-filter planning
+
+;------------------------------------------------------------------------------
+[ROUTING]
+; STEP-DOWN ladder: start at the top of the fidelity ladder for short
+; conversations, then drop down as context grows. Inverts the classic
+; "escalate-on-size" pattern. Rationale:
+;
+;   * Top-tier hosted models (Claude Opus/Sonnet on Bedrock) are fastest
+;     and most accurate on small inputs, but per-request latency and
+;     $cost scale with input tokens, and long-context behaviour
+;     degrades faster than headline benchmarks suggest.
+;   * code-smart (Qwen3-Coder 80B-A3B) has a 64k window -- best work in
+;     the middle of that range, saturates near the top.
+;   * code-fast (Qwen2.5-Coder 3B + YaRN x4) has a 128k window, is
+;     always-resident (zero load latency), free, and benefits from more
+;     explicit context (small models lean on retrieval rather than
+;     priors).
+;
+; First-match-wins decision tree applied by llmstack/app.py when model="auto":
+;
+;   1. "[nofilter]" / "uncensored:" trigger                       -> plan-uncensored
+;   2. "[ultra]" / "[opus]" / "ultra:" trigger AND code-ultra
+;      tier configured                                            -> code-ultra
+;   3. PLAN signal words AND no code-block / agent verbs / tools
+;      (pure design discussion)                                   -> plan
+;   4. tokens <= high_fidelity_ceiling AND code-ultra configured  -> code-ultra
+;      tokens <= high_fidelity_ceiling AND no code-ultra          -> code-smart
+;   5. tokens <= mid_fidelity_ceiling                             -> code-smart
+;   6. otherwise (long context):
+;        - if tools[] OR turns >= multi_turn (3B tool-calls badly) -> code-smart
+;        - else                                                    -> code-fast
+;
+; The "high-fidelity" rung is gated on availability: when the
+; [code-ultra] section is absent (or fails to load), rules (2) and (4)
+; silently fall back to code-smart instead of routing to a tier that
+; doesn't exist downstream. Override target names with the
+; ROUTER_*_MODEL env vars; numeric thresholds with the env vars
+; ROUTER_HIGH_FIDELITY_CEILING / ROUTER_MID_FIDELITY_CEILING /
+; ROUTER_MULTI_TURN.
+;
+high_fidelity_ceiling = 8000     ; tokens; below this, top-tier model is still cheap+fast
+mid_fidelity_ceiling  = 32000    ; tokens; smart's sweet spot up to here, then step down to fast
+multi_turn            = 6        ; turn count that floors the long-context rung at code-smart
+agent_signal_words    = implement, fix bug, write a function, refactor, edit, patch, debug, run tests, build it
+plan_signal_words     = design, architect, approach, trade-off, should we, how would you, explain why, think through, compare options, brainstorm, root cause
+uncensored_triggers   = [nofilter], [uncensored], [heretic], "uncensored:", "nofilter:" (line start)
+ultra_triggers        = [ultra], [opus], "ultra:", "opus:" (line start)
+
+;------------------------------------------------------------------------------
+; BEDROCK EXAMPLES (commented out -- copy / uncomment to adopt)
+;------------------------------------------------------------------------------
+; To swap one of the local GGUF tiers above for an AWS Bedrock model, COMMENT
+; OUT the existing tier of the same name and uncomment one of these. The router
+; auto-detects backend=bedrock from the presence of `aws_model_id` -- no other
+; flag needed. llama-swap won't load it; the router calls Bedrock directly via
+; boto3 (`pip install 'llmstack[bedrock]'`).
+;
+; Credentials: this file ONLY names a profile. The actual keys / SSO /
+; role chaining live in the standard AWS config files. One-time setup:
+;
+;     aws configure --profile bedrock-prod
+;     # for SSO:    aws configure sso --profile bedrock-prod
+;     # for role chaining, edit ~/.aws/config and add a profile with:
+;     #   role_arn       = arn:aws:iam::123456789012:role/llmstack-bedrock
+;     #   source_profile = bedrock-prod
+;
+; Then reference the profile name from your tier with `aws_profile = ...`.
+; If you omit `aws_profile`, boto3's default chain applies (env vars,
+; default profile, instance role -- whatever boto3 normally finds).
+;
+; SAMPLER NOTE: the `sampler = temp=..., top_p=..., top_k=..., ...`
+; line on each tier is the SINGLE SOURCE OF TRUTH for sampling, but how
+; it gets applied depends on the backend:
+;
+;   * gguf tiers -- the llama-swap generator bakes the sampler keys
+;     into the llama-server startup command line as `--temp`,
+;     `--top-p`, `--top-k`, `--min-p`, `--repeat-penalty` flags.
+;     llama-server then uses those as its defaults for every request.
+;     The router does NOT touch the request body for gguf tiers --
+;     server-side defaults survive across requests cleanly.
+;
+;   * bedrock tiers -- AWS Bedrock has no server-side defaults
+;     mechanism, so the auto-router (llmstack.app) injects the
+;     declared sampler keys into each outbound request body. Only
+;     the Converse-supported subset gets through: `temp` ->
+;     `temperature` and `top_p` -> `topP`. `top_k`, `min_p`,
+;     `rep_pen` are llama.cpp extensions and are silently dropped by
+;     the Bedrock backend; declare only what your Bedrock model
+;     accepts. Caller-supplied values in the request body still win,
+;     so per-call overrides work.
+;
+; opencode.json is sampler-free in both cases by design (the
+; opencode.json generator never emits sampler params on agents).
+;
+; Per-Bedrock-family rules (as of 2026):
+;
+;   * Claude Opus 4.7+ -- rejects all sampler params; OMIT `sampler =`
+;     entirely (the router will then pass requests through untouched).
+;   * Claude Sonnet 4.5 / Haiku 4.5 -- accept `temp` OR `top_p`, never
+;     both; pick one.
+;   * Claude Opus 4.x (4.1, 4.5, 4.6) -- accept `temp` and `top_p`.
+;   * Llama / Titan / Cohere / etc. -- accept `temp` + `top_p`; check
+;     the model card if in doubt.
+;
+; Example A: top-tier coder on Bedrock (us-west-2), default cred chain.
+; Optional `aws_model_id_next` (and optional `aws_region_next`) is the
+; queued upgrade target -- mirrors gguf `hf_file_next`. The router uses
+; it only when `--next` is in effect; permanent promotion is the same
+; as gguf: edit `aws_model_id` and re-run `llmstack install`.
+;
+; [code-smart]
+; tier              = code
+; role              = agent
+; backend           = bedrock
+; aws_model_id      = anthropic.claude-sonnet-4-5-20250929-v1:0
+; aws_region        = us-west-2
+; aws_model_id_next = anthropic.claude-sonnet-5-20260201-v1:0   ; queued
+; aws_region_next   = us-east-1                                  ; (optional) different region for the new model
+; ctx_size          = 200000
+; sampler           = temp=0.5      ; Sonnet 4.5 accepts ONE of temp / top_p; pick `temp` for agent work
+; description       = Claude Sonnet 4.5 on Bedrock - heavy coder for agent loops
+;
+; Example B: planner in a different AWS account, accessed via a named
+; profile that itself uses role-chaining + SSO under ~/.aws/config.
+; (Different tier => different profile name; different account/region.)
+;
+; [plan]
+; tier         = chat
+; role         = plan
+; aws_model_id = us.anthropic.claude-opus-4-1-20250805-v1:0
+; aws_region   = us-east-1
+; aws_profile  = bedrock-planning
+; ctx_size     = 200000
+; sampler      = temp=0.7, top_p=0.9
+; description  = Claude Opus 4.1 on Bedrock - planning, design discussions
+;
+; Example C: large model behind a VPC endpoint.
+;
+; [plan-uncensored]
+; tier             = chat
+; role             = plan-uncensored
+; aws_model_id     = meta.llama3-1-405b-instruct-v1:0
+; aws_region       = us-west-2
+; aws_profile      = bedrock-prod
+; aws_endpoint_url = https://bedrock-runtime.us-west-2.vpce.amazonaws.com
+; ctx_size         = 128000
+; sampler          = temp=0.85, top_p=0.95
+; description      = Llama 3.1 405B on Bedrock - max-exploration planning