Causality Analyzer

An embeddable causal AI library for Node.js — modular TypeScript packages for anomaly detection, causal discovery, root cause analysis, effect estimation, counterfactual reasoning, and visualization. Bring your own data, storage, and frontend.

What Is This?

Causality Analyzer is not a standalone application — it is a collection of embeddable npm packages you integrate into your own Node.js or TypeScript project. Each package is independently installable, so you only pull in what you need.

Your Use Case	Packages You Need
Add anomaly detection to a monitoring pipeline	`core` + `pipeline`
Discover causal graphs from metric data	`core` + `pipeline`
Run root cause analysis during incidents	`core` + `pipeline`
Persist results to a database	`core` + `storage-embed` or `storage-remote`
Render causal graphs in a browser dashboard	`core` + `pipeline` + `visual`
Full-stack AIOps causality platform	all 5 packages

Who Is This For?

SRE / Platform Engineers — add causal RCA to your incident response workflow. Drop in pipeline alongside your existing monitoring, call HeuristicPathRCA.findRootCauses() when anomalies fire.

Data Scientists — discover causal structure from observational data using PC/FCI algorithms, estimate treatment effects with backdoor/IV/PS/DR, run sensitivity analysis to quantify confidence.

Frontend Developers — render causal graphs and time-series anomaly charts using framework-agnostic Web Components (<ca-causal-graph>, <ca-time-series>, <ca-root-cause-ranking>).

Enterprise Architects — deploy with full mTLS on PostgreSQL + Neo4j, deterministic reproducibility for audit trails, CI-verified quality gates (lint → typecheck → test → browser → Neo4j mTLS).

For Beginners: Your First 5 Minutes

npm install @agentix-e/causality-analyzer-core @agentix-e/causality-analyzer-pipeline

import { CausalGraph, HeuristicPathRCA } from '@agentix-e/causality-analyzer-pipeline';
import { Matrix } from 'ml-matrix';

// 1. Define your system topology
const graph = new CausalGraph(['Memory', 'CPU', 'Latency']);
graph.addEdge('Memory', 'CPU');
graph.addEdge('CPU', 'Latency');

// 2. Load your metric data
const data = new Matrix(100, 3);
// ... fill with your actual metrics ...

// 3. Find the root cause
const rca = new HeuristicPathRCA();
rca.train(graph, new Set(['CPU', 'Latency']), data);
const result = rca.findRootCauses(['CPU', 'Latency']);

console.log(`Root cause: ${result.rootCauses[0].name}`);     // "Memory"
console.log(`Confidence: ${result.rootCauses[0].score}`);    // posterior probability

That's it. No server, no config file, no database required. You're doing causal root cause analysis in 3 steps.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Causality Analyzer                       │
├───────────┬───────────┬──────────────┬──────────┬──────────┤
│   core    │ pipeline  │ storage-embed│storage-  │  visual  │
│           │           │              │ remote   │          │
├───────────┼───────────┼──────────────┼──────────┼──────────┤
│ Types     │ Detection │ SQLite       │PostgreSQL│ Web      │
│ Interfaces│ Discovery │ OverGraph    │ Neo4j    │Components│
│ Math      │ RCA       │              │ mTLS     │ uPlot    │
│ Registry  │ Inference │              │          │ Canvas   │
│ Config    │ GCM       │              │          │          │
└───────────┴───────────┴──────────────┴──────────┴──────────┘

Data Flow:
  Raw Metrics → Standardize → Detect Anomalies → Causal Discovery (PC/FCI)
  → RCA (Bayesian/HT/RandomWalk) → Effect Estimation → Counterfactuals
  → Visualization → Storage

Key Features

Causal Discovery — PC algorithm (stable variant), FCI with R1-R4 orientation rules
Root Cause Analysis — HeuristicPathRCA, Bayesian Network (VE/JT/LBP/LW/Gibbs), HTRCA, RandomWalkRCA, FPGrowthRCA, CIRCA pipeline
Causal Effect Estimation — Backdoor adjustment, Frontdoor, IV/2SLS, Propensity Score, Doubly Robust
Sensitivity Analysis — E-value, partial R², robustness value with plain-English interpretation
do-Calculus — Pearl's identification rules + ID algorithm (Tian & Pearl, Shpitser & Pearl)
Structural Causal Models — Additive noise, PostNonlinear (sigmoid), auto mechanism assignment
Counterfactual Inference — Abduction-Action-Prediction framework, Shapley anomaly attribution
Audit Trail — Tamper-evident SHA-256 hash-chained audit log with verify()
NL Explanation — Deterministic, templated reports for RCA, sensitivity, and effect estimates
Enterprise Security — Full mTLS on both Bolt (Neo4j) and PG-wire (PostgreSQL)
TypeScript Native — Strict type safety, dependency injection, framework-agnostic design

Packages

Package	Version	Description
`@agentix-e/causality-analyzer-core`		Types, interfaces, ColumnarTable, math, plugin registry
`@agentix-e/causality-analyzer-pipeline`		Detection, causal discovery, RCA, inference, GCM, visualization data
`@agentix-e/causality-analyzer-storage-embed`		SQLite (better-sqlite3) + OverGraph embedded stores
`@agentix-e/causality-analyzer-storage-remote`		PostgreSQL (pg) + Neo4j (neo4j-driver-lite) with mTLS
`@agentix-e/causality-analyzer-visual`		Lit 3 Web Components for causal graphs + time series

Quick Start

Installation

git clone https://github.com/AgentiX-E/causality-analyzer.git
cd causality-analyzer
pnpm install
pnpm run --filter @agentix-e/causality-analyzer-core build

Basic Usage: Anomaly Detection

import { StatsDetector } from '@agentix-e/causality-analyzer-pipeline';

const detector = new StatsDetector({ method: 'zscore' });
detector.train([[1, 2], [1.1, 2.1], [0.9, 1.9]]);

const result = detector.update([5.0, 8.0]);
console.log(result.isAnomalous); // true
console.log(result.scores);      // z-scores per metric

Basic Usage: Causal Discovery

import { Matrix } from 'ml-matrix';
import { pcAlgorithm } from '@agentix-e/causality-analyzer-pipeline';

// 3 variables, 500 observations
const data = new Matrix(500, 3);
// ... populate data ...

const { graph } = pcAlgorithm(data, ['CPU', 'Memory', 'Latency']);
console.log(graph.edges);
// [{ source: 'CPU', target: 'Latency', ... }, ...]

Basic Usage: Root Cause Analysis

import { CausalGraph, HeuristicPathRCA } from '@agentix-e/causality-analyzer-pipeline';

const graph = new CausalGraph(['Memory', 'CPU', 'Latency']);
graph.addEdge('Memory', 'CPU');
graph.addEdge('CPU', 'Latency');

const rca = new HeuristicPathRCA();
rca.train(graph, new Set(['CPU', 'Latency']), data);
const result = rca.findRootCauses(['CPU', 'Latency']);

console.log(result.rootCauses[0].name);  // 'Memory'
console.log(result.rootCauses[0].score); // posterior probability

Basic Usage: Causal Effect Estimation

import { adjustBackdoor } from '@agentix-e/causality-analyzer-pipeline';

const nodeIndex = new Map([['Treatment', 0], ['Outcome', 1], ['Confounder', 2]]);
const { ate, se, adjustors } = adjustBackdoor(graph, 'Treatment', 'Outcome', data, nodeIndex);

console.log(`ATE = ${ate.toFixed(3)} ± ${(se * 1.96).toFixed(3)}`);
// ATE = 0.742 ± 0.128

Basic Usage: Counterfactual Reasoning

import { CausalGraph, StructuralCausalModel } from '@agentix-e/causality-analyzer-pipeline';

const scm = new StructuralCausalModel(graph);
scm.train(data);

// What would latency be if we had increased memory allocation?
const noise = scm.abduct({ Memory: 0.5, CPU: 0.8, Latency: 120 });
const cf = scm.counterfactual(noise, { Memory: 1.0 });
console.log(`Counterfactual latency: ${cf.Latency?.toFixed(0)} ms`);

Project Structure

causality-analyzer/
├── packages/
│   ├── core/                       # Foundation layer
│   │   └── src/
│   │       ├── index.ts            # Barrel exports
│   │       ├── types/index.ts      # CausalEdge, CausalGraph, RCAResult, etc.
│   │       ├── interfaces/index.ts # IRelationalStore, IGraphStore
│   │       ├── table/index.ts      # ColumnarTable (zero-copy columnar data)
│   │       ├── math.ts             # solveLinear, normalTail, erf, colMean, createRNG
│   │       ├── registry/index.ts   # PluginRegistry (detectors, graphs, analyzers)
│   │       ├── config/index.ts     # BaseConfig with Zod validation
│   │       └── di/index.ts         # Dependency injection config
│   │
│   ├── pipeline/                   # Causal analysis engine
│   │   └── src/
│   │       ├── index.ts            # Barrel exports (all sub-packages)
│   │       ├── data/standardizer.ts     # zscore, minmax, robust, discretize
│   │       ├── detect/stats-detector.ts # Z-score / MAD / IQR anomaly detection
│   │       ├── detect/spectral-residual.ts # FFT-based anomaly detection
│   │       ├── detect/spot.ts           # SPOT/DSPOT extreme value detectors
│   │       ├── detect/voting-detector.ts # Ensemble voting (majority/max/weighted)
│   │       ├── graph/causal-graph.ts     # Graph data structure (DAG/PDAG/CPDAG)
│   │       ├── graph/pc.ts              # PC algorithm (constraint-based)
│   │       ├── graph/advanced-discovery.ts # FCI, Grow-Shrink, targeted discovery
│   │       ├── analyze/rca.ts            # HeuristicPathRCA, RandomWalkRCA, HTRCA, FPGrowthRCA
│   │       ├── analyze/circa.ts          # CIRCA pipeline: RHTScorer + DAScorer
│   │       ├── infer/causal-inference.ts # Backdoor/frontdoor ID, refutation
│   │       ├── infer/effect-estimation.ts # Backdoor, frontdoor, IV, PS, DR estimators
│   │       ├── infer/sensitivity.ts      # E-value, partial R², robustness value
│   │       ├── infer/do-calculus.ts      # do-calculus rules + ID algorithm
│   │       ├── infer/mediation.ts        # NDE/NIE, arrow strength
│   │       ├── infer/cate-fairness.ts    # CATE, IPW, counterfactual fairness
│   │       ├── infer/bootstrap-ci.ts     # Bootstrap CI + parallel execution
│   │       ├── gcm/structural-causal-model.ts # SCM with counterfactuals
│   │       ├── gcm/model-evaluation.ts   # R², MSE, Shapley RCA, bootstrap CI
│   │       ├── gcm/nonlinear-mechanisms.ts # PostNonlinear, auto-assign, relevance
│   │       ├── gcm/distribution-change.ts # Mechanism change detection + attribution
│   │       ├── gcm/graph-falsification.ts # CI-based falsification + LMC testing
│   │       ├── viz/viz-data.ts           # Visualization data builders
│   │       └── viz/fusion.ts             # Multi-modal RCA fusion
│   │
│   ├── storage-embed/              # Embedded storage
│   │   └── src/
│   │       ├── embed-relational-store.ts # SQLite via better-sqlite3
│   │       └── embed-graph-store.ts      # OverGraph LSM-tree graph store
│   │
│   ├── storage-remote/             # Remote storage (enterprise)
│   │   └── src/
│   │       ├── remote-relational-store.ts # PostgreSQL via pg.Client
│   │       ├── remote-graph-store.ts      # Neo4j via neo4j-driver-lite
│   │       └── types.ts                   # MtlsConfig, TrustStrategy
│   │
│   └── visual/                     # Web Components
│       └── src/
│           └── components/
│               ├── ca-causal-graph.ts      # Force-directed causal graph
│               ├── ca-time-series.ts       # Time series with anomaly bands
│               └── ca-root-cause-ranking.ts # Ranked root cause list
│
├── docs/
│   ├── user-guide.md    # Comprehensive user guide
│   ├── guide/           # Getting started guide
│   ├── reference/       # Algorithm reference docs
│   └── api/             # TypeDoc-generated API
├── .github/workflows/   # CI/CD (lint, typecheck, test, browser, Neo4j mTLS)
└── typedoc.json         # API documentation config

Development

# Install
pnpm install

# Build foundation
pnpm run --filter @agentix-e/causality-analyzer-core build

# Quality gates (all packages)
pnpm -r lint
pnpm -r typecheck
pnpm -r test

# Generate API docs
pnpm docs

CI runs on every PR: lint → typecheck → unit tests → browser tests → Neo4j mTLS integration tests.

Documentation

User Guide — From zero to production with Causality Analyzer
API Reference — TypeDoc-generated API documentation
Cheat Sheet — Algorithm reference with scenarios and parameters
Changelog — Full release history
Contributing — Development workflow and standards

References

Resource	Link
PC Algorithm	Spirtes, Glymour & Scheines (2000). Causation, Prediction, and Search.
FCI Algorithm	Zhang (2008). On the completeness of orientation rules
CIRCA	Li et al. (KDD 2022). Causal Inference-Based Root Cause Analysis
DoWhy	py-why/dowhy
Intel Causal Discovery Lab	IntelLabs/causality-lab
SPOT/DSPOT	Siffer et al. (KDD 2017). Anomaly Detection in Streams

License

MIT — see LICENSE for details.

Causality Analyzer

Causality Analyzer

What Is This?

Who Is This For?

For Beginners: Your First 5 Minutes

Architecture

Key Features

Packages

Quick Start

Installation

Basic Usage: Anomaly Detection

Basic Usage: Causal Discovery

Basic Usage: Root Cause Analysis

Basic Usage: Causal Effect Estimation

Basic Usage: Counterfactual Reasoning

Project Structure

Development

Documentation

References

License

Settings

On This Page