ChatterjeeLab / PepPA

PepPA

Peptide Planning and Prioritization Agent

PepPA coordinates multi-objective peptide generation and computational verification before final sequence commitment. The internal design loop uses PepDFM/MOG-DFM and PepMDLM/PepTune with SOAPIA, moPPIt, AlloGen, and PeptiVerse objectives. Outer checks cover AF3/docking/EvoBind structures, external pepADMET predictions, chemical identity, synthesizability, and CMC. Required human and preclinical contexts define robust generation objectives. Experimental characterization follows the frozen computational release.

This is a manuscript and reference implementation package. The CPU kernel runs deterministic dependency graphs, validates outputs, aggregates endpoint-compatible model predictions, and applies release checks. Native scientific workers and full benchmark experiments require the integrations listed in docs/IMPLEMENTATION_STATUS.md . Integration into the existing PeptiVerse Hugging Face Space is planned.

Install and verify

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python scripts/run_compiled_example.py
python -m unittest discover -s tests -v

The example uses eight real, pinned SNOOPPI records. It preserves their interaction labels and demonstrates complete execution with an empty peptide release because required property predictions and chemical verification are absent. It runs no GPU model and invents no scores. The saved trace reproduces exactly from its cache. Thirty-four local tests cover execution, aggregation, release, scientific utilities, and the maximum-effort provider request settings. Synthetic values occur in explicitly labeled unit fixtures.

Computational formulation

1. Define targets, countertargets, chemistry, human/preclinical contexts, endpoints, and budgets.
2. Retrieve a fixed source snapshot and construct source-linked mechanistic hypotheses.
3. Compile tool dependencies, requirements, model revisions, and conditional branches.
4. Generate up to 192 proposals using native multi-objective frameworks.
5. Evaluate required properties, structures, external checkers, and synthesis/CMC requirements.
6. Apply the fixed diagnostic-to-redesign rule for at most 192 further proposals.
7. Commit chemically defined sequences with complete context-specific reports and source records.

The plan is frozen before execution. Every molecular change has a new identity and fresh scores. Experimental data belong in a separate evaluation dataset keyed to the frozen release hash.

Files

• src/peppa/compiled.py : deterministic CPU reference kernel, lineage-aware stacking, robust reward, redesign schedule, and release checks.
• scripts/run_compiled_example.py : real-source-data execution and incomplete-release example.
• results/compiled_trace.jsonl , results/compiled_release.json : actual outputs from that example.
• docs/SOPHIE_RUNBOOK.md : E0–E5 execution instructions, exact study allocations, controls, artifacts, and analysis.
• docs/IMPLEMENTATION_STATUS.md : tested implementation and required native integrations.
• docs/WORKER_INTEGRATION.md : scientific worker APIs and score contracts.
• docs/SPACE_DESIGN.md : planned Muse-backed agent within the PeptiVerse Space.
• configs/study_plan.json : synchronized computational and prospective study design.
• configs/model_registry.json : pinned model and dataset revisions.
• schemas/PlanProposal.json : language-model plan interface.
• schemas/ : existing chemical/worker record schemas.
• assets/figures/ : vector PDFs, editable SVGs, and PNG previews with Ubuntu labels.
• docs/references.bib , docs/PepPA.pdf : bibliography and compiled manuscript.

The original peppa run controller engine remains available for baseline/tool-adapter development. The primary frozen-plan formulation uses peppa.compiled ; native worker and language-model compiler integration remains an explicit implementation stage. results/real_data_trace.jsonl is the source-ingestion example regenerated from the pinned source records.

Models and scientific workers

Muse Glimmer-30B is the default open-weight backend. Its pinned identity is recorded in configs/model_registry.json . GPT-6 Astra Max and Claude Opus Max use the same PlanProposal schema. Provider credentials and exact serving revisions are supplied in the execution environment. The archive includes provider adapters but contains no live provider evaluation.

moPPIt and PeptiVerse bridges follow the inspected native APIs. PepDFM/MOG-DFM, PepMDLM/PepTune, SOAPIA, AlloGen, AF3, docking, EvoBind, pepADMET, chemical standardization, and manufacturing checks require worker registration and known-input preflight. Every worker must report its input chemistry, native endpoint, units, target context, checkpoint, preprocessing, and training lineage.

External code, weights, logos, and fonts retain their original rights. See NOTICE.md . The LaTeX project compiles with XeLaTeX, BibTeX, XeLaTeX, XeLaTeX.