# PowerOn AI Platform - Dokumentation

## Inhaltsverzeichnis

1. [Übersicht](#übersicht)
2. [Architektur](#architektur)
3. [Kernmodule](#kernmodule)
4. [Benutzeroberfläche](#benutzeroberfläche)
5. [Datenmodell](#datenmodell)
6. [Multi-Agent Workflow-System](#multi-agent-workflow-system)
7. [Externe Connectors](#externe-connectors)
8. [Installation und Konfiguration](#installation-und-konfiguration)
9. [API-Endpunkte](#api-endpunkte)
10. [Sicherheitskonzept](#sicherheitskonzept)

## Übersicht

Die PowerOn AI Platform ist eine umfassende Anwendung zur Verwaltung und Durchführung von Multi-Agent-Workflows für komplexe Datenanalyse- und Verarbeitungsaufgaben. Die Plattform ermöglicht die Nutzung von verschiedenen AI-Modellen, Web-Scraping und Datenverarbeitung innerhalb einer benutzerfreundlichen Oberfläche.

### Hauptfunktionen

- **Multi-Agent-Workflows**: Koordination verschiedener spezialisierter AI-Agenten für komplexe Aufgaben
- **Web-Scraping**: Integration von Online-Recherche in Workflows
- **Dokumentenverarbeitung**: Analyse und Verarbeitung von Dokumenten und Bildern
- **Workspace-Management**: Organisation von Projekten in Workspaces
- **Benutzerverwaltung**: Mehrstufiges Benutzermanagement mit Mandantenstruktur
- **Modernes Frontend**: Responsive Benutzeroberfläche mit dynamischen Komponenten

## Architektur

Die PowerOn AI Platform ist als modulare Webanwendung mit einer klaren Trennung zwischen Frontend und Backend konzipiert.

### Backend

Das Backend basiert auf FastAPI (Python) und bietet folgende Komponenten:

- **Gateway-Interface**: Zentrale Komponente für Authentifizierung und Mandantenverwaltung
- **LucyDOM-Interface**: Datenbank-Interface für Workspaces, Agenten, Files und Prompts
- **Agent-Service**: Orchestrierung und Ausführung von Multi-Agent-Workflows
- **Connector-Module**: Integration mit externen Diensten (OpenAI, Anthropic, Web-Scraping)
- **JSON-Datenbank**: Lokale Datenspeicherung für Entwicklung und Deployment

### Frontend

Das Frontend wurde mit modernem JavaScript entwickelt:

- **Modularer Aufbau**: Klar strukturierte JS-Module mit ES6-Import/Export
- **Responsive Design**: Anpassungsfähige UI für verschiedene Bildschirmgrössen
- **Dynamische Komponenten**: Flexible UI-Elemente für verschiedene Anwendungsfälle
- **REST-API Integration**: Kommunikation mit dem Backend über standardisierte API-Aufrufe

## Kernmodule

### Gateway-Interface

Das Gateway-Interface (`gateway_interface.py`) ist verantwortlich für:

- Benutzerauthentifizierung und -autorisierung
- Mandantenverwaltung (Multi-Tenant-Architektur)
- Basisinitialisierung der Datenbank

### LucyDOM-Interface

Das LucyDOM-Interface (`lucydom_interface.py`) verwaltet:

- Workspaces und deren Inhalte
- Agenten und deren Konfiguration
- Dateiverwaltung und -zuordnung
- Prompts und Templates

### Agent-Service

Der Agent-Service (`agentservice_interface.py`) orchestriert:

- Ausführung von Multi-Agent-Workflows
- Koordination spezialisierter Agenten über einen Moderator
- Verarbeitung von Dateien und Prompts
- Sammlung und Speicherung von Workflow-Ergebnissen
- Interaktion mit dem Benutzer während eines Workflows

### Connector-Module

Verschiedene Connectors verbinden die Plattform mit externen Diensten:

- **AI-Chat-Connectors**: Integration mit OpenAI/Anthropic für die Agentenverarbeitung
- **Web-Scraping-Connector**: Durchführung von Online-Recherchen
- **DB-Connector**: JSON-basierte Datenspeicherung

## Benutzeroberfläche

Die Benutzeroberfläche ist modular aufgebaut und bietet verschiedene funktionale Bereiche:

### Navigation

- Hierarchische Menüstruktur mit Modulen und Untermenüs
- Workspace-Auswahl und -Verwaltung
- Benutzer- und Mandantenkontextverwaltung

### Module

#### Workspaces

- Erstellung und Verwaltung von Arbeitsbereichen
- Zentrale Organisation für Agenten, Dateien und Prompts

#### Agenten

- Verwaltung verschiedener spezialisierter Agenten
- Konfiguration von Agentenfähigkeiten und -beschreibungen
- Standardagenten: Initialisierung, Organisator, Entwickler, Webscraper, Datenanalyst, Textgenerator, Visualisierer

#### Dateien

- Upload und Verwaltung von Dokumenten und Bildern
- Integration in Workflows für Datenverarbeitung

#### Prompts

- Erstellung und Verwaltung von Template-Prompts
- Wiederverwendung in verschiedenen Workflows

#### Workflow

Das Workflow-Modul ist das Herzstück der Anwendung und ermöglicht:

- Auswahl von Agenten für spezifische Aufgaben
- Eingabe von Prompts und Anweisungen
- Auswahl relevanter Dateien für die Verarbeitung
- Echtzeit-Überwachung des Workflow-Fortschritts
- Interaktion mit dem Workflow während der Ausführung
- Anzeige und Speicherung von Ergebnissen

### Admin-Module

#### Mandantenverwaltung

- Erstellung und Konfiguration von Mandanten (nur für SysAdmin)
- Zuweisung von Standardressourcen für neue Mandanten

#### Benutzerverwaltung

- Erstellung und Verwaltung von Benutzern
- Rechteverwaltung mit drei Stufen: Benutzer, Admin, SysAdmin

## Datenmodell

Die PowerOn AI Platform verwendet ein strukturiertes Datenmodell:

### Mandanten (Mandates)

- **id**: Eindeutige ID
- **name**: Name des Mandanten
- **language**: Standardsprache
- **disabled**: Flag für deaktivierte Mandanten
- **contact_email**: Kontakt-E-Mail

### Benutzer (Users)

- **id**: Eindeutige ID
- **mandate_id**: Zugehöriger Mandant
- **username**: Eindeutiger Benutzername
- **hashed_password**: Gehashtes Passwort (Argon2)
- **email**: E-Mail-Adresse
- **full_name**: Vollständiger Name
- **disabled**: Flag für deaktivierte Benutzer
- **language**: Bevorzugte Sprache
- **privilege**: Berechtigungsstufe (user, admin, sysadmin)

### Workspaces

- **id**: Eindeutige ID
- **mandate_id**: Zugehöriger Mandant
- **user_id**: Ersteller des Workspace
- **name**: Name des Workspace
- **created_at**: Erstellungszeitpunkt

### Agenten (Agents)

- **id**: Eindeutige ID
- **mandate_id**: Zugehöriger Mandant
- **user_id**: Ersteller des Agenten
- **name**: Name des Agenten
- **type**: Typ des Agenten (initialisierung, organisator, entwickler, scraper, usw.)
- **workspace_id**: Zugehöriger Workspace
- **capabilities**: Fähigkeiten des Agenten
- **description**: Beschreibung des Agenten
- **instructions**: Anweisungen für den Agenten

### Dateien (Files)

- **id**: Eindeutige ID
- **mandate_id**: Zugehöriger Mandant
- **user_id**: Hochladender Benutzer
- **name**: Dateiname
- **type**: Dateityp (document, image, usw.)
- **content_type**: MIME-Typ
- **size**: Dateigrösse
- **path**: Speicherort der Datei
- **upload_date**: Hochladezeitpunkt

### Prompts

- **id**: Eindeutige ID
- **mandate_id**: Zugehöriger Mandant
- **user_id**: Ersteller des Prompts
- **content**: Prompt-Text
- **workspace_id**: Zugehöriger Workspace
- **created_at**: Erstellungszeitpunkt
- **name**: Name des Prompts

### Workflows

- **id**: Eindeutige ID (uuid)
- **mandate_id**: Zugehöriger Mandant
- **user_id**: Ausführender Benutzer
- **status**: Status (running, completed, failed, stopped)
- **progress**: Fortschritt (0.0-1.0)
- **started_at**: Startzeitpunkt
- **completed_at**: Abschlusszeitpunkt
- **agent_statuses**: Status der einzelnen Agenten
- **logs**: Ausführungsprotokolle
- **results**: Ergebnisse der Agenten
- **data_stats**: Statistiken zur Datenübertragung
- **chat_history**: Chat-Verlauf zwischen Agenten

## Multi-Agent Workflow-System

Das Multi-Agent-System ist das zentrale Element der PowerOn AI Platform und ermöglicht die Zusammenarbeit verschiedener spezialisierter Agenten.

### Workflow-Ablauf

1. **Initialisierung**: Nutzer wählt Agenten, Files und gibt einen Prompt ein
2. **Moderator-Phase**: Moderator koordiniert den Einsatz verschiedener Agenten
3. **Agentenausführung**: Spezifische Agenten führen ihre Aufgaben aus
4. **Benutzerinteraktion**: Bei Bedarf kann der Benutzer in den Workflow eingreifen
5. **Ergebnissammlung**: Ergebnisse werden aggregiert und gespeichert

### Verfügbare Standardagenten

Die Plattform bietet folgende vordefinierte Agentenrollen:

1. **Initialisierung**: Analysiert Anfragen, plant Aufgaben und beantwortet einfache Fragen
2. **Organisator**: Koordiniert komplexe Anfragen und erstellt strukturierte Arbeitspläne
3. **Entwickler**: Erstellt Programmcode und technische Implementierungen
4. **Webscraper**: Führt Web-Recherchen durch und bereitet Informationen auf
5. **Datenanalyst**: Analysiert Daten, identifiziert Muster und erstellt Berichte
6. **Textgenerator**: Erstellt qualitativ hochwertige Texte in verschiedenen Formaten
7. **Visualisierer**: Erstellt Datenvisualisierungen und visuelle Darstellungen

### User Agent

Ein besonderer Agententyp ist der "User Agent", der Benutzerinteraktionen während eines laufenden Workflows ermöglicht:

- Beantwortung von Fragen des Moderators oder anderer Agenten
- Bereitstellung zusätzlicher Dateien während der Ausführung
- Bestätigung von Ergebnissen oder Anforderung weiterer Analysen

## Externe Connectors

Die Plattform integriert verschiedene externe Dienste:

### AI-Chat-Connectors

- **OpenAI-Connector**: Integration mit OpenAI-API (Standard)
- **Anthropic-Connector**: Alternative Integration mit Anthropic's Claude-Modellen

Diese Connectors bieten:
- Verarbeitung von Text-Prompts
- Verarbeitung von Bildern und multimodalen Inhalten
- Anpassbare Parameter (temperature, max_tokens)

### Web-Scraping-Connector

Der Web-Scraping-Connector ermöglicht:
- Suche nach relevanten Websites basierend auf Keywords
- Extraktion von Inhalten aus Webseiten
- Bewertung und Strukturierung von Online-Informationen

### JSON-DB-Connector

Der JSON-Datenbank-Connector bietet:
- Persistente Datenspeicherung in JSON-Dateien
- Unterstützung für Multi-Tenant-Architektur
- Kontextbasierte Datenfilterung

## Installation und Konfiguration

### Systemanforderungen

- Python 3.8+ für das Backend
- Moderne Browser für das Frontend
- Ausreichend Speicherplatz für Dateiuploads und Datenbank

### Konfiguration

Die Konfiguration erfolgt über eine `config.ini`-Datei mit folgenden Sektionen:

- **Connector_AiOpenai**: API-Schlüssel und Parameter für OpenAI
- **Connector_AiWebscraping**: Parameter für Web-Scraping (Timeout, User-Agent, etc.)
- **Module_AgentserviceInterface**: Parameter für den Agent-Service

## API-Endpunkte

Die PowerOn AI Platform bietet eine umfassende REST-API:

### Authentifizierung

- **POST /api/token**: Login und Token-Generierung

### Benutzer

- **GET /api/user/me**: Informationen zum aktuellen Benutzer
- **GET /api/user**: Liste aller Benutzer (Admin)
- **POST /api/user**: Neuen Benutzer erstellen
- **PUT /api/user/{id}**: Benutzer aktualisieren
- **DELETE /api/user/{id}**: Benutzer löschen

### Mandanten

- **GET /api/mandates**: Liste aller Mandanten (SysAdmin)
- **POST /api/mandates**: Neuen Mandanten erstellen
- **PUT /api/mandates/{id}**: Mandant aktualisieren
- **DELETE /api/mandates/{id}**: Mandant löschen

### Workspaces

- **GET /api/workspaces**: Liste aller Workspaces
- **POST /api/workspaces**: Neuen Workspace erstellen
- **PUT /api/workspaces/{id}**: Workspace aktualisieren
- **DELETE /api/workspaces/{id}**: Workspace löschen

### Agenten

- **GET /api/agents**: Liste aller Agenten
- **POST /api/agents**: Neuen Agenten erstellen
- **PUT /api/agents/{id}**: Agenten aktualisieren
- **DELETE /api/agents/{id}**: Agenten löschen

### Dateien

- **GET /api/files**: Liste aller Dateien
- **POST /api/files/upload**: Datei hochladen
- **GET /api/files/{id}/download**: Datei herunterladen
- **DELETE /api/files/{id}**: Datei löschen

### Prompts

- **GET /api/prompts**: Liste aller Prompts
- **POST /api/prompts**: Neuen Prompt erstellen
- **PUT /api/prompts/{id}**: Prompt aktualisieren
- **DELETE /api/prompts/{id}**: Prompt löschen

### Workflows

- **POST /api/workflows/run**: Workflow starten
- **GET /api/workflows/{id}/status**: Workflow-Status abfragen
- **GET /api/workflows/{id}/logs**: Workflow-Logs abrufen
- **GET /api/workflows/{id}/results**: Workflow-Ergebnisse abrufen
- **POST /api/workflows/{id}/stop**: Workflow stoppen
- **POST /api/workflows/{id}/user-input**: Benutzereingabe senden

## Sicherheitskonzept

Die PowerOn AI Platform implementiert mehrere Sicherheitsebenen:

### Authentifizierung

- **Token-basierte Authentifizierung**: JWT-Tokens für API-Zugriff
- **Sichere Passworthashes**: Argon2-Algorithmus für Passwort-Hashing
- **Automatische Tokenaktualisierung**: Token-Aktualisierung bei Ablauf

### Autorisierung

- **Rollenbasierte Zugriffskontrolle**: 
  - **User**: Standardbenutzer mit Zugriff auf eigene Ressourcen
  - **Admin**: Verwaltung von Benutzern und Ressourcen im eigenen Mandanten
  - **SysAdmin**: Vollständige Systemverwaltung und Mandantenverwaltung

### Mandantenisolierung

- **Strikte Datentrennung**: Jeder Mandant hat nur Zugriff auf eigene Daten
- **Kontextbasierte Filterung**: Automatische Filterung von Abfrageergebnissen basierend auf Mandantenzugehörigkeit