Skip to content

Base API

The abstract base classes support inheritance; the runtime-checkable protocols support structural pipeline components without inheritance.

BaseModel

Bases: ABC

Abstract base class for online anomaly detection models.

Online models process one observation at a time. score_one evaluates an observation against the model's current reference state; learn_one incorporates an observation into that state.

Subclasses must implement learn_one and score_one. Score ranges, warm-up behavior, and score orientation are model-specific.

learn_one abstractmethod

Python
learn_one(x: dict[str, float]) -> None

Update the model with a single data point.

Parameters:

Name Type Description Default
x dict[str, float]

A dictionary representing a single data point. The keys are feature names, and the values are the corresponding feature values.

 required

score_one abstractmethod

Python
score_one(x: dict[str, float]) -> float

Compute the anomaly score for a single data point.

Parameters:

Name Type Description Default
x dict[str, float]

A dictionary representing a single data point. The keys are feature names, and the values are the corresponding feature values.

 required

Returns:

Type Description
float

The model-specific anomaly score for the data point. Consult the
float

concrete model for its range and orientation.

BaseTransformer

Bases: ABC

Abstract base class for online transformers.

Transformers learn and transform one feature mapping at a time. A standalone transformer does not prescribe whether learning happens before or after transformation; :class:~aberrant.base.pipeline.Pipeline deliberately uses post-update transformations during learn_one.

Subclasses must implement the learn_one and transform_one methods.

learn_one abstractmethod

Python
learn_one(x: dict[str, float]) -> None

Update the transformer with a single data point.

Parameters:

Name Type Description Default
x dict[str, float]

A dictionary representing a single data point. The keys are feature names, and the values are the corresponding feature values.

 required

transform_one abstractmethod

Python
transform_one(x: dict[str, float]) -> dict[str, float]

Transform a single data point.

Parameters:

Name Type Description Default
x dict[str, float]

A dictionary representing a single data point to transform.

 required

Returns:

Type Description
dict[str, float]

A dictionary with transformed feature values.

BaseSimilaritySearchEngine

Bases: ABC

Abstract base class for similarity search engines.

This class defines the interface for engines that store observations and reduce a nearest-neighbor query to one scalar. The interface does not impose whether that scalar is a distance, dissimilarity, or similarity; callers must follow the concrete engine's contract.

Subclasses must implement the append and search methods.

append abstractmethod

Python
append(x: dict[str, float]) -> None

Add a data point to the search engine.

Parameters:

Name Type Description Default
x dict[str, float]

A dictionary representing a single data point. The keys are feature names, and the values are the corresponding feature values.

 required

search abstractmethod

Python
search(x: dict[str, float], n_neighbors: int) -> float

Search for the n nearest neighbors of a data point.

Parameters:

Name Type Description Default
x dict[str, float]

A dictionary representing the query data point.

 required
n_neighbors int

The number of nearest neighbors to find.

 required

Returns:

Type Description
float

The engine-specific scalar summary of the nearest-neighbor query.

Pipeline

Chain transformers with a transformer or model terminal.

Construction returns a :class:TransformerPipeline or :class:ModelPipeline exposing only the terminal's capability. Learning uses post-update transformations; transformation and scoring never invoke learning methods. Nested pipelines are flattened into one prefix and terminal.

first property

Python
first: TransformerProtocol

Return the transformer prefix as a composable component.

second property

Python
second: TransformerProtocol | ModelProtocol

Return the terminal component.

ends_in_transformer property

Python
ends_in_transformer: bool

Whether this pipeline can transform output and accept another stage.

learn_one

Python
learn_one(x: FeatureMap) -> None

Learn from one sample using each prefix transformer's updated state.

TransformerPipeline

Bases: Pipeline

A composable pipeline exposing transformed features.

stages property

Python
stages: tuple[TransformerProtocol, ...]

All transformer stages in execution order.

transform_one

Python
transform_one(x: FeatureMap) -> FeatureMap

Apply the learned transformer stages without calling learn_one.

ModelPipeline

Bases: Pipeline

A terminal pipeline exposing anomaly scores.

score_one

Python
score_one(x: FeatureMap) -> float

Transform and score an event without calling any stage's learn_one.

LearnerProtocol

Bases: Protocol

A component that updates itself from one feature mapping.

learn_one

Python
learn_one(x: FeatureMap) -> None

Update the component from one sample.

TransformerProtocol

Bases: LearnerProtocol, Protocol

Structural interface accepted for transformer pipeline stages.

transform_one

Python
transform_one(x: FeatureMap) -> FeatureMap

Transform one sample without updating learned state.

TransactionalLearnerProtocol

Bases: LearnerProtocol, Protocol

A learner that can restore its state when a learning pass fails.

The context remains open through downstream learning. Implementations must restore their own state when the context raises; the pipeline cannot make nontransactional components atomic.

learning_transaction

Python
learning_transaction(x: FeatureMap) -> AbstractContextManager[None]

Keep updates on success and restore prior state when the context raises.

TransactionalTransformerProtocol

Bases: TransformerProtocol, TransactionalLearnerProtocol, Protocol

A transformer with the transactional learner capability.

ModelProtocol

Bases: LearnerProtocol, Protocol

Structural interface accepted for a terminal anomaly model.

score_one

Python
score_one(x: FeatureMap) -> float

Score one sample without updating learned state.

FeatureMap module-attribute

Python
FeatureMap: TypeAlias = dict[str, float]

Readiness dataclass

Python
Readiness(ready: bool, observed: int = 0, required: int = 0, reason: str | None = None)

Whether a component has a usable learned reference, not score validity.

observed and required describe the same history unit. Readiness does not guarantee that every possible candidate satisfies the input domain.

ReadinessProtocol

Bases: Protocol

Optional capability; existing transformer/model protocols are unchanged.

readiness property

Python
readiness: Readiness

Return a detached description without changing learned state.

Exceptions

AberrantError

Bases: Exception

Base exception class for all aberrant-specific errors.

ModelNotFittedError

Python
ModelNotFittedError(message: str = 'Model has not been fitted yet.')

Bases: AberrantError

Raised when a model method is called before the model has been fitted.

TransformationError

Bases: AberrantError

Raised when a transformation operation fails.

PipelineError

Bases: AberrantError

Raised when a pipeline operation fails.

ValidationError

Bases: AberrantError

Raised when input validation fails.

ConfigurationError

Python
ConfigurationError(message: str = '', *, issues: Sequence[ConfigurationIssue] = ())

Bases: AberrantError

Raised when declarative component configuration is invalid.

issues property

Python
issues: tuple[ConfigurationIssue, ...]

Immutable diagnostics, independent of the human-readable message.

ConfigurationIssue dataclass

Python
ConfigurationIssue(code: str, loc: tuple[str | int, ...], message: str)

One configuration failure at a path relative to the submitted value.

Codes are missing_parameter, unexpected_parameter, invalid_type, invalid_value, unknown_component, missing_dependency and invalid_configuration. Locations contain object keys and array indexes.

UnknownComponentError

Python
UnknownComponentError(component_kind: str, component_id: str)

Bases: ConfigurationError

Raised when a catalog component identifier is unknown.

MissingOptionalDependencyError

Python
MissingOptionalDependencyError(component_id: str, extra: str)

Bases: ConfigurationError

Raised when a catalog component requires an unavailable optional extra.

UnsupportedFeatureError

Python
UnsupportedFeatureError(feature_name: str)

Bases: AberrantError

Raised when an unsupported feature is encountered.

IncompatibleComponentError

Python
IncompatibleComponentError(component_name: str, expected_type: str)

Bases: PipelineError

Raised when pipeline components are incompatible.

Optional PyTorch architecture base

The following object requires aberrant[dl] at runtime and is intentionally absent from from aberrant.base import *.

Architecture

Python
Architecture(device: device | None = None)

Bases: ABC, Module

Abstract base class for defining neural network architectures.

This class ensures that any neural network architecture can be plugged into online anomaly detection models. It provides a consistent interface and device handling capabilities.

Subclasses must implement the forward and input_size methods.

Initialize the architecture.

Parameters:

Name Type Description Default
device device | None

The device to run the model on. If None, uses CPU.

 None

input_size abstractmethod property

Python
input_size: int

The expected input size for the network.

Returns:

Type Description
int

Number of input features.

forward abstractmethod

Python
forward(x: Tensor) -> Tensor

Forward pass through the network.

Parameters:

Name Type Description Default
x Tensor

Input tensor.

 required

Returns:

Type Description
Tensor

Output tensor.

make_torch_generator staticmethod

Python
make_torch_generator(seed: int | None, device: device | str = 'cpu') -> Generator

Create an independently seeded, model-owned generator.