wiki/b-reference/gateway/workflow.md

Workflow-Engine

Überblick

Die Workflow-Engine im Gateway orchestriert KI-gestützte Aufgabenpläne und die Ausführung einzelner Aktionen über eine gemeinsame Method/Action-Bibliothek. Sie verbindet die Schichten Workflow → Methods → Services → Interfaces → Connectors; Workflows importieren bewusst nicht direkt Interfaces, Connectors oder aicore (Zugriff über Services).

Einsatzorte (Konsumenten der Action Library):

• Workspace (Dynamic Mode): WorkflowProcessor / modeDynamic → Planung (Stage 1/2) → ActionExecutor
• Automation v1: WorkflowProcessor / modeAutomation → ActionExecutor
• Automation2: Graph-Engine mappt Nodes (_method / _action) auf dieselbe Library
• Workspace-Agent: ActionToolAdapter exponiert dynamicMode=True-Aktionen als Tools → ActionExecutor

Ausführungsmodell: Pro Workflow-Instanz sequentielle Ausführung (kein paralleles Multi-Task-Modell auf einer Instanz). Ausführungszähler (currentRound, currentTask, currentAction) liegen am ChatWorkflow (Single Source of Truth).

---

WorkflowManager

Zentrale Steuerung in gateway/modules/workflows/workflowManager.py (grosse Datei; Einstieg für Start/Stopp und Hauptloop).

Öffentliche / zentrale Verantwortlichkeiten (Konzept):

Bereich	Inhalt
Lebenszyklus	Start eines Workflow-Laufs, Verarbeitungsschleife, Beendigung
Planung	Aufgaben- und Aktionsplanung (modusabhängig; KI-Planning über Services)
Ausführung	Abarbeitung von Tasks/Actions in definierter Reihenfolge
Zustand	Anbindung an persistierten ChatWorkflow / Chat-DB über Service- und Interface-Schicht

Workflow-Zustände (konzeptionell): running, stopped, completed, failed.

Modi (Dokumentation): Klassische Beschreibung nennt u.a. React (iterativ, begrenzte Schritte) und Actionplan (Plan upfront, ein Pfad). Die erweiterte Planungsarchitektur (ai_plan_architecture.md) beschreibt zusätzlich dynamischen Modus mit zweistufiger Aktionsplanung (Stage 1: Aktionswahl + Ressourcen; optional Stage 2: Parametergenerierung).

---

Methoden

Methoden sind Python-Klassen unter gateway/modules/workflows/methods/; der Methodenname (self.name) ist der Registry-Schlüssel (z. B. ai, context). Aktionen sind über WorkflowActionDefinition registriert; viele tragen actionId im Muster <method>.<action> und dynamicMode=True für den Agent/Graph.

Method (self.name)	Actions (Registry-Keys)
context	getDocumentIndex, extractContent, neutralizeData, triggerPreprocessingServer
ai	process, webResearch, summarizeDocument, translateDocument, convertDocument, generateDocument, generateCode
outlook	readEmails, searchEmails, composeAndDraftEmailWithContext, sendDraftEmail
sharepoint	findDocumentPath, readDocuments, uploadDocument, listDocuments, analyzeFolderUsage, findSiteByUrl, downloadFileByPath, copyFile, uploadFile
clickup	listTasks, searchTasks, getTask, createTask, updateTask, uploadAttachment
jira	connectJira, exportTicketsAsJson, importTicketsFromJson, mergeTicketData, parseCsvContent, parseExcelContent, createCsvContent, createExcelContent
trustee	extractFromFiles, processDocuments, syncToAccounting
chatbot	queryDatabase
file	create

Hinweis: Ältere Kontext-Dokumente nennen für context u. a. saveContent / transformContent; der aktuelle Gateway-Stand listet die obigen Aktionen (Stand Abgleich Code / Review 2026-04-05).

---

Aktionen

• Registrierung: Jede Aktion ist eine WorkflowActionDefinition mit Metadaten, Parametern (WorkflowActionParameter, u. a. FrontendType) und execute-Callable.
• Ausführung: ActionExecutor löst methodName + actionName auf, validiert Parameter (Action Registry / Pydantic je nach Implementierung) und liefert ein ActionResult (Erfolg, Dokumente, Fehler).
• Dokumente: Ergebnisse werden typischerweise als strukturierte ActionDocument / Extraktionsartefakte (ContentExtracted / ContentPart) weitergereicht.
• Extraktion vs. KI: Zielarchitektur (siehe ai_plan_architecture.md): reine Extraktion (context.extractContent bzw. dokumentbezogene Pipeline) ist von KI-Aufrufen (serviceAi) zu trennen; KI-Methoden arbeiten bevorzugt mit bereits extrahierten ContentPart-Strukturen.
• Planung: Stage 1 liefert u. a. action (method.action), Zieltext, optional documentList / connectionReference; Stage 2 ergänzt bei Bedarf das Parameter-JSON ohne die Stage-1-Ressourcen zu überschreiben.

---

Schlüssel-Dateien

Pfad (unter gateway/modules/)	Rolle
workflows/workflowManager.py	Workflow-Orchestrierung, Einstieg
workflows/processing/	Processor, Modi (modeReact, modeActionplan, modeDynamic, …), ActionExecutor
workflows/methods/methodBase.py	Basis für Methoden, Aktions-Validierung
workflows/methods/method*/	Konkrete Methoden und Aktionen
datamodels/datamodelChat.py	ChatWorkflow, TaskContext, Task-/Plan-Modelle
datamodels/datamodelWorkflowActions.py	Aktionsdefinitionen
services/serviceWorkflow/	Fortschritt, Logs, Nachrichten/Dokumente am Workflow
services/serviceAi/	Planning- und Content-KI (kein direkter Workflow-Import aus Methods zurück)
interfaces/interfaceDbChat*	Persistenz Workflow/Nachrichten/Dokumente

---

Regeln / Invarianten

1. Schichten-Imports: Workflows importieren nur datamodels, services, interne workflows/*. Methods importieren datamodels, services, workflows.methods.* — keine direkten Interface-/Connector-/aicore-Imports in Methods.
2. Zustand am Workflow: Rund-/Task-/Action-Indices und Kontext gehören zum ChatWorkflow / TaskContext, nicht als lose Parameter durch alle Ebenen.
3. Typisierung: Bevorzugt Pydantic-Modelle für Planungs- und Aktionskontext (ActionDefinition, TaskResult, …); JSON aus KI-Calls über zentrale Parse-/Repair-Hilfen.
4. Sequenz: Ein Workflow läuft in einer Instanz sequentiell ab; parallele Ausführung ist kein Designziel der beschriebenen Engine.
5. Neutralisierung: Sensible Daten an KI-Modelle laufen über das zentrale Gate in serviceAi (mainServiceAi.py); die Workflow-Aktion context.neutralizeData ist eine explizite Neutralisierung extrahierter Inhalte und ersetzt nicht das globale KI-Gate (siehe Compliance-Doku).
6. Gemeinsame Library: Dieselben Actions werden von Chat-Workflow, Automation v1/v2 und Agent-Tools genutzt — Änderungen an actionId / Parametern wirken quer über alle Konsumenten.