Doc Analyzer V4 - Batch Dialogue Analysis

Sistema de análise em lote de conversas usando Kysely e LLM. Permite extrair dados estruturados de diálogos, construir instruções a partir de linguagem natural e realizar análises em batch.


Build Instruction From Natural

Converte instruções em linguagem natural para JSON estruturado (schema + instruções refinadas).

Endpoint

POST /api/externalAPIs/public/docAnalyzer/buildInstructionFromNatural

Autenticação

Todas as requisições requerem autenticação através do middleware tolkyAuthMiddleware. Certifique-se de incluir o token Bearer no header Authorization.

Authorization: Bearer SEU_TOKEN_AQUI
Content-Type: application/json

Parâmetros

CampoTipoObrigatórioDescrição
instructionstringSimInstrução em linguagem natural
emailstringNãoEmail do gestor para validação e persistência do resultado. Se fornecido e válido, o resultado será salvo em arquivo
dialoguestring | ArrayNãoDiálogo de apoio. Pode ser string ou array de objetos {role, content}
contextDatastringNãoDados extras de contexto

Exemplo cURL

Request básico:

curl -X POST https://api.tolky.com/api/externalAPIs/public/docAnalyzer/buildInstructionFromNatural \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "Preciso capturar nome completo, idade e telefone do cliente. O email deve ser enviado para suporte@empresa.com",
    "email": "gestor@empresa.com",
    "contextData": "Sistema de cadastro de clientes"
  }'

Com Diálogo:

curl -X POST https://api.tolky.com/api/externalAPIs/public/docAnalyzer/buildInstructionFromNatural \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "Extrair dados do cliente",
    "email": "gestor@empresa.com",
    "dialogue": [
      { "role": "user", "content": "Preciso cadastrar nome, CPF e data de nascimento" },
      { "role": "assistant", "content": "Entendido. Esses campos serão obrigatórios?" },
      { "role": "user", "content": "Sim, todos obrigatórios" }
    ]
  }'

Resposta

{
  "data": {
    "jsonSchema": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "nome_completo": {
          "type": "string",
          "description": "Nome completo do cliente"
        },
        "idade": {
          "type": "integer",
          "description": "Idade do cliente em anos"
        },
        "telefone": {
          "type": "string",
          "description": "Número de telefone para contato"
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Endereço de email para contato ou notificação relacionado à instrução."
        }
      },
      "required": ["nome_completo", "idade", "telefone", "email"]
    },
    "generalInstructions": "Capture nome completo, idade e telefone do cliente conforme fornecido na conversa.",
    "fallbackInstructions": "",
    "targetEmail": "suporte@empresa.com",
    "rawCapture": {
      "expected_fields": [
        {
          "name": "nome_completo",
          "type": "string",
          "description": "Nome completo do cliente",
          "required": true
        },
        {
          "name": "idade",
          "type": "integer",
          "description": "Idade do cliente em anos",
          "required": true
        },
        {
          "name": "telefone",
          "type": "string",
          "description": "Número de telefone para contato",
          "required": true
        }
      ],
      "target_email": "suporte@empresa.com",
      "general_instruction": "Capture nome completo, idade e telefone do cliente conforme fornecido na conversa.",
      "requires_clarification": false
    }
  },
  "error": null
}

Analyze Dialogue (Análise Individual)

Analisa um único diálogo ou múltiplas conversas (via UUIDs) usando schema customizado.

Endpoint

POST /api/externalAPIs/public/docAnalyzer/analyzeDialogue

Autenticação

Todas as requisições requerem autenticação através do middleware tolkyAuthMiddleware. Certifique-se de incluir o token Bearer no header Authorization.

Authorization: Bearer SEU_TOKEN_AQUI
Content-Type: application/json

Parâmetros

CampoTipoObrigatórioDescrição
schemaObjectSim*JSON Schema para extração estruturada (*obrigatório se formCatalogId não fornecido)
formCatalogIdstringSim*ID do catálogo de formulário (*obrigatório se schema não fornecido). Quando fornecido, busca automaticamente o schema do catálogo e usa as instruções gerais se instructions estiver vazio
instructionsstringSimInstruções que guiam a análise. Se formCatalogId for fornecido e instructions estiver vazio, usa as instruções gerais do catálogo
dialoguestring | Array<Object> | Array<string>NãoDiálogo para análise. Pode ser:
- String: Texto simples direto
- Array de objetos: [{ role: 'user'|'assistant'|'system', content: 'texto' }]
- Array de UUIDs: Array de UUIDs de conversas (ex: ['550e8400-e29b-41d4-a716-446655440000']) - busca automática do banco
conversationIdstringNãoUUID da conversa (alternativa ao dialogue, busca automática do banco)
modelstringNãoModelo LLM (default: gpt-4o-mini)
providerstringNãoProvider do modelo (ex: ‘openai’, ‘cerebras’, ‘openrouter’, ‘google’)
recordFormDatabooleanNãoSe true, grava os dados extraídos no formFlow. Requer formCatalogId. Os dados serão salvos em form_items_values e form_responses
hostIdstringSim**ID do host (**obrigatório quando recordFormData é true ou quando formCatalogId é usado). Se conversationId for fornecido e hostId não, será buscado automaticamente da conversa
leadIdstringNãoID do lead (usado quando recordFormData é true). Se conversationId for fornecido e leadId não, será buscado automaticamente da conversa
avatarIdstringNãoID do avatar (usado quando recordFormData é true). Se conversationId for fornecido e avatarId não, será buscado automaticamente da conversa

Nota: Quando conversationId é fornecido junto com recordFormData=true, os campos hostId, leadId e avatarId são buscados automaticamente do banco de dados se não forem fornecidos explicitamente.

Compatibilidade: Os endpoints aceitam parâmetros tanto em camelCase quanto em snake_case:

  • formCatalogId / form_catalog_id
  • recordFormData / record_form_data
  • leadId / lead_id
  • avatarId / avatar_id

Exemplos cURL

Com texto direto:

curl -X POST https://api.tolky.com/api/externalAPIs/public/docAnalyzer/analyzeDialogue \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "type": "object",
      "properties": {
        "sentimento": { 
          "type": "string",
          "enum": ["positivo", "neutro", "negativo"]
        }
      }
    },
    "instructions": "Identifique o sentimento do cliente",
    "dialogue": "Estou muito satisfeito com o atendimento!"
  }'

Com array de UUIDs (busca automática do banco):

curl -X POST https://api.tolky.com/api/externalAPIs/public/docAnalyzer/analyzeDialogue \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "type": "object",
      "properties": {
        "tema_principal": { "type": "string" },
        "sentimento_geral": { 
          "type": "string",
          "enum": ["positivo", "neutro", "negativo"]
        }
      }
    },
    "instructions": "Analise todas as conversas e identifique o tema principal e sentimento geral",
    "dialogue": [
      "550e8400-e29b-41d4-a716-446655440000",
      "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
    ]
  }'

Com gravação automática no formFlow:

curl -X POST https://api.tolky.com/api/externalAPIs/public/docAnalyzer/analyzeDialogue \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "formCatalogId": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "Extraia informações do cliente",
    "conversationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "recordFormData": true
  }'

Nota: Quando formCatalogId é fornecido e instructions está vazio, o sistema usa automaticamente as instruções gerais do catálogo de formulário.

Resposta

{
  "data": {
    "tema_principal": "Suporte técnico",
    "sentimento_geral": "positivo"
  },
  "error": null,
  "rawResult": { },
  "metrics": {
    "elapsedMs": 2340
  },
  "formDataRecorded": {
    "success": true,
    "insertedCount": 2,
    "updatedCount": 0,
    "skippedCount": 0,
    "skipped": []
  }
}

Nota: O campo formDataRecorded só aparece quando recordFormData é true.


Batch Analyze Dialogue

Análise em lote de conversas usando schema customizado e instruções específicas.

Endpoint

POST /api/externalAPIs/public/docAnalyzer/batchAnalyzeDialogue

Autenticação

Todas as requisições requerem autenticação através do middleware tolkyAuthMiddleware. Certifique-se de incluir o token Bearer no header Authorization.

Authorization: Bearer SEU_TOKEN_AQUI
Content-Type: application/json

Tabela do Banco

Os resultados são armazenados na tabela conversations_reports:

CREATE TABLE IF NOT EXISTS public.conversations_reports (
  id BIGINT GENERATED BY DEFAULT AS IDENTITY NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
  conversation_id UUID NULL,
  analysis JSONB NULL,
  CONSTRAINT conversations_reports_pkey PRIMARY KEY (id),
  CONSTRAINT conversations_reports_conversation_id_fkey 
    FOREIGN KEY (conversation_id) 
    REFERENCES conversations (id) 
    ON DELETE CASCADE
) TABLESPACE pg_default;

-- Índices para melhor performance
CREATE INDEX IF NOT EXISTS idx_conversations_reports_conversation_id 
  ON public.conversations_reports(conversation_id);

CREATE INDEX IF NOT EXISTS idx_conversations_reports_created_at 
  ON public.conversations_reports(created_at DESC);

-- Índice GIN para consultas JSONB
CREATE INDEX IF NOT EXISTS idx_conversations_reports_analysis 
  ON public.conversations_reports USING GIN (analysis);

Parâmetros

CampoTipoObrigatórioDescrição
inputstringSimUUID ou query SELECT que retorna campo id
schemaObjectSimJSON Schema para extração
instructionsstringSimInstruções para análise
modelstringNãoModelo LLM (default: gpt-4o-mini)
intervalMsnumberNãoIntervalo entre processamentos (default: 200ms)

Notas:

  • As conversas são limitadas a aproximadamente 5000 caracteres (≈1666 tokens) para otimização de performance
  • A query SQL deve retornar registros com campo id (UUID)
  • Apenas queries SELECT são permitidas (validação de segurança)

Exemplos cURL

Por UUID:

curl -X POST https://api.tolky.com/api/externalAPIs/public/docAnalyzer/batchAnalyzeDialogue \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "550e8400-e29b-41d4-a716-446655440000",
    "schema": {
      "type": "object",
      "properties": {
        "sentimento": { 
          "type": "string",
          "enum": ["positivo", "neutro", "negativo"]
        }
      }
    },
    "instructions": "Identifique o sentimento do cliente",
    "intervalMs": 200
  }'

Com Query SQL:

curl -X POST https://api.tolky.com/api/externalAPIs/public/docAnalyzer/batchAnalyzeDialogue \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "SELECT id FROM conversations WHERE created_at > '\''2024-11-01'\'' LIMIT 10",
    "schema": {
      "type": "object",
      "properties": {
        "tema": { "type": "string" }
      }
    },
    "instructions": "Extraia o tema principal"
  }'

Resposta

{
  "data": {
    "total": 10,
    "processed": 10,
    "succeeded": 9,
    "failed": 1,
    "elapsedSeconds": 12.45,
    "results": [
      {
        "conversationId": "550e8400-e29b-41d4-a716-446655440000",
        "success": true,
        "metrics": { "elapsedMs": 2340 }
      }
    ]
  },
  "error": null
}

Uso Programático

Build Instruction From Natural

const { buildInstructionFromNatural } = require('@/app/v4/analyzer/instructionBuilder');

const result = await buildInstructionFromNatural({
  instruction: 'Preciso capturar nome, CPF e telefone do cliente',
  email: 'gestor@empresa.com',
  dialogue: [
    { role: 'user', content: 'Quero cadastrar clientes com dados completos' }
  ],
  contextData: 'Sistema de CRM',
  globalData, // opcional
  outputFilePath: './custom-output.txt' // opcional
});

// Resultado:
// result.jsonSchema - Schema JSON gerado
// result.generalInstructions - Instruções refinadas
// result.fallbackInstructions - Instruções de melhoria (se necessário)
// result.targetEmail - Email extraído da instrução
// result.rawCapture - Dados brutos capturados

Analyze Dialogue (Análise Individual)

A função analyzeDialogue() aceita três formatos diferentes para o parâmetro dialogue:

1. Array de mensagens (formato tradicional)

const { analyzeDialogue } = require('@/app/v4/analyzer/docAnalyzer');

const result = await analyzeDialogue({
  schema: {
    type: 'object',
    properties: {
      sentimento: { type: 'string', enum: ['positivo', 'negativo', 'neutro'] }
    }
  },
  instructions: 'Identifique o sentimento do cliente',
  dialogue: [
    { role: 'user', content: 'Estou muito satisfeito com o atendimento!' },
    { role: 'assistant', content: 'Que bom ouvir isso!' }
  ],
  model: 'gpt-4o-mini', // opcional
  globalData // opcional
});

2. String simples (texto direto)

const result = await analyzeDialogue({
  schema: { /* ... */ },
  instructions: 'Extraia informações do cliente',
  dialogue: 'Meu nome é João Silva e meu telefone é (11) 98765-4321',
  globalData
});

3. Array de UUIDs (busca automática do banco)

const result = await analyzeDialogue({
  schema: { /* ... */ },
  instructions: 'Analise o sentimento geral das conversas',
  dialogue: [
    '550e8400-e29b-41d4-a716-446655440000',
    '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
    '7c9e6679-7425-40de-944b-e07fc1f90ae7'
  ],
  globalData
});

// A função detecta automaticamente que são UUIDs,
// busca as conversas do banco (vw_conversations),
// e concatena todas as mensagens para análise

4. Com gravação automática no formFlow

const result = await analyzeDialogue({
  formCatalogId: '550e8400-e29b-41d4-a716-446655440000',
  instructions: 'Extraia informações do cliente',
  conversationId: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
  recordFormData: true,
  hostId: '7c9e6679-7425-40de-944b-e07fc1f90ae7',
  globalData
});

// Os dados extraídos serão automaticamente gravados em:
// - form_items_values (valores individuais)
// - form_responses (resumo do formulário)
// O resultado incluirá formDataRecorded com estatísticas da gravação

Retorno:

{
  data: Object|null,        // Dados extraídos conforme schema
  error: string|null,        // Mensagem de erro (se houver)
  rawResult: Object,         // Resposta bruta da OpenAI
  metrics: {
    elapsedMs: number        // Tempo de execução em ms
  },
  formDataRecorded?: {      // Apenas quando recordFormData é true
    success: boolean,
    insertedCount: number,  // Quantidade de valores inseridos
    updatedCount: number,    // Quantidade de valores atualizados
    skippedCount: number,   // Quantidade de valores ignorados
    skipped: Array<{         // Detalhes dos valores ignorados
      property: string,
      reason: string
    }>
  }
}

Batch Dialogue Analysis

const { batchDialogueAnalysis } = require('@/app/v4/analyzer/batchDialogueAnalysis');

// Por UUID
const result = await batchDialogueAnalysis({
  input: '550e8400-e29b-41d4-a716-446655440000',
  schema: {
    type: 'object',
    properties: {
      sentimento: { type: 'string', enum: ['positivo', 'negativo', 'neutro'] }
    }
  },
  instructions: 'Identifique o sentimento',
  intervalMs: 200
});

// Por Query
const result = await batchDialogueAnalysis({
  input: "SELECT id FROM conversations WHERE created_at > '2024-11-01' LIMIT 10",
  schema: { /* ... */ },
  instructions: 'Analise a conversa'
});

Consultar Resultados

-- Buscar análise
SELECT * FROM conversations_reports 
WHERE conversation_id = '550e8400-e29b-41d4-a716-446655440000';

-- Análises recentes
SELECT * FROM conversations_reports 
WHERE created_at > NOW() - INTERVAL '1 day'
ORDER BY created_at DESC;

-- Agregar por sentimento
SELECT 
  analysis->>'sentimento' as sentimento,
  COUNT(*) as quantidade
FROM conversations_reports
GROUP BY analysis->>'sentimento';

Segurança

  • ✅ Apenas queries SELECT permitidas (validação de comandos perigosos)
  • ✅ Validação de UUID
  • ✅ Autenticação via middleware (tolkyAuthMiddleware)
  • ✅ Logs de execução detalhados
  • ✅ Validação de parâmetros de entrada
  • ✅ Limite de caracteres em conversas para batch processing

Tecnologias

  • Kysely - Query builder type-safe
  • OpenAI/LLM - Análise via LLM (suporta múltiplos providers: OpenAI, Cerebras, OpenRouter, Google)
  • PostgreSQL - Storage JSONB com índices otimizados
  • Toon Format - Compressão de diálogos para otimização de tokens