sift_client.resources.annotations

CLASS	DESCRIPTION
AnnotationLogsAPIAsync	High-level API for an annotation's history.
AnnotationsAPIAsync	High-level API for interacting with annotations.

AnnotationLogsAPIAsync

AnnotationLogsAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for an annotation's history.

Each log records one event: an assignment, a state change, or a comment. Reachable as client.annotations.logs.

Initialize the AnnotationLogsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
list_	List annotation logs.
comment	Add a comment to an annotation.
record_assignment	Record that an annotation was assigned to a user.
record_state	Record a state change on an annotation.
delete	Delete an annotation log.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

list_ async

list_(
    *,
    annotation: str | Annotation | None = None,
    annotation_log_ids: list[str] | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    created_by: Any | str | None = None,
    kind: AnnotationLogKind | None = None,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[AnnotationLog]

List annotation logs.

PARAMETER	DESCRIPTION
annotation	Restrict results to this Annotation or annotation ID. TYPE: str | Annotation | None DEFAULT: None
annotation_log_ids	Filter to logs with any of these IDs. TYPE: list[str] | None DEFAULT: None
created_after	Filter logs created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Filter logs created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Filter logs modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter logs modified before this datetime. TYPE: datetime | None DEFAULT: None
created_by	Filter logs created by this user ID. TYPE: Any | str | None DEFAULT: None
kind	Filter to comments, state updates, or assignments. TYPE: AnnotationLogKind | None DEFAULT: None
filter_query	Explicit CEL query to filter logs. TYPE: str | None DEFAULT: None
order_by	Field and direction to order results by. TYPE: str | None DEFAULT: None
limit	Maximum number of logs to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[AnnotationLog]	A list of AnnotationLog objects that match the filter criteria.

comment async

comment(
    annotation: str | Annotation,
    text: str | list[AnnotationCommentElement],
) -> AnnotationLog

Add a comment to an annotation.

PARAMETER	DESCRIPTION
annotation	The Annotation or annotation ID to comment on. TYPE: str | Annotation
text	Plain text, or a list of elements to mix text with user mentions. TYPE: str | list[AnnotationCommentElement]

RETURNS	DESCRIPTION
AnnotationLog	The created AnnotationLog.

record_assignment async

record_assignment(
    annotation: str | Annotation, user: str
) -> AnnotationLog

Record that an annotation was assigned to a user.

This writes a history entry and nothing else. annotations.assign already writes one, so you rarely need this.

PARAMETER	DESCRIPTION
annotation	The Annotation or annotation ID. TYPE: str | Annotation
user	The user ID the annotation was assigned to. TYPE: str

RETURNS	DESCRIPTION
AnnotationLog	The created AnnotationLog.

record_state async

record_state(
    annotation: str | Annotation, state: AnnotationLogState
) -> AnnotationLog

Record a state change on an annotation.

This writes a history entry and nothing else. It leaves the state alone, so use annotations.resolve, flag, or reopen to change it.

PARAMETER	DESCRIPTION
annotation	The Annotation or annotation ID. TYPE: str | Annotation
state	The state to record. TYPE: AnnotationLogState

RETURNS	DESCRIPTION
AnnotationLog	The created AnnotationLog.

delete async

delete(
    annotation: str | Annotation, log: str | AnnotationLog
) -> None

Delete an annotation log.

PARAMETER	DESCRIPTION
annotation	The Annotation or annotation ID the log belongs to. TYPE: str | Annotation
log	The AnnotationLog or log ID to delete. TYPE: str | AnnotationLog

AnnotationsAPIAsync

AnnotationsAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for interacting with annotations.

An annotation marks a time range on one or more assets. A data review annotation carries a review state and an assignee. A phase annotation marks a segment of a run and carries no state.

Initialize the AnnotationsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
get	Get an Annotation.
list_	List annotations.
find	Find one annotation. Takes the same arguments as list_.
create	Create a new annotation.
create_review	Flag a time range for review.
create_phase	Mark a time range as a phase.
update	Update an Annotation.
archive	Archive an annotation.
unarchive	Unarchive an annotation.
batch_archive	Archive many annotations in one call.
batch_unarchive	Unarchive many annotations in one call.
assign	Assign an annotation to a user for review.
resolve	Close out a review as resolved.
flag	Flag a review as needing attention.
reopen	Return a review to the open state.

ATTRIBUTE	DESCRIPTION
logs
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

logs instance-attribute

logs = AnnotationLogsAPIAsync(sift_client)

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

get async

get(annotation_id: str) -> Annotation

Get an Annotation.

PARAMETER	DESCRIPTION
annotation_id	The ID of the annotation. TYPE: str

RETURNS	DESCRIPTION
Annotation	The Annotation.

list_ async

list_(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    annotation_ids: list[str] | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    created_by: Any | str | None = None,
    tags: list[str] | list[Tag] | None = None,
    metadata: dict[str, Any] | None = None,
    annotation_type: AnnotationType | None = None,
    state: AnnotationState | None = None,
    assigned_to: Any | str | None = None,
    pending: bool | None = None,
    assets: list[Asset] | list[str] | None = None,
    runs: list[Run] | list[str] | None = None,
    rule_ids: list[str] | None = None,
    report_ids: list[str] | None = None,
    start_time_after: datetime | None = None,
    start_time_before: datetime | None = None,
    end_time_after: datetime | None = None,
    end_time_before: datetime | None = None,
    description_contains: str | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[Annotation]

List annotations.

PARAMETER	DESCRIPTION
name	Exact name of the annotation. TYPE: str | None DEFAULT: None
names	List of annotation names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the annotation. TYPE: str | None DEFAULT: None
name_regex	Regular expression to filter annotations by name. TYPE: str | Pattern | None DEFAULT: None
annotation_ids	Filter to annotations with any of these IDs. TYPE: list[str] | None DEFAULT: None
created_after	Filter annotations created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Filter annotations created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Filter annotations modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter annotations modified before this datetime. TYPE: datetime | None DEFAULT: None
created_by	Filter annotations created by this user ID. TYPE: Any | str | None DEFAULT: None
tags	Filter annotations with any of these Tags or tag names. TYPE: list[str] | list[Tag] | None DEFAULT: None
metadata	Filter annotations by metadata criteria. TYPE: dict[str, Any] | None DEFAULT: None
annotation_type	Filter to DATA_REVIEW or PHASE annotations. TYPE: AnnotationType | None DEFAULT: None
state	Filter to a review state. TYPE: AnnotationState | None DEFAULT: None
assigned_to	Filter to annotations assigned to this user ID. TYPE: Any | str | None DEFAULT: None
pending	Filter to annotations from an ongoing rule violation. TYPE: bool | None DEFAULT: None
assets	Filter annotations on any of these Assets or asset IDs. TYPE: list[Asset] | list[str] | None DEFAULT: None
runs	Filter annotations on any of these Runs or run IDs. TYPE: list[Run] | list[str] | None DEFAULT: None
rule_ids	Filter annotations created by any of these rules. TYPE: list[str] | None DEFAULT: None
report_ids	Filter annotations belonging to any of these reports. TYPE: list[str] | None DEFAULT: None
start_time_after	Filter annotations that start after this datetime. TYPE: datetime | None DEFAULT: None
start_time_before	Filter annotations that start before this datetime. TYPE: datetime | None DEFAULT: None
end_time_after	Filter annotations that end after this datetime. TYPE: datetime | None DEFAULT: None
end_time_before	Filter annotations that end before this datetime. TYPE: datetime | None DEFAULT: None
description_contains	Partial description of the annotation. TYPE: str | None DEFAULT: None
include_archived	If True, include archived annotations in results. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query to filter annotations. TYPE: str | None DEFAULT: None
order_by	Field and direction to order results by. TYPE: str | None DEFAULT: None
limit	Maximum number of annotations to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[Annotation]	A list of Annotation objects that match the filter criteria.

find async

find(**kwargs) -> Annotation | None

Find one annotation. Takes the same arguments as list_.

Raises if more than one matches.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list_. DEFAULT: {}

RETURNS	DESCRIPTION
Annotation | None	The Annotation found or None.

create async

create(create: AnnotationCreate | dict) -> Annotation

Create a new annotation.

PARAMETER	DESCRIPTION
create	The annotation definition. assets and tags take names, not IDs. TYPE: AnnotationCreate | dict

RETURNS	DESCRIPTION
Annotation	The created Annotation.

create_review async

create_review(
    name: str,
    start_time: datetime,
    end_time: datetime,
    *,
    assets: list[str] | None = None,
    channels: list[Channel] | None = None,
    run: Run | str | None = None,
    description: str | None = None,
    tags: list[str] | None = None,
    state: AnnotationState | None = None,
    assign_to: str | None = None,
    metadata: dict[str, Any] | None = None,
) -> Annotation

Flag a time range for review.

The annotation must reach an asset. Pass channels and the asset comes from them, or name the assets directly.

PARAMETER	DESCRIPTION
name	The name of the annotation. TYPE: str
start_time	When the range starts. TYPE: datetime
end_time	When the range ends. TYPE: datetime
assets	Asset names to associate. Derived from channels if omitted. TYPE: list[str] | None DEFAULT: None
channels	Channels to draw the annotation on. TYPE: list[Channel] | None DEFAULT: None
run	The Run or run ID the annotation belongs to. TYPE: Run | str | None DEFAULT: None
description	A description of what to review. TYPE: str | None DEFAULT: None
tags	Tag names to apply. TYPE: list[str] | None DEFAULT: None
state	The initial review state. Defaults to open. TYPE: AnnotationState | None DEFAULT: None
assign_to	The user ID to assign the review to. TYPE: str | None DEFAULT: None
metadata	User-defined metadata. TYPE: dict[str, Any] | None DEFAULT: None

RETURNS	DESCRIPTION
Annotation	The created Annotation.

create_phase async

create_phase(
    name: str,
    start_time: datetime,
    end_time: datetime,
    *,
    assets: list[str] | None = None,
    channels: list[Channel] | None = None,
    run: Run | str | None = None,
    description: str | None = None,
    tags: list[str] | None = None,
    metadata: dict[str, Any] | None = None,
) -> Annotation

Mark a time range as a phase.

A phase labels a segment of a run. It carries no review state, so it has no state argument.

PARAMETER	DESCRIPTION
name	The name of the phase. TYPE: str
start_time	When the phase starts. TYPE: datetime
end_time	When the phase ends. TYPE: datetime
assets	Asset names to associate. Derived from channels if omitted. TYPE: list[str] | None DEFAULT: None
channels	Channels to draw the phase on. TYPE: list[Channel] | None DEFAULT: None
run	The Run or run ID the phase belongs to. TYPE: Run | str | None DEFAULT: None
description	A description of the phase. TYPE: str | None DEFAULT: None
tags	Tag names to apply. TYPE: list[str] | None DEFAULT: None
metadata	User-defined metadata. TYPE: dict[str, Any] | None DEFAULT: None

RETURNS	DESCRIPTION
Annotation	The created Annotation.

update async

update(
    annotation: str | Annotation,
    update: AnnotationUpdate | dict,
) -> Annotation

Update an Annotation.

tags, linked_channels, and metadata are replaced, not merged.

PARAMETER	DESCRIPTION
annotation	The Annotation or annotation ID to update. TYPE: str | Annotation
update	Updates to apply to the Annotation. TYPE: AnnotationUpdate | dict

RETURNS	DESCRIPTION
Annotation	The updated Annotation.

archive async

archive(annotation: str | Annotation) -> Annotation

Archive an annotation.

PARAMETER	DESCRIPTION
annotation	The Annotation or annotation ID to archive. TYPE: str | Annotation

RETURNS	DESCRIPTION
Annotation	The archived Annotation.

unarchive async

unarchive(annotation: str | Annotation) -> Annotation

Unarchive an annotation.

PARAMETER	DESCRIPTION
annotation	The Annotation or annotation ID to unarchive. TYPE: str | Annotation

RETURNS	DESCRIPTION
Annotation	The unarchived Annotation.

batch_archive async

batch_archive(annotations: list[str | Annotation]) -> None

Archive many annotations in one call.

PARAMETER	DESCRIPTION
annotations	The Annotations or annotation IDs to archive. TYPE: list[str | Annotation]

batch_unarchive async

batch_unarchive(
    annotations: list[str | Annotation],
) -> None

Unarchive many annotations in one call.

PARAMETER	DESCRIPTION
annotations	The Annotations or annotation IDs to unarchive. TYPE: list[str | Annotation]

assign async

assign(
    annotation: str | Annotation, user: str
) -> Annotation

Assign an annotation to a user for review.

PARAMETER	DESCRIPTION
annotation	The Annotation or annotation ID to assign. TYPE: str | Annotation
user	The user ID to assign to. TYPE: str

RETURNS	DESCRIPTION
Annotation	The updated Annotation.

resolve async

resolve(annotation: str | Annotation) -> Annotation

Close out a review as resolved.

PARAMETER	DESCRIPTION
annotation	The Annotation or annotation ID to resolve. TYPE: str | Annotation

RETURNS	DESCRIPTION
Annotation	The updated Annotation.

flag async

flag(annotation: str | Annotation) -> Annotation

Flag a review as needing attention.

PARAMETER	DESCRIPTION
annotation	The Annotation or annotation ID to flag. TYPE: str | Annotation

RETURNS	DESCRIPTION
Annotation	The updated Annotation.

reopen async

reopen(annotation: str | Annotation) -> Annotation

Return a review to the open state.

PARAMETER	DESCRIPTION
annotation	The Annotation or annotation ID to reopen. TYPE: str | Annotation

RETURNS	DESCRIPTION
Annotation	The updated Annotation.