| --- |
| 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). |
