cascade.models#

class cascade.models.BasicModel(*args: Any, meta_prefix: List[Dict[Any, Any]] | str | None = None, **kwargs: Any)[source]#

Basic model is a more concrete version of an abstract Model class. It provides common interface for all ML solutions. For more flexible interface refer to Model class.

See also

cascade.models.Model

evaluate(x: Any, y: Any, metrics: List[Metric | Callable[[Any, Any], SupportsFloat]], *args: Any, **kwargs: Any) → None[source]#

Receives x and y validation sequences. Passes x to the model’s predict method along with any args or kwargs needed. Then updates self.metrics with what objects in metrics return. metrics should contain Metric with compute() method or callables with the interface: f(true, predicted) -> metric_value, where metric_value is a scalar

Parameters:

• x (Any) – Input of the model.

• y (Any) – Desired output to compare with the values predicted.

• metrics (List[Union[Metric, Callable[[Any, Any], MetricType]]]) – List of metrics or callables to compute metric values

fit(x: Any, y: Any, *args: Any, **kwargs: Any) → None[source]#

Method to encapsulate training loops. May be provided with any training-related arguments.

classmethod load(path: str, check_hash: bool = True) → BasicModel[source]#

Loads the model from path provided. Path should be a folder

load_artifact(path: str, *args: Any, **kwargs: Any) → None[source]#

BasicModel implements this for compatibility. This method does nothing since there are no internal artifacts in BasicModel

predict(x: Any, *args: Any, **kwargs: Any) → Any[source]#

Method to encapsulate inference. May include preprocessing steps to make model self-sufficient.

save(path: str) → None[source]#

Saves model to the path provided Also copies any additional files in the model folder.

Path should be a folder, which will be created if not exists and saves there as model.pkl

save_artifact(path: str, *args: Any, **kwargs: Any) → None[source]#

BasicModel implements this for compatibility. This method does nothing since there are no internal artifacts in BasicModel

class cascade.models.BasicModelModifier(model: Model, *args: Any, **kwargs: Any)[source]#

Interface to unify BasicModel and ModelModifier.

class cascade.models.Model(*args: Any, meta_prefix: List[Dict[Any, Any]] | str | None = None, **kwargs: Any)[source]#

Base class for any model. Used to provide unified interface to any model, store metadata including metrics.

__init__(*args: Any, meta_prefix: List[Dict[Any, Any]] | str | None = None, **kwargs: Any) → None[source]#

Should be called in any successor - initializes default meta needed.

Successors may pass all of their parameters to superclass for it to be able to log them in meta. Everything that is worth to document about the model can be put either in params or meta_prefix

add_file(path: str, missing_ok: bool = False) → None[source]#

Add additional file artifact to the model Copy the file to the model folder when saving model.

Parameters:

• path (str) – Path to the file to be copied. Can be missing at the time of the call, but should be present when calling save()

• missing_ok (bool, optional) – If it is okay when the file does not exist. Raises an error if False, by default False

add_log_callback(callback: Callable[[Model], None]) → None[source]#

Registers a callback to be executed while logging metrics. Usually is used internally and is not initially intended as a public method

Parameters:

callback (Callable[[Model], None]) – A function that accepts a model

See also

cascade.models.Model.log_metrics

add_metric(metric: str | Metric, value: SupportsFloat | None = None, **kwargs: Any) → None[source]#

Adds metric value to the model. If metric already exists in the list, updates its value.

Parameters:

• metric (Union[str, Metric]) – Either metric name or metric object. If object, then second argument is ignored

• value (Optional[MetricType]) – Metric value when metric is str, by default None

• str (Any additional args will go to the Metric constructor for flexibility if metric is)

Raises:

• ValueError – If in either value or metric.value is None

• TypeError – If metric is of inappropriate type

evaluate(*args: Any, **kwargs: Any) → None[source]#

Evaluates model against any metrics. Should not return any value, just populate self.metrics

fit(*args: Any, **kwargs: Any) → None[source]#

Method to encapsulate training loops. May be provided with any training-related arguments.

get_meta() → List[Dict[Any, Any]][source]#

Returns:

meta – A list where first element is this object’s metadata. All other elements represent the other stages of pipeline if present.

Meta can be anything that is worth to document about the object and its properties.

Meta is a list (see Meta type alias) to allow the formation of pipelines.

Return type:

Meta

link_dataset(ds: Dataset, name: str | None = None, split: str | None = None, line: Any | None = None) → None[source]#

Convenience function for linking datasets. Produces more readable meta files and records useful info without much hassle

Parameters:

• ds (Dataset) – Dataset to link

• name (Optional[str], optional) – Dataset name, by default None

• split (Optional[str], optional) – Split if applicable, may be “train”, “test”, etc, by default None

• line (Optional[DataLine], optional) – DataLine where this dataset is stored if applicable, by default None

classmethod load(path: str, *args: Any, **kwargs: Any) → Model[source]#

Loads model from provided path

load_artifact(path: str, *args: Any, **kwargs: Any) → None[source]#

Loads standalone model’s artifact using provided filepath and sets it inside the model

log() → None[source]#

Sequentially calls every log callback. Use this if you want to make a checkpoint of a model from inside the model. Callback should be a function that given the model saves it. For example ModelLine.save method. ModelLine.add_model registers callback with only_meta=True automatically when creating a new model using create_model.

See also

cascade.models.ModelLine.add_model, cascade.models.Model.add_log_callback

predict(*args: Any, **kwargs: Any) → Any[source]#

Method to encapsulate inference. May include preprocessing steps to make model self-sufficient.

save(path: str, *args: Any, **kwargs: Any) → None[source]#

Does additional saving routines. Call this if you call save() in any subclass.

Creates the folder, copies file artifacts added by add_file automatically

Parameters:

path (str) – Path to the model folder

Raises:

• ValueError – If the path is not a folder

• FileNotFoundError – If the file that should be copied does not exists and it is not ok. See add_file for more info.

See also

cascade.models.Model.add_file

save_artifact(path: str, *args: Any, **kwargs: Any) → None[source]#

Saves standalone model’s artifact using provided filepath

class cascade.models.ModelModifier(model: Model, *args: Any, **kwargs: Any)[source]#

Analog of dataset’s Modifier. Can be used to chain two models in one.

__init__(model: Model, *args: Any, **kwargs: Any) → None[source]#

Parameters:

model (Model) – A model to modify.

get_meta() → List[Dict[Any, Any]][source]#

Returns:

meta – A list where first element is this object’s metadata. All other elements represent the other stages of pipeline if present.

Meta can be anything that is worth to document about the object and its properties.

Meta is a list (see Meta type alias) to allow the formation of pipelines.

Return type:

Meta

class cascade.models.BasicTrainer(**kwargs)[source]#

The most common of concrete Trainers. Trains a model for a certain amount of epochs. Can start from checkpoint if model file exists.

__init__(repo: ModelRepo | str, *args: Any, **kwargs: Any) → None[source]#

Parameters:

repo (Union[ModelRepo, str]) – Either repo or path to it

get_meta() → List[Dict[Any, Any]][source]#

Returns:

meta – A list where first element is this object’s metadata. All other elements represent the other stages of pipeline if present.

Meta can be anything that is worth to document about the object and its properties.

Meta is a list (see Meta type alias) to allow the formation of pipelines.

Return type:

Meta

train(model: Model, *args: Any, train_data: Iterable[Any] | None = None, test_data: Iterable[Any] | None = None, train_kwargs: Dict[Any, Any] | None = None, test_kwargs: Dict[Any, Any] | None = None, epochs: int = 1, start_from: str | None = None, eval_strategy: int | None = None, save_strategy: int | None = None, **kwargs: Any) → None[source]#

Trains, evaluates and saves given model. If specified, loads model from checkpoint.

Parameters:

• model – Model a model to be trained or which to load from line specified in start_from

• train_data – Iterable train data to be passed to model’s fit()

• test_data – Iterable, optional test data to be passed to model’s evaluate()

• train_kwargs – Dict, optional arguments for fit()

• test_kwargs – Dict, optional arguments for evaluate() - the most common is the dict of metrics

• epochs – int, optional how many times to repeat training on data

• start_from – str, optional name or index of line from which to start starts from the latest model in line

• eval_strategy – int, optional Evaluation will take place every eval_strategy epochs. If None - the strategy is no evaluation.

• save_strategy – int, optional Saving will take place every save_strategy epochs. Meta will be saved anyway. If None - the strategy is ‘save only meta’.

class cascade.models.Trainer(repo: ModelRepo | str, *args: Any, **kwargs: Any)[source]#

A class that encapsulates training, evaluation and saving of models.

__init__(repo: ModelRepo | str, *args: Any, **kwargs: Any) → None[source]#

Parameters:

repo (Union[ModelRepo, str]) – Either repo or path to it

get_meta() → List[Dict[Any, Any]][source]#

Returns:

meta – A list where first element is this object’s metadata. All other elements represent the other stages of pipeline if present.

Meta can be anything that is worth to document about the object and its properties.

Meta is a list (see Meta type alias) to allow the formation of pipelines.

Return type:

Meta

train(model: Model, *args: Any, **kwargs: Any) → None[source]#

class cascade.models.Workspace(**kwargs)[source]#

__init__(path: str, meta_fmt: Literal['.json', '.yml', '.yaml'] = '.json', default_repo: str | None = None, *args: Any, **kwargs: Any) → None[source]#

Parameters:

• description – String description of an object

• tags (Iterable[str], optional) – The list of tags to be added

See also

cascade.base.MetaHandler

add_repo(name: str, *args: Any, **kwargs: Any) → ModelRepo[source]#

Creates and adds repo to the Workspace

Parameters:

name (str) – Name of the repo

Returns:

Created repo

Return type:

ModelRepo

Raises:

ValueError – If the repo already exists

get_default() → ModelRepo[source]#

get_meta() → List[Dict[Any, Any]][source]#

Returns:

meta – A list where first element is this object’s metadata. All other elements represent the other stages of pipeline if present.

Meta can be anything that is worth to document about the object and its properties.

Meta is a list (see Meta type alias) to allow the formation of pipelines.

Return type:

Meta

get_repo_names() → List[str][source]#

load_model_meta(model: str) → List[Dict[Any, Any]][source]#

Loads metadata of a model from disk

Parameters:

model (str) – model slug e.g. fair_squid_of_bliss

Returns:

Model metadata

Return type:

Meta

Raises:

FileNotFoundError – Raises if failed to find the model with slug specified

reload() → None[source]#

set_default(repo: str) → None[source]#