spec

type AllowedTool struct {
	ToolChoiceID   string `json:"toolChoiceID"`
	ToolChoiceName string `json:"toolChoiceName"`
}

type CacheCapabilities struct {
	SupportsAutomaticCaching bool `json:"supportsAutomaticCaching"`

	TopLevel           *CacheControlCapabilities `json:"topLevel,omitempty"`
	InputOutputContent *CacheControlCapabilities `json:"inputOutputContent,omitempty"`
	ReasoningContent   *CacheControlCapabilities `json:"reasoningContent,omitempty"`
	ToolChoice         *CacheControlCapabilities `json:"toolChoice,omitempty"`
	ToolCall           *CacheControlCapabilities `json:"toolCall,omitempty"`
	ToolOutput         *CacheControlCapabilities `json:"toolOutput,omitempty"`
}

type CacheControl struct {
	Kind CacheControlKind `json:"kind"`

	// Optional. If empty and CacheControl is explicitly set, provider default may apply.
	TTL CacheControlTTL `json:"ttl,omitempty"`

	// Optional request-level cache key. Relevant for OpenAI-style root caching.
	// Irrelevant on unsupported providers/scopes and should be ignored, not errored.
	Key string `json:"key,omitempty"`
}

type CacheControlCapabilities struct {
	// Top-level gate: whether request-side TTL/retention is supported at all.
	SupportsTTL    bool               `json:"supportsTTL"`
	SupportedKinds []CacheControlKind `json:"supportedKinds,omitempty"`
	SupportedTTLs  []CacheControlTTL  `json:"supportedTTLs,omitempty"`
	SupportsKey    bool               `json:"supportsKey"`
}

type CacheControlKind string

type CacheControlTTL string

type Citation struct {
	Kind CitationKind `json:"kind"`

	URLCitation *URLCitation `json:"urlCitation,omitempty"`
}

type CitationConfig struct {
	Enabled bool `json:"enabled"`
}

type CitationKind string

type CompletionDebugger interface {
	// HTTPClient is called once when the provider initializes its SDK client.
	//
	// The debugger can:
	//   - wrap base (change Transport),
	//   - ignore base and create a new client,
	//   - or return nil to say "use provider's default client".
	HTTPClient(base *http.Client) *http.Client

	// StartSpan is called at the beginning of FetchCompletion.
	//
	// It can:
	//   - inspect the request to decide whether to debug,
	//   - attach per-request state to the context (e.g., via context keys),
	//   - return a span handle that will be ended when the call finishes.
	//
	// If span is nil, no debugging will be performed for this call.
	StartSpan(
		ctx context.Context,
		info *CompletionSpanStart,
	) (ctxWithSpan context.Context, span CompletionSpan)
}

type CompletionSpan interface {
	// End is called exactly once, just before FetchCompletion returns.
	//
	// It can:
	//   - pull any per-request state from the context,
	//   - inspect raw/normalized responses and errors,
	//   - return arbitrary data to attach to Response.DebugDetails.
	//
	// Returning nil means "no debug details for this call".
	End(info *CompletionSpanEnd) any
}

type CompletionSpanEnd struct {
	// Raw SDK response (e.g. *responses.Response for OpenAI). May be nil.
	ProviderResponse any

	// Error from the provider/stream if any.
	Err error

	// Normalized response object that the caller is about to return.
	// May be nil. MUST be treated as read-only.
	Response *FetchCompletionResponse
}

type CompletionSpanStart struct {
	Provider ProviderName
	Model    ModelName

	// Original request and options for this completion.
	// These may be nil and MUST be treated as read-only.
	Request *FetchCompletionRequest
	Options *FetchCompletionOptions
}

type ContentItemFile struct {
	ID       string `json:"id,omitzero"`
	FileName string `json:"fileName,omitzero"`
	FileMIME string `json:"fileMIME,omitzero"`
	FileURL  string `json:"fileURL,omitzero"`

	FileData          string          `json:"fileData,omitzero"`
	AdditionalContext string          `json:"additionalContext,omitzero"`
	CitationConfig    *CitationConfig `json:"citationConfig"`
}

type ContentItemImage struct {
	ID        string      `json:"id,omitzero"`
	Detail    ImageDetail `json:"detail,omitzero"`
	ImageName string      `json:"imageName,omitzero"`
	ImageMIME string      `json:"imageMIME,omitzero"`
	ImageURL  string      `json:"imageURL,omitzero"`
	ImageData string      `json:"imageData,omitzero"`
}

type ContentItemKind string

type ContentItemRefusal struct {
	Refusal string `json:"refusal"`
}

type ContentItemText struct {
	Text      string     `json:"text"`
	Citations []Citation `json:"citations,omitempty"`
	Signature string     `json:"signature,omitzero"`
}

type Error struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

type FetchCompletionOptions struct {
	// CompletionKey is an opaque, runtime-only key that is passed in runtime operations
	// It can be used by the capability resolver to map arbitrary user/model identifiers to capability profiles.
	CompletionKey string `json:"-"`

	// StreamHandler, if non-nil, is invoked with incremental streaming events
	// when ModelParam.Stream is true. Returning a non-nil error will stop
	// streaming early and propagate that error back to the caller.
	StreamHandler StreamHandler `json:"-"`
	StreamConfig  *StreamConfig `json:"streamConfig,omitempty"`

	// CapabilityResolver, if non-nil, is used to resolve model capabilities for request validation/normalization.
	// Else, inbuilt SDK capabilities are enforced.
	CapabilityResolver ModelCapabilityResolver `json:"-"`
}

type FetchCompletionRequest struct {
	ModelParam ModelParam   `json:"modelParam"`
	Inputs     []InputUnion `json:"inputs"`

	// ToolPolicy - optional control on how (or whether) the model may use the provided ToolChoices.
	ToolPolicy  *ToolPolicy  `json:"toolPolicy,omitempty"`
	ToolChoices []ToolChoice `json:"toolChoices,omitempty"`
}

type FetchCompletionResponse struct {
	Outputs      []OutputUnion `json:"outputs,omitempty"`
	Usage        *Usage        `json:"usage,omitempty"`
	Error        *Error        `json:"error,omitempty"`
	Warnings     []Warning     `json:"warnings,omitempty"`
	DebugDetails any           `json:"debugDetails,omitempty"`
}

type ImageDetail string

type InputKind string

type InputOutputContent struct {
	ID           string        `json:"id"`
	Role         RoleEnum      `json:"role"`
	Status       Status        `json:"status,omitzero"`
	CacheControl *CacheControl `json:"cacheControl,omitempty"`

	Contents []InputOutputContentItemUnion `json:"contents,omitempty"`
}

type InputOutputContentItemUnion struct {
	Kind ContentItemKind `json:"kind"`

	TextItem    *ContentItemText    `json:"textItem,omitempty"`
	RefusalItem *ContentItemRefusal `json:"refusalItem,omitempty"`
	ImageItem   *ContentItemImage   `json:"imageItem,omitempty"`
	FileItem    *ContentItemFile    `json:"fileItem,omitempty"`
}

type InputUnion struct {
	Kind InputKind `json:"kind"`

	InputMessage        *InputOutputContent `json:"inputMessage,omitempty"`
	OutputMessage       *InputOutputContent `json:"outputMessage,omitempty"`
	ReasoningMessage    *ReasoningContent   `json:"reasoningMessage,omitempty"`
	FunctionToolCall    *ToolCall           `json:"functionToolCall,omitempty"`
	FunctionToolOutput  *ToolOutput         `json:"functionToolOutput,omitempty"`
	CustomToolCall      *ToolCall           `json:"customToolCall,omitempty"`
	CustomToolOutput    *ToolOutput         `json:"customToolOutput,omitempty"`
	WebSearchToolCall   *ToolCall           `json:"webSearchToolCall,omitempty"`
	WebSearchToolOutput *ToolOutput         `json:"webSearchToolOutput,omitempty"`
}

type JSONSchemaParam struct {
	// Name - must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64..
	Name string `json:"name"`

	// Description: Optional description of what the response format is for, used by the model to determine how to
	// respond in the format.
	Description string `json:"description,omitempty"`

	// JSON Schema payload when Type == jsonSchema.
	Schema map[string]any `json:"schema,omitempty"`

	// Strict requests stricter adherence where supported.
	Strict bool `json:"strict,omitempty"`
}

type MaxOutputTokensParamName string

type Modality string

type ModelCapabilities struct {
	ModalitiesIn  []Modality `json:"modalitiesIn"`
	ModalitiesOut []Modality `json:"modalitiesOut"`

	ReasoningCapabilities    *ReasoningCapabilities    `json:"reasoningCapabilities,omitempty"`
	StopSequenceCapabilities *StopSequenceCapabilities `json:"stopSequenceCapabilities,omitempty"`
	OutputCapabilities       *OutputCapabilities       `json:"outputCapabilities,omitempty"`
	ToolCapabilities         *ToolCapabilities         `json:"toolCapabilities,omitempty"`
	CacheCapabilities        *CacheCapabilities        `json:"cacheCapabilities,omitempty"`
	ParamDialect             *ParamDialect             `json:"paramDialect,omitempty"`
}

type ModelCapabilityResolver interface {
	ResolveModelCapabilities(ctx context.Context, req ResolveModelCapabilitiesRequest) (*ModelCapabilities, error)
}

type ModelName string

type ModelParam struct {
	Name            ModelName       `json:"name"`
	Stream          bool            `json:"stream"`
	MaxPromptLength int             `json:"maxPromptLength"`
	MaxOutputLength int             `json:"maxOutputLength"`
	Temperature     *float64        `json:"temperature,omitempty"`
	Reasoning       *ReasoningParam `json:"reasoning,omitempty"`
	SystemPrompt    string          `json:"systemPrompt"`
	Timeout         int             `json:"timeout"`

	CacheControl *CacheControl `json:"cacheControl,omitempty"`

	// OutputParam controls the model's output format.
	//
	// Cross-provider notes:
	//   - OpenAI Chat Completions: maps to response_format + verbosity.
	//   - OpenAI Responses: maps to text.
	//   - Anthropic Messages: supports jsonSchema via output_config.format; verbosity maps to output_config.effort.
	OutputParam *OutputParam `json:"outputParam,omitempty"`

	// StopSequences requests provider-side stop sequences when supported.
	// Cross-provider notes:
	//   - OpenAI Chat Completions: maps to stop. Up to 4 sequences supported. Not supported by reasoning models
	//   - OpenAI Responses: Not supported.
	//   - Anthropic Messages: maps to stop_sequences.
	StopSequences []string `json:"stopSequences,omitempty"`

	AdditionalParametersRawJSON *string `json:"additionalParametersRawJSON"`
}

type OpenAIChatCompletionsParamDialect struct{}

type OutputCapabilities struct {
	SupportedOutputFormats []OutputFormatKind `json:"supportedOutputFormats"`
	SupportsVerbosity      bool               `json:"supportsVerbosity"`
}

type OutputFormat struct {
	// Can be text or JSONSchema. We don't support JSONObject as it is recommended to move to JSONSchema type.
	Kind OutputFormatKind `json:"kind"`

	JSONSchemaParam *JSONSchemaParam `json:"jsonSchemaParam,omitempty"`
}

type OutputFormatKind string

type OutputKind string

type OutputParam struct {
	Format *OutputFormat `json:"format,omitempty"`
	// Maps to "Verbosity" in OpenAI, "Effort" in Anthropic.
	Verbosity *OutputVerbosity `json:"verbosity,omitempty"`
}

type OutputUnion struct {
	Kind OutputKind `json:"kind"`

	OutputMessage       *InputOutputContent `json:"outputMessage,omitempty"`
	ReasoningMessage    *ReasoningContent   `json:"reasoningMessage,omitempty"`
	FunctionToolCall    *ToolCall           `json:"functionToolCall,omitempty"`
	CustomToolCall      *ToolCall           `json:"customToolCall,omitempty"`
	WebSearchToolCall   *ToolCall           `json:"webSearchToolCall,omitempty"`
	WebSearchToolOutput *ToolOutput         `json:"webSearchToolOutput,omitempty"`
}

type OutputVerbosity string

type ParamDialect struct {
	MaxOutputTokensParamName MaxOutputTokensParamName `json:"maxOutputTokensParamName,omitempty"`
	ToolChoiceParamStyle     ToolChoiceParamStyle     `json:"toolChoiceParamStyle,omitempty"`
}

type ProviderName string

type ProviderParam struct {
	Name                     ProviderName      `json:"name"`
	SDKType                  ProviderSDKType   `json:"sdkType"`
	APIKey                   string            `json:"apiKey"`
	Origin                   string            `json:"origin"`
	ChatCompletionPathPrefix string            `json:"chatCompletionPathPrefix"`
	APIKeyHeaderKey          string            `json:"apiKeyHeaderKey"`
	DefaultHeaders           map[string]string `json:"defaultHeaders"`
}

type ProviderSDKType string

type ReasoningCapabilities struct {
	// Top-level gate: whether request-side reasoning config is supported at all.
	// If false, ModelParam.Reasoning must not be sent.
	SupportsReasoningConfig bool `json:"supportsReasoningConfig"`

	SupportedReasoningTypes          []ReasoningType                   `json:"supportedReasoningTypes"`
	SupportedReasoningLevels         []ReasoningLevel                  `json:"supportedReasoningLevels"`
	HybridTokenBudgetCapabilities    *ReasoningTokenBudgetCapabilities `json:"hybridTokenBudgetCapabilities,omitempty"`
	SupportsSummaryStyle             bool                              `json:"supportsSummaryStyle"`
	SupportsEncryptedReasoningInput  bool                              `json:"supportsEncryptedReasoningInput"`
	TemperatureDisallowedWhenEnabled bool                              `json:"temperatureDisallowedWhenEnabled"`
}

type ReasoningContent struct {
	ID           string        `json:"id"`
	Role         RoleEnum      `json:"role"`
	Status       Status        `json:"status,omitzero"`
	CacheControl *CacheControl `json:"cacheControl,omitempty"`

	Signature        string   `json:"signature,omitzero"`
	Summary          []string `json:"summary,omitempty"`
	Thinking         []string `json:"thinking,omitempty"`
	RedactedThinking []string `json:"redactedThinking,omitempty"`
	EncryptedContent []string `json:"encryptedContent,omitempty"`
}

type ReasoningLevel string

type ReasoningParam struct {
	Type   ReasoningType  `json:"type"`
	Level  ReasoningLevel `json:"level"`
	Tokens int            `json:"tokens"`
	// SummaryStyle - what kind of summary should be emitted for the reasoning performed by the model.
	// SummaryStyle is supported by OpenAI responses only.
	SummaryStyle *ReasoningSummaryStyle `json:"summaryStyle,omitempty"`
}

type ReasoningSummaryStyle string

type ReasoningTokenBudgetCapabilities struct {
	MinAllowed      int  `json:"minAllowed,omitempty"`
	MaxAllowed      int  `json:"maxAllowed,omitempty"`
	ZeroAllowed     bool `json:"zeroAllowed,omitempty"`
	MinusOneAllowed bool `json:"minusOneAllowed,omitempty"`
}

type ReasoningType string

type ResolveModelCapabilitiesRequest struct {
	ProviderSDKType ProviderSDKType `json:"providerSDKType"`
	ModelName       ModelName       `json:"modelName"`
	CompletionKey   string          `json:"completionKey"`
}

type RoleEnum string

type Status string

type StopSequenceCapabilities struct {
	IsSupported             bool `json:"isSupported"`
	DisallowedWithReasoning bool `json:"disallowedWithReasoning"`
	MaxSequences            int  `json:"maxSequences"`
}

type StreamConfig struct {
	// FlushIntervalMillis is the maximum delay between flushes of buffered stream data to the StreamHandler.
	FlushIntervalMillis int `json:"flushIntervalMillis,omitempty"`
	// FlushChunkSize is the approximate target size (in bytes/characters) for chunks passed to the StreamHandler.
	FlushChunkSize int `json:"flushChunkSize,omitempty"`
}

type StreamContentKind string

type StreamEvent struct {
	Kind StreamContentKind `json:"kind"`

	// Optional metadata to help consumers correlate events across models/providers.
	Provider      ProviderName `json:"provider,omitempty"`
	Model         ModelName    `json:"model,omitempty"`
	CompletionKey string       `json:"completionKey,omitempty"`

	// Exactly one of the below will be non-nil depending on Kind.
	Text     *StreamTextChunk     `json:"text,omitempty"`
	Thinking *StreamThinkingChunk `json:"thinking,omitempty"`
}

type StreamHandler func(event StreamEvent) error

type StreamTextChunk struct {
	Text string `json:"text"`
}

type StreamThinkingChunk struct {
	Text string `json:"text"`
}

type ToolCall struct {
	Type ToolType `json:"type"`

	ChoiceID     string        `json:"choiceID"`
	ID           string        `json:"id"`
	Role         RoleEnum      `json:"role"`
	Status       Status        `json:"status,omitzero"`
	CacheControl *CacheControl `json:"cacheControl,omitempty"`

	CallID                 string                       `json:"callID"`
	Name                   string                       `json:"name"`
	Arguments              string                       `json:"arguments,omitempty"`
	Signature              string                       `json:"signature,omitzero"`
	WebSearchToolCallItems []WebSearchToolCallItemUnion `json:"webSearchToolCallItems,omitempty"`
}

type ToolCapabilities struct {
	SupportedToolTypes               []ToolType             `json:"supportedToolTypes"`
	SupportedToolPolicyModes         []ToolPolicyMode       `json:"supportedToolPolicyModes"`
	SupportsParallelToolCalls        bool                   `json:"supportsParallelToolCalls"`
	MaxForcedTools                   int                    `json:"maxForcedTools"`
	SupportedClientToolOutputFormats []ToolOutputFormatKind `json:"supportedClientToolOutputFormats,omitempty"`
}

type ToolChoice struct {
	Type ToolType `json:"type"`

	ID           string        `json:"id"`
	CacheControl *CacheControl `json:"cacheControl,omitempty"`

	Name        string `json:"name"`
	Description string `json:"description,omitzero"`

	Arguments          map[string]any           `json:"arguments,omitempty"`
	WebSearchArguments *WebSearchToolChoiceItem `json:"webSearchArguments,omitempty"`
}

type ToolChoiceParamStyle string

type ToolOutput struct {
	Type ToolType `json:"type"`

	ChoiceID     string        `json:"choiceID"`
	ID           string        `json:"id"`
	Role         RoleEnum      `json:"role"`
	Status       Status        `json:"status,omitzero"`
	CacheControl *CacheControl `json:"cacheControl,omitempty"`

	CallID    string `json:"callID"`
	Name      string `json:"name"`
	IsError   bool   `json:"isError"`
	Signature string `json:"signature,omitzero"`

	Contents                 []ToolOutputItemUnion          `json:"contents,omitempty"`
	WebSearchToolOutputItems []WebSearchToolOutputItemUnion `json:"webSearchToolOutputItems,omitempty"`
}

type ToolOutputFormatKind string

type ToolOutputItemUnion struct {
	Kind ContentItemKind `json:"kind"`

	TextItem  *ContentItemText  `json:"textItem,omitempty"`
	ImageItem *ContentItemImage `json:"imageItem,omitempty"`
	FileItem  *ContentItemFile  `json:"fileItem,omitempty"`
}

type ToolPolicy struct {
	// Mode selects the tool policy:
	//   - auto: model may decide.
	//   - any: model must use *a* tool.
	//          OpenAI adapters map this to tool_choice="required" and (by default) allow any ToolChoice.
	//   - tool: Force a specific tool by name/ID.
	//           Anthropic directly supports. OpenAI supports this as "required" + one tool in allowed tools.
	//   - none: prohibit tool use.
	//
	// Web search note:
	// - In OpenAI Chat Completions, web search is configured via top-level web_search_options, not as a tool-call.
	//   ToolPolicy cannot “force web search” there; toolPolicy.mode=none disables it (best-effort).
	Mode ToolPolicyMode `json:"mode"`

	AllowedTools []AllowedTool `json:"allowedTools,omitempty"`

	// DisableParallel requests that the model emit at most one tool call.
	DisableParallel bool `json:"disableParallel,omitempty"`
}

type ToolPolicyMode string

type ToolType string

type URLCitation struct {
	URL       string `json:"url"`
	Title     string `json:"title,omitzero"`
	CitedText string `json:"citedText,omitzero"`

	StartIndex     int64  `json:"startIndex,omitzero"`
	EndIndex       int64  `json:"endIndex,omitzero"`
	EncryptedIndex string `json:"encryptedIndex,omitzero"`
}

type Usage struct {
	InputTokensTotal    int64 `json:"inputTokensTotal"`
	InputTokensCached   int64 `json:"inputTokensCached"`
	InputTokensUncached int64 `json:"inputTokensUncached"`
	OutputTokens        int64 `json:"outputTokens"`
	ReasoningTokens     int64 `json:"reasoningTokens"`
}

type Warning struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

type WebSearchContextSize string

type WebSearchToolCallFind struct {
	URL     string `json:"url"`
	Pattern string `json:"pattern"`
}

type WebSearchToolCallItemUnion struct {
	Kind WebSearchToolCallKind `json:"kind"`

	SearchItem   *WebSearchToolCallSearch   `json:"searchItem,omitempty"`
	OpenPageItem *WebSearchToolCallOpenPage `json:"openPageItem,omitempty"`
	FindItem     *WebSearchToolCallFind     `json:"findItem,omitempty"`
}

type WebSearchToolCallKind string

type WebSearchToolCallOpenPage struct {
	URL string `json:"url"`
}

type WebSearchToolCallSearch struct {
	Query   string                          `json:"query"`
	Sources []WebSearchToolCallSearchSource `json:"sources,omitempty"`
	Input   map[string]any                  `json:"input,omitempty"`
}

type WebSearchToolCallSearchSource struct {
	URL string `json:"url"`
}

type WebSearchToolChoiceItem struct {
	MaxUses           int64                                `json:"maxUses,omitzero"`
	SearchContextSize WebSearchContextSize                 `json:"searchContextSize,omitzero"`
	AllowedDomains    []string                             `json:"allowedDomains,omitzero"`
	BlockedDomains    []string                             `json:"blockedDomains,omitzero"`
	UserLocation      *WebSearchToolChoiceItemUserLocation `json:"userLocation,omitempty"`
}

type WebSearchToolChoiceItemUserLocation struct {
	City     string `json:"city,omitzero"`
	Country  string `json:"country,omitzero"`
	Region   string `json:"region,omitzero"`
	Timezone string `json:"timezone,omitzero"`
}

type WebSearchToolOutputError struct {
	Code string `json:"code"`
}

type WebSearchToolOutputItemUnion struct {
	Kind WebSearchToolOutputKind `json:"kind"`

	SearchItem *WebSearchToolOutputSearch `json:"searchItem,omitempty"`
	ErrorItem  *WebSearchToolOutputError  `json:"errorItem,omitempty"`
}

type WebSearchToolOutputKind string

type WebSearchToolOutputSearch struct {
	URL              string `json:"url"`
	Title            string `json:"title,omitzero"`
	EncryptedContent string `json:"encryptedContent,omitzero"`
	RenderedContent  string `json:"renderedContent,omitzero"`
	PageAge          string `json:"pageAge,omitzero"`
}