llmproxy

type ChatRequest struct {
	// Model is the model name.
	Model ModelID `json:"model"`

	// Input is the runtime input to the model. Can be a simple prompt in form of an InputString or a list of InputItem.
	Input Input `json:"input"`

	// SystemPrompt overrides the model's default system message/prompt.
	// Needs to be re-supplied for each request, even if PreviousResponseID is used.
	SystemPrompt string `json:"systemPrompt,omitempty"`

	// PreviousResponseID is the ID of a previous response that will be passed as context
	// to the next response, allowing for multi-turn conversations.
	// This does not store full conversation history.
	PreviousResponseID string `json:"previousResponseID,omitempty"`

	// ResponseFormat specifies a structured JSON response format.
	// If provided, the model is forced to respond in the specified format if supported by the model.
	ResponseFormat *ResponseFormat `json:"responseFormat,omitempty"`

	// Tools is an optional list of tools to be made available to the model/agent
	Tools []Tool `json:"tools,omitempty"`

	// FileIDs is an optional list of uploaded file IDs accompanying this
	// request, for models that can use files as context.
	FileIDs []FileID `json:"fileIDs,omitempty"`

	// ImageIDs is an optional list of image file IDs accompanying this
	// request, for multimodal models.
	ImageIDs []FileID `json:"imageIDs,omitempty"`

	// ImageURLs is an optional list of image URLs accompanying this
	// request, for multimodal models that can fetch images from URLs.
	ImageURLs []string `json:"imageURLs,omitempty"`

	// Options lists model-specific options. For example, temperature can be
	// set through this field, if the model supports it.
	Options *Options `json:"options,omitempty"`
}

type ChatResponse struct {
	// Text is the generated response text.
	Text string `json:"text,omitempty"`

	// Citations are source references attached to spans of the assistant text.
	// Populated when the model grounds its output; empty otherwise.
	Citations []Citation `json:"citations,omitempty"`

	// ToolCallRequests are requests made by the model to call function tools as next action.
	ToolCallRequests []ToolCallRequest `json:"toolCallRequests,omitempty"`

	// ResponseID is the unique ID of this response.
	ResponseID string

	// InputTokens is the number of input/prompt tokens consumed.
	InputTokens int

	// OutputTokens is the number of output/completion tokens consumed.
	OutputTokens int

	// TokensUsed indicates the total number of tokens used in this response. This may be more than the sum of
	// InputTokens and OutputTokens for some providers.
	TokensUsed int
}

type Citation struct {
	// URL is the cited source.
	URL string `json:"url"`

	// Title is the source's title (optional).
	Title string `json:"title,omitempty"`

	// Snippet is the cited text excerpt from the source (optional).
	Snippet string `json:"snippet,omitempty"`

	// StartIdx is the start offset into the assistant message text (optional).
	StartIdx int `json:"startIdx,omitempty"`

	// EndIdx is the end offset into the assistant message text (optional).
	EndIdx int `json:"endIdx,omitempty"`
}

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

type ContentType string

type Embedder interface {
	ProviderID() ProviderID
	Embed(ctx context.Context, req *EmbeddingRequest) (*EmbeddingResponse, error)
	EmbeddingDimension(model ModelID) (int, error)
}

type EmbeddingRequest struct {
	// Model is the embedding model to use.
	Model ModelID

	// Inputs is the list of text strings to embed.
	Inputs []string
}

type EmbeddingResponse struct {
	// Embeddings contains the embedding vectors, one per input.
	Embeddings [][]float32

	// Model is the model that was used to generate the embeddings.
	Model string

	// TokensUsed is the total number of tokens consumed.
	TokensUsed int

	// InputTokens is the number of input/prompt tokens consumed.
	InputTokens int

	// OutputTokens is the number of output/completion tokens consumed.
	OutputTokens int
}

type ExternalTool interface {
	Tool
	ToolDescription() string
	ToolParams() map[string]any
}

type ExternalToolBase struct {
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Parameters  map[string]any `json:"parameters"`
}

type FileDeleteRequest struct {
	// FileID is the unique identifier of the file to be deleted.
	FileID FileID `json:"fileID"`

	// ProviderID specifies the target LLM provider from which to delete the file.
	ProviderID ProviderID `json:"providerID"`
}

type FileID string

type FileUploadRequest struct {
	// File is the file content as an io.ReadCloser.
	File io.ReadCloser `json:"file"`

	// FileName is the name of the file, including its extension.
	FileName string `json:"fileName"`

	// FileType is the MIME type of the file (e.g., "application/pdf", "image/png", "text/plain").
	FileType ContentType `json:"fileType"`

	// Purpose is an optional description of the file's intended use.
	Purpose string `json:"purpose,omitempty"`

	// ProviderID specifies the target LLM provider for the file upload.
	ProviderID ProviderID `json:"providerID"`
}

type FileUploadResponse struct {
	FileID   FileID
	FileName string
}

type FunctionTool struct {
	ExternalToolBase

	// ToolCall calls the tool function with given context and parameters.
	ToolCall func(ctx context.Context, arguments json.RawMessage) (any, error) `json:"-"`
}

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

type InputItem interface {
	// String returns a human-readable representation of the item, including its type.
	// This is used to serialize the item as plain text if the model only supports a single message type.
	String() string
	// contains filtered or unexported methods
}

type InputItems []InputItem

type InputString string

type ModelCapability string

type ModelID string

type ModelInfo struct {
	ID                 ModelID
	Provider           ProviderID
	Label              string
	Capabilities       []ModelCapability
	TokenModifier      float64 // TokenModifier scales token counts for billing (1.0 = pass-through).
	MaxTokens          *int    // MaxTokens is the model's output token cap (chat models).
	EmbeddingDimension *int    // EmbeddingDimension is the output vector size (on embedding models).
}

type NoArgs struct{}

type Option func(*Options)

type Options struct {
	// MaxTokens specifies the maximum number of tokens to generate in the response.
	// If nil, the model defaults to its internal maximum generation length.
	MaxTokens *int `json:"maxTokens,omitempty"`

	// Temperature controls randomness in generation.
	// Higher values (e.g., 1.0) make output more random, lower values (e.g., 0.0) make it deterministic.
	Temperature *float32 `json:"temperature,omitempty"`

	// TopK specifies the maximum number of tokens to consider during sampling.
	TopK *int `json:"topK,omitempty"`

	// TopP (nucleus sampling) controls the cumulative probability cutoff for token selection.
	// Only tokens whose cumulative probability <= TopP are considered at each step.
	TopP *float32 `json:"topP,omitempty"`

	// FrequencyPenalty reduces the likelihood of repeating tokens that have already appeared.
	// Higher values make the model less likely to repeat the same text.
	FrequencyPenalty *float32 `json:"frequencyPenalty,omitempty"`

	// PresencePenalty penalizes tokens that have already appeared in the text.
	// This encourages introducing new concepts instead of repeating old ones.
	PresencePenalty *float32 `json:"presencePenalty,omitempty"`

	// Seed sets the random seed for deterministic generation.
	// Useful for reproducibility. Nil uses a random seed.
	Seed *int `json:"seed,omitempty"`
}

type Provider interface {
	// ProviderID returns the unique identifier of the LLM provider.
	ProviderID() ProviderID

	// AvailableModels returns a list of supported models by the LLM service.
	AvailableModels() []ModelInfo

	// Health verifies that the LLM service is available and responding.
	// Returns an error if the service is unreachable or unhealthy.
	Health(ctx context.Context) error

	// Chat sends a text prompt (optionally with system instructions, ID of previous response,
	// files, images, and model options) to the LLM and returns the generated response.
	// The request may include structured instructions, multimodal input, and output formatting.
	Chat(ctx context.Context, req *ChatRequest) (*ChatResponse, error)

	// UploadFile uploads a file (text, PDF, image, etc.) to the LLM service.
	// Returns a FileUploadResponse containing the FileID that can be referenced in future requests.
	// Implementations may store the file temporarily or persist it depending on service capabilities.
	UploadFile(ctx context.Context, fileReq *FileUploadRequest) (*FileUploadResponse, error)

	// DeleteFile removes a previously uploaded file from the LLM service using its FileID.
	// After deletion, the file can no longer be referenced in new requests.
	DeleteFile(ctx context.Context, fileID FileID) (bool, error)
}

type ProviderID string

type ProviderInfo struct {
	ID     ProviderID
	Models []ModelInfo
}

type ResponseFormat struct {
	Name        string         `json:"name"`
	Schema      map[string]any `json:"schema"`
	Description string         `json:"description,omitempty"`
}

type Tool interface {
	// ToolName returns the name of the tool.
	ToolName() string
	// contains filtered or unexported methods
}

type ToolCallRequest struct {
	// The unique ID of the function tool call request generated by the model.
	CallID string `json:"callId"`

	// Name of the external tool called.
	Name string `json:"name"`

	// Arguments that should be passed to the external tool.
	Arguments json.RawMessage `json:"arguments"`
}

type ToolResult struct {
	// The unique ID of the function tool call request generated by the model.
	CallID string `json:"callId"`

	// Name of the external tool called.
	Name string `json:"name"`

	// Output of the external tool.
	Output any `json:"output"`
}

type WebSearch struct{}