docs: add MODULE.md + MODULE.de.md inline docs

Explains the 'why this module instead of inline HTTP' answer operators ask when they see llm.chat for the first time: audit, permission posture, endpoint portability. Signed-off-by: flemming-it <sf@flemming.it>
2026-05-25 14:06:04 +02:00 · 2026-05-25 14:06:04 +02:00 · 84a23e6b14
commit 84a23e6b14
parent 4c10a5ff3d
2 changed files with 210 additions and 0 deletions
--- a/MODULE.de.md
+++ b/MODULE.de.md
@ -0,0 +1,106 @@
+# llm.chat
+
+Generischer Ollama-kompatibler LLM-Chat-Adapter. Das
+Baustein-Modul für jeden Flow, der eine LLM-Einzelantwort
+braucht — klassifizieren, Felder extrahieren, umformulieren,
+entscheiden — ohne einen eigenen HTTP-Client zu bauen.
+
+## Capability
+
+- `llm.chat@0.1.0`
+
+## Eingaben
+
+| Name             | Typ  | Beschreibung                                                              |
+| ---------------- | ---- | ------------------------------------------------------------------------- |
+| `prompt`         | text | Der User-Prompt.                                                          |
+| `endpoint`       | text | Ollama-förmiger `/api/chat`-URL (z.B. `http://localhost:11434/api/chat`). |
+| `model`          | text | Modell-ID (z.B. `qwen2.5:14b`, `llama3.1:8b`).                            |
+| `api_key`        | text | Optionaler Bearer-Token für Cloud-Endpunkte.                              |
+| `system_prompt`  | text | Optionale System-Nachricht. Leer = Default des Modells.                   |
+
+## Ausgaben
+
+| Name             | Typ  | Beschreibung                                                          |
+| ---------------- | ---- | --------------------------------------------------------------------- |
+| `response`       | text | Die Antwort des Assistants als Plain-Text.                            |
+| `model_endpoint` | text | URL, gegen die die Antwort erzeugt wurde.                             |
+| `model_name`     | text | Modell-ID wie an die LLM-API gesendet.                                |
+| `model_digest`   | text | SHA-256-Digest des bedienenden Ollama-Modells. Leer bei Cloud-APIs.   |
+
+Zusammen beantworten die drei `model_*`-Ausgaben die Audit-
+Frage: „Welches genaue Modell hat diese Antwort erzeugt?" —
+diese Spur ist der Grund, warum Flows dieses Modul nutzen statt
+eigene HTTP-Calls zu sprechen.
+
+## Berechtigungen
+
+```yaml
+permissions:
+  - "net: localhost"
+  - "net: 127.0.0.1"
+  - "net: api.openai.com"
+  - "net: api.anthropic.com"
+```
+
+Loopback (lokales Ollama) per Default. Cloud-Endpunkte brauchen
+einen Operator-Policy-Override in
+`~/.fai/config.yaml#security.max_permissions`.
+
+## Warum dieses Modul statt Inline-HTTP
+
+Drei Gründe:
+
+1. **Audit.** Jeder LLM-Aufruf erzeugt `model_endpoint`,
+   `model_name`, `model_digest` als separate Ausgaben, die
+   im hash-verketteten Audit-Log neben der Response landen.
+   Eine Aufsichts-Reproduzierbarkeits-Prüfung vergleicht
+   einfach das Digest-Feld mit dem Modell-Snapshot.
+2. **Permission-Posture.** Operator:innen sehen `llm.chat`
+   in den installierten Modulen + dessen deklarierte
+   `net:`-Liste. Ein hausgemachtes HTTP-Modul würde seine
+   Endpunkte entweder verstecken oder bei jeder Installation
+   eine frische Review-Oberfläche schaffen.
+3. **Endpunkt-Portabilität.** Endpunkt + Modell sind Flow-
+   Inputs, keine Compile-Time-Konstanten. Derselbe Flow läuft
+   in der Entwicklung gegen `localhost:11434` und in Produktion
+   gegen ein Inferenz-Cluster — nur die Eingabe wechselt.
+
+## Grenzen in v0.1.0
+
+- Kein Streaming. Die ganze Antwort wird gepuffert, bevor der
+  Output-Step feuert.
+- Keine Tool-Call- / Function-Call-Oberfläche. Ein Flow, der
+  Tool-Use braucht, kombiniert mehrere `llm.chat`-Schritte mit
+  Prompt-Engineering oder nutzt MCP via Bridge.
+- Cloud-Provider-Adapter für OpenAI und Anthropic kommen erst,
+  wenn ein Flow sie braucht. Heute ist das Ollama-Wire-Format
+  das einzige Ziel.
+
+## Beispiel-Flow
+
+```yaml
+name: classify-incoming
+inputs:
+  text: text
+steps:
+  - id: classify
+    use: llm.chat@^0
+    with:
+      prompt: $inputs.text
+      system_prompt: |
+        Klassifiziere den Text als: question, complaint,
+        feedback, spam. Antworte nur mit dem Label.
+      endpoint: "http://localhost:11434/api/chat"
+      model: "qwen2.5:14b"
+outputs:
+  category: $classify.response
+  audit_model: $classify.model_digest
+```
+
+## Build
+
+```bash
+cargo build --release --target wasm32-wasip2
+# Ausgabe: target/wasm32-wasip2/release/llm_chat.wasm
+```