Plugins

​

Übersicht

​

Phasen

​

Ausführung der Kette

• Steps laufen in aufsteigender Reihenfolge. Ein späterer Step sieht die Änderungen eines früheren.
• Innerhalb eines Steps laufen Instanzen, deren Manifest Mutates: false angibt, parallel auf einer flachen Kopie des Exchange (ihre Values und Response-Header werden zurückgeführt). Der Step darf höchstens eine Instanz mit Mutates: true enthalten, die nach den lesenden Instanzen läuft. Zwei mutierende Instanzen im selben Step sind ein Konfigurationsfehler.
• Die Entscheidungen eines Steps werden nach Schweregrad zusammengeführt: block > respond > warn > allow. Die erste blockierende Entscheidung beendet die Kette nach ihrem Step.

​

Entscheidungen

​

Audit-Trail

​

Fehlermodi und Timeouts

​

Lebenszyklus von Instanzen

​

Streaming

​

Der Exchange

​

Konfiguration

​

Das Plugin-System aktivieren

plugins:
  enabled: true    # PLUGINS_ENABLED; Standardwert: false

​

Instanzen

guardrails:
  enabled: true
  rules:
    - name: "mask-keys"
      type: "string_replace"      # ein eingebautes Plugin oder der Manifest-Name eines geladenen Plugins
      phase: "response"           # prompt (Standard) | response | stream
      order: 10                   # Step innerhalb der Phase
      fail_mode: "open"           # closed (Standard) | open
      timeout_ms: 500             # 0 = kein Timeout pro Instanz (Standard)
      config:                     # wird gegen das ConfigSchema des Plugins validiert
        mode: "regex"
        rules: |
          sk-[A-Za-z0-9]{20,} => [redacted]

​

.so-Dateien laden

plugins:
  search_paths: ["/etc/gomodel/plugins"]   # PLUGINS_SEARCH_PATHS, kommagetrennt; Standardwert: leer
  load:
    - file: acme_guard.so                  # relativ zu einem Suchpfad oder absolut
      sha256: "3b1f..."                    # optionale Fixierung; eine Abweichung lässt den Start fehlschlagen

​

Dashboard

• Seite Plugins & Guardrails: Create Guardrail listet jedes Plugin auf, das einen Hook für prompt, response oder stream implementiert. Das Formular wird aus dem ConfigSchema des Plugins erzeugt: text, textarea, number, select, checkboxes, bool (ein Schalter), list (Freitext-Einträge, einer pro Zeile, gespeichert als String-Array), secret (maskiert; GET gibt ******** zurück, und das Zurücksenden genau dieses Literals behält den gespeicherten Wert bei) und model (dieselbe durchsuchbare Modellauswahl wie im Playground und in den Editoren für virtuelle Modelle, die die Modelle des Gateways auflistet; ein Alias oder ein virtuelles Modell wird eingetippt). Der Abschnitt Advanced enthält Fail mode (Default, Closed, Open) und Timeout (ms); diese gelten für die Instanz in jedem Workflow, der sie referenziert.
• Plugin-Liste: Unten auf der Seite Plugins & Guardrails steht jeder geladene Plugin-Typ mit Titel und Namen (Header Edit, dann header_edit – der Name ist das, worauf sich die Konfiguration bezieht), Version, Hooks, Quelle (eingebaut, registriert oder der Pfad der .so) und Zustand. Guardrail-Plugins (deren Instanzen eine Richtlinie auf Prompts, Responses oder Streams anwenden) tragen ein Schild-Symbol und werden zuerst aufgeführt; Routing-Strategien sind ebenfalls Plugins, aber keine Guardrails. Ein Plugin, das nicht geladen werden konnte, wird mit seinem Fehler aufgeführt. Die Seite wird angezeigt, sobald das Plugin-System aktiviert ist.
• Seite Workflows: Jeder Step hat eine Auswahl Phase; das Dropdown für Instanzen bietet nur Instanzen an, deren Plugin diese Phase implementiert.

​

Shared-Object-Plugins

• Plattform: Linux, macOS und FreeBSD, und nur in einem Binary, das mit CGO_ENABLED=1 gebaut wurde. Das Standard-Binary und das Standard-Image von GoModel sind statisch und lehnen .so-Dateien mit einer entsprechenden Fehlermeldung ab. Verwenden Sie make build-plugins (bin/gomodel-plugins) oder das Image gomodel:<version>-plugins (make image-plugins, gebaut aus Dockerfile.plugins, glibc-Laufzeit).
• Exakte Toolchain: Das Plugin muss mit derselben Go-Version, denselben Build-Flags (-trimpath, -race, -tags) und identischen Quellen jedes gemeinsam genutzten Pakets gebaut werden. Nur die Standardbibliothek und pluginapi werden gemeinsam genutzt, daher wirken sich interne Änderungen an GoModel nie auf ein Plugin aus, aber jedes GoModel-Release und jedes Update der Go-Toolchain (einschließlich Patch-Releases) erfordert einen Neubau. Machen Sie daraus einen CI-Schritt.
• Kein Entladen: Eine .so bleibt bis zum Neustart geladen. Änderungen an einer geladenen Datei werden beim Neustart wirksam; das Bearbeiten der Konfiguration einer Instanz führt Init ohne Neustart erneut auf einem frischen Wert aus.
• Vertrauenswürdiger Code: Das Laden einer .so ist gleichbedeutend mit einer Änderung des Binarys. Lassen Sie search_paths im Besitz von root und fixieren Sie im Produktivbetrieb sha256.

​

Bauen und prüfen

gomodel plugin build ./docs/example_plugins/keywordblock -o plugins/keyword_block.so
gomodel plugin inspect plugins/keyword_block.so
shasum -a 256 plugins/keyword_block.so     # Wert für plugins.load[].sha256

plugin file /app/plugins/x.so was built with a different toolchain, flags, or
pluginapi sources: it was built with go1.27.3, gomodel v0.1.90, flags -trimpath;
this binary was built with go1.27.3, gomodel v0.1.91, flags (none). Rebuild it
with `gomodel plugin build` from this GoModel version

docker build -f Dockerfile.plugins --target plugin-builder -t gomodel-plugin-builder .
docker run --rm -v "$PWD/my-plugin:/src" -v "$PWD/plugins:/out" \
  gomodel-plugin-builder -o /out/my-plugin.so /src

​

Ein Plugin schreiben

package main

import (
	"context"
	"encoding/json"
	"strings"

	"github.com/enterpilot/gomodel/pluginapi"
)

type wordBlock struct {
	words   []string
	enforce pluginapi.Enforcement
}

func (p *wordBlock) Manifest() pluginapi.Manifest {
	return pluginapi.Manifest{
		Name:      "word_block",
		Version:   "1.0.0",
		Kinds:     []pluginapi.Kind{pluginapi.KindPrompt},
		Guardrail: true,
		ConfigSchema: []pluginapi.Field{
			{
				Key: "words", Label: "Blocked words", Input: pluginapi.InputList,
				Required: true, Help: "One word per line.",
			},
			{
				Key: "action", Label: "On match", Input: pluginapi.InputSelect, Default: "block",
				Help: "Block rejects, respond answers with the message, warn records the match.",
				Options: []pluginapi.Option{{Value: "block", Label: "Block"}, {Value: "respond", Label: "Respond"}, {Value: "warn", Label: "Warn"}},
			},
			{Key: "message", Label: "Message", Input: pluginapi.InputText, Default: "request blocked by policy", Help: "Error, reply, or audit note."},
			pluginapi.BlockStatusField(),
		},
	}
}

func (p *wordBlock) Init(_ context.Context, raw json.RawMessage, _ pluginapi.Host) error {
	cfg, err := pluginapi.ParseConfig("word_block", p.Manifest().ConfigSchema, raw)
	if err != nil {
		return err
	}
	for _, w := range cfg.List("words") {
		p.words = append(p.words, strings.ToLower(w))
	}
	p.enforce = pluginapi.Enforcement{
		Action:      pluginapi.Action(cfg.Choice("action", "block", "block", "respond", "warn")),
		Message:     cfg.String("message", "request blocked by policy"),
		BlockStatus: cfg.BlockStatus("block_status"),
	}
	return cfg.Err()
}

func (p *wordBlock) Close(context.Context) error { return nil }

func (p *wordBlock) OnPrompt(_ context.Context, x *pluginapi.Exchange) (pluginapi.Decision, error) {
	if x.Prompt == nil || x.Prompt.LastUser() == nil {
		return pluginapi.Allow(), nil
	}
	text := strings.ToLower(x.Prompt.LastUser().Text())
	for _, w := range p.words {
		if strings.Contains(text, w) {
			return p.enforce.Enforce("word_block", map[string]any{"word": w}), nil
		}
	}
	return pluginapi.Allow(), nil
}

func GoModelPlugin() pluginapi.Plugin { return &wordBlock{} }

func main() {}

• Init erhält die Konfiguration nach der Validierung gegen ConfigSchema: Standardwerte angewendet, Zahlen, Booleans und Listen konvertiert, unbekannte Keys abgelehnt, erforderliche Keys geprüft. Zeilenorientierte textarea-Felder akzeptieren sowohl eine YAML-Liste von Strings als auch einen Block-Skalar; list-Felder akzeptieren eine Liste oder eine kommagetrennte Zeile und kommen als JSON-Array an; bool-Felder akzeptieren true/false als Boolean oder Text und kommen als JSON-Boolean an. Init wird einmal pro konfigurierter Instanz aufgerufen und erneut, wenn die Instanz bearbeitet wird.
• Lesen Sie die Konfiguration mit pluginapi.ParseConfig und dessen typisierten Lesemethoden (String, Choice, Bool, Int, Float, OptionalFloat, List, Lines, Roles, BlockStatus) statt mit einem Struct: Jede Lesemethode wendet dieselben Konvertierungen an, die das Dashboard und config.yaml benötigen, gibt bei einem Problem ihren Standardwert zurück, und Err() meldet das erste Problem mit dem betroffenen Key. Ein Decoder ist so eine einfache Liste von Zuweisungen plus eine Prüfung. RoleOptions() ist die Checkbox-Liste, die Roles versteht.
• Geben Sie Befunde über pluginapi.Enforcement aus: Lesen Sie action, message, block_status und optional respond_text darin ein; anschließend liefert Enforce(code, detail) den Block-Fehler, die Respond-Completion oder die Warnung, und Reject(code, detail) liefert Block oder Respond, selbst wenn die Aktion warn ist (für einen Befund, der nicht durchgelassen werden darf). BlockStatusField() ist das übliche Feld block_status. Die eingebauten Guardrails nutzen dies gemeinsam, sodass sich ihr Block, Respond und Warn gleich verhalten.
• Exportieren Sie einen Konstruktor (func GoModelPlugin() pluginapi.Plugin), damit eine Datei mehrere Instanzen bedienen kann. Ein var GoModelPlugin pluginapi.Plugin funktioniert ebenfalls, beschränkt die Datei aber auf eine einzige Instanz.
• Setzen Sie Mutates: true, wenn das Plugin Prompt, Response oder den Stream bearbeitet. Nicht mutierende Plugins dürfen sich einen Step teilen und laufen parallel.
• Setzen Sie Guardrail: true, wenn die Instanzen des Plugins Guardrails sind: Richtlinien, die auf Prompts, Responses oder Streams angewendet werden, unabhängig davon, ob sie blockieren, antworten, warnen oder umschreiben. Jedes eingebaute Traffic-Plugin setzt es (llm_judge, string_replace, tag_replace, header_edit, system_prompt, llm_based_altering); eine Routing-Strategie wie cheapest_healthy berührt nie den Traffic und lässt es auf false. Die Laufzeit ignoriert das Flag; das Dashboard markiert Guardrail-Plugins und ihre Instanzen mit einem Schild-Symbol und führt sie zuerst auf.
• Der an Init übergebene Host bietet Logger() (vorab mit Plugin und Instanz getaggt), Inference().Complete(...) (eine Chat Completion über das Gateway mit Ursprung plugin, für Budgets und Audit auf <user path>/guardrails/<instance> begrenzt), Metrics() (Namen mit dem Präfix plugin_<name>_) und HTTPClient() für Aufrufe externer Dienste wie eines Klassifikators oder eines Detektors für personenbezogene Daten. Der Client wird von allen Instanzen gemeinsam genutzt, verwendet die Proxy-Umgebung und den Verbindungspool des Gateways und hat als Absicherung einen Timeout von 60 s; erstellen Sie Requests mit http.NewRequestWithContext, damit timeout_ms der Instanz jeden Aufruf begrenzt. History() gibt in diesem Release einen Fehler zurück.
• Der Host implementiert außerdem das optionale pluginapi.DecisionsHost. Prüfen Sie es per Type Assertion auf dem Host und rufen Sie dann Decisions().Decide(ctx, req) auf, um einem Decision-Modell typisierte Fragen zu einem Input zu stellen, so wie es POST /v1/decisions tut. Eine Frage ist ein Prädikat (Wahrscheinlichkeit für Ja), eine Auswahl oder eine Bewertung. Der Aufruf wird wie Inference().Complete eingegrenzt und erfasst. Decisions().DecisionModel(model) meldet, ob ein Modell ausschließlich Decisions beantwortet, etwa jedes jev-Modell. llm_judge nutzt beides, um anhand einer Wahrscheinlichkeit zu blockieren, statt ein Chat-Urteil zu parsen:
  if dh, ok := host.(pluginapi.DecisionsHost); ok {
  	result, err := dh.Decisions().Decide(ctx, pluginapi.DecisionRequest{
  		Model:     "jev/jev-latest",
  		Input:     []pluginapi.Message{pluginapi.TextMessage(pluginapi.RoleUser, text)},
  		Questions: []pluginapi.Question{{Type: pluginapi.QuestionPredicate, Name: "spam", Instructions: "Is this spam?"}},
  	})
  	// result.Answers[0].Probability, außer wenn result.Answers[0].Refused()
  }
  
• Fügen Sie Summarize(config json.RawMessage) string hinzu, um in der Guardrail-Liste eine einzeilige Zusammenfassung darzustellen, und Normalize(config) (json.RawMessage, error), um eine Konfiguration vor dem Speichern zu kanonisieren. Beides ist optional.
• Implementieren Sie pluginapi.HealthChecker (Health(ctx) error), wenn eine Instanz von etwas außerhalb des Prozesses abhängt, etwa einem Klassifikator-Sidecar. GoModel prüft dies außerhalb des Request-Pfads, sobald die Instanz erstellt ist, und bei jeder Guardrail-Aktualisierung (workflows.refresh_interval, standardmäßig eine Minute), mit einer Frist von 5 s. Eine fehlschlagende Prüfung markiert die Instanz in GET /admin/guardrails und im Dashboard als degraded, mit dem Fehler als Begründung, und wird einmal pro Zustandswechsel geloggt; der Fehlertext darf keine Secrets enthalten und wird auf 256 Zeichen gekürzt. Der Zustand dient nur der Information: Der Traffic läuft weiterhin gemäß ihrem fail_mode durch die Instanz.
• Implementieren Sie pluginapi.ContentEditor (EditsContent() bool), wenn ein Plugin, das Mutates deklariert, so konfiguriert werden kann, dass es nicht bearbeitet, etwa ein Detektor, der markiert statt umzuschreiben. GoModel fragt eine konfigurierte Instanz vor Arbeiten, die es nur für bearbeitende Plugins ausführt – dem Wiedergeben des gespeicherten Verlaufs eines verketteten Responses-Requests, statt den Provider previous_response_id selbst auflösen zu lassen. Es ändert nie, wie ein Hook läuft, und bei einem mutierenden Plugin ohne diese Methode wird davon ausgegangen, dass es bearbeitet.
• Die Feld-Inputs secret und model gibt es für API-Keys externer Klassifikatoren und für Modellauswahlen; ein secret-Wert wird in jeder Admin-Response maskiert. Verwenden Sie bool für einen Schalter und list für eine offene Liste von Strings (Entitätstypen, eine Allowlist), statt diese in einem select oder einem textarea zu kodieren.
• Fügen Sie Feldern, die zu einem virtuellen Modell statt zur Instanz gehören, Scope: pluginapi.ScopeRoute hinzu (nur bei Routing-Strategien).

​

Ein Plugin testen

• plugintest.NewHost(replies...) ist ein Fake-Host: vorgegebene Inferenz-Antworten (oder eine Reply-Funktion oder ein Err), Decisions, die von einer Answer-Funktion beantwortet werden (ohne sie wird jede Frage abgelehnt), DecisionModels für DecisionModel, aufgezeichnete Requests() und DecisionRequests(), aufgezeichnete Recorded()-Metriken und ein einstellbarer HTTP-Client für einen Fake-Sidecar, der mit httptest gestartet wird.
• plugintest.Init, Text, Prompt, Completion und Exchange erstellen die Fixtures, die ein Hook-Aufruf benötigt, mit sauberer Änderungsverfolgung und einem Values-Speicher.
• plugintest.RunStream(ctx, hook, x, events) steuert einen StreamHook so, wie es der Host unter dessen StreamPolicy tut: Zusammenfassen von Chunks, der zurückgehaltene Lookbehind-Rest wird mit Overlap erneut gezeigt, pass, replace, drop und terminate werden auf das gesamte Fenster angewendet, und im gepufferten Modus wird die Completion für OnResponse zusammengesetzt. Das Ergebnis enthält den Text, den ein Client pro Choice erhalten hätte, die zugestellten Events, die terminate-Entscheidung und die End-Entscheidung.

p := plugintest.Init(t, New, `{"rules": "secret => [x]", "stream_lookbehind": 4}`, nil)
res, err := plugintest.RunStream(ctx, p.(pluginapi.StreamHook), plugintest.Exchange(nil, nil), []*pluginapi.StreamEvent{
	plugintest.TextDelta("my se"), plugintest.TextDelta("cret is safe"),
})
// res.Text[0] == "my [x] is safe": Der auf zwei Deltas aufgeteilte Treffer wurde einmal umgeschrieben.

​

Routing-Strategie-Plugins

type RouteStrategy interface {
	Select(ctx context.Context, req RouteRequest) (RouteChoice, error)
	OnAttemptEnd(outcome RouteOutcome)
}

virtual_models:
  - source: smart-router
    strategy: plugin                    # round_robin | cost | failover | adaptive | plugin
    strategy_plugin: cheapest_healthy   # Plugin-Name; erforderlich bei strategy: plugin
    strategy_config:                    # die Felder des Plugins mit Scope: route; ohne Angabe gelten die Standardwerte
      prefer: cheapest                  # cheapest | fastest
      max_error_rate: 0.2
    targets:
      - openai/gpt-4o-mini
      - anthropic/claude-haiku-4-5

• strategy_config wird gegen die routenbezogenen Felder des Plugins validiert (route_fields in GET /admin/plugins). strategy: plugin ohne strategy_plugin ist ein Validierungsfehler, und PUT /admin/virtual-models lehnt einen Namen ab, der kein geladenes Plugin mit route-Hook ist.
• Die weight der Ziele wird bei der Plugin-Strategie ignoriert.
• Instanzbezogene Felder eines Route-Plugins (ein Endpunkt, ein API-Key) stammen aus einer Guardrail-Definition, deren Name und Typ beide dem Plugin-Namen entsprechen; ohne eine solche Definition wird das Plugin mit {} initialisiert. Instanzbezogene secret-Werte erreichen ein Route-Plugin derzeit geschwärzt. Das Speichern dieser Definition baut die Instanz neu auf; die vorherige wird geschlossen, sobald ihre laufenden Select-Aufrufe zurückgekehrt sind.
• GoModel greift auf gewichtetes Round Robin zurück und loggt eine Warnung pro virtuellem Modell, wenn das Plugin fehlt, kein Route-Plugin ist, nicht initialisiert werden konnte, die strategy_config ungültig ist oder Select einen Fehler liefert, einen Panic auslöst, länger als 250 ms braucht oder ein Ziel außerhalb des verfügbaren Pools zurückgibt.

​

Admin-Endpunkte

​

GET /admin/plugins

[
  {
    "name": "string_replace",
    "label": "String Replace",
    "version": "1.0.0",
    "description": "Replaces, flags, or blocks text matching literal or regex rules in prompts, responses, and streams.",
    "kinds": ["prompt", "response", "stream"],
    "mutates": true,
    "guardrail": true,
    "source": "builtin",
    "fields": [{ "key": "rules", "label": "Rules", "input": "textarea", "required": true }],
    "route_fields": [],
    "health": "ok",
    "error": ""
  }
]

​

GET /admin/guardrails/types

{
  "type": "llm_judge",
  "label": "LLM Judge",
  "description": "Asks a judge model whether prompts and responses violate a policy, then blocks, answers, or flags them.",
  "defaults": { "action": "block", "max_tokens": 256, "target": "auto" },
  "fields": [{ "key": "model", "label": "Judge model", "input": "model", "required": true }],
  "phases": ["prompt", "response", "stream"],
  "source": "builtin",
  "mutates": false,
  "guardrail": true
}

​

GET, PUT, DELETE /admin/guardrails

​

GET /admin/workflows/guardrails

[{ "name": "pii-redact", "type": "llm_based_altering", "phases": ["prompt", "response"], "summary": "openai/gpt-4o-mini • user • default prompt" }]

​

Workflow-Payload Version 2