When I tried to pull a bibliography for a literature review, I spent three evenings manually opening PDFs, copying titles, hunting DOIs, and stitching a spreadsheet together. By the time I was done, two papers had already been superseded. The whole process felt like a black‑hole for research time.
That night I asked myself: *What if an LLM could read every PDF on my desk, pull out every citation, verify each reference against CrossRef / arXiv, and draw a live graph that updates as new versions appear?* The answer is a fully‑featured desktop agent built with Claude, a Python GUI, and a tiny SQLite store. The following guide shows how to make that happen in 2026‑ready code.
- Claude + Python can turn a folder of PDFs into a live, verified citation graph.
- Use PyMuPDF for robust PDF text extraction and fall back to OCR when needed.
- Anthropic’s structured‑output feature guarantees valid JSON from Claude.
- Thread Claude calls and web lookups off the UI thread with QThreadPool.
- Persist everything in SQLite and schedule periodic refreshes.
Before you start: Python 3.12+, Anthropic SDK v2.x, Claude 3.7 Sonnet/Opus, PyQt6 6.7+, PyMuPDF 1.24+, SQLite3 (built‑in), Requests 2.32+, optional Tesseract 5 for OCR, API keys for Anthropic, CrossRef, arXiv, and OpenAlex.
How do I build a PDF reference‑tracking agent with Claude and a Python GUI?
You build a reference‑tracking agent for academic PDFs by combining Claude’s reasoning, a PDF parser, and web APIs inside a PyQt GUI. The agent ingests PDFs, extracts citations with Claude, looks them up via CrossRef/arXiv, and visualizes a citation graph. The 2026 stack uses Anthropic SDK tool use, threaded UI, and SQLite persistence.
Architecture: Blueprint for a Production‑Ready Agent
Below is the high‑level component diagram. The arrows show the dominant data flow, not every internal method call.
graph TD
UI[GUI] -->|user action| Core[Agent Core]
Core -->|parse| PDF[PDF Parser]
Core -->|prompt| Claude[Claude API]
Claude -->|structured JSON| Graph[Citation Graph DB]
Core -->|lookup| Tools[External Lookup Tools]
Tools -->|verified meta| Graph
UI -->|render| Viz[Citation Graph Panel]
UI -->|log| Console[Agent Console]
Core component diagram
- Agent Core – orchestrates parsing, prompting, and tool dispatch. It holds a short‑lived memory of the current session and coordinates retries.
- Tool Set – thin wrappers around CrossRef, arXiv, OpenAlex, and optional DOI resolution. All tools respect a shared rate‑limiter.
- UI Layer – PyQt6 windows, widgets, and a console that streams Claude tokens. Heavy work runs in a
QThreadPoolto keep the UI responsive. - Data Store – SQLite file (
references.db) with three tables:papers,citations,metadata. The schema is deliberately normalized to keep the graph query fast.
Standalone Desktop vs. Embedded Claude Desktop
Two paths exist:
- Standalone PyQt/Tauri app – full control over UI, persistent local DB, and native OS integration (file dialogs, system tray). This is what the guide implements.
- Claude Computer Use (Claude Desktop) – you can let Claude manipulate a pre‑built UI via the Computer Use API. It works for quick prototypes but lacks a dedicated persistence layer and granular UI feedback.
I favor the standalone approach for research‑intensive workflows because you can store a multi‑GB graph, schedule background refreshes, and expose the UI to collaborators. If you only need a proof‑of‑concept, check the *Claude AI GUI Agent: Drag‑Drop Workflow Build (2026)* page for a minimal setup.
State flow design
- User drops PDFs → UI enqueues a
ParseAndExtracttask. - Worker thread extracts raw text, builds a prompt, calls Claude, receives structured citations.
- Agent Core stores raw citations, then fires
LookupCitationtasks for each entry. - Lookup workers hit CrossRef / arXiv, apply exponential back‑off, and write verified metadata back to SQLite.
- UI receives “graph updated” signals, refreshes the visualization, and logs each step in the console.
—
Step 1 – Setting Up the Foundational Toolset
1.1 Environment bootstrap
# Create an isolated environment
python3.12 -m venv .venv
source .venv/bin/activate
# Pin exact versions (helps reproducibility)
pip install "anthropic==2.5.0" "pyqt6==6.7.0" "PyMuPDF==1.24.0" \
"requests==2.32.0" "pydantic==2.6.0" "tiktoken==0.6.0"
If you need OCR fallback, install Tesseract‑5 and pytesseract:
sudo apt-get install tesseract-ocr
pip install pytesseract==0.3.10
1.2 Core libraries overview
| Library | Role |
|---|---|
| PyMuPDF (fitz) | Fast, low‑memory PDF text extraction and page‑image rendering. |
| Requests | Simple HTTP client for CrossRef / arXiv / OpenAlex. |
| SQLite3 | Built‑in, zero‑config persistence. |
| Anthropic SDK | Official 2026 client supporting structured output and tool‑use. |
| Pydantic | Declarative JSON schema for Claude’s output. |
| PyQt6 | Native‑look desktop UI with threading support. |
1.3 Prompt engineering for reliable JSON
Claude 3.7 can return typed objects when you supply a *schema* (output_schema field). Define a Pydantic model that mirrors the citation fields you care about:
# citation_schema.py
from pydantic import BaseModel, Field
from typing import List, Optional
class Citation(BaseModel):
title: str = Field(..., description="Exact title as it appears in the PDF")
authors: List[str] = Field(..., description="List of author full names")
year: Optional[int] = Field(None, description="Publication year if detectable")
raw_citation: str = Field(..., description="Original inline citation string")
doi: Optional[str] = Field(None, description="DOI extracted from the citation")
arxiv_id: Optional[str] = Field(None, description="arXiv identifier, if any")
Later we will pass Citation.schema_json() to the Anthropic SDK, which guarantees the response conforms to this shape. No need for fragile regex parsing on Claude’s free‑form text.
—
Step 2 – Building the Core Reference Parser Agent
2.1 PDF ingestion with error handling
# pdf_ingest.py
import fitz # PyMuPDF
import pytesseract
from pathlib import Path
from typing import List, Tuple
def extract_text_from_pdf(pdf_path: Path) -> str:
"""Return plain text from a PDF, falling back to OCR on unreadable pages."""
try:
doc = fitz.open(pdf_path)
except Exception as exc:
raise RuntimeError(f"Unable to open {pdf_path}: {exc}") from exc
full_text = []
for page_num, page in enumerate(doc, start=1):
try:
# Try native text extraction first
text = page.get_text("text")
if text.strip():
full_text.append(text)
continue
except Exception:
pass # fall through to OCR
# OCR fallback – render page as image then run Tesseract
pix = page.get_pixmap(dpi=200)
ocr_text = pytesseract.image_to_string(pix.tobytes())
full_text.append(ocr_text)
return "\n".join(full_text)
Why this matters: PDFs scraped from pre‑prints often contain scanned images. The OCR fallback eliminates silent failures that would otherwise drop entire sections.
2.2 Claude prompt chain
# claude_prompt.py
from anthropic import Anthropic, NOT_GIVEN
from citation_schema import Citation
import json
anthropic = Anthropic(api_key="YOUR_ANTHROPIC_API_KEY")
def extract_citations(pdf_text: str) -> List[Citation]:
system_prompt = (
"You are an academic research assistant. Given the raw text of a scholarly PDF, "
"identify every inline citation (e.g., [1], (Smith et al., 2020), etc.) and return "
"a JSON array of objects matching the provided schema. Do not hallucinate fields; "
"if a DOI/arXiv ID is missing, set it to null."
)
response = anthropic.messages.create(
model="claude-3-7-sonnet-202406",
max_tokens=4096,
temperature=0.0,
system=system_prompt,
messages=[{"role": "user", "content": pdf_text}],
# Structured output: tell Claude to obey the schema
output_schema=Citation.schema(),
)
# The SDK returns a typed dict if the response matches the schema
citations_json = response.content[0].text
try:
parsed = json.loads(citations_json)
return [Citation(**item) for item in parsed]
except json.JSONDecodeError as exc:
raise ValueError(f"Claude returned malformed JSON: {exc}") from exc
Key point: Setting temperature=0.0 and providing a schema removes stochastic drift. The call will either succeed with well‑formed JSON or raise, allowing us to retry automatically.
2.3 Building the citation graph data model
# db_schema.py
import sqlite3
from pathlib import Path
DB_PATH = Path("references.db")
def init_db():
conn = sqlite3.connect(DB_PATH)
cur = conn.cursor()
cur.execute("""
CREATE TABLE IF NOT EXISTS papers (
id INTEGER PRIMARY KEY,
file_path TEXT UNIQUE,
title TEXT,
added_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)
""")
cur.execute("""
CREATE TABLE IF NOT EXISTS citations (
id INTEGER PRIMARY KEY,
paper_id INTEGER,
raw_citation TEXT,
title TEXT,
authors TEXT,
year INTEGER,
doi TEXT,
arxiv_id TEXT,
verified BOOLEAN DEFAULT 0,
FOREIGN KEY(paper_id) REFERENCES papers(id)
)
""")
cur.execute("""
CREATE TABLE IF NOT EXISTS metadata (
doi TEXT PRIMARY KEY,
title TEXT,
authors TEXT,
year INTEGER,
source TEXT,
fetched_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)
""")
conn.commit()
conn.close()
The authors column stores a JSON‑encoded list; we keep verified as a flag that flips after successful lookup.
—
Step 3 – Implementing the GUI & Interactive Event Loop (PyQt Example)
3.1 Main window layout
# gui_main.py
import sys
from pathlib import Path
from PyQt6.QtWidgets import (
QApplication, QMainWindow, QWidget, QVBoxLayout,
QPushButton, QListWidget, QTextEdit, QFileDialog, QLabel
)
from PyQt6.QtCore import Qt, QThreadPool, QRunnable, pyqtSlot, QObject, pyqtSignal
from pdf_ingest import extract_text_from_pdf
from claude_prompt import extract_citations
from db_schema import init_db, DB_PATH
class WorkerSignals(QObject):
finished = pyqtSignal()
error = pyqtSignal(str)
result = pyqtSignal(object) # generic payload
class TaskRunner(QRunnable):
"""Runs a callable in a thread and emits signals."""
def __init__(self, fn, *args, **kwargs):
super().__init__()
self.fn = fn
self.args = args
self.kwargs = kwargs
self.signals = WorkerSignals()
@pyqtSlot()
def run(self):
try:
result = self.fn(*self.args, **self.kwargs)
except Exception as exc:
self.signals.error.emit(str(exc))
else:
self.signals.result.emit(result)
finally:
self.signals.finished.emit()
class MainWindow(QMainWindow):
def __init__(self):
super().__init__()
self.setWindowTitle("PDF Reference Tracker")
self.resize(1200, 800)
central = QWidget()
self.setCentralWidget(central)
layout = QVBoxLayout(central)
# Top controls
self.add_btn = QPushButton("Add PDFs")
self.add_btn.clicked.connect(self.pick_files)
layout.addWidget(self.add_btn)
# PDF list
self.pdf_list = QListWidget()
layout.addWidget(QLabel("Loaded PDFs"))
layout.addWidget(self.pdf_list)
# Console for streaming Claude tokens
self.console = QTextEdit()
self.console.setReadOnly(True)
layout.addWidget(QLabel("Agent console"))
layout.addWidget(self.console)
# Thread pool
self.pool = QThreadPool.globalInstance()
# Initialise DB (idempotent)
init_db()
def log(self, msg: str):
self.console.append(msg)
def pick_files(self):
files, _ = QFileDialog.getOpenFileNames(
self, "Select PDF files", "", "PDF Files (*.pdf)"
)
for f in files:
self.pdf_list.addItem(f)
self.enqueue_parsing(Path(f))
def enqueue_parsing(self, pdf_path: Path):
self.log(f"⏳ Queued parsing for {pdf_path.name}")
task = TaskRunner(self.process_pdf, pdf_path)
task.signals.result.connect(self.handle_citations)
task.signals.error.connect(lambda e: self.log(f"❗ Error: {e}"))
task.signals.finished.connect(lambda: self.log(f"✅ Finished {pdf_path.name}"))
self.pool.start(task)
def process_pdf(self, pdf_path: Path):
text = extract_text_from_pdf(pdf_path)
citations = extract_citations(text)
return {"path": pdf_path, "citations": citations}
def handle_citations(self, payload):
path = payload["path"]
citations = payload["citations"]
self.log(f"🚀 Received {len(citations)} citations from {path.name}")