Metadata-Version: 2.4
Name: inferrouter
Version: 0.1.3
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
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
```

Next:

```text
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](docs/ROUTER_PRODUCT_ARCHITECTURE.md)
2. [Progress tracker](docs/ROUTER_PROGRESS.md)
3. [MVP ship-now prompt](docs/prompts/inferrouter-mvp-ship-now-v1.md)
4. [Current SSoT](docs/ROUTER_CURRENT_SOT.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. [Touchdown Labs research bridge](docs/TOUCHDOWN_LABS_RESEARCH_BRIDGE.md)

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

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

After the first PyPI publication for the current package version:

```bash
uv tool install inferrouter
```

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

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