.env.example

# =============================================================================
# ACL (KernelBot) — variáveis de ambiente
# Copie para .env e preencha os valores reais:
#   copy .env.example .env   (Windows PowerShell: Copy-Item .env.example .env)
# O ficheiro .env não deve ir para o Git (.gitignore).
# =============================================================================

# --- OpenRouter (obrigatório) ---
# Chave da API em https://openrouter.ai/keys — usada em todas as chamadas ao LLM.
OPENROUTER_API_KEY=

# --- MySQL (obrigatório para o índice BM25 e ingestão) ---
# Host do servidor MySQL (ex.: 127.0.0.1 ou localhost). Nao use 127.0.0.0 — costuma dar timeout.
DB_HOST=
# Porta TCP (padrão MySQL: 3306).
DB_PORT=3306
# Nome da base de dados onde está a tabela `knowledge`.
DB_NAME=
# Utilizador com permissão de leitura (e escrita se correres ingest).
DB_USER=
DB_PASSWORD=

# --- Contexto global (/content sem disciplina) ---
# geral = BM25 em todos os silos e merge por score.
# all   = mesmo modo de nome alternativo aceite pelo código.
ACL_GLOBAL_CONTEXT=geral

# --- Contexto fixado (pin na sessão) ---
# Quantos turnos manter chunks fixados antes de voltar a buscar forte.
ACL_PINNED_MAX_TURNS=5
# Tamanho máximo em caracteres do texto fixado no pin.
ACL_PINNED_MAX_CHARS=24000
# Score normalizado abaixo do qual o pin é considerado "fraco" (legado / heurísticas de pin).
ACL_PINNED_WEAK_SCORE=0.4

# --- Política de retrieval (modo strict — ver engine/retrieval.py) ---
# Score BM25 bruto mínimo do melhor candidato; abaixo → hard stop (contexto insuficiente).
ACL_RETRIEVAL_MIN_SCORE=1.5
# Margem mínima entre 1.º e 2.º score; evita ambos muito próximos (ambiguidade).
ACL_RETRIEVAL_MIN_SCORE_MARGIN=0.15
# Cobertura mínima (0–1) dos termos informativos da query nos chunks escolhidos.
ACL_RETRIEVAL_MIN_COVERAGE=0.34
# Igual, mas termos "centrais" da query contam com peso 2× na métrica.
ACL_RETRIEVAL_MIN_COVERAGE_WEIGHTED=0.34
# Número mínimo de termos informativos na pergunta (strict).
ACL_RETRIEVAL_MIN_TERMS=2
# Quantos candidatos o SearchEngine devolve antes de build_decision (1–50).
ACL_RETRIEVAL_CANDIDATE_K=8
# Quantos chunks entram no prompt após passar os gates (1–20).
ACL_RETRIEVAL_TOP_K=4
# Máximo de chunks por fonte (slug) entre os selecionados — diversidade (1–10).
ACL_RETRIEVAL_MAX_CHUNKS_PER_SOURCE=2

# --- Logging ---
# text = linha legivel; json = uma linha JSON por evento ACL (grep/agregadores).
# ACL_LOG_FORMAT=text
# ACL_LOG_LEVEL=INFO
# ACL_LOG_LEVEL=DEBUG  # inclui evento retrieval_gates_inputs (metricas antes dos cortes)

# --- Não configurável por .env (definido em core/config.py) ---
# Lista de modelos OpenRouter, URL base, timeout HTTP, textos de system/sticky vêm de ficheiros
# em core/systemPrompt/ — ajusta lá ou no código se precisares de outro stack de modelos.