Metadata-Version: 2.4
Name: route66
Version: 2.0.3
Summary: route66 Python SDK
Author: route66 maintainers
License: Proprietary
Keywords: route66,sdk
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: bedrock
Requires-Dist: httpx>=0.27; extra == 'bedrock'
Provides-Extra: bench
Requires-Dist: anthropic>=0.34; extra == 'bench'
Provides-Extra: chroma
Requires-Dist: chromadb>=0.5; extra == 'chroma'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: semantic
Requires-Dist: sentence-transformers<5.0,>=4.0; extra == 'semantic'
Description-Content-Type: text/markdown

# 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`](./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`](./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`](./docs/architecture/components.md)**
  — module dependency graph, per-module code map, and extension points.
- **[`docs/PRD.md`](./docs/PRD.md)** and
  **[`docs/hackathon-definition.md`](./docs/hackathon-definition.md)**
  — original problem statement and PRD.
- **[`docs/chroma-and-mcp-sync.md`](./docs/chroma-and-mcp-sync.md)**
  — setup and testing guide for the optional Chroma DB vector store and
  the MCP tool-sync feature.
- **[`specs/`](./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`](https://docs.astral.sh/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`](./router-testkit/) —
  standard-library only
- **Tooling:** Ruff (lint + format), pytest, pre-commit

## Setup & Run Instructions

```bash
# 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

```bash
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](https://pypi.org/project/route66/), tags the
  commit, and appends to `release/CHANGELOG.md`.

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

## Additional Links / Resources

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