voxagent 0.1.0__py3-none-any.whl

voxagent/providers/cli_base.py

@@ -0,0 +1,265 @@
+"""Base class for CLI-wrapped LLM providers.
+
+This module provides a base class for providers that wrap CLI tools like
+auggie, codex, and claude instead of making direct HTTP API calls.
+
+CLI providers spawn subprocesses and communicate via stdin/stdout.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import shutil
+import subprocess
+from abc import abstractmethod
+from collections.abc import AsyncIterator
+from typing import Any
+
+from voxagent.providers.base import (
+    AbortSignal,
+    BaseProvider,
+    ErrorChunk,
+    MessageEndChunk,
+    StreamChunk,
+    TextDeltaChunk,
+)
+from voxagent.types import Message
+
+logger = logging.getLogger(__name__)
+
+
+class CLINotFoundError(Exception):
+    """Raised when a required CLI tool is not found."""
+
+    pass
+
+
+class CLIProvider(BaseProvider):
+    """Base class for CLI-wrapped providers.
+
+    These providers spawn CLI tools as subprocesses rather than making HTTP calls.
+    They require the CLI tools to be installed on the system.
+
+    Subclasses must implement:
+    - cli_name: Name of the CLI executable
+    - _build_cli_args: Build command line arguments
+    - _parse_output: Parse CLI output to extract response
+    """
+
+    # Subclasses should set this
+    CLI_NAME: str = ""
+    ENV_KEY: str = ""
+
+    def __init__(
+        self,
+        model: str | None = None,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize CLI provider.
+
+        Args:
+            model: Model name to use.
+            api_key: Optional API key (passed to CLI if supported).
+            base_url: Optional base URL (unused for most CLIs).
+            **kwargs: Additional arguments.
+        """
+        super().__init__(api_key=api_key, base_url=base_url, **kwargs)
+        self._model = model
+        self._cli_path: str | None = None
+
+    def _get_cli_path(self) -> str:
+        """Get the path to the CLI executable.
+
+        Returns:
+            Path to the CLI executable.
+
+        Raises:
+            CLINotFoundError: If the CLI is not found.
+        """
+        if self._cli_path is None:
+            self._cli_path = shutil.which(self.CLI_NAME)
+            if not self._cli_path:
+                raise CLINotFoundError(
+                    f"CLI '{self.CLI_NAME}' not found in PATH. "
+                    f"Please install it first."
+                )
+        return self._cli_path
+
+    @property
+    def supports_streaming(self) -> bool:
+        """CLI providers typically don't support true streaming."""
+        return False
+
+    @abstractmethod
+    def _build_cli_args(
+        self,
+        prompt: str,
+        system: str | None = None,
+    ) -> list[str]:
+        """Build CLI command arguments.
+
+        Args:
+            prompt: The user prompt to send.
+            system: Optional system prompt.
+
+        Returns:
+            List of command line arguments.
+        """
+        ...
+
+    @abstractmethod
+    def _parse_output(self, stdout: str, stderr: str) -> str:
+        """Parse CLI output to extract response text.
+
+        Args:
+            stdout: Standard output from CLI.
+            stderr: Standard error from CLI.
+
+        Returns:
+            Extracted response text.
+        """
+        ...
+
+    def _messages_to_prompt(self, messages: list[Message]) -> str:
+        """Convert message list to a single prompt string.
+
+        CLI tools typically don't support multi-turn conversations natively,
+        so we concatenate messages into a single prompt.
+
+        Args:
+            messages: List of conversation messages.
+
+        Returns:
+            Combined prompt string.
+        """
+        parts: list[str] = []
+        for msg in messages:
+            if msg.role == "user" and isinstance(msg.content, str):
+                parts.append(msg.content)
+            elif msg.role == "assistant" and isinstance(msg.content, str):
+                parts.append(f"[Previous response: {msg.content}]")
+        return "\n\n".join(parts)
+
+    async def _run_cli(
+        self,
+        prompt: str,
+        system: str | None = None,
+    ) -> str:
+        """Run CLI command and return output.
+
+        Args:
+            prompt: User prompt.
+            system: Optional system prompt.
+
+        Returns:
+            Parsed response text.
+
+        Raises:
+            Exception: If CLI execution fails.
+        """
+        cli_path = self._get_cli_path()
+        args = [cli_path] + self._build_cli_args(prompt, system)
+
+        logger.debug("Running CLI: %s", " ".join(args))
+
+        proc = await asyncio.create_subprocess_exec(
+            *args,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        stdout_bytes, stderr_bytes = await proc.communicate()
+        stdout = stdout_bytes.decode("utf-8", errors="replace")
+        stderr = stderr_bytes.decode("utf-8", errors="replace")
+
+        if proc.returncode != 0:
+            logger.warning("CLI exited with code %d: %s", proc.returncode, stderr)
+
+        return self._parse_output(stdout, stderr)
+
+    async def stream(
+        self,
+        messages: list[Message],
+        system: str | None = None,
+        tools: list[Any] | None = None,
+        abort_signal: AbortSignal | None = None,
+    ) -> AsyncIterator[StreamChunk]:
+        """Stream a response from the CLI.
+
+        CLI providers don't truly stream - we run the CLI and yield the result.
+
+        Args:
+            messages: Conversation messages.
+            system: Optional system prompt.
+            tools: Tool definitions (not supported by most CLIs).
+            abort_signal: Optional abort signal.
+
+        Yields:
+            StreamChunk objects.
+        """
+        if tools:
+            logger.warning("Tools not supported by CLI provider %s", self.name)
+
+        try:
+            prompt = self._messages_to_prompt(messages)
+            response = await self._run_cli(prompt, system)
+            if response:
+                yield TextDeltaChunk(delta=response)
+        except CLINotFoundError as e:
+            yield ErrorChunk(error=str(e))
+        except Exception as e:
+            yield ErrorChunk(error=f"CLI error: {e}")
+
+        yield MessageEndChunk()
+
+    async def complete(
+        self,
+        messages: list[Message],
+        system: str | None = None,
+        tools: list[Any] | None = None,
+    ) -> Message:
+        """Get a complete response from the CLI.
+
+        Args:
+            messages: Conversation messages.
+            system: Optional system prompt.
+            tools: Tool definitions (not supported by most CLIs).
+
+        Returns:
+            The assistant's response message.
+        """
+        if tools:
+            logger.warning("Tools not supported by CLI provider %s", self.name)
+
+        prompt = self._messages_to_prompt(messages)
+        response = await self._run_cli(prompt, system)
+        return Message(role="assistant", content=response)
+
+    def count_tokens(
+        self,
+        messages: list[Message],
+        system: str | None = None,
+    ) -> int:
+        """Estimate token count (rough approximation).
+
+        Args:
+            messages: Conversation messages.
+            system: Optional system prompt.
+
+        Returns:
+            Approximate token count.
+        """
+        text = system or ""
+        for msg in messages:
+            if isinstance(msg.content, str):
+                text += msg.content
+        # Rough estimate: ~4 chars per token
+        return len(text) // 4
+
+
+__all__ = ["CLIProvider", "CLINotFoundError"]
+

voxagent/providers/codex.py

@@ -0,0 +1,183 @@
+"""OpenAI Codex CLI provider.
+
+This provider wraps the OpenAI Codex CLI (codex command).
+It requires:
+1. The codex CLI to be installed: npm install -g @openai/codex
+2. Authentication via: codex login
+
+Models available:
+- o3: OpenAI o3
+- o4-mini: OpenAI o4-mini (default)
+- gpt-4.1: GPT-4.1
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import AsyncIterator
+from typing import Any
+
+from voxagent.providers.cli_base import CLINotFoundError, CLIProvider
+from voxagent.providers.base import (
+    AbortSignal,
+    ErrorChunk,
+    MessageEndChunk,
+    StreamChunk,
+    TextDeltaChunk,
+)
+from voxagent.types import Message
+
+logger = logging.getLogger(__name__)
+
+
+class CodexProvider(CLIProvider):
+    """Provider for OpenAI Codex CLI.
+
+    Uses the codex CLI in exec mode with JSON output for non-interactive use.
+    """
+
+    CLI_NAME = "codex"
+    ENV_KEY = "OPENAI_API_KEY"
+
+    # Models that work with Codex using ChatGPT Plus account
+    # Note: Many models (o3, o4-mini, gpt-4.1) require API key, not ChatGPT Plus
+    # "default" means don't specify a model and use the CLI's default
+    SUPPORTED_MODELS = [
+        "default",
+    ]
+
+    def __init__(
+        self,
+        model: str = "default",
+        api_key: str | None = None,
+        base_url: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize Codex provider.
+
+        Args:
+            model: Model name (o3, o4-mini, gpt-4.1).
+            api_key: Optional OpenAI API key.
+            base_url: Optional base URL override.
+            **kwargs: Additional arguments.
+        """
+        super().__init__(model=model, api_key=api_key, base_url=base_url, **kwargs)
+
+    @property
+    def name(self) -> str:
+        """Get the provider name."""
+        return "codex"
+
+    @property
+    def models(self) -> list[str]:
+        """Get supported models."""
+        return self.SUPPORTED_MODELS
+
+    @property
+    def supports_tools(self) -> bool:
+        """Codex has tool support but we don't expose it."""
+        return False
+
+    @property
+    def context_limit(self) -> int:
+        """Approximate context limit."""
+        return 128000
+
+    def _build_cli_args(
+        self,
+        prompt: str,
+        system: str | None = None,
+    ) -> list[str]:
+        """Build codex CLI arguments.
+
+        Uses exec mode for non-interactive execution with JSON output.
+        """
+        args = ["exec", "--json"]
+
+        # Only pass --model if not using "default"
+        if self._model and self._model != "default":
+            args.extend(["--model", self._model])
+
+        # Add the prompt
+        args.append(prompt)
+
+        return args
+
+    def _parse_output(self, stdout: str, stderr: str) -> str:
+        """Parse codex CLI JSON output.
+
+        The --json flag outputs JSONL events. We look for agent_message items.
+        Format: {"type":"item.completed","item":{"type":"agent_message","text":"..."}}
+        """
+        # Parse JSONL output and extract text from agent_message items
+        text_parts: list[str] = []
+
+        for line in stdout.strip().split("\n"):
+            if not line.strip():
+                continue
+            try:
+                event = json.loads(line)
+                # Look for item.completed events with agent_message type
+                if event.get("type") == "item.completed":
+                    item = event.get("item", {})
+                    if item.get("type") == "agent_message":
+                        text = item.get("text", "")
+                        if text:
+                            text_parts.append(text)
+            except json.JSONDecodeError:
+                # If not JSON, treat as plain text
+                text_parts.append(line)
+
+        return "\n".join(text_parts) if text_parts else stdout.strip()
+
+    async def stream(
+        self,
+        messages: list[Message],
+        system: str | None = None,
+        tools: list[Any] | None = None,
+        abort_signal: AbortSignal | None = None,
+    ) -> AsyncIterator[StreamChunk]:
+        """Stream a response from Codex CLI.
+
+        Note: The codex CLI has its own tool execution capabilities.
+        Tools passed from voxDomus are not used.
+        """
+        if tools:
+            logger.debug(
+                "Codex CLI has its own tools - ignoring %d passed tools",
+                len(tools),
+            )
+
+        try:
+            prompt = self._messages_to_prompt(messages)
+            response = await self._run_cli(prompt, system)
+            if response:
+                yield TextDeltaChunk(delta=response)
+        except CLINotFoundError as e:
+            yield ErrorChunk(error=str(e))
+        except Exception as e:
+            yield ErrorChunk(error=f"Codex CLI error: {e}")
+
+        yield MessageEndChunk()
+
+    async def complete(
+        self,
+        messages: list[Message],
+        system: str | None = None,
+        tools: list[Any] | None = None,
+    ) -> Message:
+        """Get a complete response from Codex CLI."""
+        text_parts: list[str] = []
+
+        async for chunk in self.stream(messages, system, tools):
+            if isinstance(chunk, TextDeltaChunk):
+                text_parts.append(chunk.delta)
+            elif isinstance(chunk, ErrorChunk):
+                raise Exception(chunk.error)
+
+        return Message(role="assistant", content="".join(text_parts))
+
+
+__all__ = ["CodexProvider"]
+

voxagent/providers/failover.py

@@ -0,0 +1,90 @@
+"""Failover logic for provider profiles."""
+
+from __future__ import annotations
+
+from typing import Awaitable, Callable, TypeVar
+
+from voxagent.providers.auth import (
+    AuthProfile,
+    AuthProfileManager,
+    FailoverError,
+)
+
+T = TypeVar("T")
+
+
+class NoProfilesAvailableError(Exception):
+    """No profiles available for the requested provider."""
+
+    def __init__(self, provider: str | None = None) -> None:
+        self.provider = provider
+        msg = (
+            f"No profiles available for provider: {provider}"
+            if provider
+            else "No profiles available"
+        )
+        super().__init__(msg)
+
+
+class FailoverExhaustedError(Exception):
+    """All available profiles failed."""
+
+    def __init__(self, last_error: FailoverError) -> None:
+        self.last_error = last_error
+        super().__init__(f"All profiles failed. Last error: {last_error}")
+
+
+async def run_with_failover(
+    manager: AuthProfileManager,
+    provider_name: str,
+    operation: Callable[[AuthProfile], Awaitable[T]],
+    max_retries: int | None = None,
+) -> T:
+    """
+    Run an operation with automatic failover across available profiles.
+
+    Args:
+        manager: AuthProfileManager with configured profiles
+        provider_name: Provider to filter profiles by (e.g., "openai")
+        operation: Async callable that takes an AuthProfile and returns a result
+        max_retries: Maximum number of profiles to try (default: all available)
+
+    Returns:
+        Result from successful operation
+
+    Raises:
+        NoProfilesAvailableError: If no profiles are available
+        FailoverExhaustedError: If all profiles failed with FailoverError
+        Exception: If operation raises a non-FailoverError exception
+    """
+    available = manager.get_available_profiles(provider=provider_name)
+
+    if not available:
+        raise NoProfilesAvailableError(provider_name)
+
+    # Limit retries if specified
+    profiles_to_try = available[:max_retries] if max_retries is not None else available
+
+    last_error: FailoverError | None = None
+
+    for profile in profiles_to_try:
+        try:
+            result = await operation(profile)
+            # Success - record it and return
+            manager.record_success(profile)
+            return result
+
+        except FailoverError as e:
+            # Handle failover based on error type
+            manager.handle_failover(profile, e)
+            last_error = e
+            # Continue to next profile
+            continue
+
+    # All profiles exhausted
+    if last_error is not None:
+        raise FailoverExhaustedError(last_error)
+    else:
+        # This shouldn't happen, but handle it gracefully
+        raise NoProfilesAvailableError(provider_name)
+