refactor: Organize orchestrators into dedicated package

- Create src/orchestrators/ package with proper module structure
- base.py: Shared protocols (SearchHandlerProtocol, JudgeHandlerProtocol)
- simple.py: Basic search-judge loop orchestrator (was orchestrator.py)
- advanced.py: Multi-agent MS Agent Framework orchestrator (was orchestrator_magentic.py)
- hierarchical.py: Sub-iteration middleware orchestrator
- factory.py: Factory pattern for orchestrator creation
- __init__.py: Clean public API with facade pattern

Design principles applied:
- Single Responsibility (SRP): Each file has one clear job
- Interface Segregation (ISP): Protocols in base.py
- Factory Pattern (GoF): Centralized creation logic
- Facade Pattern: Clean public imports via __init__.py

All imports updated across:
- src/app.py, src/agents/
- tests/unit/, tests/e2e/, tests/integration/
- examples/orchestrator_demo/

All 147 tests pass, linting and typecheck clean.

examples/orchestrator_demo/run_agent.py

@@ -23,7 +23,7 @@ import os
 import sys
 
 from src.agent_factory.judges import JudgeHandler
-from src.orchestrator import Orchestrator
+from src.orchestrators import Orchestrator
 from src.tools.clinicaltrials import ClinicalTrialsTool
 from src.tools.europepmc import EuropePMCTool
 from src.tools.pubmed import PubMedTool

examples/orchestrator_demo/run_magentic.py

@@ -17,7 +17,7 @@ import os
 import sys
 
 from src.agent_factory.judges import JudgeHandler
-from src.orchestrator_factory import create_orchestrator
+from src.orchestrators import create_orchestrator
 from src.tools.clinicaltrials import ClinicalTrialsTool
 from src.tools.europepmc import EuropePMCTool
 from src.tools.pubmed import PubMedTool

src/agents/judge_agent.py

@@ -12,7 +12,7 @@ from agent_framework import (
     Role,
 )
 
-from src.orchestrator import JudgeHandlerProtocol
+from src.orchestrators import JudgeHandlerProtocol
 from src.utils.models import Evidence, JudgeAssessment
 
 

src/agents/search_agent.py

@@ -10,7 +10,7 @@ from agent_framework import (
     Role,
 )
 
-from src.orchestrator import SearchHandlerProtocol
+from src.orchestrators import SearchHandlerProtocol
 from src.utils.models import Citation, Evidence, SearchResult
 
 if TYPE_CHECKING:

src/app.py

@@ -11,7 +11,7 @@ from pydantic_ai.providers.anthropic import AnthropicProvider
 from pydantic_ai.providers.openai import OpenAIProvider
 
 from src.agent_factory.judges import HFInferenceJudgeHandler, JudgeHandler, MockJudgeHandler
-from src.orchestrator_factory import create_orchestrator
+from src.orchestrators import create_orchestrator
 from src.tools.clinicaltrials import ClinicalTrialsTool
 from src.tools.europepmc import EuropePMCTool
 from src.tools.openalex import OpenAlexTool

src/orchestrators/__init__.py

@@ -0,0 +1,71 @@
+"""Orchestrators package - provides different orchestration strategies.
+
+This package implements the Strategy Pattern, allowing the application
+to switch between different orchestration approaches:
+
+- Simple: Basic search-judge loop using pydantic-ai (free tier compatible)
+- Advanced: Multi-agent coordination using Microsoft Agent Framework
+- Hierarchical: Sub-iteration middleware with fine-grained control
+
+Usage:
+    from src.orchestrators import create_orchestrator, Orchestrator
+
+    # Auto-detect mode based on available API keys
+    orchestrator = create_orchestrator(search_handler, judge_handler)
+
+    # Or explicitly specify mode
+    orchestrator = create_orchestrator(mode="advanced", api_key="sk-...")
+
+Protocols:
+    from src.orchestrators import SearchHandlerProtocol, JudgeHandlerProtocol
+
+Design Patterns Applied:
+- Factory Pattern: create_orchestrator() creates appropriate orchestrator
+- Strategy Pattern: Different orchestrators implement different strategies
+- Facade Pattern: This __init__.py provides a clean public API
+"""
+
+# Protocols (Interface Segregation Principle)
+from src.orchestrators.base import JudgeHandlerProtocol, SearchHandlerProtocol
+
+# Factory (creational pattern)
+from src.orchestrators.factory import create_orchestrator
+
+# Orchestrators (Strategy Pattern implementations)
+from src.orchestrators.simple import Orchestrator
+
+# Lazy imports for optional dependencies
+# These are not imported at module level to avoid breaking simple mode
+# when agent-framework-core is not installed
+
+
+def get_advanced_orchestrator() -> type:
+    """Get the AdvancedOrchestrator class (requires agent-framework-core)."""
+    from src.orchestrators.advanced import AdvancedOrchestrator
+
+    return AdvancedOrchestrator
+
+
+def get_hierarchical_orchestrator() -> type:
+    """Get the HierarchicalOrchestrator class (requires agent-framework-core)."""
+    from src.orchestrators.hierarchical import HierarchicalOrchestrator
+
+    return HierarchicalOrchestrator
+
+
+# Backwards compatibility aliases
+# TODO: Remove after migration period
+def get_magentic_orchestrator() -> type:
+    """Deprecated: Use get_advanced_orchestrator() instead."""
+    return get_advanced_orchestrator()
+
+
+__all__ = [
+    "JudgeHandlerProtocol",
+    "Orchestrator",
+    "SearchHandlerProtocol",
+    "create_orchestrator",
+    "get_advanced_orchestrator",
+    "get_hierarchical_orchestrator",
+    "get_magentic_orchestrator",
+]

src/{orchestrator_magentic.py → orchestrators/advanced.py}

@@ -1,4 +1,18 @@
-"""Magentic-based orchestrator using ChatAgent pattern."""
+"""Advanced Orchestrator using Microsoft Agent Framework.
+
+This orchestrator uses the ChatAgent pattern from Microsoft's agent-framework-core
+package for multi-agent coordination. It provides richer orchestration capabilities
+including specialized agents (Search, Hypothesis, Judge, Report) coordinated by
+a manager agent.
+
+Note: Previously named 'orchestrator_magentic.py' - renamed to eliminate confusion
+with the 'magentic' PyPI package (which is a different library).
+
+Design Patterns:
+- Mediator: Manager agent coordinates between specialized agents
+- Strategy: Different agents implement different strategies for their tasks
+- Observer: Event stream allows UI to observe progress
+"""
 
 import asyncio
 from collections.abc import AsyncGenerator
@@ -32,12 +46,18 @@ if TYPE_CHECKING:
 logger = structlog.get_logger()
 
 
-class MagenticOrchestrator:
+class AdvancedOrchestrator:
     """
-    Magentic-based orchestrator using ChatAgent pattern.
+    Advanced orchestrator using Microsoft Agent Framework ChatAgent pattern.
 
     Each agent has an internal LLM that understands natural language
     instructions from the manager and can call tools appropriately.
+
+    This orchestrator provides:
+    - Multi-agent coordination (Search, Hypothesis, Judge, Report)
+    - Manager agent for workflow orchestration
+    - Streaming events for real-time UI updates
+    - Configurable timeouts and round limits
     """
 
     def __init__(
@@ -90,7 +110,7 @@ class MagenticOrchestrator:
         return None
 
     def _build_workflow(self) -> Any:
-        """Build the Magentic workflow with ChatAgent participants."""
+        """Build the workflow with ChatAgent participants."""
         # Create agents with internal LLMs
         search_agent = create_search_agent(self._chat_client)
         judge_agent = create_judge_agent(self._chat_client)
@@ -122,7 +142,7 @@ class MagenticOrchestrator:
 
     async def run(self, query: str) -> AsyncGenerator[AgentEvent, None]:
         """
-        Run the Magentic workflow.
+        Run the workflow.
 
         Args:
             query: User's research question
@@ -130,11 +150,11 @@ class MagenticOrchestrator:
         Yields:
             AgentEvent objects for real-time UI updates
         """
-        logger.info("Starting Magentic orchestrator", query=query)
+        logger.info("Starting Advanced orchestrator", query=query)
 
         yield AgentEvent(
             type="started",
-            message=f"Starting research (Magentic mode): {query}",
+            message=f"Starting research (Advanced mode): {query}",
             iteration=0,
         )
 
@@ -221,7 +241,7 @@ The final output should be a structured research report."""
             )
 
         except Exception as e:
-            logger.error("Magentic workflow failed", error=str(e))
+            logger.error("Workflow failed", error=str(e))
             yield AgentEvent(
                 type="error",
                 message=f"Workflow error: {e!s}",
@@ -317,3 +337,8 @@ The final output should be a structured research report."""
                 )
 
         return None
+
+
+# Backwards compatibility alias
+# TODO: Remove after all imports are updated
+MagenticOrchestrator = AdvancedOrchestrator

src/orchestrators/base.py

@@ -0,0 +1,52 @@
+"""Base protocols and shared types for orchestrators.
+
+This module defines the interfaces that orchestrators depend on,
+following the Interface Segregation Principle (ISP) and
+Dependency Inversion Principle (DIP).
+"""
+
+from typing import Protocol
+
+from src.utils.models import Evidence, JudgeAssessment, SearchResult
+
+
+class SearchHandlerProtocol(Protocol):
+    """Protocol for search handler.
+
+    Defines the interface for executing searches across biomedical databases.
+    Implementations include SearchHandler (scatter-gather across PubMed,
+    ClinicalTrials.gov, Europe PMC).
+    """
+
+    async def execute(self, query: str, max_results_per_tool: int = 10) -> SearchResult:
+        """Execute a search query.
+
+        Args:
+            query: The search query string
+            max_results_per_tool: Maximum results to fetch per search tool
+
+        Returns:
+            SearchResult containing evidence and metadata
+        """
+        ...
+
+
+class JudgeHandlerProtocol(Protocol):
+    """Protocol for judge handler.
+
+    Defines the interface for assessing evidence quality and sufficiency.
+    Implementations include JudgeHandler (pydantic-ai), HFInferenceJudgeHandler,
+    and MockJudgeHandler.
+    """
+
+    async def assess(self, question: str, evidence: list[Evidence]) -> JudgeAssessment:
+        """Assess whether collected evidence is sufficient.
+
+        Args:
+            question: The original research question
+            evidence: List of evidence items to assess
+
+        Returns:
+            JudgeAssessment with sufficiency determination and next steps
+        """
+        ...

src/{orchestrator_factory.py → orchestrators/factory.py}

@@ -1,24 +1,37 @@
-"""Factory for creating orchestrators."""
+"""Factory for creating orchestrators.
+
+Implements the Factory Pattern (GoF) for creating the appropriate
+orchestrator based on configuration and available credentials.
+
+Design Principles:
+- Open/Closed: Easy to add new orchestrator types without modifying existing code
+- Dependency Inversion: Returns protocol-compatible objects, not concrete types
+- Single Responsibility: Only handles orchestrator creation logic
+"""
 
 from typing import Any, Literal
 
 import structlog
 
-from src.orchestrator import JudgeHandlerProtocol, Orchestrator, SearchHandlerProtocol
+from src.orchestrators.base import JudgeHandlerProtocol, SearchHandlerProtocol
+from src.orchestrators.simple import Orchestrator
 from src.utils.config import settings
 from src.utils.models import OrchestratorConfig
 
 logger = structlog.get_logger()
 
 
-def _get_magentic_orchestrator_class() -> Any:
-    """Import MagenticOrchestrator lazily to avoid hard dependency."""
+def _get_advanced_orchestrator_class() -> Any:
+    """Import AdvancedOrchestrator lazily to avoid hard dependency.
+
+    This allows the simple mode to work without agent-framework-core installed.
+    """
     try:
-        from src.orchestrator_magentic import MagenticOrchestrator
+        from src.orchestrators.advanced import AdvancedOrchestrator
 
-        return MagenticOrchestrator
+        return AdvancedOrchestrator
     except ImportError as e:
-        logger.error("Failed to import MagenticOrchestrator", error=str(e))
+        logger.error("Failed to import AdvancedOrchestrator", error=str(e))
         raise ValueError(
             "Advanced mode requires agent-framework-core. Please install it or use mode='simple'."
         ) from e
@@ -28,33 +41,46 @@ def create_orchestrator(
     search_handler: SearchHandlerProtocol | None = None,
     judge_handler: JudgeHandlerProtocol | None = None,
     config: OrchestratorConfig | None = None,
-    mode: Literal["simple", "magentic", "advanced"] | None = None,
+    mode: Literal["simple", "magentic", "advanced", "hierarchical"] | None = None,
     api_key: str | None = None,
 ) -> Any:
     """
     Create an orchestrator instance.
 
+    This factory automatically selects the appropriate orchestrator based on:
+    1. Explicit mode parameter (if provided)
+    2. Available API keys (auto-detection)
+
     Args:
         search_handler: The search handler (required for simple mode)
         judge_handler: The judge handler (required for simple mode)
         config: Optional configuration
-        mode: "simple", "magentic", "advanced" or None (auto-detect)
+        mode: "simple", "magentic", "advanced", "hierarchical" or None (auto-detect)
+              Note: "magentic" is an alias for "advanced" (kept for backwards compatibility)
         api_key: Optional API key for advanced mode (OpenAI)
 
     Returns:
         Orchestrator instance
+
+    Raises:
+        ValueError: If required handlers are missing for simple mode
+        ValueError: If advanced mode is requested but dependencies are missing
     """
     effective_mode = _determine_mode(mode, api_key)
     logger.info("Creating orchestrator", mode=effective_mode)
 
     if effective_mode == "advanced":
-        orchestrator_cls = _get_magentic_orchestrator_class()
+        orchestrator_cls = _get_advanced_orchestrator_class()
         return orchestrator_cls(
             max_rounds=config.max_iterations if config else 10,
             api_key=api_key,
-            timeout_seconds=settings.magentic_timeout,
         )
 
+    if effective_mode == "hierarchical":
+        from src.orchestrators.hierarchical import HierarchicalOrchestrator
+
+        return HierarchicalOrchestrator()
+
     # Simple mode requires handlers
     if search_handler is None or judge_handler is None:
         raise ValueError("Simple mode requires search_handler and judge_handler")
@@ -67,10 +93,24 @@ def create_orchestrator(
 
 
 def _determine_mode(explicit_mode: str | None, api_key: str | None) -> str:
-    """Determine which mode to use."""
+    """Determine which mode to use.
+
+    Priority:
+    1. Explicit mode parameter
+    2. Auto-detect based on available API keys
+
+    Args:
+        explicit_mode: Mode explicitly requested by caller
+        api_key: API key provided by caller
+
+    Returns:
+        Effective mode string: "simple", "advanced", or "hierarchical"
+    """
     if explicit_mode:
         if explicit_mode in ("magentic", "advanced"):
             return "advanced"
+        if explicit_mode == "hierarchical":
+            return "hierarchical"
         return "simple"
 
     # Auto-detect: advanced if paid API key available

src/orchestrators/hierarchical.py

@@ -0,0 +1,133 @@
+"""Hierarchical Orchestrator using middleware and sub-teams.
+
+This orchestrator implements a hierarchical team pattern where sub-teams
+can be composed and coordinated through middleware. It provides more
+granular control over the research workflow compared to the simple
+orchestrator.
+
+Design Patterns:
+- Composite: Teams can contain sub-teams
+- Chain of Responsibility: Middleware processes requests in sequence
+- Template Method: SubIterationMiddleware defines the iteration skeleton
+"""
+
+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 ChatAgent to SubIterationTeam protocol.
+
+    This adapter allows the search agent to be used within the
+    sub-iteration middleware framework.
+    """
+
+    def __init__(self) -> None:
+        self.agent = create_search_agent()
+
+    async def execute(self, task: str) -> str:
+        """Execute a research task.
+
+        Args:
+            task: The research task description
+
+        Returns:
+            Text response from the agent
+        """
+        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.
+
+    This orchestrator provides:
+    - Sub-iteration middleware for fine-grained control
+    - LLM-based judge for sub-iteration decisions
+    - Event-driven architecture for UI updates
+    """
+
+    def __init__(self) -> None:
+        """Initialize the hierarchical orchestrator."""
+        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]:
+        """Run the hierarchical workflow.
+
+        Args:
+            query: User's research question
+
+        Yields:
+            AgentEvent objects for real-time UI updates
+        """
+        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.py → orchestrators/simple.py}

@@ -1,11 +1,20 @@
-"""Orchestrator - the agent loop connecting Search and Judge."""
+"""Simple Orchestrator - the basic agent loop connecting Search and Judge.
+
+This orchestrator uses a simple loop pattern with pydantic-ai for structured
+LLM outputs. It works with free tier (HuggingFace Inference) or paid APIs
+(OpenAI, Anthropic).
+
+Design Pattern: Template Method - defines the skeleton of the search-judge loop
+while allowing handlers to implement specific behaviors.
+"""
 
 import asyncio
 from collections.abc import AsyncGenerator
-from typing import Any, Protocol
+from typing import Any
 
 import structlog
 
+from src.orchestrators.base import JudgeHandlerProtocol, SearchHandlerProtocol
 from src.utils.config import settings
 from src.utils.models import (
     AgentEvent,
@@ -18,23 +27,13 @@ from src.utils.models import (
 logger = structlog.get_logger()
 
 
-class SearchHandlerProtocol(Protocol):
-    """Protocol for search handler."""
-
-    async def execute(self, query: str, max_results_per_tool: int = 10) -> SearchResult: ...
-
-
-class JudgeHandlerProtocol(Protocol):
-    """Protocol for judge handler."""
-
-    async def assess(self, question: str, evidence: list[Evidence]) -> JudgeAssessment: ...
-
-
 class Orchestrator:
     """
-    The agent orchestrator - runs the Search -> Judge -> Loop cycle.
+    The simple agent orchestrator - runs the Search -> Judge -> Loop cycle.
 
     This is a generator-based design that yields events for real-time UI updates.
+    Uses pydantic-ai for structured LLM outputs without requiring the full
+    Microsoft Agent Framework.
     """
 
     def __init__(

tests/e2e/test_advanced_mode.py

@@ -6,7 +6,7 @@ import pytest
 agent_framework = pytest.importorskip("agent_framework")
 from agent_framework import MagenticAgentMessageEvent, MagenticFinalResultEvent
 
-from src.orchestrator_magentic import MagenticOrchestrator
+from src.orchestrators.advanced import AdvancedOrchestrator as MagenticOrchestrator
 
 
 class MockChatMessage:
@@ -24,7 +24,7 @@ async def test_advanced_mode_completes_mocked():
     """Verify Advanced mode runs without crashing (mocked workflow)."""
 
     # Initialize orchestrator (mocking requirements check)
-    with patch("src.orchestrator_magentic.check_magentic_requirements"):
+    with patch("src.orchestrators.advanced.check_magentic_requirements"):
         orchestrator = MagenticOrchestrator(max_rounds=5)
 
     # Mock the workflow
@@ -51,7 +51,7 @@ async def test_advanced_mode_completes_mocked():
     # _init_embedding_service: Avoids loading embeddings
     with (
         patch.object(orchestrator, "_build_workflow", return_value=mock_workflow),
-        patch("src.orchestrator_magentic.init_magentic_state"),
+        patch("src.orchestrators.advanced.init_magentic_state"),
         patch.object(orchestrator, "_init_embedding_service", return_value=None),
     ):
         events = []

tests/e2e/test_simple_mode.py

@@ -1,6 +1,6 @@
 import pytest
 
-from src.orchestrator import Orchestrator
+from src.orchestrators import Orchestrator
 from src.utils.models import OrchestratorConfig
 
 

tests/integration/test_dual_mode_e2e.py

@@ -6,7 +6,7 @@ import pytest
 
 pytestmark = [pytest.mark.integration, pytest.mark.slow]
 
-from src.orchestrator_factory import create_orchestrator
+from src.orchestrators import create_orchestrator
 from src.utils.models import Citation, Evidence, OrchestratorConfig
 
 
@@ -65,17 +65,18 @@ async def test_advanced_mode_explicit_instantiation():
     MagenticOrchestrator can be instantiated when explicitly requested.
     The settings patch ensures any internal checks pass.
     """
-    with patch("src.orchestrator_factory.settings") as mock_settings:
+    with patch("src.orchestrators.factory.settings") as mock_settings:
         # Settings patch ensures factory checks pass (even though mode is explicit)
         mock_settings.has_openai_key = True
 
         with patch("src.agents.magentic_agents.OpenAIChatClient"):
             # Mock agent creation to avoid real API calls during init
             with (
-                patch("src.orchestrator_magentic.create_search_agent"),
-                patch("src.orchestrator_magentic.create_judge_agent"),
-                patch("src.orchestrator_magentic.create_hypothesis_agent"),
-                patch("src.orchestrator_magentic.create_report_agent"),
+                patch("src.orchestrators.advanced.check_magentic_requirements"),
+                patch("src.orchestrators.advanced.create_search_agent"),
+                patch("src.orchestrators.advanced.create_judge_agent"),
+                patch("src.orchestrators.advanced.create_hypothesis_agent"),
+                patch("src.orchestrators.advanced.create_report_agent"),
             ):
                 # Explicit mode="advanced" - tests the explicit path, not auto-detect
                 orch = create_orchestrator(mode="advanced")

tests/unit/test_magentic_fix.py

@@ -9,7 +9,7 @@ pytest.importorskip("agent_framework")
 
 from agent_framework import MagenticFinalResultEvent  # noqa: E402
 
-from src.orchestrator_magentic import MagenticOrchestrator  # noqa: E402
+from src.orchestrators.advanced import AdvancedOrchestrator as MagenticOrchestrator  # noqa: E402
 
 
 class MockChatMessage:
@@ -39,7 +39,7 @@ class MockChatMessage:
 @pytest.fixture
 def mock_magentic_requirements():
     """Mock the API key check so tests run in CI without OPENAI_API_KEY."""
-    with patch("src.orchestrator_magentic.check_magentic_requirements"):
+    with patch("src.orchestrators.advanced.check_magentic_requirements"):
         yield
 
 
@@ -74,12 +74,12 @@ class TestMagenticFixes:
         # Also verify it's used in _build_workflow
         # Mock all the agent creation and OpenAI client calls
         with (
-            patch("src.orchestrator_magentic.create_search_agent") as mock_search,
-            patch("src.orchestrator_magentic.create_judge_agent") as mock_judge,
-            patch("src.orchestrator_magentic.create_hypothesis_agent") as mock_hypo,
-            patch("src.orchestrator_magentic.create_report_agent") as mock_report,
-            patch("src.orchestrator_magentic.OpenAIChatClient") as mock_client,
-            patch("src.orchestrator_magentic.MagenticBuilder") as mock_builder,
+            patch("src.orchestrators.advanced.create_search_agent") as mock_search,
+            patch("src.orchestrators.advanced.create_judge_agent") as mock_judge,
+            patch("src.orchestrators.advanced.create_hypothesis_agent") as mock_hypo,
+            patch("src.orchestrators.advanced.create_report_agent") as mock_report,
+            patch("src.orchestrators.advanced.OpenAIChatClient") as mock_client,
+            patch("src.orchestrators.advanced.MagenticBuilder") as mock_builder,
         ):
             # Setup mocks
             mock_search.return_value = MagicMock()

tests/unit/test_magentic_termination.py

@@ -5,7 +5,7 @@ from unittest.mock import MagicMock, patch
 import pytest
 from agent_framework import MagenticAgentMessageEvent
 
-from src.orchestrator_magentic import MagenticOrchestrator
+from src.orchestrators.advanced import AdvancedOrchestrator as MagenticOrchestrator
 from src.utils.models import AgentEvent
 
 # Skip tests if agent_framework is not installed
@@ -25,7 +25,7 @@ class MockChatMessage:
 @pytest.fixture
 def mock_magentic_requirements():
     """Mock requirements check."""
-    with patch("src.orchestrator_magentic.check_magentic_requirements"):
+    with patch("src.orchestrators.advanced.check_magentic_requirements"):
         yield
 
 

tests/unit/test_orchestrator.py

@@ -4,7 +4,7 @@ from unittest.mock import AsyncMock
 
 import pytest
 
-from src.orchestrator import Orchestrator
+from src.orchestrators import Orchestrator
 from src.utils.models import (
     AgentEvent,
     AssessmentDetails,

tests/unit/test_orchestrator_factory.py

@@ -6,19 +6,18 @@ import pytest
 
 pytestmark = pytest.mark.unit
 
-from src.orchestrator import Orchestrator
-from src.orchestrator_factory import create_orchestrator
+from src.orchestrators import Orchestrator, create_orchestrator
 
 
 @pytest.fixture
 def mock_settings():
-    with patch("src.orchestrator_factory.settings", autospec=True) as mock_settings:
+    with patch("src.orchestrators.factory.settings", autospec=True) as mock_settings:
         yield mock_settings
 
 
 @pytest.fixture
 def mock_magentic_cls():
-    with patch("src.orchestrator_factory._get_magentic_orchestrator_class") as mock:
+    with patch("src.orchestrators.factory._get_advanced_orchestrator_class") as mock:
         # The mock returns a class (callable), which returns an instance
         mock_class = MagicMock()
         mock.return_value = mock_class

tests/unit/test_streaming_fix.py

@@ -59,9 +59,9 @@ async def test_streaming_events_are_buffered_not_spammed():
         assert len(results) > 0, "Should have yielded results"
 
         # Check that we see the accumulated message
-        assert any(
-            "📡 **STREAMING**: This is a test" in r for r in results
-        ), "Buffer didn't accumulate correctly"
+        assert any("📡 **STREAMING**: This is a test" in r for r in results), (
+            "Buffer didn't accumulate correctly"
+        )
 
         # The critical check for the "Spam" bug:
         # In the spam bug, the output grew like:

tests/unit/test_ui_elements.py

@@ -6,17 +6,17 @@ from src.app import create_demo
 def test_examples_include_advanced_mode():
     """Verify that one example entry uses 'advanced' mode."""
     demo, _ = create_demo()
-    assert any(
-        "advanced" == example[1] for example in demo.examples
-    ), "Expected at least one example to be 'advanced' mode"
+    assert any("advanced" == example[1] for example in demo.examples), (
+        "Expected at least one example to be 'advanced' mode"
+    )
 
 
 def test_accordion_label_updated():
     """Verify the accordion label reflects the new, concise text."""
     _, accordion = create_demo()
-    assert (
-        accordion.label == "⚙️ Mode & API Key (Free tier works!)"
-    ), "Accordion label not updated to '⚙️ Mode & API Key (Free tier works!)'"
+    assert accordion.label == "⚙️ Mode & API Key (Free tier works!)", (
+        "Accordion label not updated to '⚙️ Mode & API Key (Free tier works!)'"
+    )
 
 
 def test_orchestrator_mode_info_text_updated():
@@ -25,9 +25,9 @@ def test_orchestrator_mode_info_text_updated():
     # Assuming additional_inputs is a list and the Radio is the first element
     orchestrator_radio = demo.additional_inputs[0]
     expected_info = "⚡ Simple: Free/OpenAI/Anthropic | 🔬 Advanced: OpenAI only"
-    assert isinstance(
-        orchestrator_radio, gr.Radio
-    ), "Expected first additional input to be gr.Radio"
-    assert (
-        orchestrator_radio.info == expected_info
-    ), "Orchestrator Mode info text not updated correctly"
+    assert isinstance(orchestrator_radio, gr.Radio), (
+        "Expected first additional input to be gr.Radio"
+    )
+    assert orchestrator_radio.info == expected_info, (
+        "Orchestrator Mode info text not updated correctly"
+    )