copex 0.8.4__py3-none-any.whl

copex/ralph.py

@@ -0,0 +1,247 @@
+"""
+Ralph Wiggum - Iterative Development Loops for Copex.
+
+Implements the Ralph Wiggum technique pioneered by Geoffrey Huntley:
+https://ghuntley.com/ralph/
+
+Core concept: The same prompt is fed to the AI repeatedly. The AI sees its
+own previous work in the conversation history, allowing it to iteratively
+improve until the task is complete.
+
+"Me fail English? That's unpossible!" - Ralph Wiggum
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Callable
+
+
+@dataclass
+class RalphState:
+    """State of a Ralph loop."""
+
+    prompt: str
+    iteration: int = 0
+    max_iterations: int | None = None
+    completion_promise: str | None = None
+    started_at: datetime = field(default_factory=datetime.now)
+    completed: bool = False
+    completion_reason: str | None = None
+    history: list[str] = field(default_factory=list)
+
+
+@dataclass
+class RalphConfig:
+    """Configuration for Ralph loops."""
+
+    max_iterations: int | None = None  # None = unlimited
+    completion_promise: str | None = None  # Text that signals completion
+    delay_between_iterations: float = 1.0  # Seconds between iterations
+    show_iteration_header: bool = True
+    continue_on_error: bool = True
+    max_consecutive_errors: int = 3
+
+
+class RalphWiggum:
+    """
+    Ralph Wiggum - Iterative AI development loops.
+
+    Usage:
+        ralph = RalphWiggum(copex_client)
+        result = await ralph.loop(
+            prompt="Build a REST API with CRUD operations",
+            completion_promise="API COMPLETE",
+            max_iterations=30,
+        )
+    """
+
+    def __init__(self, client: Any, config: RalphConfig | None = None):
+        """
+        Initialize Ralph.
+
+        Args:
+            client: A Copex client instance
+            config: Optional configuration
+        """
+        self.client = client
+        self.config = config or RalphConfig()
+        self._state: RalphState | None = None
+        self._cancelled = False
+
+    @property
+    def state(self) -> RalphState | None:
+        """Get current loop state."""
+        return self._state
+
+    @property
+    def is_running(self) -> bool:
+        """Check if a loop is currently running."""
+        return self._state is not None and not self._state.completed
+
+    def cancel(self) -> None:
+        """Cancel the current loop."""
+        self._cancelled = True
+        if self._state:
+            self._state.completed = True
+            self._state.completion_reason = "cancelled"
+
+    async def loop(
+        self,
+        prompt: str,
+        *,
+        max_iterations: int | None = None,
+        completion_promise: str | None = None,
+        on_iteration: Callable[[int, str], None] | None = None,
+        on_complete: Callable[[RalphState], None] | None = None,
+    ) -> RalphState:
+        """
+        Run a Ralph loop.
+
+        The same prompt is sent repeatedly. The AI sees the conversation
+        history and can iterate on its previous work.
+
+        Args:
+            prompt: The task prompt to repeat
+            max_iterations: Maximum iterations (None = unlimited)
+            completion_promise: Text that signals completion (e.g., "TASK COMPLETE")
+            on_iteration: Callback called after each iteration with (iteration, response)
+            on_complete: Callback called when loop completes
+
+        Returns:
+            RalphState with final state and history
+        """
+        self._cancelled = False
+        self._state = RalphState(
+            prompt=prompt,
+            max_iterations=max_iterations or self.config.max_iterations,
+            completion_promise=completion_promise or self.config.completion_promise,
+        )
+
+        consecutive_errors = 0
+
+        try:
+            while not self._cancelled:
+                self._state.iteration += 1
+                ralph_instructions = self._build_ralph_instructions()
+
+                # Check max iterations
+                if self._state.max_iterations and self._state.iteration > self._state.max_iterations:
+                    self._state.completed = True
+                    self._state.completion_reason = f"max_iterations ({self._state.max_iterations})"
+                    break
+
+                # Build iteration prompt
+                if self.config.show_iteration_header:
+                    iteration_prompt = f"{ralph_instructions}\n\n---\n\n{prompt}"
+                else:
+                    iteration_prompt = prompt
+
+                try:
+                    # Send to Copex
+                    response = await self.client.send(iteration_prompt)
+                    content = response.content
+                    self._state.history.append(content)
+                    consecutive_errors = 0
+
+                    # Check for completion promise
+                    if self._state.completion_promise:
+                        if self._check_promise(content, self._state.completion_promise):
+                            self._state.completed = True
+                            self._state.completion_reason = f"promise: {self._state.completion_promise}"
+                            break
+
+                    # Callback
+                    if on_iteration:
+                        on_iteration(self._state.iteration, content)
+
+                except Exception:
+                    consecutive_errors += 1
+                    if consecutive_errors >= self.config.max_consecutive_errors:
+                        self._state.completed = True
+                        self._state.completion_reason = f"errors: {consecutive_errors} consecutive failures"
+                        break
+
+                    if not self.config.continue_on_error:
+                        raise
+
+                # Delay between iterations
+                if self.config.delay_between_iterations > 0:
+                    await asyncio.sleep(self.config.delay_between_iterations)
+
+        finally:
+            if not self._state.completed:
+                self._state.completed = True
+                self._state.completion_reason = "unknown"
+
+            if on_complete:
+                on_complete(self._state)
+
+        return self._state
+
+    def _build_ralph_instructions(self) -> str:
+        """Build system instructions for the current iteration."""
+        parts = [f"[Ralph Wiggum Loop - Iteration {self._state.iteration}]"]
+
+        if self._state.max_iterations:
+            parts.append(f"Max iterations: {self._state.max_iterations}")
+
+        if self._state.completion_promise:
+            parts.append(
+                f"\nTo complete this loop, output: <promise>{self._state.completion_promise}</promise>\n"
+                f"ONLY output this when the statement is genuinely TRUE."
+            )
+        else:
+            parts.append("\nNo completion promise set - loop runs until max iterations or cancelled.")
+
+        parts.append("\nYou can see your previous work in the conversation. Continue improving.")
+
+        return "\n".join(parts)
+
+    def _check_promise(self, content: str, promise: str) -> bool:
+        """Check if content contains the completion promise."""
+        # Look for <promise>TEXT</promise> pattern
+        pattern = r"<promise>(.*?)</promise>"
+        matches = re.findall(pattern, content, re.DOTALL | re.IGNORECASE)
+
+        for match in matches:
+            # Normalize whitespace
+            normalized = " ".join(match.strip().split())
+            if normalized.lower() == promise.lower():
+                return True
+
+        return False
+
+
+async def ralph_loop(
+    client: Any,
+    prompt: str,
+    *,
+    max_iterations: int | None = None,
+    completion_promise: str | None = None,
+    on_iteration: Callable[[int, str], None] | None = None,
+) -> RalphState:
+    """
+    Convenience function to run a Ralph loop.
+
+    Example:
+        async with Copex() as client:
+            result = await ralph_loop(
+                client,
+                "Build a calculator app with tests",
+                completion_promise="ALL TESTS PASSING",
+                max_iterations=20,
+            )
+            print(f"Completed in {result.iteration} iterations")
+    """
+    ralph = RalphWiggum(client)
+    return await ralph.loop(
+        prompt,
+        max_iterations=max_iterations,
+        completion_promise=completion_promise,
+        on_iteration=on_iteration,
+    )
+

copex/tools.py

@@ -0,0 +1,404 @@
+"""
+Parallel Tools - Execute multiple tool calls concurrently.
+
+Enables:
+- Concurrent execution of independent tools
+- Batching of tool results
+- Timeout handling for slow tools
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable
+
+
+@dataclass
+class ToolResult:
+    """Result from a tool execution."""
+
+    name: str
+    success: bool
+    result: Any = None
+    error: str | None = None
+    duration_ms: float = 0
+
+
+@dataclass
+class ParallelToolConfig:
+    """Configuration for parallel tool execution."""
+
+    max_concurrent: int = 5  # Maximum concurrent tool calls
+    timeout: float = 30.0  # Timeout per tool in seconds
+    fail_fast: bool = False  # Stop on first error
+    retry_on_error: bool = True  # Retry failed tools
+    max_retries: int = 2  # Max retries per tool
+
+
+class ToolRegistry:
+    """
+    Registry for tools that can be executed in parallel.
+
+    Usage:
+        registry = ToolRegistry()
+
+        @registry.register("get_weather")
+        async def get_weather(city: str) -> str:
+            return f"Weather in {city}: Sunny"
+
+        @registry.register("get_time")
+        async def get_time(timezone: str) -> str:
+            return f"Time in {timezone}: 12:00"
+
+        # Execute multiple tools in parallel
+        results = await registry.execute_parallel([
+            ("get_weather", {"city": "Seattle"}),
+            ("get_time", {"timezone": "PST"}),
+        ])
+    """
+
+    def __init__(self, config: ParallelToolConfig | None = None):
+        self.config = config or ParallelToolConfig()
+        self._tools: dict[str, Callable[..., Awaitable[Any]]] = {}
+        self._descriptions: dict[str, str] = {}
+
+    def register(
+        self,
+        name: str,
+        description: str = "",
+    ) -> Callable[[Callable], Callable]:
+        """
+        Decorator to register a tool.
+
+        Args:
+            name: Tool name
+            description: Tool description
+
+        Example:
+            @registry.register("search", "Search the web")
+            async def search(query: str) -> str:
+                ...
+        """
+        def decorator(func: Callable[..., Awaitable[Any]]) -> Callable:
+            self._tools[name] = func
+            self._descriptions[name] = description or func.__doc__ or ""
+            return func
+
+        return decorator
+
+    def add_tool(
+        self,
+        name: str,
+        func: Callable[..., Awaitable[Any]],
+        description: str = "",
+    ) -> None:
+        """Add a tool directly (not as decorator)."""
+        self._tools[name] = func
+        self._descriptions[name] = description or func.__doc__ or ""
+
+    def get_tool(self, name: str) -> Callable[..., Awaitable[Any]] | None:
+        """Get a tool by name."""
+        return self._tools.get(name)
+
+    def list_tools(self) -> list[dict[str, str]]:
+        """List all registered tools."""
+        return [
+            {"name": name, "description": self._descriptions.get(name, "")}
+            for name in self._tools
+        ]
+
+    async def execute(
+        self,
+        name: str,
+        params: dict[str, Any],
+        timeout: float | None = None,
+    ) -> ToolResult:
+        """
+        Execute a single tool.
+
+        Args:
+            name: Tool name
+            params: Tool parameters
+            timeout: Optional timeout override
+
+        Returns:
+            ToolResult with success/failure info
+        """
+        import time
+
+        tool = self._tools.get(name)
+        if not tool:
+            return ToolResult(
+                name=name,
+                success=False,
+                error=f"Tool not found: {name}",
+            )
+
+        start = time.time()
+        timeout = timeout or self.config.timeout
+
+        try:
+            result = await asyncio.wait_for(
+                tool(**params),
+                timeout=timeout,
+            )
+            duration = (time.time() - start) * 1000
+
+            return ToolResult(
+                name=name,
+                success=True,
+                result=result,
+                duration_ms=duration,
+            )
+
+        except asyncio.TimeoutError:
+            duration = (time.time() - start) * 1000
+            return ToolResult(
+                name=name,
+                success=False,
+                error=f"Timeout after {timeout}s",
+                duration_ms=duration,
+            )
+
+        except Exception as e:
+            duration = (time.time() - start) * 1000
+            return ToolResult(
+                name=name,
+                success=False,
+                error=str(e),
+                duration_ms=duration,
+            )
+
+    async def execute_parallel(
+        self,
+        calls: list[tuple[str, dict[str, Any]]],
+        max_concurrent: int | None = None,
+    ) -> list[ToolResult]:
+        """
+        Execute multiple tools in parallel.
+
+        Args:
+            calls: List of (tool_name, params) tuples
+            max_concurrent: Override max concurrent limit
+
+        Returns:
+            List of ToolResult in same order as calls
+        """
+        max_concurrent = max_concurrent or self.config.max_concurrent
+        semaphore = asyncio.Semaphore(max_concurrent)
+
+        async def limited_execute(name: str, params: dict) -> ToolResult:
+            async with semaphore:
+                if self.config.retry_on_error:
+                    return await self.execute_with_retry(name, params)
+                return await self.execute(name, params)
+
+        tasks: list[asyncio.Task] = []
+        task_map: dict[asyncio.Task, int] = {}
+        for idx, (name, params) in enumerate(calls):
+            task = asyncio.create_task(limited_execute(name, params))
+            tasks.append(task)
+            task_map[task] = idx
+
+        results: list[ToolResult | None] = [None] * len(calls)
+        pending = set(tasks)
+
+        try:
+            while pending:
+                done, pending = await asyncio.wait(
+                    pending,
+                    return_when=asyncio.FIRST_COMPLETED,
+                )
+                for task in done:
+                    idx = task_map[task]
+                    try:
+                        result = await task
+                    except Exception as exc:
+                        result = ToolResult(
+                            name=calls[idx][0],
+                            success=False,
+                            error=str(exc),
+                        )
+
+                    results[idx] = result
+
+                    if self.config.fail_fast and not result.success:
+                        for pending_task in pending:
+                            pending_task.cancel()
+                        pending.clear()
+                        break
+        finally:
+            if pending:
+                await asyncio.gather(*pending, return_exceptions=True)
+
+        if self.config.fail_fast and any(r is None for r in results):
+            for idx, result in enumerate(results):
+                if result is None:
+                    results[idx] = ToolResult(
+                        name=calls[idx][0],
+                        success=False,
+                        error="Cancelled due to fail_fast",
+                    )
+
+        return [result for result in results if result is not None]
+
+    async def execute_with_retry(
+        self,
+        name: str,
+        params: dict[str, Any],
+        max_retries: int | None = None,
+    ) -> ToolResult:
+        """
+        Execute a tool with retries on failure.
+
+        Args:
+            name: Tool name
+            params: Tool parameters
+            max_retries: Override max retries
+
+        Returns:
+            ToolResult from last attempt
+        """
+        max_retries = max_retries or self.config.max_retries
+
+        for attempt in range(max_retries + 1):
+            result = await self.execute(name, params)
+
+            if result.success:
+                return result
+
+            if attempt < max_retries:
+                # Exponential backoff
+                await asyncio.sleep(2 ** attempt * 0.5)
+
+        return result
+
+
+class ParallelToolExecutor:
+    """
+    High-level executor for parallel tool calls from Copex responses.
+
+    Integrates with Copex to automatically handle tool calls in parallel.
+
+    Usage:
+        executor = ParallelToolExecutor()
+
+        @executor.tool("fetch_data")
+        async def fetch_data(url: str) -> str:
+            async with aiohttp.ClientSession() as session:
+                async with session.get(url) as response:
+                    return await response.text()
+
+        # In Copex callback
+        async def handle_tools(tool_calls: list[dict]) -> list[dict]:
+            return await executor.handle_batch(tool_calls)
+    """
+
+    def __init__(self, config: ParallelToolConfig | None = None):
+        self.registry = ToolRegistry(config)
+        self.config = config or ParallelToolConfig()
+
+    def tool(
+        self,
+        name: str,
+        description: str = "",
+    ) -> Callable[[Callable], Callable]:
+        """Decorator to register a tool."""
+        return self.registry.register(name, description)
+
+    async def handle_batch(
+        self,
+        tool_calls: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        """
+        Handle a batch of tool calls from Copex.
+
+        Args:
+            tool_calls: List of tool call dicts with "name" and "arguments"
+
+        Returns:
+            List of result dicts for Copex
+        """
+        calls = [
+            (call["name"], call.get("arguments", {}))
+            for call in tool_calls
+        ]
+
+        results = await self.registry.execute_parallel(calls)
+
+        return [
+            {
+                "tool_call_id": tool_calls[i].get("id", f"call_{i}"),
+                "name": result.name,
+                "result": result.result if result.success else None,
+                "error": result.error,
+                "success": result.success,
+            }
+            for i, result in enumerate(results)
+        ]
+
+    def get_tool_definitions(self) -> list[dict[str, Any]]:
+        """
+        Get tool definitions for Copex session.
+
+        Returns:
+            List of tool definitions for create_session
+        """
+        definitions = []
+        for tool_info in self.registry.list_tools():
+            # Get the actual function to introspect
+            func = self.registry.get_tool(tool_info["name"])
+            if not func:
+                continue
+
+            # Try to get type hints for parameters
+            import inspect
+            sig = inspect.signature(func)
+            properties = {}
+            required = []
+
+            for param_name, param in sig.parameters.items():
+                if param_name in ("self", "cls"):
+                    continue
+
+                param_type = "string"
+                if param.annotation != inspect.Parameter.empty:
+                    if param.annotation is int:
+                        param_type = "integer"
+                    elif param.annotation is float:
+                        param_type = "number"
+                    elif param.annotation is bool:
+                        param_type = "boolean"
+
+                properties[param_name] = {"type": param_type}
+
+                if param.default == inspect.Parameter.empty:
+                    required.append(param_name)
+
+            definitions.append({
+                "name": tool_info["name"],
+                "description": tool_info["description"],
+                "parameters": {
+                    "type": "object",
+                    "properties": properties,
+                    "required": required,
+                },
+            })
+
+        return definitions
+
+
+def parallel_tools(*tools: Callable) -> list[Callable]:
+    """
+    Convenience wrapper to mark tools for parallel execution.
+
+    Usage:
+        from copex.tools import parallel_tools
+
+        tools = parallel_tools(get_weather, get_time, fetch_data)
+
+        async with Copex() as copex:
+            response = await copex.send("...", tools=tools)
+    """
+    return list(tools)