core

package
v0.1.20 Latest Latest
Warning

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

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

Documentation

Overview

Package core provides the high-level AI SDK orchestration functions: GenerateText, StreamText, and supporting types for tools, structured output, and stop conditions.

This package is the Go re-interpretation of the AI SDK Core layer (generateText, streamText). It builds on the lower-level chat.Provider interface and adds tool-calling loops, multi-step reasoning, output parsing, and streaming control.

The primary entry points are:

  • GenerateText: non-streaming text generation with optional tool calling and structured output.
  • StreamText: streaming text generation with the same capabilities.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNoProvider indicates no chat provider was configured.
	ErrNoProvider = errors.New("core: no chat provider configured")

	// ErrNoOutputGenerated indicates the model produced no output.
	ErrNoOutputGenerated = errors.New("core: no output generated")

	// ErrToolNotFound indicates a tool call referenced a tool not in the tool set.
	ErrToolNotFound = errors.New("core: tool not found")

	// ErrToolExecutionFailed indicates a tool's execute function returned an error.
	ErrToolExecutionFailed = errors.New("core: tool execution failed")

	// ErrMaxStepsReached indicates generation was stopped by a step-count stop condition.
	ErrMaxStepsReached = errors.New("core: max steps reached")

	// ErrAborted indicates the generation was cancelled via context or abort signal.
	ErrAborted = errors.New("core: generation aborted")
)

Functions

func GenerateImage 

func GenerateImage(ctx context.Context, provider image.Provider, req image.GenerateImageRequest) (image.GenerateImageResponse, error)

GenerateImage orchestrates a non-streaming image generation call. It follows the same high-level patterns as GenerateText: validate provider, respect context cancellation, call through to the provider, and wrap sentinel errors with core context.

func GenerateObject 

func GenerateObject(ctx context.Context, provider object.Provider, req object.Request) (object.ObjectResult, error)

GenerateObject orchestrates a non-streaming object generation call. It follows the same high-level patterns as GenerateImage: validate provider, respect context cancellation, call through to the provider, and wrap sentinel errors with core context.

func GenerateSpeech 

func GenerateSpeech(ctx context.Context, provider speech.Provider, req speech.GenerateSpeechRequest) (speech.GenerateSpeechResponse, error)

GenerateSpeech performs a non-streaming speech generation by delegating to the provided speech.Provider. It follows the same orchestration patterns as GenerateText: respect context cancellation, validate the provider, and wrap provider errors with core context.

func GenerateVideo 

func GenerateVideo(ctx context.Context, provider video.Provider, req video.GenerateVideoRequest) (video.GenerateVideoResponse, error)

GenerateVideo orchestrates a non-streaming video generation call. It follows the same high-level patterns as GenerateImage: validate provider, respect context cancellation, call through to the provider, and wrap sentinel errors with core context.

func StreamObject 

func StreamObject(ctx context.Context, provider object.Provider, req object.Request) (object.ObjectStream, error)

StreamObject orchestrates a streaming object generation call. It validates the provider, respects context cancellation, and delegates to the provider. The caller must Close the returned ObjectStream when finished.

func Transcribe 

func Transcribe(ctx context.Context, provider transcribe.Provider, req transcribe.TranscribeRequest) (transcribe.TranscribeResponse, error)

Transcribe orchestrates a non-streaming transcription call. It validates the provider, respects context cancellation, delegates to the provider, and wraps provider errors with core context.

Types

type FinishReason 

type FinishReason string

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

Standard finish reasons.

type GenerateOptions 

type GenerateOptions struct {
	// Model is the model identifier passed to the provider.
	Model string
	// System is a system-level instruction.
	System string
	// Prompt is a simple text prompt. Mutually exclusive with Messages.
	Prompt string
	// Messages is a list of prior conversation turns.
	Messages []chat.Message
	// Tools is the set of callable tools.
	Tools ToolSet
	// MaxSteps limits the number of tool-calling loops. Defaults to 1.
	MaxSteps int
	// Temperature controls sampling randomness.
	Temperature float32
	// MaxTokens limits the total output tokens.
	MaxTokens int
	// StopWhen is an optional stop condition. Defaults to StepCountIs(1).
	StopWhen StopCondition
	// ProviderOptions carries provider-specific options keyed by
	// provider name (e.g. "openai", "anthropic"). These are passed
	// directly to chat.Request.ProviderOptions.
	ProviderOptions map[string]any
}

GenerateOptions configures a GenerateText call.

type GenerateResult 

type GenerateResult struct {
	// FinishReason describes why generation stopped.
	FinishReason FinishReason `json:"finish_reason"`
	// Text is the final text content (concatenation of all step Text).
	Text string `json:"text"`
	// Parts is the canonical multimodal content of the final step.
	// For multi-step runs, only the last step's Parts are exposed here;
	// per-step Parts are available via Steps.
	Parts chat.Parts `json:"parts,omitempty"`
	// Reasoning is the concatenated reasoning text from the final step.
	Reasoning string `json:"reasoning,omitempty"`
	// ToolCalls contains all tool calls across all steps.
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`
	// ToolResults contains all tool execution results across all steps.
	ToolResults []ToolResult `json:"tool_results,omitempty"`
	// Steps contains the per-step detail.
	Steps []StepResult `json:"steps"`
	// TotalUsage is the aggregate token usage across all steps.
	TotalUsage chat.Usage `json:"total_usage"`
	// Warnings contains all non-fatal warnings.
	Warnings []chat.Warning `json:"warnings,omitempty"`
}

GenerateResult is the result of a GenerateText call.

func GenerateText 

func GenerateText(ctx context.Context, provider chat.Provider, opts GenerateOptions) (GenerateResult, error)

GenerateText performs a non-streaming text generation with optional tool calling. It orchestrates the tool-call loop: calling the model, executing any requested tools, and feeding results back until a stop condition is met.

This is the Go equivalent of the AI SDK's generateText function.

type ReasonFuture 

type ReasonFuture func() (FinishReason, error)

ReasonFuture is a lazily-resolved finish reason.

type StepResult 

type StepResult struct {
	// StepNumber is the zero-indexed step number.
	StepNumber int `json:"step_number"`
	// FinishReason describes why this step finished.
	FinishReason FinishReason `json:"finish_reason"`
	// Text is the concatenated text content generated in this step.
	Text string `json:"text"`
	// Parts is the canonical multimodal content produced in this step
	// (text + reasoning + future image/file outputs). Text is derived
	// from the TextPart entries; consumers that care about reasoning
	// or non-text content should iterate Parts.
	Parts chat.Parts `json:"parts,omitempty"`
	// Reasoning is the concatenated reasoning/thinking text emitted by
	// the model in this step (if the provider surfaced any). It is also
	// available on Parts as one or more chat.ReasoningPart entries.
	Reasoning string `json:"reasoning,omitempty"`
	// ToolCalls contains the tool calls made by the model in this step.
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`
	// ToolResults contains the results of executing tool calls from this step.
	ToolResults []ToolResult `json:"tool_results,omitempty"`
	// Usage reports token consumption for this step.
	Usage chat.Usage `json:"usage"`
	// Warnings contains any non-fatal warnings from the provider.
	Warnings []chat.Warning `json:"warnings,omitempty"`
}

StepResult captures the result of a single step in a multi-step generation (one LLM call and its tool executions).

type StopCondition 

type StopCondition func(steps []StepResult) bool

StopCondition is a predicate that determines whether generation should stop after processing the current step.

func AnyCondition 

func AnyCondition(conditions ...StopCondition) StopCondition

AnyCondition returns a StopCondition that stops when any of the given conditions is met.

func HasToolCall 

func HasToolCall(toolName string) StopCondition

HasToolCall returns a StopCondition that stops when the named tool has been called in any step.

func StepCountIs 

func StepCountIs(maxSteps int) StopCondition

StepCountIs returns a StopCondition that stops after maxSteps steps.

type StreamPart 

type StreamPart struct {
	// Type identifies the kind of part.
	Type StreamPartType `json:"type"`
	// TextDelta holds incremental text (Type == "text-delta").
	TextDelta string `json:"text_delta,omitempty"`
	// ReasoningDelta holds incremental reasoning text
	// (Type == "reasoning-delta"). Producers that emit reasoning send
	// these between StartStep and the first ToolCall/FinishStep so
	// downstream UI can render thinking blocks before the answer.
	ReasoningDelta string `json:"reasoning_delta,omitempty"`
	// ToolCall holds a new tool call (Type == "tool-call").
	ToolCall *ToolCall `json:"tool_call,omitempty"`
	// ToolResult holds a tool execution outcome (Type == "tool-result").
	ToolResult *ToolResult `json:"tool_result,omitempty"`
	// Warning holds a provider warning (Type == "warning").
	Warning *chat.Warning `json:"warning,omitempty"`
	// Error holds stream-level error details (Type == "error").
	// It is serialised as ErrorString over the wire and reconstructed
	// as errors.New(ErrorString) on deserialisation.
	Error error `json:"-"`
	// ErrorString is the wire-format representation of Error.
	// Use MarshalJSON/UnmarshalJSON to convert to/from Error.
	ErrorString string `json:"error,omitempty"`
	// StepResult holds step-completion data (Type == "finish-step").
	StepResult *StepResult `json:"step_result,omitempty"`
	// FinishReason holds the final reason (Type == "finish").
	FinishReason FinishReason `json:"finish_reason,omitempty"`
	// TotalUsage holds the aggregate usage (Type == "finish").
	TotalUsage *chat.Usage `json:"total_usage,omitempty"`
}

StreamPart is a single event in a streaming text generation.

func (StreamPart) MarshalJSON 

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

MarshalJSON serialises a StreamPart to JSON, converting the Error field to ErrorString so it is not silently dropped.

func (*StreamPart) UnmarshalJSON 

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

UnmarshalJSON deserialises a StreamPart from JSON, reconstructing the Error field from ErrorString.

type StreamPartType 

type StreamPartType string

StreamPartType identifies the type of a stream part. 

const (
	StreamPartTextDelta      StreamPartType = "text-delta"
	StreamPartReasoningDelta StreamPartType = "reasoning-delta"
	StreamPartToolCall       StreamPartType = "tool-call"
	StreamPartToolResult     StreamPartType = "tool-result"
	StreamPartStartStep      StreamPartType = "start-step"
	StreamPartFinishStep     StreamPartType = "finish-step"
	StreamPartFinish         StreamPartType = "finish"
	StreamPartError          StreamPartType = "error"
	StreamPartAbort          StreamPartType = "abort"
	StreamPartWarning        StreamPartType = "warning"
)

Stream part type constants.

type StreamResult 

type StreamResult struct {
	// FullStream delivers all stream parts (text deltas, tool calls,
	// tool results, step boundaries, etc.).
	FullStream <-chan StreamPart `json:"-"`
	// TextStream delivers only text deltas.
	TextStream <-chan string `json:"-"`
	// Usage is a future that resolves to the total token usage.
	Usage UsageFuture `json:"-"`
	// FinishReason is a future that resolves to the final finish reason.
	FinishReason ReasonFuture `json:"-"`
}

StreamResult is the result of a StreamText call.

Use the FullStream, TextStream, or Text methods to consume the streaming output.

func StreamText 

func StreamText(ctx context.Context, provider chat.Provider, opts GenerateOptions) (StreamResult, error)

StreamText performs a streaming text generation with optional tool calling. It returns a StreamResult that exposes channels for incremental text, tool calls, and step boundaries.

The implementation runs a producer goroutine that drives the underlying chat.Provider.ChatStream, assembles tool-call deltas across chunks, executes any requested tools via GenerateOptions.Tools, and feeds tool results back to the model until GenerateOptions.StopWhen (or the default StepCountIs(MaxSteps)) terminates the loop.

Channel contract:

  • FullStream is the authoritative event stream and MUST be drained by the caller until it is closed. Its writes are synchronous — a slow consumer applies natural backpressure to the producer.
  • TextStream is a convenience view emitting only text deltas. Its writes are best-effort: if the consumer is not draining TextStream the SDK drops deltas rather than stalling the producer. Callers that need every text delta should consume StreamPartTextDelta events from FullStream.
  • Usage and FinishReason are futures that block until the producer completes; they return any terminal error from the run.

This shape integrates directly with goroutine + channel transports such as DirectTransport in pkg/ui/chat — adapters can range over FullStream and translate [StreamPart]s into their wire vocabulary.

Cancellation: the producer respects ctx — when ctx is cancelled an abort event is emitted and the channels close. Callers should still drain FullStream until close to release the producer.

type Tool 

type Tool struct {
	// Name is the identifier the model uses to call this tool.
	Name string `json:"name"`
	// Description helps the model decide when to call this tool.
	Description string `json:"description,omitempty"`
	// Parameters is a JSON Schema describing the tool's input.
	Parameters json.RawMessage `json:"parameters,omitempty"`
	// Execute is called when the model requests this tool.
	// It receives the JSON-encoded input arguments and returns the
	// JSON-encoded output or an error.
	Execute func(ctx context.Context, input string) (output string, err error) `json:"-"`
}

Tool defines a callable tool that a language model can invoke during generation. It mirrors the AI SDK's tool type.

func NewTool 

func NewTool(name, description string, parameters json.RawMessage, execute func(ctx context.Context, input string) (string, error)) *Tool

NewTool creates a Tool with the given name, description, JSON Schema parameters, and execute function.

type ToolCall 

type ToolCall struct {
	// ToolCallID is a provider-assigned identifier for this invocation.
	ToolCallID string `json:"tool_call_id"`
	// ToolName identifies which tool to invoke.
	ToolName string `json:"tool_name"`
	// Input holds the JSON-encoded arguments for the tool.
	Input string `json:"input"`
}

ToolCall represents a single tool invocation requested by the model.

type ToolResult 

type ToolResult struct {
	// ToolCallID matches the originating tool call.
	ToolCallID string `json:"tool_call_id"`
	// ToolName matches the originating tool call.
	ToolName string `json:"tool_name"`
	// Output is the JSON-encoded result returned by the tool.
	Output string `json:"output"`
	// Error is non-empty when tool execution failed.
	Error string `json:"error,omitempty"`
}

ToolResult is the outcome of executing a single ToolCall.

type ToolSet 

type ToolSet map[string]*Tool

ToolSet is a map of tool name to Tool, used for type-safe tool configuration.

type UsageFuture 

type UsageFuture func() (chat.Usage, error)

UsageFuture is a lazily-resolved total usage value.

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.