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)#

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.
resources (dict | 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.

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)#

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)
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)

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.