Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust

refactor(cli): nuke legacy commands and launcher setup (#217)

nachiketb-nvidiaba72705b2eb8
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 64af8df44..d37e49106 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -224,7 +224,10 @@ jobs:
switchyard launch claude --help > /dev/null
uv run --isolated --no-project --python 3.12 \
--with "${SWITCHYARD_EXTRAS_PACKAGE}" \
- switchyard launch claude --help 2>&1 | grep -q -- '--routing-profiles' || { echo 'FAIL: --routing-profiles flag missing from help'; exit 1; }
+ switchyard launch claude --help 2>&1 | grep -q -- '--model' || { echo 'FAIL: --model flag missing from help'; exit 1; }
+ uv run --isolated --no-project --python 3.12 \
+ --with "${SWITCHYARD_EXTRAS_PACKAGE}" \
+ switchyard launch claude --help 2>&1 | grep -q -- '--config' || { echo 'FAIL: --config flag missing from help'; exit 1; }
uv run --isolated --no-project --python 3.12 \
--with "${SWITCHYARD_EXTRAS_PACKAGE}" \
switchyard serve --help > /dev/null
diff --git a/.github/workflows/perf.yml b/.github/workflows/perf.yml
index 8b988c57e..59524629f 100644
--- a/.github/workflows/perf.yml
+++ b/.github/workflows/perf.yml
@@ -141,7 +141,7 @@ jobs:
type: model
model: mock-model
YAML
- uv run switchyard --routing-profiles bench.yaml -- serve --port $PROXY_PORT &
+ uv run switchyard serve --routing-profiles bench.yaml --port $PROXY_PORT &
echo "PROXY_PID=$!" >> "$GITHUB_ENV"
- name: Wait for proxy to be ready
diff --git a/AGENTS.md b/AGENTS.md
index 4b5190309..4ce6f7e47 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -207,22 +207,16 @@ switchyard/
│ └── intake_sink_config.py
├── cli/ # CLI (requires `nemo-switchyard[cli]`)
│ ├── switchyard_cli.py # `switchyard` entry point
-│ ├── launch_command.py # `switchyard launch claude/codex`
-│ ├── configure_command.py # `switchyard configure`
-│ ├── status.py # render_status helper used by `configure --show`
+│ ├── launch_command.py # `switchyard launch`
│ ├── command_utils.py
-│ ├── output.py
-│ ├── launchers/ # claude_code_launcher, codex_cli_launcher
+│ ├── defaults/ # packaged OpenRouter TOML deployment
+│ ├── launchers/ # Claude, Codex, and OpenClaw launchers
│ ├── model_catalog/ # model_discovery
-│ ├── routing/ # route_builder
-│ ├── tui/ # Terminal UI widgets
-│ └── config/
-│ └── user_config.py # Saved user defaults (~/.config/switchyard/)
+│ └── route_bundle.py # YAML route parsing for `serve`
└── server/ # FastAPI app factory + server utilities
├── switchyard_app.py # build_switchyard_app()
├── server_util.py # Shared CLI / server plumbing
- ├── shell_tui.py # Shell TUI session
- └── verify.py # e2e verification helpers
+ └── shell_tui.py # Shell TUI session
tests/ # Unit tests (pytest)
```
@@ -255,26 +249,17 @@ and their transitives never appear in downstream vulnerability scans.
### Running the server
```bash
-export OPENAI_API_KEY="sk-..." # or NVIDIA_API_KEY / ANTHROPIC_API_KEY where supported
-export OPENROUTER_API_KEY="sk-or-..." # pass with --api-key or save via configure
+export OPENROUTER_API_KEY="sk-or-..."
# Serve a routing bundle. Routes live in YAML; see docs/routing_algorithms/overview.md.
-switchyard --routing-profiles routes.yaml -- serve --port 4000
-
-# One-command launchers — single-model passthrough via --model
-switchyard launch claude --model openai/gpt-4o-mini \
- --base-url https://openrouter.ai/api/v1 --api-key "$OPENROUTER_API_KEY"
-switchyard launch codex --model openai/gpt-4o-mini \
- --base-url https://openrouter.ai/api/v1 --api-key "$OPENROUTER_API_KEY"
-
-# Launchers default to built-in LLM-classifier routing; tune the tiers:
-switchyard launch claude \
- --weak-model openai/gpt-4o-mini --classifier-model openai/gpt-4o \
- --classifier-min-confidence 0.6
-
-# Verification and saved config
-switchyard verify --model openai/gpt-4o-mini
-switchyard configure --show
+switchyard serve --routing-profiles routes.yaml --port 4000
+
+# Launch against the packaged OpenRouter deployment.
+switchyard launch claude --model switchyard
+switchyard launch codex --model switchyard
+
+# Or select a route from a custom native TOML deployment.
+switchyard launch claude --model my-route --config routes.toml
```
### Testing
@@ -339,7 +324,7 @@ uvicorn.run(build_switchyard_app(switchyard), port=4000)
| `OPENAI_BASE_URL` | Base URL for OpenAI-compatible API |
| `ANTHROPIC_API_KEY` | API key for Anthropic Claude |
| `NVIDIA_API_KEY` | API key for NVIDIA NIM / Inference Hub |
-| `OPENROUTER_API_KEY` | OpenRouter key for examples and saved provider setup; pass via `--api-key` or `switchyard configure` |
+| `OPENROUTER_API_KEY` | OpenRouter key used by the packaged launcher deployment |
| `SWITCHYARD_INTAKE_CAPTURE_CONTENT` | Set truthy to include prompt/response text in intake; default off (metadata-only) |
## Code Style
diff --git a/README.md b/README.md
index 5069749f1..70178a336 100644
--- a/README.md
+++ b/README.md
@@ -26,106 +26,28 @@ algorithm you write yourself.
## Quick Start
-### Install prerequisites
-
-You need Git, a native build toolchain, and Rust with Cargo. On Ubuntu or WSL:
-
-```bash
-sudo apt-get update
-sudo apt-get install -y build-essential curl git
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-source "$HOME/.cargo/env"
-```
-
-The Rust installer includes `rustc`, Cargo, and `rustup`. On macOS or native
-Windows, follow the [official Rust installation instructions](https://rust-lang.org/tools/install/).
-
-Install `uv` for the repository's Python-based tooling and CI checks. It is not
-required to build or run the Rust server:
-
-```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
-```
-
-If either installer updates your shell configuration, restart the shell before
-continuing. Verify that the tools are available:
-
-```bash
-git --version
-rustc --version
-cargo --version
-uv --version
-```
-
-### Build the Rust server from source
+Install the CLI and server dependencies:
```bash
-git clone https://github.com/NVIDIA-NeMo/Switchyard.git
-cd Switchyard
-cargo build --locked --release -p switchyard-server
-./target/release/switchyard-server --help
-```
-
-The repository pins Rust `1.96.1` in `rust-toolchain.toml`; `rustup` selects and
-installs it automatically when you run Cargo from the repository. Prebuilt Rust
-binaries are not published yet.
-
-### Run the server
-
-The `switchyard-server` binary reads an explicit TOML configuration for LLM
-clients, targets, and routes. Create `routes.toml` with an LLM-classifier route:
-
-```toml
-schema_version = 1
-
-[llm_clients.openrouter]
-format = "openai_chat"
-base_url = "https://openrouter.ai/api/v1"
-api_key_env = "OPENROUTER_API_KEY"
-
-[targets.weak]
-id = "openai/gpt-4o-mini"
-llm_client = "openrouter"
-
-[targets.strong]
-id = "openai/gpt-4o"
-llm_client = "openrouter"
-
-[routes.smart]
-id = "switchyard"
-type = "llm_classifier"
-classifier_target = "weak"
-strong_target = "strong"
-weak_target = "weak"
-base_threshold = 0.5
+uv tool install "nemo-switchyard[cli,server]"
+export OPENROUTER_API_KEY="sk-or-..."
```
-The weak model classifies each request, then serves requests above the threshold
-itself and sends the rest to the strong model.
-
-Export the provider credential, validate the configuration without binding a
-socket, then start the server:
+Launch a coding agent through the packaged OpenRouter deployment:
```bash
-export OPENROUTER_API_KEY="your-openrouter-key" # pragma: allowlist secret
-./target/release/switchyard-server --config routes.toml --dry-run
-./target/release/switchyard-server --config routes.toml --host 127.0.0.1 --port 4000
+switchyard launch claude --model switchyard
+switchyard launch codex --model switchyard
```
-The route `id` is the model name clients use. In another terminal:
+Pass a custom native deployment when needed:
```bash
-curl http://localhost:4000/health
-curl http://localhost:4000/v1/models
-curl http://localhost:4000/v1/chat/completions \
- -H "Content-Type: application/json" \
- -d '{"model":"switchyard","messages":[{"role":"user","content":"hi"}]}'
+switchyard launch claude --model my-route --config routes.toml
```
-The Rust server also supports random, LLM-classifier, and stage-router routes,
-OpenAI Responses and Anthropic Messages endpoints, TLS, and Prometheus metrics.
-See the [`switchyard-server` guide](crates/switchyard-server/README.md) for the
-complete configuration schema and operational details.
+The deployment schema belongs in the
+[`switchyard-server` README](crates/switchyard-server/README.md).
## Architecture
diff --git a/docs/cli_reference.md b/docs/cli_reference.md
index 3bb6bc6f8..f0417ddf9 100644
--- a/docs/cli_reference.md
+++ b/docs/cli_reference.md
@@ -1,403 +1,25 @@
-# CLI Reference
+# CLI reference
-This page is the canonical reference for the documented `switchyard`
-subcommands. It mirrors the relevant output of `switchyard --help` and
-`switchyard <verb> --help`. Tutorials and recipes live in
-[Getting Started](getting_started.md); this page is reference material only.
+The documented CLI workflow launches a coding agent through the native Rust
+server.
-## Verbs at a glance
-
-| Verb | Audience | What it does |
-|---|---|---|
-| [`serve`](#switchyard-serve) | Ops | Long-running proxy server. Serve a YAML route bundle selected with the global `--routing-profiles` flag. |
-| [`configure`](#switchyard-configure) | Both | Persists provider credentials, a saved routing-profile path, and skill-distillation settings under `~/.config/switchyard/`. With `--show`, also prints a redacted resolution snapshot. With `--list-models`, prints a searchable list of backend models. |
-| [`verify`](#switchyard-verify) | Ops | Sequenced pass/fail checklist for the proxy and backend. Suitable for a readiness probe or CI install gate. |
-
-## Global flags
-
-These apply to the top-level `switchyard` command, before any verb.
-
-| Flag | Purpose |
-|---|---|
-| `--version` | Print the installed Switchyard version (`switchyard X.Y.Z`) and exit. Reads the version from the installed package metadata. |
-| `--routing-profiles PATH` / `-c PATH` | [Routing](#routing) bundle applied to `serve` and `configure`. Pass before the verb; separate with `--` for clarity. |
-| `--enable-rl-logging` | Write local [RL trace logs](#rl-trace-logging), one `message_history` JSON file per turn, for `serve` route-bundle sessions. |
-| `--rl-log-dir DIR` | Output directory for `--enable-rl-logging` traces (default: `./rl_data`). No effect without `--enable-rl-logging`. |
-
-## Cross-cutting flag families
-
-Most flags appear on more than one verb. Definitions live here so the per-verb
-sections can stay short.
-
-### Credentials and endpoint
-
-| Flag | Purpose |
-|---|---|
-| `--api-key VALUE` | API key for the backend. Resolves through the [API-key waterfall](#api-key-resolution). |
-| `--base-url URL` | Backend base URL. Resolves through the [base-URL waterfall](#base-url-resolution). |
-| `--provider ID` | Provider id for saved configuration (default: `openrouter`). Used by `configure` setup, `--show`, and `--list-models`. |
-
-### Backend format selection
-
-The `format` field in a target or route configuration controls the API used for
-upstream requests. Configuration files use these lowercase values:
-
-| Value | Upstream behavior | Use when |
-|---|---|---|
-| `openai` | Sends to `/v1/chat/completions` without probing. | The upstream is OpenAI-compatible, including NIM and OpenRouter. |
-| `anthropic` | Sends to `/v1/messages` without probing. | The upstream supports the Anthropic Messages API natively. |
-| `responses` | Sends to `/v1/responses` without probing. | The upstream supports the OpenAI Responses API natively. |
-| `auto` | Probes the upstream and selects a supported format. | The upstream is unknown or the same configuration must work across providers. |
-
-`auto` resolves formats in this order:
-
-1. Probe `/v1/chat/completions`; use `openai` when supported.
-2. Probe `/v1/messages`; use `anthropic` when supported.
-3. Probe `/v1/responses`; use `responses` when supported.
-4. Fall back to `openai` (`/v1/chat/completions`).
-
-Prefer an explicit format when the upstream contract is known so startup does
-not require capability probes.
-
-### Routing
-
-Routing policies live in routing-profile YAML files. `serve` uses the global
-`--routing-profiles` flag:
-
-| Flag | Purpose |
-|---|---|
-| `--routing-profiles PATH` | Path to a routing-profile YAML bundle. Each entry under `routes:` builds its own chain. Public route types are `model`, `random_routing`, `stage_router`, `escalation_router`, and `deterministic`. Falls back to the path persisted by `switchyard --routing-profiles PATH -- configure` when omitted. |
-
-For `type: deterministic` routes, the `classifier:` block also accepts:
-
-| Key | Purpose |
-|---|---|
-| `prompt` | Optional classifier system-prompt override. Leave unset or blank to use the selected profile's built-in prompt. `${ENV_VAR}` references are expanded when the bundle is loaded. |
-| `max_request_chars` | Optional cap on the serialized request summary sent to the classifier before truncation. Defaults to `16000`; minimum `256`. |
-| `recent_turn_window` | Number of trailing conversation turns included alongside the stable system/first-user anchors. Defaults to `4`. |
-
-Benchmark runs started through `benchmark/run-baseline.sh --server-config` copy the server TOML into the run directory and record its path and SHA-256 in `run_manifest.json` under `server.server_config_snapshot` and `server.server_config_snapshot_digest`.
-
-Each route name becomes a model ID on `GET /v1/models`. Clients select a route
-by setting the request's `model` field to that name.
-
-### Intake sink (serve)
-
-`serve` wires intake processors into every route in the loaded bundle. Requests
-still opt in with `store=true` or `x-switchyard-intake-enabled=true`.
-
-> **Note:** Switchyard has two independent ways to capture training data. The
-> **Intake sink** posts live captures to nemo-platform.
-> **`--enable-rl-logging`** writes local `message_history` JSON traces for
-> `serve` route-bundle sessions. Either, both, or neither may be enabled.
-
-| Flag | Purpose |
-|---|---|
-| `--intake-enabled` / `--enable-intake` | Enable the Intake sink. `--enable-intake` is a deprecated alias. Defaults to NMP SDK credentials (`nmp auth login` once). |
-| `--intake-base-url URL` | Override intake base URL. |
-| `--intake-workspace NAME` | Override workspace for Intake records. |
-| `--intake-api-key VALUE` | Override bearer token. Disables the SDK's transparent refresh. |
-| `--intake-target-url URL` | Post flat per-request telemetry to this full URL instead of chat-completions ingest. Defaults to `$SWITCHYARD_INTAKE_TARGET_URL`. |
-
-The Intake sink posts live model-call captures to nemo-platform
-`/apis/intake/v2/workspaces/{workspace}/ingest/chat-completions`. That endpoint
-derives queryable token fields from `response.usage` and queryable cost fields
-from top-level `cost_usd`, `cost_input_usd`, `cost_output_usd`, and
-`cost_details`. Switchyard emits cost fields only when the served model has a
-known pricing entry. `routing_stats_final.json` carries the run-level aggregate
-`/v1/stats` snapshot (per-model and per-tier calls, errors, tokens, and
-latency); it does not include cost estimates. When a session ID is present,
-Switchyard also maps the Intake app/task labels into top-level
-`evaluation_context.dataset_*` and `evaluation_context.test_case_id` for span
-queries while keeping the original labels under `request.switchyard`.
-
-Set `--intake-target-url` to a full posting URL to send captures to a different
-store instead. Switchyard then posts a flat, top-level, type-prefixed document
-(`s_` string, `l_` long, `f_` float, `b_` bool, `text_` debug) to that URL,
-unauthenticated, rather than the nested nemo-platform payload.
-
-### RL trace logging
-
-`--enable-rl-logging` attaches a response-side logger to the proxy chain of a
-`serve --routing-profiles` bundle. Each completed turn, streaming or not, is
-written to its own JSON file under `--rl-log-dir` (default `./rl_data`), named
-`{timestamp}_trace_{id}_{id}.json`. The schema matches the pre-1.0 trace format:
-
-```json
-{
- "uuid": "…",
- "messages": [
- {
- "role": "assistant",
- "content": "…",
- "tool_calls": []
- }
- ],
- "tools": [],
- "tool_choice": "auto",
- "token_count": {
- "prompt_tokens": 0,
- "completion_tokens": 0,
- "total_tokens": 0
- },
- "is_valid": true
-}
-```
-
-Turns without an assistant choice, such as upstream errors, are skipped.
-
-### Transport (server verbs)
-
-| Flag | Purpose |
-|---|---|
-| `--host HOST` | Host to bind to (default: `0.0.0.0`). |
-| `--port PORT` / `-p PORT` | Port to bind to (default: `4000`, or `server.port` from `secrets.json`). |
-| `--reload` | Enable uvicorn auto-reload. |
-| `--workers N` / `-w N` | Number of uvicorn worker processes (default: `1`, or `$SWITCHYARD_WORKERS`). |
-
-## Resolution waterfalls
-
-### API-key resolution
-
-Verification resolves the API key in this order, stopping at the first
-non-empty value:
-
-1. `--api-key` on the CLI
-2. `$OPENROUTER_API_KEY`
-3. `$NVIDIA_API_KEY`
-4. `$OPENAI_API_KEY`
-5. `$ANTHROPIC_API_KEY`
-6. `secrets/secrets.json` → first provider section with `api_key` set, with
- `openrouter` then `nvidia` checked first
-
-For OpenRouter, set `OPENROUTER_API_KEY`; `OPENROUTER_BASE_URL` is optional
-because the built-in default is `https://openrouter.ai/api/v1`.
-
-### Base-URL resolution
-
-1. `--base-url` on the CLI
-2. The base URL matching the selected environment credential:
- `$OPENROUTER_BASE_URL`, `$NVIDIA_BASE_URL`, or `$OPENAI_BASE_URL`
-3. `secrets/secrets.json` → same section traversal as the API key
-4. Default: OpenRouter (`https://openrouter.ai/api/v1`)
-
-### `secrets.json` format
-
-```json
-{
- "openrouter": {
- "api_key": "sk-or-...",
- "base_url": "https://openrouter.ai/api/v1"
- },
- "server": {
- "port": 4000
- }
-}
-```
-
-`secrets/` is gitignored. Never commit this file.
-
-## `switchyard serve`
-
-Serve a long-running proxy from a YAML route bundle. Each entry under `routes:`
-builds a runnable chain and is exposed as a model on `GET /v1/models`.
-
-The server exposes the OpenAI Chat Completions (`/v1/chat/completions`),
-Anthropic Messages (`/v1/messages`), and OpenAI Responses (`/v1/responses`)
-APIs on the same host and port.
-
-**Synopsis**
-
-```text
-switchyard [--routing-profiles PATH] serve
- [--host HOST] [--port PORT] [--workers N]
- [--reload] [--inbound FORMAT]
- [--routing-log-file PATH]
- [--intake-enabled|--enable-intake [INTAKE OVERRIDES]]
-```
-
-**Flags**
-
-| Flag | Source |
-|---|---|
-| `--routing-profiles PATH` / `-c PATH` | [Routing](#routing) path. Global flag; pass before `serve`. Falls back to the saved path from `switchyard --routing-profiles PATH -- configure`. |
-| `--host`, `--port`/`-p`, `--reload` | [Transport](#transport-server-verbs). |
-| `--inbound FORMAT` | Backwards-compatible no-op; all request APIs are always registered. |
-| `--workers` / `-w` | uvicorn worker count. |
-| `--routing-log-file PATH` | Append one JSONL routing record per request to `PATH`. Also exposes `GET /v1/routing/session-stats?session_id=...`. |
-| `--intake-enabled` / `--enable-intake`, `--intake-base-url`, `--intake-workspace`, `--intake-api-key`, `--intake-target-url` | [Intake sink](#intake-sink-serve). |
-
-**Notes**
-
-- `serve` always registers `POST /v1/chat/completions`, `POST /v1/messages`,
- `POST /v1/responses`, `GET /v1/models`, and `GET /health`.
-- `GET /v1/stats` and `GET /v1/routing/stats` expose route statistics.
-- `--inbound` is retained as a compatibility no-op.
-
-**Examples**
+## `switchyard launch`
```bash
-switchyard --routing-profiles routes.yaml -- serve --port 4000
-
-switchyard --routing-profiles routes.yaml -- configure --target provider \
- --provider openrouter --api-key "$OPENROUTER_API_KEY" \
- --base-url https://openrouter.ai/api/v1 --no-tui --no-model-discovery
-switchyard serve --port 4000
-
-SWITCHYARD_WORKERS=4 switchyard --routing-profiles routes.yaml -- serve
+export OPENROUTER_API_KEY="sk-or-..."
+switchyard launch claude --model switchyard
```
-## `switchyard configure`
-
-Persist user-level Switchyard defaults under `~/.config/switchyard/`.
-Credentials are stored separately from non-secret config, with owner-only file
-permissions. Skill-distillation config also lives in
-`~/.config/switchyard/config.json`.
-
-**Synopsis**
+Supported agents are `claude`, `codex`, and `openclaw`.
```text
-switchyard [--routing-profiles PATH] configure
- [--show [--check] [--json] | --reset | --list-models]
- [--target provider]
- [--query SUBSTRING] [--limit N]
- [--provider ID]
- [--base-url URL] [--api-key VALUE]
- [--skill-distillation NAMESPACE]
- [--disable-skill-distillation]
- [--no-model-discovery] [--no-tui]
+switchyard launch <agent> --model <route-id> [--config <deployment.toml>] [-- <agent args>]
```
-**Modes (mutually exclusive)**
-
-| Flag | What it does |
-|---|---|
-| _(none)_ | Interactive setup. Prompts for missing provider defaults and runs model discovery unless `--no-model-discovery`. |
-| `--show` | Print the redacted saved config plus a provider, base-URL, and API-key resolution snapshot. Pair with `--check` for a live `GET /models` probe, or `--json` for the raw redacted JSON snapshot. |
-| `--reset` | Delete persisted user config and credentials. |
-| `--list-models` | Fetch `GET /models` from the resolved provider. Pair with `--query` to filter by substring and `--limit` to cap results. |
-
-**Configuration knobs**
-
-| Flag | Purpose |
+| Option | Purpose |
|---|---|
-| `--target provider` | Save provider-level defaults without requiring model-specific settings. |
-| `--provider`, `--base-url`, `--api-key` | Provider-level defaults and one-off overrides for `--show` and `--list-models`. |
-| `--routing-profiles PATH` | Global flag; pass before `configure`. Parses the YAML at `PATH` and stores the parsed bundle inline in `~/.config/switchyard/config.json`. Subsequent `serve` runs use it when no path is supplied. Pass an empty string to clear. |
-| `--skill-distillation NAMESPACE` | Save a namespace for one skill that improves over time. Many sessions or trajectories can contribute to it; the namespace is not a session ID. |
-| `--disable-skill-distillation` | Remove the saved skill-distillation config. Cannot be combined with `--skill-distillation`. |
-| `--query` / `-q SUBSTRING` | With `--list-models`, case-insensitive substring filter. |
-| `--limit N` | With `--list-models`, cap on the number of models printed (default: 50; pass `0` for unlimited). |
-| `--no-model-discovery` | Skip `GET /models` and rely on existing provider values during interactive setup. |
-| `--no-tui` | Use plain text prompts instead of the TUI selector. |
-| `--check` | With `--show`, call `GET /models` against the resolved provider and report pass/fail. |
-
-> **Saved bundles keep `${VAR}` references literal.** A saved routing-profile
-> bundle stores `${OPENROUTER_API_KEY}` and other `${VAR}` references verbatim.
-> Export them before running `serve`.
-
-**Skill-distillation config**
-
-```json
-{
- "skill_distillation": {
- "namespace": "tooluniverse-trialqa"
- }
-}
-```
-
-Namespaces must be a single safe path component: letters, numbers, dot,
-underscore, and hyphen only. One namespace identifies one skill that improves
-over time, and many sessions or trajectories can contribute to it.
-
-**Examples**
-
-```bash
-switchyard configure
-
-switchyard --routing-profiles routes.yaml -- configure --target provider \
- --provider openrouter --api-key "$OPENROUTER_API_KEY" \
- --base-url https://openrouter.ai/api/v1 --no-tui --no-model-discovery
-
-switchyard configure --show
-switchyard configure --show --check
-switchyard configure --show --json
-
-switchyard configure --list-models --query gpt
-switchyard configure --list-models --limit 0 --provider openrouter \
- --api-key "$OPENROUTER_API_KEY" \
- --base-url https://openrouter.ai/api/v1
-
-switchyard configure --skill-distillation tooluniverse-trialqa
-switchyard configure --disable-skill-distillation
-switchyard configure --reset
-```
-
-!!! note "Non-interactive / CI usage"
- Pass `--target provider` to save provider credentials without requiring
- model-specific settings.
-
- **`configure` requires an explicit `--api-key` flag.** It does not read
- `OPENROUTER_API_KEY` or another `*_API_KEY` environment variable, and it
- does not read `api_key` from a routing-profile bundle.
-
-## `switchyard verify`
-
-Sequenced pass/fail checklist that confirms a Switchyard install works
-end-to-end against a real backend. It is suitable for readiness probes and
-pre-deployment smoke tests.
-
-**Synopsis**
-
-```text
-switchyard verify [--model ID] [--base-url URL] [--api-key VALUE]
- [--port PORT] [--timeout SECONDS]
-```
-
-**Example model**
-
-`openai/gpt-4o-mini` is a portable OpenRouter example. Pass `--model` when your
-provider uses a different model ID.
-
-**Checklist**
-
-1. Resolve credentials (CLI → env → `secrets.json`).
-2. Reach the backend via `GET /models`.
-3. Probe `/v1/chat/completions`, `/v1/messages`, and `/v1/responses` support.
-4. Start a proxy on a free port.
-5. Round-trip a chat completion through the chain.
-6. Tear the proxy down.
-
-**Exit codes**
-
-- `0`: every step passed.
-- Non-zero: first failing step; the error message names the source it tried and
- what to fix.
-
-**Examples**
-
-```bash
-switchyard verify
-switchyard verify --model openai/gpt-4o-mini
-switchyard verify --api-key "$OPENROUTER_API_KEY" \
- --base-url https://openrouter.ai/api/v1
-```
-
-## Environment variables
-
-| Variable | Purpose |
-|---|---|
-| `OPENROUTER_API_KEY`, `NVIDIA_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` | Backend credentials resolved by `verify`. |
-| `OPENROUTER_BASE_URL`, `NVIDIA_BASE_URL`, `OPENAI_BASE_URL` | Backend base URL overrides paired with the selected provider credential. |
-| `OPENAI_API_BASE` | Legacy alias for `OPENAI_BASE_URL`. Prefer `OPENAI_BASE_URL` for new configurations. |
-| `SWITCHYARD_INTAKE_ENABLED` | Boolean equivalent of `--intake-enabled` / `--enable-intake`. |
-| `SWITCHYARD_INTAKE_TARGET_URL` | Full posting URL for the alternate flat-document intake sink. |
-| `SWITCHYARD_WORKERS` | Default uvicorn worker count for `serve`. |
-| `SWITCHYARD_TELEMETRY_OPT_OUT` | Disable the `X-Switchyard-Version` telemetry header on outbound calls. |
-| `SWITCHYARD_INTAKE_BASE_URL`, `SWITCHYARD_INTAKE_WORKSPACE`, `SWITCHYARD_INTAKE_API_KEY`, `SWITCHYARD_INTAKE_APP`, `SWITCHYARD_INTAKE_TASK`, `SWITCHYARD_SESSION_ID`, `SWITCHYARD_USER_ID` | Intake-sink overrides for CI and headless runs. |
-| `NMP_ACCESS_TOKEN` | Fallback bearer token for the Intake sink when the NMP SDK config is not present. |
-
-## See also
+| `--model ID` | Required route ID from the deployment. |
+| `--config PATH` | TOML deployment. Defaults to the packaged OpenRouter deployment. |
+| `-- ...` | Arguments forwarded to the coding agent. |
-- [Getting Started](getting_started.md): install Switchyard and run your first request.
-- [Architecture](architecture.md): system context and end-to-end request flow.
+Custom deployment syntax is documented in `crates/switchyard-server/README.md`.
diff --git a/docs/getting_started.md b/docs/getting_started.md
index b10edd531..e48eaf263 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -1,181 +1,31 @@
-# Getting Started with Switchyard
-
-## Prerequisites
-
-- Git, a native build toolchain, and Rust with Cargo
-- An API key for OpenRouter, OpenAI, Anthropic, or another OpenAI-compatible endpoint.
- To use OpenRouter, create an account at [openrouter.ai](https://openrouter.ai/)
- and generate a key from the [OpenRouter keys page](https://openrouter.ai/keys).
-
-On Ubuntu or WSL, install the build prerequisites and Rust with `rustup`:
-
-```bash
-sudo apt-get update
-sudo apt-get install -y build-essential curl git
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-source "$HOME/.cargo/env"
-```
-
-On macOS or native Windows, follow the
-[official Rust installation instructions](https://rust-lang.org/tools/install/).
-The Rust installer includes `rustc`, Cargo, and `rustup`.
-
-Install `uv` for the repository's Python-based tooling and CI checks. It is not
-required to build or run the Rust server:
-
-```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
-```
-
-If either installer updates your shell configuration, restart the shell before
-continuing. Verify the tools:
-
-```bash
-git --version
-rustc --version
-cargo --version
-uv --version
-```
+# Getting Started
## Install
-Build the Rust server from source:
-
```bash
-git clone https://github.com/NVIDIA-NeMo/Switchyard.git
-cd Switchyard
-cargo build --locked --release -p switchyard-server
-./target/release/switchyard-server --help
+uv tool install "nemo-switchyard[cli,server]"
```
-The repository pins Rust `1.96.1` in `rust-toolchain.toml`; `rustup` selects and
-installs it automatically when Cargo runs from the repository. Prebuilt Rust
-binaries are not published yet.
-
-## Configure
-
-The Rust server reads an explicit TOML file. It does not use the legacy Python
-CLI's saved configuration or YAML routing profiles.
-
-Create `routes.toml` with an LLM-classifier route:
-
-```toml
-schema_version = 1
-
-[llm_clients.openrouter]
-format = "openai_chat"
-base_url = "https://openrouter.ai/api/v1"
-api_key_env = "OPENROUTER_API_KEY"
-
-[targets.weak]
-id = "openai/gpt-4o-mini"
-llm_client = "openrouter"
-
-[targets.strong]
-id = "openai/gpt-4o"
-llm_client = "openrouter"
-
-[routes.smart]
-id = "switchyard"
-type = "llm_classifier"
-classifier_target = "weak"
-strong_target = "strong"
-weak_target = "weak"
-base_threshold = 0.5
-```
+## Launch a coding agent
-`format` selects the upstream protocol and must be `openai_chat`,
-`openai_responses`, or `anthropic_messages`. `api_key_env` names the environment
-variable the server reads; the secret does not belong in the TOML file.
-
-## Server mode
-
-Export the provider credential, validate the configuration without binding a
-socket, then start the release binary:
-
-```bash
-export OPENROUTER_API_KEY="your-openrouter-key" # pragma: allowlist secret
-./target/release/switchyard-server --config routes.toml --dry-run
-./target/release/switchyard-server --config routes.toml \
- --host 127.0.0.1 --port 4000
-```
-
-Any client that speaks OpenAI Chat Completions, Anthropic Messages, or OpenAI
-Responses API can connect. The route `id` is the model name clients use.
-
-In another terminal:
+The packaged deployment uses OpenRouter:
```bash
-curl http://localhost:4000/health
-curl http://localhost:4000/v1/models
-curl http://localhost:4000/v1/chat/completions \
- -H "Content-Type: application/json" \
- -d '{"model":"switchyard","messages":[{"role":"user","content":"hello"}]}'
+export OPENROUTER_API_KEY="sk-or-..."
+switchyard launch claude --model switchyard
```
-## Routing algorithms
-
-### Choose a route type
-
-This guide uses `llm_classifier`, which asks a classifier target whether each
-request should use the weak or strong target. The Rust server also supports:
-
-| Algorithm | Use it when | Config |
-|---|---|---|
-| Random | You need a weighted split for A/B tests or baselines. | `random` |
-| LLM classifier | Request content should decide whether to use the weak or strong target. | `llm_classifier` |
-| Stage router | Tool-result and progress signals should select an efficient or capable target. | `stage_router` |
-
-A single TOML file can declare multiple routes. The table key, such as
-`routes.smart`, is a local configuration name; each route's `id` is exposed as a
-model on `GET /v1/models`.
-
-See the [`switchyard-server` guide](../crates/switchyard-server/README.md) for
-the complete TOML schema, route options, TLS, and metrics.
-
-<!-- TODO: Restore routing-guide links after those pages use the Rust TOML schema. -->
-
-<!-- TODO: Add Python library usage back when the supported Rust-backed API is finalized. -->
-
-## Troubleshooting
-
-**No API key / auth error**
+Codex and OpenClaw use the same shape:
```bash
-test -n "$OPENROUTER_API_KEY" && echo "key is set" || echo "key is missing"
-./target/release/switchyard-server --config routes.toml --dry-run
+switchyard launch codex --model switchyard
+switchyard launch openclaw --model switchyard
```
-Confirm that `api_key_env` in `routes.toml` names the environment variable you
-exported. The dry run validates the schema, environment lookup, target
-references, and route construction without starting the server.
-
-**Connection refused**
-
-Check health: `curl http://localhost:4000/health`
-
-**Telemetry header opt-out**
-
-Switchyard adds an `X-Switchyard-Version` header to outbound LLM calls for
-release attribution. No request or response content is included. To disable:
+To use another deployment:
```bash
-export SWITCHYARD_TELEMETRY_OPT_OUT=1
+switchyard launch claude --model my-route --config routes.toml
```
-<!-- TODO: Add contributor setup back when the documented workflow is Rust-first. -->
-
----
-
-## Next steps
-
-- [`switchyard-server`](../crates/switchyard-server/README.md): server configuration,
- routing algorithms, TLS, and metrics
-- [`switchyard-libsy`](../crates/libsy/README.md): embed routing algorithms in a
- Rust application
-- [`switchyard-protocol`](../crates/protocol/README.md): provider-neutral
- request, response, and streaming types
-- [`switchyard-translation`](../crates/switchyard-translation/README.md):
- request, response, and stream translation
-
-<!-- TODO: Restore architecture, CLI, and routing links when those pages are Rust-first. -->
+See `crates/switchyard-server/README.md` for the TOML schema.
diff --git a/docs/index.md b/docs/index.md
index a07954a0f..70ba539bc 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,132 +1,28 @@
-# Switchyard Documentation
+# Switchyard
-Switchyard is a typed control plane for LLM traffic. It sits between client
-applications and model backends, translates OpenAI Chat / Anthropic Messages /
-OpenAI Responses formats, and routes each request through profile-backed chains.
+Switchyard routes and translates LLM traffic for coding agents and API clients.
+It supports OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages.
-Use Switchyard when you want coding agents, SDK clients, or internal services to
-keep their native API shape while traffic is served by a different provider,
-split across model tiers, or selected by routing policy.
-
-## Project Overview
-
-| Area | What Switchyard provides |
-|---|---|
-| Client ingress | OpenAI Chat Completions, Anthropic Messages, and OpenAI Responses compatible endpoints. |
-| Format translation | Request and response translation between supported wire formats. |
-| Routing policies | Random splits, LLM classifier routing with optional session affinity, signal-driven stage-router routing, and YAML route bundles. |
-| Operations | Request/token statistics and context-window fallback behavior. |
-| Deployment options | Local or shared HTTP service, or embedded Python runtime. |
-
-At a high level, Switchyard keeps client integrations separate from model
-providers and routing policy:
-
-```text
-clients -> compatible API surface -> routing and resilience -> model backends
-```
-
-For system context and request lifecycle diagrams, see
-[Architecture](architecture.md).
-
-## First Run
+## Start
```bash
-pip install "nemo-switchyard[cli,server]"
-switchyard configure
+uv tool install "nemo-switchyard[cli,server]"
+export OPENROUTER_API_KEY="sk-or-..."
+switchyard launch claude --model switchyard
```
-For source installs, non-interactive configuration, and a curl sanity check, use
-[Getting Started](getting_started.md).
-
-## Main Workflows
-
-<div class="grid cards" markdown>
-
-- **Configure routing**
-
- Pick between fixed splits, classifier routing, and stage-router routing, with
- optional session affinity for classifier-driven conversations.
-
- [Routing Overview](routing_algorithms/overview.md)
-
-- **Prepare skill distillation**
-
- Save a namespace for the intended automatic skill learning flow without
- changing request routing.
-
- [Skill Distillation](skill_distillation.md)
-
-- **Understand the system**
-
- See how clients, routing policy, model backends, and operations fit
- together.
-
- [Architecture](architecture.md)
-
-- **Operate the proxy**
-
- Understand context-window overflow handling and fallback behavior.
-
- [Context-Window Handling](operations/context_window.md)
-
-</div>
-
-## Configuration Model
-
-Python CLI deployments define client-facing routes in a YAML bundle:
-
-```yaml
-defaults:
- api_key: ${OPENROUTER_API_KEY}
- base_url: https://openrouter.ai/api/v1
- format: openai
-
-routes:
- smart:
- type: random_routing
- strong:
- model: openai/gpt-4o
- weak:
- model: openai/gpt-4o-mini
- strong_probability: 0.3
- fallback_target_on_evict: strong
-```
-
-Run it as a long-lived proxy. Route names appear as models on `GET /v1/models`,
-and clients select one with the request's `model` field:
-
-```bash
-switchyard --routing-profiles routes.yaml -- serve --port 4000
-```
-
-The same bundle can be saved as the default:
+Use a custom native deployment when needed:
```bash
-switchyard --routing-profiles routes.yaml -- configure --target provider \
- --provider openrouter --api-key "$OPENROUTER_API_KEY" \
- --base-url https://openrouter.ai/api/v1 --no-tui --no-model-discovery
+switchyard launch codex --model my-route --config routes.toml
```
-Non-interactive `configure` does not read provider credentials from the routing
-bundle; pass `--api-key` explicitly when persisting the bundle for CI.
-
-Route types and persistence are covered in
-[Routing Overview](routing_algorithms/overview.md). The Rust server uses its
-own explicit TOML configuration for LLM clients, targets, and libsy algorithms.
-
-## Routing Reference
-
-| Need | Read |
-|---|---|
-| Fixed strong/weak traffic split for baselines or A/B tests | [Random Routing](routing_algorithms/random_routing.md) |
-| Per-request strong/weak decisions from a classifier model | [LLM Classifier Routing](routing_algorithms/llm_classifier_routing.md) |
-| Signal-driven weak/strong escalation with optional classifier fallback | [Stage-Router Routing](routing_algorithms/stage_router_routing.md) |
-| Conversation-level affinity for cache reuse | [Sticky Routing](routing_algorithms/sticky_routing.md) |
+The TOML schema is maintained in `crates/switchyard-server/README.md`.
-## Operations and Reference
+## Read More
-| Topic | Read |
-|---|---|
-| Known limitations and workarounds for 0.1.0 | [Known Issues](known_issues.md) |
-| CLI syntax, flags, resolution rules, and environment variables | [CLI Reference](cli_reference.md) |
-| Context-window overflow retry and fallback behavior | [Context-Window Handling](operations/context_window.md) |
+- [Getting Started](getting_started.md)
+- [CLI Reference](cli_reference.md)
+- [Routing Overview](routing_algorithms/overview.md)
+- [Architecture](architecture.md)
+- [Context-Window Handling](operations/context_window.md)
diff --git a/docs/internal/metrics_reference.md b/docs/internal/metrics_reference.md
index e80974791..09d63ade7 100644
--- a/docs/internal/metrics_reference.md
+++ b/docs/internal/metrics_reference.md
@@ -15,7 +15,7 @@ a drop-in scrape config and starter alert rules.
| Default scrape interval | 15s |
`GET /metrics` is served by the Python route-bundle server started with
-`switchyard --routing-profiles PATH -- serve`.
+`switchyard serve --routing-profiles PATH`.
A JSON variant of the same underlying data lives at `GET /v1/stats`, with
`GET /v1/routing/stats` as a backwards-compatible alias.
diff --git a/docs/routing_algorithms/escalation_router_routing.md b/docs/routing_algorithms/escalation_router_routing.md
index 45095a73b..90ee9731a 100644
--- a/docs/routing_algorithms/escalation_router_routing.md
+++ b/docs/routing_algorithms/escalation_router_routing.md
@@ -101,7 +101,7 @@ routes:
Run the route as a standalone proxy:
```bash
-switchyard --routing-profiles routes.yaml -- serve --port 4000
+switchyard serve --routing-profiles routes.yaml --port 4000
```
The route ID (`agent-escalation`) is the model ID clients select to use the
diff --git a/docs/routing_algorithms/llm_classifier_routing.md b/docs/routing_algorithms/llm_classifier_routing.md
index f513589c5..676e60b73 100644
--- a/docs/routing_algorithms/llm_classifier_routing.md
+++ b/docs/routing_algorithms/llm_classifier_routing.md
@@ -51,7 +51,7 @@ routes:
Start the server with:
```bash
-switchyard --routing-profiles routes.yaml -- serve --port 4000
+switchyard serve --routing-profiles routes.yaml --port 4000
```
The route ID (`smart`) is the model ID clients select for classifier-based
diff --git a/docs/routing_algorithms/overview.md b/docs/routing_algorithms/overview.md
index 96b8d4cb2..f6fcc8efe 100644
--- a/docs/routing_algorithms/overview.md
+++ b/docs/routing_algorithms/overview.md
@@ -5,7 +5,7 @@ The Python CLI loads routing policies from a YAML bundle. Each key under
Anthropic Messages, and OpenAI Responses requests:
```bash
-switchyard --routing-profiles routes.yaml -- serve --port 4000
+switchyard serve --routing-profiles routes.yaml --port 4000
```
Use this page to choose a routing strategy, then open its detailed page for
diff --git a/docs/routing_algorithms/random_routing.md b/docs/routing_algorithms/random_routing.md
index 6cb97cc18..f81e89b0e 100644
--- a/docs/routing_algorithms/random_routing.md
+++ b/docs/routing_algorithms/random_routing.md
@@ -53,7 +53,7 @@ routes:
Run it with:
```bash
-switchyard --routing-profiles routes.yaml -- serve --port 4000
+switchyard serve --routing-profiles routes.yaml --port 4000
```
The route id (`ab-test`) is the model id clients select when they want the
diff --git a/docs/skill_distillation.md b/docs/skill_distillation.md
deleted file mode 100644
index 068482249..000000000
--- a/docs/skill_distillation.md
+++ /dev/null
@@ -1,169 +0,0 @@
-# Skill Distillation
-
-Skill distillation is intended to turn agent sessions into a reusable skill for
-the same kind of work without retraining the model. The workflow will save
-session history, use it to update a `SKILL.md`, and make the active skill
-available to later agent runs for the same namespace.
-
-The current release provides saved configuration and the Rust contracts that
-later implementations will share. It does not yet save session files, run
-distillation, update skills, import external runs, validate results, or mount
-skills into agent runtimes.
-
-## Configure It
-
-Choose a short namespace for the task or workflow you want the skill to learn:
-
-```bash
-switchyard configure --skill-distillation tooluniverse-trialqa
-switchyard configure --show
-```
-
-One namespace identifies one skill that improves over time. Keep using the same
-namespace when more sessions or trajectories should contribute to that skill;
-choose a different namespace when you want a separate skill. A namespace is not
-a session ID. The future automatic workflow will generate a separate internal
-session ID for each captured run.
-
-The namespace is stored in the user config and can be updated without provider
-credentials. To remove it:
-
-```bash
-switchyard configure --disable-skill-distillation
-```
-
-## Intended Workflow
-
-A future host integration should automate this flow:
-
-```text
-select a namespace
-capture a completed agent session
-save the session under that namespace
-distill when the session ends
-create or update the namespace's active SKILL.md
-load that active skill in the next run for the same namespace
-```
-
-If no skill exists yet, the first distilled session creates one. Later sessions
-update the existing skill and keep enough history to inspect or roll back the
-change.
-
-Skill distillation is namespace-based. A namespace identifies one skill that
-improves over time; it is not a session ID or per-request header. A future
-request may be recorded as part of a saved session, but a single HTTP request
-should not change which skill is being learned or used.
-
-## Session Ownership
-
-The host runtime should generate a separate session ID, record completed model
-turns, and finalize the project-local session record when the agent exits. The
-user should choose only the namespace, not a session ID, storage path, or
-separate recorder.
-
-The capture backend is an internal implementation detail. The initial
-implementation will use a Switchyard-managed project-local store; a later
-trajectory source or storage backend can replace or supplement it without
-changing the Rust contracts or host workflow.
-
-## Config
-
-Skill distillation config is stored in `~/.config/switchyard/config.json` under
-the top-level `skill_distillation` key:
-
-```json
-{
- "skill_distillation": {
- "namespace": "tooluniverse-trialqa"
- }
-}
-```
-
-The config is intentionally small:
-
-| Field | Default | Meaning |
-|---|---|---|
-| `namespace` | unset | Stable name for one skill that improves over time. Many sessions or trajectories can contribute to it; it is not a session ID. |
-
-Namespaces must be safe local path components: letters, numbers, dot,
-underscore, and hyphen only. They cannot be `.` or `..`.
-
-The top-level `skill_distillation` key is omitted when skill distillation is
-not configured. `namespace` is the only supported key today. Extra manually
-edited keys are rejected instead of being treated as inactive future options.
-
-## Decisions
-
-Generated output should stay portable and easy to review. Switchyard should
-write `SKILL.md` and human-readable reports, not generated Python or other
-executable files.
-
-Skill generation should happen after sessions finish, not during normal model
-request handling. Switchyard owns the session-to-skill lifecycle, including
-capture, distillation, validation, history, and run-time skill loading. It
-should not turn every request into a memory update.
-
-The automatic workflow still needs guardrails. Every skill update should record
-which sessions supported it, keep the previous active skill available for
-rollback, and produce review output. Later checks should flag answer leakage,
-source IDs, URLs, benchmark shortcuts, and task-specific details before a skill
-is trusted.
-
-## Planned Store Layout
-
-Future work should use inspectable local files:
-
-```text
-<project>/.switchyard/skill-distillation/<namespace>/
- sessions/<session-id>/
- session.json
- turns.jsonl
- stats.json
- distillation-ledger.jsonl
- candidates/<version-id>/
- skill/SKILL.md
- report.md
- active/SKILL.md
- history.jsonl
-```
-
-The ledger should track which saved sessions have already contributed to a
-skill update. That lets distillation use new sessions by default instead of
-depending on a long-lived lookback-count setting.
-
-## Rust Contracts
-
-The `switchyard-skill-distillation` crate defines the source-neutral records
-and extension points shared by future implementations and adapters. It does not
-choose a provider, storage format, agent runtime, or model implementation.
-
-The public contract includes:
-
-- safe `SkillNamespace`, `SkillEvidenceId`, and `SkillVersionId` identifiers;
-- versioned trajectories with task, execution, source, event, and outcome data;
-- versioned skill candidates with required source-evidence provenance and
- optional validation reports; and
-- async `TrajectorySource`, `SkillDistiller`, `SkillValidator`, and `SkillStore`
- traits.
-
-The traits define workflow steps, but they do not run by themselves. No
-production Switchyard code uses them today. A Switchyard runtime must load
-saved trajectories and the active skill, build a distillation request, create
-and check a candidate, then save it and decide whether to make it active. This
-crate does not choose the code that implements each trait or decide when those
-steps run.
-
-`SkillEvidenceId` is not a second session tracker. A session ID groups requests
-and turns while an agent is running. A `SkillEvidenceId` identifies the
-completed run after Switchyard saves it for distillation. The initial workflow
-will create one evidence record for each completed captured session. Switchyard
-keeps this ID stable within the namespace. The Rust contract uses it to reject
-duplicate inputs in one distillation request and to record which evidence a
-skill candidate used. The code that creates an evidence record reuses a safe
-session ID or derives the evidence ID from it in a repeatable way. It can keep
-the original run or session ID in `TrajectorySourceInfo.id`.
-
-Provider-specific event data stays inside JSON payload and metadata fields.
-The crate validates record invariants but does not redact source data, run a
-model, write files, or activate a candidate by itself. Adapters and runtime
-implementations own those operations.
diff --git a/mkdocs.yml b/mkdocs.yml
index 1650033e0..fc17c88d7 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -20,8 +20,6 @@ nav:
- Get Started:
- Getting Started: getting_started.md
- Known Issues in 0.1.0: known_issues.md
- - Guides:
- - Skill Distillation: skill_distillation.md
- Concepts:
- Core Concepts: core_concepts.md
- Architecture: architecture.md
diff --git a/pyproject.toml b/pyproject.toml
index eabebcdef..919ca836b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -64,7 +64,7 @@ tracing = [
]
# Intake — NeMo Platform SDK required by IntakeClient for telemetry capture.
-# Only needed when --intake-enabled is passed to ``switchyard launch``.
+# Only needed when --intake-enabled is passed to ``switchyard serve``.
# Install with: pip install nemo-switchyard[intake]
intake = [
"nemo-platform>=0.1.0,<1.0",
@@ -137,6 +137,7 @@ include = ["switchyard*"]
[tool.setuptools.package-data]
switchyard = [
"py.typed",
+ "cli/defaults/*.toml",
"lib/processors/prompts/*.md",
"lib/processors/stage_router/prompts/*.md",
]
diff --git a/switchyard/cli/command_utils.py b/switchyard/cli/command_utils.py
index 455d2d1a7..1539a2124 100644
--- a/switchyard/cli/command_utils.py
+++ b/switchyard/cli/command_utils.py
@@ -1,46 +1,20 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Shared helpers for CLI command modules."""
+"""Small helpers shared by the remaining CLI commands."""
-from __future__ import annotations
-
-import getpass
import logging
-import sys
-
-from switchyard.cli.model_catalog.model_discovery import (
- ModelDiscoveryError,
- fetch_model_ids,
-)
-from switchyard.cli.tui.launch_config_wizard import LaunchConfigWizard
-from switchyard.cli.tui.tui_session import TuiSession
-
-logger = logging.getLogger(__name__)
-
-ROUTING_MODE_CHOICES: list[str] = ["single", "random", "deterministic"]
def quiet_dependency_loggers() -> None:
- """Keep third-party INFO logs from interrupting interactive CLI prompts."""
+ """Keep third-party INFO logs out of launcher terminal UIs."""
for noisy in ("httpx", "httpcore", "openai", "anthropic", "uvicorn.access"):
logging.getLogger(noisy).setLevel(logging.WARNING)
-def parse_probability(value: str | float | None, *, default: float = 0.5) -> float:
- """Parse and validate a strong-model probability value."""
-
- if value is None:
- return default
- parsed = float(value)
- if not 0.0 <= parsed <= 1.0:
- raise SystemExit("strong probability must be between 0.0 and 1.0.")
- return parsed
-
-
def strip_forwarded_args(args: list[str] | None) -> list[str]:
- """Strip argparse's leading ``--`` sentinel from passthrough args."""
+ """Strip argparse's leading ``--`` sentinel from forwarded arguments."""
forwarded = args or []
if forwarded and forwarded[0] == "--":
@@ -48,37 +22,4 @@ def strip_forwarded_args(args: list[str] | None) -> list[str]:
return forwarded
-def is_interactive_terminal() -> bool:
- return sys.stdin.isatty() and sys.stdout.isatty()
-
-
-def build_launch_config_wizard(no_tui: bool) -> LaunchConfigWizard:
- return LaunchConfigWizard(
- session=TuiSession.from_current_terminal(
- force_plain=no_tui,
- input_fn=input,
- secret_fn=getpass.getpass,
- output_fn=print,
- ),
- )
-
-
-def discover_models(base_url: str, api_key: str, *, disabled: bool) -> list[str]:
- if disabled:
- return []
- try:
- return fetch_model_ids(base_url, api_key)
- except ModelDiscoveryError as exc:
- logger.warning("Could not fetch model catalog from %s: %s", base_url, exc)
- return []
-
-
-__all__ = [
- "ROUTING_MODE_CHOICES",
- "build_launch_config_wizard",
- "discover_models",
- "is_interactive_terminal",
- "parse_probability",
- "quiet_dependency_loggers",
- "strip_forwarded_args",
-]
+__all__ = ["quiet_dependency_loggers", "strip_forwarded_args"]
diff --git a/switchyard/cli/config/user_config.py b/switchyard/cli/config/user_config.py
deleted file mode 100644
index 88cddc505..000000000
--- a/switchyard/cli/config/user_config.py
+++ /dev/null
@@ -1,777 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""User-level configuration for the launcher UX.
-
-This module owns the persistent, cross-repo defaults used by
-``switchyard configure`` and the one-command launchers. It is
-intentionally independent of argparse so tests and future non-CLI entry
-points can reuse the same read/write and resolution behavior.
-"""
-
-import json
-import os
-from collections.abc import Mapping
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Literal, cast
-
-DEFAULT_PROVIDER = "openrouter"
-DEFAULT_OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
-DEFAULT_SECRETS_SECTION_PRIORITY = (DEFAULT_PROVIDER, "nvidia")
-_PROVIDER_BASE_URL_DEFAULTS = {
- DEFAULT_PROVIDER: DEFAULT_OPENROUTER_BASE_URL,
- "nvidia": "https://inference-api.nvidia.com/v1",
- "openai": "https://api.openai.com/v1",
-}
-CONFIG_DIR_ENV_VAR = "SWITCHYARD_CONFIG_DIR"
-CONFIG_FILENAME = "config.json"
-CREDENTIALS_FILENAME = "credentials.json"
-
-LaunchTarget = Literal["claude", "codex", "openclaw"]
-LaunchRouteType = Literal["single", "random", "deterministic"]
-PRIMARY_TIER = "primary"
-WEAK_TIER = "weak"
-
-_SKILL_DISTILLATION_KEYS = frozenset({"namespace"})
-
-
-class UserConfigError(RuntimeError):
- """Raised when a persisted user config file is malformed."""
-
-
-@dataclass(frozen=True)
-class ProviderConfig:
- """Non-secret provider defaults."""
-
- base_url: str | None = None
-
-
-@dataclass(frozen=True)
-class LaunchTierEndpointConfig:
- """Non-secret endpoint override for one launch route tier."""
-
- base_url: str | None = None
-
-
-@dataclass(frozen=True)
-class LaunchRouteConfig:
- """Per-harness route defaults.
-
- ``single`` is the no-routing path: every request is rewritten to
- ``model``. ``random`` routes between ``model`` (strong/primary) and
- ``weak_model`` with ``strong_probability``.
- """
-
- type: LaunchRouteType = "single"
- model: str | None = None
- weak_model: str | None = None
- strong_probability: float = 0.5
- endpoints: dict[str, LaunchTierEndpointConfig] | None = None
-
- def endpoint(self, tier: str) -> LaunchTierEndpointConfig:
- """Return the endpoint override for *tier*, if configured."""
-
- return (self.endpoints or {}).get(tier, LaunchTierEndpointConfig())
-
-
-@dataclass(frozen=True)
-class LaunchConfig:
- """Per-launcher defaults."""
-
- model: str | None = None
- route: LaunchRouteConfig | None = None
-
- def effective_route(self) -> LaunchRouteConfig:
- """Return the saved route, or a single-model route from legacy fields."""
-
- if self.route:
- return LaunchRouteConfig(
- type=self.route.type,
- model=self.route.model or self.model,
- weak_model=self.route.weak_model,
- strong_probability=self.route.strong_probability,
- endpoints=self.route.endpoints,
- )
- return LaunchRouteConfig(
- type="single",
- model=self.model,
- )
-
-
-@dataclass(frozen=True)
-class SkillDistillationConfig:
- """User-level skill distillation defaults."""
-
- namespace: str | None = None
-
- def __post_init__(self) -> None:
- if self.namespace is not None:
- _validate_skill_namespace(self.namespace)
-
- @property
- def configured(self) -> bool:
- """Return whether skill distillation has a namespace to operate on."""
-
- return self.namespace is not None
-
- def is_default(self) -> bool:
- """Return whether this matches an unconfigured skill distillation config."""
-
- return self == SkillDistillationConfig()
-
-
-@dataclass(frozen=True)
-class UserConfig:
- """Non-secret Switchyard defaults stored under the user config dir.
-
- ``routing_profiles`` is a parsed routing-profile YAML bundle saved by
- ``switchyard --routing-profiles PATH configure``. Stored as a parsed
- JSON object inline (not as a path — paths rot when files move); env
- var references inside the bundle are preserved verbatim and
- re-expanded on each load. Consumed by ``switchyard serve`` (and as a
- fallback for ``switchyard launch claude/codex``) when no CLI
- ``--routing-profiles`` is passed.
- """
-
- default_provider: str = DEFAULT_PROVIDER
- providers: dict[str, ProviderConfig] | None = None
- launch: dict[LaunchTarget, LaunchConfig] | None = None
- routing_profiles: dict[str, object] | None = None
- skill_distillation: SkillDistillationConfig = field(
- default_factory=SkillDistillationConfig,
- )
-
- def provider(self, name: str | None = None) -> ProviderConfig:
- providers = self.providers or {}
- return providers.get(name or self.default_provider, ProviderConfig())
-
- def launch_target(self, target: LaunchTarget) -> LaunchConfig:
- launch = self.launch or {}
- return launch.get(target, LaunchConfig())
-
-
-@dataclass(frozen=True)
-class LaunchCredentials:
- """Secret per-launcher tier credentials."""
-
- api_keys: dict[str, str] | None = None
-
- def api_key(self, tier: str = PRIMARY_TIER) -> str | None:
- return (self.api_keys or {}).get(tier)
-
-
-@dataclass(frozen=True)
-class UserCredentials:
- """Secret provider credentials stored separately from config."""
-
- api_keys: dict[str, str] | None = None
- launch: dict[LaunchTarget, LaunchCredentials] | None = None
-
- def api_key(self, provider: str) -> str | None:
- return (self.api_keys or {}).get(provider)
-
- def launch_target(self, target: LaunchTarget) -> LaunchCredentials:
- launch = self.launch or {}
- return launch.get(target, LaunchCredentials())
-
-
-@dataclass(frozen=True)
-class ProviderConnectivity:
- """Resolved provider connectivity after applying precedence rules."""
-
- provider: str
- api_key: str | None
- base_url: str
-
-
-def get_user_config_dir() -> Path:
- """Return the directory where Switchyard user config is stored."""
-
- override = os.environ.get(CONFIG_DIR_ENV_VAR)
- if override:
- return Path(override).expanduser()
-
- xdg_config_home = os.environ.get("XDG_CONFIG_HOME")
- if xdg_config_home:
- return Path(xdg_config_home).expanduser() / "switchyard"
-
- return Path.home() / ".config" / "switchyard"
-
-
-def get_config_path(config_dir: Path | None = None) -> Path:
- return (config_dir or get_user_config_dir()) / CONFIG_FILENAME
-
-
-def get_credentials_path(config_dir: Path | None = None) -> Path:
- return (config_dir or get_user_config_dir()) / CREDENTIALS_FILENAME
-
-
-def _read_json_object(path: Path) -> dict[str, object]:
- if not path.exists():
- return {}
- try:
- with path.open() as f:
- raw = json.load(f)
- except json.JSONDecodeError as exc:
- raise UserConfigError(f"{path} is not valid JSON: {exc}") from exc
- if not isinstance(raw, dict):
- raise UserConfigError(f"{path} must contain a JSON object")
- return cast(dict[str, object], raw)
-
-
-def _mapping_value(data: Mapping[str, object], key: str) -> dict[str, object]:
- value = data.get(key)
- if isinstance(value, dict):
- return cast(dict[str, object], value)
- return {}
-
-
-def _str_value(data: Mapping[str, object], key: str) -> str | None:
- value = data.get(key)
- return value if isinstance(value, str) and value else None
-
-
-def _validate_skill_namespace(namespace: str) -> None:
- if namespace != namespace.strip():
- raise UserConfigError(
- "skill_distillation.namespace must not have leading or trailing "
- "whitespace"
- )
- if namespace in {".", ".."}:
- raise UserConfigError(
- "skill_distillation.namespace must be a safe local path component"
- )
- allowed = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-")
- if not namespace or any(ch not in allowed for ch in namespace):
- raise UserConfigError(
- "skill_distillation.namespace may contain only letters, numbers, "
- "dot, underscore, and hyphen"
- )
-
-
-def _float_value(
- data: Mapping[str, object], key: str, default: float,
-) -> float:
- value = data.get(key)
- if isinstance(value, (int, float)):
- return float(value)
- return default
-
-
-def _route_type_value(data: Mapping[str, object], key: str) -> LaunchRouteType | None:
- value = data.get(key)
- if value == "single":
- return "single"
- if value == "random":
- return "random"
- if value == "deterministic":
- return "deterministic"
- return None
-
-
-def _parse_launch_route(raw_route: object) -> LaunchRouteConfig | None:
- if not isinstance(raw_route, dict):
- return None
- route_data = cast(dict[str, object], raw_route)
- route_type = _route_type_value(route_data, "type") or "single"
- return LaunchRouteConfig(
- type=route_type,
- model=_str_value(route_data, "model"),
- weak_model=_str_value(route_data, "weak_model"),
- strong_probability=_float_value(route_data, "strong_probability", 0.5),
- endpoints=_parse_launch_endpoints(route_data),
- )
-
-
-def _parse_launch_endpoint(raw_endpoint: object) -> LaunchTierEndpointConfig | None:
- if not isinstance(raw_endpoint, dict):
- return None
- endpoint_data = cast(dict[str, object], raw_endpoint)
- base_url = _str_value(endpoint_data, "base_url")
- if not base_url:
- return None
- return LaunchTierEndpointConfig(base_url=base_url)
-
-
-def _parse_launch_endpoints(
- route_data: Mapping[str, object],
-) -> dict[str, LaunchTierEndpointConfig] | None:
- raw_endpoints = route_data.get("endpoints")
- endpoints_data = raw_endpoints if isinstance(raw_endpoints, dict) else {}
- endpoints: dict[str, LaunchTierEndpointConfig] = {}
- for tier, raw_endpoint in cast(dict[str, object], endpoints_data).items():
- endpoint = _parse_launch_endpoint(raw_endpoint)
- if endpoint:
- endpoints[tier] = endpoint
-
- # Transitional support for early local configs that used flat keys.
- primary_base_url = _str_value(route_data, "base_url")
- if primary_base_url:
- endpoints[PRIMARY_TIER] = LaunchTierEndpointConfig(base_url=primary_base_url)
- weak_base_url = _str_value(route_data, "weak_base_url")
- if weak_base_url:
- endpoints[WEAK_TIER] = LaunchTierEndpointConfig(base_url=weak_base_url)
-
- return endpoints or None
-
-
-def _endpoint_to_json(endpoint: LaunchTierEndpointConfig) -> dict[str, object]:
- body: dict[str, object] = {}
- if endpoint.base_url:
- body["base_url"] = endpoint.base_url
- return body
-
-
-def _route_to_json(route: LaunchRouteConfig) -> dict[str, object]:
- body: dict[str, object] = {"type": route.type}
- if route.model:
- body["model"] = route.model
- if route.weak_model:
- body["weak_model"] = route.weak_model
- if route.type == "random":
- body["strong_probability"] = route.strong_probability
- endpoints: dict[str, object] = {}
- for tier, endpoint in (route.endpoints or {}).items():
- endpoint_body = _endpoint_to_json(endpoint)
- if endpoint_body:
- endpoints[tier] = endpoint_body
- if endpoints:
- body["endpoints"] = endpoints
- return body
-
-
-def _launch_config_to_json(target_config: LaunchConfig) -> dict[str, object]:
- body: dict[str, object] = {}
- route = target_config.effective_route()
- if route.model:
- body["model"] = route.model
- body["route"] = _route_to_json(route)
- return body
-
-
-def _parse_skill_distillation_config(raw_config: object) -> SkillDistillationConfig:
- if raw_config is None:
- return SkillDistillationConfig()
- if not isinstance(raw_config, dict):
- raise UserConfigError("skill_distillation must contain a JSON object")
- config_data = cast(dict[str, object], raw_config)
- unsupported_keys = sorted(set(config_data) - _SKILL_DISTILLATION_KEYS)
- if unsupported_keys:
- raise UserConfigError(
- "skill_distillation supports only namespace; unsupported key(s): "
- f"{', '.join(unsupported_keys)}"
- )
- raw_namespace = config_data.get("namespace")
- if raw_namespace is None or raw_namespace == "":
- raise UserConfigError(
- "skill_distillation.namespace is required when skill distillation "
- "is configured"
- )
- if not isinstance(raw_namespace, str):
- raise UserConfigError(
- "skill_distillation.namespace must be a non-empty string"
- )
- return SkillDistillationConfig(namespace=raw_namespace)
-
-
-def _skill_distillation_to_json(
- config: SkillDistillationConfig,
-) -> dict[str, object]:
- body: dict[str, object] = {}
- if config.namespace:
- body["namespace"] = config.namespace
- return body
-
-
-def load_user_config(config_dir: Path | None = None) -> UserConfig:
- """Load non-secret user config, returning defaults when absent."""
-
- data = _read_json_object(get_config_path(config_dir))
- providers_data = _mapping_value(data, "providers")
- providers: dict[str, ProviderConfig] = {}
- for name, raw_provider in providers_data.items():
- if not isinstance(raw_provider, dict):
- continue
- provider_data = cast(dict[str, object], raw_provider)
- providers[name] = ProviderConfig(base_url=_str_value(provider_data, "base_url"))
-
- launch_data = _mapping_value(data, "launch")
- launch: dict[LaunchTarget, LaunchConfig] = {}
- for target in ("claude", "codex", "openclaw"):
- raw_launch = launch_data.get(target)
- if not isinstance(raw_launch, dict):
- continue
- target_data = cast(dict[str, object], raw_launch)
- launch[target] = LaunchConfig(
- model=_str_value(target_data, "model"),
- route=_parse_launch_route(target_data.get("route")),
- )
-
- default_provider = _str_value(data, "default_provider") or DEFAULT_PROVIDER
- routing_profiles_raw = data.get("routing_profiles")
- routing_profiles = (
- cast(dict[str, object], routing_profiles_raw)
- if isinstance(routing_profiles_raw, dict) else None
- )
- return UserConfig(
- default_provider=default_provider,
- providers=providers,
- launch=launch,
- routing_profiles=routing_profiles,
- skill_distillation=_parse_skill_distillation_config(
- data.get("skill_distillation"),
- ),
- )
-
-
-def load_user_credentials(config_dir: Path | None = None) -> UserCredentials:
- """Load secret user credentials, returning empty credentials when absent."""
-
- data = _read_json_object(get_credentials_path(config_dir))
- providers_data = _mapping_value(data, "providers")
- api_keys: dict[str, str] = {}
- for name, raw_provider in providers_data.items():
- if not isinstance(raw_provider, dict):
- continue
- provider_data = cast(dict[str, object], raw_provider)
- api_key = _str_value(provider_data, "api_key")
- if api_key:
- api_keys[name] = api_key
-
- launch_data = _mapping_value(data, "launch")
- launch: dict[LaunchTarget, LaunchCredentials] = {}
- for target in ("claude", "codex", "openclaw"):
- raw_launch = launch_data.get(target)
- if not isinstance(raw_launch, dict):
- continue
- target_data = cast(dict[str, object], raw_launch)
- tier_api_keys_data = _mapping_value(target_data, "api_keys")
- tier_api_keys: dict[str, str] = {}
- for tier, raw_api_key in tier_api_keys_data.items():
- if isinstance(raw_api_key, str) and raw_api_key:
- tier_api_keys[tier] = raw_api_key
- if tier_api_keys:
- launch[target] = LaunchCredentials(api_keys=tier_api_keys)
-
- return UserCredentials(api_keys=api_keys, launch=launch)
-
-
-def _config_to_json(config: UserConfig) -> dict[str, object]:
- providers: dict[str, object] = {}
- for name, provider in (config.providers or {}).items():
- body: dict[str, object] = {}
- if provider.base_url:
- body["base_url"] = provider.base_url
- providers[name] = body
-
- launch: dict[str, object] = {}
- for target, target_config in (config.launch or {}).items():
- launch[target] = _launch_config_to_json(target_config)
-
- top: dict[str, object] = {
- "default_provider": config.default_provider,
- "providers": providers,
- "launch": launch,
- }
- if config.routing_profiles:
- top["routing_profiles"] = config.routing_profiles
- if not config.skill_distillation.is_default():
- top["skill_distillation"] = _skill_distillation_to_json(
- config.skill_distillation,
- )
- return top
-
-
-def _credentials_to_json(credentials: UserCredentials) -> dict[str, object]:
- providers: dict[str, object] = {}
- for name, api_key in (credentials.api_keys or {}).items():
- providers[name] = {"api_key": api_key}
-
- launch: dict[str, object] = {}
- for target, target_credentials in (credentials.launch or {}).items():
- api_keys = {
- tier: api_key
- for tier, api_key in (target_credentials.api_keys or {}).items()
- if api_key
- }
- if api_keys:
- launch[target] = {"api_keys": api_keys}
-
- body: dict[str, object] = {"providers": providers}
- if launch:
- body["launch"] = launch
- return body
-
-
-def _write_json(path: Path, data: dict[str, object], *, private: bool) -> None:
- path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
- tmp_path = path.with_suffix(f"{path.suffix}.tmp")
- with tmp_path.open("w") as f:
- json.dump(data, f, indent=2, sort_keys=True)
- f.write("\n")
- if private:
- os.chmod(tmp_path, 0o600)
- tmp_path.replace(path)
- if private:
- os.chmod(path, 0o600)
-
-
-def save_user_config(config: UserConfig, config_dir: Path | None = None) -> None:
- """Persist non-secret user config."""
-
- _write_json(get_config_path(config_dir), _config_to_json(config), private=False)
-
-
-def save_user_credentials(
- credentials: UserCredentials, config_dir: Path | None = None,
-) -> None:
- """Persist secret user credentials with owner-only permissions."""
-
- _write_json(
- get_credentials_path(config_dir),
- _credentials_to_json(credentials),
- private=True,
- )
-
-
-def reset_user_config(config_dir: Path | None = None) -> list[Path]:
- """Delete persisted user config and credentials, returning removed paths."""
-
- removed: list[Path] = []
- for path in (get_config_path(config_dir), get_credentials_path(config_dir)):
- if path.exists():
- path.unlink()
- removed.append(path)
- return removed
-
-
-def redact_secret(secret: str | None) -> str | None:
- """Return a display-safe representation of *secret*."""
-
- if not secret:
- return None
- if len(secret) <= 8:
- return "***"
- return f"{secret[:4]}...{secret[-4:]}"
-
-
-def build_redacted_snapshot(config_dir: Path | None = None) -> dict[str, object]:
- """Return config and credentials with secret values redacted."""
-
- config = load_user_config(config_dir)
- credentials = load_user_credentials(config_dir)
- providers: dict[str, object] = {}
- provider_names = set((config.providers or {}).keys()) | set((credentials.api_keys or {}).keys())
- for provider in sorted(provider_names):
- provider_config = config.provider(provider)
- body: dict[str, object] = {}
- if provider_config.base_url:
- body["base_url"] = provider_config.base_url
- redacted = redact_secret(credentials.api_key(provider))
- if redacted:
- body["api_key"] = redacted
- providers[provider] = body
-
- launch: dict[str, object] = {}
- for target, target_config in sorted((config.launch or {}).items()):
- body = _launch_config_to_json(target_config)
- route = _mapping_value(body, "route")
- launch_credentials = credentials.launch_target(target)
- for tier, api_key in (launch_credentials.api_keys or {}).items():
- redacted = redact_secret(api_key)
- if not redacted:
- continue
- endpoints = route.setdefault("endpoints", {})
- if not isinstance(endpoints, dict):
- endpoints = {}
- route["endpoints"] = endpoints
- endpoint = endpoints.setdefault(tier, {})
- if isinstance(endpoint, dict):
- endpoint["api_key"] = redacted
- launch[target] = body
-
- snapshot: dict[str, object] = {
- "config_path": str(get_config_path(config_dir)),
- "credentials_path": str(get_credentials_path(config_dir)),
- "default_provider": config.default_provider,
- "providers": providers,
- "launch": launch,
- "skill_distillation": _skill_distillation_to_json(
- config.skill_distillation,
- ),
- }
- if config.routing_profiles:
- # Surface only route ids — the saved bundle can carry env-var
- # references to secrets that we don't want printing to stdout.
- routes = config.routing_profiles.get("routes")
- if isinstance(routes, dict):
- snapshot["routing_profiles"] = {"route_ids": sorted(routes.keys())}
- else:
- snapshot["routing_profiles"] = {"route_ids": []}
- return snapshot
-
-
-def get_configured_launch_model(
- target: LaunchTarget, config_dir: Path | None = None,
-) -> str | None:
- """Return the configured default model for a launcher, if any."""
-
- return load_user_config(config_dir).launch_target(target).effective_route().model
-
-
-def _first_env_setting(env_vars: tuple[str, ...]) -> tuple[str | None, str | None]:
- for env_var in env_vars:
- value = os.environ.get(env_var)
- if value:
- return value, env_var
- return None, None
-
-
-def _env_prefix_from_api_key_var(env_var: str) -> str | None:
- suffix = "_API_KEY"
- if not env_var.endswith(suffix):
- return None
- return env_var.removesuffix(suffix)
-
-
-def _env_prefix_from_provider(provider: str) -> str:
- return provider.upper().replace("-", "_")
-
-
-def _provider_from_api_key_env_var(env_var: str | None) -> str | None:
- prefix = _env_prefix_from_api_key_var(env_var) if env_var is not None else None
- provider = prefix.lower().replace("_", "-") if prefix else None
- return provider if provider in _PROVIDER_BASE_URL_DEFAULTS else None
-
-
-def _default_base_url_for_provider(provider: str) -> str:
- return _PROVIDER_BASE_URL_DEFAULTS.get(provider, DEFAULT_OPENROUTER_BASE_URL)
-
-
-def _base_url_env_for_prefix(
- prefix: str | None,
- base_url_env_vars: tuple[str, ...],
-) -> str | None:
- if not prefix:
- return None
- env_var = f"{prefix}_BASE_URL"
- if env_var not in base_url_env_vars:
- return None
- value = os.environ.get(env_var)
- return value if value else None
-
-
-def _matching_base_url_env_value(
- *,
- api_key_env_var: str | None,
- provider: str,
- base_url_env_vars: tuple[str, ...],
-) -> str | None:
- """Return a base URL env var that belongs to the selected credential source.
-
- Launcher shells often contain unrelated provider variables, e.g.
- ``OPENAI_BASE_URL`` from another CLI while Switchyard's selected key
- belongs to NVIDIA. Treating the first configured base-url env var as
- global can pair a key/model with the wrong endpoint. If an API-key env var
- won, only accept the matching base-url env var; otherwise fall back to the
- configured provider.
- """
-
- from_api_key = _base_url_env_for_prefix(
- _env_prefix_from_api_key_var(api_key_env_var)
- if api_key_env_var is not None else None,
- base_url_env_vars,
- )
- if api_key_env_var is not None:
- return from_api_key
- return _base_url_env_for_prefix(
- _env_prefix_from_provider(provider),
- base_url_env_vars,
- )
-
-
-def _secrets_provider_values(
- secrets: Mapping[str, Mapping[str, object]] | None,
- *,
- secrets_section_priority: tuple[str, ...],
-) -> tuple[str | None, str | None]:
- if not secrets:
- return None, None
-
- api_key: str | None = None
- base_url: str | None = None
- for section_name in secrets_section_priority:
- section = secrets.get(section_name, {})
- if api_key is None:
- api_key = _str_value(section, "api_key")
- if base_url is None:
- base_url = _str_value(section, "base_url")
-
- if api_key is None:
- first_provider = next(iter(secrets.values()), {})
- api_key = _str_value(first_provider, "api_key")
- if base_url is None:
- base_url = _str_value(first_provider, "base_url")
-
- return api_key, base_url
-
-
-def resolve_provider_connectivity(
- *,
- cli_api_key: str | None,
- cli_base_url: str | None,
- api_key_env_vars: tuple[str, ...],
- base_url_env_vars: tuple[str, ...],
- secrets: Mapping[str, Mapping[str, object]] | None = None,
- secrets_section_priority: tuple[str, ...] = DEFAULT_SECRETS_SECTION_PRIORITY,
- default_provider: str | None = None,
- default_base_url: str = DEFAULT_OPENROUTER_BASE_URL,
- config_dir: Path | None = None,
-) -> ProviderConnectivity:
- """Resolve provider connectivity using the launcher precedence rules.
-
- Precedence:
- API key: CLI flag > environment variable > user credentials >
- repo-local secrets.json.
-
- Base URL: CLI flag > environment variable matching the selected
- API-key/provider source > user config > repo-local secrets.json >
- built-in base-url default.
- """
-
- user_config = load_user_config(config_dir)
- provider = default_provider or user_config.default_provider or DEFAULT_PROVIDER
- user_credentials = load_user_credentials(config_dir)
- secrets_api_key, secrets_base_url = _secrets_provider_values(
- secrets,
- secrets_section_priority=secrets_section_priority,
- )
-
- api_key_env_value, api_key_env_var = _first_env_setting(api_key_env_vars)
- selected_provider = _provider_from_api_key_env_var(api_key_env_var) or provider
- selected_user_provider = user_config.provider(selected_provider)
-
- api_key = (
- cli_api_key
- or api_key_env_value
- or user_credentials.api_key(provider)
- or secrets_api_key
- )
- base_url = (
- cli_base_url
- or _matching_base_url_env_value(
- api_key_env_var=api_key_env_var,
- provider=provider,
- base_url_env_vars=base_url_env_vars,
- )
- or selected_user_provider.base_url
- or secrets_base_url
- or _PROVIDER_BASE_URL_DEFAULTS.get(selected_provider, default_base_url)
- )
-
- return ProviderConnectivity(
- provider=selected_provider,
- api_key=api_key,
- base_url=base_url,
- )
diff --git a/switchyard/cli/configure_command.py b/switchyard/cli/configure_command.py
deleted file mode 100644
index b6d71d0b6..000000000
--- a/switchyard/cli/configure_command.py
+++ /dev/null
@@ -1,732 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Implementation of ``switchyard configure``."""
-
-import json
-import logging
-import os
-from collections.abc import Iterable
-from dataclasses import dataclass
-from pathlib import Path
-
-from switchyard.cli.command_utils import (
- build_launch_config_wizard,
- discover_models,
- is_interactive_terminal,
-)
-from switchyard.cli.config.user_config import (
- DEFAULT_SECRETS_SECTION_PRIORITY,
- PRIMARY_TIER,
- LaunchConfig,
- LaunchCredentials,
- LaunchRouteConfig,
- LaunchTierEndpointConfig,
- ProviderConfig,
- SkillDistillationConfig,
- UserConfig,
- UserConfigError,
- UserCredentials,
- _default_base_url_for_provider,
- build_redacted_snapshot,
- get_config_path,
- get_credentials_path,
- load_user_config,
- load_user_credentials,
- reset_user_config,
- resolve_provider_connectivity,
- save_user_config,
- save_user_credentials,
-)
-from switchyard.cli.configure_request import ConfigureRequest
-from switchyard.cli.launchers.claude_alias import claude_alias_for
-from switchyard.cli.model_catalog.model_discovery import (
- choose_default_claude_model,
- choose_default_codex_model,
- claude_model_candidates,
- codex_model_candidates,
- fetch_model_ids,
-)
-from switchyard.cli.models import ModelListRequest, ModelListTarget, render_models
-from switchyard.cli.output import format_config_snapshot
-from switchyard.cli.route_bundle import routing_profile_model_ids
-from switchyard.cli.status import StatusRequest, render_status
-from switchyard.cli.tui.launch_config_wizard import LaunchConfigWizard
-from switchyard.server.server_util import load_secrets
-
-logger = logging.getLogger(__name__)
-
-
-def _skill_distillation_args_present(request: ConfigureRequest) -> bool:
- return bool(request.disable_skill_distillation) or request.skill_distillation is not None
-
-
-def _provider_or_launcher_args_present(request: ConfigureRequest) -> bool:
- return any(
- value
- for value in (
- request.api_key,
- request.base_url,
- request.claude_model,
- request.claude_base_url,
- request.claude_api_key,
- request.codex_model,
- request.codex_base_url,
- request.codex_api_key,
- request.openclaw_model,
- request.openclaw_base_url,
- request.openclaw_api_key,
- )
- ) or request.routing_profiles is not None
-
-
-def _skill_only_config_update(request: ConfigureRequest) -> bool:
- return (
- _skill_distillation_args_present(request)
- and not _provider_or_launcher_args_present(request)
- )
-
-
-def _apply_skill_distillation_args(
- existing: SkillDistillationConfig,
- request: ConfigureRequest,
-) -> SkillDistillationConfig:
- if request.disable_skill_distillation:
- if request.skill_distillation is not None:
- raise UserConfigError(
- "--disable-skill-distillation cannot be combined with "
- "--skill-distillation"
- )
- return SkillDistillationConfig()
-
- return SkillDistillationConfig(
- namespace=(
- request.skill_distillation
- if request.skill_distillation is not None
- else existing.namespace
- ),
- )
-
-
-@dataclass(frozen=True)
-class _LaunchEndpointSelection:
- """Configure-time endpoint choice for one launch tier."""
-
- endpoint: LaunchTierEndpointConfig | None
- api_key: str | None
- effective_base_url: str
- effective_api_key: str
-
-
-def _endpoint_override(
- base_url: str | None,
- *,
- default_base_url: str,
-) -> LaunchTierEndpointConfig | None:
- if not base_url or base_url == default_base_url:
- return None
- return LaunchTierEndpointConfig(base_url=base_url)
-
-
-def _api_key_override(api_key: str | None, *, default_api_key: str) -> str | None:
- if not api_key or api_key == default_api_key:
- return None
- return api_key
-
-
-def _select_launch_endpoint(
- *,
- wizard: LaunchConfigWizard | None,
- interactive: bool,
- label: str,
- cli_base_url: str | None,
- cli_api_key: str | None,
- existing_endpoint: LaunchTierEndpointConfig,
- existing_api_key: str | None,
- default_base_url: str,
- default_api_key: str,
-) -> _LaunchEndpointSelection:
- """Resolve configure-time endpoint overrides for one launch tier."""
-
- existing_base_url = existing_endpoint.base_url
- existing_effective_base_url = existing_base_url or default_base_url
- existing_effective_api_key = existing_api_key or default_api_key
- if cli_base_url or cli_api_key:
- effective_base_url = cli_base_url or existing_effective_base_url
- effective_api_key = cli_api_key or existing_effective_api_key
- return _LaunchEndpointSelection(
- endpoint=_endpoint_override(
- effective_base_url,
- default_base_url=default_base_url,
- ),
- api_key=_api_key_override(
- effective_api_key,
- default_api_key=default_api_key,
- ),
- effective_base_url=effective_base_url,
- effective_api_key=effective_api_key,
- )
-
- has_existing_override = bool(existing_base_url or existing_api_key)
- if interactive and wizard:
- mode = wizard.select_endpoint_mode(
- label,
- default="custom" if has_existing_override else "default",
- )
- if mode == "default":
- return _LaunchEndpointSelection(
- endpoint=None,
- api_key=None,
- effective_base_url=default_base_url,
- effective_api_key=default_api_key,
- )
- effective_base_url = wizard.prompt_endpoint_base_url(
- label,
- existing_effective_base_url,
- )
- effective_api_key = wizard.prompt_endpoint_api_key(
- label,
- existing_effective_api_key,
- )
- return _LaunchEndpointSelection(
- endpoint=_endpoint_override(
- effective_base_url,
- default_base_url=default_base_url,
- ),
- api_key=_api_key_override(
- effective_api_key,
- default_api_key=default_api_key,
- ),
- effective_base_url=effective_base_url,
- effective_api_key=effective_api_key,
- )
-
- return _LaunchEndpointSelection(
- endpoint=_endpoint_override(
- existing_effective_base_url,
- default_base_url=default_base_url,
- ),
- api_key=_api_key_override(
- existing_effective_api_key,
- default_api_key=default_api_key,
- ),
- effective_base_url=existing_effective_base_url,
- effective_api_key=existing_effective_api_key,
- )
-
-
-def _route_endpoints(
- primary: _LaunchEndpointSelection,
-) -> dict[str, LaunchTierEndpointConfig] | None:
- endpoints: dict[str, LaunchTierEndpointConfig] = {}
- if primary.endpoint:
- endpoints[PRIMARY_TIER] = primary.endpoint
- return endpoints or None
-
-
-def _launch_credentials(
- primary: _LaunchEndpointSelection,
-) -> LaunchCredentials:
- api_keys: dict[str, str] = {}
- if primary.api_key:
- api_keys[PRIMARY_TIER] = primary.api_key
- return LaunchCredentials(api_keys=api_keys or None)
-
-
-def _read_routing_profiles_file(path: str) -> dict[str, object]:
- """Read and parse a routing-profiles YAML file into a JSON-storable dict.
-
- Env-var references (``${VAR}``) inside the YAML are preserved as
- literal strings; they expand at *load* time on each
- ``serve`` / ``launch`` run, not now. This means saving a bundle on
- one machine and using it on another picks up the *local* environment.
- """
- resolved = Path(path).expanduser()
- try:
- raw = resolved.read_text()
- except FileNotFoundError as exc:
- raise SystemExit(
- f"configure --routing-profiles: file not found: {resolved}"
- ) from exc
- except OSError as exc:
- raise SystemExit(
- f"configure --routing-profiles: cannot read {resolved}: {exc}"
- ) from exc
-
- import yaml # type: ignore[import-untyped,unused-ignore]
- try:
- parsed = yaml.safe_load(raw) or {}
- except yaml.YAMLError as exc:
- raise SystemExit(
- f"configure --routing-profiles: invalid YAML in {resolved}: {exc}"
- ) from exc
- if not isinstance(parsed, dict):
- raise SystemExit(
- f"configure --routing-profiles: {resolved} must contain a YAML "
- "mapping (got a list or scalar at the top level)"
- )
- return parsed
-
-
-def _bundle_default_credential(
- bundle: dict[str, object] | None, key: str
-) -> str | None:
- """Return the env-expanded ``defaults.<key>`` from a route bundle, if set.
-
- A saved bundle keeps ``${VAR}`` literal for portability; configure needs the
- concrete value now, so expand it here (the same way serve/launch do at load
- time). An unset ``${VAR}`` stays literal after expansion, so a result that is
- empty or still contains ``${`` is treated as unresolved.
- """
- if not bundle:
- return None
- defaults = bundle.get("defaults")
- if not isinstance(defaults, dict):
- return None
- raw = defaults.get(key)
- if not isinstance(raw, str) or not raw:
- return None
- expanded = os.path.expandvars(raw)
- if not expanded or "${" in expanded:
- return None
- return expanded
-
-
-def _discover_models_for_endpoint(
- *,
- cache: dict[tuple[str, str], list[str]],
- base_url: str,
- api_key: str,
- disabled: bool,
-) -> list[str]:
- key = (base_url, api_key)
- if key not in cache:
- cache[key] = discover_models(base_url, api_key, disabled=disabled)
- return cache[key]
-
-
-def _merge_candidate_ids(*sources: Iterable[str]) -> list[str]:
- """Return the union of model-id sources in first-seen order."""
- seen: set[str] = set()
- merged: list[str] = []
- for source in sources:
- for value in source:
- if value and value not in seen:
- seen.add(value)
- merged.append(value)
- return merged
-
-
-def _list_models(request: ConfigureRequest) -> None:
- """Print a ranked list of backend models — fold of ``switchyard models``."""
- from switchyard.server.server_util import load_secrets
-
- connectivity = resolve_provider_connectivity(
- cli_api_key=request.api_key,
- cli_base_url=request.base_url,
- api_key_env_vars=("OPENROUTER_API_KEY", "NVIDIA_API_KEY", "OPENAI_API_KEY"),
- base_url_env_vars=("OPENROUTER_BASE_URL", "NVIDIA_BASE_URL", "OPENAI_BASE_URL"),
- secrets=load_secrets(),
- secrets_section_priority=DEFAULT_SECRETS_SECTION_PRIORITY,
- default_provider=request.provider,
- )
- if not connectivity.api_key:
- raise SystemExit(
- "configure --list-models: no API key resolved. Run "
- "`switchyard configure`, set OPENROUTER_API_KEY, or pass --api-key."
- )
- model_ids = fetch_model_ids(connectivity.base_url, connectivity.api_key)
- # `--target provider` is meaningful for `configure` setup but not for
- # model ranking; collapse it to `all` so the renderer treats the
- # ranking target as the launcher-neutral default.
- raw_target = request.target
- target: ModelListTarget
- if raw_target == "claude":
- target = "claude"
- elif raw_target == "codex":
- target = "codex"
- else:
- target = "all"
- print(render_models(
- model_ids,
- ModelListRequest(
- target=target,
- query=request.query,
- limit=request.limit,
- ),
- ))
-
-
-def cmd_configure(request: ConfigureRequest) -> None:
- """Set, show, or reset user-level launcher defaults."""
-
- if request.list_models:
- _list_models(request)
- return
-
- if request.show:
- snapshot = build_redacted_snapshot()
- if request.json:
- print(json.dumps(snapshot, indent=2, sort_keys=True))
- return
- print(format_config_snapshot(snapshot))
- print()
- print(render_status(
- StatusRequest(
- cli_api_key=request.api_key,
- cli_base_url=request.base_url,
- provider=request.provider,
- check=request.check,
- secrets=load_secrets(),
- ),
- ))
- return
-
- if request.reset:
- removed = reset_user_config()
- if removed:
- print("Removed Switchyard user config:")
- for path in removed:
- print(f" {path}")
- else:
- print("No Switchyard user config found.")
- return
-
- target_scope = request.target
- configure_claude = target_scope in ("all", "claude")
- configure_codex = target_scope in ("all", "codex")
- configure_openclaw = target_scope in ("all", "openclaw")
- existing_config = load_user_config()
- existing_credentials = load_user_credentials()
- # A CLI --provider wins; otherwise honor the saved default_provider so the
- # save path doesn't overwrite it with the argparse fallback.
- provider = request.provider or existing_config.default_provider
- skill_distillation = _apply_skill_distillation_args(
- existing_config.skill_distillation,
- request,
- )
- if _skill_only_config_update(request):
- save_user_config(
- UserConfig(
- default_provider=existing_config.default_provider,
- providers=existing_config.providers,
- launch=existing_config.launch,
- routing_profiles=existing_config.routing_profiles,
- skill_distillation=skill_distillation,
- ),
- )
- print(f"Saved Switchyard config to {get_config_path()}")
- return
-
- existing_provider = existing_config.provider(provider)
- existing_claude = existing_config.launch_target("claude")
- existing_codex = existing_config.launch_target("codex")
- existing_openclaw = existing_config.launch_target("openclaw")
- existing_claude_credentials = existing_credentials.launch_target("claude")
- existing_codex_credentials = existing_credentials.launch_target("codex")
- existing_openclaw_credentials = existing_credentials.launch_target("openclaw")
- reuse_existing_provider = request.reuse_existing_provider
- interactive = is_interactive_terminal()
- wizard = build_launch_config_wizard(request.no_tui) if interactive else None
- if wizard:
- wizard.start(target=target_scope)
-
- # Resolve the routing-profiles bundle now (global/CLI --routing-profiles, or
- # the saved bundle). The interactive wizard can still offer one below when no
- # path was given. Loading it here lets non-interactive `configure` fall back
- # to the bundle's env-expanded defaults.api_key/base_url for credentials, the
- # same way serve/launch read that bundle.
- routing_profiles = existing_config.routing_profiles
- if request.routing_profiles is not None:
- # Empty string clears, any other value is a path whose YAML we parse.
- routing_profiles = (
- _read_routing_profiles_file(request.routing_profiles)
- if request.routing_profiles else None
- )
- bundle_api_key = _bundle_default_credential(routing_profiles, "api_key")
- bundle_base_url = _bundle_default_credential(routing_profiles, "base_url")
-
- base_url_default = (
- existing_provider.base_url
- or bundle_base_url
- or _default_base_url_for_provider(provider)
- )
- if request.base_url:
- base_url = request.base_url
- elif reuse_existing_provider and existing_provider.base_url:
- base_url = existing_provider.base_url
- elif interactive and wizard:
- base_url = wizard.prompt_default_base_url(base_url_default)
- else:
- base_url = base_url_default
-
- api_key = request.api_key
- if not api_key:
- existing_api_key = existing_credentials.api_key(provider)
- # Fall back to the selected provider's own env key so non-interactive
- # `configure` (no --api-key, no saved key) picks up e.g. OPENROUTER_API_KEY
- # instead of erroring that it "requires an API key". Read only the
- # provider's own <PROVIDER>_API_KEY so `configure --provider nvidia` can't
- # save another provider's key under `nvidia`; if that var isn't set we
- # fall through to the route-bundle key, then require --api-key.
- env_prefix = provider.upper().replace("-", "_")
- env_api_key = os.environ.get(f"{env_prefix}_API_KEY")
- prompt_default_api_key = (
- existing_api_key
- or request.prompt_default_api_key
- or env_api_key
- or bundle_api_key
- )
- prompt_default_api_key_source = request.prompt_default_api_key_source
- if reuse_existing_provider and existing_api_key:
- api_key = existing_api_key
- elif interactive and wizard:
- api_key = wizard.prompt_default_api_key(
- prompt_default_api_key,
- default_source=prompt_default_api_key_source,
- )
- else:
- api_key = prompt_default_api_key
- if not api_key:
- raise SystemExit(
- "configure requires an API key. Pass --api-key or run in an "
- "interactive terminal."
- )
-
- model_catalog_cache: dict[tuple[str, str], list[str]] = {}
-
- def _models_for(selection: _LaunchEndpointSelection) -> list[str]:
- return _discover_models_for_endpoint(
- cache=model_catalog_cache,
- base_url=selection.effective_base_url,
- api_key=selection.effective_api_key,
- disabled=request.no_model_discovery,
- )
-
- # A global/CLI --routing-profiles path (or the saved bundle) was already
- # loaded above; only the interactive prompt for a fresh path remains. The
- # resolved bundle also feeds the model picker below so it can surface route
- # ids + their tier models (e.g. `opus-ds-stage_router`) alongside the raw
- # `/v1/models` catalog, not just the upstream response.
- if request.routing_profiles is None and interactive and wizard:
- prompted = wizard.prompt_routing_profiles(default=None)
- if prompted:
- routing_profiles = _read_routing_profiles_file(prompted)
- routing_profile_models = routing_profile_model_ids(routing_profiles)
- # When a routing-profiles bundle is in play, its first route is the model a
- # launcher sends by default (the launcher seeds the agent with
- # `table.registered_models()[0]`). Make that the configured model default
- # too so `configure` and `launch` agree; an explicit `--*-model` still wins.
- default_route_model = routing_profile_models[0] if routing_profile_models else None
- # Claude Code's gateway-discovery filter only accepts `claude-`/`anthropic-`
- # prefixed ids. The claude launcher registers each route under both spellings
- # via `_with_claude_aliases`; save the prefixed form here so configure and
- # the launcher pick the same default.
- default_claude_route_model = default_route_model
- if default_claude_route_model is not None:
- default_claude_route_model = (
- claude_alias_for(default_claude_route_model) or default_claude_route_model
- )
-
- existing_claude_route = existing_claude.effective_route()
- claude_model = existing_claude_route.model
- claude_primary_endpoint: _LaunchEndpointSelection | None = None
- if configure_claude:
- claude_primary_endpoint = _select_launch_endpoint(
- wizard=wizard,
- interactive=interactive,
- label="Claude Code",
- cli_base_url=request.claude_base_url,
- cli_api_key=request.claude_api_key,
- existing_endpoint=existing_claude_route.endpoint(PRIMARY_TIER),
- existing_api_key=existing_claude_credentials.api_key(PRIMARY_TIER),
- default_base_url=base_url,
- default_api_key=api_key,
- )
- claude_model_ids = _merge_candidate_ids(
- routing_profile_models, _models_for(claude_primary_endpoint)
- )
- discovered_claude = choose_default_claude_model(claude_model_ids)
- claude_default = (
- request.claude_model
- or default_claude_route_model
- or existing_claude_route.model
- or discovered_claude
- )
- if not claude_default and not interactive:
- raise SystemExit(
- "No Claude model configured or discovered. Pass --claude-model "
- "or run interactively."
- )
-
- if request.claude_model:
- claude_model = request.claude_model
- elif interactive and wizard:
- claude_model = wizard.select_model(
- "Claude Code",
- preferred_model_ids=claude_model_candidates(claude_model_ids),
- all_model_ids=claude_model_ids,
- default=claude_default,
- )
- else:
- claude_model = claude_default
-
- existing_codex_route = existing_codex.effective_route()
- codex_model = existing_codex_route.model
- codex_primary_endpoint: _LaunchEndpointSelection | None = None
- if configure_codex:
- codex_primary_endpoint = _select_launch_endpoint(
- wizard=wizard,
- interactive=interactive,
- label="Codex",
- cli_base_url=request.codex_base_url,
- cli_api_key=request.codex_api_key,
- existing_endpoint=existing_codex_route.endpoint(PRIMARY_TIER),
- existing_api_key=existing_codex_credentials.api_key(PRIMARY_TIER),
- default_base_url=base_url,
- default_api_key=api_key,
- )
- codex_model_ids = _merge_candidate_ids(
- routing_profile_models, _models_for(codex_primary_endpoint)
- )
- discovered_codex = choose_default_codex_model(codex_model_ids)
- codex_default = (
- request.codex_model
- or default_route_model
- or existing_codex_route.model
- or discovered_codex
- )
- if not codex_default and not interactive:
- raise SystemExit(
- "No Codex model configured or discovered. Pass --codex-model "
- "or run interactively."
- )
-
- if request.codex_model:
- codex_model = request.codex_model
- elif interactive and wizard:
- codex_model = wizard.select_model(
- "Codex",
- preferred_model_ids=codex_model_candidates(codex_model_ids),
- all_model_ids=codex_model_ids,
- default=codex_default,
- )
- else:
- codex_model = codex_default
-
- existing_openclaw_route = existing_openclaw.effective_route()
- openclaw_model = existing_openclaw_route.model
- openclaw_primary_endpoint: _LaunchEndpointSelection | None = None
- if configure_openclaw:
- openclaw_primary_endpoint = _select_launch_endpoint(
- wizard=wizard,
- interactive=interactive,
- label="OpenClaw",
- cli_base_url=request.openclaw_base_url,
- cli_api_key=request.openclaw_api_key,
- existing_endpoint=existing_openclaw_route.endpoint(PRIMARY_TIER),
- existing_api_key=existing_openclaw_credentials.api_key(PRIMARY_TIER),
- default_base_url=base_url,
- default_api_key=api_key,
- )
- openclaw_model_ids = _merge_candidate_ids(
- routing_profile_models, _models_for(openclaw_primary_endpoint)
- )
- # OpenClaw and Codex both speak OpenAI Chat Completions to the
- # backend, so the Codex preference ranking is a reasonable default
- # until OpenClaw-specific signals emerge.
- discovered_openclaw = choose_default_codex_model(openclaw_model_ids)
- openclaw_default = (
- request.openclaw_model
- or default_route_model
- or existing_openclaw_route.model
- or discovered_openclaw
- )
- if not openclaw_default and not interactive:
- raise SystemExit(
- "No OpenClaw model configured or discovered. Pass "
- "--openclaw-model or run interactively."
- )
-
- if request.openclaw_model:
- openclaw_model = request.openclaw_model
- elif interactive and wizard:
- openclaw_model = wizard.select_model(
- "OpenClaw",
- preferred_model_ids=codex_model_candidates(openclaw_model_ids),
- all_model_ids=openclaw_model_ids,
- default=openclaw_default,
- )
- else:
- openclaw_model = openclaw_default
-
- providers = dict(existing_config.providers or {})
- providers[provider] = ProviderConfig(base_url=base_url)
- launch = dict(existing_config.launch or {})
- if configure_claude:
- if claude_primary_endpoint is None:
- raise AssertionError("Claude endpoint selection was not resolved")
- launch["claude"] = LaunchConfig(
- model=claude_model,
- route=LaunchRouteConfig(
- type="single",
- model=claude_model,
- endpoints=_route_endpoints(primary=claude_primary_endpoint),
- ),
- )
- if configure_codex:
- if codex_primary_endpoint is None:
- raise AssertionError("Codex endpoint selection was not resolved")
- launch["codex"] = LaunchConfig(
- model=codex_model,
- route=LaunchRouteConfig(
- type="single",
- model=codex_model,
- endpoints=_route_endpoints(primary=codex_primary_endpoint),
- ),
- )
- if configure_openclaw:
- if openclaw_primary_endpoint is None:
- raise AssertionError("OpenClaw endpoint selection was not resolved")
- launch["openclaw"] = LaunchConfig(
- model=openclaw_model,
- route=LaunchRouteConfig(
- type="single",
- model=openclaw_model,
- endpoints=_route_endpoints(primary=openclaw_primary_endpoint),
- ),
- )
- save_user_config(
- UserConfig(
- default_provider=provider,
- providers=providers,
- launch=launch,
- routing_profiles=routing_profiles,
- skill_distillation=skill_distillation,
- ),
- )
-
- api_keys = dict(existing_credentials.api_keys or {})
- api_keys[provider] = api_key
- launch_credentials = dict(existing_credentials.launch or {})
- if configure_claude:
- if claude_primary_endpoint is None:
- raise AssertionError("Claude endpoint selection was not resolved")
- launch_credentials["claude"] = _launch_credentials(claude_primary_endpoint)
- if configure_codex:
- if codex_primary_endpoint is None:
- raise AssertionError("Codex endpoint selection was not resolved")
- launch_credentials["codex"] = _launch_credentials(codex_primary_endpoint)
- if configure_openclaw:
- if openclaw_primary_endpoint is None:
- raise AssertionError("OpenClaw endpoint selection was not resolved")
- launch_credentials["openclaw"] = _launch_credentials(openclaw_primary_endpoint)
- save_user_credentials(
- UserCredentials(api_keys=api_keys, launch=launch_credentials),
- )
-
- print(f"Saved Switchyard config to {get_config_path()}")
- print(f"Saved Switchyard credentials to {get_credentials_path()}")
-
-
-__all__ = ["cmd_configure"]
diff --git a/switchyard/cli/configure_request.py b/switchyard/cli/configure_request.py
deleted file mode 100644
index 70495dde6..000000000
--- a/switchyard/cli/configure_request.py
+++ /dev/null
@@ -1,81 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""The typed inputs for ``switchyard configure``.
-
-This is the one place that lists every field ``cmd_configure`` reads, and the
-default for each. Two callers build it: the ``configure`` CLI command (via
-``from_namespace``) and first-run launch setup (via the constructor). Because
-both build the same type, a field the command needs but a caller forgets is
-caught by mypy or at construction time — not as an ``AttributeError`` deep
-inside ``cmd_configure`` after the user has already started a launch.
-"""
-
-import argparse
-from dataclasses import dataclass, fields
-from typing import Literal
-
-# Which defaults `configure` writes. Matches the CLI's --target choices.
-ConfigureTarget = Literal["all", "provider", "claude", "codex", "openclaw"]
-
-
-@dataclass(frozen=True, kw_only=True)
-class ConfigureRequest:
- """Everything ``cmd_configure`` reads. Each default lives here, once."""
-
- # One of these picks a mode (matches the CLI's mutually-exclusive group).
- show: bool = False
- reset: bool = False
- list_models: bool = False
- skill_distillation: str | None = None
- disable_skill_distillation: bool = False
-
- # Which provider and scope to configure.
- json: bool = False
- target: ConfigureTarget = "all"
- provider: str | None = None
- base_url: str | None = None
- api_key: str | None = None
-
- # Per-launcher endpoint overrides. None means "use the provider default".
- claude_model: str | None = None
- claude_base_url: str | None = None
- claude_api_key: str | None = None
- codex_model: str | None = None
- codex_base_url: str | None = None
- codex_api_key: str | None = None
- openclaw_model: str | None = None
- openclaw_base_url: str | None = None
- openclaw_api_key: str | None = None
-
- # Cross-cutting behavior. routing_profiles is the global --routing-profiles
- # flag, merged in here so configure sees it alongside the rest.
- routing_profiles: str | None = None
- no_model_discovery: bool = False
- no_tui: bool = False
-
- # Extra inputs for the read-only --show / --list-models modes.
- query: str | None = None
- limit: int = 50
- check: bool = False
-
- # Set only by first-run launch setup; the CLI has no flags for these.
- reuse_existing_provider: bool = False
- prompt_default_api_key: str | None = None
- prompt_default_api_key_source: str | None = None
-
- @classmethod
- def from_namespace(cls, ns: argparse.Namespace) -> "ConfigureRequest":
- """Build a request from parsed CLI args.
-
- This is the single spot where the loosely-typed argparse namespace
- becomes a typed request. argparse fills every configure flag plus the
- global routing_profiles; the launch-setup-only fields fall back to the
- defaults above. Unknown namespace attributes (argparse's own ``func``,
- etc.) are dropped so they can't leak in.
- """
- known = {field.name for field in fields(cls)}
- return cls(**{key: value for key, value in vars(ns).items() if key in known})
-
-
-__all__ = ["ConfigureRequest", "ConfigureTarget"]
diff --git a/switchyard/cli/config/__init__.py b/switchyard/cli/defaults/__init__.py
similarity index 75%
rename from switchyard/cli/config/__init__.py
rename to switchyard/cli/defaults/__init__.py
index 3d4f4eb5b..b762f67df 100644
--- a/switchyard/cli/config/__init__.py
+++ b/switchyard/cli/defaults/__init__.py
@@ -1,5 +1,4 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Persistent CLI configuration helpers."""
-
+"""Packaged launcher deployment defaults."""
diff --git a/switchyard/cli/defaults/openrouter.toml b/switchyard/cli/defaults/openrouter.toml
new file mode 100644
index 000000000..94405c249
--- /dev/null
+++ b/switchyard/cli/defaults/openrouter.toml
@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+schema_version = 1
+
+[llm_clients.openrouter]
+format = "openai_chat"
+base_url = "https://openrouter.ai/api/v1"
+api_key_env = "OPENROUTER_API_KEY"
+
+[targets.classifier]
+id = "google/gemini-3.5-flash"
+llm_client = "openrouter"
+
+[targets.strong]
+id = "anthropic/claude-opus-4.7"
+llm_client = "openrouter"
+
+[targets.weak]
+id = "moonshotai/kimi-k2.7-code"
+llm_client = "openrouter"
+
+[routes.switchyard]
+id = "switchyard"
+type = "llm_classifier"
+classifier_target = "classifier"
+strong_target = "strong"
+weak_target = "weak"
+base_threshold = 0.5
+min_confidence = 0.0
+session_affinity = true
+message_hash_fallback = true
diff --git a/switchyard/cli/intake_cli_config.py b/switchyard/cli/intake_cli_config.py
index d37d0b19a..814ddac0b 100644
--- a/switchyard/cli/intake_cli_config.py
+++ b/switchyard/cli/intake_cli_config.py
@@ -1,7 +1,7 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Shared CLI/env resolution for intake options."""
+"""Resolve Intake options for ``switchyard serve``."""
import argparse
import os
@@ -11,16 +11,12 @@ from dataclasses import dataclass
@dataclass(frozen=True)
class IntakeCliConfig:
- """Resolved intake options shared by server and launcher CLI paths."""
+ """Resolved Intake options for the Python server."""
enabled: bool
base_url: str | None = None
workspace: str | None = None
api_key: str | None = None
- app: str | None = None
- task: str | None = None
- session_id: str | None = None
- user_id: str | None = None
target_url: str | None = None
@classmethod
@@ -43,35 +39,6 @@ class IntakeCliConfig:
),
)
- @classmethod
- def from_launch_args(
- cls,
- args: argparse.Namespace,
- *,
- env: Mapping[str, str] | None = None,
- ) -> "IntakeCliConfig":
- resolved_env = os.environ if env is None else env
- base_url, workspace, api_key = _resolve_sink_connection(args, resolved_env)
- return cls(
- enabled=bool(getattr(args, "intake_enabled", False))
- or _env_bool("SWITCHYARD_INTAKE_ENABLED", resolved_env),
- base_url=base_url,
- workspace=workspace,
- api_key=api_key,
- app=_arg_or_env(args, "intake_app", resolved_env, "SWITCHYARD_INTAKE_APP"),
- task=_arg_or_env(args, "intake_task", resolved_env, "SWITCHYARD_INTAKE_TASK"),
- session_id=_arg_or_env(
- args, "intake_session_id", resolved_env, "SWITCHYARD_SESSION_ID",
- ),
- user_id=_arg_or_env(
- args, "intake_user_id", resolved_env, "SWITCHYARD_USER_ID",
- ),
- target_url=_arg_or_env(
- args, "intake_target_url", resolved_env, "SWITCHYARD_INTAKE_TARGET_URL",
- ),
- )
-
-
def _resolve_sink_connection(
args: argparse.Namespace,
env: Mapping[str, str],
diff --git a/switchyard/cli/launch_command.py b/switchyard/cli/launch_command.py
index 435e17383..94d08c190 100644
--- a/switchyard/cli/launch_command.py
+++ b/switchyard/cli/launch_command.py
@@ -1,1140 +1,60 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Implement ``switchyard launch`` subcommands."""
+"""Launch coding agents against an explicit native Switchyard deployment."""
import argparse
-import logging
-import os
-from dataclasses import replace
-from importlib import import_module
-from typing import Protocol, cast
+from pathlib import Path
-from switchyard.cli.command_utils import (
- is_interactive_terminal,
- strip_forwarded_args,
-)
-from switchyard.cli.config.user_config import (
- DEFAULT_SECRETS_SECTION_PRIORITY,
- PRIMARY_TIER,
- WEAK_TIER,
- LaunchRouteConfig,
- LaunchTarget,
- LaunchTierEndpointConfig,
- ProviderConnectivity,
- load_user_config,
- load_user_credentials,
- resolve_provider_connectivity,
-)
-from switchyard.cli.configure_command import cmd_configure
-from switchyard.cli.configure_request import ConfigureRequest, ConfigureTarget
-from switchyard.cli.intake_cli_config import IntakeCliConfig
-from switchyard.cli.launchers.launch_intake_config import LaunchIntakeConfig
-from switchyard.cli.output import format_dry_run
-from switchyard.cli.routing import (
- LaunchTierConnectivity,
- build_deterministic_routing_config,
- require_route_model,
-)
-from switchyard.lib import startup_timing
-from switchyard.lib.backends.llm_target import BackendFormat
-from switchyard.lib.profiles.random_routing import (
- RandomRoutingConfig,
-)
-from switchyard.server.server_util import load_secrets, resolve_rl_log_dir
+from switchyard.cli.command_utils import strip_forwarded_args
-logger = logging.getLogger(__name__)
-
-
-class _YamlModule(Protocol):
- def safe_dump(
- self,
- data: object,
- stream: object,
- sort_keys: bool = ...,
- ) -> object: ...
-
-
-def _api_key_prompt_default_source(
- args: argparse.Namespace,
- api_key_env_vars: tuple[str, ...],
- resolved_api_key: str | None,
-) -> str | None:
- if args.api_key or not resolved_api_key:
- return None
- for env_var in api_key_env_vars:
- if os.environ.get(env_var) == resolved_api_key:
- return f"${env_var}"
- return None
-
-
-def _resolve_launch_connectivity(
- args: argparse.Namespace,
- api_key_env_vars: tuple[str, ...],
-) -> ProviderConnectivity:
- """Resolve launch credentials without inheriting repo secrets port."""
-
- return resolve_provider_connectivity(
- cli_api_key=args.api_key,
- cli_base_url=args.base_url,
- api_key_env_vars=api_key_env_vars,
- base_url_env_vars=("OPENROUTER_BASE_URL", "NVIDIA_BASE_URL", "OPENAI_BASE_URL"),
- secrets=load_secrets(),
- secrets_section_priority=DEFAULT_SECRETS_SECTION_PRIORITY,
- )
-
-
-def resolve_launch_connectivity(
- args: argparse.Namespace,
- api_key_env_vars: tuple[str, ...],
-) -> tuple[str | None, str]:
- """Resolve launch credentials without inheriting repo secrets port."""
-
- connectivity = _resolve_launch_connectivity(
- args,
- api_key_env_vars=api_key_env_vars,
- )
- return connectivity.api_key, connectivity.base_url
-
-
-# Marker for the OpenRouter gateway. The zero-flag deterministic default trio
-# uses OpenRouter-only model ids, so a resolved endpoint that isn't OpenRouter
-# cannot serve them.
-_OPENROUTER_URL_MARKER = "openrouter.ai"
-
-
-def _reject_openrouter_only_default_trio(target: str, base_url: str) -> None:
- """Fail fast when the zero-config default trio can't reach the provider.
-
- The deterministic zero-flag default uses OpenRouter-only model ids
- (``anthropic/claude-opus-4.7`` / ``moonshotai/kimi-k2.6`` /
- ``google/gemini-3.5-flash``). This runs only on the deterministic path, so
- ``--model`` has already been ruled out, and ``--weak-model`` /
- ``--classifier-model`` do not help because the strong tier stays
- ``anthropic/claude-opus-4.7``. So when the resolved endpoint is not
- OpenRouter, raise :class:`SystemExit` pointing the user at ``--model``,
- ``--routing-profiles``, or ``OPENROUTER_API_KEY`` instead of launching a
- trio that can't work.
- """
- if _OPENROUTER_URL_MARKER in base_url:
- return
- raise SystemExit(
- f"launch {target}: the zero-config default trio "
- f"(anthropic/claude-opus-4.7, moonshotai/kimi-k2.6, "
- f"google/gemini-3.5-flash) is OpenRouter-only, but the resolved "
- f"endpoint is {base_url!r}. Pass --model, use --routing-profiles, or "
- f"set OPENROUTER_API_KEY."
- )
-
-
-def _is_deterministic_launch(
- target: str,
- args: argparse.Namespace,
- route: LaunchRouteConfig | None,
- routing_profiles: str | None,
-) -> bool:
- """Return ``True`` when the resolved launch will use deterministic routing.
-
- For ``claude`` / ``codex``: deterministic is the implicit default when
- no single-model passthrough (CLI ``--model`` or saved
- ``configured_route.model``) and no routing-profiles bundle (CLI
- ``--routing-profiles`` or saved bundle) is in play. Pass
- ``route=None`` to check before the route is resolved (e.g. inside
- :func:`launch_requirements_satisfied`); the resolver inspects
- ``args.model`` and the saved single-model config directly.
-
- For ``openclaw``: same implicit default as claude/codex (the legacy
- ``--deterministic`` opt-in flag was removed).
- """
- if target not in ("claude", "codex", "openclaw"):
- return False
- if routing_profiles:
- return False
- if route is not None:
- return not route.model
- # Pre-resolution check: replicate route_from_launch_args' "args.model
- # wins, else configured_route.model" lookup without re-running the merge.
- if getattr(args, "model", None):
- return False
- target_key = cast(LaunchTarget, target)
- configured_launch = load_user_config().launch_target(target_key)
- configured_route = configured_launch.effective_route()
- return not configured_route.model
-
-
-_SAVED_BUNDLE_TEMPFILES: list[str] = []
-
-
-def _materialize_saved_bundle(bundle: dict[str, object]) -> str:
- """Re-serialize a saved bundle dict to a YAML tempfile and return its path.
-
- The launcher's downstream API takes a YAML path; saved bundles are
- stored as parsed dicts in ``config.json``. The tempfile is retained
- for the process lifetime so the launcher's per-request reads keep
- working without re-materializing each time.
- """
- import tempfile
-
- yaml = cast(_YamlModule, import_module("yaml"))
- fd = tempfile.NamedTemporaryFile(
- mode="w", suffix=".yaml", delete=False, prefix="switchyard-routes-",
- )
- try:
- yaml.safe_dump(bundle, fd, sort_keys=False)
- finally:
- fd.close()
- _SAVED_BUNDLE_TEMPFILES.append(fd.name)
- return fd.name
-
-
-def _resolve_routing_profiles(args: argparse.Namespace) -> str | None:
- """Resolve the routing-profile YAML path for a launch.
-
- Precedence:
- CLI ``--routing-profiles PATH`` > saved parsed bundle in
- ``UserConfig.routing_profiles`` (only when no ``--model`` is on
- the CLI).
-
- Passing ``--model X`` alone is an explicit opt-in to a single-model
- launch; the saved bundle is *not* injected on top. When the fallback
- fires we re-serialize the saved bundle to a tempfile (the launcher
- API takes a path).
- """
- if args.routing_profiles:
- return cast(str, args.routing_profiles)
- if args.model:
- return None
- saved = load_user_config().routing_profiles
- if not saved:
- return None
- return _materialize_saved_bundle(saved)
-
-
-def _resolve_initial_from_profiles(*, target: str, routing_profiles: str) -> str:
- """Return the first route key from *routing_profiles*."""
- from switchyard.cli.route_bundle import (
- parse_routing_profiles_file,
- routing_profile_model_ids,
- )
-
- ids = routing_profile_model_ids(parse_routing_profiles_file(routing_profiles))
- if not ids:
- raise SystemExit(
- f"launch {target}: --routing-profiles file has no routes; "
- f"add at least one route."
- )
- return ids[0]
-
-
-def launch_requirements_satisfied(
- args: argparse.Namespace,
- target: str,
- api_key_env_vars: tuple[str, ...],
-) -> bool:
- if bool(getattr(args, "reconfigure", False)):
- return False
- api_key, _base_url = resolve_launch_connectivity(
- args,
- api_key_env_vars=api_key_env_vars,
- )
- routing_profiles = getattr(args, "routing_profiles", None)
- target_key = cast(LaunchTarget, target)
- user_config = load_user_config()
- configured_launch = user_config.launch_target(target_key)
- configured_route = configured_launch.effective_route()
- launch_credentials = load_user_credentials().launch_target(target_key)
- # LLM-classifier routing is self-sufficient: the preset bundle supplies
- # models, profile, classifier — only the primary API key has to come from
- # the user. We land here for claude/codex/openclaw when no --model and no
- # routing-profiles are configured — the implicit default.
- if _is_deterministic_launch(
- target=target, args=args, route=None, routing_profiles=routing_profiles,
- ):
- return bool(api_key or launch_credentials.api_key(PRIMARY_TIER))
- # --routing-profiles (CLI flag or saved top-level bundle) is self-sufficient:
- # the YAML carries every chain's credentials and the first route becomes
- # the initial agent model. The saved bundle is only consulted when no
- # --model is on the CLI (passing --model X is an explicit opt-in to a
- # single-model launch).
- if routing_profiles:
- return True
- if not args.model and user_config.routing_profiles:
- return True
- has_model = bool(args.model or configured_route.model)
- has_primary_key = bool(api_key or launch_credentials.api_key(PRIMARY_TIER))
- return has_model and has_primary_key
-
-
-def maybe_bootstrap_launch_config(
- args: argparse.Namespace,
- target: str,
- api_key_env_vars: tuple[str, ...],
-) -> None:
- """Run first-time interactive config when launch needs persisted defaults."""
-
- if launch_requirements_satisfied(
- args,
- target=target,
- api_key_env_vars=api_key_env_vars,
- ):
- return
- if not is_interactive_terminal():
- raise SystemExit(
- f"Switchyard is missing {target} launch defaults. Run "
- f"`switchyard configure --target {target}` or pass "
- f"--model and --api-key for a one-off launch."
- )
-
- connectivity = _resolve_launch_connectivity(
- args,
- api_key_env_vars=api_key_env_vars,
- )
- resolved_api_key = connectivity.api_key
- print(f"Switchyard is missing {target} launch defaults. Starting setup.")
- # Build the same request `switchyard configure` would. Any field we don't
- # set here — skill distillation, routing profiles, the --show/--list modes —
- # takes its default from ConfigureRequest, so setup can't crash on one we
- # forgot to pass.
- cmd_configure(ConfigureRequest(
- target=cast(ConfigureTarget, target),
- provider=connectivity.provider,
- base_url=connectivity.base_url,
- api_key=args.api_key,
- prompt_default_api_key=resolved_api_key,
- prompt_default_api_key_source=_api_key_prompt_default_source(
- args=args,
- api_key_env_vars=api_key_env_vars,
- resolved_api_key=resolved_api_key,
- ),
- reuse_existing_provider=True,
- claude_model=args.model if target == "claude" else None,
- codex_model=args.model if target == "codex" else None,
- openclaw_model=args.model if target == "openclaw" else None,
- no_model_discovery=getattr(args, "no_model_discovery", False),
- no_tui=getattr(args, "no_tui", False),
- ))
- if not args.api_key:
- configured_api_key = load_user_credentials().api_key(connectivity.provider)
- if configured_api_key:
- args.api_key = configured_api_key
-
-
-def route_from_launch_args(
- args: argparse.Namespace,
- configured_route: LaunchRouteConfig,
-) -> LaunchRouteConfig:
- """Merge one-off launch flags onto the configured route.
-
- The launcher CLI no longer exposes routing-policy flags; routing
- policies live in routing-profile YAML. We always emit a single-tier
- route here. Legacy saved random routes are rejected upstream by
- :func:`_warn_if_legacy_random_config`.
- """
-
- model = getattr(args, "model", None) or configured_route.model
- endpoints = None
- primary_endpoint = configured_route.endpoint(PRIMARY_TIER)
- if primary_endpoint.base_url:
- endpoints = {PRIMARY_TIER: primary_endpoint}
- return LaunchRouteConfig(
- type="single",
- model=model,
- endpoints=endpoints,
- )
-
-
-def route_from_random_config(config: RandomRoutingConfig) -> LaunchRouteConfig:
- """Render a random-routing config as a launcher route for summaries."""
-
- endpoints: dict[str, LaunchTierEndpointConfig] = {}
- if config.strong.endpoint.base_url:
- endpoints[PRIMARY_TIER] = LaunchTierEndpointConfig(
- base_url=config.strong.endpoint.base_url,
- )
- if config.weak.endpoint.base_url:
- endpoints[WEAK_TIER] = LaunchTierEndpointConfig(
- base_url=config.weak.endpoint.base_url,
- )
- return LaunchRouteConfig(
- type="random",
- model=config.strong.model,
- weak_model=config.weak.model,
- strong_probability=config.strong_probability,
- endpoints=endpoints or None,
- )
-
-
-def resolve_route_tier_connectivity(
- target: str,
- route: LaunchRouteConfig,
- tier: str,
- default_api_key: str | None,
- default_base_url: str,
-) -> LaunchTierConnectivity:
- credentials = load_user_credentials()
- launch_credentials = credentials.launch_target(cast(LaunchTarget, target))
- endpoint = route.endpoint(tier)
- return LaunchTierConnectivity(
- api_key=launch_credentials.api_key(tier) or default_api_key,
- base_url=endpoint.base_url or default_base_url,
- )
-
-
-def require_launch_tier_key(
- target: str,
- tier: str,
- connectivity: LaunchTierConnectivity,
-) -> LaunchTierConnectivity:
- if connectivity.api_key:
- return connectivity
- logger.warning(
- "No API key resolved for %s %s tier. Set --api-key, an API key env "
- "var, run `switchyard configure`, or add secrets/secrets.json. "
- "Using 'dummy' as placeholder.",
- target,
- tier,
- )
- return replace(connectivity, api_key="dummy")
-
-
-def placeholder_launch_tier_key(
- connectivity: LaunchTierConnectivity,
-) -> LaunchTierConnectivity:
- if connectivity.api_key:
- return connectivity
- return replace(connectivity, api_key="dummy")
-
-
-def _run_launch_smoke(
- target: str,
- model: str | None,
- connectivity: LaunchTierConnectivity,
- port: int | None,
- timeout: float | None,
-) -> None:
- """Dispatch the harness-driven smoke checklist and exit.
-
- ``--smoke`` on ``launch claude`` / ``launch codex`` / ``launch openclaw``
- runs :func:`verify_claude` / :func:`verify_codex` /
- :func:`verify_openclaw` and exits with their return code. Requires an
- explicit ``--model``; ``--routing-profiles`` is rejected before this
- function is reached. ``raise SystemExit(returncode)`` returns control to
- the user without spawning the interactive harness.
- """
- from switchyard.server.verify import (
- verify_claude,
- verify_codex,
- verify_openclaw,
- )
-
- if not model:
- raise SystemExit(
- f"launch {target} --smoke: no model resolved. "
- "Pass --model (smoke ignores --routing-profiles; use --model directly)."
- )
- if not connectivity.api_key:
- raise SystemExit(
- f"launch {target} --smoke: no API key resolved. Set --api-key, "
- "an API key env var, or run `switchyard configure`."
- )
- verifiers = {
- "claude": verify_claude,
- "codex": verify_codex,
- "openclaw": verify_openclaw,
- }
- verifier = verifiers[target]
- raise SystemExit(verifier(
- model=model,
- base_url=connectivity.base_url,
- api_key=connectivity.api_key,
- port=port,
- timeout=timeout,
- ))
-
-
-def resolve_launch_intake_config(
- args: argparse.Namespace,
- target: str,
- default_app: str,
-) -> LaunchIntakeConfig | None:
- """Build launch intake config from CLI args / env, or ``None``."""
- intake = IntakeCliConfig.from_launch_args(args)
- if not intake.enabled:
- return None
-
- return LaunchIntakeConfig.from_resolved(
- base_url=intake.base_url,
- workspace=intake.workspace,
- api_key=intake.api_key,
- app=intake.app or default_app,
- task=intake.task or "developer-session",
- session_id=intake.session_id,
- user_id=intake.user_id,
- target_url=intake.target_url,
- target=target,
- )
+_DEFAULT_CONFIG = Path(__file__).with_name("defaults") / "openrouter.toml"
+def _config_path(value: str | None) -> Path:
+ """Resolve the selected deployment, defaulting to the packaged OpenRouter config."""
+ path = Path(value).expanduser() if value else _DEFAULT_CONFIG
+ if not path.is_file():
+ raise SystemExit(f"launch: config file not found: {path}")
+ return path
def cmd_launch_claude(args: argparse.Namespace) -> None:
- """Start a proxy and spawn ``claude`` against it.
-
- Three shapes (deterministic is the default when no flags are given):
+ """Run Claude Code against a native TOML deployment."""
+ from switchyard.cli.launchers.claude_code_launcher import launch_claude_config
- * ``(no flags)`` — LLM-classifier strong/weak routing using the
- validated coding-agent trio (Claude Opus 4.7 + Nemotron-3 Super
- + DeepSeek V4 Flash classifier). Override individual tiers with
- ``--weak-model`` / ``--classifier-model`` / ``--profile``.
- * ``--model X`` — single-tier passthrough to X.
- * ``--routing-profiles FILE`` (global flag) — YAML-driven multi-chain table.
- ``--model`` is optional; falls back to the first YAML route.
-
- Random and other multi-chain routing live in the YAML schema.
- """
- if getattr(args, "startup_timing", False):
- startup_timing.enable()
- startup_timing.mark("launch invoked")
- if args.routing_profiles and getattr(args, "smoke", False):
- raise SystemExit(
- "launch claude: --smoke and --routing-profiles cannot be combined. "
- "Pass --model directly to pick the model to smoke-test."
- )
- if args.dry_run and getattr(args, "smoke", False):
- raise SystemExit(
- "launch claude: --smoke and --dry-run cannot be combined. "
- "--smoke runs a live round-trip; --dry-run would be ignored."
- )
- if getattr(args, "smoke", False) and not args.model:
- raise SystemExit(
- "launch claude: --smoke requires --model. "
- "Pass --model directly to pick the model to smoke-test."
- )
- if args.routing_profiles and args.model:
- raise SystemExit(
- "launch claude: --model and --routing-profiles are mutually exclusive.\n"
- "Pass --routing-profiles as a global flag before the subcommand:\n"
- " switchyard --routing-profiles FILE -- launch claude"
- )
- from switchyard.cli.launchers.claude_code_launcher import (
- launch_claude,
- launch_claude_deterministic_routing,
- )
- from switchyard.cli.launchers.launcher_runtime import ensure_system_ssl_trust
-
- # Fixes the classifier's "Connection error" failure on Linux dev hosts
- # behind a corporate SSL intercept (Python httpx uses certifi by default;
- # the intercept CA only lives in the system keystore). No-op elsewhere.
- ensure_system_ssl_trust()
-
- routing_profiles = _resolve_routing_profiles(args)
- if not args.dry_run and not getattr(args, "smoke", False):
- maybe_bootstrap_launch_config(
- args,
- target="claude",
- api_key_env_vars=(
- "OPENROUTER_API_KEY",
- "NVIDIA_API_KEY",
- "OPENAI_API_KEY",
- "ANTHROPIC_API_KEY",
- ),
- )
- configured_launch = load_user_config().launch_target("claude")
- configured_route = configured_launch.effective_route()
- _warn_if_legacy_random_config(configured_route, target="claude")
- # CLI --routing-profiles is a clean-slate override: route bundle and
- # default model both come from the CLI YAML. The saved config.json launch
- # route is ignored so a saved model id that doesn't exist in the new
- # bundle can't leak through. Gated on the CLI flag specifically — the
- # saved-bundle fallback path still inherits config.json's launch.<t>.model.
- if args.routing_profiles:
- configured_route = LaunchRouteConfig()
- route = route_from_launch_args(args, configured_route)
- # Deterministic LLM-classifier routing is the implicit default for
- # ``launch claude`` when neither single-model passthrough nor a
- # routing-profiles bundle is in play.
- deterministic = _is_deterministic_launch(
- target="claude", args=args, route=route, routing_profiles=routing_profiles,
- )
- if not deterministic and not (routing_profiles and not route.model):
- require_route_model(route, target="claude")
-
- api_key, base_url = resolve_launch_connectivity(
- args,
- api_key_env_vars=(
- "OPENROUTER_API_KEY",
- "NVIDIA_API_KEY",
- "OPENAI_API_KEY",
- "ANTHROPIC_API_KEY",
- ),
- )
- primary_connectivity = resolve_route_tier_connectivity(
- target="claude",
- route=route,
- tier=PRIMARY_TIER,
- default_api_key=api_key,
- default_base_url=base_url,
- )
- weak_connectivity = resolve_route_tier_connectivity(
- target="claude",
- route=route,
- tier=WEAK_TIER,
- default_api_key=api_key,
- default_base_url=base_url,
- )
- claude_args = strip_forwarded_args(args.claude_args)
-
- if getattr(args, "smoke", False):
- _run_launch_smoke(
- target="claude",
- model=route.model,
- connectivity=primary_connectivity,
- port=args.port,
- timeout=args.timeout,
+ raise SystemExit(
+ launch_claude_config(
+ config=_config_path(args.config),
+ model=args.model,
+ claude_args=strip_forwarded_args(args.claude_args),
)
-
- if args.dry_run:
- dry_run_classifier_model: str | None = None
- dry_run_profile: str | None = None
- dry_run_min_confidence: float | None = None
- dry_run_route = route
- if deterministic:
- deterministic_config = build_deterministic_routing_config(
- LaunchRouteConfig(
- type="deterministic",
- model=getattr(args, "model", None),
- weak_model=getattr(args, "weak_model", None),
- ),
- primary=placeholder_launch_tier_key(primary_connectivity),
- weak=placeholder_launch_tier_key(weak_connectivity),
- classifier_model=getattr(args, "classifier_model", None),
- profile_name=getattr(args, "profile", None),
- classifier_min_confidence=getattr(
- args, "classifier_min_confidence", None,
- ),
- backend_format=BackendFormat.OPENAI,
- strong_backend_format=BackendFormat.AUTO,
- timeout=args.timeout,
- )
- dry_run_route = LaunchRouteConfig(
- type="deterministic",
- model=deterministic_config.strong.model,
- weak_model=deterministic_config.weak.model,
- )
- dry_run_classifier_model = deterministic_config.classifier.model
- dry_run_profile = deterministic_config.profile_name
- dry_run_min_confidence = deterministic_config.classifier_min_confidence
- print(format_dry_run(
- target="claude",
- route=dry_run_route,
- base_url=primary_connectivity.base_url,
- api_key_set=bool(primary_connectivity.api_key),
- port=args.port,
- timeout=args.timeout,
- forwarded_args=claude_args,
- classifier_model=dry_run_classifier_model,
- profile=dry_run_profile,
- classifier_min_confidence=dry_run_min_confidence,
- routing_profiles=routing_profiles,
- ))
- return
-
- intake = resolve_launch_intake_config(
- args, target="claude", default_app="claude-code-switchyard",
)
- startup_timing.mark("config + credentials resolved")
-
- if deterministic:
- _reject_openrouter_only_default_trio(
- target="claude",
- base_url=primary_connectivity.base_url,
- )
- primary_connectivity = require_launch_tier_key(
- target="claude",
- tier=PRIMARY_TIER,
- connectivity=primary_connectivity,
- )
- weak_connectivity = placeholder_launch_tier_key(weak_connectivity)
- deterministic_config = build_deterministic_routing_config(
- LaunchRouteConfig(
- type="deterministic",
- model=getattr(args, "model", None),
- weak_model=getattr(args, "weak_model", None),
- ),
- primary=primary_connectivity,
- weak=weak_connectivity,
- classifier_model=getattr(args, "classifier_model", None),
- profile_name=getattr(args, "profile", None),
- classifier_min_confidence=getattr(
- args, "classifier_min_confidence", None,
- ),
- backend_format=BackendFormat.OPENAI,
- strong_backend_format=BackendFormat.AUTO,
- timeout=args.timeout,
- )
- raise SystemExit(launch_claude_deterministic_routing(
- config=deterministic_config,
- port=args.port,
- claude_args=claude_args,
- intake=intake,
- discovery_disabled=bool(getattr(args, "no_model_discovery", False)),
- rl_log_dir=resolve_rl_log_dir(args),
- ))
-
- if routing_profiles:
- initial = _resolve_initial_from_profiles(
- target="claude",
- routing_profiles=routing_profiles,
- )
- else:
- primary_connectivity = require_launch_tier_key(
- target="claude",
- tier=PRIMARY_TIER,
- connectivity=primary_connectivity,
- )
- initial = require_route_model(route, target="claude")
- raise SystemExit(launch_claude(
- model=initial,
- base_url=primary_connectivity.base_url or "",
- api_key=primary_connectivity.api_key or "dummy",
- port=args.port,
- timeout=args.timeout,
- claude_args=claude_args,
- intake=intake,
- routing_profiles=routing_profiles,
- rl_log_dir=resolve_rl_log_dir(args),
- ))
def cmd_launch_codex(args: argparse.Namespace) -> None:
- """Start a proxy and spawn ``codex`` against it.
-
- Same shape as :func:`cmd_launch_claude`: deterministic is the
- default when no flags are given; ``--model X`` or
- ``--routing-profiles FILE`` (global flag) opts out.
- """
- if args.routing_profiles and getattr(args, "smoke", False):
- raise SystemExit(
- "launch codex: --smoke and --routing-profiles cannot be combined. "
- "Pass --model directly to pick the model to smoke-test."
- )
- if args.dry_run and getattr(args, "smoke", False):
- raise SystemExit(
- "launch codex: --smoke and --dry-run cannot be combined. "
- "--smoke runs a live round-trip; --dry-run would be ignored."
- )
- if getattr(args, "smoke", False) and not args.model:
- raise SystemExit(
- "launch codex: --smoke requires --model. "
- "Pass --model directly to pick the model to smoke-test."
- )
- if args.routing_profiles and args.model:
- raise SystemExit(
- "launch codex: --model and --routing-profiles are mutually exclusive.\n"
- "Pass --routing-profiles as a global flag before the subcommand:\n"
- " switchyard --routing-profiles FILE -- launch codex"
- )
- from switchyard.cli.launchers.codex_cli_launcher import (
- launch_codex,
- launch_codex_deterministic_routing,
- )
- from switchyard.cli.launchers.launcher_runtime import ensure_system_ssl_trust
-
- ensure_system_ssl_trust()
+ """Run Codex against a native TOML deployment."""
+ from switchyard.cli.launchers.codex_cli_launcher import launch_codex_config
- routing_profiles = _resolve_routing_profiles(args)
- if not args.dry_run and not getattr(args, "smoke", False):
- maybe_bootstrap_launch_config(
- args,
- target="codex",
- api_key_env_vars=("OPENROUTER_API_KEY", "NVIDIA_API_KEY", "OPENAI_API_KEY"),
+ raise SystemExit(
+ launch_codex_config(
+ config=_config_path(args.config),
+ model=args.model,
+ codex_args=strip_forwarded_args(args.codex_args),
)
- configured_launch = load_user_config().launch_target("codex")
- configured_route = configured_launch.effective_route()
- _warn_if_legacy_random_config(configured_route, target="codex")
- if args.routing_profiles:
- configured_route = LaunchRouteConfig()
- route = route_from_launch_args(args, configured_route)
- # Deterministic LLM-classifier routing is the implicit default for
- # ``launch codex`` when neither single-model passthrough nor a
- # routing-profiles bundle is in play.
- deterministic = _is_deterministic_launch(
- target="codex", args=args, route=route, routing_profiles=routing_profiles,
- )
- if not deterministic and not (routing_profiles and not route.model):
- require_route_model(route, target="codex")
-
- api_key, base_url = resolve_launch_connectivity(
- args, api_key_env_vars=("OPENROUTER_API_KEY", "NVIDIA_API_KEY", "OPENAI_API_KEY"),
)
- primary_connectivity = resolve_route_tier_connectivity(
- target="codex",
- route=route,
- tier=PRIMARY_TIER,
- default_api_key=api_key,
- default_base_url=base_url,
- )
- weak_connectivity = resolve_route_tier_connectivity(
- target="codex",
- route=route,
- tier=WEAK_TIER,
- default_api_key=api_key,
- default_base_url=base_url,
- )
- codex_args = strip_forwarded_args(args.codex_args)
-
- if getattr(args, "smoke", False):
- _run_launch_smoke(
- target="codex",
- model=route.model,
- connectivity=primary_connectivity,
- port=args.port,
- timeout=args.timeout,
- )
-
- if args.dry_run:
- dry_run_classifier_model: str | None = None
- dry_run_profile: str | None = None
- dry_run_min_confidence: float | None = None
- dry_run_route = route
- if deterministic:
- deterministic_config = build_deterministic_routing_config(
- LaunchRouteConfig(
- type="deterministic",
- model=getattr(args, "model", None),
- weak_model=getattr(args, "weak_model", None),
- ),
- primary=placeholder_launch_tier_key(primary_connectivity),
- weak=placeholder_launch_tier_key(weak_connectivity),
- classifier_model=getattr(args, "classifier_model", None),
- profile_name=getattr(args, "profile", None),
- classifier_min_confidence=getattr(
- args, "classifier_min_confidence", None,
- ),
- backend_format=BackendFormat.OPENAI,
- timeout=args.timeout,
- )
- dry_run_route = LaunchRouteConfig(
- type="deterministic",
- model=deterministic_config.strong.model,
- weak_model=deterministic_config.weak.model,
- )
- dry_run_classifier_model = deterministic_config.classifier.model
- dry_run_profile = deterministic_config.profile_name
- dry_run_min_confidence = deterministic_config.classifier_min_confidence
- print(format_dry_run(
- target="codex",
- route=dry_run_route,
- base_url=primary_connectivity.base_url,
- api_key_set=bool(primary_connectivity.api_key),
- port=args.port,
- timeout=args.timeout,
- forwarded_args=codex_args,
- classifier_model=dry_run_classifier_model,
- profile=dry_run_profile,
- classifier_min_confidence=dry_run_min_confidence,
- routing_profiles=routing_profiles,
- ))
- return
-
- intake = resolve_launch_intake_config(
- args, target="codex", default_app="codex-switchyard",
- )
-
- if deterministic:
- _reject_openrouter_only_default_trio(
- target="codex",
- base_url=primary_connectivity.base_url,
- )
- primary_connectivity = require_launch_tier_key(
- target="codex",
- tier=PRIMARY_TIER,
- connectivity=primary_connectivity,
- )
- weak_connectivity = placeholder_launch_tier_key(weak_connectivity)
- deterministic_config = build_deterministic_routing_config(
- LaunchRouteConfig(
- type="deterministic",
- model=getattr(args, "model", None),
- weak_model=getattr(args, "weak_model", None),
- ),
- primary=primary_connectivity,
- weak=weak_connectivity,
- classifier_model=getattr(args, "classifier_model", None),
- profile_name=getattr(args, "profile", None),
- classifier_min_confidence=getattr(
- args, "classifier_min_confidence", None,
- ),
- backend_format=BackendFormat.OPENAI,
- timeout=args.timeout,
- )
- raise SystemExit(launch_codex_deterministic_routing(
- config=deterministic_config,
- port=args.port,
- codex_args=codex_args,
- intake=intake,
- discovery_disabled=bool(getattr(args, "no_model_discovery", False)),
- rl_log_dir=resolve_rl_log_dir(args),
- ))
-
- if routing_profiles:
- initial = _resolve_initial_from_profiles(
- target="codex",
- routing_profiles=routing_profiles,
- )
- else:
- primary_connectivity = require_launch_tier_key(
- target="codex",
- tier=PRIMARY_TIER,
- connectivity=primary_connectivity,
- )
- initial = require_route_model(route, target="codex")
- raise SystemExit(launch_codex(
- model=initial,
- base_url=primary_connectivity.base_url or "",
- api_key=primary_connectivity.api_key or "dummy",
- port=args.port,
- timeout=args.timeout,
- codex_args=codex_args,
- intake=intake,
- routing_profiles=routing_profiles,
- rl_log_dir=resolve_rl_log_dir(args),
- ))
def cmd_launch_openclaw(args: argparse.Namespace) -> None:
- """Start a proxy and spawn ``openclaw chat`` against it.
-
- Same shape as :func:`cmd_launch_claude` / :func:`cmd_launch_codex`:
- LLM-classifier routing by default, or single ``--model`` /
- ``--routing-profiles FILE`` (global flag) to opt out. The launcher writes a transient
- ``openclaw.json`` in a tempdir and points OpenClaw at it via
- ``OPENCLAW_STATE_DIR`` / ``OPENCLAW_HOME`` / ``OPENCLAW_CONFIG_PATH``
- — the user's real ``~/.openclaw/`` (sessions, channels, plugins)
- stays untouched.
-
- ``--smoke`` dispatches to :func:`verify_openclaw` and exits with its
- return code — same shape as ``launch claude/codex --smoke``.
- """
- if args.routing_profiles and getattr(args, "smoke", False):
- raise SystemExit(
- "launch openclaw: --smoke and --routing-profiles cannot be combined. "
- "Pass --model directly to pick the model to smoke-test."
- )
- if args.dry_run and getattr(args, "smoke", False):
- raise SystemExit(
- "launch openclaw: --smoke and --dry-run cannot be combined. "
- "--smoke runs a live round-trip; --dry-run would be ignored."
- )
- if getattr(args, "smoke", False) and not args.model:
- raise SystemExit(
- "launch openclaw: --smoke requires --model. "
- "Pass --model directly to pick the model to smoke-test."
- )
- if args.routing_profiles and args.model:
- raise SystemExit(
- "launch openclaw: --model and --routing-profiles are mutually exclusive.\n"
- "Pass --routing-profiles as a global flag before the subcommand:\n"
- " switchyard --routing-profiles FILE -- launch openclaw"
- )
- from switchyard.cli.launchers.launcher_runtime import ensure_system_ssl_trust
- from switchyard.cli.launchers.openclaw_launcher import (
- launch_openclaw,
- launch_openclaw_deterministic_routing,
- )
-
- ensure_system_ssl_trust()
-
- routing_profiles = _resolve_routing_profiles(args)
- if not args.dry_run and not getattr(args, "smoke", False):
- maybe_bootstrap_launch_config(
- args,
- target="openclaw",
- api_key_env_vars=(
- "OPENROUTER_API_KEY",
- "NVIDIA_API_KEY",
- "OPENAI_API_KEY",
- "ANTHROPIC_API_KEY",
- ),
- )
- configured_launch = load_user_config().launch_target("openclaw")
- configured_route = configured_launch.effective_route()
- _warn_if_legacy_random_config(configured_route, target="openclaw")
- if args.routing_profiles:
- configured_route = LaunchRouteConfig()
- route = route_from_launch_args(args, configured_route)
- # LLM-classifier routing is the implicit default for ``launch openclaw``
- # when neither single-model passthrough nor a routing-profiles bundle is
- # in play.
- deterministic = _is_deterministic_launch(
- target="openclaw", args=args, route=route, routing_profiles=routing_profiles,
- )
- if not deterministic and not (routing_profiles and not route.model):
- require_route_model(route, target="openclaw")
+ """Run OpenClaw against a native TOML deployment."""
+ from switchyard.cli.launchers.openclaw_launcher import launch_openclaw_config
- api_key, base_url = resolve_launch_connectivity(
- args, api_key_env_vars=(
- "OPENROUTER_API_KEY",
- "NVIDIA_API_KEY",
- "OPENAI_API_KEY",
- "ANTHROPIC_API_KEY",
- ),
- )
- primary_connectivity = resolve_route_tier_connectivity(
- target="openclaw",
- route=route,
- tier=PRIMARY_TIER,
- default_api_key=api_key,
- default_base_url=base_url,
- )
- weak_connectivity = resolve_route_tier_connectivity(
- target="openclaw",
- route=route,
- tier=WEAK_TIER,
- default_api_key=api_key,
- default_base_url=base_url,
- )
- openclaw_args = strip_forwarded_args(args.openclaw_args)
-
- if getattr(args, "smoke", False):
- _run_launch_smoke(
- target="openclaw",
- model=route.model,
- connectivity=primary_connectivity,
- port=args.port,
- timeout=args.timeout,
- )
-
- if args.dry_run:
- dry_run_classifier_model: str | None = None
- dry_run_profile: str | None = None
- dry_run_min_confidence: float | None = None
- dry_run_route = route
- if deterministic:
- deterministic_config = build_deterministic_routing_config(
- LaunchRouteConfig(
- type="deterministic",
- model=getattr(args, "model", None),
- weak_model=getattr(args, "weak_model", None),
- ),
- primary=placeholder_launch_tier_key(primary_connectivity),
- weak=placeholder_launch_tier_key(weak_connectivity),
- classifier_model=getattr(args, "classifier_model", None),
- profile_name=getattr(args, "profile", None),
- classifier_min_confidence=getattr(
- args, "classifier_min_confidence", None,
- ),
- backend_format=BackendFormat.OPENAI,
- timeout=args.timeout,
- )
- dry_run_route = LaunchRouteConfig(
- type="deterministic",
- model=deterministic_config.strong.model,
- weak_model=deterministic_config.weak.model,
- )
- dry_run_classifier_model = deterministic_config.classifier.model
- dry_run_profile = deterministic_config.profile_name
- dry_run_min_confidence = deterministic_config.classifier_min_confidence
- print(format_dry_run(
- target="openclaw",
- route=dry_run_route,
- base_url=primary_connectivity.base_url,
- api_key_set=bool(primary_connectivity.api_key),
- port=args.port,
- timeout=args.timeout,
- forwarded_args=openclaw_args,
- classifier_model=dry_run_classifier_model,
- profile=dry_run_profile,
- classifier_min_confidence=dry_run_min_confidence,
- routing_profiles=routing_profiles,
- ))
- return
-
- intake = resolve_launch_intake_config(
- args, target="openclaw", default_app="openclaw-switchyard",
- )
-
- if deterministic:
- _reject_openrouter_only_default_trio(
- target="openclaw",
- base_url=primary_connectivity.base_url,
- )
- primary_connectivity = require_launch_tier_key(
- target="openclaw",
- tier=PRIMARY_TIER,
- connectivity=primary_connectivity,
- )
- weak_connectivity = placeholder_launch_tier_key(weak_connectivity)
- deterministic_config = build_deterministic_routing_config(
- LaunchRouteConfig(
- type="deterministic",
- model=getattr(args, "model", None),
- weak_model=getattr(args, "weak_model", None),
- ),
- primary=primary_connectivity,
- weak=weak_connectivity,
- classifier_model=getattr(args, "classifier_model", None),
- profile_name=getattr(args, "profile", None),
- classifier_min_confidence=getattr(
- args, "classifier_min_confidence", None,
- ),
- backend_format=BackendFormat.OPENAI,
- timeout=args.timeout,
- )
- raise SystemExit(launch_openclaw_deterministic_routing(
- config=deterministic_config,
- port=args.port,
- openclaw_args=openclaw_args,
- intake=intake,
- discovery_disabled=bool(getattr(args, "no_model_discovery", False)),
- rl_log_dir=resolve_rl_log_dir(args),
- ))
-
- if routing_profiles:
- initial = _resolve_initial_from_profiles(
- target="openclaw",
- routing_profiles=routing_profiles,
- )
- else:
- primary_connectivity = require_launch_tier_key(
- target="openclaw",
- tier=PRIMARY_TIER,
- connectivity=primary_connectivity,
- )
- initial = require_route_model(route, target="openclaw")
- raise SystemExit(launch_openclaw(
- model=initial,
- base_url=primary_connectivity.base_url or "",
- api_key=primary_connectivity.api_key or "dummy",
- port=args.port,
- timeout=args.timeout,
- openclaw_args=openclaw_args,
- intake=intake,
- routing_profiles=routing_profiles,
- rl_log_dir=resolve_rl_log_dir(args),
- ))
-
-
-def _warn_if_legacy_random_config(
- route: LaunchRouteConfig, target: str,
-) -> None:
- """Surface a clear error when saved config is still on random-routing.
-
- The ``random-routing`` CLI subcommand and ``--routing random`` /
- ``--preset`` / ``--weak-model`` launcher flags were removed; routing
- policies live in routing-profile YAML files. Saved configs from
- earlier versions may still declare ``route.type = "random"``; bail
- with a recovery hint instead of silently launching the wrong shape.
- """
- if route.type != "random":
- return
raise SystemExit(
- f"launch {target}: saved config has route.type=\"random\" but\n"
- "random-routing CLI flags have been removed. Express your routing\n"
- "policy as a routing-profile YAML and pass it via\n"
- " --routing-profiles PATH\n"
- "or run `switchyard configure` to reset the saved route to single.\n"
- "See `switchyard serve --help` and the docs for the YAML schema."
+ launch_openclaw_config(
+ config=_config_path(args.config),
+ model=args.model,
+ openclaw_args=strip_forwarded_args(args.openclaw_args),
+ )
)
@@ -1142,11 +62,4 @@ __all__ = [
"cmd_launch_claude",
"cmd_launch_codex",
"cmd_launch_openclaw",
- "launch_requirements_satisfied",
- "maybe_bootstrap_launch_config",
- "resolve_launch_connectivity",
- "resolve_launch_intake_config",
- "resolve_route_tier_connectivity",
- "route_from_launch_args",
- "route_from_random_config",
]
diff --git a/switchyard/cli/launchers/claude_alias.py b/switchyard/cli/launchers/claude_alias.py
deleted file mode 100644
index 6dff9bf89..000000000
--- a/switchyard/cli/launchers/claude_alias.py
+++ /dev/null
@@ -1,43 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Claude Code `/model` picker alias rule.
-
-Claude Code's gateway-discovery filter only adds models to its `/model`
-picker when the id starts with ``claude`` or ``anthropic``. The claude
-launcher exposes every table id under both spellings so users can
-pick (or save) either form. Centralized here so the rule lives in
-exactly one place — see ``claude_code_launcher._with_claude_aliases``,
-``launch_command._alias_variants``, and ``configure_command``'s
-``default_claude_route_model``.
-"""
-
-from __future__ import annotations
-
-#: Prefixes Claude Code's gateway-discovery filter accepts.
-CLAUDE_PICKER_PREFIXES = ("claude", "anthropic")
-
-
-def claude_alias_for(model_id: str) -> str | None:
- """Return ``claude-<model_id>`` when *model_id* isn't already prefixed."""
- if model_id.startswith(CLAUDE_PICKER_PREFIXES):
- return None
- return f"claude-{model_id}"
-
-
-def de_claude_alias(model_id: str) -> str | None:
- """Return *model_id* with a leading ``claude-`` / ``anthropic-`` stripped.
-
- Returns ``None`` when *model_id* isn't prefixed (no de-alias to add).
- """
- for prefix in ("claude-", "anthropic-"):
- if model_id.startswith(prefix):
- return model_id[len(prefix):]
- return None
-
-
-__all__ = [
- "CLAUDE_PICKER_PREFIXES",
- "claude_alias_for",
- "de_claude_alias",
-]
diff --git a/switchyard/cli/launchers/claude_code_launcher.py b/switchyard/cli/launchers/claude_code_launcher.py
index c71eedc3a..e3c17374a 100644
--- a/switchyard/cli/launchers/claude_code_launcher.py
+++ b/switchyard/cli/launchers/claude_code_launcher.py
@@ -1,97 +1,32 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""One-command `claude` + V2 proxy supervisor.
-
-Implements two UXes on top of a single chain-agnostic runner:
-
-* ``switchyard launch claude --model <name>`` — single-model
- passthrough. Spin up an in-process V2 passthrough proxy on a free
- local port, probe the backend for native ``POST /v1/messages``
- support, build the matching chain
- (:class:`AnthropicNativeBackend` or :class:`OpenAiNativeBackend`
- with translation), then spawn ``claude`` against the proxy.
-* ``switchyard launch claude --preset <id>`` — weighted-coin
- random routing across the preset's strong / weak tiers. Same
- supervisor loop, different chain: a
- :class:`RandomRoutingRequestProcessor` picks a tier per request and
- the :class:`MultiLlmBackend` dispatches to that tier, while
- ``ANTHROPIC_MODEL`` is pinned to a Switchyard virtual model that
- represents the strong / weak pair.
-
-In both modes ``ANTHROPIC_BASE_URL`` / ``ANTHROPIC_AUTH_TOKEN`` /
-``ANTHROPIC_MODEL`` are preset (ollama convention) so Claude Code
-talks to the proxy without going through its own auth setup wizard.
-When ``claude`` exits (or Ctrl-C), the proxy is torn down cleanly.
-
-Routing mode is auto-selected at startup by the generic
-:class:`LlmTarget` recipe: Anthropic-looking models probe for native
-``POST /v1/messages`` support, otherwise the chain falls back to
-:class:`OpenAiNativeBackend` with the existing Anthropic ↔ OpenAI Chat
-translation.
-"""
+"""Run Claude Code through an in-process native Switchyard server."""
import logging
import os
import shutil
import subprocess
-import threading
-from collections.abc import Callable, Mapping, Sequence
from pathlib import Path
-from typing import Any
-
-import uvicorn
-from switchyard.cli.launchers.claude_alias import claude_alias_for, de_claude_alias
-from switchyard.cli.launchers.launch_intake_config import (
- LaunchIntakeConfig,
- build_launch_capture_processors,
- print_intake_warning,
-)
from switchyard.cli.launchers.launcher_runtime import (
banner_pause,
configure_debug_file_logging,
- deterministic_strategy_summary,
- find_free_port,
- passthrough_strategy_summary,
print_ready_banner,
print_startup_failure,
- routing_profiles_strategy_summary,
silence_launch_loggers,
- spawn_proxy_thread,
stdin_is_tty,
- suppress_uvicorn_stream_handlers,
wait_for_proxy_ready,
)
from switchyard.cli.launchers.live_stats_footer import LiveStatsFooter
+from switchyard.cli.launchers.native_server import NativeServer
from switchyard.cli.launchers.proxy_health_monitor import ProxyHealthMonitor
from switchyard.cli.launchers.session_summary import print_session_summary
-from switchyard.cli.route_bundle import (
- load_route_bundle_table,
-)
-from switchyard.lib import startup_timing
-from switchyard.lib.backends.llm_target import (
- BackendFormat,
- LlmTarget,
-)
-from switchyard.lib.processors.model_rewrite_request_processor import (
- ModelRewriteRequestProcessor,
-)
-from switchyard.lib.profiles import (
- DeterministicRoutingConfig,
-)
-from switchyard.lib.route_table import ChainRuntime, SwitchyardApp
-from switchyard.lib.route_table_builders import (
- build_single_model_table,
- build_tier_passthrough_switchyard,
-)
-from switchyard.lib.stats_accumulator import StatsAccumulator
from switchyard.server.shell_tui import ShellTUI
logger = logging.getLogger(__name__)
_READY_TIMEOUT_S = 10.0
-_SHUTDOWN_JOIN_S = 3.0
_EXIT_BINARY_NOT_FOUND = 127
_EXIT_SIGINT = 130
@@ -101,10 +36,6 @@ def _quiet_launch_loggers() -> None:
silence_launch_loggers(local_logger=logger)
-_ModelRewriteRequestProcessor = ModelRewriteRequestProcessor
-_find_free_port = find_free_port
-
-
def _find_claude_binary() -> str | None:
"""Locate the ``claude`` executable.
@@ -129,51 +60,7 @@ def _wait_ready(port: int, timeout_s: float = _READY_TIMEOUT_S) -> bool:
return wait_for_proxy_ready(port, timeout_s=timeout_s)
-def _build_claude_switchyard(
- model: str,
- api_key: str,
- base_url: str,
- timeout: float | None,
- stats: StatsAccumulator,
- extra_request_processors: Sequence[Any] = (),
- extra_response_processors: Sequence[Any] = (),
-) -> ChainRuntime:
- """Build Claude's single-tier profile-backed chain."""
- return build_tier_passthrough_switchyard(
- LlmTarget(
- id="default",
- model=model,
- format=BackendFormat.AUTO,
- api_key=api_key,
- base_url=base_url,
- timeout_secs=timeout,
- ),
- stats=stats,
- enable_stats=True,
- extra_request_processors=extra_request_processors,
- extra_response_processors=extra_response_processors,
- )
-
-
-def _spawn_proxy_thread(
- switchyard: SwitchyardApp, port: int,
-) -> tuple[uvicorn.Server, threading.Thread]:
- """Run uvicorn in a background daemon thread, return (server, thread)."""
- return spawn_proxy_thread(
- switchyard, port, thread_name="launch-claude-proxy",
- )
-
-
-def _format_anthropic_custom_headers(headers: dict[str, str]) -> str:
- """Encode header dict as Claude Code's ``ANTHROPIC_CUSTOM_HEADERS`` value."""
- return "\n".join(f"{name}: {value}" for name, value in headers.items())
-
-
-def _claude_env(
- port: int,
- model: str,
- intake: LaunchIntakeConfig | None = None,
-) -> dict[str, str]:
+def _claude_env(port: int, model: str) -> dict[str, str]:
"""Build the env-var overrides that route Claude Code through our proxy.
* ``ANTHROPIC_BASE_URL`` — our proxy URL.
@@ -187,7 +74,7 @@ def _claude_env(
* ``CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`` — tells Claude Code
to populate the picker from ``GET /v1/models``.
"""
- env = {
+ return {
"ANTHROPIC_BASE_URL": f"http://127.0.0.1:{port}",
"ANTHROPIC_AUTH_TOKEN": "switchyard",
"ANTHROPIC_API_KEY": "",
@@ -196,12 +83,6 @@ def _claude_env(
"ANTHROPIC_CUSTOM_MODEL_OPTION": model,
"CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
}
- if intake is not None:
- env["ANTHROPIC_CUSTOM_HEADERS"] = _format_anthropic_custom_headers(
- intake.opt_in_headers(),
- )
- env["SWITCHYARD_SESSION_ID"] = intake.session_id
- return env
def _supervise_claude_plain(
@@ -209,7 +90,6 @@ def _supervise_claude_plain(
claude_args: list[str],
port: int,
model: str,
- intake: LaunchIntakeConfig | None = None,
) -> int:
"""Run ``claude`` via plain subprocess (non-TTY / headless fallback).
@@ -217,7 +97,7 @@ def _supervise_claude_plain(
``KeyboardInterrupt`` is translated to exit code 130.
"""
env = os.environ.copy()
- env.update(_claude_env(port, model, intake=intake))
+ env.update(_claude_env(port, model))
try:
result = subprocess.run([claude_bin, *claude_args], env=env, check=False)
return result.returncode
@@ -225,103 +105,17 @@ def _supervise_claude_plain(
return _EXIT_SIGINT
-def _print_ready_banner(port: int, display_model: str) -> None:
- """Write the ready banner to stderr, bypassing the logger silencer above."""
- print_ready_banner(port=port, display_model=display_model)
-
-
-
-def _make_footer_fn(
- stats: StatsAccumulator,
- model: str,
- health: ProxyHealthMonitor,
-) -> Callable[[int], list[tuple[str, int]]]:
- """Return the unified live-stats footer renderer."""
- return LiveStatsFooter(stats, model, health).as_footer_fn()
-
-
-def _with_claude_aliases(src: SwitchyardApp) -> SwitchyardApp:
- """Expose every registered id under its ``claude-`` aliased AND raw form.
-
- Same chain object on every name — alias only, no duplicate Switchyard
- instance. Two-way aliasing so users can spell the model either with or
- without the prefix regardless of which form the YAML declared:
-
- - `foo` → also reachable as `claude-foo` (alias inserted first so
- `registered_models()[0]` is the prefixed view, which becomes
- `ANTHROPIC_CUSTOM_MODEL_OPTION`).
- - `claude-foo` → also reachable as `foo`.
-
- Existing entries win on collision (a YAML that declares both `foo` and
- `claude-foo` keeps both untouched). Single-chain inputs pass through
- unchanged — there's no table to alias into.
- """
- from switchyard.lib.route_table import RouteTable
- if not isinstance(src, RouteTable):
- return src
- out = RouteTable()
- seen: set[str] = set()
-
- def _put(name: str, chain: object, metadata: Mapping[str, object]) -> None:
- if name in seen:
- return
- out.register(name, chain, metadata=metadata) # type: ignore[arg-type]
- seen.add(name)
-
- for model_id, chain, metadata in src.items():
- # Insert the claude-prefixed alias BEFORE the original so the
- # table's first id (which becomes ANTHROPIC_CUSTOM_MODEL_OPTION)
- # is always the prefixed view.
- alias = claude_alias_for(model_id)
- if alias is not None:
- _put(alias, chain, {**dict(metadata), "display_name": alias})
- _put(model_id, chain, metadata)
- bare = de_claude_alias(model_id)
- if bare is not None:
- _put(bare, chain, {"display_name": bare})
- default_model = src.default_model()
- if default_model is not None and default_model in out.registered_models():
- out.set_default_model(default_model)
- return out
+def _start_native_server(config: Path) -> NativeServer:
+ """Start the native server; kept separate for launcher supervision tests."""
+ return NativeServer(config)
def _run_claude_with_switchyard(
- switchyard: SwitchyardApp,
+ config: Path,
display_model: str,
- port: int | None,
claude_args: list[str],
- stats: StatsAccumulator,
- intake: LaunchIntakeConfig | None = None,
- strategy_summary: str | None = None,
) -> int:
- """Chain-agnostic supervisor: host ``switchyard`` then spawn claude.
-
- Takes a pre-built :class:`Switchyard` and a display-only model
- name. The caller decides what's in the chain (single-model
- passthrough, random routing across a preset, …) — this function
- owns only the uvicorn-in-a-thread +
- ``claude`` supervision + env-var injection boilerplate that is
- identical across those modes.
-
- ``display_model`` is forwarded to ``ANTHROPIC_MODEL`` /
- ``ANTHROPIC_SMALL_FAST_MODEL`` so Claude Code's ``/model`` picker
- and status line show something sensible. For random-routing chains
- this is a virtual model registered in Switchyard's local model
- table.
-
- When stdin is a TTY, ``claude`` runs inside a ``ShellTUI`` that
- draws a live token-usage footer at the bottom of the terminal.
- When stdin is not a TTY (CI, piped input), falls back to a plain
- ``subprocess.run`` so headless use is unaffected.
-
- Returns the ``claude`` process's exit code (or ``127`` if the
- binary wasn't found, ``130`` on Ctrl-C).
- """
- startup_timing.mark("chain assembled")
- # Expose every table entry under a `claude-` prefixed alias so Claude
- # Code's gateway-discovery filter accepts the full listing. Originals stay
- # registered for direct-id callers; aliases share the same chain object.
- switchyard = _with_claude_aliases(switchyard)
+ """Host a native deployment and run Claude Code against it."""
claude_bin = _find_claude_binary()
if claude_bin is None:
logger.error(
@@ -333,24 +127,13 @@ def _run_claude_with_switchyard(
log_path = configure_debug_file_logging(display_model=display_model)
logger.debug("claude launcher module=%s", __file__)
- resolved_port = port if port is not None else _find_free_port()
- server, thread = _spawn_proxy_thread(switchyard, resolved_port)
- logger.debug(
- "proxy thread started port=%d alive=%s server_started=%s",
- resolved_port,
- thread.is_alive(),
- server.started,
- )
- startup_timing.mark("proxy thread started")
+ server = _start_native_server(config)
+ resolved_port = server.port
+ stats = server.stats
+ strategy_summary = f"config → {config.name}"
try:
if not _wait_ready(resolved_port):
- logger.debug(
- "proxy readiness timed out port=%d thread_alive=%s server_started=%s",
- resolved_port,
- thread.is_alive(),
- server.started,
- )
print_startup_failure(
port=resolved_port,
timeout_s=_READY_TIMEOUT_S,
@@ -358,30 +141,20 @@ def _run_claude_with_switchyard(
)
return 1
- startup_timing.mark("proxy health-ready")
- suppress_uvicorn_stream_handlers()
logger.info("proxy ready on port %d", resolved_port)
- if intake is not None:
- print_intake_warning()
- from switchyard.lib.route_table import RouteTable
- table = switchyard if isinstance(switchyard, RouteTable) else None
print_ready_banner(
port=resolved_port,
display_model=display_model,
log_path=log_path,
strategy_summary=strategy_summary,
- profile_routes=table.registered_models() if table is not None else None,
- default_route=table.default_model() if table is not None else None,
+ profile_routes=[display_model],
+ default_route=display_model,
)
if stdin_is_tty():
banner_pause()
health = ProxyHealthMonitor(resolved_port)
- env_overrides = _claude_env(
- resolved_port,
- display_model,
- intake=intake,
- )
+ env_overrides = _claude_env(resolved_port, display_model)
logger.debug(
"claude env ANTHROPIC_BASE_URL=%s ANTHROPIC_MODEL=%s "
"ANTHROPIC_CUSTOM_MODEL_OPTION=%s GATEWAY_DISCOVERY=%s",
@@ -390,12 +163,10 @@ def _run_claude_with_switchyard(
env_overrides.get("ANTHROPIC_CUSTOM_MODEL_OPTION"),
env_overrides.get("CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY"),
)
- startup_timing.mark("child agent spawned")
- startup_timing.dump()
if stdin_is_tty():
footer = LiveStatsFooter(
- stats, display_model, health, table=table,
- strategy_label=strategy_summary.split(":")[0].strip() if strategy_summary else None,
+ stats, display_model, health,
+ strategy_label="config",
)
tui = ShellTUI(
command=[claude_bin, *claude_args],
@@ -406,143 +177,21 @@ def _run_claude_with_switchyard(
return tui.run()
return _supervise_claude_plain(
claude_bin, claude_args, resolved_port, display_model,
- intake=intake,
)
finally:
print_session_summary(stats)
- server.should_exit = True
- thread.join(timeout=_SHUTDOWN_JOIN_S)
+ server.close()
-def launch_claude(
+def launch_claude_config(
+ config: Path,
model: str,
- base_url: str,
- api_key: str,
- port: int | None,
- timeout: float | None,
claude_args: list[str],
- intake: LaunchIntakeConfig | None = None,
- routing_profiles: str | None = None,
- rl_log_dir: Path | None = None,
) -> int:
- """Start a passthrough proxy and run ``claude`` against it.
-
- Single-model UX — ``model`` seeds Claude Code's session, while the
- proxy preserves any model Claude Code sends later so ``/model``
- selections remain effective.
-
- When ``routing_profiles`` is given, the launcher builds a
- :class:`RouteTable` instead of a single chain: ``model`` is
- registered as a tier passthrough, then every entry from the YAML file
- is merged on top via :meth:`RouteTable.register`. YAML routes
- win on id conflict. The launcher's stats accumulator is threaded into
- both the launcher's chain and the YAML loader so all traffic records
- into the same accumulator.
-
- Returns the ``claude`` process's exit code (or ``127`` if the
- binary wasn't found, ``130`` on Ctrl-C).
- """
+ """Run Claude Code against an explicit native server TOML deployment."""
_quiet_launch_loggers()
- stats = StatsAccumulator()
- intake_request, intake_response = build_launch_capture_processors(intake, rl_log_dir)
- switchyard = _build_claude_switchyard(
- model=model,
- api_key=api_key,
- base_url=base_url,
- timeout=timeout,
- stats=stats,
- extra_request_processors=intake_request,
- extra_response_processors=intake_response,
- )
- app: SwitchyardApp = build_single_model_table(model, switchyard)
- if routing_profiles is not None:
- # Wrap the single chain in a RouteTable so YAML routes can
- # merge on top. The launcher's chain registers under `model`; YAML
- # entries land alongside (and override on id conflict).
- from switchyard.lib.route_table import RouteTable
- table = app
- assert isinstance(table, RouteTable)
- yaml_table = load_route_bundle_table(
- routing_profiles,
- stats_accumulator=stats,
- pre_routing_request_processors=intake_request,
- extra_response_processors=intake_response,
- )
- for sub_model, sub_chain, sub_metadata in yaml_table.items():
- table.register(sub_model, sub_chain, metadata=sub_metadata)
- for warning in yaml_table.model_listing_warnings():
- table.add_model_listing_warning(warning)
- app = table
- strategy_summary = (
- routing_profiles_strategy_summary(routing_profiles, model)
- if routing_profiles is not None
- else passthrough_strategy_summary(model)
- )
return _run_claude_with_switchyard(
- app,
- display_model=model,
- port=port,
- claude_args=claude_args,
- stats=stats,
- intake=intake,
- strategy_summary=strategy_summary,
- )
-
-
-
-
-def launch_claude_deterministic_routing(
- config: DeterministicRoutingConfig,
- port: int | None,
- claude_args: list[str],
- intake: LaunchIntakeConfig | None = None,
- discovery_disabled: bool = False,
- rl_log_dir: Path | None = None,
-) -> int:
- """Start a deterministic-routing proxy and run ``claude`` against it.
-
- The LLM-classifier chain (classifier → tier selector → per-tier dispatch)
- is wrapped in a :class:`RouteTable` whose virtual model is the
- deterministic routing target. Configured strong + weak models register
- as direct passthrough chains so the Claude Code ``/model`` picker can
- override the routing policy. The classifier is not user-selectable.
- """
- from switchyard.cli.model_catalog.model_discovery import fetch_model_ids
- from switchyard.lib.route_table_builders import (
- build_deterministic_routing_switchyard,
- build_deterministic_routing_table,
- deterministic_routing_virtual_model_id,
- )
-
- def _discovery_fn(base_url: str, api_key: str) -> list[str]:
- return fetch_model_ids(base_url, api_key)
-
- _quiet_launch_loggers()
- stats = StatsAccumulator()
- intake_request, intake_response = build_launch_capture_processors(intake, rl_log_dir)
- switchyard = build_deterministic_routing_switchyard(
config,
- stats,
- pre_routing_request_processors=intake_request,
- extra_response_processors=intake_response,
- )
- routing_model = deterministic_routing_virtual_model_id(config)
- discovery_fn = None if discovery_disabled else _discovery_fn
- model_table = build_deterministic_routing_table(
- config,
- stats,
- deterministic_routing_switchyard=switchyard,
- routing_model=routing_model,
- discovery_fn=discovery_fn,
- pre_routing_request_processors=intake_request,
- extra_response_processors=intake_response,
- )
- return _run_claude_with_switchyard(
- model_table,
- display_model=routing_model,
- port=port,
+ display_model=model,
claude_args=claude_args,
- stats=stats,
- intake=intake,
- strategy_summary=deterministic_strategy_summary(config),
)
diff --git a/switchyard/cli/launchers/codex_cli_launcher.py b/switchyard/cli/launchers/codex_cli_launcher.py
index 63605c908..204005399 100644
--- a/switchyard/cli/launchers/codex_cli_launcher.py
+++ b/switchyard/cli/launchers/codex_cli_launcher.py
@@ -1,42 +1,15 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""One-command ``codex`` + V2 proxy supervisor.
-
-Sibling of :mod:`switchyard.cli.launchers.claude_code_launcher`, but
-spawns the OpenAI Codex CLI instead of Claude Code:
-
-* ``switchyard launch codex --model <name>`` — single-model
- passthrough. Spin up an in-process V2 passthrough proxy on a free
- local port, wire up a Responses-native OpenAI backend through the generic
- ``LlmTarget`` recipe, then spawn ``codex`` against the proxy.
-
-Codex is OpenAI-Responses-API-only (the inbound request hits
-``POST /v1/responses`` on the proxy), and its built-in ``openai``
-provider does **not** honor ``OPENAI_BASE_URL``. Pointing it at a
-custom endpoint requires defining a ``[model_providers.<id>]`` block in
-``~/.codex/config.toml`` *or* injecting one transiently via repeated
-``-c`` flags. We use the second path so the user's existing
-``config.toml`` is untouched and the proxy is fully self-contained.
-
-Shared launcher helpers handle the proxy process, debug logging, and live
-Switchyard stats footer so Codex and Claude Code expose the same operator
-surface.
-
-When ``codex`` exits (or Ctrl-C), the proxy thread is torn down cleanly.
-"""
+"""Run Codex through an in-process native Switchyard server."""
import json
import logging
import os
import shutil
import subprocess
-import threading
from collections.abc import Sequence
from pathlib import Path
-from typing import Any
-
-import uvicorn
from switchyard.cli.launchers.codex_model_catalog import (
CodexModelCatalogEntry,
@@ -44,76 +17,31 @@ from switchyard.cli.launchers.codex_model_catalog import (
_remove_codex_model_catalog,
_write_codex_model_catalog,
)
-from switchyard.cli.launchers.launch_intake_config import (
- LaunchIntakeConfig,
- build_launch_capture_processors,
- print_intake_warning,
-)
from switchyard.cli.launchers.launcher_runtime import (
banner_pause,
configure_debug_file_logging,
- deterministic_strategy_summary,
- find_free_port,
- passthrough_strategy_summary,
print_ready_banner,
print_startup_failure,
- routing_profiles_strategy_summary,
silence_launch_loggers,
- spawn_proxy_thread,
stdin_is_tty,
- suppress_uvicorn_stream_handlers,
wait_for_proxy_ready,
)
from switchyard.cli.launchers.live_stats_footer import LiveStatsFooter
+from switchyard.cli.launchers.native_server import NativeServer
from switchyard.cli.launchers.proxy_health_monitor import ProxyHealthMonitor
from switchyard.cli.launchers.session_summary import print_session_summary
-from switchyard.cli.route_bundle import (
- load_route_bundle_table,
-)
-from switchyard.lib.backends.llm_target import BackendFormat, LlmTarget
-from switchyard.lib.processors.model_rewrite_request_processor import (
- ModelRewriteRequestProcessor,
-)
-from switchyard.lib.profiles import (
- DeterministicRoutingConfig,
-)
-from switchyard.lib.profiles.random_routing import (
- RandomRoutingConfig,
-)
-from switchyard.lib.route_table import ChainRuntime, SwitchyardApp
-from switchyard.lib.route_table_builders import (
- build_single_model_table,
- build_tier_passthrough_switchyard,
- random_routing_virtual_model_id,
-)
-from switchyard.lib.stats_accumulator import StatsAccumulator
from switchyard.server.shell_tui import ShellTUI
logger = logging.getLogger(__name__)
_READY_TIMEOUT_S = 10.0
-_SHUTDOWN_JOIN_S = 3.0
_EXIT_BINARY_NOT_FOUND = 127
_EXIT_SIGINT = 130
-
-# Identifier we register the transient provider under via ``-c`` overrides.
-# Arbitrary — codex only cares that ``model_provider`` matches a key in
-# ``model_providers``. Kept short so the ``codex`` argv stays readable.
_PROVIDER_ID = "switchyard"
-_ModelRewriteRequestProcessor = ModelRewriteRequestProcessor
-_find_free_port = find_free_port
-
-
def _find_codex_binary() -> str | None:
- """Locate the ``codex`` executable.
-
- Checks ``$PATH`` first, then falls back to the two paths Codex's
- installers commonly write to: ``~/.npm-global/bin/codex`` (the
- ``npm install -g @openai/codex`` default on machines that pin npm's
- global prefix) and ``~/.local/bin/codex`` (alternative layouts).
- """
+ """Locate the ``codex`` executable."""
path_hit = shutil.which("codex")
if path_hit:
return path_hit
@@ -131,148 +59,36 @@ def _wait_ready(port: int, timeout_s: float = _READY_TIMEOUT_S) -> bool:
return wait_for_proxy_ready(port, timeout_s=timeout_s)
-def _build_switchyard(
- model: str,
- api_key: str,
- base_url: str,
- timeout: float | None,
- stats: StatsAccumulator,
- extra_request_processors: Sequence[Any] = (),
- extra_response_processors: Sequence[Any] = (),
-) -> ChainRuntime:
- """OpenAI Responses-native chain with live stats.
-
- Codex always speaks ``POST /v1/responses``. Uses :class:`BackendFormat.AUTO`
- so the resolver probes ``/v1/responses`` at startup: native pass-through for
- OpenAI upstreams, Chat Completions translation for upstreams like NVIDIA NIM
- that don't expose the Responses endpoint.
- """
- return build_tier_passthrough_switchyard(
- LlmTarget(
- id="default",
- model=model,
- format=BackendFormat.AUTO,
- api_key=api_key,
- base_url=base_url,
- timeout_secs=timeout,
- ),
- stats=stats,
- enable_stats=True,
- extra_request_processors=extra_request_processors,
- extra_response_processors=extra_response_processors,
- )
-
-
-def _spawn_proxy_thread(
- switchyard: SwitchyardApp, port: int,
-) -> tuple[uvicorn.Server, threading.Thread]:
- """Run uvicorn in a background daemon thread, return (server, thread)."""
- return spawn_proxy_thread(
- switchyard, port, thread_name="launch-codex-proxy",
- )
-
-
-def _format_codex_http_headers(headers: dict[str, str]) -> str:
- """Encode header dict as a TOML inline table for codex's ``-c`` flag."""
- parts = ", ".join(f'"{name}"="{value}"' for name, value in headers.items())
- return "{" + parts + "}"
-
-
-def _codex_catalog_entry_for_registered_model(
- model_id: str,
- config: RandomRoutingConfig,
-) -> CodexModelCatalogEntry:
- """Build a Codex picker entry for *model_id*, matching its role in *config*.
-
- The routing virtual id, the configured strong/weak models, and any
- discovered model each get a tailored display name and description so the
- Codex ``model`` picker explains what it would route to.
- """
- routing_model = random_routing_virtual_model_id(config)
- if model_id == routing_model:
- return (
- model_id,
- "Switchyard random routing",
- (
- "Random routes "
- f"{config.strong.model} (strong) and {config.weak.model} (weak), "
- f"p_strong={config.strong_probability:.2f}."
- ),
- )
- if model_id == config.strong.model:
- return (
- model_id,
- f"{_codex_model_display_name(model_id)} (Switchyard strong)",
- f"Direct Switchyard route to {model_id}.",
- )
- if model_id == config.weak.model:
- return (
- model_id,
- f"{_codex_model_display_name(model_id)} (Switchyard weak)",
- f"Direct Switchyard route to {model_id}.",
- )
- return (
- model_id,
- f"{_codex_model_display_name(model_id)} (Switchyard)",
- f"Direct Switchyard passthrough to discovered model {model_id}.",
- )
-
-
def _provider_overrides(
- port: int, *,
- intake: LaunchIntakeConfig | None = None,
+ port: int,
+ *,
model_catalog_json: str | None = None,
) -> list[str]:
- """Build the ``-c key=value`` argv pairs that point codex at the proxy.
-
- Codex's ``-c`` flag takes a dotted ``key=value`` pair and parses the
- value as TOML, so string values must be wrapped in literal double
- quotes inside the argv string.
-
- Base overrides:
-
- * ``model_provider="switchyard"`` — switch the active provider.
- * ``model_providers.switchyard.name="switchyard"`` — display name.
- * ``model_providers.switchyard.base_url="http://127.0.0.1:<port>/v1"``
- — point at the local proxy.
- * ``model_providers.switchyard.wire_api="responses"`` — codex's
- Responses-API wire format, which our
- :class:`ResponsesEndpoint` accepts at ``/v1/responses``.
- * ``model_providers.switchyard.env_key="OPENAI_API_KEY"`` — name of
- the env var codex reads the bearer token from.
- * ``model_providers.switchyard.requires_openai_auth=false`` — opt
- out of the OAuth/login flow that the built-in ``openai`` provider
- uses; we want the env-key path, full stop.
- * ``model_catalog_json="..."`` — optional Switchyard-only catalog so
- Codex's ``/model`` picker can switch back to routed models.
- """
+ """Build transient Codex provider overrides for the local proxy."""
base_url = f"http://127.0.0.1:{port}/v1"
overrides = [
- "-c", f'model_provider="{_PROVIDER_ID}"',
- "-c", f'model_providers.{_PROVIDER_ID}.name="{_PROVIDER_ID}"',
- "-c", f'model_providers.{_PROVIDER_ID}.base_url="{base_url}"',
- "-c", f'model_providers.{_PROVIDER_ID}.wire_api="responses"',
- "-c", f'model_providers.{_PROVIDER_ID}.env_key="OPENAI_API_KEY"',
- "-c", f"model_providers.{_PROVIDER_ID}.requires_openai_auth=false",
+ "-c",
+ f'model_provider="{_PROVIDER_ID}"',
+ "-c",
+ f'model_providers.{_PROVIDER_ID}.name="{_PROVIDER_ID}"',
+ "-c",
+ f'model_providers.{_PROVIDER_ID}.base_url="{base_url}"',
+ "-c",
+ f'model_providers.{_PROVIDER_ID}.wire_api="responses"',
+ "-c",
+ f'model_providers.{_PROVIDER_ID}.env_key="OPENAI_API_KEY"',
+ "-c",
+ f"model_providers.{_PROVIDER_ID}.requires_openai_auth=false",
]
if model_catalog_json is not None:
- overrides.extend([
- "-c", f"model_catalog_json={json.dumps(model_catalog_json)}",
- ])
- if intake is not None:
- headers_toml = _format_codex_http_headers(intake.opt_in_headers())
- overrides.extend([
- "-c", f"model_providers.{_PROVIDER_ID}.http_headers={headers_toml}",
- ])
+ overrides.extend(["-c", f"model_catalog_json={json.dumps(model_catalog_json)}"])
return overrides
-def _codex_env(intake: LaunchIntakeConfig | None = None) -> dict[str, str]:
- """Environment that makes Codex accept the transient Switchyard provider."""
+def _codex_env() -> dict[str, str]:
+ """Return the environment required by the transient provider."""
env = os.environ.copy()
env["OPENAI_API_KEY"] = "switchyard"
- if intake is not None:
- env["SWITCHYARD_SESSION_ID"] = intake.session_id
return env
@@ -281,13 +97,12 @@ def _codex_command(
codex_args: list[str],
port: int,
model: str,
- intake: LaunchIntakeConfig | None = None,
model_catalog_json: str | None = None,
) -> list[str]:
- """Build the exact Codex argv for the transient Switchyard provider."""
+ """Build the exact Codex command for the local proxy."""
return [
codex_bin,
- *_provider_overrides(port, intake=intake, model_catalog_json=model_catalog_json),
+ *_provider_overrides(port, model_catalog_json=model_catalog_json),
"-m",
model,
*codex_args,
@@ -299,33 +114,9 @@ def _supervise_codex(
codex_args: list[str],
port: int,
model: str,
- intake: LaunchIntakeConfig | None = None,
model_catalog_json: str | None = None,
) -> int:
- """Run ``codex`` with proxy provider injected; return its exit code.
-
- ``subprocess.run`` inherits stdin/stdout/stderr so the interactive
- TUI works. ``KeyboardInterrupt`` during the child is translated to
- 130 so callers can surface a meaningful exit code.
-
- Argv layout:
-
- * ``-c`` overrides from :func:`_provider_overrides` register
- the transient ``switchyard`` provider and switch to it (no edits
- to ``~/.codex/config.toml``).
- * ``-m <model>`` pins the initial model on the codex side so its
- session header / status line shows the right name. The proxy
- preserves Codex's request model so client-side model selection can
- route through the same process.
- * Caller-supplied ``codex_args`` (anything after the ``--``
- sentinel) are forwarded last so they can override our flags.
-
- Env tweak: ``OPENAI_API_KEY="switchyard"`` — opaque placeholder
- that satisfies codex's "no env_key set, refusing to start"
- precondition. The proxy ignores the inbound ``Authorization``
- header; the real upstream credential is injected by
- :class:`OpenAiNativeBackend` at call time.
- """
+ """Run Codex and return its exit code."""
try:
result = subprocess.run(
_codex_command(
@@ -333,10 +124,9 @@ def _supervise_codex(
codex_args,
port,
model,
- intake=intake,
model_catalog_json=model_catalog_json,
),
- env=_codex_env(intake=intake),
+ env=_codex_env(),
check=False,
)
return result.returncode
@@ -344,17 +134,18 @@ def _supervise_codex(
return _EXIT_SIGINT
+def _start_native_server(config: Path) -> NativeServer:
+ """Start the native server; kept separate for supervision tests."""
+ return NativeServer(config)
+
+
def _run_codex_with_switchyard(
- switchyard: SwitchyardApp,
+ config: Path,
display_model: str,
- port: int | None,
codex_args: list[str],
- stats: StatsAccumulator,
- intake: LaunchIntakeConfig | None = None,
- codex_model_catalog: Sequence[CodexModelCatalogEntry] = (),
- strategy_summary: str | None = None,
+ codex_model_catalog: Sequence[CodexModelCatalogEntry],
) -> int:
- """Chain-agnostic supervisor: host ``switchyard`` then spawn codex."""
+ """Host a native deployment and run Codex against it."""
codex_bin = _find_codex_binary()
if codex_bin is None:
logger.error(
@@ -363,15 +154,16 @@ def _run_codex_with_switchyard(
)
return _EXIT_BINARY_NOT_FOUND
- model_catalog_json = _write_codex_model_catalog(codex_bin, codex_model_catalog)
silence_launch_loggers(local_logger=logger)
log_path = configure_debug_file_logging(display_model=display_model)
- resolved_port = port if port is not None else _find_free_port()
- server: uvicorn.Server | None = None
- thread: threading.Thread | None = None
+ server = _start_native_server(config)
+ resolved_port = server.port
+ stats = server.stats
+ model_catalog_json: str | None = None
+ strategy_summary = f"config → {config.name}"
try:
- server, thread = _spawn_proxy_thread(switchyard, resolved_port)
+ model_catalog_json = _write_codex_model_catalog(codex_bin, codex_model_catalog)
if not _wait_ready(resolved_port):
print_startup_failure(
port=resolved_port,
@@ -380,19 +172,14 @@ def _run_codex_with_switchyard(
)
return 1
- suppress_uvicorn_stream_handlers()
logger.info("proxy ready on port %d", resolved_port)
- if intake is not None:
- print_intake_warning()
- from switchyard.lib.route_table import RouteTable
- table = switchyard if isinstance(switchyard, RouteTable) else None
print_ready_banner(
port=resolved_port,
display_model=display_model,
log_path=log_path,
strategy_summary=strategy_summary,
- profile_routes=table.registered_models() if table is not None else None,
- default_route=table.default_model() if table is not None else None,
+ profile_routes=[display_model],
+ default_route=display_model,
)
if stdin_is_tty():
banner_pause()
@@ -402,8 +189,7 @@ def _run_codex_with_switchyard(
stats,
display_model,
ProxyHealthMonitor(resolved_port),
- table=table,
- strategy_label=strategy_summary.split(":")[0].strip() if strategy_summary else None,
+ strategy_label="config",
)
return ShellTUI(
command=_codex_command(
@@ -411,232 +197,42 @@ def _run_codex_with_switchyard(
codex_args,
resolved_port,
display_model,
- intake=intake,
model_catalog_json=model_catalog_json,
),
footer_fn=footer.as_footer_fn(),
footer_height=lambda: footer.height,
- env=_codex_env(intake=intake),
+ env=_codex_env(),
).run()
return _supervise_codex(
- codex_bin, codex_args, resolved_port, display_model,
- intake=intake, model_catalog_json=model_catalog_json,
+ codex_bin,
+ codex_args,
+ resolved_port,
+ display_model,
+ model_catalog_json=model_catalog_json,
)
finally:
print_session_summary(stats)
- if server is not None:
- server.should_exit = True
- if thread is not None:
- thread.join(timeout=_SHUTDOWN_JOIN_S)
+ server.close()
_remove_codex_model_catalog(model_catalog_json)
-def launch_codex(
+def launch_codex_config(
+ config: Path,
model: str,
- base_url: str,
- api_key: str,
- port: int | None,
- timeout: float | None,
codex_args: list[str],
- intake: LaunchIntakeConfig | None = None,
- routing_profiles: str | None = None,
- rl_log_dir: Path | None = None,
) -> int:
- """Start a passthrough proxy and run ``codex`` against it.
-
- Single-model UX — ``model`` seeds the Codex session, while the proxy
- preserves any model Codex sends later so client-side model selection
- remains effective.
-
- When ``routing_profiles`` is given, the launcher builds a
- :class:`RouteTable` instead of a single chain: ``model`` is
- registered as a tier passthrough, then every entry from the YAML file
- is merged on top (including each tier's ``GET /v1/models`` catalog
- hydration). Codex's ``/model`` picker is populated from the merged
- table, so YAML-declared models appear alongside the launcher-
- configured one.
-
- Returns the ``codex`` process's exit code (or ``127`` if the
- binary wasn't found, ``130`` on Ctrl-C).
- """
- stats = StatsAccumulator()
- intake_request, intake_response = build_launch_capture_processors(intake, rl_log_dir)
- switchyard = _build_switchyard(
- model,
- api_key,
- base_url,
- timeout,
- stats,
- extra_request_processors=intake_request,
- extra_response_processors=intake_response,
- )
- codex_model_catalog: list[CodexModelCatalogEntry] = [
+ """Run Codex against a native server TOML deployment."""
+ catalog = [
(
model,
f"{_codex_model_display_name(model)} (Switchyard)",
- f"Routed through Switchyard to {model}.",
- ),
- ]
- app: SwitchyardApp = build_single_model_table(model, switchyard)
- if routing_profiles is not None:
- # Wrap the single chain in a RouteTable so YAML routes can
- # merge on top. The launcher's `model` registers as a tier
- # passthrough; YAML entries land alongside (override on id conflict).
- # Codex's /model picker iterates the table, so YAML-declared
- # models surface in the picker automatically.
- from switchyard.lib.route_table import RouteTable
- table = app
- assert isinstance(table, RouteTable)
- yaml_table = load_route_bundle_table(
- routing_profiles,
- stats_accumulator=stats,
- pre_routing_request_processors=intake_request,
- extra_response_processors=intake_response,
+ f"Route from {config.name}.",
)
- for sub_model, sub_chain, sub_metadata in yaml_table.items():
- table.register(sub_model, sub_chain, metadata=sub_metadata)
- for warning in yaml_table.model_listing_warnings():
- table.add_model_listing_warning(warning)
- app = table
- # Extend the codex catalog to include every YAML-registered model.
- catalog_models = {entry[0] for entry in codex_model_catalog}
- for model_id in table.registered_models():
- if model_id in catalog_models:
- continue
- codex_model_catalog.append((
- model_id,
- f"{_codex_model_display_name(model_id)} (Switchyard)",
- f"Routed through Switchyard to {model_id}.",
- ))
- catalog_models.add(model_id)
- strategy_summary = (
- routing_profiles_strategy_summary(routing_profiles, model)
- if routing_profiles is not None
- else passthrough_strategy_summary(model)
- )
- return _run_codex_with_switchyard(
- app,
- display_model=model,
- port=port,
- codex_args=codex_args,
- stats=stats,
- intake=intake,
- codex_model_catalog=codex_model_catalog,
- strategy_summary=strategy_summary,
- )
-
-
-
-
-def _codex_catalog_entry_for_deterministic_model(
- model_id: str,
- config: DeterministicRoutingConfig,
-) -> CodexModelCatalogEntry:
- """Build a Codex picker entry tailored to a deterministic-routing config."""
- from switchyard.lib.route_table_builders import (
- deterministic_routing_virtual_model_id,
- )
-
- routing_model = deterministic_routing_virtual_model_id(config)
- if model_id == routing_model:
- return (
- model_id,
- "Switchyard deterministic routing",
- (
- "LLM-classifier routes between "
- f"{config.strong.model} (strong) and {config.weak.model} (weak) "
- f"using {config.classifier.model} (classifier, "
- f"profile={config.profile_name})."
- ),
- )
- if model_id == config.strong.model:
- return (
- model_id,
- f"{_codex_model_display_name(model_id)} (Switchyard strong)",
- f"Direct Switchyard route to {model_id}.",
- )
- if model_id == config.weak.model:
- return (
- model_id,
- f"{_codex_model_display_name(model_id)} (Switchyard weak)",
- f"Direct Switchyard route to {model_id}.",
- )
- return (
- model_id,
- f"{_codex_model_display_name(model_id)} (Switchyard)",
- f"Direct Switchyard passthrough to discovered model {model_id}.",
- )
-
-
-def launch_codex_deterministic_routing(
- config: DeterministicRoutingConfig,
- port: int | None,
- codex_args: list[str],
- intake: LaunchIntakeConfig | None = None,
- discovery_disabled: bool = False,
- rl_log_dir: Path | None = None,
-) -> int:
- """Start a deterministic-routing proxy and run ``codex`` against it."""
- from switchyard.cli.model_catalog.model_discovery import fetch_model_ids
- from switchyard.lib.route_table_builders import (
- build_deterministic_routing_switchyard,
- build_deterministic_routing_table,
- deterministic_routing_virtual_model_id,
- )
-
- def _discovery_fn(base_url: str, api_key: str) -> list[str]:
- return fetch_model_ids(base_url, api_key)
-
- stats = StatsAccumulator()
- intake_request, intake_response = build_launch_capture_processors(intake, rl_log_dir)
- switchyard = build_deterministic_routing_switchyard(
- config,
- stats,
- pre_routing_request_processors=intake_request,
- extra_response_processors=intake_response,
- )
- routing_model = deterministic_routing_virtual_model_id(config)
- discovery_fn = None if discovery_disabled else _discovery_fn
- model_table = build_deterministic_routing_table(
- config,
- stats,
- deterministic_routing_switchyard=switchyard,
- routing_model=routing_model,
- discovery_fn=discovery_fn,
- pre_routing_request_processors=intake_request,
- extra_response_processors=intake_response,
- )
- codex_model_catalog: list[CodexModelCatalogEntry] = [
- _codex_catalog_entry_for_deterministic_model(
- model_id=routing_model,
- config=config,
- ),
- _codex_catalog_entry_for_deterministic_model(
- model_id=config.strong.model,
- config=config,
- ),
]
- catalog_models = {entry[0] for entry in codex_model_catalog}
- for model_id in model_table.registered_models():
- if model_id in catalog_models:
- continue
- codex_model_catalog.append(_codex_catalog_entry_for_deterministic_model(
- model_id=model_id,
- config=config,
- ))
- catalog_models.add(model_id)
return _run_codex_with_switchyard(
- model_table,
- # Boot codex on the virtual routing model so the LLM classifier runs by
- # default — matches launch_claude_deterministic_routing. Pinning the
- # strong model id here would hit its direct passthrough and silently
- # bypass routing.
- display_model=routing_model,
- port=port,
+ config,
+ display_model=model,
codex_args=codex_args,
- stats=stats,
- intake=intake,
- codex_model_catalog=codex_model_catalog,
- strategy_summary=deterministic_strategy_summary(config),
+ codex_model_catalog=catalog,
)
diff --git a/switchyard/cli/launchers/launch_intake_config.py b/switchyard/cli/launchers/launch_intake_config.py
deleted file mode 100644
index 95f9cf54a..000000000
--- a/switchyard/cli/launchers/launch_intake_config.py
+++ /dev/null
@@ -1,212 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Resolved intake configuration for the ``launch claude`` / ``launch codex`` flows.
-
-Both launchers compose two pieces when ``--intake-enabled`` is set:
-
-* server-side — the in-process proxy gets an :class:`IntakeRequestProcessor`
- + :class:`IntakeResponseProcessor` attached to its chain so each completed
- turn is shipped to NMP intake.
-* client-side — the spawned ``claude`` / ``codex`` process is given the
- per-request opt-in headers so every request the user issues actually
- triggers the sink (the intake processors short-circuit when the inbound
- request lacks the opt-in).
-
-This module owns the resolved-config dataclass that flows from CLI args /
-env vars through both seams. CLI parsing lives in
-``switchyard.cli.switchyard_cli`` and the resolver in
-``switchyard.cli.launch_command``.
-"""
-
-import re
-import secrets
-import sys
-import time
-import uuid
-from dataclasses import dataclass
-from pathlib import Path
-from typing import IO, TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
- from switchyard.lib.config import IntakeSinkConfig
-
-
-_INTAKE_WARNING_LINES = (
- "",
- " WARNING: Intake logging is enabled — your requests and responses will be",
- " logged to a database. Ensure you are following all inference",
- " rules and compliance requirements for LLM use.",
- "",
-)
-
-
-def print_intake_warning(stream: IO[str] | None = None) -> None:
- """Emit the compliance warning that runs whenever intake logging is on."""
- target = stream if stream is not None else sys.stderr
- target.write("\n".join(_INTAKE_WARNING_LINES) + "\n")
- target.flush()
-
-
-@dataclass(frozen=True)
-class LaunchIntakeConfig:
- """Everything a launcher needs to wire up the intake sink end-to-end.
-
- The auth-side fields (``base_url``, ``workspace``, ``api_key``) are
- optional because the path of least resistance is the docs' recommended
- one: leave them all unset, run
- ``uv run nmp auth login --base-url {INTAKE_BASE_URL}`` once, and the SDK
- reads everything (including a refresh-token-backed access token) from
- ``~/.config/nmp/config.yaml``. Set any of them to override that
- bootstrap (e.g. for CI/CD).
-
- ``app`` / ``task`` / ``session_id`` are always concrete because they
- drive the per-request opt-in headers regardless of which auth path the
- SDK takes.
- """
-
- base_url: str | None
- workspace: str | None
- api_key: str | None
- app: str
- task: str
- session_id: str
- user_id: str
- target_url: str | None = None
-
- @classmethod
- def from_resolved(
- cls,
- *,
- base_url: str | None,
- workspace: str | None,
- api_key: str | None,
- app: str,
- task: str,
- session_id: str | None,
- user_id: str | None = None,
- target_url: str | None = None,
- target: str,
- ) -> "LaunchIntakeConfig":
- """Resolve any blank fields and return the immutable config.
-
- ``session_id`` defaults to ``<target>-<unix-ms>-<uuid4-short>`` so each
- launch is uniquely identifiable in the intake store. Pass an explicit
- value to override (e.g. for re-runs that should join an existing
- thread).
-
- ``user_id`` defaults to the stable anonymous per-machine id so intake
- entries can be grouped by user without carrying any personal data.
- """
- return cls(
- base_url=base_url,
- workspace=workspace,
- api_key=api_key,
- app=app,
- task=task,
- session_id=session_id or _default_session_id(target),
- user_id=user_id or resolve_machine_user_id(),
- target_url=target_url,
- )
-
- def opt_in_headers(self) -> dict[str, str]:
- """Headers the spawned client must send on every request to opt in.
-
- ``IntakeRequestProcessor`` reads these via
- :meth:`RequestMetadata.from_headers` and stashes them on
- :class:`ProxyContext`; without them the sink short-circuits and no
- entry is shipped.
- """
- return {
- "x-switchyard-intake-enabled": "true",
- "x-switchyard-intake-app": self.app,
- "x-switchyard-intake-task": self.task,
- "proxy_x_session_id": self.session_id,
- }
-
- def to_sink_config(self) -> "IntakeSinkConfig":
- """Build the server-side intake sink config for this launch."""
- from switchyard.lib.config import IntakeSinkConfig
-
- return IntakeSinkConfig(
- intake_base_url=self.base_url,
- workspace=self.workspace,
- api_key=self.api_key,
- user_id=self.user_id,
- target_url=self.target_url,
- )
-
-
-def build_intake_processors(
- intake: LaunchIntakeConfig | None,
-) -> tuple[list[Any], list[Any]]:
- """Return intake processor lists for launchers, or empty lists when disabled."""
- if intake is None:
- return [], []
-
- from switchyard.lib.processors.intake_request_processor import IntakeRequestProcessor
- from switchyard.lib.processors.intake_response_processor import IntakeResponseProcessor
-
- config = intake.to_sink_config()
- return (
- [IntakeRequestProcessor()],
- [IntakeResponseProcessor(config)],
- )
-
-
-def build_launch_capture_processors(
- intake: LaunchIntakeConfig | None,
- rl_log_dir: Path | None,
-) -> tuple[list[Any], list[Any]]:
- """Combine intake + RL-logging request/response processor lists for launchers.
-
- The intake sink (``intake``) and the local RL trace logger (``rl_log_dir``)
- are independent: either, both, or neither may be active. Returns
- ``([], [])`` when neither is.
- """
- from switchyard.lib.processors.rl_logging_response_processor import (
- build_rl_logging_processors,
- )
-
- intake_request, intake_response = build_intake_processors(intake)
- rl_request, rl_response = build_rl_logging_processors(rl_log_dir)
- return [*intake_request, *rl_request], [*intake_response, *rl_response]
-
-
-def _default_session_id(target: str) -> str:
- return f"{target}-{int(time.time() * 1000)}-{uuid.uuid4().hex[:8]}"
-
-
-def _machine_user_id_path() -> Path:
- return Path.home() / ".switchyard" / "user_id"
-
-
-_USER_ID_RE = re.compile(r"^[0-9a-f]{8}$")
-
-
-def resolve_machine_user_id(path: Path | None = None) -> str:
- """Return a stable anonymous per-machine id, creating one on first use.
-
- The id is a random 8-char hex string, never derived from the username, so
- it is non-reversible. It is persisted at ``~/.switchyard/user_id`` and
- reused on later launches. Fail-open: if the file is missing, unreadable, or
- malformed, a fresh id is returned so intake never blocks a launch.
- """
- user_id = secrets.token_hex(4)
- try:
- target = path or _machine_user_id_path()
- except RuntimeError:
- # No resolvable home directory; use a fresh transient id.
- return user_id
- try:
- existing = target.read_text(encoding="utf-8").strip()
- if _USER_ID_RE.fullmatch(existing):
- return existing
- except (OSError, UnicodeError):
- pass
- try:
- target.parent.mkdir(parents=True, exist_ok=True)
- target.write_text(user_id, encoding="utf-8")
- except OSError:
- pass
- return user_id
diff --git a/switchyard/cli/launchers/launcher_runtime.py b/switchyard/cli/launchers/launcher_runtime.py
index c40367415..e8410f957 100644
--- a/switchyard/cli/launchers/launcher_runtime.py
+++ b/switchyard/cli/launchers/launcher_runtime.py
@@ -5,20 +5,11 @@
import logging
import os
-import socket
import sys
-import threading
import time
import urllib.request
from pathlib import Path
-import uvicorn
-
-from switchyard.cli.config.user_config import get_user_config_dir
-from switchyard.lib.profiles.deterministic_routing_config import DeterministicRoutingConfig
-from switchyard.lib.route_table import SwitchyardApp
-from switchyard.server.switchyard_app import build_switchyard_app
-
_debug_file_handler: logging.FileHandler | None = None
log = logging.getLogger(__name__)
@@ -27,47 +18,6 @@ log = logging.getLogger(__name__)
_LOCAL_OPENER = urllib.request.build_opener(urllib.request.ProxyHandler({}))
-#: System CA bundle paths to try (Debian/Ubuntu, RHEL/CentOS/Fedora).
-_SYSTEM_CA_BUNDLE_CANDIDATES = (
- "/etc/ssl/certs/ca-certificates.crt",
- "/etc/pki/tls/certs/ca-bundle.crt",
- "/etc/ssl/cert.pem",
-)
-
-
-def ensure_system_ssl_trust() -> None:
- """Point Python's TLS at the system CA bundle when one is available.
-
- The classifier path uses the OpenAI Python SDK → httpx, which defaults
- to certifi's CA bundle. On Linux dev environments behind a corporate
- outbound SSL intercept (NVIDIA dev boxes are one), certifi doesn't
- include the intercept CA — every classifier call fails with
- ``Connection error`` at TLS handshake. Curl and the Rust backend
- (``rustls-tls-native-roots`` feature) use the OS keystore at
- ``/etc/ssl/certs/ca-certificates.crt`` which *does* include the
- intercept CA. Setting ``SSL_CERT_FILE`` tells Python's httpx /
- OpenAI SDK to do the same.
-
- No-op when ``SSL_CERT_FILE`` is already set (user override wins) or
- when no known system bundle path exists (macOS without an explicit
- bundle; we don't touch the Mac keychain path).
- """
- if os.environ.get("SSL_CERT_FILE"):
- return
- for candidate in _SYSTEM_CA_BUNDLE_CANDIDATES:
- if os.path.exists(candidate):
- os.environ["SSL_CERT_FILE"] = candidate
- return
-
-
-def find_free_port() -> int:
- """Bind to ``127.0.0.1:0``, let the OS pick, return the chosen port."""
- with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
- s.bind(("127.0.0.1", 0))
- port: int = s.getsockname()[1]
- return port
-
-
def wait_for_proxy_ready(port: int, *, timeout_s: float) -> bool:
"""Probe ``GET /health`` until HTTP 200 or timeout."""
url = f"http://127.0.0.1:{port}/health"
@@ -83,61 +33,25 @@ def wait_for_proxy_ready(port: int, *, timeout_s: float) -> bool:
return False
-def spawn_proxy_thread(
- switchyard: SwitchyardApp,
- port: int,
- *,
- thread_name: str,
-) -> tuple[uvicorn.Server, threading.Thread]:
- """Run uvicorn in a background daemon thread."""
- app = build_switchyard_app(switchyard)
- config = uvicorn.Config(
- app,
- host="127.0.0.1",
- port=port,
- log_level="warning",
- )
- server = uvicorn.Server(config)
-
- def _run_server() -> None:
- try:
- server.run()
- except Exception:
- log.debug("uvicorn server thread crashed on port %d", port, exc_info=True)
- raise
-
- thread = threading.Thread(target=_run_server, name=thread_name, daemon=True)
- thread.start()
- log.debug(
- "spawned proxy thread name=%s port=%d alive=%s",
- thread.name,
- port,
- thread.is_alive(),
- )
- return server, thread
-
-
def configure_debug_file_logging(*, display_model: str) -> Path:
"""Move launcher diagnostics to a per-run debug log and return its path."""
global _debug_file_handler
- log_dir = get_user_config_dir() / "logs"
+ state_home = os.environ.get("XDG_STATE_HOME")
+ state_dir = (
+ Path(state_home).expanduser()
+ if state_home
+ else Path.home() / ".local" / "state"
+ )
+ log_dir = state_dir / "switchyard" / "logs"
log_dir.mkdir(parents=True, exist_ok=True)
log_path = log_dir / f"switchyard-{os.getpid()}.log"
if _debug_file_handler is not None:
_debug_file_handler.close()
- # Truncate any prior file under this pid (only matters if a stale launch
- # left one behind), then open the FileHandler in append + delay mode.
- # Background: uvicorn's startup runs `logging.config.dictConfig(...)`,
- # which internally calls `logging.shutdown()` on every registered handler.
- # `FileHandler.close()` then sets `stream=None` AND sets `_closed=True`.
- # If we'd opened in mode="w", `FileHandler.emit()` refuses to reopen the
- # stream (to avoid silently truncating the file a second time), and every
- # subsequent log line vanishes — the handler is still attached but
- # streamless. Append + delay sidesteps this: the handler is allowed to
- # reopen its stream on demand, and the file content is preserved.
+ # Truncate any prior file under this pid, then let the delayed handler open
+ # it only when the first diagnostic is emitted.
log_path.write_text("", encoding="utf-8")
file_handler = logging.FileHandler(
log_path, mode="a", encoding="utf-8", delay=True,
@@ -161,9 +75,6 @@ def configure_debug_file_logging(*, display_model: str) -> Path:
"httpcore",
"openai",
"anthropic",
- "uvicorn",
- "uvicorn.error",
- "uvicorn.access",
):
logger = logging.getLogger(name)
for handler in logger.handlers[:]:
@@ -187,9 +98,6 @@ def silence_launch_loggers(*, local_logger: logging.Logger) -> None:
"switchyard",
"httpx",
"httpcore",
- "uvicorn",
- "uvicorn.access",
- "uvicorn.error",
"openai",
"anthropic",
):
@@ -197,21 +105,6 @@ def silence_launch_loggers(*, local_logger: logging.Logger) -> None:
local_logger.setLevel(logging.INFO)
-def suppress_uvicorn_stream_handlers() -> None:
- """Remove uvicorn stdout/stderr handlers after startup."""
- for name in ("uvicorn", "uvicorn.error", "uvicorn.access"):
- logger = logging.getLogger(name)
- for handler in logger.handlers[:]:
- if isinstance(handler, logging.FileHandler):
- continue
- logger.removeHandler(handler)
- handler.close()
- if _debug_file_handler is not None and _debug_file_handler not in logger.handlers:
- logger.addHandler(_debug_file_handler)
- logger.setLevel(logging.DEBUG)
- logger.propagate = False
-
-
def stdin_is_tty() -> bool:
"""Return whether stdin is a usable TTY."""
try:
@@ -220,11 +113,6 @@ def stdin_is_tty() -> bool:
return False
-def passthrough_strategy_summary(model: str) -> str:
- """Return the strategy summary string for a single-model passthrough."""
- return f"passthrough → {model}"
-
-
def routing_profiles_strategy_summary(routing_profiles: str, default_model: str) -> str:
"""Return the strategy summary for the default route in a routing-profiles launch.
@@ -280,15 +168,6 @@ def _route_type_summary(route_type: str, route: object, route_key: str) -> str:
return f"{route_type}: {route_key}"
-def deterministic_strategy_summary(config: DeterministicRoutingConfig) -> str:
- """Return the strategy summary string for a deterministic (LLM-classifier) launch."""
- return (
- f"llm-classifier: classifier={config.classifier.model}, "
- f"strong={config.strong.model}, weak={config.weak.model}, "
- f"profile={config.profile_name}"
- )
-
-
# Keys that are abbreviated in the banner display.
_KEY_ABBREV: dict[str, str] = {
"confidence_threshold": "conf",
@@ -395,7 +274,7 @@ def print_ready_banner(
"",
f" {dim('proxy')} {cyan(base)}",
f" {dim('models')} {dim(f'curl -s {base}/v1/models')}",
- f" {dim('stats')} {dim(f'curl -s {base}/v1/routing/stats | python3 -m json.tool')}",
+ f" {dim('stats')} {dim(f'curl -s {base}/v1/stats | python3 -m json.tool')}",
]
if log_path is not None:
lines.append(f" {dim('debug')} {dim(str(log_path))}")
diff --git a/switchyard/cli/launchers/live_stats_footer.py b/switchyard/cli/launchers/live_stats_footer.py
index 7d1888bf5..ade41d6c6 100644
--- a/switchyard/cli/launchers/live_stats_footer.py
+++ b/switchyard/cli/launchers/live_stats_footer.py
@@ -13,8 +13,8 @@ from collections.abc import Callable, Mapping
from typing import cast
from switchyard.cli.launchers.proxy_health_monitor import ProxyHealthMonitor
+from switchyard.cli.launchers.stats_source import StatsSource
from switchyard.lib.route_table import RouteTable
-from switchyard.lib.stats_accumulator import StatsAccumulator
FOOTER_ROWS = 2
@@ -24,7 +24,7 @@ class LiveStatsFooter:
def __init__(
self,
- stats: StatsAccumulator,
+ stats: StatsSource,
model: str,
health: ProxyHealthMonitor,
*,
diff --git a/switchyard/cli/launchers/native_server.py b/switchyard/cli/launchers/native_server.py
new file mode 100644
index 000000000..ad38adf80
--- /dev/null
+++ b/switchyard/cli/launchers/native_server.py
@@ -0,0 +1,56 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Native Rust server lifecycle for coding-agent launchers."""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.request
+from collections.abc import Mapping
+from pathlib import Path
+
+from switchyard.cli.launchers.stats_source import StatsSource
+
+log = logging.getLogger(__name__)
+
+_LOCAL_OPENER = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+
+
+class HttpStatsSource(StatsSource):
+ """Read launcher statistics from the native server."""
+
+ def __init__(self, base_url: str) -> None:
+ self._url = f"{base_url}/v1/stats"
+ self._last_snapshot: Mapping[str, object] = {}
+
+ def snapshot_sync(self) -> Mapping[str, object]:
+ """Return fresh stats, retaining the last snapshot on transient failure."""
+ try:
+ with _LOCAL_OPENER.open(self._url, timeout=0.5) as response:
+ payload = json.load(response)
+ if isinstance(payload, dict):
+ self._last_snapshot = payload
+ except Exception:
+ log.debug("failed to fetch native launcher stats", exc_info=True)
+ return self._last_snapshot
+
+
+class NativeServer:
+ """Host one TOML deployment through the PyO3 Rust server binding."""
+
+ def __init__(self, config: Path) -> None:
+ from switchyard_rust.server import Server
+
+ self._server = Server(config, port=0)
+ self.port: int = self._server.port
+ self.base_url: str = self._server.base_url
+ self.stats: StatsSource = HttpStatsSource(self.base_url)
+
+ def close(self) -> None:
+ """Gracefully stop the native server."""
+ self._server.close()
+
+
+__all__ = ["HttpStatsSource", "NativeServer"]
diff --git a/switchyard/cli/launchers/openclaw_launcher.py b/switchyard/cli/launchers/openclaw_launcher.py
index 1eb70610e..321956f9a 100644
--- a/switchyard/cli/launchers/openclaw_launcher.py
+++ b/switchyard/cli/launchers/openclaw_launcher.py
@@ -1,44 +1,7 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""One-command ``openclaw`` + V2 proxy supervisor.
-
-Sibling of :mod:`switchyard.cli.launchers.claude_code_launcher` and
-:mod:`switchyard.cli.launchers.codex_cli_launcher`, but spawns the
-`OpenClaw <https://github.com/openclaw/openclaw>`_ personal-agent CLI
-instead of Claude Code / Codex:
-
-* ``switchyard launch openclaw --model <name>`` — single-model
- passthrough. Spin up an in-process V2 passthrough proxy on a free
- local port, wire up an OpenAI Chat backend through the generic
- ``LlmTarget`` recipe, then spawn ``openclaw chat`` against the proxy.
-
-Unlike Claude Code (env-var overrides) and Codex (transient ``-c``
-provider overrides), OpenClaw is configured exclusively through its
-JSON5 config file at ``~/.openclaw/openclaw.json`` — there is no
-per-invocation ``--model`` / ``--base-url`` / ``-c key=value`` override
-on the CLI. OpenClaw does recognise ``OPENCLAW_CONFIG_PATH`` /
-``OPENCLAW_STATE_DIR`` / ``OPENCLAW_HOME`` env vars to relocate config
-and state, so we use a transient workspace:
-
-1. ``tempfile.mkdtemp(prefix="switchyard-openclaw-")`` creates an
- ephemeral state dir that survives only for this launch.
-2. A minimal ``openclaw.json`` lands in that dir declaring a
- ``models.providers.switchyard`` block (baseUrl → proxy, ``api:
- "openai-completions"``) and pinning ``agents.defaults.model.primary``
- to the switchyard-prefixed model id.
-3. ``OPENCLAW_STATE_DIR`` / ``OPENCLAW_HOME`` / ``OPENCLAW_CONFIG_PATH``
- point openclaw at the transient workspace, leaving the user's real
- ``~/.openclaw/`` (sessions, channels, plugins) untouched.
-
-OpenClaw's ``openclaw chat`` subcommand (alias for ``openclaw tui
---local``) opens an interactive local terminal UI bound to the embedded
-agent runtime — the right shape for a launcher that wants the user
-dropped into a chat session. ``openclaw agent`` exists too but is a
-non-interactive one-shot turn (verify uses that one). When the user
-exits the chat (or hits Ctrl-C), the proxy thread is torn down and the
-transient workspace is removed.
-"""
+"""Run OpenClaw through an in-process native Switchyard server."""
import json
import logging
@@ -46,91 +9,39 @@ import os
import shutil
import subprocess
import tempfile
-import threading
from collections.abc import Sequence
from pathlib import Path
from typing import Any, TypeAlias
-import uvicorn
-
-from switchyard.cli.launchers.launch_intake_config import (
- LaunchIntakeConfig,
- build_launch_capture_processors,
- print_intake_warning,
-)
from switchyard.cli.launchers.launcher_runtime import (
banner_pause,
configure_debug_file_logging,
- deterministic_strategy_summary,
- find_free_port,
- passthrough_strategy_summary,
print_ready_banner,
print_startup_failure,
- routing_profiles_strategy_summary,
silence_launch_loggers,
- spawn_proxy_thread,
stdin_is_tty,
- suppress_uvicorn_stream_handlers,
wait_for_proxy_ready,
)
from switchyard.cli.launchers.live_stats_footer import LiveStatsFooter
+from switchyard.cli.launchers.native_server import NativeServer
from switchyard.cli.launchers.proxy_health_monitor import ProxyHealthMonitor
-from switchyard.cli.route_bundle import (
- load_route_bundle_table,
-)
-from switchyard.lib.backends.llm_target import BackendFormat, LlmTarget
-from switchyard.lib.processors.model_rewrite_request_processor import (
- ModelRewriteRequestProcessor,
-)
-from switchyard.lib.profiles import (
- DeterministicRoutingConfig,
-)
-from switchyard.lib.route_table import ChainRuntime, SwitchyardApp
-from switchyard.lib.route_table_builders import (
- build_single_model_table,
- build_tier_passthrough_switchyard,
-)
-from switchyard.lib.stats_accumulator import StatsAccumulator
+from switchyard.cli.launchers.session_summary import print_session_summary
from switchyard.server.shell_tui import ShellTUI
logger = logging.getLogger(__name__)
_READY_TIMEOUT_S = 10.0
-_SHUTDOWN_JOIN_S = 3.0
_EXIT_BINARY_NOT_FOUND = 127
_EXIT_SIGINT = 130
-
-# Identifier we register the transient provider under in openclaw.json.
-# OpenClaw references models as ``<provider>/<model>``, so picking
-# ``switchyard`` keeps the user-visible model ids self-explanatory.
_PROVIDER_ID = "switchyard"
-
-# Opaque placeholder substituted into the openclaw.json template's
-# ``apiKey: "${SWITCHYARD_API_KEY}"`` field. The proxy ignores inbound
-# Authorization headers; the real upstream credential is injected by
-# ``OpenAiNativeBackend`` at call time.
_API_KEY_ENV = "SWITCHYARD_API_KEY"
_API_KEY_PLACEHOLDER = "switchyard"
-# (model_id, display_name, description) — feeds the openclaw.json
-# ``models[]`` catalog entries + the per-model ``agents.defaults.models``
-# aliases. Same shape as :data:`CodexModelCatalogEntry`.
OpenClawModelCatalogEntry: TypeAlias = tuple[str, str, str]
-_ModelRewriteRequestProcessor = ModelRewriteRequestProcessor
-_find_free_port = find_free_port
-
-
def _find_openclaw_binary() -> str | None:
- """Locate the ``openclaw`` executable.
-
- Checks ``$PATH`` first, then falls back to the paths npm-installed
- Node binstubs commonly land on: ``~/.npm-global/bin/openclaw``
- (machines that pin npm's global prefix), ``~/.local/bin/openclaw``
- (alternative layouts), and ``~/.nvm/versions/node/*/bin/openclaw``
- (nvm-managed Node installs — the default on this dev box).
- """
+ """Locate the ``openclaw`` executable."""
path_hit = shutil.which("openclaw")
if path_hit:
return path_hit
@@ -154,61 +65,13 @@ def _wait_ready(port: int, timeout_s: float = _READY_TIMEOUT_S) -> bool:
return wait_for_proxy_ready(port, timeout_s=timeout_s)
-def _build_switchyard(
- model: str,
- api_key: str,
- base_url: str,
- timeout: float | None,
- stats: StatsAccumulator,
- extra_request_processors: Sequence[Any] = (),
- extra_response_processors: Sequence[Any] = (),
-) -> ChainRuntime:
- """OpenAI Chat Completions translation chain with live stats.
-
- OpenClaw's ``models.providers.switchyard`` block declares
- ``api: "openai-completions"``, so the inbound request lands on
- Switchyard's ``/v1/chat/completions`` endpoint. We pin
- :class:`BackendFormat.OPENAI` so the chain always translates to
- OpenAI Chat Completions on the way out — same shape Codex uses (no
- Anthropic ``/v1/messages`` probe is meaningful here).
- """
- return build_tier_passthrough_switchyard(
- LlmTarget(
- id="default",
- model=model,
- format=BackendFormat.OPENAI,
- api_key=api_key,
- base_url=base_url,
- timeout_secs=timeout,
- ),
- stats=stats,
- enable_stats=True,
- extra_request_processors=extra_request_processors,
- extra_response_processors=extra_response_processors,
- )
-
-
-def _spawn_proxy_thread(
- switchyard: SwitchyardApp, port: int,
-) -> tuple[uvicorn.Server, threading.Thread]:
- """Run uvicorn in a background daemon thread, return (server, thread)."""
- return spawn_proxy_thread(
- switchyard, port, thread_name="launch-openclaw-proxy",
- )
-
-
def _qualified_model_id(model_id: str) -> str:
- """Return the ``<provider>/<model>`` id OpenClaw uses to reference a model.
-
- OpenClaw expects every model reference to be qualified with the
- provider id (e.g. ``switchyard/openai/gpt-5.2``). Stripping any
- accidental leading slash so callers can pass either form.
- """
+ """Return the provider-qualified model ID used by OpenClaw."""
return f"{_PROVIDER_ID}/{model_id.lstrip('/')}"
def _openclaw_model_display_name(model_id: str) -> str:
- """Pretty-printable short label for a model id (last path segment)."""
+ """Return a short display name for a model ID."""
return model_id.rsplit("/", maxsplit=1)[-1]
@@ -217,66 +80,40 @@ def _build_openclaw_config(
entries: Sequence[OpenClawModelCatalogEntry],
primary_model_id: str,
) -> dict[str, Any]:
- """Build the JSON5-compatible ``openclaw.json`` body.
-
- The schema lives at
- https://docs.openclaw.ai/gateway/config-tools — see the
- ``models.providers.<id>`` table.
-
- ``primary_model_id`` is the qualified ``switchyard/<model>`` id that
- seeds ``agents.defaults.model.primary``. Each entry in *entries*
- becomes both a ``models[]`` catalog row (so OpenClaw knows the
- model's context window) and an ``agents.defaults.models`` alias (so
- the ``/model`` picker shows a friendly display name).
- """
- models_array: list[dict[str, Any]] = []
- agent_models: dict[str, Any] = {}
- for model_id, display_name, _description in entries:
- models_array.append({
+ """Build the transient OpenClaw configuration."""
+ models = [
+ {
"id": model_id,
"name": display_name,
- # OpenClaw accepts modalities as a list; "text" is the
- # universal capability that every Switchyard-routed model
- # honors. Vision / audio aren't declared because the proxy's
- # translation layer doesn't materially differ for them.
"input": ["text"],
"contextWindow": 128000,
"maxTokens": 32000,
- })
- # Qualified id keys (``switchyard/<model>``) — OpenClaw's
- # ``agents.defaults.models`` uses the same form as model
- # references elsewhere in the config.
- agent_models[_qualified_model_id(model_id)] = {
- "alias": display_name,
}
- body: dict[str, Any] = {
+ for model_id, display_name, _description in entries
+ ]
+ aliases = {
+ _qualified_model_id(model_id): {"alias": display_name}
+ for model_id, display_name, _description in entries
+ }
+ return {
"models": {
- # ``merge`` makes the switchyard provider layer on top of
- # any defaults OpenClaw ships internally rather than
- # replacing the whole providers map — future-proofing
- # against an OpenClaw release that bundles a default
- # provider list we don't want to wipe out.
"mode": "merge",
"providers": {
_PROVIDER_ID: {
"baseUrl": f"http://127.0.0.1:{port}/v1",
- # ``${ENV_VAR}`` interpolation is documented for
- # apiKey; we keep the placeholder env-driven so the
- # actual string never lands in the JSON on disk.
"apiKey": "${" + _API_KEY_ENV + "}",
"api": "openai-completions",
- "models": models_array,
- },
+ "models": models,
+ }
},
},
"agents": {
"defaults": {
"model": {"primary": primary_model_id},
- "models": agent_models,
- },
+ "models": aliases,
+ }
},
}
- return body
def _write_openclaw_workspace(
@@ -284,87 +121,38 @@ def _write_openclaw_workspace(
entries: Sequence[OpenClawModelCatalogEntry],
primary_model_id: str,
) -> str:
- """Materialise the transient OpenClaw state dir; return its path.
-
- Caller is responsible for removing the directory via
- :func:`_remove_openclaw_workspace` once the child exits.
- """
+ """Write a transient OpenClaw workspace and return its path."""
workspace = tempfile.mkdtemp(prefix="switchyard-openclaw-")
config_path = Path(workspace) / "openclaw.json"
- body = _build_openclaw_config(
- port=port,
- entries=entries,
- primary_model_id=primary_model_id,
- )
with config_path.open("w", encoding="utf-8") as handle:
- json.dump(body, handle, indent=2, sort_keys=False)
+ json.dump(
+ _build_openclaw_config(port, entries, primary_model_id),
+ handle,
+ indent=2,
+ )
handle.write("\n")
return workspace
def _remove_openclaw_workspace(workspace: str | None) -> None:
- """Best-effort removal of the transient workspace directory."""
- if workspace is None:
- return
- try:
+ """Remove a transient OpenClaw workspace."""
+ if workspace is not None:
shutil.rmtree(workspace, ignore_errors=True)
- except OSError:
- logger.debug(
- "failed to remove temporary OpenClaw workspace %s",
- workspace, exc_info=True,
- )
-def _openclaw_env(
- workspace: str,
- intake: LaunchIntakeConfig | None = None,
-) -> dict[str, str]:
- """Environment that points OpenClaw at the transient workspace.
-
- * ``OPENCLAW_STATE_DIR`` — relocates the openclaw state root to the
- tempdir so user sessions / channels / plugins in ``~/.openclaw/``
- stay untouched for the duration of the launch.
- * ``OPENCLAW_HOME`` — pinned alongside; OpenClaw's
- path-resolution precedence is ``OPENCLAW_HOME`` > ``$HOME``.
- * ``OPENCLAW_CONFIG_PATH`` — explicit pointer at the
- ``openclaw.json`` we wrote, in case OpenClaw doesn't auto-discover
- it from ``OPENCLAW_STATE_DIR`` in the version on the user's box.
- * ``OPENCLAW_HIDE_BANNER`` — Switchyard renders its own ready
- banner; OpenClaw's would double-print.
- * ``SWITCHYARD_API_KEY`` — opaque placeholder substituted into
- ``apiKey: "${SWITCHYARD_API_KEY}"``. The proxy ignores inbound
- Authorization; the real upstream credential is injected by the
- ``OpenAiNativeBackend`` at call time.
- """
+def _openclaw_env(workspace: str) -> dict[str, str]:
+ """Return the environment that selects the transient workspace."""
env = os.environ.copy()
env["OPENCLAW_STATE_DIR"] = workspace
env["OPENCLAW_HOME"] = workspace
env["OPENCLAW_CONFIG_PATH"] = str(Path(workspace) / "openclaw.json")
env["OPENCLAW_HIDE_BANNER"] = "1"
env[_API_KEY_ENV] = _API_KEY_PLACEHOLDER
- if intake is not None:
- env["SWITCHYARD_SESSION_ID"] = intake.session_id
return env
-def _openclaw_command(
- openclaw_bin: str,
- openclaw_args: list[str],
-) -> list[str]:
- """Build the OpenClaw argv: ``openclaw chat <user args>``.
-
- ``openclaw chat`` is OpenClaw's interactive local terminal UI (alias
- for ``openclaw tui --local``). It binds to the embedded agent
- runtime, which is what reads ``models.providers.switchyard`` from
- our transient ``openclaw.json``. ``openclaw agent`` is *not* an
- interactive subcommand — it runs a single non-interactive turn —
- so it's reserved for the one-shot verify path.
-
- Any forwarded args land after ``chat`` so the user can pass
- OpenClaw-native flags (``--message`` for an opening prompt,
- ``--session`` for a non-default session key, ``--thinking``, etc.)
- without colliding with our env-var injection.
- """
+def _openclaw_command(openclaw_bin: str, openclaw_args: list[str]) -> list[str]:
+ """Build the OpenClaw interactive command."""
return [openclaw_bin, "chat", *openclaw_args]
@@ -372,18 +160,12 @@ def _supervise_openclaw(
openclaw_bin: str,
openclaw_args: list[str],
workspace: str,
- intake: LaunchIntakeConfig | None = None,
) -> int:
- """Run ``openclaw chat`` with the transient workspace; return exit code.
-
- ``subprocess.run`` inherits stdin/stdout/stderr so the chat session
- works on a real terminal. ``KeyboardInterrupt`` during the child
- becomes 130 so callers can surface a meaningful exit code.
- """
+ """Run OpenClaw and return its exit code."""
try:
result = subprocess.run(
_openclaw_command(openclaw_bin, openclaw_args),
- env=_openclaw_env(workspace=workspace, intake=intake),
+ env=_openclaw_env(workspace),
check=False,
)
return result.returncode
@@ -391,17 +173,18 @@ def _supervise_openclaw(
return _EXIT_SIGINT
+def _start_native_server(config: Path) -> NativeServer:
+ """Start the native server; kept separate for supervision tests."""
+ return NativeServer(config)
+
+
def _run_openclaw_with_switchyard(
- switchyard: SwitchyardApp,
+ config: Path,
display_model: str,
- port: int | None,
openclaw_args: list[str],
- stats: StatsAccumulator,
catalog_entries: Sequence[OpenClawModelCatalogEntry],
- intake: LaunchIntakeConfig | None = None,
- strategy_summary: str | None = None,
) -> int:
- """Chain-agnostic supervisor: host ``switchyard`` then spawn openclaw."""
+ """Host a native deployment and run OpenClaw against it."""
openclaw_bin = _find_openclaw_binary()
if openclaw_bin is None:
logger.error(
@@ -412,18 +195,18 @@ def _run_openclaw_with_switchyard(
silence_launch_loggers(local_logger=logger)
log_path = configure_debug_file_logging(display_model=display_model)
- resolved_port = port if port is not None else _find_free_port()
- primary_model_id = _qualified_model_id(display_model)
- workspace = _write_openclaw_workspace(
- port=resolved_port,
- entries=catalog_entries,
- primary_model_id=primary_model_id,
- )
- server: uvicorn.Server | None = None
- thread: threading.Thread | None = None
+ server = _start_native_server(config)
+ resolved_port = server.port
+ stats = server.stats
+ workspace: str | None = None
+ strategy_summary = f"config → {config.name}"
try:
- server, thread = _spawn_proxy_thread(switchyard, resolved_port)
+ workspace = _write_openclaw_workspace(
+ port=resolved_port,
+ entries=catalog_entries,
+ primary_model_id=_qualified_model_id(display_model),
+ )
if not _wait_ready(resolved_port):
print_startup_failure(
port=resolved_port,
@@ -432,19 +215,14 @@ def _run_openclaw_with_switchyard(
)
return 1
- suppress_uvicorn_stream_handlers()
logger.info("proxy ready on port %d", resolved_port)
- if intake is not None:
- print_intake_warning()
- from switchyard.lib.route_table import RouteTable
- table = switchyard if isinstance(switchyard, RouteTable) else None
print_ready_banner(
port=resolved_port,
display_model=display_model,
log_path=log_path,
strategy_summary=strategy_summary,
- profile_routes=table.registered_models() if table is not None else None,
- default_route=table.default_model() if table is not None else None,
+ profile_routes=[display_model],
+ default_route=display_model,
)
if stdin_is_tty():
banner_pause()
@@ -454,249 +232,38 @@ def _run_openclaw_with_switchyard(
stats,
display_model,
ProxyHealthMonitor(resolved_port),
- table=table,
- strategy_label=strategy_summary.split(":")[0].strip() if strategy_summary else None,
+ strategy_label="config",
)
return ShellTUI(
command=_openclaw_command(openclaw_bin, openclaw_args),
footer_fn=footer.as_footer_fn(),
footer_height=lambda: footer.height,
- env=_openclaw_env(workspace=workspace, intake=intake),
+ env=_openclaw_env(workspace),
).run()
- return _supervise_openclaw(
- openclaw_bin, openclaw_args,
- workspace=workspace, intake=intake,
- )
+ return _supervise_openclaw(openclaw_bin, openclaw_args, workspace)
finally:
- if server is not None:
- server.should_exit = True
- if thread is not None:
- thread.join(timeout=_SHUTDOWN_JOIN_S)
+ print_session_summary(stats)
+ server.close()
_remove_openclaw_workspace(workspace)
-def _openclaw_catalog_entry_for_registered_model(
- model_id: str,
- primary_model_id: str,
-) -> OpenClawModelCatalogEntry:
- """Build an OpenClaw catalog entry for a YAML-registered model id."""
- display = _openclaw_model_display_name(model_id)
- if model_id == primary_model_id:
- return (
- model_id,
- f"{display} (Switchyard)",
- f"Routed through Switchyard to {model_id}.",
- )
- return (
- model_id,
- f"{display} (Switchyard)",
- f"Routed through Switchyard to {model_id}.",
- )
-
-
-def launch_openclaw(
+def launch_openclaw_config(
+ config: Path,
model: str,
- base_url: str,
- api_key: str,
- port: int | None,
- timeout: float | None,
openclaw_args: list[str],
- intake: LaunchIntakeConfig | None = None,
- routing_profiles: str | None = None,
- rl_log_dir: Path | None = None,
) -> int:
- """Start a passthrough proxy and run ``openclaw chat`` against it.
-
- Single-model UX — ``model`` seeds the OpenClaw session, while the
- proxy preserves any model OpenClaw sends later so a client-side
- ``/model`` selection remains effective.
-
- When ``routing_profiles`` is given, the launcher builds a
- :class:`RouteTable` instead of a single chain: ``model`` is
- registered as a tier passthrough, then every entry from the YAML
- file is merged on top (including each tier's ``GET /v1/models``
- catalog hydration). OpenClaw's ``/model`` picker is populated from
- the merged table via ``agents.defaults.models``, so YAML-declared
- models appear alongside the launcher-configured one.
-
- Returns the ``openclaw`` process's exit code (or ``127`` if the
- binary wasn't found, ``130`` on Ctrl-C).
- """
- stats = StatsAccumulator()
- intake_request, intake_response = build_launch_capture_processors(intake, rl_log_dir)
- switchyard = _build_switchyard(
- model,
- api_key,
- base_url,
- timeout,
- stats,
- extra_request_processors=intake_request,
- extra_response_processors=intake_response,
- )
- catalog_entries: list[OpenClawModelCatalogEntry] = [
+ """Run OpenClaw against a native server TOML deployment."""
+ catalog = [
(
model,
f"{_openclaw_model_display_name(model)} (Switchyard)",
- f"Routed through Switchyard to {model}.",
- ),
- ]
- app: SwitchyardApp = build_single_model_table(model, switchyard)
- if routing_profiles is not None:
- # Wrap the single chain in a RouteTable so YAML routes
- # can merge on top. The launcher's `model` registers as a tier
- # passthrough; YAML entries land alongside (override on id
- # conflict). OpenClaw's /model picker iterates the catalog, so
- # YAML-declared models surface there automatically.
- from switchyard.lib.route_table import RouteTable
- table = app
- assert isinstance(table, RouteTable)
- yaml_table = load_route_bundle_table(
- routing_profiles,
- stats_accumulator=stats,
- pre_routing_request_processors=intake_request,
- extra_response_processors=intake_response,
- )
- for sub_model, sub_chain, sub_metadata in yaml_table.items():
- table.register(sub_model, sub_chain, metadata=sub_metadata)
- for warning in yaml_table.model_listing_warnings():
- table.add_model_listing_warning(warning)
- app = table
- catalog_seen = {entry[0] for entry in catalog_entries}
- for model_id in table.registered_models():
- if model_id in catalog_seen:
- continue
- catalog_entries.append(_openclaw_catalog_entry_for_registered_model(
- model_id=model_id,
- primary_model_id=model,
- ))
- catalog_seen.add(model_id)
- strategy_summary = (
- routing_profiles_strategy_summary(routing_profiles, model)
- if routing_profiles is not None
- else passthrough_strategy_summary(model)
- )
- return _run_openclaw_with_switchyard(
- app,
- display_model=model,
- port=port,
- openclaw_args=openclaw_args,
- stats=stats,
- catalog_entries=catalog_entries,
- intake=intake,
- strategy_summary=strategy_summary,
- )
-
-
-def _openclaw_catalog_entry_for_deterministic_model(
- model_id: str,
- config: DeterministicRoutingConfig,
-) -> OpenClawModelCatalogEntry:
- """Build an OpenClaw catalog entry tailored to a deterministic config."""
- from switchyard.lib.route_table_builders import (
- deterministic_routing_virtual_model_id,
- )
-
- routing_model = deterministic_routing_virtual_model_id(config)
- display = _openclaw_model_display_name(model_id)
- if model_id == routing_model:
- return (
- model_id,
- "Switchyard deterministic routing",
- (
- "LLM-classifier routes between "
- f"{config.strong.model} (strong) and {config.weak.model} (weak) "
- f"using {config.classifier.model} (classifier, "
- f"profile={config.profile_name})."
- ),
- )
- if model_id == config.strong.model:
- return (
- model_id,
- f"{display} (Switchyard strong)",
- f"Direct Switchyard route to {model_id}.",
- )
- if model_id == config.weak.model:
- return (
- model_id,
- f"{display} (Switchyard weak)",
- f"Direct Switchyard route to {model_id}.",
+ f"Route from {config.name}.",
)
- return (
- model_id,
- f"{display} (Switchyard)",
- f"Direct Switchyard passthrough to discovered model {model_id}.",
- )
-
-
-def launch_openclaw_deterministic_routing(
- config: DeterministicRoutingConfig,
- port: int | None,
- openclaw_args: list[str],
- intake: LaunchIntakeConfig | None = None,
- discovery_disabled: bool = False,
- rl_log_dir: Path | None = None,
-) -> int:
- """Start a deterministic-routing proxy and run ``openclaw`` against it."""
- from switchyard.cli.model_catalog.model_discovery import fetch_model_ids
- from switchyard.lib.route_table_builders import (
- build_deterministic_routing_switchyard,
- build_deterministic_routing_table,
- deterministic_routing_virtual_model_id,
- )
-
- def _discovery_fn(base_url: str, api_key: str) -> list[str]:
- return fetch_model_ids(base_url, api_key)
-
- stats = StatsAccumulator()
- intake_request, intake_response = build_launch_capture_processors(intake, rl_log_dir)
- switchyard = build_deterministic_routing_switchyard(
- config,
- stats,
- pre_routing_request_processors=intake_request,
- extra_response_processors=intake_response,
- )
- routing_model = deterministic_routing_virtual_model_id(config)
- discovery_fn = None if discovery_disabled else _discovery_fn
- model_table = build_deterministic_routing_table(
- config,
- stats,
- deterministic_routing_switchyard=switchyard,
- routing_model=routing_model,
- discovery_fn=discovery_fn,
- pre_routing_request_processors=intake_request,
- extra_response_processors=intake_response,
- )
- catalog_entries: list[OpenClawModelCatalogEntry] = [
- _openclaw_catalog_entry_for_deterministic_model(
- model_id=routing_model,
- config=config,
- ),
- _openclaw_catalog_entry_for_deterministic_model(
- model_id=config.strong.model,
- config=config,
- ),
]
- catalog_seen = {entry[0] for entry in catalog_entries}
- for model_id in model_table.registered_models():
- if model_id in catalog_seen:
- continue
- catalog_entries.append(_openclaw_catalog_entry_for_deterministic_model(
- model_id=model_id,
- config=config,
- ))
- catalog_seen.add(model_id)
- # OpenClaw's primary model needs to be the virtual routing id so a
- # /model selection of "strong" or "weak" rolls back to the
- # classifier-driven pick. The catalog still exposes the tier models
- # for manual overrides, mirroring the codex deterministic UX.
return _run_openclaw_with_switchyard(
- model_table,
- display_model=routing_model,
- port=port,
+ config,
+ display_model=model,
openclaw_args=openclaw_args,
- stats=stats,
- catalog_entries=catalog_entries,
- intake=intake,
- strategy_summary=deterministic_strategy_summary(config),
+ catalog_entries=catalog,
)
diff --git a/switchyard/cli/launchers/session_summary.py b/switchyard/cli/launchers/session_summary.py
index a772df888..e676782a1 100644
--- a/switchyard/cli/launchers/session_summary.py
+++ b/switchyard/cli/launchers/session_summary.py
@@ -10,14 +10,14 @@ import logging
from collections.abc import Mapping
from typing import cast
+from switchyard.cli.launchers.stats_source import StatsSource
from switchyard.lib.cost_estimator import estimate_model_cost
-from switchyard.lib.stats_accumulator import StatsAccumulator
_RULE = "─" * 51
_LOG = logging.getLogger(__name__)
-def print_session_summary(stats: StatsAccumulator) -> None:
+def print_session_summary(stats: StatsSource) -> None:
"""Print a session summary to stdout after the launcher exits."""
try:
snapshot = stats.snapshot_sync()
diff --git a/switchyard/cli/launchers/stats_source.py b/switchyard/cli/launchers/stats_source.py
new file mode 100644
index 000000000..b2bcbbdc3
--- /dev/null
+++ b/switchyard/cli/launchers/stats_source.py
@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Stats snapshot interface shared by launcher presentation code."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Protocol
+
+
+class StatsSource(Protocol):
+ """Provides the current launcher-session statistics."""
+
+ def snapshot_sync(self) -> Mapping[str, object]:
+ """Return the latest statistics snapshot."""
+ ...
+
+
+__all__ = ["StatsSource"]
diff --git a/switchyard/cli/model_catalog/model_discovery.py b/switchyard/cli/model_catalog/model_discovery.py
index cdd9b377d..24f29593d 100644
--- a/switchyard/cli/model_catalog/model_discovery.py
+++ b/switchyard/cli/model_catalog/model_discovery.py
@@ -1,21 +1,13 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Model discovery and default model selection for launcher configuration."""
-
-from typing import Literal
+"""OpenAI-compatible model discovery for YAML route bundles."""
import httpx
class ModelDiscoveryError(RuntimeError):
- """Raised when the upstream model catalog cannot be fetched."""
-
-
-def _models_url(base_url: str) -> str:
- """Input: a provider base URL. Output: the normalized ``/models`` URL."""
-
- return f"{base_url.rstrip('/')}/models"
+ """Raised when an upstream model catalog cannot be fetched."""
def fetch_model_ids(
@@ -23,30 +15,20 @@ def fetch_model_ids(
api_key: str,
timeout_s: float = 10.0,
) -> list[str]:
- """Input: endpoint credentials. Output: sorted unique model IDs.
-
- Accepts OpenAI-compatible ``GET /models`` responses where the body is
- either a list or a dict with ``data``. Rows may be raw strings or dicts
- carrying an ``id``, ``model``, or ``name`` string. Fetch/shape failures
- raise ``ModelDiscoveryError`` so command callers can decide whether to
- fail, warn, or fall back to manual model entry.
- """
+ """Return sorted model IDs from an OpenAI-compatible ``GET /models``."""
- headers = {"Authorization": f"Bearer {api_key}"}
try:
with httpx.Client(timeout=timeout_s) as client:
- response = client.get(_models_url(base_url), headers=headers)
+ response = client.get(
+ f"{base_url.rstrip('/')}/models",
+ headers={"Authorization": f"Bearer {api_key}"},
+ )
response.raise_for_status()
body = response.json()
except (httpx.HTTPError, ValueError) as exc:
raise ModelDiscoveryError(str(exc)) from exc
- raw_items: object
- if isinstance(body, dict):
- raw_items = body.get("data", [])
- else:
- raw_items = body
-
+ raw_items = body.get("data", []) if isinstance(body, dict) else body
if not isinstance(raw_items, list):
raise ModelDiscoveryError("GET /models response did not contain a model list")
@@ -62,172 +44,7 @@ def fetch_model_ids(
if isinstance(value, str) and value:
model_ids.append(value)
break
-
return sorted(set(model_ids))
-def _ranked_model_candidates(
- model_ids: list[str],
- target: Literal["claude", "codex"],
-) -> list[str]:
- """Input: discovered model IDs. Output: target candidates, best first.
-
- Model IDs are normalized into lowercase separator-delimited segments without
- regex. This keeps ``gpt`` distinct from ``egpt`` while still understanding
- provider paths and versions such as ``gpt-5.10`` or
- ``claude-sonnet-4-5@20251001``.
-
- Ranking policy:
- - Skip tool-only/non-chat model families such as embeddings and audio.
- - Prefer stable IDs over previews, nightlies, and other prereleases.
- - Claude defaults rank family first (Opus > Sonnet > Haiku), then version.
- - Codex defaults rank exact ``gpt`` models by version, then Codex/size tiers.
- - Snapshot dates are ignored as versions, so pinned dates do not outrank a
- newer actual model release.
- """
-
- separators = str.maketrans(dict.fromkeys("-_./:@", " "))
- denied_segments = {
- "audio",
- "classifier",
- "embedding",
- "embeddings",
- "embed",
- "guardrail",
- "image",
- "images",
- "moderation",
- "realtime",
- "rerank",
- "reranker",
- "stt",
- "test",
- "transcribe",
- "transcription",
- "tts",
- }
- unstable_segments = {
- "alpha",
- "beta",
- "dev",
- "experimental",
- "nightly",
- "preview",
- }
- claude_family_rank = {"opus": 3, "sonnet": 2, "haiku": 1}
- gpt_size_rank = {"max": 4, "pro": 4, "mini": 1, "nano": 0}
-
- scored: list[tuple[tuple[int, ...], str]] = []
- for model_id in model_ids:
- segments = tuple(model_id.strip().lower().translate(separators).split())
- segment_set = set(segments)
- if denied_segments & segment_set:
- continue
-
- stable_rank = int(not (unstable_segments & segment_set))
- alias_rank = int("latest" not in segment_set)
-
- if target == "claude":
- if "claude" not in segment_set:
- continue
-
- family_index = next(
- (
- index
- for index, segment in enumerate(segments)
- if segment in claude_family_rank
- ),
- None,
- )
- family = segments[family_index] if family_index is not None else ""
- family_rank = claude_family_rank.get(family, 0)
-
- claude_index = segments.index("claude")
- version_starts = (
- [family_index + 1, claude_index + 1]
- if family_index is not None
- else [claude_index + 1]
- )
- provider_rank = int("anthropic" in segment_set) + int("azure" in segment_set)
- else:
- if "gpt" not in segment_set:
- continue
-
- version_starts = [segments.index("gpt") + 1]
- size_rank = 3
- for size_segment, rank in gpt_size_rank.items():
- if size_segment in segment_set:
- size_rank = rank
- break
- provider_rank = int("openai" in segment_set) + int("azure" in segment_set)
-
- version: list[int] = []
- for version_start in version_starts:
- version = []
- for segment in segments[version_start:]:
- if segment.isdigit():
- if len(segment) == 8 or len(segment) > 3:
- break
- version.append(int(segment))
- elif segment.endswith("o") and segment[:-1].isdigit():
- version.append(int(segment[:-1]))
- else:
- break
- if len(version) == 3:
- break
- if version:
- break
- version += [0] * (3 - len(version))
-
- rank_key: tuple[int, ...]
- if target == "claude":
- rank_key = (
- stable_rank,
- family_rank,
- version[0],
- version[1],
- version[2],
- provider_rank,
- alias_rank,
- )
- else:
- rank_key = (
- stable_rank,
- version[0],
- version[1],
- version[2],
- int("codex" in segment_set),
- size_rank,
- provider_rank,
- alias_rank,
- )
- scored.append((rank_key, model_id))
-
- scored.sort(key=lambda item: tuple(-part for part in item[0]) + (item[1],))
- return [model_id for _, model_id in scored]
-
-
-def choose_default_claude_model(model_ids: list[str]) -> str | None:
- """Input: discovered model IDs. Output: best Claude default or ``None``."""
-
- candidates = claude_model_candidates(model_ids)
- return candidates[0] if candidates else None
-
-
-def choose_default_codex_model(model_ids: list[str]) -> str | None:
- """Input: discovered model IDs. Output: best GPT/Codex default or ``None``."""
-
- candidates = codex_model_candidates(model_ids)
- return candidates[0] if candidates else None
-
-
-def claude_model_candidates(model_ids: list[str]) -> list[str]:
- """Input: discovered model IDs. Output: Claude candidates, best first."""
-
- return _ranked_model_candidates(model_ids, "claude")
-
-
-def codex_model_candidates(model_ids: list[str]) -> list[str]:
- """Input: discovered model IDs. Output: GPT candidates, best first."""
-
- return _ranked_model_candidates(model_ids, "codex")
+__all__ = ["ModelDiscoveryError", "fetch_model_ids"]
diff --git a/switchyard/cli/models.py b/switchyard/cli/models.py
deleted file mode 100644
index 2dbc067aa..000000000
--- a/switchyard/cli/models.py
+++ /dev/null
@@ -1,79 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Model catalog listing helpers for the CLI."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Literal
-
-from switchyard.cli.model_catalog.model_discovery import (
- claude_model_candidates,
- codex_model_candidates,
-)
-
-ModelListTarget = Literal["all", "claude", "codex"]
-
-
-@dataclass(frozen=True)
-class ModelListRequest:
- """Inputs for rendering ``switchyard models``."""
-
- target: ModelListTarget = "all"
- query: str | None = None
- limit: int = 50
-
-
-def _dedupe(values: list[str]) -> list[str]:
- output: list[str] = []
- seen: set[str] = set()
- for value in values:
- if value in seen:
- continue
- output.append(value)
- seen.add(value)
- return output
-
-
-def _rank_models(model_ids: list[str], target: ModelListTarget) -> list[str]:
- if target == "claude":
- return _dedupe([*claude_model_candidates(model_ids), *model_ids])
- if target == "codex":
- return _dedupe([*codex_model_candidates(model_ids), *model_ids])
- return sorted(model_ids)
-
-
-def filter_and_rank_models(
- model_ids: list[str],
- request: ModelListRequest,
-) -> list[str]:
- ranked = _rank_models(model_ids, request.target)
- if request.query:
- needle = request.query.lower()
- ranked = [model_id for model_id in ranked if needle in model_id.lower()]
- if request.limit > 0:
- return ranked[: request.limit]
- return ranked
-
-
-def render_models(model_ids: list[str], request: ModelListRequest) -> str:
- """Render a model list with target-aware ranking."""
-
- visible = filter_and_rank_models(model_ids, request)
- lines = [
- f"Models ({request.target})",
- f"showing: {len(visible)} of {len(model_ids)}",
- ]
- if request.query:
- lines.append(f"query: {request.query}")
- lines.append("")
- lines.extend(visible or ["<none>"])
- return "\n".join(lines)
-
-
-__all__ = [
- "ModelListRequest",
- "filter_and_rank_models",
- "render_models",
-]
diff --git a/switchyard/cli/output.py b/switchyard/cli/output.py
deleted file mode 100644
index 887e96c54..000000000
--- a/switchyard/cli/output.py
+++ /dev/null
@@ -1,199 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Human-readable CLI output helpers."""
-
-from collections.abc import Mapping
-from typing import cast
-
-from switchyard.cli.config.user_config import (
- PRIMARY_TIER,
- WEAK_TIER,
- LaunchRouteConfig,
-)
-
-
-def _mapping(value: object) -> Mapping[str, object]:
- if isinstance(value, dict):
- return cast(Mapping[str, object], value)
- return {}
-
-
-def _string(value: object) -> str | None:
- return value if isinstance(value, str) else None
-
-
-_TIERED_ROUTE_TYPES = frozenset({"random", "deterministic"})
-
-
-def _format_route(route: Mapping[str, object]) -> list[str]:
- route_type = _string(route.get("type")) or "single"
- lines = [f"route: {route_type}"]
- model = _string(route.get("model"))
- if model:
- lines.append(f"model: {model}")
- weak_model = _string(route.get("weak_model"))
- if route_type in _TIERED_ROUTE_TYPES and weak_model:
- lines.append(f"weak model: {weak_model}")
- probability = route.get("strong_probability")
- if route_type == "random" and isinstance(probability, (int, float)):
- lines.append(f"strong probability: {float(probability):.2f}")
- endpoints = _mapping(route.get("endpoints"))
- primary_endpoint = _mapping(endpoints.get(PRIMARY_TIER))
- primary_base_url = _string(primary_endpoint.get("base_url"))
- if primary_base_url:
- lines.append(f"base URL override: {primary_base_url}")
- primary_api_key = _string(primary_endpoint.get("api_key"))
- if primary_api_key:
- lines.append(f"API key override: {primary_api_key}")
- weak_endpoint = _mapping(endpoints.get(WEAK_TIER))
- weak_base_url = _string(weak_endpoint.get("base_url"))
- if route_type in _TIERED_ROUTE_TYPES and weak_base_url:
- lines.append(f"weak base URL override: {weak_base_url}")
- weak_api_key = _string(weak_endpoint.get("api_key"))
- if route_type in _TIERED_ROUTE_TYPES and weak_api_key:
- lines.append(f"weak API key override: {weak_api_key}")
- return lines
-
-
-def format_route_config(route: LaunchRouteConfig) -> list[str]:
- body: dict[str, object] = {"type": route.type}
- if route.model:
- body["model"] = route.model
- if route.weak_model:
- body["weak_model"] = route.weak_model
- if route.type == "random":
- body["strong_probability"] = route.strong_probability
- endpoints: dict[str, object] = {}
- for tier, endpoint in (route.endpoints or {}).items():
- endpoint_body: dict[str, object] = {}
- if endpoint.base_url:
- endpoint_body["base_url"] = endpoint.base_url
- if endpoint_body:
- endpoints[tier] = endpoint_body
- if endpoints:
- body["endpoints"] = endpoints
- return _format_route(body)
-
-
-def format_config_snapshot(snapshot: Mapping[str, object]) -> str:
- """Render ``build_redacted_snapshot`` output for humans."""
-
- lines = [
- "Switchyard config",
- f"config: {snapshot.get('config_path')}",
- f"credentials: {snapshot.get('credentials_path')}",
- f"default provider: {snapshot.get('default_provider')}",
- ]
-
- providers = _mapping(snapshot.get("providers"))
- if providers:
- lines.append("")
- lines.append("Providers")
- for name, raw_provider in providers.items():
- provider = _mapping(raw_provider)
- lines.append(f" {name}")
- base_url = _string(provider.get("base_url"))
- if base_url:
- lines.append(f" base URL: {base_url}")
- api_key = _string(provider.get("api_key"))
- lines.append(f" API key: {api_key or '<missing>'}")
-
- saved_bundle = snapshot.get("routing_profiles")
- if isinstance(saved_bundle, dict):
- route_ids = saved_bundle.get("route_ids")
- if isinstance(route_ids, list) and route_ids:
- lines.append("")
- lines.append("Routing profiles (saved bundle)")
- for route_id in route_ids:
- lines.append(f" {route_id}")
-
- skill_distillation = _mapping(snapshot.get("skill_distillation"))
- if skill_distillation:
- lines.append("")
- lines.append("Skill distillation")
- namespace = _string(skill_distillation.get("namespace"))
- lines.append(f" configured: {bool(namespace)}")
- lines.append(f" namespace: {namespace or '<not configured>'}")
- if namespace:
- lines.append(" session learning: namespace saved")
-
- launch = _mapping(snapshot.get("launch"))
- if launch:
- lines.append("")
- lines.append("Launch defaults")
- for target, raw_launch in launch.items():
- target_config = _mapping(raw_launch)
- route = _mapping(target_config.get("route"))
- lines.append(f" {target}")
- for route_line in _format_route(route):
- lines.append(f" {route_line}")
- return "\n".join(lines)
-
-
-def format_dry_run(
- *,
- target: str,
- route: LaunchRouteConfig,
- base_url: str,
- api_key_set: bool,
- port: int | None,
- timeout: float | None,
- forwarded_args: list[str],
- classifier_model: str | None = None,
- profile: str | None = None,
- classifier_min_confidence: float | None = None,
- routing_profiles: str | None = None,
-) -> str:
- """Render resolved launch settings without exposing secrets.
-
- The optional ``classifier_*`` / ``profile`` kwargs are populated by the
- deterministic-routing dispatch path — the routing-policy fields that
- aren't carried on :class:`LaunchRouteConfig`.
-
- ``routing_profiles`` is the resolved routing-profiles YAML path for a
- multi-chain bundle launch. When set, the summary reports ``route: bundle``
- plus the bundle path and its route ids instead of the single-tier
- :func:`format_route_config` view (``route`` is a placeholder single-tier
- config in that case).
- """
-
- lines = [
- f"Switchyard launch dry run: {target}",
- f"base URL: {base_url}",
- f"API key: {'set' if api_key_set else '<missing>'}",
- f"port: {port if port is not None else 'auto'}",
- f"timeout: {timeout if timeout is not None else 'default'}",
- ]
- if routing_profiles:
- from switchyard.cli.route_bundle import (
- parse_routing_profiles_file,
- routing_profile_model_ids,
- )
-
- lines.append("route: bundle")
- lines.append(f"routing profiles: {routing_profiles}")
- for route_id in routing_profile_model_ids(
- parse_routing_profiles_file(routing_profiles)
- ):
- lines.append(f" {route_id}")
- else:
- for route_line in format_route_config(route):
- lines.append(route_line)
- if route.type == "deterministic":
- if classifier_model:
- lines.append(f"classifier model: {classifier_model}")
- if profile:
- lines.append(f"profile: {profile}")
- if classifier_min_confidence is not None:
- lines.append(f"min confidence: {classifier_min_confidence:.2f}")
- if forwarded_args:
- lines.append(f"forwarded args: {' '.join(forwarded_args)}")
- return "\n".join(lines)
-
-
-__all__ = [
- "format_config_snapshot",
- "format_dry_run",
- "format_route_config",
-]
diff --git a/switchyard/cli/route_bundle.py b/switchyard/cli/route_bundle.py
index 9e9b454af..70d7c1e85 100644
--- a/switchyard/cli/route_bundle.py
+++ b/switchyard/cli/route_bundle.py
@@ -18,8 +18,6 @@ The flow is::
▼ build_table_from_bundle
RouteTable
-Launchers skip the parser and construct a :class:`RouteBundle` directly so
-argparse-driven and YAML-driven assembly share one builder.
"""
import os
@@ -310,14 +308,6 @@ class _YamlModule(Protocol):
def safe_load(self, stream: str) -> object: ...
-#: Tier fields drilled into by :func:`routing_profile_model_ids`. The
-#: ``classifier`` tier is intentionally NOT surfaced — it is an internal-only
-#: LLM call, not a user-facing target.
-_USER_FACING_TIER_FIELDS: tuple[str, ...] = (
- "strong", "weak", "target",
-)
-
-
def parse_routing_profiles_file(path: str | Path) -> dict[str, object]:
"""Read *path* and return the parsed YAML dict (no env-var expansion)."""
yaml = cast(_YamlModule, import_module("yaml"))
@@ -342,47 +332,6 @@ def _format_exception_one_line(exc: BaseException) -> str:
return " ".join(str(exc).split())
-def routing_profile_model_ids(
- routing_profiles: Mapping[str, object] | None,
-) -> list[str]:
- """User-callable model ids from a parsed routing-profiles bundle.
-
- Returns each route's YAML key followed by its tier ``model`` fields
- (``strong`` / ``weak`` for stage_router/deterministic/random_routing,
- ``target`` for ``model``). Declaration order, later
- duplicates dropped.
- Returns ``[]`` for a ``None`` or empty bundle.
-
- Used by both the configure wizard (preview the picker) and the launchers
- (validate ``--model`` against the YAML without paying the cost of a full
- table build + catalog discovery).
- """
- if not routing_profiles:
- return []
- routes = routing_profiles.get("routes")
- if not isinstance(routes, Mapping):
- return []
- seen: set[str] = set()
- ordered: list[str] = []
-
- def _add(value: object) -> None:
- if isinstance(value, str) and value and value not in seen:
- seen.add(value)
- ordered.append(value)
-
- for route_id, route in routes.items():
- _add(route_id)
- if not isinstance(route, Mapping):
- continue
- for tier_field in _USER_FACING_TIER_FIELDS:
- tier = route.get(tier_field)
- if isinstance(tier, Mapping):
- _add(tier.get("model"))
- elif isinstance(tier, str):
- _add(tier)
- return ordered
-
-
def load_route_bundle_table(
path: str | Path,
stats_accumulator: StatsAccumulator | None = None,
@@ -391,8 +340,8 @@ def load_route_bundle_table(
) -> RouteTable:
"""Load *path* and return a table keyed by route model id.
- Pass ``stats_accumulator`` when a caller (typically a launcher) is merging
- this YAML table on top of one it already built, so YAML-declared chains
+ Pass ``stats_accumulator`` when a caller is merging this YAML table into
+ an existing runtime so YAML-declared chains
record into the same accumulator surfaced at ``/v1/routing/stats`` and the
live stats footer. ``None`` (default) creates a fresh accumulator — what
standalone ``switchyard serve`` callers want.
@@ -1421,5 +1370,4 @@ __all__ = [
"build_route_bundle_table",
"load_route_bundle_table",
"parse_routing_profiles_file",
- "routing_profile_model_ids",
]
diff --git a/switchyard/cli/routing/__init__.py b/switchyard/cli/routing/__init__.py
deleted file mode 100644
index 9e6ed4c86..000000000
--- a/switchyard/cli/routing/__init__.py
+++ /dev/null
@@ -1,18 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""CLI route helpers for launcher defaults."""
-
-from switchyard.cli.routing.route_builder import (
- LaunchTierConnectivity,
- build_deterministic_routing_config,
- build_random_routing_config,
- require_route_model,
-)
-
-__all__ = [
- "LaunchTierConnectivity",
- "build_deterministic_routing_config",
- "build_random_routing_config",
- "require_route_model",
-]
diff --git a/switchyard/cli/routing/route_builder.py b/switchyard/cli/routing/route_builder.py
deleted file mode 100644
index 114d6a84b..000000000
--- a/switchyard/cli/routing/route_builder.py
+++ /dev/null
@@ -1,210 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Build routing configs from persisted launcher routes."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import cast
-
-from switchyard.cli.config.user_config import LaunchRouteConfig
-from switchyard.lib.backends.llm_target import BackendFormat, LlmTarget
-from switchyard.lib.profiles import (
- DeterministicRoutingConfig,
- DeterministicRoutingPresets,
-)
-from switchyard.lib.profiles.deterministic_routing_config import ProfileName
-from switchyard.lib.profiles.random_routing import (
- RandomRoutingConfig,
-)
-
-_SUPPORTED_PROFILES: tuple[str, ...] = ("general", "coding_agent", "openclaw")
-
-
-@dataclass(frozen=True)
-class LaunchTierConnectivity:
- """Resolved endpoint credentials for one launch route tier."""
-
- api_key: str | None
- base_url: str
-
-
-def require_route_model(route: LaunchRouteConfig, *, target: str) -> str:
- """Return the primary model or fail with a launch-specific message."""
-
- if route.model:
- return route.model
- raise SystemExit(
- f"launch {target}: requires a configured model. Run "
- f"`switchyard configure --target {target}` or pass --model."
- )
-
-
-def build_random_routing_config(
- route: LaunchRouteConfig,
- *,
- primary: LaunchTierConnectivity,
- weak: LaunchTierConnectivity,
- timeout: float | None,
-) -> RandomRoutingConfig:
- """Build the first-pass random route: primary model vs weaker model."""
-
- if not route.model:
- raise SystemExit("random routing requires a primary model.")
- if not route.weak_model:
- raise SystemExit(
- "random routing requires a weak model. Pass --weak-model or "
- "reconfigure this launcher."
- )
-
- return RandomRoutingConfig(
- strong=LlmTarget(
- id="strong",
- model=route.model,
- format=BackendFormat.AUTO,
- api_key=primary.api_key,
- base_url=primary.base_url,
- timeout_secs=timeout,
- ),
- weak=LlmTarget(
- id="weak",
- model=route.weak_model,
- format=BackendFormat.AUTO,
- api_key=weak.api_key,
- base_url=weak.base_url,
- timeout_secs=timeout,
- ),
- strong_probability=route.strong_probability,
- fallback_target_on_evict="strong",
- )
-
-
-def build_deterministic_routing_config(
- route: LaunchRouteConfig,
- *,
- primary: LaunchTierConnectivity,
- weak: LaunchTierConnectivity,
- classifier_model: str | None,
- profile_name: str | None,
- classifier_min_confidence: float | None,
- backend_format: BackendFormat,
- timeout: float | None,
- strong_backend_format: BackendFormat | None = None,
-) -> DeterministicRoutingConfig:
- """Layer LLM-as-classifier CLI overrides on top of the shipping preset.
-
- The shipping preset (``DeterministicRoutingPresets.coding_agent_default``)
- is the validated TB-Lite trio. We start from it and override only the
- fields the user explicitly supplied so ``switchyard launch claude``
- works with zero flags, while ``--model`` / ``--weak-model`` /
- ``--classifier-model`` / ``--profile`` / ``--classifier-min-confidence``
- each replace one piece.
-
- Args:
- route: Resolved :class:`LaunchRouteConfig`. ``route.model`` and
- ``route.weak_model`` carry the user's explicit overrides
- (``None`` when not supplied — the preset wins).
- primary: Connectivity for the strong tier (also reused for the
- classifier endpoint since the validated trio runs all three
- against the same gateway.
- weak: Connectivity for the weak tier.
- classifier_model: User override for the classifier LLM model id.
- profile_name: User override for the classifier profile (``general``
- / ``coding_agent`` / ``openclaw``).
- classifier_min_confidence: User override for the tier selector's
- confidence floor.
- backend_format: Wire format for the weak + classifier tiers (and the
- strong tier when ``strong_backend_format`` is ``None``).
- strong_backend_format: Strong-tier wire format override; ``AUTO``
- probes the backend for Anthropic Messages support at runtime.
- timeout: Per-request HTTP timeout for the tier backends
- (seconds).
- """
- if profile_name is not None and profile_name not in _SUPPORTED_PROFILES:
- raise SystemExit(
- f"deterministic routing: unknown profile {profile_name!r}; "
- f"choose one of {list(_SUPPORTED_PROFILES)}."
- )
- if classifier_min_confidence is not None and not (
- 0.0 <= classifier_min_confidence <= 1.0
- ):
- raise SystemExit(
- "deterministic routing: --classifier-min-confidence must be in "
- "[0.0, 1.0].",
- )
-
- # Start from the validated shipping bundle so zero-flag launches work.
- preset = DeterministicRoutingPresets.coding_agent_default(
- api_key=primary.api_key or "",
- base_url=primary.base_url,
- timeout_secs=timeout,
- )
-
- strong_model = route.model or preset.strong.model
- weak_model = route.weak_model or preset.weak.model
- classifier_model_resolved = classifier_model or preset.classifier.model
- profile_resolved: ProfileName = cast(
- ProfileName, profile_name or preset.profile_name,
- )
- min_confidence = (
- classifier_min_confidence
- if classifier_min_confidence is not None
- else preset.classifier_min_confidence
- )
-
- strong_target = LlmTarget(
- id="strong",
- model=strong_model,
- format=strong_backend_format or backend_format,
- api_key=primary.api_key,
- base_url=primary.base_url,
- timeout_secs=timeout,
- )
- weak_target = LlmTarget(
- id="weak",
- model=weak_model,
- format=backend_format,
- api_key=weak.api_key,
- base_url=weak.base_url,
- timeout_secs=timeout,
- )
- classifier_target = LlmTarget(
- id="classifier",
- model=classifier_model_resolved,
- format=backend_format,
- api_key=primary.api_key,
- base_url=primary.base_url,
- timeout_secs=preset.classifier_timeout_s,
- )
-
- return DeterministicRoutingConfig(
- strong=strong_target,
- weak=weak_target,
- classifier=classifier_target,
- profile_name=profile_resolved,
- classifier_min_confidence=min_confidence,
- classifier_fail_open=preset.classifier_fail_open,
- classifier_recent_turn_window=preset.classifier_recent_turn_window,
- classifier_timeout_s=preset.classifier_timeout_s,
- enable_stats=preset.enable_stats,
- fallback_target_on_evict=preset.fallback_target_on_evict,
- preset=(
- preset.preset
- if (
- route.model is None
- and route.weak_model is None
- and classifier_model is None
- and profile_name is None
- )
- else None
- ),
- )
-
-
-__all__ = [
- "LaunchTierConnectivity",
- "build_deterministic_routing_config",
- "build_random_routing_config",
- "require_route_model",
-]
diff --git a/switchyard/cli/status.py b/switchyard/cli/status.py
deleted file mode 100644
index f01d55866..000000000
--- a/switchyard/cli/status.py
+++ /dev/null
@@ -1,220 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Status view for launcher configuration and local tool readiness."""
-
-import os
-from collections.abc import Mapping
-from dataclasses import dataclass
-
-from switchyard.cli.config.user_config import (
- DEFAULT_PROVIDER,
- DEFAULT_SECRETS_SECTION_PRIORITY,
- LaunchTarget,
- SkillDistillationConfig,
- load_user_config,
- load_user_credentials,
- resolve_provider_connectivity,
-)
-from switchyard.cli.launchers.claude_code_launcher import (
- _find_claude_binary,
-)
-from switchyard.cli.launchers.codex_cli_launcher import (
- _find_codex_binary,
-)
-from switchyard.cli.model_catalog.model_discovery import (
- ModelDiscoveryError,
- fetch_model_ids,
-)
-from switchyard.cli.output import format_route_config
-
-_API_KEY_ENV_VARS = (
- "OPENROUTER_API_KEY",
- "NVIDIA_API_KEY",
- "OPENAI_API_KEY",
- "ANTHROPIC_API_KEY",
-)
-_BASE_URL_ENV_VARS = ("OPENROUTER_BASE_URL", "NVIDIA_BASE_URL", "OPENAI_BASE_URL")
-
-
-@dataclass(frozen=True)
-class StatusRequest:
- """Inputs for rendering ``switchyard status``."""
-
- cli_api_key: str | None = None
- cli_base_url: str | None = None
- provider: str | None = None
- check: bool = False
- secrets: Mapping[str, Mapping[str, object]] | None = None
-
-
-def _secret_value(section: Mapping[str, object], key: str) -> str | None:
- value = section.get(key)
- return value if isinstance(value, str) and value else None
-
-
-def _secrets_source(
- secrets: Mapping[str, Mapping[str, object]] | None,
- key: str,
-) -> str | None:
- if not secrets:
- return None
- priority = DEFAULT_SECRETS_SECTION_PRIORITY
- for section_name in priority:
- section = secrets.get(section_name, {})
- if _secret_value(section, key):
- return f"secrets.json[{section_name}.{key}]"
- for section_name, section in secrets.items():
- if _secret_value(section, key):
- return f"secrets.json[{section_name}.{key}]"
- return None
-
-
-def _api_key_source(
- *,
- cli_api_key: str | None,
- provider: str,
- secrets: Mapping[str, Mapping[str, object]] | None,
-) -> str:
- if cli_api_key:
- return "--api-key"
- for env_var in _API_KEY_ENV_VARS:
- if os.environ.get(env_var):
- return f"${env_var}"
- credentials = load_user_credentials()
- if credentials.api_key(provider):
- return f"{provider} credentials"
- return _secrets_source(secrets, "api_key") or "<missing>"
-
-
-def _first_set_env_var(env_vars: tuple[str, ...]) -> str | None:
- for env_var in env_vars:
- if os.environ.get(env_var):
- return env_var
- return None
-
-
-def _base_url_env_var_for(prefix: str | None) -> str | None:
- if not prefix:
- return None
- env_var = f"{prefix}_BASE_URL"
- if env_var in _BASE_URL_ENV_VARS and os.environ.get(env_var):
- return env_var
- return None
-
-
-def _base_url_source(
- *,
- cli_base_url: str | None,
- provider: str,
- secrets: Mapping[str, Mapping[str, object]] | None,
-) -> str:
- if cli_base_url:
- return "--base-url"
- api_key_env_var = _first_set_env_var(_API_KEY_ENV_VARS)
- api_key_prefix = (
- api_key_env_var.removesuffix("_API_KEY")
- if api_key_env_var and api_key_env_var.endswith("_API_KEY")
- else None
- )
- env_var = _base_url_env_var_for(api_key_prefix)
- if env_var:
- return f"${env_var}"
- if not api_key_env_var:
- env_var = _base_url_env_var_for(provider.upper().replace("-", "_"))
- if env_var:
- return f"${env_var}"
- user_config = load_user_config()
- if user_config.provider(provider).base_url:
- return f"{provider} config"
- return _secrets_source(secrets, "base_url") or "built-in default"
-
-
-def _format_binary(name: str, path: str | None) -> str:
- return f"{name}: {path or '<not found>'}"
-
-
-def _format_launch_target(target: LaunchTarget) -> list[str]:
- launch_config = load_user_config().launch_target(target)
- route = launch_config.effective_route()
- lines = [f"{target}:"]
- if route.model:
- for route_line in format_route_config(route):
- lines.append(f" {route_line}")
- else:
- lines.append(" <not configured>")
- return lines
-
-
-def _format_skill_distillation(config: SkillDistillationConfig) -> str:
- if not config.configured:
- return "skill distillation: not configured"
- return (
- f"skill distillation: configured; namespace: {config.namespace}; "
- "session learning: namespace saved"
- )
-
-
-def render_status(request: StatusRequest) -> str:
- """Return a human-readable status report."""
-
- user_config = load_user_config()
- provider = request.provider or user_config.default_provider or DEFAULT_PROVIDER
- connectivity = resolve_provider_connectivity(
- cli_api_key=request.cli_api_key,
- cli_base_url=request.cli_base_url,
- api_key_env_vars=_API_KEY_ENV_VARS,
- base_url_env_vars=_BASE_URL_ENV_VARS,
- secrets=request.secrets,
- secrets_section_priority=DEFAULT_SECRETS_SECTION_PRIORITY,
- default_provider=provider,
- )
- lines = [
- "Switchyard status",
- f"provider: {connectivity.provider}",
- f"base URL: {connectivity.base_url}",
- f"base URL source: {_base_url_source(cli_base_url=request.cli_base_url, provider=connectivity.provider, secrets=request.secrets)}",
- f"API key source: {_api_key_source(cli_api_key=request.cli_api_key, provider=connectivity.provider, secrets=request.secrets)}",
- ]
- saved_bundle = user_config.routing_profiles
- if isinstance(saved_bundle, dict):
- routes = saved_bundle.get("routes")
- n = len(routes) if isinstance(routes, dict) else 0
- summary = f"<{n} route(s) saved>"
- else:
- summary = "<not configured>"
- lines.append(f"routing profiles: {summary}")
- # Surface built-in routing strategies that don't require a saved
- # bundle on `switchyard launch {claude,codex,openclaw}`.
- if not isinstance(saved_bundle, dict):
- lines.append(
- "built-in strategy: LLM-as-classifier routing (default, strong/weak)",
- )
- lines.append(_format_skill_distillation(user_config.skill_distillation))
- lines += [
- "",
- "Launch defaults",
- *_format_launch_target("claude"),
- *_format_launch_target("codex"),
- "",
- "Harness binaries",
- _format_binary("claude", _find_claude_binary()),
- _format_binary("codex", _find_codex_binary()),
- ]
-
- if request.check:
- lines.append("")
- lines.append("Provider check")
- if not connectivity.api_key:
- lines.append("models: skipped (missing API key)")
- else:
- try:
- model_ids = fetch_model_ids(connectivity.base_url, connectivity.api_key)
- except ModelDiscoveryError as exc:
- lines.append(f"models: failed ({exc})")
- else:
- lines.append(f"models: ok ({len(model_ids)} found)")
- return "\n".join(lines)
-
-
-__all__ = ["StatusRequest", "render_status"]
diff --git a/switchyard/cli/switchyard_cli.py b/switchyard/cli/switchyard_cli.py
index b56856e88..cd82216b5 100644
--- a/switchyard/cli/switchyard_cli.py
+++ b/switchyard/cli/switchyard_cli.py
@@ -2,60 +2,14 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Unified CLI entry point for the ``Switchyard`` server.
+"""Switchyard command-line entry point."""
-Exposed as the ``switchyard`` console script.
-
-Subcommands:
- serve Serve a routing-profile bundle.
- launch claude Spawn Claude Code against a proxy. Single model
- (``--model``) or full routing via ``--routing-profiles``.
- Pair with ``--smoke`` to run a one-shot harness round-trip
- and exit (replaces the old ``verify claude``).
- launch codex Spawn OpenAI Codex CLI against a proxy. Same shape as
- ``launch claude``, including ``--smoke``.
- launch openclaw Spawn OpenClaw against a proxy via a transient
- ``openclaw.json`` workspace. Same shape as
- ``launch claude``, including ``--smoke``.
- verify Run the proxy + backend e2e checklist (no harness binary).
- configure Interactive setup wizard for saved defaults. ``--show``
- (optionally with ``--check`` for a live ``GET /models``
- probe), ``--reset``, and ``--list-models`` are mutually-
- exclusive introspection modes.
-
-Examples::
-
- # --routing-profiles is a global flag (use -- to separate it from the subcommand).
- switchyard --routing-profiles routes.yaml -- serve --port 4000
- switchyard --routing-profiles dev.yaml -- serve --port 4001
- switchyard --routing-profiles profiles.yaml -- launch claude
- switchyard --routing-profiles profiles.yaml -- launch codex
-
- # Single-model passthrough (--model stays on the launcher subcommand)
- switchyard launch claude --model openai/gpt-5.2
- switchyard launch claude --smoke --model openai/gpt-5.2
- switchyard launch codex --model openai/gpt-5.2
- switchyard launch codex --smoke --model openai/gpt-5.2
- switchyard launch openclaw --model openai/gpt-5.2
- switchyard launch openclaw --smoke --model openai/gpt-5.2
- switchyard verify --model openai/gpt-5.2
-
- # Forwarding args to the launched tool (second -- after the subcommand)
- switchyard --routing-profiles profiles.yaml -- launch claude -- --no-auto-approve
-
-Routing policies that used to be top-level CLI verbs (``passthrough``,
-``random-routing``) and launcher flags
-(``--routing``, ``--weak-model``, ``--strong-probability``, ``--preset``)
-are expressed in routing-profile YAML files. ``serve`` and
-launchers still parse the YAML into profile-backed runtimes.
-"""
+from __future__ import annotations
import argparse
import logging
import os
-import sys
from collections.abc import Sequence
-from dataclasses import dataclass
from importlib.metadata import PackageNotFoundError, version
from inspect import signature
from typing import Any
@@ -63,42 +17,25 @@ from typing import Any
from switchyard.cli.command_utils import (
quiet_dependency_loggers as _quiet_dependency_loggers,
)
-from switchyard.cli.config.user_config import (
- DEFAULT_OPENROUTER_BASE_URL,
- DEFAULT_PROVIDER,
- DEFAULT_SECRETS_SECTION_PRIORITY,
- UserConfigError,
- resolve_provider_connectivity,
-)
-from switchyard.cli.configure_command import (
- cmd_configure,
-)
-from switchyard.cli.configure_request import ConfigureRequest
from switchyard.cli.intake_cli_config import IntakeCliConfig
from switchyard.cli.launch_command import (
cmd_launch_claude,
cmd_launch_codex,
cmd_launch_openclaw,
)
-from switchyard.cli.route_bundle import (
- RouteBundleConfigError,
- load_route_bundle_table,
-)
+from switchyard.cli.route_bundle import RouteBundleConfigError, load_route_bundle_table
from switchyard.lib.config import IntakeSinkConfig
from switchyard.lib.processors.intake_request_processor import IntakeRequestProcessor
from switchyard.lib.processors.intake_response_processor import IntakeResponseProcessor
from switchyard.lib.processors.rl_logging_response_processor import build_rl_logging_processors
from switchyard.server.server_util import (
- DEFAULT_SECRETS_FILE,
add_transport_args,
build_and_serve,
- load_secrets,
resolve_rl_log_dir,
)
logger = logging.getLogger(__name__)
-_DEFAULT_OPENROUTER_BASE_URL = DEFAULT_OPENROUTER_BASE_URL
_CANONICAL_INTAKE_ENABLE_FLAG = "--intake-enabled"
_DEPRECATED_INTAKE_ENABLE_FLAG = "--enable-intake"
_ARGPARSE_ACTION_SUPPORTS_DEPRECATED = (
@@ -107,7 +44,7 @@ _ARGPARSE_ACTION_SUPPORTS_DEPRECATED = (
class _IntakeEnabledAction(argparse.Action):
- """Store the normalized Intake enable flag and warn on the deprecated alias."""
+ """Normalize the Intake flag and warn on its deprecated alias."""
def __init__(
self,
@@ -156,15 +93,22 @@ class _IntakeEnabledAction(argparse.Action):
setattr(namespace, self.dest, True)
-def _add_intake_enabled_arg(parser: argparse.ArgumentParser, help_text: str) -> None:
+def _add_intake_args(parser: argparse.ArgumentParser) -> None:
parser.add_argument(
_CANONICAL_INTAKE_ENABLE_FLAG,
_DEPRECATED_INTAKE_ENABLE_FLAG,
dest="intake_enabled",
default=False,
action=_IntakeEnabledAction,
- help=f"{help_text} Deprecated alias: {_DEPRECATED_INTAKE_ENABLE_FLAG}.",
+ help=(
+ "Enable Intake for requests that opt in with store=true or "
+ "x-switchyard-intake-enabled=true."
+ ),
)
+ parser.add_argument("--intake-base-url", default=None)
+ parser.add_argument("--intake-workspace", default=None)
+ parser.add_argument("--intake-api-key", default=None)
+ parser.add_argument("--intake-target-url", default=None)
def _resolve_intake_config(args: argparse.Namespace) -> IntakeSinkConfig | None:
@@ -185,507 +129,55 @@ def _resolve_intake_processors(
intake = _resolve_intake_config(args)
if intake is None:
return [], []
- return (
- [IntakeRequestProcessor()],
- [IntakeResponseProcessor(intake)],
- )
-
-
-def _add_intake_args(parser: argparse.ArgumentParser) -> None:
- _add_intake_enabled_arg(
- parser,
- help_text=(
- "Enable the Intake sink; requests still opt in with store=true "
- "or x-switchyard-intake-enabled=true"
- ),
- )
- _add_common_intake_args(parser)
-
-
-def _add_common_intake_args(parser: argparse.ArgumentParser) -> None:
- parser.add_argument(
- "--intake-base-url", type=str, default=None,
- help=(
- "Override the intake base URL (default: read from nmp config "
- "or $SWITCHYARD_INTAKE_BASE_URL)."
- ),
- )
- parser.add_argument(
- "--intake-workspace", type=str, default=None,
- help=(
- "Override the workspace for intake entries (default: "
- "$SWITCHYARD_INTAKE_WORKSPACE, then the NMP SDK config)."
- ),
- )
- parser.add_argument(
- "--intake-api-key", type=str, default=None,
- help=(
- "Override the bearer token (default: read from nmp config — "
- "with refresh — or fall back to $SWITCHYARD_INTAKE_API_KEY / "
- "$NMP_ACCESS_TOKEN). Setting this opts out of the SDK's "
- "config-based bootstrap and disables transparent refresh."
- ),
- )
- parser.add_argument(
- "--intake-target-url", type=str, default=None,
- help=(
- "Post flat per-request telemetry to this full URL (a data-lake "
- "posting endpoint) instead of nemo-platform chat-completions "
- "ingest. Defaults to $SWITCHYARD_INTAKE_TARGET_URL."
- ),
- )
-
-
-_DETERMINISTIC_PROFILE_CHOICES = ("general", "coding_agent", "openclaw")
-
-
-def _add_launch_deterministic_override_args(parser: argparse.ArgumentParser) -> None:
- """Attach the deterministic-trio override knobs to a ``launch`` subparser.
-
- Used by ``launch claude``, ``launch codex``, and ``launch openclaw``,
- where LLM-classifier routing is the implicit default — these flags let
- users tune the validated TB-Lite trio without writing a full
- routing-profiles YAML. They have no effect when ``--model X`` or
- ``--routing-profiles FILE`` opts the launcher out of LLM-classifier
- routing.
- """
- parser.add_argument(
- "--weak-model",
- type=str,
- default=None,
- help=(
- "Override the weak-tier model id of the default deterministic "
- "trio. Defaults to moonshotai/kimi-k2.6."
- ),
- )
- parser.add_argument(
- "--classifier-model",
- type=str,
- default=None,
- help=(
- "Override the classifier LLM. Defaults to "
- "google/gemini-3.5-flash (cheap + fast)."
- ),
- )
- parser.add_argument(
- "--profile",
- type=str,
- default=None,
- choices=_DETERMINISTIC_PROFILE_CHOICES,
- help=(
- "Classifier profile. Defaults to coding_agent "
- "(SIMPLE+MEDIUM→weak, COMPLEX/REASONING→strong, "
- "tool-planning escalation, high-confidence LLM alignment)."
- ),
- )
- parser.add_argument(
- "--classifier-min-confidence",
- type=float,
- default=None,
- help=(
- "Tier-selector confidence floor in [0.0, 1.0]. Below this "
- "the classifier's decision falls back to the strong tier "
- "(fail safer, not cheaper). Defaults to 0.0 — honor every "
- "non-abstain classification."
- ),
- )
-
-
-def _add_launch_intake_args(parser: argparse.ArgumentParser) -> None:
- """
- Attach ``--intake-enabled`` + companion args to a ``launch`` subparser.
- """
- _add_intake_enabled_arg(
- parser,
- help_text=(
- "Wire intake into both the in-process proxy and the spawned "
- "client. Uses the NMP SDK's configured credentials by default "
- "(run `nmp auth login --base-url {INTAKE_BASE_URL}` "
- "once). Override with --intake-base-url / --intake-api-key for "
- "headless or CI use."
- ),
- )
- _add_common_intake_args(parser)
- parser.add_argument(
- "--intake-app", type=str, default=None,
- help=(
- "App name for entry context (default: $SWITCHYARD_INTAKE_APP, "
- "then a launcher-specific default)."
- ),
- )
- parser.add_argument(
- "--intake-task", type=str, default=None,
- help=(
- "Task name for entry context (default: $SWITCHYARD_INTAKE_TASK, "
- "then 'developer-session')."
- ),
- )
- parser.add_argument(
- "--intake-session-id", type=str, default=None,
- help=(
- "Session id stamped on every entry. Defaults to "
- "$SWITCHYARD_SESSION_ID, then '<target>-<unix-ms>-<rand>'."
- ),
- )
- parser.add_argument(
- "--intake-user-id", type=str, default=None,
- help=(
- "Anonymous user id stamped on every entry. Defaults to "
- "$SWITCHYARD_USER_ID, then the stable per-machine id at "
- "~/.switchyard/user_id (created on first use)."
- ),
- )
-
-
-def _cmd_configure(args: argparse.Namespace) -> None:
- cmd_configure(ConfigureRequest.from_namespace(args))
-
-
-def _cmd_launch_claude(args: argparse.Namespace) -> None:
- cmd_launch_claude(args)
-
-
-def _cmd_launch_codex(args: argparse.Namespace) -> None:
- cmd_launch_codex(args)
-
-
-def _cmd_launch_openclaw(args: argparse.Namespace) -> None:
- cmd_launch_openclaw(args)
-
-
-# ---------------------------------------------------------------------------
-# Subcommand: serve
-# ---------------------------------------------------------------------------
+ return [IntakeRequestProcessor()], [IntakeResponseProcessor(intake)]
def _cmd_serve(args: argparse.Namespace) -> None:
- """Serve a routing-profile bundle."""
- from switchyard.cli.config.user_config import load_user_config
- from switchyard.cli.route_bundle import build_route_bundle_table
+ """Serve an explicit routing-profile bundle."""
- routing_profiles = args.routing_profiles
- # Intake sink + local RL trace logging both attach as chain processors;
- # combine them so a single serve invocation can run either or both.
intake_request, intake_response = _resolve_intake_processors(args)
rl_request, rl_response = build_rl_logging_processors(resolve_rl_log_dir(args))
request_processors = [*intake_request, *rl_request]
response_processors = [*intake_response, *rl_response]
- if getattr(args, "routing_log_file", None):
+ if args.routing_log_file:
from switchyard.lib.processors.routing_log_response_processor import (
RoutingLogResponseProcessor,
)
response_processors.append(RoutingLogResponseProcessor(args.routing_log_file))
- if routing_profiles:
- table = load_route_bundle_table(
- routing_profiles,
- pre_routing_request_processors=request_processors,
- extra_response_processors=response_processors,
- )
- source = routing_profiles
- else:
- saved = load_user_config().routing_profiles
- if not saved:
- raise SystemExit(
- "serve: no routing-profiles given. Pass --routing-profiles "
- "PATH or run `switchyard --routing-profiles PATH configure` "
- "to save one."
- )
- # Saved bundles are stored as parsed dicts, so we can skip the
- # YAML parse step and feed them straight into the dict-driven
- # entrypoint. Env-var references inside the dict expand inside
- # build_route_bundle_table on each run.
- table = build_route_bundle_table(
- saved,
- pre_routing_request_processors=request_processors,
- extra_response_processors=response_processors,
- )
- source = f"<saved bundle, {len(table.registered_models())} route(s)>"
+
+ table = load_route_bundle_table(
+ args.routing_profiles,
+ pre_routing_request_processors=request_processors,
+ extra_response_processors=response_processors,
+ )
logger.info(
"Switchyard route bundle loaded %d route(s) from %s",
len(table.registered_models()),
- source,
+ args.routing_profiles,
)
strategy_summary: str | None = None
default_model = table.default_model()
- if routing_profiles and default_model:
- from switchyard.cli.launchers.launcher_runtime import routing_profiles_strategy_summary
- try:
- strategy_summary = routing_profiles_strategy_summary(
- routing_profiles[0], default_model,
- )
- except Exception:
- pass
- build_and_serve(args, table, inbound_default="both", strategy_summary=strategy_summary)
-
-
-# ---------------------------------------------------------------------------
-# Subcommand: verify {proxy,claude,codex}
-# ---------------------------------------------------------------------------
-
-
-# Default verify model. Matches ``tests/offline_production_tests/conftest.py``
-# (NVIDIA inference-api) so a user with secrets/secrets.json wired up can
-# run ``switchyard verify proxy`` with no args at all and get a
-# meaningful pass/fail.
-_DEFAULT_VERIFY_MODEL = "openai/gpt-5.2"
-
-# Env vars and secrets-section priority verified by ``verify``. Same
-# resolution order as :func:`_resolve_verify_credentials` uses through
-# ``resolve_provider_connectivity`` — kept as module constants so the
-# diagnostic helper can iterate them in the same order without importing
-# private helper internals.
-_VERIFY_API_KEY_ENV_VARS: tuple[str, ...] = (
- "OPENROUTER_API_KEY",
- "NVIDIA_API_KEY",
- "OPENAI_API_KEY",
- "ANTHROPIC_API_KEY",
-)
-_VERIFY_BASE_URL_ENV_VARS: tuple[str, ...] = (
- "OPENROUTER_BASE_URL",
- "NVIDIA_BASE_URL",
- "OPENAI_BASE_URL",
-)
-_VERIFY_SECRETS_PRIORITY: tuple[str, ...] = DEFAULT_SECRETS_SECTION_PRIORITY
-
-
-@dataclass
-class _CredentialAttempt:
- """One row of the credential-resolution diagnostic.
-
- ``label`` is a stable short token (``"--api-key"`` /
- ``"$OPENROUTER_API_KEY"`` / ``"secrets.json[openrouter]"``) suitable for
- both the user-facing error table and the ``key_source`` label
- forwarded into :func:`verify_proxy` (which surfaces it in
- step 1's success line and step 2's 401 hint).
-
- ``status`` is the human-readable verdict for that source:
- ``"not provided"``, ``"set (32 chars)"``, ``"file not found"``,
- ``"missing 'api_key' field"``, etc.
-
- ``has_value`` is True iff the source produced a non-empty key.
- The first :class:`_CredentialAttempt` with ``has_value=True`` is
- the resolved key — same waterfall as
- :func:`resolve_provider_connectivity`.
- """
-
- label: str
- status: str
- has_value: bool
-
-
-def _redact_status(value: str | None) -> str:
- """Render an env-var / secrets-field value as a status string.
-
- ``None`` ⇒ ``"not set"``. Empty string ⇒ ``"empty (0 chars)"`` so
- the user notices an env var that was set but exported as empty
- (a common subtle bug). Otherwise ``"set (N chars)"`` — the char
- count helps the user spot truncation without exposing the secret.
- """
- if value is None:
- return "not set"
- if not value:
- return "empty (0 chars)"
- return f"set ({len(value)} chars)"
-
-
-def _diagnose_credential_resolution(
- args: argparse.Namespace,
-) -> tuple[str | None, str | None, str | None, list[_CredentialAttempt]]:
- """Walk the same waterfall as ``_resolve_verify_credentials`` but
- record every source we touched along the way.
-
- Returns ``(api_key, base_url, key_source, attempts)``:
-
- * ``api_key`` / ``base_url`` — same values
- :func:`resolve_provider_connectivity` would return.
- * ``key_source`` — the ``label`` of the first attempt whose
- ``has_value`` is True, or ``None`` when nothing produced a key.
- * ``attempts`` — every source we considered, in resolution order.
- Always non-empty. Used to build the tabulated error message
- when no source produced a key.
-
- The walk *parallels* :func:`resolve_provider_connectivity` rather
- than wrapping it because the underlying helper has no notion of
- "which source won". Duplication here is bounded (one waterfall, six sources)
- and the diagnostic UX is the whole point of the wrapper.
- """
- attempts: list[_CredentialAttempt] = []
- resolved_key: str | None = None
- key_source: str | None = None
-
- def _record(label: str, value: str | None, status: str) -> None:
- """Append a row to ``attempts`` and pin the resolved key on
- the first non-empty value. ``status`` is overridable so
- secrets-file rows can carry per-section context (file
- missing vs. field missing vs. set).
- """
- nonlocal resolved_key, key_source
- has_value = bool(value)
- attempts.append(_CredentialAttempt(label, status, has_value))
- if has_value and resolved_key is None:
- resolved_key = value
- key_source = label
-
- # 1. --api-key
- cli_key = args.api_key
- _record(
- "--api-key",
- cli_key,
- "provided" if cli_key else "not provided",
- )
-
- # 2. env vars (in order)
- for env_var in _VERIFY_API_KEY_ENV_VARS:
- env_value = os.environ.get(env_var)
- _record(f"${env_var}", env_value, _redact_status(env_value))
-
- # 3. secrets.json — break down failure modes so the user knows
- # whether the file is missing, the section is missing, or the
- # field is missing. Each is a different fix.
- secrets_path = DEFAULT_SECRETS_FILE
- if not secrets_path.exists():
- for section_name in _VERIFY_SECRETS_PRIORITY:
- _record(
- f"secrets.json[{section_name}.api_key]",
- None,
- f"file not found ({secrets_path})",
- )
- else:
- secrets = load_secrets()
- for section_name in _VERIFY_SECRETS_PRIORITY:
- section_body = secrets.get(section_name)
- label = f"secrets.json[{section_name}.api_key]"
- # ``SecretsFile`` types every section as a Mapping, so the
- # only structural failures we surface are "section missing"
- # and "section present but no api_key field". A malformed
- # JSON file would have crashed in :func:`load_secrets`
- # already, so we don't double-check the section's type here.
- if section_body is None:
- _record(label, None, f"section '{section_name}' missing")
- continue
- value = section_body.get("api_key")
- if not isinstance(value, str):
- _record(label, None, "field missing")
- continue
- _record(label, value, _redact_status(value))
-
- # base_url has its own waterfall, but verify's error story doesn't need
- # a per-source breakdown. Resolve it with the same provider-aware pairing
- # as launch/configure so mixed provider env vars do not get mismatched.
- connectivity = resolve_provider_connectivity(
- cli_api_key=args.api_key,
- cli_base_url=args.base_url,
- api_key_env_vars=_VERIFY_API_KEY_ENV_VARS,
- base_url_env_vars=_VERIFY_BASE_URL_ENV_VARS,
- secrets=load_secrets() if DEFAULT_SECRETS_FILE.exists() else None,
- secrets_section_priority=_VERIFY_SECRETS_PRIORITY,
- )
-
- return resolved_key, connectivity.base_url, key_source, attempts
-
-
-def _format_credential_failure(attempts: list[_CredentialAttempt]) -> str:
- """Render the multi-line tabulated diagnostic for the no-key case.
-
- Goal: the user sees, at a glance, *every* source verify checked
- and *what was wrong with each one*, plus a concrete "to fix:"
- pointer for the most common case. Aligning the labels makes the
- table scannable in dark-mode terminals where the eye is doing
- column scanning, not word reading.
- """
- width = max(len(a.label) for a in attempts) + 2
- lines = [
- "verify: no API key resolved. Tried:",
- ]
- for attempt in attempts:
- lines.append(f" {attempt.label.ljust(width)}{attempt.status}")
- lines.append("")
- lines.append(
- "To fix, set ONE of the above sources. Most common:",
- )
- lines.append(
- " export OPENROUTER_API_KEY=sk-... "
- "# (or any other env var listed above)",
- )
- lines.append(
- " cp secrets/secrets.template.json secrets/secrets.json "
- "# then edit it",
- )
- return "\n".join(lines)
-
-
-def _resolve_verify_credentials(
- args: argparse.Namespace,
-) -> tuple[str, str, str | None]:
- """Common credential resolution for all three ``verify`` modes.
-
- Mirrors :func:`_cmd_launch_claude` / :func:`_cmd_launch_codex`:
- ``--api-key`` / ``OPENROUTER_API_KEY`` / ``NVIDIA_API_KEY`` /
- ``OPENAI_API_KEY`` / ``ANTHROPIC_API_KEY`` / secrets.json waterfall;
- ``--base-url`` / ``OPENROUTER_BASE_URL`` / ``NVIDIA_BASE_URL`` /
- ``OPENAI_BASE_URL`` waterfall; defaults to OpenRouter when the user
- didn't supply one.
-
- Unlike the launchers, this helper raises ``SystemExit`` with a
- *tabulated* error rather than warning + injecting a ``"dummy"``
- placeholder. Verify is *the* command that confirms credential
- resolution works — silently masking a missing key would defeat
- the whole purpose, and a generic "set one of these" hint makes
- the user check every source instead of pointing them at the one
- they actually broke.
+ if default_model:
+ from switchyard.cli.launchers.launcher_runtime import (
+ routing_profiles_strategy_summary,
+ )
- Returns ``(api_key, base_url, key_source)`` where ``key_source``
- is the human label of the source that produced the key (e.g.
- ``"$OPENROUTER_API_KEY"``). Forwarded to the verify orchestrators
- so the credential-step's success line and the backend-reach
- step's 401 hint can name the source by hand.
- """
- api_key, base_url, key_source, attempts = (
- _diagnose_credential_resolution(args)
+ strategy_summary = routing_profiles_strategy_summary(
+ args.routing_profiles,
+ default_model,
+ )
+ build_and_serve(
+ args,
+ table,
+ inbound_default="both",
+ strategy_summary=strategy_summary,
)
- resolved_base_url = base_url or _DEFAULT_OPENROUTER_BASE_URL
- if not api_key:
- raise SystemExit(_format_credential_failure(attempts))
- return api_key, resolved_base_url, key_source
-
-
-def _cmd_verify(args: argparse.Namespace) -> None:
- """Run the proxy-only verify checklist.
-
- Harness-driven verify modes (``verify claude`` / ``verify codex``)
- moved to ``launch claude --smoke`` / ``launch codex --smoke``;
- ``verify`` is now the leaf for the proxy-only checklist that K8s
- readiness probes and CI install gates rely on.
- """
- from switchyard.server.verify import verify_proxy
-
- api_key, base_url, key_source = _resolve_verify_credentials(args)
- raise SystemExit(verify_proxy(
- model=args.model,
- base_url=base_url,
- api_key=api_key,
- port=args.port,
- timeout=args.timeout,
- key_source=key_source,
- ))
-
-
-# ---------------------------------------------------------------------------
-# Argument parser construction
-# ---------------------------------------------------------------------------
def _switchyard_version() -> str:
- """Resolve the installed Switchyard version for ``--version``.
+ """Resolve the installed distribution version."""
- Reads the version from the installed package metadata (ultimately the
- ``version`` field in ``pyproject.toml``), matching the runtime lookup in
- ``intake_payload_builder``. Falls back to the static ``__version__``
- constant when the package is not installed (e.g. running from a source
- checkout that was never built), which the release tooling keeps in sync
- with ``pyproject.toml``.
- """
try:
return version("nemo-switchyard")
except PackageNotFoundError:
@@ -694,624 +186,95 @@ def _switchyard_version() -> str:
return __version__
+def _add_launch_parser(
+ subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+ launch = subparsers.add_parser(
+ "launch",
+ help="Launch a coding agent through the native server",
+ )
+ launch_sub = launch.add_subparsers(dest="launch_target", help="Agent to launch")
+ launcher_parsers = (
+ ("claude", "Launch Claude Code", "claude_args", cmd_launch_claude),
+ ("codex", "Launch Codex CLI", "codex_args", cmd_launch_codex),
+ ("openclaw", "Launch OpenClaw", "openclaw_args", cmd_launch_openclaw),
+ )
+ for name, help_text, args_dest, command in launcher_parsers:
+ agent = launch_sub.add_parser(name, help=help_text)
+ agent.add_argument("--model", required=True, help="Route ID from the deployment.")
+ agent.add_argument(
+ "--config",
+ metavar="PATH",
+ help="TOML deployment (default: packaged OpenRouter deployment).",
+ )
+ agent.add_argument(
+ args_dest,
+ nargs=argparse.REMAINDER,
+ help="Arguments forwarded to the coding agent after --.",
+ )
+ agent.set_defaults(func=command)
+
+ def _launch_help(args: argparse.Namespace) -> None: # noqa: ARG001
+ launch.print_help()
+ raise SystemExit(1)
+
+ launch.set_defaults(func=_launch_help)
+
+
def _build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
prog="switchyard",
- description="Switchyard — chain-based LLM proxy server CLI",
+ description="Switchyard LLM proxy",
)
parser.add_argument(
"--version",
action="version",
version=f"%(prog)s {_switchyard_version()}",
- help="Print the installed Switchyard version and exit.",
- )
- parser.add_argument(
- "--routing-profiles", "-c",
- dest="routing_profiles",
- default=None,
- metavar="PATH",
- help=(
- "Path to a routing-profiles YAML file. Applies to "
- "serve, launch, and configure (saves it as the default). Separate "
- "from the subcommand with -- for clarity: "
- "switchyard --routing-profiles dev.yaml -- launch claude"
- ),
)
- parser.add_argument(
- "--enable-rl-logging",
- dest="enable_rl_logging",
- action="store_true",
- help=(
- "Write per-turn RL training traces (message_history JSON, one "
- "file per request/response pair) for `launch` sessions. Global "
- "flag — place it before the subcommand, e.g. "
- "switchyard --enable-rl-logging launch claude."
- ),
- )
- parser.add_argument(
- "--rl-log-dir",
- dest="rl_log_dir",
- default="./rl_data",
- metavar="DIR",
- help=(
- "Directory for RL trace logs (default: ./rl_data). Only takes "
- "effect with --enable-rl-logging."
- ),
- )
- subparsers = parser.add_subparsers(dest="command", help="Server mode")
+ subparsers = parser.add_subparsers(dest="command")
- # -- serve --
- serve = subparsers.add_parser(
- "serve",
- help="Serve a routing-profile bundle",
- description=(
- "Serve a routing-profile YAML bundle selected with the global "
- "--routing-profiles option."
- ),
- )
- add_transport_args(serve)
- _add_intake_args(serve)
+ serve = subparsers.add_parser("serve", help="Serve a routing-profile bundle")
serve.add_argument(
- "--routing-log-file",
- dest="routing_log_file",
- default=None,
+ "--routing-profiles",
+ "-c",
+ required=True,
metavar="PATH",
- help=(
- "Append one JSONL routing record per request (task, session, "
- "selected model, tier, token usage) to PATH."
- ),
+ help="Routing-profile YAML bundle.",
)
+ serve.add_argument("--enable-rl-logging", action="store_true")
+ serve.add_argument("--rl-log-dir", default="./rl_data", metavar="DIR")
+ add_transport_args(serve)
+ _add_intake_args(serve)
+ serve.add_argument("--routing-log-file", default=None, metavar="PATH")
serve.add_argument(
- "--workers", "-w", type=int,
+ "--workers",
+ "-w",
+ type=int,
default=int(os.environ.get("SWITCHYARD_WORKERS", "1")),
- help="Number of uvicorn worker processes (default: 1, or SWITCHYARD_WORKERS env var)",
)
serve.set_defaults(func=_cmd_serve)
- # -- configure --
- cfg = subparsers.add_parser(
- "configure",
- help="Store default provider credentials and launch models",
- description=(
- "Persist user-level Switchyard defaults under "
- "~/.config/switchyard. Credentials are stored separately "
- "from non-secret config with owner-only file permissions."
- ),
- )
- cfg_mode = cfg.add_mutually_exclusive_group()
- cfg_mode.add_argument(
- "--show", action="store_true",
- help=(
- "Print the redacted user config plus resolved provider, API-key "
- "source, and harness binary paths. Pair with --check for a live "
- "GET /models probe."
- ),
- )
- cfg_mode.add_argument(
- "--reset", action="store_true",
- help="Delete persisted user config and credentials",
- )
- cfg_mode.add_argument(
- "--list-models", action="store_true", dest="list_models",
- help=(
- "Fetch GET /models from the resolved provider and print a "
- "ranked, searchable list. Combine with --target / --query / "
- "--limit."
- ),
- )
- cfg.add_argument(
- "--json", action="store_true",
- help="With --show, print the raw redacted JSON snapshot",
- )
- cfg.add_argument(
- "--target", type=str, default="all",
- choices=("all", "provider", "claude", "codex", "openclaw"),
- help=(
- "Which defaults to configure: provider credentials only, "
- "Claude Code, Codex, OpenClaw, or all (default: all)"
- ),
- )
- cfg.add_argument(
- "--provider", type=str, default=None,
- help=f"Provider id to configure (default: the saved default_provider, "
- f"or {DEFAULT_PROVIDER} if none is saved)",
- )
- cfg.add_argument(
- "--base-url", type=str, default=None,
- help=(
- "Backend base URL to save (default: "
- f"{_DEFAULT_OPENROUTER_BASE_URL})"
- ),
- )
- cfg.add_argument(
- "--api-key", type=str, default=None,
- help="API key to save. Omit in an interactive terminal to be prompted.",
- )
- cfg.add_argument(
- "--claude-model", type=str, default=None,
- help="Claude Code default model. Omit to select from GET /models.",
- )
- cfg.add_argument(
- "--claude-base-url", type=str, default=None,
- help="Claude Code model endpoint override. Omit to use the default base URL.",
- )
- cfg.add_argument(
- "--claude-api-key", type=str, default=None,
- help="Claude Code model API-key override. Omit to use the default API key.",
- )
- cfg.add_argument(
- "--codex-model", type=str, default=None,
- help="Codex default model. Omit to select from GET /models.",
- )
- cfg.add_argument(
- "--codex-base-url", type=str, default=None,
- help="Codex model endpoint override. Omit to use the default base URL.",
- )
- cfg.add_argument(
- "--codex-api-key", type=str, default=None,
- help="Codex model API-key override. Omit to use the default API key.",
- )
- cfg.add_argument(
- "--openclaw-model", type=str, default=None,
- help="OpenClaw default model. Omit to select from GET /models.",
- )
- cfg.add_argument(
- "--openclaw-base-url", type=str, default=None,
- help="OpenClaw model endpoint override. Omit to use the default base URL.",
- )
- cfg.add_argument(
- "--openclaw-api-key", type=str, default=None,
- help="OpenClaw model API-key override. Omit to use the default API key.",
- )
- cfg_mode.add_argument(
- "--skill-distillation",
- metavar="NAMESPACE",
- default=None,
- help=(
- "Save a namespace for one skill that improves over time. Many "
- "sessions or trajectories can contribute to it; the namespace is "
- "not a session ID. Use a safe local path component (for example: "
- "tooluniverse-trialqa)."
- ),
- )
- cfg_mode.add_argument(
- "--disable-skill-distillation",
- action="store_true",
- help="Remove saved skill distillation config.",
- )
- cfg.add_argument(
- "--no-model-discovery", action="store_true",
- help="Skip GET /models and rely on explicit or existing model values",
- )
- cfg.add_argument(
- "--no-tui", action="store_true",
- help="Use plain text prompts instead of the interactive terminal selector",
- )
- cfg.add_argument(
- "--query", "-q", type=str, default=None,
- help=(
- "With --list-models, case-insensitive substring filter applied "
- "to the result set."
- ),
- )
- cfg.add_argument(
- "--limit", type=int, default=50,
- help=(
- "With --list-models, cap on the number of models printed "
- "(default: 50; pass 0 for unlimited)."
- ),
- )
- cfg.add_argument(
- "--check", action="store_true",
- help=(
- "With --show, also call GET /models on the resolved provider "
- "and report pass/fail."
- ),
- )
- cfg.set_defaults(func=_cmd_configure)
-
- # -- launch --
- launch = subparsers.add_parser(
- "launch",
- help="Start proxy + spawn a CLI tool in one command (ollama-style UX)",
- description=(
- "Start a proxy and spawn a CLI tool pointed at it in the same "
- "terminal, tear it down when the tool exits."
- ),
- )
- launch_sub = launch.add_subparsers(dest="launch_target", help="Tool to launch")
-
- # -- launch claude --
- lc = launch_sub.add_parser(
- "claude",
- help="Launch Claude Code with a proxy (one terminal, one command)",
- description=(
- "Starts a proxy on an auto-picked free local port, then "
- "spawns `claude` with ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, "
- "and ANTHROPIC_MODEL preset. Proxy shuts down when claude exits.\n\n"
- "Route selection (mutually exclusive — pick one or neither):\n"
- " --model X single-model passthrough — every request "
- "is rewritten to model=X. Falls back to the saved configure default.\n"
- " --routing-profiles PATH serve a YAML bundle of routes (random, "
- "stage_router, …); the first declared route "
- "is the initial model.\n\n"
- "With neither flag, the saved routing bundle from "
- "`switchyard configure` is used."
- ),
- formatter_class=argparse.RawDescriptionHelpFormatter,
- )
- lc.add_argument(
- "--model", type=str, default=None,
- help=(
- "Single-model passthrough: model id from GET /v1/models "
- "(e.g. openai/gpt-5.2). Falls back to the saved "
- "`configure` default when omitted. Mutually exclusive with "
- "--routing-profiles (pass that as a global switchyard flag before "
- "the subcommand)."
- ),
- )
- lc.add_argument(
- "--base-url", type=str, default=None,
- help=(
- "Backend base URL (default: "
- f"{_DEFAULT_OPENROUTER_BASE_URL}, or OPENROUTER_BASE_URL / "
- "NVIDIA_BASE_URL / "
- "OPENAI_BASE_URL env var)."
- ),
- )
- lc.add_argument(
- "--api-key", type=str, default=None,
- help=(
- "API key (falls back to OPENROUTER_API_KEY, NVIDIA_API_KEY, OPENAI_API_KEY, "
- "user config, secrets.json)"
- ),
- )
- lc.add_argument(
- "--no-model-discovery", action="store_true",
- help="First-run setup: skip GET /models and type the model manually",
- )
- lc.add_argument(
- "--no-tui", action="store_true",
- help="First-run setup: use plain text prompts instead of the TUI selector",
- )
- lc.add_argument(
- "--reconfigure", action="store_true",
- help="Run Claude setup before launching, even if defaults already exist",
- )
- lc.add_argument(
- "--dry-run", action="store_true",
- help="Print resolved launch settings without starting the proxy or Claude",
- )
- lc.add_argument(
- "--smoke", action="store_true",
- help=(
- "Smoke-test mode: start the proxy, run one "
- "`claude -p \"<smoke>\" --max-turns 1` round-trip, assert exit 0, "
- "and exit. Replaces the old `switchyard verify claude` subcommand. "
- "Requires --model; cannot be combined with --routing-profiles or --dry-run "
- "(use --model directly to pick the model to smoke-test)."
- ),
- )
- lc.add_argument(
- "--port", type=int, default=None,
- help="Proxy port (default: auto-pick free port)",
- )
- lc.add_argument(
- "--timeout", type=float, default=None,
- help="Request timeout in seconds for the backend LLM client",
- )
- lc.add_argument(
- "--startup-timing", action="store_true",
- help=(
- "Print a per-stage startup timing breakdown to stderr before "
- "claude starts (each backend-format probe on its own line). "
- "Also enabled with SWITCHYARD_STARTUP_TIMING=1."
- ),
- )
- _add_launch_deterministic_override_args(lc)
- _add_launch_intake_args(lc)
- lc.add_argument(
- "claude_args", nargs=argparse.REMAINDER,
- help="Args forwarded to claude (prefix with `--`, e.g. `-- --version`)",
- )
- lc.set_defaults(func=_cmd_launch_claude)
-
- # -- launch codex --
- cx = launch_sub.add_parser(
- "codex",
- help="Launch OpenAI Codex CLI with a proxy (one terminal, one command)",
- description=(
- "Starts a proxy on an auto-picked free local port, then "
- "spawns `codex` with a transient `switchyard` provider injected "
- "via repeated `-c` flags (no edits to ~/.codex/config.toml).\n\n"
- "Codex talks to the proxy via OpenAI Responses API "
- "(/v1/responses); the chain translates that to OpenAI Chat "
- "Completions for the upstream backend. Proxy shuts down when "
- "codex exits.\n\n"
- "Route selection (mutually exclusive — pick one or neither):\n"
- " --model X single-model passthrough — every request "
- "is rewritten to model=X. Falls back to the saved configure default.\n"
- " --routing-profiles PATH serve a YAML bundle of routes (random, "
- "stage_router, …); the first declared route "
- "is the initial model.\n\n"
- "With neither flag, the saved routing bundle from "
- "`switchyard configure` is used."
- ),
- formatter_class=argparse.RawDescriptionHelpFormatter,
- )
- cx.add_argument(
- "--model", type=str, default=None,
- help=(
- "Single-model passthrough: model id from GET /v1/models "
- "(e.g. openai/gpt-5.2). Falls back to the saved "
- "`configure` default when omitted. Mutually exclusive with "
- "--routing-profiles (pass that as a global switchyard flag before "
- "the subcommand)."
- ),
- )
- cx.add_argument(
- "--base-url", type=str, default=None,
- help=(
- "Backend base URL (default: "
- f"{_DEFAULT_OPENROUTER_BASE_URL}, or OPENROUTER_BASE_URL / "
- "NVIDIA_BASE_URL / "
- "OPENAI_BASE_URL env var)."
- ),
- )
- cx.add_argument(
- "--api-key", type=str, default=None,
- help=(
- "API key (falls back to OPENROUTER_API_KEY, NVIDIA_API_KEY, OPENAI_API_KEY, "
- "user config, secrets.json)"
- ),
- )
- cx.add_argument(
- "--no-model-discovery", action="store_true",
- help="First-run setup: skip GET /models and type the model manually",
- )
- cx.add_argument(
- "--no-tui", action="store_true",
- help="First-run setup: use plain text prompts instead of the TUI selector",
- )
- cx.add_argument(
- "--reconfigure", action="store_true",
- help="Run Codex setup before launching, even if defaults already exist",
- )
- cx.add_argument(
- "--dry-run", action="store_true",
- help="Print resolved launch settings without starting the proxy or Codex",
- )
- cx.add_argument(
- "--smoke", action="store_true",
- help=(
- "Smoke-test mode: start the proxy, run one "
- "`codex exec \"<smoke>\"` round-trip, assert exit 0, and exit. "
- "Replaces the old `switchyard verify codex` subcommand. "
- "Requires --model; cannot be combined with --routing-profiles or --dry-run "
- "(use --model directly to pick the model to smoke-test)."
- ),
- )
- cx.add_argument(
- "--port", type=int, default=None,
- help="Proxy port (default: auto-pick free port)",
- )
- cx.add_argument(
- "--timeout", type=float, default=None,
- help="Request timeout in seconds for the backend LLM client",
- )
- _add_launch_deterministic_override_args(cx)
- _add_launch_intake_args(cx)
- cx.add_argument(
- "codex_args", nargs=argparse.REMAINDER,
- help="Args forwarded to codex (prefix with `--`, e.g. `-- exec \"hi\"`)",
- )
- cx.set_defaults(func=_cmd_launch_codex)
-
- # -- launch openclaw --
- ow = launch_sub.add_parser(
- "openclaw",
- help="Launch OpenClaw with a proxy (one terminal, one command)",
- description=(
- "Starts a proxy on an auto-picked free local port, then "
- "spawns `openclaw chat` (alias for `openclaw tui --local`) "
- "against a transient OpenClaw "
- "workspace (OPENCLAW_STATE_DIR / OPENCLAW_HOME / "
- "OPENCLAW_CONFIG_PATH point at a tempdir) — the user's "
- "real ~/.openclaw/ (sessions, channels, plugins) is "
- "untouched.\n\n"
- "OpenClaw talks to the proxy via OpenAI Chat Completions "
- "(/v1/chat/completions); the proxy translates as needed for "
- "the upstream backend. Proxy and the transient workspace "
- "are torn down when openclaw exits.\n\n"
- "Route selection (mutually exclusive — pick one or neither):\n"
- " --model X single-model passthrough — every request "
- "is rewritten to model=X. Falls back to the saved configure default.\n"
- " --routing-profiles PATH serve a YAML bundle of routes (random, "
- "stage_router, …); the first declared route "
- "is the initial model.\n\n"
- "With neither flag, the saved routing bundle from "
- "`switchyard configure` is used."
- ),
- formatter_class=argparse.RawDescriptionHelpFormatter,
- )
- ow.add_argument(
- "--model", type=str, default=None,
- help=(
- "Single-model passthrough: model id from GET /v1/models "
- "(e.g. openai/gpt-5.2). Falls back to the saved "
- "`configure` default when omitted. Mutually exclusive with "
- "--routing-profiles (pass that as a global switchyard flag before "
- "the subcommand)."
- ),
- )
- ow.add_argument(
- "--base-url", type=str, default=None,
- help=(
- "Backend base URL (default: "
- f"{_DEFAULT_OPENROUTER_BASE_URL}, or OPENROUTER_BASE_URL / "
- "NVIDIA_BASE_URL / "
- "OPENAI_BASE_URL env var)."
- ),
- )
- ow.add_argument(
- "--api-key", type=str, default=None,
- help=(
- "API key (falls back to OPENROUTER_API_KEY, NVIDIA_API_KEY, OPENAI_API_KEY, "
- "user config, secrets.json)"
- ),
- )
- ow.add_argument(
- "--no-model-discovery", action="store_true",
- help="First-run setup: skip GET /models and type the model manually",
- )
- ow.add_argument(
- "--no-tui", action="store_true",
- help="First-run setup: use plain text prompts instead of the TUI selector",
- )
- ow.add_argument(
- "--reconfigure", action="store_true",
- help="Run OpenClaw setup before launching, even if defaults already exist",
- )
- ow.add_argument(
- "--dry-run", action="store_true",
- help="Print resolved launch settings without starting the proxy or OpenClaw",
- )
- ow.add_argument(
- "--port", type=int, default=None,
- help="Proxy port (default: auto-pick free port)",
- )
- ow.add_argument(
- "--timeout", type=float, default=None,
- help="Request timeout in seconds for the backend LLM client",
- )
- ow.add_argument(
- "--smoke", action="store_true",
- help=(
- "Smoke-test mode: start the proxy, run one openclaw round-trip "
- "(non-interactive, JSON envelope), assert exit 0, and exit. "
- "Replaces the old `switchyard verify openclaw` subcommand. "
- "Requires --model; cannot be combined with --routing-profiles or --dry-run "
- "(use --model directly to pick the model to smoke-test)."
- ),
- )
- _add_launch_deterministic_override_args(ow)
- _add_launch_intake_args(ow)
- ow.add_argument(
- "openclaw_args", nargs=argparse.REMAINDER,
- help=(
- "Args forwarded to `openclaw chat` "
- "(prefix with `--`, e.g. `-- --message 'hi' --thinking high`)"
- ),
- )
- ow.set_defaults(func=_cmd_launch_openclaw)
-
- def _launch_help(args: argparse.Namespace) -> None: # noqa: ARG001
- launch.print_help()
- raise SystemExit(1)
- launch.set_defaults(func=_launch_help)
-
- # -- verify --
- verify = subparsers.add_parser(
- "verify",
- help="Run the proxy + backend e2e checklist (smoke test for users)",
- description=(
- "Run the proxy-only checklist:\n"
- " 1. Resolve credentials\n"
- " 2. Reach backend (GET /models)\n"
- " 3. Probe /v1/messages support (informational)\n"
- " 4. Start proxy on a free port\n"
- " 5. Round-trip a chat completion through the chain\n"
- " 6. Tear down proxy\n\n"
- "Fast (~1-3s on a healthy stack), no extra dependencies. "
- "Suitable for K8s readiness probes and pre-deployment "
- "smoke tests. For harness-driven smoke tests (spawn "
- "claude/codex/openclaw against the proxy), use "
- "`launch {claude,codex,openclaw} --smoke`."
- ),
- formatter_class=argparse.RawDescriptionHelpFormatter,
- )
- verify.add_argument(
- "--model", type=str, default=_DEFAULT_VERIFY_MODEL,
- help=(
- "Model to verify against the backend (default: "
- f"{_DEFAULT_VERIFY_MODEL}, matches the e2e test default)."
- ),
- )
- verify.add_argument(
- "--base-url", type=str, default=None,
- help=(
- "Backend base URL (default: "
- f"{_DEFAULT_OPENROUTER_BASE_URL}, or OPENROUTER_BASE_URL / "
- "NVIDIA_BASE_URL / OPENAI_BASE_URL env var)."
- ),
- )
- verify.add_argument(
- "--api-key", type=str, default=None,
- help=(
- "API key (falls back to OPENROUTER_API_KEY, NVIDIA_API_KEY, "
- "OPENAI_API_KEY, secrets.json). No 'dummy' placeholder fallback "
- "— verify fails fast on a missing key by design."
- ),
- )
- verify.add_argument(
- "--port", type=int, default=None,
- help="Proxy port (default: auto-pick free port)",
- )
- verify.add_argument(
- "--timeout", type=float, default=None,
- help="Request timeout in seconds for the backend LLM client",
- )
- verify.set_defaults(func=_cmd_verify)
-
+ _add_launch_parser(subparsers)
return parser
-# ---------------------------------------------------------------------------
-# Entry point
-# ---------------------------------------------------------------------------
-
-
def main() -> None:
- """Switchyard server CLI."""
+ """Run the Switchyard CLI."""
+
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
)
_quiet_dependency_loggers()
-
parser = _build_parser()
- # Strip the first '--' separator, allowing the canonical form:
- # switchyard --routing-profiles dev.yaml -- launch claude
- # The '--' is purely visual — argparse doesn't need it.
- argv = list(sys.argv[1:])
- # Only strip a '--' that precedes the subcommand token; a '--' after it is
- # the harness separator (e.g. `launch claude ... -- --version`) and must
- # survive so forwarded args reach the launcher instead of tripping argparse.
- # Read the subcommand names off the parser so this can't drift as
- # subcommands are added.
- subparsers_action = next(
- a for a in parser._actions if isinstance(a, argparse._SubParsersAction)
- )
- subcommands = set(subparsers_action.choices)
- sep_idx = argv.index("--") if "--" in argv else len(argv)
- cmd_idx = next((i for i, t in enumerate(argv) if t in subcommands), len(argv))
- if sep_idx < cmd_idx:
- argv.pop(sep_idx)
- args = parser.parse_args(argv)
-
+ args = parser.parse_args()
if not hasattr(args, "func"):
parser.print_help()
raise SystemExit(1)
-
try:
args.func(args)
except RouteBundleConfigError as exc:
- # Route-bundle misconfiguration is normal user error, not a crash:
- # surface the dedicated message as a one-line CLI diagnostic with a
- # non-zero exit instead of letting it propagate as a raw traceback.
raise SystemExit(f"error: invalid route bundle: {exc}") from exc
- except UserConfigError as exc:
- raise SystemExit(f"error: invalid user config: {exc}") from exc
if __name__ == "__main__":
diff --git a/switchyard/cli/tui/__init__.py b/switchyard/cli/tui/__init__.py
deleted file mode 100644
index 87b95894f..000000000
--- a/switchyard/cli/tui/__init__.py
+++ /dev/null
@@ -1,29 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Terminal UI helpers for the Switchyard CLI."""
-
-from switchyard.cli.tui.choice_selector import (
- ChoiceOption,
- ChoiceSelector,
-)
-from switchyard.cli.tui.launch_config_wizard import LaunchConfigWizard
-from switchyard.cli.tui.model_selector import ModelCandidate, ModelSelector
-from switchyard.cli.tui.terminal_capabilities import (
- NO_TUI_ENV_VAR,
- TerminalCapabilities,
- detect_terminal_capabilities,
-)
-from switchyard.cli.tui.tui_session import TuiSession
-
-__all__ = [
- "NO_TUI_ENV_VAR",
- "ChoiceOption",
- "ChoiceSelector",
- "LaunchConfigWizard",
- "ModelCandidate",
- "ModelSelector",
- "TerminalCapabilities",
- "TuiSession",
- "detect_terminal_capabilities",
-]
diff --git a/switchyard/cli/tui/choice_selector.py b/switchyard/cli/tui/choice_selector.py
deleted file mode 100644
index 9b7af166a..000000000
--- a/switchyard/cli/tui/choice_selector.py
+++ /dev/null
@@ -1,55 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Small reusable selector for non-model CLI choices."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from switchyard.cli.tui.model_selector import (
- ModelCandidate,
- ModelSelector,
-)
-from switchyard.cli.tui.tui_session import TuiSession
-
-
-@dataclass(frozen=True)
-class ChoiceOption:
- """One selectable choice in an interactive prompt."""
-
- value: str
- label: str
-
-
-@dataclass(frozen=True)
-class ChoiceSelector:
- """Selector for a short list of named choices."""
-
- title: str
- options: list[ChoiceOption]
- default: str
-
- def select(self, session: TuiSession) -> str:
- label_to_value = {option.label: option.value for option in self.options}
- value_to_label = {option.value: option.label for option in self.options}
- default_label = value_to_label.get(self.default, self.options[0].label)
- selected_label = ModelSelector(
- title=self.title,
- candidates=[
- ModelCandidate(
- model_id=option.label,
- group="default" if option.value == self.default else "available",
- )
- for option in self.options
- ],
- default=default_label,
- allow_manual=False,
- prompt_label=self.title.lower(),
- manual_entry_label="option",
- cycle_label_plural="options",
- ).select(session)
- return label_to_value[selected_label]
-
-
-__all__ = ["ChoiceOption", "ChoiceSelector"]
diff --git a/switchyard/cli/tui/launch_config_wizard.py b/switchyard/cli/tui/launch_config_wizard.py
deleted file mode 100644
index a55e76ddb..000000000
--- a/switchyard/cli/tui/launch_config_wizard.py
+++ /dev/null
@@ -1,103 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Interactive launcher configuration wizard."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from switchyard.cli.tui.choice_selector import (
- ChoiceOption,
- ChoiceSelector,
-)
-from switchyard.cli.tui.model_selector import (
- ModelSelector,
- build_model_candidates,
-)
-from switchyard.cli.tui.tui_session import TuiSession
-
-
-@dataclass(frozen=True)
-class LaunchConfigWizard:
- """Prompt orchestration for provider and per-launcher defaults."""
-
- session: TuiSession
-
- def start(self, *, target: str) -> None:
- self.session.print_header(
- "Switchyard setup",
- f"Configuring {target} defaults. Existing values are preselected.",
- )
-
- def prompt_default_base_url(self, default: str) -> str:
- return self.session.prompt_text("Default base URL", default)
-
- def prompt_default_api_key(
- self,
- existing_api_key: str | None,
- *,
- default_source: str | None = None,
- ) -> str:
- label = "Default API key"
- if existing_api_key and default_source:
- label = f"{label} (default: {default_source})"
- return self.session.prompt_secret(label, existing_api_key)
-
- def select_endpoint_mode(self, label: str, *, default: str) -> str:
- return ChoiceSelector(
- title=f"{label} endpoint",
- options=[
- ChoiceOption(value="default", label="Use default endpoint"),
- ChoiceOption(value="custom", label="Customize endpoint"),
- ],
- default=default,
- ).select(self.session)
-
- def prompt_endpoint_base_url(self, label: str, default: str) -> str:
- return self.session.prompt_text(f"{label} base URL", default)
-
- def prompt_endpoint_api_key(
- self, label: str, existing_api_key: str | None,
- ) -> str:
- return self.session.prompt_secret(f"{label} API key", existing_api_key)
-
- def select_model(
- self,
- label: str,
- *,
- preferred_model_ids: list[str],
- all_model_ids: list[str],
- default: str | None,
- ) -> str:
- return ModelSelector(
- title=f"{label} model",
- candidates=build_model_candidates(
- preferred_model_ids=preferred_model_ids,
- all_model_ids=all_model_ids,
- default=default,
- ),
- default=default,
- allow_manual=True,
- prompt_label=f"{label} model",
- manual_entry_label="model id",
- cycle_label_plural="models",
- ).select(self.session)
-
- def prompt_routing_profiles(self, *, default: str | None) -> str | None:
- """Prompt for an optional routing-profile YAML path.
-
- Used by ``switchyard serve`` and as a fallback for
- ``switchyard launch claude/codex``. Returns ``None`` for an empty
- response or when the user types ``-`` to clear, so the saved
- path is removed rather than persisted as an empty string.
- """
- prompt_label = (
- "Routing-profiles YAML path "
- "(press enter to skip; type '-' to clear)"
- )
- value = self.session.prompt_text(prompt_label, default or "")
- cleaned = value.strip()
- if cleaned == "-" or not cleaned:
- return None
- return cleaned
diff --git a/switchyard/cli/tui/model_selector.py b/switchyard/cli/tui/model_selector.py
deleted file mode 100644
index e26779c83..000000000
--- a/switchyard/cli/tui/model_selector.py
+++ /dev/null
@@ -1,251 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Searchable model selector used by launcher configuration."""
-
-from __future__ import annotations
-
-from collections.abc import Iterable
-from dataclasses import dataclass
-from typing import Literal
-
-from switchyard.cli.tui.tui_session import TuiSession
-
-CandidateGroup = Literal["default", "recommended", "available"]
-
-
-@dataclass(frozen=True)
-class ModelCandidate:
- """One selectable model row."""
-
- model_id: str
- group: CandidateGroup
-
- @property
- def display_group(self) -> str:
- if self.group == "default":
- return "current default"
- if self.group == "recommended":
- return "recommended"
- return "available"
-
-
-def _append_unique(
- output: list[ModelCandidate],
- seen: set[str],
- model_ids: Iterable[str],
- group: CandidateGroup,
-) -> None:
- for model_id in model_ids:
- if model_id in seen:
- continue
- output.append(ModelCandidate(model_id=model_id, group=group))
- seen.add(model_id)
-
-
-def build_model_candidates(
- *,
- preferred_model_ids: Iterable[str],
- all_model_ids: Iterable[str],
- default: str | None,
-) -> list[ModelCandidate]:
- """Return a selector list with defaults first, then ranked suggestions."""
-
- candidates: list[ModelCandidate] = []
- seen: set[str] = set()
- if default:
- _append_unique(candidates, seen, (default,), "default")
- _append_unique(candidates, seen, preferred_model_ids, "recommended")
- _append_unique(candidates, seen, all_model_ids, "available")
- return candidates
-
-
-@dataclass(frozen=True)
-class ModelSelector:
- """Model chooser with prompt-toolkit TUI and plain-terminal fallback."""
-
- title: str
- candidates: list[ModelCandidate]
- default: str | None = None
- allow_manual: bool = True
- prompt_label: str = "model"
- manual_entry_label: str = "model id"
- cycle_label_plural: str = "models"
-
- def _ordered_candidates(self) -> list[ModelCandidate]:
- """Return candidates with the default value first when present."""
-
- ordered: list[ModelCandidate] = []
- seen: set[str] = set()
- if self.default:
- ordered.append(ModelCandidate(model_id=self.default, group="default"))
- seen.add(self.default)
- for candidate in self.candidates:
- if candidate.model_id in seen:
- continue
- ordered.append(candidate)
- seen.add(candidate.model_id)
- return ordered
-
- def filter_candidates(self, query: str) -> list[ModelCandidate]:
- needle = query.strip().lower()
- candidates = self._ordered_candidates()
- if not needle:
- return candidates
- return [
- candidate
- for candidate in candidates
- if needle in candidate.model_id.lower()
- or needle in candidate.display_group.lower()
- ]
-
- def select(self, session: TuiSession) -> str:
- if session.enabled:
- return self._select_with_prompt_toolkit(session)
- return self._select_plain(session)
-
- def _select_plain(self, session: TuiSession) -> str:
- candidates = self._ordered_candidates()
- visible = candidates[:20]
- if visible:
- session.output_fn("")
- session.output_fn(f"{self.title} candidates:")
- for index, candidate in enumerate(visible, start=1):
- marker = " *" if candidate.model_id == self.default else ""
- session.output_fn(
- f" {index}. {candidate.model_id} ({candidate.display_group}){marker}"
- )
- if len(candidates) > len(visible):
- session.output_fn(
- f" ... {len(candidates) - len(visible)} more. "
- f"Type a {self.manual_entry_label} to use one not shown."
- )
-
- suffix = f" [{self.default}]" if self.default else ""
- value = str(
- session.input_fn(
- f"{self.title}{suffix} (number or {self.manual_entry_label}): "
- )
- ).strip()
- if not value:
- if self.default:
- return self.default
- raise SystemExit(f"{self.title} is required.")
- if value.isdigit():
- index = int(value)
- if 1 <= index <= len(visible):
- return visible[index - 1].model_id
- raise SystemExit(f"{self.title} choice {value} is out of range.")
- if not self.allow_manual and value not in {candidate.model_id for candidate in candidates}:
- raise SystemExit(
- f"{self.title} must be one of: "
- f"{', '.join(candidate.model_id for candidate in candidates)}"
- )
- return value
-
- def _select_with_prompt_toolkit(self, session: TuiSession) -> str:
- from prompt_toolkit import prompt # pyright: ignore[reportMissingImports]
- from prompt_toolkit.application.current import ( # pyright: ignore[reportMissingImports]
- get_app,
- )
- from prompt_toolkit.completion import ( # pyright: ignore[reportMissingImports]
- FuzzyWordCompleter,
- )
- from prompt_toolkit.formatted_text import HTML # pyright: ignore[reportMissingImports]
- from prompt_toolkit.key_binding import KeyBindings # pyright: ignore[reportMissingImports]
- from prompt_toolkit.styles import Style # pyright: ignore[reportMissingImports]
-
- style = Style.from_dict({
- "prompt": "bold #76b900",
- "completion-menu.completion": "bg:#1f2937 #d1d5db",
- "completion-menu.completion.current": "bg:#76b900 #111827",
- "completion-menu.meta.completion": "bg:#111827 #9ca3af",
- "bottom-toolbar": "#888888",
- })
- candidates = self._ordered_candidates()
-
- session.output_fn("")
- session.output_fn(f"{self.title}")
- if candidates:
- session.output_fn(
- "Type to filter, use arrow keys to move, enter to select. "
- f"You can paste a {self.manual_entry_label} directly."
- )
- else:
- session.output_fn(
- f"No catalog was discovered. Enter a {self.manual_entry_label}."
- )
-
- meta_by_model = {
- candidate.model_id: candidate.display_group
- for candidate in candidates
- }
- key_bindings = KeyBindings()
-
- def _cycle_next(event: object) -> None:
- buffer = get_app().current_buffer
- if buffer.complete_state:
- buffer.complete_next()
- else:
- buffer.start_completion(select_first=True)
-
- def _cycle_previous(event: object) -> None:
- buffer = get_app().current_buffer
- if buffer.complete_state:
- buffer.complete_previous()
- else:
- buffer.start_completion(select_last=True)
-
- def _accept_selection(event: object) -> None:
- buffer = get_app().current_buffer
- complete_state = buffer.complete_state
- if complete_state and complete_state.current_completion:
- buffer.apply_completion(complete_state.current_completion)
- buffer.validate_and_handle()
-
- key_bindings.add("down")(_cycle_next)
- key_bindings.add("up")(_cycle_previous)
- key_bindings.add("enter")(_accept_selection)
-
- def _open_completion_menu() -> None:
- if candidates:
- get_app().current_buffer.start_completion(select_first=True)
-
- toolbar = (
- f"Up/down cycles {self.cycle_label_plural}. Enter selects. "
- "Type to filter. Ctrl-C cancels."
- )
- if self.default:
- toolbar = f"Default: {self.default} | {toolbar}"
-
- try:
- selected = str(
- prompt(
- HTML(f"<ansigreen><b>{self.prompt_label}</b></ansigreen> "),
- default="",
- accept_default=False,
- completer=FuzzyWordCompleter(
- [candidate.model_id for candidate in candidates],
- meta_dict=meta_by_model,
- ),
- complete_while_typing=True,
- key_bindings=key_bindings,
- pre_run=_open_completion_menu,
- reserve_space_for_menu=12,
- style=style,
- bottom_toolbar=toolbar,
- )
- ).strip()
- except (EOFError, KeyboardInterrupt) as exc:
- raise SystemExit("Setup canceled.") from exc
-
- if not selected:
- if self.default:
- return self.default
- raise SystemExit(f"{self.title} is required.")
- if not self.allow_manual and selected not in meta_by_model:
- raise SystemExit(
- f"{self.title} must be one of: "
- f"{', '.join(candidate.model_id for candidate in candidates)}"
- )
- return selected
diff --git a/switchyard/cli/tui/terminal_capabilities.py b/switchyard/cli/tui/terminal_capabilities.py
deleted file mode 100644
index 8ba95391d..000000000
--- a/switchyard/cli/tui/terminal_capabilities.py
+++ /dev/null
@@ -1,88 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Terminal capability detection for optional interactive TUI flows."""
-
-from __future__ import annotations
-
-import os
-import sys
-from collections.abc import Mapping
-from dataclasses import dataclass
-from typing import Protocol
-
-NO_TUI_ENV_VAR = "SWITCHYARD_NO_TUI"
-
-
-class SupportsIsAtty(Protocol):
- def isatty(self) -> bool:
- ...
-
-
-@dataclass(frozen=True)
-class TerminalCapabilities:
- """Small, testable verdict for interactive terminal features."""
-
- interactive: bool
- color: bool
- tui: bool
- reason: str | None = None
-
-
-def _stream_isatty(stream: SupportsIsAtty) -> bool:
- try:
- return stream.isatty()
- except OSError:
- return False
-
-
-def detect_terminal_capabilities(
- *,
- force_plain: bool = False,
- stdin: SupportsIsAtty | None = None,
- stdout: SupportsIsAtty | None = None,
- environ: Mapping[str, str] | None = None,
-) -> TerminalCapabilities:
- """Return whether the current process can use rich terminal prompts."""
-
- env = environ or os.environ
- if force_plain:
- return TerminalCapabilities(
- interactive=False,
- color=False,
- tui=False,
- reason="plain mode requested",
- )
- if env.get(NO_TUI_ENV_VAR):
- return TerminalCapabilities(
- interactive=False,
- color=False,
- tui=False,
- reason=f"{NO_TUI_ENV_VAR} is set",
- )
-
- effective_stdin = stdin or sys.stdin
- effective_stdout = stdout or sys.stdout
- interactive = _stream_isatty(effective_stdin) and _stream_isatty(effective_stdout)
- if not interactive:
- return TerminalCapabilities(
- interactive=False,
- color=False,
- tui=False,
- reason="stdin/stdout are not both terminals",
- )
-
- term = env.get("TERM", "")
- if term == "dumb":
- return TerminalCapabilities(
- interactive=True,
- color=False,
- tui=False,
- reason="TERM=dumb",
- )
-
- return TerminalCapabilities(
- interactive=True,
- color="NO_COLOR" not in env,
- tui=True,
- )
diff --git a/switchyard/cli/tui/tui_session.py b/switchyard/cli/tui/tui_session.py
deleted file mode 100644
index aa849e6fc..000000000
--- a/switchyard/cli/tui/tui_session.py
+++ /dev/null
@@ -1,111 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Reusable prompt session for Switchyard CLI TUI screens."""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-from dataclasses import dataclass
-
-from switchyard.cli.tui.terminal_capabilities import (
- TerminalCapabilities,
- detect_terminal_capabilities,
-)
-
-InputFn = Callable[[str], str]
-SecretFn = Callable[[str], str]
-OutputFn = Callable[[str], None]
-
-
-def _prompt_toolkit_available() -> bool:
- try:
- import prompt_toolkit # pyright: ignore[reportMissingImports] # noqa: F401
- except ImportError:
- return False
- return True
-
-
-@dataclass(frozen=True)
-class TuiSession:
- """Terminal prompt session shared by current and future CLI screens."""
-
- capabilities: TerminalCapabilities
- input_fn: InputFn
- secret_fn: SecretFn
- output_fn: OutputFn
-
- @classmethod
- def from_current_terminal(
- cls,
- *,
- force_plain: bool,
- input_fn: InputFn,
- secret_fn: SecretFn,
- output_fn: OutputFn,
- ) -> TuiSession:
- return cls(
- capabilities=detect_terminal_capabilities(force_plain=force_plain),
- input_fn=input_fn,
- secret_fn=secret_fn,
- output_fn=output_fn,
- )
-
- @property
- def enabled(self) -> bool:
- """Return whether prompt-toolkit backed TUI prompts should be used."""
-
- return self.capabilities.tui and _prompt_toolkit_available()
-
- def print_header(self, title: str, subtitle: str | None = None) -> None:
- if self.enabled and self.capabilities.color:
- self.output_fn(f"\033[1;32m{title}\033[0m")
- else:
- self.output_fn(title)
- if subtitle:
- self.output_fn(subtitle)
-
- def prompt_text(self, label: str, default: str | None = None) -> str:
- if self.enabled:
- return self._prompt_toolkit_text(label, default=default, is_password=False)
-
- suffix = f" [{default}]" if default else ""
- value = self.input_fn(f"{label}{suffix}: ").strip()
- return value or default or ""
-
- def prompt_secret(self, label: str, default: str | None = None) -> str:
- if self.enabled:
- return self._prompt_toolkit_text(label, default=default, is_password=True)
-
- suffix = " [press enter to keep existing]" if default else ""
- value = self.secret_fn(f"{label}{suffix}: ").strip()
- return value or default or ""
-
- def _prompt_toolkit_text(
- self,
- label: str,
- *,
- default: str | None,
- is_password: bool,
- ) -> str:
- from prompt_toolkit import prompt # pyright: ignore[reportMissingImports]
- from prompt_toolkit.styles import Style # pyright: ignore[reportMissingImports]
-
- prompt_style = Style.from_dict({
- "prompt": "bold #76b900",
- "bottom-toolbar": "#888888",
- })
- try:
- value = str(
- prompt(
- f"{label}: ",
- default=default or "",
- is_password=is_password,
- style=prompt_style,
- bottom_toolbar="Enter to accept the shown default.",
- )
- ).strip()
- except (EOFError, KeyboardInterrupt) as exc:
- raise SystemExit("Setup canceled.") from exc
-
- return value or default or ""
diff --git a/switchyard/server/verify.py b/switchyard/server/verify.py
deleted file mode 100644
index fd06bf9f9..000000000
--- a/switchyard/server/verify.py
+++ /dev/null
@@ -1,1340 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""End-to-end installation verifier for the launchers.
-
-Mirrors the ``launch_claude`` / ``launch_codex`` / ``launch_openclaw``
-flow but, instead of dropping the user into an interactive TUI, runs a
-sequenced checklist and reports pass/fail for each step. Four modes:
-
-* :func:`verify_proxy` — backend + chain only. No harness binary
- needed. Catches credential / network / translation drift in seconds.
-* :func:`verify_claude` — proxy + spawn ``claude -p "..."``. Full
- end-to-end through Claude Code's CLI.
-* :func:`verify_codex` — proxy + spawn ``codex exec "..."``. Full
- end-to-end through Codex's CLI (with the same ``-c`` provider
- overrides ``launch_codex`` uses, so this validates the wire shape too).
-* :func:`verify_openclaw` — proxy + spawn ``openclaw agent --local
- --message ... --json`` against a transient OpenClaw workspace
- identical to ``launch_openclaw``'s, so any drift in the JSON5
- config schema surfaces here. Note ``verify_openclaw`` uses the
- one-shot ``agent`` subcommand because it has to exit cleanly without
- a TTY; ``launch_openclaw`` uses the interactive ``chat`` subcommand.
-
-Designed to double as our offline e2e production gate: a pytest test
-that shells out to ``switchyard verify <mode>`` and asserts
-``returncode == 0`` protects the user-facing UX automatically.
-
-The checklist runner intentionally writes to ``sys.stdout`` rather than
-a logger — verify is *the* command users run to confirm their install,
-and a checklist pinned to print semantics renders cleanly in CI logs,
-plain terminals, and ``capture_output=True`` subprocess captures.
-"""
-
-import asyncio
-import json
-import logging
-import os
-import socket
-import subprocess
-import threading
-import time
-from collections.abc import Callable
-from dataclasses import dataclass, field
-from typing import Any
-
-import httpx
-import uvicorn
-
-from switchyard.cli.launchers.claude_code_launcher import (
- _build_claude_switchyard,
- _find_claude_binary,
-)
-from switchyard.cli.launchers.codex_cli_launcher import (
- _build_switchyard as _build_codex_switchyard,
-)
-from switchyard.cli.launchers.codex_cli_launcher import (
- _find_codex_binary,
- _provider_overrides,
-)
-from switchyard.cli.launchers.openclaw_launcher import (
- _build_switchyard as _build_openclaw_switchyard,
-)
-from switchyard.cli.launchers.openclaw_launcher import (
- _find_openclaw_binary,
- _openclaw_env,
- _openclaw_model_display_name,
- _remove_openclaw_workspace,
- _write_openclaw_workspace,
-)
-from switchyard.lib.backends.backend_format_resolver import (
- probe_anthropic_messages_support,
-)
-from switchyard.lib.route_table import SwitchyardApp
-from switchyard.lib.route_table_builders import build_single_model_table
-from switchyard.lib.stats_accumulator import StatsAccumulator
-from switchyard.server.switchyard_app import build_switchyard_app
-
-logger = logging.getLogger(__name__)
-
-# ---------------------------------------------------------------------------
-# Constants
-# ---------------------------------------------------------------------------
-
-# Same readiness-poll deadline launch_claude / launch_codex use; verify
-# is the same hot path so a divergent timeout would be a footgun.
-_READY_TIMEOUT_S = 10.0
-_SHUTDOWN_JOIN_S = 3.0
-_BACKEND_PROBE_TIMEOUT_S = 10.0
-_ROUNDTRIP_TIMEOUT_S = 60.0
-# Per-harness invocation budget. ``claude -p`` and ``codex exec`` should
-# both finish "say ok" in ~1-3s on a healthy stack; 60s leaves enough
-# headroom for cold-start + slow network without making a hung CI job
-# wait forever.
-_HARNESS_TIMEOUT_S = 60.0
-
-# Single-word reply prompt — deterministic, cheap (one input/output
-# token), and easy to assert on (any non-empty response passes). The
-# explicit "Reply with the single word: ok" phrasing nudges chatty
-# models toward a tight reply.
-_SMOKE_PROMPT = "Reply with the single word: ok"
-
-_EXIT_OK = 0
-_EXIT_FAIL = 1
-_EXIT_BINARY_NOT_FOUND = 127
-
-
-# ---------------------------------------------------------------------------
-# Checklist runner
-# ---------------------------------------------------------------------------
-
-
-@dataclass
-class _VerifyState:
- """Cross-step state bag for the orchestrators.
-
- Promoted to a dataclass instead of a ``dict`` so each field carries
- its own type — the orchestrators are closure-heavy by design (each
- checklist step is a thunk so test mocks stay simple), and a dict
- forces every cross-step pull through a ``cast`` or an ``Any``
- annotation (banned by project policy ``disallow_any_explicit``).
-
- All fields are ``Optional`` because the same bag is reused across
- the three modes — ``codex_bin`` is unset on the claude path,
- ``claude_bin`` is unset on the codex path, and ``server`` /
- ``thread`` / ``port`` are unset until the proxy-start step runs.
- """
-
- server: uvicorn.Server | None = None
- thread: threading.Thread | None = None
- port: int | None = None
- claude_bin: str | None = None
- codex_bin: str | None = None
- openclaw_bin: str | None = None
- openclaw_workspace: str | None = None
-
-
-@dataclass
-class _StepResult:
- """One row in the verify checklist.
-
- ``passed`` doubles as the binary outcome and the determinant of the
- final exit code: any False ⇒ overall FAIL. ``detail`` is the
- success annotation (e.g. "200 OK, 142ms") or the failure reason
- (e.g. "ConnectionError: nodename nor servname provided").
- """
-
- name: str
- passed: bool
- detail: str
- elapsed_ms: float
-
-
-@dataclass
-class _Checklist:
- """Stdout-rendered ``[N/M] step... OK/FAIL`` checklist.
-
- Owns three things:
-
- 1. Step counter — every :meth:`run` call advances it and prints the
- header before the step body executes.
- 2. Result accumulator — :attr:`results` lets callers assemble a
- summary block at the end (counts, total elapsed, mode label).
- 3. Halt-on-fail policy — once a step records ``passed=False``, all
- subsequent :meth:`run` calls become no-ops that record a
- ``"skipped (prior step failed)"`` row. This keeps the output
- readable when the first step fails (no point trying to spawn
- ``claude`` if backend connectivity is down).
- """
-
- title: str
- total: int
- results: list[_StepResult] = field(default_factory=list)
- _idx: int = 0
- _halted: bool = False
-
- def _emit(self, line: str) -> None:
- # Single ``print`` per line so subprocess capture stays
- # well-ordered. ``flush=True`` forces output even when the
- # caller has buffered stdout (pytest's ``-s`` redirected
- # captures, etc.).
- print(line, flush=True)
-
- def run(self, name: str, body: Callable[[], str]) -> _StepResult:
- """Execute one step and record / print its outcome.
-
- ``body`` is a thunk that returns a detail string on success and
- raises any exception on failure (the exception's class name +
- message become the failure detail). Returning a non-string is
- tolerated and coerced to ``str()``.
- """
- self._idx += 1
- self._emit(f"[{self._idx}/{self.total}] {name}...")
-
- if self._halted:
- result = _StepResult(
- name=name,
- passed=False,
- detail="skipped (prior step failed)",
- elapsed_ms=0.0,
- )
- self.results.append(result)
- self._emit(f" SKIP {result.detail}")
- return result
-
- start = time.monotonic()
- try:
- detail = body()
- except Exception as e:
- elapsed_ms = (time.monotonic() - start) * 1000.0
- reason = f"{type(e).__name__}: {e}"
- result = _StepResult(
- name=name, passed=False, detail=reason, elapsed_ms=elapsed_ms,
- )
- self.results.append(result)
- self._emit(f" FAIL ({reason}, {elapsed_ms:.0f}ms)")
- self._halted = True
- return result
-
- elapsed_ms = (time.monotonic() - start) * 1000.0
- result = _StepResult(
- name=name, passed=True, detail=str(detail), elapsed_ms=elapsed_ms,
- )
- self.results.append(result)
- # Empty-detail steps (e.g. "Tearing down proxy") get just OK + ms;
- # filled-in details get the annotation in parens.
- if detail:
- self._emit(f" OK ({detail}, {elapsed_ms:.0f}ms)")
- else:
- self._emit(f" OK ({elapsed_ms:.0f}ms)")
- return result
-
- def summarize(self, mode: str, model: str, total_elapsed_ms: float) -> int:
- """Print the final ``verify <mode>: PASS/FAIL`` line and return exit code.
-
- Halt-injected SKIP rows count as failures for the exit code;
- the user already saw the FAIL that triggered the halt, so the
- summary just reports overall pass/fail without re-listing the
- skips.
- """
- passed = all(r.passed for r in self.results)
- verdict = "PASS" if passed else "FAIL"
- self._emit("")
- self._emit(
- f"verify {mode}: {verdict} (model={model}, {total_elapsed_ms:.0f}ms)"
- )
- return _EXIT_OK if passed else _EXIT_FAIL
-
-
-# ---------------------------------------------------------------------------
-# Local helpers (duplicated from launch_*.py — trivial, intentional)
-# ---------------------------------------------------------------------------
-
-
-def _find_free_port() -> int:
- """Bind to ``127.0.0.1:0``, let the OS pick, return the chosen port.
-
- Duplicated from ``launch_claude._find_free_port`` per the same
- "deliberate near-duplicate" pattern the launchers themselves use —
- keeps verify independent of any private symbol there so the
- launcher path stays untouched as a hot-fix concern.
- """
- with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
- s.bind(("127.0.0.1", 0))
- port: int = s.getsockname()[1]
- return port
-
-
-def _wait_ready(server: uvicorn.Server, timeout_s: float = _READY_TIMEOUT_S) -> bool:
- """Poll ``server.started`` until True or the timeout elapses."""
- deadline = time.monotonic() + timeout_s
- while time.monotonic() < deadline:
- if server.started:
- return True
- time.sleep(0.05)
- return False
-
-
-def _spawn_proxy_thread(
- switchyard: SwitchyardApp,
- port: int,
-) -> tuple[uvicorn.Server, threading.Thread]:
- """Run uvicorn in a background daemon thread, return (server, thread).
-
- ``log_level="critical"`` is intentional — verify is a structured
- checklist and any uvicorn output that interleaves with the
- checklist breaks the layout. In particular, ``force_exit=True``
- during :func:`_teardown` cancels in-flight lifespan handlers,
- which uvicorn surfaces as an ``asyncio.CancelledError`` traceback
- at ERROR level. That traceback is harmless (graceful-shutdown
- path) but visually noisy; CRITICAL hides it without suppressing
- real chain failures (those propagate through the HTTP response,
- not uvicorn's loggers). ``log_config=None`` keeps uvicorn from
- overwriting the level we already set in
- :func:`_silence_chatty_loggers`.
- """
- app = build_switchyard_app(switchyard)
- config = uvicorn.Config(
- app,
- host="127.0.0.1",
- port=port,
- log_level="critical",
- log_config=None,
- )
- server = uvicorn.Server(config)
- thread = threading.Thread(
- target=server.run, name="verify-proxy", daemon=True,
- )
- thread.start()
- return server, thread
-
-
-# ---------------------------------------------------------------------------
-# Step bodies
-# ---------------------------------------------------------------------------
-
-
-def _check_credentials(
- api_key: str | None,
- base_url: str | None,
- key_source: str | None = None,
-) -> str:
- """Step body: validate that resolution produced something usable.
-
- ``base_url`` is allowed to be empty — the launchers fall through to
- the OpenAI SDK default. ``api_key`` is required because every
- backend we ship against demands one; failing here saves a 401
- later.
-
- ``key_source`` (e.g. ``"$OPENROUTER_API_KEY"`` or
- ``"secrets.json[openrouter]"``) is an optional human label that says
- *where* the key came from. Surfaced in the step's success detail
- so the user knows which source they're verifying — and so the
- backend-reach step can name the source in a 401 hint without
- re-doing the resolution itself.
- """
- if not api_key:
- raise RuntimeError(
- "no API key resolved (set --api-key, OPENROUTER_API_KEY, "
- "NVIDIA_API_KEY, OPENAI_API_KEY, or secrets/secrets.json)"
- )
- base_url_label = base_url or "<openai default>"
- source_suffix = f" from {key_source}" if key_source else ""
- return f"api_key=*****{source_suffix}, base_url={base_url_label}"
-
-
-def _check_backend_reachable(
- base_url: str,
- api_key: str,
- key_source: str | None = None,
-) -> str:
- """Step body: HTTP GET ``{base_url}/models`` with the user's key.
-
- Picks ``/models`` because it's the cheapest authenticated endpoint
- every OpenAI-compatible backend exposes — it doesn't consume
- tokens, it doesn't require a request body, and the response shape
- is tiny.
-
- Status-code branches surface actionable hints rather than a bare
- ``"HTTP <code>"``:
-
- * ``200`` → success.
- * ``401`` → key was rejected. This is the most common
- "credential failure" case once a key has been resolved; we name
- the source (``key_source``, e.g. ``$OPENROUTER_API_KEY``) so the
- user knows exactly which variable / file to fix, and call out
- that the backend itself rejected the key (vs. the proxy or a
- network issue). ``key_source`` falls back to a generic
- ``"the resolved key"`` label when the caller didn't track it.
- * ``404`` → ``/models`` route missing. Almost always a
- ``--base-url`` typo — surface that hypothesis directly so the
- user looks at the URL, not the key.
- * other 4xx / 5xx → generic, with the status code in the
- message so a follow-up curl is one ``grep`` away.
-
- A 4xx still counts as "backend reachable" structurally — the TCP
- handshake completed and the server replied — but verify reports
- it as a failure because the user almost certainly cares about
- "backend reachable AND responds successfully".
- """
- url = f"{base_url.rstrip('/')}/models"
- headers = {"Authorization": f"Bearer {api_key}"}
- start = time.monotonic()
- with httpx.Client(timeout=_BACKEND_PROBE_TIMEOUT_S) as client:
- resp = client.get(url, headers=headers)
- elapsed_ms = (time.monotonic() - start) * 1000.0
- if resp.status_code == 200:
- return f"GET /models 200, {elapsed_ms:.0f}ms"
-
- source_label = key_source or "the resolved key"
- if resp.status_code == 401:
- raise RuntimeError(
- f"HTTP 401 — the backend rejected {source_label}. "
- f"The key resolved successfully but is invalid, expired, "
- f"or doesn't have access to {url}. Double-check {source_label} "
- f"or rotate it."
- )
- if resp.status_code == 404:
- raise RuntimeError(
- f"HTTP 404 — {url} not found. Likely a --base-url / "
- f"OPENROUTER_BASE_URL / NVIDIA_BASE_URL / OPENAI_BASE_URL typo (the path should "
- f"end in /v1).",
- )
- raise RuntimeError(
- f"GET {url} returned HTTP {resp.status_code}"
- )
-
-
-async def _check_anthropic_probe(base_url: str, api_key: str) -> str:
- """Step body: probe whether the upstream speaks ``/v1/messages`` natively.
-
- Outcome is informational: we want the user to know which chain
- they'll get (native passthrough vs OpenAI translation) so the rest
- of the diagnostics make sense. A False result isn't a failure —
- it's the documented fallback.
- """
- is_native = await probe_anthropic_messages_support(
- base_url=base_url, api_key=api_key,
- )
- return (
- "native passthrough"
- if is_native
- else "translation (backend lacks /v1/messages)"
- )
-
-
-def _start_proxy(
- switchyard: SwitchyardApp, port: int | None,
-) -> tuple[uvicorn.Server, threading.Thread, int]:
- """Step helper: spin up a proxy and wait for ``server.started``.
-
- Returns ``(server, thread, resolved_port)`` so the caller can hold
- the lifecycle handles for the round-trip + teardown steps. Raises
- on readiness timeout — the runner converts that to a FAIL row.
- """
- resolved = port if port is not None else _find_free_port()
- server, thread = _spawn_proxy_thread(switchyard, resolved)
- if not _wait_ready(server):
- # Best-effort teardown so we don't leak a half-started uvicorn.
- server.should_exit = True
- thread.join(timeout=_SHUTDOWN_JOIN_S)
- raise RuntimeError(
- f"proxy did not become ready within {_READY_TIMEOUT_S:.1f}s"
- )
- return server, thread, resolved
-
-
-def _proxy_roundtrip(port: int, model: str) -> str:
- """Step body: send one ``/v1/chat/completions`` request through the proxy.
-
- Picks Chat Completions (not Responses, not Anthropic Messages)
- because every chain we build serves it as the canonical
- inbound, and the response shape is the smallest of the three.
-
- Verify's contract is *"did the chain correctly translate, forward,
- and return a structurally valid response?"* — not *"did the model
- say something specific?"* — so the assertions are:
-
- * HTTP 200
- * Response has ``choices`` and ``usage`` (chain plumbed both ends)
- * Generation actually happened (``completion_tokens > 0``)
- * Visible text *is* surfaced when the model produced any —
- ``content`` becomes the reply preview in the success line
-
- Reasoning-only truncation is treated as a pass: models like
- ``nvidia/qwen/qwen3.5-*`` and the GPT-5-reasoning family
- consume their entire output-token budget on internal reasoning
- when the budget is small, and the visible-text block comes back
- empty. The chain still worked end-to-end (200 + usage + non-zero
- output tokens), so we report the result with a
- ``"no visible text (reasoning-only)"`` annotation rather than
- failing. Earlier production e2e suites
- (``test_passthrough_anthropic_e2e.py``) already adopted this
- forgiveness pattern; verify follows it for consistency.
-
- ``max_tokens=2048`` is large enough that most non-reasoning
- models will surface visible text, but small enough that the
- one-line smoke prompt can't burn meaningful cost even on
- pricier backends.
- """
- url = f"http://127.0.0.1:{port}/v1/chat/completions"
- body = {
- "model": model,
- "messages": [{"role": "user", "content": _SMOKE_PROMPT}],
- "max_tokens": 2048,
- }
- start = time.monotonic()
- # Loopback probe to our own in-process proxy — bypass env proxies so a
- # configured HTTP_PROXY doesn't intercept the 127.0.0.1 request.
- with httpx.Client(timeout=_ROUNDTRIP_TIMEOUT_S, trust_env=False) as client:
- resp = client.post(url, json=body)
- elapsed_ms = (time.monotonic() - start) * 1000.0
- if resp.status_code != 200:
- # Show a snippet of the body to help debug (NVIDIA error
- # responses usually carry a JSON ``message`` field worth
- # surfacing). Truncate aggressively to keep output readable.
- snippet = resp.text[:200].replace("\n", " ")
- raise RuntimeError(
- f"POST {url} returned HTTP {resp.status_code}: {snippet}"
- )
- data = resp.json()
-
- choices = data.get("choices") or []
- if not choices:
- raise RuntimeError(
- f"chat completion returned no choices; "
- f"response.keys={list(data.keys())}"
- )
-
- usage = data.get("usage") or {}
- in_toks = usage.get("prompt_tokens", 0)
- out_toks = usage.get("completion_tokens", 0)
- if not out_toks:
- # Zero output tokens means the model didn't generate
- # anything — that's a real chain or upstream issue worth
- # surfacing as a failure (vs the reasoning-truncation case
- # below where output tokens *did* get generated, just not
- # surfaced as text).
- raise RuntimeError(
- f"chat completion produced no output tokens; usage={usage}"
- )
-
- content = (choices[0].get("message", {}).get("content") or "").strip()
- if content:
- reply_preview = content[:40].replace("\n", " ")
- return (
- f"reply={reply_preview!r}, {elapsed_ms:.0f}ms, "
- f"in={in_toks} out={out_toks} tokens"
- )
-
- # Reasoning-only truncation: the chain worked, the model
- # generated tokens, but they were all internal reasoning that
- # didn't surface as visible text. Show the finish_reason so
- # the user sees the cause rather than a mysterious "no text"
- # success.
- finish_reason = choices[0].get("finish_reason", "?")
- return (
- f"no visible text (finish_reason={finish_reason}, reasoning-only), "
- f"{elapsed_ms:.0f}ms, in={in_toks} out={out_toks} tokens"
- )
-
-
-def _locate_claude() -> str:
- """Step body: find the ``claude`` binary or raise.
-
- Reuses :func:`launch_claude._find_claude_binary` so the search
- paths stay in lockstep with the actual launcher (otherwise verify
- could pass while launch fails, or vice versa, which is the worst
- possible outcome for a "did I install everything correctly"
- check).
- """
- bin_path = _find_claude_binary()
- if bin_path is None:
- raise RuntimeError(
- "claude binary not found on PATH or in known fallback "
- "locations (~/.claude/local/claude, ~/.local/bin/claude). "
- "Install with `curl -fsSL https://claude.ai/install.sh | bash`"
- )
- return bin_path
-
-
-def _locate_codex() -> str:
- """Step body: find the ``codex`` binary or raise.
-
- Sibling of :func:`_locate_claude` for the codex path — same
- "search paths must match the launcher" argument.
- """
- bin_path = _find_codex_binary()
- if bin_path is None:
- raise RuntimeError(
- "codex binary not found on PATH or in known fallback "
- "locations (~/.npm-global/bin/codex, ~/.local/bin/codex). "
- "Install with `npm install -g @openai/codex`"
- )
- return bin_path
-
-
-def _locate_openclaw() -> str:
- """Step body: find the ``openclaw`` binary or raise.
-
- Sibling of :func:`_locate_codex` for the openclaw path — same
- "search paths must match the launcher" argument.
- """
- bin_path = _find_openclaw_binary()
- if bin_path is None:
- raise RuntimeError(
- "openclaw binary not found on PATH or in known fallback "
- "locations (~/.npm-global/bin/openclaw, ~/.local/bin/openclaw, "
- "~/.nvm/versions/node/*/bin/openclaw). "
- "Install with `npm install -g openclaw@latest`"
- )
- return bin_path
-
-
-def _run_claude_prompt(claude_bin: str, port: int, model: str) -> str:
- """Step body: spawn ``claude -p "..."`` against the proxy, capture output.
-
- Uses the same env-injection contract as ``launch_claude``
- (``ANTHROPIC_BASE_URL`` / ``ANTHROPIC_AUTH_TOKEN`` /
- ``ANTHROPIC_API_KEY=""`` / ``ANTHROPIC_MODEL`` /
- ``ANTHROPIC_SMALL_FAST_MODEL``) so any drift in that contract
- surfaces here rather than in production.
-
- Flags:
- ``-p`` non-interactive prompt mode
- ``--output-format json`` structured envelope so we can
- distinguish "empty result"
- (reasoning truncation, OK)
- from "missing result"
- (real failure)
- ``--max-turns 1`` one round-trip only — verify
- isn't testing agentic loops
- ``--dangerously-skip-permissions`` required for non-interactive
- so claude doesn't block on a
- permission prompt that has no
- stdin to answer it
-
- The JSON envelope is the contract: claude prints a single
- ``{"type": "result", ..., "result": "..."}`` object on stdout.
- We treat:
-
- * ``returncode != 0`` → real failure (claude or the chain blew up)
- * exit 0, valid JSON, ``result`` non-empty → success with a reply
- preview
- * exit 0, valid JSON, ``result`` empty/missing → reasoning-only
- truncation (same forgiveness as :func:`_proxy_roundtrip` —
- surface ``num_turns`` / ``stop_reason`` if present so the user
- sees the cause)
- * exit 0 but stdout isn't valid JSON → real failure (claude
- changed its envelope shape, or something corrupted stdout)
- """
- env_overrides = {
- "ANTHROPIC_BASE_URL": f"http://127.0.0.1:{port}",
- "ANTHROPIC_AUTH_TOKEN": "switchyard",
- "ANTHROPIC_API_KEY": "",
- "ANTHROPIC_MODEL": model,
- "ANTHROPIC_SMALL_FAST_MODEL": model,
- }
- env = os.environ.copy()
- env.update(env_overrides)
-
- cmd = [
- claude_bin, "-p", _SMOKE_PROMPT,
- "--output-format", "json",
- "--max-turns", "1",
- "--dangerously-skip-permissions",
- ]
-
- start = time.monotonic()
- try:
- proc = subprocess.run(
- cmd, env=env, capture_output=True, text=True,
- timeout=_HARNESS_TIMEOUT_S, check=False,
- )
- except subprocess.TimeoutExpired as e:
- raise RuntimeError(
- f"claude did not exit within {_HARNESS_TIMEOUT_S:.0f}s"
- ) from e
- elapsed_ms = (time.monotonic() - start) * 1000.0
-
- if proc.returncode != 0:
- stderr_snippet = (proc.stderr or "").strip()[:200].replace("\n", " ")
- raise RuntimeError(
- f"claude exited {proc.returncode}: {stderr_snippet}"
- )
-
- stdout = (proc.stdout or "").strip()
- if not stdout:
- raise RuntimeError(
- "claude exited 0 but produced no stdout (expected JSON envelope)"
- )
-
- # Parse the envelope. A 0-exit with non-JSON stdout means
- # claude's output contract changed under us — surface that as
- # a real failure rather than ignoring the malformed body.
- try:
- envelope = json.loads(stdout)
- except json.JSONDecodeError as e:
- snippet = stdout[:200].replace("\n", " ")
- raise RuntimeError(
- f"claude produced non-JSON stdout: {snippet} ({e})"
- ) from e
-
- if not isinstance(envelope, dict):
- raise RuntimeError(
- f"claude JSON envelope wasn't an object: {type(envelope).__name__}"
- )
-
- result_text = envelope.get("result") or ""
- if isinstance(result_text, str):
- result_text = result_text.strip()
- else:
- # ``result`` exists but isn't a string — pre-2.x claude
- # used a list of content blocks; the contract drift is
- # worth surfacing rather than coercing.
- raise RuntimeError(
- f"claude 'result' field had unexpected type: {type(result_text).__name__}"
- )
-
- if result_text:
- preview = result_text[:40].replace("\n", " ")
- return f"reply={preview!r}, {elapsed_ms:.0f}ms"
-
- # Reasoning-only truncation case — the chain worked end-to-end
- # (claude got a response) but the model's visible-text block was
- # empty. Same forgiveness as :func:`_proxy_roundtrip`: report
- # what we *do* know (envelope fields claude surfaces) so the user
- # sees this is a model-budget artifact, not a chain bug.
- num_turns = envelope.get("num_turns", "?")
- stop_reason = (
- envelope.get("stop_reason")
- or envelope.get("subtype")
- or "?"
- )
- return (
- f"no visible reply (num_turns={num_turns}, stop_reason={stop_reason}, "
- f"reasoning-only), {elapsed_ms:.0f}ms"
- )
-
-
-def _run_openclaw_prompt(
- openclaw_bin: str,
- workspace: str,
- model: str,
-) -> str:
- """Step body: spawn ``openclaw agent`` against the proxy with a smoke prompt.
-
- Uses the same env-injection contract as ``launch_openclaw`` —
- ``OPENCLAW_STATE_DIR`` / ``OPENCLAW_HOME`` / ``OPENCLAW_CONFIG_PATH``
- point openclaw at a transient workspace with a ``models.providers.
- switchyard`` block declaring the proxy as a custom provider, and
- ``SWITCHYARD_API_KEY`` is set to the opaque placeholder the JSON5
- config references.
-
- ``openclaw agent`` is a non-interactive one-shot turn (``--local``
- binds it to the embedded agent runtime that reads our transient
- ``openclaw.json``). Flags:
-
- * ``--message`` — the smoke prompt. Required: ``openclaw agent``
- refuses to read from stdin.
- * ``--session-key`` — required session selector. We use a
- per-PID smoke key so concurrent verifies don't collide.
- * ``--json`` — emit a structured envelope to stdout so we can pull
- ``finalAssistantVisibleText`` deterministically.
-
- Outcome handling matches :func:`_run_codex_prompt`:
-
- * exit non-zero → real failure (openclaw or the chain blew up);
- include stderr snippet
- * exit 0 + non-empty visible reply → success with reply preview
- * exit 0 + empty ``finalAssistantVisibleText`` → reasoning-only
- truncation (same forgiveness as the codex / proxy-roundtrip
- steps).
- """
- env = _openclaw_env(workspace=workspace)
- session_key = f"smoke-{os.getpid()}-{int(time.time())}"
- cmd = [
- openclaw_bin,
- "agent",
- "--local",
- "--session-key", session_key,
- "--message", _SMOKE_PROMPT,
- "--json",
- ]
-
- start = time.monotonic()
- try:
- proc = subprocess.run(
- cmd, env=env, capture_output=True, text=True,
- timeout=_HARNESS_TIMEOUT_S, check=False,
- )
- except subprocess.TimeoutExpired as e:
- raise RuntimeError(
- f"openclaw did not exit within {_HARNESS_TIMEOUT_S:.0f}s"
- ) from e
- elapsed_ms = (time.monotonic() - start) * 1000.0
-
- if proc.returncode != 0:
- stderr_snippet = (proc.stderr or "").strip()[:200].replace("\n", " ")
- raise RuntimeError(
- f"openclaw exited {proc.returncode}: {stderr_snippet}"
- )
-
- reply = _extract_openclaw_visible_text(proc.stdout or "")
- if reply:
- preview = reply[:40].replace("\n", " ")
- return (
- f"reply={preview!r}, model={_openclaw_model_display_name(model)}, "
- f"{elapsed_ms:.0f}ms"
- )
-
- # Reasoning-only / no visible-text reply.
- return (
- f"no visible reply (openclaw exited 0 with empty "
- f"finalAssistantVisibleText, reasoning-only), {elapsed_ms:.0f}ms"
- )
-
-
-def _extract_openclaw_visible_text(stdout: str) -> str:
- """Pull the assistant's user-visible reply out of ``openclaw agent --json``.
-
- The envelope schema has shifted between openclaw releases — the
- visible reply has lived at the top level and nested under wrapper
- keys like ``data`` / ``result`` in different versions. We walk the
- JSON depth-first for the first ``finalAssistantVisibleText`` key,
- then fall back to ``finalAssistantRawText`` if the visible text was
- suppressed (for instance, when openclaw stripped a thinking tag).
-
- Returns ``""`` when JSON parsing fails, when the key isn't found,
- or when the matched value is whitespace-only. Callers map ``""``
- to the reasoning-only / empty-reply branch.
- """
- text = stdout.strip()
- if not text:
- return ""
- try:
- payload = json.loads(text)
- except json.JSONDecodeError:
- # Plain-text fallback for an openclaw release that prints
- # something non-JSON under --json (or an error preamble before
- # the envelope). Treat the whole stdout as the preview so we
- # still surface something.
- return text
- for key in ("finalAssistantVisibleText", "finalAssistantRawText"):
- found = _find_first_key(payload, key)
- if isinstance(found, str) and found.strip():
- return found.strip()
- return ""
-
-
-def _find_first_key(payload: Any, target: str) -> Any:
- """Depth-first lookup of ``target`` in nested dicts and lists.
-
- Returns the first match's value, or ``None`` if not found.
- """
- if isinstance(payload, dict):
- if target in payload:
- return payload[target]
- for value in payload.values():
- found = _find_first_key(value, target)
- if found is not None:
- return found
- elif isinstance(payload, list):
- for item in payload:
- found = _find_first_key(item, target)
- if found is not None:
- return found
- return None
-
-
-def _run_codex_prompt(codex_bin: str, port: int, model: str) -> str:
- """Step body: spawn ``codex exec "..."`` against the proxy.
-
- Uses the same six ``-c`` provider-config overrides as
- ``launch_codex`` (via :func:`_provider_overrides`) so any wire-
- contract drift caught here matches what the launcher would hit.
-
- Flags:
- ``exec <prompt>`` codex's non-interactive subcommand
- ``-m <model>`` pin the model on the codex side (status line
- display); the proxy's request processor
- rewrites it as a safety net.
-
- Codex's ``exec`` mode requires ``OPENAI_API_KEY`` to be set per
- its provider-config validation — value is opaque (proxy injects
- the real upstream credential at call time).
-
- Outcome handling matches :func:`_run_claude_prompt`:
-
- * exit non-zero → real failure (codex or the chain blew up);
- include stderr snippet
- * exit 0 + non-empty stdout → success with reply preview
- * exit 0 + empty stdout → reasoning-only truncation (same
- forgiveness as the claude / proxy-roundtrip steps). Codex's
- ``exec`` mode doesn't emit a structured envelope we can
- inspect for ``num_turns`` / ``stop_reason``, so we don't get
- to be as precise as ``_run_claude_prompt`` here — but
- tolerating the empty case keeps reasoning-model verifies
- passing instead of false-failing.
- """
- overrides = _provider_overrides(port)
-
- env = os.environ.copy()
- env["OPENAI_API_KEY"] = "switchyard"
-
- cmd = [codex_bin, *overrides, "-m", model, "exec", _SMOKE_PROMPT]
-
- start = time.monotonic()
- try:
- proc = subprocess.run(
- cmd, env=env, capture_output=True, text=True,
- timeout=_HARNESS_TIMEOUT_S, check=False,
- )
- except subprocess.TimeoutExpired as e:
- raise RuntimeError(
- f"codex did not exit within {_HARNESS_TIMEOUT_S:.0f}s"
- ) from e
- elapsed_ms = (time.monotonic() - start) * 1000.0
-
- if proc.returncode != 0:
- stderr_snippet = (proc.stderr or "").strip()[:200].replace("\n", " ")
- raise RuntimeError(
- f"codex exited {proc.returncode}: {stderr_snippet}"
- )
- stdout = (proc.stdout or "").strip()
- if stdout:
- preview = stdout[:40].replace("\n", " ")
- return f"reply={preview!r}, {elapsed_ms:.0f}ms"
-
- # Reasoning-only truncation case. See :func:`_run_claude_prompt`
- # for the broader rationale; codex doesn't expose ``num_turns``
- # or ``stop_reason`` on stdout in ``exec`` mode, so the
- # annotation is sparser.
- return (
- f"no visible reply (codex exited 0 with empty stdout, "
- f"reasoning-only), {elapsed_ms:.0f}ms"
- )
-
-
-def _teardown(server: uvicorn.Server, thread: threading.Thread) -> str:
- """Step body: signal uvicorn to exit, join the thread.
-
- Sets both ``should_exit`` (graceful) and ``force_exit`` (drop
- in-flight connections) because uvicorn's default
- ``timeout_graceful_shutdown=None`` blocks shutdown until every
- keep-alive connection closes, and clients like Claude Code can
- leave a connection lingering after the response stream
- completes. Without ``force_exit`` the join here would hang for
- minutes on a streaming workload.
-
- A timed-out join is reported as an OK with a "shutdown slow"
- annotation, *not* a failure: the proxy thread is a daemon, so it
- dies when the verify process exits regardless. Failing here
- would mask the meaningful signal (the rest of the chain worked
- end-to-end) behind a uvicorn shutdown quirk that doesn't affect
- a single-shot CLI. A genuinely-stuck shutdown still surfaces in
- the annotation so a developer scanning verify output sees it.
- """
- server.should_exit = True
- server.force_exit = True
- thread.join(timeout=_SHUTDOWN_JOIN_S)
- if thread.is_alive():
- return (
- f"shutdown slow (>{_SHUTDOWN_JOIN_S:.1f}s, daemon thread will "
- f"exit when verify process does)"
- )
- return ""
-
-
-# ---------------------------------------------------------------------------
-# Mode orchestrators
-# ---------------------------------------------------------------------------
-
-
-def _silence_chatty_loggers() -> None:
- """Quiet down dependency loggers so the checklist stays readable.
-
- Two tiers:
-
- * WARNING for ``switchyard`` / ``httpx`` / ``openai`` /
- ``anthropic`` — same as the launchers, keeps INFO chatter out
- of the user's checklist while letting WARNING / ERROR surface
- real problems (probe timeout, upstream 5xx, etc).
-
- * CRITICAL for ``uvicorn*`` / ``starlette*`` — strictly
- noisier. When ``force_exit=True`` cancels in-flight lifespan
- handlers during teardown, starlette / uvicorn log a
- ``CancelledError`` traceback at ERROR level even though it's
- a normal part of the shutdown path and harmless to verify's
- contract. Bumping to CRITICAL hides that traceback without
- hiding genuine HTTP / framework errors during the active
- steps (those propagate via the chain itself, not the server's
- own loggers). The launchers don't need this because they
- run uvicorn for the lifetime of the parent process — the
- shutdown only fires on process exit, where stderr noise
- doesn't matter.
- """
- for noisy in ("switchyard", "httpx", "openai", "anthropic"):
- logging.getLogger(noisy).setLevel(logging.WARNING)
- for very_noisy in (
- "uvicorn", "uvicorn.access", "uvicorn.error",
- "starlette", "starlette.routing",
- ):
- logging.getLogger(very_noisy).setLevel(logging.CRITICAL)
-
-
-def verify_proxy(
- *,
- model: str,
- base_url: str,
- api_key: str,
- port: int | None = None,
- timeout: float | None = None,
- key_source: str | None = None,
-) -> int:
- """Run the proxy-only verify checklist; return exit code.
-
- Six steps:
-
- 1. Resolve credentials
- 2. Reach backend
- 3. Probe ``/v1/messages`` (informational)
- 4. Start proxy
- 5. Round-trip a chat completion through the chain
- 6. Tear down proxy
-
- Designed to be the cheapest possible "is my install good?" check
- — no harness binary needed, just credentials + network + the
- proxy thread. Fast enough to run as a K8s readiness probe.
-
- ``key_source`` is an optional human label naming where the
- ``api_key`` came from (e.g. ``"$OPENROUTER_API_KEY"`` or
- ``"secrets.json[openrouter]"``). Surfaced in step 1's success
- annotation and in step 2's 401 hint so a credential mishap names
- the exact knob the user has to turn.
- """
- _silence_chatty_loggers()
- overall_start = time.monotonic()
- checklist = _Checklist(title="verify proxy", total=6)
-
- checklist.run(
- "Resolving credentials",
- lambda: _check_credentials(api_key, base_url, key_source),
- )
- checklist.run(
- "Reaching backend",
- lambda: _check_backend_reachable(base_url, api_key, key_source),
- )
- checklist.run(
- "Probing /v1/messages support",
- lambda: asyncio.run(_check_anthropic_probe(base_url, api_key)),
- )
-
- # Steps 4-6 share the proxy lifecycle through ``state`` — each
- # step is a closure so it can mutate dataclass fields without
- # ``nonlocal``. Closures-as-step-bodies is the design: keeps the
- # checklist runner generic and the test mocks simple.
- state = _VerifyState()
-
- def _start() -> str:
- switchyard = _build_claude_switchyard(
- model=model,
- api_key=api_key,
- base_url=base_url,
- timeout=timeout,
- stats=StatsAccumulator(),
- )
- server, thread, resolved_port = _start_proxy(switchyard, port)
- state.server = server
- state.thread = thread
- state.port = resolved_port
- return f"127.0.0.1:{resolved_port}"
-
- checklist.run("Starting proxy", _start)
-
- def _roundtrip() -> str:
- assert state.port is not None # set by _start; halt-on-fail prevents reaching here otherwise
- return _proxy_roundtrip(state.port, model)
-
- checklist.run("Round-tripping chat completion", _roundtrip)
-
- def _shutdown() -> str:
- if state.server is None or state.thread is None:
- return "(no proxy started)"
- return _teardown(state.server, state.thread)
-
- checklist.run("Tearing down proxy", _shutdown)
-
- total_ms = (time.monotonic() - overall_start) * 1000.0
- return checklist.summarize("proxy", model, total_ms)
-
-
-def verify_claude(
- *,
- model: str,
- base_url: str,
- api_key: str,
- port: int | None = None,
- timeout: float | None = None,
- key_source: str | None = None,
-) -> int:
- """Run the full ``claude`` e2e verify checklist; return exit code.
-
- Eight steps — the proxy-mode six plus the harness-specific two
- (locate binary + spawn-and-validate).
-
- See :func:`verify_proxy` for the ``key_source`` contract.
- """
- _silence_chatty_loggers()
- overall_start = time.monotonic()
- checklist = _Checklist(title="verify claude", total=8)
-
- checklist.run(
- "Resolving credentials",
- lambda: _check_credentials(api_key, base_url, key_source),
- )
- checklist.run(
- "Reaching backend",
- lambda: _check_backend_reachable(base_url, api_key, key_source),
- )
- checklist.run(
- "Probing /v1/messages support",
- lambda: asyncio.run(_check_anthropic_probe(base_url, api_key)),
- )
-
- state = _VerifyState()
-
- def _start() -> str:
- switchyard = _build_claude_switchyard(
- model=model,
- api_key=api_key,
- base_url=base_url,
- timeout=timeout,
- stats=StatsAccumulator(),
- )
- server, thread, resolved_port = _start_proxy(switchyard, port)
- state.server = server
- state.thread = thread
- state.port = resolved_port
- return f"127.0.0.1:{resolved_port}"
-
- checklist.run("Starting proxy", _start)
-
- def _locate() -> str:
- bin_path = _locate_claude()
- state.claude_bin = bin_path
- return bin_path
-
- checklist.run("Locating claude binary", _locate)
-
- def _roundtrip() -> str:
- # Lightweight smoke first via the proxy directly — catches
- # backend / chain failures *before* spawning claude, so a
- # claude failure is unambiguously a claude / env issue
- # rather than an upstream issue.
- assert state.port is not None
- return _proxy_roundtrip(state.port, model)
-
- checklist.run("Round-tripping chat completion", _roundtrip)
-
- def _spawn() -> str:
- assert state.claude_bin is not None
- assert state.port is not None
- return _run_claude_prompt(state.claude_bin, state.port, model)
-
- checklist.run("Spawning claude with proxy env", _spawn)
-
- def _shutdown() -> str:
- if state.server is None or state.thread is None:
- return "(no proxy started)"
- return _teardown(state.server, state.thread)
-
- checklist.run("Tearing down proxy", _shutdown)
-
- total_ms = (time.monotonic() - overall_start) * 1000.0
- return checklist.summarize("claude", model, total_ms)
-
-
-def verify_codex(
- *,
- model: str,
- base_url: str,
- api_key: str,
- port: int | None = None,
- timeout: float | None = None,
- key_source: str | None = None,
-) -> int:
- """Run the full ``codex`` e2e verify checklist; return exit code.
-
- Seven steps — like ``verify claude`` minus the Anthropic probe
- (codex always uses the OpenAI translation chain, no native
- passthrough path to detect).
-
- See :func:`verify_proxy` for the ``key_source`` contract.
- """
- _silence_chatty_loggers()
- overall_start = time.monotonic()
- checklist = _Checklist(title="verify codex", total=7)
-
- checklist.run(
- "Resolving credentials",
- lambda: _check_credentials(api_key, base_url, key_source),
- )
- checklist.run(
- "Reaching backend",
- lambda: _check_backend_reachable(base_url, api_key, key_source),
- )
-
- state = _VerifyState()
-
- def _start() -> str:
- chain = _build_codex_switchyard(
- model, api_key, base_url, timeout, StatsAccumulator(),
- )
- switchyard = build_single_model_table(model, chain)
- server, thread, resolved_port = _start_proxy(switchyard, port)
- state.server = server
- state.thread = thread
- state.port = resolved_port
- return f"127.0.0.1:{resolved_port}"
-
- checklist.run("Starting proxy", _start)
-
- def _locate() -> str:
- bin_path = _locate_codex()
- state.codex_bin = bin_path
- return bin_path
-
- checklist.run("Locating codex binary", _locate)
-
- def _roundtrip() -> str:
- assert state.port is not None
- return _proxy_roundtrip(state.port, model)
-
- checklist.run("Round-tripping chat completion", _roundtrip)
-
- def _spawn() -> str:
- assert state.codex_bin is not None
- assert state.port is not None
- return _run_codex_prompt(state.codex_bin, state.port, model)
-
- checklist.run("Spawning codex with proxy provider", _spawn)
-
- def _shutdown() -> str:
- if state.server is None or state.thread is None:
- return "(no proxy started)"
- return _teardown(state.server, state.thread)
-
- checklist.run("Tearing down proxy", _shutdown)
-
- total_ms = (time.monotonic() - overall_start) * 1000.0
- return checklist.summarize("codex", model, total_ms)
-
-
-def verify_openclaw(
- *,
- model: str,
- base_url: str,
- api_key: str,
- port: int | None = None,
- timeout: float | None = None,
- key_source: str | None = None,
-) -> int:
- """Run the full ``openclaw`` e2e verify checklist; return exit code.
-
- Eight steps — the proxy-only five plus harness-specific three
- (locate binary + write transient workspace + spawn-and-validate).
-
- See :func:`verify_proxy` for the ``key_source`` contract.
- """
- _silence_chatty_loggers()
- overall_start = time.monotonic()
- checklist = _Checklist(title="verify openclaw", total=8)
-
- checklist.run(
- "Resolving credentials",
- lambda: _check_credentials(api_key, base_url, key_source),
- )
- checklist.run(
- "Reaching backend",
- lambda: _check_backend_reachable(base_url, api_key, key_source),
- )
-
- state = _VerifyState()
-
- def _start() -> str:
- # OpenClaw always speaks OpenAI Chat Completions to the proxy,
- # so we always build the OpenAI translation chain — no probe
- # required (matches launch_openclaw).
- switchyard = _build_openclaw_switchyard(
- model, api_key, base_url, timeout, StatsAccumulator(),
- )
- server, thread, resolved_port = _start_proxy(switchyard, port)
- state.server = server
- state.thread = thread
- state.port = resolved_port
- return f"127.0.0.1:{resolved_port}"
-
- checklist.run("Starting proxy", _start)
-
- def _locate() -> str:
- bin_path = _locate_openclaw()
- state.openclaw_bin = bin_path
- return bin_path
-
- checklist.run("Locating openclaw binary", _locate)
-
- def _workspace() -> str:
- assert state.port is not None
- # Build a single-model catalog matching the one launch_openclaw
- # would emit, so the verify path exercises the same JSON5
- # schema.
- entries = [(
- model,
- f"{_openclaw_model_display_name(model)} (Switchyard)",
- f"Routed through Switchyard to {model}.",
- )]
- workspace = _write_openclaw_workspace(
- port=state.port,
- entries=entries,
- primary_model_id=f"switchyard/{model.lstrip('/')}",
- )
- state.openclaw_workspace = workspace
- return workspace
-
- checklist.run("Writing transient openclaw workspace", _workspace)
-
- def _roundtrip() -> str:
- assert state.port is not None
- return _proxy_roundtrip(state.port, model)
-
- checklist.run("Round-tripping chat completion", _roundtrip)
-
- def _spawn() -> str:
- assert state.openclaw_bin is not None
- assert state.openclaw_workspace is not None
- return _run_openclaw_prompt(
- state.openclaw_bin, state.openclaw_workspace, model,
- )
-
- checklist.run("Spawning openclaw with proxy workspace", _spawn)
-
- def _shutdown() -> str:
- if state.server is None or state.thread is None:
- return "(no proxy started)"
- result = _teardown(state.server, state.thread)
- _remove_openclaw_workspace(state.openclaw_workspace)
- return result
-
- checklist.run("Tearing down proxy", _shutdown)
-
- total_ms = (time.monotonic() - overall_start) * 1000.0
- return checklist.summarize("openclaw", model, total_ms)
-
-
-__all__ = [
- "verify_proxy",
- "verify_claude",
- "verify_codex",
- "verify_openclaw",
-]
diff --git a/tests/e2e/test_verify_e2e.py b/tests/e2e/test_verify_e2e.py
deleted file mode 100644
index de1ba26d2..000000000
--- a/tests/e2e/test_verify_e2e.py
+++ /dev/null
@@ -1,336 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""End-to-end production gate for the smoke-test CLI surface.
-
-Shells out to the same CLI a fresh user runs after cloning the repo,
-so the test and the user-facing UX share a single source of truth.
-Each test invokes one of:
-
-* ``switchyard verify ...`` (proxy + backend; no harness binary)
-* ``switchyard launch claude --smoke ...`` (full claude e2e)
-* ``switchyard launch codex --smoke ...`` (full codex e2e)
-
-…as a subprocess, captures its stdout/stderr, and asserts
-``returncode == 0`` plus the final ``verify <mode>: PASS`` summary
-line is present. (The ``--smoke`` flag dispatches to the same
-:func:`verify_claude` / :func:`verify_codex` helpers the standalone
-``verify claude`` / ``verify codex`` subcommands used to drive, so
-the summary line wording is preserved.)
-
-Three mode-specific test classes:
-
-* :class:`TestVerifyProxyE2E` — runs unconditionally when secrets are
- available. No harness binary required. Cheapest gate.
-* :class:`TestVerifyClaudeE2E` — gated on ``claude --version`` being
- installable; ``pytest.skip`` otherwise.
-* :class:`TestVerifyCodexE2E` — gated on ``codex --version``; same
- skip pattern.
-
-Why subprocess-out instead of calling ``verify_proxy()`` directly:
-
-1. The subprocess captures the user-facing UX exactly — flag parsing,
- credential resolution, exit codes, output formatting. An in-process
- call would test the implementation, not the CLI.
-2. Spawning ``claude`` / ``codex`` from inside pytest's own process
- would fight with the surrounding pytest event loop (the verifier
- hosts uvicorn in a thread, and pytest-asyncio's autouse loop can
- interfere with subprocess teardown timing). A subprocess shell-out
- avoids both classes of cross-talk.
-
-Run with::
-
- OPENROUTER_API_KEY=sk-or-... pytest tests/e2e/test_verify_e2e.py -v
-"""
-
-from __future__ import annotations
-
-import logging
-import os
-import subprocess
-import sys
-
-import pytest
-
-from .conftest import REPO_ROOT
-
-pytestmark = pytest.mark.integration
-
-logger = logging.getLogger("e2e.verify")
-
-# Per-mode budget for the entire ``verify`` subprocess. Step-level
-# timeouts inside ``verify`` (60s per harness invocation, 60s round-
-# trip, 10s per probe) sum to ~3 minutes worst case; 240s gives slack
-# for subprocess startup + Python's own venv-resolution latency.
-_VERIFY_TIMEOUT_S = 240.0
-
-
-def _run_verify(
- mode: str,
- *,
- api_key: str,
- base_url: str,
- model: str,
- extra_args: list[str] | None = None,
-) -> subprocess.CompletedProcess:
- """Shell out to the smoke-test CLI for ``mode``.
-
- Modes dispatch to:
-
- * ``"proxy"`` → ``switchyard verify ...``
- * ``"claude"`` → ``switchyard launch claude --smoke ...``
- * ``"codex"`` → ``switchyard launch codex --smoke ...``
-
- All three end up running the same orchestrators in
- ``switchyard.server.verify`` (``verify_proxy`` / ``verify_claude``
- / ``verify_codex``) and emit the same ``verify <mode>: PASS`` /
- ``FAIL`` summary line; the CLI shape is the only thing that
- changed in the unification.
-
- Invokes via ``python -m`` (not ``.venv/bin/switchyard``) to match
- the convention :mod:`tests.e2e.conftest` uses — keeps the tests
- independent of whether the editable-install script shim has been
- regenerated since the last package install.
- """
- base_cmd = [sys.executable, "-m", "switchyard.cli.switchyard_cli"]
- if mode == "proxy":
- verb_args = ["verify"]
- elif mode == "claude":
- verb_args = ["launch", "claude", "--smoke"]
- elif mode == "codex":
- verb_args = ["launch", "codex", "--smoke"]
- else:
- raise ValueError(f"unsupported smoke mode: {mode!r}")
- cmd = [
- *base_cmd,
- *verb_args,
- "--model", model,
- "--api-key", api_key,
- "--base-url", base_url,
- ]
- if extra_args:
- cmd.extend(extra_args)
-
- env = os.environ.copy()
- # Belt-and-braces: the verify orchestrator also resolves from env
- # vars, but we set OPENAI_API_KEY here so any deeper subprocess
- # (e.g. the codex CLI shelled out by ``launch codex --smoke``)
- # finds it without requiring the same waterfall.
- env.setdefault("OPENAI_API_KEY", api_key)
-
- logger.info("[Verify] Running: %s", " ".join(cmd))
- return subprocess.run(
- cmd,
- capture_output=True,
- text=True,
- timeout=_VERIFY_TIMEOUT_S,
- cwd=str(REPO_ROOT),
- env=env,
- check=False,
- )
-
-
-def _assert_pass(result: subprocess.CompletedProcess, mode: str) -> None:
- """Common pass assertion: rc=0 + a ``verify <mode>: PASS`` line.
-
- Both checks are intentional. Exit 0 alone could be a parse error
- that exited cleanly without ever reaching the runner; the summary
- line is the only positive signal that the orchestrator ran end-to-
- end. Pinning both gives loud failures with surfaceable output —
- the assertion message dumps stdout + stderr so CI logs are
- diagnosable without re-running the test.
- """
- assert result.returncode == 0, (
- f"verify {mode} exited {result.returncode}\n"
- f"--- stdout ---\n{result.stdout}\n"
- f"--- stderr ---\n{result.stderr}\n"
- )
- assert f"verify {mode}: PASS" in result.stdout, (
- f"missing 'verify {mode}: PASS' summary line\n"
- f"--- stdout ---\n{result.stdout}\n"
- f"--- stderr ---\n{result.stderr}\n"
- )
-
-
-# ---------------------------------------------------------------------------
-# verify proxy — backend + chain only, no harness binary
-# ---------------------------------------------------------------------------
-
-
-class TestVerifyProxyE2E:
- """The cheapest gate — runs unconditionally when secrets are available.
-
- Smoke-tests the verify CLI's six steps end-to-end against the selected
- live backend: credentials, /models reachability, /v1/messages probe,
- proxy spin-up, chat-completion round-trip, teardown.
-
- A failure here means *something* in the chain is broken (or the
- upstream is down) — useful tripwire even before we get to the
- harness-binary tests.
- """
-
- def test_verify_proxy_passes(self, nvidia_config: dict) -> None:
- result = _run_verify(
- "proxy",
- api_key=nvidia_config["api_key"],
- base_url=nvidia_config["base_url"],
- model=nvidia_config["model"],
- )
- _assert_pass(result, "proxy")
-
- # All six steps must report — count check guards against the
- # runner short-circuiting silently after a refactor.
- for step_marker in ("[1/6]", "[2/6]", "[3/6]", "[4/6]", "[5/6]", "[6/6]"):
- assert step_marker in result.stdout, (
- f"missing step header {step_marker}\n--- stdout ---\n{result.stdout}"
- )
-
- def test_verify_proxy_fails_loud_on_bad_credentials(
- self, nvidia_config: dict,
- ) -> None:
- """Negative test: a bogus key must fail at step 2 (Reach backend),
- not silently pass — this is the contract that lets
- ``returncode == 0`` mean "everything is wired correctly".
-
- Picks an obviously-invalid key shape so the test doesn't
- depend on rate-limit behavior of any specific upstream.
- """
- result = _run_verify(
- "proxy",
- api_key="sk-deliberately-invalid-credential-for-test",
- base_url=nvidia_config["base_url"],
- model=nvidia_config["model"],
- )
- assert result.returncode != 0, (
- f"verify proxy must fail with a bad key; got rc=0\n"
- f"--- stdout ---\n{result.stdout}\n"
- f"--- stderr ---\n{result.stderr}\n"
- )
- assert "verify proxy: FAIL" in result.stdout, (
- f"missing FAIL summary line\n"
- f"--- stdout ---\n{result.stdout}\n"
- )
-
-
-# ---------------------------------------------------------------------------
-# verify claude — full e2e through Claude Code's CLI
-# ---------------------------------------------------------------------------
-
-
-def _is_claude_cli_available() -> bool:
- try:
- result = subprocess.run(
- ["claude", "--version"],
- capture_output=True,
- text=True,
- timeout=5.0,
- check=False,
- )
- return result.returncode == 0
- except (FileNotFoundError, subprocess.TimeoutExpired):
- return False
-
-
-class TestVerifyClaudeE2E:
- """Runs the full ``launch claude``-equivalent path: proxy + spawn
- ``claude -p "..."``. Skipped when ``claude`` isn't installed.
- """
-
- def test_verify_claude_passes(self, nvidia_config: dict) -> None:
- if not _is_claude_cli_available():
- pytest.skip(
- "claude CLI not installed; install with "
- "`curl -fsSL https://claude.ai/install.sh | bash`"
- )
-
- result = _run_verify(
- "claude",
- api_key=nvidia_config["api_key"],
- base_url=nvidia_config["base_url"],
- model=nvidia_config["model"],
- )
- _assert_pass(result, "claude")
-
- # All eight steps — pin the count to catch drift between
- # claude (8 steps with the Anthropic probe) and codex (7 steps).
- for step_marker in (
- "[1/8]", "[2/8]", "[3/8]", "[4/8]", "[5/8]", "[6/8]", "[7/8]", "[8/8]",
- ):
- assert step_marker in result.stdout, (
- f"missing step header {step_marker}\n--- stdout ---\n{result.stdout}"
- )
-
- # Spawn step-specific check: the ``Spawning claude`` step must
- # have appeared with a reply preview, not just OK.
- assert "Spawning claude" in result.stdout
- assert "reply=" in result.stdout, (
- f"missing reply preview from claude\n--- stdout ---\n{result.stdout}"
- )
-
-
-# ---------------------------------------------------------------------------
-# verify codex — full e2e through OpenAI Codex CLI
-# ---------------------------------------------------------------------------
-
-
-def _is_codex_cli_available() -> bool:
- """Mirror of :func:`_is_claude_cli_available` for codex."""
- try:
- result = subprocess.run(
- ["codex", "--version"],
- capture_output=True,
- text=True,
- timeout=5.0,
- check=False,
- )
- return result.returncode == 0
- except (FileNotFoundError, subprocess.TimeoutExpired):
- return False
-
-
-class TestVerifyCodexE2E:
- """Runs the full ``launch codex``-equivalent path: proxy + spawn
- ``codex exec "..."``. Skipped when ``codex`` isn't installed.
- """
-
- # Pinned model — overrides whatever provider model env is set to for
- # this test only. Codex sends a Responses API request whose
- # ``input`` items can place a ``role: "system"`` message after
- # the first user turn; strict providers (notably
- # ``nvidia/qwen/qwen3.5-35b-a3b`` on the NVIDIA Inference Hub)
- # reject that with HTTP 400 ``"System message must be at the
- # beginning."`` Nemotron Super v3 accepts it, so we hard-pin to
- # that model so this test validates the codex e2e path
- # independently of whatever the local default model happens to be.
- _CODEX_TEST_MODEL = "nvidia/nvidia/nemotron-3-super-v3"
-
- def test_verify_codex_passes(self, nvidia_config: dict) -> None:
- if not _is_codex_cli_available():
- pytest.skip(
- "codex CLI not installed; install with "
- "`npm install -g @openai/codex`"
- )
-
- result = _run_verify(
- "codex",
- api_key=nvidia_config["api_key"],
- base_url=nvidia_config["base_url"],
- model=self._CODEX_TEST_MODEL,
- )
- _assert_pass(result, "codex")
-
- # Codex skips the Anthropic probe — pin count at 7 to catch
- # drift toward claude's 8-step shape.
- for step_marker in (
- "[1/7]", "[2/7]", "[3/7]", "[4/7]", "[5/7]", "[6/7]", "[7/7]",
- ):
- assert step_marker in result.stdout, (
- f"missing step header {step_marker}\n--- stdout ---\n{result.stdout}"
- )
- assert "[8/" not in result.stdout, (
- "verify codex must run 7 steps, not 8 — Anthropic probe "
- "should be skipped for the codex path."
- )
-
- assert "Spawning codex" in result.stdout
- assert "reply=" in result.stdout
diff --git a/tests/getting_started/test_getting_started.py b/tests/getting_started/test_getting_started.py
index c7d54552b..835be30da 100644
--- a/tests/getting_started/test_getting_started.py
+++ b/tests/getting_started/test_getting_started.py
@@ -1,260 +1,17 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Executable coverage for ``docs/getting_started.md``."""
+"""Drift checks for the concise getting-started guide."""
-from __future__ import annotations
-
-import asyncio
-import os
-from collections.abc import AsyncIterator
-from contextlib import asynccontextmanager
from pathlib import Path
-import httpx
-import pytest
-from markdown_it import MarkdownIt
-
-REPO_ROOT = Path(__file__).resolve().parents[2]
-GUIDE_PATH = REPO_ROOT / "docs" / "getting_started.md"
-STARTUP_TIMEOUT_S = 30.0
-REQUEST_TIMEOUT_S = 1.0
-TEARDOWN_GRACE_S = 10.0
-
-
[email protected](scope="module")
-def guide_text() -> str:
- """Return the published Getting Started source."""
- return GUIDE_PATH.read_text()
-
-
[email protected](scope="session")
-async def rust_server_binary() -> Path:
- """Build and return the Rust server binary exercised by the guide."""
- returncode, stdout, stderr = await _run_command(
- ["cargo", "build", "--quiet", "--locked", "-p", "switchyard-server"],
- )
- assert returncode == 0, f"failed to build switchyard-server:\n{stderr}{stdout}"
- binary = REPO_ROOT / "target" / "debug" / "switchyard-server"
- assert binary.is_file(), f"cargo did not create {binary}"
- return binary
-
-
-def _code_blocks(text: str, lang: str) -> list[str]:
- """Extract fenced Markdown blocks for one language."""
- md = MarkdownIt()
- return [
- token.content
- for token in md.parse(text)
- if token.type == "fence" and token.info.strip() == lang
- ]
-
-
-async def test_rust_server_toml_blocks_validate_with_rust_schema(
- guide_text: str,
- rust_server_binary: Path,
- tmp_path: Path,
-) -> None:
- """Validate every documented server config with the production Rust loader."""
- configs = [
- block
- for block in _code_blocks(guide_text, "toml")
- if "schema_version" in block
- and "[llm_clients." in block
- and "[targets." in block
- and "[routes." in block
- ]
- assert configs, "no Rust server TOML config found in the guide"
-
- env = os.environ.copy()
- env["OPENROUTER_API_KEY"] = "getting-started-test-key"
- for index, config in enumerate(configs):
- config_path = tmp_path / f"getting-started-{index}.toml"
- config_path.write_text(config)
- returncode, stdout, stderr = await _run_command(
- [rust_server_binary, "--config", config_path, "--dry-run"],
- env=env,
- )
- assert returncode == 0, (
- f"TOML block {index} failed Rust schema validation:\n{stderr}{stdout}"
- )
- assert "server OK: switchyard" in stdout
-
-
-async def test_rust_server_help_advertises_documented_flags(
- rust_server_binary: Path,
-) -> None:
- """Keep the guide's server flags aligned with the Rust CLI."""
- returncode, stdout, stderr = await _run_command(
- [rust_server_binary, "--help"],
- )
- assert returncode == 0, stderr
- for flag in ("--config", "--dry-run", "--host", "--port"):
- assert flag in stdout, f"documented flag {flag} is missing from --help"
-
-
-def test_guide_uses_the_rust_server_flow(guide_text: str) -> None:
- """Prevent legacy Python install, configure, and serve commands from returning."""
- assert "cargo build --locked --release -p switchyard-server" in guide_text
- assert "./target/release/switchyard-server --config routes.toml" in guide_text
- for legacy_command in (
- 'pip install "nemo-switchyard',
- "switchyard configure",
- "switchyard serve",
- "--routing-profiles",
- "routes.yaml",
- ):
- assert legacy_command not in guide_text
-
-
-def noop_config(tmp_path: Path) -> Path:
- """Create a network-free Rust route for exercising the documented endpoints."""
- config_path = tmp_path / "routes.toml"
- config_path.write_text(
- """\
-schema_version = 1
-
-[llm_clients]
-
-[targets]
-
-[routes.health_check]
-id = "switchyard/test"
-type = "noop"
-"""
- )
- return config_path
-
-
-async def test_rust_server_health_and_models(
- rust_server_binary: Path,
- noop_config: Path,
-) -> None:
- """Start the Rust server and exercise the guide's operational endpoints."""
- async with _serve_in_background(rust_server_binary, noop_config) as client:
- health = await client.get("/health")
- assert health.status_code == 200
-
- models = await client.get("/v1/models")
- assert models.status_code == 200
- assert any(model["id"] == "switchyard/test" for model in models.json()["data"])
-
-
-async def _run_command(
- command: list[str | os.PathLike[str]],
- *,
- env: dict[str, str] | None = None,
-) -> tuple[int, str, str]:
- """Run a command without blocking the active test event loop."""
- process = await asyncio.create_subprocess_exec(
- *command,
- cwd=REPO_ROOT,
- env=env,
- stdout=asyncio.subprocess.PIPE,
- stderr=asyncio.subprocess.PIPE,
- )
- stdout, stderr = await process.communicate()
- if process.returncode is None:
- raise RuntimeError(f"command did not exit: {command}")
- return (
- process.returncode,
- stdout.decode(errors="replace"),
- stderr.decode(errors="replace"),
- )
-
-
-async def _read_server_base_url(process: asyncio.subprocess.Process) -> str:
- """Read the ephemeral address from the Rust server startup banner."""
- if process.stdout is None:
- raise RuntimeError("switchyard-server stdout was not captured")
-
- deadline = asyncio.get_running_loop().time() + STARTUP_TIMEOUT_S
- output: list[str] = []
- while True:
- remaining = deadline - asyncio.get_running_loop().time()
- if remaining <= 0:
- raise TimeoutError(
- "switchyard-server did not report its bound address:\n" + "".join(output)
- )
- try:
- raw_line = await asyncio.wait_for(process.stdout.readline(), timeout=remaining)
- except TimeoutError as error:
- raise TimeoutError(
- "switchyard-server did not report its bound address:\n" + "".join(output)
- ) from error
- if not raw_line:
- await process.wait()
- raise RuntimeError(
- f"switchyard-server exited early with {process.returncode}:\n"
- + "".join(output)
- )
-
- line = raw_line.decode(errors="replace")
- output.append(line)
- if line.startswith(" listening: "):
- return line.removeprefix(" listening: ").strip()
-
-
-async def _wait_for_proxy_ready(
- process: asyncio.subprocess.Process,
- client: httpx.AsyncClient,
-) -> None:
- """Wait until the server accepts requests or exits."""
- deadline = asyncio.get_running_loop().time() + STARTUP_TIMEOUT_S
- while asyncio.get_running_loop().time() < deadline:
- if process.returncode is not None:
- raise RuntimeError(
- f"switchyard-server exited early with {process.returncode}"
- )
- try:
- response = await client.get("/health")
- if response.status_code == 200:
- return
- except httpx.HTTPError:
- pass
- await asyncio.sleep(0.1)
- raise TimeoutError(
- f"switchyard-server did not become ready within {STARTUP_TIMEOUT_S}s"
- )
-
-
-@asynccontextmanager
-async def _serve_in_background(
- binary: Path,
- config_path: Path,
-) -> AsyncIterator[httpx.AsyncClient]:
- """Run the Rust server until the lifecycle assertion completes."""
- process = await asyncio.create_subprocess_exec(
- binary,
- "--config",
- config_path,
- "--host",
- "127.0.0.1",
- "--port",
- "0",
- cwd=REPO_ROOT,
- stdout=asyncio.subprocess.PIPE,
- stderr=asyncio.subprocess.STDOUT,
- )
- try:
- base_url = await _read_server_base_url(process)
- async with httpx.AsyncClient(
- base_url=base_url,
- timeout=REQUEST_TIMEOUT_S,
- ) as client:
- await _wait_for_proxy_ready(process, client)
- yield client
- finally:
- if process.returncode is None:
- process.terminate()
- try:
- await asyncio.wait_for(process.wait(), timeout=TEARDOWN_GRACE_S)
- except TimeoutError:
- process.kill()
- await asyncio.wait_for(process.wait(), timeout=TEARDOWN_GRACE_S)
-
-# TODO: Add launcher coverage back when launchers are wired to the Rust server.
-# TODO: Add Python snippet coverage back with the supported Rust-backed API.
-# TODO: Add YAML route-bundle coverage back only if YAML becomes a supported Rust format.
+def test_getting_started_uses_the_current_cli() -> None:
+ guide = (
+ Path(__file__).resolve().parents[2] / "docs" / "getting_started.md"
+ ).read_text()
+ assert "switchyard launch claude --model switchyard" in guide
+ assert "switchyard launch codex --model switchyard" in guide
+ assert "switchyard serve" not in guide
+ assert "switchyard configure" not in guide
+ assert "switchyard verify" not in guide
diff --git a/tests/readme/test_readme.py b/tests/readme/test_readme.py
index f119f2be9..240f5232b 100644
--- a/tests/readme/test_readme.py
+++ b/tests/readme/test_readme.py
@@ -1,85 +1,15 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Executable coverage for the README.md."""
+"""README command drift checks."""
-from __future__ import annotations
-
-import os
-import subprocess
from pathlib import Path
-import pytest
-from markdown_it import MarkdownIt
-
-REPO_ROOT = Path(__file__).resolve().parents[2]
-README_PATH = REPO_ROOT / "README.md"
-
-
[email protected](scope="module")
-def readme_text() -> str:
- return README_PATH.read_text()
-
-
-def _code_blocks(text: str, lang: str) -> list[str]:
- # markdown-it-py handles indented fences + trailing whitespace correctly,
- # which a naive triple-backtick regex does not.
- md = MarkdownIt()
- return [
- token.content
- for token in md.parse(text)
- if token.type == "fence" and token.info.strip() == lang
- ]
-
-
-def test_rust_server_toml_blocks_validate_with_rust_schema(
- readme_text: str,
- tmp_path: Path,
-) -> None:
- blocks = _code_blocks(readme_text, "toml")
- server_configs = [
- block
- for block in blocks
- if "schema_version" in block
- and "[llm_clients." in block
- and "[targets." in block
- and "[routes." in block
- ]
-
- assert server_configs, "no README TOML block found for the Rust server"
-
- env = os.environ.copy()
- env["OPENROUTER_API_KEY"] = "readme-test-key"
- for index, config in enumerate(server_configs):
- config_path = tmp_path / f"readme-server-{index}.toml"
- config_path.write_text(config)
- # Dry-run uses the production Rust loader for schema and reference validation.
- result = subprocess.run(
- [
- "cargo",
- "run",
- "--quiet",
- "--locked",
- "-p",
- "switchyard-server",
- "--",
- "--config",
- str(config_path),
- "--dry-run",
- ],
- cwd=REPO_ROOT,
- env=env,
- capture_output=True,
- text=True,
- check=False,
- )
- assert result.returncode == 0, (
- f"README TOML block {index} failed Rust schema validation:\n"
- f"{result.stderr}{result.stdout}"
- )
-# TODO: Add Python snippet tripwire test back in when we have a Python snippet to test.
-# TODO: Add route block validation test back in when we document YAML route bundles.
-# TODO: Add routing docs schema test back in when the README links those guides.
-# TODO: Add CLI subcommand test back in when the README documents Python CLI commands.
-# TODO: Add CLI flag test back in when the README documents Python CLI flags.
+def test_readme_uses_the_current_cli() -> None:
+ readme = (Path(__file__).resolve().parents[2] / "README.md").read_text()
+ assert "switchyard launch claude --model switchyard" in readme
+ assert "switchyard launch codex --model switchyard" in readme
+ assert "switchyard serve" not in readme
+ assert "switchyard configure" not in readme
+ assert "switchyard verify" not in readme
diff --git a/tests/test_cli_reference_docs.py b/tests/test_cli_reference_docs.py
index bc0de940d..3c5af543d 100644
--- a/tests/test_cli_reference_docs.py
+++ b/tests/test_cli_reference_docs.py
@@ -1,56 +1,25 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Tests for CLI reference documentation drift."""
+"""CLI reference drift tests."""
import argparse
-from collections.abc import Callable
from pathlib import Path
-from markdown_it import MarkdownIt
-
from switchyard.cli.switchyard_cli import _build_parser
-REPO_ROOT = Path(__file__).resolve().parents[1]
-CLI_REFERENCE = REPO_ROOT / "docs" / "cli_reference.md"
-_MARKDOWN = MarkdownIt()
-_AGENT_SPECIFIC_CONFIGURE_OPTIONS = {
- "--claude-api-key",
- "--claude-base-url",
- "--claude-model",
- "--codex-api-key",
- "--codex-base-url",
- "--codex-model",
- "--openclaw-api-key",
- "--openclaw-base-url",
- "--openclaw-model",
-}
+CLI_REFERENCE = Path(__file__).resolve().parents[1] / "docs" / "cli_reference.md"
def _subparsers(parser: argparse.ArgumentParser) -> dict[str, argparse.ArgumentParser]:
- action = next(a for a in parser._actions if isinstance(a, argparse._SubParsersAction))
+ action = next(
+ action
+ for action in parser._actions
+ if isinstance(action, argparse._SubParsersAction)
+ )
return action.choices # type: ignore[return-value]
-def _markdown_section(text: str, heading: str) -> str:
- tokens = _MARKDOWN.parse(text)
- lines = text.splitlines()
- for index, token in enumerate(tokens):
- if token.type != "heading_open" or token.tag != "h2":
- continue
- title = tokens[index + 1].content
- if title.strip("`") != heading:
- continue
- start = token.map[0] if token.map else 0
- end = len(lines)
- for next_token in tokens[index + 1:]:
- if next_token.type == "heading_open" and next_token.tag == "h2" and next_token.map:
- end = next_token.map[0]
- break
- return "\n".join(lines[start:end])
- raise AssertionError(f"docs/cli_reference.md missing section {heading!r}")
-
-
def _long_options(parser: argparse.ArgumentParser) -> set[str]:
return {
option
@@ -60,160 +29,18 @@ def _long_options(parser: argparse.ArgumentParser) -> set[str]:
}
-def test_cli_reference_documents_every_serve_flag() -> None:
- parser = _build_parser()
- serve = _subparsers(parser)["serve"]
- serve_section = _markdown_section(CLI_REFERENCE.read_text(), "switchyard serve")
-
- expected = _long_options(serve) | {"--routing-profiles"}
- missing = sorted(flag for flag in expected if flag not in serve_section)
-
- assert not missing, (
- "docs/cli_reference.md serve section missing flags: " + ", ".join(missing)
- )
-
-
-def test_cli_reference_documents_supported_configure_flags() -> None:
- parser = _build_parser()
- configure = _subparsers(parser)["configure"]
- configure_section = _markdown_section(
- CLI_REFERENCE.read_text(),
- "switchyard configure",
- )
-
- expected = (
- _long_options(configure) - _AGENT_SPECIFIC_CONFIGURE_OPTIONS
- ) | {"--routing-profiles"}
- missing = sorted(flag for flag in expected if flag not in configure_section)
-
- assert not missing, (
- "docs/cli_reference.md configure section missing flags: "
- + ", ".join(missing)
- )
-
-
-def test_cli_reference_omits_unsupported_skill_distillation_flags() -> None:
- configure_section = _markdown_section(
- CLI_REFERENCE.read_text(),
- "switchyard configure",
- )
- unsupported_flags = {
- "--skill-session-store",
- "--skill-trigger",
- "--skill-mount",
- "--skill-stage-only",
- "--skill-lookback-sessions",
- }
-
- stale = sorted(flag for flag in unsupported_flags if flag in configure_section)
-
- assert not stale, (
- "docs/cli_reference.md configure section documents unsupported flags: "
- + ", ".join(stale)
- )
-
-
-def test_cli_reference_serve_overview_points_to_route_bundle() -> None:
- serve_row = next(
- line
- for line in CLI_REFERENCE.read_text().splitlines()
- if line.startswith("| [`serve`](#switchyard-serve)")
- )
-
- assert "--routing-profiles" in serve_row
- assert "`serve --config`" not in serve_row
- assert "inbound format" not in serve_row.lower()
-
-
-def test_cli_reference_marks_serve_inbound_as_noop() -> None:
- serve_section = _markdown_section(CLI_REFERENCE.read_text(), "switchyard serve").lower()
-
- assert "`--inbound format`" in serve_section
- assert "no-op" in serve_section
- assert "compat" in serve_section
-
-
-def test_cli_reference_documents_serve_intake_flags_once() -> None:
- doc = CLI_REFERENCE.read_text()
-
- assert "### Intake sink (serve)" in doc
- assert "`--intake-enabled`" in doc
- assert "`--enable-intake`" in doc
- assert doc.count("`--intake-base-url URL`") == 1
- assert doc.count("`--intake-workspace NAME`") == 1
- assert doc.count("`--intake-api-key VALUE`") == 1
- assert doc.count("`--intake-target-url URL`") == 1
-
-
-def _public_cli_doc_paths() -> list[Path]:
- return [REPO_ROOT / "README.md", *sorted((REPO_ROOT / "docs").glob("*.md"))]
-
-
-def _markdown_command_lines(path: Path) -> list[tuple[int, str]]:
- text = path.read_text(encoding="utf-8")
- matches: list[tuple[int, str]] = []
- for token in _MARKDOWN.parse(text):
- if token.type == "inline" and token.children and token.map:
- for child in token.children:
- if child.type == "code_inline" and child.content.strip():
- matches.append((token.map[0] + 1, child.content.strip()))
- continue
- if token.type not in {"fence", "code_block"} or token.map is None:
- continue
- line_base = token.map[0] + (2 if token.type == "fence" else 1)
- for offset, line in enumerate(token.content.splitlines()):
- stripped = line.strip()
- if stripped:
- matches.append((line_base + offset, stripped))
- return matches
-
-
-def _command_words(line: str) -> list[str]:
- return line.replace("`", "").replace("\\", " ").split()
-
-
-def _has_stale_routing_profiles(line: str) -> bool:
- words = _command_words(line)
- for index, word in enumerate(words):
- if word != "switchyard" or index + 2 >= len(words):
- continue
- if words[index + 1] in {"serve", "configure"}:
- if "--routing-profiles" in words[index + 2:]:
- return True
- return False
-
-
-def _has_serve_api_key(line: str) -> bool:
- words = _command_words(line)
- for index, word in enumerate(words):
- if word == "switchyard" and words[index + 1:index + 2] == ["serve"]:
- if "--api-key" in words[index + 2:]:
- return True
- return False
-
-
-def _matching_markdown_lines(predicate: Callable[[str], bool]) -> list[str]:
- matches: list[str] = []
- for path in _public_cli_doc_paths():
- for lineno, line in _markdown_command_lines(path):
- if predicate(line):
- matches.append(f"{path.relative_to(REPO_ROOT)}:{lineno}: {line}")
- return matches
-
-
-def test_cli_docs_do_not_use_stale_flag_placements() -> None:
- stale_checks = {
- "--routing-profiles must be a global switchyard flag": _has_stale_routing_profiles,
- "serve does not accept --api-key": _has_serve_api_key,
- }
-
- failures = []
- for reason, predicate in stale_checks.items():
- matches = _matching_markdown_lines(predicate)
- if matches:
- failures.append(reason + ":\n" + "\n".join(matches))
-
- assert not failures, "\n\n".join(failures)
+def test_reference_documents_launch_only() -> None:
+ text = CLI_REFERENCE.read_text()
+ assert "## `switchyard launch`" in text
+ assert "switchyard serve" not in text
+ assert "switchyard configure" not in text
+ assert "switchyard verify" not in text
-# TODO: Add agent-specific command-reference coverage when that documentation returns.
+def test_reference_lists_launcher_contract() -> None:
+ launch = _subparsers(_build_parser())["launch"]
+ text = CLI_REFERENCE.read_text()
+ for parser in _subparsers(launch).values():
+ assert _long_options(parser) == {"--model", "--config"}
+ assert "--model" in text
+ assert "--config" in text
diff --git a/tests/test_cli_stale_names.py b/tests/test_cli_stale_names.py
deleted file mode 100644
index 98662a372..000000000
--- a/tests/test_cli_stale_names.py
+++ /dev/null
@@ -1,73 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Tests that CLI constants and runtime strings use the `switchyard` command name.
-
-The PyPI distribution is `nemo-switchyard`, but user-facing CLI names,
-configuration directories, and runtime model descriptions stay `switchyard`.
-"""
-
-from __future__ import annotations
-
-import os
-from unittest.mock import patch
-
-
-def test_config_dir_env_var_name() -> None:
- from switchyard.cli.config.user_config import CONFIG_DIR_ENV_VAR
- assert CONFIG_DIR_ENV_VAR == "SWITCHYARD_CONFIG_DIR", (
- f"Expected SWITCHYARD_CONFIG_DIR, got {CONFIG_DIR_ENV_VAR}"
- )
-
-
-def test_no_tui_env_var_name() -> None:
- from switchyard.cli.tui.terminal_capabilities import NO_TUI_ENV_VAR
- assert NO_TUI_ENV_VAR == "SWITCHYARD_NO_TUI", (
- f"Expected SWITCHYARD_NO_TUI, got {NO_TUI_ENV_VAR}"
- )
-
-
-def test_config_dir_path_uses_switchyard() -> None:
- from switchyard.cli.config.user_config import get_user_config_dir
-
- clean_env = {
- k: v for k, v in os.environ.items()
- if k not in ("XDG_CONFIG_HOME", "NEMO_SWITCHYARD_CONFIG_DIR", "SWITCHYARD_CONFIG_DIR")
- }
- with patch.dict(os.environ, clean_env, clear=True):
- result = get_user_config_dir()
-
- assert result.name == "switchyard", (
- f"Config dir should end with 'switchyard', got '{result.name}'"
- )
- assert "nemo-switchyard" not in str(result), (
- f"Config dir path should not contain 'nemo-switchyard', got '{result}'"
- )
-
-
-def test_argparse_prog_is_switchyard() -> None:
- # The parser prog= determines the command name shown in --help and errors.
-
- # Import the CLI module and find the parser builder
- # The ArgumentParser is built inside main() / build_parser() — search for it
- import inspect
-
- import switchyard.cli.switchyard_cli as cli_module
- source = inspect.getsource(cli_module)
- assert 'prog="nemo-switchyard"' not in source, (
- "argparse prog still set to 'nemo-switchyard'; should be 'switchyard'"
- )
-
-
-def test_claude_code_launcher_model_description_uses_switchyard() -> None:
- import inspect
-
- import switchyard.cli.launchers.claude_code_launcher as launcher_module
- source = inspect.getsource(launcher_module)
- assert "nemo-switchyard" not in source or "Routed via nemo-switchyard" not in source, (
- "claude_code_launcher still uses 'nemo-switchyard' in user-visible model description"
- )
- # More precise check
- assert "Routed via nemo-switchyard" not in source, (
- "ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION still says 'nemo-switchyard'"
- )
diff --git a/tests/test_configure_model_picker_inputs.py b/tests/test_configure_model_picker_inputs.py
deleted file mode 100644
index b9bfa9268..000000000
--- a/tests/test_configure_model_picker_inputs.py
+++ /dev/null
@@ -1,108 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Unit tests for the `configure` wizard's model-picker input plumbing.
-
-Pins the two helpers that feed `wizard.select_model(...)`:
-
-* `_routing_profile_model_ids(...)` — extracts user-callable model ids from a
- parsed routing-profiles bundle.
-* `_merge_candidate_ids(...)` — unions routing-profile ids with the upstream
- catalog in first-seen order.
-
-Without these in the picker pipeline the wizard offers only the upstream
-catalog and the user can't pick a route key like `opus-ds-stage_router` even when
-their YAML declares it.
-"""
-
-from __future__ import annotations
-
-from switchyard.cli.configure_command import _merge_candidate_ids
-from switchyard.cli.route_bundle import routing_profile_model_ids as _routing_profile_model_ids
-
-
-def test_empty_or_none_bundle_returns_empty() -> None:
- assert _routing_profile_model_ids(None) == []
- assert _routing_profile_model_ids({}) == []
- assert _routing_profile_model_ids({"routes": {}}) == []
-
-
-def test_extracts_route_keys_and_tier_models() -> None:
- """StageRouter + deterministic routes contribute the route key plus
- strong/weak tier models. Classifier is intentionally skipped (internal)."""
- bundle = {
- "routes": {
- "opus-ds-stage_router": {
- "type": "stage_router",
- "picker": "capable_first",
- "fallback_target_on_evict": "strong",
- "strong": {"model": "aws/anthropic/bedrock-claude-opus-4-7"},
- "weak": {"model": "nvidia/deepseek-ai/evals-deepseek-v4-pro"},
- "classifier": {"model": "nvidia/deepseek-ai/deepseek-v4-flash"},
- },
- "opus-ds-classifier": {
- "type": "deterministic",
- "profile": "coding_agent",
- "fallback_target_on_evict": "strong",
- "strong": {"model": "aws/anthropic/bedrock-claude-opus-4-7"},
- "weak": {"model": "nvidia/deepseek-ai/evals-deepseek-v4-pro"},
- "classifier": {"model": "nvidia/deepseek-ai/deepseek-v4-flash"},
- },
- },
- }
- assert _routing_profile_model_ids(bundle) == [
- "opus-ds-stage_router",
- "aws/anthropic/bedrock-claude-opus-4-7",
- "nvidia/deepseek-ai/evals-deepseek-v4-pro",
- "opus-ds-classifier",
- ]
-
-
-def test_single_model_passthrough_target_extracted() -> None:
- bundle = {
- "routes": {
- "opus-direct": {
- "type": "model",
- "target": {"model": "aws/anthropic/bedrock-claude-opus-4-7"},
- },
- },
- }
- assert _routing_profile_model_ids(bundle) == [
- "opus-direct",
- "aws/anthropic/bedrock-claude-opus-4-7",
- ]
-
-
-def test_string_shorthand_tier_resolves_to_model_id() -> None:
- """``strong: "model/id"`` shorthand should land as a candidate too."""
- bundle = {
- "routes": {
- "rr": {
- "type": "random_routing",
- "strong": "gpt-4o",
- "weak": "gpt-4o-mini",
- },
- },
- }
- assert _routing_profile_model_ids(bundle) == ["rr", "gpt-4o", "gpt-4o-mini"]
-
-
-def test_merge_candidate_ids_dedupes_preserves_first_seen_order() -> None:
- """Routing-profile entries first, then upstream catalog. Duplicates from
- later sources drop."""
- routing = ["opus-ds-stage_router", "aws/anthropic/bedrock-claude-opus-4-7"]
- upstream = [
- "openai/gpt-5.2",
- "aws/anthropic/bedrock-claude-opus-4-7", # dup with routing[1]
- "nvidia/nvidia/nemotron-3-super-120b-long-ctx",
- ]
- assert _merge_candidate_ids(routing, upstream) == [
- "opus-ds-stage_router",
- "aws/anthropic/bedrock-claude-opus-4-7",
- "openai/gpt-5.2",
- "nvidia/nvidia/nemotron-3-super-120b-long-ctx",
- ]
-
-
-def test_merge_candidate_ids_skips_empty_strings() -> None:
- assert _merge_candidate_ids(["a", "", "b"], ["", "c"]) == ["a", "b", "c"]
diff --git a/tests/test_intake_cli_flags.py b/tests/test_intake_cli_flags.py
index 58e656cc2..be20137a4 100644
--- a/tests/test_intake_cli_flags.py
+++ b/tests/test_intake_cli_flags.py
@@ -1,98 +1,46 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Tests for Intake enable flag normalization across CLI surfaces."""
+"""Tests for Intake flags on ``switchyard serve``."""
-from __future__ import annotations
-
-import argparse
import logging
import pytest
from switchyard.cli.switchyard_cli import _build_parser
+_SERVE = ["serve", "--routing-profiles", "routes.yaml"]
-def test_serve_accepts_canonical_intake_flag() -> None:
- args = _build_parser().parse_args(["serve", "--intake-enabled"])
-
- assert args.intake_enabled is True
- assert not hasattr(args, "enable_intake")
-
-
-def test_serve_accepts_deprecated_intake_alias(caplog: pytest.LogCaptureFixture) -> None:
- caplog.set_level(logging.WARNING, "switchyard.cli.switchyard_cli")
-
- args = _build_parser().parse_args(["serve", "--enable-intake"])
-
- assert args.intake_enabled is True
- assert not hasattr(args, "enable_intake")
- assert "--enable-intake is deprecated; use --intake-enabled" in caplog.text
-
-
[email protected]("target", ["claude", "codex", "openclaw"])
-def test_launchers_accept_canonical_intake_flag(target: str) -> None:
- args = _build_parser().parse_args([
- "launch",
- target,
- "--model",
- "nvidia/moonshotai/kimi-k2.5",
- "--intake-enabled",
- ])
+def test_serve_accepts_canonical_intake_flag() -> None:
+ args = _build_parser().parse_args([*_SERVE, "--intake-enabled"])
assert args.intake_enabled is True
- assert not hasattr(args, "enable_intake")
[email protected]("target", ["claude", "codex", "openclaw"])
-def test_launchers_accept_deprecated_intake_alias(
- target: str,
+def test_serve_accepts_deprecated_intake_alias(
caplog: pytest.LogCaptureFixture,
) -> None:
caplog.set_level(logging.WARNING, "switchyard.cli.switchyard_cli")
-
- args = _build_parser().parse_args([
- "launch",
- target,
- "--model",
- "nvidia/moonshotai/kimi-k2.5",
- "--enable-intake",
- ])
-
+ args = _build_parser().parse_args([*_SERVE, "--enable-intake"])
assert args.intake_enabled is True
- assert not hasattr(args, "enable_intake")
assert "--enable-intake is deprecated; use --intake-enabled" in caplog.text
-COMMON_INTAKE_ARGS = [
- "--intake-base-url", "https://nmp.example",
- "--intake-workspace", "workspace-a",
- "--intake-api-key", "ci-token",
- "--intake-target-url", "https://data-lake.example/posting",
-]
-
-
-def _assert_common_intake_args(args: argparse.Namespace) -> None:
+def test_serve_accepts_intake_connection_options() -> None:
+ args = _build_parser().parse_args(
+ [
+ *_SERVE,
+ "--intake-base-url",
+ "https://nmp.example",
+ "--intake-workspace",
+ "workspace-a",
+ "--intake-api-key",
+ "ci-token",
+ "--intake-target-url",
+ "https://data-lake.example/posting",
+ ]
+ )
assert args.intake_base_url == "https://nmp.example"
assert args.intake_workspace == "workspace-a"
assert args.intake_api_key == "ci-token"
assert args.intake_target_url == "https://data-lake.example/posting"
-
-
-def test_serve_accepts_common_intake_args() -> None:
- args = _build_parser().parse_args(["serve", *COMMON_INTAKE_ARGS])
-
- _assert_common_intake_args(args)
-
-
[email protected]("target", ["claude", "codex", "openclaw"])
-def test_launchers_accept_common_intake_args(target: str) -> None:
- args = _build_parser().parse_args([
- "launch",
- target,
- "--model",
- "nvidia/moonshotai/kimi-k2.5",
- *COMMON_INTAKE_ARGS,
- ])
-
- _assert_common_intake_args(args)
diff --git a/tests/test_intake_target.py b/tests/test_intake_target.py
index 6b47f309b..edbb91230 100644
--- a/tests/test_intake_target.py
+++ b/tests/test_intake_target.py
@@ -1,84 +1,38 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Tests for intake target-URL CLI/env wiring into the intake sink config."""
+"""Tests for Intake target URL resolution on ``switchyard serve``."""
import argparse
from switchyard.cli.intake_cli_config import IntakeCliConfig
-from switchyard.cli.launchers.launch_intake_config import LaunchIntakeConfig
-_URL = "https://data-lake.example/lake/example-project/posting"
-
-def test_launch_args_resolve_target_from_flag() -> None:
- args = argparse.Namespace(intake_enabled=True, intake_target_url=_URL)
- resolved = IntakeCliConfig.from_launch_args(args, env={})
- assert resolved.target_url == _URL
-
-
-def test_launch_args_resolve_target_from_env() -> None:
- args = argparse.Namespace(intake_enabled=True, intake_target_url=None)
- resolved = IntakeCliConfig.from_launch_args(
- args, env={"SWITCHYARD_INTAKE_TARGET_URL": "https://from-env.example/posting"}
- )
- assert resolved.target_url == "https://from-env.example/posting"
-
-
-def test_flag_wins_over_env() -> None:
+def test_server_target_flag_wins_over_environment() -> None:
args = argparse.Namespace(
- intake_enabled=True, intake_target_url="https://from-flag.example/posting"
+ intake_enabled=True,
+ intake_target_url="https://from-flag.example/posting",
)
- resolved = IntakeCliConfig.from_launch_args(
- args, env={"SWITCHYARD_INTAKE_TARGET_URL": "https://from-env.example/posting"}
+ resolved = IntakeCliConfig.from_server_args(
+ args,
+ env={"SWITCHYARD_INTAKE_TARGET_URL": "https://from-env.example/posting"},
)
assert resolved.target_url == "https://from-flag.example/posting"
-def test_server_args_resolve_target() -> None:
- args = argparse.Namespace(intake_enabled=True, intake_target_url=_URL)
- resolved = IntakeCliConfig.from_server_args(args, env={})
- assert resolved.target_url == _URL
-
-
-def test_target_absent_defaults_to_none() -> None:
+def test_server_target_resolves_from_environment() -> None:
args = argparse.Namespace(intake_enabled=True, intake_target_url=None)
- resolved = IntakeCliConfig.from_launch_args(args, env={})
- assert resolved.target_url is None
-
-
-def test_to_sink_config_passes_target_through_binding() -> None:
- config = LaunchIntakeConfig(
- base_url=None,
- workspace=None,
- api_key=None,
- app="claude-code",
- task="developer-session",
- session_id="sess-1",
- user_id="0badf00d",
- target_url=_URL,
+ resolved = IntakeCliConfig.from_server_args(
+ args,
+ env={"SWITCHYARD_INTAKE_TARGET_URL": "https://from-env.example/posting"},
)
- sink = config.to_sink_config()
- assert sink.target_url == _URL
- # A target URL alone defaults to the flat, unauthenticated data-lake shape.
- assert sink.target_format == "flat_document"
- assert sink.target_authenticated is False
-
-
-def test_launch_env_var_enables_intake() -> None:
- # SWITCHYARD_INTAKE_ENABLED turns intake on for launch (parity with serve).
- args = argparse.Namespace(intake_enabled=False, intake_target_url=None)
- resolved = IntakeCliConfig.from_launch_args(args, env={"SWITCHYARD_INTAKE_ENABLED": "1"})
- assert resolved.enabled is True
-
-
-def test_launch_disabled_without_flag_or_env() -> None:
- args = argparse.Namespace(intake_enabled=False, intake_target_url=None)
- resolved = IntakeCliConfig.from_launch_args(args, env={})
- assert resolved.enabled is False
+ assert resolved.target_url == "https://from-env.example/posting"
-def test_server_env_var_enables_intake() -> None:
+def test_server_environment_can_enable_intake() -> None:
args = argparse.Namespace(intake_enabled=False, intake_target_url=None)
- resolved = IntakeCliConfig.from_server_args(args, env={"SWITCHYARD_INTAKE_ENABLED": "1"})
+ resolved = IntakeCliConfig.from_server_args(
+ args,
+ env={"SWITCHYARD_INTAKE_ENABLED": "1"},
+ )
assert resolved.enabled is True
diff --git a/tests/test_intake_user_id.py b/tests/test_intake_user_id.py
deleted file mode 100644
index 51820bdce..000000000
--- a/tests/test_intake_user_id.py
+++ /dev/null
@@ -1,104 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Tests for the anonymous per-machine intake user id."""
-
-from __future__ import annotations
-
-import argparse
-import re
-from pathlib import Path
-
-from switchyard.cli.intake_cli_config import IntakeCliConfig
-from switchyard.cli.launchers.launch_intake_config import (
- LaunchIntakeConfig,
- resolve_machine_user_id,
-)
-
-_HEX_8 = re.compile(r"^[0-9a-f]{8}$")
-
-
-def test_resolve_creates_stable_anonymous_id(tmp_path: Path) -> None:
- target = tmp_path / "user_id"
- first = resolve_machine_user_id(target)
- assert _HEX_8.match(first)
- assert target.read_text(encoding="utf-8").strip() == first
- # Second call reuses the persisted id rather than minting a new one.
- assert resolve_machine_user_id(target) == first
-
-
-def test_resolve_reads_existing_id(tmp_path: Path) -> None:
- target = tmp_path / "user_id"
- target.write_text("cafebabe", encoding="utf-8")
- assert resolve_machine_user_id(target) == "cafebabe"
-
-
-def test_resolve_is_fail_open_when_unwritable(tmp_path: Path) -> None:
- # A directory where the id file path is itself a directory cannot be read
- # or written; resolution must still return a usable id.
- target = tmp_path / "user_id"
- target.mkdir()
- assert _HEX_8.match(resolve_machine_user_id(target))
-
-
-def test_resolve_fails_open_when_home_unresolvable(monkeypatch) -> None:
- # Path.home() raises RuntimeError when no home dir resolves; resolution
- # must still return a usable id rather than abort the launch.
- import switchyard.cli.launchers.launch_intake_config as mod
-
- def _boom() -> Path:
- raise RuntimeError("no home directory")
-
- monkeypatch.setattr(mod, "_machine_user_id_path", _boom)
- assert _HEX_8.match(resolve_machine_user_id())
-
-
-def test_resolve_regenerates_on_malformed_or_corrupt_file(tmp_path: Path) -> None:
- # Non-hex text and undecodable bytes must fail open to a fresh valid id,
- # not abort the launch.
- text_target = tmp_path / "text_user_id"
- text_target.write_text("not-a-valid-id", encoding="utf-8")
- assert _HEX_8.match(resolve_machine_user_id(text_target))
-
- bytes_target = tmp_path / "bytes_user_id"
- bytes_target.write_bytes(b"\xff\xfe\x00bad")
- assert _HEX_8.match(resolve_machine_user_id(bytes_target))
-
-
-def test_from_resolved_prefers_explicit_user_id(tmp_path: Path) -> None:
- config = LaunchIntakeConfig.from_resolved(
- base_url=None,
- workspace=None,
- api_key=None,
- app="claude-code",
- task="developer-session",
- session_id="sess-1",
- user_id="deadbeef",
- target="claude",
- )
- assert config.user_id == "deadbeef"
-
-
-def test_to_sink_config_passes_user_id() -> None:
- config = LaunchIntakeConfig(
- base_url=None,
- workspace=None,
- api_key=None,
- app="claude-code",
- task="developer-session",
- session_id="sess-1",
- user_id="deadbeef",
- )
- assert config.to_sink_config().user_id == "deadbeef"
-
-
-def test_from_launch_args_resolves_user_id_from_env() -> None:
- args = argparse.Namespace(intake_enabled=True, intake_user_id=None)
- resolved = IntakeCliConfig.from_launch_args(args, env={"SWITCHYARD_USER_ID": "0badf00d"})
- assert resolved.user_id == "0badf00d"
-
-
-def test_from_launch_args_prefers_flag_over_env() -> None:
- args = argparse.Namespace(intake_enabled=True, intake_user_id="11112222")
- resolved = IntakeCliConfig.from_launch_args(args, env={"SWITCHYARD_USER_ID": "0badf00d"})
- assert resolved.user_id == "11112222"
diff --git a/tests/test_launch_claude.py b/tests/test_launch_claude.py
deleted file mode 100644
index 6bee53ba1..000000000
--- a/tests/test_launch_claude.py
+++ /dev/null
@@ -1,1475 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Tests for ``switchyard.cli.launchers.claude_code_launcher``.
-
-Exercises the public ``launch_claude`` entry, the private model-rewrite
-request processor, and the ``claude`` binary lookup. Real uvicorn and
-``subprocess.run`` are mocked — these tests don't start a server or
-spawn a child process.
-"""
-
-import argparse
-import asyncio
-import logging
-import subprocess
-from pathlib import Path
-from typing import cast
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-from switchyard.cli.configure_request import ConfigureRequest
-from switchyard.cli.launchers.claude_code_launcher import (
- _EXIT_BINARY_NOT_FOUND,
- _EXIT_SIGINT,
- ProxyHealthMonitor,
- _find_claude_binary,
- _find_free_port,
- _make_footer_fn,
- _ModelRewriteRequestProcessor,
- _print_ready_banner,
- launch_claude,
-)
-from switchyard.cli.launchers.launch_intake_config import LaunchIntakeConfig
-from switchyard.lib.backends.llm_target import LlmTarget
-from switchyard.lib.processors.model_rewrite_request_processor import (
- ModelRewriteRequestProcessor,
-)
-from switchyard.lib.profiles.random_routing import RandomRoutingConfig
-from switchyard.lib.proxy_context import ProxyContext
-from switchyard.lib.route_table import RouteTable
-from switchyard.lib.route_table_builders import (
- random_routing_virtual_model_id,
-)
-from switchyard.lib.stats_accumulator import StatsAccumulator
-from switchyard_rust.core import ChatRequest
-
-
-def test_random_routing_virtual_model_id_is_client_neutral() -> None:
- config = RandomRoutingConfig(
- strong=LlmTarget(model="azure/anthropic/claude-opus-4-7"),
- weak=LlmTarget(model="nvidia/nvidia/nemotron-3-super-120b-long-ctx"),
- strong_probability=0.25,
- fallback_target_on_evict="strong",
- )
-
- model = random_routing_virtual_model_id(config)
-
- assert model.startswith("switchyard-default-random-")
- assert "/" not in model
- assert "claude-opus-4-7" not in model
- assert "nemotron-3-super-120b-long-ctx" not in model
-
-
-def test_bootstrap_persists_selected_env_provider_base_url(monkeypatch, tmp_path) -> None:
- from switchyard.cli.launch_command import maybe_bootstrap_launch_config
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- for env_var in (
- "OPENROUTER_API_KEY",
- "OPENROUTER_BASE_URL",
- "NVIDIA_API_KEY",
- "NVIDIA_BASE_URL",
- "OPENAI_API_KEY",
- "OPENAI_BASE_URL",
- "ANTHROPIC_API_KEY",
- ):
- monkeypatch.delenv(env_var, raising=False)
- monkeypatch.setenv("NVIDIA_API_KEY", "nvidia-key")
- monkeypatch.setenv("NVIDIA_BASE_URL", "https://nvidia.test/v1")
- monkeypatch.setattr("switchyard.cli.launch_command.is_interactive_terminal", lambda: True)
- monkeypatch.setattr("switchyard.cli.launch_command.load_secrets", lambda: {})
- captured: dict[str, ConfigureRequest] = {}
- monkeypatch.setattr(
- "switchyard.cli.launch_command.cmd_configure",
- lambda configure_request: captured.setdefault("request", configure_request),
- )
-
- args = argparse.Namespace(
- reconfigure=True,
- api_key=None,
- base_url=None,
- model="nvidia/model",
- routing_profiles=None,
- no_model_discovery=True,
- no_tui=True,
- )
-
- maybe_bootstrap_launch_config(
- args,
- target="claude",
- api_key_env_vars=(
- "OPENROUTER_API_KEY",
- "NVIDIA_API_KEY",
- "OPENAI_API_KEY",
- "ANTHROPIC_API_KEY",
- ),
- )
-
- configure_request = captured["request"]
- assert configure_request.provider == "nvidia"
- assert configure_request.base_url == "https://nvidia.test/v1"
- assert configure_request.prompt_default_api_key == "nvidia-key" # pragma: allowlist secret
- assert configure_request.prompt_default_api_key_source == "$NVIDIA_API_KEY"
-
- # Setup leaves these three at their ConfigureRequest defaults. Assert them
- # directly so a regression in any one field fails here, not mid-launch: a
- # missing default is exactly what crashed the first run before this fix.
- assert configure_request.routing_profiles is None
- assert configure_request.skill_distillation is None
- assert configure_request.disable_skill_distillation is False
-
- # The request setup builds must work with the real configure helpers. Before
- # the typed ConfigureRequest, setup passed a hand-built namespace missing the
- # skill-distillation fields, and these helpers crashed with AttributeError.
- from switchyard.cli.config.user_config import SkillDistillationConfig
- from switchyard.cli.configure_command import (
- _apply_skill_distillation_args,
- _skill_only_config_update,
- )
-
- assert (
- _apply_skill_distillation_args(SkillDistillationConfig(), configure_request)
- == SkillDistillationConfig()
- )
- assert _skill_only_config_update(configure_request) is False
-
-
-def test_configure_parser_builds_a_complete_request() -> None:
- # A real `switchyard configure` parse must fill every ConfigureRequest field
- # through the one from_namespace boundary. This is the check the original bug
- # lacked: disable_skill_distillation is the field that crashed first-run.
- from switchyard.cli.switchyard_cli import _build_parser
-
- namespace = _build_parser().parse_args(["configure"])
- request = ConfigureRequest.from_namespace(namespace)
-
- # --provider defaults to None so it can't shadow a saved default_provider;
- # cmd_configure resolves the effective provider from the saved config.
- assert request.provider is None
- assert request.disable_skill_distillation is False
- assert request.routing_profiles is None # the global flag is merged in
-
-
-def test_main_forwards_harness_args_after_separator(monkeypatch, tmp_path) -> None:
- """``launch claude ... -- --version`` forwards harness args past the ``--``.
-
- main() must only strip a ``--`` that occurs before the subcommand token,
- so the launcher-side ``--`` separating claude args survives argparse and
- the forwarded args reach ``launch_claude`` intact. Before the fix the first
- ``--`` was popped unconditionally, so ``--version`` hit argparse as an
- unrecognized argument (``SystemExit(2)``).
- """
- import sys
-
- from switchyard.cli import switchyard_cli as cli
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- sys, "argv",
- [
- "switchyard", "launch", "claude",
- "--model", "nvidia/x", "--api-key", "sk-test",
- "--", "--version",
- ],
- )
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://inference-api.nvidia.com/v1"),
- )
-
- captured: dict = {}
-
- def fake_launch(**kwargs):
- captured.update(kwargs)
- raise SystemExit(0)
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher.launch_claude",
- fake_launch,
- )
-
- with pytest.raises(SystemExit) as excinfo:
- cli.main()
-
- assert excinfo.value.code == 0
- assert captured["claude_args"] == ["--version"]
-
-
-# ---------------------------------------------------------------------------
-# _ModelRewriteRequestProcessor
-# ---------------------------------------------------------------------------
-
-
-class TestModelRewriteRequestProcessor:
- """Processor must rewrite ``body['model']`` for every ChatRequest subclass."""
-
- async def test_rewrites_anthropic_request(self):
- proc = _ModelRewriteRequestProcessor("nvidia/moonshotai/kimi-k2.5")
- req = ChatRequest.anthropic({
- "model": "claude-sonnet-4-5",
- "messages": [{"role": "user", "content": "hi"}],
- "max_tokens": 100,
- })
- out = await proc.process(ProxyContext(), req)
- assert out is req
- assert req.body["model"] == "nvidia/moonshotai/kimi-k2.5"
-
- async def test_rewrites_openai_chat_request(self):
- proc = _ModelRewriteRequestProcessor("target-model")
- req = ChatRequest.openai_chat({"model": "gpt-4o", "messages": []})
- await proc.process(ProxyContext(), req)
- assert req.body["model"] == "target-model"
-
- async def test_rewrites_responses_request(self):
- proc = _ModelRewriteRequestProcessor("target-model")
- req = ChatRequest.openai_responses({"model": "gpt-4o", "input": "hi"})
- await proc.process(ProxyContext(), req)
- assert req.body["model"] == "target-model"
-
-
-# ---------------------------------------------------------------------------
-# _find_claude_binary
-# ---------------------------------------------------------------------------
-
-
-class TestFindClaudeBinary:
- def test_returns_path_hit_when_on_path(self):
- with patch("shutil.which", return_value="/usr/local/bin/claude"):
- assert _find_claude_binary() == "/usr/local/bin/claude"
-
- def test_falls_back_to_claude_local(self, tmp_path, monkeypatch):
- monkeypatch.setattr("shutil.which", lambda _: None)
- fake_home = tmp_path
- monkeypatch.setattr(Path, "home", lambda: fake_home)
- claude = fake_home / ".claude" / "local" / "claude"
- claude.parent.mkdir(parents=True)
- claude.write_text("#!/bin/sh\necho claude\n")
- claude.chmod(0o755)
- assert _find_claude_binary() == str(claude)
-
- def test_falls_back_to_local_bin(self, tmp_path, monkeypatch):
- monkeypatch.setattr("shutil.which", lambda _: None)
- fake_home = tmp_path
- monkeypatch.setattr(Path, "home", lambda: fake_home)
- claude = fake_home / ".local" / "bin" / "claude"
- claude.parent.mkdir(parents=True)
- claude.write_text("#!/bin/sh\necho claude\n")
- claude.chmod(0o755)
- assert _find_claude_binary() == str(claude)
-
- def test_returns_none_when_nowhere(self, tmp_path, monkeypatch):
- monkeypatch.setattr("shutil.which", lambda _: None)
- monkeypatch.setattr(Path, "home", lambda: tmp_path)
- assert _find_claude_binary() is None
-
-
-# ---------------------------------------------------------------------------
-# _find_free_port
-# ---------------------------------------------------------------------------
-
-
-class TestFindFreePort:
- def test_returns_usable_port(self):
- port = _find_free_port()
- assert 1024 <= port <= 65535
-
-
-# ---------------------------------------------------------------------------
-# launch_claude — integration (with mocked externals)
-# ---------------------------------------------------------------------------
-
-
-def _make_fake_server(started: bool = True) -> MagicMock:
- """uvicorn.Server stand-in that reports started immediately."""
- server = MagicMock()
- server.started = started
- server.should_exit = False
- return server
-
-
-def _stub_spawn_proxy(server: MagicMock):
- """Return a function that mimics _spawn_proxy_thread's (server, thread) tuple."""
- def _inner(switchyard, port):
- thread = MagicMock()
- return server, thread
- return _inner
-
-
[email protected](autouse=True)
-def _mock_probe(monkeypatch, tmp_path):
- """Mock external launcher side effects in all tests."""
- monkeypatch.setattr(
- "switchyard.lib.backends.backend_format_resolver.probe_openai_chat_completions_support_sync",
- lambda **_: False,
- )
- monkeypatch.setattr(
- "switchyard.lib.backends.backend_format_resolver.probe_anthropic_messages_support_sync",
- lambda **_: False,
- )
- monkeypatch.setattr(
- "switchyard.lib.backends.backend_format_resolver.probe_openai_responses_support_sync",
- lambda **_: False,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._wait_ready",
- lambda port, timeout_s=10.0: True,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher.configure_debug_file_logging",
- lambda display_model: tmp_path / "switchyard.log",
- )
- # pytest redirects stdin to a pseudofile with no real fd;
- # isatty would raise UnsupportedOperation — force non-TTY mode.
- monkeypatch.setattr("os.isatty", lambda fd: False)
-
-
-class TestLaunchClaude:
- def test_happy_path(self, monkeypatch):
- fake_server = _make_fake_server(started=True)
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._find_claude_binary",
- lambda: "/fake/bin/claude",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._spawn_proxy_thread",
- _stub_spawn_proxy(fake_server),
- )
-
- captured: dict = {}
-
- def fake_run(cmd, env, check):
- captured["cmd"] = cmd
- captured["env"] = env
- return subprocess.CompletedProcess(cmd, returncode=0)
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- exit_code = launch_claude(
- model="nvidia/moonshotai/kimi-k2.5",
- base_url="https://inference-api.nvidia.com/v1",
- api_key="test-key",
- port=None,
- timeout=None,
- claude_args=["--version"],
- )
-
- assert exit_code == 0
- assert captured["cmd"] == ["/fake/bin/claude", "--version"]
- assert captured["env"]["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:54321"
- # ANTHROPIC_AUTH_TOKEN tells Claude Code auth is external, skipping
- # the Console / 3rd-party provider setup wizard. ANTHROPIC_API_KEY
- # is emptied to suppress the "Auth conflict" warning.
- assert captured["env"]["ANTHROPIC_AUTH_TOKEN"] == "switchyard"
- assert captured["env"]["ANTHROPIC_API_KEY"] == ""
- # ANTHROPIC_MODEL / ANTHROPIC_SMALL_FAST_MODEL set Claude Code's
- # initial active model. Selecting a builtin via /model overrides
- # this at runtime.
- assert captured["env"]["ANTHROPIC_MODEL"] == "nvidia/moonshotai/kimi-k2.5"
- assert captured["env"]["ANTHROPIC_SMALL_FAST_MODEL"] == "nvidia/moonshotai/kimi-k2.5"
- assert captured["env"]["CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY"] == "1"
- # ANTHROPIC_CUSTOM_MODEL_OPTION registers the Switchyard-routed model
- # as a *persistent* /model picker entry — the picker reads this on
- # every render, so the entry survives toggling to a builtin.
- assert captured["env"]["ANTHROPIC_CUSTOM_MODEL_OPTION"] == "nvidia/moonshotai/kimi-k2.5"
- assert "ANTHROPIC_CUSTOM_MODEL_OPTION_NAME" not in captured["env"]
- assert "ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION" not in captured["env"]
- # Proxy torn down on return
- assert fake_server.should_exit is True
-
- def test_intake_injects_custom_headers(self, monkeypatch):
- fake_server = _make_fake_server(started=True)
- fake_sdk = MagicMock()
- fake_sdk.workspace = "sdk-workspace"
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._find_claude_binary",
- lambda: "/fake/bin/claude",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._spawn_proxy_thread",
- _stub_spawn_proxy(fake_server),
- )
- monkeypatch.setattr(
- "switchyard.lib.processors.intake_client._build_sdk_client",
- lambda config: fake_sdk,
- )
-
- captured: dict = {}
-
- def fake_run(cmd, env, check):
- captured["env"] = env
- return subprocess.CompletedProcess(cmd, returncode=0)
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- intake = LaunchIntakeConfig.from_resolved(
- base_url="https://intake.example",
- workspace=None,
- api_key=None,
- app="claude-code",
- task="developer-session",
- session_id="sess-xyz",
- target="claude",
- )
- exit_code = launch_claude(
- model="nvidia/moonshotai/kimi-k2.5",
- base_url="https://inference-api.nvidia.com/v1",
- api_key="test-key",
- port=None,
- timeout=None,
- claude_args=[],
- intake=intake,
- )
-
- assert exit_code == 0
- assert captured["env"]["SWITCHYARD_SESSION_ID"] == "sess-xyz"
- custom = captured["env"]["ANTHROPIC_CUSTOM_HEADERS"]
- assert "x-switchyard-intake-enabled: true" in custom
- assert "x-switchyard-intake-app: claude-code" in custom
- assert "proxy_x_session_id: sess-xyz" in custom
-
- def test_port_override(self, monkeypatch):
- fake_server = _make_fake_server(started=True)
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._find_claude_binary",
- lambda: "/fake/bin/claude",
- )
-
- # If --port is set, _find_free_port should NOT be called
- def _should_not_be_called():
- raise AssertionError("_find_free_port called despite --port override")
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._find_free_port",
- _should_not_be_called,
- )
-
- captured: dict = {}
-
- def stub_spawn(switchyard, port):
- captured["port"] = port
- thread = MagicMock()
- return fake_server, thread
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._spawn_proxy_thread",
- stub_spawn,
- )
- monkeypatch.setattr(
- subprocess, "run",
- lambda cmd, env, check: subprocess.CompletedProcess(cmd, returncode=0),
- )
-
- exit_code = launch_claude(
- model="m", base_url="u", api_key="k",
- port=4000, timeout=None, claude_args=[],
- )
-
- assert exit_code == 0
- assert captured["port"] == 4000
-
- def test_missing_binary_returns_127(self, monkeypatch):
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._find_claude_binary",
- lambda: None,
- )
-
- # If we reach _spawn_proxy_thread, we failed to short-circuit
- def _should_not_spawn(*args, **kwargs):
- raise AssertionError("proxy spawned despite missing binary")
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._spawn_proxy_thread",
- _should_not_spawn,
- )
-
- exit_code = launch_claude(
- model="m", base_url="u", api_key="k",
- port=None, timeout=None, claude_args=[],
- )
- assert exit_code == _EXIT_BINARY_NOT_FOUND
-
- def test_ctrl_c_returns_130_and_tears_down(self, monkeypatch):
- fake_server = _make_fake_server(started=True)
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._find_claude_binary",
- lambda: "/fake/bin/claude",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._spawn_proxy_thread",
- _stub_spawn_proxy(fake_server),
- )
-
- def raise_sigint(cmd, env, check):
- raise KeyboardInterrupt()
- monkeypatch.setattr(subprocess, "run", raise_sigint)
-
- exit_code = launch_claude(
- model="m", base_url="u", api_key="k",
- port=None, timeout=None, claude_args=[],
- )
-
- assert exit_code == _EXIT_SIGINT
- assert fake_server.should_exit is True
-
- def test_strips_leading_double_dash_from_claude_args(self, monkeypatch, tmp_path):
- """``argparse.REMAINDER`` keeps the ``--`` sentinel in the captured
- list, so ``launch claude ... -- --version`` produces
- ``['--', '--version']``. The handler must strip the leading ``--``
- before forwarding so ``subprocess.run`` doesn't receive a bare
- ``--`` as an arg.
- """
- from switchyard.cli.switchyard_cli import (
- _build_parser,
- _cmd_launch_claude,
- )
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "claude",
- "--model", "nvidia/moonshotai/kimi-k2.5",
- "--api-key", "sk-test",
- "--", "--version",
- ])
- assert args.claude_args == ["--", "--version"] # argparse kept '--'
-
- captured: dict = {}
-
- def fake_launch(**kwargs):
- captured.update(kwargs)
- raise SystemExit(0)
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://inference-api.nvidia.com/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher.launch_claude",
- fake_launch,
- )
-
- with pytest.raises(SystemExit):
- _cmd_launch_claude(args)
-
- # Handler stripped the '--' before forwarding.
- assert captured["claude_args"] == ["--version"]
-
- def test_cmd_launch_claude_resolves_intake_args(self, monkeypatch, tmp_path):
- from switchyard.cli.switchyard_cli import (
- _build_parser,
- _cmd_launch_claude,
- )
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "claude",
- "--model", "nvidia/moonshotai/kimi-k2.5",
- "--api-key", "sk-test",
- "--intake-enabled",
- "--intake-base-url", "https://nmp.example",
- "--intake-api-key", "ci-token",
- "--intake-app", "cli-app",
- "--intake-task", "custom-task",
- "--intake-session-id", "sess-cli",
- ])
-
- captured: dict = {}
-
- def fake_launch(**kwargs):
- captured.update(kwargs)
- raise SystemExit(0)
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://inference-api.nvidia.com/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher.launch_claude",
- fake_launch,
- )
-
- with pytest.raises(SystemExit):
- _cmd_launch_claude(args)
-
- intake = captured["intake"]
- assert intake.base_url == "https://nmp.example"
- assert intake.api_key == "ci-token"
- assert intake.app == "cli-app"
- assert intake.task == "custom-task"
- assert intake.session_id == "sess-cli"
-
- def test_selects_native_backend_when_probe_true(self, monkeypatch):
- """Probe returning True -> chain stats-wraps an Anthropic-native backend."""
- from switchyard.lib.backends.stats_llm_backend import StatsLlmBackend
-
- monkeypatch.setattr(
- "switchyard.lib.backends.backend_format_resolver."
- "probe_anthropic_messages_support_sync",
- lambda **_: True,
- )
-
- model = "aws/anthropic/bedrock-claude-opus-4-6"
- captured_switchyard: dict = {}
-
- def stub_spawn(app, port):
- assert isinstance(app, RouteTable)
- chain = app.lookup_switchyard(model)
- captured_switchyard["app"] = app
- captured_switchyard["switchyard"] = chain
- captured_switchyard["backend"] = next(
- component
- for component in chain.iter_components()
- if isinstance(component, StatsLlmBackend)
- )
- fake_server = _make_fake_server(started=True)
- return fake_server, MagicMock()
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._find_claude_binary",
- lambda: "/fake/bin/claude",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._spawn_proxy_thread",
- stub_spawn,
- )
- monkeypatch.setattr(
- subprocess, "run",
- lambda cmd, env, check: subprocess.CompletedProcess(cmd, returncode=0),
- )
-
- launch_claude(
- model=model,
- base_url="https://inference-api.nvidia.com/v1",
- api_key="sk-test",
- port=None, timeout=None, claude_args=[],
- )
- table = captured_switchyard["app"]
- assert table.registered_models() == [f"claude-{model}", model]
- assert table.default_model() == model
- assert table.lookup_switchyard(f"claude-{model}") is table.lookup_switchyard(model)
- backend = captured_switchyard["backend"]
- assert isinstance(backend, StatsLlmBackend)
- assert [item.value for item in backend.supported_request_types] == ["anthropic"]
- assert not any(
- isinstance(component, ModelRewriteRequestProcessor)
- for component in captured_switchyard["switchyard"].iter_components()
- )
-
- def test_selects_translated_backend_when_probe_false(self, monkeypatch):
- """Probe returning False -> chain stats-wraps an OpenAI-native backend."""
- from switchyard.lib.backends.stats_llm_backend import StatsLlmBackend
- # Default autouse fixture already sets probe to False; no override needed.
-
- model = "nvidia/moonshotai/kimi-k2.5"
- captured_switchyard: dict = {}
-
- def stub_spawn(app, port):
- assert isinstance(app, RouteTable)
- chain = app.lookup_switchyard(model)
- captured_switchyard["app"] = app
- captured_switchyard["switchyard"] = chain
- captured_switchyard["backend"] = next(
- component
- for component in chain.iter_components()
- if isinstance(component, StatsLlmBackend)
- )
- fake_server = _make_fake_server(started=True)
- return fake_server, MagicMock()
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._find_claude_binary",
- lambda: "/fake/bin/claude",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._spawn_proxy_thread",
- stub_spawn,
- )
- monkeypatch.setattr(
- subprocess, "run",
- lambda cmd, env, check: subprocess.CompletedProcess(cmd, returncode=0),
- )
-
- launch_claude(
- model=model,
- base_url="https://inference-api.nvidia.com/v1",
- api_key="sk-test",
- port=None, timeout=None, claude_args=[],
- )
- table = captured_switchyard["app"]
- assert table.registered_models() == [f"claude-{model}", model]
- assert table.default_model() == model
- assert table.lookup_switchyard(f"claude-{model}") is table.lookup_switchyard(model)
- backend = captured_switchyard["backend"]
- assert isinstance(backend, StatsLlmBackend)
- assert [item.value for item in backend.supported_request_types] == ["openai_chat"]
- assert not any(
- isinstance(component, ModelRewriteRequestProcessor)
- for component in captured_switchyard["switchyard"].iter_components()
- )
-
- def test_smoke_with_routing_profiles_errors_clearly(
- self, monkeypatch, tmp_path,
- ):
- """``--smoke --routing-profiles FILE`` is rejected at the CLI level."""
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_claude
-
- yaml_path = tmp_path / "bundle.yaml"
- yaml_path.write_text(
- "routes:\n"
- " fast-nemotron:\n"
- " type: model\n"
- " target: nvidia/nvidia/nemotron-nano-9b-v2\n"
- )
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://inference-api.nvidia.com/v1"),
- )
- parser = _build_parser()
- args = parser.parse_args([
- "--routing-profiles", str(yaml_path),
- "launch", "claude", "--smoke", "--api-key", "sk-test",
- ])
- with pytest.raises(SystemExit) as exc_info:
- _cmd_launch_claude(args)
- assert "--smoke and --routing-profiles cannot be combined" in str(exc_info.value)
-
- def test_smoke_without_model_errors_with_helpful_message(
- self, monkeypatch, tmp_path,
- ):
- """``--smoke`` with no model gives a clear error directing to ``--model``."""
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_claude
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://inference-api.nvidia.com/v1"),
- )
- parser = _build_parser()
- args = parser.parse_args(["launch", "claude", "--smoke", "--api-key", "sk-test"])
- with pytest.raises(SystemExit) as exc_info:
- _cmd_launch_claude(args)
- assert "--smoke requires --model" in str(exc_info.value)
-
- def test_routing_profiles_merges_extras_on_top_of_launcher_table(
- self, monkeypatch, tmp_path,
- ):
- """`--routing-profiles` adds YAML routes on top of the launcher's chain.
-
- The launcher registers its own ``--model`` chain under ``model``;
- every YAML entry is merged on top via
- :meth:`RouteTable.register`. YAML wins on id conflict.
- """
- captured_switchyard: dict = {}
-
- def stub_spawn(switchyard, port):
- captured_switchyard["app"] = switchyard
- fake_server = _make_fake_server(started=True)
- return fake_server, MagicMock()
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._find_claude_binary",
- lambda: "/fake/bin/claude",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._spawn_proxy_thread",
- stub_spawn,
- )
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda cmd, env, check: subprocess.CompletedProcess(cmd, returncode=0),
- )
-
- yaml_path = tmp_path / "extras.yaml"
- yaml_path.write_text(
- "routes:\n"
- " extras/yaml-only:\n"
- " type: model\n"
- " target:\n"
- " model: extras/yaml-only\n"
- " api_key: sk-yaml\n"
- " base_url: https://yaml.example/v1\n"
- " primary/model:\n"
- " type: model\n"
- " target:\n"
- " model: primary/model\n"
- " api_key: sk-yaml-override\n"
- " base_url: https://yaml-override.example/v1\n"
- )
-
- launch_claude(
- model="primary/model",
- base_url="https://example.invalid/v1",
- api_key="sk-test",
- port=None,
- timeout=None,
- claude_args=[],
- routing_profiles=str(yaml_path),
- )
-
- table = captured_switchyard["app"]
- assert isinstance(table, RouteTable)
-
- # Launcher registers `primary/model`; YAML overrides it in place and
- # adds `extras/yaml-only`. The claude launcher also exposes each
- # non-prefixed id under a `claude-` alias (same chain object) so
- # Claude Code's gateway-discovery filter accepts the full listing.
- # Aliases come right before their originals in iteration order.
- assert table.registered_models() == [
- "claude-primary/model",
- "primary/model",
- "claude-extras/yaml-only",
- "extras/yaml-only",
- ]
- # Alias and original resolve to the same chain object.
- assert table.default_model() == "primary/model"
- assert table.lookup_switchyard("claude-extras/yaml-only") is table.lookup_switchyard(
- "extras/yaml-only"
- )
- assert table.lookup_switchyard("claude-primary/model") is table.lookup_switchyard(
- "primary/model"
- )
-
- def test_proxy_never_ready_returns_error(self, monkeypatch):
- fake_server = _make_fake_server(started=False) # never flips to True
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._find_claude_binary",
- lambda: "/fake/bin/claude",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._spawn_proxy_thread",
- _stub_spawn_proxy(fake_server),
- )
- # Override the autouse _wait_ready mock to simulate a timeout.
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._wait_ready",
- lambda port, timeout_s=10.0: False,
- )
-
- def _should_not_run(*args, **kwargs):
- raise AssertionError("claude spawned despite proxy not ready")
- monkeypatch.setattr(subprocess, "run", _should_not_run)
-
- exit_code = launch_claude(
- model="m", base_url="u", api_key="k",
- port=None, timeout=None, claude_args=[],
- )
- assert exit_code == 1
- assert fake_server.should_exit is True
-
-
-# ---------------------------------------------------------------------------
-# _print_ready_banner
-# ---------------------------------------------------------------------------
-
-
-class TestPrintReadyBanner:
- """Banner must surface the proxy URL + stats curl on stderr unconditionally.
-
- Critical because Claude Code's TUI takeover plus the silencer that drops
- ``switchyard`` to WARNING was hiding the previous logger-based
- status line entirely.
- """
-
- def test_includes_proxy_url_and_stats_curl(self, capsys):
- _print_ready_banner(46385, "azure/anthropic/claude-opus-4-6")
- err = capsys.readouterr().err
- assert "http://127.0.0.1:46385" in err
- assert "curl -s http://127.0.0.1:46385/v1/routing/stats" in err
- assert "azure/anthropic/claude-opus-4-6" in err
-
- def test_writes_to_stderr_not_stdout(self, capsys):
- _print_ready_banner(4000, "m")
- captured = capsys.readouterr()
- assert captured.out == ""
- assert "switchyard" in captured.err and "ready" in captured.err
-
- def test_survives_logger_silencing(self, capsys):
- logging.getLogger("switchyard").setLevel(logging.WARNING)
- try:
- _print_ready_banner(4000, "m")
- finally:
- logging.getLogger("switchyard").setLevel(logging.NOTSET)
- assert "http://127.0.0.1:4000" in capsys.readouterr().err
-
-
-# ---------------------------------------------------------------------------
-# _make_footer_fn — passthrough vs random-routing layouts
-# ---------------------------------------------------------------------------
-
-
-class _StubHealth:
- """Minimal stand-in for ``ProxyHealthMonitor`` — the renderer only
- calls ``poll()`` (no-op here) and reads the ``indicator`` tuple.
- Avoids opening a real socket from a unit test.
- """
-
- def __init__(self, indicator: tuple[str, int] = ("●", 1)) -> None:
- self._indicator = indicator
-
- def poll(self) -> None:
- return None
-
- @property
- def indicator(self) -> tuple[str, int]:
- return self._indicator
-
-
-def _strip_ansi(s: str) -> str:
- import re
- return re.sub(r"\x1b\[[0-9;]*m", "", s)
-
-
-def _record_stats(
- stats: StatsAccumulator,
- model: str,
- prompt_tokens: int,
- completion_tokens: int,
- tier: str | None = None,
-) -> None:
- async def _record() -> None:
- await stats.record_success(model=model, tier=tier)
- await stats.record_usage(
- model=model,
- tier=tier,
- prompt_tokens=prompt_tokens,
- completion_tokens=completion_tokens,
- )
-
- asyncio.run(_record())
-
-
-class TestMakeFooterFn:
- """Footer: aggregate row + one row per active model tier."""
-
- def test_renders_two_rows_with_active_model(self):
- stats = StatsAccumulator()
- _record_stats(
- stats,
- model="kimi-k2.5", tier="strong",
- prompt_tokens=800, completion_tokens=400,
- )
- fn = _make_footer_fn(
- stats, "openai/openai/kimi-k2.5", cast(ProxyHealthMonitor, _StubHealth()),
- )
- rows = fn(120)
- assert len(rows) == 2
- agg, tier = (_strip_ansi(r[0]) for r in rows)
- # Aggregate row carries totals but no model name.
- assert "1 req" in agg and "800 in" in agg and "400 out" in agg
- assert "kimi-k2.5" not in agg
- # Tier row carries the model the backend actually saw.
- assert "kimi-k2.5" in tier
- assert "1 req" in tier
-
- def test_renders_two_rows_at_zero_traffic_with_default_label(self):
- stats = StatsAccumulator()
- fn = _make_footer_fn(
- stats, "openai/openai/kimi-k2.5",
- cast(ProxyHealthMonitor, _StubHealth()),
- )
- rows = fn(120)
- assert len(rows) == 2
- # Aggregate is non-empty even at zero traffic; tier falls back to
- # the launch default label.
- assert _strip_ansi(rows[0][0]).strip() != ""
- assert "kimi-k2.5" in _strip_ansi(rows[1][0])
-
- def test_shows_one_row_per_active_tier(self):
- """Two-tier routing → 3 rows total: aggregate + one per model."""
- stats = StatsAccumulator()
- _record_stats(
- stats,
- model="aws/anthropic/bedrock-claude-opus-4-7", tier="strong",
- prompt_tokens=120, completion_tokens=80,
- )
- _record_stats(
- stats,
- model="nvidia/deepseek-ai/evals-deepseek-v4-pro", tier="weak",
- prompt_tokens=200, completion_tokens=150,
- )
- fn = _make_footer_fn(
- stats, "switchyard-deterministic-abc12345",
- cast(ProxyHealthMonitor, _StubHealth()),
- )
- rows = fn(120)
- assert len(rows) == 3
- agg = _strip_ansi(rows[0][0])
- tier_texts = [_strip_ansi(r[0]) for r in rows[1:]]
- # Aggregate sees both calls.
- assert "2 req" in agg
- # Both models appear, one per row.
- all_text = " ".join(tier_texts)
- assert "bedrock-claude-opus-4-7" in all_text
- assert "evals-deepseek-v4-pro" in all_text
-
-_MINIMAL_YAML_BUNDLE = (
- "routes:\n"
- " example/model:\n"
- " type: model\n"
- " target:\n"
- " model: example/model\n"
- " api_key: sk-test\n"
- " base_url: https://example.invalid/v1\n"
-)
-
-
-class TestResolveRoutingProfiles:
- """Precedence rules for the saved-bundle + CLI routing-profile resolution."""
-
- _BUNDLE = {"routes": {"example/model": {"type": "model"}}}
-
- def test_cli_value_wins_over_saved(self, monkeypatch, tmp_path):
- from switchyard.cli.config.user_config import UserConfig, save_user_config
- from switchyard.cli.launch_command import _resolve_routing_profiles
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- save_user_config(UserConfig(routing_profiles=self._BUNDLE))
- args = argparse.Namespace(routing_profiles="/cli/path.yaml", model=None)
- assert _resolve_routing_profiles(args) == "/cli/path.yaml"
-
- def test_saved_bundle_materialized_to_yaml_tempfile(
- self, monkeypatch, tmp_path,
- ):
- """The saved dict is re-serialized to a tempfile path the launcher reads."""
- import yaml
-
- from switchyard.cli.config.user_config import UserConfig, save_user_config
- from switchyard.cli.launch_command import _resolve_routing_profiles
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- save_user_config(UserConfig(routing_profiles=self._BUNDLE))
- args = argparse.Namespace(routing_profiles=None, model=None)
- resolved = _resolve_routing_profiles(args)
- assert resolved is not None
- materialized = Path(resolved)
- assert materialized.exists()
- assert yaml.safe_load(materialized.read_text()) == self._BUNDLE
-
- def test_model_only_does_not_inject_saved(self, monkeypatch, tmp_path):
- """`--model X` alone is an explicit opt-in to single-model; saved bundle stays out."""
- from switchyard.cli.config.user_config import UserConfig, save_user_config
- from switchyard.cli.launch_command import _resolve_routing_profiles
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- save_user_config(UserConfig(routing_profiles=self._BUNDLE))
- args = argparse.Namespace(routing_profiles=None, model="some/model")
- assert _resolve_routing_profiles(args) is None
-
- def test_cli_value_wins_even_with_model_flag(self, monkeypatch, tmp_path):
- """`--model X --routing-profiles Y` composes (CLI path wins, saved ignored)."""
- from switchyard.cli.config.user_config import UserConfig, save_user_config
- from switchyard.cli.launch_command import _resolve_routing_profiles
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- save_user_config(UserConfig(routing_profiles=self._BUNDLE))
- args = argparse.Namespace(
- routing_profiles="/cli/path.yaml", model="some/model",
- )
- assert _resolve_routing_profiles(args) == "/cli/path.yaml"
-
- def test_returns_none_when_nothing_saved_or_passed(self, monkeypatch, tmp_path):
- from switchyard.cli.launch_command import _resolve_routing_profiles
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- args = argparse.Namespace(routing_profiles=None, model=None)
- assert _resolve_routing_profiles(args) is None
-
-
-class TestResolveInitialFromProfiles:
- """First declared route is always returned; --model + --routing-profiles is an error."""
-
- def _write_yaml(self, tmp_path):
- yaml_path = tmp_path / "profiles.yaml"
- yaml_path.write_text(
- "routes:\n"
- " some/route:\n"
- " type: model\n"
- " target:\n"
- " model: some/upstream\n"
- " api_key: sk-test\n"
- " base_url: https://example.invalid/v1\n"
- )
- return str(yaml_path)
-
- def test_returns_first_yaml_route(self, tmp_path):
- from switchyard.cli.launch_command import _resolve_initial_from_profiles
- yaml_path = self._write_yaml(tmp_path)
- assert (
- _resolve_initial_from_profiles(target="codex", routing_profiles=yaml_path)
- == "some/route"
- )
-
- def test_empty_bundle_raises(self, tmp_path):
- from switchyard.cli.launch_command import _resolve_initial_from_profiles
- yaml_path = tmp_path / "empty.yaml"
- yaml_path.write_text("routes:\n direct:\n type: model\n target: some/model\n")
- assert (
- _resolve_initial_from_profiles(target="codex", routing_profiles=str(yaml_path))
- == "direct"
- )
-
- def test_model_and_profiles_mutually_exclusive(self):
- """Runtime check rejects --model + --routing-profiles together for all launchers."""
- from switchyard.cli.launch_command import (
- cmd_launch_claude,
- cmd_launch_codex,
- cmd_launch_openclaw,
- )
- from switchyard.cli.switchyard_cli import _build_parser
- parser = _build_parser()
- handlers = {
- "claude": cmd_launch_claude,
- "codex": cmd_launch_codex,
- "openclaw": cmd_launch_openclaw,
- }
- for cmd, handler in handlers.items():
- # --routing-profiles is now global; --model stays on the launcher
- args = parser.parse_args(
- ["--routing-profiles", "p.yaml", "launch", cmd, "--model", "some/model"]
- )
- with pytest.raises(SystemExit) as exc:
- handler(args)
- assert exc.value.code != 0 or "mutually exclusive" in str(exc.value)
-
-
-class TestServeRoutingProfilesFallback:
- """`switchyard serve` falls back to the saved parsed bundle (no tempfile)."""
-
- _BUNDLE = {
- "routes": {
- "example/model": {
- "type": "model",
- "target": {
- "model": "example/model",
- "api_key": "sk-test",
- "base_url": "https://example.invalid/v1",
- },
- },
- },
- }
-
- def test_falls_back_to_saved_bundle_when_cli_omitted(
- self, monkeypatch, tmp_path,
- ):
- """Saved dict feeds straight into build_route_bundle_table."""
- from switchyard.cli.config.user_config import UserConfig, save_user_config
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_serve
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- save_user_config(UserConfig(routing_profiles=self._BUNDLE))
-
- captured: dict = {}
-
- def fake_build_and_serve(args, table, inbound_default, **_kwargs):
- captured["registered_models"] = table.registered_models()
- captured["inbound_default"] = inbound_default
-
- monkeypatch.setattr(
- "switchyard.cli.switchyard_cli.build_and_serve",
- fake_build_and_serve,
- )
-
- parser = _build_parser()
- args = parser.parse_args(["serve", "--port", "4000"])
- _cmd_serve(args)
- assert captured["registered_models"] == ["example/model"]
- assert captured["inbound_default"] == "both"
-
- def test_cli_path_overrides_saved(self, monkeypatch, tmp_path):
- from switchyard.cli.config.user_config import UserConfig, save_user_config
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_serve
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- cli_yaml = tmp_path / "cli.yaml"
- cli_yaml.write_text(_MINIMAL_YAML_BUNDLE)
- save_user_config(UserConfig(routing_profiles=self._BUNDLE))
-
- captured: dict = {}
-
- def fake_build_and_serve(args, table, inbound_default, **_kwargs):
- captured["routing_profiles"] = args.routing_profiles
-
- monkeypatch.setattr(
- "switchyard.cli.switchyard_cli.build_and_serve",
- fake_build_and_serve,
- )
-
- parser = _build_parser()
- args = parser.parse_args([
- "--routing-profiles", str(cli_yaml), "serve", "--port", "4000",
- ])
- _cmd_serve(args)
- # CLI path wins as-is.
- assert captured["routing_profiles"] == str(cli_yaml)
-
- def test_errors_when_neither_cli_nor_saved(self, monkeypatch, tmp_path):
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_serve
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- parser = _build_parser()
- args = parser.parse_args(["serve", "--port", "4000"])
- with pytest.raises(SystemExit) as excinfo:
- _cmd_serve(args)
- assert "switchyard --routing-profiles PATH configure" in str(excinfo.value)
-
-
-class TestConfigurePersistsRoutingProfiles:
- """`switchyard --routing-profiles PATH configure` snapshots the bundle."""
-
- def test_cli_path_persists_parsed_bundle(self, monkeypatch, tmp_path):
- from switchyard.cli.config.user_config import load_user_config
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_configure
-
- cwd = tmp_path / "cwd"
- cwd.mkdir()
- yaml_content = (
- "routes:\n"
- " example/model:\n"
- " type: model\n"
- " target:\n"
- " model: example/model\n"
- " api_key: ${TEST_API_KEY}\n"
- " base_url: https://example.invalid/v1\n"
- )
- rel_yaml = cwd / "route.yaml"
- rel_yaml.write_text(yaml_content)
- monkeypatch.chdir(cwd)
-
- config_dir = tmp_path / "config"
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(config_dir))
- monkeypatch.setattr(
- "switchyard.cli.command_utils.is_interactive_terminal",
- lambda: False,
- )
- monkeypatch.setattr(
- "switchyard.cli.configure_command.is_interactive_terminal",
- lambda: False,
- )
- monkeypatch.setattr(
- "switchyard.cli.configure_command.discover_models",
- lambda base_url, api_key, disabled: ["model-a"],
- )
-
- parser = _build_parser()
- args = parser.parse_args([
- "--routing-profiles", "route.yaml",
- "configure",
- "--target", "claude",
- "--api-key", "sk-test",
- "--claude-model", "model-a",
- "--no-model-discovery",
- ])
- _cmd_configure(args)
-
- saved = load_user_config(config_dir).routing_profiles
- assert saved is not None
- # Env-var references should be preserved verbatim (re-expanded at load).
- target = saved["routes"]["example/model"]["target"]
- assert target["api_key"] == "${TEST_API_KEY}"
-
- def test_first_route_becomes_model_default(self, monkeypatch, tmp_path):
- """With a routing profile and no --claude-model, the first route key is
- the saved Claude model default (matching what the launcher seeds)."""
- from switchyard.cli.config.user_config import load_user_config
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_configure
-
- cwd = tmp_path / "cwd"
- cwd.mkdir()
- # Two routes; `coding-agent` is declared first, so it wins as the default.
- yaml_content = (
- "routes:\n"
- " coding-agent:\n"
- " type: model\n"
- " target:\n"
- " model: aws/anthropic/bedrock-claude-opus-4-7\n"
- " other-route:\n"
- " type: model\n"
- " target:\n"
- " model: nvidia/nemotron-3-super\n"
- )
- (cwd / "route.yaml").write_text(yaml_content)
- monkeypatch.chdir(cwd)
-
- config_dir = tmp_path / "config"
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(config_dir))
- monkeypatch.setattr(
- "switchyard.cli.command_utils.is_interactive_terminal",
- lambda: False,
- )
- monkeypatch.setattr(
- "switchyard.cli.configure_command.is_interactive_terminal",
- lambda: False,
- )
- monkeypatch.setattr(
- "switchyard.cli.configure_command.discover_models",
- lambda base_url, api_key, *, disabled: [],
- )
-
- parser = _build_parser()
- # No --claude-model: the routing profile's first route supplies the default.
- args = parser.parse_args([
- "--routing-profiles", "route.yaml",
- "configure",
- "--target", "claude",
- "--api-key", "sk-test",
- "--no-model-discovery",
- ])
- _cmd_configure(args)
-
- saved = load_user_config(config_dir)
- # The saved claude model uses the `claude-` aliased form (the launcher
- # exposes every non-prefixed route under that alias so Claude Code's
- # gateway-discovery picker picks it up).
- assert saved.launch_target("claude").effective_route().model == "claude-coding-agent"
-
- def test_explicit_model_flag_overrides_routing_profile_default(
- self, monkeypatch, tmp_path,
- ):
- """An explicit --claude-model wins over the routing profile's first route."""
- from switchyard.cli.config.user_config import load_user_config
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_configure
-
- cwd = tmp_path / "cwd"
- cwd.mkdir()
- (cwd / "route.yaml").write_text(
- "routes:\n"
- " coding-agent:\n"
- " type: model\n"
- " target:\n"
- " model: aws/anthropic/bedrock-claude-opus-4-7\n"
- )
- monkeypatch.chdir(cwd)
-
- config_dir = tmp_path / "config"
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(config_dir))
- monkeypatch.setattr(
- "switchyard.cli.command_utils.is_interactive_terminal",
- lambda: False,
- )
- monkeypatch.setattr(
- "switchyard.cli.configure_command.is_interactive_terminal",
- lambda: False,
- )
- monkeypatch.setattr(
- "switchyard.cli.configure_command.discover_models",
- lambda base_url, api_key, *, disabled: [],
- )
-
- parser = _build_parser()
- args = parser.parse_args([
- "--routing-profiles", "route.yaml",
- "configure",
- "--target", "claude",
- "--api-key", "sk-test",
- "--claude-model", "my/explicit-model",
- "--no-model-discovery",
- ])
- _cmd_configure(args)
-
- saved = load_user_config(config_dir)
- assert saved.launch_target("claude").effective_route().model == "my/explicit-model"
-
- def test_empty_routing_profiles_clears_saved_content(
- self, monkeypatch, tmp_path,
- ):
- """Passing --routing-profiles '' wipes the saved snapshot."""
- from switchyard.cli.config.user_config import (
- UserConfig,
- load_user_config,
- save_user_config,
- )
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_configure
-
- config_dir = tmp_path / "config"
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(config_dir))
- save_user_config(
- UserConfig(routing_profiles={"routes": {"x": {"type": "model"}}}),
- config_dir=config_dir,
- )
- monkeypatch.setattr(
- "switchyard.cli.command_utils.is_interactive_terminal",
- lambda: False,
- )
- monkeypatch.setattr(
- "switchyard.cli.configure_command.is_interactive_terminal",
- lambda: False,
- )
- monkeypatch.setattr(
- "switchyard.cli.configure_command.discover_models",
- lambda base_url, api_key, disabled: ["model-a"],
- )
-
- parser = _build_parser()
- args = parser.parse_args([
- "--routing-profiles", "",
- "configure",
- "--target", "claude",
- "--api-key", "sk-test",
- "--claude-model", "model-a",
- "--no-model-discovery",
- ])
- _cmd_configure(args)
-
- assert load_user_config(config_dir).routing_profiles is None
-
- def test_missing_path_errors_clearly(self, monkeypatch, tmp_path):
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_configure
-
- config_dir = tmp_path / "config"
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(config_dir))
- monkeypatch.setattr(
- "switchyard.cli.command_utils.is_interactive_terminal",
- lambda: False,
- )
- monkeypatch.setattr(
- "switchyard.cli.configure_command.is_interactive_terminal",
- lambda: False,
- )
- monkeypatch.setattr(
- "switchyard.cli.configure_command.discover_models",
- lambda base_url, api_key, disabled: ["model-a"],
- )
-
- parser = _build_parser()
- args = parser.parse_args([
- "--routing-profiles", "/this/does/not/exist.yaml",
- "configure",
- "--target", "claude",
- "--api-key", "sk-test",
- "--claude-model", "model-a",
- "--no-model-discovery",
- ])
- with pytest.raises(SystemExit) as excinfo:
- _cmd_configure(args)
- assert "file not found" in str(excinfo.value)
diff --git a/tests/test_launch_claude_deterministic.py b/tests/test_launch_claude_deterministic.py
deleted file mode 100644
index 17d09170d..000000000
--- a/tests/test_launch_claude_deterministic.py
+++ /dev/null
@@ -1,352 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Tests for the deterministic default of ``switchyard launch claude``.
-
-``launch claude`` defaults to LLM-classifier deterministic routing when
-no ``--model`` or ``--routing-profiles`` is given. The legacy
-``--deterministic`` flag has been removed from this subparser; tier
-overrides (``--weak-model``, ``--classifier-model``, ``--profile``,
-``--classifier-min-confidence``) still tune the default trio.
-"""
-
-import pytest
-
-
-class TestArgparse:
- def test_deterministic_flag_removed(self) -> None:
- from switchyard.cli.switchyard_cli import _build_parser
-
- parser = _build_parser()
- with pytest.raises(SystemExit):
- parser.parse_args(["launch", "claude", "--deterministic"])
-
- def test_default_no_flags_parses(self) -> None:
- from switchyard.cli.switchyard_cli import _build_parser
-
- parser = _build_parser()
- # No --deterministic, no --model: the launcher will dispatch to
- # deterministic routing as the implicit default.
- args = parser.parse_args(["launch", "claude"])
- assert args.model is None
- assert args.routing_profiles is None
- # Override knobs default to None — preset values fill them in.
- assert args.weak_model is None
- assert args.classifier_model is None
- assert args.profile is None
- assert args.classifier_min_confidence is None
-
- def test_overrides_parse(self) -> None:
- from switchyard.cli.switchyard_cli import _build_parser
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "claude",
- "--classifier-model", "nvidia/nvidia/nemotron-3-super-v3",
- "--profile", "general",
- "--classifier-min-confidence", "0.55",
- ])
- assert args.classifier_model == "nvidia/nvidia/nemotron-3-super-v3"
- assert args.profile == "general"
- assert args.classifier_min_confidence == 0.55
-
- def test_profile_choices_enforced(self) -> None:
- from switchyard.cli.switchyard_cli import _build_parser
-
- parser = _build_parser()
- with pytest.raises(SystemExit):
- parser.parse_args([
- "launch", "claude",
- "--profile", "invented",
- ])
-
-
-class TestDispatch:
- def test_default_dispatches_to_deterministic_launcher(
- self, monkeypatch, tmp_path,
- ) -> None:
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_claude
-
- parser = _build_parser()
- # Zero flags beyond credentials — deterministic should fire.
- args = parser.parse_args([
- "launch", "claude", "--api-key", "sk-test",
- ])
-
- captured: dict = {}
-
- def fake_launch(**kwargs):
- captured.update(kwargs)
- raise SystemExit(0)
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher."
- "launch_claude_deterministic_routing",
- fake_launch,
- )
-
- with pytest.raises(SystemExit):
- _cmd_launch_claude(args)
-
- config = captured["config"]
- assert config.strong.model == "anthropic/claude-opus-4.7"
- assert config.weak.model == "moonshotai/kimi-k2.6"
- assert config.classifier.model == "google/gemini-3.5-flash"
- assert config.profile_name == "coding_agent"
- assert config.preset == "coding_agent_default"
-
- def test_launch_uses_auto_format_for_strong_tier(
- self, monkeypatch, tmp_path,
- ) -> None:
- """Claude can probe Anthropic support on compatible gateways while
- OpenRouter defaults fall back to OpenAI-compatible chat completions."""
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_claude
- from switchyard.lib.backends.llm_target import BackendFormat
-
- parser = _build_parser()
- args = parser.parse_args(["launch", "claude", "--api-key", "sk-test"])
-
- captured: dict = {}
-
- def fake_launch(**kwargs):
- captured.update(kwargs)
- raise SystemExit(0)
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher."
- "launch_claude_deterministic_routing",
- fake_launch,
- )
-
- with pytest.raises(SystemExit):
- _cmd_launch_claude(args)
-
- config = captured["config"]
- assert config.strong.format == BackendFormat.AUTO
- assert config.weak.format == BackendFormat.OPENAI
- assert config.classifier.format == BackendFormat.OPENAI
-
- def test_model_flag_opts_out_of_deterministic(
- self, monkeypatch, tmp_path,
- ) -> None:
- """Passing --model X falls through to single-model passthrough."""
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_claude
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "claude",
- "--api-key", "sk-test",
- "--model", "nvidia/moonshotai/kimi-k2.5",
- ])
-
- captured_passthrough: dict = {}
-
- def fake_passthrough(**kwargs):
- captured_passthrough.update(kwargs)
- raise SystemExit(0)
-
- def fake_deterministic(**_kwargs):
- raise AssertionError(
- "--model X should not dispatch to deterministic launcher",
- )
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher.launch_claude",
- fake_passthrough,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher."
- "launch_claude_deterministic_routing",
- fake_deterministic,
- )
-
- with pytest.raises(SystemExit):
- _cmd_launch_claude(args)
-
- assert captured_passthrough["model"] == "nvidia/moonshotai/kimi-k2.5"
-
- def test_dispatch_honors_user_overrides(self, monkeypatch, tmp_path) -> None:
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_claude
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "claude", "--api-key", "sk-test",
- "--weak-model", "nvidia/moonshotai/kimi-k2.5",
- "--profile", "general",
- "--classifier-min-confidence", "0.55",
- ])
-
- captured: dict = {}
-
- def fake_launch(**kwargs):
- captured.update(kwargs)
- raise SystemExit(0)
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher."
- "launch_claude_deterministic_routing",
- fake_launch,
- )
-
- with pytest.raises(SystemExit):
- _cmd_launch_claude(args)
-
- config = captured["config"]
- assert config.weak.model == "nvidia/moonshotai/kimi-k2.5"
- assert config.profile_name == "general"
- assert config.classifier_min_confidence == 0.55
- # Strong + classifier still come from the preset
- assert config.strong.model == "anthropic/claude-opus-4.7"
- assert config.classifier.model == "google/gemini-3.5-flash"
- # Preset blanked because user overrode at least one model
- assert config.preset is None
-
- def test_dry_run_does_not_invoke_launcher(self, monkeypatch, tmp_path) -> None:
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_claude
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "claude", "--api-key", "sk-test",
- "--dry-run",
- ])
-
- def fake_launch(**_kwargs):
- raise AssertionError("dry-run must not invoke the launcher")
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher."
- "launch_claude_deterministic_routing",
- fake_launch,
- )
-
- # Dry-run prints + returns without SystemExit.
- _cmd_launch_claude(args)
-
- def test_dry_run_routing_profiles_reports_bundle(
- self, monkeypatch, tmp_path, capsys,
- ) -> None:
- """A ``--routing-profiles`` dry run reports ``route: bundle``, not single."""
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_claude
-
- yaml_path = tmp_path / "routes.yaml"
- yaml_path.write_text(
- "routes:\n"
- " my-route:\n"
- " type: model\n"
- " model: openai/gpt-4o-mini\n",
- encoding="utf-8",
- )
-
- parser = _build_parser()
- args = parser.parse_args([
- "--routing-profiles", str(yaml_path),
- "launch", "claude", "--dry-run",
- ])
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
- )
-
- _cmd_launch_claude(args)
-
- out = capsys.readouterr().out
- assert "route: bundle" in out
- assert "route: single" not in out
-
- def test_zero_config_non_openrouter_rejects_default_trio(
- self, monkeypatch, tmp_path,
- ) -> None:
- """Zero-flag launch against a non-OpenRouter provider fails fast."""
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_claude
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setenv("NVIDIA_API_KEY", "nvapi-test")
- monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("nvapi-test", "https://inference-api.nvidia.com/v1"),
- )
-
- parser = _build_parser()
- args = parser.parse_args(["launch", "claude"])
-
- with pytest.raises(SystemExit) as exc_info:
- _cmd_launch_claude(args)
-
- message = str(exc_info.value)
- assert "OpenRouter-only" in message
- assert "anthropic/claude-opus-4.7" in message
- assert "moonshotai/kimi-k2.6" in message
- assert "google/gemini-3.5-flash" in message
- assert "https://inference-api.nvidia.com/v1" in message
-
-
-class TestRoutesByDefault:
- """The deterministic launch must boot claude on the *router*, not strong.
-
- Mirror of the codex guard — both launchers pin the agent to the virtual
- routing model id so the LLM classifier runs by default.
- """
-
- def test_claude_boots_on_routing_virtual_model(self, monkeypatch) -> None:
- from switchyard.cli.launchers.claude_code_launcher import (
- launch_claude_deterministic_routing,
- )
- from switchyard.lib.profiles import (
- DeterministicRoutingPresets,
- )
- from switchyard.lib.route_table_builders import (
- deterministic_routing_virtual_model_id,
- )
-
- config = DeterministicRoutingPresets.coding_agent_default(api_key="sk-test")
- captured: dict = {}
-
- def fake_run(_table, **kwargs):
- captured.update(kwargs)
- return 0
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._run_claude_with_switchyard",
- fake_run,
- )
-
- rc = launch_claude_deterministic_routing(
- config=config,
- port=None,
- claude_args=[],
- discovery_disabled=True,
- )
-
- assert rc == 0
- assert captured["display_model"] == deterministic_routing_virtual_model_id(
- config,
- )
- assert captured["display_model"] != config.strong.model
diff --git a/tests/test_launch_codex.py b/tests/test_launch_codex.py
deleted file mode 100644
index 5fc23a6bc..000000000
--- a/tests/test_launch_codex.py
+++ /dev/null
@@ -1,824 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Tests for ``switchyard.cli.launchers.codex_cli_launcher``.
-
-Exercises the public ``launch_codex`` entry, the private model-rewrite
-request processor, the codex provider override builder, and the
-``codex`` binary lookup. Real uvicorn and ``subprocess.run`` are mocked
-— these tests don't start a server or spawn a child process.
-
-Mirrors :mod:`tests.test_launch_claude_v2`; shared launcher helpers cover
-the proxy process and live stats footer, while harness-specific tests stay
-split by child process.
-"""
-
-import subprocess
-from pathlib import Path
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-from switchyard.cli.launchers.codex_cli_launcher import (
- _EXIT_BINARY_NOT_FOUND,
- _EXIT_SIGINT,
- _PROVIDER_ID,
- _find_codex_binary,
- _find_free_port,
- _ModelRewriteRequestProcessor,
- _provider_overrides,
- launch_codex,
-)
-from switchyard.cli.launchers.codex_model_catalog import (
- _build_codex_model_catalog,
- _fallback_codex_model_template,
-)
-from switchyard.cli.launchers.launch_intake_config import LaunchIntakeConfig
-from switchyard.lib.proxy_context import ProxyContext
-from switchyard.lib.route_table import RouteTable
-from switchyard_rust.core import ChatRequest
-
-# ---------------------------------------------------------------------------
-# _ModelRewriteRequestProcessor
-# ---------------------------------------------------------------------------
-
-
-class TestModelRewriteRequestProcessor:
- """Processor must rewrite ``body['model']`` for every ChatRequest subclass.
-
- Codex itself only ever sends Responses-shaped requests, but the
- processor is type-agnostic, so we exercise all three subclasses for
- parity with the launch_claude tests.
- """
-
- async def test_rewrites_responses_request(self):
- proc = _ModelRewriteRequestProcessor("nvidia/moonshotai/kimi-k2.5")
- req = ChatRequest.openai_responses({
- "model": "gpt-5.3-codex",
- "input": "hi",
- })
- out = await proc.process(ProxyContext(), req)
- assert out is req
- assert req.body["model"] == "nvidia/moonshotai/kimi-k2.5"
-
- async def test_rewrites_openai_chat_request(self):
- proc = _ModelRewriteRequestProcessor("target-model")
- req = ChatRequest.openai_chat({"model": "gpt-4o", "messages": []})
- await proc.process(ProxyContext(), req)
- assert req.body["model"] == "target-model"
-
- async def test_rewrites_anthropic_request(self):
- proc = _ModelRewriteRequestProcessor("target-model")
- req = ChatRequest.anthropic({
- "model": "claude-sonnet-4-5",
- "messages": [{"role": "user", "content": "hi"}],
- "max_tokens": 100,
- })
- await proc.process(ProxyContext(), req)
- assert req.body["model"] == "target-model"
-
-
-# ---------------------------------------------------------------------------
-# _find_codex_binary
-# ---------------------------------------------------------------------------
-
-
-class TestFindCodexBinary:
- def test_returns_path_hit_when_on_path(self):
- with patch("shutil.which", return_value="/usr/local/bin/codex"):
- assert _find_codex_binary() == "/usr/local/bin/codex"
-
- def test_falls_back_to_npm_global(self, tmp_path, monkeypatch):
- monkeypatch.setattr("shutil.which", lambda _: None)
- monkeypatch.setattr(Path, "home", lambda: tmp_path)
- codex = tmp_path / ".npm-global" / "bin" / "codex"
- codex.parent.mkdir(parents=True)
- codex.write_text("#!/bin/sh\necho codex\n")
- codex.chmod(0o755)
- assert _find_codex_binary() == str(codex)
-
- def test_falls_back_to_local_bin(self, tmp_path, monkeypatch):
- monkeypatch.setattr("shutil.which", lambda _: None)
- monkeypatch.setattr(Path, "home", lambda: tmp_path)
- codex = tmp_path / ".local" / "bin" / "codex"
- codex.parent.mkdir(parents=True)
- codex.write_text("#!/bin/sh\necho codex\n")
- codex.chmod(0o755)
- assert _find_codex_binary() == str(codex)
-
- def test_returns_none_when_nowhere(self, tmp_path, monkeypatch):
- monkeypatch.setattr("shutil.which", lambda _: None)
- monkeypatch.setattr(Path, "home", lambda: tmp_path)
- assert _find_codex_binary() is None
-
-
-# ---------------------------------------------------------------------------
-# _find_free_port
-# ---------------------------------------------------------------------------
-
-
-class TestFindFreePort:
- def test_returns_usable_port(self):
- port = _find_free_port()
- assert 1024 <= port <= 65535
-
-
-# ---------------------------------------------------------------------------
-# _provider_overrides
-# ---------------------------------------------------------------------------
-
-
-class TestProviderOverrides:
- """The codex ``-c`` argv pairs are the contract with codex's TOML
- parser — typos here silently route the user to the built-in OpenAI
- provider instead of our proxy. These assertions pin the wire shape.
- """
-
- def test_emits_six_overrides(self):
- out = _provider_overrides(54321)
- # Six ``-c key=value`` pairs = 12 argv entries (alternating).
- assert len(out) == 12
- # Every even index is the literal ``-c`` flag.
- assert all(out[i] == "-c" for i in range(0, len(out), 2))
-
- def test_activates_switchyard_provider(self):
- out = _provider_overrides(54321)
- assert f'model_provider="{_PROVIDER_ID}"' in out
-
- def test_base_url_includes_port_and_v1(self):
- out = _provider_overrides(54321)
- expected = f'model_providers.{_PROVIDER_ID}.base_url="http://127.0.0.1:54321/v1"'
- assert expected in out
-
- def test_wire_api_is_responses(self):
- # Codex speaks /v1/responses; ResponsesEndpoint
- # is what the inbound side mounts. ``chat`` would route codex
- # to /v1/chat/completions which the proxy also serves but
- # bypasses codex's Responses-specific request shape.
- out = _provider_overrides(54321)
- assert f'model_providers.{_PROVIDER_ID}.wire_api="responses"' in out
-
- def test_env_key_is_openai_api_key(self):
- # Has to match the env var that ``_supervise_codex`` sets.
- out = _provider_overrides(54321)
- assert f'model_providers.{_PROVIDER_ID}.env_key="OPENAI_API_KEY"' in out
-
- def test_disables_openai_oauth(self):
- # Without this, codex still attempts ChatGPT OAuth refresh
- # against the built-in openai provider's token store. The
- # 401 chatter is harmless but spammy; opting out is cleaner.
- out = _provider_overrides(54321)
- assert (
- f"model_providers.{_PROVIDER_ID}.requires_openai_auth=false" in out
- )
-
- def test_model_catalog_override_is_appended(self):
- out = _provider_overrides(54321, model_catalog_json="/tmp/switchyard models.json")
- assert len(out) == 14
- assert 'model_catalog_json="/tmp/switchyard models.json"' in out
-
- def test_intake_appends_http_headers(self):
- intake = LaunchIntakeConfig.from_resolved(
- base_url=None,
- workspace=None,
- api_key=None,
- app="codex",
- task="developer-session",
- session_id="sess-xyz",
- target="codex",
- )
- out = _provider_overrides(54321, intake=intake)
- http_overrides = [arg for arg in out if "http_headers" in arg]
-
- assert len(http_overrides) == 1
- value = http_overrides[0].split("=", 1)[1]
- assert '"x-switchyard-intake-enabled"="true"' in value
- assert '"x-switchyard-intake-app"="codex"' in value
- assert '"proxy_x_session_id"="sess-xyz"' in value
-
-
-class TestCodexModelCatalog:
- def test_builds_switchyard_only_catalog_from_template(self, monkeypatch):
- template = {
- "slug": "gpt-5.5",
- "display_name": "GPT-5.5",
- "description": "template",
- "default_reasoning_level": "xhigh",
- "supported_reasoning_levels": [
- {"effort": "xhigh", "description": "Extra high reasoning"},
- ],
- "shell_type": "shell_command",
- "visibility": "list",
- "supported_in_api": True,
- "priority": 99,
- "availability_nux": {"message": "template nux"},
- "upgrade": {"message": "template upgrade"},
- "base_instructions": "template instructions",
- }
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_model_catalog._load_codex_model_template",
- lambda codex_bin: template,
- )
-
- catalog = _build_codex_model_catalog(
- "/fake/bin/codex",
- [
- (
- "switchyard-default-random-12345678",
- "Switchyard random routing",
- "Random route.",
- ),
- ("strong/model", "Strong model", "Direct strong route."),
- ],
- )
-
- models = catalog["models"]
- assert [model["slug"] for model in models] == [
- "switchyard-default-random-12345678",
- "strong/model",
- ]
- assert models[0]["display_name"] == "Switchyard random routing"
- assert models[0]["description"] == "Random route."
- assert models[0]["priority"] == 0
- assert models[0]["availability_nux"] is None
- assert models[0]["upgrade"] is None
- assert models[0]["base_instructions"] == "template instructions"
- assert models[1]["priority"] == 1
-
-# ---------------------------------------------------------------------------
-# launch_codex — integration (with mocked externals)
-# ---------------------------------------------------------------------------
-
-
-def _make_fake_server(started: bool = True) -> MagicMock:
- """uvicorn.Server stand-in that reports started immediately."""
- server = MagicMock()
- server.started = started
- server.should_exit = False
- return server
-
-
-def _stub_spawn_proxy(server: MagicMock):
- """Return a function that mimics _spawn_proxy_thread's (server, thread) tuple."""
- def _inner(switchyard, port):
- thread = MagicMock()
- return server, thread
- return _inner
-
-
[email protected](autouse=True)
-def _mock_ready_and_tty(monkeypatch, tmp_path):
- """Launcher tests use fake servers, so bypass external runtime side effects."""
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._wait_ready",
- lambda port, timeout_s=10.0: True,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher.stdin_is_tty",
- lambda: False,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher.configure_debug_file_logging",
- lambda display_model: tmp_path / "switchyard.log",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_model_catalog._load_codex_model_template",
- lambda codex_bin: _fallback_codex_model_template(),
- )
- # Prevent real network calls; simulate OpenAI upstream: Chat Completions probe fails so
- # Responses wins (OpenAI gpt models expose /v1/responses but not /v1/chat/completions
- # as the primary surface in these tests).
- monkeypatch.setattr(
- "switchyard.lib.backends.backend_format_resolver.probe_openai_chat_completions_support_sync",
- lambda **_: False,
- )
- monkeypatch.setattr(
- "switchyard.lib.backends.backend_format_resolver.probe_anthropic_messages_support_sync",
- lambda **_: False,
- )
- monkeypatch.setattr(
- "switchyard.lib.backends.backend_format_resolver.probe_openai_responses_support_sync",
- lambda **_: True,
- )
-
-
-class TestLaunchCodex:
- def test_happy_path(self, monkeypatch):
- fake_server = _make_fake_server(started=True)
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._find_codex_binary",
- lambda: "/fake/bin/codex",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._spawn_proxy_thread",
- _stub_spawn_proxy(fake_server),
- )
-
- captured: dict = {}
-
- def fake_run(cmd, env, check):
- captured["cmd"] = cmd
- captured["env"] = env
- return subprocess.CompletedProcess(cmd, returncode=0)
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- exit_code = launch_codex(
- model="nvidia/moonshotai/kimi-k2.5",
- base_url="https://inference-api.nvidia.com/v1",
- api_key="test-key",
- port=None,
- timeout=None,
- codex_args=["exec", "say hi"],
- )
-
- assert exit_code == 0
- cmd = captured["cmd"]
- # argv layout: [codex_bin, *provider -c overrides, -m, model, *codex_args]
- assert cmd[0] == "/fake/bin/codex"
- assert cmd[-4:] == ["-m", "nvidia/moonshotai/kimi-k2.5", "exec", "say hi"]
- # The first provider overrides occupy indices 1..13 (12 entries).
- assert cmd[1] == "-c"
- assert any(
- v == 'model_provider="switchyard"' for v in cmd[1:13]
- )
- assert any(
- 'base_url="http://127.0.0.1:54321/v1"' in v for v in cmd[1:13]
- )
- assert any(v.startswith("model_catalog_json=") for v in cmd)
- # OPENAI_API_KEY must be set (codex's provider config refuses to
- # start without it). Real upstream key is injected by the proxy
- # at call time — this is just a placeholder.
- assert captured["env"]["OPENAI_API_KEY"] == "switchyard"
- # Proxy torn down on return
- assert fake_server.should_exit is True
-
- def test_port_override(self, monkeypatch):
- fake_server = _make_fake_server(started=True)
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._find_codex_binary",
- lambda: "/fake/bin/codex",
- )
-
- # If --port is set, _find_free_port should NOT be called
- def _should_not_be_called():
- raise AssertionError("_find_free_port called despite --port override")
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._find_free_port",
- _should_not_be_called,
- )
-
- captured: dict = {}
-
- def stub_spawn(switchyard, port):
- captured["port"] = port
- thread = MagicMock()
- return fake_server, thread
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._spawn_proxy_thread",
- stub_spawn,
- )
-
- def fake_run(cmd, env, check):
- captured["cmd"] = cmd
- return subprocess.CompletedProcess(cmd, returncode=0)
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- exit_code = launch_codex(
- model="m", base_url="u", api_key="k",
- port=4000, timeout=None, codex_args=[],
- )
-
- assert exit_code == 0
- assert captured["port"] == 4000
- # Provider override base_url must reflect the chosen port.
- assert any(
- 'base_url="http://127.0.0.1:4000/v1"' in v for v in captured["cmd"]
- )
-
- def test_missing_binary_returns_127(self, monkeypatch):
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._find_codex_binary",
- lambda: None,
- )
-
- # If we reach _spawn_proxy_thread, we failed to short-circuit
- def _should_not_spawn(*args, **kwargs):
- raise AssertionError("proxy spawned despite missing binary")
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._spawn_proxy_thread",
- _should_not_spawn,
- )
-
- exit_code = launch_codex(
- model="m", base_url="u", api_key="k",
- port=None, timeout=None, codex_args=[],
- )
- assert exit_code == _EXIT_BINARY_NOT_FOUND
-
- def test_ctrl_c_returns_130_and_tears_down(self, monkeypatch):
- fake_server = _make_fake_server(started=True)
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._find_codex_binary",
- lambda: "/fake/bin/codex",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._spawn_proxy_thread",
- _stub_spawn_proxy(fake_server),
- )
-
- def raise_sigint(cmd, env, check):
- raise KeyboardInterrupt()
- monkeypatch.setattr(subprocess, "run", raise_sigint)
-
- exit_code = launch_codex(
- model="m", base_url="u", api_key="k",
- port=None, timeout=None, codex_args=[],
- )
-
- assert exit_code == _EXIT_SIGINT
- assert fake_server.should_exit is True
-
- def test_strips_leading_double_dash_from_codex_args(self, monkeypatch, tmp_path):
- """``argparse.REMAINDER`` keeps the ``--`` sentinel in the captured
- list, so ``launch codex ... -- exec hi`` produces
- ``['--', 'exec', 'hi']``. The handler must strip the leading ``--``
- before forwarding so codex doesn't receive a bare ``--`` arg.
- """
- from switchyard.cli.switchyard_cli import (
- _build_parser,
- _cmd_launch_codex,
- )
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "codex",
- "--model", "nvidia/moonshotai/kimi-k2.5",
- "--api-key", "sk-test",
- "--", "exec", "hi",
- ])
- assert args.codex_args == ["--", "exec", "hi"] # argparse kept '--'
-
- captured: dict = {}
-
- def fake_launch(**kwargs):
- captured.update(kwargs)
- raise SystemExit(0)
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://inference-api.nvidia.com/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher.launch_codex",
- fake_launch,
- )
-
- with pytest.raises(SystemExit):
- _cmd_launch_codex(args)
-
- # Handler stripped the '--' before forwarding.
- assert captured["codex_args"] == ["exec", "hi"]
-
- def test_no_flags_dispatches_to_deterministic(self, monkeypatch, tmp_path):
- """No ``--model``, no ``--routing-profiles`` → deterministic default.
-
- Previously ``launch codex`` errored asking for ``--model``; the
- zero-flag default now resolves to the LLM-classifier
- deterministic chain.
- """
- from switchyard.cli.switchyard_cli import (
- _build_parser,
- _cmd_launch_codex,
- )
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- # OpenRouter endpoint: the zero-flag default trio is OpenRouter-only, so
- # the deterministic default only dispatches when the resolved endpoint is
- # OpenRouter (a non-OpenRouter provider is rejected).
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
- )
-
- captured: dict = {}
-
- def fake_launch(**kwargs):
- captured.update(kwargs)
- raise SystemExit(0)
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher."
- "launch_codex_deterministic_routing",
- fake_launch,
- )
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "codex", "--api-key", "sk-test",
- ])
- with pytest.raises(SystemExit):
- _cmd_launch_codex(args)
- assert captured["config"].preset == "coding_agent_default"
-
- def test_proxy_never_ready_returns_error(self, monkeypatch):
- fake_server = _make_fake_server(started=False) # never flips to True
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._find_codex_binary",
- lambda: "/fake/bin/codex",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._spawn_proxy_thread",
- _stub_spawn_proxy(fake_server),
- )
- # Override the autouse readiness mock to simulate a timeout.
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._wait_ready",
- lambda port, timeout_s=10.0: False,
- )
-
- def _should_not_run(*args, **kwargs):
- raise AssertionError("codex spawned despite proxy not ready")
- monkeypatch.setattr(subprocess, "run", _should_not_run)
-
- exit_code = launch_codex(
- model="m", base_url="u", api_key="k",
- port=None, timeout=None, codex_args=[],
- )
- assert exit_code == 1
- assert fake_server.should_exit is True
-
- def test_uses_openai_translation_chain(self, monkeypatch):
- """Codex always speaks Responses API → backend always
- an OpenAI-native backend behind the stats wrapper.
- """
- from switchyard.lib.backends.stats_llm_backend import StatsLlmBackend
- from switchyard.lib.processors.stats_response_processor_accumulator import (
- StatsResponseProcessor,
- )
-
- model = "nvidia/moonshotai/kimi-k2.5"
- captured_switchyard: dict = {}
-
- def stub_spawn(app, port):
- assert isinstance(app, RouteTable)
- chain = app.lookup_switchyard(model)
- captured_switchyard["app"] = app
- captured_switchyard["switchyard"] = chain
- captured_switchyard["backend"] = next(
- component
- for component in chain.iter_components()
- if isinstance(component, StatsLlmBackend)
- )
- return _make_fake_server(started=True), MagicMock()
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._find_codex_binary",
- lambda: "/fake/bin/codex",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._spawn_proxy_thread",
- stub_spawn,
- )
- monkeypatch.setattr(
- subprocess, "run",
- lambda cmd, env, check: subprocess.CompletedProcess(cmd, returncode=0),
- )
-
- launch_codex(
- model=model,
- base_url="https://inference-api.nvidia.com/v1",
- api_key="sk-test",
- port=None, timeout=None, codex_args=[],
- )
- table = captured_switchyard["app"]
- assert table.registered_models() == [model]
- assert table.default_model() == model
- assert isinstance(captured_switchyard["backend"], StatsLlmBackend)
- assert [
- item.value
- for item in captured_switchyard["backend"].supported_request_types
- ] == ["openai_responses"]
- assert not any(
- isinstance(component, _ModelRewriteRequestProcessor)
- for component in captured_switchyard["switchyard"].iter_components()
- )
- assert any(
- isinstance(component, StatsResponseProcessor)
- for component in captured_switchyard["switchyard"].iter_components()
- )
-
- def test_tty_mode_wraps_codex_with_stats_footer(self, monkeypatch):
- """Interactive Codex launches should get the same Switchyard footer."""
- captured: dict = {}
-
- class FakeShellTUI:
- def __init__(self, command, footer_fn, footer_height, env):
- captured["command"] = command
- captured["footer_fn"] = footer_fn
- captured["footer_height"] = footer_height
- captured["env"] = env
-
- def run(self):
- return 0
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._find_codex_binary",
- lambda: "/fake/bin/codex",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._spawn_proxy_thread",
- _stub_spawn_proxy(_make_fake_server(started=True)),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher.stdin_is_tty",
- lambda: True,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher.ShellTUI",
- FakeShellTUI,
- )
-
- exit_code = launch_codex(
- model="nvidia/moonshotai/kimi-k2.5",
- base_url="https://inference-api.nvidia.com/v1",
- api_key="sk-test",
- port=None,
- timeout=None,
- codex_args=["exec", "hi"],
- )
-
- assert exit_code == 0
- assert captured["command"][0] == "/fake/bin/codex"
- assert captured["command"][-4:] == [
- "-m",
- "nvidia/moonshotai/kimi-k2.5",
- "exec",
- "hi",
- ]
- assert any(v.startswith("model_catalog_json=") for v in captured["command"])
- assert callable(captured["footer_height"]) and captured["footer_height"]() == 2
- rows = captured["footer_fn"](120)
- assert len(rows) == 2
- assert "switchyard" in rows[0][0]
- assert captured["env"]["OPENAI_API_KEY"] == "switchyard"
-
- def test_smoke_with_routing_profiles_errors_clearly(
- self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path,
- ) -> None:
- """``--smoke --routing-profiles FILE`` is rejected at the CLI level with a
- clear error directing the user to pass ``--model`` instead.
- """
- from switchyard.cli.switchyard_cli import (
- _build_parser,
- _cmd_launch_codex,
- )
-
- yaml_path = tmp_path / "bundle.yaml"
- yaml_path.write_text(
- "routes:\n"
- " fast-nemotron:\n"
- " type: model\n"
- " target: nvidia/nvidia/nemotron-nano-9b-v2\n"
- )
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://inference-api.nvidia.com/v1"),
- )
-
- parser = _build_parser()
- args = parser.parse_args([
- "--routing-profiles", str(yaml_path),
- "launch", "codex",
- "--smoke", "--api-key", "sk-test",
- ])
- with pytest.raises(SystemExit) as exc_info:
- _cmd_launch_codex(args)
- assert "--smoke and --routing-profiles cannot be combined" in str(exc_info.value)
-
- def test_smoke_without_model_errors_with_helpful_message(
- self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path,
- ) -> None:
- """``--smoke`` without ``--model`` gives a clear error directing the
- user to pass ``--model``, not ``--routing-profiles``.
- """
- from switchyard.cli.switchyard_cli import (
- _build_parser,
- _cmd_launch_codex,
- )
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://inference-api.nvidia.com/v1"),
- )
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "codex", "--smoke", "--api-key", "sk-test",
- ])
- with pytest.raises(SystemExit) as exc_info:
- _cmd_launch_codex(args)
- assert "--smoke requires --model" in str(exc_info.value)
-
- def test_routing_profiles_merges_extras_on_top_of_launcher_table(
- self, monkeypatch, tmp_path,
- ):
- """`--routing-profiles` adds YAML routes on top of the launcher's chain.
-
- The launcher registers its ``--model`` chain under ``model``; every
- YAML entry is merged on top via
- :meth:`RouteTable.register`. YAML wins on id conflict.
- """
- captured_switchyard: dict = {}
-
- def stub_spawn(switchyard, port):
- captured_switchyard["app"] = switchyard
- return _make_fake_server(started=True), MagicMock()
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._find_codex_binary",
- lambda: "/fake/bin/codex",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._spawn_proxy_thread",
- stub_spawn,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._write_codex_model_catalog",
- lambda _codex_bin, _entries: "/tmp/switchyard-codex-models.json",
- )
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda cmd, env, check: subprocess.CompletedProcess(cmd, returncode=0),
- )
-
- yaml_path = tmp_path / "extras.yaml"
- yaml_path.write_text(
- "routes:\n"
- " extras/yaml-only:\n"
- " type: model\n"
- " target:\n"
- " model: extras/yaml-only\n"
- " api_key: sk-yaml\n"
- " base_url: https://yaml.example/v1\n"
- " primary/model:\n"
- " type: model\n"
- " target:\n"
- " model: primary/model\n"
- " api_key: sk-yaml-override\n"
- " base_url: https://yaml-override.example/v1\n"
- )
-
- launch_codex(
- model="primary/model",
- base_url="https://example.invalid/v1",
- api_key="sk-test",
- port=None,
- timeout=None,
- codex_args=[],
- routing_profiles=str(yaml_path),
- )
-
- table = captured_switchyard["app"]
- assert isinstance(table, RouteTable)
- assert table.registered_models() == [
- "primary/model",
- "extras/yaml-only",
- ]
- assert table.default_model() == "primary/model"
- table.lookup_switchyard("extras/yaml-only")
- table.lookup_switchyard("primary/model")
diff --git a/tests/test_launch_codex_deterministic.py b/tests/test_launch_codex_deterministic.py
deleted file mode 100644
index b2d029d7e..000000000
--- a/tests/test_launch_codex_deterministic.py
+++ /dev/null
@@ -1,239 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Tests for the deterministic default of ``switchyard launch codex``.
-
-``launch codex`` defaults to LLM-classifier deterministic routing when
-no ``--model`` or ``--routing-profiles`` is given. The legacy
-``--deterministic`` flag has been removed from this subparser; tier
-overrides (``--weak-model``, ``--classifier-model``, ``--profile``,
-``--classifier-min-confidence``) still tune the default trio.
-"""
-
-from __future__ import annotations
-
-import pytest
-
-
-class TestArgparse:
- def test_deterministic_flag_removed(self) -> None:
- from switchyard.cli.switchyard_cli import _build_parser
-
- parser = _build_parser()
- with pytest.raises(SystemExit):
- parser.parse_args(["launch", "codex", "--deterministic"])
-
- def test_default_no_flags_parses(self) -> None:
- from switchyard.cli.switchyard_cli import _build_parser
-
- parser = _build_parser()
- args = parser.parse_args(["launch", "codex"])
- assert args.model is None
- assert args.routing_profiles is None
- assert args.weak_model is None
- assert args.classifier_model is None
- assert args.profile is None
- assert args.classifier_min_confidence is None
-
- def test_overrides_parse(self) -> None:
- from switchyard.cli.switchyard_cli import _build_parser
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "codex",
- "--classifier-model", "nvidia/nvidia/nemotron-3-super-v3",
- "--profile", "general",
- "--classifier-min-confidence", "0.55",
- ])
- assert args.classifier_model == "nvidia/nvidia/nemotron-3-super-v3"
- assert args.profile == "general"
- assert args.classifier_min_confidence == 0.55
-
-
-class TestDispatch:
- def test_default_dispatches_to_deterministic_launcher(
- self, monkeypatch, tmp_path,
- ) -> None:
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_codex
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "codex", "--api-key", "sk-test",
- ])
-
- captured: dict = {}
-
- def fake_launch(**kwargs):
- captured.update(kwargs)
- raise SystemExit(0)
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher."
- "launch_codex_deterministic_routing",
- fake_launch,
- )
-
- with pytest.raises(SystemExit):
- _cmd_launch_codex(args)
-
- config = captured["config"]
- assert config.strong.model == "anthropic/claude-opus-4.7"
- assert config.weak.model == "moonshotai/kimi-k2.6"
- assert config.classifier.model == "google/gemini-3.5-flash"
- assert config.profile_name == "coding_agent"
- assert config.preset == "coding_agent_default"
-
- def test_model_flag_opts_out_of_deterministic(
- self, monkeypatch, tmp_path,
- ) -> None:
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_codex
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "codex",
- "--api-key", "sk-test",
- "--model", "nvidia/moonshotai/kimi-k2.5",
- ])
-
- captured_passthrough: dict = {}
-
- def fake_passthrough(**kwargs):
- captured_passthrough.update(kwargs)
- raise SystemExit(0)
-
- def fake_deterministic(**_kwargs):
- raise AssertionError(
- "--model X should not dispatch to deterministic launcher",
- )
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher.launch_codex",
- fake_passthrough,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher."
- "launch_codex_deterministic_routing",
- fake_deterministic,
- )
-
- with pytest.raises(SystemExit):
- _cmd_launch_codex(args)
-
- assert captured_passthrough["model"] == "nvidia/moonshotai/kimi-k2.5"
-
- def test_dispatch_honors_weak_model_override(
- self, monkeypatch, tmp_path,
- ) -> None:
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_codex
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "codex", "--api-key", "sk-test",
- "--weak-model", "nvidia/moonshotai/kimi-k2.5",
- ])
-
- captured: dict = {}
-
- def fake_launch(**kwargs):
- captured.update(kwargs)
- raise SystemExit(0)
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher."
- "launch_codex_deterministic_routing",
- fake_launch,
- )
-
- with pytest.raises(SystemExit):
- _cmd_launch_codex(args)
-
- config = captured["config"]
- assert config.weak.model == "nvidia/moonshotai/kimi-k2.5"
- assert config.preset is None
-
- def test_dry_run_does_not_invoke_launcher(self, monkeypatch, tmp_path) -> None:
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_codex
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "codex", "--api-key", "sk-test",
- "--dry-run",
- ])
-
- def fake_launch(**_kwargs):
- raise AssertionError("dry-run must not invoke the launcher")
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher."
- "launch_codex_deterministic_routing",
- fake_launch,
- )
-
- _cmd_launch_codex(args)
-
-
-class TestRoutesByDefault:
- """The deterministic launch must boot codex on the *router*, not strong.
-
- Regression guard for the bug where ``launch_codex_deterministic_routing``
- pinned codex's ``-m`` to ``config.strong.model`` — a direct passthrough that
- silently bypassed the LLM classifier and sent every request straight to the
- strong model. It must use the virtual routing model id, matching claude.
- """
-
- def test_codex_boots_on_routing_virtual_model(self, monkeypatch) -> None:
- from switchyard.cli.launchers.codex_cli_launcher import (
- launch_codex_deterministic_routing,
- )
- from switchyard.lib.profiles import (
- DeterministicRoutingPresets,
- )
- from switchyard.lib.route_table_builders import (
- deterministic_routing_virtual_model_id,
- )
-
- config = DeterministicRoutingPresets.coding_agent_default(api_key="sk-test")
- captured: dict = {}
-
- def fake_run(_table, **kwargs):
- captured.update(kwargs)
- return 0
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._run_codex_with_switchyard",
- fake_run,
- )
-
- rc = launch_codex_deterministic_routing(
- config=config,
- port=None,
- codex_args=[],
- discovery_disabled=True, # no GET /models network call
- )
-
- assert rc == 0
- # codex is launched against the router, so the classifier runs by default.
- assert captured["display_model"] == deterministic_routing_virtual_model_id(
- config,
- )
- assert captured["display_model"] != config.strong.model
diff --git a/tests/test_launch_openclaw.py b/tests/test_launch_openclaw.py
deleted file mode 100644
index 62c11b426..000000000
--- a/tests/test_launch_openclaw.py
+++ /dev/null
@@ -1,905 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Tests for ``switchyard.cli.launchers.openclaw_launcher``.
-
-Exercises the public ``launch_openclaw`` entry, the transient JSON5
-config builder, the env-var injection contract, and the ``openclaw``
-binary lookup. Real uvicorn and ``subprocess.run`` are mocked —
-these tests don't start a server or spawn a child process.
-
-Mirrors :mod:`tests.test_launch_codex`; the per-launch transient
-workspace replaces codex's ``-c`` provider overrides.
-"""
-
-import json
-import subprocess
-from pathlib import Path
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-from switchyard.cli.launchers.launch_intake_config import LaunchIntakeConfig
-from switchyard.cli.launchers.openclaw_launcher import (
- _API_KEY_ENV,
- _API_KEY_PLACEHOLDER,
- _EXIT_BINARY_NOT_FOUND,
- _EXIT_SIGINT,
- _PROVIDER_ID,
- _build_openclaw_config,
- _find_free_port,
- _find_openclaw_binary,
- _ModelRewriteRequestProcessor,
- _openclaw_command,
- _openclaw_env,
- _qualified_model_id,
- _write_openclaw_workspace,
- launch_openclaw,
-)
-from switchyard.lib.proxy_context import ProxyContext
-from switchyard.lib.route_table import RouteTable
-from switchyard_rust.core import ChatRequest
-
-# ---------------------------------------------------------------------------
-# _ModelRewriteRequestProcessor
-# ---------------------------------------------------------------------------
-
-
-class TestModelRewriteRequestProcessor:
- """OpenClaw clients only send Chat-Completions requests, but the
- processor is type-agnostic — exercise all three inbound shapes for
- parity with the claude/codex tests.
- """
-
- async def test_rewrites_openai_chat_request(self):
- proc = _ModelRewriteRequestProcessor("nvidia/moonshotai/kimi-k2.5")
- req = ChatRequest.openai_chat({"model": "gpt-4o", "messages": []})
- out = await proc.process(ProxyContext(), req)
- assert out is req
- assert req.body["model"] == "nvidia/moonshotai/kimi-k2.5"
-
- async def test_rewrites_responses_request(self):
- proc = _ModelRewriteRequestProcessor("target-model")
- req = ChatRequest.openai_responses({"model": "gpt-5.2", "input": "hi"})
- await proc.process(ProxyContext(), req)
- assert req.body["model"] == "target-model"
-
- async def test_rewrites_anthropic_request(self):
- proc = _ModelRewriteRequestProcessor("target-model")
- req = ChatRequest.anthropic({
- "model": "claude-sonnet-4-5",
- "messages": [{"role": "user", "content": "hi"}],
- "max_tokens": 100,
- })
- await proc.process(ProxyContext(), req)
- assert req.body["model"] == "target-model"
-
-
-# ---------------------------------------------------------------------------
-# _find_openclaw_binary
-# ---------------------------------------------------------------------------
-
-
-class TestFindOpenclawBinary:
- def test_returns_path_hit_when_on_path(self):
- with patch("shutil.which", return_value="/usr/local/bin/openclaw"):
- assert _find_openclaw_binary() == "/usr/local/bin/openclaw"
-
- def test_falls_back_to_npm_global(self, tmp_path, monkeypatch):
- monkeypatch.setattr("shutil.which", lambda _: None)
- monkeypatch.setattr(Path, "home", lambda: tmp_path)
- openclaw = tmp_path / ".npm-global" / "bin" / "openclaw"
- openclaw.parent.mkdir(parents=True)
- openclaw.write_text("#!/bin/sh\necho openclaw\n")
- openclaw.chmod(0o755)
- assert _find_openclaw_binary() == str(openclaw)
-
- def test_falls_back_to_local_bin(self, tmp_path, monkeypatch):
- monkeypatch.setattr("shutil.which", lambda _: None)
- monkeypatch.setattr(Path, "home", lambda: tmp_path)
- openclaw = tmp_path / ".local" / "bin" / "openclaw"
- openclaw.parent.mkdir(parents=True)
- openclaw.write_text("#!/bin/sh\necho openclaw\n")
- openclaw.chmod(0o755)
- assert _find_openclaw_binary() == str(openclaw)
-
- def test_falls_back_to_nvm(self, tmp_path, monkeypatch):
- monkeypatch.setattr("shutil.which", lambda _: None)
- monkeypatch.setattr(Path, "home", lambda: tmp_path)
- openclaw = tmp_path / ".nvm" / "versions" / "node" / "v22.0.0" / "bin" / "openclaw"
- openclaw.parent.mkdir(parents=True)
- openclaw.write_text("#!/bin/sh\necho openclaw\n")
- openclaw.chmod(0o755)
- assert _find_openclaw_binary() == str(openclaw)
-
- def test_nvm_picks_highest_version(self, tmp_path, monkeypatch):
- """When multiple Node versions exist under nvm, we prefer the
- lexicographically-highest one (newest by default for v22.x.x)."""
- monkeypatch.setattr("shutil.which", lambda _: None)
- monkeypatch.setattr(Path, "home", lambda: tmp_path)
- for version in ("v20.0.0", "v22.5.0"):
- bin_dir = tmp_path / ".nvm" / "versions" / "node" / version / "bin"
- bin_dir.mkdir(parents=True)
- openclaw = bin_dir / "openclaw"
- openclaw.write_text("#!/bin/sh\necho openclaw\n")
- openclaw.chmod(0o755)
- assert _find_openclaw_binary().endswith("/v22.5.0/bin/openclaw")
-
- def test_returns_none_when_nowhere(self, tmp_path, monkeypatch):
- monkeypatch.setattr("shutil.which", lambda _: None)
- monkeypatch.setattr(Path, "home", lambda: tmp_path)
- assert _find_openclaw_binary() is None
-
-
-# ---------------------------------------------------------------------------
-# _find_free_port
-# ---------------------------------------------------------------------------
-
-
-class TestFindFreePort:
- def test_returns_usable_port(self):
- port = _find_free_port()
- assert 1024 <= port <= 65535
-
-
-# ---------------------------------------------------------------------------
-# _qualified_model_id
-# ---------------------------------------------------------------------------
-
-
-class TestQualifiedModelId:
- def test_prefixes_provider(self):
- assert _qualified_model_id("openai/gpt-5.2") == "switchyard/openai/gpt-5.2"
-
- def test_strips_leading_slash(self):
- assert _qualified_model_id("/openai/gpt-5.2") == "switchyard/openai/gpt-5.2"
-
- def test_bare_model_name(self):
- assert _qualified_model_id("kimi-k2.5") == "switchyard/kimi-k2.5"
-
-
-# ---------------------------------------------------------------------------
-# _build_openclaw_config
-# ---------------------------------------------------------------------------
-
-
-class TestBuildOpenclawConfig:
- """Pin the JSON5 schema — typos here silently leave openclaw unable
- to resolve the switchyard provider and the user falls back to
- openclaw's built-in defaults (or fails to start).
- """
-
- def test_declares_switchyard_provider_with_correct_base_url(self):
- body = _build_openclaw_config(
- port=54321,
- entries=[("openai/gpt-5.2", "GPT 5.2", "desc")],
- primary_model_id="switchyard/openai/gpt-5.2",
- )
- provider = body["models"]["providers"][_PROVIDER_ID]
- assert provider["baseUrl"] == "http://127.0.0.1:54321/v1"
- # The api field must match the openclaw docs' allowed values.
- assert provider["api"] == "openai-completions"
- # apiKey uses ${ENV_VAR} interpolation so the real placeholder
- # never lands in the JSON on disk.
- assert provider["apiKey"] == "${" + _API_KEY_ENV + "}"
-
- def test_merge_mode_does_not_clobber_default_providers(self):
- body = _build_openclaw_config(
- port=54321,
- entries=[("openai/gpt-5.2", "GPT 5.2", "desc")],
- primary_model_id="switchyard/openai/gpt-5.2",
- )
- assert body["models"]["mode"] == "merge"
-
- def test_primary_model_is_qualified(self):
- body = _build_openclaw_config(
- port=54321,
- entries=[("openai/gpt-5.2", "GPT 5.2", "desc")],
- primary_model_id="switchyard/openai/gpt-5.2",
- )
- assert body["agents"]["defaults"]["model"]["primary"] == "switchyard/openai/gpt-5.2"
-
- def test_emits_one_models_entry_per_catalog_row(self):
- body = _build_openclaw_config(
- port=54321,
- entries=[
- ("openai/gpt-5.2", "GPT 5.2", "primary"),
- ("nvidia/moonshotai/kimi-k2.5", "Kimi", "extra"),
- ],
- primary_model_id="switchyard/openai/gpt-5.2",
- )
- models = body["models"]["providers"][_PROVIDER_ID]["models"]
- assert [m["id"] for m in models] == [
- "openai/gpt-5.2",
- "nvidia/moonshotai/kimi-k2.5",
- ]
- assert [m["name"] for m in models] == ["GPT 5.2", "Kimi"]
- # Every entry has the minimal capability set openclaw expects.
- for entry in models:
- assert entry["input"] == ["text"]
- assert entry["contextWindow"] > 0
- assert entry["maxTokens"] > 0
-
- def test_aliases_use_qualified_model_id_keys(self):
- body = _build_openclaw_config(
- port=54321,
- entries=[("openai/gpt-5.2", "GPT 5.2", "primary")],
- primary_model_id="switchyard/openai/gpt-5.2",
- )
- aliases = body["agents"]["defaults"]["models"]
- # OpenClaw references models by ``provider/model`` everywhere;
- # the alias keys must use the same form.
- assert "switchyard/openai/gpt-5.2" in aliases
- assert aliases["switchyard/openai/gpt-5.2"]["alias"] == "GPT 5.2"
-
-
-# ---------------------------------------------------------------------------
-# _write_openclaw_workspace
-# ---------------------------------------------------------------------------
-
-
-class TestWriteOpenclawWorkspace:
- def test_writes_valid_json5_compatible_json(self, tmp_path, monkeypatch):
- # mkdtemp lands the workspace in tmp_path so the test stays
- # isolated from the system temp dir.
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher.tempfile.mkdtemp",
- lambda prefix: str(tmp_path / "ws"),
- )
- (tmp_path / "ws").mkdir()
- workspace = _write_openclaw_workspace(
- port=54321,
- entries=[("openai/gpt-5.2", "GPT 5.2", "desc")],
- primary_model_id="switchyard/openai/gpt-5.2",
- )
- config_path = Path(workspace) / "openclaw.json"
- assert config_path.is_file()
- body = json.loads(config_path.read_text())
- assert body["models"]["providers"]["switchyard"]["api"] == "openai-completions"
- assert (
- body["agents"]["defaults"]["model"]["primary"]
- == "switchyard/openai/gpt-5.2"
- )
-
-
-# ---------------------------------------------------------------------------
-# _openclaw_env
-# ---------------------------------------------------------------------------
-
-
-class TestOpenclawEnv:
- """The env-var contract is the only thing pointing openclaw at our
- transient workspace — drift here silently sends openclaw at the
- user's real ~/.openclaw/ and bypasses the proxy entirely.
- """
-
- def test_relocates_state_dir(self):
- env = _openclaw_env(workspace="/tmp/switchyard-openclaw-xyz")
- assert env["OPENCLAW_STATE_DIR"] == "/tmp/switchyard-openclaw-xyz"
- assert env["OPENCLAW_HOME"] == "/tmp/switchyard-openclaw-xyz"
- assert (
- env["OPENCLAW_CONFIG_PATH"]
- == "/tmp/switchyard-openclaw-xyz/openclaw.json"
- )
-
- def test_hides_banner(self):
- env = _openclaw_env(workspace="/tmp/x")
- assert env["OPENCLAW_HIDE_BANNER"] == "1"
-
- def test_sets_api_key_placeholder(self):
- env = _openclaw_env(workspace="/tmp/x")
- assert env[_API_KEY_ENV] == _API_KEY_PLACEHOLDER
-
- def test_intake_session_id_propagates(self):
- intake = LaunchIntakeConfig.from_resolved(
- base_url=None, workspace=None, api_key=None,
- app="openclaw", task="developer-session",
- session_id="sess-xyz", target="openclaw",
- )
- env = _openclaw_env(workspace="/tmp/x", intake=intake)
- assert env["SWITCHYARD_SESSION_ID"] == "sess-xyz"
-
- def test_no_intake_omits_session_id(self):
- env = _openclaw_env(workspace="/tmp/x")
- assert "SWITCHYARD_SESSION_ID" not in env
-
-
-# ---------------------------------------------------------------------------
-# _openclaw_command
-# ---------------------------------------------------------------------------
-
-
-class TestOpenclawCommand:
- def test_prepends_chat_subcommand(self):
- # `openclaw chat` (alias for `openclaw tui --local`) is the
- # interactive subcommand. `openclaw agent` is the one-shot
- # non-interactive form and is reserved for verify.
- cmd = _openclaw_command("/fake/bin/openclaw", [])
- assert cmd == ["/fake/bin/openclaw", "chat"]
-
- def test_forwards_user_args_after_chat(self):
- cmd = _openclaw_command("/fake/bin/openclaw", ["--thinking", "high"])
- assert cmd == ["/fake/bin/openclaw", "chat", "--thinking", "high"]
-
-
-# ---------------------------------------------------------------------------
-# launch_openclaw — integration (with mocked externals)
-# ---------------------------------------------------------------------------
-
-
-def _make_fake_server(started: bool = True) -> MagicMock:
- """uvicorn.Server stand-in that reports started immediately."""
- server = MagicMock()
- server.started = started
- server.should_exit = False
- return server
-
-
-def _stub_spawn_proxy(server: MagicMock):
- """Return a function that mimics _spawn_proxy_thread's (server, thread) tuple."""
- def _inner(switchyard, port):
- thread = MagicMock()
- return server, thread
- return _inner
-
-
[email protected](autouse=True)
-def _mock_ready_and_tty(monkeypatch, tmp_path):
- """Launcher tests use fake servers, so bypass external runtime side effects."""
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._wait_ready",
- lambda port, timeout_s=10.0: True,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher.stdin_is_tty",
- lambda: False,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher.configure_debug_file_logging",
- lambda display_model: tmp_path / "switchyard.log",
- )
-
-
-class TestLaunchOpenclaw:
- def test_happy_path(self, monkeypatch, tmp_path):
- fake_server = _make_fake_server(started=True)
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._find_openclaw_binary",
- lambda: "/fake/bin/openclaw",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._spawn_proxy_thread",
- _stub_spawn_proxy(fake_server),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher.tempfile.mkdtemp",
- lambda prefix: str(tmp_path / "ws"),
- )
- (tmp_path / "ws").mkdir()
-
- captured: dict = {}
-
- def fake_run(cmd, env, check):
- # Snapshot the config file at the moment openclaw would
- # see it — the launcher's finally block tears down the
- # tempdir before the call returns.
- captured["cmd"] = cmd
- captured["env"] = env
- config_path = Path(env["OPENCLAW_CONFIG_PATH"])
- captured["config"] = json.loads(config_path.read_text())
- return subprocess.CompletedProcess(cmd, returncode=0)
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- exit_code = launch_openclaw(
- model="nvidia/moonshotai/kimi-k2.5",
- base_url="https://inference-api.nvidia.com/v1",
- api_key="test-key",
- port=None,
- timeout=None,
- openclaw_args=["--verbose"],
- )
-
- assert exit_code == 0
- cmd = captured["cmd"]
- # argv layout: [openclaw_bin, "chat", *openclaw_args] — `chat`
- # is the interactive local TUI; `agent` is the one-shot form
- # verify uses, not what launch wants.
- assert cmd == ["/fake/bin/openclaw", "chat", "--verbose"]
- # Env-var contract — these are the only knobs pointing openclaw
- # at our proxy. Verify every required one was set.
- env = captured["env"]
- assert env["OPENCLAW_STATE_DIR"] == str(tmp_path / "ws")
- assert env["OPENCLAW_HOME"] == str(tmp_path / "ws")
- assert env["OPENCLAW_CONFIG_PATH"] == str(tmp_path / "ws" / "openclaw.json")
- assert env[_API_KEY_ENV] == _API_KEY_PLACEHOLDER
- # Config file is written before the spawn.
- provider = captured["config"]["models"]["providers"]["switchyard"]
- assert provider["baseUrl"] == "http://127.0.0.1:54321/v1"
- # Tempdir is cleaned up after openclaw exits.
- assert not (tmp_path / "ws" / "openclaw.json").exists()
- # Proxy torn down on return.
- assert fake_server.should_exit is True
-
- def test_port_override(self, monkeypatch, tmp_path):
- fake_server = _make_fake_server(started=True)
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._find_openclaw_binary",
- lambda: "/fake/bin/openclaw",
- )
-
- # If --port is set, _find_free_port should NOT be called.
- def _should_not_be_called():
- raise AssertionError("_find_free_port called despite --port override")
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._find_free_port",
- _should_not_be_called,
- )
-
- captured: dict = {}
-
- def stub_spawn(switchyard, port):
- captured["port"] = port
- thread = MagicMock()
- return fake_server, thread
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._spawn_proxy_thread",
- stub_spawn,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher.tempfile.mkdtemp",
- lambda prefix: str(tmp_path / "ws2"),
- )
- (tmp_path / "ws2").mkdir()
-
- def capture_run(cmd, env, check):
- config_path = Path(env["OPENCLAW_CONFIG_PATH"])
- captured["config"] = json.loads(config_path.read_text())
- return subprocess.CompletedProcess(cmd, returncode=0)
-
- monkeypatch.setattr(subprocess, "run", capture_run)
-
- exit_code = launch_openclaw(
- model="m", base_url="u", api_key="k",
- port=4000, timeout=None, openclaw_args=[],
- )
-
- assert exit_code == 0
- assert captured["port"] == 4000
- assert (
- captured["config"]["models"]["providers"]["switchyard"]["baseUrl"]
- == "http://127.0.0.1:4000/v1"
- )
-
- def test_missing_binary_returns_127(self, monkeypatch):
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._find_openclaw_binary",
- lambda: None,
- )
-
- def _should_not_spawn(*args, **kwargs):
- raise AssertionError("proxy spawned despite missing binary")
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._spawn_proxy_thread",
- _should_not_spawn,
- )
-
- exit_code = launch_openclaw(
- model="m", base_url="u", api_key="k",
- port=None, timeout=None, openclaw_args=[],
- )
- assert exit_code == _EXIT_BINARY_NOT_FOUND
-
- def test_ctrl_c_returns_130_and_tears_down(self, monkeypatch, tmp_path):
- fake_server = _make_fake_server(started=True)
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._find_openclaw_binary",
- lambda: "/fake/bin/openclaw",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._spawn_proxy_thread",
- _stub_spawn_proxy(fake_server),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher.tempfile.mkdtemp",
- lambda prefix: str(tmp_path / "ws3"),
- )
- (tmp_path / "ws3").mkdir()
-
- def raise_sigint(cmd, env, check):
- raise KeyboardInterrupt()
- monkeypatch.setattr(subprocess, "run", raise_sigint)
-
- exit_code = launch_openclaw(
- model="m", base_url="u", api_key="k",
- port=None, timeout=None, openclaw_args=[],
- )
-
- assert exit_code == _EXIT_SIGINT
- assert fake_server.should_exit is True
-
- def test_strips_leading_double_dash_from_openclaw_args(
- self, monkeypatch, tmp_path,
- ):
- """``argparse.REMAINDER`` keeps the ``--`` sentinel in the captured
- list, so ``launch openclaw ... -- --verbose`` produces
- ``['--', '--verbose']``. The handler must strip the leading ``--``
- before forwarding so openclaw doesn't receive a bare ``--`` arg.
- """
- from switchyard.cli.switchyard_cli import (
- _build_parser,
- _cmd_launch_openclaw,
- )
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "openclaw",
- "--model", "nvidia/moonshotai/kimi-k2.5",
- "--api-key", "sk-test",
- "--", "--verbose",
- ])
- assert args.openclaw_args == ["--", "--verbose"]
-
- captured: dict = {}
-
- def fake_launch(**kwargs):
- captured.update(kwargs)
- raise SystemExit(0)
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://inference-api.nvidia.com/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher.launch_openclaw",
- fake_launch,
- )
-
- with pytest.raises(SystemExit):
- _cmd_launch_openclaw(args)
-
- assert captured["openclaw_args"] == ["--verbose"]
-
- def test_no_model_defaults_to_classifier(self, monkeypatch, tmp_path):
- """No ``--model`` no longer errors — it defaults to LLM-classifier
- routing, the same implicit default as ``launch claude`` / ``codex``.
- """
- from switchyard.cli.switchyard_cli import (
- _build_parser,
- _cmd_launch_openclaw,
- )
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
-
- def fake_passthrough(**_kwargs):
- raise AssertionError(
- "no --model should default to the classifier launcher, "
- "not single-model passthrough",
- )
-
- def fake_classifier(**_kwargs):
- raise SystemExit(0)
-
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://inference-api.nvidia.com/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher.launch_openclaw",
- fake_passthrough,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher."
- "launch_openclaw_deterministic_routing",
- fake_classifier,
- )
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "openclaw", "--api-key", "sk-test",
- ])
- with pytest.raises(SystemExit):
- _cmd_launch_openclaw(args)
-
- def test_proxy_never_ready_returns_error(self, monkeypatch, tmp_path):
- fake_server = _make_fake_server(started=False)
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._find_openclaw_binary",
- lambda: "/fake/bin/openclaw",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._spawn_proxy_thread",
- _stub_spawn_proxy(fake_server),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher.tempfile.mkdtemp",
- lambda prefix: str(tmp_path / "ws-fail"),
- )
- (tmp_path / "ws-fail").mkdir()
- # Override the autouse readiness mock to simulate a timeout.
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._wait_ready",
- lambda port, timeout_s=10.0: False,
- )
-
- def _should_not_run(*args, **kwargs):
- raise AssertionError("openclaw spawned despite proxy not ready")
- monkeypatch.setattr(subprocess, "run", _should_not_run)
-
- exit_code = launch_openclaw(
- model="m", base_url="u", api_key="k",
- port=None, timeout=None, openclaw_args=[],
- )
- assert exit_code == 1
- assert fake_server.should_exit is True
-
- def test_uses_openai_translation_chain(self, monkeypatch, tmp_path):
- """OpenClaw speaks OpenAI Chat Completions → backend is an
- OpenAI-native backend behind the stats wrapper.
- """
- from switchyard.lib.backends.stats_llm_backend import StatsLlmBackend
- from switchyard.lib.processors.stats_response_processor_accumulator import (
- StatsResponseProcessor,
- )
-
- model = "nvidia/moonshotai/kimi-k2.5"
- captured_switchyard: dict = {}
-
- def stub_spawn(app, port):
- assert isinstance(app, RouteTable)
- chain = app.lookup_switchyard(model)
- captured_switchyard["app"] = app
- captured_switchyard["switchyard"] = chain
- captured_switchyard["backend"] = next(
- component
- for component in chain.iter_components()
- if isinstance(component, StatsLlmBackend)
- )
- return _make_fake_server(started=True), MagicMock()
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._find_openclaw_binary",
- lambda: "/fake/bin/openclaw",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._spawn_proxy_thread",
- stub_spawn,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher.tempfile.mkdtemp",
- lambda prefix: str(tmp_path / "ws-chain"),
- )
- (tmp_path / "ws-chain").mkdir()
- monkeypatch.setattr(
- subprocess, "run",
- lambda cmd, env, check: subprocess.CompletedProcess(cmd, returncode=0),
- )
-
- launch_openclaw(
- model=model,
- base_url="https://inference-api.nvidia.com/v1",
- api_key="sk-test",
- port=None, timeout=None, openclaw_args=[],
- )
- table = captured_switchyard["app"]
- assert table.registered_models() == [model]
- assert table.default_model() == model
- assert isinstance(captured_switchyard["backend"], StatsLlmBackend)
- assert [
- item.value
- for item in captured_switchyard["backend"].supported_request_types
- ] == ["openai_chat"]
- assert any(
- isinstance(component, StatsResponseProcessor)
- for component in captured_switchyard["switchyard"].iter_components()
- )
-
- def test_tty_mode_wraps_openclaw_with_stats_footer(self, monkeypatch, tmp_path):
- """Interactive OpenClaw launches should get the Switchyard footer."""
- captured: dict = {}
-
- class FakeShellTUI:
- def __init__(self, command, footer_fn, footer_height, env):
- captured["command"] = command
- captured["footer_fn"] = footer_fn
- captured["footer_height"] = footer_height
- captured["env"] = env
-
- def run(self):
- return 0
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._find_openclaw_binary",
- lambda: "/fake/bin/openclaw",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._spawn_proxy_thread",
- _stub_spawn_proxy(_make_fake_server(started=True)),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher.stdin_is_tty",
- lambda: True,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher.ShellTUI",
- FakeShellTUI,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher.tempfile.mkdtemp",
- lambda prefix: str(tmp_path / "ws-tty"),
- )
- (tmp_path / "ws-tty").mkdir()
-
- exit_code = launch_openclaw(
- model="nvidia/moonshotai/kimi-k2.5",
- base_url="https://inference-api.nvidia.com/v1",
- api_key="sk-test",
- port=None,
- timeout=None,
- openclaw_args=["--verbose"],
- )
-
- assert exit_code == 0
- assert captured["command"] == ["/fake/bin/openclaw", "chat", "--verbose"]
- assert callable(captured["footer_height"]) and captured["footer_height"]() == 2
- rows = captured["footer_fn"](120)
- assert len(rows) == 2
- assert "switchyard" in rows[0][0]
- assert captured["env"]["OPENCLAW_STATE_DIR"] == str(tmp_path / "ws-tty")
-
- def test_smoke_with_routing_profiles_errors_clearly(
- self, monkeypatch, tmp_path,
- ):
- """``--smoke --routing-profiles FILE`` is rejected at the CLI level."""
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_openclaw
-
- yaml_path = tmp_path / "bundle.yaml"
- yaml_path.write_text(
- "routes:\n"
- " fast-nemotron:\n"
- " type: model\n"
- " target: nvidia/nvidia/nemotron-nano-9b-v2\n"
- )
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://inference-api.nvidia.com/v1"),
- )
- parser = _build_parser()
- args = parser.parse_args([
- "--routing-profiles", str(yaml_path),
- "launch", "openclaw", "--smoke", "--api-key", "sk-test",
- ])
- with pytest.raises(SystemExit) as exc_info:
- _cmd_launch_openclaw(args)
- assert "--smoke and --routing-profiles cannot be combined" in str(exc_info.value)
-
- def test_smoke_without_model_errors_with_helpful_message(
- self, monkeypatch, tmp_path,
- ):
- """``--smoke`` with no model gives a clear error directing to ``--model``."""
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_openclaw
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://inference-api.nvidia.com/v1"),
- )
- parser = _build_parser()
- args = parser.parse_args(["launch", "openclaw", "--smoke", "--api-key", "sk-test"])
- with pytest.raises(SystemExit) as exc_info:
- _cmd_launch_openclaw(args)
- assert "--smoke requires --model" in str(exc_info.value)
-
- def test_routing_profiles_merges_extras_on_top_of_launcher_table(
- self, monkeypatch, tmp_path,
- ):
- """`--routing-profiles` adds YAML routes on top of the launcher's chain.
-
- The launcher registers its ``--model`` chain under ``model``; every
- YAML entry is merged on top via
- :meth:`RouteTable.register`. YAML wins on id conflict.
- """
- captured_switchyard: dict = {}
-
- def stub_spawn(switchyard, port):
- captured_switchyard["app"] = switchyard
- return _make_fake_server(started=True), MagicMock()
-
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._find_openclaw_binary",
- lambda: "/fake/bin/openclaw",
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._find_free_port",
- lambda: 54321,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._spawn_proxy_thread",
- stub_spawn,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher.tempfile.mkdtemp",
- lambda prefix: str(tmp_path / "ws-routes"),
- )
- (tmp_path / "ws-routes").mkdir()
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda cmd, env, check: subprocess.CompletedProcess(cmd, returncode=0),
- )
-
- yaml_path = tmp_path / "extras.yaml"
- yaml_path.write_text(
- "routes:\n"
- " extras/yaml-only:\n"
- " type: model\n"
- " target:\n"
- " model: extras/yaml-only\n"
- " api_key: sk-yaml\n"
- " base_url: https://yaml.example/v1\n"
- " primary/model:\n"
- " type: model\n"
- " target:\n"
- " model: primary/model\n"
- " api_key: sk-yaml-override\n"
- " base_url: https://yaml-override.example/v1\n"
- )
-
- def capture_run(cmd, env, check):
- config_path = Path(env["OPENCLAW_CONFIG_PATH"])
- captured_switchyard["config"] = json.loads(config_path.read_text())
- return subprocess.CompletedProcess(cmd, returncode=0)
-
- monkeypatch.setattr(subprocess, "run", capture_run)
-
- launch_openclaw(
- model="primary/model",
- base_url="https://example.invalid/v1",
- api_key="sk-test",
- port=None,
- timeout=None,
- openclaw_args=[],
- routing_profiles=str(yaml_path),
- )
-
- table = captured_switchyard["app"]
- assert isinstance(table, RouteTable)
- assert table.registered_models() == [
- "primary/model",
- "extras/yaml-only",
- ]
- assert table.default_model() == "primary/model"
- # The YAML-registered model lands in the openclaw.json catalog too.
- config = captured_switchyard["config"]
- catalog_ids = [
- entry["id"]
- for entry in config["models"]["providers"]["switchyard"]["models"]
- ]
- assert "primary/model" in catalog_ids
- assert "extras/yaml-only" in catalog_ids
diff --git a/tests/test_launch_openclaw_deterministic.py b/tests/test_launch_openclaw_deterministic.py
deleted file mode 100644
index 215208a70..000000000
--- a/tests/test_launch_openclaw_deterministic.py
+++ /dev/null
@@ -1,242 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Tests for the LLM-classifier default of ``switchyard launch openclaw``.
-
-``launch openclaw`` defaults to LLM-classifier routing when no ``--model``
-or ``--routing-profiles`` is given — same shape as ``launch claude`` /
-``launch codex``. The legacy ``--deterministic`` opt-in flag has been
-removed; tier overrides (``--weak-model``, ``--classifier-model``,
-``--profile``, ``--classifier-min-confidence``) still tune the default trio.
-"""
-
-from __future__ import annotations
-
-import pytest
-
-
-class TestArgparse:
- def test_deterministic_flag_removed(self) -> None:
- from switchyard.cli.switchyard_cli import _build_parser
-
- parser = _build_parser()
- with pytest.raises(SystemExit):
- parser.parse_args(["launch", "openclaw", "--deterministic"])
-
- def test_default_no_flags_parses(self) -> None:
- from switchyard.cli.switchyard_cli import _build_parser
-
- parser = _build_parser()
- # No --model: the launcher dispatches to LLM-classifier routing as
- # the implicit default.
- args = parser.parse_args(["launch", "openclaw"])
- assert args.model is None
- assert args.routing_profiles is None
- # Override knobs default to None — preset values fill them in.
- assert args.weak_model is None
- assert args.classifier_model is None
- assert args.profile is None
- assert args.classifier_min_confidence is None
-
- def test_overrides_parse(self) -> None:
- from switchyard.cli.switchyard_cli import _build_parser
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "openclaw",
- "--classifier-model", "nvidia/nvidia/nemotron-3-super-v3",
- "--profile", "openclaw",
- "--classifier-min-confidence", "0.55",
- ])
- assert args.classifier_model == "nvidia/nvidia/nemotron-3-super-v3"
- assert args.profile == "openclaw"
- assert args.classifier_min_confidence == 0.55
-
-
-class TestMutualExclusion:
- def test_routing_profiles_opts_out_of_classifier(
- self, monkeypatch, tmp_path,
- ) -> None:
- """``--routing-profiles`` opts out of the LLM-classifier default."""
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_openclaw
-
- yaml_path = tmp_path / "routes.yaml"
- yaml_path.write_text(
- "defaults:\n"
- " api_key: sk-test\n"
- " base_url: https://upstream.invalid/v1\n"
- " format: openai\n"
- "routes:\n"
- " bench:\n"
- " type: model\n"
- " target: some/model\n"
- )
- parser = _build_parser()
- args = parser.parse_args([
- "--routing-profiles", str(yaml_path),
- "launch", "openclaw",
- "--dry-run",
- ])
-
- def fake_deterministic(**_kwargs):
- raise AssertionError(
- "--routing-profiles should opt out of LLM-classifier routing",
- )
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher."
- "launch_openclaw_deterministic_routing",
- fake_deterministic,
- )
- # Dry-run prints + returns without invoking the classifier launcher.
- _cmd_launch_openclaw(args)
-
-
-class TestDispatch:
- def test_default_dispatches_to_classifier_launcher(
- self, monkeypatch, tmp_path,
- ) -> None:
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_openclaw
-
- parser = _build_parser()
- # Zero flags beyond credentials — LLM-classifier routing should fire.
- args = parser.parse_args([
- "launch", "openclaw", "--api-key", "sk-test",
- ])
-
- captured: dict = {}
-
- def fake_launch(**kwargs):
- captured.update(kwargs)
- raise SystemExit(0)
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher."
- "launch_openclaw_deterministic_routing",
- fake_launch,
- )
-
- with pytest.raises(SystemExit):
- _cmd_launch_openclaw(args)
-
- config = captured["config"]
- # The launcher inherits the coding_agent_default trio by default
- # (same defaults as claude/codex implicit LLM-classifier mode).
- assert config.strong.model == "anthropic/claude-opus-4.7"
- assert config.weak.model == "moonshotai/kimi-k2.6"
- assert config.classifier.model == "google/gemini-3.5-flash"
- assert config.profile_name == "coding_agent"
- assert config.preset == "coding_agent_default"
-
- def test_model_flag_opts_out_of_classifier(
- self, monkeypatch, tmp_path,
- ) -> None:
- """Passing --model X falls through to single-model passthrough."""
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_openclaw
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "openclaw",
- "--api-key", "sk-test",
- "--model", "nvidia/moonshotai/kimi-k2.5",
- ])
-
- captured_passthrough: dict = {}
-
- def fake_passthrough(**kwargs):
- captured_passthrough.update(kwargs)
- raise SystemExit(0)
-
- def fake_deterministic(**_kwargs):
- raise AssertionError(
- "--model X should not dispatch to the classifier launcher",
- )
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher.launch_openclaw",
- fake_passthrough,
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher."
- "launch_openclaw_deterministic_routing",
- fake_deterministic,
- )
-
- with pytest.raises(SystemExit):
- _cmd_launch_openclaw(args)
-
- assert captured_passthrough["model"] == "nvidia/moonshotai/kimi-k2.5"
-
- def test_dispatch_honors_profile_override(
- self, monkeypatch, tmp_path,
- ) -> None:
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_openclaw
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "openclaw", "--api-key", "sk-test",
- "--profile", "openclaw",
- ])
-
- captured: dict = {}
-
- def fake_launch(**kwargs):
- captured.update(kwargs)
- raise SystemExit(0)
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher."
- "launch_openclaw_deterministic_routing",
- fake_launch,
- )
-
- with pytest.raises(SystemExit):
- _cmd_launch_openclaw(args)
-
- config = captured["config"]
- assert config.profile_name == "openclaw"
-
- def test_dry_run_does_not_invoke_launcher(self, monkeypatch, tmp_path) -> None:
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_openclaw
-
- parser = _build_parser()
- args = parser.parse_args([
- "launch", "openclaw", "--api-key", "sk-test",
- "--dry-run",
- ])
-
- def fake_launch(**_kwargs):
- raise AssertionError("dry-run must not invoke the launcher")
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher."
- "launch_openclaw_deterministic_routing",
- fake_launch,
- )
-
- _cmd_launch_openclaw(args)
diff --git a/tests/test_launch_route_builder.py b/tests/test_launch_route_builder.py
deleted file mode 100644
index 6352302ac..000000000
--- a/tests/test_launch_route_builder.py
+++ /dev/null
@@ -1,190 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-import pytest
-
-from switchyard.cli.config.user_config import LaunchRouteConfig
-from switchyard.cli.routing.route_builder import (
- LaunchTierConnectivity,
- build_deterministic_routing_config,
- build_random_routing_config,
-)
-from switchyard.lib.backends.llm_target import BackendFormat, LlmTarget
-from switchyard.lib.profiles.random_routing import (
- RandomRoutingConfig,
-)
-from switchyard.lib.route_table_builders import build_passthrough_table
-from switchyard.lib.stats_accumulator import StatsAccumulator
-
-
-def _connectivity() -> LaunchTierConnectivity:
- return LaunchTierConnectivity(
- api_key="sk-test",
- base_url="https://openrouter.ai/api/v1",
- )
-
-
-def test_random_launch_routes_use_auto_backend_format_for_both_tiers() -> None:
- route = LaunchRouteConfig(
- type="random",
- model="strong-model",
- weak_model="weak-model",
- )
-
- config = build_random_routing_config(
- route,
- primary=_connectivity(),
- weak=_connectivity(),
- timeout=None,
- )
-
- assert config.strong.format is BackendFormat.AUTO
- assert config.weak.format is BackendFormat.AUTO
-
-
-def test_passthrough_table_dedupes_endpoints_and_registers_discovered_models() -> None:
- calls: list[tuple[str, str]] = []
-
- def fake_discover_models(base_url: str, api_key: str) -> list[str]:
- calls.append((base_url, api_key))
- if base_url == "https://primary.example/v1":
- return ["primary/extra", "shared/model"]
- return ["weak/extra", "shared/model"]
-
- config = RandomRoutingConfig(
- strong=LlmTarget(
- model="strong/model",
- format=BackendFormat.AUTO,
- api_key="primary-key",
- base_url="https://primary.example/v1",
- ),
- weak=LlmTarget(
- model="weak/model",
- format=BackendFormat.AUTO,
- api_key="weak-key",
- base_url="https://weak.example/v1",
- ),
- fallback_target_on_evict="strong")
-
- table = build_passthrough_table(
- (config.strong, config.weak),
- StatsAccumulator(),
- discovery_fn=fake_discover_models,
- )
-
- # Each (base_url, api_key) pair is fetched exactly once.
- assert calls == [
- ("https://primary.example/v1", "primary-key"),
- ("https://weak.example/v1", "weak-key"),
- ]
- # Configured tier models register before discovered models; identical
- # discovered ids across tiers register against the first tier that saw them.
- assert table.registered_models() == [
- "strong/model",
- "weak/model",
- "primary/extra",
- "shared/model",
- "weak/extra",
- ]
-
-
-def test_passthrough_table_skips_discovery_when_fn_is_none() -> None:
- config = RandomRoutingConfig(
- strong=LlmTarget(
- model="strong/model",
- format=BackendFormat.AUTO,
- api_key="primary-key",
- base_url="https://primary.example/v1",
- ),
- weak=LlmTarget(
- model="weak/model",
- format=BackendFormat.AUTO,
- api_key="weak-key",
- base_url="https://weak.example/v1",
- ),
- fallback_target_on_evict="strong")
-
- table = build_passthrough_table(
- (config.strong, config.weak),
- StatsAccumulator(),
- # discovery_fn=None (default) — no discovery runs.
- )
-
- # Only the configured tier models register; discovery never runs.
- assert table.registered_models() == ["strong/model", "weak/model"]
-
-
-def test_deterministic_launch_routes_use_preset_defaults() -> None:
- """Zero-override --deterministic launches use the validated TB-Lite trio."""
- route = LaunchRouteConfig(type="deterministic")
- config = build_deterministic_routing_config(
- route,
- primary=_connectivity(),
- weak=_connectivity(),
- classifier_model=None,
- profile_name=None,
- classifier_min_confidence=None,
- backend_format=BackendFormat.OPENAI,
- timeout=600.0,
- )
- assert config.strong.model == "anthropic/claude-opus-4.7"
- assert config.weak.model == "moonshotai/kimi-k2.6"
- assert config.classifier.model == "google/gemini-3.5-flash"
- assert config.profile_name == "coding_agent"
- assert config.classifier_min_confidence == 0.0
- assert config.preset == "coding_agent_default"
-
-
-def test_deterministic_launch_routes_apply_user_overrides() -> None:
- """User-supplied --model / --weak-model / --classifier-model / --profile win."""
- route = LaunchRouteConfig(
- type="deterministic",
- model="openai/openai/gpt-5.2",
- weak_model="nvidia/moonshotai/kimi-k2.5",
- )
- config = build_deterministic_routing_config(
- route,
- primary=_connectivity(),
- weak=_connectivity(),
- classifier_model="nvidia/nvidia/nemotron-3-super-v3",
- profile_name="general",
- classifier_min_confidence=0.55,
- backend_format=BackendFormat.OPENAI,
- timeout=600.0,
- )
- assert config.strong.model == "openai/openai/gpt-5.2"
- assert config.weak.model == "nvidia/moonshotai/kimi-k2.5"
- assert config.classifier.model == "nvidia/nvidia/nemotron-3-super-v3"
- assert config.profile_name == "general"
- assert config.classifier_min_confidence == 0.55
- assert config.preset is None
-
-
-def test_deterministic_launch_routes_reject_invalid_profile() -> None:
- route = LaunchRouteConfig(type="deterministic")
- with pytest.raises(SystemExit, match="unknown profile"):
- build_deterministic_routing_config(
- route,
- primary=_connectivity(),
- weak=_connectivity(),
- classifier_model=None,
- profile_name="invented_profile",
- classifier_min_confidence=None,
- backend_format=BackendFormat.OPENAI,
- timeout=600.0,
- )
-
-
-def test_deterministic_launch_routes_reject_out_of_range_confidence() -> None:
- route = LaunchRouteConfig(type="deterministic")
- with pytest.raises(SystemExit, match=r"\[0\.0, 1\.0\]"):
- build_deterministic_routing_config(
- route,
- primary=_connectivity(),
- weak=_connectivity(),
- classifier_model=None,
- profile_name=None,
- classifier_min_confidence=1.5,
- backend_format=BackendFormat.OPENAI,
- timeout=600.0,
- )
diff --git a/tests/test_launchers.py b/tests/test_launchers.py
new file mode 100644
index 000000000..fa4ec9e2d
--- /dev/null
+++ b/tests/test_launchers.py
@@ -0,0 +1,86 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Contract tests for the minimal coding-agent launcher surface."""
+
+import argparse
+from pathlib import Path
+
+import pytest
+
+from switchyard.cli.launch_command import _config_path
+from switchyard.cli.launchers.native_server import NativeServer
+from switchyard.cli.switchyard_cli import _build_parser
+
+
+def _subparsers(parser: argparse.ArgumentParser) -> dict[str, argparse.ArgumentParser]:
+ action = next(
+ action
+ for action in parser._actions
+ if isinstance(action, argparse._SubParsersAction)
+ )
+ return action.choices # type: ignore[return-value]
+
+
+def test_cli_exposes_only_serve_and_launch() -> None:
+ assert set(_subparsers(_build_parser())) == {"serve", "launch"}
+
+
[email protected]("agent", ["claude", "codex", "openclaw"])
+def test_launcher_surface_is_model_config_and_forwarded_args(agent: str) -> None:
+ launch = _subparsers(_build_parser())["launch"]
+ parser = _subparsers(launch)[agent]
+ options = {
+ option
+ for action in parser._actions
+ for option in action.option_strings
+ if option != "--help"
+ }
+ assert options == {"-h", "--model", "--config"}
+
+ args = parser.parse_args(["--model", "switchyard", "--", "--version"])
+ assert args.model == "switchyard"
+ assert args.config is None
+ assert vars(args)[f"{agent}_args"] == ["--", "--version"]
+
+
+def test_default_config_is_packaged_openrouter_deployment() -> None:
+ config = _config_path(None)
+ assert config.name == "openrouter.toml"
+ assert "OPENROUTER_API_KEY" in config.read_text()
+
+
+def test_native_server_passes_config_directly_to_binding(
+ monkeypatch: pytest.MonkeyPatch,
+ tmp_path: Path,
+) -> None:
+ config = tmp_path / "routes.toml"
+ config.write_text("schema_version = 1\n")
+ captured: dict[str, object] = {}
+
+ class FakeServer:
+ port = 4321
+ base_url = "http://127.0.0.1:4321"
+
+ def __init__(self, path: Path, *, port: int) -> None:
+ captured["path"] = path
+ captured["port"] = port
+
+ def close(self) -> None:
+ captured["closed"] = True
+
+ import switchyard_rust.server
+
+ monkeypatch.setattr(switchyard_rust.server, "Server", FakeServer)
+ server = NativeServer(config)
+ server.close()
+
+ assert captured == {"path": config, "port": 0, "closed": True}
+ assert server.port == 4321
+ assert config.exists()
+
+
+def test_missing_explicit_config_is_a_cli_error(tmp_path: Path) -> None:
+ missing = tmp_path / "missing.toml"
+ with pytest.raises(SystemExit, match="config file not found"):
+ _config_path(str(missing))
diff --git a/tests/test_model_discovery.py b/tests/test_model_discovery.py
deleted file mode 100644
index 5caf780a4..000000000
--- a/tests/test_model_discovery.py
+++ /dev/null
@@ -1,191 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-from switchyard.cli.model_catalog.model_discovery import (
- choose_default_claude_model,
- choose_default_codex_model,
- claude_model_candidates,
- codex_model_candidates,
-)
-
-
-def test_choose_default_claude_model_prefers_opus_47():
- models = [
- "azure/anthropic/claude-sonnet-4-6",
- "aws/anthropic/bedrock-claude-opus-4-6",
- "aws/anthropic/bedrock-claude-opus-4-7",
- "nvidia/moonshotai/kimi-k2.6",
- ]
-
- assert (
- choose_default_claude_model(models)
- == "aws/anthropic/bedrock-claude-opus-4-7"
- )
- assert claude_model_candidates(models)[0] == "aws/anthropic/bedrock-claude-opus-4-7"
-
-
-def test_choose_default_claude_model_prefers_newer_opus_without_ceiling():
- models = [
- "azure/anthropic/claude-sonnet-5-0",
- "aws/anthropic/bedrock-claude-opus-4-7",
- "aws/anthropic/bedrock-claude-opus-4-8",
- ]
-
- assert (
- choose_default_claude_model(models)
- == "aws/anthropic/bedrock-claude-opus-4-8"
- )
- assert claude_model_candidates(models)[0] == "aws/anthropic/bedrock-claude-opus-4-8"
-
-
-def test_choose_default_claude_model_prefers_stable_over_future_preview():
- models = [
- "anthropic/claude-opus-5-0-preview",
- "aws/anthropic/bedrock-claude-opus-4-7",
- ]
-
- assert (
- choose_default_claude_model(models)
- == "aws/anthropic/bedrock-claude-opus-4-7"
- )
-
-
-def test_choose_default_claude_model_ignores_date_suffix_as_model_version():
- models = [
- "anthropic/claude-3-5-sonnet-20241022",
- "anthropic/claude-sonnet-3-7",
- ]
-
- assert (
- choose_default_claude_model(models)
- == "anthropic/claude-sonnet-3-7"
- )
-
-
-def test_choose_default_claude_model_handles_legacy_version_before_family():
- models = [
- "anthropic/claude-3-5-sonnet-20241022",
- "anthropic/claude-3-7-sonnet-20250219",
- ]
-
- assert (
- choose_default_claude_model(models)
- == "anthropic/claude-3-7-sonnet-20250219"
- )
-
-
-def test_choose_default_claude_model_handles_vertex_snapshot_separator():
- models = [
- "anthropic/claude-sonnet-4-5@20251001",
- "anthropic/claude-sonnet-4-6",
- ]
-
- assert choose_default_claude_model(models) == "anthropic/claude-sonnet-4-6"
-
-
-def test_choose_default_claude_model_falls_back_to_sonnet():
- models = [
- "nvidia/moonshotai/kimi-k2.6",
- "azure/anthropic/claude-sonnet-4-6",
- ]
-
- assert choose_default_claude_model(models) == "azure/anthropic/claude-sonnet-4-6"
-
-
-def test_choose_default_claude_model_returns_none_without_candidates():
- models = [
- "nvidia/moonshotai/kimi-k2.6",
- "openai/openai/openai/gpt-5.5",
- ]
-
- assert choose_default_claude_model(models) is None
- assert claude_model_candidates(models) == []
-
-
-def test_choose_default_codex_model_prefers_gpt_55():
- models = [
- "openai/openai/openai/gpt-5.2",
- "openai/openai/openai/gpt-5.5",
- "openai/openai/openai/gpt-4.1",
- "aws/anthropic/bedrock-claude-opus-4-7",
- ]
-
- assert choose_default_codex_model(models) == "openai/openai/openai/gpt-5.5"
- assert codex_model_candidates(models)[0] == "openai/openai/openai/gpt-5.5"
-
-
-def test_choose_default_codex_model_prefers_future_gpt_without_ceiling():
- models = [
- "openai/openai/openai/gpt-5.5",
- "openai/openai/openai/gpt-5.6",
- "openai/openai/openai/gpt-5.4-codex",
- ]
-
- assert choose_default_codex_model(models) == "openai/openai/openai/gpt-5.6"
- assert codex_model_candidates(models)[0] == "openai/openai/openai/gpt-5.6"
-
-
-def test_choose_default_codex_model_prefers_stable_over_preview():
- models = [
- "openai/openai/openai/gpt-5.5",
- "openai/openai/openai/gpt-6.0-preview",
- ]
-
- assert choose_default_codex_model(models) == "openai/openai/openai/gpt-5.5"
-
-
-def test_choose_default_codex_model_uses_exact_gpt_segment():
- models = [
- "notopenai/vendor/egpt-9",
- "openai/openai/openai/gpt-5.5",
- ]
-
- assert choose_default_codex_model(models) == "openai/openai/openai/gpt-5.5"
- assert codex_model_candidates(models) == ["openai/openai/openai/gpt-5.5"]
-
-
-def test_choose_default_codex_model_skips_non_chat_models():
- models = [
- "openai/openai/openai/gpt-5.5-embedding",
- "openai/openai/openai/gpt-5.4",
- ]
-
- assert choose_default_codex_model(models) == "openai/openai/openai/gpt-5.4"
-
-
-def test_choose_default_codex_model_prefers_newer_gpt_5_when_no_55():
- models = [
- "openai/openai/openai/gpt-5.2",
- "openai/openai/openai/gpt-5.4",
- "openai/openai/openai/gpt-5.3-codex",
- ]
-
- assert choose_default_codex_model(models) == "openai/openai/openai/gpt-5.4"
-
-
-def test_choose_default_codex_model_prefers_multi_digit_minor_version():
- models = [
- "openai/openai/openai/gpt-5.9",
- "openai/openai/openai/gpt-5.10",
- ]
-
- assert choose_default_codex_model(models) == "openai/openai/openai/gpt-5.10"
-
-
-def test_choose_default_codex_model_prefers_codex_variant_on_same_version():
- models = [
- "openai/openai/openai/gpt-5.2",
- "openai/openai/openai/gpt-5.2-codex",
- ]
-
- assert choose_default_codex_model(models) == "openai/openai/openai/gpt-5.2-codex"
-
-
-def test_choose_default_codex_model_returns_none_without_candidates():
- models = [
- "nvidia/moonshotai/kimi-k2.6",
- "aws/anthropic/bedrock-claude-opus-4-7",
- ]
-
- assert choose_default_codex_model(models) is None
- assert codex_model_candidates(models) == []
diff --git a/tests/test_model_listing.py b/tests/test_model_listing.py
deleted file mode 100644
index 91c941533..000000000
--- a/tests/test_model_listing.py
+++ /dev/null
@@ -1,85 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-from switchyard.lib.model_listing import model_entry, model_list_payload
-
-
-def test_model_entry_merges_metadata_without_overriding_wire_identity() -> None:
- entry = model_entry(
- "served-model",
- metadata={
- "id": "wrong",
- "object": "wrong",
- "type": "wrong",
- "display_name": "Served Model",
- "description": "Runtime route.",
- "owned_by": "nvidia",
- "capabilities": {
- "context_window": 128_000,
- "tool_calling": True,
- },
- },
- )
-
- assert entry["id"] == "served-model"
- assert entry["object"] == "model"
- assert entry["type"] == "model"
- assert entry["display_name"] == "Served Model"
- assert entry["owned_by"] == "nvidia"
- assert entry["description"] == "Runtime route."
- assert entry["capabilities"]["context_window"] == 128_000
- assert entry["capabilities"]["tool_calling"] is True
- assert entry["capabilities"]["streaming"] is True
- assert entry["capabilities"]["supported_inbound_formats"] == [
- "openai-chat-completions",
- "openai-responses",
- "anthropic-messages",
- ]
-
-
-def test_model_list_payload_exposes_default_pool_and_warnings() -> None:
- payload = model_list_payload(
- [
- model_entry("first"),
- model_entry("second"),
- ],
- warnings=["catalog unavailable"],
- )
-
- assert payload["object"] == "list"
- assert payload["first_id"] == "first"
- assert payload["last_id"] == "second"
- assert payload["default_model"] == "first"
- assert payload["model_pool"] == ["first", "second"]
- assert payload["has_more"] is False
- assert payload["warnings"] == ["catalog unavailable"]
-
-
-def test_model_list_payload_uses_advertised_default_when_present() -> None:
- payload = model_list_payload(
- [
- model_entry("strong/model"),
- model_entry("weak/model"),
- model_entry("switchyard-route"),
- ],
- default_model="switchyard-route",
- )
-
- assert payload["first_id"] == "strong/model"
- assert payload["default_model"] == "switchyard-route"
-
-
-def test_model_list_payload_falls_back_when_advertised_default_is_missing() -> None:
- payload = model_list_payload(
- [model_entry("first")],
- default_model="missing",
- )
-
- assert payload["default_model"] == "first"
-
-
-def test_model_entry_defaults_capability_fields_to_non_null_values() -> None:
- entry = model_entry("unknown/model")
-
- assert entry["capabilities"]["tool_calling"] is True
- assert entry["capabilities"]["context_window"] == 128_000
diff --git a/tests/test_proxy_event_loop.py b/tests/test_proxy_event_loop.py
deleted file mode 100644
index e4067f9eb..000000000
--- a/tests/test_proxy_event_loop.py
+++ /dev/null
@@ -1,376 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Tests for launch_claude proxy event-loop safety and the sync probe.
-
-Background
-----------
-The original bug: ``launch_claude`` called ``asyncio.run()`` to run the
-startup probe, which created and then *closed* event loop L1. The
-``AsyncAnthropic`` / ``OpenAILLMClient`` async clients were constructed
-during that same ``asyncio.run()`` call, so their internal httpx connection
-pools could bind to L1.
-
-When uvicorn later created event loop L2 in a background thread and a
-request arrived, ``await client.send(...)`` attempted to use connection-pool
-primitives that were (silently) associated with the closed L1. The coroutine
-never resolved — no exception, no timeout, just an indefinite hang.
-
-Fix: the probe became a synchronous ``httpx.Client`` call (no event loop
-created), and ``_build_claude_switchyard`` remains a plain ``def``.
-Async clients are now constructed with *no* running loop; they bind their
-connection pools to uvicorn's L2 on first use.
-
-What these tests verify
------------------------
-1. Sync probe returns the correct True/False for each HTTP status class.
-2. ``_build_claude_switchyard`` is a plain function (not ``async def``).
-3. No ``asyncio.run()`` is called during switchyard construction.
-4. A proxy built and started the correct way handles requests end-to-end
- without hanging against a loopback OpenAI-compatible upstream.
-5. The "old" pattern — asyncio.run() before client construction — is
- documented as a regression scenario and checked for cross-loop hang.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import json
-import threading
-from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
-from unittest.mock import patch
-
-import httpx
-import pytest
-import respx
-
-from switchyard.cli.launchers.claude_code_launcher import (
- _build_claude_switchyard,
- _find_free_port,
- _spawn_proxy_thread,
- _wait_ready,
-)
-from switchyard.lib.backends.backend_format_resolver import (
- probe_anthropic_messages_support_sync,
-)
-from switchyard.lib.stats_accumulator import StatsAccumulator
-
-_BASE_URL = "https://fake-inference.example.com/v1"
-_MESSAGES_URL = "https://fake-inference.example.com/v1/messages"
-
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-
-def _minimal_openai_completion(model: str = "test-model") -> dict:
- return {
- "id": "chatcmpl-test",
- "object": "chat.completion",
- "created": 1700000000,
- "model": model,
- "choices": [
- {
- "index": 0,
- "message": {"role": "assistant", "content": "pong"},
- "finish_reason": "stop",
- }
- ],
- "usage": {"prompt_tokens": 5, "completion_tokens": 1, "total_tokens": 6},
- }
-
-
-class _OpenAICompatStub:
- def __init__(self) -> None:
- self._server: ThreadingHTTPServer | None = None
- self._thread: threading.Thread | None = None
- self._requests: list[dict[str, object]] = []
-
- def __enter__(self) -> _OpenAICompatStub:
- owner = self
-
- class Handler(BaseHTTPRequestHandler):
- protocol_version = "HTTP/1.1"
-
- def do_POST(self) -> None:
- length = int(self.headers.get("content-length", "0"))
- raw = self.rfile.read(length)
- body = json.loads(raw.decode("utf-8"))
- owner._requests.append({"path": self.path, "body": body})
- content = json.dumps(_minimal_openai_completion()).encode("utf-8")
- self.send_response(200)
- self.send_header("content-type", "application/json")
- self.send_header("content-length", str(len(content)))
- self.send_header("connection", "close")
- self.end_headers()
- self.wfile.write(content)
-
- def log_message(self, _format: str, *args: object) -> None:
- return None
-
- self._server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
- self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
- self._thread.start()
- return self
-
- def __exit__(self, *args: object) -> None:
- if self._server is not None:
- self._server.shutdown()
- self._server.server_close()
- if self._thread is not None:
- self._thread.join(timeout=2)
-
- @property
- def base_url(self) -> str:
- if self._server is None:
- raise RuntimeError("stub server is not running")
- host, port = self._server.server_address
- return f"http://{host}:{port}/v1"
-
- @property
- def requests(self) -> list[dict[str, object]]:
- return list(self._requests)
-
-
-# ---------------------------------------------------------------------------
-# Sync probe — unit tests for every status code branch
-# ---------------------------------------------------------------------------
-
-
-def test_sync_probe_true_on_400():
- """400 means 'route exists, body invalid' — native path should be used."""
- respx.post(_MESSAGES_URL).mock(return_value=httpx.Response(400))
- assert probe_anthropic_messages_support_sync(base_url=_BASE_URL, api_key="k")
-
-
-def test_sync_probe_true_on_422():
- respx.post(_MESSAGES_URL).mock(return_value=httpx.Response(422))
- assert probe_anthropic_messages_support_sync(base_url=_BASE_URL, api_key="k")
-
-
-def test_sync_probe_true_on_200():
- respx.post(_MESSAGES_URL).mock(return_value=httpx.Response(200, json={}))
- assert probe_anthropic_messages_support_sync(base_url=_BASE_URL, api_key="k")
-
-
-def test_sync_probe_false_on_404():
- """404 means the route doesn't exist — fall back to translation."""
- respx.post(_MESSAGES_URL).mock(return_value=httpx.Response(404))
- assert not probe_anthropic_messages_support_sync(base_url=_BASE_URL, api_key="k")
-
-
-def test_sync_probe_false_on_401():
- """401 = bad credentials — warn and fall back."""
- respx.post(_MESSAGES_URL).mock(return_value=httpx.Response(401))
- assert not probe_anthropic_messages_support_sync(base_url=_BASE_URL, api_key="k")
-
-
-def test_sync_probe_false_on_500():
- """5xx = backend error — safer to fall back than commit to a broken native path."""
- respx.post(_MESSAGES_URL).mock(return_value=httpx.Response(500))
- assert not probe_anthropic_messages_support_sync(base_url=_BASE_URL, api_key="k")
-
-
-def test_sync_probe_false_on_timeout():
- respx.post(_MESSAGES_URL).mock(side_effect=httpx.TimeoutException("timeout"))
- assert not probe_anthropic_messages_support_sync(base_url=_BASE_URL, api_key="k")
-
-
-def test_sync_probe_false_on_network_error():
- respx.post(_MESSAGES_URL).mock(side_effect=httpx.ConnectError("refused"))
- assert not probe_anthropic_messages_support_sync(base_url=_BASE_URL, api_key="k")
-
-
-# ---------------------------------------------------------------------------
-# Event-loop safety — structural assertions
-# ---------------------------------------------------------------------------
-
-
-def test_select_and_build_is_not_async():
- """_build_claude_switchyard must be a plain def, not async def.
-
- An async def (or a wrapper over asyncio.run()) creates and closes event
- loop L1. Async clients built afterward may bind httpx connection pools to
- L1; when uvicorn's L2 awaits them the coroutine never resolves.
- """
- assert not asyncio.iscoroutinefunction(_build_claude_switchyard), (
- "_build_claude_switchyard must be a plain def. "
- "Using async def or asyncio.run() here creates a loop that closes "
- "before uvicorn starts. Connection-pool primitives bound to the dead "
- "loop cause indefinite hangs on first use in uvicorn's loop."
- )
-
-
-def test_no_asyncio_run_during_switchyard_construction():
- """asyncio.run() must not be called during switchyard construction.
-
- This is the direct structural assertion for the regression: if
- asyncio.run() is called, a loop is created and closed before uvicorn
- starts, leading to the cross-loop hang described in the module docstring.
- """
- run_calls: list = []
- original_run = asyncio.run
-
- def spy_run(coro, **kwargs):
- run_calls.append(coro)
- return original_run(coro, **kwargs)
-
- with patch("asyncio.run", spy_run):
- _build_claude_switchyard(
- model="test-model",
- api_key="test-key",
- base_url=_BASE_URL,
- timeout=1.0,
- stats=StatsAccumulator(),
- )
-
- assert not run_calls, (
- f"asyncio.run() was called {len(run_calls)} time(s) inside "
- "_build_claude_switchyard. This creates and closes event loop L1 "
- "before uvicorn's L2 starts. Async clients built here may bind their "
- "connection-pool primitives to L1; awaiting them in L2 hangs forever."
- )
-
-
-# ---------------------------------------------------------------------------
-# Integration test — proxy built correctly handles requests without hanging
-# ---------------------------------------------------------------------------
-
-
-def test_proxy_request_completes_not_hanging():
- """A proxy built without prior asyncio.run() must return a response, not hang.
-
- Regression test for event-loop contention. We:
- 1. Build the switchyard via the fixed code path (no asyncio.run).
- 2. Start uvicorn in a background thread.
- 3. Point the real Rust backend at a loopback OpenAI-compatible upstream.
- 4. POST to /v1/messages with a 5-second client timeout.
- 5. Assert a response arrives. A hang would surface as httpx.ReadTimeout.
-
- If the event-loop contention bug were present (clients built inside
- asyncio.run()), step 4 would time out because the async call in uvicorn's
- loop would await primitives bound to the now-closed startup loop.
- """
- port = _find_free_port()
- stats = StatsAccumulator()
-
- with _OpenAICompatStub() as upstream:
- switchyard = _build_claude_switchyard(
- model="test-model",
- api_key="test-key",
- base_url=upstream.base_url,
- timeout=2.0,
- stats=stats,
- )
- server, thread = _spawn_proxy_thread(switchyard, port)
- try:
- assert _wait_ready(port, timeout_s=5.0), "proxy did not start within 5 s"
- with httpx.Client(timeout=5.0) as client:
- resp = client.post(
- f"http://127.0.0.1:{port}/v1/messages",
- json={
- "model": "test-model",
- "max_tokens": 10,
- "messages": [{"role": "user", "content": "ping"}],
- },
- )
-
- assert resp.status_code == 200, resp.text
- assert upstream.requests, "proxy did not call the loopback upstream"
- finally:
- server.should_exit = True
- thread.join(timeout=3.0)
-
-
-# ---------------------------------------------------------------------------
-# Regression scenario — old pattern with asyncio.run() before construction
-# ---------------------------------------------------------------------------
-
-
-def test_proxy_built_after_closed_loop_documents_hang_risk():
- """Document the failure mode: build after asyncio.run() → hang risk.
-
- Reproduces the old code pattern:
- asyncio.run(noop) → L1 created then closed
- _build_claude_switchyard() → async clients constructed
- uvicorn in background thread → uses L2
- POST /v1/messages → client awaits in L2, but pools may reference L1
-
- Because an actual hang would block the test suite forever, we use a
- 2-second deadline for the request thread and observe the outcome:
-
- - If the request times out (does NOT complete): the cross-loop hang is
- reproducible on this platform. We mark the test as ``xfail`` with a
- meaningful message so CI reports it rather than blocking.
- - If it completes: the Python/httpx/anyio stack on this platform handles
- the cross-loop case gracefully — the test passes (xpass).
-
- Either way the test never actually hangs the suite.
- """
- # Step 1 — close loop L1, exactly as the old launch_claude did.
- async def _noop() -> None:
- pass
-
- asyncio.run(_noop())
-
- # Step 2 — build async clients (now with no running loop, but L1 is gone).
- port = _find_free_port()
- stats = StatsAccumulator()
- with _OpenAICompatStub() as upstream:
- switchyard = _build_claude_switchyard(
- model="test-model",
- api_key="test-key",
- base_url=upstream.base_url,
- timeout=1.0,
- stats=stats,
- )
- server, thread = _spawn_proxy_thread(switchyard, port)
- completed = threading.Event()
- status_holder: list[int] = []
-
- def _make_request() -> None:
- try:
- with httpx.Client(timeout=2.0) as c:
- r = c.post(
- f"http://127.0.0.1:{port}/v1/messages",
- json={
- "model": "test-model",
- "max_tokens": 10,
- "messages": [{"role": "user", "content": "ping"}],
- },
- )
- status_holder.append(r.status_code)
- except Exception:
- pass
- finally:
- completed.set()
-
- try:
- assert _wait_ready(port, timeout_s=5.0), "proxy did not start"
- t = threading.Thread(target=_make_request, daemon=True)
- t.start()
- finished_in_time = completed.wait(timeout=2.5)
-
- if not finished_in_time:
- # Cross-loop hang reproduced on this platform — mark xfail so CI
- # reports it as a known failure rather than a blocking hang.
- pytest.xfail(
- "Request did not complete within 2.5 s after asyncio.run() was "
- "called before client construction. This confirms the cross-loop "
- "hang bug is reproducible on this Python/httpx/anyio version. "
- "The fix (sync probe, no asyncio.run before build) prevents this."
- )
- # If it finished — the platform doesn't exhibit the bug. Pass.
- assert status_holder, "request thread exited without recording a status"
- finally:
- server.should_exit = True
- thread.join(timeout=3.0)
diff --git a/tests/test_rl_logging.py b/tests/test_rl_logging.py
index 0788413e6..4ab814ae8 100644
--- a/tests/test_rl_logging.py
+++ b/tests/test_rl_logging.py
@@ -16,7 +16,6 @@ from openai.types.chat.chat_completion_chunk import Choice as ChunkChoice
from openai.types.chat.chat_completion_chunk import ChoiceDelta
from openai.types.completion_usage import CompletionUsage
-from switchyard.cli.launchers.launch_intake_config import build_launch_capture_processors
from switchyard.cli.switchyard_cli import _build_parser
from switchyard.lib.chat_response import ResponseStream
from switchyard.lib.processors.rl_logging_request_processor import (
@@ -236,15 +235,6 @@ async def test_write_failure_does_not_break_the_response(
assert list(tmp_path.glob("*.json")) == []
-def test_build_launch_capture_processors_toggles_on_rl_log_dir(tmp_path: Path) -> None:
- none_req, none_resp = build_launch_capture_processors(None, None)
- assert none_req == [] and none_resp == []
-
- req, resp = build_launch_capture_processors(None, tmp_path)
- assert [type(p).__name__ for p in req] == ["RlLoggingRequestProcessor"]
- assert [type(p).__name__ for p in resp] == ["RlLoggingResponseProcessor"]
-
-
def test_resolve_rl_log_dir() -> None:
off = argparse.Namespace(enable_rl_logging=False, rl_log_dir="./rl_data")
assert resolve_rl_log_dir(off) is None
@@ -296,20 +286,17 @@ async def test_streaming_logs_after_drain(tmp_path: Path) -> None:
}
-def test_global_flag_parses_before_subcommand() -> None:
+def test_rl_flags_are_scoped_to_serve() -> None:
parser = _build_parser()
args = parser.parse_args(
- ["--enable-rl-logging", "--rl-log-dir", "/tmp/x", "launch", "claude"],
- )
- assert args.enable_rl_logging is True
- assert args.rl_log_dir == "/tmp/x"
- assert resolve_rl_log_dir(args) == Path("/tmp/x")
-
-
-def test_global_flag_parses_before_serve() -> None:
- parser = _build_parser()
- args = parser.parse_args(
- ["--enable-rl-logging", "--rl-log-dir", "/tmp/x", "serve"],
+ [
+ "serve",
+ "--routing-profiles",
+ "profiles.yaml",
+ "--enable-rl-logging",
+ "--rl-log-dir",
+ "/tmp/x",
+ ],
)
assert args.command == "serve"
assert args.enable_rl_logging is True
@@ -343,6 +330,7 @@ def test_serve_attaches_rl_logging_processors(monkeypatch, tmp_path: Path) -> No
enable_rl_logging=True, rl_log_dir=str(tmp_path),
intake_enabled=False, intake_base_url=None, intake_workspace=None,
intake_api_key=None, intake_target_url=None,
+ routing_log_file=None,
)
cli._cmd_serve(args)
diff --git a/tests/test_route_bundle.py b/tests/test_route_bundle.py
index 726ccc3eb..d2fcc00b7 100644
--- a/tests/test_route_bundle.py
+++ b/tests/test_route_bundle.py
@@ -327,9 +327,9 @@ def test_serve_subcommand_hands_table_to_server(
monkeypatch.setattr(cli, "build_and_serve", _fake_serve)
args = cli._build_parser().parse_args([
+ "serve",
"--routing-profiles",
str(yaml_path),
- "serve",
"--port",
"4555",
])
@@ -354,7 +354,7 @@ def test_main_reports_route_bundle_config_error_without_traceback(
" bogus_key: 1\n"
)
monkeypatch.setattr(
- sys, "argv", ["switchyard", "--routing-profiles", str(yaml_path), "serve"]
+ sys, "argv", ["switchyard", "serve", "--routing-profiles", str(yaml_path)]
)
with pytest.raises(SystemExit) as excinfo:
@@ -372,7 +372,7 @@ def test_main_reports_missing_route_bundle_file_without_traceback(
) -> None:
missing_path = tmp_path / "does-not-exist.yaml"
monkeypatch.setattr(
- sys, "argv", ["switchyard", "--routing-profiles", str(missing_path), "serve"]
+ sys, "argv", ["switchyard", "serve", "--routing-profiles", str(missing_path)]
)
with pytest.raises(SystemExit) as excinfo:
@@ -395,7 +395,7 @@ def test_main_reports_bad_route_bundle_yaml_without_traceback(
" target: x\n"
)
monkeypatch.setattr(
- sys, "argv", ["switchyard", "--routing-profiles", str(yaml_path), "serve"]
+ sys, "argv", ["switchyard", "serve", "--routing-profiles", str(yaml_path)]
)
with pytest.raises(SystemExit) as excinfo:
@@ -414,7 +414,7 @@ def test_main_reports_non_utf8_route_bundle_without_traceback(
yaml_path = tmp_path / "non_utf8.yaml"
yaml_path.write_bytes(b"\xff")
monkeypatch.setattr(
- sys, "argv", ["switchyard", "--routing-profiles", str(yaml_path), "serve"]
+ sys, "argv", ["switchyard", "serve", "--routing-profiles", str(yaml_path)]
)
with pytest.raises(SystemExit) as excinfo:
@@ -435,7 +435,7 @@ def test_main_accepts_routing_profiles_flag(
yaml_path.write_text("routes:\n direct:\n type: model\n target: some/model\n")
monkeypatch.setattr(
- sys, "argv", ["switchyard", "--routing-profiles", str(yaml_path), "serve"]
+ sys, "argv", ["switchyard", "serve", "--routing-profiles", str(yaml_path)]
)
def _fake_serve(
@@ -453,34 +453,6 @@ def test_main_accepts_routing_profiles_flag(
assert capsys.readouterr().err == ""
-def test_serve_accepts_saved_route_bundle(
- monkeypatch: pytest.MonkeyPatch,
- tmp_path,
- capsys: pytest.CaptureFixture[str],
-) -> None:
- from switchyard.cli.config.user_config import UserConfig, save_user_config
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- save_user_config(UserConfig(routing_profiles={"routes": {
- "direct": {"type": "model", "target": "some/model"},
- }}))
-
- def _fake_serve(
- args: argparse.Namespace,
- switchyard: object,
- inbound_default: str,
- **_kwargs: object,
- ) -> None:
- return
-
- monkeypatch.setattr(cli, "build_and_serve", _fake_serve)
- args = cli._build_parser().parse_args(["serve", "--port", "4000"])
-
- cli._cmd_serve(args)
-
- assert capsys.readouterr().err == ""
-
-
def test_serve_subcommand_enables_intake_from_cli_args(
monkeypatch: pytest.MonkeyPatch,
tmp_path,
@@ -511,9 +483,9 @@ def test_serve_subcommand_enables_intake_from_cli_args(
monkeypatch.setattr(cli, "build_and_serve", _fake_serve)
args = cli._build_parser().parse_args([
+ "serve",
"--routing-profiles",
str(yaml_path),
- "serve",
"--intake-enabled",
"--intake-base-url",
"https://intake.example.test",
diff --git a/tests/test_routing_banner.py b/tests/test_routing_banner.py
deleted file mode 100644
index 0a6d96d35..000000000
--- a/tests/test_routing_banner.py
+++ /dev/null
@@ -1,252 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Tests for the routing-policy banner passed to print_ready_banner at launch.
-
-Verifies the strategy summary helpers directly and that each launcher
-(claude, codex, openclaw) calls the right helper for passthrough,
-routing-profiles, and deterministic modes.
-"""
-
-import textwrap
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-from switchyard.cli.launchers.claude_code_launcher import launch_claude
-from switchyard.cli.launchers.codex_cli_launcher import launch_codex
-from switchyard.cli.launchers.launcher_runtime import (
- deterministic_strategy_summary,
- passthrough_strategy_summary,
- routing_profiles_strategy_summary,
-)
-from switchyard.cli.launchers.openclaw_launcher import launch_openclaw
-
-_STAGE_ROUTER_YAML = textwrap.dedent("""\
- routes:
- my_route:
- type: stage_router
- confidence_threshold: 0.7
- strong:
- model: strong-model/v1
- weak:
- model: weak-model/v1
- classifier:
- model: clf-model/v1
-""")
-
-_MODEL_ROUTE_YAML = textwrap.dedent("""\
- routes:
- my_route:
- type: model
- target: some/model
-""")
-
-
-class TestStrategyHelpers:
- def test_passthrough_summary(self):
- """passthrough_strategy_summary returns 'passthrough → <model>'."""
- assert passthrough_strategy_summary("my/model") == "passthrough → my/model"
-
- def test_routing_profiles_stage_router(self, tmp_path):
- """routing_profiles_strategy_summary describes the default stage_router route."""
- p = tmp_path / "profiles.yaml"
- p.write_text(_STAGE_ROUTER_YAML)
- result = routing_profiles_strategy_summary(str(p), "my_route")
- assert result == "stage_router: strong=strong-model/v1, weak=weak-model/v1, llm-classifier=clf-model/v1, confidence_threshold=0.7"
-
- def test_routing_profiles_model_type(self, tmp_path):
- """routing_profiles_strategy_summary renders a model-type route as passthrough."""
- p = tmp_path / "profiles.yaml"
- p.write_text(_MODEL_ROUTE_YAML)
- result = routing_profiles_strategy_summary(str(p), "my_route")
- assert result == "passthrough → some/model"
-
- def test_routing_profiles_fallback_on_missing_file(self):
- """Falls back to default_model when the profiles file cannot be read."""
- result = routing_profiles_strategy_summary("/nonexistent/path.yaml", "fallback-model")
- assert result == "routing-profiles: fallback-model"
-
- def test_deterministic_summary(self):
- """deterministic_strategy_summary formats all config fields."""
- config = MagicMock()
- config.classifier.model = "clf-model"
- config.strong.model = "strong-model"
- config.weak.model = "weak-model"
- config.profile_name = "default"
- result = deterministic_strategy_summary(config)
- assert result == "llm-classifier: classifier=clf-model, strong=strong-model, weak=weak-model, profile=default"
-
-
-def _captured_strategy(captured: dict) -> str | None:
- return captured.get("strategy_summary")
-
-
-def _patch_codex_runner(captured: dict):
- """Patch _run_codex_with_switchyard to capture kwargs and return 0."""
- def _fake_run(*args, **kwargs):
- captured.update(kwargs)
- return 0
- return patch(
- "switchyard.cli.launchers.codex_cli_launcher._run_codex_with_switchyard",
- side_effect=_fake_run,
- )
-
-
-def _patch_claude_runner(captured: dict):
- def _fake_run(*args, **kwargs):
- captured.update(kwargs)
- return 0
- return patch(
- "switchyard.cli.launchers.claude_code_launcher._run_claude_with_switchyard",
- side_effect=_fake_run,
- )
-
-
-def _patch_openclaw_runner(captured: dict):
- """Patch _run_openclaw_with_switchyard to capture kwargs and return 0."""
- def _fake_run(*args, **kwargs):
- captured.update(kwargs)
- return 0
- return patch(
- "switchyard.cli.launchers.openclaw_launcher._run_openclaw_with_switchyard",
- side_effect=_fake_run,
- )
-
-
[email protected](autouse=True)
-def _patch_build_deps(monkeypatch):
- """Stub out chain-building so tests don't need real API keys or Rust init."""
- monkeypatch.setattr(
- "switchyard.cli.launchers.codex_cli_launcher._build_switchyard",
- lambda *a, **kw: MagicMock(),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.claude_code_launcher._build_claude_switchyard",
- lambda *a, **kw: MagicMock(),
- )
- monkeypatch.setattr(
- "switchyard.cli.launchers.openclaw_launcher._build_switchyard",
- lambda *a, **kw: MagicMock(),
- )
- monkeypatch.setattr(
- "switchyard.lib.route_table_builders.build_single_model_table",
- lambda *a, **kw: MagicMock(),
- )
-
-
-class TestCodexRoutingBanner:
- def test_passthrough_banner(self):
- """launch_codex produces passthrough → <model> for single-model launch."""
- captured: dict = {}
- with _patch_codex_runner(captured):
- launch_codex(
- model="nvidia/moonshotai/kimi-k2.6",
- base_url="https://example.com/v1",
- api_key="key",
- port=4000,
- timeout=None,
- codex_args=[],
- )
- assert _captured_strategy(captured) == "passthrough → nvidia/moonshotai/kimi-k2.6"
-
- def test_routing_profiles_banner(self, tmp_path):
- """launch_codex describes the default route type for routing-profiles launch."""
- profiles_path = tmp_path / "profiles.yaml"
- profiles_path.write_text(_STAGE_ROUTER_YAML)
- captured: dict = {}
- with (
- _patch_codex_runner(captured),
- patch(
- "switchyard.cli.launchers.codex_cli_launcher.load_route_bundle_table",
- return_value=MagicMock(items=lambda: [], model_listing_warnings=lambda: []),
- ),
- ):
- launch_codex(
- model="my_route",
- base_url="https://example.com/v1",
- api_key="key",
- port=4000,
- timeout=None,
- codex_args=[],
- routing_profiles=str(profiles_path),
- )
- assert _captured_strategy(captured) == "stage_router: strong=strong-model/v1, weak=weak-model/v1, llm-classifier=clf-model/v1, confidence_threshold=0.7"
-
-
-class TestOpenclawRoutingBanner:
- def test_passthrough_banner(self):
- """launch_openclaw produces passthrough → <model> for single-model launch."""
- captured: dict = {}
- with _patch_openclaw_runner(captured):
- launch_openclaw(
- model="nvidia/moonshotai/kimi-k2.6",
- base_url="https://example.com/v1",
- api_key="key",
- port=4000,
- timeout=None,
- openclaw_args=[],
- )
- assert _captured_strategy(captured) == "passthrough → nvidia/moonshotai/kimi-k2.6"
-
- def test_routing_profiles_banner(self, tmp_path):
- """launch_openclaw describes the default route type for routing-profiles launch."""
- profiles_path = tmp_path / "profiles.yaml"
- profiles_path.write_text(_STAGE_ROUTER_YAML)
- captured: dict = {}
- with (
- _patch_openclaw_runner(captured),
- patch(
- "switchyard.cli.launchers.openclaw_launcher.load_route_bundle_table",
- return_value=MagicMock(items=lambda: [], model_listing_warnings=lambda: []),
- ),
- ):
- launch_openclaw(
- model="my_route",
- base_url="https://example.com/v1",
- api_key="key",
- port=4000,
- timeout=None,
- openclaw_args=[],
- routing_profiles=str(profiles_path),
- )
- assert _captured_strategy(captured) == "stage_router: strong=strong-model/v1, weak=weak-model/v1, llm-classifier=clf-model/v1, confidence_threshold=0.7"
-
-
-class TestClaudeRoutingBanner:
- def test_passthrough_banner(self):
- """launch_claude produces passthrough → <model> for single-model launch."""
- captured: dict = {}
- with _patch_claude_runner(captured):
- launch_claude(
- model="nvidia/moonshotai/kimi-k2.6",
- base_url="https://example.com/v1",
- api_key="key",
- port=4000,
- timeout=None,
- claude_args=[],
- )
- assert _captured_strategy(captured) == "passthrough → nvidia/moonshotai/kimi-k2.6"
-
- def test_routing_profiles_banner(self, tmp_path):
- """launch_claude describes the default route type for routing-profiles launch."""
- profiles_path = tmp_path / "profiles.yaml"
- profiles_path.write_text(_STAGE_ROUTER_YAML)
- captured: dict = {}
- with (
- _patch_claude_runner(captured),
- patch(
- "switchyard.cli.launchers.claude_code_launcher.load_route_bundle_table",
- return_value=MagicMock(items=lambda: [], model_listing_warnings=lambda: []),
- ),
- ):
- launch_claude(
- model="my_route",
- base_url="https://example.com/v1",
- api_key="key",
- port=4000,
- timeout=None,
- claude_args=[],
- routing_profiles=str(profiles_path),
- )
- assert _captured_strategy(captured) == "stage_router: strong=strong-model/v1, weak=weak-model/v1, llm-classifier=clf-model/v1, confidence_threshold=0.7"
diff --git a/tests/test_routing_log_response_processor.py b/tests/test_routing_log_response_processor.py
index 736ea5520..75fa1a62a 100644
--- a/tests/test_routing_log_response_processor.py
+++ b/tests/test_routing_log_response_processor.py
@@ -286,5 +286,13 @@ def test_session_stats_endpoint_returns_snapshot_and_404(tmp_path: Path) -> None
def test_serve_parser_accepts_routing_log_file() -> None:
parser = _build_parser()
- args = parser.parse_args(["serve", "--routing-log-file", "tmp/routing.jsonl"])
+ args = parser.parse_args(
+ [
+ "serve",
+ "--routing-profiles",
+ "routes.yaml",
+ "--routing-log-file",
+ "tmp/routing.jsonl",
+ ]
+ )
assert args.routing_log_file == "tmp/routing.jsonl"
diff --git a/tests/test_status.py b/tests/test_status.py
deleted file mode 100644
index a65a4b4dd..000000000
--- a/tests/test_status.py
+++ /dev/null
@@ -1,26 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-from switchyard.cli.status import StatusRequest, render_status
-
-
-def test_status_base_url_source_matches_selected_env_provider(monkeypatch, tmp_path) -> None:
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- for env_var in (
- "OPENROUTER_API_KEY",
- "OPENROUTER_BASE_URL",
- "NVIDIA_API_KEY",
- "NVIDIA_BASE_URL",
- "OPENAI_API_KEY",
- "OPENAI_BASE_URL",
- "ANTHROPIC_API_KEY",
- ):
- monkeypatch.delenv(env_var, raising=False)
- monkeypatch.setenv("NVIDIA_API_KEY", "nvidia-key")
- monkeypatch.setenv("OPENROUTER_BASE_URL", "https://openrouter.test/v1")
-
- status = render_status(StatusRequest())
-
- assert "provider: nvidia" in status
- assert "base URL: https://inference-api.nvidia.com/v1" in status
- assert "base URL source: built-in default" in status
diff --git a/tests/test_tui_model_selector.py b/tests/test_tui_model_selector.py
deleted file mode 100644
index 890844496..000000000
--- a/tests/test_tui_model_selector.py
+++ /dev/null
@@ -1,191 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-from __future__ import annotations
-
-from switchyard.cli.tui.launch_config_wizard import LaunchConfigWizard
-from switchyard.cli.tui.model_selector import (
- ModelSelector,
- build_model_candidates,
-)
-from switchyard.cli.tui.terminal_capabilities import TerminalCapabilities
-from switchyard.cli.tui.tui_session import TuiSession
-
-
-def _plain_session(input_value: str) -> TuiSession:
- output: list[str] = []
- return TuiSession(
- capabilities=TerminalCapabilities(
- interactive=False,
- color=False,
- tui=False,
- reason="test",
- ),
- input_fn=lambda _prompt: input_value,
- secret_fn=lambda _prompt: input_value,
- output_fn=output.append,
- )
-
-
-def test_build_model_candidates_puts_default_and_recommendations_first():
- candidates = build_model_candidates(
- preferred_model_ids=[
- "aws/anthropic/bedrock-claude-opus-4-7",
- "azure/anthropic/claude-sonnet-4-6",
- ],
- all_model_ids=[
- "nvidia/moonshotai/kimi-k2.5",
- "aws/anthropic/bedrock-claude-opus-4-7",
- ],
- default="aws/anthropic/bedrock-claude-opus-4-7",
- )
-
- assert [candidate.model_id for candidate in candidates] == [
- "aws/anthropic/bedrock-claude-opus-4-7",
- "azure/anthropic/claude-sonnet-4-6",
- "nvidia/moonshotai/kimi-k2.5",
- ]
- assert [candidate.group for candidate in candidates] == [
- "default",
- "recommended",
- "available",
- ]
-
-
-def test_selector_filter_matches_model_id_and_group():
- selector = ModelSelector(
- title="Claude Code model",
- candidates=build_model_candidates(
- preferred_model_ids=["aws/anthropic/bedrock-claude-opus-4-7"],
- all_model_ids=["nvidia/moonshotai/kimi-k2.5"],
- default=None,
- ),
- )
-
- assert [
- candidate.model_id for candidate in selector.filter_candidates("opus")
- ] == ["aws/anthropic/bedrock-claude-opus-4-7"]
- assert [
- candidate.model_id for candidate in selector.filter_candidates("available")
- ] == ["nvidia/moonshotai/kimi-k2.5"]
-
-
-def test_selector_moves_default_to_front_when_candidates_are_not_ordered():
- selector = ModelSelector(
- title="Claude reasoning effort",
- candidates=build_model_candidates(
- preferred_model_ids=["none", "disabled", "low", "medium", "high"],
- all_model_ids=[],
- default=None,
- ),
- default="high",
- allow_manual=False,
- )
-
- candidates = selector.filter_candidates("")
- assert [candidate.model_id for candidate in candidates] == [
- "high",
- "none",
- "disabled",
- "low",
- "medium",
- ]
- assert candidates[0].group == "default"
-
-
-def test_plain_selector_accepts_blank_default():
- selector = ModelSelector(
- title="Codex model",
- candidates=build_model_candidates(
- preferred_model_ids=["openai/openai/openai/gpt-5.5"],
- all_model_ids=[],
- default="openai/openai/openai/gpt-5.5",
- ),
- default="openai/openai/openai/gpt-5.5",
- )
-
- assert selector.select(_plain_session("")) == "openai/openai/openai/gpt-5.5"
-
-
-def test_plain_selector_accepts_manual_model_id():
- selector = ModelSelector(
- title="Codex model",
- candidates=[],
- default=None,
- allow_manual=True,
- )
-
- assert selector.select(_plain_session("custom/model")) == "custom/model"
-
-
-def test_plain_selector_uses_custom_manual_entry_label():
- captured: dict[str, str] = {}
- session = TuiSession(
- capabilities=TerminalCapabilities(
- interactive=False,
- color=False,
- tui=False,
- reason="test",
- ),
- input_fn=lambda prompt: (captured.setdefault("prompt", prompt), "2")[1],
- secret_fn=lambda _prompt: "",
- output_fn=lambda _line: None,
- )
- selector = ModelSelector(
- title="Routing mode",
- candidates=build_model_candidates(
- preferred_model_ids=["No routing", "Random between two models"],
- all_model_ids=[],
- default="No routing",
- ),
- default="No routing",
- allow_manual=False,
- manual_entry_label="option",
- )
-
- assert selector.select(session) == "Random between two models"
- assert "(number or option)" in captured["prompt"]
-
-
-def test_launch_wizard_uses_provider_neutral_default_api_key_label():
- captured: dict[str, str] = {}
- session = TuiSession(
- capabilities=TerminalCapabilities(
- interactive=False,
- color=False,
- tui=False,
- reason="test",
- ),
- input_fn=lambda _prompt: "",
- secret_fn=lambda prompt: (captured.setdefault("prompt", prompt), "sk-test")[1],
- output_fn=lambda _line: None,
- )
-
- assert LaunchConfigWizard(session).prompt_default_api_key(None) == "sk-test"
- assert "Default API key" in captured["prompt"]
- assert "NVIDIA" not in captured["prompt"]
-
-
-def test_launch_wizard_shows_api_key_default_source_without_secret():
- captured: dict[str, str] = {}
- session = TuiSession(
- capabilities=TerminalCapabilities(
- interactive=False,
- color=False,
- tui=False,
- reason="test",
- ),
- input_fn=lambda _prompt: "",
- secret_fn=lambda prompt: (captured.setdefault("prompt", prompt), "")[1],
- output_fn=lambda _line: None,
- )
-
- assert (
- LaunchConfigWizard(session).prompt_default_api_key(
- "sk-env",
- default_source="$NVIDIA_API_KEY",
- )
- == "sk-env"
- )
- assert "Default API key (default: $NVIDIA_API_KEY)" in captured["prompt"]
- assert "sk-env" not in captured["prompt"]
diff --git a/tests/test_user_config.py b/tests/test_user_config.py
deleted file mode 100644
index 0357312d1..000000000
--- a/tests/test_user_config.py
+++ /dev/null
@@ -1,799 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-import json
-import stat
-import sys
-
-import pytest
-
-from switchyard.cli.config.user_config import (
- DEFAULT_OPENROUTER_BASE_URL,
- PRIMARY_TIER,
- LaunchConfig,
- LaunchCredentials,
- LaunchRouteConfig,
- LaunchTierEndpointConfig,
- ProviderConfig,
- SkillDistillationConfig,
- UserConfig,
- UserConfigError,
- UserCredentials,
- build_redacted_snapshot,
- load_user_config,
- load_user_credentials,
- resolve_provider_connectivity,
- save_user_config,
- save_user_credentials,
-)
-from switchyard.cli.output import format_config_snapshot
-from switchyard.cli.status import StatusRequest, render_status
-
-
[email protected](autouse=True)
-def _clear_provider_env_vars(monkeypatch: pytest.MonkeyPatch) -> None:
- """Prevent the developer's shell credentials from influencing any test in this file."""
- monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
- monkeypatch.delenv("OPENROUTER_BASE_URL", raising=False)
- monkeypatch.delenv("NVIDIA_API_KEY", raising=False)
- monkeypatch.delenv("NVIDIA_BASE_URL", raising=False)
- monkeypatch.delenv("OPENAI_API_KEY", raising=False)
- monkeypatch.delenv("OPENAI_BASE_URL", raising=False)
-
-
-def test_user_config_round_trips_and_credentials_are_private(tmp_path):
- bundle = {
- "routes": {
- "example/model": {
- "type": "model",
- "target": {
- "model": "example/model",
- "api_key": "sk-test",
- "base_url": "https://example.invalid/v1",
- },
- },
- },
- }
- save_user_config(
- UserConfig(
- providers={
- "nvidia": ProviderConfig(base_url="https://example.test/v1"),
- },
- launch={
- "claude": LaunchConfig(
- model="aws/anthropic/bedrock-claude-opus-4-7",
- route=LaunchRouteConfig(
- type="single",
- model="aws/anthropic/bedrock-claude-opus-4-7",
- endpoints={
- PRIMARY_TIER: LaunchTierEndpointConfig(
- base_url="https://strong.example/v1",
- ),
- },
- ),
- ),
- "codex": LaunchConfig(model="openai/openai/openai/gpt-5.5"),
- },
- routing_profiles=bundle,
- ),
- config_dir=tmp_path,
- )
- save_user_credentials(
- UserCredentials(
- api_keys={"nvidia": "nvapi-secret"},
- launch={
- "claude": LaunchCredentials(
- api_keys={PRIMARY_TIER: "strong-secret"},
- ),
- },
- ),
- config_dir=tmp_path,
- )
-
- config = load_user_config(tmp_path)
- credentials = load_user_credentials(tmp_path)
-
- assert config.provider("nvidia").base_url == "https://example.test/v1"
- assert config.launch_target("claude").model == "aws/anthropic/bedrock-claude-opus-4-7"
- route = config.launch_target("claude").effective_route()
- assert route.type == "single"
- assert route.endpoint(PRIMARY_TIER).base_url == "https://strong.example/v1"
- assert config.launch_target("codex").model == "openai/openai/openai/gpt-5.5"
- assert config.routing_profiles == bundle
- assert credentials.api_key("nvidia") == "nvapi-secret"
- assert credentials.launch_target("claude").api_key(PRIMARY_TIER) == "strong-secret"
-
- mode = stat.S_IMODE((tmp_path / "credentials.json").stat().st_mode)
- assert mode == 0o600
-
-
-def test_top_level_routing_profiles_round_trips(tmp_path):
- bundle = {"routes": {"example/model": {"type": "model"}}}
- save_user_config(UserConfig(routing_profiles=bundle), config_dir=tmp_path)
- loaded = load_user_config(tmp_path)
- assert loaded.routing_profiles == bundle
-
-
-def test_top_level_routing_profiles_clears_when_none(tmp_path):
- save_user_config(
- UserConfig(routing_profiles={"routes": {"a": {"type": "model"}}}),
- config_dir=tmp_path,
- )
- save_user_config(UserConfig(routing_profiles=None), config_dir=tmp_path)
- assert load_user_config(tmp_path).routing_profiles is None
-
-
-def test_default_skill_distillation_config_is_not_persisted(tmp_path):
- save_user_config(UserConfig(), config_dir=tmp_path)
-
- raw = json.loads((tmp_path / "config.json").read_text())
- assert "skill_distillation" not in raw
- assert load_user_config(tmp_path).skill_distillation == SkillDistillationConfig()
-
-
-def test_skill_distillation_config_round_trips_and_surfaces(
- monkeypatch,
- tmp_path,
-):
- skill_config = SkillDistillationConfig(
- namespace="tooluniverse-trialqa",
- )
- save_user_config(
- UserConfig(skill_distillation=skill_config),
- config_dir=tmp_path,
- )
-
- raw = json.loads((tmp_path / "config.json").read_text())
- assert raw["skill_distillation"] == {
- "namespace": "tooluniverse-trialqa",
- }
- assert load_user_config(tmp_path).skill_distillation == skill_config
-
- snapshot = build_redacted_snapshot(tmp_path)
- assert snapshot["skill_distillation"] == raw["skill_distillation"]
- rendered = format_config_snapshot(snapshot)
- assert "Skill distillation" in rendered
- assert "namespace: tooluniverse-trialqa" in rendered
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- status = render_status(StatusRequest())
- assert "skill distillation: configured; namespace: tooluniverse-trialqa" in status
- assert "session learning: namespace saved" in status
-
-
- ("body", "message"),
- [
- ({}, "namespace is required"),
- ({"namespace": "ok", "enabled": False}, "supports only namespace"),
- ({"namespace": "ok", "save_sessions": False}, "supports only namespace"),
- ({"namespace": 7}, "must be a non-empty string"),
- ({"namespace": "bad/name"}, "letters, numbers"),
- ({"namespace": " bad"}, "leading or trailing whitespace"),
- ({"namespace": "ok", "session_store": "remote"}, "supports only namespace"),
- ({"namespace": "ok", "trigger": "instant"}, "supports only namespace"),
- ({"namespace": "ok", "mount": "global"}, "supports only namespace"),
- ({"namespace": "ok", "lookback_sessions": 0}, "supports only namespace"),
- ],
-)
-def test_skill_distillation_config_validates(
- tmp_path,
- body,
- message,
-):
- (tmp_path / "config.json").write_text(json.dumps({
- "skill_distillation": body,
- }))
-
- with pytest.raises(UserConfigError, match=message):
- load_user_config(tmp_path)
-
-
-def test_configure_skill_only_update_does_not_require_api_key(
- monkeypatch,
- tmp_path,
- capsys,
-):
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_configure
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.command_utils.is_interactive_terminal",
- lambda: False,
- )
- monkeypatch.setattr(
- "switchyard.cli.configure_command.is_interactive_terminal",
- lambda: False,
- )
-
- parser = _build_parser()
- args = parser.parse_args([
- "configure",
- "--skill-distillation", "tooluniverse-trialqa",
- ])
-
- _cmd_configure(args)
-
- config = load_user_config(tmp_path)
- assert config.skill_distillation.configured is True
- assert config.skill_distillation.namespace == "tooluniverse-trialqa"
- assert not (tmp_path / "credentials.json").exists()
- assert "Saved Switchyard config" in capsys.readouterr().out
-
-
-def test_configure_disable_skill_distillation_clears_config(
- monkeypatch,
- tmp_path,
- capsys,
-):
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_configure
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- save_user_config(
- UserConfig(
- skill_distillation=SkillDistillationConfig(
- namespace="tooluniverse-trialqa",
- ),
- ),
- config_dir=tmp_path,
- )
-
- parser = _build_parser()
- args = parser.parse_args([
- "configure",
- "--disable-skill-distillation",
- ])
-
- _cmd_configure(args)
-
- assert load_user_config(tmp_path).skill_distillation == SkillDistillationConfig()
- raw = json.loads((tmp_path / "config.json").read_text())
- assert "skill_distillation" not in raw
- assert not (tmp_path / "credentials.json").exists()
- assert "Saved Switchyard config" in capsys.readouterr().out
-
-
-def test_configure_disable_skill_distillation_rejects_conflicting_flags():
- from switchyard.cli.switchyard_cli import _build_parser
-
- parser = _build_parser()
- with pytest.raises(SystemExit):
- parser.parse_args([
- "configure",
- "--disable-skill-distillation",
- "--skill-distillation",
- "tooluniverse-trialqa",
- ])
-
-
[email protected]("mode", ["--show", "--reset", "--list-models"])
- "skill_args",
- [
- ["--skill-distillation", "tooluniverse-trialqa"],
- ["--disable-skill-distillation"],
- ],
-)
-def test_configure_skill_distillation_rejects_read_or_reset_modes(
- mode,
- skill_args,
-):
- from switchyard.cli.switchyard_cli import _build_parser
-
- parser = _build_parser()
- with pytest.raises(SystemExit):
- parser.parse_args([
- "configure",
- mode,
- *skill_args,
- ])
-
-
-def test_configure_empty_skill_namespace_does_not_keep_existing_value(
- monkeypatch,
- tmp_path,
-):
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_configure
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- existing = SkillDistillationConfig(namespace="existing")
- save_user_config(UserConfig(skill_distillation=existing), config_dir=tmp_path)
-
- parser = _build_parser()
- args = parser.parse_args([
- "configure",
- "--skill-distillation",
- "",
- ])
-
- with pytest.raises(UserConfigError, match="letters, numbers"):
- _cmd_configure(args)
-
- assert load_user_config(tmp_path).skill_distillation == existing
-
-
-def test_configure_invalid_skill_namespace_reports_user_error(
- monkeypatch,
- tmp_path,
-):
- from switchyard.cli import switchyard_cli
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(sys, "argv", [
- "switchyard",
- "configure",
- "--skill-distillation", "bad/name",
- ])
-
- with pytest.raises(SystemExit) as excinfo:
- switchyard_cli.main()
-
- message = str(excinfo.value)
- assert "error: invalid user config" in message
- assert "letters, numbers, dot, underscore, and hyphen" in message
-
-
-def test_configure_list_models_honors_saved_default_provider(
- monkeypatch,
- tmp_path,
-):
- """`configure --list-models` uses the saved default_provider, not the
- argparse --provider default (which now defaults to None so it can't shadow
- the saved value)."""
- from switchyard.cli.configure_command import _list_models
- from switchyard.cli.switchyard_cli import _build_parser
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- save_user_config(
- UserConfig(
- default_provider="nvidia",
- providers={"nvidia": ProviderConfig(base_url="https://nvidia.test/v1")},
- ),
- config_dir=tmp_path,
- )
- save_user_credentials(
- UserCredentials(api_keys={"nvidia": "nvidia-key"}),
- config_dir=tmp_path,
- )
- monkeypatch.setattr("switchyard.server.server_util.load_secrets", lambda: {})
-
- captured: dict = {}
- monkeypatch.setattr(
- "switchyard.cli.configure_command.fetch_model_ids",
- lambda base_url, api_key: captured.update(base_url=base_url, api_key=api_key) or [],
- )
- monkeypatch.setattr(
- "switchyard.cli.configure_command.render_models",
- lambda model_ids, request: "",
- )
-
- parser = _build_parser()
- assert parser.parse_args(["configure"]).provider is None
- args = parser.parse_args(["configure", "--list-models"])
-
- _list_models(args)
-
- assert captured["base_url"] == "https://nvidia.test/v1"
- assert captured["api_key"] == "nvidia-key"
-
-
-def test_configure_non_interactive_uses_env_api_key(
- monkeypatch,
- tmp_path,
-):
- """Non-interactive `configure` falls back to an env/secrets API key instead
- of erroring out when none is passed on the CLI."""
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_configure
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setenv("OPENROUTER_API_KEY", "env-or-key")
- monkeypatch.setattr(
- "switchyard.cli.command_utils.is_interactive_terminal",
- lambda: False,
- )
- monkeypatch.setattr(
- "switchyard.cli.configure_command.is_interactive_terminal",
- lambda: False,
- )
- monkeypatch.setattr("switchyard.cli.configure_command.load_secrets", lambda: {})
-
- parser = _build_parser()
- args = parser.parse_args([
- "configure",
- "--no-model-discovery",
- "--target", "provider",
- ])
-
- _cmd_configure(args)
-
- assert load_user_credentials(tmp_path).api_key("openrouter") == "env-or-key"
-
-
-def test_configure_non_interactive_scopes_env_key_to_selected_provider(
- monkeypatch,
- tmp_path,
-):
- """`configure --provider nvidia` must not save an OPENROUTER_API_KEY under
- `nvidia`. With no NVIDIA_API_KEY set it requires an explicit --api-key."""
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_configure
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setenv("OPENROUTER_API_KEY", "openrouter-key")
- monkeypatch.setattr(
- "switchyard.cli.command_utils.is_interactive_terminal",
- lambda: False,
- )
- monkeypatch.setattr(
- "switchyard.cli.configure_command.is_interactive_terminal",
- lambda: False,
- )
- monkeypatch.setattr("switchyard.cli.configure_command.load_secrets", lambda: {})
-
- parser = _build_parser()
- args = parser.parse_args([
- "configure",
- "--provider", "nvidia",
- "--no-model-discovery",
- "--target", "provider",
- ])
-
- with pytest.raises(SystemExit, match="requires an API key"):
- _cmd_configure(args)
-
- assert load_user_credentials(tmp_path).api_key("nvidia") is None
-
-
-def test_configure_non_interactive_ignores_foreign_secrets_for_selected_provider(
- monkeypatch,
- tmp_path,
-):
- """A secrets.json entry for another provider must not satisfy
- `configure --provider nvidia`. Only the provider's own env key (or an
- explicit --api-key) may be saved under it; otherwise OpenRouter's secret
- would be persisted under `nvidia` and silently 401 at launch."""
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_configure
-
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- # secrets.json carries only OpenRouter's key; NVIDIA_API_KEY is unset
- # (cleared by the autouse fixture). Pre-fix this key leaked under nvidia.
- monkeypatch.setattr(
- "switchyard.cli.configure_command.load_secrets",
- lambda: {"openrouter": {"api_key": "sk-or-secrets"}},
- )
- monkeypatch.setattr(
- "switchyard.cli.command_utils.is_interactive_terminal",
- lambda: False,
- )
- monkeypatch.setattr(
- "switchyard.cli.configure_command.is_interactive_terminal",
- lambda: False,
- )
-
- parser = _build_parser()
- args = parser.parse_args([
- "configure",
- "--provider", "nvidia",
- "--no-model-discovery",
- "--target", "provider",
- ])
-
- with pytest.raises(SystemExit, match="requires an API key"):
- _cmd_configure(args)
-
- assert load_user_credentials(tmp_path).api_key("nvidia") is None
-
-
-def _write_bundle(path, api_key: str) -> None:
- path.write_text(
- "defaults:\n"
- f" api_key: {api_key}\n"
- " base_url: https://example.invalid/v1\n"
- "routes:\n"
- " alpha/model:\n"
- " type: model\n"
- )
-
-
-def _non_interactive_configure(monkeypatch, tmp_path):
- monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
- monkeypatch.setattr(
- "switchyard.cli.command_utils.is_interactive_terminal", lambda: False
- )
- monkeypatch.setattr(
- "switchyard.cli.configure_command.is_interactive_terminal", lambda: False
- )
- monkeypatch.setattr("switchyard.cli.configure_command.load_secrets", lambda: {})
-
-
-def test_configure_non_interactive_uses_route_bundle_api_key(monkeypatch, tmp_path):
- """Non-interactive `configure` with a --routing-profiles bundle that carries
- a literal defaults.api_key uses that key instead of erroring for --api-key.
- Regression for NVBug 6371154 / SWITCH-785."""
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_configure
-
- _non_interactive_configure(monkeypatch, tmp_path)
- bundle = tmp_path / "routes.yaml"
- _write_bundle(bundle, "bundle-secret-key")
-
- args = _build_parser().parse_args([
- "--routing-profiles", str(bundle),
- "configure", "--no-model-discovery", "--target", "provider",
- ])
- _cmd_configure(args)
-
- assert load_user_credentials(tmp_path).api_key("openrouter") == "bundle-secret-key"
-
-
-def test_configure_non_interactive_expands_route_bundle_env_ref(monkeypatch, tmp_path):
- """A bundle defaults.api_key of ${NVIDIA_API_KEY} is expanded from the env at
- configure time even when the provider defaults to openrouter — the exact
- reopened NVBug 6371154 repro (env var set, no --provider, no --api-key)."""
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_configure
-
- _non_interactive_configure(monkeypatch, tmp_path)
- monkeypatch.setenv("NVIDIA_API_KEY", "nv-env-key")
- bundle = tmp_path / "routes.yaml"
- _write_bundle(bundle, "${NVIDIA_API_KEY}")
-
- args = _build_parser().parse_args([
- "--routing-profiles", str(bundle),
- "configure", "--no-model-discovery", "--target", "provider",
- ])
- _cmd_configure(args)
-
- assert load_user_credentials(tmp_path).api_key("openrouter") == "nv-env-key"
-
-
-def test_configure_non_interactive_unresolved_bundle_env_ref_requires_key(
- monkeypatch, tmp_path
-):
- """An unset ${VAR} in the bundle stays literal after expansion, so configure
- fails closed and asks for --api-key rather than saving a literal ${VAR}."""
- from switchyard.cli.switchyard_cli import _build_parser, _cmd_configure
-
- _non_interactive_configure(monkeypatch, tmp_path)
- monkeypatch.delenv("DEFINITELY_UNSET_KEY_XYZ", raising=False)
- bundle = tmp_path / "routes.yaml"
- _write_bundle(bundle, "${DEFINITELY_UNSET_KEY_XYZ}")
-
- args = _build_parser().parse_args([
- "--routing-profiles", str(bundle),
- "configure", "--no-model-discovery", "--target", "provider",
- ])
- with pytest.raises(SystemExit, match="requires an API key"):
- _cmd_configure(args)
-
-
-def test_redacted_snapshot_surfaces_only_route_ids(tmp_path):
- """The snapshot exposes route ids but never the full bundle (env-var
- references inside the bundle may resolve to secrets at run time)."""
- save_user_config(
- UserConfig(routing_profiles={"routes": {
- "alpha/model": {"type": "model"},
- "beta/model": {"type": "model", "target": "other/model"},
- }}),
- config_dir=tmp_path,
- )
- snapshot = build_redacted_snapshot(tmp_path)
- saved = snapshot["routing_profiles"]
- assert isinstance(saved, dict)
- assert saved == {"route_ids": ["alpha/model", "beta/model"]}
-
-
-def test_resolve_provider_connectivity_precedence(monkeypatch, tmp_path):
- save_user_config(
- UserConfig(
- default_provider="nvidia",
- providers={"nvidia": ProviderConfig(base_url="https://user.test/v1")},
- ),
- config_dir=tmp_path,
- )
- save_user_credentials(
- UserCredentials(api_keys={"nvidia": "user-key"}),
- config_dir=tmp_path,
- )
- secrets = {
- "nvidia": {
- "api_key": "secrets-key",
- "base_url": "https://secrets.test/v1",
- },
- }
-
- resolved = resolve_provider_connectivity(
- cli_api_key=None,
- cli_base_url=None,
- api_key_env_vars=("NVIDIA_API_KEY",),
- base_url_env_vars=("NVIDIA_BASE_URL",),
- secrets=secrets,
- config_dir=tmp_path,
- )
- assert resolved.api_key == "user-key"
- assert resolved.base_url == "https://user.test/v1"
-
- monkeypatch.setenv("NVIDIA_API_KEY", "env-key")
- monkeypatch.setenv("NVIDIA_BASE_URL", "https://env.test/v1")
- resolved = resolve_provider_connectivity(
- cli_api_key="cli-key",
- cli_base_url="https://cli.test/v1",
- api_key_env_vars=("NVIDIA_API_KEY",),
- base_url_env_vars=("NVIDIA_BASE_URL",),
- secrets=secrets,
- config_dir=tmp_path,
- )
- assert resolved.api_key == "cli-key"
- assert resolved.base_url == "https://cli.test/v1"
-
-
-def test_resolve_provider_connectivity_ignores_unmatched_base_url_env(
- monkeypatch,
- tmp_path,
-):
- save_user_config(
- UserConfig(
- default_provider="nvidia",
- providers={"nvidia": ProviderConfig(base_url="https://user.test/v1")},
- ),
- config_dir=tmp_path,
- )
- save_user_credentials(
- UserCredentials(api_keys={"nvidia": "user-key"}),
- config_dir=tmp_path,
- )
- monkeypatch.setenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
-
- resolved = resolve_provider_connectivity(
- cli_api_key=None,
- cli_base_url=None,
- api_key_env_vars=("NVIDIA_API_KEY", "OPENAI_API_KEY"),
- base_url_env_vars=("NVIDIA_BASE_URL", "OPENAI_BASE_URL"),
- config_dir=tmp_path,
- )
-
- assert resolved.api_key == "user-key"
- assert resolved.base_url == "https://user.test/v1"
-
-
-def test_resolve_provider_connectivity_pairs_api_key_and_base_url_env(
- monkeypatch,
- tmp_path,
-):
- monkeypatch.setenv("OPENROUTER_API_KEY", "openrouter-key")
- monkeypatch.setenv("OPENROUTER_BASE_URL", "https://openrouter.test/v1")
- monkeypatch.setenv("NVIDIA_API_KEY", "nvidia-key")
- monkeypatch.setenv("NVIDIA_BASE_URL", "https://nvidia.test/v1")
-
- resolved = resolve_provider_connectivity(
- cli_api_key=None,
- cli_base_url=None,
- api_key_env_vars=("OPENROUTER_API_KEY", "NVIDIA_API_KEY", "OPENAI_API_KEY"),
- base_url_env_vars=("OPENROUTER_BASE_URL", "NVIDIA_BASE_URL", "OPENAI_BASE_URL"),
- config_dir=tmp_path,
- )
-
- assert resolved.provider == "openrouter"
- assert resolved.api_key == "openrouter-key" # pragma: allowlist secret # pragma: allowlist secret
- assert resolved.base_url == "https://openrouter.test/v1"
-
-
-def test_resolve_provider_connectivity_keeps_nvidia_env_fallback(
- monkeypatch,
- tmp_path,
-):
- monkeypatch.setenv("NVIDIA_API_KEY", "nvidia-key")
- monkeypatch.setenv("NVIDIA_BASE_URL", "https://nvidia.test/v1")
-
- resolved = resolve_provider_connectivity(
- cli_api_key=None,
- cli_base_url=None,
- api_key_env_vars=("OPENROUTER_API_KEY", "NVIDIA_API_KEY", "OPENAI_API_KEY"),
- base_url_env_vars=("OPENROUTER_BASE_URL", "NVIDIA_BASE_URL", "OPENAI_BASE_URL"),
- config_dir=tmp_path,
- )
-
- assert resolved.provider == "nvidia"
- assert resolved.api_key == "nvidia-key" # pragma: allowlist secret # pragma: allowlist secret
- assert resolved.base_url == "https://nvidia.test/v1"
-
-
-def test_resolve_provider_connectivity_uses_selected_env_provider_default_base_url(
- monkeypatch,
- tmp_path,
-):
- monkeypatch.setenv("NVIDIA_API_KEY", "nvidia-key")
- monkeypatch.setenv("OPENROUTER_BASE_URL", "https://openrouter.test/v1")
-
- resolved = resolve_provider_connectivity(
- cli_api_key=None,
- cli_base_url=None,
- api_key_env_vars=("OPENROUTER_API_KEY", "NVIDIA_API_KEY", "OPENAI_API_KEY"),
- base_url_env_vars=("OPENROUTER_BASE_URL", "NVIDIA_BASE_URL", "OPENAI_BASE_URL"),
- config_dir=tmp_path,
- )
-
- assert resolved.provider == "nvidia"
- assert resolved.api_key == "nvidia-key" # pragma: allowlist secret # pragma: allowlist secret
- assert resolved.base_url == "https://inference-api.nvidia.com/v1"
-
-
-def test_resolve_provider_connectivity_ignores_unsupported_env_provider(
- monkeypatch,
- tmp_path,
-):
- monkeypatch.setenv("ANTHROPIC_API_KEY", "anthropic-key")
-
- resolved = resolve_provider_connectivity(
- cli_api_key=None,
- cli_base_url=None,
- api_key_env_vars=("ANTHROPIC_API_KEY",),
- base_url_env_vars=("OPENROUTER_BASE_URL",),
- config_dir=tmp_path,
- )
-
- assert resolved.provider == "openrouter"
- assert resolved.api_key == "anthropic-key" # pragma: allowlist secret # pragma: allowlist secret
- assert resolved.base_url == DEFAULT_OPENROUTER_BASE_URL
-
-
-def test_resolve_provider_connectivity_uses_default_base_url(tmp_path):
- resolved = resolve_provider_connectivity(
- cli_api_key=None,
- cli_base_url=None,
- api_key_env_vars=("OPENROUTER_API_KEY",),
- base_url_env_vars=("OPENROUTER_BASE_URL",),
- config_dir=tmp_path,
- )
- assert resolved.api_key is None
- assert resolved.base_url == DEFAULT_OPENROUTER_BASE_URL
-
-
-def test_redacted_snapshot_hides_api_key(tmp_path):
- save_user_config(
- UserConfig(
- providers={"nvidia": ProviderConfig(base_url="https://example.test/v1")},
- launch={
- "codex": LaunchConfig(
- model="openai/openai/openai/gpt-5.5",
- route=LaunchRouteConfig(
- type="single",
- model="openai/openai/openai/gpt-5.5",
- endpoints={
- PRIMARY_TIER: LaunchTierEndpointConfig(
- base_url="https://codex.example/v1",
- ),
- },
- ),
- ),
- },
- ),
- config_dir=tmp_path,
- )
- save_user_credentials(
- UserCredentials(
- api_keys={"nvidia": "nvapi-abcdef123456"},
- launch={
- "codex": LaunchCredentials(
- api_keys={PRIMARY_TIER: "codex-abcdef123456"},
- ),
- },
- ),
- config_dir=tmp_path,
- )
-
- snapshot = build_redacted_snapshot(tmp_path)
- providers = snapshot["providers"]
- assert isinstance(providers, dict)
- provider = providers["nvidia"]
- assert isinstance(provider, dict)
- assert provider["api_key"] == "nvap...3456"
- launch = snapshot["launch"]
- assert isinstance(launch, dict)
- codex = launch["codex"]
- assert isinstance(codex, dict)
- route = codex["route"]
- assert isinstance(route, dict)
- endpoints = route["endpoints"]
- assert isinstance(endpoints, dict)
- primary = endpoints[PRIMARY_TIER]
- assert isinstance(primary, dict)
- assert primary["base_url"] == "https://codex.example/v1"
- assert primary["api_key"] == "code...3456"
diff --git a/tests/test_verify.py b/tests/test_verify.py
deleted file mode 100644
index 4bb75266a..000000000
--- a/tests/test_verify.py
+++ /dev/null
@@ -1,1387 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Tests for ``switchyard.server.verify``.
-
-Covers the three top-level orchestrators (``verify_proxy``,
-``verify_claude``, ``verify_codex``), the ``_Checklist`` runner that
-produces their pass/fail output, and each step body in isolation
-(credential resolution, backend reachability, probe shape, proxy
-round-trip, harness binary lookup, harness invocation, lifecycle
-teardown).
-
-Real network, uvicorn, and ``subprocess.run`` are all mocked — these
-tests don't open a port or hit the wire. The end-to-end integration
-tests live in ``tests/offline_production_tests/v2/test_verify_e2e.py``
-and are gated on a real NVIDIA API key + the harness binaries.
-
-Mirrors the structure of :mod:`tests.test_launch_claude_v2` /
-:mod:`tests.test_launch_codex_v2` for consistency: same fixture
-patterns, same monkeypatch path strings, same per-section comment
-banners. Keeps the verify tests easy to read alongside their
-launcher counterparts.
-"""
-
-from __future__ import annotations
-
-import subprocess
-from unittest.mock import MagicMock
-
-import httpx
-import pytest
-
-from switchyard.server import verify as verify_mod
-from switchyard.server.verify import (
- _check_backend_reachable,
- _check_credentials,
- _Checklist,
- _locate_claude,
- _locate_codex,
- _proxy_roundtrip,
- _run_claude_prompt,
- _run_codex_prompt,
- _teardown,
- verify_claude,
- verify_codex,
- verify_proxy,
-)
-
-# ---------------------------------------------------------------------------
-# _Checklist — the runner that powers the pass/fail UX
-# ---------------------------------------------------------------------------
-
-
-class TestChecklist:
- """Stdout rendering, halt-on-fail policy, and summary-line semantics."""
-
- def test_happy_path_three_ok_steps_returns_zero(self, capsys):
- cl = _Checklist(title="t", total=3)
- cl.run("a", lambda: "detail-a")
- cl.run("b", lambda: "detail-b")
- cl.run("c", lambda: "") # detail-less ⇒ "OK (Nms)" form
- rc = cl.summarize("proxy", "model-x", 12.5)
-
- assert rc == 0
- out = capsys.readouterr().out
- assert "[1/3] a..." in out
- assert "OK (detail-a" in out
- assert "[2/3] b..." in out
- assert "[3/3] c..." in out
- assert "verify proxy: PASS (model=model-x" in out
-
- def test_first_failure_halts_subsequent_steps(self, capsys):
- cl = _Checklist(title="t", total=3)
- cl.run("a", lambda: "ok-a")
-
- def _boom() -> str:
- raise RuntimeError("nope")
- cl.run("b", _boom)
-
- sentinel: dict[str, bool] = {"called": False}
- def _later() -> str:
- sentinel["called"] = True
- return "should-not-render"
- cl.run("c", _later)
-
- rc = cl.summarize("proxy", "m", 1.0)
-
- assert rc == 1
- assert sentinel["called"] is False, (
- "Step c body must be skipped once an earlier step has failed; "
- "otherwise the verifier would mask the root-cause failure "
- "behind a cascade of follow-up failures."
- )
- out = capsys.readouterr().out
- assert "FAIL (RuntimeError: nope" in out
- assert "SKIP skipped (prior step failed)" in out
- assert "verify proxy: FAIL" in out
-
- def test_results_record_passed_and_detail(self, capsys): # noqa: ARG002
- cl = _Checklist(title="t", total=2)
- cl.run("a", lambda: "ok-a-detail")
- cl.run("b", lambda: (_ for _ in ()).throw(ValueError("bad")))
-
- assert len(cl.results) == 2
- assert cl.results[0].passed is True
- assert cl.results[0].detail == "ok-a-detail"
- assert cl.results[1].passed is False
- assert "ValueError: bad" in cl.results[1].detail
-
-
-# ---------------------------------------------------------------------------
-# _check_credentials
-# ---------------------------------------------------------------------------
-
-
-class TestCheckCredentials:
- """Pure function: missing key raises, valid key produces a redacted label."""
-
- def test_missing_api_key_raises(self):
- with pytest.raises(RuntimeError, match="no API key resolved"):
- _check_credentials(None, "https://example.com/v1")
-
- def test_empty_api_key_raises(self):
- with pytest.raises(RuntimeError, match="no API key resolved"):
- _check_credentials("", "https://example.com/v1")
-
- def test_valid_credentials_returns_label(self):
- out = _check_credentials("sk-abc", "https://example.com/v1")
- # Key must be redacted — verify is run by users in shared
- # terminals (CI logs, screenshots, slack pastes). A leaked
- # key in our own diagnostic is the worst possible outcome.
- assert "sk-abc" not in out
- assert "*****" in out
- assert "https://example.com/v1" in out
-
- def test_missing_base_url_falls_back_to_label(self):
- out = _check_credentials("sk-abc", None)
- assert "openai default" in out
-
- def test_key_source_surfaced_in_success_detail(self):
- """When the caller knows where the key came from, the success
- annotation should name the source. This is the contract that
- lets the user spot which env var / file is in play *before* a
- downstream failure forces them to hunt.
- """
- out = _check_credentials(
- "sk-abc", "https://example.com/v1", key_source="$NVIDIA_API_KEY",
- )
- assert "from $NVIDIA_API_KEY" in out
- # Source gets prefixed by " from " so it reads naturally next
- # to the redacted key: "api_key=***** from $NVIDIA_API_KEY".
- assert "api_key=***** from $NVIDIA_API_KEY" in out
-
- def test_key_source_omitted_when_caller_doesnt_track_it(self):
- """Direct API callers can omit ``key_source`` — no source label
- should appear, and the rest of the detail should still render.
- """
- out = _check_credentials("sk-abc", "https://example.com/v1")
- assert " from " not in out
- assert "*****" in out
-
-
-# ---------------------------------------------------------------------------
-# _check_backend_reachable
-# ---------------------------------------------------------------------------
-
-
-class TestCheckBackendReachable:
- """HTTP semantics: 200 OK returns detail, non-200 raises with status code."""
-
- def test_200_returns_detail(self, monkeypatch):
- captured: dict = {}
-
- class _FakeResp:
- status_code = 200
- text = ""
-
- class _FakeClient:
- def __init__(self, *_, **kwargs):
- captured["timeout"] = kwargs.get("timeout")
-
- def __enter__(self):
- return self
-
- def __exit__(self, *_):
- return False
-
- def get(self, url, headers):
- captured["url"] = url
- captured["headers"] = headers
- return _FakeResp()
-
- monkeypatch.setattr(httpx, "Client", _FakeClient)
-
- out = _check_backend_reachable(
- "https://api.example.com/v1", "sk-abc",
- )
- assert "GET /models 200" in out
- assert captured["url"] == "https://api.example.com/v1/models"
- assert captured["headers"]["Authorization"] == "Bearer sk-abc"
-
- def _install_fake_status(self, monkeypatch, status_code: int, body: str = ""):
- """Helper: pin ``httpx.Client.get`` to return a fixed status code.
-
- Lets each status-code branch test stay self-contained without
- repeating the four-method fake-client boilerplate.
- """
- class _FakeResp:
- def __init__(self, code: int, text: str) -> None:
- self.status_code = code
- self.text = text
-
- class _FakeClient:
- def __init__(self, *_, **__):
- pass
-
- def __enter__(self):
- return self
-
- def __exit__(self, *_):
- return False
-
- def get(self, url, headers): # noqa: ARG002
- return _FakeResp(status_code, body)
-
- monkeypatch.setattr(httpx, "Client", _FakeClient)
-
- def test_401_names_the_key_source(self, monkeypatch):
- """The 401 branch must call out (a) that the *backend* rejected
- the key, (b) which source the key came from, and (c) what to
- do about it. All three are user-facing requirements — a bare
- "HTTP 401" forces the user to hunt for which knob to turn.
- """
- self._install_fake_status(monkeypatch, 401, '{"error": "invalid"}')
-
- with pytest.raises(RuntimeError) as exc_info:
- _check_backend_reachable(
- "https://api.example.com/v1", "sk-bad",
- key_source="$NVIDIA_API_KEY",
- )
- msg = str(exc_info.value)
- assert "HTTP 401" in msg
- assert "$NVIDIA_API_KEY" in msg
- assert "rejected" in msg.lower()
- # Actionable hint must be present — the user's next move is
- # rotate-or-replace, not "investigate".
- assert "rotate" in msg.lower() or "double-check" in msg.lower()
-
- def test_401_uses_generic_label_when_source_unknown(self, monkeypatch):
- """Direct callers may not know where the key came from — fall
- back to a neutral phrase rather than a literal ``"None"``.
- """
- self._install_fake_status(monkeypatch, 401)
- with pytest.raises(RuntimeError) as exc_info:
- _check_backend_reachable(
- "https://api.example.com/v1", "sk-bad",
- )
- msg = str(exc_info.value)
- assert "HTTP 401" in msg
- assert "None" not in msg
- assert "the resolved key" in msg
-
- def test_404_hints_at_base_url_typo(self, monkeypatch):
- """404 means the URL is wrong, not the key. The hint must
- steer the user to the URL. Common case: ``--base-url`` was
- set without the ``/v1`` suffix or with a typo elsewhere.
- """
- self._install_fake_status(monkeypatch, 404)
- with pytest.raises(RuntimeError) as exc_info:
- _check_backend_reachable(
- "https://api.example.com/typo", "sk-abc",
- key_source="$NVIDIA_API_KEY",
- )
- msg = str(exc_info.value)
- assert "HTTP 404" in msg
- assert "typo" in msg.lower()
- assert "/v1" in msg
- # Source label is irrelevant for a 404 (it's a URL problem,
- # not a credential problem) — must NOT mislead the user by
- # mentioning the key source.
- assert "$NVIDIA_API_KEY" not in msg
-
- def test_other_4xx_falls_through_to_generic(self, monkeypatch):
- """Status codes outside 401/404 use the generic "HTTP <code>"
- message — keeps the surface predictable and doesn't pretend
- to diagnose codes we haven't validated specific hints for.
- """
- self._install_fake_status(monkeypatch, 403)
- with pytest.raises(RuntimeError) as exc_info:
- _check_backend_reachable("https://api.example.com/v1", "sk-abc")
- assert "HTTP 403" in str(exc_info.value)
-
- def test_strips_trailing_slash_in_url(self, monkeypatch):
- captured: dict = {}
-
- class _FakeResp:
- status_code = 200
- text = ""
-
- class _FakeClient:
- def __init__(self, *_, **__):
- pass
-
- def __enter__(self):
- return self
-
- def __exit__(self, *_):
- return False
-
- def get(self, url, headers): # noqa: ARG002
- captured["url"] = url
- return _FakeResp()
-
- monkeypatch.setattr(httpx, "Client", _FakeClient)
-
- _check_backend_reachable("https://api.example.com/v1/", "sk-abc")
- # Must not produce ``//models`` from ``base_url='/v1/'`` + ``/models``.
- assert captured["url"] == "https://api.example.com/v1/models"
-
-
-# ---------------------------------------------------------------------------
-# _proxy_roundtrip
-# ---------------------------------------------------------------------------
-
-
-class TestProxyRoundtrip:
- """Validates the synthetic chat-completions probe sent through the proxy."""
-
- def _install_fake_response(self, monkeypatch, payload, status_code=200):
- """Helper: pin ``httpx.Client.post`` to return a fixed JSON body.
-
- Centralizes the four-method fake-client boilerplate so each
- scenario test reads as a single ``payload`` dict. ``status_code``
- is overridable for the non-200 case.
- """
- class _FakeResp:
- def __init__(self, code, body):
- self.status_code = code
- self.text = ""
- self._body = body
-
- def json(self):
- return self._body
-
- class _FakeClient:
- def __init__(self, *_, **kwargs):
- # SWITCH-857: the loopback verify roundtrip must bypass env
- # proxies, so verify.py builds this client with trust_env=False.
- # Assert it here so dropping that kwarg fails the suite.
- assert kwargs.get("trust_env") is False, (
- "verify roundtrip must use httpx.Client(trust_env=False) to "
- "bypass env proxies on the 127.0.0.1 probe"
- )
-
- def __enter__(self):
- return self
-
- def __exit__(self, *_):
- return False
-
- def post(self, url, json): # noqa: ARG002
- return _FakeResp(status_code, payload)
-
- monkeypatch.setattr(httpx, "Client", _FakeClient)
-
- def test_happy_path_with_visible_text_returns_reply_preview(
- self, monkeypatch,
- ):
- self._install_fake_response(monkeypatch, {
- "choices": [{"message": {"content": "ok"}}],
- "usage": {"prompt_tokens": 10, "completion_tokens": 1},
- })
-
- out = _proxy_roundtrip(54321, "test-model")
- assert "reply='ok'" in out
- assert "in=10" in out
- assert "out=1" in out
-
- def test_non_200_raises_with_body_snippet(self, monkeypatch):
- self._install_fake_response(
- monkeypatch, {}, status_code=500,
- )
- with pytest.raises(RuntimeError, match="HTTP 500"):
- _proxy_roundtrip(54321, "test-model")
-
- def test_reasoning_only_truncation_is_tolerated(self, monkeypatch):
- """Reasoning models (Qwen, GPT-5-reasoning) at small max_tokens
- consume the entire budget on internal reasoning and surface
- empty visible text. The chain still worked end-to-end —
- verify must report this as a pass with an annotation, not as
- a failure that would mask a real chain bug.
-
- Critical contract: completion_tokens > 0 (model *did*
- generate) + content empty + finish_reason="length" → PASS
- with ``"no visible text (reasoning-only)"`` detail.
- """
- self._install_fake_response(monkeypatch, {
- "choices": [{
- "message": {"content": ""},
- "finish_reason": "length",
- }],
- "usage": {"prompt_tokens": 10, "completion_tokens": 2048},
- })
-
- out = _proxy_roundtrip(54321, "test-model")
- assert "no visible text" in out
- assert "reasoning-only" in out
- assert "finish_reason=length" in out
- # Token counts must still appear so the user sees the chain
- # *did* shuffle tokens through — that's the positive signal.
- assert "in=10" in out
- assert "out=2048" in out
-
- def test_zero_output_tokens_raises(self, monkeypatch):
- """``completion_tokens == 0`` is a real failure: the upstream
- returned a structurally valid response but never generated
- anything, so verify can't claim "all good". Distinct from
- the reasoning-truncation case (which has nonzero output
- tokens, just no visible text).
- """
- self._install_fake_response(monkeypatch, {
- "choices": [{"message": {"content": ""}}],
- "usage": {"prompt_tokens": 5, "completion_tokens": 0},
- })
-
- with pytest.raises(RuntimeError, match="no output tokens"):
- _proxy_roundtrip(54321, "test-model")
-
- def test_no_choices_raises(self, monkeypatch):
- """A 200 response with no ``choices`` array means the upstream
- replied but the chain didn't produce a usable shape — has
- happened with badly-configured upstreams that 200 a JSON
- error blob. Surface it loudly.
- """
- self._install_fake_response(monkeypatch, {
- "id": "bad", "object": "chat.completion", "usage": {},
- })
-
- with pytest.raises(RuntimeError, match="no choices"):
- _proxy_roundtrip(54321, "test-model")
-
-
-# ---------------------------------------------------------------------------
-# _locate_claude / _locate_codex
-# ---------------------------------------------------------------------------
-
-
-class TestLocateBinaries:
- """Reuses the launcher's binary-finder so resolution stays in lockstep."""
-
- def test_locate_claude_present(self, monkeypatch):
- monkeypatch.setattr(verify_mod, "_find_claude_binary", lambda: "/x/claude")
- assert _locate_claude() == "/x/claude"
-
- def test_locate_claude_missing_raises_with_install_hint(self, monkeypatch):
- monkeypatch.setattr(verify_mod, "_find_claude_binary", lambda: None)
- with pytest.raises(RuntimeError, match="claude binary not found"):
- _locate_claude()
-
- def test_locate_codex_present(self, monkeypatch):
- monkeypatch.setattr(verify_mod, "_find_codex_binary", lambda: "/x/codex")
- assert _locate_codex() == "/x/codex"
-
- def test_locate_codex_missing_raises_with_install_hint(self, monkeypatch):
- monkeypatch.setattr(verify_mod, "_find_codex_binary", lambda: None)
- with pytest.raises(RuntimeError, match="codex binary not found"):
- _locate_codex()
-
-
-# ---------------------------------------------------------------------------
-# _run_claude_prompt / _run_codex_prompt
-# ---------------------------------------------------------------------------
-
-
-class TestRunClaudePrompt:
- """Subprocess invocation: env injection, exit-code handling, timeout,
- and the ``--output-format json`` envelope contract.
- """
-
- @staticmethod
- def _envelope(result: str | None = "ok", **extra) -> str:
- """Build a claude ``--output-format json`` envelope for tests.
-
- Mirrors the real shape: a single JSON object with ``type``,
- ``subtype``, ``result``, plus optional ``num_turns`` /
- ``stop_reason`` fields claude surfaces in the empty-result
- case. Centralized so test data stays consistent.
- """
- import json as _json
- body = {
- "type": "result",
- "subtype": "success",
- "result": result,
- }
- body.update(extra)
- return _json.dumps(body)
-
- def test_happy_path_returns_reply_preview(self, monkeypatch):
- captured: dict = {}
-
- def fake_run(cmd, env, capture_output, text, timeout, check): # noqa: ARG001
- captured["cmd"] = cmd
- captured["env"] = env
- return subprocess.CompletedProcess(
- cmd, returncode=0, stdout=self._envelope("ok"), stderr="",
- )
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- out = _run_claude_prompt("/fake/claude", 54321, "test-model")
- assert "reply='ok'" in out
-
- # Env-var contract must match launch_claude — drift here means
- # the verifier validates a shape Claude Code doesn't actually
- # accept in production.
- env = captured["env"]
- assert env["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:54321"
- assert env["ANTHROPIC_AUTH_TOKEN"] == "switchyard"
- assert env["ANTHROPIC_API_KEY"] == ""
- assert env["ANTHROPIC_MODEL"] == "test-model"
- assert env["ANTHROPIC_SMALL_FAST_MODEL"] == "test-model"
-
- # Argv contract: -p prompt, JSON output, --max-turns 1, skip
- # permissions. The output-format pin is what enables the
- # reasoning-truncation tolerance below — drift here would
- # break that diagnostic.
- cmd = captured["cmd"]
- assert cmd[0] == "/fake/claude"
- assert "-p" in cmd
- assert "--output-format" in cmd
- assert "json" in cmd
- assert "--max-turns" in cmd
- assert "--dangerously-skip-permissions" in cmd
-
- def test_non_zero_exit_surfaces_stderr(self, monkeypatch):
- def fake_run(cmd, **kwargs): # noqa: ARG001
- return subprocess.CompletedProcess(
- cmd, returncode=1, stdout="", stderr="boom",
- )
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- with pytest.raises(RuntimeError, match=r"claude exited 1.*boom"):
- _run_claude_prompt("/fake/claude", 54321, "m")
-
- def test_empty_stdout_raises(self, monkeypatch):
- """Exit 0 with literally no stdout means claude didn't even
- emit its envelope — that's a real failure, distinct from
- the "envelope present but ``result`` empty" case below.
- """
- def fake_run(cmd, **kwargs): # noqa: ARG001
- return subprocess.CompletedProcess(
- cmd, returncode=0, stdout=" \n", stderr="",
- )
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- with pytest.raises(RuntimeError, match="exited 0 but produced no stdout"):
- _run_claude_prompt("/fake/claude", 54321, "m")
-
- def test_empty_result_field_is_tolerated(self, monkeypatch):
- """Reasoning models burn the budget on internal reasoning and
- surface an empty ``result`` field. Same contract as the
- proxy roundtrip step: chain worked end-to-end → PASS with
- a "reasoning-only" annotation rather than failing.
- """
- def fake_run(cmd, **kwargs): # noqa: ARG001
- return subprocess.CompletedProcess(
- cmd, returncode=0,
- stdout=self._envelope(
- result="", num_turns=1, stop_reason="length",
- ),
- stderr="",
- )
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- out = _run_claude_prompt("/fake/claude", 54321, "qwen-reasoning")
- assert "no visible reply" in out
- assert "reasoning-only" in out
- # Surface the envelope hints so the user sees *why* the
- # reply is empty — it's a model-budget artifact, not a
- # chain bug.
- assert "num_turns=1" in out
- assert "stop_reason=length" in out
-
- def test_invalid_json_stdout_raises(self, monkeypatch):
- """Exit 0 with stdout that isn't valid JSON means claude's
- output contract changed — surface as a real failure rather
- than swallowing the malformed body.
- """
- def fake_run(cmd, **kwargs): # noqa: ARG001
- return subprocess.CompletedProcess(
- cmd, returncode=0, stdout="just plain text, not json",
- stderr="",
- )
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- with pytest.raises(RuntimeError, match="non-JSON stdout"):
- _run_claude_prompt("/fake/claude", 54321, "m")
-
- def test_timeout_raises_runtime_error(self, monkeypatch):
- def fake_run(cmd, **kwargs):
- raise subprocess.TimeoutExpired(cmd, kwargs["timeout"])
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- with pytest.raises(RuntimeError, match="claude did not exit within"):
- _run_claude_prompt("/fake/claude", 54321, "m")
-
-
-class TestRunCodexPrompt:
- """Sibling of TestRunClaudePrompt. Codex's ``exec`` mode doesn't
- expose a structured envelope, so the reasoning-only-truncation
- detection here is coarser (exit 0 + empty stdout = tolerate)
- than in :class:`TestRunClaudePrompt`.
- """
-
- def test_happy_path_returns_reply_preview(self, monkeypatch):
- captured: dict = {}
-
- def fake_run(cmd, env, capture_output, text, timeout, check): # noqa: ARG001
- captured["cmd"] = cmd
- captured["env"] = env
- return subprocess.CompletedProcess(
- cmd, returncode=0, stdout="ok\n", stderr="",
- )
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- out = _run_codex_prompt("/fake/codex", 54321, "test-model")
- assert "reply='ok'" in out
-
- # OPENAI_API_KEY placeholder is required for codex's provider
- # config validation; matches launch_codex's contract.
- assert captured["env"]["OPENAI_API_KEY"] == "switchyard"
-
- # Argv contract: codex_bin, six -c overrides (12 entries),
- # -m model, exec, prompt. Provider overrides must include
- # the proxy URL with the chosen port.
- cmd = captured["cmd"]
- assert cmd[0] == "/fake/codex"
- assert "exec" in cmd
- assert "-m" in cmd
- assert "test-model" in cmd
- assert any('base_url="http://127.0.0.1:54321/v1"' in v for v in cmd)
-
- def test_non_zero_exit_surfaces_stderr(self, monkeypatch):
- def fake_run(cmd, **kwargs): # noqa: ARG001
- return subprocess.CompletedProcess(
- cmd, returncode=2, stdout="", stderr="codex error",
- )
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- with pytest.raises(RuntimeError, match=r"codex exited 2.*codex error"):
- _run_codex_prompt("/fake/codex", 54321, "m")
-
- def test_empty_stdout_is_tolerated(self, monkeypatch):
- """Exit 0 with empty stdout = reasoning-only truncation.
- Codex doesn't emit an envelope so we can't be precise about
- ``num_turns`` / ``stop_reason``, but the chain still ran
- end-to-end (exit 0). Must not false-fail here.
- """
- def fake_run(cmd, **kwargs): # noqa: ARG001
- return subprocess.CompletedProcess(
- cmd, returncode=0, stdout=" \n", stderr="",
- )
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- out = _run_codex_prompt("/fake/codex", 54321, "qwen-reasoning")
- assert "no visible reply" in out
- assert "reasoning-only" in out
-
- def test_timeout_raises_runtime_error(self, monkeypatch):
- def fake_run(cmd, **kwargs):
- raise subprocess.TimeoutExpired(cmd, kwargs["timeout"])
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- with pytest.raises(RuntimeError, match="codex did not exit within"):
- _run_codex_prompt("/fake/codex", 54321, "m")
-
-
-# ---------------------------------------------------------------------------
-# _teardown
-# ---------------------------------------------------------------------------
-
-
-class TestTeardown:
- """Lifecycle: signal exit (both graceful + force), join with timeout,
- soft-warn rather than fail loud when the shutdown is slow.
- """
-
- def test_clean_shutdown_returns_empty_detail(self):
- server = MagicMock()
- server.should_exit = False
- server.force_exit = False
- thread = MagicMock()
- thread.is_alive.return_value = False
-
- out = _teardown(server, thread)
- assert out == ""
- # Both flags must be set: uvicorn's default
- # timeout_graceful_shutdown=None blocks shutdown until all
- # keep-alive connections close, so streaming clients (Claude
- # Code, codex) can hold the proxy hostage without
- # ``force_exit``. Drift here would silently regress the
- # streaming-shutdown contract.
- assert server.should_exit is True
- assert server.force_exit is True
- thread.join.assert_called_once()
-
- def test_slow_shutdown_returns_warning_not_failure(self):
- """When uvicorn doesn't drain in time, the teardown step must
- return a soft warning rather than raising — verify is a
- single-shot CLI, the proxy thread is a daemon, and so a
- lingering thread dies on process exit anyway. Failing here
- would mask the real signal (the verify chain worked end-to-
- end) behind a uvicorn shutdown quirk.
- """
- server = MagicMock()
- thread = MagicMock()
- thread.is_alive.return_value = True
-
- out = _teardown(server, thread)
- # Soft warning text — the user should still see that
- # shutdown was slow so a real shutdown bug isn't fully
- # silenced, but the step doesn't fail the verify run.
- assert "shutdown slow" in out
- assert "daemon thread" in out
-
-
-# ---------------------------------------------------------------------------
-# Top-level orchestrators (with externals mocked)
-# ---------------------------------------------------------------------------
-
-
-def _make_fake_server(started: bool = True) -> MagicMock:
- server = MagicMock()
- server.started = started
- server.should_exit = False
- return server
-
-
-def _stub_spawn_proxy_returning(server: MagicMock):
- def _inner(switchyard, port): # noqa: ARG001
- thread = MagicMock()
- thread.is_alive.return_value = False
- return server, thread
- return _inner
-
-
-def _stub_httpx_responses(monkeypatch, *, models_status=200, chat_status=200,
- chat_content="ok"):
- """Wire ``httpx.Client`` to return canned responses for ``GET /models``
- and ``POST /v1/chat/completions``. Routing is by URL substring so
- one stub covers both verify steps in a single fixture.
- """
-
- class _FakeResp:
- def __init__(self, status, body=None):
- self.status_code = status
- self.text = ""
- self._body = body or {}
-
- def json(self):
- return self._body
-
- class _FakeClient:
- def __init__(self, *_, **__):
- pass
-
- def __enter__(self):
- return self
-
- def __exit__(self, *_):
- return False
-
- def get(self, url, headers): # noqa: ARG002
- return _FakeResp(models_status)
-
- def post(self, url, json): # noqa: ARG002
- body = {
- "choices": [{"message": {"content": chat_content}}],
- "usage": {"prompt_tokens": 5, "completion_tokens": 1},
- }
- return _FakeResp(chat_status, body)
-
- monkeypatch.setattr(httpx, "Client", _FakeClient)
-
-
-def _mock_verify_externals(monkeypatch):
- """Mock probe + chain construction so verify_* never hit the wire.
-
- Individual tests still install their own ``subprocess.run`` /
- ``httpx.Client`` mocks because each one tests a different mode-
- specific code path; this fixture just covers the parts that are
- identical across all three orchestrators.
- """
- async def _probe_false(**_):
- return False
- def _build_switchyard(*_args, **_kwargs):
- return MagicMock()
- monkeypatch.setattr(verify_mod, "probe_anthropic_messages_support", _probe_false)
- monkeypatch.setattr(verify_mod, "_build_claude_switchyard", _build_switchyard)
- monkeypatch.setattr(
- verify_mod, "_build_codex_switchyard", lambda *a, **kw: MagicMock(),
- )
- monkeypatch.setattr(
- verify_mod, "_spawn_proxy_thread",
- _stub_spawn_proxy_returning(_make_fake_server(started=True)),
- )
- monkeypatch.setattr(verify_mod, "_find_free_port", lambda: 54321)
-
-
-class TestVerifyProxyOrchestrator:
- """End-to-end smoke for the proxy-only mode with all externals mocked."""
-
- def test_happy_path_returns_zero(
- self, monkeypatch, capsys, _mock_verify_externals,
- ):
- _stub_httpx_responses(monkeypatch)
-
- rc = verify_proxy(
- model="test-model",
- base_url="https://example.com/v1",
- api_key="sk-test",
- port=None,
- timeout=None,
- )
-
- assert rc == 0
- out = capsys.readouterr().out
- # All six steps must report — the count check is the
- # contract that the runner didn't short-circuit silently.
- assert "[1/6]" in out
- assert "[6/6]" in out
- assert "verify proxy: PASS" in out
-
- def test_unreachable_backend_returns_one_and_skips_rest(
- self, monkeypatch, capsys, _mock_verify_externals,
- ):
- _stub_httpx_responses(monkeypatch, models_status=503)
-
- rc = verify_proxy(
- model="test-model",
- base_url="https://example.com/v1",
- api_key="sk-test",
- port=None,
- timeout=None,
- )
-
- assert rc == 1
- out = capsys.readouterr().out
- assert "FAIL (RuntimeError" in out
- assert "verify proxy: FAIL" in out
- # Subsequent steps must be skipped — ensures the user sees
- # ONE root-cause failure, not a cascade of derived ones.
- assert "SKIP" in out
-
- def test_missing_api_key_fails_at_step_1(
- self, monkeypatch, capsys, _mock_verify_externals,
- ):
- _stub_httpx_responses(monkeypatch)
-
- rc = verify_proxy(
- model="test-model",
- base_url="https://example.com/v1",
- api_key="",
- port=None,
- timeout=None,
- )
-
- assert rc == 1
- out = capsys.readouterr().out
- # Failure at step 1 means everything else gets SKIP.
- assert "[1/6] Resolving credentials..." in out
- assert "FAIL" in out
-
-
-class TestVerifyClaudeOrchestrator:
- """End-to-end smoke for ``verify claude`` with all externals mocked."""
-
- def test_happy_path_returns_zero(
- self, monkeypatch, capsys, _mock_verify_externals,
- ):
- _stub_httpx_responses(monkeypatch)
- monkeypatch.setattr(verify_mod, "_find_claude_binary", lambda: "/x/claude")
-
- # Claude's --output-format json envelope shape — see
- # :class:`TestRunClaudePrompt._envelope` for the canonical
- # builder. Inlined here because this test only needs a
- # single happy-path body and importing across test classes
- # would couple them.
- import json as _json
- envelope = _json.dumps({
- "type": "result", "subtype": "success", "result": "ok",
- })
-
- def fake_run(cmd, **kwargs): # noqa: ARG001
- return subprocess.CompletedProcess(
- cmd, returncode=0, stdout=envelope, stderr="",
- )
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- rc = verify_claude(
- model="test-model",
- base_url="https://example.com/v1",
- api_key="sk-test",
- port=None,
- timeout=None,
- )
-
- assert rc == 0
- out = capsys.readouterr().out
- assert "[8/8]" in out
- assert "verify claude: PASS" in out
-
- def test_missing_claude_binary_returns_one(
- self, monkeypatch, capsys, _mock_verify_externals,
- ):
- _stub_httpx_responses(monkeypatch)
- monkeypatch.setattr(verify_mod, "_find_claude_binary", lambda: None)
-
- sentinel = {"called": False}
- def fake_run(*_args, **_kwargs):
- sentinel["called"] = True
- return subprocess.CompletedProcess([], returncode=0)
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- rc = verify_claude(
- model="test-model",
- base_url="https://example.com/v1",
- api_key="sk-test",
- port=None,
- timeout=None,
- )
-
- assert rc == 1
- # claude must NOT have been spawned — locating fails first.
- assert sentinel["called"] is False
- out = capsys.readouterr().out
- assert "Locating claude binary" in out
- assert "claude binary not found" in out
-
-
-class TestVerifyCodexOrchestrator:
- """End-to-end smoke for ``verify codex`` with all externals mocked."""
-
- def test_happy_path_returns_zero(
- self, monkeypatch, capsys, _mock_verify_externals,
- ):
- _stub_httpx_responses(monkeypatch)
- monkeypatch.setattr(verify_mod, "_find_codex_binary", lambda: "/x/codex")
-
- def fake_run(cmd, **kwargs): # noqa: ARG001
- return subprocess.CompletedProcess(
- cmd, returncode=0, stdout="ok\n", stderr="",
- )
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- rc = verify_codex(
- model="test-model",
- base_url="https://example.com/v1",
- api_key="sk-test",
- port=None,
- timeout=None,
- )
-
- assert rc == 0
- out = capsys.readouterr().out
- # codex skips the Anthropic probe step (only 7 total) — pin
- # the count so the test catches if the orchestrator drifts to
- # claude's 8-step shape.
- assert "[7/7]" in out
- assert "[8/8]" not in out
- assert "verify codex: PASS" in out
-
- def test_missing_codex_binary_returns_one(
- self, monkeypatch, capsys, _mock_verify_externals,
- ):
- _stub_httpx_responses(monkeypatch)
- monkeypatch.setattr(verify_mod, "_find_codex_binary", lambda: None)
-
- rc = verify_codex(
- model="test-model",
- base_url="https://example.com/v1",
- api_key="sk-test",
- port=None,
- timeout=None,
- )
-
- assert rc == 1
- out = capsys.readouterr().out
- assert "Locating codex binary" in out
- assert "codex binary not found" in out
-
-
-# ---------------------------------------------------------------------------
-# CLI handlers — credential resolution + arg forwarding
-# ---------------------------------------------------------------------------
-
-
-def _isolate_credentials(monkeypatch, *, secrets_exists: bool = False,
- secrets_content: dict | None = None) -> None:
- """Wipe credentials from the test environment.
-
- Drops every env var the verify resolver inspects and points
- ``DEFAULT_SECRETS_FILE`` at a controllable temp file. Tests
- that want to exercise specific source combinations can then
- set just the env var(s) they care about.
-
- The default ``secrets_exists=False`` makes the file appear
- missing — most "no key" tests want this. ``secrets_content``
- populates the file when ``secrets_exists=True``.
- """
- for var in (
- "OPENROUTER_API_KEY", "NVIDIA_API_KEY", "OPENAI_API_KEY",
- "ANTHROPIC_API_KEY", "OPENROUTER_BASE_URL", "NVIDIA_BASE_URL",
- "OPENAI_BASE_URL",
- ):
- monkeypatch.delenv(var, raising=False)
-
- import json as _json
- import tempfile
-
- fake_path = (
- tempfile.NamedTemporaryFile(suffix=".json", delete=False).name
- if secrets_exists
- else "/tmp/__verify_test_no_such_file_should_not_exist__.json"
- )
- if secrets_exists:
- from pathlib import Path as _Path
- _Path(fake_path).write_text(_json.dumps(secrets_content or {}))
-
- from pathlib import Path as _Path
-
- monkeypatch.setattr(
- "switchyard.cli.switchyard_cli.DEFAULT_SECRETS_FILE",
- _Path(fake_path),
- )
- # ``load_secrets`` reads from ``DEFAULT_SECRETS_FILE`` in the
- # ``server_util`` module too — patch both so the diagnostic and
- # the underlying resolver see the same picture.
- monkeypatch.setattr(
- "switchyard.server.server_util.DEFAULT_SECRETS_FILE",
- _Path(fake_path),
- )
-
-
-# ---------------------------------------------------------------------------
-# _diagnose_credential_resolution
-# ---------------------------------------------------------------------------
-
-
-class TestDiagnoseCredentialResolution:
- """The waterfall walker that powers verify's "why no key?" UX.
-
- Every test must assert (a) the resolved ``api_key`` value,
- (b) the ``key_source`` label, and (c) that ``attempts`` contains
- a row for *every* source we considered (so the no-key error
- can list them all). Together those three pin both the success
- contract (right source wins) and the failure UX (no source is
- silently skipped).
- """
-
- def _make_args(
- self,
- *,
- api_key: str | None = None,
- base_url: str | None = None,
- port: int | None = None,
- ):
- """Build a minimal ``argparse.Namespace`` matching what the
- verify CLI parser produces. ``port`` is included because
- the underlying ``resolve_config_with_secrets`` helper
- mutates it from secrets when present.
- """
- import argparse as _argparse
- return _argparse.Namespace(
- api_key=api_key, base_url=base_url, port=port,
- )
-
- def test_no_sources_returns_none_with_full_attempt_list(self, monkeypatch):
- from switchyard.cli.switchyard_cli import (
- _diagnose_credential_resolution,
- )
- _isolate_credentials(monkeypatch)
-
- api_key, _base_url, key_source, attempts = _diagnose_credential_resolution(
- self._make_args(),
- )
-
- assert api_key is None
- assert key_source is None
- # Sources verified in resolution order: --api-key, env vars, then
- # secrets.json provider sections. Pin the order so a future refactor
- # can't silently drop a source.
- labels = [a.label for a in attempts]
- assert labels == [
- "--api-key",
- "$OPENROUTER_API_KEY",
- "$NVIDIA_API_KEY",
- "$OPENAI_API_KEY",
- "$ANTHROPIC_API_KEY",
- "secrets.json[openrouter.api_key]",
- "secrets.json[nvidia.api_key]",
- ]
- # Every attempt's status must explain *why* it didn't yield a
- # key — empty / missing / not-set — so the tabulated error
- # message has something useful per row.
- for attempt in attempts:
- assert attempt.has_value is False
- assert attempt.status, (
- f"empty status for {attempt.label!r} would render as a "
- f"blank row in the user-facing error table"
- )
-
- def test_cli_api_key_wins(self, monkeypatch):
- from switchyard.cli.switchyard_cli import (
- _diagnose_credential_resolution,
- )
- _isolate_credentials(monkeypatch)
- # Plant a competing env var to verify CLI wins per the
- # waterfall order — this is the same priority the launcher
- # uses, so a regression here would be a behavior change.
- monkeypatch.setenv("OPENROUTER_API_KEY", "sk-from-env")
-
- api_key, _base_url, key_source, _ = _diagnose_credential_resolution(
- self._make_args(api_key="sk-from-cli"),
- )
-
- assert api_key == "sk-from-cli"
- assert key_source == "--api-key"
-
- def test_env_var_wins_when_no_cli(self, monkeypatch):
- from switchyard.cli.switchyard_cli import (
- _diagnose_credential_resolution,
- )
- _isolate_credentials(monkeypatch)
- monkeypatch.setenv("OPENROUTER_API_KEY", "sk-from-openrouter")
- monkeypatch.setenv("NVIDIA_API_KEY", "sk-from-nvidia")
- monkeypatch.setenv("OPENAI_API_KEY", "sk-from-openai")
-
- api_key, _, key_source, _ = _diagnose_credential_resolution(
- self._make_args(),
- )
-
- assert api_key == "sk-from-openrouter" # pragma: allowlist secret # pragma: allowlist secret
- assert key_source == "$OPENROUTER_API_KEY"
-
- def test_base_url_matches_selected_env_provider(self, monkeypatch):
- from switchyard.cli.switchyard_cli import (
- _diagnose_credential_resolution,
- )
- _isolate_credentials(monkeypatch)
- monkeypatch.setenv("NVIDIA_API_KEY", "sk-from-nvidia")
- monkeypatch.setenv("OPENROUTER_BASE_URL", "https://openrouter.test/v1")
-
- api_key, base_url, key_source, _ = _diagnose_credential_resolution(
- self._make_args(),
- )
-
- assert api_key == "sk-from-nvidia"
- assert key_source == "$NVIDIA_API_KEY"
- assert base_url == "https://inference-api.nvidia.com/v1"
-
- def test_secrets_file_wins_when_no_cli_or_env(self, monkeypatch):
- from switchyard.cli.switchyard_cli import (
- _diagnose_credential_resolution,
- )
- _isolate_credentials(
- monkeypatch,
- secrets_exists=True,
- secrets_content={
- "openrouter": {
- "api_key": "sk-from-secrets",
- "base_url": "https://from-secrets/v1",
- },
- },
- )
-
- api_key, base_url, key_source, _ = _diagnose_credential_resolution(
- self._make_args(),
- )
-
- assert api_key == "sk-from-secrets"
- assert key_source == "secrets.json[openrouter.api_key]"
- assert base_url == "https://from-secrets/v1"
-
- def test_secrets_section_missing_status(self, monkeypatch):
- """secrets.json is present but the ``openrouter`` section isn't.
- The diagnostic must distinguish "file not found" from
- "section missing" — they're different fixes.
- """
- from switchyard.cli.switchyard_cli import (
- _diagnose_credential_resolution,
- )
- _isolate_credentials(
- monkeypatch,
- secrets_exists=True,
- secrets_content={"some_other_section": {}},
- )
-
- api_key, _, _, attempts = _diagnose_credential_resolution(
- self._make_args(),
- )
- assert api_key is None
- secrets_row = next(a for a in attempts if "secrets.json" in a.label)
- assert "missing" in secrets_row.status
-
- def test_secrets_section_present_field_missing_status(self, monkeypatch):
- """``openrouter`` section exists but has no ``api_key`` field —
- another distinct failure mode requiring its own status string.
- """
- from switchyard.cli.switchyard_cli import (
- _diagnose_credential_resolution,
- )
- _isolate_credentials(
- monkeypatch,
- secrets_exists=True,
- secrets_content={"openrouter": {"base_url": "https://x/v1"}},
- )
-
- api_key, _, _, attempts = _diagnose_credential_resolution(
- self._make_args(),
- )
- assert api_key is None
- secrets_row = next(a for a in attempts if "secrets.json" in a.label)
- assert "field missing" in secrets_row.status
-
- def test_empty_env_var_reported_distinctly(self, monkeypatch):
- """An env var that's been *set* to the empty string is a
- common subtle bug (typically a shell rc that exports the
- var unconditionally). The status must say ``"empty (0
- chars)"`` rather than ``"not set"`` so the user sees the
- difference.
- """
- from switchyard.cli.switchyard_cli import (
- _diagnose_credential_resolution,
- )
- _isolate_credentials(monkeypatch)
- monkeypatch.setenv("OPENROUTER_API_KEY", "")
-
- _, _, _, attempts = _diagnose_credential_resolution(
- self._make_args(),
- )
- openrouter_row = next(a for a in attempts if a.label == "$OPENROUTER_API_KEY")
- assert "empty" in openrouter_row.status
-
- def test_set_env_var_reports_char_count(self, monkeypatch):
- """A set env var should advertise its length — useful for
- spotting truncated keys without ever exposing the secret.
- """
- from switchyard.cli.switchyard_cli import (
- _diagnose_credential_resolution,
- )
- _isolate_credentials(monkeypatch)
- monkeypatch.setenv("OPENROUTER_API_KEY", "sk-12345")
-
- _, _, _, attempts = _diagnose_credential_resolution(
- self._make_args(),
- )
- openrouter_row = next(a for a in attempts if a.label == "$OPENROUTER_API_KEY")
- # 8 chars = len("sk-12345"). The actual key value MUST NOT
- # appear in the status — leaking secrets in our own
- # diagnostic is the worst possible outcome.
- assert "8 chars" in openrouter_row.status
- assert "sk-12345" not in openrouter_row.status
-
-
-# ---------------------------------------------------------------------------
-# _format_credential_failure
-# ---------------------------------------------------------------------------
-
-
-class TestFormatCredentialFailure:
- """The tabulated user-facing error. Pin the parts that matter:
- every source label appears, each row has its status, and a
- concrete "to fix" pointer is at the bottom.
- """
-
- def test_all_attempts_appear_in_output(self):
- from switchyard.cli.switchyard_cli import (
- _CredentialAttempt,
- _format_credential_failure,
- )
- attempts = [
- _CredentialAttempt("--api-key", "not provided", False),
- _CredentialAttempt("$OPENROUTER_API_KEY", "not set", False),
- _CredentialAttempt("$OPENAI_API_KEY", "empty (0 chars)", False),
- _CredentialAttempt("secrets.json[openrouter.api_key]", "file not found", False),
- ]
-
- out = _format_credential_failure(attempts)
-
- for attempt in attempts:
- assert attempt.label in out, (
- f"missing row for {attempt.label!r} — user can't see "
- f"that source was checked"
- )
- assert attempt.status in out
- # "To fix" pointer must include both the env-var path and the
- # secrets-file path so the user has two concrete next moves.
- assert "export OPENROUTER_API_KEY" in out
- assert "secrets.json" in out
-
-
-# ---------------------------------------------------------------------------
-# CLI handlers — credential resolution + arg forwarding
-# ---------------------------------------------------------------------------
-
-
-class TestVerifyCliHandlers:
- """``_cmd_verify_*`` must surface a clear error when secrets are absent
- and forward parsed args correctly when they are present.
- """
-
- def test_missing_credentials_raises_systemexit_with_tabulated_help(
- self, monkeypatch,
- ):
- """The error must list every source we tried + a concrete "to
- fix" pointer. This is the contract that lets a fresh user
- see exactly which knob to turn instead of paging through
- docs to figure out what env var to set.
- """
- from switchyard.cli.switchyard_cli import (
- _build_parser,
- _cmd_verify,
- )
- _isolate_credentials(monkeypatch)
-
- parser = _build_parser()
- args = parser.parse_args(["verify"])
-
- with pytest.raises(SystemExit) as exc_info:
- _cmd_verify(args)
-
- msg = str(exc_info.value)
- assert "no API key resolved" in msg
- # Every source must be named in the table — silently skipping
- # any of them would leave the user guessing.
- for source in (
- "--api-key", "$OPENROUTER_API_KEY", "$NVIDIA_API_KEY",
- "$OPENAI_API_KEY", "$ANTHROPIC_API_KEY", "secrets.json",
- ):
- assert source in msg, f"missing source {source!r} in error"
- assert "To fix" in msg
-
- def test_happy_path_forwards_args_to_verify_proxy(self, monkeypatch):
- """The CLI must forward all six verify-proxy args (model /
- api_key / base_url / port / timeout / key_source) so a
- regression silently dropping any of them surfaces here.
- """
- from switchyard.cli.switchyard_cli import (
- _build_parser,
- _cmd_verify,
- )
- _isolate_credentials(monkeypatch)
- monkeypatch.setenv("OPENROUTER_API_KEY", "sk-resolved")
- monkeypatch.setenv("OPENROUTER_BASE_URL", "https://upstream/v1")
-
- captured: dict = {}
- def fake_verify_proxy(**kwargs):
- captured.update(kwargs)
- return 0
- monkeypatch.setattr(
- "switchyard.server.verify.verify_proxy",
- fake_verify_proxy,
- )
-
- parser = _build_parser()
- args = parser.parse_args([
- "verify",
- "--model", "custom-model",
- "--port", "4444",
- "--timeout", "30",
- ])
-
- with pytest.raises(SystemExit) as exc_info:
- _cmd_verify(args)
- assert exc_info.value.code == 0
-
- assert captured["model"] == "custom-model"
- assert captured["api_key"] == "sk-resolved"
- assert captured["base_url"] == "https://upstream/v1"
- assert captured["port"] == 4444
- assert captured["timeout"] == 30.0
- # Source label must be forwarded — this is what powers the
- # 401 hint in step 2. Pin the exact label so a future
- # rename of the source string is caught here, not in
- # production.
- assert captured["key_source"] == "$OPENROUTER_API_KEY"