chat

package
v0.39.0 Latest Latest
Warning

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

 Go to latest Published: Sep 28, 2026 License: Apache-2.0 Imports: 19 Imported by: 51

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    = errors.New("chat: invalid message")
	ErrInvalidPart       = errors.New("chat: invalid part")
	ErrInvalidToolCall   = errors.New("chat: invalid tool call")
	ErrInvalidToolOutput = errors.New("chat: invalid tool output")
	ErrInvalidToolResult = errors.New("chat: invalid tool result")
)
View Source 
var (
	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")
View Source 
var ErrInvalidOptions = errors.New("chat: invalid options")
View Source 
var ErrInvalidRequest = errors.New("chat: invalid request")
View Source 
var ErrInvalidResponse = errors.New("chat: invalid response")
View Source 
var ErrInvalidToolChoice = errors.New("chat: invalid tool choice")
View Source 
var ErrInvalidToolDefinition = errors.New("chat: invalid tool definition")
View Source 
var ErrInvalidUsage = errors.New("chat: invalid usage")

Functions

This section is empty.

Types

type CallMiddleware 

type CallMiddleware func(next Model) Model

CallMiddleware composes synchronous model behavior. Concrete policy belongs to upper modules.

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

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 incomplete output that the caller may continue,
	// including token limits and provider pauses requiring another request.
	FinishReasonLength    FinishReason = "length"
	FinishReasonToolCalls FinishReason = "tool_calls"
	// FinishReasonContentFilter means provider policy withheld or cut short
	// generated content; FinishReasonRefusal means the model declined the request.
	FinishReasonContentFilter FinishReason = "content_filter"
	FinishReasonRefusal       FinishReason = "refusal"
	// FinishReasonOther is a terminal outcome without a portable match, such as
	// a malformed tool call. It must not hide truncation or policy stops.
	FinishReasonOther FinishReason = "other"
)

Adapters classify the outcome using these reasons and preserve the native reason in OutputMetadata.Extra.

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
}

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

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 performs a complete provider-neutral exchange; streaming is a separate capability.

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)

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,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"`
}

Options contains per-request overrides; zero values use provider defaults. Resolve overlays populated fields and snapshots mutable values without changing either input. Adapters must report unsupported populated fields, never drop them.

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,omitzero"`
	FinishReason FinishReason    `json:"finish_reason,omitempty"`
	Metadata     *OutputMetadata `json:"metadata,omitzero"`
}

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)

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,omitzero"`
}

OutputFormat is the requested representation. Name, Description, and Schema belong only to OutputFormatJSONSchema. Construction and cloning snapshot Schema.

func NewJSONSchemaOutputFormat 

func NewJSONSchemaOutputFormat(config JSONSchemaConfig) (OutputFormat, error)

func NewOutputFormat 

func NewOutputFormat(formatType OutputFormatType) (OutputFormat, error)

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)

func (*OutputFormat) UnmarshalJSON 

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

func (OutputFormat) Validate 

func (o OutputFormat) Validate() error

type OutputFormatType 

type OutputFormatType string
const (
	OutputFormatText       OutputFormatType = "text"
	OutputFormatJSON       OutputFormatType = "json"
	OutputFormatJSONSchema OutputFormatType = "json_schema"
)

type OutputMetadata 

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

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,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"`
}

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

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

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,omitzero"`
	ReasoningState []byte         `json:"reasoning_state,omitempty"`
	ToolCall       *ToolCallDelta `json:"tool_call,omitzero"`
	Citation       *Citation      `json:"citation,omitzero"`
	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

func NewMediaDelta added in v0.13.0 

func NewMediaDelta(value *media.Media) PartDelta

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

func NewTextDelta added in v0.13.0 

func NewTextDelta(text string) PartDelta

func NewToolCallDelta added in v0.13.0 

func NewToolCallDelta(delta ToolCallDelta) PartDelta

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

func (PartDeltaKind) Valid added in v0.13.0 

func (p PartDeltaKind) Valid() bool

type PartKind 

type PartKind string
const (
	PartText       PartKind = "text"
	PartMedia      PartKind = "media"
	PartReasoning  PartKind = "reasoning"
	PartToolCall   PartKind = "tool_call"
	PartToolResult PartKind = "tool_result"
	PartRefusal    PartKind = "refusal"
)

func (PartKind) Valid 

func (p PartKind) Valid() bool

type ReasoningEffort 

type ReasoningEffort string

ReasoningEffort uses the selected model's vocabulary, not a fixed enum. Adapters must reject levels they cannot express; mapping a level to a token budget would invent caller policy. Provider-specific controls use extensions.

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,omitzero"`
	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 snapshots all nested values, then validates message structure and the leading system prefix. 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,omitzero"`
	Metadata *ResponseMetadata `json:"metadata,omitzero"`
}

func NewResponse 

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

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

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

func (ResponseMetadata) MarshalJSON 

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

func (*ResponseMetadata) UnmarshalJSON 

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

type Role 

type Role string
const (
	RoleSystem    Role = "system"
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
	RoleTool      Role = "tool"
)

func (Role) Valid 

func (r Role) Valid() bool

type StreamMiddleware 

type StreamMiddleware func(next Streamer) Streamer

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 yields independently owned deltas with cumulative usage snapshots. On failure it yields (nil, err) once, preserving context error identity. Stopping iteration must synchronously release provider resources without a cancellation yield or detached goroutine. ResponseAccumulator owns aggregation.

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]

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"`
}

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
const (
	ToolChoiceAuto     ToolChoiceMode = "auto"
	ToolChoiceNone     ToolChoiceMode = "none"
	ToolChoiceRequired ToolChoiceMode = "required"
	ToolChoiceNamed    ToolChoiceMode = "named"
)

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,omitzero"`
	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,omitzero"`
}

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

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,omitzero"`
}

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,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"`
}

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.