llm

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

type AuthMode string

type ChatChunk struct {
	// Content is a text delta.
	Content string
	// ToolCalls carries incremental tool-call fragments (argument text arrives
	// across multiple chunks and must be accumulated by the caller).
	ToolCalls []ToolCall
	// FinishReason is set on the final chunk when the model signals a stop.
	FinishReason string
}

type ChatRequest struct {
	// Model overrides the provider's configured default model. Empty = default.
	Model string
	// Messages is the full conversation history in order.
	Messages []Message
	// Tools is the set of tool definitions to expose to the model.
	Tools []ToolDefinition
	// Temperature controls sampling. 0 = deterministic (default).
	Temperature float64
	// MaxTokens caps the completion length. 0 = provider default.
	MaxTokens int
	// ResponseFormat constrains output to a JSON Schema. Non-nil only in
	// Plan-and-Execute mode (TAD §11.3). Providers that do not support it
	// (SupportsStructuredOutput() == false) ignore it.
	ResponseFormat *JSONSchemaFormat
}

type ChatResponse struct {
	// Content is the model's text output (empty when ToolCalls is non-empty).
	Content string
	// ToolCalls is the set of function invocations the model requested.
	ToolCalls []ToolCall
	// Usage reports token consumption for this completion.
	Usage TokenUsage
	// FinishReason is a provider-agnostic stop cause: "stop", "length",
	// "tool_calls", "content_filter", ...
	FinishReason string
}

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

type GatewayOptions struct {
	// FailoverThreshold is the number of consecutive failures that opens a
	// provider's circuit. Default: 3.
	FailoverThreshold int
	// Cooldown is how long an open circuit stays open before a probe request
	// is allowed through. Default: 30s.
	Cooldown time.Duration
}

type HTTPStatusError struct {
	StatusCode int
	Message    string
}

type JSONSchemaFormat struct {
	Name   string
	Schema map[string]any
}

type Message struct {
	// Role identifies the speaker: "system" | "user" | "assistant" | "tool".
	Role string
	// Content is the plain-text body of the message.
	Content string
	// Name is the tool name for "tool" role messages.
	Name string
	// ToolCallID ties a "tool" role message to the assistant's tool call.
	ToolCallID string
	// ToolCalls appears on "assistant" messages that invoke tools.
	ToolCalls []ToolCall
}

type ModelInfo struct {
	// Name is the provider model identifier.
	Name string
	// SupportsTools mirrors Provider.SupportsToolCalling.
	SupportsTools bool
	// SupportsStructuredOutput mirrors Provider.SupportsStructuredOutput.
	SupportsStructuredOutput bool
}

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

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

type Provider interface {
	// ChatCompletion performs a complete, non-streaming chat round trip.
	ChatCompletion(ctx context.Context, req ChatRequest) (*ChatResponse, error)

	// StreamChatCompletion performs a streaming chat round trip. The initial
	// request is made synchronously so connection-level failures are returned
	// as the error; once established, partial results arrive on the channel,
	// which the provider closes when the stream completes. A stream that fails
	// mid-flight is closed early (the TAD §2.7 contract carries no per-chunk
	// error field, so callers must treat a short stream as an error).
	StreamChatCompletion(ctx context.Context, req ChatRequest) (<-chan ChatChunk, error)

	// SupportsToolCalling reports whether the provider can emit and consume
	// function-call tool definitions.
	SupportsToolCalling() bool

	// SupportsStructuredOutput reports whether the provider can constrain
	// output to a JSON Schema via ChatRequest.ResponseFormat.
	SupportsStructuredOutput() bool

	// ModelInfo returns static capabilities for the provider's configured model.
	ModelInfo() ModelInfo
}

type ProviderOptions struct {
	// APIKey is the provider secret.
	APIKey string
	// Model is the default model identifier.
	Model string
	// BaseURL overrides the provider endpoint (defaults to the official
	// endpoint; required for openai_compatible). Tests point this at an
	// httptest.Server.
	BaseURL string
	// MaxTokens is the default completion token cap (0 = provider default).
	MaxTokens int
	// HTTPClient overrides the shared HTTP client (tests inject a short one).
	HTTPClient *http.Client
	// Auth selects the authentication mode (see AuthMode). Zero value means
	// the provider's default: AuthBearer for openai, AuthBearerIfKey for
	// openai_compatible.
	Auth AuthMode
	// ToolCalling and StructuredOutput override the adapter's capability
	// report. OpenAI-compatible servers vary in support, so per-instance
	// overrides let a self-hosted endpoint disable features it lacks.
	// nil = adapter default.
	ToolCalling      *bool
	StructuredOutput *bool
}

type TokenUsage struct {
	PromptTokens     int
	CompletionTokens int
	TotalTokens      int
}

type ToolCall struct {
	// ID is the provider-assigned invocation id, echoed back on the tool result.
	ID string
	// Name is the tool name the model chose to invoke.
	Name string
	// Arguments is the JSON-encoded argument map the model produced.
	Arguments string
}

type ToolDefinition struct {
	Name        string
	Description string
	// Parameters is a JSON Schema object ("type": "object", "properties",
	// "required", ...). See TAD §10.2 for the field-mapping rules.
	Parameters map[string]any
}