llm

type Capabilities struct {
	// Streaming reports whether Provider.Stream produces real incremental
	// output. It is false for providers whose Stream is a formality.
	Streaming bool
	// Tools reports whether CompletionRequest.Tools is honored.
	Tools bool
	// Images reports whether PartImage is honored.
	Images bool
	// Reasoning reports whether CompletionRequest.ReasoningEffort is honored
	// and PartThinking parts come back.
	Reasoning bool
	// StructuredOutput reports whether CompletionRequest.ResponseFormat is
	// honored.
	StructuredOutput bool
}

type CompletionRequest struct {
	// Temperature controls randomness, conventionally in [0, 2].
	Temperature *float64
	// TopP controls nucleus sampling, in [0, 1]. Setting it alongside
	// Temperature is accepted but rarely what anyone wants.
	TopP *float64
	// MaxTokens caps the response length. Anthropic requires one and the
	// provider layer supplies a default when this is nil.
	MaxTokens *int
	// Seed asks for reproducible sampling. Best-effort everywhere.
	Seed *int
	// ParallelToolCalls allows the model to request several tools at once.
	ParallelToolCalls *bool
	// ResponseFormat constrains the response to a JSON schema.
	ResponseFormat *ResponseFormat
	// ToolChoice constrains which of Tools the model may call.
	ToolChoice *ToolChoice
	// Model is the provider's model identifier. Empty means the provider's
	// configured default.
	Model string
	// System is the system prompt. See Role for why it is a field rather than a
	// message.
	System string
	// ReasoningEffort asks for extended thinking.
	ReasoningEffort ReasoningEffort
	// Messages is the conversation so far, oldest first. At least one is
	// required.
	Messages []Message
	// Tools are the tools the model may call.
	Tools []Tool
	// StopSequences are strings that end generation when produced.
	StopSequences []string
}

type CompletionResponse struct {
	// Usage is the token accounting for the request, when the provider
	// reported it.
	Usage *Usage
	// ID is the provider's identifier for the response.
	ID string
	// Model is the model that actually answered, which can differ from the one
	// requested when the provider resolves an alias.
	Model string
	// StopReason is why generation ended.
	StopReason StopReason
	// Content is what the model produced, in order. See Part.
	Content []Part
}

type Event struct {
	ToolUse    *ToolUse
	Usage      *Usage
	Type       EventType
	Text       string
	StopReason StopReason
}

type EventType string

type Image struct {
	// URL is an http(s) URL or a data: URI the provider fetches or decodes.
	URL string
	// MediaType is the IANA media type of Data, e.g. "image/png". It is
	// required with Data and ignored with URL, whose own media type is either
	// implied by the server or already inside the data URI.
	MediaType string
	// Data is the raw image bytes, which the provider layer encodes as a data
	// URI. MediaType must be set alongside it.
	Data []byte
}

type Message struct {
	Role    Role
	Content []Part
}

type Part struct {
	Image      *Image
	ToolUse    *ToolUse
	ToolResult *ToolResult
	Type       PartType
	Text       string
}

type PartType string

type Provider interface {
	// Name identifies the provider, e.g. "anthropic". It is stable and safe to
	// use as a metric label or a persisted discriminator.
	Name() string
	// Capabilities reports what the provider supports.
	Capabilities() Capabilities
	// Completion answers the request in full.
	Completion(ctx context.Context, req *CompletionRequest) (*CompletionResponse, error)
	// Stream answers the request incrementally. The returned Stream must be
	// closed. The error is for failures that happen before the stream starts;
	// failures during it surface from Stream.Err.
	Stream(ctx context.Context, req *CompletionRequest) (Stream, error)
}

type RateLimitError struct {
	// RetryAfter is how long the provider asked the caller to wait. It is zero
	// when the provider did not say, which is not the same as "retry
	// immediately" — a caller with no advice should fall back to its own
	// backoff.
	RetryAfter time.Duration
}

type ReasoningEffort string

type ResponseFormat struct {
	// Schema is the JSON Schema the response must satisfy, as a decoded object.
	Schema map[string]any
	// Name identifies the schema to the provider. Required.
	Name string
	// Strict asks the provider to guarantee conformance rather than merely
	// prompt for it, where it can.
	Strict bool
}

type Role string

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

type StopReason string

type Stream interface {
	// Next advances to the next event, reporting whether there is one.
	Next() bool
	// Current returns the event Next advanced to. It is only valid after Next
	// returned true.
	Current() Event
	// Err returns the error that stopped the stream, or nil if it ended
	// cleanly or is still running.
	Err() error
	// Close releases the stream's resources. It is idempotent.
	Close() error
}

type Tool struct {
	// Schema is the JSON Schema describing the tool's input, as a decoded
	// object. It reaches the provider unchanged.
	Schema map[string]any
	// Name is what the model names in a ToolUse.
	Name string
	// Description tells the model when to call the tool. It is prompt text and
	// carries most of the weight of getting tool use right.
	Description string
}

type ToolChoice struct {
	// Name is the tool to call. It is required when Mode is
	// ToolChoiceSpecific and ignored otherwise.
	Name string
	// Mode is how the choice is constrained. The zero value is not a valid
	// mode; leave ToolChoice nil rather than sending an empty one.
	Mode ToolChoiceMode
}

type ToolChoiceMode string

type ToolResult struct {
	// ToolUseID is the ID of the ToolUse this answers.
	ToolUseID string
	// Content is what the tool produced, as text. Structured results should be
	// marshaled to JSON by the caller.
	Content string
	// IsError reports that the tool failed. The providers' normalized wire
	// shape has no flag for this, so it is conveyed to the model by prefixing
	// Content with "error: " — the model still learns the call failed, which is
	// the point, but the transport is a convention rather than a field.
	IsError bool
}

type ToolUse struct {
	// ID correlates this call with the ToolResult that answers it.
	ID string
	// Name is the Tool.Name the model chose.
	Name string
	// Input is the tool's arguments as JSON, shaped by the Tool's Schema. It is
	// the model's output and therefore untrusted: it may not validate against
	// the schema, and it may not be valid JSON at all if the model was cut off.
	Input json.RawMessage
}

type Usage struct {
	// InputTokens is what the prompt cost.
	InputTokens int
	// OutputTokens is what the response cost, including reasoning tokens where
	// the provider bills them that way.
	OutputTokens int
	// ReasoningTokens is the reasoning portion, when the provider breaks it
	// out.
	ReasoningTokens int
	// TotalTokens is the provider's own total. It is reported rather than
	// derived, because a provider that discounts or surcharges some tokens
	// disagrees with InputTokens + OutputTokens on purpose.
	TotalTokens int
}