thinkless 0.2.0__tar.gz → 0.3.0__tar.gz

{thinkless-0.2.0 → thinkless-0.3.0}/CHANGELOG.md

@@ -6,6 +6,41 @@ All notable changes are recorded here. The format follows
 
 ## Unreleased
 
+## 0.3.0 - 2026-09-25
+
+Shadow mode, framework adapters, limits, a decision server and MCP tools.
+
+### Added
+
+- Shadow mode (`thinkless.shadow`): run a candidate engine next to existing
+  decision code without changing what it returns, log both answers, and
+  report agreement with a 95% interval, the share settled without an LLM,
+  cost and latency on both sides, thresholds fitted on production traffic,
+  and a verdict per question (`thinkless shadow report`). Disagreements
+  export as labeling rows (`thinkless shadow export`). The same class audits
+  a live engine against an LLM.
+- Framework adapters (`thinkless.integrations`): a LangGraph router, decision
+  node and async decision node; OpenAI Agents SDK input guardrails, tool input
+  guardrails and `route_agent`; and framework-neutral `Router`, `route` and
+  `gate`, tested with LangChain tools and Pydantic AI. Extras `langgraph` and
+  `openai-agents`.
+- Engine deadlines (`deadline_ms` on the engine and per call), spend limits
+  (`SpendLimit`, lifetime or rolling window) and per-run caps
+  (`engine.run(..., max_cost_usd=...)`). Skipped providers are recorded with
+  reason `deadline` or `spend_limit`.
+- A decision server (`thinkless serve`, `thinkless.server.app.create_app`)
+  with `/v1/decide` and a System One compatible `/v1/systemone`, so another
+  engine's `SystemOne` provider, or TypeSafe's SDK, can use it. Extra
+  `server`.
+- MCP tools (`thinkless mcp`, `thinkless.server.mcp.create_mcp_server`): one
+  `decide_<question>` tool per registered question. Extra `mcp`.
+- `thinkless trace export` turns traced decisions into labeling rows, and
+  `thinkless trace drift` compares two periods and exits with 1 when a
+  question drifted.
+- `question_from_spec` rebuilds a question from its spec.
+- Docs: an integrations section, a migration guide, shadow mode, serving,
+  a pilot playbook and a FAQ, published to GitHub Pages by a new workflow.
+
 ## 0.2.0 - 2026-09-25
 
 First release on PyPI.

{thinkless-0.2.0 → thinkless-0.3.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: thinkless
-Version: 0.2.0
+Version: 0.3.0
 Summary: The decision plane for AI agents. Rules and small calibrated models make the routine decisions, the LLM is reserved for the steps that need thought, and every step is traced.
 Project-URL: Homepage, https://github.com/inboxpraveen/ThinkLess
-Project-URL: Documentation, https://github.com/inboxpraveen/ThinkLess/tree/main/docs
+Project-URL: Documentation, https://inboxpraveen.github.io/ThinkLess/
 Project-URL: Repository, https://github.com/inboxpraveen/ThinkLess
 Project-URL: Issues, https://github.com/inboxpraveen/ThinkLess/issues
 Project-URL: Changelog, https://github.com/inboxpraveen/ThinkLess/blob/main/CHANGELOG.md
@@ -34,8 +34,12 @@ Provides-Extra: all
 Requires-Dist: accelerate>=1.0; extra == 'all'
 Requires-Dist: anthropic>=1.0; extra == 'all'
 Requires-Dist: datasets>=3.0; extra == 'all'
+Requires-Dist: fastapi>=0.115; extra == 'all'
 Requires-Dist: gliner2[local]<3,>=2.0; extra == 'all'
+Requires-Dist: langgraph>=1.0; extra == 'all'
 Requires-Dist: laya<0.4,>=0.3.20; extra == 'all'
+Requires-Dist: mcp>=1.10; extra == 'all'
+Requires-Dist: openai-agents>=0.22; extra == 'all'
 Requires-Dist: openai>=2.0; extra == 'all'
 Requires-Dist: opentelemetry-api>=1.25; extra == 'all'
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25; extra == 'all'
@@ -44,14 +48,20 @@ Requires-Dist: protobuf>=4.25; extra == 'all'
 Requires-Dist: sentencepiece>=0.2; extra == 'all'
 Requires-Dist: torch>=2.1; extra == 'all'
 Requires-Dist: transformers<5,>=4.48; extra == 'all'
+Requires-Dist: uvicorn>=0.30; extra == 'all'
 Provides-Extra: anthropic
 Requires-Dist: anthropic>=1.0; extra == 'anthropic'
 Provides-Extra: bench
 Requires-Dist: datasets>=3.0; extra == 'bench'
 Provides-Extra: dev
+Requires-Dist: fastapi>=0.115; extra == 'dev'
+Requires-Dist: langgraph>=1.0; extra == 'dev'
+Requires-Dist: mcp>=1.10; extra == 'dev'
 Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
 Requires-Dist: mkdocstrings[python]>=0.26; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: openai-agents>=0.22; extra == 'dev'
+Requires-Dist: pydantic-ai-slim>=1.0; extra == 'dev'
 Requires-Dist: pytest-cov>=5; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
@@ -61,6 +71,8 @@ Requires-Dist: gliner2[local]<3,>=2.0; extra == 'gliner'
 Requires-Dist: protobuf>=4.25; extra == 'gliner'
 Requires-Dist: sentencepiece>=0.2; extra == 'gliner'
 Requires-Dist: transformers<5,>=4.48; extra == 'gliner'
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=1.0; extra == 'langgraph'
 Provides-Extra: laya
 Requires-Dist: laya<0.4,>=0.3.20; extra == 'laya'
 Requires-Dist: transformers<5,>=4.48; extra == 'laya'
@@ -76,12 +88,19 @@ Provides-Extra: local-llm
 Requires-Dist: accelerate>=1.0; extra == 'local-llm'
 Requires-Dist: torch>=2.1; extra == 'local-llm'
 Requires-Dist: transformers<5,>=4.48; extra == 'local-llm'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.10; extra == 'mcp'
 Provides-Extra: openai
 Requires-Dist: openai>=2.0; extra == 'openai'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.22; extra == 'openai-agents'
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.25; extra == 'otel'
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25; extra == 'otel'
 Requires-Dist: opentelemetry-sdk>=1.25; extra == 'otel'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.115; extra == 'server'
+Requires-Dist: uvicorn>=0.30; extra == 'server'
 Description-Content-Type: text/markdown
 
 <h1 align="center">ThinkLess</h1>
@@ -229,6 +248,51 @@ No GPU? `pip install thinkless` and run
 [`examples/01_rules_only.py`](https://github.com/inboxpraveen/ThinkLess/blob/main/examples/01_rules_only.py): the API, the cascade
 and the traces with no model downloads.
 
+## Use it in your agent
+
+ThinkLess sits inside the framework you already use, at the points where the
+agent decides something: which path to take, whether an input is safe,
+whether a tool call is inside policy. Uncertain decisions go to the code you
+run today, so nothing gets worse while the routine ones get cheaper.
+
+```python
+from thinkless.integrations.langgraph import router
+
+intent = router(engine, INTENT, {"order_status": "tracking", "refund": "refunds"},
+                default="agent")          # your existing LLM node
+builder.add_conditional_edges(START, intent, intent.destinations)
+```
+
+- [LangGraph](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/integrations/langgraph.md):
+  routers, decision nodes and gated tools.
+- [OpenAI Agents SDK](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/integrations/openai-agents.md):
+  input guardrails, tool guardrails and routing to a specialist agent.
+- [Any framework](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/integrations/any-framework.md):
+  `route` and `gate` for Pydantic AI, a hand-written loop, or anything else.
+
+Before switching anything, measure it. Shadow mode runs ThinkLess next to your
+current code on live traffic and reports, per decision, the agreement with a
+confidence interval and what it would save:
+
+```python
+from thinkless.shadow import Shadow
+
+shadow = Shadow(engine, log="shadow/intent.jsonl", sample=0.2)
+
+@shadow.watch(INTENT, cost_usd=0.0004)    # today's cost per call
+def classify(message: str) -> str:
+    ...                                    # unchanged, and still what users get
+```
+
+```bash
+thinkless shadow report shadow/intent.jsonl --volume 2000000
+```
+
+The [migration guide](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/migration.md)
+walks through it, and the [FAQ](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/faq.md)
+covers the common questions. To share one engine across services, run it as
+a [decision server or MCP tools](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/serving.md).
+
 ## Try the demo agent
 
 A complete customer support agent ships with the package: a mock store with
@@ -299,7 +363,15 @@ Writing your own provider is one class. [Providers](https://github.com/inboxprav
 
 ## Documentation
 
-- [Getting started](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/getting-started.md)
+- [Getting started](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/getting-started.md),
+  [installation](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/installation.md)
+- Use it in your agent: [overview](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/integrations/index.md),
+  [LangGraph](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/integrations/langgraph.md),
+  [OpenAI Agents SDK](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/integrations/openai-agents.md),
+  [any framework](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/integrations/any-framework.md),
+  [migration](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/migration.md),
+  [shadow mode](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/shadow-mode.md),
+  [FAQ](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/faq.md)
 - Concepts: [the four planes](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/concepts/planes.md),
   [questions](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/concepts/questions.md),
   [confidence](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/concepts/confidence.md),
@@ -310,16 +382,19 @@ Writing your own provider is one class. [Providers](https://github.com/inboxprav
   [providers](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/providers.md),
   [LLM backends](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/llm-backends.md),
   [production](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/production.md),
+  [serving](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/serving.md),
+  [running a pilot](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/pilot.md),
   [troubleshooting](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/troubleshooting.md)
 - [Benchmarks](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/benchmarks.md), [CLI reference](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/reference/cli.md),
   [Python API](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/reference/api.md), [roadmap](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/roadmap.md)
 
 ## Status
 
-ThinkLess is at 0.1: the core API (questions, the engine, decisions and
-traces) is meant to stay stable, and providers and benchmarks will grow.
-Next up are shadow mode, calibration from traces, calibrated LLM confidence
-from log probabilities, and live Jev runs. See the [roadmap](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/roadmap.md).
+ThinkLess is pre-1.0: the core API (questions, the engine, decisions and
+traces) is meant to stay stable, and providers, adapters and benchmarks will
+grow. Next up are a neutral benchmark for decision models, cross-request
+batching in the server, calibrated LLM confidence from log probabilities, and
+live Jev runs. See the [roadmap](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/roadmap.md).
 
 ## Contributing
 

{thinkless-0.2.0 → thinkless-0.3.0}/README.md

@@ -143,6 +143,51 @@ No GPU? `pip install thinkless` and run
 [`examples/01_rules_only.py`](https://github.com/inboxpraveen/ThinkLess/blob/main/examples/01_rules_only.py): the API, the cascade
 and the traces with no model downloads.
 
+## Use it in your agent
+
+ThinkLess sits inside the framework you already use, at the points where the
+agent decides something: which path to take, whether an input is safe,
+whether a tool call is inside policy. Uncertain decisions go to the code you
+run today, so nothing gets worse while the routine ones get cheaper.
+
+```python
+from thinkless.integrations.langgraph import router
+
+intent = router(engine, INTENT, {"order_status": "tracking", "refund": "refunds"},
+                default="agent")          # your existing LLM node
+builder.add_conditional_edges(START, intent, intent.destinations)
+```
+
+- [LangGraph](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/integrations/langgraph.md):
+  routers, decision nodes and gated tools.
+- [OpenAI Agents SDK](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/integrations/openai-agents.md):
+  input guardrails, tool guardrails and routing to a specialist agent.
+- [Any framework](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/integrations/any-framework.md):
+  `route` and `gate` for Pydantic AI, a hand-written loop, or anything else.
+
+Before switching anything, measure it. Shadow mode runs ThinkLess next to your
+current code on live traffic and reports, per decision, the agreement with a
+confidence interval and what it would save:
+
+```python
+from thinkless.shadow import Shadow
+
+shadow = Shadow(engine, log="shadow/intent.jsonl", sample=0.2)
+
+@shadow.watch(INTENT, cost_usd=0.0004)    # today's cost per call
+def classify(message: str) -> str:
+    ...                                    # unchanged, and still what users get
+```
+
+```bash
+thinkless shadow report shadow/intent.jsonl --volume 2000000
+```
+
+The [migration guide](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/migration.md)
+walks through it, and the [FAQ](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/faq.md)
+covers the common questions. To share one engine across services, run it as
+a [decision server or MCP tools](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/serving.md).
+
 ## Try the demo agent
 
 A complete customer support agent ships with the package: a mock store with
@@ -213,7 +258,15 @@ Writing your own provider is one class. [Providers](https://github.com/inboxprav
 
 ## Documentation
 
-- [Getting started](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/getting-started.md)
+- [Getting started](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/getting-started.md),
+  [installation](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/installation.md)
+- Use it in your agent: [overview](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/integrations/index.md),
+  [LangGraph](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/integrations/langgraph.md),
+  [OpenAI Agents SDK](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/integrations/openai-agents.md),
+  [any framework](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/integrations/any-framework.md),
+  [migration](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/migration.md),
+  [shadow mode](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/shadow-mode.md),
+  [FAQ](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/faq.md)
 - Concepts: [the four planes](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/concepts/planes.md),
   [questions](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/concepts/questions.md),
   [confidence](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/concepts/confidence.md),
@@ -224,16 +277,19 @@ Writing your own provider is one class. [Providers](https://github.com/inboxprav
   [providers](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/providers.md),
   [LLM backends](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/llm-backends.md),
   [production](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/production.md),
+  [serving](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/serving.md),
+  [running a pilot](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/pilot.md),
   [troubleshooting](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/troubleshooting.md)
 - [Benchmarks](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/benchmarks.md), [CLI reference](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/reference/cli.md),
   [Python API](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/reference/api.md), [roadmap](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/roadmap.md)
 
 ## Status
 
-ThinkLess is at 0.1: the core API (questions, the engine, decisions and
-traces) is meant to stay stable, and providers and benchmarks will grow.
-Next up are shadow mode, calibration from traces, calibrated LLM confidence
-from log probabilities, and live Jev runs. See the [roadmap](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/roadmap.md).
+ThinkLess is pre-1.0: the core API (questions, the engine, decisions and
+traces) is meant to stay stable, and providers, adapters and benchmarks will
+grow. Next up are a neutral benchmark for decision models, cross-request
+batching in the server, calibrated LLM confidence from log probabilities, and
+live Jev runs. See the [roadmap](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/roadmap.md).
 
 ## Contributing
 

{thinkless-0.2.0 → thinkless-0.3.0}/pyproject.toml

@@ -70,7 +70,13 @@ otel = [
 ]
 # Public dataset benchmarks.
 bench = ["datasets>=3.0"]
-all = ["thinkless[local,openai,anthropic,otel,bench]"]
+# Agent framework adapters (thinkless.integrations).
+langgraph = ["langgraph>=1.0"]
+openai-agents = ["openai-agents>=0.22"]
+# The decision server (thinkless serve) and MCP tools (thinkless mcp).
+server = ["fastapi>=0.115", "uvicorn>=0.30"]
+mcp = ["mcp>=1.10"]
+all = ["thinkless[local,openai,anthropic,otel,bench,langgraph,openai-agents,server,mcp]"]
 dev = [
   "pytest>=8",
   "pytest-cov>=5",
@@ -79,11 +85,16 @@ dev = [
   "typesafe-sdk>=0.7",
   "mkdocs-material>=9.5",
   "mkdocstrings[python]>=0.26",
+  "langgraph>=1.0",
+  "openai-agents>=0.22",
+  "pydantic-ai-slim>=1.0",
+  "fastapi>=0.115",
+  "mcp>=1.10",
 ]
 
 [project.urls]
 Homepage = "https://github.com/inboxpraveen/ThinkLess"
-Documentation = "https://github.com/inboxpraveen/ThinkLess/tree/main/docs"
+Documentation = "https://inboxpraveen.github.io/ThinkLess/"
 Repository = "https://github.com/inboxpraveen/ThinkLess"
 Issues = "https://github.com/inboxpraveen/ThinkLess/issues"
 Changelog = "https://github.com/inboxpraveen/ThinkLess/blob/main/CHANGELOG.md"

{thinkless-0.2.0 → thinkless-0.3.0}/src/thinkless/__init__.py

@@ -28,6 +28,7 @@ from ._version import __version__
 from .decision import Answer, Attempt, Decision, Plane, Status, Usage
 from .engine import Engine, Run
 from .errors import ConfigurationError, ThinkLessError
+from .limits import SpendLimit, SpendLimitError
 from .logs import configure_logging
 from .questions import Choice, Extract, Kind, Question, Score, YesNo
 from .settings import load_env
@@ -49,6 +50,8 @@ __all__ = [
     "Question",
     "Run",
     "Score",
+    "SpendLimit",
+    "SpendLimitError",
     "Status",
     "ThinkLessError",
     "TraceSummary",

thinkless-0.3.0/src/thinkless/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

{thinkless-0.2.0 → thinkless-0.3.0}/src/thinkless/bench/metrics.py

@@ -13,6 +13,7 @@ __all__ = [
     "percentile",
     "recommend_threshold",
     "threshold_sweep",
+    "wilson_interval",
 ]
 
 
@@ -113,3 +114,18 @@ def recommend_threshold(
         if point.accuracy is not None and point.accuracy >= target_accuracy and point.coverage > 0:
             return point
     return None
+
+
+def wilson_interval(successes: int, n: int, z: float = 1.96) -> tuple[float, float]:
+    """Wilson score interval for a proportion, 95% by default.
+
+    It stays inside [0, 1] and behaves at small ``n`` and at rates near 0 or
+    1, which is where agreement numbers usually sit.
+    """
+    if n <= 0:
+        return 0.0, 1.0
+    p = successes / n
+    denominator = 1 + z * z / n
+    centre = (p + z * z / (2 * n)) / denominator
+    half = z * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / denominator
+    return max(0.0, centre - half), min(1.0, centre + half)

{thinkless-0.2.0 → thinkless-0.3.0}/src/thinkless/cli/main.py

@@ -20,6 +20,10 @@ from rich.table import Table
 from .._version import __version__
 from ..logs import configure_logging
 from ..settings import Settings, load_env
+from .serve import mcp as mcp_command
+from .serve import serve as serve_command
+from .shadow import shadow_app
+from .traces import trace_drift, trace_export
 
 app = typer.Typer(
     name="thinkless",
@@ -591,5 +595,13 @@ def trace_view(
         webbrowser.open(output.resolve().as_uri())
 
 
+# Commands defined in their own modules, listed after the ones above.
+trace_app.command("export")(trace_export)
+trace_app.command("drift")(trace_drift)
+app.add_typer(shadow_app, name="shadow")
+app.command("serve")(serve_command)
+app.command("mcp")(mcp_command)
+
+
 if __name__ == "__main__":  # pragma: no cover
     app()

thinkless-0.3.0/src/thinkless/cli/serve.py

@@ -0,0 +1,117 @@
+"""``thinkless serve`` and ``thinkless mcp``: run an engine you defined in Python."""
+
+from __future__ import annotations
+
+import importlib
+import os
+import sys
+from collections.abc import Iterable, Mapping
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+err = Console(stderr=True)
+
+EngineArg = Annotated[
+    str,
+    typer.Argument(
+        help="Where the engine is, as module:attribute, for example myapp.decisions:engine. "
+        "The attribute can also be a function that returns an engine."
+    ),
+]
+QuestionsOption = Annotated[
+    str | None,
+    typer.Option(
+        help="Questions to register, as module:attribute (a list or a mapping of questions). "
+        "Default: QUESTIONS in the engine's module, if it exists."
+    ),
+]
+
+
+def _load(path: str) -> Any:
+    module_name, _, attribute = path.partition(":")
+    if not module_name or not attribute:
+        raise typer.BadParameter(f"expected module:attribute, got {path!r}")
+    if os.getcwd() not in sys.path:
+        sys.path.insert(0, os.getcwd())
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as exc:
+        raise typer.BadParameter(f"cannot import {module_name!r}: {exc}") from exc
+    try:
+        return getattr(module, attribute)
+    except AttributeError as exc:
+        raise typer.BadParameter(f"{module_name!r} has no attribute {attribute!r}") from exc
+
+
+def load_engine_and_questions(engine_path: str, questions_path: str | None) -> tuple[Any, Any]:
+    from ..engine import Engine
+    from ..questions import Question
+
+    engine = _load(engine_path)
+    if callable(engine) and not isinstance(engine, Engine):
+        engine = engine()
+    if not isinstance(engine, Engine):
+        raise typer.BadParameter(f"{engine_path} is not a thinkless.Engine")
+    if questions_path:
+        questions = _load(questions_path)
+    else:
+        module = sys.modules[engine_path.partition(":")[0]]
+        questions = getattr(module, "QUESTIONS", None)
+    if questions is not None:
+        items = questions.values() if isinstance(questions, Mapping) else questions
+        if not isinstance(items, Iterable) or not all(isinstance(q, Question) for q in items):
+            raise typer.BadParameter("questions must be a list or a mapping of Question objects")
+    return engine, questions
+
+
+def serve(
+    engine: EngineArg,
+    questions: QuestionsOption = None,
+    host: Annotated[str, typer.Option(help="Interface to bind.")] = "127.0.0.1",
+    port: Annotated[int, typer.Option(help="Port to listen on.")] = 8080,
+    api_key_env: Annotated[
+        str,
+        typer.Option(help="Environment variable holding the bearer token clients must send."),
+    ] = "THINKLESS_API_KEY",
+    registered_only: Annotated[
+        bool,
+        typer.Option(
+            "--registered-only", help="Refuse questions that are not registered on the server."
+        ),
+    ] = False,
+) -> None:
+    """Serve an engine over HTTP: /v1/decide, /v1/systemone, /v1/questions, /healthz."""
+    try:
+        import uvicorn
+
+        from ..server.app import create_app
+    except ImportError as exc:
+        raise typer.BadParameter('the server needs: pip install "thinkless[server]"') from exc
+
+    built, registered = load_engine_and_questions(engine, questions)
+    api_key = os.environ.get(api_key_env) or None
+    if api_key is None and host not in ("127.0.0.1", "localhost", "::1"):
+        err.print(
+            f"[yellow]Serving on {host} without authentication. Set {api_key_env} to require "
+            "a bearer token.[/]"
+        )
+    app = create_app(built, registered, api_key=api_key, allow_ad_hoc=not registered_only)
+    uvicorn.run(app, host=host, port=port)
+
+
+def mcp(
+    engine: EngineArg,
+    questions: QuestionsOption = None,
+    transport: Annotated[
+        str, typer.Option(help="stdio (for desktop and IDE clients) or streamable-http.")
+    ] = "stdio",
+) -> None:
+    """Serve an engine's questions as MCP tools, one decide_<question> tool each."""
+    from ..server.mcp import create_mcp_server
+
+    built, registered = load_engine_and_questions(engine, questions)
+    if not registered:
+        raise typer.BadParameter("MCP needs registered questions: pass --questions")
+    create_mcp_server(built, registered).run(transport)