werkrevisor/docs/konzept-jev-classifier.md

Konzept: Classifier Jev und LLM-Review kombinieren

Stand: 2026-10-05, Entwurf aus der Diskussion nach dem Versuch auf git.javagil.de.

Stand der Umsetzung

Stufe 1 ist in werkrevisor 0.5.0 umgesetzt: Jev bewertet die Abschnitte und Gherkin-Szenarien der PR-Dokumente.

• [engine] mode wählt llm (wie bisher, Standard), classifier oder combined.
• Jede Frage fragt nach einem Problem; ein hoher Wert bedeutet immer „schlecht“. Ein Score läuft von „kein Problem“ bis „schlimmstes Problem“; sein Wert ist die erwartete Stufe geteilt durch die höchste Stufe. Eine Auswahl nennt ihre schlechten Optionen in problem_options; ihr Wert ist deren Wahrscheinlichkeit.
• Statt max_state_tokens begrenzt max_state_chars die Einheit; eine zu große Einheit geht nicht an Jev und ergibt YELLOW. max_units begrenzt die Zahl der Aufrufe je Review.
• Ein Ja/Nein hat keine Konfidenz; min_confidence gilt nur für Auswahl und Score.
• Im Modus combined bekommt das LLM die markierten Einheiten als Liste nach den vollständigen Dateien im User-Prompt: Datei, Zeile, Szenario-Nummer, Frage und Wert, aber kein Text aus dem PR.
• tools/jev-eval misst die Fragen offline an vorhandenen PR-Dokumenten, ohne Gitea.

Die Schwellwerte und Fragen in config/hsadmin-ng.toml sind ein erster Vorschlag; sie werden vor dem Einsatz mit tools/jev-eval an der Historie von hsadmin-ng geprüft. Stufe 2 (Risiko je Datei) und Stufe 3 (Build-Laufzeit) sind offen.

Ausgangslage

Der heutige Review ist ein einzelner LLM-Aufruf über PR-Agent und OpenRouter. Er liefert Befunde mit Problem, Auswirkung und Fundstelle, ist aber für jede Einzelfrage teuer und langsam.

Jev von TypeSafe ist ein „System One“-Modell, also ein Classifier. Jev erzeugt keinen Text, sondern beantwortet getypte Fragen mit kalibrierten Wahrscheinlichkeiten:

• Fragetypen: Ja/Nein (noul), Auswahl (choice, bis 255 Optionen), Score (score, 2–10 Stufen);
• Eingabe („state“) bis etwa 32.000 Tokens, state und Fragen zusammen bis etwa 64.000 Tokens;
• Antwortzeit etwa 100 ms;
• Preis 0,042 USD pro 1 Mio. Input-Tokens, Output kostenlos;
• keine Begründung, keine Fundstelle, kein verlässliches Rechnen oder Vergleichen von Zahlen.

Quelle: flaviocopes.com/jev, LiteLLM-Doku.

Anbindung

Jev ist über OpenRouter nicht als Classifier verfügbar. Dort gibt es nur typesafe/jev-router; der wählt für Chat-Anfragen ein passendes LLM aus. litellm und damit PR-Agent kennen Jev nur als Pass-Through im Proxy-Betrieb.

werkrevisor spricht Jev deshalb direkt an: POST https://api.typesafe.ai/v1/systemone mit model: "jev-latest". Dazu kommt ein kleiner Client nur mit der Standardbibliothek, mit denselben Regeln wie der Gitea-Client (TLS, keine Weiterleitungen). Neues Secret auf dem Host: TYPESAFE_API_KEY in werkdock.env bzw. docker.env. Werkator und die Gitea-Seite bleiben unverändert.

Offen: TypeSafe hat neue Registrierungen pausiert; alternativ ist Jev über das Vercel AI Gateway erreichbar.

Ablauf in vier Stufen

1. Aufbereiten

Ohne Modell und deterministisch wird der PR in Einheiten zerlegt:

• je geänderte Datei: Diff plus vollständige neue Fassung; passt sie nicht in das Limit von Jev, nur ein Ausschnitt um die Änderungen, und die Einheit gilt als unvollständig;
• das PR-Dokument nach Abschnitten (Markdown-Überschriften);
• jedes Gherkin-Szenario einzeln.

Ein LLM zum Aufbereiten ist vorerst nicht nötig, höchstens für Zusammenfassungen sehr großer Dateien.

2. Viele Jev-Aufrufe parallel

Einheit	Fragen
je Datei	Risiko (Score 1–5); ändert sich Verhalten (Ja/Nein); werden Tests abgeschwächt (Ja/Nein); sicherheitsrelevant (Ja/Nein)
je Abschnitt des PR-Dokuments	verständlich für Menschen (Score); Slop-Faktor: Füllwörter, gestelzte Prosa, Erzählung statt Begründung (Score); hält die Schreibregeln ein (Ja/Nein)
je Gherkin-Szenario	gut lesbar (Score); genau ein Aspekt (Ja/Nein); frei von Implementierungsdetails (Ja/Nein); Given/When/Then sauber (Ja/Nein)

Die Schreibregeln (z. B. aus AGENTS.md) gehen verdichtet in die Anweisungen der Fragen. Die Fragen, Optionen und Schwellwerte stehen in der Betreiber-Konfiguration, nie im PR.

Risiko je Änderung auf Dateiebene

Das Risiko hängt an der Art der Änderung, nicht an ihrer Größe. Jev ordnet jede geänderte Datei einer Änderungsklasse zu (choice), mit Wahrscheinlichkeit und Konfidenz:

Änderungsklasse	Risiko
nur Imports oder Paketnamen geändert, z. B. weil eine Klasse verschoben wurde	gering
Datei umbenannt oder verschoben, Inhalt unverändert	gering
neue Testmethoden oder neue Assertions	gering
Assertions oder Testmethoden gelöscht oder abgeschwächt, Tests deaktiviert	hoch
Verhalten im Produktivcode geändert	je nach Inhalt (Score)

Ein Paket-Umzug, der Imports in 200 Dateien ändert, ist damit fast risikofrei: Ein falscher Import fällt bei der guten Testabdeckung in der verpflichtenden CI auf. Die geringe Einstufung gilt deshalb nur zusammen mit einer grünen CI.

Mechanische Änderungen lassen sich oft auch deterministisch erkennen, z. B. wenn ein Datei-Diff nur import- und package-Zeilen enthält. Diese Erkennung ist sicher und kostet nichts; Jev entscheidet nur die Fälle, die sie nicht eindeutig zuordnet. Als mechanisch erkannte Dateien gehen nicht in den LLM-Review und belasten dessen Token-Budget nicht. So wird ein großer, aber mechanischer PR nicht mehr allein wegen seiner Größe YELLOW.

3. Zusammenführen

• Ein schlecht lesbares Gherkin-Szenario oder ein PR-Dokument mit hohem Slop-Faktor ergibt früh RED, bevor ein Mensch Zeit investiert. Für hsadmin-ng ist das besonders wichtig, weil die Gherkin-Szenarien dort eine von Menschen freigegebene Spezifikation sind.
• Hohe Risiko-Scores, unsichere Antworten (niedrige Konfidenz) oder unvollständige Einheiten ergeben YELLOW.
• Sind alle Einheiten unauffällig, ist der PR ein Kandidat für GREEN.
• Die festen Regeln (Kategorien, riskante Pfade, Secret-Scan) gelten unverändert und gehen vor.

4. Gezielter LLM-Review

Das LLM bekommt die Jev-Ergebnisse als Hinweise, z. B. „Datei X Risiko 4, Szenario 3 nicht lesbar“. Es prüft vor allem die markierten Stellen und schreibt die Befunde mit Problem, Auswirkung und Fundstelle. Ein RED aus Jev allein bleibt ohne Befund nur dann RED, wenn es eine Spezifikationsfrage betrifft (Gherkin, PR-Dokument); sonst wird es YELLOW mit dem Hinweis „Classifier sieht Änderungsbedarf“.

Der Kommentar zeigt zusätzlich eine kleine Tabelle mit den Jev-Werten je Datei, Abschnitt und Szenario.

Konfiguration

[engine]
# "llm" ist der heutige Review, "classifier" nur Jev, "combined" die vier Stufen.
mode = "combined"

[classifier]
endpoint = "https://api.typesafe.ai/v1/systemone"
model = "jev-latest"
input_price_usd_per_mtok = 0.042
max_state_chars = 60000
max_units = 80
timeout_seconds = 20
pr_doc_globs = ["doc/PR/*.md"]
min_confidence = 0.3
# Dazu die Fragen in [[classifier.scenario_questions]] und [[classifier.section_questions]], siehe config/hsadmin-ng.toml.

Gewechselt wird wie bisher über WERKREVISOR_CONFIG_TOML auf dem Host, ohne neues Image.

Build-Laufzeit als Kriterium

Ein PR, der nur Tests hinzufügt, ist an sich risikofrei; er kann aber die Build-Laufzeit stark erhöhen. Das gehört nicht zu Jev, weil Jev Zahlen schlecht vergleicht; es wird deterministisch geprüft.

• Werkator kennt die Build-Dauer je Definition mit Median (BuildDurationTrends).
• Den Test-Anteil getrennt vom PIT-Anteil liefert der --profile-Bericht von hsadmin-ng; ein unzureichender PIT-Cache darf nicht als langsamer Test zählen.
• Dafür muss der Review das Ende der CI des gleichen Heads abwarten und die Zahlen von Werkator bekommen. Das ist eine eigene, spätere Ausbaustufe mit einer Werkator-Erweiterung.

Vorbehalte

• Wie gut Jev Code-Risiko, Slop und Lesbarkeit bewertet, ist unbekannt. Vor dem Einsatz wird Jev offline an der Historie von hsadmin-ng gemessen: bekannte gute und schlechte Szenarien und PR-Dokumente.
• Ohne Enterprise-Vertrag garantiert TypeSafe keine Löschung der Anfragen, trainiert aber nicht darauf. Für öffentlich gespiegelten Code ist das vermutlich unkritisch; die Entscheidung trifft der Betreiber.

Reihenfolge

1. Jev für Gherkin-Szenarien und PR-Dokument: größter Nutzen, RED vor dem menschlichen Review.
2. Risiko je Datei als Vorfilter und Hinweisgeber für den LLM-Review.
3. Build-Laufzeit über Werkator.

Voraussetzung für 1 und 2 ist ein Jev-Zugang.