howso.direct

Classes

HowsoDirectClient

The direct Howso client.

The Python API for the Howso Direct Client.

class howso.direct.HowsoDirectClient(*, amalgam=None, config_path=None, debug=False, default_persist_path=None, howso_path=PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/diveplane-howso-docs/envs/release-latest/lib/python3.11/site-packages/howso/howso-engine'), howso_fname='howso.caml', react_initial_batch_size=10, trace=False, train_initial_batch_size=100, verbose=False, version_check=True, **kwargs)

Bases: AbstractHowsoClient

The direct Howso client.

A client which provides access to the Howso Engine endpoints via a direct interface using dynamic libraries.

Parameters:

• amalgam (Mapping[str, Any] | None, default: None) – Keyword-argument overrides to the underlying Amalgam instance.

• config_path (Path | str | None, default: None) –

  A configuration file in yaml format that specifies Howso engine settings.

  If not set, the client will also check in order of precedence:

  • HOWSO_CONFIG environment variable

  • The current directory for howso.yml, howso.yaml, config.yml

  • ~/.howso for howso.yml, howso.yaml, config.yml.

• debug (bool, default: False) – Enable debug output.

• default_persist_path (Path | str | None, default: None) – Override the default save location for created Trainees. If not specified the current working directory will be used.

• howso_path (Path | str, default: PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/diveplane-howso-docs/envs/release-latest/lib/python3.11/site-packages/howso/howso-engine')) – Directory path to the Howso caml files. Defaults to the built-in package location.

• howso_fname (str, default: 'howso.caml') – Name of the Howso caml file with file extension.

• react_initial_batch_size (int, default: 10) – The default number of cases to react to in the first batch for calls to HowsoDirectClient.react().

• trace (bool, default: False) – When true, enables tracing of Amalgam operations. This will generate an execution trace file useful in debugging, the filename will use the standard name of howso_[random 6 byte hex]_execution.trace.

• train_initial_batch_size (int, default: 100) – The default number of cases to train to in the first batch for calls to HowsoDirectClient.train().

• verbose (bool, default: False) – Set verbose output.

• version_check (bool, default: True) – Check if the latest version of Howso engine is installed.

acquire_trainee_resources(trainee_id, *, max_wait_time=None)

Acquire resources for a trainee in the Howso service.

Parameters:

• trainee_id (str) – The ID of the Trainee to acquire resources for.

• max_wait_time (int | float | None, default: None) – (Not implemented) The number of seconds to wait to acquire trainee resources before aborting gracefully.

Raises:

HowsoError – If no Trainee with the requested ID can be found or loaded.

begin_session(name='default', metadata=None)

Begin a new session.

Parameters:

• name (str | None, default: 'default') – The name of the session.

• metadata (Mapping | None, default: None) – Any key-value pair to store as custom metadata for the session.

Returns:

The new session instance.

Raises:

TypeError – If name is non-None and not a string or metadata is non-None and not a dictionary.

Return type:

Session

check_name_valid_for_save(file_path, clobber=False)

Ensure that the given filename is a valid name for the host OS.

Parameters:

• file_path (Path | str) – The full path of the desired Trainee.

• clobber (bool, default: False) – If True, checks will pass if the file is writable even if it already exists.

Return type:

tuple[bool, str]

Returns:

• bool – Return True if the file has a valid filename, is a filepath (not a directory path), that the process (user) has sufficient permissions and, if clobber is False, also that the file does not already exist (optional check).

• str – The reason. If the return is True, this will be ‘OK’.

check_version()

Check if there is a more recent version.

Return type:

str | None

copy_trainee(trainee_id, new_trainee_name=None, new_trainee_id=None, *, library_type=None, resources=None, runtime=None)

Copies a trainee to a new trainee id in the Howso service.

Parameters:

• trainee_id (str) – The trainee id of the trainee to be copied.

• new_trainee_name (str | None, default: None) – The name of the new Trainee.

• new_trainee_id (str | None, default: None) –

  The id of the new Trainee.

  If not provided, the id will be set to new_trainee_name (if provided), otherwise a new uuid4.

• library_type (Literal['st', 'mt'] | None, default: None) –

  (Not Implemented) The library type of the Trainee. If not specified, the new trainee will inherit the value from the original.

  Deprecated since version 31.0: Pass via runtime instead.

• resources (Mapping[str, Any] | None, default: None) –

  (Not Implemented) Customize the resources provisioned for the Trainee instance. If not specified, the new trainee will inherit the value from the original.

  Deprecated since version 31.0: Pass via runtime instead.

• runtime (TraineeRuntimeOptions | None, default: None) – Library type, resource requirements, and other runtime settings for the new Trainee instance. If not specified, the new trainee will inherit the values from the original. Not used in this client implementation.

Returns:

The Trainee object that was created.

Raises:

ValueError – If the Trainee could not be copied.

Return type:

Trainee

create_trainee(name=None, features=None, *, id=None, library_type=None, max_wait_time=None, metadata=None, overwrite_trainee=False, persistence='allow', project=None, resources=None, runtime=None)

Create a Trainee on the Howso service.

A Trainee can be thought of as “model” in traditional ML sense.

Parameters:

• name (str | None, default: None) – A name to use for the Trainee.

• features (Mapping[str, Mapping] | None, default: None) – The Trainee feature attributes.

• id (str | UUID | None, default: None) – A custom unique identifier to use with the Trainee. If not specified the name will be used, or a new UUID if no name was provided.

• library_type (Literal['st', 'mt'] | None, default: None) –

  (Not implemented in this client)

  Deprecated since version 31.0: Pass via runtime instead.

• max_wait_time (int | float | None, default: None) – (Not implemented in this client)

• metadata (MutableMapping[str, Any] | None, default: None) – Arbitrary jsonifiable data to store along with the Trainee.

• overwrite_trainee (bool, default: False) – If True, and if a trainee with the provided id already exists, the existing trainee will be deleted and a new trainee created.

• persistence (Literal['allow', 'always', 'never'], default: 'allow') – The requested persistence state of the Trainee.

• project (str | Project | None, default: None) – (Not implemented in this client)

• resources (Mapping[str, Any] | None, default: None) –

  (Not implemented in this client)

  Deprecated since version 31.0: Pass via runtime instead.

• runtime (TraineeRuntimeOptions | None, default: None) – (Not implemented in this client)

Returns:

The Trainee object that was created.

Return type:

Trainee

delete_trainee(trainee_id=None, *, file_path=None)

Delete a Trainee from the Howso service and filesystem.

Includes all cases, model metadata, session data, persisted files, etc.

Parameters:

• trainee_id (str | None, default: None) – The ID of the Trainee. If full filepath with is provided, trainee_id will only be used to delete from memory.

• file_path (Path | str | None, default: None) –

  The path of the file used to load the Trainee from. Used for deleting trainees from disk.

  The file path must end with a filename, but file path can be either an absolute path, a relative path or just the file name.

  If trainee_id is not provided, in addition to deleting from disk, will attempt to delete a Trainee from memory assuming the Trainee has the same name as the filename.

  If file_path is a relative path the absolute path will be computed appending the file_path to the CWD.

  If file_path is an absolute path, this is the absolute path that will be used.

  If file_path is just a filename, then the absolute path will be computed appending the filename to the CWD.

execute(trainee_id, label, payload, **kwargs)

Execute a label in Howso engine.

Parameters:

• trainee_id (str) – The entity handle of the Trainee.

• label (str) – The label to execute.

• payload (Any) – The payload to send to label.

Returns:

The label’s response.

Return type:

Any

execute_sized(trainee_id, label, payload, **kwargs)

Execute a label in Howso engine and return the request and response sizes.

Parameters:

• trainee_id (str) – The entity handle of the Trainee.

• label (str) – The label to execute.

• payload (Any) – The payload to send to label.

Return type:

tuple[Any, int, int]

Returns:

• Any – The label’s response.

• int – The request payload size.

• int – The response payload size.

export_trainee(trainee_id, *, decode_cases=False, filepath=None, path_to_trainee=None)

Export a saved Trainee’s data to json files for migration.

Parameters:

• trainee_id (str) – The ID of the Trainee.

• decode_cases (bool, default: False) – When True, decode (e.g., convert from epoch to datetime) any encoded feature values. When False, case feature values will be exported as is from the Trainee.

• filepath (Path | str | None, default: None) – The directory to write the exported Trainee json files to.

• path_to_trainee (Path | str | None, default: None) – Deprecated, use filepath instead.

get_session(session_id)

Retrieve a session.

Note

If multiple trainees are loaded, the session will be retrieved from the most recently loaded trainee that contains the requested session. (The metadata will include the trainee_id from which the session was retrieved from)

Parameters:

session_id (str) – The id of the session to retrieve.

Returns:

The session instance.

Return type:

Session

get_trainee(trainee_id)

Gets a trainee loaded in the Howso service.

Parameters:

trainee_id (str) – The id of the trainee.

Returns:

A Trainee object representing the Trainee.

Return type:

Trainee

get_trainee_runtime(trainee_id)

Get information about the trainee.

Including trainee version and configuration parameters.

Parameters:

trainee_id (str) – The ID of the Trainee.

Returns:

The Trainee runtime details. Including Trainee version and configuration parameters.

Return type:

TraineeRuntime

get_version()

Return the Howso version.

Returns:

A version response that contains the version data for the current instance of Howso.

Return type:

HowsoVersion

is_tracing_enabled(trainee_id)

Get if tracing is enabled for Trainee.

Parameters:

trainee_id (str) – The identifier of the Trainee.

Returns:

True, if tracing is enabled for provided Trainee.

Return type:

bool

persist_trainee(trainee_id)

Persists a Trainee in the Howso service storage.

After persisting, the Trainee resources can be released.

Parameters:

trainee_id (str) – The ID of the Trainee to persist.

Raises:

AssertionError – If the requested Trainee’s persistence is set to “never”.

query_sessions(search_terms=None, *, trainee=None, **kwargs)

Return a list of all accessible sessions.

Note

Returns sessions from across all loaded trainees. (The metadata will include the trainee_id from which the session was retrieved from)

Parameters:

• search_terms (str | None, default: None) – Space or comma delimited search terms to filter results by.

• trainee (str | Trainee | None, default: None) – A Trainee to filter by.

Returns:

The listing of session instances.

Return type:

list[Session]

query_trainees(search_terms=None)

Query accessible Trainees.

Parameters:

search_terms (str | None, default: None) – Keywords to filter Trainees by.

Returns:

A list of the Trainee identities with schema {“name”: TRAINEE_NAME, “id”: TRAINEE_ID}

Return type:

list[dict]

release_trainee_resources(trainee_id)

Release a trainee’s resources from the Howso service.

Parameters:

trainee_id (str) – The ID of the Trainee to release resources for.

Raises:

HowsoError – If the requested Trainee has a persistence of “never”.

report_version(task)

Report to end-user that there is a newer version available.

Parameters:

task (Future)

resolve_trainee_filepath(filename, *, filepath=None)

Resolve the path to a persisted Trainee file.

Parameters:

• filename (str) – The name of the Trainee file.

• filepath (Path | str | None, default: None) – The directory of the file. If not provided, uses default persist path.

Returns:

The resolved path to the the Trainee file.

Return type:

str

update_session(session_id, *, metadata=None)

Update a session.

Note

Updates the session across all loaded trainees.

Parameters:

• session_id (str) – The id of the session to update metadata for.

• metadata (Mapping | None, default: None) – Any key-value pair to store as custom metadata for the session.

Returns:

The updated session instance.

Raises:

• TypeError – If metadata is non-None and not a dictionary.

• HowsoError – If session_id is not found for the active session or any of the session(s) of a loaded Trainees.

Return type:

Session

update_trainee(trainee)

Update an existing Trainee in the Howso service.

Parameters:

trainee (Mapping | Trainee) – A Trainee object defining the Trainee.

Returns:

The Trainee object that was updated.

Return type:

Trainee

upgrade_trainee(trainee_id, *, filename=None, filepath=None, path_to_trainee=None)

Upgrade a saved Trainee to current version.

Parameters:

• trainee_id (str) – The ID of the Trainee.

• filename (str | None, default: None) – The base name of the exported Trainee json files. If not specified, uses the value of trainee_id. (e.g., [filename].meta.json)

• filepath (Path | str | None, default: None) – The directory where the exported Trainee .exp.json and .meta.json files exist.

• path_to_trainee (Path | str | None, default: None) – Deprecated, use filepath instead.

Returns:

The Trainee that was upgraded.

Return type:

Trainee

BAD_TRAINEE_NAME_CHARS = {'..', '/', ':', '\\'}

The characters which are disallowed from being a part of a Trainee name or ID.

SUPPORTED_PRECISION_VALUES = ['exact', 'similar']

The supported values of precision for methods that accept it

property active_session: Session

Return the active session.

Returns:

The active session instance.

property react_initial_batch_size: int

The default number of cases in the first react batch.

Returns:

The default number of cases to react to in the first batch.

property train_initial_batch_size: int

The default number of cases in the first train batch.

Returns:

The default number of cases to train in the first batch.

property trainee_cache: TraineeCache

Return the trainee cache.

Returns:

The trainee cache.