interfaces

type APIHandler interface {
	// HandlerType returns the type identifier for this API handler.
	// This is used to determine which request/response translators to use.
	HandlerType() string

	// Models returns a list of supported models for this API handler.
	// Each model is represented as a map containing model metadata.
	Models() []map[string]any
}

type Client interface {
	// Type returns the client type identifier (e.g., "gemini", "claude").
	Type() string

	// GetRequestMutex returns the mutex used to synchronize requests for this client.
	// This ensures that only one request is processed at a time for quota management.
	GetRequestMutex() *sync.Mutex

	// GetUserAgent returns the User-Agent string used for HTTP requests.
	GetUserAgent() string

	// SendRawMessage sends a raw JSON message to the AI service without translation.
	// This method is used when the request is already in the service's native format.
	SendRawMessage(ctx context.Context, modelName string, rawJSON []byte, alt string) ([]byte, *ErrorMessage)

	// SendRawMessageStream sends a raw JSON message and returns streaming responses.
	// Similar to SendRawMessage but for streaming responses.
	SendRawMessageStream(ctx context.Context, modelName string, rawJSON []byte, alt string) (<-chan []byte, <-chan *ErrorMessage)

	// SendRawTokenCount sends a token count request to the AI service.
	// This method is used to estimate the number of tokens in a given text.
	SendRawTokenCount(ctx context.Context, modelName string, rawJSON []byte, alt string) ([]byte, *ErrorMessage)

	// SaveTokenToFile saves the client's authentication token to a file.
	// This is used for persisting authentication state between sessions.
	SaveTokenToFile() error

	// IsModelQuotaExceeded checks if the specified model has exceeded its quota.
	// This helps with load balancing and automatic failover to alternative models.
	IsModelQuotaExceeded(model string) bool

	// GetEmail returns the email associated with the client's authentication.
	// This is used for logging and identification purposes.
	GetEmail() string

	// CanProvideModel checks if the client can provide the specified model.
	CanProvideModel(modelName string) bool

	// Provider returns the name of the AI service provider (e.g., "gemini", "claude").
	Provider() string

	// RefreshTokens refreshes the access tokens if needed
	RefreshTokens(ctx context.Context) error

	// IsAvailable returns true if the client is available for use.
	IsAvailable() bool

	// SetUnavailable sets the client to unavailable.
	SetUnavailable()
}

type Content struct {
	// Role indicates who sent the message ("user", "model", or "tool").
	Role string `json:"role"`

	// Parts is a collection of content parts that make up the message.
	Parts []Part `json:"parts"`
}

type ErrorMessage struct {
	// StatusCode is the HTTP status code returned by the API.
	StatusCode int

	// Error is the underlying error that occurred.
	Error error

	// Addon contains additional headers to be added to the response.
	Addon http.Header
}

type FunctionCall struct {
	// Name is the identifier of the function to be called.
	Name string `json:"name"`

	// Args contains the arguments to pass to the function.
	Args map[string]interface{} `json:"args"`
}

type FunctionResponse struct {
	// Name is the identifier of the function that was called.
	Name string `json:"name"`

	// Response contains the result data from the function execution.
	Response map[string]interface{} `json:"response"`
}

type GCPProject struct {
	// Projects is a list of Google Cloud projects accessible by the user.
	Projects []GCPProjectProjects `json:"projects"`
}

type GCPProjectLabels struct {
	// GenerativeLanguage indicates if the project has generative language APIs enabled.
	GenerativeLanguage string `json:"generative-language"`
}

type GCPProjectProjects struct {
	// ProjectNumber is the unique numeric identifier for the project.
	ProjectNumber string `json:"projectNumber"`

	// ProjectID is the unique string identifier for the project.
	ProjectID string `json:"projectId"`

	// LifecycleState indicates the current state of the project (e.g., "ACTIVE").
	LifecycleState string `json:"lifecycleState"`

	// Name is the human-readable name of the project.
	Name string `json:"name"`

	// Labels contains metadata labels associated with the project.
	Labels GCPProjectLabels `json:"labels"`

	// CreateTime is the timestamp when the project was created.
	CreateTime time.Time `json:"createTime"`
}

type GenerateContentRequest struct {
	// SystemInstruction provides system-level instructions that guide the model's behavior.
	SystemInstruction *Content `json:"systemInstruction,omitempty"`

	// Contents is the conversation history between the user and the model.
	Contents []Content `json:"contents"`

	// Tools defines the available tools/functions that the model can call.
	Tools []ToolDeclaration `json:"tools,omitempty"`

	// GenerationConfig contains parameters that control the model's generation behavior.
	GenerationConfig `json:"generationConfig"`
}

type GenerationConfig struct {
	// ThinkingConfig specifies configuration for the model's "thinking" process.
	ThinkingConfig GenerationConfigThinkingConfig `json:"thinkingConfig,omitempty"`

	// Temperature controls the randomness of the model's responses.
	// Values closer to 0 make responses more deterministic, while values closer to 1 increase randomness.
	Temperature float64 `json:"temperature,omitempty"`

	// TopP controls nucleus sampling, which affects the diversity of responses.
	// It limits the model to consider only the top P% of probability mass.
	TopP float64 `json:"topP,omitempty"`

	// TopK limits the model to consider only the top K most likely tokens.
	// This can help control the quality and diversity of generated text.
	TopK float64 `json:"topK,omitempty"`
}

type GenerationConfigThinkingConfig struct {
	// IncludeThoughts determines whether the model should output its reasoning process.
	// When enabled, the model will include its step-by-step thinking in the response.
	IncludeThoughts bool `json:"include_thoughts,omitempty"`
}

type InlineData struct {
	// MimeType specifies the media type of the embedded data (e.g., "image/png").
	MimeType string `json:"mime_type,omitempty"`

	// Data contains the base64-encoded binary data.
	Data string `json:"data,omitempty"`
}

type Part struct {
	// Text contains plain text content.
	Text string `json:"text,omitempty"`

	// InlineData contains base64-encoded data with its MIME type (e.g., images).
	InlineData *InlineData `json:"inlineData,omitempty"`

	// FunctionCall represents a tool call requested by the model.
	FunctionCall *FunctionCall `json:"functionCall,omitempty"`

	// FunctionResponse represents the result of a tool execution.
	FunctionResponse *FunctionResponse `json:"functionResponse,omitempty"`
}

type ToolDeclaration struct {
	// FunctionDeclarations is a list of available functions that the model can call.
	FunctionDeclarations []interface{} `json:"functionDeclarations"`
}

type TranslateRequestFunc func(string, []byte, bool) []byte

type TranslateResponse struct {
	// Stream handles streaming response translation.
	Stream TranslateResponseFunc

	// NonStream handles non-streaming response translation.
	NonStream TranslateResponseNonStreamFunc
}

type TranslateResponseFunc func(ctx context.Context, modelName string, originalRequestRawJSON, requestRawJSON, rawJSON []byte, param *any) []string

type TranslateResponseNonStreamFunc func(ctx context.Context, modelName string, originalRequestRawJSON, requestRawJSON, rawJSON []byte, param *any) string

type UnregisterReason string