# paftacular

> Python library for parsing and serializing mzPAF, the HUPO-PSI Peak
> Annotation Format for mass spectrometry fragment-ion annotations (e.g.
> `y5-H2O^2/1.2ppm*0.95`, `b2{PEP}`, `IK[Acetyl]`). Requires `tacular` for
> element/amino-acid/fragment-ion-mass lookups. It optionally integrates with
> `peptacular` for peptide-sequence-aware mass/composition calculations and
> converting `peptacular` `Fragment` objects directly into mzPAF annotations.

Parse mzPAF with `parse_single()` or `parse_multi()`. `iter_parse()` and
`parse_batch()` retain structured errors for individual input records.
Build annotations with `PafAnnotation.make_*` factories. Use `resolve()` with
a full analyte before calculating complete peptide or precursor masses.
Without sequence context, these calculations return offsets and modifiers.
Use `to_dict()` and `PafAnnotation.from_dict()` for versioned interchange,
including resolved context. `as_dict()` remains a compact display format.

MCP integration is available in paftacular 1.3.0 and newer with
`pip install 'paftacular[mcp]'`. Configure a local MCP host to launch `paftacular-mcp`.
It provides parsing, construction, resolution, calculation, generation, and
m/z matching tools, plus reference resources and analysis prompts. Complete
peptide calculations require context. See [MCP guide](docs/mcp.rst).

## Docs

- [README](README.md): installation, quick start, mzPAF format overview
- [CLAUDE.md](CLAUDE.md): architecture and command reference for AI coding agents, including the frozen-dataclass instance-caching pattern and fragment-ion-lookup-key gotchas
- [HISTORY.md](HISTORY.md): changelog
- [Read the Docs](https://paftacular.readthedocs.io/en/latest/): full usage guide and API reference (Sphinx)

## Source

- [GitHub repository](https://github.com/tacular-omics/paftacular)
- [PyPI package](https://pypi.org/project/paftacular/)

## Optional

- [mzPAF specification](https://github.com/HUPO-PSI/mzPAF): the HUPO-PSI peak annotation format standard that paftacular parses and serializes
- [tacular](https://github.com/tacular-omics/tacular): required dependency providing element/amino-acid/fragment-ion-mass lookups
- [peptacular](https://github.com/tacular-omics/peptacular): optional dependency for peptide-sequence-aware mass/composition calculations and `to_mzpaf()` Fragment conversion
