aloop 0.1.0__py3-none-any.whl

agent/context.py

@@ -0,0 +1,126 @@
+"""Context injection module for providing environment information to agents."""
+
+import asyncio
+import os
+import platform
+from datetime import datetime
+from typing import Any, Dict
+
+
+def get_working_directory() -> str:
+    """Get the current working directory.
+
+    Returns:
+        Absolute path of current working directory
+    """
+    return os.getcwd()
+
+
+def get_platform_info() -> Dict[str, str]:
+    """Get platform and system information.
+
+    Returns:
+        Dictionary with platform details
+    """
+    return {
+        "system": platform.system(),  # Linux, Darwin, Windows
+        "platform": os.name,  # posix, nt
+        "python_version": platform.python_version(),
+    }
+
+
+async def _run_git_command(args: list[str], timeout: float = 2.0) -> tuple[int, str, str]:
+    process = await asyncio.create_subprocess_exec(
+        *args,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    try:
+        stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=timeout)
+    except asyncio.TimeoutError:
+        process.kill()
+        await process.communicate()
+        raise
+    returncode = process.returncode if process.returncode is not None else 0
+    return (
+        returncode,
+        stdout.decode(errors="ignore").strip(),
+        stderr.decode(errors="ignore").strip(),
+    )
+
+
+async def get_git_status() -> Dict[str, Any]:
+    """Get git repository information if available.
+
+    Returns:
+        Dictionary with git information or is_repo=False
+    """
+    try:
+        returncode, _, _ = await _run_git_command(["git", "rev-parse", "--git-dir"], timeout=2)
+        if returncode != 0:
+            return {"is_repo": False}
+
+        _, branch, _ = await _run_git_command(["git", "rev-parse", "--abbrev-ref", "HEAD"], 2)
+        _, status, _ = await _run_git_command(["git", "status", "--short"], 2)
+        _, recent_commits, _ = await _run_git_command(["git", "log", "-5", "--oneline"], 2)
+
+        try:
+            _, remote_head, _ = await _run_git_command(
+                ["git", "symbolic-ref", "refs/remotes/origin/HEAD"], 2
+            )
+            main_branch = remote_head.split("/")[-1] if remote_head else "main"
+        except asyncio.TimeoutError:
+            main_branch = "main"
+
+        return {
+            "is_repo": True,
+            "branch": branch,
+            "main_branch": main_branch,
+            "status": status if status else "Clean working directory",
+            "recent_commits": recent_commits,
+            "has_uncommitted_changes": bool(status),
+        }
+
+    except (asyncio.TimeoutError, FileNotFoundError):
+        return {"is_repo": False}
+
+
+async def format_context_prompt() -> str:
+    """Format environment context as a prompt section.
+
+    Returns:
+        Formatted context string with XML tags
+
+    Note:
+        Git information is intentionally excluded to save tokens.
+        Agents can use git_status, git_log, and other git tools
+        to get up-to-date repository information when needed.
+    """
+    cwd = get_working_directory()
+    platform_info = get_platform_info()
+    today = datetime.now().strftime("%Y-%m-%d")
+
+    lines = [
+        "<environment>",
+        f"Working directory: {cwd}",
+        f"Platform: {platform_info['system']}",
+        f"Today's date: {today}",
+        "</environment>\n",
+    ]
+
+    return "\n".join(lines)
+
+
+async def get_context_dict() -> Dict[str, Any]:
+    """Get context information as a dictionary.
+
+    Returns:
+        Dictionary with all context information
+    """
+    return {
+        "working_directory": get_working_directory(),
+        "platform": get_platform_info(),
+        "git": await get_git_status(),
+        "date": datetime.now().strftime("%Y-%m-%d"),
+        "timestamp": datetime.now().isoformat(),
+    }

agent/todo.py

@@ -0,0 +1,149 @@
+"""Todo list management for agents to track complex multi-step tasks."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Dict, List
+
+
+class TodoStatus(Enum):
+    """Status of a todo item."""
+
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+
+
+@dataclass
+class TodoItem:
+    """A single todo item."""
+
+    content: str  # Imperative form: "Fix authentication bug"
+    activeForm: str  # Present continuous form: "Fixing authentication bug"
+    status: TodoStatus
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for serialization."""
+        return {"content": self.content, "activeForm": self.activeForm, "status": self.status.value}
+
+
+class TodoList:
+    """Manages a list of todo items for an agent."""
+
+    def __init__(self) -> None:
+        self._items: List[TodoItem] = []
+
+    def add(self, content: str, activeForm: str) -> str:
+        """Add a new todo item.
+
+        Args:
+            content: Imperative form (e.g., "Read CSV file")
+            activeForm: Present continuous form (e.g., "Reading CSV file")
+
+        Returns:
+            Success message with item index
+        """
+        if not content or not activeForm:
+            return "Error: Both content and activeForm are required"
+
+        item = TodoItem(content=content, activeForm=activeForm, status=TodoStatus.PENDING)
+        self._items.append(item)
+        return f"Added todo #{len(self._items)}: {content}"
+
+    def update_status(self, index: int, status: str) -> str:
+        """Update the status of a todo item.
+
+        Args:
+            index: 1-indexed position of the todo item
+            status: New status (pending, in_progress, or completed)
+
+        Returns:
+            Success or error message
+        """
+        if index < 1 or index > len(self._items):
+            return f"Error: Invalid index {index}. Valid range: 1-{len(self._items)}"
+
+        try:
+            new_status = TodoStatus(status)
+        except ValueError:
+            return f"Error: Invalid status '{status}'. Must be: pending, in_progress, or completed"
+
+        # Check the ONE in_progress rule
+        if new_status == TodoStatus.IN_PROGRESS:
+            in_progress_count = sum(
+                1 for item in self._items if item.status == TodoStatus.IN_PROGRESS
+            )
+            if in_progress_count > 0:
+                in_progress_items = [
+                    i + 1
+                    for i, item in enumerate(self._items)
+                    if item.status == TodoStatus.IN_PROGRESS
+                ]
+                return f"Error: Task #{in_progress_items[0]} is already in_progress. Complete it first before starting another task."
+
+        item = self._items[index - 1]
+        old_status = item.status.value
+        item.status = new_status
+
+        return f"Updated todo #{index} status: {old_status} → {status}"
+
+    def get_current(self) -> List[TodoItem]:
+        """Get all current todo items."""
+        return self._items.copy()
+
+    def remove(self, index: int) -> str:
+        """Remove a todo item.
+
+        Args:
+            index: 1-indexed position of the todo item
+
+        Returns:
+            Success or error message
+        """
+        if index < 1 or index > len(self._items):
+            return f"Error: Invalid index {index}. Valid range: 1-{len(self._items)}"
+
+        item = self._items.pop(index - 1)
+        return f"Removed todo: {item.content}"
+
+    def format_list(self) -> str:
+        """Format the todo list for display."""
+        if not self._items:
+            return "No todos in the list"
+
+        lines = ["Current Todo List:"]
+        for i, item in enumerate(self._items, 1):
+            status_symbol = {
+                TodoStatus.PENDING: "⏳",
+                TodoStatus.IN_PROGRESS: "🔄",
+                TodoStatus.COMPLETED: "✅",
+            }[item.status]
+
+            status_text = item.activeForm if item.status == TodoStatus.IN_PROGRESS else item.content
+            lines.append(f"{i}. {status_symbol} [{item.status.value}] {status_text}")
+
+        # Summary
+        pending = sum(1 for item in self._items if item.status == TodoStatus.PENDING)
+        in_progress = sum(1 for item in self._items if item.status == TodoStatus.IN_PROGRESS)
+        completed = sum(1 for item in self._items if item.status == TodoStatus.COMPLETED)
+
+        lines.append(
+            f"\nSummary: {completed} completed, {in_progress} in progress, {pending} pending"
+        )
+
+        return "\n".join(lines)
+
+    def get_summary(self) -> Dict[str, int]:
+        """Get summary statistics."""
+        return {
+            "total": len(self._items),
+            "pending": sum(1 for item in self._items if item.status == TodoStatus.PENDING),
+            "in_progress": sum(1 for item in self._items if item.status == TodoStatus.IN_PROGRESS),
+            "completed": sum(1 for item in self._items if item.status == TodoStatus.COMPLETED),
+        }
+
+    def clear_completed(self) -> str:
+        """Remove all completed items."""
+        before_count = len(self._items)
+        self._items = [item for item in self._items if item.status != TodoStatus.COMPLETED]
+        removed = before_count - len(self._items)
+        return f"Removed {removed} completed todo(s)"

agent/tool_executor.py

@@ -0,0 +1,54 @@
+"""Tool execution engine for managing and executing tools."""
+
+import asyncio
+from typing import Any, Dict, List
+
+from config import Config
+from tools.base import BaseTool
+
+
+class ToolExecutor:
+    """Executes tools called by the LLM."""
+
+    def __init__(self, tools: List[BaseTool]):
+        """Initialize with a list of tools."""
+        self.tools = {tool.name: tool for tool in tools}
+
+    async def execute_tool_call(self, tool_name: str, tool_input: Dict[str, Any]) -> str:
+        """Execute a single tool call and return result."""
+        if tool_name not in self.tools:
+            return f"Error: Tool '{tool_name}' not found"
+
+        try:
+            timeout = Config.TOOL_TIMEOUT
+            if "timeout" in tool_input and tool_input["timeout"] is not None:
+                try:
+                    timeout = float(tool_input["timeout"])
+                except (TypeError, ValueError):
+                    timeout = Config.TOOL_TIMEOUT
+
+            if timeout is not None and timeout > 0:
+                async with asyncio.timeout(timeout):
+                    result = await self.tools[tool_name].execute(**tool_input)
+            else:
+                result = await self.tools[tool_name].execute(**tool_input)
+            return str(result)
+        except asyncio.CancelledError:
+            # Re-raise CancelledError to allow proper cleanup
+            raise
+        except TimeoutError:
+            return f"Error: Tool '{tool_name}' timed out after {timeout}s"
+        except Exception as e:
+            return f"Error executing {tool_name}: {str(e)}"
+
+    def get_tool_schemas(self) -> List[Dict[str, Any]]:
+        """Get Anthropic-formatted schemas for all tools."""
+        return [tool.to_anthropic_schema() for tool in self.tools.values()]
+
+    def add_tool(self, tool: BaseTool):
+        """Add a tool to the executor.
+
+        Args:
+            tool: Tool instance to add
+        """
+        self.tools[tool.name] = tool

agent/verification.py

@@ -0,0 +1,135 @@
+"""Verification interface and default LLM verifier for the Ralph Loop.
+
+The verifier judges whether the agent's final answer truly satisfies the
+original task. If not, feedback is returned so the outer loop can re-enter
+the inner ReAct loop with corrective guidance.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from llm import LLMMessage
+from utils import get_logger
+from utils.tui.progress import AsyncSpinner
+
+if TYPE_CHECKING:
+    from llm import LiteLLMAdapter
+    from utils.tui.terminal_ui import TerminalUI
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class VerificationResult:
+    """Result of a verification check."""
+
+    complete: bool
+    reason: str
+
+
+@runtime_checkable
+class Verifier(Protocol):
+    """Protocol for task-completion verifiers."""
+
+    async def verify(
+        self,
+        task: str,
+        result: str,
+        iteration: int,
+        previous_results: list[VerificationResult],
+    ) -> VerificationResult:
+        """Judge whether *result* satisfies *task*.
+
+        Args:
+            task: The original user task description.
+            result: The agent's final answer from the inner loop.
+            iteration: Current outer-loop iteration (1-indexed).
+            previous_results: Verification results from earlier iterations.
+
+        Returns:
+            VerificationResult indicating completion status and reasoning.
+        """
+        ...  # pragma: no cover
+
+
+_VERIFICATION_PROMPT = """\
+You are a strict verification assistant. Your job is to determine whether an \
+AI agent's answer fully and correctly completes the user's original task.
+
+<task>
+{task}
+</task>
+
+<agent_answer>
+{result}
+</agent_answer>
+
+{previous_context}
+
+<judgment_rules>
+1. If the task is a ONE-TIME request (e.g. "calculate 1+1", "summarize this file"), \
+judge whether the answer is correct and complete.
+
+2. If the task requires MULTIPLE steps and only some were done, respond INCOMPLETE \
+with specific feedback on what remains.
+</judgment_rules>
+
+Respond with EXACTLY one of:
+- COMPLETE: <brief reason why the task is satisfied>
+- INCOMPLETE: <specific feedback on what is missing or wrong>
+
+Do NOT restate the answer. Only judge it."""
+
+
+class LLMVerifier:
+    """Default verifier that uses a lightweight LLM call (no tools)."""
+
+    def __init__(self, llm: LiteLLMAdapter, terminal_ui: TerminalUI | None = None):
+        self.llm = llm
+        self._tui = terminal_ui
+
+    async def verify(
+        self,
+        task: str,
+        result: str,
+        iteration: int,
+        previous_results: list[VerificationResult],
+    ) -> VerificationResult:
+        previous_context = ""
+        if previous_results:
+            lines = []
+            for i, pr in enumerate(previous_results, 1):
+                status = "complete" if pr.complete else "incomplete"
+                lines.append(f"  Attempt {i}: {status} — {pr.reason}")
+            previous_context = "Previous verification attempts:\n" + "\n".join(lines)
+
+        prompt = _VERIFICATION_PROMPT.format(
+            task=task,
+            result=result[:4000],  # Truncate to avoid excessive tokens
+            previous_context=previous_context,
+        )
+
+        messages = [
+            LLMMessage(role="system", content="You are a task-completion verifier."),
+            LLMMessage(role="user", content=prompt),
+        ]
+
+        console = self._tui.console if self._tui else None
+        if console:
+            async with AsyncSpinner(console, "Verifying completion..."):
+                response = await self.llm.call_async(messages=messages, tools=None, max_tokens=512)
+        else:
+            response = await self.llm.call_async(messages=messages, tools=None, max_tokens=512)
+
+        text = (response.content or "").strip()
+        logger.debug(f"Verification response (iter {iteration}): {text}")
+
+        upper = text.upper()
+        if upper.startswith("COMPLETE"):
+            reason = text.split(":", 1)[1].strip() if ":" in text else text
+            return VerificationResult(complete=True, reason=reason)
+        else:
+            reason = text.split(":", 1)[1].strip() if ":" in text else text
+            return VerificationResult(complete=False, reason=reason)