pi-lemonade-link 1.1.0 → 2.0.0

package/README.md

@@ -10,16 +10,19 @@ No hardcoded endpoints, no manual model lists. One extension, five capabilities:
 1. **Live model discovery** — every chat model your lemonade box advertises shows
    up in `/model` automatically, annotated with whether it's loaded right now.
 2. **Nine agent tools** — transcription, image generation/editing/upscaling,
-   text-to-speech, music/SFX, 3D meshes, and text classification, all callable
+   text-to-speech (incl. voice cloning + voice design), music/SFX, 3D meshes,
+   and text classification (fixed-label + zero-shot), all callable
    by the LLM, all model-aware.
 3. **A setup menu** — `/lemonade-setup` opens a navigable TUI for status,
-   discovery, configuration, model management (live-progress pulls, Hugging
-   Face installs), and live log streaming.
+   discovery, configuration, a live model browser (inline status, type-to-
+   search, contextual actions, animated busy markers with Esc-to-detach),
+   download-job management, recipe-backend installs, model updates, Hugging
+   Face installs, and live log streaming.
 4. **A lemonade status bar** — while a lemonade model is active, an extra
    below-editor row appears (your footer is never touched): instance name,
    tok/s and prefix-cache hit % derived locally from the session's own
-   messages, plus polled busy/queue, CPU/GPU/NPU and VRAM from the active
-   instance.
+   messages, plus polled busy/queue, whole-box active requests + live tok/s,
+   CPU/GPU/NPU and VRAM from the active instance.
    Switching to a non-lemonade model removes the row.
 5. **Harness self-awareness** — every chat, including virgin ones, is told
    where its lemonade machinery lives, so the agent can operate it directly.
@@ -186,7 +189,7 @@ Per tool:
 | `upscale_image` | Image → 4x PNG | arg → `defaultUpscaleModel` (RealESRGAN-x4plus) | PNG on disk + path | needs an upscale model pulled on the server; `-anime` variant exists for art. Sends the image as base64 JSON, not multipart |
 | `text_to_speech` | Text → spoken audio | arg → first model labeled `tts` (OpenMOSS-TTS on current builds) | mp3/wav on disk + path | if the TTS model isn't pulled, the request can trigger a slow auto-pull that outlasts the request — pull it via the setup menu first. `voice`/`speed`/`response_format` supported |
 | `generate_audio` | Prompt → music / SFX | arg → first model labeled `music`/`sfx`/`audio` | wav on disk + path | ACE-Step for music (optional `lyrics` with `[verse]`/`[chorus]` tags = sung vocals; omit = instrumental), ThinkSound for SFX. Not downloaded by default — pull first |
-| `classify_text` | Text → ranked label confidences | arg → `defaultClassifierModel` → first catalog model with the `onnxruntime` recipe | inline text readout | encoder classifiers (phishing, PII, prompt-injection...) — millisecond inference in its own classification slot; scores returned highest-first, so the top line is the verdict. Pull classifiers via the setup menu or HF install |
+| `classify_text` | Text → ranked label confidences | arg → `defaultClassifierModel` → first catalog model with the `onnxruntime` recipe (or a `zero-shot` decision model when `labels` is passed) | inline text readout | fixed-label encoder classifiers (phishing, PII, prompt-injection — their label set is baked in) and zero-shot decision models (labels sent per request); scores returned highest-first, so the top line is the verdict. Pull classifiers via the setup menu or HF install |
 | `generate_3d_model` | Image → textured `.glb` | arg → first model labeled `3d` (TRELLIS-3D) | .glb on disk + path | minutes per mesh; `resolution` 512/1024/1536; needs TRELLIS pulled. TUI cannot render it — open the file in a 3D viewer |
 
 **How `classify_text` handles multiple classifiers and modalities.** Each
@@ -278,8 +281,9 @@ and the normal menu takes over once the first instance exists.
 | Menu | What you can do |
 |---|---|
 | **Server status** | The complete state of the box, grouped by the endpoint each metric came from — every server metric flat on one **live** panel that re-fetches every `statusPollMs` (default 2 s) while open, with each snapshot timestamped in the header; a transient fetch failure keeps the last good snapshot. Scrollable (wrap-aware `↑↓/j/k/pgup/pgdn/home/end` scrolling + mouse wheel, `q`/`esc`/`enter` return; position indicator in the footer). With multiple instances configured, `n`/`p` cycles between boxes without leaving the view — the title names the instance shown, and the menu's active instance follows it on exit. Sections: `/v1/health` (loaded models with busy/streaming/backend-health/pid/slot-pool, per-type slot limits, pinned counts, telemetry state), `/v1/system-stats` (CPU/RAM used-total-%, GPU, VRAM, NPU), `/v1/stats` (last-request tok/s, TTFT, in/out tokens, prefix-cache hit rate, lifetime token/request counters, routing decisions), `/v1/system-info` (CPU cores/threads, OS, GPU/NPU inventory incl. NPU power mode and TOPS, model-storage drive usage), and `/metrics` (llama.cpp backend: request queue depth, busy slots per decode, peak sequence length). Each section degrades to an "(unreachable)" line independently — one dead endpoint never blanks the panel |
-| **Server settings** | Discover servers (UDP beacon + HTTP fallback), edit base URL, edit API key, test connection |
-| **Model management** | List catalog (including not-yet-downloaded registry entries), load / unload, pull (download) with live progress + esc-to-cancel, install from Hugging Face (search → pick variant → install as `user.*`), delete, change context size (unload → reload with `ctx_size`, saved), toggle chat-only filter, refresh provider |
+| **Server settings** | Discover servers (UDP beacon + HTTP fallback), edit base URL, edit API key, edit admin key (for `/internal/*`: pin, bulk model sync), test connection |
+| **Model management** | **Model browser**: one live list of every model — downloaded or not — with inline status (`●` loaded · `○` downloaded · `◌` not on disk · `↓` downloading % · `⤴` update available · `★` featured); **type to search** (substring over name + description, `⌫` edits, `esc` clears the filter first), `ctrl+t` toggles all ⇄ downloaded-only, and the list refreshes underneath you every ~2 s. Selecting a model opens its **contextual actions**: view details (checkpoints, launch command, load state), load (animated busy marker with live server-side load status, `esc` continues in background), unload, pin/unpin, pull / update (live progress + esc-cancel), recipe-options editor, delete (typed phrase). Plus: **Downloads** (server-owned job list — live, cancel/pause/remove/retry, bulk-clear stopped jobs; terminal jobs are auto-removed so they never linger), **Install from Hugging Face** (search → pick variant → install as `user.*`), **Check for model updates** (report, then bulk sync via the admin key or update one-by-one with plain pulls), chat-only filter toggle, refresh provider |
+| **Backends** | The recipe × backend inventory from system-info (installed / installable / unsupported, tier, version) — install with dry-run preview + live download progress, uninstall, `ctrl`-free type-to-search across every recipe:backend. Guest-tier note: models whose recipe has only guest backends stay hidden from the catalog until one is installed |
 | **Transcription settings** | Default Whisper model, endpoint path, smoke-test a file |
 | **Live server logs** | WebSocket stream of the server's log: full snapshot backlog (up to 5000 entries) then live entries as they happen; Esc to close |
 | **Spec & version check** | The three drift tiers, interactive: docs-vs-upstream status (TUI-only), live per-instance server versions beside the verified build and the latest upstream release, re-check now, one-keystroke docs re-sync (re-downloads upstream docs into the extension's docs/ folder — the code is not updated), `specCheck` / `serverVersionCheck` / `upstreamVersionCheck` toggles |
@@ -289,9 +293,14 @@ Notes on the destructive and slow paths:
 - **Delete** requires two gates: a confirm dialog, then typing the exact phrase
   `i want to delete <model-id>` — three attempts allowed, each prompt shows
   chances remaining, and Esc aborts immediately.
-- **Change context size** prefills the model's *current* context (from live
-  health), accepts `32k`, `1m`, or raw token counts, and warns that the model
-  is unloaded and reloaded (the new `ctx_size` is saved for future loads).
+- **Change context size / recipe options** is a per-model editor over
+  `GET/POST/DELETE /v1/models/{id}/options`: every option key with its
+  saved/effective/default values side by side; edits save immediately
+  (merge — untouched keys keep their values; empty/`auto` clears a key,
+  `ctx_size: -1` = auto-size, backend keys get a menu of what this system
+  supports), and a loaded model is offered a reload to apply. Works on
+  unloaded models too — the options take effect at the next load. The old
+  unload → reload-with-ctx hack is retired; this is strictly more capable.
 - **Pull** uses lemonade's server-owned download jobs: a live progress view
   (percent, bytes, per-file status, updated every second) with **Esc to cancel**
   (via `/v1/downloads/control`). Blocking pull is kept only as a fallback for
@@ -402,17 +411,18 @@ The full shape (values shown are the built-in defaults):
 |---|---|
 | `servers` | **Required** — the only instance store: `[{ "name", "baseUrl", "apiKey"?, "description"? }]`. May be empty on a fresh install (the first `/lemonade-setup` run offers a wizard); the FIRST entry is the default instance (targeted when tools' `server` argument is omitted); reordering changes the default. Each registers as a `lemonade-<name>` provider. |
 | `apiKey` | Shared fallback `Authorization: Bearer …` for instances without their own. A dummy value works for auth-less servers (pi requires non-empty auth to list models). |
-| `*Path` | API endpoint paths, in case a future lemonade changes them. |
+| `adminApiKey` | Key for `/internal/*` endpoints (pin/unpin, bulk model sync) on servers that set `LEMONADE_ADMIN_API_KEY`. Empty = fall back to `apiKey`. Per-instance override lives on the server entry, same fallback chain. |
+| `*Path` | API endpoint paths, in case a future lemonade changes them (incl. `modelOptionsPath` with its `{id}` placeholder). |
 | `chatOnly` | Filter the provider down to chat-capable models. |
 | `cacheOnOutage` | **Outage cache**: when a probe can't reach an instance, `/model` lists its last good catalog — persisted on every successful probe, provenance-marked `(cached <time>)`, warned at session start, and re-synced automatically (prompt submits, model selections, session starts, plus the status bar's own health poll) with a `+new −gone` diff notice once the box answers. Once an instance is known down (durable flag from the last failed probe), the next startup serves the cached listing **instantly — no probe wait** and reconciles in the background, so the down-box stall only ever bites once per outage, at the transition into it. `false` (default) keeps the fully-honest empty listing. Manage via `/lemonade-setup` → *Catalog cache*; force a re-probe with *Refresh connection*. |
-| `defaultTranscriptionModel` / `defaultImageModel` / `defaultUpscaleModel` / `defaultClassifierModel` | Fixed model ids for the tools. Empty = auto-pick from the live catalog (by label, or by `onnxruntime` recipe for classifiers). |
+| `defaultTranscriptionModel` / `defaultImageModel` / `defaultUpscaleModel` / `defaultClassifierModel` | Fixed model ids for the tools. Empty = auto-pick from the live catalog (by label; classifiers prefer `onnxruntime` encoders, or `zero-shot`-labeled decision models when `labels` is passed). |
 | `outputDir` | Where generated files (images, audio, meshes) are saved. Empty = agent's working directory. |
 | `*TimeoutMs` | Per-operation timeouts. `pullTimeoutMs` only caps the *blocking* pull fallback — normal pulls use download jobs with live progress. |
 | `statusPollMs` | How often the setup-menu status panel re-fetches while open (live refresh). `0` = static snapshot. |
 | `statusBar` | Show the below-editor lemonade status bar while a lemonade model is active (see *Lemonade status bar*). |
 | `barPollMs` | Server-poll cadence for the status bar's busy/queue + CPU/GPU/NPU/VRAM segments. `0` = local metrics only (instance, tok/s, cache-hit %). |
 | `specCheck` / `specCheckCooldownMs` / `specCheckTimeoutMs` | Docs-freshness check: the `docs/` snapshot is compared against upstream `lemonade-sdk/lemonade` by git blob SHA — **TUI-only status, no startup warning** (extension ↔ server agreement is what matters; see *Keeping the specs honest*); the verdict is durable for `specCheckCooldownMs` (default 24 h, also the upstream-release probe's throttle). |
-| `serverVersionCheck` | **Tier 1, startup warning**: `/v1/health` self-reports the server version; any instance reporting a version other than the build this extension was verified against (`v11.7.0` — a constant in the extension code, not a setting) warns **with direction**: server newer → check for an extension update; server older → update the server. |
+| `serverVersionCheck` | **Tier 1, startup warning**: `/v1/health` self-reports the server version; any instance reporting a version other than the build this extension was verified against (`v2026.46.2` — a constant in the extension code, not a setting; dev builds like `2026.46.2~1719.034d3f52` count as their release) warns **with direction**: server newer → check for an extension update; server older → update the server. |
 | `upstreamVersionCheck` | **Tier 2, info notice**: servers older than the latest published lemonade release (probed via GitHub, throttled) get a one-line "a server update is available" notice — **deduplicated to once per (instance, release)**, so it never re-fires on every session for the same release; the TUI always shows current state. Default on; separately toggleable. |
 
 ## Offline & unreachable networks
@@ -545,6 +555,8 @@ uses:
 | [`docs/README.md`](./docs/README.md) | Spec index and design philosophy |
 | [`docs/openai.md`](./docs/openai.md) | OpenAI-compatible surface: chat/completions, embeddings, audio (transcription, speech, generations), images (generation/edit/variation/upscale), realtime, `/v1/models` + labels taxonomy |
 | [`docs/lemonade.md`](./docs/lemonade.md) | Lemonade-specific surface: load/unload/pull/delete, download jobs + control, registry search + pull variants, health/stats/system-stats/system-info, classify, audio/3D generation, log streaming, job engine, install/uninstall |
+| [`docs/router.md`](./docs/router.md) | Router API: `collection.router` models and routing policies |
+| [`docs/internal.md`](./docs/internal.md) | Internal API: aliases, model sync, telemetry — used by the desktop app; versioned separately from the public surface |
 | [`docs/mcp.md`](./docs/mcp.md) | The MCP gateway (lemonade as an MCP server) |
 | [`docs/ollama.md`](./docs/ollama.md), [`docs/anthropic.md`](./docs/anthropic.md), [`docs/llamacpp.md`](./docs/llamacpp.md) | Other compatibility surfaces (rerank, slots, etc.) |
 
@@ -562,7 +574,7 @@ Drift is watched **in tiers, ordered by what actually matters at runtime**:
 
 1. **Extension ↔ server sync (startup warning).** Every registration and
    refresh compares each instance's live `/v1/health` version against the
-   build this extension was verified against (`v11.7.0` — a constant in the
+   build this extension was verified against (`v2026.46.2` — a constant in the
    extension code, **not a user setting**: it is a property of the code,
    updated with each extension release). A mismatch is the one signal that
    means *endpoints may have changed for this pairing*, so it warns —
@@ -573,7 +585,7 @@ Drift is watched **in tiers, ordered by what actually matters at runtime**:
    default, separately toggleable).** The latest published lemonade release
    is probed via GitHub (throttled, durable, silent on network failure); any
    server older than it gets a single info line — *"instance 'x' runs
-   lemonade v11.7.0; the latest published release is v11.9.0 — a server
+   lemonade v2026.44.1; the latest published release is v2026.46.2 — a server
    update is available."* Much lower tier: an older server isn't broken,
    it's just behind. The notice is **deduplicated to once per (instance,
    release)** — it fires when a new upstream release first appears, never
@@ -599,7 +611,7 @@ release.
 ## Extension version & provider API
 
 This extension's version (`version` in `package.json`) and the lemonade
-server build it was verified against (`11.7.0`) are recorded together in
+server build it was verified against (`2026.46.2`) are recorded together in
 the `provider` block of `package.json` and in the
 `EXTENSION_CONFIRMED_SERVER_VERSION` constant in `index.ts` (which drives
 the startup version-drift warning). The server status panel and the
@@ -623,8 +635,10 @@ and server-version checks (see *Keeping the specs honest*) are what catch
 
 ## Lemonade behavior reference
 
-Empirically confirmed against lemonade 11.7.0 (cross-checked with the
-[official endpoint spec](https://lemonade-server.ai/docs/api/)):
+Empirically confirmed against lemonade 2026.46.2 (cross-checked with the
+[official endpoint spec](https://lemonade-server.ai/docs/api/) — which the
+server now also serves itself at `GET /v1/docs`, so the running build's
+reference is always one curl away):
 
 - **Auto-loading.** A request for an unloaded model triggers an automatic load
   attempt. If the model's slot is free or holds an unpinned model, lemonade
@@ -634,8 +648,27 @@ Empirically confirmed against lemonade 11.7.0 (cross-checked with the
 - **Per-type slots.** The server holds one slot per model type (llm,
   transcription, image, embedding, …), so Whisper can be loaded alongside your
   chat model.
-- **change-ctx.** Implemented as unload → reload with `ctx_size` +
-  `save_options: true`, which persists the choice for future loads.
+- **change-ctx & friends.** Per-model recipe options (ctx size, backend,
+  args, evict timeouts) are edited through `/v1/models/{id}/options` — saved
+  without loading, merged per key, applied to a loaded model by a plain
+  reload (`POST /v1/load` reloads a model whose load-time options changed).
+- **Pinning.** `POST /internal/pin` flips a loaded model's pinned flag in
+  place (no reload); it demands `LEMONADE_ADMIN_API_KEY` when the server sets
+  one — configure `adminApiKey` or every pin attempt fails with an actionable
+  admin-key message.
+- **Model updates.** `POST /v1/models/check-updates` reports newer upstream
+  commits (plain key); updating is either a bulk `/internal/models/sync`
+  (admin key) or plain per-model re-pulls. Re-pulling a model with a stale
+  errored job RESUMES the job (status flips back to `downloading`) — verified
+  live.
+- **Download-job hygiene.** The server keeps errored/cancelled jobs in
+  `GET /v1/downloads` until a client removes them; this extension now removes
+  the ones it drove to a terminal outcome (and offers bulk-clear in the
+  Downloads view), so dead jobs no longer linger forever.
+- **Backends.** `GET /v1/system-info` reports the full recipe × backend matrix
+  (state: installed/installable/unsupported, tier, version, format);
+  `POST /v1/install` (+`/dry-run`) and `/v1/uninstall` manage them, and
+  installs flow through the same `/v1/downloads` job machinery as pulls.
 - **Status panel sources.** All five metric endpoints are live-confirmed:
   `/v1/health` (incl. per-model `is_busy`/`is_streaming`/`backend_health`/
   `slot_pool`/`residency_class`/`last_use`/`pid` and `pinned_models` counters),

package/docs/README.md

@@ -18,5 +18,28 @@ This spec details all supported endpoints. It is organized into pages that corre
 | [MCP Gateway](./mcp.md) | Use this to expose Lemonade as a Model Context Protocol server (POST /mcp). |
 | [llama.cpp-Specific API](./llamacpp.md) | Reference for llama.cpp-specific compatibility and conventions. |
 | [Lemonade-Specific API](./lemonade.md) | Local-first API for managing lifecycle, configuration, backends, etc. |
+| [Router API](./router.md) | How `collection.router` models route requests, and how to test a routing policy. |
+| [Internal API](./internal.md) | Control endpoints for clients bundled with the server, secured by `LEMONADE_ADMIN_API_KEY`. |
 
 A running server also serves these pages itself: [`GET /v1/docs`](./lemonade.md#get-v1docs) lists what it has and [`GET /v1/docs/{page}`](./lemonade.md#get-v1docspage) returns one, so the reference always matches the installed version and stays available offline.
+
+## Authentication
+
+When `LEMONADE_API_KEY` is set, clients send it in the `Authorization` header as a Bearer token:
+
+```bash
+curl http://localhost:13305/v1/models -H "Authorization: Bearer $LEMONADE_API_KEY"
+```
+
+Each route says whether it needs a key. The internal routes take `LEMONADE_ADMIN_API_KEY` when it is set, and `LEMONADE_API_KEY` otherwise; the admin key also works on every other route. Lemonade reads no other header, so an Anthropic SDK client passes the key as `auth_token`, not `api_key`. The WebSocket APIs take the key as an `api_key` query parameter instead. See [API Key and Security](../guide/configuration/README.md#api-key-and-security) for every combination of the two keys.
+
+## Errors
+
+Each route lists the errors it answers with in its Errors table. These come from the server before a request reaches a route, so no route lists them:
+
+| Status | Body | When |
+|--------|------|------|
+| `401` | `{"error": "Invalid or missing API key"}`, or `"Invalid or missing admin API key"` for an internal route | The request lacks the key its route needs |
+| `403` | `{"error": "Origin not allowed"}` | The `Origin` header names an origin that [`allowed_origins`](../guide/configuration/README.md) does not allow |
+| `404` | `{"error": {"message": "The requested endpoint does not exist", "type": "not_found", "path"}}` | No route matches the path |
+| `405` | `{"error": "Method Not Allowed. Use POST for this endpoint"}` | A `GET` reaches a `POST`-only route under `/v0/`, `/v1/`, `/api/v0/` or `/api/v1/` |

package/docs/anthropic.md

@@ -1,11 +1,188 @@
 # Anthropic-Compatible API
 
-Lemonade supports an initial Anthropic Messages compatibility endpoint for applications that call Claude-style APIs.
+Lemonade serves the Anthropic Messages API for applications that call Claude-style APIs.
 
-| Endpoint | Status | Notes |
-|----------|--------|-------|
-| `POST /v1/messages` | Supported | Supports both streaming and non-streaming. Query params like `?beta=true` are accepted. |
+<!-- BEGIN GENERATED: anthropic.summary -->
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | [`/v1/messages`](#post-v1messages) | Generate the next assistant message |
+<!-- END GENERATED: anthropic.summary -->
 
-Current scope focuses on message generation parity for common fields (`model`, `messages`, `system`, `max_tokens`, `temperature`, `stream`, and basic `tools`). Unsupported or unimplemented Anthropic-specific fields are ignored and surfaced via warning logs/headers.
+<!-- BEGIN GENERATED: anthropic.messages -->
+## `POST /v1/messages`
+<sub>![Status](https://img.shields.io/badge/status-partially_available-yellow)</sub>
 
-Those limits apply only where Lemonade converts to and from the OpenAI shape. A cloud provider registered with `--wire-format anthropic` is relayed unconverted, so no field is dropped — see [Cloud Offload](../guide/configuration/cloud.md#providers-that-speak-the-anthropic-messages-format).
+Generates the next assistant message for a conversation in the Anthropic Messages format.
+
+Requires `LEMONADE_API_KEY` when it is set.
+
+### Parameters
+
+| Parameter | Required | Description | Status |
+|-----------|----------|-------------|--------|
+| `model` | Yes | The model to run; loaded on first use. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `messages` | Yes | Conversation so far, as `user` and `assistant` messages. `content` is a string or an array of `text`, `image` (base64 source), `tool_use` and `tool_result` blocks. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `system` | No | System prompt, as a string or an array of `text` blocks. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `max_tokens` | No | Upper bound on generated tokens. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `temperature` | No | Sampling temperature. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `top_p` | No | Cumulative probability of the top tokens to consider during nucleus sampling, from `0.0` to `1.0`. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `top_k` | No | Number of top tokens to consider during sampling. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `stop_sequences` | No | Sequences where generation stops. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `stream` | No | `true` sends the response as server-sent events as it progresses; `false` sends one response once complete. Defaults to `false`. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `tools` | No | Tools the model may call, each with a `name`, `description` and `input_schema`. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `tool_choice` | No | `{"type": "auto"}`, `any`, `none`, or `tool` with a `name`. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `output_config` | No | `format` of type `json_schema` (with a `schema`) or `json_object` constrains the reply. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `thinking` | No | Not applied to local models: reasoning models think regardless. Qwen3 models skip their reasoning when the prompt ends with `/no_think`. | <sub>![Status](https://img.shields.io/badge/not_available-red)</sub> |
+| `metadata` | No | Ignored for local models, with a warning. | <sub>![Status](https://img.shields.io/badge/not_available-red)</sub> |
+| `context_management` | No | Ignored for local models, with a warning. | <sub>![Status](https://img.shields.io/badge/not_available-red)</sub> |
+| `ctx_size` | No | Lemonade extension: context size to load the model with, when this request loads it. Ignored when the model is already loaded. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `beta` (query) | No | Accepted for Anthropic SDK compatibility. Values other than `true` add a warning; `true` is passed on to providers that are relayed. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+
+Lemonade runs the request as an OpenAI chat completion and converts both ways. Some values it cannot convert, such as an unsupported content block type or `metadata`, are ignored and reported in the `X-Lemonade-Warning` header (joined with ` | `) and in a `warnings` array. Unknown fields are ignored without a warning. A cloud provider registered with `--wire-format anthropic` is relayed unconverted, so nothing is dropped; see [Cloud Offload](../guide/configuration/cloud.md#providers-that-speak-the-anthropic-messages-format).
+
+Errors use Anthropic's shape, `{"type": "error", "error": {"type", "message"}}`.
+
+### Examples
+
+#### Non-streaming
+
+=== "PowerShell"
+
+    ```powershell
+    Invoke-WebRequest `
+      -Uri "http://localhost:13305/v1/messages" `
+      -Method POST `
+      -Headers @{ "Content-Type" = "application/json" } `
+      -Body '{
+          "model": "Qwen3-0.6B-GGUF",
+          "max_tokens": 64,
+          "temperature": 0,
+          "messages": [{"role": "user", "content": "What is the capital of France? /no_think"}]
+        }'
+    ```
+
+=== "Bash"
+
+    ```bash
+    curl http://localhost:13305/v1/messages \
+      -H "Content-Type: application/json" \
+      -d '{
+          "model": "Qwen3-0.6B-GGUF",
+          "max_tokens": 64,
+          "temperature": 0,
+          "messages": [{"role": "user", "content": "What is the capital of France? /no_think"}]
+        }'
+    ```
+
+**Response:** `200 OK`
+
+```json
+{
+  "id": "chatcmpl-e1cbsIyQh8RNvDa8IFa7hUsiL7xxgEmv",
+  "type": "message",
+  "role": "assistant",
+  "model": "Qwen3-0.6B-GGUF",
+  "content": [{"type": "text", "text": "The capital of France is **Paris**."}],
+  "stop_reason": "end_turn",
+  "stop_sequence": null,
+  "usage": {"input_tokens": 19, "output_tokens": 14}
+}
+```
+
+#### Streaming
+
+=== "PowerShell"
+
+    ```powershell
+    Invoke-WebRequest `
+      -Uri "http://localhost:13305/v1/messages" `
+      -Method POST `
+      -Headers @{ "Content-Type" = "application/json" } `
+      -Body '{
+          "model": "Qwen3-0.6B-GGUF",
+          "max_tokens": 64,
+          "temperature": 0,
+          "messages": [{"role": "user", "content": "What is the capital of France? /no_think"}],
+          "stream": true
+        }'
+    ```
+
+=== "Bash"
+
+    ```bash
+    curl http://localhost:13305/v1/messages \
+      -H "Content-Type: application/json" \
+      -d '{
+          "model": "Qwen3-0.6B-GGUF",
+          "max_tokens": 64,
+          "temperature": 0,
+          "messages": [{"role": "user", "content": "What is the capital of France? /no_think"}],
+          "stream": true
+        }'
+    ```
+
+**Response:** `200 OK`
+
+```text
+event: message_start
+data: {"type": "message_start", "message": {"content": [], "id": "chatcmpl-VoeIi1EHhQg4HDI3S7ehBxKOoUCjX2DI", "model": "Qwen3-0.6B-GGUF", "role": "assistant", "stop_reason": null, "stop_sequence": null, "type": "message", "usage": {"input_tokens": 0, "output_tokens": 0}}}
+event: content_block_start
+data: {"type": "content_block_start", "index": 0, "content_block": {"text": "", "type": "text"}}
+event: content_block_delta
+data: {"type": "content_block_delta", "index": 0, "delta": {"text": "The", "type": "text_delta"}}
+...
+event: message_delta
+data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}, "usage": {"input_tokens": 0, "output_tokens": 0}}
+event: message_stop
+data: {"type": "message_stop"}
+```
+
+### Response format
+
+#### JSON
+
+- `id` - The message's ID.
+- `type` - Always `message`.
+- `role` - Always `assistant`.
+- `model` - The model that generated the message.
+- `content` - The message's content blocks.
+  - `type` - `text` or `tool_use`. A relayed provider can add its own block types, such as `thinking`.
+  - `text` - In a `text` block: the text.
+  - `id` - In a `tool_use` block: the tool call's ID.
+  - `name` - In a `tool_use` block: the tool's name.
+  - `input` - In a `tool_use` block: the call's arguments.
+- `stop_reason` - `end_turn`, `max_tokens` or `tool_use`.
+- `stop_sequence` - The stop sequence that ended the message; always `null` for local models.
+- `usage` - Token counts.
+  - `input_tokens` - Prompt tokens.
+  - `output_tokens` - Generated tokens.
+- `warnings` - What Lemonade ignored or changed while converting; present only when there is something to report.
+
+#### Event stream
+
+- `type` - Matches the event's name: `message_start`, `content_block_start`, `content_block_delta`, `content_block_stop`, `message_delta`, `message_stop` or `error`. A relayed provider can also send `ping`.
+- `message` - In `message_start`: the message, with empty `content` and zero `usage`.
+- `index` - In `content_block_start`, `content_block_delta` and `content_block_stop`: the block's position in the message's `content`.
+- `content_block` - In `content_block_start`: the block, with empty `text` or `input`.
+- `delta` - In `content_block_delta`: the block's next `text_delta` text or `input_json_delta` partial JSON. In `message_delta`: the `stop_reason` and `stop_sequence`.
+- `usage` - In `message_delta`: token counts. Both are `0` when the backend's stream carries no usage, as with llama.cpp.
+- `warnings` - In `message_delta`: what Lemonade ignored while converting; present only when there is something to report.
+- `error` - In `error`, sent when the backend or provider fails after the stream started: the error's `type` and `message`.
+
+### Errors
+
+| Status | Code | When |
+|--------|------|------|
+| `400` | `invalid_json` | The body is not a JSON object |
+| `400` | `missing_argument` | A required argument is missing |
+| `400` | `invalid_argument` | An argument or a value nested in it has the wrong JSON type, or a value its schema does not list |
+| `400` |  | `model` is a cloud model whose `--wire-format anthropic` provider has an `http://` base URL and was not installed with `--allow-insecure-http` |
+| `401` |  | `model` is a cloud model whose `--wire-format anthropic` provider has no API key |
+| `404` |  | `model` fails to load for any reason other than a residency conflict, such as naming no model or a failed download |
+| `409` | `router_residency_conflict` | Loading the requested model would evict a model that a `collection.router` model needs resident on the same NPU |
+| `500` |  | `model` is a cloud model whose `--wire-format anthropic` provider has no base URL |
+| `500` |  | `model` is a `--wire-format anthropic` cloud model with no `checkpoint` |
+| `500` |  | The backend reports an error; the backend's own status replaces this one when it sends one |
+| `500` |  | The request fails unexpectedly |
+| `502` |  | Without `stream`, the relayed cloud request fails or the provider answers with an error; the provider's own status and body replace this one when it answers |
+<!-- END GENERATED: anthropic.messages -->