README.md

metadata

title: Deep Research
emoji: 🏆
colorFrom: red
colorTo: green
sdk: gradio
sdk_version: 5.34.0
app_file: src/main.py
pinned: false
license: apache-2.0

Deep Research

Deep Research is an AI-powered research assistant that helps users investigate complex topics by generating clarifying questions, planning web searches, and synthesizing detailed markdown reports.

Features

• Clarification: Asks targeted questions to refine the research query.
• Planning: Suggests up to five web searches to address the query.
• Web Search: Summarizes web results for each planned search.
• Report Generation: Produces a comprehensive markdown report with a summary and follow-up questions.
• Interactive UI: Chat-based Gradio interface for end-to-end research.

Usage

1. Send your research topic in the chat box.
2. Answer the clarifying questions.
3. Receive the detailed report back in the same conversation.

Tech Stack

• Python, Gradio
• openai-agents (for agent orchestration)
• Async/await for non-blocking operations

File Overview

• main.py — Gradio UI and app entry point
• research_manager.py — Orchestrates the research workflow
• research_agent.py — Core agent logic and tool coordination
• clarifier.py — Generates clarifying questions
• planner.py — Plans web search queries
• web_search.py — Summarizes web search results
• report_generator.py — Creates the final markdown report

Setup (with uv)

1. Install Python 3.12 (if not already installed).
2. Install uv:

   pip install uv
   

3. Create enviroment and install dependencies:

   uv sync
   

4. Activate the enviroment

   source .venv/bin/activate #.venv/Scripts/activate on Win
   

5. Run the app:

   uv run src/main.py
   

The app will launch a Gradio interface that you can access in your browser.