// Package llm 提供与 OpenAI 兼容接口的大模型通信能力（含视觉与流式）。
package llm

import (
	"context"
	"fmt"
)

// Role 是消息角色。
type Role string

// 支持的角色。
const (
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
)

// Message 是一条对话消息。Image 非空表示该消息附带一张 JPEG 图片。
type Message struct {
	Role  Role
	Text  string
	Image []byte
}

// Usage 记录一次调用的 token 用量。
type Usage struct {
	PromptTokens     int
	CompletionTokens int
	TotalTokens      int
}

// Add 累加用量。
func (u *Usage) Add(o Usage) {
	u.PromptTokens += o.PromptTokens
	u.CompletionTokens += o.CompletionTokens
	u.TotalTokens += o.TotalTokens
}

// DeltaFunc 接收流式增量文本，返回 error 可中断请求。
type DeltaFunc func(delta string) error

// Options 描述一个模型接入点。
type Options struct {
	Name         string
	BaseURL      string
	APIKey       string
	Model        string
	ExtraHeaders map[string]string
	MaxTokens    int
	Temperature  float64
}

// Provider 是大模型服务的最小抽象。
// 目前只有 OpenAI 兼容实现，其它私有协议按此接口新增即可。
type Provider interface {
	// Chat 发起一次流式对话，system 为系统提示词。
	Chat(ctx context.Context, system string, msgs []Message, fn DeltaFunc) (Usage, error)
	// Ping 做一次最小代价的连通性检查。
	Ping(ctx context.Context) error
}

// New 根据接入点创建 Provider。
func New(opts Options) (Provider, error) {
	if opts.BaseURL == "" {
		return nil, fmt.Errorf("模型接入点缺少 BaseURL")
	}
	if opts.Model == "" {
		return nil, fmt.Errorf("模型接入点 %s 缺少 model", opts.Name)
	}
	return newOpenAI(opts), nil
}