model

type Choice struct {
	// Content is the assistant content for this choice.
	Content Content
	// FinishReason indicates why generation stopped.
	FinishReason FinishReason
}

type Content struct {
	// Role is the participant role (system, user, assistant, tool).
	Role Role
	// Content is the plain text content.
	// For multi-modal user content use Parts instead; Parts takes precedence
	// when non-empty.
	Content string
	// Parts holds multi-modal content (text, images, etc.).
	// When non-empty, Parts takes precedence over Content.
	// Currently only supported for RoleUser messages.
	Parts []ContentPart
	// ReasoningContent holds the model's internal chain-of-thought output, when
	// returned by reasoning models (e.g. DeepSeek-R1, o-series via compatible
	// providers). Most adapters treat it as informational only; providers that
	// require it for continuity, such as DeepSeek thinking-mode tool calls, may
	// forward it on subsequent turns.
	ReasoningContent string
	// ToolCalls is populated when Role is RoleAssistant and the model requests tool invocations.
	ToolCalls []ToolCall
	// ToolResponse is populated when Role is RoleTool.
	ToolResponse *ToolResponse
	// ToolCallID links a RoleTool message back to the ToolCall.ID it is
	// responding to. It is kept as a text fallback for simple callers; when
	// ToolResponse is non-nil, ToolResponse.ToolCallID takes precedence.
	ToolCallID string
}

type ContentPart struct {
	// Type identifies the kind of content.
	Type ContentPartType
	// Text holds the plain-text content when Type is ContentPartTypeText.
	Text string
	// ImageURL is the HTTPS URL of the image when Type is ContentPartTypeImageURL.
	ImageURL string
	// ImageBase64 is the raw base64-encoded image data (no data URI prefix)
	// when Type is ContentPartTypeImageBase64.
	ImageBase64 string
	// MIMEType is the MIME type of the base64 image (e.g. "image/jpeg", "image/png").
	// Required when Type is ContentPartTypeImageBase64.
	MIMEType string
	// ImageDetail controls the fidelity at which the image is processed.
	// Defaults to "auto" when empty. Relevant for ContentPartTypeImageURL and
	// ContentPartTypeImageBase64.
	ImageDetail ImageDetail
}

type ContentPartType string

type Event struct {
	// ID is assigned by Runner before the event is persisted. Zero means the
	// event has not been persisted yet.
	ID int64
	// SessionID identifies the session that owns this event when persisted.
	SessionID string
	// TurnID groups all events produced by one Runner.Run call. It is a
	// correlation identifier, not an ordering key; event ordering remains
	// defined by CreatedAt and ID.
	TurnID string
	// Author identifies the producer of the event, for example "user" or an
	// agent name. It is display metadata and is not forwarded to the LLM.
	Author string
	// Content contains the payload for this event.
	// When Partial=true, only Content.Content and Content.ReasoningContent
	// carry incremental (delta) text; all other fields may be zero-valued.
	// When Partial=false, Content is fully assembled.
	Content Content
	// FinishReason indicates why model generation stopped for assistant events.
	FinishReason FinishReason
	// Usage holds token consumption when the event was produced by an LLM call.
	Usage *TokenUsage
	// Partial indicates this is a streaming fragment, not a complete message.
	// Callers (e.g. Runner) should forward partial events to the client for
	// real-time display but only persist complete events (Partial=false).
	Partial bool
	// CreatedAt is set by Runner or the session backend when persisted.
	CreatedAt int64
	// UpdatedAt is set by Runner or the session backend when persisted.
	UpdatedAt int64
}

type FinishReason string

type GenerateConfig struct {
	// Temperature controls sampling randomness. A zero value leaves the decision
	// to the provider.
	Temperature float64
	// MaxTokens overrides the maximum number of tokens to generate.
	// A zero value leaves the decision to the provider (which may use its own default).
	MaxTokens int64
}

type ImageDetail string

type LLM interface {
	Name() string
	// GenerateContent sends the request to the LLM and yields responses.
	// When stream is false, exactly one *LLMResponse is yielded (the complete response).
	// When stream is true, zero or more partial *LLMResponse are yielded (Partial=true)
	// followed by one complete *LLMResponse (Partial=false, TurnComplete=true).
	GenerateContent(ctx context.Context, req *LLMRequest, cfg *GenerateConfig, stream bool) iter.Seq2[*LLMResponse, error]
}

type LLMRequest struct {
	// Model is the identifier of the model to use.
	Model string
	// Contents is the conversation history, projected from session events.
	Contents []Content
	// Tools is the list of tools the model may call during generation.
	Tools []tool.Tool
}

type LLMResponse struct {
	Content      Content
	FinishReason FinishReason
	// Usage holds the token consumption reported by the LLM provider.
	// Only populated on the final complete response (Partial=false).
	Usage *TokenUsage
	// Partial indicates this response is a streaming fragment.
	// When true, only Content.Content and Content.ReasoningContent carry
	// incremental (delta) text; other fields may be zero-valued.
	Partial bool
	// TurnComplete indicates the LLM has finished generating its full response.
	// Set to true on the final complete response (Partial=false).
	TurnComplete bool
}

type Role string

type TokenUsage struct {
	PromptTokens     int64
	CompletionTokens int64
	TotalTokens      int64
	Details          *TokenUsageDetails
}

type TokenUsageDetails struct {
	// CachedPromptTokens is the number of prompt tokens served from cache.
	CachedPromptTokens int64 `json:"cached_prompt_tokens,omitempty"`
	// CacheCreationPromptTokens is the number of prompt tokens used to create a cache entry.
	CacheCreationPromptTokens int64 `json:"cache_creation_prompt_tokens,omitempty"`
	// CacheReadPromptTokens is the number of prompt tokens read from a cache entry.
	CacheReadPromptTokens int64 `json:"cache_read_prompt_tokens,omitempty"`
	// ReasoningTokens is the number of output tokens used for model reasoning.
	ReasoningTokens int64 `json:"reasoning_tokens,omitempty"`
	// ToolUsePromptTokens is the number of prompt tokens from tool execution results.
	ToolUsePromptTokens int64 `json:"tool_use_prompt_tokens,omitempty"`
	// AudioPromptTokens is the number of prompt tokens from audio input.
	AudioPromptTokens int64 `json:"audio_prompt_tokens,omitempty"`
	// AudioCompletionTokens is the number of completion tokens from audio output.
	AudioCompletionTokens int64 `json:"audio_completion_tokens,omitempty"`
	// AcceptedPredictionTokens is the number of predicted output tokens accepted by the model.
	AcceptedPredictionTokens int64 `json:"accepted_prediction_tokens,omitempty"`
	// RejectedPredictionTokens is the number of predicted output tokens rejected by the model.
	RejectedPredictionTokens int64 `json:"rejected_prediction_tokens,omitempty"`
}

type ToolCall struct {
	// ID is a unique identifier for this tool call, used to match results back.
	ID string
	// Name is the name of the tool to invoke.
	Name string
	// Arguments is the raw JSON payload of the tool's input parameters.
	Arguments json.RawMessage
	// ThoughtSignature is an opaque token that some providers (e.g. Gemini thinking
	// models) attach to a function-call part. It must be echoed back verbatim in the
	// subsequent request so the provider can restore its reasoning context.
	// Non-Gemini adapters leave this field nil and ignore it on input.
	ThoughtSignature []byte
}

type ToolResponse struct {
	// ToolCallID links this response to the ToolCall.ID it answers.
	ToolCallID string
	// Name is the tool name associated with the response.
	Name string
	// Outcome is either a successful *tool.Result or a model-visible
	// *tool.HandledError.
	Outcome tool.Outcome
}