Skip to content

Architecture Overview

DeepCritical is a deep research agent system that uses iterative search-and-judge loops to comprehensively answer research questions. The system supports multiple orchestration patterns, graph-based execution, parallel research workflows, and long-running task management with real-time streaming.

Core Architecture

Orchestration Patterns

  1. Graph Orchestrator (src/orchestrator/graph_orchestrator.py):
  2. Graph-based execution using Pydantic AI agents as nodes
  3. Supports both iterative and deep research patterns
  4. Node types: Agent, State, Decision, Parallel
  5. Edge types: Sequential, Conditional, Parallel
  6. Conditional routing based on knowledge gaps, budget, and iterations
  7. Parallel execution for concurrent research loops
  8. Event streaming via AsyncGenerator[AgentEvent] for real-time UI updates

  9. Fallback to agent chains when graph execution is disabled

  10. Deep Research Flow (src/orchestrator/research_flow.py):

  11. Pattern: Planner → Parallel Iterative Loops (one per section) → Synthesis
  12. Uses PlannerAgent to break query into report sections
  13. Runs IterativeResearchFlow instances in parallel per section via WorkflowManager
  14. Synthesizes results using LongWriterAgent or ProofreaderAgent
  15. Supports both graph execution (use_graph=True) and agent chains (use_graph=False)
  16. Budget tracking per section and globally

  17. State synchronization across parallel loops

  18. Iterative Research Flow (src/orchestrator/research_flow.py):

  19. Pattern: Generate observations → Evaluate gaps → Select tools → Execute → Judge → Continue/Complete
  20. Uses KnowledgeGapAgent, ToolSelectorAgent, ThinkingAgent, WriterAgent
  21. JudgeHandler assesses evidence sufficiency
  22. Iterates until research complete or constraints met (iterations, time, tokens)

  23. Supports graph execution and agent chains

  24. Magentic Orchestrator (src/orchestrator_magentic.py):

  25. Multi-agent coordination using agent-framework-core
  26. ChatAgent pattern with internal LLMs per agent
  27. Uses MagenticBuilder with participants: searcher, hypothesizer, judge, reporter
  28. Manager orchestrates agents via OpenAIChatClient
  29. Requires OpenAI API key (function calling support)
  30. Event-driven: converts Magentic events to AgentEvent for UI streaming

  31. Supports long-running workflows with max rounds and stall/reset handling

  32. Hierarchical Orchestrator (src/orchestrator_hierarchical.py):

  33. Uses SubIterationMiddleware with ResearchTeam and LLMSubIterationJudge
  34. Adapts Magentic ChatAgent to SubIterationTeam protocol
  35. Event-driven via asyncio.Queue for coordination

  36. Supports sub-iteration patterns for complex research tasks

  37. Legacy Simple Mode (src/legacy_orchestrator.py):

  38. Linear search-judge-synthesize loop
  39. Uses SearchHandlerProtocol and JudgeHandlerProtocol
  40. Generator-based design yielding AgentEvent objects
  41. Backward compatibility for simple use cases

Long-Running Task Support

The system is designed for long-running research tasks with comprehensive state management and streaming:

  1. Event Streaming:
  2. All orchestrators yield AgentEvent objects via AsyncGenerator
  3. Real-time UI updates through Gradio chat interface
  4. Event types: started, searching, search_complete, judging, judge_complete, looping, synthesizing, hypothesizing, complete, error

  5. Metadata includes iteration numbers, tool names, result counts, durations

  6. Budget Tracking (src/middleware/budget_tracker.py):

  7. Per-loop and global budget management
  8. Tracks: tokens, time (seconds), iterations
  9. Budget enforcement at decision nodes
  10. Token estimation (~4 chars per token)
  11. Early termination when budgets exceeded

  12. Budget summaries for monitoring

  13. Workflow Manager (src/middleware/workflow_manager.py):

  14. Coordinates parallel research loops
  15. Tracks loop status: pending, running, completed, failed, cancelled
  16. Synchronizes evidence between loops and global state
  17. Handles errors per loop (doesn't fail all if one fails)
  18. Supports loop cancellation and timeout handling

  19. Evidence deduplication across parallel loops

  20. State Management (src/middleware/state_machine.py):

  21. Thread-safe isolation using ContextVar for concurrent requests
  22. WorkflowState tracks: evidence, conversation history, embedding service
  23. Evidence deduplication by URL
  24. Semantic search via embedding service
  25. State persistence across long-running workflows

  26. Supports both iterative and deep research patterns

  27. Gradio UI (src/app.py):

  28. Real-time streaming of research progress
  29. Accordion-based UI for pending/done operations
  30. OAuth integration (HuggingFace)
  31. Multiple backend support (API keys, free tier)
  32. Handles long-running tasks with progress indicators
  33. Event accumulation for pending operations

Graph Architecture

The graph orchestrator (src/orchestrator/graph_orchestrator.py) implements a flexible graph-based execution model:

Node Types:

  • Agent Nodes: Execute Pydantic AI agents (e.g., KnowledgeGapAgent, ToolSelectorAgent)
  • State Nodes: Update or read workflow state (evidence, conversation)
  • Decision Nodes: Make routing decisions (research complete?, budget exceeded?)
  • Parallel Nodes: Execute multiple nodes concurrently (parallel research loops)

Edge Types:

  • Sequential Edges: Always traversed (no condition)
  • Conditional Edges: Traversed based on condition (e.g., if research complete → writer, else → tool selector)
  • Parallel Edges: Used for parallel execution branches

Graph Patterns:

  • Iterative Graph: [Input] → [Thinking] → [Knowledge Gap] → [Decision: Complete?] → [Tool Selector] or [Writer]
  • Deep Research Graph: [Input] → [Planner] → [Parallel Iterative Loops] → [Synthesizer]

Execution Flow:

  1. Graph construction from nodes and edges
  2. Graph validation (no cycles, all nodes reachable)
  3. Graph execution from entry node
  4. Node execution based on type
  5. Edge evaluation for next node(s)
  6. Parallel execution via asyncio.gather()
  7. State updates at state nodes
  8. Event streaming for UI

Key Components

  • Orchestrators: Multiple orchestration patterns (src/orchestrator/, src/orchestrator_*.py)
  • Research Flows: Iterative and deep research patterns (src/orchestrator/research_flow.py)
  • Graph Builder: Graph construction utilities (src/agent_factory/graph_builder.py)
  • Agents: Pydantic AI agents (src/agents/, src/agent_factory/agents.py)
  • Search Tools: PubMed, ClinicalTrials.gov, Europe PMC, RAG (src/tools/)
  • Judge Handler: LLM-based evidence assessment (src/agent_factory/judges.py)
  • Embeddings: Semantic search & deduplication (src/services/embeddings.py)
  • Statistical Analyzer: Modal sandbox execution (src/services/statistical_analyzer.py)
  • Middleware: State management, budget tracking, workflow coordination (src/middleware/)
  • MCP Tools: Claude Desktop integration (src/mcp_tools.py)
  • Gradio UI: Web interface with MCP server and streaming (src/app.py)

Research Team & Parallel Execution

The system supports complex research workflows through:

  1. WorkflowManager: Coordinates multiple parallel research loops
  2. Creates and tracks ResearchLoop instances
  3. Runs loops in parallel via asyncio.gather()
  4. Synchronizes evidence to global state

  5. Handles loop failures gracefully

  6. Deep Research Pattern: Breaks complex queries into sections

  7. Planner creates report outline with sections
  8. Each section runs as independent iterative research loop
  9. Loops execute in parallel
  10. Evidence shared across loops via global state

  11. Final synthesis combines all section results

  12. State Synchronization: Thread-safe evidence sharing

  13. Evidence deduplication by URL
  14. Global state accessible to all loops
  15. Semantic search across all collected evidence
  16. Conversation history tracking per iteration

Configuration & Modes

  • Orchestrator Factory (src/orchestrator_factory.py):
  • Auto-detects mode: "advanced" if OpenAI key available, else "simple"
  • Supports explicit mode selection: "simple", "magentic", "advanced"

  • Lazy imports for optional dependencies

  • Research Modes:

  • iterative: Single research loop
  • deep: Multi-section parallel research

  • auto: Auto-detect based on query complexity

  • Execution Modes:

  • use_graph=True: Graph-based execution (parallel, conditional routing)
  • use_graph=False: Agent chains (sequential, backward compatible)