provider

type AnthropicOptions struct {
	Provider              string
	Model                 string
	BaseURL               string
	APIKey                string
	StateCompatibilityKey string
	HTTPClient            *http.Client
	Capabilities          Capabilities
}

type Attachment struct {
	ResourceRef string               `json:"resource_ref"`
	Name        string               `json:"name"`
	MIMEType    string               `json:"mime_type"`
	SizeBytes   int64                `json:"size_bytes,omitempty"`
	TextStats   *AttachmentTextStats `json:"text_stats,omitempty"`
}

type AttachmentPayloadMode string

type AttachmentTextStats struct {
	UnicodeCodePointCount int64 `json:"unicode_code_points"`
	LogicalLineCount      int64 `json:"logical_lines"`
}

type Capabilities struct {
	// OutputControl declares whether a client output ceiling is enforced.
	OutputControl       OutputControl              `json:"output_control,omitempty"`
	Reasoning           ReasoningSupport           `json:"reasoning"`
	ReasoningCapability config.ReasoningCapability `json:"reasoning_capability,omitempty"`
	AttachmentPayload   AttachmentPayloadMode      `json:"attachment_payload"`
	ReasoningHistory    ReasoningHistoryPolicy     `json:"reasoning_history,omitempty"`
}

type ContentAttributionPart struct {
	// Category optionally identifies a span within merged protocol instructions.
	Category string `json:"category,omitempty"`
	Start    int    `json:"start"`
	End      int    `json:"end"`
	Key      string `json:"key,omitempty"`
}

type DeepSeekOptions struct {
	Model                 string
	BaseURL               string
	APIKey                string
	StateCompatibilityKey string
	HTTPClient            *http.Client
	Temperature           *float64
	TopP                  *float64
	ResponseFormat        string
	// ResolveAttachment resolves an authorized opaque attachment into image bytes.
	// It runs during Prepare (or Stream for direct callers), never during replay
	// of a prepared request. Nil preserves descriptor-only behavior. The gateway
	// accepts images only when the selected model advertises image input.
	ResolveAttachment func(context.Context, Attachment) ([]byte, error)
}

type Event struct {
	Type           EventType         `json:"type"`
	Text           string            `json:"text,omitempty"`
	ToolCallStream *ToolCallStream   `json:"tool_call_stream,omitempty"`
	ToolCalls      []ToolCall        `json:"tool_calls,omitempty"`
	HostedToolCall *ToolCall         `json:"hosted_tool_call,omitempty"`
	HostedResult   *HostedToolResult `json:"hosted_result,omitempty"`
	Sources        []Source          `json:"sources,omitempty"`
	Reason         string            `json:"reason,omitempty"`
	Usage          Usage             `json:"usage,omitempty"`
	ResponseID     string            `json:"response_id,omitempty"`
	ResponseState  *State            `json:"response_state,omitempty"`
	Err            error             `json:"-"`
}

type EventType string

type Gateway interface {
	Identity() Identity
	Capabilities() Capabilities
	Stream(context.Context, Request) (<-chan Event, error)
}

type HostedToolDefinition struct {
	// ReplaySafe permits repeating the entire model request after uncertain dispatch.
	ReplaySafe  bool           `json:"replay_safe,omitempty"`
	Name        string         `json:"name"`
	Type        string         `json:"type"`
	Description string         `json:"description,omitempty"`
	Parameters  map[string]any `json:"parameters,omitempty"`
	Options     map[string]any `json:"options,omitempty"`
}

type HostedToolResult struct {
	// ResultsProvided is true when the provider returned a structured result list, including an empty list.
	ResultsProvided bool                   `json:"results_provided,omitempty"`
	Text            string                 `json:"text,omitempty"`
	Results         []HostedToolResultItem `json:"results,omitempty"`
	Error           *HostedToolResultError `json:"error,omitempty"`
	Metadata        map[string]any         `json:"metadata,omitempty"`
}

type HostedToolResultError struct {
	Code    string `json:"code,omitempty"`
	Message string `json:"message,omitempty"`
}

type HostedToolResultItem struct {
	Title    string         `json:"title,omitempty"`
	URL      string         `json:"url,omitempty"`
	Snippet  string         `json:"snippet,omitempty"`
	Source   string         `json:"source,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type Identity struct {
	Provider              string `json:"provider"`
	Model                 string `json:"model"`
	StateCompatibilityKey string `json:"state_compatibility_key"`
}

type Labels struct {
	Correlation map[string]string `json:"correlation,omitempty"`
	Host        map[string]string `json:"host,omitempty"`
}

type Message struct {
	// Attribution is observation-only provenance, never model input.
	Attribution *MessageAttribution `json:"attribution,omitempty"`
	Role        MessageRole         `json:"role"`
	Text        string              `json:"text,omitempty"`
	Attachments []Attachment        `json:"attachments,omitempty"`
	Reasoning   string              `json:"reasoning,omitempty"`
	ToolCalls   []ToolCall          `json:"tool_calls,omitempty"`
	ToolResult  *ToolResult         `json:"tool_result,omitempty"`
}

type MessageAttribution struct {
	Category string                   `json:"category"`
	Parts    []ContentAttributionPart `json:"parts,omitempty"`
}

type MessageRole string

type OpenAICompatibleOptions struct {
	Provider              string
	Model                 string
	BaseURL               string
	APIKey                string
	StateCompatibilityKey string
	HTTPClient            *http.Client
	Capabilities          Capabilities
}

type OutputControl string

type PreparedRequest interface {
	Stream(context.Context) (<-chan Event, error)
	TokenEstimate() TokenEstimate
	RenderedPayloadFingerprint() string
	Close() error
}

type PreparedRequestOutputLimiter interface {
	WithMaxOutputTokens(context.Context, int64) (PreparedRequest, error)
}

type PreparedRequestReplay interface {
	PrepareRetry(context.Context, Request) (PreparedRequest, error)
}

type ProviderHTTPError struct {
	Provider   string
	StatusCode int
	Code       string
	Message    string
}

type ReasoningHistoryPolicy string

type ReasoningSupport string

type RenderedContentAttribution struct {
	Path      string
	Category  string
	Key       string
	Source    string
	Namespace string
	Parts     []ContentAttributionPart
}

type RenderedRequest struct {
	// Attribution refers only to decoded values in Payload using JSON Pointer paths.
	Attribution []RenderedContentAttribution
	Provider    string
	Model       string
	Format      RequestFormat
	Payload     []byte
}

type Request struct {
	RunID            identity.RunID            `json:"run_id"`
	ThreadID         identity.ThreadID         `json:"thread_id,omitempty"`
	TurnID           identity.TurnID           `json:"turn_id,omitempty"`
	TraceID          identity.TraceID          `json:"trace_id,omitempty"`
	PromptScopeID    identity.PromptScopeID    `json:"prompt_scope_id"`
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id,omitempty"`
	AttemptID        string                    `json:"attempt_id,omitempty"`
	AttemptEpoch     int                       `json:"attempt_epoch,omitempty"`
	Step             int                       `json:"step"`
	Messages         []Message                 `json:"messages"`
	Tools            []tools.ToolDefinition    `json:"tools,omitempty"`
	HostedTools      []HostedToolDefinition    `json:"hosted_tools,omitempty"`
	MaxOutputTokens  int64                     `json:"max_output_tokens,omitempty"`
	Reasoning        config.ReasoningSelection `json:"reasoning,omitempty"`
	PreviousState    *State                    `json:"previous_state,omitempty"`
	// ReusePolicy is always set by the runtime. Nil preserves gateway defaults
	// for callers constructing requests outside the Engine.
	ReusePolicy *RequestReusePolicy `json:"reuse_policy,omitempty"`
	Labels      Labels              `json:"labels,omitempty"`
}

type RequestFormat string

type RequestPreparer interface {
	Prepare(context.Context, Request) (PreparedRequest, error)
}

type RequestReusePolicy struct {
	PromptCacheEnabled   bool   `json:"prompt_cache_enabled"`
	PromptCacheNamespace string `json:"prompt_cache_namespace,omitempty"`
	ProviderStateAllowed bool   `json:"provider_state_allowed"`
	PreferContinuation   bool   `json:"prefer_continuation"`
}

type RequestTimeoutDetails = internalprovider.RequestTimeoutDetails

type RequestTimeoutError = internalprovider.RequestTimeoutError

type RetryAdvice struct {
	Category  RetryCategory `json:"category,omitempty"`
	NotBefore time.Time     `json:"not_before,omitempty"`
	Forbidden bool          `json:"forbidden,omitempty"`
}

type RetryAdviser interface{ ProviderRetryAdvice() RetryAdvice }

type RetryCategory string

type Source struct {
	Title      string `json:"title,omitempty"`
	URL        string `json:"url,omitempty"`
	StartIndex *int   `json:"start_index,omitempty"`
	EndIndex   *int   `json:"end_index,omitempty"`
}

type State struct {
	ReusePolicy StateReusePolicy  `json:"reuse_policy,omitempty"`
	Kind        string            `json:"kind,omitempty"`
	ID          string            `json:"id,omitempty"`
	Attributes  map[string]string `json:"attributes,omitempty"`
}

type StateReusePolicy string

type TokenEstimate struct {
	Breakdown config.ContextBreakdown `json:"breakdown,omitzero"`
	// AttachmentTokens is the estimated media/file subset already included in MessageTokens.
	AttachmentTokens     int64  `json:"attachment_tokens,omitempty"`
	PrefixTokens         int64  `json:"prefix_tokens,omitempty"`
	MessageTokens        int64  `json:"message_tokens,omitempty"`
	ToolDefinitionTokens int64  `json:"tool_definition_tokens,omitempty"`
	EstimatedInputTokens int64  `json:"estimated_input_tokens,omitempty"`
	Source               string `json:"source,omitempty"`
	Method               string `json:"method,omitempty"`
	Confidence           string `json:"confidence,omitempty"`
	Coverage             string `json:"coverage,omitempty"`
}

type ToolCall struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	Args string `json:"args"`
}

type ToolCallStream struct {
	ID   string `json:"id,omitempty"`
	Name string `json:"name,omitempty"`
}

type ToolResult struct {
	CallID      string       `json:"call_id"`
	ToolName    string       `json:"tool_name"`
	Text        string       `json:"text,omitempty"`
	Attachments []Attachment `json:"attachments,omitempty"`
}

type Usage struct {
	// OutputIncludesReasoning means ReasoningTokens is a subset of OutputTokens.
	OutputIncludesReasoning bool `json:"output_includes_reasoning,omitempty"`
	// TotalTokensReported distinguishes an explicit native zero from an absent total.
	TotalTokensReported bool    `json:"total_tokens_reported,omitempty"`
	InputTokens         int64   `json:"input_tokens,omitempty"`
	OutputTokens        int64   `json:"output_tokens,omitempty"`
	ReasoningTokens     int64   `json:"reasoning_tokens,omitempty"`
	CacheReadTokens     int64   `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens    int64   `json:"cache_write_tokens,omitempty"`
	TotalTokens         int64   `json:"total_tokens,omitempty"`
	CostUSD             float64 `json:"cost_usd,omitempty"`
	Source              string  `json:"source,omitempty"`
	Available           bool    `json:"available,omitempty"`
	WindowInputTokens   int64   `json:"window_input_tokens,omitempty"`
}