fix: implement SPEC_04 (Magentic UX) and SPEC_05 (cleanup)

SPEC_04:
- P0: Preserve chat history on timeout (app.py)
- P1: Increase default timeout to 600s
- P1: Add MAGENTIC_TIMEOUT env var config

SPEC_05:
- Delete empty src/orchestrator/ folder
- Delete unused orchestrator_hierarchical.py (0% coverage)

All 162 tests pass.

docs/specs/SPEC_03_OPENALEX_INTEGRATION.md

@@ -499,3 +499,24 @@ class TestOpenAlexIntegration:
         # Should have concepts
         assert len(results[0].metadata["concepts"]) > 0
 ```
+
+## Acceptance Criteria
+
+- [x] `OpenAlexTool` implements `SearchTool` Protocol
+- [x] Tool returns `list[Evidence]` with citation metadata
+- [x] Abstract reconstructed from inverted index format
+- [x] Relevance calculated from citation count (capped at 1.0)
+- [x] Exported from `src/tools/__init__.py`
+- [x] Integrated into `src/app.py` SearchHandler
+- [x] UI description updated to mention OpenAlex
+- [x] All unit tests pass (11 tests)
+- [x] Integration test passes with real API
+
+**Status: IMPLEMENTED** (commits fd28242, TBD)
+
+## Files Modified
+
+1. `src/tools/openalex.py` - NEW: OpenAlex tool implementation
+2. `tests/unit/tools/test_openalex.py` - NEW: Unit and integration tests
+3. `src/tools/__init__.py` - Export OpenAlexTool
+4. `src/app.py` - Wire OpenAlexTool into SearchHandler

src/app.py

@@ -14,6 +14,7 @@ from src.agent_factory.judges import HFInferenceJudgeHandler, JudgeHandler, Mock
 from src.orchestrator_factory import create_orchestrator
 from src.tools.clinicaltrials import ClinicalTrialsTool
 from src.tools.europepmc import EuropePMCTool
+from src.tools.openalex import OpenAlexTool
 from src.tools.pubmed import PubMedTool
 from src.tools.search_handler import SearchHandler
 from src.utils.config import settings
@@ -45,7 +46,7 @@ def configure_orchestrator(
 
     # Create search tools
     search_handler = SearchHandler(
-        tools=[PubMedTool(), ClinicalTrialsTool(), EuropePMCTool()],
+        tools=[PubMedTool(), ClinicalTrialsTool(), EuropePMCTool(), OpenAlexTool()],
         timeout=config.search_timeout,
     )
 
@@ -176,13 +177,7 @@ async def research_agent(
         # Immediate backend info + loading feedback so user knows something is happening
         yield (
             f"🧠 **Backend**: {backend_name}\n\n"
-            "⏳ **Processing...** Searching PubMed, ClinicalTrials.gov, Europe PMC...\n"
-        )
-
-        # Immediate loading feedback so user knows something is happening
-        yield (
-            f"🧠 **Backend**: {backend_name}\n\n"
-            "⏳ **Processing...** Searching PubMed, ClinicalTrials.gov, Europe PMC...\n"
+            "⏳ **Processing...** Searching PubMed, ClinicalTrials.gov, Europe PMC, OpenAlex...\n"
         )
 
         async for event in orchestrator.run(message):
@@ -203,7 +198,8 @@ async def research_agent(
 
             # Handle complete events specially
             if event.type == "complete":
-                yield event.message
+                response_parts.append(event.message)
+                yield "\n\n".join(response_parts)
             else:
                 # Format and append non-streaming events
                 event_md = event.to_markdown()
@@ -240,7 +236,7 @@ def create_demo() -> tuple[gr.ChatInterface, gr.Accordion]:
         title="🍆 DeepBoner",
         description=(
             "*AI-Powered Sexual Health Research Agent — searches PubMed, "
-            "ClinicalTrials.gov & Europe PMC*\n\n"
+            "ClinicalTrials.gov, Europe PMC & OpenAlex*\n\n"
             "Deep research for sexual wellness, ED treatments, hormone therapy, "
             "libido, and reproductive health - for all genders.\n\n"
             "---\n"

src/orchestrator_factory.py

@@ -52,6 +52,7 @@ def create_orchestrator(
         return orchestrator_cls(
             max_rounds=config.max_iterations if config else 10,
             api_key=api_key,
+            timeout_seconds=settings.magentic_timeout,
         )
 
     # Simple mode requires handlers

src/orchestrator_hierarchical.py

@@ -1,95 +0,0 @@
-"""Hierarchical orchestrator using middleware and sub-teams."""
-
-import asyncio
-from collections.abc import AsyncGenerator
-
-import structlog
-
-from src.agents.judge_agent_llm import LLMSubIterationJudge
-from src.agents.magentic_agents import create_search_agent
-from src.middleware.sub_iteration import SubIterationMiddleware, SubIterationTeam
-from src.services.embeddings import get_embedding_service
-from src.state import init_magentic_state
-from src.utils.models import AgentEvent
-
-logger = structlog.get_logger()
-
-
-class ResearchTeam(SubIterationTeam):
-    """Adapts Magentic ChatAgent to SubIterationTeam protocol."""
-
-    def __init__(self) -> None:
-        self.agent = create_search_agent()
-
-    async def execute(self, task: str) -> str:
-        response = await self.agent.run(task)
-        if response.messages:
-            for msg in reversed(response.messages):
-                if msg.role == "assistant" and msg.text:
-                    return str(msg.text)
-        return "No response from agent."
-
-
-class HierarchicalOrchestrator:
-    """Orchestrator that uses hierarchical teams and sub-iterations."""
-
-    def __init__(self) -> None:
-        self.team = ResearchTeam()
-        self.judge = LLMSubIterationJudge()
-        self.middleware = SubIterationMiddleware(self.team, self.judge, max_iterations=5)
-
-    async def run(self, query: str) -> AsyncGenerator[AgentEvent, None]:
-        logger.info("Starting hierarchical orchestrator", query=query)
-
-        try:
-            service = get_embedding_service()
-            init_magentic_state(service)
-        except Exception as e:
-            logger.warning(
-                "Embedding service initialization failed, using default state",
-                error=str(e),
-            )
-            init_magentic_state()
-
-        yield AgentEvent(type="started", message=f"Starting research: {query}")
-
-        queue: asyncio.Queue[AgentEvent | None] = asyncio.Queue()
-
-        async def event_callback(event: AgentEvent) -> None:
-            await queue.put(event)
-
-        task_future = asyncio.create_task(self.middleware.run(query, event_callback))
-
-        while not task_future.done():
-            get_event = asyncio.create_task(queue.get())
-            done, _ = await asyncio.wait(
-                {task_future, get_event}, return_when=asyncio.FIRST_COMPLETED
-            )
-
-            if get_event in done:
-                event = get_event.result()
-                if event:
-                    yield event
-            else:
-                get_event.cancel()
-
-        # Process remaining events
-        while not queue.empty():
-            ev = queue.get_nowait()
-            if ev:
-                yield ev
-
-        try:
-            result, assessment = await task_future
-
-            assessment_text = assessment.reasoning if assessment else "None"
-            yield AgentEvent(
-                type="complete",
-                message=(
-                    f"Research complete.\n\nResult:\n{result}\n\nAssessment:\n{assessment_text}"
-                ),
-                data={"assessment": assessment.model_dump() if assessment else None},
-            )
-        except Exception as e:
-            logger.error("Orchestrator failed", error=str(e))
-            yield AgentEvent(type="error", message=f"Orchestrator failed: {e}")

src/orchestrator_magentic.py

@@ -45,7 +45,7 @@ class MagenticOrchestrator:
         max_rounds: int = 10,
         chat_client: OpenAIChatClient | None = None,
         api_key: str | None = None,
-        timeout_seconds: float = 300.0,
+        timeout_seconds: float = 600.0,
     ) -> None:
         """Initialize orchestrator.
 
@@ -53,7 +53,7 @@ class MagenticOrchestrator:
             max_rounds: Maximum coordination rounds
             chat_client: Optional shared chat client for agents
             api_key: Optional OpenAI API key (for BYOK)
-            timeout_seconds: Maximum workflow duration (default: 5 minutes)
+            timeout_seconds: Maximum workflow duration (default: 10 minutes)
         """
         # Validate requirements only if no key provided
         if not chat_client and not api_key:

src/utils/config.py

@@ -57,6 +57,10 @@ class Settings(BaseSettings):
     # Agent Configuration
     max_iterations: int = Field(default=10, ge=1, le=50)
     search_timeout: int = Field(default=30, description="Seconds to wait for search")
+    magentic_timeout: int = Field(
+        default=600,
+        description="Timeout for Magentic mode in seconds",
+    )
 
     # Logging
     log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = "INFO"

tests/unit/test_app_timeout.py

@@ -0,0 +1,60 @@
+"""Tests for app timeout and history preservation."""
+
+import os
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from src.app import research_agent
+from src.utils.models import AgentEvent
+
+
+async def async_gen(items):
+    for item in items:
+        yield item
+
+
+@pytest.mark.asyncio
+async def test_complete_event_preserves_history():
+    """
+    Verify that a 'complete' event (like timeout) appends to the history
+    instead of replacing it.
+    """
+    # Mock events: Progress -> Progress -> Complete
+    mock_events = [
+        AgentEvent(type="thinking", message="Step 1: Thinking...", iteration=0),
+        AgentEvent(type="search_complete", message="Step 2: Found data", iteration=1),
+        AgentEvent(type="complete", message="Timeout: Synthesizing...", iteration=1),
+    ]
+
+    # Create a mock orchestrator that yields these events
+    mock_orchestrator = MagicMock()
+    # The run method should return an async generator
+    mock_orchestrator.run.side_effect = lambda msg: async_gen(mock_events)
+
+    # Patch configure_orchestrator to return our mock
+    with patch("src.app.configure_orchestrator") as mock_config:
+        mock_config.return_value = (mock_orchestrator, "Mock Backend")
+
+        # Run the agent
+        results = []
+        async for output in research_agent("test query", [], "simple"):
+            results.append(output)
+
+        # The final output should contain the accumulated history AND the timeout message
+        final_output = results[-1]
+
+        # Check for preservation
+        assert "Step 1: Thinking..." in final_output
+        assert "Step 2: Found data" in final_output
+        assert "Timeout: Synthesizing..." in final_output
+
+
+@pytest.mark.asyncio
+async def test_timeout_configurable():
+    """Verify MAGENTIC_TIMEOUT env var is respected."""
+    from src.utils.config import Settings
+
+    with patch.dict(os.environ, {"MAGENTIC_TIMEOUT": "120"}):
+        settings = Settings()
+        assert settings.magentic_timeout == 120