Hugging Face's logo

Spaces:
Visal9252
/
ResearchPilot-AI
Sleeping

App Files Community
ResearchPilot-AI / README.md
Visal9252's picture
Visal9252
Update README.md
cf58d99 verified
preview code
|
Raw
History Blame Contribute Delete
26.7 kB
---
title: 'ResearchPilot AI '
sdk: docker
emoji: 🌍
colorFrom: indigo
colorTo: purple
thumbnail: >-
 https://cdn-uploads.huggingface.co/production/uploads/64ea5e1dc68ddc867b5ec02f/r8wTLNQPQIfsQjgazt_I5.png
short_description: ResearchPilot AI is an Autonomous Multi-Agent Research Syste
---
<div align="center">
# 🧭 ResearchPilot AI
### Autonomous Multi-Agent Research System
**Give it a topic → Get a complete, evidence-backed research report with charts, citations, and PDF export.**
ResearchPilot AI runs a coordinated team of specialised AI agents — each with a focused job — orchestrated by LangGraph. It plans, routes, searches, analyses, fact-checks, visualises, writes, and self-grades, all from one query.
[![Python](https://img.shields.io/badge/Python-3.11+-3776AB?logo=python&logoColor=white)](https://python.org)
[![LangGraph](https://img.shields.io/badge/LangGraph-Orchestration-7C3AED)](https://langchain-ai.github.io/langgraph/)
[![Groq](https://img.shields.io/badge/Groq-Llama_3.3_70B-F97316)](https://groq.com)
[![Streamlit](https://img.shields.io/badge/UI-Streamlit-FF4B4B?logo=streamlit&logoColor=white)](https://streamlit.io)
[![Plotly](https://img.shields.io/badge/Charts-Plotly-3F4F75)](https://plotly.com)
[![ReportLab](https://img.shields.io/badge/PDF-ReportLab-1E3A5F)](https://www.reportlab.com)
[![License: MIT](https://img.shields.io/badge/License-MIT-22C55E)](LICENSE)
[🚀 Live Demo](#) · [📄 Report Sample](#) · [👨‍💻 Portfolio](https://vishal-lazrus-portfolio.vercel.app/)
</div>
---
## 📌 Table of Contents
| # | Section |
|---|---|
| 1 | [What is ResearchPilot AI?](#-what-is-researchpilot-ai) |
| 2 | [What Makes It Different](#-what-makes-it-different) |
| 3 | [Architecture](#-architecture) |
| 4 | [How It Works — Real Example](#-how-it-works--real-example) |
| 5 | [Folder Structure](#-folder-structure) |
| 6 | [The Five Agents](#-the-five-agents) |
| 7 | [The Six Chart Types](#-the-six-chart-types) |
| 8 | [Getting API Keys (Free)](#-getting-api-keys-free) |
| 9 | [Installation & Setup](#-installation--setup) |
| 10 | [Running the Project](#-running-the-project) |
| 11 | [Deploy to Hugging Face Spaces](#-deploy-to-hugging-face-spaces) |
| 12 | [Concepts Covered](#-concepts-covered) |
| 13 | [Troubleshooting](#-troubleshooting) |
| 14 | [Roadmap](#-roadmap) |
| 15 | [Connect With Me](#-connect-with-me) |
---
## 🤔 What is ResearchPilot AI?
ResearchPilot AI is a **multi-agent AI research system** built with LangGraph. You type one query — say, *"Impact of AI on healthcare market growth"* — and it autonomously runs an 8-node pipeline:
```
Query → Plan → Route → Research + Analyse → Visualise → Write → Grade → Deliver
```
The system produces:
- ✅ A **structured markdown report** (Executive Summary → Key Findings → Analysis → Expert Perspective → Conclusion → References)
- 📊 Up to **6 interactive Plotly charts** generated from real statistical data
- 📄 A **professional academic PDF** with embedded charts and APA citations
- 🗂️ A **CSV file** of the raw statistics for further analysis
> This is not a chatbot wrapper. It implements the **planner → router → workers → critic** pattern used in production agentic AI systems.
### Who is this for?
| 🎓 Students | 💼 Professionals | 🧑‍💻 Developers |
|---|---|---|
| Research papers, literature reviews, assignment prep | Market research, competitive analysis, technology evaluation | Learn LangGraph, conditional routing, agentic design patterns |
---
## ✨ What Makes It Different
| Feature | What it does |
|---|---|
| 🔀 **Dynamic Router Agent** | One LLM call decides *per-query* which of 5 specialist agents to activate. A history question never wastes time running a Statistics agent. A finance query gets Fact Checker. Nothing runs unless it adds value. |
| 📊 **Statistics → Charts pipeline** | The Statistics agent returns *structured JSON* (not prose) — metrics, time-series, regional breakdowns — which directly drives 6 Plotly chart types with no extra LLM calls. |
| 🎓 **Persona-driven Domain Expert** | Adopts a credentialed persona per domain ("Dr. Sarah Chen, Harvard physician" for healthcare; "Marcus Reid, ex-Goldman analyst" for finance) — sharper than a generic "you are an expert" prompt. |
| ✅ **Dedicated Fact Checker** | Extracts specific claims, runs independent search evidence per claim, labels each: Verified / Partially True / Disputed / Unverifiable. |
| 🏆 **Self-grading + auto-retry** | Quality Gate scores the report 0–10 against five weighted criteria. Below 7 → automatic retry with explicit feedback. Capped at 2 retries to prevent runaway cost. |
| 🖼️ **Cover runs after scoring** | The SVG cover card is generated *last* — after Quality Gate — so it always shows the real quality score, not zero. |
| 📄 **ReportLab academic PDF** | Flowable single-column layout, deep-blue academic headings, horizontal rule separators, charts embedded directly under their matching report section. |
---
## 🏗️ Architecture
> **Exact node execution order as wired in `graph/graph_builder.py`:**
```
 ┌─────────────────────────────────┐
 │ USER QUERY │
 └────────────────┬────────────────┘
 │
 ▼
 ┌──────────────────┐
 │ 🧠 PLANNER │
 │ │
 │ • Detects domain │
 │ • Builds 3 tasks │
 └────────┬─────────┘
 │
 ▼
 ┌──────────────────┐
 │ 🔀 ROUTER │
 │ │
 │ Single LLM call │
 │ → active_agents │
 │ list in state │
 └────────┬─────────┘
 │
 ▼
 ┌─────────────────────────────────────────────────────────┐
 │ ⚙️ WORKERS NODE │
 │ Only activated agents run │
 │ │
 │ ┌────────────┐ ┌────────────┐ ┌──────────────────┐ │
 │ │ 🔍Research │ │ 📊Stats │ │ 🎓Domain Expert │ │
 │ │ │ │ │ │ │ │
 │ │ 3 Tavily │ │ Structured │ │ Persona prompt │ │
 │ │ searches │ │ JSON → │ │ per domain │ │
 │ │ → LLM │ │ chart data │ │ │ │
 │ └─────┬──────┘ └─────┬──────┘ └────────┬─────────┘ │
 │ │ │ │ │
 │ ┌─────┴──────┐ ┌─────┴──────┐ │ │
 │ │ ✅Fact │ │ 📖Refs │ │ │
 │ │ Checker │ │ │ │ │
 │ │ Claim-by- │ │ APA format │ │ │
 │ │ claim │ │ citations │ │ │
 │ └─────┬──────┘ └─────┬──────┘ │ │
 │ │ │ │ │
 │ └───────────────┴──────┬────────────┘ │
 │ Virtual File System │
 │ (shared dict living in state) │
 └───────────────────────────┬─────────────────────────────┘
 │
 ▼
 ┌──────────────────┐
 │ 📈 VISUALIZATION │
 │ │
 │ Statistics JSON │
 │ → 6 Plotly charts│
 │ (no LLM call) │
 └────────┬─────────┘
 │
 ▼
 ┌──────────────────┐
 │ ✍️ WRITER │
 │ │
 │ Reads all 5 VFS │
 │ files → builds │
 │ final report │
 └────────┬─────────┘
 │
 ▼
 ┌──────────────────┐
 ┌────────┤ 🏆 QUALITY GATE │◄────────────────────┐
 │ │ │ │
 │ │ LLM scores 0-10 │ │
 │ └────────┬─────────┘ │
 │ │ │
 │ score ≥ 7 │ score < 7 (max 2 retries) │
 │ ┌────────┘ └──────────────────────► Writer
 │ ▼
 │ ┌──────────────────┐
 │ │ 🖼️ COVER │
 │ │ │
 │ │ SVG card with │
 │ │ real score baked │
 │ │ in (runs last) │
 │ └────────┬─────────┘
 │ │
 └──────────┘
 │
 ▼
 STREAMLIT UI
 ┌────────────────────────────────┐
 │ 🔬 Research │ 📊 Data&Charts │
 │ 📖 References│ 📄 Report │
 │ │ ⏱️ Trace │
 └────────────────────────────────┘
 MD · CSV · PDF downloads
```
---
## ⚡ How It Works — Real Example
**Query typed:** `"Impact of AI on healthcare market growth: adoption rates, investment trends and future outlook"`
| Step | Node | What happens |
|---|---|---|
| 1 | **Planner** | Detects `topic_domain = "healthcare"`. Creates tasks: search clinical data, find market numbers, locate key organisations. |
| 2 | **Router** | One LLM call → `["research", "statistics", "domain_expert", "fact_checker", "citation"]`. All 5 activate because healthcare needs everything. |
| 3a | **Research** | Runs 3 Tavily searches: raw query + "latest developments 2025" + "key findings evidence". LLM synthesises into structured deep-research. Writes `research_deep.txt` to VFS. |
| 3b | **Statistics** | Searches for "$45B market size", "29% CAGR" etc. Forces LLM to return exact JSON schema (metrics array + trends array + comparisons array). Writes `statistics.txt` + `statistics_data.csv`. |
| 3c | **Domain Expert** | Persona: *"Dr. Sarah Chen, Harvard-trained physician"*. Reads `research_deep.txt`, adds clinical nuance. Writes `expert_analysis.txt`. |
| 3d | **Fact Checker** | Extracts 6 specific claims. Verifies 4 individually via fresh Tavily searches. Labels ✅/⚠️/❌. Writes `fact_check.txt`. |
| 3e | **References** | Formats all sources from `raw_search.txt` into APA JSON. Writes `references.txt`. Returns structured `citations` list. |
| 4 | **Visualization** | No LLM call. Reads `structured_data` dict → builds 6 Plotly figures → stores as JSON strings in `chart_json`. |
| 5 | **Writer** | Checks each VFS key. Builds context from whichever files exist. One large LLM call produces 9-section markdown report. |
| 6 | **Quality Gate** | LLM scores the report: **7.5/10**. `should_retry()` returns `"done"`. Routes to Cover. |
| 7 | **Cover** | Now has `quality_score = 7.5`. Generates SVG card with real score baked in. |
| **End** | **UI** | 5 sections rendered. Download MD + CSV + PDF available. |
---
## 📁 Folder Structure
```
ResearchPilot AI/ ← root folder
│
├── graph/ ← LangGraph nodes (the "brain")
│ ├── __init__.py
│ ├── state.py ← ResearchState TypedDict — shared memory
│ │ every node reads from and writes to
│ ├── llm_factory.py ← get_llm() — Groq primary, Gemini fallback
│ │ every node imports this, never hardcodes
│ ├── planner.py ← Node 1: detects domain, builds task list
│ ├── router.py ← Node 2: LLM → active_agents list
│ ├── workers.py ← Node 3: all 5 specialist agents
│ │ conditionally called by if "agent" in active_agents
│ ├── visualization.py ← Node 4: structured_data JSON → 6 Plotly charts
│ │ (no LLM call — pure Python/Plotly)
│ ├── synthesizer.py ← Node 5 (displayed as "Writer"):
│ │ reads VFS → one LLM call → final report
│ ├── quality_gate.py ← Node 6: scores report + should_retry() function
│ │ drives the conditional edge / retry loop
│ ├── thumbnail.py ← Node 7 (displayed as "Cover"):
│ │ runs AFTER quality_gate so score exists
│ └── graph_builder.py ← Wires all 7 nodes + edges + conditional edge
│ into one compiled StateGraph object
│
├── tools/ ← Utilities used by nodes (not nodes themselves)
│ ├── __init__.py
│ ├── search_tool.py ← web_search() wraps Tavily API
│ │ returns plain string for LLM context
│ ├── file_system.py ← vfs_write() / vfs_read() helpers
│ │ copy-on-write to keep state immutable
│ └── pdf_generator.py ← ReportLab flowable PDF
│ strips duplicate References section,
│ embeds charts under matching headings
│
├── ui/
│ └── app.py ← Single-page Streamlit UI (~800 lines)
│ st.session_state caches results so
│ download clicks don't re-run the pipeline
│
├── .streamlit/
│ └── config.toml ← Dark theme + port 7860 for HF Spaces
│
├── Dockerfile ← Production Docker image for HF Spaces
├── main.py ← Terminal test runner (no UI)
├── app.py ← HF Spaces entry point
├── requirements.txt
├── .env.example ← API key template
├── .gitignore ← Excludes .env, __pycache__, *.pdf
└── README.md
```
---
## 🤖 The Five Agents
| Agent | File | Activates when | What it produces |
|---|---|---|---|
| **Research** | `workers.py` | Always | 3-angle Tavily search + LLM synthesis → `research_deep.txt` |
| **Statistics** | `workers.py` | Topic has numbers/trends | Structured JSON (metrics + trends + comparisons) + CSV → `statistics.txt` |
| **Domain Expert** | `workers.py` | Specialised topic | Persona-primed analysis → `expert_analysis.txt` |
| **Fact Checker** | `workers.py` | Claims need verification | Per-claim Tavily verify → `fact_check.txt` |
| **References** | `workers.py` | Citations add value | APA-formatted JSON list → `references.txt` |
All agents share data through the **Virtual File System** — a `Dict[str, str]` inside LangGraph state. Zero disk I/O.
---
## 📊 The Six Chart Types
All generated from Statistics agent JSON with zero extra LLM calls:
| # | Chart | Driven by |
|---|---|---|
| 1 | **Horizontal Bar** | `metrics` array |
| 2 | **Multi-series Area / Trend** | `trends[].data_points` |
| 3 | **Donut / Pie** | `comparisons` array |
| 4 | **Gauge** | First 0–100 metric value |
| 5 | **Bubble Scatter** | All `metrics` (size = relative value) |
| 6 | **Year-on-Year Bar** | `trends[0].data_points` |
---
## 🔑 Getting API Keys (Free)
### Groq — Primary LLM ⭐ Required
Fast open-source inference (14,400 free requests/day):
1. [console.groq.com](https://console.groq.com) → Sign up → API Keys → Create
2. Copy: `gsk_...`
### Tavily — Web Search ✅ Required
Real-time web search for agents:
1. [app.tavily.com](https://app.tavily.com) → Sign up → Dashboard
2. Copy: `tvly-...`
3. Free: 1,000 searches/month
### Google Gemini — Fallback LLM (optional)
Only needed if no Groq key:
1. [aistudio.google.com](https://aistudio.google.com) → Get API Key
2. Copy: `AIzaSy...`
### LangSmith — Tracing (optional but recommended)
See every node execution, LLM call, and retry as a visual timeline:
1. [smith.langchain.com](https://smith.langchain.com) → Settings → API Keys → Create
2. Copy: `lsv2_...`
---
## ⚙️ Installation & Setup
**Prerequisites:** Python 3.11+, Git
```bash
# 1. Clone
git clone https://github.com/vishal815/ResearchPilot-AI.git
cd ResearchPilot-AI
# 2. Virtual environment
python -m venv .venv
# 3. Activate
# Windows:
.venv\Scripts\activate
# Mac/Linux:
source .venv/bin/activate
# 4. Install dependencies
pip install -r requirements.txt
# 5. Set up API keys
cp .env.example .env
# Now open .env and fill in your keys
```
Your `.env` file:
```env
GROQ_API_KEY=gsk_your_key_here
TAVILY_API_KEY=tvly_your_key_here
# GOOGLE_API_KEY=AIzaSy_your_key_here (optional fallback)
# LANGCHAIN_API_KEY=lsv2_your_key_here (optional tracing)
# LANGCHAIN_TRACING_V2=true
# LANGCHAIN_PROJECT=researchpilot-ai
```
---
## ▶️ Running the Project
### Terminal mode (test the pipeline first)
```bash
python main.py
```
Output:
```
============================================================
 ResearchPilot AI
 Query: Impact of AI on healthcare market growth...
============================================================
[NODE: PLANNER] Domain detected: healthcare | 3 tasks created
[NODE: ROUTER] Activated: ['research', 'statistics', 'domain_expert', 'fact_checker', 'citation']
[NODE: WORKERS] Research done | Statistics: 8 metrics, 3 trends | Expert done | FactCheck done | Refs: 8 sources
[NODE: VISUALIZATION] 6 charts generated
[NODE: WRITER] Report generated
[NODE: QUALITY_GATE] Score: 7.5/10
[NODE: COVER] SVG cover card generated
============================================================
 Total time: 52.3s | Saved to output_report_v2.md
```
### Streamlit Web UI
```bash
streamlit run ui/app.py
```
Opens at `http://localhost:8501`
---
## 🐳 Deploy to Hugging Face Spaces
The project ships with a ready `Dockerfile` that targets port 7860 (Hugging Face's required port).
### Step 1 — Push to GitHub
```bash
git add .
git commit -m "Initial ResearchPilot AI upload"
git push origin main
```
### Step 2 — Create a Hugging Face Space
1. Go to [huggingface.co/spaces](https://huggingface.co/spaces)
2. Click **Create new Space**
3. Set:
 - **Space name:** `ResearchPilot-AI`
 - **License:** MIT
 - **SDK:** **Docker** ← important, not Streamlit
 - **Visibility:** Public
### Step 3 — Add API Keys as Secrets
> ⚠️ Never put real API keys in code or `Dockerfile`. Use HF Secrets — they're injected as environment variables at runtime, invisible in the repo.
Go to your Space → **Settings** → **Repository secrets** → **New secret**:
| Secret Name | Value | Required? |
|---|---|---|
| `GROQ_API_KEY` | Your Groq key (`gsk_...`) | ✅ Required |
| `TAVILY_API_KEY` | Your Tavily key (`tvly_...`) | ✅ Required |
| `LANGCHAIN_API_KEY` | Your LangSmith key (`lsv2_...`) | Optional |
| `LANGCHAIN_TRACING_V2` | `true` | Optional (with LangSmith) |
| `GOOGLE_API_KEY` | Your Gemini key | Optional fallback |
**Why secrets, not `.env`?** HF Spaces clones your repo publicly — your `.env` must never be committed (it's in `.gitignore`). Secrets are stored encrypted in HF's vault and injected at container start time.
Your `Dockerfile` already sets:
```dockerfile
ENV LANGCHAIN_PROJECT="researchpilot-ai"
```
This constant is safe to hardcode because it's not sensitive — it's just the project name in LangSmith's dashboard.
The `LANGCHAIN_TRACING_V2=true` env var activates LangSmith auto-tracing — set it as a secret alongside your `LANGCHAIN_API_KEY`. Once both are set, every run appears in your [LangSmith dashboard](https://smith.langchain.com) showing exactly which node ran, how long each LLM call took, and the full prompt/response for every agent call.
### Step 4 — Link GitHub Repo
In your Space → **Files** → **Connect to GitHub repo** → select your repo → HF auto-builds on every push.
Or push directly to the HF Space's git remote:
```bash
git remote add hf https://huggingface.co/spaces/YOUR_HF_USERNAME/ResearchPilot-AI
git push hf main
```
### Step 5 — Wait for Build
HF Spaces shows a build log. The first build takes ~3-5 minutes (downloads dependencies). After that, code-only pushes rebuild in ~60 seconds.
---
## 📚 Concepts Covered
| Concept | Where in code | One-line description |
|---|---|---|
| **Agentic AI** | All nodes | Agents decide and act, not just reply |
| **LangGraph StateGraph** | `graph_builder.py` | Stateful multi-node orchestration with cycles |
| **Conditional Edge / Routing** | `graph_builder.py` + `quality_gate.py` | `should_retry()` returns string → LangGraph picks next node |
| **Shared State (TypedDict)** | `state.py` | One dict flows through every node — how agents "talk" |
| **Tool Use** | `search_tool.py` | Agents calling Tavily external API |
| **Virtual File System** | `file_system.py` | Dict-as-filesystem for zero-I/O context sharing |
| **Persona Priming** | `workers.py` | Named, credentialed identity → sharper domain output |
| **Structured Output Forcing** | `workers.py` | Force LLM to return exact JSON schema for deterministic chart rendering |
| **LLM-as-Judge** | `quality_gate.py` | Separate LLM call evaluates the first LLM's output |
| **Self-Correction Loop** | `quality_gate.py` | Cycle in graph capped by `retry_count` |
| **RAG** | `workers.py` | Search first → synthesise over retrieved context |
| **Flowable PDF** | `pdf_generator.py` | ReportLab auto-layout vs. manual x/y coordinate mess |
| **Streamlit Session State** | `ui/app.py` | Cache results across reruns so downloads don't re-trigger agents |
---
## 🔧 Troubleshooting
| Error | Cause | Fix |
|---|---|---|
| `ModuleNotFoundError` | venv not activated | `.venv\Scripts\activate` then `pip install -r requirements.txt` |
| `ImportError: cannot import name 'web_search'` | Old `search_tool.py` | Confirm file has `def web_search(query, max_results=5):` |
| Charts missing / only 1 chart | rgba color bug (old version) | Make sure you have the latest `visualization.py` |
| Cover shows `Score: 0.0` | Old graph wiring (cover before quality_gate) | Make sure you have the latest `graph_builder.py` |
| PDF has two References sections | LLM writes its own + structured list | Make sure you have latest `pdf_generator.py` with `_strip_references_section()` |
| `kaleido` error in PDF | Wrong kaleido version | `pip install kaleido==0.2.1` (pin to 0.2.1 exactly) |
| Page "resets" on download | Old `app.py` without session_state cache | Make sure you have latest `ui/app.py` |
| `429` rate limit | Hit LLM free tier | Wait 60s and retry, or switch to Gemini fallback |
---
## 🛣️ Roadmap
- [ ] AI-generated cover image via Pollinations AI (free, no key needed)
- [ ] LangGraph checkpointing for session memory across multiple queries
- [ ] Upload a PDF/document as additional research context
- [ ] Model selector in UI (Groq / Gemini / OpenRouter)
- [ ] Auto-generate PowerPoint slide deck from the report
- [ ] LangSmith evaluation dashboard integration
---
## 📜 License
MIT License — free to use, modify, and distribute with attribution.
---
## 🙏 Acknowledgements
[LangGraph](https://langchain-ai.github.io/langgraph/) · [Groq](https://groq.com) · [Google Gemini](https://aistudio.google.com) · [Tavily](https://tavily.com) · [Plotly](https://plotly.com) · [Streamlit](https://streamlit.io) · [ReportLab](https://www.reportlab.com) · [LangSmith](https://smith.langchain.com)
---
## 👨‍💻 Connect With Me
<div align="center">
[🌐 Portfolio](https://vishal-lazrus-portfolio.vercel.app/) &nbsp;•&nbsp;
[💼 LinkedIn](https://www.linkedin.com/in/vishal-lazrus/) &nbsp;•&nbsp;
[🐙 GitHub](https://github.com/vishal815)
**If this helped you learn something, give it a ⭐ on GitHub!**
*Built by Vishal Lazrus during AI Internship at Infosys, June 2026*
</div>