@hed-hog/core 0.0.387 → 0.0.390

package/src/ai/ai.service.ts

@@ -13,16 +13,57 @@ import axios from 'axios';
 import { createHash } from 'crypto';
 import pdfParse from 'pdf-parse';
 import { AiExecutionService } from '../ai-instruction/ai-execution.service';
+import {
+  AiPromptResolverService,
+  applyGeminiModelParams,
+  applyOpenAiModelParams,
+  mergeModelParams,
+  type PromptSource,
+} from '../ai-instruction/ai-prompt-resolver.service';
+import type { TemplateVars } from '../ai-instruction/ai-prompt-template.util';
 import { DeleteDTO } from '../dto/delete.dto';
 import { FileService } from '../file/file.service';
-import { buildAiConfigFromIntegration } from '../integration-profile/integration-profile.utils';
+import {
+  buildAiConfigFromIntegration,
+  DEEPSEEK_API_BASE_URL,
+  DEEPSEEK_DEFAULT_MODEL,
+} from '../integration-profile/integration-profile.utils';
 import { SettingService } from '../setting/setting.service';
+import {
+  attachedFileBlock,
+  binaryAttachmentMarker,
+  unreadablePdfMarker,
+} from './ai-attachment.fragments';
+import { CORE_AI_PROMPT_SLUGS } from './ai.prompts';
 import { ChatAgentDTO } from './dto/chat-agent.dto';
 import { ChatDTO } from './dto/chat.dto';
 import { CreateAgentDTO } from './dto/create-agent.dto';
 import { UpdateAgentDTO } from './dto/update-agent.dto';
 
-type AiProvider = 'openai' | 'gemini';
+type AiProvider = 'openai' | 'gemini' | 'deepseek';
+
+/** Fallback call timeout when the active AI integration profile doesn't set `timeout_ms`. */
+const DEFAULT_AI_CALL_TIMEOUT_MS = 120_000;
+
+/** Setting (Settings → AI) que guarda o perfil de integração de cada provider. */
+const AI_PROFILE_SETTING: Record<AiProvider, string> = {
+  openai: 'ai-openai-profile-id',
+  gemini: 'ai-gemini-profile-id',
+  deepseek: 'ai-deepseek-profile-id',
+};
+
+/**
+ * Optional per-call model tuning.
+ *
+ * These are only sent to the provider when a value is present: the request
+ * bodies must stay byte-identical to what they were before this existed, since
+ * some newer models reject `temperature` / `max_tokens` outright.
+ */
+export type AiChatModelParams = {
+  temperature?: number | null;
+  maxTokens?: number | null;
+  responseFormat?: 'text' | 'json_object';
+};
 
 type AiAgentRecord = {
   id: number;
@@ -54,68 +95,141 @@ export class AiService implements OnModuleInit {
     private readonly fileService: FileService,
     @Inject(forwardRef(() => AiExecutionService))
     private readonly aiExecution: AiExecutionService,
+    @Inject(forwardRef(() => AiPromptResolverService))
+    private readonly promptResolver: AiPromptResolverService,
   ) {}
 
   async onModuleInit() {
     try {
-      const s = await this.settingService.getSettingValues([
-        'ai-openai-profile-id',
-        'ai-gemini-profile-id',
-      ]);
-      if (
-        !String(s['ai-openai-profile-id'] ?? '').trim() &&
-        !String(s['ai-gemini-profile-id'] ?? '').trim()
-      ) {
+      const slugs = Object.values(AI_PROFILE_SETTING);
+      const s = await this.settingService.getSettingValues(slugs);
+      if (slugs.every((slug) => !String(s[slug] ?? '').trim())) {
         this.logger.warn('No AI profiles configured. Set profiles in Settings → AI.');
       }
     } catch { /* settings not available yet */ }
   }
 
   async chat(data: ChatDTO, file?: MulterFile) {
-    const provider = data.provider || 'openai';
+    const provider = data.provider || (await this.getDefaultProvider());
     const attachment = await this.resolveAttachment(file, data.file_id);
+    const aiProfile = await this.getAiProfile(provider);
+    const model = data.model || aiProfile.model || this.getDefaultModel(provider);
+    const timeoutMs = aiProfile.timeoutMs ?? DEFAULT_AI_CALL_TIMEOUT_MS;
+    const params: AiChatModelParams = {
+      temperature: data.temperature,
+      maxTokens: data.max_tokens,
+      responseFormat: data.response_format,
+    };
 
     const executionId = await this.aiExecution.start({ trigger: 'api', contextSlug: 'ai-chat' });
     const stepStart = Date.now();
 
     try {
-      if (provider === 'openai') {
-        const model = data.model || 'gpt-4o-mini';
-        const { content, usage } = await this.chatWithOpenAi({
+      const { content, usage } = await this.withTimeout(
+        this.chatWithProvider(provider, {
           message: data.message,
           model,
           systemPrompt: data.systemPrompt,
           attachment,
-        });
-
-        await this.aiExecution.recordStep({
-          executionId,
-          stepOrder: 0,
-          type: 'output',
-          provider: 'openai',
-          model,
-          durationMs: Date.now() - stepStart,
-          usage,
-          outputSummary: content.slice(0, 200),
-        });
-        await this.aiExecution.finish(executionId, 'completed');
-
-        return { provider, model, content };
-      }
+          apiKey: aiProfile.apiKey,
+          baseUrl: aiProfile.baseUrl,
+          params,
+        }),
+        timeoutMs,
+      );
 
-      const model = data.model || 'gemini-1.5-flash';
-      const { content, usage } = await this.chatWithGemini({
-        message: data.message,
+      await this.aiExecution.recordStep({
+        executionId,
+        stepOrder: 0,
+        type: 'output',
+        provider,
         model,
-        systemPrompt: data.systemPrompt,
-        attachment,
+        durationMs: Date.now() - stepStart,
+        usage,
+        outputSummary: content.slice(0, 200),
       });
+      await this.aiExecution.finish(executionId, 'completed');
+
+      return { provider, model, content };
+    } catch (err) {
+      await this.aiExecution.finish(executionId, 'failed', String(err));
+      throw err;
+    }
+  }
+
+  /**
+   * Chat driven by prompts stored in `ai_instruction`.
+   *
+   * Resolves the system and user prompts by slug in one query, applies whatever
+   * model params the records declare (falling back to `params` and then to the
+   * provider defaults), and reports back where each prompt came from so callers
+   * can log a fallback.
+   */
+  async chatWithPrompt(input: {
+    systemPromptSlug?: string;
+    userPromptSlug: string;
+    variables?: TemplateVars;
+    provider?: AiProvider;
+    params?: AiChatModelParams;
+    contextSlug?: string;
+  }): Promise<{
+    provider: AiProvider;
+    model: string;
+    content: string;
+    promptSources: Record<string, PromptSource>;
+  }> {
+    const slugs = input.systemPromptSlug
+      ? [input.systemPromptSlug, input.userPromptSlug]
+      : [input.userPromptSlug];
+
+    const resolved = await this.promptResolver.resolveMany(
+      slugs.map((slug) => ({ slug, variables: input.variables })),
+    );
+
+    const systemPrompt = input.systemPromptSlug
+      ? resolved[input.systemPromptSlug]
+      : undefined;
+    const userPrompt = resolved[input.userPromptSlug];
+
+    // The system prompt represents the call, so its params win over the user one.
+    const stored = mergeModelParams(systemPrompt, userPrompt);
+
+    const provider = input.provider || (await this.getDefaultProvider());
+    const aiProfile = await this.getAiProfile(provider);
+    const model =
+      stored.model || aiProfile.model || this.getDefaultModel(provider);
+    const timeoutMs = aiProfile.timeoutMs ?? DEFAULT_AI_CALL_TIMEOUT_MS;
+
+    const params: AiChatModelParams = {
+      temperature: stored.temperature ?? input.params?.temperature,
+      maxTokens: stored.maxTokens ?? input.params?.maxTokens,
+      responseFormat: input.params?.responseFormat,
+    };
+
+    const executionId = await this.aiExecution.start({
+      trigger: 'api',
+      contextSlug: input.contextSlug || input.userPromptSlug,
+    });
+    const stepStart = Date.now();
+
+    try {
+      const { content, usage } = await this.withTimeout(
+        this.chatWithProvider(provider, {
+          message: userPrompt.content,
+          model,
+          systemPrompt: systemPrompt?.content || undefined,
+          apiKey: aiProfile.apiKey,
+          baseUrl: aiProfile.baseUrl,
+          params,
+        }),
+        timeoutMs,
+      );
 
       await this.aiExecution.recordStep({
         executionId,
         stepOrder: 0,
         type: 'output',
-        provider: 'gemini',
+        provider,
         model,
         durationMs: Date.now() - stepStart,
         usage,
@@ -123,7 +237,11 @@ export class AiService implements OnModuleInit {
       });
       await this.aiExecution.finish(executionId, 'completed');
 
-      return { provider, model, content };
+      const promptSources = Object.fromEntries(
+        Object.entries(resolved).map(([slug, prompt]) => [slug, prompt.source]),
+      );
+
+      return { provider, model, content, promptSources };
     } catch (err) {
       await this.aiExecution.finish(executionId, 'failed', String(err));
       throw err;
@@ -155,7 +273,7 @@ export class AiService implements OnModuleInit {
       INSERT INTO ai_agent (slug, provider, model, instructions, external_agent_id)
       VALUES (
         ${slug},
-        CAST(${provider} AS ai_agent_provider_enum),
+        CAST(${provider} AS ai_agent_provider_7cb93b1143_enum),
         ${model},
         ${instructions},
         ${externalAgentId}
@@ -165,6 +283,39 @@ export class AiService implements OnModuleInit {
     return this.findAgentBySlug(slug);
   }
 
+  /**
+   * Creates the agent, or updates it when its stored instructions/model drifted
+   * from what the caller now wants.
+   *
+   * `createAgent` returns the existing row untouched, so a caller that passes
+   * instructions on every request would keep whatever the very first call
+   * persisted. That silently defeats an editable prompt: the admin would save a
+   * change and the agent would go on using the original text.
+   */
+  async upsertAgent(data: CreateAgentDTO) {
+    const existing = await this.findAgentBySlug(data.slug.trim());
+
+    if (!existing) {
+      return this.createAgent(data);
+    }
+
+    const instructions = data.instructions?.trim() || null;
+    const model = data.model || existing.model;
+
+    const unchanged =
+      (instructions === null || instructions === existing.instructions) &&
+      model === existing.model;
+
+    if (unchanged) {
+      return existing;
+    }
+
+    return this.updateAgent(existing.id, {
+      instructions: instructions ?? undefined,
+      model: model ?? undefined,
+    });
+  }
+
   async listAgents(paginationParams: PaginationDTO) {
     const page = Math.max(Number(paginationParams?.page || 1), 1);
     const pageSize = Math.min(
@@ -248,7 +399,7 @@ export class AiService implements OnModuleInit {
     await this.prismaService.$executeRaw`
       UPDATE ai_agent
       SET slug = ${slug},
-          provider = CAST(${provider} AS ai_agent_provider_enum),
+          provider = CAST(${provider} AS ai_agent_provider_7cb93b1143_enum),
           model = ${model},
           instructions = ${instructions},
           external_agent_id = ${externalAgentId},
@@ -292,27 +443,11 @@ export class AiService implements OnModuleInit {
       throw new NotFoundException(`AI agent with slug "${slug}" was not found.`);
     }
 
-    if (agent.provider === 'openai') {
-      if (agent.external_agent_id && !attachment) {
-        const content = await this.chatWithOpenAiAssistant(
-          agent.external_agent_id,
-          data.message,
-        );
-
-        return {
-          slug: agent.slug,
-          provider: agent.provider,
-          model: agent.model,
-          content,
-        };
-      }
-
-      const { content } = await this.chatWithOpenAi({
-        message: data.message,
-        model: agent.model || this.getDefaultModel('openai'),
-        systemPrompt: agent.instructions || undefined,
-        attachment,
-      });
+    if (agent.provider === 'openai' && agent.external_agent_id && !attachment) {
+      const content = await this.chatWithOpenAiAssistant(
+        agent.external_agent_id,
+        data.message,
+      );
 
       return {
         slug: agent.slug,
@@ -322,11 +457,15 @@ export class AiService implements OnModuleInit {
       };
     }
 
-    const { content } = await this.chatWithGemini({
+    const aiProfile = await this.getAiProfile(agent.provider);
+
+    const { content } = await this.chatWithProvider(agent.provider, {
       message: data.message,
-      model: agent.model || this.getDefaultModel('gemini'),
+      model: agent.model || this.getDefaultModel(agent.provider),
       systemPrompt: agent.instructions || undefined,
       attachment,
+      apiKey: aiProfile.apiKey,
+      baseUrl: aiProfile.baseUrl,
     });
 
     return {
@@ -435,15 +574,74 @@ export class AiService implements OnModuleInit {
   }
 
   private getDefaultModel(provider: AiProvider): string {
-    if (provider === 'openai') {
-      return 'gpt-4o-mini';
+    if (provider === 'gemini') {
+      return 'gemini-1.5-flash';
+    }
+
+    if (provider === 'deepseek') {
+      return DEEPSEEK_DEFAULT_MODEL;
+    }
+
+    return 'gpt-4o-mini';
+  }
+
+  /** Default AI provider used when a caller doesn't specify one (Settings → AI). */
+  private async getDefaultProvider(): Promise<AiProvider> {
+    const settings = await this.settingService.getSettingValues(['ai-default-provider']);
+    const value = String(settings['ai-default-provider'] ?? '').trim();
+    return value in AI_PROFILE_SETTING ? (value as AiProvider) : 'openai';
+  }
+
+  /**
+   * Envia o chat ao provider certo.
+   *
+   * O DeepSeek expõe a mesma API de `/chat/completions` da OpenAI, então reusa o
+   * caminho da OpenAI trocando a base URL — só não aceita imagens, porque os
+   * modelos `deepseek-chat`/`deepseek-reasoner` não têm visão.
+   */
+  private chatWithProvider(
+    provider: AiProvider,
+    input: {
+      message: string;
+      model: string;
+      systemPrompt?: string;
+      attachment?: AiAttachment | null;
+      apiKey?: string;
+      baseUrl?: string;
+      params?: AiChatModelParams;
+    },
+  ) {
+    if (provider === 'gemini') {
+      return this.chatWithGemini(input);
     }
 
-    return 'gemini-1.5-flash';
+    if (provider === 'deepseek') {
+      return this.chatWithOpenAi({
+        ...input,
+        provider,
+        baseUrl: input.baseUrl || DEEPSEEK_API_BASE_URL,
+        supportsImages: false,
+      });
+    }
+
+    return this.chatWithOpenAi(input);
   }
 
   private async getAiApiKey(provider: AiProvider): Promise<string> {
-    const slug = provider === 'openai' ? 'ai-openai-profile-id' : 'ai-gemini-profile-id';
+    return (await this.getAiProfile(provider)).apiKey;
+  }
+
+  /** Resolves the active AI integration profile's credentials plus its optional model/timeout overrides. */
+  private async getAiProfile(
+    provider: AiProvider,
+  ): Promise<{
+    apiKey: string;
+    organization?: string;
+    model?: string;
+    timeoutMs?: number;
+    baseUrl?: string;
+  }> {
+    const slug = AI_PROFILE_SETTING[provider] ?? AI_PROFILE_SETTING.openai;
     const settings = await this.settingService.getSettingValues([slug]);
     const profileSlug = String(settings[slug] ?? '').trim();
 
@@ -462,16 +660,33 @@ export class AiService implements OnModuleInit {
       throw new BadRequestException(`AI profile "${profileSlug}" not found.`);
     }
 
-    const { apiKey } = buildAiConfigFromIntegration(
+    const aiConfig = buildAiConfigFromIntegration(
       profile.integration_provider.slug,
       profile.config,
     );
 
-    if (!apiKey) {
+    if (!aiConfig.apiKey) {
       throw new BadRequestException(`AI profile "${profileSlug}" has no API key configured.`);
     }
 
-    return apiKey;
+    return aiConfig;
+  }
+
+  /** Rejects with a timeout error if `promise` doesn't settle within `ms`. */
+  private withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error(`AI call timed out after ${ms}ms`)), ms);
+      promise.then(
+        (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+      );
+    });
   }
 
   private async chatWithOpenAi({
@@ -479,13 +694,24 @@ export class AiService implements OnModuleInit {
     model,
     systemPrompt,
     attachment,
+    apiKey,
+    params,
+    provider = 'openai',
+    baseUrl = 'https://api.openai.com/v1',
+    supportsImages = true,
   }: {
     message: string;
     model: string;
     systemPrompt?: string;
     attachment?: AiAttachment | null;
+    apiKey?: string;
+    params?: AiChatModelParams;
+    /** Provider dono da chave — o DeepSeek usa este mesmo formato de requisição. */
+    provider?: AiProvider;
+    baseUrl?: string;
+    supportsImages?: boolean;
   }): Promise<{ content: string; usage?: { input: number; output: number; total: number } }> {
-    const openai = await this.getAiApiKey('openai');
+    const openai = apiKey ?? (await this.getAiApiKey(provider));
 
     const messages: Array<any> = [];
 
@@ -493,12 +719,22 @@ export class AiService implements OnModuleInit {
       messages.push({ role: 'system', content: systemPrompt });
     }
 
-    const userContent = await this.buildOpenAiUserContent(message, attachment);
+    const userContent = await this.buildOpenAiUserContent(
+      message,
+      attachment,
+      supportsImages,
+    );
     messages.push({ role: 'user', content: userContent });
 
+    const body = applyOpenAiModelParams(
+      { messages },
+      { model: null, temperature: params?.temperature ?? null, maxTokens: params?.maxTokens ?? null },
+      { model, jsonObject: params?.responseFormat === 'json_object' },
+    );
+
     const response = await axios.post(
-      'https://api.openai.com/v1/chat/completions',
-      { model, messages },
+      `${baseUrl.replace(/\/+$/, '')}/chat/completions`,
+      body,
       {
         headers: {
           Authorization: `Bearer ${openai}`,
@@ -525,12 +761,17 @@ export class AiService implements OnModuleInit {
   }): Promise<string> {
     const openai = await this.getAiApiKey('openai');
 
+    const defaultInstructions = await this.promptResolver.resolve({
+      slug: CORE_AI_PROMPT_SLUGS.agentDefaultInstructions,
+      variables: { slug },
+    });
+
     const response = await axios.post(
       'https://api.openai.com/v1/assistants',
       {
         name: slug,
         model,
-        instructions: instructions || `You are the assistant identified by slug ${slug}.`,
+        instructions: instructions || defaultInstructions.content,
       },
       {
         headers: {
@@ -646,13 +887,17 @@ export class AiService implements OnModuleInit {
     model,
     systemPrompt,
     attachment,
+    apiKey,
+    params,
   }: {
     message: string;
     model: string;
     systemPrompt?: string;
     attachment?: AiAttachment | null;
+    apiKey?: string;
+    params?: AiChatModelParams;
   }): Promise<{ content: string; usage?: { input: number; output: number; total: number } }> {
-    const gemini = await this.getAiApiKey('gemini');
+    const gemini = apiKey ?? (await this.getAiApiKey('gemini'));
 
     const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${gemini}`;
 
@@ -661,13 +906,13 @@ export class AiService implements OnModuleInit {
     if (attachment) {
       if (this.isTextMime(attachment.mimeType)) {
         userParts.push({
-          text: `\n\n[Attached file: ${attachment.filename}]\n${this.toUtf8Text(attachment.buffer)}`,
+          text: attachedFileBlock(attachment.filename, this.toUtf8Text(attachment.buffer)),
         });
       } else if (this.isPdfMime(attachment.mimeType)) {
         const pdfText = await this.extractPdfText(attachment.buffer);
         if (pdfText) {
           userParts.push({
-            text: `\n\n[Attached file: ${attachment.filename}]\n${pdfText}`,
+            text: attachedFileBlock(attachment.filename, pdfText),
           });
         } else {
           userParts.push({
@@ -687,7 +932,7 @@ export class AiService implements OnModuleInit {
       }
     }
 
-    const payload: any = {
+    let payload: any = {
       contents: [{ parts: userParts }],
     };
 
@@ -697,6 +942,12 @@ export class AiService implements OnModuleInit {
       };
     }
 
+    payload = applyGeminiModelParams(
+      payload,
+      { model: null, temperature: params?.temperature ?? null, maxTokens: params?.maxTokens ?? null },
+      { jsonObject: params?.responseFormat === 'json_object' },
+    );
+
     const response = await axios.post(url, payload, {
       headers: {
         'Content-Type': 'application/json',
@@ -751,12 +1002,13 @@ export class AiService implements OnModuleInit {
   private async buildOpenAiUserContent(
     message: string,
     attachment?: AiAttachment | null,
+    supportsImages = true,
   ) {
     if (!attachment) {
       return message;
     }
 
-    if (this.isImageMime(attachment.mimeType)) {
+    if (supportsImages && this.isImageMime(attachment.mimeType)) {
       const dataUri = `data:${attachment.mimeType};base64,${attachment.buffer.toString('base64')}`;
       return [
         { type: 'text', text: message },
@@ -771,12 +1023,16 @@ export class AiService implements OnModuleInit {
     } else if (this.isPdfMime(attachment.mimeType)) {
       text =
         (await this.extractPdfText(attachment.buffer)) ||
-        `[PDF attachment with unreadable text: ${attachment.filename}]`;
+        unreadablePdfMarker(attachment.filename);
     } else {
-      text = `[Binary attachment: ${attachment.filename} | ${attachment.mimeType} | ${attachment.buffer.length} bytes]`;
+      text = binaryAttachmentMarker(
+        attachment.filename,
+        attachment.mimeType,
+        attachment.buffer.length,
+      );
     }
 
-    return `${message}\n\n[Attached file: ${attachment.filename}]\n${text}`;
+    return `${message}${attachedFileBlock(attachment.filename, text)}`;
   }
 
   private isImageMime(mimeType: string) {

package/src/ai/dto/chat.dto.ts

@@ -1,5 +1,14 @@
 import { Type } from 'class-transformer';
-import { IsIn, IsInt, IsNotEmpty, IsOptional, IsString } from 'class-validator';
+import {
+  IsIn,
+  IsInt,
+  IsNotEmpty,
+  IsNumber,
+  IsOptional,
+  IsString,
+  Max,
+  Min,
+} from 'class-validator';
 
 export class ChatDTO {
   @IsString()
@@ -8,8 +17,8 @@ export class ChatDTO {
 
   @IsOptional()
   @IsString()
-  @IsIn(['openai', 'gemini'])
-  provider?: 'openai' | 'gemini';
+  @IsIn(['openai', 'gemini', 'deepseek'])
+  provider?: 'openai' | 'gemini' | 'deepseek';
 
   @IsOptional()
   @IsString()
@@ -23,4 +32,25 @@ export class ChatDTO {
   @Type(() => Number)
   @IsInt()
   file_id?: number;
+
+  // Omitted parameters are not sent to the provider at all — some newer models
+  // reject temperature/max_tokens.
+  @IsOptional()
+  @Type(() => Number)
+  @IsNumber()
+  @Min(0)
+  @Max(2)
+  temperature?: number;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(200000)
+  max_tokens?: number;
+
+  @IsOptional()
+  @IsString()
+  @IsIn(['text', 'json_object'])
+  response_format?: 'text' | 'json_object';
 }

package/src/ai/dto/create-agent.dto.ts

@@ -7,8 +7,8 @@ export class CreateAgentDTO {
 
   @IsOptional()
   @IsString()
-  @IsIn(['openai', 'gemini'])
-  provider?: 'openai' | 'gemini';
+  @IsIn(['openai', 'gemini', 'deepseek'])
+  provider?: 'openai' | 'gemini' | 'deepseek';
 
   @IsOptional()
   @IsString()