Horus Context Layer

Contexto & tese

O gargalo real da escala não é o sistema de processos nem os agentes — é o banco de contexto. Na escala, o problema vira perda de contexto das IAs e a ausência de uma base viva, alimentada todos os dias. Três estudos (Atlan, AI Labs) convergem com Ask Gartner e Ironclad numa tese única:

• Modelo é commodity; contexto é o IP proprietário. O diferencial defensável é a camada de contexto, não o LLM.
• Três problemas matam IA em produção e vão aparecer na Horus na escala.

🧊 Cold start: montar contexto leva 5–12 meses no modo manual.

📉 Limiar de 70% de acurácia: abaixo disso o agente é abandonado.

🔀 Context portability: cada agente aprende isolado → respostas divergentes (context drift).

Referências de mercado que guiam o desenho: Ask Gartner = corpus curado, atualizado continuamente, respostas sempre com citação e governança. Ironclad = captura estruturada a partir do fluxo operacional normal + playbooks (efeito de rede: cada uso enriquece a base).

Decisões do Tales (2026-05-30)

• Corpus jurídico BR primeiro.
• North-star: O Estagiário / petições (legal-agent-builder aterrado em jurisprudência real via RAG).
• Feeder moderado (~US$100–300/mês; bursts no bootstrap + janelas diárias).
• Fontes oficiais / APIs públicas (baixo risco jurídico).

🎯 Resultado pretendido: a maior e mais confiável base de contexto jurídico-operacional do Brasil — viva — elevando a acurácia rumo a "o advogado sênior concordaria com essa resposta".

Onde se encaixa no ecossistema

Recorte canônico atualizado (2026-05-30): 5 produtos + 2 repos de infra cross-product. O Context Layer aterra os agentes existentes, começando pelo north-star.

Infra cross-product: horus-core (Supabase schema core, outbox, dispatcher, Edge Functions, Actions orchestrator, ai_ops) e thoth (lib pública de skills, via submodule). O plano reaproveita ao máximo o que já existe: @horus/ai, @horus/db, @horus/legal-rag (Tier-2 roadmapado), protocolo lab-experiments (EXP-005 é literalmente este caso) e os 3 caminhos de integração com Lovable.

⚠️ Fora do recorte: CSI Jurídico e Portal Horus não fazem parte dos produtos canônicos atuais.

Arquitetura-alvo

Onde mora

Projeto Supabase dedicado horus-context (org Horus Hub.dev, ehmnvkxxakysopaigkje) — não dentro do core. Volume alto (milhões de chunks + embeddings pgvector HNSW) não pode inchar o horus-core, que precisa ser leve e estável. Escala, custo e backup ficam isolados. Vínculo com core.tenants por tenant_id opcional (corpus público é cross-tenant; traces operacionais são por tenant). Cumpre a Condição 1 do ADR-005 v2 nativamente (org própria).

As 4 camadas (Atlan → Horus)

Layer 1 · Fontes oficiais BR
  LexML · Planalto/LeisBR · DOU · Dados abertos STF/STJ/TST/CNJ · Diários oficiais
  └─ [Ingestion Agent SDK (feeder)]
     ▼
Layer 2 · Enterprise Data Graph — schema `ingest`
  source registry · job/runs · linhagem · proveniência · freshness · dedup (hash/idempotency)
     ▼
Layer 3 · Context Layer — `legal_knowledge` + `context`
  documentos + chunks + embeddings (pgvector) · metadados (tribunal, área, ementa,
  tese, dispositivo, citações) · ontologia · sinais de confiança · política de acesso
  └─ [@horus/legal-rag — híbrido + rerank + citações]
     ▼
Layer 4 · Agentes
  Estagiário/legal-agent-builder (north-star) → depois CSI · JurisLab · operação interna
  └─ [decision traces (Fase 3)]
     ▼
Layer 3'' · Context Graph — `context.decision_traces`
  cada peça gerada / correção do advogado / aprovação → MVDT → realimenta o flywheel

Stack técnica (decisões)

Modelo de dados

Migrations no horus-context, em três schemas.

ingest — Layer 2 (proveniência/linhagem)

• sources — registro de cada fonte (slug, base_url, tipo, robots/ToS ok, cadência, parser).
• ingest_runs — cada execução do feeder (source_id, started/finished, status, counts, custo_tokens, model_used).
• raw_documents — payload bruto + content_hash (dedup idempotente), url, fetched_at, source_id.

legal_knowledge — Layer 3 (corpus consultável)

• documents — 1 linha por peça canônica: tipo (jurisprudencia|legislacao|sumula|doutrina), tribunal/órgão, área, número, datas, relator, status (vigente|revogado|superado), valid_at/valid_until (temporalidade — crítico: lei muda), citações (jsonb), url_oficial.
• chunks — texto + embedding vector + tsv tsvector + metadados herdados + tipo de seção.
• citations — arestas documento→documento (precedente/cita/revoga) → grafo via recursive CTE.

-- Retrieval híbrido (BM25 + vetorial, RRF) + rerank + citação obrigatória
function search_chunks(
  query       text,
  filtros     jsonb,   -- {tribunal, area, status, valid_at}
  k           int      -- top-k
) returns table(
  chunk_id    uuid,
  documento   jsonb,   -- tipo, tribunal, data, url_oficial
  trecho      text,
  score       numeric, -- confiança 0–1 (N fontes convergentes)
  url_oficial text     -- citação (nunca responder sem fonte)
)

context — semântica + decisões

• glossary / ontology — termos jurídicos canônicos, sinônimos, mapeamentos (ex: "dano moral" ↔ variações), área.
• decision_traces (Fase 3 — o "todos alimentam") — MVDT: o que foi gerado/decidido, por qual agente/usuário, tenant, fontes citadas (linka documents), outcome (aceitou/editou/rejeitou), policy_version, valid_at.

📊 Telemetria sempre em colunas dedicadas (model_used, *_tokens, generation_ms) — padrão de core.strategies. Traces de IA seguem em ai_ops.*.

O Agent SDK feeder

App apps/ingestor no monorepo, usando Claude Agent SDK + @horus/ai + @horus/db. "Abastece sem parar até a base ficar sólida." Loop por fonte:

1. Discover — Lista novos itens da fonte oficial desde o último valid_at ingerido (cursor por fonte).
2. Fetch + dedup — Baixa, calcula content_hash, pula se já existe em ingest.raw_documents.
3. Parse + structure — O agente extrai metadados estruturados (tribunal, área, ementa, tese, dispositivo, citações) — context engineering, não scraping burro.
4. Chunk + embed — Chunking estrutural → embeddings Voyage → grava em legal_knowledge.
5. Link — Resolve citações/precedentes → arestas em citations.
6. Self-chain — Emite o próximo job (repository_dispatch) até esgotar o slice; respeita o teto de custo/dia.

Cadência (moderado)

• Bootstrap: jobs self-chaining processam o backlog por área prioritária (Trabalhista → Previdenciário → Cível). Teto diário de tokens; pausa e retoma.
• Steady-state (rotina macro diária): cron por fonte pega só o delta (legislação nova, julgados novos, DOU do dia).

🎛️ Custo/qualidade: teto diário em ingest.sources.config; tier:'fast' p/ parsing, balanced só onde precisa; toda run loga custo; circuit-breaker por fonte.

🛡️ Compliance: só fontes com robots/ToS ok; sempre guardar url_oficial (citação/auditoria); nunca apresentar texto sem fonte rastreável. Corpus público sem PII; traces (Fase 3) com RLS por tenant (ADR-007).

Retrieval & uso (@horus/legal-rag)

• search(query, filtros) → híbrido (BM25 + vetorial, RRF) → rerank Voyage → top-k com citação obrigatória + score de confiança.
• Confiança alta = N fontes convergentes; baixa/ambígua = "tese controvertida, eis os dois lados" em vez de chutar (padrão Ironclad/Gartner).
• Exposto a: orchestrator (handlers), Edge Function HTTP (Lovable) e RPC SQL direto.

⭐ North-star: o legal-agent-builder (Estagiário) passa a gerar peças citando jurisprudência real recuperada — vira o caso EXP-005.

Context Engineering Loop

A disciplina que garante o 5x (AI Labs), aterrada no protocolo lab existente (lab-experiments/, ai_ops):

1. Golden questions — 20–30 perguntas reais de petição (Trabalhista primeiro), com tese/precedente esperado → vira o eval/regression suite.
2. Baseline vs context — Roda o legal-agent-builder sem e com @horus/legal-rag; mede acurácia e consistência.
3. Failures = context bugs — Cada recuperação errada vira bug de metadado (chunking, ontologia, filtro), corrigido uma vez na camada → todas as perguntas herdam.
4. Human ON the loop — Advogado decide só os pontos de julgamento (tese controvertida, precedente superado); a decisão volta como decision_trace.
5. Outer loop — Uso em produção revela edge cases → novas golden questions.

🏁 Meta de promoção (ADR-006 / PROMOTION-CHECKLIST): ~80% acurácia + ~70% consistência antes de escalar do Estagiário pro CSI/JurisLab.

Roadmap por fases

Artefatos a criar & tracking

• horus-context migrations — schemas ingest, legal_knowledge, context.
• horus-monorepo/packages/legal-rag/ — @horus/legal-rag (reusa @horus/ai, @horus/db).
• horus-monorepo/apps/ingestor/ — Agent SDK feeder.
• .github/workflows/ingestor-bootstrap.yml + ingestor-cron.yml.
• ADR-011-context-layer.md — registra as decisões (Supabase dedicado, pgvector, voyage-law-2, grafo relacional).
• lab-experiments/EXP-005-* — hipótese + golden questions.
• horus-context/docs/ — source registry + runbook de ingestão + política de fontes/compliance.

📌 Tracking: epic "Horus Context Layer" no horus-core + issues por fase com labels (area:infra/area:estagiario/area:fluxo-05, sprint:*, status:approved).

Pré-requisitos & verificação

Bloqueado em Tales

• Instalar Node + Supabase CLI + gh CLI no Windows (ambiente só tem git).
• Secrets/contas: Voyage AI API key; confirmar créditos Anthropic; service role do horus-context (após criar o projeto).
• Confirmar ordem de áreas (assumido Trabalhista → Previdenciário → Cível).

Como provar que funciona (ponta a ponta)

• Pipeline: rodar o ingestor na fonte piloto → conferir ingest_runs (counts/custo) e documents/chunks com embeddings não-nulos.
• Retrieval: chamar search_chunks('<tese trabalhista>') → top-k relevante com url_oficial e score; rerank melhora a ordem.
• North-star: gerar petição com e sem @horus/legal-rag; rodar golden questions; medir ganho (meta ~80%/~70%).
• Rotina macro: disparar o cron (workflow_dispatch) → só o delta do dia é ingerido (dedup por content_hash).
• Custo: somar ingest_runs.custo_tokens da semana → dentro do teto (~US$100–300/mês).
• Decision trace (Fase 3): gerar peça → MVDT em decision_traces ligado às fontes; simular correção → outcome atualizado.