ai

type ChatRequest struct {
	Model       string
	System      string
	Messages    []Message
	MaxTokens   int
	Temperature *float64
	JSON        bool   // ask for a single JSON object response
	Effort      string // optional reasoning effort hint (anthropic)
	User        string // end-user id for provider abuse monitoring (optional)

	// ResolveImage, when set, loads images the request references by a URL
	// of the calling site's own content (see ImageResolver). It is used by
	// the Service (router) before the request reaches a provider; providers
	// never see it and ignore it if set.
	ResolveImage ImageResolver
}

type ChatResponse struct {
	Content    string `json:"content"`
	Model      string `json:"model"` // provider model id (router replaces with alias)
	StopReason string `json:"stop_reason"`
	Usage      Usage  `json:"usage"`
}

type EmbedRequest struct {
	Model string
	Input []string
	User  string
}

type EmbedResponse struct {
	Embeddings [][]float64
	Usage      Usage
}

type Image struct {
	Data      []byte
	MediaType string
}

type ImageRequest struct {
	Model  string
	Prompt string
	Size   string // e.g. "1024x1024"; provider-specific values passed through
	N      int
	User   string
}

type ImageResolver func(ctx context.Context, ref string, maxBytes int64) ([]byte, error)

type ImageResponse struct {
	Images []Image
}

type Message struct {
	Role    string `json:"role"`
	Content []Part `json:"content"`
}

type ModelInfo struct {
	Name        string `json:"name"`
	Kind        string `json:"kind"` // chat | image | embedding
	Provider    string `json:"provider"`
	Model       string `json:"model,omitempty"` // only if ai.expose_model_ids
	Description string `json:"description,omitempty"`
}

type Part struct {
	Type      string `json:"type"`                 // "text" | "image"
	Text      string `json:"text,omitempty"`       // type=text
	Data      []byte `json:"-"`                    // type=image: raw bytes (decoded from base64 "data")
	MediaType string `json:"media_type,omitempty"` // type=image: image/png, image/jpeg, image/gif, image/webp
	URL       string `json:"url,omitempty"`        // type=image: remote image URL (providers may fetch or reject)
}

type Provider interface {
	// Name returns the configured provider key (e.g. "anthropic").
	Name() string
	// Chat performs a non-streaming completion.
	Chat(ctx context.Context, req ChatRequest) (*ChatResponse, error)
	// ChatStream streams text deltas to onDelta and returns the final response
	// (Content contains the full text). If onDelta returns an error the stream
	// is aborted and that error returned.
	ChatStream(ctx context.Context, req ChatRequest, onDelta func(text string) error) (*ChatResponse, error)
	// Image generates images or returns ErrUnsupported.
	Image(ctx context.Context, req ImageRequest) (*ImageResponse, error)
	// Embed computes embeddings or returns ErrUnsupported.
	Embed(ctx context.Context, req EmbedRequest) (*EmbedResponse, error)
}

type Service interface {
	// Chat resolves req.Model (an alias, "" = default, or "provider/model" if
	// raw models are allowed) and dispatches. The response's Model is the alias.
	Chat(ctx context.Context, alias string, req ChatRequest) (*ChatResponse, error)
	ChatStream(ctx context.Context, alias string, req ChatRequest, onDelta func(string) error) (*ChatResponse, error)
	Image(ctx context.Context, alias string, req ImageRequest) (*ImageResponse, string, error) // returns alias used
	Embed(ctx context.Context, alias string, req EmbedRequest) (*EmbedResponse, string, error)
	// Models lists configured aliases (sorted by name) and the default chat alias.
	Models() (defaultAlias string, models []ModelInfo)
	// Enabled reports whether any model is configured.
	Enabled() bool
}

type UpstreamError struct {
	Provider string
	Status   int // HTTP status from the provider, 0 if not applicable
	Message  string
	// RetryDelay is how long the provider asked callers to wait before
	// retrying (its Retry-After, retry-after-ms or rate-limit reset
	// headers, or Google's RetryInfo), 0 when it did not say.
	RetryDelay time.Duration
}

type Usage struct {
	InputTokens  int `json:"input_tokens"`
	OutputTokens int `json:"output_tokens"`
}