Standardize config-driven condition weight generation

zh1peng · zh1peng · commit 8c8062fca85b · 2026-03-02T15:15:16.000+08:00
diff --git a/ChangLog.md b/ChangLog.md
@@ -1,5 +1,23 @@
 # psyflow change log
 
+## 0.1.19 (2026-03-02)
+
+### Summary
+- Added framework-level condition-weight resolver:
+  - `psyflow.utils.trials.resolve_condition_weights(...)`
+  - exported via `psyflow.resolve_condition_weights` and `psyflow.utils`.
+- Standardized config/contract semantics for weighted condition generation:
+  - `task.condition_weights` is optional and validated when provided.
+  - mapping/list formats must align with `task.conditions`; positive numeric weights required.
+  - omitted/null `task.condition_weights` means even/default generation unless task code documents custom generation.
+- Updated cookiecutter template to include optional `task.condition_weights` and pass resolved weights into default condition scheduler.
+- Updated task-build skill docs/checklists/templates to enforce explicit `task.condition_weights` when weighted generation is used.
+- Added unit coverage for weight resolver behavior in `tests/test_condition_weights.py`.
+
+### Validation
+- `python -m unittest tests.test_condition_weights` passed.
+- `python -m psyflow.validate "psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}"` passed with `FAIL=0`.
+
 ## 0.1.18 (2026-03-02)
 
 ### Summary
diff --git a/psyflow/__init__.py b/psyflow/__init__.py
@@ -53,6 +53,7 @@
     "next_trial_id": ("psyflow.utils.trials", "next_trial_id"),
     "reset_trial_counter": ("psyflow.utils.trials", "reset_trial_counter"),
     "resolve_deadline": ("psyflow.utils.trials", "resolve_deadline"),
+    "resolve_condition_weights": ("psyflow.utils.trials", "resolve_condition_weights"),
     "resolve_trial_id": ("psyflow.utils.trials", "resolve_trial_id"),
 }
 
@@ -91,6 +92,7 @@
         next_trial_id as next_trial_id,
         reset_trial_counter as reset_trial_counter,
         resolve_deadline as resolve_deadline,
+        resolve_condition_weights as resolve_condition_weights,
         resolve_trial_id as resolve_trial_id,
     )
 
diff --git a/psyflow/contracts/v0.1.0/README.md b/psyflow/contracts/v0.1.0/README.md
@@ -8,6 +8,7 @@ These contracts define practical standards for building auditable psyflow/TAPS t
 - Task metadata (`taskbeacon.yaml`)
 - Config structure and explicit value/type constraints
   - mandatory/optional/recommended keys and value specs
+  - optional `task.condition_weights` validation (mapping/list aligned to `task.conditions`)
   - stimulus type standards and asset-backed path conventions
   - smoke-profile rules for `config_qa.yaml` and sim configs (shorter than base but condition-covering)
 - Runtime entrypoint pattern (`main.py`)
diff --git a/psyflow/contracts/v0.1.0/config.yaml b/psyflow/contracts/v0.1.0/config.yaml
@@ -16,6 +16,7 @@ forbidden_nested_keys:
   - sim
 optional_nested_keys:
   - controller
+  - task.condition_weights
 recommended_nested_keys:
   - task.trial_per_block
 mandatory_value_specs:
@@ -133,6 +134,8 @@ stim_asset_path_prefixes:
 notes:
   - controller is optional.
   - if controller is configured, keep implementation under src/utils.py.
+  - if task.condition_weights is defined, weighted condition generation must be explicit and aligned to task.conditions.
+  - if task.condition_weights is omitted (or null), default/even condition generation is assumed unless a custom generator is documented.
   - stimuli entries must include a valid type.
   - asset-backed stimuli (image/movie/sound) should load from assets/ paths.
   - if an asset-backed stimulus path is set dynamically in runtime code, keep a clear comment in run_trial.py.
diff --git a/psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/config/config.yaml b/psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/config/config.yaml
@@ -40,6 +40,9 @@ task:
   total_trials: 24
   trial_per_block: 12
   conditions: [baseline, variant]
+  # Optional weighted condition generation; leave null for even generation.
+  # Use either a mapping by condition label or a list aligned to task.conditions.
+  condition_weights: null
   key_list: [space]
   correct_key: space
   seed_mode: same_across_sub
diff --git a/psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/config/config_qa.yaml b/psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/config/config_qa.yaml
@@ -41,6 +41,9 @@ task:
   total_trials: 8
   trial_per_block: 8
   conditions: [baseline, variant]
+  # Optional weighted condition generation; leave null for even generation.
+  # Use either a mapping by condition label or a list aligned to task.conditions.
+  condition_weights: null
   key_list: [space]
   correct_key: space
   seed_mode: same_across_sub
diff --git a/psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/config/config_sampler_sim.yaml b/psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/config/config_sampler_sim.yaml
@@ -41,6 +41,9 @@ task:
   total_trials: 8
   trial_per_block: 8
   conditions: [baseline, variant]
+  # Optional weighted condition generation; leave null for even generation.
+  # Use either a mapping by condition label or a list aligned to task.conditions.
+  condition_weights: null
   key_list: [space]
   correct_key: space
   seed_mode: same_across_sub
diff --git a/psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/config/config_scripted_sim.yaml b/psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/config/config_scripted_sim.yaml
@@ -41,6 +41,9 @@ task:
   total_trials: 8
   trial_per_block: 8
   conditions: [baseline, variant]
+  # Optional weighted condition generation; leave null for even generation.
+  # Use either a mapping by condition label or a list aligned to task.conditions.
+  condition_weights: null
   key_list: [space]
   correct_key: space
   seed_mode: same_across_sub
diff --git a/psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/main.py b/psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/main.py
@@ -18,6 +18,7 @@
     initialize_triggers,
     load_config,
     parse_task_run_options,
+    resolve_condition_weights,
     runtime_context,
 )
 
@@ -91,6 +92,10 @@ def run(options: TaskRunOptions):
         instruction.wait_and_continue()
 
         all_data = []
+        condition_weights = resolve_condition_weights(
+            getattr(settings, "condition_weights", None),
+            list(getattr(settings, "conditions", [])),
+        )
         for block_i in range(settings.total_blocks):
             if options.mode not in ("qa", "sim"):
                 count_down(win, 3, color="black")
@@ -99,6 +104,7 @@ def run(options: TaskRunOptions):
                 block_idx=block_i,
                 n_trials=int(settings.trials_per_block),
                 conditions=list(getattr(settings, "conditions", [])),
+                condition_weights=condition_weights,
             )
 
             block = (
diff --git a/psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/src/utils.py b/psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/src/utils.py
@@ -30,16 +30,42 @@ def from_dict(cls, config: dict[str, Any] | None) -> "Controller":
         merged = {key: raw.get(key, default) for key, default in defaults.items()}
         return cls(**merged)
 
-    def prepare_block(self, *, block_idx: int, n_trials: int, conditions: list[str] | None) -> list[str]:
+    def prepare_block(
+        self,
+        *,
+        block_idx: int,
+        n_trials: int,
+        conditions: list[str] | None,
+        condition_weights: list[float] | None = None,
+    ) -> list[str]:
         labels = [str(c) for c in (conditions or []) if str(c).strip()]
         if not labels:
             labels = ["default"]
 
         trial_count = max(1, int(n_trials))
-        schedule = [labels[i % len(labels)] for i in range(trial_count)]
+        rng = random.Random(self.seed + int(block_idx) * 1009)
+
+        if condition_weights is None:
+            schedule = [labels[i % len(labels)] for i in range(trial_count)]
+        else:
+            if len(condition_weights) != len(labels):
+                raise ValueError(
+                    "condition_weights length mismatch for labels "
+                    f"{labels}: expected {len(labels)}, got {len(condition_weights)}"
+                )
+            total_w = sum(float(w) for w in condition_weights)
+            raw = [trial_count * float(w) / total_w for w in condition_weights]
+            counts = [int(x) for x in raw]
+            rem = trial_count - sum(counts)
+            if rem > 0:
+                extra = rng.choices(labels, weights=condition_weights, k=rem)
+                for lbl in extra:
+                    counts[labels.index(lbl)] += 1
+            schedule = []
+            for lbl, cnt in zip(labels, counts):
+                schedule.extend([lbl] * cnt)
 
         if self.shuffle and len(schedule) > 1:
-            rng = random.Random(self.seed + int(block_idx) * 1009)
             rng.shuffle(schedule)
 
         if self.enable_logging:
diff --git a/psyflow/utils/__init__.py b/psyflow/utils/__init__.py
@@ -10,7 +10,13 @@
 from .experiment import initialize_exp
 from .ports import show_ports
 from .templates import taps
-from .trials import next_trial_id, reset_trial_counter, resolve_deadline, resolve_trial_id
+from .trials import (
+    next_trial_id,
+    reset_trial_counter,
+    resolve_deadline,
+    resolve_trial_id,
+    resolve_condition_weights,
+)
 from .voices import list_supported_voices
 
 __all__ = [
@@ -21,6 +27,7 @@
     "next_trial_id",
     "reset_trial_counter",
     "resolve_deadline",
+    "resolve_condition_weights",
     "resolve_trial_id",
     "show_ports",
     "taps",
diff --git a/psyflow/utils/trials.py b/psyflow/utils/trials.py
@@ -1,4 +1,5 @@
 from typing import Any
+import math
 
 _SESSION_TRIAL_COUNTER = 0
 
@@ -46,3 +47,70 @@ def resolve_trial_id(value: Any) -> int | str | None:
             pass
             
     return str(value)
+
+
+def resolve_condition_weights(condition_weights: Any, conditions: Any) -> list[float] | None:
+    """Resolve condition weights aligned to a condition label list.
+
+    Parameters
+    ----------
+    condition_weights : Any
+        Either ``None`` (use even generation), a list/tuple aligned to
+        ``conditions`` order, or a mapping keyed by condition labels.
+    conditions : Any
+        Sequence of condition labels.
+
+    Returns
+    -------
+    list[float] | None
+        Normalized/validated weight vector aligned to ``conditions``, or
+        ``None`` when no weighted generation is requested.
+    """
+    if condition_weights is None:
+        return None
+
+    if not isinstance(conditions, (list, tuple)):
+        raise TypeError("conditions must be a list/tuple when condition_weights is provided.")
+
+    labels = [str(c) for c in list(conditions)]
+    if not labels:
+        raise ValueError("conditions must be non-empty when condition_weights is provided.")
+
+    values: list[Any]
+    if isinstance(condition_weights, dict):
+        keyed = {str(k): v for k, v in condition_weights.items()}
+        missing = [label for label in labels if label not in keyed]
+        extra = [key for key in keyed if key not in labels]
+        if missing:
+            raise ValueError(f"condition_weights missing entries for condition(s): {missing}")
+        if extra:
+            raise ValueError(f"condition_weights contains unknown condition key(s): {extra}")
+        values = [keyed[label] for label in labels]
+    elif isinstance(condition_weights, (list, tuple)):
+        if len(condition_weights) != len(labels):
+            raise ValueError(
+                "condition_weights length mismatch: expected "
+                f"{len(labels)} for conditions {labels}, got {len(condition_weights)}"
+            )
+        values = list(condition_weights)
+    else:
+        raise TypeError("condition_weights must be None, list/tuple, or mapping by condition label.")
+
+    weights: list[float] = []
+    for i, raw in enumerate(values):
+        try:
+            w = float(raw)
+        except Exception as exc:
+            raise TypeError(
+                f"condition_weights[{i}] could not be parsed as number: {raw!r}"
+            ) from exc
+        if not math.isfinite(w):
+            raise ValueError(f"condition_weights[{i}] must be finite, got {w!r}")
+        if w <= 0:
+            raise ValueError(f"condition_weights[{i}] must be > 0, got {w!r}")
+        weights.append(w)
+
+    if sum(weights) <= 0:
+        raise ValueError(f"condition_weights sum must be > 0, got {weights}")
+
+    return weights
diff --git a/psyflow/validate.py b/psyflow/validate.py
@@ -590,6 +590,68 @@ def _check_stimulus_contract(task_dir: Path, data: Any, cfg: dict[str, Any]) ->
     return fails, warns
 
 
+def _check_condition_weight_config(data: Any) -> tuple[list[str], list[str]]:
+    fails: list[str] = []
+    warns: list[str] = []
+
+    task_cfg = _nested_get(data, "task")
+    if not isinstance(task_cfg, dict):
+        return fails, warns
+
+    conditions = task_cfg.get("conditions")
+    if not isinstance(conditions, list):
+        return fails, warns
+    labels = [str(c) for c in conditions]
+    if not labels:
+        return fails, warns
+
+    if "condition_weights" not in task_cfg:
+        return fails, warns
+
+    raw = task_cfg.get("condition_weights")
+    if raw is None:
+        # Explicit null means "use even/default generation".
+        return fails, warns
+
+    values: list[Any]
+    if isinstance(raw, dict):
+        keyed = {str(k): v for k, v in raw.items()}
+        missing = [label for label in labels if label not in keyed]
+        extra = [key for key in keyed if key not in labels]
+        if missing:
+            fails.append(f"task.condition_weights missing condition key(s): {missing}")
+        if extra:
+            fails.append(f"task.condition_weights has unknown condition key(s): {extra}")
+        values = [keyed.get(label) for label in labels]
+    elif isinstance(raw, list):
+        if len(raw) != len(labels):
+            fails.append(
+                "task.condition_weights length mismatch: expected "
+                f"{len(labels)} values for conditions {labels}, got {len(raw)}"
+            )
+        values = list(raw)
+    else:
+        fails.append("task.condition_weights must be null, list, or mapping keyed by task.conditions.")
+        return fails, warns
+
+    numeric: list[float] = []
+    for i, value in enumerate(values):
+        if value is None:
+            continue
+        if not _is_number(value):
+            fails.append(f"task.condition_weights[{i}] must be numeric, got {type(value).__name__}")
+            continue
+        val = float(value)
+        if val <= 0:
+            fails.append(f"task.condition_weights[{i}] must be > 0, got {val}")
+        numeric.append(val)
+
+    if numeric and sum(numeric) <= 0:
+        fails.append("task.condition_weights sum must be > 0.")
+
+    return fails, warns
+
+
 def _check_responder_spec(task_dir: Path, data: Any, cfg: dict[str, Any]) -> tuple[list[str], list[str]]:
     fails: list[str] = []
     warns: list[str] = []
@@ -873,6 +935,10 @@ def _check_config_file(task_dir: Path, cfg: dict[str, Any]) -> ContractResult:
     fails.extend(rec_fails)
     warns.extend(rec_warns)
 
+    cw_fails, cw_warns = _check_condition_weight_config(data)
+    fails.extend(cw_fails)
+    warns.extend(cw_warns)
+
     profile_rules = cfg.get("profile_rules") if isinstance(cfg, dict) else None
     if isinstance(profile_rules, dict):
         base_file = str(profile_rules.get("base_file") or "").strip()
diff --git a/skills/task-build/SKILL.md b/skills/task-build/SKILL.md
@@ -121,6 +121,9 @@ PsyFlow-first implementation decision rules:
 - Start from the simplest PsyFlow-native implementation path, then add task-specific abstractions only when the native path cannot express the paradigm.
 - Condition generation:
   - Prefer built-in `BlockUnit.generate_conditions(...)` using config-defined condition labels/weights/order.
+  - If weighted generation is required, define `task.condition_weights` explicitly in `config/config.yaml` (and mirrored mode profiles as needed).
+  - `task.condition_weights` can be a mapping by condition label or a list aligned to `task.conditions`.
+  - If `task.condition_weights` is omitted (or `null`), assume even/default generation unless a custom generator is documented.
   - Use a custom generation function only when simple condition labels cannot represent the required trial semantics.
   - If custom generation is used, document the reason and data shape in `references/task_logic_audit.md` before coding.
 - `utils.py` scope:
diff --git a/skills/task-build/assets/templates/parameter_mapping_template.md b/skills/task-build/assets/templates/parameter_mapping_template.md
@@ -4,7 +4,7 @@
 
 | Parameter ID | Config Path | Implemented Value | Source Paper ID | Evidence (quote/figure/table) | Decision Type | Notes |
 |---|---|---|---|---|---|---|
-| `example_param` | `timing.example_param` | `0.5` | `paper_001` | `Table 1` | `direct` | Replace with task-specific mapping. |
+| `condition_distribution` | `task.condition_weights` | `` | `paper_001` | `Condition proportion table` | `adapted` | If weighted generation is used, define explicit config weights aligned to `task.conditions`; otherwise mark even/default generation. |
 
 Decision type values:
 
diff --git a/skills/task-build/assets/templates/task_logic_audit_template.md b/skills/task-build/assets/templates/task_logic_audit_template.md
@@ -20,6 +20,9 @@ Use this file as `references/task_logic_audit.md` before coding.
 - Total blocks:
 - Trials per block:
 - Randomization/counterbalancing:
+- Condition weight policy:
+  - If weighted generation is used, where is `task.condition_weights` defined in config?
+  - If omitted/null, confirm even/default generation (or document custom generator behavior).
 - Condition generation method:
   - Built-in `BlockUnit.generate_conditions(...)` or custom generator?
   - If custom generator is used, why can simple condition labels not represent the task?
diff --git a/skills/task-build/references/psyflow_task_standard_checklist.md b/skills/task-build/references/psyflow_task_standard_checklist.md
@@ -32,6 +32,8 @@ Use this checklist before running final gates.
 - Participant-facing labels/text/options are config-driven (`config/*.yaml` stimuli), not hardcoded in `src/run_trial.py`.
 - `src/run_trial.py` should not directly instantiate participant-facing text stimuli with literal text; use `stim_bank.get(...)` / `stim_bank.get_and_format(...)`.
 - If custom condition generation is used, `references/task_logic_audit.md` documents why built-in block condition generation is insufficient.
+- If weighted condition generation is used, `task.condition_weights` is explicitly defined in config and aligned with `task.conditions`.
+- If `task.condition_weights` is omitted (or `null`) and no custom generator is used, condition generation is treated as even/default by design.
 - If a task-specific controller exists, `references/task_logic_audit.md` documents why it is needed (for example adaptive timing or online control).
 - Response keys/mappings are config-driven unless the audit documents a justified runtime exception.
 - Legacy/backward-compatibility fallback branches are avoided unless the audit explicitly requires them.
diff --git a/tests/test_condition_weights.py b/tests/test_condition_weights.py

Original file line number	Diff line number	Diff line change
`@@ -53,6 +53,7 @@`
`53`	`53`	`"next_trial_id": ("psyflow.utils.trials", "next_trial_id"),`
`54`	`54`	`"reset_trial_counter": ("psyflow.utils.trials", "reset_trial_counter"),`
`55`	`55`	`"resolve_deadline": ("psyflow.utils.trials", "resolve_deadline"),`
	`56`	`+ "resolve_condition_weights": ("psyflow.utils.trials", "resolve_condition_weights"),`
`56`	`57`	`"resolve_trial_id": ("psyflow.utils.trials", "resolve_trial_id"),`
`57`	`58`	`}`
`58`	`59`
`@@ -91,6 +92,7 @@`
`91`	`92`	`next_trial_id as next_trial_id,`
`92`	`93`	`reset_trial_counter as reset_trial_counter,`
`93`	`94`	`resolve_deadline as resolve_deadline,`
	`95`	`+ resolve_condition_weights as resolve_condition_weights,`
`94`	`96`	`resolve_trial_id as resolve_trial_id,`
`95`	`97`	`)`
`96`	`98`