# CLAUDE.md - Papercutter

## Overview

PDF to Data Factory: Extract structured data from academic papers.

**Entry point**: `papercutter` CLI (or `python3 -m papercutter`)

**Version**: 3.0.0

## Project Structure

```
src/papercutter/
├── __init__.py      # Version and exports
├── __main__.py      # Entry point
├── cli.py           # Typer CLI (4 commands)
├── project.py       # Inventory management
├── ingest.py        # Docling PDF processing
├── grind.py         # LLM extraction
├── report.py        # CSV + PDF generation
└── templates/
    └── review.tex.j2
```

## CLI Commands

```bash
papercutter ingest ./pdfs/    # PDF → Markdown + Tables
papercutter configure         # Generate columns.yaml schema
papercutter grind             # Extract data via LLM
papercutter report            # Generate matrix.csv + review.pdf
```

## Installation

```bash
pip install papercutter[full]  # All features (docling + llm + reports)
```

## Pipeline

1. **ingest**: Docling converts PDFs to Markdown + extracts tables as JSON
2. **configure**: LLM samples papers and proposes extraction schema
3. **grind**: LLM extracts fields from each paper → extractions.json
4. **report**: Generates matrix.csv (for R/Stata) + review.pdf (Evidence Dossier)

## Configuration

- `columns.yaml`: Define fields to extract (generated by configure)
- `inventory.json`: Tracks paper processing status
- `OPENAI_API_KEY` env var for LLM features

## Dependencies

**Core**: typer, pypdf, pydantic, pyyaml, rich, json-repair

**Optional**:
- `docling` - PDF processing
- `litellm` - LLM provider abstraction
- `jinja2` - PDF report templating

## Development

```bash
pip3 install -e ".[dev,full]"
```

Use `python3` not `python` (macOS compatibility)

## Git Workflow

Always `git push` after commits

## Publishing

```bash
python3 -m build && python3 -m twine upload dist/*
```
