stream

package
v0.1.9 Latest Latest
Warning

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

Go to latest
Published: Sep 16, 2026 License: Apache-2.0 Imports: 4 Imported by: 20

Documentation

Overview

Package stream defines the streaming events from LLM responses. This mirrors the ai-sdk fullStream event types.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IntPtr

func IntPtr(v int) *int

IntPtr returns a pointer to an int. Convenience helper for constructing Usage values from raw integers, since all Usage token fields are *int.

Types

type CallOptions

type CallOptions struct {
	// Messages is the conversation history.
	Messages []message.Message `json:"messages,omitempty"`

	// Tools is the ordered list of tools (already prepared by the core).
	Tools []tool.Tool `json:"tools,omitempty"`

	// ToolChoice controls how the model selects tools.
	ToolChoice any `json:"toolChoice,omitempty"`

	// Temperature controls randomness (0-2).
	Temperature *float64 `json:"temperature,omitempty"`

	// TopP controls nucleus sampling (0-1).
	TopP *float64 `json:"topP,omitempty"`

	// TopK controls top-k sampling.
	TopK *int `json:"topK,omitempty"`

	// PresencePenalty affects the likelihood of the model to repeat
	// information already in the prompt. Mirrors ai-sdk's CallOptions.
	PresencePenalty *float64 `json:"presencePenalty,omitempty"`

	// FrequencyPenalty affects the likelihood of the model to repeatedly
	// use the same words or phrases. Mirrors ai-sdk's CallOptions.
	FrequencyPenalty *float64 `json:"frequencyPenalty,omitempty"`

	// Seed requests deterministic sampling when supported by the provider.
	// Mirrors ai-sdk's CallOptions.
	Seed *int `json:"seed,omitempty"`

	// MaxOutputTokens limits the response length.
	MaxOutputTokens *int `json:"maxOutputTokens,omitempty"`

	// StopSequences are strings that stop generation.
	StopSequences []string `json:"stopSequences,omitempty"`

	// AbortSignal allows cancellation (not serializable).
	AbortSignal context.Context `json:"-"`

	// Headers are additional HTTP headers.
	Headers map[string]string `json:"headers,omitempty"`

	// ResponseFormat configures structured output (text or json with optional schema).
	ResponseFormat *ResponseFormat `json:"responseFormat,omitempty"`

	// IncludeRawChunks, when true, makes streaming providers emit a
	// RawChunkEvent for each upstream SSE payload before the translated
	// events. Off by default. Mirrors ai-sdk v4 includeRawChunks.
	IncludeRawChunks bool `json:"includeRawChunks,omitempty"`

	// Reasoning selects shared effort, translated to provider-specific levels
	// or thinking budgets. Empty and provider-default preserve defaults.
	// Explicit options follow provider-specific precedence (see README).
	Reasoning ReasoningEffort `json:"reasoning,omitempty"`

	// ProviderOptions are provider-specific options.
	ProviderOptions map[string]any `json:"providerOptions,omitempty"`
}

CallOptions is the provider-facing input (like ai-sdk's LanguageModelV4CallOptions). This is what providers receive - it has Tools as an already-ordered slice.

type ErrorEvent

type ErrorEvent struct {
	Error error `json:"error"`
}

ErrorEvent signals an error during streaming.

type Event

type Event struct {
	Type EventType
	Data EventData
}

Event represents a single streaming event.

func ToolOutcomeEvent added in v0.1.4

func ToolOutcomeEvent(toolCallID, toolName string, input json.RawMessage, out message.ToolResultOutput, title string, metadata map[string]any) Event

ToolOutcomeEvent wraps a tool output into the stream event whose kind matches its discriminated outcome: success → tool-result, error → tool-error, execution-denied → tool-output-denied. Shared by every producer so consumers that branch on event type get a consistent signal while the carried Output keeps the full union. title and metadata ride only on the success outcome — the discriminated error/denied variants carry no tool-supplied metadata.

type EventData

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

EventData is the interface for all event data types.

type EventType

type EventType string

EventType represents the type of streaming event.

const (
	EventStart            EventType = "start"
	EventTextStart        EventType = "text-start"
	EventTextDelta        EventType = "text-delta"
	EventTextEnd          EventType = "text-end"
	EventToolInputStart   EventType = "tool-input-start"
	EventToolInputDelta   EventType = "tool-input-delta"
	EventToolInputEnd     EventType = "tool-input-end"
	EventToolCall         EventType = "tool-call"
	EventToolResult       EventType = "tool-result"
	EventToolError        EventType = "tool-error"
	EventToolOutputDenied EventType = "tool-output-denied"
	EventReasoningStart   EventType = "reasoning-start"
	EventReasoningDelta   EventType = "reasoning-delta"
	EventReasoningEnd     EventType = "reasoning-end"
	EventStartStep        EventType = "start-step"
	EventFinishStep       EventType = "finish-step"
	EventFinish           EventType = "finish"
	EventError            EventType = "error"
	EventRawChunk         EventType = "raw"
	EventSource           EventType = "source"
)

type FailedToolCall

type FailedToolCall struct {
	ToolCallID string
	ToolName   string
	Input      json.RawMessage
	Error      error
}

FailedToolCall contains information about a failed tool call.

type FinishEvent

type FinishEvent struct {
	FinishReason     FinishReason   `json:"finishReason"`
	Usage            Usage          `json:"usage"`
	ProviderMetadata map[string]any `json:"providerMetadata,omitempty"`
}

FinishEvent signals the end of the stream.

type FinishReason

type FinishReason string

FinishReason indicates why the model stopped generating.

const (
	FinishReasonStop          FinishReason = "stop"
	FinishReasonLength        FinishReason = "length"
	FinishReasonContentFilter FinishReason = "content-filter"
	FinishReasonToolCalls     FinishReason = "tool-calls"
	FinishReasonError         FinishReason = "error"
	FinishReasonOther         FinishReason = "other"
)

type FinishStepEvent

type FinishStepEvent struct {
	FinishReason     FinishReason   `json:"finishReason"`
	Usage            Usage          `json:"usage"`
	ProviderMetadata map[string]any `json:"providerMetadata,omitempty"`
}

FinishStepEvent signals the end of a processing step.

type Input

type Input struct {
	// Model is the language model to use.
	Model Model

	// Messages is the conversation history.
	Messages []message.Message

	// Instructions is the system prompt, supplied out-of-band from Messages.
	// When set, it is sent to the provider as the leading system message.
	// Preferring this over a RoleSystem entry in Messages keeps the trusted
	// system channel separate from conversation content. Mirrors ai-sdk's
	// instructions option (renamed from system).
	Instructions string

	// AllowSystemInMessages opts into accepting RoleSystem entries inside
	// Messages. It is reserved for the future default-reject behavior; today
	// RoleSystem messages are always accepted.
	AllowSystemInMessages bool

	// Tools is the set of available tools (user-facing).
	// The core converts this to an ordered slice before passing to providers.
	Tools tool.Set

	// ActiveTools limits which tools the model can use (optional).
	ActiveTools []string

	// ToolOrder controls the order tool definitions are sent to the provider.
	// Tools named here are sent first in this order; the rest follow in their
	// default (alphabetical) order. ActiveTools filters first, then ToolOrder
	// orders the survivors. A stable order helps providers reuse cached
	// request prefixes. Mirrors ai-sdk's toolOrder option.
	ToolOrder []string

	// ToolChoice controls how the model selects tools.
	// Can be "auto", "none", "required", or a specific tool name.
	// Matches ai-sdk's toolChoice parameter.
	ToolChoice any

	// Temperature controls randomness (0-2).
	Temperature *float64

	// TopP controls nucleus sampling (0-1).
	TopP *float64

	// TopK controls top-k sampling.
	TopK *int

	// MaxOutputTokens limits the response length.
	MaxOutputTokens *int

	// StopSequences are strings that stop generation.
	StopSequences []string

	// AbortSignal allows cancellation.
	AbortSignal context.Context

	// Headers are additional HTTP headers.
	Headers map[string]string

	// MaxRetries is the number of provider stream-setup retries. The default is
	// 2. Set MaxRetriesSet when explicitly configuring this value, including 0.
	MaxRetries    int
	MaxRetriesSet bool

	// ProviderOptions are provider-specific options.
	ProviderOptions map[string]any

	// IncludeRawChunks, when true, makes streaming providers emit a
	// RawChunkEvent for each upstream SSE payload before the translated
	// events. Off by default. Mirrors ai-sdk v4 includeRawChunks.
	IncludeRawChunks bool

	// Reasoning selects shared effort: none, minimal, low, medium, high, or
	// xhigh. Empty and provider-default leave provider defaults untouched.
	// Providers translate effort to supported levels or thinking budgets;
	// explicit options follow provider-specific precedence (see README).
	Reasoning ReasoningEffort

	// Output is the optional output strategy for parsing the model's response.
	// When set, ResponseFormat is sent to the model on every step, and the
	// final step's text is parsed via Output.ParseComplete (only when the
	// final step finishes with FinishReasonStop).
	Output Output

	// OnError is called when an error occurs.
	OnError func(error)

	// RepairToolCall attempts to fix malformed tool calls.
	RepairToolCall func(failed FailedToolCall) (*RepairedToolCall, error)

	// RefineToolInput is an experimental hook that runs after a tool call's
	// input has been parsed (and any RepairToolCall completed) but before
	// the tool executes. Different LLM providers can produce slightly
	// different inputs for the same schema (e.g. empty string vs null);
	// this lets callers normalize them. The refined bytes must remain
	// schema-shaped — input validation does not run again.
	//
	// Returning an error fails the call as if the model had emitted bad
	// input. Mirrors ai-sdk experimental_refineToolInput (#15000).
	RefineToolInput func(toolName string, input json.RawMessage) (json.RawMessage, error)

	// MaxSteps is the maximum number of tool-calling steps (default 1).
	// When > 1, tools are executed automatically and the model is called again
	// until a stop condition is met or MaxSteps is reached.
	MaxSteps int

	// OnStart is called once before the first step, with the resolved request.
	OnStart func(data StartData)

	// OnStepStart is called before each step's model call.
	OnStepStart func(data StepStartData)

	// OnStepEnd is called after each step completes.
	// Receives the step result with all content, tool calls, and tool results.
	OnStepEnd func(step StepResultData)

	// OnEnd is called after all steps complete.
	// Receives the final step result plus all accumulated steps and total usage.
	OnEnd func(result OnEndData)

	// Executor handles tool execution. If nil, tools are executed locally
	// using their Execute functions. Set this to use remote execution.
	Executor tool.Executor

	// ToolCallExecutionMode controls execution of tool calls emitted in the
	// same model response. Empty defaults to sync.
	ToolCallExecutionMode ToolCallExecutionMode
}

Input represents the input to StreamText.

type InputTokens

type InputTokens struct {
	// Total is the total number of input (prompt) tokens.
	Total *int `json:"total,omitempty"`
	// NoCache is the number of non-cached input tokens.
	NoCache *int `json:"noCache,omitempty"`
	// CacheRead is the number of cached input tokens read.
	CacheRead *int `json:"cacheRead,omitempty"`
	// CacheWrite is the number of cached input tokens written.
	CacheWrite *int `json:"cacheWrite,omitempty"`
}

InputTokens holds the prompt-side token breakdown.

type Model

type Model interface {
	// ID returns the model identifier.
	ID() string

	// Provider returns the provider identifier.
	Provider() string

	// Stream sends a request and returns a stream of events.
	Stream(ctx context.Context, options *CallOptions) (<-chan Event, error)
}

Model represents a language model.

type OnEndData added in v0.1.4

type OnEndData struct {
	// Steps contains all step results from the generation.
	Steps []StepResultData
	// TotalUsage is the accumulated token usage across all steps.
	TotalUsage Usage
	// FinalStep is the last step result.
	FinalStep StepResultData
}

OnEndData contains data passed to the OnEnd callback.

type Output

type Output interface {
	// Name returns the name of the output mode.
	Name() string

	// ResponseFormat returns the response format configuration for the model.
	ResponseFormat() *ResponseFormat

	// ParseComplete parses the complete model output.
	ParseComplete(text string, ctx OutputParseContext) (any, error)

	// ParsePartial parses partial output during streaming.
	// Returns nil if the partial output cannot be parsed.
	ParsePartial(text string) any
}

Output is the interface for output strategies (text, object, array, choice, json). Implementations live in the goai/output package.

type OutputParseContext

type OutputParseContext struct {
	FinishReason FinishReason
	Usage        Usage
}

OutputParseContext provides context for parsing complete output.

type OutputTokens

type OutputTokens struct {
	// Total is the total number of output (completion) tokens.
	Total *int `json:"total,omitempty"`
	// Text is the number of text-output tokens.
	Text *int `json:"text,omitempty"`
	// Reasoning is the number of reasoning/thinking tokens.
	Reasoning *int `json:"reasoning,omitempty"`
}

OutputTokens holds the completion-side token breakdown.

type RawChunkEvent

type RawChunkEvent struct {
	RawValue any `json:"rawValue"`
}

RawChunkEvent carries an unparsed payload from the upstream provider. Emitted only when CallOptions.IncludeRawChunks is true. RawValue is typically the SSE "data: …" string with the prefix already trimmed; providers may emit []byte or a parsed object when that's more useful. Mirrors ai-sdk's v4 raw stream-part (LanguageModelV4StreamPart).

type ReasoningDeltaEvent

type ReasoningDeltaEvent struct {
	ID               string         `json:"id"`
	Text             string         `json:"text"`
	ProviderMetadata map[string]any `json:"providerMetadata,omitempty"`
}

ReasoningDeltaEvent contains a chunk of reasoning text.

type ReasoningEffort

type ReasoningEffort = string

ReasoningEffort is the uniform top-level reasoning-effort enum. Mirrors ai-sdk v4 LanguageModelV4CallOptions.reasoning.

const (
	ReasoningEffortNone    ReasoningEffort = "none"
	ReasoningEffortMinimal ReasoningEffort = "minimal"
	ReasoningEffortLow     ReasoningEffort = "low"
	ReasoningEffortMedium  ReasoningEffort = "medium"
	ReasoningEffortHigh    ReasoningEffort = "high"
	ReasoningEffortXHigh   ReasoningEffort = "xhigh"
)

Reasoning effort values. Empty string and provider-default both mean "use the provider's default".

type ReasoningEndEvent

type ReasoningEndEvent struct {
	ID               string         `json:"id"`
	ProviderMetadata map[string]any `json:"providerMetadata,omitempty"`
}

ReasoningEndEvent signals the end of reasoning.

type ReasoningStartEvent

type ReasoningStartEvent struct {
	ID               string         `json:"id"`
	ProviderMetadata map[string]any `json:"providerMetadata,omitempty"`
}

ReasoningStartEvent signals the start of reasoning/thinking.

type RepairedToolCall

type RepairedToolCall struct {
	ToolName string
	Input    json.RawMessage
}

RepairedToolCall contains the repaired tool call.

type ResponseFormat

type ResponseFormat struct {
	// Type is "text" or "json".
	Type string `json:"type"`

	// Schema is the JSON schema for structured output (when Type is "json").
	Schema json.RawMessage `json:"schema,omitempty"`

	// Name is an optional name for the schema.
	Name string `json:"name,omitempty"`

	// Description is an optional description for the schema.
	Description string `json:"description,omitempty"`
}

ResponseFormat configures how the model should format its response. Mirrors ai-sdk's LanguageModelV4CallOptions.responseFormat.

type Result

type Result struct {
	// FullStream is a channel that receives all streaming events.
	FullStream <-chan Event

	// Text returns the final complete text when streaming is done.
	// If streaming fails after partial output, it returns the partial text and the error.
	// This blocks until the stream is complete.
	Text func() (string, error)

	// ToolCalls returns all tool calls made during generation.
	// This blocks until the stream is complete.
	ToolCalls func() []ToolCall

	// ToolResults returns all tool results.
	// This blocks until the stream is complete.
	ToolResults func() []ToolResultEvent

	// Sources returns all citation sources (URLs / documents) emitted by
	// hosted search/retrieval tools across all steps. Mirrors ai-sdk's
	// StreamTextResult.sources. Blocks until the stream is complete.
	Sources func() []SourceEvent

	// FinishReason returns why the generation stopped.
	// If streaming fails, it returns the best known finish reason and the error.
	// This blocks until the stream is complete.
	FinishReason func() (FinishReason, error)

	// Usage returns token usage statistics.
	// If streaming fails, it returns accumulated usage and the error.
	// This blocks until the stream is complete.
	Usage func() (Usage, error)

	// Output returns the parsed output when an Output strategy was provided
	// on Input and the final step finished with FinishReasonStop.
	// Returns nil otherwise. Blocks until the stream is complete.
	Output func() any
}

Result represents the result of a streaming text generation.

type SourceEvent added in v0.1.2

type SourceEvent struct {
	SourceType       SourceType     `json:"sourceType"`
	ID               string         `json:"id"`
	URL              string         `json:"url,omitempty"`
	Title            string         `json:"title,omitempty"`
	MediaType        string         `json:"mediaType,omitempty"`
	Filename         string         `json:"filename,omitempty"`
	ProviderMetadata map[string]any `json:"providerMetadata,omitempty"`
}

SourceEvent reports a source the model used to generate the response — emitted by providers when a hosted tool (web_search, google_search, file_search, ...) cites a URL or document. Mirrors ai-sdk's LanguageModelV4Source content part.

SourceType discriminates which fields are meaningful:

  • SourceTypeURL: ID, URL, Title.
  • SourceTypeDocument: ID, MediaType, Title, Filename.

ProviderMetadata carries provider-specific extras (e.g. OpenAI's file_id and container_id on file_citation annotations).

type SourceType added in v0.1.2

type SourceType string

SourceType is the discriminator on SourceEvent. Mirrors ai-sdk's LanguageModelV4Source union (packages/provider/src/language-model/v4/ language-model-v4-source.ts).

const (
	// SourceTypeURL is a web source — used for url_citation annotations
	// emitted by web_search / google_search hosted tools.
	SourceTypeURL SourceType = "url"
	// SourceTypeDocument is a file/document source — used for
	// file_citation, container_file_citation, and file_path annotations.
	SourceTypeDocument SourceType = "document"
)

type StartData added in v0.1.4

type StartData struct {
	// Messages is the conversation history the generation starts from.
	Messages []message.Message
}

StartData is passed to the OnStart callback before the first step.

type StartEvent

type StartEvent struct {
	Warnings []Warning `json:"warnings,omitempty"`
}

StartEvent signals the start of streaming. Warnings surfaces non-fatal issues encountered while preparing the request (e.g. unsupported CallOptions, tools dropped by the converter).

type StartStepEvent

type StartStepEvent struct{}

StartStepEvent signals the start of a processing step.

type StepResultData

type StepResultData interface {
	Text() string
	ToolCalls() []ToolCall
	ToolResults() []ToolResultEvent
	GetFinishReason() FinishReason
	GetUsage() Usage
}

StepResultData is the minimal interface for step results needed by callbacks. The full StepResult type is defined in the main goai package.

type StepStartData added in v0.1.4

type StepStartData struct {
	// StepNumber is the zero-based index of the step about to run.
	StepNumber int
	// Messages is the conversation history sent to the model for this step.
	Messages []message.Message
}

StepStartData is passed to the OnStepStart callback before each step.

type TextDeltaEvent

type TextDeltaEvent struct {
	Text             string         `json:"text"`
	ProviderMetadata map[string]any `json:"providerMetadata,omitempty"`
}

TextDeltaEvent contains a chunk of generated text.

type TextEndEvent

type TextEndEvent struct {
	ProviderMetadata map[string]any `json:"providerMetadata,omitempty"`
}

TextEndEvent signals the end of text generation.

type TextStartEvent

type TextStartEvent struct {
	ProviderMetadata map[string]any `json:"providerMetadata,omitempty"`
}

TextStartEvent signals the start of text generation.

type ToolCall

type ToolCall struct {
	// ProviderExecuted calls are replayed but never refined or executed locally.
	ProviderExecuted bool            `json:"providerExecuted,omitempty"`
	ProviderMetadata map[string]any  `json:"providerMetadata,omitempty"`
	ID               string          `json:"id"`
	Name             string          `json:"name"`
	Input            json.RawMessage `json:"input"`
}

ToolCall represents a tool call from the model.

type ToolCallEvent

type ToolCallEvent struct {
	ProviderExecuted bool            `json:"providerExecuted,omitempty"`
	ToolCallID       string          `json:"toolCallId"`
	ToolName         string          `json:"toolName"`
	Input            json.RawMessage `json:"input"`
	ProviderMetadata map[string]any  `json:"providerMetadata,omitempty"`
}

ToolCallEvent signals a complete tool call ready for execution.

type ToolCallExecutionMode added in v0.1.7

type ToolCallExecutionMode string

ToolCallExecutionMode controls whether tool calls from one model response execute one at a time or concurrently.

const (
	ToolCallExecutionSync  ToolCallExecutionMode = "sync"
	ToolCallExecutionAsync ToolCallExecutionMode = "async"
)

type ToolErrorEvent

type ToolErrorEvent struct {
	ProviderExecuted bool                     `json:"providerExecuted,omitempty"`
	ProviderMetadata map[string]any           `json:"providerMetadata,omitempty"`
	ToolCallID       string                   `json:"toolCallId"`
	ToolName         string                   `json:"toolName"`
	Input            json.RawMessage          `json:"input,omitempty"`
	Output           message.ToolResultOutput `json:"output"`
}

ToolErrorEvent signals a failed tool execution. Output carries the error variant (error-text | error-json).

func (ToolErrorEvent) ErrorText added in v0.1.4

func (e ToolErrorEvent) ErrorText() string

ErrorText returns the error message text for this event.

func (ToolErrorEvent) MarshalJSON added in v0.1.4

func (e ToolErrorEvent) MarshalJSON() ([]byte, error)

func (*ToolErrorEvent) UnmarshalJSON added in v0.1.4

func (e *ToolErrorEvent) UnmarshalJSON(b []byte) error

type ToolInputDeltaEvent

type ToolInputDeltaEvent struct {
	ID    string `json:"id"`
	Delta string `json:"delta"`
}

ToolInputDeltaEvent contains a chunk of tool input.

type ToolInputEndEvent

type ToolInputEndEvent struct {
	ID string `json:"id"`
}

ToolInputEndEvent signals the end of tool input streaming.

type ToolInputStartEvent

type ToolInputStartEvent struct {
	ProviderExecuted bool   `json:"providerExecuted,omitempty"`
	ID               string `json:"id"`
	ToolName         string `json:"toolName"`
}

ToolInputStartEvent signals the start of tool input streaming.

type ToolOutputDeniedEvent added in v0.1.4

type ToolOutputDeniedEvent struct {
	ToolCallID string          `json:"toolCallId"`
	ToolName   string          `json:"toolName"`
	Input      json.RawMessage `json:"input,omitempty"`
	Reason     string          `json:"reason,omitempty"`
}

ToolOutputDeniedEvent signals a tool call the user/policy refused to run.

type ToolResultEvent

type ToolResultEvent struct {
	ProviderExecuted bool                     `json:"providerExecuted,omitempty"`
	ProviderMetadata map[string]any           `json:"providerMetadata,omitempty"`
	ToolCallID       string                   `json:"toolCallId"`
	ToolName         string                   `json:"toolName"`
	Input            json.RawMessage          `json:"input,omitempty"`
	Output           message.ToolResultOutput `json:"output"`
	Title            string                   `json:"title,omitempty"`
	Metadata         map[string]any           `json:"metadata,omitempty"`
}

ToolResultEvent contains a successful tool execution result. Output is a success variant of the discriminated union (text | json | content).

Title and Metadata carry the tool's presentation hints (the tool's short Result.Title and its structured Result.Metadata). Consumers that render a curated activity log — e.g. airlock's build log — use these to summarize a call without dumping the full model-facing Output.

func (ToolResultEvent) MarshalJSON added in v0.1.4

func (e ToolResultEvent) MarshalJSON() ([]byte, error)

func (*ToolResultEvent) UnmarshalJSON added in v0.1.4

func (e *ToolResultEvent) UnmarshalJSON(b []byte) error

type Usage

type Usage struct {
	InputTokens  InputTokens    `json:"inputTokens"`
	OutputTokens OutputTokens   `json:"outputTokens"`
	Raw          map[string]any `json:"raw,omitempty"`
}

Usage contains token usage information. Mirrors ai-sdk's LanguageModelV4Usage (packages/provider/src/language-model/v4/language-model-v4-usage.ts). All integer fields are pointers so "unreported by provider" (nil) is distinguishable from "reported as zero" (pointer to 0).

func UsageFrom

func UsageFrom(prompt, completion int) Usage

UsageFrom builds a Usage from a prompt/completion pair. Convenience helper for providers that only surface the totals; more detailed breakdowns should construct Usage explicitly.

func (*Usage) Add

func (u *Usage) Add(other Usage)

Add accumulates another Usage into the receiver. Nil fields on either side are treated as zero for the purposes of the sum; the result field is nil only when both sides had nil. This mirrors the common multi-step aggregation pattern in goai.GenerateText / StreamText.

func (Usage) GrandTotal

func (u Usage) GrandTotal() int

GrandTotal returns InputTotal + OutputTotal for callers that want a single aggregate number (replaces the old TotalTokens field).

func (Usage) InputTotal

func (u Usage) InputTotal() int

InputTotal returns the total input tokens, or 0 if unreported.

func (Usage) Normalized added in v0.1.7

func (u Usage) Normalized() Usage

Normalized clamps reported token counts to zero without changing Raw or the provider's pointers. Unreported counts remain nil.

func (Usage) OutputTotal

func (u Usage) OutputTotal() int

OutputTotal returns the total output tokens, or 0 if unreported.

type Warning

type Warning struct {
	Type    WarningType `json:"type"`
	Feature string      `json:"feature,omitempty"`
	Message string      `json:"message,omitempty"`
	Details string      `json:"details,omitempty"`
}

Warning reports a non-fatal issue encountered while building or processing a provider request. Mirrors ai-sdk's SharedV3Warning.

Feature is set for Unsupported/Compatibility; Message is set for Other. Details may be set for any type to provide extra context.

func CompatibilityWarning

func CompatibilityWarning(feature, details string) Warning

CompatibilityWarning builds a Warning with type=compatibility.

func OtherWarning

func OtherWarning(message string) Warning

OtherWarning builds a Warning with type=other.

func UnsupportedWarning

func UnsupportedWarning(feature, details string) Warning

UnsupportedWarning builds a Warning with type=unsupported.

type WarningType

type WarningType string

WarningType mirrors ai-sdk's SharedV3Warning discriminant (references/ai-sdk/packages/provider/src/shared/v3/shared-v3-warning.ts).

const (
	// WarningUnsupported reports a CallOption or provider-option the
	// model ignored (e.g. frequencyPenalty on Anthropic).
	WarningUnsupported WarningType = "unsupported"
	// WarningCompatibility reports an input that was silently converted
	// to make it compatible with the model (e.g. temperature clamped).
	WarningCompatibility WarningType = "compatibility"
	// WarningOther is a free-form informational warning.
	WarningOther WarningType = "other"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL