Feat/agent navigation mentor

.env.example

@@ -8,6 +8,10 @@ ENABLE_SCHEDULER=true
 BORDERLESS_AUTH_URL=https://api.borderlesscoding.com
 ADMIN_EMAILS=
 
+# --- Rotas internas da borderless-api (catálogo de aulas + mídia; ingestão do mentor) ---
+# preencher — mesmo segredo configurado do lado da API
+BORDERLESS_INTERNAL_SECRET=
+
 # --- Navegação (agente) ---
 # NAVIGATION_CATALOG_TTL_S=3600
 # Cache negativo: quanto esperar antes de tentar a API de novo depois de uma falha.
@@ -61,6 +65,13 @@ EVAL_REPORTS_DIR=evals/reports
 # O juiz é sempre OpenAI, independente de LLM_PROVIDER (ADR-0013 / spec 2026-08-03).
 # JUDGE_MODEL=gpt-4.1-mini
 
+# --- Mentor de aula (spec 2026-09-11) ---
+# Kill switch de verdade (default false): sem ele ligado, tanto
+# POST /conversations/ask (mode=mentor) quanto GET /lessons/{id}/status
+# voltam 404 antes de qualquer trabalho — inclusive antes do entitlement.
+# Precisa estar true para rodar a demo do modo mentor.
+MENTOR_ENABLED=true
+
 # --- Tracing: LangSmith (opcional; desligado por padrão) ---
 LANGSMITH_TRACING=false
 # LANGSMITH_API_KEY=           # preencher, só se LANGSMITH_TRACING=true

database/migrations/versions/0012_mentor_lessons.py

@@ -0,0 +1,68 @@
+"""lessons e lesson_chunks — base do mentor de aula (spec 2026-09-11 §4).
+
+Revision ID: 0012_mentor_lessons
+Revises: 0011_navigation_persistence
+Create Date: 2026-09-11
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from pgvector.sqlalchemy import Vector
+
+revision = "0012_mentor_lessons"
+down_revision = "0011_navigation_persistence"
+branch_labels = None
+depends_on = None
+
+EMBEDDING_DIM = 1536  # settings.EMBEDDING_DIM (snapshot na migration)
+
+
+def upgrade() -> None:
+    op.create_table(
+        "lessons",
+        sa.Column("uuid", sa.Uuid(), primary_key=True),
+        sa.Column("platform_video_id", sa.String(64), nullable=False),
+        sa.Column("program_slug", sa.String(255), nullable=False),
+        sa.Column("module_slug", sa.String(255), nullable=False),
+        sa.Column("video_slug", sa.String(255), nullable=False),
+        sa.Column("title", sa.String(512), nullable=False),
+        sa.Column("duration_seconds", sa.Integer(), nullable=True),
+        sa.Column("provider", sa.String(32), nullable=False),
+        sa.Column("provider_ref", sa.String(255), nullable=False),
+        sa.Column("transcript_text", sa.Text(), nullable=True),
+        sa.Column("transcript_status", sa.String(20), nullable=False),
+        sa.Column("content_hash", sa.String(64), nullable=True),
+        sa.Column("transcribed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("attempts", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("failure_reason", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+    )
+    op.create_index("ix_lessons_platform_video_id", "lessons", ["platform_video_id"], unique=True)
+    op.create_index("ix_lessons_program_slug", "lessons", ["program_slug"])
+    op.create_index("ix_lessons_transcript_status", "lessons", ["transcript_status"])
+
+    op.create_table(
+        "lesson_chunks",
+        sa.Column("uuid", sa.Uuid(), primary_key=True),
+        sa.Column("lesson_id", sa.Uuid(), sa.ForeignKey("lessons.uuid", ondelete="CASCADE"), nullable=False),
+        sa.Column("ordinal", sa.Integer(), nullable=False),
+        sa.Column("content", sa.Text(), nullable=False),
+        sa.Column("start_seconds", sa.Float(), nullable=False),
+        sa.Column("end_seconds", sa.Float(), nullable=False),
+        sa.Column("embedding", Vector(EMBEDDING_DIM), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+    )
+    op.create_index("ix_lesson_chunks_lesson_id", "lesson_chunks", ["lesson_id"])
+    # HNSW por SQL cru: o Alembic não emite `USING hnsw` com opclass.
+    op.execute(
+        "CREATE INDEX ix_lesson_chunks_embedding_hnsw "
+        "ON lesson_chunks USING hnsw (embedding vector_cosine_ops)"
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_lesson_chunks_embedding_hnsw", table_name="lesson_chunks")
+    op.drop_table("lesson_chunks")
+    op.drop_table("lessons")

database/migrations/versions/0013_mentor_trace.py

@@ -0,0 +1,40 @@
+"""Colunas de mentor no agent_traces (spec 2026-09-11 §9.1).
+
+Revision ID: 0013_mentor_trace
+Revises: 0012_mentor_lessons
+Create Date: 2026-09-11
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from pgvector.sqlalchemy import Vector
+
+revision = "0013_mentor_trace"
+down_revision = "0012_mentor_lessons"
+branch_labels = None
+depends_on = None
+
+EMBEDDING_DIM = 1536  # settings.EMBEDDING_DIM (snapshot na migration)
+
+
+def upgrade() -> None:
+    op.add_column("agent_traces", sa.Column("lesson_id", sa.String(64), nullable=True))
+    op.add_column("agent_traces", sa.Column("program_slug", sa.String(255), nullable=True))
+    op.add_column("agent_traces", sa.Column("lesson_coverage", sa.String(16), nullable=True))
+    # Sem índice ANN de propósito: agrupar alguns milhares de perguntas é
+    # varredura, e um HNSW sobre coluna majoritariamente nula só custaria
+    # manutenção (spec §9.1).
+    op.add_column("agent_traces", sa.Column("question_embedding", Vector(EMBEDDING_DIM), nullable=True))
+    op.create_index("ix_agent_traces_lesson_id", "agent_traces", ["lesson_id"])
+    op.create_index("ix_agent_traces_program_slug", "agent_traces", ["program_slug"])
+    op.create_index("ix_agent_traces_lesson_coverage", "agent_traces", ["lesson_coverage"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_agent_traces_lesson_coverage", table_name="agent_traces")
+    op.drop_index("ix_agent_traces_program_slug", table_name="agent_traces")
+    op.drop_index("ix_agent_traces_lesson_id", table_name="agent_traces")
+    op.drop_column("agent_traces", "question_embedding")
+    op.drop_column("agent_traces", "lesson_coverage")
+    op.drop_column("agent_traces", "program_slug")
+    op.drop_column("agent_traces", "lesson_id")

docker/Dockerfile

@@ -4,6 +4,10 @@ FROM python:3.13-slim
 # uv para gerenciar dependências.
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
 
+# ffmpeg/ffprobe: extração e fatiamento de áudio das aulas (Mentor).
+RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
 WORKDIR /app
 
 # Instala dependências primeiro (cache de camadas).

docs/adr/0020-fase-1-do-turno-no-corpo-sse.md

@@ -73,6 +73,10 @@ Falha em gate/retrieve/refuse vira `RUN_ERROR` **depois dos passos já emitidos*
 
 `TurnTimeline` não tem mais os três pontos. Sem atividade, a lista renderiza vazia com `aria-busy` e altura reservada de uma linha; o primeiro passo chega no round-trip HTTP. Protocolo, parser e `useAskStream` não mudam.
 
+### Tool que precisa do banco durante `stream()` (revisão C1/mentor)
+
+O invariante "`stream()` nunca toca o banco" descreve o que o RUNNER garante (nenhum nó do grafo entre `answer` e o fim abre sessão por conta própria); não impede uma TOOL de precisar do banco depois que o escopo 2 já fechou — `search_lesson` (modo mentor) é o primeiro caso: o modelo pode chamá-la várias vezes dentro do tool loop, todo esse loop rodando em `stream()`. A tool resolve isso abrindo o PRÓPRIO escopo curto (`async_session_scope()`, o mesmo helper do escopo 2/3) só para a duração da chamada — e a Action/Repository só podem nascer DENTRO desse `async with`, porque o Repository captura `CurrentAsyncSessionContext.get()` no `__init__`: construí-los antes (ou fora) do escopo deixaria o repositório preso à sessão já fechada do prelúdio, o que vaza conexão e falha de forma não determinística em vez de sempre. A regra prática vale para qualquer tool futura na mesma situação: se ela precisa do banco e roda em `stream()`, abre seu próprio `async_session_scope()` e constrói tudo o que capture sessão lá dentro — nunca herda a sessão de um escopo que já era do chamador.
+
 ## Consequências
 
 **Positivas**