ai

type Allowance struct {
	Unit     string    `json:"unit"` // e.g. "tokens", "requests"
	Used     int64     `json:"used"`
	Limit    int64     `json:"limit"`
	ResetsAt time.Time `json:"resetsAt,omitzero"`
}

type ChatRequest struct {
	// Product identifies the consuming product ("sneat", "datatug", ...) for
	// cloud metering, limits and routing. BYOK adapters ignore it.
	Product string `json:"product"`
	// Model is a concrete model ID, ModelAuto, or "" (same as ModelAuto).
	Model string `json:"model,omitempty"`
	// System is the stable system prompt.
	System string `json:"system,omitempty"`
	// Context blocks are rendered after System, static blocks first, in the
	// given order, so the static prefix is cacheable.
	Context  []ContextBlock `json:"context,omitempty"`
	Messages []Message      `json:"messages"`
	// MaxTokens caps output; 0 means the adapter default.
	MaxTokens int `json:"maxTokens,omitempty"`
	// ResponseSchema, when set, asks for a JSON object matching this JSON
	// Schema. Adapters use native structured output where the provider has it
	// and otherwise instruct the model; either way the final object arrives as
	// an EventStructured event (text deltas may still stream first).
	ResponseSchema json.RawMessage `json:"responseSchema,omitempty"`
	// StrictSchema controls whether an adapter with a native "strict" JSON
	// Schema mode (e.g. OpenAI's response_format.json_schema.strict) turns
	// it on for ResponseSchema. Strict mode requires the schema to follow
	// stricter authoring rules (every property required, no bare optional
	// fields, additionalProperties:false throughout); a caller whose schema
	// doesn't meet them sets StrictSchema to a false pointer to opt out. Nil
	// (the default) means strict when the adapter supports it.
	StrictSchema *bool `json:"strictSchema,omitempty"`
	// Metadata is opaque key/value data forwarded to the cloud for diagnostics
	// (e.g. "path": "llm-fallback"). Never put secrets or user content here.
	Metadata map[string]string `json:"metadata,omitempty"`
	// Tools the model may call this turn.
	Tools []Tool `json:"tools,omitempty"`
	// ToolChoice: "" (adapter default) | "auto" | "none" | "required" | a
	// specific tool name.
	ToolChoice string `json:"toolChoice,omitempty"`
	// Reasoning requests extended/deliberate reasoning where the provider
	// supports it: "" | "low" | "medium" | "high". Adapters map it to their
	// own knob (OpenAI-compatible reasoning_effort, Anthropic extended
	// thinking budget) and ignore it where unsupported.
	Reasoning string `json:"reasoning,omitempty"`
}

type ContextBlock struct {
	Scope string      `json:"scope"`
	Kind  ContextKind `json:"kind"`
	Name  string      `json:"name"`
	Text  string      `json:"text"`
}

type ContextKind string

type Error struct {
	Code      string `json:"code"`
	Message   string `json:"message"`
	Retryable bool   `json:"retryable,omitempty"`
}

type Event struct {
	Type EventType `json:"type"`
	// Started: which provider/model is actually answering.
	Provider string `json:"provider,omitempty"`
	Model    string `json:"model,omitempty"`
	// TextDelta: the next chunk of text.
	Text string `json:"text,omitempty"`
	// Structured: the final JSON object for ChatRequest.ResponseSchema.
	Structured json.RawMessage `json:"structured,omitempty"`
	// Usage / Completed: token and allowance accounting when known.
	Usage *Usage `json:"usage,omitempty"`
	// Error: a terminal or non-terminal provider error.
	Error *Error `json:"error,omitempty"`
	// ToolCall: set on EventToolCall, one fully-assembled call.
	ToolCall *ToolCall `json:"toolCall,omitempty"`
	// ToolResult: set on EventToolResult (ai/agent only).
	ToolResult *ToolResult `json:"toolResult,omitempty"`
	// StopReason: set on EventCompleted; "tool_calls" | "end" | "length".
	StopReason string `json:"stopReason,omitempty"`
	// ProviderState: set on EventCompleted when the adapter captured
	// provider-specific state (e.g. ai/anthropic's thinking/
	// redacted_thinking blocks with signatures) that MUST be attached to the
	// assistant message this turn produces — see Message.ProviderState.
	ProviderState json.RawMessage `json:"providerState,omitempty"`
}

type EventType string

type LLMProvider interface {
	// Name identifies the provider in diagnostics ("cloud",
	// "openai-compatible", "openai-responses", "anthropic").
	Name() string
	Stream(ctx context.Context, req ChatRequest) iter.Seq2[Event, error]
}

type Message struct {
	Role Role   `json:"role"`
	Text string `json:"text"`
	// ToolCalls is set on an assistant message that invoked tools.
	ToolCalls []ToolCall `json:"toolCalls,omitempty"`
	// ToolResults is set on a RoleTool message answering prior ToolCalls.
	ToolResults []ToolResult `json:"toolResults,omitempty"`
	// ProviderState is opaque, provider-specific extra content an adapter
	// attached to an assistant message it produced (e.g. ai/anthropic's
	// extended-thinking/redacted-thinking blocks, signature included) and
	// that same adapter MUST replay unmodified on a later request that
	// includes this message — some providers 400 a tool-use continuation
	// that drops or edits the thinking blocks from the turn that requested
	// the tool call. Populated from Event.ProviderState (see EventCompleted)
	// by whoever appends the assistant message (e.g. ai/agent.Loop). An
	// adapter that doesn't understand another adapter's ProviderState MUST
	// ignore it rather than error.
	ProviderState json.RawMessage `json:"providerState,omitempty"`
}

type Role string

type Tool struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Schema      json.RawMessage `json:"schema"`
}

type ToolCall struct {
	ID        string          `json:"id"`
	Name      string          `json:"name"`
	Arguments json.RawMessage `json:"arguments"`
}

type ToolResult struct {
	CallID  string `json:"callId"`
	Content string `json:"content"`
	IsError bool   `json:"isError,omitempty"`
}

type Usage struct {
	InputTokens  int64 `json:"inputTokens,omitempty"`
	OutputTokens int64 `json:"outputTokens,omitempty"`
	// CacheReadTokens counts tokens served from a prompt cache.
	// ai/openaicompat populates it from
	// usage.prompt_tokens_details.cached_tokens: this is an INFORMATIONAL
	// SUBSET already counted inside InputTokens (OpenAI's prompt_tokens
	// includes cached tokens; the details object only breaks out how many
	// of them were cache hits) — do NOT add it to InputTokens. ai/anthropic
	// populates it from usage.cache_read_input_tokens: on the Messages API
	// this is the OPPOSITE relationship — Anthropic's input_tokens counts
	// ONLY the tokens actually processed fresh, and cache_read_input_tokens
	// (billed at its own, cheaper per-token rate) is NOT included in it —
	// so for ai/anthropic, CacheReadTokens IS additive to InputTokens.
	CacheReadTokens int64 `json:"cacheReadTokens,omitempty"`
	// CacheWriteTokens counts tokens written to a prompt cache. Only
	// ai/anthropic populates it, from usage.cache_creation_input_tokens —
	// same additive relationship to InputTokens as CacheReadTokens above
	// (billed separately, at its own higher per-token rate, and not
	// included in input_tokens). ai/openaicompat never populates this
	// field: OpenAI's API has no separate cache-write concept to report.
	CacheWriteTokens int64 `json:"cacheWriteTokens,omitempty"`
	// ReasoningTokens counts provider-side reasoning/thinking tokens, ONLY
	// on adapters that report them SEPARATELY from OutputTokens.
	// ai/openaicompat populates it from
	// usage.completion_tokens_details.reasoning_tokens when the API returns
	// that field: this is an INFORMATIONAL SUBSET already counted inside
	// OutputTokens (OpenAI's completion_tokens includes reasoning tokens;
	// the details object only breaks out how many of them were spent on
	// reasoning) — do NOT add it to OutputTokens. ai/anthropic leaves it
	// zero: the Messages API's usage object has no separate thinking-token
	// count — thinking tokens are already included in OutputTokens
	// (usage.output_tokens), not broken out on top of it, so there is
	// nothing distinct to report here without double-counting.
	ReasoningTokens int64 `json:"reasoningTokens,omitempty"`
	// Allowance is set by the cloud provider (ai/cloud); nil for BYOK.
	Allowance *Allowance `json:"allowance,omitempty"`
}