rootly-graphify

Basado en graphify, una herramienta inspirada en la idea de LLM Wiki de Andrej Karpathy — en lugar de redescubrir el conocimiento desde cero en cada consulta, un LLM construye un grafo de conocimiento persistente y estructurado que se enriquece con el tiempo. Graphify toma cualquier carpeta de archivos y la convierte en un grafo consultable con comunidades, conexiones y puntuaciones de confianza. Este fork lo orienta a la API de Rootly.

Conecta la API de Rootly, recopila incidentes, alertas, equipos y el catálogo de servicios para una ventana de tiempo seleccionada, expórtalos a un corpus local y convierte ese corpus en un grafo de conocimiento consultable. Usa graphify rootly para la recopilación y /graphify en Claude Code o Codex cuando quieras un análisis semántico más profundo.

Instalación

Instalación nueva (Graphify + importador Rootly):

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

Añadir el importador Rootly a una instalación existente de Graphify:

pip install "graphifyy[rootly]" --upgrade

Configura tu clave de API de Rootly

Crea un archivo .env en la raíz de tu proyecto:

ROOTLY_API_KEY=rootly_...

Ejecuta el flujo de trabajo

Paso 1: Obtener y construir (terminal)

Obtiene incidentes, alertas activadas y equipos. Construye el grafo inicial con colores de severidad, filtros de alertas y capas de equipos/servicios.

graphify rootly

No interactivo:

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

Salidas escritas en graphify-rootly-data/graphify-out/:

• graph.html — ábrelo en el navegador para explorar el grafo
• GRAPH_REPORT.md — nodos dios, comunidades, preguntas sugeridas
• graph.json — grafo sin procesar para consultas

Paso 2: Añadir significado semántico (agente)

Ejecuta subagentes en paralelo sobre el corpus de incidentes para inferir temas transversales, patrones recurrentes y relaciones de causa raíz.

Claude Code — escribe en el chat:

/graphify graphify-rootly-data --mode deep

Codex — escribe en el chat:

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

Qué puedes explorar

Qué se recopila

Filtros de visualización

Una vez que graph.html está abierto en un navegador:

• Equipo — filtra todos los nodos a los incidentes y servicios de un equipo específico
• Severidad — mostrar/ocultar por SEV1–SEV4
• Incidentes — todos o solo abiertos
• Alertas — activadas (activado por defecto) / huérfanas (desactivado por defecto, no recopiladas)
• Rango de tiempo — control deslizante para ajustar la ventana de incidentes

Cómo funciona

rootly-graphify tiene una fase de recopilación Rootly y una fase de análisis de grafo.

1. Recopilación Rootly determinista. Valida la clave de API, elige una ventana de 7, 30 o 90 días, obtén los incidentes cuyo started_at esté dentro de esa ventana, obtén sus alertas activadas a través del sub-recurso por incidente, obtén todos los datos de equipos y escribe todo en un directorio de corpus local.

2. Construcción inicial del grafo Rootly. El ejecutor Rootly incorporado crea nodos para incidentes, alertas, equipos y servicios, los conecta con aristas tipadas (triggered, affects, owns, responded_by, targets), agrupa el grafo y escribe graph.html, GRAPH_REPORT.md y graph.json. El HTML incluye codificación de colores por severidad, capas de equipo/servicio y filtros de alertas.

3. Enriquecimiento profundo opcional. Ejecuta /graphify ./graphify-rootly-data --mode deep para despachar subagentes en paralelo sobre los archivos markdown e inferir temas transversales, fundamentos y vínculos conceptuales.

4. Usa la salida actual de nivel superior. Después del enriquecimiento semántico, abre . El exportador genérico actual ya incluye los filtros y elementos visuales mantenidos directamente, por lo que no se requiere un paso de reaplicación por separado.

La agrupación se basa en la topología del grafo, no en embeddings. Leiden encuentra comunidades por densidad de aristas. Las aristas de similitud semántica (semantically_similar_to, marcadas INFERRED) influyen directamente en la detección de comunidades. No se requiere un paso de embedding separado ni base de datos vectorial.

Cada relación está etiquetada como EXTRACTED (encontrada directamente en la fuente), INFERRED (inferencia razonable, con una puntuación de confianza) o AMBIGUOUS (marcada para revisión).

Qué obtienes

• Nodos dios — incidentes o servicios de mayor grado (por lo que todo se conecta)
• Conexiones sorprendentes — vínculos entre incidentes clasificados por puntuación compuesta, cada uno con una explicación en lenguaje claro
• Preguntas sugeridas — 4–5 preguntas que el grafo está especialmente capacitado para responder sobre tu historial de incidentes
• Puntuaciones de confianza — cada arista INFERRED tiene un confidence_score (0.0–1.0). Las aristas EXTRACTED siempre son 1.0.
• Aristas de similitud semántica — vínculos conceptuales entre incidentes sin conexión estructural. Dos incidentes causados por el mismo patrón raíz sin compartir servicios ni equipos.
• Eficiencia de tokens — la primera ejecución extrae y construye el grafo (consume tokens). Cada consulta posterior lee el grafo compacto en lugar del markdown sin procesar — ahí es donde se acumulan los ahorros. La caché SHA256 significa que las re-ejecuciones solo reprocesan los archivos modificados.

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)

Re-ejecutar con datos nuevos

# 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