Create reports/explainability.py

reports/explainability.py

@@ -1,14 +1,56 @@
-def explainability_report(results):
-    agencies = {r["agency"] for r in results}
-    return f"""
-### Explainability Report
+"""
+Explainability Report
+Federal FOIA Intelligence Search
+Public Electronic Reading Rooms Only
+"""
 
-**Purpose:** Public FOIA discovery  
-**Agencies:** {', '.join(agencies)}  
+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.
 
-Safeguards:
+The platform does not bypass access controls, does not scrape restricted
+systems, and does not declassify information.
+"""
+
+
+DATA_SOURCES_EXPLANATION = """
+All indexed materials originate from agency-operated FOIA Electronic
+Reading Rooms. Each result includes explicit source attribution.
+
+No content is modified, inferred, or enhanced beyond the released record.
+"""
+
+
+SAFETY_CONTROLS = """
+Safety mechanisms include:
 - Robots.txt enforcement
-- Kill switches
-- Redaction detection
-- FOIA exemption surfacing
-"""
+- 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,
+    ])