feat(ai/forensics): complete — Policy-Benefit Causal Analysis

ai/forensics/policy_benefit_analyzer.py: three causal inference methods

Method 1 — Granger causality:
Compares residual variance of an autoregressive model for the
contract series (restricted) versus a VAR model that also includes
lagged policy event values (unrestricted). F-statistic above 2.5
indicates policy events carry predictive power over contracts.
Lag order 2. Fallback-safe when series is too short.

Method 2 — Transfer entropy:
Discretised joint/marginal probability estimation over binned
contract and policy time series. TE(policy->contracts) above 0.15
nats indicates directional information flow from policy activity
to contract patterns.

Method 3 — Cumulative Abnormal Contract Award (CACA):
For each policy event, computes expected contract volume from the
180-day pre-event baseline and compares to 180-day post-event
actual. CACA ratio above 1.5x is flagged. All methods are
fallback-safe with sample data when database is unavailable.

api/routes/policy.py: GET /policy/causal/{entity_id}
Returns all three analyses with structured findings and evidence.
Returns HTTP 404 if entity not found.
api/main.py: policy router registered, version bumped to 0.25.0

api/main.py

@@ -10,7 +10,7 @@ from fastapi.middleware.cors import CORSMiddleware
 from loguru import logger
 
 from api.dependencies import get_driver, close_driver
-from api.routes import search, profile, graph, risk, multilingual, export, admin, investigation, affidavit, biography, benami, sources, procurement, conflict, linguistic
+from api.routes import search, profile, graph, risk, multilingual, export, admin, investigation, affidavit, biography, benami, sources, procurement, conflict, linguistic, policy
 from api.models import HealthResponse, StatsResponse
 
 
@@ -30,7 +30,7 @@ app = FastAPI(
         "All data sourced from official government records. "
         "Outputs are structural indicators, not legal findings."
     ),
-    version="0.24.0",
+    version="0.25.0",
     lifespan=lifespan,
 )
 
@@ -67,6 +67,7 @@ app.include_router(sources.router,      tags=["Sources"])
 app.include_router(procurement.router,   tags=["Procurement"])
 app.include_router(conflict.router,       tags=["Conflict"])
 app.include_router(linguistic.router,     tags=["Linguistic"])
+app.include_router(policy.router,         tags=["Policy"])
 
 
 @app.get("/health", response_model=HealthResponse)
@@ -81,7 +82,7 @@ def health_check():
     return HealthResponse(
         status="ok" if connected else "degraded",
         neo4j_connected=connected,
-        version="0.24.0",
+        version="0.25.0",
         generated_at=datetime.now().isoformat(),
     )
 

api/routes/policy.py

@@ -0,0 +1,25 @@
+import os, sys
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+
+from fastapi import APIRouter, Depends, HTTPException
+from loguru import logger
+from api.dependencies import get_db
+from ai.forensics.policy_benefit_analyzer import PolicyBenefitAnalyzer
+
+router   = APIRouter()
+analyzer = PolicyBenefitAnalyzer()
+
+
+@router.get("/policy/causal/{entity_id}")
+def policy_causal_analysis(entity_id: str, driver=Depends(get_db)):
+    logger.info(f"[Policy] Causal analysis requested: {entity_id}")
+    with driver.session() as s:
+        row = s.run(
+            "MATCH (n {id:$id}) RETURN n.name AS name", id=entity_id
+        ).single()
+    if not row:
+        raise HTTPException(
+            status_code=404, detail=f"Entity {entity_id} not found"
+        )
+    name = row.get("name") or entity_id
+    return analyzer.analyze(entity_id, name, driver=driver)