pynakes 0.5.1

Agent-friendly, round-trip-faithful BibTeX/BibLaTeX maintenance toolkit

pynakes

[!WARNING] pynakes is alpha-quality software. Interfaces and behavior may change between releases.

pynakes is a deterministic bibliography maintenance engine built for reliable agentic workflows, CI, and human use. Agents decide what should change; pynakes inspects, validates, previews, and applies those changes safely and reproducibly.

The Python CLI makes small, explicit, reviewable changes to .bib files — minimal diffs, dry-run previews, and atomic writes — and reports every change as structured JSON.

Requires Python 3.11+ and is packaged as an OS-independent CLI and library.

Untouched entries write back byte-for-byte — no hidden reformatting, reordering, or re-quoting. The file stays diff-friendly in git and yours for decades.

Named after the Pinakes, Callimachus's catalog of the Library of Alexandria — antiquity's first bibliography. A .bib file is the index card; a pinax is the card together with the shelf it points at.

Why pynakes

• Reviewable by design. Modifying commands support --dry-run --diff for review before writing. Writes are atomic and re-parse-validated; --backup optionally retains the previous file. Ambiguous cases — conflicting merges, duplicate DOIs — are reported with exit code 2 rather than guessed.
• Round-trip fidelity. An entry you don't touch is written back byte-for-byte. pynakes never normalizes whitespace, reorders fields, or re-quotes values behind your back — so diffs stay tiny and reviewable.
• A deterministic execution layer for agents and CI. Stable JSON output and exit codes, machine-readable capabilities, structured change plans, and --strict / pre-commit gates let an agent exercise judgment without directly rewriting bibliography text.
• Deterministic and offline by default. No hidden time, randomness, or ordering; network access is explicit (ref import, asset fetch, or --online) and confined to the few commands that need it.
• Preservation-first interoperability. Untouched BibTeX/BibLaTeX source and JabRef metadata round-trip unchanged. pynakes-meta holds native settings; JabRef metadata can be preserved, adopted, and projected explicitly.

Two workflows

1. Bibliography engine

Load any .bib file the BibTeX/BibLaTeX toolchain produces, then:

• Inspect — entry count, encoding, duplicates, JabRef metadata
• Lint — validate required fields, DOI shape, key conflicts (CI-gate multiple files)
• Normalize — authors, DOIs, months, journals, saveActions pipeline
• Format — deterministic layout-only rewrites with explicit layout flags
• Import by DOI or arXiv identifier, with configurable key generation, or add a manual entry
• Dedupe & merge — detect and resolve duplicates, with conflict reporting
• Bulk-edit fields — set, rename, move, append, clear, or protect fields on matching references
• Manage groups and keys — list, rename, repair, generate from patterns
• Convert between BibTeX/BibLaTeX dialects; import/export CSL-JSON, RIS, MODS, and EndNote; export CSV
• Track citation usage — find cited, unused, and missing keys in .tex or .aux sources
• Remove entries with a single command

All through the standardized lifecycle: load → stage → preview/diff → commit. JabRef v5.15 interoperability covers metadata preservation and classification, offline-compatible saveActions, all four group types, save-order configuration, and common key-pattern markers and modifiers. Unsupported formatter names are reported rather than silently applied. Every modifying command supports --dry-run --diff and atomic writes; backups are opt-in.

2. Pinax — the corpus layer

Opt in by setting a files-dir in the library metadata. Now every citation key can carry materials:

• arXiv download — PDFs and source bundles, automatically fetched, verified, and extracted with provenance tracking (source hash, download timestamp)
• Open-access published PDFs — resolved from DOI via OpenAlex, CrossRef, and publisher-specific URL overrides; .published.pdf lands only for genuinely OA papers, never misidentified repository mirrors
• asset fetch — download configured materials for all entries or one key
• asset check — validate presence, detect orphans, verify checksums, optionally fix (--fix)
• ref remove — removes both the entry and its materials by default
• Coordinated key edits — renaming a key moves its materials
• corpus combine/corpus split — materials follow their entries

The .bib stays the source of truth; Pinax just keeps the shelf tidy.

Installation

pip install pynakes

For development (with test/lint tools):

git clone https://github.com/maiani/pynakes.git
cd pynakes
pip install -e ".[dev]"
pre-commit install  # enable ruff hooks on commit

See the Installation guide for shell completion and troubleshooting.

Quick start

# Create a new library, then inspect and check for issues
pynakes init mylib.bib
pynakes inspect mylib.bib
pynakes lint mylib.bib --json

# Import a reference by DOI or arXiv id, or add one manually
pynakes ref import 10.5555/example mylib.bib
pynakes ref import arXiv:2301.00001 mylib.bib
pynakes ref add Manual2026 mylib.bib --field title="Manual Reference" --field year=2026
pynakes ref add  # interactive
pynakes ref show Manual2026 mylib.bib
pynakes ref edit Manual2026 mylib.bib --field year=2027 --clear-field note
pynakes ref edit Manual2026 mylib.bib  # interactive

# Preview the normalization pass before committing
pynakes normalize mylib.bib --dry-run --diff

# Remove entries by citation key (with pinax material cleanup)
pynakes ref remove mylib.bib DeprecatedKey2020

# Rename a citation key across the .bib file and .tex sources
pynakes keys rename mylib.bib OldKey2020 NewKey2020 paper.tex chapters/

# Fetch configured materials for one entry (Pinax mode)
pynakes asset fetch arXivKey2024 mylib.bib

# Search entries
pynakes search mylib.bib "neural network" --json

# Gate a build: fail if any .bib has errors
pynakes lint mylib.bib chapters/*.bib --strict

# Shell completion for cite keys (bash/zsh/fish)
eval "$(pynakes --show-completion bash)"

When the current directory contains exactly one .bib file, its path may be omitted from commands that operate on a single library (for example, pynakes normalize --dry-run).

Commands still require an explicit path when there are multiple .bib files.

See the Quick Start guide and Usage guide for the full command surface.

Safety model

Every modifying command:

• Validates before writing (parse errors, conflicts, missing required fields)
• Supports --dry-run and --diff to preview changes
• Writes atomically and optionally creates a .bak backup
• Reports conflicts and exits 2 rather than guessing (e.g. duplicate DOI on import)
• Emits structured JSON (--json) for programmatic use

For scripted and LLM-assisted workflows

In an agentic workflow, the agent supplies judgment and pynakes supplies the deterministic execution layer. The same interface is safe for ordinary scripts and CI:

• --json returns machine-readable results with status, warnings, and errors
• pynakes capabilities --json describes supported operations for an agent
• Exit codes: 0 success, 1 error, 2 conflict (safe to retry with user input)

See the LLM Integration guide for the full JSON envelope and recommended workflows.

Status

v0.5.0 is the first public alpha. It includes the preservation-first parser/writer, the documented maintenance command surface, broad JabRef v5.15 interoperability, machine-readable command discovery, and the optional Pinax corpus layer with arXiv and published-PDF material workflows. CI tests Python 3.11–3.13 and enforces a 90% coverage floor.

Until v1.0, pynakes does not guarantee backward compatibility for the Python API, CLI syntax, or JSON envelopes. The project aims to keep automation workflows predictable and documents breaking changes in the changelog, but production users should pin exact 0.x versions.

Parser conformance is verified against the TeX Live 2026 toolchain (BibTeX 0.99d, BibLaTeX 3.21, Biber 2.21). The project roadmap is documented in DEVPLAN.md.

Documentation

• Quick Start
• Usage Guide
• Installation
• LLM Integration
• Git Workflows: pre-commit & CI
• Architecture
• Pinax — the corpus layer
• API Reference

License

MIT — see LICENSE.

Contributing

Contributions are welcome — see CONTRIBUTING.md.