Create sovereign_role_scope_report.py

sovereign_role_scope_report.py

@@ -0,0 +1,254 @@
+# sovereign_role_scope_report.py
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from sovereign_role_scope_profile import generate_role_scope_profile
+
+
+ROLE_SCOPE_OUTPUT_DIR = "sovereign_role_scope_outputs"
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _ensure_dir(path: str) -> None:
+    os.makedirs(path, exist_ok=True)
+
+
+def _safe(v: Any, default: Any = "") -> Any:
+    return v if v is not None else default
+
+
+def _bool_text(v: Any) -> str:
+    return "True" if bool(v) else "False"
+
+
+def _render_header(bundle: Dict[str, Any]) -> str:
+    profile = bundle.get("role_scope_profile", {}) if isinstance(bundle, dict) else {}
+
+    return f"""# Sovereign Role / Scope Report
+
+Generated at: {_safe((profile or {}).get("generated_at"), _utc_now())}
+
+## 1. Profile Identity
+- Profile Type: {_safe(profile.get("profile_type"), "Sovereign Role Scope Profile")}
+- Domain: {_safe(profile.get("domain"), "banking_and_financial_institutions")}
+"""
+
+
+def _render_summary(bundle: Dict[str, Any]) -> str:
+    profile = bundle.get("role_scope_profile", {}) if isinstance(bundle, dict) else {}
+    summary = profile.get("summary", {}) if isinstance(profile, dict) else {}
+
+    return f"""## 2. Executive Summary
+- Total Roles: {_safe(summary.get("total_roles"), 0)}
+- High Sensitivity Roles: {_safe(summary.get("high_sensitivity_roles"), 0)}
+- Dual-Control Roles: {_safe(summary.get("dual_control_roles"), 0)}
+- Read-Only Roles: {_safe(summary.get("read_only_roles"), 0)}
+
+### Practical Interpretation
+- Sovereign defines bounded AI role profiles rather than unbounded generic AI authority.
+- High-risk banking roles are intentionally constrained with stronger review posture.
+- Some roles are read-only by design and must remain non-mutating.
+- Dual control is explicitly expected for sensitive execution-facing domains.
+"""
+
+
+def _render_roles(bundle: Dict[str, Any]) -> str:
+    profile = bundle.get("role_scope_profile", {}) if isinstance(bundle, dict) else {}
+    roles = profile.get("roles", []) if isinstance(profile, dict) else []
+
+    lines: List[str] = ["## 3. Role Inventory"]
+
+    if not roles:
+        lines.append("- No roles recorded.")
+        return "\n".join(lines)
+
+    for item in roles:
+        allowed = item.get("allowed_actions", []) if isinstance(item, dict) else []
+        forbidden = item.get("forbidden_actions", []) if isinstance(item, dict) else []
+        scope = item.get("data_access_scope", []) if isinstance(item, dict) else []
+
+        lines.append(f"### {item.get('role', 'unknown_role')}")
+        lines.append(f"- Status: {_safe(item.get('status'))}")
+        lines.append(f"- Business Domain: {_safe(item.get('business_domain'))}")
+        lines.append(f"- Sensitivity Boundary: {_safe(item.get('sensitivity_boundary'))}")
+        lines.append(f"- Review Expectation: {_safe(item.get('review_expectation'))}")
+        lines.append(f"- Dual Control Required: {_bool_text(item.get('dual_control_required'))}")
+
+        if allowed:
+            lines.append("- Allowed Actions:")
+            for x in allowed:
+                lines.append(f"  - {x}")
+
+        if forbidden:
+            lines.append("- Forbidden Actions:")
+            for x in forbidden:
+                lines.append(f"  - {x}")
+
+        if scope:
+            lines.append("- Data Access Scope:")
+            for x in scope:
+                lines.append(f"  - {x}")
+
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _render_principles(bundle: Dict[str, Any]) -> str:
+    profile = bundle.get("role_scope_profile", {}) if isinstance(bundle, dict) else {}
+    principles = profile.get("global_principles", []) if isinstance(profile, dict) else []
+
+    lines: List[str] = ["## 4. Global Role-Scope Principles"]
+
+    if not principles:
+        lines.append("- No global principles recorded.")
+        return "\n".join(lines)
+
+    for item in principles:
+        lines.append(f"### {item.get('principle', 'unknown_principle')}")
+        lines.append(f"- Status: {_safe(item.get('status'))}")
+        lines.append(f"- Description: {_safe(item.get('description'))}")
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _render_governance_interpretation(bundle: Dict[str, Any]) -> str:
+    profile = bundle.get("role_scope_profile", {}) if isinstance(bundle, dict) else {}
+    roles = profile.get("roles", []) if isinstance(profile, dict) else []
+
+    dual_control_roles = [r.get("role") for r in roles if bool(r.get("dual_control_required"))]
+    read_only_roles = [r.get("role") for r in roles if "read_only" in str(r.get("role", "")).lower()]
+
+    lines = ["## 5. Governance Interpretation"]
+
+    if dual_control_roles:
+        lines.append("- Roles Expecting Dual Control:")
+        for role in dual_control_roles:
+            lines.append(f"  - {role}")
+    else:
+        lines.append("- No dual-control roles recorded.")
+
+    if read_only_roles:
+        lines.append("- Read-Only Roles:")
+        for role in read_only_roles:
+            lines.append(f"  - {role}")
+    else:
+        lines.append("- No read-only roles recorded.")
+
+    lines.append("- High-risk banking execution domains should not silently inherit broad autonomous authority.")
+    lines.append("- Support, audit, and analysis roles should remain bound to their declared scope.")
+    lines.append("- Payment and treasury-like roles require proportional runtime control and review posture.")
+
+    return "\n".join(lines)
+
+
+def _render_artifact_status(bundle: Dict[str, Any]) -> str:
+    seal = bundle.get("crypto_seal", {}) if isinstance(bundle, dict) else {}
+
+    return f"""## 6. Artifact Status
+- Sealed: {bool(bundle.get("sealed", False))}
+- Seal Digest: {_safe(seal.get("seal_digest"), "")}
+- Seal Scheme: {_safe(seal.get("scheme"), "")}
+- Seal Algorithm: {_safe(seal.get("algorithm"), "")}
+- Signer Hint: {_safe(seal.get("signer_hint"), "")}
+"""
+
+
+def _render_verdict(bundle: Dict[str, Any]) -> str:
+    profile = bundle.get("role_scope_profile", {}) if isinstance(bundle, dict) else {}
+    notes = profile.get("notes", []) if isinstance(profile, dict) else []
+
+    verdict = (
+        "Sovereign currently expresses a bounded bank-grade role model: "
+        "AI roles are scoped by business function, high-risk roles are constrained, "
+        "and role support does not imply unbounded autonomous execution authority."
+    )
+
+    lines = [
+        "## 7. Preliminary Bank-Facing Verdict",
+        verdict,
+        "",
+        "## 8. Notes",
+    ]
+
+    if notes:
+        for item in notes:
+            lines.append(f"- {item}")
+    else:
+        lines.append("- No additional notes provided.")
+
+    return "\n".join(lines)
+
+
+def build_role_scope_markdown(bundle: Dict[str, Any]) -> str:
+    parts = [
+        _render_header(bundle),
+        _render_summary(bundle),
+        _render_roles(bundle),
+        _render_principles(bundle),
+        _render_governance_interpretation(bundle),
+        _render_artifact_status(bundle),
+        _render_verdict(bundle),
+    ]
+    return "\n\n".join(parts).strip() + "\n"
+
+
+def save_role_scope_report(
+    bundle: Dict[str, Any],
+    output_dir: str = ROLE_SCOPE_OUTPUT_DIR,
+    base_name: Optional[str] = None,
+) -> Dict[str, str]:
+    _ensure_dir(output_dir)
+
+    ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    base = base_name or f"sovereign_role_scope_report_{ts}"
+
+    json_path = os.path.join(output_dir, f"{base}.json")
+    md_path = os.path.join(output_dir, f"{base}.md")
+
+    with open(json_path, "w", encoding="utf-8") as f:
+        json.dump(bundle, f, ensure_ascii=False, indent=2)
+
+    markdown = build_role_scope_markdown(bundle)
+    with open(md_path, "w", encoding="utf-8") as f:
+        f.write(markdown)
+
+    return {
+        "json_report": json_path,
+        "markdown_report": md_path,
+    }
+
+
+def generate_role_scope_report(
+    output_dir: str = ROLE_SCOPE_OUTPUT_DIR,
+    base_name: Optional[str] = None,
+) -> Dict[str, Any]:
+    bundle = generate_role_scope_profile()
+
+    files = save_role_scope_report(
+        bundle=bundle,
+        output_dir=output_dir,
+        base_name=base_name,
+    )
+
+    return {
+        "ok": True,
+        "generated_at": _utc_now(),
+        "bundle": bundle,
+        "files": files,
+    }
+
+
+if __name__ == "__main__":
+    out = generate_role_scope_report()
+    print(json.dumps(out, indent=2, ensure_ascii=False))
+
+