@orxataguy/tyr 1.0.31 → 1.0.32

package/src/lib/AIVendorManager.ts

@@ -17,11 +17,15 @@ export type AIRole = 'system' | 'user' | 'assistant';
  *    formato (en Gemini, por ejemplo, es un id sintético generado por este manager, ya que la
  *    API de Gemini no da ids reales para las function calls).
  *  - 'tool_result': resultado de haber ejecutado una herramienta, para devolvérselo al modelo.
+ *  - 'image': imagen adjunta (p.ej. un attachment de chat). `data` es el contenido en base64 SIN
+ *    el prefijo `data:...;base64,`; `mediaType` es el MIME type (p.ej. 'image/png'). Solo válido
+ *    en mensajes de rol 'user' — los vendors no devuelven imágenes en sus respuestas.
  */
 export type AIContentBlock =
     | { type: 'text'; text: string }
     | { type: 'tool_use'; id: string; name: string; input: any }
-    | { type: 'tool_result'; tool_use_id: string; content: string; is_error?: boolean };
+    | { type: 'tool_result'; tool_use_id: string; content: string; is_error?: boolean }
+    | { type: 'image'; mediaType: string; data: string };
 
 export interface AIMessage {
     role: AIRole;
@@ -37,6 +41,24 @@ export interface AITool {
     input_schema: any;
 }
 
+/**
+ * Nivel de "esfuerzo de razonamiento" (extended thinking) pedido al modelo, independiente del
+ * vendor concreto. Se traduce a `thinking.budget_tokens` en Anthropic y a `reasoning_effort` en
+ * los modelos de OpenAI que lo soportan (serie 'o'); Gemini no tiene un equivalente público en
+ * este momento y el valor se ignora silenciosamente para ese vendor.
+ */
+export type ThinkingEffort = 'none' | 'low' | 'medium' | 'high' | 'max';
+
+/** Prioridad de una tarea, usada por resolvePriority()/completeWithPriority() para elegir modelo
+ *  y esfuerzo de razonamiento sin que el llamador tenga que conocer nombres de modelo concretos. */
+export type TaskPriority =
+    | 'baja-prioridad'
+    | 'baja-media-prioridad'
+    | 'media-prioridad'
+    | 'media-alta-prioridad'
+    | 'alta-prioridad'
+    | 'muy-alta-prioridad';
+
 export interface AICompletionOptions {
     vendor?: AIVendor;
     model?: string;
@@ -46,6 +68,9 @@ export interface AICompletionOptions {
     /** Herramientas disponibles para que el modelo las invoque. Solo soportado en complete(),
      *  no en stream() — ver el guard al inicio de stream(). */
     tools?: AITool[];
+    /** Nivel de extended thinking / reasoning effort. Ver ThinkingEffort. 'none' (o ausente)
+     *  desactiva el thinking explícitamente. */
+    thinking?: ThinkingEffort;
 }
 
 export interface AICompletionResult {
@@ -72,6 +97,7 @@ interface VendorConfig {
     temperature: number;
     maxTokens: number;
     maxRetries: number;
+    thinking: ThinkingEffort;
 }
 
 interface VendorRequest {
@@ -97,6 +123,58 @@ const DEFAULT_MAX_TOKENS = 4096;
 const DEFAULT_MAX_RETRIES = 3;
 const RETRY_BASE_DELAY_MS = 500;
 
+// --- Dynamic Model Routing ----------------------------------------------------------------------
+//
+// Three cost/capability tiers per vendor. Each is overridable via env var (AI_MODEL_CHEAP /
+// AI_MODEL_BALANCED / AI_MODEL_FLAGSHIP) so operators can point a tier at a newer model without
+// touching code. 'balanced' matches DEFAULT_MODELS on purpose — it's the vendor's normal default.
+type ModelTier = 'cheap' | 'balanced' | 'flagship';
+
+const MODEL_TIERS: Record<AIVendor, Record<ModelTier, string>> = {
+    anthropic: { cheap: 'claude-haiku-4-5', balanced: 'claude-sonnet-5', flagship: 'claude-opus-4-1' },
+    openai: { cheap: 'gpt-4o-mini', balanced: 'gpt-4o', flagship: 'gpt-4o' },
+    gemini: { cheap: 'gemini-2.5-flash', balanced: 'gemini-2.5-pro', flagship: 'gemini-2.5-pro' },
+};
+
+const MODEL_TIER_ENV: Record<ModelTier, string> = {
+    cheap: 'AI_MODEL_CHEAP',
+    balanced: 'AI_MODEL_BALANCED',
+    flagship: 'AI_MODEL_FLAGSHIP',
+};
+
+/** budget_tokens sent to Anthropic's `thinking` param per effort level. 'none' disables thinking. */
+const THINKING_BUDGETS: Record<ThinkingEffort, number> = {
+    none: 0,
+    low: 1024,
+    medium: 4096,
+    high: 8192,
+    max: 16384,
+};
+
+/**
+ * Task-priority → (model tier, thinking effort) matrix. This is the routing table requested by
+ * the architecture spec: callers pick a priority by *intent* ("this is a trivial file", "this
+ * previous attempt failed"), not by model name, and AIVendorManager decides what that costs.
+ */
+const PRIORITY_ROUTING: Record<TaskPriority, { tier: ModelTier; thinking: ThinkingEffort }> = {
+    'baja-prioridad': { tier: 'cheap', thinking: 'none' },
+    'baja-media-prioridad': { tier: 'cheap', thinking: 'max' },
+    'media-prioridad': { tier: 'balanced', thinking: 'none' },
+    'media-alta-prioridad': { tier: 'balanced', thinking: 'high' },
+    'alta-prioridad': { tier: 'balanced', thinking: 'max' },
+    'muy-alta-prioridad': { tier: 'flagship', thinking: 'max' },
+};
+
+/** Ordered priority ladder, used by bumpPriority() to escalate one level at a time. */
+const PRIORITY_LADDER: TaskPriority[] = [
+    'baja-prioridad',
+    'baja-media-prioridad',
+    'media-prioridad',
+    'media-alta-prioridad',
+    'alta-prioridad',
+    'muy-alta-prioridad',
+];
+
 /**
  * @class AIVendorManager
  * @description Unified client for AI chat-completion APIs (Anthropic, OpenAI, Gemini).
@@ -154,9 +232,79 @@ export class AIVendorManager {
             temperature: options?.temperature ?? getEnvDouble('AI_TEMPERATURE', DEFAULT_TEMPERATURE),
             maxTokens: options?.maxTokens ?? getEnvInt('AI_MAX_TOKENS', DEFAULT_MAX_TOKENS),
             maxRetries: options?.maxRetries ?? getEnvInt('AI_MAX_RETRIES', DEFAULT_MAX_RETRIES),
+            thinking: options?.thinking ?? 'none',
+        };
+    }
+
+    /**
+     * @method resolvePriority
+     * @description Translates a TaskPriority into concrete AICompletionOptions (model + thinking
+     * effort) for the currently configured vendor (or the vendor passed in `overrides`), via the
+     * routing matrix in PRIORITY_ROUTING. This is the single place that maps "how important/hard
+     * is this task" to "which model do we pay for" — Manager code should route through this
+     * instead of hardcoding model names.
+     * @param {TaskPriority} priority - One of the six priority levels (see TaskPriority).
+     * @param {AICompletionOptions} overrides - Optional overrides merged on top (e.g. tools, maxTokens).
+     * @returns {AICompletionOptions} Options ready to pass to complete()/stream().
+     * @example
+     * const options = aiVendor.resolvePriority('media-alta-prioridad', { tools: AGENT_TOOLS });
+     * const result = await aiVendor.complete(messages, options);
+     */
+    public resolvePriority(priority: TaskPriority, overrides: AICompletionOptions = {}): AICompletionOptions {
+        const vendor = (overrides.vendor ?? (getEnvString('AI_VENDOR') as AIVendor | undefined) ?? 'anthropic')
+            .toString()
+            .toLowerCase() as AIVendor;
+
+        const route = PRIORITY_ROUTING[priority];
+        if (!route) {
+            throw new TyrError(`Unknown task priority: '${priority}'`, null, `Use one of: ${PRIORITY_LADDER.join(', ')}`);
+        }
+
+        const tierModel = getEnvString(MODEL_TIER_ENV[route.tier]) ?? MODEL_TIERS[vendor][route.tier];
+
+        return {
+            vendor,
+            model: tierModel,
+            thinking: route.thinking,
+            ...overrides,
         };
     }
 
+    /**
+     * @method bumpPriority
+     * @description Escalates a priority one level up the ladder (baja-prioridad → ... →
+     * muy-alta-prioridad), capping at the top. Used for self-healing retries: each consecutive
+     * failure (e.g. a broken compile after an applied patch) buys the model more capability.
+     * @param {TaskPriority} priority - The current priority.
+     * @returns {TaskPriority} The next priority level, or the same value if already at the top.
+     * @example
+     * priority = aiVendor.bumpPriority(priority); // one more level of thinking/model tier
+     */
+    public bumpPriority(priority: TaskPriority): TaskPriority {
+        const index = PRIORITY_LADDER.indexOf(priority);
+        if (index === -1 || index === PRIORITY_LADDER.length - 1) return priority;
+        return PRIORITY_LADDER[index + 1];
+    }
+
+    /**
+     * @method completeWithPriority
+     * @description Convenience wrapper around complete() that resolves model + thinking effort
+     * from a TaskPriority first. Equivalent to `complete(messages, resolvePriority(priority, options))`.
+     * @param {AIMessage[]} messages - Conversation messages.
+     * @param {TaskPriority} priority - Routing priority (see TaskPriority).
+     * @param {AICompletionOptions} options - Optional overrides merged on top of the routed defaults.
+     * @returns {Promise<AICompletionResult>}
+     * @example
+     * const result = await aiVendor.completeWithPriority(messages, 'alta-prioridad', { tools });
+     */
+    public async completeWithPriority(
+        messages: AIMessage[],
+        priority: TaskPriority,
+        options: AICompletionOptions = {}
+    ): Promise<AICompletionResult> {
+        return this.complete(messages, this.resolvePriority(priority, options));
+    }
+
     private splitSystem(messages: AIMessage[]): { system: string; turns: AIMessage[] } {
         const system = messages
             .filter(m => m.role === 'system')
@@ -190,6 +338,7 @@ export class AIVendorManager {
         if (typeof content === 'string') return content;
         return content.map(block => {
             if (block.type === 'text') return { type: 'text', text: block.text };
+            if (block.type === 'image') return { type: 'image', source: { type: 'base64', media_type: block.mediaType, data: block.data } };
             if (block.type === 'tool_use') return { type: 'tool_use', id: block.id, name: block.name, input: block.input };
             return { type: 'tool_result', tool_use_id: block.tool_use_id, content: block.content, ...(block.is_error ? { is_error: true } : {}) };
         });
@@ -231,11 +380,19 @@ export class AIVendorManager {
 
             const toolResults = m.content.filter(b => b.type === 'tool_result') as Array<Extract<AIContentBlock, { type: 'tool_result' }>>;
             const text = m.content.filter(b => b.type === 'text').map(b => (b as any).text).join('');
+            const images = m.content.filter(b => b.type === 'image') as Array<Extract<AIContentBlock, { type: 'image' }>>;
 
             for (const tr of toolResults) {
                 result.push({ role: 'tool', tool_call_id: tr.tool_use_id, content: tr.content });
             }
-            if (text) {
+            if (images.length > 0) {
+                const parts: any[] = [];
+                if (text) parts.push({ type: 'text', text });
+                for (const img of images) {
+                    parts.push({ type: 'image_url', image_url: { url: `data:${img.mediaType};base64,${img.data}` } });
+                }
+                result.push({ role: m.role, content: parts });
+            } else if (text) {
                 result.push({ role: m.role, content: text });
             }
         }
@@ -283,6 +440,7 @@ export class AIVendorManager {
 
             const toolResults = m.content.filter(b => b.type === 'tool_result') as Array<Extract<AIContentBlock, { type: 'tool_result' }>>;
             const textBlocks = m.content.filter(b => b.type === 'text') as Array<Extract<AIContentBlock, { type: 'text' }>>;
+            const imageBlocks = m.content.filter(b => b.type === 'image') as Array<Extract<AIContentBlock, { type: 'image' }>>;
 
             if (toolResults.length > 0) {
                 result.push({
@@ -295,20 +453,51 @@ export class AIVendorManager {
                     })),
                 });
             }
-            if (textBlocks.length > 0) {
-                result.push({ role: 'user', parts: textBlocks.map(b => ({ text: b.text })) });
+            if (textBlocks.length > 0 || imageBlocks.length > 0) {
+                result.push({
+                    role: 'user',
+                    parts: [
+                        ...textBlocks.map(b => ({ text: b.text })),
+                        ...imageBlocks.map(b => ({ inlineData: { mimeType: b.mediaType, data: b.data } })),
+                    ],
+                });
             }
         }
 
         return result;
     }
 
+    /** Anthropic's extended thinking requires temperature === 1 and max_tokens strictly greater
+     *  than budget_tokens; both are enforced here so callers never have to remember it. */
+    private anthropicThinkingFields(config: VendorConfig): { thinking?: any; temperature: number; max_tokens: number } {
+        const budget = THINKING_BUDGETS[config.thinking];
+        if (!budget) return { temperature: config.temperature, max_tokens: config.maxTokens };
+
+        return {
+            thinking: { type: 'enabled', budget_tokens: budget },
+            temperature: 1,
+            max_tokens: Math.max(config.maxTokens, budget + 1024),
+        };
+    }
+
+    /** OpenAI's `reasoning_effort` only exists on the 'o' reasoning model family and only accepts
+     *  low/medium/high (no 'none'/'max') — mapped from our vendor-agnostic ThinkingEffort. Those
+     *  models also reject a custom `temperature`, so it's omitted whenever reasoning_effort is set. */
+    private openaiReasoningFields(config: VendorConfig): { reasoning_effort?: string; temperature?: number } {
+        const isReasoningModel = /^o\d/.test(config.model);
+        if (!isReasoningModel || config.thinking === 'none') return { temperature: config.temperature };
+
+        const effortMap: Partial<Record<ThinkingEffort, string>> = { low: 'low', medium: 'medium', high: 'high', max: 'high' };
+        return { reasoning_effort: effortMap[config.thinking] };
+    }
+
     private buildRequest(config: VendorConfig, messages: AIMessage[], stream: boolean, tools?: AITool[]): VendorRequest {
         const { system, turns } = this.splitSystem(messages);
         const vendorTools = this.buildVendorTools(config, tools);
 
         switch (config.vendor) {
-            case 'anthropic':
+            case 'anthropic': {
+                const thinkingFields = this.anthropicThinkingFields(config);
                 return {
                     url: 'https://api.anthropic.com/v1/messages',
                     headers: {
@@ -320,14 +509,15 @@ export class AIVendorManager {
                         model: config.model,
                         system,
                         messages: this.buildAnthropicMessages(turns),
-                        temperature: config.temperature,
-                        max_tokens: config.maxTokens,
                         stream,
+                        ...thinkingFields,
                         ...(vendorTools ? { tools: vendorTools } : {}),
                     },
                 };
+            }
 
-            case 'openai':
+            case 'openai': {
+                const reasoningFields = this.openaiReasoningFields(config);
                 return {
                     url: 'https://api.openai.com/v1/chat/completions',
                     headers: {
@@ -340,13 +530,14 @@ export class AIVendorManager {
                             ...(system ? [{ role: 'system', content: system }] : []),
                             ...this.buildOpenAIMessages(turns),
                         ],
-                        temperature: config.temperature,
                         max_tokens: config.maxTokens,
                         stream,
+                        ...reasoningFields,
                         ...(stream ? { stream_options: { include_usage: true } } : {}),
                         ...(vendorTools ? { tools: vendorTools } : {}),
                     },
                 };
+            }
 
             case 'gemini': {
                 const action = stream ? 'streamGenerateContent?alt=sse&' : 'generateContent?';