gobby 0.2.5__py3-none-any.whl

gobby/llm/executor.py

@@ -0,0 +1,316 @@
+"""
+Abstract base class for agent executors.
+
+AgentExecutor defines the interface for executing agentic loops with tool calling.
+Each LLM provider implements this interface to enable subagent spawning.
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+
+@dataclass
+class ToolSchema:
+    """Schema definition for an MCP tool."""
+
+    name: str
+    """Tool name (e.g., 'create_task')."""
+
+    description: str
+    """Human-readable description of what the tool does."""
+
+    input_schema: dict[str, Any]
+    """JSON Schema for the tool's input parameters."""
+
+    server_name: str | None = None
+    """Optional server name this tool belongs to (e.g., 'gobby-tasks')."""
+
+
+@dataclass
+class ToolResult:
+    """Result from executing a tool call."""
+
+    tool_name: str
+    """Name of the tool that was called."""
+
+    success: bool
+    """Whether the tool call succeeded."""
+
+    result: Any = None
+    """Result data from the tool (if success=True)."""
+
+    error: str | None = None
+    """Error message (if success=False)."""
+
+
+@dataclass
+class ToolCallRecord:
+    """Record of a tool call made during agent execution."""
+
+    tool_name: str
+    """Name of the tool that was called."""
+
+    arguments: dict[str, Any]
+    """Arguments passed to the tool."""
+
+    result: ToolResult | None = None
+    """Result from the tool execution."""
+
+
+@dataclass
+class AgentResult:
+    """Result from running an agent to completion."""
+
+    output: str
+    """Final text output from the agent."""
+
+    status: Literal["success", "partial", "blocked", "timeout", "error"]
+    """Completion status of the agent run."""
+
+    tool_calls: list[ToolCallRecord] = field(default_factory=list)
+    """List of all tool calls made during execution."""
+
+    artifacts: dict[str, Any] = field(default_factory=dict)
+    """Structured artifacts produced by the agent (via complete() tool)."""
+
+    files_modified: list[str] = field(default_factory=list)
+    """List of files modified during execution."""
+
+    next_steps: list[str] = field(default_factory=list)
+    """Suggested next steps from the agent."""
+
+    error: str | None = None
+    """Error message if status is 'error'."""
+
+    turns_used: int = 0
+    """Number of turns used during execution."""
+
+    run_id: str | None = None
+    """ID of the agent run (set by AgentRunner)."""
+
+    child_session_id: str | None = None
+    """ID of the child session created for this agent (set by AgentRunner)."""
+
+
+# Type alias for the tool handler callback
+ToolHandler = Callable[[str, dict[str, Any]], Awaitable[ToolResult]]
+"""
+Callback function to execute a tool call.
+
+Args:
+    tool_name: Name of the tool to execute.
+    arguments: Arguments to pass to the tool.
+
+Returns:
+    ToolResult with success/failure and result data.
+"""
+
+
+class AgentExecutor(ABC):
+    """
+    Abstract base class for executing agentic loops with tool calling.
+
+    Each LLM provider (Claude, Gemini, Codex, LiteLLM) implements this interface
+    to enable subagent spawning. The executor handles:
+
+    - Running the agent loop with tool calling
+    - Enforcing turn limits and timeouts
+    - Calling tools via the provided tool_handler
+    - Detecting completion (via 'complete' tool or natural end)
+    - Returning structured results
+
+    The tool_handler callback is provided by the caller (AgentRunner) and handles:
+    - Workflow-based tool filtering
+    - Routing to MCP servers
+    - Recording tool metrics
+
+    Example usage:
+        >>> executor = ClaudeExecutor(config)
+        >>> result = await executor.run(
+        ...     prompt="Create a task called 'Fix bug'",
+        ...     tools=[ToolSchema(name="create_task", ...)],
+        ...     tool_handler=my_tool_handler,
+        ... )
+        >>> print(result.output)
+        >>> print(result.status)
+    """
+
+    @property
+    @abstractmethod
+    def provider_name(self) -> str:
+        """
+        Return the provider name for this executor.
+
+        Returns:
+            Provider name (e.g., "claude", "gemini", "litellm", "codex").
+        """
+        pass
+
+    @abstractmethod
+    async def run(
+        self,
+        prompt: str,
+        tools: list[ToolSchema],
+        tool_handler: ToolHandler,
+        system_prompt: str | None = None,
+        model: str | None = None,
+        max_turns: int = 10,
+        timeout: float = 120.0,
+    ) -> AgentResult:
+        """
+        Execute an agentic loop with tool calling.
+
+        Runs the agent with the given prompt, making tool calls as needed
+        until completion, max_turns, or timeout.
+
+        Args:
+            prompt: The user prompt to process.
+            tools: List of available tools with their schemas.
+            tool_handler: Callback to execute tool calls. This is called
+                whenever the agent wants to use a tool.
+            system_prompt: Optional system prompt to set agent behavior.
+            model: Optional model override. If None, uses provider default.
+            max_turns: Maximum number of turns before stopping (default: 10).
+            timeout: Maximum execution time in seconds (default: 120.0).
+
+        Returns:
+            AgentResult containing output, status, tool calls, and artifacts.
+
+        Raises:
+            No exceptions should be raised - errors are captured in AgentResult.
+        """
+        pass
+
+    async def run_with_complete_tool(
+        self,
+        prompt: str,
+        tools: list[ToolSchema],
+        tool_handler: ToolHandler,
+        system_prompt: str | None = None,
+        model: str | None = None,
+        max_turns: int = 10,
+        timeout: float = 120.0,
+    ) -> AgentResult:
+        """
+        Execute an agentic loop that requires explicit completion via 'complete' tool.
+
+        This is a convenience wrapper that adds the 'complete' tool to the
+        available tools and watches for its invocation to terminate the loop.
+
+        The complete tool signature:
+            complete(
+                output: str,
+                status: Literal["success", "partial", "blocked"] = "success",
+                artifacts: dict[str, Any] = {},
+                files_modified: list[str] = [],
+                next_steps: list[str] = [],
+            )
+
+        Args:
+            prompt: The user prompt to process.
+            tools: List of available tools (complete tool is added automatically).
+            tool_handler: Callback to execute tool calls.
+            system_prompt: Optional system prompt.
+            model: Optional model override.
+            max_turns: Maximum turns before stopping.
+            timeout: Maximum execution time in seconds.
+
+        Returns:
+            AgentResult populated from the complete() call, or with status='timeout'
+            if the agent didn't call complete() before limits were reached.
+        """
+        # Add complete tool schema
+        complete_tool = ToolSchema(
+            name="complete",
+            description=(
+                "Signal that you have completed the task. Call this when you are done "
+                "with all work. Provide a summary of what was accomplished, any artifacts "
+                "produced, and suggested next steps."
+            ),
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "output": {
+                        "type": "string",
+                        "description": "Summary of what was accomplished.",
+                    },
+                    "status": {
+                        "type": "string",
+                        "enum": ["success", "partial", "blocked"],
+                        "default": "success",
+                        "description": "Completion status.",
+                    },
+                    "artifacts": {
+                        "type": "object",
+                        "description": "Structured outputs from the task.",
+                        "default": {},
+                    },
+                    "files_modified": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "List of files that were modified.",
+                        "default": [],
+                    },
+                    "next_steps": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Suggested next steps for the caller.",
+                        "default": [],
+                    },
+                },
+                "required": ["output"],
+            },
+        )
+
+        all_tools = [*tools, complete_tool]
+        completion_result: AgentResult | None = None
+
+        async def wrapped_handler(tool_name: str, arguments: dict[str, Any]) -> ToolResult:
+            nonlocal completion_result
+
+            if tool_name == "complete":
+                # Validate status against allowed values for complete() tool
+                allowed_statuses = {"success", "partial", "blocked"}
+                raw_status = arguments.get("status")
+                validated_status: Literal["success", "partial", "blocked"] = (
+                    raw_status if raw_status in allowed_statuses else "success"
+                )
+
+                # Extract completion data
+                completion_result = AgentResult(
+                    output=arguments.get("output", ""),
+                    status=validated_status,
+                    artifacts=arguments.get("artifacts", {}),
+                    files_modified=arguments.get("files_modified", []),
+                    next_steps=arguments.get("next_steps", []),
+                )
+                return ToolResult(
+                    tool_name="complete",
+                    success=True,
+                    result="Task completed.",
+                )
+
+            # Delegate to the original handler
+            return await tool_handler(tool_name, arguments)
+
+        # Run with the wrapped handler
+        result = await self.run(
+            prompt=prompt,
+            tools=all_tools,
+            tool_handler=wrapped_handler,
+            system_prompt=system_prompt,
+            model=model,
+            max_turns=max_turns,
+            timeout=timeout,
+        )
+
+        # If complete() was called, use that result (preserving tool_calls and turns)
+        if completion_result is not None:
+            completion_result.tool_calls = result.tool_calls
+            completion_result.turns_used = result.turns_used
+            return completion_result
+
+        # Otherwise, return the raw result (might be timeout or natural end)
+        return result

gobby/llm/factory.py

@@ -0,0 +1,34 @@
+"""
+Factory for creating LLM service.
+
+Provides factory function for creating LLMService with multi-provider support.
+"""
+
+import logging
+
+from gobby.config.app import DaemonConfig
+from gobby.llm.service import LLMService
+
+logger = logging.getLogger(__name__)
+
+
+def create_llm_service(config: DaemonConfig) -> LLMService:
+    """
+    Create an LLM service for multi-provider support.
+
+    Args:
+        config: Client configuration with llm_providers.
+
+    Returns:
+        LLMService instance with access to all configured providers.
+
+    Raises:
+        ValueError: If config doesn't have llm_providers set.
+
+    Example:
+        service = create_llm_service(config)
+        provider, model, prompt = service.get_provider_for_feature(
+            config.session_summary
+        )
+    """
+    return LLMService(config)

gobby/llm/gemini.py

@@ -0,0 +1,258 @@
+"""
+Gemini implementation of LLMProvider.
+
+Supports two authentication modes:
+- api_key: Use GEMINI_API_KEY environment variable (BYOK)
+- adc: Use Google Application Default Credentials (subscription-based via gcloud auth)
+"""
+
+import json
+import logging
+import os
+from typing import Any, Literal
+
+from gobby.config.app import DaemonConfig
+from gobby.llm.base import AuthMode, LLMProvider
+
+logger = logging.getLogger(__name__)
+
+
+class GeminiProvider(LLMProvider):
+    """
+    Gemini implementation of LLMProvider using google-generativeai package.
+
+    Supports two authentication modes:
+    - api_key: Use GEMINI_API_KEY environment variable (BYOK)
+    - adc: Use Google Application Default Credentials (run `gcloud auth application-default login`)
+    """
+
+    def __init__(
+        self,
+        config: DaemonConfig,
+        auth_mode: Literal["api_key", "adc"] | None = None,
+    ):
+        """
+        Initialize GeminiProvider.
+
+        Args:
+            config: Client configuration.
+            auth_mode: Override auth mode. If None, reads from config.llm_providers.gemini.auth_mode
+                      or falls back to "api_key".
+        """
+        self.config = config
+        self.logger = logger
+        self.model_summary = None
+        self.model_title = None
+
+        # Determine auth mode from config or parameter
+        self._auth_mode: AuthMode = "api_key"  # Default
+        if auth_mode:
+            self._auth_mode = auth_mode
+        elif config.llm_providers and config.llm_providers.gemini:
+            self._auth_mode = config.llm_providers.gemini.auth_mode
+
+        try:
+            import google.generativeai as genai
+
+            # Initialize based on auth mode
+            if self._auth_mode == "adc":
+                # Use Application Default Credentials
+                # User must run: gcloud auth application-default login
+                try:
+                    import google.auth
+
+                    credentials, project = google.auth.default()
+                    genai.configure(credentials=credentials)
+                    self.genai = genai
+                    self.logger.debug("Gemini initialized with ADC credentials")
+                except Exception as e:
+                    self.logger.error(
+                        f"Failed to initialize Gemini with ADC: {e}. "
+                        "Run 'gcloud auth application-default login' to authenticate."
+                    )
+                    self.genai = None
+            else:
+                # Use API key from environment
+                api_key = os.environ.get("GEMINI_API_KEY")
+                if api_key:
+                    genai.configure(api_key=api_key)
+                    self.genai = genai
+                    self.logger.debug("Gemini initialized with API key")
+                else:
+                    self.logger.warning("GEMINI_API_KEY not found in environment variables.")
+                    self.genai = None
+
+            # Initialize models if genai is configured
+            if self.genai:
+                summary_model_name = self.config.session_summary.model or "gemini-1.5-pro"
+                title_model_name = self.config.title_synthesis.model or "gemini-1.5-flash"
+
+                self.model_summary = genai.GenerativeModel(summary_model_name)
+                self.model_title = genai.GenerativeModel(title_model_name)
+
+        except ImportError:
+            self.logger.error(
+                "google-generativeai package not found. Please install with `pip install google-generativeai`."
+            )
+            self.genai = None
+        except Exception as e:
+            self.logger.error(f"Failed to initialize Gemini client: {e}")
+            self.genai = None
+
+    @property
+    def provider_name(self) -> str:
+        """Return provider name."""
+        return "gemini"
+
+    @property
+    def auth_mode(self) -> AuthMode:
+        """Return the authentication mode for this provider."""
+        return self._auth_mode
+
+    async def generate_summary(
+        self, context: dict[str, Any], prompt_template: str | None = None
+    ) -> str:
+        """
+        Generate session summary using Gemini.
+        """
+        if not self.genai or not self.model_summary:
+            return "Session summary unavailable (Gemini client not initialized)"
+
+        # Build formatted context for prompt template
+        formatted_context = {
+            "transcript_summary": context.get("transcript_summary", ""),
+            "last_messages": json.dumps(context.get("last_messages", []), indent=2),
+            "git_status": context.get("git_status", ""),
+            "file_changes": context.get("file_changes", ""),
+            **{
+                k: v
+                for k, v in context.items()
+                if k not in ["transcript_summary", "last_messages", "git_status", "file_changes"]
+            },
+        }
+
+        # Build prompt - prompt_template is required
+        if not prompt_template:
+            raise ValueError(
+                "prompt_template is required for generate_summary. "
+                "Configure 'session_summary.prompt' in ~/.gobby/config.yaml"
+            )
+        prompt = prompt_template.format(**formatted_context)
+
+        try:
+            # Gemini async generation
+            response = await self.model_summary.generate_content_async(prompt)
+            return response.text or ""
+        except Exception as e:
+            self.logger.error(f"Failed to generate summary with Gemini: {e}")
+            return f"Session summary generation failed: {e}"
+
+    async def synthesize_title(
+        self, user_prompt: str, prompt_template: str | None = None
+    ) -> str | None:
+        """
+        Synthesize session title using Gemini.
+        """
+        if not self.genai or not self.model_title:
+            return None
+
+        # Build prompt - prompt_template is required
+        if not prompt_template:
+            raise ValueError(
+                "prompt_template is required for synthesize_title. "
+                "Configure 'title_synthesis.prompt' in ~/.gobby/config.yaml"
+            )
+        prompt = prompt_template.format(user_prompt=user_prompt)
+
+        try:
+            response = await self.model_title.generate_content_async(prompt)
+            return (response.text or "").strip()
+        except Exception as e:
+            self.logger.error(f"Failed to synthesize title with Gemini: {e}")
+            return None
+
+    async def generate_text(
+        self,
+        prompt: str,
+        system_prompt: str | None = None,
+        model: str | None = None,
+    ) -> str:
+        """
+        Generate text using Gemini.
+        """
+        if not self.genai:
+            return "Generation unavailable (Gemini client not initialized)"
+
+        model_name = model or "gemini-1.5-flash"
+
+        try:
+            # Note: Gemini system prompts are configured at model creation,
+            # but simple generation usually just includes it in the prompt or uses default.
+            # For simplicity we'll just generate content.
+            model_instance = self.genai.GenerativeModel(model_name)
+
+            full_prompt = prompt
+            if system_prompt:
+                # Prepend system prompt if provided
+                full_prompt = f"{system_prompt}\n\n{prompt}"
+
+            response = await model_instance.generate_content_async(full_prompt)
+            return response.text or ""
+        except Exception as e:
+            self.logger.error(f"Failed to generate text with Gemini: {e}")
+            return f"Generation failed: {e}"
+
+    async def describe_image(
+        self,
+        image_path: str,
+        context: str | None = None,
+    ) -> str:
+        """
+        Generate a text description of an image using Gemini's vision capabilities.
+
+        Uses Gemini 1.5 Flash for efficient image description.
+
+        Args:
+            image_path: Path to the image file
+            context: Optional context to guide the description
+
+        Returns:
+            Text description of the image
+        """
+        from pathlib import Path
+
+        if not self.genai:
+            return "Image description unavailable (Gemini client not initialized)"
+
+        path = Path(image_path)
+        if not path.exists():
+            return f"Image not found: {image_path}"
+
+        try:
+            # Use PIL to load the image - Gemini accepts PIL images directly
+            from PIL import Image
+
+            # Use context manager to ensure image file handle is properly closed
+            with Image.open(path) as image:
+                # Build prompt
+                prompt = (
+                    "Please describe this image in detail, focusing on key visual elements, "
+                    "any text visible, and the overall context or meaning."
+                )
+                if context:
+                    prompt = f"{context}\n\n{prompt}"
+
+                # Use gemini-1.5-flash for efficient vision tasks
+                model = self.genai.GenerativeModel("gemini-1.5-flash")
+
+                # Generate content with image and prompt
+                response = await model.generate_content_async([prompt, image])
+
+                return response.text or "No description generated"
+
+        except ImportError:
+            self.logger.error("PIL/Pillow not installed. Required for image description.")
+            return "Image description unavailable (PIL not installed)"
+        except Exception as e:
+            self.logger.error(f"Failed to describe image with Gemini: {e}")
+            return f"Image description failed: {e}"