hooks

package
v1.3.12 Latest Latest
Warning

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

 Go to latest Published: Mar 10, 2026 License: Apache-2.0 Imports: 10 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
	// Enforced indicates the hook already applied enforcement (e.g., truncated
	// or replaced content on the response). When true, the provider stage
	// records the validation result but continues the pipeline instead of
	// returning an error.
	Enforced bool
}

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.

func Enforced added in v1.3.12 

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

Enforced creates an enforced decision — the hook applied enforcement (truncation, content replacement) and the pipeline should continue.

type ExecHookConfig added in v1.3.12 

type ExecHookConfig struct {
	Name      string
	Command   string
	Args      []string
	Env       []string
	TimeoutMs int
	Phases    []string
	Mode      string // "filter" | "observe"
}

ExecHookConfig holds the configuration for creating exec-based hooks.

type ExecProviderHook added in v1.3.12 

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

ExecProviderHook implements ProviderHook by spawning an external subprocess.

func NewExecProviderHook added in v1.3.12 

func NewExecProviderHook(cfg *ExecHookConfig) *ExecProviderHook

NewExecProviderHook creates a new ExecProviderHook from the given config.

func (*ExecProviderHook) AfterCall added in v1.3.12 

func (h *ExecProviderHook) AfterCall(
	ctx context.Context, req *ProviderRequest, resp *ProviderResponse,
) Decision

AfterCall intercepts an LLM provider call after it completes.

func (*ExecProviderHook) BeforeCall added in v1.3.12 

func (h *ExecProviderHook) BeforeCall(ctx context.Context, req *ProviderRequest) Decision

BeforeCall intercepts an LLM provider call before it is sent.

func (*ExecProviderHook) Name added in v1.3.12 

func (h *ExecProviderHook) Name() string

Name returns the hook name.

type ExecSessionHook added in v1.3.12 

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

ExecSessionHook implements SessionHook by spawning an external subprocess.

func NewExecSessionHook added in v1.3.12 

func NewExecSessionHook(cfg *ExecHookConfig) *ExecSessionHook

NewExecSessionHook creates a new ExecSessionHook from the given config.

func (*ExecSessionHook) Name added in v1.3.12 

func (h *ExecSessionHook) Name() string

Name returns the hook name.

func (*ExecSessionHook) OnSessionEnd added in v1.3.12 

func (h *ExecSessionHook) OnSessionEnd(ctx context.Context, event SessionEvent) error

OnSessionEnd handles the session end event.

func (*ExecSessionHook) OnSessionStart added in v1.3.12 

func (h *ExecSessionHook) OnSessionStart(ctx context.Context, event SessionEvent) error

OnSessionStart handles the session start event.

func (*ExecSessionHook) OnSessionUpdate added in v1.3.12 

func (h *ExecSessionHook) OnSessionUpdate(ctx context.Context, event SessionEvent) error

OnSessionUpdate handles a session update event.

type ExecToolHook added in v1.3.12 

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

ExecToolHook implements ToolHook by spawning an external subprocess.

func NewExecToolHook added in v1.3.12 

func NewExecToolHook(cfg *ExecHookConfig) *ExecToolHook

NewExecToolHook creates a new ExecToolHook from the given config.

func (*ExecToolHook) AfterExecution added in v1.3.12 

func (h *ExecToolHook) AfterExecution(ctx context.Context, req ToolRequest, resp ToolResponse) Decision

AfterExecution intercepts a tool call after execution.

func (*ExecToolHook) BeforeExecution added in v1.3.12 

func (h *ExecToolHook) BeforeExecution(ctx context.Context, req ToolRequest) Decision

BeforeExecution intercepts a tool call before execution.

func (*ExecToolHook) Name added in v1.3.12 

func (h *ExecToolHook) Name() string

Name returns the hook name.

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 bridge the unified eval system to the pipeline's hook infrastructure.
 Package guardrails provides built-in ProviderHook implementations that bridge the unified eval system to the pipeline's hook infrastructure.

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.