Data models

All data models are importable from the SDK and work with IDE autocomplete:

from fi.queues import (
    AnnotationLabel, QueueDetail, QueueItem, Score,
    QueueProgress, QueueAnalytics, QueueAgreement,
    AddItemsResponse, ExportToDatasetResponse, ImportAnnotationsResponse,
)

AnnotationLabel

Field	Type	Description
id	str	Label UUID
name	str	Label name
type	str	Label type (categorical, text, numeric, star, thumbs_up_down)
description	Optional[str]	Label description
settings	Optional[Dict[str, Any]]	Type-specific configuration (see Label Settings by Type)

QueueDetail

Field	Type	Description
id	str	Queue UUID
name	str	Queue name
description	Optional[str]	Queue description
instructions	Optional[str]	Annotator instructions
status	Optional[str]	Queue status (draft, active, paused, completed)
assignment_strategy	Optional[str]	Assignment strategy (manual, round_robin, load_balanced)
annotations_required	Optional[int]	Annotations needed per item
reservation_timeout_minutes	Optional[int]	Reservation timeout in minutes
requires_review	Optional[bool]	Whether review is required
created_at	Optional[str]	Creation timestamp
updated_at	Optional[str]	Last update timestamp
item_count	Optional[int]	Total items in queue
completed_count	Optional[int]	Completed items count

QueueItem

Field	Type	Description
id	str	Item UUID
source_type	Optional[str]	Source entity type
source_id	Optional[str]	Source entity UUID
status	Optional[str]	Item status (pending, in_progress, completed)
order	Optional[int]	Item order in queue
assigned_to	Optional[str]	Assigned user ID
created_at	Optional[str]	Creation timestamp

Score

Field	Type	Description
id	Optional[str]	Score UUID
label_id	Optional[str]	Label UUID
label_name	Optional[str]	Label display name
value	Optional[Any]	Annotation value
score_source	Optional[str]	Origin (human, api, auto, imported)
notes	Optional[str]	Free-text notes
annotator_id	Optional[str]	Annotator user ID
annotator_name	Optional[str]	Annotator display name
source_type	Optional[str]	Source entity type
source_id	Optional[str]	Source entity UUID
created_at	Optional[str]	Creation timestamp

QueueProgress

Field	Type	Description
total	int	Total items
pending	int	Pending items
in_progress	int	In-progress items
completed	int	Completed items
skipped	int	Skipped items
progress_pct	Optional[float]	Completion percentage
annotator_stats	Optional[List[Dict]]	Per-annotator statistics

QueueAnalytics

Field	Type	Description
throughput	Optional[Dict]	Throughput metrics — contains daily (list of {"date", "count"} entries for the last 30 days), total_completed (int), and avg_per_day (float)
annotator_performance	Optional[List[Dict]]	Per-annotator performance — each entry has user_id, name, completed, and last_active
label_distribution	Optional[Dict]	Distribution of annotations across labels — keyed by label ID, each with name, type, and values (value-to-count mapping)
status_breakdown	Optional[Dict[str, int]]	Item count by status (e.g. {"pending": 5, "completed": 10})
total	Optional[int]	Total items in the queue

QueueAgreement

Field	Type	Description
overall_agreement	Optional[float]	Overall agreement percentage
per_label	Optional[List[Dict]]	Agreement broken down by label
annotator_pairs	Optional[List[Dict]]	Pairwise annotator agreement

AddItemsResponse

Field	Type	Description
added	int	Number of items added
duplicates	int	Number of duplicate items skipped
errors	Optional[List[Dict]]	Any errors encountered

ExportToDatasetResponse

Field	Type	Description
dataset_id	Optional[str]	Dataset UUID
dataset_name	Optional[str]	Dataset name
rows_created	Optional[int]	Number of rows created

ImportAnnotationsResponse

Field	Type	Description
imported	int	Number of annotations imported