stabbur 0.6.0__tar.gz

stabbur-0.6.0/LICENSE

@@ -0,0 +1,24 @@
+stabbur — Proprietary Software License
+
+Copyright (c) 2026 Morten Hansen. All rights reserved.
+
+This software and its source code (the "Software") are the exclusive property of
+Morten Hansen (the "Owner"). The Software is made source-available for reference
+and evaluation only. It is NOT open-source and is NOT licensed for use.
+
+No license or right is granted, whether express or implied, to any person or
+entity to use, copy, run, execute, deploy, host, modify, adapt, translate,
+create derivative works of, distribute, sublicense, sell, or otherwise exploit
+the Software, in whole or in part, for any purpose, without the prior written
+permission of the Owner.
+
+Viewing the source in the public repository does not grant any right to use it.
+Any use of the Software requires a separate written license agreement with the
+Owner. To request permission, contact morten@winterop.com.
+
+Unless required by applicable law or agreed to in writing, 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 non-infringement. In no event shall the Owner be liable for any
+claim, damages, or other liability arising from, out of, or in connection with
+the Software or its use.

stabbur-0.6.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: stabbur
+Version: 0.6.0
+Summary: Stabbur — build a local LLM library, then run, chat, and serve it — fully on-box
+Keywords: llm,local-llm,self-hosted,mcp,agent,dhis2,fastapi,huggingface
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: fastapi[standard]>=0.138.2
+Requires-Dist: fastmcp>=3.4.2
+Requires-Dist: hf-xet>=1.5.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: huggingface-hub>=1.21.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: kokoro-onnx>=0.4.9
+Requires-Dist: pluginkit>=0.4.7
+Requires-Dist: pydantic-settings>=2.14.2
+Requires-Dist: soundfile>=0.13.1
+Requires-Dist: textual>=0.85
+Requires-Dist: typer>=0.25.1
+Requires-Dist: uvicorn[standard]>=0.49.0
+Requires-Dist: mlx-lm>=0.31.3 ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'mlx'
+Requires-Dist: mlx-vlm>=0.6.3 ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'mlx'
+Requires-Dist: transformers>=5.5,<5.13 ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'mlx'
+Requires-Dist: mlx-audio>=0.4.4 ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'voice'
+Requires-Dist: misaki[en]>=0.9.4 ; extra == 'voice'
+Requires-Dist: soundfile>=0.13.1 ; extra == 'voice'
+Requires-Dist: soxr>=0.5 ; extra == 'voice'
+Requires-Dist: transformers>=5.5,<5.13 ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'voice'
+Requires-Dist: playwright>=1.47 ; extra == 'web'
+Requires-Dist: trafilatura>=1.12 ; extra == 'web'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/winterop-com/stabbur
+Project-URL: Repository, https://github.com/winterop-com/stabbur
+Project-URL: Documentation, https://github.com/winterop-com/stabbur/tree/main/docs
+Project-URL: Issues, https://github.com/winterop-com/stabbur/issues
+Provides-Extra: benchmark
+Provides-Extra: mlx
+Provides-Extra: voice
+Provides-Extra: web
+Description-Content-Type: text/markdown
+
+<!-- Absolute URLs: this README is the PyPI long description, and PyPI does not rewrite
+     relative paths - a repo-relative src renders as a broken image on the project page. -->
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/winterop-com/stabbur/main/docs/assets/logo.png" alt="stabbur" width="200">
+
+# stabbur
+
+[![CI](https://github.com/winterop-com/stabbur/actions/workflows/ci.yml/badge.svg)](https://github.com/winterop-com/stabbur/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/stabbur)](https://pypi.org/project/stabbur/)
+[![Python](https://img.shields.io/badge/python-3.13-3776ab)](https://www.python.org/)
+[![Packaging](https://img.shields.io/badge/install-uv-6340ac)](https://docs.astral.sh/uv/)
+[![License](https://img.shields.io/badge/license-proprietary-lightgrey)](https://github.com/winterop-com/stabbur/blob/main/LICENSE)
+
+</div>
+
+A tool for building and keeping a **full local library of LLM models**. It
+discovers models from **Hugging Face**, **Ollama**, and **LM Studio**, pulls
+them into a single library (browse via a **Typer CLI** or a **browser chat UI**),
+and runs them from there. The library lives under one configurable root you point
+at an external drive (e.g. a 5TB drive).
+
+**Short form.** Every command is also available as `sb` — `sb chat`, `sb serve`, `sb library ls`.
+
+**The name.** A *stabbur* is the Norwegian storehouse — raised on pillars, off the ground and
+out of the damp, where a household kept what it had gathered and wanted to keep. That is what this
+is: your models, pulled in from wherever they came from and kept somewhere of your own, on your own
+box, rather than in someone else's cloud.
+
+> **Proprietary, source-available.** stabbur is not open-source. Copyright (c) 2026 Morten
+> Hansen, all rights reserved (see [`LICENSE`](LICENSE)). The source is published for
+> reference and evaluation; running it requires a written license — contact
+> <morten@winterop.com>. Install is from source with `uv` (there is no `pip install stabbur`).
+
+![stabbur web UI](https://raw.githubusercontent.com/winterop-com/stabbur/main/docs/assets/web-ui.png)
+
+## Layout
+
+```
+src/stabbur/
+├── config.py          # Pydantic settings (STABBUR_* env vars)
+├── models.py          # Catalog / entry / result models
+├── catalog.py         # Aggregates listing + pull across sources
+├── library.py         # Scans the on-drive library (gguf/ mlx/ voice/ ...)
+├── capabilities.py    # Detects per-model tools/vision/audio + context
+├── runtime.py         # Serves a model (llama.cpp / mlx_lm / mlx-vlm)
+├── voice/             # Voice models: registry, import, TTS/STT runtime
+├── cli/              # Typer CLI package, one module per command group (entry: `stabbur` → stabbur.cli:main)
+├── app.py             # FastAPI app factory
+├── routers/           # health + catalog (browse/pull) + serving (load/chat/audio) endpoints
+└── sources/           # huggingface / ollama / lmstudio adapters
+```
+
+## Setup
+
+```bash
+uv sync                       # stabbur itself (needs Python 3.13 + uv)
+brew install llama.cpp        # baseline runtime: GGUF chat + OuteTTS speech (build from source on Linux)
+make install-mlx              # optional: MLX runtimes (Apple Silicon)
+uv sync --extra voice         # optional: mlx-audio runtimes (Dia/Whisper, Apple Silicon)
+make frontend                 # optional: build the web UI (needs Bun)
+export STABBUR_LIBRARY_ROOT=/path/to/your/library   # required: where your library lives
+stabbur doctor                   # verify what's installed
+```
+
+**Point stabbur at a library.** stabbur won't guess a location — set `STABBUR_LIBRARY_ROOT`
+(a per-machine shell/`.env` value; an external drive is the intended home). Without
+it, library commands fail with a clear message instead of silently using `./data`.
+
+**Install globally** (run `stabbur` from any directory):
+
+```bash
+uv tool install --editable ".[mlx,voice,web,benchmark]"   # from a checkout: stabbur on your PATH, code edits live
+uv tool install "git+https://github.com/winterop-com/stabbur" # or straight from git (requires repo access; core CLI)
+# then put STABBUR_LIBRARY_ROOT in your shell profile (~/.zshrc) so it applies everywhere
+```
+
+Only `uv sync` + llama.cpp are needed to run GGUF models; the rest are optional.
+The `benchmark` extra adds the `stabbur benchmark` eval command; drop it if you don't need it.
+See [getting started](docs/getting-started.md) for details.
+
+stabbur is installed **from source** (`uv sync` / `uv tool install -e .`), not from PyPI. It builds
+as a single self-contained wheel — the bundled first-party MCP servers are vendored into the `stabbur`
+package (`src/stabbur/mcp_servers/*`) rather than published as separate packages — but stabbur is
+proprietary/source-available and is not distributed on PyPI.
+
+## CLI
+
+```bash
+stabbur library ls                     # your library (the models on your drive)
+stabbur library sources                # models in app caches (HF/Ollama/LM Studio) you could pull
+stabbur library pull lmstudio lmstudio-community/gemma-4-12B-it-QAT-GGUF
+stabbur library pull ollama gemma4:31b --move   # copy to the library, then delete the local copy
+stabbur doctor                         # pre-flight: runtimes, library, project
+stabbur serve --ui                     # browse + chat in the browser (Chat · Voice · Library)
+stabbur chat gemma-4-12B-it-QAT-GGUF -p "hi"             # one-shot, scriptable
+stabbur chat gemma-4-12B-it-QAT-GGUF -p "?" -i pic.jpg   # image input (vision model)
+stabbur voice ls                       # voice models (TTS/STT) in the library
+stabbur voice import --all             # import known voice models to the library
+stabbur voice speak -v af_heart "hello there"           # text-to-speech (Kokoro)
+stabbur voice speak --model dia --seed 10 "hi there"    # Dia (pin a seed for a stable voice)
+stabbur project init                   # scaffold a project assistant (model + tools + prompt)
+```
+
+**Two model families:** **Chat** (language models you talk to — text in/out; some
+also read images/audio or call tools) and **Voice** (TTS speaks, STT transcribes).
+stabbur detects each chat model's capabilities and runs the right runtime — GGUF via
+llama.cpp (`llama-server`, `--mmproj` for vision/audio), MLX via `mlx_lm`/`mlx-vlm`.
+The web UI's **Library** lists both families; the **Voice** studio does TTS/STT
+(Kokoro, Dia with voice cloning, Whisper); in chat you can attach images/audio,
+dictate with the mic (Whisper), and **read replies aloud** (Kokoro by default). See
+the [voice guide](docs/guides/voice.md).
+
+Full docs: **[`docs/`](docs/)** (run `make docs` to serve the site locally) —
+getting started, the library, pulling, running & chatting, the web UI, the Chrome side panel,
+the DHIS2 assistant, and the architecture.
+
+## API
+
+`stabbur serve` exposes an OpenAI-compatible surface plus browse/voice endpoints:
+`/api/status`, `/api/library`, `/api/voice`, `/api/chat` (tool-aware SSE),
+`/v1/*` (proxied to the loaded model), and `/v1/audio/speech` +
+`/v1/audio/transcriptions`. See the [web UI guide](docs/guides/web-ui.md) for the
+full endpoint table and the single-origin proxy design.
+
+## Chrome side panel & the DHIS2 assistant
+
+stabbur ships an **MV3 Chrome side panel** (`extension/`, built with WXT) — a thin client for
+a local or remote `stabbur serve` that puts your own model + tools next to any page. It builds
+in two flavors from one codebase: the generic **stabbur** panel and **stabbur for DHIS2**
+(`STABBUR_FLAVOR=dhis2`).
+
+Pointed at a DHIS2 project (`stabbur project new --template dhis2`), it becomes the north-star
+assistant: chat grounded in the page you are viewing, a target banner (verify + tab
+match/mismatch), and **"Use my login"** — mint a read-only, GET-scoped Personal Access Token
+in the DHIS2 tab's own security context and hand it to stabbur once, so the tools act as *you*
+(with a session-cookie fallback). Everything runs against your own local model; nothing
+leaves the box.
+
+```bash
+cd extension && bun install && bun run build          # -> extension/.output/chrome-mv3(-dhis2)
+# chrome://extensions -> Load unpacked -> the built dir; then `stabbur serve` and open the panel
+```
+
+See the [Chrome side panel guide](docs/guides/extension.md) and
+the [verified prompt catalog](docs/guides/extension-prompts.md).
+
+## Configuration
+
+Two separate concepts:
+
+- **The library location** — where your models live. Set **`STABBUR_LIBRARY_ROOT`** (a
+  per-machine value; shell profile or `.env`). stabbur **requires** it — without one,
+  library/chat/serve commands fail with a clear message rather than silently using a
+  local folder. An external drive is the intended home:
+
+  ```bash
+  export STABBUR_LIBRARY_ROOT=/path/to/your/library     # e.g. a mounted external drive
+  ```
+
+- **A project** (`stabbur.toml`, via `stabbur project init` / `stabbur project new <dir>`) — a
+  purpose-built **assistant**: `[project].model` + `system_prompt`, with tools in a sibling
+  `.mcp.json` (standard `mcpServers`). In a project, `stabbur serve` / `stabbur chat` bind to that
+  model (like `--model`, with its tools + prompt); **outside** a project it's free-play
+  (pick/switch any model). A project uses the machine library by default.
+
+Precedence (high → low): CLI flags, `STABBUR_*` env vars, `stabbur.toml`, `.env`,
+`~/.config/stabbur/config.toml` (machine defaults).
+
+| Key / env var                                 | Purpose                             |
+| --------------------------------------------- | ----------------------------------- |
+| `STABBUR_LIBRARY_ROOT` (or `library_root`)       | the library location (**required**) |
+| `STABBUR_OLLAMA_MODELS_DIR`, `STABBUR_LMSTUDIO_MODELS_DIR` | source caches to pull from    |
+| `STABBUR_HF_TOKEN`                               | HF token (uses your HF login if unset) |
+| `STABBUR_DEFAULT_MAX_TOKENS` (or `default_max_tokens`) | per-turn `/api/chat` generation cap (default 4096; `0` = unbounded) |
+
+## Develop
+
+```bash
+make lint    # ruff format + check, mypy, pyright (mutates)
+make check   # same, read-only (CI gate) + tests
+make test    # pytest
+make build   # uv build (wheel + sdist)
+```

stabbur-0.6.0/README.md

@@ -0,0 +1,184 @@
+<!-- Absolute URLs: this README is the PyPI long description, and PyPI does not rewrite
+     relative paths - a repo-relative src renders as a broken image on the project page. -->
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/winterop-com/stabbur/main/docs/assets/logo.png" alt="stabbur" width="200">
+
+# stabbur
+
+[![CI](https://github.com/winterop-com/stabbur/actions/workflows/ci.yml/badge.svg)](https://github.com/winterop-com/stabbur/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/stabbur)](https://pypi.org/project/stabbur/)
+[![Python](https://img.shields.io/badge/python-3.13-3776ab)](https://www.python.org/)
+[![Packaging](https://img.shields.io/badge/install-uv-6340ac)](https://docs.astral.sh/uv/)
+[![License](https://img.shields.io/badge/license-proprietary-lightgrey)](https://github.com/winterop-com/stabbur/blob/main/LICENSE)
+
+</div>
+
+A tool for building and keeping a **full local library of LLM models**. It
+discovers models from **Hugging Face**, **Ollama**, and **LM Studio**, pulls
+them into a single library (browse via a **Typer CLI** or a **browser chat UI**),
+and runs them from there. The library lives under one configurable root you point
+at an external drive (e.g. a 5TB drive).
+
+**Short form.** Every command is also available as `sb` — `sb chat`, `sb serve`, `sb library ls`.
+
+**The name.** A *stabbur* is the Norwegian storehouse — raised on pillars, off the ground and
+out of the damp, where a household kept what it had gathered and wanted to keep. That is what this
+is: your models, pulled in from wherever they came from and kept somewhere of your own, on your own
+box, rather than in someone else's cloud.
+
+> **Proprietary, source-available.** stabbur is not open-source. Copyright (c) 2026 Morten
+> Hansen, all rights reserved (see [`LICENSE`](LICENSE)). The source is published for
+> reference and evaluation; running it requires a written license — contact
+> <morten@winterop.com>. Install is from source with `uv` (there is no `pip install stabbur`).
+
+![stabbur web UI](https://raw.githubusercontent.com/winterop-com/stabbur/main/docs/assets/web-ui.png)
+
+## Layout
+
+```
+src/stabbur/
+├── config.py          # Pydantic settings (STABBUR_* env vars)
+├── models.py          # Catalog / entry / result models
+├── catalog.py         # Aggregates listing + pull across sources
+├── library.py         # Scans the on-drive library (gguf/ mlx/ voice/ ...)
+├── capabilities.py    # Detects per-model tools/vision/audio + context
+├── runtime.py         # Serves a model (llama.cpp / mlx_lm / mlx-vlm)
+├── voice/             # Voice models: registry, import, TTS/STT runtime
+├── cli/              # Typer CLI package, one module per command group (entry: `stabbur` → stabbur.cli:main)
+├── app.py             # FastAPI app factory
+├── routers/           # health + catalog (browse/pull) + serving (load/chat/audio) endpoints
+└── sources/           # huggingface / ollama / lmstudio adapters
+```
+
+## Setup
+
+```bash
+uv sync                       # stabbur itself (needs Python 3.13 + uv)
+brew install llama.cpp        # baseline runtime: GGUF chat + OuteTTS speech (build from source on Linux)
+make install-mlx              # optional: MLX runtimes (Apple Silicon)
+uv sync --extra voice         # optional: mlx-audio runtimes (Dia/Whisper, Apple Silicon)
+make frontend                 # optional: build the web UI (needs Bun)
+export STABBUR_LIBRARY_ROOT=/path/to/your/library   # required: where your library lives
+stabbur doctor                   # verify what's installed
+```
+
+**Point stabbur at a library.** stabbur won't guess a location — set `STABBUR_LIBRARY_ROOT`
+(a per-machine shell/`.env` value; an external drive is the intended home). Without
+it, library commands fail with a clear message instead of silently using `./data`.
+
+**Install globally** (run `stabbur` from any directory):
+
+```bash
+uv tool install --editable ".[mlx,voice,web,benchmark]"   # from a checkout: stabbur on your PATH, code edits live
+uv tool install "git+https://github.com/winterop-com/stabbur" # or straight from git (requires repo access; core CLI)
+# then put STABBUR_LIBRARY_ROOT in your shell profile (~/.zshrc) so it applies everywhere
+```
+
+Only `uv sync` + llama.cpp are needed to run GGUF models; the rest are optional.
+The `benchmark` extra adds the `stabbur benchmark` eval command; drop it if you don't need it.
+See [getting started](docs/getting-started.md) for details.
+
+stabbur is installed **from source** (`uv sync` / `uv tool install -e .`), not from PyPI. It builds
+as a single self-contained wheel — the bundled first-party MCP servers are vendored into the `stabbur`
+package (`src/stabbur/mcp_servers/*`) rather than published as separate packages — but stabbur is
+proprietary/source-available and is not distributed on PyPI.
+
+## CLI
+
+```bash
+stabbur library ls                     # your library (the models on your drive)
+stabbur library sources                # models in app caches (HF/Ollama/LM Studio) you could pull
+stabbur library pull lmstudio lmstudio-community/gemma-4-12B-it-QAT-GGUF
+stabbur library pull ollama gemma4:31b --move   # copy to the library, then delete the local copy
+stabbur doctor                         # pre-flight: runtimes, library, project
+stabbur serve --ui                     # browse + chat in the browser (Chat · Voice · Library)
+stabbur chat gemma-4-12B-it-QAT-GGUF -p "hi"             # one-shot, scriptable
+stabbur chat gemma-4-12B-it-QAT-GGUF -p "?" -i pic.jpg   # image input (vision model)
+stabbur voice ls                       # voice models (TTS/STT) in the library
+stabbur voice import --all             # import known voice models to the library
+stabbur voice speak -v af_heart "hello there"           # text-to-speech (Kokoro)
+stabbur voice speak --model dia --seed 10 "hi there"    # Dia (pin a seed for a stable voice)
+stabbur project init                   # scaffold a project assistant (model + tools + prompt)
+```
+
+**Two model families:** **Chat** (language models you talk to — text in/out; some
+also read images/audio or call tools) and **Voice** (TTS speaks, STT transcribes).
+stabbur detects each chat model's capabilities and runs the right runtime — GGUF via
+llama.cpp (`llama-server`, `--mmproj` for vision/audio), MLX via `mlx_lm`/`mlx-vlm`.
+The web UI's **Library** lists both families; the **Voice** studio does TTS/STT
+(Kokoro, Dia with voice cloning, Whisper); in chat you can attach images/audio,
+dictate with the mic (Whisper), and **read replies aloud** (Kokoro by default). See
+the [voice guide](docs/guides/voice.md).
+
+Full docs: **[`docs/`](docs/)** (run `make docs` to serve the site locally) —
+getting started, the library, pulling, running & chatting, the web UI, the Chrome side panel,
+the DHIS2 assistant, and the architecture.
+
+## API
+
+`stabbur serve` exposes an OpenAI-compatible surface plus browse/voice endpoints:
+`/api/status`, `/api/library`, `/api/voice`, `/api/chat` (tool-aware SSE),
+`/v1/*` (proxied to the loaded model), and `/v1/audio/speech` +
+`/v1/audio/transcriptions`. See the [web UI guide](docs/guides/web-ui.md) for the
+full endpoint table and the single-origin proxy design.
+
+## Chrome side panel & the DHIS2 assistant
+
+stabbur ships an **MV3 Chrome side panel** (`extension/`, built with WXT) — a thin client for
+a local or remote `stabbur serve` that puts your own model + tools next to any page. It builds
+in two flavors from one codebase: the generic **stabbur** panel and **stabbur for DHIS2**
+(`STABBUR_FLAVOR=dhis2`).
+
+Pointed at a DHIS2 project (`stabbur project new --template dhis2`), it becomes the north-star
+assistant: chat grounded in the page you are viewing, a target banner (verify + tab
+match/mismatch), and **"Use my login"** — mint a read-only, GET-scoped Personal Access Token
+in the DHIS2 tab's own security context and hand it to stabbur once, so the tools act as *you*
+(with a session-cookie fallback). Everything runs against your own local model; nothing
+leaves the box.
+
+```bash
+cd extension && bun install && bun run build          # -> extension/.output/chrome-mv3(-dhis2)
+# chrome://extensions -> Load unpacked -> the built dir; then `stabbur serve` and open the panel
+```
+
+See the [Chrome side panel guide](docs/guides/extension.md) and
+the [verified prompt catalog](docs/guides/extension-prompts.md).
+
+## Configuration
+
+Two separate concepts:
+
+- **The library location** — where your models live. Set **`STABBUR_LIBRARY_ROOT`** (a
+  per-machine value; shell profile or `.env`). stabbur **requires** it — without one,
+  library/chat/serve commands fail with a clear message rather than silently using a
+  local folder. An external drive is the intended home:
+
+  ```bash
+  export STABBUR_LIBRARY_ROOT=/path/to/your/library     # e.g. a mounted external drive
+  ```
+
+- **A project** (`stabbur.toml`, via `stabbur project init` / `stabbur project new <dir>`) — a
+  purpose-built **assistant**: `[project].model` + `system_prompt`, with tools in a sibling
+  `.mcp.json` (standard `mcpServers`). In a project, `stabbur serve` / `stabbur chat` bind to that
+  model (like `--model`, with its tools + prompt); **outside** a project it's free-play
+  (pick/switch any model). A project uses the machine library by default.
+
+Precedence (high → low): CLI flags, `STABBUR_*` env vars, `stabbur.toml`, `.env`,
+`~/.config/stabbur/config.toml` (machine defaults).
+
+| Key / env var                                 | Purpose                             |
+| --------------------------------------------- | ----------------------------------- |
+| `STABBUR_LIBRARY_ROOT` (or `library_root`)       | the library location (**required**) |
+| `STABBUR_OLLAMA_MODELS_DIR`, `STABBUR_LMSTUDIO_MODELS_DIR` | source caches to pull from    |
+| `STABBUR_HF_TOKEN`                               | HF token (uses your HF login if unset) |
+| `STABBUR_DEFAULT_MAX_TOKENS` (or `default_max_tokens`) | per-turn `/api/chat` generation cap (default 4096; `0` = unbounded) |
+
+## Develop
+
+```bash
+make lint    # ruff format + check, mypy, pyright (mutates)
+make check   # same, read-only (CI gate) + tests
+make test    # pytest
+make build   # uv build (wheel + sdist)
+```