AI-powered research agent that performs iterative web research and produces cited, structured reports — powered by LangGraph, Gemini, and Tavily.
| 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 |
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
| 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 |
- Python 3.11+
- API keys from:
- Google AI Studio → Gemini API key
- Tavily → Search API key
# 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🖥 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/docsdeep-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
# 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| 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"}'| 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 |
| Service | Free Tier | Per Research |
|---|---|---|
| Tavily | 1000 credits/month | ~3 credits (standard) |
| Gemini | 15 RPM / 1500 RPD | ~4-6 calls |
- Fork the repo
- Create a feature branch (
git checkout -b feature/amazing) - Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing) - Open a Pull Request
The CI pipeline will automatically run lint, type checks, and tests.
MIT
Built with ❤️ using LangGraph + Gemini + Tavily