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 (see below)
    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

# result.categorization (when present)
{
    "categories": [
        {
            "name": "Safety Inspection Reports",  # AI-generated label
            "description": "...",                  # Brief description
            "document_ids": ["doc_1", "doc_3"],    # Documents in this group
            "count": 2
        },
        ...
    ],
    "total_files": 10,
    "status": "success"  # "success" | "partial" | "failed"
}

@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