protocol

type ChatModel interface {
	Name() string
	// Chat return common chat response
	Chat(ctx context.Context, req ChatRequest) (*ChatResponse, error)
	// StreamChat returns a streaming handle that yields incremental deltas.
	StreamChat(ctx context.Context, req ChatRequest) (ChatStream, error)
}

type ChatRequest struct {
	// Model is the target model identifier (e.g. "gpt-4o", "claude-3-opus").
	Model string `json:"model"`
	// Messages is the ordered conversation history.
	Messages []Message `json:"messages"`
	// MaxTokens limits generated tokens (provider specific defaults apply when zero).
	MaxTokens int `json:"max_tokens,omitempty"`
	// Temperature controls randomness (0–2 typical for OpenAI-compatible models).
	Temperature float32 `json:"temperature,omitempty"`
	// TopP enables nucleus sampling (provider specific).
	TopP float32 `json:"top_p,omitempty"`
	// Stop provides stop sequences.
	Stop []string `json:"stop,omitempty"`
	// Tools are functions the model can call.
	Tools []Tool `json:"tools,omitempty"`
	// ToolChoice controls tool calling behavior.
	ToolChoice ToolChoice `json:"tool_choice,omitempty"`
	// Metadata is an optional provider-specific bag for future extensions.
	Metadata map[string]string `json:"metadata,omitempty"`
}

type ChatResponse struct {
	ID        string              `json:"id"`
	Model     string              `json:"model"`
	CreatedAt time.Time           `json:"created_at"`
	Choices   []Choice            `json:"choices"`
	Usage     TokenUsage          `json:"usage"`
	Metrics   metrics.CallMetrics `json:"metrics,omitempty"`
}

type ChatStream interface {
	Recv() (*ChatStreamChunk, error)
	Close() error
	Metrics() metrics.CallMetrics
}

type ChatStreamChunk struct {
	Index        int         `json:"index"`
	Role         MessageRole `json:"role"`
	Delta        string      `json:"delta"`
	FinishReason string      `json:"finish_reason,omitempty"`
}

type Choice struct {
	Index        int     `json:"index"`
	Message      Message `json:"message"`
	FinishReason string  `json:"finish_reason"`
}

type ClientConfig struct {
	Provider     ProviderType
	APIKey       string
	BaseURL      string
	Organization string // OpenAI only
	Project      string // OpenAI only
}

type ClientFactory func(ClientConfig) (ChatModel, error)

type FunctionCall struct {
	Name      string          `json:"name"`
	Arguments json.RawMessage `json:"arguments"`
}

type Message struct {
	Role       MessageRole `json:"role"`
	Content    string      `json:"content"`
	ToolCallID string      `json:"tool_call_id,omitempty"`
	ToolCalls  []ToolCall  `json:"tool_calls,omitempty"`
}

type MessageRole string

type ProviderType string

type SourceEOF struct {
	Source string
}

type StreamReader = ChatStream

type StreamTransformer interface {
	Transform(ctx context.Context, chunk *ChatStreamChunk) (*ChatStreamChunk, error)
}

type StreamTransformerFunc func(ctx context.Context, chunk *ChatStreamChunk) (*ChatStreamChunk, error)

type StreamWriter interface {
	// Send sends a chunk to the stream.
	Send(chunk *ChatStreamChunk, err error) error
	// Close closes the stream.
	Close() error
}

type TokenUsage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

type Tool struct {
	Name        string                 `json:"name"`
	Description string                 `json:"description"`
	Parameters  map[string]interface{} `json:"parameters,omitempty"`
}

type ToolCall struct {
	ID       string       `json:"id"`
	Type     string       `json:"type"`
	Function FunctionCall `json:"function"`
}

type ToolChoice string