route66 2.0.3

route66 Python SDK

route66

Team Information

• Team Lead: Het Shah
• Members: Rajdeep Kamani, Dharv Pandya, Harsh Maradia, Dhruv Fadadu, Devanshu Patel
• Note This is our development repo. - https://internalgitlab.cdsys.local/rajdeep.kamani/route66

Project Overview

route66 is an intelligent tool router for LLM agents. Given a query and a large tool catalog, it returns only the relevant tools — deduplicated, in an ordered execution plan, with policy-aware defaults (deprecation preference, out-of-scope refusal, clarify-on-vague- destructive). It is catalog-in and pure compute: it never opens a network connection, authenticates, or executes a tool. The caller keeps their own agent loop and credentials; route66 just picks which tools belong in the next prompt.

Built against the router-testkit 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.

The pipeline is a Facade over pluggable strategies (retriever, fuser, reranker, vector store, planner, capability provider, policy chain) — each injectable, each independently testable, each swappable via a constructor argument or an environment variable.

Demo Video

https://drive.google.com/drive/folders/1V85PW-WlZC20VsnLwYK-jUnP694jBzRT

One Pager Link

Technical Design / Architecture Decision Record

• 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.
• docs/architecture/components.md — module dependency graph, per-module code map, and extension points.
• docs/PRD.md and docs/hackathon-definition.md — original problem statement and PRD.
• docs/chroma-and-mcp-sync.md — setup and testing guide for the optional Chroma DB vector store and the MCP tool-sync feature.
• specs/ — spec-driven implementation plan; every module has acceptance criteria pinned to specific TC-* cases.

Inline summary

Query → grammar-driven plan split (rule-based, LLM optional) → for each step: dense (via a pluggable VectorStore) + BM25 + learned-association retrievers → reciprocal rank fusion → optional cross-encoder rerank (Bedrock Cohere or local sentence-transformers) → runtime near-duplicate resolution → cluster-hint reorder → capability filter → policy chain (PreferCurrent, NoToolOnOOS, ClarifyOnDestructiveVague) → pick.

Tech Stack

• Language: Python ≥ 3.14 (pinned in .python-version, managed by uv)
• Core: standard library only for the pipeline
• Embedding backends: built-in HashingEmbedder (zero-dep default), SentenceTransformerEmbedder (opt-in, --extra semantic), BedrockEmbedder (via internal gateway; TR_EMBEDDER=bedrock)
• Rerank backends: local CrossEncoderReranker (sentence- transformers) or BedrockReranker (Cohere rerank via gateway; TR_RERANKER=bedrock)
• Vector store: in-memory exact-cosine default; optional Chroma DB backend (--extra chroma, TR_VECTOR_STORE=chroma)
• Planner: rule-based RuleChainPlanner by default; optional LLMChainPlanner (Bedrock chat, fail-open) via TR_PLANNER=bedrock
• Catalog sync (opt-in): MCP client via the official mcp SDK (--extra mcp)
• Grading harness: router-testkit — standard-library only
• Tooling: Ruff (lint + format), pytest, pre-commit

Setup & Run Instructions

# 1. Clone and install (uv-managed).
git clone <this repo>
cd route66
uv sync                       # base install, zero extras

# Optional extras:
uv sync --extra semantic      # local sentence-transformers embedder
uv sync --extra chroma        # Chroma DB vector store
uv sync --extra mcp           # MCP client for live tool sync
uv sync --extra dev           # ruff + pytest + pre-commit

# 2. Score the reference baseline (sanity check).
cd router-testkit/harness
python run_benchmark.py --verbose

# 3. Score this project's router against the default suite.
python run_benchmark.py --router testkit_adapter:MyRouter --verbose

# 4. Score every suite in parallel and save per-suite logs to results/.
cd ../..
python results/run_all.py

Optional environment variables

Variable	Values	Effect
TR_EMBEDDER	bedrock | semantic | hashing	Which embedder to load (default: semantic → hashing fallback).
TR_RERANKER	bedrock | cross-encoder | unset	Enable a cross-encoder rerank stage (off by default).
TR_VECTOR_STORE	chroma | memory	Dense-retrieval backend (default: memory).
TR_PLANNER	bedrock | rule	Chain planner backend (default: rule).
TR_FORCE_HASHING	any value	Force HashingEmbedder even when semantic is installed.
TR_LOG	debug | info | warning | error	route66 logger level (default: WARNING).
TR_TRACE	any value	Print one line per routed query and bump logging to INFO.
BEDROCK_API_KEY	value	Required for any Bedrock backend.
BEDROCK_CA_CERT	path	Required for any Bedrock backend.

Dev commands

uv run ruff check .           # lint
uv run ruff format .          # format
uv run pytest                 # full test suite (Bedrock-live tests skip when credentials absent)

CI / release pipeline

route66 ships with a GitLab CI pipeline that runs on every push and publishes releases to PyPI:

• .gitlab-ci.yml — lint → test → build on every non-master branch and MR. Same checks run locally via pre-commit.
• ci/release.gitlab-ci.yml — a manually-triggered child pipeline on master. It bumps src/route66/_version.py, builds wheel + sdist, publishes to PyPI, tags the commit, and appends to release/CHANGELOG.md.

See release/README.md for the full release knobs (BUMP, VERSION, RELEASE_NOTES).

Additional Links / Resources

• PyPI package: pypi.org/project/route66 — pip install route66
• How to use route66 via pip (with provider snippets): docs/pip-usage.md
• Grading contract: router-testkit/README.md
• Chroma + MCP setup guide: docs/chroma-and-mcp-sync.md
• Original PRD: docs/PRD.md
• Problem statement: docs/hackathon-definition.md
• Release process: release/README.md
• GitLab CI pipeline: .gitlab-ci.yml (lint / test / build) + ci/release.gitlab-ci.yml (PyPI publish, tag, changelog)
• Demo script (60-tool toy catalog): python demo.py
• Extra benchmarks (baseline, mutations, guardrail): bench/
• Per-suite result logs: results/

Repository Layout

route66/
├── src/route66/          # The library (facade + retrievers + policy + vector store + MCP sync)
├── testkit_adapter.py    # Bridges route66 to the harness contract
├── demo.py               # Toy 60-tool catalog demo
├── metrics.py            # Recall / precision / token-savings eval
├── router-testkit/       # Grading kit (catalog + test cases + harness)
├── bench/                # Additional benchmarks
├── specs/                # Spec-driven implementation plan
├── docs/                 # PRDs, architecture docs, feature guides
├── results/              # Per-suite benchmark logs + run_all.py driver
└── tests/                # Unit tests