stream

package
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: May 6, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

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 Attachment 

type Attachment struct {
	Data     string `json:"data"`
	MimeType string `json:"mimeType"`
	Filename string `json:"filename,omitempty"`
}

Attachment represents a file attachment.

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 is the uniform reasoning-effort enum. Empty string means
	// "use the provider's default" — providers that have an effort-style
	// knob will lower it to their wire-specific field. Provider-specific
	// effort options (e.g. anthropic.MessagesOptions.Effort) take
	// precedence when both are set. Mirrors ai-sdk v4 reasoning.
	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.

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

	// 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

	// 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 retry attempts.
	MaxRetries int

	// 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 is the uniform reasoning-effort enum (one of "", "none",
	// "minimal", "low", "medium", "high", "xhigh"). Empty means
	// "provider default". Provider-specific effort options take precedence
	// when both are set. Mirrors ai-sdk v4 reasoning.
	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

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

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

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

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 OnFinishData 

type OnFinishData 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
}

OnFinishData contains data passed to the OnFinish 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 means "use the provider's default" (equivalent to ai-sdk's "provider-default" sentinel; goai uses the empty string instead since Go has no first-class union types).

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.
	// This blocks until the stream is complete.
	Text func() string

	// 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.
	// This blocks until the stream is complete.
	FinishReason func() FinishReason

	// Usage returns token usage statistics.
	// This blocks until the stream is complete.
	Usage func() Usage

	// 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 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 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 {
	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 {
	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 ToolErrorEvent 

type ToolErrorEvent struct {
	ToolCallID string          `json:"toolCallId"`
	ToolName   string          `json:"toolName"`
	Input      json.RawMessage `json:"input,omitempty"`
	Error      error           `json:"error"`
}

ToolErrorEvent signals an error during tool execution.

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 {
	ID       string `json:"id"`
	ToolName string `json:"toolName"`
}

ToolInputStartEvent signals the start of tool input streaming.

type ToolOutput 

type ToolOutput struct {
	Output      string         `json:"output"`
	Title       string         `json:"title,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
	Attachments []Attachment   `json:"attachments,omitempty"`
}

ToolOutput represents the output from a tool execution.

type ToolResultEvent 

type ToolResultEvent struct {
	ToolCallID string          `json:"toolCallId"`
	ToolName   string          `json:"toolName"`
	Input      json.RawMessage `json:"input,omitempty"`
	Output     ToolOutput      `json:"output"`
}

ToolResultEvent contains the result of a tool execution.

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

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.