route67 0.1.0__py3-none-any.whl

llm_router/__init__.py

@@ -0,0 +1,8 @@
+"""Public package interface for route67."""
+
+from .config import ModelSpec, RouterConfig, RoutingTableEntry
+from .controller import Controller
+
+__all__ = ["Controller", "ModelSpec", "RouterConfig", "RoutingTableEntry"]
+__version__ = "0.1.0"
+

llm_router/config.py

@@ -0,0 +1,61 @@
+"""Configuration models for the router."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+ModelTarget = Literal["weak_model", "strong_model"]
+MODEL_TARGETS = frozenset({"weak_model", "strong_model"})
+
+
+@dataclass(frozen=True, slots=True)
+class RoutingTableEntry:
+    query: str
+    target: ModelTarget
+    notes: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.target not in MODEL_TARGETS:
+            raise ValueError(
+                "routing target must be 'weak_model' or 'strong_model'"
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class ModelSpec:
+    name: str
+    usage_notes: str | None = None
+
+
+@dataclass(slots=True)
+class RouterConfig:
+    routing_table: list[RoutingTableEntry] = field(default_factory=list)
+    similarity_threshold: float = 0.75
+    weak_model: ModelSpec | None = None
+    strong_model: ModelSpec | None = None
+    embedding_cache_path: str | None = None
+    log_path: str | None = None
+    escalation_max_tokens: int = 10
+    embedding_model: str = "minishlab/potion-base-8M"
+
+    def __post_init__(self) -> None:
+        if not -1.0 <= self.similarity_threshold <= 1.0:
+            raise ValueError("similarity_threshold must be between -1.0 and 1.0")
+        if self.weak_model is None:
+            raise ValueError("weak_model is required")
+        if self.strong_model is None:
+            raise ValueError("strong_model is required")
+        if self.escalation_max_tokens < 1:
+            raise ValueError("escalation_max_tokens must be at least 1")
+
+    def resolve_target(self, target: ModelTarget) -> ModelSpec:
+        if target == "weak_model":
+            if self.weak_model is None:
+                raise RuntimeError("weak_model is not configured")
+            return self.weak_model
+        if target == "strong_model":
+            if self.strong_model is None:
+                raise RuntimeError("strong_model is not configured")
+            return self.strong_model
+        raise ValueError("routing target must be 'weak_model' or 'strong_model'")

llm_router/controller.py

@@ -0,0 +1,101 @@
+"""OpenAI-compatible public controller."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .config import RouterConfig
+from .embedder import Embedder
+from .escalation import run_with_escalation
+from .logging_utils import RoutingDecision, log_decision
+from .routing_table import RoutingTable
+
+
+class Controller:
+    def __init__(
+        self,
+        config: RouterConfig,
+        openai_client: Any | None = None,
+        embedder: Embedder | None = None,
+    ) -> None:
+        self.config = config
+        self.client = openai_client or _default_openai_client()
+        self.table = RoutingTable(
+            config.routing_table,
+            embedder or Embedder(config.embedding_model),
+            config.embedding_cache_path,
+        )
+        self.chat = _ChatProxy(self)
+
+    def chat_completions_create(self, **kwargs: Any) -> Any:
+        if kwargs.get("stream"):
+            raise NotImplementedError("Public streaming is not supported in route67 v1")
+        messages = kwargs.get("messages")
+        if not isinstance(messages, list):
+            raise TypeError("messages must be provided as a list")
+
+        query = extract_user_query(messages)
+        entry, score = self.table.best_match(query)
+        forwarded = {key: value for key, value in kwargs.items() if key != "model"}
+
+        if entry is not None and score >= self.config.similarity_threshold:
+            selected_model = self.config.resolve_target(entry.target)
+            response = self.client.chat.completions.create(
+                model=selected_model.name,
+                **forwarded,
+            )
+            decision = RoutingDecision("table_match", selected_model.name, score)
+        else:
+            result = run_with_escalation(
+                self.client,
+                self.config,
+                messages,
+                request_kwargs=forwarded,
+            )
+            response = result.response
+            decision = RoutingDecision(
+                "escalated" if result.escalated else "weak_model_direct",
+                result.used_model,
+                score,
+            )
+
+        log_decision(self.config.log_path, query, decision)
+        return response
+
+
+def extract_user_query(messages: list[dict[str, Any]]) -> str:
+    for message in reversed(messages):
+        if message.get("role") != "user":
+            continue
+        content = message.get("content", "")
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            return " ".join(
+                part.get("text", "")
+                for part in content
+                if isinstance(part, dict) and part.get("type") == "text"
+            )
+        return str(content)
+    raise ValueError("messages must contain at least one user message")
+
+
+def _default_openai_client() -> Any:
+    try:
+        from openai import OpenAI
+    except ImportError as exc:
+        raise ImportError("openai is required when openai_client is not supplied") from exc
+    return OpenAI()
+
+
+class _ChatProxy:
+    def __init__(self, controller: Controller) -> None:
+        self.completions = _CompletionsProxy(controller)
+
+
+class _CompletionsProxy:
+    def __init__(self, controller: Controller) -> None:
+        self._controller = controller
+
+    def create(self, **kwargs: Any) -> Any:
+        return self._controller.chat_completions_create(**kwargs)

llm_router/embedder.py

@@ -0,0 +1,42 @@
+"""Small, lazy-loading Model2Vec embedder."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+import numpy as np
+
+
+class Embedder:
+    def __init__(
+        self,
+        model_name: str = "minishlab/potion-base-8M",
+        model: Any | None = None,
+    ) -> None:
+        self.model_name = model_name
+        self._model = model
+
+    @property
+    def model(self) -> Any:
+        if self._model is None:
+            try:
+                from model2vec import StaticModel
+            except ImportError as exc:
+                raise ImportError(
+                    "model2vec is required to compute embeddings; install route67"
+                ) from exc
+            self._model = StaticModel.from_pretrained(self.model_name)
+        return self._model
+
+    def encode(self, texts: Sequence[str]) -> np.ndarray:
+        if isinstance(texts, str):
+            raise TypeError("encode expects a sequence of strings; use encode_one for one string")
+        vectors = np.asarray(self.model.encode(list(texts)), dtype=np.float32)
+        if vectors.ndim != 2:
+            raise ValueError("embedder returned an array with an unexpected shape")
+        return vectors
+
+    def encode_one(self, text: str) -> np.ndarray:
+        return self.encode([text])[0]
+

llm_router/escalation.py

@@ -0,0 +1,248 @@
+"""Sequential weak-to-strong escalation."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from types import SimpleNamespace
+from typing import Any
+
+from .config import RouterConfig
+from .prompts import build_escalation_prompt
+
+SENTINEL = "ESCALATE"
+
+
+@dataclass(frozen=True, slots=True)
+class EscalationResult:
+    used_model: str
+    response: Any
+    escalated: bool
+
+
+def run_with_escalation(
+    client: Any,
+    config: RouterConfig,
+    messages: list[dict[str, Any]],
+    request_kwargs: dict[str, Any] | None = None,
+) -> EscalationResult:
+    request_kwargs = dict(request_kwargs or {})
+    request_kwargs.pop("model", None)
+    request_kwargs.pop("messages", None)
+    request_kwargs.pop("stream", None)
+
+    prompt = build_escalation_prompt(
+        config.weak_model.usage_notes,
+        config.strong_model,
+        config.routing_table,
+    )
+    weak_messages = [{"role": "system", "content": prompt}, *messages]
+    weak_stream = client.chat.completions.create(
+        model=config.weak_model.name,
+        messages=weak_messages,
+        stream=True,
+        **request_kwargs,
+    )
+
+    chunks: list[Any] = []
+    preview = ""
+    decision_made = False
+    try:
+        for chunk in weak_stream:
+            chunks.append(chunk)
+            preview += _chunk_text(chunk)
+            if not decision_made and _decision_boundary_reached(
+                preview, config.escalation_max_tokens
+            ):
+                decision_made = True
+                if _is_escalation(preview):
+                    _close_stream(weak_stream)
+                    strong_response = client.chat.completions.create(
+                        model=config.strong_model.name,
+                        messages=messages,
+                        stream=False,
+                        **request_kwargs,
+                    )
+                    return EscalationResult(
+                        used_model=config.strong_model.name,
+                        response=strong_response,
+                        escalated=True,
+                    )
+    finally:
+        _close_stream(weak_stream)
+
+    if _is_escalation(preview):
+        strong_response = client.chat.completions.create(
+            model=config.strong_model.name,
+            messages=messages,
+            stream=False,
+            **request_kwargs,
+        )
+        return EscalationResult(config.strong_model.name, strong_response, True)
+
+    response = _assemble_chat_completion(chunks, config.weak_model.name)
+    return EscalationResult(config.weak_model.name, response, False)
+
+
+def _decision_boundary_reached(text: str, max_tokens: int) -> bool:
+    stripped = text.lstrip()
+    if "\n" in stripped or "\r" in stripped:
+        return True
+    if stripped.lower().startswith(SENTINEL.lower()) and len(stripped) >= len(SENTINEL):
+        return True
+    if stripped and not SENTINEL.lower().startswith(stripped.lower()):
+        return True
+    return len(stripped.split()) >= max_tokens
+
+
+def _is_escalation(text: str) -> bool:
+    return text.lstrip().lower().startswith(SENTINEL.lower())
+
+
+def _chunk_text(chunk: Any) -> str:
+    choices = _get(chunk, "choices", []) or []
+    if not choices:
+        return ""
+    delta = _get(choices[0], "delta")
+    return _get(delta, "content", "") or ""
+
+
+def _close_stream(stream: Any) -> None:
+    close = getattr(stream, "close", None)
+    if callable(close):
+        close()
+
+
+def _assemble_chat_completion(chunks: list[Any], model: str) -> Any:
+    message: dict[str, Any] = {"role": "assistant", "content": ""}
+    response_extensions: dict[str, Any] = {}
+    choice_extensions: dict[str, Any] = {}
+    finish_reason = "stop"
+    completion_id = "route67-weak"
+    created = int(time.time())
+    system_fingerprint = None
+    usage = None
+
+    for chunk in chunks:
+        chunk_payload = _dump(chunk)
+        if isinstance(chunk_payload, dict):
+            for key, value in chunk_payload.items():
+                if key not in {
+                    "id",
+                    "object",
+                    "created",
+                    "model",
+                    "choices",
+                    "usage",
+                    "system_fingerprint",
+                } and value is not None:
+                    response_extensions[key] = value
+        completion_id = _get(chunk, "id", completion_id) or completion_id
+        created = _get(chunk, "created", created) or created
+        system_fingerprint = _get(chunk, "system_fingerprint", system_fingerprint)
+        usage = _get(chunk, "usage", usage)
+        choices = _get(chunk, "choices", []) or []
+        if not choices:
+            continue
+        choice = choices[0]
+        delta = _get(choice, "delta")
+        delta_payload = _dump(delta)
+        if isinstance(delta_payload, dict):
+            message = _merge_stream_value(message, delta_payload)
+        choice_payload = _dump(choice)
+        if isinstance(choice_payload, dict):
+            for key, value in choice_payload.items():
+                if key not in {"index", "delta", "finish_reason"} and value is not None:
+                    choice_extensions[key] = value
+        finish_reason = _get(choice, "finish_reason", finish_reason) or finish_reason
+
+    payload = {
+        "id": completion_id,
+        "object": "chat.completion",
+        "created": created,
+        "model": model,
+        "choices": [
+            {
+                "index": 0,
+                "message": message,
+                "finish_reason": finish_reason,
+                "logprobs": None,
+                **choice_extensions,
+            }
+        ],
+        "usage": _dump(usage) if usage is not None else None,
+        "system_fingerprint": system_fingerprint,
+        **response_extensions,
+    }
+    try:
+        from openai.types.chat import ChatCompletion
+
+        return ChatCompletion.model_validate(payload)
+    except (ImportError, TypeError, ValueError):
+        # Compatible providers can add values before the OpenAI SDK schema knows
+        # about them. Preserve the response shape instead of rejecting the data.
+        return _namespace(payload)
+
+
+def _get(value: Any, name: str, default: Any = None) -> Any:
+    if isinstance(value, dict):
+        return value.get(name, default)
+    return getattr(value, name, default)
+
+
+def _dump(value: Any) -> Any:
+    if isinstance(value, dict):
+        return value
+    model_dump = getattr(value, "model_dump", None)
+    if callable(model_dump):
+        return model_dump(exclude_none=True)
+    attributes = getattr(value, "__dict__", None)
+    return dict(attributes) if isinstance(attributes, dict) else value
+
+
+def _merge_stream_value(current: Any, incoming: Any, key: str | None = None) -> Any:
+    """Merge streamed OpenAI-format deltas without dropping provider extensions."""
+    if incoming is None:
+        return current
+    if current is None:
+        return incoming
+    if isinstance(current, dict) and isinstance(incoming, dict):
+        merged = dict(current)
+        for child_key, value in incoming.items():
+            merged[child_key] = _merge_stream_value(
+                merged.get(child_key), value, child_key
+            )
+        return merged
+    if isinstance(current, list) and isinstance(incoming, list):
+        return _merge_stream_lists(current, incoming)
+    if isinstance(current, str) and isinstance(incoming, str):
+        if key in {"role", "name"}:
+            return incoming
+        return current + incoming
+    return incoming
+
+
+def _merge_stream_lists(current: list[Any], incoming: list[Any]) -> list[Any]:
+    merged = list(current)
+    positions = {
+        item.get("index"): position
+        for position, item in enumerate(merged)
+        if isinstance(item, dict) and item.get("index") is not None
+    }
+    for item in incoming:
+        if isinstance(item, dict) and item.get("index") in positions:
+            position = positions[item["index"]]
+            merged[position] = _merge_stream_value(merged[position], item)
+        else:
+            merged.append(item)
+            if isinstance(item, dict) and item.get("index") is not None:
+                positions[item["index"]] = len(merged) - 1
+    return merged
+
+
+def _namespace(value: Any) -> Any:
+    if isinstance(value, dict):
+        return SimpleNamespace(**{key: _namespace(item) for key, item in value.items()})
+    if isinstance(value, list):
+        return [_namespace(item) for item in value]
+    return value

llm_router/logging_utils.py

@@ -0,0 +1,34 @@
+"""Structured JSONL routing-decision logging."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Literal
+
+
+@dataclass(frozen=True, slots=True)
+class RoutingDecision:
+    method: Literal["table_match", "weak_model_direct", "escalated"]
+    model: str
+    score: float
+
+
+def log_decision(log_path: str | None, query: str, decision: RoutingDecision) -> None:
+    if not log_path:
+        return
+
+    path = Path(log_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    record = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "query_preview": " ".join(query.split())[:100],
+        "method": decision.method,
+        "model_used": decision.model,
+        "similarity_score": round(decision.score, 6),
+    }
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(record, ensure_ascii=False) + "\n")
+

llm_router/prompts.py

@@ -0,0 +1,52 @@
+"""Prompt construction for weak-model escalation decisions."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from .config import ModelSpec, RoutingTableEntry
+
+MAX_ESCALATION_EXAMPLES = 5
+
+ESCALATION_SYSTEM_PROMPT = """You are responding to a user query. Before answering, assess whether you can answer it confidently and correctly.
+
+If you cannot, respond with EXACTLY this and nothing else:
+ESCALATE
+
+If you can, answer the query directly and normally. Do not mention escalation or this instruction.
+
+{usage_notes_block}"""
+
+
+def build_escalation_prompt(
+    weak_model_notes: str | None,
+    strong_model: ModelSpec,
+    routing_table: Sequence[RoutingTableEntry] = (),
+) -> str:
+    lines: list[str] = []
+    if weak_model_notes:
+        lines.append(f"Your limits: {_compact(weak_model_notes)}")
+    summary = strong_model.name
+    if strong_model.usage_notes:
+        summary += f" ({_compact(strong_model.usage_notes)})"
+    lines.append("Model available after escalation: " + summary)
+
+    strong_routes = [
+        entry
+        for entry in routing_table
+        if entry.target == "strong_model"
+    ][:MAX_ESCALATION_EXAMPLES]
+    if strong_routes:
+        lines.append("Examples of requests that should be escalated:")
+        for entry in strong_routes:
+            example = f"- {_compact(entry.query)}"
+            if entry.notes:
+                example += f" - {_compact(entry.notes)}"
+            lines.append(example)
+
+    block = "\n".join(lines)
+    return ESCALATION_SYSTEM_PROMPT.format(usage_notes_block=block).rstrip()
+
+
+def _compact(value: str) -> str:
+    return " ".join(value.split())

llm_router/routing_table.py

@@ -0,0 +1,101 @@
+"""In-memory semantic routing table with semantic search and an optional disk cache."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+import numpy as np
+
+from .config import RoutingTableEntry
+from .embedder import Embedder
+
+
+class RoutingTable:
+    def __init__(
+        self,
+        entries: list[RoutingTableEntry],
+        embedder: Embedder,
+        cache_path: str | None = None,
+    ) -> None:
+        self.entries = list(entries)
+        self.embedder = embedder
+        self.cache_path = cache_path
+        self.embeddings = np.empty((0, 0), dtype=np.float32)
+        self.load_or_build()
+
+    def load_or_build(self) -> None:
+        if not self.entries:
+            return
+
+        table_hash = self._table_hash()
+        vector_path, metadata_path = self._cache_paths()
+        if vector_path and metadata_path and vector_path.exists() and metadata_path.exists():
+            try:
+                metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+                if (
+                    metadata.get("table_hash") == table_hash
+                    and metadata.get("embedding_model") == self.embedder.model_name
+                ):
+                    cached = np.load(vector_path, allow_pickle=False)
+                    if cached.ndim == 2 and cached.shape[0] == len(self.entries):
+                        self.embeddings = cached.astype(np.float32, copy=False)
+                        return
+            except (OSError, ValueError, json.JSONDecodeError):
+                pass
+
+        vectors = self.embedder.encode([entry.query for entry in self.entries])
+        self.embeddings = _normalize_rows(vectors)
+
+        if vector_path and metadata_path:
+            vector_path.parent.mkdir(parents=True, exist_ok=True)
+            np.save(vector_path, self.embeddings, allow_pickle=False)
+            metadata_path.write_text(
+                json.dumps(
+                    {
+                        "table_hash": table_hash,
+                        "embedding_model": self.embedder.model_name,
+                        "entries": [asdict(entry) for entry in self.entries],
+                    },
+                    ensure_ascii=False,
+                    indent=2,
+                ),
+                encoding="utf-8",
+            )
+
+    def best_match(self, query: str) -> tuple[RoutingTableEntry | None, float]:
+        if not self.entries:
+            return None, 0.0
+
+        query_vector = _normalize_rows(self.embedder.encode([query]))[0]
+        scores = self.embeddings @ query_vector
+        best_index = int(np.argmax(scores))
+        return self.entries[best_index], float(scores[best_index])
+
+    def _table_hash(self) -> str:
+        payload = json.dumps(
+            [asdict(entry) for entry in self.entries],
+            sort_keys=True,
+            ensure_ascii=False,
+            separators=(",", ":"),
+        )
+        return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+    def _cache_paths(self) -> tuple[Path | None, Path | None]:
+        if not self.cache_path:
+            return None, None
+        base = Path(self.cache_path)
+        if base.suffix in {".npy", ".json"}:
+            base = base.with_suffix("")
+        return base.with_suffix(".npy"), base.with_suffix(".json")
+
+
+def _normalize_rows(vectors: np.ndarray) -> np.ndarray:
+    vectors = np.asarray(vectors, dtype=np.float32)
+    if vectors.ndim != 2:
+        raise ValueError("embeddings must be a two-dimensional array")
+    norms = np.linalg.norm(vectors, axis=1, keepdims=True)
+    return np.divide(vectors, norms, out=np.zeros_like(vectors), where=norms != 0)
+

route67-0.1.0.dist-info/METADATA

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: route67
+Version: 0.1.0
+Summary: A semantic LLM router for OpenAI-compatible chat completions.
+Project-URL: Homepage, https://github.com/SmallChungus1/route67
+Project-URL: Repository, https://github.com/SmallChungus1/route67
+Project-URL: Issues, https://github.com/SmallChungus1/route67/issues
+Author: route67 contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: llm,openai,router,semantic-routing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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.10
+Requires-Dist: model2vec<1,>=0.6
+Requires-Dist: numpy>=1.24
+Requires-Dist: openai<3,>=1.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# route67
+
+`route67` is a LLM router for OpenAI-compatible chat
+completions format. It uses a user-defined routing table for user defined question-model routing via semantic similarity, as a fallback a weak model answer or explicitly escalate to a strong model.
+
+## How it works
+
+```mermaid
+flowchart LR
+    Q["User request"] --> R{"Semantic route match?"}
+    R -- Yes --> M["Configured weak or strong model"]
+    R -- No --> W["Weak model gate<br/>usage notes + strong-route examples"]
+    W -- Answers --> O["Response"]
+    W -- ESCALATE --> S["Strong model"]
+    M --> O
+    S --> O
+```
+
+## Install
+
+route67 requires Python 3.10 or newer. Choose either the standard Python workflow
+or the `uv` workflow.
+
+### Using `python -m venv`
+
+Create and activate a virtual environment:
+
+```console
+python -m venv .venv
+```
+
+```powershell
+# Windows PowerShell
+.\.venv\Scripts\Activate.ps1
+```
+
+```console
+# macOS/Linux
+source .venv/bin/activate
+```
+
+Then install route67 and its dependencies:
+
+```console
+python -m pip install --upgrade pip
+python -m pip install -e .
+```
+
+To also install the test dependencies, use `python -m pip install -e ".[test]"`.
+
+### Using `uv`
+
+With [`uv`](https://docs.astral.sh/uv/) installed, create the environment and
+install the project from the lockfile:
+
+```console
+uv sync
+```
+
+Run commands inside the environment with `uv run`, for example
+`uv run python example.py`. To include test dependencies, use
+`uv sync --extra test`.
+
+## Get started
+
+Set an OpenAI API key in your environment:
+
+```powershell
+# Windows PowerShell
+$env:OPENAI_API_KEY = "your-api-key"
+```
+
+```console
+# macOS/Linux
+export OPENAI_API_KEY="your-api-key"
+```
+
+Create `example.py`:
+
+```python
+from llm_router import Controller, ModelSpec, RouterConfig, RoutingTableEntry
+
+config = RouterConfig(
+    routing_table=[
+        RoutingTableEntry(
+            "Prove this theorem",
+            "strong_model",
+            notes="Requires a rigorous multi-step proof.",
+        ),
+        RoutingTableEntry("Rewrite this paragraph", "weak_model"),
+    ],
+    weak_model=ModelSpec(
+        "gpt-5-mini",
+        usage_notes="Avoid difficult multi-step proofs.",
+    ),
+    strong_model=ModelSpec(
+        "gpt-5",
+        usage_notes="Use for rigorous proofs and difficult reasoning.",
+    ),
+    embedding_cache_path=".cache/routes",
+    log_path=".cache/routing.jsonl",
+)
+
+client = Controller(config)
+response = client.chat.completions.create(
+    messages=[{"role": "user", "content": "Prove that sqrt(2) is irrational."}]
+)
+print(response.choices[0].message.content)
+```
+
+Run it with the activated standard virtual environment:
+
+```console
+python example.py
+```
+
+Or with `uv`:
+
+```console
+uv run python example.py
+```
+
+### OpenAI-compatible providers
+
+route67 can use any provider exposed through an OpenAI-compatible client. Create
+the provider's client normally and inject it into the controller. Model names in
+the routing configuration are passed to that provider unchanged.
+
+For example, with OpenRouter:
+
+```python
+import os
+
+from openai import OpenAI
+from llm_router import Controller, ModelSpec, RouterConfig, RoutingTableEntry
+
+openrouter = OpenAI(
+    base_url="https://openrouter.ai/api/v1",
+    api_key=os.environ["OPENROUTER_API_KEY"],
+)
+
+config = RouterConfig(
+    routing_table=[
+        RoutingTableEntry(
+            "Answer questions about a country",
+            "weak_model",
+        ),
+        RoutingTableEntry(
+            "Solve a difficult reasoning or math problem",
+            "strong_model",
+            notes="Requires careful multi-step reasoning.",
+        ),
+    ],
+    weak_model=ModelSpec(
+        "openai/gpt-4.1-mini",
+        usage_notes="Best for straightforward factual and writing questions.",
+    ),
+    strong_model=ModelSpec(
+        "deepseek/deepseek-v4-flash",
+        usage_notes="Use for difficult reasoning, mathematics, and verification.",
+    ),
+)
+
+client = Controller(config, openai_client=openrouter)
+response = client.chat.completions.create(
+    messages=[
+        {
+            "role": "user",
+            "content": "How many r's are in the word 'strawberry'?",
+        }
+    ],
+    extra_body={"reasoning": {"enabled": True}},
+)
+```
+
+Provider-specific request options such as `extra_body` and `extra_headers` are
+forwarded unchanged. Provider-specific response fields, including
+`reasoning_details`, are also preserved. To continue a provider's reasoning,
+pass its assistant message fields back unmodified in the next request.
+
+Routing table entries target only `"weak_model"` or `"strong_model"`. Provider
+model names live in `ModelSpec`, so switching models or providers does not
+require rewriting the routing table.
+
+`ModelSpec.usage_notes` are added to the weak model's escalation system prompt.
+The prompt also includes up to five routing-table entries targeting
+`"strong_model"` as examples of requests that should be escalated. Add concise
+`notes` to those entries when the reason for escalation is useful context.
+
+Your first request will download the `minishlab/potion-base-8M` from HuggingFace. The model is lazy-loaded,
+so constructing a controller with an empty routing table does not download it.

route67-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+llm_router/__init__.py,sha256=RwHWX6F0Is8P0MaQTNj7wLZDurk4vHtpZ7L3W6kC6dU,242
+llm_router/config.py,sha256=FxjEeO62qVwVcPtxsvfsm82ezo91A2-A9zHIq76oLd4,2086
+llm_router/controller.py,sha256=5rSAP2pTzFWApZp0_oB7y7RWGTpKkuiYCgC7gkWjoCs,3390
+llm_router/embedder.py,sha256=9g1V7toS7c8H7Jvmx5ho0kZsnzlPXuyYV5xo1Ao4qKo,1305
+llm_router/escalation.py,sha256=S22Lt3bUei3QjOKd1470Hpn6CujAiu46UcOI6K_-m6c,8445
+llm_router/logging_utils.py,sha256=G9d-aEFGYlaKDYNyiuklMwAu8MUyOXFvDOCAzNKekYk,984
+llm_router/prompts.py,sha256=tC01-zazA0wcclb8eAS0I7JPMCm0WZs55jIHyKl8QG4,1643
+llm_router/routing_table.py,sha256=x5X0sGMn-oOaPncTXswqCGIJFd0aGiNRvTHXVnjkxeA,3667
+route67-0.1.0.dist-info/METADATA,sha256=27TSDzfH3YjRE8e7lQxZ1uCLZWikph3Op52K2vxM_10,6343
+route67-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+route67-0.1.0.dist-info/licenses/LICENSE,sha256=QaM-505zGS0RtXBxfg_YtfN-J3YndVxG7ruuzAGs2v4,1077
+route67-0.1.0.dist-info/RECORD,,

route67-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

route67-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 route67 contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.