opencode-llmstack 0.9.1__py3-none-any.whl → 0.9.3__py3-none-any.whl

llmstack/__init__.py

@@ -16,5 +16,5 @@ organised by concern:
 
 from __future__ import annotations
 
-__version__ = "0.1.0"
+__version__ = "0.9.2"
 __all__ = ["__version__"]

llmstack/app.py

@@ -212,6 +212,7 @@ logging.basicConfig(
 )
 log = logging.getLogger("router")
 
+
 @asynccontextmanager
 async def _lifespan(app: FastAPI):
     global client
@@ -423,7 +424,8 @@ def _filter_response_headers(resp: httpx.Response) -> dict[str, str]:
 
 
 async def _stream_proxy(method: str, path: str, body: bytes, headers: dict[str, str]) -> StreamingResponse:
-    assert client is not None
+    if client is None:
+        raise RuntimeError("HTTP client not initialised — lifespan not started")
     upstream_req = client.build_request(method, path, content=body, headers=headers)
     upstream = await client.send(upstream_req, stream=True)
 
@@ -489,7 +491,8 @@ async def serve_models_ini() -> Response:
 
 @app.get("/v1/models")
 async def list_models() -> JSONResponse:
-    assert client is not None
+    if client is None:
+        raise RuntimeError("HTTP client not initialised — lifespan not started")
     try:
         r = await client.get("/v1/models")
         data = r.json()
@@ -614,9 +617,14 @@ async def _handle_completion(req: Request, path: str) -> Response:
         return await _stream_proxy(req.method, path, raw, headers)
 
     mutated = False
+    est_tokens: int | None = None
     requested = body.get("model")
     if requested in AUTO_ALIASES or requested == "auto":
         chosen, reason = classify(body)
+        est_tokens = _estimate_tokens(
+            body.get("messages") if isinstance(body.get("messages"), list) else None,
+            body.get("prompt") if isinstance(body.get("prompt"), str) else None,
+        )
         body["model"] = chosen
         log.info("auto -> %s (%s) [path=%s]", chosen, reason, path)
         mutated = True
@@ -636,9 +644,13 @@ async def _handle_completion(req: Request, path: str) -> Response:
 
     if tier is not None and tier.is_bedrock:
         from llmstack.backends import bedrock as bedrock_backend
-        return await bedrock_backend.dispatch(req, tier, body)
+        resp = await bedrock_backend.dispatch(req, tier, body)
+    else:
+        resp = await _stream_proxy(req.method, path, raw, headers)
 
-    return await _stream_proxy(req.method, path, raw, headers)
+    if est_tokens is not None:
+        resp.headers["X-LLMStack-Tokens"] = str(est_tokens)
+    return resp
 
 
 @app.post("/v1/chat/completions")

llmstack/backends/bedrock.py

@@ -400,7 +400,7 @@ def _tool_config(tools: list[dict[str, Any]] | None) -> dict[str, Any] | None:
     return {"tools": specs}
 
 
-def _inference_config(body: dict[str, Any]) -> dict[str, Any]:
+def _inference_config(body: dict[str, Any], max_output_tokens: int | None = None) -> dict[str, Any]:
     # We forward only what the Converse `inferenceConfig` schema accepts:
     # `temperature`, `topP`, `maxTokens`, `stopSequences`. Other sampler
     # knobs (`top_k`, `min_p`, `repetition_penalty`) have no Converse-
@@ -415,28 +415,34 @@ def _inference_config(body: dict[str, Any]) -> dict[str, Any]:
     # forward. Configure Bedrock tiers in models.ini accordingly: omit
     # the `sampler =` line for Opus 4.7+, and pick the one allowed knob
     # for Sonnet 4.5 / Haiku 4.5.
-    cfg: dict[str, Any] = {}
+    #
+    # `max_output_tokens` is the per-tier cap from models.ini
+    # (`aws_max_output_tokens`). When set, the client-requested value is
+    # silently clamped to this ceiling -- useful for models like
+    # Llama 3.1 405B whose Bedrock deployment rejects values above 4096.
+    icfg: dict[str, Any] = {}
     if "temperature" in body:
         try:
-            cfg["temperature"] = float(body["temperature"])
+            icfg["temperature"] = float(body["temperature"])
         except (TypeError, ValueError):
             pass
     if "top_p" in body:
         try:
-            cfg["topP"] = float(body["top_p"])
+            icfg["topP"] = float(body["top_p"])
         except (TypeError, ValueError):
             pass
     if "max_tokens" in body or "max_completion_tokens" in body:
         try:
-            cfg["maxTokens"] = int(body.get("max_tokens") or body.get("max_completion_tokens"))
+            requested = int(body.get("max_tokens") or body.get("max_completion_tokens"))
+            icfg["maxTokens"] = min(requested, max_output_tokens) if max_output_tokens else requested
         except (TypeError, ValueError):
             pass
     stop = body.get("stop")
     if isinstance(stop, str):
-        cfg["stopSequences"] = [stop]
+        icfg["stopSequences"] = [stop]
     elif isinstance(stop, list):
-        cfg["stopSequences"] = [s for s in stop if isinstance(s, str)]
-    return cfg
+        icfg["stopSequences"] = [s for s in stop if isinstance(s, str)]
+    return icfg
 
 
 def _build_converse_kwargs(tier: Tier, body: dict[str, Any], cfg: BedrockConfig) -> dict[str, Any]:
@@ -446,7 +452,8 @@ def _build_converse_kwargs(tier: Tier, body: dict[str, Any], cfg: BedrockConfig)
     next), passed in so the caller controls the channel and we don't
     re-read the env mid-call.
     """
-    assert tier.bedrock is not None
+    if tier.bedrock is None:
+        raise TypeError(f"_build_converse_kwargs called on non-bedrock tier {tier.name!r}")
     messages = body.get("messages")
     if not isinstance(messages, list):
         # /v1/completions style: synthesise a single user message
@@ -462,7 +469,7 @@ def _build_converse_kwargs(tier: Tier, body: dict[str, Any], cfg: BedrockConfig)
     if sys_blocks:
         converse_kwargs["system"] = sys_blocks
 
-    inference = _inference_config(body)
+    inference = _inference_config(body, max_output_tokens=cfg.max_output_tokens)
     if inference:
         converse_kwargs["inferenceConfig"] = inference
 
@@ -763,7 +770,8 @@ async def _stream_response(client: Any, tier: Tier, converse_kwargs: dict[str, A
 
 def model_descriptor(tier: Tier) -> dict[str, Any]:
     """Return an OpenAI-style ``/v1/models`` entry for a bedrock tier."""
-    assert tier.bedrock is not None
+    if tier.bedrock is None:
+        raise TypeError(f"model_descriptor called on non-bedrock tier {tier.name!r}")
     use_next = _use_next()
     active = tier.bedrock.resolved(use_next=use_next)
     channel = "next" if (use_next and tier.bedrock.has_next) else "current"

llmstack/commands/start.py

@@ -54,7 +54,6 @@ from llmstack.commands._helpers import (
 from llmstack.generators import render_to
 from llmstack.generators.llama_swap import render as render_yaml
 from llmstack.generators.llama_swap import validate as validate_yaml
-from llmstack.tiers import load_tiers
 from llmstack.paths import (
     DEFAULT_REMOTE_URL,
     ROUTER_PORT,

llmstack/models.ini

@@ -1,8 +1,8 @@
 ; ----------------------------------------------------------------------------
 ; models.ini  -  inventory of models served by llmstack/.
 ;
-; Runtime config: llmstack/llama-swap.yaml.
-; opencode bindings: ../opencode.json (model + agent.build/plan/plan-nofilter).
+; Runtime config: .llmstack/llama-swap.yaml  (written by `llmstack start`).
+; opencode bindings: .llmstack/opencode.json  (written by `llmstack install`).
 ;
 ; SUPPORTED TIERS -- canonical names recognised by the router and the
 ; opencode / llama-swap generators. ONLY the names listed below should
@@ -215,9 +215,10 @@ description  = Mistral-Small 3.2 24B Heretic - no-filter planning
 ; tier         = chat
 ; role         = plan-uncensored
 ; backend      = bedrock
-; aws_model_id = meta.llama3-1-405b-instruct-v1:0
-; aws_region   = us-west-2     ; Llama 405B has no EU deployment; keep on US
-; aws_profile  = bedrock-prod
+; aws_model_id         = meta.llama3-1-405b-instruct-v1:0
+; aws_region           = us-west-2     ; Llama 405B has no EU deployment; keep on US
+; aws_profile          = bedrock-prod
+; aws_max_output_tokens = 4096         ; Llama 3.1 405B Bedrock hard cap
 ; ctx_size     = 128000
 ; sampler      = temp=0.85, top_p=0.95   ; max exploration
 ; description  = Llama 3.1 405B on Bedrock - no-filter planning
@@ -229,10 +230,11 @@ description  = Mistral-Small 3.2 24B Heretic - no-filter planning
 ; tier             = chat
 ; role             = plan-uncensored
 ; backend          = bedrock
-; aws_model_id     = meta.llama3-1-405b-instruct-v1:0
-; aws_region       = us-west-2     ; Llama 405B has no EU deployment
-; aws_profile      = bedrock-prod
-; aws_endpoint_url = https://bedrock-runtime.us-west-2.vpce.amazonaws.com
+; aws_model_id         = meta.llama3-1-405b-instruct-v1:0
+; aws_region           = us-west-2     ; Llama 405B has no EU deployment
+; aws_profile          = bedrock-prod
+; aws_endpoint_url     = https://bedrock-runtime.us-west-2.vpce.amazonaws.com
+; aws_max_output_tokens = 4096         ; Llama 3.1 405B Bedrock hard cap
 ; ctx_size         = 128000
 ; sampler          = temp=0.85, top_p=0.95
 ; description      = Llama 3.1 405B on Bedrock (VPC) - no-filter planning

llmstack/tiers.py

@@ -139,6 +139,7 @@ class BedrockConfig:
     endpoint_url: str | None = None
     model_id_next: str | None = None
     region_next: str | None = None
+    max_output_tokens: int | None = None
 
     @property
     def has_next(self) -> bool:
@@ -298,6 +299,7 @@ def _build_bedrock(section) -> BedrockConfig:
         endpoint_url=_opt(section.get("aws_endpoint_url")),
         model_id_next=_opt(section.get("aws_model_id_next")),
         region_next=_opt(section.get("aws_region_next")),
+        max_output_tokens=_int(section.get("aws_max_output_tokens", "")) or None,
     )
 
 

opencode_llmstack-0.9.3.data/data/CHANGELOG.md

@@ -0,0 +1,117 @@
+# Changelog
+
+All notable changes to `opencode-llmstack` are documented here.
+
+---
+
+## [0.9.2] — 2026-05-11
+
+### Fixed
+- `classify()` now counts only **user-role messages** when evaluating the
+  multi-turn floor (`n_turns`). Previously `len(messages)` counted system
+  prompts, assistant turns, and tool-result messages, causing the floor to
+  fire after just a few real exchanges and permanently blocking `code-fast`
+  routing for the rest of any session.
+- Multi-turn floor threshold raised from **6 → 10** user turns. `code-fast`
+  is now a hosted Bedrock model (Haiku 4.5) that tool-calls reliably, so
+  the old 3B-model rationale no longer applies. Sessions with fewer than 10
+  user turns will now correctly step down to `code-fast` past 32k tokens.
+- Log label corrected: `(tools floor)` → `(user-turns=N>=10 floor)`.
+- `__version__` corrected from `"0.1.0"` to `"0.9.2"`.
+- CI release pipeline now runs lint (`ruff`) + `pytest` across Python
+  3.11/3.12/3.13 before building the wheel. Previously the `test` job was
+  documented in comments but never implemented.
+- Added `LICENSE` (MIT) file to the repository root.
+- README routing table updated: high-fidelity ceiling corrected (8k → 12k),
+  tools-floor condition updated to reflect user-turn counting, `ROUTER_MULTI_TURN`
+  default corrected (6 → 10).
+- UPGRADING.md corrected: `llmstack install` does **not** regenerate
+  `llama-swap.yaml` — that is `llmstack restart`'s job. Three places in the
+  doc had this wrong.
+- README layout tree: repo root label corrected (`opencode/` → `llmstack/`),
+  `models.ini` moved to its correct location inside the package, `shell.py`
+  (deleted) removed, `reload.py` and `LICENSE` added.
+- `iter_downloads` reference in UPGRADING.md corrected to `iter_download_targets`.
+- Bundled `llmstack/models.ini` header comment paths updated from legacy
+  locations to current `.llmstack/` state-dir layout.
+- `assert` statements in production code (`app.py`, `bedrock.py`) replaced
+  with explicit `RuntimeError` / `TypeError` raises so `-O` optimisation
+  does not silently swallow them.
+- `UPGRADING.md` and `LICENSE` added to the sdist via `pyproject.toml`
+  `package-data` / `tool.setuptools` config.
+- `[tool.pytest.ini_options]` added to `pyproject.toml` with `testpaths`
+  and `addopts`.
+- Python 3.14 classifier added to `pyproject.toml`.
+
+### Added
+- `classify()` end-to-end test coverage: step-down ladder (short/mid/long
+  context), multi-turn floor, plan-signal routing, ultra-trigger routing,
+  uncensored-trigger routing, plan ctx-size overflow fall-through.
+- Generator tests: `build_config()` coverage for gguf tiers, bedrock tiers,
+  `use_next`, `small_model` wiring, agent wiring, `auto` ctx derivation.
+- `X-LLMStack-Tokens` response header on every `/v1/chat/completions` and
+  `/v1/completions` response so opencode (and curl) can see the estimated
+  token count the router used to make its routing decision.
+
+---
+
+## [0.9.1] — 2026-05-11
+
+### Fixed
+- `classify()` multi-turn floor: count only `role == "user"` messages
+  (not all messages). This was the primary fix preventing `code-fast`
+  from ever being reached in long sessions.
+- Multi-turn threshold raised 6 → 10 (see 0.9.2 for full rationale).
+- Log label `(tools floor)` corrected to `(user-turns=N>=10 floor)`.
+
+---
+
+## [0.9.0] — 2026-05-08
+
+### Changed
+- Plan tiers now strip `tools` from the request body before dispatch.
+  Previously a plan-routed request carrying a `tools` array would fail
+  on Bedrock (Converse rejects tool configs on non-agent models).
+- Long-context fall-through to `code-fast` is now allowed even when
+  `tools[]` is present in the request body. The tools-presence check
+  was removed from the floor condition; only turn count matters now.
+- `plan` tier ctx-size overflow: when estimated tokens exceed the
+  planner's `ctx_size`, the request falls through to the coding ladder
+  instead of being sent to a planner whose window can't hold it.
+- `HIGH_FIDELITY_CEILING` raised to 12 000 (was 8 000).
+
+---
+
+## [0.8.0] — 2026-05-07
+
+### Changed
+- Fidelity-ceiling overhaul: each ceiling is now exactly half of the
+  corresponding tier's `ctx_size` (the "comfortable headroom" invariant).
+- `code-ultra.ctx_size` set to 24 000 (2× high ceiling of 12 000).
+- `code-smart.ctx_size` set to 64 000 (2× mid ceiling of 32 000).
+- `code-fast.ctx_size` set to 128 000 (YaRN ×4 from native 32k).
+- `HIGH_FIDELITY_CEILING` env var added; overrides the 12 000 default.
+- `MID_FIDELITY_CEILING` env var added; overrides the 32 000 default.
+
+---
+
+## [0.7.3] — 2026-05-06
+
+### Added
+- Per-tier Bedrock alternatives in `models.ini`: every tier now ships a
+  commented-out Bedrock block directly beneath its GGUF block.
+- All Bedrock tiers anchored to `eu-west-3`; `plan-uncensored` pinned to
+  `us-west-2` (Llama 405B has no EU deployment).
+- `aws_model_id_next` / `aws_region_next` support for Bedrock upgrade
+  pre-staging (mirrors gguf `hf_file_next`).
+
+### Fixed
+- `models.ini` comment cleanup: removed stale references to old model names.
+
+---
+
+## [0.7.2] — earlier
+
+### Fixed
+- Soft-fail when `llama-server` binary is missing at startup.
+- PowerShell activation hook: fixed `Invoke-Expression` quoting.

opencode_llmstack-0.9.3.data/data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 llmstack contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opencode_llmstack-0.9.3.data/data/UPGRADING.md

@@ -0,0 +1,602 @@
+# UPGRADING — replacing models with newer / better ones
+
+This stack is built around **swapping individual model files in/out**. There is no
+lock-in to provider, model family, or name — you can replace any tier with any
+other GGUF that fits the role and your hardware budget.
+
+This doc explains:
+
+1. [Why GGUF specifically](#why-gguf)
+2. [Where each model is referenced (single source of truth + IDE wiring)](#where-the-models-live)
+3. [The upgrade workflow](#upgrade-workflow)
+4. [How to judge "holistically better" per tier](#judging-better-per-tier)
+5. [Where to look for candidates](#where-to-find-candidates)
+6. [Worked example](#worked-example-replacing-the-plan-tier)
+7. [After-upgrade housekeeping](#after-upgrade-housekeeping)
+8. [Upgrading the Python toolchain](#upgrading-the-python-toolchain)
+
+---
+
+## Why GGUF
+
+Every model the stack runs **must** be a GGUF (`.gguf`) file because:
+
+- **`llama.cpp` only loads GGUF natively.** The whole stack — `llama-server`,
+  `llama-swap`, the Metal backend on Apple Silicon — is built on llama.cpp.
+- **Self-contained format.** A single `.gguf` includes weights, tokenizer,
+  chat template (Jinja), and metadata. No `transformers`, no separate
+  tokenizer files, no Python deps at runtime.
+- **First-class quantisation.** GGUF is the format quantised models ship in
+  (Q4_K_M, Q5_K_M, Q8_0, i1, UD, …). Quants are how a 24 B model fits in
+  13 GB of RAM with little quality loss.
+- **Instant `-hf` resolution.** `llama-server -hf <repo> -hff <file>.gguf`
+  downloads on demand into the standard HF cache and starts serving — no
+  conversion step, no extra tooling.
+
+If a model you want is **not** published as a GGUF, you have two options:
+
+1. Wait for one of the trusted converters (`bartowski`, `unsloth`,
+   `mradermacher`, `lmstudio-community`, `MaziyarPanahi`, …) to publish one —
+   usually within hours of the original release.
+2. Convert it yourself with `llama.cpp/convert_hf_to_gguf.py` then quantise
+   with `llama-quantize`. Doable but slow and adds maintenance burden — only
+   worth it for niche models.
+
+**Rule of thumb:** if you can't find `<model-name>-GGUF` on HF or via the
+maintainers above, the model is not ready for this stack. Pick another.
+
+## Cache management
+
+There is **one** writer to the model cache: `llama-cli`. Everything reads from
+the same place: `~/.cache/huggingface/hub/`.
+
+```
+~/.cache/huggingface/hub/
+└── models--<owner>--<repo>/
+    ├── blobs/
+    │   ├── <sha>                       ← completed file
+    │   └── <sha>.downloadInProgress    ← llama.cpp's resumable partial
+    ├── refs/main                       ← commit hash
+    └── snapshots/<commit>/
+        └── <filename>.gguf             ← symlink to the blob
+```
+
+Key points:
+
+- **`llama-cli -cl`** lists everything currently complete in the cache.
+- **`llmstack download` uses `llama-cli`** so the cache stays coherent. It
+  accepts `HF_TOKEN` from the environment if you have one.
+- **Do NOT use `huggingface-cli download` or `pip install huggingface_hub`'s
+  `hf_hub_download()`** to write to the same cache — they use a different
+  partial-file convention (`.incomplete` vs `.downloadInProgress`) and
+  cannot resume each other's partials. Completed files are interchangeable;
+  in-flight downloads are not.
+- **Cache-dir override:** all llama.cpp tools accept `-cd <dir>` to point at
+  a different cache. We don't use it; the default is correct.
+- **Cache cleanup:** `llama-cli -cr <repo>:<quant>` removes a single entry,
+  or `rm -rf ~/.cache/huggingface/hub/models--<owner>--<repo>/` removes a
+  whole repo's blobs.
+
+## `-hf` / `-hff` syntax (gotcha)
+
+```
+-hf  <user>/<repo>             repo on HuggingFace
+-hf  <user>/<repo>:<quant>     repo + quant TAG  (e.g. :Q4_K_M, :Q6_K) — auto-resolves a file
+-hff <filename>.gguf           explicit file inside the repo
+```
+
+`-hf <repo>:<full-filename>.gguf` **does not work** — the `:suffix` part is
+parsed as a quant tag, so a full filename ending in `.gguf` is rejected with
+`get_hf_plan: no GGUF files found in repository`. Always pair `-hf <repo>` with
+`-hff <filename>.gguf` for explicit selection. This is what the generated
+`llama-swap.yaml` uses everywhere.
+
+---
+
+## Where the models live
+
+There is exactly **one source of truth** that determines what runs in a
+given project: `.llmstack/models.ini` in the work-dir. Everything else is
+generated from it. The first time you run `llmstack install` in a fresh
+project, this file is auto-seeded from the bundled template at
+`llmstack/models.ini` inside the package; from then on it's per-project.
+
+| File | What it does | Required when changing a model? |
+|---|---|---|
+| **`<work-dir>/.llmstack/models.ini`** | The single source of truth: tier definitions (repo, file, ctx, sampler, role, …). All other artefacts derive from it. Auto-seeded from the bundled template on first `install`; gitignored after that — yours to edit per project. | **Yes — primary edit.** |
+| `llmstack/models.ini` (in the package) | Bundled template, version-controlled, ships with `pip install -e .`. Only consulted as the seed source when a project has no `.llmstack/models.ini` yet. Edit if you want to change the *factory defaults* every new project starts from. | Only when changing factory defaults. |
+| `<work-dir>/.llmstack/llama-swap.yaml` | AUTO-GENERATED by `llmstack.generators.llama_swap`. Determines what `llama-server` actually loads. Regenerated fresh by `llmstack start` (or `llmstack restart`) for the channel you're booting into. Do not regenerate with `llmstack install` — `install` only writes `opencode.json` + `AGENTS.md`. | Auto — don't hand-edit. |
+| `<work-dir>/.llmstack/opencode.json` | AUTO-GENERATED by `llmstack.generators.opencode`. `<work-dir>` is whatever directory the CLI was invoked from — `cd` into any project to get a project-local config. Wires opencode's `model`, `small_model`, and `agent.*` to the right tiers. Loaded by opencode via the `OPENCODE_CONFIG` env var that the activate hook (or `llmstack start`'s fallback subshell) exports — your global `~/.config/opencode/opencode.json` is intentionally left alone. Regenerate via `llmstack install`. | Auto — don't hand-edit. |
+| `<work-dir>/.llmstack/AGENTS.md` | Copy of `llmstack/AGENTS.md` (the bundled template), made by `install`. Loaded by opencode via the `instructions` field of `opencode.json`. Edit the source template to change defaults; edit the `.llmstack/` copy for one-off project tweaks (will be overwritten on next `install`). | Auto — copy of template. |
+| `llmstack download` | Enumerates download targets at runtime via `llmstack.tiers.iter_download_targets` (which reads `models.ini`). | No edits — it reflects `models.ini` automatically. |
+
+`llmstack check` flags any DRIFT between `models.ini` (the recommended file
+per tier) and `llama-swap.yaml` (the file actually configured). If you ever
+see DRIFT, run `llmstack restart` to regenerate the yaml and cycle the stack.
+
+### Where the download list comes from
+
+`llmstack download` does **not** hardcode the (repo, file) tuples. It
+enumerates them at runtime by reading `.llmstack/models.ini` (via
+`llmstack.tiers`), yielding one row per `(tier, label)` where `label` is
+`current` (the active `hf_file`) or `next` (the queued `hf_file_next`).
+
+To add a new file to the download set, edit the matching tier in
+`models.ini`. To stop pre-fetching an upgrade target, blank out its
+`hf_file_next` line. No edits to Python code needed.
+
+### Trying the queued upgrade without committing to it
+
+Once an `hf_file_next` finishes downloading you can run the whole stack
+against the **next** file for every tier that has one, without touching
+`models.ini` permanently:
+
+```bash
+llmstack stop
+llmstack start --next
+llmstack status           # shows "channel: next" + per-tier swap list
+```
+
+Under the hood, `start --next` calls
+`llmstack.generators.llama_swap.render(use_next=True)` and writes the
+result to the same `<work-dir>/.llmstack/llama-swap.yaml` (with a header
+banner reminding you it's the next-channel build), then points llama-swap
+at it. Tiers with no `hf_file_next` are unchanged. To revert, `llmstack
+stop && llmstack start` (no `--next`) regenerates the canonical yaml.
+To make the upgrade permanent, swap `hf_file_next` into `hf_file` in
+`models.ini` and re-run `llmstack install`.
+
+### Anchors to find on each upgrade
+
+Inside `<work-dir>/.llmstack/llama-swap.yaml`, each tier has a clearly-marked
+model block:
+
+```yaml
+models:
+  code-fast:                     # ← tier alias (do not rename without updating opencode.json)
+    cmd: |
+      ${llama_server} ${metal_defaults}
+      # >>> UPGRADE-POINT (code-fast): swap the -hf/-hff pair below to change this tier.
+      -hf  bartowski/Qwen2.5-Coder-3B-Instruct-GGUF        # <-- REPLACE: HF repo
+      -hff Qwen2.5-Coder-3B-Instruct-Q5_K_M.gguf           # <-- REPLACE: filename in that repo
+      --alias code-fast
+      -c 131072
+      ...
+```
+
+But don't edit the YAML — it's regenerated. Find the same lines in
+`.llmstack/models.ini` (search for the tier name, e.g. `[code-fast]`) and
+edit `hf_repo` / `hf_file` there. Then re-run `llmstack install`.
+
+The download list comes from the same ini file: the four tiers map 1:1 to
+four download jobs, each with `(repo, current-file, next-file?)`.
+
+---
+
+## Upgrade workflow
+
+Apply this **per tier**, not all at once. Test one model at a time so you
+can roll back cleanly.
+
+```
+0. (Optional, fast) llmstack check
+   → prints current model + repo + last-modified + HF URL for each tier
+
+1. Identify a candidate.
+   - Hugging Face search:  https://huggingface.co/models?search=<keywords>+GGUF&sort=trending
+   - Filter:               GGUF format, last 30 days, downloads > 1k
+   - Cross-check:          a leaderboard appropriate to the tier (see below)
+
+2. Verify the candidate is suitable for the tier.
+   - GGUF available?              must exist as a .gguf file
+   - Size in budget?              see "tier sizes" table below
+   - Chat template embedded?      open the GGUF page → "Use this model" → llama.cpp tab.
+                                   If --jinja is mentioned or chat_template metadata
+                                   is shown, you're fine.
+   - Tool calls supported?        only matters for code-smart. Check that the model
+                                   page lists "function calling" or its chat template
+                                   handles tool-call blocks.
+   - Native context length?       must be ≥ what you set with -c, or have YaRN config.
+
+3. Smoke-test it before wiring it in. First, prefetch + validate via llama-cli:
+
+       llama-cli -hf <new-repo> -hff <new-file>.gguf \
+                 --no-warmup -ngl 0 -c 256 -p ok -n 1
+
+       # then bring up llama-server on a throwaway port to test inference:
+       llama-server -hf <new-repo> -hff <new-file>.gguf \
+                    --port 9999 -ngl 999 -fa on --jinja \
+                    --cache-type-k q8_0 --cache-type-v q8_0 -c 32768
+
+       # in another terminal:
+       curl -sN http://127.0.0.1:9999/v1/chat/completions \
+            -H 'Content-Type: application/json' \
+            -d '{"model":"x","messages":[{"role":"user","content":"hello"}]}'
+
+   Confirm:
+     - it loads without errors                     (look for "main: model loaded")
+     - it streams a sensible response
+     - it accepts your typical request shape       (tools, long context, …)
+
+4. Edit ONE file: `.llmstack/models.ini`. In the matching `[tier]` section,
+   update:
+
+       hf_repo      = <new-repo>
+       hf_file      = <new-file>.gguf
+       ctx_size     = <new-context>     ; only if changing
+       sampler      = temp=..., top_p=..., ...   ; only if changing
+       size_gb, quant, status            ; for documentation accuracy
+
+   No other files need editing — `llama-swap.yaml`, `opencode.json`, and
+   the download list are all auto-derived from this.
+
+5. Regenerate everything from the ini:
+
+       llmstack install     # rewrites opencode.json + AGENTS.md
+       llmstack download    # picks up the new (repo, file) pair from models.ini
+
+6. Cycle the stack:
+
+       llmstack stop
+       llmstack start
+       llmstack status
+       curl -s http://127.0.0.1:10101/v1/models | jq '.data[].id'
+
+7. Sanity-check via opencode (or curl) — fire a few characteristic prompts at
+   the upgraded tier. If the new model misbehaves, the rollback is just a
+   one-line revert in models.ini + `llmstack install` + `llmstack restart`.
+```
+
+---
+
+## Judging "better" per tier
+
+A model that scores +5 % on MMLU is not automatically better for *your*
+workflow. Score against the role the tier plays.
+
+### `code-fast` — autocomplete / FIM / quick Q&A
+
+What matters:
+- **Tokens/sec on M4 Max** (must clear ~60 tok/s for tab-feel responsiveness)
+- **FIM (fill-in-the-middle) support** — the chat template must include a FIM
+  format, and the model must be trained for it
+- **Tool calling** — *not* required, this tier never calls tools
+
+How to evaluate:
+- Run `llama-bench -m <new>.gguf -p 512 -n 128 -ngl 999` for raw speed
+- Sniff test with a typical autocomplete prompt; latency should feel like
+  the cursor is barely ahead of you
+- Aider leaderboard "edit format" column — proxy for FIM quality
+
+Size budget: **~2–6 GB** weights (we want this resident permanently while
+sharing memory with the heavy tier).
+
+Good candidates to track:
+- `bartowski/Qwen2.5-Coder-*-Instruct-GGUF` (any of 3B/7B)
+- `bartowski/DeepSeek-Coder-V2-Lite-Instruct-GGUF`
+- `unsloth/Qwen3-Coder-*-GGUF` (smaller variants)
+- Any new "tab" / "FIM" coder ≤ 7B that drops
+
+### `code-smart` — agent: tool calls, multi-file edits, refactors
+
+What matters:
+- **Tool / function-calling correctness** (the model must reliably emit
+  well-formed tool-call blocks)
+- **Long-context recall** (≥ 64 k usable, ideally 128 k+)
+- **Code editing benchmarks** (aider edit success, SWE-Bench Verified)
+- **Speed at full context** (MoE models win here on Apple Silicon)
+
+How to evaluate:
+- Aider's [LLM Leaderboard](https://aider.chat/docs/leaderboards/) — most
+  honest signal for agentic coding
+- LiveCodeBench scores
+- SWE-Bench Verified (the "real PRs" benchmark)
+- Run an actual opencode session in `build` mode against your repo
+
+Size budget: **~30–55 GB** weights (must fit alongside `code-fast` ≈ 5 GB
+in your wired-mem cap).
+
+Good candidates to track:
+- `unsloth/Qwen3-Coder-*-GGUF` (incl. the Next 80B-A3B you have)
+- `bartowski/DeepSeek-Coder-V*-Instruct-GGUF`
+- `bartowski/Codestral-*-GGUF` future versions
+- New "Coder" or "Devstral" releases as they appear
+
+### `plan` — design discussions, architecture, trade-offs
+
+What matters:
+- **Reasoning quality** (MMLU-Pro, GPQA-Diamond)
+- **Instruction-following on multi-step prompts** (IFEval)
+- **Discussion style** — should propose alternatives, not jump to code
+- **Refusals on edge cases** — fine to refuse weird stuff in plain plan mode
+
+How to evaluate:
+- Open LLM Leaderboard (filter to chat/instruct, your size class)
+- Chatbot Arena — vibes-based but useful proxy
+- Hand-roll a "design this rate limiter" prompt and compare outputs
+
+Size budget: **~7–25 GB** weights — this tier shouldn't dominate memory.
+
+Good candidates to track:
+- `bartowski/Qwen3-*-Instruct-GGUF`
+- `bartowski/Mistral-Small-*-Instruct-GGUF` (non-uncensored)
+- `bartowski/gemma-*-it-GGUF`
+- `bartowski/glm-*-chat-GGUF`
+- Reasoning-tuned variants: QwQ, DeepSeek-R1-Distill, Qwen3-Thinking
+
+### `plan-uncensored` — no-filter planning
+
+What matters:
+- Same metrics as `plan`
+- **Plus** demonstrably reduced refusal rate (look for "abliterated",
+  "uncensored", "heretic", "dolphin", "neural-chat" branding)
+
+Good candidates to track:
+- `mradermacher/<base-model>-uncensored-*-GGUF`
+- `mradermacher/<base-model>-heretic-i1-GGUF`
+- `bartowski/<base-model>-abliterated-*-GGUF`
+- `cognitivecomputations/dolphin-*` (then look for GGUF re-uploads)
+
+Same size budget as `plan`.
+
+---
+
+## Where to find candidates
+
+**HuggingFace search** (fastest):
+
+- All recent GGUFs sorted by trending:
+  https://huggingface.co/models?library=gguf&sort=trending
+- New coder GGUFs in the last 30 days:
+  https://huggingface.co/models?other=code&library=gguf&sort=created
+- Specific maintainer feeds (subscribe / bookmark):
+  - https://huggingface.co/bartowski (broad coverage, fast turnaround)
+  - https://huggingface.co/unsloth (Qwen, Llama, with Dynamic UD quants)
+  - https://huggingface.co/mradermacher (i1 / abliterated / heretic variants)
+  - https://huggingface.co/lmstudio-community (curated, conservative quants)
+  - https://huggingface.co/MaziyarPanahi (broad chat + coder)
+
+**Leaderboards** (signal):
+
+| Tier | Leaderboard |
+|---|---|
+| `code-fast` / `code-smart` | https://aider.chat/docs/leaderboards/ |
+|                            | https://livecodebench.github.io/leaderboard.html |
+|                            | https://www.swebench.com/ (Verified split) |
+| `plan` / `plan-uncensored` | https://huggingface.co/spaces/open-llm-leaderboard/open_llm_leaderboard |
+|                            | https://lmarena.ai/ |
+|                            | https://livebench.ai/ |
+
+**Community signal** (qualitative but valuable):
+
+- r/LocalLLaMA — daily threads on what's good
+- HF model card discussions — real-world report-backs
+- Each maintainer's repo READMEs often link to benchmarks they ran themselves
+
+---
+
+## Worked example: replacing the `plan` tier
+
+Suppose tomorrow `bartowski` ships `Qwen3-Next-32B-Thinking-GGUF` and you
+think it'd plan better than your current Qwopus GLM 18B.
+
+```bash
+# 0. Snapshot the current configuration
+cd ~/Projects/opencode
+llmstack check > /tmp/before.txt
+
+# 1. Pre-pull via llama-cli (writes to the standard cache)
+llama-cli -hf bartowski/Qwen3-Next-32B-Thinking-GGUF \
+          -hff Qwen3-Next-32B-Thinking-Q5_K_M.gguf \
+          --no-warmup -ngl 0 -c 256 -p ok -n 1
+
+# 2. Smoke-test inference on a throwaway port
+llama-server -hf bartowski/Qwen3-Next-32B-Thinking-GGUF \
+             -hff Qwen3-Next-32B-Thinking-Q5_K_M.gguf \
+             --port 9999 -ngl 999 -fa on --jinja \
+             --cache-type-k q8_0 --cache-type-v q8_0 -c 65536 &
+
+curl -sN http://127.0.0.1:9999/v1/chat/completions \
+     -H 'Content-Type: application/json' \
+     -d '{"model":"x","messages":[{"role":"user","content":"How would you architect a rate limiter for our API?"}]}'
+
+kill %1   # stop the test server
+
+# 3. Edit ONE file: .llmstack/models.ini  -> the [plan] section.
+#      OLD:
+#        hf_repo = Jackrong/Qwopus-GLM-18B-Merged-GGUF
+#        hf_file = Qwopus-GLM-18B-Healed-Q4_K_M.gguf
+#      NEW:
+#        hf_repo = bartowski/Qwen3-Next-32B-Thinking-GGUF
+#        hf_file = Qwen3-Next-32B-Thinking-Q5_K_M.gguf
+#      Also bump size_gb / quant for documentation accuracy.
+
+# 4. Apply: regenerate llama-swap.yaml + opencode.json, restart, verify.
+llmstack install
+llmstack restart
+llmstack status
+llmstack check          # confirms no DRIFT vs models.ini
+```
+
+Roll back? Revert the two lines in `.llmstack/models.ini` and re-run
+`llmstack install && llmstack restart`. The old GGUF is still in the HF
+cache so loading it costs nothing extra.
+
+---
+
+## After-upgrade housekeeping
+
+When you're confident in the new model, reclaim disk space:
+
+```bash
+# What does llama.cpp see in its cache?
+llama-cli -cl
+
+# Sizes on disk (sorted)
+du -h ~/.cache/huggingface/hub/* | sort -h
+
+# Drop a single quant
+llama-cli -cr <user>/<repo>:<quant>          # e.g. -cr unsloth/Qwen3-Coder-Next-GGUF:Q4_K_M
+
+# Drop a whole repo
+rm -rf ~/.cache/huggingface/hub/models--<owner>--<repo>/
+```
+
+The old `Q4_K_M` for a tier you've upgraded is also a candidate for deletion
+once the new quant is verified working.
+
+---
+
+## Upgrading the Python toolchain
+
+The stack is a single Python package (`llmstack`) installed via
+`pyproject.toml`. The runtime needs:
+
+- `llmstack/app.py` — `fastapi`, `uvicorn[standard]`, `httpx` (router)
+- `llmstack/check_models.py` — `huggingface_hub`, `PyYAML`
+- `llmstack/tiers.py`, `llmstack/generators/*.py` — stdlib only
+
+`hf_transfer` is a declared dep and gets used automatically when
+`HF_HUB_ENABLE_HF_TRANSFER=1` is set, for faster multi-GB GGUF pulls.
+
+Dependency versions live in `pyproject.toml`'s `[project.dependencies]`,
+not in a `requirements.txt`. There is no checked-in venv either.
+
+### First-time setup
+
+The cleanest install puts the CLI on your PATH in an isolated env:
+
+```bash
+cd ~/Projects/opencode
+pipx install -e .            # editable install + isolated venv
+llmstack --version
+```
+
+Or, if you prefer a managed venv (no pipx):
+
+```bash
+cd ~/Projects/opencode
+python3 -m venv .venv
+.venv/bin/pip install -e .
+.venv/bin/llmstack --version
+```
+
+Pin a specific Python (e.g. 3.13) by passing `python3.13 -m venv .venv` or
+`pipx install --python python3.13 -e .`. Anything ≥ 3.11 works (we use
+3.11+ syntax: PEP 604 `X | None`, `list[Tier]`, etc.).
+
+### Routine upgrade (latest patch versions of declared deps)
+
+```bash
+cd ~/Projects/opencode
+pipx upgrade llmstack             # if installed via pipx
+# or, in your venv:
+.venv/bin/pip install -U -e .
+
+llmstack stop && llmstack start   # bounce the router
+llmstack check                    # smoke-test PyYAML + huggingface_hub
+```
+
+### Bumping a major version (e.g. fastapi 0 → 1)
+
+1. Edit the version constraint in `pyproject.toml`'s
+   `[project.dependencies]` (e.g. `"fastapi>=1.0,<2.0"`).
+2. Reinstall: `pipx upgrade llmstack` or `.venv/bin/pip install -U -e .`.
+3. Test the router:
+
+       llmstack stop && llmstack start
+       curl -s http://127.0.0.1:10101/v1/models | jq '.data[].id'
+       curl -s http://127.0.0.1:10101/models.ini | head
+       curl -sN http://127.0.0.1:10101/v1/chat/completions -H 'Content-Type: application/json' \
+            -d '{"model":"auto","messages":[{"role":"user","content":"hi"}]}'
+
+4. Read the upstream changelog for any breaking imports the router relies
+   on (`fastapi.FastAPI`, `Request`, `Response`, `JSONResponse`,
+   `StreamingResponse`, lifespan handlers, etc.). Update `llmstack/app.py`
+   to match if needed.
+
+### Rebuilding the install from scratch
+
+If anything gets weird (corrupt install, Python upgrade, dependency
+conflicts), nuke and reinstall — it's cheap:
+
+```bash
+# pipx install:
+pipx uninstall llmstack
+pipx install -e ~/Projects/opencode
+
+# venv install:
+cd ~/Projects/opencode
+rm -rf .venv
+python3 -m venv .venv
+.venv/bin/pip install -e .
+```
+
+Nothing in the venv / pipx env is editable — all source lives under
+`llmstack/` in the repo and is installed in editable mode (`-e`), so edits
+land instantly.
+
+### Upgrading the llama-swap binary
+
+The binary lives at `$LLMSTACK_BIN_DIR/llama-swap`, which defaults to
+`$XDG_DATA_HOME/llmstack/bin/llama-swap` (i.e.
+`~/.local/share/llmstack/bin/llama-swap` on macOS). It is **not** in
+version control — `llmstack setup` downloads it as part of the first-time
+walkthrough, and `llmstack install-llama-swap` lets you re-fetch it on
+demand.
+
+```bash
+llmstack install-llama-swap           # latest, idempotent (no-op if up-to-date)
+llmstack install-llama-swap --force   # redownload even if up-to-date
+LLAMA_SWAP_VERSION=v211 \
+  llmstack install-llama-swap         # pin a specific tag
+```
+
+It auto-detects OS (Darwin / Linux / FreeBSD) and arch (arm64 / amd64) and
+downloads the matching tarball from
+https://github.com/mostlygeek/llama-swap/releases.
+
+To check what's installed, look at the version line printed by
+`llmstack install-llama-swap` (or run the binary directly):
+
+```bash
+"$(llmstack status 2>/dev/null | awk '/llama-swap binary/ {print $NF}')" --version
+# or simply:
+~/.local/share/llmstack/bin/llama-swap --version
+```
+
+After bumping the binary, re-run `llmstack install` only if the new
+version of llama-swap requires a config-schema change (it usually doesn't —
+the YAML schema is stable).
+
+### Snapshotting the exact installed set
+
+For reproducibility (e.g. before a risky upgrade) capture the full lock:
+
+```bash
+# pipx:
+pipx runpip llmstack freeze > requirements.lock.txt
+
+# venv:
+.venv/bin/pip freeze > requirements.lock.txt
+
+# …upgrade…
+# if it goes wrong:
+.venv/bin/pip install -r requirements.lock.txt
+```
+
+We don't commit `requirements.lock.txt` by default — the floor pins in
+`pyproject.toml` are sufficient for this stack's blast radius.
+
+---
+
+## Quick reference — tier sizes & natural model classes
+
+| Tier | Weights budget | Typical params (dense) | Typical params (MoE) | Examples |
+|---|---|---|---|---|
+| `code-fast` | 2–6 GB | 1.5–7 B | — | Qwen2.5-Coder 3B/7B, DeepSeek-Coder-V2-Lite |
+| `code-smart` | 25–55 GB | 30–70 B | 30B-A3B / 80B-A3B | Qwen3-Coder-Next, DeepSeek-Coder-V2, Codestral |
+| `plan` | 7–25 GB | 14–32 B | — | Qwen3, Mistral-Small, Gemma-3, GLM |
+| `plan-uncensored` | 7–25 GB | 14–32 B | — | abliterated/heretic/dolphin variants of the above |
+
+Anything outside these brackets either won't fit, or wastes hardware.

{opencode_llmstack-0.9.1.dist-info → opencode_llmstack-0.9.3.dist-info}/METADATA

@@ -1,9 +1,30 @@
 Metadata-Version: 2.4
 Name: opencode-llmstack
-Version: 0.9.1
+Version: 0.9.3
 Summary: Multi-tier local LLM stack: llama-swap + FastAPI auto-router + opencode wiring.
 Author: llmstack
-License: MIT
+License: MIT License
+        
+        Copyright (c) 2024 llmstack contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
 Project-URL: Homepage, https://github.com/rohitgarg19/llmstack
 Project-URL: Issues, https://github.com/rohitgarg19/llmstack/issues
 Keywords: llm,llama-cpp,llama-swap,opencode,router,local-ai
@@ -17,9 +38,11 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: fastapi<1.0,>=0.110
 Requires-Dist: httpx<1.0,>=0.27
 Requires-Dist: uvicorn[standard]<1.0,>=0.30
@@ -32,6 +55,7 @@ Requires-Dist: pytest>=7; extra == "dev"
 Provides-Extra: bedrock
 Requires-Dist: boto3>=1.35; extra == "bedrock"
 Requires-Dist: botocore>=1.35; extra == "bedrock"
+Dynamic: license-file
 
 # llmstack — multi-tier local LLM stack for Mac M4 Max / 64 GB
 
@@ -118,9 +142,9 @@ First match wins:
 | 1 | last user msg contains `[nofilter]`, `[uncensored]`, `[heretic]`, or starts with `uncensored:` / `nofilter:` | `plan-uncensored` | explicit opt-in |
 | 2 | `[ultra]` / `[opus]` / `ultra:` trigger AND `code-ultra` tier configured | `code-ultra` | explicit top-tier opt-in |
 | 3 | plan verbs (*design, architect, approach, trade-off, should we, explain why, …*) AND no code blocks / agent verbs / tools | `plan` | pure design discussion (orthogonal track) |
-| 4 | estimated input ≤ 8 000 tokens | `code-ultra` *(or `code-smart` if ultra unwired)* | top tier — context still being built, latency/$ are best here |
+| 4 | estimated input ≤ 12 000 tokens | `code-ultra` *(or `code-smart` if ultra unwired)* | top tier — context still being built, latency/$ are best here |
 | 5 | estimated input ≤ 32 000 tokens | `code-smart` | mid-context, local heavy coder is at its sweet spot |
-| 6 | otherwise (long context) AND (`tools[]` OR ≥ 6 turns) | `code-smart` | floor: 3B model tool-calls unreliably |
+| 6 | otherwise (long context) AND ≥ 10 user turns | `code-smart` | floor: deep agentic loop, keep the heavy model |
 | 7 | otherwise (long context) | `code-fast` | 128k YaRN window + always-resident + free |
 
 Token estimates are `chars / 4` over all message text + `prompt`. The
@@ -185,12 +209,12 @@ from any directory you previously ran `install` in.
 ## Layout
 
 ```
-opencode/                       # repo root
+llmstack/                       # repo root
 ├── pyproject.toml              # package metadata + `llmstack` console script
 ├── README.md                   # this file
 ├── UPGRADING.md                # how to swap any tier for a newer/better model
 │                                  + how to upgrade the Python toolchain itself
-├── models.ini                  # SINGLE SOURCE OF TRUTH for tiers + sampler
+├── LICENSE                     # MIT
 └── llmstack/                   # the python package (importable, installable)
     ├── __init__.py
     ├── __main__.py             # `python -m llmstack`
@@ -199,6 +223,7 @@ opencode/                       # repo root
     ├── shell_env.py            # spawn the env-prepared subshell + activate hooks
     ├── app.py                  # FastAPI auto-router (~280 lines)
     ├── tiers.py                # parse models.ini -> Tier dataclasses
+    ├── models.ini              # SINGLE SOURCE OF TRUTH for tiers + sampler (bundled template)
     ├── check_models.py         # snapshot tool (HF metadata + drift check)
     ├── AGENTS.md               # opencode agent template (shipped as package data)
     ├── generators/
@@ -213,9 +238,9 @@ opencode/                       # repo root
         ├── install_llama_swap.py
         ├── download.py
         ├── start.py
-        ├── shell.py
         ├── stop.py
         ├── restart.py
+        ├── reload.py
         ├── status.py
         ├── check.py
         └── activate.py
@@ -544,7 +569,7 @@ All knobs are env vars; defaults are picked up by `llmstack start`.
 | `ROUTER_UNCENSORED_MODEL` | `plan-uncensored` | `[nofilter]` triggers → here |
 | `ROUTER_HIGH_FIDELITY_CEILING` | `12000` | tokens; at or below this, route to top tier (ultra → smart fallback). Paired with `code-ultra.ctx_size = 24000` (2x). |
 | `ROUTER_MID_FIDELITY_CEILING` | `32000` | tokens; at or below this, route to `code-smart`; beyond, step down to `code-fast`. Paired with `code-smart.ctx_size = 64000` (2x). |
-| `ROUTER_MULTI_TURN` | `6` | turn count that floors the long-context rung at `code-smart` |
+| `ROUTER_MULTI_TURN` | `10` | user-turn count that floors the long-context rung at `code-smart` |
 | `ROUTER_HOST` / `ROUTER_PORT` | `127.0.0.1` / `10101` | listen address |
 | `LOG_LEVEL` | `info` | router log level |
 

{opencode_llmstack-0.9.1.dist-info → opencode_llmstack-0.9.3.dist-info}/RECORD

@@ -1,16 +1,16 @@
 llmstack/AGENTS.md,sha256=4DVUkqJ1-EP-cDNRCpznzghOOX6dAMbVWdcwyfFCALw,528
-llmstack/__init__.py,sha256=EKHybZtPxLqFWkgkIoYBameu5_Tf9j4UewpANKm0fMU,855
+llmstack/__init__.py,sha256=Qs9d58V8cJWmJvu4QLvO7_panKa8UkGRXAurHYgKDyU,855
 llmstack/__main__.py,sha256=wXHd5-BmCCHUfNEmy2rbilBSyVhi4KD1dSIO_4NlxuE,199
 llmstack/_platform.py,sha256=eDY3T9krkaBigG5xXxqzIbH3MhdZqX3BWe7bozOsAso,13099
-llmstack/app.py,sha256=WKViWk7-TUuqdo3em77JgxgUo1Jo745Ew3RUoY7th-s,27945
+llmstack/app.py,sha256=3Qt_bveLS13rPEucyX0P6QDf9o9O68amnJIvwMqoTQQ,28469
 llmstack/check_models.py,sha256=WvTS2Td4acp-Q0-yWXUgXAgAgFOmpxiaeSDuAoivirw,4559
 llmstack/cli.py,sha256=Om70PzHrmU81y2Mw1sB6eeUs1fRHP0PnsCEVNC0UNvI,11341
-llmstack/models.ini,sha256=m595QVX5Nh5YEHcrKLl5ldvNIORiy27OwxNMDsSwlsE,20339
+llmstack/models.ini,sha256=U38Z6wfGCpmgQTCNbnp1zu80rUrhNGWFTvI2nhVx1Mo,20556
 llmstack/paths.py,sha256=A8q4-tpwIt5UMGG5ZDESKSuViMGLbPIAL1VoONopJqU,11512
 llmstack/shell_env.py,sha256=MJSW0PP15q-fsppIZ98WZ7XoqYMZmDy4k8N0gzEA6wU,39362
-llmstack/tiers.py,sha256=et738dWftsc74ZElZ3Vt9eEF_SzgJCDuH9kBhzH-scI,14697
+llmstack/tiers.py,sha256=yl5xEhECe-GHiVXBRvlNoFtH_9y4uNSASpfHlZ4Ja74,14820
 llmstack/backends/__init__.py,sha256=-85sQz0R94OdbM2bUHGyyA5WaMnI9bHywPOaELeQHX0,777
-llmstack/backends/bedrock.py,sha256=_UFBWR7R2Q4BPAsskXemjgPnu0dyJLSXel86smo9mSc,30015
+llmstack/backends/bedrock.py,sha256=Nb9sV45aH0RQHie_AkQwcpX5pkio5EAqnsphZM5P_nQ,30638
 llmstack/commands/__init__.py,sha256=eVO-YUxh1fSfdq72KggC-NrTYMtN6zIykgjyRgOCAt4,406
 llmstack/commands/_helpers.py,sha256=UKADaNXrnuoDi_JG0W2Tph7rWFB0cXvQh8YknZBw56I,2660
 llmstack/commands/activate.py,sha256=zCdEmyVv5qZUdhfez6hZ5Y46N_yjPwfKbPTwCJXnA3o,3663
@@ -21,7 +21,7 @@ llmstack/commands/install_llama_swap.py,sha256=c6iedl-DjnOc7jMVzy_M0aIWSgygzAgYU
 llmstack/commands/reload.py,sha256=Z7ceZQX2fkHpZiWxov8YwidR72Xw0-qMFFV_RRXpkwI,2016
 llmstack/commands/restart.py,sha256=Bp6lSAnLhR2Nd7eA5BlD9J_TeGlzRfWS_Z3DdxP-eq4,294
 llmstack/commands/setup.py,sha256=ZBPXas7jswfYL6IwAJhReR0BVGn4LWaf-0ZhR8lQG6I,5381
-llmstack/commands/start.py,sha256=V9BDZeCQS_NL2bJmJANHVE2J1rqoYBUDYcjK9O_PNYM,15693
+llmstack/commands/start.py,sha256=u6tLI5yTtOtIRwEJNDofZiqY2vv39Xhw6GPShE1wFIg,15655
 llmstack/commands/status.py,sha256=TOHoDSyu04lZtepJH4bFmIk694RyaUYeFMpUejyUPe0,10403
 llmstack/commands/stop.py,sha256=vntZ1n8wpY9zgix1xGHDNJqEacaUpw9haSKgOnMg73k,2474
 llmstack/download/__init__.py,sha256=lpGmxsE4zxSp0fQViNJZHzbCL_V8zy6IHn71MP31538,695
@@ -30,8 +30,12 @@ llmstack/download/ggufs.py,sha256=2hCr-svUiPIV2I3ruwTbXo6lPn9m-VBOqa3DFbvdIcA,54
 llmstack/generators/__init__.py,sha256=LfbcReuyYBCdVuT9J5RKo7-f8n585YBU3Hus6DsxqTs,1189
 llmstack/generators/llama_swap.py,sha256=KdYH9N6TJECotZvyxvAjaa3kRyzn4YOi2T6D2UdyVKw,14785
 llmstack/generators/opencode.py,sha256=s_FrLXUBnLzRGQovl1PcAEs7V_P52wT1vnvvxMcKfs4,11203
-opencode_llmstack-0.9.1.dist-info/METADATA,sha256=OAoNwEOF9ESVwKAQ-VXD5868sMSIhiVxq47cDqWcK_k,34914
-opencode_llmstack-0.9.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-opencode_llmstack-0.9.1.dist-info/entry_points.txt,sha256=soomjpqvl4KzFScgpQbu96vgcLriOtkB9MbiSC0rvZ8,47
-opencode_llmstack-0.9.1.dist-info/top_level.txt,sha256=tMv9sDWp8RW_DNNY8cuM4Uy4sND-KwTLcsScl5gdcEQ,9
-opencode_llmstack-0.9.1.dist-info/RECORD,,
+opencode_llmstack-0.9.3.data/data/CHANGELOG.md,sha256=2Ok5sn4aA_N5UMaUJ4jRbuTeWC1pt7gdFgYnxj2JdKU,5217
+opencode_llmstack-0.9.3.data/data/LICENSE,sha256=6G-Otw6BHIM1WJSBlJ04P1rDVCqbDEzKpdOlSr5CqIY,1078
+opencode_llmstack-0.9.3.data/data/UPGRADING.md,sha256=0XSNZ9trCviFLH5EL3Jz02fO2_8AfqB8_9aX0-o1bik,24927
+opencode_llmstack-0.9.3.dist-info/licenses/LICENSE,sha256=6G-Otw6BHIM1WJSBlJ04P1rDVCqbDEzKpdOlSr5CqIY,1078
+opencode_llmstack-0.9.3.dist-info/METADATA,sha256=QL_Za8nscUU57s41131pavDonGlSmSbHnNUZXWAMYqo,36323
+opencode_llmstack-0.9.3.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+opencode_llmstack-0.9.3.dist-info/entry_points.txt,sha256=soomjpqvl4KzFScgpQbu96vgcLriOtkB9MbiSC0rvZ8,47
+opencode_llmstack-0.9.3.dist-info/top_level.txt,sha256=tMv9sDWp8RW_DNNY8cuM4Uy4sND-KwTLcsScl5gdcEQ,9
+opencode_llmstack-0.9.3.dist-info/RECORD,,

opencode_llmstack-0.9.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 llmstack contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.