agentleFS
strikersamstrikersam/autonomous-ai-agency/router/CLAUDE.md

autonomous-ai-agency / router

CLAUDE.md12 starsChanged 29 days agoMITView on GitHub

Model routing affects every request in the system. The invariants you must not break are CLAUDE.md rules 21–23. Read those first. This file covers how selection works and how to extend it. The central model-selection layer for all API surfaces. Selection priority, highest first: Local Ollama model names are passthrough: they bypass the alias table entirely and resolve to RoutingDecision(selection_source="passthrough"). The health check is cached with TTL ROUTER_HEALTH_CACHE_TTL (default 60s). The cache is deliberately invalidated before fallback retries — that…

The file

We split this CLAUDE.md into the rules it gives an agent

9 rules. About 0 are common, 2 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    No "done" without an independent verifier (pstack): Before any task is reported done, by a coding agent or by an agency agent, a verifier …

    line 12
  2. Very specific:

    Add an entry to MODEL_REGISTRY in registry.py.

    line 58
  3. Very specific:

    Add a routing test in tests/test_model_router.py (rule 23).

    line 61
  4. Very specific:

    Update docs/architecture/overview.md if the capability profile changes.

    line 62
  5. Very specific:

    Add the category string to classifier.py.

    line 66
  6. Distinctive:

    Add its matching logic — keyword, heuristic, or metadata.

    line 67
  7. Very specific:

    Add tests under "Task classification" in tests/test_model_router.py.

    line 69
  8. Very specific:

    All router tests are in tests/test_model_router.py:

    line 89
  9. Very specific:

    Always cover after a change: manual override still wins.

    line 95

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md — router/

Model routing affects every request in the system.

The invariants you must not break are CLAUDE.md rules 21–23. Read those first. This file covers how selection works and how to extend it.

Verification rule (mirrored from CLAUDE.md §2, binding on every agent)

<!-- pstack-verification:start -->
  1. No "done" without an independent verifier (pstack). Before any task is reported done, by a coding agent or by an agency agent, a verifier that did not write the change tries to break it. It exercises the real artifact (runs the feature, the tests, the built page; not "it compiles", not the author's own report) and returns PASS, PASS+NOTES, or FAIL with a report: what it checked, what it found broken, what was fixed, and the evidence (command output; screenshots for any UI change). FAIL sends the work back: fix every defect it found, then verify again, until it passes. Only PASS or PASS+NOTES permits a done claim, and the report quotes that verdict. Work in small units that each end in a check. Agency tasks enforce this in code (tasks/verification.py, live control TASK_VERIFICATION_REQUIRED). Source: pstack's principle-prove-it-works and its independent per-PR verdict (github.com/cursor/plugins/tree/main/pstack, github.com/michael-denyer/pstack-claude). This rule is mirrored byte-for-byte in every agent instruction file; python scripts/check_verification_rule.py fails if a copy drifts.
<!-- pstack-verification:end -->

What this package does

The central model-selection layer for all API surfaces.

FileRole
model_router.pyModelRouter.route() → RoutingDecision
classifier.pyclassify_task() → task category string
registry.pyModel capability registry, best_model_for()
health.pyOllama /api/tags health check with TTL cache

Selection priority, highest first:

  1. Manual override — X-Model-Override header or override_model kwarg
  2. MODEL_MAP env var, or the built-in Anthropic alias table
  3. Heuristic — task classification into a capability-registry lookup
  4. Default — AGENT_EXECUTOR_MODEL

Local Ollama model names are passthrough: they bypass the alias table entirely and resolve to RoutingDecision(selection_source="passthrough").

The health check is cached with TTL ROUTER_HEALTH_CACHE_TTL (default 60s). The cache is deliberately invalidated before fallback retries — that is not a bug.


Adding a model

  1. Add an entry to MODEL_REGISTRY in registry.py.
  2. Set strengths accurately — it drives heuristic selection.
  3. Set cost_tier (1 = cheapest) — it drives fast-response routing.
  4. Add a routing test in tests/test_model_router.py (rule 23).
  5. Update docs/architecture/overview.md if the capability profile changes.

Adding a task category

  1. Add the category string to classifier.py.
  2. Add its matching logic — keyword, heuristic, or metadata.
  3. List the category in strengths on the MODEL_REGISTRY entries that serve it.
  4. Add tests under "Task classification" in tests/test_model_router.py.

Environment variables

VariableEffect
MODEL_MAPColon-separated alias overrides, e.g. claude-sonnet-4-6:deepseek-r1:32b
ROUTER_EXTRA_MODELSAdd models at runtime: name:type:strength1+strength2
ROUTER_HEALTH_CHECK_ENABLEDfalse disables health filtering (useful in tests)
ROUTER_HEALTH_CACHE_TTLHealth cache TTL in seconds (default 60)
DENIED_MODEL_IDSOperator deny-list (packages/ai/model_policy.py): route() moves a denied resolved_model to the next allowed fallback and drops denied ids from fallback_chain; if every option is denied the decision is left unchanged so resolved_model stays non-empty (rule 21) and dispatch refuses it
ROUTER_FAST_RESPONSE_CHARSChar threshold for fast_response classification (default 200)
AGENT_EXECUTOR_MODELFinal fallback when nothing else resolves

Testing

All router tests are in tests/test_model_router.py:

pytest -x tests/test_model_router.py

Always cover after a change: manual override still wins; the built-in alias table maps correctly; heuristic fallback fires when no alias matches; health-check bypass works with ROUTER_HEALTH_CHECK_ENABLED=false; reset_router() isolates the singleton between tests.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.