inferrouter 0.1.4

Loop-aware router and tracing for coding agents (Claude Code, Codex). Routes workflow steps by phase and evidence and records hash-only cost/cache/verification/outcome receipts.

InferRouter

Loop-aware model routing and hash-only evidence for coding agents such as Claude Code and Codex.

Status: alpha. The package, import, and CLI are all inferrouter. InferGuard is a separate diagnostics product.

MVP

one coding task
→ one observed coding loop
→ safe model/provider choices by phase
→ tools and tests
→ verification
→ accepted or rejected result
→ one complete hash-only receipt chain

Primary metric: cost per accepted patch at required quality and p95/p99 full-loop latency.

Current milestone

Built:

request-level gateway and protocol adapters
hard tenant/capability/protocol/tool/context/latency gates
provider cooldown and bounded affinity
pre-first-byte fallback
spend controls and hash-only receipts
loop, verification, and outcome ledgers
TaskEnvelopeV1 and ContextFingerprintV1
cross-runtime canonicalization and tenant-scoped fingerprints

Next:

1. Packet 1B receipt observability
2. accepted-task baseline-versus-routed canary
3. one provider-reported cache experiment
4. one second-provider outage drill
5. bounded worker lifecycle

Read first

1. Product architecture
2. Progress tracker
3. MVP ship-now prompt
4. Current SSoT
5. Machine-readable status database
6. Archive lessons and integration plan
7. Touchdown Labs research bridge

Use docs/ROUTER_MASTER_SOT.md, the runbook, and audit files for detailed chronology and historical deployment evidence.

Repository boundary

OCWC22/inferrouter
  = product/runtime authority

OCWC22/Touchdown-Labs
  = company/research authority

InferGuard
  = separate diagnostics product

See TOUCHDOWN_LABS.md.

Install

uv tool install .
# or
pip install .

After the first PyPI publication for the current package version:

uv tool install inferrouter

This installs inferrouter and inferrouter-routerd.

Phase-routed Codex workflow

Install the isolated gateway profile once, then run one bounded coding task:

inferrouter install codex

mkdir -p ~/.touchdown/subscription_codex_home
chmod 700 ~/.touchdown/subscription_codex_home
CODEX_HOME=~/.touchdown/subscription_codex_home codex login

inferrouter workflow \
  --goal 'Implement the requested repository change and preserve existing behavior.' \
  --verify 'python3 -m pytest -q'

The command uses the Touchdown API gateway for read-only planning, a dedicated persistent Touchdown Codex home for ChatGPT-subscription implementation, the operator-supplied local command for verification, and the API gateway for read-only final review. The dedicated profile gets its own separate initial ChatGPT login, so OAuth refreshes persist there and normal ~/.codex is never used as a workflow profile. Revocation or logout can require signing in again. The workflow fails unless implementation, verification, repository/config integrity, and the exact final review verdict all pass. This MVP is for trusted/private repositories; implementation tools can read their own dedicated Codex authentication file.

The executable Markdown contract is inferrouter/workflows/PRODUCTION_PHASE_WORKFLOW.md. Print the contract shipped in the installed package with:

inferrouter workflow --print-spec

Coding-loop quickstart

inferrouter loop goal \
  --loop-id fix_auth_tests \
  --goal "auth tests pass" \
  --verify "python -m pytest tests/auth -q" \
  --max-turns 5 --agent codex \
  -- codex exec "fix the failing auth tests"

Hash-only local evidence is written under .touchdown/:

.touchdown/loops/loop_runs.jsonl
.touchdown/loops/verifications.jsonl
.touchdown/session.json

Other commands:

inferrouter loop turn --agent generic -- <command>
inferrouter loop report [--loop-id L]
inferrouter loop usage [--by loop|task|phase|provider|model]
inferrouter doctor --split
inferrouter --help

Claude Code and Codex launchers

inferrouter claude -- -p "summarize the failing test log"
inferrouter codex -- summarize the failing test log

The split proxy is explicit and self-managed:

inferrouter proxy status
inferrouter proxy stop

The gateway routes API requests. It does not silently intercept every local prompt and does not create subagents by itself.

Production gateway

The documented gateway is:

https://touchdown-router.odd-star-67a4.workers.dev

Request path:

customer request
→ tenant/capability/protocol/tool/context/latency gates
→ cheapest viable configured route
→ bounded provider fallback
→ protocol-correct stream
→ hash-only receipt

Repository main may be ahead of the live Worker. A merged feature is not a deployment claim. Use the progress tracker and runbook for current live evidence.

Safety defaults

• Package-local commands make no live provider call unless explicitly configured.
• Raw prompts, source code, tool content, outputs, and credentials stay out of receipts and reports.
• Unsupported protocol semantics fail closed.
• Fallback happens only before client-visible output.
• Cost never overrides tenant, safety, capability, protocol, tool, context, or latency eligibility.

Development

python -m pytest -q
uv build
bash scripts/package_smoke.sh

The import package, distribution name, and CLI command are all inferrouter.

Contributing

See CONTRIBUTING.md, Code of Conduct, and SECURITY.md.

License

Apache License 2.0. See LICENSE and NOTICE.