+
PowerON AI Service Architektur
+
+
+ 📖 Dokumentation: Diese Dokumentation beschreibt die Architektur des zentralen AI-Service von PowerON. Der Service orchestriert alle AI-Operationen und verwaltet die Kommunikation mit verschiedenen AI-Modellen und Services.
+
+
+
1. High-Level Übersicht
+
+
+
+
🎯 AI Service Center
+
@modules/services/serviceAi/mainServiceAi.py
+
Rolle: Orchestrator, koordiniert alle AI-Operationen
+
Verantwortung: Lazy Initialization, Delegation, Public API
+
+
+
⬇️
+
+
+
+
🔧 Core AI Operations
+
@subCoreAi.py
+
+ - callAiPlanning() - JSON Planning
+ - callAiDocuments() - Dokument-Verarbeitung
+ - readImage() - Bildanalyse
+ - generateImage() - Bildgenerierung
+ - Looping-System für lange Antworten
+
+
+
+
+
📄 Document Processing
+
@subDocumentProcessing.py
+
+ - processDocumentsPerChunk()
+ - processDocumentsPerChunkJson()
+ - Extraction-Integration
+ - Merging-Logik
+
+
+
+
+
⬇️
+
+
+
🏗️ AI Interface Layer
+
@interfaces/interfaceAiObjects.py (AiObjects)
+
+ - Model Registry - Auto-Discovery von Connectors
+ - Model Selector - Dynamische Model-Auswahl
+ - Standardisierte Call-Interface
+ - Price-Calculations
+
+
+
+
+
2. AI-Call-Prozess
+
+
+
🔄 Komponenten-Übersicht
+
+
+
+
📥 Input Layer
+
+ Entry Points: callAiPlanning(), callAiDocuments()
+ prompt + options + placeholders/documents
+
+
+
+
⬇️
+
+
+
🔀 Orchestration Layer
+
+ Placeholder Replacement → Prompt Building → Options Determination
+ subSharedAiUtils.py - buildPromptWithPlaceholders()
+
+
+
+
⬇️
+
+
+
🌐 AI Call Layer
+
+ Looping System → Model Selection → API Call → Response Processing
+ _callAiWithLooping() → AiObjects.call()
+
+
+
+
⬇️
+
+
+
📊 Response Layer
+
+ JSON Merging → Debug Logging → Stats Tracking
+ _mergeJsonContent() → writeDebugFile() → storeWorkflowStat()
+
+
+
+
⬇️
+
+
+
📤 Output Layer
+
+ Return → Document Processing → Generation
+ result → Extracted Content → Final Documents
+
+
+
+
+
+
3. Looping-System für lange Antworten
+
+
+
🔄 Multi-Iteration Processing
+
Problem: Token-Limits können bei großen Ausgaben überschritten werden
+
Lösung: Kontinuierliches Looping mit State-Transfer
+
+
+ Iteration 1: Start des AI-Calls
+ prompt + LOOP_INSTRUCTION → AI Response
+ → Response wird an Token-Limit evaluiert
+
+
+
+ Continuation Check: Response enthält {"continuation": {...}}
+ if continuation != null: Weiter mit next_instruction
+ → Letzte Daten + nächste Anweisung gespeichert
+
+
+
+ Iteration N: Continuation wird erneut verarbeitet
+ continuation_prompt + previous_state → AI Response
+ → Neue Daten werden akkumuliert
+
+
+
+ Final: {"continuation": null} erreicht
+ _mergeJsonContent() - Alle JSON-Listen werden zusammengeführt
+ → Komplette Antwort wird zurückgegeben
+
+
+
+
+
💡 Wichtige Features des Looping-Systems:
+
+ - Max 100 Iterations - Verhindert Endlosschleifen
+ - Automatisches JSON-Merging - Listen werden intelligent zusammengeführt
+ - Debug Logging - Jede Iteration wird in separate Dateien gespeichert
+ - Continuation Detection - Nur aktiv wenn
LOOP_INSTRUCTION im Prompt ist
+ - Stats Tracking - Jede Iteration erzeugt Workflow-Statistiken
+
+
+
+
4. Verfügbare Methoden
+
+
+
🚀 Public API Methods
+
+
+
Planning
+
callAiPlanning()
+
Parameter:
+
+ - prompt (required)
+ - placeholders (optional)
+
+
Verwendung: Task Planning, Action Selection, Review
+
✓ Statische Parameter (QUALITY + DETAILED)
+
+
+
+
Documents
+
callAiDocuments()
+
Parameter:
+
+ - prompt (required)
+ - documents (optional)
+ - options (optional)
+ - outputFormat (optional)
+ - title (optional)
+
+
Support: PDF, DOCX, TXT, HTML, JSON, CSV, XLSX, Bilder (JPG, PNG)
+
Intern: Alles wird in Standard-JSON konvertiert (formatunabhängig)
+
Features: Neutralizer, Image-Analysis, Multi-Format-Ausgabe
+
⚙️ Adaptive Parameter via _analyzePromptAndCreateOptions()
+
+
+
+
Image
+
readImage()
+
Parameter:
+
+ - prompt (required)
+ - imageData (required)
+ - mimeType (optional)
+ - options (optional)
+
+
Verwendung: Direkte Bild-Analyse mit Vision-Modellen
+
ℹ️ Auch integriert in callAiDocuments()!
+
✓ Operation: IMAGE_ANALYSE
+
+
+
+
Image
+
generateImage()
+
Parameter:
+
+ - prompt (required)
+ - size (optional)
+ - quality (optional)
+ - style (optional)
+
+
Verwendung: Direkte AI-Bildgenerierung
+
ℹ️ Auch in Generation-Workflows integriert
+
✓ Delegiert an aiObjects.generateImage()
+
+
+
+
+
5. Beispiel: AI-Call Flow
+
+
+
🎯 Use Case: Dokument-Verarbeitung mit AI
+
+
+
📍 Step 1: Eingabe
+
Workflow-Call: ai.process()
+
+{
+ "aiPrompt": "Extrahiere alle wichtigen Fakten aus den Dokumenten",
+ "documentList": ["docList:msg_123"],
+ "resultType": "docx"
+}
+
+
+
+
+
🔄 Step 2: Prompt-Building
+
Placeholder Replacement (falls vorhanden)
+
+buildPromptWithPlaceholders(
+ "{{KEY:TASK_OBJECTIVE}} extrahieren",
+ {"TASK_OBJECTIVE": "Spesenbelege"}
+)
+→ "Spesenbelege extrahieren"
+
+
+
+
+
⚙️ Step 3: Options Determination
+
Adaptive oder Static Parameter?
+
+ - Planning: Static → QUALITY + DETAILED
+ - Documents: Optional → AI-gestützte Analyse via
_analyzePromptAndCreateOptions()
+
+
+
+
+
🌐 Step 4: AI-Call mit Looping
+
Iteration 1 → Iteration N (falls continuation)
+
+ - Request erstellen:
AiCallRequest(prompt, options)
+ - Model Selection:
modelSelector.select(prompt, options)
+ - API Call:
model.functionCall(modelCall)
+ - Response:
AiCallResponse(content, modelName, priceUsd)
+ - Debug: Speicherung in
debug/[timestamp]_prompt.txt
+
+
+
+
+
📊 Step 5: Response Processing
+
JSON Merging (falls Multi-Iteration)
+
+if continuation != null:
+ # Weiter mit next_instruction
+ accumulatedContent.append(partialResponse)
+ continue
+else:
+ # Final - alle JSON-Listen mergen
+ finalResult = _mergeJsonContent(accumulatedContent)
+ return finalResult
+
+
+
+
+
📈 Step 6: Stats & Logging
+
Workflow-Statistiken speichern
+
+storeWorkflowStat(
+ workflow,
+ aiCallResponse,
+ "ai.call.document_processing"
+)
+# Logs: processingTime, priceUsd, tokensUsed
+
+
+
+
+
✓ AI-Call abgeschlossen
+
Return: DOCX mit extrahierten Daten
+
Iterations: 3 (wegen Token-Limits)
+
Processing Time: 12.5s
+
Cost: $0.0032 USD
+
+
+
+
6. Neutralizer & Normalizer - Datenschutz & Formatunabhängigkeit
+
+
+
🔒 Neutralizer - Datenschutz bei User-Dokumenten
+
+
+ 🔐 Neutralizer-Funktion: Alle Dokumente, die im User-Prompt mitgeliefert werden, werden durch den Neutralizer geschleust, um personenbezogene und sensible Daten durch Platzhalter zu ersetzen.
+
+
+
+
+
🔄 Datenschutz-Neutralisierung
+
Beispiel:
+
+Original: "Max Mustermann, geboren am 01.01.1980 in Berlin"
+Neutralisiert: "{{person}}, geboren am {{date}} in {{city}}"
+
+
+ - Personendaten: Namen → {{person}}
+ - Daten: Geburts-/Gesundheitsdaten → {{date}} / {{health_data}}
+ - Financial: Kontonummern, Kreditkarten → {{account_number}}
+ - Lokationen: Adressen → {{address}}
+ - Kontakte: E-Mails, Telefonnummern → {{contact}}
+
+
✓ Automatisch bei allen User-Prompt-Dokumenten!
+
+
+
+
⬇️
+
+
📊 Normalizer - Formatunabhängige JSON-Struktur
+
+
+ 💡 Kern-Prinzip: Alle Dokument-Formate werden intern in ein einheitliches Standard-JSON-Format konvertiert. Dadurch ist die Verarbeitung formatunabhängig.
+
+
+
+
+
📥 Input-Formate
+
+ - Dokumente: PDF, DOCX, TXT, HTML, JSON, CSV, XLSX
+ - Bilder: JPG, PNG, GIF, WebP
+ - Strukturierte Daten: XML, YAML
+ - Code: Python, JavaScript, etc.
+
+
→ Normalizer:
+
NormalizationService konvertiert alles in Standard-JSON-Struktur
+
+
+
+
📤 Output-Formate
+
+ - Dokumente: PDF, DOCX, HTML, TXT, MD
+ - Daten: JSON, CSV, XLSX
+ - Präsentation: Powerpoint
+ - Spezial: Custom Renderer
+
+
→ Renderer:
+
Generation-Service rendert JSON → gewünschtes Format
+
+
+
+
⬇️
+
+
+
📊 Standard-JSON Struktur
+
+{
+ "metadata": {
+ "title": "Document Title",
+ "format": "auto-detected",
+ "timestamp": "2024-01-15T10:30:00Z"
+ },
+ "documents": [
+ {
+ "documentName": "output.pdf",
+ "sections": [
+ {
+ "sectionTitle": "Section 1",
+ "content": "...",
+ "type": "text|table|list|image"
+ }
+ ]
+ }
+ ]
+}
+
+
+
+
+ ✓ Vollständige Pipeline: Input (jedes Format) → Neutralizer (Datenschutz) → Extraction → Normalizer (JSON) → AI Processing → Renderer → Output (jedes Format)
+
+
+
+
7. Integration mit anderen Services
+
+
+
🔗 Service-Dependencies
+
+
+
+
📤 Generation Service
+
@serviceGeneration/
+
Verwendung:
+
+ - Prompt-Building für Generierung
+ - Rendering von JSON → Final Format
+ - Multi-File Generation
+ - Format-spezifische Renderer
+
+
+
+
+
🔍 Extraction Service
+
@serviceExtraction/
+
Verwendung:
+
+ - extractContent() - Dokument-Extraktion
+ - Chunking-Strategien
+ - Merging-Strategien
+ - Bild-Analyse (Vision-Models)
+
+
+
+
+
⬇️
+
+
+
🔄 Normalization Service
+
@serviceNormalization/
+
Zentral für formatunabhängige Verarbeitung!
+
+ - discoverStructures() - Erkennt Tabellen, Listen, Strukturen
+ - requestHeaderMapping() - AI-gestützte Spalten-Mapping
+ - applyMapping() - Konvertiert in kanonisches JSON
+ - validateCanonical() - Validiert JSON-Struktur
+
+
⚠️ Hinweis: Zu unterscheiden vom Neutralizer (Datenschutz) - dieser konvertiert Formate in JSON
+
+
+
+
🔍 Klärung: Neutralizer vs. Normalizer
+
+
+
Neutralizer
+
+ - Für User-Prompt-Dokumente
+ - Datenschutz durch Platzhalter
+ - Ersetzt sensible Daten
+ - z.B. Name → {{person}}
+
+
+
+
Normalizer
+
+ - Für alle Dokument-Formate
+ - Konvertiert in JSON-Struktur
+ - Formatunabhängige Verarbeitung
+ - z.B. PDF → JSON
+
+
+
+
+
+
⬇️
+
+
+
🗄️ Storage & Logging
+
Components:
+
+ - Debug Files:
local/logs/debug/[timestamp]_[type].txt
+ - Workflow Stats:
services.workflow.storeWorkflowStat()
+ - Progress Logging:
services.workflow.progressLogStart()
+
+
+
+
+
+
📊 Legende
+
+
+
Service Box: Hauptkomponenten des AI-Service
+
+
+
+
Component Box: Sub-Komponenten (Core, Processing, Generation)
+
+
+
+
Loop Step: Iteration im Looping-System
+
+
+
+
Success Box: Erfolgreich abgeschlossener Call
+
+
+
+
+
⚠️ Wichtige Hinweise:
+
+ - Lazy Initialization: Sub-Module werden erst bei Bedarf initialisiert
+ - Model Registry: Auto-Discovery von AI-Connectors zur Laufzeit
+ - Looping System: Nur aktiv wenn
LOOP_INSTRUCTION im Prompt ist
+ - Debug Logging: Alle Prompts und Responses werden in Debug-Files gespeichert
+ - Price Tracking: Kosten werden pro Call berechnet und gespeichert
+
+
+
+
+
+
diff --git a/poweron/appdoc/doc_architecture_gateway.drawio b/poweron/appdoc/doc_architecture_gateway.drawio
index e6f231b..768fe34 100644
--- a/poweron/appdoc/doc_architecture_gateway.drawio
+++ b/poweron/appdoc/doc_architecture_gateway.drawio
@@ -1 +1 @@
-