Metadata-Version: 2.4
Name: inferrouter
Version: 0.1.7
Summary: 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.
Author: Touchdown Labs
Maintainer: Touchdown Labs
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/OCWC22/inferrouter
Project-URL: Repository, https://github.com/OCWC22/inferrouter
Project-URL: Issues, https://github.com/OCWC22/inferrouter/issues
Project-URL: Changelog, https://github.com/OCWC22/inferrouter/blob/main/CHANGELOG.md
Keywords: llm,inference,router,routing,coding-agent,claude-code,codex,observability,tracing,cost-optimization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: cryptography>=46
Requires-Dist: PyYAML>=6
Requires-Dist: tomli>=2; python_version < "3.11"
Provides-Extra: schema
Requires-Dist: jsonschema>=4; extra == "schema"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: jsonschema>=4; extra == "dev"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
Dynamic: license-file

# InferRouter

[![Tests](https://github.com/OCWC22/inferrouter/actions/workflows/test.yml/badge.svg)](https://github.com/OCWC22/inferrouter/actions/workflows/test.yml)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)

Phase-, risk-, and role-aware model routing with joined cost and verification
receipts for coding agents such as Claude Code and Codex.

> **Status: alpha package; production-live fixed four-phase MVP Worker.** The package, import, and CLI are all `inferrouter`. InferGuard is a separate diagnostics product.

## Core workflow

```text
prompt + bounded repository context
→ phase + risk + required agent role (Fusion/semantic policy)
→ eligible model + provider + billing lane + reasoning effort
→ readable frontier plan
→ cheaper implementation steps or subagents
→ deterministic local verification
→ bounded retry, escalation, or re-plan
→ independent frontier review
→ accepted or rejected result
→ one joined token, cost, latency, and verification receipt
```

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

The Devin Fusion-style role decision is the first hard gate. OpenRouter-style
provider, billing, and runtime selection happens only inside the eligible role
set. Semantic-router signals are explicit Boolean eligibility gates, not a
single prompt-complexity score. OpenRouter Fusion panel/judge deliberation is a
future optional escalation lane, not the default path. Claudex is an optional
compatibility bridge and is not part of this core router path.

## Current milestone

Built:

```text
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
0.1.6 published PyPI rollback baseline: canonical Fusion/semantic role gate,
bounded repository planning context, and joined workflow usage/cost
0.1.7 candidate adds first-class OpenRouter routing, current OpenCode usage,
and the installed deterministic plus opt-in live mixed-lane release gate
production fixed four-phase Worker 89f59b62 at 100%, source annotation 34a2d76,
with rollback Worker 84992285 retained at 0%
optional experimental Claudex compatibility path: isolated opt-in launcher,
15-case deterministic evaluator, and explicit bounded live canaries/benchmark
```

Next:

```text
1. merge and trusted-publish the verified 0.1.7 candidate
2. clean-install the public artifact and rerun the installed mixed-lane gate
3. expand accepted-task economics and failure drills without enabling unproven lanes
```

`inferrouter==0.1.6` remains the latest public package. Its exact-source Worker
is live at 100% after
three 80/80 candidate reports,
4/4 real-Codex conformance with ten zero-fallback receipts, a passing
Terra-plan/ChatGPT-implementation/local-verify/GPT-5.5-review workflow, a
zero-error 10% traffic sample, a successful rollback/forward-restore rehearsal,
an isolated `0.1.6 -> 0.1.5 -> 0.1.6` package rehearsal, and post-promotion
convergence. The public `0.1.6` wheel then passed a clean install, workflow,
downgrade to public `0.1.5`, forward restore, and a second workflow run.
The `0.1.7` candidate separately passed one accepted live universal workflow:
exact OpenRouter Opus 4.8 planning, lower-cost exact Sonnet 4.6 execution,
sandboxed local verification, independent exact Opus review, zero fallback,
3,682 tokens, `$0.037006` provider-reported cost, and one valid 26-event
receipt. Public package publication and clean-install proof are still pending.
Claudex remains experimental, separately installed, and never a core/default
lane.

## Read first

1. [Current SSoT](docs/ROUTER_CURRENT_SOT.md)
2. [Universal coordinator executable contract](inferrouter/workflows/UNIVERSAL_COORDINATOR_WORKFLOW.md)
3. [Product architecture](docs/ROUTER_PRODUCT_ARCHITECTURE.md)
4. [Progress tracker](docs/ROUTER_PROGRESS.md)
5. [Machine-readable status database](docs/ROUTER_STATUS_DATABASE.json)
6. [Archive lessons and integration plan](docs/ROUTER_ARCHIVE_LESSONS_AND_INTEGRATION_PLAN.md)
7. [Historical pre-0.1.4 ship-now prompt](docs/prompts/inferrouter-mvp-ship-now-v1.md)
8. [Touchdown Labs research bridge](docs/TOUCHDOWN_LABS_RESEARCH_BRIDGE.md)
9. [Experimental Claudex compatibility bridge](docs/CLAUDEX_COMPATIBILITY_BRIDGE.md)
10. [Packaged Claudex compatibility workflow](inferrouter/workflows/CLAUDEX_COMPATIBILITY_WORKFLOW.md)

Use `docs/TOUCHDOWN_ROUTER_RUNBOOK.md` for current Worker operations,
`docs/production-runbook.md` for the explicitly labeled legacy offline/replay
surface, and `docs/ROUTER_MASTER_SOT.md` plus audit files for chronology.

## Repository boundary

```text
OCWC22/inferrouter
  = product/runtime authority

OCWC22/Touchdown-Labs
  = company/research authority

InferGuard
  = separate diagnostics product
```

See [TOUCHDOWN_LABS.md](TOUCHDOWN_LABS.md).

## Install

```bash
uv tool install .
# or
pip install .
```

Install the current release with:

```bash
uv tool install 'inferrouter==0.1.6'
```

PyPI SHA-256: wheel
`9a1df374f7ceb4d130b8467f4391f1ea41e6f1f561046b130f568e41ba29a08d`;
sdist `ea96e631dd954857e995763f89b1762b0c95e9288a1c2fc3846014343067f876`.

For rollback, `0.1.5` remains immutable. Its published wheel SHA-256 is
`cb332238395112d51fd9fb59712651507d53e2a2fcdee1f689bcf6dbc1762844`; the sdist
SHA-256 is `e5d813f423b0614aafe278ee31d28e31a65d37aff41a9806aeb425cd9dd3cd68`.
Use that release as the isolated package rollback baseline.

This installs `inferrouter` and `inferrouter-routerd`.

## Universal coordinator

The coordinator is the cross-provider workflow the product is aiming at. It is
explicitly invoked with one CLI/SDK goal and records whether that goal came from
Codex, Claude Code, OpenCode, or an API/SDK caller; it does not auto-intercept
native client tasks. All four entry labels use the same bounded state machine.
The planner emits a validated DAG; every step is routed at a checkpoint to a
configured local, subscription, API, GMI, or registered OpenAI-compatible lane.
Local verification and an independent reviewer must pass before acceptance.
The automatic planner prompt contains only content-free counts, hashes, and root
fingerprints—not repository-controlled filenames or raw README, AGENTS,
manifest, status, or diff contents. Needed file inspection uses read-only tools.
The graph's operator-goal SHA-256 is trace binding only; a separate, explicit
per-run write gate is enforced outside the planner. Incremental Codex attribution
reconstructs model state only from bytes at or before the saved tail offset, so
later model context cannot relabel earlier token usage.

Prove the core policy and executor plumbing offline with the deterministic
installed-artifact evaluator. This uses the real coordinator, receipt store,
subprocess adapters, Git inspection, and sandboxed verifier, but fixture model
responses; it does not claim live provider authentication, entitlement, model
quality, or subscription billing:

```bash
python -m inferrouter.evals.production_workflow --json

# Release gate: fixture-safe by default; --live makes paid OpenRouter calls.
inferrouter eval mixed-lane --json
OPENROUTER_API_KEY=... inferrouter eval mixed-lane --live --json
```

```bash
inferrouter coordinator --print-spec

# Configuration/auth only. No model probe.
inferrouter coordinator doctor --json

# Also prove exact model identity, entitlement, and liveness for configured remote lanes.
inferrouter coordinator doctor --live --json

# Preflight and rank without a model/tool call.
inferrouter coordinator run \
  --goal 'Implement the requested change and prove it with tests.' \
  --workdir . \
  --entry-client opencode \
  --dry-run \
  --json

# Execute after at least one planner, one implementation lane, local verification,
# and an independent reviewer are ready.
inferrouter coordinator run \
  --goal 'Implement the requested change and prove it with tests.' \
  --workdir . \
  --entry-client opencode \
  --allow-writes \
  --json
```

Workspace writes are denied by default. `--allow-writes` is the operator's
per-run authorization for planner-selected worktree edits; the goal hash is
trace binding only and cannot grant that permission.

The packaged profile references credential environment-variable names; it does
not contain credential values. Codex uses the isolated
`~/.touchdown/subscription_codex_home`. Claude Code uses its native subscription
login with ambient API/cloud credentials removed. API and registered endpoint
keys resolve only inside their executor. Fable is excluded unless an exact-model
live probe succeeds; a silent native model fallback fails the lane.

### OpenCode provider path

The production-proven OpenCode path in this release is OpenCode to OpenRouter,
not OpenCode directly to the Touchdown Worker. Keep the key in the environment
and use an OpenCode custom provider such as:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "touchdown-openrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Touchdown OpenRouter",
      "options": {
        "baseURL": "https://openrouter.ai/api/v1",
        "apiKey": "{env:OPENROUTER_API_KEY}"
      },
      "models": {
        "anthropic/claude-opus-4.8": {"name": "Claude Opus 4.8"},
        "anthropic/claude-sonnet-4.6": {"name": "Claude Sonnet 4.6"}
      }
    }
  }
}
```

```bash
opencode run --pure --format json \
  --model touchdown-openrouter/anthropic/claude-sonnet-4.6 \
  'Implement the bounded task and run its tests.'
```

This direct provider path emits current OpenCode token and reported-cost events.
It is not automatic checkpoint routing by itself; use `inferrouter coordinator
run --entry-client opencode` for the full plan/execute/verify/review workflow.
Direct OpenCode-to-Worker streaming/tool execution remains disabled because its
current request shape fails upstream compatibility.

Private handoff text is stored outside the writable repository under
`~/.touchdown/inferrouter/coordinator/<run-id>/` with
owner-only permissions. `events.jsonl` contains only hash-linked metadata. Check
it independently with:

```bash
inferrouter coordinator verify-receipt \
  ~/.touchdown/inferrouter/coordinator/<run-id>/events.jsonl
```

That command proves canonical structure and hash-link integrity. The chain is
not yet signed or externally anchored, so a process with the same filesystem
ownership could still rewrite and rehash the entire history. Do not treat it as
third-party authenticity proof until a frozen terminal receipt is anchored.

The full behavioral contract is
[inferrouter/workflows/UNIVERSAL_COORDINATOR_WORKFLOW.md](inferrouter/workflows/UNIVERSAL_COORDINATOR_WORKFLOW.md).

Configured-only `doctor` proves a viable local workflow shape, not live
readiness. `doctor --live` probes configured remote lanes and returns top-level
`ok` only when it can prove an exact-model planner, a mutating executor, local
verification, and an independent exact-model reviewer. Operators must still
inspect every intended lane because top-level success does not mean every
configured lane passed. Codex requires a separate isolated exact-model canary
because the live doctor does not call Codex.

## Phase-routed Codex workflow

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

```bash
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](inferrouter/workflows/PRODUCTION_PHASE_WORKFLOW.md). Print the contract shipped in the installed package with:

```bash
inferrouter workflow --print-spec
```

## Coding-loop quickstart

```bash
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/`:

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

Other commands:

```bash
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

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

The split proxy is explicit and self-managed:

```bash
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.

An explicitly unsupported compatibility option can run the Claude Code shell
against Codex through a separately installed Claudex proxy:

```bash
inferrouter claudex setup --acknowledge-unsupported --model gpt-5.6-sol
inferrouter claudex doctor
inferrouter claudex launch -- -p "summarize the failing test log"

# Deterministic, no-network compatibility gate. Expected today: 15/15.
inferrouter eval claudex --out-dir out/evals/claudex

# Plan only by default; no paid or subscription request.
inferrouter benchmark claudex

# Explicit unsupported live gates. Requires exact reviewed Claudex and auth.
inferrouter eval claudex --live --acknowledge-unsupported
inferrouter benchmark claudex --live --acknowledge-unsupported --runs 3
```

The merged `0.1.6` source passes 1,038 Python tests, the core deterministic
phase-routed workflow eval, the Claudex 15/15 offline rubric, Twine validation,
and isolated Python 3.11 wheel, sdist, and `uv tool` smokes. CI repeats the
installed core workflow eval on macOS and makes the existing required
`python-tests` context fail if either the unit or workflow gate fails. The fixed
four-phase Worker path is live-proven; the universal coordinator's live
mixed-lane authentication, quality, and economics proof remains missing.

This is not automatic routing and is never installed or enabled by default.
The InferRouter guard rebuilds the child environment from a strict non-secret
allowlist; redirects Claudex, Claude, Codex, XDG, and temporary-file roots under
`~/.touchdown`; caps runtime and retries; denies known built-in
Agent/Task/workflow/cron fan-out tools; and writes a hash-only receipt. It does
not enforce a true global agent, process, request, or token cap. This is not an
OS sandbox: tools can still reach files under the inherited `HOME`, and
Bash/process/request/token fan-out is not proxy-enforced.
See [the compatibility boundary and production rubric](docs/CLAUDEX_COMPATIBILITY_BRIDGE.md).

## Production gateway

The documented gateway is:

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

Request path:

```text
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

```bash
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](CONTRIBUTING.md), [Code of Conduct](CODE_OF_CONDUCT.md), and [SECURITY.md](SECURITY.md).

## License

Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
