Breakthrough Insights

albert.collections.btinsight.BTInsightCollection

BTInsightCollection(*, session: AlbertSession)

Bases: BaseCollection

Manage Breakthrough insights in the Albert platform.

Albert Breakthrough is Albert's inverse-design / ML optimization capability. An insight (BTInsight) is an output produced by Breakthrough, such as an optimizer result, impact chart, or generated candidate. An insight is categorized by its BTInsightCategory and can trace back to the dataset, model session, and model it came from (dataset_id, model_session_id, model_id), which link to BTDatasetCollection and BTModelCollection.

Insights are identified by an insight ID (format INS..., e.g. "INS7").

This collection is accessed as client.btinsights.

Example

from albert import Albert

client = Albert()
insight = client.btinsights.get_by_id(id="INS7")
insight.name
# 'Cost optimizer run'

Parameters:

Name	Type	Description	Default
session	AlbertSession	The authenticated Albert session used for API calls.	required

Attributes:

Name	Type	Description
base_path	str	The base API route for insight requests.

Methods:

Name	Description
create	Create a new insight.
get_by_id	Get a single insight by its ID.
search	Search for insights by text, name, state, or category.
update	Update an existing insight.
delete	Delete an insight by its ID.

Parameters:

Name	Type	Description	Default
session	AlbertSession	The authenticated Albert session used for API calls.	required

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

def __init__(self, *, session: AlbertSession):
    """Initialize a BTInsightCollection.

    Parameters
    ----------
    session : AlbertSession
        The authenticated Albert session used for API calls.
    """
    super().__init__(session=session)
    self.base_path = f"/api/{BTInsightCollection._api_version}/btinsight"

base_path

base_path = (
    f"/api/{BTInsightCollection._api_version}/btinsight"
)

create

create(*, insight: BTInsight) -> BTInsight

Create a new insight.

Example

from albert import Albert
from albert.resources.btinsight import BTInsight, BTInsightCategory

client = Albert()
insight = BTInsight(
    name="Cost optimizer run",
    category=BTInsightCategory.OPTIMIZER,
)
created = client.btinsights.create(insight=insight)
created.id
# 'INS7'

Parameters:

Name	Type	Description	Default
insight	BTInsight	The insight to create. name and category are required.	required

Returns:

Type	Description
BTInsight	The newly created insight, populated with its assigned ID.

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

@validate_call
def create(self, *, insight: BTInsight) -> BTInsight:
    """Create a new insight.

    !!! example
        ```python
        from albert import Albert
        from albert.resources.btinsight import BTInsight, BTInsightCategory

        client = Albert()
        insight = BTInsight(
            name="Cost optimizer run",
            category=BTInsightCategory.OPTIMIZER,
        )
        created = client.btinsights.create(insight=insight)
        created.id
        # 'INS7'
        ```

    Parameters
    ----------
    insight : BTInsight
        The insight to create. ``name`` and ``category`` are required.

    Returns
    -------
    BTInsight
        The newly created insight, populated with its assigned ID.
    """
    response = self.session.post(
        self.base_path,
        json=insight.model_dump(mode="json", by_alias=True, exclude_none=True),
    )
    return BTInsight(**response.json())

get_by_id

get_by_id(*, id: BTInsightId) -> BTInsight

Get a single insight by its ID.

Example

insight = client.btinsights.get_by_id(id="INS7")
insight.name
# 'Cost optimizer run'

Parameters:

Name	Type	Description	Default
id	BTInsightId	The insight ID (format INS..., e.g. "INS7").	required

Returns:

Type	Description
BTInsight	The fully populated insight.

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

@validate_call
def get_by_id(self, *, id: BTInsightId) -> BTInsight:
    """Get a single insight by its ID.

    !!! example
        ```python
        insight = client.btinsights.get_by_id(id="INS7")
        insight.name
        # 'Cost optimizer run'
        ```

    Parameters
    ----------
    id : BTInsightId
        The insight ID (format ``INS...``, e.g. ``"INS7"``).

    Returns
    -------
    BTInsight
        The fully populated insight.
    """
    response = self.session.get(f"{self.base_path}/{id}")
    return BTInsight(**response.json())

search

search(
    *,
    order_by: OrderBy | None = None,
    sort_by: str | None = None,
    text: str | None = None,
    name: str | list[str] | None = None,
    state: BTInsightState
    | list[BTInsightState]
    | None = None,
    category: BTInsightCategory
    | list[BTInsightCategory]
    | None = None,
    created_by: str | list[str] | None = None,
    updated_by: str | list[str] | None = None,
    from_created_at: str | None = None,
    to_created_at: str | None = None,
    from_updated_at: str | None = None,
    to_updated_at: str | None = None,
    model_session: str | list[str] | None = None,
    tag: str | list[str] | None = None,
    offset: int | None = None,
    max_items: int | None = None,
) -> Iterator[BTInsight]

Search for insights matching the given filters.

Results are returned as a lazily paginated iterator, so iterating fetches additional pages on demand.

Example

from albert.resources.btinsight import BTInsightCategory

hits = client.btinsights.search(
    category=BTInsightCategory.OPTIMIZER,
    max_items=10,
)
for insight in hits:
    print(insight.id, insight.name)

Parameters:

Name	Type	Description	Default
order_by	OrderBy	Sort direction (ascending or descending). Default None (server order).	None
sort_by	str	Field to sort by. Default None.	None
text	str	Free-text query matched against insight name and related fields.	None
name	str or list[str]	Filter by exact insight name(s).	None
state	BTInsightState or list[BTInsightState]	Filter by progress state (e.g. Complete, Error).	None
category	BTInsightCategory or list[BTInsightCategory]	Filter by category (e.g. Optimizer, Impact Chart).	None
created_by	str or list[str]	Filter by creator. Accepts user display name(s) or UserId(s) (e.g. "USR4227" or "Jane Doe").	None
updated_by	str or list[str]	Filter by user(s) who last updated the insight. Accepts UserId(s) only (e.g. "USR4227"), not display names.	None
from_created_at	str	Only include insights created on or after this date (ISO 8601).	None
to_created_at	str	Only include insights created on or before this date (ISO 8601).	None
from_updated_at	str	Only include insights updated on or after this date (ISO 8601).	None
to_updated_at	str	Only include insights updated on or before this date (ISO 8601).	None
model_session	str or list[str]	Filter by model session ID(s) (format MDS...).	None
tag	str or list[str]	Filter by tag name(s).	None
max_items	int	Maximum number of items to return in total. If None, iterates over all matches.	None

Returns:

Type	Description
Iterator[BTInsight]	A lazily paginated iterator of matching insights.

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

@validate_call
def search(
    self,
    *,
    order_by: OrderBy | None = None,
    sort_by: str | None = None,
    text: str | None = None,
    name: str | list[str] | None = None,
    state: BTInsightState | list[BTInsightState] | None = None,
    category: BTInsightCategory | list[BTInsightCategory] | None = None,
    created_by: str | list[str] | None = None,
    updated_by: str | list[str] | None = None,
    from_created_at: str | None = None,
    to_created_at: str | None = None,
    from_updated_at: str | None = None,
    to_updated_at: str | None = None,
    model_session: str | list[str] | None = None,
    tag: str | list[str] | None = None,
    offset: int | None = None,
    max_items: int | None = None,
) -> Iterator[BTInsight]:
    """Search for insights matching the given filters.

    Results are returned as a lazily paginated iterator, so iterating fetches
    additional pages on demand.

    !!! example
        ```python
        from albert.resources.btinsight import BTInsightCategory

        hits = client.btinsights.search(
            category=BTInsightCategory.OPTIMIZER,
            max_items=10,
        )
        for insight in hits:
            print(insight.id, insight.name)
        ```

    Parameters
    ----------
    order_by : OrderBy, optional
        Sort direction (ascending or descending). Default None (server order).
    sort_by : str, optional
        Field to sort by. Default None.
    text : str, optional
        Free-text query matched against insight name and related fields.
    name : str or list[str], optional
        Filter by exact insight name(s).
    state : BTInsightState or list[BTInsightState], optional
        Filter by progress state (e.g. ``Complete``, ``Error``).
    category : BTInsightCategory or list[BTInsightCategory], optional
        Filter by category (e.g. ``Optimizer``, ``Impact Chart``).
    created_by : str or list[str], optional
        Filter by creator. Accepts user display name(s) or UserId(s) (e.g.
        ``"USR4227"`` or ``"Jane Doe"``).
    updated_by : str or list[str], optional
        Filter by user(s) who last updated the insight. Accepts UserId(s)
        only (e.g. ``"USR4227"``), not display names.
    from_created_at : str, optional
        Only include insights created on or after this date (ISO 8601).
    to_created_at : str, optional
        Only include insights created on or before this date (ISO 8601).
    from_updated_at : str, optional
        Only include insights updated on or after this date (ISO 8601).
    to_updated_at : str, optional
        Only include insights updated on or before this date (ISO 8601).
    model_session : str or list[str], optional
        Filter by model session ID(s) (format ``MDS...``).
    tag : str or list[str], optional
        Filter by tag name(s).
    max_items : int, optional
        Maximum number of items to return in total. If None, iterates over all
        matches.

    Returns
    -------
    Iterator[BTInsight]
        A lazily paginated iterator of matching insights.
    """
    params = {
        "offset": offset,
        "order": order_by,
        "sortBy": sort_by,
        "text": text,
        "name": ensure_list(name),
    }

    state_values = ensure_list(state)
    params["state"] = state_values if state_values else None

    category_values = ensure_list(category)
    params["category"] = category_values if category_values else None
    params["createdBy"] = ensure_list(created_by)
    params["updatedBy"] = ensure_list(updated_by)
    params["fromCreatedAt"] = from_created_at
    params["toCreatedAt"] = to_created_at
    params["fromUpdatedAt"] = from_updated_at
    params["toUpdatedAt"] = to_updated_at
    params["modelSession"] = ensure_list(model_session)
    params["tag"] = ensure_list(tag)

    return AlbertPaginator(
        mode=PaginationMode.OFFSET,
        path=f"{self.base_path}/search",
        session=self.session,
        params=params,
        max_items=max_items,
        deserialize=lambda items: [BTInsight(**item) for item in items],
    )

update

update(*, insight: BTInsight) -> BTInsight

Update an existing insight.

Fetch the insight (e.g. with get_by_id), modify the updatable fields on the returned object, then pass it here. Only the fields listed in Notes are applied; changes to other fields are ignored.

Example

insight = client.btinsights.get_by_id(id="INS7")
insight.name = "Cost optimizer run (final)"
updated = client.btinsights.update(insight=insight)
updated.name
# 'Cost optimizer run (final)'

Parameters:

Name	Type	Description	Default
insight	BTInsight	The insight to update. Must have a valid id.	required

Returns:

Type	Description
BTInsight	The updated insight.

Notes

The following fields can be updated: content_edited, end_time, metadata, name, output_key, payload_type, raw_payload, registry, start_time, state, total_time.

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

@validate_call
def update(self, *, insight: BTInsight) -> BTInsight:
    """Update an existing insight.

    Fetch the insight (e.g. with [`get_by_id`][albert.collections.btinsight.BTInsightCollection.get_by_id]), modify the updatable
    fields on the returned object, then pass it here. Only the fields listed in
    Notes are applied; changes to other fields are ignored.

    !!! example
        ```python
        insight = client.btinsights.get_by_id(id="INS7")
        insight.name = "Cost optimizer run (final)"
        updated = client.btinsights.update(insight=insight)
        updated.name
        # 'Cost optimizer run (final)'
        ```

    Parameters
    ----------
    insight : BTInsight
        The insight to update. Must have a valid ``id``.

    Returns
    -------
    BTInsight
        The updated insight.

    Notes
    -----
    The following fields can be updated: ``content_edited``, ``end_time``,
    ``metadata``, ``name``, ``output_key``, ``payload_type``, ``raw_payload``,
    ``registry``, ``start_time``, ``state``, ``total_time``.
    """
    path = f"{self.base_path}/{insight.id}"
    payload = self._generate_patch_payload(
        existing=self.get_by_id(id=insight.id),
        updated=insight,
        generate_metadata_diff=False,
    )
    self.session.patch(path, json=payload.model_dump(mode="json", by_alias=True))
    return self.get_by_id(id=insight.id)

delete

delete(*, id: BTInsightId) -> None

Delete an insight by its ID.

Example

client.btinsights.delete(id="INS7")

Parameters:

Name	Type	Description	Default
id	BTInsightId	The insight ID to delete (format INS...).	required

Returns:

Type	Description
None

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

@validate_call
def delete(self, *, id: BTInsightId) -> None:
    """Delete an insight by its ID.

    !!! example
        ```python
        client.btinsights.delete(id="INS7")
        ```

    Parameters
    ----------
    id : BTInsightId
        The insight ID to delete (format ``INS...``).

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