api

type APIError struct {
	// ErrCategory 是错误的语义分类
	ErrCategory ErrorCategory

	// StatusCode 是 HTTP 状态码(连接错误时为 0)
	StatusCode int

	// Msg 是原始错误消息(可能来自 API JSON body 或网络错误)
	Msg string

	// Hint 是用户可操作的诊断提示(如 "检查企业代理的 SSL 证书")
	Hint string

	// Retry 是重试建议(nil 表示使用 ErrCategory 默认行为)
	Retry *RetryInfo

	// TokenGap 是 prompt_too_long 时溢出的 token 数(用于响应式压缩跳步).
	// 精妙之处(CLEVER): 从 "137500 tokens > 135000 maximum" 中提取差值 2500,
	// 让压缩模块一步跳过 2500 token 的消息组,而非逐个尝试.
	// 仅在 ErrCategory == ErrPromptTooLong 时有意义.
	TokenGap int

	// RespHeaders 是保留的响应头(用于下游消费者提取供应商特定信息)
	RespHeaders http.Header

	// Body 是原始响应体(用于调试和日志)
	Body string

	// Cause 是底层错误(网络错误时保留原始 error 链)
	Cause error
}

type AnthropicClassifier struct {
	// Hinter 提供连接诊断提示(可选)
	Hinter DiagnosticHinter
}

type BetaFeatures struct {
	// PromptCaching 启用 prompt caching
	PromptCaching bool
	// PromptCachingScope 缓存范围 ("global" 或 "org")
	PromptCachingScope string
	// ExtendedThinking 启用 extended thinking
	ExtendedThinking bool
	// FastMode 启用快速模式
	FastMode bool
	// Effort 努力级别 ("low"/"medium"/"high")
	Effort string
	// ContextManagement 启用上下文管理
	ContextManagement bool
	// StructuredOutput 启用结构化输出
	StructuredOutput bool
	// TaskBudgets 启用任务预算
	TaskBudgets bool
}

type CacheControl struct {
	Type string `json:"type"` // "ephemeral"
}

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

type ClientOption func(*Client)

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

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

type ContentBlock struct {
	Type      string         `json:"type"`
	Text      string         `json:"text,omitempty"`
	ID        string         `json:"id,omitempty"`
	Name      string         `json:"name,omitempty"`
	Input     map[string]any `json:"input,omitempty"`
	ToolUseID string         `json:"tool_use_id,omitempty"`
	Content   string         `json:"content,omitempty"`
	IsError   bool           `json:"is_error,omitempty"`
	Signature string         `json:"signature,omitempty"` // thinking block 的签名(Anthropic API 要求)

	// Source 携带 type=="image" 块的图片数据, 对齐 Anthropic image block
	// source spec (base64 内联或 url). 非 image 块留 nil (omitempty).
	//
	// Source carries image data for type=="image" blocks, matching
	// Anthropic's image block source spec (base64 inline or url). Nil
	// for non-image blocks (omitempty on the wire).
	Source *ImageSource `json:"source,omitempty"`

	// ContentItems carries array-form tool_result content (text + image
	// mixed). MarshalJSON picks between Content (string) and ContentItems
	// (array) for the "content" wire field. Non-tool_result blocks leave
	// it nil.
	//
	// ContentItems 承载 array 形式的 tool_result 内容 (text + image 混排).
	// MarshalJSON 在 Content 字符串 / ContentItems 数组间选一个做 "content"
	// wire 字段. 非 tool_result 块留 nil.
	ContentItems []ContentBlock `json:"-"`
}

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

type DefaultClassifier struct{}

type DefaultHinter struct{}

type DiagnosticHinter interface {
	// Hint 返回用户可操作的诊断提示,空字符串表示没有建议.
	Hint(err *APIError) string
}

type ErrorCategory = apierror.ErrorCategory

type ErrorClassifier interface {
	// Classify 分类一个 API 错误.
	// statusCode: HTTP 状态码(连接错误时为 0)
	// headers: 响应头(连接错误时为 nil)
	// body: 响应体(连接错误时为 nil)
	// cause: 底层错误(网络错误时非 nil)
	Classify(statusCode int, headers http.Header, body []byte, cause error) *APIError
}

type ImageSource struct {
	Type      string `json:"type"`                 // "base64" 或 "url"
	MediaType string `json:"media_type,omitempty"` // "image/png" 等, base64 时必填
	Data      string `json:"data,omitempty"`       // base64 编码字节, base64 时必填
	URL       string `json:"url,omitempty"`        // HTTPS URL, url 时必填
}

type MessageRequest struct {
	Model     string           `json:"model"`
	MaxTokens int              `json:"max_tokens"`
	System    json.RawMessage  `json:"system,omitempty"` // 支持字符串或 SystemContentBlock 数组
	Messages  []RequestMessage `json:"messages"`
	Tools     []ToolDef        `json:"tools,omitempty"`
	Stream    bool             `json:"stream"`
	Thinking  *ThinkingConfig  `json:"thinking,omitempty"` // extended thinking 配置
	// 升华改进(ELEVATED): stop_sequences 是 API 的基础能力,引擎应完整支持.
	// 不应因为"当前只有分类器用"就砍掉--跨场景谁知道哪个场景需要.
	// 例如仓储场景可能需要模型生成到 "---订单结束---" 就停.
	// 分类器 Stage 1 用 stop_sequences=["</block>"] 可以从 64 token 省到 5 token.
	// 替代方案:不支持,靠 max_tokens 兜底(能用但浪费 token).
	StopSequences []string `json:"stop_sequences,omitempty"`
	// Beta 功能配置(不序列化到请求体,通过 header 传递)
	Beta           *BetaFeatures   `json:"-"`
	ResponseFormat *ResponseFormat `json:"response_format,omitempty"` // 结构化输出格式

	// Temperature is the per-request sampling temperature; nil omits the
	// field on the wire so the upstream uses its default. Anthropic accepts
	// [0, 1]; anthropic provider also enforces extended-thinking mode's
	// hard constraint of temperature=1.0 before reaching this point.
	//
	// Temperature 是本次请求的采样温度; nil 时 wire 上不传, 上游用默认.
	// Anthropic 接受 [0, 1]; anthropic provider 在 extended thinking 模式
	// 下会在到达此处前强制覆盖为 1.0 (服务端硬约束).
	Temperature *float64 `json:"temperature,omitempty"`

	// TopP is the per-request nucleus sampling cutoff; nil omits the field.
	// Anthropic accepts [0, 1]; in thinking mode the API restricts to
	// [0.95, 1.0] (anthropic provider pre-handles the override).
	//
	// TopP 是本次请求的 nucleus 采样阈值; nil 时 wire 上不传.
	// Anthropic 接受 [0, 1]; thinking 模式下 API 限制 [0.95, 1.0]
	// (anthropic provider 提前覆盖).
	TopP *float64 `json:"top_p,omitempty"`
}

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

type RequestMessage struct {
	Role    string          `json:"role"`
	Content json.RawMessage `json:"content"`
}

type ResponseFormat struct {
	Type       string          `json:"type"`                  // "json_schema"
	JSONSchema json.RawMessage `json:"json_schema,omitempty"` // JSON Schema 定义
}

type RetryInfo = apierror.RetryInfo

type StreamEvent struct {
	Type  StreamEventType
	Index int    // content block 的索引
	Delta string // text / thinking 增量内容

	// content_block_start 时携带完整的 block 信息
	BlockType string // "text", "thinking", "tool_use"
	BlockID   string // tool_use block 的 ID
	BlockName string // tool_use block 的工具名称

	// tool_use delta 时累积的 JSON 片段
	PartialJSON string

	// message_start / message_delta 时携带的 usage 信息
	Usage *UsageInfo

	// message_delta 时携带的 stop_reason
	StopReason string
}

type StreamEventType string

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

type StreamGuardConfig struct {
	// IdleTimeout 空闲超时:流中间多久无事件视为挂起(默认 90s).
	// 精妙之处(CLEVER): SDK 的 request timeout 只管初始连接,
	// 不管流中间断了.没有看门狗,静默断开的连接会让进程永远挂起.
	IdleTimeout time.Duration

	// IdleWarningAt 空闲警告时间点(默认 IdleTimeout/2).
	IdleWarningAt time.Duration

	// StallThreshold 停顿阈值(默认 30s).
	StallThreshold time.Duration

	// OnIdleWarning 空闲警告回调(可选)
	OnIdleWarning func(elapsed time.Duration)

	// OnIdleTimeout 空闲超时回调(可选)
	OnIdleTimeout func()

	// OnStall 停顿检测回调(可选)
	OnStall func(gap time.Duration, stallCount int, totalStallTime time.Duration)

	// OnStreamEnd 流结束回调(可选)
	OnStreamEnd func(stats *StreamStats)
}

type StreamStats struct {
	// HasContent 是否收到过内容事件(TextDelta / ToolUse / ThinkingDelta)
	HasContent bool
	// HasUsage 是否收到 UsageEvent(流正常结束的标志)
	HasUsage bool
	// StopReason 最终的 stop_reason(来自 UsageEvent)
	StopReason string
	// ContentBlockCount 完成的内容块数量(Text + ToolUse)
	ContentBlockCount int
	// EventCount 总事件数量
	EventCount int
	// StallCount 停顿次数
	StallCount int
	// TotalStallTime 累计停顿时间
	TotalStallTime time.Duration
	// Duration 流的总持续时间
	Duration time.Duration
	// IdleAborted 是否因空闲超时被中止
	IdleAborted bool
}

type SystemContentBlock struct {
	Type         string        `json:"type"` // "text"
	Text         string        `json:"text"`
	CacheControl *CacheControl `json:"cache_control,omitempty"` // 缓存控制标记
}

type ThinkingConfig struct {
	Type         string `json:"type"`                    // "enabled" 或 "disabled"
	BudgetTokens int    `json:"budget_tokens,omitempty"` // thinking token 预算(0=不限制)
}

type ToolDef struct {
	Name         string          `json:"name"`
	Description  string          `json:"description"`
	InputSchema  json.RawMessage `json:"input_schema"`
	CacheControl *CacheControl   `json:"cache_control,omitempty"`
}

type TransportConfig struct {
	// MaxIdleConnsPerHost 每个 host 最大空闲连接数(默认 2)
	MaxIdleConnsPerHost int
	// MaxIdleConns 全局最大空闲连接数(默认 10)
	MaxIdleConns int
	// IdleConnTimeout 空闲连接超时时间(默认 90s)
	IdleConnTimeout time.Duration
	// TLSHandshakeTimeout TLS 握手超时(默认 10s)
	TLSHandshakeTimeout time.Duration
	// ResponseHeaderTimeout 等待响应头的超时(默认 0=不限制,由 context 控制)
	ResponseHeaderTimeout time.Duration
	// DisableKeepAlives 禁用 keep-alive(stale 连接自愈时使用)
	DisableKeepAlives bool
	// TLSConfig 自定义 TLS 配置(mTLS 客户端证书等)
	TLSConfig *tls.Config
	// DialTimeout TCP 连接超时(默认 30s)
	DialTimeout time.Duration
	// DNSResolver 自定义 DNS 解析器(可选,用于 DNS 预解析)
	DNSResolver *net.Resolver
}

type UsageInfo struct {
	InputTokens      int `json:"input_tokens"`
	OutputTokens     int `json:"output_tokens"`
	CacheReadTokens  int `json:"cache_read_input_tokens"`
	CacheWriteTokens int `json:"cache_creation_input_tokens"`
}