antifile 0.1.0__tar.gz

antifile-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/

antifile-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: antifile
+Version: 0.1.0
+Summary: Extract BibTeX metadata from PDFs, EPUBs, URLs, and identifiers
+Project-URL: Homepage, https://github.com/vxvware/antifile
+Project-URL: Repository, https://github.com/vxvware/antifile
+Project-URL: Issues, https://github.com/vxvware/antifile/issues
+Author-email: VxVware <trevor.j.vincent@gmail.com>
+License-Expression: MIT
+Keywords: arxiv,bibliography,bibtex,citations,doi,epub,isbn,metadata,pdf
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Science/Research
+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 :: Text Processing :: Markup :: LaTeX
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: bibtexparser>=2.0.0b7
+Requires-Dist: httpx>=0.27
+Requires-Dist: pymupdf>=1.24
+Requires-Dist: rapidfuzz>=3.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# antifile
+
+Extract BibTeX metadata from PDFs, EPUBs, URLs, and identifiers (DOI, arXiv, ISBN)
+and append it to a `.bib` file.
+
+## Install
+
+```bash
+pip install antifile
+# or
+uv tool install antifile
+```
+
+## Usage
+
+```bash
+antifile INPUT -o refs.bib
+```
+
+`INPUT` can be:
+
+- a **PDF** or **EPUB** file — `antifile paper.pdf -o refs.bib`
+- a **folder** of PDFs/EPUBs — `antifile ~/Downloads/papers -o refs.bib` (add `--recursive` to descend into subfolders)
+- a **URL** — `antifile https://example.com/article -o refs.bib`
+- a **DOI** — `antifile 10.1145/3292500 -o refs.bib`
+- an **arXiv ID** — `antifile arXiv:1706.03762 -o refs.bib`
+- an **ISBN** — `antifile 9780262033848 -o refs.bib`
+
+Entries are appended with de-duplication: a new entry matching an existing one
+(by DOI, arXiv ID, ISBN, or normalized title+author) fills in any missing fields
+rather than creating a duplicate. Pass `--no-merge` to skip on duplicate, or
+`--force` to append anyway with an auto-suffixed key.
+
+### Options
+
+| flag | effect |
+|------|--------|
+| `-o, --output FILE` | target `.bib` (required; created if missing) |
+| `--method {auto,doi,arxiv,isbn,crossref,llm,claude-code}` | force a PDF extraction method (default: `auto`) |
+| `--recursive` | recurse into subfolders for folder input |
+| `--no-preview` | skip the first-page PDF preview |
+| `--no-merge` | on duplicate, skip instead of filling missing fields |
+| `--force` | append even if a duplicate exists |
+
+### LLM-assisted extraction
+
+When a PDF has no resolvable identifier, antifile can fall back to an LLM to read
+the first page. Set whichever API key you have — it's picked up from the
+environment:
+
+```bash
+export ANTHROPIC_API_KEY=...   # or OPENAI_API_KEY, or GEMINI_API_KEY / GOOGLE_API_KEY
+```
+
+## Related
+
+- [antilibrary](https://github.com/vxvware/antilibrary) — manage BibTeX libraries from the terminal (can call antifile via `--add-from-files`).
+- [antifind](https://github.com/vxvware/antifind) — online metadata search → BibTeX.
+
+## License
+
+MIT

antifile-0.1.0/README.md

@@ -0,0 +1,62 @@
+# antifile
+
+Extract BibTeX metadata from PDFs, EPUBs, URLs, and identifiers (DOI, arXiv, ISBN)
+and append it to a `.bib` file.
+
+## Install
+
+```bash
+pip install antifile
+# or
+uv tool install antifile
+```
+
+## Usage
+
+```bash
+antifile INPUT -o refs.bib
+```
+
+`INPUT` can be:
+
+- a **PDF** or **EPUB** file — `antifile paper.pdf -o refs.bib`
+- a **folder** of PDFs/EPUBs — `antifile ~/Downloads/papers -o refs.bib` (add `--recursive` to descend into subfolders)
+- a **URL** — `antifile https://example.com/article -o refs.bib`
+- a **DOI** — `antifile 10.1145/3292500 -o refs.bib`
+- an **arXiv ID** — `antifile arXiv:1706.03762 -o refs.bib`
+- an **ISBN** — `antifile 9780262033848 -o refs.bib`
+
+Entries are appended with de-duplication: a new entry matching an existing one
+(by DOI, arXiv ID, ISBN, or normalized title+author) fills in any missing fields
+rather than creating a duplicate. Pass `--no-merge` to skip on duplicate, or
+`--force` to append anyway with an auto-suffixed key.
+
+### Options
+
+| flag | effect |
+|------|--------|
+| `-o, --output FILE` | target `.bib` (required; created if missing) |
+| `--method {auto,doi,arxiv,isbn,crossref,llm,claude-code}` | force a PDF extraction method (default: `auto`) |
+| `--recursive` | recurse into subfolders for folder input |
+| `--no-preview` | skip the first-page PDF preview |
+| `--no-merge` | on duplicate, skip instead of filling missing fields |
+| `--force` | append even if a duplicate exists |
+
+### LLM-assisted extraction
+
+When a PDF has no resolvable identifier, antifile can fall back to an LLM to read
+the first page. Set whichever API key you have — it's picked up from the
+environment:
+
+```bash
+export ANTHROPIC_API_KEY=...   # or OPENAI_API_KEY, or GEMINI_API_KEY / GOOGLE_API_KEY
+```
+
+## Related
+
+- [antilibrary](https://github.com/vxvware/antilibrary) — manage BibTeX libraries from the terminal (can call antifile via `--add-from-files`).
+- [antifind](https://github.com/vxvware/antifind) — online metadata search → BibTeX.
+
+## License
+
+MIT

antifile-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "antifile"
+version = "0.1.0"
+description = "Extract BibTeX metadata from PDFs, EPUBs, URLs, and identifiers"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "VxVware", email = "trevor.j.vincent@gmail.com" },
+]
+keywords = ["bibtex", "bibliography", "citations", "pdf", "epub", "doi", "arxiv", "isbn", "metadata"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Text Processing :: Markup :: LaTeX",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "bibtexparser>=2.0.0b7",
+    "rapidfuzz>=3.0",
+    "rich>=13.0",
+    "httpx>=0.27",
+    "pymupdf>=1.24",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/vxvware/antifile"
+Repository = "https://github.com/vxvware/antifile"
+Issues = "https://github.com/vxvware/antifile/issues"
+
+[project.scripts]
+antifile = "antifile.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/antifile"]
+
+[tool.ruff]
+line-length = 100

antifile-0.1.0/src/antifile/__init__.py

@@ -0,0 +1,25 @@
+"""antifile — extract BibTeX metadata from PDFs, URLs, and identifiers."""
+
+from antifile.entry import Entry
+from antifile._base import (
+    ExtractionResult,
+    Identifiers,
+    ExtractorError,
+    ExtractorUnavailableError,
+    NetworkError,
+    PDFError,
+)
+from antifile.dispatch import extract
+from antifile import bibfile
+
+__all__ = [
+    "extract",
+    "bibfile",
+    "Entry",
+    "ExtractionResult",
+    "Identifiers",
+    "ExtractorError",
+    "ExtractorUnavailableError",
+    "NetworkError",
+    "PDFError",
+]

antifile-0.1.0/src/antifile/_base.py

@@ -0,0 +1,49 @@
+"""Base types for the extractor system."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from antifile.entry import Entry
+
+
+class ExtractorError(Exception):
+    """Base exception for extractors."""
+
+
+class ExtractorUnavailableError(ExtractorError):
+    """Raised when a required dependency is missing."""
+
+
+class NetworkError(ExtractorError):
+    """Raised on API/network failures."""
+
+
+class PDFError(ExtractorError):
+    """Raised on PDF read failures."""
+
+
+@dataclass
+class Identifiers:
+    """Identifiers extracted from document text."""
+
+    dois: list[str] = field(default_factory=list)
+    arxiv_ids: list[str] = field(default_factory=list)
+    isbns: list[str] = field(default_factory=list)
+
+    @property
+    def has_any(self) -> bool:
+        return bool(self.dois or self.arxiv_ids or self.isbns)
+
+
+@dataclass
+class ExtractionResult:
+    """Result from an extraction attempt."""
+
+    entry: Entry | None
+    source: str
+    confidence: float
+    identifiers: Identifiers = field(default_factory=Identifiers)
+    errors: list[str] = field(default_factory=list)
+    pdf_path: Path | None = None

antifile-0.1.0/src/antifile/bibfile.py

@@ -0,0 +1,137 @@
+"""Read, dedup, and append BibTeX entries to a .bib file."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import bibtexparser
+
+from antifile.entry import Entry
+
+
+def _btp_to_entry(e, source: Path | None = None) -> Entry:
+    fields = {f.key: f.value for f in e.fields}
+    return Entry(key=e.key, entry_type=e.entry_type, fields=fields, source_file=source)
+
+
+def load(path: Path) -> list[Entry]:
+    """Load all entries from a .bib file. Returns [] if missing/empty."""
+    if not path.exists():
+        return []
+    text = path.read_text()
+    if not text.strip():
+        return []
+    lib = bibtexparser.parse_string(text)
+    return [_btp_to_entry(e, path) for e in lib.entries]
+
+
+def _norm(s: str) -> str:
+    return s.strip().lower()
+
+
+def find_duplicate(entry: Entry, existing: list[Entry]) -> Entry | None:
+    """Return an existing entry that matches by identifier or title+author."""
+    new_doi = _norm(entry.fields.get("doi", ""))
+    new_arxiv = _norm(entry.fields.get("eprint", ""))
+    new_isbn = _norm(entry.fields.get("isbn", ""))
+    new_title = _norm(entry.fields.get("title", ""))
+    new_author = _norm(entry.fields.get("author", ""))
+
+    for e in existing:
+        if e.key == entry.key:
+            return e
+        if new_doi and _norm(e.fields.get("doi", "")) == new_doi:
+            return e
+        if new_arxiv and _norm(e.fields.get("eprint", "")) == new_arxiv:
+            return e
+        if new_isbn and _norm(e.fields.get("isbn", "")) == new_isbn:
+            return e
+        if (
+            new_title
+            and _norm(e.fields.get("title", "")) == new_title
+            and new_author
+            and _norm(e.fields.get("author", "")) == new_author
+        ):
+            return e
+    return None
+
+
+def make_unique_key(base: str, existing: list[Entry]) -> str:
+    """Suffix a, b, c... if `base` collides with any key in existing."""
+    keys = {e.key for e in existing}
+    if base not in keys:
+        return base
+    for suffix in "abcdefghijklmnopqrstuvwxyz":
+        candidate = f"{base}{suffix}"
+        if candidate not in keys:
+            return candidate
+    n = 1
+    while f"{base}{n}" in keys:
+        n += 1
+    return f"{base}{n}"
+
+
+def _append_entry(path: Path, entry: Entry) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    text = path.read_text() if path.exists() else ""
+    separator = "\n\n" if text.strip() else ""
+    with open(path, "a") as f:
+        f.write(separator + entry.to_bibtex() + "\n")
+    entry.source_file = path
+
+
+def _rewrite(path: Path, entries: list[Entry]) -> None:
+    content = "\n\n".join(e.to_bibtex() for e in entries)
+    path.write_text(content + "\n" if content else "")
+
+
+def merge_missing(target: Entry, source: Entry) -> bool:
+    """Fill empty/absent fields on `target` from `source`. Returns True if changed."""
+    changed = False
+    for k, v in source.fields.items():
+        if not v:
+            continue
+        if not target.fields.get(k, "").strip():
+            target.fields[k] = v
+            changed = True
+    return changed
+
+
+class AppendResult:
+    __slots__ = ("status", "entry", "duplicate_of")
+
+    def __init__(self, status: str, entry: Entry, duplicate_of: Entry | None = None):
+        self.status = status  # "added" | "skipped" | "merged"
+        self.entry = entry
+        self.duplicate_of = duplicate_of
+
+
+def append(
+    path: Path,
+    entry: Entry,
+    *,
+    merge: bool = True,
+    force: bool = False,
+) -> AppendResult:
+    """Append `entry` to the .bib at `path` with dedup.
+
+    - If a duplicate exists and `force` is False:
+        - If `merge` is True (default), fill missing/empty fields on the existing entry
+          and rewrite the file. Returns status="merged" if anything changed,
+          otherwise "skipped".
+        - If `merge` is False, returns status="skipped".
+    - Otherwise auto-suffixes the key on collision and appends.
+    """
+    existing = load(path)
+    dup = find_duplicate(entry, existing) if not force else None
+
+    if dup is not None:
+        if merge:
+            if merge_missing(dup, entry):
+                _rewrite(path, existing)
+                return AppendResult("merged", dup, duplicate_of=dup)
+        return AppendResult("skipped", dup, duplicate_of=dup)
+
+    entry.key = make_unique_key(entry.key, existing)
+    _append_entry(path, entry)
+    return AppendResult("added", entry)

antifile-0.1.0/src/antifile/cli.py

@@ -0,0 +1,256 @@
+"""antifile CLI — extract BibTeX from PDFs / URLs / identifiers and append to a .bib file."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from rich.console import Console
+from rich.syntax import Syntax
+
+from antifile import bibfile
+from antifile._base import ExtractionResult, ExtractorUnavailableError, NetworkError
+from antifile.dispatch import extract as dispatch_extract
+from antifile.pdf import (
+    extract_from_pdf,
+    extract_text,
+    extract_probable_title,
+    extract_via_claude_code,
+    extract_via_llm,
+    find_identifiers,
+    resolve_arxiv,
+    resolve_doi,
+    resolve_isbn,
+    search_crossref_by_title,
+)
+from antifile.preview import show_pdf_first_page
+
+console = Console()
+_METHODS = ("auto", "doi", "arxiv", "isbn", "crossref", "llm", "claude-code")
+
+
+def _api_keys_from_env() -> dict[str, str]:
+    keys: dict[str, str] = {}
+    if v := os.environ.get("ANTHROPIC_API_KEY"):
+        keys["anthropic"] = v
+    if v := os.environ.get("OPENAI_API_KEY"):
+        keys["openai"] = v
+    if v := os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY"):
+        keys["gemini"] = v
+    return keys
+
+
+def _extract_pdf_with_method(
+    pdf_path: Path, method: str, api_keys: dict[str, str]
+) -> ExtractionResult:
+    """Run a specific extraction method against a PDF."""
+    if method == "auto":
+        return extract_from_pdf(pdf_path, api_keys=api_keys)
+
+    from antifile._base import Identifiers
+
+    text = extract_text(pdf_path, max_pages=3)
+    identifiers = find_identifiers(text) if text.strip() else Identifiers()
+    entry = None
+
+    if method == "doi":
+        for doi in identifiers.dois[:3]:
+            entry = resolve_doi(doi)
+            if entry:
+                break
+    elif method == "arxiv":
+        for aid in identifiers.arxiv_ids[:3]:
+            entry = resolve_arxiv(aid)
+            if entry:
+                break
+    elif method == "isbn":
+        for isbn in identifiers.isbns[:3]:
+            entry = resolve_isbn(isbn)
+            if entry:
+                break
+    elif method == "crossref":
+        title = extract_probable_title(text)
+        if title:
+            entry = search_crossref_by_title(title)
+    elif method == "llm":
+        entry = extract_via_llm(text, api_keys)
+    elif method == "claude-code":
+        entry = extract_via_claude_code(text)
+
+    if entry:
+        entry.fields["file"] = str(pdf_path)
+
+    confidence = 0.7 if method in ("llm", "claude-code", "crossref") else 0.95
+    return ExtractionResult(
+        entry=entry, source=method,
+        confidence=confidence if entry else 0.0,
+        identifiers=identifiers, pdf_path=pdf_path,
+    )
+
+
+def _extract_one(
+    input_str: str, method: str, api_keys: dict[str, str]
+) -> ExtractionResult:
+    """Dispatch helper that honors --method for PDFs."""
+    path = Path(input_str).expanduser()
+    if method != "auto" and path.exists() and path.is_file() and path.suffix.lower() == ".pdf":
+        return _extract_pdf_with_method(path, method, api_keys)
+    return dispatch_extract(input_str, api_keys=api_keys)
+
+
+def _looks_like_path(s: str) -> bool:
+    return s.startswith(("/", "~", "./", "../")) or "/" in s
+
+
+def _process(
+    input_str: str,
+    output: Path,
+    method: str,
+    api_keys: dict[str, str],
+    show_preview: bool,
+    merge: bool,
+    force: bool,
+    counters: dict[str, int],
+    label: str | None = None,
+) -> None:
+    display = label or input_str
+    console.print(f"[cyan]→[/] {display}")
+
+    path = Path(input_str).expanduser()
+
+    # Detect path-like inputs that don't exist before trying to classify them
+    # as URLs/identifiers — saves a confusing "Could not classify" message.
+    if _looks_like_path(input_str) and not path.exists():
+        console.print(f"  [yellow]skipped:[/] path not found ({path})")
+        counters["skipped"] += 1
+        return
+
+    is_pdf = path.exists() and path.is_file() and path.suffix.lower() == ".pdf"
+
+    if show_preview and is_pdf:
+        show_pdf_first_page(path)
+
+    try:
+        result = _extract_one(input_str, method, api_keys)
+    except (ExtractorUnavailableError, NetworkError) as e:
+        console.print(f"  [red]error:[/] {e}")
+        counters["failed"] += 1
+        return
+    except Exception as e:
+        console.print(f"  [red]error:[/] {e}")
+        counters["failed"] += 1
+        return
+
+    for err in result.errors:
+        console.print(f"  [yellow]warning:[/] {err}")
+
+    if result.entry is None:
+        if result.source == "unknown":
+            console.print(f"  [yellow]skipped:[/] unrecognized input")
+            counters["skipped"] += 1
+        else:
+            console.print(f"  [red]no entry extracted[/] (source={result.source})")
+            counters["failed"] += 1
+        return
+
+    conf_color = "green" if result.confidence >= 0.9 else "yellow"
+    console.print(
+        f"  [dim]source:[/] {result.source}  "
+        f"[{conf_color}]confidence: {result.confidence:.0%}[/]"
+    )
+    console.print(
+        Syntax(result.entry.to_bibtex(), "bibtex", theme="monokai", line_numbers=False, padding=(0, 1))
+    )
+
+    res = bibfile.append(output, result.entry, merge=merge, force=force)
+    if res.status == "added":
+        console.print(f"  [green]added[/] [bold]{res.entry.key}[/] → {output}")
+        counters["added"] += 1
+    elif res.status == "merged":
+        console.print(f"  [green]merged[/] missing fields into [bold]{res.entry.key}[/]")
+        counters["merged"] += 1
+    else:
+        # silent skip per spec, but keep it visible at INFO level
+        counters["duplicates"] += 1
+
+
+_SUPPORTED_SUFFIXES = (".pdf", ".epub")
+
+
+def _iter_supported(folder: Path, recursive: bool) -> list[Path]:
+    pattern = "**/*" if recursive else "*"
+    return sorted(
+        p for p in folder.glob(pattern)
+        if p.is_file() and p.suffix.lower() in _SUPPORTED_SUFFIXES
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="antifile",
+        description="Extract BibTeX from PDFs, EPUBs, URLs, DOIs, arXiv IDs, or ISBNs into a .bib file.",
+    )
+    parser.add_argument("input", help="PDF/EPUB path, folder, URL, DOI, arXiv ID, or ISBN")
+    parser.add_argument(
+        "-o", "--output", required=True, type=Path,
+        help="Target .bib file (created if missing; entries appended with dedup)",
+    )
+    parser.add_argument(
+        "--method", choices=_METHODS, default="auto",
+        help="Force a specific extraction method (PDF only). Default: auto.",
+    )
+    parser.add_argument("--recursive", action="store_true", help="Recurse into subfolders for folder input")
+    parser.add_argument("--no-preview", action="store_true", help="Skip first-page PDF preview")
+    parser.add_argument("--no-merge", action="store_true",
+                        help="On duplicate, skip without filling missing fields (default: fill missing)")
+    parser.add_argument("--force", action="store_true",
+                        help="Append even if a duplicate exists (auto-suffixes the key)")
+
+    args = parser.parse_args(argv)
+
+    api_keys = _api_keys_from_env()
+    show_preview = not args.no_preview
+    merge = not args.no_merge
+
+    counters = {"added": 0, "merged": 0, "duplicates": 0, "failed": 0, "skipped": 0}
+
+    input_str: str = args.input
+    path = Path(input_str).expanduser()
+
+    if path.exists() and path.is_dir():
+        files = _iter_supported(path, args.recursive)
+        if not files:
+            console.print(f"[dim]No PDF/EPUB files found in {path}[/]")
+            return 0
+        console.print(f"[cyan]Found {len(files)} file(s) in {path}[/]")
+        for i, f in enumerate(files, 1):
+            try:
+                _process(
+                    str(f), args.output, args.method, api_keys,
+                    show_preview, merge, args.force, counters,
+                    label=f"[{i}/{len(files)}] {f.name}",
+                )
+            except KeyboardInterrupt:
+                console.print("\n[dim]stopped[/]")
+                break
+    else:
+        _process(
+            input_str, args.output, args.method, api_keys,
+            show_preview, merge, args.force, counters,
+        )
+
+    console.print()
+    console.print(
+        f"[green]added: {counters['added']}[/]  "
+        f"[green]merged: {counters['merged']}[/]  "
+        f"[dim]duplicates: {counters['duplicates']}[/]  "
+        f"[yellow]skipped: {counters['skipped']}[/]  "
+        f"[red]failed: {counters['failed']}[/]"
+    )
+    return 0 if counters["failed"] == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())