chat

package
v0.21.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 12, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package chat defines the serializable provider-neutral chat protocol and its minimal synchronous Model and optional Streamer capabilities.

Construct messages and requests with NewSystemMessage, NewUserMessage, and NewRequest. Leaf constructors establish protocol shape; aggregate roots and model boundaries validate the complete value. Call Validate again after mutating exported fields. System messages form a leading prefix so providers with a distinct system channel can translate a request without reordering it. Options express only per-call overrides; ToolChoice describes portable tool selection, ReasoningEffort carries model-advertised intensity without imposing one provider's closed enum, and OutputFormat describes the requested representation without adopting provider wire naming. Namespaced Extensions preserve provider data without expanding the shared protocol for every provider feature.

Response is a complete, stable output. Streamer yields ResponseDelta transport increments instead of partial Responses; ResponseAccumulator is the single promotion path between them and requires a terminal finish reason. Citations, refusals, reasoning replay state, and tool calls remain typed protocol values while exact provider-only data stays in namespaced metadata.

ToolDefinition describes wire schema only. Executable tools, registries, history, retries, middleware policy, and tool loops belong to higher-level modules. Protocol values therefore never retain callbacks, provider clients, or other runtime objects.

Example 
package main

import (
	"fmt"

	"github.com/Tangerg/scope/core/chat"
)

func main() {
	request, err := chat.NewRequest(
		chat.NewSystemMessage("Answer concisely."),
		chat.NewUserMessage(chat.NewTextPart("What is a scope?")),
	)
	if err != nil {
		panic(err)
	}
	request.Options = chat.Options{Model: "provider-model"}

	fmt.Println(request.Messages[1].Text())
	fmt.Println(request.Options.Model)
}

Output:
What is a scope?
provider-model

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalidMessage identifies a message whose role, parts, or metadata
	// violate the portable conversation contract.
	ErrInvalidMessage = errors.New("chat: invalid message")
	// ErrInvalidPart identifies a part whose kind and active payload disagree.
	ErrInvalidPart = errors.New("chat: invalid part")
	// ErrInvalidToolCall identifies an incomplete tool invocation request.
	ErrInvalidToolCall = errors.New("chat: invalid tool call")
	// ErrInvalidToolOutput identifies a malformed tool execution payload.
	ErrInvalidToolOutput = errors.New("chat: invalid tool output")
	// ErrInvalidToolResult identifies a result that cannot answer a tool call.
	ErrInvalidToolResult = errors.New("chat: invalid tool result")
)
View Source 
var (
	// ErrInvalidOutputFormat identifies an internally inconsistent format
	// contract.
	ErrInvalidOutputFormat = errors.New("chat: invalid output format")
	// ErrUnsupportedOutputFormat lets a provider reject a valid portable format
	// that its native endpoint cannot enforce.
	ErrUnsupportedOutputFormat = errors.New("chat: unsupported output format")
)
View Source 
var ErrInvalidCitation = errors.New("chat: invalid citation")

ErrInvalidCitation identifies a citation that cannot be represented by the portable evidence contract.

View Source 
var ErrInvalidOptions = errors.New("chat: invalid options")

ErrInvalidOptions identifies generation overrides that cannot be mapped to the portable request contract.

View Source 
var ErrInvalidRequest = errors.New("chat: invalid request")

ErrInvalidRequest identifies an invalid complete model input.

View Source 
var ErrInvalidResponse = errors.New("chat: invalid response")

ErrInvalidResponse identifies provider output that cannot satisfy the portable response contract.

View Source 
var ErrInvalidToolChoice = errors.New("chat: invalid tool choice")

ErrInvalidToolChoice identifies contradictory selection or parallelism controls.

View Source 
var ErrInvalidToolDefinition = errors.New("chat: invalid tool definition")

ErrInvalidToolDefinition identifies a model-facing tool schema that cannot be transported safely.

View Source 
var ErrInvalidUsage = errors.New("chat: invalid usage")

ErrInvalidUsage identifies impossible token totals or breakdowns.

Functions

This section is empty.

Types

type CallMiddleware 

type CallMiddleware func(next Model) Model

CallMiddleware wraps a Model with cross-cutting call behavior. Concrete logging, tracing, retry, history, and safety policy belong to upper modules; core/chat only owns this composition vocabulary.

type Citation added in v0.13.0 

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

Citation is the portable identity and quoted evidence attached to a text part. Exact provider coordinates remain available through response metadata.

func (Citation) Validate added in v0.13.0 

func (c Citation) Validate() error

type CitationSource added in v0.13.0 

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

CitationSource identifies cited material without adopting a provider's location taxonomy. Provider-native page, block, and character coordinates remain in the preserved native response.

func (CitationSource) Validate added in v0.13.0 

func (c CitationSource) Validate() error

type CitationSourceKind added in v0.13.0 

type CitationSourceKind string

CitationSourceKind distinguishes a resolvable URI from an opaque source reference whose interpretation remains with the provider or host. 

const (
	CitationSourceURI       CitationSourceKind = "uri"
	CitationSourceReference CitationSourceKind = "reference"
)

Portable citation source kinds deliberately stop short of provider-specific page, block, or character coordinates.

func (CitationSourceKind) Valid added in v0.13.0 

func (c CitationSourceKind) Valid() bool

type FinishReason 

type FinishReason string

FinishReason explains why generation stopped. Complete outputs require a non-empty value; ResponseDelta uses the empty value before termination. 

const (
	// FinishReasonStop means the model reached a natural stop condition,
	// including one of the caller's stop sequences. The output is complete.
	FinishReasonStop FinishReason = "stop"
	// FinishReasonLength means the output is incomplete and continuing is the
	// caller's remedy. It groups by the state the caller is left in rather than
	// by the cause: the caller's own token budget, a provider limit such as a
	// context window that filled first, or a provider pausing a long-running
	// turn and inviting the caller to send the response back to resume all
	// leave the same half-finished output, so all of them map here. An adapter
	// that files one of them under [FinishReasonOther] instead hides it from
	// every caller that decides whether to continue by reading this field; the
	// provider's own reason belongs in [OutputMetadata.Extra] alongside, not
	// in place of, this one.
	FinishReasonLength FinishReason = "length"
	// FinishReasonToolCalls means the model stopped to request tool execution.
	FinishReasonToolCalls FinishReason = "tool_calls"
	// FinishReasonContentFilter means provider policy withheld or cut short the
	// content — safety, blocklists, prohibited content, recitation, and the
	// like. It covers policy acting on what was generated, whereas
	// [FinishReasonRefusal] is the model itself declining the request.
	FinishReasonContentFilter FinishReason = "content_filter"
	// FinishReasonRefusal means the model declined the request.
	FinishReasonRefusal FinishReason = "refusal"
	// FinishReasonOther preserves a known terminal state with no portable
	// match, such as a malformed tool call or a provider-side iteration limit.
	// It is not a default for reasons an adapter has not classified: mapping a
	// truncation or a policy stop here hides it from every caller that checks
	// the two reasons above.
	FinishReasonOther FinishReason = "other"
)

A provider's native reason maps to exactly one of these. Callers act on the distinction — retrying, continuing, or surfacing a policy outcome — so an adapter classifies by what happened to the output, not by how the provider spelled it. The native value belongs in OutputMetadata.Extra either way.

func (FinishReason) String 

func (f FinishReason) String() string

func (FinishReason) Valid 

func (f FinishReason) Valid() bool

type JSONSchemaConfig added in v0.13.0 

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

JSONSchemaConfig names a provider-enforced structured-output contract.

type Message 

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

Message is one provider-neutral conversation entry. Parts retain their order so interleaved assistant text, reasoning, and tool calls round-trip. Clone recursively owns every mutable protocol value. Text projection concatenates only text parts and deliberately ignores reasoning, media, and tool payloads.

func NewAssistantMessage 

func NewAssistantMessage(parts ...Part) Message

NewAssistantMessage copies the parts container and borrows nested values.

func NewSystemMessage 

func NewSystemMessage(text string) Message

NewSystemMessage creates an instruction message suitable for the leading system prefix required by Request.

func NewToolMessage 

func NewToolMessage(results ...ToolResult) Message

NewToolMessage preserves one result part per call so a provider can correlate a returned batch without inspecting untyped content. Nested output is borrowed.

func NewUserMessage 

func NewUserMessage(parts ...Part) Message

NewUserMessage copies the parts container and borrows nested values.

func (Message) Clone 

func (m Message) Clone() Message

func (Message) MarshalJSON 

func (m Message) MarshalJSON() ([]byte, error)

func (*Message) Text 

func (m *Message) Text() string

func (*Message) UnmarshalJSON 

func (m *Message) UnmarshalJSON(data []byte) error

func (Message) Validate 

func (m Message) Validate() error

type Model 

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)
}

Model is the minimal synchronous chat capability. Implementations must validate request before provider I/O, honor context cancellation, and return a provider-neutral Response. Cancellation errors must retain context.Canceled or context.DeadlineExceeded for errors.Is.

Streaming, default configuration, and provider identity are independent concerns and deliberately are not methods of Model.

func Wrap 

func Wrap(model Model, middlewares ...CallMiddleware) Model

Wrap composes call middlewares around model. The first middleware is the outermost wrapper. Nil entries are ignored so optional middleware can be supplied without a separate branch.

type ModelFunc 

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

ModelFunc adapts a function to Model without introducing a second call API.

func (ModelFunc) Call 

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

type Options 

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

Options contains provider-neutral per-request generation overrides. Its zero value means provider defaults. Resolve overlays only explicitly populated fields, merges namespaced extensions, snapshots mutable values, and leaves both source values unchanged.

A populated field an adapter cannot express must be reported, never dropped. A caller has no other way to learn the difference: a request that silently loses its temperature or its reasoning effort still returns a plausible answer, generated under settings nobody asked for. Refusing costs the caller one error at the boundary and tells them exactly which of their intentions the provider cannot carry, which is why an unsupported option is a provider capability gap rather than a value to approximate.

func (Options) Clone 

func (o Options) Clone() Options

func (Options) MarshalJSON 

func (o Options) MarshalJSON() ([]byte, error)

func (Options) Resolve 

func (o Options) Resolve(override Options) (Options, error)

Resolve overlays only explicitly populated override values and returns an independently owned, validated result. Neither input is mutated.

func (*Options) UnmarshalJSON 

func (o *Options) UnmarshalJSON(data []byte) error

func (Options) Validate 

func (o Options) Validate() error

type Output 

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

Output is the complete single provider generation produced by a chat call. Message may be nil when the provider completed without a portable content item, but FinishReason is always present.

func NewOutput 

func NewOutput(message *Message, finishReason FinishReason, outputMetadata *OutputMetadata) (*Output, error)

NewOutput validates the single stable generation promoted from a provider response or accumulated stream.

func (Output) MarshalJSON 

func (o Output) MarshalJSON() ([]byte, error)

func (*Output) Text 

func (o *Output) Text() string

func (*Output) UnmarshalJSON 

func (o *Output) UnmarshalJSON(data []byte) error

func (*Output) Validate 

func (o *Output) Validate() error

type OutputFormat 

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

OutputFormat is the provider-neutral representation contract for one model result. Name, Description, and Schema belong only to OutputFormatJSONSchema. Provider adapters decode Schema into their native SDK shape when supported. Schema bytes are always snapshotted at construction and cloning boundaries.

func NewJSONSchemaOutputFormat 

func NewJSONSchemaOutputFormat(config JSONSchemaConfig) (OutputFormat, error)

NewJSONSchemaOutputFormat snapshots and validates an object JSON Schema so adapters receive one immutable portable contract.

func NewOutputFormat 

func NewOutputFormat(formatType OutputFormatType) (OutputFormat, error)

NewOutputFormat constructs the schema-free text or JSON contract. JSON Schema uses NewJSONSchemaOutputFormat because its identity is required.

func (*OutputFormat) Clone 

func (o *OutputFormat) Clone() *OutputFormat

func (OutputFormat) MarshalJSON 

func (o OutputFormat) MarshalJSON() ([]byte, error)

func (*OutputFormat) SchemaAs 

func (o *OutputFormat) SchemaAs[T any]() (T, error)

SchemaAs decodes the preserved JSON Schema into an adapter's native schema shape without introducing a second source of truth.

func (*OutputFormat) UnmarshalJSON 

func (o *OutputFormat) UnmarshalJSON(data []byte) error

func (OutputFormat) Validate 

func (o OutputFormat) Validate() error

type OutputFormatType 

type OutputFormatType string

OutputFormatType identifies the representation requested for a chat result. Provider adapters map the format to an equivalent native control or reject it. 

const (
	// OutputFormatText requests ordinary text.
	OutputFormatText OutputFormatType = "text"
	// OutputFormatJSON requests provider-enforced JSON without a schema.
	OutputFormatJSON OutputFormatType = "json"
	// OutputFormatJSONSchema requests provider-enforced conformance to Schema.
	OutputFormatJSONSchema OutputFormatType = "json_schema"
)

type OutputMetadata 

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

OutputMetadata holds provider-specific metadata for one generation output.

func (OutputMetadata) MarshalJSON 

func (o OutputMetadata) MarshalJSON() ([]byte, error)

func (*OutputMetadata) UnmarshalJSON 

func (o *OutputMetadata) UnmarshalJSON(data []byte) error

type Part 

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

Part is a tagged protocol value. Kind selects exactly one payload shape: Text, Media, reasoning Text/ReasoningState, ToolCall, or ToolResult. Citations annotate only text parts. Metadata retains JSON-safe, part-scoped provider state without weakening the common semantic payload.

func NewMediaPart 

func NewMediaPart(value *media.Media) Part

NewMediaPart borrows value. Use Clone when independent ownership is needed.

func NewReasoningPart 

func NewReasoningPart(text string, state []byte) Part

NewReasoningPart copies opaque replay state alongside visible reasoning.

func NewRefusalPart added in v0.13.0 

func NewRefusalPart(text string) Part

NewRefusalPart keeps a model refusal distinguishable from ordinary output.

func NewTextPart 

func NewTextPart(text string) Part

NewTextPart establishes the text payload shape; aggregate validation rejects empty text.

func NewToolCallPart 

func NewToolCallPart(call ToolCall) Part

NewToolCallPart preserves a model-requested invocation as typed assistant output.

func NewToolResultPart 

func NewToolResultPart(result ToolResult) Part

NewToolResultPart copies result and borrows its nested content.

func (Part) Clone 

func (p Part) Clone() Part

func (Part) MarshalJSON 

func (p Part) MarshalJSON() ([]byte, error)

func (*Part) UnmarshalJSON 

func (p *Part) UnmarshalJSON(data []byte) error

func (Part) Validate 

func (p Part) Validate() error

type PartDelta added in v0.13.0 

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

PartDelta is one transport increment. It is intentionally distinct from Part because incomplete tool arguments and citation attachment are not valid stable message content.

func NewCitationDelta added in v0.13.0 

func NewCitationDelta(citation Citation) PartDelta

NewCitationDelta attaches one complete evidence item to streamed text.

func NewMediaDelta added in v0.13.0 

func NewMediaDelta(value *media.Media) PartDelta

NewMediaDelta carries one complete media value delivered by the stream.

func NewReasoningDelta added in v0.13.0 

func NewReasoningDelta(text string, state []byte) PartDelta

NewReasoningDelta snapshots visible reasoning or opaque replay state.

func NewRefusalDelta added in v0.13.0 

func NewRefusalDelta(text string) PartDelta

NewRefusalDelta keeps refusal text distinct from ordinary text while it is streamed.

func NewTextDelta added in v0.13.0 

func NewTextDelta(text string) PartDelta

NewTextDelta carries one non-empty text increment.

func NewToolCallDelta added in v0.13.0 

func NewToolCallDelta(delta ToolCallDelta) PartDelta

NewToolCallDelta carries the next identity, name, or argument fragment for a tool call under construction.

func (PartDelta) Clone added in v0.13.0 

func (p PartDelta) Clone() PartDelta

func (PartDelta) MarshalJSON added in v0.13.0 

func (p PartDelta) MarshalJSON() ([]byte, error)

func (*PartDelta) UnmarshalJSON added in v0.13.0 

func (p *PartDelta) UnmarshalJSON(data []byte) error

func (PartDelta) Validate added in v0.13.0 

func (p PartDelta) Validate() error

type PartDeltaKind added in v0.13.0 

type PartDeltaKind string

PartDeltaKind identifies transport increments whose lifecycle differs from a complete Part, including incomplete tool arguments and citation attachment. 

const (
	PartDeltaText      PartDeltaKind = "text"
	PartDeltaMedia     PartDeltaKind = "media"
	PartDeltaReasoning PartDeltaKind = "reasoning"
	PartDeltaToolCall  PartDeltaKind = "tool_call"
	PartDeltaCitation  PartDeltaKind = "citation"
	PartDeltaRefusal   PartDeltaKind = "refusal"
)

Delta kinds name the only payload shape active in each stream increment.

func (PartDeltaKind) Valid added in v0.13.0 

func (p PartDeltaKind) Valid() bool

type PartKind 

type PartKind string

PartKind identifies which payload in Part is active. 

const (
	// PartText carries plain text.
	PartText PartKind = "text"
	// PartMedia carries an image, audio, document, or other media value.
	PartMedia PartKind = "media"
	// PartReasoning carries visible reasoning and optional opaque replay state.
	PartReasoning PartKind = "reasoning"
	// PartToolCall carries one tool invocation request.
	PartToolCall PartKind = "tool_call"
	// PartToolResult carries one tool execution result.
	PartToolResult PartKind = "tool_result"
	// PartRefusal carries a model refusal separately from ordinary output text.
	PartRefusal PartKind = "refusal"
)

func (PartKind) Valid 

func (p PartKind) Valid() bool

type ReasoningEffort 

type ReasoningEffort string

ReasoningEffort is a provider-neutral reasoning intensity selected from a model's advertised values. It is intentionally open rather than a fixed enum: the selected model owns its accepted vocabulary.

Being open makes it the easiest option to drop by accident, because there is no enum to switch over and no compiler complaint for leaving it out. An adapter whose provider expresses reasoning as something other than a level — a token budget, say — cannot translate a level into it without inventing the number, so it reports the option as unsupported and lets the caller state the provider's own parameters through an extension. What it must not do is accept the effort and send a request that never carried it.

func (ReasoningEffort) Validate 

func (r ReasoningEffort) Validate() error

Validate rejects values whose identity would change under trimming. Empty is valid and asks the provider adapter to use the selected model's default.

type Request 

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

Request is the complete provider-neutral input to a chat model. It contains only serializable protocol values; executable tools and invocation state are supplied separately by higher-level runtimes. Construction and cloning snapshot every mutable nested protocol value before middleware or providers receive it.

func NewRequest 

func NewRequest(messages ...Message) (*Request, error)

NewRequest validates message structure and the leading system prefix, then snapshots all nested values. Cross-message call/result pairing is outside this structural contract; providers own their conversation sequencing rules.

func (*Request) Clone 

func (r *Request) Clone() *Request

func (Request) MarshalJSON 

func (r Request) MarshalJSON() ([]byte, error)

func (*Request) UnmarshalJSON 

func (r *Request) UnmarshalJSON(data []byte) error

func (*Request) Validate 

func (r *Request) Validate() error

type Response 

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

Response is one complete provider output with exactly one generation output.

func NewResponse 

func NewResponse(output *Output, responseMetadata *ResponseMetadata) (*Response, error)

NewResponse validates one complete output and its response-scoped metadata.

func (*Response) Clone 

func (r *Response) Clone() *Response

func (Response) MarshalJSON 

func (r Response) MarshalJSON() ([]byte, error)

func (*Response) Text 

func (r *Response) Text() string

func (*Response) UnmarshalJSON 

func (r *Response) UnmarshalJSON(data []byte) error

func (*Response) Validate 

func (r *Response) Validate() error

type ResponseAccumulator 

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

ResponseAccumulator is the only promotion path from transport deltas to a complete Response. Its zero value is ready to use. It must not be copied after first use and is not safe for concurrent use.

func (*ResponseAccumulator) Add 

func (r *ResponseAccumulator) Add(delta *ResponseDelta) error

Add validates and applies one delta atomically; a failed merge leaves the accumulated stream unchanged. Atomicity does not imply concurrency safety.

func (*ResponseAccumulator) Response 

func (r *ResponseAccumulator) Response() (*Response, error)

Response promotes the accumulated stream only after a terminal finish reason has been observed and returns an independently owned snapshot.

func (*ResponseAccumulator) Text added in v0.13.0 

func (r *ResponseAccumulator) Text() string

Text returns the currently accumulated visible text without manufacturing a partial Response.

type ResponseDelta added in v0.13.0 

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,omitempty"`
	Metadata        *ResponseMetadata `json:"metadata,omitempty"`
}

ResponseDelta is one independently owned stream increment. Usage is a cumulative snapshot; an optional finish reason marks the terminal increment.

func (*ResponseDelta) Clone added in v0.13.0 

func (r *ResponseDelta) Clone() *ResponseDelta

func (ResponseDelta) MarshalJSON added in v0.13.0 

func (r ResponseDelta) MarshalJSON() ([]byte, error)

func (*ResponseDelta) Text added in v0.13.0 

func (r *ResponseDelta) Text() string

func (*ResponseDelta) UnmarshalJSON added in v0.13.0 

func (r *ResponseDelta) UnmarshalJSON(data []byte) error

func (*ResponseDelta) Validate added in v0.13.0 

func (r *ResponseDelta) Validate() error

type ResponseMetadata 

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,omitempty"`
	CreatedAt time.Time    `json:"created_at,omitzero"`
	Extra     metadata.Map `json:"extra,omitzero"`
}

ResponseMetadata holds provider identity, usage, and response-scoped extras.

func (ResponseMetadata) MarshalJSON 

func (r ResponseMetadata) MarshalJSON() ([]byte, error)

func (*ResponseMetadata) UnmarshalJSON 

func (r *ResponseMetadata) UnmarshalJSON(data []byte) error

type Role 

type Role string

Role identifies a message's participant in a conversation. 

const (
	// RoleSystem carries model instructions.
	RoleSystem Role = "system"
	// RoleUser carries user input.
	RoleUser Role = "user"
	// RoleAssistant carries model output.
	RoleAssistant Role = "assistant"
	// RoleTool carries results for tool calls requested by the assistant.
	RoleTool Role = "tool"
)

func (Role) Valid 

func (r Role) Valid() bool

type StreamMiddleware 

type StreamMiddleware func(next Streamer) Streamer

StreamMiddleware wraps the optional Streamer capability.

type Streamer 

type Streamer interface {
	// Stream starts provider work lazily when the sequence is iterated. Each
	// yielded response is an independently owned delta accepted by
	// ResponseAccumulator. Stopping iteration releases provider resources before
	// the iterator returns; a terminal error is yielded at most once.
	Stream(ctx context.Context, request *Request) iter.Seq2[*ResponseDelta, error]
}

Streamer is the optional streaming chat capability. It is independent of Model so an implementation is not forced to provide a synthetic synchronous Call path, and a call-only implementation is not forced to fake streaming.

Every successful yield is a valid ResponseDelta. Usage, when present, is a cumulative snapshot rather than a per-chunk increment. On failure the sequence yields (nil, err) once and terminates. Context errors retain their errors.Is identity. When the caller stops iteration, implementations must synchronously release provider resources without yielding a cancellation error or leaving a detached goroutine behind. ResponseAccumulator defines the provider-neutral aggregation semantics.

func WrapStream 

func WrapStream(streamer Streamer, middlewares ...StreamMiddleware) Streamer

WrapStream composes stream middlewares around streamer using the same outermost-first order as Wrap.

type StreamerFunc 

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

StreamerFunc adapts a function to Streamer without coupling it to Model.

func (StreamerFunc) Stream 

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

type ToolCall 

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

ToolCall is one complete, untrusted model proposal to invoke a named tool. Arguments retains the provider's JSON text so malformed final model output remains serializable. A runtime must promote the proposal through the bound Tool schema before exposing it to capabilities or execution.

func (ToolCall) Validate 

func (t ToolCall) Validate() error

type ToolCallDelta 

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

ToolCallDelta is one streaming fragment of a ToolCall. It cannot appear in a Request; ResponseAccumulator is the only boundary that promotes fragments to a complete ToolCall.

func (ToolCallDelta) Validate 

func (t ToolCallDelta) Validate() error

type ToolChoice added in v0.13.0 

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

ToolChoice owns how a model may select client tools. The zero parallelism delegates concurrency policy to the provider.

func (*ToolChoice) Clone added in v0.13.0 

func (t *ToolChoice) Clone() *ToolChoice

func (ToolChoice) Validate added in v0.13.0 

func (t ToolChoice) Validate() error

type ToolChoiceMode added in v0.13.0 

type ToolChoiceMode string

ToolChoiceMode states whether the model may choose tools, must choose one, or must invoke one exact named tool. 

const (
	ToolChoiceAuto     ToolChoiceMode = "auto"
	ToolChoiceNone     ToolChoiceMode = "none"
	ToolChoiceRequired ToolChoiceMode = "required"
	ToolChoiceNamed    ToolChoiceMode = "named"
)

Portable tool selection modes map only controls shared by provider APIs.

func (ToolChoiceMode) Valid added in v0.13.0 

func (t ToolChoiceMode) Valid() bool

type ToolContent added in v0.21.0 

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

ToolContent is one text or media value in a ToolOutput. Kind must be PartText or PartMedia. It shares media and citation contracts with Part without admitting chat control payloads or recursively nested tool results.

func (ToolContent) Clone added in v0.21.0 

func (t ToolContent) Clone() ToolContent

func (ToolContent) MarshalJSON added in v0.21.0 

func (t ToolContent) MarshalJSON() ([]byte, error)

func (*ToolContent) UnmarshalJSON added in v0.21.0 

func (t *ToolContent) UnmarshalJSON(data []byte) error

func (ToolContent) Validate added in v0.21.0 

func (t ToolContent) Validate() error

type ToolDefinition 

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

ToolDefinition is the serializable description exposed to a model. Tool execution belongs to package tool and is deliberately absent here.

func (ToolDefinition) Clone 

func (t ToolDefinition) Clone() ToolDefinition

func (ToolDefinition) MarshalJSON 

func (t ToolDefinition) MarshalJSON() ([]byte, error)

func (*ToolDefinition) UnmarshalJSON 

func (t *ToolDefinition) UnmarshalJSON(data []byte) error

func (ToolDefinition) Validate 

func (t ToolDefinition) Validate() error

type ToolOutput 

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

ToolOutput is the provider-neutral value produced by a Tool. Content is the model-visible ordered text/media representation. Details is optional JSON for structured consumers; providers use its encoded JSON as the model-visible fallback only when Content is empty.

Content cannot contain chat control payloads or recursively contain results.

func NewJSONToolOutput 

func NewJSONToolOutput(value json.RawMessage) (ToolOutput, error)

NewJSONToolOutput returns a structured output whose exact JSON encoding is preserved. The value must be one complete RFC 7493 JSON document.

func NewTextToolOutput 

func NewTextToolOutput(text string) ToolOutput

NewTextToolOutput returns a text output. Empty text is represented by the valid zero ToolOutput rather than an invalid empty text Part.

func (ToolOutput) Clone 

func (t ToolOutput) Clone() ToolOutput

func (ToolOutput) MarshalJSON added in v0.13.0 

func (t ToolOutput) MarshalJSON() ([]byte, error)

func (ToolOutput) Text 

func (t ToolOutput) Text() (string, bool)

Text returns the lossless text projection used by providers whose tool result protocol accepts only strings. It reports false when Content contains media so adapters cannot silently discard it. Details is encoded only when Content is empty.

func (*ToolOutput) UnmarshalJSON added in v0.13.0 

func (t *ToolOutput) UnmarshalJSON(data []byte) error

func (ToolOutput) Validate 

func (t ToolOutput) Validate() error

type ToolParallelism added in v0.13.0 

type ToolParallelism string

ToolParallelism states whether one response may request multiple calls; the zero value delegates the decision to the provider. 

const (
	ToolParallelismAllow  ToolParallelism = "allow"
	ToolParallelismSingle ToolParallelism = "single"
)

Explicit tool parallelism modes avoid encoding provider booleans into the shared protocol.

func (ToolParallelism) Valid added in v0.13.0 

func (t ToolParallelism) Valid() bool

type ToolResult 

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

ToolResult is one tool execution result correlated to a ToolCall by ID.

func (ToolResult) Clone 

func (t ToolResult) Clone() ToolResult

func (ToolResult) Validate 

func (t ToolResult) Validate() error

type Usage 

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,omitempty"`
	OutputTokens          int64  `json:"output_tokens,omitempty"`
	ReasoningTokens       *int64 `json:"reasoning_tokens,omitempty"`
	CacheReadInputTokens  *int64 `json:"cache_read_input_tokens,omitempty"`
	CacheWriteInputTokens *int64 `json:"cache_write_input_tokens,omitempty"`
}

Usage records provider-neutral token counts. Breakdown pointers distinguish an explicitly reported zero from an unsupported dimension.

func (Usage) MarshalJSON 

func (u Usage) MarshalJSON() ([]byte, error)

func (Usage) TotalTokens 

func (u Usage) TotalTokens() int64

TotalTokens returns the provider-reported input and output totals without double-counting their optional breakdowns.

func (*Usage) UnmarshalJSON 

func (u *Usage) UnmarshalJSON(data []byte) error

func (Usage) Validate 

func (u Usage) Validate() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.