jambu-gpu 0.1.0__tar.gz

jambu_gpu-0.1.0/.env.example

@@ -0,0 +1,11 @@
+# Credentials are resolved from the environment, this file, or
+# ~/.jambu/credentials - never from jambu.yaml.
+
+# Required by the vast provider.
+VAST_API_KEY=
+
+# Optional: needed for gated HuggingFace models.
+HF_TOKEN=
+
+# Optional: per-profile override, used when provider.profile: staging
+# VAST_API_KEY__staging=

jambu_gpu-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.jambu/
+.env
+.env.*
+!.env.example
+.pytest_cache/
+.coverage
+node_modules/
+*.tsbuildinfo

jambu_gpu-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing
+
+`jambu-gpu` provisions a temporary GPU runtime and guarantees it stops billing
+when nothing is using it. Contributions are welcome. By submitting a change you
+agree it is licensed under the [MIT License](LICENSE).
+
+## Command name
+
+The published command is `gpu`. The package name stays `jambu-gpu`.
+
+Do not add a second console script. One command, in `pyproject.toml`:
+
+```toml
+[project.scripts]
+gpu = "jambu_gpu.cli.main:main"
+```
+
+## Setup
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+```
+
+Python 3.10 or newer. Tests do not need `VAST_API_KEY`, a GPU, or network access.
+
+## Tests
+
+```bash
+.venv/bin/pytest
+.venv/bin/pytest tests/test_policy.py       # shutdown rule
+.venv/bin/pytest tests/test_watchdog.py     # generated guard, as a real process
+.venv/bin/pytest tests/test_integration.py  # setup -> boot -> run -> auto-stop
+```
+
+A change to lifecycle behaviour needs a test that fails before the change and
+passes after it. The policy in `jambu_gpu/core/policy.py` and the watchdog that
+runs on the instance must keep agreeing: the watchdog inlines that module at
+provision time.
+
+`tests/test_integration.py` does not mock the boot. It runs the onstart script
+the engine generated, starts the real watchdog, waits on a real health endpoint,
+runs a workload with real heartbeats, and asserts the guard stops the instance
+with the right reason.
+
+## What you may change
+
+| Change | Where it goes |
+| --- | --- |
+| New provider | `jambu_gpu/providers/<name>/` plus one registry line. See [docs/ADDING_A_PROVIDER.md](docs/ADDING_A_PROVIDER.md). |
+| Shutdown rule | `jambu_gpu/core/policy.py` and `tests/test_policy.py`. |
+| How the model server starts | `jambu_gpu/runtime/`. |
+| CLI surface | `jambu_gpu/cli/`. Keep `--json` and `--config` on every command. |
+
+The core must not branch on a provider name. Branch on `provider.capabilities`.
+If a provider feature requires an `if provider == "..."` in `core/`, the contract
+is wrong — extend the contract instead.
+
+Out of scope: multi-instance scheduling, multi-GPU
+orchestration, Kubernetes, distributed inference, automatic provider selection,
+job queues, a web dashboard. See [docs/ACCEPTANCE.md](docs/ACCEPTANCE.md).
+
+## Secrets
+
+Never commit credentials, `.env`, `.jambu/state.json`, or provider instance
+ids from a real run. Keys are read from the environment, a gitignored `.env`,
+or `~/.jambu/credentials`. `.env.example` ships with empty values only.
+
+## Pull requests
+
+- Explain why the behaviour should change, not only what moved.
+- Run `.venv/bin/pytest` and report the result.
+- Keep commits focused. A provider adapter and a policy change are two PRs.
+- Match the surrounding style: English identifiers and docs, type hints on new
+  public functions, no new dependency unless the standard library cannot do the job.

jambu_gpu-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jambu.ai and João Gabriel Lima
+
+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.

jambu_gpu-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.5
+Name: jambu-gpu
+Version: 0.1.0
+Summary: Provider-agnostic CLI for provisioning and managing temporary GPU runtimes
+Project-URL: Homepage, https://github.com/jambuai/jambu-gpu
+Project-URL: Repository, https://github.com/jambuai/jambu-gpu
+Project-URL: Issues, https://github.com/jambuai/jambu-gpu/issues
+Author: Jambu.ai
+Author-email: João Gabriel Lima <joao.gabriel@jambu.ai>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gpu
+
+Temporary GPU runtimes that stop billing when the work stops.
+
+You declare the model and how long it may live. `gpu` provisions a machine, starts the model server, and runs your job against it. Shutdown happens on the instance, so closing the laptop does not leave the GPU billing.
+
+Vast.ai is the first provider. Another provider is a new adapter. The lifecycle rule stays the same.
+
+## Run
+
+```bash
+pip install jambu-gpu
+
+cd your-experiment
+gpu init --model empero-ai/Qwythos-9B-v2
+export VAST_API_KEY=...
+
+gpu validate
+gpu setup
+gpu run python experiment.py
+```
+
+When you are finished, `gpu destroy`. If you walk away, the idle timeout does it.
+
+The API key is read from the environment, a project `.env`, or `~/.jambu/credentials`. It never goes in the manifest.
+
+## Declare
+
+```yaml
+gpu_runtime:
+  provider: {name: vast}
+  model_profile: qwythos-9b
+  lifecycle:
+    idle_timeout: 15m
+    max_lifetime: 6h
+  budget:
+    max_hourly_cost_usd: 1.50
+```
+
+The file is `jambu.yaml`. This tool reads only the `gpu_runtime:` key, so other Jambu tools can share the same file. A full example is [`jambu.example.yaml`](jambu.example.yaml).
+
+## Docs
+
+- [Commands, workloads, and agents](docs/USAGE.md)
+- [Every config field](docs/CONFIG.md)
+- [Choosing a model](docs/CHOOSING_A_MODEL.md)
+- [How shutdown works](docs/LIFECYCLE.md)
+- [Adding a provider](docs/ADDING_A_PROVIDER.md)
+- [Contributing](CONTRIBUTING.md)
+
+## License
+
+[MIT](LICENSE).
+
+<p align="center">
+  <a href="https://jambu.ai">
+    <img src="docs/assets/jambu-logo.jpg" alt="Jambu.ai — Applied Intelligence Lab" width="280">
+  </a>
+</p>

jambu_gpu-0.1.0/README.md

@@ -0,0 +1,59 @@
+# gpu
+
+Temporary GPU runtimes that stop billing when the work stops.
+
+You declare the model and how long it may live. `gpu` provisions a machine, starts the model server, and runs your job against it. Shutdown happens on the instance, so closing the laptop does not leave the GPU billing.
+
+Vast.ai is the first provider. Another provider is a new adapter. The lifecycle rule stays the same.
+
+## Run
+
+```bash
+pip install jambu-gpu
+
+cd your-experiment
+gpu init --model empero-ai/Qwythos-9B-v2
+export VAST_API_KEY=...
+
+gpu validate
+gpu setup
+gpu run python experiment.py
+```
+
+When you are finished, `gpu destroy`. If you walk away, the idle timeout does it.
+
+The API key is read from the environment, a project `.env`, or `~/.jambu/credentials`. It never goes in the manifest.
+
+## Declare
+
+```yaml
+gpu_runtime:
+  provider: {name: vast}
+  model_profile: qwythos-9b
+  lifecycle:
+    idle_timeout: 15m
+    max_lifetime: 6h
+  budget:
+    max_hourly_cost_usd: 1.50
+```
+
+The file is `jambu.yaml`. This tool reads only the `gpu_runtime:` key, so other Jambu tools can share the same file. A full example is [`jambu.example.yaml`](jambu.example.yaml).
+
+## Docs
+
+- [Commands, workloads, and agents](docs/USAGE.md)
+- [Every config field](docs/CONFIG.md)
+- [Choosing a model](docs/CHOOSING_A_MODEL.md)
+- [How shutdown works](docs/LIFECYCLE.md)
+- [Adding a provider](docs/ADDING_A_PROVIDER.md)
+- [Contributing](CONTRIBUTING.md)
+
+## License
+
+[MIT](LICENSE).
+
+<p align="center">
+  <a href="https://jambu.ai">
+    <img src="docs/assets/jambu-logo.jpg" alt="Jambu.ai — Applied Intelligence Lab" width="280">
+  </a>
+</p>

jambu_gpu-0.1.0/docs/ACCEPTANCE.md

@@ -0,0 +1,28 @@
+# Acceptance criteria — where each one is implemented and tested
+
+Twelve guarantees, mapped to the code and the test that holds each one.
+
+| # | Guarantee | Implementation | Test |
+| --- | --- | --- | --- |
+| 1 | Repeated `setup` does not duplicate infrastructure | `core/engine.py::Engine.setup` reconciles first, compares `config.fingerprint()`, and holds an exclusive `.jambu/runtime.lock` | `test_engine.py::test_setup_twice_does_not_create_two_instances`, `::test_setup_refuses_to_reuse_an_incompatible_instance` |
+| 2 | Provider APIs do not leak into core orchestration | `providers/base.py` contract; all Vast wire format confined to `providers/vast/{client,mapper}.py` | `test_engine.py::test_the_core_never_branches_on_a_provider_name` (greps `core/`) |
+| 3 | Missing credentials fail before provisioning | `VastProvider.validate` returns before any API call; `CredentialResolver` never reads jambu.yaml | `test_vast_provider.py::test_validate_fails_before_provisioning_without_a_key` (asserts zero HTTP calls) |
+| 4 | Failed provisioning cleans up | `Engine.setup` persists state *before* the long wait, then destroys on failure when `cleanup_on_setup_failure` | `test_engine.py::test_failed_setup_cleans_up_partially_created_resources` |
+| 5 | Active workloads are never stopped by the idle guard | `core/policy.py::evaluate` returns `workload_active` before any idle check | `test_policy.py::test_active_workload_is_never_stopped_by_the_idle_guard`, `test_watchdog.py::test_a_heartbeating_workload_is_never_stopped` |
+| 6 | An idle unlocked instance stops within `idle_timeout + watchdog_interval` | remote watchdog loop, `watchdog/agent_body.py::guard_loop` | `test_watchdog.py::test_idle_instance_is_stopped_with_a_recorded_reason` (real subprocess) |
+| 7 | `max_lifetime` bounds forgotten instances | `policy.evaluate` checks age before activity | `test_policy.py::test_max_lifetime_stops_even_when_busy`, `test_watchdog.py::test_max_lifetime_stops_a_busy_instance` |
+| 8 | Locks prevent shutdown until expiry | `policy.Snapshot.lock_active` / `lock_expired`; TTL required unless `allow_indefinite_lock` | `test_policy.py::test_expired_lock_stops_protecting`, `test_watchdog.py::test_a_lock_prevents_shutdown_until_it_expires` |
+| 9 | A crashed CLI does not disable protection | the guard runs *on the instance*; heartbeats go stale after `heartbeat_grace` | `test_watchdog.py::test_a_vanished_heartbeat_falls_back_to_idle`, `::test_startup_grace_expires_when_the_cli_never_confirms` |
+| 10 | Remote state is reconciled | `Engine._reconcile` merges provider truth + watchdog truth and repairs local state | `test_engine.py::test_status_repairs_state_when_the_instance_vanished` |
+| 11 | A new provider needs only the contract | `providers/registry.py`; the engine is driven end to end by `tests/fakes.py::FakeProvider` | `test_engine.py::test_a_new_provider_needs_only_the_contract` |
+| 12 | Every automatic shutdown records its reason | `lifecycle_guard_triggered` + `instance_stopped` events carry `reason`, locally and on the instance | `test_engine.py::test_guard_stops_an_idle_unlocked_instance_and_records_the_reason`, `test_watchdog.py::test_idle_instance_is_stopped_with_a_recorded_reason` |
+
+## The MVP command surface
+
+`jambu.yaml` schema, CLI, provider contract, provider registry, Vast.ai adapter,
+vLLM runtime, `setup`, `run`, `status`, `stop`, `destroy`, `lock`/`unlock`, idle
+timeout, max lifetime, remote watchdog, structured logs — all present.
+
+Deliberately not implemented: multi-instance scheduling, multi-GPU
+orchestration, Kubernetes, distributed inference, provider optimization, automatic
+provider selection, job queues, web dashboard.

jambu_gpu-0.1.0/docs/ADDING_A_PROVIDER.md

@@ -0,0 +1,121 @@
+# Adding a provider
+
+Adding a provider means adding `jambu_gpu/providers/<name>/` and one line in the
+registry. **No lifecycle, execution or CLI code changes.** If you find yourself
+editing `core/`, the contract is leaking.
+
+## 1. Implement the contract
+
+```python
+# jambu_gpu/providers/runpod/provider.py
+from ...core.models import ProviderCapabilities
+from ..base import GPUProvider, WatchdogSpec
+
+
+class RunpodProvider(GPUProvider):
+    name = "runpod"
+    display_name = "RunPod"
+    required_credentials = ["RUNPOD_API_KEY"]
+    capabilities = ProviderCapabilities(
+        stop=True,
+        destroy=True,
+        ssh=True,
+        public_ports=True,
+        gpu_selection=True,
+        pricing_query=True,
+        remote_exec=True,
+        logs=True,
+        stop_eliminates_billing=True,
+    )
+
+    def validate(self, config): ...
+    def setup(self, spec): ...
+    def start(self, instance): ...
+    def run(self, instance, workload): ...
+    def status(self, instance): ...
+    def stop(self, instance): ...
+    def destroy(self, instance): ...
+    def logs(self, instance): ...
+```
+
+Suggested layout, mirroring the Vast adapter:
+
+```
+providers/runpod/
+├── provider.py   the contract implementation
+├── client.py     raw HTTP; the ONLY place that knows the wire format
+├── mapper.py     payloads <-> normalized models, state mapping
+└── config.py     provider.options schema and constants
+```
+
+## 2. Declare capabilities honestly
+
+The core never branches on `provider.name` — only on `provider.capabilities`. Set
+`stop_eliminates_billing=False` if a stopped instance still costs money; the policy
+then knows it may need to escalate to destroy.
+
+## 3. Normalize state and errors
+
+Map every provider status onto `InstanceState`
+(`provisioning / starting / ready / busy / idle / stopped / failed / destroyed`),
+and raise only the normalized errors from `core/errors.py`:
+`AuthenticationError`, `CapacityUnavailableError`, `ProvisioningError`,
+`ProviderTimeoutError`, `UnsupportedCapabilityError`. CLI behaviour must be
+identical across providers.
+
+## 4. Supply the watchdog actions
+
+The lifecycle *policy* is the core's; the adapter contributes only the two calls
+that shut the machine down from inside itself:
+
+```python
+WATCHDOG_ACTIONS = '''
+def provider_stop(ctx):
+    ...   # stdlib only: urllib, json, os
+
+def provider_destroy(ctx):
+    ...
+'''
+
+def watchdog_spec(self, spec_or_instance=None):
+    return WatchdogSpec(
+        actions_source=WATCHDOG_ACTIONS,
+        env={"RUNPOD_API_KEY": self.credentials.get("RUNPOD_API_KEY") or ""},
+        context={"provider": self.name},
+    )
+```
+
+The instance id may not exist when the boot script is generated. Either resolve it
+from the container's own environment (as the Vast adapter does with
+`VAST_CONTAINERLABEL`), or rely on the CLI's `/identify` call — support both if you
+can, so the guard works even if the CLI never reconnects.
+
+Return `None` only if the provider genuinely cannot self-terminate; users then have
+to run `gpu guard` externally, and `validate` will warn.
+
+## 5. Publish the ports
+
+`ComputeSpec.ports` lists the container ports the core needs published. Map them to
+`Instance.endpoints` under the names `model` and `watchdog`. Without a published
+watchdog port the remote guard is unreachable.
+
+## 6. Register it
+
+```python
+# providers/registry.py
+def load_builtin_providers():
+    from .vast.provider import VastProvider
+    from .runpod.provider import RunpodProvider
+
+    registry.register(VastProvider)
+    registry.register(RunpodProvider)
+    return registry
+```
+
+## 7. Test it
+
+Copy `tests/test_vast_provider.py` and swap the mocked payloads. Then check the
+adapter really is swappable — `tests/test_engine.py` drives the whole engine
+through `tests/fakes.py::FakeProvider` with zero core changes, and
+`test_the_core_never_branches_on_a_provider_name` fails the build if `core/` learns
+a provider's name.

jambu_gpu-0.1.0/docs/CHOOSING_A_MODEL.md

@@ -0,0 +1,198 @@
+# Where jambu.yaml's model-specific values come from
+
+Every value in `model:`/`compute.gpu:`/`runtime:` that depends on *which model*
+you're deploying (VRAM, dtype, context length, tool-call parser,
+`trust_remote_code`) has a real source. This is that source, and the command
+that reads it for you.
+
+## `gpu inspect-model`
+
+```bash
+gpu inspect-model Qwen/Qwen2.5-7B-Instruct
+```
+
+```text
+Qwen/Qwen2.5-7B-Instruct @ main
+  architecture   Qwen2ForCausalLM (model_type: qwen2)
+  parameters     7.62B (BF16)
+  weight size    ~15.2 GB -> suggested min_vram_gb: 22
+  context        native 32768
+  tool calling   hermes
+
+Sources
+  https://huggingface.co/api/models/Qwen/Qwen2.5-7B-Instruct
+  https://huggingface.co/Qwen/Qwen2.5-7B-Instruct/raw/main/config.json
+
+Suggested gpu_runtime: snippet
+gpu_runtime:
+  model:
+    id: Qwen/Qwen2.5-7B-Instruct
+
+  compute:
+    gpu:
+      min_vram_gb: 22  # estimate, see notes
+      count: 1
+
+  runtime:
+    engine: vllm
+    context_length: 32768
+    tool_calling: auto  # resolves to hermes automatically
+```
+
+Paste the snippet under `gpu_runtime:` in your `jambu.yaml`, adjust
+`lifecycle`/`health`/`budget` for your situation, and you have a starting
+config. Add `--json` for machine-readable output, `--revision` for a
+non-`main` branch/tag, `--hf-token-env` if the repo is gated and your token
+lives under a different env var than `HF_TOKEN`.
+
+**This is a starting point, not an oracle.** It never talks to Vast.ai and
+never boots anything — it only reads two public HuggingFace documents and does
+arithmetic. Confirm the real number with `gpu offers` (finds actual
+capacity at that size) and a real `gpu setup` (the only way to know a
+model genuinely boots and serves).
+
+## The two documents, and exactly what each field feeds
+
+### 1. `https://huggingface.co/api/models/<repo>` — the Hub API
+
+The **real, on-disk** shape of the checkpoint — more reliable than anything in
+prose, because it's read from the actual safetensors file headers, not
+declared by the model's author.
+
+| JSON field | Feeds | Notes |
+| --- | --- | --- |
+| `safetensors.total` | `compute.gpu.min_vram_gb` (via weight size) | Total parameter count. Absent for GGUF-only repos — size manually if so. |
+| `safetensors.parameters` | `runtime.dtype`, byte width for the VRAM estimate | `{"BF16": N, "F8_E4M3": M}` style breakdown. `inspect-model` picks the dtype with the most parameters — a few embedding/norm tensors often stay bf16 even in an FP8 release. |
+| `gated` | whether you need `model.hf_token_env` | `false` / `"auto"` / `"manual"` — any non-`false` value means a real token is required, not just recommended. |
+| `tags`, `pipeline_tag` | sanity check | Confirms it's actually a text-generation checkpoint before you provision a GPU for it. |
+
+### 2. `https://huggingface.co/<repo>/raw/<revision>/config.json` — the model's own HF config
+
+The architecture's own declaration of itself — what `transformers`/vLLM read
+to know how to load it.
+
+| JSON field | Feeds | Notes |
+| --- | --- | --- |
+| `architectures` | recognizing the model family | e.g. `Qwen3_5ForConditionalGeneration`. Cross-reference against [vLLM's supported models](https://docs.vllm.ai/en/latest/models/supported_models/) — an unlisted architecture will fail to load regardless of VRAM. |
+| `model_type` | hybrid-attention detection | gpu flags known linear-attention families (`qwen3_5`/`qwen3_6`/`qwen3_8`, `jamba`, `mamba`, `bamba`, `deltanet`/`gdn` in the string, ...) — these need an **Ampere-or-newer** GPU for their Triton/FLA kernels. Confirmed the hard way: a Turing card (Quadro RTX 8000) failed to boot vLLM at all for a `qwen3_5` model; Ampere (RTX A6000) worked immediately. |
+| `torch_dtype` | `runtime.dtype`, VRAM estimate (fallback) | Used only when the Hub API's `safetensors.parameters` is absent — the API's real on-disk dtype is preferred when both exist, since a repo can ship a different dtype than it trained in. |
+| `quantization_config.quant_method` | VRAM estimate, `runtime.dtype: auto` | `fp8`/`awq`/`gptq`/`bitsandbytes_4bit` change the byte width per parameter; when present, set `runtime.dtype: auto` and let vLLM read the quantization from the checkpoint instead of forcing a dtype that fights it. |
+| `max_position_embeddings` | `runtime.context_length` | The model's *native* window. `inspect-model` suggests `min(native, 32768)` — the native number is often a YaRN-extended marketing ceiling (e.g. 1,048,576), not a sane default: allocating KV cache for the full window is neither necessary nor cheap for typical agentic/tool-use turns. |
+| `auto_map` | `model.trust_remote_code` | Its *presence* (regardless of value) is the actual signal `transformers` uses to know a repo ships custom modeling code. Absence doesn't guarantee you never need `trust_remote_code: true` — some very new architectures need it even with native library support during a transition period — but presence is a reliable "you definitely do." |
+| `rope_scaling` | context length ceiling sanity-check | Confirms whether a large `max_position_embeddings` is native or extended (YaRN/linear/dynamic) — extended windows cost more KV cache per token than the base architecture would suggest. |
+
+### Tool-call parser: a third, unwritten source
+
+There is no machine-readable field anywhere that says "use `--tool-call-parser
+X`" — this is `jambu_gpu/core/tool_parsers.py`'s own hand-maintained table,
+matched against vLLM's [tool calling
+docs](https://docs.vllm.ai/en/latest/features/tool_calling/) and, sometimes,
+empirical testing when the docs don't cover a model family yet (the Qwen3.5+
+`qwen3_xml` entry was added after a live test showed `hermes` left the model's
+tool call as inert text in `content` instead of a parsed `tool_calls` array).
+
+Consequences:
+
+- It only matches on **repo name substrings** (`"qwen3.5"`, `"llama-3"`, ...).
+  A fine-tune with a custom name (`empero-ai/Qwythos-9B-v2`, based on Qwen3.5)
+  won't be recognized even though the underlying format is known — set
+  `runtime.tool_call_parser` explicitly once you know the base model.
+- It can be wrong or incomplete for anything genuinely new. If `inspect-model`
+  reports no parser guessed, **or an explicit one you set doesn't actually
+  produce a `tool_calls` array**, the fix is the same: pick a candidate
+  parser (start from the model's base-architecture family, e.g. Qwen3.8 → try
+  what worked for Qwen3.5), restart the server with `--enable-auto-tool-choice
+  --tool-call-parser <candidate>`, and send one real tool-calling request —
+  a working parser puts the call in `message.tool_calls`, not `message.content`.
+  See [`docs/ADDING_A_PROVIDER.md`](ADDING_A_PROVIDER.md) for how the fingerprint
+  interacts with runtime-only changes like this if you're doing it through
+  `gpu setup` rather than by hand.
+- When you do confirm one empirically, add it to `_TOOL_PARSER_HINTS` in
+  `jambu_gpu/core/tool_parsers.py` (a one-line PR) so `tool_calling: auto`
+  picks it up for everyone next time, the same way the Qwen3.5+ finding did.
+
+## Don't write a new jambu.yaml per model - use the catalog
+
+Every model you add this way is tempting to just copy the whole file: same
+provider, same lifecycle, same budget, only `model:`/`compute.gpu:` actually
+differ. Do that a handful of times and a repo ends up with
+`jambu.qwythos.yaml`, `jambu.model-b.yaml`, `jambu.model-c.yaml`... duplicated
+again in every sub-project directory that wants one - a pile of near-identical
+files where changing a lifecycle default means editing all of them.
+
+The fix: split "what varies by model" (the catalog) from "what varies by
+project" (the active `jambu.yaml`), and reference the former by name.
+
+```yaml
+# jambu.models.yaml - one entry per model, shared by every project in the
+# repo (found by walking up from a project's jambu.yaml, same as jambu.yaml
+# itself is found - one catalog can sit at the repo root and serve every
+# sub-project under it).
+qwythos-9b:
+  model: {id: empero-ai/Qwythos-9B-v2, trust_remote_code: true}
+  compute: {gpu: {min_vram_gb: 40, name_filter: A6000}}
+  runtime: {tool_calling: "on", tool_call_parser: qwen3_xml}
+
+qwen3.8-27b-uncensored:
+  model: {id: orcarouter/Qwen3.8-27B-Uncensored-FP8}
+  compute: {gpu: {min_vram_gb: 44, name_filter: A6000}}
+```
+
+```yaml
+# jambu.yaml - just this project's policy + which model
+gpu_runtime:
+  version: 1
+  model_profile: qwythos-9b   # the only thing that changes to switch models
+  lifecycle: {idle_timeout: 15m, max_lifetime: 6h}
+  budget: {max_hourly_cost_usd: 1.50}
+```
+
+The project's own fields always win over the profile's - a profile is a set
+of defaults, not a lock, so a project can still override just one leaf
+(`compute.gpu.min_vram_gb: 80`, say) without redeclaring the whole model.
+
+`gpu inspect-model <repo> --add-profile <name>` writes straight into
+the catalog (creating it if it doesn't exist) instead of printing a snippet
+to paste into a new file - the research and the config land in the same
+command. `gpu profiles` lists what's in it.
+
+This is the same base+overlay pattern as docker-compose's `extends`, Helm
+`values.yaml`, or Kustomize overlays - one place owns "what", each consumer
+only says "which one, and what's different here."
+
+**When a full standalone file still makes sense:** a genuinely one-off
+experiment nobody else will reuse, or a config for a completely different
+project that will never share this repo's catalog. Most "I need to try model
+X" situations are the catalog case, not this one.
+
+## Dynamic / un-modeled vLLM flags
+
+`jambu.yaml`'s schema deliberately models the fields that affect *lifecycle,
+cost, and provider portability* — it does not, and cannot, keep up with every
+flag vLLM ships (vLLM adds flags faster than any fixed contract could track).
+For everything else, `runtime:` has two escape hatches, applied in this order
+(later wins on conflict, matching how vLLM's own argparse takes the last
+occurrence of a repeated flag):
+
+```yaml
+runtime:
+  # Structured: {flag: value} -> --flag value. Handles the common shapes:
+  #   true            -> a bare flag                    --enable-prefix-caching
+  #   false           -> the negated flag                --no-enforce-eager
+  #   a dict/list      -> JSON-encoded (several vLLM flags take JSON)
+  #                                          --limit-mm-per-prompt '{"image":0}'
+  #   anything else    -> --flag str(value)              --max-num-seqs 64
+  vllm_args:
+    max_num_seqs: 64
+    enable-prefix-caching: true
+
+  # Raw argv, appended last, verbatim - for anything the structured form
+  # can't express (repeated flags, exotic syntax).
+  extra_args: ["--kv-cache-dtype", "fp8"]
+```
+
+Setting a flag gpu already manages through another field (`--model`,
+`--port`, `--enable-auto-tool-choice`, ...) via `vllm_args` still works — it
+wins, since it's applied after those — but `gpu validate` warns about it,
+because the config field that's supposed to control that behavior (e.g.
+`runtime.tool_calling`) will silently stop reflecting what's actually running.