Metadata-Version: 2.4
Name: agent-wire-proxy
Version: 0.1.0
Summary: Protocol bridge for OpenAI Responses, Chat Completions, and Anthropic Messages clients.
Author: Agent Wire Proxy contributors
License-Expression: MIT
License-File: LICENSE
Keywords: agents,anthropic,api-proxy,llm,openai,vllm
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: certifi>=2024.8.30
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == 'dev'
Requires-Dist: ruff<1,>=0.12; extra == 'dev'
Description-Content-Type: text/markdown

# Agent Wire Proxy

A lightweight compatibility proxy that lets OpenAI Responses, OpenAI Chat
Completions, and Anthropic Messages clients share Qwen/vLLM backends.

> [!IMPORTANT]
> Agent Wire Proxy is an alpha-stage compatibility layer. Review the
> [compatibility contract](docs/compatibility.md) before relying on it in a
> production path, and put authentication and TLS in front of non-localhost
> deployments.

It is useful when:

- Codex expects `/v1/responses`, but a backend only exposes Chat Completions.
- Claude Code needs an Anthropic Messages-compatible gateway.
- several model IDs must route through one local proxy port.
- streaming text, tool calls, usage, and timing must survive protocol conversion.

## Requirements

- Python 3.11+
- one or more OpenAI-compatible model backends
- Codex or Claude Code only when using the optional TUI launcher

## Install

Install the published package from PyPI:

```bash
python3 -m pip install agent-wire-proxy
```

Or install from a repository checkout for development:

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -e .
```

For development:

```bash
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest
.venv/bin/python -m ruff check .
```

## Configure models

Routes live in [`config/models.toml`](config/models.toml):

```toml
[proxy]
default_model = "Qwen3.5-397B-FP8"

[[models]]
id = "Qwen3.5-397B-FP8"
target = "http://127.0.0.1:8000"
upstream_api = "responses"
aliases = ["claude-qwen3-5-397b"]

[[models]]
id = "qwen3.5-122b-a10b"
target = "http://127.0.0.1:8001"
upstream_api = "chat_completions"
aliases = ["claude-qwen3-5-122b"]
```

For machine-specific routes, copy it to the Git-ignored
`config/models.local.toml`; the helper scripts prefer that file when it exists.

Use `api_key_env = "UPSTREAM_API_KEY"` for an authenticated upstream. Put the
value in an ignored `.env` file:

```bash
cp .env.example .env
```

## Run the proxy

The lifecycle helper runs the proxy in the background on
`http://127.0.0.1:18009`:

```bash
scripts/agent_wire_proxy.command start
scripts/agent_wire_proxy.command status
scripts/agent_wire_proxy.command restart
scripts/agent_wire_proxy.command stop
```

It reads `config/models.toml` and `.env`, and writes runtime files under
`logs/`. Override `LISTEN`, `CONFIG`, `ENV_FILE`, `LOG_PATH`, `PID_PATH`, or
`STDOUT_PATH` when needed.

You can also run the installed CLI in the foreground:

```bash
agent-wire-proxy \
  --listen 127.0.0.1:18009 \
  --config config/models.toml \
  --env-file .env
```

The installed package also exposes a reentrant API. Each returned server owns
its routing state, so multiple differently configured proxies can run in the
same process:

```python
from agent_wire_proxy import serve

proxy = serve(
    config="config/models.toml",
    listen=("127.0.0.1", 0),
    block=False,
)
print(proxy.server_port)

# Later:
proxy.shutdown()
proxy.server_close()
```

Check health and model discovery:

```bash
curl -fsS http://127.0.0.1:18009/health
curl -fsS http://127.0.0.1:18009/v1/models
```

## Launch Codex or Claude Code

Choose an agent and configured model interactively:

```bash
agent-wire-tui
```

Or select them directly:

```bash
# Codex + Qwen 397B
agent-wire-tui --agent codex --model Qwen3.5-397B-FP8

# Claude Code + Qwen 397B
agent-wire-tui --agent claude --model claude-qwen3-5-397b
```

The launcher injects temporary client settings. It does not modify the user's
Codex configuration. It is also available as
`launch(agent="codex", model="Qwen3.5-397B-FP8")` from Python. Run
`agent-wire-tui --help` for all options. The legacy `scripts/agent_wire_tui.command`
wrapper uses the installed CLI when available and otherwise runs from the
source checkout.

Unless `--config` is supplied, the launcher checks `AGENT_WIRE_PROXY_CONFIG`, then
`config/models.local.toml` and `config/models.toml` under the current directory,
then `$XDG_CONFIG_HOME/agent-wire-proxy/models.toml` (or the equivalent
under `~/.config`), and finally the packaged default configuration.

## Supported endpoints

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/health` | Health check |
| `GET` | `/v1/models` | OpenAI, Codex, and Claude model discovery |
| `POST` | `/v1/responses` | OpenAI Responses |
| `POST` | `/v1/chat/completions` | OpenAI Chat Completions |
| `POST` | `/v1/messages` | Anthropic Messages |
| `POST` | `/v1/messages/count_tokens` | Approximate token count |

The proxy supports streaming text, reasoning, and tool-call conversion between
these protocols. It can also write content-free benchmark route receipts; see
[`docs/cli.md`](docs/cli.md) for configuration and operational details.

The APIs are not a symmetric provider gateway: upstreams must expose OpenAI
Responses or Chat Completions. See [`docs/compatibility.md`](docs/compatibility.md)
for the supported matrix, behavior classes, and repair contract.

For opt-in endpoint checks and LiteLLM comparisons, see
[`docs/compatibility-testing.md`](docs/compatibility-testing.md).

## Security

- Client authentication is optional. Set `AGENT_WIRE_PROXY_CLIENT_API_KEY` and
  still prefer a localhost binding or authenticated TLS reverse proxy.
- Keep upstream credentials in environment variables or an ignored `.env`.
- Request and response content is omitted from logs by default. Treat logs
  produced with `--log-content` as sensitive.
- Configure `NO_PROXY`/`no_proxy` yourself when an upstream must bypass an HTTP
  proxy.

## License

[MIT](LICENSE)
