Merge pull request #47 from bitstarkbridge/Ledgerlens-data43

feature:Implement Causal Inference Engine for Wash-Trade Attribution ……and Root-Cause Forensics

Author: Inkman007

data/synthetic_dataset.parquet

@@ -74,6 +74,7 @@ def compute_trade_pattern_features(
         return {
             "counterparty_concentration_ratio": 0.0,
             "round_trip_frequency": 0.0,
+            "net_roundtrip_ratio": 0.0,
             "self_matching_rate": 0.0,
             "order_cancellation_rate": order_cancellation_rate,
         }
@@ -95,6 +96,7 @@ def compute_trade_pattern_features(
     return {
         "counterparty_concentration_ratio": float(concentration),
         "round_trip_frequency": float(round_trip_frequency),
+        "net_roundtrip_ratio": float(round_trip_frequency),
         "self_matching_rate": float(self_matching_rate),
         "order_cancellation_rate": order_cancellation_rate,
     }

detection/causal_attribution.py

@@ -0,0 +1,128 @@
+"""Forensic report structures for risk scoring and causal attribution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import networkx as nx
+import pandas as pd
+
+from detection.causal_attribution import CounterfactualAttributor
+from detection.model_inference import RiskScorer
+from detection.shap_explainer import ShapExplainer
+
+
+@dataclass(slots=True)
+class CausalAttribution:
+    minimal_exonerating_trades: list[str]
+    counterfactual_score: int
+    root_cause_wallet: str | None
+    causal_chain: list[dict]
+    interventional_score_if_no_wash: int
+
+
+@dataclass(slots=True)
+class ForensicReport:
+    wallet: str
+    asset_pair: str
+    risk_score: dict
+    shap_explanations: list[dict] = field(default_factory=list)
+    causal_attribution: CausalAttribution | None = None
+
+
+class ForensicReportGenerator:
+    """Build a structured report for a scored wallet."""
+
+    def __init__(self, scorer: RiskScorer | None = None, explainer: ShapExplainer | None = None):
+        self._scorer = scorer or RiskScorer()
+        self._explainer = explainer or ShapExplainer()
+
+    def generate(
+        self,
+        wallet: str,
+        asset_pair: str,
+        feature_row: pd.Series,
+        wallet_trades: pd.DataFrame,
+        activity=None,
+        orderbook_events: pd.DataFrame | None = None,
+        funding_graph: nx.DiGraph | None = None,
+        all_pairs_df: pd.DataFrame | None = None,
+        causal: bool = False,
+        top_n: int = 5,
+    ) -> ForensicReport:
+        risk_score = self._scorer.score(feature_row)
+        shap_explanations = []
+        try:
+            shap_explanations = self._explainer.explain_ensemble(
+                feature_row, self._scorer.models, top_n=top_n
+            )
+        except Exception:  # noqa: BLE001
+            shap_explanations = []
+
+        causal_attribution = None
+        if causal:
+            attributor = CounterfactualAttributor(self._scorer)
+            minimal_set = (
+                attributor.minimal_exonerating_set(
+                    wallet,
+                    wallet_trades,
+                    activity=activity,
+                    orderbook_events=orderbook_events,
+                    funding_graph=funding_graph,
+                    all_pairs_df=all_pairs_df,
+                )
+                or []
+            )
+            counterfactual = attributor.counterfactual_score(
+                wallet,
+                wallet_trades,
+                minimal_set,
+                activity=activity,
+                orderbook_events=orderbook_events,
+                funding_graph=funding_graph,
+                all_pairs_df=all_pairs_df,
+            )
+            scm = attributor.build_scm(
+                wallet,
+                wallet_trades,
+                activities=[activity] if activity is not None else None,
+                orderbook_events=orderbook_events,
+                funding_graph=funding_graph,
+                all_pairs_df=all_pairs_df,
+            )
+            intervention_score = counterfactual["counterfactual_score"]
+            intervention_key = next(
+                (name for name in feature_row.index if name == "benford_chi_square_24h"),
+                next(
+                    (name for name in feature_row.index if name.startswith("benford_chi_square_")),
+                    None,
+                ),
+            )
+            if intervention_key is not None:
+                intervention_result = attributor.interventional_score(
+                    wallet, scm, {intervention_key: 0.0}
+                )
+                intervention_score = intervention_result["score"]
+
+            causal_attribution = CausalAttribution(
+                minimal_exonerating_trades=minimal_set,
+                counterfactual_score=counterfactual["counterfactual_score"],
+                root_cause_wallet=attributor.root_cause_wallet(
+                    wallet,
+                    wallet_trades,
+                    funding_graph,
+                    activity=activity,
+                    orderbook_events=orderbook_events,
+                    all_pairs_df=all_pairs_df,
+                ),
+                causal_chain=attributor.causal_chain(wallet, funding_graph),
+                interventional_score_if_no_wash=intervention_score,
+            )
+
+        return ForensicReport(
+            wallet=wallet,
+            asset_pair=asset_pair,
+            risk_score=risk_score,
+            shap_explanations=shap_explanations,
+            causal_attribution=causal_attribution,
+        )

detection/feature_engineering.py

@@ -0,0 +1,62 @@
+# Causal Inference for LedgerLens
+
+This document describes the causal attribution layer added to LedgerLens on top of the existing feature pipeline and ensemble scorer.
+
+## Why Causal Attribution
+
+SHAP explains which features contributed to a score. Causal attribution asks a more operational question: which trades, counterparties, or funding paths would need to change for the wallet to fall below the risk threshold?
+
+That distinction matters in investigations. A wallet can be high-risk because a feature is large, but the analyst still needs to know which observable trades or upstream wallets are driving that feature.
+
+## Structural Causal Model
+
+LedgerLens builds a lightweight SCM from the existing feature vector:
+
+- Nodes are features.
+- Edges represent simple structural dependencies between features computed from the same trade set.
+- Interventions propagate through the graph so downstream features are recomputed rather than blindly overwritten.
+
+The SCM is intentionally small and deterministic. It is not a symbolic causal discovery engine; it is a forensic explanation layer built around known feature relationships.
+
+## Counterfactual Scoring
+
+`CounterfactualAttributor.counterfactual_score()` removes selected trades, rebuilds the wallet features, and rescales the wallet with the same trained ensemble used in production.
+
+This is different from feature substitution. Removing trades changes the trade-derived features, the Benford metrics, and the graph-derived signals together.
+
+## Greedy Exoneration Search
+
+`minimal_exonerating_set()` uses greedy backward elimination:
+
+1. Score the wallet with the current trade set.
+2. Remove the trade that lowers the score the most.
+3. Repeat until the score falls below the threshold or the search limit is reached.
+
+If no subset of up to 20 trades can move the wallet below threshold, the result is `None`. That indicates the signal is structural or graph-driven rather than explained by a small trade subset.
+
+## Root Cause Wallets
+
+`root_cause_wallet()` evaluates each counterparty wallet and measures the score reduction if its shared trades are removed. Ties prefer counterparties with stronger funding-source similarity and larger shared trade sets.
+
+## Interventions
+
+`interventional_score()` applies a `do(feature = value)` style intervention to the SCM and propagates the effect to downstream features. This is useful for questions like:
+
+- What happens if the Benford anomaly is neutralized?
+- Does the round-trip signal remain high after upstream changes?
+- Which downstream indicators move together with the manipulated feature?
+
+## Counterfactual vs SHAP
+
+SHAP is correlational. It tells you which features are most associated with the model output.
+
+The causal layer is operational. It tells you which trades and wallets change the score when removed or intervened on.
+
+Use SHAP for attribution. Use causal scoring for investigation and evidence triage.
+
+## Investigative Use Cases
+
+- Identify the smallest trade subset that keeps a wallet below threshold.
+- Rank counterparties by how much they contribute to the score.
+- Trace the funding chain behind a flagged wallet.
+- Test whether an apparent wash-trading signal propagates into downstream trade-pattern features.

detection/forensic_report.py

@@ -46,6 +46,7 @@ def generate_synthetic_dataset(n_wallets: int = 500, seed: int = 42) -> pd.DataF
         if is_wash:
             row["counterparty_concentration_ratio"] = rng.uniform(0.7, 1.0)
             row["round_trip_frequency"] = rng.uniform(0.3, 1.0)
+            row["net_roundtrip_ratio"] = rng.uniform(0.3, 1.0)
             row["self_matching_rate"] = rng.uniform(0.3, 1.0)
             row["order_cancellation_rate"] = rng.uniform(0.4, 0.9)
             row["volume_per_counterparty_ratio"] = rng.uniform(1000, 10000)
@@ -65,6 +66,7 @@ def generate_synthetic_dataset(n_wallets: int = 500, seed: int = 42) -> pd.DataF
         else:
             row["counterparty_concentration_ratio"] = rng.uniform(0.0, 0.5)
             row["round_trip_frequency"] = rng.uniform(0.0, 0.1)
+            row["net_roundtrip_ratio"] = rng.uniform(0.0, 0.1)
             row["self_matching_rate"] = rng.uniform(0.0, 0.1)
             row["order_cancellation_rate"] = rng.uniform(0.0, 0.3)
             row["volume_per_counterparty_ratio"] = rng.uniform(10, 1000)

docs/causal_inference.md

@@ -20,6 +20,7 @@
 from stellar_sdk import Asset as SdkAsset
 
 from config import config
+from detection.causal_attribution import CounterfactualAttributor
 from detection.feature_engineering import build_feature_vector
 from detection.model_inference import RiskScorer
 from detection.shap_explainer import ShapExplainer
@@ -83,9 +84,40 @@ def parse_args() -> argparse.Namespace:
         help="Skip loading order-book events",
     )
     parser.add_argument("--json", action="store_true", help="Output result as JSON")
+    parser.add_argument(
+        "--causal",
+        action="store_true",
+        help="Include causal attribution in the output",
+    )
+    parser.add_argument(
+        "--what-if-remove",
+        default=None,
+        help="Comma-separated trade IDs to remove for a counterfactual score",
+    )
     return parser.parse_args()
 
 
+def _parse_remove_trade_ids(
+    remove_trade_ids: str | None, trades_df: pd.DataFrame, wallet: str
+) -> list[str]:
+    if not remove_trade_ids:
+        return []
+
+    requested = [trade_id.strip() for trade_id in remove_trade_ids.split(",") if trade_id.strip()]
+    if not requested:
+        return []
+
+    if trades_df.empty or "trade_id" not in trades_df.columns:
+        raise ValueError("Cannot remove trades: wallet trade history is empty")
+
+    wallet_trade_ids = set(trades_df["trade_id"].astype(str))
+    invalid = [trade_id for trade_id in requested if trade_id not in wallet_trade_ids]
+    if invalid:
+        raise ValueError(f"Trade IDs not found in wallet history: {', '.join(sorted(invalid))}")
+
+    return requested
+
+
 def main() -> None:
     args = parse_args()
 
@@ -139,6 +171,31 @@ def main() -> None:
         print(f"Error during scoring: {e}", file=sys.stderr)
         sys.exit(1)
 
+    remove_trade_ids = []
+    causal_result = None
+    if args.what_if_remove or args.causal:
+        try:
+            remove_trade_ids = _parse_remove_trade_ids(args.what_if_remove, trades_df, args.wallet)
+        except ValueError as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            raise
+
+        attributor = CounterfactualAttributor(scorer)
+        if remove_trade_ids:
+            causal_result = attributor.counterfactual_score(
+                args.wallet,
+                trades_df,
+                remove_trade_ids,
+                orderbook_events=orderbook_events_df,
+            )
+        elif args.causal:
+            causal_result = attributor.counterfactual_score(
+                args.wallet,
+                trades_df,
+                [],
+                orderbook_events=orderbook_events_df,
+            )
+
     # 5. Explain
     try:
         explainer = ShapExplainer()
@@ -159,6 +216,8 @@ def main() -> None:
             "confidence": result["confidence"],
             "shap_explanations": shap_explanations,
         }
+        if causal_result is not None:
+            output["causal_attribution"] = causal_result
         print(json.dumps(output, indent=2))
     else:
         status = "FLAGGED" if result["score"] >= config.RISK_SCORE_FLAG_THRESHOLD else "OK"
@@ -172,6 +231,16 @@ def main() -> None:
             contrib = f"{exp['contribution']:+.2f}"
             print(f"  {i}. {exp['feature']:<25} {contrib:>6}  (value: {exp['value']:.4g})")
 
+        if causal_result is not None:
+            print("\nCausal attribution:")
+            print(f"  Original score:        {causal_result['original_score']}")
+            print(f"  Counterfactual score:   {causal_result['counterfactual_score']}")
+            print(f"  Score delta:           {causal_result['score_delta']}")
+            if causal_result["features_changed"]:
+                print("  Features changed:")
+                for name, details in causal_result["features_changed"].items():
+                    print(f"    - {name}: {details['original']} -> {details['counterfactual']}")
+
 
 if __name__ == "__main__":
     main()

scripts/generate_synthetic_dataset.py

@@ -0,0 +1,36 @@
+# Forensic Report
+
+Wallet: {{ report.wallet }}
+Asset pair: {{ report.asset_pair }}
+Risk score: {{ report.risk_score.score }}
+
+## Summary
+
+- Benford flag: {{ report.risk_score.benford_flag }}
+- ML flag: {{ report.risk_score.ml_flag }}
+- Confidence: {{ report.risk_score.confidence }}
+
+## SHAP
+
+{% for item in report.shap_explanations %}
+- {{ item.feature }}: {{ item.contribution }} (value: {{ item.value }})
+{% endfor %}
+
+## Causal Attribution
+
+{% if report.causal_attribution %}
+- Minimal exonerating trades: {{ report.causal_attribution.minimal_exonerating_trades | join(', ') }}
+- Counterfactual score: {{ report.causal_attribution.counterfactual_score }}
+- Root cause wallet: {{ report.causal_attribution.root_cause_wallet }}
+- Interventional score if no wash: {{ report.causal_attribution.interventional_score_if_no_wash }}
+
+### Causal chain
+
+{% for hop in report.causal_attribution.causal_chain %}
+- Hop {{ hop.hop }}: {{ hop.wallet }} ({{ hop.role }})
+{% endfor %}
+
+> The presence of a minimal exonerating set does not indicate the wallet is innocent; it indicates which specific trades are most anomalous.
+{% else %}
+- Causal attribution disabled.
+{% endif %}