+
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
+
+
+
+
+
PowerON Workflow Engine Architektur
+
+
+ 📖 Dokumentation: Diese Dokumentation beschreibt die Architektur der Workflow Engine von PowerON. Die Engine ermöglicht es, komplexe Multi-Step Workflows zu erstellen, die Tasks und Actions dynamisch organisieren und ausführen.
+
+
+
1. Workflow-Übersicht
+
+
+
+
🎯 Workflow Manager
+
@gateway/modules/workflows/workflowManager.py
+
Zentrale Komponente, die alle Workflow-Typen verwaltet und koordiniert.
+
Routen: @routeChatPlayground.py
+
+
+
⬇️
+
+
+
+
📋 Actionplan Mode
+
@modeActionplan.py
+
Funktion:
+
+ - Batch-Planung aller Actions
+ - Sequenzielle Ausführung
+ - AI Review nach Task-Abschluss
+ - Automatische Retry-Logik
+
+
✓ Implementiert
+
+
+
+
🔄 React Mode
+
@modeReact.py
+
Funktion:
+
+ - Iterative Plan-Act-Observe-Schleife
+ - Dynamische Action-Generierung
+ - Adaptive Learning
+ - Content Validation
+
+
✓ Implementiert
+
+
+
+
⚙️ Automated Mode
+
@modeAutomated.py
+
Funktion:
+
+ - Fixed Workflow-Definition
+ - Zeitgesteuerte Ausführung
+ - Vordefinierter Fahrplan
+ - Standardisierte Prozesse
+
+
⚠ Geplant
+
+
+
+
+
2. Workflow-Modell
+
+
+
🏗️ Hierarchische Struktur
+
+
+
+
📦 Workflow
+
Attribute: ID, Status, Round, Mandate
+
Zustände: running, stopped, completed, failed
+
+
+
+
Task 1 - Erste Aufgabe
+
Objective: "Verknüpfung definieren"
+
+
+ Action 1: sharepoint.findDocumentPath
+ Findet Dokumente im SharePoint
+
+
+
+ Action 2: sharepoint.readDocuments
+ Liest gefundene Dokumente
+
+
+
+
+
Task 2 - Zweite Aufgabe
+
Objective: "Verarbeitung durchführen"
+
+
+ Action 1: ai.process
+ Verarbeitet Dokumente mit AI
+
+
+
+ Action 2: sharepoint.uploadDocument
+ Speichert Ergebnisse
+
+
+
+
+
Task 3 - Dritte Aufgabe
+
Objective: "Benachrichtigung versenden"
+
+
+ Action 1: outlook.composeAndSendEmailWithContext
+ Sendet E-Mail mit Ergebnis
+
+
+
+
+
+
+
💡 Wichtige Prinzipien:
+
+ - 1 Task = 1..n Actions - Ein Task kann mehrere Actions enthalten
+ - Dynamisches AI Planning - Actionplan und React generieren Actions dynamisch mittels AI
+ - Variable Übergabe - Actions können Ergebnisse von vorherigen Actions als Input nutzen
+ - Context Propagation - TaskContext überträgt State zwischen Tasks
+
+
+
+
3. Verfügbare Actions
+
+
+
🤖 Method: AI
+
+
+
ai
+
process
+
Parameter:
+
+ - aiPrompt (required)
+ - documentList (optional)
+ - resultType (optional)
+
+
AI-Textverarbeitung mit optionalen Input-Dokumenten
+
+
+
+
ai
+
webResearch
+
Parameter:
+
+ - searchQuery (required)
+ - language (optional)
+
+
Web-Recherche mit AI-gestützter Zusammenfassung
+
+
+
+
ai
+
generateImage
+
Parameter:
+
+ - imagePrompt (required)
+ - style (optional)
+
+
AI-Bildgenerierung basierend auf Textprompt
+
+
+
+
📁 Method: SharePoint
+
+
+
sharepoint
+
findDocumentPath
+
Parameter:
+
+ - connectionReference (required)
+ - searchQuery (required)
+ - site (optional)
+ - maxResults (optional)
+
+
Sucht Dokumente und Ordner in SharePoint
+
+
+
+
sharepoint
+
readDocuments
+
Parameter:
+
+ - documentList (required)
+ - connectionReference (required)
+
+
Liest Dokumente aus SharePoint
+
+
+
+
sharepoint
+
uploadDocument
+
Parameter:
+
+ - documentData (required)
+ - targetPath (required)
+ - connectionReference (required)
+
+
Lädt Dokumente in SharePoint hoch
+
+
+
+
sharepoint
+
listDocuments
+
Parameter:
+
+ - folderPath (required)
+ - connectionReference (required)
+ - includeSubfolders (optional)
+
+
Listet Dokumente in einem Ordner auf
+
+
+
+
📧 Method: Outlook
+
+
+
outlook
+
readEmails
+
Parameter:
+
+ - connectionReference (required)
+ - folder (optional)
+ - limit (optional)
+ - filter (optional)
+
+
Liest E-Mails aus einem Postfach
+
+
+
+
outlook
+
searchEmails
+
Parameter:
+
+ - connectionReference (required)
+ - searchQuery (required)
+
+
Sucht E-Mails mit spezifischen Kriterien
+
+
+
+
outlook
+
composeAndSendEmailWithContext
+
Parameter:
+
+ - connectionReference (required)
+ - recipientEmail (required)
+ - subject (required)
+ - emailBody (required)
+ - attachments (optional)
+
+
Erstellt und sendet E-Mail mit Kontext
+
+
+
+
+
4. Beispiel-Workflow: Spesenverarbeitung
+
+
+
🎯 Use Case: Automatische Spesenverarbeitung
+
Szenario: Ein Kunde lädt PDF-Spesenbelege in einen SharePoint-Ordner. Der Workflow liest täglich die neuen Belege, verarbeitet sie über die Microsoft-Verbindung, aktualisiert das Buchhaltungssystem und sendet eine Bestätigungsmail.
+
+
+
📍 Step 1: Trigger (Automated Mode)
+
Zeitgesteuerte tägliche Ausführung (z.B. 08:00 Uhr)
+
Workflow ID: workflow_spesen_daily
+
Mode: Automated (fix vordefiniert)
+
+
+
+
📋 Task 1: Dokumente identifizieren
+
Objective: "Finde alle neuen PDF-Belege im Spesen-Ordner"
+
+
+
Action 1.1: sharepoint.listDocuments
+
+ Parameters: {
+ "folderPath": "/Spesen/2024",
+ "connectionReference": "user_msft_connection",
+ "includeSubfolders": false
+ }
+
+
✓ Ergebnis: Liste aller PDF-Dateien
+
+
+
+
Action 1.2: sharepoint.readDocuments
+
+ Parameters: {
+ "documentList": ["docList:msg_123:Rechnung_1.pdf", "docList:msg_123:Rechnung_2.pdf"],
+ "connectionReference": "user_msft_connection"
+ }
+
+
✓ Ergebnis: PDF-Inhalte für AI-Verarbeitung
+
+
+
+
+
🤖 Task 2: Daten extrahieren und verarbeiten
+
Objective: "Extrahiere Spesendaten aus PDFs und strukturiere sie"
+
+
+
Action 2.1: ai.process
+
+ Parameters: {
+ "aiPrompt": "Extrahiere alle Ausgaben aus den Spesenbelegen. Erstelle eine strukturierte JSON-Liste mit: Datum, Betrag, Kategorie, Verwendungszweck.",
+ "documentList": ["docList:msg_124:pdf_content"],
+ "resultType": "json"
+ }
+
+
✓ Ergebnis: Strukturierte Spesendaten (JSON)
+
+
+
+
+
📊 Task 3: Buchhaltung aktualisieren
+
Objective: "Übertrage Spesendaten ins Buchhaltungssystem"
+
+
+
Action 3.1: sharepoint.uploadDocument
+
+ Parameters: {
+ "documentData": {"content": "{\"transactions\": [...]}", "mimeType": "application/json"},
+ "targetPath": "/Buchhaltung/Spesen/processed/2024-01-15.json",
+ "connectionReference": "trust_accounting_system"
+ }
+
+
✓ Ergebnis: Aktualisierte Buchhaltung
+
+
+
+
+
📧 Task 4: Bestätigung senden
+
Objective: "Versende Bestätigungsmail mit Übersicht"
+
+
+
Action 4.1: outlook.composeAndSendEmailWithContext
+
+ Parameters: {
+ "connectionReference": "user_msft_connection",
+ "recipientEmail": "user@company.com",
+ "subject": "Spesenverarbeitung abgeschlossen - 15.01.2024",
+ "emailBody": "Guten Tag,\n\nIhre Spesenbelege wurden verarbeitet...",
+ "attachments": ["docList:msg_125:summary.pdf"]
+ }
+
+
✓ Ergebnis: E-Mail erfolgreich versendet
+
+
+
+
+
✓ Workflow abgeschlossen
+
Status: completed
+
Verarbeitet: 5 Actions in 4 Tasks
+
Dauer: ~2 Minuten
+
Ergebnis: Spesenbelege verarbeitet, Buchhaltung aktualisiert, Bestätigung versendet
+
+
+
+
5. Technische Architektur
+
+
+
+
🔧 Core Components
+
Processing Core:
+
+ actionExecutor.py - Führt Actions ausmessageCreator.py - Erstellt Workflow-NachrichtentaskPlanner.py - Plant Tasksvalidator.py - Validiert Actions
+
+
Adaptive Features:
+
+ intentAnalyzer.py - Analysiert User-IntentscontentValidator.py - Validiert InhalteadaptiveLearningEngine.py - Lernt aus FeedbackprogressTracker.py - Verfolgt Fortschritt
+
+
+
+
+
📊 Legende
+
+
+
Workflow/Mode Box: Hauptkomponenten der Engine
+
+
+
+
Task Box: Einzelne Aufgabe im Workflow
+
+
+
+
Action Card: Konkrete Action-Ausführung
+
+
+
+
Success Box: Erfolgreich abgeschlossener Schritt
+
+
+
+
+
⚠️ Wichtige Hinweise:
+
+ - Automated Mode ist noch nicht implementiert, die Architektur dafür ist aber bereits dokumentiert
+ - Variable Übergabe zwischen Actions erfolgt über
documentList Parameter mit References
+ - Connection References müssen vom User konfiguriert sein (Microsoft OAuth)
+ - Error Handling erfolgt über Retry-Logik in den Modes
+
+
+
+