Breakthrough Model

albert.collections.btmodel

BTModelId module-attribute

BTModelId = Annotated[
    str, AfterValidator(ensure_btmodel_id)
]

BTModelSessionId module-attribute

BTModelSessionId = Annotated[
    str, AfterValidator(ensure_btmodel_session_id)
]

AlbertSession

AlbertSession(
    *,
    base_url: str,
    token: str | None = None,
    auth_manager: AlbertClientCredentials
    | AlbertSSOClient
    | None = None,
    retries: int | None = None,
)

Bases: Session

A session that has a base URL, which is prefixed to all request URLs.

Parameters:

Name	Type	Description	Default
base_url	str	The base URL to prefix to all relative request paths (e.g., "https://app.albertinvent.com").	required
token	str | None	A static JWT token for authentication. Ignored if auth_manager is provided.	None
auth_manager	AlbertClientCredentials | AlbertSSOClient	An authentication manager used to dynamically fetch and refresh tokens. If provided, it overrides token.	None
retries	int	The number of automatic retries on failed requests (default is 3).	None

Methods:

Name	Description
request

Source code in src/albert/core/session.py

def __init__(
    self,
    *,
    base_url: str,
    token: str | None = None,
    auth_manager: AlbertClientCredentials | AlbertSSOClient | None = None,
    retries: int | None = None,
):
    super().__init__()
    self.base_url = base_url
    self.headers.update(
        {
            "Content-Type": "application/json",
            "Accept": "application/json",
            "User-Agent": f"albert-SDK V.{albert.__version__}",
        }
    )

    if token is None and auth_manager is None:
        raise ValueError("Either `token` or `auth_manager` must be specified.")

    self._auth_manager = auth_manager
    self._provided_token = token

    # Set up retry logic
    retries = retries if retries is not None else 3
    retry = Retry(
        total=retries,
        read=retries,
        connect=retries,
        backoff_factor=0.3,
        status_forcelist=(500, 502, 503, 504, 403),
        raise_on_status=False,
    )
    adapter = HTTPAdapter(max_retries=retry)
    self.mount("http://", adapter)
    self.mount("https://", adapter)

base_url instance-attribute

base_url = base_url

request

request(
    method: str, path: str, *args, **kwargs
) -> Response

Source code in src/albert/core/session.py

def request(self, method: str, path: str, *args, **kwargs) -> requests.Response:
    self.headers["Authorization"] = f"Bearer {self._access_token}"
    full_url = urljoin(self.base_url, path) if not path.startswith("http") else path
    with handle_http_errors():
        response = super().request(method, full_url, *args, **kwargs)
        response.raise_for_status()
        return response

BTModel

Bases: BaseResource

A single Breakthrough model.

A BTModel may have a parent_id or be a detached, standalone model.

Attributes:

Name	Type	Description
name	str	The name of the model.
id	BTModelId | None	The unique identifier for the model.
dataset_id	BTDatasetId | None	The identifier for the dataset associated with the model.
parent_id	BTModelSessionId | None	The identifier for the parent model session, if applicable.
metadata	dict[str, Any] | None	Metadata associated with the model, if applicable.
type	BTModelType | None	The type of the model (e.g., Session, Detached).
state	BTModelState | None	The current state of the model (e.g., Queued, Building Models, Complete).
target	list[str] | None	The target variables for the model, if applicable.
start_time	str | None	The start time of the model creation, if applicable.
end_time	str | None	The end time of the model creation, if applicable.
total_time	str | None	The total time taken for the model creation, if applicable.
model_binary_key	str | None	The storage key for the model data, if applicable.

dataset_id class-attribute instance-attribute

dataset_id: BTDatasetId | None = Field(
    default=None, alias="datasetId"
)

end_time class-attribute instance-attribute

end_time: str | None = Field(default=None, alias='endTime')

flag class-attribute instance-attribute

flag: bool = Field(default=False)

id class-attribute instance-attribute

id: BTModelId | None = Field(default=None)

metadata class-attribute instance-attribute

metadata: dict[str, Any] | None = Field(
    default=None, alias="Metadata"
)

model_binary_key class-attribute instance-attribute

model_binary_key: str | None = Field(
    default=None, alias="modelBinaryKey"
)

name instance-attribute

name: str

parent_id class-attribute instance-attribute

parent_id: BTModelSessionId | None = Field(
    default=None, alias="parentId"
)

start_time class-attribute instance-attribute

start_time: str | None = Field(
    default=None, alias="startTime"
)

state class-attribute instance-attribute

state: BTModelState | None = Field(default=None)

target class-attribute instance-attribute

target: list[str] | None = Field(default=None)

total_time class-attribute instance-attribute

total_time: str | None = Field(
    default=None, alias="totalTime"
)

type class-attribute instance-attribute

type: BTModelType | None = Field(default=None)

BTModelCollection

BTModelCollection(*, session: AlbertSession)

Bases: BaseCollection

BTModelCollection is a collection class for managing Breakthrough model entities.

Breakthrough models can be associated with a parent Breakthrough model session, or a detached without a parent.

Parameters:

Name	Type	Description	Default
session	AlbertSession	The Albert session instance.	required

Methods:

Name	Description
create	Create a new BTModel instance.
delete	Delete a BTModel by ID.
get_by_id	Retrieve a BTModel by its ID.
update	Update an existing BTModel.

Source code in src/albert/collections/btmodel.py

def __init__(self, *, session: AlbertSession):
    super().__init__(session=session)

create

create(
    *,
    model: BTModel,
    parent_id: BTModelSessionId | None = None,
) -> BTModel

Create a new BTModel instance.

Parameters:

Name	Type	Description	Default
model	BTModel	The BTModel instance to create.	required
parent_id	BTModelSessionId | None	The optional ID of the parent BTModelSession.	None

Returns:

Type	Description
BTModel	The created BTModel instance.

Source code in src/albert/collections/btmodel.py

@validate_call
def create(self, *, model: BTModel, parent_id: BTModelSessionId | None = None) -> BTModel:
    """
    Create a new BTModel instance.

    Parameters
    ----------
    model : BTModel
        The BTModel instance to create.
    parent_id : BTModelSessionId | None
        The optional ID of the parent BTModelSession.

    Returns
    -------
    BTModel
        The created BTModel instance.
    """
    base_path = self._get_base_path(parent_id)
    response = self.session.post(
        base_path,
        json=model.model_dump(mode="json", by_alias=True, exclude_none=True),
    )
    return BTModel(**response.json())

delete

delete(
    *,
    id: BTModelId,
    parent_id: BTModelSessionId | None = None,
) -> None

Delete a BTModel by ID.

Parameters:

Name	Type	Description	Default
id	BTModelId	The ID of the BTModel to delete.	required
parent_id	BTModelSessionId | None	The optional ID of the parent BTModelSession.	None

Returns:

Type	Description
None

Source code in src/albert/collections/btmodel.py

@validate_call
def delete(self, *, id: BTModelId, parent_id: BTModelSessionId | None = None) -> None:
    """Delete a BTModel by ID.

    Parameters
    ----------
    id : BTModelId
        The ID of the BTModel to delete.
    parent_id : BTModelSessionId | None
        The optional ID of the parent BTModelSession.

    Returns
    -------
    None
    """
    base_path = self._get_base_path(parent_id)
    self.session.delete(f"{base_path}/{id}")

get_by_id

get_by_id(
    *,
    id: BTModelId,
    parent_id: BTModelSessionId | None = None,
) -> BTModel

Retrieve a BTModel by its ID.

Parameters:

Name	Type	Description	Default
id	BTModelId	The ID of the BTModel to retrieve.	required
parent_id	BTModelSessionId | None	The optional ID of the parent BTModelSession.	None

Returns:

Type	Description
BTModel	The retrieved BTModel instance.

Source code in src/albert/collections/btmodel.py

@validate_call
def get_by_id(self, *, id: BTModelId, parent_id: BTModelSessionId | None = None) -> BTModel:
    """
    Retrieve a BTModel by its ID.

    Parameters
    ----------
    id : BTModelId
        The ID of the BTModel to retrieve.
    parent_id : BTModelSessionId | None
        The optional ID of the parent BTModelSession.

    Returns
    -------
    BTModel
        The retrieved BTModel instance.
    """
    base_path = self._get_base_path(parent_id)
    response = self.session.get(f"{base_path}/{id}")
    return BTModel(**response.json())

update

update(
    *,
    model: BTModel,
    parent_id: BTModelSessionId | None = None,
) -> BTModel

Update an existing BTModel.

Parameters:

Name	Type	Description	Default
model	BTModel	The BTModel instance with updated data.	required
parent_id	BTModelSessionId | None	The optional ID of the parent BTModelSession.	None

Returns:

Type	Description
BTModel	The updated BTModel instance.

Source code in src/albert/collections/btmodel.py

@validate_call
def update(self, *, model: BTModel, parent_id: BTModelSessionId | None = None) -> BTModel:
    """
    Update an existing BTModel.

    Parameters
    ----------
    model : BTModel
        The BTModel instance with updated data.
    parent_id : BTModelSessionId | None
        The optional ID of the parent BTModelSession.

    Returns
    -------
    BTModel
        The updated BTModel instance.
    """
    base_path = self._get_base_path(parent_id)
    payload = self._generate_patch_payload(
        existing=self.get_by_id(id=model.id, parent_id=parent_id),
        updated=model,
        generate_metadata_diff=False,
    )
    self.session.patch(
        f"{base_path}/{model.id}",
        json=payload.model_dump(mode="json", by_alias=True),
    )
    return self.get_by_id(id=model.id, parent_id=parent_id)

BTModelSession

Bases: BaseResource

Parent session for a set of BTModels.

Attributes:

Name	Type	Description
name	str	The name of the model session.
category	BTModelSessionCategory	The category of the model session (e.g., userModel, albertModel).
id	BTModelSessionId | None	The unique identifier for the model session.
dataset_id	BTDatasetId	The identifier for the dataset associated with the model session.
default_model	str | None	The default model name for the session, if applicable.
total_time	str | None	The total time taken for the session, if applicable.
model_count	int | None	The number of models in the session, if applicable.
target	list[str] | None	The target variables for the models in the session, if applicable.
registry	BTModelRegistry | None	The registry containing build logs and metrics for the session, if applicable.
albert_model_details	dict[str, Any] | None	Details specific to the Albert model, if applicable.

albert_model_details class-attribute instance-attribute

albert_model_details: dict[str, Any] | None = Field(
    default=None, alias="albertModelDetails"
)

category instance-attribute

category: BTModelSessionCategory

dataset_id class-attribute instance-attribute

dataset_id: BTDatasetId = Field(..., alias='datasetId')

default_model class-attribute instance-attribute

default_model: str | None = Field(
    default=None, alias="defaultModel"
)

flag class-attribute instance-attribute

flag: bool = Field(default=False)

id class-attribute instance-attribute

id: BTModelSessionId | None = Field(default=None)

model_count class-attribute instance-attribute

model_count: int | None = Field(
    default=None, alias="modelCount"
)

name instance-attribute

name: str

registry class-attribute instance-attribute

registry: BTModelRegistry | None = Field(
    default=None, alias="Registry"
)

target class-attribute instance-attribute

target: list[str] | None = Field(default=None)

total_time class-attribute instance-attribute

total_time: str | None = Field(
    default=None, alias="totalTime"
)

BTModelSessionCollection

BTModelSessionCollection(*, session: AlbertSession)

Bases: BaseCollection

BTModelSessionCollection is a collection class for managing Breakthrough model session entities.

Parameters:

Name	Type	Description	Default
session	AlbertSession	The Albert session instance.	required

Attributes:

Name	Type	Description
base_path	str	The base path for BTModelSession API requests.

Methods:

Name	Description
create
delete	Delete a BTModelSession by ID.
get_by_id
update

Source code in src/albert/collections/btmodel.py

def __init__(self, *, session: AlbertSession):
    super().__init__(session=session)
    self.base_path = f"/api/{BTModelSessionCollection._api_version}/btmodel"

base_path instance-attribute

base_path = f'/api/{_api_version}/btmodel'

create

create(*, model_session: BTModelSession) -> BTModelSession

Source code in src/albert/collections/btmodel.py

@validate_call
def create(self, *, model_session: BTModelSession) -> BTModelSession:
    response = self.session.post(
        self.base_path,
        json=model_session.model_dump(mode="json", by_alias=True, exclude_none=True),
    )
    return BTModelSession(**response.json())

delete

delete(*, id: BTModelSessionId) -> None

Delete a BTModelSession by ID.

Parameters:

Name	Type	Description	Default
id	BTModelSessionId	The ID of the BTModelSession to delete.	required

Returns:

Type	Description
None

Source code in src/albert/collections/btmodel.py

@validate_call
def delete(self, *, id: BTModelSessionId) -> None:
    """Delete a BTModelSession by ID.

    Parameters
    ----------
    id : BTModelSessionId
        The ID of the BTModelSession to delete.

    Returns
    -------
    None
    """
    self.session.delete(f"{self.base_path}/{id}")

get_by_id

get_by_id(*, id: BTModelSessionId) -> BTModelSession

Source code in src/albert/collections/btmodel.py

@validate_call
def get_by_id(self, *, id: BTModelSessionId) -> BTModelSession:
    response = self.session.get(f"{self.base_path}/{id}")
    return BTModelSession(**response.json())

update

update(*, model_session: BTModelSession) -> BTModelSession

Source code in src/albert/collections/btmodel.py

@validate_call
def update(self, *, model_session: BTModelSession) -> BTModelSession:
    path = f"{self.base_path}/{model_session.id}"
    payload = self._generate_patch_payload(
        existing=self.get_by_id(id=model_session.id),
        updated=model_session,
    )
    self.session.patch(path, json=payload.model_dump(mode="json", by_alias=True))
    return self.get_by_id(id=model_session.id)

BaseCollection

BaseCollection(*, session: AlbertSession)

BaseCollection is the base class for all collection classes.

Parameters:

Name	Type	Description	Default
session	AlbertSession	The Albert API Session instance.	required

Source code in src/albert/collections/base.py

def __init__(self, *, session: AlbertSession):
    self.session = session

session instance-attribute

session = session