Documentation
¶
Overview ¶
Package guardrails provides built-in ProviderHook implementations that bridge the unified eval system to the pipeline's hook infrastructure.
Index ¶
- func NewGuardrailHook(typeName string, params map[string]any, opts ...GuardrailOption) (hooks.ProviderHook, error)
- func NewGuardrailHookFromRegistry(typeName string, params map[string]any, registry *evals.EvalTypeRegistry, ...) (hooks.ProviderHook, error)
- func ValidatorsToHooks(validators []prompt.ValidatorConfig) []hooks.ProviderHook
- type GuardrailHookAdapter
- func (a *GuardrailHookAdapter) AfterCall(ctx context.Context, req *hooks.ProviderRequest, resp *hooks.ProviderResponse) hooks.Decision
- func (a *GuardrailHookAdapter) BeforeCall(ctx context.Context, req *hooks.ProviderRequest) hooks.Decision
- func (a *GuardrailHookAdapter) Name() string
- func (a *GuardrailHookAdapter) OnChunk(ctx context.Context, chunk *providers.StreamChunk) hooks.Decision
- type GuardrailOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 ¶ added in v1.3.12
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 — handlers for which params are unusable return an error here, and the SDK's warn-and-skip loop in convertPackValidatorsToHooks logs and drops them.
func ValidatorsToHooks ¶ added in v1.4.9
func ValidatorsToHooks(validators []prompt.ValidatorConfig) []hooks.ProviderHook
ValidatorsToHooks 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"].
- Unusable validators (unknown type, ValidateParams failure) are logged and skipped; one bad entry does not break the others.
Types ¶
type GuardrailHookAdapter ¶ added in v1.3.12
type GuardrailHookAdapter struct {
// contains filtered or unexported fields
}
GuardrailHookAdapter wraps an evals.EvalTypeHandler as a hooks.ProviderHook. This bridges the unified eval system to the pipeline's hook infrastructure, allowing any registered eval handler to be used as a guardrail.
Guardrails always enforce: on a hit the adapter mutates the response (truncate or replace) and returns an Enforced decision so the pipeline continues. If you want observe-only behavior, declare an eval — not a guardrail — and assert on it in scenarios.
func (*GuardrailHookAdapter) AfterCall ¶ added in v1.3.12
func (a *GuardrailHookAdapter) AfterCall( ctx context.Context, req *hooks.ProviderRequest, resp *hooks.ProviderResponse, ) hooks.Decision
AfterCall checks provider output when direction is "output" or "both". When the guardrail triggers, it enforces in-place on resp.Message (truncating or replacing content) and returns an Enforced decision.
func (*GuardrailHookAdapter) BeforeCall ¶ added in v1.3.12
func (a *GuardrailHookAdapter) BeforeCall( ctx context.Context, req *hooks.ProviderRequest, ) hooks.Decision
BeforeCall checks input messages when direction is "input" or "both". For input direction, it evaluates the last user message.
func (*GuardrailHookAdapter) Name ¶ added in v1.3.12
func (a *GuardrailHookAdapter) Name() string
Name returns the eval type identifier for this guardrail.
func (*GuardrailHookAdapter) OnChunk ¶ added in v1.3.12
func (a *GuardrailHookAdapter) OnChunk( ctx context.Context, chunk *providers.StreamChunk, ) hooks.Decision
OnChunk evaluates streaming chunks via StreamableEvalHandler.EvalPartial. When a guardrail triggers, it truncates the chunk content and returns an Enforced decision so the provider stage can stop reading but continue the pipeline.
type GuardrailOption ¶ added in v1.3.12
type GuardrailOption func(*GuardrailHookAdapter)
GuardrailOption configures a GuardrailHookAdapter.
func WithMessage ¶ added in v1.3.12
func WithMessage(msg string) GuardrailOption
WithMessage sets the user-facing message shown when content is blocked.
Source Files