rootly-graphify

Construído sobre graphify, uma ferramenta inspirada pela ideia de LLM Wiki de Andrej Karpathy — em vez de redescobrir conhecimento do zero a cada consulta, faça um LLM construir um grafo de conhecimento persistente e estruturado que se torna mais rico ao longo do tempo. Graphify pega qualquer pasta de arquivos e a transforma em um grafo consultável com comunidades, conexões e pontuações de confiança. Este fork o direciona para a API do Rootly.

Conecte a API do Rootly, colete incidentes, alertas, equipes e o catálogo de serviços para uma janela de tempo selecionada, exporte-os para um corpus local e transforme esse corpus em um grafo de conhecimento consultável. Use graphify rootly para coleta e /graphify no Claude Code ou Codex quando quiser uma análise semântica mais profunda sobre os dados.

Instalação

Instalação nova (Graphify + Importador Rootly):

pip install "graphifyy[rootly]"
graphify install            # Claude Code
graphify install --platform codex  # Codex

Adicionar importador Rootly a uma configuração Graphify existente:

pip install "graphifyy[rootly]" --upgrade

Defina sua chave da API do Rootly

Crie um arquivo .env na raiz do seu projeto:

ROOTLY_API_KEY=rootly_...

Execute o fluxo de trabalho

Passo 1: Buscar e construir (terminal)

Busca incidentes, alertas acionados e equipes. Constrói o grafo inicial com cores de severidade, filtros de alerta e camadas de equipe/serviço.

graphify rootly

Não interativo:

graphify rootly --api-key-env ROOTLY_API_KEY --days 30 --mode standard

Resultados escritos em graphify-rootly-data/graphify-out/:

• graph.html — abra no navegador para explorar o grafo
• GRAPH_REPORT.md — nós principais, comunidades, perguntas sugeridas
• graph.json — grafo bruto para consulta

Passo 2: Adicionar significado semântico (agente)

Executa subagentes paralelos sobre o corpus de incidentes para inferir temas entre incidentes, padrões recorrentes e relações de causa raiz.

Claude Code — digite no chat:

/graphify graphify-rootly-data --mode deep

Codex — digite no chat:

run graphify on graphify-rootly-data --mode deep

O que você pode explorar

O que é coletado

Filtros de visualização

Uma vez que graph.html está aberto no navegador:

• Equipe — filtre todos os nós para os incidentes e serviços de uma equipe específica
• Severidade — mostrar/ocultar por SEV1–SEV4
• Incidentes — todos ou apenas abertos
• Alertas — acionados (ativo por padrão) / órfãos (desativado por padrão, não coletados)
• Intervalo de tempo — controle deslizante para restringir a janela de incidentes

Como funciona

rootly-graphify tem uma fase de coleta Rootly e uma fase de análise de grafo.

1. Coleta Rootly determinística. Valide a chave da API, escolha uma janela de 7, 30 ou 90 dias, busque incidentes cujo started_at esteja dentro dessa janela, busque seus alertas acionados através do sub-recurso por incidente, busque todos os dados de equipe e escreva tudo em um diretório de corpus local.

2. Construção inicial do grafo Rootly. O executor Rootly embutido cria nós para incidentes, alertas, equipes e serviços, conecta-os com arestas tipadas (triggered, affects, owns, responded_by, targets), agrupa o grafo e escreve graph.html, GRAPH_REPORT.md e graph.json. O HTML inclui codificação de cores por severidade, camadas de equipe/serviço e filtros de alerta.

3. Enriquecimento profundo opcional. Execute /graphify ./graphify-rootly-data --mode deep para despachar subagentes paralelos sobre os arquivos markdown e inferir temas entre incidentes, justificativas e links conceituais.

4. Use a saída atual de nível superior. Após o enriquecimento semântico, abra . O exportador genérico atual já inclui os filtros mantidos e visuais diretamente, portanto, nenhuma etapa separada de reaplicação é necessária.

O agrupamento é baseado em topologia de grafo — sem embeddings. Leiden encontra comunidades por densidade de arestas. Arestas de similaridade semântica (semantically_similar_to, marcadas como INFERRED) influenciam diretamente a detecção de comunidades. Nenhuma etapa separada de embedding ou banco de dados vetorial é necessária.

Cada relacionamento é marcado como EXTRACTED (encontrado diretamente na fonte), INFERRED (inferência razoável, com uma pontuação de confiança) ou AMBIGUOUS (sinalizado para revisão).

O que você obtém

Nós principais — incidentes ou serviços de maior grau (por onde tudo se conecta)

Conexões surpreendentes — links entre incidentes classificados por pontuação composta, cada um com uma explicação em linguagem simples

Perguntas sugeridas — 4–5 perguntas que o grafo está exclusivamente posicionado para responder sobre seu histórico de incidentes

Pontuações de confiança — toda aresta INFERRED tem um confidence_score (0.0–1.0). Arestas EXTRACTED são sempre 1.0.

Arestas de similaridade semântica — links conceituais entre incidentes sem conexão estrutural. Dois incidentes causados pelo mesmo padrão raiz sem compartilhar serviços ou equipes.

Eficiência de tokens — a primeira execução extrai e constrói o grafo (custa tokens). Cada consulta subsequente lê o grafo compacto em vez do markdown bruto — é aí que as economias se acumulam. O cache SHA256 significa que as reexecuções só reprocessam arquivos alterados.

Uso

# --- Rootly workflow (terminal) ---
graphify rootly                                        # interactive Rootly import flow
graphify rootly --days 30                              # collect last 30 days of incidents
graphify rootly --api-key-env ROOTLY_API_KEY           # non-interactive key lookup from env
graphify rootly --output ./my-rootly-corpus            # write corpus to a custom folder

# --- Semantic enrichment (agent: Claude Code / Codex) ---
/graphify ./graphify-rootly-data                       # analyze the Rootly corpus
/graphify ./graphify-rootly-data --mode deep           # more aggressive INFERRED edges
/graphify ./graphify-rootly-data --update              # re-extract only changed files

# --- Query the graph (agent) ---
/graphify query "which services have the most recurring incidents?"
/graphify query "what patterns connect the SEV1 incidents?"
/graphify path "payment-api" "auth-service"
/graphify explain "Incident: Database connection pool exhausted"

# --- Optional exports ---
/graphify ./graphify-rootly-data --wiki                # agent-crawlable wiki per community
/graphify ./graphify-rootly-data --no-viz              # skip HTML, report + JSON only
/graphify ./graphify-rootly-data --obsidian            # Obsidian vault

# --- Always-on assistant instructions ---
graphify claude install                                # CLAUDE.md + PreToolUse hook (Claude Code)
graphify codex install                                 # AGENTS.md (Codex)

Reexecutar com novos dados

# Fetch fresh data and rebuild
graphify rootly --api-key-env ROOTLY_API_KEY --days 30 --mode standard

# Re-enrich with semantic step (Claude Code)
/graphify graphify-rootly-data --update