toolapproval

package
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Jun 18, 2025 License: AGPL-3.0 Imports: 6 Imported by: 0

Documentation

Overview

Package toolapproval provides a system for approving or denying tool calls before they are executed. This allows for human-in-the-loop workflows where certain tool calls may require explicit approval.

Index

Constants

This section is empty.

Variables

View Source
var DefaultExternalToolRiskAnalyzer = NewExternalToolRiskAnalyzer(nil)

DefaultExternalToolRiskAnalyzer is a global instance for convenience

View Source
var DefaultToolRiskRegistry = initDefaultToolRiskRegistry()

DefaultToolRiskRegistry is a global instance of ToolRiskRegistry with predefined risk levels for built-in tools

Functions

This section is empty.

Types

type AlwaysDenyPolicy

type AlwaysDenyPolicy struct{}

AlwaysDenyPolicy automatically denies all tool calls

func (*AlwaysDenyPolicy) Name

func (p *AlwaysDenyPolicy) Name() string

Name returns the name of the policy

func (*AlwaysDenyPolicy) ShouldApprove

func (p *AlwaysDenyPolicy) ShouldApprove(ctx context.Context, toolCall llm.ToolCall) (bool, ApprovalResult)

ShouldApprove always returns false for the AlwaysDenyPolicy

type ApprovalResult

type ApprovalResult struct {
	// Status is the approval status
	Status ApprovalStatus

	// Reason explains why the tool call was approved, denied, or requires approval
	Reason string

	// RequiresHumanApproval indicates if human approval is required
	RequiresHumanApproval bool
}

ApprovalResult contains the result of a tool call approval decision

type ApprovalService

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

ApprovalService is responsible for approving or denying tool calls based on the configured policy.

func NewApprovalService

func NewApprovalService(policy Policy, logger *slog.Logger) *ApprovalService

NewApprovalService creates a new ApprovalService with the given policy

func (*ApprovalService) ApproveToolCall

func (s *ApprovalService) ApproveToolCall(ctx context.Context, toolCall llm.ToolCall) (bool, ApprovalResult)

ApproveToolCall determines if a tool call should be approved based on the configured policy It returns: - true if the tool call is approved and can be executed - false if the tool call is denied or requires explicit approval - an ApprovalResult with details about the decision

func (*ApprovalService) ExecuteWithApproval

func (s *ApprovalService) ExecuteWithApproval(
	ctx context.Context,
	toolCall llm.ToolCall,
	toolRegistry *llm.ToolRegistry,
	humanApprovalHandler HumanApprovalHandler,
) (string, error)

ExecuteWithApproval executes a tool call if it is approved by the policy or by a human If the policy requires human approval, the humanApprovalHandler will be called to get the human's decision.

func (*ApprovalService) GetPolicy

func (s *ApprovalService) GetPolicy() Policy

GetPolicy returns the current policy

func (*ApprovalService) SetPolicy

func (s *ApprovalService) SetPolicy(policy Policy)

SetPolicy changes the current policy

type ApprovalStatus

type ApprovalStatus string

ApprovalStatus represents the status of a tool call approval

const (
	// StatusApproved indicates the tool call was approved
	StatusApproved ApprovalStatus = "approved"

	// StatusDenied indicates the tool call was denied
	StatusDenied ApprovalStatus = "denied"

	// StatusPending indicates the tool call requires explicit approval
	StatusPending ApprovalStatus = "pending"
)

type AutoApprovePolicy

type AutoApprovePolicy struct{}

AutoApprovePolicy automatically approves all tool calls

func (*AutoApprovePolicy) Name

func (p *AutoApprovePolicy) Name() string

Name returns the name of the policy

func (*AutoApprovePolicy) ShouldApprove

func (p *AutoApprovePolicy) ShouldApprove(ctx context.Context, toolCall llm.ToolCall) (bool, ApprovalResult)

ShouldApprove always returns true for the AutoApprovePolicy

type ExternalToolRiskAnalyzer added in v0.0.2

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

ExternalToolRiskAnalyzer is responsible for analyzing and assigning risk levels to external tools that aren't explicitly rated in the DefaultToolRiskRegistry

func NewExternalToolRiskAnalyzer added in v0.0.2

func NewExternalToolRiskAnalyzer(logger *slog.Logger) *ExternalToolRiskAnalyzer

NewExternalToolRiskAnalyzer creates a new analyzer for external tools

func (*ExternalToolRiskAnalyzer) AnalyzeToolRisk added in v0.0.2

func (a *ExternalToolRiskAnalyzer) AnalyzeToolRisk(
	toolName string,
	serverName string,
	description string,
) RiskLevel

AnalyzeToolRisk analyzes a tool and returns its estimated risk level based on tool name, description, and other available information

func (*ExternalToolRiskAnalyzer) ClearCache added in v0.0.2

func (a *ExternalToolRiskAnalyzer) ClearCache()

ClearCache clears the analyzer's cache

type ExternalToolRiskConfig added in v0.0.2

type ExternalToolRiskConfig struct {
	// ServerName is the name of the MCP server
	ServerName string `yaml:"server_name"`

	// Tools is a map of tool names to risk levels
	Tools map[string]string `yaml:"tools"`

	// DefaultRiskLevel is the default risk level for tools from this server
	DefaultRiskLevel string `yaml:"default_risk_level"`
}

ExternalToolRiskConfig represents a configuration for external tool risk levels

func (*ExternalToolRiskConfig) GetRiskLevel added in v0.0.2

func (c *ExternalToolRiskConfig) GetRiskLevel(toolName string) RiskLevel

GetRiskLevel returns the risk level for a specific tool

type HumanApprovalHandler

type HumanApprovalHandler func(ctx context.Context, toolCall llm.ToolCall, result ApprovalResult) (bool, error)

HumanApprovalHandler defines a callback function for handling human approval requests It should return: - true if the human approved the tool call - false if the human denied the tool call - an error if there was a problem getting the human's decision

type Policy

type Policy interface {
	// Name returns the name of the policy
	Name() string

	// ShouldApprove determines if a tool call should be approved automatically
	// or requires explicit approval. It returns:
	// - true if the tool call is approved
	// - false if the tool call is denied or requires explicit approval
	// - an ApprovalResult with details about the decision
	ShouldApprove(ctx context.Context, toolCall llm.ToolCall) (bool, ApprovalResult)
}

Policy defines the interface for tool call approval policies. A policy determines whether a tool call should be auto-approved, denied, or requires explicit approval.

func PolicyFactory

func PolicyFactory(name string, logger *slog.Logger) (Policy, error)

PolicyFactory creates a policy by name

type RiskLevel added in v0.0.2

type RiskLevel int

RiskLevel represents the risk level of a tool

const (
	// RiskLevelLow represents a low-risk tool that can be auto-approved in most cases
	RiskLevelLow RiskLevel = iota

	// RiskLevelMedium represents a medium-risk tool that may require approval
	// depending on the policy configuration
	RiskLevelMedium

	// RiskLevelHigh represents a high-risk tool that should require explicit approval
	RiskLevelHigh

	// RiskLevelUnknown represents a tool with an unknown risk level
	// This is used for tools that haven't been explicitly rated
	RiskLevelUnknown
)

func AnalyzeExternalTool added in v0.0.2

func AnalyzeExternalTool(
	toolName string,
	serverName string,
	description string,
	analyzer *ExternalToolRiskAnalyzer,
) RiskLevel

AnalyzeExternalTool analyzes an external tool and returns its risk level It first checks if the tool has an explicit risk level in the DefaultToolRiskRegistry If not, it uses the ExternalToolRiskAnalyzer to estimate the risk level

func RiskLevelFromString added in v0.0.2

func RiskLevelFromString(s string) RiskLevel

RiskLevelFromString converts a string to a RiskLevel

func (RiskLevel) String added in v0.0.2

func (r RiskLevel) String() string

String returns a string representation of the risk level

type SmartPolicy

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

SmartPolicy makes decisions based on risk levels of tools It automatically approves tools below a certain risk threshold and requires human approval for tools above the threshold.

func NewSmartPolicy

func NewSmartPolicy(logger *slog.Logger, options ...SmartPolicyOption) *SmartPolicy

NewSmartPolicy creates a new SmartPolicy with the given options

func (*SmartPolicy) Name

func (p *SmartPolicy) Name() string

Name returns the name of the policy

func (*SmartPolicy) ShouldApprove

func (p *SmartPolicy) ShouldApprove(ctx context.Context, toolCall llm.ToolCall) (bool, ApprovalResult)

ShouldApprove implements a smart approval policy based on tool risk levels Tools with risk levels below or equal to the threshold are auto-approved Tools with risk levels above the threshold require human approval

type SmartPolicyOption added in v0.0.2

type SmartPolicyOption func(*SmartPolicy)

SmartPolicyOption is a functional option for configuring SmartPolicy

func WithRiskRegistry added in v0.0.2

func WithRiskRegistry(registry *ToolRiskRegistry) SmartPolicyOption

WithRiskRegistry sets the risk registry for the SmartPolicy

func WithRiskThreshold added in v0.0.2

func WithRiskThreshold(threshold RiskLevel) SmartPolicyOption

WithRiskThreshold sets the risk threshold for the SmartPolicy

type ToolRegistryWrapper

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

ToolRegistryWrapper wraps a ToolRegistry and adds approval functionality

func NewToolRegistryWrapper

func NewToolRegistryWrapper(
	toolRegistry *llm.ToolRegistry,
	approvalSvc *ApprovalService,
	logger *slog.Logger,
) *ToolRegistryWrapper

NewToolRegistryWrapper creates a new ToolRegistryWrapper

func (*ToolRegistryWrapper) ExecuteTool

func (w *ToolRegistryWrapper) ExecuteTool(toolCall llm.ToolCall) (string, error)

ExecuteTool executes a tool call if it is approved

func (*ToolRegistryWrapper) GetTools

func (w *ToolRegistryWrapper) GetTools() []llm.Tool

GetTools returns all registered tools from the wrapped registry

func (*ToolRegistryWrapper) RegisterTool

func (w *ToolRegistryWrapper) RegisterTool(tool llm.Tool, executor llm.ToolExecutor)

RegisterTool adds a tool to the wrapped registry

func (*ToolRegistryWrapper) SetHumanApprovalHandler

func (w *ToolRegistryWrapper) SetHumanApprovalHandler(handler HumanApprovalHandler)

SetHumanApprovalHandler sets the handler for human approval

type ToolRiskRegistry added in v0.0.2

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

ToolRiskRegistry maintains a mapping of tool names to risk levels

func NewToolRiskRegistry added in v0.0.2

func NewToolRiskRegistry(defaultRiskLevel RiskLevel) *ToolRiskRegistry

NewToolRiskRegistry creates a new ToolRiskRegistry with the given default risk level

func (*ToolRiskRegistry) GetDefaultRiskLevel added in v0.0.2

func (r *ToolRiskRegistry) GetDefaultRiskLevel() RiskLevel

GetDefaultRiskLevel returns the default risk level

func (*ToolRiskRegistry) GetRiskLevel added in v0.0.2

func (r *ToolRiskRegistry) GetRiskLevel(toolName string) RiskLevel

GetRiskLevel returns the risk level for a tool If the tool is not explicitly rated, it returns the default risk level

func (*ToolRiskRegistry) SetDefaultRiskLevel added in v0.0.2

func (r *ToolRiskRegistry) SetDefaultRiskLevel(riskLevel RiskLevel)

SetDefaultRiskLevel changes the default risk level for tools not explicitly rated

func (*ToolRiskRegistry) SetRiskLevel added in v0.0.2

func (r *ToolRiskRegistry) SetRiskLevel(toolName string, riskLevel RiskLevel)

SetRiskLevel sets the risk level for a tool

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL