core

type AgentHandler func(ctx context.Context, input map[string]any) (map[string]any, error)

type AgentInfo struct {
	// AgentID is the unique identifier for the agent instance
	AgentID string

	// AgentType is the category/type of the agent (e.g., "ReactiveAgent", "PlannerAgent")
	AgentType string

	// Capabilities lists the tools/capabilities available to this agent
	Capabilities []Tool

	// Version is the agent version for compatibility tracking
	Version string

	// Metadata contains additional agent-specific information
	Metadata map[string]any
}

type AgentInterceptor func(ctx context.Context, input map[string]any, info *AgentInfo, handler AgentHandler) (map[string]any, error)

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

type BaseLLMOption func(*BaseLLM)

type BaseModule struct {
	Signature   Signature
	LLM         LLM
	DisplayName string
	ModuleType  string
	// contains filtered or unexported fields
}

type BaseOptimizer struct {
	Name string
}

type BatchEmbedder interface {
	CreateEmbeddings(ctx context.Context, inputs []string, options ...EmbeddingOption) (*BatchEmbeddingResult, error)
}

type BatchEmbeddingResult struct {
	// Embeddings for each input
	Embeddings []EmbeddingResult
	// Any error that occurred during processing
	Error error
	// Input index that caused the error (if applicable)
	ErrorIndex int
}

type BootstrapFewShot struct {
	BaseOptimizer
	MaxExamples int
}

type Capability string

type CapabilityProvider interface {
	Capabilities() []Capability
}

type ChatMessage struct {
	Role       string          `json:"role"`                  // "system"|"user"|"assistant"|"tool"
	Content    []ContentBlock  `json:"content"`               // reuse existing multimodal blocks from llm.go
	ToolCalls  []ToolCall      `json:"tool_calls,omitempty"`  // for assistant messages requesting tool calls
	ToolResult *ChatToolResult `json:"tool_result,omitempty"` // for tool role messages
}

type ChatToolResult struct {
	ToolCallID string         `json:"tool_call_id"`
	Name       string         `json:"name"`
	Content    []ContentBlock `json:"content"`
	IsError    bool           `json:"is_error,omitempty"`
}

type CloneableTool interface {
	CloneTool() Tool
}

type CompileOptions struct {
	MaxTrials int
	Teacher   *Program
}

type Composable interface {
	Module
	Compose(next Module) Module
	GetSubModules() []Module
	SetSubModules([]Module)
}

type Config struct {
	DefaultLLM       LLM
	TeacherLLM       LLM
	ConcurrencyLevel int

	// Registry configuration
	Registry *RegistryConfig `json:"registry,omitempty" yaml:"registry,omitempty"`
}

type ContentBlock struct {
	Type     FieldType `json:"type"`
	Text     string    `json:"text,omitempty"`
	Data     []byte    `json:"-"` // Raw binary data for images/audio
	MimeType string    `json:"mime_type,omitempty"`
	// Optional metadata for extensibility
	Metadata map[string]any `json:"metadata,omitempty"`
}

type ContentGenerator interface {
	GenerateWithContent(ctx context.Context, content []ContentBlock, options ...GenerateOption) (*LLMResponse, error)
}

type Dataset interface {
	// Next returns the next example in the dataset
	Next() (Example, bool)
	// Reset resets the dataset iterator
	Reset()
}

type DemoConsumer interface {
	SetDemos([]Example)
}

type DemoProvider interface {
	GetDemos() []Example
}

type Embedder interface {
	CreateEmbedding(ctx context.Context, input string, options ...EmbeddingOption) (*EmbeddingResult, error)
}

type EmbeddingOption func(*EmbeddingOptions)

type EmbeddingOptions struct {
	// Model-specific options for embedding
	Model string
	// Optional batch size for bulk embeddings
	BatchSize int
	// Additional model-specific parameters
	Params map[string]any
}

type EmbeddingResult struct {
	// The generated embedding vector
	Vector []float32
	// Token count and other metadata
	TokenCount int
	// Any model-specific metadata
	Metadata map[string]any
}

type EndpointConfig struct {
	BaseURL    string            // Base API URL
	Path       string            // Specific endpoint path
	Headers    map[string]string // Common headers
	TimeoutSec int               // Request timeout in seconds
}

type Example struct {
	Inputs  map[string]any
	Outputs map[string]any
}

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

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

type Field struct {
	Name        string
	Description string
	Prefix      string
	Type        FieldType // Default is FieldTypeText for backward compatibility
}

type FieldMetadata struct {
	Name        string       // Field name from struct tag or field name
	GoFieldName string       // Original Go struct field name for direct lookup
	Required    bool         // Whether field is required
	Description string       // Field description
	Prefix      string       // Output prefix for LLM generation
	Type        FieldType    // Field type (text, image, audio)
	GoType      reflect.Type // The actual Go type
}

type FieldOption func(*Field)

type FieldType string

type ForwardFactory func(modules map[string]Module) func(context.Context, map[string]any) (map[string]any, error)

type FunctionCaller interface {
	GenerateWithFunctions(ctx context.Context, prompt string, functions []map[string]any, options ...GenerateOption) (map[string]any, error)
}

type GenerateOption func(*GenerateOptions)

type GenerateOptions struct {
	MaxTokens        int
	Temperature      float64
	TopP             float64
	PresencePenalty  float64
	FrequencyPenalty float64
	Stop             []string
}

type InputField struct {
	Field
}

type InterceptableModule interface {
	Module

	// ProcessWithInterceptors executes the module's logic with interceptor support
	ProcessWithInterceptors(ctx context.Context, inputs map[string]any, interceptors []ModuleInterceptor, opts ...Option) (map[string]any, error)

	// SetInterceptors sets the default interceptors for this module instance
	SetInterceptors(interceptors []ModuleInterceptor)

	// GetInterceptors returns the current interceptors for this module
	GetInterceptors() []ModuleInterceptor

	// ClearInterceptors removes all interceptors from this module
	ClearInterceptors()
}

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

type JSONGenerator interface {
	GenerateWithJSON(ctx context.Context, prompt string, options ...GenerateOption) (map[string]any, error)
}

type LLM interface {
	TextGenerator
	JSONGenerator
	FunctionCaller
	Embedder
	BatchEmbedder
	StreamGenerator
	ContentGenerator
	StreamContentGenerator
	LLMMetadata
}

type LLMFactory interface {
	// CreateLLM creates a new LLM instance. It uses the global configuration
	// from core.GlobalConfig for client settings.
	CreateLLM(apiKey string, modelID ModelID) (LLM, error)
}

type LLMMetadata interface {
	ProviderNamer
	ModelIdentifier
	CapabilityProvider
}

type LLMRegistry interface {
	// RegisterProvider registers a new provider factory
	RegisterProvider(name string, factory ProviderFactory) error

	// UnregisterProvider removes a provider
	UnregisterProvider(name string) error

	// CreateLLM creates an LLM instance using the registry
	CreateLLM(ctx context.Context, apiKey string, modelID ModelID) (LLM, error)

	// CreateLLMWithConfig creates an LLM instance with specific configuration
	CreateLLMWithConfig(ctx context.Context, config ProviderConfig, modelID ModelID) (LLM, error)

	// LoadFromConfig loads provider configurations from a config structure
	LoadFromConfig(ctx context.Context, configs map[string]ProviderConfig) error

	// ListProviders returns all registered provider names
	ListProviders() []string

	// GetProviderConfig returns the configuration for a provider
	GetProviderConfig(name string) (ProviderConfig, bool)

	// IsModelSupported checks if a model is supported by any provider
	IsModelSupported(modelID ModelID) bool

	// GetModelProvider returns the provider name for a model
	GetModelProvider(modelID ModelID) (string, bool)

	// SetDefaultProvider sets the default provider for models
	SetDefaultProvider(name string) error

	// RefreshProvider reloads a provider configuration
	RefreshProvider(ctx context.Context, name string, config ProviderConfig) error
}

type LLMResponse struct {
	Content  string
	Usage    *TokenInfo
	Metadata map[string]any
}

type LMConfigProvider interface {
	GetLLMIdentifier() map[string]string // Returns map like {"provider": "OpenAI", "model": "gpt-4"}
}

type LoadProgramOptions struct {
	// WarningHandler receives non-fatal compatibility or shape warnings encountered
	// while loading state. When nil, warnings are ignored.
	WarningHandler func(message string)
}

type Metric func(expected, actual map[string]any) float64

type ModelConfig struct {
	// Model identifier
	ID string `json:"id" yaml:"id"`

	// Display name
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	// Model capabilities
	Capabilities []string `json:"capabilities,omitempty" yaml:"capabilities,omitempty"`

	// Model-specific parameters
	Params map[string]any `json:"params,omitempty" yaml:"params,omitempty"`

	// Default generation options
	DefaultOptions *GenerateOptions `json:"default_options,omitempty" yaml:"default_options,omitempty"`
}

type ModelID string

type ModelIdentifier interface {
	ModelID() string
}

type Module interface {
	// Process executes the module's logic
	Process(ctx context.Context, inputs map[string]any, opts ...Option) (map[string]any, error)

	// GetSignature returns the module's input and output signature
	GetSignature() Signature

	SetSignature(signature Signature)

	// SetLLM sets the language model for the module
	SetLLM(llm LLM)

	// Clone creates a deep copy of the module
	Clone() Module

	// GetDisplayName returns a human-readable name for this module instance
	GetDisplayName() string

	// GetModuleType returns the category/type of this module
	GetModuleType() string
}

type ModuleChain struct {
	BaseModule
	Modules []Module
}

type ModuleHandler func(ctx context.Context, inputs map[string]any, opts ...Option) (map[string]any, error)

type ModuleInfo struct {
	// ModuleName is the human-readable name of the module instance
	ModuleName string

	// ModuleType is the category/type of the module (e.g., "ChainOfThought", "React")
	ModuleType string

	// Signature contains the input/output structure definition
	Signature Signature

	// LLM is the module-local language model when one is configured.
	// Interceptors should prefer this over process-global defaults.
	LLM LLM

	// Version is the module version for compatibility tracking
	Version string

	// Metadata contains additional module-specific information
	Metadata map[string]any
}

type ModuleInterceptor func(ctx context.Context, inputs map[string]any, info *ModuleInfo, handler ModuleHandler, opts ...Option) (map[string]any, error)

type ModuleOptions struct {
	// LLM generation options
	GenerateOptions []GenerateOption

	StreamHandler StreamHandler
}

type Optimizer interface {
	// Compile optimizes a given program using the provided dataset and metric
	Compile(ctx context.Context, program Program, dataset Dataset, metric Metric) (Program, error)
}

type OptimizerFactory func() (Optimizer, error)

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

type Option func(*ModuleOptions)

type OutputField struct {
	Field
}

type ParameterConsumer interface {
	SetTunedParameters(params map[string]any) error // Return error for validation
}

type ParameterProvider interface {
	GetTunedParameters() map[string]any
}

type Program struct {
	Modules map[string]Module
	Forward func(ctx context.Context, inputs map[string]any) (map[string]any, error)
	// contains filtered or unexported fields
}

type ProgressReporter interface {
	Report(stage string, processed, total int)
}

type PromptModel interface {
	TextGenerator
	ModelIdentifier
}

type ProviderConfig struct {
	// Provider name (e.g., "anthropic", "google", "ollama")
	Name string `json:"name" yaml:"name"`

	// API configuration
	APIKey  string `json:"api_key,omitempty" yaml:"api_key,omitempty"`
	BaseURL string `json:"base_url,omitempty" yaml:"base_url,omitempty"`

	// Model-specific configuration
	Models map[string]ModelConfig `json:"models,omitempty" yaml:"models,omitempty"`

	// Provider-specific parameters
	Params map[string]any `json:"params,omitempty" yaml:"params,omitempty"`

	// Endpoint configuration
	Endpoint *EndpointConfig `json:"endpoint,omitempty" yaml:"endpoint,omitempty"`
}

type ProviderFactory func(ctx context.Context, config ProviderConfig, modelID ModelID) (LLM, error)

type ProviderNamer interface {
	ProviderName() string
}

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

type RegistryConfig struct {
	// Providers configuration
	Providers map[string]ProviderConfig `json:"providers,omitempty" yaml:"providers,omitempty"`

	// Default provider
	DefaultProvider string `json:"default_provider,omitempty" yaml:"default_provider,omitempty"`

	// Cache settings
	CacheEnabled bool          `json:"cache_enabled,omitempty" yaml:"cache_enabled,omitempty"`
	CacheTTL     time.Duration `json:"cache_ttl,omitempty" yaml:"cache_ttl,omitempty"`
}

type RegistryConstructor func() LLMRegistry

type Runtime struct {
	DefaultLLM LLM
	TeacherLLM LLM
}

type SavedExample struct {
	Inputs  map[string]any `json:"inputs"`
	Outputs map[string]any `json:"outputs"`
}

type SavedModuleState struct {
	Signature       string            `json:"signature"`                  // Module's signature string representation (READ-ONLY during load)
	Demos           []SavedExample    `json:"demos,omitempty"`            // Saved demos, if the module provides them
	LMIdentifier    map[string]string `json:"lm_identifier,omitempty"`    // Identifying info for the LM used (e.g., provider, model)
	TunedParameters map[string]any    `json:"tuned_parameters,omitempty"` // Module-specific tuned parameters (e.g., k for retriever)
	ModuleType      string            `json:"module_type"`                // Concrete type name (e.g., "Predict")

}

type SavedProgramState struct {
	Modules  map[string]SavedModuleState `json:"modules"`  // Map module ID/name to its state
	Metadata map[string]string           `json:"metadata"` // e.g., {"dspy_go_version": "..."}
}

type Signature struct {
	Inputs      []InputField
	Outputs     []OutputField
	Instruction string
}

type SignatureMetadata struct {
	Inputs      []FieldMetadata
	Outputs     []FieldMetadata
	Instruction string
}

type Span struct {
	ID          string
	ParentID    string
	Operation   string
	StartTime   time.Time
	EndTime     time.Time
	Error       error
	Annotations map[string]any
	// contains filtered or unexported fields
}

type StreamChunk struct {
	Content string     // The text content of this chunk
	Done    bool       // Indicates if this is the final chunk
	Error   error      // Any error that occurred during streaming
	Usage   *TokenInfo // Optional token usage information (may be nil)
}

type StreamContentGenerator interface {
	StreamGenerateWithContent(ctx context.Context, content []ContentBlock, options ...GenerateOption) (*StreamResponse, error)
}

type StreamGenerator interface {
	StreamGenerate(ctx context.Context, prompt string, options ...GenerateOption) (*StreamResponse, error)
}

type StreamHandler func(chunk StreamChunk) error

type StreamResponse struct {
	ChunkChannel <-chan StreamChunk // Channel receiving response chunks
	Cancel       func()             // Function to cancel the stream
}

type TextGenerator interface {
	Generate(ctx context.Context, prompt string, options ...GenerateOption) (*LLMResponse, error)
}

type TokenInfo struct {
	PromptTokens     int
	CompletionTokens int
	TotalTokens      int
}

type TokenUsage struct {
	PromptTokens     int
	CompletionTokens int
	TotalTokens      int
	Cost             float64
}

type Tool interface {
	// Name returns the tool's identifier
	Name() string

	// Description returns human-readable explanation of the tool's purpose
	Description() string

	// Metadata returns the tool's metadata
	Metadata() *ToolMetadata

	// CanHandle checks if the tool can handle a specific action/intent
	CanHandle(ctx context.Context, intent string) bool

	// Execute runs the tool with provided parameters
	Execute(ctx context.Context, params map[string]any) (ToolResult, error)

	// Validate checks if the parameters match the expected schema
	Validate(params map[string]any) error

	// InputSchema returns the expected parameter structure
	InputSchema() models.InputSchema
}

type ToolApprovalDecision struct {
	Allowed bool
	Reason  string
}

type ToolApprovalFunc func(ctx context.Context, info *ToolInfo, args map[string]any) (ToolApprovalDecision, error)

type ToolBlockedError struct {
	Reason string
}

type ToolCall struct {
	ID        string         `json:"id"` // provider-assigned ID; required for tool-result correlation
	Name      string         `json:"name"`
	Arguments map[string]any `json:"arguments"`
	Metadata  map[string]any `json:"metadata,omitempty"`
}

type ToolCallingChatLLM interface {
	GenerateWithTools(ctx context.Context, messages []ChatMessage, tools []map[string]any, opts ...GenerateOption) (map[string]any, error)
}

type ToolHandler func(ctx context.Context, args map[string]any) (ToolResult, error)

type ToolInfo struct {
	// Name is the unique identifier for the tool
	Name string

	// Description is a human-readable explanation of the tool's purpose
	Description string

	// InputSchema defines the expected parameter structure
	InputSchema models.InputSchema

	// ToolType is the category/type of the tool (e.g., "MCPTool", "FunctionTool")
	ToolType string

	// Version is the tool version for compatibility tracking
	Version string

	// Capabilities lists the specific capabilities this tool provides
	Capabilities []string

	// Metadata contains additional tool-specific information
	Metadata map[string]any
}

type ToolInterceptor func(ctx context.Context, args map[string]any, info *ToolInfo, handler ToolHandler) (ToolResult, error)

type ToolMetadata struct {
	Name          string             // Unique identifier for the tool
	Description   string             // Human-readable description
	InputSchema   models.InputSchema // Rich schema from MCP-Go - now consistent with Tool interface
	OutputSchema  map[string]string  // Keep this field for backward compatibility
	Capabilities  []string           // List of supported capabilities
	ContextNeeded []string           // Required context keys
	Version       string             // Tool version for compatibility
}

type ToolRegistry interface {
	Register(tool Tool) error
	Get(name string) (Tool, error)
	List() []Tool
	Match(intent string) []Tool
}

type ToolResult struct {
	Data        any            // The actual result data
	Metadata    map[string]any // Execution metadata (timing, resources used, etc)
	Annotations map[string]any // Additional context for result interpretation
}

type TransportConfig struct {
	MaxIdleConns        int           // Total idle connections across all hosts (default: 100)
	MaxIdleConnsPerHost int           // Idle connections per host (default: 100)
	MaxConnsPerHost     int           // Max concurrent connections per host (default: 100)
	IdleConnTimeout     time.Duration // How long idle connections stay open (default: 90s)
	TLSHandshakeTimeout time.Duration // TLS handshake timeout (default: 10s)
}

type TypedSignature[TInput, TOutput any] interface {
	// GetInputType returns the reflect.Type for the input struct
	GetInputType() reflect.Type

	// GetOutputType returns the reflect.Type for the output struct
	GetOutputType() reflect.Type

	// ValidateInput performs compile-time and runtime validation of input
	ValidateInput(input TInput) error

	// ValidateOutput performs compile-time and runtime validation of output
	ValidateOutput(output TOutput) error

	// GetFieldMetadata returns parsed struct tag metadata
	GetFieldMetadata() SignatureMetadata

	// ToLegacySignature converts to the existing Signature interface for backward compatibility
	ToLegacySignature() Signature

	// WithInstruction returns a new TypedSignature with the specified instruction
	WithInstruction(instruction string) TypedSignature[TInput, TOutput]
}

type WorkloadType int