AssistentIA — Especificação Técnica Pública (Alto Nível)

> Documento público para dar previsibilidade técnica. Nomes de entidades/API são indicativos e podem evoluir mantendo compatibilidade.

1) Domínios e entidades (resumo)

Tenants: identificação, chaves (pública/secret), plano, allowed origins, quotas, status de billing.
Usuários (por tenant): e-mail, nome, papéis (owner/admin/agent), confirmação e habilitação.
Fontes (sources): tipos url|faq|file, título, URL/caminho, status, configuração de crawl, timestamps.
Chunks: unidades indexáveis com lang, url, texto e vetor (espelhado/derivado).
Conversas/Mensagens: sessão, UA/IP/locale, contadores, conteúdo, metadados de modelo e citações.
Handoff Queue: fila para transferência a humano, com razão, confiança, payload e assignee.
Webhooks: eventos, URL e segredo, status.
Uso Diário: métricas de consumo (mensagens, tokens, custo estimado).
Pagamentos (quando aplicável): sessão, plano, preapproval id, status.

Suporta fontes url, faq e file.
Deduplicação por hash de conteúdo e atualização incremental.
Limpeza/sanitização do conteúdo para indexação semântica.
Remoção de chunks obsoletos por tenant_id + source_id + content_hash anterior.
Governança pelo painel: Pausar/Reindexar/Excluir.

Armazena vetores dos chunks com payload mínimo (tenant_id, source_id, content_hash, url, text, type, lang).
Seleção e combinação de trechos relevantes em tempo de resposta.
Camada relacional mantém espelho/auditoria dos chunks.

Recebe consulta com contexto do tenant.
Recupera candidatos semânticos; aplica política de resposta e formata citações (quando habilitado).
Persiste conversa/mensagens para auditoria/analytics.

Regra de envio à fila por confiança baixa, intenção específica ou palavra‑chave.
Operação da fila: open|claimed|closed com assignee e timestamps.
Integração via webhook/eventos.

Eventos indicativos: conversation.created, message.created, handoff.opened, usage.daily, etc.
Autenticação por segredo por tenant.