rai-audit-core 0.1.0__tar.gz

rai_audit_core-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Packaging / build
+build/
+dist/
+*.egg-info/
+*.egg
+pip-wheel-metadata/
+*.whl
+
+# Test / coverage / type checking
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+
+# Audit runtime artifacts
+.rai-audit/
+*_audit_report.html
+*_audit_report.md
+*_audit_report.json
+loan_audit_report.*
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+# Typical dev data
+dev-data/

rai_audit_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sai Teja Erukude
+
+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.

rai_audit_core-0.1.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: rai-audit-core
+Version: 0.1.0
+Summary: Shared audit engine, findings, reports, and CLI for the RAI Audit Kit
+Author: Sai Teja Erukude
+License: MIT License
+        
+        Copyright (c) 2026 Sai Teja Erukude
+        
+        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: audit,fairness,responsible-ai,trustworthy-ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# rai-audit-core

rai_audit_core-0.1.0/README.md

@@ -0,0 +1 @@
+# rai-audit-core

rai_audit_core-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rai-audit-core"
+version = "0.1.0"
+description = "Shared audit engine, findings, reports, and CLI for the RAI Audit Kit"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Sai Teja Erukude" }]
+requires-python = ">=3.10"
+keywords = ["responsible-ai", "audit", "fairness", "trustworthy-ai"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "typer>=0.12",
+  "rich>=13.0",
+]
+
+[project.scripts]
+rai-audit = "rai_audit.core.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rai_audit"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""

rai_audit_core-0.1.0/src/rai_audit/core/__init__.py

@@ -0,0 +1,19 @@
+from rai_audit.core.findings import (
+    AuditFinding,
+    AuditReport,
+    CategoryRisk,
+    RemediationEffort,
+    RiskLevel,
+    Severity,
+)
+from rai_audit.core.scoring import compute_risk_matrix
+
+__all__ = [
+    "AuditFinding",
+    "AuditReport",
+    "CategoryRisk",
+    "RemediationEffort",
+    "RiskLevel",
+    "Severity",
+    "compute_risk_matrix",
+]

rai_audit_core-0.1.0/src/rai_audit/core/cli.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from rai_audit.core.history import diff_runs, list_runs, load_run, render_diff_text
+from rai_audit.core.scoring import gate_check
+
+app = typer.Typer(
+    name="rai-audit",
+    help="Responsible AI (RAI) Audit Kit — evidence-grade audits for responsible AI systems.",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.command()
+def init(
+    project: str = typer.Option("my-project", help="Project name"),
+    output: Path = typer.Option(Path("audit.yaml"), help="Output config path"),
+) -> None:
+    """Scaffold a starter audit.yaml config file."""
+    config = f"""project:
+  name: {project}
+  owner: ""
+  version: 0.1.0
+
+audit:
+  output_dir: ./audit-report
+  report_formats:
+    - html
+    - markdown
+    - json
+
+checks:
+  fairness:
+    enabled: true
+    max_demographic_parity_difference: 0.10
+    max_equal_opportunity_difference: 0.10
+  robustness:
+    enabled: true
+  data_quality:
+    enabled: true
+  drift:
+    enabled: false
+
+gate:
+  min_score: null
+  fail_on_critical: true
+"""
+    output.write_text(config, encoding="utf-8")
+    console.print(f"[green]✓[/green] Created {output}")
+
+
+@app.command()
+def report(
+    input: Path = typer.Argument(..., help="Path to a saved audit JSON run"),
+    format: str = typer.Option("html", help="Output format: html | markdown | json"),
+    output: Optional[Path] = typer.Option(None, help="Output file path"),
+) -> None:
+    """Render a report from a saved audit run JSON file."""
+    if not input.exists():
+        console.print(f"[red]Error:[/red] {input} not found")
+        raise typer.Exit(1)
+
+    run = load_run(input)
+
+    if output is None:
+        output = input.with_suffix(f".{format}" if format != "json" else ".out.json")
+
+    if format == "json":
+        output.write_text(json.dumps(run, indent=2), encoding="utf-8")
+    elif format == "markdown":
+        from rai_audit.core.findings import AuditReport, AuditFinding, CategoryRisk, Severity, RiskLevel, RemediationEffort
+        from rai_audit.core.report import render_markdown
+        report_obj = _dict_to_report(run)
+        output.write_text(render_markdown(report_obj), encoding="utf-8")
+    elif format == "html":
+        from rai_audit.core.report import render_html
+        report_obj = _dict_to_report(run)
+        output.write_text(render_html(report_obj), encoding="utf-8")
+    else:
+        console.print(f"[red]Unknown format:[/red] {format}")
+        raise typer.Exit(1)
+
+    console.print(f"[green]✓[/green] Report written to {output}")
+
+
+@app.command()
+def gate(
+    input: Path = typer.Argument(..., help="Path to saved audit JSON run"),
+    min_score: Optional[float] = typer.Option(None, help="Minimum required score"),
+    fail_on_critical: bool = typer.Option(True, help="Fail if any critical findings exist"),
+    output_json: Optional[Path] = typer.Option(None, help="Write gate result to JSON file"),
+) -> None:
+    """
+    CI/CD deployment gate. Exits with code 1 on failure, 0 on pass.
+    """
+    if not input.exists():
+        console.print(f"[red]Error:[/red] {input} not found")
+        raise typer.Exit(1)
+
+    run = load_run(input)
+    passed, reason = gate_check(run, min_score=min_score, fail_on_critical=fail_on_critical)
+
+    risk_matrix = {r["category"]: r["risk_level"] for r in run.get("risk_matrix", [])}
+    critical_count = sum(
+        1 for f in run.get("findings", []) if f.get("severity") == "critical"
+    )
+
+    result = {
+        "passed": passed,
+        "reason": reason,
+        "critical_count": critical_count,
+        "risk_matrix": risk_matrix,
+    }
+
+    if output_json:
+        output_json.write_text(json.dumps(result, indent=2), encoding="utf-8")
+
+    if passed:
+        console.print(f"[green]✓ GATE PASSED:[/green] {reason}")
+    else:
+        console.print(f"[red]✗ GATE FAILED:[/red] {reason}")
+        raise typer.Exit(1)
+
+
+@app.command()
+def diff(
+    run_a: Path = typer.Argument(..., help="Older audit run JSON"),
+    run_b: Path = typer.Argument(..., help="Newer audit run JSON"),
+    output_json: Optional[Path] = typer.Option(None, help="Write diff to JSON file"),
+) -> None:
+    """Compare two audit runs and show what changed."""
+    for p in [run_a, run_b]:
+        if not p.exists():
+            console.print(f"[red]Error:[/red] {p} not found")
+            raise typer.Exit(1)
+
+    result = diff_runs(run_a, run_b)
+
+    if output_json:
+        output_json.write_text(json.dumps(result, indent=2), encoding="utf-8")
+
+    console.print(render_diff_text(result))
+
+
+@app.command()
+def history(
+    directory: Path = typer.Option(Path(".rai-audit/history"), help="History directory"),
+) -> None:
+    """List past audit runs."""
+    runs = list_runs(directory)
+    if not runs:
+        console.print("No audit runs found.")
+        return
+
+    table = Table(title="Audit History")
+    table.add_column("File", style="cyan")
+    table.add_column("Project")
+    table.add_column("Risk")
+    table.add_column("Findings", justify="right")
+
+    for run_path in runs:
+        try:
+            run = load_run(run_path)
+            risk_levels = [r["risk_level"] for r in run.get("risk_matrix", [])]
+            worst = max(risk_levels, key=lambda r: ["low","medium","high","critical"].index(r)) if risk_levels else "n/a"
+            count = sum(1 for f in run.get("findings", []) if f.get("severity") not in ("passed", "info"))
+            table.add_row(run_path.name, run.get("project_name", "?"), worst.upper(), str(count))
+        except Exception:
+            table.add_row(run_path.name, "?", "?", "?")
+
+    console.print(table)
+
+
+def _dict_to_report(d: dict):
+    """Reconstruct an AuditReport from a saved dict (for re-rendering)."""
+    from rai_audit.core.findings import (
+        AuditFinding, AuditReport, CategoryRisk,
+        RemediationEffort, RiskLevel, Severity,
+    )
+
+    findings = [
+        AuditFinding(
+            check_id=f["check_id"],
+            title=f["title"],
+            severity=Severity(f["severity"]),
+            description=f["description"],
+            evidence=f.get("evidence", {}),
+            recommendation=f.get("recommendation", ""),
+            category=f.get("category", ""),
+            affected_group=f.get("affected_group"),
+            remediation_effort=RemediationEffort(f.get("remediation_effort", "medium")),
+            standards_refs=f.get("standards_refs", []),
+            timestamp=f.get("timestamp"),
+        )
+        for f in d.get("findings", [])
+    ]
+
+    risk_matrix = [
+        CategoryRisk(
+            category=r["category"],
+            risk_level=RiskLevel(r["risk_level"]),
+            finding_count=r["finding_count"],
+            passed_count=r["passed_count"],
+        )
+        for r in d.get("risk_matrix", [])
+    ]
+
+    return AuditReport(
+        project_name=d.get("project_name", "Audit"),
+        audit_type=d.get("audit_type", ""),
+        risk_matrix=risk_matrix,
+        findings=findings,
+        metadata=d.get("metadata", {}),
+        overall_score=d.get("overall_score"),
+    )

rai_audit_core-0.1.0/src/rai_audit/core/engine.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import asyncio
+from abc import ABC, abstractmethod
+from concurrent.futures import ThreadPoolExecutor
+
+from rai_audit.core.findings import AuditReport
+
+
+class BaseAudit(ABC):
+    """Abstract base class for all audit modules."""
+
+    @abstractmethod
+    def run(self) -> AuditReport:
+        """Execute the audit synchronously and return a report."""
+        ...
+
+    async def run_async(self) -> AuditReport:
+        """Execute the audit asynchronously (default: runs sync in a thread pool)."""
+        loop = asyncio.get_event_loop()
+        with ThreadPoolExecutor() as pool:
+            return await loop.run_in_executor(pool, self.run)

rai_audit_core-0.1.0/src/rai_audit/core/findings.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+class Severity(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+    PASSED = "passed"
+
+
+class RiskLevel(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+class RemediationEffort(str, Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+@dataclass
+class AuditFinding:
+    check_id: str
+    title: str
+    severity: Severity
+    description: str
+    evidence: dict[str, Any]
+    recommendation: str
+    category: str = ""
+    affected_group: str | None = None
+    remediation_effort: RemediationEffort = RemediationEffort.MEDIUM
+    standards_refs: list[str] = field(default_factory=list)
+    timestamp: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "check_id": self.check_id,
+            "title": self.title,
+            "severity": self.severity.value,
+            "description": self.description,
+            "evidence": self.evidence,
+            "recommendation": self.recommendation,
+            "category": self.category,
+            "affected_group": self.affected_group,
+            "remediation_effort": self.remediation_effort.value,
+            "standards_refs": self.standards_refs,
+            "timestamp": self.timestamp,
+        }
+
+
+@dataclass
+class CategoryRisk:
+    category: str
+    risk_level: RiskLevel
+    finding_count: int
+    passed_count: int
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "category": self.category,
+            "risk_level": self.risk_level.value,
+            "finding_count": self.finding_count,
+            "passed_count": self.passed_count,
+        }
+
+
+@dataclass
+class AuditReport:
+    project_name: str
+    audit_type: str
+    risk_matrix: list[CategoryRisk]
+    findings: list[AuditFinding]
+    metadata: dict[str, Any]
+    overall_score: float | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "project_name": self.project_name,
+            "audit_type": self.audit_type,
+            "risk_matrix": [r.to_dict() for r in self.risk_matrix],
+            "findings": [f.to_dict() for f in self.findings],
+            "metadata": self.metadata,
+            "overall_score": self.overall_score,
+        }
+
+    def to_json(self, path: str) -> None:
+        Path(path).write_text(json.dumps(self.to_dict(), indent=2), encoding="utf-8")
+
+    def to_markdown(self, path: str) -> None:
+        from rai_audit.core.report import render_markdown
+
+        Path(path).write_text(render_markdown(self), encoding="utf-8")
+
+    def to_html(self, path: str) -> None:
+        from rai_audit.core.report import render_html
+
+        Path(path).write_text(render_html(self), encoding="utf-8")
+
+    @property
+    def critical_findings(self) -> list[AuditFinding]:
+        return [f for f in self.findings if f.severity == Severity.CRITICAL]
+
+    @property
+    def high_findings(self) -> list[AuditFinding]:
+        return [f for f in self.findings if f.severity == Severity.HIGH]
+
+    @property
+    def passed_findings(self) -> list[AuditFinding]:
+        return [f for f in self.findings if f.severity == Severity.PASSED]
+
+    @property
+    def overall_risk_level(self) -> RiskLevel:
+        for cat in self.risk_matrix:
+            if cat.risk_level == RiskLevel.CRITICAL:
+                return RiskLevel.CRITICAL
+        for cat in self.risk_matrix:
+            if cat.risk_level == RiskLevel.HIGH:
+                return RiskLevel.HIGH
+        for cat in self.risk_matrix:
+            if cat.risk_level == RiskLevel.MEDIUM:
+                return RiskLevel.MEDIUM
+        return RiskLevel.LOW

rai_audit_core-0.1.0/src/rai_audit/core/history.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+DEFAULT_HISTORY_DIR = Path(".rai-audit") / "history"
+
+
+def save_run(report_dict: dict, directory: Path | None = None) -> Path:
+    """Persist an audit run as a timestamped JSON file."""
+    directory = directory or DEFAULT_HISTORY_DIR
+    directory.mkdir(parents=True, exist_ok=True)
+    ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+    slug = report_dict.get("project_name", "audit").replace(" ", "_").lower()
+    path = directory / f"{slug}_{ts}.json"
+    path.write_text(json.dumps(report_dict, indent=2), encoding="utf-8")
+    return path
+
+
+def load_run(path: Path) -> dict:
+    """Load a persisted audit run."""
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def list_runs(directory: Path | None = None) -> list[Path]:
+    """List all persisted audit run files, newest first."""
+    directory = directory or DEFAULT_HISTORY_DIR
+    if not directory.exists():
+        return []
+    return sorted(directory.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)
+
+
+def diff_runs(path_a: Path, path_b: Path) -> dict:
+    """
+    Compare two audit runs and return a structured diff.
+    path_a is the older run, path_b is the newer run.
+    """
+    a = load_run(Path(path_a))
+    b = load_run(Path(path_b))
+
+    risk_a = {r["category"]: r["risk_level"] for r in a.get("risk_matrix", [])}
+    risk_b = {r["category"]: r["risk_level"] for r in b.get("risk_matrix", [])}
+
+    risk_order = {"critical": 3, "high": 2, "medium": 1, "low": 0}
+    risk_changes: list[dict] = []
+    all_cats = sorted(set(risk_a) | set(risk_b))
+    for cat in all_cats:
+        old = risk_a.get(cat, "n/a")
+        new = risk_b.get(cat, "n/a")
+        if old != new:
+            old_rank = risk_order.get(old, -1)
+            new_rank = risk_order.get(new, -1)
+            direction = "REGRESSION" if new_rank > old_rank else "IMPROVED"
+            risk_changes.append(
+                {"category": cat, "from": old, "to": new, "direction": direction}
+            )
+
+    ids_a = {f["check_id"] for f in a.get("findings", []) if f.get("severity") != "passed"}
+    ids_b = {f["check_id"] for f in b.get("findings", []) if f.get("severity") != "passed"}
+
+    new_findings = [
+        f for f in b.get("findings", [])
+        if f["check_id"] not in ids_a and f.get("severity") != "passed"
+    ]
+    resolved_findings = [
+        f for f in a.get("findings", [])
+        if f["check_id"] not in ids_b and f.get("severity") != "passed"
+    ]
+
+    return {
+        "project_name": b.get("project_name", "unknown"),
+        "run_a": str(path_a),
+        "run_b": str(path_b),
+        "risk_changes": risk_changes,
+        "new_findings": new_findings,
+        "resolved_findings": resolved_findings,
+        "summary": {
+            "regressions": sum(1 for c in risk_changes if c["direction"] == "REGRESSION"),
+            "improvements": sum(1 for c in risk_changes if c["direction"] == "IMPROVED"),
+            "new_finding_count": len(new_findings),
+            "resolved_finding_count": len(resolved_findings),
+        },
+    }
+
+
+def render_diff_text(diff: dict) -> str:
+    """Render a diff dict as a human-readable text report."""
+    lines: list[str] = []
+    lines.append(f"Audit Diff: {diff['project_name']}")
+    lines.append("─" * 60)
+
+    if diff["risk_changes"]:
+        for c in diff["risk_changes"]:
+            arrow = "⚠ REGRESSION" if c["direction"] == "REGRESSION" else "✓ IMPROVED"
+            lines.append(f"{c['category']:30s}  {c['from'].upper()} → {c['to'].upper()}    {arrow}")
+    else:
+        lines.append("No risk level changes.")
+
+    if diff["new_findings"]:
+        lines.append("\nNew findings:")
+        for f in diff["new_findings"]:
+            lines.append(f"  [{f['severity'].upper()}] {f['check_id']}: {f['title']}")
+
+    if diff["resolved_findings"]:
+        lines.append("\nResolved findings:")
+        for f in diff["resolved_findings"]:
+            lines.append(f"  ✓ {f['check_id']}: {f['title']}")
+
+    s = diff["summary"]
+    lines.append(
+        f"\nSummary: {s['regressions']} regression(s), {s['improvements']} improvement(s), "
+        f"{s['new_finding_count']} new, {s['resolved_finding_count']} resolved."
+    )
+    return "\n".join(lines)