concepts

type ClientTransport interface {
	// RegisterToolProvider registers a tool provider (e.g. via the /utcp endpoint)
	// and returns the list of tools it exposes.
	RegisterToolProvider(ctx context.Context, manualProvider Provider) ([]Tool, error)

	// DeregisterToolProvider removes a previously registered provider.
	DeregisterToolProvider(ctx context.Context, manualProvider Provider) error

	// CallTool invokes a named tool with the given arguments on a specific provider.
	// It returns whatever the tool returns (often map[string]interface{} or a typed result).
	CallTool(ctx context.Context, toolName string, arguments map[string]any, toolProvider Provider, l *string) (any, error)
}

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

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

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

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

type TextTransport interface {
	ClientTransport
	SetBasePath(path string)
}

type Tool struct {
	Name                string                `json:"name"`
	Description         string                `json:"description"`
	Inputs              ToolInputOutputSchema `json:"inputs"`
	Outputs             ToolInputOutputSchema `json:"outputs"`
	Tags                []string              `json:"tags"`
	AverageResponseSize *int                  `json:"average_response_size,omitempty"`
	Provider            Provider              `json:"tool_provider"`
	Handler             ToolHandler           `json:"-"`
}

type ToolHandler func(ctx map[string]interface{}, inputs map[string]interface{}) (outputs map[string]interface{}, err error)

type ToolInputOutputSchema struct {
	Type        string                 `json:"type"`                 // e.g. "object", "array", "string"
	Properties  map[string]interface{} `json:"properties,omitempty"` // field schemas
	Required    []string               `json:"required,omitempty"`
	Description string                 `json:"description,omitempty"`
	Title       string                 `json:"title,omitempty"`
	Items       map[string]interface{} `json:"items,omitempty"` // for arrays
	Enum        []interface{}          `json:"enum,omitempty"`
	Minimum     *float64               `json:"minimum,omitempty"`
	Maximum     *float64               `json:"maximum,omitempty"`
	Format      string                 `json:"format,omitempty"` // e.g. "date-time"
}

type ToolProvider interface {
	Type() string
	Name() string
}

type ToolRepository interface {
	// SaveProviderWithTools saves a provider and its associated tools.
	SaveProviderWithTools(ctx context.Context, provider Provider, tools []Tool) error

	// RemoveProvider removes a provider and all its tools by name.
	// Returns an error if the provider does not exist.
	RemoveProvider(ctx context.Context, providerName string) error

	// RemoveTool removes a single tool by name.
	// Returns an error if the tool does not exist.
	RemoveTool(ctx context.Context, toolName string) error

	// GetTool retrieves a tool by name.
	// Returns (nil, nil) if the tool is not found.
	GetTool(ctx context.Context, toolName string) (*Tool, error)

	// GetTools returns all tools in the repository.
	GetTools(ctx context.Context) ([]Tool, error)

	// GetToolsByProvider returns all tools for a specific provider.
	// Returns (nil, nil) if the provider is not found.
	GetToolsByProvider(ctx context.Context, providerName string) ([]Tool, error)

	// GetProvider retrieves a provider by name.
	// Returns (nil, nil) if the provider is not found.
	GetProvider(ctx context.Context, providerName string) (*Provider, error)

	// GetProviders returns all providers in the repository.
	GetProviders(ctx context.Context) ([]Provider, error)
}

type ToolSearchStrategy interface {
	// SearchTools returns up to `limit` tools matching `query`.
	// A limit of 0 means “no limit” (return all matches).
	//
	// ctx carries deadlines, cancellation signals, and other request-scoped values.
	SearchTools(ctx context.Context, query string, limit int) ([]Tool, error)
}

type UtcpManual struct {
	Version string
	Tools   []Tool
	Name    string // optional, for OpenAPI-derived manuals
}