refactor: reduce CLI complexity and improve typing across optimize-anything

- decompose large CLI flows into semantic helper functions
- reduce worst-function and average complexity across core modules
- improve typing to eliminate remaining mypy errors
- preserve CLI behavior and public help surfaces
- verified via pytest, eval harness, and CLI smoke checks

Author: cellarius

src/optimize_anything/cli.py

@@ -3,6 +3,7 @@
 import json
 import textwrap
 from collections.abc import Mapping
+from numbers import Real
 from typing import Any
 
 
@@ -104,33 +105,24 @@ def _extract_rubric_summary(intake: Mapping[str, Any] | None) -> str:
     if not intake:
         return "No rubric summary provided."
 
-    quality_dimensions = intake.get("quality_dimensions")
-    if isinstance(quality_dimensions, list) and quality_dimensions:
-        fragments: list[str] = []
-        for item in quality_dimensions:
-            if not isinstance(item, Mapping):
-                continue
-            name = str(item.get("name", "")).strip()
-            weight = item.get("weight")
-            if not name:
-                continue
-            try:
-                fragments.append(f"{name}:{float(weight):.2f}")
-            except (TypeError, ValueError):
-                continue
-        if fragments:
-            return f"quality_dimensions={', '.join(fragments)}"
+    quality_dimension_summary = _format_quality_dimension_summary(
+        intake.get("quality_dimensions")
+    )
+    if quality_dimension_summary is not None:
+        return quality_dimension_summary
 
     for key in ("rubric_summary", "rubric_brief", "rubric"):
         value = intake.get(key)
         if value not in (None, ""):
             return _compact_text(value, max_length=240)
 
-    fragments = []
-    for key in ("criteria", "rubric_dimensions", "dimensions", "focus"):
-        value = intake.get(key)
-        if value not in (None, ""):
-            fragments.append(f"{key}={_compact_text(value, max_length=96)}")
+    fragments = _collect_rubric_fragments(
+        intake,
+        "criteria",
+        "rubric_dimensions",
+        "dimensions",
+        "focus",
+    )
 
     if fragments:
         joined = "; ".join(fragments)
@@ -141,6 +133,40 @@ def _extract_rubric_summary(intake: Mapping[str, Any] | None) -> str:
     return "No rubric summary provided."
 
 
+def _format_quality_dimension_summary(value: Any) -> str | None:
+    if not isinstance(value, list) or not value:
+        return None
+
+    fragments: list[str] = []
+    for item in value:
+        if not isinstance(item, Mapping):
+            continue
+        name = str(item.get("name", "")).strip()
+        weight = item.get("weight")
+        if not name or not isinstance(weight, (Real, str)):
+            continue
+        try:
+            fragments.append(f"{name}:{float(weight):.2f}")
+        except (TypeError, ValueError):
+            continue
+
+    if not fragments:
+        return None
+    return f"quality_dimensions={', '.join(fragments)}"
+
+
+def _collect_rubric_fragments(
+    intake: Mapping[str, Any],
+    *keys: str,
+) -> list[str]:
+    fragments: list[str] = []
+    for key in keys:
+        value = intake.get(key)
+        if value not in (None, ""):
+            fragments.append(f"{key}={_compact_text(value, max_length=96)}")
+    return fragments
+
+
 def _default_quality_dimensions() -> list[tuple[str, float]]:
     """Return default quality dimensions, sourced from intake module constants."""
     from optimize_anything.intake import DEFAULT_QUALITY_DIMENSIONS
@@ -164,8 +190,11 @@ def _extract_quality_dimensions(
         name = str(item.get("name", "")).strip()
         if not name:
             continue
+        weight = item.get("weight")
+        if not isinstance(weight, (Real, str)):
+            continue
         try:
-            weight = float(item.get("weight"))
+            weight = float(weight)
         except (TypeError, ValueError):
             continue
         dimensions.append((name, weight))

src/optimize_anything/evaluator_generator.py

@@ -157,17 +157,25 @@ def _parse_evaluator_result(result: Any, score_range: str = "unit") -> tuple[flo
     try:
         score = float(raw_score)
     except (TypeError, ValueError):
-        side_info["error"] = "Evaluator 'score' must be numeric"
-        side_info["score"] = raw_score
-        return 0.0, side_info
+        return _evaluator_score_error(side_info, raw_score, "Evaluator 'score' must be numeric")
 
     if not math.isfinite(score):
-        side_info["error"] = "Evaluator 'score' must be finite"
-        side_info["score"] = raw_score
-        return 0.0, side_info
+        return _evaluator_score_error(side_info, raw_score, "Evaluator 'score' must be finite")
 
     if score_range == "unit" and (score < 0.0 or score > 1.0):
-        side_info["error"] = "Evaluator 'score' must be between 0.0 and 1.0"
-        side_info["score"] = raw_score
-        return 0.0, side_info
+        return _evaluator_score_error(
+            side_info,
+            raw_score,
+            "Evaluator 'score' must be between 0.0 and 1.0",
+        )
     return score, side_info
+
+
+def _evaluator_score_error(
+    side_info: dict[str, Any],
+    raw_score: Any,
+    message: str,
+) -> tuple[float, dict[str, Any]]:
+    side_info["error"] = message
+    side_info["score"] = raw_score
+    return 0.0, side_info

src/optimize_anything/evaluators.py

@@ -107,38 +107,9 @@ def _normalize_quality_dimensions(value: Any) -> list[dict[str, Any]]:
     weights: list[float] = []
 
     for idx, item in enumerate(value):
-        if not isinstance(item, Mapping):
-            raise ValueError(
-                f"quality_dimensions[{idx}] must be an object with 'name' and 'weight'"
-            )
-        if "name" not in item:
-            raise ValueError(f"quality_dimensions[{idx}] missing required field 'name'")
-        if "weight" not in item:
-            raise ValueError(f"quality_dimensions[{idx}] missing required field 'weight'")
-
-        name = item["name"]
-        if not isinstance(name, str):
-            raise ValueError(f"quality_dimensions[{idx}].name must be a string")
-        normalized_name = name.strip()
-        if not normalized_name:
-            raise ValueError(
-                f"quality_dimensions[{idx}].name must be a non-empty string"
-            )
-
-        raw_weight = item["weight"]
-        if isinstance(raw_weight, bool) or not isinstance(raw_weight, Real):
-            raise ValueError(f"quality_dimensions[{idx}].weight must be numeric")
-
-        weight = float(raw_weight)
-        if not isfinite(weight):
-            raise ValueError(f"quality_dimensions[{idx}].weight must be finite")
-        if weight <= 0:
-            raise ValueError(f"quality_dimensions[{idx}].weight must be > 0")
-
+        normalized_name, weight = _normalize_quality_dimension_item(item, idx)
         if normalized_name in seen_names:
-            raise ValueError(
-                f"Duplicate quality dimension name: '{normalized_name}'"
-            )
+            raise ValueError(f"Duplicate quality dimension name: '{normalized_name}'")
         seen_names.add(normalized_name)
         names.append(normalized_name)
         weights.append(weight)
@@ -150,6 +121,39 @@ def _normalize_quality_dimensions(value: Any) -> list[dict[str, Any]]:
     ]
 
 
+def _normalize_quality_dimension_item(
+    item: Any,
+    idx: int,
+) -> tuple[str, float]:
+    if not isinstance(item, Mapping):
+        raise ValueError(
+            f"quality_dimensions[{idx}] must be an object with 'name' and 'weight'"
+        )
+    if "name" not in item:
+        raise ValueError(f"quality_dimensions[{idx}] missing required field 'name'")
+    if "weight" not in item:
+        raise ValueError(f"quality_dimensions[{idx}] missing required field 'weight'")
+
+    name = item["name"]
+    if not isinstance(name, str):
+        raise ValueError(f"quality_dimensions[{idx}].name must be a string")
+    normalized_name = name.strip()
+    if not normalized_name:
+        raise ValueError(f"quality_dimensions[{idx}].name must be a non-empty string")
+
+    raw_weight = item["weight"]
+    if isinstance(raw_weight, bool) or not isinstance(raw_weight, Real):
+        raise ValueError(f"quality_dimensions[{idx}].weight must be numeric")
+
+    weight = float(raw_weight)
+    if not isfinite(weight):
+        raise ValueError(f"quality_dimensions[{idx}].weight must be finite")
+    if weight <= 0:
+        raise ValueError(f"quality_dimensions[{idx}].weight must be > 0")
+
+    return normalized_name, weight
+
+
 def _normalize_weights(weights: list[float]) -> list[float]:
     total = sum(weights)
     scaled = [(weight / total) * 10000 for weight in weights]

src/optimize_anything/intake.py

@@ -221,14 +221,14 @@ def _parse_judge_response(
         score = _compute_weighted_score(parsed, quality_dimensions)
     else:
         raw_score = parsed.get("score")
-        try:
-            score = float(raw_score)
-        except (TypeError, ValueError):
+        coerced_score = _coerce_float(raw_score)
+        if coerced_score is None:
             return 0.0, {
                 "error": "LLM 'score' field is not numeric",
                 "raw_response": raw_content[:500],
                 **side_info,
             }
+        score = coerced_score
 
     if not math.isfinite(score):
         return 0.0, {"error": "LLM score is not finite", **side_info}
@@ -248,15 +248,21 @@ def _compute_weighted_score(
     for dim in quality_dimensions:
         dim_name = dim["name"]
         raw_value = parsed.get(dim_name)
-        try:
-            value = float(raw_value)
-        except (TypeError, ValueError):
+        value = _coerce_float(raw_value)
+        if value is None:
             value = 0.0
         value = max(0.0, min(1.0, value))
         weighted_sum += value * dim["weight"]
     return weighted_sum / total_weight
 
 
+def _coerce_float(value: Any) -> float | None:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
 ANALYZE_SYSTEM_PROMPT = """\
 You are a careful, objective evaluator and quality analyst. You will be given
 a text artifact, its current score, and the scoring objective. Your job is to
@@ -434,34 +440,39 @@ def _parse_dimensions_response(raw_content: str | None) -> list[dict[str, Any]]:
         )
 
     validated: list[dict[str, Any]] = []
-    for i, d in enumerate(raw_dims):
-        if not isinstance(d, dict):
-            continue
-        name = d.get("name")
-        if not isinstance(name, str) or not name.strip():
-            continue
-        try:
-            weight = float(d.get("weight", 0))
-        except (TypeError, ValueError):
-            weight = 0.0
-        weight = max(0.0, min(1.0, weight))
-        try:
-            dim_score = float(d.get("score", 0))
-        except (TypeError, ValueError):
-            dim_score = 0.0
-        dim_score = max(0.0, min(1.0, dim_score))
-        description = d.get("description", "")
-        if not isinstance(description, str):
-            description = str(description)
-
-        validated.append({
-            "name": name.strip(),
-            "weight": weight,
-            "score": dim_score,
-            "description": description,
-        })
+    for raw_dimension in raw_dims:
+        normalized = _normalize_dimension_entry(raw_dimension)
+        if normalized is not None:
+            validated.append(normalized)
 
     if not validated:
         raise RuntimeError("No valid dimensions found in LLM response")
 
     return validated
+
+
+def _normalize_dimension_entry(raw_dimension: Any) -> dict[str, Any] | None:
+    if not isinstance(raw_dimension, dict):
+        return None
+
+    name = raw_dimension.get("name")
+    if not isinstance(name, str):
+        return None
+    normalized_name = name.strip()
+    if not normalized_name:
+        return None
+
+    description = raw_dimension.get("description", "")
+    return {
+        "name": normalized_name,
+        "weight": _clamp_dimension_value(raw_dimension.get("weight", 0)),
+        "score": _clamp_dimension_value(raw_dimension.get("score", 0)),
+        "description": description if isinstance(description, str) else str(description),
+    }
+
+
+def _clamp_dimension_value(value: Any) -> float:
+    coerced = _coerce_float(value)
+    if coerced is None:
+        return 0.0
+    return max(0.0, min(1.0, coerced))