rfd4-proteina-campaign

RFD4-Proteína design campaigns

Purpose

A campaign is an inspectable scientific program, not a collection of output directories. Its durable product is a ledger that connects every design to the exact annotated CIF, resolved configuration, run, lineage, metrics, oracle predictions, and versioned passer decision that produced it.

Required operating contract

1. Interview the user about intent, success criteria, uniqueness, compute budget,

and scheduler choices before launching work.

1. Initialize the campaign ledger before the first run. Register inputs, resolved

configs, and planned runs before submission; ingest designs and oracle results incrementally.

1. Preserve every user-selected partition, account, QoS/priority, reservation,

constraint, GPU, memory, CPU, and runtime setting. State the resolved values before submission and never substitute a competing directive.

1. Give every materialized design a stable ID. Never recover input, config, or

parentage by matching filename fragments.

1. Preserve all oracle predictions and available confidence JSON, including

on-target, off-target, checkpoint, and failed evaluations. Metrics link to the exact design or prediction that produced them.

1. Define passers with an immutable criteria-set version. Store actual metric

values and evidence; changing a threshold creates a new evaluation rather than overwriting history.

1. Treat interrupted runs as recoverable. Ingest completed outputs, record missing

or failed work explicitly, and reconcile the filesystem with the ledger before retrying.

Prerequisites

Python 3.12 for the ledger, a writable campaign directory, and the setup/generation/evaluation skills for model runs.

Use the user-selected model checkout at RFPROTEINA_ROOT for model commands, configs, and upstream manuals. This catalog contains the skills, not that checkout. In helper examples, resolve open-models-skills/rfd4-proteina/<name>/... to its absolute installed path when the catalog and model checkout are separate.

Inputs

Required: the user's campaign location, objective, criteria, uniqueness rule, budget, and scheduler choices. Optional: an existing ledger to resume. Reuse established choices; ask only for missing values that affect the campaign.

Instructions

1. Intent and setup — complete rfd4-proteina-setup, interview the user, and

initialize the ledger.

1. Inputs — use rfd4-proteina-annotated-cif to create and validate each

annotated CIF; archive every conditioning variant as a distinct input.

1. Criteria — agree on gating metrics, exact operators and thresholds,

missing-value policy, and the definition of uniqueness.

1. Pilot — run one small end-to-end generation and evaluation, including the

ledger ingest and reconciliation path.

1. Baseline — use rfd4-proteina-generate to establish best-of-N pass rate,

diversity, and GPU-hour efficiency.

1. Explore — use rfd4-proteina-commitment-curves when reward timing matters

and rfd4-proteina-autoresearch for wave-based search experiments.

1. Scale and proliferate — scale selected input/config pairs, then use partial

diffusion where supported by the evidence. Preserve parent-child lineage.

1. Evaluate and deliver — use rfd4-proteina-evaluate, recompute passers under

the named criteria version, and call rfd4-proteina-package for a shareable TAR.

Read references/campaign-strategy.md when choosing baselines, experiments, scaling, or partial diffusion. Read references/lifecycle.md before planning or running a campaign. Read references/campaign-ledger.md before creating or ingesting records. Read references/passers-and-oracles.md when defining filters, uniqueness, or refolding. Read references/execution-and-recovery.md before any real launch or recovery.

Examples

The deterministic helper creates a portable SQLite ledger and content-addressed artifact store:

python open-models-skills/rfd4-proteina/rfd4-proteina-campaign/scripts/campaign_ledger.py --help

Cluster workers write immutable JSONL events under their run directory. A single coordinator imports those events into SQLite; workers do not write the shared database concurrently. CSV/Markdown reports are exports, never the source of truth.

Output Format

A campaign handoff reports the criteria-set version, number of evaluated designs, passers and unique passers, unresolved failures or missing metrics, compute used, and exact location of the ledger and delivery TAR. A delivered design must trace to its annotated CIF, resolved config, output CIF, oracle predictions, actual metric values, and passer evidence.

Limitations

The ledger records provenance and measured criteria; it does not establish experimental binding or activity. Missing metrics remain explicit and cannot count as evidence of a passer.

Troubleshooting

For interrupted jobs, ingest completed events and reconcile before retrying. For missing artifacts or criteria evidence, inspect the recorded IDs and source paths; do not infer lineage from filenames.

Available Scripts