Agent Operation Types

@dataclass(frozen=True)
class SynthesizeResult:
    success: bool                                  # Whether synthesis succeeded
    report: str                                    # Generated report content
    summary: str                                   # Brief summary
    image_count: int                               # Images included
    document_count: int                            # Documents included
    saved_document_id: Optional[str]               # Document ID if auto_save=True
    execution_time_ms: int                         # Processing time
    iterations: int                                # ReAct reasoning iterations
    token_usage: Optional[dict[str, int]] = None   # Token usage stats

@dataclass(frozen=True)
class DocumentAnalysisResult:
    success: bool                                          # Whether analysis succeeded
    analysis: str                                          # Full analysis content
    summary: str                                           # Brief summary
    document_count: int                                    # Documents analyzed
    categorization: Optional[dict[str, Any]]               # Document categorization
    chunk_references: list[ChunkReference]                 # Cited document chunks
    execution_time_ms: int                                 # Processing time
    iterations: int                                        # ReAct reasoning iterations
    token_usage: Optional[dict[str, int]] = None           # Token usage stats

@dataclass(frozen=True)
class OrganizeResult:
    success: bool                                          # Whether organization succeeded
    summary: str                                           # Summary of actions taken
    actions: list[FolderActionDetail]                      # Individual folder operations
    folders_created: int                                   # New folders created
    files_moved: int                                       # Files moved to folders
    execution_time_ms: int                                 # Processing time
    iterations: int                                        # ReAct reasoning iterations
    token_usage: Optional[dict[str, int]] = None           # Token usage stats

@dataclass(frozen=True)
class ChunkReference:
    chunk_id: str                                  # Chunk identifier
    document_id: str                               # Parent document ID
    document_filename: Optional[str] = None        # Source filename
    page_numbers: Optional[list[int]] = None       # Pages referenced

@dataclass(frozen=True)
class FolderActionDetail:
    action: str                                    # Type of action performed
    folder_id: Optional[str] = None                # Affected folder ID
    folder_name: Optional[str] = None              # Folder name
    file_count: Optional[int] = None               # Files affected