chronos

name	chronos
description	Investigate data quality incidents — root cause analysis, blast radius, lineage traversal — via the CHRONOS autonomous RCA agent
trigger	/chronos

/chronos

Autonomous Data Incident Root Cause Analysis via the CHRONOS agent. Investigates failing data quality tests by reasoning across OpenMetadata lineage, a temporal knowledge graph, and code intelligence — returning a confidence-scored report with evidence chain and recommended actions.

Usage

/chronos investigate <entity_fqn>                          # Full 10-step RCA on a failing entity
/chronos investigate <entity_fqn> --test <test_name>       # Scope to a specific test
/chronos investigate <entity_fqn> --message "row count 0"  # Include the failure message
/chronos get <incident_id>                                 # Fetch a completed incident report
/chronos list                                              # List recent incidents
/chronos list --status open                                # Filter by status (open|acknowledged|resolved)
/chronos lineage <entity_fqn>                              # Walk upstream lineage
/chronos lineage <entity_fqn> --direction downstream       # Walk downstream (blast radius)
/chronos lineage <entity_fqn> --depth 5                    # Custom hop depth (default: 3)
/chronos search <table_or_model>                           # Ripgrep codebase for entity references
/chronos graph <entity_fqn>                                # Community + blast-radius graph context
/chronos failures                                          # Poll OpenMetadata for current test failures
/chronos failures --limit 20                               # Custom result limit

What CHRONOS Does

CHRONOS runs a 10-step RCA pipeline for each investigation:

1. Entity resolution — looks up the entity in OpenMetadata, pulls schema, owner, tier, tags
2. Test history — retrieves prior failures on the same entity
3. Temporal changes — queries Graphiti knowledge graph for changes in the investigation window
4. Schema diff — detects column additions, removals, type changes
5. Upstream lineage — walks dbt DAG upstream to find source-level failures
6. Code intelligence — searches codebase for recent commits touching the entity
7. Downstream impact — enumerates all assets depending on the failing entity
8. Audit events — pulls OpenMetadata audit log for recent mutations
9. LLM synthesis — sends full evidence bundle to an LLM for root cause reasoning
10. PROV-O provenance — generates W3C-compliant audit artifacts (JSON-LD / Turtle / PROV-N)

What You Must Do When Invoked

Parse the subcommand from the args. If no subcommand is given and an entity FQN looks like an argument, default to investigate.

Step 1 — Resolve the base URL

Check for CHRONOS_API_URL in environment. Default: https://chronos-api-0e8635fe890d.herokuapp.com

BASE="${CHRONOS_API_URL:-https://chronos-api-0e8635fe890d.herokuapp.com}"

Step 2 — Dispatch to the right endpoint

investigate <entity_fqn>

curl -s -X POST "$BASE/api/v1/investigate" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_fqn": "<entity_fqn>",
    "test_name": "<test_name_or_null>",
    "failure_message": "<message_or_null>"
  }'

Returns immediately with {"incident_id": "...", "status": "running"}. Poll GET /api/v1/incidents/<incident_id> every 5 seconds until status is completed or failed.

Stream progress in real time (optional):

curl -N "$BASE/api/v1/investigations/<incident_id>/stream"

get <incident_id>

curl -s "$BASE/api/v1/incidents/<incident_id>"

list

curl -s "$BASE/api/v1/incidents?status=<status>&limit=<limit>"

lineage <entity_fqn>

curl -s "$BASE/api/v1/lineage/<encoded_fqn>?direction=<upstream|downstream>&depth=<n>"

search <term>

Via MCP tool search_entity or:

curl -s "$BASE/api/v1/search?q=<term>"

graph <entity_fqn>

Via MCP tool get_graph_context or:

curl -s "$BASE/api/v1/graph/<encoded_fqn>"

failures

curl -s "$BASE/api/v1/failures?limit=<n>"

Step 3 — Present the incident report

When status == "completed", render the key fields clearly:

CHRONOS Incident Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Incident ID:    <incident_id>
Entity:         <entity_fqn>
Root Cause:     <probable_root_cause>
Category:       <root_cause_category>
Confidence:     <confidence * 100>%
Business Impact: <business_impact>

Evidence Chain:
  • <evidence item 1>
  • <evidence item 2>
  ...

Recommended Actions:
  1. [<priority>] <description> — owner: <owner>
  2. ...

Provenance: GET <BASE>/api/v1/incidents/<id>/provenance.jsonld

MCP Integration (preferred for agent pipelines)

If running inside Claude Desktop or an MCP-capable agent, connect directly:

stdio (local):

pip install chronos-rca   # or: git clone + pip install -e .
chronos-mcp               # starts stdio MCP server

SSE (remote):

chronos-mcp --transport sse --host 0.0.0.0 --port 8001

Claude Desktop config (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "chronos": {
      "command": "chronos-mcp",
      "env": {
        "OPENMETADATA_URL": "http://localhost:8585",
        "OPENMETADATA_JWT": "your-jwt-token",
        "LITELLM_PROXY_URL": "http://localhost:4000"
      }
    }
  }
}

Available MCP tools:

Tool	Hint	Description
trigger_investigation	Action	Start 10-step RCA pipeline
get_incident	Read	Fetch completed report by ID
list_incidents	Read	Filter/list incidents
query_lineage	Graph	Walk dbt DAG up or downstream
search_entity	Code	Ripgrep codebase (injection-safe)
get_graph_context	Graph	Community + blast-radius query
poll_failures	Monitor	Pull OM test-case failures

MCP resources: chronos://health, chronos://incidents, chronos://incident/{id}

Environment Variables

Variable	Required	Description
CHRONOS_API_URL	No	Override base URL (default: Heroku)
OPENMETADATA_URL	Yes (local)	OpenMetadata API base URL
OPENMETADATA_JWT	Yes (local)	OpenMetadata JWT token
LITELLM_PROXY_URL	Yes (local)	LiteLLM proxy URL
LITELLM_MASTER_KEY	No	LiteLLM auth key
GRAPHITI_URI	No	Neo4j/FalkorDB URI for temporal KG

Agent Discovery (A2A)

CHRONOS publishes a Linux Foundation A2A agent card:

GET https://chronos-api-0e8635fe890d.herokuapp.com/.well-known/agent-card.json
Accept: application/json

Returns the full capability manifest — skills, endpoints, protocols, MCP tools — so orchestrators can auto-configure without human setup.

Error Handling

• If investigate returns 422, the entity FQN is malformed or unknown — check with /chronos failures to see the exact FQN format OpenMetadata uses.
• If status == "failed" in a poll, the investigation hit an LLM or data source error — retry once, then fall back to /chronos lineage for manual blast-radius scoping.
• If the Heroku API is unreachable, start a local instance: chronos-server (requires env vars above).

Examples

/chronos investigate default.prod.orders --test row_count_check --message "Expected >0 rows, got 0"
/chronos list --status open
/chronos lineage default.prod.orders --direction downstream --depth 4
/chronos failures --limit 10