// Package tools defines tool specifications (pure) and their execution functions (impure).
// Each tool is a pair: Def (pure data) + ToolFunc (impure execution).
// To add a new tool, create a file in this package and register it in the agent builder.
package tools

import "context"

// Def is the pure specification of a tool — only data, no side effects.
type Def struct {
	Name        string
	Description string
	Parameters  []Param
}

// Param describes a single parameter accepted by a tool.
type Param struct {
	Name        string
	Type        string // "string", "number", "boolean", "integer", "object", "array"
	Description string
	Required    bool
}

// Result holds the outcome of executing a tool.
type Result struct {
	Output string
	Err    error
}

// ToolFunc is the impure function that actually executes the tool.
type ToolFunc func(ctx context.Context, args map[string]any) Result

// Tool bundles a pure definition with its impure implementation.
type Tool struct {
	Def  Def
	Exec ToolFunc
}

// GetString extracts a string argument by name, returning "" if missing or wrong type.
func GetString(args map[string]any, key string) string {
	v, ok := args[key]
	if !ok {
		return ""
	}
	s, ok := v.(string)
	if !ok {
		return ""
	}
	return s
}

// GetInt extracts an integer argument by name, returning 0 if missing or wrong type.
func GetInt(args map[string]any, key string) int {
	v, ok := args[key]
	if !ok {
		return 0
	}
	switch n := v.(type) {
	case float64:
		return int(n)
	case int:
		return n
	default:
		return 0
	}
}