tools

type Cache interface {
	Get(key string) (any, bool)
	Set(key string, value any, ttl time.Duration)
}

type CacheKeyFunc func(toolName string, args json.RawMessage) string

type CircuitBreakerConfig struct {
	FailureThreshold int           // Failures before opening.
	SuccessThreshold int           // Successes in half-open to close.
	OpenDuration     time.Duration // How long to stay open.
}

type CircuitState int

type Logger interface {
	Printf(format string, v ...any)
}

type MetricsCollector interface {
	// RecordCall records a tool call with its outcome.
	RecordCall(toolName string, duration time.Duration, err error)
}

type Middleware func(next ToolCallFunc) ToolCallFunc

type RateLimiter interface {
	// Allow returns true if the request should proceed.
	Allow() bool
	// Wait blocks until the request can proceed or context is canceled.
	Wait(ctx context.Context) error
}

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

type RegistryOption func(*Registry)

type RetryConfig struct {
	MaxAttempts int
	InitialWait time.Duration
	MaxWait     time.Duration
	Multiplier  float64
	Retryable   func(error) bool // Returns true if error is retryable.
}

type SchemaValidator interface {
	Validate(schema json.RawMessage, data json.RawMessage) error
}

type Tool interface {
	// Name returns the unique identifier for this tool.
	Name() string

	// Description returns a human-readable description of what this tool does.
	// This is provided to the AI model to help it decide when to use the tool.
	Description() string

	// Schema returns the JSON Schema that describes the tool's parameters.
	Schema() ToolSchema

	// Call executes the tool with the given arguments.
	// The args parameter contains the raw JSON arguments from the model.
	// Returns the tool's result or an error if execution fails.
	Call(ctx context.Context, args json.RawMessage) (any, error)
}

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

type ToolContext struct {
	// ToolName is the name of the tool being called.
	ToolName string

	// CallID is a unique identifier for this invocation (if available).
	CallID string

	// Iteration is the current workflow loop iteration (if provided by caller).
	Iteration int

	// Schema is the tool's JSON schema for this invocation.
	Schema json.RawMessage

	// Metadata allows middleware to share data with each other.
	Metadata map[string]any
}

type ToolSchema struct {
	// JSONSchema is a valid JSON Schema object describing the tool's parameters.
	// Example: {"type": "object", "properties": {"location": {"type": "string"}}}
	JSONSchema json.RawMessage `json:"json_schema"`
}