docs(quickadapter): clarify helper contracts and comments

diff --git a/quickadapter/.basedpyright/diagnostics.json b/quickadapter/.basedpyright/diagnostics.json
index bfd642f4206cb729f50b17abfc80e99abc3ff02f..87a578ed7a41e51f15eb6f72191f387908f75a4b 100644 (file)
--- a/quickadapter/.basedpyright/diagnostics.json
+++ b/quickadapter/.basedpyright/diagnostics.json
@@ -1993,343 +1993,343 @@
     },
     {
       "endCharacter": 55,
-      "endLine": 3638,
+      "endLine": 3637,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "\"rolling\" is not a known attribute of \"None\"",
       "rule": "reportOptionalMemberAccess",
       "severity": "error",
       "startCharacter": 48,
-      "startLine": 3638
+      "startLine": 3637
     },
     {
       "endCharacter": 38,
-      "endLine": 3663,
+      "endLine": 3662,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "\"rolling\" is not a known attribute of \"None\"",
       "rule": "reportOptionalMemberAccess",
       "severity": "error",
       "startCharacter": 31,
-      "startLine": 3663
+      "startLine": 3662
     },
     {
       "endCharacter": 55,
-      "endLine": 3689,
+      "endLine": 3688,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "\"rolling\" is not a known attribute of \"None\"",
       "rule": "reportOptionalMemberAccess",
       "severity": "error",
       "startCharacter": 48,
-      "startLine": 3689
+      "startLine": 3688
     },
     {
       "endCharacter": 56,
-      "endLine": 3690,
+      "endLine": 3689,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "\"rolling\" is not a known attribute of \"None\"",
       "rule": "reportOptionalMemberAccess",
       "severity": "error",
       "startCharacter": 49,
-      "startLine": 3690
+      "startLine": 3689
     },
     {
       "endCharacter": 33,
-      "endLine": 3762,
+      "endLine": 3761,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Argument of type \"Series[Any] | NDArray[floating[Any]]\" cannot be assigned to parameter \"series\" of type \"Series[Any]\" in function \"calculate_zero_lag\"\n  Type \"Series[Any] | NDArray[floating[Any]]\" is not assignable to type \"Series[Any]\"\n    \"ndarray[_AnyShape, dtype[floating[Any]]]\" is not assignable to \"Series[Any]\"",
       "rule": "reportArgumentType",
       "severity": "error",
       "startCharacter": 27,
-      "startLine": 3762
+      "startLine": 3761
     },
     {
       "endCharacter": 69,
-      "endLine": 3762,
+      "endLine": 3761,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Expected 1 more positional argument",
       "rule": "reportCallIssue",
       "severity": "error",
       "startCharacter": 59,
-      "startLine": 3762
+      "startLine": 3761
     },
     {
       "endCharacter": 40,
-      "endLine": 3817,
+      "endLine": 3816,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Argument of type \"Series[Any] | None\" cannot be assigned to parameter \"series\" of type \"Series[Any]\" in function \"calculate_zero_lag\"\n  Type \"Series[Any] | None\" is not assignable to type \"Series[Any]\"\n    \"None\" is not assignable to \"Series[Any]\"",
       "rule": "reportArgumentType",
       "severity": "error",
       "startCharacter": 35,
-      "startLine": 3817
+      "startLine": 3816
     },
     {
       "endCharacter": 38,
-      "endLine": 3818,
+      "endLine": 3817,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Argument of type \"Series[Any] | None\" cannot be assigned to parameter \"series\" of type \"Series[Any]\" in function \"calculate_zero_lag\"\n  Type \"Series[Any] | None\" is not assignable to type \"Series[Any]\"\n    \"None\" is not assignable to \"Series[Any]\"",
       "rule": "reportArgumentType",
       "severity": "error",
       "startCharacter": 34,
-      "startLine": 3818
+      "startLine": 3817
     },
     {
       "endCharacter": 42,
-      "endLine": 3819,
+      "endLine": 3818,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Argument of type \"Series[Any] | None\" cannot be assigned to parameter \"series\" of type \"Series[Any]\" in function \"calculate_zero_lag\"\n  Type \"Series[Any] | None\" is not assignable to type \"Series[Any]\"\n    \"None\" is not assignable to \"Series[Any]\"",
       "rule": "reportArgumentType",
       "severity": "error",
       "startCharacter": 36,
-      "startLine": 3819
+      "startLine": 3818
     },
     {
       "endCharacter": 45,
-      "endLine": 3821,
+      "endLine": 3820,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "\"index\" is not a known attribute of \"None\"",
       "rule": "reportOptionalMemberAccess",
       "severity": "error",
       "startCharacter": 40,
-      "startLine": 3821
+      "startLine": 3820
     },
     {
       "endCharacter": 33,
-      "endLine": 3823,
+      "endLine": 3822,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "\"iloc\" is not a known attribute of \"None\"",
       "rule": "reportOptionalMemberAccess",
       "severity": "error",
       "startCharacter": 29,
-      "startLine": 3823
+      "startLine": 3822
     },
     {
       "endCharacter": 31,
-      "endLine": 3824,
+      "endLine": 3823,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "\"iloc\" is not a known attribute of \"None\"",
       "rule": "reportOptionalMemberAccess",
       "severity": "error",
       "startCharacter": 27,
-      "startLine": 3824
+      "startLine": 3823
     },
     {
       "endCharacter": 48,
-      "endLine": 3829,
+      "endLine": 3828,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "\"index\" is not a known attribute of \"None\"",
       "rule": "reportOptionalMemberAccess",
       "severity": "error",
       "startCharacter": 43,
-      "startLine": 3829
+      "startLine": 3828
     },
     {
       "endCharacter": 40,
-      "endLine": 3830,
+      "endLine": 3829,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "\"iloc\" is not a known attribute of \"None\"",
       "rule": "reportOptionalMemberAccess",
       "severity": "error",
       "startCharacter": 36,
-      "startLine": 3830
+      "startLine": 3829
     },
     {
       "endCharacter": 59,
-      "endLine": 3832,
+      "endLine": 3831,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Cannot access attribute \"iloc\" for class \"NDArray[Any]\"\n  Attribute \"iloc\" is unknown",
       "rule": "reportAttributeAccessIssue",
       "severity": "error",
       "startCharacter": 55,
-      "startLine": 3832
+      "startLine": 3831
     },
     {
       "endCharacter": 34,
-      "endLine": 3834,
+      "endLine": 3833,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Cannot access attribute \"iloc\" for class \"NDArray[Any]\"\n  Attribute \"iloc\" is unknown",
       "rule": "reportAttributeAccessIssue",
       "severity": "error",
       "startCharacter": 30,
-      "startLine": 3834
+      "startLine": 3833
     },
     {
       "endCharacter": 51,
-      "endLine": 3834,
+      "endLine": 3833,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "\"iloc\" is not a known attribute of \"None\"",
       "rule": "reportOptionalMemberAccess",
       "severity": "error",
       "startCharacter": 47,
-      "startLine": 3834
+      "startLine": 3833
     },
     {
       "endCharacter": 72,
-      "endLine": 3834,
+      "endLine": 3833,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Cannot access attribute \"iloc\" for class \"NDArray[Any]\"\n  Attribute \"iloc\" is unknown",
       "rule": "reportAttributeAccessIssue",
       "severity": "error",
       "startCharacter": 68,
-      "startLine": 3834
+      "startLine": 3833
     },
     {
       "endCharacter": 40,
-      "endLine": 3901,
+      "endLine": 3900,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Type \"(Series[Any] | NDArray[floating[Any]], int) -> (Series[Any] | NDArray[floating[Any]])\" is not assignable to declared type \"(series: Unknown, timeperiod: Unknown) -> Series[Any]\"\n  Type \"(Series[Any] | NDArray[floating[Any]], int) -> (Series[Any] | NDArray[floating[Any]])\" is not assignable to type \"(series: Unknown, timeperiod: Unknown) -> Series[Any]\"\n    Missing keyword parameter \"series\"\n    Missing keyword parameter \"timeperiod\"\n      Position-only parameter mismatch; parameter \"series\" is not position-only\n      Position-only parameter mismatch; parameter \"timeperiod\" is not position-only\n      Position-only parameter mismatch; expected 2 but received 0\n      Function return type \"Series[Any] | NDArray[floating[Any]]\" is incompatible with type \"Series[Any]\"\n        Type \"Series[Any] | NDArray[floating[Any]]\" is not assignable to type \"Series[Any]\"\n  ...",
       "rule": "reportAssignmentType",
       "severity": "error",
       "startCharacter": 20,
-      "startLine": 3901
+      "startLine": 3900
     },
     {
       "endCharacter": 33,
-      "endLine": 3903,
+      "endLine": 3902,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Type \"(Series[Any] | NDArray[floating[Any]], int) -> (Series[Any] | NDArray[floating[Any]])\" is not assignable to declared type \"(series: Unknown, timeperiod: Unknown) -> Series[Any]\"\n  Type \"(Series[Any] | NDArray[floating[Any]], int) -> (Series[Any] | NDArray[floating[Any]])\" is not assignable to type \"(series: Unknown, timeperiod: Unknown) -> Series[Any]\"\n    Missing keyword parameter \"series\"\n    Missing keyword parameter \"timeperiod\"\n      Position-only parameter mismatch; parameter \"series\" is not position-only\n      Position-only parameter mismatch; parameter \"timeperiod\" is not position-only\n      Position-only parameter mismatch; expected 2 but received 0\n      Function return type \"Series[Any] | NDArray[floating[Any]]\" is incompatible with type \"Series[Any]\"\n        Type \"Series[Any] | NDArray[floating[Any]]\" is not assignable to type \"Series[Any]\"\n  ...",
       "rule": "reportAssignmentType",
       "severity": "error",
       "startCharacter": 16,
-      "startLine": 3903
+      "startLine": 3902
     },
     {
       "endCharacter": 35,
-      "endLine": 3949,
+      "endLine": 3948,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "\"to_numpy\" is not a known attribute of \"None\"",
       "rule": "reportOptionalMemberAccess",
       "severity": "error",
       "startCharacter": 27,
-      "startLine": 3949
+      "startLine": 3948
     },
     {
       "endCharacter": 33,
-      "endLine": 3950,
+      "endLine": 3949,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "\"to_numpy\" is not a known attribute of \"None\"",
       "rule": "reportOptionalMemberAccess",
       "severity": "error",
       "startCharacter": 25,
-      "startLine": 3950
+      "startLine": 3949
     },
     {
       "endCharacter": 37,
-      "endLine": 4062,
+      "endLine": 4061,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "\"to_numpy\" is not a known attribute of \"None\"",
       "rule": "reportOptionalMemberAccess",
       "severity": "error",
       "startCharacter": 29,
-      "startLine": 4062
+      "startLine": 4061
     },
     {
       "endCharacter": 35,
-      "endLine": 4063,
+      "endLine": 4062,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "\"to_numpy\" is not a known attribute of \"None\"",
       "rule": "reportOptionalMemberAccess",
       "severity": "error",
       "startCharacter": 27,
-      "startLine": 4063
+      "startLine": 4062
     },
     {
       "endCharacter": 33,
-      "endLine": 4064,
+      "endLine": 4063,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "\"to_numpy\" is not a known attribute of \"None\"",
       "rule": "reportOptionalMemberAccess",
       "severity": "error",
       "startCharacter": 25,
-      "startLine": 4064
+      "startLine": 4063
     },
     {
       "endCharacter": 39,
-      "endLine": 4084,
+      "endLine": 4083,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "\"to_numpy\" is not a known attribute of \"None\"",
       "rule": "reportOptionalMemberAccess",
       "severity": "error",
       "startCharacter": 31,
-      "startLine": 4084
+      "startLine": 4083
     },
     {
       "endCharacter": 92,
-      "endLine": 4443,
+      "endLine": 4442,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Type \"bool_ | bool\" is not assignable to return type \"bool\"\n  Type \"bool_ | bool\" is not assignable to type \"bool\"\n    \"numpy.bool[builtins.bool]\" is not assignable to \"bool\"",
       "rule": "reportReturnType",
       "severity": "error",
       "startCharacter": 15,
-      "startLine": 4443
+      "startLine": 4442
     },
     {
       "endCharacter": 85,
-      "endLine": 4844,
+      "endLine": 4843,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Argument of type \"XGBoostPruningCallback\" cannot be assigned to parameter \"object\" of type \"RegressorCallback\" in function \"append\"\n  Type \"XGBoostPruningCallback\" is not assignable to type \"RegressorCallback\"\n    Type \"XGBoostPruningCallback\" is not assignable to type \"(...) -> Any\"\n    \"XGBoostPruningCallback\" is not assignable to \"TrainingCallback\"",
       "rule": "reportArgumentType",
       "severity": "error",
       "startCharacter": 16,
-      "startLine": 4844
+      "startLine": 4843
     },
     {
       "endCharacter": 29,
-      "endLine": 4887,
+      "endLine": 4886,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Argument of type \"list[tuple[DataFrame, DataFrame]] | None\" cannot be assigned to parameter \"eval_set\" of type \"List[_LGBM_ScikitValidSet] | None\" in function \"fit\"\n  Type \"list[tuple[DataFrame, DataFrame]] | None\" is not assignable to type \"List[_LGBM_ScikitValidSet] | None\"\n    Type \"list[tuple[DataFrame, DataFrame]]\" is not assignable to type \"List[_LGBM_ScikitValidSet] | None\"\n      \"list[tuple[DataFrame, DataFrame]]\" is not assignable to \"List[_LGBM_ScikitValidSet]\"\n        Type parameter \"_T@list\" is invariant, but \"tuple[DataFrame, DataFrame]\" is not the same as \"_LGBM_ScikitValidSet\"\n        Consider switching from \"list\" to \"Sequence\" which is covariant\n      \"list[tuple[DataFrame, DataFrame]]\" is not assignable to \"None\"",
       "rule": "reportArgumentType",
       "severity": "error",
       "startCharacter": 21,
-      "startLine": 4887
+      "startLine": 4886
     },
     {
       "endCharacter": 43,
-      "endLine": 4888,
+      "endLine": 4887,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Argument of type \"list[NDArray[floating[Any]]] | None\" cannot be assigned to parameter \"eval_sample_weight\" of type \"List[_LGBM_WeightType] | None\" in function \"fit\"\n  Type \"list[NDArray[floating[Any]]] | None\" is not assignable to type \"List[_LGBM_WeightType] | None\"\n    Type \"list[NDArray[floating[Any]]]\" is not assignable to type \"List[_LGBM_WeightType] | None\"\n      \"list[NDArray[floating[Any]]]\" is not assignable to \"List[_LGBM_WeightType]\"\n        Type parameter \"_T@list\" is invariant, but \"NDArray[floating[Any]]\" is not the same as \"_LGBM_WeightType\"\n        Consider switching from \"list\" to \"Sequence\" which is covariant\n      \"list[NDArray[floating[Any]]]\" is not assignable to \"None\"",
       "rule": "reportArgumentType",
       "severity": "error",
       "startCharacter": 31,
-      "startLine": 4888
+      "startLine": 4887
     },
     {
       "endCharacter": 62,
-      "endLine": 4891,
+      "endLine": 4890,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Argument of type \"list[RegressorCallback] | None\" cannot be assigned to parameter \"callbacks\" of type \"List[(...) -> Unknown] | None\" in function \"fit\"\n  Type \"list[RegressorCallback] | None\" is not assignable to type \"List[(...) -> Unknown] | None\"\n    Type \"list[RegressorCallback]\" is not assignable to type \"List[(...) -> Unknown] | None\"\n      \"list[RegressorCallback]\" is not assignable to \"List[(...) -> Unknown]\"\n        Type parameter \"_T@list\" is invariant, but \"RegressorCallback\" is not the same as \"(...) -> Unknown\"\n        Consider switching from \"list\" to \"Sequence\" which is covariant\n      \"list[RegressorCallback]\" is not assignable to \"None\"",
       "rule": "reportArgumentType",
       "severity": "error",
       "startCharacter": 22,
-      "startLine": 4891
+      "startLine": 4890
     },
     {
       "endCharacter": 35,
-      "endLine": 4913,
+      "endLine": 4912,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Object of type \"None\" is not subscriptable",
       "rule": "reportOptionalSubscript",
       "severity": "error",
       "startCharacter": 27,
-      "startLine": 4913
+      "startLine": 4912
     },
     {
       "endCharacter": 35,
-      "endLine": 4959,
+      "endLine": 4958,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Object of type \"None\" is not subscriptable",
       "rule": "reportOptionalSubscript",
       "severity": "error",
       "startCharacter": 27,
-      "startLine": 4959
+      "startLine": 4958
     },
     {
       "endCharacter": 49,
-      "endLine": 5024,
+      "endLine": 5023,
       "file": "quickadapter/user_data/strategies/Utils.py",
       "message": "Argument of type \"CatBoostPruningCallback\" cannot be assigned to parameter \"object\" of type \"RegressorCallback\" in function \"append\"\n  Type \"CatBoostPruningCallback\" is not assignable to type \"RegressorCallback\"\n    Type \"CatBoostPruningCallback\" is not assignable to type \"(...) -> Any\"\n    \"CatBoostPruningCallback\" is not assignable to \"TrainingCallback\"",
       "rule": "reportArgumentType",
       "severity": "error",
       "startCharacter": 33,
-      "startLine": 5024
+      "startLine": 5023
     },
     {
       "endCharacter": 75,

diff --git a/quickadapter/user_data/strategies/Utils.py b/quickadapter/user_data/strategies/Utils.py
index d275dd2a38984856c7df2df4b7574f0d087b1c46..3542b3f35e35b7fc7e29d7f4b8c112afa867091b 100644 (file)
--- a/quickadapter/user_data/strategies/Utils.py
+++ b/quickadapter/user_data/strategies/Utils.py
@@ -1551,7 +1551,7 @@ def get_fit_live_predictions_candles(config: Any, logger: Logger) -> int:
 
 
 def normalize_fit_live_predictions_config(config: dict[str, Any], logger: Logger) -> None:
-    """Publish the canonical window without hiding an absent/invalid FreqAI section."""
+    """Normalize ``fit_live_predictions_candles`` in a nonempty FreqAI configuration."""
     freqai = config.get("freqai")
     if isinstance(freqai, dict) and freqai:
         freqai["fit_live_predictions_candles"] = get_fit_live_predictions_candles(freqai, logger)
@@ -3592,7 +3592,6 @@ def _format_collection(
 
 
 _FORMAT_STYLES: Final[tuple[Literal["dict", "params"], ...]] = ("dict", "params")
-"""Canonical formatting style domain for ``format_dict``."""
 
 
 def format_dict(
@@ -5177,10 +5176,11 @@ def _validate_optuna_label_best_params(
     missing or invalid ``selection_metadata``, missing or invalid
     ``selection_metadata.schema_version``, schema-version mismatch with
     ``_OPTUNA_LABEL_SELECTION_SCHEMA_VERSION``, missing or invalid
-    ``label_period_candles`` / ``label_natr_multiplier`` /
-    ``label_horizon_candles``, and -- when ``expected_selection_metadata``
-    is provided -- any drift between the stored and the caller's current
-    ``selection_metadata``. Every rejection emits a ``[<pair>]``-prefixed
+    ``label_period_candles`` / ``label_natr_multiplier``, and -- when
+    ``expected_selection_metadata`` is provided -- any drift between the
+    stored and the caller's current ``selection_metadata``.
+    ``label_horizon_candles`` may be absent or ``None``; otherwise it must
+    be a positive integer. Every rejection emits a ``[<pair>]``-prefixed
     warning when ``logger`` is provided.
     """
     if not isinstance(best_params, dict):
@@ -5656,7 +5656,7 @@ def get_optuna_study_model_parameters(
             "grow_policy": grow_policy,
             **(
                 {
-                    # Unlimited depth is reconstructed at the estimator boundary.
+                    # resolve_optuna_model_parameters adds max_depth=0 for lossguide.
                     "max_leaves": _optuna_suggest_int_from_range(
                         trial, "max_leaves", ranges["max_leaves"], min_val=2, log=True
                     ),