Annotations

# Basic listing
annotations = client.annotations.list(
    dataset_id="dataset_abc123",
    asset_id="asset_xyz789"
)

for annotation in annotations.items:
    print(f"ID: {annotation.annotation_id}")
    print(f"Type: {annotation.spec.bound_type}")

# With custom pagination
from vi.api.types import PaginationParams

annotations = client.annotations.list(
    dataset_id="dataset_abc123",
    asset_id="asset_xyz789",
    pagination=PaginationParams(page_size=100)
)

for annotation in annotations.items:
    print(f"{annotation.annotation_id}: {annotation.spec.bound_type}")

# Using dict for pagination
annotations = client.annotations.list(
    dataset_id="dataset_abc123",
    asset_id="asset_xyz789",
    pagination={"page_size": 100}
)

# Iterate through all pages
for page in client.annotations.list(
    dataset_id="dataset_abc123",
    asset_id="asset_xyz789"
):
    for annotation in page.items:
        print(f"{annotation.annotation_id}: {annotation.spec.bound_type}")

# Collect all annotations for an asset
all_annotations = list(
    client.annotations.list(
        dataset_id="dataset_abc123",
        asset_id="asset_xyz789"
    ).all_items()
)

print(f"Total annotations: {len(all_annotations)}")

# Basic usage
annotation = client.annotations.get(
    dataset_id="dataset_abc123",
    asset_id="asset_xyz789",
    annotation_id="annotation_xyz789"
)

print(f"Type: {annotation.spec.bound_type}")
print(f"Content: {annotation.spec.contents}")

# Access caption content
annotation = client.annotations.get(
    dataset_id="dataset_abc123",
    asset_id="asset_xyz789",
    annotation_id="annotation_xyz789"
)

if hasattr(annotation.spec.contents, 'contents'):
    # It's a Caption
    print(f"Caption: {annotation.spec.contents.contents}")

# Access bounding box content
annotation = client.annotations.get(
    dataset_id="dataset_abc123",
    asset_id="asset_xyz789",
    annotation_id="annotation_xyz789"
)

if hasattr(annotation.spec.contents, 'bound'):
    # It's a PhraseGroundingBoundingBox
    print(f"Bounds: {annotation.spec.contents.bound}")
    print(f"Target span: {annotation.spec.contents.target}")

# Display detailed information
annotation = client.annotations.get(
    dataset_id="dataset_abc123",
    asset_id="asset_xyz789",
    annotation_id="annotation_xyz789"
)
annotation.info()  # Prints formatted annotation summary

# Upload single JSONL file
result = client.annotations.upload(
    dataset_id="dataset_abc123",
    paths="annotations.jsonl",
    wait_until_done=True
)

print(f"✓ Imported: {result.total_annotations}")

# Upload folder of annotation files
result = client.annotations.upload(
    dataset_id="dataset_abc123",
    paths="./annotations/",
    wait_until_done=True
)

print(result.summary())

# Upload multiple specific files
result = client.annotations.upload(
    dataset_id="dataset_abc123",
    paths=["batch1.jsonl", "batch2.jsonl"],
    wait_until_done=True
)

# Upload and verify count
def upload_and_verify(dataset_id: str, annotations_path: str) -> bool:
    """Upload annotations and verify success."""

    # Count annotations in file
    with open(annotations_path) as f:
        local_count = sum(1 for _ in f)

    # Upload
    result = client.annotations.upload(
        dataset_id=dataset_id,
        paths=annotations_path,
        wait_until_done=True
    )

    # Verify
    print(f"Local: {local_count}")
    print(f"Imported: {result.total_annotations}")

    return result.total_annotations == local_count

success = upload_and_verify("dataset_abc123", "annotations.jsonl")

# Create annotations programmatically and upload
import json
from pathlib import Path

def create_and_upload_annotations(dataset_id: str, images_dir: str):
    """Create annotations for images and upload."""
    annotations = []

    for image_path in Path(images_dir).glob("*.jpg"):
        annotation = {
            "asset_id": image_path.stem,
            "caption": f"Image of {image_path.stem}",
            "grounded_phrases": []
        }
        annotations.append(annotation)

    # Save to JSONL
    output_file = "generated_annotations.jsonl"
    with open(output_file, "w") as f:
        for annotation in annotations:
            json.dump(annotation, f)
            f.write("\n")

    # Upload
    result = client.annotations.upload(
        dataset_id=dataset_id,
        paths=output_file,
        wait_until_done=True
    )

    return result

result = create_and_upload_annotations("dataset_abc123", "./images")

# Delete single annotation
deleted = client.annotations.delete(
    dataset_id="dataset_abc123",
    asset_id="asset_xyz789",
    annotation_id="annotation_xyz789"
)

# Delete all annotations for an asset
annotations = client.annotations.list(
    dataset_id="dataset_abc123",
    asset_id="asset_xyz789"
)

for annotation in annotations.items:
    client.annotations.delete(
        dataset_id="dataset_abc123",
        asset_id="asset_xyz789",
        annotation_id=annotation.annotation_id
    )
    print(f"Deleted: {annotation.annotation_id}")

# Basic usage
status = client.annotations.wait_until_done(
    dataset_id="dataset_abc123",
    annotation_import_session_id="session_id"
)

print(f"Total: {status.status.annotations.status_count}")

# After async upload
result = client.annotations.upload(
    dataset_id="dataset_abc123",
    paths="annotations.jsonl",
    wait_until_done=False
)

# Do other work...

# Then wait for completion
status = client.annotations.wait_until_done(
    dataset_id="dataset_abc123",
    annotation_import_session_id=result.session_id
)

print(f"Import complete: {status.status.annotations.status_count}")

# Download with default settings (ViJsonl format)
result = client.annotations.download(
    dataset_id="dataset_abc123"
)

print(result.summary())

# Download in COCO format
from vi.api.resources.datasets.types import (
    DatasetExportFormat,
    DatasetExportSettings
)

result = client.annotations.download(
    dataset_id="dataset_abc123",
    export_settings=DatasetExportSettings(
        format=DatasetExportFormat.COCO
    ),
    save_dir="./annotations"
)

print(f"Downloaded to: {result.save_dir}")

# Download in YOLO format
result = client.annotations.download(
    dataset_id="dataset_abc123",
    export_settings={"format": DatasetExportFormat.YOLO_DARKNET},
    save_dir="./yolo_annotations"
)

# Download using existing export
result = client.annotations.download(
    dataset_id="dataset_abc123",
    dataset_export_id="export_xyz789"
)

# Download without progress bars (CI/CD environments)
result = client.annotations.download(
    dataset_id="dataset_abc123",
    show_progress=False,
    overwrite=True
)

# Download and process annotations
from pathlib import Path
import json

result = client.annotations.download(
    dataset_id="dataset_abc123",
    export_settings={"format": DatasetExportFormat.VI_JSONL},
    save_dir="./annotations"
)

# Process downloaded annotations
annotation_files = Path(result.save_dir).glob("*.jsonl")
for file in annotation_files:
    with open(file) as f:
        for line in f:
            annotation = json.loads(line)
            print(f"Asset: {annotation['asset_id']}")

from vi.api.resources.datasets.annotations.responses import Annotation

from vi.api.resources.datasets.annotations.responses import AnnotationSpec

from vi.api.resources.datasets.annotations.responses import AnnotationAggregation

from vi.api.resources.datasets.annotations.responses import Whole

from vi.api.resources.datasets.annotations.responses import ThisPart

from vi.api.resources.datasets.annotations.responses import AnnotationContent

AnnotationContent = Caption | PhraseGroundingBoundingBox

from vi.api.resources.datasets.annotations.responses import Caption

from vi.api.resources.datasets.annotations.responses import PhraseGroundingBoundingBox

from vi.api.resources.datasets.annotations.responses import AnnotationImportSession

from vi.api.resources.datasets.annotations.responses import AnnotationImportSpec

from vi.api.resources.datasets.annotations.responses import AnnotationImportFailurePolicy

from vi.api.resources.datasets.annotations.responses import AnnotationImportSessionStatus

from vi.api.resources.datasets.annotations.responses import AnnotationImportSessionCondition

from vi.api.resources.datasets.annotations.responses import AnnotationFileStatus

from vi.api.resources.datasets.annotations.responses import AnnotationStatus

from vi.api.resources.datasets.annotations.responses import ExportedAnnotations

from vi.api.resources.datasets.annotations.responses import ExportedAnnotationsStatus

from vi.api.resources.datasets.annotations.responses import ExportedAnnotationsDownloadUrl

from vi.api.resources.datasets.annotations.responses import Roles

from vi.api.resources.datasets.annotations.responses import FailurePolicy

from vi.api.resources.datasets.annotations.responses import AnnotationImportSource

from vi.api.resources.datasets.annotations.responses import ConditionReason

{
  "asset_id": "asset_123",
  "caption": "A cat sitting on a couch",
  "grounded_phrases": [
    {
      "phrase": "cat",
      "bbox": [0.1, 0.2, 0.5, 0.7]
    },
    {
      "phrase": "couch",
      "bbox": [0.6, 0.2, 0.9, 0.7]
    }
  ]
}

{
  "asset_id": "asset_123",
  "contents": {
    "interactions": [
      {
        "question": "What is the cat doing?",
        "answer": "Sitting on a couch"
      }
    ]
  }
}

def to_pixels(bbox: list[float], width: int, height: int) -> list[int]:
    """Convert normalized bbox to pixel coordinates."""
    x_min, y_min, x_max, y_max = bbox
    return [
        int(x_min * width),
        int(y_min * height),
        int(x_max * width),
        int(y_max * height)
    ]

# Example
bbox = [0.1, 0.2, 0.5, 0.7]
pixel_bbox = to_pixels(bbox, 1920, 1080)
# Result: [192, 216, 960, 756]

def from_pixels(bbox: list[int], width: int, height: int) -> list[float]:
    """Convert pixel coordinates to normalized bbox."""
    x_min, y_min, x_max, y_max = bbox
    return [
        x_min / width,
        y_min / height,
        x_max / width,
        y_max / height
    ]