File Types

@dataclass(frozen=True)
class UserFile:
    id: str                            # Unique file identifier
    size_bytes: int                    # File size
    has_full_description: bool         # Whether full descriptions exist
    title: Optional[str]               # User or auto-generated title
    filename: Optional[str]            # Original filename
    thumbnail_url: Optional[str]       # URL to thumbnail
    upload_description: Optional[str]  # Quick AI description
    visible_text: Optional[str]        # OCR text
    tags: Optional[list[str]]          # Tags
    created_at: Optional[datetime]     # Upload timestamp
    content_created_at: Optional[datetime]  # EXIF date
    dimensions: Optional[dict[str, int]]  # {width, height}
    format: Optional[str]              # jpeg, png, etc.
    variant_status: Optional[str]      # Variant generation status
    variant_count: Optional[int]       # Number of variants generated
    medium_url: Optional[str]          # URL to medium variant
    full_url: Optional[str]            # URL to full-size
    blur_hash: Optional[str]           # BlurHash for placeholders
    description_status: Optional[str]  # Description generation status
    description_error: Optional[str]   # Error if description failed
    content_type: Optional[str]        # MIME type (image/jpeg, video/mp4)
    media_type: Optional[str]          # "image" or "video"
    # Video-specific fields
    video_metadata: Optional[dict[str, Any]]  # Duration, resolution, codecs
    video_url: Optional[str]           # URL to playable video file
    video_analysis_status: Optional[str]  # Analysis job status
    video_analysis_job_id: Optional[str]  # Analysis job ID
    scene_count: Optional[int]         # Scenes detected in video
    has_audio_transcript: Optional[bool]  # Whether transcript exists

@dataclass(frozen=True)
class UserFileDetails:
    id: str
    object_key: str                    # S3 object key
    size_bytes: int
    content_type: str                  # MIME type
    hash: str                          # File hash
    title: Optional[str]
    tags: Optional[list[str]]
    dimensions: Optional[dict[str, int]]
    format: Optional[str]
    full_url: Optional[str]            # 1024px variant URL
    thumbnail_url: Optional[str]
    medium_url: Optional[str]
    original_url: Optional[str]        # Always available fallback
    upload_description: Optional[str]
    visible_text: Optional[str]
    description_generated_at: Optional[datetime]
    full_descriptions: Optional[list[FullDescription]]
    processing_history: Optional[list[ProcessingHistory]]
    created_at: Optional[datetime]
    updated_at: Optional[datetime]
    content_created_at: Optional[datetime]  # EXIF/video metadata date
    upload_method: Optional[str]       # "DIRECT" or "POST"
    original_filename: Optional[str]   # Original filename from upload
    variant_status: Optional[str]      # pending | processing | completed | failed
    variant_count: Optional[int]       # Number of variants generated
    blur_hash: Optional[str]           # BlurHash for placeholders
    description_status: Optional[str]  # pending | processing | completed | failed

@dataclass(frozen=True)
class FileList:
    files: list[UserFile]    # File summaries
    total_count: int         # Total files matching query
    has_more: bool           # More files available

@dataclass(frozen=True)
class FullDescription:
    id: str                            # Description identifier
    description: str                   # Full description text
    visible_text: Optional[str]        # OCR text
    confidence_score: Optional[float]  # Confidence (0-1)
    providers_used: Optional[list[str]]  # AI models used
    verification_level: Optional[str]
    processing_time_ms: Optional[int]
    created_at: Optional[datetime]

@dataclass(frozen=True)
class ProcessingHistory:
    id: str                            # History entry identifier
    operation_type: str                # Type of operation (describe, verify, rules)
    status: str                        # Processing status
    created_at: Optional[datetime]     # When the operation started
    completed_at: Optional[datetime]   # When the operation completed
    error_message: Optional[str]       # Error message if failed

@dataclass(frozen=True)
class UpdateFileResult:
    id: str                        # File identifier
    title: Optional[str]           # Updated title
    tags: Optional[list[str]]      # Updated tags
    updated_at: Optional[datetime] # Update timestamp

@dataclass(frozen=True)
class DeleteFileResult:
    id: str                        # Deleted file identifier
    deleted_at: Optional[datetime] # Deletion timestamp
    message: str                   # Confirmation message

@dataclass(frozen=True)
class BatchDeleteFileResult:
    id: str                        # File identifier
    status: str                    # "deleted", "skipped", or "failed"
    message: Optional[str]         # Additional details about the operation
    deleted_at: Optional[datetime] # Deletion timestamp (if deleted)

@dataclass(frozen=True)
class BatchDeleteFilesResponse:
    deleted: list[BatchDeleteFileResult]  # Successfully deleted files
    skipped: list[BatchDeleteFileResult]  # Files skipped (e.g., currently processing)
    failed: list[BatchDeleteFileResult]   # Files that failed to delete
    summary: dict[str, int]              # Stats: {total, deleted, skipped, failed}