Aim Python SDK#

API Reference for Aim Python SDK classes#

Aim is designed to enable logging of any data type. This reference will guide you through the fundamental data building blocks, as well as data retrieval approaches.

Repo class reference#

The repo module contains implementation of class Repo; a core class for accessing the data logged in Aim. It provides interfaces for creating and managing Aim repositories, for both local and remote setups. Repo class can be used to query stored Containers and Sequences, as well as get the metadata about logs, such as registered types, actions, packages, summary of logged types, etc.

Repository management#

Repo.is_remote_path

Determines if the provided path refers to a remote repository.

Repo.default

Retrieves the default repository instance.

Repo.from_path

Named constructor for Repo for given path.

Repo.active_repo

Retrieves the currently active repository.

Repo.exists

Checks if an Aim repository exists at the given path.

Repo.init

Initializes a new Aim repository at the given path.

Repo.rm

Deletes an Aim repository at the given path.

Repo.get_version

Retrieves the version of the Aim repository at the given path.

Data access interface#

Repo.container_hashes

Retrieves a list of hashes for all tracked containers.

Repo.get_container

Retrieves a container from the repository based on its hash.

Repo.containers

Retrieves a collection of containers based on the query expression and type.

Repo.sequences

Retrieves a collection of sequences based on the query expression and type.

Repo.tracked_container_types

Lists all container types being tracked in the repository.

Repo.tracked_sequence_types

Lists all sequence types being tracked in the repository.

Repo.tracked_sequence_infos

Retrieves information for a specific sequence type.

Repo.tracked_params

Retrieves all tracked parameters for the repository.

Repo.storage_engine

Returns the storage engine associated with the repository.

Repo.resource_tracker

Returns the resource tracker associated with the repository.

Package and Types information#

Repo.registered_container_types

Lists all registered container types in the repository.

Repo.registered_sequence_types

Lists all registered sequence types in the repository.

Repo.registered_actions

Lists all registered actions in the repository.

Repo.add_package

Adds a package to the repository.

Repo.remove_package

Removes a package from the repository.

Repo.load_active_packages

Loads all active packages in the repository.

Data management interface#

Repo.delete_containers

Deletes multiple Containers data from aim repository

Repo.delete_container

Delete Container data from aim repository

Repo.move_containers

Move multiple Containers data from current aim repository to destination aim repository

Repo.copy_containers

Copy multiple Containers data from current aim repository to destination aim repository

Repo.prune

Removes dangling/orphan params/sequences with no referring containers.

class aim._sdk.repo.Repo(path, *, read_only=True)[source]#

Represents an Aim repository, handling both local and remote repositories.

Initializes a repository instance.

Parameters:
  • path (str) – Path to the Aim repository.

  • read_only (bool, optional) – If True, opens the repo in read-only mode. Default is True.

static is_remote_path(path)[source]#

Determines if the provided path refers to a remote repository.

Parameters:

path (str) – The path to be checked.

Returns:

True if the path is remote, otherwise False.

Return type:

bool

classmethod default()[source]#

Retrieves the default repository instance.

Returns:

Default repository instance.

Return type:

Repo

classmethod from_path(path, read_only=True)[source]#

Named constructor for Repo for given path.

Parameters:
  • path (str) – Path to Aim repository.

  • read_only (bool, optional) – Flag for opening Repo in readonly mode. False by default.

  • init (bool, optional) – Flag used to initialize new Repo. False by default. Recommended to use aim init command instead.

Returns:

Repo object.

Return type:

Repo

classmethod get_version(path)[source]#

Retrieves the version of the Aim repository at the given path.

Parameters:

path (str) – The repository path.

Returns:

Version tuple if the path refers to a valid Aim repository, otherwise None.

Return type:

Optional[Tuple[int, …]]

classmethod active_repo()[source]#

Retrieves the currently active repository.

Returns:

The active repository instance.

Return type:

Repo

Raises:

ValueError – If it’s not possible to determine the active repository.

classmethod exists(path)[source]#

Checks if an Aim repository exists at the given path.

Parameters:

path (str) – The path to check.

Returns:

True if the Aim repository exists, otherwise False.

Return type:

bool

classmethod init(path)[source]#

Initializes a new Aim repository at the given path.

Parameters:

path (str) – Path where the Aim repository should be created.

Returns:

The newly initialized repository instance.

Return type:

Repo

classmethod rm(path)[source]#

Deletes an Aim repository at the given path.

Parameters:

path (str) – The path to the Aim repository to be deleted.

__hash__()[source]#

Return hash(self).

Return type:

int

property storage_engine: StorageEngine#

Returns the storage engine associated with the repository.

Returns:

The storage engine instance.

Return type:

StorageEngine

property resource_tracker: ResourceTracker#

Returns the resource tracker associated with the repository.

Returns:

The resource tracker instance.

Return type:

ResourceTracker

tracked_container_types()[source]#

Lists all container types being tracked in the repository.

Returns:

List of tracked container types.

Return type:

List[str]

tracked_sequence_types()[source]#

Lists all sequence types being tracked in the repository.

Returns:

List of tracked sequence types.

Return type:

List[str]

tracked_sequence_infos(sequence_type)[source]#

Retrieves information for a specific sequence type.

Parameters:

sequence_type (str) – The sequence type to retrieve information for.

Returns:

Dictionary of tracked sequence names/contexts.

Return type:

Dict[str, List]

tracked_params()[source]#

Retrieves all tracked parameters for the repository.

Returns:

Dictionary of tracked parameters.

Return type:

Dict

registered_container_types()[source]#

Lists all registered container types in the repository.

Returns:

List of registered container types.

Return type:

List[str]

registered_sequence_types()[source]#

Lists all registered sequence types in the repository.

Returns:

List of registered sequence types.

Return type:

List[str]

registered_actions()[source]#

Lists all registered actions in the repository.

Returns:

List of registered actions.

Return type:

List[str]

property container_hashes#

Retrieves a list of hashes for all tracked containers.

Returs:

List[str]: List of container hashes.

get_container(hash_)[source]#

Retrieves a container from the repository based on its hash.

Parameters:

hash (str) – The hash of the container to retrieve.

Returns:

The corresponding container object.

Return type:

Container

containers(query_=None, type_=<class 'aim._sdk.container.Container'>, **kwargs)[source]#

Retrieves a collection of containers based on the query expression and type.

Parameters:
  • query (Optional[str]) – The query string to filter containers.

  • type (Union[str, Type[Container]]) – The type of containers to retrieve.

  • query_ (Optional[str]) –

  • type_ (Union[str, Type[Container]]) –

Returns:

The resulting collection of containers.

Return type:

ContainerCollection

sequences(query_=None, type_=<class 'aim._sdk.sequence.Sequence'>, **kwargs)[source]#

Retrieves a collection of sequences based on the query expression and type.

Parameters:
  • query (Optional[str]) – The query string to filter sequences.

  • type (Union[str, Type[Sequence]]) – The type of sequences to retrieve.

  • query_ (Optional[str]) –

  • type_ (Union[str, Type[Sequence]]) –

Returns:

The resulting collection of sequences.

Return type:

SequenceCollection

add_package(pkg_name)[source]#

Adds a package to the repository.

Parameters:

pkg_name (str) – The name of the package to be added.

Returns:

True if the package was added successfully, False if it already exists.

Return type:

bool

remove_package(pkg_name)[source]#

Removes a package from the repository.

Parameters:

pkg_name (str) – The name of the package to be removed.

Returns:

True if the package was removed successfully, False if it doesn’t exist.

Return type:

bool

load_active_packages()[source]#

Loads all active packages in the repository. Only applicable for local repositories.

Note

This method doesn’t return any value but has side effects on the state of loaded packages.

delete_containers(container_hashes)[source]#

Deletes multiple Containers data from aim repository

This action removes containers data permanently and cannot be reverted. If you want to archive container but keep it’s data use repo.get_container(container_hash).archived = True.

Parameters:

container_hashes (str) – list of Containers to be deleted.

Returns:

(True, []) if all containers deleted successfully, (False, list) with list of remaining containers otherwise.

Return type:

Tuple[bool, List[str]]

delete_container(container_hash)[source]#

Delete Container data from aim repository

This action removes container data permanently and cannot be reverted. If you want to archive container but keep it’s data use repo.get_container(container_hash).archived = True.

Parameters:

container_hash (str) – Container to be deleted.

Returns:

True if container deleted successfully, False otherwise.

Return type:

bool

move_containers(container_hashes, dest_repo)[source]#

Move multiple Containers data from current aim repository to destination aim repository

Parameters:
  • container_hashes (str) – list of Containers to be moved.

  • dest_repo (Repo) – destination Repo instance to move Containers

Returns:

(True, []) if all containers were moved successfully, (False, list) with list of remaining containers otherwise.

Return type:

Tuple[bool, List[str]]

copy_containers(container_hashes, dest_repo)[source]#

Copy multiple Containers data from current aim repository to destination aim repository

Parameters:
  • container_hashes (str) – list of Containers to be copied.

  • dest_repo (Repo) – destination Repo instance to copy Containers

Returns:

(True, []) if all containers were copied successfully, (False, list) with list of remaining containers otherwise.

Return type:

Tuple[bool, List[str]]

prune()[source]#

Removes dangling/orphan params/sequences with no referring containers.

Container class interface#

The container module provides implementation of a Container class. Container is a core class, representing a inter-related set of properties, parameters, Sequence and Record entities. Specific Container types can be used to collect and store data representing a process execution, such as model training, LLM chain execution, etc. Container class provides interface for getting and setting it’s pre-defined Properties as well as free-form dict-like parameters. Container class has an interface for managing sequence objects.

Container creation and retrieval#

Container.from_storage

Restores a serialized container instance from given storage and meta tree.

Container.filter

Filters the containers based on the given expression and repository.

Container.find

Finds and returns a container instance based on the given hash.

Container.match

Checks if the container matches the given expression.

Params and properties management#

Container.__setitem__

Sets a value in the container for a given key.

Container.set

Sets a value in the container for a given key with optional strictness.

Container.__getitem__

Retrieves a value from the container based on the given key.

Container.get

Retrieves a value from the container based on the key or returns a default value.

Container.__delitem__

Deletes a value in the container based on the given key.

Container.collect_properties

Collects and returns all properties associated with the container as a dictionary object.

Container.creation_time

Container.end_time

Sequence data management#

Container.delete_sequence

Deletes a sequence from the container based on the given name and context.

Container.sequences

Returns a map of sequences associated with the container.

ContainerSequenceMap.typed_sequence

Retrieves a sequence of specified type based on the given name and context.

ContainerSequenceMap.__call__

Retrieves a sequence collection based on a query expression.

ContainerSequenceMap.__iter__

Returns an iterator over the sequences.

ContainerSequenceMap.__getitem__

Retrieves a sequence based on the given item (name or tuple of name and context).

ContainerSequenceMap.__delitem__

Deletes a sequence based on the given item (name or tuple of name and context).

Container metadata and management#

Container.delete

Deletes the container and its associated data.

Container.close

Closes the container and releases any associated resources.

Container.get_logged_typename

Returns the typename of the logged data in the container.

Container.get_typename

Container.get_full_typename

Container.version

class aim._sdk.container.Container(hash_=None, *, repo=None, mode=ContainerOpenMode.WRITE)[source]#

Initializes the Container instance.

Parameters:
  • hash (str, optional) – Unique identifier for the container.

  • repo (Union[str, 'Repo'], optional) – Repository path or Repo object.

  • mode (Union[str, ContainerOpenMode], optional) – Mode for the container (e.g., β€œREADONLY” or β€œWRITE”). Defaults to β€œWRITE”.

  • hash_ (Optional[str]) –

classmethod from_storage(storage, meta_tree, *, hash_)[source]#

Restores a serialized container instance from given storage and meta tree.

Parameters:
  • storage – Storage backend instance.

  • meta_tree ('TreeView') – Tree view of the metadata.

  • hash (str) – Unique identifier for the container.

  • hash_ (str) –

classmethod filter(expr='', repo=None)[source]#

Filters the containers based on the given expression and repository.

Parameters:
  • expr (str, optional) – Query expression for filtering.

  • repo ('Repo', optional) – Repository instance. Defaults to the active Repo.

Return type:

ContainerCollection

classmethod find(hash_)[source]#

Finds and returns a container instance based on the given hash.

Parameters:
  • hash (str) – Unique identifier for the container.

  • hash_ (str) –

Return type:

Optional[Container]

__setitem__(key, value)[source]#

Sets a value in the container for a given key.

Parameters:
  • key – Key to set the value for.

  • value – Value to be set.

set(key, value, strict)[source]#

Sets a value in the container for a given key with optional strictness.

Parameters:
  • key – Key to set the value for.

  • value – Value to be set.

  • strict (bool) – Whether to enforce strict setting.

__getitem__(key)[source]#

Retrieves a value from the container based on the given key.

Parameters:

key – Key for which value is to be retrieved.

get(key, default=None, strict=False)[source]#

Retrieves a value from the container based on the key or returns a default value.

Parameters:
  • key – Key for which value is to be retrieved.

  • default (optional) – Default value to return if key doesn’t exist.

  • strict (bool, optional) – Whether to enforce strict retrieval.

__delitem__(key)[source]#

Deletes a value in the container based on the given key.

Parameters:

key – Key for which the value is to be deleted.

collect_properties()[source]#

Collects and returns all properties associated with the container as a dictionary object.

Return type:

Dict

get_logged_typename()[source]#

Returns the typename of the logged data in the container.

Return type:

str

match(expr)[source]#

Checks if the container matches the given expression.

Return type:

bool

delete_sequence(name, context=None)[source]#

Deletes a sequence from the container based on the given name and context.

Parameters:
  • name – Name of the sequence to delete.

  • context (optional) – Contextual information for the sequence. {} if not specified.

delete()[source]#

Deletes the container and its associated data.

property sequences: ContainerSequenceMap#

Returns a map of sequences associated with the container.

__hash__()[source]#

Return hash(self).

Return type:

int

close()[source]#

Closes the container and releases any associated resources.

class aim._sdk.container.ContainerSequenceMap(container, sequence_cls)[source]#
__call__(query_=None, type_=<class 'aim._sdk.sequence.Sequence'>, **kwargs)[source]#

Retrieves a sequence collection based on a query expression.

Parameters:
  • query (str, optional) – Query expression for filtering.

  • type (Union[str, Type[Sequence]]) – Sequence type or type name. Defaults to Sequence.

  • **kwargs – Additional keyword arguments.

  • query_ (Optional[str]) –

  • type_ (Union[str, Type[Sequence]]) –

Returns:

The filtered sequence collection.

Return type:

SequenceCollection

__iter__()[source]#

Returns an iterator over the sequences.

Yields:

Sequence – The next sequence in the container.

Return type:

Iterator[Sequence]

__getitem__(item)[source]#

Retrieves a sequence based on the given item (name or tuple of name and context).

Parameters:

item (Union[str, Tuple[str, Dict]]) – Name of the sequence or a tuple of name and context.

Returns:

The retrieved sequence.

Return type:

Sequence

typed_sequence(sequence_type, name, context)[source]#

Retrieves a sequence of specified type based on the given name and context.

Parameters:
  • sequence_type (Type[Sequence]) – The desired sequence type.

  • name (str) – Name of the sequence.

  • context (Dict) – Contextual information for the sequence.

Returns:

The sequence instance.

Return type:

Sequence

__delitem__(item)[source]#

Deletes a sequence based on the given item (name or tuple of name and context).

Parameters:

item (Union[str, Tuple[str, Dict]]) – Name of the sequence or a tuple of name and context.

Sequence class interface#

Sequence.track

Tracks a given value at a specific step in the sequence.

Sequence.filter

Filters sequences based on a given expression.

Sequence.find

Finds a Sequence based on container hash, name, and context.

Sequence.match

Checks if the sequence matches a given expression.

class aim._sdk.sequence.Sequence(container, *, name, context)[source]#

Initializes a Sequence with the given container, name, and context.

Parameters:
  • container (Container) – The enclosing container for the sequence.

  • name (str) – The name of the sequence.

  • context (_ContextInfo) – The context for the sequence.

classmethod from_storage(storage, meta_tree, *, hash_, name, context)[source]#

Creates a Sequence instance from the provided storage and metadata.

Parameters:
  • storage – The storage object where the sequence is stored.

  • meta_tree (TreeView) – The tree view of metadata.

  • hash (str) – The hash of the enclosing container.

  • name (str) – The name of the sequence.

  • context (_ContextInfo) – The context for the sequence.

  • hash_ (str) –

Returns:

A Sequence instance.

Return type:

Sequence

classmethod filter(expr='', repo=None)[source]#

Filters sequences based on a given expression.

Parameters:
  • expr (str, optional) – The query expression for filtering. Defaults to an empty string.

  • repo (Repo, optional) – The repository to filter from. If not provided, uses the active repo.

Returns:

A collection of sequences satisfying the filter.

Return type:

SequenceCollection

classmethod find(hash_, name, context)[source]#

Finds a Sequence based on container hash, name, and context.

Parameters:
  • hash (str) – The hash identifier of the enclosing container.

  • name (str) – The name of the sequence.

  • context (Dict) – The context for the sequence.

  • hash_ (str) –

Returns:

Returns a Sequence if found, otherwise None.

Return type:

Sequence or None

property name#

Gets the name of the sequence.

Type:

str

property context: Dict#

Gets the context dictionary of the sequence.

Type:

Dict

property type: str#

Gets the type of the tracked items.

Type:

str

property allowed_value_types: Tuple[str]#

Gets the allowed value types for the sequence.

Type:

Tuple[str]

property is_empty: bool#

Returns True if the sequence is empty, otherwise False.

Type:

bool

property start: int#

Gets the first step of the sequence.

Type:

int

property stop: int#

Gets the last step of the sequence.

Type:

int

property next_step: int#

Gets the next available step for the sequence.

Type:

int

match(expr)[source]#

Checks if the sequence matches a given expression.

Parameters:

expr – The expression to check.

Returns:

True if the sequence matches the expression, otherwise False.

Return type:

bool

property axis_names: Tuple[str]#

Gets the names of the axis for the sequence.

Type:

Tuple[str]

axis(name)[source]#

Gets the axis values for a given axis name.

Parameters:

name (str) – The name of the axis.

Returns:

An iterator over the axis values.

Return type:

Iterator[Any]

items()[source]#

Iterator[Tuple[int, Any]]: Returns an iterator over the sequence items (steps and their values).

Return type:

Iterator[Tuple[int, Any]]

values()[source]#

Iterator[Any]: Returns an iterator over the sequence values.

Return type:

Iterator[Any]

sample(k)[source]#

Samples k items from the sequence.

Parameters:

k (int) – The number of items to sample.

Returns:

A list of sampled items.

Return type:

List[Any]

track(value, *, step=None, **axis)[source]#

Tracks a given value at a specific step in the sequence.

Parameters:
  • value (Any) – The value to be tracked.

  • step (Optional[int], optional) – The step at which the value should be tracked. If not provided, it will be determined automatically.

  • **axis – Additional axis values.

Raises:

ValueError – If the provided value type is not supported by the sequence.

get_logged_typename()[source]#

Retrieves the type name of the logged sequence.

Returns:

The type name of the logged sequence.

Return type:

str

__iter__()[source]#

Returns an iterator over the steps and their associated values in the sequence.

Returns:

An iterator over the sequence items.

Return type:

Iterator[Tuple[int, Tuple[Any, …]]]

__getitem__(item)[source]#

Retrieves items from the sequence by index, slice, or column name(s).

Parameters:

item (Union[slice, str, Tuple[str]]) – The index, slice, or column name(s) to retrieve.

Returns:

A view on the selected sequence data.

Return type:

SequenceView

class aim._sdk.sequence.SequenceView(sequence, *, columns, start=None, stop=None)[source]#
Parameters:
  • sequence (Sequence) –

  • columns (Tuple[str]) –

  • start (int) –

  • stop (int) –

aim.Record#

class aim._sdk.record.Record(*args, **kwargs)[source]#
classmethod __init_subclass__(**kwargs)[source]#

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.