route66 2.0.1

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.

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.