oc-cc-proxy 0.1.0__py3-none-any.whl

oc_cc_proxy-0.1.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: oc-cc-proxy
+Version: 0.1.0
+Summary: Local LiteLLM proxy for routing Claude Code to OpenCode Go.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: litellm[proxy]>=1.83.14
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: pyyaml>=6.0.3
+
+# oc-cc-proxy
+
+`oc-cc-proxy` runs a local LiteLLM Proxy that lets Claude Code send Anthropic Messages API requests to OpenCode Go's OpenAI-compatible endpoint.
+
+The proxy listens on `http://127.0.0.1:4000` by default and routes all Claude Code model names through LiteLLM wildcard passthrough to `https://opencode.ai/zen/go/v1/chat/completions`.
+
+## Setup
+
+1. Install dependencies:
+
+   ```bash
+   uv sync
+   ```
+
+2. Configure the OpenCode Go API key:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+3. Edit `.env` and set `OPENCODE_GO_API_KEY`.
+
+4. Start the proxy:
+
+   ```bash
+   uv run oc-cc-proxy
+   ```
+
+The proxy fails before accepting requests if `OPENCODE_GO_API_KEY` is missing.
+
+## Claude Code Settings
+
+Add equivalent environment values to your Claude Code user-scope `settings.json`:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://127.0.0.1:4000",
+    "ANTHROPIC_API_KEY": "not-a-real-anthropic-key",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-pro",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro"
+  }
+}
+```
+
+`ANTHROPIC_API_KEY` only needs to be non-empty for the local proxy path. OpenCode Go authentication uses `OPENCODE_GO_API_KEY` on the proxy process.
+
+## Validation
+
+With the proxy running, validate non-streaming text, wildcard model passthrough, streaming terminal events, tool definitions, tool results, and streamed tool requests:
+
+```bash
+uv run oc-cc-proxy-validate --model deepseek-v4-pro
+```
+
+Expected successful output starts each check with `ok:`. Any dropped, malformed, or ignored tool-call behavior should be treated as a blocking compatibility issue before describing the proxy as Claude Code-ready.
+
+Project-local checks:
+
+```bash
+uv run pytest
+uv run ruff check .
+```
+
+## Debugging
+
+Enable LiteLLM verbose logging and local request-shape diagnostics:
+
+```bash
+uv run oc-cc-proxy --debug
+```
+
+Debug helpers redact sensitive headers such as `Authorization`, `x-api-key`, and `api-key`. Avoid pasting raw upstream logs publicly unless you have checked them for secrets.
+
+To inspect the generated LiteLLM config path without starting the server:
+
+```bash
+uv run oc-cc-proxy --print-config --config /tmp/oc-cc-proxy-litellm.yaml
+```
+
+## Configuration
+
+- `OPENCODE_GO_API_KEY`: required OpenCode Go API key.
+- `OC_PROXY_HOST`: optional host override, defaults to `127.0.0.1`.
+- `OC_PROXY_PORT`: optional port override, defaults to `4000`.
+
+The generated LiteLLM route uses:
+
+```yaml
+model_list:
+  - model_name: "*"
+    litellm_params:
+      model: "openai/*"
+      api_base: "https://opencode.ai/zen/go/v1"
+```
+
+## Current Limitations
+
+- Tool-use compatibility must be validated against a live OpenCode Go account and target model before claiming a model is known-good for Claude Code.
+- `deepseek-v4-pro` is the current known-good validation target for text, streaming, wildcard routing, tool calls, streamed tool-call metadata, and `tool_result` follow-up turns.
+- DeepSeek V4 requires its returned reasoning metadata to be replayed on assistant tool-call history. The proxy installs a LiteLLM callback that converts Anthropic `thinking` blocks back into upstream `reasoning_content` before `tool_result` follow-up turns.
+- Anthropic-specific features such as prompt caching, extended thinking, and any endpoints beyond `/v1/messages` are not claimed as supported unless separately validated.
+- Invalid Claude Code model names are forwarded to OpenCode Go by design because wildcard model passthrough keeps Claude Code settings as the source of truth.

oc_cc_proxy-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+oc_proxy/__init__.py,sha256=wQ5ZuKi7Ka_ObJ_Ai7ynzCt9QyNrZFkxx3m2ermYNXc,105
+oc_proxy/cli.py,sha256=2I48yZLWPI4yiF_tg6JyFvatsyvdVOE1io-zRb1o0Ic,3060
+oc_proxy/config.py,sha256=WgVOH0HN8h_3WyI76etxCDh5dgUWqaQZ-TDbSNBg0_Q,3167
+oc_proxy/reasoning.py,sha256=bo8LU4ZJfxH50EUmvmOwem8xo46e3n24buzAwV_7xQQ,4434
+oc_proxy/validation.py,sha256=nqhAZlPLoYnDhF3VBz7mjrH269gMb78JN7ofYPso0bs,6295
+oc_cc_proxy-0.1.0.dist-info/METADATA,sha256=O5cKpID5RtB48NiOxcNwDGMiAMQf3voQGkf_bmVknKI,3879
+oc_cc_proxy-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+oc_cc_proxy-0.1.0.dist-info/entry_points.txt,sha256=0vIUCZBN5eJJpM7ovwMopNP4RH8dl6qFdDya_76kRPM,98
+oc_cc_proxy-0.1.0.dist-info/top_level.txt,sha256=11eGVx9Bi9dmxBE7mIP1My_Hl5epQ0eA61PZCxR8Oa8,9
+oc_cc_proxy-0.1.0.dist-info/RECORD,,

oc_cc_proxy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

oc_cc_proxy-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+oc-cc-proxy = oc_proxy.cli:main
+oc-cc-proxy-validate = oc_proxy.validation:main

oc_cc_proxy-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+oc_proxy

oc_proxy/__init__.py

@@ -0,0 +1,5 @@
+"""Local Claude Code proxy wrapper for OpenCode Go."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

oc_proxy/cli.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+from .config import ConfigurationError, load_settings, summarize_payload_shape, write_litellm_config
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Run a local LiteLLM proxy for Claude Code and OpenCode Go.")
+    parser.add_argument("--env-file", help="Path to a .env file containing OPENCODE_GO_API_KEY.")
+    parser.add_argument("--host", help="Override OC_PROXY_HOST for this run.")
+    parser.add_argument("--port", type=int, help="Override OC_PROXY_PORT for this run.")
+    parser.add_argument("--config", help="Write LiteLLM config to this path instead of a temporary file.")
+    parser.add_argument("--print-config", action="store_true", help="Print generated LiteLLM config path and exit.")
+    parser.add_argument("--debug", action="store_true", help="Enable LiteLLM verbose logging and request-shape diagnostics.")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        settings = load_settings(env_file=args.env_file, debug=args.debug)
+    except ConfigurationError as exc:
+        print(f"Configuration error: {exc}", file=sys.stderr)
+        return 2
+
+    if args.host or args.port:
+        settings = settings.__class__(
+            api_key=settings.api_key,
+            host=args.host or settings.host,
+            port=args.port or settings.port,
+            api_base=settings.api_base,
+            debug=settings.debug,
+        )
+
+    if args.config:
+        config_path = Path(args.config)
+        write_litellm_config(settings, config_path)
+        temp_dir = None
+    else:
+        temp_dir = tempfile.TemporaryDirectory(prefix="oc-cc-proxy-")
+        config_path = Path(temp_dir.name) / "litellm.yaml"
+        write_litellm_config(settings, config_path)
+
+    if args.debug:
+        shape = summarize_payload_shape({"model": "deepseek-v4-pro", "messages": [{"role": "user", "content": "..."}], "tools": []})
+        print(f"Debug request shape example: {json.dumps(shape, sort_keys=True)}", file=sys.stderr)
+
+    if args.print_config:
+        print(config_path)
+        if temp_dir:
+            temp_dir.cleanup()
+        return 0
+
+    litellm_executable = shutil.which("litellm")
+    if not litellm_executable:
+        print("Configuration error: litellm executable was not found in PATH.", file=sys.stderr)
+        return 2
+
+    command = [
+        litellm_executable,
+        "--config",
+        str(config_path),
+        "--host",
+        settings.host,
+        "--port",
+        str(settings.port),
+    ]
+    print(f"Starting oc-cc-proxy on http://{settings.host}:{settings.port}")
+    print("Set Claude Code ANTHROPIC_BASE_URL to this URL and use any non-empty ANTHROPIC_API_KEY value.")
+    try:
+        return subprocess.call(command)
+    finally:
+        if temp_dir:
+            temp_dir.cleanup()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

oc_proxy/config.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+from dotenv import load_dotenv
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 4000
+OPENCODE_GO_API_BASE = "https://opencode.ai/zen/go/v1"
+OPENCODE_GO_API_KEY_ENV = "OPENCODE_GO_API_KEY"
+
+
+class ConfigurationError(RuntimeError):
+    """Raised when required proxy configuration is missing or invalid."""
+
+
+@dataclass(frozen=True)
+class ProxySettings:
+    api_key: str
+    host: str = DEFAULT_HOST
+    port: int = DEFAULT_PORT
+    api_base: str = OPENCODE_GO_API_BASE
+    debug: bool = False
+
+
+def load_settings(*, env_file: str | None = None, debug: bool = False) -> ProxySettings:
+    if env_file:
+        load_dotenv(env_file)
+    else:
+        load_dotenv()
+
+    api_key = os.getenv(OPENCODE_GO_API_KEY_ENV)
+    if not api_key:
+        raise ConfigurationError(
+            f"Missing {OPENCODE_GO_API_KEY_ENV}. Set it in the environment or a .env file before starting oc-cc-proxy."
+        )
+
+    host = os.getenv("OC_PROXY_HOST", DEFAULT_HOST)
+    port_value = os.getenv("OC_PROXY_PORT", str(DEFAULT_PORT))
+    try:
+        port = int(port_value)
+    except ValueError as exc:
+        raise ConfigurationError(f"OC_PROXY_PORT must be an integer, got {port_value!r}.") from exc
+
+    return ProxySettings(api_key=api_key, host=host, port=port, debug=debug)
+
+
+def build_litellm_config(settings: ProxySettings) -> dict[str, Any]:
+    config: dict[str, Any] = {
+        "model_list": [
+            {
+                "model_name": "*",
+                "litellm_params": {
+                    "model": "openai/*",
+                    "api_base": settings.api_base,
+                    "api_key": settings.api_key,
+                },
+            }
+        ],
+        "litellm_settings": {
+            "callbacks": ["oc_proxy.reasoning.deepseek_reasoning_content_callback"],
+            "drop_params": True,
+            "set_verbose": settings.debug,
+            "use_chat_completions_url_for_anthropic_messages": True,
+        },
+    }
+    return config
+
+
+def write_litellm_config(settings: ProxySettings, path: Path) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    callback_dir = path.parent / "oc_proxy"
+    callback_dir.mkdir(exist_ok=True)
+    (callback_dir / "__init__.py").write_text("", encoding="utf-8")
+    shutil.copyfile(Path(__file__).with_name("reasoning.py"), callback_dir / "reasoning.py")
+    with path.open("w", encoding="utf-8") as config_file:
+        yaml.safe_dump(build_litellm_config(settings), config_file, sort_keys=False)
+    return path
+
+
+def redact_headers(headers: dict[str, str]) -> dict[str, str]:
+    sensitive = {"authorization", "x-api-key", "api-key"}
+    return {key: ("<redacted>" if key.lower() in sensitive else value) for key, value in headers.items()}
+
+
+def summarize_payload_shape(payload: Any) -> Any:
+    if isinstance(payload, dict):
+        return {key: summarize_payload_shape(value) for key, value in payload.items()}
+    if isinstance(payload, list):
+        return [summarize_payload_shape(payload[0])] if payload else []
+    return type(payload).__name__

oc_proxy/reasoning.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from typing import Any
+
+from litellm.integrations.custom_logger import CustomLogger
+from litellm.types.utils import CallTypes
+
+
+def _patch_litellm_empty_stream_choices() -> None:
+    try:
+        from litellm.litellm_core_utils.streaming_handler import CustomStreamWrapper
+        from litellm.llms.anthropic.experimental_pass_through.adapters.streaming_iterator import (
+            AnthropicStreamWrapper,
+        )
+        from litellm.llms.anthropic.experimental_pass_through.adapters.transformation import (
+            LiteLLMAnthropicMessagesAdapter,
+        )
+    except ImportError:
+        return
+
+    original_should_start = AnthropicStreamWrapper._should_start_new_content_block
+    original_translate = LiteLLMAnthropicMessagesAdapter.translate_streaming_openai_response_to_anthropic
+    original_raise_on_repetition = CustomStreamWrapper.raise_on_model_repetition
+
+    if getattr(original_translate, "_oc_proxy_empty_choices_patch", False):
+        return
+
+    def patched_should_start(self: Any, chunk: Any) -> bool:
+        if _has_empty_choices(chunk):
+            return False
+        return original_should_start(self, chunk)
+
+    def patched_translate(self: Any, response: Any, current_content_block_index: int) -> dict[str, Any]:
+        if _has_empty_choices(response):
+            return {
+                "type": "content_block_delta",
+                "index": current_content_block_index,
+                "delta": {"type": "text_delta", "text": ""},
+            }
+        return original_translate(self, response, current_content_block_index)
+
+    def patched_raise_on_repetition(self: Any) -> None:
+        if len(self.chunks) < 2:
+            return
+        if _has_empty_choices(self.chunks[-1]) or _has_empty_choices(self.chunks[-2]):
+            self._repeated_messages_count = 1
+            return
+        return original_raise_on_repetition(self)
+
+    patched_translate._oc_proxy_empty_choices_patch = True  # type: ignore[attr-defined]
+    CustomStreamWrapper.raise_on_model_repetition = patched_raise_on_repetition
+    AnthropicStreamWrapper._should_start_new_content_block = patched_should_start
+    LiteLLMAnthropicMessagesAdapter.translate_streaming_openai_response_to_anthropic = patched_translate
+
+
+class DeepSeekReasoningContentCallback(CustomLogger):
+    """Preserve DeepSeek reasoning metadata and drop Anthropic-only replay fields."""
+
+    async def async_pre_call_deployment_hook(self, kwargs: dict[str, Any], call_type: CallTypes | None) -> dict[str, Any]:
+        if call_type not in {CallTypes.completion, CallTypes.acompletion}:
+            return kwargs
+
+        model = str(kwargs.get("model") or "")
+        should_preserve_reasoning = model.startswith(("deepseek-v4", "kimi-k2"))
+        messages = kwargs.get("messages")
+        if not isinstance(messages, list):
+            return kwargs
+
+        for message in messages:
+            if not isinstance(message, dict) or message.get("role") != "assistant":
+                continue
+            thinking_blocks = message.pop("thinking_blocks", None)
+            reasoning_content = _thinking_blocks_to_reasoning_content(thinking_blocks) if should_preserve_reasoning else None
+            if reasoning_content:
+                message["reasoning_content"] = reasoning_content
+            if message.get("tool_calls") and message.get("content") is None:
+                message["content"] = ""
+        return kwargs
+
+    async def async_post_call_streaming_iterator_hook(self, user_api_key_dict: Any, response: Any, request_data: dict) -> Any:
+        model = str(request_data.get("model") or "")
+        async for item in response:
+            if model == "minimax-m2.7" and _has_empty_choices(item):
+                continue
+            yield item
+
+
+def _has_empty_choices(item: Any) -> bool:
+    choices = getattr(item, "choices", None)
+    return isinstance(choices, list) and not choices
+
+
+def _thinking_blocks_to_reasoning_content(thinking_blocks: Any) -> str | None:
+    if not isinstance(thinking_blocks, list):
+        return None
+
+    parts: list[str] = []
+    for block in thinking_blocks:
+        if isinstance(block, dict) and block.get("type") == "thinking" and block.get("thinking"):
+            parts.append(str(block["thinking"]))
+    return "\n".join(parts) or None
+
+
+deepseek_reasoning_content_callback = DeepSeekReasoningContentCallback()
+_patch_litellm_empty_stream_choices()

oc_proxy/validation.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Any
+
+import httpx
+
+
+def raise_for_status_with_body(response: httpx.Response, check_name: str) -> None:
+    try:
+        response.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        body = response.text[:1000]
+        raise RuntimeError(f"{check_name} failed with HTTP {response.status_code}: {body}") from exc
+
+
+def messages_payload(*, model: str, stream: bool = False, tools: bool = False) -> dict[str, Any]:
+    prompt = "Use the get_status tool for target proxy. Do not answer in text."
+    if not tools:
+        prompt = "Reply with exactly: ok"
+    messages: list[dict[str, Any]] = [{"role": "user", "content": prompt}]
+    payload: dict[str, Any] = {
+        "model": model,
+        "max_tokens": 256 if tools else 64,
+        "stream": stream,
+        "messages": messages,
+    }
+    if tools:
+        payload["tools"] = [
+            {
+                "name": "get_status",
+                "description": "Return a short status string.",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {"target": {"type": "string"}},
+                    "required": ["target"],
+                },
+            }
+        ]
+    return payload
+
+
+def has_tool_use(content: Any) -> bool:
+    return isinstance(content, list) and any(
+        isinstance(block, dict) and block.get("type") == "tool_use" for block in content
+    )
+
+
+def get_tool_use_id(content: Any) -> str:
+    if not isinstance(content, list):
+        raise RuntimeError("tool response content is not a list")
+    for block in content:
+        if isinstance(block, dict) and block.get("type") == "tool_use" and block.get("id"):
+            return str(block["id"])
+    raise RuntimeError(f"tool response did not include a tool_use id: {json.dumps(content)[:500]}")
+
+
+def tool_result_payload(*, model: str, assistant_content: Any) -> dict[str, Any]:
+    return {
+        "model": model,
+        "max_tokens": 64,
+        "messages": [
+            {"role": "user", "content": "Use the get_status tool for target proxy."},
+            {"role": "assistant", "content": assistant_content},
+            {
+                "role": "user",
+                "content": [{"type": "tool_result", "tool_use_id": get_tool_use_id(assistant_content), "content": "ok"}],
+            },
+        ],
+    }
+
+
+def validate(base_url: str, model: str, api_key: str) -> int:
+    headers = {"x-api-key": api_key, "anthropic-version": "2023-06-01"}
+    checks = [
+        ("non-streaming text", messages_payload(model=model)),
+        ("wildcard model passthrough", messages_payload(model=model)),
+    ]
+    with httpx.Client(timeout=60) as client:
+        for name, payload in checks:
+            response = client.post(f"{base_url.rstrip('/')}/v1/messages", headers=headers, json=payload)
+            raise_for_status_with_body(response, name)
+            body = response.json()
+            if body.get("type") != "message" or "content" not in body:
+                raise RuntimeError(f"{name} did not return an Anthropic-shaped message: {json.dumps(body)[:500]}")
+            print(f"ok: {name}")
+
+        response = client.post(
+            f"{base_url.rstrip('/')}/v1/messages",
+            headers=headers,
+            json=messages_payload(model=model, tools=True),
+        )
+        raise_for_status_with_body(response, "tool definitions and tool_use response")
+        body = response.json()
+        tool_response_content = body.get("content")
+        if not has_tool_use(tool_response_content):
+            raise RuntimeError(f"tool definitions did not produce an Anthropic tool_use block: {json.dumps(body)[:500]}")
+        print("ok: tool definitions and tool_use response")
+
+        with client.stream(
+            "POST",
+            f"{base_url.rstrip('/')}/v1/messages",
+            headers=headers,
+            json=messages_payload(model=model, stream=True),
+        ) as response:
+            raise_for_status_with_body(response, "streaming text")
+            events = list(response.iter_lines())
+            if not any("message_stop" in event or "[DONE]" in event for event in events):
+                raise RuntimeError("streaming response did not include a terminal event")
+            print("ok: streaming text and terminal event")
+
+        with client.stream(
+            "POST",
+            f"{base_url.rstrip('/')}/v1/messages",
+            headers=headers,
+            json=messages_payload(model=model, stream=True, tools=True),
+        ) as response:
+            raise_for_status_with_body(response, "streamed tool request")
+            events = list(response.iter_lines())
+            if not events:
+                raise RuntimeError("streamed tool validation returned no events")
+            event_text = "\n".join(events)
+            required_parts = ["get_status", "tool", "id"]
+            missing_parts = [part for part in required_parts if part not in event_text]
+            if missing_parts:
+                raise RuntimeError(f"streamed tool response missing expected parts {missing_parts}: {event_text[:1000]}")
+            print("ok: streamed tool response preserves name, input, and identifier information")
+
+        response = client.post(
+            f"{base_url.rstrip('/')}/v1/messages",
+            headers=headers,
+            json=tool_result_payload(model=model, assistant_content=tool_response_content),
+        )
+        raise_for_status_with_body(response, "tool result follow-up")
+        body = response.json()
+        if body.get("type") != "message" or "content" not in body:
+            raise RuntimeError(f"tool result follow-up did not return an Anthropic-shaped message: {json.dumps(body)[:500]}")
+        print("ok: tool result follow-up")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate Claude Code proxy compatibility against a running oc-cc-proxy.")
+    parser.add_argument("--base-url", default="http://127.0.0.1:4000")
+    parser.add_argument("--model", default="qwen3.6-plus")
+    parser.add_argument("--api-key", default="not-a-real-anthropic-key")
+    args = parser.parse_args()
+    return validate(args.base_url, args.model, args.api_key)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())