247 lines
8.5 KiB
Markdown
247 lines
8.5 KiB
Markdown
# 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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
|
|
1. **Document Processing**: Datei-Uploads werden mit Content Extraction verarbeitet.
|
|
2. **AI Language Support**: Sprache wird erkannt und im Workflow gesetzt.
|
|
3. **Round Counting**: Jede Interaktion inkrementiert `currentRound`.
|
|
4. **Agent Registry**: Agents werden dynamisch geladen und registriert.
|
|
5. **Standardized Task Processing**: Alle Agents implementieren das gleiche Task-Interface.
|