ai

type AI interface {
	// Agent creates a conversation bound to the resolved driver.
	Agent(agent Agent, options ...Option) (Conversation, error)
	// Audio creates a fluent audio generation request.
	Audio(prompt string) AudioRequest
	// Image creates a fluent image generation request.
	Image(prompt string) ImageRequest
	// Transcription creates a fluent speech-to-text request.
	Transcription(file StorableFile) TranscriptionRequest
	// WithContext returns a new AI instance that carries the provided context for all operations.
	WithContext(ctx context.Context) AI
}

type Agent interface {
	// Instructions returns the system instructions for the model.
	Instructions() string
	// Messages returns prior conversation messages to include as context.
	Messages() []Message
	// Middleware returns the default middleware applied to the agent conversation.
	// Return nil or an empty slice if no middleware is configured.
	Middleware() []Middleware
	// Tools returns the tools the model may invoke during the conversation.
	// Return nil or an empty slice if no tools are available.
	Tools() []Tool
}

type AgentPrompt struct {
	Agent       Agent
	Input       string
	Model       string
	Attachments []Attachment
	// Tools lists the tools available to the model for this request.
	Tools []Tool
	// ProviderState carries provider-scoped state for this conversation.
	ProviderState ProviderState
}

type AgentResponse interface {
	Text() string
	Usage() Usage
	// ToolCalls returns any tool invocations the model requested.
	// Returns nil or an empty slice when the model returns plain text.
	ToolCalls() []ToolCall
	// Then registers a callback against the resolved response.
	Then(callback func(AgentResponse)) AgentResponse
}

type Attachment interface {
	StorableFile
	Kind() AttachmentKind
	Put(ctx context.Context, options ...Option) (FileResponse, error)
}

type AttachmentKind string

type AttachmentOption func(options *AttachmentOptions)

type AttachmentOptions struct {
	MimeType string
	// Only used by FromStorage.
	Disk string
	// Title provides a display name for attachments created from
	// sources without a natural filename (e.g. fromString, fromByte).
	// Providers such as Anthropic require a non-empty document title.
	Title string
}

type AudioPrompt struct {
	Prompt       string
	Model        string
	Voice        string
	Instructions string
	Timeout      time.Duration
}

type AudioProvider interface {
	// Audio executes a text-to-speech request.
	Audio(ctx context.Context, prompt AudioPrompt) (AudioResponse, error)
}

type AudioRequest interface {
	Model(model string) AudioRequest
	Provider(provider string, failovers ...string) AudioRequest
	Voice(voice string) AudioRequest
	Male() AudioRequest
	Female() AudioRequest
	Instructions(instructions string) AudioRequest
	Timeout(timeout time.Duration) AudioRequest
	Store(disk ...string) (string, error)
	StoreAs(path string, disk ...string) (string, error)
	Generate() (AudioResponse, error)
}

type AudioResponse interface {
	Content() ([]byte, error)
	MimeType() string
	Store(disk ...string) (string, error)
	StoreAs(path string, disk ...string) (string, error)
	Usage() Usage
	Then(callback func(AudioResponse)) AudioResponse
}

type Config struct {
	Default   string                    `json:"default"`
	Providers map[string]ProviderConfig `json:"providers"`
}

type Conversation interface {
	// Prompt sends a non-streaming input and updates the conversation history.
	Prompt(input string, options ...ConversationOption) (AgentResponse, error)
	// Stream sends a streaming input and returns a streamable response object.
	Stream(input string, options ...ConversationOption) (StreamableAgentResponse, error)
	// Messages returns current conversation history.
	Messages() []Message
	// Reset clears runtime history and restores initial agent messages.
	Reset()
}

type ConversationOption func(options *ConversationOptions)

type ConversationOptions struct {
	Attachments []Attachment
}

type FailoverError interface {
	error
	Reason() FailoverReason
	Provider() string
	Unwrap() error
}

type FailoverReason string

type FileProvider interface {
	// PutFile uploads the given file and returns the provider-managed file handle.
	// Providers may return an ID-only handle with empty MimeType()/Content().
	PutFile(ctx context.Context, file StorableFile) (FileResponse, error)
	// GetFile resolves a previously stored provider-managed file.
	GetFile(ctx context.Context, id string) (FileResponse, error)
	// DeleteFile removes a previously stored provider-managed file.
	DeleteFile(ctx context.Context, id string) error
}

type FileResponse interface {
	ID() string
	MimeType() string
	Content(ctx context.Context) ([]byte, error)
}

type ImagePrompt struct {
	Prompt      string
	Model       string
	Size        ImageSize
	Quality     ImageQuality
	Attachments []Attachment
	Timeout     time.Duration
}

type ImageProvider interface {
	// Image executes an image generation or edit request.
	Image(ctx context.Context, prompt ImagePrompt) (ImageResponse, error)
}

type ImageQuality string

type ImageRequest interface {
	Model(model string) ImageRequest
	Provider(provider string, failovers ...string) ImageRequest
	Square() ImageRequest
	Portrait() ImageRequest
	Landscape() ImageRequest
	Quality(quality ImageQuality) ImageRequest
	Attachments(attachments ...Attachment) ImageRequest
	Timeout(timeout time.Duration) ImageRequest
	Store(disk ...string) (string, error)
	StoreAs(path string, disk ...string) (string, error)
	Generate() (ImageResponse, error)
}

type ImageResponse interface {
	Content() ([]byte, error)
	MimeType() string
	Store(disk ...string) (string, error)
	StoreAs(path string, disk ...string) (string, error)
	Usage() Usage
	Then(callback func(ImageResponse)) ImageResponse
}

type ImageSize string

type ImageStorer interface {
	Store(content []byte, name string, disk string) (string, error)
	StoreAs(content []byte, path string, disk string) (string, error)
}

type Message struct {
	Role    MessageRole
	Content string
	// ToolCallID is set on RoleToolResult messages to correlate a tool
	// result with the assistant ToolCall that requested it.
	ToolCallID string
	// ToolCalls is set on RoleAssistant messages when the model requests
	// one or more tool invocations instead of (or before) returning text.
	ToolCalls []ToolCall
}

type MessageRole string

type Middleware interface {
	Handle(ctx context.Context, prompt AgentPrompt, next Next) (AgentResponse, error)
}

type ModelsConfig struct {
	Text struct {
		Default   string `json:"default"`
		MaxTokens int    `json:"max_tokens"`
	} `json:"text"`
	Audio struct {
		Default string `json:"default"`
	} `json:"audio"`
	Transcription struct {
		Default string `json:"default"`
	} `json:"transcription"`
	Image struct {
		Default string `json:"default"`
	} `json:"image"`
}

type Next func(ctx context.Context, prompt AgentPrompt) (AgentResponse, error)

type Option func(options *Options)

type Options struct {
	// Providers is the ordered primary and failover provider list.
	Providers []string
	// Model overrides the selected provider's default model.
	Model string
	// Middlewares appends middleware for the current agent request.
	Middlewares []Middleware
}

type Provider interface {
	// Prompt executes a non-streaming model request.
	Prompt(ctx context.Context, prompt AgentPrompt) (AgentResponse, error)
	// Stream executes a streaming model request and returns a streamable response.
	Stream(ctx context.Context, prompt AgentPrompt) (StreamableAgentResponse, error)
}

type ProviderConfig struct {
	Key      string                      `json:"key"`
	Models   ModelsConfig                `json:"models"`
	Url      string                      `json:"url"`
	Via      any                         `json:"via"` // Provider or func() (Provider, error)
	Failover map[FailoverReason][]string `json:"failover"`
}

type ProviderFile interface {
	Attachment
	ID() string
	Get(ctx context.Context, options ...Option) (FileResponse, error)
	Delete(ctx context.Context, options ...Option) error
}

type ProviderState interface {
	Get(key string) any
	Set(key string, value any)
}

type RenderFunc func(w contractshttp.StreamWriter, event StreamEvent) error

type StorableFile interface {
	FileName() string
	MimeType() string
	Content(ctx context.Context) ([]byte, error)
}

type StreamEvent struct {
	Type      StreamEventType
	Delta     string
	Usage     Usage
	Error     string
	ToolCalls []ToolCall
}

type StreamEventType string

type StreamOption func(options *StreamOptions)

type StreamOptions struct {
	Code   int
	Render RenderFunc
}

type StreamableAgentResponse interface {
	Each(callback func(StreamEvent) error) error
	Then(callback func(AgentResponse)) StreamableAgentResponse
	HTTPResponse(ctx contractshttp.Context, options ...StreamOption) contractshttp.Response
}

type Tool interface {
	// Name returns the function name sent to the model. Must be unique per agent.
	Name() string
	// Description tells the model what the tool does and when to use it.
	Description() string
	// Parameters returns the JSON Schema object describing the tool's input.
	// Return nil if the tool takes no parameters.
	Parameters() map[string]any
	// Execute is called by the framework when the model invokes the tool.
	Execute(ctx context.Context, args map[string]any) (string, error)
}

type ToolCall struct {
	// ID is the model-generated unique identifier for this call.
	ID string
	// Name is the tool function name the model wants to invoke.
	Name string
	// Args contains the decoded JSON arguments for the call.
	Args map[string]any
	// RawArgs is the raw JSON string of the arguments as returned by the model.
	// It is used when replaying tool calls back to the API to preserve exact formatting.
	RawArgs string
}

type TranscriptionPrompt struct {
	File     StorableFile
	Model    string
	Language string
	Diarize  bool
	Timeout  time.Duration
}

type TranscriptionProvider interface {
	// Transcription executes a speech-to-text request.
	Transcription(ctx context.Context, prompt TranscriptionPrompt) (TranscriptionResponse, error)
}

type TranscriptionRequest interface {
	Model(model string) TranscriptionRequest
	Provider(provider string, failovers ...string) TranscriptionRequest
	Language(language string) TranscriptionRequest
	Diarize() TranscriptionRequest
	Timeout(timeout time.Duration) TranscriptionRequest
	Generate() (TranscriptionResponse, error)
}

type TranscriptionResponse interface {
	Text() string
	Segments() []TranscriptionSegment
	Usage() Usage
	Then(callback func(TranscriptionResponse)) TranscriptionResponse
}

type TranscriptionSegment struct {
	Speaker string
	Start   time.Duration
	End     time.Duration
	Text    string
}

type Usage interface {
	Input() int
	Output() int
	Total() int
}