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 ficheiro na raiz do projeto: .. list-table:: :widths: 30 45 25 :header-rows: 1 * - 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)* .. danger:: **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``). .. note:: 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. .. code-block:: python 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} }' .. warning:: **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 (``"``). .. note:: Se ``ENABLE_RATE_LIMITER`` estiver como ``False``, todos os limites acima são ignorados, permitindo requisições ilimitadas. Use com cautela em produção. 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``). .. warning:: 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``). .. danger:: **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()``. .. note:: **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"``.