fantasy

type Agent interface {
	Generate(context.Context, AgentCall) (*AgentResult, error)
	Stream(context.Context, AgentStreamCall) (*AgentResult, error)
}

type AgentCall struct {
	Prompt           string     `json:"prompt"`
	Files            []FilePart `json:"files"`
	Messages         []Message  `json:"messages"`
	MaxOutputTokens  *int64
	Temperature      *float64    `json:"temperature"`
	TopP             *float64    `json:"top_p"`
	TopK             *int64      `json:"top_k"`
	PresencePenalty  *float64    `json:"presence_penalty"`
	FrequencyPenalty *float64    `json:"frequency_penalty"`
	ActiveTools      []string    `json:"active_tools"`
	ToolChoice       *ToolChoice `json:"tool_choice"`
	Headers          map[string]string
	ProviderOptions  ProviderOptions
	OnRetry          OnRetryCallback
	OnAuthRefresh    OnAuthRefreshFunc
	MaxRetries       *int

	// ModelProvider, when non-nil, is called on each retry attempt to
	// obtain the language model. This allows callers to swap in a
	// refreshed model after OnAuthRefresh rebuilds credentials. When
	// nil, the model captured at step preparation time is used.
	ModelProvider func() LanguageModel

	StopWhen       []StopCondition
	PrepareStep    PrepareStepFunction
	RepairToolCall RepairToolCallFunction
}

type AgentOption = func(*agentSettings)

type AgentResult struct {
	Steps []StepResult
	// Final response. When the last step is tool-only (no text content),
	// this is the response from the most recent step that contained text,
	// so callers always see meaningful output without walking Steps manually.
	Response   Response
	TotalUsage Usage
}

type AgentStreamCall struct {
	Prompt           string     `json:"prompt"`
	Files            []FilePart `json:"files"`
	Messages         []Message  `json:"messages"`
	MaxOutputTokens  *int64
	Temperature      *float64    `json:"temperature"`
	TopP             *float64    `json:"top_p"`
	TopK             *int64      `json:"top_k"`
	PresencePenalty  *float64    `json:"presence_penalty"`
	FrequencyPenalty *float64    `json:"frequency_penalty"`
	ActiveTools      []string    `json:"active_tools"`
	ToolChoice       *ToolChoice `json:"tool_choice"`
	Headers          map[string]string
	ProviderOptions  ProviderOptions
	OnRetry          OnRetryCallback
	OnAuthRefresh    OnAuthRefreshFunc
	MaxRetries       *int

	// ModelProvider, when non-nil, is called on each retry attempt to
	// obtain the language model. This allows callers to swap in a
	// refreshed model after OnAuthRefresh rebuilds credentials. When
	// nil, the model captured at step preparation time is used.
	ModelProvider func() LanguageModel

	StopWhen       []StopCondition
	PrepareStep    PrepareStepFunction
	RepairToolCall RepairToolCallFunction

	// Agent-level callbacks
	OnAgentStart  OnAgentStartFunc  // Called when agent starts
	OnAgentFinish OnAgentFinishFunc // Called when agent finishes
	OnStepStart   OnStepStartFunc   // Called when a step starts
	OnStepFinish  OnStepFinishFunc  // Called when a step finishes
	OnFinish      OnFinishFunc      // Called when entire agent completes
	OnError       OnErrorFunc       // Called when an error occurs

	// Stream part callbacks - called for each corresponding stream part type
	OnChunk          OnChunkFunc          // Called for each stream part (catch-all)
	OnWarnings       OnWarningsFunc       // Called for warnings
	OnTextStart      OnTextStartFunc      // Called when text starts
	OnTextDelta      OnTextDeltaFunc      // Called for text deltas
	OnTextEnd        OnTextEndFunc        // Called when text ends
	OnReasoningStart OnReasoningStartFunc // Called when reasoning starts
	OnReasoningDelta OnReasoningDeltaFunc // Called for reasoning deltas
	OnReasoningEnd   OnReasoningEndFunc   // Called when reasoning ends
	OnToolInputStart OnToolInputStartFunc // Called when tool input starts
	OnToolInputDelta OnToolInputDeltaFunc // Called for tool input deltas
	OnToolInputEnd   OnToolInputEndFunc   // Called when tool input ends
	OnToolCall       OnToolCallFunc       // Called when tool call is complete
	OnToolResult     OnToolResultFunc     // Called when tool execution completes
	OnSource         OnSourceFunc         // Called for source references
	OnStreamFinish   OnStreamFinishFunc   // Called when stream finishes
}

type AgentTool interface {
	Info() ToolInfo
	Run(ctx context.Context, params ToolCall) (ToolResponse, error)
	ProviderOptions() ProviderOptions
	SetProviderOptions(opts ProviderOptions)
}

type Call struct {
	Prompt           Prompt      `json:"prompt"`
	MaxOutputTokens  *int64      `json:"max_output_tokens"`
	Temperature      *float64    `json:"temperature"`
	TopP             *float64    `json:"top_p"`
	TopK             *int64      `json:"top_k"`
	PresencePenalty  *float64    `json:"presence_penalty"`
	FrequencyPenalty *float64    `json:"frequency_penalty"`
	Tools            []Tool      `json:"tools"`
	ToolChoice       *ToolChoice `json:"tool_choice"`

	// UserAgent overrides the provider-level User-Agent header for this call.
	UserAgent string `json:"-"`

	// Headers overrides matching provider-level headers for this call.
	Headers map[string]string `json:"-"`

	// for provider specific options, the key is the provider id
	ProviderOptions ProviderOptions `json:"provider_options"`
}

type CallWarning struct {
	Type    CallWarningType `json:"type"`
	Setting string          `json:"setting"`
	Tool    Tool            `json:"tool"`
	Details string          `json:"details"`
	Message string          `json:"message"`
}

type CallWarningType string

type Content interface {
	GetType() ContentType
}

type ContentType string

type Error struct {
	Message string
	Title   string
	Cause   error
}

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

type FileContent struct {
	// The IANA media type of the file, e.g. `image/png` or `audio/mp3`.
	// @see https://www.iana.org/assignments/media-types/media-types.xhtml
	MediaType string `json:"media_type"`
	// Generated file data as binary data.
	Data             []byte           `json:"data"`
	ProviderMetadata ProviderMetadata `json:"provider_metadata"`
}

type FilePart struct {
	Filename        string          `json:"filename"`
	Data            []byte          `json:"data"`
	MediaType       string          `json:"media_type"`
	ProviderOptions ProviderOptions `json:"provider_options"`
}

type FinishReason string

type FunctionTool struct {
	// Name of the tool. Unique within this model call.
	Name string `json:"name"`
	// Description of the tool. The language model uses this to understand the
	// tool's purpose and to provide better completion suggestions.
	Description string `json:"description"`
	// InputSchema - the parameters that the tool expects. The language model uses this to
	// understand the tool's input requirements and to provide matching suggestions.
	InputSchema map[string]any `json:"input_schema"` // JSON Schema
	// ProviderOptions are provider-specific options for the tool.
	ProviderOptions ProviderOptions `json:"provider_options"`
}

type LanguageModel interface {
	Generate(context.Context, Call) (*Response, error)
	Stream(context.Context, Call) (StreamResponse, error)

	GenerateObject(context.Context, ObjectCall) (*ObjectResponse, error)
	StreamObject(context.Context, ObjectCall) (ObjectStreamResponse, error)

	Provider() string
	Model() string
}

type Message struct {
	Role            MessageRole     `json:"role"`
	Content         []MessagePart   `json:"content"`
	ProviderOptions ProviderOptions `json:"provider_options"`
}

type MessagePart interface {
	GetType() ContentType
	Options() ProviderOptions
}

type MessageRole string

type NoObjectGeneratedError struct {
	RawText         string
	ParseError      error
	ValidationError error
	Usage           Usage
	FinishReason    FinishReason
}

type ObjectCall struct {
	Prompt            Prompt
	Schema            Schema
	SchemaName        string
	SchemaDescription string

	MaxOutputTokens  *int64
	Temperature      *float64
	TopP             *float64
	TopK             *int64
	PresencePenalty  *float64
	FrequencyPenalty *float64

	// UserAgent overrides the provider-level User-Agent header for this call.
	UserAgent string `json:"-"`

	// Headers overrides matching provider-level headers for this call.
	Headers map[string]string `json:"-"`

	ProviderOptions ProviderOptions

	RepairText schema.ObjectRepairFunc
}

type ObjectMode string

type ObjectResponse struct {
	Object           any
	RawText          string
	Usage            Usage
	FinishReason     FinishReason
	Warnings         []CallWarning
	ProviderMetadata ProviderMetadata
}

type ObjectResult[T any] struct {
	Object           T
	RawText          string
	Usage            Usage
	FinishReason     FinishReason
	Warnings         []CallWarning
	ProviderMetadata ProviderMetadata
}

type ObjectStreamPart struct {
	Type             ObjectStreamPartType
	Object           any
	Delta            string
	Error            error
	Usage            Usage
	FinishReason     FinishReason
	Warnings         []CallWarning
	ProviderMetadata ProviderMetadata
}

type ObjectStreamPartType string

type ObjectStreamResponse = iter.Seq[ObjectStreamPart]

type OnAgentFinishFunc func(result *AgentResult) error

type OnAgentStartFunc func()

type OnAuthRefreshFunc func(ctx context.Context, err *ProviderError) error

type OnChunkFunc func(StreamPart) error

type OnErrorFunc func(error)

type OnFinishFunc func(result *AgentResult)

type OnReasoningDeltaFunc func(id, text string) error

type OnReasoningEndFunc func(id string, reasoning ReasoningContent) error

type OnReasoningStartFunc func(id string, reasoning ReasoningContent) error

type OnRetryCallback = func(err *ProviderError, delay time.Duration)

type OnSourceFunc func(source SourceContent) error

type OnStepFinishFunc func(stepResult StepResult) error

type OnStepFinishedFunction = func(step StepResult)

type OnStepStartFunc func(stepNumber int) error

type OnStreamFinishFunc func(usage Usage, finishReason FinishReason, providerMetadata ProviderMetadata) error

type OnTextDeltaFunc func(id, text string) error

type OnTextEndFunc func(id string) error

type OnTextStartFunc func(id string) error

type OnToolCallFunc func(toolCall ToolCallContent) error

type OnToolInputDeltaFunc func(id, delta string) error

type OnToolInputEndFunc func(id string) error

type OnToolInputStartFunc func(id, toolName string) error

type OnToolResultFunc func(result ToolResultContent) error

type OnWarningsFunc func(warnings []CallWarning) error

type PrepareStepFunction = func(ctx context.Context, options PrepareStepFunctionOptions) (context.Context, PrepareStepResult, error)

type PrepareStepFunctionOptions struct {
	Steps      []StepResult
	StepNumber int
	Model      LanguageModel
	Messages   []Message
}

type PrepareStepResult struct {
	Model           LanguageModel
	Messages        []Message
	System          *string
	ToolChoice      *ToolChoice
	ActiveTools     []string
	DisableAllTools bool
	Tools           []AgentTool
}

type Prompt []Message

type Provider interface {
	Name() string
	LanguageModel(ctx context.Context, modelID string) (LanguageModel, error)
}

type ProviderDefinedTool struct {
	// ID of the tool. Should follow the format `<provider-name>.<unique-tool-name>`.
	ID string `json:"id"`
	// Name of the tool that the user must use in the tool set.
	Name string `json:"name"`
	// Args for configuring the tool. Must match the expected arguments defined by the provider for this tool.
	Args map[string]any `json:"args"`
}

type ProviderError struct {
	Message string
	Title   string
	Cause   error

	URL             string
	StatusCode      int
	RequestBody     []byte
	ResponseHeaders map[string]string
	ResponseBody    []byte

	ContextUsedTokens  int
	ContextMaxTokens   int
	ContextTooLargeErr bool

	// AuthError marks the error as an authentication failure a provider
	// flagged as resolvable by refreshing credentials (e.g. re-running an
	// interactive login). It covers auth failures that do not carry an HTTP
	// 401 status, so a caller-supplied OnAuthRefresh hook still engages.
	AuthError bool
}

type ProviderMetadata map[string]ProviderOptionsData

type ProviderOptions map[string]ProviderOptionsData

type ProviderOptionsData interface {
	// Options is a marker method that identifies types implementing this interface.
	Options()
	json.Marshaler
	json.Unmarshaler
}

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

type ReasoningContent struct {
	Text             string           `json:"text"`
	ProviderMetadata ProviderMetadata `json:"provider_metadata"`
}

type ReasoningPart struct {
	Text            string          `json:"text"`
	ProviderOptions ProviderOptions `json:"provider_options"`
}

type RepairToolCallFunction = func(ctx context.Context, options ToolCallRepairOptions) (*ToolCallContent, error)

type Response struct {
	Content      ResponseContent `json:"content"`
	FinishReason FinishReason    `json:"finish_reason"`
	Usage        Usage           `json:"usage"`
	Warnings     []CallWarning   `json:"warnings"`

	// for provider specific response metadata, the key is the provider id
	ProviderMetadata ProviderMetadata `json:"provider_metadata"`
}

type ResponseContent []Content

type RetryError struct {
	Errors []error
}

type RetryFn[T any] func() (T, error)

type RetryFunction[T any] func(ctx context.Context, fn RetryFn[T]) (T, error)

type RetryOptions struct {
	MaxRetries     int
	InitialDelayIn time.Duration
	BackoffFactor  float64
	OnRetry        OnRetryCallback

	// OnAuthRefresh is called when an operation fails with an authentication
	// error the caller may be able to resolve (e.g. an expired SSO session).
	// If it returns nil, the entire retry pass restarts with a fresh retry
	// budget; if it returns an error, the original auth error is returned
	// without retry. At most one refresh is attempted, since auth refresh is
	// a one-shot human-in-the-loop step and a second attempt would not fare
	// better.
	OnAuthRefresh OnAuthRefreshFunc
}

type Schema = schema.Schema

type SourceContent struct {
	SourceType       SourceType       `json:"source_type"` // "url" or "document"
	ID               string           `json:"id"`
	URL              string           `json:"url"` // for URL sources
	Title            string           `json:"title"`
	MediaType        string           `json:"media_type"` // for document sources (IANA media type)
	Filename         string           `json:"filename"`   // for document sources
	ProviderMetadata ProviderMetadata `json:"provider_metadata"`
}

type SourceType string

type StepResult struct {
	Response
	Messages []Message
}

type StopCondition = func(steps []StepResult) bool

type StreamObjectResult[T any] struct {
	// contains filtered or unexported fields
}

type StreamPart struct {
	Type             StreamPartType `json:"type"`
	ID               string         `json:"id"`
	ToolCallName     string         `json:"tool_call_name"`
	ToolCallInput    string         `json:"tool_call_input"`
	Delta            string         `json:"delta"`
	ProviderExecuted bool           `json:"provider_executed"`
	Usage            Usage          `json:"usage"`
	FinishReason     FinishReason   `json:"finish_reason"`
	Error            error          `json:"error"`
	Warnings         []CallWarning  `json:"warnings"`

	// Source-related fields
	SourceType SourceType `json:"source_type"`
	URL        string     `json:"url"`
	Title      string     `json:"title"`

	ProviderMetadata ProviderMetadata `json:"provider_metadata"`
}

type StreamPartType string

type StreamResponse = iter.Seq[StreamPart]

type TextContent struct {
	// The text content.
	Text             string           `json:"text"`
	ProviderMetadata ProviderMetadata `json:"provider_metadata"`
}

type TextPart struct {
	Text            string          `json:"text"`
	ProviderOptions ProviderOptions `json:"provider_options"`
}

type Tool interface {
	GetType() ToolType
	GetName() string
}

type ToolCall struct {
	ID    string `json:"id"`
	Name  string `json:"name"`
	Input string `json:"input"`
}

type ToolCallContent struct {
	ToolCallID string `json:"tool_call_id"`
	ToolName   string `json:"tool_name"`
	// Stringified JSON object with the tool call arguments.
	// Must match the parameters schema of the tool.
	Input string `json:"input"`
	// Whether the tool call will be executed by the provider.
	// If this flag is not set or is false, the tool call will be executed by the client.
	ProviderExecuted bool `json:"provider_executed"`
	// Additional provider-specific metadata for the tool call.
	ProviderMetadata ProviderMetadata `json:"provider_metadata"`
	// Whether this tool call is invalid (failed validation/parsing)
	Invalid bool `json:"invalid,omitempty"`
	// Error that occurred during validation/parsing (only set if Invalid is true)
	ValidationError error `json:"validation_error,omitempty"`
}

type ToolCallPart struct {
	ToolCallID       string          `json:"tool_call_id"`
	ToolName         string          `json:"tool_name"`
	Input            string          `json:"input"` // the json string
	ProviderExecuted bool            `json:"provider_executed"`
	ProviderOptions  ProviderOptions `json:"provider_options"`
}

type ToolCallRepairOptions struct {
	OriginalToolCall ToolCallContent
	ValidationError  error
	AvailableTools   []AgentTool
	SystemPrompt     string
	Messages         []Message
}

type ToolChoice string

type ToolInfo struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Parameters  map[string]any `json:"parameters"`
	Required    []string       `json:"required"`
	Parallel    bool           `json:"parallel"` // Whether this tool can run in parallel with other tools
}

type ToolResponse struct {
	Type    string `json:"type"`
	Content string `json:"content"`
	// Data contains binary data for image/media responses (e.g., image bytes, audio data).
	Data []byte `json:"data,omitempty"`
	// MediaType specifies the MIME type of the media (e.g., "image/png", "audio/wav").
	MediaType string `json:"media_type,omitempty"`
	Metadata  string `json:"metadata,omitempty"`
	IsError   bool   `json:"is_error"`
	StopTurn  bool   `json:"stop_turn,omitempty"`
}

type ToolResultContent struct {
	// The ID of the tool call that this result is associated with.
	ToolCallID string `json:"tool_call_id"`
	// Name of the tool that generated this result.
	ToolName string `json:"tool_name"`
	// Result of the tool call. This is a JSON-serializable object.
	Result         ToolResultOutputContent `json:"result"`
	ClientMetadata string                  `json:"client_metadata"` // Metadata from the client that executed the tool
	// Whether the tool result was generated by the provider.
	// If this flag is set to true, the tool result was generated by the provider.
	// If this flag is not set or is false, the tool result was generated by the client.
	ProviderExecuted bool `json:"provider_executed"`
	// Additional provider-specific metadata for the tool result.
	ProviderMetadata ProviderMetadata `json:"provider_metadata"`
	// StopTurn indicates that the agent loop should stop after this result.
	// The tool result is still delivered to the model's context, but the model
	// does not get another chance to make tool calls in the same turn.
	StopTurn bool `json:"stop_turn,omitempty"`
}

type ToolResultContentType string

type ToolResultOutputContent interface {
	GetType() ToolResultContentType
}

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

type ToolResultOutputContentMedia struct {
	Data      string `json:"data"`           // for media type (base64)
	MediaType string `json:"media_type"`     // for media type
	Text      string `json:"text,omitempty"` // optional text content accompanying the media
}

type ToolResultOutputContentText struct {
	Text string `json:"text"`
}

type ToolResultPart struct {
	ToolCallID       string                  `json:"tool_call_id"`
	Output           ToolResultOutputContent `json:"output"`
	ProviderExecuted bool                    `json:"provider_executed"`
	ProviderOptions  ProviderOptions         `json:"provider_options"`
}

type ToolType string

type UnmarshalFunc func([]byte) (ProviderOptionsData, error)

type Usage struct {
	InputTokens         int64 `json:"input_tokens"`
	OutputTokens        int64 `json:"output_tokens"`
	TotalTokens         int64 `json:"total_tokens"`
	ReasoningTokens     int64 `json:"reasoning_tokens"`
	CacheCreationTokens int64 `json:"cache_creation_tokens"`
	CacheReadTokens     int64 `json:"cache_read_tokens"`
}