tags	Agent Research LLM DeepResearch
deployspec	entry_file src/deep_research/gui.py
license	MIT

Deep Research Agent

An autonomous research assistant powered by LLMs, designed to perform deep information gathering, multi-step reasoning, and structured report synthesis.

🌐 Try it Online

🌟 Key Features

• Multi-Agent Orchestration: A specialized Orchestrator decomposes goals into sub-tasks, delegated to focused SubAgents for deep investigation.
• Robust ReAct Framework: Built on a unified BaseReActAgent abstraction, ensuring consistent reasoning, acting, and context management across all agent roles.
• Real-time Event Streaming: Powered by a custom StreamHandler, providing live feedback on Thoughts, Actions, and tool outputs.
• Powerful Toolset:
  • Smart Search: Integrated with DuckDuckGo for up-to-date web discovery.
  • High-Precision Scraping: Uses Trafilatura and Playwright for clean content extraction and JavaScript rendering support.
  • Multi-Format Parsing: Built-in support for PDF analysis and Markdown conversion via MarkItDown.
• Interactive UI: A modern Streamlit-based dashboard for visualizing the research process and managing loops.

🛠️ Technical Stack

• Core: Python 3.12+
• Agent Framework: Custom ReAct orchestration with OpenAI-compatible API integration.
• UI: Streamlit
• Package Management: uv

🚀 Quick Start

1. Installation

Ensure you have uv installed, then run:

# Clone the repository
git clone <repo-url>
cd deep-research

# Install dependencies and setup virtual environment
uv sync

2. Configuration

Create a .env file in the project root:

OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
MODEL_NAME=gpt-4o  # Or your preferred model

3. Usage

Start the interactive research interface:

uv run dr

📂 Project Structure

• src/deep_research/
  • agents/: Core agent roles (Orchestrator, SubAgent, Validator) inheriting from a shared BaseAgent.
  • core/: Infrastructure layer including LLMClient, Log, and StreamHandler.
  • tools/: Extensible tool modules and the ToolRegistry manager.
  • prompts/: Role-specific system instructions and templates.
  • models.py: Shared data models for events and pulses.
  • config.py: Global configuration and environment management.
  • gui.py: Streamlit frontend implementation.

🔗 Reference

• MiroThinker

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.