llm

type Accumulator struct {
	StopReason string
	Usage      Usage
	// contains filtered or unexported fields
}

type BlockType string

type BoundaryMeta struct {
	// Trigger is what caused compaction: "auto" (proactive threshold),
	// "reactive" (recovery from a prompt-too-long error), or "manual".
	Trigger string `json:"trigger,omitempty"`
	// PreTokens is the token count just before compaction.
	PreTokens int `json:"pre_tokens"`
	// MessagesSummarized is how many messages were condensed into the summary.
	MessagesSummarized int `json:"messages_summarized,omitempty"`
	// ActiveSkills names the invoked skills re-injected verbatim after this
	// boundary (diagnostics; the instructions themselves ride in the messages).
	ActiveSkills []string `json:"active_skills,omitempty"`
}

type CompletionRequest struct {
	// System is the host-controlled system prompt, in segments. The SDK injects
	// no presets (design decision 1). Segments are joined with blank lines.
	System []string
	// DynamicBoundary is the index in System separating cacheable static prefix
	// from per-request dynamic content; providers may set a cache breakpoint
	// there (FR-02.2). 0 disables.
	DynamicBoundary int
	Messages        []Message
	Tools           []ToolSchema
	MaxTokens       int
	Temperature     *float64
	Stop            []string
	// Thinking overrides the provider's thinking mode for THIS request only:
	// "" inherits Config.ThinkingType; "enabled"/"disabled" force that mode.
	// Compaction's summary call sets "disabled" so the summarizer never spends
	// tokens on reasoning and never replays thinking blocks (which Anthropic
	// rejects when thinking is off).
	Thinking string
}

type Config struct {
	Format     Format
	BaseURL    string
	APIKey     string
	Model      string
	APIVersion string // Anthropic only; default 2023-06-01
	HTTPClient *http.Client
	// Proxy, when set, routes all model requests through the given proxy URL —
	// "http://", "https://" or "socks5://" (optionally with user:pass@). It only
	// affects the built-in client: when empty, the built-in client falls back to
	// the standard HTTP_PROXY / HTTPS_PROXY / NO_PROXY environment variables.
	// Ignored when the caller supplies its own HTTPClient.
	Proxy string
	// MaxRetries bounds transient-failure retries on the model request
	// establishment (connection reset / timeout / 429 / 5xx). 0 = default 3;
	// negative disables retrying. Only the pre-stream phase is retried (safe);
	// a mid-stream drop is surfaced as an error.
	MaxRetries int
	// RetryInterval, when > 0, replaces the exponential backoff between
	// establishment retries with this FIXED wait. 0 (default) keeps the
	// 0.5s/1s/2s… ladder capped at 8s. A host that wants a predictable,
	// operator-set cadence sets both MaxRetries and this.
	RetryInterval time.Duration
	// EmptyResponseRetries bounds how many times a completed-but-EMPTY response
	// is re-requested (FormatOpenAI only; see emptyResponseRetries). 0 = default
	// 2; negative disables. Separate from MaxRetries because an empty-response
	// retry re-sends the whole prompt rather than re-establishing a request.
	EmptyResponseRetries int
	// EmptyResponseInterval, when > 0, replaces the exponential backoff before
	// each empty-response retry with this FIXED wait. 0 keeps the ladder.
	EmptyResponseInterval time.Duration
	// RateLimit, when set, bounds the request rate shared across every caller of
	// the built Provider (per-second and/or per-minute). Retries do not count.
	RateLimit *RateLimit

	// ThinkingType toggles extended/reasoning mode via the request's
	// "thinking":{"type":...} field, for both formats. "" omits it (provider
	// default); "enabled"/"disabled" are sent verbatim.
	ThinkingType string
	// ReasoningEffort sets the reasoning strength. "" omits it. For OpenAI it maps
	// to "reasoning_effort"; for Anthropic to "output_config":{"effort":...}.
	// Typical values: low / medium / high / max.
	ReasoningEffort string
	// MaxTokensField selects which request key carries the output cap on
	// FormatOpenAI (Chat Completions). "" (default) sends the classic
	// "max_tokens"; MaxTokensFieldCompletion sends "max_completion_tokens"
	// instead. OpenAI's reasoning models reject "max_tokens" outright
	// (unsupported_parameter) and accept only the newer key, whose budget covers
	// reasoning tokens plus visible output; most OpenAI-compatible gateways still
	// take the old one, hence the opt-in default. Exactly one key is ever sent.
	// Ignored by the Anthropic and Responses formats, which name the field
	// themselves ("max_tokens" / "max_output_tokens").
	MaxTokensField string
	// contains filtered or unexported fields
}

type ContentBlock struct {
	Type BlockType `json:"type"`

	// Text block.
	Text string `json:"text,omitempty"`

	// Thinking block (extended thinking). Anthropic requires the field to be
	// named "thinking" (not "text") and requires "signature" when replaying
	// the block in multi-turn history.
	Thinking  string `json:"thinking,omitempty"`
	Signature string `json:"signature,omitempty"`

	// ToolUse: a model request to invoke a tool.
	ID    string          `json:"id,omitempty"`
	Name  string          `json:"name,omitempty"`
	Input json.RawMessage `json:"input,omitempty"`

	// ToolResult: the outcome of a tool, fed back to the model.
	ToolUseID string         `json:"tool_use_id,omitempty"`
	Content   []ContentBlock `json:"content,omitempty"`
	IsError   bool           `json:"is_error,omitempty"`
}

type Format string

type Message struct {
	Role    Role           `json:"role"`
	Content []ContentBlock `json:"content"`
}

type Provider interface {
	Stream(ctx context.Context, req CompletionRequest) iter.Seq2[StreamEvent, error]
	Complete(ctx context.Context, req CompletionRequest) (Message, string, Usage, error)
}

type RateLimit struct {
	PerSecond float64 // max requests per second (0 = unlimited)
	PerMinute float64 // max requests per minute (0 = unlimited)
	// Burst is the per-second bucket capacity (how many may go at once before
	// smoothing). 0 = default to PerSecond.
	Burst float64
	// OnWait, when set, is called once per acquired request with how long the
	// caller blocked on the limiter (0 if it passed immediately). Observability
	// hook; nil disables it.
	OnWait func(blocked time.Duration)
}

type Role string

type StreamEvent struct {
	Type       StreamEventType
	Text       string // text/thinking/tool_input JSON fragment
	ToolID     string // tool_use_start
	ToolName   string // tool_use_start
	StopReason string // message_delta
	Usage      Usage  // message_start / message_delta
}

type StreamEventType string

type ToolSchema struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	InputSchema map[string]any `json:"input_schema"`
}

type Usage struct {
	InputTokens      int `json:"input_tokens"`
	OutputTokens     int `json:"output_tokens"`
	CacheReadTokens  int `json:"cache_read_tokens"`
	CacheWriteTokens int `json:"cache_write_tokens"`
}