Metadata-Version: 2.4
Name: respf
Version: 1.3.1
Summary: Download academic papers from Unpaywall, OpenAlex, PubMed, bioRxiv, ArXiv, and more (no LLM)
Author-email: Madhav <support@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/madhaviit/respf-python
Keywords: research,papers,academic,download,arxiv,doi,pubmed,biorxiv,open-access,agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8.1
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: beautifulsoup4>=4.11.0
Requires-Dist: arxiv>=1.4.0
Requires-Dist: lxml>=4.9.0
Requires-Dist: aiohttp>=3.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: summarize
Requires-Dist: pdftotext>=2.1.5; extra == "summarize"
Dynamic: license-file

# respf - Research Paper Fetcher

A Python package for downloading academic papers across **all research fields** (CS, biology, medicine, physics, and more). No LLM calls: only APIs, metadata, and deterministic title matching.

## Installation

```bash
pip install respf
# or local dev:
cd final && uv venv && uv pip install -e ".[dev]"
```

## Sources

| Source | Best for |
|--------|----------|
| `acl` | ACL Anthology (NLP/CL proceedings) — IDs, URLs, titles |
| `acm` | ACM Digital Library (`10.1145/*`, `dl.acm.org`) |
| `crossref` | Journal DOIs via Crossref PDF links in metadata |
| `plos` | PLOS open-access journals (`10.1371/*`) |
| `hal` | HAL open archive (hal.science) |
| `osf` | OSF preprints |
| `ieee` | IEEE Xplore (when stamp PDF is open) |
| `direct_url` | Direct PDF URLs, Springer/Nature heuristics |
| `unpaywall` | Any DOI with legal open-access PDF |
| `pubmed` | Biology / medicine (PMC open access) |
| `biorxiv` | bioRxiv & medRxiv preprints |
| `openalex` | Cross-disciplinary search & OA links |
| `arxiv` | Physics, CS, math preprints |
| `europepmc` | Biomedical literature (Europe PMC API) |
| `zenodo` | Open research records (`10.5281/zenodo.*`) |
| `semantic_scholar` | DOI/title with openAccessPdf |
| `google_scholar` | Fallback PDF discovery |
| `springer`, `acm`, `github` | Publisher / repo search |

Default **source order depends on identifier type** (DOI tries Unpaywall first; PMID tries PubMed first; titles try OpenAlex before ArXiv).

## Usage

### CLI

```bash
# List sources
respf --list-sources

# How will this identifier be resolved? (no download)
respf --resolve "10.1038/nature12373" --json

# Download by DOI (biology, any field)
respf "10.1038/nature12373"

# Download by PubMed ID
respf "https://pubmed.ncbi.nlm.nih.gov/12345678/"

# Download by title (title similarity verification, no LLM)
respf "Attention Is All You Need"

# Direct PDF URL (e.g. ACL Anthology)
respf "https://aclanthology.org/2025.findings-emnlp.1074.pdf"

# Explicit sources
respf "10.1101/2020.01.01.123456" --sources unpaywall,biorxiv,openalex

# Citations file with --parse (APA, IEEE, BibTeX, PubMed, PMC, bioRxiv URLs)
respf --file citations.txt --parse --dir ./papers

# Metadata without download (OpenAlex / Unpaywall)
respf --info "10.1038/nature12373" --json

# Dry-run: routing + metadata, no PDF
respf --dry-run "10.1038/nature12373" --json

# Batch with 4 parallel workers
respf --file citations.txt --parse --workers 4

# Agent capability manifest (JSON)
respf --capabilities
```

### Agent / programmatic API

Structured JSON-friendly responses with `resolved`, `error_code`, and routing metadata.

```python
from respf import (
    ResearchPaperDownloader,
    agent_capabilities,
    agent_fetch,
    agent_lookup,
    agent_resolve,
    download_paper,
    resolve_identifier,
    list_sources,
    parse_identifier,
)

# Agent session bootstrap
print(agent_capabilities())

# Discover sources
print(list_sources())

# Route before downloading (agents)
routing = resolve_identifier("10.1038/nature12373")
# {"kind": "doi", "recommended_sources": ["direct_url", "unpaywall", ...], ...}

downloader = ResearchPaperDownloader(download_dir="papers")
result = downloader.download_paper("10.1038/nature12373")
# result["success"], result["results"][0]["filepath"], result["resolved"]

info = downloader.get_paper_info("10.1038/nature12373")  # no PDF download

# Or agent helpers (stable JSON shapes)
agent_lookup("10.1038/nature12373")
agent_fetch("10.1038/nature12373", dry_run=True)
```

### Environment (optional)

| Variable | Purpose |
|----------|---------|
| `UNPAYWALL_EMAIL` | Polite pool email for Unpaywall API |
| `OPENALEX_EMAIL` | Polite pool for OpenAlex |
| `SEMANTIC_SCHOLAR_API_KEY` | Higher rate limits for Semantic Scholar |

## Accuracy (no LLM)

- **Identifier routing**: DOI, PMID, PMC, ArXiv, bioRxiv, and direct PDF URLs go to the right source first.
- **Title search**: `difflib` similarity; downloads rejected if best match score &lt; 0.62 (ArXiv/OpenAlex/Semantic Scholar).
- **PDF verification**: Every download checked for `%PDF` magic bytes and minimum size.

## PDF Summarization

```bash
pip install respf[summarize]
respf --summarize --dir ./papers
```

## License

MIT
