pv-agent/.agents/MEMORY.md

# Agent-Memory — pv-agent

Rollender Übergabe-Log für agent-Threads. Workflow: `.agents/SKILL.md`
(agent-memory-Skill). Ergänzen, nicht überschreiben.

## Current focus

M1, M2 und **M3 (Bake-off) sind abgeschlossen** — `qwen3.8:27b` ist als
Antwortmodell fixiert (D7). Offen: Fehlverweigerungs-Tuning (q-008,
q-031 — beide Finalisten betreffend) und Odoo-Integration (M4, separat
zu planen).

## Completed (2026-09-14)

- **Planung** (`planung.md`): Architektur, Grounding-Regeln, Modellfeld,
  Meilensteine M1–M4; **Skill** `.agents/skills/pv-rag-agent/SKILL.md`.
- **Commits**: `25eb285` (Wissensbasis-Import), `bf8191b` (Planung +
  Skills), `2cba72a` (M1+M2-Implementierung, 41 Tests).
- **Implementierung M1+M2** (`agent/`): kb/ingest/retrieve/generate/
  ollama_client/api/cli/eval, Goldset 31 Fragen, Test-Chat.
- **Ollama-Anbindung verifiziert** (Ziel-Instanz `http://100.103.83.12:11435`,
  Ollama 0.32.13): `bge-m3` per API gepullt; `qwen3.8:27b` war bereits
  installiert. Hybrid-Index: 3.005 Chunks, alle eingebettet (144 s).
- **M1-Akzeptanz erreicht**: Retrieval Hybrid Hit-Rate 0,968 ·
  Recall@8 **0,952** (>0,9 ✓) · MRR 0,690 (BM25-only: 0,871/0,855/0,476).
- **M2-Antwortmodus-Eval** (qwen3.8:27b, Thinking aus): Zitier-Präzision
  **100 %** (4 Regenerierungen, alle geheilt) · Verweigerung korrekt
  94,3 % · erwartete Quelle zitiert 80,6 % · Latenz mean 32 s / p95 53 s.
  Report: `data/eval-qwen38.json`.
- Der ATZ-Konfliktfall (28,5 vs. 27,5 %) wird korrekt mit ⚠ und beiden
  IDs beantwortet; harte Verweigerung (UStVA, Retrieval nicht leer)
  funktioniert.
- **Topologie geklärt**: `100.103.83.12` ist die **Remote-GPU-Maschine**
  (Entwicklungsumgebung, R9700, Tailscale); die Dev-Maschine selbst hat
  einen eigenen, fast leeren Ollama auf localhost:11434 (dorthin ging der
  erste bge-m3-Pull — auf die GPU-Maschine neu gepullt). Ziel-Instanz ist
  ausschließlich `http://100.103.83.12:11435`.
- **Bake-off M3 — abgeschlossen (D7)**: alle 5 Kandidaten gemessen
  (Tabelle in `planung.md` Abschnitt 13). **`qwen3.8:27b` gewinnt**
  (100 % Zitier-Präzision, 94,3 % Verweigerung korrekt, 80,6 % erwartete
  Quelle, 32 s mean). `gemma4:26b` = dokumentierter Latenz-Kandidat
  (7,9 s mean, 100 % Zitier-Präzision, aber 67,7 % Quellentreue, 3
  Fehlverweigerungen). mistral-small3.1: 71,4 % Verweigerungskorrektheit
  — Deutsch-Hypothese praktisch widerlegt. qwen3.6:27B: 2 dauerhafte
  Zitierverletzungen, 10 Regenerierungen. gemma4:12B: 2 Verletzungen.
  Reports: `data/eval-*.json`. q-008/q-031 verweigern beide Finalisten —
  Prompt-/Retrieval-Tuning (nicht modellspezifisch).
- **Remote-GPU-Maschine**: nach `systemctl restart ollama` (User-Aktion)
  liefen alle Läufe stabil; zwischen Kandidaten wurde per `keep_alive: 0`
  entladen (Crash-Ursache war der Modell-Swap-Stress beim gemma4-Lauf).

## Open issues / blockers

- **Push**: Remote localhost:3003 aus der Sandbox nicht erreichbar — User
  pusht vom Host.
- **Fehlverweigerungen**: q-008 (Abfertigung/Verfügungsmöglichkeiten),
  q-031 (Mindestlohngesetz) — breite Fragen, Retrieval erfolgreich, Modell
  verweigert. M3-Tuning: Regel-4-Formulierung lockern („behandle den
  behandelten Teil“) oder Kontextblöcke erhöhen. Vorher Prompt einfrieren
  für den Bake-off-Vergleich.
- **Latenz**: mean 32 s/ Antwort ist hoch (Dense 27B + große Prompts).
  Hebel: weniger Kontextblöcke (aktuell 8+6), schnellere Kandidaten.
- **Cloud-Modelle** (`*:cloud` auf der Ollama-Instanz) sind für Antworten
  tabu (Anforderung: lokal). Nicht versehentlich konfigurieren.
- **Bake-off M3 — erledigt** (siehe Completed; Entscheidung D7 in
  `planung.md`). Nach Tuning von Prompt/Retrieval: erneuter kurzer
  Bestätigungslauf nur mit dem Sieger.
- **M4 Odoo**: native LLM-Module des konkreten Odoo-19-Stands verifizieren
  (keine API-Annahmen); Option A (dünnes Custom-Modul + Service-API) ist
  Default.

## Decisions & conventions

- **D1 (Planung):** Schlanke Eigen-Pipeline statt LangChain/LlamaIndex —
  Grounding-Kontrolle schlägt Framework-Komfort bei 601 Dokumenten.
- **D2:** Retrieval-Korpus ist **nur Layer 2**; Layer 1 bleibt aus Prompts
  (Lizenz); Antworten zitieren `[kb-id]` + `(Stand YYYY-MM)`.
- **D3:** Umlaut-Folding für FTS (NFKD, ß→ss) — gilt konsistent für Index
  und Query; ASCII-Slug-Konvention der Wissensbasis bleibt davon unberührt.
- **D4:** Post-Validierung strikt: zitierte IDs ⊆ Retrieved-Set (Block-Kopf-
  IDs); Fließtext-Verweis-IDs sind KEINE Belege (Systemprompt-Regel 2) —
  Verstoß → 1× Regenerierung → Verweigerung (UNCERTAIN_MESSAGE).
- **D5:** Vektoren-Tabelle ist Cache (Content-Hash × Modell), Rebuild
  löscht sie nicht; `--no-embed` setzt `embed_off` im Config-Copy.
- **D6:** Leeres Retrieval → deterministische Verweigerung ohne LLM-Call.
- **D7 (Bake-off 2026-09-14):** `qwen3.8:27b` ist das fixierte Antwortmodell
  (100 % Zitier-Präzision, 94,3 % Verweigerung korrekt). `gemma4:26b` als
  dokumentierter Latenz-Kandidat; ein Modellwechsel läuft nur erneut über
  das dokumentierte Protokoll (Skill).
- **Bake-off-Protokoll** (Skill): Modellwechsel nur über dokumentierten
  Goldset-Vergleich; Kriterium: Zitier-Präzision > Verweigerungs-
  korrektheit > Latenz.

## Files that matter right now

- `planung.md` — Plan + Entscheidungspunkte (Abschnitt 12) + Stand.
- `.agents/skills/pv-rag-agent/SKILL.md` — verbindliche Regeln.
- `agent/README.md` — Betrieb, Konfiguration, Host-Schritte.
- `agent/eval/goldset.yaml` — Goldset (IDs gegen kb.json verifiziert).
- `agent/generate.py` — Grounding-Kern (Prompt, Post-Validierung).
- `wissensbasis/README.md` — Layer-2-Schema (unverändert gültig).