core

type AgentExecutionMetadata struct {
	AgentID      string        `json:"agent_id,omitempty"`
	TokensUsed   int           `json:"tokens_used,omitempty"`
	Cost         float64       `json:"cost,omitempty"`
	Duration     time.Duration `json:"duration,omitempty"`
	FinishReason string        `json:"finish_reason,omitempty"`
}

type AgentExecutionOutput struct {
	Content      string        `json:"content"`
	TokensUsed   int           `json:"tokens_used,omitempty"`
	Cost         float64       `json:"cost,omitempty"`
	Duration     time.Duration `json:"duration,omitempty"`
	FinishReason string        `json:"finish_reason,omitempty"`
}

type AgentExecutor interface {
	Execute(ctx context.Context, input map[string]any) (*AgentExecutionOutput, error)
}

type GatewayLike interface {
	Invoke(ctx context.Context, req *LLMRequest) (*LLMResponse, error)
	Stream(ctx context.Context, req *LLMRequest) (<-chan LLMStreamChunk, error)
}

type HumanInputHandler interface {
	RequestInput(ctx context.Context, prompt string, inputType string, options []string) (*HumanInputResult, error)
}

type HumanInputResult struct {
	Value    string `json:"value"`
	OptionID string `json:"option_id,omitempty"`
}

type LLMRequest struct {
	Model       string
	Prompt      string
	Temperature float64
	MaxTokens   int
	Metadata    map[string]string
}

type LLMResponse struct {
	Content string
	Model   string
	Usage   *LLMUsage
}

type LLMStreamChunk struct {
	Delta            string
	ReasoningContent *string
	Model            string
	Usage            *LLMUsage
	Done             bool
	Err              error
}

type LLMUsage struct {
	PromptTokens     int
	CompletionTokens int
	TotalTokens      int
}

type StepError struct {
	StepID   string
	StepType StepType
	Cause    error
}

type StepInput struct {
	// Data 上游步骤输出或用户输入。
	// nil 时视为空 map，调用方应使用 len(Data) == 0 或 Data == nil 判断。
	Data map[string]any
	// Metadata trace_id、run_id、node_id 等追踪信息。
	// nil 时视为空 map，调用方应使用 len(Metadata) == 0 或 Metadata == nil 判断。
	Metadata map[string]string
}

type StepOutput struct {
	Data    map[string]any    // 输出数据
	Usage   *types.TokenUsage // 可选，LLM 步骤填充
	Latency time.Duration
	Agent   *AgentExecutionMetadata // 可选，Agent 步骤填充
}

type StepProtocol interface {
	// ID 返回步骤唯一标识。
	ID() string
	// Type 返回步骤类型。
	Type() StepType
	// Execute 执行步骤。
	Execute(ctx context.Context, input StepInput) (StepOutput, error)
	// Validate 校验步骤配置是否合法。
	Validate() error
}

type StepType string

type ToolRegistry interface {
	ExecuteTool(ctx context.Context, name string, params map[string]any) (any, error)
}