planwise 0.1.0

PlanWise Router — intelligent tool routing layer for large tool catalogs

PlanWise Router

An intelligent tool-routing layer for large tool catalogs (60+ tools). Instead of showing an AI agent every tool schema — which wastes tokens and causes wrong picks between look-alike tools — PlanWise reads the user's query, writes a step-by-step plan, and hands the agent only the 3–6 tools it actually needs, in the right order.

Built for the Crest Data AI Innovation Challenge (Problem 02).

How it works (short version)

1. Offline: every tool passes quality gates, gets ~8 LLM-written example user questions, and is indexed (embeddings + keywords). Twin tools are grouped; version families (v1/v2) are linked.
2. Runtime: one cheap LLM call breaks the query into abstract steps (it never sees tool names, so it can't invent one). Each step finds its best tool with a 4-signal score: meaning match + keyword match + input fit + output fit (what the tool returns vs what the step needs — this is how same-input twins get told apart).
3. Hand-off: the agent gets the few chosen tool schemas plus a plan hint like Suggested plan: 1) get_revenue_report 2) generate_chart 3) send_email.

Full design: docs/HLD.md · docs/LLD.md · docs/architecture-diagram.html

Quick start

pip install -e ".[dev]"          # or: pip install -e . for the minimal core

export $(grep -v '^#' .env | xargs) # if inside venv

# Route one query against the sample catalog
planwise route "Pull last quarter's revenue and email the chart to [e-mail]"

# Run the evaluation harness (with the naive baseline to beat)
planwise eval --baseline

Works fully offline out of the box: with no gateway configured it uses a rule-based planner and lexical embeddings. For the real pipeline (LLM planner + semantic embeddings), point it at the Crest AWS Bedrock gateway (OpenAI-compatible):

pip install -e ".[llm,embeddings]"
export PLANWISE_LLM_API_KEY=sk-...                     # your gateway key
export PLANWISE_LLM_CERT=/path/to/apiproxy.cdsys.crt   # internal-CA cert from IT
# must be on the Crest network / VPN
planwise eval --baseline

All LLM traffic goes through planwise/engine/llm.py (one place). The key and cert path come from the environment — never hardcoded or committed. Default models: Bedrock-ant-haiku-4-5-20251001-v1-0 for the planner/enrichment.

Layout

• planwise/engine/ — the routing engine (pure library: intake, index, planner, scorer, binder, assembler)
• planwise/middleware/ — self-healing execution wrapper (Tier 2)
• planwise/server.py — HTTP gateway (Tier 1), planwise/mcp_server.py — MCP surface (Tier 3)
• eval/ — evaluation harness, stress suites, baselines
• data/ — sample catalog + ground-truth queries (replaced by the organizers' files at hackathon start)

Tests

python -m pytest tests/

Tests run deterministic and offline (hashing embeddings, rules planner) — no downloads, no API keys.