ValueOn AG 0e4a0e0e62 fixes comcoach

2026-04-16 14:20:31 +02:00

17 KiB

Raw Blame History

Trustee Tooling Overhaul & PWG Demo Preparation

Beschreibung und Kontext

Für den PWG-Inspirationsworkshop (16. April 2026) werden drei Use Cases in PORTA demonstriert. Use Case 1 (Belegverarbeitung + Budgetkontrolle) und Use Case 3 (Datenneutralisierung) erfordern Code-Anpassungen im Trustee-Feature und im Agent-Tooling.

Business-Treiber: PWG AG (gemeinnützige Wohnungsstiftung Zürich, 200+ Liegenschaften, Abacus als Hauptsystem) evaluiert PORTA. Der Workshop ist die erste Live-Demo — Plattform-Tiefgang und funktionierende Schnittstellen sind entscheidend.

Risiko bei Nicht-Umsetzung: Demo scheitert an fehlenden Tools (Agent kann keine Buchhaltungsdaten lesen), langsamer Performance (jede Query startet neuen Sub-Agent-Loop) oder fehlendem Workflow im Graphical Editor.

Parallel zur Demo-Vorbereitung wird das Trustee-Tooling grundlegend überarbeitet. Die aktuelle Architektur hat strukturelle Schwächen, die auch im Produktivbetrieb problematisch sind.

Hinweis: Die Automation Unification (v1/v2 → Graphical Editor) ist abgeschlossen (siehe c-work/3-validate/2026-04-automation-unification.md, Status: done). Dieses Dokument baut auf dem konsolidierten System auf: Feature graphicalEditor, DB poweron_graphicaleditor, konsolidierter Scheduler.

Fokus und kritische Details

Ist-Zustand Trustee-Tooling (Analyse)

Fähigkeit	Status	Problem
Daten lesen (Agent)	`queryFeatureInstance` → Sub-Agent mit `browseTable`/`queryTable`	Jeder Call öffnet neue DB-Connection + startet 5-Runden-Agent-Loop mit AI-Calls. Kein Caching. Langsam (~5-15s pro Query).
Daten aus Buchhaltung importieren	`AccountingDataSync.importData()` via REST-Endpoint	Full-clear + Full-write bei jedem Import. Kein inkrementeller Sync. Kein Agent-Zugriff (nur REST).
Daten schreiben (Agent)	Nicht vorhanden	Agent kann keine Trustee-Positionen erstellen oder ändern.
Daten aggregieren	Nicht vorhanden	Sub-Agent hat nur row-level Tools. Keine SQL-Aggregationen (SUM, GROUP BY). Für Budgetvergleiche muss der Agent alle Rows laden und selbst rechnen.
Chart of Accounts	`AccountingBridge.getChartOfAccounts()` mit Cache auf `TrusteeAccountingConfig`	Funktioniert, aber nur für Bridge-interne Nutzung. Agent hat keinen direkten Zugriff.
Graph-Editor Nodes (Trustee)	3 Nodes in `nodeDefinitions/trustee.py`: `extractFromFiles`, `processDocuments`, `syncToAccounting`	Alle `dynamicMode=False` — nicht als Agent-Tools verfügbar. Für Graph-Editor nutzbar. Kein Node für `refreshAccountingData` / Datenimport.
Graph-Editor Nodes (SharePoint)	6 Nodes in `nodeDefinitions/sharepoint.py`: findFile, readFile, uploadFile, listFiles, downloadFile, copyFile	Vorhanden und funktional. `listFiles` + `downloadFile` reichen für den Demo-Flow.
Graph-Editor Nodes (Flow)	5 Nodes: ifElse, switch, loop, merge, delay	Loop-Node vorhanden (`flow.loop`). Nötig für "für jede Datei aus SharePoint → Trustee-Pipeline".
Node-Kategorie `trustee`	Nodes nutzen `category: "trustee"`	Fehlt in `nodeRegistry.getNodeTypesForApi()` Categories-Liste (Zeile 63-73) — Trustee-Nodes werden im Editor nicht unter eigener Kategorie angezeigt.
Toolbox `trustee`	Nicht vorhanden	Die Toolbox Registry (`toolboxRegistry.py`) hat Toolboxes für email, sharepoint, clickup, jira, workflow — aber keine für Trustee. Für den Agent-Zugriff auf Trustee-Actions (`dynamicMode=True`) wäre eine Toolbox sinnvoll.

Performance-Problem `queryFeatureInstance`

Der Hauptgrund für die langsame Query-Performance:

Neuer Sub-Agent pro Call — runFeatureDataAgent startet einen eigenen Agent-Loop (max 5 Runden, je ein AI-Call) für jede Frage. Das bedeutet: Main-Agent stellt Frage → Sub-Agent macht 1-3 AI-Calls um SQL zu generieren → Sub-Agent antwortet → Main-Agent verarbeitet.
Neue DB-Connection pro Call — DatabaseConnector wird jedes Mal neu instanziiert und geschlossen.
Kein Result-Cache — Identische Fragen werden jedes Mal neu beantwortet.

Ziel und Nicht-Ziele

Ziel:

Agent kann Trustee-Buchhaltungsdaten lesen (gecacht oder frisch vom externen System)
Agent kann Aggregationen auf Trustee-Daten ausführen (SUM, GROUP BY für Budgetvergleiche)
Graphical-Editor-Workflow für Belegverarbeitung (SharePoint → Trustee Import+Sync) funktioniert
Performance von Feature-Data-Queries deutlich verbessert
Demo für PWG-Workshop läuft stabil end-to-end

Explizit NICHT:

Kein vollständiger Umbau des Sub-Agent-Patterns
Keine neuen Abacus-API-Endpoints (nutzen bestehenden Connector)
Keine Frontend-Änderungen am Trustee-UI

Betroffene Module

Gateway: features/trustee/, serviceCenter/services/serviceAgent/ (inkl. toolboxRegistry.py), workflows/methods/methodTrustee/, features/graphicalEditor/nodeDefinitions/, features/graphicalEditor/nodeRegistry.py
Frontend: keine Änderungen
DB-Migration: nein (nutzt bestehende TrusteeData*-Tabellen in Feature-DB poweron_trustee)
Graphical Editor: Node-Definitionen + Kategorie-Registry + Workflow-Konfiguration für Demo

Entscheidungen

Datum	Entscheidung	Begründung
2026-04-07	Neues Tool `refreshTrusteeData` statt Erweiterung von `queryFeatureInstance`	Separation of Concerns: Sync ist eine schreibende Operation, Query ist lesend. Agent entscheidet selbst, ob er zuerst refreshen muss.
2026-04-07	`aggregateTable`-Tool im Sub-Agent statt SQL in `queryTable`	Saubere Trennung: row-level vs. aggregate. Verhindert SQL-Injection-Risiko bei freien GROUP BY-Ausdrücken.
2026-04-07	DB-Connection-Pooling für Feature-Data-Agent statt Connection-per-Call	Grösster Performance-Hebel. Connection-Aufbau ist teuer (~200ms), Pool eliminiert das.
2026-04-07	Result-Cache auf WorkflowMemory-Ebene	Nutzt bestehendes Konzept (WorkflowMemory mit Embedding). Agent kann gecachte Ergebnisse aus früheren Runden wiederverwenden.

Umsetzungs-Checkliste

Phase 1: Trustee Agent-Tools (Prio: hoch — Blocker für Demo UC1 Teil B)

refreshTrusteeData — Neue Workflow-Action trustee.refreshAccountingData mit dynamicMode=True
- Prüft TrusteeAccountingConfig.lastSyncAt — wenn älter als Schwellwert (z.B. 1h) oder Daten leer → triggert AccountingDataSync.importData()
- Parameter: featureInstanceId (required), forceRefresh (optional, default false), dateFrom/dateTo (optional)
- Rückgabe: Summary (Anzahl Records pro Tabelle, Sync-Dauer, ob frisch oder gecacht)
- Registrierung in MethodTrustee.__init__ analog zu bestehenden Actions
aggregateTable — Neues Tool im Feature-Data-Sub-Agent (featureDataAgent.py)
- SQL-Aggregationen: SUM, COUNT, AVG, MIN, MAX
- GROUP BY auf vordefinierte Felder (Whitelist pro Tabelle)
- Scope-Filter wie bei queryTable (featureInstanceId + mandateId)
- Beispiel: aggregateTable(tableName="TrusteeDataJournalLine", aggregate="SUM", field="debitAmount", groupBy="costCenter")

Phase 2: Graphical-Editor Node-Definitionen (Prio: hoch — Blocker für Demo UC1 Teil A)

Ist-Zustand Node-Registry (features/graphicalEditor/nodeDefinitions/):

Datei	Nodes	Status
`trustee.py`	`extractFromFiles`, `processDocuments`, `syncToAccounting`	Vorhanden, aber kein Node für Datenimport/Refresh
`sharepoint.py`	`findFile`, `readFile`, `uploadFile`, `listFiles`, `downloadFile`, `copyFile`	Vorhanden, ausreichend für Demo
`flow.py`	`ifElse`, `switch`, `loop`, `merge`, `delay`	Vorhanden, Loop-Node nötig für Demo

Anpassungen:

Kategorie trustee in nodeRegistry.py ergänzen
- In getNodeTypesForApi() → categories-Liste (Zeile 63-73) fehlt {"id": "trustee", "label": {"en": "Trustee", "de": "Treuhand", "fr": "Fiduciaire"}}
- Ohne diese Kategorie werden die Trustee-Nodes in der Node-Palette des Graphical Editors nicht unter einer eigenen Gruppe angezeigt
Neuer Node trustee.refreshAccountingData in nodeDefinitions/trustee.py
- Mapped auf neue Workflow-Action trustee.refreshAccountingData (Phase 1)
- Parameter: featureInstanceId (required), forceRefresh (optional), dateFrom/dateTo (optional)
- Kategorie: trustee, Icon: mdi-database-refresh, Color: #4CAF50
- Damit kann der Datenimport auch als Flow-Node genutzt werden (z.B. "Jeden Morgen Daten aus Abacus importieren")
[~] Neuer Node trustee.importAndProcess in nodeDefinitions/trustee.py (optional, Convenience) — übersprungen: bestehende 3 Nodes funktionieren dank Output-Chaining-Fix (s.u.)
- Kombiniert die Pipeline extractFromFiles → processDocuments → syncToAccounting in einem einzigen Node
- Vereinfacht den Demo-Flow auf 2 Nodes statt 4 (SharePoint Download → Trustee Import+Process+Sync)
- Parameter: connectionId, sharepointFolder, featureInstanceId, prompt
- Falls zu aufwändig: bestehende 3 Nodes einzeln im Flow verketten (funktioniert, ist aber visuell weniger eindrucksvoll)
Toolbox trustee in toolboxRegistry.py registrieren (für Agent-Zugriff)
- Analog zu sharepoint, email, clickup — Toolbox mit requiresConnection: false (Trustee hat eigene Config)
- Enthält refreshTrusteeData (Phase 1) und ggf. weitere Trustee-Actions wenn dynamicMode=True
- Ermöglicht dem Agent, Trustee-Tools via requestToolbox("trustee") zu aktivieren
Bestehende Trustee-Nodes prüfen und angepasst
- trustee.extractFromFiles: _paramMap korrekt (connectionId → connectionReference), Output = ActionDocument-Liste → wird via model_dump() serialisiert
- trustee.processDocuments: Fix implementiert — neue _resolveDocumentList() Funktion erkennt sowohl Graph-Editor-Output (Liste von Dicts mit documentData) als auch Chat-Referenzen (Fallback). Kein Chat-Service im Graph-Editor nötig.
- trustee.syncToAccounting: Fix implementiert — neue _resolveFirstDocument() Funktion mit gleicher Dual-Path-Logik
Output-Chaining verifiziert und gefixt:
- actionNodeExecutor.py Zeile 828: ActionDocument → model_dump() → Dict mit documentName, documentData, mimeType
- actionNodeExecutor.py Zeile 836-837: Output enthält documents + documentList (identisch)
- _getDocumentsFromUpstream() (Zeile 237) liest documents oder documentList aus dem Output-Dict
- Zeile 569: resolvedParams.setdefault("documentList", docs) mergt die Dicts in den nächsten Node
- Problem war: processDocuments und syncToAccounting nutzten DocumentReferenceList.from_string_list() + chat.getChatDocumentsFromDocumentList() — funktioniert nur im Chat-Kontext, nicht im Graph-Editor
- Lösung: Beide Actions erkennen jetzt direkt übergebene Dicts (Graph-Editor-Pfad) und nutzen Chat nur als Fallback — manuell testen

Phase 3: Performance (Prio: hoch — spürbar in jeder Demo)

DB-Connection-Pooling für Feature-Data-Agent
- Singleton DatabaseConnector pro Feature-DB (z.B. poweron_trustee) statt Connection-per-Call
- Pool in _featureSubAgentTools.py oder zentral im ServiceCenter
- Connection-Reuse über featureDbConnPool[featureDbName]
Sub-Agent Result-Caching
- Cache-Key: (featureInstanceId, question_hash, lastSyncAt)
- Invalidierung bei neuem Sync (lastSyncAt ändert sich)
- TTL: 5 Minuten (konfigurierbar)
- Speicherort: In-Memory Dict im Agent-Kontext (pro Workflow-Session)

Phase 4: Graphical-Editor Workflow für Demo (Prio: hoch — nötig für UC1 Teil A)

Workflow im Graphical Editor bauen: SharePoint Read Files Loop → Trustee Import+Sync
- Trigger: trigger.manual (mit Hinweis "könnte automatisch laufen")
- Node 1: sharepoint.listFiles → Ordner mit Belegen
- Node 2: flow.loop über die Dateiliste
- Node 3 (im Loop): sharepoint.downloadFile → PDF herunterladen
- Node 4 (im Loop): trustee.extractFromFiles → Belege extrahieren
- Node 5 (im Loop): trustee.processDocuments → Buchungen erstellen
- Node 6 (nach Loop): trustee.syncToAccounting → Sync mit Abacus
- Alternativ: trustee.importAndProcess Convenience-Node (Phase 2) statt Nodes 4-6
- Testen mit 3-4 Musterbelegen
- Workflow als System-Template speichern (templateScope: system)
Musterbelege erstellen: Handwerkerrechnung, Nebenkostenabrechnung, Bankbeleg, Versicherungsbeleg (PDFs)

Phase 5: Demo-Daten & Testläufe (Prio: mittel)

Budget-Excel erstellen (Soll-Werte 2026 pro Kostenstelle/Liegenschaft)
Demo-Prompt für Budgetkontrolle vorbereiten und testen
CommCoach-Personas für Immobilien-Kontext erstellen
Neutralisierungs-Demo mit fiktivem Mieterdossier testen
Demo-Mandant "PWG Demo" sauber aufsetzen
Alle 3 Use Cases end-to-end durchspielen

Akzeptanzkriterien

#	Kriterium (Given-When-Then)	Prio
1	Given Trustee-Instanz mit Abacus-Config, When Agent `refreshTrusteeData` aufruft, Then werden Daten aus Abacus in `TrusteeData*`-Tabellen importiert und Summary zurückgegeben	must
2	Given gecachte Daten (lastSyncAt < 1h), When Agent `refreshTrusteeData` ohne `forceRefresh` aufruft, Then wird kein externer Sync ausgelöst und gecachte Counts zurückgegeben	must
3	Given Trustee-Daten in DB, When Sub-Agent `aggregateTable` mit SUM/GROUP BY aufruft, Then kommen korrekte Aggregationen zurück (verifiziert gegen manuelle Berechnung)	must
4	Given identische Query innerhalb 5 Min, When `queryFeatureInstance` erneut aufgerufen wird, Then wird gecachtes Ergebnis zurückgegeben (kein neuer Sub-Agent-Loop)	should
5	Given Graphical Editor geöffnet, When Node-Palette geladen wird, Then erscheint Kategorie "Treuhand" mit allen Trustee-Nodes (inkl. neuem `refreshAccountingData`)	must
6	Given Workflow im Graphical Editor mit trigger.manual → sharepoint.listFiles → flow.loop → trustee.extractFromFiles → processDocuments → syncToAccounting, When Workflow manuell gestartet wird, Then werden PDFs aus SharePoint geladen, extrahiert und als Positionen mit Sync-Status im Trustee angezeigt	must
7	Given Trustee-Pipeline im Flow (extract → process → sync), When Node A Output an Node B weitergereicht wird, Then wird `documentList`-Referenz korrekt aufgelöst (Output-Chaining funktioniert)	must
8	Given Budget-Excel im Workspace + Trustee-Daten, When Budgetkontrolle-Prompt ausgeführt wird, Then erstellt Agent Soll/Ist-Vergleich mit Charts und sendet per Mail	must

Testplan

ID	AC	Art	Automatisiert	Repo-Pfad	Status
T1	1	api	nein (manuell mit Abacus-Sandbox)	—	pending
T2	2	api	ja	gateway/tests/features/trustee/test_refresh_tool.py	pending
T3	3	api	ja	gateway/tests/features/trustee/test_aggregate_table.py	pending
T4	4	api	ja	gateway/tests/serviceAgent/test_feature_data_cache.py	pending
T5	5	ui	nein (manuell)	—	pending
T6	6	e2e	nein (manuell)	—	pending
T7	7	api	ja	gateway/tests/workflows/graphicalEditor/test_node_chaining.py	pending
T8	8	e2e	nein (manuell)	—	pending

Abschluss

b-reference/gateway/workflow.md aktualisiert (neue Action trustee.refreshAccountingData)
b-reference/gateway/ai-agent.md aktualisiert (aggregateTable Tool im Sub-Agent, Trustee-Toolbox)
b-reference/gateway/automation.md aktualisiert (neue Trustee-Nodes + Kategorie in Node-Palette)
TOPICS.md aktualisiert (falls neues Thema)
Dieses Dokument → z-archive/ verschoben

17 KiB Raw Blame History