Configuration

There are two configuration levels:

• a protocol describes cohorts, feature registries, experiment variants, prompts, folds, and shot counts;
• a generated run config is the immutable input to one method invocation.

Every generated run records independent provenance axes:

Field	Meaning
encoder_provenance	Whether the encoder boundary is native or bridged by an adapter
prompt_provenance	Where the actual text/prompt artifact originated
implementation_provenance	Whether the executed method code is vendored, mixed, or locally reconstructed
upstream_fidelity	upstream, partial, or local_baseline

Set require_upstream_fidelity: true when a campaign must reject partial implementations rather than merely emit a doctor warning.

Dataset definition

A task entry defines stable label order and prompt semantics:

tasks:
  my_task:
    labels: [class_a, class_b]
    classnames:
      - class A diagnosis
      - class B diagnosis
    prompt_spec: benchmarks/my_benchmark/prompts/my_task.yaml

Label order is significant. It determines numeric labels, logit columns, and method-native prompt ordering.

Feature registry

Feature sources are named independently from model methods:

feature_registry:
  conch_5x:
    encoder: conch
    feature_space_id: hf:MahmoodLab/conch
    input_kind: patch_bag
    feature_dim: 512
    resolution: 5x
    path_template: /data/{cohort}/5x/features_conch
    feature_key: features

The important fields are:

Field	Meaning
encoder	producer or slide encoder name
feature_space_id	exact checkpoint/model provenance
input_kind	patch bag, slide embedding, sequence, or raw tiles
feature_dim	last tensor dimension expected by the adapter
resolution	semantic magnification such as 5x, 10x, or 20x
path_template	cohort-specific storage location
feature_key	exact tensor key inside HDF5/mapping payloads

An inventory source may set runtime_encoder: false when PGVL-Gym can audit and consume its cached tensors but cannot construct that producer's image/text tower in the current environment. Such a source must retain either a local encoder_weights path or a stable encoder_reference; registration does not silently imply method compatibility. This distinction is used for exact feature bookkeeping without pretending that an offline feature space can be used for text comparison.

Low and high resolution are roles, not fixed magnifications. A dual-scale experiment may map low to 5x and high to 20x, or use another declared pair, as long as the method and feature registry agree.

Method and encoder selection

Generated configs record both the runtime prompt encoder and the offline feature source where applicable:

method: muse
backbone: conch
backbone_weights: /models/conch
feature_sources:
  bag: musk_10x
feature_dim: 1024
feature_space_id: hf:xiangjx/musk
prompt_feature_space_id: hf:MahmoodLab/conch
muse_prompt_learning: token_16_conch
n_ctx: 16
muse_runtime: sfse_smmo_full_queue_token_prompt_v2
muse_recipe: cvpr_2026_paper_algorithm_1
muse_semantic_updates_per_slide: 20
muse_logit_fusion: paper_mean
muse_base_patch_filter: paper_top_20_percent
retrieval_k: 20
top_patch_ratio: 0.2

MUSE learns its published 16 context tokens in the CONCH text tower and can learn a visual adapter between these declared widths. A method that compares patch and text embeddings directly cannot do so unless its architecture explicitly defines such a projection.

For SLDPC, slide_encoder identifies cached slide vectors while backbone identifies the runtime prompt tower. slide_projection_mode: native requires the paired slide projector; linear and mlp are explicit learned-alignment variants and must be reported separately.

SLDPC has two distinct text contracts. prompt_classnames is the ordered list of fixed class-code tokens embedded by the learned Stage-1/Stage-2 PromptLearner; its digest and provenance describe the trained run. The released synonym YAMLs and exact 23 templates are used only by upstream's separately reported, untrained TITAN zero-shot baseline. A retained YAML therefore uses zero_shot_prompt_path with zero_shot_prompt_usage: reference_only_unwired; it never determines the trained run's prompt_provenance.

Path expansion

Configuration loading recursively expands environment variables and leading ~/ notation in nested mappings and lists, not only top-level path fields. Use ${PGVL_REPO_ROOT}, ${PGVL_STORAGE_ROOT}, and ${PGVL_USER_ROOT} for portable benchmark configs. An undefined variable remains visible to the doctor and is a configuration error rather than being interpreted as a literal filesystem name.

Resolved YAML must also round-trip through JSON because config.json and the resume fingerprint are the persistent experiment identity. Quote date-like or numeric mapping keys; YAML dates, sets, binary values, non-string keys, and .nan/.inf numbers are rejected during loading instead of failing after a results directory has been created. Duplicate mapping keys are rejected at any nesting level instead of silently keeping the last value. YAML merge keys retain their standard explicit override behavior.

SLDPC configs must state epochs explicitly and set it to stage1_epochs + stage2_epochs. The unified loop does not infer a private adapter default for this schedule because the two upstream training stages are part of the experiment identity.

Split layouts

Runtime loaders and the doctor share three fold representations:

• generated foldN/{train,val,test}.csv files with complete manifest rows;
• CLAM-style splits_N.csv files with train, val, and test slide-ID columns; and
• upstream-style foldN.csv files, which may also carry train_label, val_label, and test_label columns.

For a wide table without phase-label columns, dataset_csv must contain unique slide_id and label columns. The loader joins the requested IDs back to that manifest and retains its exact feature-path and case-ID fields. A label present in both sources must agree. Direct train.csv, val.csv, and test.csv files at the split root are supported only for a single-fold run; multi-fold configs must scope them under foldN/ so the same split is never counted repeatedly.

Prompt sources

Most upstream repositories ship their prompts as an explicit per-task file, and that file is part of the published method: FOCUS and ViLa-MIL each read a headerless one-column CSV containing all low-scale prompts followed by all high-scale prompts, MSCPT reads a GPT description JSON, MUSE reads per-class description CSVs, and SLIP a tissue-name JSON. Which file a run embeds is a scientific parameter, so state it in the cohort rather than leave it to resolution order:

cohorts:
  ubc_ocean:
    prompts:
      focus: text_prompts/focus/UBC_OCEAN_two_scale_text_prompt.csv
      vila_mil: text_prompts/vila_mil/UBC_OCEAN_two_scale_text_prompt.csv
      mscpt: train_data/gpt/description/UBC-OCEAN.json
      slip: text_prompts/slip/ubc_ocean_tissues.json
      convlm: text_prompts/convlm/ubc_ocean_attributes.json
      muse:                       # a method may name several files
        - benchmarks/ubc_ocean/data/ubc_ocean/prompts/muse/generated_new_0.csv
        - benchmarks/ubc_ocean/data/ubc_ocean/prompts/muse/generated_new_1.csv
        - benchmarks/ubc_ocean/data/ubc_ocean/prompts/muse/generated_new_2.csv
        - benchmarks/ubc_ocean/data/ubc_ocean/prompts/muse/generated_new_3.csv
        - benchmarks/ubc_ocean/data/ubc_ocean/prompts/muse/generated_new_4.csv

FOCUS configs record focus_prompt_file_classnames, focus_prompt_file_sha256, and focus_prompt_bank_sha256 because its native files are positional. CAMELYON16, TCGA-NSCLC, and UBC-OCEAN use exact upstream banks; BRCA and RCC are generated task extensions. The released UBC file order is CC, HGSC, LGSC, EC, MC, so the runtime explicitly reorders it to the benchmark classifier order rather than interpreting its rows incorrectly.

ViLa-MIL's positional schema cannot name its classes in-file. Generated configs therefore also record vila_prompt_file_classnames, vila_prompt_file_sha256, and vila_prompt_bank_sha256. The runtime may reorder an explicitly declared file order into classifier order, but rejects missing, extra, or contradictory class bindings. Lung and RCC use byte-exact upstream banks; BRCA, UBC-OCEAN, and CAMELYON16 report prompt_provenance: generated.

SLDPC declares its active and reference-only inputs outside that generic map:

    sldpc_prompt_classnames: [CC, EC, HGSC, LGSC, MC]
    sldpc_prompt_provenance: upstream
    sldpc_zero_shot_prompt_yaml: text_prompts/sldpc/ubc_ocean.yaml

The RCC benchmark class order is CCRCC, PRCC, CHRCC, so those upstream codes are classified as derived after reordering. BRCA's IDC, ILC tokens are a derived subset of the upstream TCGA-OT token list. CAMELYON16 has no released SLDPC task bank and is marked generated.

Paths are repository-relative or absolute. A named file that does not exist is an error, never a silent fallback: a prompt the author asked for and did not get would change what the model reads without saying so.

prompt_provenance describes the selected method condition, not merely the origin of some words inside it. Thus UBC-OCEAN's CSVs are generated for MUSE even though their descriptions originate in an upstream MSCPT bank.

ConVLM is stricter because its released class attribute matrix is absent. A runtime JSON bank must declare or inherit audited provenance, class order, prompt counts, and content hashes. A precomputed .pt bank must additionally use schema pgvl.convlm.attribute_embeddings.v1 and bind the ordered source prompt digest to the text encoder's feature-space ID and checkpoint SHA-256. Bare tensors and .npy matrices are rejected because they cannot prove either row identity or encoder compatibility.

A method with no entry falls back, in order:

1. the cohort's published per-method key (focus_prompt_csv, mscpt_prompt_json, muse_prompt_csvs, …), then
2. the asset compiled from prompt_spec.

prompt_precedence inverts those two for a cohort, or protocol-wide:

Value	Meaning
upstream (default)	the paper's published asset wins; the compiler is the fallback for tasks that have no published prompts
generated	prefer prompts compiled from prompt_spec, for instance to compare every method under one uniform prompt style

WSI-FiVE is an exception to this generic fallback. Its six aligned questions, training answers, and evaluation descriptions have different roles and cannot be inferred from a class-description prompt_spec; configure them explicitly. Native NSCLC binds each role with wsi_*_file_sha256, a semantic wsi_*_bank_sha256, and wsi_*_provenance. The checked-in containers are not byte copies of upstream files: question/evaluation containers are derived, while the complete answer bank is generated because it combines 912 upstream answers with 27 disclosed local blank-cell completions and 82 conservative benchmark-cohort extensions generated by openai:gpt-5.6. The generated rows are not paper-authored. The compiler, runtime, and doctor all enforce the same bindings and generation metadata. CAMELYON16 uses the separate upstream_classname_bank mode: its derived containers transcribe the six released question strings and exact normal/tumor evaluation descriptions, but no report-answer bank is configured or permitted. That mode also locks the upstream 22,528-frame/0.5-sampling recipe.

TOP applies the same rule to its two independent roles. The instance bank is bound by top_instance_file_sha256, top_instance_prompt_bank_sha256, and top_instance_provenance; a configured bag bank additionally requires the corresponding top_bag_* hashes, provenance, and usage. top_prompt_format pins the combined schema. Do not infer prompt_provenance or prompt_source from the filename: the shared loader derives both from the validated instance/bag roles and rejects contradictory declarations. TOP configs must also declare all_ctx_trainable: false. This is the released executable boundary: description words remain frozen and only the ten * slots in each initialized prompt are learned. The adapter and doctor reject full-description training because it changes the model and can numerically saturate the prompt path before SGD produces a representable update. TOP also unit-normalizes every incoming CLIP-RN50 patch vector before its temperature-scaled image/text comparisons. This makes the paper's cosine similarity rule independent of whether an external feature cache stores raw or already-normalized encoder outputs.

Each generated config records which source was actually used in prompt_provenance, and the run matrix carries it as prompt_source and prompt_asset. Check those before reporting: a cohort declaring a prompt_spec alongside a published CSV will silently read one of the two, and the two are not the same experiment.

Class names are prompts for some methods

classnames is not merely a label ordering. TOP, SLDPC, SLIP, WSI-FiVE's simplified_classnames mode, and PathPT's legacy simplified_slide_ce mode build text from it, so a bare study code such as KIRC or CC becomes the prompt. Native PathPT instead resolves its audited task synonym bank. Native WSI-FiVE trains against a fold-local answer bank and evaluates against evaluation_prompt_path; label_dict still fixes that bank's class order. Keep diagnosis names and label order aligned even when a method reads an explicit bank.

HiVE-MIL hierarchy contract

HiVE-MIL configurations bind two CONCH v1 feature columns explicitly:

method: hive_mil
feature_resolutions: {low: 5x, high: 20x}
feature_path_column_l: feature__conch_v1_5x
feature_path_column_s: feature__conch_v1_20x
feature_dim: 512
feature_space_id: hf:MahmoodLab/conch
hierarchy_geometry: per_slide_hdf5
max_children: 16
text_prompt_path: text_prompts/hive_mil/tcga_nsclc.json
upstream_commit: fa5ccec1a99db510e9add85b318e6241acb1aecd

The two HDF5 files must expose aligned features and coords datasets. Each pair must declare one shared level-0 coordinate frame, 5x/20x targets, and level-0 spans consistent with its own source magnification. For example, a 512-pixel tile spans 2048/512 level-0 pixels on a 20x scan and 4096/1024 on a 40x scan. The loader derives the parent span per slide, requires an exact 4:1 linear ratio (the released 4x4 child grid), groups 20x rows in stored order, and zero-pads to 16. It rejects an overflow, frame mismatch, inconsistent magnification/span metadata, or feature-width mismatch. The prompt JSON must contain the same keyed classes as label_dict, with exactly four ordered coarse descriptions followed by twelve fine descriptions per class. text_prompt_file_sha256 and upstream_commit make both assets auditable.

This hierarchy is compiled from local Trident coordinates rather than loaded from HiVE-MIL's preprocessed archive, so generated runs correctly report upstream_fidelity: partial even though the model code and GPT-4o prompt text come from the pinned upstream release.

MI-VisionShot training-free contract

MI-VisionShot is registered for two TCGA-RCC/PLIP conditions that make an upstream paper/code conflict explicit:

method: mi_visionshot
training_mode: nonparametric_prototypes
feature_resolutions: {bag: 20x}
feature_path_column: feature__plip_20x
feature_dim: 768
feature_space_id: hf:vinid/plip#vision-preprojection
feature_projection: native_visual_projection
prompt_feature_space_id: hf:vinid/plip
top_k: 200
support_aggregation: label_guided_topk
inference_aggregation: normalized_bgap
mi_visionshot_recipe: released_code_unnormalized
patch_similarity_normalization: none
epochs: 0
early_stopping: false

The cached patch rows are PLIP's 768-dimensional vision-transformer output. The adapter applies the same checkpoint's frozen visual projection to restore the 512-dimensional paired image/text space. For each labeled support slide, it ranks projected patches against that slide's known class prompt, averages the top 200, L2-normalizes the slide vector, and averages those vectors into a normalized class prototype. Validation and test labels never enter selection: inference averages every projected patch, normalizes the BGAP vector, and compares it with the prototypes. This is the train/test distinction stated by paper Eqs. 2.3--2.5.

The base mi_visionshot experiment preserves released main.py and get_visual_mbeddings: projected patch rows are not normalized before ranking or pooling. The paper, however, explicitly defines the patch feature in Eq. 2.2 as L2-normalized. The separately named mi_visionshot_paper_l2 experiment sets mi_visionshot_recipe: paper_eq2_2_l2 and patch_similarity_normalization: l2; it normalizes every projected patch before support similarity/top-200 pooling and before label-free inference BGAP. The doctor rejects a recipe/normalization mismatch, and results from these two conditions must not be merged.

The three prompt strings are unchanged from upstream and are keyed into benchmark order by text_prompts/mi_visionshot/tcga_rcc.json. Generated configs classify this locally constructed keyed container as derived and pin the prompt hash, source commit, and paper DOI. Upstream declares no software license, so PGVL-Gym contains a clean equation-level implementation, not copied source.

Report this condition as partial rather than as a numerical reproduction. The paper uses 923 RCC slides, 256-pixel 20x patches, and five random few-shot repetitions without a validation split. The common benchmark uses 939 current slides, 224-pixel 20x cached bags, frozen patient-level folds, and a separate validation partition. The paper's top-200 balanced accuracies are 0.762±0.014 (4-shot), 0.783±0.010 (8-shot), and 0.800±0.013 (16-shot); they are reference values, not acceptance thresholds for the different PGVL protocol.

Libra-MIL dual-prototype contract

Libra-MIL is registered for its native TCGA-RCC/CONCH condition:

method: libra_mil
feature_resolutions: {bag: 20x}
feature_path_column: feature__conch_v1_20x
feature_dim: 512
feature_space_id: hf:MahmoodLab/conch
patch_geometry: 20x_512px_0px_overlap
num_instance_prompts: 46
num_visual_prototypes: 10
num_heads: 8
ot_epsilon: 0.05
ot_iterations: 20
optimizer: adamw
lr: 0.0001
lr_scheduler: cosine_per_update
warmup_steps: 100
epochs: 80
early_stopping: true
es_patience: 15

The 46 released instance descriptions initialize learned text prototypes; ten learned visual prototypes form the second modality. Libra-MIL computes both patch-to-prototype cosine maps, aligns their prototype marginals with 20 Sinkhorn iterations, and uses the fused score to reweight the bag. The three released high-resolution RCC descriptions then query that bag by cross attention and produce logits in benchmark CCRCC/PRCC/CHRCC order.

Both prompt files retain upstream wording. Their repository provenance is derived solely because the JSON gains a final newline and the CSV normalizes CRLF to LF; original and repository hashes are recorded. Upstream has no software license, so the model is a clean paper-equation implementation. The paper specifies 80 epochs and patience 15, while released main.py defaults to 20 epochs and contains no early-stop loop. Generated configs follow the paper for that conflict and retain the released AdamW cosine schedule with 100 warm-up updates. Results remain partial: PGVL-Gym uses 939 current slides and shared patient-disjoint 4/8/16/32-shot folds, versus the paper's 925 slides and 1/4/16-shot folds. The paper's RCC 4-shot reference is 91.4±3.2 ACC, 98.2±3.1 AUC, and 88.5±5.3 macro F1.

DyKo paired knowledge contract

DyKo is registered on TCGA-NSCLC and TCGA-RCC with 768-wide CONCH-v1.5 vision-preprojection bags, the exact TITAN runtime prompt tower, and the released 1,000×768 concept tensor for each task. The cached vision producer and runtime text encoder deliberately have different feature-space identifiers: feature_space_id validates the patch boundary while prompt_feature_space_id validates the loaded TITAN checkpoint. The doctor and runtime contract require both. Configs preserve 16 learned context tokens, 10 visual prototypes, per-prototype top-10 concept retrieval, temperature 0.1, and weight-1 structural consistency. Deterministic PyTorch K-means replaces FAISS and cached tiles are 20x/512px rather than the paper's 20x/448px, so the condition is partial. RCC remains launch-gated until its current 935/939 CONCH-v1.5 coverage is complete.

MGPATH released PLIP-only contract

MGPATH is registered on TCGA-BRCA and TCGA-NSCLC with coordinate-bearing PLIP 5x/20x bags. Each four-row CSV is positional: low-resolution class rows come first, followed by high-resolution class rows. The runtime learns four 16-token prompt views, applies the matching frozen PLIP visual projection to the 768-wide caches, constructs four-neighbour graphs, learns 64 image centers, and evaluates the two scales through epsilon-0.1 Sinkhorn transport. This is the released PLIP-only branch without spatial augmentation, not the paper's primary PLIP-G/Prov-GigaPath condition, and is therefore partial.

HIPSS cached hierarchy contract

HIPSS is registered on CAMELYON16, TCGA-NSCLC, and UBC-OCEAN. The loader groups coordinate-bearing CONCH patches into deterministic 4096-level0 regions and emits a padded region mask. Each class's WSI and region descriptions are tokenized separately, concatenated, and encoded as one joint class embedding. The clean runtime applies SSF after attention normalization, MLP normalization, the MLP expansion, and the MLP projection in each selected frozen CONCH text block. With two blocks it has 284,419 trainable parameters; with eight it has 348,931, exactly matching the paper. For binary tasks, class 1 guides both hierarchy levels; multiclass tasks use the mean class embedding, following the paper rather than the released source's unconditional mean.

Upstream states that ChatGPT-4o authored its descriptions but releases empty literals and only two prompt slots; PGVL-Gym therefore supplies complete openai:gpt-5.6 replacement banks and records that generator per asset. The conditions remain partial: CAMELYON16 and NSCLC use cached 20x patches rather than the paper's dense 40x/256px instances, while UBC-OCEAN uses matching 20x/256px coordinates but retains only tissue-selected patches.

Reproducibility fields

Every comparable generated run records at least:

• shots, seed, k_start, k_end, and split_dir;
• n_classes, classnames, and label_dict;
• method/backbone identities and weight locations;
• feature roles, dimensions, spaces, and resolutions;
• prompt source and provenance;
• optimizer, scheduler, epoch, and early-stopping settings;
• the experiment-specific results directory.

Do not edit one generated YAML in isolation for a benchmark change. Update the protocol and regenerate the matrix so validation and provenance reports remain synchronized.

Preflight coverage policy

Run configs require every manifest row to have every referenced feature file. Preflight checks non-empty files and, for multi-input methods, the intersection of rows across all required feature columns. This strict default prevents two methods from reporting results over different accidental subsets of a cohort.

An intentionally partial exploratory run must state its minimum acceptable coverage explicitly as a fraction:

min_feature_coverage: 0.95

Such a run emits a coverage warning and should not be mixed with complete-cohort benchmark results. A zero-file source and a zero-row joint intersection remain fatal regardless of the configured threshold.