guardrails

package
v0.1.66 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 31, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package guardrails provides a pluggable pipeline for request-level guardrails.

Guardrails intercept requests before they reach providers, allowing validation, modification, or rejection.

Guardrails operate on a normalized []Message DTO, decoupled from concrete API request types (ChatRequest, ResponsesRequest, etc.). Adapters in the GuardedProvider convert between concrete requests and the message list.

Execution is driven by a per-guardrail "order" value:

  • Guardrails with the same order run in parallel (concurrently).
  • Groups are executed sequentially in ascending order.
  • Each group receives the output of the previous group.

Example with orders 0, 0, 1, 2, 2: 

Group 0  ──┬── guardrail A ──┬──▶ Group 1 ── guardrail C ──▶ Group 2 ──┬── guardrail D ──┬──▶ done
           └── guardrail B ──┘                                         └── guardrail E ──┘

Index

Constants

View Source 
const (
	DefaultLLMBasedAlteringMaxTokens = 4096
)
View Source 
const DefaultLLMBasedAlteringPrompt = `` /* 8087-byte string literal not displayed */

DefaultLLMBasedAlteringPrompt is the built-in prompt used when no custom prompt is configured. It is derived from LiteLLM's data anonymization guardrail prompt and instructs the model to rewrite text conservatively.

Variables

View Source 
var ErrNotFound = errors.New("guardrail not found")

ErrNotFound indicates a requested guardrail was not found.

Functions

func ComputeGuardrailsHash 

func ComputeGuardrailsHash(rules []RuleDescriptor) string

ComputeGuardrailsHash computes the guardrails_hash for a set of rule identifiers. Each rule is represented as "name:type:order:mode:content_hash". The combined seed is sorted for stability, then passed through SHA-256. Uses xxhash64 per-component and SHA-256 for the final hash to balance speed and collision resistance.

The hash is carried on the request context (core.WithGuardrailsHash) and consumed by the response cache as an opaque key component, so guardrail configuration changes invalidate cached completions.

func EffectiveLLMBasedAlteringMaxTokens 

func EffectiveLLMBasedAlteringMaxTokens(maxTokens int) int

EffectiveLLMBasedAlteringMaxTokens returns the effective max_tokens value for the auxiliary rewrite request.

func IsValidationError 

func IsValidationError(err error) bool

IsValidationError reports whether err is a validation error.

func NormalizeLLMBasedAlteringRoles 

func NormalizeLLMBasedAlteringRoles(roles []string) ([]string, error)

NormalizeLLMBasedAlteringRoles validates, lowercases, and deduplicates the configured target roles.

func ResolveLLMBasedAlteringPrompt 

func ResolveLLMBasedAlteringPrompt(prompt string) string

ResolveLLMBasedAlteringPrompt returns the effective system prompt.

Types

type Catalog 

type Catalog interface {
	Len() int
	Names() []string
	BuildPipeline(steps []StepReference) (*Pipeline, string, error)
}

Catalog resolves named guardrail references into executable pipelines. BuildPipeline returns the compiled pipeline, a deterministic configuration hash for cache/change detection, and an error. The hash should change whenever the effective pipeline configuration changes; empty is reserved for "no pipeline".

type ChatCompletionExecutor 

type ChatCompletionExecutor interface {
	ChatCompletion(ctx context.Context, req *core.ChatRequest) (*core.ChatResponse, error)
}

ChatCompletionExecutor provides the auxiliary model call used by llm_based_altering guardrails.

type ContextPipelineResolver 

type ContextPipelineResolver interface {
	PipelineForContext(ctx context.Context) *Pipeline
}

ContextPipelineResolver resolves a request-scoped guardrails pipeline.

type Definition 

type Definition struct {
	Name        string          `json:"name" bson:"name"`
	Type        string          `json:"type" bson:"type"`
	Description string          `json:"description,omitempty" bson:"description,omitempty"`
	UserPath    string          `json:"user_path,omitempty" bson:"user_path,omitempty"`
	Config      json.RawMessage `json:"config" bson:"config"`
	CreatedAt   time.Time       `json:"created_at" bson:"created_at"`
	UpdatedAt   time.Time       `json:"updated_at" bson:"updated_at"`
}

Definition is one persisted reusable guardrail instance.

type Guardrail 

type Guardrail interface {
	// Name returns a human-readable identifier for this guardrail.
	Name() string

	// Process processes a normalized message list.
	// Return the (possibly modified) messages, or an error to reject the request.
	Process(ctx context.Context, msgs []Message) ([]Message, error)
}

Guardrail processes a message list and returns the (possibly modified) messages or an error. Returning an error rejects the request before it reaches the provider.

type LLMBasedAlteringConfig 

type LLMBasedAlteringConfig struct {
	Model             string
	Provider          string
	UserPath          string
	Prompt            string
	Roles             []string
	SkipContentPrefix string
	MaxTokens         int
}

LLMBasedAlteringConfig holds the normalized configuration for the auxiliary LLM-backed message rewriting guardrail.

func NormalizeLLMBasedAlteringConfig 

func NormalizeLLMBasedAlteringConfig(cfg LLMBasedAlteringConfig) (LLMBasedAlteringConfig, error)

NormalizeLLMBasedAlteringConfig resolves defaults for the auxiliary LLM guardrail config.

type LLMBasedAlteringGuardrail 

type LLMBasedAlteringGuardrail struct {
	// contains filtered or unexported fields
}

LLMBasedAlteringGuardrail rewrites targeted message contents by calling an auxiliary model before the main provider request runs.

func NewLLMBasedAlteringGuardrail 

func NewLLMBasedAlteringGuardrail(name string, cfg LLMBasedAlteringConfig, executor ChatCompletionExecutor) (*LLMBasedAlteringGuardrail, error)

NewLLMBasedAlteringGuardrail constructs an LLM-backed content rewriting guardrail.

func (*LLMBasedAlteringGuardrail) Name 

func (g *LLMBasedAlteringGuardrail) Name() string

Name returns the configured guardrail name.

func (*LLMBasedAlteringGuardrail) Process 

func (g *LLMBasedAlteringGuardrail) Process(ctx context.Context, msgs []Message) ([]Message, error)

Process rewrites targeted message text and fails open on auxiliary provider errors so the original request can continue unchanged.

type Message 

type Message struct {
	Role        string // "system", "user", "assistant", "tool"
	Content     string
	ToolCalls   []core.ToolCall
	ToolCallID  string
	ContentNull bool
}

Message represents a single message in a conversation. This is the normalized DTO that all text guardrails operate on, decoupled from concrete API request types.

type MongoDBStore 

type MongoDBStore struct {
	// contains filtered or unexported fields
}

MongoDBStore stores guardrail definitions in MongoDB.

func NewMongoDBStore 

func NewMongoDBStore(ctx context.Context, database *mongo.Database) (*MongoDBStore, error)

NewMongoDBStore creates collection indexes if needed.

func (*MongoDBStore) Close 

func (s *MongoDBStore) Close() error

func (*MongoDBStore) Delete 

func (s *MongoDBStore) Delete(ctx context.Context, name string) error

func (*MongoDBStore) Get 

func (s *MongoDBStore) Get(ctx context.Context, name string) (*Definition, error)

func (*MongoDBStore) List 

func (s *MongoDBStore) List(ctx context.Context) ([]Definition, error)

func (*MongoDBStore) Upsert 

func (s *MongoDBStore) Upsert(ctx context.Context, definition Definition) error

func (*MongoDBStore) UpsertMany 

func (s *MongoDBStore) UpsertMany(ctx context.Context, definitions []Definition) error

type Pipeline 

type Pipeline struct {
	// contains filtered or unexported fields
}

Pipeline orchestrates the execution of multiple guardrails.

Guardrails are grouped by their order value. Groups execute sequentially in ascending order. Within a group, all guardrails run in parallel. If a group contains a single guardrail, it runs directly (no goroutine overhead).

func NewPipeline 

func NewPipeline() *Pipeline

NewPipeline creates a new empty guardrails pipeline.

func (*Pipeline) Add 

func (p *Pipeline) Add(g Guardrail, order int)

Add appends a guardrail with the given execution order. Guardrails with the same order run in parallel; different orders run sequentially.

func (*Pipeline) Len 

func (p *Pipeline) Len() int

Len returns the number of guardrails in the pipeline.

func (*Pipeline) Process 

func (p *Pipeline) Process(ctx context.Context, msgs []Message) ([]Message, error)

Process runs all guardrails on a normalized message list.

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry stores named guardrails so workflows can reference them by id.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates an empty named guardrail registry.

func (*Registry) BuildPipeline 

func (r *Registry) BuildPipeline(steps []StepReference) (*Pipeline, string, error)

BuildPipeline resolves named guardrail references into an executable pipeline and hash.

func (*Registry) Len 

func (r *Registry) Len() int

Len returns the number of registered named guardrails.

func (*Registry) Names 

func (r *Registry) Names() []string

Names returns the registered guardrail names in sorted order.

func (*Registry) Register 

func (r *Registry) Register(g Guardrail, descriptor RuleDescriptor) error

Register adds one named guardrail and its hashing descriptor.

type Result 

type Result struct {
	Service       *Service
	Store         Store
	RefreshErrors <-chan error
	// contains filtered or unexported fields
}

Result holds the initialized guardrail service and any owned resources.

func New 

func New(ctx context.Context, shared storage.Storage, refreshInterval time.Duration, executors ...ChatCompletionExecutor) (*Result, error)

New creates a guardrails subsystem using an existing storage connection.

func (*Result) Close 

func (r *Result) Close() error

Close releases resources held by the guardrails subsystem.

type RuleDescriptor 

type RuleDescriptor struct {
	Name    string
	Type    string
	Order   int
	Mode    string
	Content string
}

RuleDescriptor describes a single active guardrail rule for hashing.

type SQLStore added in v0.1.60 

type SQLStore struct {
	// contains filtered or unexported fields
}

SQLStore stores guardrail definitions in a SQL database.

func NewSQLStore added in v0.1.60 

func NewSQLStore(ctx context.Context, db sqlx.DB) (*SQLStore, error)

NewSQLStore creates the guardrail table and indexes if needed.

func (*SQLStore) Close added in v0.1.60 

func (s *SQLStore) Close() error

func (*SQLStore) Delete added in v0.1.60 

func (s *SQLStore) Delete(ctx context.Context, name string) error

func (*SQLStore) Get added in v0.1.60 

func (s *SQLStore) Get(ctx context.Context, name string) (*Definition, error)

func (*SQLStore) List added in v0.1.60 

func (s *SQLStore) List(ctx context.Context) ([]Definition, error)

func (*SQLStore) Upsert added in v0.1.60 

func (s *SQLStore) Upsert(ctx context.Context, definition Definition) error

func (*SQLStore) UpsertMany added in v0.1.60 

func (s *SQLStore) UpsertMany(ctx context.Context, definitions []Definition) error

type Service 

type Service struct {
	// contains filtered or unexported fields
}

Service keeps reusable guardrails cached in memory and refreshes them from storage.

func NewService 

func NewService(store Store, executors ...ChatCompletionExecutor) (*Service, error)

NewService creates a guardrail service backed by the provided store.

func (*Service) BuildPipeline 

func (s *Service) BuildPipeline(steps []StepReference) (*Pipeline, string, error)

BuildPipeline resolves named steps through the current in-memory guardrail registry.

func (*Service) Delete 

func (s *Service) Delete(ctx context.Context, name string) error

Delete removes a guardrail definition from storage and swaps the snapshot on success.

func (*Service) Get 

func (s *Service) Get(name string) (*Definition, bool)

Get returns one cached guardrail by name.

func (*Service) Len 

func (s *Service) Len() int

Len returns the number of loaded guardrails.

func (*Service) List 

func (s *Service) List() []Definition

List returns all cached guardrail definitions sorted by name.

func (*Service) ListViews 

func (s *Service) ListViews() []View

ListViews returns all cached guardrail definitions with lightweight summaries.

func (*Service) Names 

func (s *Service) Names() []string

Names returns the loaded guardrail names in sorted order.

func (*Service) Refresh 

func (s *Service) Refresh(ctx context.Context) error

Refresh reloads guardrails from storage and atomically swaps the in-memory snapshot.

func (*Service) SetExecutor 

func (s *Service) SetExecutor(ctx context.Context, executor ChatCompletionExecutor) error

SetExecutor swaps the auxiliary chat executor used by llm_based_altering guardrails and rebuilds the in-memory snapshot atomically.

func (*Service) TypeDefinitions 

func (s *Service) TypeDefinitions() []TypeDefinition

TypeDefinitions returns the supported guardrail type schemas.

func (*Service) Upsert 

func (s *Service) Upsert(ctx context.Context, definition Definition) error

Upsert validates and stores a guardrail definition, then swaps the snapshot on success.

func (*Service) UpsertDefinitions 

func (s *Service) UpsertDefinitions(ctx context.Context, definitions []Definition) error

UpsertDefinitions validates and upserts a definition set, then swaps the snapshot on success.

type StepReference 

type StepReference struct {
	Ref  string
	Step int
}

StepReference points to one named guardrail and the step it should run at.

type Store 

type Store interface {
	List(ctx context.Context) ([]Definition, error)
	Get(ctx context.Context, name string) (*Definition, error)
	Upsert(ctx context.Context, definition Definition) error
	UpsertMany(ctx context.Context, definitions []Definition) error
	Delete(ctx context.Context, name string) error
	Close() error
}

Store defines persistence operations for reusable guardrail definitions.

type SystemPromptGuardrail 

type SystemPromptGuardrail struct {
	// contains filtered or unexported fields
}

SystemPromptGuardrail injects, overrides, or decorates system messages.

func NewSystemPromptGuardrail 

func NewSystemPromptGuardrail(name string, mode SystemPromptMode, content string) (*SystemPromptGuardrail, error)

NewSystemPromptGuardrail creates a new system prompt guardrail instance. name identifies this instance (e.g. "safety-prompt", "compliance-check"). mode must be "inject", "override", or "decorator". content is the system prompt text to apply.

func (*SystemPromptGuardrail) Name 

func (g *SystemPromptGuardrail) Name() string

Name returns this instance's name.

func (*SystemPromptGuardrail) Process 

func (g *SystemPromptGuardrail) Process(_ context.Context, msgs []Message) ([]Message, error)

Process applies the system prompt guardrail to a normalized message list.

type SystemPromptMode 

type SystemPromptMode string

SystemPromptMode defines how the system prompt guardrail modifies messages. 

const (
	// SystemPromptInject adds a system message only if none exists.
	SystemPromptInject SystemPromptMode = "inject"

	// SystemPromptOverride replaces all existing system messages with the configured one.
	SystemPromptOverride SystemPromptMode = "override"

	// SystemPromptDecorator prepends the configured content to the first existing
	// system message (separated by a newline), or adds a new system message if none exists.
	SystemPromptDecorator SystemPromptMode = "decorator"
)

type TypeDefinition 

type TypeDefinition struct {
	Type        string          `json:"type"`
	Label       string          `json:"label"`
	Description string          `json:"description,omitempty"`
	Defaults    json.RawMessage `json:"defaults"`
	Fields      []TypeField     `json:"fields"`
}

TypeDefinition describes one supported guardrail type and its config schema.

func TypeDefinitions 

func TypeDefinitions() []TypeDefinition

TypeDefinitions returns the UI-facing definitions for supported guardrail types.

type TypeField 

type TypeField struct {
	Key         string       `json:"key"`
	Label       string       `json:"label"`
	Input       string       `json:"input"`
	Required    bool         `json:"required"`
	Help        string       `json:"help,omitempty"`
	Placeholder string       `json:"placeholder,omitempty"`
	Options     []TypeOption `json:"options,omitempty"`
}

TypeField describes one UI field for a guardrail type.

type TypeOption 

type TypeOption struct {
	Value string `json:"value"`
	Label string `json:"label"`
}

TypeOption is one allowed option for a typed guardrail config field.

type ValidationError 

type ValidationError = validation.Error

ValidationError indicates invalid guardrail input or state.

type View 

type View struct {
	Definition
	Summary string `json:"summary,omitempty"`
}

View is the admin-facing representation of a persisted guardrail.

func ViewFromDefinition 

func ViewFromDefinition(def Definition) View

ViewFromDefinition projects one guardrail definition into its admin-facing view.

type WorkflowBatchPreparer 

type WorkflowBatchPreparer struct {
	// contains filtered or unexported fields
}

WorkflowBatchPreparer applies the guardrails pipeline selected by the current workflow.

func NewWorkflowBatchPreparer 

func NewWorkflowBatchPreparer(provider core.RoutableProvider, resolver ContextPipelineResolver) *WorkflowBatchPreparer

NewWorkflowBatchPreparer creates a native-batch preparer that resolves its pipeline per request.

func (*WorkflowBatchPreparer) PrepareBatchRequest 

func (p *WorkflowBatchPreparer) PrepareBatchRequest(ctx context.Context, providerType string, req *core.BatchRequest) (*core.BatchRewriteResult, error)

PrepareBatchRequest applies the request-scoped guardrails pipeline to native batch items.

type WorkflowRequestPatcher 

type WorkflowRequestPatcher struct {
	// contains filtered or unexported fields
}

WorkflowRequestPatcher applies the guardrails pipeline selected by the current workflow.

func NewWorkflowRequestPatcher 

func NewWorkflowRequestPatcher(resolver ContextPipelineResolver) *WorkflowRequestPatcher

NewWorkflowRequestPatcher creates a translated-request patcher that resolves its pipeline from the request context on each call.

func (*WorkflowRequestPatcher) PatchChatRequest 

func (p *WorkflowRequestPatcher) PatchChatRequest(ctx context.Context, req *core.ChatRequest) (*core.ChatRequest, error)

PatchChatRequest applies the request-scoped guardrails pipeline to a translated chat request.

func (*WorkflowRequestPatcher) PatchResponsesRequest 

func (p *WorkflowRequestPatcher) PatchResponsesRequest(ctx context.Context, req *core.ResponsesRequest) (*core.ResponsesRequest, error)

PatchResponsesRequest applies the request-scoped guardrails pipeline to a translated responses request.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.