// Package llm abstrae el acceso al modelo de lenguaje.
//
// El resto del programa depende solo de la interfaz Client y de estos tipos,
// no del proveedor concreto. La implementación incluida habla el dialecto
// OpenAI (POST /chat/completions), que también implementan llama.cpp, vLLM,
// Ollama, LM Studio y muchos otros servidores.
package llm

import "context"

// Roles de mensaje del protocolo de chat.
const (
	RoleSystem    = "system"
	RoleUser      = "user"
	RoleAssistant = "assistant"
	RoleTool      = "tool"
)

// Message es un mensaje de la conversación.
type Message struct {
	Role       string     `json:"role"`
	Content    string     `json:"content"`
	Name       string     `json:"name,omitempty"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`
}

// ToolCall es una invocación de herramienta propuesta por el modelo.
// Los argumentos llegan como texto JSON sin validar: el registro de
// herramientas los decodifica estrictamente antes de ejecutar nada.
type ToolCall struct {
	ID       string       `json:"id"`
	Type     string       `json:"type"`
	Function FunctionCall `json:"function"`
}

// FunctionCall contiene el nombre y los argumentos JSON (sin validar).
type FunctionCall struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

// Tool describe una herramienta ofrecida al modelo.
type Tool struct {
	Type     string       `json:"type"`
	Function ToolFunction `json:"function"`
}

// ToolFunction es el esquema de una herramienta (JSON Schema en Parameters).
type ToolFunction struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Parameters  any    `json:"parameters,omitempty"`
}

// ChatRequest es una petición independiente del proveedor.
type ChatRequest struct {
	Messages    []Message
	Tools       []Tool
	MaxTokens   int      // 0: el servidor decide
	Temperature *float64 // nil: el servidor decide
}

// Usage es el consumo de tokens reportado por el servidor.
// Todos los campos son 0 si el servidor no lo reporta.
type Usage struct {
	PromptTokens     int
	CompletionTokens int
	TotalTokens      int
}

// ChatResponse es la respuesta del modelo.
type ChatResponse struct {
	Message      Message
	Reasoning    string // razonamiento separado, si el servidor lo expone
	FinishReason string
	Usage        Usage
}

// Client es la interfaz que usa la lógica del agente.
type Client interface {
	Chat(ctx context.Context, req ChatRequest) (ChatResponse, error)
}

// ModelInfo es la información que se pudo obtener del servidor sobre el modelo.
// ContextSize == 0 significa UNKNOWN.
type ModelInfo struct {
	ID          string
	ContextSize int
	Source      string // de dónde se obtuvo ContextSize, para mostrarlo con honestidad
}