# Wayfinder Router

> A fast, offline, deterministic prompt router that scores prompt complexity and routes easy prompts to local/small models and hard ones to cloud/large models — no model call required.

Wayfinder Router is an open-source Python library and CLI tool that routes LLM prompts between local and hosted models based on a deterministic complexity score — without making any model call to decide the route. It was split out from a larger requirements tool because, as the README explains, "routing is a runtime concern, not a knowledge one." The project is licensed under Apache 2.0 and available on PyPI as `wayfinder-router`.

## What It Is

Wayfinder Router sits in front of any OpenAI-compatible client and scores each incoming prompt's structure (length, headings, lists, code blocks) and optionally its wording (proof terms, math symbols, constraint language) into a `0.0`–`1.0` complexity score. Based on a configurable threshold or tier ladder, it forwards easy prompts to a cheap local model (Ollama, vLLM, LM Studio, llama.cpp) and hard ones to a hosted model (OpenAI, Anthropic, Gemini, Mistral, etc.). The decision is sub-millisecond, fully offline, and produces the same result every time for the same input — no API key, no network round-trip, no randomness.

## How the Routing Decision Works

Unlike most routers that call a trained classifier or LLM judge to decide where to send a prompt, Wayfinder reads structural and lexical features directly:

- **Structural features**: word count, heading count, list item count, code block presence
- **Lexical features (opt-in)**: reasoning terms, math symbols, constraint terms — shipped off by default because a double-blind benchmark showed the lift doesn't generalize reliably
- **Three routing modes**: binary threshold (single cut), tiered (N-tier score bands mapped to N models), and classifier (fitted multinomial-logistic model from calibration data)
- **Per-request overrides**: the `model` field acts as a routing directive (`auto`, `local`, `cloud`, `prefer-local`, `prefer-hosted`); an `X-Wayfinder-Threshold` header re-cuts the decision for one request

The README is explicit about tradeoffs: Wayfinder is no better than random on RouterBench's short-but-hard items, and a prompt whose difficulty is purely semantic has no structural tell — a semantic router will beat it there.

## Deployment Model

Wayfinder exposes an OpenAI-compatible gateway (`/v1/chat/completions`) so any existing client, agent framework, or IDE assistant just changes one `base_url`. It also exposes a `/v1/messages` adapter for Claude Code (Anthropic Messages API ↔ OpenAI translation, streaming and tool use included).

Supported deployment paths include:
- **CLI**: `wayfinder-router serve` runs the gateway; `wayfinder-router chat` opens a terminal chat with routing decisions shown per turn
- **Docker**: a Dockerfile and `docker-compose.example.yml` are included for sidecar or standalone service deployment
- **In-process Python API**: `from wayfinder_router import score_complexity` — the scoring core has no dependencies beyond the standard library
- **Local web UI**: `wayfinder-router ui` for interactive explain, calibrate, configure, and onboard workflows

Compatible integrations documented in the repo include Open WebUI, LibreChat, Jan, Continue, Cline, Zed, JetBrains, LangChain, LlamaIndex, CrewAI, AutoGen, OpenAI Agents SDK, Vercel AI SDK, aider, Copilot CLI, and LiteLLM.

## Calibration and Feedback Loop

Wayfinder includes a full offline calibration pipeline so operators can tune the routing cut to their own traffic:

- `wayfinder-router calibrate` reads a labeled JSONL dataset and fits a threshold, tier ladder, or classifier using deterministic L2-regularized Newton/IRLS — no model call, pure Python
- `wayfinder-router onboard` runs A/B comparisons between two model arms and collects human judgments to build a labeled dataset
- `wayfinder-router judge` automates labeling using a deterministic text comparator with trust gates (Cohen's κ ≥ 0.6, out-of-fold lift, both arms represented) — it refuses to emit a config if gates fail
- `wayfinder-router recalibrate` re-fits from a feedback log on a schedule and hot-reloads the result into a running gateway with no restart
- A `/v1/feedback` endpoint accepts thumbs-up/thumbs-down judgments from any client

## Update: Version 2026.6.10 — The "Feedback" Release

The latest release, version 2026.6.10 (published 2026-06-29), is named the "feedback" release, signaling that the feedback loop, recalibration, and automated judging pipeline are the primary additions in this version. The repository was created in June 2026 and has been actively pushed to, with 282 stars and 16 forks as of the last update. The project is in active development with 3 open issues.

## Features
- Deterministic offline prompt complexity scoring (0.0–1.0)
- No model call required to make routing decision
- Binary threshold, N-tier ladder, and classifier routing modes
- OpenAI-compatible gateway (drop-in base_url replacement)
- Anthropic Messages API adapter for Claude Code
- Terminal chat UI with per-turn routing decisions and savings tracking
- Local web UI for explain, calibrate, configure, and onboard
- Offline calibration via labeled JSONL dataset (Newton/IRLS)
- Automated judging with trust gates (Cohen's κ ≥ 0.6)
- Feedback endpoint and hot-reload recalibration
- Per-request routing overrides via model field and X-Wayfinder-Threshold header
- Slash directives for chat-based routing control
- Secret management via env vars or vault commands (1Password, macOS Keychain, etc.)
- Production features: timeouts, retries, circuit breaker, failover, budget cap, cache, rate limiting, virtual API keys
- Dependency-free scoring core (standard library only)
- Docker and docker-compose support
- Python API for in-process scoring

## Integrations
OpenAI, Anthropic Claude, Google Gemini, Mistral, Ollama, Groq, Together AI, OpenRouter, Fireworks, DeepSeek, vLLM, LM Studio, llama.cpp, LangChain, LlamaIndex, CrewAI, AutoGen, OpenAI Agents SDK, Vercel AI SDK, LiteLLM, Open WebUI, LibreChat, Jan, Continue, Cline, Zed, JetBrains, aider, Copilot CLI, 1Password, macOS Keychain, HashiCorp Vault, AWS Secrets Manager, Doppler

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, JETBRAINS_PLUGIN, CLI

## Pricing
Open Source

## Version
2026.6.10

## Links
- Website: https://github.com/itsthelore/wayfinder-router
- Documentation: https://github.com/itsthelore/wayfinder-router/blob/main/docs/faq.md
- Repository: https://github.com/itsthelore/wayfinder-router
- EveryDev.ai: https://www.everydev.ai/tools/wayfinder-router