From 3143e3a0528c0f29b013996ef44441c00c5b9a0a Mon Sep 17 00:00:00 2001
From: ValueOn AG <p.motsch@valueon.ch>
Date: Mon, 6 Oct 2025 12:53:56 +0200
Subject: [PATCH] ai context loop

---
 .../implementation_ai_processing_flows.md     | 217 ++++++++++++++++++
 1 file changed, 217 insertions(+)
 create mode 100644 poweron/implementation/implementation_ai_processing_flows.md

diff --git a/poweron/implementation/implementation_ai_processing_flows.md b/poweron/implementation/implementation_ai_processing_flows.md
new file mode 100644
index 0000000..31a5109
--- /dev/null
+++ b/poweron/implementation/implementation_ai_processing_flows.md
@@ -0,0 +1,217 @@
+### 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
+```
+
+