Upload 15 files

.dockerignore

@@ -0,0 +1,11 @@
+.venv
+__pycache__
+**/__pycache__
+*.pyc
+*.pyo
+.git
+.env
+.firebaserc
+firebase.json
+WORKSHOP.md
+README.md

.gcloudignore

@@ -0,0 +1,11 @@
+.gcloudignore
+.git
+.venv
+__pycache__
+**/__pycache__
+*.pyc
+*.pyo
+.env
+public/
+WORKSHOP.md
+README.md

.gitignore

@@ -0,0 +1,3 @@
+*.pyc
+.env
+.vscode/settings.json

Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends graphviz && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+ENV PORT=8080
+CMD ["python", "main.py"]

README.md

@@ -0,0 +1,202 @@
+---
+title: AI Research Paper Explainer
+emoji: 📄
+colorFrom: indigo
+colorTo: purple
+sdk: docker
+app_port: 8080
+pinned: false
+---
+
+# Research Paper Explainer Agent
+
+A specialized ADK based AI agent that analyzes research papers and provides detailed explanations with visual aids. Upload a PDF research paper, ask questions about specific concepts, and receive comprehensive explanations accompanied by flowcharts and diagrams. Made with Google's Agent Development Kit (ADK) 
+
+**My motivation to make this:** I often need to read several research papers and learn new advanced concepts in machine learning directly from highly technical papers to keep up with the literature and implement these new concepts at work and in my research. This tool will help me focus on the important parts of the paper and give me illustrations and diagrams to help me learn and visualize things faster. The agent is designed to use multiple diagrams to explain the concept, giving me more details than the one or two diagrams that are normally included in research papers.
+
+## Features
+
+- **PDF Analysis**: Upload and analyze research papers in PDF format
+- **Concept Explanation**: Get detailed, accessible explanations of complex research concepts
+- **Visual Learning**: Automatic generation of flowcharts and diagrams to enhance understanding
+- **Context-Aware**: Explanations are grounded in the specific paper being analyzed
+- **Interactive Q&A**: Ask follow-up questions and get clarifications
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.8+
+- Google Cloud Project with Vertex AI enabled OR
+- [Google AI Studio](https://aistudio.google.com/app/apikey) API key
+- ADK (Agent Development Kit) installed
+
+### Installation
+
+1. Clone or download this project
+2. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. Set up environment variables:
+   ```bash
+   cp env.example .env
+   ```
+   Edit `.env` and add your Google Cloud configuration / Google AI Studio API key:
+   ```
+   GOOGLE_GENAI_USE_VERTEXAI=TRUE
+   GOOGLE_CLOUD_PROJECT=your-project-id
+   GOOGLE_CLOUD_LOCATION=your-region
+   ```
+   OR
+   ```
+   GOOGLE_API_KEY=your-api-key
+   ```
+
+### Running locally
+
+The backend (FastAPI + ADK agent) and frontend (static HTML) are served separately — mirroring how they're deployed in production (Cloud Run + Firebase Hosting).
+
+**Terminal 1 — backend:**
+```bash
+fastapi dev main.py
+```
+The API will be available at `http://localhost:8000`.
+
+**Terminal 2 — frontend:**
+```bash
+cd public
+python3 -m http.server 3000
+```
+Open `http://localhost:3000` in your browser.
+
+> The `BACKEND_URL` in `public/index.html` defaults to `http://localhost:8000/api/explain`, so no extra config is needed for local dev.
+
+## How It Works
+
+### Core Functionality
+
+The Research Explainer agent follows a structured workflow:
+
+1. **Paper Analysis**: Reads and understands the uploaded PDF research paper
+2. **Concept Identification**: Identifies the specific concept you're asking about
+3. **Detailed Explanation**: Provides a clear, structured explanation including:
+   - Definition of the concept
+   - How it works (step-by-step if applicable)
+   - Why it's important in the context of the paper
+   - Key mathematical formulas or technical details
+4. **Visual Generation**: Creates appropriate flowcharts or diagrams to illustrate the concept
+5. **Integration**: Seamlessly integrates visual aids into the explanation
+
+### Response Structure
+
+Each explanation follows this format:
+- **Brief Overview**: What the concept is and why it matters
+- **Detailed Explanation**: Step-by-step breakdown with technical details
+- **Paper Context**: How this concept fits into the broader research
+- **Visual Aid**: Flowchart or diagram (integrated at the most relevant point)
+- **Key Takeaways**: Summary of the most important points
+
+## Tools
+
+The agent is equipped with two specialized tools for visual learning:
+
+### 1. Flowchart Generator (`generate_flowchart`)
+
+Creates programmatically generated flowcharts to illustrate processes, workflows, and relationships between concepts.
+
+**Features:**
+- Customizable node colors and labels
+- Flexible connection patterns
+- Professional styling with clean typography
+- Automatic layout optimization
+
+**Use Cases:**
+- Algorithm workflows
+- Process diagrams
+- System architectures
+- Decision trees
+- Data flow diagrams
+
+### 2. Diagram Generator (`generate_diagram`)
+
+Creates abstract diagrams and illustrations to explain complex concepts that don't fit into flowchart format.
+
+**Features:**
+- AI-generated technical illustrations
+- High-resolution, clean design
+- Context-aware visualizations
+- Support for abstract concepts
+
+**Use Cases:**
+- Mathematical concepts
+- Scientific phenomena
+- Abstract relationships
+- Conceptual models
+- Technical illustrations
+
+## Example Usage
+
+### Sample Questions
+
+- "Explain the machine learning algorithm described in this paper"
+- "How does the proposed method work step by step?"
+- "What is the architecture of the system described?"
+- "Can you explain the mathematical formulation in section 3?"
+- "What are the key contributions of this research?"
+
+### Sample Response
+
+The agent will provide:
+1. Paper title and main contributions
+2. Detailed explanation of the requested concept
+3. Relevant flowcharts showing the process flow
+4. Additional diagrams illustrating key concepts
+5. Page references and citations from the paper
+
+## Technical Details
+
+### Model
+- **Primary Model**: Gemini 2.5 Pro for text generation and analysis
+- **Image Generation**: Gemini 2.5 Flash Image Preview for diagram creation
+- **Flowchart Engine**: Graphviz for programmatic flowchart generation
+
+
+## Troubleshooting
+
+### Common Issues
+
+1. **PDF Upload Fails**: Ensure the PDF is not password-protected and is readable
+2. **No Visuals Generated**: The agent may determine that a concept doesn't need visual aids
+3. **Environment Errors**: Verify your Google Cloud credentials and project configuration / `GOOGLE_API_KEY` is set in `.env`
+
+### Getting Help
+
+If you encounter issues:
+1. Check that `GOOGLE_API_KEY` is set in `.env`
+2. Ensure all dependencies are properly installed
+3. Check the console output for detailed error messages
+
+If using VertexAI:
+1. Check your Google Cloud project configuration
+2. Verify that Vertex AI is enabled in your project
+3. Ensure all dependencies are properly installed
+4. Check the console output for detailed error messages
+
+## Contributing
+
+This agent is designed to be easily extensible. You can:
+- Add new tools for different types of visualizations
+- Modify the prompt to specialize in specific research domains
+- Enhance the PDF processing capabilities
+- Add support for additional file formats
+
+## License
+
+Created by Rohan Mitra (rohanmitra8@gmail.com)
+Copyright © 2025
+
+---
+
+**Note**: This agent requires a Google Cloud project with Vertex AI enabled and proper authentication configured OR Google AI Studio API key (`GOOGLE_API_KEY` in `.env`).

env.example

@@ -0,0 +1,8 @@
+# Google Cloud Configuration
+# GOOGLE_GENAI_USE_VERTEXAI=TRUE
+# GOOGLE_CLOUD_PROJECT=<your-project-id>
+# GOOGLE_CLOUD_LOCATION=<region>
+
+# Google AI Studio (Gemini Developer API)
+# Get a key at https://aistudio.google.com/app/apikey
+GOOGLE_API_KEY=<your-api-key>

main.py

@@ -0,0 +1,334 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+FastAPI entrypoint for an ADK agent using **in-memory** session and artifact storage.
+
+Intended for **single-instance** deployment (e.g. one Cloud Run instance with min/max
+instances = 1). State is lost on restart and is not shared across replicas.
+
+Swap points for your project:
+  - Import: replace `paper_agent` / the fallback import with your real agent symbol
+    (this repo exposes `root_agent` in `research_explainer.agent`).
+
+Images in the JSON response are **data URLs** (`data:image/png;base64,...`) loaded from
+the in-memory artifact store after the run, so a browser or frontend can render them
+without GCS.
+
+Session TTL: set ``SESSION_TTL_SECONDS`` (seconds of inactivity). ``0`` disables expiry.
+After TTL, the session is deleted and recreated on the next request. Only **session-scoped**
+artifacts are removed on expiry; ``user:`` namespaced artifacts are left intact so other
+sessions for the same ``user_id`` are not affected.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import os
+from typing import Any, Iterable
+
+import dotenv
+
+dotenv.load_dotenv()
+
+from fastapi import FastAPI, File, Form, HTTPException, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from google.adk.artifacts import InMemoryArtifactService
+from google.adk.events.event import Event
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+from google.genai import types
+from pydantic import BaseModel
+import uvicorn
+
+# -----------------------------------------------------------------------------
+# SWAP: import your root ADK agent here.
+# Example for this repository:
+#   from research_explainer.agent import root_agent as paper_agent
+# -----------------------------------------------------------------------------
+try:
+    from agent import paper_agent
+except ImportError:  # pragma: no cover - convenience for this repo layout
+    from research_explainer.agent import root_agent as paper_agent
+
+logger = logging.getLogger(__name__)
+
+# Max PDF size for UploadFile (bytes).
+MAX_PDF_BYTES = int(os.environ.get("MAX_PDF_BYTES", str(25 * 1024 * 1024)))
+
+APP_NAME = os.environ.get("ADK_APP_NAME", "research_explainer")
+DEFAULT_USER_ID = os.environ.get("ADK_USER_ID", "web")
+# Set RUNNING_LOCALLY=1 for verbose session logging (similar to local dev flags).
+RUNNING_LOCALLY = os.environ.get("RUNNING_LOCALLY", "").lower() in (
+    "1",
+    "true",
+    "yes",
+)
+
+artifact_service = InMemoryArtifactService()
+session_service = InMemorySessionService()
+
+runner = Runner(
+    app_name=APP_NAME,
+    agent=paper_agent,
+    session_service=session_service,
+    artifact_service=artifact_service,
+)
+
+
+async def resolve_session(
+    user_id: str,
+    session_id: str,
+    *,
+    initial_state: dict[str, Any] | None = None,
+) -> None:
+    """
+    Load an existing session or create one with the given id.
+
+    Use `initial_state` when you need to seed session-scoped state on first creation
+    (e.g. tool flags). Omitted here by default; extend the call site if your app needs it.
+    """
+    sess = await session_service.get_session(
+        app_name=APP_NAME,
+        user_id=user_id,
+        session_id=session_id,
+    )
+    if sess is not None:
+        if RUNNING_LOCALLY:
+            logger.info(
+                "Session already exists: app=%r user=%r session=%r",
+                APP_NAME,
+                user_id,
+                session_id,
+            )
+        return
+
+    await session_service.create_session(
+        app_name=APP_NAME,
+        user_id=user_id,
+        session_id=session_id,
+        state=initial_state,
+    )
+    logger.info(
+        "New session created: app=%r user=%r session=%r",
+        APP_NAME,
+        user_id,
+        session_id,
+    )
+
+
+app = FastAPI(title="Research Explainer API", version="1.0.0")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=False,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+def _gather_text_for_response(events: Iterable[Event]) -> str:
+    """Collects user-visible assistant text from streamed events.
+
+    Do not skip events just because they also include tool calls/responses; the model
+    often emits explanation text in the same turn as ``function_call`` parts. Skipping
+    those events previously dropped the entire explanation while images still appeared.
+    """
+    final_chunks: list[str] = []
+    assistant_chunks: list[str] = []
+
+    for event in events:
+        if event.partial:
+            continue
+        if not event.content or not event.content.parts:
+            continue
+        # User turn events can appear in the stream; only aggregate assistant output.
+        if event.author == "user":
+            continue
+
+        pieces: list[str] = []
+        for part in event.content.parts:
+            if part.text:
+                pieces.append(part.text)
+        segment = "".join(pieces).strip()
+        if not segment:
+            continue
+
+        assistant_chunks.append(segment)
+        if event.is_final_response():
+            final_chunks.append(segment)
+
+    if final_chunks:
+        return "\n\n".join(final_chunks)
+    if assistant_chunks:
+        return "\n\n".join(assistant_chunks)
+    return ""
+
+
+async def _collect_images_as_data_urls(
+    events: Iterable[Event],
+    *,
+    app_name: str,
+    user_id: str,
+    session_id: str,
+) -> list[str]:
+    """
+    Loads image artifacts touched during this run from the in-memory artifact service
+    and returns them as data URLs for the frontend.
+    """
+    seen: set[tuple[str, int]] = set()
+    ordered: list[str] = []
+
+    for event in events:
+        if not event.actions or not event.actions.artifact_delta:
+            continue
+        for filename, version in event.actions.artifact_delta.items():
+            key = (filename, version)
+            if key in seen:
+                continue
+            seen.add(key)
+
+            load_session_id = None if filename.startswith("user:") else session_id
+            part = await artifact_service.load_artifact(
+                app_name=app_name,
+                user_id=user_id,
+                filename=filename,
+                session_id=load_session_id,
+                version=version,
+            )
+            if not part or not part.inline_data or not part.inline_data.data:
+                continue
+            mime = (part.inline_data.mime_type or "application/octet-stream").lower()
+            if not mime.startswith("image/"):
+                continue
+            b64 = base64.b64encode(part.inline_data.data).decode("ascii")
+            ordered.append(f"data:{mime};base64,{b64}")
+
+    return ordered
+
+
+class ExplainResponse(BaseModel):
+    text: str
+    images: list[str]
+
+
+@app.post("/api/explain", response_model=ExplainResponse)
+async def explain(
+    session_id: str = Form(...),
+    user_input: str = Form(""),
+    file: UploadFile | None = File(default=None),
+) -> ExplainResponse:
+    """
+    Runs one agent turn for the given ``session_id``.
+
+    Send JSON-compatible fields via **multipart/form-data**: ``session_id``, ``user_input``,
+    and optional ``file`` (PDF). The PDF is attached to the user message as inline bytes
+    for the model. A PDF is only accepted on the **first** turn of a session (no prior
+    events); later turns must omit ``file``.
+    """
+    session_id = session_id.strip()
+    user_input = (user_input or "").strip()
+    user_id = DEFAULT_USER_ID
+
+    pdf_bytes: bytes | None = None
+    if file is not None and getattr(file, "filename", None):
+        if not str(file.filename).lower().endswith(".pdf"):
+            raise HTTPException(
+                status_code=400, detail="Only PDF uploads are supported (.pdf)."
+            )
+        pdf_bytes = await file.read()
+        if len(pdf_bytes) > MAX_PDF_BYTES:
+            raise HTTPException(
+                status_code=400,
+                detail=f"PDF exceeds maximum size of {MAX_PDF_BYTES // (1024 * 1024)} MB.",
+            )
+        if not pdf_bytes:
+            raise HTTPException(status_code=400, detail="Uploaded PDF is empty.")
+
+    if not user_input and not pdf_bytes:
+        raise HTTPException(
+            status_code=400,
+            detail="Provide non-empty user_input and/or a PDF file.",
+        )
+
+    try:
+        await resolve_session(user_id, session_id)
+    except Exception as exc:  # pragma: no cover - runtime guard
+        logger.exception("Session resolution failed for session_id=%s", session_id)
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    existing = await session_service.get_session(
+        app_name=APP_NAME,
+        user_id=user_id,
+        session_id=session_id,
+    )
+    if (
+        pdf_bytes is not None
+        and existing
+        and existing.events
+        and len(existing.events) > 0
+    ):
+        raise HTTPException(
+            status_code=400,
+            detail="A PDF can only be attached on the first message of a conversation.",
+        )
+
+    parts: list[types.Part] = []
+    if pdf_bytes is not None:
+        parts.append(
+            types.Part.from_bytes(data=pdf_bytes, mime_type="application/pdf")
+        )
+    if user_input:
+        parts.append(types.Part.from_text(text=user_input))
+
+    new_message = types.Content(role="user", parts=parts)
+
+    collected: list[Event] = []
+
+    try:
+        async for event in runner.run_async(
+            user_id=user_id,
+            session_id=session_id,
+            new_message=new_message,
+        ):
+            collected.append(event)
+    except HTTPException:
+        raise
+    except Exception as exc:  # pragma: no cover - runtime guard
+        logger.exception("Runner failed for session_id=%s", session_id)
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    text = _gather_text_for_response(collected)
+    images = await _collect_images_as_data_urls(
+        collected,
+        app_name=APP_NAME,
+        user_id=user_id,
+        session_id=session_id,
+    )
+
+    return ExplainResponse(text=text, images=images)
+
+
+
+# Serve the static frontend in public/ at the site root, so a SINGLE container
+# serves both the web page and the /api/explain endpoint (Hugging Face Spaces).
+app.mount("/", StaticFiles(directory="public", html=True), name="static")
+
+if __name__ == "__main__":
+    logging.basicConfig(level=os.environ.get("LOG_LEVEL", "INFO"))
+    port = int(os.environ.get("PORT", "8080"))
+    uvicorn.run("main:app", host="0.0.0.0", port=port)

public/index.html

@@ -0,0 +1,550 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AI Research Paper Explainer</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script>
+      tailwind.config = { darkMode: "class" };
+    </script>
+    <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+    <style>
+      .drop-zone-active {
+        border-color: #6366f1 !important;
+        background-color: #eef2ff !important;
+        box-shadow: 0 0 0 3px rgba(99, 102, 241, 0.25);
+      }
+      .dark .drop-zone-active {
+        background-color: #1e1b4b !important;
+      }
+    </style>
+  </head>
+  <body class="min-h-screen bg-stone-100 text-stone-900 antialiased transition-colors dark:bg-stone-950 dark:text-stone-100">
+    <div class="mx-auto flex min-h-screen max-w-3xl flex-col px-4 py-6">
+
+      <!-- Header -->
+      <header class="mb-5 flex flex-shrink-0 items-center justify-between">
+        <div>
+          <h1 class="font-serif text-2xl font-bold tracking-tight text-stone-800 dark:text-stone-100 md:text-3xl">
+            AI Research Paper Explainer
+          </h1>
+          <p class="mt-0.5 text-sm text-stone-500 dark:text-stone-400">
+            Powered by Gemini 2.5 Pro · Google ADK
+          </p>
+        </div>
+        <div class="flex items-center gap-2">
+          <button
+            type="button"
+            id="theme-toggle"
+            class="rounded-lg border border-stone-300 bg-white px-3 py-2 text-sm text-stone-600 shadow-sm transition hover:bg-stone-50 dark:border-stone-600 dark:bg-stone-800 dark:text-stone-300 dark:hover:bg-stone-700"
+            title="Toggle dark mode"
+          >
+            <span id="theme-toggle-label">Dark</span>
+          </button>
+          <button
+            type="button"
+            id="new-chat-btn"
+            class="rounded-lg border border-stone-300 bg-white px-3 py-2 text-sm text-stone-600 shadow-sm transition hover:bg-stone-50 dark:border-stone-600 dark:bg-stone-800 dark:text-stone-300 dark:hover:bg-stone-700"
+          >
+            New chat
+          </button>
+        </div>
+      </header>
+
+      <!-- Chat panel -->
+      <div class="flex min-h-0 flex-1 flex-col overflow-hidden rounded-2xl border border-stone-200 bg-white shadow-sm dark:border-stone-700 dark:bg-stone-900">
+
+        <!-- Message list -->
+        <div
+          id="chat-messages"
+          class="flex-1 space-y-5 overflow-y-auto p-5"
+          aria-live="polite"
+        >
+          <div id="chat-empty" class="flex flex-col items-center justify-center py-16 text-center">
+            <div class="mb-3 flex h-14 w-14 items-center justify-center rounded-full bg-indigo-50 dark:bg-indigo-950">
+              <svg class="h-7 w-7 text-indigo-500" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
+                <path stroke-linecap="round" stroke-linejoin="round" d="M19.5 14.25v-2.625a3.375 3.375 0 0 0-3.375-3.375h-1.5A1.125 1.125 0 0 1 13.5 7.125v-1.5a3.375 3.375 0 0 0-3.375-3.375H8.25m0 12.75h7.5m-7.5 3H12M10.5 2.25H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 0 0-9-9Z" />
+              </svg>
+            </div>
+            <p class="text-sm font-medium text-stone-700 dark:text-stone-300">Upload a paper and start asking questions</p>
+            <p class="mt-1 text-xs text-stone-400 dark:text-stone-500">
+              Press <kbd class="rounded bg-stone-100 px-1.5 py-0.5 text-stone-600 dark:bg-stone-800 dark:text-stone-300">Enter</kbd> to send &nbsp;·&nbsp;
+              <kbd class="rounded bg-stone-100 px-1.5 py-0.5 text-stone-600 dark:bg-stone-800 dark:text-stone-300">Shift+Enter</kbd> for a new line
+            </p>
+          </div>
+        </div>
+
+        <!-- Typing indicator -->
+        <div
+          id="typing-indicator"
+          class="hidden border-t border-stone-100 px-5 py-2.5 text-sm text-stone-500 dark:border-stone-800 dark:text-stone-400"
+        >
+          <span class="inline-flex items-center gap-2">
+            <span class="flex gap-0.5">
+              <span class="h-1.5 w-1.5 animate-bounce rounded-full bg-indigo-400 [animation-delay:-0.3s]"></span>
+              <span class="h-1.5 w-1.5 animate-bounce rounded-full bg-indigo-400 [animation-delay:-0.15s]"></span>
+              <span class="h-1.5 w-1.5 animate-bounce rounded-full bg-indigo-400"></span>
+            </span>
+            Agent is thinking…
+          </span>
+        </div>
+
+        <!-- Input area -->
+        <form id="chat-form" class="border-t border-stone-200 bg-stone-50 p-4 dark:border-stone-700 dark:bg-stone-900/60" novalidate>
+
+          <!-- PDF drop zone (hidden after first turn) -->
+          <div id="pdf-zone-wrap" class="mb-3">
+            <div
+              id="pdf-drop-zone"
+              class="relative flex cursor-pointer flex-col items-center justify-center gap-2 rounded-xl border-2 border-dashed border-stone-300 bg-white px-4 py-5 transition dark:border-stone-600 dark:bg-stone-800 hover:border-indigo-400 dark:hover:border-indigo-500"
+            >
+              <!-- Default (no file selected) -->
+              <div id="pdf-drop-default" class="flex flex-col items-center gap-1 text-center">
+                <svg class="h-8 w-8 text-stone-400 dark:text-stone-500" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
+                  <path stroke-linecap="round" stroke-linejoin="round" d="M3 16.5v2.25A2.25 2.25 0 0 0 5.25 21h13.5A2.25 2.25 0 0 0 21 18.75V16.5m-13.5-9L12 3m0 0 4.5 4.5M12 3v13.5" />
+                </svg>
+                <p class="text-sm font-medium text-stone-600 dark:text-stone-300">
+                  Drag &amp; drop your PDF here, or <span class="text-indigo-600 underline dark:text-indigo-400">click to upload</span>
+                </p>
+                <p class="text-xs text-stone-400 dark:text-stone-500">One PDF per conversation · Max 25 MB</p>
+              </div>
+
+              <!-- File selected state -->
+              <div id="pdf-drop-selected" class="hidden w-full items-center justify-between gap-3">
+                <div class="flex min-w-0 items-center gap-2">
+                  <svg class="h-5 w-5 shrink-0 text-indigo-500" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
+                    <path stroke-linecap="round" stroke-linejoin="round" d="M19.5 14.25v-2.625a3.375 3.375 0 0 0-3.375-3.375h-1.5A1.125 1.125 0 0 1 13.5 7.125v-1.5a3.375 3.375 0 0 0-3.375-3.375H8.25m2.25 0H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 0 0-9-9Z" />
+                  </svg>
+                  <span id="pdf-filename" class="truncate text-sm font-medium text-stone-700 dark:text-stone-200"></span>
+                </div>
+                <button
+                  type="button"
+                  id="pdf-clear-btn"
+                  class="shrink-0 rounded-full p-1 text-stone-400 transition hover:bg-stone-100 hover:text-stone-600 dark:hover:bg-stone-700 dark:hover:text-stone-200"
+                  title="Remove file"
+                >
+                  <svg class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
+                    <path stroke-linecap="round" stroke-linejoin="round" d="M6 18 18 6M6 6l12 12" />
+                  </svg>
+                </button>
+              </div>
+
+              <!-- Hidden file input -->
+              <input
+                type="file"
+                id="pdf-input"
+                accept=".pdf,application/pdf"
+                class="absolute inset-0 cursor-pointer opacity-0"
+              />
+            </div>
+          </div>
+
+          <!-- Locked PDF banner (shown after first turn) -->
+          <div id="pdf-locked-banner" class="mb-3 hidden items-center gap-2 rounded-xl border border-stone-200 bg-stone-50 px-3 py-2 text-xs text-stone-500 dark:border-stone-700 dark:bg-stone-800 dark:text-stone-400">
+            <svg class="h-3.5 w-3.5 shrink-0" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
+              <path stroke-linecap="round" stroke-linejoin="round" d="M16.5 10.5V6.75a4.5 4.5 0 1 0-9 0v3.75m-.75 11.25h10.5a2.25 2.25 0 0 0 2.25-2.25v-6.75a2.25 2.25 0 0 0-2.25-2.25H6.75a2.25 2.25 0 0 0-2.25 2.25v6.75a2.25 2.25 0 0 0 2.25 2.25Z" />
+            </svg>
+            <span id="pdf-locked-name"></span>
+            <span class="text-stone-400 dark:text-stone-500">· Click <strong>New chat</strong> to use a different paper.</span>
+          </div>
+
+          <!-- Text input + send -->
+          <div class="flex items-end gap-2">
+            <textarea
+              id="chat-input"
+              rows="2"
+              class="min-h-[4rem] flex-1 resize-none rounded-xl border border-stone-300 bg-white px-3.5 py-2.5 text-sm text-stone-800 shadow-inner placeholder:text-stone-400 focus:border-indigo-500 focus:outline-none focus:ring-2 focus:ring-indigo-500/25 dark:border-stone-600 dark:bg-stone-800 dark:text-stone-100 dark:placeholder:text-stone-500"
+              placeholder="Ask about the paper…"
+            ></textarea>
+            <button
+              type="submit"
+              id="send-btn"
+              class="inline-flex h-10 shrink-0 items-center justify-center gap-1.5 rounded-xl bg-indigo-600 px-4 text-sm font-semibold text-white shadow transition hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2 focus:ring-offset-stone-50 disabled:cursor-not-allowed disabled:opacity-50 dark:focus:ring-offset-stone-900"
+            >
+              <span id="send-label">Send</span>
+              <span
+                id="send-spinner"
+                class="hidden h-4 w-4 animate-spin rounded-full border-2 border-white border-t-transparent"
+                aria-hidden="true"
+              ></span>
+            </button>
+          </div>
+
+          <p id="validation-msg" class="mt-2 hidden text-xs text-red-600 dark:text-red-400" role="alert"></p>
+        </form>
+      </div>
+    </div>
+
+    <!-- Lightbox -->
+    <div
+      id="lightbox"
+      class="fixed inset-0 z-[100] hidden cursor-zoom-out items-center justify-center bg-black/85 p-4"
+      role="dialog"
+      aria-modal="true"
+      aria-label="Enlarged image"
+    >
+      <button
+        type="button"
+        id="lightbox-close"
+        class="absolute right-4 top-4 rounded-full bg-white/10 px-3 py-1 text-sm text-white hover:bg-white/20"
+      >
+        Close
+      </button>
+      <img id="lightbox-img" src="" alt="" class="max-h-[92vh] max-w-full rounded object-contain shadow-2xl" />
+    </div>
+
+    <script>
+      // TODO: After deploying the backend to Cloud Run, replace this with your Cloud Run HTTPS URL.
+      const BACKEND_URL = "/api/explain";
+
+      const SESSION_KEY = "research-explainer-session-id";
+      const THEME_KEY = "research-explainer-theme";
+
+      const chatMessages = document.getElementById("chat-messages");
+      const chatForm = document.getElementById("chat-form");
+      const chatInput = document.getElementById("chat-input");
+      const sendBtn = document.getElementById("send-btn");
+      const sendLabel = document.getElementById("send-label");
+      const sendSpinner = document.getElementById("send-spinner");
+      const typingIndicator = document.getElementById("typing-indicator");
+      const validationMsg = document.getElementById("validation-msg");
+      const newChatBtn = document.getElementById("new-chat-btn");
+      const pdfInput = document.getElementById("pdf-input");
+      const pdfDropZone = document.getElementById("pdf-drop-zone");
+      const pdfZoneWrap = document.getElementById("pdf-zone-wrap");
+      const pdfDropDefault = document.getElementById("pdf-drop-default");
+      const pdfDropSelected = document.getElementById("pdf-drop-selected");
+      const pdfFilename = document.getElementById("pdf-filename");
+      const pdfClearBtn = document.getElementById("pdf-clear-btn");
+      const pdfLockedBanner = document.getElementById("pdf-locked-banner");
+      const pdfLockedName = document.getElementById("pdf-locked-name");
+      const lightbox = document.getElementById("lightbox");
+      const lightboxImg = document.getElementById("lightbox-img");
+      const lightboxClose = document.getElementById("lightbox-close");
+      const themeToggle = document.getElementById("theme-toggle");
+      const themeToggleLabel = document.getElementById("theme-toggle-label");
+
+      var hasCompletedFirstTurn = false;
+
+      const mdClasses =
+        "prose-msg space-y-2 leading-relaxed text-stone-800 dark:text-stone-100 [&_a]:text-indigo-600 dark:[&_a]:text-indigo-400 [&_a]:underline [&_code]:rounded [&_code]:bg-stone-100 dark:[&_code]:bg-stone-900 [&_code]:px-1 [&_pre]:overflow-x-auto [&_pre]:rounded-lg [&_pre]:bg-stone-100 dark:[&_pre]:bg-stone-900 [&_pre]:p-3 [&_ul]:list-disc [&_ul]:pl-5 [&_ol]:list-decimal [&_ol]:pl-5 [&_h1]:text-lg [&_h2]:text-base [&_h3]:text-sm [&_blockquote]:border-l-4 [&_blockquote]:border-stone-300 dark:[&_blockquote]:border-stone-600 [&_blockquote]:pl-4 [&_blockquote]:italic";
+
+      // ── Theme ──────────────────────────────────────────────────────────────
+
+      function isDarkMode() { return document.documentElement.classList.contains("dark"); }
+
+      function syncThemeUi() {
+        var dark = isDarkMode();
+        themeToggleLabel.textContent = dark ? "Light" : "Dark";
+      }
+
+      function applyStoredTheme() {
+        if (localStorage.getItem(THEME_KEY) === "dark") {
+          document.documentElement.classList.add("dark");
+        } else {
+          document.documentElement.classList.remove("dark");
+        }
+        syncThemeUi();
+      }
+
+      applyStoredTheme();
+      themeToggle.addEventListener("click", function () {
+        document.documentElement.classList.toggle("dark");
+        localStorage.setItem(THEME_KEY, isDarkMode() ? "dark" : "light");
+        syncThemeUi();
+      });
+
+      // ── Session ────────────────────────────────────────────────────────────
+
+      function getSessionId() {
+        var id = sessionStorage.getItem(SESSION_KEY);
+        if (!id) {
+          id = typeof crypto !== "undefined" && crypto.randomUUID
+            ? crypto.randomUUID()
+            : "sess-" + Date.now() + "-" + String(Math.random()).slice(2, 10);
+          sessionStorage.setItem(SESSION_KEY, id);
+        }
+        return id;
+      }
+
+      // ── PDF zone state ─────────────────────────────────────────────────────
+
+      function showFileSelected(name) {
+        pdfDropDefault.classList.add("hidden");
+        pdfDropSelected.classList.remove("hidden");
+        pdfDropSelected.classList.add("flex");
+        pdfFilename.textContent = name;
+      }
+
+      function showFileDefault() {
+        pdfDropDefault.classList.remove("hidden");
+        pdfDropSelected.classList.add("hidden");
+        pdfDropSelected.classList.remove("flex");
+        pdfFilename.textContent = "";
+      }
+
+      function lockPdfZone(name) {
+        pdfZoneWrap.classList.add("hidden");
+        pdfLockedBanner.classList.remove("hidden");
+        pdfLockedBanner.classList.add("flex");
+        pdfLockedName.textContent = name || "PDF attached";
+      }
+
+      function unlockPdfZone() {
+        pdfZoneWrap.classList.remove("hidden");
+        pdfLockedBanner.classList.add("hidden");
+        pdfLockedBanner.classList.remove("flex");
+        showFileDefault();
+      }
+
+      pdfClearBtn.addEventListener("click", function (e) {
+        e.stopPropagation();
+        pdfInput.value = "";
+        showFileDefault();
+      });
+
+      pdfInput.addEventListener("change", function () {
+        if (pdfInput.files && pdfInput.files[0]) {
+          showFileSelected(pdfInput.files[0].name);
+        } else {
+          showFileDefault();
+        }
+      });
+
+      // Drag-and-drop
+      ["dragenter", "dragover"].forEach(function (evt) {
+        pdfDropZone.addEventListener(evt, function (e) {
+          e.preventDefault();
+          pdfDropZone.classList.add("drop-zone-active");
+        });
+      });
+      ["dragleave", "drop"].forEach(function (evt) {
+        pdfDropZone.addEventListener(evt, function (e) {
+          e.preventDefault();
+          pdfDropZone.classList.remove("drop-zone-active");
+        });
+      });
+      pdfDropZone.addEventListener("drop", function (e) {
+        var files = e.dataTransfer && e.dataTransfer.files;
+        if (files && files[0]) {
+          var dt = new DataTransfer();
+          dt.items.add(files[0]);
+          pdfInput.files = dt.files;
+          showFileSelected(files[0].name);
+        }
+      });
+
+      // ── New chat ───────────────────────────────────────────────────────────
+
+      function startNewChat() {
+        sessionStorage.removeItem(SESSION_KEY);
+        hasCompletedFirstTurn = false;
+        pdfInput.value = "";
+        unlockPdfZone();
+        chatMessages.innerHTML = "";
+        var empty = document.createElement("div");
+        empty.id = "chat-empty";
+        empty.className = "flex flex-col items-center justify-center py-16 text-center";
+        empty.innerHTML =
+          '<div class="mb-3 flex h-14 w-14 items-center justify-center rounded-full bg-indigo-50 dark:bg-indigo-950">' +
+          '<svg class="h-7 w-7 text-indigo-500" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M19.5 14.25v-2.625a3.375 3.375 0 0 0-3.375-3.375h-1.5A1.125 1.125 0 0 1 13.5 7.125v-1.5a3.375 3.375 0 0 0-3.375-3.375H8.25m0 12.75h7.5m-7.5 3H12M10.5 2.25H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 0 0-9-9Z" /></svg>' +
+          '</div>' +
+          '<p class="text-sm font-medium text-stone-700 dark:text-stone-300">Upload a paper and start asking questions</p>' +
+          '<p class="mt-1 text-xs text-stone-400 dark:text-stone-500">Press <kbd class="rounded bg-stone-100 px-1.5 py-0.5 text-stone-600 dark:bg-stone-800 dark:text-stone-300">Enter</kbd> to send &nbsp;·&nbsp; <kbd class="rounded bg-stone-100 px-1.5 py-0.5 text-stone-600 dark:bg-stone-800 dark:text-stone-300">Shift+Enter</kbd> for a new line</p>';
+        chatMessages.appendChild(empty);
+        chatInput.focus();
+      }
+
+      newChatBtn.addEventListener("click", startNewChat);
+
+      // ── Loading state ──────────────────────────────────────────────────────
+
+      function scrollToBottom() { chatMessages.scrollTop = chatMessages.scrollHeight; }
+
+      function setLoading(on) {
+        sendBtn.disabled = on;
+        chatInput.disabled = on;
+        pdfInput.disabled = on;
+        if (on) {
+          sendSpinner.classList.remove("hidden");
+          sendLabel.textContent = "…";
+          typingIndicator.classList.remove("hidden");
+        } else {
+          sendSpinner.classList.add("hidden");
+          sendLabel.textContent = "Send";
+          typingIndicator.classList.add("hidden");
+        }
+        scrollToBottom();
+      }
+
+      // ── Chat bubbles ───────────────────────────────────────────────────────
+
+      function appendUserBubble(text, withPdf) {
+        var emptyEl = document.getElementById("chat-empty");
+        if (emptyEl) emptyEl.remove();
+        var wrap = document.createElement("div");
+        wrap.className = "flex justify-end";
+        var bubble = document.createElement("div");
+        bubble.className =
+          "max-w-[82%] rounded-2xl rounded-br-md bg-indigo-600 px-4 py-2.5 text-sm text-white shadow-sm dark:bg-indigo-700";
+        bubble.textContent = text || "(PDF only)";
+        if (withPdf) {
+          var note = document.createElement("div");
+          note.className = "mt-1.5 flex items-center gap-1 border-t border-indigo-400/50 pt-1.5 text-xs text-indigo-200";
+          note.innerHTML = '<svg class="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M19.5 14.25v-2.625a3.375 3.375 0 0 0-3.375-3.375h-1.5A1.125 1.125 0 0 1 13.5 7.125v-1.5a3.375 3.375 0 0 0-3.375-3.375H8.25m2.25 0H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 0 0-9-9Z"/></svg> PDF attached';
+          bubble.appendChild(note);
+        }
+        wrap.appendChild(bubble);
+        chatMessages.appendChild(wrap);
+        scrollToBottom();
+      }
+
+      function appendAssistantBubble(html, images) {
+        var wrap = document.createElement("div");
+        wrap.className = "flex justify-start";
+        var bubble = document.createElement("div");
+        bubble.className =
+          "max-w-[88%] rounded-2xl rounded-bl-md border border-stone-200 bg-stone-50 px-4 py-3 text-sm shadow-sm dark:border-stone-700 dark:bg-stone-800";
+        var textEl = document.createElement("div");
+        textEl.className = mdClasses;
+        textEl.innerHTML = html;
+        bubble.appendChild(textEl);
+        if (images && images.length > 0) {
+          var grid = document.createElement("div");
+          grid.className = "mt-3 grid gap-3 sm:grid-cols-2";
+          images.forEach(function (src, i) {
+            if (!src) return;
+            var img = document.createElement("img");
+            img.src = src;
+            img.alt = "Diagram " + (i + 1);
+            img.className =
+              "diagram-img max-h-80 w-full cursor-zoom-in rounded-xl border border-stone-200 bg-white object-contain shadow-sm transition hover:ring-2 hover:ring-indigo-300 dark:border-stone-600 dark:bg-stone-900 dark:hover:ring-indigo-500";
+            img.loading = "lazy";
+            img.title = "Click to enlarge";
+            grid.appendChild(img);
+          });
+          bubble.appendChild(grid);
+        }
+        wrap.appendChild(bubble);
+        chatMessages.appendChild(wrap);
+        scrollToBottom();
+      }
+
+      function appendErrorBubble(msg) {
+        var safe = String(msg).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+        var wrap = document.createElement("div");
+        wrap.className = "flex justify-start";
+        var bubble = document.createElement("div");
+        bubble.className =
+          "max-w-[88%] rounded-2xl rounded-bl-md border border-red-200 bg-red-50 px-4 py-3 text-sm text-red-800 shadow-sm dark:border-red-900 dark:bg-red-950/40 dark:text-red-300";
+        bubble.innerHTML = "<p>" + safe + "</p>";
+        wrap.appendChild(bubble);
+        chatMessages.appendChild(wrap);
+        scrollToBottom();
+      }
+
+      // ── Lightbox ───────────────────────────────────────────────────────────
+
+      chatMessages.addEventListener("click", function (e) {
+        if (e.target && e.target.classList && e.target.classList.contains("diagram-img")) {
+          lightboxImg.src = e.target.src;
+          lightboxImg.alt = e.target.alt || "Diagram";
+          lightbox.classList.remove("hidden");
+          lightbox.classList.add("flex");
+        }
+      });
+
+      function closeLightbox() {
+        lightbox.classList.add("hidden");
+        lightbox.classList.remove("flex");
+        lightboxImg.src = "";
+      }
+
+      lightboxClose.addEventListener("click", closeLightbox);
+      lightbox.addEventListener("click", function (e) {
+        if (e.target === lightbox || e.target === lightboxImg) closeLightbox();
+      });
+      document.addEventListener("keydown", function (e) {
+        if (e.key === "Escape" && !lightbox.classList.contains("hidden")) closeLightbox();
+      });
+
+      // ── Keyboard shortcut ──────────────────────────────────────────────────
+
+      chatInput.addEventListener("keydown", function (e) {
+        if (e.key === "Enter" && !e.shiftKey) {
+          e.preventDefault();
+          if (!sendBtn.disabled) chatForm.requestSubmit();
+        }
+      });
+
+      // ── Submit ─────────────────────────────────────────────────────────────
+
+      function formatDetail(detail) {
+        if (detail == null) return "";
+        if (typeof detail === "string") return detail;
+        if (Array.isArray(detail)) return detail.map(function (x) { return x && x.msg ? x.msg : JSON.stringify(x); }).join("; ");
+        return JSON.stringify(detail);
+      }
+
+      chatForm.addEventListener("submit", async function (e) {
+        e.preventDefault();
+        validationMsg.classList.add("hidden");
+
+        var text = chatInput.value.trim();
+        var file = !hasCompletedFirstTurn && pdfInput.files && pdfInput.files[0] ? pdfInput.files[0] : null;
+
+        if (!text && !file) {
+          validationMsg.textContent = "Enter a message and/or attach a PDF.";
+          validationMsg.classList.remove("hidden");
+          return;
+        }
+
+        appendUserBubble(text, !!file);
+        chatInput.value = "";
+        setLoading(true);
+
+        var fd = new FormData();
+        fd.append("session_id", getSessionId());
+        fd.append("user_input", text);
+        if (file) fd.append("file", file, file.name);
+
+        var parseMd = typeof marked.parse === "function" ? marked.parse.bind(marked) : marked;
+
+        try {
+          var response = await fetch(BACKEND_URL, { method: "POST", body: fd });
+          var rawBody = await response.text();
+          var data = null;
+          try { data = rawBody ? JSON.parse(rawBody) : null; } catch (_) {}
+
+          if (!response.ok) {
+            var msg = "Request failed (" + response.status + " " + response.statusText + ").";
+            if (data && data.detail !== undefined) msg += " " + formatDetail(data.detail);
+            else if (rawBody && !data) msg += " " + rawBody.slice(0, 200);
+            appendErrorBubble(msg);
+            return;
+          }
+
+          if (!data || typeof data !== "object") { appendErrorBubble("Unexpected response from server."); return; }
+
+          var md = data.text != null ? String(data.text) : "";
+          var images = Array.isArray(data.images) ? data.images : [];
+          if (!md.trim() && images.length > 0) md = "*The model returned diagrams without explanation text.*";
+          appendAssistantBubble(parseMd(md, { breaks: true }), images);
+
+          if (!hasCompletedFirstTurn) {
+            hasCompletedFirstTurn = true;
+            lockPdfZone(file ? file.name : "");
+          }
+        } catch (err) {
+          appendErrorBubble(err && err.message ? err.message : "Network error — check the backend URL and CORS.");
+        } finally {
+          setLoading(false);
+          chatInput.focus();
+        }
+      });
+
+      getSessionId();
+    </script>
+  </body>
+</html>

requirements.txt

@@ -0,0 +1,9 @@
+google-adk
+google-genai==1.27.0
+python-dotenv
+requests
+fastapi[standard]
+pydantic
+python-multipart
+uvicorn
+graphviz

research_explainer/__init__.py

@@ -0,0 +1 @@
+# Research Explainer Agent Package

research_explainer/agent.py

@@ -0,0 +1,96 @@
+"""
+Author: Rohan Mitra (rohanmitra8@gmail.com)
+agent.py (c) 2025
+Desc: The Research Explainer ADK agent
+Created:  2025-09-05T18:00:00.000Z
+Modified: 2026-06-20T06:53:56.136Z
+"""
+
+from google.adk.agents import Agent
+from .tools import generate_flowchart, generate_diagram, find_research_context
+import dotenv
+
+dotenv.load_dotenv()
+
+
+BASE_PROMPT = """
+You are a Research Paper Explainer agent. Your goal is to help users understand specific concepts from research papers by providing clear, detailed explanations and generating appropriate diagrams when needed.
+
+## Core Capabilities
+- Analyze the uploaded PDF research paper
+- Explain complex concepts in simple, understandable terms
+- Generate flowcharts for visual learning alongside your explanations
+- Find live external research context, related papers, and follow-up directions when useful
+- Provide context-aware explanations based on the specific paper
+
+## Behavior and Style
+- Be thorough but accessible in your explanations
+- Break down complex concepts into digestible parts
+- Use analogies and examples when helpful
+- Always cite specific sections or pages from the paper when relevant
+- Ask clarifying questions if the user's request is ambiguous
+
+## Workflow for Concept Explanation
+1. Read the uploaded PDF paper and understand the content. You must output the title of the paper and the main contributions of the paper in max 3 lines.
+2. **Concept Explanation**: Provide a clear, structured explanation that includes:
+   - Definition of the concept
+   - How it works (step-by-step if applicable)
+   - Why it's important in the context of the paper
+   - Key mathematical formulas or technical details
+3. **Visual Learning**: When a visual would help, use the `generate_flowchart` tool to generate a flowchart. The tool requires a dict of all the nodes in the flowchart and their background colors, as well as a list of all the connections between the nodes.
+4. **External Research Context**: When the user asks where a concept leads, what uses it, related work, follow-up reading, future directions, or broader impact, use the `find_research_context` tool. Give it the concept, paper-specific context from the uploaded PDF, and the research domain. You can also volunteer this information if you think it would be helpful and relevant to the explanation.
+5. **Integration**: Include the flowchart or research context naturally in your response. It can be at any point in the explanation, not just the end.
+
+## Flowchart Integration
+When you determine that a diagram would enhance understanding, make the `generate_flowchart` tool call and include the flowchart in your response.
+You need to first give it a dictionary of all the nodes to be included in the flowchart, and their background colors in hexadecimal format (#000000 - #FFFFFF). Keep the names of the nodes simple and make sure the arrows show the relationship between the nodes. The relationship can be complex and doesnt have to result in a linear set of relationships.
+You also need to give it a list of all the connections between the nodes by listing the source and destination nodes as a tuple. Make sure to use the same names for the nodes as in the dictionary.
+The datatypes are as follows:
+- nodes_and_colors: dict[str, str]
+- edges: list[list[str]]
+
+A sample generate_flowchart call is given below:
+```
+nodes_and_colors = {
+    'A': '#c1e5f5',
+    'B': '#ffb76e',
+    'C': '#c1e5f5',
+    'D': '#88cc99',
+    'E': 'white',
+}
+edges = [
+    ('A', 'B'), #Connects A to B
+    ('C', 'D'), #Connects C to D
+    ('D', 'E'), #Connects D to E
+    ('E', 'B'), #Connects E to B
+]
+```
+
+## Research Context Integration
+When the user wants to understand how a paper concept connects to the broader field, call `find_research_context`.
+Use a precise `concept` and include a short `paper_context` string that captures the method, task, domain, and surrounding terminology from the uploaded paper.
+After the tool returns results, explain how the external papers or directions relate back to the original paper. Do not overstate the connection if a result is only loosely related.
+
+## Response Structure
+Your explanations should follow this structure:
+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 concept fits into the broader research
+4. **Visual Aid or Research Context**: Include a flowchart or live research context if helpful - this can be at any point in the explanation, not just the end.
+5. **Key Takeaways**: Summary of the most important points
+
+## Technical Guidelines
+- Always read the PDF paper first before attempting to explain concepts
+- Provide page numbers or section references when available
+- If a concept isn't clearly explained in the paper, acknowledge this limitation
+- For mathematical concepts, include the relevant formulas and explain their meaning
+
+## Error Handling
+- If a concept isn't found in the paper, suggest related concepts that are discussed
+- If the explanation becomes too technical, offer to simplify it further
+
+Remember: Your goal is to make complex research accessible while maintaining accuracy and depth. Always ground your explanations in the specific paper being analyzed.
+"""
+
+
+

research_explainer/tools/__init__.py

@@ -0,0 +1,13 @@
+"""
+Tool exports for the Research Explainer ADK agent.
+"""
+
+from .diagram import generate_diagram
+from .flowchart import generate_flowchart
+from .research_context import find_research_context
+
+__all__ = [
+    "find_research_context",
+    "generate_diagram",
+    "generate_flowchart",
+]

research_explainer/tools/diagram.py

@@ -0,0 +1,102 @@
+"""
+AI-generated diagram tool.
+"""
+
+import os
+
+import dotenv
+from google import genai
+from google.adk.tools import ToolContext
+from google.genai import types
+
+dotenv.load_dotenv()
+
+client = genai.Client(api_key=os.environ["GOOGLE_API_KEY"])
+
+
+async def generate_diagram(
+    image_gen_prompt: str, concept_to_explain: str, tool_context: ToolContext
+) -> dict:
+    """
+    Generates a technical diagram for a research paper based on a detailed prompt describing the flow and design requirements.
+    Returns a dictionary with the status and filename or error detail.
+
+    Args:
+        image_gen_prompt (str): The detailed prompt describing the flow and design requirements.
+        concept_to_explain (str): The concept to explain.
+        tool_context (ToolContext): The context for the tool execution.
+
+    Returns:
+        dict: Contains 'status' ('success' or 'failed'), and either 'filename' or 'detail'.
+    """
+    print("Generate diagram tool called!")
+    try:
+        # Create a comprehensive prompt for diagram generation
+        enhanced_prompt = f"""
+        Create a technical, high-quality diagram for a research paper to explain the concept "{concept_to_explain}", based on the following specifications:
+
+        {image_gen_prompt}
+
+        Requirements:
+        - Clear, readable, and precise design
+        - High resolution and clean design
+        - Use of appropriate colors and typography
+        - Helps explain the concept to a student
+
+        Generate a diagram that represents the flow and design requirements.
+        """
+
+        content = types.Content(
+            role="user",
+            parts=[
+                types.Part.from_text(text=enhanced_prompt),
+            ],
+        )
+
+        response = client.models.generate_content(
+            model="gemini-2.5-flash-image-preview",
+            contents=content,
+            config=types.GenerateContentConfig(
+                temperature=0.8,
+                top_p=0.95,
+                max_output_tokens=8192,
+                response_modalities=["TEXT", "IMAGE"],
+            ),
+        )
+
+        if not response or not getattr(response, "candidates", None):
+            return {"status": "failed", "detail": "No response or candidates from model."}
+
+        image_bytes_out = None
+        candidate = response.candidates[0] if response.candidates else None
+        content_out = getattr(candidate, "content", None) if candidate is not None else None
+
+        if content_out is not None:
+            for part in getattr(content_out, "parts", []):
+                part_inline = getattr(part, "inline_data", None)
+                part_data = (
+                    getattr(part_inline, "data", None)
+                    if part_inline is not None
+                    else None
+                )
+                if part_data:
+                    image_bytes_out = part_data
+                    break
+
+        if not image_bytes_out:
+            return {"status": "failed", "detail": "No image bytes found in model response."}
+
+        # Save the generated diagram
+        await tool_context.save_artifact(
+            "diagram.png",
+            types.Part.from_bytes(data=image_bytes_out, mime_type="image/png"),
+        )
+
+        return {
+            "status": "success",
+            "detail": "Diagram generated successfully and stored in artifacts.",
+            "filename": "diagram.png",
+        }
+
+    except Exception as e:
+        return {"status": "failed", "detail": f"Error generating diagram: {str(e)}"}

research_explainer/tools/flowchart.py

@@ -0,0 +1,66 @@
+"""
+Programmatic flowchart generation tool.
+"""
+
+import graphviz
+from google.adk.tools import ToolContext
+from google.genai import types
+
+
+async def generate_flowchart(
+    nodes_and_colors: dict[str, str],
+    edges: list[list[str]],
+    title: str,
+    tool_context: ToolContext,
+) -> dict:
+    """
+    Generates a flowchart for a research paper based on the nodes to be included, and the connections between them.
+    Returns a dictionary with the status and filename or error detail.
+
+    Args:
+        nodes_and_colors (dict[str,str]): dictionary of the nodes to be included in the flowchart, and their background colors in hex format. Eg: {'node1': '#c1e5f5', 'node2': '#88cc99'}
+        edges (list[tuple[str,str]]): list of tuples of the nodes to be connected, and the connections between them. Eg: [('node1', 'node2'), ('node2', 'node3')] this would draw an arrow from node1 to node2, and from node2 to node3.
+        title (str): the title of the flowchart.
+        tool_context (ToolContext): The context for the tool execution.
+
+    Returns:
+        dict: Contains 'status' ('success' or 'failed'), and either 'filename' or 'detail'.
+    """
+
+    try:
+        # Initialize the Digraph with a specific engine and global attributes
+        dot = graphviz.Digraph(comment=title, engine="dot")
+        dot.attr(rankdir="TB", splines="ortho", pad="0.5", nodesep="0.5")
+        dot.attr("node", style="filled", fontname="Times-Roman", fontsize="16")
+        dot.attr("edge", fontname="Times-Roman", fontsize="16")
+
+        # Define a cluster for the main flow
+        with dot.subgraph(name="cluster_1") as c:
+            c.attr(rankdir="TB", splines="ortho")
+            c.attr("node", shape="box", fontname="Times-Roman", fontsize="16")
+
+            # Define the nodes with their specific colors and labels
+            for node, color in nodes_and_colors.items():
+                c.node(node, node, fillcolor=color)
+
+            # Add edges with labels
+            for edge in edges:
+                c.edge(edge[0], edge[1])
+
+        # Add the title at the top
+        dot.attr(label=title, labelloc="t", fontname="Times-Roman", fontsize="20")
+
+        png_bytes = dot.pipe(format="png")
+        # Save the generated flowchart
+        await tool_context.save_artifact(
+            "flowchart.png",
+            types.Part.from_bytes(data=png_bytes, mime_type="image/png"),
+        )
+        return {
+            "status": "success",
+            "detail": "Flowchart generated successfully and stored in artifacts.",
+            "filename": "flowchart.png",
+        }
+
+    except Exception as e:
+        return {"status": "failed", "detail": f"Error generating flowchart: {str(e)}"}

research_explainer/tools/research_context.py

@@ -0,0 +1,236 @@
+"""
+Live research-context lookup tools.
+"""
+
+import re
+import xml.etree.ElementTree as ET
+
+import requests
+
+SEMANTIC_SCHOLAR_SEARCH_URL = "https://api.semanticscholar.org/graph/v1/paper/search"
+ARXIV_SEARCH_URL = "https://export.arxiv.org/api/query"
+PAPER_FIELDS = "title,abstract,year,authors,url,citationCount,venue,fieldsOfStudy"
+
+
+def _clean_text(value: str | None, max_length: int | None = None) -> str:
+    text = re.sub(r"\s+", " ", value or "").strip()
+    if max_length and len(text) > max_length:
+        return f"{text[: max_length - 3].rstrip()}..."
+    return text
+
+
+def _build_research_query(concept: str, paper_context: str, domain: str) -> str:
+    query_parts = [
+        _clean_text(concept, 120),
+        _clean_text(paper_context, 220),
+        _clean_text(domain, 80),
+    ]
+    return " ".join(part for part in query_parts if part)
+
+
+def _normalize_max_results(max_results: int) -> int:
+    return max(1, min(int(max_results or 5), 10))
+
+
+def _semantic_scholar_papers(query: str, max_results: int) -> list[dict]:
+    response = requests.get(
+        SEMANTIC_SCHOLAR_SEARCH_URL,
+        params={
+            "query": query,
+            "limit": max_results,
+            "fields": PAPER_FIELDS,
+        },
+        timeout=10,
+    )
+    response.raise_for_status()
+    data = response.json()
+
+    papers: list[dict] = []
+    for paper in data.get("data", []):
+        title = _clean_text(paper.get("title"))
+        if not title:
+            continue
+
+        papers.append(
+            {
+                "title": title,
+                "year": paper.get("year"),
+                "authors": [
+                    _clean_text(author.get("name"))
+                    for author in paper.get("authors", [])[:5]
+                    if author.get("name")
+                ],
+                "venue": _clean_text(paper.get("venue")),
+                "url": paper.get("url"),
+                "citation_count": paper.get("citationCount"),
+                "fields_of_study": paper.get("fieldsOfStudy") or [],
+                "abstract": _clean_text(paper.get("abstract"), 700),
+                "source": "Semantic Scholar",
+            }
+        )
+
+    return papers
+
+
+def _arxiv_papers(query: str, max_results: int) -> list[dict]:
+    response = requests.get(
+        ARXIV_SEARCH_URL,
+        params={
+            "search_query": f"all:{query}",
+            "start": 0,
+            "max_results": max_results,
+            "sortBy": "relevance",
+            "sortOrder": "descending",
+        },
+        timeout=10,
+    )
+    response.raise_for_status()
+
+    root = ET.fromstring(response.text)
+    namespace = {"atom": "http://www.w3.org/2005/Atom"}
+    papers: list[dict] = []
+
+    for entry in root.findall("atom:entry", namespace):
+        title = _clean_text(
+            entry.findtext("atom:title", default="", namespaces=namespace)
+        )
+        if not title:
+            continue
+
+        authors = [
+            _clean_text(author.findtext("atom:name", default="", namespaces=namespace))
+            for author in entry.findall("atom:author", namespace)[:5]
+        ]
+        papers.append(
+            {
+                "title": title,
+                "year": (
+                    entry.findtext("atom:published", default="", namespaces=namespace)
+                    or ""
+                )[:4],
+                "authors": [author for author in authors if author],
+                "venue": "arXiv",
+                "url": entry.findtext("atom:id", default="", namespaces=namespace),
+                "citation_count": None,
+                "fields_of_study": [],
+                "abstract": _clean_text(
+                    entry.findtext("atom:summary", default="", namespaces=namespace),
+                    700,
+                ),
+                "source": "arXiv",
+            }
+        )
+
+    return papers
+
+
+def _suggest_research_directions(concept: str, papers: list[dict]) -> list[str]:
+    title_and_abstract = " ".join(
+        f"{paper.get('title', '')} {paper.get('abstract', '')}" for paper in papers
+    ).lower()
+    directions: list[str] = []
+
+    keyword_directions = [
+        (
+            ("efficient", "linear", "sparse", "compression"),
+            f"More efficient versions of {concept}",
+        ),
+        (
+            ("scaling", "large-scale", "foundation", "pretraining"),
+            f"Scaling {concept} to larger models or datasets",
+        ),
+        (
+            ("vision", "image", "multimodal", "video"),
+            f"Using {concept} in vision or multimodal systems",
+        ),
+        (
+            ("retrieval", "knowledge", "rag", "memory"),
+            f"Combining {concept} with retrieval or external knowledge",
+        ),
+        (
+            ("robust", "safety", "bias", "privacy"),
+            f"Studying robustness, safety, or privacy around {concept}",
+        ),
+    ]
+
+    for keywords, direction in keyword_directions:
+        if any(keyword in title_and_abstract for keyword in keywords):
+            directions.append(direction)
+
+    if not directions:
+        directions = [
+            f"Foundational papers that introduced or popularized {concept}",
+            f"Recent applications that adapt {concept} to new tasks",
+            f"Limitations and follow-up methods that improve on {concept}",
+        ]
+
+    return directions[:5]
+
+
+async def find_research_context(
+    concept: str,
+    paper_context: str,
+    domain: str = "machine learning",
+    max_results: int = 5,
+) -> dict:
+    """
+    Finds external research context for a concept discussed in the uploaded paper.
+
+    Use this when the user asks where a concept leads, what uses it, related work,
+    follow-up reading, or how the idea connects to broader research.
+
+    Args:
+        concept (str): The concept or method to investigate.
+        paper_context (str): Paper-specific context that makes the search precise.
+        domain (str): The broader research domain, such as machine learning.
+        max_results (int): Maximum number of papers to return, capped at 10.
+
+    Returns:
+        dict: Related papers, suggested directions, source metadata, or error details.
+    """
+    concept = _clean_text(concept, 120)
+    paper_context = _clean_text(paper_context, 500)
+    domain = _clean_text(domain, 80) or "machine learning"
+    max_results = _normalize_max_results(max_results)
+
+    if not concept:
+        return {
+            "status": "failed",
+            "detail": "Provide a non-empty concept to search for research context.",
+        }
+
+    query = _build_research_query(concept, paper_context, domain)
+    errors: list[str] = []
+
+    try:
+        papers = _semantic_scholar_papers(query, max_results)
+        source = "Semantic Scholar"
+    except Exception as exc:
+        papers = []
+        source = "arXiv"
+        errors.append(f"Semantic Scholar search failed: {exc}")
+
+    if not papers:
+        try:
+            papers = _arxiv_papers(query, max_results)
+            source = "arXiv"
+        except Exception as exc:
+            errors.append(f"arXiv search failed: {exc}")
+
+    if not papers:
+        return {
+            "status": "failed",
+            "query": query,
+            "detail": "No related papers found from Semantic Scholar or arXiv.",
+            "errors": errors,
+        }
+
+    return {
+        "status": "success",
+        "concept": concept,
+        "query": query,
+        "source": source,
+        "suggested_directions": _suggest_research_directions(concept, papers),
+        "papers": papers[:max_results],
+        "errors": errors,
+    }