Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

🔬 Deep Research Agent

AI-powered research agent that performs iterative web research and produces cited, structured reports — powered by LangGraph, Gemini, and Tavily.

CI Python 3.11+ License: MIT FastAPI


✨ Key Features

Feature Description
🧠 Query Decomposition Breaks complex queries into targeted sub-queries
🔄 Iterative Research Loop Continues searching until sufficient data is gathered
📝 Cited Reports Markdown reports with inline citations [1], [2]
📊 Citation Analytics Visual breakdown of most-cited domains
🚀 REST API FastAPI backend with OpenAPI docs at /docs
📄 PDF Export Download reports as PDF with one click
🧪 Tested + CI Unit tests, linting, type checks on every PR
🐳 Docker Ready One-command deployment with docker-compose
💾 Semantic Caching ChromaDB-backed cache avoids duplicate API calls
📎 PDF Extraction Agent can download and extract text from PDF sources

🏗 Architecture

Query → Decompose → [Search → Evaluate] → Synthesize → Report
                         ↑         |
                         └─────────┘
                    (continue if needed)
graph LR
    A[User Query] --> B[Decompose]
    B --> C[Search]
    C --> D[Evaluate]
    D -->|Need more| C
    D -->|Sufficient| E[Synthesize]
    E --> F[Cited Report]
    
    style A fill:#667eea,color:#fff
    style F fill:#22c55e,color:#fff
Loading

Components

Component Role
LangGraph StateGraph Manages the ReAct research loop with conditional edges
Gemini 2.5 Flash LLM for decomposition, evaluation, and synthesis
Tavily API Web search with structured results
Streamlit Interactive web UI with analytics dashboard
FastAPI REST API with async job support
ChromaDB Semantic caching for search results
Pydantic v2 Structured, validated outputs throughout

🚀 Quick Start

Prerequisites

Installation

# Clone the repository
git clone https://github.com/YOUR_USERNAME/deep-research-agent.git
cd deep-research-agent

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your API keys

Usage

🖥 Web UI (Streamlit):

streamlit run src/ui/streamlit_app.py

⚡ REST API (FastAPI):

python -m src.api
# Visit http://localhost:8000/docs for interactive API docs

💻 CLI Mode:

python -m src.agent "Your research query here"

🐳 Docker:

docker-compose up
# Streamlit → http://localhost:8501
# API       → http://localhost:8000/docs

📁 Project Structure

deep-research-agent/
├── src/
│   ├── agent/
│   │   ├── graph.py          # LangGraph StateGraph + nodes
│   │   ├── state.py          # TypedDict state schema
│   │   ├── tools.py          # Tavily search integration
│   │   ├── models.py         # Pydantic models (SourceModel, ResearchReport)
│   │   ├── cache.py          # Semantic cache (ChromaDB)
│   │   └── pdf_tool.py       # PDF extraction tool
│   ├── ui/
│   │   ├── streamlit_app.py  # Enhanced Streamlit dashboard
│   │   └── graph_viz.py      # GraphViz rendering utility
│   └── api.py                # FastAPI REST backend
├── tests/
│   ├── test_agent.py         # Agent + model tests
│   └── test_api.py           # API endpoint tests
├── outputs/                  # Generated reports
├── .github/workflows/
│   └── ci.yml                # GitHub Actions CI pipeline
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── .env.example
└── README.md

🧪 Testing

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --tb=short

# Lint
ruff check src/ tests/

# Type check
mypy src/ --ignore-missing-imports

📡 API Endpoints

Method Endpoint Description
GET /health Health check + key status
POST /research Synchronous research (returns full report)
POST /research/async Async research (returns job_id)
GET /research/status/{job_id} Poll async job status

Example request:

curl -X POST http://localhost:8000/research \
  -H "Content-Type: application/json" \
  -d '{"query": "Compare GPT-4 vs Claude 3.5 Sonnet", "depth": "standard"}'

⚙️ Configuration

Env Variable Required Default Description
GEMINI_API_KEY ✅ — Google AI Studio API key
TAVILY_API_KEY ✅ — Tavily search API key
GEMINI_MODEL ❌ gemini-2.5-flash Override Gemini model

📊 Rate Limits

Service Free Tier Per Research
Tavily 1000 credits/month ~3 credits (standard)
Gemini 15 RPM / 1500 RPD ~4-6 calls

🤝 Contributing

  1. Fork the repo
  2. Create a feature branch (git checkout -b feature/amazing)
  3. Commit changes (git commit -m 'Add amazing feature')
  4. Push to branch (git push origin feature/amazing)
  5. Open a Pull Request

The CI pipeline will automatically run lint, type checks, and tests.

📄 License

MIT


Built with ❤️ using LangGraph + Gemini + Tavily

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages