piggyback-first

name	piggyback-first
description	Before writing new code in citeformer, consult the piggyback map. The hard work — token masking, CSL rendering, PDF extraction, NLI — already lives in well-maintained deps. We compose; we don't reinvent.

Piggyback-first

Before writing new code in citeformer, ask: is this already done by one of the libraries we depend on?

The piggyback map lives in docs/reference/architecture.md. The short version:

We piggyback on	For
XGrammar / llguidance	Token-level logit masking
transformers / vLLM / llama-cpp-python	Running the model
citeproc-py + CSL styles repo	Reference-list rendering
lark	Authoring grammars before handoff
httpx + diskcache	Metadata fetchers with caching
grobid-client-python	PDF extraction
readability-lxml	URL extraction
DeBERTa-v3-MNLI via transformers	Entailment verification

What citeformer actually owns

• The citation grammar shape (§10.1 contract) — cite-id GBNF rule + policy rules.
• The CSL-JSON source metadata contract (§10.2).
• The output pydantic models and their schema versions (§10.3).
• The inline-marker-to-reference coupling (no reference without a matching marker; no marker without a reference).
• The orchestration loop — fetching metadata, building the grammar, handing to the backend, decoding output, rendering references, verifying.

Everything else should compose something else.

Red flags

If you catch yourself doing any of these, stop and check whether a dep already solves it:

• Writing a token-by-token sampling loop. (Use XGrammar / llguidance.)
• Parsing CSL style XML. (Use citeproc-py.)
• Reimplementing PDF layout extraction. (Use GROBID.)
• Rolling a BibTeX parser. (Use pybtex or citeproc-py's bib support.)
• Computing entailment from scratch. (Use DeBERTa-v3-MNLI.)

When the answer is genuinely "no existing dep does this" — document why in a code comment, with the dep you considered and the gap you found.