Generative AI Transformer Plugins¶

In a nutshell

These plugins let an AI language model tweak things as the assistant works. They act like an editor sitting in the middle of the conversation. They can step in twice: once to clean up or rephrase what you just said before the assistant tries to understand it, and once to polish the assistant's reply before it's spoken aloud. You can stack several of them and set the order they run in. To learn more, see Transformer Plugins and the Glossary.

Transformer plugins intercept the OVOS processing pipeline at two points: before intent matching (utterance transformers) and before TTS synthesis (dialog transformers). They operate independently of the persona system but can use the same LLM backends.

Utterance transformers (opm.transformer.text): run after STT, before NLP.
Dialog transformers (opm.transformer.dialog): run after skill response generation, before TTS.

LLM-backed implementations are provided by ovos-openai-plugin / ovos-gguf-plugin (dialog transformers).

Multiple transformers of each type can be stacked. The priority config key controls execution order (lower priority runs first, OVOS-TRANSFORM-1 §4 ascending order).

Utterance Transformers¶

Utterance transformers normalize or validate ASR output before it reaches the intent pipeline. They receive a list of candidate utterances and return a (possibly modified) list plus a context dict.

A typical utterance transformer normalises informal or noisy speech to standard form, or classifies ASR output as valid or invalid before it reaches intent matching so that garbled speech like "Potato stop green light now yes." is discarded. The priority config key controls where each runs in the chain (lower priority runs first).

Dialog Transformers¶

Dialog transformers receive the final response string from the skill and return a rewritten version. Only invoked when a rewrite_prompt is configured (via config or per-call context). Falls back to the original dialog on API error.

OpenAI Dialog Transformer¶

OpenAIDialogTransformer — ovos_openai_plugin/dialog_transformers.py:OpenAIDialogTransformer

Entry point: opm.transformer.dialog (ovos-dialog-transformer-openai-plugin)

Works with any OpenAI-compatible endpoint: OpenAI, Ollama, llama.cpp, or ovos-persona-server:

{
  "dialog_transformers": {
    "ovos-dialog-transformer-openai-plugin": {
      "api_url": "https://api.openai.com/v1",
      "key": "sk-...",
      "model": "gpt-4o-mini",
      "rewrite_prompt": "rewrite the text as if you were explaining it to a 5-year-old"
    }
  }
}

GGUF Dialog Transformer¶

GGUFDialogTransformer — ovos_gguf_plugin/dialog_transformers.py:GGUFDialogTransformer

Fully offline alternative using a local GGUF model:

{
  "dialog_transformers": {
    "ovos-dialog-transformer-gguf-plugin": {
      "model": "/path/to/model.gguf",
      "rewrite_prompt": "Rewrite in a warm, friendly tone.",
      "n_gpu_layers": 20
    }
  }
}

Rewrite Prompt Examples¶

The rewrite_prompt value is the most important lever. Examples across all transformer implementations:

Prompt	Effect
`"Rewrite so it sounds natural when spoken aloud. Remove markdown."`	TTS-safe output
`"Rewrite as if explaining to a 5-year-old."`	Simpler vocabulary
`"Rewrite in the style of a grumpy old pirate."`	Character voice
`"Make it sound enthusiastic and upbeat."`	Tone adjustment
`"Remove all technical jargon."`	Plain language
`"Explain it like you're a Shakespearean actor."`	Archaic dramatic style

Stacking Transformers¶

Multiple transformers of the same type can be active at once. Each configured entry under dialog_transformers runs in turn, lower priority first (ascending). Each one's output feeds into the next. For example, you can run a cheap local pass to strip markdown and jargon, then let an expensive cloud model add personality on top:

{
  "dialog_transformers": {
    "ovos-dialog-transformer-gguf-plugin": {
      "model": "/path/to/model.gguf",
      "rewrite_prompt": "Remove all markdown and technical jargon; keep it plain and short.",
      "n_gpu_layers": 20,
      "priority": 40
    },
    "ovos-dialog-transformer-openai-plugin": {
      "api_url": "https://api.openai.com/v1",
      "key": "sk-...",
      "model": "gpt-4o-mini",
      "rewrite_prompt": "Rewrite in the style of a grumpy old pirate.",
      "priority": 60
    }
  }
}

With this configuration, a skill's dialog is rewritten twice before TTS: first the GGUF transformer (priority: 40) runs locally to clean the raw text, then its output is passed to the OpenAI transformer (priority: 60) to apply the character voice. If either call fails, it falls back to passing its input through unchanged, so the chain degrades gracefully.

Utterance transformers work the same way but run before intent matching (cleaning or validating ASR output), with lower priority also running first.

Where this code actually lives

ovos-core only defines the opm.transformer.text / opm.transformer.dialog entry-point contracts and calls into whatever is installed. It does not implement any transformer itself. The LLM-backed implementations documented on this page live in their own plugin repos: ovos-openai-plugin and ovos-gguf-plugin.

Source code: OpenVoiceOS/ovos-core (transformer contract) · OpenVoiceOS/ovos-openai-plugin · OpenVoiceOS/ovos-gguf-plugin (implementations).

Read next: Transformers Overview (Pipeline) Related: OpenAI-compatible · GGUF / Local LLM · Agent Engine Types