.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).
# =============================================================================

# --- Provider LLM (OpenRouter ou Cursor SDK) ---
# cursor (default): usa Cursor Python SDK (cursor-sdk) com runtime local
# openrouter: usa OpenRouter chat completions (httpx)
ACL_LLM_PROVIDER=cursor

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

# --- Cursor SDK (obrigatório se ACL_LLM_PROVIDER=cursor) ---
# Chave da API no Cursor Dashboard -> API Keys.
CURSOR_API_KEY=
# Modelo do Cursor SDK (ex.: composer-2.5). Para delegar o default ao servidor: auto.
ACL_CURSOR_MODEL=composer-2.5
# true = workspace vazio (.cursor-chat-workspace) sem rules/MCP do repo (chat-only, não agente no código).
ACL_CURSOR_CHAT_ONLY=false

# --- 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

# --- Histórico de conversa no prompt (POC — localStorage no browser) ---
# Máximo de mensagens user/assistant injetadas no LLM por turno.
ACL_CHAT_HISTORY_MAX_TURNS=12
# Máximo de caracteres totais do history no prompt (exclui system RAG).
ACL_CHAT_HISTORY_MAX_CHARS=12000

# --- 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
# --- Política de grounding (contrato injectado no prompt) ---
# strict   = trechos RAG são SSOT absoluto (comportamento conservador)
# anchored = trechos são evidência primária + extensão pedagógica rotulada (default)
# hybrid   = anchored com chunks; permissive sem chunks em retrieval fraco
ACL_GROUNDING_POLICY=anchored

# Legado (ignorado): gates de retrieval são só classificação (reason/confidence).
# Toda mensagem dispara o LLM; chunks fracos seguem ACL_GROUNDING_POLICY.
# ACL_RETRIEVAL_MODE=strict
# Com true, ambiguous_retrieval com ≥2 candidatos acima do MIN_SCORE gera LLM
# com grounding_disambiguation e fontes numeradas [Fonte 1], [Fonte 2], …
ACL_DISAMBIGUATION_ENABLED=false

# --- Catálogo lexical de aulas (ISS JSON — ver engine/lesson_catalog.py) ---
# Ativa roteamento por catálogo sem LLM (rescue, sugestões em hard stop).
ACL_CATALOG_ENABLED=false
# Diretório com lessons.json e search-index.json (vazio = ../ISS/content se existir).
# ACL_CATALOG_JSON_DIR=/caminho/para/ISS/content
# Score BM25 do catálogo mínimo para is_confident() (rescue / sugestões).
ACL_CATALOG_MIN_SCORE=2.0
# Margem mínima entre 1.º e 2.º match do catálogo.
ACL_CATALOG_MIN_MARGIN=0.35
# Limiar alto para is_strict_confident() — pré-escopo BM25 em fase futura (não relaxa retrieval).
ACL_CATALOG_STRICT_THRESHOLD=4.0
# Quantos matches do catálogo retornar em match().
ACL_CATALOG_PROMPT_TOP_K=5

# --- Rate limit /chat (fixo no código — api/routes.py) ---
# 30 requisições POST /chat por IP a cada 60 segundos → HTTP 429.

# --- Ambiente de execução ---
# development (default) | staging | production
# Em production: middleware no-cache de /src desativado; use KERNELBOT_FORCE_HSTS=true atrás de HTTPS.
KERNELBOT_ENV=development

# --- Reload / health CI (Bearer) ---
# Obrigatório em KERNELBOT_ENV=production para GET /health/catalog e POST /chat "/reload".
# Em staging/local pode ficar vazio — /health/catalog retorna 503 (comportamento esperado).
# O workflow ISS sync-kernelbot-knowledge envia o mesmo valor em KERNELBOT_RELOAD_TOKEN.
ACL_RELOAD_BEARER_TOKEN=

# --- ISS (links de fonte no frontend) ---
# Base da página de aula no ISS; o frontend monta ?d=<disciplina>&a=<slug>
# KERNELBOT_ISS_PUBLIC_BASE_URL=https://gaabdevweb.github.io/ISS/public/aula.html

# --- HTTPS / proxy reverso ---
# KERNELBOT_FORCE_HSTS=true

# --- 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.