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

massgen/backend/docs/OPENAI_GPT5_MODELS.md

@@ -0,0 +1,211 @@
+# OpenAI GPT-5 Models - Backend Implementation Notes
+
+> **Status**: Latest information as of August 2025
+> **Source**: OpenAI Platform Documentation - GPT-5 Guide
+> **Impact**: Major updates required for MassGen backend implementations
+
+## Overview
+
+GPT-5 represents OpenAI's most intelligent model series, with significant architectural changes requiring backend updates for optimal integration.
+
+### Key Capabilities
+- **Code generation, bug fixing, and refactoring** - Enhanced over previous models
+- **Instruction following** - Improved accuracy and adherence
+- **Long context and tool calling** - Up to 1M tokens with better comprehension
+- **Reasoning models** - Internal chain of thought with step-by-step problem solving
+
+## Model Variants
+
+| Model | Best For | Use Case in MassGen |
+|-------|----------|-------------------|
+| **gpt-5** | Complex reasoning, broad world knowledge, code-heavy tasks | Primary model for complex agent workflows |
+| **gpt-5-mini** | Cost-optimized reasoning and chat | Balanced cost/performance for standard tasks |
+| **gpt-5-nano** | High-throughput, simple instruction-following | Classification, simple function calling |
+
+## New API Features (Critical for Backend Updates)
+
+### 1. Minimal Reasoning Effort
+```python
+# New reasoning.effort parameter
+{
+    "model": "gpt-5",
+    "reasoning": {
+        "effort": "minimal"  # Options: minimal, low, medium, high
+    }
+}
+```
+**Backend Impact**: Add reasoning parameter support to response.py and new GPT-5 backend
+
+### 2. Verbosity Control
+```python
+# New text.verbosity parameter
+{
+    "model": "gpt-5",
+    "text": {
+        "verbosity": "low"  # Options: low, medium, high
+    }
+}
+```
+**Backend Impact**: Enables output length control, important for cost optimization
+
+### 3. Custom Tools (Major Enhancement)
+```python
+# Freeform tool inputs - no longer restricted to JSON
+{
+    "type": "custom",
+    "name": "code_exec",
+    "description": "Executes arbitrary python code"
+}
+```
+**Backend Impact**: Requires tool format updates in MassGen tool handling
+
+### 4. Allowed Tools (New Safety Feature)
+```python
+# Restrict model to subset of available tools
+"tool_choice": {
+    "type": "allowed_tools",
+    "mode": "auto",  # or "required"
+    "tools": [
+        {"type": "function", "name": "get_weather"},
+        {"type": "image_generation"}
+    ]
+}
+```
+**Backend Impact**: Enhanced tool safety and predictability
+
+### 5. Preambles (Transparency Feature)
+- Model explains "why" before each tool call
+- Improves tool-calling accuracy
+- Enable via system instruction: "Before you call a tool, explain why you are calling it"
+
+## API Migration Requirements
+
+### Primary Recommendation: Use Responses API
+GPT-5 **works best** with the Responses API due to:
+- **Chain of Thought (CoT) passing** between turns
+- Improved intelligence through reasoning continuity
+- Fewer generated reasoning tokens
+- Higher cache hit rates
+- Lower latency
+
+### Migration Path from Current Models
+| Current Model | Recommended GPT-5 | Reasoning Level |
+|---------------|------------------|----------------|
+| o3 | gpt-5 | medium or high |
+| gpt-4.1 | gpt-5 | minimal or low |
+| o4-mini/gpt-4.1-mini | gpt-5-mini | with prompt tuning |
+| gpt-4.1-nano | gpt-5-nano | with prompt tuning |
+
+## Backend Implementation Requirements
+
+### 1. Response API Backend Updates
+```python
+# New parameters to add to response.py
+api_params = {
+    "model": "gpt-5",
+    "input": messages,  # Note: 'input' not 'messages'
+    "reasoning": {"effort": "medium"},  # NEW
+    "text": {"verbosity": "medium"},    # NEW
+    "tools": tools,
+    "tool_choice": {                   # ENHANCED
+        "type": "allowed_tools",
+        "mode": "auto",
+        "tools": allowed_subset
+    }
+}
+```
+
+### 2. Chain of Thought Handling
+```python
+# Critical: Pass previous reasoning between turns
+{
+    "previous_response_id": "resp_123",  # Automatic CoT passing
+    # OR manually include reasoning items
+    "reasoning": {
+        "items": encrypted_reasoning_tokens
+    }
+}
+```
+
+### 3. Custom Tool Integration
+```python
+# Support freeform tool inputs
+def convert_tools_for_gpt5(tools):
+    for tool in tools:
+        if tool.get("supports_freeform"):
+            tool["type"] = "custom"
+            # Remove JSON schema constraints
+            tool.pop("parameters", None)
+    return tools
+```
+
+## Pricing Considerations
+
+Based on historical patterns, expect:
+- **gpt-5**: ~$15-20 per 1M input tokens, $60-80 per 1M output tokens
+- **gpt-5-mini**: ~$1-2 per 1M input tokens, $5-8 per 1M output tokens
+- **gpt-5-nano**: ~$0.25-0.50 per 1M input tokens, $1-2 per 1M output tokens
+
+**Note**: Reasoning effort affects token usage - minimal uses fewer reasoning tokens.
+
+## MassGen Backend Action Items
+
+### Immediate (High Priority)
+1. **Update response.py** - Add GPT-5 parameter support
+2. **Create gpt5.py backend** - Dedicated implementation for GPT-5 features
+3. **Update agent_config.py** - Add GPT-5 model configurations
+4. **Test tool compatibility** - Ensure custom tools work with MassGen framework
+
+### Medium Priority
+1. **Implement CoT passing** - Between conversation turns
+2. **Add verbosity controls** - Cost optimization feature
+3. **Update pricing calculations** - New model pricing
+4. **Enhanced tool safety** - Allowed tools integration
+
+### Future Enhancements
+1. **Prompt optimization** - Use OpenAI's prompt optimizer for GPT-5
+2. **Reasoning item encryption** - For zero data retention workflows
+3. **Preamble integration** - Tool call transparency features
+
+## Code Generation Optimizations
+
+GPT-5 excels at coding tasks. Recommended prompt patterns:
+```python
+system_prompt = """
+You are a software engineering agent with well-defined responsibilities.
+- Use functions.run for code execution tasks
+- Test changes with unit tests or Python commands
+- Generate clean, semantically correct markdown
+- Format code with proper fences and inline backticks
+Before you call a tool, explain why you are calling it.
+"""
+```
+
+## Frontend Engineering Excellence
+
+For web development tasks, GPT-5 performs best with:
+- **Libraries**: Tailwind CSS, shadcn/ui, Radix Themes
+- **Icons**: Lucide, Material Symbols, Heroicons
+- **Animation**: Motion
+- **Zero-to-one capability**: Can generate full web apps from single prompt
+
+## Integration Timeline
+
+**Phase 1 (Immediate)**: Basic GPT-5 support via updated response.py
+**Phase 2 (Week 2)**: Dedicated GPT-5 backend with all new features
+**Phase 3 (Month 1)**: Full CoT integration and optimization
+**Phase 4 (Month 2)**: Advanced features (custom tools, allowed tools)
+
+## Testing Strategy
+
+1. **Model Performance**: Compare against existing GPT-4o implementations
+2. **Tool Compatibility**: Verify all MassGen tools work with custom tool format
+3. **Cost Analysis**: Monitor reasoning token usage vs. performance gains
+4. **Agent Workflows**: Test multi-turn conversations with CoT passing
+
+---
+
+**Next Steps**:
+1. Update response.py to support basic GPT-5 parameters
+2. Create comprehensive test suite for GPT-5 features
+3. Implement gradual rollout strategy for existing MassGen users

massgen/backend/{OPENAI_RESPONSES_API_FORMAT.md → docs/OPENAI_RESPONSE_API_TOOL_CALLS.md}

@@ -7,7 +7,7 @@
 {
     "type": "function_call",
     "id": "fc_12345xyz",
-    "call_id": "call_12345xyz", 
+    "call_id": "call_12345xyz",
     "name": "get_weather",
     "arguments": "{\"location\":\"Paris, France\"}"
 }
@@ -27,7 +27,7 @@
 When handling tool calls across multiple turns:
 
 1. **Model makes tool call** - Returns function_call object with call_id
-2. **Execute function** - Run your code with the arguments  
+2. **Execute function** - Run your code with the arguments
 3. **Add BOTH messages to input array**:
    ```python
    input_messages.append(tool_call)  # append model's function call message
@@ -52,7 +52,7 @@ For error messages to tools, follow the same pattern:
 ```python
 # Agent made invalid tool call with call_id "call_123"
 error_message = {
-    "type": "function_call_output", 
+    "type": "function_call_output",
     "call_id": "call_123",
     "output": "Error: You can only vote once per response. Please vote for just ONE agent."
 }