Merge pull request #107 from The-Obstacle-Is-The-Way/fix/p1-chain-of-thought-interpretability

docs/bugs/ACTIVE_BUGS.md

@@ -23,16 +23,9 @@ _No active P0 bugs._
 - `Manager (task_ledger): We are working to address...`
 - `Manager (instruction): Conduct targeted searches on PubMed...`
 
-These are framework-internal bookkeeping truncated at 200 chars, making them uninterpretable.
-
 **Root Cause:** `_process_event()` in `advanced.py` doesn't filter or transform `MagenticOrchestratorMessageEvent` events from `agent-framework-core`.
 
-**Solution Options:**
-1. Filter internal events (`user_task`, `task_ledger`, `instruction`)
-2. Transform to user-friendly messages ("Manager assigning search task...")
-3. Add verbose mode for debugging
-
-**Status:** Open
+**Status:** PR [#107](https://github.com/The-Obstacle-Is-The-Way/DeepBoner/pull/107) open, pending merge.
 
 ---
 

docs/bugs/P1_ADVANCED_MODE_UNINTERPRETABLE_CHAIN_OF_THOUGHT.md

@@ -2,8 +2,9 @@
 
 **Priority**: P1 (UX Degradation)
 **Component**: `src/orchestrators/advanced.py`
-**Status**: Open
+**Status**: Fix Ready (PR #107 open)
 **Issue**: [#106](https://github.com/The-Obstacle-Is-The-Way/DeepBoner/issues/106)
+**PR**: [#107](https://github.com/The-Obstacle-Is-The-Way/DeepBoner/pull/107)
 **Created**: 2025-12-01
 
 ## Summary
@@ -15,6 +16,16 @@ The Advanced orchestrator exposes raw internal framework events from `agent-fram
 3. Shown with misleading "JUDGING" event type
 4. Not meaningful to end users
 
+## Resolution
+
+Implemented "Smart Filter + Transform" logic in `src/orchestrators/advanced.py`:
+
+1. **Filtered**: `task_ledger` and `instruction` events are now hidden.
+2. **Transformed**: `user_task` events are mapped to `type="progress"` with a friendly "Manager assigning research task..." message.
+3. **Smart Truncation**: Text is now truncated at sentence boundaries or word boundaries, preventing mid-word cuts.
+
+Verified with new unit tests in `tests/unit/orchestrators/test_advanced_events.py`.
+
 ## Example of Bad Output
 
 ```

src/orchestrators/advanced.py

@@ -358,17 +358,46 @@ The final output should be a structured research report."""
             return "synthesizing"
         return "judging"  # Default for unknown agents
 
+    def _smart_truncate(self, text: str, max_len: int = 200) -> str:
+        """Truncate at sentence boundary to avoid cutting words."""
+        if len(text) <= max_len:
+            return text
+        # Find last sentence boundary before limit
+        truncated = text[:max_len]
+        last_period = truncated.rfind(". ")
+        if last_period > max_len // 2:
+            return truncated[: last_period + 1]
+        # Fallback to word boundary
+        return truncated.rsplit(" ", 1)[0] + "..."
+
     def _process_event(self, event: Any, iteration: int) -> AgentEvent | None:
         """Process workflow event into AgentEvent."""
         if isinstance(event, MagenticOrchestratorMessageEvent):
-            text = self._extract_text(event.message)
-            if text:
+            # FILTERING: Skip internal framework bookkeeping
+            if event.kind in ("task_ledger", "instruction"):
+                return None
+
+            # TRANSFORMATION: Handle user_task BEFORE text extraction
+            # (user_task uses static message, doesn't need text content)
+            if event.kind == "user_task":
                 return AgentEvent(
-                    type="judging",
-                    message=f"Manager ({event.kind}): {text[:200]}...",
+                    type="progress",
+                    message="Manager assigning research task to agents...",
                     iteration=iteration,
                 )
 
+            # For other manager events, extract and validate text
+            text = self._extract_text(event.message)
+            if not text:
+                return None
+
+            # Default fallback for other manager events
+            return AgentEvent(
+                type="judging",
+                message=f"Manager ({event.kind}): {self._smart_truncate(text)}",
+                iteration=iteration,
+            )
+
         elif isinstance(event, MagenticAgentMessageEvent):
             agent_name = event.agent_id or "unknown"
             text = self._extract_text(event.message)
@@ -377,7 +406,7 @@ The final output should be a structured research report."""
             # All returned types are valid AgentEvent.type literals
             return AgentEvent(
                 type=event_type,  # type: ignore[arg-type]
-                message=f"{agent_name}: {text[:200]}...",
+                message=f"{agent_name}: {self._smart_truncate(text)}",
                 iteration=iteration + 1,
             )
 

tests/unit/orchestrators/test_advanced_events.py

@@ -0,0 +1,109 @@
+"""Test for AdvancedOrchestrator event processing (P1 Bug)."""
+
+import pytest
+from agent_framework import MagenticOrchestratorMessageEvent
+
+from src.orchestrators.advanced import AdvancedOrchestrator
+
+
+@pytest.mark.unit
+class TestAdvancedEventProcessing:
+    """Test event processing logic in AdvancedOrchestrator."""
+
+    @pytest.fixture
+    def orchestrator(self) -> AdvancedOrchestrator:
+        """Create an orchestrator instance with mocks."""
+        # Bypass __init__ logic that requires keys/env vars
+        orch = AdvancedOrchestrator.__new__(AdvancedOrchestrator)
+        # Minimal setup
+        orch._max_rounds = 5
+        orch._timeout_seconds = 300.0
+        return orch
+
+    def test_filters_internal_task_ledger_events(self, orchestrator: AdvancedOrchestrator) -> None:
+        """
+        Bug P1: Internal 'task_ledger' events should be filtered out.
+
+        Current behavior: Returns AgentEvent(type='judging', message='Manager (task_ledger): ...')
+        Desired behavior: Returns None (filtered)
+        """
+        # Create a raw internal framework event
+        raw_event = MagenticOrchestratorMessageEvent(
+            kind="task_ledger",
+            message="We are working to address the following user request: Research sildenafil...",
+        )
+
+        # Process the event
+        result = orchestrator._process_event(raw_event, iteration=1)
+
+        # FAIL if the event is NOT filtered (i.e., if it returns an event)
+        assert result is None, f"Should filter 'task_ledger' events, but got: {result}"
+
+    def test_filters_internal_instruction_events(self, orchestrator: AdvancedOrchestrator) -> None:
+        """
+        Bug P1: Internal 'instruction' events should be filtered out.
+
+        Current behavior: Returns AgentEvent(type='judging', message='Manager (instruction): ...')
+        Desired behavior: Returns None (filtered)
+        """
+        raw_event = MagenticOrchestratorMessageEvent(
+            kind="instruction", message="Conduct targeted searches on PubMed..."
+        )
+
+        result = orchestrator._process_event(raw_event, iteration=1)
+
+        assert result is None, f"Should filter 'instruction' events, but got: {result}"
+
+    def test_transforms_user_task_events(self, orchestrator: AdvancedOrchestrator) -> None:
+        """
+        Bug P1: 'user_task' events should be transformed to user-friendly messages.
+
+        Current behavior: 'Manager (user_task): Research...' (truncated, type='judging')
+        Desired behavior: 'Manager assigning research task...' (type='progress')
+        """
+        raw_event = MagenticOrchestratorMessageEvent(
+            kind="user_task",
+            message="Research sexual health and wellness interventions for: sildenafil mechanism",
+        )
+
+        result = orchestrator._process_event(raw_event, iteration=1)
+
+        assert result is not None
+        assert result.type == "progress"  # NOT "judging"
+        assert "Manager assigning research task" in result.message
+        # Should use the generic friendly message
+        assert "sildenafil mechanism" not in result.message
+
+    def test_prevents_mid_sentence_truncation(self, orchestrator: AdvancedOrchestrator) -> None:
+        """
+        Bug P1: Long messages should be smart-truncated at sentence boundaries.
+
+        Tests _smart_truncate directly to ensure regression protection.
+        The function truncates at sentence boundary if period is after halfway point.
+        """
+        # First sentence ends at position ~55, which is > 50 (100//2)
+        long_text = (
+            "This is a longer first sentence that ends past the midpoint. "
+            "Second sentence continues with more text that would be cut."
+        )
+
+        # Call the helper directly to test its behavior explicitly
+        truncated = orchestrator._smart_truncate(long_text, max_len=100)
+
+        # Should truncate at the end of the first sentence (period > max_len//2)
+        assert truncated.endswith("midpoint.")
+        assert "Second sentence" not in truncated
+        assert len(truncated) <= 100
+
+    def test_smart_truncate_word_boundary_fallback(
+        self, orchestrator: AdvancedOrchestrator
+    ) -> None:
+        """Test that truncation falls back to word boundary when no sentence end."""
+        # No sentence ending in the first 80 chars
+        long_text = "This is a very long text without any sentence ending in the limit"
+
+        truncated = orchestrator._smart_truncate(long_text, max_len=50)
+
+        # Should end with "..." and not cut mid-word
+        assert truncated.endswith("...")
+        assert len(truncated) <= 53  # 50 + "..."