162 lines
9.1 KiB
Markdown
162 lines
9.1 KiB
Markdown
# 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](https://flaviocopes.com/jev/), [LiteLLM-Doku](https://docs.litellm.ai/docs/pass_through/typesafe).
|
||
|
||
## 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
|
||
|
||
```toml
|
||
[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.
|