Metadata-Version: 2.4
Name: inferrouter
Version: 0.1.5
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/)

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

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

```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.5 universal coordinator source candidate: typed lanes, bounded DAGs, external
executors, checkpoint re-planning, independent review, and hash-linked receipts
```

Next:

```text
1. freeze the versioned candidate commit and repeat the green release ladder in CI
2. authenticate and live-probe at least two independent execution/review lanes
3. run mixed-lane canaries, failure drills, and package rollback rehearsal
4. measure accepted-task cost and latency against the fixed workflow baseline
5. publish, reinstall from PyPI, repeat the canary, then promote proven lanes
```

The source candidate is versioned `0.1.5` in the worktree. That is not a PyPI or
production-deployment claim. The current published `0.1.4` boundary remains the
fixed four-phase workflow described below until the coordinator package,
live-canary, and rollback receipts complete.

## 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)

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

The current published release is:

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

The full Python and Worker suites, strict Worker dry-run, wheel, sdist, Twine,
isolated pip installs, and isolated `uv tool` package smokes pass locally. The
candidate must repeat those gates in CI, be live-canary tested, be rolled back
to the command above, and be restored before it can be published as `0.1.5`.

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, or an API/SDK caller; it does not yet auto-intercept native
Codex or Claude tasks. All three 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.

```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 codex \
  --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 codex \
  --json
```

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.

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.

## 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).
