From 7c989f3d91837b6d52d2f4bb05cdffbe9daedbe5 Mon Sep 17 00:00:00 2001 From: flemming-it Date: Mon, 25 May 2026 14:06:04 +0200 Subject: [PATCH] docs: add MODULE.md + MODULE.de.md inline docs Same shape as text-extract's docs commit. Audit-grade model- provenance fields documented next to each output so the operator sees the contract without leaving the Store sheet. Signed-off-by: flemming-it --- MODULE.de.md | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++ MODULE.md | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 188 insertions(+) create mode 100644 MODULE.de.md create mode 100644 MODULE.md diff --git a/MODULE.de.md b/MODULE.de.md new file mode 100644 index 0000000..532120b --- /dev/null +++ b/MODULE.de.md @@ -0,0 +1,94 @@ +# text.translate + +Ollama-basierte Übersetzung zwischen Sprachen. Sendet Quelltext +an einen konfigurierten LLM-Endpunkt mit einem +Übersetzungs-System-Prompt und liefert die Übersetzung plus +audit-taugliche Modell-Herkunfts-Felder. + +## Capability + +- `text.translate@0.1.0` + +## Eingaben + +| Name | Typ | Beschreibung | +| ----------------- | ---- | ------------------------------------------------------------------------- | +| `text` | text | Quelltext. | +| `target_language` | text | Zielsprache in einfachem Englisch (z.B. `German`, `French`, `ja-JP`). | +| `source_language` | text | Optionaler Hinweis auf die Ausgangssprache. Leer = Modell erkennt selbst. | +| `endpoint` | text | Ollama-förmiger `/api/chat`-Endpunkt. | +| `model` | text | Modell-ID am Endpunkt (z.B. `qwen2.5:14b`). | +| `api_key` | text | Optionaler Bearer-Token für Cloud-Endpunkte. | + +## Ausgaben + +| Name | Typ | Beschreibung | +| ----------------- | ---- | ------------------------------------------------------------------ | +| `translation` | text | Die Übersetzung. | +| `source_language` | text | Echo der Eingabe (oder erkannte Sprache bei Auto). | +| `target_language` | text | Echo der Eingabe. | +| `model_endpoint` | text | URL, gegen die übersetzt wurde. | +| `model_name` | text | Modell-ID wie an die LLM-API gesendet. | +| `model_digest` | text | SHA-256-Digest des bedienenden Ollama-Modells (wenn erreichbar). | + +Die drei `model_*`-Ausgaben sind das Audit-Primitiv: jede +Übersetzung im Flow-Log lässt sich auch Monate später dem exakten +Modell-Hash zuordnen, der sie erzeugt hat. + +## Berechtigungen + +```yaml +permissions: + - "net: localhost" + - "net: 127.0.0.1" + - "net: api.openai.com" + - "net: api.anthropic.com" +``` + +Default-Policy erlaubt lokales Ollama und die zwei großen +Hosted-Anbieter. Mit privatem LLM-Endpunkt: Hostname in die +Operator-Policy-Ceiling aufnehmen; das Modul prüft seine +Berechtigungen gegen diese Ceiling bei der Installation. + +## Für regulierte Umgebungen gebaut + +Der Ollama-Endpunkt steht per Default auf einem lokalen Daemon +— Quelltext verlässt nie den Rechner. Cloud-Anbieter sind +Opt-in über die URL + Operator-Policy. Das `model_digest`-Feld +ist der kryptographische Vertrauensanker für die +Übersetzungs-Herkunft: zwei Ausgaben mit gleichem Digest +stammen vom selben Modell-Gewicht, Punkt. + +## Grenzen in v0.1.0 + +- Single-Shot. Lange Dokumente mit Chunking + Überlapp- + Stitching folgt in v0.2.0. +- Keine Glossar-/Terminologie-Listen. Aktuell verlässt sich das + Modul auf das Allgemeinwissen des Modells; ein `glossary`- + Input ist auf der v0.2.0-Roadmap. + +## Beispiel-Flow + +```yaml +name: translate-to-german +inputs: + source: text +steps: + - id: translate + use: text.translate@^0 + with: + text: $inputs.source + target_language: "German" + endpoint: "http://localhost:11434/api/chat" + model: "qwen2.5:14b" +outputs: + translation: $translate.translation + audit_model: $translate.model_digest +``` + +## Build + +```bash +cargo build --release --target wasm32-wasip2 +# Ausgabe: target/wasm32-wasip2/release/text_translate.wasm +``` diff --git a/MODULE.md b/MODULE.md new file mode 100644 index 0000000..f9d462b --- /dev/null +++ b/MODULE.md @@ -0,0 +1,94 @@ +# text.translate + +Ollama-backed translation between languages. Sends source text +to a configured LLM endpoint with a translation system prompt +and emits the translated text plus audit-grade +model-provenance fields. + +## Capability + +- `text.translate@0.1.0` + +## Inputs + +| Name | Type | Description | +| ----------------- | ---- | ---------------------------------------------------------------------- | +| `text` | text | Source text to translate. | +| `target_language` | text | Target language in plain English (e.g. `German`, `French`, `ja-JP`). | +| `source_language` | text | Optional source-language hint. Empty = let the model auto-detect. | +| `endpoint` | text | Ollama-shaped `/api/chat` endpoint URL. | +| `model` | text | Model identifier the endpoint serves (e.g. `qwen2.5:14b`). | +| `api_key` | text | Optional bearer token for cloud-hosted endpoints. | + +## Outputs + +| Name | Type | Description | +| ----------------- | ---- | -------------------------------------------------------------------- | +| `translation` | text | The translated text. | +| `source_language` | text | Echo of the input value (or detected language when auto). | +| `target_language` | text | Echo of the input value. | +| `model_endpoint` | text | URL the translation was generated against. | +| `model_name` | text | Model identifier as supplied to the LLM API. | +| `model_digest` | text | SHA-256 digest of the served Ollama model (when reachable). | + +The three `model_*` outputs are the audit primitive: every +translation in the flow log can be matched to the exact model +hash that produced it, even months later. + +## Permissions + +```yaml +permissions: + - "net: localhost" + - "net: 127.0.0.1" + - "net: api.openai.com" + - "net: api.anthropic.com" +``` + +The default policy allows local Ollama and the two major +hosted providers. Operators with a private LLM endpoint add +their hostname to the operator-policy ceiling; the module's +permissions are enforced against that ceiling at install time. + +## Built for regulated environments + +The Ollama endpoint defaults to a local daemon — source text +never leaves the host. Cloud providers are opt-in via the +endpoint URL + operator policy. The `model_digest` field is +the cryptographic root-of-trust for translation provenance: +two outputs with the same digest came from the same model +weights, period. + +## Limits in v0.1.0 + +- Single-shot translation. Long-document chunked translation + with overlap-stitching is the v0.2.0 plan. +- No glossary / terminology-list support. Operators currently + rely on the model's general knowledge; a `glossary` input + is on the v0.2.0 roadmap. + +## Example flow + +```yaml +name: translate-to-german +inputs: + source: text +steps: + - id: translate + use: text.translate@^0 + with: + text: $inputs.source + target_language: "German" + endpoint: "http://localhost:11434/api/chat" + model: "qwen2.5:14b" +outputs: + translation: $translate.translation + audit_model: $translate.model_digest +``` + +## Build + +```bash +cargo build --release --target wasm32-wasip2 +# Output: target/wasm32-wasip2/release/text_translate.wasm +```