Metadata-Version: 2.4
Name: inferrouter
Version: 0.1.1
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"
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 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

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

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

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

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

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

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

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

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

## License

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