Base classes and registration decorators for machine learning algorithms.
This module provides the foundation for the plugin-based algorithm system. All base classes (
Classifier, Clusterer, Regressor, Associator) are defined here and integrate with the component registry (tuiml.registry).Classes
Abstract base class for all machine learning algorithms.
Provides a unified interface for model lifecycle management, including training, prediction, evaluation, persistence, REST serving, and registration with the component registry.
Constructor
__init__( self, )
Overview
This class serves as the foundation for the specialized base classes such as
Classifier and Regressor. It defines standard methods for metadata retrieval, parameter handling, and REST serving.Attributes
_is_fitted
bool
Internal flag indicating whether the model has been trained.
Notes
Subclasses MUST implement
fit and predict.See Also
Methods
get_parameter_schema
(cls) -> Dict[str, Dict[str, Any]]
get_parameter_schema
(cls) -> Dict[str, Dict[str, Any]]
Return JSON Schema for algorithm parameters.
Returns
schema
dict
Dictionary mapping parameter names to their JSON Schemas, for example:: { "n_trees": { "type": "integer", "default": 100, "minimum": 1, "maximum": 1000, "description": "Number of trees in the forest" } }
fit
(self, X: np.ndarray, y: Optional[np.ndarray]=None) -> 'Algorithm'
fit
(self, X: np.ndarray, y: Optional[np.ndarray]=None) -> 'Algorithm'
Train the algorithm on data.
Parameters
X
np.ndarray of shape (n_samples, n_features)
Training features.
y
np.ndarray of shape (n_samples,)
Training labels or target values. Optional for unsupervised algorithms.
Returns
self
Algorithm
The fitted estimator (for method chaining).
fit_predict
(self, X: np.ndarray, y: Optional[np.ndarray]=None) -> np.ndarray
fit_predict
(self, X: np.ndarray, y: Optional[np.ndarray]=None) -> np.ndarray
Fit and predict in one step (useful for clustering).
Parameters
X
np.ndarray of shape (n_samples, n_features)
Training features.
y
np.ndarray of shape (n_samples,)
Training labels or target values.
Returns
predictions
np.ndarray of shape (n_samples,)
Predictions on the training data.
score
(self, X: np.ndarray, y: np.ndarray) -> float
score
(self, X: np.ndarray, y: np.ndarray) -> float
Return the default score of the model on the given data.
Parameters
X
np.ndarray of shape (n_samples, n_features)
Test features.
y
np.ndarray of shape (n_samples,)
True labels or target values.
Returns
score
float
Accuracy for classifiers, R² for regressors.
evaluate
(self, X: np.ndarray, y: np.ndarray, metrics: Union[str, List[str]]='auto') -> Dict[str, float]
evaluate
(self, X: np.ndarray, y: np.ndarray, metrics: Union[str, List[str]]='auto') -> Dict[str, float]
Evaluate the model on test data with one or more metrics.
Parameters
X
np.ndarray of shape (n_samples, n_features)
Test features.
y
np.ndarray of shape (n_samples,)
True labels or target values.
metrics
str or list of str
= "auto"
Metric function names from
tuiml.evaluation.metrics (e.g., ["accuracy_score", "f1_score"]). "auto" selects accuracy/F1 for classifiers and MSE/R² for regressors.
Returns
results
dict
Mapping of metric names to computed values.
partial_fit
(self, X: np.ndarray, y: Optional[np.ndarray]=None, classes: Optional[np.ndarray]=None) -> 'Algorithm'
partial_fit
(self, X: np.ndarray, y: Optional[np.ndarray]=None, classes: Optional[np.ndarray]=None) -> 'Algorithm'
Incrementally fit the model on a batch of samples.
Parameters
X
np.ndarray of shape (n_samples, n_features)
Batch of training features.
y
np.ndarray of shape (n_samples,)
Batch of training labels or target values.
classes
np.ndarray
Full array of possible class labels (classifiers only). Used to populate
classes_ before all classes have been seen.
Returns
self
Algorithm
The fitted estimator (for method chaining).
get_params
(self, deep: bool=True) -> Dict[str, Any]
get_params
(self, deep: bool=True) -> Dict[str, Any]
Return the algorithm's constructor parameters.
Parameters
deep
bool
= True
Accepted for API symmetry with composite estimators, which use it to include their children's parameters. Plain algorithms have no nested components, so it makes no difference here.
Returns
params
dict
Parameter names mapped to their current values.
set_params
(self, **params) -> 'Algorithm'
set_params
(self, **params) -> 'Algorithm'
Set algorithm parameters.
Parameters
**params
dict
Parameter names mapped to their new values. Each name must be an existing attribute of the estimator.
Returns
self
Algorithm
The estimator (for method chaining).
Raises
ValueError
If a parameter name is not a valid attribute.
serve
(self, port: int=8000, host: str='127.0.0.1', model_id: Optional[str]=None, background: Optional[bool]=None)
serve
(self, port: int=8000, host: str='127.0.0.1', model_id: Optional[str]=None, background: Optional[bool]=None)
Serve this fitted model behind a REST API.
Parameters
port
int
= 8000
Port to listen on.
host
str
= "127.0.0.1"
Host to bind to.
model_id
str
Identifier for the model in the server. Defaults to the class name.
background
bool
Whether to run the server on a background thread. The default adapts to the caller:
True inside a notebook, where blocking would freeze the cell, and False in a plain script, where the process should stay up to serve requests.
Returns
dict or None
Server details (
server_id, url, endpoints) when running in the background; None when blocking.
Raises
RuntimeError
If the model is not fitted, or the server cannot start (most often because the port is already in use).
Base class for supervised classification algorithms.
Classifiers learn to assign categorical labels (classes) to instances based on training data. The default
score is accuracy.Attributes
classes_
np.ndarray
Class labels known to the classifier, when set by the subclass during
fit.
Base class for unsupervised clustering algorithms.
Clustering groups similar instances together without the need for pre-defined labels, discovering the underlying structure of the data.
Constructor
__init__( self, )
Overview
Algorithms in this category typically handle partition-based (e.g., K-Means) or hierarchical grouping.
Attributes
n_clusters_
int
The number of resulting clusters (if applicable).
labels_
np.ndarray
The labels assigned to each instance in the training set.
cluster_centers_
np.ndarray
Coordinates of the cluster centroids.
See Also
Methods
Base class for density-based clusterers.
Density-based clusterers can estimate the probability of cluster membership for each instance.
Methods
Base class for clusterers that support incremental updates.
Methods
partial_fit
(self, X: np.ndarray, y: Optional[np.ndarray]=None, classes: Optional[np.ndarray]=None) -> 'UpdateableClusterer'
partial_fit
(self, X: np.ndarray, y: Optional[np.ndarray]=None, classes: Optional[np.ndarray]=None) -> 'UpdateableClusterer'
Incrementally fit the model on a batch of samples.
Parameters
X
np.ndarray of shape (n_samples, n_features)
Batch of training data.
y
None
Ignored (unsupervised learning).
classes
None
Ignored; accepted for API symmetry with classifiers.
Returns
self
UpdateableClusterer
The updated clusterer (for method chaining).
Base class for supervised regression algorithms.
Regressors learn to predict continuous target values from training data. The default
score is R². Timeseries models also use this base class.Base class for survival analysis models.
Survival models estimate the time to an event of interest — failure, churn, relapse — where some subjects are right-censored: the event had not happened when observation stopped. Input is therefore (X, time, event) rather than (X, y), with event marking which time values are observed event times and which are censoring times.
A model predicts a risk score, where a larger value means an earlier expected event, and optionally a survival function S(t) = P(T > t).
Methods
Base class for uplift / heterogeneous-treatment-effect models.
Uplift models estimate the causal effect of a treatment on an individual: the difference between the outcome with treatment and without it. Input is therefore (X, treatment, y) rather than (X, y), with treatment a binary indicator of which group each sample belonged to.
The headline output is the individual treatment effect, or uplift, which is what decides who to treat.
See Also
Methods
Represents a set of items that appear together frequently.
Parameters
items
frozenset of int
The set of item identifiers included in the itemset.
support
float
The proportion of transactions containing this itemset: :math:`P(items)`.
count
int
= 0
The absolute frequency count of the itemset.
Represents a discovered relationship in the form $A \Rightarrow C$.
Overview
Association rules quantify how likely the consequent ($C$) is to appear given the presence of the antecedent ($A$).
Parameters
antecedent
frozenset of int
The conditional part of the rule ($A$).
consequent
frozenset of int
The predicted part of the rule ($C$).
support
float
The joint probability: :math:`P(A \cup C)`.
confidence
float
The conditional probability: :math:`P(C|A) = \frac{P(A \cup C)}{P(A)}`.
lift
float
= 1.0
The ratio of observed support to expected support if independent: :math:`\frac{P(C|A)}{P(C)}`.
leverage
float
= 0.0
The difference from independence: :math:`P(A \cup C) - P(A)P(C)`.
conviction
float
= 1.0
Implication strength: :math:`\frac{1 - P(C)}{1 - \text{confidence}}`.
jaccard
float
= 0.0
Jaccard coefficient: :math:`\frac{P(A \cup C)}{P(A) + P(C) - P(A \cup C)}`.
kulczynski
float
= 0.0
Average of the two conditional confidences :math:`P(C|A)` and :math:`P(A|C)`.
all_confidence
float
= 0.0
Minimum of the two conditional confidences.
Base class for Association Rule Mining.
Discovers interesting patterns and relationships between items in large datasets (e.g., market basket analysis).
Constructor
__init__( self, )
Theory
Mining typically involves two steps:
- Finding all Frequent Itemsets that satisfy a minimum support.
- Generating Association Rules that satisfy a minimum confidence.
Attributes
frequent_itemsets_
list of FrequentItemset
The collection of all itemsets found above the minimum support threshold.
rules_
list of AssociationRule
The collection of all generated rules.
Methods
fit
(self, X: np.ndarray, y: Optional[np.ndarray]=None) -> 'Associator'
fit
(self, X: np.ndarray, y: Optional[np.ndarray]=None) -> 'Associator'
Find frequent itemsets and generate association rules.
Parameters
X
np.ndarray or list of list of int
Transaction data, either a binary matrix of shape (n_transactions, n_items) or a list of lists of item indices.
y
None
Ignored.
Returns
self
Associator
The fitted associator (for method chaining).
get_frequent_itemsets
(self, min_size: int=1, max_size: Optional[int]=None) -> List[FrequentItemset]
get_frequent_itemsets
(self, min_size: int=1, max_size: Optional[int]=None) -> List[FrequentItemset]
Return the discovered frequent itemsets.
Parameters
min_size
int
= 1
Minimum itemset size.
max_size
int
Maximum itemset size (
None for no limit).
Returns
itemsets
list of FrequentItemset
Frequent itemsets within the requested size range.
get_rules
(self, min_confidence: Optional[float]=None, min_lift: Optional[float]=None) -> List[AssociationRule]
get_rules
(self, min_confidence: Optional[float]=None, min_lift: Optional[float]=None) -> List[AssociationRule]
Return the discovered association rules.
Parameters
min_confidence
float
Minimum confidence threshold.
min_lift
float
Minimum lift threshold.
Returns
rules
list of AssociationRule
Rules passing all requested thresholds.
Central registry for all algorithms (legacy wrapper).
Provides discovery, registration, and instantiation of algorithms.
Notes
This class now wraps the unified component registry (
tuiml.registry) for backward compatibility. New code should use the registry directly.Methods
Functions
call_metric(metric_func, y_true, y_pred)
Call a metric function, choosing macro averaging for multiclass data.
TuiML's
f1_score/precision_score/recall_score default to binary averaging, which on multiclass labels silently reports only the score of class 1. Whenever the metric accepts an average argument and the data has more than two classes, macro averaging is used instead.Parameters
metric_func
callable
A metric function from
tuiml.evaluation.metrics.
y_true
array-like of shape (n_samples,)
True labels or target values.
y_pred
array-like of shape (n_samples,)
Predicted labels or values.
Returns
float or np.ndarray
The metric value.
algorithm(type: str='classifier')
Decorator to register an algorithm with the component registry.
Parameters
type
str
= "classifier"
Algorithm type (
'classifier', 'clusterer', 'regressor', 'associator').
Returns
decorator
callable
Class decorator that registers the algorithm.
python
>>> from tuiml.base.algorithms import algorithm, Classifier
>>> @algorithm(type="classifier")
... class RandomForest(Classifier):
... passclassifier(name: Optional[str]=None, tags: Optional[List[str]]=None, version: str='1.0.0', author: Optional[str]=None)
Decorator to register a classifier with the component registry.
Parameters
name
str
Registry name. Defaults to the class name.
tags
list of str
Tags for discovery and search.
version
str
= "1.0.0"
Component version string.
author
str
Component author.
Returns
decorator
callable
Class decorator that registers the classifier.
python
>>> from tuiml.base.algorithms import classifier, Classifier
>>> @classifier(tags=["ensemble", "tree"])
... class RandomForest(Classifier):
... passclusterer(name: Optional[str]=None, tags: Optional[List[str]]=None, version: str='1.0.0', author: Optional[str]=None)
Decorator to register a clusterer with the component registry.
Parameters
name
str
Registry name. Defaults to the class name.
tags
list of str
Tags for discovery and search.
version
str
= "1.0.0"
Component version string.
author
str
Component author.
Returns
decorator
callable
Class decorator that registers the clusterer.
python
>>> from tuiml.base.algorithms import clusterer, Clusterer
>>> @clusterer(tags=["partitioning"])
... class KMeans(Clusterer):
... passregressor(name: Optional[str]=None, tags: Optional[List[str]]=None, version: str='1.0.0', author: Optional[str]=None)
Decorator to register a regressor with the component registry.
Parameters
name
str
Registry name. Defaults to the class name.
tags
list of str
Tags for discovery and search.
version
str
= "1.0.0"
Component version string.
author
str
Component author.
Returns
decorator
callable
Class decorator that registers the regressor.
python
>>> from tuiml.base.algorithms import regressor, Regressor
>>> @regressor(tags=["linear"])
... class LinearRegression(Regressor):
... passanomaly_detector(name: Optional[str]=None, tags: Optional[List[str]]=None, version: str='1.0.0', author: Optional[str]=None)
Decorator to register an anomaly detector with the component registry.
Detectors subclass
Classifier and predict a discrete inlier/outlier label, so they score like a classifier. They register under their own component type instead, so list_algorithms can report them as anomaly detectors rather than burying them among the classifiers.Parameters
name
str
Registry name. Defaults to the class name.
tags
list of str
Tags for discovery and search.
version
str
= "1.0.0"
Component version string.
author
str
Component author.
Returns
decorator
callable
Class decorator that registers the detector.
python
>>> from tuiml.base.algorithms import anomaly_detector, Classifier
>>> @anomaly_detector(tags=["anomaly-detection", "tree-based"])
... class MyForestDetector(Classifier):
... passassociator(name: Optional[str]=None, tags: Optional[List[str]]=None, version: str='1.0.0', author: Optional[str]=None)
Decorator to register an associator with the component registry.
Parameters
name
str
Registry name. Defaults to the class name.
tags
list of str
Tags for discovery and search.
version
str
= "1.0.0"
Component version string.
author
str
Component author.
Returns
decorator
callable
Class decorator that registers the associator.
python
>>> from tuiml.base.algorithms import associator, Associator
>>> @associator(tags=["itemset", "frequent"])
... class Apriori(Associator):
... passsurvival(name: Optional[str]=None, tags: Optional[List[str]]=None, version: str='1.0.0', author: Optional[str]=None)
Decorator to register a survival model with the component registry.
Survival models subclass
Survival and estimate time-to-event with right-censored data.Parameters
name
str
Registry name. Defaults to the class name.
tags
list of str
Tags for discovery and search.
version
str
= "1.0.0"
Component version string.
author
str
Component author.
Returns
decorator
callable
Class decorator that registers the survival model.
uplift(name: Optional[str]=None, tags: Optional[List[str]]=None, version: str='1.0.0', author: Optional[str]=None)
Decorator to register an uplift model with the component registry.
Uplift models subclass
UpliftModel and estimate heterogeneous treatment effects.Parameters
name
str
Registry name. Defaults to the class name.
tags
list of str
Tags for discovery and search.
version
str
= "1.0.0"
Component version string.
author
str
Component author.
Returns
decorator
callable
Class decorator that registers the uplift model.
get_algorithm(name: str) -> Type[Algorithm]
Get an algorithm class by name from the component registry.
Parameters
name
str
Registered algorithm name.
Returns
algorithm_class
type
The algorithm class.
list_algorithms(type: Optional[str]=None) -> List[Dict[str, Any]]
List available algorithms.
Parameters
type
str
Filter by type (
'classifier', 'clusterer', 'regressor', 'associator').
Returns
algorithms
list of dict
Algorithm metadata dictionaries.