Develop

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

.gitignore

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

README.md

@@ -1,55 +1,20 @@
-# KernelBots (ACL)
-
-Agente de contexto local com RAG (BM25) sobre Markdown em `content/`, interface em `templates/` e respostas em streaming via OpenRouter.
-
-## Requisitos
-
-- Python 3.10+
-- Chave `OPENROUTER_API_KEY` no arquivo `.env` na raiz do repositório
-
-## Instalação
-
-```bash
-pip install -r requirements.txt
-```
-
-## Executar
-
-```bash
-python main.py
-```
-
-Ou com Uvicorn:
-
-```bash
-uvicorn main:app --host 127.0.0.1 --port 8000
-```
-
-Abra `http://127.0.0.1:8000`.
-
-## Estrutura
-
-| Caminho | Função |
-|--------|--------|
-| `main.py` | Orquestração: logging, `SearchEngine`, watchdog, `create_app` |
-| `core/` | Config (`Settings`), logging centralizado |
-| `engine/` | BM25 (`SearchEngine`), `ContentWatcher`, `ContextManager`, `ChatProvider` |
-| `api/` | Rotas FastAPI (`GET /`, `POST /chat`) |
-| `app/` | `create_app()`, estado injetado em `app.state` |
-| `content/` | Arquivos `.md` indexados |
-| `templates/` | UI (Jinja2) |
-
-## Testes
-
-```bash
-python -m pytest tests/ -v
-```
-
-## Logging
-
-O projeto usa `logging` da biblioteca padrão com loggers prefixados `kernelbots.*` (ex.: `kernelbots.engine.search`, `kernelbots.api.chat`). Para logs estruturados em JSON no stdout, é possível estender `core/logging_config.py` com algo como `structlog` no mesmo ponto de configuração.
-
-## Comandos no chat
-
-- `/content …` — força uso da base local (com fallback para os primeiros chunks se não houver hit BM25).
-- `/doc …` — injeta o conteúdo de `documentation.md` quando disponível no índice.
+<div align="center">
+  <img src="frontend/assets/images/KernelBanner.webp" alt="Banner" width="100%" />
+</div>
+
+<br />
+
+<div>
+  <img align="right" width="50%" src="frontend/assets/images/spiderMan.webp" alt="Work in Progress" />
+
+  <strong><h3>Em obras (ou quase isso)</h3></strong>
+
+  <p>O código já está performando mais que muito sênior por aí, mas a documentação ainda está sendo "indexada" pela minha produtividade.</p>
+
+  <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.
+
+
+  <br clear="all" />
+</div>

api/routes.py

@@ -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",

app/factory.py

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

app/state.py

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