massgen 0.0.3__py3-none-any.whl → 0.1.0__py3-none-any.whl

massgen/backend/cli_base.py

@@ -0,0 +1,209 @@
+# -*- coding: utf-8 -*-
+"""
+CLI Backend Base Class - Abstract interface for CLI-based LLM backends.
+
+This module provides the base class for backends that interact with LLM providers
+through command-line interfaces (like Claude Code CLI, Gemini CLI, etc.).
+"""
+
+import asyncio
+import subprocess
+import tempfile
+from abc import abstractmethod
+from pathlib import Path
+from typing import Any, AsyncGenerator, Dict, List, Optional
+
+from .base import LLMBackend, StreamChunk, TokenUsage
+
+
+class CLIBackend(LLMBackend):
+    """Abstract base class for CLI-based LLM backends."""
+
+    def __init__(self, cli_command: str, api_key: Optional[str] = None, **kwargs):
+        super().__init__(api_key, **kwargs)
+        self.cli_command = cli_command
+        self.working_dir = kwargs.get("working_dir", Path.cwd())
+        self.timeout = kwargs.get("timeout", 300)  # 5 minutes default
+
+    @abstractmethod
+    def _build_command(self, messages: List[Dict[str, Any]], tools: List[Dict[str, Any]], **kwargs) -> List[str]:
+        """Build the CLI command to execute.
+
+        Args:
+            messages: Conversation messages
+            tools: Available tools
+            **kwargs: Additional parameters
+
+        Returns:
+            List of command arguments for subprocess
+        """
+
+    @abstractmethod
+    def _parse_output(self, output: str) -> Dict[str, Any]:
+        """Parse CLI output into structured format.
+
+        Args:
+            output: Raw CLI output
+
+        Returns:
+            Parsed response data
+        """
+
+    async def _execute_cli_command(self, command: List[str]) -> str:
+        """Execute CLI command asynchronously.
+
+        Args:
+            command: Command arguments
+
+        Returns:
+            Command output
+
+        Raises:
+            subprocess.CalledProcessError: If command fails
+            asyncio.TimeoutError: If command times out
+        """
+        process = await asyncio.create_subprocess_exec(
+            *command,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=self.working_dir,
+        )
+
+        try:
+            stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=self.timeout)
+
+            if process.returncode != 0:
+                error_msg = stderr.decode("utf-8") if stderr else "Unknown error"
+                raise subprocess.CalledProcessError(process.returncode, command, error_msg)
+
+            return stdout.decode("utf-8")
+
+        except asyncio.TimeoutError as exc:
+            process.kill()
+            await process.wait()
+            raise asyncio.TimeoutError(f"CLI command timed out after {self.timeout} seconds") from exc
+
+    def _create_temp_file(self, content: str, suffix: str = ".txt") -> Path:
+        """Create a temporary file with content.
+
+        Args:
+            content: File content
+            suffix: File suffix
+
+        Returns:
+            Path to temporary file
+        """
+        with tempfile.NamedTemporaryFile(mode="w", suffix=suffix, delete=False) as temp_file:
+            temp_file.write(content)
+            return Path(temp_file.name)
+
+    def _format_messages_for_cli(self, messages: List[Dict[str, Any]]) -> str:
+        """Format messages for CLI input.
+
+        Args:
+            messages: Conversation messages
+
+        Returns:
+            Formatted string for CLI
+        """
+        formatted_parts = []
+
+        for msg in messages:
+            role = msg.get("role", "user")
+            content = msg.get("content", "")
+
+            if role == "system":
+                formatted_parts.append(f"System: {content}")
+            elif role == "user":
+                formatted_parts.append(f"User: {content}")
+            elif role == "assistant":
+                formatted_parts.append(f"Assistant: {content}")
+
+        return "\n\n".join(formatted_parts)
+
+    async def stream_with_tools(self, messages: List[Dict[str, Any]], tools: List[Dict[str, Any]], **kwargs) -> AsyncGenerator[StreamChunk, None]:
+        """Stream response with tools support."""
+        try:
+            # Build CLI command
+            command = self._build_command(messages, tools, **kwargs)
+
+            # Execute command
+            output = await self._execute_cli_command(command)
+
+            # Parse output
+            parsed_response = self._parse_output(output)
+
+            # Convert to stream chunks
+            async for chunk in self._convert_to_stream_chunks(parsed_response):
+                yield chunk
+
+        except Exception as e:
+            yield StreamChunk(
+                type="error",
+                error=f"CLI backend error: {str(e)}",
+                source=self.__class__.__name__,
+            )
+
+    async def _convert_to_stream_chunks(self, response: Dict[str, Any]) -> AsyncGenerator[StreamChunk, None]:
+        """Convert parsed response to stream chunks.
+
+        Args:
+            response: Parsed response data
+
+        Yields:
+            StreamChunk objects
+        """
+        # Yield content
+        if "content" in response and response["content"]:
+            yield StreamChunk(
+                type="content",
+                content=response["content"],
+                source=self.__class__.__name__,
+            )
+
+        # Yield tool calls if present
+        if "tool_calls" in response and response["tool_calls"]:
+            yield StreamChunk(
+                type="tool_calls",
+                tool_calls=response["tool_calls"],
+                source=self.__class__.__name__,
+            )
+
+        # Yield complete message
+        yield StreamChunk(
+            type="complete_message",
+            complete_message=response,
+            source=self.__class__.__name__,
+        )
+
+        # Yield done
+        yield StreamChunk(type="done", source=self.__class__.__name__)
+
+    def get_token_usage(self) -> TokenUsage:
+        """Get token usage statistics."""
+        # CLI backends typically don't provide detailed token usage
+        # This could be estimated or left as zero
+        return self.token_usage
+
+    def get_cost_per_token(self) -> Dict[str, float]:
+        """Get cost per token for this provider."""
+        # Override in specific implementations
+        return {"input": 0.0, "output": 0.0}
+
+    def get_model_name(self) -> str:
+        """Get the model name being used."""
+        return self.config.get("model", "unknown")
+
+    def get_provider_info(self) -> Dict[str, Any]:
+        """Get provider information."""
+        return {
+            "provider": self.__class__.__name__,
+            "cli_command": self.cli_command,
+            "model": self.get_model_name(),
+            "supports_tools": True,
+            "supports_streaming": True,
+        }
+
+    def get_provider_name(self) -> str:
+        """Get the name of this provider."""
+        return self.__class__.__name__

massgen/backend/docs/BACKEND_ARCHITECTURE.md

@@ -0,0 +1,126 @@
+# Backend Architecture: Stateful vs Stateless
+
+## Overview
+
+The MassGen backend system supports two distinct architectural patterns for AI model backends: stateless and stateful. Understanding these patterns is crucial for proper agent implementation and state management.
+
+## Backend Types
+
+### Stateless Backends
+
+**Examples:** `ChatCompletionBackend`, OpenAI GPT models, Gemini
+
+**Characteristics:**
+- No conversation state maintained between requests
+- Each request is independent and self-contained
+- Complete context must be provided with every request
+- No memory of previous interactions
+- Simpler to scale horizontally
+
+**Implementation Pattern:**
+```python
+# Each request includes full conversation history
+# NOTE: Documentation uses .generate() for clarity, actual code uses .stream_with_tools()
+response = backend.generate(
+    messages=[
+        {"role": "user", "content": "Previous context..."},
+        {"role": "assistant", "content": "Previous response..."},
+        {"role": "user", "content": "Current request..."}
+    ]
+)
+```
+
+### Stateful Backends
+
+**Examples:** `Claude Code CLI`, Interactive CLI sessions
+
+**Characteristics:**
+- Maintains conversation context across interactions
+- State persists between requests
+- Can reference previous interactions without resending context
+- Requires explicit state management (reset, clear, etc.)
+- More complex but efficient for long conversations
+
+**Implementation Pattern:**
+```python
+# Only current request needed, context maintained internally
+# NOTE: Documentation uses .generate() for clarity, actual code uses .stream_with_tools()
+response = backend.generate(message="Current request...")
+```
+
+## Current Agent Implementation Issue
+
+The current agent implementation assumes all backends are **stateless**, which creates inefficiencies and potential issues:
+
+### Problems with Current Approach:
+1. **Redundant Context**: Sends complete conversation history to stateful backends
+2. **Inefficient Resource Usage**: Wastes bandwidth and processing power
+3. **State Confusion**: May conflict with backend's internal state management
+4. **Reset Handling**: Doesn't properly clear stateful backend state on reset
+
+## Recommended Solution
+
+### 1. Backend Detection
+Add capability detection to identify backend type:
+
+```python
+class Backend:
+    @property
+    def is_stateful(self) -> bool:
+        """Returns True if backend maintains conversation state"""
+        return False  # Default to stateless
+```
+
+### 2. Conditional Context Management
+Adjust message sending based on backend type:
+
+```python
+def send_message(self, message: str):
+    if self.backend.is_stateful:
+        # Send only current message
+        # NOTE: Documentation uses .generate() for clarity, actual code uses .stream_with_tools()
+        response = self.backend.generate(message)
+    else:
+        # Send full conversation history
+        # NOTE: Documentation uses .generate() for clarity, actual code uses .stream_with_tools()
+        response = self.backend.generate(self.get_full_context())
+```
+
+### 3. Reset Handling
+Handle resets differently for each backend type:
+
+```python
+# NOTE: Methods shown are conceptual examples, not current implementation
+def reset_conversation(self):
+    if self.backend.is_stateful:
+        # Clear backend's internal state
+        self.backend.reset()
+    else:
+        # Clear local conversation history
+        self.conversation_history.clear()
+```
+
+## Implementation Files
+
+- `base.py` - Base backend interface with `LLMBackend` abstract class
+- `chat_completions.py` - Stateless ChatCompletion backends (OpenAI-compatible)
+- `claude_code.py` - **Stateful** Claude Code backend with streaming support
+- `cli_base.py` - Base CLI backend functionality
+
+## Benefits of Proper Implementation
+
+1. **Performance**: Reduced context transmission for stateful backends
+2. **Reliability**: Proper state management prevents confusion
+3. **Scalability**: Optimized resource usage
+4. **Consistency**: Uniform behavior across backend types
+5. **Maintainability**: Clear separation of concerns
+
+## Next Steps
+
+1. Add `is_stateful` property to backend interface
+2. Update agent logic to detect and handle backend types
+3. Implement proper reset mechanisms for both types
+4. Add tests for both stateful and stateless scenarios
+5. Update documentation for backend developers
+
+TODO: Clean up the design - StreamChunk has grown complex with many optional fields for different reasoning types and provider-specific features

massgen/backend/{CLAUDE_API_RESEARCH.md → docs/CLAUDE_API_RESEARCH.md}

@@ -2,14 +2,14 @@
 
 ## API Status & Availability (2025)
 
-✅ **Production Ready**: Claude API is stable and production-ready  
-✅ **Active Development**: Regular updates with new features in 2025  
-✅ **Strong SDK Support**: Official Python SDK with async/sync support  
+✅ **Production Ready**: Claude API is stable and production-ready
+✅ **Active Development**: Regular updates with new features in 2025
+✅ **Strong SDK Support**: Official Python SDK with async/sync support
 
 ## Models Available (2025)
 
 - **Claude 4 Opus**: Most capable, hybrid with extended thinking mode
-- **Claude 4 Sonnet**: Balanced performance, also available to free users  
+- **Claude 4 Sonnet**: Balanced performance, also available to free users
 - **Claude 3.7 Sonnet**: Previous generation, still supported
 - **Claude 3.5 Haiku**: Fastest, cost-effective option
 
@@ -17,7 +17,7 @@
 
 ### ✅ Excellent Multi-Tool Support
 **Key Advantage**: Claude can combine ALL tool types in a single request:
-- ✅ **Server-side tools** (web search, code execution) 
+- ✅ **Server-side tools** (web search, code execution)
 - ✅ **User-defined functions** (custom tools)
 - ✅ **File processing** via Files API
 - ✅ **No restrictions** on combining different tool types
@@ -114,7 +114,7 @@ response = await beta_client.beta.messages.create(
 
 ## Advanced Features (2025)
 
-### New Beta Features  
+### New Beta Features
 - **Code execution**: Python sandbox with server-side execution
   - Header: `"anthropic-beta": "code-execution-2025-05-22"`
   - Tool type: `code_execution_20250522`
@@ -144,7 +144,7 @@ response = await beta_client.beta.messages.create(
 
 **Production Readiness:**
 - ✅ Stable API with predictable pricing
-- ✅ No session limits or experimental restrictions  
+- ✅ No session limits or experimental restrictions
 - ✅ Strong error handling and rate limits
 
 ## Implementation Recommendation
@@ -165,7 +165,7 @@ response = await beta_client.beta.messages.create(
 
 ### Suggested Implementation Order:
 1. ✅ OpenAI Backend (completed)
-2. ✅ Grok Backend (completed) 
+2. ✅ Grok Backend (completed)
 3. 🎯 **Claude Backend** (recommended next)
 4. ⏳ Gemini Backend (when API supports multi-tools)
 
@@ -175,27 +175,27 @@ response = await beta_client.beta.messages.create(
 class ClaudeBackend(LLMBackend):
     def __init__(self, api_key: Optional[str] = None):
         self.client = anthropic.AsyncAnthropic(api_key=api_key)
-    
+
     async def stream_with_tools(self, messages, tools, **kwargs):
         # Can freely combine all tool types
         combined_tools = []
-        
-        # Add server-side tools  
+
+        # Add server-side tools
         if kwargs.get("enable_web_search"):
             combined_tools.append({"type": "web_search_20250305"})
-        
+
         if kwargs.get("enable_code_execution"):
             combined_tools.append({"type": "code_execution_20250522"})
-        
+
         # Add user-defined tools
         if tools:
             combined_tools.extend(tools)
-        
+
         # Single API call with all tools - USE BETA CLIENT FOR CODE EXECUTION
         headers = {}
         if kwargs.get("enable_code_execution"):
             headers["anthropic-beta"] = "code-execution-2025-05-22"
-            
+
         stream = await self.client.beta.messages.create(
             model="claude-3-5-sonnet-20241022",
             messages=messages,
@@ -203,7 +203,7 @@ class ClaudeBackend(LLMBackend):
             headers=headers,
             stream=True
         )
-        
+
         async for event in stream:
             yield StreamChunk(...)
 ```
@@ -219,13 +219,13 @@ class ClaudeBackend(LLMBackend):
 ### ✅ Tool Execution Pattern
 Claude's code execution is **server-side** - Claude executes the code and streams results back:
 1. Send request with `code_execution_20250522` tool
-2. Claude generates code and executes it server-side  
+2. Claude generates code and executes it server-side
 3. Claude streams back execution results automatically
 4. No client-side tool execution needed for code execution tools
 
 ### ✅ Streaming Event Types to Handle
 - `content_block_start`: Tool use begins
-- `content_block_delta`: Tool input streaming  
+- `content_block_delta`: Tool input streaming
 - `input_json_delta`: Tool arguments as JSON fragments
 - Tool execution results are streamed as additional content blocks
 

massgen/backend/{GEMINI_API_DOCUMENTATION.md → docs/GEMINI_API_DOCUMENTATION.md}

@@ -12,7 +12,7 @@ The Gemini API provides access to Google's latest generative AI models with mult
 ## Models Available
 
 1. **Gemini 2.5 Pro**: Most powerful thinking model with features for complex reasoning
-2. **Gemini 2.5 Flash**: Newest multimodal model with next generation features  
+2. **Gemini 2.5 Flash**: Newest multimodal model with next generation features
 3. **Gemini 2.5 Flash-Lite**: Lighter version
 
 **Note**: Starting April 29, 2025, Gemini 1.5 Pro and Gemini 1.5 Flash models are not available in projects with no prior usage.
@@ -41,7 +41,7 @@ print(response.text)
 ### Synchronous Streaming
 ```python
 for chunk in client.models.generate_content_stream(
-    model='gemini-2.0-flash', 
+    model='gemini-2.0-flash',
     contents='Tell me a story in 300 words.'
 ):
     print(chunk.text)
@@ -51,7 +51,7 @@ for chunk in client.models.generate_content_stream(
 ### Asynchronous Streaming
 ```python
 async for chunk in await client.aio.models.generate_content_stream(
-    model='gemini-2.0-flash', 
+    model='gemini-2.0-flash',
     contents="Write a cute story about cats."
 ):
     if chunk.text:
@@ -87,7 +87,7 @@ async def async_demo():
 - Allows models to interact with external tools and APIs
 - Three primary use cases:
   1. Augment Knowledge
-  2. Extend Capabilities  
+  2. Extend Capabilities
   3. Take Actions
 
 ### Function Call Workflow
@@ -218,7 +218,7 @@ response = client.models.generate_content(
 
 **Response Format:**
 - `text`: Model's explanatory text
-- `executableCode`: Generated Python code  
+- `executableCode`: Generated Python code
 - `codeExecutionResult`: Execution output
 - Access via `response.candidates[0].content.parts`
 
@@ -243,7 +243,7 @@ grounding_tool = types.Tool(google_search=types.GoogleSearch())
 config = types.GenerateContentConfig(tools=[grounding_tool])
 
 response = client.models.generate_content(
-    model="gemini-2.5-flash", 
+    model="gemini-2.5-flash",
     contents="Latest AI developments in 2025",
     config=config
 )
@@ -345,11 +345,11 @@ client.models.generate_content(...)
 - `function_declarations` only (user-defined tools)
 
 **❌ NOT Supported:**
-- `code_execution` + `function_declarations` 
+- `code_execution` + `function_declarations`
 - `grounding` + `function_declarations`
 - All three tool types together
 
-### Live API (Preview/Experimental) 
+### Live API (Preview/Experimental)
 **✅ Multi-Tool Support:**
 - Can combine `google_search` + `code_execution` + `function_declarations`
 - Full flexibility but comes with major limitations
@@ -399,7 +399,7 @@ client.models.generate_content(...)
 **Usage Examples:**
 ```python
 # CLI usage
-python -m massgen.cli --backend gemini --model gemini-2.5-flash "Your question"
+uv run python -m massgen.cli --backend gemini --model gemini-2.5-flash "Your question"
 
 # Configuration
 AgentConfig.create_gemini_config(