codex-proxy 3.1.0__py3-none-any.whl

codex_proxy/__init__.py

@@ -0,0 +1,3 @@
+"""codex-proxy — Responses API to Chat Completions bridge for Codex CLI."""
+
+__version__ = "3.1.0"

codex_proxy/__main__.py

@@ -0,0 +1,66 @@
+"""CLI entry point — `codex-proxy` or `python -m codex_proxy`."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .config import DEFAULT_CONFIG, load_config, write_example_config
+from .server import run
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(
+        prog="codex-proxy",
+        description="Responses API to Chat Completions bridge for Codex CLI",
+    )
+    ap.add_argument("--config", "-c", type=str, default=None,
+                    help=f"Config file path (default: {DEFAULT_CONFIG})")
+    ap.add_argument("--host", type=str, default=None,
+                    help="Override bind host")
+    ap.add_argument("--port", "-p", type=int, default=None,
+                    help="Override bind port")
+    ap.add_argument("--init", action="store_true",
+                    help="Write example config and exit")
+    ap.add_argument("--print-config", action="store_true",
+                    help="Print resolved config and exit")
+    ap.add_argument("--tui", "-t", action="store_true",
+                    help="Launch interactive Rich TUI dashboard")
+    args = ap.parse_args()
+
+    if args.init:
+        path = write_example_config()
+        print(f"Example config written to {path}")
+        sys.exit(0)
+
+    config = load_config(args.config and Path(args.config))
+
+    if args.host:
+        config.server.host = args.host
+    if args.port:
+        config.server.port = args.port
+
+    if args.print_config:
+        print(f"  host:   {config.server.host}")
+        print(f"  port:   {config.server.port}")
+        print(f"  provider: {config.provider.display_name}")
+        print(f"  base_url: {config.provider.base_url}")
+        print(f"  models: {', '.join(config.provider.models)}")
+        print(f"  api_key: {'***' if config.provider.effective_api_key() else '(empty)'}")
+        print(f"  key_pool: {len(config.provider.effective_api_keys())} key(s)")
+        print(f"  circuit_breaker: {'enabled' if config.circuit_breaker.enabled else 'disabled'} (threshold={config.circuit_breaker.failure_threshold}, timeout={config.circuit_breaker.recovery_timeout}s)")
+        print(f"  compaction: {'enabled' if config.compaction.enabled else 'disabled'} (max_messages={config.compaction.max_messages}, keep_last={config.compaction.keep_last})")
+        print(f"  plugins: {'enabled' if config.plugins.enabled else 'disabled'} ({len(config.plugins.plugins)} configured)")
+        sys.exit(0)
+
+    if not config.provider.effective_api_key():
+        print("WARNING: No API key configured.")
+        print(f"  Set api_key or api_key_env in {DEFAULT_CONFIG}")
+        print("  Or set CODEX_PROXY_API_KEY / OPENAI_API_KEY env var")
+
+    run(config, tui=args.tui)
+
+
+if __name__ == "__main__":
+    main()

codex_proxy/circuit_breaker.py

@@ -0,0 +1,83 @@
+"""Async circuit breaker for upstream provider protection."""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+
+logger = logging.getLogger("codex-proxy")
+
+
+class CircuitState(Enum):
+    CLOSED = "closed"
+    OPEN = "open"
+    HALF_OPEN = "half_open"
+
+
+@dataclass
+class CircuitBreaker:
+    """Simple circuit breaker for upstream requests.
+
+    - CLOSED: requests flow normally
+    - OPEN: requests are rejected immediately (fail fast)
+    - HALF_OPEN: one request is allowed through to test recovery
+    """
+
+    failure_threshold: int = 5
+    recovery_timeout: float = 30.0
+    half_open_max: int = 1
+
+    state: CircuitState = field(default=CircuitState.CLOSED, init=False)
+    failure_count: int = field(default=0, init=False)
+    last_failure_time: float = field(default=0.0, init=False)
+    half_open_count: int = field(default=0, init=False)
+
+    def can_execute(self) -> bool:
+        """Check if a request can proceed."""
+        if self.state == CircuitState.CLOSED:
+            return True
+        if self.state == CircuitState.OPEN:
+            if time.time() - self.last_failure_time >= self.recovery_timeout:
+                self.state = CircuitState.HALF_OPEN
+                self.half_open_count = 1
+                logger.info("Circuit breaker: OPEN -> HALF_OPEN")
+                return True
+            return False
+        # HALF_OPEN
+        if self.half_open_count < self.half_open_max:
+            self.half_open_count += 1
+            return True
+        return False
+
+    def record_success(self) -> None:
+        """Record a successful request."""
+        if self.state == CircuitState.HALF_OPEN:
+            self.state = CircuitState.CLOSED
+            self.failure_count = 0
+            logger.info("Circuit breaker: HALF_OPEN -> CLOSED")
+        elif self.state == CircuitState.CLOSED:
+            self.failure_count = 0
+
+    def record_failure(self) -> None:
+        """Record a failed request."""
+        self.failure_count += 1
+        self.last_failure_time = time.time()
+        if self.state == CircuitState.HALF_OPEN:
+            self.state = CircuitState.OPEN
+            logger.warning("Circuit breaker: HALF_OPEN -> OPEN")
+        elif self.failure_count >= self.failure_threshold:
+            self.state = CircuitState.OPEN
+            logger.warning(
+                "Circuit breaker: CLOSED -> OPEN (failures=%d)", self.failure_count,
+            )
+
+    def get_status(self) -> dict:
+        """Return circuit breaker status for monitoring."""
+        return {
+            "state": self.state.value,
+            "failure_count": self.failure_count,
+            "failure_threshold": self.failure_threshold,
+            "recovery_timeout": self.recovery_timeout,
+        }

codex_proxy/compaction.py

@@ -0,0 +1,42 @@
+"""Context compaction — trim conversation history to fit within limits."""
+
+from __future__ import annotations
+
+
+def compact_messages(
+    messages: list[dict], max_messages: int = 50, keep_last: int = 20,
+) -> list[dict]:
+    """Compact messages if the conversation exceeds max_messages.
+
+    Strategy:
+    - Always keep the system message (if present)
+    - Keep the last `keep_last` messages
+    - Drop messages in between, inserting a compaction notice
+
+    Returns messages unchanged if under the limit.
+    """
+    if len(messages) <= max_messages:
+        return messages
+
+    system_msgs: list[dict] = []
+    rest = messages
+    if messages and messages[0].get("role") == "system":
+        system_msgs = [messages[0]]
+        rest = messages[1:]
+
+    if len(rest) <= keep_last:
+        return messages
+
+    kept = rest[-keep_last:]
+    dropped_count = len(rest) - keep_last
+
+    compaction_notice = {
+        "role": "system",
+        "content": (
+            f"[Context compacted: {dropped_count} earlier messages were "
+            "summarized to fit context limits. Continue based on the "
+            "remaining conversation.]"
+        ),
+    }
+
+    return system_msgs + [compaction_notice] + kept

codex_proxy/config.py

@@ -0,0 +1,313 @@
+"""Config file loading — ~/.codex-proxy/config.toml"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[import-not-found]
+
+DEFAULT_DIR = Path.home() / ".codex-proxy"
+DEFAULT_CONFIG = DEFAULT_DIR / "config.toml"
+DEFAULT_PORT = 4242
+
+
+@dataclass
+class ProviderConfig:
+    name: str = "zai"
+    display_name: str = "Z.AI"
+    base_url: str = "https://api.z.ai/api/paas/v4"
+    api_key: str = ""
+    api_key_env: str = ""  # env var name to read key from
+    api_keys: list[str] = field(default_factory=list)
+    api_keys_env: list[str] = field(default_factory=list)
+    models: list[str] = field(default_factory=lambda: ["glm-5.1", "glm-5", "glm-4.7"])
+    default_model: str = "glm-5.1"
+    stream: bool = True
+    extra_headers: dict[str, str] = field(default_factory=dict)
+
+    def effective_api_key(self) -> str:
+        if self.api_key:
+            return self.api_key
+        if self.api_key_env:
+            return os.environ.get(self.api_key_env, "")
+        return ""
+
+    def effective_api_keys(self) -> list[str]:
+        """Return the full resolved key pool."""
+        keys: list[str] = []
+        if self.api_keys:
+            keys.extend(self.api_keys)
+        for env_name in self.api_keys_env:
+            val = os.environ.get(env_name, "")
+            if val:
+                keys.append(val)
+        if not keys:
+            single = self.effective_api_key()
+            if single:
+                keys.append(single)
+        return keys
+
+
+@dataclass
+class ServerConfig:
+    host: str = "127.0.0.1"
+    port: int = DEFAULT_PORT
+    log_level: str = "warning"
+    log_dir: Path = field(default_factory=lambda: DEFAULT_DIR / "logs")
+
+
+@dataclass
+class StoreConfig:
+    ttl_seconds: int = 600
+    max_entries: int = 100
+
+
+@dataclass
+class CircuitBreakerConfig:
+    enabled: bool = True
+    failure_threshold: int = 5
+    recovery_timeout: float = 30.0
+
+
+@dataclass
+class CompactionConfig:
+    enabled: bool = True
+    max_messages: int = 50
+    keep_last: int = 20
+
+
+@dataclass
+class PluginConfig:
+    enabled: bool = False
+    plugins: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ProxyConfig:
+    server: ServerConfig = field(default_factory=ServerConfig)
+    provider: ProviderConfig = field(default_factory=ProviderConfig)
+    store: StoreConfig = field(default_factory=StoreConfig)
+    circuit_breaker: CircuitBreakerConfig = field(default_factory=CircuitBreakerConfig)
+    compaction: CompactionConfig = field(default_factory=CompactionConfig)
+    plugins: PluginConfig = field(default_factory=PluginConfig)
+
+
+def load_config(path: Path | None = None) -> ProxyConfig:
+    """Load config from TOML file, falling back to defaults."""
+    config_path = path or DEFAULT_CONFIG
+
+    if not config_path.exists():
+        # Try env var overrides for quick setup
+        provider = ProviderConfig(
+            base_url=os.environ.get("CODEX_PROXY_BASE_URL", ProviderConfig.base_url),
+            api_key=os.environ.get("CODEX_PROXY_API_KEY", ""),
+            api_key_env=os.environ.get("CODEX_PROXY_API_KEY_ENV", ""),
+            default_model=os.environ.get("CODEX_PROXY_MODEL", "glm-5.1"),
+        )
+        if not provider.api_key and not provider.api_key_env:
+            provider.api_key_env = "OPENAI_API_KEY"
+        return ProxyConfig(provider=provider)
+
+    with open(config_path, "rb") as f:
+        raw = tomllib.load(f)
+
+    server_raw = raw.get("server", {})
+    provider_raw = raw.get("provider", {})
+    store_raw = raw.get("store", {})
+    cb_raw = raw.get("circuit_breaker", {})
+    comp_raw = raw.get("compaction", {})
+    plugins_raw = raw.get("plugins", {})
+
+    server = ServerConfig(
+        host=server_raw.get("host", "127.0.0.1"),
+        port=server_raw.get("port", DEFAULT_PORT),
+        log_level=server_raw.get("log_level", "warning"),
+        log_dir=Path(server_raw.get("log_dir", str(DEFAULT_DIR / "logs"))),
+    )
+
+    provider = ProviderConfig(
+        name=provider_raw.get("name", "zai"),
+        display_name=provider_raw.get("display_name", "Z.AI"),
+        base_url=provider_raw.get("base_url", "https://api.z.ai/api/paas/v4"),
+        api_key=provider_raw.get("api_key", ""),
+        api_key_env=provider_raw.get("api_key_env", ""),
+        api_keys=provider_raw.get("api_keys", []),
+        api_keys_env=provider_raw.get("api_keys_env", []),
+        models=provider_raw.get("models", ["glm-5.1", "glm-5", "glm-4.7"]),
+        default_model=provider_raw.get("default_model", "glm-5.1"),
+        stream=provider_raw.get("stream", True),
+        extra_headers=provider_raw.get("extra_headers", {}),
+    )
+
+    store = StoreConfig(
+        ttl_seconds=store_raw.get("ttl_seconds", 600),
+        max_entries=store_raw.get("max_entries", 100),
+    )
+
+    circuit_breaker = CircuitBreakerConfig(
+        enabled=cb_raw.get("enabled", True),
+        failure_threshold=cb_raw.get("failure_threshold", 5),
+        recovery_timeout=cb_raw.get("recovery_timeout", 30.0),
+    )
+
+    compaction = CompactionConfig(
+        enabled=comp_raw.get("enabled", True),
+        max_messages=comp_raw.get("max_messages", 50),
+        keep_last=comp_raw.get("keep_last", 20),
+    )
+
+    plugins = PluginConfig(
+        enabled=plugins_raw.get("enabled", False),
+        plugins=plugins_raw.get("plugins", []),
+    )
+
+    return ProxyConfig(
+        server=server, provider=provider, store=store,
+        circuit_breaker=circuit_breaker, compaction=compaction,
+        plugins=plugins,
+    )
+
+
+def write_example_config(path: Path | None = None) -> Path:
+    """Write an example config file."""
+    target = path or DEFAULT_CONFIG
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    content = """\
+# codex-proxy config — https://github.com/ZakPro/codex-proxy
+
+[server]
+host = "127.0.0.1"
+port = 4242
+log_level = "warning"    # debug, info, warning, error
+
+[store]
+ttl_seconds = 600         # response cache TTL (10 min)
+max_entries = 100         # max cached responses
+
+[circuit_breaker]
+enabled = true             # protect upstream from cascading failures
+failure_threshold = 5      # consecutive failures before opening circuit
+recovery_timeout = 30.0    # seconds before trying half-open recovery
+
+[compaction]
+enabled = true             # auto-trim long conversations
+max_messages = 50          # trigger compaction above this count
+keep_last = 20             # recent messages to preserve
+
+[plugins]
+enabled = true             # enable hook-based middleware plugins
+plugins = [
+    "codex_proxy.plugins_builtin.LoggingPlugin",  # built-in structured logger
+]
+
+[provider]
+# Provider: Z.AI (GLM models)
+name = "zai"
+display_name = "Z.AI"
+base_url = "https://api.z.ai/api/paas/v4"
+api_key = ""             # or set api_key_env below
+api_key_env = "OPENAI_API_KEY"  # reads from env var
+# api_keys = ["sk-key1", "sk-key2", "sk-key3"]  # multi-key rotation
+# api_keys_env = ["OPENAI_API_KEY_1", "OPENAI_API_KEY_2"]
+models = ["glm-5.1", "glm-5", "glm-4.7", "glm-4.6", "glm-4.5-air"]
+default_model = "glm-5.1"
+
+# --- Other providers (uncomment one) ---
+
+# [provider]
+# name = "groq"
+# display_name = "Groq"
+# base_url = "https://api.groq.com/openai/v1"
+# api_key_env = "GROQ_API_KEY"
+# models = ["llama-4-maverick-17b", "mixtral-8x7b-32768"]
+# default_model = "llama-4-maverick-17b"
+
+# [provider]
+# name = "together"
+# display_name = "Together AI"
+# base_url = "https://api.together.xyz/v1"
+# api_key_env = "TOGETHER_API_KEY"
+# models = ["meta-llama/Llama-3.3-70B-Instruct-Turbo"]
+# default_model = "meta-llama/Llama-3.3-70B-Instruct-Turbo"
+
+# [provider]
+# name = "openrouter"
+# display_name = "OpenRouter"
+# base_url = "https://openrouter.ai/api/v1"
+# api_key_env = "OPENROUTER_API_KEY"
+# models = ["deepseek/deepseek-chat-v3-0324"]
+# default_model = "deepseek/deepseek-chat-v3-0324"
+
+# [provider]
+# name = "ollama"
+# display_name = "Ollama (local)"
+# base_url = "http://localhost:11434/v1"
+# api_key = "ollama"      # Ollama doesn't need a real key
+# models = ["qwen3:32b", "codellama:34b"]
+# default_model = "qwen3:32b"
+
+# [provider]
+# name = "fireworks"
+# display_name = "Fireworks AI"
+# base_url = "https://api.fireworks.ai/inference/v1"
+# api_key_env = "FIREWORKS_API_KEY"
+# models = ["accounts/fireworks/models/llama4-maverick-instruct-basic"]
+# default_model = "accounts/fireworks/models/llama4-maverick-instruct-basic"
+
+# [provider]
+# name = "anthropic"
+# display_name = "Anthropic"
+# base_url = "https://api.anthropic.com/v1"
+# api_key_env = "ANTHROPIC_API_KEY"
+# models = ["claude-sonnet-4-20250514"]
+# default_model = "claude-sonnet-4-20250514"
+
+# [provider]
+# name = "gemini"
+# display_name = "Google Gemini"
+# base_url = "https://generativelanguage.googleapis.com/v1beta/openai"
+# api_key_env = "GEMINI_API_KEY"
+# models = ["gemini-2.5-flash"]
+# default_model = "gemini-2.5-flash"
+
+# [provider]
+# name = "deepseek"
+# display_name = "DeepSeek"
+# base_url = "https://api.deepseek.com/v1"
+# api_key_env = "DEEPSEEK_API_KEY"
+# models = ["deepseek-chat", "deepseek-reasoner"]
+# default_model = "deepseek-chat"
+
+# [provider]
+# name = "mistral"
+# display_name = "Mistral AI"
+# base_url = "https://api.mistral.ai/v1"
+# api_key_env = "MISTRAL_API_KEY"
+# models = ["mistral-large-latest"]
+# default_model = "mistral-large-latest"
+
+# [provider]
+# name = "cohere"
+# display_name = "Cohere"
+# base_url = "https://api.cohere.com/compatibility/v1"
+# api_key_env = "CO_API_KEY"
+# models = ["command-a-03-2025"]
+# default_model = "command-a-03-2025"
+
+# [provider]
+# name = "nvidia"
+# display_name = "NVIDIA NIM"
+# base_url = "https://integrate.api.nvidia.com/v1"
+# api_key_env = "NVIDIA_API_KEY"
+# models = ["nvidia/llama-3.1-nemotron-ultra-253b-v1"]
+# default_model = "nvidia/llama-3.1-nemotron-ultra-253b-v1"
+"""
+    target.write_text(content, encoding="utf-8")
+    return target

codex_proxy/key_rotation.py

@@ -0,0 +1,108 @@
+"""Multi-key rotation with per-key circuit breakers."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+from .circuit_breaker import CircuitBreaker
+
+_FAIL_CODES = frozenset({401, 403, 429})
+
+
+def _mask_key(key: str) -> str:
+    """Mask a key for display: show first 3 and last 4 chars."""
+    if len(key) <= 7:
+        return "***"
+    return f"{key[:3]}...{key[-4:]}"
+
+
+@dataclass
+class _KeyEntry:
+    key: str
+    circuit_breaker: CircuitBreaker
+    error_count: int = 0
+    success_count: int = 0
+    last_used: float = 0.0
+    last_error_status: int = 0
+
+
+class KeyRotator:
+    """Round-robin key pool with per-key circuit breakers."""
+
+    def __init__(self, keys: list[str], failure_threshold: int = 3,
+                 recovery_timeout: float = 60.0) -> None:
+        if not keys:
+            raise ValueError("KeyRotator requires at least one key")
+        self._keys = keys
+        self._failure_threshold = failure_threshold
+        self._recovery_timeout = recovery_timeout
+        self._index = 0
+        self._entries: list[_KeyEntry] = []
+        self._rebuild_entries(keys)
+
+    def _rebuild_entries(self, keys: list[str]) -> None:
+        self._entries = [
+            _KeyEntry(
+                key=k,
+                circuit_breaker=CircuitBreaker(
+                    failure_threshold=self._failure_threshold,
+                    recovery_timeout=self._recovery_timeout,
+                ),
+            )
+            for k in keys
+        ]
+
+    def next_key(self) -> str:
+        """Return the best available key (round-robin with skip-bad)."""
+        n = len(self._entries)
+        for _ in range(n):
+            entry = self._entries[self._index % n]
+            self._index = (self._index + 1) % n
+            if entry.circuit_breaker.can_execute():
+                entry.last_used = time.time()
+                return entry.key
+        # All keys have open circuits — fail-open
+        entry = self._entries[0]
+        entry.last_used = time.time()
+        return entry.key
+
+    def record_success(self, key: str) -> None:
+        entry = self._find(key)
+        if entry:
+            entry.circuit_breaker.record_success()
+            entry.success_count += 1
+
+    def record_failure(self, key: str, status_code: int) -> None:
+        entry = self._find(key)
+        if not entry:
+            return
+        entry.error_count += 1
+        entry.last_error_status = status_code
+        if status_code in _FAIL_CODES:
+            entry.circuit_breaker.record_failure()
+
+    def _find(self, key: str) -> _KeyEntry | None:
+        for e in self._entries:
+            if e.key == key:
+                return e
+        return None
+
+    def get_status(self) -> list[dict]:
+        """Return status dicts for each key."""
+        return [
+            {
+                "key": _mask_key(e.key),
+                "state": e.circuit_breaker.get_status().get("state", "UNKNOWN"),
+                "errors": e.error_count,
+                "successes": e.success_count,
+                "last_error": e.last_error_status,
+            }
+            for e in self._entries
+        ]
+
+    def reset(self, keys: list[str]) -> None:
+        """Rebuild the pool with new keys."""
+        self._keys = keys
+        self._index = 0
+        self._rebuild_entries(keys)