Configuração¶
De onde vêm os valores¶
src/core/config/settings.py contém a dataclass imutável Settings e o loader load_settings(), com cache por processo. Ele lê os.environ; não abre .env. O arquivo é carregado pelo launcher ou por scripts que implementam seu próprio loader. A referência de variáveis relaciona os consumidores e as diferenças entre fontes.
| Fonte | Papel | Quando passa a valer |
|---|---|---|
.env.example |
Modelo versionado de configuração local | Somente depois de copiar, editar e carregar |
.env |
Valores locais, ignorados pelo Git | Conforme o loader do script |
| Ambiente do processo | Entrada efetiva de load_settings() |
No primeiro carregamento do processo |
| SSM Parameter Store | Resolução de segredos referenciados | Na inicialização do cliente/settings que os busca |
template.yaml |
Variáveis/recursos de cada Lambda | Depois de deploy bem-sucedido |
samconfig.toml e script de deploy |
Seleção de ambiente e parâmetros | Na execução de build/deploy |
| Configurações/recursos DynamoDB | Whitelist adicional, horário, prompts e packages | Quando os consumidores consultam o repository |
Mudar .env não atualiza uma Lambda nem um Settings já carregado. Reinicie o processo local após mudar flags. Testes que alteram o ambiente usam load_settings.cache_clear() para evitar configuração de outro caso.
Configuração mínima e adapters¶
Para construir as dependências do core, configure OPENAI_API_KEY diretamente ou OPENAI_API_KEY_SSM_PARAM, além de DYNAMODB_TABLE. A chave direta tem precedência sobre SSM. No dashboard, DYNAMODB_TABLE recebe um default local antes da construção das dependências.
| Integração | Flag | Desabilitada | Habilitada |
|---|---|---|---|
WHATSAPP_CLOUD_ENABLED |
WhatsAppClientStub |
Cloud API; exige token, app secret, verify token e phone number ID | |
| CRM | HUBSPOT_ENABLED |
HubSpotClientStub |
HubSpotHttpClient; exige token e pipeline/stage |
| eGestor | EGESTOR_ENABLED |
EGestorClientStub |
EGestorHttpClient; resolve URL/token diretos ou SSM |
| Handoff | HANDOFF_NOTIFIER_ENABLED |
HandoffNotifierStub |
Seleciona stub, email ou whatsapp |
| IA | Sem flag geral de stub no factory | Não se aplica | OpenAIClient é construído pelo factory |
StubResponse é o tipo de retorno de CRM/eGestor reais e fictícios. Seu nome não significa que uma operação foi simulada. Confira a flag e a classe selecionada antes de interpretar um ID retornado.
Tipos e validações¶
Booleanos aceitam 1, true, yes, y ou on, sem distinção entre maiúsculas e minúsculas. Valores ausentes ou vazios usam o default; outros textos não vazios viram false. Inteiros usam int(): texto inválido causa erro de configuração. Listas CSV são separadas por vírgula e têm espaços externos removidos.
BUSINESS_HOURS_DAYS usa 1 para segunda e 7 para domingo; uma string vazia cria uma tupla sem dias. O horário efetivo pode ser sobreposto pelo registro operacional business_hours. O timezone depende da base zoneinfo; o extra tzdata é instalado no Windows pelas dependências da aplicação.
WHATSAPP_FREE_ONLY=false com Cloud API habilitada causa RuntimeError('Paid WhatsApp modes are not implemented'). Essa flag não implementa templates pagos nem verifica a janela de atendimento de cada destinatário.
Modelos e limites¶
Os modelos de Triagem, Qualificação, Coleta e resumo têm variáveis independentes. OPENAI_REASONING_EFFORT é uma configuração compartilhada do cliente. Consulte OpenAI antes de trocar modelo: o método do core ainda se chama chat, mas a implementação usa Responses API.
Divergência documental e de defaults
Os defaults de modelo de settings.py, .env.example e SAM diferem. Não escolha o modelo efetivo lendo apenas um deles. scripts/deploy_from_env.ps1 também não encaminha OPENAI_REASONING_EFFORT para o parâmetro OpenAiReasoningEffort; confira o perfil SAM e o ambiente implantado.
MAX_HISTORY_MESSAGES limita a consulta de histórico e MAX_CONTEXT_ENRICHMENTS_PER_MESSAGE limita o enriquecimento s=99. DEBOUNCE_WINDOW_SECONDS existe por compatibilidade; o caminho FIFO atual trabalha sem janela de espera. Consulte SQS para separar esse valor do algoritmo latest-message-wins.
Configuração dinâmica¶
build_dependencies() compõe DynamicKnowledgeBase sobre InMemoryKnowledgeBase. Um package ativo no repository versionado tem precedência; um override inativo desabilita aquele package. Prompts usam AgentInvokerImpl._apply_prompt_override(): override ausente ou inativo retorna o prompt padrão, enquanto {{default_prompt}} permite acrescentar instruções ao original.
A whitelist efetiva é a união da variável com a lista operacional. Remover um operador apenas da lista dinâmica não o remove se continuar em WHITELIST_PHONE_NUMBERS. As regras de autenticação e os repositórios explicam os efeitos desses registros.
Diagnosticar configuração incorreta¶
Leia o nome da variável no erro; nunca imprima o objeto Settings inteiro, que inclui segredos. Para Missing required env var, confira a presença no processo correto. Para falha SSM, confira nome do parâmetro, região, permissão ssm:GetParameter e decriptação. Para factory CRM/eGestor, confira flags e campos obrigatórios antes de investigar payloads.
Fontes e testes: src/core/config/settings.py, src/core/integrations/factory.py, src/core/application/admin_tools.py, src/core/knowledge_base/repository.py, tests/unit/test_settings.py, tests/unit/integrations/test_factory.py, tests/unit/integrations/test_knowledge_base.py.