# peptacular

> ProForma 2.1 peptide sequence library for Python: parse and serialize ProForma,
> edit modifications, and calculate mass, m/z, elemental composition, fragment ions
> (exportable as mzPAF), isotopic envelopes, enzymatic digests and physicochemical
> properties.

Install with `pip install peptacular` (Python >= 3.12). Import as `pt`. There are two
equivalent APIs:

- the object API: `pt.parse("PEM[Oxidation]TIDE/2")` returns a `ProFormaAnnotation`
  with methods such as `.mass()`, `.mz()`, `.fragment()` and `.digest()`;
- the functional API: `pt.mass(seq)`, `pt.fragment(seq)`, `pt.digest(seq, "trypsin")`
  and friends accept a string, an annotation or a list, and parallelize large lists.

Optional extras add an MCP server (`peptacular[mcp]`, console script
`peptacular-mcp`) and converters for pyteomics, psm_utils and AlphaBase
(`peptacular[interop]`).

peptacular is part of tacular-omics. It takes all reference data (modifications, amino
acids, elements, ion types, proteases) from `tacular`, and its fragments export as mzPAF
strings that `paftacular` parses.

## Docs

- [llms-full.txt](https://raw.githubusercontent.com/tacular-omics/peptacular/main/llms-full.txt): self-contained usage guide for agents, covering public names with signatures, examples, the CLI and gotchas
- [README](https://github.com/tacular-omics/peptacular/blob/main/README.md): overview, install, quick examples
- [Quick start](https://peptacular.readthedocs.io/en/latest/quickstart.html): tested examples of parsing, editing, mass, fragments, digestion, isotopes, properties
- [Mass calculation](https://peptacular.readthedocs.io/en/latest/mass_calculation.html): ion types, charge, isotopes and deltas
- [Streaming and batch](https://peptacular.readthedocs.io/en/latest/streaming.html): `iter_fasta`, `batch`, `iter_batch`, diagnostics
- [JSON serialization](https://peptacular.readthedocs.io/en/latest/json_serialization.html): versioned lossless JSON and its schema
- [CHANGELOG](https://github.com/tacular-omics/peptacular/blob/main/CHANGELOG.md): release notes and migration from 3.x

## API

- [API reference](https://peptacular.readthedocs.io/en/latest/api.html): Sphinx autodoc for the whole package
- [Features](https://peptacular.readthedocs.io/en/latest/features.html): feature overview
- [Interoperability](https://peptacular.readthedocs.io/en/latest/interoperability.html): pyteomics, psm_utils and AlphaBase converters
- [Local MCP server](https://peptacular.readthedocs.io/en/latest/mcp.html): the 12 `peptacular-mcp` tools, client setup and limits
- [ProForma JSON schema](https://peptacular.readthedocs.io/en/latest/proforma-json-v1.schema.json): JSON Schema for `to_proforma_json` output

## Optional

- [CLAUDE.md](https://github.com/tacular-omics/peptacular/blob/main/CLAUDE.md): guide for coding agents working on peptacular itself
- [PROFORMA_COMPLIANCE.md](https://github.com/tacular-omics/peptacular/blob/main/PROFORMA_COMPLIANCE.md): ProForma 2.1 feature coverage
- [ProForma specification](https://github.com/HUPO-PSI/ProForma): the notation standard
- [tacular](https://github.com/tacular-omics/tacular): reference data layer
- [paftacular](https://github.com/tacular-omics/paftacular): mzPAF fragment annotation parser
- [GitHub](https://github.com/tacular-omics/peptacular) and [PyPI](https://pypi.org/project/peptacular/)
