rti-ethics-engine 1.0.0__py3-none-any.whl

rti_ethics_engine/__init__.py

@@ -0,0 +1,73 @@
+"""
+RTI Ethics Engine - Production AI Ethics Framework for RTI Applications
+India's first granular 9-dimension AI ethics evaluator (36 metrics)
+
+Quick Start:
+    from rti_ethics_engine import evaluate
+    
+    metrics = {
+        "fairness": {"spd": 0.02, "di": 1.0, "eop": 0.05, "aod": 0.03},
+        "legal": {"lawfulness": 1.0, "cvr": 0.98},
+        # ... other dimensions
+    }
+    
+    result = evaluate(metrics)
+    print(result.final_label)        # "ETHICAL"
+    print(result.s_llm)              # 0.92
+    
+    # Granular access
+    print(result.get_l1_metric("fairness", "spd"))  # 0.02
+    print(result.get_failed_dims())                  # []
+"""
+
+from .core import EthicsEngine
+from .results import EthicsResult, DimensionResult, RiskBand, FinalLabel
+from .config import (
+    L1_THRESHOLDS, 
+    DIMENSION_WEIGHTS, 
+    RISK_THRESHOLDS,
+    DIMENSION_INFO,
+    METRIC_CATALOG
+)
+from .metrics import build_default_metrics
+
+__version__ = "1.0.0"
+__author__ = "RTI Ethics Engine Team"
+__license__ = "MIT"
+
+__all__ = [
+    # Core classes
+    "EthicsEngine",
+    "EthicsResult", 
+    "DimensionResult",
+    # Enums
+    "RiskBand",
+    "FinalLabel",
+    # Config
+    "L1_THRESHOLDS",
+    "DIMENSION_WEIGHTS",
+    "RISK_THRESHOLDS",
+    "DIMENSION_INFO",
+    "METRIC_CATALOG",
+    # Helpers
+    "evaluate",
+    "build_default_metrics",
+]
+
+
+def evaluate(metrics: dict) -> EthicsResult:
+    """
+    Quick evaluation entrypoint.
+    
+    Args:
+        metrics: Dict of dimension -> metrics mapping.
+    
+    Returns:
+        EthicsResult with complete evaluation and granular accessors.
+    
+    Example:
+        result = evaluate({"fairness": {"spd": 0.02}, "legal": {"lawfulness": 1.0}})
+        print(result.final_label)  # "ETHICAL"
+    """
+    engine = EthicsEngine()
+    return engine.run_protocol(metrics)

rti_ethics_engine/config.py

@@ -0,0 +1,169 @@
+"""
+RTI Ethics Engine - Configuration Module
+Centralized thresholds and weights for all 36 metrics.
+"""
+
+from typing import Dict, Any
+
+# ================== L1 THRESHOLDS (Hard Gates) ==================
+# These are the strict mathematical gates that must pass for L1 approval.
+# Violation of ANY threshold results in L1 FAIL for that dimension.
+
+L1_THRESHOLDS: Dict[str, Dict[str, float]] = {
+    "fairness": {
+        "spd": 0.1,          # Statistical Parity Difference: |SPD| <= 0.1
+        "di_min": 0.8,       # Disparate Impact: 0.8 <= DI <= 1.25
+        "di_max": 1.25,
+        "eop": 0.1,          # Equal Opportunity Difference: |EOP| <= 0.1
+        "aod": 0.1           # Average Odds Difference: |AOD| <= 0.1
+    },
+    "drift": {
+        "psi": 0.2,          # Population Stability Index: PSI <= 0.2
+        "ks": 0.05           # Kolmogorov-Smirnov statistic: KS <= 0.05
+    },
+    "environmental": {
+        "inf_cost_max": 0.05,   # Max inference cost (USD)
+        "gpu_hours_max": 0.1    # Max GPU hours per query
+    },
+    "explainability": {
+        "confidence_min": 0.6,  # Minimum model confidence
+        "fi_min": 0.1           # Minimum feature importance coverage
+    },
+    "ux": {
+        "tcr_min": 0.85,     # Task Completion Rate: TCR >= 0.85
+        "ftr_max": 0.15      # Frustration Rate: FTR <= 0.15
+    },
+    "legal": {
+        "lawfulness": 1.0,   # Must have legal basis (binary)
+        "cvr_min": 0.95      # Consent Validity Rate: CVR >= 0.95
+    },
+    "performance": {
+        "accuracy_min": 0.8,  # Minimum accuracy
+        "recall_min": 0.75    # Minimum recall
+    },
+    "monitoring": {
+        "alc_min": 0.95,     # Audit Log Completeness: ALC >= 0.95
+        "sla_min": 0.99      # SLA Compliance: SLA >= 0.99
+    },
+    "security": {
+        "adv_acc_min": 0.7,  # Adversarial Accuracy: AdvAcc >= 0.7
+        "pisr_max": 0.05     # Prompt Injection Success Rate: PISR <= 0.05
+    }
+}
+
+# ================== DIMENSION WEIGHTS (Step 904) ==================
+# Authoritative Policy Weights - NO NORMALIZATION (Sum = 1.24)
+# These reflect the relative importance of each dimension in RTI context.
+
+DIMENSION_WEIGHTS: Dict[str, float] = {
+    "legal": 0.20,
+    "fairness": 0.20,
+    "explainability": 0.16,
+    "security": 0.16,
+    "monitoring": 0.16,
+    "performance": 0.12,
+    "ux": 0.12,
+    "drift": 0.08,
+    "environmental": 0.04
+}
+
+# ================== RISK THRESHOLDS ==================
+# Tau values for categorical decision boundaries
+
+RISK_THRESHOLDS: Dict[str, float] = {
+    "tau1": 0.3,  # Below this: LOW risk
+    "tau2": 0.7   # Above this: HIGH risk (0.3-0.7 = MEDIUM)
+}
+
+# ================== DIMENSION METADATA ==================
+# Human-readable names and descriptions for each dimension
+
+DIMENSION_INFO: Dict[str, Dict[str, str]] = {
+    "legal": {
+        "name": "Legal Compliance",
+        "description": "Statutory alignment with the RTI Act 2005."
+    },
+    "fairness": {
+        "name": "Bias & Fairness",
+        "description": "Ensures equitable outcomes across demographics."
+    },
+    "explainability": {
+        "name": "Explainability & Transparency",
+        "description": "Ensures system reasoning is interpretable."
+    },
+    "security": {
+        "name": "Security & Robustness",
+        "description": "Resistance to prompt injection and poisoning."
+    },
+    "monitoring": {
+        "name": "Monitoring & Compliance",
+        "description": "Integrity of the audit trail."
+    },
+    "performance": {
+        "name": "Model Performance",
+        "description": "Core statistical accuracy and recall."
+    },
+    "ux": {
+        "name": "Human-AI UX",
+        "description": "Evaluates user friction and reading complexity."
+    },
+    "drift": {
+        "name": "Data & Model Drift",
+        "description": "Detects performance degradation over time."
+    },
+    "environmental": {
+        "name": "Environmental & Cost",
+        "description": "Monitors carbon footprint and compute efficiency."
+    }
+}
+
+# ================== METRIC CATALOG ==================
+# Complete catalog of all 36 metrics organized by layer and dimension
+
+METRIC_CATALOG: Dict[str, Dict[str, list]] = {
+    "fairness": {
+        "l1": ["spd", "di", "eop", "aod"],
+        "l2": ["fnrd", "pred_parity", "refusal_disp"],
+        "l3": ["counterfactual", "mi_leakage"]
+    },
+    "drift": {
+        "l1": ["psi", "ks"],
+        "l2": ["pred_drift", "conf_drift"],
+        "l3": ["emb_drift"]
+    },
+    "environmental": {
+        "l1": ["inf_cost", "gpu_hours"],
+        "l2": ["compute_intensity", "hardware_util"],
+        "l3": ["cur"]
+    },
+    "explainability": {
+        "l1": ["confidence", "fi"],
+        "l2": ["counterfactual_dist"],
+        "l3": ["exp_stability"]
+    },
+    "ux": {
+        "l1": ["tcr", "ftr"],
+        "l2": ["dtc", "cognitive_load"],
+        "l3": ["readability_fk"]
+    },
+    "legal": {
+        "l1": ["lawfulness", "cvr"],
+        "l2": ["proportionality"],
+        "l3": ["dpia"]
+    },
+    "performance": {
+        "l1": ["accuracy", "recall"],
+        "l2": ["group_f1"],
+        "l3": ["acc_lt"]
+    },
+    "monitoring": {
+        "l1": ["alc", "sla"],
+        "l2": ["pvr"],
+        "l3": ["irf"]
+    },
+    "security": {
+        "l1": ["adv_acc", "pisr"],
+        "l2": ["mir"],
+        "l3": ["pdr"]
+    }
+}

rti_ethics_engine/core.py

@@ -0,0 +1,184 @@
+"""
+RTI Ethics Engine - Core Orchestrator
+Main EthicsEngine class that coordinates evaluation across all dimensions.
+"""
+
+from datetime import datetime
+from typing import Dict, Any
+
+from .config import DIMENSION_WEIGHTS, RISK_THRESHOLDS, DIMENSION_INFO
+from .dimensions import create_all_dimensions
+from .results import EthicsResult, DimensionResult
+
+
+class EthicsEngine:
+    """
+    RTI Ethics Engine - Production AI Ethics Evaluator
+    
+    Implements a 3-layer evaluation protocol:
+    - Layer 1 (L1): Hard mathematical gates (pass/fail)
+    - Layer 2 (L2): Weighted risk scoring [0, 1]
+    - Layer 3 (L3): Forensic evidence bundle for CIC auditors
+    
+    Example usage:
+        engine = EthicsEngine()
+        result = engine.run_protocol(metrics)
+        
+        # Access results
+        print(result.final_label)                      # "ETHICAL"
+        print(result.get_l1_metric("fairness", "spd")) # 0.023
+        print(result.get_failed_dims())                # []
+    """
+    
+    def __init__(self):
+        """Initialize the ethics engine with all 9 dimensions."""
+        self.dimensions = create_all_dimensions()
+        self.weights = DIMENSION_WEIGHTS
+    
+    def run_protocol(self, all_metrics: Dict[str, Dict[str, Any]]) -> EthicsResult:
+        """
+        Execute the complete 3-layer ethics evaluation protocol.
+        
+        Args:
+            all_metrics: Dict of dimension -> metrics mapping.
+                Example: {
+                    "fairness": {"spd": 0.02, "di": 1.0, "eop": 0.05, "aod": 0.03},
+                    "legal": {"lawfulness": 1.0, "cvr": 0.98},
+                    ...
+                }
+        
+        Returns:
+            EthicsResult with complete evaluation data and granular accessors.
+        """
+        # Initialize tracking
+        total_weighted_risk = 0.0
+        risk_vector: Dict[str, float] = {}
+        audit_trail: list = []
+        l1_failed_dims: list = []
+        dimension_results: Dict[str, DimensionResult] = {}
+        layer3_explanations: Dict[str, Any] = {}
+        
+        # Generate audit ID
+        audit_id = f"RTI-{datetime.now().strftime('%Y%j%H%M%S')}"
+        
+        # STEP 1: Evaluate ALL dimensions (NO early return)
+        for key, dim in self.dimensions.items():
+            m = all_metrics.get(key, {})
+            
+            # Layer 1: Hard gate evaluation
+            l1_status, l1_reasons = dim.evaluate_layer1(m)
+            
+            # L1 FAIL -> L2 = 1.0 MAX RISK (hard gate enforcement)
+            if l1_status == "FAIL":
+                l2_risk = 1.0
+                l2_indicators = ["L1_HARD_GATE_VIOLATION"]
+                l1_failed_dims.append(dim.name)
+                audit_trail.append(f"L1 {dim.name}: ❌ FAIL -> L2=1.00")
+            else:
+                # Layer 2: Risk scoring
+                l2_risk, l2_indicators = dim.evaluate_layer2(m)
+                audit_trail.append(f"L1 {dim.name}: ✅ PASS -> L2={l2_risk:.2f}")
+            
+            # Layer 3: Forensic evidence
+            l3_evidence = dim.get_layer3_evidence(
+                m, (l1_status, l1_reasons), (l2_risk, l2_indicators)
+            )
+            
+            # Store dimension result
+            dimension_results[key] = DimensionResult(
+                key=key,
+                name=dim.name,
+                l1_status=l1_status,
+                l1_reasons=l1_reasons,
+                l2_risk=l2_risk,
+                l2_indicators=l2_indicators,
+                l3_evidence=l3_evidence,
+                raw_metrics=m
+            )
+            
+            # Weighted risk aggregation
+            total_weighted_risk += l2_risk * self.weights[key]
+            risk_vector[dim.name] = round(l2_risk, 4)
+            layer3_explanations[key] = l3_evidence
+        
+        # STEP 2: Calculate S_LLM (LLM Ethics Score)
+        s_llm = 1.0 - total_weighted_risk
+        
+        # STEP 3: Determine final decision based on weighted risk
+        final_label, risk_band, required_action = self._determine_decision(
+            total_weighted_risk, l1_failed_dims, dimension_results
+        )
+        
+        # Determine overall L1 status
+        layer1_status = "FAIL" if l1_failed_dims else "PASS"
+        
+        # Build and return EthicsResult
+        return EthicsResult(
+            final_label=final_label,
+            layer1_status=layer1_status,
+            layer2_risk_score=round(total_weighted_risk, 4),
+            s_llm=round(s_llm, 4),
+            risk_band=risk_band,
+            required_action=required_action,
+            audit_id=audit_id,
+            risk_vector=risk_vector,
+            dimension_results=dimension_results,
+            layer3_evidence={
+                "audit_trail": audit_trail,
+                "explanations": layer3_explanations
+            }
+        )
+    
+    def _determine_decision(
+        self, 
+        total_risk: float, 
+        l1_failed: list,
+        dimension_results: Dict[str, DimensionResult]
+    ) -> tuple:
+        """
+        Determine final label, risk band, and required action.
+        
+        Decision logic:
+        1. If all L1 fail AND high risk -> CRITICAL / BLOCK_AND_PURGE
+        2. If risk > tau2 (0.7) -> UNETHICAL / HIGH / BLOCK_AND_REVIEW
+        3. If any L1 fail -> CONDITIONALLY_ETHICAL / MEDIUM / REVIEW_FAILED_DIMS
+        4. If risk > tau1 (0.3) -> CONDITIONALLY_ETHICAL / MEDIUM / HUMAN_REVIEW
+        5. Otherwise -> ETHICAL / LOW / NONE
+        """
+        tau1 = RISK_THRESHOLDS["tau1"]
+        tau2 = RISK_THRESHOLDS["tau2"]
+        
+        if total_risk > tau2:
+            # High aggregate risk (>= 0.70)
+            all_failed = all(v.l1_status == "FAIL" for v in dimension_results.values())
+            if all_failed:
+                return "UNETHICAL", "CRITICAL", "BLOCK_AND_PURGE"
+            return "UNETHICAL", "HIGH", "BLOCK_AND_REVIEW"
+        
+        elif l1_failed:
+            # At least one dimension failed L1, but total risk is manageable
+            return "CONDITIONALLY_ETHICAL", "MEDIUM", f"REVIEW_FAILED_DIMS ({', '.join(l1_failed)})"
+        
+        elif total_risk > tau1:
+            # All L1 pass, but moderate aggregate risk (> 0.30)
+            return "CONDITIONALLY_ETHICAL", "MEDIUM", "HUMAN_REVIEW (Risk)"
+        
+        else:
+            # Low risk (< 0.30) and all L1 pass
+            return "ETHICAL", "LOW", "NONE"
+    
+    def evaluate(self, all_metrics: Dict[str, Dict[str, Any]]) -> EthicsResult:
+        """Alias for run_protocol() for convenience."""
+        return self.run_protocol(all_metrics)
+    
+    def get_dimension_names(self) -> list:
+        """Get list of all dimension names."""
+        return [dim.name for dim in self.dimensions.values()]
+    
+    def get_dimension_keys(self) -> list:
+        """Get list of all dimension keys."""
+        return list(self.dimensions.keys())
+    
+    def get_weights(self) -> Dict[str, float]:
+        """Get dimension weights."""
+        return self.weights.copy()