Metadata-Version: 2.4
Name: axm-bib
Version: 0.1.0
Summary: AXM bibliographic tools — DOI resolution, BibTeX retrieval, paper search & PDF download
Author-email: Gabriel Jarry <jarry.gabriel@gmail.com>
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: bibtexparser>=1.4
Requires-Dist: cyclopts>=4.5.1
Requires-Dist: habanero>=1.2
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Description-Content-Type: text/markdown

# axm-bib

**Bibliographic tools: search papers, resolve DOIs to BibTeX, download open-access PDFs.**

<p align="center">
  <a href="https://github.com/axm-protocols/axm-bib/actions/workflows/ci.yml"><img src="https://github.com/axm-protocols/axm-bib/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://coveralls.io/github/axm-protocols/axm-bib?branch=main"><img src="https://coveralls.io/repos/github/axm-protocols/axm-bib/badge.svg?branch=main" alt="Coverage"></a>
  <a href="https://pypi.org/project/axm-bib/"><img src="https://img.shields.io/pypi/v/axm-bib" alt="PyPI"></a>
  <img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python 3.12+">
  <img src="https://img.shields.io/badge/typed-strict-blue" alt="Typed">
  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
  <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv"></a>
  <a href="https://axm-protocols.github.io/axm-bib/"><img src="https://img.shields.io/badge/docs-live-brightgreen" alt="Docs"></a>
</p>

---

## Features

- 🔍 **Search** — Find papers by title/keywords (Semantic Scholar + CrossRef fallback)
- 📖 **DOI → BibTeX** — Resolve any DOI to a BibTeX entry (CrossRef)
- 📥 **PDF Download** — Download open-access PDFs (Unpaywall + arXiv fallback)
- 🤖 **MCP Integration** — Auto-discovered tools via `axm-mcp`

## Installation

```bash
uv add axm-bib
```

## Quick Start

```bash
# Search papers
axm-bib search "attention is all you need" -n 5

# Resolve a DOI to BibTeX
axm-bib doi 10.1145/363235.363259

# Download an open-access PDF
axm-bib pdf 10.48550/arXiv.1706.03762
```

## CLI Options

### `axm-bib search`

| Option | Default | Description |
|---|---|---|
| `QUERY` | *required* | Search query (title, keywords) |
| `--limit`, `-n` | 5 | Max results (1–100) |
| `--abstract/--no-abstract` | `True` | Show paper abstracts |
| `--abstract-len` | 0 (full) | Truncate abstracts to N chars |

### `axm-bib doi`

| Option | Description |
|---|---|
| `DOI` | Digital Object Identifier to resolve |

### `axm-bib pdf`

| Option | Default | Description |
|---|---|---|
| `DOI` | *required* | DOI of the paper |
| `--output`, `-o` | auto | Output directory |

## MCP Integration

`axm-bib` tools are automatically discovered by `axm-mcp`:

- `search_paper(query, limit)` — Search papers
- `doi_to_bibtex(doi)` — Resolve DOI
- `get_pdf(doi)` — Download PDF

## Configuration

| Variable | Purpose |
|---|---|
| `UNPAYWALL_EMAIL` | Email for Unpaywall API (prompted on first use) |
| `S2_API_KEY` | Optional Semantic Scholar API key for higher rate limits |

Config file: `~/.config/axm-bib/config.toml`

## Development

```bash
git clone https://github.com/axm-protocols/axm-bib.git
cd axm-bib
uv sync --all-extras
uv run pytest           # 122 tests, 93% coverage
uv run ruff check src/  # lint
```

## License

Apache License 2.0