Skip to content

Design Candidates (🧪Beta)

albert.collections.design_candidates.DesignCandidateCollection

DesignCandidateCollection(*, session: AlbertSession)

Bases: BaseCollection

Access design candidates in the Albert platform (🧪 Beta).

A candidate is one formulation a design run proposed, with its sampled inputs and, where the run produced them, its predictions and score. Candidates are read-only.

This collection is accessed as client.design_candidates.

Beta Feature!

Please do not use in production or without explicit guidance from Albert. You might otherwise have a bad experience. This feature currently falls outside of the Albert support contract, but we'd love your feedback!

Example

from albert import Albert

client = Albert()
candidate = client.design_candidates.get_by_id(id="DCN123")
candidate.predictions

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 candidate requests.

Methods:

Name Description
get_by_id

Get a candidate by its ID.

get_all

Get the candidates of a set.

Source code in src/albert/collections/design_candidates.py
def __init__(self, *, session: AlbertSession):
    super().__init__(session=session)
    self.base_path = f"/api/{DesignCandidateCollection._api_version}/design/candidates"

base_path

base_path = f"/api/{DesignCandidateCollection._api_version}/design/candidates"

get_by_id

get_by_id(*, id: DesignCandidateId) -> DesignCandidate

Get a candidate by its ID.

rank is not returned here; it is only derived when listing a set's candidates.

Example

candidate = client.design_candidates.get_by_id(id="DCN123")

Parameters:

Name Type Description Default
id DesignCandidateId

The candidate ID (format DCN...).

required

Returns:

Type Description
DesignCandidate

The fully populated DesignCandidate.

Source code in src/albert/collections/design_candidates.py
@validate_call
def get_by_id(self, *, id: DesignCandidateId) -> DesignCandidate:
    """Get a candidate by its ID.

    ``rank`` is not returned here; it is only derived when listing a set's candidates.

    !!! example
        ```python
        candidate = client.design_candidates.get_by_id(id="DCN123")
        ```

    Parameters
    ----------
    id : DesignCandidateId
        The candidate ID (format ``DCN...``).

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

get_all

get_all(
    *,
    candidate_set_id: DesignCandidateSetId,
    max_items: int | None = None,
) -> Iterator[DesignCandidate]

Get the candidates of a set.

Results are returned as a lazily paginated iterator, in stored order. Each candidate carries its rank when the set was scored.

Example

for candidate in client.design_candidates.get_all(candidate_set_id="DCS123"):
    print(candidate.id, candidate.rank)

Parameters:

Name Type Description Default
candidate_set_id DesignCandidateSetId

The candidate set (format DCS...) whose candidates to list.

required
max_items int

Stop after this many candidates.

None

Returns:

Type Description
Iterator[DesignCandidate]

A lazily paginated iterator over the set's candidates.

Source code in src/albert/collections/design_candidates.py
@validate_call
def get_all(
    self, *, candidate_set_id: DesignCandidateSetId, max_items: int | None = None
) -> Iterator[DesignCandidate]:
    """Get the candidates of a set.

    Results are returned as a lazily paginated iterator, in stored order. Each
    candidate carries its ``rank`` when the set was scored.

    !!! example
        ```python
        for candidate in client.design_candidates.get_all(candidate_set_id="DCS123"):
            print(candidate.id, candidate.rank)
        ```

    Parameters
    ----------
    candidate_set_id : DesignCandidateSetId
        The candidate set (format ``DCS...``) whose candidates to list.
    max_items : int, optional
        Stop after this many candidates.

    Returns
    -------
    Iterator[DesignCandidate]
        A lazily paginated iterator over the set's candidates.
    """
    return LastKeyCursorPaginator(
        mode=PaginationMode.KEY,
        path=self.base_path,
        session=self.session,
        params={"candidateSetId": candidate_set_id},
        max_items=max_items,
        deserialize=lambda items: [DesignCandidate(**item) for item in items],
    )