Upload folder using huggingface_hub

analytics.py

@@ -0,0 +1,215 @@
+"""
+Performance Analytics & Episode History
+
+Tracks episode metrics over time and provides analysis tools.
+"""
+
+from typing import List, Dict, Any, Optional
+from dataclasses import dataclass, field
+from datetime import datetime
+import json
+import os
+
+
+@dataclass
+class EpisodeMetrics:
+    """Metrics for a single episode."""
+    episode_id: str
+    task_id: str
+    start_time: datetime
+    end_time: Optional[datetime] = None
+    steps: int = 0
+    total_reward: float = 0.0
+    total_vehicles: int = 0
+    total_emergency: int = 0
+    total_waiting_time: float = 0.0
+    total_collisions: int = 0
+    phase_changes: int = 0
+    avg_queue_length: List[float] = field(default_factory=lambda: [0.0, 0.0, 0.0, 0.0])
+    rewards_history: List[float] = field(default_factory=list)
+    decisions: List[Dict[str, Any]] = field(default_factory=list)
+    
+    @property
+    def duration_seconds(self) -> float:
+        if self.end_time:
+            return (self.end_time - self.start_time).total_seconds()
+        return 0.0
+    
+    @property
+    def throughput_per_step(self) -> float:
+        if self.steps > 0:
+            return self.total_vehicles / self.steps
+        return 0.0
+    
+    @property
+    def avg_reward_per_step(self) -> float:
+        if self.steps > 0:
+            return self.total_reward / self.steps
+        return 0.0
+
+
+class EpisodeHistory:
+    """Store and analyze episode history."""
+    
+    def __init__(self, max_episodes: int = 100):
+        self.episodes: List[EpisodeMetrics] = []
+        self.max_episodes = max_episodes
+        self._current: Optional[EpisodeMetrics] = None
+    
+    def start_episode(self, episode_id: str, task_id: str) -> EpisodeMetrics:
+        """Start tracking a new episode."""
+        episode = EpisodeMetrics(
+            episode_id=episode_id,
+            task_id=task_id,
+            start_time=datetime.now(),
+        )
+        self._current = episode
+        return episode
+    
+    def record_step(
+        self,
+        step: int,
+        reward: float,
+        action: Dict[str, Any],
+        observation: Dict[str, Any],
+    ) -> None:
+        """Record a step in the current episode."""
+        if self._current:
+            self._current.steps = step
+            self._current.total_reward += reward
+            self._current.rewards_history.append(reward)
+            
+            # Track queue lengths for averaging
+            queues = observation.get("queue_lengths", [0, 0, 0, 0])
+            for i, q in enumerate(queues):
+                self._current.avg_queue_length[i] = (
+                    self._current.avg_queue_length[i] * (step - 1) + q
+                ) / step
+            
+            # Record decision
+            self._current.decisions.append({
+                "step": step,
+                "action": action,
+                "phase": observation.get("current_phase"),
+                "queues": queues,
+                "emergency_queues": observation.get("emergency_queue", [0, 0, 0, 0]),
+            })
+    
+    def record_state(self, state: Dict[str, Any]) -> None:
+        """Record final state metrics."""
+        if self._current:
+            self._current.total_vehicles = state.get("total_vehicles_passed", 0)
+            self._current.total_emergency = state.get("total_emergency_passed", 0)
+            self._current.total_waiting_time = state.get("total_waiting_time", 0.0)
+            self._current.total_collisions = state.get("total_collisions", 0)
+            self._current.phase_changes = state.get("total_phase_changes", 0)
+    
+    def end_episode(self) -> EpisodeMetrics:
+        """Finalize the current episode."""
+        if self._current:
+            self._current.end_time = datetime.now()
+            self.episodes.append(self._current)
+            
+            # Trim old episodes
+            if len(self.episodes) > self.max_episodes:
+                self.episodes = self.episodes[-self.max_episodes:]
+            
+            result = self._current
+            self._current = None
+            return result
+        
+        raise RuntimeError("No active episode to end")
+    
+    def get_summary(self, task_id: Optional[str] = None) -> Dict[str, Any]:
+        """Get summary statistics."""
+        episodes = self.episodes
+        if task_id:
+            episodes = [e for e in episodes if e.task_id == task_id]
+        
+        if not episodes:
+            return {"message": "No episodes recorded yet"}
+        
+        total_episodes = len(episodes)
+        avg_reward = sum(e.avg_reward_per_step for e in episodes) / total_episodes
+        avg_throughput = sum(e.throughput_per_step for e in episodes) / total_episodes
+        avg_duration = sum(e.duration_seconds for e in episodes) / total_episodes
+        
+        # Find best episode
+        best_idx = max(range(total_episodes), key=lambda i: episodes[i].avg_reward_per_step)
+        best = episodes[best_idx]
+        
+        return {
+            "total_episodes": total_episodes,
+            "avg_reward_per_step": round(avg_reward, 4),
+            "avg_throughput_per_step": round(avg_throughput, 4),
+            "avg_duration_seconds": round(avg_duration, 2),
+            "best_episode": {
+                "episode_id": best.episode_id,
+                "task_id": best.task_id,
+                "reward_per_step": round(best.avg_reward_per_step, 4),
+                "total_reward": round(best.total_reward, 2),
+                "steps": best.steps,
+            },
+            "recent_performance": [
+                {
+                    "episode_id": e.episode_id,
+                    "task_id": e.task_id,
+                    "reward_per_step": round(e.avg_reward_per_step, 4),
+                    "steps": e.steps,
+                }
+                for e in episodes[-10:]
+            ],
+        }
+    
+    def get_episode_details(self, episode_id: str) -> Optional[Dict[str, Any]]:
+        """Get detailed metrics for a specific episode."""
+        for episode in self.episodes:
+            if episode.episode_id == episode_id:
+                return {
+                    "episode_id": episode.episode_id,
+                    "task_id": episode.task_id,
+                    "start_time": episode.start_time.isoformat(),
+                    "end_time": episode.end_time.isoformat() if episode.end_time else None,
+                    "duration_seconds": episode.duration_seconds,
+                    "steps": episode.steps,
+                    "total_reward": round(episode.total_reward, 2),
+                    "total_vehicles": episode.total_vehicles,
+                    "total_emergency": episode.total_emergency,
+                    "total_collisions": episode.total_collisions,
+                    "phase_changes": episode.phase_changes,
+                    "avg_queue_lengths": [round(q, 2) for q in episode.avg_queue_length],
+                    "throughput_per_step": round(episode.throughput_per_step, 4),
+                    "reward_per_step": round(episode.avg_reward_per_step, 4),
+                    "rewards_history": [round(r, 3) for r in episode.rewards_history],
+                    "decision_count": len(episode.decisions),
+                }
+        return None
+    
+    def export_to_json(self, filepath: str) -> None:
+        """Export all episodes to JSON file."""
+        data = {
+            "export_time": datetime.now().isoformat(),
+            "total_episodes": len(self.episodes),
+            "episodes": [
+                {
+                    "episode_id": e.episode_id,
+                    "task_id": e.task_id,
+                    "steps": e.steps,
+                    "total_reward": e.total_reward,
+                    "total_vehicles": e.total_vehicles,
+                    "avg_reward_per_step": e.avg_reward_per_step,
+                }
+                for e in self.episodes
+            ],
+        }
+        with open(filepath, 'w') as f:
+            json.dump(data, f, indent=2)
+
+
+# Global history instance
+_episode_history = EpisodeHistory()
+
+
+def get_history() -> EpisodeHistory:
+    """Get the global episode history instance."""
+    return _episode_history

arena.py

@@ -0,0 +1,389 @@
+"""
+Comparative Agent Arena
+
+Run multiple agents simultaneously to compare performance.
+Supports:
+- Rule-based agent
+- LLM agent (makes live API calls)
+- Random agent
+"""
+
+import os
+import json
+import textwrap
+import time
+import random
+import asyncio
+from typing import Dict, List, Any, Optional
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from traffic_control.environment import TrafficControlEnvironment
+from traffic_control.models import TrafficAction, TrafficObservation
+from traffic_control.tasks import grade, GradeResult
+
+
+try:
+    from openai import OpenAI
+    _HAS_OPENAI = True
+except ImportError:
+    _HAS_OPENAI = False
+
+
+@dataclass
+class AgentResult:
+    """Result for a single agent run."""
+    agent_name: str
+    agent_type: str
+    task_id: str
+    episode_id: str
+    steps: int = 0
+    total_reward: float = 0.0
+    score: float = 0.0
+    metrics: Dict[str, Any] = field(default_factory=dict)
+    grade_result: Optional[GradeResult] = None
+    decision_times: List[float] = field(default_factory=list)
+    
+    @property
+    def avg_decision_time_ms(self) -> float:
+        if self.decision_times:
+            return sum(self.decision_times) / len(self.decision_times) * 1000
+        return 0.0
+
+
+class RuleBasedAgent:
+    """Rule-based traffic controller (optimized for high scores)."""
+    
+    def __init__(self, name: str = "RuleBased"):
+        self.name = name
+    
+    def decide(self, obs: TrafficObservation) -> int:
+        """Return light phase based on rules."""
+        em_q = obs.emergency_queue
+        em_u = obs.emergency_urgency
+        q = obs.queue_lengths
+        current = obs.current_phase
+        time_in = obs.time_in_phase
+        
+        # Emergency prioritization
+        ns_em_urgency = em_u[0] + em_u[1] + em_q[0] * 2 + em_q[1] * 2
+        ew_em_urgency = em_u[2] + em_u[3] + em_q[2] * 2 + em_q[3] * 2
+        
+        if ns_em_urgency > 0 or ew_em_urgency > 0:
+            return 0 if ns_em_urgency >= ew_em_urgency else 1
+        
+        # Queue-based switching
+        ns_total = q[0] + q[1]
+        ew_total = q[2] + q[3]
+        min_phase_time = min(3 + max(ns_total, ew_total) // 5, 8)
+        
+        if current == 0 and time_in < min_phase_time and ns_total > 0:
+            return 0
+        if current == 1 and time_in < min_phase_time and ew_total > 0:
+            return 1
+        
+        if ns_total >= ew_total + 2:
+            return 0
+        elif ew_total >= ns_total + 2:
+            return 1
+        else:
+            return current if current in (0, 1) else 0
+
+
+class RandomAgent:
+    """Random traffic controller for baseline comparison."""
+    
+    def __init__(self, name: str = "Random", seed: int = 42):
+        self.name = name
+        self.rng = random.Random(seed)
+    
+    def decide(self, obs: TrafficObservation) -> int:
+        """Return random light phase."""
+        return self.rng.choice([0, 1, 2])
+
+
+class RoundRobinAgent:
+    """Simple round-robin controller."""
+    
+    def __init__(self, name: str = "RoundRobin", switch_interval: int = 5):
+        self.name = name
+        self.switch_interval = switch_interval
+        self.step_count = 0
+    
+    def decide(self, obs: TrafficObservation) -> int:
+        """Alternate between phases."""
+        self.step_count += 1
+        phase_index = (self.step_count // self.switch_interval) % 2
+        return int(phase_index)
+
+
+# LLM System Prompt for arena
+LLM_SYSTEM_PROMPT = textwrap.dedent("""
+    You are an Autonomous Traffic Control AI managing a 4-way intersection.
+
+    PHASES:
+      0 = North-South Green  (N/S vehicles may pass)
+      1 = East-West Green    (E/W vehicles may pass)
+      2 = All Red            (no vehicles pass)
+
+    DECISION RULES (apply in order):
+      1. EMERGENCY CHECK: If emergency vehicles are waiting, prioritize them.
+      2. MINIMUM PHASE TIME: Stay in current phase at least 3 steps if traffic present.
+      3. QUEUE BALANCE: Switch to direction with significantly more traffic.
+
+    OUTPUT: Reply with exactly one JSON object: {"light_phase": <0, 1, or 2>}
+""")
+
+
+class LLM_Agent:
+    """LLM-powered agent that makes dynamic API calls."""
+    
+    def __init__(
+        self,
+        name: str = "LLM-Agent",
+        api_base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        model_name: str = "gpt-4.1-mini",
+    ):
+        self.name = name
+        self.model_name = model_name
+        self.api_calls_made = 0
+        
+        # Initialize OpenAI client if credentials available
+        if _HAS_OPENAI and (api_base_url or api_key):
+            self.client = OpenAI(
+                base_url=api_base_url or "https://api.openai.com/v1",
+                api_key=api_key or "dummy-key",
+            )
+        else:
+            self.client = None
+    
+    def _build_prompt(self, obs: TrafficObservation) -> str:
+        """Build the user prompt from observation."""
+        return (
+            f"Current phase: {obs.current_phase} (0=NS Green, 1=EW Green, 2=All Red)\n"
+            f"Time in phase: {obs.time_in_phase} steps\n"
+            f"\n"
+            f"Queue lengths (N, S, E, W): {obs.queue_lengths}\n"
+            f"Emergency queues (N, S, E, W): {obs.emergency_queue}\n"
+            f"Emergency urgency (N, S, E, W): {obs.emergency_urgency}\n"
+            f"\n"
+            f"What light phase should be set? Respond with JSON: {{\"light_phase\": 0, 1, or 2}}"
+        )
+    
+    def decide(self, obs: TrafficObservation) -> int:
+        """Make LLM API call to get decision."""
+        if not self.client:
+            # Fallback to rule-based if no client
+            return self._rule_fallback(obs)
+        
+        try:
+            resp = self.client.chat.completions.create(
+                model=self.model_name,
+                messages=[
+                    {"role": "system", "content": LLM_SYSTEM_PROMPT},
+                    {"role": "user", "content": self._build_prompt(obs)},
+                ],
+                temperature=0.0,
+                max_tokens=32,
+                stream=False,
+            )
+            self.api_calls_made += 1
+            
+            content = resp.choices[0].message.content.strip()
+            
+            # Parse JSON response
+            try:
+                data = json.loads(content)
+                phase = int(data.get("light_phase", 0))
+                return max(0, min(2, phase))  # Clamp to valid range
+            except (json.JSONDecodeError, ValueError, KeyError):
+                # Fallback if parsing fails
+                return self._rule_fallback(obs)
+                
+        except Exception as e:
+            # Fallback on API error
+            print(f"[LLM Agent] API error: {e}, using fallback")
+            return self._rule_fallback(obs)
+    
+    def _rule_fallback(self, obs: TrafficObservation) -> int:
+        """Rule-based fallback when LLM fails."""
+        em_q = obs.emergency_queue
+        em_u = obs.emergency_urgency
+        q = obs.queue_lengths
+        current = obs.current_phase
+        
+        # Emergency prioritization
+        ns_em = em_u[0] + em_u[1] + em_q[0] + em_q[1]
+        ew_em = em_u[2] + em_u[3] + em_q[2] + em_q[3]
+        
+        if ns_em > 0 or ew_em > 0:
+            return 0 if ns_em >= ew_em else 1
+        
+        # Queue-based
+        ns_total = q[0] + q[1]
+        ew_total = q[2] + q[3]
+        
+        if ns_total > ew_total:
+            return 0
+        elif ew_total > ns_total:
+            return 1
+        else:
+            return current if current in (0, 1) else 0
+
+
+class Arena:
+    """Run multiple agents and compare results."""
+    
+    def __init__(self):
+        self.results: List[AgentResult] = []
+        
+        # Get LLM credentials from env (for arena LLM agent)
+        api_base = os.environ.get("API_BASE_URL")
+        api_key = os.environ.get("API_KEY")
+        model = os.environ.get("MODEL_NAME", "gpt-4.1-mini")
+        
+        self.agents = {
+            "llm": LLM_Agent("Dynamic LLM", api_base, api_key, model),
+            "rule_based": RuleBasedAgent("Smart Rule-Based"),
+            "random": RandomAgent("Random Baseline"),
+            "round_robin": RoundRobinAgent("Round Robin"),
+        }
+    
+    async def run_agent(
+        self,
+        agent_type: str,
+        task_id: str,
+        max_steps: int = 300,
+        seed: int = 42,
+    ) -> AgentResult:
+        """Run a single agent episode."""
+        env = TrafficControlEnvironment(task_id=task_id)
+        agent = self.agents.get(agent_type, self.agents["rule_based"])
+        
+        obs = env.reset(seed=seed)
+        episode_id = env._episode_id
+        
+        result = AgentResult(
+            agent_name=agent.name,
+            agent_type=agent_type,
+            task_id=task_id,
+            episode_id=episode_id,
+        )
+        
+        for step in range(max_steps):
+            import time
+            start_time = time.time()
+            
+            action_id = agent.decide(obs)
+            action = TrafficAction(light_phase=action_id)
+            
+            decision_time = time.time() - start_time
+            result.decision_times.append(decision_time)
+            
+            obs = env.step(action)
+            result.steps = step + 1
+            result.total_reward += obs.reward or 0.0
+            
+            if obs.done:
+                break
+        
+        # Grade the result
+        state = env.state
+        result.grade_result = grade(
+            task_id,
+            total_vehicles_passed=state.total_vehicles_passed,
+            total_emergency_passed=state.total_emergency_passed,
+            total_waiting_time=state.total_waiting_time,
+            total_collisions=state.total_collisions,
+            total_emergency_delay=state.total_emergency_delay,
+            total_phase_changes=state.total_phase_changes,
+            step_count=result.steps,
+        )
+        result.score = result.grade_result.score
+        result.metrics = result.grade_result.metrics
+        
+        return result
+    
+    async def run_comparison(
+        self,
+        task_id: str,
+        agents: Optional[List[str]] = None,
+        runs_per_agent: int = 1,
+    ) -> Dict[str, Any]:
+        """Run multiple agents and compare."""
+        agents_to_run = agents or list(self.agents.keys())
+        all_results = []
+        
+        for agent_type in agents_to_run:
+            for run in range(runs_per_agent):
+                seed = 42 + run
+                result = await self.run_agent(agent_type, task_id, seed=seed)
+                all_results.append(result)
+        
+        self.results.extend(all_results)
+        
+        # Aggregate results
+        summary = self._aggregate_results(all_results)
+        return summary
+    
+    def _aggregate_results(self, results: List[AgentResult]) -> Dict[str, Any]:
+        """Aggregate results by agent type."""
+        by_agent: Dict[str, List[AgentResult]] = {}
+        for r in results:
+            if r.agent_type not in by_agent:
+                by_agent[r.agent_type] = []
+            by_agent[r.agent_type].append(r)
+        
+        summary = {
+            "timestamp": datetime.now().isoformat(),
+            "total_runs": len(results),
+            "agents": {},
+            "winner": None,
+        }
+        
+        best_score = -1
+        best_agent = None
+        
+        for agent_type, agent_results in by_agent.items():
+            avg_score = sum(r.score for r in agent_results) / len(agent_results)
+            avg_reward = sum(r.total_reward for r in agent_results) / len(agent_results)
+            avg_steps = sum(r.steps for r in agent_results) / len(agent_results)
+            avg_time = sum(r.avg_decision_time_ms for r in agent_results) / len(agent_results)
+            
+            summary["agents"][agent_type] = {
+                "name": agent_results[0].agent_name,
+                "runs": len(agent_results),
+                "avg_score": round(avg_score, 4),
+                "avg_total_reward": round(avg_reward, 2),
+                "avg_steps": round(avg_steps, 1),
+                "avg_decision_time_ms": round(avg_time, 2),
+                "best_run": max(agent_results, key=lambda r: r.score).episode_id,
+            }
+            
+            if avg_score > best_score:
+                best_score = avg_score
+                best_agent = agent_type
+        
+        summary["winner"] = best_agent
+        summary["all_runs"] = [
+            {
+                "agent": r.agent_type,
+                "episode_id": r.episode_id,
+                "score": r.score,
+                "reward": round(r.total_reward, 2),
+                "steps": r.steps,
+            }
+            for r in results
+        ]
+        
+        return summary
+
+
+# Global arena instance
+_arena = Arena()
+
+
+def get_arena() -> Arena:
+    """Get the global arena instance."""
+    return _arena

dashboard.py

@@ -0,0 +1,253 @@
+"""
+Real-time Visual Dashboard for Traffic Control Environment.
+
+Generates SVG visualizations of the 4-way intersection showing:
+- Vehicles in each queue
+- Traffic light states with color-coded signals
+- Emergency vehicles with flashing indicators
+- Live statistics overlay
+"""
+
+from typing import List, Optional, Dict, Any
+from dataclasses import dataclass
+import json
+
+
+@dataclass
+class RenderState:
+    """Current state for rendering."""
+    current_phase: int
+    time_in_phase: int
+    queue_lengths: List[int]
+    emergency_queue: List[int]
+    emergency_urgency: List[int]
+    total_vehicles_passed: int = 0
+    total_emergency_passed: int = 0
+    step_count: int = 0
+    reward: float = 0.0
+
+
+def get_phase_color(phase: int, direction: str) -> str:
+    """Get traffic light color for a given phase and direction."""
+    colors = {
+        0: {"NS": "#22c55e", "EW": "#ef4444"},  # NS_GREEN
+        1: {"NS": "#ef4444", "EW": "#22c55e"},  # EW_GREEN
+        2: {"NS": "#ef4444", "EW": "#ef4444"},  # ALL_RED
+        3: {"NS": "#eab308", "EW": "#ef4444"},  # NS_YELLOW
+        4: {"NS": "#ef4444", "EW": "#eab308"},  # EW_YELLOW
+    }
+    mapping = colors.get(phase, colors[0])
+    return mapping.get(direction, "#ef4444")
+
+
+def render_intersection(state: RenderState, width: int = 600, height: int = 600) -> str:
+    """
+    Render the intersection as an SVG string.
+    
+    Args:
+        state: Current simulation state
+        width: SVG width in pixels
+        height: SVG height in pixels
+        
+    Returns:
+        SVG string
+    """
+    cx, cy = width // 2, height // 2
+    road_width = 80
+    lane_width = road_width // 2
+    
+    # Colors
+    bg_color = "#1a1a2e"
+    road_color = "#2d2d44"
+    line_color = "#fbbf24"
+    text_color = "#e2e8f0"
+    
+    svg_parts = [
+        f'<svg width="{width}" height="{height}" xmlns="http://www.w3.org/2000/svg">',
+        f'<rect width="{width}" height="{height}" fill="{bg_color}"/>',
+    ]
+    
+    # Draw roads
+    # Vertical road (North-South)
+    svg_parts.append(
+        f'<rect x="{cx - road_width//2}" y="0" width="{road_width}" height="{height}" fill="{road_color}"/>'
+    )
+    # Horizontal road (East-West)
+    svg_parts.append(
+        f'<rect x="0" y="{cy - road_width//2}" width="{width}" height="{road_width}" fill="{road_color}"/>'
+    )
+    
+    # Draw center intersection
+    svg_parts.append(
+        f'<rect x="{cx - road_width//2}" y="{cy - road_width//2}" width="{road_width}" height="{road_width}" fill="{road_color}"/>'
+    )
+    
+    # Draw lane markings
+    dash_length = 20
+    gap_length = 20
+    for y in range(0, height, dash_length + gap_length):
+        svg_parts.append(
+            f'<rect x="{cx - 2}" y="{y}" width="4" height="{dash_length}" fill="{line_color}" opacity="0.5"/>'
+        )
+    for x in range(0, width, dash_length + gap_length):
+        svg_parts.append(
+            f'<rect x="{x}" y="{cy - 2}" width="{dash_length}" height="4" fill="{line_color}" opacity="0.5"/>'
+        )
+    
+    # Draw stop lines
+    stop_line_offset = road_width // 2 + 10
+    svg_parts.extend([
+        # North stop line
+        f'<line x1="{cx - road_width//2}" y1="{cy - stop_line_offset}" x2="{cx + road_width//2}" y2="{cy - stop_line_offset}" stroke="{line_color}" stroke-width="3"/>',
+        # South stop line
+        f'<line x1="{cx - road_width//2}" y1="{cy + stop_line_offset}" x2="{cx + road_width//2}" y2="{cy + stop_line_offset}" stroke="{line_color}" stroke-width="3"/>',
+        # East stop line
+        f'<line x1="{cx + stop_line_offset}" y1="{cy - road_width//2}" x2="{cx + stop_line_offset}" y2="{cy + road_width//2}" stroke="{line_color}" stroke-width="3"/>',
+        # West stop line
+        f'<line x1="{cx - stop_line_offset}" y1="{cy - road_width//2}" x2="{cx - stop_line_offset}" y2="{cy + road_width//2}" stroke="{line_color}" stroke-width="3"/>',
+    ])
+    
+    # Draw traffic lights
+    light_radius = 12
+    ns_color = get_phase_color(state.current_phase, "NS")
+    ew_color = get_phase_color(state.current_phase, "EW")
+    
+    # North light
+    svg_parts.append(
+        f'<circle cx="{cx + road_width//2 + 20}" cy="{cy - stop_line_offset}" r="{light_radius}" fill="{ns_color}" stroke="white" stroke-width="2"/>'
+    )
+    # South light
+    svg_parts.append(
+        f'<circle cx="{cx - road_width//2 - 20}" cy="{cy + stop_line_offset}" r="{light_radius}" fill="{ns_color}" stroke="white" stroke-width="2"/>'
+    )
+    # East light
+    svg_parts.append(
+        f'<circle cx="{cx + stop_line_offset}" cy="{cy + road_width//2 + 20}" r="{light_radius}" fill="{ew_color}" stroke="white" stroke-width="2"/>'
+    )
+    # West light
+    svg_parts.append(
+        f'<circle cx="{cx - stop_line_offset}" cy="{cy - road_width//2 - 20}" r="{light_radius}" fill="{ew_color}" stroke="white" stroke-width="2"/>'
+    )
+    
+    # Draw vehicles in queues
+    car_width = 24
+    car_height = 36
+    truck_width = 28
+    truck_height = 44
+    
+    def draw_vehicle(x: float, y: float, is_emergency: bool, urgency: int, rotation: int = 0):
+        if is_emergency:
+            # Emergency vehicle (flashing red/blue)
+            flash = "#ef4444" if state.step_count % 4 < 2 else "#3b82f6"
+            return (
+                f'<g transform="translate({x},{y}) rotate({rotation})">'
+                f'<rect x="{-truck_width//2}" y="{-truck_height//2}" width="{truck_width}" height="{truck_height}" rx="4" fill="{flash}" stroke="white" stroke-width="2"/>'
+                f'<text x="0" y="4" text-anchor="middle" fill="white" font-size="10" font-weight="bold">🚨</text>'
+                f'<text x="0" y="{-truck_height//2 - 8}" text-anchor="middle" fill="#ef4444" font-size="12" font-weight="bold">!{urgency}</text>'
+                f'</g>'
+            )
+        else:
+            # Regular car
+            car_colors = ["#60a5fa", "#34d399", "#f472b6", "#fbbf24"]
+            color = car_colors[(int(x) + int(y)) % len(car_colors)]
+            return (
+                f'<g transform="translate({x},{y}) rotate({rotation})">'
+                f'<rect x="{-car_width//2}" y="{-car_height//2}" width="{car_width}" height="{car_height}" rx="3" fill="{color}" stroke="white" stroke-width="1"/>'
+                f'<rect x="{-car_width//2 + 4}" y="{-car_height//2 + 4}" width="{car_width - 8}" height="{car_height//3}" rx="2" fill="#1e293b"/>'
+                f'</g>'
+            )
+    
+    # Draw North queue (approaching from top)
+    nx = cx - lane_width // 2
+    for i in range(min(state.queue_lengths[0], 8)):
+        y = 30 + i * 45
+        svg_parts.append(draw_vehicle(nx, y, False, 0, 180))
+    for i in range(min(state.emergency_queue[0], 2)):
+        y = 30 + (state.queue_lengths[0] + i) * 45
+        urgency = state.emergency_urgency[0] if i == 0 else 5
+        svg_parts.append(draw_vehicle(nx, y, True, urgency, 180))
+    
+    # Draw South queue (approaching from bottom)
+    sx = cx + lane_width // 2
+    for i in range(min(state.queue_lengths[1], 8)):
+        y = height - 30 - i * 45
+        svg_parts.append(draw_vehicle(sx, y, False, 0, 0))
+    for i in range(min(state.emergency_queue[1], 2)):
+        y = height - 30 - (state.queue_lengths[1] + i) * 45
+        urgency = state.emergency_urgency[1] if i == 0 else 5
+        svg_parts.append(draw_vehicle(sx, y, True, urgency, 0))
+    
+    # Draw East queue (approaching from right)
+    ey = cy + lane_width // 2
+    for i in range(min(state.queue_lengths[2], 8)):
+        x = width - 30 - i * 45
+        svg_parts.append(draw_vehicle(x, ey, False, 0, 270))
+    for i in range(min(state.emergency_queue[2], 2)):
+        x = width - 30 - (state.queue_lengths[2] + i) * 45
+        urgency = state.emergency_urgency[2] if i == 0 else 5
+        svg_parts.append(draw_vehicle(x, ey, True, urgency, 270))
+    
+    # Draw West queue (approaching from left)
+    wy = cy - lane_width // 2
+    for i in range(min(state.queue_lengths[3], 8)):
+        x = 30 + i * 45
+        svg_parts.append(draw_vehicle(x, wy, False, 0, 90))
+    for i in range(min(state.emergency_queue[3], 2)):
+        x = 30 + (state.queue_lengths[3] + i) * 45
+        urgency = state.emergency_urgency[3] if i == 0 else 5
+        svg_parts.append(draw_vehicle(x, wy, True, urgency, 90))
+    
+    # Draw labels
+    svg_parts.extend([
+        f'<text x="{width//2}" y="25" text-anchor="middle" fill="{text_color}" font-size="18" font-weight="bold">🚦 Traffic Control Dashboard</text>',
+        f'<text x="15" y="{height//2 - 60}" fill="{text_color}" font-size="14" transform="rotate(-90, 15, {height//2})">West ({state.queue_lengths[3]}🚗 {state.emergency_queue[3]}🚨)</text>',
+        f'<text x="{width - 15}" y="{height//2 - 60}" fill="{text_color}" font-size="14" transform="rotate(90, {width - 15}, {height//2})">East ({state.queue_lengths[2]}🚗 {state.emergency_queue[2]}🚨)</text>',
+        f'<text x="{width//2}" y="{height - 10}" text-anchor="middle" fill="{text_color}" font-size="14">South ({state.queue_lengths[1]}🚗 {state.emergency_queue[1]}🚨)</text>',
+        f'<text x="{width//2}" y="{height - 30}" text-anchor="middle" fill="{text_color}" font-size="14">North ({state.queue_lengths[0]}🚗 {state.emergency_queue[0]}🚨)</text>',
+    ])
+    
+    # Draw stats panel
+    stats_x = 10
+    stats_y = height - 100
+    svg_parts.append(
+        f'<rect x="{stats_x}" y="{stats_y}" width="180" height="90" rx="8" fill="rgba(0,0,0,0.5)" stroke="{text_color}" stroke-width="1"/>'
+    )
+    
+    phase_names = {0: "NS GREEN", 1: "EW GREEN", 2: "ALL RED", 3: "NS YELLOW", 4: "EW YELLOW"}
+    phase_name = phase_names.get(state.current_phase, "UNKNOWN")
+    
+    stats_text = [
+        f"Step: {state.step_count}",
+        f"Phase: {phase_name} ({state.time_in_phase}s)",
+        f"Reward: {state.reward:.2f}",
+        f"Passed: {state.total_vehicles_passed}🚗 {state.total_emergency_passed}🚨",
+    ]
+    
+    for i, line in enumerate(stats_text):
+        svg_parts.append(
+            f'<text x="{stats_x + 10}" y="{stats_y + 20 + i * 20}" fill="{text_color}" font-size="12" font-family="monospace">{line}</text>'
+        )
+    
+    svg_parts.append('</svg>')
+    return '\n'.join(svg_parts)
+
+
+def observation_to_render_state(
+    obs: Dict[str, Any],
+    total_vehicles: int = 0,
+    total_emergency: int = 0,
+    step: int = 0,
+    reward: float = 0.0,
+) -> RenderState:
+    """Convert observation dict to RenderState."""
+    return RenderState(
+        current_phase=obs.get("current_phase", 0),
+        time_in_phase=obs.get("time_in_phase", 0),
+        queue_lengths=obs.get("queue_lengths", [0, 0, 0, 0]),
+        emergency_queue=obs.get("emergency_queue", [0, 0, 0, 0]),
+        emergency_urgency=obs.get("emergency_urgency", [0, 0, 0, 0]),
+        total_vehicles_passed=total_vehicles,
+        total_emergency_passed=total_emergency,
+        step_count=step,
+        reward=reward,
+    )

environment.py

@@ -5,11 +5,12 @@ Implements openenv-core's Environment interface so it works directly
 with create_app() — no adapters needed.
 
 Simulates a 4-way intersection with:
-  - Poisson vehicle arrivals per approach
-  - Emergency vehicles with urgency levels (0-10)
+  - Time-varying traffic wave patterns (sinusoidal arrival rates)
+  - Directional traffic imbalance (rush-hour asymmetry)
+  - Emergency vehicles with urgency levels (0-10) that escalate over time
   - Yellow-light transition state machine (2-step yellow)
   - Traffic-surge events (hard task only)
-  - Multi-objective reward function
+  - Multi-objective reward function aligned with grading weights
 """
 
 from __future__ import annotations
@@ -84,7 +85,7 @@ YELLOW_DURATION = 2
 
 
 # ---------------------------------------------------------------------------
-# Task configurations
+# Task configurations — enhanced with wave/imbalance parameters
 # ---------------------------------------------------------------------------
 
 TASK_CONFIGS: Dict[str, dict] = {
@@ -96,6 +97,12 @@ TASK_CONFIGS: Dict[str, dict] = {
         "max_queue_per_lane":      20,
         "surge_probability":       0.0,
         "surge_multiplier":        1.0,
+        # Wave pattern: sinusoidal variation in arrival rate
+        "wave_amplitude":          0.15,   # ±15% variation
+        "wave_period":             40,     # steps per wave cycle
+        # Directional imbalance: multiplier for NS vs EW
+        "ns_bias":                 1.2,    # NS gets 20% more traffic
+        "ew_bias":                 0.8,
     },
     "emergency_priority": {
         "vehicle_arrival_rate":    0.5,
@@ -105,6 +112,10 @@ TASK_CONFIGS: Dict[str, dict] = {
         "max_queue_per_lane":      20,
         "surge_probability":       0.0,
         "surge_multiplier":        1.0,
+        "wave_amplitude":          0.20,
+        "wave_period":             50,
+        "ns_bias":                 1.0,
+        "ew_bias":                 1.0,
     },
     "dynamic_scenarios": {
         "vehicle_arrival_rate":    0.7,
@@ -114,6 +125,10 @@ TASK_CONFIGS: Dict[str, dict] = {
         "max_queue_per_lane":      30,
         "surge_probability":       0.04,
         "surge_multiplier":        3.0,
+        "wave_amplitude":          0.25,
+        "wave_period":             60,
+        "ns_bias":                 1.3,
+        "ew_bias":                 0.7,
     },
 }
 
@@ -163,6 +178,7 @@ class TrafficControlEnvironment(Environment):
         self._episode_id: str = ""
         self._step_count: int = 0
         self._queues: List[List[Vehicle]] = [[] for _ in range(4)]
+        self._prev_queue_lengths: List[int] = [0, 0, 0, 0]
         self._current_phase: LightPhase = LightPhase.NS_GREEN
         self._time_in_phase: int = 0
         self._pending_phase: Optional[int] = None
@@ -194,6 +210,7 @@ class TrafficControlEnvironment(Environment):
         self._episode_id  = episode_id or str(uuid.uuid4())
         self._step_count  = 0
         self._queues      = [[] for _ in range(4)]
+        self._prev_queue_lengths = [0, 0, 0, 0]
         self._current_phase = LightPhase.NS_GREEN
         self._time_in_phase = 0
         self._pending_phase = None
@@ -211,6 +228,11 @@ class TrafficControlEnvironment(Environment):
         """Execute one simulation step."""
         self._step_count += 1
 
+        # Snapshot queue lengths before this step for trend tracking
+        self._prev_queue_lengths = [
+            len(q) for q in self._queues
+        ]
+
         self._spawn_vehicles()
         phase_changed = self._apply_action(action)
         self._advance_phase()
@@ -249,13 +271,27 @@ class TrafficControlEnvironment(Environment):
     # Simulation internals
     # ------------------------------------------------------------------
 
+    def _get_wave_rate(self, base_rate: float) -> float:
+        """Apply sinusoidal wave pattern to arrival rate."""
+        amp    = self._cfg.get("wave_amplitude", 0.0)
+        period = self._cfg.get("wave_period", 40)
+        if amp <= 0 or period <= 0:
+            return base_rate
+        wave = math.sin(2 * math.pi * self._step_count / period)
+        return max(0.05, base_rate * (1.0 + amp * wave))
+
     def _spawn_vehicles(self) -> None:
-        arr     = self._cfg["vehicle_arrival_rate"]
-        em      = self._cfg["emergency_arrival_rate"]
-        urg     = self._cfg["emergency_urgency_range"]
-        surge_p = self._cfg["surge_probability"]
-        surge_m = self._cfg["surge_multiplier"]
-        max_q   = self._cfg["max_queue_per_lane"]
+        base_arr = self._cfg["vehicle_arrival_rate"]
+        em       = self._cfg["emergency_arrival_rate"]
+        urg      = self._cfg["emergency_urgency_range"]
+        surge_p  = self._cfg["surge_probability"]
+        surge_m  = self._cfg["surge_multiplier"]
+        max_q    = self._cfg["max_queue_per_lane"]
+        ns_bias  = self._cfg.get("ns_bias", 1.0)
+        ew_bias  = self._cfg.get("ew_bias", 1.0)
+
+        # Apply wave pattern
+        arr = self._get_wave_rate(base_arr)
 
         surge_dir   = -1
         surge_extra = 0
@@ -264,7 +300,9 @@ class TrafficControlEnvironment(Environment):
             surge_extra = max(0, int(self._rng.gauss(3, 1) * surge_m))
 
         for d in range(4):
-            n = self._poisson(arr)
+            # Directional bias: NS directions (0,1) vs EW (2,3)
+            dir_bias = ns_bias if d in (0, 1) else ew_bias
+            n = self._poisson(arr * dir_bias)
             if d == surge_dir:
                 n += surge_extra
             for _ in range(n):
@@ -345,6 +383,8 @@ class TrafficControlEnvironment(Environment):
                 v.waiting_time += 1
                 total += 1.0
                 if v.vehicle_type == VehicleType.EMERGENCY:
+                    # Urgency escalates over time — waiting makes it worse
+                    v.urgency = min(10, v.urgency + (1 if v.waiting_time % 5 == 0 else 0))
                     self._total_emergency_delay += 1.0
         return total
 
@@ -362,26 +402,42 @@ class TrafficControlEnvironment(Environment):
         collision: bool,
         phase_changed: bool,
     ) -> float:
-        r  = vehicles_passed  * 0.20
-        r += emergency_passed * 10.0
-        r -= waiting_delta    * 0.05
+        # --- Throughput reward (aligned with grading target ~1.8-2.0 veh/step) ---
+        r  = vehicles_passed  * 0.30
+        r += emergency_passed * 12.0
 
+        # --- Waiting penalty (progressive) ---
+        r -= waiting_delta * 0.08
+
+        # --- Emergency urgency penalty (super-linear: urgency^1.5) ---
         for d in range(4):
             for v in self._queues[d]:
                 if v.vehicle_type == VehicleType.EMERGENCY:
-                    r -= v.urgency * 0.4
+                    r -= (v.urgency ** 1.5) * 0.5
 
+        # --- Collision is catastrophic ---
         if collision:
             r -= 200.0
 
+        # --- Phase change penalty (proportional to wasted switch) ---
         if phase_changed:
             p = int(self._current_phase)
+            new_dir_queue = 0
             if p == PHASE_NS_GREEN:
-                if (len(self._queues[0]) + len(self._queues[1])) == 0:
-                    r -= 0.5
+                new_dir_queue = len(self._queues[0]) + len(self._queues[1])
             elif p == PHASE_EW_GREEN:
-                if (len(self._queues[2]) + len(self._queues[3])) == 0:
-                    r -= 0.5
+                new_dir_queue = len(self._queues[2]) + len(self._queues[3])
+
+            total_queue = sum(len(q) for q in self._queues)
+            if total_queue > 0:
+                empty_ratio = 1.0 - (new_dir_queue / total_queue)
+                r -= 0.5 + empty_ratio * 1.5  # heavier penalty for switching to emptier side
+            else:
+                r -= 0.5
+
+        # --- Stability bonus: reward NOT switching when traffic is flowing ---
+        if not phase_changed and vehicles_passed > 0:
+            r += 0.05
 
         return r
 
@@ -409,6 +465,17 @@ class TrafficControlEnvironment(Environment):
             emergency_queue.append(em)
             emergency_urgency.append(max_u)
 
+        # Compute queue trend (current - previous)
+        current_totals = [len(q) for q in self._queues]
+        queue_trend = [
+            current_totals[i] - self._prev_queue_lengths[i]
+            for i in range(4)
+        ]
+
+        # Compute average wait time
+        all_waits = [v.waiting_time for q in self._queues for v in q]
+        avg_wait = sum(all_waits) / max(len(all_waits), 1) if all_waits else 0.0
+
         return TrafficObservation(
             current_phase=int(self._current_phase),
             time_in_phase=self._time_in_phase,
@@ -417,6 +484,10 @@ class TrafficControlEnvironment(Environment):
             emergency_urgency=emergency_urgency,
             vehicles_passed=vehicles_passed,
             emergency_passed=emergency_passed,
+            avg_wait_time=round(avg_wait, 2),
+            queue_trend=queue_trend,
+            total_vehicles_passed_cumulative=self._total_vehicles_passed,
+            total_emergency_passed_cumulative=self._total_emergency_passed,
             total_waiting_time=waiting_delta,
             collision=collision,
             reward=reward,

inference.py

@@ -1,20 +1,17 @@
 """
 Inference Script — Autonomous Traffic Control OpenEnv Environment
 =================================================================
+Advanced Hybrid Agent: combines optimized rule engine + LLM for ambiguous cases.
+
 Mandatory env variables (injected by validator):
     API_BASE_URL   LLM proxy endpoint (MUST use validator's LiteLLM proxy)
     MODEL_NAME     Model identifier
-    API_KEY        LiteLLM proxy key (MUST use validator's injected key)
+    HF_TOKEN       Hugging Face API token / LiteLLM proxy key
 
 Optional:
     SERVER_URL     Running env server (default: http://localhost:8000)
 
-Usage:
-    API_BASE_URL=<url> API_KEY=<key> python inference.py
-
-CRITICAL: This script REQUIRES API_BASE_URL and API_KEY from environment.
-          No fallbacks or hardcoded values are used.
-          The validator injects these to route calls through LiteLLM proxy.
+Output format: [START], [STEP], [END] lines only (strict protocol compliance)
 """
 
 import os
@@ -48,137 +45,283 @@ except ImportError:
     from models import TrafficAction, TrafficObservation  # type: ignore
 
 # ---------------------------------------------------------------------------
-# Configuration — read from env at import time (matches sample script pattern)
+# Configuration
 # ---------------------------------------------------------------------------
 
-# CRITICAL: Use exact syntax validator requires for static analysis
-API_BASE_URL = os.environ["API_BASE_URL"]
-API_KEY      = os.environ["API_KEY"]
-MODEL_NAME   = os.environ.get("MODEL_NAME", "gpt-4.1-mini")
-SERVER_URL   = os.environ.get("SERVER_URL", "http://localhost:8000")
+API_BASE_URL = os.getenv("API_BASE_URL", "https://api.openai.com/v1")
+MODEL_NAME = os.getenv("MODEL_NAME", "gpt-4.1-mini")
+HF_TOKEN = os.getenv("HF_TOKEN")
+SERVER_URL = os.getenv("SERVER_URL", "http://localhost:8000")
+
+if HF_TOKEN is None:
+    raise ValueError("HF_TOKEN environment variable is required")
 
 SEED        = 42
 MAX_TOKENS  = 64
 TEMPERATURE = 0.0
 
 # ---------------------------------------------------------------------------
-# Prompts
+# Enhanced LLM Prompt — scoring-aware
 # ---------------------------------------------------------------------------
 
 SYSTEM_PROMPT = textwrap.dedent("""
-    You are an Autonomous Traffic Control AI managing a 4-way intersection.
+    You are an elite Autonomous Traffic Control AI managing a 4-way intersection.
 
-    OBJECTIVE: Maximise vehicle throughput and prioritise emergency vehicles.
+    OBJECTIVE: Maximise your SCORE by balancing throughput, emergency response,
+    efficiency, and stability (avoid unnecessary phase switching).
 
     PHASES:
-      0 = North-South Green  (N/S vehicles may pass)
-      1 = East-West Green    (E/W vehicles may pass)
-      2 = All Red            (no vehicles pass — rarely needed)
+      0 = North-South Green  (N/S vehicles may pass, up to 3 per direction per step)
+      1 = East-West Green    (E/W vehicles may pass, up to 3 per direction per step)
+      2 = All Red            (no vehicles pass — use ONLY for emergency clearance)
+
+    SCORING COMPONENTS (what you're graded on):
+      - Throughput: vehicles cleared per step (target ≥ 1.8/step)
+      - Emergency response: clear emergency vehicles FAST (avg delay < 3 steps)
+      - Efficiency: minimize total waiting time
+      - Adaptability: DON'T switch phases too often (penalty for over-switching!)
+      - Stability: staying in a productive phase is rewarded
 
-    DECISION RULES (apply in order):
-      1. EMERGENCY CHECK: If emergency vehicles are waiting (emergency_queue > 0),
-         IMMEDIATELY switch to phase 0 if N/S has emergencies, else phase 1.
-         Urgency 8-10 is critical - act immediately regardless of time_in_phase.
+    CRITICAL RULES (apply in strict order):
+      1. EMERGENCY VEHICLES: If ANY emergency vehicle is waiting (emergency_queue > 0),
+         switch to their direction IMMEDIATELY. Emergency delay is heavily penalized.
+         Higher urgency = more critical. Urgency 8-10 is catastrophic.
 
-      2. MINIMUM PHASE TIME: Stay in current phase at least 3 steps.
-         If time_in_phase < 3, remain in current phase.
+      2. STAY IN PRODUCTIVE PHASE: If current phase is clearing vehicles AND
+         queue has traffic, STAY. Each switch costs 2 yellow steps of zero throughput.
 
-      3. QUEUE BALANCE: After minimum time, compare N/S vs E/W queue depths.
-         - If one direction has 3+ more vehicles than the other, switch to that phase.
-         - If within 2 vehicles, stay in current phase to avoid switch penalty.
+      3. MINIMUM PHASE TIME: Stay at least 3-5 steps in a phase (more for deeper queues).
+         If time_in_phase < 3 and current direction has traffic, STAY.
 
-      4. EMPTY QUEUE: If current direction has 0 vehicles waiting and other direction > 0,
-         switch immediately (no minimum time wait needed).
+      4. SWITCH ON IMBALANCE: Only switch when the OTHER direction has 3+ more
+         vehicles than current direction. Small differences don't justify the switch cost.
 
-    REWARD SIGNALS:
-      - Vehicles passing: +0.2 each
-      - Emergency vehicles passing: +10 each
-      - Phase change with empty queue: -0.5 penalty
-      - Emergency waiting: -0.4 * urgency per step (HUGE penalty)
+      5. EMPTY QUEUE: If current direction queue = 0 and other direction > 0, switch.
 
-    OUTPUT: Reply with exactly one JSON object — no markdown, no explanation:
+      6. NEVER use phase 2 (All Red) unless ALL queues are empty.
+
+    OUTPUT: Exactly one JSON object, no markdown, no explanation:
       {"light_phase": <0, 1, or 2>}
 """).strip()
 
 
-def _build_prompt(obs: TrafficObservation) -> str:
+def _build_prompt(obs: TrafficObservation, step: int, total_rewards: float) -> str:
+    """Build a rich prompt with scoring context for the LLM."""
     q    = obs.queue_lengths
     em_q = obs.emergency_queue
     em_u = obs.emergency_urgency
+
+    # Queue trend info
+    trend = getattr(obs, 'queue_trend', [0, 0, 0, 0])
+    avg_wait = getattr(obs, 'avg_wait_time', 0.0)
+
+    ns_total = q[0] + q[1]
+    ew_total = q[2] + q[3]
+    ns_em_total = em_q[0] + em_q[1]
+    ew_em_total = em_q[2] + em_q[3]
+
     return textwrap.dedent(f"""
+        STEP {step} | Cumulative reward: {total_rewards:.1f}
+
         CURRENT STATE:
-          Active phase      : {obs.current_phase}
+          Active phase      : {obs.current_phase} (0=NS Green, 1=EW Green, 2=All Red)
           Steps in phase    : {obs.time_in_phase}
-          Regular queue     : N={q[0]}, S={q[1]}, E={q[2]}, W={q[3]}
+
+        QUEUES:
+          Regular vehicles  : N={q[0]}, S={q[1]}, E={q[2]}, W={q[3]}
+          → NS total: {ns_total}  |  EW total: {ew_total}  |  Difference: {abs(ns_total - ew_total)}
+          Queue trend (Δ)   : N={trend[0]:+d}, S={trend[1]:+d}, E={trend[2]:+d}, W={trend[3]:+d}
+          Avg wait time     : {avg_wait:.1f} steps
+
+        EMERGENCIES:
           Emergency queue   : N={em_q[0]}, S={em_q[1]}, E={em_q[2]}, W={em_q[3]}
           Emergency urgency : N={em_u[0]}, S={em_u[1]}, E={em_u[2]}, W={em_u[3]}
+          → NS emergencies: {ns_em_total}  |  EW emergencies: {ew_em_total}
 
-        Respond with exactly: {{"light_phase": <0, 1, or 2>}}
+        DECISION: {{"light_phase": <0, 1, or 2>}}
     """).strip()
 
 # ---------------------------------------------------------------------------
-# Rule-based fallback — optimized for high scores
+# Advanced rule-based engine — score-maximizing
 # ---------------------------------------------------------------------------
 
-def _rule_based_action(obs: TrafficObservation) -> TrafficAction:
-    em_q = obs.emergency_queue
-    em_u = obs.emergency_urgency
-    q    = obs.queue_lengths
-    current = obs.current_phase
-    time_in = obs.time_in_phase
+class SmartRuleEngine:
+    """Stateful rule-based agent that tracks history for better decisions."""
+
+    def __init__(self):
+        self.phase_change_count = 0
+        self.total_steps = 0
+        self.last_3_queues: List[List[int]] = []
+
+    def decide(self, obs: TrafficObservation) -> TrafficAction:
+        self.total_steps += 1
+
+        em_q = obs.emergency_queue
+        em_u = obs.emergency_urgency
+        q    = obs.queue_lengths
+        current = obs.current_phase
+        time_in = obs.time_in_phase
+
+        # Track queue history for trend analysis
+        total_q = [q[i] + em_q[i] for i in range(4)]
+        self.last_3_queues.append(total_q)
+        if len(self.last_3_queues) > 3:
+            self.last_3_queues.pop(0)
+
+        # ── Rule 1: EMERGENCY PRIORITY (highest priority, override everything) ──
+        ns_em_score = em_u[0] + em_u[1] + em_q[0] * 3 + em_q[1] * 3
+        ew_em_score = em_u[2] + em_u[3] + em_q[2] * 3 + em_q[3] * 3
+
+        if ns_em_score > 0 or ew_em_score > 0:
+            target = 0 if ns_em_score >= ew_em_score else 1
+            if target != current:
+                self.phase_change_count += 1
+            return TrafficAction(light_phase=target)
+
+        # ── Rule 2: EMPTY CURRENT DIRECTION → instant switch ──
+        ns_total = q[0] + q[1]
+        ew_total = q[2] + q[3]
+
+        if current == 0 and ns_total == 0 and ew_total > 0:
+            self.phase_change_count += 1
+            return TrafficAction(light_phase=1)
+        if current == 1 and ew_total == 0 and ns_total > 0:
+            self.phase_change_count += 1
+            return TrafficAction(light_phase=0)
+
+        # ── Rule 3: DYNAMIC MINIMUM PHASE TIME ──
+        # Deeper queues → stay longer to maximize throughput before switching
+        current_dir_queue = ns_total if current == 0 else ew_total
+        other_dir_queue = ew_total if current == 0 else ns_total
+
+        # Adaptive min time: 3 base + 1 per 4 vehicles, capped at 10
+        min_phase_time = min(3 + current_dir_queue // 4, 10)
+
+        if time_in < min_phase_time and current_dir_queue > 0:
+            return TrafficAction(light_phase=current if current in (0, 1) else 0)
+
+        # ── Rule 4: ADAPTABILITY-AWARE SWITCHING THRESHOLD ──
+        # The more we've already switched, the higher the threshold to switch again
+        switch_rate = self.phase_change_count / max(self.total_steps, 1)
+        # Base threshold is 3 vehicles; increases if we're switching too much
+        switch_threshold = 3 + int(switch_rate * 10)
+
+        if current == 0 and ew_total >= ns_total + switch_threshold:
+            self.phase_change_count += 1
+            return TrafficAction(light_phase=1)
+        elif current == 1 and ns_total >= ew_total + switch_threshold:
+            self.phase_change_count += 1
+            return TrafficAction(light_phase=0)
+
+        # ── Rule 5: QUEUE TREND ANALYSIS ──
+        # If other direction's queue is growing fast (trend > 0 for last 3 steps)
+        if len(self.last_3_queues) >= 3:
+            if current == 0:
+                ew_growing = all(
+                    self.last_3_queues[i][2] + self.last_3_queues[i][3] <=
+                    self.last_3_queues[i+1][2] + self.last_3_queues[i+1][3]
+                    for i in range(len(self.last_3_queues) - 1)
+                )
+                if ew_growing and ew_total > ns_total and time_in >= 3:
+                    self.phase_change_count += 1
+                    return TrafficAction(light_phase=1)
+            elif current == 1:
+                ns_growing = all(
+                    self.last_3_queues[i][0] + self.last_3_queues[i][1] <=
+                    self.last_3_queues[i+1][0] + self.last_3_queues[i+1][1]
+                    for i in range(len(self.last_3_queues) - 1)
+                )
+                if ns_growing and ns_total > ew_total and time_in >= 3:
+                    self.phase_change_count += 1
+                    return TrafficAction(light_phase=0)
+
+        # ── Default: STAY in current phase for stability bonus ──
+        return TrafficAction(light_phase=current if current in (0, 1) else 0)
+
+
+# ---------------------------------------------------------------------------
+# Sanitize error strings
+# ---------------------------------------------------------------------------
+
+def _sanitize(s: str) -> str:
+    """Strip newlines, carriage returns, and problematic characters for output."""
+    return s.replace('\n', ' ').replace('\r', ' ').replace('"', "'").replace('\\', '')
+
+# ---------------------------------------------------------------------------
+# LLM action with smart fallback
+# ---------------------------------------------------------------------------
 
-    # Emergency prioritization: urgency-weighted score per direction
-    ns_em_urgency = em_u[0] + em_u[1] + em_q[0] * 2 + em_q[1] * 2
-    ew_em_urgency = em_u[2] + em_u[3] + em_q[2] * 2 + em_q[3] * 2
+_rule_engine = SmartRuleEngine()
 
-    if ns_em_urgency > 0 or ew_em_urgency > 0:
-        # Emergency waiting - switch immediately to help them
-        return TrafficAction(light_phase=0 if ns_em_urgency >= ew_em_urgency else 1)
 
-    # No emergencies - use queue depth with hysteresis
+def get_llm_action(
+    client: OpenAI,
+    obs: TrafficObservation,
+    step: int,
+    total_rewards: float,
+) -> TrafficAction:
+    """
+    Hybrid approach:
+    - Use rules for clear-cut decisions (saves API calls + faster)
+    - Use LLM for ambiguous situations (close queues, complex emergencies)
+    """
+    q    = obs.queue_lengths
+    em_q = obs.emergency_queue
+    current = obs.current_phase
+
     ns_total = q[0] + q[1]
     ew_total = q[2] + q[3]
+    ns_em = sum(em_q[0:2])
+    ew_em = sum(em_q[2:4])
+    diff = abs(ns_total - ew_total)
 
-    # Dynamic minimum phase time based on queue depth (deeper queues = stay longer)
-    min_phase_time = min(3 + max(ns_total, ew_total) // 5, 8)
-
-    # Stay in current phase if below min time and still has traffic
-    if current == 0 and time_in < min_phase_time and ns_total > 0:
-        return TrafficAction(light_phase=0)
-    if current == 1 and time_in < min_phase_time and ew_total > 0:
-        return TrafficAction(light_phase=1)
-
-    # Switch to direction with more traffic (with 2-vehicle hysteresis to prevent flip-flopping)
-    if ns_total >= ew_total + 2:
-        return TrafficAction(light_phase=0)
-    elif ew_total >= ns_total + 2:
-        return TrafficAction(light_phase=1)
-    else:
-        # Within 2 vehicles - stay in current phase to avoid switch penalty
-        return TrafficAction(light_phase=current if current in (0, 1) else 0)
+    # ── FAST PATH: clear-cut decisions → use rules (no LLM call needed) ──
 
-# ---------------------------------------------------------------------------
-# LLM action — client passed in from main() (created once with env-level vars)
-# ---------------------------------------------------------------------------
+    # Emergency vehicles → always rules (speed critical, don't wait for LLM)
+    if ns_em > 0 or ew_em > 0:
+        return _rule_engine.decide(obs)
 
-def get_llm_action(client: OpenAI, obs: TrafficObservation) -> TrafficAction:
-    print(f"[DEBUG] Making LLM call to {API_BASE_URL} with model {MODEL_NAME}", flush=True)
-    resp = client.chat.completions.create(
-        model=MODEL_NAME,
-        messages=[
-            {"role": "system", "content": SYSTEM_PROMPT},
-            {"role": "user",   "content": _build_prompt(obs)},
-        ],
-        temperature=TEMPERATURE,
-        max_tokens=MAX_TOKENS,
-        stream=False,
-    )
-    print(f"[DEBUG] LLM response received", flush=True)
-    data_str = (resp.choices[0].message.content or "").strip()
-    match = re.search(r'\{[^}]*\}', data_str.replace('\n', ' '))
-    data  = json.loads(match.group(0) if match else data_str)
-    phase = max(0, min(2, int(data.get("light_phase", obs.current_phase))))
-    return TrafficAction(light_phase=phase)
+    # Empty current direction → obvious switch
+    if current == 0 and ns_total == 0 and ew_total > 0:
+        return _rule_engine.decide(obs)
+    if current == 1 and ew_total == 0 and ns_total > 0:
+        return _rule_engine.decide(obs)
+
+    # Large imbalance → obvious switch
+    if diff >= 5:
+        return _rule_engine.decide(obs)
+
+    # Very early in phase → obviously stay
+    if obs.time_in_phase < 3:
+        return _rule_engine.decide(obs)
+
+    # ── SLOW PATH: ambiguous situation → ask LLM ──
+    try:
+        resp = client.chat.completions.create(
+            model=MODEL_NAME,
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user",   "content": _build_prompt(obs, step, total_rewards)},
+            ],
+            temperature=TEMPERATURE,
+            max_tokens=MAX_TOKENS,
+            stream=False,
+            timeout=30,
+        )
+        data_str = (resp.choices[0].message.content or "").strip()
+        match = re.search(r'\{[^}]*\}', data_str.replace('\n', ' '))
+        data  = json.loads(match.group(0) if match else data_str)
+        phase = max(0, min(2, int(data.get("light_phase", obs.current_phase))))
+
+        # Update rule engine state even when using LLM
+        _rule_engine.total_steps += 1
+        if phase != current:
+            _rule_engine.phase_change_count += 1
+
+        return TrafficAction(light_phase=phase)
+    except Exception:
+        # LLM failed — use optimized rule-based agent as fallback
+        return _rule_engine.decide(obs)
 
 # ---------------------------------------------------------------------------
 # Grade fetcher
@@ -211,65 +354,72 @@ def _fetch_score(task_id: str, state_payload: dict) -> float:
 # ---------------------------------------------------------------------------
 
 def run_task(task_id: str, client: OpenAI) -> None:
-    print(f"[START] task={task_id} env=traffic-control model={MODEL_NAME}", flush=True)
+    global _rule_engine
+    _rule_engine = SmartRuleEngine()  # Fresh engine per task
+
+    print(f"[START] task={task_id} env=traffic_control model={MODEL_NAME}", flush=True)
 
     rewards: List[float] = []
     success = False
+    step = 0
+    total_rewards = 0.0
 
     try:
         with TrafficControlEnv(base_url=SERVER_URL).sync() as env:
             step_result = env.reset(task_id=task_id, seed=SEED)
-            step = 1
+            step = 0
+            broke_on_error = False
 
             while not step_result.done:
-                obs       = step_result.observation
-                error_msg: Optional[str] = None
-
-                action = get_llm_action(client, obs)
+                obs = step_result.observation
+                step += 1
 
-                action_str = f"TrafficAction(light_phase={action.light_phase})"
+                action = get_llm_action(client, obs, step, total_rewards)
+                action_str = f"light_phase({action.light_phase})"
 
                 try:
                     step_result = env.step(action)
-                    reward_val  = step_result.reward if step_result.reward is not None else 0.0
+                    reward_val = step_result.reward if step_result.reward is not None else 0.0
                     rewards.append(reward_val)
-                    done_val    = str(step_result.done).lower()
-                    error_val   = error_msg if error_msg else "null"
+                    total_rewards += reward_val
+                    done_val = str(step_result.done).lower()
+
+                    error_val = "null"
+                    if hasattr(step_result, 'info') and step_result.info:
+                        err = step_result.info.get('error')
+                        if err:
+                            error_val = _sanitize(str(err))
+
                     print(
                         f"[STEP] step={step} action={action_str} "
                         f"reward={reward_val:.2f} done={done_val} error={error_val}",
                         flush=True,
                     )
                 except Exception as exc:
-                    env_err = str(exc).replace('"', "'").replace("\\", "")
+                    env_err = _sanitize(str(exc))
+                    rewards.append(0.0)
                     print(
                         f"[STEP] step={step} action={action_str} "
                         f"reward=0.00 done=true error={env_err}",
                         flush=True,
                     )
+                    broke_on_error = True
                     break
 
-                step += 1
-
-            success = True
+            success = not broke_on_error
 
     except Exception as exc:
-        print(f"[STEP] step=0 action=none reward=0.00 done=true error={exc}", flush=True)
+        err_msg = _sanitize(str(exc))
+        if step == 0:
+            step = 1
+            rewards.append(0.0)
+            print(f"[STEP] step=1 action=null reward=0.00 done=true error={err_msg}", flush=True)
         success = False
 
     rewards_str = ",".join(f"{r:.2f}" for r in rewards) if rewards else "0.00"
 
-    score = 0.5
-    try:
-        state_resp = _http.get(f"{SERVER_URL}/state", timeout=10)
-        if state_resp.status_code == 200:
-            score = _fetch_score(task_id, state_resp.json())
-    except Exception:
-        pass
-
     print(
-        f"[END] success={str(success).lower()} steps={len(rewards)} "
-        f"score={score:.3f} rewards={rewards_str}",
+        f"[END] success={str(success).lower()} steps={step} rewards={rewards_str}",
         flush=True,
     )
 
@@ -278,35 +428,17 @@ def run_task(task_id: str, client: OpenAI) -> None:
 # ---------------------------------------------------------------------------
 
 def main() -> None:
-    # Debug: show env var status with explicit length check
-    print(
-        f"[CONFIG] API_BASE_URL={API_BASE_URL} (len={len(API_BASE_URL)}) "
-        f"API_KEY={API_KEY[:10]}... (len={len(API_KEY)}) "
-        f"MODEL_NAME={MODEL_NAME}",
-        flush=True,
-    )
-    
-    # Ensure env vars are not empty
-    if not API_BASE_URL or not API_KEY:
-        raise SystemExit(f"[FATAL] Empty env vars: API_BASE_URL='{API_BASE_URL}', API_KEY empty={not API_KEY}")
-
-    # Create the OpenAI client once using module-level env vars
-    client = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
-    
-    # Verify the client is configured correctly by making a test call
-    try:
-        _ = client.chat.completions.create(
-            model=MODEL_NAME,
-            messages=[{"role": "user", "content": "test"}],
-            max_tokens=1,
-        )
-    except Exception as e:
-        print(f"[WARN] Test call failed: {e}", flush=True)
+    client = OpenAI(base_url=API_BASE_URL, api_key=HF_TOKEN)
 
     for task in ["basic_flow", "emergency_priority", "dynamic_scenarios"]:
         run_task(task, client)
-        print(flush=True)
 
 
 if __name__ == "__main__":
-    main()
+    try:
+        main()
+    except Exception as exc:
+        err = _sanitize(str(exc))
+        print(f"[START] task=unknown env=traffic_control model={MODEL_NAME}", flush=True)
+        print(f"[STEP] step=1 action=null reward=0.00 done=true error={err}", flush=True)
+        print(f"[END] success=false steps=1 rewards=0.00", flush=True)

models.py

@@ -87,6 +87,24 @@ class TrafficObservation(Observation):
     vehicles_passed: int = Field(default=0, description="Regular vehicles cleared this step")
     emergency_passed: int = Field(default=0, description="Emergency vehicles cleared this step")
 
+    # -- Trend & context fields --
+    avg_wait_time: float = Field(
+        default=0.0,
+        description="Average waiting time across all queued vehicles this step",
+    )
+    queue_trend: List[int] = Field(
+        default_factory=lambda: [0, 0, 0, 0],
+        description="Queue growth since last step per approach [N,S,E,W] (positive=growing)",
+    )
+    total_vehicles_passed_cumulative: int = Field(
+        default=0,
+        description="Cumulative regular vehicles cleared this episode",
+    )
+    total_emergency_passed_cumulative: int = Field(
+        default=0,
+        description="Cumulative emergency vehicles cleared this episode",
+    )
+
     # -- Penalty signals --
     total_waiting_time: float = Field(
         default=0.0,

pyproject.toml

@@ -35,5 +35,5 @@ server = "traffic_control.server.app:main"
 include-package-data = true
 
 [tool.setuptools.packages.find]
-where = [".."]
+where = ["."]
 include = ["traffic_control*"]

server/app.py

@@ -33,13 +33,18 @@ for _p in (_PKG_DIR, _ROOT):
     if _p not in sys.path:
         sys.path.insert(0, _p)
 
+from typing import Optional
 from openenv.core.env_server.http_server import create_app
 from fastapi import Request
+from fastapi.responses import HTMLResponse
 
 # All imports from within traffic_control/ only
 from traffic_control.models import TrafficAction, TrafficObservation
 from traffic_control.environment import TrafficControlEnvironment
 from traffic_control.tasks import grade as run_grader
+from traffic_control.dashboard import render_intersection, observation_to_render_state
+from traffic_control.analytics import get_history
+from traffic_control.arena import get_arena
 
 
 # ---------------------------------------------------------------------------
@@ -108,6 +113,455 @@ async def grade(request: Request):
     }
 
 
+# ---------------------------------------------------------------------------
+# Dashboard endpoints
+# ---------------------------------------------------------------------------
+
+@app.get("/dashboard", tags=["dashboard"])
+async def dashboard():
+    """Serve the live dashboard HTML page."""
+    html_content = '''<!DOCTYPE html>
+<html>
+<head>
+    <title>Traffic Control Dashboard</title>
+    <style>
+        body {
+            font-family: system-ui, -apple-system, sans-serif;
+            background: #0f172a;
+            color: #e2e8f0;
+            margin: 0;
+            padding: 20px;
+            min-height: 100vh;
+        }
+        .container {
+            max-width: 1200px;
+            margin: 0 auto;
+        }
+        h1 {
+            text-align: center;
+            margin-bottom: 10px;
+        }
+        .controls {
+            display: flex;
+            gap: 10px;
+            justify-content: center;
+            margin-bottom: 20px;
+            flex-wrap: wrap;
+        }
+        button, select {
+            padding: 10px 20px;
+            font-size: 14px;
+            border-radius: 6px;
+            border: none;
+            cursor: pointer;
+        }
+        button {
+            background: #3b82f6;
+            color: white;
+        }
+        button:hover {
+            background: #2563eb;
+        }
+        select {
+            background: #1e293b;
+            color: #e2e8f0;
+            border: 1px solid #475569;
+        }
+        .dashboard-container {
+            display: grid;
+            grid-template-columns: 1fr 300px;
+            gap: 20px;
+        }
+        .visualization {
+            background: #1e293b;
+            border-radius: 12px;
+            padding: 20px;
+        }
+        .visualization svg {
+            width: 100%;
+            height: auto;
+            border-radius: 8px;
+        }
+        .stats-panel {
+            background: #1e293b;
+            border-radius: 12px;
+            padding: 20px;
+        }
+        .stat-item {
+            margin-bottom: 15px;
+            padding: 12px;
+            background: #0f172a;
+            border-radius: 8px;
+        }
+        .stat-label {
+            font-size: 12px;
+            color: #94a3b8;
+            text-transform: uppercase;
+        }
+        .stat-value {
+            font-size: 24px;
+            font-weight: bold;
+            color: #22c55e;
+        }
+        .stat-value.warning {
+            color: #eab308;
+        }
+        .stat-value.danger {
+            color: #ef4444;
+        }
+        .phase-indicator {
+            display: inline-block;
+            padding: 4px 12px;
+            border-radius: 20px;
+            font-size: 12px;
+            font-weight: bold;
+        }
+        .phase-ns { background: #22c55e; color: #064e3b; }
+        .phase-ew { background: #3b82f6; color: #1e3a8a; }
+        .phase-red { background: #ef4444; color: #7f1d1d; }
+        .queue-bar {
+            height: 8px;
+            background: #334155;
+            border-radius: 4px;
+            margin-top: 5px;
+            overflow: hidden;
+        }
+        .queue-fill {
+            height: 100%;
+            background: linear-gradient(90deg, #22c55e, #eab308, #ef4444);
+            transition: width 0.3s;
+        }
+        .auto-toggle {
+            display: flex;
+            align-items: center;
+            gap: 10px;
+            justify-content: center;
+            margin-top: 10px;
+        }
+        .toggle-switch {
+            position: relative;
+            width: 50px;
+            height: 24px;
+            background: #475569;
+            border-radius: 12px;
+            cursor: pointer;
+            transition: background 0.3s;
+        }
+        .toggle-switch.active {
+            background: #22c55e;
+        }
+        .toggle-slider {
+            position: absolute;
+            top: 2px;
+            left: 2px;
+            width: 20px;
+            height: 20px;
+            background: white;
+            border-radius: 50%;
+            transition: transform 0.3s;
+        }
+        .toggle-switch.active .toggle-slider {
+            transform: translateX(26px);
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>🚦 Autonomous Traffic Control Dashboard</h1>
+        
+        <div class="controls">
+            <select id="taskSelect">
+                <option value="basic_flow">Basic Flow</option>
+                <option value="emergency_priority">Emergency Priority</option>
+                <option value="dynamic_scenarios">Dynamic Scenarios</option>
+            </select>
+            <button onclick="resetEnv()">🔄 Reset</button>
+            <button onclick="stepOnce()">▶️ Step Once</button>
+            <div class="auto-toggle">
+                <span>Auto Run</span>
+                <div class="toggle-switch" id="autoToggle" onclick="toggleAuto()">
+                    <div class="toggle-slider"></div>
+                </div>
+            </div>
+            <button onclick="setPhase(0)">🟢 NS Green</button>
+            <button onclick="setPhase(1)">🟢 EW Green</button>
+            <button onclick="setPhase(2)">🔴 All Red</button>
+        </div>
+        
+        <div class="dashboard-container">
+            <div class="visualization">
+                <div id="svgContainer">Loading...</div>
+            </div>
+            
+            <div class="stats-panel">
+                <h3>📊 Live Statistics</h3>
+                
+                <div class="stat-item">
+                    <div class="stat-label">Current Phase</div>
+                    <div id="phaseValue" class="stat-value">-</div>
+                </div>
+                
+                <div class="stat-item">
+                    <div class="stat-label">Step Count</div>
+                    <div id="stepValue" class="stat-value">0</div>
+                </div>
+                
+                <div class="stat-item">
+                    <div class="stat-label">Total Reward</div>
+                    <div id="rewardValue" class="stat-value">0.00</div>
+                </div>
+                
+                <div class="stat-item">
+                    <div class="stat-label">Vehicles Passed</div>
+                    <div id="vehiclesValue" class="stat-value">0</div>
+                </div>
+                
+                <div class="stat-item">
+                    <div class="stat-label">Emergency Vehicles</div>
+                    <div id="emergencyValue" class="stat-value">0</div>
+                </div>
+                
+                <div class="stat-item">
+                    <div class="stat-label">Queue Depths</div>
+                    <div id="queueValue" style="font-size: 14px;">N:0 S:0 E:0 W:0</div>
+                    <div class="queue-bar">
+                        <div class="queue-fill" id="queueBar" style="width: 0%"></div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <script>
+        let autoRunning = false;
+        let autoInterval = null;
+        let totalReward = 0;
+        let totalVehicles = 0;
+        let totalEmergency = 0;
+        let stepCount = 0;
+        
+        async function resetEnv() {
+            const task = document.getElementById('taskSelect').value;
+            try {
+                await fetch('/reset', {
+                    method: 'POST',
+                    headers: {'Content-Type': 'application/json'},
+                    body: JSON.stringify({task_id: task, seed: 42})
+                });
+                totalReward = 0;
+                totalVehicles = 0;
+                totalEmergency = 0;
+                stepCount = 0;
+                updateDashboard();
+            } catch (e) {
+                console.error('Reset failed:', e);
+            }
+        }
+        
+        async function stepOnce() {
+            try {
+                const response = await fetch('/step', {
+                    method: 'POST',
+                    headers: {'Content-Type': 'application/json'},
+                    body: JSON.stringify({action: {light_phase: 0}})
+                });
+                const data = await response.json();
+                updateStats(data);
+                updateDashboard();
+            } catch (e) {
+                console.error('Step failed:', e);
+            }
+        }
+        
+        async function setPhase(phase) {
+            try {
+                const response = await fetch('/step', {
+                    method: 'POST',
+                    headers: {'Content-Type': 'application/json'},
+                    body: JSON.stringify({action: {light_phase: phase}})
+                });
+                const data = await response.json();
+                updateStats(data);
+                updateDashboard();
+            } catch (e) {
+                console.error('Set phase failed:', e);
+            }
+        }
+        
+        function toggleAuto() {
+            autoRunning = !autoRunning;
+            document.getElementById('autoToggle').classList.toggle('active', autoRunning);
+            
+            if (autoRunning) {
+                autoInterval = setInterval(stepOnce, 1000);
+            } else {
+                clearInterval(autoInterval);
+            }
+        }
+        
+        function updateStats(data) {
+            if (data.reward) totalReward += data.reward;
+            if (data.metadata && data.metadata.vehicles_passed) {
+                totalVehicles = data.metadata.total_vehicles_passed || totalVehicles;
+                totalEmergency = data.metadata.total_emergency_passed || totalEmergency;
+            }
+            stepCount++;
+            
+            document.getElementById('stepValue').textContent = stepCount;
+            document.getElementById('rewardValue').textContent = totalReward.toFixed(2);
+            document.getElementById('vehiclesValue').textContent = totalVehicles;
+            document.getElementById('emergencyValue').textContent = totalEmergency;
+            
+            if (data.observation) {
+                const obs = data.observation;
+                const phaseNames = {0: 'NS GREEN', 1: 'EW GREEN', 2: 'ALL RED', 3: 'NS YELLOW', 4: 'EW YELLOW'};
+                document.getElementById('phaseValue').textContent = phaseNames[obs.current_phase] || 'UNKNOWN';
+                
+                const queues = obs.queue_lengths;
+                const totalQueue = queues.reduce((a, b) => a + b, 0) + obs.emergency_queue.reduce((a, b) => a + b, 0);
+                document.getElementById('queueValue').textContent = `N:${queues[0]} S:${queues[1]} E:${queues[2]} W:${queues[3]}`;
+                document.getElementById('queueBar').style.width = Math.min(totalQueue * 5, 100) + '%';
+            }
+        }
+        
+        async function updateDashboard() {
+            try {
+                const response = await fetch('/state');
+                const state = await response.json();
+                
+                const svgResponse = await fetch('/dashboard/svg', {
+                    method: 'POST',
+                    headers: {'Content-Type': 'application/json'},
+                    body: JSON.stringify(state)
+                });
+                const svgData = await svgResponse.json();
+                document.getElementById('svgContainer').innerHTML = svgData.svg;
+            } catch (e) {
+                console.error('Dashboard update failed:', e);
+            }
+        }
+        
+        // Initial load
+        resetEnv();
+    </script>
+</body>
+</html>'''
+    return HTMLResponse(content=html_content)
+
+
+@app.post("/dashboard/svg", tags=["dashboard"])
+async def dashboard_svg(request: Request):
+    """Generate SVG visualization from current state."""
+    try:
+        state_data = await request.json()
+        render_state = observation_to_render_state(
+            state_data.get("observation", {}),
+            total_vehicles=state_data.get("total_vehicles_passed", 0),
+            total_emergency=state_data.get("total_emergency_passed", 0),
+            step=state_data.get("step_count", 0),
+            reward=state_data.get("reward", 0.0),
+        )
+        svg = render_intersection(render_state)
+        return {"svg": svg}
+    except Exception as e:
+        return {"error": str(e), "svg": ""}
+
+
+# ---------------------------------------------------------------------------
+# Analytics endpoints
+# ---------------------------------------------------------------------------
+
+@app.get("/analytics/summary", tags=["analytics"])
+async def analytics_summary(task_id: Optional[str] = None):
+    """Get summary statistics of all recorded episodes."""
+    return get_history().get_summary(task_id)
+
+
+@app.get("/analytics/episodes", tags=["analytics"])
+async def list_episodes():
+    """List all recorded episodes."""
+    history = get_history()
+    return {
+        "episodes": [
+            {
+                "episode_id": e.episode_id,
+                "task_id": e.task_id,
+                "steps": e.steps,
+                "total_reward": round(e.total_reward, 2),
+                "avg_reward_per_step": round(e.avg_reward_per_step, 4),
+            }
+            for e in history.episodes
+        ]
+    }
+
+
+@app.get("/analytics/episodes/{episode_id}", tags=["analytics"])
+async def get_episode(episode_id: str):
+    """Get detailed metrics for a specific episode."""
+    details = get_history().get_episode_details(episode_id)
+    if details:
+        return details
+    return {"error": "Episode not found"}
+
+
+# ---------------------------------------------------------------------------
+# Arena endpoints
+# ---------------------------------------------------------------------------
+
+@app.post("/arena/run", tags=["arena"])
+async def arena_run(request: Request):
+    """Run agent comparison in the arena."""
+    body = {}
+    try:
+        body = await request.json()
+    except Exception:
+        pass
+    
+    task_id = body.get("task_id", "basic_flow")
+    agents = body.get("agents", None)  # List of agent types or None for all
+    runs_per_agent = int(body.get("runs_per_agent", 1))
+    
+    arena = get_arena()
+    result = await arena.run_comparison(
+        task_id=task_id,
+        agents=agents,
+        runs_per_agent=runs_per_agent,
+    )
+    return result
+
+
+@app.get("/arena/agents", tags=["arena"])
+async def list_agents():
+    """List available agents in the arena."""
+    return {
+        "agents": [
+            {"id": "llm", "name": "Dynamic LLM Agent", "description": "Makes live LLM API calls for each decision"},
+            {"id": "rule_based", "name": "Smart Rule-Based", "description": "Optimized rule-based controller"},
+            {"id": "random", "name": "Random Baseline", "description": "Random action selector"},
+            {"id": "round_robin", "name": "Round Robin", "description": "Simple alternating controller"},
+        ]
+    }
+
+
+@app.get("/arena/results", tags=["arena"])
+async def arena_results():
+    """Get all historical arena results."""
+    arena = get_arena()
+    return {
+        "total_comparisons": len(arena.results),
+        "recent_results": [
+            {
+                "agent": r.agent_type,
+                "episode": r.episode_id,
+                "score": r.score,
+                "reward": round(r.total_reward, 2),
+                "steps": r.steps,
+            }
+            for r in arena.results[-20:]
+        ],
+    }
+
+
 # ---------------------------------------------------------------------------
 # 3. Gradio UI (mounted at /ui)
 # ---------------------------------------------------------------------------

tasks.py

@@ -7,6 +7,15 @@ Defines three tasks of increasing difficulty:
   3. dynamic_scenarios   – surge-traffic + emergencies under hard constraints (Hard)
 
 Each grader returns a GradeResult(score, metrics, feedback) with 0–1 score.
+
+Scoring dimensions:
+  - Throughput       : vehicles cleared per step
+  - Efficiency       : low total waiting time
+  - Emergency rate   : emergency vehicles cleared per step
+  - Emergency delay  : average delay per emergency vehicle
+  - Adaptability     : not over-switching phases
+  - Consistency      : steady throughput (low variance) — BONUS
+  - Queue balance    : not letting one direction starve — BONUS
 """
 
 from __future__ import annotations
@@ -77,6 +86,7 @@ def _grade_basic_flow(
     total_vehicles_passed: int,
     total_waiting_time: float,
     total_collisions: int,
+    total_phase_changes: int,
     step_count: int,
     **_ignored,
 ) -> GradeResult:
@@ -85,21 +95,27 @@ def _grade_basic_flow(
     efficiency_score    = 1.0 / (1.0 + total_waiting_time / max(step_count, 1) * 0.1)
     collision_penalty   = 0.8 if total_collisions > 0 else 0.0
 
-    raw   = throughput_score * 0.6 + efficiency_score * 0.4
+    # BONUS: Queue balance — penalize excessive phase switching (shows instability)
+    switch_rate = total_phase_changes / max(step_count, 1)
+    stability_bonus = max(0.0, 0.05 * (1.0 - min(switch_rate * 4, 1.0)))
+
+    raw   = throughput_score * 0.6 + efficiency_score * 0.4 + stability_bonus
     score = max(0.0, raw - collision_penalty)
 
     return GradeResult(
-        score=_clamp(raw - collision_penalty),
+        score=_clamp(score),
         metrics={
             "throughput_per_step": round(throughput_per_step, 3),
             "throughput_score":    round(throughput_score,    4),
             "efficiency_score":    round(efficiency_score,    4),
+            "stability_bonus":     round(stability_bonus,     4),
             "total_collisions":    total_collisions,
             "collision_penalty":   collision_penalty,
         },
         feedback=(
             f"Throughput {throughput_per_step:.2f} veh/step "
             f"(target {_BASIC_FLOW_TARGET_THROUGHPUT_PER_STEP}). "
+            f"Phase switches: {total_phase_changes} ({switch_rate:.2f}/step). "
             + ("⚠ Collision penalty applied!" if total_collisions else "No collisions ✓.")
         ),
     )
@@ -139,8 +155,17 @@ def _grade_emergency_priority(
     efficiency_score  = 1.0 / (1.0 + total_waiting_time / max(step_count, 1) * 0.05)
     collision_penalty = 0.85 if total_collisions > 0 else 0.0
 
+    # BONUS: emergency response quality
+    response_bonus = 0.0
+    if total_emergency_passed > 0:
+        avg_em_delay = total_emergency_delay / total_emergency_passed
+        if avg_em_delay < 2.0:
+            response_bonus = 0.05  # exceptional response time
+        elif avg_em_delay < 4.0:
+            response_bonus = 0.02
+
     raw   = (throughput_score * 0.30 + em_rate_score * 0.35 +
-             delay_score      * 0.20 + efficiency_score * 0.15)
+             delay_score      * 0.20 + efficiency_score * 0.15 + response_bonus)
     score = max(0.0, raw - collision_penalty)
 
     avg_delay_str = (
@@ -149,13 +174,14 @@ def _grade_emergency_priority(
     )
 
     return GradeResult(
-        score=_clamp(raw - collision_penalty),
+        score=_clamp(score),
         metrics={
             "throughput_per_step":       round(throughput_per_step, 3),
             "throughput_score":          round(throughput_score,    4),
             "emergency_rate_score":      round(em_rate_score,       4),
             "emergency_delay_score":     round(delay_score,         4),
             "efficiency_score":          round(efficiency_score,    4),
+            "response_bonus":            round(response_bonus,      4),
             "total_emergency_passed":    total_emergency_passed,
             "avg_emergency_delay_steps": avg_delay_str,
             "total_collisions":          total_collisions,
@@ -164,6 +190,7 @@ def _grade_emergency_priority(
             f"Cleared {total_emergency_passed} emergency vehicles "
             f"(avg delay {avg_delay_str}). "
             f"Throughput {throughput_per_step:.2f} veh/step. "
+            + (f"🏆 Fast response bonus +{response_bonus:.0%}! " if response_bonus > 0 else "")
             + ("⚠ Collision!" if total_collisions else "No collisions ✓.")
         ),
     )
@@ -200,13 +227,20 @@ def _grade_dynamic_scenarios(
     adaptability_score = 1.0 / (1.0 + total_phase_changes / max(step_count, 1) * 0.5)
     collision_penalty  = 0.9 if total_collisions > 0 else 0.0
 
+    # BONUS: queue balance + surge resilience
+    surge_bonus = 0.0
+    if total_vehicles_passed > step_count * 1.5:
+        surge_bonus = 0.03  # handled high traffic well
+    if total_emergency_passed > 0 and total_collisions == 0:
+        surge_bonus += 0.02  # survived with zero collisions
+
     raw   = (throughput_score    * 0.25 + em_rate_score   * 0.30 +
              delay_score         * 0.20 + efficiency_score * 0.15 +
-             adaptability_score  * 0.10)
+             adaptability_score  * 0.10 + surge_bonus)
     score = max(0.0, raw - collision_penalty)
 
     return GradeResult(
-        score=_clamp(raw - collision_penalty),
+        score=_clamp(score),
         metrics={
             "throughput_per_step":   round(throughput_per_step, 3),
             "throughput_score":      round(throughput_score,    4),
@@ -214,6 +248,7 @@ def _grade_dynamic_scenarios(
             "emergency_delay_score": round(delay_score,         4),
             "efficiency_score":      round(efficiency_score,    4),
             "adaptability_score":    round(adaptability_score,  4),
+            "surge_bonus":           round(surge_bonus,         4),
             "total_collisions":      total_collisions,
             "total_phase_changes":   total_phase_changes,
         },
@@ -221,6 +256,7 @@ def _grade_dynamic_scenarios(
             f"Dynamic task: throughput {throughput_per_step:.2f} veh/step, "
             f"{total_emergency_passed} emergencies cleared, "
             f"{total_phase_changes} phase changes over {step_count} steps. "
+            + (f"🏆 Surge resilience bonus +{surge_bonus:.0%}! " if surge_bonus > 0 else "")
             + ("⚠ Collision!" if total_collisions else "No collisions ✓.")
         ),
     )