Architecture

Architecture

CYPForge is organized into three cores that produce a single MD-ready system, executed as ten stages with hard gates between them.

Three cores

Core	What it produces	V1.3 entry points
Core 1 — Heme + axial Cys	A standardized PDB with heme correctly placed, axial CYS renamed CYM, plus state-specific HEM / CYP mol2 and frcmod files	cypforge module heme prepare, cypforge module heme leap
Core 2 — Ligand RESP + GAFF2	A typed ligand.mol2 with RESP charges + GAFF2 frcmod, atom names consistent with the complex PDB	cypforge module ligand prepare, cypforge module ligand leap
Core 3 — Assembly + pre-MD	Solvated, ionized AMBER topology + 9-stage equilibration (stage 09 = 20 ns free NPT) + global audit + readiness decision	cypforge module protonation finalize, cypforge module solvate render/validate, cypforge module pre-md render/validate, cypforge module global-audit

The cores are not independent — Core 2 takes the Core 1 PDB as --complex-pdb, and Core 3 consumes the artifacts from both. The boundary is enforced by the orchestrator, not by the script signatures, so you cannot accidentally feed a Core 1 input file into Core 3.

Ten stages

The fixed order, enforced by skills/cypforge/skills_manifest.json and src/cypforge_core/orchestrator/models.py:

00  environment_check                   # Amber/Multiwfn/WSL availability
01  core1_prepare_heme_cym              # heme placement + CYM rename + Fe-S bond
02  core2_prepare_ligand_resp_gaff2     # ligand graph match + GAFF2 + RESP
03  core3_finalize_protonation          # apply protonation_decision.json
04  core3_solvate_ionize                # tleap solvate + counterion neutralization
05  core3_render_pre_md                 # render 9 mdin files
06  core3_run_pre_md                    # run the 9-stage pre-MD
07  global_audit                        # geometry + charge + Fe-S audit
08  equilibration_decision              # decide whether system equilibrated
09  production_readiness_check          # final gate before production MD

Each stage writes:

• <stage>.manifest.json — machine-readable inputs, outputs, command lines, gate result, timing.
• <stage>.report.md — human-readable summary of decisions and observations.
• logs/<stage>.log — full stdout/stderr from any subprocess.

Data flow

                            ┌─────────────────────┐
                            │ run_config.json     │
                            │ run_manifest.json   │
                            └──────────┬──────────┘
                                       │
   PDB ──────┐                         ▼                       ┌──> heme mol2/frcmod
            ┌┴─ Core 1 ─ heme + CYM placement, Fe-S bond ───────┤
   SDF ─────┤                                                   └──> standardized PDB
            │                          │                               │
            └─ Core 2 ─ ligand RESP + GAFF2 ─────────────────────┐    │
                                       │                          ▼    ▼
                                       │                  ligand.mol2 / frcmod
                                       ▼
                          Core 3 stages 03-09:
                            protonation → solvate/ionize →
                            render pre-MD → run pre-MD →
                            global audit → equilibration_decision →
                            production_readiness_check
                                       │
                                       ▼
                       ┌──────────────────────────────────┐
                       │ system.prmtop / inpcrd           │
                       │ stage_09_final.rst7              │
                       │ global_audit_report.md           │
                       │ production_readiness.json        │
                       └──────────────────────────────────┘

Code layout

Layer	Path	Purpose
Orchestration	src/cypforge_core/	WorkflowManager, ModuleRunner, GateChecker, AgentContext
Chemistry	src/cypforge/	Heme placement geometry, axial-Cys identification, Fe–S checks
CLI	src/cypforge_core/cli.py	Installed cypforge command and cypforge module ... stage entry points
Skills	skills/cypforge/	The agent-facing skill manifest + 10 skill .md files
Tests	tests/	pytest suite (heme core, orchestrator)

The orchestrator

WorkflowManager (in src/cypforge_core/orchestrator/workflow.py) is the state machine. Its job is:

1. Load run_config.json and run_manifest.json.
2. Find the first stage whose status is not PASS or SKIPPED.
3. Hand off to ModuleRunner, which formats the CLI invocation, runs the subprocess, and writes the per-stage log.
4. Run GateChecker.check(stage_dir) to read the stage's manifest and decide PASS / WARN / FAIL.
5. Update run_manifest.json and either continue, pause (WARN without --auto-accept-warn), or stop (FAIL).

This loop is the whole control flow. There is no implicit recovery, no "carry on with the previous result", no skip-on-error. Every transition is explicit.

Skills layer

The same workflow is exposed to AI agents through skills/cypforge/. Each skill .md file contains:

• the stage's preconditions and required inputs,
• the exact command-line invocation,
• the expected outputs and manifest schema,
• the gating criteria (what makes the result PASS / WARN / FAIL),
• how to recover from common failure modes.

SKILL.md is the top-level contract — an agent runner reads this first, then walks the manifest in order. See Gate System and Manifests for the gate schema.

What lives where (quick reference)

src/cypforge_core/
├── cli.py                            # `cypforge` console entry point
├── orchestrator/
│   ├── workflow.py                   # state machine
│   ├── runner.py                     # subprocess + log capture
│   ├── gates.py                      # PASS/WARN/FAIL evaluator
│   ├── context.py                    # JSON context export for agents
│   └── models.py                     # stage definitions + ordering
├── complex_pre_md_equilibration.py   # 9-stage equilibration runner
├── complex_solvation_ionization.py
├── complex_protonation_finalize.py
├── complex_global_audit.py
├── ligand_*.py                       # Core 2 implementations
└── heme.py / heme_mapping_leapin.py  # Core 1 implementations

src/cypforge/
├── heme/
│   ├── prepare.py                    # heme placement (Layers 1-6 of S3)
│   └── mapping.py                    # template ↔ source atom correspondence
├── cys/
│   ├── axial_identification.py       # Fe-S distance + geometry checks
│   ├── fe_s_geometry.py
│   └── proximal_rewrite.py           # CYS → CYM rename
└── data/heme_params/                 # IC6 / DIOXY / CPDI mol2 + frcmod

Next: Mathematical Foundations for the proof structure that backs Core 1 and Core 2.