@agentix-e/causality-analyzer-pipeline

Complete causal AI pipeline — anomaly detection, causal discovery, root cause analysis, effect estimation, counterfactual reasoning, and model evaluation.

Overview

@agentix-e/causality-analyzer-pipeline is the causal reasoning engine. It implements the full stack from raw metric ingestion to counterfactual "what-if" analysis, including academic-grade sensitivity testing and graph validation.

Architecture

Raw Data → Standardize → Detect Anomalies
                                ↓
              Causal Discovery (PC / FCI / Targeted)
                                ↓
              Root Cause Analysis (Bayesian / HT / RandomWalk / CIRCA)
                                ↓
              Effect Estimation (Backdoor / Frontdoor / IV / PS / DR)
                                ↓
              Sensitivity & Refutation (E-value / pR² / Bootstrap)
                                ↓
              Counterfactual Reasoning (SCM → Abduction → Action → Prediction)
                                ↓
              Model Evaluation (R² / MSE / Shapley RCA / Distribution Change)
Copy

Installation

npm install @agentix-e/causality-analyzer-pipeline
npm install @agentix-e/causality-analyzer-core  # peer dependency
Copy

Quick Start

1. Anomaly Detection

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

// Z-score detector
const detector = new StatsDetector({ method: 'zscore' });
detector.train(normalData);
const result = detector.update([5.2, 8.1]);  // anomalous!

// Ensemble voting
const ensemble = new VotingDetector({
  detectors: [statsDetector, srDetector],
  strategy: 'majority',
});
const voted = ensemble.detect(dataPoints);
Copy

2. Causal Discovery

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

// PC algorithm (no latent confounders)
const { graph } = pcAlgorithm(data, ['CPU', 'Memory', 'Latency']);

// FCI algorithm (with latent confounders)
const { pagEdges } = fciAlgorithm(data, nodeNames);

// Targeted: only find parents of 'Latency'
const parents = targetedDiscovery(data, ['Latency'], nodeNames);
Copy

3. Root Cause Analysis

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

// Bayesian Network RCA
const rca = new BayesianRCA();
rca.train(graph, anomalousNodes, data);
const result = rca.findRootCauses(['CPU', 'Latency']);

// Hypothesis Testing RCA (regression residuals)
const ht = new HTRCA();
ht.train(graph, data);
const htResult = ht.findRootCauses(['CPU', 'Latency'], data);

// CIRCA Pipeline (KDD 2022)
const circa = new CIRCAPipeline(graph);
const circaResult = circa.analyze(anomalyData, ['CPU', 'Latency']);
Copy

4. Causal Effect Estimation

import {
  adjustBackdoor, estimateIV, estimatePSMatching, estimateDoublyRobust
} from '@agentix-e/causality-analyzer-pipeline';

// Backdoor adjustment
const { ate, se } = adjustBackdoor(graph, 'Treatment', 'Outcome', data, nodeIndex);

// Instrumental Variables (2SLS)
const ivResult = estimateIV(data, treatmentIdx, outcomeIdx, ivIdx);

// Propensity Score Matching
const psmResult = estimatePSMatching(data, treatmentIdx, outcomeIdx, [confounderIdx]);

// Doubly Robust
const drResult = estimateDoublyRobust(data, treatmentIdx, outcomeIdx, [confounderIdx]);
Copy

5. Sensitivity Analysis

import { eValueSensitivity, robustnessValue } from '@agentix-e/causality-analyzer-pipeline';

const { eValue, interpretation } = eValueSensitivity(0.8);
// "E-value=4.22: strong robustness — only very strong unmeasured confounding..."

const { rv } = robustnessValue(0.8, 0.1, 1000);
// "RV=3.15: ROBUST — causal conclusion is well-supported"
Copy

6. 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 doubled memory?
const noise = scm.abduct({ Memory: 0.5, CPU: 0.8, Latency: 120 });
const cf = scm.counterfactual(noise, { Memory: 1.0 });

// Shapley-based anomaly attribution
import { shapleyAttribute } from '@agentix-e/causality-analyzer-pipeline';
const shapleyRCA = shapleyAttribute(scm, anomalousObservation, 5);
Copy

API Reference

📚 Full TypeDoc API: pnpm docs from the monorepo root.

Module Index

Deterministic Reproducibility

All stochastic algorithms accept an optional seed parameter for reproducible results:

// With seed → deterministic
const result = shapleyAttribute(scm, obs, 5, seed);
const ci = bootstrapRCA(scm, obs, 200, 0.05, seed);

// Without seed → non-deterministic (uses Math.random)
const result2 = shapleyAttribute(scm, obs, 5);
Copy

License

MIT