Callback Types

@dataclass(frozen=True)
class UploadProgressEvent:
    file_index: int         # Zero-based index of file being uploaded
    uploaded_bytes: int     # File size in bytes (always equals total_bytes)
    total_bytes: int        # Total file size in bytes
    filename: Optional[str] # Name of file that was prepared

    # Properties
    @property
    def progress_percent(self) -> float: ...  # Always 100.0

    # Serialization
    def to_dict(self, exclude_none: bool = True) -> dict[str, Any]: ...

@dataclass(frozen=True)
class FileCompleteEvent:
    file_index: int       # Zero-based index of completed file
    result: UploadResult  # Upload result with image_id, filename, etc.

    def to_dict(self, exclude_none: bool = True) -> dict[str, Any]: ...

@dataclass(frozen=True)
class DescriptionProgressEvent:
    completed_count: int     # Descriptions completed so far
    total_count: int         # Total files awaiting descriptions
    latest_result: UploadResult  # Most recently completed result

    # Properties
    @property
    def progress_percent(self) -> float: ...  # 0-100
    @property
    def remaining_count(self) -> int: ...

    def to_dict(self, exclude_none: bool = True) -> dict[str, Any]: ...

@dataclass(frozen=True)
class DescriptionFailedEvent:
    file_index: int       # Zero-based index of failed file
    result: UploadResult  # Result with error details populated

    # Properties
    @property
    def error_message(self) -> Optional[str]: ...
    @property
    def is_retryable(self) -> bool: ...

    def to_dict(self, exclude_none: bool = True) -> dict[str, Any]: ...

@dataclass(frozen=True)
class DocumentUploadProgressEvent:
    file_index: int         # Zero-based index of the file that was uploaded
    uploaded_bytes: int     # Size of the uploaded file in bytes (always equals total_bytes)
    total_bytes: int        # Total size of the file in bytes
    filename: Optional[str] # Name of the file that was uploaded

    # Properties
    @property
    def progress_percent(self) -> float: ...  # Always 100.0

    # Serialization
    def to_dict(self, exclude_none: bool = True) -> dict[str, Any]: ...

@dataclass(frozen=True)
class DocumentFileCompleteEvent:
    file_index: int              # Zero-based index of completed file
    result: DocumentUploadResult # Document upload result with document_id, filename, etc.

    def to_dict(self, exclude_none: bool = True) -> dict[str, Any]: ...

@dataclass(frozen=True)
class DocumentProcessingProgressEvent:
    completed_count: int              # Documents completed so far
    total_count: int                  # Total documents awaiting processing
    latest_result: DocumentUploadResult  # Most recently completed result

    # Properties
    @property
    def progress_percent(self) -> float: ...  # 0-100
    @property
    def remaining_count(self) -> int: ...

    def to_dict(self, exclude_none: bool = True) -> dict[str, Any]: ...

@dataclass(frozen=True)
class DocumentProcessingFailedEvent:
    file_index: int              # Zero-based index of failed file
    result: DocumentUploadResult # Result with error details populated

    # Properties
    @property
    def error_message(self) -> Optional[str]: ...
    @property
    def is_retryable(self) -> bool: ...

    def to_dict(self, exclude_none: bool = True) -> dict[str, Any]: ...

@dataclass(frozen=True)
class CloudStorageJobProgressEvent:
    job: CloudStorageJob        # Current job status snapshot

    # Properties
    @property
    def progress_percent(self) -> float: ...  # Delegates to job.progress_percent
    @property
    def is_terminal(self) -> bool: ...        # Delegates to job.is_terminal

    def to_dict(self, exclude_none: bool = True) -> dict[str, Any]: ...

from aion import AionVision, CloudStorageJobProgressEvent

def on_import_progress(event: CloudStorageJobProgressEvent):
    job = event.job
    print(f"Import progress: {event.progress_percent:.0f}% "
          f"({job.completed_files}/{job.total_files} files, "
          f"{job.failed_files} failed)")

async with AionVision(api_key="aion_...") as client:
    job = await client.cloud_storage.import_and_wait(
        connection_id="conn_abc123",
        files=files,
        on_progress=on_import_progress,
    )

from aion import AionVision

def on_progress(event: AionVision.UploadProgressEvent):
    print(f"Prepared file {event.file_index}: {event.filename} ({event.total_bytes} bytes)")

def on_file_complete(event: AionVision.FileCompleteEvent):
    print(f"Uploaded: {event.result.filename} -> {event.result.image_id}")

def on_desc_progress(event: AionVision.DescriptionProgressEvent):
    print(f"Descriptions: {event.completed_count}/{event.total_count}")

def on_desc_failed(event: AionVision.DescriptionFailedEvent):
    print(f"Failed: {event.error_message}")
    if event.is_retryable:
        print("  -> Can retry")

async with AionVision(api_key="aion_...") as client:
    results = await client.upload(
        files,
        on_progress=on_progress,
        on_file_complete=on_file_complete,
        on_description_progress=on_desc_progress,
        on_description_failed=on_desc_failed,
    )