pynakes 0.5.1__tar.gz

pynakes-0.5.1/.pre-commit-hooks.yaml

@@ -0,0 +1,49 @@
+# pynakes pre-commit hooks.
+#
+# Add to a repository's .pre-commit-config.yaml:
+#
+#   repos:
+#     - repo: https://github.com/maiani/pynakes
+#       rev: v0.5.0
+#       hooks:
+#         - id: pynakes-lint
+#         - id: pynakes-keys-check
+#         - id: pynakes-files-check   # opt-in: validates linked-file paths
+#         - id: pynakes-dedupe-check  # opt-in: flags duplicate works
+#
+# Every hook is read-only, offline, and deterministic. pre-commit passes the
+# staged .bib files as arguments; --strict makes a finding fail the commit.
+
+- id: pynakes-lint
+  name: pynakes lint
+  description: Validate BibTeX entries and fail on errors (duplicate/empty keys, missing required fields).
+  entry: pynakes lint --strict
+  language: python
+  files: \.bib$
+  types: [file]
+
+- id: pynakes-keys-check
+  name: pynakes keys check
+  description: Fail if any citation key is duplicated.
+  entry: pynakes keys check --strict
+  language: python
+  files: \.bib$
+  types: [file]
+
+- id: pynakes-files-check
+  name: pynakes files check
+  description: Fail if any JabRef linked file is missing or the wrong type.
+  entry: pynakes files check --strict
+  language: python
+  files: \.bib$
+  types: [file]
+  stages: [manual]
+
+- id: pynakes-dedupe-check
+  name: pynakes dedupe check
+  description: Fail if duplicate works (same DOI/arXiv/title) are present.
+  entry: pynakes dedupe check --strict
+  language: python
+  files: \.bib$
+  types: [file]
+  stages: [manual]

pynakes-0.5.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrea Maiani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pynakes-0.5.1/MANIFEST.in

@@ -0,0 +1,4 @@
+# Ship the complete test environment with the source distribution so downstream
+# packagers can validate the archive without checking out the repository.
+include .pre-commit-hooks.yaml
+recursive-include tests *.py *.bib *.json *.tex *.aux

pynakes-0.5.1/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: pynakes
+Version: 0.5.1
+Summary: Agent-friendly, round-trip-faithful BibTeX/BibLaTeX maintenance toolkit
+Author-email: Andrea Maiani <dev@andreamaiani.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/maiani/pynakes
+Project-URL: Repository, https://github.com/maiani/pynakes
+Project-URL: Issues, https://github.com/maiani/pynakes/issues
+Project-URL: Changelog, https://github.com/maiani/pynakes/blob/main/CHANGELOG.md
+Keywords: bibtex,biblatex,bibliography,citations,references,jabref,latex,doi,reference-management,cli,agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Text Processing :: Markup :: LaTeX
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.7.0
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.6.0; extra == "dev"
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: hypothesis>=6.100.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
+Dynamic: license-file
+
+# pynakes
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/maiani/pynakes/main/docs/assets/logo.svg" alt="pynakes logo" width="128">
+</p>
+
+[![PyPI](https://img.shields.io/pypi/v/pynakes.svg)](https://pypi.org/project/pynakes/)
+[![Python](https://img.shields.io/pypi/pyversions/pynakes.svg)](https://pypi.org/project/pynakes/)
+[![CI](https://img.shields.io/github/actions/workflow/status/maiani/pynakes/ci.yml?branch=main)](https://github.com/maiani/pynakes/actions)
+[![License](https://img.shields.io/github/license/maiani/pynakes)](https://github.com/maiani/pynakes/blob/main/LICENSE)
+
+> [!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
+
+```bash
+pip install pynakes
+```
+
+For development (with test/lint tools):
+
+```bash
+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](docs/guides/installation.md) for shell completion and troubleshooting.
+
+## Quick start
+
+```bash
+# 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](docs/guides/quickstart.md) and [Usage guide](docs/guides/usage.md) 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](docs/guides/llm-integration.md) 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](DEVPLAN.md).
+
+## Documentation
+
+- [Quick Start](docs/guides/quickstart.md)
+- [Usage Guide](docs/guides/usage.md)
+- [Installation](docs/guides/installation.md)
+- [LLM Integration](docs/guides/llm-integration.md)
+- [Git Workflows: pre-commit & CI](docs/guides/git-workflows.md)
+- [Architecture](docs/guides/architecture.md)
+- [Pinax — the corpus layer](docs/guides/pinax.md)
+- [API Reference](docs/api/reference.md)
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

pynakes-0.5.1/README.md

@@ -0,0 +1,197 @@
+# pynakes
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/maiani/pynakes/main/docs/assets/logo.svg" alt="pynakes logo" width="128">
+</p>
+
+[![PyPI](https://img.shields.io/pypi/v/pynakes.svg)](https://pypi.org/project/pynakes/)
+[![Python](https://img.shields.io/pypi/pyversions/pynakes.svg)](https://pypi.org/project/pynakes/)
+[![CI](https://img.shields.io/github/actions/workflow/status/maiani/pynakes/ci.yml?branch=main)](https://github.com/maiani/pynakes/actions)
+[![License](https://img.shields.io/github/license/maiani/pynakes)](https://github.com/maiani/pynakes/blob/main/LICENSE)
+
+> [!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
+
+```bash
+pip install pynakes
+```
+
+For development (with test/lint tools):
+
+```bash
+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](docs/guides/installation.md) for shell completion and troubleshooting.
+
+## Quick start
+
+```bash
+# 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](docs/guides/quickstart.md) and [Usage guide](docs/guides/usage.md) 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](docs/guides/llm-integration.md) 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](DEVPLAN.md).
+
+## Documentation
+
+- [Quick Start](docs/guides/quickstart.md)
+- [Usage Guide](docs/guides/usage.md)
+- [Installation](docs/guides/installation.md)
+- [LLM Integration](docs/guides/llm-integration.md)
+- [Git Workflows: pre-commit & CI](docs/guides/git-workflows.md)
+- [Architecture](docs/guides/architecture.md)
+- [Pinax — the corpus layer](docs/guides/pinax.md)
+- [API Reference](docs/api/reference.md)
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

pynakes-0.5.1/pyproject.toml

@@ -0,0 +1,98 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pynakes"
+version = "0.5.1"
+description = "Agent-friendly, round-trip-faithful BibTeX/BibLaTeX maintenance toolkit"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [
+    {name = "Andrea Maiani", email = "dev@andreamaiani.com"}
+]
+keywords = [
+    "bibtex",
+    "biblatex",
+    "bibliography",
+    "citations",
+    "references",
+    "jabref",
+    "latex",
+    "doi",
+    "reference-management",
+    "cli",
+    "agent",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Text Processing :: Markup :: LaTeX",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "click>=8.1.0",
+    "httpx>=0.27.0",
+    "typer>=0.12.0",
+    "rich>=13.7.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pre-commit>=3.6.0",
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "hypothesis>=6.100.0",
+    "ruff>=0.1.0",
+    "build>=1.2.0",
+    "twine>=5.0.0",
+]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.26",
+]
+
+[project.urls]
+Homepage = "https://github.com/maiani/pynakes"
+Repository = "https://github.com/maiani/pynakes"
+Issues = "https://github.com/maiani/pynakes/issues"
+Changelog = "https://github.com/maiani/pynakes/blob/main/CHANGELOG.md"
+
+[project.scripts]
+pynakes = "pynakes.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pynakes = ["py.typed", "providers/pdf_overrides.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+markers = [
+    "agent_eval: opt-in real-agent beta-test harness",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = ["E501"]
+
+[tool.coverage.run]
+source = ["src/pynakes"]

pynakes-0.5.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pynakes-0.5.1/src/pynakes/__init__.py

@@ -0,0 +1,8 @@
+"""pynakes: Agent-friendly BibTeX library management."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("pynakes")
+except PackageNotFoundError:  # running from a source tree that isn't installed
+    __version__ = "0.0.0+unknown"

pynakes-0.5.1/src/pynakes/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running pynakes as a module."""
+
+from pynakes.cli import app
+
+if __name__ == "__main__":
+    app()