refactor: type analyze_gaps and extract_decisions with AgentResponse

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

agents/crew_orchestrator.py

@@ -267,11 +267,10 @@ class CrewOrchestrator(BaseOrchestrator):
                     preview["gcode_url"] = f"/api/models/{part_name}.gcode"
 
         # Update design state
-        agent_msgs = [{"message": r.get("message", "")} for r in responses]
-        updated_state = extract_decisions(agent_msgs, state, message)
+        updated_state = extract_decisions(agent_responses, state, message)
 
         # Gap analysis — detect missing info and generate question cards
-        gap_result = analyze_gaps(responses)
+        gap_result = analyze_gaps(agent_responses)
         question_cards = []
         if gap_result.has_gaps:
             cards = generate_question_cards(gap_result, updated_state, user_message=message)
@@ -287,8 +286,8 @@ class CrewOrchestrator(BaseOrchestrator):
 
         # If approved and CAD said NOT READY, reset
         if state.phase == "approved":
-            for r in responses:
-                if r.get("agent_id") == "cad" and r.get("message", "").upper().startswith("NOT READY:"):
+            for r in agent_responses:
+                if r.agent_id == "cad" and r.message.upper().startswith("NOT READY:"):
                     updated_state.phase = "exploring"
                     updated_state.plan = None
                     break
@@ -322,7 +321,7 @@ class CrewOrchestrator(BaseOrchestrator):
         mock = MockChatBackend(output_dir=self.output_dir)
         result = mock.chat_turn(message, history, mentions, design_state=state.model_dump(), plan_context=plan_context)
         if "question_cards" not in result:
-            result_responses = result.get("responses", [])
+            result_responses = [AgentResponse(**r) for r in result.get("responses", [])]
             gap_result = analyze_gaps(result_responses)
             if gap_result.has_gaps:
                 cards = generate_question_cards(gap_result, state, user_message=message)

agents/design_state.py

@@ -3,12 +3,15 @@
 from __future__ import annotations
 
 import re
-from typing import Literal
+from typing import TYPE_CHECKING, Literal
 
 from pydantic import BaseModel, Field
 
 from config.settings import settings
 
+if TYPE_CHECKING:
+    from agents.agent_flow import AgentResponse
+
 
 # ── Config-driven domain data helpers ─────────────────────────────────────────
 
@@ -135,7 +138,7 @@ class DesignState(BaseModel):
 
     def update_from_messages(
         self,
-        agent_responses: list[dict],
+        agent_responses: list[AgentResponse],
         user_message: str = "",
     ) -> "DesignState":
         """Extract design decisions from messages and return updated state."""
@@ -143,7 +146,7 @@ class DesignState(BaseModel):
         max_decisions = settings.orchestration.max_decisions
 
         # Combine all text for scanning
-        all_text = user_message + " " + " ".join(r.get("message", "") for r in agent_responses)
+        all_text = user_message + " " + " ".join(r.message for r in agent_responses)
         lower = all_text.lower()
 
         materials = _get_materials()
@@ -217,7 +220,7 @@ class DesignState(BaseModel):
 
         # Extract decisions: sentences with agreement language from agent messages only
         for resp in agent_responses:
-            msg = resp.get("message", "")
+            msg = resp.message
             sentences = re.split(r'[.!?]+', msg)
             for sentence in sentences:
                 s = sentence.strip()
@@ -273,7 +276,7 @@ def compute_score(state: DesignState) -> float:
 
 
 def extract_decisions(
-    agent_responses: list[dict],
+    agent_responses: list[AgentResponse],
     current_state: DesignState,
     user_message: str = "",
 ) -> DesignState:

agents/gap_analyzer.py

@@ -10,6 +10,7 @@ from pydantic import BaseModel, Field
 
 from config.settings import settings
 from agents.definitions import AGENTS
+from agents.agent_flow import AgentResponse
 
 
 # ── Models ────────────────────────────────────────────────────────────────────
@@ -85,7 +86,7 @@ QUESTION_TEMPLATES: dict[str, dict] = {
 # ── Core functions ────────────────────────────────────────────────────────────
 
 
-def analyze_gaps(responses: list[dict]) -> GapAnalysis:
+def analyze_gaps(responses: list[AgentResponse]) -> GapAnalysis:
     """Scan agent responses for NOT READY: prefixes and classify missing items.
 
     Deduplicates by category — first agent to flag a category wins.
@@ -97,8 +98,8 @@ def analyze_gaps(responses: list[dict]) -> GapAnalysis:
     missing_items: list[MissingItem] = []
 
     for response in responses:
-        message: str = response.get("message", "")
-        agent_id: str = response.get("agent_id", "")
+        message: str = response.message
+        agent_id: str = response.agent_id
 
         # Case-insensitive check for NOT READY: prefix
         stripped = message.strip()

agents/orchestrator.py

@@ -18,7 +18,7 @@ from pathlib import Path
 
 from agents.definitions import AGENT_COLORS, AGENT_NAMES, AGENT_AVATARS
 from core.utils import derive_part_name
-from agents.agent_flow import route_agents
+from agents.agent_flow import AgentResponse, route_agents
 from agents.base import BaseOrchestrator
 from agents.design_state import DesignState, extract_decisions
 from core.backends import MockBackend
@@ -176,22 +176,23 @@ class MockChatBackend(BaseOrchestrator):
         else:
             active = route_agents(message, mentions=[], is_approved_phase=False)
 
+        agent_responses: list[AgentResponse] = []
         responses: list[dict] = []
         preview = None
 
         if "design" in active:
-            responses.append(
-                _format_response("design", self._design_response(lower))
+            agent_responses.append(
+                AgentResponse.from_agent("design", self._design_response(lower))
             )
 
         if "engineering" in active:
-            responses.append(
-                _format_response("engineering", self._engineering_response(lower))
+            agent_responses.append(
+                AgentResponse.from_agent("engineering", self._engineering_response(lower))
             )
 
         if "cnc" in active:
-            responses.append(
-                _format_response("cnc", self._cnc_response(lower))
+            agent_responses.append(
+                AgentResponse.from_agent("cnc", self._cnc_response(lower))
             )
 
         if "cad" in active:
@@ -200,8 +201,8 @@ class MockChatBackend(BaseOrchestrator):
 
             mock = MockBackend()
             code = mock.generate(build_messages(message))
-            responses.append(
-                _format_response(
+            agent_responses.append(
+                AgentResponse.from_agent(
                     "cad",
                     "Model generated. Click the 3D viewer to inspect it.",
                     code=code,
@@ -209,8 +210,10 @@ class MockChatBackend(BaseOrchestrator):
             )
             preview = _execute_cad_code(code, message, self.output_dir)
 
+        responses = [r.model_dump() for r in agent_responses]
+
         # Update design state from responses
-        updated_state = extract_decisions(responses, state, message)
+        updated_state = extract_decisions(agent_responses, state, message)
 
         return {"responses": responses, "preview": preview, "design_state": updated_state.model_dump()}
 

tests/test_design_state.py

@@ -1,5 +1,6 @@
 """Tests for agents/design_state.py — state tracking and decision extraction."""
 
+from agents.agent_flow import AgentResponse
 from agents.design_state import DesignPlan, DesignState, compute_score, extract_decisions
 
 
@@ -34,7 +35,7 @@ class TestDesignState:
 class TestExtractDecisions:
     def test_extracts_material(self):
         responses = [
-            {"agent_id": "engineering", "message": "I recommend aluminum 6061 for this application."}
+            AgentResponse.from_agent("engineering", "I recommend aluminum 6061 for this application.")
         ]
         state = extract_decisions(responses, DesignState())
         assert "aluminum" in state.material.lower()
@@ -47,14 +48,14 @@ class TestExtractDecisions:
 
     def test_extracts_fastener_features(self):
         responses = [
-            {"agent_id": "engineering", "message": "I'll add 4x M6 clearance holes for mounting."}
+            AgentResponse.from_agent("engineering", "I'll add 4x M6 clearance holes for mounting.")
         ]
         state = extract_decisions(responses, DesignState())
         assert any("M6" in f for f in state.features)
 
     def test_extracts_axis_recommendation(self):
         responses = [
-            {"agent_id": "cnc", "message": "This part needs 5-axis machining due to the undercut."}
+            AgentResponse.from_agent("cnc", "This part needs 5-axis machining due to the undercut.")
         ]
         state = extract_decisions(responses, DesignState())
         assert "5-axis" in state.axis_recommendation
@@ -67,7 +68,7 @@ class TestExtractDecisions:
     def test_preserves_existing_state(self):
         existing = DesignState(material="steel", dimensions={"width": 50.0})
         responses = [
-            {"agent_id": "engineering", "message": "Height should be 30mm."}
+            AgentResponse.from_agent("engineering", "Height should be 30mm.")
         ]
         updated = extract_decisions(responses, existing, user_message="add height")
         assert updated.material == "steel"
@@ -75,7 +76,7 @@ class TestExtractDecisions:
 
     def test_extracts_decisions_from_agreement(self):
         responses = [
-            {"agent_id": "design", "message": "I'd recommend an L-bracket form factor for this."}
+            AgentResponse.from_agent("design", "I'd recommend an L-bracket form factor for this.")
         ]
         state = extract_decisions(responses, DesignState())
         assert len(state.decisions) > 0
@@ -83,7 +84,7 @@ class TestExtractDecisions:
     def test_no_duplicate_features(self):
         existing = DesignState(features=["4x M6 holes"])
         responses = [
-            {"agent_id": "engineering", "message": "The 4x M6 holes are properly specified."}
+            AgentResponse.from_agent("engineering", "The 4x M6 holes are properly specified.")
         ]
         updated = extract_decisions(responses, existing)
         m6_count = sum(1 for f in updated.features if "M6" in f)

tests/test_gap_analyzer.py

@@ -1,5 +1,6 @@
 """Tests for agents/gap_analyzer.py — gap detection and question card generation."""
 
+from agents.agent_flow import AgentResponse
 from agents.gap_analyzer import (
     MissingItem, GapAnalysis, QuestionCard,
     analyze_gaps, generate_question_cards,
@@ -10,8 +11,8 @@ from agents.design_state import DesignState
 class TestAnalyzeGaps:
     def test_no_gaps_when_no_not_ready(self):
         responses = [
-            {"agent_id": "design", "message": "I suggest an L-bracket design."},
-            {"agent_id": "engineering", "message": "Aluminum 6061 would work well."},
+            AgentResponse.from_agent("design", "I suggest an L-bracket design."),
+            AgentResponse.from_agent("engineering", "Aluminum 6061 would work well."),
         ]
         result = analyze_gaps(responses)
         assert not result.has_gaps
@@ -19,7 +20,7 @@ class TestAnalyzeGaps:
 
     def test_detects_not_ready_from_cad(self):
         responses = [
-            {"agent_id": "cad", "message": "NOT READY: Need dimensions (width, height) and material selection."},
+            AgentResponse.from_agent("cad", "NOT READY: Need dimensions (width, height) and material selection."),
         ]
         result = analyze_gaps(responses)
         assert result.has_gaps
@@ -29,7 +30,7 @@ class TestAnalyzeGaps:
 
     def test_detects_not_ready_from_cnc(self):
         responses = [
-            {"agent_id": "cnc", "message": "NOT READY: Need material and tolerance info for manufacturability check."},
+            AgentResponse.from_agent("cnc", "NOT READY: Need material and tolerance info for manufacturability check."),
         ]
         result = analyze_gaps(responses)
         assert result.has_gaps
@@ -39,7 +40,7 @@ class TestAnalyzeGaps:
 
     def test_detects_not_ready_from_cam(self):
         responses = [
-            {"agent_id": "cam", "message": "NOT READY: No 3D model available. Need CAD generation first."},
+            AgentResponse.from_agent("cam", "NOT READY: No 3D model available. Need CAD generation first."),
         ]
         result = analyze_gaps(responses)
         assert result.has_gaps
@@ -48,8 +49,8 @@ class TestAnalyzeGaps:
 
     def test_deduplicates_across_agents(self):
         responses = [
-            {"agent_id": "cad", "message": "NOT READY: Need material and dimensions."},
-            {"agent_id": "cnc", "message": "NOT READY: Material is required for manufacturability."},
+            AgentResponse.from_agent("cad", "NOT READY: Need material and dimensions."),
+            AgentResponse.from_agent("cnc", "NOT READY: Material is required for manufacturability."),
         ]
         result = analyze_gaps(responses)
         material_items = [i for i in result.missing_items if i.category == "material"]
@@ -58,7 +59,7 @@ class TestAnalyzeGaps:
 
     def test_case_insensitive_not_ready(self):
         responses = [
-            {"agent_id": "cad", "message": "not ready: missing width and height dimensions."},
+            AgentResponse.from_agent("cad", "not ready: missing width and height dimensions."),
         ]
         result = analyze_gaps(responses)
         assert result.has_gaps
@@ -66,8 +67,8 @@ class TestAnalyzeGaps:
 
     def test_no_false_positive_on_regular_message(self):
         responses = [
-            {"agent_id": "cad", "message": "Model generated successfully."},
-            {"agent_id": "cnc", "message": "3-axis machining is ready for this part."},
+            AgentResponse.from_agent("cad", "Model generated successfully."),
+            AgentResponse.from_agent("cnc", "3-axis machining is ready for this part."),
         ]
         result = analyze_gaps(responses)
         assert not result.has_gaps