hooks

package
v1.3.9 Latest Latest
Warning

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

 Go to latest Published: Mar 4, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package hooks provides synchronous interception points for provider calls, tool execution, and session lifecycle in the PromptKit runtime.

Index

Constants

This section is empty.

Variables

View Source 
var Allow = Decision{Allow: true} //nolint:gochecknoglobals // convenience sentinel

Allow is the zero-cost approval decision.

Functions

This section is empty.

Types

type ChunkInterceptor 

type ChunkInterceptor interface {
	OnChunk(ctx context.Context, chunk *providers.StreamChunk) Decision
}

ChunkInterceptor is an opt-in streaming extension for ProviderHook. ProviderHooks that also implement ChunkInterceptor will have OnChunk called for each streaming chunk, enabling early abort.

type Decision 

type Decision struct {
	Allow    bool
	Reason   string
	Metadata map[string]any
}

Decision is the result of a hook evaluation.

func Deny 

func Deny(reason string) Decision

Deny creates a denial decision with a reason.

func DenyWithMetadata 

func DenyWithMetadata(reason string, metadata map[string]any) Decision

DenyWithMetadata creates a denial decision with a reason and metadata.

type HookDeniedError 

type HookDeniedError struct {
	HookName string
	HookType string // "provider_before", "provider_after", "chunk", "tool_before", "tool_after"
	Reason   string
	Metadata map[string]any
}

HookDeniedError is returned when a hook denies an operation.

func (*HookDeniedError) Error 

func (e *HookDeniedError) Error() string

type Option 

type Option func(*Registry)

Option configures a Registry during construction.

func WithProviderHook 

func WithProviderHook(h ProviderHook) Option

WithProviderHook registers a provider hook.

func WithSessionHook 

func WithSessionHook(h SessionHook) Option

WithSessionHook registers a session hook.

func WithToolHook 

func WithToolHook(h ToolHook) Option

WithToolHook registers a tool hook.

type ProviderHook 

type ProviderHook interface {
	Name() string
	BeforeCall(ctx context.Context, req *ProviderRequest) Decision
	AfterCall(ctx context.Context, req *ProviderRequest, resp *ProviderResponse) Decision
}

ProviderHook intercepts LLM provider calls.

type ProviderRequest 

type ProviderRequest struct {
	ProviderID   string
	Model        string
	Messages     []types.Message
	SystemPrompt string
	Round        int
	Metadata     map[string]any
}

ProviderRequest describes an LLM call about to be made.

type ProviderResponse 

type ProviderResponse struct {
	ProviderID string
	Model      string
	Message    types.Message
	Round      int
	LatencyMs  int64
}

ProviderResponse describes a completed LLM call.

type Registry 

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

Registry holds registered hooks and provides chain-execution methods. A nil *Registry is safe to use — all Run* methods return Allow / nil.

func NewRegistry 

func NewRegistry(opts ...Option) *Registry

NewRegistry creates a Registry with the given options.

func (*Registry) HasChunkInterceptors 

func (r *Registry) HasChunkInterceptors() bool

HasChunkInterceptors returns true if any registered provider hook implements ChunkInterceptor.

func (*Registry) IsEmpty 

func (r *Registry) IsEmpty() bool

IsEmpty returns true if no hooks are registered.

func (*Registry) RunAfterProviderCall 

func (r *Registry) RunAfterProviderCall(ctx context.Context, req *ProviderRequest, resp *ProviderResponse) Decision

RunAfterProviderCall executes all provider hooks' AfterCall in order. First deny wins and short-circuits.

func (*Registry) RunAfterToolExecution 

func (r *Registry) RunAfterToolExecution(ctx context.Context, req ToolRequest, resp ToolResponse) Decision

RunAfterToolExecution executes all tool hooks' AfterExecution in order. First deny wins and short-circuits.

func (*Registry) RunBeforeProviderCall 

func (r *Registry) RunBeforeProviderCall(ctx context.Context, req *ProviderRequest) Decision

RunBeforeProviderCall executes all provider hooks' BeforeCall in order. First deny wins and short-circuits.

func (*Registry) RunBeforeToolExecution 

func (r *Registry) RunBeforeToolExecution(ctx context.Context, req ToolRequest) Decision

RunBeforeToolExecution executes all tool hooks' BeforeExecution in order. First deny wins and short-circuits.

func (*Registry) RunOnChunk 

func (r *Registry) RunOnChunk(ctx context.Context, chunk *providers.StreamChunk) Decision

RunOnChunk executes all chunk interceptors in order. First deny wins and short-circuits.

func (*Registry) RunSessionEnd 

func (r *Registry) RunSessionEnd(ctx context.Context, event SessionEvent) error

RunSessionEnd executes all session hooks' OnSessionEnd in order. First error short-circuits.

func (*Registry) RunSessionStart 

func (r *Registry) RunSessionStart(ctx context.Context, event SessionEvent) error

RunSessionStart executes all session hooks' OnSessionStart in order. First error short-circuits.

func (*Registry) RunSessionUpdate 

func (r *Registry) RunSessionUpdate(ctx context.Context, event SessionEvent) error

RunSessionUpdate executes all session hooks' OnSessionUpdate in order. First error short-circuits.

type SessionEvent 

type SessionEvent struct {
	SessionID      string
	ConversationID string
	Messages       []types.Message
	TurnIndex      int
	Metadata       map[string]any
}

SessionEvent carries context for session lifecycle hooks.

type SessionHook 

type SessionHook interface {
	Name() string
	OnSessionStart(ctx context.Context, event SessionEvent) error
	OnSessionUpdate(ctx context.Context, event SessionEvent) error
	OnSessionEnd(ctx context.Context, event SessionEvent) error
}

SessionHook tracks session lifecycle.

type ToolHook 

type ToolHook interface {
	Name() string
	BeforeExecution(ctx context.Context, req ToolRequest) Decision
	AfterExecution(ctx context.Context, req ToolRequest, resp ToolResponse) Decision
}

ToolHook intercepts tool execution (LLM-initiated calls only).

type ToolRequest 

type ToolRequest struct {
	Name   string
	Args   json.RawMessage
	CallID string
}

ToolRequest describes a tool call about to be executed.

type ToolResponse 

type ToolResponse struct {
	Name      string
	CallID    string
	Content   string
	Error     string
	LatencyMs int64
}

ToolResponse describes a completed tool execution.

Source Files

View all Source files

Directories

Path Synopsis
Package guardrails provides built-in ProviderHook implementations that replace the legacy validator system with hook-based guardrails.
 Package guardrails provides built-in ProviderHook implementations that replace the legacy validator system with hook-based guardrails.

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.