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

| User wants... | Command | |---------------|---------| | Abbreviate a journal name | python3 jabbrv.py abbrev "Nature Medicine" | | Expand an abbreviation | python3 jabbrv.py expand "Nat. Med." | | Auto-detect direction | python3 jabbrv.py lookup "J. Am. Chem. Soc." | | Fuzzy search (paginated) | python3 jabbrv.py search "biolog chem" --limit 10 --offset 0 | | Process a .bib file | python3 jabbrv.py bib refs.bib | | Preview .bib changes (no write) | python3 jabbrv.py bib refs.bib --dry-run | | Explicit .bib output path | python3 jabbrv.py bib refs.bib --output out.bib | | Expand .bib abbreviations | python3 jabbrv.py bib refs.bib --expand | | Replay-safe .bib (retry returns cached envelope) | python3 jabbrv.py bib refs.bib --idempotency-key run-001 | | Batch text list | python3 jabbrv.py batch journals.txt | | Batch as NDJSON stream | python3 jabbrv.py batch journals.txt --stream | | Inspect cache state | python3 jabbrv.py cache status | | Download missing cache files | python3 jabbrv.py cache update | | Preview what update would fetch | python3 jabbrv.py cache update --dry-run | | Atomic rebuild (destructive, with audit marker) | python3 jabbrv.py cache rebuild --yes | | Preview rebuild (no delete) | python3 jabbrv.py cache rebuild --dry-run | | Suppress stderr progress | python3 jabbrv.py --quiet cache update | | Machine-readable CLI contract | python3 jabbrv.py schema | | Schema for one subcommand | python3 jabbrv.py schema lookup |

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

| Code | Meaning | |------|---------| | 0 | success (including partial success) | | 1 | runtime / upstream error | | 2 | validation / bad input (missing file, bad flag) | | 3 | not found (the looked-up journal does not exist) |

Error codes (inside error.code)

| Code | Retryable | Exit | Meaning | |------|-----------|------|---------| | not_found | no | 3 | Lookup completed but no source matched | | upstream_unavailable | yes | 1 | One or more upstream APIs failed transiently; the lookup could not be concluded. Carries error.sources[] listing each failure. Retry later. | | file_not_found | no | 2 | Input file path does not exist | | validation_error | no | 2 | Bad argument or flag combination | | runtime_error | yes | 1 | Unexpected internal error |

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)

| Variable | Effect | |----------|--------| | JABBRV_CACHE_DIR | Override the cache directory (default: /cache). Useful in sandboxes where the install tree is read-only. | | JABBRV_OFFLINE | Truthy (1/true/yes/on) skips AbbrevISO and NLM; only the local JabRef cache is consulted. Misses become definitive not_found (not retryable) since the host has declared upstream off-limits. meta.offline: true appears in every envelope so callers can see the policy. | | NO_COLOR | https://no-color.org convention. Any non-empty value disables color. No ANSI is emitted today; meta.no_color: true appears when set so callers can see the policy. |

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 persists the success envelope next to

the output file as ..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

| Intent | Action | |--------|--------| | Single journal name/abbreviation | Use lookup (auto-detect) or abbrev/expand (explicit direction) | | "What's the abbreviation for X?" | Use abbrev | | "What journal is X?" | Use expand | | Partial or uncertain name | Use search for fuzzy matching | | Fix journal names in .bib file | Use bib | | List of journals to process | Use batch |

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:

| Standard | Periods | Example | Used by | |----------|---------|---------|---------| | ISO 4 | Yes | Nat. Med. | Most publishers, BibTeX | | MEDLINE | No | Nat Med | PubMed, NLM databases |

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

| Word | Abbreviation | Word | Abbreviation | |------|-------------|------|-------------| | Journal | J. | International | Int. | | American | Am. | European | Eur. | | Science/Sciences | Sci. | Medicine/Medical | Med. | | Biology/Biological | Biol. | Chemistry/Chemical | Chem. | | Physics/Physical | Phys. | Engineering | Eng. | | Research | Res. | Review/Reviews | Rev. | | Society | Soc. | National | Natl. | | Proceedings | Proc. | Transactions | Trans. | | Letters | Lett. | Communications | Commun. | | Applied | Appl. | Computational | Comput. |

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

| Issue | Solution | |-------|---------| | "No result found" | Try search with partial name for fuzzy matching | | Cache download fails | Check network connection, retry with cache update (or cache rebuild to force) | | Wrong abbreviation style | JabRef = ISO 4 (with dots), NLM = MEDLINE (no dots) | | BibTeX field not detected | Ensure format is journal = {Name} (curly braces) |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Agents365-ai
• Source: Agents365-ai/journal-abbrev
• License: MIT

Install and usage instructions live in the source repository linked above.