# Download PDFs

## Basic Usage

```bash
axm-bib pdf 10.48550/arXiv.1706.03762
```

You can also pass an arXiv ID directly:

```bash
axm-bib pdf arXiv:2503.18813
```

Downloads the PDF, extracts content to Markdown, saves figures as PNG, and writes `paper.bib` — all in one command.

### Output Structure

```
~/axm/papers/vaswani2017attention/
├── vaswani2017attention.pdf   # downloaded PDF
├── paper.bib                  # BibTeX entry
├── content.md                 # extracted Markdown
└── figures/
    ├── fig_001.png
    └── ...
```

```
Downloaded: ~/axm/papers/vaswani2017attention
  PDF: vaswani2017attention.pdf (1,234,567 bytes)
  BibTeX: paper.bib
  Markdown: content.md (8,432 words, 45,123 chars, 12 pages)
  Figures: 8
```

## Email Configuration

The Unpaywall API requires an email address. On first use, `axm-bib` will prompt you:

```
Unpaywall requires an email. Enter yours: user@example.com
Saved to ~/.config/axm-bib/config.toml
```

Alternatively, set it via environment variable:

```bash
export UNPAYWALL_EMAIL="user@example.com"
```

Resolution order:

1. `UNPAYWALL_EMAIL` environment variable
2. `~/.config/axm-bib/config.toml`
3. Interactive prompt (saved for next time)

## How the Multi-Source URL Chain Works

```mermaid
graph TD
    A["_build_pdf_urls(ref)"] --> B{Identifier type?}
    B -->|Any| S2["1. S2 Open Access PDF"]
    B -->|arXiv| AX["2. arXiv direct URL"]
    B -->|DOI| UW["3. Unpaywall API"]
    B -->|DOI| FB["4. DOI-based fallbacks"]
    S2 --> TRY["Try URLs in order"]
    AX --> TRY
    UW --> TRY
    FB --> TRY
    TRY -->|Success| F["Save to {key}/ folder"]
    TRY -->|All failed| I[Not open access]
    F --> J[Extract Markdown + figures]
    J --> K["resolve(ref) → paper.bib"]
```

URLs are tried in this priority order:

1. **S2 Open Access PDF** — Semantic Scholar’s open_access_pdf field
2. **arXiv direct** — `arxiv.org/pdf/{id}` (if arXiv ID detected)
3. **Unpaywall** — OA locations sorted by reliability (if DOI available)
4. **DOI-based fallback** — for known OA publishers:
    - arXiv: `10.48550/arXiv.*` → `arxiv.org/pdf/{id}`
    - ACL Anthology: `10.18653/v1/*` → `aclanthology.org/{path}.pdf`

BibTeX is resolved via `resolve(ref)` (not just CrossRef), with graceful fallback if resolution fails.

## Standalone Extraction

Already have a PDF? Use `extract` directly:

```bash
axm-bib extract paper.pdf -o ~/output/
```

This creates `content.md` + `figures/` without downloading.

!!! tip "Figure extraction is resilient"
    Images with CMYK or ICC colorspaces are automatically converted to sRGB.
    Corrupt or unsupported images are skipped gracefully — they won't crash the extraction.

## Not Open Access?

If the paper has no OA version and no known DOI-based fallback:

```
Paper is not open access — no PDF available.
```

## Python API

```python
from axm_bib.pipeline import BibPipeline

pipeline = BibPipeline()
result = pipeline.download_pdf("10.48550/arXiv.1706.03762")
# Also works with arXiv IDs:
# result = pipeline.download_pdf("arXiv:2503.18813")

if result:
    print(f"Folder: {result.paper_dir}")
    print(f"PDF:    {result.path} ({result.size_bytes} bytes)")
    print(f"BibTeX: {result.bibtex_path}")
    if result.extraction:
        ext = result.extraction
        print(f"Markdown: {ext.markdown_path} ({ext.word_count} words, {ext.char_count} chars)")
        print(f"Figures:  {len(ext.figures)}")
else:
    print("Not open access")
```
