Metadata-Version: 2.5
Name: axm-bib
Version: 0.4.0
Summary: AXM bibliographic tools — DOI resolution, BibTeX retrieval, paper search & PDF download
Project-URL: Homepage, https://github.com/axm-protocols/axm-knowledge
Project-URL: Repository, https://github.com/axm-protocols/axm-knowledge.git
Project-URL: Issues, https://github.com/axm-protocols/axm-knowledge/issues
Project-URL: Documentation, https://knowledge.axm-protocols.io/axm-bib/
Author-email: Gabriel Jarry <gabriel@axm-protocols.io>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: axm-ingot>=0.3.0
Requires-Dist: axm-vault
Requires-Dist: axm>=0.7.0
Requires-Dist: bibtexparser<2,>=1.4
Requires-Dist: habanero>=1.2
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: pymupdf4llm>=0.0.17
Requires-Dist: pymupdf>=1.25
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/axm-protocols/axm-knowledge/main/docs/assets/logo.svg" alt="AXM Logo" width="180" />
</p>

<p align="center">
  <strong>axm-bib — Bibliographic tools: search papers, resolve DOIs, download & extract PDFs</strong>
</p>


<p align="center">
  <a href="https://github.com/axm-protocols/axm-knowledge/actions/workflows/ci.yml"><img src="https://github.com/axm-protocols/axm-knowledge/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://forge.axm-protocols.io/audit/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-knowledge/gh-pages/badges/axm-bib/axm-audit.json" alt="axm-audit"></a>
  <a href="https://forge.axm-protocols.io/init/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-knowledge/gh-pages/badges/axm-bib/axm-init.json" alt="axm-init"></a>
  <a href="https://github.com/axm-protocols/axm-knowledge/actions/workflows/axm-quality.yml"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-knowledge/gh-pages/badges/axm-bib/coverage.json" 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+">
  <a href="https://knowledge.axm-protocols.io/axm-bib/"><img src="https://img.shields.io/badge/docs-live-brightgreen" alt="Docs"></a>
</p>

---

`axm-bib` searches academic sources, resolves scholarly identifiers to BibTeX,
and downloads or extracts papers. Its AXMTools share the same Python pipeline.
Network results depend on provider availability; file-producing operations need
an explicit destination when the default paper library is not appropriate.

## Features

- Parallel search across Semantic Scholar, CrossRef, DBLP, OpenReview, arXiv and OpenAlex, with source diagnostics and date filters.
- DOI, arXiv, HAL, DBLP and OpenReview resolution; merge coherent identifiers for one paper or batch several papers.
- Venue enrichment and citation/reference traversal with OpenAlex fallback.
- Open-access PDF download, Markdown extraction and embedded image extraction.
- Topic digests with persistent seen identifiers and a dry-run mode.
- The same tools through the generic `axm` CLI and MCP discovery.

## Installation

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

Python 3.12 or newer is required. These pages describe the checkout; the published
release can lag behind it. For this exact revision, use the workspace installation
under Development. Commands below assume its environment is activated.

Set a contact email before using the network pipeline:

```bash
export AXM_BIB_EMAIL="you@example.org"
```

Replace this address with your own. The current pipeline constructs its Unpaywall
client eagerly, so email is required for search, resolution and graph traversal as
well as PDF downloads. Local PDF extraction does not require it. Tools do not
prompt for missing credentials.

## Quick Start

```bash
axm bib_search --query "attention is all you need" --limit 3
```

Read `papers`, `sources_queried` and `sources_failed`. Results vary with providers.
Choose an identifier from a result, then resolve it:

```bash
axm bib_resolve --ref arXiv:1706.03762
```

The result includes `bibtex`, `key`, `doi` and `entry_type`; this call does not
write a file unless `--output-path` is supplied. A paper title is not an identifier.

## Usage

### Tools

| Tool | Purpose |
|---|---|
| `bib_search` | Find papers with venue, author, year and date-window filters |
| `bib_resolve` | Resolve one identifier or merge identifiers for the same work |
| `bib_resolve_batch` | Resolve a list of identifier groups, reporting per-paper failures |
| `bib_graph` | Return citations, references, or both |
| `bib_pdf` | Download PDF and write extracted content and optional BibTeX |
| `bib_extract` | Extract a local PDF without network access |
| `bib_digest` | Return unseen identifiers for topics, optionally updating state |

```bash
axm bib_extract --pdf ./paper.pdf --output-dir ./extracted
axm bib_digest --topics "diffusion models" --since 7d --dry-run
axm bib_graph --ref arXiv:1706.03762 --direction both --limit 10
```

Extraction writes `<pdf-stem>.md` and `figures/`; reruns overwrite matching files.
`bib_pdf` normally writes under `~/axm/papers/{key}/`. Its `--output-path` changes
only the PDF destination: BibTeX and extracted content remain in the paper library.
See the [PDF guide](docs/howto/pdf.md) before choosing destinations.

### Python

```python
from axm_bib.pipeline import BibPipeline

pipeline = BibPipeline(mailto="you@example.org")
result = pipeline.search("attention is all you need", limit=3)
for paper in result.papers:
    print(paper.title, paper.doi or paper.arxiv_id)
```

The root `axm_bib` namespace exports exception types and `__version__`.
Pipeline, models and clients use module-qualified imports. MCP discovery requires
`axm-bib` to be installed in the server's environment; see the
[MCP guide](docs/howto/mcp.md).

## Documentation

- [Published documentation](https://knowledge.axm-protocols.io/axm-bib/)
- [Getting started](docs/tutorials/getting-started.md)
- [Task guides](docs/howto/index.md)
- [Tool reference](docs/reference/cli.md) and [Python API](docs/reference/api.md)
- [Architecture](docs/explanation/architecture.md)

## Development

```bash
git clone https://github.com/axm-protocols/axm-knowledge.git
cd axm-knowledge
uv sync --all-groups
source .venv/bin/activate
make test-bib
cd packages/axm-bib
mkdocs build --strict
```

Workspace dependencies may require the sibling checkouts declared in the root
`pyproject.toml`. The standalone build uses this package's `mkdocs.yml` and docs
dependencies. It does not validate the workspace's combined navigation.

## License

Licensed under Apache-2.0. See [LICENSE](LICENSE).
