Configuração do Sistema (Variáveis e Constantes)

O ecossistema do Menthor gerencia seu comportamento através de dois arquivos principais de configuração: o arquivo de ambiente .env (na raiz) e o script técnico projects/menthor/menthor_config.py.

Variáveis de Ambiente (.env)

Configure as credenciais dinâmicas, chaves de terceiros e parâmetros de tráfego no arquivo na raiz do projeto:

Variável	Descrição	Exemplo
`OPENAI_MODEL`	Modelo padrão utilizado para as inferências gerais de chat.	`"gpt-4o"`
`OPENAI_MODEL_SMALL`	Modelo leve utilizado especificamente na rota `llm_health_check`.	`"gpt-4o-mini"`
`OPENAI_MODEL_LIST`	Lista de modelos homologados e permitidos pelo sistema.	`["gpt-4o", "gpt-4o-mini"]`
`AI_PROVIDER`	Provedor de Inteligência Artificial ativo no sistema.	`"openai"` ou `"azure"`
`API_KEY`	Token de segurança exigido no header `X-API-KEY`.	`"0..."`
`CHAINLIT_AUTH_SECRET`	Chave secreta de autenticação para a interface Chainlit.	`"y...."`
`WPP_AUTH_SECRET`	Chave secreta de autenticação para as integrações de WhatsApp.	`"633...."`
`OPENAI_API_KEY_MENTHOR`	Chave oficial do Menthor para acesso à API da OpenAI (Maximiza).	`"sk-..."`
`AZURE_OPENAI_API_KEY_MENTHOR`	Chave oficial do Menthor para acesso à API da Azure OpenAI (Getter).	`"Ci....."`
`ENDPOINT_AZURE_MENTHOR`	URL do endpoint base para as chamadas da API da Azure OpenAI (Getter).	`"https://.../openai/v1/"`
`ENABLE_RATE_LIMITER`	Chave mestra que ativa ou desativa os limites de uso.	`True`
`RATE_LIMITS_CONFIG`	Dicionário JSON com as quotas de requisição por perfil.	(Ver seção abaixo)
`REDIS_URL`	URL de conexão com a instância do Redis para persistência de sessões e códigos OTP.	`"redis://redis:6379/0"`
`SMTP_HOST`	Host do servidor SMTP para envio de códigos de verificação OTP.	`"smtp.gmail.com"`
`SMTP_PORT`	Porta de conexão do servidor SMTP (587 para TLS ou 465 para SSL).	`587`
`SMTP_USER`	E-mail remetente autenticado para disparo das mensagens.	`"seu-email@gmail.com"`
`SMTP_PASSWORD`	Senha de aplicativo (App Password) gerada no provedor de e-mail.	`"xxxx xxxx xxxx xxxx"`
`SMTP_FROM_NAME`	Nome de exibição amigável do remetente na caixa de entrada do usuário.	`"Menthor IA"`
`SMTP_USE_TLS`	Habilita criptografia STARTTLS (recomendado para porta 587).	`True`
`SMTP_USE_SSL`	Habilita conexão SSL direta (para porta 465).	`False`

Perigo

Restrição de Modelos (OPENAI_MODEL / OPENAI_MODEL_SMALL / OPENAI_MODEL_LIST): Estes valores não devem ser alterados sem alinhamento prévio com a equipe de desenvolvimento. A arquitetura, os prompts e a lógica de processamento de dados foram otimizados especificamente para estes modelos. Alterações não homologadas podem causar falhas críticas na geração de respostas e instabilidade no sistema.

Controle de Fluxo (Rate Limiting)

O sistema implementa um limitador de requisições baseado em API Key e Janela Fixa para proteger a infraestrutura contra uso excessivo e picos de custo.

Perfis de Limite

As quotas são segmentadas por categorias de consumo:

MESSAGES: Aplicado aos endpoints de streaming (/token_streaming, /sentence_streaming, /block_streaming).

Nota

O endpoint /send_prompt_wpp consome a cota do perfil MESSAGES, pois utiliza internamente a lógica de blocos para entrega ao WhatsApp.
PROCESSING: Aplicado a operações de escrita e análise profunda, como o gerenciamento de arquivos (Menthor Files) e a documentação automática de bancos de dados (Menthor DB), como /databases/create_description_db, /databases/evaluate-context-quality, /storage/upload_files e /storage/update_files. Inclui o uso do endpoint específico de análise de detecções /llm_analysis/detections e de ocorrências /llm_analysis/occurrences.
DEFAULT / ADMIN: Limites de segurança para rotas de sistema e monitoramento. Não aplicados no Menthor.

Configuração Técnica das Quotas

A variável RATE_LIMITS_CONFIG deve seguir rigorosamente a sintaxe de dicionário Python/JSON.

RATE_LIMITS_CONFIG='{
    "DEFAULT": {"per_minute": 20, "per_hour": 100, "per_day": 500},
    "MESSAGES": {"per_minute": 50, "per_hour": 200, "per_day": 1200},
    "PROCESSING": {"per_minute": 20, "per_hour": 100, "per_day": 500}
}'

Aviso

Sintaxe de Aspas: Para que o sistema interprete as configurações corretamente, o bloco deve ser envolvido por aspas simples (') e as chaves internas por aspas duplas (").

Nota

Se ENABLE_RATE_LIMITER estiver como False, todos os limites acima são ignorados, permitindo requisições ilimitadas. Use com cautela em produção.

Serviço de Cache e Autenticação OTP (Redis & SMTP)

Para viabilizar a validação segura de identidade de usuários finais via One-Time Password (OTP) com suporte a múltiplos nós ou workers (Uvicorn), o sistema utiliza uma camada de persistência temporária no Redis e disparo por e-mail via protocolo SMTP.

Persistência no Redis

A variável REDIS_URL define a conexão com o banco de chaves:

Em Docker: Utiliza o hostname da rede interna: redis://redis:6379/0.
Em Desenvolvimento Local: Aponta para a porta exposta no host: redis://localhost:6379/0.
Mecanismo de Fallback: Caso a conexão com o Redis fique indisponível, o sistema emite um aviso no log e ativa automaticamente um armazenamento em memória local (in-memory) thread-safe para evitar interrupções operacionais.

Envio de E-mail via SMTP

O envio de e-mails de verificação suporta qualquer provedor SMTP padrão (como Gmail, Outlook, AWS SES ou servidores corporativos):

Google Workspace / Gmail: Requer o uso de Senha de Aplicativo (App Password) de 16 dígitos gerada na Conta Google com 2FA ativo. O sistema higieniza automaticamente espaços em branco e caracteres invisíveis na variável SMTP_PASSWORD.
Criptografia: Por padrão, utiliza STARTTLS na porta 587 (SMTP_USE_TLS=True). Se utilizar a porta 465 com SSL direto, configure SMTP_USE_SSL=True e SMTP_USE_TLS=False.

Limites de Envio e Provedores Transacionais

Ao planejar o ambiente produtivo, observe as particularidades de volume e entregabilidade:

Quotas de Envio (Gmail / Google Workspace): Contas gratuitas do Gmail possuem cota de ~500 envios/dia, enquanto contas corporativas do Google Workspace suportam até ~2.000 envios/dia via SMTP. Picos repentinos de validações podem atingir esse teto temporariamente se houver muitas requisições simultâneas.
Provedores Transacionais em Alta Escala: Para operações corporativas com alto tráfego ou múltiplos clientes simultâneos, recomenda-se apontar as credenciais SMTP para serviços transacionais dedicados (como Amazon SES, SendGrid, Resend ou Postmark), que oferecem maior volume e reputação de entrega.
Registros de Domínio (SPF, DKIM e DMARC): Certifique-se de que o domínio do remetente (SMTP_USER) possua os registros SPF, DKIM e DMARC configurados na zona de DNS, garantindo que os e-mails de código de segurança cheguem imediatamente à Caixa de Entrada dos colaboradores.

Configurações Internas (menthor_config.py)

O arquivo técnico projects/menthor/menthor_config.py atua centralizando constantes estruturais da aplicação e inicializando os clientes da API de IA através da classe estática AIConfig.

Integrações Externas e Diretórios

Este arquivo define valores fixos que controlam as pontes de dados da plataforma:

Integração SQL Externa (Getter): Configura a URL base (URL_API), o token de parceiro (ACCESS_TOKEN) e o email administrador corporativo (USER_EMAIL) para sincronização de contextos de empresas em caso de erro em arquivo local.
Notificações a APIs Externas: Gerencia chaves internas como EXTERNAL_API_TOKEN e o token dedicado EXTERNAL_API_TOKEN_VALGROUP.
Estrutura de Pastas Locais: Mapeia onde o sistema busca dados brutos e índices (CONTEXT_DIR, DB_DIR e VS_DIR).

Aviso

Se alterar o caminho de CONTEXT_DIR, deve-se obrigatoriamente alterar a variável correspondente de mesmo nome contida em core/config_menthor.py.
Roteamento de Mensagens (WhatsApp): Centraliza as variáveis de ambiente API_KEY e WPP_AUTH_SECRET combinando-as com os IPs de servidores de mensageria em produção (END_POINT_BLOCK_STREAMING e END_POINT_WPP).

Perigo

Mudança de Infraestrutura (IP do Servidor): Caso o servidor de mensageria seja migrado ou o IP sofra alterações, os endereços das constantes END_POINT_BLOCK_STREAMING e END_POINT_WPP devem ser atualizados manualmente neste arquivo, caso contrário o fluxo de entrega de mensagens/WhatsApp falhará por completo. Para desenvolvimento local, as linhas de apontamento para 127.0.0.1 devem ser descomentadas.

Classe de Conexão de IA (AIConfig)

A classe AIConfig faz a ponte inteligente com o arquivo .env. Ela lê dinamicamente as credenciais informadas e expõe métodos globais como get_async_client() e get_sync_client().

Nota

Regra Crítica do Azure: Ao utilizar o provedor Azure, o nome de implantação (Model deployment name) configurado na nuvem SEMPRE deve ser idêntico ao nome oficial do modelo equivalente na OpenAI (ex: gpt-4o). A classe se encarrega de injetar o base_url correto automaticamente se o provedor for detectado como "azure".