route67 0.1.0__tar.gz

route67-0.1.0/.gitignore

@@ -0,0 +1,62 @@
+# Virtual environments
+.venv/
+.venv-*/
+venv/
+env/
+ENV/
+*.venv
+
+# Python bytecode and build artifacts
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+.tmp-dist/
+
+# Test, coverage, lint, and type-check caches
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.hypothesis/
+.mypy_cache/
+.pyright/
+.ruff_cache/
+.tox/
+.nox/
+
+# Runtime caches and logs
+.cache/
+*.log
+*.jsonl
+
+# Local environment variables and credentials
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+credentials*.json
+secrets*.json
+
+# Local model and Hugging Face caches
+.huggingface/
+.hf_home/
+
+# Editors, OS files, and local agent metadata
+.idea/
+.vscode/
+.agents/
+.codex/
+*.swp
+*~
+.DS_Store
+Thumbs.db
+Desktop.ini
+publish_instruction.md

route67-0.1.0/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.

route67-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,191 @@
+# 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/example.py

@@ -0,0 +1,46 @@
+"""Route67 usage with open router example"""
+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(
+        "google/gemma-3-4b-it",
+        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": "What are some interesting facts about South Korea?",
+        }
+    ],
+    extra_body={"reasoning": {"enabled": True}},
+)
+
+print(f"Response model name: {response.model}")
+print(response.choices[0].message.content)

route67-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "route67"
+dynamic = ["version"]
+description = "A semantic LLM router for OpenAI-compatible chat completions."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "route67 contributors" }]
+keywords = ["llm", "router", "openai", "semantic-routing"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "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 = [
+  "model2vec>=0.6,<1",
+  "numpy>=1.24",
+  "openai>=1.0,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/SmallChungus1/route67"
+Repository = "https://github.com/SmallChungus1/route67"
+Issues = "https://github.com/SmallChungus1/route67/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/llm_router"]
+
+[tool.hatch.version]
+path = "src/llm_router/__init__.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

route67-0.1.0/src/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"
+

route67-0.1.0/src/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'")