rhylthyme-cli-runner 0.2.0a0__tar.gz → 0.2.2a0__tar.gz

{rhylthyme_cli_runner-0.2.0a0/src/rhylthyme_cli_runner.egg-info → rhylthyme_cli_runner-0.2.2a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rhylthyme-cli-runner
-Version: 0.2.0a0
+Version: 0.2.2a0
 Summary: CLI runner for Rhylthyme real-time program schedules
 Home-page: https://github.com/rhylthyme/rhylthyme-cli-runner
 Author: Rhylthyme Team
@@ -197,9 +197,30 @@ rhylthyme run examples/programs/breakfast_schedule.json --environment kitchen
 rhylthyme run examples/programs/breakfast_schedule.json --no-validate
 ```
 
+### Analyze and Publish a Program
+
+Neither needs an account; both are computed by the hosted MCP server.
+
+```bash
+# Total length, critical path, resource conflicts
+rhylthyme analyze examples/programs/breakfast_schedule.json
+
+# When does each step start if breakfast is at 8:30?
+rhylthyme analyze examples/programs/breakfast_schedule.json --finish-at 8:30am
+
+# A live, shareable timeline with timers; prints the URL
+rhylthyme publish examples/programs/breakfast_schedule.json
+```
+
+`validate` checks structure only. Two steps that want the only oven at the
+same time pass validation; `analyze` reports them, and `--strict` makes that
+a non-zero exit.
+
 ### Optimize a Program
 
-Create an optimized version of a program to reduce resource contention:
+`plan` is an older stagger heuristic that reads the pre-0.2 program format; on
+programs written with `stepId` and `task` (all current examples) it writes the
+program back unchanged. Use `analyze` to find contention.
 
 ```bash
 # Optimize a program and save to new file
@@ -227,6 +248,29 @@ rhylthyme validate-environments
 rhylthyme environment-info kitchen
 ```
 
+## Claude Skill
+
+[`skills/rhylthyme`](skills/rhylthyme) is an [Agent Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
+that teaches Claude (Claude Code, the Claude apps, the Agent SDK) to turn a
+protocol, recipe or run sheet into a validated program with this CLI, check
+it for conflicts, and hand back a live timeline. It follows the layout of
+[K-Dense scientific skills](https://github.com/K-Dense-AI/claude-scientific-skills):
+a `SKILL.md` plus `references/`.
+
+```bash
+# Claude Code, for one user
+mkdir -p ~/.claude/skills
+cp -r skills/rhylthyme ~/.claude/skills/
+
+# or for one project
+mkdir -p .claude/skills && cp -r skills/rhylthyme .claude/skills/
+```
+
+Then ask, for example, "time a Western blot so imaging is at 4 pm" or "two PCR
+protocols, one thermocycler: when do I start each?". `tests/test_skill.py`
+validates every program in the skill and checks that every command it names
+exists.
+
 ## Program File Examples
 
 ### Simple Breakfast Schedule
@@ -305,6 +349,39 @@ Environment: `RHYLTHYME_TOKEN` (access token, overrides the stored session),
 `RHYLTHYME_MCP_URL` (default `https://mcp.rhylthyme.com/mcp`),
 `RHYLTHYME_SITE_URL` (default `https://www.rhylthyme.com`).
 
+### `rhylthyme mcp-test`
+
+Smoke-tests a Rhylthyme MCP server and exits 1 if any check fails. By
+default it runs the read-only checks against all five hosted endpoints
+(`/mcp`, `/kitchen/mcp`, `/lab/mcp`, `/events/mcp`, `/gym/mcp`):
+
+| Check | What it proves |
+|---|---|
+| `initialize` | server name, protocol version, tools/resources/prompts capabilities, instructions |
+| `tools` | core tools and the endpoint's one-shot tools are listed, each with a description and schema |
+| `validate-good` / `validate-bad` | a valid program passes (including a `type: "compound"` trigger); a dangling step reference is rejected with a fix hint |
+| `analyze` | makespan, critical path and wall-clock itinerary for a known program |
+| `resources` / `prompts` | schema and guides are readable, a bundled example validates, `plan_schedule` substitutes its arguments |
+| `json-accept` | clients that do not accept SSE (`*/*`, `application/json`) get JSON, not 406 |
+| `bad-requests` | unknown method gives -32601, unknown tool gives an error, never a 5xx |
+| `login-gate` | account tools refuse without a token and point at `login` |
+| `catalog` | public search returns entries that load with a URL (empty catalog = warning) |
+| `publish` (`--publish`) | `visualize_schedule` returns a URL on the right site; the page and PNG load |
+| `generate` (`--generate`) | the model-backed `import_text` returns a program that validates (needs `login`) |
+
+```bash
+rhylthyme mcp-test                         # everything read-only
+rhylthyme mcp-test -e lab --publish        # one endpoint, plus a real share
+rhylthyme mcp-test -k catalog -k tools     # only some checks
+rhylthyme mcp-test --url http://localhost:3000/mcp -e generic
+rhylthyme mcp-test --json --strict         # cron / CI: warnings fail too
+```
+
+Requests carry `mcp-test` in the User-Agent so the hosted server logs the
+errors these checks provoke without alerting anyone. The same suite is
+importable (`rhylthyme_cli_runner.remote.checks.run_suite`), and
+`RHYLTHYME_MCP_LIVE=1 pytest tests/test_mcp_checks.py` runs it live.
+
 ### `rhylthyme login` / `logout` / `whoami`
 
 `login` opens the rhylthyme.com sign-in page and receives the session on a
@@ -331,9 +408,33 @@ Runs programs with interactive terminal UI.
 - `--validate / --no-validate`: Validate before running (default: True)
 - `--auto-start`: Automatically start without manual trigger
 
+### `rhylthyme analyze`
+
+Total length, critical path, what gates each link of it, resource conflicts
+and tracks that finish early. No sign-in; nothing is published.
+
+**Options:**
+- `--finish-at TEXT`: when everything must be finished (`19:00`, `7:30pm` or ISO 8601); prints local clock times per step
+- `--start-at TEXT`: when the program starts; ignored with `--finish-at`
+- `--strict`: exit non-zero when there are resource conflicts
+- `--json`: the full analysis
+
+### `rhylthyme publish`
+
+Publishes a program file as a live timeline and prints its URL. No sign-in.
+A published timeline is reachable by anyone who has the link.
+
+**Options:**
+- `-e, --env`: `generic`, `kitchen`, `lab`, `events`, `gym` (default: from `environmentType`)
+- `-q, --quiet`: print only the URL
+- `--json`: `url`, `shareId`, `imageUrl`, `makespanSeconds`, `warnings`
+- `--open`: open it in a browser
+
 ### `rhylthyme plan`
 
-Optimizes program schedules to reduce resource contention.
+An older stagger heuristic. It reads the pre-0.2 program format and leaves
+programs written with `stepId` and `task` unchanged; use `analyze` to find
+contention and edit the triggers.
 
 **Options:**
 - `--verbose, -v`: Show detailed planning information
@@ -614,6 +715,56 @@ make test-unit                 # excludes llm
 RHYLTHYME_EVAL_LIVE=1 pytest -m llm      # one real call, opt in
 ```
 
+
+### Other models and a spending cap
+
+`--model` also accepts models served through an OpenAI-compatible API. The
+provider is picked from the model id and the key is read from the
+environment:
+
+| Model id | Provider | Key |
+|---|---|---|
+| `claude-*` | Anthropic | `ANTHROPIC_API_KEY` |
+| `deepseek-*` (e.g. `deepseek-flash`, `deepseek-v4-pro`) | api.deepseek.com | `DEEPSEEK_API_KEY` |
+| `qwen*` | Alibaba DashScope (international) | `DASHSCOPE_API_KEY` |
+| `kimi-*`, `moonshot-*` | Moonshot | `MOONSHOT_API_KEY` |
+| `glm-*` | Z.ai | `ZAI_API_KEY` |
+| anything with a slash, e.g. `deepseek/deepseek-flash` | OpenRouter | `OPENROUTER_API_KEY` |
+| any id, with `RHYLTHYME_EVAL_BASE_URL` set | that endpoint (vLLM, Ollama, ...) | `RHYLTHYME_EVAL_API_KEY`, optional for localhost |
+
+Costs come from the price table in `eval/llm.py` (DeepSeek at its peak
+rates, so estimates are upper bounds). For a model the table does not know,
+set `RHYLTHYME_EVAL_PRICE_IN` and `RHYLTHYME_EVAL_PRICE_OUT` in USD per
+million tokens.
+
+`eval/run_model_comparison.py` runs a model under a hard budget. It runs one
+gold program at a time, both prompts per program, records each program's
+cost in `eval/models/spend-ledger.json`, and stops before the next program
+could cross `--cap`. The ledger is cumulative across models and
+invocations, and the script refuses a model with no known price (it would
+be recorded as $0 and the cap would never trip).
+
+One OpenRouter key reaches OpenAI, Qwen and Meta models (ids with a vendor
+prefix). Run the cheapest first and raise the cumulative cap as you go, so
+no single model can spend the whole allowance. Reasoning models need a
+higher per-call output ceiling than the default 16,000 tokens:
+
+```bash
+export OPENROUTER_API_KEY=...
+L=eval/models/spend-ledger-openrouter.json
+python eval/run_model_comparison.py --ledger $L --model meta-llama/llama-4-maverick --cap 0.80 --first-guess 0.05
+python eval/run_model_comparison.py --ledger $L --model qwen/qwen3.8-flash --cap 2.00 --first-guess 0.08 --max-tokens 64000
+python eval/run_model_comparison.py --ledger $L --model openai/gpt-5.6-luna --cap 4.50 --first-guess 0.15 --max-tokens 64000
+python eval/compare_models.py
+```
+
+```bash
+export DEEPSEEK_API_KEY=...
+python eval/run_model_comparison.py --model deepseek-flash --cap 6.70 --dry-run
+python eval/run_model_comparison.py --model deepseek-flash --cap 6.70
+python eval/compare_models.py        # like-for-like table across every model run so far
+```
+
 ## Development
 
 1. Clone the repository

{rhylthyme_cli_runner-0.2.0a0 → rhylthyme_cli_runner-0.2.2a0}/README.md

@@ -137,9 +137,30 @@ rhylthyme run examples/programs/breakfast_schedule.json --environment kitchen
 rhylthyme run examples/programs/breakfast_schedule.json --no-validate
 ```
 
+### Analyze and Publish a Program
+
+Neither needs an account; both are computed by the hosted MCP server.
+
+```bash
+# Total length, critical path, resource conflicts
+rhylthyme analyze examples/programs/breakfast_schedule.json
+
+# When does each step start if breakfast is at 8:30?
+rhylthyme analyze examples/programs/breakfast_schedule.json --finish-at 8:30am
+
+# A live, shareable timeline with timers; prints the URL
+rhylthyme publish examples/programs/breakfast_schedule.json
+```
+
+`validate` checks structure only. Two steps that want the only oven at the
+same time pass validation; `analyze` reports them, and `--strict` makes that
+a non-zero exit.
+
 ### Optimize a Program
 
-Create an optimized version of a program to reduce resource contention:
+`plan` is an older stagger heuristic that reads the pre-0.2 program format; on
+programs written with `stepId` and `task` (all current examples) it writes the
+program back unchanged. Use `analyze` to find contention.
 
 ```bash
 # Optimize a program and save to new file
@@ -167,6 +188,29 @@ rhylthyme validate-environments
 rhylthyme environment-info kitchen
 ```
 
+## Claude Skill
+
+[`skills/rhylthyme`](skills/rhylthyme) is an [Agent Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
+that teaches Claude (Claude Code, the Claude apps, the Agent SDK) to turn a
+protocol, recipe or run sheet into a validated program with this CLI, check
+it for conflicts, and hand back a live timeline. It follows the layout of
+[K-Dense scientific skills](https://github.com/K-Dense-AI/claude-scientific-skills):
+a `SKILL.md` plus `references/`.
+
+```bash
+# Claude Code, for one user
+mkdir -p ~/.claude/skills
+cp -r skills/rhylthyme ~/.claude/skills/
+
+# or for one project
+mkdir -p .claude/skills && cp -r skills/rhylthyme .claude/skills/
+```
+
+Then ask, for example, "time a Western blot so imaging is at 4 pm" or "two PCR
+protocols, one thermocycler: when do I start each?". `tests/test_skill.py`
+validates every program in the skill and checks that every command it names
+exists.
+
 ## Program File Examples
 
 ### Simple Breakfast Schedule
@@ -245,6 +289,39 @@ Environment: `RHYLTHYME_TOKEN` (access token, overrides the stored session),
 `RHYLTHYME_MCP_URL` (default `https://mcp.rhylthyme.com/mcp`),
 `RHYLTHYME_SITE_URL` (default `https://www.rhylthyme.com`).
 
+### `rhylthyme mcp-test`
+
+Smoke-tests a Rhylthyme MCP server and exits 1 if any check fails. By
+default it runs the read-only checks against all five hosted endpoints
+(`/mcp`, `/kitchen/mcp`, `/lab/mcp`, `/events/mcp`, `/gym/mcp`):
+
+| Check | What it proves |
+|---|---|
+| `initialize` | server name, protocol version, tools/resources/prompts capabilities, instructions |
+| `tools` | core tools and the endpoint's one-shot tools are listed, each with a description and schema |
+| `validate-good` / `validate-bad` | a valid program passes (including a `type: "compound"` trigger); a dangling step reference is rejected with a fix hint |
+| `analyze` | makespan, critical path and wall-clock itinerary for a known program |
+| `resources` / `prompts` | schema and guides are readable, a bundled example validates, `plan_schedule` substitutes its arguments |
+| `json-accept` | clients that do not accept SSE (`*/*`, `application/json`) get JSON, not 406 |
+| `bad-requests` | unknown method gives -32601, unknown tool gives an error, never a 5xx |
+| `login-gate` | account tools refuse without a token and point at `login` |
+| `catalog` | public search returns entries that load with a URL (empty catalog = warning) |
+| `publish` (`--publish`) | `visualize_schedule` returns a URL on the right site; the page and PNG load |
+| `generate` (`--generate`) | the model-backed `import_text` returns a program that validates (needs `login`) |
+
+```bash
+rhylthyme mcp-test                         # everything read-only
+rhylthyme mcp-test -e lab --publish        # one endpoint, plus a real share
+rhylthyme mcp-test -k catalog -k tools     # only some checks
+rhylthyme mcp-test --url http://localhost:3000/mcp -e generic
+rhylthyme mcp-test --json --strict         # cron / CI: warnings fail too
+```
+
+Requests carry `mcp-test` in the User-Agent so the hosted server logs the
+errors these checks provoke without alerting anyone. The same suite is
+importable (`rhylthyme_cli_runner.remote.checks.run_suite`), and
+`RHYLTHYME_MCP_LIVE=1 pytest tests/test_mcp_checks.py` runs it live.
+
 ### `rhylthyme login` / `logout` / `whoami`
 
 `login` opens the rhylthyme.com sign-in page and receives the session on a
@@ -271,9 +348,33 @@ Runs programs with interactive terminal UI.
 - `--validate / --no-validate`: Validate before running (default: True)
 - `--auto-start`: Automatically start without manual trigger
 
+### `rhylthyme analyze`
+
+Total length, critical path, what gates each link of it, resource conflicts
+and tracks that finish early. No sign-in; nothing is published.
+
+**Options:**
+- `--finish-at TEXT`: when everything must be finished (`19:00`, `7:30pm` or ISO 8601); prints local clock times per step
+- `--start-at TEXT`: when the program starts; ignored with `--finish-at`
+- `--strict`: exit non-zero when there are resource conflicts
+- `--json`: the full analysis
+
+### `rhylthyme publish`
+
+Publishes a program file as a live timeline and prints its URL. No sign-in.
+A published timeline is reachable by anyone who has the link.
+
+**Options:**
+- `-e, --env`: `generic`, `kitchen`, `lab`, `events`, `gym` (default: from `environmentType`)
+- `-q, --quiet`: print only the URL
+- `--json`: `url`, `shareId`, `imageUrl`, `makespanSeconds`, `warnings`
+- `--open`: open it in a browser
+
 ### `rhylthyme plan`
 
-Optimizes program schedules to reduce resource contention.
+An older stagger heuristic. It reads the pre-0.2 program format and leaves
+programs written with `stepId` and `task` unchanged; use `analyze` to find
+contention and edit the triggers.
 
 **Options:**
 - `--verbose, -v`: Show detailed planning information
@@ -554,6 +655,56 @@ make test-unit                 # excludes llm
 RHYLTHYME_EVAL_LIVE=1 pytest -m llm      # one real call, opt in
 ```
 
+
+### Other models and a spending cap
+
+`--model` also accepts models served through an OpenAI-compatible API. The
+provider is picked from the model id and the key is read from the
+environment:
+
+| Model id | Provider | Key |
+|---|---|---|
+| `claude-*` | Anthropic | `ANTHROPIC_API_KEY` |
+| `deepseek-*` (e.g. `deepseek-flash`, `deepseek-v4-pro`) | api.deepseek.com | `DEEPSEEK_API_KEY` |
+| `qwen*` | Alibaba DashScope (international) | `DASHSCOPE_API_KEY` |
+| `kimi-*`, `moonshot-*` | Moonshot | `MOONSHOT_API_KEY` |
+| `glm-*` | Z.ai | `ZAI_API_KEY` |
+| anything with a slash, e.g. `deepseek/deepseek-flash` | OpenRouter | `OPENROUTER_API_KEY` |
+| any id, with `RHYLTHYME_EVAL_BASE_URL` set | that endpoint (vLLM, Ollama, ...) | `RHYLTHYME_EVAL_API_KEY`, optional for localhost |
+
+Costs come from the price table in `eval/llm.py` (DeepSeek at its peak
+rates, so estimates are upper bounds). For a model the table does not know,
+set `RHYLTHYME_EVAL_PRICE_IN` and `RHYLTHYME_EVAL_PRICE_OUT` in USD per
+million tokens.
+
+`eval/run_model_comparison.py` runs a model under a hard budget. It runs one
+gold program at a time, both prompts per program, records each program's
+cost in `eval/models/spend-ledger.json`, and stops before the next program
+could cross `--cap`. The ledger is cumulative across models and
+invocations, and the script refuses a model with no known price (it would
+be recorded as $0 and the cap would never trip).
+
+One OpenRouter key reaches OpenAI, Qwen and Meta models (ids with a vendor
+prefix). Run the cheapest first and raise the cumulative cap as you go, so
+no single model can spend the whole allowance. Reasoning models need a
+higher per-call output ceiling than the default 16,000 tokens:
+
+```bash
+export OPENROUTER_API_KEY=...
+L=eval/models/spend-ledger-openrouter.json
+python eval/run_model_comparison.py --ledger $L --model meta-llama/llama-4-maverick --cap 0.80 --first-guess 0.05
+python eval/run_model_comparison.py --ledger $L --model qwen/qwen3.8-flash --cap 2.00 --first-guess 0.08 --max-tokens 64000
+python eval/run_model_comparison.py --ledger $L --model openai/gpt-5.6-luna --cap 4.50 --first-guess 0.15 --max-tokens 64000
+python eval/compare_models.py
+```
+
+```bash
+export DEEPSEEK_API_KEY=...
+python eval/run_model_comparison.py --model deepseek-flash --cap 6.70 --dry-run
+python eval/run_model_comparison.py --model deepseek-flash --cap 6.70
+python eval/compare_models.py        # like-for-like table across every model run so far
+```
+
 ## Development
 
 1. Clone the repository

{rhylthyme_cli_runner-0.2.0a0 → rhylthyme_cli_runner-0.2.2a0}/setup.py

@@ -19,7 +19,7 @@ def read_readme():
 
 setup(
     name="rhylthyme-cli-runner",
-    version="0.2.0a0",
+    version="0.2.2a0",
     description="CLI runner for Rhylthyme real-time program schedules",
     long_description=read_readme(),
     long_description_content_type="text/markdown",

{rhylthyme_cli_runner-0.2.0a0 → rhylthyme_cli_runner-0.2.2a0}/src/rhylthyme_cli_runner/__init__.py

@@ -6,7 +6,7 @@ This package provides the command-line interface for running and validating
 Rhylthyme real-time program schedules.
 """
 
-__version__ = "0.2.0a0"
+__version__ = "0.2.2a0"
 __author__ = "Rhylthyme Team"
 __description__ = "CLI runner for Rhylthyme real-time program schedules"
 

{rhylthyme_cli_runner-0.2.0a0 → rhylthyme_cli_runner-0.2.2a0}/src/rhylthyme_cli_runner/eval/cli.py

@@ -321,7 +321,10 @@ def _live(
     if fake_client_path:
         with open(fake_client_path, "r", encoding="utf-8") as handle:
             fake_responses = json.load(handle)
-    client = make_client(fake_responses)
+    try:
+        client = make_client(fake_responses, model=model)
+    except RuntimeError as exc:
+        raise click.UsageError(str(exc))
 
     gold_set = _load_gold(gold_dir)
     out_root = Path(out_dir)

{rhylthyme_cli_runner-0.2.0a0 → rhylthyme_cli_runner-0.2.2a0}/src/rhylthyme_cli_runner/eval/llm.py

@@ -16,7 +16,12 @@ Plus a small price table so runs can log an estimated cost.
 
 from __future__ import annotations
 
+import json
+import os
 import threading
+import time
+import urllib.error
+import urllib.request
 from dataclasses import dataclass, field
 from typing import Any, Dict, List, Mapping, Optional, Protocol, Sequence, Union
 
@@ -38,9 +43,42 @@ PRICES_PER_MTOK: Dict[str, tuple] = {
     "claude-sonnet-5": (2.00, 10.00),
     "claude-sonnet-4-6": (3.00, 15.00),
     "claude-haiku-4-5": (1.00, 5.00),
+    # DeepSeek, from api-docs.deepseek.com/quick_start/pricing on 2026-09-19.
+    # PEAK rates (off-peak is half), so a budget computed from these is an
+    # upper bound. Cache-miss input price: the harness does not rely on
+    # provider-side prompt caching.
+    "deepseek-flash": (0.30, 1.20),
+    "deepseek-v4-pro": (1.32, 3.96),
+    # Gemini paid tier, from ai.google.dev/gemini-api/docs/pricing on
+    # 2026-09-19. Output prices include thinking tokens.
+    "gemini-3.5-flash-lite": (0.30, 2.50),
+    "gemini-3.1-flash-lite": (0.25, 1.50),
+    "gemini-2.5-flash-lite": (0.10, 0.40),
+    # OpenAI list price (developers.openai.com/api/docs/pricing, 2026-09-19).
+    "gpt-5.6-luna": (0.20, 1.20),
+    # Through OpenRouter, from its public /api/v1/models listing on
+    # 2026-09-19. Reasoning tokens are billed as output.
+    "openai/gpt-5.6-luna": (0.20, 1.20),
+    "qwen/qwen3.8-flash": (0.15, 0.47),
+    "qwen/qwen3-235b-a22b-2507": (0.0875, 0.35),
+    "meta-llama/llama-4-maverick": (0.188, 0.652),
+    "meta-llama/llama-4-scout": (0.10, 0.30),
+    "meta-llama/llama-3.3-70b-instruct": (0.10, 0.32),
 }
 
 
+def _env_price() -> Optional[tuple]:
+    """RHYLTHYME_EVAL_PRICE_IN / _OUT (USD per million tokens) price a model
+    the table does not know, e.g. one reached through an aggregator."""
+    try:
+        return (
+            float(os.environ["RHYLTHYME_EVAL_PRICE_IN"]),
+            float(os.environ["RHYLTHYME_EVAL_PRICE_OUT"]),
+        )
+    except (KeyError, ValueError):
+        return None
+
+
 def price_for(model: str) -> Optional[tuple]:
     """``(input, output)`` USD per million tokens, or ``None`` if unknown."""
     if model in PRICES_PER_MTOK:
@@ -49,7 +87,7 @@ def price_for(model: str) -> Optional[tuple]:
     for key in PRICES_PER_MTOK:
         if model.startswith(key) and (best is None or len(key) > len(best)):
             best = key
-    return PRICES_PER_MTOK[best] if best else None
+    return PRICES_PER_MTOK[best] if best else _env_price()
 
 
 def estimate_cost(model: str, input_tokens: int, output_tokens: int) -> Optional[float]:
@@ -165,6 +203,143 @@ class AnthropicClient:
         )
 
 
+# Providers that speak the OpenAI chat-completions format. A model id picks
+# its provider by prefix; an id with a slash ("deepseek/deepseek-flash") goes
+# to OpenRouter, which fronts most of them under one key. RHYLTHYME_EVAL_BASE_URL
+# and RHYLTHYME_EVAL_API_KEY override both, for any other compatible endpoint
+# (a local vLLM or Ollama server included).
+OPENAI_COMPAT_PROVIDERS = [
+    ("deepseek-", "https://api.deepseek.com", "DEEPSEEK_API_KEY"),
+    (
+        "qwen",
+        "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
+        "DASHSCOPE_API_KEY",
+    ),
+    ("kimi-", "https://api.moonshot.ai/v1", "MOONSHOT_API_KEY"),
+    ("moonshot-", "https://api.moonshot.ai/v1", "MOONSHOT_API_KEY"),
+    ("glm-", "https://api.z.ai/api/paas/v4", "ZAI_API_KEY"),
+    (
+        "gemini-",
+        "https://generativelanguage.googleapis.com/v1beta/openai",
+        "GEMINI_API_KEY",
+    ),
+    ("gpt-", "https://api.openai.com/v1", "OPENAI_API_KEY"),
+]
+OPENROUTER = ("https://openrouter.ai/api/v1", "OPENROUTER_API_KEY")
+
+
+def provider_for(model: str) -> Optional[tuple]:
+    """``(base_url, api_key_env)`` for an OpenAI-compatible model, else None."""
+    if os.environ.get("RHYLTHYME_EVAL_BASE_URL"):
+        return (
+            os.environ["RHYLTHYME_EVAL_BASE_URL"].rstrip("/"),
+            "RHYLTHYME_EVAL_API_KEY",
+        )
+    if model.startswith("claude-"):
+        return None
+    if "/" in model:
+        return OPENROUTER
+    for prefix, base_url, key_env in OPENAI_COMPAT_PROVIDERS:
+        if model.startswith(prefix):
+            return (base_url, key_env)
+    return None
+
+
+class OpenAICompatClient:
+    """Chat-completions client for OpenAI-compatible endpoints. Standard
+    library only. Retries on 429/5xx; never on a timeout, because a request
+    that timed out here may still have been billed there."""
+
+    RETRY_STATUS = (429, 500, 502, 503, 529)
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: Optional[str],
+        *,
+        timeout: float = 900.0,
+        retries: int = 3,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        # RHYLTHYME_EVAL_TIMEOUT (seconds) overrides the per-call timeout.
+        self.timeout = float(os.environ.get("RHYLTHYME_EVAL_TIMEOUT") or timeout)
+        self.retries = retries
+
+    def complete(
+        self,
+        messages: Sequence[Message],
+        *,
+        system: Optional[str] = None,
+        model: str,
+        max_tokens: int,
+    ) -> Completion:
+        chat: List[Dict[str, Any]] = (
+            [{"role": "system", "content": system}] if system else []
+        )
+        chat += [{"role": m["role"], "content": m["content"]} for m in messages]
+        body = json.dumps(
+            {
+                "model": model,
+                "messages": chat,
+                # OpenAI's current models reject `max_tokens`.
+                (
+                    "max_completion_tokens"
+                    if "api.openai.com" in self.base_url
+                    else "max_tokens"
+                ): max_tokens,
+                "stream": False,
+            }
+        ).encode("utf-8")
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        for attempt in range(self.retries + 1):
+            req = urllib.request.Request(
+                f"{self.base_url}/chat/completions",
+                data=body,
+                headers=headers,
+                method="POST",
+            )
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    data = json.loads(resp.read().decode("utf-8"))
+                break
+            except urllib.error.HTTPError as exc:
+                detail = exc.read().decode("utf-8", "replace")[:300]
+                if exc.code in self.RETRY_STATUS and attempt < self.retries:
+                    time.sleep(2.0 * (attempt + 1))
+                    continue
+                raise RuntimeError(
+                    f"{self.base_url} returned HTTP {exc.code}: {detail}"
+                ) from exc
+            except (TimeoutError, urllib.error.URLError) as exc:
+                # A stalled provider. Retrying can double-bill a request that
+                # did complete remotely, so it is opt-in (cheap models only).
+                if (
+                    os.environ.get("RHYLTHYME_EVAL_RETRY_TIMEOUTS")
+                    and attempt < self.retries
+                ):
+                    continue
+                raise RuntimeError(
+                    f"{self.base_url} did not answer within {self.timeout:.0f}s: {exc}"
+                ) from exc
+        choice = (data.get("choices") or [{}])[0]
+        usage = data.get("usage") or {}
+        finish = choice.get("finish_reason")
+        return Completion(
+            text=str((choice.get("message") or {}).get("content") or ""),
+            input_tokens=int(usage.get("prompt_tokens") or 0),
+            # Reasoning tokens are billed as output and are inside this count.
+            output_tokens=int(usage.get("completion_tokens") or 0),
+            model=str(data.get("model") or model),
+            stop_reason={"stop": "end_turn", "length": "max_tokens"}.get(
+                finish, finish
+            ),
+            raw=data,
+        )
+
+
 CannedResponse = Union[str, Completion]
 
 
@@ -252,8 +427,20 @@ class FakeClient:
         )
 
 
-def make_client(fake_responses: Optional[Any] = None) -> Client:
-    """Build the client the CLI uses: a fake when canned responses are given."""
+def make_client(
+    fake_responses: Optional[Any] = None, model: Optional[str] = None
+) -> Client:
+    """Build the client the CLI uses: a fake when canned responses are given,
+    otherwise the provider the model id belongs to (Anthropic by default)."""
     if fake_responses is not None:
         return FakeClient(fake_responses)
-    return AnthropicClient()
+    provider = provider_for(model or "")
+    if provider is None:
+        return AnthropicClient()
+    base_url, key_env = provider
+    api_key = os.environ.get(key_env)
+    if not api_key and "localhost" not in base_url and "127.0.0.1" not in base_url:
+        raise RuntimeError(
+            f"Model {model!r} is served by {base_url}; set {key_env} to use it."
+        )
+    return OpenAICompatClient(base_url, api_key)