provider

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

type AudioChunk struct {
	Format     string `json:"format,omitempty"` // "pcm16","opus","mp3"
	SampleRate int    `json:"sample_rate,omitempty"`
	Data       []byte `json:"data,omitempty"`       // raw bytes; encoders may base64
	Transcript string `json:"transcript,omitempty"` // partial transcript for realtime
}

type BiStream interface {
	Stream

	// Send pushes a client event upstream. May return ErrNotSupported on
	// streams that don't accept the requested event type.
	Send(ctx context.Context, evt ClientEvent) error
}

type Capabilities struct {
	Chat       bool `json:"chat"`       // Chat completions
	Streaming  bool `json:"streaming"`  // SSE streaming
	Embeddings bool `json:"embeddings"` // Text embeddings
	Images     bool `json:"images"`     // Image generation
	Vision     bool `json:"vision"`     // Image input in messages
	Tools      bool `json:"tools"`      // Function/tool calling
	JSON       bool `json:"json"`       // Structured JSON output
	Audio      bool `json:"audio"`      // Audio input/output
	Thinking   bool `json:"thinking"`   // Extended thinking / reasoning
	Batch      bool `json:"batch"`      // Batch API support

	// Streaming-specific capabilities — describe what the provider can
	// surface incrementally during a stream. Use these for feature
	// detection at the gateway (e.g. only forward reasoning deltas to
	// clients that explicitly opted in).
	StreamingReasoning bool `json:"streaming_reasoning,omitempty"` // emits delta.reasoning
	StreamingTools     bool `json:"streaming_tools,omitempty"`     // emits incremental tool-call deltas
	StreamingAudio     bool `json:"streaming_audio,omitempty"`     // emits delta.audio chunks
	StreamingCitations bool `json:"streaming_citations,omitempty"` // emits delta.citations
	RealtimeAudio      bool `json:"realtime_audio,omitempty"`      // bidirectional realtime audio (OpenAI Realtime)
	RealtimeVideo      bool `json:"realtime_video,omitempty"`      // bidirectional realtime video
	LiveBidi           bool `json:"live_bidi,omitempty"`           // bidirectional live API (Gemini Live)
}

type ChannelOptions struct {
	// Buffer is the channel capacity. Default: 16. Use 0 for an unbuffered
	// channel (slowest consumer fully gates the producer).
	Buffer int

	// EmitErrorChunk, when true, sends a final EventError chunk over the
	// channel before closing on a non-EOF error. Consumers that select on
	// the channel will see the error in-band rather than having to call
	// Stream.Next themselves. Default: true.
	EmitErrorChunk bool
}

type Choice struct {
	Index        int     `json:"index"`
	Message      Message `json:"message"`
	FinishReason string  `json:"finish_reason"`
}

type Citation struct {
	URL      string `json:"url,omitempty"`
	Title    string `json:"title,omitempty"`
	Quoted   string `json:"quoted,omitempty"`
	StartIdx int    `json:"start_idx,omitempty"`
	EndIdx   int    `json:"end_idx,omitempty"`
}

type ClientEvent struct {
	// Type identifies the variant. Common values:
	//   "audio_chunk" — Audio populated; appends a partial audio buffer
	//   "image"       — Image populated; uploads a still frame
	//   "commit"      — finalize the current input turn (Realtime API)
	//   "cancel"      — abort the current response generation
	//   "control"     — provider-specific Data payload
	Type string

	Audio *AudioChunk
	Image *ImageChunk

	// Data is a free-form payload for provider-specific control messages.
	// JSON-marshalable; the upstream provider deserializes it.
	Data any
}

type CompletionRequest struct {
	// Routing
	Model    string `json:"model"`
	Provider string `json:"provider,omitempty"` // force specific provider

	// Messages
	Messages []Message `json:"messages"`
	System   string    `json:"system,omitempty"` // system prompt (Anthropic-style)

	// Parameters
	MaxTokens   int      `json:"max_tokens,omitempty"`
	Temperature *float64 `json:"temperature,omitempty"`
	TopP        *float64 `json:"top_p,omitempty"`
	Stop        []string `json:"stop,omitempty"`
	Stream      bool     `json:"stream,omitempty"`

	// Tool calling
	Tools      []Tool `json:"tools,omitempty"`
	ToolChoice any    `json:"tool_choice,omitempty"` // honoured by anthropic, openai (and providers built on it) and azureopenai; others drop it

	// Structured output
	ResponseFormat *ResponseFormat `json:"response_format,omitempty"`

	// Extended thinking / reasoning
	Thinking *ThinkingConfig `json:"thinking,omitempty"`

	// Nexus metadata (not sent to provider)
	TenantID string            `json:"-"`
	KeyID    string            `json:"-"`
	Metadata map[string]string `json:"-"` // user-defined labels
}

type CompletionResponse struct {
	ID       string    `json:"id"`
	Provider string    `json:"provider"`
	Model    string    `json:"model"`
	Created  time.Time `json:"created"`

	// Content
	Choices []Choice `json:"choices"`

	// Usage
	Usage Usage `json:"usage"`

	// Nexus metadata
	Cached  bool          `json:"cached,omitempty"`
	Latency time.Duration `json:"latency,omitempty"`
	Cost    *money.USD    `json:"cost,omitempty"` // exact; nil until something prices the request

	// Extended thinking
	ThinkingContent string `json:"thinking_content,omitempty"`
	ThinkingTokens  int    `json:"thinking_tokens,omitempty"`

	// State is used to pass metadata between middleware layers.
	State map[string]any `json:"-"`
}

type ContentPart struct {
	Type     string `json:"type"` // text, image_url, image_base64
	Text     string `json:"text,omitempty"`
	ImageURL string `json:"image_url,omitempty"`
	Data     string `json:"data,omitempty"` // base64
	MimeType string `json:"mime_type,omitempty"`
}

type Credential struct {
	// APIKey replaces the provider's configured key for the request. It is
	// a secret: nothing logs it or puts it in an error, and Credential's
	// String and GoString leave it out.
	APIKey string
	// BaseURL replaces the provider's configured base URL for the request.
	// "" keeps the configured one. A credential with a BaseURL brings its
	// own APIKey: the provider sends that key, empty or not, and never its
	// configured one, to the host this URL names.
	//
	// Nexus trusts the URL as given and sends the request body there. A
	// host that lets tenants choose it must validate it first: allow only
	// https (or the schemes it means to), refuse private, loopback,
	// link-local and cloud metadata addresses, and guard against DNS
	// rebinding by checking the address the name resolves to at dial time,
	// not only when the URL is saved.
	BaseURL string
}

type CredentialAware interface {
	AcceptsCredentials() bool
}

type CredentialProvider interface {
	// GetCredential returns the current credential (API key) for a
	// provider, or ErrCredentialNotFound when it has none.
	GetCredential(ctx context.Context, providerName string) (string, error)
}

type CredentialResolver interface {
	ResolveCredential(ctx context.Context, providerName string) (Credential, error)
}

type Delta struct {
	Role      string     `json:"role,omitempty"`
	Content   string     `json:"content,omitempty"`
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`

	// Reasoning carries extended-thinking content (o1, Claude thinking_delta,
	// DeepSeek R1 reasoning_content). Emitted alongside (or before) Content.
	Reasoning string `json:"reasoning,omitempty"`

	// Refusal is an OpenAI-style structured refusal string.
	Refusal string `json:"refusal,omitempty"`

	// Citations carries grounding / source references.
	Citations []Citation `json:"citations,omitempty"`

	// Audio carries a multi-modal audio chunk (raw bytes + optional transcript).
	Audio *AudioChunk `json:"audio,omitempty"`

	// Image carries a multi-modal image chunk (raw bytes or URL).
	Image *ImageChunk `json:"image,omitempty"`

	// Transcript is a partial speech transcript (realtime / live APIs).
	Transcript string `json:"transcript,omitempty"`

	// Native is the whole reply in the provider's own format, set on the
	// EventMessageStop chunk. The accumulator copies it to Message.Native.
	Native *NativeContent `json:"-"`
}

type DimensionsAware interface {
	SupportsDimensions(model string) bool
}

type EmbeddingRequest struct {
	Model    string   `json:"model"`
	Provider string   `json:"provider,omitempty"` // force specific provider
	Input    []string `json:"input"`
	// Dimensions asks for vectors of exactly this many numbers; 0 keeps the
	// model's default. The gateway refuses it for a provider that cannot
	// honour it (see DimensionsAware) and fails a response whose vectors
	// have another length.
	Dimensions int    `json:"dimensions,omitempty"`
	TenantID   string `json:"-"`
	KeyID      string `json:"-"`
	// Metadata is stored on the usage record, where it can be filtered by
	// (see usage.ValidateMetadata for the limits).
	Metadata map[string]string `json:"-"`
}

type EmbeddingResponse struct {
	Provider   string      `json:"provider"`
	Model      string      `json:"model"`
	Embeddings [][]float64 `json:"embeddings"`
	Usage      Usage       `json:"usage"`
}

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

type EventKind string

type FreeOfCharge interface {
	FreeOfCharge() bool
}

type HealthStats struct {
	TotalRequests int           `json:"total_requests"`
	Successes     int           `json:"successes"`
	Failures      int           `json:"failures"`
	SuccessRate   float64       `json:"success_rate"`
	AvgLatency    time.Duration `json:"avg_latency"`
	P99Latency    time.Duration `json:"p99_latency"`
	LastSuccess   time.Time     `json:"last_success,omitempty"`
	LastFailure   time.Time     `json:"last_failure,omitempty"`
	LastError     string        `json:"last_error,omitempty"`
}

type HealthTracker interface {
	// RecordSuccess records a successful provider call.
	RecordSuccess(providerName string, latency time.Duration)

	// RecordFailure records a failed provider call.
	RecordFailure(providerName string, err error)

	// Stats returns health statistics for a provider.
	Stats(providerName string) *HealthStats

	// IsHealthy returns true if the provider is considered healthy.
	IsHealthy(providerName string) bool

	// AllStats returns stats for all tracked providers.
	AllStats() map[string]*HealthStats
}

type ImageChunk struct {
	MimeType string `json:"mime_type,omitempty"`
	Data     []byte `json:"data,omitempty"`
	URL      string `json:"url,omitempty"`
	Partial  bool   `json:"partial,omitempty"` // true while incremental, false on final
}

type JSONSchemaDef struct {
	// Name is a free-form identifier OpenAI requires (any non-empty string).
	Name string `json:"name"`
	// Description is optional human-readable hint for the model.
	Description string `json:"description,omitempty"`
	// Schema is the JSON Schema document (object with type/properties/required).
	Schema any `json:"schema"`
	// Strict enables strict mode — model output must validate against Schema.
	Strict bool `json:"strict,omitempty"`
}

type Message struct {
	Role       string     `json:"role"` // system, user, assistant, tool
	Content    any        `json:"content"`
	Name       string     `json:"name,omitempty"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`

	// Native is the assistant reply in the provider's own format. Keep it
	// with the message and pass it back unchanged; see NativeContent.
	Native *NativeContent `json:"-"`
}

type Model struct {
	ID            string       `json:"id"`       // e.g., "gpt-4o"
	Provider      string       `json:"provider"` // e.g., "openai"
	Name          string       `json:"name"`     // human-readable
	Capabilities  Capabilities `json:"capabilities"`
	ContextWindow int          `json:"context_window"`
	MaxOutput     int          `json:"max_output"`
	Pricing       Pricing      `json:"pricing"`
}

type NativeContent struct {
	// Provider names the provider whose wire format Content is in.
	Provider string `json:"provider"`
	// Model is the model that produced the reply.
	Model string `json:"model"`
	// Content is the reply's content as that provider returned it.
	Content json.RawMessage `json:"content"`
}

type Pricing struct {
	InputPerMillion          money.USD `json:"input_per_million"`
	OutputPerMillion         money.USD `json:"output_per_million"`
	EmbeddingPerMillion      money.USD `json:"embedding_per_million,omitzero"`
	CacheReadPerMillion      money.USD `json:"cache_read_per_million,omitzero"`
	CacheWritePerMillion     money.USD `json:"cache_write_per_million,omitzero"`      // 5-minute cache writes
	CacheWriteLongPerMillion money.USD `json:"cache_write_long_per_million,omitzero"` // 1-hour cache writes
	LongContextAbove         int       `json:"long_context_above,omitempty"`          // prompt tokens; 0 means no tier
	LongContext              *Pricing  `json:"long_context,omitempty"`
	Free                     bool      `json:"free,omitempty"`
}

type Provider interface {
	// Name returns the provider identifier (e.g., "openai", "anthropic").
	Name() string

	// Capabilities returns what this provider supports.
	Capabilities() Capabilities

	// Models returns the list of available models.
	Models(ctx context.Context) ([]Model, error)

	// Complete sends a chat completion request.
	Complete(ctx context.Context, req *CompletionRequest) (*CompletionResponse, error)

	// CompleteStream sends a streaming chat completion request.
	CompleteStream(ctx context.Context, req *CompletionRequest) (Stream, error)

	// Embed sends an embedding request (if supported).
	Embed(ctx context.Context, req *EmbeddingRequest) (*EmbeddingResponse, error)

	// Healthy returns true if the provider is reachable.
	Healthy(ctx context.Context) bool
}

type Registry interface {
	// Register adds a provider to the registry.
	Register(p Provider)

	// Get returns a provider by name.
	Get(name string) (Provider, bool)

	// All returns all registered providers.
	All() []Provider

	// Count returns the number of registered providers.
	Count() int

	// ForModel returns the providers whose Models list the model, in
	// registration order. A provider whose Models fails is left out.
	ForModel(model string) []Provider

	// WithCapability returns providers with a specific capability.
	WithCapability(capability string) []Provider

	// Healthy returns only healthy providers.
	Healthy(ctx context.Context) []Provider
}

type ResponseFormat struct {
	Type       string         `json:"type"` // text, json_object, json_schema
	Schema     any            `json:"schema,omitempty"`
	JSONSchema *JSONSchemaDef `json:"json_schema,omitempty"`
}

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

type Stream interface {
	// Next returns the next chunk. Returns io.EOF when done.
	Next(ctx context.Context) (*StreamChunk, error)

	// Close releases resources.
	Close() error

	// Usage returns final usage after stream completes.
	Usage() *Usage
}

type StreamChunk struct {
	ID           string    `json:"id"`
	Provider     string    `json:"provider"`
	Model        string    `json:"model"`
	Kind         EventKind `json:"kind,omitempty"`
	Delta        Delta     `json:"delta"`
	FinishReason string    `json:"finish_reason,omitempty"`

	// Optional payloads — populated based on Kind.
	Usage   *Usage `json:"usage,omitempty"`   // EventUsage / final delta
	Err     string `json:"error,omitempty"`   // EventError
	Created int64  `json:"created,omitempty"` // unix ms; used for cache-replay timing
}

type StreamEvents interface {
	Events(ctx context.Context) <-chan StreamChunk
}

type ThinkingConfig struct {
	Enabled         bool `json:"enabled,omitempty"`
	BudgetTokens    int  `json:"budget_tokens,omitempty"`
	IncludeThinking bool `json:"include_thinking,omitempty"`
	// Effort steers how much the model thinks and spends: "low", "medium",
	// "high", "xhigh" or "max". Empty keeps the model's default. A provider
	// that knows the model rejects a level the model does not accept.
	Effort string `json:"effort,omitempty"`
}

type Tool struct {
	Type     string       `json:"type"` // function
	Function ToolFunction `json:"function"`
}

type ToolCall struct {
	ID       string       `json:"id"`
	Type     string       `json:"type"`
	Function ToolCallFunc `json:"function"`
}

type ToolCallFunc struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

type ToolChoice struct {
	Mode     ToolChoiceMode
	Function string // set when Mode is ToolChoiceFunction
}

type ToolChoiceMode string

type ToolFunction struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Parameters  any    `json:"parameters,omitempty"` // JSON Schema
}

type TransportWrapper interface {
	WrapTransport(wrap func(http.RoundTripper) http.RoundTripper)
}

type Usage struct {
	PromptTokens         int `json:"prompt_tokens"`
	CompletionTokens     int `json:"completion_tokens"`
	ThinkingTokens       int `json:"thinking_tokens,omitempty"`
	CacheReadTokens      int `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens     int `json:"cache_write_tokens,omitempty"`
	CacheWriteLongTokens int `json:"cache_write_long_tokens,omitempty"`
	TotalTokens          int `json:"total_tokens"`
}