Spaces:
Sleeping
Sleeping
metadata
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
🧭 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.
📌 Table of Contents
🤔 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):
- console.groq.com → Sign up → API Keys → Create
- Copy:
gsk_...
Tavily — Web Search ✅ Required
Real-time web search for agents:
- app.tavily.com → Sign up → Dashboard
- Copy:
tvly-... - Free: 1,000 searches/month
Google Gemini — Fallback LLM (optional)
Only needed if no Groq key:
- aistudio.google.com → Get API Key
- Copy:
AIzaSy...
LangSmith — Tracing (optional but recommended)
See every node execution, LLM call, and retry as a visual timeline:
- smith.langchain.com → Settings → API Keys → Create
- Copy:
lsv2_...
⚙️ Installation & Setup
Prerequisites: Python 3.11+, Git
# 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:
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)
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
git add .
git commit -m "Initial ResearchPilot AI upload"
git push origin main
Step 2 — Create a Hugging Face Space
- Go to huggingface.co/spaces
- Click Create new Space
- Set:
- Space name:
ResearchPilot-AI - License: MIT
- SDK: Docker ← important, not Streamlit
- Visibility: Public
- Space name:
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:
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 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:
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 · Groq · Google Gemini · Tavily · Plotly · Streamlit · ReportLab · LangSmith
👨💻 Connect With Me
🌐 Portfolio • 💼 LinkedIn • 🐙 GitHub
If this helped you learn something, give it a ⭐ on GitHub!
Built by Vishal Lazrus during AI Internship at Infosys, June 2026