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