Search Types

@dataclass(frozen=True)
class ImageSearchAgentResult:
    success: bool                              # Whether search succeeded
    results: list[ImageSearchResultItem]       # Full result objects
    count: int                                 # Total results found
    result_ids: list[str]                      # Flat list of image IDs
    summary: str                               # Human-readable summary (refs resolved)
    summary_raw: str                           # Original with [[ref:X]] patterns
    result_refs: dict[str, ResultRefData]      # For interactive UI building
    execution_time_ms: int                     # Total execution time
    iterations: int                            # Reasoning iterations performed
    search_strategy: Optional[dict[str, Any]] = None  # Strategy metadata
    token_usage: Optional[dict[str, int]] = None      # LLM token usage

    @classmethod
    def from_api_response(cls, data: dict) -> "ImageSearchAgentResult": ...

    def as_collection(self) -> FileCollection:
        """Convert results to a FileCollection for agent data flow."""
        ...

@dataclass(frozen=True)
class DocumentSearchAgentResult:
    success: bool                              # Whether search succeeded
    results: list[DocumentChunkResultItem]     # Full chunk objects
    count: int                                 # Total chunks found
    chunk_ids: list[str]                       # Flat list of chunk IDs
    document_ids: list[str]                    # Unique document IDs in results
    summary: str                               # Human-readable summary
    summary_raw: str                           # Original with [[ref:X]] patterns
    result_refs: dict[str, ResultRefData]      # For interactive UI building
    search_mode: str                           # Search mode used
    execution_time_ms: int                     # Total execution time
    iterations: int                            # Reasoning iterations performed
    search_strategy: Optional[dict[str, Any]] = None  # Strategy metadata
    token_usage: Optional[dict[str, int]] = None      # LLM token usage

    @classmethod
    def from_api_response(cls, data: dict) -> "DocumentSearchAgentResult": ...

    def as_collection(self, by: str = "document") -> FileCollection:
        """Convert results to a FileCollection. by='document' uses document IDs, by='chunk' uses chunk IDs."""
        ...

@dataclass(frozen=True)
class ImageSearchResultItem:
    image_id: str                                 # Image UUID
    score: float                                  # Relevance score (0-1)
    filename: Optional[str] = None                # Original filename
    title: Optional[str] = None                   # Image title
    description: Optional[str] = None             # AI-generated description
    folder_id: Optional[str] = None               # Parent folder ID
    thumbnail_url: Optional[str] = None           # Thumbnail URL
    features: Optional[list[dict[str, Any]]] = None  # Detected objects/features

    @classmethod
    def from_api_response(cls, data: dict) -> "ImageSearchResultItem": ...

@dataclass(frozen=True)
class DocumentChunkResultItem:
    chunk_id: str                            # Chunk UUID
    document_id: str                         # Parent document UUID
    document_filename: str                   # Document filename
    text: str                                # Chunk text content
    score: float                             # Relevance score (0-1)
    page_numbers: Optional[list[int]] = None # Page numbers for this chunk
    chunk_index: Optional[int] = None        # Position in document

    @classmethod
    def from_api_response(cls, data: dict) -> "DocumentChunkResultItem": ...

@dataclass(frozen=True)
class ResultRefData:
    count: int                 # Number of items
    ids: list[str]             # Item IDs (images, chunks, or documents)
    image_ids: list[str]       # Backward compat: image IDs when id_type='image'
    id_type: str               # "image", "document", or "chunk"
    label: str                 # Human-readable label (e.g., "15 images")

    @classmethod
    def from_api_response(cls, data: dict) -> "ResultRefData": ...