Merge branch 'main' into feat/tailwind-v4-ui

Author: gbdiniz

.env.example

@@ -51,6 +51,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
 
+# --- 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
+
 # --- Logging ---
 # text = linha legivel; json = uma linha JSON por evento ACL (grep/agregadores).
 # ACL_LOG_FORMAT=text

.gitignore

@@ -19,4 +19,6 @@ scripts/
 CLAUDE.md
 
 node_modules/
-frontend/assets/css/output.css
+frontend/assets/css/output.css
+
+.agent_history.md

Features.canvas

@@ -0,0 +1,78 @@
+{
+	"nodes":[
+		{
+			"id":"6c0d14f9d11e02ff",
+			"type":"text",
+			"text":"# Para hoje: \n\n## Começar o 'prompt interno' do kernelBot\n\t- Desenhar arquitetura, discutir stack e et\n\t\tVer oque é mais vantajoso, usar RAGMB35, ou o prompt interno, ou ambos somados",
+			"styleAttributes":{},
+			"x":-780,
+			"y":-280,
+			"width":500,
+			"height":260
+		},
+		{
+			"id":"ca79b034ef1e38b1",
+			"type":"text",
+			"text":"Basicamente: \n\nUm sistem prompt que seria 'ativado' a cada interação com o usuário e guiaria o sistema com base nas descrições e outros campos dos jsons do projeto, a escolher a aula/conteúdo que melhor se enquadra com a pergunta e/ou solicitação do usuário, para assim, não depender apenas de RAGMB35\n- Discutivel\n- Ver viabiliadade\n- Discutir se é possivel manter o RAGMB35, ou usar ambos \n",
+			"styleAttributes":{},
+			"x":-180,
+			"y":-820,
+			"width":480,
+			"height":420
+		},
+		{
+			"id":"6865db41af0d27e4",
+			"type":"text",
+			"text":"Basicamente casos de ambiguidade ou a falta de contexto suficiente",
+			"styleAttributes":{},
+			"x":500,
+			"y":-500,
+			"width":340,
+			"height":100,
+			"color":"3"
+		},
+		{
+			"id":"d0bb3e87f6fc7f4d",
+			"type":"text",
+			"text":"Sistem prompt seria bom para os casos aonde: \n- Encontrei trechos na base, mas eles não cobrem bem a sua pergunta. Reformule incluindo termos mais específicos sobre o que quer saber.\n- Encontrei conteúdos parecidos na base e não consegui distinguir qual deles realmente responde à sua pergunta. Adicione detalhes que ajudem a desempatar, como nome do módulo, comando ou tecnologia.\n- etc",
+			"styleAttributes":{},
+			"x":420,
+			"y":-840,
+			"width":500,
+			"height":300
+		}
+	],
+	"edges":[
+		{
+			"id":"a61d1246554b6d96",
+			"styleAttributes":{},
+			"toFloating":false,
+			"fromNode":"6c0d14f9d11e02ff",
+			"fromSide":"right",
+			"toNode":"ca79b034ef1e38b1",
+			"toSide":"left"
+		},
+		{
+			"id":"d4f523af1ccedba6",
+			"styleAttributes":{},
+			"toFloating":false,
+			"fromNode":"ca79b034ef1e38b1",
+			"fromSide":"right",
+			"toNode":"d0bb3e87f6fc7f4d",
+			"toSide":"left"
+		},
+		{
+			"id":"5ba456aeac796445",
+			"styleAttributes":{},
+			"toFloating":false,
+			"fromNode":"6865db41af0d27e4",
+			"fromSide":"top",
+			"toNode":"d0bb3e87f6fc7f4d",
+			"toSide":"bottom"
+		}
+	],
+	"metadata":{
+		"version":"1.0-1.0",
+		"frontmatter":{}
+	}
+}

app/state.py

@@ -2,10 +2,11 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 from engine.chat_provider import ChatProvider
 from engine.context import ContextManager
+from engine.lesson_catalog import LessonCatalog
 from engine.pinned_store import PinnedSessionStore
 from engine.search import SearchEngine
 
@@ -16,3 +17,6 @@ class AppServices:
     context_manager: ContextManager
     chat_provider: ChatProvider
     pinned_store: PinnedSessionStore
+    lesson_catalog: LessonCatalog | None = None
+    indexed_lesson_keys: frozenset[str] = field(default_factory=frozenset)
+    catalog_drift_report: dict | None = None

core/config.py

@@ -58,6 +58,15 @@ class Settings:
     retrieval_candidate_k: int
     retrieval_top_k: int
     retrieval_max_chunks_per_source: int
+    # Catálogo lexical de aulas (ISS JSON) — ver engine/lesson_catalog.py
+    catalog_enabled: bool
+    catalog_json_dir: Path | None
+    catalog_min_score: float
+    catalog_min_margin: float
+    # Limiar alto para pré-escopo BM25 (Fase futura); não relaxar retrieval BM25.
+    catalog_strict_threshold: float
+    catalog_prompt_top_k: int
+    catalog_router_prompt: str
 
     @property
     def openrouter_headers(self) -> dict[str, str]:
@@ -88,6 +97,7 @@ def load(cls) -> Settings:
         prompts_dir = Path(__file__).resolve().parent / "systemPrompt"
         system_prompt_file = prompts_dir / "system_prompt.txt"
         sticky_instruction_file = prompts_dir / "sticky_instruction.txt"
+        catalog_router_file = prompts_dir / "catalog_router.txt"
 
         if not system_prompt_file.exists():
             raise RuntimeError(
@@ -99,9 +109,15 @@ def load(cls) -> Settings:
                 f"Arquivo de instrução sticky não encontrado: {sticky_instruction_file}. "
                 "Crie o arquivo core/systemPrompt/sticky_instruction.txt com o template de contexto fixado."
             )
+        if not catalog_router_file.exists():
+            raise RuntimeError(
+                f"Arquivo de prompt do catálogo não encontrado: {catalog_router_file}. "
+                "Crie o arquivo core/systemPrompt/catalog_router.txt com as instruções de contexto do catálogo."
+            )
 
         system_prompt = system_prompt_file.read_text(encoding="utf-8").strip()
         sticky_instruction = sticky_instruction_file.read_text(encoding="utf-8").strip()
+        catalog_router_prompt = catalog_router_file.read_text(encoding="utf-8").strip()
 
         raw_global = (os.getenv("ACL_GLOBAL_CONTEXT") or "geral").strip().lower()
         if raw_global == "geral":
@@ -161,6 +177,30 @@ def _env_int(name: str, default: int, lo: int, hi: int) -> int:
             "ACL_RETRIEVAL_MAX_CHUNKS_PER_SOURCE", 2, 1, 10
         )
 
+        raw_catalog_enabled = (os.getenv("ACL_CATALOG_ENABLED") or "false").strip().lower()
+        catalog_enabled = raw_catalog_enabled in ("1", "true", "yes", "on")
+
+        catalog_json_dir: Path | None = None
+        raw_catalog_dir = (os.getenv("ACL_CATALOG_JSON_DIR") or "").strip()
+        if raw_catalog_dir:
+            raw_path = Path(raw_catalog_dir).expanduser()
+            catalog_json_dir = (
+                raw_path.resolve()
+                if raw_path.is_absolute()
+                else (project_root / raw_path).resolve()
+            )
+        else:
+            iss_fallback = project_root.parent / "ISS" / "content"
+            if iss_fallback.is_dir():
+                catalog_json_dir = iss_fallback.resolve()
+
+        catalog_min_score = _env_float("ACL_CATALOG_MIN_SCORE", 2.0, 0.0, 100.0)
+        catalog_min_margin = _env_float("ACL_CATALOG_MIN_MARGIN", 0.35, 0.0, 50.0)
+        catalog_strict_threshold = _env_float(
+            "ACL_CATALOG_STRICT_THRESHOLD", 4.0, 0.0, 100.0
+        )
+        catalog_prompt_top_k = _env_int("ACL_CATALOG_PROMPT_TOP_K", 5, 1, 20)
+
         """ !Credenciais do banco! """
 
         db_host = _normalize_db_host(os.getenv("DB_HOST") or "")
@@ -205,4 +245,11 @@ def _env_int(name: str, default: int, lo: int, hi: int) -> int:
             retrieval_candidate_k=retrieval_candidate_k,
             retrieval_top_k=retrieval_top_k,
             retrieval_max_chunks_per_source=retrieval_max_chunks_per_source,
+            catalog_enabled=catalog_enabled,
+            catalog_json_dir=catalog_json_dir,
+            catalog_min_score=catalog_min_score,
+            catalog_min_margin=catalog_min_margin,
+            catalog_strict_threshold=catalog_strict_threshold,
+            catalog_prompt_top_k=catalog_prompt_top_k,
+            catalog_router_prompt=catalog_router_prompt,
         )

core/systemPrompt/catalog_router.txt

@@ -0,0 +1,6 @@
+Contexto do catálogo de aulas (ativado quando há correspondência lexical provável):
+
+- O assistente está respondendo no contexto de uma aula provável do catálogo acadêmico.
+- Fundamente a resposta APENAS nos trechos RAG fornecidos abaixo deste bloco.
+- Não invente conteúdo, exemplos ou definições a partir só dos metadados do catálogo (título, slug, resumo).
+- Se os trechos forem insuficientes para responder com segurança, diga explicitamente que a base não cobre a pergunta e peça reformulação com termos mais específicos (módulo, comando, tecnologia).