route66 2.0.2

route66 Python SDK

route66

Intelligent Tool Router for LLM Agents — a catalog-in library that, given a query and a large tool catalog, returns only the relevant tools, deduplicated, in an ordered execution plan, with policy-aware defaults.

Built against the router-testkit hackathon grading contract (single-tool routing, ordered multi-tool plans, near-duplicate resolution, capability-based fallback widening, deprecation policy, out-of-scope refusal, and clarify-on-vague-destructive).

Layout

route66/
├── tool_router/          # The POC library (facade + retrievers + dedup)
├── testkit_adapter.py    # Bridges tool_router to the harness contract
├── demo.py               # Toy 60-tool catalog demo of the POC
├── metrics.py            # Recall/precision/token-savings eval on the toy set
├── router-testkit/       # Hackathon input kit — DO NOT MODIFY
│   ├── catalog/          #   64 mock tools · 13 clusters · dup/version metadata
│   ├── test_cases/       #   29 scored cases across 11 categories
│   ├── registry_guardrail/#  Intake validator fixtures
│   └── harness/          #   run_benchmark.py (scorer) + baseline_router.py
├── bench/                # Additional benchmarks (baseline, mutations, guardrail)
├── specs/                # Spec-driven-development plan (SPEC-001..011)
├── docs/                 # PRDs and the hackathon problem statement
└── tests/                # Unit tests (populated as specs are executed)

Baseline

Router	Cases passed	Token savings
Testkit reference baseline_router	7 / 29 (24%)	94%
tool_router (this repo, current)	5 / 29 (17%)	90%

The gap is deliberate and mapped in specs/. See specs/README.md for the priority-ordered plan (P0 → P1 → P2) with acceptance criteria pinned to specific TC-* cases. Target after P0: ≥ 20/29. After P1: ≥ 24/29.

Quick start

# Install (uv-managed)
uv sync

# Score the reference baseline
cd router-testkit/harness
python run_benchmark.py --verbose

# Score this project's router
python run_benchmark.py --router testkit_adapter:MyRouter --verbose

The harness has no third-party dependencies; standard-library only. The router itself can run on HashingEmbedder (zero deps) or opt-in SentenceTransformerEmbedder via uv sync --extra semantic.

Pluggable embedding store (Chroma DB, optional)

The dense-retrieval leg of the pipeline stores tool embeddings behind a VectorStore abstraction. The default is a zero-dependency in-memory exact-cosine store; you can opt into Chroma DB without changing any other code.

from route66 import Tool, ToolRouter, ChromaVectorStore

tools = [Tool(id="fin.get_revenue", name="get_revenue_report",
              description="Retrieve booked revenue for a period"), ...]

# Default: in-memory store, zero extra deps.
router = ToolRouter(tools)

# Opt in to Chroma DB — same catalog, same results, external store.
router = ToolRouter(tools, vector_store=ChromaVectorStore())

Or select it by environment variable (no code change):

export TR_VECTOR_STORE=chroma      # 'memory' (default) | 'chroma'

Install the optional dependency with uv sync --extra chroma. When chromadb is not installed, the registry logs a warning and falls back to the in-memory store, so nothing breaks.

Live tool sync from MCP servers (optional)

MCPToolSync connects to an agent's MCP server(s) with the official mcp SDK, calls list_tools(), transforms the schemas into route66 Tools, and updates the embedding store — adding embeddings for new tools and purging embeddings for any tool whose server was removed. It works with either vector store above.

from route66 import ToolRouter, MCPServerSpec, MCPToolSync, ChromaVectorStore

router = ToolRouter(seed_tools, vector_store=ChromaVectorStore())

sync = MCPToolSync(router, servers=[
    MCPServerSpec("slack", command="npx", args=("-y", "@modelcontextprotocol/server-slack")),
    MCPServerSpec("github", url="https://mcp.example.com/sse"),
])

sync.sync()             # connect → transform → embed (returns a CatalogDelta)

sync.servers.pop()      # detach the github server
sync.sync()             # its tool embeddings are purged from the store

sync() is a manual, pull-based call (no threads, no file watching): run it at start-up and whenever you attach/detach a server. It is a no-op when nothing changed. Install the optional client with uv sync --extra mcp.

How to test and set these up locally: see docs/chroma-and-mcp-sync.md.

Where to read next

1. docs/architecture/query-flow.md — sequence diagram of a single route() call end-to-end. Every arrow points at a function you can grep for. Read this before touching the pipeline.
2. docs/architecture/components.md — module dependency graph, per-module code-map, and extension-point cheat-sheet. Read this when picking up the codebase cold.
3. specs/README.md — the executable plan. Every spec is pickable independently and has acceptance criteria tied to testkit case IDs.
4. router-testkit/README.md — the grading contract (authoritative).
5. docs/hackathon-definition.md — the problem statement.
6. docs/PRD.md — the initial PRD.

Toolchain

• Python ≥ 3.14 (pinned in .python-version, managed by uv)
• Ruff for lint + format
• Pytest for unit tests (see pyproject.toml's [dev] extra)

Dev

uv run ruff check .
uv run ruff format .
uv run pytest

Release

Releases are published to PyPI via a GitLab CI child pipeline. To trigger a release:

1. Go to CI/CD → Pipelines → Run pipeline on the master branch.
2. The trigger:release job starts automatically and spawns the release child pipeline.
3. Set any of the following pipeline variables before running:

Variable	Default	Meaning
BUMP	patch	patch / minor / major — controls auto-increment.
VERSION	empty	Explicit x.y.z — overrides BUMP when set.
RELEASE_NOTES	empty	Free-form notes shown on the PyPI page, git tag, and GitLab Release.

The pipeline will:

• Bump src/route66/_version.py and rebuild the package
• Inject release notes into the PyPI long description (visible on pypi.org)
• Publish the wheel + sdist via twine
• Commit the version bump and push an annotated git tag vX.Y.Z
• Create a GitLab Release under Deployments → Releases
• Update release/CHANGELOG.md and release/versions/pypi.json

See release/README.md for full pipeline and variable documentation.