quickthink 0.2.1__tar.gz → 0.2.2__tar.gz

{quickthink-0.2.1 → quickthink-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quickthink
-Version: 0.2.1
+Version: 0.2.2
 Summary: Compressed planning scaffold for local LLMs — latency-aware routing and structured output reliability
 Author-email: Rolando Bosch <roli@hermes-labs.ai>
 License-Expression: Apache-2.0
@@ -17,13 +17,13 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: typer>=0.12.0
-Requires-Dist: pydantic>=2.7.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.2.0; extra == "dev"
 Requires-Dist: ruff>=0.4.0; extra == "dev"
@@ -92,8 +92,8 @@ Small/local models are fast but often underperform on multi-step tasks.
 Prerequisite: install and start [Ollama](https://ollama.com/) locally.
 
 ```bash
-# 1) Before the first PyPI publication, install the current source
-python -m pip install "quickthink @ git+https://github.com/hermes-labs-ai/quickthink.git"
+# 1) Install the released package
+python -m pip install "quickthink==0.2.2"
 
 # 2) Pull one supported model
 ollama pull qwen2.5:1.5b
@@ -104,12 +104,6 @@ quickthink ask "Give me a 3-step plan to learn SQL basics" --model qwen2.5:1.5b
 
 If this command works, your local setup is ready.
 
-After `v0.2.1` has been published to PyPI, install the release instead:
-
-```bash
-python -m pip install "quickthink==0.2.1"
-```
-
 For development, clone the repository and install the editable development extras:
 
 ```bash
@@ -199,6 +193,18 @@ Show routing diagnostics:
 quickthink ask "Design a robust parser with tradeoffs and a JSON output schema" --show-route --show-plan
 ```
 
+Skip planning entirely (`direct` mode):
+
+```bash
+quickthink ask "What is the capital of France?" --mode direct
+```
+
+Inspect routing and the exact prompt(s) without calling Ollama (`--dry-run` works offline):
+
+```bash
+quickthink ask "Design a retry strategy for a flaky payments API: compare exponential backoff versus a circuit breaker, list the tradeoffs, and return a JSON schema for the config" --mode two_pass --dry-run
+```
+
 Optional continuity hint (tiny, off by default):
 
 ```bash
@@ -351,8 +357,9 @@ Test:
 PYTHONPATH=src .venv/bin/pytest -q
 ```
 
-Lint (basic syntax/import sanity):
+Lint (same commands as CI):
 ```bash
+.venv/bin/ruff check src/ tests/ scripts/
 python -m compileall src tests scripts
 ```
 
@@ -384,4 +391,6 @@ Apache-2.0
 
 ## About Hermes Labs
 
-Hermes Labs is an independent AI-reliability lab building open-source tools that catch silent failure modes in production AI. More at [hermes-labs.ai](https://hermes-labs.ai).
+[Hermes Labs](https://hermes-labs.ai) is an AI reliability engineering studio for product and engineering teams shipping production agents and LLM applications. We find the structural AI failures standard evals miss, then harden retrieval, memory, agents, and the language layers around production AI systems with runtime controls and defensible evidence.
+
+Browse the [open-source catalog](https://hermes-labs.ai/open-source) or contact [roli@hermes-labs.ai](mailto:roli@hermes-labs.ai).

{quickthink-0.2.1 → quickthink-0.2.2}/README.md

@@ -61,8 +61,8 @@ Small/local models are fast but often underperform on multi-step tasks.
 Prerequisite: install and start [Ollama](https://ollama.com/) locally.
 
 ```bash
-# 1) Before the first PyPI publication, install the current source
-python -m pip install "quickthink @ git+https://github.com/hermes-labs-ai/quickthink.git"
+# 1) Install the released package
+python -m pip install "quickthink==0.2.2"
 
 # 2) Pull one supported model
 ollama pull qwen2.5:1.5b
@@ -73,12 +73,6 @@ quickthink ask "Give me a 3-step plan to learn SQL basics" --model qwen2.5:1.5b
 
 If this command works, your local setup is ready.
 
-After `v0.2.1` has been published to PyPI, install the release instead:
-
-```bash
-python -m pip install "quickthink==0.2.1"
-```
-
 For development, clone the repository and install the editable development extras:
 
 ```bash
@@ -168,6 +162,18 @@ Show routing diagnostics:
 quickthink ask "Design a robust parser with tradeoffs and a JSON output schema" --show-route --show-plan
 ```
 
+Skip planning entirely (`direct` mode):
+
+```bash
+quickthink ask "What is the capital of France?" --mode direct
+```
+
+Inspect routing and the exact prompt(s) without calling Ollama (`--dry-run` works offline):
+
+```bash
+quickthink ask "Design a retry strategy for a flaky payments API: compare exponential backoff versus a circuit breaker, list the tradeoffs, and return a JSON schema for the config" --mode two_pass --dry-run
+```
+
 Optional continuity hint (tiny, off by default):
 
 ```bash
@@ -320,8 +326,9 @@ Test:
 PYTHONPATH=src .venv/bin/pytest -q
 ```
 
-Lint (basic syntax/import sanity):
+Lint (same commands as CI):
 ```bash
+.venv/bin/ruff check src/ tests/ scripts/
 python -m compileall src tests scripts
 ```
 
@@ -353,4 +360,6 @@ Apache-2.0
 
 ## About Hermes Labs
 
-Hermes Labs is an independent AI-reliability lab building open-source tools that catch silent failure modes in production AI. More at [hermes-labs.ai](https://hermes-labs.ai).
+[Hermes Labs](https://hermes-labs.ai) is an AI reliability engineering studio for product and engineering teams shipping production agents and LLM applications. We find the structural AI failures standard evals miss, then harden retrieval, memory, agents, and the language layers around production AI systems with runtime controls and defensible evidence.
+
+Browse the [open-source catalog](https://hermes-labs.ai/open-source) or contact [roli@hermes-labs.ai](mailto:roli@hermes-labs.ai).

{quickthink-0.2.1 → quickthink-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quickthink"
-version = "0.2.1"
+version = "0.2.2"
 description = "Compressed planning scaffold for local LLMs — latency-aware routing and structured output reliability"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -29,12 +29,12 @@ classifiers = [
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
   "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
   "httpx>=0.27.0",
   "typer>=0.12.0",
-  "pydantic>=2.7.0",
 ]
 
 [project.urls]

{quickthink-0.2.1 → quickthink-0.2.2}/src/quickthink/cli.py

@@ -4,8 +4,9 @@ import json
 from datetime import datetime, timezone
 from importlib.metadata import version as package_version
 from pathlib import Path
-from typing import Optional
+from typing import NoReturn, Optional
 
+import httpx
 import typer
 
 from .config import MODEL_PROFILES, PRESET_PROFILES, SUPPORTED_MODELS, QuickThinkConfig
@@ -14,6 +15,8 @@ from .ui_server import serve_ui
 
 app = typer.Typer(help="Compressed planning scaffold for local LLMs")
 
+MODES = ("lite", "two_pass", "direct")
+
 
 def _version_callback(value: bool) -> None:
     if value:
@@ -57,7 +60,7 @@ def ask(
     prompt: str = typer.Argument(..., help="User prompt"),
     model: str = typer.Option("qwen2.5:1.5b", help="Ollama model"),
     ollama_url: str = typer.Option("http://localhost:11434", help="Ollama base URL"),
-    mode: str = typer.Option("lite", help="Execution mode: lite or two_pass"),
+    mode: str = typer.Option("lite", help="Execution mode: lite, two_pass, or direct"),
     preset: str = typer.Option("balanced", help="Preset profile: fast, balanced, strict"),
     show_plan: bool = typer.Option(False, help="Show compressed plan in terminal output"),
     show_route: bool = typer.Option(False, help="Show routing diagnostics"),
@@ -65,9 +68,14 @@ def ask(
     bypass_short_prompts: bool = typer.Option(True, help="Skip plan stage for short prompts"),
     continuity_hint: Optional[str] = typer.Option(None, help="Optional tiny continuity hint"),
     lane_policy: str = typer.Option("default", help="Lane policy: default or strict_safe"),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Resolve routing and print the prompt(s) that would be sent to Ollama, without calling it",
+    ),
 ) -> None:
-    if mode not in {"lite", "two_pass"}:
-        raise typer.BadParameter("mode must be 'lite' or 'two_pass'")
+    if mode not in MODES:
+        raise typer.BadParameter("mode must be one of: lite, two_pass, direct")
     if preset not in PRESET_PROFILES:
         raise typer.BadParameter("preset must be one of: fast, balanced, strict")
     if lane_policy not in {"default", "strict_safe"}:
@@ -80,7 +88,21 @@ def ask(
     config.lane_policy = lane_policy
     engine = QuickThinkEngine(config)
 
-    result = engine.run(prompt)
+    if dry_run:
+        preview = engine.preview(prompt)
+        typer.echo(
+            f"[route] mode={preview.mode} bypassed={preview.bypassed} score={preview.route_score} "
+            f"plan_budget={preview.selected_plan_budget} model_calls={preview.model_calls} model={model}"
+        )
+        for stage, text in preview.prompts:
+            typer.echo(f"[prompt:{stage}]")
+            typer.echo(text)
+        return
+
+    try:
+        result = engine.run(prompt)
+    except httpx.HTTPError as exc:
+        _ollama_error(exc, ollama_url=ollama_url, model=model)
 
     if show_route:
         typer.echo(
@@ -117,6 +139,42 @@ def ask(
             )
 
 
+def _ollama_error(exc: httpx.HTTPError, *, ollama_url: str, model: str) -> NoReturn:
+    typer.echo(
+        f"error: Ollama request to {ollama_url} failed ({exc.__class__.__name__}: {exc}).\n"
+        f"Start Ollama with `ollama serve` and make sure the model is available with `ollama pull {model}`.",
+        err=True,
+    )
+    raise typer.Exit(code=2)
+
+
+def _bench_modes(
+    *,
+    prompt: str,
+    model: str,
+    ollama_url: str,
+    runs: int,
+    preset: str,
+    lane_policy: str,
+    lite_latencies: list[float],
+    two_pass_latencies: list[float],
+    direct_latencies: list[float],
+) -> None:
+    for mode, latencies in (("lite", lite_latencies), ("two_pass", two_pass_latencies), ("direct", direct_latencies)):
+        config = QuickThinkConfig.with_model_profile(model=model, ollama_url=ollama_url)
+        config.apply_preset(preset)
+        config.mode = mode
+        # Benchmark the configured mode itself: without this, prompts below the preset's
+        # bypass threshold or complexity score would silently measure the direct path under
+        # a lite/two_pass label. `strict_safe` keeps its own strict-format bypass.
+        config.bypass_short_prompts = False
+        config.adaptive_routing = False
+        config.lane_policy = lane_policy
+        engine = QuickThinkEngine(config)
+        for _ in range(runs):
+            latencies.append(engine.run(prompt).total_latency_ms)
+
+
 @app.command()
 def bench(
     prompt: str = typer.Argument(..., help="Benchmark prompt"),
@@ -134,32 +192,20 @@ def bench(
     two_pass_latencies: list[float] = []
     direct_latencies: list[float] = []
 
-    config_lite = QuickThinkConfig.with_model_profile(model=model, ollama_url=ollama_url)
-    config_lite.apply_preset(preset)
-    config_lite.mode = "lite"
-    config_lite.lane_policy = lane_policy
-    engine_lite = QuickThinkEngine(config_lite)
-    for _ in range(runs):
-        lite_latencies.append(engine_lite.run(prompt).total_latency_ms)
-
-    config_two_pass = QuickThinkConfig.with_model_profile(model=model, ollama_url=ollama_url)
-    config_two_pass.apply_preset(preset)
-    config_two_pass.mode = "two_pass"
-    config_two_pass.lane_policy = lane_policy
-    engine_two_pass = QuickThinkEngine(config_two_pass)
-    for _ in range(runs):
-        two_pass_latencies.append(engine_two_pass.run(prompt).total_latency_ms)
-
-    config_direct = QuickThinkConfig.with_model_profile(model=model, ollama_url=ollama_url)
-    config_direct.apply_preset(preset)
-    config_direct.mode = "lite"
-    config_direct.lane_policy = lane_policy
-    config_direct.bypass_short_prompts = True
-    config_direct.adaptive_routing = False
-    config_direct.bypass_char_threshold = 100_000
-    engine_direct = QuickThinkEngine(config_direct)
-    for _ in range(runs):
-        direct_latencies.append(engine_direct.run(prompt).total_latency_ms)
+    try:
+        _bench_modes(
+            prompt=prompt,
+            model=model,
+            ollama_url=ollama_url,
+            runs=runs,
+            preset=preset,
+            lane_policy=lane_policy,
+            lite_latencies=lite_latencies,
+            two_pass_latencies=two_pass_latencies,
+            direct_latencies=direct_latencies,
+        )
+    except httpx.HTTPError as exc:
+        _ollama_error(exc, ollama_url=ollama_url, model=model)
 
     avg_lite = sum(lite_latencies) / len(lite_latencies)
     avg_two_pass = sum(two_pass_latencies) / len(two_pass_latencies)

{quickthink-0.2.1 → quickthink-0.2.2}/src/quickthink/engine.py

@@ -33,23 +33,87 @@ class QuickThinkResult:
         return self.plan_latency_ms + self.answer_latency_ms
 
 
+@dataclass
+class QuickThinkPreview:
+    """Routing decision plus the prompt(s) that would be sent, produced without a model call."""
+
+    mode: str
+    bypassed: bool
+    route_score: int
+    selected_plan_budget: int
+    prompts: list[tuple[str, str]]
+    model_calls_min: int
+    model_calls_max: int
+
+    @property
+    def model_calls(self) -> str:
+        """Human-readable call count, e.g. ``"1"`` or ``"2-3"`` when a plan repair call may occur."""
+        if self.model_calls_min == self.model_calls_max:
+            return str(self.model_calls_min)
+        return f"{self.model_calls_min}-{self.model_calls_max}"
+
+
 class QuickThinkEngine:
     def __init__(self, config: QuickThinkConfig) -> None:
         self.config = config
         self.client = OllamaClient(config.ollama_url, timeout_s=config.request_timeout_s)
 
-    def run(self, prompt: str) -> QuickThinkResult:
+    def _resolve_route(self, prompt: str) -> tuple[bool, int, int]:
+        """Return (bypass, route_score, selected_budget) without contacting the model."""
         if self.config.lane_policy == "strict_safe" and infer_task_class(prompt) == "strict_format":
-            return self._run_direct(prompt=prompt, route_score=-1, selected_budget=self.config.min_plan_budget_tokens)
+            return True, -1, self.config.min_plan_budget_tokens
+        return should_bypass(prompt, self.config)
+
+    def preview(self, prompt: str) -> QuickThinkPreview:
+        """Resolve routing and build the exact prompt(s) that ``run`` would send, without calling Ollama."""
+        bypass, route_score, selected_budget = self._resolve_route(prompt)
+        if bypass or self.config.mode == "direct":
+            return QuickThinkPreview(
+                mode=self.config.mode,
+                bypassed=True,
+                route_score=route_score,
+                selected_plan_budget=selected_budget,
+                prompts=[("answer", prompt)],
+                model_calls_min=1,
+                model_calls_max=1,
+            )
+        if self.config.mode == "two_pass":
+            # The answer prompt embeds the plan returned by the first call, so it is shown as a
+            # template; an invalid first plan triggers one extra repair call before the answer.
+            prompts = [
+                ("plan", make_plan_prompt(prompt, selected_budget)),
+                ("answer-template", make_answer_prompt(prompt, "<plan from the first call>")),
+            ]
+            calls_min, calls_max = 2, 3
+        else:
+            prompts = [
+                (
+                    "plan+answer",
+                    make_inline_plan_answer_prompt(
+                        prompt,
+                        selected_budget,
+                        continuity_hint=self.config.continuity_hint,
+                        scaffold_rules=self.config.scaffold_rules,
+                    ),
+                )
+            ]
+            calls_min, calls_max = 1, 1
+        return QuickThinkPreview(
+            mode=self.config.mode,
+            bypassed=False,
+            route_score=route_score,
+            selected_plan_budget=selected_budget,
+            prompts=prompts,
+            model_calls_min=calls_min,
+            model_calls_max=calls_max,
+        )
 
-        bypass, route_score, selected_budget = should_bypass(prompt, self.config)
-        if bypass:
+    def run(self, prompt: str) -> QuickThinkResult:
+        bypass, route_score, selected_budget = self._resolve_route(prompt)
+        if bypass or self.config.mode == "direct":
             return self._run_direct(prompt=prompt, route_score=route_score, selected_budget=selected_budget)
-
         if self.config.mode == "two_pass":
             return self._run_two_pass(prompt, route_score, selected_budget)
-        if self.config.mode == "direct":
-            return self._run_direct(prompt=prompt, route_score=route_score, selected_budget=selected_budget)
         return self._run_lite(prompt, route_score, selected_budget)
 
     def _run_direct(self, prompt: str, route_score: int, selected_budget: int) -> QuickThinkResult:

{quickthink-0.2.1 → quickthink-0.2.2}/src/quickthink.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quickthink
-Version: 0.2.1
+Version: 0.2.2
 Summary: Compressed planning scaffold for local LLMs — latency-aware routing and structured output reliability
 Author-email: Rolando Bosch <roli@hermes-labs.ai>
 License-Expression: Apache-2.0
@@ -17,13 +17,13 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: typer>=0.12.0
-Requires-Dist: pydantic>=2.7.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.2.0; extra == "dev"
 Requires-Dist: ruff>=0.4.0; extra == "dev"
@@ -92,8 +92,8 @@ Small/local models are fast but often underperform on multi-step tasks.
 Prerequisite: install and start [Ollama](https://ollama.com/) locally.
 
 ```bash
-# 1) Before the first PyPI publication, install the current source
-python -m pip install "quickthink @ git+https://github.com/hermes-labs-ai/quickthink.git"
+# 1) Install the released package
+python -m pip install "quickthink==0.2.2"
 
 # 2) Pull one supported model
 ollama pull qwen2.5:1.5b
@@ -104,12 +104,6 @@ quickthink ask "Give me a 3-step plan to learn SQL basics" --model qwen2.5:1.5b
 
 If this command works, your local setup is ready.
 
-After `v0.2.1` has been published to PyPI, install the release instead:
-
-```bash
-python -m pip install "quickthink==0.2.1"
-```
-
 For development, clone the repository and install the editable development extras:
 
 ```bash
@@ -199,6 +193,18 @@ Show routing diagnostics:
 quickthink ask "Design a robust parser with tradeoffs and a JSON output schema" --show-route --show-plan
 ```
 
+Skip planning entirely (`direct` mode):
+
+```bash
+quickthink ask "What is the capital of France?" --mode direct
+```
+
+Inspect routing and the exact prompt(s) without calling Ollama (`--dry-run` works offline):
+
+```bash
+quickthink ask "Design a retry strategy for a flaky payments API: compare exponential backoff versus a circuit breaker, list the tradeoffs, and return a JSON schema for the config" --mode two_pass --dry-run
+```
+
 Optional continuity hint (tiny, off by default):
 
 ```bash
@@ -351,8 +357,9 @@ Test:
 PYTHONPATH=src .venv/bin/pytest -q
 ```
 
-Lint (basic syntax/import sanity):
+Lint (same commands as CI):
 ```bash
+.venv/bin/ruff check src/ tests/ scripts/
 python -m compileall src tests scripts
 ```
 
@@ -384,4 +391,6 @@ Apache-2.0
 
 ## About Hermes Labs
 
-Hermes Labs is an independent AI-reliability lab building open-source tools that catch silent failure modes in production AI. More at [hermes-labs.ai](https://hermes-labs.ai).
+[Hermes Labs](https://hermes-labs.ai) is an AI reliability engineering studio for product and engineering teams shipping production agents and LLM applications. We find the structural AI failures standard evals miss, then harden retrieval, memory, agents, and the language layers around production AI systems with runtime controls and defensible evidence.
+
+Browse the [open-source catalog](https://hermes-labs.ai/open-source) or contact [roli@hermes-labs.ai](mailto:roli@hermes-labs.ai).

{quickthink-0.2.1 → quickthink-0.2.2}/src/quickthink.egg-info/SOURCES.txt

@@ -18,6 +18,7 @@ src/quickthink.egg-info/entry_points.txt
 src/quickthink.egg-info/requires.txt
 src/quickthink.egg-info/top_level.txt
 tests/test_cli_lane_policy.py
+tests/test_cli_offline.py
 tests/test_cli_version.py
 tests/test_engine_lane_policy.py
 tests/test_eval_harness_safety.py

{quickthink-0.2.1 → quickthink-0.2.2}/src/quickthink.egg-info/requires.txt

@@ -1,6 +1,5 @@
 httpx>=0.27.0
 typer>=0.12.0
-pydantic>=2.7.0
 
 [dev]
 pytest>=8.2.0

quickthink-0.2.2/tests/test_cli_offline.py

@@ -0,0 +1,118 @@
+"""CLI behaviour that must work without a running Ollama server."""
+
+from typer.testing import CliRunner
+
+from quickthink.cli import app
+from quickthink.config import QuickThinkConfig
+from quickthink.engine import QuickThinkEngine
+
+# Port 9 (discard) is closed on every CI runner, so a connection is refused immediately.
+UNREACHABLE = "http://127.0.0.1:9"
+
+# Longer than the balanced preset's 120-char bypass threshold and scores >1 on the routing regexes,
+# so it takes the scaffold path instead of the direct path.
+SCAFFOLD_PROMPT = (
+    "Design a retry strategy for a flaky payments API: compare exponential backoff versus a circuit "
+    "breaker, list the tradeoffs, and return a JSON schema for the config"
+)
+
+
+def test_help_runs_without_ollama() -> None:
+    result = CliRunner().invoke(app, ["--help"])
+    assert result.exit_code == 0
+    assert "ask" in result.output
+
+
+def test_ask_accepts_direct_mode_and_dry_run_makes_no_network_call() -> None:
+    result = CliRunner().invoke(
+        app,
+        ["ask", "what is 2 + 2?", "--mode", "direct", "--ollama-url", UNREACHABLE, "--dry-run"],
+    )
+    assert result.exit_code == 0, result.output
+    assert "[route] mode=direct bypassed=True" in result.output
+    assert "model_calls=1" in result.output
+    assert "[prompt:answer]\nwhat is 2 + 2?" in result.output
+
+
+def test_dry_run_lite_shows_scaffold_prompt() -> None:
+    prompt = SCAFFOLD_PROMPT
+    result = CliRunner().invoke(app, ["ask", prompt, "--ollama-url", UNREACHABLE, "--dry-run"])
+    assert result.exit_code == 0, result.output
+    assert "[route] mode=lite bypassed=False" in result.output
+    assert "[prompt:plan+answer]" in result.output
+    assert "Generate a compact internal plan prefix" in result.output
+
+
+def test_dry_run_two_pass_lists_both_calls() -> None:
+    prompt = SCAFFOLD_PROMPT
+    result = CliRunner().invoke(
+        app, ["ask", prompt, "--mode", "two_pass", "--ollama-url", UNREACHABLE, "--dry-run"]
+    )
+    assert result.exit_code == 0, result.output
+    assert "model_calls=2-3" in result.output
+    assert "[prompt:plan]" in result.output
+    assert "[prompt:answer-template]" in result.output
+    assert "<plan from the first call>" in result.output
+
+
+def test_ask_invalid_mode_rejected() -> None:
+    result = CliRunner().invoke(app, ["ask", "hello", "--mode", "turbo"])
+    assert result.exit_code != 0
+    assert "mode must be one of: lite, two_pass, direct" in result.output
+
+
+def test_ask_reports_unreachable_ollama_cleanly() -> None:
+    result = CliRunner().invoke(app, ["ask", "hello", "--ollama-url", UNREACHABLE])
+    assert result.exit_code == 2
+    assert result.exception is None or isinstance(result.exception, SystemExit)
+    assert "error: Ollama request to http://127.0.0.1:9 failed" in result.output
+    assert "ollama serve" in result.output
+
+
+def test_engine_preview_matches_run_routing(monkeypatch) -> None:
+    cfg = QuickThinkConfig.with_model_profile("qwen2.5:1.5b")
+    cfg.mode = "lite"
+    cfg.bypass_short_prompts = False
+    cfg.adaptive_routing = False
+    engine = QuickThinkEngine(cfg)
+
+    sent: list[str] = []
+
+    def fake_generate(**kwargs):  # type: ignore[no-untyped-def]
+        sent.append(str(kwargs.get("prompt", "")))
+        return {"response": "[P]g:x;c:y;s:z;r:k\n[A]ok"}
+
+    monkeypatch.setattr(engine.client, "generate", fake_generate)
+
+    preview = engine.preview("Compare two retry strategies")
+    result = engine.run("Compare two retry strategies")
+
+    assert preview.bypassed is result.bypassed
+    assert preview.route_score == result.route_score
+    assert preview.selected_plan_budget == result.selected_plan_budget
+    assert [text for _, text in preview.prompts] == sent
+
+
+def test_bench_forces_planned_modes(monkeypatch) -> None:
+    """A short prompt must still be measured under lite and two_pass, not bypassed to direct."""
+    from quickthink import cli
+
+    seen: list[tuple[str, bool]] = []
+
+    class FakeEngine:
+        def __init__(self, config: QuickThinkConfig) -> None:
+            self.config = config
+
+        def run(self, prompt: str):  # type: ignore[no-untyped-def]
+            real = QuickThinkEngine(self.config).preview(prompt)
+            seen.append((self.config.mode, real.bypassed))
+
+            class R:
+                total_latency_ms = 1.0
+
+            return R()
+
+    monkeypatch.setattr(cli, "QuickThinkEngine", FakeEngine)
+    result = CliRunner().invoke(app, ["bench", "what is 2 + 2?", "--runs", "1"])
+    assert result.exit_code == 0, result.output
+    assert seen == [("lite", False), ("two_pass", False), ("direct", True)]