api

type A2ARequest struct {
	// 任务描述或查询
	Task string `json:"task" example:"What is the weather today?" binding:"required"`
	// 额外的背景信息
	Context any `json:"context,omitempty"`
	// 是否流式传输响应
	Stream bool `json:"stream,omitempty" example:"false"`
}

type A2AResponse struct {
	// 响应状态（pending、processing、completed、failed）
	Status string `json:"status" example:"pending"`
	// 任务结果
	Result any `json:"result,omitempty"`
	// 如果失败则出现错误消息
	Error string `json:"error,omitempty"`
}

type AgentCard struct {
	// 代理名称
	Name string `json:"name" example:"my-agent"`
	// 代理说明
	Description string `json:"description" example:"A helpful AI assistant"`
	// 代理端点 URL
	URL string `json:"url" example:"http://localhost:8080"`
	// 代理版
	Version string `json:"version" example:"1.0.0"`
	// 代理能力
	Capabilities []Capability `json:"capabilities"`
	// 代理输入的 JSON 架构
	InputSchema any `json:"input_schema,omitempty"`
	// 代理输出的 JSON 架构
	OutputSchema any `json:"output_schema,omitempty"`
	// 可用工具
	Tools []ToolDefinition `json:"tools,omitempty"`
	// 附加元数据
	Metadata map[string]string `json:"metadata,omitempty"`
}

type Capability struct {
	// 能力名称
	Name string `json:"name" example:"chat"`
	// 能力描述
	Description string `json:"description" example:"Chat with the agent"`
	// 能力类型（任务、查询、流）
	Type string `json:"type" example:"query"`
}

type ChatChoice struct {
	// 选项索引
	Index int `json:"index" example:"0"`
	// 完成原因（stop、length、tool_calls、content_filter）
	FinishReason string `json:"finish_reason,omitempty" example:"stop"`
	// 响应消息
	Message Message `json:"message"`
}

type ChatRequest struct {
	// 用于请求跟踪的跟踪 ID
	TraceID string `json:"trace_id,omitempty" example:"trace-123"`
	// 多租户的租户 ID
	TenantID string `json:"tenant_id,omitempty" example:"tenant-1"`
	// 用户身份
	UserID string `json:"user_id,omitempty" example:"user-1"`
	// 模型名称（例如 gpt-4、claude-3-opus）
	Model string `json:"model" example:"gpt-4" binding:"required"`
	// Provider 路由提示（如 openai/anthropic）
	Provider string `json:"provider,omitempty" example:"openai"`
	// 路由策略（balanced/cost_first/health_first/latency_first）
	RoutePolicy string `json:"route_policy,omitempty" example:"balanced"`
	// 对话消息
	Messages []Message `json:"messages" binding:"required"`
	// 生成的最大 Token 数量
	MaxTokens int `json:"max_tokens,omitempty" example:"4096"`
	// 采样温度（0-2）
	Temperature float32 `json:"temperature,omitempty" example:"0.7"`
	// 核采样参数（0-1）
	TopP float32 `json:"top_p,omitempty" example:"1.0"`
	// 停止序列
	Stop []string `json:"stop,omitempty"`
	// 函数调用的可用工具
	Tools []ToolSchema `json:"tools,omitempty"`
	// 工具选择模式（字符串如 "auto"/"none"/"required"，或结构化对象）
	ToolChoice any `json:"tool_choice,omitempty"`
	// 请求超时时长
	Timeout string `json:"timeout,omitempty" example:"30s"`
	// 自定义元数据
	Metadata map[string]string `json:"metadata,omitempty"`
	// 路由标签
	Tags []string `json:"tags,omitempty"`
}

type ChatResponse struct {
	// 响应ID
	ID string `json:"id,omitempty" example:"chatcmpl-123"`
	// 处理请求的提供者
	Provider string `json:"provider,omitempty" example:"openai"`
	// 使用的模型
	Model string `json:"model" example:"gpt-4"`
	// 响应选项
	Choices []ChatChoice `json:"choices"`
	// Token 使用统计
	Usage ChatUsage `json:"usage"`
	// 响应创建时间戳
	CreatedAt time.Time `json:"created_at"`
}

type ChatUsage struct {
	// 提示 Token 数
	PromptTokens int `json:"prompt_tokens" example:"100"`
	// 补全 Token 数
	CompletionTokens int `json:"completion_tokens" example:"50"`
	// 总 Token 数
	TotalTokens int `json:"total_tokens" example:"150"`
}

type ErrorInfo struct {
	Code       string `json:"code"`
	Message    string `json:"message"`
	Details    string `json:"details,omitempty"`
	Retryable  bool   `json:"retryable,omitempty"`
	HTTPStatus int    `json:"-"` // not serialized to JSON
	Provider   string `json:"provider,omitempty"`
}

type ErrorResponse struct {
	// 错误详情
	Error ErrorInfo `json:"error"`
}

type ImageContent struct {
	// 图像内容类型（url 或 base64）
	Type string `json:"type" example:"url"`
	// 图片 URL（当类型为 url 时）
	URL string `json:"url,omitempty" example:"https://example.com/image.png"`
	// Base64编码的图像数据（当类型为base64时）
	Data string `json:"data,omitempty"`
}

type LLMModel struct {
	// 模型 ID
	ID uint `json:"id" example:"1"`
	// 模型标识符
	ModelName string `json:"model_name" example:"gpt-4"`
	// 显示名称
	DisplayName string `json:"display_name,omitempty" example:"GPT-4"`
	// 模型描述
	Description string `json:"description,omitempty"`
	// 模型是否启用
	Enabled bool `json:"enabled" example:"true"`
	// 创建时间戳
	CreatedAt time.Time `json:"created_at"`
	// 最后更新时间戳
	UpdatedAt time.Time `json:"updated_at"`
}

type LLMProvider struct {
	// 提供商 ID
	ID uint `json:"id" example:"1"`
	// 提供商代码（例如 openai、anthropic）
	Code string `json:"code" example:"openai"`
	// 提供商显示名称
	Name string `json:"name" example:"OpenAI"`
	// 提供商描述
	Description string `json:"description,omitempty" example:"OpenAI GPT models"`
	// 提供商状态（0：非活动、1：活动、2：禁用）
	Status int `json:"status" example:"1"`
	// 创建时间戳
	CreatedAt time.Time `json:"created_at"`
	// 最后更新时间戳
	UpdatedAt time.Time `json:"updated_at"`
}

type LLMProviderModel struct {
	// 映射ID
	ID uint `json:"id" example:"1"`
	// 模型 ID
	ModelID uint `json:"model_id" example:"1"`
	// 提供商 ID
	ProviderID uint `json:"provider_id" example:"1"`
	// 提供商已知的模型名称
	RemoteModelName string `json:"remote_model_name" example:"gpt-4-turbo"`
	// 提供者基本 URL
	BaseURL string `json:"base_url,omitempty" example:"https://api.openai.com"`
	// 每 1K 输入 Token 的价格
	PriceInput float64 `json:"price_input" example:"0.01"`
	// 每 1K 补全 Token 的价格
	PriceCompletion float64 `json:"price_completion" example:"0.03"`
	// 最大上下文长度
	MaxTokens int `json:"max_tokens" example:"128000"`
	// 路由优先级
	Priority int `json:"priority" example:"100"`
	// 是否启用映射
	Enabled bool `json:"enabled" example:"true"`
}

type Message struct {
	// 消息角色（系统、用户、助手、工具）
	Role string `json:"role" example:"user" binding:"required"`
	// 消息内容
	Content string `json:"content,omitempty" example:"Hello, how are you?"`
	// 推理/思考内容
	ReasoningContent *string `json:"reasoning_content,omitempty"`
	// Claude thinking blocks（用于多轮 round-trip）
	ThinkingBlocks []types.ThinkingBlock `json:"thinking_blocks,omitempty"`
	// 模型拒绝内容
	Refusal *string `json:"refusal,omitempty"`
	// 名称（用于工具消息）
	Name string `json:"name,omitempty"`
	// 工具调用（用于助手消息）
	ToolCalls []types.ToolCall `json:"tool_calls,omitempty"`
	// 工具调用 ID（用于工具消息）
	ToolCallID string `json:"tool_call_id,omitempty"`
	// tool_result 是否为错误结果
	IsToolError bool `json:"is_tool_error,omitempty"`
	// 多模式消息的图像内容
	Images []ImageContent `json:"images,omitempty"`
	// 多模态消息的视频内容
	Videos []types.VideoContent `json:"videos,omitempty"`
	// URL 引用注释
	Annotations []types.Annotation `json:"annotations,omitempty"`
	// 自定义元数据
	Metadata any `json:"metadata,omitempty"`
	// 消息时间戳
	Timestamp time.Time `json:"timestamp,omitempty"`
}

type ModelListResponse struct {
	// 模型列表
	Models []LLMModel `json:"models"`
}

type ProviderHealthResponse struct {
	// 提供者是否健康
	Healthy bool `json:"healthy" example:"true"`
	// 响应延迟
	Latency string `json:"latency" example:"100ms"`
	// 错误率（0-1）
	ErrorRate float64 `json:"error_rate" example:"0.01"`
	// 健康检查消息（可选，如降级原因）
	Message string `json:"message,omitempty" example:""`
}

type ProviderListResponse struct {
	// 供应商名单
	Providers []LLMProvider `json:"providers"`
}

type ProviderSelection struct {
	// 提供商 ID
	ProviderID uint `json:"provider_id" example:"1"`
	// 提供商代码
	ProviderCode string `json:"provider_code" example:"openai"`
	// 模型 ID
	ModelID uint `json:"model_id" example:"1"`
	// 模型名称
	ModelName string `json:"model_name" example:"gpt-4"`
	// 是否为金丝雀部署
	IsCanary bool `json:"is_canary" example:"false"`
	// 用于选择的策略
	Strategy string `json:"strategy" example:"cost"`
}

type Response struct {
	Success   bool       `json:"success"`
	Data      any        `json:"data,omitempty"`
	Error     *ErrorInfo `json:"error,omitempty"`
	Timestamp time.Time  `json:"timestamp"`
	RequestID string     `json:"request_id,omitempty"`
}

type RoutingRequest struct {
	// 路由的模型名称
	Model string `json:"model" example:"gpt-4" binding:"required"`
	// 路由策略（cost、health、qps、canary、tag）
	Strategy string `json:"strategy" example:"cost" binding:"required"`
	// 用于基于标签的路由的标签
	Tags []string `json:"tags,omitempty"`
}

type StreamChunk struct {
	// 块ID
	ID string `json:"id,omitempty" example:"chatcmpl-123"`
	// 提供商名称
	Provider string `json:"provider,omitempty" example:"openai"`
	// 模型名称
	Model string `json:"model,omitempty" example:"gpt-4"`
	// 选项索引
	Index int `json:"index,omitempty" example:"0"`
	// 增量消息内容
	Delta Message `json:"delta"`
	// 完成原因（仅在最后一块）
	FinishReason string `json:"finish_reason,omitempty" example:"stop"`
	// 使用统计（仅在最终块中）
	Usage *ChatUsage `json:"usage,omitempty"`
	// 错误信息
	Error *ErrorInfo `json:"error,omitempty"`
}

type ToolDefinition struct {
	// 工具名称
	Name string `json:"name" example:"search"`
	// 工具说明
	Description string `json:"description" example:"Search the web"`
	// 工具参数的 JSON 架构
	Parameters any `json:"parameters,omitempty"`
}

type ToolInvokeRequest struct {
	// 工具参数
	Arguments json.RawMessage `json:"arguments" binding:"required"`
}

type ToolListResponse struct {
	// 工具清单
	Tools []ToolSchema `json:"tools"`
}

type ToolResultDTO struct {
	// 工具调用 ID
	ToolCallID string `json:"tool_call_id" example:"call_123"`
	// 工具名称
	Name string `json:"name" example:"get_weather"`
	// JSON 格式的工具结果
	Result json.RawMessage `json:"result"`
	// 如果执行失败则出现错误消息
	Error string `json:"error,omitempty"`
	// 执行时长
	Duration string `json:"duration,omitempty" example:"100ms"`
}

type ToolSchema struct {
	// 工具名称
	Name string `json:"name" example:"get_weather"`
	// 工具说明
	Description string `json:"description,omitempty" example:"Get the current weather for a location"`
	// 工具参数的 JSON 架构
	Parameters json.RawMessage `json:"parameters"`
	// 工具版本
	Version string `json:"version,omitempty" example:"1.0.0"`
}