nai

type AIExprEnv struct {
	VarMap     map[string]any
	AINodeName string // The AI node name (e.g., "ai_1") for context
}

type AIParam struct {
	Name        string // Variable name (e.g., "userId")
	Description string // Human-readable description (e.g., "The user ID to fetch")
	Type        string // Data type: "string", "number", "boolean", "array", "object"
	Required    bool   // Whether this parameter is required (default: true)
	SourceHint  string // Optional: Where to get this value (e.g., "GetUser.response.body.id")
}

type AIParamProvider interface {
	// GetAIParams returns all AI parameters this node requires.
	GetAIParams() []AIParam
}

type AIProvider interface {
	node.FlowNode

	// Execute runs the LLM with typed input and returns typed output.
	// This is the primary method for orchestrator-to-provider communication,
	// maintaining type safety for messages and tool calls.
	Execute(ctx context.Context, req *node.FlowNodeRequest, input AIProviderInput) (*mflow.AIProviderOutput, error)

	// GetModelString returns the model identifier string (e.g., "gpt-5.2")
	GetModelString() string

	// GetProviderString returns the provider name (e.g., "openai", "anthropic")
	GetProviderString() string

	// SetProviderFactory sets the LLM provider factory on the provider node
	SetProviderFactory(factory *scredential.LLMProviderFactory)

	// SetLLM sets a mock LLM model for testing purposes
	SetLLM(llm any)
}

type AIProviderInput struct {
	Messages []llm.Message
	Tools    []llm.Tool
}

type AIVarDetail struct {
	Path        string `json:"path"`                  // Full variable path (e.g., "GetUser.response.body.id")
	Type        string `json:"type,omitempty"`        // Data type if known
	Description string `json:"description,omitempty"` // Human description
	Source      string `json:"source,omitempty"`      // Where this value comes from
	Example     string `json:"example,omitempty"`     // Example value
}

type BuiltinToolExecution struct {
	*ChildExecution
	ToolName string
}

type ChainInfo struct {
	FromTool  string // Source tool name (e.g., "GetUser")
	FromPath  string // Output path (e.g., "response.body.id")
	ToParam   string // Target parameter name (e.g., "userId")
	ToTool    string // Target tool name (e.g., "GetPosts")
	ParamType string // Expected type
}

type ChildExecution struct {
	ExecutionID idwrap.IDWrap
	ParentID    idwrap.IDWrap // Parent orchestrator's execution ID
	NodeID      idwrap.IDWrap
	Name        string
	Tracker     *tracking.VariableTracker
}

type DescribableNode interface {
	// GetDescription returns a user-defined description of what this node does,
	// including required inputs and expected outputs.
	GetDescription() string
}

type NodeAI struct {
	FlowNodeID    idwrap.IDWrap
	Name          string
	Prompt        string
	MaxIterations int32
	// ProviderFactory creates LLM clients from credentials (passed to provider)
	ProviderFactory *scredential.LLMProviderFactory
	// EnableDiscoveryTool enables the discover_tools function (PoC #3)
	EnableDiscoveryTool bool
	// DiscoverToolCalls tracks how many times discover_tools was called (for metrics)
	DiscoverToolCalls int
}

type NodeTool struct {
	TargetNode node.FlowNode
	Req        *node.FlowNodeRequest
}

type NodeToolExecution struct {
	*ChildExecution
	ToolName string
}

type ProviderExecution struct {
	*ChildExecution
	Iteration int
}

type ToolExecuteResult struct {
	Output      string
	OutputData  any
	AuxiliaryID *idwrap.IDWrap
	Err         error
}

type ToolInfo struct {
	Name         string   `json:"name"`
	Description  string   `json:"description"`
	RequiredVars []string `json:"required_variables,omitempty"`
	OutputVars   []string `json:"output_variables,omitempty"`
}

type ToolOverview struct {
	Name    string
	Inputs  []AIParam
	Outputs []string
}