@hed-hog/core 0.0.387 → 0.0.393

package/src/ai/ai-attachment.fragments.spec.ts

@@ -0,0 +1,319 @@
+import axios from 'axios';
+import {
+  attachedFileBlock,
+  binaryAttachmentMarker,
+  unreadablePdfMarker,
+} from './ai-attachment.fragments';
+import { AiService } from './ai.service';
+
+jest.mock('axios');
+
+const mockedAxios = axios as jest.Mocked<typeof axios>;
+
+/**
+ * Fidelidade byte a byte da extração.
+ *
+ * As funções `legacy*` abaixo são cópias literais do que `chatWithGemini` e
+ * `buildOpenAiUserContent` montavam inline antes dos marcadores virarem helpers
+ * — `[Attached file: …]` estava triplicado, `[Binary attachment: …]` e
+ * `[PDF attachment with unreadable text: …]` moram no mesmo bloco. Um `\n`
+ * perdido ou um espaço a mais em torno dos `|` muda o que o modelo recebe SEM
+ * levantar erro algum. Este é o único check que pega isso — não "arrume" estas
+ * cópias.
+ *
+ * Repare no ponto delicado: no legado do OpenAI o `\n\n` ficava no template do
+ * `return`, e agora vem de dentro de `attachedFileBlock`. Os bytes finais são os
+ * mesmos, e é exatamente isso que `legacyOpenAiReturn` prova.
+ */
+
+type LegacyAttachment = { filename: string; mimeType: string; buffer: Buffer };
+
+function legacyGeminiTextPart(attachment: LegacyAttachment, utf8Text: string): string {
+  return `\n\n[Attached file: ${attachment.filename}]\n${utf8Text}`;
+}
+
+function legacyGeminiPdfPart(attachment: LegacyAttachment, pdfText: string): string {
+  return `\n\n[Attached file: ${attachment.filename}]\n${pdfText}`;
+}
+
+function legacyUnreadablePdf(attachment: LegacyAttachment): string {
+  return `[PDF attachment with unreadable text: ${attachment.filename}]`;
+}
+
+function legacyBinaryMarker(attachment: LegacyAttachment): string {
+  return `[Binary attachment: ${attachment.filename} | ${attachment.mimeType} | ${attachment.buffer.length} bytes]`;
+}
+
+function legacyOpenAiReturn(
+  message: string,
+  attachment: LegacyAttachment,
+  text: string,
+): string {
+  return `${message}\n\n[Attached file: ${attachment.filename}]\n${text}`;
+}
+
+function makeAttachment(
+  filename: string,
+  mimeType: string,
+  content: string,
+): LegacyAttachment {
+  return { filename, mimeType, buffer: Buffer.from(content, 'utf8') };
+}
+
+const TEXT_ATTACHMENT = makeAttachment('notas.txt', 'text/plain', 'linha 1\nlinha 2');
+const PDF_ATTACHMENT = makeAttachment('contrato.pdf', 'application/pdf', '%PDF-1.4');
+const BINARY_ATTACHMENT = makeAttachment('planilha.xlsx', 'application/octet-stream', 'PK');
+
+describe('marcadores de anexo — fidelidade', () => {
+  it('bloco de arquivo de texto é idêntico ao original do Gemini', () => {
+    const utf8Text = TEXT_ATTACHMENT.buffer.toString('utf8');
+
+    expect(attachedFileBlock(TEXT_ATTACHMENT.filename, utf8Text)).toBe(
+      legacyGeminiTextPart(TEXT_ATTACHMENT, utf8Text),
+    );
+  });
+
+  it('bloco de PDF extraído é idêntico ao original do Gemini', () => {
+    const pdfText = 'Cláusula 1ª — objeto do contrato.';
+
+    expect(attachedFileBlock(PDF_ATTACHMENT.filename, pdfText)).toBe(
+      legacyGeminiPdfPart(PDF_ATTACHMENT, pdfText),
+    );
+  });
+
+  it('bloco do OpenAI é idêntico ao original mesmo com o \\n\\n vindo do helper', () => {
+    const message = 'Resuma o anexo.';
+    const text = TEXT_ATTACHMENT.buffer.toString('utf8');
+
+    expect(`${message}${attachedFileBlock(TEXT_ATTACHMENT.filename, text)}`).toBe(
+      legacyOpenAiReturn(message, TEXT_ATTACHMENT, text),
+    );
+  });
+
+  it('marcador de binário é idêntico ao original, com os pipes espaçados', () => {
+    expect(
+      binaryAttachmentMarker(
+        BINARY_ATTACHMENT.filename,
+        BINARY_ATTACHMENT.mimeType,
+        BINARY_ATTACHMENT.buffer.length,
+      ),
+    ).toBe(legacyBinaryMarker(BINARY_ATTACHMENT));
+
+    expect(binaryAttachmentMarker('a.bin', 'application/octet-stream', 12)).toBe(
+      '[Binary attachment: a.bin | application/octet-stream | 12 bytes]',
+    );
+  });
+
+  it('marcador de PDF ilegível é idêntico ao original', () => {
+    expect(unreadablePdfMarker(PDF_ATTACHMENT.filename)).toBe(
+      legacyUnreadablePdf(PDF_ATTACHMENT),
+    );
+  });
+
+  it('preserva nome de arquivo com espaço, acento e pipe', () => {
+    const weird = makeAttachment('nota fiscal | 2ª via.pdf', 'application/pdf', 'x');
+
+    expect(attachedFileBlock(weird.filename, 'corpo')).toBe(
+      legacyGeminiPdfPart(weird, 'corpo'),
+    );
+    expect(binaryAttachmentMarker(weird.filename, weird.mimeType, weird.buffer.length)).toBe(
+      legacyBinaryMarker(weird),
+    );
+    expect(unreadablePdfMarker(weird.filename)).toBe(legacyUnreadablePdf(weird));
+  });
+
+  it('corpo vazio mantém a quebra final, e zero bytes continua "0 bytes"', () => {
+    const empty = makeAttachment('vazio.txt', 'text/plain', '');
+
+    expect(attachedFileBlock(empty.filename, '')).toBe(legacyGeminiTextPart(empty, ''));
+    expect(attachedFileBlock(empty.filename, '')).toBe('\n\n[Attached file: vazio.txt]\n');
+    expect(binaryAttachmentMarker(empty.filename, empty.mimeType, empty.buffer.length)).toBe(
+      legacyBinaryMarker(empty),
+    );
+  });
+});
+
+/**
+ * O que sai no fio. Este bloco é o que pega "troquei o call site pelo helper
+ * errado" — os asserts comparam o corpo da requisição com as cópias legadas.
+ */
+describe('AiService — anexos no fio', () => {
+  let service: AiService;
+
+  const aiProfile = { apiKey: 'sk-test', model: undefined, timeoutMs: undefined };
+
+  beforeEach(() => {
+    const prisma = {} as any;
+    const settingService = { getSettingValues: jest.fn().mockResolvedValue({}) } as any;
+    const fileService = {} as any;
+    const aiExecution = {
+      start: jest.fn().mockResolvedValue(1),
+      recordStep: jest.fn().mockResolvedValue(undefined),
+      finish: jest.fn().mockResolvedValue(undefined),
+    } as any;
+    const promptResolver = { resolveMany: jest.fn() };
+
+    service = new AiService(prisma, settingService, fileService, aiExecution, promptResolver as any);
+
+    jest.spyOn(service as any, 'getAiProfile').mockResolvedValue(aiProfile);
+    jest.spyOn(service as any, 'getDefaultProvider').mockResolvedValue('openai');
+
+    mockedAxios.post.mockResolvedValue({
+      data: {
+        choices: [{ message: { content: 'ok' } }],
+        candidates: [{ content: { parts: [{ text: 'ok' }] } }],
+      },
+    } as any);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    mockedAxios.post.mockReset();
+  });
+
+  function useAttachment(attachment: LegacyAttachment | null) {
+    jest.spyOn(service as any, 'resolveAttachment').mockResolvedValue(attachment);
+  }
+
+  function lastBody(): Record<string, any> {
+    return mockedAxios.post.mock.calls.at(-1)?.[1] as Record<string, any>;
+  }
+
+  describe('Gemini', () => {
+    it('embrulha anexo de texto exatamente como o código original', async () => {
+      useAttachment(TEXT_ATTACHMENT);
+
+      await service.chat({ message: 'Resuma.', provider: 'gemini' } as any);
+
+      expect(lastBody().contents[0].parts[1].text).toBe(
+        legacyGeminiTextPart(TEXT_ATTACHMENT, TEXT_ATTACHMENT.buffer.toString('utf8')),
+      );
+    });
+
+    it('embrulha PDF com texto extraído exatamente como o código original', async () => {
+      const pdfText = 'Cláusula 1ª — objeto do contrato.';
+      useAttachment(PDF_ATTACHMENT);
+      jest.spyOn(service as any, 'extractPdfText').mockResolvedValue(pdfText);
+
+      await service.chat({ message: 'Resuma.', provider: 'gemini' } as any);
+
+      expect(lastBody().contents[0].parts[1].text).toBe(
+        legacyGeminiPdfPart(PDF_ATTACHMENT, pdfText),
+      );
+    });
+
+    it('PDF ilegível continua indo como inline_data, sem marcador de texto', async () => {
+      useAttachment(PDF_ATTACHMENT);
+      jest.spyOn(service as any, 'extractPdfText').mockResolvedValue('');
+
+      await service.chat({ message: 'Resuma.', provider: 'gemini' } as any);
+
+      const part = lastBody().contents[0].parts[1];
+      expect(part).not.toHaveProperty('text');
+      expect(part.inline_data.mime_type).toBe('application/pdf');
+    });
+
+    it('binário continua indo como inline_data, sem marcador de texto', async () => {
+      useAttachment(BINARY_ATTACHMENT);
+
+      await service.chat({ message: 'Resuma.', provider: 'gemini' } as any);
+
+      const part = lastBody().contents[0].parts[1];
+      expect(part).not.toHaveProperty('text');
+      expect(part.inline_data.mime_type).toBe('application/octet-stream');
+    });
+
+    it('sem anexo, a mensagem vai crua num único part', async () => {
+      useAttachment(null);
+
+      await service.chat({ message: 'Resuma.', provider: 'gemini' } as any);
+
+      expect(lastBody().contents[0].parts).toHaveLength(1);
+      expect(lastBody().contents[0].parts[0].text).toBe('Resuma.');
+    });
+  });
+
+  describe('OpenAI', () => {
+    it('embrulha anexo de texto exatamente como o código original', async () => {
+      useAttachment(TEXT_ATTACHMENT);
+
+      await service.chat({ message: 'Resuma.', provider: 'openai' } as any);
+
+      expect(lastBody().messages[0].content).toBe(
+        legacyOpenAiReturn(
+          'Resuma.',
+          TEXT_ATTACHMENT,
+          TEXT_ATTACHMENT.buffer.toString('utf8'),
+        ),
+      );
+    });
+
+    it('embrulha PDF com texto extraído exatamente como o código original', async () => {
+      const pdfText = 'Cláusula 1ª — objeto do contrato.';
+      useAttachment(PDF_ATTACHMENT);
+      jest.spyOn(service as any, 'extractPdfText').mockResolvedValue(pdfText);
+
+      await service.chat({ message: 'Resuma.', provider: 'openai' } as any);
+
+      expect(lastBody().messages[0].content).toBe(
+        legacyOpenAiReturn('Resuma.', PDF_ATTACHMENT, pdfText),
+      );
+    });
+
+    it('PDF ilegível cai no marcador de PDF, dentro do bloco de arquivo', async () => {
+      useAttachment(PDF_ATTACHMENT);
+      jest.spyOn(service as any, 'extractPdfText').mockResolvedValue('');
+
+      await service.chat({ message: 'Resuma.', provider: 'openai' } as any);
+
+      expect(lastBody().messages[0].content).toBe(
+        legacyOpenAiReturn('Resuma.', PDF_ATTACHMENT, legacyUnreadablePdf(PDF_ATTACHMENT)),
+      );
+    });
+
+    it('binário cai no marcador de binário, dentro do bloco de arquivo', async () => {
+      useAttachment(BINARY_ATTACHMENT);
+
+      await service.chat({ message: 'Resuma.', provider: 'openai' } as any);
+
+      expect(lastBody().messages[0].content).toBe(
+        legacyOpenAiReturn(
+          'Resuma.',
+          BINARY_ATTACHMENT,
+          legacyBinaryMarker(BINARY_ATTACHMENT),
+        ),
+      );
+    });
+
+    it('imagem continua indo por image_url, sem nenhum marcador', async () => {
+      const image = makeAttachment('foto.png', 'image/png', 'binario');
+      useAttachment(image);
+
+      await service.chat({ message: 'Descreva.', provider: 'openai' } as any);
+
+      const content = lastBody().messages[0].content;
+      expect(content[0]).toEqual({ type: 'text', text: 'Descreva.' });
+      expect(content[1].type).toBe('image_url');
+      expect(JSON.stringify(content)).not.toContain('[Attached file:');
+    });
+
+    it('no DeepSeek, imagem cai no marcador de binário (o modelo não tem visão)', async () => {
+      const image = makeAttachment('foto.png', 'image/png', 'binario');
+      useAttachment(image);
+
+      await service.chat({ message: 'Descreva.', provider: 'deepseek' } as any);
+
+      expect(lastBody().messages[0].content).toBe(
+        legacyOpenAiReturn('Descreva.', image, legacyBinaryMarker(image)),
+      );
+    });
+
+    it('sem anexo, a mensagem vai crua — sem \\n\\n pendurado', async () => {
+      useAttachment(null);
+
+      await service.chat({ message: 'Resuma.', provider: 'openai' } as any);
+
+      expect(lastBody().messages[0].content).toBe('Resuma.');
+    });
+  });
+});

package/src/ai/ai-attachment.fragments.ts

@@ -0,0 +1,35 @@
+/**
+ * Framing mecânico de anexo enviado ao modelo — deliberadamente FORA do registry
+ * de `ai_instruction` (ver o docblock de `ai.prompts.ts`).
+ *
+ * Estes marcadores andam em lockstep com `isTextMime`/`isPdfMime`/`extractPdfText`
+ * em `ai.service.ts`: são o que diz ao modelo que o texto a seguir é o conteúdo de
+ * um arquivo, e não a mensagem do usuário. Antes estavam copiados literalmente nos
+ * dois caminhos de provider (Gemini e OpenAI), onde uma cópia podia ser corrigida
+ * e a outra esquecida sem gerar erro nenhum.
+ *
+ * O `\n\n` inicial faz parte do bloco: no Gemini ele abre um `part` separado, no
+ * OpenAI ele é a junta logo depois de `${message}`. Nos dois casos os bytes finais
+ * são exatamente os mesmos.
+ *
+ * Coberto byte a byte por `ai-attachment.fragments.spec.ts` — não "arrume" o texto.
+ */
+
+/** Bloco que embrulha o conteúdo textual extraído de um anexo. */
+export function attachedFileBlock(filename: string, body: string): string {
+  return `\n\n[Attached file: ${filename}]\n${body}`;
+}
+
+/** Usado quando o anexo não é texto nem PDF legível e vai apenas descrito. */
+export function binaryAttachmentMarker(
+  filename: string,
+  mimeType: string,
+  bytes: number,
+): string {
+  return `[Binary attachment: ${filename} | ${mimeType} | ${bytes} bytes]`;
+}
+
+/** Usado quando `extractPdfText` não consegue extrair nada do PDF. */
+export function unreadablePdfMarker(filename: string): string {
+  return `[PDF attachment with unreadable text: ${filename}]`;
+}

package/src/ai/ai.controller.ts

@@ -7,7 +7,9 @@ import { AiService } from './ai.service';
 import { ChatAgentDTO } from './dto/chat-agent.dto';
 import { ChatDTO } from './dto/chat.dto';
 import { CreateAgentDTO } from './dto/create-agent.dto';
+import { RichtextEditHtmlDTO } from './dto/richtext-edit-html.dto';
 import { UpdateAgentDTO } from './dto/update-agent.dto';
+import { RichtextAiService } from './richtext-ai.service';
 
 @Role()
 @Controller('ai')
@@ -15,6 +17,8 @@ export class AiController {
   constructor(
     @Inject(forwardRef(() => AiService))
     private readonly aiService: AiService,
+    @Inject(forwardRef(() => RichtextAiService))
+    private readonly richtextAiService: RichtextAiService,
   ) {}
 
   @Post('chat')
@@ -65,4 +69,9 @@ export class AiController {
   ) {
     return this.aiService.chatWithAgent(slug, data, file);
   }
+
+  @Post('richtext/edit-html')
+  async editRichtextHtml(@Body() data: RichtextEditHtmlDTO) {
+    return this.richtextAiService.editHtml(data);
+  }
 }

package/src/ai/ai.module.ts

@@ -5,6 +5,7 @@ import { FileModule } from '../file/file.module';
 import { SettingModule } from '../setting/setting.module';
 import { AiController } from './ai.controller';
 import { AiService } from './ai.service';
+import { RichtextAiService } from './richtext-ai.service';
 
 @Module({
   imports: [
@@ -14,7 +15,7 @@ import { AiService } from './ai.service';
     forwardRef(() => AiInstructionModule),
   ],
   controllers: [AiController],
-  providers: [AiService],
-  exports: [AiService],
+  providers: [AiService, RichtextAiService],
+  exports: [AiService, RichtextAiService],
 })
 export class AiModule {}

package/src/ai/ai.prompts.ts

@@ -0,0 +1,38 @@
+import { registerAiPrompts } from '../ai-instruction/ai-prompt-registry';
+
+/**
+ * Core AI prompts.
+ *
+ * Deliberately NOT moved here: the attachment wrappers (`[Attached file: …]`,
+ * `[Binary attachment: …]`, `[PDF attachment with unreadable text: …]`). Those are
+ * mechanical framing that must stay in lockstep with `isTextMime`/`isPdfMime`/
+ * `buildOpenAiUserContent` on the parsing side — editable prose they are not.
+ * They now live in `ai-attachment.fragments.ts` (single copy, in code), covered
+ * byte for byte by `ai-attachment.fragments.spec.ts`.
+ */
+
+export const CORE_AI_PROMPT_SLUGS = {
+  agentDefaultInstructions: 'task.core.ai-agent.default-instructions.system',
+} as const;
+
+/** Used when an agent is created without explicit instructions. */
+export const AGENT_DEFAULT_INSTRUCTIONS_PROMPT =
+  'You are the assistant identified by slug {{slug}}.';
+
+registerAiPrompts([
+  {
+    slug: CORE_AI_PROMPT_SLUGS.agentDefaultInstructions,
+    name: 'AI agent — instruções padrão',
+    moduleSlug: 'core',
+    locale: 'en',
+    fallback: AGENT_DEFAULT_INSTRUCTIONS_PROMPT,
+    variables: {
+      slug: {
+        type: 'string',
+        required: true,
+        description: 'Slug do agente sendo criado.',
+        sample: 'finance-payable-extractor',
+      },
+    },
+  },
+]);