tooldiscovery

package
v0.646.4 Latest Latest
Warning

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

Go to latest
Published: Aug 17, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Entry

type Entry struct {
	Tool     tools.BaseTool
	Metadata ToolMetadata
}

Entry holds a registered tool together with its resolved metadata. Tool is nil for catalog-only entries (e.g. MCP tools reachable exclusively through the gateway's remote executor).

type PolicyConfig

type PolicyConfig struct {
	Mode             PolicyMode
	MaxDirectTools   int
	NonDeferredTools []string // tool names always kept visible
	DeferredSources  []string // source labels deferred by default
}

PolicyConfig parameterises the selection policy.

func DefaultPolicyConfig

func DefaultPolicyConfig() PolicyConfig

DefaultPolicyConfig returns conservative defaults.

type PolicyMode

type PolicyMode string

PolicyMode controls when deferred tool selection is active.

const (
	// ModeAuto activates discovery when total tool count exceeds MaxDirectTools.
	ModeAuto PolicyMode = "auto"
	// ModeAlways forces discovery mode regardless of tool count.
	ModeAlways PolicyMode = "always"
	// ModeOff disables discovery — all tools are always visible.
	ModeOff PolicyMode = "off"
)

type Registry

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

Registry indexes all available tools, resolves aliases, and tracks per-session discovered/visible state.

func BuildRegistry

func BuildRegistry(allTools []tools.BaseTool, nonDeferredNames map[string]bool) *Registry

BuildRegistry assembles a Registry from a flat tool slice, classifying each tool by source based on its name prefix and optionally implemented metadata.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty Registry.

func (*Registry) All

func (r *Registry) All() []Entry

All returns all registered entries.

func (*Registry) AllTools

func (r *Registry) AllTools() []tools.BaseTool

AllTools returns all registered live tools (catalog-only entries are skipped).

func (*Registry) DiscoveredTools

func (r *Registry) DiscoveredTools() []tools.BaseTool

DiscoveredTools returns all live tools marked as discovered.

func (*Registry) ExecuteTool added in v0.646.4

func (r *Registry) ExecuteTool(ctx context.Context, nameOrAlias string, params map[string]interface{}) (tools.ToolResponse, error)

ExecuteTool runs any registered tool by canonical name or alias. Live tools are executed directly; catalog-only entries are routed to the remote executor (typically the MCP gateway). The executed tool is marked as discovered so subsequent turns can expose it directly.

func (*Registry) GetEntry

func (r *Registry) GetEntry(name string) (Entry, bool)

GetEntry returns the full Entry for a canonical name.

func (*Registry) HasRemoteEntries added in v0.646.4

func (r *Registry) HasRemoteEntries() bool

HasRemoteEntries reports whether the registry holds catalog-only entries that are only reachable through tool_search + the remote executor.

func (*Registry) IsDiscovered

func (r *Registry) IsDiscovered(name string) bool

IsDiscovered reports whether a tool has been surfaced via tool_search.

func (*Registry) MarkDiscovered

func (r *Registry) MarkDiscovered(name string)

MarkDiscovered marks a tool as discovered in the current session.

func (*Registry) Register

func (r *Registry) Register(t tools.BaseTool, source ToolSource, nonDeferred bool) error

Register adds or updates a tool in the registry (upsert by canonical name). source and nonDeferred are used when the tool does not implement ToolMetadataProvider.

func (*Registry) RegisterCatalogEntry added in v0.646.4

func (r *Registry) RegisterCatalogEntry(meta ToolMetadata) error

RegisterCatalogEntry adds a metadata-only entry (no local BaseTool). These entries are searchable and executable through the remote executor.

func (*Registry) Resolve

func (r *Registry) Resolve(nameOrAlias string) tools.BaseTool

Resolve returns the tool for name or alias, nil if not found or if the entry is catalog-only (no local BaseTool).

func (*Registry) Search

func (r *Registry) Search(query string, limit int) []SearchResult

Search returns up to limit tools ranked by lexical relevance to query. Ranking uses a simple term-frequency + field-weight scoring over name, aliases, server name, description, and parameter names.

func (*Registry) SetRemoteExecutor added in v0.646.4

func (r *Registry) SetRemoteExecutor(fn RemoteToolExecutor)

SetRemoteExecutor wires the executor used for catalog-only entries.

func (*Registry) SyncCatalogEntries added in v0.646.4

func (r *Registry) SyncCatalogEntries(metas []ToolMetadata)

SyncCatalogEntries replaces every catalog-only (Tool == nil) entry with the provided set. Names that already have a live tool registered are skipped so directly-exposed tools (e.g. gateway favorites) always win. Discovered state is preserved because it is keyed by canonical name.

type RegistrySearchAdapter

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

RegistrySearchAdapter wraps *Registry to satisfy tools.ToolSearchProvider. This breaks the import cycle: tools imports no tooldiscovery, tooldiscovery imports tools, and the adapter lives in tooldiscovery.

func NewRegistrySearchAdapter

func NewRegistrySearchAdapter(reg *Registry) *RegistrySearchAdapter

NewRegistrySearchAdapter wraps reg as a tools.ToolSearchProvider.

func (*RegistrySearchAdapter) MarkDiscovered

func (a *RegistrySearchAdapter) MarkDiscovered(name string)

MarkDiscovered implements tools.ToolSearchProvider.

func (*RegistrySearchAdapter) SearchTools

func (a *RegistrySearchAdapter) SearchTools(query string, limit int) []tools.ToolSearchEntry

SearchTools implements tools.ToolSearchProvider.

type RemoteToolExecutor added in v0.646.4

type RemoteToolExecutor func(ctx context.Context, serverName, toolName string, params map[string]interface{}) (string, error)

RemoteToolExecutor executes tools that have no local BaseTool, such as MCP catalog entries that live behind the gateway. It receives the server name, the tool name on that server, and the raw parameters.

type SearchResult

type SearchResult struct {
	CanonicalName string
	Aliases       []string
	ServerName    string
	Source        ToolSource
	Description   string
	Score         float64
}

SearchResult is a single match from a tool search query.

type SelectionPolicy

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

SelectionPolicy decides which tools are immediately visible and which are deferred.

func NewSelectionPolicy

func NewSelectionPolicy(cfg PolicyConfig) *SelectionPolicy

NewSelectionPolicy creates a SelectionPolicy from cfg.

func (*SelectionPolicy) Apply

func (p *SelectionPolicy) Apply(reg *Registry, toolSearch tools.BaseTool) []tools.BaseTool

Apply returns the visible tool slice given the full set in the registry. If toolSearch is non-nil it is prepended to the visible set when discovery mode is active so the model can always find deferred tools. When the registry holds catalog-only entries (remote MCP tools) tool_search is the only way to reach them, so it is included even below the activation threshold.

func (*SelectionPolicy) IsDeferred

func (p *SelectionPolicy) IsDeferred(e Entry) bool

IsDeferred reports whether a given entry should be hidden initially.

type ToolMetadata

type ToolMetadata struct {
	CanonicalName string
	Aliases       []string
	ServerName    string
	ToolName      string
	Source        ToolSource
	Category      string
	// Description and Parameters back catalog-only entries (no local BaseTool,
	// e.g. MCP tools reachable only through the gateway). They are ignored when
	// a live tool is registered, whose Info() takes precedence.
	Description string
	Parameters  map[string]any
	// NonDeferred means this tool is always visible regardless of the threshold.
	NonDeferred bool
	// Priority controls ordering within a category (higher = more important).
	Priority int
}

ToolMetadata carries optional discovery metadata for a BaseTool.

type ToolMetadataProvider

type ToolMetadataProvider interface {
	ToolMetadata() ToolMetadata
}

ToolMetadataProvider is an optional interface a BaseTool can implement to expose richer discovery metadata without changing the core BaseTool contract.

type ToolSource

type ToolSource string

ToolSource identifies which subsystem provided a tool.

const (
	SourceCore     ToolSource = "core"
	SourceMCP      ToolSource = "mcp"
	SourceInternal ToolSource = "internal"
	SourceLua      ToolSource = "lua"
	SourceMesnada  ToolSource = "mesnada"
	SourceRAG      ToolSource = "rag"
	SourceGateway  ToolSource = "gateway"
)

func ClassifySource added in v0.646.4

func ClassifySource(name string) ToolSource

ClassifySource infers the ToolSource from the tool name. The set of agent-native tools is sourced from tools.IsBuiltinTool so this classifier and the MCP gateway share a single source of truth: any built-in tool stays a directly-visible source and is never deferred as an MCP tool. Real MCP tools follow the "<server>_<toolname>" convention established in mcp-tools.go.

Jump to

Keyboard shortcuts

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