Guardrail

A pluggable async filter applied to LLM text before it reaches TTS.

Defined in: src/core/types/guardrails.ts:160

A pluggable async filter applied to LLM text before it reaches TTS.

Examples

const redactAccounts: Guardrail = {
  name: 'account-numbers',
  check(text) {
    return { text: text.replace(/\b\d{10}\b/g, 'your account') };
  },
};

const moderation: Guardrail = {
  name: 'moderation',
  stages: ['final'],
  async check(text, ctx) {
    const res = await fetch('/api/moderate', {
      method: 'POST',
      body: JSON.stringify({ text }),
      signal: ctx.signal,
    });
    const { flagged, categories } = await res.json();
    return flagged
      ? { block: true, reason: 'flagged by moderation', metadata: { categories } }
      : {};
  },
};

See

GuardrailsConfig for wiring guardrails into the pipeline.

Properties

Property	Modifier	Type	Default value	Description	Defined in
`name`	`readonly`	`string`	`undefined`	Identifier used in logs and guardrail events. Should be unique.	src/core/types/guardrails.ts:162
`stages?`	`readonly`	readonly `GuardrailStage`[]	`['chunk', 'final']`	Stages at which this guardrail runs. Remarks Defaults to both stages. Restrict to `['final']` for expensive or network-bound checks that need the whole utterance; restrict to `['chunk']` for cheap rewrites that must not run twice.	src/core/types/guardrails.ts:174

Methods

check()

check(text, context): 
  | void
  | GuardrailResult
| Promise<void | GuardrailResult>;

Defined in: src/core/types/guardrails.ts:184

Inspect and optionally rewrite or block the text.

Parameters

Parameter	Type	Description
`text`	`string`	Text to filter — the output of the preceding guardrail, or the raw LLM text for the first guardrail in the chain.
`context`	`GuardrailContext`	Stage, accumulated text, history, and abort signal.

Returns

| void | GuardrailResult | Promise<void | GuardrailResult>

The decision, or nothing to pass the text through unchanged.