Merge pull request

KernelBot v2: retrieval strict, logs estruturados e config por .env.example

Author: GaabDevWeb

.env.example

@@ -0,0 +1,62 @@
+# =============================================================================
+# 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.

.github/workflows/main.yml

@@ -1,8 +1,40 @@
+<<<<<<< HEAD
 .env
 
+.pytest_cache/
+
 **/__pycache__/
 *.py[cod]
 *$py.class
 *.so
 
-cursor/
+content/
+.venv/
+.venv_readme_check/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/
+scripts/
+=======
+.env
+
+.pytest_cache/
+
+**/__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+content/
+.venv/
+.venv_readme_check/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/
+scripts/
+
+>>>>>>> 124ae17972dd35902cec901ff1819bd5be55891f

.gitignore

@@ -14,7 +14,7 @@
   <p>
     <strong>Se você é um recrutador:</strong> O código fala mais que mil palavras. Olhe a pasta <code>engine/</code>.<br />
     <strong>Se você é um curioso:</strong> Volte em breve. Ou dê um <code>python main.py</code> e descubra.
-  </p>
+
 
   <br clear="all" />
 </div>

LICENSE

@@ -81,11 +81,10 @@ async def chat(request: Request) -> StreamingResponse:
         log.info("🔄 Comando /reload recebido — reconstruindo índice BM25...")
         services.search_engine.rebuild()
         chunk_count = len(services.search_engine.chunks)
-        db_count = sum(1 for c in services.search_engine.chunks if c.get("source", "").startswith("db:"))
-        md_count = chunk_count - db_count
+        silo_count = len(services.search_engine.discipline_ids)
         status = (
             f"Índice reconstruído: {chunk_count} chunk(s) total "
-            f"({md_count} de arquivos .md + {db_count} do MySQL)."
+            f"({silo_count} silo(s) do MySQL)."
         )
         log.info("✅ /reload concluído — %s", status)
 
@@ -106,7 +105,11 @@ async def _reload_stream() -> AsyncGenerator[str, None]:
     )
 
     return StreamingResponse(
-        services.chat_provider.stream_response(built.messages, trace=built.trace),
+        services.chat_provider.stream_response(
+            built.messages,
+            trace=built.trace,
+            decision=built.decision,
+        ),
         media_type="text/event-stream",
         headers={
             "Cache-Control": "no-cache",

README.md

@@ -24,9 +24,7 @@ def create_app(services: AppServices) -> FastAPI:
     async def lifespan(app: FastAPI):
         log.info("🚀 ACL iniciado e pronto para receber requisições.")
         yield
-        services.observer.stop()
-        services.observer.join()
-        log.info("🛑 Watchdog encerrado. Servidor finalizado.")
+        log.info("🛑 Servidor finalizado.")
 
     app = FastAPI(title="ACL — Agente de Contexto Local", lifespan=lifespan)
     app.state.services = services
@@ -41,4 +39,5 @@ async def lifespan(app: FastAPI):
         app.mount("/src", StaticFiles(directory=str(src_dir)), name="src")
 
     app.include_router(router)
+
     return app

SQL/instructions_for_creation.md

@@ -4,8 +4,6 @@
 
 from dataclasses import dataclass
 
-from watchdog.observers import Observer
-
 from engine.chat_provider import ChatProvider
 from engine.context import ContextManager
 from engine.pinned_store import PinnedSessionStore
@@ -17,5 +15,4 @@ class AppServices:
     search_engine: SearchEngine
     context_manager: ContextManager
     chat_provider: ChatProvider
-    observer: Observer
     pinned_store: PinnedSessionStore