`nexuml.evaluation.algorithm`¶

nexuml.evaluation.algorithm ¶

Base class for post-training evaluation algorithms.

ContractError ¶

Bases: KeyError

Raised when a declared key contract cannot be satisfied at runtime.

EvalAlgorithm ¶

Bases: ABC

Base class for post-training evaluation algorithms.

Flat batch lifecycle

fit_batch(x, y) — accumulate statistics from one train batch (optional)
fit_end() — finalize fitting after all train batches
eval_batch(x, y) — process one test batch using fitted state
eval_end() — finalize evaluation after all test batches
results() — return computed metrics as a flat dict

Evaluation algorithms are consumer-only: they read from the pipeline output TensorDict and never produce new score keys. Score-producing components belong in the pipeline as PostTrainFitLayer subclasses.

fit_batch ¶

fit_batch(x: TensorDict, y: TensorDict | None) -> None

Accumulate statistics from one train batch.

fit_end ¶

fit_end() -> None

Finalize fitting after all train batches. Default: no-op.

eval_batch ¶

eval_batch(x: TensorDict, y: TensorDict | None) -> None

Score/process one test batch using fitted state.

eval_end ¶

eval_end() -> None

Finalize evaluation after all test batches.

visualize ¶

visualize(logger: Any) -> None

Produce visualizations and log them (optional).

results `abstractmethod` ¶

results() -> dict[str, float]

Return computed metrics as a flat dict.

DistanceEstimator ¶

Bases: ABC

Abstract base for streaming distance estimators.

Lifecycle

fit_batch(features, labels=None) — accumulate train statistics batch-by-batch
fit_end() — finalize (compute inverse covariance, fit GMM, etc.)
score(features, labels=None) — return per-sample anomaly scores

fit_batch `abstractmethod` ¶

fit_batch(
    features: Tensor, labels: TensorDict | None = None
) -> None

Accumulate statistics from a batch of features.

fit_end `abstractmethod` ¶

fit_end() -> None

Finalize the estimator after all batches.

score `abstractmethod` ¶

score(
    features: Tensor, labels: TensorDict | None = None
) -> torch.Tensor

Return per-sample anomaly scores (higher = more anomalous).

get_declared_tensor ¶

get_declared_tensor(
    x: TensorDict, key: str, *, algorithm: str = ""
) -> Any

Return a declared tensor key from x; raise ContractError if absent.

algorithm is included in diagnostics when provided.

Returns:

Type	Description
`Any`	The tensor stored under key.

Raises:

Type	Description
`ContractError`	If key is not present in x.

get_declared_axis ¶

get_declared_axis(
    x: TensorDict,
    y: TensorDict | None,
    axis_spec: Any,
    *,
    metadata: Any = None,
    algorithm: str = "",
) -> Any

Resolve a declared axis key from x, y, or metadata per its provenance.

Enforces EXACT provenance — no silent fallback between sources. axis_spec may be a string (shorthand, defaults source=y) or an AxisKeySpec. metadata is an optional DataFrame-like with per-sample columns.

Returns:

Type	Description
`Any`	The resolved axis value from the appropriate source.

Raises:

Type	Description
`ValueError`	If axis_spec references an unknown source.
`ContractError`	If the declared key is missing from the resolved source.

get_fit_mask ¶

get_fit_mask(
    x: TensorDict,
    y: TensorDict | None,
    fit_mask_key: str | None,
    batch_size: int,
    *,
    algorithm: str = "",
) -> torch.Tensor

Resolve fit mask to a bool tensor; returns all-True if fit_mask_key is None.

Returns:

Type	Description
`Tensor`	Bool tensor of shape `(batch_size,)`.

Raises:

Type	Description
`ContractError`	If fit_mask_key is not found in y or x.

nexuml.evaluation.algorithm¶