Aufräumen
This commit is contained in:
@@ -1,324 +0,0 @@
|
||||
# Arbeitspakete – Erweiterung um native Anthropic Claude-Anbindung
|
||||
|
||||
## Geltungsbereich
|
||||
|
||||
Dieses Dokument beschreibt ausschließlich die Arbeitspakete für die Erweiterung **„Zusätzliche KI-Provider-Familie Anthropic Claude über die native Messages API"**.
|
||||
|
||||
Der Basisstand des Projekts ist vollständig umgesetzt, dokumentiert, getestet und freigegeben. Diese Erweiterung ist eine **bewusst minimale Ergänzung** dieses Basisstands.
|
||||
|
||||
Das einzige Ziel dieser Erweiterung ist:
|
||||
- den bestehenden, OpenAI-kompatiblen KI-Weg unverändert nutzbar zu halten,
|
||||
- zusätzlich die **native Anthropic Messages API** als zweiten, gleichwertig unterstützten KI-Provider anzubinden,
|
||||
- und zwischen beiden Providern über die Konfiguration genau **einen aktiven Provider** auszuwählen.
|
||||
|
||||
Die Arbeitspakete sind so geschnitten, dass:
|
||||
- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann,
|
||||
- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann,
|
||||
- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt.
|
||||
|
||||
Die Reihenfolge der Arbeitspakete ist verbindlich.
|
||||
|
||||
## Schnittregeln für die KI-Bearbeitung
|
||||
|
||||
- Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch Domain, Application, Adapter, Bootstrap, Konfiguration, Dokumentation und Tests ändern.
|
||||
- Keine Annahmen treffen, die nicht durch die verbindlichen Spezifikationen, dieses Dokument oder den tatsächlich vorliegenden Code gedeckt sind.
|
||||
- Änderungen strikt nach dem Prinzip: **so wenig wie möglich, so viel wie nötig**.
|
||||
- Keine allgemeine Provider-Plattform und keine Abstraktion für hypothetische weitere Provider.
|
||||
- Kein Umbau des bestehenden fachlichen Ablaufs ohne direkten Bezug zur Provider-Erweiterung.
|
||||
- Das bestehende fachliche Verhalten des Basisstands bleibt unverändert, soweit dieses Dokument nichts anderes ausdrücklich erweitert.
|
||||
- Jeder positive Zwischenstand muss bereits **vollständig buildbar, testbar und dokumentiert** sein.
|
||||
- Zu jedem Arbeitspaket gehören die unmittelbar betroffenen:
|
||||
- Implementierungen,
|
||||
- Tests (inkl. ggf. Mutationstests in den unmittelbar betroffenen Modulen),
|
||||
- JavaDoc / `package-info`,
|
||||
- Konfigurationsbeispiele,
|
||||
- sowie sonstige Repository-Dokumente mit direktem Bezug.
|
||||
|
||||
## Explizit nicht Bestandteil dieser Erweiterung
|
||||
|
||||
- Provider-Familien jenseits der zwei explizit unterstützten (OpenAI-kompatibel, Anthropic Messages API)
|
||||
- mehrere Konfigurationen je Provider-Familie (Profilverwaltung)
|
||||
- automatische Fallback-Umschaltung zwischen Providern
|
||||
- parallele Nutzung mehrerer Provider in einem Lauf
|
||||
- Änderung des fachlichen Ergebnisvertrags der KI
|
||||
- Änderung der Dateinamensregeln
|
||||
- Änderung der Retry-Regeln
|
||||
- Änderung des Batch-Betriebsmodells
|
||||
- Änderung der bestehenden fachlichen Kernlogik außerhalb der für die Claude-Integration nötigen Anbindung
|
||||
- Persistenz- oder Schemaänderungen ohne zwingenden Bedarf für die Provider-Erweiterung (additive Provider-Identifikator-Spalte ist explizit zwingend, mehr nicht)
|
||||
|
||||
## Verbindliche Regeln für **alle** Arbeitspakete
|
||||
|
||||
### 1. Minimale Erweiterung des Basisstands
|
||||
Die Erweiterung darf den bestehenden fachlichen Ablauf **nicht stillschweigend verändern**.
|
||||
|
||||
Ziel ist ausschließlich:
|
||||
- den bestehenden OpenAI-kompatiblen KI-Weg weiter nutzbar zu halten,
|
||||
- zusätzlich einen nativen Anthropic-Messages-API-Adapter zu integrieren,
|
||||
- und zwischen beiden Wegen über die Konfiguration genau **einen aktiven Provider** auszuwählen.
|
||||
|
||||
### 2. Einheitlicher fachlicher KI-Vertrag
|
||||
Unabhängig vom Provider gilt weiterhin derselbe fachliche Vertrag:
|
||||
- gleicher fachlicher Input
|
||||
- gleicher fachlicher Output (`NamingProposal`)
|
||||
- gleicher Validierungs- und Folgeprozess in der Anwendung
|
||||
- keine provider-spezifische Verzweigung im fachlichen Kern
|
||||
- der bestehende strukturierte Ergebnisvertrag bleibt unverändert; es entsteht **kein** provider-spezifischer Sonderweg
|
||||
|
||||
### 3. Genau ein aktiver Provider
|
||||
Es werden gespeichert:
|
||||
- **genau eine** Konfiguration für die OpenAI-kompatible Provider-Familie
|
||||
- **genau eine** Konfiguration für die Anthropic-Provider-Familie
|
||||
- **genau ein** aktiver Provider
|
||||
|
||||
Es gibt:
|
||||
- keine Profilverwaltung
|
||||
- keine Prioritätenliste
|
||||
- keinen Mehrfach-Fallback
|
||||
- keine automatische Umschaltung bei Fehlern
|
||||
|
||||
### 4. Properties-Datei bleibt führend
|
||||
Die Konfiguration bleibt in der `.properties`-Datei geführt.
|
||||
|
||||
Die Struktur darf weiterentwickelt werden, muss aber:
|
||||
- bestehende Properties-Dateien des Vorgängerstands **weiterhin akzeptieren**,
|
||||
- diese **beim ersten Start** kontrolliert in die neue Struktur überführen,
|
||||
- **vor** der Migration immer eine `.bak`-Sicherung anlegen.
|
||||
|
||||
### 5. Migration bestehender Properties beim ersten Start
|
||||
Wird eine Legacy-Form erkannt, gilt verbindlich:
|
||||
1. Legacy-Form erkennen
|
||||
2. `.bak`-Sicherung anlegen
|
||||
3. Datei in die neue Struktur migrieren (Legacy-Werte → Namensraum `openai-compatible`, `ai.provider.active=openai-compatible`)
|
||||
4. Datei erneut laden und validieren
|
||||
5. Erst danach den normalen Lauf fortsetzen
|
||||
|
||||
Alte und neue Struktur sind **kein** dauerhaft gleichrangiges Endformat.
|
||||
|
||||
### 6. OpenAI-kompatibler Weg bleibt funktional unverändert
|
||||
Der bestehende OpenAI-kompatible Adapter bleibt funktional unverändert nutzbar.
|
||||
|
||||
Daraus folgt:
|
||||
- kein fachlicher Regressionsumbau des bisherigen Provider-Verhaltens
|
||||
- bestehende Konfigurationen müssen nach der Migration weiterhin funktional anschlussfähig sein
|
||||
- die Erweiterung darf den bestehenden Weg nicht beschädigen
|
||||
|
||||
### 7. Claude wird über die native Messages API angebunden
|
||||
Anthropic Claude wird über einen **eigenen nativen Adapter** im Adapter-Out-Modul angebunden.
|
||||
|
||||
Daraus folgt:
|
||||
- Endpunkt, Authentifizierungsschema, Request- und Response-Format der Anthropic Messages API leben **ausschließlich** im Adapter
|
||||
- Domain und Application bleiben provider-neutral
|
||||
- die provider-spezifische Request-/Response-Abbildung darf den fachlichen Vertrag nicht verändern
|
||||
- Adapter dürfen nicht voneinander abhängen; es gibt keine gemeinsame Zwischenschicht
|
||||
|
||||
### 8. Provider-Auswahl ist strikt und ohne Fallback
|
||||
Der aktive Provider wird ausschließlich aus der Konfiguration bestimmt.
|
||||
|
||||
Daraus folgt:
|
||||
- nur der aktive Provider wird verwendet
|
||||
- der inaktive Provider wird in keiner Fehlersituation als Backup verwendet
|
||||
- Fehler des aktiven Providers bleiben Fehler dieses einen Pfads und folgen der bestehenden Retry- und Fehlersemantik
|
||||
|
||||
### 9. Keine Zusatzänderungen ohne direkten Provider-Bezug
|
||||
Es werden nur solche Änderungen eingeführt, die für die zusätzliche Claude-Integration und die dafür nötige Provider-Auswahl tatsächlich erforderlich sind.
|
||||
|
||||
Daraus folgt:
|
||||
- keine zusätzlichen Komfortfunktionen
|
||||
- keine allgemeine Provider-Plattform
|
||||
- keine Änderungen an Persistenz oder Nachvollziehbarkeit, sofern sie für diese Erweiterung nicht zwingend erforderlich sind (additive Provider-Identifikator-Spalte ist die einzige zwingende Persistenzänderung)
|
||||
|
||||
### 10. Architekturtreue
|
||||
Es gilt unverändert:
|
||||
- strikte hexagonale Architektur
|
||||
- Abhängigkeiten zeigen nach innen
|
||||
- keine Infrastrukturtypen in Domain oder Application
|
||||
- keine direkte Adapter-zu-Adapter-Kopplung
|
||||
- keine Vermischung von Provider-spezifischer HTTP-Kommunikation mit fachlicher Entscheidungslogik
|
||||
- der `AiNamingPort` bleibt provider-neutral
|
||||
|
||||
---
|
||||
|
||||
## AP-001 – Konfigurations-Schema, Migration mit `.bak` und Startvalidierung
|
||||
|
||||
### Voraussetzung
|
||||
Keine. Dieses Arbeitspaket ist der Startpunkt der Erweiterung.
|
||||
|
||||
### Ziel
|
||||
Die Konfiguration wird mit minimalem Eingriff so erweitert, dass zwischen den unterstützten Provider-Familien gewählt werden kann, und bestehende Properties-Dateien aus dem Vorgängerstand werden beim ersten Start automatisch sicher in das neue Schema überführt.
|
||||
|
||||
### Muss umgesetzt werden
|
||||
- Properties-Schema minimal so erweitern, dass folgende Informationen konfigurierbar sind:
|
||||
- aktiver Provider (`ai.provider.active`),
|
||||
- Konfigurations-Namensraum für die OpenAI-kompatible Provider-Familie,
|
||||
- Konfigurations-Namensraum für die Claude-Provider-Familie.
|
||||
- Legacy-Form (flache `api.*`-Schlüssel) eindeutig erkennen.
|
||||
- Vor jeder Migration automatisch eine **`.bak`-Sicherung** anlegen.
|
||||
- Migration als **In-Place-Update** umsetzen:
|
||||
- Legacy lesen,
|
||||
- in neues Schema überführen,
|
||||
- in-place schreiben,
|
||||
- neu laden,
|
||||
- validieren.
|
||||
- Legacy-Werte korrekt in den Namensraum `openai-compatible` überführen und `ai.provider.active=openai-compatible` setzen.
|
||||
- Startvalidierung gezielt erweitern, insbesondere für:
|
||||
- genau ein gesetzter, unterstützter aktiver Provider,
|
||||
- nur die für den aktiven Provider nötigen Pflichtwerte,
|
||||
- technisch konsistente Provider-Konfiguration (Modellname, Timeout, ggf. Basis-URL),
|
||||
- API-Schlüssel des aktiven Providers (Umgebungsvariable hat Vorrang vor Properties).
|
||||
- Konfigurationsbeispiele, JavaDoc und unmittelbar betroffene Repository-Dokumente anpassen.
|
||||
- Tests ergänzen für:
|
||||
- erfolgreiche Migration einer realistischen Legacy-Datei,
|
||||
- `.bak`-Erzeugung,
|
||||
- korrekte Übernahme der Legacy-Werte in den `openai-compatible`-Namensraum,
|
||||
- Abweisung ungültiger oder fehlender `ai.provider.active`,
|
||||
- Abweisung unvollständiger Pflichtwerte für den aktiven Provider,
|
||||
- Vorrang der Umgebungsvariablen vor dem Properties-Schlüssel des aktiven Providers.
|
||||
|
||||
### Explizit nicht Teil
|
||||
- nativer Claude-Adapter
|
||||
- Bootstrap-Auswahl des aktiven Providers (folgt in AP-002)
|
||||
- Refactoring des bestehenden OpenAI-kompatiblen Adapters über das für das neue Schema nötige Maß hinaus
|
||||
- Persistenz- oder Schemaänderungen
|
||||
- fachliche Änderungen am KI-Ergebnisvertrag
|
||||
|
||||
### Fertig wenn
|
||||
- das erweiterte Properties-Schema technisch nutzbar ist,
|
||||
- Legacy-Dateien beim ersten Start sicher mit `.bak` migriert werden,
|
||||
- ungültige Provider-Konfigurationen sauber abgewiesen werden,
|
||||
- der Build weiterhin fehlerfrei ist und alle bestehenden Tests grün bleiben.
|
||||
|
||||
---
|
||||
|
||||
## AP-002 – Bestehenden OpenAI-kompatiblen Pfad an die Provider-Auswahl anbinden
|
||||
|
||||
### Voraussetzung
|
||||
AP-001 ist abgeschlossen.
|
||||
|
||||
### Ziel
|
||||
Der bestehende OpenAI-kompatible KI-Weg wird mit minimalem Umbau so eingebettet, dass das Bootstrap-Modul den aktiven Provider aus der Konfiguration auswählen und verdrahten kann, ohne den bisherigen fachlichen Ablauf zu verändern.
|
||||
|
||||
### Muss umgesetzt werden
|
||||
- Im Bootstrap-Modul eine **Provider-Auswahl** einführen, die anhand von `ai.provider.active` genau eine `AiNamingPort`-Implementierung als aktive Implementierung verdrahtet.
|
||||
- Den bestehenden OpenAI-kompatiblen Adapter so anbinden, dass er die Werte aus dem Namensraum `ai.provider.openai-compatible.*` konsumiert.
|
||||
- Den bisherigen OpenAI-kompatiblen Weg dabei funktional unverändert erhalten.
|
||||
- Application und Domain weiterhin frei von provider-spezifischen HTTP-/JSON-Typen halten.
|
||||
- Provider-spezifische Request-/Response-Abbildung und Fehlerbehandlung weiterhin klar im Adapter-Out kapseln.
|
||||
- Sicherstellen, dass ein zukünftiger zweiter Provider nur durch eine zusätzliche Implementierung im Adapter-Out und einen zusätzlichen Eintrag in der Provider-Auswahl angebunden wird – ohne neue Zwischenschicht und ohne Adapter-zu-Adapter-Kopplung.
|
||||
- Den Provider-Identifikator des aktiven Providers in die Versuchshistorie einfließen lassen (additive Schema-Erweiterung mit definiertem Default für historische Versuche).
|
||||
- Logging-Mindestumfang um den **aktiven Provider beim Laufstart** ergänzen.
|
||||
- Relevante JavaDoc- und Repository-Dokumentation mitziehen.
|
||||
- Tests gezielt anpassen oder ergänzen, um nachzuweisen:
|
||||
- der bisherige OpenAI-kompatible Pfad bleibt funktional intakt,
|
||||
- die Provider-Auswahl ist technisch sauber angebunden,
|
||||
- eine ungültige Provider-Auswahl scheitert in der Startvalidierung,
|
||||
- der Provider-Identifikator landet pro Versuch korrekt in der Persistenz,
|
||||
- der fachliche Ergebnisvertrag bleibt unverändert,
|
||||
- bestehende Datenbestände bleiben lesbar und korrekt interpretierbar.
|
||||
|
||||
### Explizit nicht Teil
|
||||
- nativer Claude-Adapter
|
||||
- Fallback-Logik
|
||||
- zusätzliche Provider-Familien
|
||||
- Persistenz- oder Schemaänderungen jenseits der additiven Provider-Identifikator-Spalte
|
||||
- globale Abschlussprüfung
|
||||
|
||||
### Fertig wenn
|
||||
- der OpenAI-kompatible Weg über die neue Provider-Auswahl sauber nutzbar bleibt,
|
||||
- sein fachliches Verhalten gegenüber dem Vorgängerstand unverändert ist,
|
||||
- keine Provider-Implementierungsdetails in den fachlichen Kern durchsickern,
|
||||
- der Provider-Identifikator persistent erfasst wird,
|
||||
- bestehende Datenbestände unverändert nutzbar bleiben,
|
||||
- der Build weiterhin fehlerfrei ist.
|
||||
|
||||
---
|
||||
|
||||
## AP-003 – Nativen Anthropic-Messages-API-Adapter implementieren und verdrahten
|
||||
|
||||
### Voraussetzung
|
||||
AP-001 und AP-002 sind abgeschlossen.
|
||||
|
||||
### Ziel
|
||||
Ein nativer Adapter für die Anthropic Messages API ist technisch nutzbar, wird über die Provider-Auswahl als aktiver Provider verdrahtet und liefert fachlich denselben Ergebnisvertrag wie der bestehende OpenAI-kompatible Weg.
|
||||
|
||||
### Muss umgesetzt werden
|
||||
- Im Adapter-Out-Modul eine zweite `AiNamingPort`-Implementierung anlegen, die die **native Anthropic Messages API** anspricht.
|
||||
- Die Claude-spezifische Konfiguration aus dem Namensraum `ai.provider.claude.*` technisch anbinden, mindestens:
|
||||
- Modellname,
|
||||
- API-Schlüssel (Umgebungsvariable hat Vorrang),
|
||||
- Timeout,
|
||||
- Basis-URL als optionaler Konfigurationswert mit fachlich neutralem Default.
|
||||
- Provider-spezifische Request-Erzeugung und Response-Verarbeitung so umsetzen, dass das fachliche JSON-Ergebnis (`date`, `title`, `reasoning`) wie beim bestehenden Weg in den vorhandenen Domain-Typ `NamingProposal` abgebildet wird.
|
||||
- Technische Fehlerfälle des Claude-Pfads (HTTP-Fehler, Timeouts, ungültige Antwortstrukturen, Authentifizierungsfehler) **im Adapter** klassifizieren und auf die bestehende technische Fehlersemantik des Projekts abbilden. Es entstehen keine neuen Fehlerklassen.
|
||||
- Sicherstellen, dass Claude **keinen** Sonderweg im fachlichen Kern erzwingt und keine Application-/Domain-Klasse provider-spezifisch wird.
|
||||
- Die Provider-Auswahl im Bootstrap-Modul um die neue Implementierung erweitern. Das geschieht ausschließlich in der bereits in AP-002 angelegten Auswahlstelle, ohne neue Zwischenschicht.
|
||||
- Adapter-zu-Adapter-Kopplung aktiv vermeiden: keine gemeinsame Basisklasse, kein gemeinsamer Hilfsadapter zwischen Port und konkreten Adaptern.
|
||||
- Konfigurationsbeispiele, JavaDoc und unmittelbar betroffene Repository-Dokumente mitziehen.
|
||||
- Tests ergänzen für:
|
||||
- korrekte Request-Erzeugung gegen die Anthropic Messages API (Adapter-Test mit gemocktem HTTP-Layer),
|
||||
- korrekte Response-Abbildung auf den bestehenden fachlichen Vertrag,
|
||||
- technische Claude-Fehlerfälle (HTTP-Fehler, Timeout, Auth-Fehler, defekte Antwortstruktur) und deren Klassifikation,
|
||||
- Auswahl und Nutzung von Claude als aktivem Provider über die Konfiguration,
|
||||
- keine fachliche Sonderbehandlung gegenüber dem OpenAI-kompatiblen Pfad,
|
||||
- korrekter Provider-Identifikator in der Versuchshistorie für Claude-Läufe.
|
||||
|
||||
### Explizit nicht Teil
|
||||
- automatische Fallback-Logik
|
||||
- weitere Provider-Familien
|
||||
- Persistenz- oder Schemaänderungen jenseits der bereits in AP-002 eingeführten additiven Provider-Identifikator-Spalte
|
||||
- neue Fachfunktionalität außerhalb der Provider-Erweiterung
|
||||
- globale Abschlussprüfung
|
||||
|
||||
### Fertig wenn
|
||||
- der native Anthropic-Messages-API-Adapter technisch nutzbar ist,
|
||||
- Claude über die Konfiguration als aktiver Provider auswählbar ist,
|
||||
- sein Ergebnis fachlich auf denselben Vertrag wie der bestehende Provider abgebildet wird,
|
||||
- provider-spezifische Details ausschließlich im Adapter-Out leben,
|
||||
- der bestehende OpenAI-kompatible Pfad weiterhin unverändert nutzbar ist,
|
||||
- der Build weiterhin fehlerfrei ist.
|
||||
|
||||
---
|
||||
|
||||
## AP-004 – Regressionsschutz, Dokumentationskonsolidierung und Abschlussnachweis
|
||||
|
||||
### Voraussetzung
|
||||
AP-001 bis AP-003 sind abgeschlossen.
|
||||
|
||||
### Ziel
|
||||
Der vollständige Erweiterungsstand wird automatisiert abgesichert, dokumentarisch konsolidiert und als minimale Erweiterung des freigegebenen Basisstands belastbar nachgewiesen.
|
||||
|
||||
### Muss umgesetzt werden
|
||||
- Den vollständigen Erweiterungsstand gegen die in diesem Dokument definierten Regeln prüfen.
|
||||
- Tests vervollständigen bzw. konsolidieren, insbesondere für:
|
||||
- erfolgreiche Migration einer realistischen Legacy-Properties-Datei,
|
||||
- `.bak`-Erzeugung,
|
||||
- OpenAI-kompatibler Provider weiterhin nutzbar (Regression),
|
||||
- nativer Anthropic-Provider nutzbar,
|
||||
- genau ein aktiver Provider, ohne Fallback-Umschaltung,
|
||||
- einheitlicher fachlicher Ergebnisvertrag über beide Provider hinweg,
|
||||
- Provider-Identifikator in der Versuchshistorie korrekt gesetzt,
|
||||
- Logging des aktiven Providers beim Laufstart vorhanden,
|
||||
- Sensibilitätsregel für KI-Inhalte gilt provider-unabhängig,
|
||||
- bestehende Datenbestände bleiben lesbar und korrekt interpretierbar.
|
||||
- Vorhandene PIT-/Mutationstest-Konfiguration auf die neuen oder geänderten Klassen ausdehnen, soweit für den Stand sinnvoll.
|
||||
- Smoke-Tests so erweitern, dass für **beide** Provider-Konfigurationen der Bootstrap-Pfad bis zur erfolgreichen Verdrahtung des `AiNamingPort` durchläuft (ohne realen externen Aufruf).
|
||||
- Konfigurationsbeispiele, Startdokumentation und sonstige Repository-Dokumente konsolidieren, sodass die Erweiterung ohne implizite Annahmen verständlich bleibt.
|
||||
- Einen knappen, im Repository verbleibenden Abschlussnachweis ergänzen, der mindestens festhält:
|
||||
- welche Prüfungen tatsächlich ausgeführt wurden,
|
||||
- dass die Erweiterung minimal-invasiv umgesetzt wurde,
|
||||
- dass beide Provider-Familien unterstützt werden,
|
||||
- dass die Konfigurationsmigration und `.bak`-Sicherung nachgewiesen sind,
|
||||
- dass keine Architekturbrüche eingeführt wurden.
|
||||
- Den relevanten Build-/Test-Umfang tatsächlich ausführen.
|
||||
|
||||
### Explizit nicht Teil
|
||||
- weitere Provider-Familien
|
||||
- zusätzliche Konfigurationsprofile
|
||||
- neue Komfort- oder Bedienfunktionen
|
||||
- weitergehende Architekturumbauten ohne direkten Bezug zur Erweiterung
|
||||
|
||||
### Fertig wenn
|
||||
- der vollständige Erweiterungsstand automatisiert abgesichert ist,
|
||||
- die Dokumentation konsistent zum realen Verhalten passt,
|
||||
- die Minimalinvasivität gegenüber dem Basisstand belastbar nachgewiesen ist,
|
||||
- ein fehlerfreier, übergabefähiger Stand vorliegt.
|
||||
Reference in New Issue
Block a user