feat: add look-ahead causality auditor

src/ml4t/diagnostic/__init__.py

@@ -31,7 +31,7 @@
 exported in __all__. Breaking changes will only occur in major version bumps.
 """
 
-__version__ = "0.1.0b22"
+__version__ = "0.1.0b23"
 
 # Sub-modules for advanced usage
 from . import (
@@ -64,6 +64,15 @@
 # Main evaluation framework
 from .evaluation import BarrierAnalysis, EvaluationResult, Evaluator
 
+# Look-ahead / feature causality auditor
+from .evaluation.causality import (
+    CausalityError,
+    CausalityReport,
+    LeakEvent,
+    assert_causal,
+    audit_lookahead,
+)
+
 # ValidatedCrossValidation - combines CPCV + DSR in one step
 from .evaluation.validated_cv import ValidatedCrossValidation
 
@@ -116,6 +125,12 @@
     "SignalResult",
     # Barrier Analysis
     "BarrierAnalysis",
+    # Look-ahead / feature causality auditor
+    "audit_lookahead",
+    "assert_causal",
+    "CausalityReport",
+    "CausalityError",
+    "LeakEvent",
     # Configuration (10 primary configs)
     "DiagnosticConfig",
     "StatisticalConfig",

src/ml4t/diagnostic/api.py

@@ -2,6 +2,13 @@
 
 from ml4t.diagnostic.config import DiagnosticConfig, ValidatedCrossValidationConfig
 from ml4t.diagnostic.evaluation.barrier_analysis import BarrierAnalysis
+from ml4t.diagnostic.evaluation.causality import (
+    CausalityError,
+    CausalityReport,
+    LeakEvent,
+    assert_causal,
+    audit_lookahead,
+)
 from ml4t.diagnostic.evaluation.feature_diagnostics import (
     FeatureDiagnostics,
     FeatureDiagnosticsResult,
@@ -35,6 +42,11 @@
     "ValidationResult",
     "validated_cross_val_score",
     "BarrierAnalysis",
+    "audit_lookahead",
+    "assert_causal",
+    "CausalityReport",
+    "CausalityError",
+    "LeakEvent",
     "FeatureDiagnostics",
     "DiagnosticConfig",
     "FeatureDiagnosticsResult",

src/ml4t/diagnostic/evaluation/AGENTS.md

@@ -5,6 +5,7 @@ This package holds the main research and validation workflows.
 ## Main Entry Points
 
 - `ValidatedCrossValidation` for CPCV plus DSR
+- `audit_lookahead` and `assert_causal` for model-agnostic feature causality checks
 - `FeatureDiagnostics` for feature-quality checks
 - `PortfolioAnalysis` for return and risk analytics
 - `TradeAnalysis` and `TradeShapAnalyzer` for trade-level diagnostics

src/ml4t/diagnostic/evaluation/__init__.py

@@ -19,6 +19,13 @@
 
 from . import drift, stats  # noqa: F401 (module re-export)
 from .barrier_analysis import BarrierAnalysis  # noqa: F401
+from .causality import (  # noqa: F401
+    CausalityError,
+    CausalityReport,
+    LeakEvent,
+    assert_causal,
+    audit_lookahead,
+)
 from .event_analysis import EventStudyAnalysis  # noqa: F401
 
 # Factor exposure and attribution
@@ -128,6 +135,11 @@ def __getattr__(name: str):
     "validated_cross_val_score",
     "ValidationFoldResult",
     "ValidationResult",
+    "audit_lookahead",
+    "assert_causal",
+    "CausalityReport",
+    "CausalityError",
+    "LeakEvent",
     # Analysis workflows
     "FeatureDiagnostics",
     "FeatureDiagnosticsAnalysisResult",