{"openapi":"3.1.0","info":{"title":"Willi-Mako API v2","version":"1.1.0","description":"KI-gestützte Wissensplattform für die deutsche Energiewirtschaft. Umfasst Marktkommunikation (EDIFACT, GPKE, WiM, GeLi Gas, UTILMD, MSCONS), Regulierung (BNetzA, EnWG, StromNEV, ARegV, §14a EnWG), Netzbetrieb (TAB, VDE-FNN, SAIDI/SAIFI) und wissenschaftliche Studien.\n\n**Version 1.1.0 - OpenAI-Kompatible Chat API! 🚀**\n- ✅ **Neuer Endpoint /chat/completions** - OpenAI SDK-kompatibel mit RAG-Enhancement\n- ✅ **Drop-in Replacement** für OpenAI (nur Base-URL + API-Key ändern)\n- ✅ **Automatische QDrant-Suche** über 5 Collections (IMMER aktiv)\n- ✅ **System Instructions** via messages array (OpenAI-Format)\n- ✅ **Stateless Operation** - keine Session erforderlich\n- ✅ **RAG-Metadata transparent** in x_rag_metadata\n- 📝 **Details:** docs/api/v2/OPENAI-COMPATIBLE-CHAT-ENDPOINT.md\n\n**Version 1.0.2 - Cloudflare-Timeout GELÖST! 🎉**\n- ✅ **Heartbeat-Fix** im Streaming-Endpoint implementiert (alle 30s Events)\n- ✅ **Neuer Polling-Endpoint** für einfache Status-Checks (/chat/chats/{chatId}/status)\n- ✅ **Lightweight Response-Endpoint** für High-Frequency Polling (/chat/chats/{chatId}/latest-response)\n- ✅ **Zwei Lösungen:** Streaming (beste UX) oder Polling (einfachste Implementation)\n- 📝 **Details:** docs/api/v2/POLLING-ENDPOINT-GUIDE.md\n\n**Features:**\n- ✅ Session-Management mit MongoDB-TTL\n- ✅ Structured Data Integration mit Natural Language Queries (MaStR, Marktpartner, Strompreise)\n- ✅ Tooling, Artefakt-Management und mehrstufige Reasoning-Pipelines\n- ✅ Cloudflare-Timeout-Problem vollständig gelöst (Heartbeat + Polling)"},"servers":[{"url":"/api/v2","description":"Relative API v2 Base"},{"url":"/api/chat","description":"Legacy Chat Endpoints (für Streaming)"}],"paths":{"/auth/token":{"post":{"summary":"JWT Token erhalten","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","format":"password"}}}}}},"responses":{"200":{"description":"Token erfolgreich erstellt","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"accessToken":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}}}}}}}}},"/sessions":{"post":{"summary":"Session erstellen","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","properties":{"companiesOfInterest":{"type":"array","items":{"type":"string"}},"preferredTopics":{"type":"array","items":{"type":"string"}}}},"contextSettings":{"type":"object"},"ttlMinutes":{"type":"integer","minimum":1}}}}}},"responses":{"201":{"description":"Session erfolgreich erstellt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionEnvelopeResponse"}}}}}}},"/sessions/{sessionId}":{"get":{"summary":"Session abrufen","security":[{"bearerAuth":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Session gefunden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionEnvelopeResponse"}}}}}},"delete":{"summary":"Session löschen","security":[{"bearerAuth":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Session gelöscht"}}}},"/chat":{"post":{"summary":"Parität-Chat ausführen (SYNCHRON)","description":"⚠️ WICHTIG: Dieser Endpoint ist SYNCHRON und wartet auf die vollständige AI-Verarbeitung (kann 90+ Sekunden dauern). Bei Cloudflare-Proxy führt dies zu 504 Timeouts nach ~100s. Für lange Anfragen verwenden Sie stattdessen den Streaming-Endpoint `/api/chat/chats/{chatId}/messages/stream` oder Polling über `/api/chat/chats/{chatId}`.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId","message"],"properties":{"sessionId":{"type":"string","format":"uuid"},"message":{"type":"string"},"contextSettings":{"type":"object"},"timelineId":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Antwort aus Legacy-Chat (nur bei kurzen Anfragen < 90s)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"504":{"description":"Gateway Timeout - Anfrage dauert zu lange (> 90-100s). Verwenden Sie Streaming-Endpoint."}}}},"/chat/completions":{"post":{"summary":"OpenAI-kompatible Chat Completion (RAG-Enhanced) ✨","description":"✅ **OpenAI-kompatible Chat API** mit automatischer RAG-Enhancement\n\n**🎯 Besonderheit**: Nutzt dieselben QDrant Collections wie unsere Standard-Chat-API, aber mit OpenAI-kompatiblem Request/Response-Format.\n\n**� Authentifizierung**: Unterstützt **JWT Token** UND **API Token** (beide gleichwertig)\n- **JWT Token** (24-30 Tage): Via `/api/v2/auth/token`\n- **API Token** (90 Tage) ⭐ EMPFOHLEN: Via `/api/v2/user/tokens` selbst erstellen\n\nDokumentation: [API-TOKEN-MANAGEMENT.md](/docs/API-TOKEN-MANAGEMENT.md)\n\n**�📦 Drop-in Replacement**:\n```python\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=\"YOUR_WILLI_MAKO_TOKEN\",  # JWT oder API Token\n    base_url=\"https://stromhaltig.de/api/v2\"  # Nur diese Zeile ändern!\n)\n\nresponse = client.chat.completions.create(\n    model=\"willi-mako-rag\",\n    messages=[\n        {\"role\": \"system\", \"content\": \"Du bist ein Experte für Marktkommunikation.\"},\n        {\"role\": \"user\", \"content\": \"Was ist der Unterschied zwischen UTILMD und MSCONS?\"}\n    ]\n)\n\nprint(response.choices[0].message.content)\nprint(f\"RAG Docs: {response.x_rag_metadata['retrieved_documents']}\")\n```\n\n**Use-Cases**:\n- Migration von OpenAI zu Willi-Mako (nur Base-URL + API-Key ändern)\n- Externe Integrationen (Tools, die OpenAI-SDK nutzen)\n- Stateless-Anfragen (kein Session-Management nötig)\n- Custom System Instructions pro Request\n- Token-Zählung wichtig\n\n**⚠️ Wichtig**: RAG-Retrieval ist IMMER aktiv und kann nicht deaktiviert werden. Die QDrant-Suche über unsere Energie-Wissensbasis ist der Kern von Willi-Mako!\n\n**Features**:\n- ✅ OpenAI SDK-kompatibel (Python, Node.js, etc.)\n- ✅ Automatische QDrant-Suche über 5 Collections\n- ✅ System Instructions via `messages` array\n- ✅ Stateless (keine Session erforderlich)\n- ✅ Token Usage Statistics\n- ✅ RAG Metadata transparent (`x_rag_metadata`)\n- ✅ Unified Authentication (JWT + API Token)\n\n**Unterschied zu /chat**: \n- OpenAI-Format vs. Willi-Mako-Format\n- Stateless vs. Session-basiert\n- Conversation History im Request vs. Server-seitig\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["messages"],"properties":{"messages":{"type":"array","description":"Conversation history im OpenAI-Format","items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","user","assistant"],"description":"Rolle des Teilnehmers"},"content":{"type":"string","description":"Nachrichteninhalt"},"name":{"type":"string","description":"Optional: Name des Teilnehmers"}}},"minItems":1},"model":{"type":"string","description":"Modell-Name (optional, wird ignoriert - wir nutzen unser aktives LLM)","example":"willi-mako-rag"},"temperature":{"type":"number","minimum":0,"maximum":2,"default":0.7,"description":"Temperature für Sampling"},"max_tokens":{"type":"integer","minimum":1,"maximum":32000,"default":2048,"description":"Maximale Anzahl Tokens in der Antwort"},"top_p":{"type":"number","minimum":0,"maximum":1,"default":1,"description":"Top-p Sampling"},"stream":{"type":"boolean","default":false,"description":"Streaming aktivieren (Phase 2, derzeit nicht unterstützt)"},"stop":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Stop sequences"},"presence_penalty":{"type":"number","minimum":-2,"maximum":2,"default":0,"description":"Presence penalty"},"frequency_penalty":{"type":"number","minimum":-2,"maximum":2,"default":0,"description":"Frequency penalty"},"context_settings":{"type":"object","description":"⚠️ Diese Settings ERGÄNZEN die automatische QDrant-Suche (schalten sie NICHT ab!)","properties":{"includeUserDocuments":{"type":"boolean","description":"User-spezifische Dokumente einbeziehen"},"includeUserNotes":{"type":"boolean","description":"User-spezifische Notizen einbeziehen"},"includeSystemKnowledge":{"type":"boolean","default":true,"description":"System-Wissensbasis (QDrant) - Default: true, IMMER AKTIV"},"targetCollections":{"type":"array","items":{"type":"string","enum":["willi_mako","willi-netz","cs30","willi-cs","s4hu"]},"description":"Collection Override: Nur spezifische Collections durchsuchen. Default: Alle 5 Collections"},"timelineId":{"type":"string","format":"uuid","description":"Timeline-ID für Audit-Logging"}}},"session_id":{"type":"string","format":"uuid","description":"Optional: Session-ID für Zustandsverwaltung"}}},"examples":{"simple-question":{"summary":"Einfache Frage ohne System Instructions","value":{"messages":[{"role":"user","content":"Was ist der Unterschied zwischen UTILMD und MSCONS?"}]}},"with-system-instructions":{"summary":"Mit System Instructions und Conversation History","value":{"messages":[{"role":"system","content":"Du bist ein Senior-Berater für Netzbetreiber. Antworte präzise und verweise auf gesetzliche Grundlagen."},{"role":"user","content":"Welche Fristen gelten für den Lieferantenwechsel?"},{"role":"assistant","content":"Der Lieferantenwechsel muss innerhalb von 3 Wochen nach Vertragsabschluss durchgeführt werden..."},{"role":"user","content":"Und was passiert bei Verzögerungen?"}],"temperature":0.5,"max_tokens":1500}},"restricted-collections":{"summary":"Nur willi-netz Collection durchsuchen","value":{"messages":[{"role":"user","content":"Was sind die TAB-Anforderungen für PV-Anlagen?"}],"context_settings":{"targetCollections":["willi-netz"]}}}}}}},"responses":{"200":{"description":"Chat Completion Response (OpenAI-kompatibel + Extensions)","content":{"application/json":{"schema":{"type":"object","required":["id","object","created","model","choices","usage"],"properties":{"id":{"type":"string","example":"chatcmpl-abc123","description":"Eindeutige ID für diese Completion"},"object":{"type":"string","enum":["chat.completion"],"description":"Objekt-Typ (OpenAI-Standard)"},"created":{"type":"integer","description":"Unix timestamp"},"model":{"type":"string","example":"willi-mako-rag-gemini","description":"Verwendetes Modell"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"message":{"type":"object","properties":{"role":{"type":"string","enum":["assistant"]},"content":{"type":"string","description":"Generierte Antwort"}}},"finish_reason":{"type":"string","enum":["stop","length","content_filter"],"description":"Warum die Generation gestoppt wurde"}}}},"usage":{"type":"object","description":"Token-Verbrauch (Näherung)","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}},"x_rag_metadata":{"type":"object","description":"✨ Willi-Mako Extension: RAG-Metadata","properties":{"searched_collections":{"type":"array","items":{"type":"string"},"description":"Welche Collections wurden durchsucht"},"retrieved_documents":{"type":"integer","description":"Anzahl gefundener relevanter Dokumente"},"retrieval_duration_ms":{"type":"integer","description":"Retrieval-Dauer in Millisekunden"},"search_strategy":{"type":"string","enum":["semantic","hybrid","keyword"],"description":"Verwendete Search-Strategie"},"top_source_ids":{"type":"array","items":{"type":"string"},"description":"Top 3 Quellen-IDs"}}},"x_system_info":{"type":"object","description":"✨ Willi-Mako Extension: System-Informationen","properties":{"version":{"type":"string"},"active_llm":{"type":"string"}}}}},"example":{"id":"chatcmpl-abc123","object":"chat.completion","created":1702835234,"model":"willi-mako-rag-gemini","choices":[{"index":0,"message":{"role":"assistant","content":"UTILMD ist eine Nachricht für Stammdatenmitteilungen (z.B. Anmeldung, Abmeldung), während MSCONS Messwertübermittlungen enthält..."},"finish_reason":"stop"}],"usage":{"prompt_tokens":1250,"completion_tokens":320,"total_tokens":1570},"x_rag_metadata":{"searched_collections":["willi_mako","willi-netz","cs30","willi-cs","s4hu"],"retrieved_documents":18,"retrieval_duration_ms":234,"search_strategy":"hybrid","top_source_ids":["doc-123","doc-456","doc-789"]},"x_system_info":{"version":"1.0.0","active_llm":"gemini"}}}}},"400":{"description":"Invalid Request (OpenAI-kompatible Error Response)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["invalid_request_error","authentication_error","rate_limit_error","server_error"]},"code":{"type":"string"},"param":{"type":"string"}}}}}}}},"501":{"description":"Streaming nicht unterstützt (Phase 2)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string"},"code":{"type":"string"}}}}}}}}}},"get":{"summary":"Endpoint-Informationen","description":"Gibt Metainformationen über den Chat Completions Endpoint zurück","responses":{"200":{"description":"Endpoint-Informationen","content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"features":{"type":"array","items":{"type":"string"}},"supported_methods":{"type":"array","items":{"type":"string"}},"streaming_support":{"type":"boolean"},"max_tokens":{"type":"integer"},"default_temperature":{"type":"number"},"collections":{"type":"array","items":{"type":"string"}}}}}}}}}},"/chat/chats/{chatId}/messages/stream":{"post":{"summary":"Chat mit Server-Sent Events (✅ HEARTBEAT-FIX IMPLEMENTIERT!)","description":"✅ **CLOUDFLARE-TIMEOUT GELÖST!** Dieser Endpoint sendet jetzt Heartbeat-Events alle 30 Sekunden.\n\n**Was wurde gefixt:**\n- ✅ Heartbeat-Timer implementiert (sendet alle 30s ein Event)\n- ✅ Verhindert Cloudflare-Timeout auch bei > 3 Minuten AI-Verarbeitung\n- ✅ Funktioniert jetzt zuverlässig bei langen Anfragen\n\n**Wie es funktioniert:**\n1. Client startet SSE-Verbindung\n2. Server sendet initiale Status-Events\n3. Während AI-Verarbeitung: Heartbeat alle 30s (\"Verarbeitung läuft...\")\n4. Bei Completion: Finale Events mit vollständiger Antwort\n\n**Alternative (einfacher):** Nutzen Sie den neuen Polling-Endpoint `/chat/chats/{chatId}/status` wenn Sie keine SSE-Komplexität wollen.\n\nDetails: `docs/api/v2/POLLING-ENDPOINT-GUIDE.md`","security":[{"bearerAuth":[]}],"servers":[{"url":"/api/chat","description":"Legacy Chat Base"}],"parameters":[{"name":"chatId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Die legacyChatId aus der Session"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","description":"Die Chat-Nachricht"},"contextSettings":{"type":"object","description":"Context-Einstellungen (searchType, topK, etc.)"}}}}}},"responses":{"200":{"description":"Server-Sent Events Stream mit progressiven Updates. Verhindert Cloudflare 504 Timeouts durch kontinuierliche Status-Updates während der AI-Verarbeitung.","content":{"text/event-stream":{"schema":{"type":"string","description":"SSE Stream mit JSON-Events gemäß SSEStreamEvent Schema. Jedes Event hat die Form: `data: {type, message?, progress?, data?}\\n\\n`. Weitere Details siehe CloudflareTimeoutInfo Schema.","example":"data: {\"type\":\"status\",\"message\":\"Starte Anfrage...\",\"progress\":10}\n\ndata: {\"type\":\"status\",\"message\":\"Durchsuche Wissensdatenbank...\",\"progress\":30}\n\ndata: {\"type\":\"progress\",\"message\":\"Generiere Antwort...\",\"progress\":70}\n\ndata: {\"type\":\"complete\",\"progress\":100,\"data\":{\"userMessage\":{...},\"assistantMessage\":{...}}}\n\n"},"examples":{"status-event":{"value":"data: {\"type\":\"status\",\"message\":\"Durchsuche Wissensdatenbank...\",\"progress\":30}\n\n","description":"Status-Update während der Verarbeitung"},"complete-event":{"value":"data: {\"type\":\"complete\",\"progress\":100,\"data\":{\"userMessage\":{\"id\":\"msg-1\",\"role\":\"user\",\"content\":\"Frage\"},\"assistantMessage\":{\"id\":\"msg-2\",\"role\":\"assistant\",\"content\":\"Antwort\"}}}\n\n","description":"Finale Nachricht mit vollständigen Daten"},"error-event":{"value":"data: {\"type\":\"error\",\"message\":\"Fehler bei der Verarbeitung\"}\n\n","description":"Fehler-Event"}}}}}},"x-code-samples":[{"lang":"JavaScript","source":"// Streaming-Client Beispiel\nconst response = await fetch('/api/chat/chats/CHAT_ID/messages/stream', {\n  method: 'POST',\n  headers: {\n    'Authorization': 'Bearer TOKEN',\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify({\n    content: 'Erkläre den GPKE-Prozess'\n  })\n});\n\nconst reader = response.body.getReader();\nconst decoder = new TextDecoder();\n\nwhile (true) {\n  const { done, value } = await reader.read();\n  if (done) break;\n  \n  const chunk = decoder.decode(value);\n  const lines = chunk.split('\\n\\n');\n  \n  for (const line of lines) {\n    if (line.startsWith('data: ')) {\n      const event = JSON.parse(line.slice(6));\n      console.log(event.type, event.message, event.progress);\n      \n      if (event.type === 'complete') {\n        console.log('Antwort:', event.data.assistantMessage.content);\n      }\n    }\n  }\n}"}]}},"/chat/chats/{chatId}":{"get":{"summary":"Chat mit allen Nachrichten abrufen","description":"Gibt alle Nachrichten eines Chats zurück. Verwenden Sie dies für Polling: Regelmäßig abrufen bis neue Assistant-Nachricht erscheint.","security":[{"bearerAuth":[]}],"servers":[{"url":"/api/chat","description":"Legacy Chat Base"}],"parameters":[{"name":"chatId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Die legacyChatId aus der Session"}],"responses":{"200":{"description":"Chat mit allen Nachrichten","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"chat":{"type":"object","properties":{"id":{"type":"string"},"user_id":{"type":"string"},"title":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"metadata":{"type":"object"}}},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"chat_id":{"type":"string"},"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"},"metadata":{"type":"object"},"created_at":{"type":"string","format":"date-time"}}}}}}}}}}}},"/chat/chats/{chatId}/status":{"get":{"summary":"Chat-Status und letzte Nachrichten abrufen (POLLING-ENDPOINT)","description":"✅ **EMPFOHLENER POLLING-ENDPOINT** wenn SSE/Streaming fehlschlägt oder für einfachere Client-Implementation!\n\n**Use-Case:**\n- Prüfen ob Backend noch eine Antwort verarbeitet (status: \"processing\")\n- Letzte User- und Assistant-Nachricht abrufen\n- Geschätzten Fortschritt anzeigen (estimatedProgress)\n\n**Polling-Pattern:**\n```javascript\n// 1. Session + Chat erstellen (wie gewohnt)\nconst session = await createSession();\nconst chatId = session.legacyChatId;\n\n// 2. Nachricht senden (synchron, kann timeout)\ntry {\n  await fetch('/api/v2/chat', { \n    method: 'POST',\n    body: JSON.stringify({ sessionId, message: 'Frage...' })\n  });\n} catch (error) {\n  // Timeout oder Netzwerkfehler → egal, backend arbeitet weiter!\n  console.log('Request failed, starting polling...');\n}\n\n// 3. Status pollen bis \"completed\"\nconst poll = setInterval(async () => {\n  const status = await fetch(`/api/chat/chats/${chatId}/status`, {\n    headers: { 'Authorization': 'Bearer TOKEN' }\n  }).then(r => r.json());\n  \n  console.log('Status:', status.data.status, status.data.estimatedProgress + '%');\n  \n  if (status.data.status === 'completed') {\n    clearInterval(poll);\n    const answer = status.data.latestMessages.assistant;\n    console.log('Antwort:', answer.content);\n  }\n}, 5000); // Alle 5 Sekunden\n```\n\n**Vorteile:**\n- ✅ Funktioniert auch bei Cloudflare-Timeouts\n- ✅ Sehr einfache Client-Implementation\n- ✅ Backend arbeitet im Hintergrund weiter\n- ✅ Kein SSE-Support nötig","security":[{"bearerAuth":[]}],"servers":[{"url":"/api/chat","description":"Legacy Chat Base"}],"parameters":[{"name":"chatId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Die legacyChatId aus der Session"}],"responses":{"200":{"description":"Chat-Status mit letzten Nachrichten","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"chatId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["idle","processing","completed","error"],"description":"idle = nichts passiert, processing = Backend arbeitet, completed = Antwort fertig, error = Fehler aufgetreten"},"estimatedProgress":{"type":"integer","minimum":0,"maximum":100,"description":"Geschätzter Fortschritt in Prozent (0-100)"},"processingTimeMs":{"type":"integer","description":"Zeit seit Start der Verarbeitung in Millisekunden (0 wenn idle)"},"chat":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"latestMessages":{"type":"object","properties":{"user":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"content":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"assistant":{"type":"object","nullable":true,"description":"Letzte Antwort - null wenn noch keine Antwort vorhanden","properties":{"id":{"type":"string"},"content":{"type":"string","description":"Die vollständige AI-Antwort"},"createdAt":{"type":"string","format":"date-time"},"metadata":{"type":"object"}}}}},"pollingAdvice":{"type":"object","description":"Empfohlenes Polling-Intervall basierend auf Status","properties":{"recommended":{"type":"boolean","description":"Soll weiter gepollt werden?"},"intervalMs":{"type":"integer","description":"Empfohlenes Intervall in Millisekunden"},"message":{"type":"string","description":"Menschenlesbare Empfehlung"}}}}}}},"examples":{"processing":{"value":{"success":true,"data":{"chatId":"abc-123","status":"processing","estimatedProgress":45,"processingTimeMs":67000,"chat":{"id":"abc-123","createdAt":"2025-12-15T14:00:00Z","updatedAt":"2025-12-15T14:01:07Z"},"latestMessages":{"user":{"id":"msg-1","content":"Erkläre GPKE","createdAt":"2025-12-15T14:00:30Z"},"assistant":null},"pollingAdvice":{"recommended":true,"intervalMs":5000,"message":"Backend verarbeitet Anfrage. Pollen Sie alle 5 Sekunden."}}}},"completed":{"value":{"success":true,"data":{"chatId":"abc-123","status":"completed","estimatedProgress":100,"processingTimeMs":0,"latestMessages":{"user":{"id":"msg-1","content":"Erkläre GPKE","createdAt":"2025-12-15T14:00:30Z"},"assistant":{"id":"msg-2","content":"Der GPKE-Prozess (Geschäftsprozesse zur Kundenbelieferung mit Elektrizität)...","createdAt":"2025-12-15T14:02:45Z"}},"pollingAdvice":{"recommended":false,"intervalMs":10000,"message":"Chat ist idle. Pollen Sie alle 10 Sekunden oder weniger häufig."}}}}}}}}}}},"/chat/chats/{chatId}/latest-response":{"get":{"summary":"Nur die letzte Antwort abrufen (Lightweight Polling)","description":"Ultra-leichtgewichtiger Endpoint um nur die letzte Assistant-Nachricht abzurufen. Perfekt für High-Frequency Polling ohne Status-Overhead.","security":[{"bearerAuth":[]}],"servers":[{"url":"/api/chat","description":"Legacy Chat Base"}],"parameters":[{"name":"chatId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Die legacyChatId aus der Session"}],"responses":{"200":{"description":"Letzte Assistant-Nachricht","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","nullable":true,"description":"null wenn noch keine Antwort vorhanden","properties":{"id":{"type":"string"},"content":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"metadata":{"type":"object"}}},"message":{"type":"string"}}}}}}}}},"/retrieval/semantic-search":{"post":{"summary":"Semantische Suche über willi_mako Collection (Marktkommunikation)","description":"Durchsucht die willi_mako Collection mit Fokus auf Marktkommunikation: EDIFACT-Standards, GPKE (Geschäftsprozesse zur Kundenbelieferung mit Elektrizität), WiM (Wechselprozesse im Messstellenbetrieb), GeLi Gas, UTILMD (Stammdaten- und Prozessmeldungen), MSCONS (Messwertübermittlung), ORDERS, PRICAT, INVOIC, BDEW-Prüfkataloge. Ideal für operative Marktkommunikationsfragen, Lieferantenwechsel, Bilanzkreismanagement.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId","query"],"properties":{"sessionId":{"type":"string","format":"uuid"},"query":{"type":"string"},"options":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":100},"alpha":{"type":"number"},"outlineScoping":{"type":"boolean"},"excludeVisual":{"type":"boolean"}}}}}}}},"responses":{"200":{"description":"Trefferliste der semantischen Suche","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"query":{"type":"string"},"totalResults":{"type":"integer"},"durationMs":{"type":"number"},"options":{"type":"object","properties":{"limit":{"type":"integer"},"alpha":{"type":"number","nullable":true},"outlineScoping":{"type":"boolean"},"excludeVisual":{"type":"boolean"}}},"results":{"type":"array","items":{"$ref":"#/components/schemas/SemanticSearchResultItem"}}}}}}}}}}}},"/willi-netz/semantic-search":{"post":{"summary":"Semantische Suche über willi-netz Collection (Regulierung & Netzbetrieb)","description":"Durchsucht die willi-netz Collection, spezialisiert auf kaufmännisches Netzmanagement, Regulierung und Asset Management bei Verteilnetzbetreibern. Enthält: Energierecht (EnWG, StromNEV, ARegV), BNetzA-Festlegungen & Monitoringberichte, TAB von Netzbetreibern (Westnetz, Netze BW, etc.), BDEW-Leitfäden, VDE-FNN Hinweise, Asset Management (ISO 55000), wissenschaftliche Studien zur Energiewirtschaft. Typische Anfragen: Erlösobergrenzen, §14a EnWG, SAIDI/SAIFI, TAB-Anforderungen, Netzentgelte, Tagungsbände.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId","query"],"properties":{"sessionId":{"type":"string","format":"uuid"},"query":{"type":"string"},"options":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":100},"alpha":{"type":"number"},"outlineScoping":{"type":"boolean"},"excludeVisual":{"type":"boolean"}}}}}}}},"responses":{"200":{"description":"Trefferliste der semantischen Suche aus willi-netz","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"collection":{"type":"string","enum":["willi-netz"]},"query":{"type":"string"},"totalResults":{"type":"integer"},"durationMs":{"type":"number"},"options":{"type":"object","properties":{"limit":{"type":"integer"},"alpha":{"type":"number","nullable":true},"outlineScoping":{"type":"boolean"},"excludeVisual":{"type":"boolean"}}},"results":{"type":"array","items":{"$ref":"#/components/schemas/SemanticSearchResultItem"}}}}}}}}}}}},"/willi-netz/chat":{"post":{"summary":"Chat über willi-netz Collection (Regulierung & Netzbetrieb)","description":"Chat-Interaktion basierend auf der willi-netz Collection (Netzmanagement, Regulierung, TAB, Asset Management, wissenschaftliche Studien). Ideal für Fragen zu: BNetzA-Regulierung, Anreizregulierung (ARegV), Technische Anschlussbedingungen, §14a EnWG, Smart Meter, E-Mobilität, Speicher, NEST-Projekt, Versorgungsqualität (SAIDI/SAIFI), Tagungsbände und wissenschaftliche Veröffentlichungen.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId","message"],"properties":{"sessionId":{"type":"string","format":"uuid"},"message":{"type":"string"},"contextSettings":{"type":"object"},"timelineId":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Antwort aus willi-netz Chat","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"collection":{"type":"string","enum":["willi-netz"]}},"additionalProperties":true}}}}}}}}},"/combined/semantic-search":{"post":{"summary":"Semantische Suche übergreifend über 5 Collections (willi_mako, willi-netz, cs30, willi-cs, s4hu)","description":"Durchsucht parallel alle 5 Collections und vereint die Ergebnisse für ein breites Wissensspektrum. willi_mako: EDIFACT, Marktkommunikation (GPKE, WiM, GeLi Gas), UTILMD, MSCONS, ORDERS, Prüfkataloge. willi-netz: Netzmanagement, BNetzA-Regulierung, TAB, Asset Management, EnWG/ARegV, wissenschaftliche Studien. cs30: Schleupen CS/30 Software-Dokumentation. willi-cs: weitere Wissensbasis. s4hu: weitere Wissensbasis. Ergebnisse enthalten sourceCollection-Information im Payload. Ideal für übergreifende Recherchen, die mehrere Wissensbereiche betreffen.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId","query"],"properties":{"sessionId":{"type":"string","format":"uuid"},"query":{"type":"string"},"options":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":100},"alpha":{"type":"number"},"outlineScoping":{"type":"boolean"},"excludeVisual":{"type":"boolean"}}}}}}}},"responses":{"200":{"description":"Kombinierte Trefferliste aus allen 5 Collections","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"collections":{"type":"array","items":{"type":"string"},"example":["willi_mako","willi-netz","cs30","willi-cs","s4hu"]},"query":{"type":"string"},"totalResults":{"type":"integer"},"durationMs":{"type":"number"},"options":{"type":"object","properties":{"limit":{"type":"integer"},"alpha":{"type":"number","nullable":true},"outlineScoping":{"type":"boolean"},"excludeVisual":{"type":"boolean"}}},"results":{"type":"array","items":{"$ref":"#/components/schemas/SemanticSearchResultItem"}}}}}}}}}}}},"/combined/chat":{"post":{"summary":"Chat übergreifend über 5 Collections (willi_mako, willi-netz, cs30, willi-cs, s4hu)","description":"Chat-Interaktion mit Zugriff auf alle 5 Collections. Nutzt automatisch die relevanteste Collection basierend auf der Anfrage. Ideal für komplexe Fragen, die mehrere Wissensbereiche betreffen: Marktkommunikation (EDIFACT, Lieferantenwechsel), Regulierung (Netzentgelte, TAB, §14a EnWG), Schleupen Software (CS/30), wissenschaftliche Studien und weitere Wissensbasen.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId","message"],"properties":{"sessionId":{"type":"string","format":"uuid"},"message":{"type":"string"},"contextSettings":{"type":"object"},"timelineId":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Antwort aus kombiniertem Chat (5 Collections)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"collections":{"type":"array","items":{"type":"string"},"example":["willi_mako","willi-netz","cs30","willi-cs","s4hu"]}},"additionalProperties":true}}}}}}}}},"/message-analyzer/analyze":{"post":{"summary":"EDIFACT-Nachricht strukturell analysieren","description":"Führt eine strukturelle Analyse einer EDIFACT-Nachricht durch, extrahiert Segmente und reichert sie mit Code-Lookup-Informationen an.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Die zu analysierende EDIFACT-Nachricht","example":"UNH+00000000001111+MSCONS:D:11A:UN:2.6e\\nBGM+E01+1234567890+9\\nUNT+3+00000000001111"}}}}}},"responses":{"200":{"description":"Analyseergebnis","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/EdifactAnalysisResult"}}}}}},"400":{"description":"Ungültige Anfrage"}}}},"/message-analyzer/explanation":{"post":{"summary":"KI-Erklärung einer EDIFACT-Nachricht generieren","description":"Generiert eine verständliche, strukturierte Erklärung einer EDIFACT-Nachricht unter Nutzung von LLM und Expertenwissen.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Die zu erklärende EDIFACT-Nachricht"}}}}}},"responses":{"200":{"description":"KI-generierte Erklärung","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"explanation":{"type":"string","description":"Verständliche Erklärung der Nachricht"},"success":{"type":"boolean"}}}}}}}}}}},"/message-analyzer/chat":{"post":{"summary":"Interaktiver Chat über EDIFACT-Nachricht","description":"Ermöglicht interaktive Fragen und Diskussionen über eine EDIFACT-Nachricht mit kontextbewusstem KI-Assistenten.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message","currentEdifactMessage"],"properties":{"message":{"type":"string","description":"Die Frage oder Nachricht des Benutzers","example":"In welchem Zeitfenster ist der Verbrauch am höchsten?"},"chatHistory":{"type":"array","description":"Bisheriger Chat-Verlauf","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"}}}},"currentEdifactMessage":{"type":"string","description":"Die aktuelle EDIFACT-Nachricht als Kontext"}}}}}},"responses":{"200":{"description":"Chat-Antwort","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"response":{"type":"string","description":"KI-Antwort auf die Frage"},"timestamp":{"type":"string","format":"date-time"}}}}}}}}}}},"/message-analyzer/modify":{"post":{"summary":"EDIFACT-Nachricht modifizieren","description":"Modifiziert eine EDIFACT-Nachricht basierend auf natürlichsprachlicher Anweisung unter Beibehaltung der EDIFACT-Struktur.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["instruction","currentMessage"],"properties":{"instruction":{"type":"string","description":"Änderungsanweisung in natürlicher Sprache","example":"Erhöhe den Verbrauch in jedem Zeitfenster um 10%"},"currentMessage":{"type":"string","description":"Die aktuelle EDIFACT-Nachricht"}}}}}},"responses":{"200":{"description":"Modifizierte Nachricht","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"modifiedMessage":{"type":"string","description":"Die modifizierte EDIFACT-Nachricht"},"isValid":{"type":"boolean","description":"Basis-Validierung der modifizierten Nachricht"},"timestamp":{"type":"string","format":"date-time"}}}}}}}}}}},"/message-analyzer/validate":{"post":{"summary":"EDIFACT-Nachricht validieren","description":"Validiert eine EDIFACT-Nachricht strukturell und semantisch mit detaillierten Fehler- und Warnungslisten.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Die zu validierende EDIFACT-Nachricht"}}}}}},"responses":{"200":{"description":"Validierungsergebnis","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/EdifactValidationResult"}}}}}}}}},"/market-partners/search":{"get":{"summary":"Marktpartner suchen","description":"Suche nach Marktpartnern über BDEW/EIC-Codes. Öffentlicher Endpunkt ohne Authentifizierung.","parameters":[{"name":"q","in":"query","required":false,"description":"Suchbegriff (Code, Firmenname, Stadt, etc.). Optional, sofern Filter wie role gesetzt sind.","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"description":"Maximale Anzahl der Ergebnisse (1-2000). Standard: 50 mit Query, 500 bei reiner Filtersuche.","schema":{"type":"integer","minimum":1,"maximum":2000,"default":50}},{"name":"role","in":"query","required":false,"description":"Filter nach Marktrolle (z.B. \"VNB\" für Verteilnetzbetreiber, \"LF\" für Lieferant, \"MSB\" für Messstellenbetreiber, \"UNB\" für Übertragungsnetzbetreiber)","schema":{"type":"string","enum":["VNB","LF","MSB","UNB","ÜNB","LIEFERANT","VERTEILNETZBETREIBER","MESSSTELLENBETREIBER","ÜBERTRAGUNGSNETZBETREIBER"]},"examples":{"vnb":{"value":"VNB","summary":"Verteilnetzbetreiber"},"lf":{"value":"LF","summary":"Lieferant"},"msb":{"value":"MSB","summary":"Messstellenbetreiber"}}}],"responses":{"200":{"description":"Suchergebnisse","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/MarketPartnerSearchResult"}},"count":{"type":"integer","description":"Anzahl der zurückgegebenen Ergebnisse"},"query":{"type":"string","description":"Verwendete Suchanfrage"},"limit":{"type":"integer","description":"Angewendetes Limit nach Clamping (max. 2000)"}}}}}}}},"400":{"description":"Ungültige Anfrage (fehlender oder leerer Suchbegriff)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}}}},"/structured-data/query":{"post":{"summary":"Strukturierte Datenabfrage (Dual-Mode)","description":"Führt eine Abfrage gegen Data Provider aus. Zwei Modi: (1) Explizite Capability mit Parametern oder (2) Natural Language Query mit automatischer Intent Resolution.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["capability","parameters"],"properties":{"capability":{"type":"string","description":"Explizite Capability ID","enum":["market-partner-search","mastr-installations-query","energy-market-prices","grid-production-data","green-energy-forecast"],"example":"market-partner-search"},"parameters":{"type":"object","description":"Capability-spezifische Parameter","example":{"q":"netz","limit":5}},"options":{"type":"object","properties":{"timeout":{"type":"integer","minimum":1000,"maximum":30000},"bypassCache":{"type":"boolean"}}}}},{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"Natural Language Query","minLength":1,"maxLength":1000,"example":"Wie viele Solaranlagen gibt es in Bayern?"},"options":{"type":"object","properties":{"timeout":{"type":"integer","minimum":1000,"maximum":30000},"bypassCache":{"type":"boolean"}}}}}]},"examples":{"explicitCapability":{"summary":"Explizite Capability","value":{"capability":"market-partner-search","parameters":{"q":"netz","limit":5}}},"naturalLanguage":{"summary":"Natural Language","value":{"query":"Wie viele Solaranlagen gibt es in Bayern?"}}}}}},"responses":{"200":{"description":"Erfolgreiche Abfrage","headers":{"X-Structured-Data-Provider":{"description":"ID des verwendeten Providers","schema":{"type":"string"}},"X-Structured-Data-Intent-Confidence":{"description":"Intent Confidence Score (nur bei NL-Queries)","schema":{"type":"string"}},"X-Cache-Hit":{"description":"Cache-Status","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","description":"Provider-spezifische Daten"},"metadata":{"type":"object","properties":{"providerId":{"type":"string"},"capability":{"type":"string"},"executionTimeMs":{"type":"integer"},"cacheHit":{"type":"boolean"},"dataSource":{"type":"string"},"retrievedAt":{"type":"string","format":"date-time"},"intentResolution":{"type":"object","description":"Nur bei Natural Language Queries","properties":{"originalQuery":{"type":"string"},"resolvedCapability":{"type":"string"},"confidence":{"type":"number"},"reasoning":{"type":"string"},"extractedParameters":{"type":"object"}}}}}}}}}},"400":{"description":"Intent unklar oder ungültige Parameter","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","enum":["INTENT_UNCLEAR","INVALID_REQUEST"]},"message":{"type":"string"},"details":{"type":"object"}}},"availableCapabilities":{"type":"array","items":{"type":"object","properties":{"capability":{"type":"string"},"providerId":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}}}}}}}}}},"404":{"description":"Feature deaktiviert oder kein Provider verfügbar","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","enum":["FEATURE_DISABLED","NO_PROVIDER"]},"message":{"type":"string"}}}}}}}}}}},"/structured-data/resolve-intent":{"post":{"summary":"Intent Resolution (Dry-Run)","description":"Analysiert eine Natural Language Query und zeigt die erkannten Capabilities ohne Ausführung. Nützlich zum Testen der Intent Detection.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":1000,"example":"Wie viele Solaranlagen gibt es in Bayern?"}}}}}},"responses":{"200":{"description":"Intent erfolgreich analysiert","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"originalQuery":{"type":"string"},"detectedCapabilities":{"type":"array","items":{"type":"object","properties":{"capability":{"type":"string"},"confidence":{"type":"number"},"parameters":{"type":"object"}}}},"suggestedCapability":{"type":"string"},"suggestedParameters":{"type":"object"},"confidence":{"type":"number"},"reasoning":{"type":"string"}}},"availableCapabilities":{"type":"array","items":{"type":"object","properties":{"capability":{"type":"string"},"providerId":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}},"keywords":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/structured-data/providers":{"get":{"summary":"Verfügbare Provider auflisten","description":"Listet alle registrierten Data Provider mit ihren Capabilities und Health-Status.","responses":{"200":{"description":"Provider-Liste","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}},"healthy":{"type":"boolean"}}}},"stats":{"type":"object","properties":{"totalProviders":{"type":"integer"},"capabilities":{"type":"array","items":{"type":"string"}}}}}}}}}}}}}},"/structured-data/health":{"get":{"summary":"Health-Status aller Provider","description":"Prüft den Gesundheitsstatus aller registrierten Data Provider.","responses":{"200":{"description":"Alle Provider healthy","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"overall":{"type":"string","enum":["healthy","degraded"]},"providers":{"type":"array","items":{"type":"object","properties":{"providerId":{"type":"string"},"healthy":{"type":"boolean"},"lastCheckAt":{"type":"string","format":"date-time"},"errorMessage":{"type":"string"}}}}}}}}}}},"503":{"description":"Mindestens ein Provider degraded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"data":{"type":"object","properties":{"overall":{"type":"string","enum":["degraded"]},"providers":{"type":"array"}}}}}}}}}}},"/reasoning/generate":{"post":{"summary":"Fortgeschrittenes Reasoning ausführen","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId","query"],"properties":{"sessionId":{"type":"string","format":"uuid"},"query":{"type":"string"},"messages":{"type":"array","items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string"},"content":{"type":"string"}}}},"contextSettingsOverride":{"type":"object"},"preferencesOverride":{"type":"object"},"overridePipeline":{"type":"object"},"useDetailedIntentAnalysis":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Generiertes Reasoning Ergebnis","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"response":{"type":"string"},"reasoningSteps":{"type":"array","items":{"type":"object"}},"finalQuality":{"type":"number"},"iterationsUsed":{"type":"integer"},"contextAnalysis":{"type":"object"},"qaAnalysis":{"type":"object"},"pipelineDecisions":{"type":"object"},"apiCallsUsed":{"type":"integer"},"hybridSearchUsed":{"type":"boolean"},"hybridSearchAlpha":{"type":"number","nullable":true},"metadata":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"usedDetailedIntentAnalysis":{"type":"boolean"},"usedOverridePipeline":{"type":"boolean"},"contextSettings":{"type":"object"},"preferences":{"type":"object"}}}}}}}}}}}}},"/context/resolve":{"post":{"summary":"Arbeitsplatz-Kontext ermitteln","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId","query"],"properties":{"sessionId":{"type":"string","format":"uuid"},"query":{"type":"string"},"messages":{"type":"array","items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string"},"content":{"type":"string"}}}},"contextSettingsOverride":{"type":"object"}}}}}},"responses":{"200":{"description":"Kontext-Entscheidung und Ressourcen","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"contextSettingsUsed":{"type":"object"},"decision":{"type":"object"},"publicContext":{"type":"array","items":{"type":"string"}},"userContext":{"type":"object"}}}}}}}}}}},"/clarification/analyze":{"post":{"summary":"Klarstellungsbedarf für eine Anfrage analysieren","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId","query"],"properties":{"sessionId":{"type":"string","format":"uuid"},"query":{"type":"string"},"includeEnhancedQuery":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Analyse des Klarstellungsbedarfs","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"query":{"type":"string"},"analysis":{"$ref":"#/components/schemas/ClarificationAnalysis"}}}}}}}}}}},"/tools/generate-script":{"post":{"summary":"Job zur deterministischen Skriptgenerierung einreichen","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateToolScriptRequest"}}}},"responses":{"202":{"description":"Job angenommen – Ergebnisse können später abgefragt werden.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/GenerateToolScriptJobResponse"}}}}}}}}},"/tools/generate-script/repair":{"post":{"summary":"Fehlgeschlagenen Skript-Job erneut anstoßen","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateToolScriptRepairRequest"}}}},"responses":{"202":{"description":"Reparatur-Job aufgenommen – neues Ergebnis wird asynchron bereitgestellt.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/GenerateToolScriptRepairResponse"}}}}}}}}},"/tools/run-node-script":{"post":{"summary":"Node.js Skript als Sandbox-Job registrieren","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId","source"],"properties":{"sessionId":{"type":"string","format":"uuid"},"source":{"type":"string","maxLength":4000},"timeoutMs":{"type":"integer","minimum":500,"maximum":60000},"metadata":{"type":"object","description":"Optionale Hinweise für spätere Jobs (z. B. beabsichtigte Artefakte)."}}}}}},"responses":{"202":{"description":"Job aufgenommen (Ausführung benötigt manuelle Freigabe).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"job":{"$ref":"#/components/schemas/ToolJob"}}}}}}}}}}},"/tools/jobs":{"get":{"summary":"Tool-Jobs einer Session auflisten","security":[{"bearerAuth":[]}],"parameters":[{"name":"sessionId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Alle bekannten Jobs der Session","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/ToolJob"}}}}}}}}}}}},"/tools/jobs/{jobId}":{"get":{"summary":"Tool-Job Status abrufen","security":[{"bearerAuth":[]}],"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Aktueller Status des Jobs","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/ToolJob"}}}}}}}}}}},"/artifacts":{"post":{"summary":"Artefakt für eine Session speichern","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId","type","name","mimeType","encoding","content"],"properties":{"sessionId":{"type":"string","format":"uuid"},"type":{"type":"string"},"name":{"type":"string","maxLength":120},"mimeType":{"type":"string"},"encoding":{"type":"string","enum":["utf8","base64"]},"content":{"type":"string"},"description":{"type":"string","maxLength":2000},"version":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"maxItems":12},"metadata":{"type":"object","additionalProperties":true}}}}}},"responses":{"201":{"description":"Artefakt wurde eingelagert","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/CreateArtifactResponse"}}}}}}}}},"/documents/upload":{"post":{"summary":"Dokument hochladen","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Datei (PDF, DOCX, TXT, MD) - max. 50MB"},"title":{"type":"string","description":"Titel des Dokuments (Standard: Dateiname)"},"description":{"type":"string","description":"Optionale Beschreibung"},"tags":{"type":"string","description":"JSON-Array oder Komma-separierte Tags"},"is_ai_context_enabled":{"type":"boolean","description":"Aktiviert KI-Kontext für dieses Dokument"}}}}}},"responses":{"201":{"description":"Dokument erfolgreich hochgeladen","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"document":{"$ref":"#/components/schemas/Document"},"message":{"type":"string"}}}}}}}}}}},"/documents/upload-multiple":{"post":{"summary":"Mehrere Dokumente hochladen (max. 10)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["files"],"properties":{"files":{"type":"array","items":{"type":"string","format":"binary"},"maxItems":10,"description":"Array von Dateien (max. 10)"},"is_ai_context_enabled":{"type":"boolean","description":"Aktiviert KI-Kontext für alle Dokumente"}}}}}},"responses":{"201":{"description":"Dokumente erfolgreich hochgeladen","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"message":{"type":"string"}}}}}}}}}}},"/documents":{"get":{"summary":"Liste aller Dokumente","security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":12}},{"name":"search","in":"query","schema":{"type":"string"},"description":"Suchbegriff für Titel/Beschreibung"},{"name":"processed","in":"query","schema":{"type":"boolean"},"description":"Filter nach Verarbeitungsstatus"}],"responses":{"200":{"description":"Liste der Dokumente","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}}}}}}},"/documents/{id}":{"get":{"summary":"Einzelnes Dokument abrufen","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Dokument-Details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Document"}}}}}}}},"put":{"summary":"Dokument-Metadaten aktualisieren","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"is_ai_context_enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Dokument aktualisiert","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Document"}}}}}}}},"delete":{"summary":"Dokument löschen","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Dokument erfolgreich gelöscht"}}}},"/documents/{id}/download":{"get":{"summary":"Dokument herunterladen","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Datei-Download","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}}}}},"/documents/{id}/reprocess":{"post":{"summary":"Dokument neu verarbeiten","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Verarbeitung gestartet","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}}}},"/documents/{id}/ai-context":{"post":{"summary":"KI-Kontext aktivieren/deaktivieren","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"KI-Kontext-Status aktualisiert","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Document"}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"SessionEnvelopeResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SessionEnvelope"}}},"SessionEnvelope":{"type":"object","required":["sessionId","userId","workspaceContext","policyFlags","preferences","expiresAt"],"properties":{"sessionId":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"legacyChatId":{"type":"string","format":"uuid"},"workspaceContext":{"type":"object"},"policyFlags":{"type":"object","properties":{"role":{"type":"string"},"canAccessCs30":{"type":"boolean"}}},"preferences":{"type":"object","properties":{"companiesOfInterest":{"type":"array","items":{"type":"string"}},"preferredTopics":{"type":"array","items":{"type":"string"}}}},"contextSettings":{"type":"object"},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"SemanticSearchResultItem":{"type":"object","properties":{"id":{"type":"string"},"score":{"type":"number","nullable":true},"payload":{"type":"object"},"highlight":{"type":"string","nullable":true},"metadata":{"type":"object","properties":{"rank":{"type":"integer"},"originalScore":{"type":"number","nullable":true},"mergedScore":{"type":"number","nullable":true},"version":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]}}}}},"ClarificationQuestion":{"type":"object","properties":{"id":{"type":"string"},"question":{"type":"string"},"category":{"type":"string","enum":["scope","context","detail_level","stakeholder","energy_type"]},"options":{"type":"array","items":{"type":"string"},"nullable":true},"priority":{"type":"integer"}}},"ClarificationAnalysis":{"type":"object","properties":{"clarificationNeeded":{"type":"boolean"},"ambiguityScore":{"type":"number"},"detectedTopics":{"type":"array","items":{"type":"string"}},"reasoning":{"type":"string"},"suggestedQuestions":{"type":"array","items":{"$ref":"#/components/schemas/ClarificationQuestion"}},"clarificationSessionId":{"type":"string","nullable":true},"enhancedQuery":{"type":"string","nullable":true}}},"ToolJobSourceInfo":{"type":"object","properties":{"language":{"type":"string","enum":["node"]},"hash":{"type":"string"},"bytes":{"type":"integer"},"preview":{"type":"string"},"lineCount":{"type":"integer"}}},"ToolJobResult":{"type":"object","properties":{"completedAt":{"type":"string","format":"date-time","nullable":true},"durationMs":{"type":"integer","nullable":true},"stdout":{"type":"string","nullable":true},"stderr":{"type":"string","nullable":true},"error":{"type":"string","nullable":true}}},"ToolJobDiagnostics":{"type":"object","properties":{"executionEnabled":{"type":"boolean"},"notes":{"type":"array","items":{"type":"string"}}}},"ToolJob":{"oneOf":[{"$ref":"#/components/schemas/RunNodeScriptJob"},{"$ref":"#/components/schemas/GenerateScriptJob"}]},"RunNodeScriptJob":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["run-node-script"]},"sessionId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"timeoutMs":{"type":"integer"},"metadata":{"type":"object","nullable":true},"source":{"$ref":"#/components/schemas/ToolJobSourceInfo"},"result":{"oneOf":[{"$ref":"#/components/schemas/ToolJobResult"},{"type":"null"}]},"warnings":{"type":"array","items":{"type":"string"}},"diagnostics":{"$ref":"#/components/schemas/ToolJobDiagnostics"}}},"GenerateScriptJobProgress":{"type":"object","properties":{"stage":{"type":"string","enum":["queued","collecting-context","prompting","repairing","validating","testing","completed"]},"message":{"type":"string","nullable":true},"attempt":{"type":"integer","nullable":true}},"required":["stage"]},"GenerateScriptJobError":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string","nullable":true},"details":{"type":"object","nullable":true}},"required":["message"]},"GenerateScriptJob":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["generate-script"]},"sessionId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"progress":{"$ref":"#/components/schemas/GenerateScriptJobProgress"},"attempts":{"type":"integer"},"warnings":{"type":"array","items":{"type":"string"}},"result":{"oneOf":[{"$ref":"#/components/schemas/GenerateToolScriptResponse"},{"type":"null"}]},"error":{"oneOf":[{"$ref":"#/components/schemas/GenerateScriptJobError"},{"type":"null"}]},"continuedFromJobId":{"type":"string","format":"uuid","nullable":true}}},"ToolScriptValidationReport":{"type":"object","properties":{"syntaxValid":{"type":"boolean"},"deterministic":{"type":"boolean"},"forbiddenApis":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}}}},"ToolScriptDescriptor":{"type":"object","required":["code","language","entrypoint","description","runtime","deterministic","dependencies","source","validation","notes"],"properties":{"code":{"type":"string"},"language":{"type":"string","enum":["javascript"]},"entrypoint":{"type":"string","enum":["run"]},"description":{"type":"string"},"runtime":{"type":"string","enum":["node18"]},"deterministic":{"type":"boolean"},"dependencies":{"type":"array","items":{"type":"string"}},"source":{"$ref":"#/components/schemas/ToolJobSourceInfo"},"validation":{"$ref":"#/components/schemas/ToolScriptValidationReport"},"notes":{"type":"array","items":{"type":"string"}}}},"ToolScriptInputSchemaProperty":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"example":{}}},"ToolScriptInputSchema":{"type":"object","properties":{"type":{"type":"string","enum":["object"]},"description":{"type":"string"},"properties":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ToolScriptInputSchemaProperty"}},"required":{"type":"array","items":{"type":"string"}}}},"ToolScriptReference":{"type":"object","required":["snippet"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"snippet":{"type":"string","maxLength":2000},"weight":{"type":"number"},"useForPrompt":{"type":"boolean"}}},"ToolScriptAttachment":{"type":"object","required":["filename","content"],"properties":{"id":{"type":"string"},"filename":{"type":"string","maxLength":160},"content":{"type":"string","description":"UTF-8 Textinhalt des Attachments, z. B. EDIFACT-Datei oder CSV-Ausschnitt.","maxLength":1048576},"mimeType":{"type":"string"},"description":{"type":"string","maxLength":240},"weight":{"type":"number","minimum":1,"maximum":10}}},"ToolScriptTestAssertion":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["contains","equals","regex"]},"value":{"type":"string"}}},"ToolScriptTestCase":{"type":"object","required":["input"],"properties":{"name":{"type":"string","maxLength":120},"description":{"type":"string","maxLength":240},"input":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"assertions":{"type":"array","items":{"$ref":"#/components/schemas/ToolScriptTestAssertion"}}}},"ToolScriptConstraints":{"type":"object","properties":{"deterministic":{"type":"boolean"},"allowNetwork":{"type":"boolean"},"allowFilesystem":{"type":"boolean"},"maxRuntimeMs":{"type":"integer","minimum":500,"maximum":60000}}},"GenerateToolScriptRequest":{"type":"object","required":["sessionId","instructions"],"properties":{"sessionId":{"type":"string","format":"uuid"},"instructions":{"type":"string","maxLength":1600},"inputSchema":{"$ref":"#/components/schemas/ToolScriptInputSchema"},"expectedOutputDescription":{"type":"string","maxLength":1200},"additionalContext":{"type":"string","maxLength":2000},"constraints":{"$ref":"#/components/schemas/ToolScriptConstraints"},"referenceDocuments":{"type":"array","items":{"$ref":"#/components/schemas/ToolScriptReference"}},"testCases":{"type":"array","items":{"$ref":"#/components/schemas/ToolScriptTestCase"}},"attachments":{"type":"array","description":"Textbasierte Dateien (max. 1 MB pro Attachment, 4 MB gesamt), die automatisch in Prompt-Snippets aufgeteilt werden sollen.","items":{"$ref":"#/components/schemas/ToolScriptAttachment"}}}},"GenerateToolScriptRepairRequest":{"type":"object","required":["sessionId","jobId"],"properties":{"sessionId":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"repairInstructions":{"type":"string","maxLength":600},"additionalContext":{"type":"string","maxLength":2000},"referenceDocuments":{"type":"array","items":{"$ref":"#/components/schemas/ToolScriptReference"}},"attachments":{"type":"array","description":"Textbasierte Dateien (max. 1 MB pro Attachment, 4 MB gesamt), die beim Reparaturversuch erneut für den Prompt genutzt werden sollen.","items":{"$ref":"#/components/schemas/ToolScriptAttachment"}},"testCases":{"type":"array","items":{"$ref":"#/components/schemas/ToolScriptTestCase"}}}},"GenerateToolScriptResponse":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"script":{"$ref":"#/components/schemas/ToolScriptDescriptor"},"inputSchema":{"$ref":"#/components/schemas/ToolScriptInputSchema"},"expectedOutputDescription":{"type":"string","nullable":true}}},"GenerateToolScriptJobResponse":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"job":{"$ref":"#/components/schemas/GenerateScriptJob"}}},"GenerateToolScriptRepairResponse":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"job":{"$ref":"#/components/schemas/GenerateScriptJob"}}},"ArtifactStorage":{"type":"object","properties":{"mode":{"type":"string","enum":["inline"]},"encoding":{"type":"string","enum":["utf8","base64"]},"content":{"type":"string"}}},"Artifact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sessionId":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string"},"mimeType":{"type":"string"},"byteSize":{"type":"integer"},"checksum":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"storage":{"$ref":"#/components/schemas/ArtifactStorage"},"preview":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"version":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"metadata":{"type":"object","nullable":true}}},"CreateArtifactResponse":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"artifact":{"$ref":"#/components/schemas/Artifact"}}},"Document":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"original_name":{"type":"string"},"file_path":{"type":"string"},"file_size":{"type":"integer","description":"Dateigröße in Bytes"},"mime_type":{"type":"string"},"is_processed":{"type":"boolean"},"is_ai_context_enabled":{"type":"boolean"},"extracted_text":{"type":"string","nullable":true},"extracted_text_length":{"type":"integer","nullable":true},"processing_error":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"vector_point_id":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"EdifactAnalysisResult":{"type":"object","properties":{"summary":{"type":"string","description":"Zusammenfassung der Analyse"},"plausibilityChecks":{"type":"array","items":{"type":"string"},"description":"Liste der Plausibilitätsprüfungen"},"structuredData":{"type":"object","properties":{"segments":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","description":"Segment-Tag (z.B. UNH, BGM, NAD)"},"elements":{"type":"array","items":{"type":"string"},"description":"Datenelemente des Segments"},"original":{"type":"string","description":"Original-Segment-String"},"description":{"type":"string","description":"Beschreibung des Segments"},"resolvedCodes":{"type":"object","additionalProperties":{"type":"string"},"description":"Aufgelöste BDEW/EIC-Codes"}}}}}},"format":{"type":"string","enum":["EDIFACT","XML","TEXT","UNKNOWN"],"description":"Erkanntes Nachrichtenformat"}}},"EdifactValidationResult":{"type":"object","properties":{"isValid":{"type":"boolean","description":"Ist die Nachricht strukturell gültig?"},"errors":{"type":"array","items":{"type":"string"},"description":"Liste der Validierungsfehler"},"warnings":{"type":"array","items":{"type":"string"},"description":"Liste der Warnungen"},"messageType":{"type":"string","description":"Erkannter Nachrichtentyp (z.B. MSCONS, UTILMD)"},"segmentCount":{"type":"integer","description":"Anzahl der Segmente"}}},"MarketPartnerSearchResult":{"type":"object","properties":{"code":{"type":"string","description":"BDEW- oder EIC-Code"},"companyName":{"type":"string","description":"Firmenname"},"codeType":{"type":"string","description":"Code-Typ (z.B. BDEW, EIC)"},"source":{"type":"string","enum":["bdew","eic"],"description":"Datenquelle"},"validFrom":{"type":"string","format":"date","nullable":true,"description":"Gültig ab Datum"},"validTo":{"type":"string","format":"date","nullable":true,"description":"Gültig bis Datum"},"bdewCodes":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Liste aller BDEW-Codes des Unternehmens"},"contacts":{"type":"array","items":{"type":"object","properties":{"BdewCode":{"type":"string"},"CompanyName":{"type":"string"},"City":{"type":"string"},"PostCode":{"type":"string"},"Street":{"type":"string"},"CodeContact":{"type":"string"},"CodeContactPhone":{"type":"string"},"CodeContactEmail":{"type":"string"}}},"nullable":true,"description":"Kontaktinformationen"},"contactSheetUrl":{"type":"string","nullable":true,"description":"URL zum Kontaktdatenblatt"},"markdown":{"type":"string","nullable":true,"description":"Markdown-formatierte Informationen"},"allSoftwareSystems":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name des Software-Systems"},"confidence":{"type":"string","enum":["High","Medium","Low"],"description":"Konfidenz der Erkennung"},"evidence_text":{"type":"string","description":"Beweis-Text für die Erkennung"}}},"nullable":true,"description":"Erkannte Software-Systeme"}}},"SSEStreamEvent":{"type":"object","description":"Server-Sent Event für Streaming-Responses. Verhindert Cloudflare 504 Timeouts bei langen AI-Anfragen (> 90 Sekunden). Die Verbindung bleibt offen und sendet kontinuierlich Updates.","required":["type"],"properties":{"type":{"type":"string","enum":["status","progress","complete","error"],"description":"Event-Typ: status = allgemeiner Status, progress = Fortschritt mit Prozent, complete = Verarbeitung abgeschlossen, error = Fehler aufgetreten"},"message":{"type":"string","nullable":true,"description":"Statusmeldung (z.B. \"Durchsuche Wissensdatenbank...\", \"Generiere Antwort...\")","examples":["Starte Anfrage...","Durchsuche Wissensdatenbank...","Generiere Antwort...","Fertig!"]},"progress":{"type":"number","minimum":0,"maximum":100,"nullable":true,"description":"Fortschritt in Prozent (0-100)"},"data":{"type":"object","nullable":true,"description":"Payload-Daten (nur bei type=complete)","properties":{"userMessage":{"type":"object","description":"Die gesendete User-Nachricht","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["user"]},"content":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"assistantMessage":{"type":"object","description":"Die generierte AI-Antwort","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["assistant"]},"content":{"type":"string","description":"Die vollständige AI-Antwort"},"metadata":{"type":"object","properties":{"processingTime":{"type":"number","description":"Verarbeitungszeit in Millisekunden"},"modelUsed":{"type":"string","description":"Verwendetes AI-Modell"},"sourcesCount":{"type":"number","description":"Anzahl verwendeter Quellen"}}},"created_at":{"type":"string","format":"date-time"}}}}}}},"CloudflareTimeoutInfo":{"type":"object","description":"Cloudflare Timeout-Verhalten und Lösungsstrategien","properties":{"problem":{"type":"string","description":"Cloudflare unterbricht HTTP-Verbindungen nach ca. 100 Sekunden (nicht konfigurierbar). Backend-Timeout liegt bei 90 Sekunden.","default":"POST /api/v2/chat ist synchron und wartet auf vollständige AI-Antwort → 504 Gateway Timeout bei langen Anfragen"},"solution":{"type":"string","description":"Nutzen Sie den Streaming-Endpoint /api/chat/chats/{chatId}/messages/stream mit Server-Sent Events","default":"SSE hält die Verbindung offen durch kontinuierliche Status-Updates → keine Timeouts, auch bei > 180 Sekunden Verarbeitung"},"benefits":{"type":"array","items":{"type":"string"},"default":["Keine 504 Timeouts mehr","Progressive Status-Updates für bessere UX","Funktioniert bei Anfragen > 3 Minuten","Cloudflare-kompatibel","Real-time Fortschrittsanzeige möglich"]},"migration":{"type":"object","description":"Migration von synchronem zu Streaming-Endpoint","properties":{"old":{"type":"string","default":"POST /api/v2/chat → wartet 90s → 504 Timeout"},"new":{"type":"string","default":"POST /api/chat/chats/{chatId}/messages/stream → SSE → kein Timeout"},"complexity":{"type":"string","default":"Low - siehe Code-Beispiele in der OpenAPI-Dokumentation"}}}}}}}}