ValueOn AG d9d13dfc12 fix: refactored structure and removed mandates data

2025-11-11 19:16:25 +01:00

8.5 KiB

Raw Blame History

State Machine Documentation for Backend Chat Workflow

Overview

Das Backend implementiert eine State Machine, die Benutzereingaben, Agenten-Workflows und die Kommunikation mit dem Frontend orchestriert. Die State Machine steuert Statusübergänge, Logging, Dokumentenmanagement und Fehlerbehandlung für robuste Multi-Agent-Workflows.

Core Objects

Workflow Object

{
  "id": "uuid-string",
  "mandateId": int,
  "userId": int,
  "name": "Workflow name",
  "startedAt": "ISO-datetime",
  "status": "string", // running, completed, failed, stopped
  "lastActivity": "ISO-datetime",
  "dataStats": {
    "bytesSent": int,
    "bytesReceived": int,
    "tokensUsed": int,
    "processingTime": float
  },
  "currentRound": int,
  "messageIds": [ "string" ],
  "messages": [ /* WorkflowMessage */ ],
  "logs": [ /* WorkflowLog */ ]
}

Message Object

{
  "id": "msg_uuid-string",
  "workflowId": "workflow-uuid",
  "parentMessageId": "string|null",
  "startedAt": "ISO-datetime",
  "finishedAt": "ISO-datetime|null",
  "sequenceNo": int,
  "status": "string", // first, step, last
  "role": "string", // user, assistant, system
  "dataStats": { /* optional */ },
  "documents": [ /* Document */ ],
  "content": "string",
  "agentName": "string"
}

Log Entry Object

{
  "id": "log_uuid-string",
  "workflowId": "workflow-uuid",
  "message": "string",
  "type": "string", // info, warning, error
  "timestamp": "ISO-datetime",
  "agentName": "string",
  "status": "string", // running, completed, failed, stopped
  "progress": int, // Optional, 0-100
  "mandateId": int,
  "userId": int
}

Document Object

{
  "id": "doc_uuid-string",
  "fileId": int,
  "name": "string", // Filename ohne Extension
  "ext": "string", // File Extension
  "data": "base64-encoded-string", // File-Inhalt
  "contents": [ /* ContentItem */ ]
}

Content Item Object

{
  "sequenceNr": int, // Reihenfolge im Dokument
  "name": "string",
  "ext": "string",
  "contentType": "string", // mime type
  "data": "string|base64", // Originalinhalt
  "dataExtracted": "string", // Optional: AI-Extrakt
  "metadata": {
    "isText": boolean,
    "base64Encoded": boolean,
    "aiProcessed": boolean
    // Optional: weitere Metadaten
  },
  "summary": "string" // AI-generierte Zusammenfassung
}

State Machine Workflow

1. Workflow Initialization

Trigger: User message via /api/workflows/start oder /api/workflows/start?id=string
Input: UserInputRequest mit prompt und optional listFileId
Prozess:
- Wenn id existiert und Workflow existiert: Workflow laden, currentRound inkrementieren, Status auf "running"
- Sonst: Neuen Workflow anlegen, currentRound=1, Status "running"
Logs: "Workflow initialized" oder "Running workflow", progress 0%
API: 200 OK mit Workflow-ID, Fehler: 400/404/500

2. Workflow Exception

Trigger: User stoppt Workflow via API oder Exception tritt auf
Prozess:
- Bei Status=="stopped": Status auf "stopped", Log, lastActivity aktualisieren, sofort abbrechen
- Bei Status=="failed": Status auf "failed", Log, lastActivity aktualisieren, sofort abbrechen
- Sonst: Normal fortfahren
Logs: "Workflow failure reported", progress 100%
API: 200 OK bei Stop, 500 bei Exception

3. User Message Processing

Prozess:
- User-Input wird als Message-Objekt mit Dokumenten gespeichert, Status "first"
- Datei-Inhalte werden extrahiert (getDocumentContents())
- Statische Summaries für Content Items generieren
State Changes:
- User-Message zu workflow.messages und workflow.messageIds hinzufügen
- workflow.lastActivity aktualisieren
Logs: "Workflow processing started", progress 0%

4. Project Manager Analysis

Prozess:
- Prompt für Project Manager AI generieren
- Analyse und Workplan generieren
Outputs:
- objFinalDocuments: Liste erwarteter Output-Dokumente
- objWorkplan: Liste Agenten-Tasks
- objUserResponse: Textantwort an User
- userLanguage: Detektierte Sprache
State Changes:
- Assistant-Message mit Status "step" speichern
- User-Language im Interface setzen
Logs: "Analyzing request and planning work" (10%), "Work plan created" (25%)

5. Agent Execution

Prozess (für jeden Task im Workplan):
- Input-Dokumente vorbereiten
- Agent ausführen
- Output-Dokumente speichern
- Assistant-Message mit Status "step" speichern
Logs: "Running task X/Y: agentName" (30-90%)

6. Final Response Generation

Prozess:
- Final-Message mit Review der gelieferten Dokumente erzeugen
- Dokumente zum Workflow hinzufügen
State Changes: Final-Message mit Status "last" speichern
Logs: "Creating final response" (90%)

7. Workflow Completion

Prozess:
- Workflow finalisieren, Status auf "completed"
- workflow.lastActivity aktualisieren
Logs: "Workflow completed successfully" (100%)
API: Message mit Status "last" in Response, Status-Endpoint gibt "completed" zurück

8. Workflow Stopped

Trigger: /api/workflows/{workflowId}/stop
Prozess:
- Workflow sofort stoppen, Status auf "stopped"
- lastActivity aktualisieren
Logs: "Workflow stopped by user" (100%)
API: 200 OK

9. Workflow Failed

Trigger: Exception im Workflow
Prozess:
- Fehler loggen, Status auf "failed"
- lastActivity aktualisieren
Logs: Fehler-Log (100%)
API: Status-Endpoint gibt "failed" zurück

10. Workflow Resumption

Trigger: /api/workflows/start?id={workflowId}
Prozess:
- Workflow laden, currentRound inkrementieren, Status auf "running"
- Neue User-Message hinzufügen
Logs: "Resuming workflow, round {currentRound}" (0%)
API: wie Workflow-Init

11. Workflow Reset/Deletion

Trigger: /api/workflows/{workflowId} DELETE
Prozess:
- Workflow und zugehörige Daten löschen
Logs: System-Log "workflow deleted"
API: 200 OK oder 404

API Endpoints und Polling Support

Main Workflow Endpoints

POST /api/workflows/start?id=string: Startet neuen Workflow oder setzt fort
POST /api/workflows/{workflowId}/stop: Stoppt laufenden Workflow
DELETE /api/workflows/{workflowId}: Löscht Workflow
GET /api/workflows/{workflowId}/status: Holt Workflow-Status
GET /api/workflows/{workflowId}/logs?id=string: Holt Logs (optional ab ID)
GET /api/workflows/{workflowId}/messages?id=string: Holt Messages (optional ab ID)

Document Management

DELETE /api/workflows/{workflowId}/messages/{messageId}: Löscht Message
DELETE /api/workflows/{workflowId}/messages/{messageId}/files/{fileId}: Entfernt Datei aus Message

Backend Support für Frontend Polling

Selektive Datenübertragung via id-Parameter bei /logs und /messages
Logs enthalten Timestamp, Progress, Status
Messages enthalten Status ("first", "step", "last")
Status-Endpoint liefert nur Status und lastActivity
Caching für häufige Polling-Requests
Batch/Paging für große Log-/Message-Sets

Dokumentenstruktur

data: base64-kodierter Originalinhalt
contents: Liste extrahierter Content Items
Agents können auf das Original und die extrahierten Inhalte zugreifen

State Transitions

[null] → [running]               // New workflow created
[running] → [completed]          // Workflow completes successfully
[running] → [stopped]            // User manually stops workflow
[running] → [failed]             // Error occurs during workflow
[completed] → [running]          // User continues workflow with new input (new round)
[stopped] → [running]            // User continues after manual stop (new round)
[failed] → [running]             // User retries workflow despite error (new round)
[any] → [null]                   // Workflow deleted

Exception Handling

Status wird auf "failed" gesetzt bei Fehlern, Fehler werden im Log dokumentiert
Project Manager/Agenten-Outputs und Inputs werden für Debugging geloggt
HTTP-Fehler werden mit passendem Statuscode zurückgegeben
Fehlgeschlagene Agenten-Tasks werden geloggt, stoppen aber nicht den gesamten Workflow

Special Notes

Document Processing: Datei-Uploads werden mit Content Extraction verarbeitet.
AI Language Support: Sprache wird erkannt und im Workflow gesetzt.
Round Counting: Jede Interaktion inkrementiert currentRound.
Agent Registry: Agents werden dynamisch geladen und registriert.
Standardized Task Processing: Alle Agents implementieren das gleiche Task-Interface.

8.5 KiB Raw Blame History