Athena

A local academic research assistant that runs entirely on your machine. Drop PDFs into a folder — Athena indexes them, builds a searchable vector library, and exposes tools to Claude Desktop for semantic search, claim extraction, contradiction detection, and multi-step research synthesis.

What It Does

• Semantic search across your paper library with section-level filtering (search only results sections, only abstracts, etc.)

• Contradiction detection — surfaces conflicting claims across papers on a given topic

• Definition extractor — shows how different papers define the same term

• Related paper suggestions from Semantic Scholar for papers not in your library

• Full research agent — refines your query, extracts claims, detects contradictions, and returns a structured markdown report

• Automatic metadata enrichment — extracts titles from font analysis, verifies against Semantic Scholar, fills in authors/year/abstract

Related MCP server: ragi

Architecture

Claude Desktop
    │
    │  MCP (stdio — no tunnel needed)
    ▼
FastMCP Server (server/tools.py)
    │
    ├── ChromaDB  — vectors + chunk metadata (semantic search)
    ├── SQLite    — paper metadata (structured queries)
    └── LangGraph Agent (agent/graph.py)
            │
            └── Groq / Llama 3.3-70b  — query refinement, claim extraction, synthesis

Storage split: SQLite handles structured paper metadata (title, authors, year). ChromaDB stores chunks with their embeddings and attached metadata, enabling hybrid queries — semantic similarity + structured filters in one call.

Parent/child chunking: each paper section is split into large parent chunks (~512 tokens) and small child chunks (~128 tokens). Retrieval uses children for precise matching; the LLM receives parents for full context.

Section-aware indexing: section_type is stored on every chunk (abstract, introduction, methods, results, conclusion). Tools filter to specific sections — contradiction detection searches results/conclusions, definition extraction searches abstract/intro/methods.

Setup

Prerequisites

• Python 3.12+

• uv — pip install uv

• A free Groq API key

Install

git clone <repo>
cd athena
uv sync

Create a .env file:

GROQ_API_KEY=your_key_here

Index Papers

Start the file watcher — drop PDFs into data/raw/ and they get indexed automatically:

uv run python -m pdf_ingestion.watcher

Papers already in data/raw/ when the watcher starts are indexed on startup. The watcher is idempotent — restart it any time without re-indexing completed papers.

Use the CLI

# Full research agent
uv run python cli.py "What are the main approaches to guided diffusion?"

# Quick semantic search (no LLM)
uv run python cli.py --search "score-based generative models"

# List all indexed papers
uv run python cli.py --list

# How different papers define a term
uv run python cli.py --define "latent space"

Use with Claude Desktop (Recommended)

Install as a native extension — no tunnel, no URL, no re-configuration on restarts:

1. Build the extension package:

   uv run python build_dxt.py

2. Open Claude Desktop → Extensions → drag athena.dxt onto the page

3. Enter your Groq API key when prompted

4. Optionally set a Library Directory (defaults to ~/Documents/Athena) — put your PDFs in the raw/ subfolder inside that directory

5. Start a new chat — Athena tools are available immediately

On first use, ask Claude: "Check if Athena is ready" — it will call get_status and confirm the embedding model has finished loading before you search.

Use with Claude Desktop (Dev / HTTP)

For local development with HTTP transport:

.\start_athena.ps1

This starts uvicorn on port 8000 and a Cloudflare quick tunnel. Copy the tunnel URL into Claude Desktop → Connectors → Add connector. Note the URL changes on every restart.

Project Structure

athena/
├── agent/
│   └── graph.py              — LangGraph 6-node research agent
├── chunker/
│   └── chunker.py            — parent/child chunking with sentence boundaries
├── db/
│   └── database.py           — SQLite paper lifecycle management
├── embedding/
│   └── embedder.py           — sentence-transformers + ChromaDB storage
├── pdf_ingestion/
│   ├── metadata_enricher.py  — title extraction + Semantic Scholar lookup
│   ├── parser.py             — PyMuPDF extraction with font analysis
│   ├── section_detector.py   — 4-signal header detection
│   └── watcher.py            — watchdog file watcher + pipeline orchestration
├── server/
│   └── tools.py              — 8 MCP tools via FastMCP
├── cli.py                    — terminal interface
├── config.py                 — data directory configuration
├── build_dxt.py              — packages source into athena.dxt
├── manifest.json             — Claude Desktop extension manifest
└── start_athena.ps1          — dev script: uvicorn + cloudflared tunnel

MCP Tools

Tech Stack