guardrails

package
v0.1.90 Latest Latest
Warning

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

 Go to latest Published: Sep 8, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Index

Constants

This section is empty.

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. See plugins.ComputeChainHash.

func IsValidationError 

func IsValidationError(err error) bool

IsValidationError reports whether err is a validation error.

func TypeLabel added in v0.1.90 

func TypeLabel(name string) string

TypeLabel turns a manifest name into a title: "llm_based_altering" becomes "LLM Based Altering". The dashboard shows it next to the name.

Types

type Catalog 

type Catalog interface {
	Len() int
	Names() []string
	BuildChains(steps []StepReference) (*plugins.Chains, error)
}

Catalog resolves named guardrail references into per-phase plugin chains. BuildChains returns nil when steps is empty; the chain hashes change whenever the effective configuration changes.

type ContextChainsResolver added in v0.1.90 

type ContextChainsResolver interface {
	ChainsForContext(ctx context.Context) *plugins.Chains
}

ContextChainsResolver resolves the request-scoped plugin chains.

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"`
	// FailMode is "closed" or "open"; empty selects the phase default.
	FailMode string `json:"fail_mode,omitempty" bson:"fail_mode,omitempty"`
	// TimeoutMS bounds every hook call of the instance; zero means none.
	TimeoutMS int       `json:"timeout_ms,omitempty" bson:"timeout_ms,omitempty"`
	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 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 Normalizer added in v0.1.90 

type Normalizer interface {
	Normalize(config json.RawMessage) (json.RawMessage, error)
}

Normalizer is implemented by plugins that canonicalize a validated config before it is stored (for example folding a provider hint into the model).

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, catalog *plugins.Catalog, deps plugins.HostDeps) (*Result, error)

New creates a guardrails subsystem using an existing storage connection, building instances from the plugin catalog.

func (*Result) Close 

func (r *Result) Close() error

Close releases resources held by the guardrails subsystem.

type RuleDescriptor 

type RuleDescriptor = plugins.RuleDescriptor

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 guardrail instances cached in memory and refreshes them from storage. Instances whose definition is unchanged survive a refresh; replaced ones are closed once compiled workflows have moved on.

func NewService 

func NewService(store Store, catalog *plugins.Catalog, deps plugins.HostDeps) (*Service, error)

NewService creates a guardrail service backed by the provided store. The catalog supplies the plugin types instances are built from; deps are the gateway services exposed to plugins.

func (*Service) BuildChains added in v0.1.90 

func (s *Service) BuildChains(steps []StepReference) (*plugins.Chains, error)

BuildChains resolves named steps into per-phase chains through the current in-memory instances.

func (*Service) Close added in v0.1.90 

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

Close closes every active and retired instance. The service keeps an empty snapshot afterwards; call it after request handling and refreshes stopped.

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, secrets redacted.

func (*Service) GetView added in v0.1.90 

func (s *Service) GetView(name string) (View, bool)

GetView returns one cached guardrail view by name.

func (*Service) InstanceConfig added in v0.1.90 

func (s *Service) InstanceConfig(name string) (config json.RawMessage, pluginType string, ok bool)

InstanceConfig returns the stored (unredacted) config and type of one cached guardrail, for building plugin instances outside this service. Callers must not expose the config to admin clients.

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, secrets redacted.

func (*Service) ListViews 

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

ListViews returns all cached guardrail definitions with phases and 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) SetChatCompleter added in v0.1.90 

func (s *Service) SetChatCompleter(chat plugins.ChatCompleter)

SetChatCompleter swaps the gateway-internal chat executor plugins use for inference. Instances see the new executor on their next call.

func (*Service) TypeDefinitions 

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

TypeDefinitions returns the guardrail editor schema of every catalog plugin that implements a prompt, response, or stream hook.

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. A masked secret keeps the stored value.

func (*Service) UpsertDefinitions 

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

UpsertDefinitions validates and upserts a definition set (configuration seeding), then swaps the snapshot on success. Secrets are stored as given.

type StepReference 

type StepReference struct {
	Ref   string
	Phase pluginapi.Kind
	Step  int
}

StepReference points a workflow step at one named guardrail instance in one phase. An empty Phase means prompt.

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 Summarizer added in v0.1.90 

type Summarizer interface {
	Summarize(config json.RawMessage) string
}

Summarizer is implemented by plugins that render a one-line summary of a config for the guardrails list.

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"`
	Phases      []string        `json:"phases"`
	Source      string          `json:"source"`
	Mutates     bool            `json:"mutates"`
	Guardrail   bool            `json:"guardrail"`
}

TypeDefinition describes one supported guardrail type and its config schema.

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"`
	Default     any          `json:"default,omitempty"`
	Scope       string       `json:"scope,omitempty"`
}

TypeField describes one UI field for a guardrail type.

func TypeFieldsFromSchema added in v0.1.90 

func TypeFieldsFromSchema(schema []pluginapi.Field, scope pluginapi.FieldScope) []TypeField

TypeFieldsFromSchema converts the schema fields of one scope.

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
	// Phases lists the hook phases the instance's plugin implements.
	Phases  []string `json:"phases,omitempty"`
	Summary string   `json:"summary,omitempty"`
	// Guardrail reports whether the instance's plugin polices traffic (see
	// pluginapi.Manifest.Guardrail); an instance of a modifier such as
	// header_edit is a plugin instance but not a guardrail.
	Guardrail bool `json:"guardrail"`
	// Mutates reports whether the instance's plugin may edit the request or
	// response (see pluginapi.Manifest.Mutates); within one workflow step the
	// gateway runs such an instance after the step's readers.
	Mutates bool `json:"mutates"`
}

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 without catalog-derived fields (phases, summary).

type WorkflowBatchPreparer 

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

WorkflowBatchPreparer runs the prompt chain selected by the current workflow over native batch items.

func NewWorkflowBatchPreparer 

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

NewWorkflowBatchPreparer creates a native-batch preparer that resolves its chains 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 prompt chain to native batch items.

type WorkflowRequestPatcher 

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

WorkflowRequestPatcher runs the prompt chain selected by the current workflow over translated requests.

func NewWorkflowRequestPatcher 

func NewWorkflowRequestPatcher(resolver ContextChainsResolver) *WorkflowRequestPatcher

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

func (*WorkflowRequestPatcher) PatchChatRequest 

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

PatchChatRequest runs the prompt chain over a translated chat request.

func (*WorkflowRequestPatcher) PatchResponsesRequest 

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

PatchResponsesRequest runs the prompt chain over 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.