Wayfinder Router

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.