Batch Types

class BatchStatus(str, Enum):
    PENDING = "pending"
    PROCESSING = "processing"
    COMPLETED = "completed"
    FAILED = "failed"
    CANCELLED = "cancelled"
    PARTIALLY_COMPLETED = "partially_completed"

class BatchItemStatus(str, Enum):
    PENDING = "pending"       # Not yet processed
    PROCESSING = "processing" # Currently being processed
    SUCCESS = "success"       # Completed successfully
    FAILED = "failed"         # Processing failed
    SKIPPED = "skipped"       # Skipped (e.g., duplicate)

@dataclass(frozen=True)
class BatchStatusResult:
    batch_id: str                 # Unique batch identifier
    status: BatchStatus           # Current status
    total_items: int              # Total items in batch
    processed_items: int          # Items processed so far
    successful_items: int         # Successfully processed items
    failed_items: int             # Items that failed
    success_rate: float           # Proportion of successful items (0-1)
    progress_percentage: float    # Progress (0-100)
    created_at: Optional[datetime]
    started_at: Optional[datetime]
    completed_at: Optional[datetime]
    estimated_completion_time: Optional[datetime]
    avg_processing_time_ms: Optional[int]

    def is_terminal(self) -> bool: ...  # Check if batch reached terminal state

@dataclass(frozen=True)
class BatchResults:
    batch_id: str                     # Unique batch identifier
    status: BatchStatus               # Current batch status
    results: list[BatchItemResult]    # Individual results
    pagination: BatchResultsPagination
    summary: BatchResultsSummary

    # Helper methods
    def successful_results(self) -> list[BatchItemResult]: ...
    def failed_results(self) -> list[BatchItemResult]: ...

@dataclass(frozen=True)
class BatchItemResult:
    item_id: str                  # Unique item identifier
    item_index: int               # Index in original batch (0-based)
    status: BatchItemStatus       # PENDING | PROCESSING | SUCCESS | FAILED | SKIPPED
    input_data: Optional[dict]    # Original input data
    output_data: Optional[dict]   # Processing results (varies by operation)
    error_message: Optional[str]  # Error message if failed
    processing_time_ms: Optional[int]
    stored_image_url: Optional[str]

    # Properties (computed from output_data)
    @property
    def description(self) -> Optional[str]: ...
    @property
    def confidence_score(self) -> Optional[float]: ...
    @property
    def is_verified(self) -> Optional[bool]: ...

@dataclass(frozen=True)
class BatchImageInput:
    image_url: Optional[str] = None         # Public URL to image
    image_base64: Optional[str] = None      # Base64-encoded image (with data URL prefix)
    object_key: Optional[str] = None        # S3 object key for uploaded image
    metadata: Optional[dict[str, Any]] = None  # Optional metadata to associate

@dataclass(frozen=True)
class BatchSubmissionResult:
    batch_id: str              # Unique batch identifier
    status: str                # Initial status (typically "pending")
    total_items: int           # Number of items submitted
    estimated_completion_time: Optional[datetime] = None

@dataclass(frozen=True)
class BatchResultsPagination:
    offset: int
    limit: int
    total: int
    has_more: bool

@dataclass(frozen=True)
class BatchResultsSummary:
    total_items: int
    successful_items: int
    failed_items: int
    skipped_items: int
    processing_time_ms: int    # Total processing time in ms