---
title: AI Research Paper Explainer
emoji: 📄
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 8080
pinned: false
---

# AI Research Paper Explainer

> A **Decoding Data Science** build — learner edition.
> An AI agent that reads a research paper (PDF), explains the concepts in plain language, and draws flowcharts to make them easier to understand. Built with Google's **Agent Development Kit (ADK)** and **Gemini**.

This guide is written so a learner can take the project from **running on their own laptop (VS Code)** all the way to a **live, shareable app on Hugging Face Spaces — for free**.

---

## What it does

- **PDF Analysis** — upload and analyze a research paper in PDF format
- **Concept Explanation** — clear, accessible explanations of complex ideas
- **Visual Learning** — automatic flowcharts to illustrate processes and relationships
- **Live Research Context** — pulls in related work and follow-up directions when useful
- **Interactive Q&A** — ask follow-up questions in the same conversation

---

## How it works (the two halves)

The app is made of two parts that now run together as **one service**:

1. **The brain (backend)** — a FastAPI app running a Google ADK agent. It reads the PDF, talks to Gemini, and generates flowcharts.
2. **The face (frontend)** — a simple HTML chat page in the `public/` folder where you upload the PDF and ask questions.

When deployed (locally or on Hugging Face), **a single server serves both the page and the AI**, so there is nothing to wire together between separate services.

---

## Part 1 — Run it locally (on your laptop)

### Prerequisites

- **Python 3.10+**
- A **Google AI Studio API key** (free) — get one at <https://aistudio.google.com/app/apikey>

> Note: This project uses **only the Google API key** (the Gemini Developer API). It does **not** use Google Cloud, Vertex AI, or any paid Google Cloud service.

### Step 1 — Get the code

```bash
git clone https://github.com/<your-username>/research-paper-explainer.git
cd research-paper-explainer
```

### Step 2 — Install the dependencies

```bash
pip install -r requirements.txt
```

> You also need **Graphviz** installed on your machine for flowcharts. On Mac: `brew install graphviz`. On Ubuntu/Debian: `sudo apt-get install graphviz`. (On Hugging Face this is installed automatically — see Part 2.)

### Step 3 — Add your API key

Create a `.env` file in the project root (you can copy the template):

```bash
cp env.example .env
```

Then open `.env` and set just one line:

```
GOOGLE_API_KEY=your-api-key-here
```

### Step 4 — Run it

```bash
python main.py
```

Now open **<http://localhost:8080>** in your browser. The chat page loads **and** the AI works — all from one command, because the app serves the page and the API together.

Upload a PDF, type a question like *"Explain the main method in this paper,"* and you should get an explanation with a flowchart.

---

## Part 2 — Put it on Hugging Face Spaces (free)

Once it works locally, here is exactly how to take that same project and host it for free on Hugging Face, so anyone can use it from a public link.

### Why Docker?

Think of **Docker as a sealed lunchbox**: it packs the code, the language, and the tools (like Graphviz) into one box that runs the same way on any computer. This repo already includes a `Dockerfile` (the packing recipe), so we use a **Docker Space**. Hugging Face opens the lunchbox and runs your app.

### What had to change to go from "two services" to "one Space"

The original project was designed to run the page and the brain in **two separate places**. A Space is **one container**, so the project was adjusted as follows (these changes are already in this repo):

| Change | File | Why |
|---|---|---|
| Backend now also serves the web page | `main.py` | One container serves both the page and the API |
| Page calls `/api/explain` (relative), not `localhost` | `public/index.html` | So it works on any server, not just your laptop |
| Stop excluding the `public/` folder from the image | `.dockerignore` | The web page must be packed inside the container |
| Added the Space config header | `README.md` | Tells Hugging Face: `sdk: docker`, `app_port: 8080` |
| Confirmed the agent is fully defined (`root_agent`) | `research_explainer/agent.py` | The app crashes on startup if the agent code is missing |

> Tip for learners: if you ever see `ImportError: cannot import name 'root_agent'`, it means the agent object in `research_explainer/agent.py` is missing or renamed — make sure the file ends with a `root_agent = Agent(...)` definition.

### Step-by-step deployment

1. **Create a Space**
   - Go to <https://huggingface.co/new-space>
   - **SDK:** Docker → template **Blank**
   - **Hardware:** **CPU Basic (Free)**
   - Click **Create Space**

2. **Upload the project files**
   - Open the **Files** tab → **Add file → Upload files**
   - Upload everything so that `README.md`, `Dockerfile`, and `main.py` sit at the **top level** (the root) of the Space — not inside a subfolder — and include the `public/` and `research_explainer/` folders.
   - Keep the auto-created `.gitattributes` (leave it untouched). Let your `README.md` **overwrite** the default one — yours carries the Space settings.
   - Add a commit message and **Commit changes**.

3. **Add your API key as a Secret** (never put the key in a file)
   - Go to the Space's **Settings** tab → **Variables and secrets** → **New secret**
   - **Name:** `GOOGLE_API_KEY` (exact spelling) · **Value:** your key → **Save**

4. **Let it build**
   - The Space rebuilds automatically. Watch the **Logs**.
   - First build takes ~3–5 minutes (it installs Graphviz and the Python packages).
   - When the status turns **Running**, your app is live on a public `…hf.space` URL.

5. **Test it**
   - Open the App, upload a PDF, ask a question, and confirm you get an explanation with a flowchart.

### Common issues (and fixes)

- **`403 — cpu-basic quota limit`** → On the free plan only a limited number of your Spaces can run at once. Open your other Spaces marked **"Running"**, **pause** one you don't need (Settings → Pause), then **Restart** this Space. (Spaces marked "Sleeping" don't count.)
- **Runtime crash on startup / `ImportError: root_agent`** → Make sure `research_explainer/agent.py` actually defines the agent (`root_agent = Agent(...)`).
- **App loads but answers fail / "Failed to fetch"** → Check the secret is named exactly `GOOGLE_API_KEY`.

---

## Response structure (what the agent returns)

Each explanation generally follows this shape:

1. **Brief Overview** — what the concept is and why it matters
2. **Detailed Explanation** — step-by-step breakdown with technical details
3. **Paper Context** — how this fits into the broader research
4. **Visual Aid / Research Context** — a flowchart or related work, placed where most useful
5. **Key Takeaways** — a short summary

---

## Tools the agent uses

- **Flowchart Generator (`generate_flowchart`)** — builds clean flowcharts (via Graphviz) to show processes, architectures, and relationships.
- **Research Context (`find_research_context`)** — finds related papers and follow-up directions and ties them back to the uploaded paper.
- **Diagram Generator (`generate_diagram`)** — *optional* image-based diagrams via Gemini image generation. Left **off by default** in this build; enable it in `research_explainer/agent.py` by un-commenting it in the agent's `tools` list.

---

## Technical details

- **Model:** Gemini 2.5 Flash (text generation and analysis)
- **Flowcharts:** Graphviz (programmatic generation)
- **Backend:** FastAPI + Google ADK, in-memory sessions (runs as a single instance — which is exactly what one Space provides)
- **Auth:** Google AI Studio API key (`GOOGLE_API_KEY`) — no Vertex AI, no Google Cloud

---

## Sample questions to try

- "Explain the machine learning method described in this paper."
- "How does the proposed approach work, step by step?"
- "What is the architecture of the system described?"
- "What are the key contributions of this research?"

---

## Extending it

This agent is easy to build on. You can:

- Add new tools (e.g. different kinds of visualizations)
- Adjust the prompt in `research_explainer/agent.py` to specialize in a domain
- Enable the image-diagram tool
- Improve the PDF handling or support more file types

---

## Credits & ownership

Maintained by **Mohammad Arshad** · **Decoding Data Science**
© 2026 Decoding Data Science. Built for the DDS community and learners.

Original "Research Paper Explainer" concept built with Google's Agent Development Kit (ADK).