shuttle

package
v1.0.2 Latest Latest
Warning

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

 Go to latest Published: Jan 15, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Copyright 2026 Teradata

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Count 

func Count() int

Count returns the number of registered tools in the global registry.

func List 

func List() []string

List returns all registered tool names from the global registry.

func Register 

func Register(tool Tool)

Register registers a tool in the global registry.

func Unregister 

func Unregister(name string)

Unregister removes a tool from the global registry.

Types

type ContactHumanConfig 

type ContactHumanConfig struct {
	Store        HumanRequestStore
	Notifier     Notifier
	Timeout      time.Duration        // Default timeout for requests (default: 5 minutes)
	PollInterval time.Duration        // How often to check for responses (default: 1 second)
	Tracer       observability.Tracer // Tracer for observability (default: NoOpTracer)
	Logger       *zap.Logger          // Logger for structured logging (default: NoOp logger)
}

ContactHumanConfig configures the ContactHumanTool.

type ContactHumanTool 

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

ContactHumanTool provides human-in-the-loop capabilities for agents. Implements 12-Factor Agent Compliance (Factor 7: Human Oversight & Approval).

Use cases: - Approval workflows (e.g., "Should I delete this data?") - High-stakes decisions (e.g., "Confirm this financial transaction") - Ambiguity resolution (e.g., "Which interpretation is correct?") - Quality gates (e.g., "Review this generated code before deployment")

func NewContactHumanTool 

func NewContactHumanTool(config ContactHumanConfig) *ContactHumanTool

NewContactHumanTool creates a new human-in-the-loop tool.

func (*ContactHumanTool) Backend 

func (t *ContactHumanTool) Backend() string

func (*ContactHumanTool) Description 

func (t *ContactHumanTool) Description() string

Description returns the tool description. Deprecated: Description loaded from PromptRegistry (prompts/tools/human.yaml). This fallback is used only when prompts are not configured.

func (*ContactHumanTool) Execute 

func (t *ContactHumanTool) Execute(ctx context.Context, params map[string]interface{}) (*Result, error)

func (*ContactHumanTool) InputSchema 

func (t *ContactHumanTool) InputSchema() *JSONSchema

func (*ContactHumanTool) Name 

func (t *ContactHumanTool) Name() string

type Error 

type Error struct {
	// Code is a machine-readable error code
	Code string

	// Message is a human-readable error message
	Message string

	// Details provides additional error context
	Details map[string]interface{}

	// Retryable indicates if the operation can be retried
	Retryable bool

	// Suggestion provides a suggestion for fixing the error
	Suggestion string
}

Error represents a tool execution error with structured information.

type Executor 

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

Executor executes tools with tracking and error handling.

func NewExecutor 

func NewExecutor(registry *Registry) *Executor

NewExecutor creates a new tool executor.

func (*Executor) Execute 

func (e *Executor) Execute(ctx context.Context, toolName string, params map[string]interface{}) (*Result, error)

Execute executes a tool by name with the given parameters.

func (*Executor) ExecuteWithTool 

func (e *Executor) ExecuteWithTool(ctx context.Context, tool Tool, params map[string]interface{}) (*Result, error)

ExecuteWithTool executes a specific tool instance (not from registry).

func (*Executor) ListAvailableTools 

func (e *Executor) ListAvailableTools() []Tool

ListAvailableTools returns all tools available in the executor's registry.

func (*Executor) ListToolsByBackend 

func (e *Executor) ListToolsByBackend(backend string) []Tool

ListToolsByBackend returns all tools for a specific backend.

func (*Executor) SetMCPManager 

func (e *Executor) SetMCPManager(manager MCPManager)

SetMCPManager configures the MCP manager for dynamic MCP tool registration.

func (*Executor) SetPermissionChecker 

func (e *Executor) SetPermissionChecker(checker *PermissionChecker)

SetPermissionChecker configures permission checking for tool execution.

func (*Executor) SetSQLResultStore 

func (e *Executor) SetSQLResultStore(sqlStore *storage.SQLResultStore)

SetSQLResultStore configures SQL result store for queryable large SQL results.

func (*Executor) SetSharedMemory 

func (e *Executor) SetSharedMemory(sharedMemory *storage.SharedMemoryStore, threshold int64)

SetSharedMemory configures shared memory for large result handling.

func (*Executor) SetToolRegistry 

func (e *Executor) SetToolRegistry(registry ToolRegistry)

SetToolRegistry configures the tool registry for dynamic tool discovery. When a tool is not found in the local registry, the executor will check the tool registry and dynamically register MCP tools if found.

type HumanRequest 

type HumanRequest struct {
	ID          string                 `json:"id"`
	AgentID     string                 `json:"agent_id"`
	SessionID   string                 `json:"session_id"`
	Question    string                 `json:"question"`
	Context     map[string]interface{} `json:"context"`
	RequestType string                 `json:"request_type"` // "approval", "decision", "input", "review"
	Priority    string                 `json:"priority"`     // "low", "normal", "high", "critical"
	Timeout     time.Duration          `json:"timeout"`
	CreatedAt   time.Time              `json:"created_at"`
	ExpiresAt   time.Time              `json:"expires_at"`

	// Response fields (populated when human responds)
	Status       string                 `json:"status"` // "pending", "approved", "rejected", "timeout", "responded"
	Response     string                 `json:"response"`
	ResponseData map[string]interface{} `json:"response_data"`
	RespondedAt  *time.Time             `json:"responded_at"`
	RespondedBy  string                 `json:"responded_by"`
}

HumanRequest represents a request for human input.

type HumanRequestStore 

type HumanRequestStore interface {
	// Store saves a new human request
	Store(ctx context.Context, req *HumanRequest) error

	// Get retrieves a human request by ID
	Get(ctx context.Context, id string) (*HumanRequest, error)

	// Update updates an existing human request
	Update(ctx context.Context, req *HumanRequest) error

	// List returns all pending requests (for human review interface)
	ListPending(ctx context.Context) ([]*HumanRequest, error)

	// ListBySession returns all requests for a session
	ListBySession(ctx context.Context, sessionID string) ([]*HumanRequest, error)
}

HumanRequestStore manages storage and retrieval of human requests.

type InMemoryHumanRequestStore 

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

InMemoryHumanRequestStore provides an in-memory implementation of HumanRequestStore. Suitable for testing and single-instance deployments.

func NewInMemoryHumanRequestStore 

func NewInMemoryHumanRequestStore() *InMemoryHumanRequestStore

NewInMemoryHumanRequestStore creates a new in-memory store.

func (*InMemoryHumanRequestStore) Get 

func (s *InMemoryHumanRequestStore) Get(ctx context.Context, id string) (*HumanRequest, error)

func (*InMemoryHumanRequestStore) ListBySession 

func (s *InMemoryHumanRequestStore) ListBySession(ctx context.Context, sessionID string) ([]*HumanRequest, error)

func (*InMemoryHumanRequestStore) ListPending 

func (s *InMemoryHumanRequestStore) ListPending(ctx context.Context) ([]*HumanRequest, error)

func (*InMemoryHumanRequestStore) RespondToRequest 

func (s *InMemoryHumanRequestStore) RespondToRequest(ctx context.Context, requestID, status, response, respondedBy string, responseData map[string]interface{}) error

RespondToRequest updates a human request with a response. This is called by the human review interface (CLI, Web UI, API).

func (*InMemoryHumanRequestStore) Store 

func (s *InMemoryHumanRequestStore) Store(ctx context.Context, req *HumanRequest) error

func (*InMemoryHumanRequestStore) Update 

func (s *InMemoryHumanRequestStore) Update(ctx context.Context, req *HumanRequest) error

type InstrumentedExecutor 

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

InstrumentedExecutor wraps an Executor with observability instrumentation. It captures detailed traces and metrics for every tool execution, including: - Tool name and parameters - Execution duration and success/failure - Result data and errors - Backend information

This wrapper is transparent and can wrap any Executor.

func NewInstrumentedExecutor 

func NewInstrumentedExecutor(executor *Executor, tracer observability.Tracer) *InstrumentedExecutor

NewInstrumentedExecutor creates a new instrumented tool executor.

func (*InstrumentedExecutor) Execute 

func (e *InstrumentedExecutor) Execute(ctx context.Context, toolName string, params map[string]interface{}) (*Result, error)

Execute executes a tool by name with observability instrumentation.

func (*InstrumentedExecutor) ExecuteWithTool 

func (e *InstrumentedExecutor) ExecuteWithTool(ctx context.Context, tool Tool, params map[string]interface{}) (*Result, error)

ExecuteWithTool executes a specific tool instance with observability.

func (*InstrumentedExecutor) ListAvailableTools 

func (e *InstrumentedExecutor) ListAvailableTools() []Tool

ListAvailableTools delegates to the underlying executor.

func (*InstrumentedExecutor) ListToolsByBackend 

func (e *InstrumentedExecutor) ListToolsByBackend(backend string) []Tool

ListToolsByBackend delegates to the underlying executor.

type JSONNotifier 

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

JSONNotifier sends notifications as JSON to a configured endpoint (webhook).

func NewJSONNotifier 

func NewJSONNotifier(webhookURL string) *JSONNotifier

NewJSONNotifier creates a new JSON webhook notifier.

func (*JSONNotifier) Notify 

func (n *JSONNotifier) Notify(ctx context.Context, req *HumanRequest) error

type JSONSchema 

type JSONSchema struct {
	Type        string                 `json:"type"`
	Description string                 `json:"description,omitempty"`
	Properties  map[string]*JSONSchema `json:"properties,omitempty"`
	Required    []string               `json:"required,omitempty"`
	Items       *JSONSchema            `json:"items,omitempty"`
	Enum        []interface{}          `json:"enum,omitempty"`
	Default     interface{}            `json:"default,omitempty"`
	Format      string                 `json:"format,omitempty"`
	Pattern     string                 `json:"pattern,omitempty"`
	Minimum     *float64               `json:"minimum,omitempty"`
	Maximum     *float64               `json:"maximum,omitempty"`
	MinLength   *int                   `json:"minLength,omitempty"`
	MaxLength   *int                   `json:"maxLength,omitempty"`
}

JSONSchema represents a JSON Schema for tool parameters. This follows the JSON Schema spec for type definitions.

func FromJSON 

func FromJSON(data []byte) (*JSONSchema, error)

FromJSON creates a JSONSchema from JSON bytes.

func NewArraySchema 

func NewArraySchema(description string, items *JSONSchema) *JSONSchema

NewArraySchema creates a new array schema.

func NewBooleanSchema 

func NewBooleanSchema(description string) *JSONSchema

NewBooleanSchema creates a new boolean schema.

func NewNumberSchema 

func NewNumberSchema(description string) *JSONSchema

NewNumberSchema creates a new number schema.

func NewObjectSchema 

func NewObjectSchema(description string, properties map[string]*JSONSchema, required []string) *JSONSchema

NewObjectSchema creates a new object schema with the given properties.

func NewStringSchema 

func NewStringSchema(description string) *JSONSchema

NewStringSchema creates a new string schema.

func NormalizeSchema 

func NormalizeSchema(schema *JSONSchema) *JSONSchema

NormalizeSchema ensures a JSON Schema complies with JSON Schema draft 2020-12. This is critical for Bedrock Claude models which strictly validate schemas.

Common issues fixed: - Object types with nil properties -> empty map {} - Missing type fields -> inferred from structure - Nested objects with nil properties -> recursively normalized

func (*JSONSchema) MarshalJSON 

func (s *JSONSchema) MarshalJSON() ([]byte, error)

MarshalJSON implements custom JSON marshaling to ensure Bedrock compliance. Object types must have "properties": {} (not omitted) per JSON Schema 2020-12.

func (*JSONSchema) ToJSON 

func (s *JSONSchema) ToJSON() ([]byte, error)

ToJSON converts the schema to JSON bytes.

func (*JSONSchema) WithDefault 

func (s *JSONSchema) WithDefault(value interface{}) *JSONSchema

WithDefault adds a default value to the schema.

func (*JSONSchema) WithEnum 

func (s *JSONSchema) WithEnum(values ...interface{}) *JSONSchema

WithEnum adds enum values to the schema.

func (*JSONSchema) WithFormat 

func (s *JSONSchema) WithFormat(format string) *JSONSchema

WithFormat adds a format constraint to the schema.

func (*JSONSchema) WithLength 

func (s *JSONSchema) WithLength(minLen, maxLen *int) *JSONSchema

WithLength adds length constraints to the schema.

func (*JSONSchema) WithPattern 

func (s *JSONSchema) WithPattern(pattern string) *JSONSchema

WithPattern adds a pattern constraint to the schema.

func (*JSONSchema) WithRange 

func (s *JSONSchema) WithRange(min, max *float64) *JSONSchema

WithRange adds min/max constraints to the schema.

type MCPManager 

type MCPManager interface {
	GetClient(serverName string) (interface{}, error)
}

MCPManager is an interface for getting MCP clients. This avoids import cycles with pkg/mcp/manager.

type MockTool 

type MockTool struct {
	MockName        string
	MockDescription string
	MockSchema      *JSONSchema
	MockBackend     string
	MockExecute     func(ctx context.Context, params map[string]interface{}) (*Result, error)
	ExecuteCount    int
	LastParams      map[string]interface{}
	// contains filtered or unexported fields
}

MockTool is a mock implementation of the Tool interface for testing. It allows tests to control all tool behavior and verify interactions. Thread-safe for concurrent testing.

func (*MockTool) Backend 

func (m *MockTool) Backend() string

Backend returns the mock backend type.

func (*MockTool) Description 

func (m *MockTool) Description() string

Description returns the mock tool description.

func (*MockTool) Execute 

func (m *MockTool) Execute(ctx context.Context, params map[string]interface{}) (*Result, error)

Execute runs the mock execution function.

func (*MockTool) InputSchema 

func (m *MockTool) InputSchema() *JSONSchema

InputSchema returns the mock input schema.

func (*MockTool) Name 

func (m *MockTool) Name() string

Name returns the mock tool name.

type NoOpNotifier 

type NoOpNotifier struct{}

NoOpNotifier is a no-op implementation of Notifier for testing.

func (*NoOpNotifier) Notify 

func (n *NoOpNotifier) Notify(ctx context.Context, req *HumanRequest) error

type Notifier 

type Notifier interface {
	// Notify sends a notification about a human request
	Notify(ctx context.Context, req *HumanRequest) error
}

Notifier sends notifications to humans when their input is requested.

type PermissionChecker 

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

PermissionChecker checks if a tool can be executed based on configuration.

func NewPermissionChecker 

func NewPermissionChecker(config PermissionConfig) *PermissionChecker

NewPermissionChecker creates a new permission checker.

func (*PermissionChecker) CheckPermission 

func (pc *PermissionChecker) CheckPermission(ctx context.Context, toolName string, params map[string]interface{}) error

CheckPermission checks if a tool can be executed. Returns nil if allowed, error if denied.

func (*PermissionChecker) IsToolAllowed 

func (pc *PermissionChecker) IsToolAllowed(toolName string) bool

IsToolAllowed returns true if a tool is explicitly allowed (whitelist).

func (*PermissionChecker) IsToolDisabled 

func (pc *PermissionChecker) IsToolDisabled(toolName string) bool

IsToolDisabled returns true if a tool is explicitly disabled (blacklist).

func (*PermissionChecker) IsYOLOMode 

func (pc *PermissionChecker) IsYOLOMode() bool

IsYOLOMode returns true if YOLO mode is enabled.

func (*PermissionChecker) RequiresApproval 

func (pc *PermissionChecker) RequiresApproval() bool

RequiresApproval returns true if user approval is required for tools.

type PermissionConfig 

type PermissionConfig struct {
	RequireApproval bool
	YOLO            bool
	AllowedTools    []string
	DisabledTools   []string
	DefaultAction   string // "allow" or "deny"
	TimeoutSeconds  int
}

PermissionConfig holds permission configuration.

type PromptAwareTool 

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

PromptAwareTool wraps a tool and loads descriptions from PromptRegistry. Falls back to tool's native Description() if prompt not found. This enables externalized tool descriptions while maintaining backward compatibility.

func (*PromptAwareTool) Backend 

func (p *PromptAwareTool) Backend() string

Backend returns the backend type this tool requires (delegates to wrapped tool).

func (*PromptAwareTool) Description 

func (p *PromptAwareTool) Description() string

Description loads the tool description from PromptRegistry. Falls back to the wrapped tool's native Description() if: - PromptRegistry lookup fails - Prompt is not found - Prompt is empty

This ensures tools always have a valid description, even if prompts are not configured.

func (*PromptAwareTool) Execute 

func (p *PromptAwareTool) Execute(ctx context.Context, params map[string]interface{}) (*Result, error)

Execute runs the tool with given parameters (delegates to wrapped tool).

func (*PromptAwareTool) InputSchema 

func (p *PromptAwareTool) InputSchema() *JSONSchema

InputSchema returns the JSON Schema for tool parameters (delegates to wrapped tool).

func (*PromptAwareTool) Name 

func (p *PromptAwareTool) Name() string

Name returns the tool's unique identifier (delegates to wrapped tool).

type Registry 

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

Registry manages tool registration and lookup.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates a new tool registry.

func (*Registry) Count 

func (r *Registry) Count() int

Count returns the number of registered tools.

func (*Registry) Get 

func (r *Registry) Get(name string) (Tool, bool)

Get retrieves a tool by name.

func (*Registry) List 

func (r *Registry) List() []string

List returns all registered tool names.

func (*Registry) ListByBackend 

func (r *Registry) ListByBackend(backend string) []Tool

ListByBackend returns all tools for a specific backend. Pass empty string to get backend-agnostic tools.

func (*Registry) ListTools 

func (r *Registry) ListTools() []Tool

ListTools returns all registered tools.

func (*Registry) Register 

func (r *Registry) Register(tool Tool)

Register registers a tool with the registry. If a tool with the same name already exists, it will be replaced.

func (*Registry) Unregister 

func (r *Registry) Unregister(name string)

Unregister removes a tool from the registry.

type Result 

type Result struct {
	// Success indicates if the tool executed successfully
	Success bool

	// Data contains the result data (format varies by tool)
	// For small results, data is stored here directly
	// For large results, use DataReference instead
	Data interface{}

	// Error contains error information if execution failed
	Error *Error

	// Metadata contains tool-specific metadata
	Metadata map[string]interface{}

	// ExecutionTime in milliseconds
	ExecutionTimeMs int64

	// CacheHit indicates if this result came from cache
	CacheHit bool

	// DataReference points to large result data in shared memory
	// When set, Data field should contain only a brief summary
	DataReference *loomv1.DataReference
}

Result represents the outcome of tool execution.

type SQLiteConfig 

type SQLiteConfig struct {
	Path   string               // Database file path (default: ":memory:")
	Tracer observability.Tracer // Tracer for observability (default: NoOpTracer)
}

SQLiteConfig configures the SQLite store.

type SQLiteHumanRequestStore 

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

SQLiteHumanRequestStore provides persistent SQLite storage for human requests. Suitable for production deployments with request history and audit trail.

func NewSQLiteHumanRequestStore 

func NewSQLiteHumanRequestStore(config SQLiteConfig) (*SQLiteHumanRequestStore, error)

NewSQLiteHumanRequestStore creates a new SQLite-backed human request store.

func (*SQLiteHumanRequestStore) Close 

func (s *SQLiteHumanRequestStore) Close() error

Close closes the database connection.

func (*SQLiteHumanRequestStore) Get 

func (s *SQLiteHumanRequestStore) Get(ctx context.Context, id string) (*HumanRequest, error)

Get retrieves a human request by ID.

func (*SQLiteHumanRequestStore) ListBySession 

func (s *SQLiteHumanRequestStore) ListBySession(ctx context.Context, sessionID string) ([]*HumanRequest, error)

ListBySession returns all requests for a session.

func (*SQLiteHumanRequestStore) ListPending 

func (s *SQLiteHumanRequestStore) ListPending(ctx context.Context) ([]*HumanRequest, error)

ListPending returns all pending requests.

func (*SQLiteHumanRequestStore) RespondToRequest 

func (s *SQLiteHumanRequestStore) RespondToRequest(ctx context.Context, requestID, status, response, respondedBy string, responseData map[string]interface{}) error

RespondToRequest updates a human request with a response.

func (*SQLiteHumanRequestStore) Store 

func (s *SQLiteHumanRequestStore) Store(ctx context.Context, req *HumanRequest) error

Store saves a new human request to the database.

func (*SQLiteHumanRequestStore) Update 

func (s *SQLiteHumanRequestStore) Update(ctx context.Context, req *HumanRequest) error

Update updates an existing human request.

type Tool 

type Tool interface {
	// Name returns the tool's unique identifier
	Name() string

	// Description returns a human-readable description for LLM context
	Description() string

	// InputSchema returns the JSON Schema for tool parameters
	InputSchema() *JSONSchema

	// Execute runs the tool with given parameters
	Execute(ctx context.Context, params map[string]interface{}) (*Result, error)

	// Backend returns the backend type this tool requires (e.g., "teradata", "postgres", "api")
	// Empty string means the tool is backend-agnostic
	Backend() string
}

Tool defines the interface for executable tools (shuttles) in the agent framework. Tools are the primary mechanism for agents to interact with backends and perform domain-specific operations. Each tool encapsulates a single capability.

Why "shuttle"? Tools "shuttle" data and execution between the LLM and the backend, like a shuttle in weaving carries thread back and forth across the loom.

func Get 

func Get(name string) (Tool, bool)

Get retrieves a tool from the global registry.

func ListByBackend 

func ListByBackend(backend string) []Tool

ListByBackend returns all tools for a specific backend from the global registry.

func ListTools 

func ListTools() []Tool

ListTools returns all registered tools from the global registry.

func MustGet 

func MustGet(name string) Tool

MustGet retrieves a tool from the global registry and panics if not found. This is useful for testing and initialization code.

func NewPromptAwareTool 

func NewPromptAwareTool(tool Tool, registry prompts.PromptRegistry, promptKey string) Tool

NewPromptAwareTool wraps a tool with PromptRegistry-based descriptions. If registry is nil, returns the original tool unchanged (no wrapping overhead).

Example: 

registry := prompts.NewFileRegistry("./prompts")
tool := builtin.NewHTTPClientTool()
wrapped := shuttle.NewPromptAwareTool(tool, registry, "tools.http_request")
description := wrapped.Description() // Loads from prompts/tools/http_request.yaml

type ToolRegistry 

type ToolRegistry interface {
	Search(ctx context.Context, req *loomv1.SearchToolsRequest) (*loomv1.SearchToolsResponse, error)
}

ToolRegistry is an interface for dynamic tool discovery. This avoids import cycles with pkg/tools/registry.

Source Files

View all Source files

Directories

Path Synopsis
Package metadata provides rich, self-describing tool metadata loading.
 Package metadata provides rich, self-describing tool metadata loading.

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.