schema

type AgenticAllowedToolChoice struct {
	// Tools is the list of allowed tools for the model to call.
	// Optional.
	Tools []*AllowedTool
}

type AgenticForcedToolChoice struct {
	// Tools is the list of tools that the model must call.
	// Optional.
	Tools []*AllowedTool
}

type AgenticMessage struct {
	// Role is the message role.
	Role AgenticRoleType

	// ContentBlocks is the list of content blocks.
	ContentBlocks []*ContentBlock

	// ResponseMeta is the response metadata.
	ResponseMeta *AgenticResponseMeta

	// Extra is the additional information.
	Extra map[string]any
}

type AgenticMessagesTemplate interface {
	Format(ctx context.Context, vs map[string]any, formatType FormatType) ([]*AgenticMessage, error)
}

type AgenticResponseMeta struct {
	// TokenUsage is the token usage.
	TokenUsage *TokenUsage

	// OpenAIExtension is the extension for OpenAI.
	OpenAIExtension *openai.ResponseMetaExtension

	// GeminiExtension is the extension for Gemini.
	GeminiExtension *gemini.ResponseMetaExtension

	// ClaudeExtension is the extension for Claude.
	ClaudeExtension *claude.ResponseMetaExtension

	// Extension is the extension for other models, supplied by the component implementer.
	Extension any
}

type AgenticRoleType string

type AgenticToolChoice struct {
	// Type is the tool choice mode.
	Type ToolChoice

	// Allowed optionally specifies the list of tools that the model is permitted to call.
	// Optional.
	Allowed *AgenticAllowedToolChoice

	// Forced optionally specifies the list of tools that the model is required to call.
	// Optional.
	Forced *AgenticForcedToolChoice
}

type AllowedMCPTool struct {
	// ServerLabel is the label of the MCP server.
	ServerLabel string
	// Name is the name of the MCP tool.
	Name string
}

type AllowedServerTool struct {
	// Name is the name of the server tool.
	Name string
}

type AllowedTool struct {
	// FunctionName specifies a function tool by name.
	FunctionName string

	// MCPTool specifies an MCP tool.
	MCPTool *AllowedMCPTool

	// ServerTool specifies a server tool.
	ServerTool *AllowedServerTool
}

type AssistantGenAudio struct {
	// URL is the HTTP/HTTPS link.
	URL string

	// Base64Data is the binary data in Base64 encoded string format.
	Base64Data string

	// MIMEType is the mime type, e.g. "audio/wav".
	MIMEType string
}

type AssistantGenImage struct {
	// URL is the HTTP/HTTPS link.
	URL string

	// Base64Data is the binary data in Base64 encoded string format.
	Base64Data string

	// MIMEType is the mime type, e.g. "image/png".
	MIMEType string
}

type AssistantGenText struct {
	// Text is the generated text.
	Text string

	// OpenAIExtension is the extension for OpenAI.
	OpenAIExtension *openai.AssistantGenTextExtension

	// ClaudeExtension is the extension for Claude.
	ClaudeExtension *claude.AssistantGenTextExtension

	// Extension is the extension for other models, supplied by the component implementer.
	Extension any
}

type AssistantGenVideo struct {
	// URL is the HTTP/HTTPS link.
	URL string

	// Base64Data is the binary data in Base64 encoded string format.
	Base64Data string

	// MIMEType is the mime type, e.g. "video/mp4".
	MIMEType string
}

type ChatMessagePartType string

type CompletionTokensDetails struct {
	// ReasoningTokens tokens generated by the model for reasoning.
	// This is currently supported by OpenAI, Gemini, ARK and Qwen  chat models.
	// For other models, this field will be 0.
	ReasoningTokens int `json:"reasoning_tokens,omitempty"`
}

type ContentBlock struct {
	Type ContentBlockType

	// Reasoning contains the reasoning content generated by the model.
	Reasoning *Reasoning

	// UserInputText contains the text content provided by the user.
	UserInputText *UserInputText

	// UserInputImage contains the image content provided by the user.
	UserInputImage *UserInputImage

	// UserInputAudio contains the audio content provided by the user.
	UserInputAudio *UserInputAudio

	// UserInputVideo contains the video content provided by the user.
	UserInputVideo *UserInputVideo

	// UserInputFile contains the file content provided by the user.
	UserInputFile *UserInputFile

	// AssistantGenText contains the text content generated by the model.
	AssistantGenText *AssistantGenText

	// AssistantGenImage contains the image content generated by the model.
	AssistantGenImage *AssistantGenImage

	// AssistantGenAudio contains the audio content generated by the model.
	AssistantGenAudio *AssistantGenAudio

	// AssistantGenVideo contains the video content generated by the model.
	AssistantGenVideo *AssistantGenVideo

	// FunctionToolCall contains the invocation details for a user-defined tool.
	FunctionToolCall *FunctionToolCall

	// FunctionToolResult contains the result returned from a user-defined tool call.
	FunctionToolResult *FunctionToolResult

	// ServerToolCall contains the invocation details for a provider built-in tool executed on the model server.
	ServerToolCall *ServerToolCall

	// ServerToolResult contains the result returned from a provider built-in tool executed on the model server.
	ServerToolResult *ServerToolResult

	// MCPToolCall contains the invocation details for an MCP tool managed by the model server.
	MCPToolCall *MCPToolCall

	// MCPToolResult contains the result returned from an MCP tool managed by the model server.
	MCPToolResult *MCPToolResult

	// MCPListToolsResult contains the list of available MCP tools reported by the model server.
	MCPListToolsResult *MCPListToolsResult

	// MCPToolApprovalRequest contains the user approval request for an MCP tool call when required.
	MCPToolApprovalRequest *MCPToolApprovalRequest

	// MCPToolApprovalResponse contains the user's approval decision for an MCP tool call.
	MCPToolApprovalResponse *MCPToolApprovalResponse

	// StreamingMeta contains metadata for streaming responses.
	StreamingMeta *StreamingMeta

	// Extra contains additional information for the content block.
	Extra map[string]any
}

type ContentBlockType string

type ConvertOption func(*convertOptions)

type DataType string

type Document struct {
	// ID is the unique identifier of the document.
	ID string `json:"id"`
	// Content is the content of the document.
	Content string `json:"content"`
	// MetaData is the metadata of the document, can be used to store extra information.
	MetaData map[string]any `json:"meta_data"`
}

type FormatType uint8

type FunctionCall struct {
	// Name is the name of the function to call, it can be used to identify the specific function.
	Name string `json:"name,omitempty"`
	// Arguments is the arguments to call the function with, in JSON format.
	Arguments string `json:"arguments,omitempty"`
}

type FunctionToolCall struct {
	// CallID is the unique identifier for the tool call.
	CallID string

	// Name specifies the function tool invoked.
	Name string

	// Arguments is the JSON string arguments for the function tool call.
	Arguments string
}

type FunctionToolResult struct {
	// CallID is the unique identifier for the tool call.
	CallID string

	// Name specifies the function tool invoked.
	Name string

	// Result is the function tool result returned by the user
	Result string
}

type ImageURLDetail string

type LogProb struct {
	// Token represents the text of the token, which is a contiguous sequence of characters
	// (e.g., a word, part of a word, or punctuation) as understood by the tokenization process used by the language model.
	Token string `json:"token"`
	// LogProb is the log probability of this token, if it is within the top 20 most likely tokens.
	// Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.
	LogProb float64 `json:"logprob"`
	// Bytes is a list of integers representing the UTF-8 bytes representation of the token.
	// Useful in instances where characters are represented by multiple tokens and
	// their byte representations must be combined to generate the correct text
	// representation. Can be `null` if there is no bytes representation for the token.
	Bytes []int64 `json:"bytes,omitempty"` // Omitting the field if it is null
	// TopLogProbs is a list of the most likely tokens and their log probability, at this token position.
	// In rare cases, there may be fewer than the number of requested top_logprobs returned.
	TopLogProbs []TopLogProb `json:"top_logprobs"`
}

type LogProbs struct {
	// Content is a list of message content tokens with log probability information.
	Content []LogProb `json:"content"`
}

type MCPListToolsItem struct {
	// Name is the name of the tool.
	Name string

	// Description is the description of the tool.
	Description string

	// InputSchema is the JSON schema that describes the tool input parameters.
	InputSchema *jsonschema.Schema
}

type MCPListToolsResult struct {
	// ServerLabel is the MCP server label used to identify it in tool calls.
	ServerLabel string

	// Tools is the list of tools available on the server.
	Tools []*MCPListToolsItem

	// Error returned when the server fails to list tools.
	Error string
}

type MCPToolApprovalRequest struct {
	// ID is the approval request ID.
	ID string

	// Name is the name of the tool to run.
	Name string

	// Arguments is the JSON string arguments for the tool call.
	Arguments string

	// ServerLabel is the MCP server label used to identify it in tool calls.
	ServerLabel string
}

type MCPToolApprovalResponse struct {
	// ApprovalRequestID is the approval request ID being responded to.
	ApprovalRequestID string

	// Approve indicates whether the request is approved.
	Approve bool

	// Reason is the rationale for the decision.
	// Optional.
	Reason string
}

type MCPToolCall struct {
	// ServerLabel is the MCP server label used to identify it in tool calls
	ServerLabel string

	// ApprovalRequestID is the approval request ID.
	ApprovalRequestID string

	// CallID is the unique ID of the tool call.
	CallID string

	// Name is the name of the tool to run.
	Name string

	// Arguments is the JSON string arguments for the tool call.
	Arguments string
}

type MCPToolCallError struct {
	// Code is the error code.
	Code *int64

	// Message is the error message.
	Message string
}

type MCPToolResult struct {
	// ServerLabel is the MCP server label used to identify it in tool calls
	ServerLabel string

	// CallID is the unique ID of the tool call.
	CallID string

	// Name is the name of the tool to run.
	Name string

	// Result is the JSON string with the tool result.
	Result string

	// Error returned when the server fails to run the tool.
	Error *MCPToolCallError
}

type Message struct {
	Role RoleType `json:"role"`

	// Content is for user text input and model text output.
	Content string `json:"content"`

	// if MultiContent is not empty, use this instead of Content
	// if MultiContent is empty, use Content
	// Deprecated: Use UserInputMultiContent for user multimodal inputs and AssistantGenMultiContent for model multimodal outputs.
	MultiContent []ChatMessagePart `json:"multi_content,omitempty"`

	// UserInputMultiContent passes multimodal content provided by the user to the model.
	UserInputMultiContent []MessageInputPart `json:"user_input_multi_content,omitempty"`

	// AssistantGenMultiContent is for receiving multimodal output from the model.
	AssistantGenMultiContent []MessageOutputPart `json:"assistant_output_multi_content,omitempty"`

	Name string `json:"name,omitempty"`

	// only for AssistantMessage
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`

	// only for ToolMessage
	ToolCallID string `json:"tool_call_id,omitempty"`
	// only for ToolMessage
	ToolName string `json:"tool_name,omitempty"`

	ResponseMeta *ResponseMeta `json:"response_meta,omitempty"`

	// ReasoningContent is the thinking process of the model, which will be included when the model returns reasoning content.
	ReasoningContent string `json:"reasoning_content,omitempty"`

	// customized information for model implementation
	Extra map[string]any `json:"extra,omitempty"`
}

type MessageInputAudio struct {
	MessagePartCommon
}

type MessageInputFile struct {
	MessagePartCommon

	// Name represents the filename.
	// Optional.
	Name string `json:"name,omitempty"`
}

type MessageInputImage struct {
	MessagePartCommon

	// Detail is the quality of the image url.
	Detail ImageURLDetail `json:"detail,omitempty"`
}

type MessageInputPart struct {
	Type ChatMessagePartType `json:"type"`

	Text string `json:"text,omitempty"`

	// Image is the image input of the part, it's used when Type is "image_url".
	Image *MessageInputImage `json:"image,omitempty"`

	// Audio  is the audio input of the part, it's used when Type is "audio_url".
	Audio *MessageInputAudio `json:"audio,omitempty"`

	// Video is the video input of the part, it's used when Type is "video_url".
	Video *MessageInputVideo `json:"video,omitempty"`

	// File is the file input of the part, it's used when Type is "file_url".
	File *MessageInputFile `json:"file,omitempty"`

	// Extra is used to store extra information.
	Extra map[string]any `json:"extra,omitempty"`
}

type MessageInputVideo struct {
	MessagePartCommon
}

type MessageJSONParseConfig struct {
	// parse from content or tool call, default is content.
	ParseFrom MessageParseFrom `json:"parse_from,omitempty"`

	// parse key path, default is empty.
	// must be a valid json path expression, eg: field.sub_field
	ParseKeyPath string `json:"parse_key_path,omitempty"`
}

type MessageJSONParser[T any] struct {
	ParseFrom    MessageParseFrom
	ParseKeyPath string
}

type MessageOutputAudio struct {
	MessagePartCommon
}

type MessageOutputImage struct {
	MessagePartCommon
}

type MessageOutputPart struct {
	// Type is the type of the part, eg. "text", "image_url", "audio_url", "video_url".
	Type ChatMessagePartType `json:"type"`

	// Text is the text of the part, it's used when Type is "text".
	Text string `json:"text,omitempty"`

	// Image is the image output of the part, used when Type is ChatMessagePartTypeImageURL.
	Image *MessageOutputImage `json:"image,omitempty"`

	// Audio is the audio output of the part, used when Type is ChatMessagePartTypeAudioURL.
	Audio *MessageOutputAudio `json:"audio,omitempty"`

	// Video is the video output of the part, used when Type is ChatMessagePartTypeVideoURL.
	Video *MessageOutputVideo `json:"video,omitempty"`

	// Extra is used to store extra information.
	Extra map[string]any `json:"extra,omitempty"`
}

type MessageOutputVideo struct {
	MessagePartCommon
}

type MessageParseFrom string

type MessageParser[T any] interface {
	Parse(ctx context.Context, m *Message) (T, error)
}

type MessagePartCommon struct {
	// URL is primarily used for HTTP or HTTPS access links.
	// For data in the format 'data:[<mediatype>][;base64],<data>' (the 'data' URL Schema of RFC-2397 (https://www.rfc-editor.org/rfc/rfc2397)),
	// it is recommended to use Base64Data and MIMEType fields separately instead.
	URL *string `json:"url,omitempty"`

	// Base64Data represents the binary data in Base64 encoded string format.
	Base64Data *string `json:"base64data,omitempty"`

	// MIMEType is the mime type , eg."image/png",""audio/wav" etc.
	MIMEType string `json:"mime_type,omitempty"`

	// Extra is used to store extra information.
	Extra map[string]any `json:"extra,omitempty"`
}

type MessagesTemplate interface {
	Format(ctx context.Context, vs map[string]any, formatType FormatType) ([]*Message, error)
}

type ParameterInfo struct {
	// The type of the parameter.
	Type DataType
	// The element type of the parameter, only for array.
	ElemInfo *ParameterInfo
	// The sub parameters of the parameter, only for object.
	SubParams map[string]*ParameterInfo
	// The description of the parameter.
	Desc string
	// The enum values of the parameter, only for string.
	Enum []string
	// Whether the parameter is required.
	Required bool
}

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

type PromptTokenDetails struct {
	// Cached tokens present in the prompt.
	CachedTokens int `json:"cached_tokens"`
}

type Reasoning struct {
	// Text is either the thought summary or the raw reasoning text itself.
	Text string

	// Signature contains encrypted reasoning tokens.
	// Required by some models when passing reasoning text back.
	Signature string
}

type ResponseMeta struct {
	// FinishReason is the reason why the chat response is finished.
	// It's usually "stop", "length", "tool_calls", "content_filter", "null". This is defined by chat model implementation.
	FinishReason string `json:"finish_reason,omitempty"`
	// Usage is the token usage of the chat response, whether usage exists depends on whether the chat model implementation returns.
	Usage *TokenUsage `json:"usage,omitempty"`
	// LogProbs is Log probability information.
	LogProbs *LogProbs `json:"logprobs,omitempty"`
}

type RoleType string

type ServerToolCall struct {
	// Name specifies the server-side tool invoked.
	// Supplied by the model server (e.g., `web_search` for OpenAI, `googleSearch` for Gemini).
	Name string

	// CallID is the unique identifier for the tool call.
	// Empty if not provided by the model server.
	CallID string

	// Arguments are the raw inputs to the server-side tool,
	// supplied by the component implementer.
	Arguments any
}

type ServerToolResult struct {
	// Name specifies the server-side tool invoked.
	// Supplied by the model server (e.g., `web_search` for OpenAI, `googleSearch` for Gemini).
	Name string

	// CallID is the unique identifier for the tool call.
	// Empty if not provided by the model server.
	CallID string

	// Result refers to the raw output generated by the server-side tool,
	// supplied by the component implementer.
	Result any
}

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

type StreamReader[T any] struct {
	// contains filtered or unexported fields
}

type StreamWriter[T any] struct {
	// contains filtered or unexported fields
}

type StreamingMeta struct {
	// Index specifies the index position of this block in the final response.
	Index int
}

type TokenUsage struct {
	// PromptTokens is the number of prompt tokens, including all the input tokens of this request.
	PromptTokens int `json:"prompt_tokens"`
	// PromptTokenDetails is a breakdown of the prompt tokens.
	PromptTokenDetails PromptTokenDetails `json:"prompt_token_details"`
	// CompletionTokens is the number of completion tokens.
	CompletionTokens int `json:"completion_tokens"`
	// TotalTokens is the total number of tokens.
	TotalTokens int `json:"total_tokens"`
	// CompletionTokensDetails is breakdown of completion tokens.
	CompletionTokensDetails CompletionTokensDetails `json:"completion_token_details"`
}

type ToolCall struct {
	// Index is used when there are multiple tool calls in a message.
	// In stream mode, it's used to identify the chunk of the tool call for merging.
	Index *int `json:"index,omitempty"`
	// ID is the id of the tool call, it can be used to identify the specific tool call.
	ID string `json:"id"`
	// Type is the type of the tool call, default is "function".
	Type string `json:"type"`
	// Function is the function call to be made.
	Function FunctionCall `json:"function"`

	// Extra is used to store extra information for the tool call.
	Extra map[string]any `json:"extra,omitempty"`
}

type ToolChoice string

type ToolInfo struct {
	// The unique name of the tool that clearly communicates its purpose.
	Name string
	// Used to tell the model how/when/why to use the tool.
	// You can provide few-shot examples as a part of the description.
	Desc string
	// Extra is the extra information for the tool.
	Extra map[string]any

	// The parameters the functions accepts (different models may require different parameter types).
	// can be described in two ways:
	//  - use params: schema.NewParamsOneOfByParams(params)
	//  - use jsonschema: schema.NewParamsOneOfByJSONSchema(jsonschema)
	// If is nil, signals that the tool does not need any input parameter
	*ParamsOneOf
}

type ToolMessageOption func(*toolMessageOptions)

type TopLogProb struct {
	// Token represents the text of the token, which is a contiguous sequence of characters
	// (e.g., a word, part of a word, or punctuation) as understood by the tokenization process used by the language model.
	Token string `json:"token"`
	// LogProb is the log probability of this token, if it is within the top 20 most likely tokens.
	// Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.
	LogProb float64 `json:"logprob"`
	// Bytes is a list of integers representing the UTF-8 bytes representation of the token.
	// Useful in instances where characters are represented by multiple tokens and
	// their byte representations must be combined to generate the correct text
	// representation. Can be `null` if there is no bytes representation for the token.
	Bytes []int64 `json:"bytes,omitempty"`
}

type UserInputAudio struct {
	// URL is the HTTP/HTTPS link.
	URL string

	// Base64Data is the binary data in Base64 encoded string format.
	Base64Data string

	// MIMEType is the mime type, e.g. "audio/wav".
	MIMEType string
}

type UserInputFile struct {
	// URL is the HTTP/HTTPS link.
	URL string

	// Name is the filename.
	Name string

	// Base64Data is the binary data in Base64 encoded string format.
	Base64Data string

	// MIMEType is the mime type, e.g. "application/pdf".
	MIMEType string
}

type UserInputImage struct {
	// URL is the HTTP/HTTPS link.
	URL string

	// Base64Data is the binary data in Base64 encoded string format.
	Base64Data string

	// MIMEType is the mime type, e.g. "image/png".
	MIMEType string

	// Detail is the quality of the image url.
	Detail ImageURLDetail
}

type UserInputText struct {
	// Text is the text content.
	Text string
}

type UserInputVideo struct {
	// URL is the HTTP/HTTPS link.
	URL string

	// Base64Data is the binary data in Base64 encoded string format.
	Base64Data string

	// MIMEType is the mime type, e.g. "video/mp4".
	MIMEType string
}