🧬 Peptide Bioactivity Audit Pipeline (PBAP)

🚀 Try it online (no install) → huggingface.co/spaces/Paredes-0/pbap-demo Free, non-commercial public demo. Paste up to 50 peptides and download the same REPORT.html the CLI produces locally. The operator-side scaffold (FastAPI + Gradio + Cloudflare Tunnel) lives under demo/.

🌐 Architecture overview → paredes0.github.io/pbap Visual walkthrough of how the pipeline works (Phase 1 flow, integrated tools, agreement layer, hierarchical ranking, APEX selectivity, applicability-domain grading).

PBAP is a modular orchestrator that audits the reusability of published peptide-bioactivity prediction tools and coordinates them under a unified output schema, adding analytical layers (concordance, pathogen / commensal selectivity, hierarchical multi-criteria ranking) that are absent from individual tools.

Out of 26 prediction tools published between 2023 and 2025 that we systematically evaluated, 10 are currently integrated and operational, spanning 7 bioactivity categories: toxicity, hemolytic, antimicrobial, anti-inflammatory, anticancer, blood-brain-barrier, cell-penetrating peptides.

License at a glance: this orchestrator is released under the PolyForm Noncommercial 1.0.0 license. Free for research, academic and personal use. Commercial use requires a separate license — see LICENSE for contact info.

The 26 third-party tools are NOT bundled and each has its own license — see THIRD_PARTY_LICENSES.md.

---

Why this project

Most peptide-bioactivity prediction tools published in the literature report high in-paper metrics, but the practical reality is fragmented:

• ~60% of evaluated tools cannot be run as-is (training scripts published as if they were inference, missing weights, feature pipelines without an orchestrator, login walls, etc.).
• Each runnable tool uses a different input format, output format and environment.
• No published platform coordinates them under a single schema, with bacterial-selectivity tagging and a multi-criteria ranking.

PBAP fills that gap. It is also designed as a platform of tools rather than a monolithic predictor: adding, replacing or disabling a tool is a YAML edit, not a code change. This makes it sustainable in a field where dozens of new tools are published every year.

---

Quick start

# 1. Clone
git clone https://github.com/Paredes0/pbap.git
cd pbap

# 2. Install micromamba (per-tool environment manager)
# See https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html

# 3. Clone the 10 prediction tools + apply patches (one command, idempotent)
bash scripts/bootstrap_tools.sh

# 4. Create the 6 micromamba environments the tools live in
#    (~30–40 GB disk, 20–40 min on a decent connection)
bash scripts/bootstrap_envs.sh

# 5. Create the orchestrator's own env (Python ≥ 3.10, 5 tiny deps)
micromamba create -n pbap_orchestrator python=3.11 pip
micromamba activate pbap_orchestrator
pip install -r requirements.txt

# 6. Run the smoke test with the bundled example FASTA
python scripts/run_audit.py --input Inputs/example.fasta
# Result: Outputs/example_<timestamp>/REPORT.html

⚠️ Step 3 of docs/SETUP_FROM_SCRATCH.md adds one manual download (HemoPI2's Model.zip, hosted off-repo by the upstream authors). Everything else is scripted.

📖 Full walkthrough: docs/SETUP_FROM_SCRATCH.md. 📖 Architecture: docs/architecture.md. 📖 Doc index: docs/INDEX.md.

---

What you get per run

For every batch of input peptides, the orchestrator produces under Outputs/<input>_<timestamp>/:

File	What it contains
REPORT.html	Interactive HTML5 (sortable matrix + filters + per-peptide drill-down). No external dependencies. The primary artefact for eye-balling results.
REPORT.md	Plain-text Markdown summary (6 sections).
consolidated.csv / .json	Wide (CSV) and nested (JSON) data, every prediction with score, agreement flags and extra metrics.
consolidated.xlsx	5-sheet Excel workbook with conditional formatting, autofilter and frozen panes.
tool_health_report.json	Per-tool runtime, status and diagnosis (catches partial failures).

---

Integrated tools (10 active)

Category	Tool	Notes
Toxicity	ToxinPred3	SVM + molecular features
Antimicrobial (binary)	AntiBP3	sklearn + blastp
Antimicrobial (34 strains, MIC µM)	APEX	+ pathogen / commensal / broad-spectrum selectivity tagging
Hemolytic	HemoPI2	ESM-2 fine-tuned
Hemolytic	HemoDL	ESM-2 + ProtT5 ensemble
Anticancer	DeepBP	ESM-2 deep ensemble
Anticancer	ACP-DPE	CNN + GRU dual-path
Blood-brain barrier	DeepB3P	Transformer-based
Cell-penetrating peptides	PerseuCPP	Two-stage (CPP + efficiency)
Anti-inflammatory	BertAIP	BERT-based, threshold 0.8

Plus 5 tools currently parked (waiting on RAM, login walls or LFS hydration) and 10 evaluated but structurally blocked (training-script-as-inference, missing weights, etc.). See docs/pipeline_viability.md for the per-tool verdict.

---

Adding your own tools

The pipeline is intentionally a platform. Adding a new tool is a YAML edit, not a Python change. The architecture supports two configuration files coordinated by state:

• config/pipeline_config.yaml — active tools + standby tools (~14 entries).
• config/pipeline_config_blocked.yaml — tools evaluated and blocked, kept for traceability without polluting the productive config.

A minimal YAML block looks like:

tools:
  your_tool_id:
    display_name: Your Tool
    category: antimicrobial
    conda_env: torch
    script: predict.py
    arg_style: flagged           # or: positional
    input_flag: -i
    output_flag: -o
    output_capture: file         # or: hardcoded_file | stdout
    output_parsing:
      format: csv
      prediction_column: Prediction
      positive_label: 1
      score_column: Probability
      score_threshold: 0.5

Full guide and dimensions: see CONTRIBUTING.md and docs/orchestrator_design.md.

---

Working with AI agents on this repository

This repository follows the AGENTS.md convention: a root file (AGENTS.md) defines the operating manual for AI agents working on the code, the doc directory (docs/INDEX.md) serves as their navigation entry point, and a short ONBOARDING.md at the root explains how the docs system stays alive when code changes (the contract). Compatible agents include Claude Code, Gemini CLI, Cursor, GitHub Copilot Workspace and similar.

If you clone this repository and open it with an AI assistant, it will pick up the project's full context (architecture, decisions, conventions, glossary, pipeline viability) without any manual setup. This was a deliberate design choice: lowering the barrier to entry for contributors who use AI assistance but have no formal programming background, and making the project sustainable beyond its original author.

If you contribute via AI assistance, your PRs are reviewed against the same quality bar as manual contributions.

---

Project structure

.
├── bin/                          # Bash entry points (audit_pipeline.sh)
├── scripts/                      # Python orchestrator and helpers
│   └── run_audit.py              # End-to-end inference orchestrator
├── audit_lib/                    # Shared library (config, runner, parsers, ...)
├── wrappers/                     # Tiny CLI adapters for specific tools
├── config/
│   ├── pipeline_config.yaml          # Active + standby tools (~14)
│   ├── pipeline_config_blocked.yaml  # Blocked / inactive tools (~12)
│   ├── categories_config.yaml        # Bioactivity categories + polarities
│   └── apex_strain_classification.yaml  # Pathogen / commensal mapping
├── docs/                         # Project documentation (INDEX.md is the entry)
├── demo/                         # Reference scaffold for the public web demo
│   ├── api/                      #   FastAPI backend (operator's Linux host)
│   └── frontend/                 #   Gradio app (Hugging Face Space)
├── patches/                      # ~100 lines of mechanical adapters to 5 tools
├── envs/                         # micromamba YAML manifests for the 6 envs
├── site/                         # GitHub Pages landing source
├── Inputs/                       # Drop your FASTA files here (gitignored)
├── Outputs/                      # Auto-created per run (gitignored)
├── test_data/                    # Canonical FASTA samples for smoke tests
├── AGENTS.md                     # AI agent operating manual
├── CLAUDE.md / GEMINI.md         # Agent-specific entrypoints (import AGENTS.md)
├── LICENSE                       # PolyForm Noncommercial 1.0.0
├── NOTICE                        # What is and is not distributed here
├── THIRD_PARTY_LICENSES.md       # License status of the 26 third-party tools
└── CITATION.cff                  # How to cite this work

Folders excluded from the repository (see .gitignore):

• Dataset_Bioactividad/ — local clones of the 10 third-party tools. Auto-clonado por scripts/bootstrap_tools.sh usando los github_url declarados en config/pipeline_config.yaml (e historial detallado en docs/pipeline_viability.md).
• DATABASES_FASTA/ — external peptide databases (download yourself from DBAASP, APD3, ConoServer, etc.). Required for Phase 2 (offline audit) only; Phase 1 (user inference) does not need it.
• reference_data/ — internal curated reference data used by Phase 2. Not redistributed; Phase 2 is therefore not reproducible from this repo alone (see docs/SETUP_FROM_SCRATCH.md §scope note).
• Inputs/* / Outputs/* — user data and run artefacts (folders kept via .gitkeep; Inputs/example.fasta is tracked so the smoke test works out of the box).

---

Roadmap and contributing

• 🗺️ Roadmap: docs/roadmap.md — community-facing ideas, open for contribution.
• 🐛 Known issues / tech debt: docs/todo.md.
• 🤝 How to contribute: CONTRIBUTING.md — includes the YAML template for adding new tools.
• 📜 Code of Conduct: CODE_OF_CONDUCT.md (Contributor Covenant 2.1).

---

Use of generative AI in the development of this project

This project was developed with the assistance of generative AI models — Claude Opus 4.7 (Anthropic) and Gemini 3 Pro (Google) — used as collaborative tools throughout. The assistance covered four areas:

• Code drafting and review of the orchestrator (audit_lib/, scripts/run_audit.py), the public demo (demo/) and the reproducibility infrastructure (patches/, envs/, scripts/bootstrap_*.sh), always under the author's direction.
• Literature search, retrieval and synthesis, with each cited reference manually verified.
• Assisted drafting of technical documentation (this README, the docs/ folder, the agent-facing ONBOARDING.md and AGENTS.md), with human review and rewriting before commit.
• Methodological discussion on design decisions during development.

All AI-generated output was reviewed, validated and curated by the author. The conceptualisation of the project, the scope, the five-criterion viability-audit protocol, the choice of integrated tools, the dual-output schema, the multi-criteria ranking, the applicability-domain framing, the case-study application to Octopus vulgaris transcriptome-derived peptides, and the operational decisions on demo deployment and mitigation shield are the entire responsibility of the human author.

Generative AI appears here as an operational assistance tool, not as a co-author; no AI model is listed in the authorship, in line with current editorial and academic-evaluation guidelines (e.g. Nature, Elsevier, ICMJE 2023–2024 disclosure policies).

---

Citation

If you use this pipeline in academic work, please cite it as described in CITATION.cff. When the accompanying manuscript is published, a BibTeX entry will be added here.

Each integrated tool has its own primary citation — please cite the tools you actually used, in addition to the pipeline. See THIRD_PARTY_LICENSES.md for per-tool references.

---

License summary

This software is licensed under the PolyForm Noncommercial License 1.0.0.

• ✅ Free for: academic research, teaching, personal projects, public- research organisations, non-profit organisations, government use.
• ❌ Not allowed without a separate license: paid SaaS deployment, commercial product integration, any revenue-generating use.

If you want to deploy PBAP commercially, please contact the author via the address in LICENSE. The author is generally happy to grant commercial licenses on reasonable terms.

The 26 third-party prediction tools are not redistributed by this repository; each has its own upstream license that you must satisfy separately. See THIRD_PARTY_LICENSES.md.