Fix Python 3.9 compat, sync API docs, fix install instructions, remove placeholder, improve scorer performance

Author: Fahad Alghanim

README.md

@@ -4,8 +4,7 @@ Add suspicious-login detection, auth-risk scoring, and step-up decisions to your
 
 ![MIT License](https://img.shields.io/badge/license-MIT-green.svg)
 ![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)
-![Tests Passing](https://img.shields.io/badge/tests-32%20passing-brightgreen.svg)
-![Pip Installable](https://img.shields.io/badge/pip-installable-orange.svg)
+![Tests Passing](https://img.shields.io/badge/tests-35%20passing-brightgreen.svg)
 
 ## Why This Exists
 Every fintech and crypto app builds auth-risk scoring internally because generic fraud tooling rarely models authentication flow context well. Teams need to distinguish legitimate users from attackers before full identity verification and before adding friction. This project packages those patterns into an open-source toolkit with synthetic-data-first workflows so you can run everything locally.
@@ -37,26 +36,39 @@ Auth Events
 Action: allow | step-up | review | block | revoke
 ```
 
-## Quickstart
+## Install
 ```bash
-pip install identity-risk-engine
+git clone https://github.com/KOKOSde/identity-risk-engine.git
+cd identity-risk-engine
+python3 -m pip install -e .
 ```
 
+## Quickstart
 ```python
 from identity_risk_engine.simulator_ire import generate_synthetic_auth_events
 from identity_risk_engine.policy_engine import PolicyEngine
-from identity_risk_engine.risk_engine_ire import score_dataframe
+from identity_risk_engine.risk_engine_ire import score_event
 
 events = generate_synthetic_auth_events(num_users=50, num_sessions=1000, attack_ratio=0.2, seed=42)
-scored = score_dataframe(events, policy_engine=PolicyEngine())
-print(scored[["event_id", "risk_score", "action"]].head())
+event = events.iloc[50].to_dict()
+history = events.iloc[:50]
+result = score_event(event=event, history_df=history, policy_engine=PolicyEngine())
+
+print(result["risk_score"], result["decision"]["action"])
+print(result["explanation"]["human_summary"])
 ```
 
+`PolicyEngine` exposes `decide()` (not `evaluate()`), and per-event explanations are returned by `risk_engine_ire.score_event()` under `result["explanation"]`.
+
 ## CLI Quickstart
 ```bash
-identity-risk-engine simulate --users 500 --sessions 20000 --attack-ratio 0.2 --out synthetic.csv
-identity-risk-engine score --events synthetic.csv --policy configs/default_policy.yaml --out scored.csv
-identity-risk-engine report --events scored.csv --out report.html
+python3 -m identity_risk_engine.cli_ire simulate --users 500 --sessions 20000 --attack-ratio 0.2 --out synthetic.csv
+python3 -m identity_risk_engine.cli_ire score --events synthetic.csv --policy configs/default_policy.yaml --out scored.csv
+python3 -m identity_risk_engine.cli_ire report --events scored.csv --out report.html
+# fast demo mode for large files:
+python3 -m identity_risk_engine.cli_ire score --events synthetic.csv --policy configs/default_policy.yaml --fast --out scored_fast.csv
+# force full scoring mode even on large files:
+python3 -m identity_risk_engine.cli_ire score --events synthetic.csv --policy configs/default_policy.yaml --full --out scored_full.csv
 ```
 
 ## FastAPI Quickstart
@@ -114,15 +126,16 @@ Supported actions: `allow`, `allow_with_monitoring`, `step_up_with_passkey`, `st
 
 ## Benchmark Results
 Run details: `num_users=100`, `num_sessions=2400`, `attack_ratio=0.22`, `seed=21`, time split from `demo_outputs/benchmark_output_ire.txt`.
+Reproducible with `seed=42` in model training and deterministic model settings.
 
 | Cohort | AUC | Precision@0.95Recall | Recall@0.95Precision |
 |---|---:|---:|---:|
 | Global | 1.000 | 1.000 | 1.000 |
-| account_takeover | 0.914 | 0.246 | 0.000 |
-| bot_behavior | 0.904 | 0.138 | 0.000 |
-| credential_stuffing | 0.915 | 0.262 | 0.000 |
-| impossible_travel | 0.907 | 0.177 | 0.000 |
-| new_account_fraud | 0.907 | 0.177 | 0.000 |
+| account_takeover | 0.916 | 0.246 | 0.000 |
+| bot_behavior | 0.906 | 0.138 | 0.000 |
+| credential_stuffing | 0.908 | 0.262 | 0.000 |
+| impossible_travel | 0.910 | 0.177 | 0.000 |
+| new_account_fraud | 0.910 | 0.177 | 0.000 |
 
 ## Demo Output
 CLI report summary snippet (from `/tmp/ire_report.html` generated by CLI):
@@ -161,9 +174,6 @@ FastAPI `/simulate` response snippet (from `demo_outputs/fastapi_simulate_ire.tx
 - Fraud analysts
 - Security researchers
 
-## Case Study
-Coinbase case study notebook placeholder: `notebooks/coinbase_case_study.ipynb` (to be added in a follow-up).
-
 ## Related Projects
 - [onchain-sybil-detector](../onchain-sybil-detector)
 - [LocalMod](../LocalMod)

demo_outputs/benchmark_output_ire.txt

@@ -1,8 +1,7 @@
 global {'auc': 1.0, 'precision_at_95_recall': 1.0, 'recall_at_95_precision': 1.0}
 attack_type,auc,precision_at_95_recall,recall_at_95_precision
-account_takeover,0.9137323943661972,0.24615384615384617,0.0
-bot_behavior,0.9037800687285223,0.13846153846153847,0.0
-credential_stuffing,0.9151943462897526,0.26153846153846155,0.0
-impossible_travel,0.9072790294627383,0.17692307692307693,0.0
-new_account_fraud,0.9072790294627383,0.17692307692307693,0.0
-
+account_takeover,0.9163732394366197,0.24615384615384617,0.0
+bot_behavior,0.9063573883161512,0.13846153846153847,0.0
+credential_stuffing,0.9077114944917897,0.26153846153846155,0.0
+impossible_travel,0.9098786828422877,0.17692307692307693,0.0
+new_account_fraud,0.9098786828422877,0.17692307692307693,0.0

demo_outputs/benchmark_repro_ire.txt

@@ -0,0 +1,5 @@
+run1= {"auc": 1.0, "precision_at_95_recall": 1.0, "recall_at_95_precision": 1.0}
+run2= {"auc": 1.0, "precision_at_95_recall": 1.0, "recall_at_95_precision": 1.0}
+identical_global= True
+identical_by_attack= True
+by_attack= [{"attack_type": "account_takeover", "auc": 0.9163732394366197, "precision_at_95_recall": 0.24615384615384617, "recall_at_95_precision": 0.0}, {"attack_type": "bot_behavior", "auc": 0.9063573883161512, "precision_at_95_recall": 0.13846153846153847, "recall_at_95_precision": 0.0}, {"attack_type": "credential_stuffing", "auc": 0.9077114944917897, "precision_at_95_recall": 0.26153846153846155, "recall_at_95_precision": 0.0}, {"attack_type": "impossible_travel", "auc": 0.9098786828422877, "precision_at_95_recall": 0.17692307692307693, "recall_at_95_precision": 0.0}, {"attack_type": "new_account_fraud", "auc": 0.9098786828422877, "precision_at_95_recall": 0.17692307692307693, "recall_at_95_precision": 0.0}]

demo_outputs/cli_timing_report_ire.txt

@@ -0,0 +1,4 @@
+Report written -> /tmp/ire_report.html
+real 1.64
+user 2.25
+sys 0.26

demo_outputs/cli_timing_score_ire.txt

@@ -0,0 +1,17 @@
+Scored 19101 events -> /tmp/ire_scored.csv
+Scoring mode: fast-auto (history_window=8)
+Elapsed seconds: 9.12
+Mean risk score: 0.1036
+Action counts:
+  allow: 12206
+  allow_with_monitoring: 4416
+  block: 187
+  manual_review: 127
+  require_recovery_review: 217
+  revoke_session: 110
+  step_up_with_email_code: 49
+  step_up_with_passkey: 940
+  step_up_with_totp: 849
+real 11.70
+user 12.27
+sys 0.34

demo_outputs/cli_timing_simulate_ire.txt

@@ -0,0 +1,16 @@
+Generated 19101 events -> /tmp/ire_test.csv
+Attack mix:
+  account_takeover: 94
+  bot_behavior: 456
+  credential_stuffing: 779
+  impossible_travel: 156
+  mfa_fatigue: 894
+  multi_account_sybil: 630
+  new_account_fraud: 85
+  normal: 14847
+  passkey_registration_abuse: 364
+  recovery_abuse: 632
+  session_hijack: 164
+real 3.35
+user 4.15
+sys 0.34

demo_outputs/test_output_ire_fixes.txt

@@ -0,0 +1,45 @@
+============================= test session starts ==============================
+platform linux -- Python 3.9.20, pytest-8.4.2, pluggy-1.6.0 -- /usr/bin/python3.9
+cachedir: .pytest_cache
+rootdir: /scratch/fkalghan/circuit_discovery_and_supression/graphs_ai_psych/identity-risk-engine
+configfile: pyproject.toml
+plugins: cov-7.1.0, anyio-4.12.0
+collecting ... collected 35 items
+
+tests/test_behavior_anomaly.py::test_new_user_no_history_returns_uncertainty_score PASSED [  2%]
+tests/test_behavior_anomaly.py::test_insufficient_baseline_still_scores PASSED [  5%]
+tests/test_behavior_anomaly.py::test_clear_behavior_outlier_scores_higher_than_normal PASSED [  8%]
+tests/test_cli_ire.py::test_cli_simulate_score_report_smoke PASSED       [ 11%]
+tests/test_cli_ire.py::test_cli_score_fast_mode_smoke PASSED             [ 14%]
+tests/test_composite_scorer.py::test_composite_model_reaches_auc_target_on_synthetic_data PASSED [ 17%]
+tests/test_composite_scorer.py::test_predict_proba_shape_and_operating_points PASSED [ 20%]
+tests/test_composite_scorer.py::test_composite_model_is_reproducible_with_seed_42 PASSED [ 22%]
+tests/test_device_fingerprint.py::test_known_device_gets_low_novelty PASSED [ 25%]
+tests/test_device_fingerprint.py::test_new_device_is_more_novel PASSED   [ 28%]
+tests/test_device_fingerprint.py::test_new_user_without_history_scores_max_novelty PASSED [ 31%]
+tests/test_events_ire.py::test_auth_event_validates_required_schema PASSED [ 34%]
+tests/test_events_ire.py::test_event_to_row_serializes_enum_to_string PASSED [ 37%]
+tests/test_events_ire.py::test_invalid_event_type_raises_validation_error PASSED [ 40%]
+tests/test_explainer_ire.py::test_explainer_output_shape_and_content PASSED [ 42%]
+tests/test_fastapi_ire.py::test_health_endpoint PASSED                   [ 45%]
+tests/test_fastapi_ire.py::test_simulate_and_dashboard_endpoints PASSED  [ 48%]
+tests/test_fastapi_ire.py::test_events_endpoint_returns_scored_decision PASSED [ 51%]
+tests/test_geo_velocity.py::test_same_location_speed_zero PASSED         [ 54%]
+tests/test_geo_velocity.py::test_null_coordinates_do_not_crash PASSED    [ 57%]
+tests/test_geo_velocity.py::test_impossible_travel_detected PASSED       [ 60%]
+tests/test_policy_engine_ire.py::test_default_policy_mapping PASSED      [ 62%]
+tests/test_policy_engine_ire.py::test_auth_method_override_applies PASSED [ 65%]
+tests/test_policy_engine_ire.py::test_tenant_override_applies PASSED     [ 68%]
+tests/test_policy_engine_ire.py::test_dry_run_override PASSED            [ 71%]
+tests/test_risk_engine_ire.py::test_attack_events_get_nonzero_risk_scores PASSED [ 74%]
+tests/test_signals_ire.py::test_device_signals_fire_for_new_device PASSED [ 77%]
+tests/test_signals_ire.py::test_geo_signals_fire_for_impossible_travel PASSED [ 80%]
+tests/test_signals_ire.py::test_behavior_signals_fire_for_failure_burst PASSED [ 82%]
+tests/test_signals_ire.py::test_passkey_signals_fire_for_unfamiliar_device PASSED [ 85%]
+tests/test_signals_ire.py::test_recovery_signals_fire_for_unfamiliar_env PASSED [ 88%]
+tests/test_signals_ire.py::test_simulator_ire_contains_all_attack_types PASSED [ 91%]
+tests/test_synthetic_data.py::test_generator_contains_all_attack_types PASSED [ 94%]
+tests/test_synthetic_data.py::test_generator_has_required_features PASSED [ 97%]
+tests/test_synthetic_data.py::test_new_account_fraud_is_young_account PASSED [100%]
+
+======================== 35 passed in 263.28s (0:04:23) ========================

src/identity_risk_engine/behavior_anomaly.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from typing import Optional, Union
 
 import numpy as np
 import pandas as pd
@@ -30,8 +31,8 @@ class UserBehaviorProfile:
     actions_std: float
     entropy_mean: float
     entropy_std: float
-    iso_model: IsolationForest | None
-    last_timestamp: pd.Timestamp | None
+    iso_model: Optional[IsolationForest]
+    last_timestamp: Optional[pd.Timestamp]
 
 
 class BehaviorAnomalyScorer:
@@ -217,7 +218,7 @@ def score_dataframe(self, sessions_df: pd.DataFrame) -> pd.Series:
 
         return self.score(sessions_df)["behavior_anomaly_score"]
 
-    def score_session(self, session: dict[str, object] | pd.Series) -> float:
+    def score_session(self, session: Union[dict[str, object], pd.Series]) -> float:
         """Score a single session payload."""
 
         if isinstance(session, pd.Series):