faux

Documentation

Overview

Package faux provides a scripted, in-memory provider for agent and provider tests.

Index

• func AssistantMessage(content any, options ...AssistantMessageOptions) *ai.AssistantMessage
• func Text(text string) *ai.TextContent
• func Thinking(thinking string) *ai.ThinkingContent
• func ToolCall(name string, arguments map[string]any, options ...ToolCallOptions) *ai.ToolCall
• type AssistantMessageOptions
• type ModelDefinition
• type Options
• type Provider
  • func New(option ...Options) *Provider
  • func (provider *Provider) API() ai.API
  • func (provider *Provider) AppendResponses(responses []ResponseStep)
  • func (provider *Provider) GetModel(modelID ...string) *ai.Model
  • func (provider *Provider) Models() []*ai.Model
  • func (provider *Provider) PendingResponseCount() int
  • func (provider *Provider) ProviderID() ai.ProviderID
  • func (provider *Provider) SetResponses(responses []ResponseStep)
  • func (provider *Provider) State() State
  • func (provider *Provider) Stream(ctx context.Context, request ai.Request) (ai.AssistantMessageEventStream, error)
  • func (provider *Provider) StreamSimple(ctx context.Context, model *ai.Model, requestContext ai.Context, ...) (ai.AssistantMessageEventStream, error)
• type ResponseFactory
• type ResponseStep
  • func Factory(factory ResponseFactory) ResponseStep
• type State
• type TokenSize
  • func FixedTokenSize(size int) TokenSize
• type ToolCallOptions

Functions

func AssistantMessage

func AssistantMessage(content any, options ...AssistantMessageOptions) *ai.AssistantMessage

AssistantMessage creates a faux assistant response from a string, one block, or ai.AssistantContent.

func Text

func Text(text string) *ai.TextContent

Text creates a faux text block.

func Thinking

func Thinking(thinking string) *ai.ThinkingContent

Thinking creates a faux thinking block.

func ToolCall

func ToolCall(name string, arguments map[string]any, options ...ToolCallOptions) *ai.ToolCall

ToolCall creates a faux tool-call block.

Types

type AssistantMessageOptions

type AssistantMessageOptions struct {
	StopReason   ai.StopReason
	ErrorMessage *string
	ResponseID   *string
	Timestamp    *int64
}

AssistantMessageOptions controls fields that differ from the helper defaults.

type ModelDefinition

type ModelDefinition struct {
	ID            string
	Name          *string
	Reasoning     bool
	Input         ai.InputModalities
	Cost          *ai.ModelCostRates
	ContextWindow *float64
	MaxTokens     *float64
}

ModelDefinition describes one model exposed by a Provider.

type Options

type Options struct {
	API             ai.API
	Provider        ai.ProviderID
	Models          []ModelDefinition
	TokensPerSecond float64
	TokenSize       TokenSize
	Now             func() int64
}

Options configures a scripted provider.

type Provider

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

Provider owns faux models, scripted responses, and prompt-cache state.

func New

func New(option ...Options) *Provider

New creates an isolated scripted provider. At most one Options value is accepted.

func (*Provider) API

func (provider *Provider) API() ai.API

API returns the provider's distinct API identifier.

func (*Provider) AppendResponses

func (provider *Provider) AppendResponses(responses []ResponseStep)

AppendResponses appends response steps in FIFO order.

func (*Provider) GetModel

func (provider *Provider) GetModel(modelID ...string) *ai.Model

GetModel returns the first model when modelID is empty, or the matching model.

func (*Provider) Models

func (provider *Provider) Models() []*ai.Model

Models returns a copy of the model pointer collection.

func (*Provider) PendingResponseCount

func (provider *Provider) PendingResponseCount() int

PendingResponseCount returns the number of unreserved response steps.

func (*Provider) ProviderID

func (provider *Provider) ProviderID() ai.ProviderID

ProviderID returns the provider identifier placed on models and messages.

func (*Provider) SetResponses

func (provider *Provider) SetResponses(responses []ResponseStep)

SetResponses replaces the pending response queue without cloning its elements.

func (*Provider) State

func (provider *Provider) State() State

State returns a consistent invocation-state snapshot.

func (*Provider) Stream

func (provider *Provider) Stream(ctx context.Context, request ai.Request) (ai.AssistantMessageEventStream, error)

Stream implements ai.StreamFn. Scripted/provider failures are terminal events; the returned error is reserved for malformed requests.

func (*Provider) StreamSimple

func (provider *Provider) StreamSimple(
	ctx context.Context,
	model *ai.Model,
	requestContext ai.Context,
	options *ai.SimpleStreamOptions,
) (ai.AssistantMessageEventStream, error)

StreamSimple has the provider-neutral direct stream signature used by agents.

type ResponseFactory

type ResponseFactory func(
	ctx context.Context,
	requestContext ai.Context,
	options *ai.StreamOptions,
	state State,
	model *ai.Model,
) (*ai.AssistantMessage, error)

ResponseFactory resolves a queued response when its request begins streaming.

type ResponseStep

type ResponseStep any

ResponseStep is either an *ai.AssistantMessage, an ai.AssistantMessage, or a ResponseFactory.

func Factory

func Factory(factory ResponseFactory) ResponseStep

Factory converts a function literal into a queueable ResponseFactory.

type State

type State struct {
	CallCount int64
}

State is a race-safe snapshot of provider invocation state.

type TokenSize

type TokenSize struct {
	Min *int
	Max *int
}

TokenSize controls the inclusive range of JavaScript-style token chunk sizes.

func FixedTokenSize

func FixedTokenSize(size int) TokenSize

FixedTokenSize configures deterministic chunk boundaries.

type ToolCallOptions

type ToolCallOptions struct {
	ID string
}

ToolCallOptions controls fields generated by ToolCall.