Move condition weight resolution into TaskSettings

zh1peng · zh1peng · commit 39ebde15d96f · 2026-03-02T15:29:05.000+08:00
diff --git a/ChangLog.md b/ChangLog.md
@@ -1,5 +1,21 @@
 # psyflow change log
 
+## 0.1.20 (2026-03-02)
+
+### Summary
+- Moved condition-weight resolution into `TaskSettings`:
+  - added `TaskSettings.resolve_condition_weights()` in `psyflow/TaskSettings.py`.
+- Removed `psyflow.utils.trials.resolve_condition_weights` and all related exports.
+- Updated runtime/template standards to use `settings.resolve_condition_weights()`:
+  - cookiecutter `main.py` and config comments now point to the `TaskSettings` method.
+- Updated contracts and task-build skill assets/checklists to standardize this policy.
+- Updated condition-weight unit tests to exercise the `TaskSettings` method directly.
+
+### Validation
+- `python -m unittest tests.test_condition_weights` passed.
+- `python -m unittest tests.test_validate` passed.
+- `python -m psyflow.validate "psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}"` passed with `FAIL=0`.
+
 ## 0.1.19 (2026-03-02)
 
 ### Summary
diff --git a/psyflow/TaskSettings.py b/psyflow/TaskSettings.py
@@ -1,6 +1,7 @@
 from dataclasses import dataclass, field
 from typing import List, Optional, Any, Dict
 from math import ceil
+import math
 import random
 import hashlib
 from datetime import datetime
@@ -40,6 +41,7 @@ class TaskSettings:
 
     # --- Trial logic ---
     conditions: List[str] = field(default_factory=list)
+    condition_weights: Any = None
     block_seed: Optional[List[int]] = None
 
     # --- Seeding strategy ---
@@ -81,6 +83,65 @@ def set_block_seed(self, seed_base: Optional[int]):
             rng = random.Random(seed_base)
             self.block_seed = [rng.randint(0, 99999) for _ in range(self.total_blocks)]
 
+    def resolve_condition_weights(self) -> list[float] | None:
+        """Resolve and validate optional condition weights.
+
+        Returns
+        -------
+        list[float] | None
+            A weight vector aligned to ``self.conditions`` when
+            ``self.condition_weights`` is configured; otherwise ``None`` to
+            indicate even/default generation.
+        """
+        raw = getattr(self, "condition_weights", None)
+        if raw is None:
+            return None
+
+        if not isinstance(self.conditions, list):
+            raise TypeError("conditions must be a list when condition_weights is provided.")
+
+        labels = [str(c) for c in self.conditions]
+        if not labels:
+            raise ValueError("conditions must be non-empty when condition_weights is provided.")
+
+        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:
+                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(raw, (list, tuple)):
+            if len(raw) != len(labels):
+                raise ValueError(
+                    "condition_weights length mismatch: expected "
+                    f"{len(labels)} for conditions {labels}, got {len(raw)}"
+                )
+            values = list(raw)
+        else:
+            raise TypeError("condition_weights must be null, list/tuple, or mapping keyed by condition label.")
+
+        weights: list[float] = []
+        for i, value in enumerate(values):
+            try:
+                w = float(value)
+            except Exception as exc:
+                raise TypeError(
+                    f"condition_weights[{i}] could not be parsed as number: {value!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
+
     def add_subinfo(self, subinfo: Dict[str, Any]):
         """
         Add subject-specific information and set seed/file names accordingly.
diff --git a/psyflow/__init__.py b/psyflow/__init__.py
@@ -53,7 +53,6 @@
     "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"),
 }
 
@@ -92,7 +91,6 @@
         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,7 +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`)
+  - optional `task.condition_weights` validation (mapping/list aligned to `task.conditions`, resolved via `TaskSettings.resolve_condition_weights()`)
   - 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
@@ -135,6 +135,7 @@ 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.
+  - task runtime should resolve/validate weights through TaskSettings.resolve_condition_weights().
   - 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.
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,7 +40,8 @@ task:
   total_trials: 24
   trial_per_block: 12
   conditions: [baseline, variant]
-  # Optional weighted condition generation; leave null for even generation.
+  # Optional weighted condition generation consumed by TaskSettings.resolve_condition_weights().
+  # 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]
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,7 +41,8 @@ task:
   total_trials: 8
   trial_per_block: 8
   conditions: [baseline, variant]
-  # Optional weighted condition generation; leave null for even generation.
+  # Optional weighted condition generation consumed by TaskSettings.resolve_condition_weights().
+  # 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]
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,7 +41,8 @@ task:
   total_trials: 8
   trial_per_block: 8
   conditions: [baseline, variant]
-  # Optional weighted condition generation; leave null for even generation.
+  # Optional weighted condition generation consumed by TaskSettings.resolve_condition_weights().
+  # 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]
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,7 +41,8 @@ task:
   total_trials: 8
   trial_per_block: 8
   conditions: [baseline, variant]
-  # Optional weighted condition generation; leave null for even generation.
+  # Optional weighted condition generation consumed by TaskSettings.resolve_condition_weights().
+  # 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]
diff --git a/psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/main.py b/psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/main.py
@@ -18,7 +18,6 @@
     initialize_triggers,
     load_config,
     parse_task_run_options,
-    resolve_condition_weights,
     runtime_context,
 )
 
@@ -92,10 +91,7 @@ def run(options: TaskRunOptions):
         instruction.wait_and_continue()
 
         all_data = []
-        condition_weights = resolve_condition_weights(
-            getattr(settings, "condition_weights", None),
-            list(getattr(settings, "conditions", [])),
-        )
+        condition_weights = settings.resolve_condition_weights()
         for block_i in range(settings.total_blocks):
             if options.mode not in ("qa", "sim"):
                 count_down(win, 3, color="black")
diff --git a/psyflow/utils/__init__.py b/psyflow/utils/__init__.py
@@ -15,7 +15,6 @@
     reset_trial_counter,
     resolve_deadline,
     resolve_trial_id,
-    resolve_condition_weights,
 )
 from .voices import list_supported_voices
 
@@ -27,7 +26,6 @@
     "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,5 +1,4 @@
 from typing import Any
-import math
 
 _SESSION_TRIAL_COUNTER = 0
 
@@ -47,70 +46,3 @@ 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/skills/task-build/SKILL.md b/skills/task-build/SKILL.md
@@ -123,6 +123,7 @@ PsyFlow-first implementation decision rules:
   - 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`.
+  - Runtime code should resolve weight policy through `TaskSettings.resolve_condition_weights()` instead of custom helper functions.
   - 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.
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 |
 |---|---|---|---|---|---|---|
-| `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. |
+| `condition_distribution` | `task.condition_weights` | `` | `paper_001` | `Condition proportion table` | `adapted` | If weighted generation is used, define explicit config weights aligned to `task.conditions` and resolve via `TaskSettings.resolve_condition_weights()`; 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
@@ -22,6 +22,7 @@ Use this file as `references/task_logic_audit.md` before coding.
 - Randomization/counterbalancing:
 - Condition weight policy:
   - If weighted generation is used, where is `task.condition_weights` defined in config?
+  - Is runtime resolution delegated to `TaskSettings.resolve_condition_weights()`?
   - If omitted/null, confirm even/default generation (or document custom generator behavior).
 - Condition generation method:
   - Built-in `BlockUnit.generate_conditions(...)` or custom generator?
diff --git a/skills/task-build/references/psyflow_task_standard_checklist.md b/skills/task-build/references/psyflow_task_standard_checklist.md
@@ -33,6 +33,7 @@ Use this checklist before running final gates.
 - `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`.
+- Runtime resolves `task.condition_weights` through `TaskSettings.resolve_condition_weights()` (no task-local duplicate parser).
 - 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.
diff --git a/tests/test_condition_weights.py b/tests/test_condition_weights.py
@@ -1,29 +1,66 @@
 import unittest
 
-from psyflow.utils.trials import resolve_condition_weights
+from psyflow.TaskSettings import TaskSettings
 
 
 class TestConditionWeights(unittest.TestCase):
     def test_resolve_from_mapping(self) -> None:
-        conditions = ["AX", "AY", "BX", "BY"]
-        raw = {"AX": 0.4, "AY": 0.1, "BX": 0.1, "BY": 0.4}
-        weights = resolve_condition_weights(raw, conditions)
+        settings = TaskSettings.from_dict(
+            {
+                "total_blocks": 1,
+                "total_trials": 4,
+                "conditions": ["AX", "AY", "BX", "BY"],
+                "condition_weights": {"AX": 0.4, "AY": 0.1, "BX": 0.1, "BY": 0.4},
+            }
+        )
+        weights = settings.resolve_condition_weights()
         self.assertEqual(weights, [0.4, 0.1, 0.1, 0.4])
 
     def test_resolve_from_list(self) -> None:
-        weights = resolve_condition_weights([1, 2, 3], ["A", "B", "C"])
+        settings = TaskSettings.from_dict(
+            {
+                "total_blocks": 1,
+                "total_trials": 3,
+                "conditions": ["A", "B", "C"],
+                "condition_weights": [1, 2, 3],
+            }
+        )
+        weights = settings.resolve_condition_weights()
         self.assertEqual(weights, [1.0, 2.0, 3.0])
 
     def test_none_returns_none(self) -> None:
-        self.assertIsNone(resolve_condition_weights(None, ["A", "B"]))
+        settings = TaskSettings.from_dict(
+            {
+                "total_blocks": 1,
+                "total_trials": 2,
+                "conditions": ["A", "B"],
+            }
+        )
+        self.assertIsNone(settings.resolve_condition_weights())
 
     def test_invalid_missing_key_raises(self) -> None:
+        settings = TaskSettings.from_dict(
+            {
+                "total_blocks": 1,
+                "total_trials": 2,
+                "conditions": ["A", "B"],
+                "condition_weights": {"A": 1.0},
+            }
+        )
         with self.assertRaises(ValueError):
-            resolve_condition_weights({"A": 1.0}, ["A", "B"])
+            settings.resolve_condition_weights()
 
     def test_invalid_non_positive_raises(self) -> None:
+        settings = TaskSettings.from_dict(
+            {
+                "total_blocks": 1,
+                "total_trials": 2,
+                "conditions": ["A", "B"],
+                "condition_weights": [1.0, 0.0],
+            }
+        )
         with self.assertRaises(ValueError):
-            resolve_condition_weights([1.0, 0.0], ["A", "B"])
+            settings.resolve_condition_weights()
 
 
 if __name__ == "__main__":

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