KFC Core Steps API

kfc_procedure.core.steps.kstep.KStep

Bases: ABC, BaseEstimator, ClusterMixin

Multi-divergence clustering stage in the KFC pipeline.

This estimator fits multiple BregmanKMeans models, each using a different Bregman divergence. The goal is to produce multiple clustering representations of the same dataset under different geometric assumptions.

Parameters:

Name	Type	Description	Default
divergences	list of str or BaseBregmanDivergence	List of divergence specifications. Each element can be: - a string identifier resolved via BregmanDivergenceFactory - an instantiated divergence object	required
divergences_params	dict	Optional parameter dictionary per divergence name. Example: { "gkl": {"alpha": 1.0}, "is": {"scale": 0.5} }	{}
n_clusters	int	Number of clusters per divergence model.	3
max_iter	int	Maximum number of Lloyd iterations per KMeans model.	300
tol	float	Convergence tolerance for distortion change.	1e-4
verbose	bool	If True, prints convergence diagnostics.	False
random_state	int or None	Random seed for reproducibility across all models.	None

Attributes:

Name	Type	Description
models_	dict	Fitted BregmanKMeans models keyed by divergence name.
clusters_	dict	Training cluster assignments per divergence model.

Methods:

Name	Description
fit	Fit one clustering model per divergence.
predict	Return cluster assignments for each divergence model.

Notes

This stage is purely model-parallel:

• No divergence interaction occurs during training
• Each model is independent
• Outputs are intended for downstream ensemble fusion

The design supports heterogeneous metric learning where no single divergence is assumed optimal for the dataset structure.

kfc_procedure.core.steps.fstep.FStep

Bases: ABC, BaseEstimator

Local model fitting stage of the KFC pipeline.

The F-step trains separate predictive models inside each cluster generated by the K-step clustering stage. Each divergence produces its own clustering structure, and a dedicated set of local models is trained per structure.

Parameters:

Name	Type	Description	Default
local_model	str or BaseLocalModel	Base model used for local learning. Can be: - string identifier resolved via LocalModelFactory - pre-instantiated model object	required
local_model_params	dict	Parameters passed to the local model constructor.	{}
task	str	Learning task type. Used for factory validation.	"regression"
random_state	int or None	Random seed passed to stochastic models.	None

Attributes:

Name	Type	Description
models_	dict	Nested dictionary storing trained local models: models_[divergence_name][cluster_id]

Methods:

Name	Description
fit	Train local models for each cluster and divergence.
predict	Predict using cluster-specific models for each divergence.

Notes

Prediction is performed per divergence:

* Each divergence has its own clustering assignment
* Each cluster has its own trained model
* Outputs are concatenated across divergences

This design enables divergence-aware local specialization, improving flexibility compared to global models.

kfc_procedure.core.steps.cstep.CStep

Bases: BaseEstimator

C-step: Aggregation layer for divergence-aware predictions.

The C-step combines outputs from multiple divergence-specific models into a final prediction using a configurable combiner strategy.

Parameters:

Name	Type	Description	Default
combiner	str or BaseCombiner	Aggregation strategy. Can be: - string identifier resolved via CombinerFactory - pre-instantiated BaseCombiner object	required
combiner_params	dict	Parameters passed to the combiner constructor.	None
task	str	Learning task type: - "regression" - "classification"	"regression"
random_state	int or None	Random seed forwarded to stochastic combiners.	None

Attributes:

Name	Type	Description
strategy_	BaseCombiner	Fitted combiner strategy instance.

Methods:

Name	Description
fit	Fit the aggregation strategy on prediction matrix.
predict	Return aggregated regression or class predictions.
predict_proba	Return class probabilities (classification only).

Notes

The C-step operates on the output of the F-step:

X = F_step(X_input)

Each column of X corresponds to a divergence-specific prediction.

The C-step performs:

y = f(X)

where f is a learned or rule-based aggregation function.

Raises:

Type	Description
AttributeError	If predict_proba is called on a regression task or unsupported combiner.

fit

Fit the combiner strategy.

predict

Predict final aggregated outputs.

predict_proba

Predict class probabilities (classification only).