tools

type ErrToolDenied ¶

type ErrToolDenied struct {
	CallName string
	Reason   string
}

ErrToolDenied is returned by ExecuteCall when a ToolApprover rejects a call. The Reason is returned to the model as the tool result content so the model can explain to the user why the action was blocked.

func (e *ErrToolDenied) Error() string

type HandoffSignal ¶

type HandoffSignal struct {
	Target string // Agent or workflow name to hand off to
}

HandoffSignal is returned by a tool handler to signal handoff to another agent or workflow. Handoff is a tool like any other: the model calls the handoff tool with a target; the handler returns HandoffSignal{Target: "name"}; the tool loop emits a KindCustom handoff frame and exits without adding a tool result. The runner (e.g. DSL RunHandoff) then runs the target. Use this instead of encoding handoff in result content.

func (HandoffSignal) Error() string

type InputStreamOptions ¶

type InputStreamOptions struct {
	// Role used when converting streamed input to a single message.
	// Defaults to niro.RoleUser.
	Role niro.Role
}

InputStreamOptions controls behavior when falling back to non-native providers.

func DefaultInputStreamOptions() InputStreamOptions

type InputStreamingProvider ¶

type InputStreamingProvider interface {
	GenerateInputStream(ctx context.Context, req *niro.Request, input *niro.Stream) (*niro.Stream, error)
}

InputStreamingProvider is an optional provider extension for native input streaming (duplex-style) where user input arrives incrementally.

Providers that support realtime/duplex APIs may implement this directly. Core helpers will automatically prefer this path when available.

type StreamWithToolHandling ¶

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

StreamWithToolHandling wraps a Provider and executes tool calls automatically.

func NewStreamWithToolHandling(p niro.Provider, executor ToolExecutor, maxRounds int) *StreamWithToolHandling

func NewStreamWithToolHandlingOptions(p niro.Provider, executor ToolExecutor, opts ToolStreamOptions) *StreamWithToolHandling

func (swth *StreamWithToolHandling) Generate(ctx context.Context, req *niro.Request) (*niro.Stream, error)

type ToolApproval ¶

type ToolApproval struct {
	// Approved must be true for the tool call to proceed.
	Approved bool
	// Reason is fed back to the LLM as the tool result when Approved is false.
	// Provide a clear human-readable message — the model will use it to explain
	// to the user why the action was blocked.
	Reason string
}

ToolApproval is the outcome of an approval decision.

type ToolApprover ¶

type ToolApprover interface {
	Approve(ctx context.Context, call niro.ToolCall) (ToolApproval, error)
}

ToolApprover intercepts tool calls before execution for human or policy-based review. Implementations block until a decision is made. The context carries the deadline — if no decision arrives in time, context cancellation is the timeout mechanism.

Example — channel-based human approval:

type ChannelApprover struct { Requests chan ApprovalRequest }
func (a *ChannelApprover) Approve(ctx context.Context, call niro.ToolCall) (ToolApproval, error) {
	req := ApprovalRequest{Call: call, Reply: make(chan ToolApproval, 1)}
	select {
	case a.Requests <- req:
	case <-ctx.Done(): return ToolApproval{}, ctx.Err()
	}
	select {
	case dec := <-req.Reply: return dec, nil
	case <-ctx.Done():       return ToolApproval{}, ctx.Err()
	}
}

func ApproveAll() ToolApprover

func DenyAll(reason string) ToolApprover

type ToolApproverFunc ¶

type ToolApproverFunc func(ctx context.Context, call niro.ToolCall) (ToolApproval, error)

ToolApproverFunc adapts a function to the ToolApprover interface.

func (f ToolApproverFunc) Approve(ctx context.Context, call niro.ToolCall) (ToolApproval, error)

type ToolDefinition ¶

type ToolDefinition struct {
	Name        string
	Description string
	Schema      json.RawMessage
	Handler     ToolHandler
}

ToolDefinition is a high-level tool abstraction. It maps to niro.Request.Tools for providers and supports runtime execution.

func NewToolDefinition(name, description string, schema json.RawMessage, handler ToolHandler) (ToolDefinition, error)

func NewToolDefinitionAny(name, description string, schema any, handler ToolHandler) (ToolDefinition, error)

func (d ToolDefinition) ToTool() niro.Tool

func (d ToolDefinition) Validate() error

type ToolExecutionInfo ¶

type ToolExecutionInfo struct {
	Name   string
	CallID string
	Args   json.RawMessage
	Result niro.ToolResult
	Err    error
}

ToolExecutionInfo contains execution event data.

type ToolExecutor ¶

type ToolExecutor interface {
	// Execute runs the named tool with the given arguments and returns the result.
	// The executor should handle errors appropriately (e.g. tool not found, execution failure)
	Execute(ctx context.Context, name string, args json.RawMessage) (string, error)
}

ToolExecutor defines how to execute a tool call.

type ToolExecutorFunc ¶

type ToolExecutorFunc func(ctx context.Context, name string, args json.RawMessage) (string, error)

ToolExecutorFunc adapts a function to ToolExecutor interface.

func (f ToolExecutorFunc) Execute(ctx context.Context, name string, args json.RawMessage) (string, error)

type ToolHandler ¶

type ToolHandler func(ctx context.Context, args json.RawMessage) (any, error)

ToolHandler executes a tool with raw JSON args and returns any JSON-serializable value. Return string to emit plain text content directly.

type ToolLoop ¶

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

ToolLoop manages automatic tool calling loops. It reads tool call frames from a stream, executes them, and returns a new stream with the results integrated.

func NewToolLoop(executor ToolExecutor, maxRounds int) *ToolLoop

func NewToolLoopWithOptions(executor ToolExecutor, opts ToolStreamOptions) *ToolLoop

func (tl *ToolLoop) GenerateWithTools(ctx context.Context, provider niro.Provider, req *niro.Request) (*niro.Stream, error)

type ToolRuntimeHook ¶

type ToolRuntimeHook interface {
	OnToolValidate(ctx context.Context, info ToolValidationInfo)
	OnToolExecuteStart(ctx context.Context, call niro.ToolCall)
	OnToolExecuteEnd(ctx context.Context, info ToolExecutionInfo)
}

ToolRuntimeHook receives tool validation/execution lifecycle events.

type ToolSchemaValidator ¶

type ToolSchemaValidator interface {
	Validate(schema json.RawMessage, args json.RawMessage) error
}

ToolSchemaValidator validates tool call args against schema.

func CurrentToolSchemaValidator() ToolSchemaValidator

type ToolStreamOptions ¶

type ToolStreamOptions struct {
	MaxRounds       int
	Parallel        bool
	EmitToolResults bool
	ToolTimeout     time.Duration
	StreamBuffer    int
	// Approver is an optional human-in-the-loop gate.
	// When set, every tool call is passed to Approver.Approve before execution.
	// A nil Approver means all calls proceed without review.
	Approver ToolApprover
}

ToolStreamOptions controls automatic tool execution behavior.

func DefaultToolStreamOptions() ToolStreamOptions

type ToolValidationInfo ¶

type ToolValidationInfo struct {
	Name string
	Args json.RawMessage
	Err  error
}

ToolValidationInfo contains validation event data.

type ToolingProvider ¶

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

ToolingProvider is a smart provider wrapper that applies declared tools and executes tool loops with validation + hooks.

func NewToolingProvider(base niro.Provider, set *Toolset, opts ToolStreamOptions) *ToolingProvider

func (p *ToolingProvider) Generate(ctx context.Context, req *niro.Request) (*niro.Stream, error)

type Toolset ¶

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

Toolset provides a Genkit-like abstraction over tool declaration, provider wiring, validation, hooks, and execution.

func NewToolset() *Toolset

func (ts *Toolset) Apply(req *niro.Request) *niro.Request

func (ts *Toolset) Execute(ctx context.Context, name string, args json.RawMessage) (string, error)

func (ts *Toolset) ExecuteCall(ctx context.Context, call niro.ToolCall) (niro.ToolResult, error)

func (ts *Toolset) Get(name string) (ToolDefinition, bool)

func (ts *Toolset) Len() int

func (ts *Toolset) MustRegister(def ToolDefinition) *Toolset

func (ts *Toolset) Names() []string

func (ts *Toolset) Register(def ToolDefinition) error

func (ts *Toolset) Remove(name string) bool

func (ts *Toolset) Tools() []niro.Tool

func (ts *Toolset) WithApprover(a ToolApprover) *Toolset

func (ts *Toolset) WithHook(h ToolRuntimeHook) *Toolset

func (ts *Toolset) WithValidator(v ToolSchemaValidator) *Toolset