/journal-abbrev

Journal Abbreviation Lookup

Look up journal/magazine name abbreviations using a multi-source cascade: JabRef database (~25K journals) → AbbrevISO API (ISO 4) → NLM Catalog (MEDLINE).

Critical rule: Always use jabbrv.py for lookups. Never guess abbreviations — even common journals have non-obvious abbreviations.

Quick Reference

Output format

Stdout is a stable JSON envelope when the CLI is not attached to a terminal (piped or captured by an agent), and a human table/indented view when run on a TTY. To force a format: --format json|table|human|auto. --json remains as a back-compat alias for --format json. Flags may appear before or after the subcommand.

Envelope shape (always the same fields for every subcommand):

• Success: { "ok": true, "data": ..., "meta": { "schema_version", "cli_version", "cache", "latency_ms" } }
• Partial success (batch): { "ok": "partial", "data": { "succeeded": [...], "failed": [...] }, "meta": {...} }
• Error: { "ok": false, "error": { "code", "message", "retryable", ... }, "meta": {...} }

Exit codes

Error codes (inside error.code)

Branch on error.code + error.retryable rather than exit code alone — exit 1 covers both upstream_unavailable and runtime_error. Full machine-readable listing: python3 jabbrv.py schema → data.error_codes.

Environment variables (set by host, not by agent argv)

Trust boundary: these are read from the process environment, not from arguments. The host or sandbox sets them; the agent cannot override them via argv. Schema introspection: python3 jabbrv.py schema → data.global_env.

Retries, idempotency, and destructive intent

• Branch on error.code + error.retryable, not exit code alone. Exit 1 covers both upstream_unavailable (retry) and runtime_error (retry once, then escalate).
• bib --idempotency-key <token> persists the success envelope next to the output file as <output>.<token>.envelope.json. A retry with the same key returns that envelope with meta.idempotent_replay: true instead of rerunning the rewrite. Token must match [A-Za-z0-9._-]{1,64}.
• cache rebuild is atomic — downloads stage into a sibling directory and the swap only happens if every file succeeded. If any fails, the existing cache is preserved and the response is upstream_unavailable (retryable). Add --yes to record meta.confirmed: true for audit policies; the CLI itself never prompts, so --yes is not a gate.

Workflow

Step 1: Detect Intent

Step 2: Execute

Run the appropriate jabbrv.py command. The script handles:

1. Local cache lookup (instant, ~25K journals from JabRef)
2. AbbrevISO API fallback (algorithmic ISO 4 abbreviation, forward only)
3. NLM Catalog fallback (biomedical journals, bidirectional)

First run downloads JabRef CSV cache files automatically (~2-5 MB).

Step 3: Present Results

• Show the full name, abbreviation, and source
• Note the standard (ISO 4 vs MEDLINE) when relevant
• For .bib processing: show the change summary before confirming

ISO 4 vs MEDLINE

Two common abbreviation standards exist:

JabRef provides ISO 4 style. NLM Catalog provides MEDLINE style. AbbrevISO computes ISO 4 algorithmically from LTWA (List of Title Word Abbreviations).

Common Abbreviation Patterns

Note: Single-word titles (e.g., "Nature", "Science", "Cell") are NOT abbreviated per ISO 4 rules.

Integration Examples

With Zotero

# Export BibTeX from Zotero, then standardize journal names
zot export COLLECTION_KEY --format bibtex > refs.bib
python3 jabbrv.py bib refs.bib

With LaTeX

# Before compiling, ensure all journal names are abbreviated
python3 jabbrv.py bib references.bib
# Use the output file (references_abbrev.bib) in your LaTeX document

Batch Processing

Create a text file with one journal name per line:

Nature Medicine
Journal of Biological Chemistry
Proceedings of the National Academy of Sciences

Then run:

python3 jabbrv.py batch journals.txt

Troubleshooting