Merge pull request frommysql-refactor

Mysql refactor

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.

.gitignore

@@ -1,8 +1,10 @@
-.env
-
-**/__pycache__/
-*.py[cod]
-*$py.class
-*.so
-
-cursor/
+.env
+
+.pytest_cache/
+
+**/__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+cursor/

README.md

@@ -1,186 +0,0 @@
-<p align="center">
-  <img src="frontend/assets/images/KernelBanner.webp" alt="KernelBot" width="100%" />
-</p>
-
-# KernelBot
-
-**Chatbot RAG local-first que transforma Markdown em base de conhecimento consultável via chat.**
-
----
-
-## O que é
-
-O KernelBot — internamente chamado **ACL (Agente de Contexto Local)** — é um sistema que indexa arquivos Markdown de um diretório local (`content/`) usando BM25, recupera trechos relevantes e os injeta como contexto para um LLM via OpenRouter. A resposta chega em streaming (SSE) com rastreabilidade: você sabe de onde veio cada trecho usado.
-
-Sem banco de dados, sem fila, sem infra pesada. Índice e estado ficam na memória do processo.
-
----
-
-## Problema que resolve
-
-Alunos precisam revisar gravações de aulas de ~2h para tirar dúvidas simples. Sem o KernelBot, a alternativa é reassistir o material bruto ou esperar resposta da secretaria/professores.
-
-O sistema usa resumos estruturados das aulas como corpus RAG, permitindo perguntas diretas com respostas ancoradas no conteúdo real — não em "achismo" do modelo.
-
----
-
-## Como funciona
-
-```
-content/*.md ──► SearchEngine (BM25 por silo) ──► ContextManager ──► ChatProvider ──► SSE
-     ▲                                                                      │
-     │                                                                      ▼
-  Watchdog                                                            OpenRouter API
-(rebuild automático)                                                 (LLM com fallback)
-```
-
-**Três etapas:**
-
-1. **Indexação** — `SearchEngine` lê `content/**/*.md`, divide por headers em chunks e cria um índice BM25 separado por silo (subpasta). O Watchdog monitora alterações e reconstrói o índice automaticamente (~1.5s de debounce).
-
-2. **Decisão de contexto** — `ContextManager.build_messages()` interpreta comandos (`/python`, `/doc`, `/content`), campo `discipline` do JSON e pinned context por sessão para decidir quais chunks injetar no system prompt.
-
-3. **Geração** — `ChatProvider` chama o LLM via OpenRouter em streaming SSE. Suporta fallback automático entre modelos. Antes dos tokens, emite metadados (`[ACL_META]`) com rótulo do silo e fontes usadas.
-
----
-
-## Diferenciais
-
-| Recurso | O que faz |
-|---------|-----------|
-| **Silos BM25** | Cada subpasta de `content/` é um domínio isolado com índice próprio — evita mistura de contextos entre disciplinas |
-| **Comandos de escopo** | `/python`, `/doc`, `/content` etc. forçam onde a busca acontece |
-| **Pinned context** | Mantém contexto entre mensagens da mesma sessão para follow-ups curtos não "perderem o fio" |
-| **File watching** | Editou um `.md` em `content/`? Em ~1.5s o índice já reflete a mudança |
-| **Rastreabilidade** | Respostas incluem breadcrumbs com os arquivos fonte usados (via `[ACL_META]` no SSE) |
-| **Zero infra** | Sem banco, sem Redis, sem Docker obrigatório — `python main.py` e pronto |
-
----
-
-## Estrutura de pastas
-
-```
-KernelBot/
-├── main.py              # Orquestração: serviços, watchdog, app FastAPI
-├── core/                # Settings (.env), logging centralizado
-├── engine/              # SearchEngine, ContentWatcher, ContextManager, ChatProvider, PinnedSessionStore
-├── api/                 # Rotas FastAPI (GET /, POST /chat)
-├── app/                 # create_app(), estado injetado (AppServices)
-├── content/             # Base de conhecimento — silos por subpasta
-│   ├── python/          # 16 aulas
-│   ├── visualizacao-sql/# 17 aulas
-│   ├── projeto-bloco/   # 9 aulas
-│   ├── planejamento-curso-carreira/  # 7 aulas
-│   └── doc/             # Documentação interna (silo /doc)
-├── frontend/            # Assets CSS e módulos JS da UI
-├── templates/           # index.html (Jinja2)
-├── tests/               # Smoke tests (pytest)
-└── requirements.txt
-```
-
----
-
-## Como rodar
-
-### Pré-requisitos
-
-- Python 3.10+
-- Chave de API do [OpenRouter](https://openrouter.ai/)
-
-### Instalação
-
-```bash
-git clone https://github.com/seu-usuario/KernelBot.git
-cd KernelBot
-pip install -r requirements.txt
-```
-
-### Configuração
-
-Crie um arquivo `.env` na raiz:
-
-```
-OPENROUTER_API_KEY=sua-chave-aqui
-```
-
-Variáveis opcionais:
-
-| Variável | Default | Descrição |
-|----------|---------|-----------|
-| `ACL_GLOBAL_CONTEXT` | `geral` | Escopo BM25 sem filtro: `geral` (só silo geral) ou `all` (todos os silos) |
-| `ACL_PINNED_MAX_TURNS` | `5` | Turnos antes do pinned context expirar |
-| `ACL_PINNED_MAX_CHARS` | `24000` | Limite de caracteres no pinned context |
-| `ACL_PINNED_WEAK_SCORE` | `0.4` | Score BM25 abaixo do qual se reutiliza o pin |
-
-### Executar
-
-```bash
-python main.py
-```
-
-Ou com reload para desenvolvimento:
-
-```bash
-uvicorn main:app --host 127.0.0.1 --port 8000 --reload
-```
-
-Acesse `http://127.0.0.1:8000`.
-
----
-
-## Comandos do chat
-
-| Comando | Efeito |
-|---------|--------|
-| `/python <pergunta>` | Busca RAG restrita ao silo `python` |
-| `/visualizacao-sql <pergunta>` | Busca RAG restrita ao silo `visualizacao-sql` |
-| `/projeto-bloco <pergunta>` | Busca RAG restrita ao silo `projeto-bloco` |
-| `/planejamento-curso-carreira <pergunta>` | Busca RAG restrita ao silo `planejamento-curso-carreira` |
-| `/doc <pergunta>` | Injeta todo o conteúdo de `content/doc/` no prompt |
-| `/content <pergunta>` | Força RAG no escopo global (com fallback para os primeiros chunks se não houver hit) |
-| `/reset` ou `/limpar` | Limpa o pinned context da sessão |
-
-Sem comando, o sistema usa o campo `discipline` do JSON (se enviado) ou o escopo global configurado.
-
----
-
-## Testes
-
-```bash
-python -m pytest tests/ -v
-```
-
----
-
-## Limitações
-
-- **BM25 é lexical, não semântico** — se o vocabulário da pergunta divergir do corpus, o retrieval pode falhar. Use `/content` para forçar contexto.
-- **Sem autenticação** — adequado para uso local (`127.0.0.1`). Não expor em rede sem proteção adicional.
-- **Pinned context em RAM** — reiniciar o servidor perde o estado de sessão.
-- **Comandos de silo não são automáticos** — novas subpastas em `content/` indexam automaticamente, mas o atalho `/nome` precisa ser adicionado manualmente em `_DISCIPLINE_COMMAND_PREFIXES` (`engine/context.py`).
-- **Versões não fixadas** — `requirements.txt` sem pins exatos; risco de drift em novas instalações.
-
----
-
-## Por que existe
-
-Criado para resolver uma dor real: alunos do INFNET gastavam horas revisando gravações de aula para tirar dúvidas pontuais. O KernelBot transforma resumos estruturados dessas aulas em uma base pesquisável via chat — com controle de escopo, rastreabilidade e zero dependência de infra complexa.
-
----
-
-## Stack
-
-| Camada | Tecnologia |
-|--------|------------|
-| Servidor HTTP | FastAPI + Uvicorn |
-| Índice de busca | BM25Okapi (`rank-bm25`) |
-| File watching | Watchdog |
-| LLM gateway | OpenRouter API (`httpx` async) |
-| Frontend | HTML/CSS/JS puro (Jinja2) |
-| Streaming | Server-Sent Events (SSE) |
-
----
-
-## Licença
-
-Veja o arquivo [LICENSE](LICENSE).

SQL/pybot.sql

@@ -1,10 +1,18 @@
 CREATE TABLE IF NOT EXISTS knowledge (
-    id         INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
-    title      VARCHAR(255) NOT NULL,
-    content    TEXT         NOT NULL,
-    category   VARCHAR(100) NOT NULL DEFAULT 'geral',
-    active     TINYINT(1)   NOT NULL DEFAULT 1,
-    created_at DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    updated_at DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-    INDEX idx_active_category (active, category)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+    id               INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+    slug             VARCHAR(255)   NOT NULL,
+    discipline       VARCHAR(70)    NOT NULL,
+    title            VARCHAR(255)   NOT NULL,
+    `order`          INT            NOT NULL DEFAULT 0,
+    content          MEDIUMTEXT     NOT NULL,
+    payload          JSON           NOT NULL,
+    payload_version  SMALLINT       NOT NULL DEFAULT 1,
+    source_checksum  CHAR(64)       NOT NULL,
+    active           TINYINT(1)     NOT NULL DEFAULT 1,
+    created_at       TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at       TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    UNIQUE KEY uk_slug (slug),
+    KEY idx_active_discipline (active, discipline),
+    KEY idx_discipline_order (discipline, `order`),
+    CONSTRAINT chk_payload_json CHECK (JSON_VALID(payload))
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

SQL/schema.sql

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

api/routes.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/factory.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