Metadata-Version: 2.4
Name: route66
Version: 2.0.1
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: 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: semantic
Requires-Dist: sentence-transformers<5.0,>=4.0; extra == 'semantic'
Description-Content-Type: text/markdown

# 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`](./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

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

```bash
uv run ruff check .
uv run ruff format .
uv run pytest
```

## Release

Releases are published to [PyPI](https://pypi.org/project/route66/) 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`](./release/README.md) for full pipeline and
variable documentation.
