tools

type Choice struct {
	// Mode controls how the model may use tools.
	// Semantics:
	// - Any: The model may choose any available tool (or none).
	// - AllowOnly: The model may only choose from AllowedTools. If the list is empty, no tools may be used.
	// - RequireOneOf: The model must choose one of AllowedTools. If the list is empty, this effectively forbids tool use.
	Mode ChoiceMode `json:"mode"`
	// AllowedTools are tool function names that are permitted/required depending on Mode.
	AllowedTools []string `json:"allowed_tools,omitempty"`
}

type ChoiceMode string

type FunctionSchema struct {
	// Name is the name of the function to be called.
	Name string `json:"name"`
	// Description is a description of what the function does.
	Description string `json:"description"`
	// Parameters is the schema for the arguments object that the function expects.
	Parameters ValueSchema `json:"parameters"`
}

type Grammar interface {
	// contains filtered or unexported methods
}

type JSONGrammar interface {
	Grammar
	Schema() *FunctionSchema
	// SkipValidation returns true when the tool should bypass JSON validation
	// (e.g., External tools that accept arbitrary json.RawMessage parameters).
	SkipValidation() bool
}

type LarkGrammar struct{ Definition string }

type RegexGrammar struct{ Definition string }

type Result interface {
	// Label returns a short single line description of the entire tool run.
	Label() string
	// Content returns the structured content of the result.
	Content() content.Content
	// Error returns the error that occurred during the tool run, if any.
	Error() error
}

type Runner interface {
	Context() context.Context
	Toolbox() *Toolbox
	Report(status string)
}

type TextGrammar struct{}

type Tool interface {
	// Label returns a nice human readable title for the tool.
	Label() string
	// Description returns the description of the tool.
	Description() string
	// FuncName returns the function name for the tool.
	FuncName() string
	// Run runs the tool with the provided parameters.
	Run(r Runner, params json.RawMessage) Result
	// Grammar returns the grammar configuration for this tool.
	Grammar() Grammar
}

type Toolbox struct {

	// Choice controls tool selection policy for providers.
	Choice Choice
	// contains filtered or unexported fields
}

type ValueSchema struct {
	// Type specifies the data type of the value (e.g., "string", "integer", "object", "array", "boolean", "number").
	Type string `json:"type,omitempty"`
	// Description provides a brief explanation of the value or field.
	Description string `json:"description,omitempty"`
	// Items defines the schema for elements within an array. Only used when Type is "array".
	Items *ValueSchema `json:"items,omitempty"`
	// Properties defines the schema for properties within an object. Only used when Type is "object".
	// Note: We use an ordered map to preserve insertion order from callers (e.g., TS clients).
	Properties *jsonmap.Map `json:"properties,omitempty"`
	// AdditionalProperties specifies the schema for additional properties in an object, or allows/disallows them.
	// It can be a boolean (true to allow any, false to disallow) or a ValueSchema defining the type of allowed additional properties.
	// Only used when Type is "object".
	AdditionalProperties any `json:"additionalProperties,omitempty"`
	// Required lists the names of properties that must be present when Type is "object".
	Required []string `json:"required,omitempty"`
	// AnyOf specifies that the value must conform to at least one of the provided schemas.
	AnyOf []ValueSchema `json:"anyOf,omitempty"`
}