utils

This module provides

class Component(loc=None)

Bases: object

Base class for all components with dynamic loading capability.

Parameters:

loc (str)

loc

Location identifier for the component.

Type:

str

args

Expected keys for arguments.

Type:

dict

check_args(args)

Check whether provided args contain all required keys.

Parameters:

args (dict)

Return type:

bool

setup(args)

Set up the component with provided arguments.

Parameters:

args (Dict[str, Any]) – Dictionary of arguments to initialize the component.

Returns:

Initialized component or setup result.

Return type:

Optional[Any]

class DataSet

Bases: Component, Dataset, ABC

Abstract base class for PyTorch datasets with dynamic loading support.

class Db(db_path)

Bases: object

Lightweight SQLite wrapper with foreign key enforcement.

Parameters:

db_path (str) – Path to the SQLite database file.

Raises:

FileNotFoundError – If the directory for the DB path doesn’t exist.

close()

Closes the database connection.

Return type:

None

execute(query, params=())

Execute a SQL query (INSERT, UPDATE, DELETE).

Parameters:

• query (str) – SQL query string.

• params (tuple) – Query parameters.

Returns:

sqlite3.Cursor or None

Return type:

Cursor | None

query(query, params=())

Execute a SELECT query and fetch all results.

Parameters:

• query (str) – SQL query string.

• params (tuple) – Query parameters.

Returns:

Query results.

Return type:

list

class Loss

Bases: Component, Module, ABC

Abstract base class for loss functions.

class Metric

Bases: Component, Module, ABC

Abstract base class for metrics.

class Model

Bases: Component, Module, ABC

Abstract base class for PyTorch models with dynamic loading support.

class Optimizer

Bases: Component, Module, ABC

Abstract base class for optimizers.

extract_all_locs(d)

Recursively extract all ‘loc’ values from nested dictionaries or lists. A component is defined as a dict with a ‘loc’ key and optional ‘args’.

Parameters:

d (Dict | List)

Return type:

List[str]

filter_configs(query: str, ids: List[str], loader_func: Callable[[str], Dict[str, Any]], params: Literal[True]) → DataFrame

filter_configs(query: str, ids: List[str], loader_func: Callable[[str], Dict[str, Any]], params: Literal[False] = False) → List[str]

Filter and extract information from a collection of configurations.

get_invalid_loc_queries(d, parent_key='')

Parameters:

• d (Dict | List)

• parent_key (str)

Return type:

List[str]

get_matching(base_id, get_ids_fn, loader_fn, query=None, include=False)

Get IDs of configurations that match the same flattened key-value pair(s) as a base config.

Parameters:

• base_id (str) – ID of the base configuration.

• get_ids_fn (Callable) – Function to retrieve all configuration IDs.

• loader_fn (Callable) – Function to load a configuration given its ID.

• query (str, optional) – Specific query key or ‘key=value’ pair.

Returns:

Mapping of matched query to list of matching IDs.

Return type:

Dict[str, List[str]]

hash_args(args)

Generate a SHA-256 hash from a dictionary of arguments.

This is commonly used to uniquely identify a configuration or set of parameters.

Parameters:

args (dict) – The dictionary of arguments to be hashed. Must be JSON-serializable.

Returns:

A SHA-256 hash string representing the input dictionary.

Return type:

str

Raises:

• TypeError –

• If the dictionary contains non-serializable values. –

load_component(loc, args=None, setup=True)

Dynamically load and optionally initialize a component class.

This utility imports a class from a given module path and instantiates it. If the class defines a setup method and setup=True, it calls setup(args) and returns the initialized component. Otherwise, it returns the raw instance.

Parameters:

• loc (str) – Fully qualified class location in dot notation (e.g., ‘CompBase.models.MyModel’). If no dot is present, it is assumed the class is defined in __main__.

• args (dict, optional) – Dictionary of arguments to pass to the setup() method, if applicable. Defaults to an empty dict.

• setup (bool, optional) – Whether to invoke the component’s setup method after instantiation. Defaults to True.

Returns:

An instance of the loaded class, either raw or configured via setup().

Return type:

Any

Raises:

• ComponentLoadError – If the specified class is not found in the target module.

• ImportError – If the module cannot be imported.