CI / Linux x86_64 (Forgejo) (push) Failing after 1s

Details

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

3.9 KiB

Raw Blame History

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

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:

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.
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.
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

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

cargo build --release --target wasm32-wasip2
# Ausgabe: target/wasm32-wasip2/release/llm_chat.wasm

3.9 KiB Raw Blame History