<div align="center">

🔬 Autonomous Deep Research Flow

An AI-powered research pipeline that thinks, plans, researches, fact-checks and reports — automatically

---

---

💡 "I wanted to build something that could do real, deep research on any topic — not just a single web search, but a full pipeline that plans, researches in parallel, fact-checks, and produces a structured report. So I built it."

— Pradeep Kumar

---

</div>

---

📌 Table of Contents

• 🌟 Why I Built This
• ✨ Key Features
• 🏗️ System Architecture
• 🔄 How the Flow Works
• 🤖 The AI Agents
• 🛠️ Tools Used
• ⚙️ Installation & Setup
• 🚀 How to Run
• 📊 Example Output
• 📁 Project Structure
• 🔮 Future Improvements
• 👤 Author

---

🌟 Why I Built This

Standard AI chatbots give you a single answer from a single model. But real research requires planning, exploring multiple angles, verifying facts, and synthesizing everything into a structured report.

I built this system to do exactly that — autonomously. It uses a CrewAI Flow to intelligently decide whether a query needs deep research or a simple answer, then routes it through a parallel multi-agent pipeline that plans, researches, fact-checks, and produces a professional report — all without human intervention.

The system even remembers previous sessions (via persistence) and generates charts from research data automatically.

---

✨ Key Features

| Feature | Description | |--------|-------------| | 🧠 Intelligent Query Routing | Automatically decides: simple answer vs. deep research | | 🔄 CrewAI Flow Orchestration | Full stateful flow with persistence across sessions | | ⚡ Parallel Research | Main and secondary topics researched simultaneously | | 🔍 Exa AI Search | Semantic web search for high-quality, relevant sources | | ✅ Built-in Guardrails | Enforces Summary, Insights, and Citations sections | | 📊 Auto Chart Generation | Automatically creates charts from research data | | 💾 Session Persistence | Remembers your previous queries across runs | | 🔎 Observability & Tracing | Full tracing enabled for monitoring and debugging | | 📄 Markdown Report Output | Saves complete research report to research_report.md |

---

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    DEEP RESEARCH FLOW                           │
│                                                                 │
│  [User Query]                                                   │
│       │                                                         │
│  ┌────▼──────────┐                                              │
│  │ start_        │ ← Entry point, remembers past sessions       │
│  │ conversation  │                                              │
│  └────┬──────────┘                                              │
│       │                                                         │
│  ┌────▼──────────┐                                              │
│  │ analyze_query │ ← Router: SIMPLE or RESEARCH?               │
│  └────┬──────────┘                                              │
│       │                                                         │
│  ┌────┴──────────────────────┐                                  │
│  │                           │                                  │
│  ▼ "SIMPLE"              ▼ "RESEARCH"                          │
│  ┌──────────┐        ┌───────────────┐                         │
│  │ simple_  │        │ clarify_query │                         │
│  │ answer   │        └───────┬───────┘                         │
│  └────┬─────┘                │                                  │
│       │               ┌──────▼──────────────────────────────┐  │
│       │               │     PARALLEL DEEP RESEARCH CREW     │  │
│       │               │                                     │  │
│       │               │  Research Planner → breaks query    │  │
│       │               │  Topic Researcher → main topics ──┐ │  │
│       │               │  Topic Researcher → secondary   ──┤ │  │
│       │               │  Fact Checker → validates main  ◄─┤ │  │
│       │               │  Fact Checker → validates sec.  ◄─┘ │  │
│       │               │  Report Writer → final report       │  │
│       │               └──────┬──────────────────────────────┘  │
│       │               ┌──────▼──────────┐                      │
│       │               │ save_report_    │ ← Saves .md + charts │
│       │               │ and_summarize   │                      │
│       │               └──────┬──────────┘                      │
│       │                      │                                  │
│  ┌────▼──────────────────────▼──┐                               │
│  │     return_final_answer      │ ← Returns to user             │
│  └──────────────────────────────┘                               │
└─────────────────────────────────────────────────────────────────┘

---

🔄 How the Flow Works

1. 🎤  User enters research query
         │
2. 🤔  Flow analyzes complexity → routes to SIMPLE or RESEARCH
         │
   ┌─────┴──────────────────────┐
   │ SIMPLE                RESEARCH
   │                            │
3a.💬 Direct LLM answer   3b.❓ Clarify query if needed
         │                      │
         │               4. 🚀  Parallel research crew kicks off:
         │                      ├── Research Planner splits topics
         │                      ├── Researcher covers main topics ─┐
         │                      ├── Researcher covers secondary  ──┤ parallel
         │                      ├── Fact checker validates main  ◄─┘
         │                      └── Report writer synthesizes all
         │                      │
         │               5. 💾  Full report saved to research_report.md
         │                      │
         └──────────────────────┘
                  │
6. 📤  Final answer returned to user

---

🤖 The AI Agents

🗺️ Agent 1 — Research Planner

• Role: Breaks the query into MAIN (core) and SECONDARY (supporting) topics
• Goal: Create a strategic research plan for parallel execution

🔍 Agent 2 — Topic Researcher

• Role: Researches both topic branches simultaneously using live web search
• Goal: Gather comprehensive, cited information from credible sources
• Tools: EXASearchTool, ScrapeWebsiteTool

✅ Agent 3 — Fact Checker

• Role: Validates all research data for accuracy and consistency
• Goal: Identify misinformation, hallucinations, and unsupported claims
• Tools: EXASearchTool, ScrapeWebsiteTool

📝 Agent 4 — Report Writer

• Role: Synthesizes all validated data into a structured report
• Goal: Produce a clear, well-cited report that answers the original query
• Guardrail: Report must include Summary, Insights, and Citations sections

---

🛠️ Tools Used

| Tool | Purpose | |------|---------| | 🔍 EXASearchTool | Semantic AI-powered web search for high-quality sources | | 🌐 ScrapeWebsiteTool | Extracts full content from identified web pages | | 📊 ChartGeneratorTool | Auto-generates charts from research data using matplotlib | | 🧠 GPT-4o-mini | Powers all agents and flow routing decisions | | 💾 CrewAI Persistence | Saves flow state to database across sessions |

---

⚙️ Installation & Setup

Prerequisites

• Python 3.10+
• OpenAI API Key → Get one here
• Exa API Key → Get one here

Install Dependencies

cd deep_research_flow
pip install -e .

Configure API Keys

cp .env.example .env

Then open .env and fill in your keys:

OPENAI_API_KEY=your-openai-api-key-here
EXA_API_KEY=your-exa-api-key-here

---

🚀 How to Run

# 1. Clone the repository
git clone https://github.com/Pradeep-Kumar25th/autonomous-deep-research-flow.git
cd autonomous-deep-research-flow

# 2. Install dependencies
cd deep_research_flow
pip install -e .

# 3. Set up API keys
cp .env.example .env   # fill in your keys

# 4. Run the flow
python -m deep_research_flow.main

# OR use the project script
kickoff

💡 Example Queries to Try

# Simple query (direct answer)
"What is the capital of France?"

# Research query (triggers full pipeline)
"What are the latest developments in quantum computing and its impact on cryptography?"
"Analyze the growth of renewable energy in India over the last 5 years"
"What are the key risks and opportunities in the Indian startup ecosystem in 2025?"

---

📊 Example Output

🔍 Deep Research Flow started
What would you like to research?
>> What are the latest AI agent frameworks in 2025?

🤔 Analyzing query complexity...
📚 Complex query detected — initiating deep research pipeline
🔍 Reviewing query for research clarity...
🚀 Executing deep research crew...

[Agents research in parallel...]

✅ Research completed successfully!
📄 Full report saved to research_report.md

📝 Final Answer:
Here is a summary of the research findings:

In 2025, the AI agent framework landscape has evolved significantly,
with CrewAI, LangGraph, and AutoGen leading adoption...

[Full report available in research_report.md]
✨ Deep Research Flow completed!

---

📁 Project Structure

autonomous-deep-research-flow/
 ┣ deep_research_flow/
 ┃  ┣ src/deep_research_flow/
 ┃  ┃  ┣ crews/deep_research_crew/
 ┃  ┃  ┃  ┣ config/
 ┃  ┃  ┃  ┃  ┣ agents.yaml       ← Agent definitions
 ┃  ┃  ┃  ┃  ┗ tasks.yaml        ← Task definitions
 ┃  ┃  ┃  ┣ guardrails/
 ┃  ┃  ┃  ┃  ┗ guardrails.py     ← Report quality guardrail
 ┃  ┃  ┃  ┗ crew.py              ← Parallel research crew
 ┃  ┃  ┣ tools/
 ┃  ┃  ┃  ┗ chart_generator_tool.py  ← Auto chart generation
 ┃  ┃  ┗ main.py                 ← Flow orchestrator
 ┃  ┣ knowledge/
 ┃  ┃  ┗ user_preference.txt     ← User context for agents
 ┃  ┗ pyproject.toml             ← Dependencies
 ┣ README.md
 ┣ .env.example
 ┗ .gitignore

---

🔮 Future Improvements

• [ ] 🌐 Web UI using Streamlit for interactive research sessions
• [ ] 📧 Email delivery of completed research reports
• [ ] 🗄️ Vector database integration for research history search
• [ ] 🌍 Multi-language research support
• [ ] 📱 Telegram/WhatsApp bot interface
• [ ] 🔁 Scheduled research — run automatically on a topic daily/weekly

---

👤 Author

<div align="center">

Built with ❤️ by Pradeep Kumar

Passionate about AI Agents, multi-agent systems, and building tools that automate complex real-world tasks.

Made with 🤖 CrewAI • 🧠 OpenAI • 🔍 Exa AI • 🐍 Python

</div>