Camada de Inteligência Científica

O lean-ctx vai além da correspondência de padrões. Seis algoritmos de teoria da informação, teoria dos grafos e mecânica estatística trabalham juntos para decidir o que manter, o que cortar e onde posicionar - tudo automaticamente, tudo localmente, zero configuração.

Esses algoritmos alimentam a camada de inteligência autônoma. Eles são ativados durante cada chamada de ctx_read, ctx_preload e ctx_overview - você nunca os invoca diretamente.

Como as camadas interagem

Pontuação de Surpresa Preditiva

Filtros de compressão tradicionais usam entropia de Shannon em caracteres brutos, que trata aaaa e import como igualmente previsíveis. A Surpresa Preditiva mede a entropia cruzada em relação à frequência de tokens BPE - quão surpreendente cada linha é para o tokenizador do LLM.

Como funciona

1. Cada linha é tokenizada usando o200k_base (tokenizador GPT-4o / Claude).
2. Para cada token, uma distribuição Zipfiana estima a frequência esperada com base na posição.
3. A entropia cruzada é calculada: linhas com tokens comuns (boilerplate) recebem pontuação baixa; linhas com tokens raros (lógica complexa) recebem pontuação alta.
4. Linhas abaixo do limiar de surpresa são candidatas à remoção durante a compressão agressiva.

Exemplo

// Low surprise (boilerplate) - candidate for removal:
return Ok(());                    // surprise: 0.12
use std::collections::HashMap;   // surprise: 0.18

// High surprise (unique logic) - always preserved:
let decay = (-alpha * dist as f64).exp();   // surprise: 0.89
scores[j] += heat[i] * decay / degree;      // surprise: 0.94

Por que isso importa

A Surpresa Preditiva remove 15–30% mais boilerplate do que a entropia em nível de caractere, preservando a lógica complexa. Ela modela diretamente o que o LLM considera "informativo" porque usa o mesmo vocabulário BPE.

Propagação de Relevância Espectral

Quando você pede ao lean-ctx para pré-carregar contexto para uma tarefa, ele precisa decidir quais arquivos importam. A correspondência simples por palavras-chave só encontra arquivos que mencionam seus termos de busca. A Relevância Espectral encontra arquivos que estão estruturalmente conectados aos relevantes - mesmo que não compartilhem palavras-chave.

Como funciona

Dois algoritmos de grafos são executados no grafo de dependências do projeto:

1. Difusão de Calor - Arquivos-semente que correspondem à descrição da tarefa recebem "calor" inicial. O calor se espalha pelas arestas de importação com decaimento exponencial, simulando o fluxo de informação pela base de código.
2. Centralidade PageRank - Arquivos importados por muitos outros arquivos recebem pontuações de centralidade mais altas. Isso identifica hubs estruturais (ex.: um db.ts importado por 20 módulos).

A pontuação final de relevância combina ambos: 0.7 × heat + 0.3 × pagerank. Arquivos abaixo do limiar são excluídos do pré-carregamento.

Exemplo

Task: "fix authentication bug"

Direct matches:       auth.ts, login.ts
Heat diffusion adds:  middleware.ts (imports auth.ts)
                      session.ts (imported by auth.ts)
PageRank promotes:    db.ts (imported by 18 files - structural hub)

Result: 5 files preloaded instead of 2, covering the full blast radius.

Zero configuração

O grafo de dependências é construído automaticamente no primeiro uso via load_or_build(). Nenhum ctx_graph build necessário - simplesmente funciona.

Alocação de Contexto de Boltzmann

Depois que a Relevância Espectral seleciona os arquivos relevantes, cada arquivo precisa de um orçamento de tokens. Abordagens ingênuas atribuem orçamentos iguais ou ordenam por relevância. A Alocação de Boltzmann usa mecânica estatística para distribuir tokens de forma otimizada.

Como funciona

1. Cada arquivo tem uma pontuação de relevância E_i da Relevância Espectral.
2. Um parâmetro de temperatura β é derivado da tarefa: tarefas específicas ("corrigir bug de autenticação em login.ts") produzem baixa temperatura (alocação concentrada nos arquivos principais); tarefas amplas ("refatorar a base de código") produzem alta temperatura (distribuição uniforme).
3. Os orçamentos de tokens seguem a distribuição de Boltzmann: budgeti = total × (eβ·Ei / Σ eβ·Ej)
4. Orçamentos mínimos e máximos são aplicados (128–4096 tokens por arquivo), e o modo de compressão (full, map, signatures) é escolhido com base no orçamento alocado.

Exemplo

Task: "fix the JWT validation in auth middleware"
Task specificity: 0.85 (specific) → β = 4.2

File            | Relevance | Budget | Mode
auth.ts         |      0.92 |  3,200 | full
middleware.ts   |      0.78 |  1,800 | full
session.ts      |      0.45 |    420 | map
db.ts           |      0.31 |    180 | signatures
routes.ts       |      0.22 |    128 | signatures
                                ─────
Total:                         5,728 tokens (within 8,000 budget)

Reciprocal Rank Fusion (RRF) Cache Eviction

lean-ctx uses Reciprocal Rank Fusion for cache eviction decisions, replacing the earlier Boltzmann-inspired weighted scoring. RRF handles incomparable signals (time in seconds, frequency as counts, size in tokens) without arbitrary weight tuning.

Formula: RRF(d) = Σ 1/(K + ranki(d)) - entries with the lowest fused score are evicted first. This produces monotonically correct ordering regardless of signal magnitude differences.

Chunking Semântico com Pontes de Atenção

LLMs sofrem do problema "Perdido no Meio": informações no início e no final do contexto recebem mais atenção do que o conteúdo no meio. O Chunking Semântico reestrutura a saída para minimizar a perda de informação.

Como funciona

1. Detecção de Chunks - As linhas de código são agrupadas em chunks semânticos (funções, tipos, imports, lógica solta) com base em heurísticas de limites da AST.
2. Ordenação por Relevância - Chunks que correspondem à tarefa atual são promovidos ao topo (posição de alta atenção). Os chunks restantes são ordenados por prioridade de tipo.
3. Pontes de Atenção - Entre os chunks, o lean-ctx insere marcadores de ponte mínimos (---) para que o LLM reconheça os limites estruturais.
4. Âncoras Finais - As últimas 2–3 linhas do chunk de maior prioridade são repetidas no final da saída, explorando o viés de recência para informações críticas.

Exemplo

// Without chunking (flat output):
import { db } from '../pages/docs/db';
import { hash } from '../pages/docs/crypto';
const MAX_RETRIES = 3;
export function createUser(...) { ... }
export function validateToken(...) { ... }    ← lost in the middle
export function deleteUser(...) { ... }

// With semantic chunking (task: "fix token validation"):
export function validateToken(...) { ... }    ← promoted to top
---
export function createUser(...) { ... }
export function deleteUser(...) { ... }
---
import { db } from '../pages/docs/db';
const MAX_RETRIES = 3;
---
// anchor: validateToken signature                ← tail anchor

Deduplicação MMR

Quando múltiplos arquivos são carregados no contexto, eles frequentemente contêm imports duplicados, boilerplate compartilhado ou padrões de código muito similares. A Relevância Marginal Máxima (MMR) remove essa redundância preservando informações únicas.

Como funciona

1. Para cada linha, calcula a similaridade de Jaccard por bigramas em relação a todas as linhas previamente selecionadas (o "conjunto de cobertura").
2. A pontuação MMR equilibra relevância contra redundância: MMR(l) = λ × relevance(l) - (1 - λ) × max_similarity(l, selected)
3. Linhas com MMR < 0 são suprimidas - elas adicionam mais redundância do que informação. O parâmetro λ tem valor padrão de 0,7 (favorecendo relevância sobre diversidade).

Impacto

Em um carregamento típico de múltiplos arquivos, o MMR remove 10–25% do conteúdo redundante - principalmente imports compartilhados e padrões utilitários repetidos.

Otimização de Tokens Alinhada ao BPE

Após todo o conteúdo ser selecionado e ordenado, uma passagem final otimiza o texto bruto para o tokenizador BPE do LLM. Pequenas alterações de formatação podem reduzir significativamente a contagem de tokens sem alterar a semântica.

Regras de otimização

Como funciona

Cada regra é uma simples substituição de string aplicada linha a linha após todas as outras etapas de compressão. As regras são derivadas da análise de limites de tokens BPE - elas visam padrões onde o tokenizador produz tokens desnecessariamente numerosos para texto semanticamente equivalente.

Impacto

A otimização BPE normalmente economiza 3–8% de tokens adicionais em saídas já comprimidas. A economia se acumula entre arquivos e é mais significativa para linguagens verbosas (TypeScript, Java, C#).

Verificando o impacto

Execute lean-ctx benchmark run no seu projeto para medir o efeito combinado dos seis algoritmos. O relatório do benchmark mostra economia de tokens por arquivo, pontuações de preservação (AST, identificadores, linhas) e taxas de compressão gerais.

$ lean-ctx benchmark run
──────────────────────────────────────────
BENCHMARK - /Users/you/project
──────────────────────────────────────────
Files:       143
Total:       285,401 → 42,810 tokens (85% reduction)
Avg/file:    1,997 → 300 tokens

Preservation:
  AST:         98.2%
  Identifiers: 97.4%
  Lines:       96.1%

Mode breakdown:
  full:        68% of files
  map:         22% of files
  signatures:   8% of files
  aggressive:   2% of files

Reconhecimento estruturado de intenção

lean-ctx classifica cada interação em um StructuredIntent - uma representação baseada em slots contendo tipo de tarefa, confiança, arquivos alvo, escopo, dica de idioma, urgência e verbo de ação. Isso dirige todas as decisões subsequentes: qual modo de compressão usar, como rotear o contexto e o que priorizar.

9 tipos de tarefa são reconhecidos: Explore, Generate, FixBug, Refactor, Test, Review, Config, Deploy e Document. Cada tipo dispara diferentes estratégias de compressão e roteamento de contexto.

IntentScope vai de SingleFile passando por MultiFile e CrossModule até ProjectWide - determinando a amplitude da coleta de contexto.

Como funciona

A compressão se adapta por intenção: tarefas FixBug priorizam linhas de erro e arquivos de teste via filtro Information Bottleneck, tarefas Explore usam limpeza leve para preservar estrutura, e tarefas Generate focam em assinaturas e tipos.

O seletor de modo automático do ctx_read usa o tipo de tarefa ativo para refinar sua decisão - escolhendo modo task para correções de bugs em arquivos grandes, modo map para exploração e modo signatures para tarefas de documentação.

Exemplo

Query: "fix the NaN bug in entropy.rs"

StructuredIntent:
  task_type:    FixBug (confidence: 0.95)
  targets:      ["entropy.rs"]
  scope:        SingleFile
  language:     Rust
  urgency:      0.8
  action_verb:  "fix"

→ Compression: Information Bottleneck filter (error lines boosted)
→ Mode:        task (error-focused extraction)
→ Suggestions: tests/entropy_test.rs (deficit detection)

Arquitetura do pipeline de contexto

O pipeline de contexto processa informações através de seis camadas distintas: Input → Intent → Relevance → Compression → Translation → Delivery. Cada camada tem contratos definidos (tipos de entrada/saída) e emite métricas.

Como funciona

Input → Intent → Relevance → Compression → Terse Engine → Delivery
  │        │          │            │              │              │
  │        │          │            │              │              └─ Final output to LLM
  │        │          │            │              └─ 4-layer terse pipeline (see below)
  │        │          │            └─ AST-aware compression per intent
  │        │          └─ Graph heat + relevance scoring
  │        └─ StructuredIntent classification
  └─ Raw file content / shell output

Métricas por camada rastreiam tokens de entrada, tokens de saída, taxa de compressão e tempo de processamento. Agregadas em uma sessão, revelam onde as maiores economias ocorrem e quais camadas são gargalos.

4-Layer Terse Engine

The terse engine applies four composable compression layers, controlled by compression_level (Off / Lite / Standard / Max). Each layer is independently verified by Lean4 proofs (TerseQuality, TerseEngine — part of 82 total theorems).

Livro de contexto e gestão de pressão

O ContextLedger rastreia cada arquivo enviado à IA: caminho, modo de compressão, tokens originais, tokens enviados e marca temporal. Calcula a utilização da janela de contexto e a pressão em tempo real.

Como funciona

Três níveis de pressão: None (menos de 70% de utilização), Compress (70–90%) e Evict (acima de 90%). Em cada nível, o sistema toma ações diferentes - rebaixando modos de compressão para arquivos menos relevantes ou sugerindo despejos.

Exemplo

Context Window: 128,000 tokens
Loaded: 89,600 tokens (70% utilization)
Pressure: None → safe

After loading 3 more files:
Loaded: 115,200 tokens (90% utilization)
Pressure: Compress → downgrade non-target files

Re-Injection Plan:
  utils.rs:    full → signatures  (save 2,400 tokens)
  helpers.rs:  full → map         (save 1,800 tokens)
  config.rs:   full → signatures  (save 1,200 tokens)
  Protected:   auth.rs, login.ts  (target files)

A detecção de déficit de contexto identifica informações ausentes: se uma correção de bug visa auth.rs mas nenhum arquivo de teste está carregado, o sistema sugere tests/auth_test.rs. Para tarefas de configuração, recomenda Cargo.toml, .env ou Dockerfile.

A reinjeção inteligente gera um plano para liberar orçamento de contexto rebaixando arquivos não-alvo (ex. mudança de modo full para signatures) enquanto protege arquivos críticos para a intenção atual.

Inteligência multi-agente

Quando múltiplos agentes de IA colaboram (ex. um programador e um revisor), lean-ctx fornece transferências estruturadas, profundidade de contexto baseada em papéis e compartilhamento de conhecimento entre agentes.

Como funciona

HandoffPackage agrupa o livro de sessão atual, a intenção estruturada e o snapshot do contexto em uma unidade transferível - para que o agente receptor comece com consciência situacional completa em vez de uma página em branco.

Sete papéis de agente são reconhecidos: Coder, Reviewer, Planner, Explorer, Debugger, Tester e Orchestrator. Cada um recebe uma ContextDepthConfig personalizada - um Programador obtém mais leituras completas, um Revisor mais assinaturas, um Explorador contexto de grafo mais amplo.

Exemplo

Agent "coder-1" (role: Coder):
  max_files_full: 8
  preferred_mode: full
  context_budget: 80%

Agent "reviewer-1" (role: Reviewer):
  max_files_full: 3
  preferred_mode: signatures
  context_budget: 60%

Shared Knowledge:
  K:discovery:auth_bug = "null check missing in line 42"
  K:decision:fix_approach = "add Option<T> wrapper"
  → reviewer-1 inherits these facts without re-reading files

O compartilhamento de conhecimento entre agentes permite que agentes troquem fatos estruturados (ex. "discovery:auth_bug=verificação null ausente na linha 42") via bloco de notas compartilhado. Novos agentes herdam conhecimento relevante sem precisar redescobri-lo.

Community Detection (Louvain)

The core::community module clusters files by their dependency graph using the Louvain algorithm. This groups tightly-coupled files into communities, enabling more intelligent context selection — files in the same community as your target are prioritized for preloading and receive higher relevance scores during task-driven reads.

Code Smell Detection

The ctx_smells tool detects long functions, deep nesting, and high cyclomatic complexity using the core::smells module. Detected smells are scored with graph-enriched weighting — files with high PageRank or many dependents receive amplified smell scores, surfacing maintenance hotspots that have the widest blast radius across the codebase.

Veja também

• Ferramentas de Inteligência Autônoma - as ferramentas que usam esses algoritmos
• Motor tree-sitter - análise AST para 18 linguagens
• Configuração - ajustando limiares e configurações de autonomia
• Benchmark - medindo sua economia