model

type CacheCheckpointPart struct{}

type CacheOptions struct {
	// AfterSystem places a checkpoint after all system messages.
	AfterSystem bool

	// AfterTools places a checkpoint after tool definitions. Not all
	// providers support tool-level checkpoints (e.g., Nova does not).
	AfterTools bool
}

type Chunk struct {
	// Type identifies the kind of streaming event.
	Type string

	// Message carries incremental assistant content for text or thinking
	// chunks when present.
	Message *Message

	// Thinking carries incremental reasoning text for providers that surface
	// it out-of-band from Message.
	Thinking string

	// ToolCall carries a single tool invocation when Type is ChunkTypeToolCall.
	ToolCall *ToolCall

	// ToolCallDelta carries an incremental tool-call payload fragment when Type
	// is ChunkTypeToolCallDelta. It is strictly optional and may be ignored.
	ToolCallDelta *ToolCallDelta

	// UsageDelta reports incremental token usage when available.
	UsageDelta *TokenUsage

	// StopReason records why streaming stopped when Type is ChunkTypeStop.
	StopReason string
}

type Citation struct {
	// Title is the source document title/identifier when available.
	Title string

	// Source is a provider-specific source identifier when available.
	Source string

	// Location identifies where in the source document the cited content can be found.
	Location CitationLocation

	// SourceContent is the cited excerpt from the source document when provided.
	SourceContent []string
}

type CitationLocation struct {
	// DocumentChar identifies a character span within a source document.
	DocumentChar *DocumentCharLocation

	// DocumentChunk identifies a range of chunks within a source document.
	DocumentChunk *DocumentChunkLocation

	// DocumentPage identifies a page within a source document.
	DocumentPage *DocumentPageLocation
}

type CitationsPart struct {
	// Text is the generated content supported by Citations.
	Text string

	// Citations reference the source documents that informed Text.
	Citations []Citation
}

type Client interface {
	// Complete performs a non-streaming model invocation.
	Complete(ctx context.Context, req *Request) (*Response, error)

	// Stream performs a streaming model invocation when supported.
	Stream(ctx context.Context, req *Request) (Streamer, error)
}

type ConversationRole string

type DocumentCharLocation struct {
	DocumentIndex int
	Start         int
	End           int
}

type DocumentChunkLocation struct {
	DocumentIndex int
	Start         int
	End           int
}

type DocumentFormat string

type DocumentPageLocation struct {
	DocumentIndex int
	Start         int
	End           int
}

type DocumentPart struct {
	// Name is a short neutral identifier for the document (for example, "spec").
	Name string

	// Format identifies the document format/extension (for example, "pdf", "txt", "md").
	Format DocumentFormat

	// Bytes carries the raw document bytes when the document is provided as an upload.
	Bytes []byte

	// Text carries the document content when the document is provided as a single text blob.
	Text string

	// Chunks carries the document content split into logical chunks when citations
	// should reference chunk indices rather than character spans.
	Chunks []string

	// URI locates the document externally when the document should not be
	// embedded in the request payload (for example, "s3://bucket/key.pdf").
	//
	// Provider adapters fail fast when URI schemes are not supported.
	URI string

	// Context is optional contextual information about how the document should be
	// interpreted by the model when generating citations.
	Context string

	// Cite requests provider-native citations when supported.
	Cite bool
}

type ImageFormat string

type ImagePart struct {
	// Format identifies the encoding of Bytes (e.g., "png").
	Format ImageFormat

	// Bytes contains the raw image bytes for the declared format.
	Bytes []byte
}

type Message struct {
	// Role identifies the speaker for this message.
	Role ConversationRole

	// Parts are the ordered content blocks for the message.
	Parts []Part

	// Meta carries optional provider- or application-specific metadata
	// attached to the message.
	Meta map[string]any
}

type ModelClass string

type Part interface {
	// contains filtered or unexported methods
}

type ProviderError struct {
	// contains filtered or unexported fields
}

type ProviderErrorKind string

type Request struct {
	// RunID identifies the logical run for this request when available.
	RunID string

	// Model is the provider-specific model identifier when specified.
	Model string

	// ModelClass selects a model family when Model is not specified.
	ModelClass ModelClass

	// PromptRefs records the exact prompts and versions used to build this
	// request. Runtime components and observers use this for provenance and
	// auditing; provider adapters must treat it as metadata and must not
	// translate it to provider wire payloads.
	PromptRefs []prompt.PromptRef

	// Messages is the ordered transcript provided to the model.
	Messages []*Message

	// Temperature controls sampling when supported by the provider.
	Temperature float32

	// Tools lists the tool definitions available to the model.
	Tools []*ToolDefinition

	// ToolChoice optionally constrains how the model uses tools.
	ToolChoice *ToolChoice

	// MaxTokens caps the number of output tokens when supported.
	MaxTokens int

	// Stream requests streaming responses when true and supported.
	Stream bool

	// Thinking configures provider-specific reasoning behavior.
	Thinking *ThinkingOptions

	// Cache configures prompt caching behavior. Nil means no caching.
	Cache *CacheOptions
}

type Response struct {
	// Content is the ordered list of assistant messages produced.
	Content []Message

	// ToolCalls lists tool invocations requested by the model.
	ToolCalls []ToolCall

	// Usage reports token consumption for the request.
	Usage TokenUsage

	// StopReason records why generation stopped (provider-specific).
	StopReason string
}

type Streamer interface {
	// Recv returns the next streaming chunk or an error.
	Recv() (Chunk, error)

	// Close releases any resources associated with the stream.
	Close() error

	// Metadata carries provider-specific metadata collected during the call.
	Metadata() map[string]any
}

type TextPart struct {
	// Text is the human-readable content for this part.
	Text string
}

type ThinkingOptions struct {
	// Enable turns provider thinking features on when supported.
	Enable bool

	// Interleaved requests interleaved thinking and assistant content when
	// supported.
	Interleaved bool

	// BudgetTokens caps the number of thinking tokens when supported.
	BudgetTokens int
}

type ThinkingPart struct {
	// Text is the provider-visible reasoning text when available.
	Text string

	// Signature is the provider-issued signature for Text when present.
	Signature string

	// Redacted carries provider-issued reasoning content in redacted form
	// when plaintext Text is not available.
	Redacted []byte

	// Index is the position of this block in the reasoning sequence.
	Index int

	// Final reports whether this reasoning block is the last one for the
	// current turn.
	Final bool
}

type TokenUsage struct {
	// Model is the provider-resolved model identifier that produced this
	// usage (e.g., "us.anthropic.claude-sonnet-4-20250514-v1:0"). Set by
	// the model adapter; empty when the adapter does not report it.
	Model string

	// ModelClass is the logical model family that was requested (e.g.,
	// "default", "high-reasoning", "small"). Set by the model adapter
	// from the original request.
	ModelClass ModelClass

	// InputTokens is the number of tokens consumed by inputs.
	InputTokens int

	// OutputTokens is the number of tokens produced by outputs.
	OutputTokens int

	// TotalTokens is the total number of tokens consumed by the call.
	TotalTokens int

	// CacheReadTokens is tokens read from cache (reduced cost).
	CacheReadTokens int

	// CacheWriteTokens is tokens written to cache.
	CacheWriteTokens int
}

type ToolCall struct {
	// Name is the tool identifier requested by the model.
	Name tools.Ident

	// Payload is the canonical JSON arguments supplied by the model.
	//
	// Provider adapters MUST populate this as a valid JSON value. Planners and
	// runtimes treat it as opaque JSON and rely on codecs for any schema-aware
	// decoding. The RawJSON type exists to make workflow-boundary encoding safe
	// (it normalizes empty payloads to JSON null).
	Payload rawjson.Message

	// ID is an optional provider-issued identifier for the tool call.
	ID string
}

type ToolCallDelta struct {
	// Name is the canonical tool identifier for this delta stream.
	//
	// Provider adapters MUST populate Name for every emitted delta so
	// downstream consumers can render tool-specific previews deterministically.
	Name tools.Ident

	// ID is the provider-issued tool call identifier used to correlate all
	// deltas and the final ToolCall payload.
	ID string

	// Delta is a raw JSON fragment emitted by the provider.
	Delta string
}

type ToolChoice struct {
	// Mode selects the desired tool behavior for the request.
	Mode ToolChoiceMode

	// Name identifies the tool to request when Mode is ToolChoiceModeTool.
	// It must match the Name of one of the tool definitions in Request.Tools.
	Name string
}

type ToolChoiceMode string

type ToolDefinition struct {
	// Name is the tool identifier as seen by the model.
	Name string

	// Description is a concise summary presented to the model to decide
	// when to call the tool.
	Description string

	// InputSchema is a JSON Schema describing the tool input payload.
	InputSchema any
}

type ToolResultPart struct {
	// ToolUseID correlates this result to a prior tool use declaration.
	ToolUseID string

	// Content is the provider-facing tool result payload.
	//
	// Contract:
	//   - Successful results carry a decoded JSON-compatible value.
	//   - Failed results carry plain error text with IsError=true.
	//   - Runtime/tooling code must not store raw JSON bytes or Go error
	//     structs here.
	Content any

	// IsError reports whether Content represents an error from the tool.
	IsError bool
}

type ToolUsePart struct {
	// ID uniquely identifies this tool call within the run.
	ID string

	// Name is the tool identifier requested by the model.
	Name string

	// Input is the JSON-compatible arguments object provided by the model.
	Input any
}