llmapi

type ContentPart struct {
	Type     ContentPartType `json:"Type"`
	Text     string          `json:"Text,omitempty"`
	ImageURL string          `json:"ImageURL,omitempty"`
}

type ContentPartType uint8

type DialogueUsage struct {
	TokensSent         int           `json:"InputTokens"`
	TokensReceived     int           `json:"OutputTokens"`
	TokensReasoned     int           `json:"ReasoningTokens"`
	TokensCached       int           `json:"CachedTokens"`
	TokensCacheCreated int           `json:"CacheCreatedTokens"`
	Completions        int           `json:"Completions"`
	ToolCalls          int           `json:"ToolCalls"`
	TotalDuration      time.Duration `json:"TotalDuration"`
	InferenceDuration  time.Duration `json:"InferenceDuration"`
	ToolCallDuration   time.Duration `json:"ToolCallDuration"`
}

type DoneData struct {
	Message      Message
	FinishReason FinishReason
	Usage        Usage
}

type ErrContextWindowExceeded struct {
	Count, Max int
}

type Event struct {
	Type      EventType
	Text      string         // EventTextDelta
	Reasoning string         // EventReasoningDelta
	ToolCall  *ToolCall      // EventToolCallDone — complete tool call
	DoneData  *DoneData      // EventStreamDone
	Error     error          // EventStreamError
	RateLimit *RateLimitInfo // EventRateLimitWarning
}

type EventType int

type FinishReason string

type FunctionCall struct {
	Name      string
	Arguments string
}

type FunctionDefinition struct {
	Name        string
	Description string
	// Parameters is an object describing the function.
	// You can pass a raw byte array describing the schema,
	// or you can pass in a struct which serializes to the proper JSONSchema.
	Parameters any
}

type Message struct {
	Role         Role          `json:"Role"`
	Content      string        `json:"Content"`
	MultiContent []ContentPart `json:"MultiContent,omitempty"`
	ToolCalls    []ToolCall    `json:"ToolCalls,omitempty"`
	ToolCallID   string        `json:"ToolCallID,omitempty"`
	Name         string        `json:"Name,omitempty"`
	// ReasoningContent is the human-readable reasoning text for display and is
	// lossy; ReasoningBlocks is the source of truth for replaying reasoning
	// back to the model (it preserves per-block signatures and order). When a
	// provider requires replay, populate ReasoningBlocks, not ReasoningContent.
	ReasoningContent string           `json:"ReasoningContent,omitempty"`
	ReasoningBlocks  []ReasoningBlock `json:"ReasoningBlocks,omitempty"`
	// ProviderItems carries opaque provider-specific items that must be
	// threaded back into the next request to maintain stateful continuity
	// (e.g. ChatGPT Codex backend reasoning items with encrypted_content
	// when store=false). Each entry is the raw JSON of a single item,
	// preserved in the order it was emitted by the provider. Cross-provider
	// code should treat this field as opaque.
	ProviderItems []json.RawMessage `json:"ProviderItems,omitempty"`
}

type ModelEntry struct {
	// Name is the model identifier (e.g. "gpt-4o", "claude-opus-4-6").
	Name string
	// Provider identifies which LLM provider serves this model
	// (e.g. "openai", "anthropic", "gemini", "ollama").
	Provider string
	// ContextWindow is the nominal maximum context window in tokens.
	ContextWindow int
	// BaseURL is the provider-specific API base URL.
	// Empty string means use the provider's default.
	BaseURL string
	// ProjectorPath is the absolute path to an optional multimodal projector
	// GGUF (mmproj) associated with a local llama.cpp model. Empty for
	// providers that do not use a separate projector file.
	ProjectorPath string
}

type RateLimitInfo struct {
	// WaitDuration is non-zero when the client is actively waiting before a retry.
	WaitDuration time.Duration
	// Message is a human-readable warning composed by the client.
	Message string
}

type ReasoningBlock struct {
	Kind      string `json:"Kind"`
	Text      string `json:"Text,omitempty"`
	Signature string `json:"Signature,omitempty"`
	Data      string `json:"Data,omitempty"`
}

type ReasoningEffort string

type ReasoningSummary string

type Request struct {
	Messages          []Message
	Tools             []Tool
	ToolChoice        ToolChoice
	ParallelToolCalls *bool
	ReasoningEffort   ReasoningEffort
	ReasoningSummary  ReasoningSummary
	MaxOutputTokens   int
	ResponseFormat    *ResponseFormat

	// PromptCacheKey is a stable identifier (typically the dialogue ID)
	// that the provider uses for server-side prompt caching. Requests
	// sharing the same key get a ~90% discount on repeated input-token
	// prefixes. Works without storing responses server-side, preserving
	// Zero Data Retention compatibility.
	PromptCacheKey string

	// TokenCount, when set, is used for the context-window safety check
	// instead of calling CountTokens. The agent loop pre-computes this
	// from the provider-reported usage (or CountTokens + tool estimate on
	// the first turn), so passing it here avoids a redundant re-count on
	// every CreateCompletion call.
	TokenCount int
}

type ResponseFormat struct {
	Type       ResponseFormatType        `json:"type,omitempty"`
	JSONSchema *ResponseFormatJSONSchema `json:"json_schema,omitempty"`
}

type ResponseFormatJSONSchema struct {
	Name        string
	Description string
	Schema      json.Marshaler
	Strict      bool
}

type ResponseFormatType string

type Role string

type Service interface {
	// CreateCompletion attempts to complete the given request using
	// the given model. Returns a stream of typed events.
	// This method should return ErrContextWindowExceeded if a request
	// exceeds the context window of the selected model.
	CreateCompletion(
		ctx context.Context,
		model ModelEntry,
		request Request,
	) (iterator.Iterator[Event], error)

	// CountTokens returns the approximate token count for the given
	// messages under the given model's tokenizer.
	CountTokens(model ModelEntry, messages []Message) (int, error)

	// Models returns an iterator over all available model entries.
	Models() iterator.Iterator[ModelEntry]

	// GetModel returns the canonical entry for the given model. Callers
	// typically pass a ModelEntry with only Name set; the returned
	// entry carries the full provider metadata. GetModel returns
	// ErrModelNotFound if the model is not known to the service.
	GetModel(ctx context.Context, model ModelEntry) (ModelEntry, error)
}

type Tool struct {
	Type     ToolType
	Function FunctionDefinition
}

type ToolCall struct {
	ID       string
	Type     ToolType
	Function FunctionCall
	// ProviderFields carries opaque provider-specific data attached to this
	// individual tool call that must be threaded back into the next request
	// to maintain stateful continuity (e.g. Gemini 3+ requires the
	// per-call thought_signature to be echoed on the functionCall part).
	// Each value is the raw JSON of a single field. Cross-provider code
	// should treat this map as opaque and leave unknown keys untouched.
	ProviderFields map[string]json.RawMessage `json:"ProviderFields,omitempty"`
}

type ToolChoice string

type ToolType string

type Usage struct {
	TokensSent         int
	TokensReceived     int
	TokensReasoned     int
	TokensCached       int
	TokensCacheCreated int
}