Phase 2.1: Core Agent Infrastructure Complete - PlannerAgent with strategic planning, Pydantic models, BaseAgent class, comprehensive tests (11/11 passing, 90% coverage)

pyproject.toml

@@ -139,4 +139,11 @@ select = [
 ignore = [
     "E501",  # line too long, handled by black
     "B008",  # do not perform function calls in argument defaults
-]
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5",
+    "pytest-asyncio>=0.26.0",
+    "pytest-cov>=6.1.1",
+]

src/__init__.py

@@ -1,10 +1,8 @@
 """
 BeatDebate - Multi-Agent Music Recommendation System
 
-A sophisticated music recommendation system using 4 specialized AI agents
-that demonstrate advanced agentic planning behavior for music discovery.
-
-Built for the AgentX competition.
+A sophisticated music recommendation system using strategic planning
+and multi-agent coordination for the AgentX competition.
 """
 
 __version__ = "0.1.0"

src/agents/__init__.py

@@ -0,0 +1,13 @@
+"""
+Agents Package for BeatDebate Multi-Agent System
+
+Contains all agent implementations for the music recommendation workflow.
+"""
+
+from .base_agent import BaseAgent
+from .planner_agent import PlannerAgent
+
+__all__ = [
+    "BaseAgent",
+    "PlannerAgent",
+]

src/agents/base_agent.py

@@ -0,0 +1,364 @@
+"""
+Base Agent Class for BeatDebate Multi-Agent Music Recommendation System
+
+Provides common functionality for all agents including LLM integration,
+logging, error handling, and reasoning chain management.
+"""
+
+import asyncio
+import time
+from abc import ABC, abstractmethod
+from typing import Dict, List, Any, Optional
+import structlog
+from datetime import datetime
+
+from ..models.agent_models import (
+    MusicRecommenderState,
+    AgentDeliberation,
+    ReasoningChain,
+    AgentConfig
+)
+
+logger = structlog.get_logger(__name__)
+
+
+class BaseAgent(ABC):
+    """
+    Base class for all agents in the BeatDebate system.
+    
+    Provides common functionality:
+    - LLM integration with Gemini
+    - Reasoning chain management
+    - Error handling and logging
+    - Strategy processing utilities
+    - Performance monitoring
+    """
+    
+    def __init__(self, config: AgentConfig):
+        """
+        Initialize base agent with configuration.
+        
+        Args:
+            config: Agent configuration including LLM settings
+        """
+        self.config = config
+        self.agent_name = config.agent_name
+        self.agent_type = config.agent_type
+        self.logger = logger.bind(agent=self.agent_name)
+        
+        # Initialize LLM client (will be set up in subclasses)
+        self.llm_client = None
+        
+        # Performance tracking
+        self.processing_times: List[float] = []
+        self.success_count = 0
+        self.error_count = 0
+        
+        self.logger.info(
+            "Agent initialized",
+            agent_type=self.agent_type,
+            llm_model=config.llm_model,
+            temperature=config.temperature
+        )
+    
+    @abstractmethod
+    async def process(self, state: MusicRecommenderState) -> MusicRecommenderState:
+        """
+        Main processing method that each agent must implement.
+        
+        Args:
+            state: Current state of the music recommendation workflow
+            
+        Returns:
+            Updated state after agent processing
+        """
+        pass
+    
+    async def execute_with_monitoring(self, state: MusicRecommenderState) -> MusicRecommenderState:
+        """
+        Execute agent processing with performance monitoring and error handling.
+        
+        Args:
+            state: Current workflow state
+            
+        Returns:
+            Updated state after processing
+        """
+        start_time = time.time()
+        
+        try:
+            self.logger.info("Starting agent processing", user_query=state.user_query)
+            
+            # Execute main processing
+            updated_state = await self._execute_with_timeout(state)
+            
+            # Record successful execution
+            processing_time = time.time() - start_time
+            self.processing_times.append(processing_time)
+            self.success_count += 1
+            
+            # Add deliberation record
+            deliberation = AgentDeliberation(
+                agent_name=self.agent_name,
+                timestamp=datetime.now(),
+                input_data={"user_query": state.user_query},
+                reasoning_steps=self._extract_reasoning_steps(updated_state),
+                output_data=self._extract_output_data(updated_state),
+                confidence=self._calculate_confidence(updated_state),
+                processing_time=processing_time
+            )
+            
+            updated_state.agent_deliberations.append(deliberation.dict())
+            
+            self.logger.info(
+                "Agent processing completed successfully",
+                processing_time=processing_time,
+                confidence=deliberation.confidence
+            )
+            
+            return updated_state
+            
+        except asyncio.TimeoutError:
+            self.error_count += 1
+            self.logger.error(
+                "Agent processing timed out",
+                timeout_seconds=self.config.timeout_seconds
+            )
+            # Return state with error information
+            return self._handle_timeout_error(state)
+            
+        except Exception as e:
+            self.error_count += 1
+            self.logger.error(
+                "Agent processing failed",
+                error=str(e),
+                error_type=type(e).__name__
+            )
+            # Return state with error information
+            return self._handle_processing_error(state, e)
+    
+    async def _execute_with_timeout(self, state: MusicRecommenderState) -> MusicRecommenderState:
+        """Execute processing with timeout."""
+        return await asyncio.wait_for(
+            self.process(state),
+            timeout=self.config.timeout_seconds
+        )
+    
+    def _extract_reasoning_steps(self, state: MusicRecommenderState) -> List[str]:
+        """Extract reasoning steps from the updated state."""
+        # Get the most recent reasoning log entries added by this agent
+        if hasattr(self, '_reasoning_steps'):
+            return self._reasoning_steps
+        return ["Processing completed"]
+    
+    def _extract_output_data(self, state: MusicRecommenderState) -> Dict[str, Any]:
+        """Extract output data specific to this agent."""
+        return {"status": "completed"}
+    
+    def _calculate_confidence(self, state: MusicRecommenderState) -> float:
+        """Calculate confidence score for this agent's processing."""
+        # Default implementation - subclasses should override
+        return 0.8
+    
+    def _handle_timeout_error(self, state: MusicRecommenderState) -> MusicRecommenderState:
+        """Handle timeout error by adding error information to state."""
+        error_msg = f"{self.agent_name} processing timed out after {self.config.timeout_seconds}s"
+        state.reasoning_log.append(f"ERROR: {error_msg}")
+        return state
+    
+    def _handle_processing_error(self, state: MusicRecommenderState, error: Exception) -> MusicRecommenderState:
+        """Handle processing error by adding error information to state."""
+        error_msg = f"{self.agent_name} processing failed: {str(error)}"
+        state.reasoning_log.append(f"ERROR: {error_msg}")
+        return state
+    
+    def add_reasoning_step(self, step: str, evidence: List[str] = None, confidence: float = 0.8):
+        """
+        Add a reasoning step for transparency.
+        
+        Args:
+            step: Description of the reasoning step
+            evidence: Supporting evidence for this step
+            confidence: Confidence in this reasoning step
+        """
+        if not hasattr(self, '_reasoning_steps'):
+            self._reasoning_steps = []
+        
+        self._reasoning_steps.append(step)
+        
+        if evidence:
+            self._reasoning_steps.append(f"Evidence: {', '.join(evidence)}")
+        
+        self.logger.debug(
+            "Reasoning step added",
+            step=step,
+            confidence=confidence
+        )
+    
+    def log_strategy_application(self, strategy: Dict[str, Any], step: str):
+        """
+        Log how strategy is being applied.
+        
+        Args:
+            strategy: Strategy object being applied
+            step: Description of strategy application step
+        """
+        self.logger.info(
+            "Applying strategy",
+            step=step,
+            strategy_keys=list(strategy.keys()) if strategy else []
+        )
+    
+    async def call_llm(self, prompt: str, system_prompt: str = None) -> str:
+        """
+        Call LLM with proper error handling and logging.
+        
+        Args:
+            prompt: User prompt for the LLM
+            system_prompt: System prompt (optional)
+            
+        Returns:
+            LLM response text
+        """
+        if not self.llm_client:
+            raise RuntimeError(f"LLM client not initialized for {self.agent_name}")
+        
+        try:
+            self.logger.debug(
+                "Calling LLM",
+                prompt_length=len(prompt),
+                model=self.config.llm_model
+            )
+            
+            # This will be implemented by subclasses with actual LLM integration
+            response = await self._make_llm_call(prompt, system_prompt)
+            
+            self.logger.debug(
+                "LLM response received",
+                response_length=len(response)
+            )
+            
+            return response
+            
+        except Exception as e:
+            self.logger.error(
+                "LLM call failed",
+                error=str(e),
+                prompt_length=len(prompt)
+            )
+            raise
+    
+    async def _make_llm_call(self, prompt: str, system_prompt: str = None) -> str:
+        """
+        Make actual LLM call - to be implemented by subclasses.
+        
+        Args:
+            prompt: User prompt
+            system_prompt: System prompt
+            
+        Returns:
+            LLM response
+        """
+        raise NotImplementedError("Subclasses must implement _make_llm_call")
+    
+    def get_performance_metrics(self) -> Dict[str, Any]:
+        """
+        Get performance metrics for this agent.
+        
+        Returns:
+            Dictionary of performance metrics
+        """
+        avg_processing_time = (
+            sum(self.processing_times) / len(self.processing_times)
+            if self.processing_times else 0
+        )
+        
+        total_requests = self.success_count + self.error_count
+        success_rate = self.success_count / total_requests if total_requests > 0 else 0
+        
+        return {
+            "agent_name": self.agent_name,
+            "total_requests": total_requests,
+            "success_count": self.success_count,
+            "error_count": self.error_count,
+            "success_rate": success_rate,
+            "avg_processing_time": avg_processing_time,
+            "processing_times": self.processing_times[-10:]  # Last 10 times
+        }
+    
+    def validate_strategy(self, strategy: Dict[str, Any], required_keys: List[str]) -> bool:
+        """
+        Validate that strategy contains required keys.
+        
+        Args:
+            strategy: Strategy object to validate
+            required_keys: List of required keys
+            
+        Returns:
+            True if strategy is valid, False otherwise
+        """
+        if not strategy:
+            self.logger.warning("Strategy is None or empty")
+            return False
+        
+        missing_keys = [key for key in required_keys if key not in strategy]
+        if missing_keys:
+            self.logger.warning(
+                "Strategy missing required keys",
+                missing_keys=missing_keys,
+                available_keys=list(strategy.keys())
+            )
+            return False
+        
+        return True
+    
+    def extract_strategy_for_agent(self, full_strategy: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Extract strategy specific to this agent from full strategy.
+        
+        Args:
+            full_strategy: Complete strategy from PlannerAgent
+            
+        Returns:
+            Strategy specific to this agent
+        """
+        if not full_strategy:
+            return {}
+        
+        coordination_strategy = full_strategy.get("coordination_strategy", {})
+        
+        # Map agent names to strategy keys
+        agent_strategy_map = {
+            "GenreMoodAgent": "genre_mood_agent",
+            "DiscoveryAgent": "discovery_agent",
+            "JudgeAgent": "evaluation_framework"
+        }
+        
+        strategy_key = agent_strategy_map.get(self.agent_name)
+        if strategy_key and strategy_key in coordination_strategy:
+            return coordination_strategy[strategy_key]
+        
+        # Return evaluation framework for JudgeAgent
+        if self.agent_name == "JudgeAgent":
+            return full_strategy.get("evaluation_framework", {})
+        
+        return {}
+    
+    def format_reasoning_chain(self, steps: List[str]) -> str:
+        """
+        Format reasoning steps into a coherent chain.
+        
+        Args:
+            steps: List of reasoning steps
+            
+        Returns:
+            Formatted reasoning chain
+        """
+        if not steps:
+            return "No reasoning steps recorded."
+        
+        formatted_steps = []
+        for i, step in enumerate(steps, 1):
+            formatted_steps.append(f"{i}. {step}")
+        
+        return "\n".join(formatted_steps) 

src/agents/planner_agent.py

@@ -0,0 +1,583 @@
+"""
+PlannerAgent for BeatDebate Multi-Agent Music Recommendation System
+
+Strategic coordinator and planning engine that demonstrates sophisticated
+agentic planning behavior for the AgentX competition.
+"""
+
+import json
+import re
+from typing import Dict, List, Any, Optional
+import structlog
+
+from .base_agent import BaseAgent
+from ..models.agent_models import MusicRecommenderState, AgentConfig
+
+logger = structlog.get_logger(__name__)
+
+
+class PlannerAgent(BaseAgent):
+    """
+    Master planning agent that coordinates the entire music recommendation workflow.
+    
+    Demonstrates agentic planning behavior required for AgentX competition:
+    - Strategic task decomposition
+    - Resource allocation and coordination
+    - Success criteria definition
+    - Adaptive execution monitoring
+    """
+    
+    def __init__(self, config: AgentConfig, gemini_client=None):
+        """
+        Initialize PlannerAgent with Gemini LLM client.
+        
+        Args:
+            config: Agent configuration
+            gemini_client: Gemini LLM client for reasoning
+        """
+        super().__init__(config)
+        self.llm_client = gemini_client
+        
+        # Planning templates and patterns
+        self.query_patterns = self._initialize_query_patterns()
+        self.strategy_templates = self._initialize_strategy_templates()
+        
+        self.logger.info("PlannerAgent initialized with strategic planning capabilities")
+    
+    async def process(self, state: MusicRecommenderState) -> MusicRecommenderState:
+        """
+        Create comprehensive music discovery strategy.
+        
+        Args:
+            state: Current workflow state with user query
+            
+        Returns:
+            Updated state with planning strategy
+        """
+        self.add_reasoning_step("Starting strategic planning for music discovery")
+        
+        try:
+            # Step 1: Analyze user query complexity and intent
+            task_analysis = await self._analyze_user_query(state.user_query)
+            self.add_reasoning_step(f"Query analysis completed: {task_analysis['primary_goal']}")
+            
+            # Step 2: Create coordination strategy for advocate agents
+            coordination_strategy = await self._plan_agent_coordination(state.user_query, task_analysis)
+            self.add_reasoning_step("Agent coordination strategy developed")
+            
+            # Step 3: Define evaluation framework for judge
+            evaluation_framework = await self._create_evaluation_framework(state.user_query, task_analysis)
+            self.add_reasoning_step("Evaluation framework established")
+            
+            # Step 4: Set up execution monitoring
+            execution_monitoring = await self._setup_execution_monitoring(task_analysis)
+            self.add_reasoning_step("Execution monitoring protocols defined")
+            
+            # Combine into comprehensive strategy
+            planning_strategy = {
+                "task_analysis": task_analysis,
+                "coordination_strategy": coordination_strategy,
+                "evaluation_framework": evaluation_framework,
+                "execution_monitoring": execution_monitoring
+            }
+            
+            # Update state with strategy
+            state.planning_strategy = planning_strategy
+            state.reasoning_log.append(f"PlannerAgent: Created comprehensive strategy for '{task_analysis['primary_goal']}'")
+            
+            self.logger.info(
+                "Strategic planning completed",
+                primary_goal=task_analysis['primary_goal'],
+                complexity=task_analysis['complexity_level'],
+                strategy_components=len(planning_strategy)
+            )
+            
+            return state
+            
+        except Exception as e:
+            self.logger.error("Strategic planning failed", error=str(e))
+            state.reasoning_log.append(f"PlannerAgent ERROR: {str(e)}")
+            return state
+    
+    async def _analyze_user_query(self, user_query: str) -> Dict[str, Any]:
+        """
+        Analyze user query for complexity, intent, and context factors.
+        
+        Args:
+            user_query: User's music request
+            
+        Returns:
+            Task analysis dictionary
+        """
+        system_prompt = """You are a strategic music recommendation planner. Analyze the user's query to understand their intent, mood, and context.
+
+Extract:
+1. Primary goal (what they want to achieve with music)
+2. Complexity level (simple/medium/complex)
+3. Context factors (activity, mood, setting)
+4. Mood indicators (energy level, emotional state)
+5. Genre hints (explicit or implicit preferences)
+
+Respond in JSON format."""
+
+        user_prompt = f"""Analyze this music request:
+"{user_query}"
+
+Provide analysis in this JSON format:
+{{
+    "primary_goal": "brief description of main intent",
+    "complexity_level": "simple|medium|complex",
+    "context_factors": ["factor1", "factor2"],
+    "mood_indicators": ["mood1", "mood2"],
+    "genre_hints": ["genre1", "genre2"]
+}}"""
+
+        try:
+            response = await self.call_llm(user_prompt, system_prompt)
+            analysis = self._parse_json_response(response)
+            
+            # Validate and enhance analysis
+            analysis = self._enhance_task_analysis(analysis, user_query)
+            
+            return analysis
+            
+        except Exception as e:
+            self.logger.warning("LLM analysis failed, using pattern matching", error=str(e))
+            return self._fallback_query_analysis(user_query)
+    
+    async def _plan_agent_coordination(self, user_query: str, task_analysis: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Plan coordination strategy for GenreMoodAgent and DiscoveryAgent.
+        
+        Args:
+            user_query: Original user query
+            task_analysis: Analysis of the query
+            
+        Returns:
+            Coordination strategy for advocate agents
+        """
+        system_prompt = """You are planning coordination between two music recommendation agents:
+1. GenreMoodAgent: Specializes in genre and mood-based search
+2. DiscoveryAgent: Specializes in similarity and underground discovery
+
+Create specific strategies for each agent based on the user's request and analysis."""
+
+        user_prompt = f"""User Query: "{user_query}"
+Task Analysis: {json.dumps(task_analysis, indent=2)}
+
+Create coordination strategy in this JSON format:
+{{
+    "genre_mood_agent": {{
+        "focus_areas": ["area1", "area2"],
+        "energy_level": "low|medium|high",
+        "search_tags": ["tag1", "tag2"],
+        "mood_priority": "primary mood to target",
+        "genre_constraints": ["constraint1", "constraint2"]
+    }},
+    "discovery_agent": {{
+        "novelty_priority": "low|medium|high",
+        "similarity_base": "what to base similarity on",
+        "underground_bias": 0.0-1.0,
+        "discovery_scope": "narrow|medium|broad",
+        "exploration_strategy": "strategy description"
+    }}
+}}"""
+
+        try:
+            response = await self.call_llm(user_prompt, system_prompt)
+            coordination = self._parse_json_response(response)
+            
+            # Validate and enhance coordination strategy
+            coordination = self._enhance_coordination_strategy(coordination, task_analysis)
+            
+            return coordination
+            
+        except Exception as e:
+            self.logger.warning("LLM coordination planning failed, using templates", error=str(e))
+            return self._fallback_coordination_strategy(task_analysis)
+    
+    async def _create_evaluation_framework(self, user_query: str, task_analysis: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Create evaluation framework for JudgeAgent decision making.
+        
+        Args:
+            user_query: Original user query
+            task_analysis: Analysis of the query
+            
+        Returns:
+            Evaluation framework for judge
+        """
+        system_prompt = """You are creating an evaluation framework for a judge agent to select the best music recommendations.
+
+The framework should define:
+1. Primary weights for different criteria
+2. Diversity targets
+3. Explanation style preferences
+
+Consider the user's specific request and context."""
+
+        user_prompt = f"""User Query: "{user_query}"
+Task Analysis: {json.dumps(task_analysis, indent=2)}
+
+Create evaluation framework in this JSON format:
+{{
+    "primary_weights": {{
+        "relevance": 0.0-1.0,
+        "novelty": 0.0-1.0,
+        "quality": 0.0-1.0,
+        "mood_match": 0.0-1.0,
+        "context_fit": 0.0-1.0
+    }},
+    "diversity_targets": {{
+        "genre": 1-3,
+        "era": 1-3,
+        "energy": 1-2,
+        "artist": 2-3
+    }},
+    "explanation_style": "detailed|concise|technical|casual",
+    "selection_criteria": ["criterion1", "criterion2"]
+}}"""
+
+        try:
+            response = await self.call_llm(user_prompt, system_prompt)
+            framework = self._parse_json_response(response)
+            
+            # Validate and enhance framework
+            framework = self._enhance_evaluation_framework(framework, task_analysis)
+            
+            return framework
+            
+        except Exception as e:
+            self.logger.warning("LLM framework creation failed, using templates", error=str(e))
+            return self._fallback_evaluation_framework(task_analysis)
+    
+    async def _setup_execution_monitoring(self, task_analysis: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Set up execution monitoring and adaptation protocols.
+        
+        Args:
+            task_analysis: Analysis of the user query
+            
+        Returns:
+            Execution monitoring configuration
+        """
+        complexity = task_analysis.get('complexity_level', 'medium')
+        
+        # Define quality thresholds based on complexity
+        quality_thresholds = {
+            'simple': {'min_confidence': 0.7, 'min_relevance': 0.8},
+            'medium': {'min_confidence': 0.6, 'min_relevance': 0.7},
+            'complex': {'min_confidence': 0.5, 'min_relevance': 0.6}
+        }
+        
+        # Define fallback strategies
+        fallback_strategies = [
+            "Broaden search criteria if no results found",
+            "Reduce novelty requirements if underground tracks unavailable",
+            "Adjust mood constraints if mood-specific search fails",
+            "Use genre similarity if exact genre match fails"
+        ]
+        
+        # Define coordination protocols
+        coordination_protocols = {
+            "parallel_execution": True,
+            "result_sharing": False,  # Agents work independently
+            "conflict_resolution": "judge_decides",
+            "timeout_handling": "partial_results_acceptable"
+        }
+        
+        return {
+            "quality_thresholds": quality_thresholds.get(complexity, quality_thresholds['medium']),
+            "fallback_strategies": fallback_strategies,
+            "coordination_protocols": coordination_protocols,
+            "success_metrics": {
+                "min_recommendations": 2,
+                "target_recommendations": 3,
+                "max_processing_time": 300  # 5 minutes
+            }
+        }
+    
+    def _parse_json_response(self, response: str) -> Dict[str, Any]:
+        """Parse JSON response from LLM, handling common formatting issues."""
+        try:
+            # Clean up response - remove markdown formatting
+            cleaned = re.sub(r'```json\s*', '', response)
+            cleaned = re.sub(r'```\s*$', '', cleaned)
+            cleaned = cleaned.strip()
+            
+            return json.loads(cleaned)
+            
+        except json.JSONDecodeError as e:
+            self.logger.warning("Failed to parse JSON response", error=str(e), response=response[:200])
+            raise
+    
+    def _enhance_task_analysis(self, analysis: Dict[str, Any], user_query: str) -> Dict[str, Any]:
+        """Enhance and validate task analysis."""
+        # Ensure required fields exist
+        analysis.setdefault('primary_goal', 'music_discovery')
+        analysis.setdefault('complexity_level', 'medium')
+        analysis.setdefault('context_factors', [])
+        analysis.setdefault('mood_indicators', [])
+        analysis.setdefault('genre_hints', [])
+        
+        # Add pattern-based enhancements
+        query_lower = user_query.lower()
+        
+        # Detect activity context
+        activity_patterns = {
+            'work': ['work', 'coding', 'study', 'focus', 'concentration'],
+            'exercise': ['workout', 'gym', 'running', 'exercise'],
+            'relax': ['chill', 'relax', 'calm', 'peaceful'],
+            'party': ['party', 'dance', 'energetic', 'upbeat']
+        }
+        
+        for activity, keywords in activity_patterns.items():
+            if any(keyword in query_lower for keyword in keywords):
+                if activity not in analysis['context_factors']:
+                    analysis['context_factors'].append(activity)
+        
+        return analysis
+    
+    def _enhance_coordination_strategy(self, coordination: Dict[str, Any], task_analysis: Dict[str, Any]) -> Dict[str, Any]:
+        """Enhance and validate coordination strategy."""
+        # Ensure required structure
+        coordination.setdefault('genre_mood_agent', {})
+        coordination.setdefault('discovery_agent', {})
+        
+        # Set defaults for GenreMoodAgent
+        gma = coordination['genre_mood_agent']
+        gma.setdefault('focus_areas', task_analysis.get('genre_hints', ['indie', 'alternative']))
+        gma.setdefault('energy_level', 'medium')
+        gma.setdefault('search_tags', task_analysis.get('mood_indicators', ['chill']))
+        
+        # Set defaults for DiscoveryAgent
+        da = coordination['discovery_agent']
+        da.setdefault('novelty_priority', 'medium')
+        da.setdefault('underground_bias', 0.6)
+        da.setdefault('discovery_scope', 'medium')
+        
+        return coordination
+    
+    def _enhance_evaluation_framework(self, framework: Dict[str, Any], task_analysis: Dict[str, Any]) -> Dict[str, Any]:
+        """Enhance and validate evaluation framework."""
+        # Ensure required structure
+        framework.setdefault('primary_weights', {})
+        framework.setdefault('diversity_targets', {})
+        
+        # Set default weights
+        weights = framework['primary_weights']
+        weights.setdefault('relevance', 0.3)
+        weights.setdefault('novelty', 0.25)
+        weights.setdefault('quality', 0.25)
+        weights.setdefault('mood_match', 0.2)
+        
+        # Normalize weights to sum to 1.0
+        total_weight = sum(weights.values())
+        if total_weight > 0:
+            for key in weights:
+                weights[key] = weights[key] / total_weight
+        
+        # Set default diversity targets
+        diversity = framework['diversity_targets']
+        diversity.setdefault('genre', 2)
+        diversity.setdefault('era', 2)
+        diversity.setdefault('energy', 1)
+        diversity.setdefault('artist', 3)
+        
+        return framework
+    
+    def _fallback_query_analysis(self, user_query: str) -> Dict[str, Any]:
+        """Fallback query analysis using pattern matching."""
+        query_lower = user_query.lower()
+        
+        # Determine complexity
+        complexity_indicators = {
+            'simple': ['play', 'song', 'music'],
+            'complex': ['discover', 'explore', 'recommend', 'find', 'suggest']
+        }
+        
+        complexity = 'medium'  # default
+        for level, indicators in complexity_indicators.items():
+            if any(indicator in query_lower for indicator in indicators):
+                complexity = level
+                break
+        
+        # Extract mood indicators
+        mood_patterns = {
+            'chill': ['chill', 'relax', 'calm', 'peaceful'],
+            'energetic': ['energetic', 'upbeat', 'pump', 'hype'],
+            'focus': ['focus', 'concentration', 'study', 'work'],
+            'sad': ['sad', 'melancholy', 'depressing'],
+            'happy': ['happy', 'joyful', 'cheerful']
+        }
+        
+        mood_indicators = []
+        for mood, keywords in mood_patterns.items():
+            if any(keyword in query_lower for keyword in keywords):
+                mood_indicators.append(mood)
+        
+        return {
+            'primary_goal': 'music_discovery',
+            'complexity_level': complexity,
+            'context_factors': [],
+            'mood_indicators': mood_indicators or ['general'],
+            'genre_hints': []
+        }
+    
+    def _fallback_coordination_strategy(self, task_analysis: Dict[str, Any]) -> Dict[str, Any]:
+        """Fallback coordination strategy using templates."""
+        return {
+            'genre_mood_agent': {
+                'focus_areas': task_analysis.get('genre_hints', ['indie', 'alternative']),
+                'energy_level': 'medium',
+                'search_tags': task_analysis.get('mood_indicators', ['chill']),
+                'mood_priority': task_analysis.get('mood_indicators', ['general'])[0],
+                'genre_constraints': []
+            },
+            'discovery_agent': {
+                'novelty_priority': 'medium',
+                'similarity_base': 'genre_and_mood',
+                'underground_bias': 0.6,
+                'discovery_scope': 'medium',
+                'exploration_strategy': 'balanced_discovery'
+            }
+        }
+    
+    def _fallback_evaluation_framework(self, task_analysis: Dict[str, Any]) -> Dict[str, Any]:
+        """Fallback evaluation framework using templates."""
+        return {
+            'primary_weights': {
+                'relevance': 0.3,
+                'novelty': 0.25,
+                'quality': 0.25,
+                'mood_match': 0.2
+            },
+            'diversity_targets': {
+                'genre': 2,
+                'era': 2,
+                'energy': 1,
+                'artist': 3
+            },
+            'explanation_style': 'detailed',
+            'selection_criteria': ['relevance', 'novelty', 'quality']
+        }
+    
+    def _initialize_query_patterns(self) -> Dict[str, List[str]]:
+        """Initialize patterns for query analysis."""
+        return {
+            'activity_context': {
+                'work': ['work', 'coding', 'study', 'focus', 'concentration', 'productivity'],
+                'exercise': ['workout', 'gym', 'running', 'exercise', 'fitness'],
+                'relax': ['chill', 'relax', 'calm', 'peaceful', 'unwind'],
+                'party': ['party', 'dance', 'energetic', 'upbeat', 'celebration'],
+                'sleep': ['sleep', 'bedtime', 'lullaby', 'peaceful'],
+                'drive': ['driving', 'road trip', 'car', 'travel']
+            },
+            'mood_indicators': {
+                'happy': ['happy', 'joyful', 'cheerful', 'uplifting', 'positive'],
+                'sad': ['sad', 'melancholy', 'depressing', 'emotional', 'heartbreak'],
+                'energetic': ['energetic', 'pump up', 'hype', 'motivational'],
+                'calm': ['calm', 'peaceful', 'serene', 'tranquil'],
+                'nostalgic': ['nostalgic', 'throwback', 'memories', 'classic'],
+                'romantic': ['romantic', 'love', 'intimate', 'passionate']
+            },
+            'genre_hints': {
+                'rock': ['rock', 'guitar', 'band', 'alternative'],
+                'electronic': ['electronic', 'edm', 'techno', 'house', 'ambient'],
+                'hip_hop': ['hip hop', 'rap', 'beats', 'urban'],
+                'indie': ['indie', 'independent', 'underground', 'alternative'],
+                'classical': ['classical', 'orchestra', 'symphony', 'instrumental'],
+                'jazz': ['jazz', 'blues', 'swing', 'improvisation'],
+                'folk': ['folk', 'acoustic', 'singer-songwriter', 'country']
+            }
+        }
+    
+    def _initialize_strategy_templates(self) -> Dict[str, Dict[str, Any]]:
+        """Initialize strategy templates for different scenarios."""
+        return {
+            'work_focus': {
+                'genre_mood_agent': {
+                    'focus_areas': ['instrumental', 'ambient', 'post-rock'],
+                    'energy_level': 'medium-low',
+                    'search_tags': ['focus', 'study', 'instrumental', 'concentration']
+                },
+                'discovery_agent': {
+                    'novelty_priority': 'medium',
+                    'underground_bias': 0.7,
+                    'discovery_scope': 'narrow'
+                }
+            },
+            'workout_energy': {
+                'genre_mood_agent': {
+                    'focus_areas': ['electronic', 'rock', 'hip-hop'],
+                    'energy_level': 'high',
+                    'search_tags': ['energetic', 'pump', 'workout', 'motivational']
+                },
+                'discovery_agent': {
+                    'novelty_priority': 'low',
+                    'underground_bias': 0.3,
+                    'discovery_scope': 'broad'
+                }
+            },
+            'chill_discovery': {
+                'genre_mood_agent': {
+                    'focus_areas': ['indie', 'alternative', 'folk'],
+                    'energy_level': 'low',
+                    'search_tags': ['chill', 'relax', 'mellow', 'peaceful']
+                },
+                'discovery_agent': {
+                    'novelty_priority': 'high',
+                    'underground_bias': 0.8,
+                    'discovery_scope': 'broad'
+                }
+            }
+        }
+    
+    async def _make_llm_call(self, prompt: str, system_prompt: str = None) -> str:
+        """
+        Make LLM call using Gemini client.
+        
+        Args:
+            prompt: User prompt
+            system_prompt: System prompt
+            
+        Returns:
+            LLM response
+        """
+        if not self.llm_client:
+            raise RuntimeError("Gemini client not initialized")
+        
+        try:
+            # Combine system and user prompts
+            full_prompt = f"{system_prompt}\n\n{prompt}" if system_prompt else prompt
+            
+            # Call Gemini (this will be implemented when we integrate Gemini)
+            # For now, return a placeholder
+            response = await self.llm_client.generate_content(full_prompt)
+            return response.text
+            
+        except Exception as e:
+            self.logger.error("Gemini API call failed", error=str(e))
+            raise
+    
+    def _extract_output_data(self, state: MusicRecommenderState) -> Dict[str, Any]:
+        """Extract PlannerAgent output data."""
+        return {
+            "planning_strategy_created": state.planning_strategy is not None,
+            "strategy_components": len(state.planning_strategy) if state.planning_strategy else 0
+        }
+    
+    def _calculate_confidence(self, state: MusicRecommenderState) -> float:
+        """Calculate confidence in planning strategy."""
+        if not state.planning_strategy:
+            return 0.0
+        
+        # Base confidence
+        confidence = 0.7
+        
+        # Increase confidence based on strategy completeness
+        required_components = ['task_analysis', 'coordination_strategy', 'evaluation_framework']
+        present_components = sum(1 for comp in required_components if comp in state.planning_strategy)
+        confidence += (present_components / len(required_components)) * 0.3
+        
+        return min(confidence, 1.0) 

src/models/__init__.py

@@ -0,0 +1,33 @@
+"""
+Models Package for BeatDebate Multi-Agent System
+
+Contains Pydantic models for state management and data structures.
+"""
+
+from .agent_models import (
+    MusicRecommenderState,
+    AgentStrategy,
+    TaskAnalysis,
+    AgentCoordinationStrategy,
+    EvaluationFramework,
+    TrackRecommendation,
+    AgentDeliberation,
+    ReasoningChain,
+    FinalRecommendationResponse,
+    AgentConfig,
+    SystemConfig
+)
+
+__all__ = [
+    "MusicRecommenderState",
+    "AgentStrategy",
+    "TaskAnalysis",
+    "AgentCoordinationStrategy",
+    "EvaluationFramework",
+    "TrackRecommendation",
+    "AgentDeliberation",
+    "ReasoningChain",
+    "FinalRecommendationResponse",
+    "AgentConfig",
+    "SystemConfig",
+]

src/models/agent_models.py

@@ -0,0 +1,184 @@
+"""
+Agent Models for BeatDebate Multi-Agent Music Recommendation System
+
+Pydantic models for state management, agent communication, and data structures.
+"""
+
+from typing import Dict, List, Any, Optional
+from pydantic import BaseModel, Field
+from datetime import datetime
+
+
+class MusicRecommenderState(BaseModel):
+    """Shared state across all agents in the LangGraph workflow"""
+    
+    # Input
+    user_query: str = Field(..., description="Original user query for music recommendation")
+    user_profile: Optional[Dict[str, Any]] = Field(default=None, description="User preferences and history")
+    
+    # Planning phase
+    planning_strategy: Optional[Dict[str, Any]] = Field(default=None, description="Strategy created by PlannerAgent")
+    execution_plan: Optional[Dict[str, Any]] = Field(default=None, description="Execution monitoring plan")
+    
+    # Advocate phase  
+    genre_mood_recommendations: List[Dict] = Field(default_factory=list, description="GenreMoodAgent recommendations")
+    discovery_recommendations: List[Dict] = Field(default_factory=list, description="DiscoveryAgent recommendations")
+    
+    # Judge phase
+    final_recommendations: List[Dict] = Field(default_factory=list, description="Final selected recommendations")
+    
+    # Reasoning transparency
+    reasoning_log: List[str] = Field(default_factory=list, description="Step-by-step reasoning log")
+    agent_deliberations: List[Dict] = Field(default_factory=list, description="Agent decision records")
+    
+    # Metadata
+    processing_start_time: Optional[float] = Field(default=None, description="Processing start timestamp")
+    total_processing_time: Optional[float] = Field(default=None, description="Total processing time in seconds")
+    session_id: Optional[str] = Field(default=None, description="Unique session identifier")
+
+
+class AgentStrategy(BaseModel):
+    """Strategy object passed between agents"""
+    
+    task_analysis: Dict[str, Any] = Field(..., description="Analysis of the user query and task")
+    coordination_strategy: Dict[str, Any] = Field(..., description="Strategy for each advocate agent")
+    evaluation_framework: Dict[str, Any] = Field(..., description="Criteria for judge evaluation")
+    execution_monitoring: Dict[str, Any] = Field(..., description="Monitoring and adaptation protocols")
+
+
+class TaskAnalysis(BaseModel):
+    """Analysis of user query complexity and intent"""
+    
+    primary_goal: str = Field(..., description="Main intent extracted from query")
+    complexity_level: str = Field(..., description="Query complexity: simple, medium, complex")
+    context_factors: List[str] = Field(default_factory=list, description="Context clues from query")
+    mood_indicators: List[str] = Field(default_factory=list, description="Mood/energy indicators")
+    genre_hints: List[str] = Field(default_factory=list, description="Genre preferences or hints")
+
+
+class AgentCoordinationStrategy(BaseModel):
+    """Coordination strategy for advocate agents"""
+    
+    genre_mood_agent: Dict[str, Any] = Field(..., description="Strategy for GenreMoodAgent")
+    discovery_agent: Dict[str, Any] = Field(..., description="Strategy for DiscoveryAgent")
+
+
+class EvaluationFramework(BaseModel):
+    """Framework for judge evaluation"""
+    
+    primary_weights: Dict[str, float] = Field(..., description="Weights for different criteria")
+    diversity_targets: Dict[str, int] = Field(..., description="Diversity targets for recommendations")
+    explanation_style: str = Field(..., description="Style for generating explanations")
+
+
+class TrackRecommendation(BaseModel):
+    """Individual track recommendation with reasoning"""
+    
+    # Track metadata
+    title: str = Field(..., description="Track title")
+    artist: str = Field(..., description="Artist name")
+    album: Optional[str] = Field(default=None, description="Album name")
+    year: Optional[int] = Field(default=None, description="Release year")
+    
+    # External identifiers
+    lastfm_url: Optional[str] = Field(default=None, description="Last.fm URL")
+    spotify_url: Optional[str] = Field(default=None, description="Spotify URL")
+    preview_url: Optional[str] = Field(default=None, description="Audio preview URL")
+    
+    # Metadata
+    genres: List[str] = Field(default_factory=list, description="Genre tags")
+    tags: List[str] = Field(default_factory=list, description="Mood/style tags")
+    similar_artists: List[str] = Field(default_factory=list, description="Similar artists")
+    
+    # Recommendation context
+    reasoning_chain: str = Field(..., description="Agent's reasoning for this recommendation")
+    confidence_score: float = Field(..., ge=0.0, le=1.0, description="Confidence in recommendation")
+    novelty_score: Optional[float] = Field(default=None, ge=0.0, le=1.0, description="Novelty/underground score")
+    relevance_score: float = Field(..., ge=0.0, le=1.0, description="Relevance to user query")
+    
+    # Agent attribution
+    recommending_agent: str = Field(..., description="Agent that made this recommendation")
+    strategy_applied: Dict[str, Any] = Field(..., description="Strategy used for this recommendation")
+
+
+class AgentDeliberation(BaseModel):
+    """Record of agent decision-making process"""
+    
+    agent_name: str = Field(..., description="Name of the agent")
+    timestamp: datetime = Field(default_factory=datetime.now, description="When deliberation occurred")
+    input_data: Dict[str, Any] = Field(..., description="Input data for the agent")
+    reasoning_steps: List[str] = Field(..., description="Step-by-step reasoning process")
+    output_data: Dict[str, Any] = Field(..., description="Agent's output/decision")
+    confidence: float = Field(..., ge=0.0, le=1.0, description="Agent's confidence in decision")
+    processing_time: float = Field(..., description="Time taken for deliberation in seconds")
+
+
+class ReasoningChain(BaseModel):
+    """Structured reasoning chain for transparency"""
+    
+    step_number: int = Field(..., description="Step number in reasoning chain")
+    step_type: str = Field(..., description="Type of reasoning step")
+    description: str = Field(..., description="Description of reasoning step")
+    evidence: List[str] = Field(default_factory=list, description="Evidence supporting this step")
+    confidence: float = Field(..., ge=0.0, le=1.0, description="Confidence in this reasoning step")
+
+
+class FinalRecommendationResponse(BaseModel):
+    """Final response format for the user"""
+    
+    recommendations: List[TrackRecommendation] = Field(..., description="Final track recommendations")
+    explanation: str = Field(..., description="Overall explanation of recommendations")
+    planning_summary: str = Field(..., description="Summary of planning process")
+    agent_coordination_summary: str = Field(..., description="Summary of agent coordination")
+    
+    # Metadata
+    total_processing_time: float = Field(..., description="Total processing time in seconds")
+    agents_involved: List[str] = Field(..., description="List of agents that participated")
+    reasoning_transparency: List[AgentDeliberation] = Field(..., description="Full reasoning transparency")
+    session_id: str = Field(..., description="Session identifier")
+    
+    # Quality metrics
+    diversity_score: float = Field(..., ge=0.0, le=1.0, description="Diversity of recommendations")
+    novelty_score: float = Field(..., ge=0.0, le=1.0, description="Average novelty score")
+    confidence_score: float = Field(..., ge=0.0, le=1.0, description="Overall confidence")
+
+
+class AgentConfig(BaseModel):
+    """Configuration for individual agents"""
+    
+    agent_name: str = Field(..., description="Name of the agent")
+    agent_type: str = Field(..., description="Type of agent (planner, advocate, judge)")
+    llm_model: str = Field(default="gemini-2.0-flash-exp", description="LLM model to use")
+    temperature: float = Field(default=0.7, ge=0.0, le=2.0, description="LLM temperature")
+    max_tokens: int = Field(default=1000, description="Maximum tokens for LLM response")
+    timeout_seconds: int = Field(default=30, description="Timeout for agent processing")
+    
+    # Agent-specific configuration
+    specialty_config: Dict[str, Any] = Field(default_factory=dict, description="Agent-specific configuration")
+
+
+class SystemConfig(BaseModel):
+    """Overall system configuration"""
+    
+    # API configurations
+    gemini_api_key: str = Field(..., description="Gemini API key")
+    lastfm_api_key: str = Field(..., description="Last.fm API key")
+    spotify_client_id: Optional[str] = Field(default=None, description="Spotify client ID")
+    spotify_client_secret: Optional[str] = Field(default=None, description="Spotify client secret")
+    
+    # Rate limiting
+    gemini_rate_limit: int = Field(default=15, description="Gemini requests per minute")
+    lastfm_rate_limit: float = Field(default=3.0, description="Last.fm requests per second")
+    spotify_rate_limit: int = Field(default=50, description="Spotify requests per hour")
+    
+    # Caching
+    cache_enabled: bool = Field(default=True, description="Enable caching")
+    cache_ttl_hours: int = Field(default=24, description="Cache TTL in hours")
+    cache_directory: str = Field(default="data/cache", description="Cache directory path")
+    
+    # Agent configurations
+    agent_configs: Dict[str, AgentConfig] = Field(default_factory=dict, description="Configuration for each agent")
+    
+    # Performance settings
+    max_concurrent_agents: int = Field(default=2, description="Maximum concurrent agent executions")
+    total_timeout_minutes: int = Field(default=5, description="Total workflow timeout in minutes") 

src/services/__init__.py

@@ -0,0 +1,8 @@
+"""
+Services Package for BeatDebate Multi-Agent System
+
+Contains business logic, workflow orchestration, and utility services.
+"""
+
+# Services will be added as we implement them
+__all__ = []

tests/test_planner_agent.py

@@ -0,0 +1,215 @@
+"""
+Tests for PlannerAgent
+
+Basic tests to verify PlannerAgent functionality and strategic planning behavior.
+"""
+
+import pytest
+import asyncio
+from unittest.mock import Mock, AsyncMock
+
+from src.models.agent_models import MusicRecommenderState, AgentConfig
+from src.agents.planner_agent import PlannerAgent
+
+
+class TestPlannerAgent:
+    """Test suite for PlannerAgent"""
+    
+    @pytest.fixture
+    def agent_config(self):
+        """Create test agent configuration"""
+        return AgentConfig(
+            agent_name="PlannerAgent",
+            agent_type="planner",
+            llm_model="gemini-2.0-flash-exp",
+            temperature=0.7,
+            timeout_seconds=30
+        )
+    
+    @pytest.fixture
+    def mock_gemini_client(self):
+        """Create mock Gemini client"""
+        client = Mock()
+        client.generate_content = AsyncMock()
+        return client
+    
+    @pytest.fixture
+    def planner_agent(self, agent_config, mock_gemini_client):
+        """Create PlannerAgent instance for testing"""
+        return PlannerAgent(agent_config, mock_gemini_client)
+    
+    @pytest.fixture
+    def test_state(self):
+        """Create test state with user query"""
+        return MusicRecommenderState(
+            user_query="I need focus music for coding",
+            session_id="test_session_123"
+        )
+    
+    def test_planner_agent_initialization(self, planner_agent):
+        """Test that PlannerAgent initializes correctly"""
+        assert planner_agent.agent_name == "PlannerAgent"
+        assert planner_agent.agent_type == "planner"
+        assert planner_agent.llm_client is not None
+        assert hasattr(planner_agent, 'query_patterns')
+        assert hasattr(planner_agent, 'strategy_templates')
+    
+    def test_fallback_query_analysis(self, planner_agent):
+        """Test fallback query analysis without LLM"""
+        # Test simple query
+        analysis = planner_agent._fallback_query_analysis("play some music")
+        assert analysis['complexity_level'] == 'simple'
+        assert analysis['primary_goal'] == 'music_discovery'
+        
+        # Test complex query
+        analysis = planner_agent._fallback_query_analysis("discover underground indie rock for studying")
+        assert analysis['complexity_level'] == 'complex'
+        assert 'focus' in analysis['mood_indicators']
+    
+    def test_fallback_coordination_strategy(self, planner_agent):
+        """Test fallback coordination strategy creation"""
+        task_analysis = {
+            'primary_goal': 'focus_music',
+            'complexity_level': 'medium',
+            'mood_indicators': ['focus', 'chill'],
+            'genre_hints': ['indie', 'electronic']
+        }
+        
+        coordination = planner_agent._fallback_coordination_strategy(task_analysis)
+        
+        assert 'genre_mood_agent' in coordination
+        assert 'discovery_agent' in coordination
+        assert coordination['genre_mood_agent']['focus_areas'] == ['indie', 'electronic']
+        assert coordination['discovery_agent']['novelty_priority'] == 'medium'
+    
+    def test_fallback_evaluation_framework(self, planner_agent):
+        """Test fallback evaluation framework creation"""
+        task_analysis = {'complexity_level': 'medium'}
+        
+        framework = planner_agent._fallback_evaluation_framework(task_analysis)
+        
+        assert 'primary_weights' in framework
+        assert 'diversity_targets' in framework
+        assert sum(framework['primary_weights'].values()) == pytest.approx(1.0, rel=1e-2)
+    
+    def test_enhance_task_analysis(self, planner_agent):
+        """Test task analysis enhancement"""
+        analysis = {'primary_goal': 'test'}
+        query = "I need music for coding and focus"
+        
+        enhanced = planner_agent._enhance_task_analysis(analysis, query)
+        
+        assert 'work' in enhanced['context_factors']
+        assert enhanced['complexity_level'] == 'medium'  # default
+        assert isinstance(enhanced['mood_indicators'], list)
+    
+    def test_parse_json_response(self, planner_agent):
+        """Test JSON response parsing"""
+        # Test clean JSON
+        response = '{"test": "value", "number": 123}'
+        parsed = planner_agent._parse_json_response(response)
+        assert parsed['test'] == 'value'
+        assert parsed['number'] == 123
+        
+        # Test JSON with markdown
+        response = '```json\n{"test": "value"}\n```'
+        parsed = planner_agent._parse_json_response(response)
+        assert parsed['test'] == 'value'
+    
+    @pytest.mark.asyncio
+    async def test_process_with_fallback(self, planner_agent, test_state):
+        """Test process method using fallback strategies (no LLM calls)"""
+        # Mock LLM to raise exception, forcing fallback
+        planner_agent.llm_client.generate_content.side_effect = Exception("LLM unavailable")
+        
+        result_state = await planner_agent.process(test_state)
+        
+        # Verify strategy was created using fallbacks
+        assert result_state.planning_strategy is not None
+        assert 'task_analysis' in result_state.planning_strategy
+        assert 'coordination_strategy' in result_state.planning_strategy
+        assert 'evaluation_framework' in result_state.planning_strategy
+        assert 'execution_monitoring' in result_state.planning_strategy
+        
+        # Verify reasoning log was updated
+        assert len(result_state.reasoning_log) > 0
+        assert any('PlannerAgent' in log for log in result_state.reasoning_log)
+    
+    @pytest.mark.asyncio
+    async def test_process_with_mock_llm(self, planner_agent, test_state):
+        """Test process method with mocked LLM responses"""
+        # Mock LLM responses
+        mock_responses = [
+            '{"primary_goal": "focus_music", "complexity_level": "medium", "context_factors": ["work"], "mood_indicators": ["focus"], "genre_hints": ["instrumental"]}',
+            '{"genre_mood_agent": {"focus_areas": ["instrumental"], "energy_level": "medium"}, "discovery_agent": {"novelty_priority": "medium", "underground_bias": 0.6}}',
+            '{"primary_weights": {"relevance": 0.4, "novelty": 0.3, "quality": 0.3}, "diversity_targets": {"genre": 2, "artist": 3}}'
+        ]
+        
+        planner_agent.llm_client.generate_content.side_effect = [
+            Mock(text=response) for response in mock_responses
+        ]
+        
+        result_state = await planner_agent.process(test_state)
+        
+        # Verify strategy was created
+        assert result_state.planning_strategy is not None
+        strategy = result_state.planning_strategy
+        
+        # Verify task analysis
+        assert strategy['task_analysis']['primary_goal'] == 'focus_music'
+        assert strategy['task_analysis']['complexity_level'] == 'medium'
+        
+        # Verify coordination strategy
+        assert 'genre_mood_agent' in strategy['coordination_strategy']
+        assert 'discovery_agent' in strategy['coordination_strategy']
+        
+        # Verify evaluation framework
+        assert 'primary_weights' in strategy['evaluation_framework']
+        assert 'diversity_targets' in strategy['evaluation_framework']
+    
+    def test_execution_monitoring_setup(self, planner_agent):
+        """Test execution monitoring setup"""
+        task_analysis = {'complexity_level': 'complex'}
+        
+        monitoring = asyncio.run(planner_agent._setup_execution_monitoring(task_analysis))
+        
+        assert 'quality_thresholds' in monitoring
+        assert 'fallback_strategies' in monitoring
+        assert 'coordination_protocols' in monitoring
+        assert 'success_metrics' in monitoring
+        
+        # Verify complex query gets lower thresholds
+        assert monitoring['quality_thresholds']['min_confidence'] == 0.5
+        assert monitoring['success_metrics']['target_recommendations'] == 3
+    
+    def test_strategy_templates_initialization(self, planner_agent):
+        """Test that strategy templates are properly initialized"""
+        templates = planner_agent.strategy_templates
+        
+        assert 'work_focus' in templates
+        assert 'workout_energy' in templates
+        assert 'chill_discovery' in templates
+        
+        # Verify template structure
+        work_template = templates['work_focus']
+        assert 'genre_mood_agent' in work_template
+        assert 'discovery_agent' in work_template
+        assert work_template['genre_mood_agent']['energy_level'] == 'medium-low'
+    
+    def test_query_patterns_initialization(self, planner_agent):
+        """Test that query patterns are properly initialized"""
+        patterns = planner_agent.query_patterns
+        
+        assert 'activity_context' in patterns
+        assert 'mood_indicators' in patterns
+        assert 'genre_hints' in patterns
+        
+        # Verify pattern content
+        assert 'work' in patterns['activity_context']
+        assert 'coding' in patterns['activity_context']['work']
+        assert 'happy' in patterns['mood_indicators']
+        assert 'rock' in patterns['genre_hints']
+
+
+if __name__ == "__main__":
+    pytest.main([__file__]) 

uv.lock

@@ -368,6 +368,13 @@ dev = [
     { name = "ruff" },
 ]
 
+[package.dev-dependencies]
+dev = [
+    { name = "pytest" },
+    { name = "pytest-asyncio" },
+    { name = "pytest-cov" },
+]
+
 [package.metadata]
 requires-dist = [
     { name = "aiohttp", specifier = ">=3.9.0" },
@@ -401,6 +408,13 @@ requires-dist = [
     { name = "uvicorn", specifier = ">=0.24.0" },
 ]
 
+[package.metadata.requires-dev]
+dev = [
+    { name = "pytest", specifier = ">=8.3.5" },
+    { name = "pytest-asyncio", specifier = ">=0.26.0" },
+    { name = "pytest-cov", specifier = ">=6.1.1" },
+]
+
 [[package]]
 name = "beautifulsoup4"
 version = "4.13.4"