feat(ai/forensics):complete — Revolving Door + TBML

- ai/forensics/revolving_door.py: career transition detector
Cooling-off violation: government role → private board < 365 days
Pre-employment benefit: company received contracts before appointment
Fallback-safe with sample data when DB unavailable
- ai/forensics/tbml_detector.py: trade-based transfer indicators
Price anomaly: contracts > 2.5 std-dev from entity mean
Subcontract loop: circular re-award chain detection via Neo4j cycles
Director-change window: directorship change within 90 days of contract
- api/routes/conflict.py: GET /conflict/revolving-door/{entity_id},
GET /conflict/tbml/{entity_id}
- api/main.py: conflict router registered

ai/forensics/revolving_door.py

@@ -0,0 +1,157 @@
+import os, sys
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+
+from datetime import datetime, date
+from loguru import logger
+
+COOLING_OFF_DAYS = 365   # 1 year minimum expected gap
+BENEFIT_WINDOW   = 730   # 2 years pre-appointment benefit window
+
+
+class RevolvingDoorDetector:
+    """
+    Detects career transitions from regulatory/government roles
+    to private-sector boards and companies that were regulated
+    or benefited from the official's decisions.
+    """
+
+    def analyze(self, entity_id: str, entity_name: str,
+                driver=None) -> dict:
+        logger.info(f"[RevolvingDoor] Analyzing {entity_name}")
+
+        transitions = self._fetch_transitions(entity_id, driver)
+        findings    = []
+        positive    = []
+
+        for t in transitions:
+            gap_days = self._day_gap(
+                t.get("left_date",""), t.get("joined_date","")
+            )
+            if gap_days is None:
+                continue
+
+            if gap_days < COOLING_OFF_DAYS:
+                findings.append({
+                    "type":     "cooling_off_violation",
+                    "severity": "HIGH" if gap_days < 180 else "MODERATE",
+                    "description": (
+                        f"{entity_name} moved from {t.get('from_role','?')} "
+                        f"at {t.get('from_org','?')} to {t.get('to_role','?')} "
+                        f"at {t.get('to_org','?')} in {gap_days} days — "
+                        f"below the expected {COOLING_OFF_DAYS}-day cooling-off period."
+                    ),
+                    "evidence": [
+                        f"Left: {t.get('from_org')} on {t.get('left_date')}",
+                        f"Joined: {t.get('to_org')} on {t.get('joined_date')}",
+                        f"Gap: {gap_days} days",
+                    ],
+                })
+
+            pre_benefit = self._check_pre_employment_benefit(
+                t, entity_id, driver
+            )
+            if pre_benefit:
+                findings.append(pre_benefit)
+
+        if not findings:
+            positive.append(
+                "No cooling-off violations or pre-employment benefit patterns "
+                "detected in available career transition data."
+            )
+
+        logger.success(
+            f"[RevolvingDoor] {entity_name}: "
+            f"{len(transitions)} transitions, {len(findings)} findings"
+        )
+        return {
+            "entity_id":         entity_id,
+            "entity_name":       entity_name,
+            "transitions_found": len(transitions),
+            "findings":          findings,
+            "positive":          positive,
+            "analyzed_at":       datetime.now().isoformat(),
+        }
+
+    def _fetch_transitions(self, entity_id: str, driver) -> list:
+        if not driver:
+            return [
+                {
+                    "from_org":    "Ministry of Finance",
+                    "from_role":   "Joint Secretary",
+                    "left_date":   "2021-03-31",
+                    "to_org":      "HDFC Bank",
+                    "to_role":     "Independent Director",
+                    "joined_date": "2021-07-15",
+                    "entity_type": "regulator_to_private",
+                },
+            ]
+        try:
+            with driver.session() as s:
+                rows = s.run(
+                    """
+                    MATCH (p {id:$id})-[:WORKED_AT]->(org)
+                    RETURN org.name AS from_org, org.role AS from_role,
+                           org.left_date AS left_date, org.type AS org_type
+                    LIMIT 20
+                    """, id=entity_id
+                ).data()
+                return [dict(r) for r in rows]
+        except Exception:
+            return []
+
+    def _check_pre_employment_benefit(self, transition: dict,
+                                       entity_id: str, driver) -> dict | None:
+        if not driver:
+            return None
+        try:
+            to_org = transition.get("to_org","")
+            with driver.session() as s:
+                row = s.run(
+                    """
+                    MATCH (c:Company {name:$name})-[:WON_CONTRACT]->(ct:Contract)
+                    WHERE ct.order_date >= $start AND ct.order_date <= $end
+                    RETURN count(ct) AS n, sum(ct.amount_crore) AS total
+                    """,
+                    name=to_org,
+                    start=transition.get("left_date","2000-01-01"),
+                    end=transition.get("joined_date","2099-01-01"),
+                ).single()
+                if row and row.get("n",0) >= 2:
+                    return {
+                        "type":     "pre_employment_benefit",
+                        "severity": "HIGH",
+                        "description": (
+                            f"{to_org} received {row['n']} government contracts "
+                            f"worth Rs {row.get('total',0):.1f} Cr during the "
+                            f"period between the official's departure and board appointment."
+                        ),
+                        "evidence": [
+                            f"Contracts: {row['n']}",
+                            f"Total: Rs {row.get('total',0):.1f} Cr",
+                            f"Window: {transition.get('left_date')} → {transition.get('joined_date')}",
+                        ],
+                    }
+        except Exception:
+            pass
+        return None
+
+    def _day_gap(self, date_a: str, date_b: str):
+        try:
+            d1 = date.fromisoformat(date_a[:10])
+            d2 = date.fromisoformat(date_b[:10])
+            return abs((d2 - d1).days)
+        except Exception:
+            return None
+
+
+if __name__ == "__main__":
+    print("=" * 55)
+    print("BharatGraph — Revolving Door Test")
+    print("=" * 55)
+    r = RevolvingDoorDetector()
+    result = r.analyze("pol_001", "Test Official", driver=None)
+    print(f"\n  Transitions: {result['transitions_found']}")
+    print(f"  Findings:    {len(result['findings'])}")
+    for f in result["findings"]:
+        print(f"  [{f['severity']}] {f['type']}: {f['description'][:70]}")
+    print("\nDone!")

ai/forensics/tbml_detector.py

@@ -0,0 +1,193 @@
+import os, sys, statistics
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+
+from datetime import datetime
+from loguru import logger
+
+PRICE_ANOMALY_SIGMA = 2.5   # std dev threshold for price anomaly
+SUBCONTRACT_DEPTH   = 3     # max re-award chain considered suspicious
+
+
+class TBMLDetector:
+    """
+    Trade-Based indicators of value transfer:
+    1. Contract price anomaly vs category median
+    2. Subcontract loop detection (A awards to B, B to C, C to A)
+    3. Award-to-director-change window (director changed shortly after contract)
+    """
+
+    def analyze(self, entity_id: str, driver=None) -> dict:
+        logger.info(f"[TBML] Analyzing {entity_id}")
+
+        findings = []
+        positive = []
+
+        price_findings  = self._price_anomaly(entity_id, driver)
+        loop_findings   = self._subcontract_loop(entity_id, driver)
+        window_findings = self._award_director_window(entity_id, driver)
+
+        findings.extend(price_findings)
+        findings.extend(loop_findings)
+        findings.extend(window_findings)
+
+        if not findings:
+            positive.append(
+                "Trade-based transfer analysis found no significant anomalies "
+                "in contract pricing, subcontracting patterns, or director changes."
+            )
+
+        logger.success(
+            f"[TBML] {entity_id}: {len(findings)} findings"
+        )
+        return {
+            "entity_id":  entity_id,
+            "findings":   findings,
+            "positive":   positive,
+            "analyzed_at":datetime.now().isoformat(),
+        }
+
+    def _price_anomaly(self, entity_id: str, driver) -> list:
+        contracts = self._fetch_contracts(entity_id, driver)
+        if len(contracts) < 3:
+            return []
+
+        amounts = [float(c.get("amount_crore") or 0) for c in contracts]
+        amounts = [a for a in amounts if a > 0]
+        if len(amounts) < 3:
+            return []
+
+        mean   = statistics.mean(amounts)
+        stdev  = statistics.stdev(amounts)
+        if stdev == 0:
+            return []
+
+        outliers = [
+            c for c in contracts
+            if abs(float(c.get("amount_crore") or 0) - mean) > PRICE_ANOMALY_SIGMA * stdev
+        ]
+        if not outliers:
+            return []
+
+        return [{
+            "type":     "contract_price_anomaly",
+            "severity": "HIGH" if len(outliers) >= 2 else "MODERATE",
+            "description": (
+                f"{len(outliers)} contract(s) have values more than "
+                f"{PRICE_ANOMALY_SIGMA} standard deviations from the "
+                f"entity's contract average (Rs {mean:.1f} Cr). "
+                f"Abnormal contract pricing may indicate value inflation."
+            ),
+            "evidence": [
+                f"Contract Rs {float(c.get('amount_crore',0)):.1f} Cr "
+                f"vs mean Rs {mean:.1f} Cr (z={abs(float(c.get('amount_crore',0))-mean)/stdev:.1f}σ)"
+                for c in outliers[:3]
+            ],
+        }]
+
+    def _subcontract_loop(self, entity_id: str, driver) -> list:
+        if not driver:
+            return []
+        try:
+            with driver.session() as s:
+                rows = s.run(
+                    """
+                    MATCH path = (c1:Company)-[:SUBCONTRACTS_TO*2..4]->(c1)
+                    WHERE any(n IN nodes(path) WHERE n.id = $id)
+                    RETURN length(path) AS depth, 
+                           [n IN nodes(path) | n.name] AS loop_nodes
+                    LIMIT 5
+                    """, id=entity_id
+                ).data()
+                if rows:
+                    return [{
+                        "type":     "subcontract_loop",
+                        "severity": "HIGH",
+                        "description": (
+                            f"Circular subcontracting detected: "
+                            f"{' → '.join((rows[0].get('loop_nodes') or [])[:4])}. "
+                            f"Contract re-award loops are a structural indicator "
+                            f"of artificial transaction chains."
+                        ),
+                        "evidence": [
+                            f"Loop depth: {rows[0].get('depth')} hops"
+                        ],
+                    }]
+        except Exception:
+            pass
+        return []
+
+    def _award_director_window(self, entity_id: str, driver) -> list:
+        if not driver:
+            return []
+        try:
+            with driver.session() as s:
+                rows = s.run(
+                    """
+                    MATCH (p {id:$id})-[:DIRECTOR_OF]->(c:Company)
+                          -[:WON_CONTRACT]->(ct:Contract)
+                    WHERE ct.order_date IS NOT NULL
+                      AND c.director_change_date IS NOT NULL
+                      AND abs(duration.inDays(
+                            date(ct.order_date),
+                            date(c.director_change_date)
+                          ).days) <= 90
+                    RETURN c.name AS company, ct.order_date AS award,
+                           c.director_change_date AS change_date
+                    LIMIT 5
+                    """, id=entity_id
+                ).data()
+                if rows:
+                    return [{
+                        "type":     "director_change_near_award",
+                        "severity": "MODERATE",
+                        "description": (
+                            f"Director change at {rows[0].get('company','?')} "
+                            f"occurred within 90 days of contract award on "
+                            f"{rows[0].get('award','?')}. Director substitution "
+                            f"near contract award is a structural risk indicator."
+                        ),
+                        "evidence": [
+                            f"Award: {r.get('award')} | Director change: {r.get('change_date')}"
+                            for r in rows[:3]
+                        ],
+                    }]
+        except Exception:
+            pass
+        return []
+
+    def _fetch_contracts(self, entity_id: str, driver) -> list:
+        if not driver:
+            return [
+                {"id":"c1","amount_crore":12.0,"buyer_org":"MoRTH"},
+                {"id":"c2","amount_crore":11.5,"buyer_org":"MoRTH"},
+                {"id":"c3","amount_crore":89.0,"buyer_org":"MoRTH"},
+                {"id":"c4","amount_crore":13.0,"buyer_org":"MoRTH"},
+            ]
+        try:
+            with driver.session() as s:
+                rows = s.run(
+                    """
+                    MATCH (p {id:$id})-[:DIRECTOR_OF]->(c:Company)
+                          -[:WON_CONTRACT]->(ct:Contract)
+                    RETURN ct.id AS id, ct.amount_crore AS amount_crore,
+                           ct.buyer_org AS buyer_org, ct.order_date AS date
+                    LIMIT 50
+                    """, id=entity_id
+                ).data()
+                return [dict(r) for r in rows]
+        except Exception:
+            return []
+
+
+if __name__ == "__main__":
+    print("=" * 55)
+    print("BharatGraph — TBML Detector Test")
+    print("=" * 55)
+    t = TBMLDetector()
+    r = t.analyze("pol_001", driver=None)
+    print(f"\n  Findings: {len(r['findings'])}")
+    for f in r["findings"]:
+        print(f"  [{f['severity']}] {f['type']}: {f['description'][:70]}")
+    if r["positive"]:
+        print(f"  Positive: {r['positive'][0][:70]}")
+    print("\nDone!")

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
+from api.routes import search, profile, graph, risk, multilingual, export, admin, investigation, affidavit, biography, benami, sources, procurement, conflict
 from api.models import HealthResponse, StatsResponse
 
 
@@ -65,6 +65,7 @@ app.include_router(biography.router,     tags=["Biography"])
 app.include_router(benami.router,       tags=["Benami"])
 app.include_router(sources.router,      tags=["Sources"])
 app.include_router(procurement.router,   tags=["Procurement"])
+app.include_router(conflict.router,       tags=["Conflict"])
 
 
 @app.get("/health", response_model=HealthResponse)

api/routes/conflict.py

@@ -0,0 +1,30 @@
+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.revolving_door import RevolvingDoorDetector
+from ai.forensics.tbml_detector  import TBMLDetector
+
+router    = APIRouter()
+rev_door  = RevolvingDoorDetector()
+tbml      = TBMLDetector()
+
+
+@router.get("/conflict/revolving-door/{entity_id}")
+def revolving_door(entity_id: str, driver=Depends(get_db)):
+    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 rev_door.analyze(entity_id, name, driver=driver)
+
+
+@router.get("/conflict/tbml/{entity_id}")
+def tbml_analysis(entity_id: str, driver=Depends(get_db)):
+    return tbml.analyze(entity_id, driver=driver)