structured-eval 0.1.0__py3-none-any.whl

structured_eval/metrics/utils/number.py

@@ -0,0 +1,46 @@
+"""Lenient numeric parsing shared by the numeric field metrics.
+
+One parsing behavior for ``Numeric`` and ``NumericCloseness`` so a value is read
+the same way by both. Accepts int/float (rejecting ``bool``) and parses numeric
+strings: currency symbols, thousands separators and whitespace are stripped,
+accounting notation ``"(123)"`` is read as ``-123``, and scientific notation
+``"1e3"`` is supported. A ``"%"`` is only stripped, never interpreted
+(``"50%"`` → ``50``). US format is assumed (``,`` = thousands, ``.`` = decimal);
+anything that does not parse cleanly returns ``None``.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+# Everything that is not part of a (possibly scientific) number. Kept: digits,
+# decimal point, signs, and the exponent marker e/E, so float() parses
+# scientific notation ("1e3" → 1000.0, "1.5e-3" → 0.0015).
+_NON_NUMERIC = re.compile(r"[^0-9eE.+\-]")
+
+
+def parse_number(value: Any) -> float | None:
+    """Coerce ``value`` to a float, or ``None`` if it isn't cleanly numeric."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    if not isinstance(value, str):
+        return None
+
+    text = value.strip()
+    negative = False
+    # Accounting notation: "(123)" means -123.
+    if text.startswith("(") and text.endswith(")"):
+        text = text[1:-1]
+        negative = True
+
+    text = _NON_NUMERIC.sub("", text)
+    if text in ("", "-", ".", "-."):
+        return None
+    try:
+        number = float(text)
+    except ValueError:
+        return None
+    return -number if negative else number

structured_eval/metrics/utils/object_utils.py

@@ -0,0 +1,87 @@
+"""Verdicts for object metrics: matched fields → ``(score, threshold, weight)``.
+
+A parent object does not re-compare its children; it reads each matched child's
+already-computed representative score (``node.representative``) and pairs it with
+the bar it must clear and the weight it carries. Those triples feed
+``calculate.prf_counts``.
+
+``score_policy`` (on ``ObjectF1`` / ``ObjectAccuracy`` / …) overrides the
+criterion for a named field — a metric instance or its registered name, run on
+that child via ``MetricInvoker`` (so it works for any child kind, not only
+scalars). ``thresholds`` may be a per-field dict or a single float.
+
+``weight_mode`` (see ``calculate.WeightMode``) decides each child's weight:
+``NONE`` → ``1.0`` (plain counts), ``PROPORTIONAL`` → the child's configured
+``weight``. Missing (FN) and spurious (FP) children are weighted the same way
+via ``missing_weight`` / ``spurious_weight``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from structured_eval.metrics.base import resolve_metric
+from structured_eval.metrics.invoker import MetricInvoker
+from structured_eval.metrics.utils.calculate import WeightMode
+
+if TYPE_CHECKING:
+    from structured_eval.models.nodes.base import EvalNode
+    from structured_eval.models.nodes.object_node import ObjectNode
+
+
+def leaf_name(path: str) -> str:
+    """Last path segment without any trailing index, e.g. ``"a.b[0]"`` → ``"b"``."""
+    return path.rsplit(".", 1)[-1].split("[", 1)[0]
+
+
+def _resolve_threshold(
+    thresholds: float | dict[str, float] | None, name: str, fallback: float
+) -> float:
+    if isinstance(thresholds, dict):
+        return float(thresholds.get(name, fallback))
+    if thresholds is not None:
+        return float(thresholds)
+    return fallback
+
+
+def _weight_of(child: EvalNode, weight_mode: WeightMode) -> float:
+    return child.weight if weight_mode == WeightMode.PROPORTIONAL else 1.0
+
+
+def matched_verdicts(
+    node: ObjectNode,
+    score_policy: dict[str, Any] | None = None,
+    thresholds: float | dict[str, float] | None = None,
+    weight_mode: WeightMode = WeightMode.PROPORTIONAL,
+) -> list[tuple[float, float, float]]:
+    """``(score, threshold, weight)`` for each matched child of an object.
+
+    Each child contributes its representative score (any node type — scalars and
+    nested objects/arrays alike). ``score_policy`` overrides the criterion for a
+    named child, re-scoring it with the policy metric (any node kind).
+    """
+    out: list[tuple[float, float, float]] = []
+    for child in node.matched:
+        name = leaf_name(child.path)
+        spec = (score_policy or {}).get(name)
+        if spec is not None:
+            score = MetricInvoker(resolve_metric(spec)).scalar_on_node(child)
+        else:
+            score = child.representative
+        threshold = _resolve_threshold(thresholds, name, child.threshold)
+        out.append((score, threshold, _weight_of(child, weight_mode)))
+    return out
+
+
+def missing_weight(
+    node: ObjectNode, weight_mode: WeightMode = WeightMode.PROPORTIONAL
+) -> float:
+    """Summed weight of the object's missing (FN) children (count when uniform)."""
+    return sum(_weight_of(node.children[name], weight_mode) for name in node.missing)
+
+
+def spurious_weight(
+    node: ObjectNode, weight_mode: WeightMode = WeightMode.PROPORTIONAL
+) -> float:
+    """Summed weight of the object's spurious (FP) children (count when uniform)."""
+    return sum(_weight_of(node.children[name], weight_mode) for name in node.spurious)

structured_eval/models/__init__.py

@@ -0,0 +1,72 @@
+"""structured_eval.models — the pydantic data layer.
+
+Single home for every user-facing data model, re-exported here so callers use
+one path — ``from structured_eval.models import <X>`` — rather than reaching
+into individual submodules:
+
+- configuration: ``EvalConfig`` + the ``*FieldConfig`` family and policies;
+- input: ``Sample``, ``EvalContext``;
+- the ``EvalNode`` tree: ``EvalNode`` / ``ScalarNode`` / ``ObjectNode`` /
+  ``ArrayNode`` (+ ``ArrayMatchResult``);
+- metric values: ``MetricResult`` / ``MetricCollection``;
+- reports & scores: ``EvalReport`` / ``BatchEvalReport`` / ``ConsistencyReport``,
+  ``FieldScore`` / ``RuleResult`` / ``RegressionDiff`` / ``EvalWarning`` /
+  ``WarningType`` / ``NodeType``.
+"""
+
+from structured_eval.models.config import (
+    ArrayFieldConfig,
+    ArrayStrategy,
+    EvalConfig,
+    ExtraKeysPolicy,
+    FieldConfig,
+    ObjectFieldConfig,
+)
+from structured_eval.models.context import EvalContext
+from structured_eval.models.metric_result import MetricCollection, MetricResult
+from structured_eval.models.nodes import (
+    ArrayMatchResult,
+    ArrayNode,
+    EvalNode,
+    ObjectNode,
+    ScalarNode,
+)
+from structured_eval.models.result import (
+    BatchEvalReport,
+    ConsistencyReport,
+    EvalReport,
+    EvalWarning,
+    FieldScore,
+    NodeType,
+    RegressionDiff,
+    RuleResult,
+    WarningType,
+)
+from structured_eval.models.sample import Sample
+
+__all__ = [
+    "ArrayFieldConfig",
+    "ArrayMatchResult",
+    "ArrayNode",
+    "ArrayStrategy",
+    "BatchEvalReport",
+    "ConsistencyReport",
+    "EvalConfig",
+    "EvalContext",
+    "EvalNode",
+    "EvalReport",
+    "EvalWarning",
+    "ExtraKeysPolicy",
+    "FieldConfig",
+    "FieldScore",
+    "MetricCollection",
+    "MetricResult",
+    "NodeType",
+    "ObjectFieldConfig",
+    "ObjectNode",
+    "RegressionDiff",
+    "RuleResult",
+    "Sample",
+    "ScalarNode",
+    "WarningType",
+]

structured_eval/models/config.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# ── Defaults ──────────────────────────────────────────────────────────────────
+
+DEFAULT_FIELD_WEIGHT: float = 1.0
+
+
+# ── Enums ─────────────────────────────────────────────────────────────────────
+
+
+class ExtraKeysPolicy(StrEnum):
+    """How to treat keys present in actual but absent from expected."""
+
+    IGNORE = "ignore"  # extra keys are skipped
+    PENALIZE = "penalize"  # extra keys lower precision
+
+
+class ArrayStrategy(StrEnum):
+    """How to align actual array items with expected ones."""
+
+    BY_INDEX = "by_index"  # pair the i-th with the i-th
+    BY_KEY = "by_key"  # match on a shared unique field (see ArrayFieldConfig.params)
+    HUNGARIAN = "hungarian"  # optimal one-to-one assignment by element similarity
+
+
+# ── Field configs ───────────────────────────────────────────────────────────
+
+
+class FieldConfig(BaseModel):
+    """Configuration for a scalar (leaf) field.
+
+    In v3 comparison is a metric: ``metrics`` is the field's metric list, *added*
+    to the metrics cascading from ``EvalConfig.metrics``. ``key_metric`` names
+    which of them is the match criterion the parent object/array uses (a metric
+    instance or its registered name; ``None`` → ``ExactMatch``); ``threshold`` is
+    the bar it must clear to count as a true positive.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    metrics: list[Any] | None = (
+        None  # list[Metric]; added to the cascading config.metrics
+    )
+    key_metric: Any = None  # Metric | name str used as the parent's match criterion
+    threshold: float | None = None
+    weight: float = DEFAULT_FIELD_WEIGHT
+
+
+class ObjectFieldConfig(BaseModel):
+    """Configuration for an object (dict) field."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    fields: dict[str, AnyFieldConfig] = Field(default_factory=dict)
+    weight: float = DEFAULT_FIELD_WEIGHT
+    threshold: float | None = None
+    metrics: list[Any] | None = None
+
+
+class ArrayFieldConfig(BaseModel):
+    """Configuration for an array (list) field.
+
+    ``item`` describes the type and config of each element. ``strategy`` picks
+    the aligner; ``params`` carries that strategy's options (interpreted by the
+    aligner built in ``make_aligner``), so new strategies add no new fields here:
+
+    * ``BY_INDEX`` → ``params`` empty.
+    * ``BY_KEY`` → ``{"key": <field|None>, "key_metric": <metric|name>,
+      "threshold": <float>}``. The generalized ``BY_KEY`` subsumes value- and
+      similarity-based matching (technical_details_v3 §5).
+    * ``HUNGARIAN`` → ``{"scorer": <Scorer | dict[str, Scorer] | None>,
+      "threshold": <float>, "key": <field|None>}``. Optimal one-to-one
+      assignment; ``scorer`` as a per-field dict scores arrays of objects.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    item: FieldConfig | ObjectFieldConfig | None = None
+    strategy: ArrayStrategy = ArrayStrategy.BY_INDEX
+    params: dict[str, Any] = Field(default_factory=dict)  # strategy-specific options
+    weight: float = DEFAULT_FIELD_WEIGHT
+    threshold: float | None = None
+    metrics: list[Any] | None = None
+
+
+AnyFieldConfig = FieldConfig | ObjectFieldConfig | ArrayFieldConfig
+
+
+def weight_of(cfg: AnyFieldConfig | None) -> float:
+    """The aggregation weight a field config contributes (``1.0`` when absent)."""
+    return cfg.weight if cfg is not None else DEFAULT_FIELD_WEIGHT
+
+
+# ── Eval config ───────────────────────────────────────────────────────────────
+
+
+class EvalConfig(BaseModel):
+    """Top-level evaluation configuration.
+
+    Metrics are class instances (e.g. ``ObjectF1()``, ``SchemaValidity(...)``).
+    ``fields`` accepts canonical nested configs as well as dot-notation keys
+    (``"vendor.name"``) as syntactic sugar. ``root`` explicitly declares the
+    type of the root node; when omitted it is inferred from ``type(actual)``.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    metrics: list[Any] = Field(
+        default_factory=list
+    )  # list[Metric]; cascade by type to all nodes
+    fields: dict[str, AnyFieldConfig] = Field(default_factory=dict)
+    root: ObjectFieldConfig | ArrayFieldConfig | None = None
+    key_metric: Any = None  # Metric whose value becomes report.score
+    extra_keys: ExtraKeysPolicy = ExtraKeysPolicy.IGNORE
+
+
+ObjectFieldConfig.model_rebuild()
+ArrayFieldConfig.model_rebuild()
+EvalConfig.model_rebuild()

structured_eval/models/context.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+from structured_eval.models.config import EvalConfig  # noqa: TC001
+
+
+class EvalContext(BaseModel):
+    """The single owner of a sample's data.
+
+    Every ``EvalNode`` in the tree holds a reference to one ``EvalContext``;
+    nothing is copied. ``flat_actual`` / ``flat_expected`` are the documents
+    pre-flattened to dot-notation paths, computed once up front.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    actual: Any
+    expected: Any
+    source: str | None
+    flat_actual: dict[str, Any]
+    flat_expected: dict[str, Any]
+    config: EvalConfig

structured_eval/models/metric_result.py

@@ -0,0 +1,121 @@
+"""A metric's value: a float that also carries structured detail.
+
+``MetricResult`` is the single shape every metric value takes once it has passed
+through ``MetricRunner._apply`` — whatever a metric's ``compute`` returns (a bare
+``float``, a ``dict`` of sub-scores, a ``(value, extra)`` tuple, or a
+``MetricResult``) is normalized to it. It *is* a ``float`` (so every existing
+numeric use keeps working) and additionally exposes ``.extra`` — arbitrary
+structured detail a metric wants to surface beyond the number (offending paths,
+per-rule outcomes, an LLM judge's reasoning, …).
+
+``MetricCollection`` is the cross-field view: ``report.metrics[name]`` gathers a
+named metric's value at every node that produced it, keyed by path, with numeric
+reductions and the union of their ``extra`` payloads.
+"""
+
+from __future__ import annotations
+
+from statistics import mean
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, GetCoreSchemaHandler
+from pydantic_core import core_schema
+
+
+class MetricResult(float):
+    """A metric value: a ``float`` everywhere, plus structured ``.extra``."""
+
+    extra: dict[str, Any]
+
+    def __new__(cls, value: float, extra: dict[str, Any] | None = None) -> MetricResult:
+        obj = super().__new__(cls, value)
+        obj.extra = dict(extra) if extra else {}
+        return obj
+
+    def __repr__(self) -> str:
+        num = float.__repr__(self)
+        return (
+            f"MetricResult({num}, extra={self.extra!r})"
+            if self.extra
+            else f"MetricResult({num})"
+        )
+
+    # ── pydantic (round-trips extra: serialized as a bare float when empty,
+    #    else as ``{"value": ..., "extra": ...}``; both forms re-validate) ──
+    @classmethod
+    def _validate(cls, value: Any) -> MetricResult:
+        if isinstance(value, cls):
+            return value
+        if isinstance(value, dict):
+            return cls(value["value"], value.get("extra"))
+        return cls(value)
+
+    @staticmethod
+    def _serialize(value: MetricResult) -> Any:
+        return (
+            {"value": float(value), "extra": value.extra}
+            if value.extra
+            else float(value)
+        )
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source: Any, handler: GetCoreSchemaHandler
+    ) -> core_schema.CoreSchema:
+        return core_schema.no_info_plain_validator_function(
+            cls._validate,
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                cls._serialize
+            ),
+        )
+
+
+class MetricCollection(BaseModel):
+    """A named metric's values across the tree (``report.metrics[name]``).
+
+    ``by_path`` maps every node path that produced this metric to its
+    ``MetricResult``. Numeric reductions (``mean``/``min``/``max``) summarise the
+    whole tree; ``root()`` is the document-level value (path ``"$"``) when the
+    metric ran at the root; ``extra`` is the list of non-empty detail payloads.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    name: str
+    by_path: dict[str, MetricResult] = Field(default_factory=dict)
+
+    def values(self) -> list[MetricResult]:
+        return list(self.by_path.values())
+
+    def mean(self) -> float:
+        vals = self.values()
+        return mean(vals) if vals else 0.0
+
+    def min(self) -> float:
+        vals = self.values()
+        return min(vals) if vals else 0.0
+
+    def max(self) -> float:
+        vals = self.values()
+        return max(vals) if vals else 0.0
+
+    def root(self) -> MetricResult | None:
+        """The document-level value (path ``"$"``), or ``None`` if not at root."""
+        return self.by_path.get("$")
+
+    def representative(self) -> float:
+        """The document-level value if present, else the mean across the tree."""
+        root = self.root()
+        return float(root) if root is not None else self.mean()
+
+    @property
+    def extra(self) -> list[dict[str, Any]]:
+        """The non-empty ``extra`` payloads from each node, in path order."""
+        return [r.extra for r in self.values() if r.extra]
+
+    def extra_values(self, key: str) -> list[Any]:
+        """Flatten a list-valued ``extra[key]`` across every node's detail."""
+        out: list[Any] = []
+        for result in self.values():
+            out.extend(result.extra.get(key, []))
+        return out

structured_eval/models/nodes/__init__.py

@@ -0,0 +1,13 @@
+from structured_eval.models.nodes.array_node import ArrayMatchResult, ArrayNode
+from structured_eval.models.nodes.base import EvalNode, navigate
+from structured_eval.models.nodes.object_node import ObjectNode
+from structured_eval.models.nodes.scalar import ScalarNode
+
+__all__ = [
+    "ArrayMatchResult",
+    "ArrayNode",
+    "EvalNode",
+    "ObjectNode",
+    "ScalarNode",
+    "navigate",
+]

structured_eval/models/nodes/array_node.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from structured_eval.models.config import ArrayStrategy  # noqa: TC001
+from structured_eval.models.nodes.base import EvalNode
+
+
+class ArrayMatchResult(BaseModel):
+    """Alignment of an actual array against an expected array.
+
+    A structural breakdown only: ``matched`` are ``(expected_idx, actual_idx)``
+    pairs, ``missed`` are expected indices with no actual counterpart (FN),
+    ``spurious`` are actual indices absent from expected (FP). For precision /
+    recall / F1 use the **value-aware** array metrics (``ArrayPrecision`` /
+    ``ArrayRecall`` / ``ArrayF1``), which grade each matched element rather than
+    just counting it.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    strategy: ArrayStrategy
+    matched: list[tuple[int, int]] = Field(default_factory=list)
+    missed: list[int] = Field(default_factory=list)
+    spurious: list[int] = Field(default_factory=list)
+
+
+class ArrayNode(EvalNode):
+    """A list node. ``items`` are the per-element nodes after matching."""
+
+    match_result: ArrayMatchResult | None = None
+    items: list[EvalNode] = Field(default_factory=list)

structured_eval/models/nodes/base.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from structured_eval.models.context import EvalContext  # noqa: TC001
+from structured_eval.models.metric_result import MetricResult  # noqa: TC001
+from structured_eval.utils.paths import MISSING, navigate
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+# Re-exported for back-compat: ``navigate`` / ``MISSING`` now live in
+# ``structured_eval.utils.paths`` (a lower layer with no model dependency).
+__all__ = ["MISSING", "EvalNode", "navigate"]
+
+
+class EvalNode(BaseModel):
+    """A node in the evaluation tree.
+
+    Holds its ``path`` and a shared reference to the ``EvalContext``; data is
+    never copied — ``actual``/``expected`` are resolved lazily by navigating the
+    context's documents. ``expected_path`` defaults to ``path``; it diverges
+    only for array items aligned out of order (``expected[1]`` ↔ ``actual[0]``),
+    so each side navigates its own index. ``metric_results`` accumulates each
+    requested metric's value at this node (filled by the engine in phase 2).
+
+    ``key_metric`` is the node's *representative* metric — the single score that
+    bubbles up to a parent's aggregation (and, at the root, to ``report.score``).
+    It is computed last (its logic may depend on the node's other metrics) and
+    defaults to ``MeanScore`` (the arithmetic mean of the node's own metrics).
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    path: str
+    context: EvalContext
+    expected_path: str | None = None
+    weight: float = 1.0  # relative importance for weighted aggregation (OverallLeafScore, object metrics)
+    metrics: list[Any] = Field(
+        default_factory=list
+    )  # list[BaseMetric] resolved for this node
+    key_metric: Any = (
+        None  # BaseMetric: this node's representative score (parents read it)
+    )
+    threshold: float = 1.0  # bar the representative score must clear to count as a TP
+    metric_results: dict[str, MetricResult] = Field(default_factory=dict)
+
+    @property
+    def actual(self) -> Any:
+        value = navigate(self.context.actual, self.path)
+        return None if value is MISSING else value
+
+    @property
+    def expected(self) -> Any:
+        if self.context.expected is None:
+            return None
+        value = navigate(self.context.expected, self.expected_path or self.path)
+        return None if value is MISSING else value
+
+    @property
+    def representative(self) -> float:
+        """The node's single representative score: its ``key_metric``'s value.
+
+        Every node always carries a ``key_metric`` (the engine defaults it to
+        ``MeanScore``) and at least one metric for it to summarise, so by the
+        time anyone reads this the value exists. A parent reads its already
+        computed children's representatives to aggregate (post-order); the root's
+        is ``report.score``. Missing is a programming error, not a fallback.
+        """
+        km = self.key_metric
+        if km is None:
+            raise ValueError(f"node {self.path!r} has no key_metric")
+        value = self.metric_results.get(km.name)
+        if value is None:
+            raise ValueError(
+                f"node {self.path!r}: key_metric {km.name!r} has no computed value"
+            )
+        return float(value)
+
+    # ── traversal ──────────────────────────────────────────────────────────
+    # Children are discovered by duck-typing (``children`` on objects, ``items``
+    # on arrays) so the base node need not import its own subclasses.
+
+    def children_nodes(self) -> Iterator[EvalNode]:
+        """Yield the node's direct child nodes (none for a scalar leaf)."""
+        children = getattr(self, "children", None)
+        if isinstance(children, dict):
+            yield from children.values()
+        items = getattr(self, "items", None)
+        if isinstance(items, list):
+            yield from items
+
+    def is_leaf(self) -> bool:
+        """True for a scalar node (no object children, no array items)."""
+        return (
+            getattr(self, "children", None) is None
+            and getattr(self, "items", None) is None
+        )
+
+    def walk(self) -> Iterator[EvalNode]:
+        """Depth-first traversal yielding this node and every descendant."""
+        yield self
+        for child in self.children_nodes():
+            yield from child.walk()
+
+    def leaves(self) -> Iterator[EvalNode]:
+        """Yield every scalar (leaf) node at or beneath this node."""
+        for node in self.walk():
+            if node.is_leaf():
+                yield node

structured_eval/models/nodes/object_node.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from structured_eval.models.nodes.base import EvalNode
+
+
+class ObjectNode(EvalNode):
+    """A dict node.
+
+    ``matched`` holds child nodes present in both actual and expected.
+    ``missing`` / ``spurious`` hold keys present on only one side (FN / FP).
+    ``children`` maps every child key to its node for tree traversal.
+    """
+
+    matched: list[EvalNode] = Field(default_factory=list)
+    missing: list[str] = Field(default_factory=list)
+    spurious: list[str] = Field(default_factory=list)
+    children: dict[str, EvalNode] = Field(default_factory=dict)

structured_eval/models/nodes/scalar.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from structured_eval.models.nodes.base import EvalNode
+
+
+class ScalarNode(EvalNode):
+    """A leaf node: a single comparable value.
+
+    In v3 there is no pre-computed ``similarity`` — comparison *is* a metric.
+    The match criterion is the node's ``key_metric`` (defined on ``EvalNode``):
+    its representative score, defaulting to ``MeanScore`` over the node's field
+    metrics (a lone ``ExactMatch`` when none are configured). ``threshold`` is
+    the bar that score must clear to count as a true positive.
+    """