agentrelay-cli 0.5.1__py3-none-any.whl

agentrelay_cli-0.5.1.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: agentrelay-cli
+Version: 0.5.1
+Summary: OpenAI- and Anthropic-compatible API server that routes through agent CLIs
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.34
+Description-Content-Type: text/markdown
+
+# agent-relay
+
+[![CI](https://github.com/npow/claude-relay/actions/workflows/ci.yml/badge.svg)](https://github.com/npow/claude-relay/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/agentrelay-cli)](https://pypi.org/project/agentrelay-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+Drop-in OpenAI **and Anthropic** API server that routes through agent CLIs (currently [Claude Code](https://docs.anthropic.com/en/docs/claude-code)).
+
+> Compatibility note: `claude-relay` remains available as a compatibility package/command alias.
+
+## Why
+
+You have tools that speak the OpenAI or Anthropic API. You have Claude Code with its tools, MCP servers, and agentic capabilities. **agent-relay** bridges the two — point any compatible client at it and every request flows through `claude -p` under the hood.
+
+- **Use Claude Code from any OpenAI or Anthropic client** — Cursor, Continue, aider, LangChain, custom scripts
+- **Keep Claude Code's superpowers** — tool use, MCP servers, file access, shell execution
+- **Zero config** — if `claude` works on your machine, so does this
+- **Real token usage** — reports actual token counts from Claude (not zeros)
+- **Token-level streaming** — uses `--include-partial-messages` for true real-time deltas
+
+## Install
+
+```bash
+# With uv (recommended)
+uvx agent-relay serve
+
+# Or install globally
+uv tool install agentrelay-cli
+agent-relay serve
+
+# Or from source
+git clone https://github.com/npow/claude-relay.git
+cd claude-relay
+uv sync
+uv run agent-relay serve
+```
+
+## Quick start
+
+```bash
+agent-relay serve
+# Server starts on http://localhost:18082
+```
+
+### Run as background service (macOS)
+
+```bash
+# Install and auto-start on login
+agent-relay service install
+```
+
+The installer will offer to add these to your `~/.zshrc` (or `~/.bashrc`) so every SDK and agent picks up the relay automatically:
+
+```bash
+export ANTHROPIC_BASE_URL="http://127.0.0.1:18082"
+export OPENAI_BASE_URL="http://127.0.0.1:18082/v1"
+```
+
+```bash
+# Check status
+agent-relay service status
+
+# Update
+uv tool upgrade agentrelay-cli
+agent-relay service restart
+
+# Stop and remove
+agent-relay service uninstall
+```
+
+Point any OpenAI-compatible client at it:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(base_url="http://localhost:18082/v1", api_key="unused")
+
+# Streaming
+for chunk in client.chat.completions.create(
+    model="sonnet",
+    messages=[{"role": "user", "content": "Hello!"}],
+    stream=True,
+):
+    print(chunk.choices[0].delta.content or "", end="")
+
+# Non-streaming
+resp = client.chat.completions.create(
+    model="sonnet",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+print(resp.choices[0].message.content)
+```
+
+### Anthropic SDK
+
+```python
+import anthropic
+
+# Just set the base URL — the SDK reads ANTHROPIC_BASE_URL automatically
+# export ANTHROPIC_BASE_URL=http://localhost:18082
+client = anthropic.Anthropic(base_url="http://localhost:18082")
+
+# Streaming
+with client.messages.stream(
+    model="sonnet",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello!"}],
+) as stream:
+    for text in stream.text_stream:
+        print(text, end="")
+
+# Non-streaming
+resp = client.messages.create(
+    model="sonnet",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+print(resp.content[0].text)
+```
+
+### LangChain
+
+```python
+from langchain_anthropic import ChatAnthropic
+
+# export ANTHROPIC_BASE_URL=http://localhost:18082
+llm = ChatAnthropic(model="sonnet")
+print(llm.invoke("Hello!").content)
+```
+
+### curl
+
+```bash
+# OpenAI format
+curl http://localhost:18082/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"sonnet","messages":[{"role":"user","content":"Hello"}],"stream":true}'
+
+# OpenAI Responses format
+curl http://localhost:18082/v1/responses \
+  -H "Content-Type: application/json" \
+  -d '{"model":"sonnet","input":"Hello"}'
+
+# Anthropic format
+curl http://localhost:18082/v1/messages \
+  -H "Content-Type: application/json" \
+  -d '{"model":"sonnet","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'
+```
+
+## Configuration
+
+```
+agent-relay serve [--host HOST] [--port PORT]
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--host` | `0.0.0.0` | Bind address |
+| `--port` | `18082` | Bind port |
+
+## API
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/v1/chat/completions` | POST | Chat completions (OpenAI-compatible) |
+| `/v1/responses` | POST | Responses API (OpenAI-compatible) |
+| `/v1/messages` | POST | Messages (Anthropic-compatible) |
+| `/v1/models` | GET | List available models |
+| `/health` | GET | Server and CLI status |
+
+All endpoints also work without the `/v1` prefix. CORS is enabled for all origins.
+
+### Supported features
+
+| Feature | Status |
+|---|---|
+| Streaming (SSE) | Yes |
+| System messages | Yes (via `--system-prompt`) |
+| Multi-turn conversations | Yes |
+| Multimodal (text parts) | Yes |
+| Model selection | Yes |
+| Token usage reporting | Yes |
+| CORS | Yes |
+
+### Models
+
+Pass any model name — it goes directly to `claude --model`:
+
+| Model | Description |
+|---|---|
+| `opus` | Most capable |
+| `sonnet` | Balanced (default) |
+| `haiku` | Fastest |
+
+## Limitations
+
+- `temperature`, `max_tokens`, `top_p`, and other sampling parameters are ignored (Claude Code CLI does not expose them)
+- No tool/function calling passthrough (Claude Code uses its own tools internally, but they aren't exposed via the OpenAI tool-calling protocol)
+- Each request spawns a new `claude` process (~2-3s overhead on top of API latency)
+- No image/audio content forwarding — only text parts of multimodal messages are extracted
+
+## How it works
+
+```
+OpenAI client     ─┐
+                    ├→  claude-relay  →  claude -p  →  Anthropic API
+Anthropic client  ─┘     (FastAPI)      (stream-json)
+```
+
+Each request spawns a `claude -p` process with `--output-format stream-json --include-partial-messages`. The proxy translates between the OpenAI or Anthropic wire format and Claude Code's streaming JSON protocol. Requests are stateless — no conversation history bleeds between calls.
+
+## Development
+
+```bash
+uv sync
+uv run pytest tests/ -v
+```
+
+## License
+
+[MIT](LICENSE)

agentrelay_cli-0.5.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+claude_relay/__init__.py,sha256=j-jSCPmUIKrgyLFLndirleNcsiMDAblpOXe0Nk3qD4s,102
+claude_relay/__main__.py,sha256=wWlLVucqVV_aaOSTH2-O-6UQtQvjFi0GLTK_j900fOo,3656
+claude_relay/server.py,sha256=0t-J5yDVqvGbfUZRRJoow2RGQ9nCh6eOQA1JDI22BP8,30437
+claude_relay/service.py,sha256=or5K5DU-jC_CTGKybmzG-_TglpRo-pxGm0LKBiqjCdc,7039
+agentrelay_cli-0.5.1.dist-info/METADATA,sha256=U7bNzHXoj_7YXJTr6g2PZOZJzWSCpIIgOeafsQTOEcA,6632
+agentrelay_cli-0.5.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agentrelay_cli-0.5.1.dist-info/entry_points.txt,sha256=K07kg2FzlhDrv7158kblVE4CHVd9OxcAIRvWlATsfWM,101
+agentrelay_cli-0.5.1.dist-info/licenses/LICENSE,sha256=ptZw4XxMsq-0L4naAIqBDTgCXvWh1Ut4oARyxdD9HB4,1061
+agentrelay_cli-0.5.1.dist-info/RECORD,,

agentrelay_cli-0.5.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentrelay_cli-0.5.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+agent-relay = claude_relay.__main__:main
+claude-relay = claude_relay.__main__:main

agentrelay_cli-0.5.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 npow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claude_relay/__init__.py

@@ -0,0 +1,3 @@
+"""agent-relay: OpenAI- and Anthropic-compatible API server for agent CLIs."""
+
+__version__ = "0.5.1"

claude_relay/__main__.py

@@ -0,0 +1,93 @@
+"""Entry point for `python -m claude_relay` and the `agent-relay` CLI command."""
+
+import argparse
+import os
+import sys
+
+DEFAULT_PORT = 18082
+
+
+def _cpu_count() -> int:
+    """Return the number of usable CPUs (respects cgroup / affinity masks)."""
+    try:
+        return len(os.sched_getaffinity(0))
+    except (AttributeError, OSError):
+        return os.cpu_count() or 1
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="agent-relay", description="OpenAI-compatible API server for agent CLIs")
+    sub = parser.add_subparsers(dest="command")
+
+    # --- serve (default) ---
+    serve_p = sub.add_parser("serve", help="Start the relay server")
+    serve_p.add_argument("--host", default="0.0.0.0", help="Bind host (default: 0.0.0.0)")
+    serve_p.add_argument("--port", type=int, default=DEFAULT_PORT, help=f"Bind port (default: {DEFAULT_PORT})")
+    serve_p.add_argument("--max-concurrent", type=int, default=10, help="Max concurrent subprocess requests per worker (default: 10)")
+    serve_p.add_argument("--request-timeout", type=float, default=300, help="Per-request timeout in seconds (default: 300)")
+    serve_p.add_argument("--workers", type=int, default=_cpu_count(), help="Number of uvicorn workers (default: CPU count)")
+    serve_p.add_argument(
+        "--backend",
+        choices=["claude", "codex"],
+        default=os.environ.get("AGENT_RELAY_BACKEND", "claude"),
+        help="Backend CLI to execute (default: claude). Codex is reserved for future adapter support.",
+    )
+
+    # --- service management ---
+    svc_p = sub.add_parser("service", help="Manage background service (macOS launchd)")
+    svc_sub = svc_p.add_subparsers(dest="action")
+    install_p = svc_sub.add_parser("install", help="Install and start the launchd service")
+    install_p.add_argument("--port", type=int, default=DEFAULT_PORT, help=f"Port for the service (default: {DEFAULT_PORT})")
+    install_p.add_argument("--host", default="127.0.0.1", help="Bind host for the service (default: 127.0.0.1)")
+    install_p.add_argument(
+        "--backend",
+        choices=["claude", "codex"],
+        default=os.environ.get("AGENT_RELAY_BACKEND", "claude"),
+        help="Backend CLI to execute (default: claude).",
+    )
+    svc_sub.add_parser("restart", help="Restart the launchd service")
+    svc_sub.add_parser("uninstall", help="Stop and remove the launchd service")
+    svc_sub.add_parser("status", help="Show service status")
+
+    args = parser.parse_args()
+
+    # Default to serve when no subcommand given.
+    if args.command is None:
+        args = parser.parse_args(["serve"])
+
+    if args.command == "serve":
+        import uvicorn
+
+        os.environ["CLAUDE_RELAY_MAX_CONCURRENT"] = str(args.max_concurrent)
+        os.environ["CLAUDE_RELAY_REQUEST_TIMEOUT"] = str(args.request_timeout)
+        os.environ["AGENT_RELAY_BACKEND"] = args.backend
+
+        uvicorn.run(
+            "claude_relay.server:app",
+            host=args.host,
+            port=args.port,
+            workers=args.workers,
+        )
+
+    elif args.command == "service":
+        from claude_relay.service import service_install, service_restart, service_status, service_uninstall
+
+        if args.action == "install":
+            service_install(host=args.host, port=args.port, backend=args.backend)
+        elif args.action == "restart":
+            service_restart()
+        elif args.action == "uninstall":
+            service_uninstall()
+        elif args.action == "status":
+            service_status()
+        else:
+            svc_p.print_help()
+            sys.exit(1)
+
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()