pi_coder_2/README.md

> **Archiviert seit 16.10.2026.** Abgelöst durch **pi_coder v3** in `~/pi_coder_v3`
> (Forgejo `https://kitux.de/forgejo/dschlueter/pi_coder_3`). Dieser Stand wird nicht mehr gepflegt; pi lädt die
> Erweiterung inzwischen aus `~/pi_coder_v3`.

# pi_coder_2 — Automatisierter Coder/Judge-Workflow für pi agent

Dieses Repository enthält die Konfiguration und Skripte für einen automatisierten
Coding-Workflow mit einem lokalen Modell (Standard: Strata), das abwechselnd als Coder und Judge
agiert — gesteuert über Pi Agent. Er dreht solange Optimierungsschleifen, bis das
Programm Produktionsreife hat.

---

## Überblick

```
Nutzer gibt Auftrag
        │
        ▼
  /coder  →  Strata (:9090, Coder-Persona)  →  Implementierung + git commit
        │
        ▼
  /judge  →  Strata (:9090, Judge-Persona)  →  Review: PASS / FAIL + Blocker
        │
   FAIL? ▼
  /fix    →  Strata (:9090, Coder-Persona)  →  Fixes + git commit
        │
   PASS WITH CONCERNS? ▼
        │  (ohne --approve-concerns: wie FAIL → weiterer Fix-Zyklus)
        │
   PASS? ▼
  /shipit →  Strata (:9090, Judge-Persona)  →  Finale Freigabe: SHIP / NO-SHIP
               (nur bei "PASS WITH CONCERNS" --approve-concerns; klares PASS → direkt SHIP)

  /optimize = Coder→Judge→Fix-Schleife automatisch (bis PASS oder max. N Runden)
  --interactive: pausiert nach PASS für menschlichen Checkpoint + optionale Zusatzaufträge
```

Ein **einzelner** llama.cpp-Docker-Container bedient beide Rollen. Die Rollenumschaltung
(Coder ↔ Judge) erfolgt über unterschiedliche System-Prompts, die der `before_agent_start`-Hook
der Extension vor jeder Inference injiziert. pi agent wechselt keine Server mehr —
nur die Persona im System-Prompt ändert sich.

---

## Modelle

| Rolle | Modell (`<provider>/<id>`) | Port | Betrieb | GPU |
|---|---|---|---|---|
| Coder + Judge (Standard) | `strata/qwen3.8-flash-next-iq3_s` | 9090 | Strata-Server, `~/nvme2n1p7_home/strata-betrieb` | 1 und 2 |
| Coder + Judge (Alternative) | `llama-cpp-single/coding_model` (Qwen3.6-27B IQ4_XS) | 8001 | Container `coding_model`, `start-coding-server.sh` | 1 |

Coder- und Judge-Rollen werden durch verschiedene System-Prompts realisiert —
dasselbe Modell, unterschiedliche Persona. Freie Eingaben in pi nutzen weiter pis eigenes Standardmodell.

Strata lädt sein Modell bei der ersten Anfrage selbst, gibt vorher die GPUs frei und entlädt es nach 10 Minuten ohne
Anfrage (eingerichtet in `strata-betrieb`). Ein anderes Modell für beide Rollen setzt
`PI_CODER_MODEL=<provider>/<id>`, siehe
[BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md#modell-wählen).

---

## Voraussetzungen

- [pi](https://pi.dev) installiert (`~/.pi/`).
- Ein Modell für Coder und Judge:
  - **Standard:** der lokale Strata-Server auf `127.0.0.1:9090` (Betrieb: `~/nvme2n1p7_home/strata-betrieb`).
  - **Alternative:** der llama.cpp-Server in Docker auf Port 8001 (unten). Dafür Docker mit NVIDIA Container Toolkit,
    eine GPU mit 24 GB (Standard GPU 1, `GPU_DEVICE=…`) und das GGUF-Modell unter
    `$HF_HOME/models/qwen3/Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-IQ4_XS.gguf`
    (Standard `HF_HOME=/home/dschlueter/nvme2n1p7_home/huggingface`).

---

## Installation

```bash
git clone https://kitux.de/forgejo/dschlueter/pi_coder_2.git ~/pi_coder_v2
cd ~/pi_coder_v2
./deploy-pi-config.sh   # verlinkt Extension und mcp.json, kopiert models.json, übernimmt settings.json (nur packages)
```

Danach pi im Projektordner starten. Was das Skript genau tut und wie man das Modell wählt:
[BEDIENUNGSANLEITUNG.md, Kapitel 2](BEDIENUNGSANLEITUNG.md#2-vorbereitung).

---

## llama.cpp-Server (Alternative)

```bash
./start-coding-server.sh          # startet den Container coding_model, wartet bis HTTP bereit (bis 5 min)
GPU_DEVICE=0 ./start-coding-server.sh
./stop-coding-server.sh
./status-coding-server.sh
```

Ein erneuter Start entfernt einen laufenden Container zuerst (`docker rm -f`); eine laufende Anfrage bricht dabei ab.
Coder und Judge nutzen ihn mit `PI_CODER_MODEL=llama-cpp-single/coding_model pi`.

---

## llama.cpp-Serverparameter im Detail

### Parameter des Single-Servers (Port 8001)

| Parameter | Wert | Bedeutung |
|---|---|---|
| `--jinja` | — | Verwendet das im GGUF eingebettete Jinja-Chat-Template (Qwen-Format). Notwendig für korrekte `<\|im_start\|>`-Tokens. |
| `--reasoning on` | — | Aktiviert das interne Thinking-Budget des Modells (Qwen3-spezifisch). |
| `--no-context-shift` | — | Kontextfenster wird **nicht** verschoben wenn es voll ist — stattdessen Fehler. Verhindert stille Datenverluste. |
| `--repeat-penalty 1.05` | — | Leichte Penalty für Wiederholungen. |
| `--top-k 20` | — | Nur die 20 wahrscheinlichsten nächsten Tokens. |
| `--min-p 0.01` | — | Tokens mit Wahrscheinlichkeit < 1 % des wahrscheinlichsten Tokens werden ausgeschlossen. |
| `-ngl 999` | — | Alle Layer auf die GPU laden. |
| `-fa on` | — | Flash Attention. |
| `--kv-unified` | — | Einheitlicher KV-Cache über alle Schichten. |
| `--cache-type-k q4_0` | — | KV-Cache Keys 4-Bit quantisiert. Nötig für 256K Kontext auf einer 24-GB-GPU. |
| `--cache-type-v q4_0` | — | KV-Cache Values ebenfalls 4-Bit quantisiert. |
| `--cont-batching` | — | Continuous Batching. |
| `-c 262144` | 256K | Großes Kontextfenster für langen Gesprächsverlauf im Optimize-Loop. |
| `-n 16384` | 16K | Maximale Ausgabelänge. |
| `--temp 0.2` | — | Deterministisch — Coder-Rolle. Der Judge-System-Prompt gleicht die etwas höhere Temperatur aus. |
| `--parallel 2` | — | 2 Slots, damit pi agent Folgeanfragen schnell hintereinander stellen kann. |
| `--gpus '"device=1"'` | — | Standard: GPU 1. Überschreibbar: `GPU_DEVICE=0 ./start-coding-server.sh`. |

---

## GPU-Konfiguration und VRAM

### Aktuelles Setup (1 GPU, 1 Server)

Ein einzelner Container bedient beide Rollen sequenziell:

```
GPU 0  NVIDIA T600       →  Display / Monitor (nicht für KI genutzt)
GPU 1  RTX 3090 (24 GB)  →  coding_model  (Port 8001, Coder + Judge)
```

Da Coder und Judge nicht gleichzeitig inferieren, gibt es keinen VRAM-Konflikt.
Die Umschaltung zwischen den Rollen erfolgt ausschließlich über den System-Prompt —
der Container läuft ohne Unterbrechung durch.

### VRAM-Abschätzung für das 27B IQ4_XS-Modell

| Komponente | Größe (ca.) |
|---|---|
| Modell-Gewichte (IQ4_XS, 27B) | ~14 GB |
| KV-Cache bei 262 144 Tokens (q4_0) | ~8–10 GB |
| KV-Cache bei 131 072 Tokens (q4_0) | ~4–5 GB |
| KV-Cache bei 65 536 Tokens (q4_0) | ~2–3 GB |
| **Summe (262k Kontext)** | **~22–24 GB** |

Bei einer **24-GB-GPU** ist 262k Kontext knapp kalkuliert. Keine anderen Prozesse
dürfen nennenswert VRAM belegen (z. B. TTS-Dienste, Ollama). Prüfen mit:
```bash
nvidia-smi --query-gpu=index,memory.used,memory.free --format=csv
```

Falls der VRAM nicht reicht: Kontext in `start-coding-server.sh` auf `131072` oder `65536` reduzieren.

### Anpassung für andere GPU-Konfigurationen

```bash
# Andere GPU verwenden:
GPU_DEVICE=0 ./start-coding-server.sh

# 2 GPUs für einen Server (sehr großer Kontext):
# start-coding-server.sh anpassen:
  --gpus '"device=0,1"' \
  --tensor-split 0.5,0.5 \
  --main-gpu 0 \
  -c 262144
```

---

## Parameter-Tuning-Guide

### Temperatur (`--temp`)

| Wert | Eignung |
|---|---|
| `0.0–0.1` | Maximale Reproduzierbarkeit. |
| `0.1–0.3` | Guter Kompromiss für Coding. **Aktuell gesetzt: 0.2.** |
| `0.4–0.6` | Kreativere Lösungen. |
| `0.7–1.0` | Für Coding meist zu viel Rauschen. |

### Kontextgröße (`-c`)

| Kontext | KV-Cache (q4_0) | Empfehlung |
|---|---|---|
| 32 768 | ~1,9 GB | 1 × 16-GB-GPU |
| 65 536 | ~3,7 GB | 1 × 24-GB-GPU (konservativ) |
| 131 072 | ~7,5 GB | 1 × 24-GB-GPU |
| 262 144 | ~8–10 GB | 1 × 24-GB-GPU (q4_0) — **aktuell gesetzt** |

### KV-Cache-Quantisierung

| `--cache-type-k/v` | VRAM | Qualität |
|---|---|---|
| `f16` | 100 % (Basis) | Referenz |
| `q8_0` | ~50 % | Kaum merklich schlechter |
| `q4_0` | ~25 % | Merklicher Qualitätsverlust bei langen Kontexten — aber nötig für 256K Kontext auf 24 GB. **Aktuell gesetzt.** |

---

## Tests ausführen

```bash
./run-tests.sh
```

Keine npm-Installation nötig — nutzt den integrierten `node:test`-Runner und
`--experimental-strip-types` für TypeScript. Testet Parsing-Logik, Konfigurationskonsistenz
und Extension-Guards gegen Regressionen.

---

## Dateien

| Datei / Verzeichnis | Zweck |
|---|---|
| `pi-coding-extension.ts` | pi agent Extension (Kommandos, Tools, Hooks, Rollen-Logik) |
| `models.json` | Provider- und Modell-Konfiguration für pi agent |
| `settings.json` | pi-Settings; `deploy-pi-config.sh` übernimmt daraus nur die Liste `packages` |
| `mcp.json` | MCP-Server für pi (Playwright, Context7), nach `~/.pi/agent/mcp.json` verlinkt |
| `run-tests.sh` | Tests ausführen |
| `tests/` | Testdateien (pure-logic, config, extension-guards, scripts) |
| `start-coding-server.sh` | Single-Server starten (Port 8001, Coder + Judge) |
| `stop-coding-server.sh` | Container stoppen |
| `status-coding-server.sh` | Laufstatus anzeigen |
| `deploy-pi-config.sh` | Extension und `mcp.json` nach `~/.pi/agent/` verlinken, `models.json` kopieren, `packages` aus `settings.json` übernehmen |

---

## pi-Kommandos (Kurzübersicht)

| Kommando | Persona | Beschreibung |
|---|---|---|
| `/coder <auftrag>` | Coder | TASK.md anlegen, Implementierung starten |
| `/judge [fokus]` | Judge | Code-Review gegen TASK.md + letzten Commit |
| `/fix [hinweis]` | Coder | Judge-Kritik beheben, committen |
| `/shipit` | Judge | Finale Freigabeprüfung |
| `/optimize <auftrag> [--rounds N] [--with-doku] [--continue] [--interactive]` | beide | Vollautomatische Schleife bis PASS (Standard: 2 Runden) |
| `/optimize ... [--no-tests] [--approve-concerns] [--test-cmd "cmd"] [--test-timeout N]` | beide | Test-Erkennung überspringen / PASS WITH CONCERNS akzeptieren |
| `/patch <änderung>` | Coder | Gezielte Minimaländerung ohne Review |
| `/quick_check [was]` | Judge | Schnelle Prüfung der letzten Änderung |
| `/version` | — | Versionsnummer erhöhen (SemVer + Git-Tag) |
| `/update_doku` | Coder | Code kommentieren + README + Bedienungsanleitung + LICENCE.md |
| `/plan <auftrag>` | Coder | Implementierungsplan in PLAN.md (kein Code) |
| `/continue` | Coder | Unterbrochenen Prozess fortsetzen |
| `/cancel` | — | Laufenden Loop nach aktuellem Schritt abbrechen |
| `/new_project <pfad>` | — | Neues Projektverzeichnis + git init |

Ausführliche Beschreibung aller Kommandos mit Beispielen: [BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md).

---

## PASS WITH CONCERNS — Verhalten

Im `/optimize`-Loop gilt `PASS WITH CONCERNS` **nicht** als bestanden — der Coder erhält
einen weiteren Fix-Auftrag, genau wie bei `FAIL`. Erst sauberes `PASS` beendet die Schleife.

Opt-out: `--approve-concerns` lässt `PASS WITH CONCERNS` als bestanden gelten.

Wann der Judge welches Urteil gibt (Urteilsregeln, Abschnitt „Hinweise“): siehe
[BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md), Judge-Persona.

---

## Live-Aktivitätsstatus

Während der Ausführung zeigt pi_coder in der Statuszeile, was gerade passiert —
inklusive eines laufenden `[MM:SS]`-Timers während jeder LLM-Inference-Phase:

| Situation | Anzeige |
|---|---|
| Coder implementiert | `◉ Coder implementiert: Login-Flow mit JWT [01:23]` |
| edit-Tool aktiv | `Editiere src/main.py…` |
| git commit | `Git-Commit…` |
| Judge (Runde 1) | `◉○ Runde 1/2: Judge — TASK.md + letzter Commit + Tests [00:47]` |
| Judge (Runde 2) | `●◉ Runde 2/2: Judge — TASK.md + letzter Commit + Tests [02:15]` |
| Tests laufen | `●○ Runde 1/2: Tests laufen (pytest, max. 120s)…` |
| Fix-Phase | `●◉ Runde 2/2: Coder fixt — fehlendes Null-Check [01:05]` |
| ShipIt | `●●◉ ShipIt — finale Freigabe [00:33]` |
| Interactive-Pause | `⏸ PASS – warte auf /continue…` |

Der Timer beweist, dass die LLM tatsächlich arbeitet. Steht er still, hängt der Prozess.

---

## Documentation

- [BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md) – Einrichtung, Modellwahl, alle Befehle, MCP-Server, Web-Tests,
  schneller entwickeln, Fehlermeldungen
- [FUNKTIONSWEISE.md](FUNKTIONSWEISE.md) – Aufbau der Extension, Ablauf von `/optimize`, Designentscheidungen, Grenzen
- [CHANGELOG.md](CHANGELOG.md) – Änderungen und was beim Update zu tun ist
- [LICENSE](LICENSE) – MIT
- Strata-Server und Messwerte auf diesem PC: `~/nvme2n1p7_home/strata-betrieb`