alyah@decisionpath: ~/docs — zsh
> Every decision leaves a trace. Make it searchable.
Um framework de Context Graph para capturar, traçar e reutilizar o conhecimento de decisões tomadas por humanos, agentes de IA e sistemas híbridos — transformando raciocínio efêmero em precedente estruturado. Se o OpenTelemetry padronizou a captura de execução e o Git a captura de mudanças de código, o DecisionPath padroniza a captura de decisões.
CRMs, ERPs e bancos de dados armazenam estado: o negócio foi fechado, o ticket foi escalado. Eles não armazenam por que aquele estado foi alcançado. A lógica de exceção vive em cabeças humanas, conversas de Slack e reuniões de aprovação. Quando um agente de IA precisa decidir, ele começa do zero.
Decisões humanas morrem em Slack, e-mails e cabeças — sem estrutura persistente. O melhor atendente se aposenta e leva 15 anos de intuição. Agentes não têm precedente e humanos repetem os mesmos erros.
Decisões de agentes são capturadas como logs de execução — latência, tokens, custo — não como raciocínio semântico. Soluções como LangSmith e Langfuse capturam o que o agente fez, não por que ele decidiu.
Decisões híbridas (humano + agente) não têm um modelo que atribua responsabilidade. Quem propôs? Quem aprovou? Quem sobrescreveu? Sem essa cadeia, conformidade e auditoria são impossíveis.
┌─────────────────────────────────────────────────────────────────────┐ │ every decision is a path. every path is knowledge. │ │ every decision leaves a trace. make it searchable. │ └─────────────────────────────────────────────────────────────────────┘
DecisionPath modela cada decisão como um nó em um Context Graph — um grafo direcionado acíclico (DAG) conectando problema, atores, raciocínio, alternativas, políticas e outcome. O schema é agnóstico a domínio, framework e tipo de decisor.
Cada decisão — humana, de agente ou híbrida — é interceptada no exato momento em que é tomada (commit-time capture). O trace contém problema, opção escolhida, alternativas consideradas, políticas aplicadas, precedentes citados e metadados temporais. Três modos de ingestão: stream via SDK/OTel, batch retroativo (CSV, JSON Lines, OTLP) e captura humana (formulário, voice-to-trace, extração de Slack).
O LLM Enricher extrai entidades, políticas e alternativas do texto livre. Dois embeddings são gerados: Reasoning Embedding (similaridade semântica via HNSW) e FastRP Embedding (similaridade topológica no grafo). PII é detectado e anonimizado antes da persistência. O trace é persistido como nós e arestas no Context Graph (Neo4j).
Busca semântica encontra raciocínios similares via vector search. Busca estrutural navega a cadeia causal no grafo (quem decidiu, o que causou). Busca híbrida combina vector + graph traversal + re-ranking por FastRP. Busca temporal detecta padrões, regressões e anomalias ao longo do tempo. P95 < 300ms para top_k=10.
O resultado é um Decision Packet padronizado: decisão, contexto completo, evidence path, proveniência e score. Servido via REST API, SDK Python/TypeScript, CLI ou MCP Server para agentes. O agente recebe precedentes reais e toma decisões fundamentadas em conhecimento acumulado — não em adivinhação.
API unificada para registrar decisões e consultar caminhos. Compatível com LangGraph, Agno, AutoGen, OpenAI SDK e CrewAI. Funciona via SDK, CLI ou MCP Server.
Agnóstico a domínio, framework de agentes e tipo de decisor. Ontologia emergente: o schema não é definido upfront, mas aprendido a partir dos próprios traces acumulados.
Stream Collector (OTel/SDK) para agentes em tempo real. Batch Importer para bases legadas (CSV, JSON Lines, OTLP, JDBC). Human Capture Interface para decisões humanas via formulário, voice-to-trace e extração inferida de Slack/email.
Normalização para schema canônico. LLM Enricher extrai entidades, políticas e alternativas. Embedding Pipeline gera Reasoning Embedding (semântico) e FastRP Embedding (estrutural). PII Redactor anonimiza dados sensíveis antes da persistência.
Neo4j como Context Graph Store (nós, arestas, propriedades). Vector Index HNSW para embeddings semânticos e estruturais. Redis para cache de sessões ativas. S3/MinIO para payloads brutos e PII criptografado. ClickHouse opcional para analytics.
Search API com 4 modos (semântica, estrutural, híbrida, temporal). MCP Server expõe 5 tools para agentes. GraphRAG Interface para RAG com proveniência explicável. SDK Python/TypeScript e CLI para integração direta.
24 features planejadas em 4 fases. Cada componente projetado para produção com milhões de traces, busca sub-segundo e rastreabilidade completa. LGPD/GDPR by design.
Grafo de 12 tipos de nós universais (Problem, Actor, Decision, Alternative, Policy, Outcome, Entity...) com 13 tipos de arestas. Traces imutáveis — correções criam nós com aresta SUPERSEDES, preservando histórico completo.
Semântica (HNSW k-NN), estrutural (Cypher traversal), híbrida (vector + graph + re-ranking FastRP) e temporal (padrões e anomalias). Decision Packets com evidence path e proveniência. P95 < 300ms.
5 tools via protocolo MCP: search_precedents, record_decision, get_causal_chain, get_applicable_policies e find_similar_outcomes. Qualquer agente LangGraph, Agno ou Claude consome no momento da decisão.
Namespace isolado por tenant com ACL no Neo4j. Buscas cross-tenant proibidas por padrão. PII Redactor obrigatório (CPF, CNPJ, nome, email). Payload original criptografado AES-256 com ACL restrita. Direito ao esquecimento built-in.
Humana (formulários, voice, Slack/email), de agentes (SDK, OTel spans, chain-of-thought) e híbrida (propõe → aprova → executa). Modelo de responsabilidade: proposed_by, approved_by, override. Co-existem no mesmo grafo.
Outcomes retroalimentam scores de confiança. Override Tracker registra quando humanos sobrescrevem agentes. Precedent Linker detecta automaticamente decisões similares. Pattern Alerts notificam loops e override rates anômalos.
DecisionPath é uma ponte entre quem decide e quem precisa entender a decisão. Seis tipos de atores interagem com o grafo — como fontes e como consumidores.
Emite spans via SDK durante execução. Busca precedentes antes de decidir. Recebe Decision Packets via MCP Server.
Captura decisões via formulário, voice-to-trace ou extração de Slack/email. O conhecimento tácito vira precedente durável.
Consulta cadeia causal completa. Rastreia quem decidiu, quando, por quê e qual resultado. Export em formatos regulatórios.
Debugging de comportamentos de agentes. Decision Replay reproduz o contexto original. Compara alternativas e valida resultados.
O schema define primitivos universais (Problem, Actor, Decision, Policy, Outcome). O significado semântico é propriedade livre, não imposta pelo framework. Adapta-se a qualquer domínio onde decisões importam.