feat: Add research-paper-analyzer kit

kits/research-paper-analyzer/.gitignore

@@ -0,0 +1,5 @@
+.env
+.env.local
+apps/node_modules
+apps/.next
+apps/.vercel

kits/research-paper-analyzer/README.md

@@ -0,0 +1,127 @@
+# Research Paper Analyzer
+
+An AI-powered kit that takes any academic PDF URL and returns a structured breakdown:
+
+- **Problem Statement** — what the research is trying to solve and why it matters
+- **Methodology** — how the study was conducted
+- **Key Findings** — the main results and conclusions
+- **Limitations** — acknowledged weaknesses or gaps
+- **Plain English Summary** — jargon-free explanation for non-specialists
+- **Follow-up Questions** — ideas for future research directions
+
+Built on [Lamatic.ai](https://lamatic.ai) with a **FastAPI** backend and a **React + Vite** frontend (JavaScript/JSX).
+
+---
+
+## Architecture
+
+```
+React (Vite/JSX)  →  FastAPI (Python)  →  Lamatic Flow  →  LLM
+   frontend              backend            orchestration
+ localhost:5173       localhost:8000
+```
+
+---
+
+## Quick Start
+
+### 1. Deploy the Flow in Lamatic Studio
+
+1. Go to [studio.lamatic.ai](https://studio.lamatic.ai) → New Project → New Flow
+2. Add nodes in this order:
+   - **API Trigger** — input schema: `{ pdf_url: string }`
+   - **Extract From File** — file URL: `{{trigger.pdf_url}}`
+   - **LLM Node** — use prompt from `prompts/analyze-paper.md`, structured JSON output
+   - **API Response** — output: `{{LLMNode.output}}`
+3. Deploy the flow and copy the **Flow ID** from Settings
+
+### 2. Start the FastAPI Backend
+
+```bash
+cd apps/backend
+cp .env.example .env
+# Fill in your Flow ID and Lamatic credentials in .env
+pip install -r requirements.txt
+uvicorn main:app --reload
+```
+
+Backend runs at [http://localhost:8000](http://localhost:8000).  
+Check [http://localhost:8000/docs](http://localhost:8000/docs) for the auto-generated API docs.
+
+`.env` values to fill in:
+```
+RESEARCH_PAPER_ANALYZER_FLOW_ID=<your-flow-id>
+LAMATIC_API_URL=<from Lamatic Settings>
+LAMATIC_PROJECT_ID=<from Lamatic Settings>
+LAMATIC_API_KEY=<from Lamatic Settings>
+```
+
+### 3. Start the React Frontend
+
+```bash
+cd apps/frontend
+npm install
+npm run dev
+```
+
+Frontend runs at [http://localhost:5173](http://localhost:5173).  
+Vite proxies `/analyze` → FastAPI automatically, so no CORS issues in dev.
+
+---
+
+## Usage
+
+1. Paste any publicly accessible PDF URL (e.g., an arXiv paper)
+2. Click **Analyze Paper**
+3. Browse the structured breakdown — expand/collapse each section
+4. Click **JSON** to copy the raw JSON output
+
+### Example URLs to try
+
+- `https://arxiv.org/pdf/2303.08774.pdf` — GPT-4 Technical Report
+- `https://arxiv.org/pdf/1706.03762.pdf` — Attention Is All You Need
+
+---
+
+## API Reference
+
+### `POST /analyze`
+
+**Request:**
+```json
+{ "pdf_url": "https://arxiv.org/pdf/2303.08774.pdf" }
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "title": "...",
+    "authors": ["..."],
+    "year": 2023,
+    "problem_statement": "...",
+    "methodology": "...",
+    "key_findings": ["..."],
+    "limitations": ["..."],
+    "plain_english_summary": "...",
+    "follow_up_questions": ["..."]
+  }
+}
+```
+
+---
+
+## Tech Stack
+
+- **Backend**: FastAPI, Python, httpx, Pydantic, python-dotenv
+- **Frontend**: React.js, Vite, JavaScript/JSX, Tailwind CSS, Lucide React
+- **AI Orchestration**: Lamatic.ai flows
+
+---
+
+## Requirements
+
+- Python 3.10+
+- Node.js 18+, npm 9+
+- Lamatic.ai account ([sign up free](https://lamatic.ai))

kits/research-paper-analyzer/agent.md

@@ -0,0 +1,44 @@
+# Research Paper Analyzer Agent
+
+## Identity
+
+You are an expert academic research analyst. Your role is to read scientific papers and produce clear, structured analyses that help researchers, students, and professionals quickly understand complex academic work.
+
+## Capabilities
+
+- Extract and articulate the core research problem and motivation
+- Identify and explain the methodology used
+- Summarize key findings and results objectively
+- Surface limitations and potential gaps in the research
+- Translate academic language into plain English for non-specialists
+- Generate thoughtful follow-up research questions
+
+## Behavior Guidelines
+
+- Always base your analysis strictly on the paper content — do not hallucinate facts
+- Be objective; do not editorialize beyond what the paper states
+- If a section of the paper is unclear or missing, state that explicitly
+- Keep the plain-English summary accessible to a smart non-expert
+- Format all output as structured JSON matching the defined schema
+
+## Output Schema
+
+```json
+{
+  "title": "string",
+  "authors": ["string"],
+  "year": "number | null",
+  "problem_statement": "string",
+  "methodology": "string",
+  "key_findings": ["string"],
+  "limitations": ["string"],
+  "plain_english_summary": "string",
+  "follow_up_questions": ["string"]
+}
+```
+
+## Constraints
+
+- Never invent citations, statistics, or claims not present in the paper
+- Refuse requests to misrepresent or plagiarize research
+- If the uploaded file is not an academic paper, respond with a clear error message

kits/research-paper-analyzer/apps/backend/.env.example

@@ -0,0 +1,4 @@
+RESEARCH_PAPER_ANALYZER_FLOW_ID=your_flow_id_here
+LAMATIC_API_URL=https://your-lamatic-endpoint.lamatic.ai
+LAMATIC_PROJECT_ID=your_project_id_here
+LAMATIC_API_KEY=your_api_key_here

kits/research-paper-analyzer/apps/backend/.gitignore

@@ -0,0 +1,7 @@
+.env
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+env/

kits/research-paper-analyzer/apps/backend/main.py

@@ -0,0 +1,128 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, field_validator
+from urllib.parse import urlparse
+import ipaddress
+import httpx
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+LAMATIC_API_URL = os.getenv("LAMATIC_API_URL", "").rstrip("/")
+LAMATIC_PROJECT_ID = os.getenv("LAMATIC_PROJECT_ID", "")
+LAMATIC_API_KEY = os.getenv("LAMATIC_API_KEY", "")
+FLOW_ID = os.getenv("RESEARCH_PAPER_ANALYZER_FLOW_ID", "")
+
+# Lamatic uses GraphQL — single POST endpoint per project
+EXECUTE_QUERY = """
+query ExecuteWorkflow($workflowId: String!, $payload: JSON) {
+  executeWorkflow(workflowId: $workflowId, payload: $payload) {
+    status
+    result
+  }
+}
+"""
+
+app = FastAPI(title="Research Paper Analyzer", version="1.0.0")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:5173", "http://localhost:3000"],
+    allow_methods=["POST", "GET"],
+    allow_headers=["*"],
+)
+
+
+_BLOCKED_RANGES = [
+    ipaddress.ip_network("10.0.0.0/8"),
+    ipaddress.ip_network("172.16.0.0/12"),
+    ipaddress.ip_network("192.168.0.0/16"),
+    ipaddress.ip_network("127.0.0.0/8"),
+    ipaddress.ip_network("169.254.0.0/16"),  # link-local / cloud IMDS
+    ipaddress.ip_network("0.0.0.0/8"),
+    ipaddress.ip_network("::1/128"),
+    ipaddress.ip_network("fc00::/7"),
+]
+
+
+class AnalyzeRequest(BaseModel):
+    pdf_url: str
+
+    @field_validator("pdf_url")
+    @classmethod
+    def validate_pdf_url(cls, v: str) -> str:
+        parsed = urlparse(v)
+        if parsed.scheme not in {"https"}:
+            raise ValueError("Only HTTPS URLs are accepted.")
+        hostname = parsed.hostname or ""
+        if not hostname:
+            raise ValueError("URL must contain a valid hostname.")
+        try:
+            ip = ipaddress.ip_address(hostname)
+            if any(ip in net for net in _BLOCKED_RANGES):
+                raise ValueError("URL resolves to a private or reserved address.")
+        except ValueError as exc:
+            if "private or reserved" in str(exc):
+                raise
+            # hostname is a domain name — pass through
+        return v
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok"}
+
+
+@app.post("/analyze")
+async def analyze_paper(req: AnalyzeRequest):
+    if not FLOW_ID:
+        raise HTTPException(500, "RESEARCH_PAPER_ANALYZER_FLOW_ID is not set.")
+    if not LAMATIC_API_URL or not LAMATIC_API_KEY or not LAMATIC_PROJECT_ID:
+        raise HTTPException(500, "Lamatic API credentials are not set.")
+
+    headers = {
+        "Authorization": f"Bearer {LAMATIC_API_KEY}",
+        "x-project-id": LAMATIC_PROJECT_ID,
+        "Content-Type": "application/json",
+    }
+
+    body = {
+        "query": EXECUTE_QUERY,
+        "variables": {
+            "workflowId": FLOW_ID,
+            "payload": {"pdf_url": req.pdf_url},
+        },
+    }
+
+    try:
+        async with httpx.AsyncClient(timeout=120.0) as client:
+            response = await client.post(LAMATIC_API_URL, headers=headers, json=body)
+
+        if response.status_code == 401:
+            raise HTTPException(401, "Invalid Lamatic API key or project ID.")
+        if response.status_code != 200:
+            raise HTTPException(response.status_code, f"Lamatic API error: {response.text}")
+
+        data = response.json()
+
+        # GraphQL errors surface inside data.errors
+        if "errors" in data:
+            raise HTTPException(500, f"Flow error: {data['errors'][0].get('message', 'unknown')}")
+
+        execute_result = data.get("data", {}).get("executeWorkflow", {})
+
+        if execute_result.get("status") != "success":
+            raise HTTPException(500, f"Flow did not succeed: {execute_result.get('status')}")
+
+        analysis = execute_result.get("result")
+
+        if not analysis:
+            raise HTTPException(500, "No analysis returned by the flow.")
+
+        return {"success": True, "data": analysis}
+
+    except httpx.TimeoutException:
+        raise HTTPException(504, "Request timed out. The PDF may be too large.")
+    except httpx.RequestError as e:
+        raise HTTPException(503, f"Network error: {str(e)}")

kits/research-paper-analyzer/apps/backend/requirements.txt

@@ -0,0 +1,5 @@
+fastapi>=0.111.0
+uvicorn[standard]>=0.29.0
+httpx>=0.27.0
+python-dotenv>=1.0.0
+pydantic>=2.0.0

kits/research-paper-analyzer/apps/frontend/.env.example

@@ -0,0 +1,3 @@
+# Leave empty when using Vite's built-in proxy (dev mode)
+# Set to your deployed FastAPI URL for production builds
+VITE_BACKEND_URL=

kits/research-paper-analyzer/apps/frontend/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.env
+.env.local

kits/research-paper-analyzer/apps/frontend/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Research Paper Analyzer · Lamatic.ai</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

kits/research-paper-analyzer/apps/frontend/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "research-paper-analyzer-frontend",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "lucide-react": "^0.469.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.1",
+    "autoprefixer": "^10.4.19",
+    "postcss": "^8.4.38",
+    "tailwindcss": "^3.4.4",
+    "vite": "^5.3.1"
+  }
+}

kits/research-paper-analyzer/apps/frontend/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};