Utilities API

kfc_procedure.core.factory.BaseFactory

Bases: ABC

Abstract base class for registry-driven factories.

BaseFactory provides a generic mechanism for registering classes under string identifiers and creating instances dynamically at runtime.

Each subclass maintains an isolated registry, allowing multiple factory types to coexist independently without registration conflicts.

The registry stores:

• implementation class references
• category labels
• optional metadata

Registration is typically performed using the :meth:register decorator.

Notes

• Registration names are case-insensitive.
• All identifiers are normalized to lowercase internally.
• Factory subclasses automatically receive independent registries through __init_subclass__.

Attributes:

Name	Type	Description
_registry	Dict[str, Dict[str, Any]]	Internal registry mapping normalized names to registration metadata. Each entry has the structure:: { "class": Type, "categories": Set[str], "metadata": Dict[str, Any], }

Examples:

>>> class OptimizerFactory(BaseFactory):
...     pass

>>> @OptimizerFactory.register(
...     "adam",
...     categories={"optimizer"},
...     version="v1",
... )
... class Adam:
...     pass

>>> OptimizerFactory.contains("adam")
True

__init_subclass__

Initialize subclass with an independent registry.

Each subclass receives a fresh registry dictionary to ensure registrations remain isolated between factory types.

Parameters:

Name	Type	Description	Default
**kwargs	dict	Additional keyword arguments forwarded to parent classes.	{}

Examples:

>>> class KernelFactory(BaseFactory):
...     pass

>>> class OptimizerFactory(BaseFactory):
...     pass

>>> KernelFactory._registry is OptimizerFactory._registry
False

register classmethod

Register a class under one or more aliases.

This method is primarily intended for decorator-based registration.

Parameters:

Name	Type	Description	Default
*names	str	One or more aliases associated with the target class. Registration names are normalized to lowercase before storage.	()
categories	str or Set[str]	Optional category labels associated with the registration. Categories are useful for grouping implementations by capability, functionality, or component type.	None
**metadata	Any	Additional arbitrary metadata attached to the registration entry. Metadata is stored without interpretation and can later be accessed through :meth:info.	{}

Returns:

Type	Description
callable	A decorator that registers the target class and returns it unchanged.

Raises:

Type	Description
KeyError	If any provided registration name already exists in the registry.

Notes

Multiple aliases may point to the same implementation class.

Examples:

>>> @KernelFactory.register(
...     "gaussian",
...     "rbf",
...     categories={"kernel"},
...     stationary=True,
... )
... class GaussianKernel:
...     pass

create classmethod

Create an instance of a registered implementation.

Parameters:

Name	Type	Description	Default
name	str	Registered name or alias of the implementation class.	required
**kwargs	dict	Keyword arguments forwarded to the implementation constructor.	{}

Returns:

Type	Description
Any	Instantiated implementation object.

Raises:

Type	Description
KeyError	If the requested name does not exist in the registry.

Examples:

>>> kernel = KernelFactory.create(
...     "gaussian",
...     sigma=1.5,
... )

available classmethod

Return all registered names.

Returns:

Type	Description
List[str]	Sorted list of available registration names.

Examples:

>>> KernelFactory.available()
['gaussian', 'rbf']

contains classmethod

Check whether a name exists in the registry.

Parameters:

Name	Type	Description	Default
name	str	Registration name or alias to check.	required

Returns:

Type	Description
bool	True if the name exists in the registry, otherwise False.

Examples:

>>> KernelFactory.contains("gaussian")
True

available_categories classmethod

Return all registered category labels.

Returns:

Type	Description
Set[str]	Set of unique category names currently present in the registry.

Examples:

>>> KernelFactory.available_categories()
{'kernel', 'distance'}

available_by_category classmethod

Return all registered names associated with a category.

Parameters:

Name	Type	Description	Default
category	str	Category label used for filtering.	required

Returns:

Type	Description
List[str]	Sorted list of registered names belonging to the category.

Examples:

>>> KernelFactory.available_by_category("kernel")
['gaussian', 'rbf']

info classmethod

Return registration metadata for a registered name.

Parameters:

Name	Type	Description	Default
name	str	Registered name or alias.	required

Returns:

Type	Description
Dict[str, Any]	Dictionary containing registration information. The returned structure includes:: { "name": str, "class": str, "categories": List[str], "metadata": Dict[str, Any], }

Raises:

Type	Description
KeyError	If the name is not registered.

Examples:

>>> KernelFactory.info("gaussian")
{
    'name': 'gaussian',
    'class': 'GaussianKernel',
    'categories': ['kernel'],
    'metadata': {'stationary': True}
}

find_by_class classmethod

Return all registered aliases associated with a class.

Parameters:

Name	Type	Description	Default
target_cls	Type	Implementation class to search for.	required

Returns:

Type	Description
List[str]	Sorted list of aliases registered for the class.

Examples:

>>> KernelFactory.find_by_class(GaussianKernel)
['gaussian', 'rbf']

supports classmethod

Check whether a registered implementation belongs to a category.

Parameters:

Name	Type	Description	Default
name	str	Registered name or alias.	required
category	str	Category label to test.	required

Returns:

Type	Description
bool	True if the implementation is registered under the specified category, otherwise False.

Examples:

>>> KernelFactory.supports("gaussian", "kernel")
True

kfc_procedure.utils.logger.Logger

Lightweight structured logger for the KFC pipeline.

This logger provides a minimal, dependency-free logging utility designed specifically for debugging and profiling multi-stage machine learning pipelines (K-step → F-step → C-step).

It supports hierarchical verbosity levels similar to logging libraries, but remains simple and NumPy-friendly.

Logging levels

verbose = 0 Silent mode (no output)

verbose = 1 Basic information messages (high-level pipeline events)

verbose = 2 Debug messages (shapes, stage transitions, model info)

verbose = 3 Trace-level output (iteration-level and fine-grained updates)

Parameters:

Name	Type	Description	Default
verbose	int	Controls the logging verbosity level.	0

Attributes:

Name	Type	Description
verbose	int	Current verbosity level.
t0	float	Timestamp marking logger initialization time (used for elapsed time tracking).

Notes

• This logger is intentionally minimal and does not depend on Python's standard logging module.
• All timestamps are relative to the logger initialization time.
• Designed for ML experimentation, not production logging.

Examples:

>>> logger = KFCLogger(verbose=2)
>>> logger.info("Training started")
>>> logger.debug("Shape = (100, 10)")
>>> logger.trace("Iteration 1 complete")

__init__

Initialize the KFC logger.

Parameters:

Name	Type	Description	Default
verbose	int	Logging verbosity level (0–3).	0

log

Internal logging dispatcher.

Parameters:

Name	Type	Description	Default
level	int	Required verbosity level to display the message.	required
msg	str	Message to display.	required

Notes

If self.verbose >= level, the message is printed with elapsed time since initialization.

info

Log high-level pipeline information.

Parameters:

Name	Type	Description	Default
msg	str	Informational message.	required

debug

Log debugging information.

Parameters:

Name	Type	Description	Default
msg	str	Debug message (e.g., shapes, shapes, model states).	required

trace

Log fine-grained execution details.

Parameters:

Name	Type	Description	Default
msg	str	Trace-level message (e.g., per-iteration updates).	required

kfc_procedure.utils.logger.timed

kfc_procedure.utils.resolve.resolve_bregman

kfc_procedure.utils.resolve.resolve_kstep