diff --git a/docs/workpackages/V1.1 - Neue Arbeitspakete.md b/docs/workpackages/V1.1 - Neue Arbeitspakete.md deleted file mode 100644 index cbd0682..0000000 --- a/docs/workpackages/V1.1 - Neue Arbeitspakete.md +++ /dev/null @@ -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.