https://static.wixstatic.com/media/bb27e0_2688501ec3c84180977a93955137bd03~mv2.png/v1/fill/w_55,h_55,al_c,q_85,usm_0.66_1.00_0.01,enc_auto/iconx.png

Menthor: Inteligência de Dados

O Menthor é o assistente inteligente da Maximiza IA projetado para a exploração e análise de dados. Ele combina o poder dos modelos de linguagem (LLMs) com acesso direto a bases de dados e documentos, transformando perguntas em linguagem natural em insights técnicos, consultas SQL e visualizações.

Nota

Esta documentação cobre a versão |last_update| da API Menthor+MIA.

Capacidades do Assistente

O sistema está estruturado em três pilares principais:

Análise de Dados Estruturados (Menthor DB): Capacidade de interpretar esquemas de banco de dados, gerar consultas SQL dinâmicas e extrair estatísticas diretamente de tabelas.
Busca Semântica e Documental (Menthor Files): Exploração de arquivos e documentos através de Vector Stores, permitindo encontrar conteúdos e contextos específicos que não estão em bancos de dados tradicionais.
Inteligência Analítica: Geração de gráficos, visualizações de dados e sugestões proativas baseadas no comportamento do usuário e nos dados analisados.

Exemplos de Fluxos Suportados

Para guiar o desenvolvimento e testes, o assistente responde a comandos como:

Consultas diretas: «Liste os registros da tabela de vendas.»
Visualização: «Crie um gráfico com os dados da coluna de faturamento.»
Busca de Contexto: «O que os documentos dizem sobre a política de privacidade?»

—

Guia de Desenvolvimento:

Referência da API: Menthor

Abaixo estão detalhados os endpoints gerados a partir da especificação OpenAPI. Eles estão organizados por tags conforme as responsabilidades do sistema.

Test

GET /ping

Ping

Health Check (Disponibilidade)

Verificação simplificada para monitoramento de infraestrutura.

Público: Não exige cabeçalhos de autenticação.
Uso: Load Balancers (AWS/GCP), Uptime Kuma ou scripts de heartbeat.
Custo: Operação de memória, sem latência de rede externa.

—

Return:: String estática «pong».
Rtype:: str

Example request:

GET /ping HTTP/1.1
Host: example.com

Status Codes:

200 OK –
Servidor online e operacional.

Example response:
```
HTTP/1.1 200 OK
Content-Type: text/plain

pong
```

GET /credentials

Credentials

Validação de Handshake (Segurança)

Verifica se a chave de API configurada no cliente é aceita pelo servidor antes de iniciar fluxos de dados.

Quando usar:

No Startup da sua aplicação cliente.
Para depurar erros de permissão sem consumir cota de tokens/LLM.
Testar conectividade HTTPS e certificados.

Segurança: Requer o header X-API-Key preenchido corretamente.

—

Return:: Confirmação de acesso «ok».
Rtype:: str
Raises HTTPException:: 401 (Não autorizado).

Example request:

GET /credentials HTTP/1.1
Host: example.com

Status Codes:

200 OK –
Credenciais validadas com sucesso.

Example response:
```
HTTP/1.1 200 OK
Content-Type: text/plain

ok
```
401 Unauthorized – X-API-Key ausente ou inválida.
403 Forbidden – Token sem permissão para este recurso.

GET /llm_health_check

Llm Health Check

Health Check de Inteligência (LLM)

Realiza uma chamada de baixa latência para a API da OpenAI para validar o pipeline completo de inferência.

O que este teste valida:

Conectividade: Se o servidor consegue alcançar os endpoints da OpenAI.
Autenticação: Se a OPENAI_API_KEY configurada é válida e tem permissões.
Cota: Se há créditos disponíveis para processamento.
Integridade: Se o modelo retorna a string exata esperada (evitando saídas corrompidas).

Tratamento de Erros Granular:

Este endpoint mapeia erros específicos da biblioteca OpenAI para códigos HTTP correspondentes (401, 403, 429, 503), facilitando o diagnóstico de falhas na infraestrutura de IA.

—

Return:: Objeto com o status do modelo e a resposta curta gerada.
Rtype:: dict
Raises HTTPException:: Retorna códigos variados baseados na falha da API externa.

Example request:

GET /llm_health_check HTTP/1.1
Host: example.com

Status Codes:

200 OK –

LLM operacional e respondendo corretamente.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "ok",
    "model": "gpt-5-nano",
    "response": "tudo ok"
}

401 Unauthorized – Problema de autenticação (API key inválida).
403 Forbidden – Permissões insuficientes.
404 Not Found – Recurso/modelo não encontrado.
409 Conflict – Conflito (ex: recurso em uso).
429 Too Many Requests – Limite de requisições / cota excedida.
503 Service Unavailable – Serviço indisponível / sobrecarregado / timeout.
500 Internal Server Error – Erro interno inesperado.

GET /interaction_health_check

Interaction Health Check

Monitoramento de Fluxo de Conversa (Chat Health)

Retorna o status de sucesso ou erro da última tentativa de interação via chat.

Comportamento:

Estado em Memória: Este endpoint consulta uma flag interna (chat_error_flag) protegida por um lock de concorrência.
Status Dinâmico: O código HTTP retornado altera entre 200 (Sucesso) e 500 (Erro) para facilitar a integração com ferramentas de alerta.
Rastreabilidade: Inclui o timestamp da última interação para validar se o monitoramento está lendo dados atualizados.

Quando usar:

Monitorar se o modelo está gerando erros sistemáticos após atualizações de banco de dados.
Criar alertas de «Parada de Serviço» baseados na experiência do usuário final.

—

Return:: JSON contendo o status («OK» ou «ERROR») e o horário da última atividade.
Rtype:: JSONResponse

Example request:

GET /interaction_health_check HTTP/1.1
Host: example.com

Status Codes:

200 OK –

A última interação de chat foi processada com sucesso.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "OK",
    "last_interaction_time": "2026-02-26T10:00:00Z"
}

500 Internal Server Error –

Falha na última interação (Erro Lógico ou de Processamento).

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "status": "ERROR",
    "last_interaction_time": "2026-02-26T10:05:00Z"
}

User

GET /list_users

List Users

Listagem Geral de Usuários

Recupera todos os perfis registrados na base de dados, filtrando apenas os campos essenciais de visualização.

Campos Retornados:

Role: Define o nível de acesso do usuário (ex: admin, user).
Is_Active: Indica se o usuário possui permissão atual para interagir com o sistema.
Payload: Objeto JSON dinâmico que dados específicos de cada projeto.

Processamento Interno:

O sistema converte a base persistida (DataFrame) em uma lista de objetos compatíveis com o schema UserOut, garantindo que dados sensíveis não mapeados sejam omitidos na resposta.

—

Return:: Lista de objetos de usuário.
Rtype:: List[UserOut]

Example request:

GET /list_users HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Lista de usuários recuperada com sucesso.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 1,
        "name": "Jo\u00e3o Silva",
        "email": "joao@empresa.com",
        "phone": "5511999999999",
        "role": "admin",
        "is_active": true,
        "payload": {
            "id_context_active": "67d3686f422c4f1568a7c844"
        }
    }
]

500 Internal Server Error – Erro ao processar a base de dados de usuários.

POST /add_user

Add User

Gestão Unificada de Usuários (Upsert)

Realiza o cadastro ou a atualização inteligente de um perfil de usuário na base de dados.

Lógica de Processamento:

Validação de Telefone: O número passa por normalização automática (removendo caracteres especiais e validando DDI/DDD).
Idempotência: Se o usuário já existir e os dados enviados (Nome, Telefone e Payload) forem rigorosamente iguais aos atuais, o sistema não realiza escrita, apenas retorna o perfil existente.
Atualização (Update): Caso o e-mail exista mas algum dado tenha mudado, o cadastro é atualizado preservando o histórico.
Criação (Insert): Caso o e-mail seja inédito, um novo perfil é criado com configurações padrão (Role: user, Quota: 999).

—

Parameters:

user – Objeto UserCreate contendo name, email, phone e payload opcional.

Return:

Objeto UserOut com o status da operação na chave “message”.

Raises HTTPException:

401 (Telefone inválido), 500 (Falha de persistência).

Example request:

POST /add_user HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "email": "name@example.com",
    "phone": "string",
    "password": "string",
    "payload": {}
}

Status Codes:

200 OK –

Operação realizada com sucesso (Criação, Atualização ou Identificação de dados idênticos).

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "name": "Douglas Maximiza",
    "email": "douglas@maximiza.ai",
    "phone": "+5511999999999",
    "role": "user",
    "is_active": true,
    "payload": {
        "id_context_active": "67d3686f422c4f1568a7c844"
    },
    "message": "Usu\u00e1rio criado com sucesso."
}

401 Unauthorized –

Falha na validação do telefone ou Token inválido.

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "Autentica\u00e7\u00e3o falhou para telefone inv\u00e1lido: formato incorreto."
}

500 Internal Server Error – Erro interno ao persistir dados no UserManager.

422 Unprocessable Entity –

Validation Error

Example response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

DELETE /delete_user/{identifier}

Delete User

Remoção Definitiva de Usuário

Exclui permanentemente um registro de usuário da base de dados.

O que este endpoint faz:

Localização: Busca o registro baseado no identifier (e-mail ou número de telefone).
Expurgo: Remove a linha correspondente na persistência.
Desvinculação: Interrompe imediatamente o acesso do usuário a qualquer contexto via API.

Cuidado: Esta operação é irreversível. Uma vez deletado, o histórico de interações vinculadas ao e-mail deste usuário poderá ficar órfão ou inacessível via endpoints de histórico.

—

Parameters:

identifier (string) – E-mail ou número de telefone do usuário a ser removido.
identifier

Return:

Mensagem de confirmação de exclusão.

Rtype:

JSONResponse

Raises HTTPException:

404 (Não encontrado), 500 (Erro de escrita/persistência).

Status Codes:

200 OK –

Usuário removido com sucesso.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "Usu\u00e1rio joao@exemplo.com removido com sucesso."
}

404 Not Found –

Usuário não encontrado.

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "detail": "Usu\u00e1rio com o identificador '123' n\u00e3o existe."
}

500 Internal Server Error – Erro interno ao acessar o sistema de arquivos ou banco de usuários.

422 Unprocessable Entity –

Validation Error

Example response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

POST /add_user_getter

Add User Getter

Realiza o provisionamento de usuários e a atualização da base global de contextos.

Operações Realizadas:

Sync Global: Extrai as chaves de id_context_enabled e as registra na lista de contextos do sistema.
Upsert de Usuário: * Se o e-mail não existe: Cria novo registro com role: user e cotas padrão.
- Se o e-mail existe: Sobrescreve name, phone e payload caso haja divergência nos dados enviados.
Integração Vector Store: Associa o id_context_active aos storages correspondentes via get_vector_stores_from_context.

Regras de Negócio:

Telefone: Aceita padrão E.164 (+55…). Para números brasileiros, aceita sem “+” ou sem código de país (ex: 44993221991). Erro 401 se inválido.
Payload: O sistema converte o dicionário de contextos em uma lista de IDs para armazenamento interno.
Senha: Novos usuários recebem a senha padrão «pass».

—

Parameters:

user (UserCreateGetter) – Objeto contendo os dados de criação/atualização.

Return:

Dados públicos do usuário e logs de feedback da operação.

Rtype:

UserOut

Raises HTTPException:

401 (Telefone inválido) ou 500 (Erro interno de processamento).

Example request:

POST /add_user_getter HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "email": "name@example.com",
    "phone": "string",
    "id_context_enabled": {},
    "id_context_active": "string",
    "response_tone": "friendly",
    "response_style": "concise",
    "proactivity_enabled": true
}

Status Codes:

200 OK –

Successful Response

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "name": "string",
    "email": "string",
    "phone": "string",
    "role": "admin",
    "is_active": true,
    "payload": {},
    "message": "string"
}

422 Unprocessable Entity –

Validation Error

Example response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

GET /user_history/{id_context}

Get Active Histories

Recuperação de Histórico Ativo por Contexto

Retorna todas as sessões de chat ativas vinculadas a um usuário e contexto, consolidando interações vindas de diferentes canais (WhatsApp, Web, etc.).

Estrutura de Retorno:

Consolidação: O campo total_messages indica o número de arquivos de sessão (canais distintos ou sessões resetadas) encontrados.
Origem (Origin): Identifica de onde veio a interação: whatsapp, web_email ou web_phone.
Conteúdo Bruto: O campo content preserva a integridade da conversa, incluindo metadados de sistema, chamadas de funções e avisos de limpeza de tokens.

Regras de Negócio:

Filtro de Contexto: Apenas históricos que correspondem ao id_context ativo e ao e-mail do usuário são retornados.
Sessões Ativas: Históricos arquivados (limpos após atualização de metadados do DB) não são listados aqui.
Nomenclatura de Arquivos: O sistema utiliza uma convenção interna (user#origem-contexto.json) para mapear as referências de arquivos retornadas em file_ref.

—

Parameters:

id_context (string) – ID do contexto para o qual o histórico deve ser recuperado (na rota).
user_email (str) – E-mail do usuário para filtragem das sessões (query string).
id_context

Return:

Objeto consolidado contendo metadados e a lista de sessões de chat.

Rtype:

dict

Raises HTTPException:

404 (Nenhum histórico encontrado para este par usuário/contexto), 500 (Erro ao ler arquivos de log).

Query Parameters:

user_email (string) – (Required)

Example request:

GET /user_history/{id_context}?user_email=string HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Históricos encontrados e retornados.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "history": [
        {
            "content": [
                {
                    "content": "Ol\u00e1, qual o estoque?",
                    "role": "user"
                },
                {
                    "content": "O estoque atual \u00e9 de 50 unidades.",
                    "role": "assistant"
                }
            ],
            "file_ref": "contato@maximiza.ai#wpp-vendas_farma.json",
            "origin": "whatsapp"
        }
    ],
    "id_context": "vendas_farma",
    "total_messages": 1,
    "user_email": "contato@maximiza.ai"
}

404 Not Found – Nenhum histórico encontrado.
500 Internal Server Error – Erro ao processar os arquivos de histórico.

422 Unprocessable Entity –

Validation Error

Example response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Streaming

POST /token_streaming

Token Streaming

Motor de Inferência por Tokens (SSE)

Endpoint universal para consumo de modelos de IA com suporte a respostas complexas (texto, gráficos e arquivos). Entrega o conteúdo de forma granular (token por token), ideal para interfaces de chat fluidas.

Flexibilidade de Carga (Payload)

O campo payload é dinâmico e comporta lógicas específicas por aplicação:

Aplicações Gerais: Podem enviar o payload vazio ou com metadados de sessão.
Ecossistema Menthor: Utiliza o subcampo id_context para direcionar a busca em bases de conhecimento específicas.

Protocolo de Resposta (EventSource)

Os dados são entregues no formato data: {"tipo": "...", "data": "..."}:

msg: Fluxo de texto (tokens/pedaços de palavras).
dynamic_chart: Gráficos interativos (JSON).
image / pdf / vcard: Arquivos binários codificados em Base64.

Exemplo Universal (cURL):

curl -X POST http://localhost:8000/token_streaming -H "Content-Type: application/json" -d '{"user_prompt": "Olá", "section_id": "sessao_123", "email": "user@provider.com", "phone": "554499999999"}'

Example request:

POST /token_streaming HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "user_prompt": "string",
    "email": "string",
    "phone": "string",
    "id_chat": "string",
    "payload": {
        "id_context": "string"
    }
}

Status Codes:

200 OK –

Successful Response

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{}

422 Unprocessable Entity –

Validation Error

Example response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

POST /sentence_streaming

Sentence Streaming

Motor de Inferência por Sentenças (SSE)

Endpoint universal para consumo de modelos de IA com suporte a respostas complexas (texto, gráficos e arquivos). Entrega o conteúdo agrupado em frases completas, ideal para integrações de voz (TTS) ou leitura assistida.

Flexibilidade de Carga (Payload)

O campo payload é dinâmico e comporta lógicas específicas por aplicação:

Aplicações Gerais: Podem enviar o payload vazio ou com metadados de sessão.
Ecossistema Menthor: Utiliza o subcampo id_context para direcionar a busca em bases de conhecimento específicas.

Protocolo de Resposta (EventSource)

Os dados são entregues no formato data: {"tipo": "...", "data": "..."}:

msg: Fluxo de texto (frases completas pontuadas).
dynamic_chart: Gráficos interativos (JSON).
image / pdf / vcard: Arquivos binários codificados em Base64.

Exemplo Universal (cURL):

curl -X POST http://localhost:8000/sentence_streaming -H "Content-Type: application/json" -d '{"user_prompt": "Olá", "section_id": "sessao_123", "email": "user@provider.com", "phone": "554499999999"}'

Example request:

POST /sentence_streaming HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "user_prompt": "string",
    "email": "string",
    "phone": "string",
    "id_chat": "string",
    "payload": {
        "id_context": "string"
    }
}

Status Codes:

200 OK –

Successful Response

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{}

422 Unprocessable Entity –

Validation Error

Example response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

POST /block_streaming

Block Streaming

Motor de Inferência por Blocos (SSE / WhatsApp)

Endpoint universal para consumo de modelos de IA com suporte a respostas complexas e tratamento de canal. Entrega o conteúdo agrupado em mensagens completas, ideal para integrações com WhatsApp e ferramentas de automação.

Especialidade WhatsApp (WPP)

Se o section_id iniciar com o prefixo wpp-, o motor ativa o modo de compatibilidade:

Formatação: Ajusta automaticamente o texto para o padrão de Markdown do WhatsApp.
Conversão de Mídia: Converte dynamic_chart (interativo) em image (estático PNG) de forma transparente.

Flexibilidade de Carga (Payload)

O campo payload é dinâmico e comporta lógicas específicas por aplicação:

Aplicações Gerais: Podem enviar o payload vazio ou com metadados de sessão.
Ecossistema Menthor: Utiliza o subcampo id_context para direcionar a busca em bases de conhecimento específicas.

Protocolo de Resposta (EventSource)

Os dados são entregues no formato data: {"tipo": "...", "data": "..."}:

msg: Blocos de texto processados e formatados para o canal.
dynamic_chart: Gráficos interativos (JSON) - apenas para canais não-WPP.
image / pdf / vcard: Arquivos binários codificados em Base64.

Exemplo Universal (cURL):

curl -X POST http://localhost:8000/block_streaming -H "Content-Type: application/json" -d '{"user_prompt": "Olá", "section_id": "main-chat", "email": "user@provider.com", "phone": "554499999999"}'

Example request:

POST /block_streaming HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "user_prompt": "string",
    "email": "string",
    "phone": "string",
    "id_chat": "string",
    "payload": {
        "id_context": "string"
    }
}

Status Codes:

200 OK –

Successful Response

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{}

422 Unprocessable Entity –

Validation Error

Example response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

POST /send_prompt_wpp

Send Direct Message

Envio Direto de Mensagem via WhatsApp

Processa uma solicitação de chat, gera uma resposta através do motor de IA e realiza o envio imediato para o destinatário no WhatsApp.

Fluxo de Processamento:

Sanitização: O campo phone é limpo para conter apenas dígitos, garantindo compatibilidade com o protocolo internacional.
Injeção de Contexto: O número de telefone é inserido no dicionário payload, vinculando a execução da IA ao contato destino.
Geração e Envio: O motor MIA processa o prompt e a resposta resultante é enviada via gateway de mensageria para o WhatsApp.

Regras de Negócio:

Campos Obrigatórios: A ausência do telefone no corpo da requisição interrompe o processo com erro 400.
Dependências Externas: Falhas de comunicação com a IA ou com o serviço de WhatsApp são reportadas com o código 502.
Retorno Simplificado: A resposta confirma o sucesso da operação e fornece um recorte (preview) do texto que foi enviado ao usuário.

—

Parameters:

request (MessageRequest) – Objeto MessageRequest contendo o prompt e o telefone do destinatário.

Return:

Status de sucesso, contato sanitizado e preview da mensagem.

Rtype:

dict

Raises HTTPException:

400 (Telefone ausente), 502 (Erro em serviços externos).

Example request:

POST /send_prompt_wpp HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "user_prompt": "string",
    "email": "string",
    "phone": "string",
    "id_chat": "string",
    "payload": {
        "id_context": "string"
    }
}

Status Codes:

200 OK –

Mensagem processada e enviada com sucesso.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "sucesso",
    "contato": "5543..."
}

400 Bad Request – Dados de entrada inválidos (falta telefone).
502 Bad Gateway – Falha na comunicação com serviços externos (IA ou WhatsApp).

422 Unprocessable Entity –

Validation Error

Example response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Utils

POST /history_save

History Save

Example request:

POST /history_save HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "group_id": "string",
    "group_name": "string",
    "users": [
        "string"
    ],
    "create_at": "string",
    "msgs": [
        {
            "tipo": "string",
            "data": "string",
            "sender": "string",
            "phone": "string",
            "timestamp": "string"
        }
    ]
}

Status Codes:

200 OK –

Successful Response

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{}

422 Unprocessable Entity –

Validation Error

Example response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Databases

POST /databases/create_description_db

Create Description Db

Geração Automática de Metadados para Menthor DB

Este endpoint inicia o processo de análise semântica de tabelas para gerar descrições e tipos de dados automaticamente. O processamento é realizado de forma assíncrona.

Fluxo de Operação:

Validação: Verifica se a lista de tabelas (files) não está vazia.
Agendamento: Adiciona a tarefa process_context_and_notify à fila de execução em segundo plano.
Resposta Imediata: Retorna status 202 confirmando o recebimento.
Processamento Offline: A IA analisa cada tabela, identifica colunas, tipos de dados e gera descrições contextuais.
Callback/Notificação: Ao finalizar todas as tabelas, o sistema envia um POST para a API externa com o payload completo (incluindo descrições e colunas).

Regras de Negócio:

Idempotência de Resposta: O retorno imediato lista apenas os nomes das tabelas para conferência.
Rate Limiting: Este endpoint está sujeito ao limitador de processamento (PROCESSING).
Notificação Única: Mesmo que o contexto contenha múltiplos arquivos, apenas uma notificação consolidada é enviada ao final do processo.

—

Parameters:

contexts (ContextSimplifiedInputDB) – Objeto contendo o ID do contexto e a lista de tabelas para processar.
background_tasks – Gerenciador de tarefas do FastAPI (gerido internamente).

Return:

Confirmação de recebimento e lista de tabelas agendadas.

Rtype:

DocumentResponse

Raises HTTPException:

404 (Nenhuma tabela fornecida) ou 500 (Erro no agendamento).

Example request:

POST /databases/create_description_db HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "id_context": "string",
    "files": [
        {
            "document_key": "string",
            "status": "string",
            "table_name": "string",
            "description": "string",
            "columns": [
                {
                    "column_name": "string",
                    "column_data_type": "string",
                    "column_description": "string"
                }
            ]
        }
    ]
}

Status Codes:

202 Accepted –

Contexto aceito. A geração de metadados das tabelas foi agendada para processamento em segundo plano.

Example response:

HTTP/1.1 202 Accepted
Content-Type: application/json

{
    "status": "Contexto recebido e sendo processado.",
    "details": {
        "tabelas": [
            "ctx_vendas_2023_xlsx",
            "ctx_clientes_ouro_csv"
        ]
    }
}

404 Not Found – Nenhuma tabela recebida no contexto.
500 Internal Server Error – Erro ao processar contexto.

422 Unprocessable Entity –

Validation Error

Example response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

POST /databases/receive_documents_db

Receive Documents Db

Sincronização e Persistência de Metadados (Menthor DB)

Recebe metadados estruturados, realiza o armazenamento local para uso do motor de IA e notifica sistemas externos.

Fluxo de Operação:

Verificação de Alteração: O sistema compara os dados recebidos com a versão local (via lock de arquivo). Se forem idênticos, retorna 200 OK e encerra.
Persistência: Se houver mudanças, salva o novo estado em disco (.json).
Reset de Memória: Executa archive_interaction_history para garantir que a IA não use contextos obsoletos nas próximas interações.
Callback Assíncrono: Agenda uma tarefa em segundo plano para notificar a API externa sobre a atualização bem-sucedida.

Regras de Negócio:

Geração de Contexto: Os dados salvos aqui são a fonte primária para a IA entender a estrutura das tabelas durante o chat com o usuário.
Integridade: O uso de save_json_with_lock evita corrupção de dados em escritas simultâneas.
Histórico: O arquivamento do histórico de interação é obrigatório a cada nova carga de metadados para manter a consistência das respostas da IA.

—

Parameters:

contexts (ContextSimplifiedInputDB) – Objeto contendo o ID do contexto e a estrutura completa de metadados (tabelas/colunas).
background_tasks – Gerenciador de tarefas assíncronas do FastAPI.

Return:

Status da operação (Criado ou Já Existente) e lista de tabelas processadas.

Rtype:

Union[DocumentResponse, SimpleStatusResponse]

Raises HTTPException:

404 (Contexto vazio), 500 (Erro de escrita em disco ou permissão).

Example request:

POST /databases/receive_documents_db HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "id_context": "string",
    "files": [
        {
            "document_key": "string",
            "status": "string",
            "table_name": "string",
            "description": "string",
            "columns": [
                {
                    "column_name": "string",
                    "column_data_type": "string",
                    "column_description": "string"
                }
            ]
        }
    ]
}

Status Codes:

201 Created –

Novo contexto persistido com sucesso e histórico resetado.

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "status": "Contexto recebido e salvo com sucesso.",
    "details": {
        "tabelas": [
            "vendas_anual",
            "clientes_ativos"
        ]
    }
}

200 OK –

Idempotência detectada: O conteúdo enviado é idêntico ao já armazenado. Nenhuma ação foi realizada.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "Contexto recebido igual ao existente. Nada foi salvo."
}

404 Not Found – Nenhuma tabela recebida no contexto.
500 Internal Server Error – Erro interno ao salvar contexto.

422 Unprocessable Entity –

Validation Error

Example response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

POST /databases/evaluate-context-quality/{id_context}

Evaluate Context Quality Db

Avaliação de Qualidade de Dados e Metadados (Data Quality)

Realiza uma auditoria técnica e semântica em todas as tabelas vinculadas a um contexto específico. Este processo combina métricas estatísticas rígidas com análise qualitativa via IA.

Fluxo de Execução:

Extração de Schema: Recupera todas as definições de tabelas associadas ao id_context.
Processamento Paralelo: Dispara avaliações individuais para cada tabela simultaneamente usando asyncio.gather.
Métricas Técnicas: Calcula scores de completitude (completeness), unicidade (uniqueness) e aderência ao schema (schema adherence).
Análise Qualitativa (LLM): A IA avalia se as descrições e nomes de colunas são claros e úteis para a exploração de dados.
Consolidação: Reúne os relatórios de sucesso e falha em um objeto único de diagnóstico.

Regras de Negócio e Observações:

Performance: Por ser um endpoint que aguarda o retorno da LLM para múltiplas tarefas, o tempo de resposta pode variar conforme o número de tabelas no contexto.
Tolerância a Falhas: O endpoint não falha completamente se apenas uma tabela der erro. Ele retornará os sucessos em table_reports e os erros em failed_reports.
Erro 503: Retornado apenas se todas as tentativas de avaliação falharem (ex: queda da API da OpenAI ou erro crítico de conexão com o Banco).

—

Parameters:

id_context (string) – Identificador único do contexto (passado na URL).
id_context

Return:

Relatório detalhado com scores globais e sugestões de melhoria por tabela.

Rtype:

ContextQualityResponse

Raises HTTPException:

404 (Contexto não localizado), 503 (Falha total nos serviços externos), 500 (Erro de processamento).

Status Codes:

200 OK –

Avaliação concluída com sucesso.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "failed_reports": [],
    "id_context": "vendas_2024",
    "overall_score": 8.5,
    "summary": "Qualidade alta. Sugerida melhoria em 2 descri\u00e7\u00f5es.",
    "table_reports": [
        {
            "final_score": 9.0,
            "llm_evaluation": {
                "feedback": "Nomes claros, mas falta descri\u00e7\u00e3o na coluna SKU.",
                "score": 8.0,
                "suggestions": [
                    "Adicionar descri\u00e7\u00e3o para 'sku_id'"
                ]
            },
            "metric_scores": {
                "completeness": 10.0,
                "schema_adherence": 10.0,
                "uniqueness": 10.0
            },
            "summary": "Tabela excelente.",
            "table_name": "produtos"
        }
    ],
    "tables_evaluated": 10,
    "tables_failed": 0
}

404 Not Found – Contexto ou tabelas não encontradas.
503 Service Unavailable – Serviço externo (LLM ou Banco de Dados) indisponível.
500 Internal Server Error – Erro ao avaliar a qualidade dos dados do contexto.

422 Unprocessable Entity –

Validation Error

Example response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Files

POST /files/upload_files

Upload Files

Upload e Indexação de Documentos (Menthor Files)

Recebe metadados e URLs de documentos, realiza o download local, e orquestra a criação de uma Vector Store na OpenAI para busca semântica. O processamento pesado ocorre de forma assíncrona.

Fluxo de Operação (Imediato):

Validação de Limite: Verifica se o contexto já atingiu o limite de 2 Vector Stores ativas (Erro 400 se excedido).
Download em Lote: Tenta baixar todos os arquivos das URLs fornecidas.
Filtragem de Sucesso: Se pelo menos um arquivo for baixado, o processo segue. Se nenhum for baixado, retorna erro 502.
Agendamento: Os arquivos com sucesso são enviados para a tarefa processing_upload_files em background.

Fluxo de Processamento (Background):

Upload para OpenAI: Os arquivos são enviados para o storage da OpenAI.
Criação de Vector Store: Uma nova store é criada e os arquivos são vinculados via Batch.
Monitoramento: O sistema aguarda a indexação completa ou parcial.
Persistência: Salva localmente os IDs da Vector Store e os metadados dos arquivos indexados com sucesso.
Callback: Notifica a plataforma externa com o status final (Sucesso, Parcial ou Erro).

Regras de Negócio:

Limpeza Automática: Arquivos temporários são excluídos do servidor local imediatamente após o upload para a OpenAI.
Rollback Automático: Se ocorrer um erro crítico durante a criação da Vector Store, os arquivos já subidos para a OpenAI são deletados para evitar custos e lixo digital.
Sucesso Parcial: O sistema é resiliente. Se de 10 arquivos, 2 falharem no download ou na indexação, o processo termina como «PARTIAL_SUCCESS» informando os detalhes de cada um.

—

Parameters:

context (ContextSchema) – Objeto ContextSchema contendo IDs, nomes e lista de URLs dos arquivos.
background_tasks – Gerenciador de tarefas assíncronas do FastAPI.

Return:

Status de agendamento e lista detalhada de arquivos que falharam no download inicial.

Rtype:

DocumentResponse

Raises HTTPException:

400 (Limite de Vector Stores atingido), 502 (Falha total de download), 500 (Erro interno).

Example request:

POST /files/upload_files HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "id_context": "string",
    "vs_name": "string",
    "vs_description": "string",
    "vs_files": [
        {
            "_id": "string",
            "blobName": "string",
            "url": "https://example.com",
            "file_description": "string"
        }
    ]
}

Status Codes:

202 Accepted –

Arquivos recebidos e sendo processados.

Example response:

HTTP/1.1 202 Accepted
Content-Type: application/json

{
    "status": "Arquivos recebidos e processamento iniciado.",
    "details": {
        "document_keys_scheduled": [
            "doc_abc_123"
        ],
        "failed_count": 1,
        "failed_files": [
            {
                "document_key": "doc_xyz_456",
                "error": "404 Not Found"
            }
        ]
    }
}

400 Bad Request – Requisição inválida: limite de 2 vector stores atingido.
502 Bad Gateway – Falha ao baixar arquivos externos.
500 Internal Server Error – Erro ao processar upload de arquivos.

422 Unprocessable Entity –

Validation Error

Example response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

PATCH /files/update_files

Update Files

Sincronização Evolutiva de Vector Stores (Upsert)

Atualiza o conteúdo de uma Vector Store existente comparando o estado atual com o novo conjunto de arquivos enviado. Realiza a manutenção da base removendo arquivos obsoletos e adicionando novos.

Fluxo de Operação (Imediato):

Validação de Vínculo: Verifica se o id_context existe e se a vector_store_id informada pertence efetivamente a este contexto.
Análise de Diferença (Diff): Compara as document_key atuais com as recebidas para identificar o que deve ser deletado e o que deve ser baixado.
Idempotência: Se não houver novos arquivos para baixar nem arquivos para remover, retorna 200 OK.
Download de Incrementos: Realiza o download apenas dos arquivos que ainda não constam na Vector Store.
Agendamento: Dispara a tarefa processing_update_files para processamento assíncrono.

Fluxo de Processamento (Background):

Remoção na OpenAI: Desvincula e deleta os arquivos obsoletos tanto da Vector Store quanto do Storage da OpenAI.
Upload e Batch: Envia os novos arquivos e inicia um processo de atualização em lote (Batch) na Vector Store existente.
Monitoramento e Auditoria: Acompanha a indexação e verifica se algum arquivo novo falhou no processo.
Persistência de Metadados: Atualiza os registros locais com a nova composição de arquivos da Store.
Callback: Notifica a plataforma externa com o balanço final de adições, remoções e falhas.

Regras de Negócio:

Sincronização Baseada em Chave: A lógica utiliza a document_key (blobName) como identificador único. Alterar o conteúdo de um arquivo mantendo a mesma chave causará a substituição.
Resiliência de Remoção: Falhas ao deletar arquivos na OpenAI não interrompem a adição de novos, mas são reportadas como sucesso parcial no callback.
Rollback de Emergência: Se o processo de update falhar criticamente, novos arquivos subidos para o Storage são removidos para evitar inconsistência de faturamento.

—

Parameters:

update_data (ContextSchemaUpdate) – Objeto ContextSchemaUpdate com IDs de contexto/store e lista de arquivos.
background_tasks – Gerenciador de tarefas assíncronas do FastAPI.

Return:

Status da sincronização e resumo quantitativo de alterações.

Rtype:

DocumentResponse

Raises HTTPException:

400 (Store não vinculada), 404 (Contexto/Store inexistente), 502 (Erro no download de novos itens).

Example request:

PATCH /files/update_files HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "id_context": "string",
    "vector_store_id": "string",
    "vs_files": [
        {
            "_id": "string",
            "blobName": "string",
            "url": "https://example.com",
            "file_description": "string"
        }
    ]
}

Status Codes:

202 Accepted –

Sincronização iniciada: novos arquivos serão adicionados e os omitidos serão removidos.

Example response:

HTTP/1.1 202 Accepted
Content-Type: application/json

{
    "status": "Sincroniza\u00e7\u00e3o iniciada com sucesso.",
    "details": {
        "added_count": 2,
        "added_files": [
            "manual_v2.pdf",
            "tabela_precos.xlsx"
        ],
        "removed_count": 1,
        "removed_files": [
            "manual_v1.pdf"
        ],
        "failed_count": 0,
        "failed_files": []
    }
}

200 OK –

Sincronização concluída: nenhuma alteração foi necessária.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "Sincroniza\u00e7\u00e3o conclu\u00edda: Nenhuma altera\u00e7\u00e3o necess\u00e1ria.",
    "details": {
        "message": "Listagem de arquivos recebida igual a existente em vector store. Nada foi salvo"
    }
}

400 Bad Request – Requisição inválida: contexto sem vector stores associadas.
404 Not Found – Contexto ou vector store não encontrados ou vector store não pertence ao contexto.
502 Bad Gateway – Falha ao baixar novos arquivos externos.
500 Internal Server Error – Erro ao processar sincronização de arquivos.

422 Unprocessable Entity –

Validation Error

Example response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Context

GET /context/all

List All Contexts

Catálogo Global de Contextos

Recupera a lista de todos os contextos registrados no ecossistema Menthor, servindo como o dicionário mestre de IDs e descrições.

Funcionamento do Endpoint:

Acesso ao Registro Global: Lê o arquivo persistido id_context_list.json, que é alimentado automaticamente pelos processos de sincronização de usuários.
Mapeamento: Retorna um objeto onde as chaves são os IDs técnicos dos contextos e os valores são suas descrições amigáveis (labels).

Regras de Negócio:

Sincronização: Esta lista é atualizada toda vez que um novo contexto é introduzido via /add_user_getter.
Disponibilidade: Se o arquivo mestre ainda não foi criado (primeiro uso do sistema), o endpoint retornará 404.
Uso Típico: Ideal para popular componentes de interface como dropdowns, filtros e dashboards de administração.

—

Return:: Objeto contendo o dicionário global de contextos disponíveis.
Rtype:: ContextList
Raises HTTPException:: 404 (Arquivo de registro global não encontrado), 500 (Erro de leitura ou JSON inválido).

Example request:

GET /context/all HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Lista completa de todos os contextos disponíveis no sistema para Menthor.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id_context_list": [
        {
            "description": "Informa dados sobre vendas e cat\u00e1logo de produtos. ",
            "id_context": "68540ec0b3c2f21317421010",
            "vector_store_ids": [
                "vs_68540ec0b3c2f21317421010"
            ]
        },
        {
            "description": "Dados tabelados de opera\u00e7\u00e3o.",
            "id_context": "60980ac0b3g2k21398765452",
            "vector_store_ids": []
        }
    ]
}

404 Not Found – O arquivo com lista de contextos de Menthor não foi encontrado no servidor.
500 Internal Server Error – Erro interno ao ler ou processar o arquivo com lista de contextos de Menthor.

GET /context/{id_context}

Get Context Information

Consulta Detalhada de Metadados de Contexto

Realiza uma busca exaustiva por metadados associados a um ID de contexto, agregando informações de bases de dados (Menthor DB) e de arquivos/documentos (Menthor Files).

Fluxo de Agregação:

Busca Paralela: Executa simultaneamente a recuperação de metadados estruturados (DB) e metadados de arquivos (PDF/Vector Stores).
Tolerância a Falhas: Caso uma das fontes não exista (ex: o contexto só possui arquivos e não tabelas), o endpoint ainda retorna os dados da fonte disponível em vez de falhar.
Verificação de Integridade: Se os dados de documentos estiverem incompletos (ex: falha na sincronização do Vector Store), o endpoint sinaliza através do status HTTP 207.

Estados de Retorno:

200 OK: Informações recuperadas integralmente de pelo menos uma das fontes.
207 Multi-Status: O contexto foi localizado, porém os metadados de busca vetorial (Files Data) estão parciais ou inconsistentes.
404 Not Found: O ID informado não possui registros em nenhuma das bases locais.

—

Parameters:

id_context (string) – Identificador único do contexto a ser consultado (na URL).
id_context

Return:

Objeto consolidado contendo db_data (metadados de tabelas) e files_data (metadados de documentos).

Rtype:

FullContextResponse

Raises HTTPException:

404 (Nenhum metadado encontrado para o ID fornecido).

Example request:

GET /context/{id_context} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Contexto encontrado (DB ou Files ou DB + Files).

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "db_data": {
        "files": [
            {
                "columns": [
                    {
                        "column_data_type": "text",
                        "column_name": "Nome"
                    }
                ],
                "document_key": "1234",
                "table_name": "ctx_parana_com_executivos_xlsx"
            }
        ],
        "id_context": "68540ec0b3c2f21317421010"
    },
    "files_data": {
        "id_context": "68540ec0b3c2f21317421010",
        "is_partial": false,
        "vector_stores": [
            {
                "vector_store_id": "vs_68540ec0b3c2f21317421010",
                "vs_name": "catalogos_de_vendas"
            }
        ]
    },
    "id_context": "68540ec0b3c2f21317421010"
}

207 Multi Status – Contexto encontrado (Files ou DB + Files), mas com dados parciais de Vector Stores.
404 Not Found – Nenhum dado encontrado para este ID em nenhuma das bases.

422 Unprocessable Entity –

Validation Error

Example response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}