Create reports/explainability.py

reports/explainability.py

@@ -1,56 +1,51 @@
 """
-Explainability Report
+Regulator-Facing Explainability Report
 Federal FOIA Intelligence Search
 Public Electronic Reading Rooms Only
 """
 
-EXPLAINABILITY_SUMMARY = """
-Federal FOIA Intelligence Search is a public-interest discovery system
-that indexes only documents already released by U.S. Government agencies
-in FOIA Electronic Reading Rooms.
+from datetime import datetime
 
-The platform does not bypass access controls, does not scrape restricted
-systems, and does not declassify information.
-"""
 
+def generate_report(stats: dict) -> str:
+    return f"""
+Federal FOIA Intelligence Search
+Explainability Report
 
-DATA_SOURCES_EXPLANATION = """
-All indexed materials originate from agency-operated FOIA Electronic
-Reading Rooms. Each result includes explicit source attribution.
+Generated: {datetime.utcnow().isoformat()} UTC
 
-No content is modified, inferred, or enhanced beyond the released record.
-"""
+Scope
+-----
+This system indexes only documents already released to the public
+via U.S. Government FOIA Electronic Reading Rooms.
 
+Data Sources
+------------
+- Agency-managed FOIA portals
+- Public PDFs and HTML disclosures
+- No internal or restricted systems
 
-SAFETY_CONTROLS = """
-Safety mechanisms include:
+Safeguards
+----------
 - Robots.txt enforcement
-- Per-agency automated kill switches
-- Health and latency monitoring
-- Redaction-aware previews
-- Clear labeling of stub vs live sources
-"""
-
-
-INTENDED_USE = """
-This system is intended for:
-- Journalists
-- Academic researchers
-- Legal professionals
-- Members of the public conducting FOIA research
-
-It is not intended for operational intelligence use or surveillance.
-"""
-
-
-def generate_explainability_report() -> str:
-    """
-    Return a consolidated explainability narrative suitable for
-    regulators, reviewers, or Trust & Safety teams.
-    """
-    return "\n\n".join([
-        EXPLAINABILITY_SUMMARY,
-        DATA_SOURCES_EXPLANATION,
-        SAFETY_CONTROLS,
-        INTENDED_USE,
-    ])
+- Per-agency kill switches
+- Adapter compliance testing
+- No authentication bypass
+- No scraping beyond published endpoints
+
+Analytics
+---------
+- Keyword-based retrieval
+- Optional semantic clustering (FAISS)
+- No predictive inference
+- No content alteration
+
+Results Summary
+---------------
+Total Documents: {stats.get('total_docs', 'N/A')}
+Agencies Covered: {len(stats.get('agencies', []))}
+
+Compliance Statement
+--------------------
+This system complies with FOIA, CFAA, and platform terms by design.
+"""