llm

type APIError struct {
	Provider   string
	Status     int
	Message    string
	Retryable  bool
	RetryAfter time.Duration
}

type Budget interface {
	// Allow returns an error (normally wrapping ErrBudgetExceeded) when no
	// more calls may be made.
	Allow(ctx context.Context) error
	// Record adds a finished call's usage. The record names the provider and
	// the model that answered, so a budget can price what it is told.
	Record(ctx context.Context, rec CallRecord)
}

type BudgetError struct {
	Limit      Limit
	VHost      string
	WorkflowID string
	// Used and Max are tokens for the token limits and micro-units of the
	// vhost's currency for the cost limits. Both are zero for the kill switch
	// and for an unreadable budget.
	Used int64
	Max  int64
	// Cause is why the budget could not be read, for LimitUnavailable.
	Cause error
}

type CallRecord struct {
	Provider   string
	Model      string
	Usage      Usage
	Latency    time.Duration
	StopReason StopReason
	Err        error
}

type ChatRequest struct {
	// Model is the provider's model id. Adapters that have a sensible
	// default use it when this is empty; the others reject the request.
	Model    string
	System   string
	Messages []Message
	Tools    []ToolSpec
	// ResponseSchema, when set, asks for a JSON object matching this JSON
	// Schema, using the provider's native structured output where it has one.
	ResponseSchema map[string]any
	// MaxTokens caps the response. Zero means the adapter's default.
	MaxTokens int
	// Temperature is sent only when set, and only to providers whose current
	// models accept it.
	Temperature *float64
}

type ChatResponse struct {
	Text       string
	ToolCalls  []ToolCall
	StopReason StopReason
	Usage      Usage
	// Model is the model that actually answered (it can differ from the one
	// asked for when a fallback served the call).
	Model     string
	Provider  string
	RequestID string
	Latency   time.Duration
}

type EmbedRequest struct {
	Model  string
	Inputs []string
}

type EmbedResponse struct {
	Vectors [][]float32
	Usage   Usage
	Model   string
}

type Embedder interface {
	Embed(ctx context.Context, req EmbedRequest) (EmbedResponse, error)
}

type Limit string

type Message struct {
	Role        Role
	Text        string
	ToolCalls   []ToolCall
	ToolResults []ToolResult
}

type Middleware func(Provider) Provider

type Observer func(context.Context, CallRecord)

type Provider interface {
	// Name is the provider kind, e.g. "anthropic", "openai", "gemini".
	Name() string
	Chat(ctx context.Context, req ChatRequest) (ChatResponse, error)
}

type RetryPolicy struct {
	// MaxAttempts counts the first try. Values below 1 mean 1.
	MaxAttempts int
	BaseDelay   time.Duration
	MaxDelay    time.Duration
}

type Role string

type Scope struct {
	VHost      string
	WorkflowID string
}

type StopReason string

type ToolCall struct {
	ID    string
	Name  string
	Input json.RawMessage
}

type ToolResult struct {
	CallID  string
	Name    string
	Content string
	IsError bool
}

type ToolSpec struct {
	Name        string
	Description string
	Schema      map[string]any
}

type Usage struct {
	InputTokens  int64
	OutputTokens int64
}