rti-ethics-engine 1.0.0__tar.gz → 2.0.1__tar.gz

rti_ethics_engine-2.0.1/INPUTS_OUTPUTS.md

@@ -0,0 +1,62 @@
+# RTI Ethics Engine: Input & Output Specification
+
+Detailed API reference for the package components.
+
+## 1. Input: Metrics Dictionary Shape
+
+The primary input to `evaluate(metrics)` is a nested dictionary structured by logical dimensions.
+
+### Dimensions & Metric Keys
+
+| Dimension          | Key              | L1 Metrics (Gates)        | L2 Metrics (Risk)      | L3 Metrics (Forensic) |
+| ------------------ | ---------------- | ------------------------- | ---------------------- | --------------------- |
+| **Fairness**       | `fairness`       | `spd`, `di`, `eop`, `aod` | `fnrd`, `refusal_disp` | `mutual_info`         |
+| **Drift**          | `drift`          | `psi`, `ks`               | `pred_drift`           | `embed_drift`         |
+| **Explainability** | `explainability` | `confidence`              | `support_ratio`        | `stability`           |
+| **Legal**          | `legal`          | `lawfulness`, `cvr`       | `proportionality`      | `explanation`         |
+| **Performance**    | `performance`    | `accuracy`, `recall`      | `f1`                   | `group_f1`            |
+| **UX**             | `ux`             | `tcr`, `sla`              | `cognitive_load`       | `dtc`                 |
+| **Security**       | `security`       | `adv_acc`                 | `pisr`                 | `mir`                 |
+| **Monitoring**     | `monitoring`     | `alc`                     | `pvr`                  | `irf`                 |
+| **Environment**    | `environmental`  | `inf_cost`                | `gpu_hours`            | `compute_intensity`   |
+
+---
+
+## 2. Dynamic Computation: `build_metrics_from_raw_data`
+
+Used to convert raw arrays and runtime data into the metrics dictionary above.
+
+### Parameters
+
+| Name                   | Type         | Description                                 |
+| ---------------------- | ------------ | ------------------------------------------- |
+| `query`                | `str`        | User input string                           |
+| `response`             | `str`        | AI response string                          |
+| `predictions`          | `np.ndarray` | Binary classification array (0/1)           |
+| `labels`               | `np.ndarray` | Ground truth array (0/1)                    |
+| `sensitive_attr`       | `np.ndarray` | Sensitive group indicator (0/1)             |
+| `latency_ms`           | `float`      | Response time in milliseconds               |
+| `output_tokens`        | `int`        | Token count of AI response                  |
+| `grounding_score`      | `float`      | Score from grounding judge (0-1)            |
+| `baseline_predictions` | `np.ndarray` | (Optional) Predictions for drift comparison |
+
+---
+
+## 3. Output: `EthicsResult` Schema
+
+The object returned by evaluation gives detailed access to the 3-layer audit results.
+
+### Summary Fields
+
+- `final_label`: `ETHICAL` (Pass), `CONDITIONALLY_ETHICAL` (Review), `UNETHICAL` (Block)
+- `s_llm`: Balanced audit score [0 to 1]
+- `risk_band`: `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`
+- `layer1_status`: `PASS` (All gates green) or `FAIL`
+
+### Accessor Methods
+
+- `get_l1_metric(dim, key)`: Returns raw float value (e.g., `0.021`)
+- `get_l2_risk(dim)`: Returns normalized risk [0 to 1]
+- `get_l3_evidence(dim)`: Returns forensic explanation string or dictionary
+- `get_failed_dims()`: List of dimension names that failed L1 gates
+- `to_json()`: Serializes the entire audit trail to JSON

rti_ethics_engine-2.0.1/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: rti-ethics-engine
+Version: 2.0.1
+Summary: India's first granular AI ethics framework for RTI applications (36 metrics, 9 dimensions)
+Project-URL: Homepage, https://github.com/rti-ethics/rti-ethics-engine
+Project-URL: Documentation, https://rti-ethics-engine.readthedocs.io
+Project-URL: Repository, https://github.com/rti-ethics/rti-ethics-engine
+Project-URL: Issues, https://github.com/rti-ethics/rti-ethics-engine/issues
+Author: RTI Ethics Engine Team
+License: MIT License
+        
+        Copyright (c) 2026 RTI Ethics Engine Team
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai-ethics,audit,compliance,fairness,government,india,llm,rti
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.10.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=5.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# RTI Ethics Engine (v2.0.0)
+
+**India's first granular AI ethics framework for RTI applications** - A production-ready Python package implementing 36 metrics across 9 ethical dimensions with granular formula access and dynamic data computation.
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install rti-ethics-engine
+```
+
+## ⚡ Quick Start (Dynamic Mode)
+
+The recommended way to use the engine is to compute metrics directly from your application data:
+
+```python
+import numpy as np
+from rti_ethics_engine import evaluate_from_raw
+
+# 1. Prepare your data
+query = "What is the budget for the Metro project?"
+response = "The budget for the Metro project is 5000 Crores..."
+predictions = np.array([1, 1, 0, 1])  # Model predictions
+labels = np.array([1, 1, 1, 1])       # Ground truth
+sensitive_attr = np.array([0, 1, 0, 1]) # Demographic group (e.g. Urban/Rural)
+
+# 2. Evaluate with one call
+result = evaluate_from_raw(
+    query=query,
+    response=response,
+    predictions=predictions,
+    labels=labels,
+    sensitive_attr=sensitive_attr,
+    latency_ms=450.0,
+    grounding_score=0.92
+)
+
+# 3. Get results
+print(f"Label: {result.final_label}")  # "ETHICAL"
+print(f"S_LLM Score: {result.s_llm}")  # 0.942
+print(f"Risk Band: {result.risk_band}") # "LOW"
+```
+
+## 📊 The 3-Layer Audit Protocol
+
+The RTI Ethics Engine uses a rigorous 3-layer protocol for every dimension:
+
+1.  **Layer 1: Hard Gates (L1)** - Pass/Fail compliance checks (e.g., Statistical Parity < 0.1).
+2.  **Layer 2: Risk Scoring (L2)** - Normalized risk vectors weighted by policy importance.
+3.  **Layer 3: Forensic Evidence (L3)** - Detailed context and reasoning for the scores.
+
+### Granular Access
+
+```python
+# Check if a specific dimension passed its hard gates
+if result.get_l1_status("fairness") == "FAIL":
+    print(f"Fairness fail reasons: {result.get_l1_reasons('fairness')}")
+
+# Get granular metric values (36 metrics available)
+spd = result.get_l1_metric("fairness", "spd")
+psi = result.get_l1_metric("drift", "psi")
+
+# Export complete audit trail
+audit_json = result.to_json()
+```
+
+## 🏗️ 9 Ethical Dimensions
+
+| Dimension            | Description                          | Key Metrics                     |
+| -------------------- | ------------------------------------ | ------------------------------- |
+| **Legal Compliance** | RTI Act 2005 & Data Policy alignment | Lawfulness, Consent Validity    |
+| **Bias & Fairness**  | Demographic equity across groups     | SPD, DI, EOP, AOD               |
+| **Explainability**   | Transparency & Model Confidence      | FI Sum, Counterfactual Distance |
+| **Security**         | Robustness against prompt injection  | PISR, Adversarial Accuracy      |
+| **Monitoring**       | Audit trail & SLA integrity          | Audit Completeness, SLA rate    |
+| **Performance**      | Statistical accuracy of responses    | Recall, Group-F1, Accuracy      |
+| **Human-AI UX**      | User friction and frustration levels | TCR, Cognitive Load             |
+| **Drift**            | Model/Data stability over time       | PSI, KS-Statistic               |
+| **Environment**      | Carbon footprint & compute cost      | GPU Hours, Inference Cost       |
+
+## 📖 Documentation
+
+For detailed input/output schemas and advanced configuration, see:
+
+- [API Reference (INPUTS_OUTPUTS.md)](https://github.com/Krishil-Parikh/bazinga_tsec_hacks/blob/krishil/rti_ethics_engine/INPUTS_OUTPUTS.md)
+- [Mathematical Manifest (calculators.py)](https://github.com/Krishil-Parikh/bazinga_tsec_hacks/blob/krishil/rti_ethics_engine/rti_ethics_engine/calculators.py)
+
+## 🧪 Testing
+
+```bash
+pytest tests/ -v
+```
+
+## 🇮🇳 Why RTI Ethics Engine?
+
+Designed specifically for **Right to Information (RTI)** workflows, it ensures that AI systems responding to citizen queries are:
+
+- **Legally Sound:** Compliant with Section 4/8 of the RTI Act.
+- **Fair:** No bias between rural/urban or language variations.
+- **Auditable:** Providing forensic evidence for Central Information Commission (CIC) audits.
+
+---
+
+**License:** MIT | **Support:** [github.com/rti-ethics/rti-ethics-engine](https://github.com/rti-ethics/rti-ethics-engine)

rti_ethics_engine-2.0.1/README.md

@@ -0,0 +1,108 @@
+# RTI Ethics Engine (v2.0.0)
+
+**India's first granular AI ethics framework for RTI applications** - A production-ready Python package implementing 36 metrics across 9 ethical dimensions with granular formula access and dynamic data computation.
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install rti-ethics-engine
+```
+
+## ⚡ Quick Start (Dynamic Mode)
+
+The recommended way to use the engine is to compute metrics directly from your application data:
+
+```python
+import numpy as np
+from rti_ethics_engine import evaluate_from_raw
+
+# 1. Prepare your data
+query = "What is the budget for the Metro project?"
+response = "The budget for the Metro project is 5000 Crores..."
+predictions = np.array([1, 1, 0, 1])  # Model predictions
+labels = np.array([1, 1, 1, 1])       # Ground truth
+sensitive_attr = np.array([0, 1, 0, 1]) # Demographic group (e.g. Urban/Rural)
+
+# 2. Evaluate with one call
+result = evaluate_from_raw(
+    query=query,
+    response=response,
+    predictions=predictions,
+    labels=labels,
+    sensitive_attr=sensitive_attr,
+    latency_ms=450.0,
+    grounding_score=0.92
+)
+
+# 3. Get results
+print(f"Label: {result.final_label}")  # "ETHICAL"
+print(f"S_LLM Score: {result.s_llm}")  # 0.942
+print(f"Risk Band: {result.risk_band}") # "LOW"
+```
+
+## 📊 The 3-Layer Audit Protocol
+
+The RTI Ethics Engine uses a rigorous 3-layer protocol for every dimension:
+
+1.  **Layer 1: Hard Gates (L1)** - Pass/Fail compliance checks (e.g., Statistical Parity < 0.1).
+2.  **Layer 2: Risk Scoring (L2)** - Normalized risk vectors weighted by policy importance.
+3.  **Layer 3: Forensic Evidence (L3)** - Detailed context and reasoning for the scores.
+
+### Granular Access
+
+```python
+# Check if a specific dimension passed its hard gates
+if result.get_l1_status("fairness") == "FAIL":
+    print(f"Fairness fail reasons: {result.get_l1_reasons('fairness')}")
+
+# Get granular metric values (36 metrics available)
+spd = result.get_l1_metric("fairness", "spd")
+psi = result.get_l1_metric("drift", "psi")
+
+# Export complete audit trail
+audit_json = result.to_json()
+```
+
+## 🏗️ 9 Ethical Dimensions
+
+| Dimension            | Description                          | Key Metrics                     |
+| -------------------- | ------------------------------------ | ------------------------------- |
+| **Legal Compliance** | RTI Act 2005 & Data Policy alignment | Lawfulness, Consent Validity    |
+| **Bias & Fairness**  | Demographic equity across groups     | SPD, DI, EOP, AOD               |
+| **Explainability**   | Transparency & Model Confidence      | FI Sum, Counterfactual Distance |
+| **Security**         | Robustness against prompt injection  | PISR, Adversarial Accuracy      |
+| **Monitoring**       | Audit trail & SLA integrity          | Audit Completeness, SLA rate    |
+| **Performance**      | Statistical accuracy of responses    | Recall, Group-F1, Accuracy      |
+| **Human-AI UX**      | User friction and frustration levels | TCR, Cognitive Load             |
+| **Drift**            | Model/Data stability over time       | PSI, KS-Statistic               |
+| **Environment**      | Carbon footprint & compute cost      | GPU Hours, Inference Cost       |
+
+## 📖 Documentation
+
+For detailed input/output schemas and advanced configuration, see:
+
+- [API Reference (INPUTS_OUTPUTS.md)](https://github.com/Krishil-Parikh/bazinga_tsec_hacks/blob/krishil/rti_ethics_engine/INPUTS_OUTPUTS.md)
+- [Mathematical Manifest (calculators.py)](https://github.com/Krishil-Parikh/bazinga_tsec_hacks/blob/krishil/rti_ethics_engine/rti_ethics_engine/calculators.py)
+
+## 🧪 Testing
+
+```bash
+pytest tests/ -v
+```
+
+## 🇮🇳 Why RTI Ethics Engine?
+
+Designed specifically for **Right to Information (RTI)** workflows, it ensures that AI systems responding to citizen queries are:
+
+- **Legally Sound:** Compliant with Section 4/8 of the RTI Act.
+- **Fair:** No bias between rural/urban or language variations.
+- **Auditable:** Providing forensic evidence for Central Information Commission (CIC) audits.
+
+---
+
+**License:** MIT | **Support:** [github.com/rti-ethics/rti-ethics-engine](https://github.com/rti-ethics/rti-ethics-engine)

{rti_ethics_engine-1.0.0 → rti_ethics_engine-2.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rti-ethics-engine"
-version = "1.0.0"
+version = "2.0.1"
 description = "India's first granular AI ethics framework for RTI applications (36 metrics, 9 dimensions)"
 readme = "README.md"
 license = {file = "LICENSE"}
@@ -37,7 +37,8 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules"
 ]
 dependencies = [
-    "numpy>=1.24.0"
+    "numpy>=1.24.0",
+    "scipy>=1.10.0"
 ]
 
 [project.optional-dependencies]
@@ -61,12 +62,14 @@ Issues = "https://github.com/rti-ethics/rti-ethics-engine/issues"
 
 [tool.hatch.build.targets.wheel]
 packages = ["rti_ethics_engine"]
+include = ["INPUTS_OUTPUTS.md"]
 
 [tool.hatch.build.targets.sdist]
 include = [
     "/rti_ethics_engine",
     "/tests",
     "/README.md",
+    "/INPUTS_OUTPUTS.md",
     "/LICENSE"
 ]
 

rti_ethics_engine-2.0.1/rti_ethics_engine/__init__.py

@@ -0,0 +1,180 @@
+"""
+RTI Ethics Engine - Production AI Ethics Framework for RTI Applications
+India's first granular 9-dimension AI ethics evaluator (36 metrics)
+
+ALL METRICS COMPUTED DYNAMICALLY FROM DATA - NO HARDCODED VALUES.
+
+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())                  # []
+
+Dynamic Metrics (compute from raw data):
+    from rti_ethics_engine import build_metrics_from_raw_data, MetricCalculator
+    
+    # Build metrics from actual data
+    metrics = build_metrics_from_raw_data(
+        query="What is Section 4?",
+        response="Section 4 requires...",
+        predictions=np.array([1, 0, 1]),
+        labels=np.array([1, 1, 0]),
+        sensitive_attr=np.array([0, 1, 1]),
+        latency_ms=500.0
+    )
+    result = evaluate(metrics)
+"""
+
+from .core import EthicsEngine
+from .results import EthicsResult, DimensionResult, RiskBand, FinalLabel
+from .config import (
+    # Backwards-compatible static exports
+    L1_THRESHOLDS, 
+    DIMENSION_WEIGHTS, 
+    RISK_THRESHOLDS,
+    DIMENSION_INFO,
+    METRIC_CATALOG,
+    # Dynamic config functions
+    get_l1_thresholds,
+    get_dimension_weights,
+    get_risk_thresholds,
+    get_config_from_data,
+    get_similarity_function,
+    generate_columns_from_formulas,
+    reset_config,
+    DynamicConfigLoader
+)
+from .metrics import (
+    build_default_metrics,
+    build_metrics_from_raw_data,
+    compute_fairness_from_data,
+    compute_drift_from_data,
+    compute_environmental_from_data,
+    compute_ux_from_text,
+    compute_legal_from_response,
+    compute_performance_from_data,
+    compute_monitoring_from_data,
+    compute_security_from_data,
+    compute_explainability_from_data,
+    test_dynamic_formulas
+)
+from .calculators import (
+    # Individual metric calculators
+    compute_spd, compute_di, compute_eop, compute_aod,
+    compute_fnrd, compute_refusal_disparity, compute_mutual_info_leakage,
+    compute_psi, compute_ks_statistic, compute_prediction_drift,
+    compute_inference_cost, compute_gpu_hours,
+    compute_readability_fk, compute_cognitive_load,
+    compute_accuracy, compute_recall, compute_f1, compute_group_f1,
+    # Master calculator class
+    MetricCalculator
+)
+
+__version__ = "2.0.1"  # Major version bump for dynamic computation
+__author__ = "RTI Ethics Engine Team"
+__license__ = "MIT"
+
+__all__ = [
+    # Core classes
+    "EthicsEngine",
+    "EthicsResult", 
+    "DimensionResult",
+    "MetricCalculator",
+    # Enums
+    "RiskBand",
+    "FinalLabel",
+    # Config (static - backwards compatible)
+    "L1_THRESHOLDS",
+    "DIMENSION_WEIGHTS",
+    "RISK_THRESHOLDS",
+    "DIMENSION_INFO",
+    "METRIC_CATALOG",
+    # Config (dynamic)
+    "get_l1_thresholds",
+    "get_dimension_weights",
+    "get_risk_thresholds",
+    "get_config_from_data",
+    "get_similarity_function",
+    "generate_columns_from_formulas",
+    "reset_config",
+    "DynamicConfigLoader",
+    # Metric builders
+    "build_default_metrics",
+    "build_metrics_from_raw_data",
+    "compute_fairness_from_data",
+    "compute_drift_from_data",
+    "compute_environmental_from_data",
+    "compute_ux_from_text",
+    "compute_legal_from_response",
+    "compute_performance_from_data",
+    "compute_monitoring_from_data",
+    "compute_security_from_data",
+    "compute_explainability_from_data",
+    # Individual calculators
+    "compute_spd", "compute_di", "compute_eop", "compute_aod",
+    "compute_fnrd", "compute_mutual_info_leakage",
+    "compute_psi", "compute_ks_statistic",
+    "compute_accuracy", "compute_recall", "compute_f1",
+    "compute_readability_fk",
+    # Helpers
+    "evaluate",
+    "test_dynamic_formulas",
+]
+
+
+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)
+
+
+def evaluate_from_raw(
+    query: str,
+    response: str,
+    **kwargs
+) -> EthicsResult:
+    """
+    Evaluate ethics directly from raw data (no pre-computed metrics needed).
+    
+    Args:
+        query: User query text
+        response: LLM response text
+        **kwargs: Additional data (predictions, labels, sensitive_attr, latency_ms, etc.)
+    
+    Returns:
+        EthicsResult with complete evaluation
+    
+    Example:
+        result = evaluate_from_raw(
+            query="What is Section 4 of RTI?",
+            response="Section 4 mandates proactive disclosure...",
+            latency_ms=500,
+            grounding_score=0.9
+        )
+        print(result.final_label)
+    """
+    metrics = build_metrics_from_raw_data(query, response, **kwargs)
+    return evaluate(metrics)