feat: harden public OpenAI API contracts

backend/scripts/export_contracts.py

@@ -0,0 +1,51 @@
+"""Generate deterministic public API contract snapshots.
+
+Run from the repository root with:
+
+    make contract-snapshots
+
+The files are reviewed and committed like source code. Tests fail when runtime
+schemas drift from these snapshots.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from app import app
+from services.openai_realtime.schemas import (
+    realtime_client_event_json_schema,
+    realtime_server_event_json_schema,
+)
+
+
+CONTRACT_DIRECTORY = Path(__file__).resolve().parents[1] / "contracts"
+
+
+def contract_documents() -> dict[str, dict]:
+    return {
+        "openapi.json": app.openapi(),
+        "openai-realtime-client-events.schema.json": (
+            realtime_client_event_json_schema()
+        ),
+        "openai-realtime-server-events.schema.json": (
+            realtime_server_event_json_schema()
+        ),
+    }
+
+
+def main() -> None:
+    CONTRACT_DIRECTORY.mkdir(parents=True, exist_ok=True)
+    for name, document in contract_documents().items():
+        destination = CONTRACT_DIRECTORY / name
+        destination.write_text(
+            json.dumps(document, ensure_ascii=False, indent=2, sort_keys=True)
+            + "\n",
+            encoding="utf-8",
+        )
+        print(destination.relative_to(CONTRACT_DIRECTORY.parent))
+
+
+if __name__ == "__main__":
+    main()

backend/scripts/run_tests.py

@@ -0,0 +1,18 @@
+"""Run the backend suite with all local-runtime prerequisites configured."""
+
+from __future__ import annotations
+
+import os
+import unittest
+
+
+def main() -> None:
+    # Must be set before test discovery imports Pipecat and NLTK.
+    os.environ.setdefault("NLTK_DISABLE_IMPORT_SECURITY", "1")
+    suite = unittest.defaultTestLoader.discover("tests")
+    result = unittest.TextTestRunner(verbosity=1).run(suite)
+    raise SystemExit(0 if result.wasSuccessful() else 1)
+
+
+if __name__ == "__main__":
+    main()