post inicial

internal/llm/types.go

@@ -0,0 +1,91 @@
+// 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
+}