wiki/z-archive/implementation/implementation_ai_processing_flows.md

### AI process with prompt, documents, and outputFormat

```mermaid
flowchart TD
    start[Workflow ai.process]
    callAi[services.ai.callAi prompt documents outputFormat]
    getPrompt[GenerationService.getExtractionPrompt]
    aiText[_callAiText with extractionPrompt documents options]
    extract[ExtractionService.extractContent]
    readFile[Db.getFileData]
    llmCall[AiObjects.call]
    hasImages{Any image parts}
    llmImg[AiObjects.callImage]
    render[GenerationService.renderReport]
    pickRenderer[renderers.registry.get_renderer]
    renderer[Format specific renderer]
    rendered[Rendered content + mimeType]
    result[ActionResult documents]

    start --> callAi
    callAi --> getPrompt
    callAi --> aiText

    aiText --> extract
    extract --> readFile

    aiText --> llmCall
    aiText --> hasImages
    hasImages -->|yes| llmImg
    hasImages -->|no| llmCall

    aiText --> render
    render --> pickRenderer
    pickRenderer --> renderer
    renderer --> rendered
    rendered --> result
```

### method.document.extract with prompt and documents

```mermaid
flowchart TD
    start[MethodDocument.extract]
    callAi[services.ai.callAi prompt documents]
    aiText[_callAiText with prompt documents options]
    extract[ExtractionService.extractContent]
    readFile[Db.getFileData]
    llmCall[AiObjects.call]
    hasImages{Any image parts?}
    llmImg[AiObjects.callImage]
    textOut[Aggregated AI response text]
    buildDocs[Create ActionDocument txt]
    result[ActionResult documents]

    start --> callAi
    callAi --> aiText

    aiText --> extract
    extract --> readFile

    aiText --> llmCall
    aiText --> hasImages
    hasImages -->|yes| llmImg
    hasImages -->|no| llmCall

    llmCall --> textOut
    llmImg --> textOut
    textOut --> buildDocs
    buildDocs --> result
```

### Common flow between ai.process and document.extract

```mermaid
flowchart TD
    userInput[User Input Parameters]
    workflow[Workflow Engine]
    method[Method Handler]
    start[Workflow Action]
    callAi[services.ai.callAi]
    aiText[_callAiText]
    extract[ExtractionService.extractContent]
    readFile[Db.getFileData]
    llmCall[AiObjects.call]
    hasImages{Any image parts?}
    llmImg[AiObjects.callImage]
    aiResponse[AI Response]
    
    %% ai.process specific
    getPrompt[GenerationService.getExtractionPrompt]
    render[GenerationService.renderReport]
    pickRenderer[renderers.registry.get_renderer]
    renderer[Format specific renderer]
    rendered[Rendered content + mimeType]
    
    %% document.extract specific
    buildDocs[Create ActionDocument txt]
    
    %% Common result
    actionResult[ActionResult with documents]
    workflowResult[Workflow Result]
    userOutput[User Output]

    userInput --> workflow
    workflow --> method
    method --> start
    start --> callAi
    callAi --> aiText

    aiText --> extract
    extract --> readFile

    aiText --> llmCall
    aiText --> hasImages
    hasImages -->|yes| llmImg
    hasImages -->|no| llmCall

    llmCall --> aiResponse
    llmImg --> aiResponse
    
    %% ai.process path
    callAi --> getPrompt
    aiResponse --> render
    render --> pickRenderer
    pickRenderer --> renderer
    renderer --> rendered
    rendered --> actionResult
    
    %% document.extract path
    aiResponse --> buildDocs
    buildDocs --> actionResult
    
    %% Common result path
    actionResult --> workflowResult
    workflowResult --> userOutput

    classDef common fill:#e1f5fe
    classDef aiProcess fill:#fff3e0
    classDef extract fill:#f3e5f5
    classDef io fill:#e8f5e8

    class start,callAi,aiText,extract,readFile,llmCall,hasImages,llmImg,aiResponse,actionResult,workflowResult,userOutput common
    class getPrompt,render,pickRenderer,renderer,rendered aiProcess
    class buildDocs extract
    class userInput,workflow,method,userOutput io
```

### Input points for ai.process and document.extract

```mermaid
flowchart TD
    user[User]
    
    %% ai.process input
    aiProcess[ai.process Action]
    aiPrompt[prompt: string]
    aiDocuments[documents: ChatDocument[]]
    aiOutputFormat[outputFormat: string]
    aiTitle[title: string optional]
    
    %% document.extract input  
    docExtract[document.extract Action]
    docPrompt[prompt: string]
    docDocuments[documentList: string[]]
    docOperationType[operationType: string optional]
    docProcessIndividually[processDocumentsIndividually: bool optional]
    docChunkAllowed[chunkAllowed: bool optional]
    docMergeStrategy[mergeStrategy: dict optional]
    docExpectedFormats[expectedDocumentFormats: list optional]
    docIncludeMetadata[includeMetadata: bool optional]
    
    %% Common processing
    commonAI[services.ai.callAi]
    
    user --> aiProcess
    user --> docExtract
    
    aiProcess --> aiPrompt
    aiProcess --> aiDocuments
    aiProcess --> aiOutputFormat
    aiProcess --> aiTitle
    
    docExtract --> docPrompt
    docExtract --> docDocuments
    docExtract --> docOperationType
    docExtract --> docProcessIndividually
    docExtract --> docChunkAllowed
    docExtract --> docMergeStrategy
    docExtract --> docExpectedFormats
    docExtract --> docIncludeMetadata
    
    aiPrompt --> commonAI
    aiDocuments --> commonAI
    aiOutputFormat --> commonAI
    aiTitle --> commonAI
    
    docPrompt --> commonAI
    docDocuments --> commonAI
    docOperationType --> commonAI
    docProcessIndividually --> commonAI
    docChunkAllowed --> commonAI
    docMergeStrategy --> commonAI
    docExpectedFormats --> commonAI
    docIncludeMetadata --> commonAI

    classDef aiProcess fill:#fff3e0
    classDef docExtract fill:#f3e5f5
    classDef common fill:#e1f5fe
    classDef input fill:#e8f5e8

    class aiProcess,aiPrompt,aiDocuments,aiOutputFormat,aiTitle aiProcess
    class docExtract,docPrompt,docDocuments,docOperationType,docProcessIndividually,docChunkAllowed,docMergeStrategy,docExpectedFormats,docIncludeMetadata docExtract
    class commonAI common
    class user input
```