# pi-ghost-autocomplete

[English](README.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Español](README.es.md) | [中文](README.zh-CN.md) | [日本語](README.ja.md) | [Português](README.pt-BR.md) | [Italiano](README.it.md) | [Русский](README.ru.md)

Inline-Ghost-Text-Autovervollständigung für den [Pi Coding Agent](https://pi.dev/) (`@earendil-works/pi-coding-agent`).

Während du an der Pi-Eingabe schreibst, sagt ein LLM die wahrscheinlichste
Fortsetzung der aktuellen Zeile voraus und zeigt sie als grauen „Ghost-Text"
rechts vom Cursor an. Drücke **Rechtspfeil** zum Akzeptieren. Der Cursor
bewegt sich erst, wenn du das tust, das bestehende Slash-Command-Popup
behält **Tab**, und ein langsamer oder unerreichbarer Backend deaktiviert
sich selbstständig, statt den Chat zu spammen.

**Mehrsprachig** (Session 52): Unicode-fähige Worterkennung verarbeitet
deutsche Umlaute, französische/spanische Akzente, CJK-Schriften und
kombinierende Zeichen. Register-basiertes Routing stellt sicher, dass
Prosa in der jeweiligen Sprache vervollständigt wird, ohne als
Coding-Agent-Anweisung umgedeutet zu werden.

## Erste Schritte

### 1. Mercury Edit 2 API-Key besorgen

Der Standard-Provider ist **Mercury Edit 2** von Inception Labs — ein
diffusionsbasiertes Modell für latenzarme Code-Vervollständigungen.
Registriere dich unter [platform.inceptionlabs.ai](https://platform.inceptionlabs.ai),
um einen API-Key zu erhalten.

Setze die `INCEPTION_API_KEY`-Umgebungsvariable:

```bash
# ~/.bashrc oder ~/.zshrc
export INCEPTION_API_KEY="dein-key"
```

```powershell
# PowerShell $PROFILE
$env:INCEPTION_API_KEY = "dein-key"
```

### 2. Erweiterung installieren

```bash
pi install npm:pi-ghost-autocomplete
```

Für nur ein einzelnes Projekt:

```bash
pi install npm:pi-ghost-autocomplete -l
```

### 3. Pi starten und ausprobieren

```bash
pi
```

Beginne an der Eingabe zu tippen. Ein grauer Ghost-Text sollte innerhalb
von ~150 ms erscheinen. Drücke **Rechtspfeil** zum Akzeptieren oder tippe
weiter zum Verwerfen.

> **Die erste Sitzung fühlt sich „kalt" an.** Trie, Cache und Profil
> starten leer und lernen mit der Zeit. Nach 20–30 akzeptierten
> Vorschlägen werden häufige Präfixe aus dem lokalen Cache bedient.

## Konfiguration

Alle Einstellungen sind Umgebungsvariablen — keine zusätzliche
Konfigurationsdatei nötig. Die wichtigsten:

| Variable | Standard | Wirkung |
| --- | --- | --- |
| `PI_GHOST_DISABLED` | nicht gesetzt | Auf `1` setzen, um beim Start zu deaktivieren |
| `PI_GHOST_PROVIDER` | Mercury Edit 2 | `cloud`, `local`, oder `router` |
| `INCEPTION_API_KEY` | — | API-Key für Mercury Edit |
| `PI_GHOST_MODEL` | providerspezifisch | Modell-ID |
| `PI_GHOST_CHAT_MAX_TOKENS` | `256` | Token-Limit für den Chat-Zweig (Router-Modus) |
| `PI_GHOST_CHAT_TEMPERATURE` | `0.75` | Temperatur für den Chat-Zweig |
| `PI_GHOST_DEBOUNCE_MS` | 150 (Cloud) / 400 (Local) | Debounce vor Request |
| `PI_GHOST_METRICS` | nicht gesetzt | Auf `1` setzen für Metriken in `.pi/ghost-autocomplete/metrics.jsonl` |

> Die vollständige Variablen-Referenz findest du im
> [englischen README](README.md#configuration).

## Register-Routing

Der Router-Modus teilt die Arbeit zwischen zwei Modellen auf, basierend auf
dem **Completion-Register**:

| Register | Zweig | System-Prompt |
| --- | --- | --- |
| `code` | **FIM** (`mercury-edit-2`) | Code/Command/Pfad-Vervollständigung |
| `agent-message` | **Chat** (`mercury-2`) | „Setze die Nachricht an den Assistenten fort" |
| `general-prose` | **Chat** (`mercury-2`) | „Setze den Text natürlich fort, gleiche Sprache/Stil" — **ohne** Coding-Agent-Framing |

```bash
PI_GHOST_PROVIDER=router INCEPTION_API_KEY=dein-key pi ...
```

### Mehrsprachige Unterstützung

Die Intent-Erkennung und Kontext-Tokenisierung verwenden Unicode-fähige
Wortsegmentierung (`Intl.Segmenter`) statt ASCII-Regexen. Das bedeutet:

- Deutsche Umlaute (möchte, ändern, über) werden als vollständige Wörter erkannt
- Französische/Spanische Akzente (café, función) bleiben erhalten
- CJK-Text (Chinesisch/Japanisch/Koreanisch) erhält wörterbuchbasierte Segmentierung
- BM25-Kontextauswahl funktioniert für nichtenglische Konversationen

## Befehle

| Befehl | Wirkung |
| --- | --- |
| `/ghost` | Aktuelle Konfiguration anzeigen |
| `/ghost on` | Für diese Sitzung aktivieren |
| `/ghost off` | Für diese Sitzung deaktivieren |

## Metriken und Debug-Logging

```bash
PI_GHOST_METRICS=1 pi ...        # schreibt .pi/ghost-autocomplete/metrics.jsonl
PI_GHOST_DEBUG_LOG=1 pi ...      # schreibt .pi/ghost-autocomplete/debug.jsonl
```

Metriken enthalten: Zeitstempel, Provider-Latenzen, Completion-Register,
Ergebnis, Acceptance-Outcome und (bei `empty`) die diagnostizierte Ursache.
Rohe Prompts/Completions werden **niemals** in die Metrik-Datei geschrieben.

### Empty-Ursachen

| Ursache | Bedeutung |
| --- | --- |
| `model-empty` | Modell lieferte leeren/Whitespace-Only-Text |
| `token-budget-exhausted` | Budget vollständig für Reasoning verbraucht → `PI_GHOST_CHAT_MAX_TOKENS` erhöhen |
| `sanitizer-null` | Inhalt vom Sanitizer verworfen (Echo, Dateiname in Prosa) |
| `response-schema-error` | Response war JSON, aber nicht im erwarteten Schema |
| `http-error` | Fehlender Key, Non-2xx, malformed JSON, Timeout |

`pi-ghost-bench` zeigt eine `empty-cause`-Aufschlüsselung.

## Benutzerprofil

Die Erweiterung speichert ein langlebiges JSONL-Profil unter
`.pi/ghost-autocomplete/profile.jsonl`, um Slash-Command-, Pfad- und
Trigramm-Häufigkeiten über Sitzungen hinweg zu lernen. Das Profil speist
drei lokale Signale:

1. **Slash-Fast-Path** — `/`-Präfixe werden aus dem Gedächtnis bedient
2. **Profile-Bias-Rerank** — Trigramm-Häufigkeit fließt in den Reranker ein
3. **Pfad-Boost** — Häufige Pfade erhalten einen begrenzten Boost

Datenschutz: Keine rohen Präfixe oder Completions werden gespeichert.
Das Profil nutzt SHA-256-Hashes für Präfix-Lookups und sanitisierte
n-Grams. Sensible Nachrichten werden vollständig verworfen.

## Lizenz

SSPL-1.0 — siehe [Lizenzdatei](LICENSE).

---

> Die vollständige technische Dokumentation findest du im
> [englischen README](README.md) und in [`docs/`](docs/).