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 interface {
	// Kind identifies the event variant.
	Kind() string
	// contains filtered or unexported methods
}

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 validated streaming model invocation when supported.
	Stream(ctx context.Context, req *Request) (ValidatedStreamer, error)
}

type Completion struct {
	// Name is the stable completion identifier associated with this payload.
	Name string

	// Payload is the canonical JSON value for the streamed completion.
	Payload rawjson.Message
}

type CompletionChunk struct {
	Completion Completion
}

type CompletionDelta struct {
	// Name is the stable completion identifier associated with this delta.
	Name string

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

type CompletionDeltaChunk struct {
	Delta CompletionDelta
}

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 OutputValidationError struct {
	// contains filtered or unexported fields
}

type OutputValidationKind string

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

type Provider 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 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

	// StructuredOutput constrains assistant output to a JSON schema when the
	// provider supports native structured-output enforcement.
	StructuredOutput *StructuredOutput

	// 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
	// contains filtered or unexported fields
}

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

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

	// OutputLimited reports that the provider stopped because generated
	// output reached its configured token or context limit. A validated
	// client never exposes such a response as successful completed work.
	OutputLimited bool
}

type ResponseEvidence struct {
	Present     bool
	ByteCount   int
	Fingerprint [sha256.Size]byte
}

type StopChunk struct {
	Reason        string
	OutputLimited bool
}

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

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

	// Response returns the provider-owned terminal response after Recv has
	// returned a literal io.EOF. It returns nil before then or after failure.
	Response() *Response
}

type StructuredOutput struct {
	// Name identifies the response format for providers that require one.
	Name string

	// Schema is the JSON Schema payload sent to the provider.
	Schema rawjson.Message
}

type TextChunk struct {
	Message Message
}

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

type ThinkingChunk struct {
	Message Message
}

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 TokenCount struct {
	// Model is the provider-resolved model identifier that would receive this
	// request. It is empty when an estimator cannot resolve the concrete model.
	Model string

	// ModelClass is the logical model family requested by the caller.
	ModelClass ModelClass

	// InputTokens is the number of input tokens counted or estimated.
	InputTokens int

	// Exact reports whether InputTokens came from provider-native counting.
	Exact bool
}

type TokenCounter interface {
	CountTokens(ctx context.Context, req *Request) (TokenCount, error)
}

type TokenEstimator struct {
	// CharactersPerToken is the approximate byte-to-token conversion ratio.
	// When zero, the estimator uses three characters per token.
	CharactersPerToken int

	// OverheadTokens adds a fixed allowance for provider framing and request
	// fields that are not represented directly in message text.
	// When zero, the estimator uses 500 tokens.
	OverheadTokens int

	// MinimumTokens is the minimum non-zero estimate returned for tiny
	// requests. When zero, the estimator uses 500 tokens.
	MinimumTokens int
}

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 uncached input tokens consumed. It does
	// not include CacheReadTokens or CacheWriteTokens.
	InputTokens int

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

	// TotalTokens is the total number of tokens consumed by the call. When
	// non-zero, it equals InputTokens + OutputTokens + CacheReadTokens +
	// CacheWriteTokens.
	TotalTokens int

	// CacheReadTokens is the number of input tokens read from cache. This
	// count is disjoint from InputTokens.
	CacheReadTokens int

	// CacheWriteTokens is the number of input tokens written to cache. This
	// count is disjoint from InputTokens.
	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 ToolCallChunk struct {
	ToolCall ToolCall
}

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 ToolCallDeltaChunk struct {
	Delta ToolCallDelta
}

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
}

type UsageChunk struct {
	Usage TokenUsage
}

type ValidatedStreamer interface {
	Streamer

	Finalize(primaryErr error) error
}