Doc Analyzer V4
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.
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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
instruction | string | Sim | Instrução em linguagem natural |
email | string | Não | Email do gestor para validação e persistência do resultado. Se fornecido e válido, o resultado será salvo em arquivo |
dialogue | string | Array | Não | Diálogo de apoio. Pode ser string ou array de objetos {role, content} |
contextData | string | Não | Dados 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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
schema | Object | Sim* | JSON Schema para extração estruturada (*obrigatório se formCatalogId não fornecido) |
formCatalogId | string | Sim* | 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 |
instructions | string | Sim | Instruções que guiam a análise. Se formCatalogId for fornecido e instructions estiver vazio, usa as instruções gerais do catálogo |
dialogue | string | Array<Object> | Array<string> | Não | Diá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 |
conversationId | string | Não | UUID da conversa (alternativa ao dialogue, busca automática do banco) |
model | string | Não | Modelo LLM (default: gpt-4o-mini) |
provider | string | Não | Provider do modelo (ex: ‘openai’, ‘cerebras’, ‘openrouter’, ‘google’) |
recordFormData | boolean | Não | Se true, grava os dados extraídos no formFlow. Requer formCatalogId. Os dados serão salvos em form_items_values e form_responses |
hostId | string | Sim** | 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 |
leadId | string | Não | ID do lead (usado quando recordFormData é true). Se conversationId for fornecido e leadId não, será buscado automaticamente da conversa |
avatarId | string | Não | ID 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_idrecordFormData/record_form_dataleadId/lead_idavatarId/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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
input | string | Sim | UUID ou query SELECT que retorna campo id |
schema | Object | Sim | JSON Schema para extração |
instructions | string | Sim | Instruções para análise |
model | string | Não | Modelo LLM (default: gpt-4o-mini) |
intervalMs | number | Não | Intervalo 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