// Package textgen provides a unified interface for text generation
// across multiple LLM providers with fallback and routing capabilities.
package textgen

import (
	"context"
	"time"
)

// Provider defines common methods for all text generation providers.
// Implementations must be safe for concurrent use.
type Provider interface {
	// Name returns the provider name for logging and metrics.
	Name() string

	// Health checks if the provider is reachable and operational.
	Health(ctx context.Context) error
}

// TextGenerator defines the interface for text generation providers.
// Implementations must be safe for concurrent use.
type TextGenerator interface {
	Provider

	// GenerateText generates text content from a prompt.
	GenerateText(ctx context.Context, req TextRequest) (*TextResponse, error)
}

// TextRequest represents a unified text generation request.
type TextRequest struct {
	Prompt      string        // Required: the prompt to generate from
	Model       string        // Optional: model override (provider-specific)
	MaxTokens   int           // Optional: maximum tokens to generate
	Temperature float64       // Optional: sampling temperature (0.0-2.0)
	Timeout     time.Duration // Optional: request timeout

	// System prompt for chat-style models
	SystemPrompt string // Optional: system/instruction prompt

	// Messages for multi-turn conversation (alternative to Prompt)
	Messages []Message // Optional: conversation history
}

// Message represents a single message in a conversation.
type Message struct {
	Role    string // "system", "user", or "assistant"
	Content string // Message content
}

// TextResponse represents a unified text generation response.
type TextResponse struct {
	Text     string        // Generated text content
	Provider string        // Name of provider that generated this response
	Latency  time.Duration // Time taken to generate
	Usage    *Usage        // Token usage statistics (if available)
}

// Usage represents token usage statistics.
type Usage struct {
	PromptTokens     int // Tokens in the prompt
	CompletionTokens int // Tokens in the completion
	TotalTokens      int // Total tokens used
}

// StreamChunk represents a single chunk from streaming text generation.
type StreamChunk struct {
	// Text is the chunk content.
	Text string
	// Done indicates this is the final chunk.
	Done bool
	// Provider name (only set on final chunk).
	Provider string
}

// TextStreamer extends TextGenerator with streaming support.
// Implementations deliver chunks via the onChunk callback as tokens arrive.
type TextStreamer interface {
	TextGenerator

	// GenerateStream generates text with streaming delivery.
	// onChunk is called for each token/chunk as it arrives.
	// The final call has Done=true and Provider set.
	GenerateStream(ctx context.Context, req TextRequest, onChunk func(StreamChunk)) error
}