DeepResearchAI 🔬

An autonomous multi-agent deep research system featuring a Next.js + shadcn/ui modern frontend and a FastAPI + LangChain + LangGraph asynchronous backend.

The platform orchestrates four specialized AI agents to discover, extract, synthesize, and peer-review publication-ready research reports on any topic in real-time.

---

🏛️ System Architecture

flowchart LR
    subgraph Frontend ["Frontend (Next.js 16 + shadcn/ui)"]
        UI[Interactive Dashboard]
        LiveStream[SSE Event Streamer]
        Viewer[Markdown Report Viewer]
        Review[Critic Evaluation Card]
    end

    subgraph Backend ["Backend (FastAPI)"]
        API[FastAPI Server - /backend/main.py]
        Engine[Pipeline Orchestrator - /backend/pipeline.py]
        
        subgraph Agents ["Multi-Agent Pipeline"]
            A1[01 Search Agent]
            A2[02 Reader Agent]
            A3[03 Writer Chain]
            A4[04 Critic Chain]
        end
    end

    UI -->|SSE / REST| API
    API --> Engine
    Engine --> A1
    Engine --> A2
    Engine --> A3
    Engine --> A4
    A1 -->|Query| Tavily[(Tavily API)]
    A2 -->|Scrape| Web[(Target Webpage)]
    A3 -->|Draft| LLM[(Groq LLM)]
    A4 -->|Critique| LLM

Loading

---

📁 Repository Structure

DeepResearchAI/
├── backend/
│   ├── main.py              # FastAPI server with REST & SSE endpoints
│   ├── agents.py            # LangChain/LangGraph agent & chain definitions
│   ├── pipeline.py          # 4-stage research pipeline (sync, async, & SSE generator)
│   ├── tools.py             # Tavily web search & resilient web scraper tools
│   ├── requirements.txt     # Python dependencies
│   ├── .env                 # API keys (Groq, Tavily)
│   ├── .env.example         # Template configuration
│   └── app.py               # (Optional) Legacy Streamlit interface
│
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   │   ├── layout.tsx   # Next.js root layout
│   │   │   ├── page.tsx     # DeepResearchAI interactive dashboard
│   │   │   └── globals.css  # Dark theme styling & glow effects
│   │   ├── components/
│   │   │   ├── ui/          # shadcn/ui components (Button, Card, Badge, Input, Progress)
│   │   │   ├── StepProgress.tsx # Real-time visual agent pipeline tracker
│   │   │   ├── ReportViewer.tsx # Markdown report viewer with copy & download
│   │   │   ├── CriticCard.tsx   # Peer review scorecard & analysis
│   │   │   └── RawExpander.tsx  # Collapsible viewer for raw search & scrape data
│   │   └── lib/
│   │       ├── api.ts       # Backend REST & SSE client
│   │       └── utils.ts     # shadcn classnames helper
│   ├── package.json         # Node.js dependencies (Next.js, Tailwind v4, Lucide)
│   └── tsconfig.json        # TypeScript configuration
│
├── package.json             # Root helper scripts
├── .gitignore               # Ignored build and secret files
└── README.md                # Project documentation

---

⚡ Quick Start

1. Configure Backend Environment

Navigate into /backend and create your .env file:

cd backend
cp .env.example .env

Ensure your keys are added to backend/.env:

GROQ_API_KEY=your_groq_api_key_here
TAVILY_API_KEY=your_tavily_api_key_here
GROQ_MODEL=qwen/qwen3.8-27b
PORT=8000

2. Launch the Entire System (One Command)

From the root directory, simply run:

python run.py

This starts both the FastAPI backend (http://127.0.0.1:8000) and the Next.js frontend (http://localhost:3000) concurrently with unified color-coded logging and auto-opens your browser. Press Ctrl+C at any time to cleanly stop all services.

Launcher Options:

python run.py                 # Run both backend and frontend
python run.py --backend       # Run only the FastAPI backend
python run.py --frontend      # Run only the Next.js frontend
python run.py --no-open       # Don't auto-open browser
python run.py --backend-port 8000 --frontend-port 3000

Alternatively, you can run services individually in separate terminals:

# Terminal 1: Backend
cd backend && uvicorn main:app --reload --port 8000

# Terminal 2: Frontend
cd frontend && npm run dev

---

📡 Backend API Endpoints

Method	Route	Description
GET	/	API status and overview
GET	/health	Health check for Groq and Tavily credentials
POST	/api/research	Full 4-step pipeline asynchronous execution
GET	/api/research/stream?topic=...	Live Server-Sent Events (SSE) progress streaming
POST	/api/search	Search Agent standalone execution
POST	/api/scrape	Webpage extraction standalone execution
POST	/api/write	Writer Chain report generation from raw notes
POST	/api/critique	Critic Chain report review and grading

---

🖥️ Frontend Features

• Live Agent Timeline: Real-time stage indicators with pulse animations, step status badges, and duration timers.
• Server-Sent Events (SSE) Streaming: Instant feedback streamed directly from FastAPI as agents execute.
• Markdown Report Viewer: Beautiful typography with copy to clipboard, reading time estimation, and .md file download.
• Peer-Review Scorecard: Visual score out of 10, key strengths, constructive feedback, and final verdict.
• Raw Data Expanders: Inspect raw search snippets and scraped webpage text at any time.
• Connection Health Monitor: Automatic polling of backend status with live online/offline indicator.