guardrails

func CompileValidators ¶

func CompileValidators(validators []prompt.ValidatorConfig) ([]hooks.ProviderHook, error)

CompileValidators turns pack-declared validators into ProviderHooks suitable for prepending to a hook registry. Both SDK.Open and Arena's per-turn pipeline use this so guardrails run identically in production and in tests.

Per-validator behavior:

• Validators with Enabled == &false are skipped silently (explicit opt-out). nil Enabled means enabled (spec default).
• All accepted validators enforce: on a hit they rewrite the assistant message in place (truncate or replace). If you want observe-only behavior, declare an eval and assert on it; guardrails always act.
• "message" set on the validator becomes the user-facing blocked text, falling back to Params["message"].

Failure policy — both shapes of "this declaration cannot work" are FATAL, for the same reason:

• An **unknown eval type** returns ErrUnknownGuardrailType. A type that is not registered has no legitimate use — it is a typo — and silently dropping it leaves the conversation with no protection while load appears to succeed. That is fail-open on a safety control.
• A registered type whose own evals.ParamValidator **rejects the params** returns ErrInvalidGuardrailParams. The handler is the authority on its own config; its rejection says this validator cannot run, and dropping it produces exactly the same silently unprotected conversation. This path used to log and skip on a forward-compatibility argument — that a pack authored against a newer runtime may carry params this build does not understand. It does not apply: a build that does not know the type at all is already fatal, and a build that does know it has the handler's own verdict. Forward-compatibility loses to an unprotected conversation.

Params that no handler ever inspects are unaffected — only a handler that implements evals.ParamValidator can reject anything here, and a type with no validator accepts whatever it is given, exactly as before.

On a fatal error no hooks are returned, so a caller cannot accidentally proceed with a partial guardrail set.

func CompileValidatorsWithOptions ¶ added in v2.5.0

func CompileValidatorsWithOptions(
	validators []prompt.ValidatorConfig, registry *evals.EvalTypeRegistry, opts ...GuardrailOption,
) ([]hooks.ProviderHook, error)

CompileValidatorsWithOptions is CompileValidatorsWithRegistry with options applied to every guardrail it builds — WithJudge above all, which is what makes a judge-backed validator usable at all.

Per-validator options (the blocked message) are applied after these, so a validator's own message still wins.

func CompileValidatorsWithRegistry ¶

func CompileValidatorsWithRegistry(
	validators []prompt.ValidatorConfig, registry *evals.EvalTypeRegistry,
) ([]hooks.ProviderHook, error)

CompileValidatorsWithRegistry is CompileValidators resolving each validator's eval type against the supplied registry instead of the built-in default. Pass the registry a caller configured (sdk.WithEvalRegistry) so a custom handler can back a pack validator; a nil registry means the default one.

Without this the default registry does not know a custom type, construction fails, and — on the lenient path — the guardrail is logged and dropped, which leaves the conversation unprotected while load appears to succeed (#1717).

Failure policy is CompileValidators's: an unknown type and a handler-rejected param set are both fatal.

func NewGuardrailHook ¶

func NewGuardrailHook(typeName string, params map[string]any, opts ...GuardrailOption) (hooks.ProviderHook, error)

NewGuardrailHook creates a guardrail ProviderHook using the default eval registry.

func NewGuardrailHookFromRegistry ¶

func NewGuardrailHookFromRegistry(
	typeName string, params map[string]any, registry *evals.EvalTypeRegistry,
	opts ...GuardrailOption,
) (hooks.ProviderHook, error)

NewGuardrailHookFromRegistry creates a guardrail ProviderHook using the eval registry. Any registered eval handler (including aliases) can be used as a guardrail.

If the handler implements evals.ParamValidator, the params are normalised (ApplyDefaults + NormalizeParams) and passed to ValidateParams before the hook is constructed. This surfaces invalid pack validators at SDK load time instead of silently failing every turn: a rejection is returned wrapped in ErrInvalidGuardrailParams, which the strict compile path (and therefore sdk.Open) treats as fatal.