inferrouter 0.1.1

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 router and tracing for coding agents (Claude Code, Codex).

InferRouter wraps a coding-agent loop, routes each workflow step by phase and evidence, and records hash-only receipts for cost, cache, verification, and outcome. Real agent work is a loop that plans, retrieves context, calls tools, reads logs, generates output, verifies, retries, and stops when a condition is met. InferRouter measures the whole loop and keeps the outcome + cost evidence.

Status: alpha, Apache-2.0. The command, package, and import are all inferrouter. InferGuard is a separate, original diagnostics tool and is not this repo.

Install

# From a checkout of this repo (works today)
uv tool install .
# or
pip install .

# From PyPI (after first publish)
uv tool install inferrouter

This installs the inferrouter command (plus inferrouter-routerd).

Quickstart

Wrap any command as a goal loop with a verifier. The loop stops when the verifier passes or max-turns is reached, and writes receipts under .touchdown/:

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"

Receipts written (hash-only, never raw prompts/output/secrets):

.touchdown/loops/loop_runs.jsonl       # one LoopRunReceipt per run: status, turns, stop reason, cost
.touchdown/loops/verifications.jsonl   # one VerificationEvent per turn: pass/fail, output hash
.touchdown/session.json                # connector_session_id, workspace hash

Other commands:

inferrouter loop turn    --agent generic -- <command>     # single exploratory step
inferrouter loop every   --loop-id L --interval 0 --max-iterations 1 -- <command>
inferrouter loop report  [--loop-id L]                    # turns, task ids, verifier results, cost
inferrouter loop usage   [--by loop|task|phase|provider|model]
inferrouter --help

Architecture

The loop layer sits above a correlated task graph:

loop_id -> loop_run_id -> task_id -> step_id
  route -> capture -> provider-call -> verification -> outcome   (all hash-only receipts)

See docs/ARCHITECTURE.md for the full loop-aware architecture and the router doctrine (route by phase and evidence, not a static complexity score). Integration notes: docs/agent-install.md, docs/319-claude-code-loop-integration.md, docs/320-codex-loop-replication.md.

Safety defaults

• No network and no live provider calls by default. Live provider calls are gated behind explicit configuration plus a key.
• Receipts and ledgers store hashes only. Raw prompts, raw output, API keys, and secrets are never written to any receipt, ledger, report, or log. Ledgers actively reject unsafe keys.

Development

python -m pytest -q             # test suite
uv build                        # build wheel + sdist into dist/
bash scripts/package_smoke.sh   # build + clean-venv install + console-script smoke

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

Contributing

Contributions are welcome. See CONTRIBUTING.md, our Code of Conduct, and the security policy.

License

Apache License 2.0. See LICENSE and NOTICE.