cade-cli 0.3.3__py3-none-any.whl

cadecoder/execution/parallel.py

@@ -0,0 +1,287 @@
+"""Parallel tool executor.
+
+This module provides intelligent parallel execution of tools.
+"""
+
+import asyncio
+import json
+from typing import TYPE_CHECKING, Any
+
+from cadecoder.core.logging import log
+from cadecoder.core.types import (
+    ResourceSet,
+    ToolCallList,
+    ToolExecutionResult,
+    ToolGroup,
+    ToolGroups,
+    extract_tool_output_content,
+)
+from cadecoder.tools.manager import ToolAuthorizationRequired
+
+if TYPE_CHECKING:
+    from cadecoder.tools.manager import ToolManager
+
+
+class ParallelToolExecutor:
+    """Executes tools in parallel."""
+
+    def __init__(self, tool_manager: "ToolManager", max_concurrent: int = 10):
+        """Initialize parallel executor."""
+        self.tool_manager = tool_manager
+        self.max_concurrent = max_concurrent
+        self._semaphore = asyncio.Semaphore(max_concurrent)
+        self._interactive_lock = asyncio.Lock()
+
+    async def execute_tools(
+        self, tool_calls: ToolCallList, preserve_order: bool = True
+    ) -> list[ToolExecutionResult]:
+        """Execute tools with intelligent parallelization."""
+        if not tool_calls:
+            return []
+
+        independent_groups = self._analyze_tool_dependencies(tool_calls)
+
+        # Log detailed parallelization info
+        if len(independent_groups) == 1 and len(tool_calls) > 1:
+            log.info(f"Parallel execution: {len(tool_calls)} tools in 1 group (all parallel)")
+        elif len(independent_groups) == len(tool_calls):
+            log.info(f"Sequential execution: {len(tool_calls)} tools (dependencies detected)")
+        else:
+            group_sizes = [len(g) for g in independent_groups]
+            log.info(
+                f"Mixed execution: {len(tool_calls)} tools in "
+                f"{len(independent_groups)} groups {group_sizes}"
+            )
+
+        all_results: list[ToolExecutionResult] = []
+
+        for group_idx, group in enumerate(independent_groups):
+            log.debug(f"Executing group {group_idx + 1} with {len(group)} tools")
+
+            group_tasks: list[asyncio.Task[ToolExecutionResult]] = []
+            for tool_call in group:
+                task = asyncio.create_task(self._execute_single_tool_with_semaphore(tool_call))
+                group_tasks.append(task)
+
+            try:
+                group_results: list[ToolExecutionResult | BaseException] = await asyncio.gather(
+                    *group_tasks, return_exceptions=True
+                )
+            except asyncio.CancelledError:
+                for task in group_tasks:
+                    if not task.done():
+                        task.cancel()
+                await asyncio.gather(*group_tasks, return_exceptions=True)
+                raise
+
+            for tool_call, result in zip(group, group_results):
+                if isinstance(result, Exception):
+                    auth_url = None
+                    # Check for authorization exception
+                    if isinstance(result, ToolAuthorizationRequired):
+                        auth_url = result.authorization_url
+                        log.error(f"Authorization required: {result}")
+                    else:
+                        log.error(f"Tool execution failed: {result}")
+
+                    all_results.append(
+                        ToolExecutionResult(
+                            tool_call_id=tool_call.get("id", ""),
+                            name=tool_call.get("function", {}).get("name", ""),
+                            content=str(result),
+                            status="error",
+                            error=str(result),
+                            authorization_url=auth_url,
+                        )
+                    )
+                else:
+                    if isinstance(result, ToolExecutionResult):
+                        all_results.append(result)
+
+        if preserve_order:
+            ordered_results = self._restore_order(tool_calls, all_results)
+            return ordered_results
+
+        return all_results
+
+    async def _execute_single_tool_with_semaphore(
+        self, tool_call: dict[str, Any]
+    ) -> ToolExecutionResult:
+        """Execute a single tool with semaphore for rate limiting."""
+        async with self._semaphore:
+            if await self._is_interactive_call(tool_call):
+                async with self._interactive_lock:
+                    return await self._execute_single_tool(tool_call)
+            return await self._execute_single_tool(tool_call)
+
+    async def _is_interactive_call(self, tool_call: dict[str, Any]) -> bool:
+        """Determine if the tool call requires exclusive terminal access."""
+        function = tool_call.get("function", {})
+        name = function.get("name", "")
+
+        if hasattr(self.tool_manager, "is_interactive_tool"):
+            try:
+                return bool(self.tool_manager.is_interactive_tool(name))
+            except Exception:
+                return False
+        return False
+
+    async def _execute_single_tool(
+        self,
+        tool_call: dict[str, Any],
+        timeout: float = 120.0,
+    ) -> ToolExecutionResult:
+        """Execute a single tool with timeout and cancellation support."""
+        function = tool_call.get("function", {})
+        name = function.get("name", "unknown")
+        tool_call_id = tool_call.get("id", "unknown")
+
+        try:
+            args = json.loads(function.get("arguments", "{}"))
+            log.debug(f"Executing tool: {name} with args: {args}")
+
+            try:
+                result_content = await asyncio.wait_for(
+                    self.tool_manager.execute(name, args),
+                    timeout=timeout,
+                )
+            except TimeoutError:
+                log.warning(f"Tool {name} timed out after {timeout}s")
+                return ToolExecutionResult(
+                    tool_call_id=tool_call_id,
+                    name=name,
+                    content=f"Tool execution timed out after {timeout} seconds",
+                    status="error",
+                    error="timeout",
+                    authorization_url=None,
+                )
+            except asyncio.CancelledError:
+                log.info(f"Tool {name} was cancelled")
+                return ToolExecutionResult(
+                    tool_call_id=tool_call_id,
+                    name=name,
+                    content="Tool execution was cancelled",
+                    status="cancelled",
+                    error="cancelled",
+                    authorization_url=None,
+                )
+
+            actual_content = extract_tool_output_content(result_content)
+
+            return ToolExecutionResult(
+                tool_call_id=tool_call_id,
+                name=name,
+                content=actual_content,
+                status="success",
+                error=None,
+                authorization_url=None,
+            )
+
+        except Exception as e:
+            auth_url = None
+            if isinstance(e, ToolAuthorizationRequired):
+                auth_url = e.authorization_url
+                log.error(f"Authorization required for tool {name}")
+            else:
+                log.error(f"Tool execution failed for {name}: {e}")
+
+            return ToolExecutionResult(
+                tool_call_id=tool_call_id,
+                name=name,
+                content=str(e),
+                status="error",
+                error=str(e),
+                authorization_url=auth_url,
+            )
+
+    def _analyze_tool_dependencies(self, tool_calls: ToolCallList) -> ToolGroups:
+        """Analyze tool dependencies to determine execution groups.
+
+        Tools are grouped for parallel execution unless they operate on
+        the same resource (detected by examining argument values).
+        """
+        if len(tool_calls) <= 1:
+            return [tool_calls] if tool_calls else []
+
+        # Extract resources for each tool call
+        tool_resources: list[ResourceSet] = []
+        for tool_call in tool_calls:
+            function = tool_call.get("function", {})
+            args_str = function.get("arguments", "{}")
+            try:
+                args = json.loads(args_str)
+            except json.JSONDecodeError:
+                args = {}
+            resources = self._extract_resources(args)
+            tool_resources.append(resources)
+
+        # Group tools - only serialize if same resource is accessed
+        groups: ToolGroups = []
+        current_group: ToolGroup = []
+        current_group_resources: ResourceSet = set()
+
+        for i, tool_call in enumerate(tool_calls):
+            resources = tool_resources[i]
+
+            # Check if this tool conflicts with current group
+            if resources & current_group_resources:
+                # Conflict - start new group
+                if current_group:
+                    groups.append(current_group)
+                current_group = [tool_call]
+                current_group_resources = resources.copy()
+            else:
+                # No conflict - add to current group
+                current_group.append(tool_call)
+                current_group_resources.update(resources)
+
+        if current_group:
+            groups.append(current_group)
+
+        return groups if groups else [[tc] for tc in tool_calls]
+
+    def _extract_resources(self, obj: Any) -> ResourceSet:
+        """Extract resource identifiers from tool arguments.
+
+        Looks for any string values that appear to be paths or identifiers.
+        """
+        resources: set[str] = set()
+
+        if isinstance(obj, str):
+            # Include strings that look like paths or identifiers
+            if "/" in obj or "\\" in obj or "." in obj:
+                resources.add(obj)
+        elif isinstance(obj, dict):
+            for value in obj.values():
+                resources.update(self._extract_resources(value))
+        elif isinstance(obj, list):
+            for item in obj:
+                resources.update(self._extract_resources(item))
+
+        return resources
+
+    def _restore_order(
+        self, original_calls: list[dict[str, Any]], results: list[ToolExecutionResult]
+    ) -> list[ToolExecutionResult]:
+        """Restore original order of results."""
+        result_map = {r.tool_call_id: r for r in results}
+        ordered = []
+
+        for call in original_calls:
+            call_id = call.get("id", "unknown")
+            if call_id in result_map:
+                ordered.append(result_map[call_id])
+            else:
+                log.warning(f"No result found for tool call {call_id}")
+                ordered.append(
+                    ToolExecutionResult(
+                        tool_call_id=call_id,
+                        name=call.get("function", {}).get("name", ""),
+                        content="No result",
+                        status="error",
+                        error="Result not found",
+                        authorization_url=None,
+                    )
+                )
+
+        return ordered

cadecoder/providers/__init__.py

@@ -0,0 +1,60 @@
+"""Provider package for LLM integrations.
+
+This package provides a clean, unified interface for different LLM providers
+with automatic registration and easy access.
+"""
+
+from cadecoder.core.logging import log
+from cadecoder.providers.base import (
+    Provider,
+    ProviderError,
+    ProviderRegistry,
+    ProviderRequest,
+    ProviderResponse,
+    ProviderType,
+    StreamEvent,
+    provider_registry,
+)
+from cadecoder.providers.openai import OpenAIProvider
+
+
+def initialize_providers() -> None:
+    """Initialize and register available providers."""
+    import os
+
+    # Register OpenAI if configured
+    if os.environ.get("OPENAI_API_KEY"):
+        try:
+            openai_provider = OpenAIProvider()
+            provider_registry.register(openai_provider)
+            provider_registry.set_default(ProviderType.OPENAI)
+            log.info("Registered OpenAI provider")
+        except Exception as e:
+            log.warning(f"Failed to register OpenAI provider: {e}")
+
+    # Add other providers as they're implemented
+    # Example:
+    # if config.settings.anthropic_api_key:
+    #     anthropic_provider = AnthropicProvider()
+    #     provider_registry.register(anthropic_provider)
+
+
+# Auto-initialize on import
+initialize_providers()
+
+
+__all__ = [
+    # Base classes
+    "Provider",
+    "ProviderError",
+    "ProviderRegistry",
+    "ProviderRequest",
+    "ProviderResponse",
+    "ProviderType",
+    "StreamEvent",
+    "provider_registry",
+    # Providers
+    "OpenAIProvider",
+    # Functions
+    "initialize_providers",
+]

cadecoder/providers/base.py

@@ -0,0 +1,294 @@
+"""Base provider interface for LLM integrations.
+
+This module defines a clean, simple interface that all LLM providers
+must implement, ensuring consistent behavior across different AI services.
+Also includes provider-related utility functions.
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from cadecoder.core.types import ConversationMessageDict
+
+
+class ProviderType(str, Enum):
+    """Supported LLM providers."""
+
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    ARCADE = "arcade"
+    LOCAL = "local"
+
+
+class ProviderRequest(BaseModel):
+    """Unified request format for all providers."""
+
+    messages: list[ConversationMessageDict] = Field(..., description="Conversation messages")
+    model: str = Field(..., description="Model to use")
+    tools: list[dict[str, Any]] | None = Field(None, description="Available tools in OpenAI format")
+    temperature: float = Field(0.7, description="Response randomness")
+    max_tokens: int | None = Field(None, description="Maximum response tokens")
+    stream: bool = Field(False, description="Whether to stream responses")
+
+    # Optional parameters
+    tool_choice: str | dict[str, Any] | None = Field(None, description="Tool selection preference")
+    system_prompt: str | None = Field(None, description="System prompt override")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Provider-specific metadata")
+
+
+class ProviderResponse(BaseModel):
+    """Unified response format from providers."""
+
+    content: str | None = Field(None, description="Response content")
+    tool_calls: list[dict[str, Any]] | None = Field(None, description="Tool calls requested")
+    finish_reason: str = Field("stop", description="Why generation stopped")
+    usage: dict[str, int] | None = Field(None, description="Token usage statistics")
+    model: str | None = Field(None, description="Model that was used")
+    provider: ProviderType | None = Field(None, description="Provider type")
+
+
+class StreamEvent(BaseModel):
+    """Streaming event from providers."""
+
+    type: str = Field(..., description="Event type (see ExecutionEventType for allowed values)")
+    content: str | None = Field(None, description="Content delta")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Event metadata")
+
+
+class Provider(ABC):
+    """Abstract base class for LLM providers.
+
+    This defines the minimal interface that all providers must implement.
+    Each provider adapter translates between this interface and the
+    provider's native API.
+    """
+
+    @property
+    @abstractmethod
+    def provider_type(self) -> ProviderType:
+        """Return the provider type."""
+        ...
+
+    @property
+    @abstractmethod
+    def supported_models(self) -> list[str]:
+        """Return list of supported model names."""
+        ...
+
+    @abstractmethod
+    async def complete(self, request: ProviderRequest) -> ProviderResponse:
+        """Create a completion.
+
+        Args:
+            request: The request to process
+
+        Returns:
+            The provider's response
+
+        Raises:
+            ProviderError: If the request fails
+        """
+        ...
+
+    @abstractmethod
+    def stream(self, request: ProviderRequest) -> AsyncIterator[StreamEvent]:
+        """Stream a completion.
+
+        Args:
+            request: The request to process
+
+        Yields:
+            Stream events as they arrive
+
+        Raises:
+            ProviderError: If the request fails
+        """
+        ...
+
+    def supports_feature(self, feature: str) -> bool:
+        """Check if provider supports a feature.
+
+        Args:
+            feature: Feature name (e.g., "tools", "streaming", "vision")
+
+        Returns:
+            True if supported
+        """
+        # Default implementation - override in subclasses
+        return feature in ["streaming", "tools"]
+
+
+class ProviderError(Exception):
+    """Base exception for provider errors."""
+
+    def __init__(
+        self,
+        message: str,
+        provider: ProviderType | None = None,
+        status_code: int | None = None,
+        details: dict[str, Any] | None = None,
+    ):
+        super().__init__(message)
+        self.provider = provider
+        self.status_code = status_code
+        self.details = details or {}
+
+
+class ProviderRegistry:
+    """Registry for managing available providers."""
+
+    def __init__(self):
+        self._providers: dict[ProviderType, Provider] = {}
+        self._default_provider: ProviderType | None = None
+
+    def register(self, provider: Provider) -> None:
+        """Register a provider.
+
+        Args:
+            provider: Provider instance to register
+        """
+        self._providers[provider.provider_type] = provider
+
+    def get(self, provider_type: ProviderType) -> Provider | None:
+        """Get a provider by type.
+
+        Args:
+            provider_type: Type of provider to get
+
+        Returns:
+            Provider instance or None if not found
+        """
+        return self._providers.get(provider_type)
+
+    def get_default(self) -> Provider | None:
+        """Get the default provider.
+
+        Returns:
+            Default provider or None if not set
+        """
+        if self._default_provider:
+            return self.get(self._default_provider)
+        # Return first available provider
+        return next(iter(self._providers.values())) if self._providers else None
+
+    def set_default(self, provider_type: ProviderType) -> None:
+        """Set the default provider.
+
+        Args:
+            provider_type: Provider type to use as default
+        """
+        if provider_type not in self._providers:
+            raise ValueError(f"Provider {provider_type} not registered")
+        self._default_provider = provider_type
+
+    @property
+    def available_providers(self) -> list[ProviderType]:
+        """Get list of available provider types."""
+        return list(self._providers.keys())
+
+
+# Global registry instance
+provider_registry = ProviderRegistry()
+
+
+# ============================================================================
+# Provider Utility Functions
+# ============================================================================
+
+
+def get_total_tokens(usage_source: Any) -> int:
+    """Return total tokens from a provider response or usage mapping.
+
+    Accepts either a provider response object (with optional ``usage`` field)
+    or a raw usage dictionary/object. Prefers an explicit ``total_tokens`` when
+    present; otherwise computes a total from known token fields.
+
+    Known field sets:
+    - OpenAI: ``prompt_tokens``, ``completion_tokens``, optional ``reasoning_tokens``
+    - Anthropic: ``input_tokens``, ``output_tokens``
+    - Generic: ``total_tokens``
+
+    Args:
+        usage_source: Provider response or usage mapping/object
+
+    Returns:
+        Total token count as an integer (0 if unavailable)
+    """
+    if usage_source is None:
+        return 0
+
+    # If a ProviderResponse-like object, extract its usage field first
+    usage = getattr(usage_source, "usage", None)
+    candidate = usage if usage is not None else usage_source
+
+    # Handle dict-like usage
+    if isinstance(candidate, dict):
+        # Prefer explicit total_tokens
+        if "total_tokens" in candidate and candidate["total_tokens"] is not None:
+            try:
+                return int(candidate.get("total_tokens", 0))
+            except Exception:
+                return 0
+
+        # OpenAI-style fields
+        prompt = candidate.get("prompt_tokens")
+        completion = candidate.get("completion_tokens")
+        reasoning = candidate.get("reasoning_tokens")
+        if prompt is not None or completion is not None or reasoning is not None:
+            try:
+                total = int(prompt or 0) + int(completion or 0)
+                # Only include reasoning if present and not already included
+                # Some APIs may already include reasoning in completion; when in doubt,
+                # prefer inclusion to avoid undercounting.
+                total += int(reasoning or 0)
+                return total
+            except Exception:
+                return 0
+
+        # Anthropic-style fields
+        input_tokens = candidate.get("input_tokens")
+        output_tokens = candidate.get("output_tokens")
+        if input_tokens is not None or output_tokens is not None:
+            try:
+                return int(input_tokens or 0) + int(output_tokens or 0)
+            except Exception:
+                return 0
+
+        return 0
+
+    # Handle object-style usage with attributes
+    # Prefer explicit total_tokens
+    if hasattr(candidate, "total_tokens"):
+        try:
+            return int(getattr(candidate, "total_tokens", 0) or 0)
+        except Exception:
+            return 0
+
+    # OpenAI-style attributes
+    has_prompt = hasattr(candidate, "prompt_tokens")
+    has_completion = hasattr(candidate, "completion_tokens")
+    has_reasoning = hasattr(candidate, "reasoning_tokens")
+    if has_prompt or has_completion or has_reasoning:
+        try:
+            total = int(getattr(candidate, "prompt_tokens", 0) or 0) + int(
+                getattr(candidate, "completion_tokens", 0) or 0
+            )
+            total += int(getattr(candidate, "reasoning_tokens", 0) or 0)
+            return total
+        except Exception:
+            return 0
+
+    # Anthropic-style attributes
+    if hasattr(candidate, "input_tokens") or hasattr(candidate, "output_tokens"):
+        try:
+            return int(getattr(candidate, "input_tokens", 0) or 0) + int(
+                getattr(candidate, "output_tokens", 0) or 0
+            )
+        except Exception:
+            return 0
+
+    return 0