chat

type CallMiddleware func(next Model) Model

type Citation struct {
	Source CitationSource `json:"source"`
	Title  string         `json:"title,omitempty"`
	Quote  string         `json:"quote,omitempty"`
}

type CitationSource struct {
	Kind  CitationSourceKind `json:"kind"`
	Value string             `json:"value"`
}

type CitationSourceKind string

type FinishReason string

type JSONSchemaConfig struct {
	Name        string
	Description string
	Schema      json.RawMessage
}

type Message struct {
	Role     Role         `json:"role"`
	Parts    []Part       `json:"parts"`
	Metadata metadata.Map `json:"metadata,omitzero"`
}

type Model interface {
	// Call performs one complete model exchange. It must reject an invalid
	// request before provider I/O, must not retain or mutate request, and
	// transfers ownership of the returned response to the caller. Context
	// cancellation remains identifiable through errors.Is.
	Call(ctx context.Context, request *Request) (*Response, error)
}

type ModelFunc func(ctx context.Context, request *Request) (*Response, error)

type Options struct {
	Model            string              `json:"model,omitempty"`
	OutputFormat     *OutputFormat       `json:"output_format,omitzero"`
	FrequencyPenalty *float64            `json:"frequency_penalty,omitzero"`
	MaxOutputTokens  *int64              `json:"max_output_tokens,omitzero"`
	PresencePenalty  *float64            `json:"presence_penalty,omitzero"`
	ReasoningEffort  ReasoningEffort     `json:"reasoning_effort,omitempty"`
	Stop             []string            `json:"stop,omitzero"`
	Temperature      *float64            `json:"temperature,omitzero"`
	TopK             *int64              `json:"top_k,omitzero"`
	TopP             *float64            `json:"top_p,omitzero"`
	Extensions       metadata.Extensions `json:"extensions,omitzero"`
}

type Output struct {
	Message      *Message        `json:"message,omitzero"`
	FinishReason FinishReason    `json:"finish_reason,omitempty"`
	Metadata     *OutputMetadata `json:"metadata,omitzero"`
}

type OutputFormat struct {
	Type        OutputFormatType `json:"type"`
	Name        string           `json:"name,omitempty"`
	Description string           `json:"description,omitempty"`
	Schema      json.RawMessage  `json:"schema,omitzero"`
}

type OutputFormatType string

type OutputMetadata struct {
	Extra metadata.Map `json:"extra,omitzero"`
}

type Part struct {
	Kind           PartKind     `json:"kind"`
	Text           string       `json:"text,omitempty"`
	Media          *media.Media `json:"media,omitzero"`
	ReasoningState []byte       `json:"reasoning_state,omitempty"`
	ToolCall       *ToolCall    `json:"tool_call,omitzero"`
	ToolResult     *ToolResult  `json:"tool_result,omitzero"`
	Citations      []Citation   `json:"citations,omitempty"`
	Metadata       metadata.Map `json:"metadata,omitzero"`
}

type PartDelta struct {
	Kind           PartDeltaKind  `json:"kind"`
	Text           string         `json:"text,omitempty"`
	Media          *media.Media   `json:"media,omitzero"`
	ReasoningState []byte         `json:"reasoning_state,omitempty"`
	ToolCall       *ToolCallDelta `json:"tool_call,omitzero"`
	Citation       *Citation      `json:"citation,omitzero"`
	Metadata       metadata.Map   `json:"metadata,omitzero"`
}

type PartDeltaKind string

type PartKind string

type ReasoningEffort string

type Request struct {
	Messages   []Message        `json:"messages"`
	Tools      []ToolDefinition `json:"tools,omitempty"`
	ToolChoice *ToolChoice      `json:"tool_choice,omitzero"`
	Options    Options          `json:"options,omitzero"`
}

type Response struct {
	Output   *Output           `json:"output,omitzero"`
	Metadata *ResponseMetadata `json:"metadata,omitzero"`
}

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

type ResponseDelta struct {
	Parts           []PartDelta       `json:"parts,omitempty"`
	MessageMetadata metadata.Map      `json:"message_metadata,omitzero"`
	FinishReason    FinishReason      `json:"finish_reason,omitempty"`
	OutputMetadata  *OutputMetadata   `json:"output_metadata,omitzero"`
	Metadata        *ResponseMetadata `json:"metadata,omitzero"`
}

type ResponseMetadata struct {
	ID    string `json:"id,omitempty"`
	Model string `json:"model,omitempty"`
	// Usage is nil when token accounting was not reported. A non-nil zero
	// value records an explicitly reported zero total.
	Usage     *Usage       `json:"usage,omitzero"`
	CreatedAt time.Time    `json:"created_at,omitzero"`
	Extra     metadata.Map `json:"extra,omitzero"`
}

type Role string

type StreamMiddleware func(next Streamer) Streamer

type Streamer interface {
	// Stream starts provider work lazily when the sequence is iterated. Each
	// yielded delta is independently owned, carries a cumulative usage snapshot,
	// and is accepted by ResponseAccumulator. A failure yields (nil, err) at most
	// once, preserving context error identity. Stopping iteration releases
	// provider resources before the iterator returns, without a cancellation
	// yield or detached goroutine.
	Stream(ctx context.Context, request *Request) iter.Seq2[*ResponseDelta, error]
}

type StreamerFunc func(ctx context.Context, request *Request) iter.Seq2[*ResponseDelta, error]

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

type ToolCallDelta struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	Arguments string `json:"arguments,omitempty"`
}

type ToolChoice struct {
	Mode        ToolChoiceMode  `json:"mode"`
	Name        string          `json:"name,omitempty"`
	Parallelism ToolParallelism `json:"parallelism,omitempty"`
}

type ToolChoiceMode string

type ToolContent struct {
	Kind      PartKind     `json:"kind"`
	Text      string       `json:"text,omitempty"`
	Media     *media.Media `json:"media,omitzero"`
	Citations []Citation   `json:"citations,omitempty"`
	Metadata  metadata.Map `json:"metadata,omitzero"`
}

type ToolDefinition struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	InputSchema json.RawMessage `json:"input_schema"`
}

type ToolOutput struct {
	Content []ToolContent   `json:"content,omitempty"`
	Details json.RawMessage `json:"details,omitzero"`
}

type ToolParallelism string

type ToolResult struct {
	ID      string     `json:"id"`
	Name    string     `json:"name"`
	Output  ToolOutput `json:"output"`
	IsError bool       `json:"is_error,omitzero"`
}

type Usage struct {
	// InputTokens is the total processed input count. Provider cache-read and
	// cache-write counts, when reported, are breakdowns included in this total.
	InputTokens           int64  `json:"input_tokens,omitzero"`
	OutputTokens          int64  `json:"output_tokens,omitzero"`
	ReasoningTokens       *int64 `json:"reasoning_tokens,omitzero"`
	CacheReadInputTokens  *int64 `json:"cache_read_input_tokens,omitzero"`
	CacheWriteInputTokens *int64 `json:"cache_write_input_tokens,omitzero"`
}