src

Imported from davidcantidio/test-tdd-project (src/AGENTS.md). Install upstream with npx skills add davidcantidio/test-tdd-project --skill src. Copyright stays with the author.

🤖 CLAUDE.md - AI Services Module

Module: src/ia/
Purpose: Core AI services for Product Vision + Epic Generation
Status: ✅ PRODUCTION READY - Phase 5.1 Complete
Architecture: Clean separation between agents, services, and refiners + Epic Generation
Last Updated: 2025-09-04 - IA-Driven Epic Generation Integration

📋 Module Overview

The src/ia/ module provides comprehensive AI services for both Product Vision refinement and automated Epic Generation. It implements a clean architecture with proper separation of concerns between AI agents, services, and refiners, now enhanced with epic generation capabilities from product vision analysis.

🏗️ Directory Structure

src/
└── ia/                          # AI/Intelligence services
    ├── agents/
    │   ├── agno_agent.py        # Agno framework integration with GPT-5-nano
    │   └── epic_generation_agent.py  # NEW: AI agent for epic generation [Phase 5.1]
    ├── services/
    │   ├── vision_refine_service.py  # Service layer for vision refinement
    │   └── epic_generation_service.py # NEW: Epic generation service [Phase 5.1]
    ├── models/
    │   ├── product_vision_dto.py   # Product Vision data models
    │   └── epic_generation_dto.py   # NEW: Epic generation data models [Phase 5.1]
    └── product_vision_refiner.py     # Refiner implementations (Real & Mock)

🎯 Core Components

1. VisionRefinerAgent (agents/agno_agent.py)

The core AI agent using the Agno framework with OpenAI GPT-5-nano.

Key Features:

• Structured output using Pydantic ProductVisionDTO
• Validation of required fields before refinement
• JSON mode for consistent responses
• Professional Product Manager prompt engineering

Usage:

from src.ia.agents.agno_agent import VisionRefinerAgent, ProductVisionDTO

agent = VisionRefinerAgent(model_id="gpt-5-nano")
refined = agent.refine({
    "vision_statement": "app delivery",
    "problem_statement": "fome rápida",
    "target_audience": "pessoas com pressa",
    "value_proposition": "entrega em 10 minutos",
    "constraints": ["budget limitado"]
})

2. VisionRefineService (services/vision_refine_service.py)

Service layer that wraps the agent with business logic and error handling.

Key Features:

• Enterprise-ready error handling
• Adapter pattern for flexible agent swapping
• Validation and sanitization
• Logging and monitoring hooks

3. Product Vision Refiners (product_vision_refiner.py)

High-level refiner implementations for different environments.

Implementations:

• RealGPTRefiner: Production refiner using actual GPT-5-nano
• FakeClaudeRefiner: Mock refiner for testing/development

4. Epic Generation Agent (agents/epic_generation_agent.py) [NEW - Phase 5.1]

Advanced AI agent specialized in generating project epics from product vision analysis.

Key Features:

• Deep product vision analysis with context understanding
• Structured epic generation with dependency detection
• Complexity scoring and effort estimation
• JSON output with validation via EpicGenerationResponseDTO
• Professional Project Manager + Technical Lead prompt engineering

Usage:

from src.ia.agents.epic_generation_agent import EpicGenerationAgent

agent = EpicGenerationAgent(model_id="gpt-4")
epics = agent.generate_epics_from_vision({
    "vision_statement": "food delivery platform",
    "problem_statement": "slow food delivery times",
    "target_audience": "busy professionals",
    "value_proposition": "10-minute guaranteed delivery",
    "constraints": ["limited budget", "small team"]
})

5. Epic Generation Service (services/epic_generation_service.py) [NEW - Phase 5.1]

Enterprise service layer for epic generation with business logic integration.

Key Features:

• Product vision analysis and validation
• AI-driven epic generation with confidence scoring
• Dependency validation and cycle detection
• Integration with TopologicalOrderingService
• Error handling and fallback strategies

📊 Data Models

ProductVisionDTO (Product Vision Refinement)

class ProductVisionDTO(BaseModel):
    vision_statement: str   # Clear product vision
    problem_statement: str  # Problem being solved
    target_audience: str    # Primary target users
    value_proposition: str  # Unique value offered
    constraints: List[str]  # Limitations/restrictions

Epic Generation DTOs [NEW - Phase 5.1]

class GeneratedEpicDTO(BaseModel):
    """Single epic generated by AI"""
    name: str                    # Epic name (concise, descriptive)
    description: str             # Detailed epic scope and deliverables
    complexity_score: float      # 1.0-5.0 difficulty rating
    effort_estimate: int         # Estimated effort in days
    epic_dependencies: List[str] # List of prerequisite epic keys
    unblock_potential: int       # Number of epics this epic enables
    ai_confidence: float         # AI confidence score (0.0-1.0)

class EpicGenerationResponseDTO(BaseModel):
    """Complete AI response for epic generation"""
    success: bool
    generated_epics: List[GeneratedEpicDTO]
    analysis_summary: str        # AI's analysis of the product vision
    total_project_complexity: float  # Overall project complexity (1.0-5.0)
    recommended_team_size: int   # Suggested team size
    estimated_timeline_weeks: int    # Total project timeline estimate
    confidence_metrics: Dict[str, float]  # Confidence breakdown by category
    
    # Validation and error handling
    validation_errors: List[str] = []
    generation_warnings: List[str] = []

class EpicDependencyValidationDTO(BaseModel):
    """Dependency validation results"""
    is_valid: bool
    dependency_graph: Dict[str, List[str]]
    cycles_detected: List[List[str]] = []
    orphaned_epics: List[str] = []
    complexity_metrics: Dict[str, float]

🧠 Epic Generation Prompt Engineering & Parsing [NEW - Phase 5.1]

Structured Prompt Templates

The epic generation system uses sophisticated prompt engineering to ensure consistent, high-quality AI responses.

Core Epic Generation Prompt

EPIC_GENERATION_PROMPT_TEMPLATE = """
Você é um experiente Product Manager e Arquiteto de Software trabalhando na análise de product visions para gerar épicos otimizados.

**CONTEXTO DO PRODUTO:**
Visão: {vision_statement}
Problema: {problem_statement}  
Público-alvo: {target_audience}
Proposta de valor: {value_proposition}
Restrições: {constraints}

**TAREFA:**
Gere entre 3-7 épicos que representem as principais divisões técnicas e funcionais deste projeto.

**CRITÉRIOS PARA CADA ÉPICO:**
1. **Nome**: Conciso, descritivo, orientado a resultado (ex: "Backend Infrastructure", "User Authentication", "Payment Processing")
2. **Descrição**: Escopo detalhado, deliverables específicos, critérios de sucesso claros
3. **Complexidade**: Escala 1.0-5.0 (1.0=simples config, 5.0=arquitetura complexa)
4. **Esforço**: Estimativa realista em dias (1-30 dias)
5. **Dependências**: Liste epic_keys que devem ser concluídos ANTES deste épico
6. **Potencial de Desbloqueio**: Quantos épicos futuros este épico habilita

**DIRETRIZES DE QUALIDADE:**
- Priorize épicos que desbloqueiam outros (alto unblock_potential)
- Balance complexidade técnica com valor de negócio
- Considere as restrições especificadas
- Mantenha dependências realistas (evite ciclos)
- Pense como arquiteto: infraestrutura antes de features

**FORMATO DE SAÍDA:** JSON estruturado exatamente como este exemplo:
{{
    "success": true,
    "analysis_summary": "Análise detalhada da visão do produto...",
    "total_project_complexity": 3.2,
    "recommended_team_size": 4,
    "estimated_timeline_weeks": 12,
    "generated_epics": [
        {{
            "name": "Backend Infrastructure",
            "description": "Configurar infraestrutura base: APIs, banco de dados, autenticação, deploy pipeline",
            "complexity_score": 3.5,
            "effort_estimate": 10,
            "epic_dependencies": [],
            "unblock_potential": 4,
            "ai_confidence": 0.9
        }},
        {{
            "name": "User Management System", 
            "description": "Sistema completo de usuários: registro, login, perfis, permissões",
            "complexity_score": 2.8,
            "effort_estimate": 7,
            "epic_dependencies": ["Backend Infrastructure"],
            "unblock_potential": 2,
            "ai_confidence": 0.85
        }}
    ],
    "confidence_metrics": {{
        "technical_analysis": 0.9,
        "business_alignment": 0.8,
        "dependency_accuracy": 0.85,
        "effort_estimation": 0.75
    }}
}}
"""

Specialized Prompts by Domain

# Domain-specific prompt variations
CONSTRUCTION_PROMPT_SUFFIX = """
**CONTEXTO ESPECÍFICO - CONSTRUÇÃO:**
- Considere fases físicas: fundação → estrutura → acabamentos
- Priorize épicos que liberam trabalho paralelo
- Considere fatores climáticos e recursos materiais
"""

SOFTWARE_PROMPT_SUFFIX = """  
**CONTEXTO ESPECÍFICO - SOFTWARE:**
- Considere arquitetura: infra → backend → frontend → integração
- Priorize épicos que permitem desenvolvimento paralelo
- Considere CI/CD, testes, e deployment desde o início
"""

CONTENT_PROMPT_SUFFIX = """
**CONTEXTO ESPECÍFICO - CONTEÚDO:**
- Considere pipeline: pesquisa → criação → edição → publicação  
- Priorize épicos que estabelecem processos e ferramentas
- Considere distribuição e métricas desde o planejamento
"""

AI Response Parsing & Validation

Robust JSON Parsing

class EpicGenerationResponseParser:
    def parse_ai_response(self, raw_response: str) -> EpicGenerationResponseDTO:
        """Parse and validate AI response with robust error handling"""
        try:
            # Clean response (remove markdown, extra text)
            cleaned_json = self._extract_json_from_response(raw_response)
            
            # Parse JSON
            response_data = json.loads(cleaned_json)
            
            # Validate structure
            validated_response = self._validate_response_structure(response_data)
            
            # Create DTO with validation
            return EpicGenerationResponseDTO(**validated_response)
            
        except json.JSONDecodeError as e:
            return self._create_error_response(f"JSON parsing failed: {e}")
        except ValidationError as e:
            return self._create_error_response(f"Response validation failed: {e}")
        except Exception as e:
            return self._create_error_response(f"Unexpected parsing error: {e}")
    
    def _extract_json_from_response(self, response: str) -> str:
        """Extract JSON from potentially messy AI response"""
        # Remove markdown code blocks
        response = re.sub(r'```json\s*', '', response)
        response = re.sub(r'```\s*$', '', response)
        
        # Find JSON object boundaries
        json_start = response.find('{')
        json_end = response.rfind('}') + 1
        
        if json_start == -1 or json_end == 0:
            raise ValueError("No JSON object found in response")
            
        return response[json_start:json_end]
    
    def _validate_response_structure(self, data: dict) -> dict:
        """Validate and sanitize response data"""
        # Ensure required fields exist
        required_fields = ['success', 'generated_epics', 'analysis_summary']
        for field in required_fields:
            if field not in data:
                raise ValueError(f"Missing required field: {field}")
        
        # Validate epics structure
        if not isinstance(data['generated_epics'], list):
            raise ValueError("generated_epics must be a list")
            
        # Sanitize individual epics
        sanitized_epics = []
        for epic in data['generated_epics']:
            sanitized_epic = self._sanitize_epic_data(epic)
            sanitized_epics.append(sanitized_epic)
            
        data['generated_epics'] = sanitized_epics
        return data
    
    def _sanitize_epic_data(self, epic: dict) -> dict:
        """Sanitize individual epic data"""
        # Ensure required epic fields
        epic.setdefault('name', 'Unnamed Epic')
        epic.setdefault('description', 'No description provided')
        epic.setdefault('complexity_score', 3.0)
        epic.setdefault('effort_estimate', 7)
        epic.setdefault('epic_dependencies', [])
        epic.setdefault('unblock_potential', 1)
        epic.setdefault('ai_confidence', 0.7)
        
        # Validate ranges
        epic['complexity_score'] = max(1.0, min(5.0, float(epic['complexity_score'])))
        epic['effort_estimate'] = max(1, min(30, int(epic['effort_estimate'])))
        epic['ai_confidence'] = max(0.0, min(1.0, float(epic['ai_confidence'])))
        epic['unblock_potential'] = max(0, int(epic['unblock_potential']))
        
        # Ensure dependencies is a list
        if not isinstance(epic['epic_dependencies'], list):
            epic['epic_dependencies'] = []
            
        return epic

Confidence Scoring & Quality Metrics

class EpicGenerationQualityAnalyzer:
    def analyze_generation_quality(self, response: EpicGenerationResponseDTO) -> dict:
        """Comprehensive quality analysis of generated epics"""
        
        # Dependency analysis
        dependency_metrics = self._analyze_dependencies(response.generated_epics)
        
        # Complexity distribution
        complexity_metrics = self._analyze_complexity_distribution(response.generated_epics)
        
        # Confidence analysis  
        confidence_metrics = self._analyze_confidence_distribution(response.generated_epics)
        
        # Business logic validation
        business_metrics = self._validate_business_logic(response.generated_epics)
        
        return {
            'overall_quality_score': self._calculate_overall_quality(
                dependency_metrics, complexity_metrics, confidence_metrics, business_metrics
            ),
            'dependency_health': dependency_metrics,
            'complexity_balance': complexity_metrics,
            'confidence_distribution': confidence_metrics,
            'business_alignment': business_metrics,
            'recommendations': self._generate_quality_recommendations(response)
        }

🔧 Configuration

Environment Variables

# Required for production
export OPENAI_API_KEY="your-api-key"

# Optional model selection
export AI_MODEL_ID="gpt-5-nano"  # or "gpt-4", "gpt-3.5-turbo"

Model Options

• gpt-5-nano (default): Fast, cost-effective for refinement
• gpt-4: Higher quality, slower response
• gpt-3.5-turbo: Budget option, good performance

🧪 Testing

Unit Tests

# Test AI agents
pytest tests/ia/test_agno_agent.py

# Test refiners
pytest tests/product_vision/test_product_vision_refiner.py

Mock vs Real

# Development - use mock
from src.ia.product_vision_refiner import FakeClaudeRefiner
refiner = FakeClaudeRefiner()

# Production - use real
from src.ia.product_vision_refiner import RealGPTRefiner
refiner = RealGPTRefiner()

🔗 Integration Points

Used By:

• /streamlit_extension/pages/projetos/steps/product_vision_step/product_vision.py - Main UI integration
• /streamlit_extension/services/vision_service.py - Service layer wrapper

Dependencies:

• agno: AI agent framework
• pydantic: Data validation and schemas
• openai: LLM provider (via agno)

🚀 Future Enhancements

Planned:

• Multi-language support (PT-BR, EN, ES)
• Field-specific refinement strategies
• Caching layer for repeated refinements
• A/B testing framework for prompts
• Cost optimization with intelligent model selection

Under Consideration:

• Custom fine-tuned models for domain-specific refinement
• Batch processing for multiple visions
• Version control for refinement prompts
• Analytics dashboard for refinement quality

📚 Related Documentation

System Documentation

• Main System - Overall system architecture and overview
• Streamlit Extension - Complete UI framework documentation

Integration Documentation

• Project Wizard - Generic project framework implementation
• Product Vision Step - Detailed AI refinement UI integration

Testing & Quality

• Test Framework - Test organization and coverage
• AI Tests - Specific AI refinement tests

Core AI services for intelligent Product Vision refinement. Clean architecture with proper separation between agents, services, and implementations.