humane-proxy 0.2.3__tar.gz → 0.3.0__tar.gz

{humane_proxy-0.2.3 → humane_proxy-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: humane-proxy
-Version: 0.2.3
+Version: 0.3.0
 Summary: Lightweight, plug-and-play AI safety middleware that protects humans.
 Author-email: Vishisht Mishra <Vishisht16@users.noreply.github.com>
 License: Apache-2.0
@@ -40,8 +40,19 @@ Requires-Dist: humane-proxy[mcp]; extra == "langchain"
 Requires-Dist: langchain-mcp-adapters>=0.1.0; extra == "langchain"
 Provides-Extra: webhooks
 Requires-Dist: httpx>=0.24.0; extra == "webhooks"
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == "redis"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
+Requires-Dist: psycopg_pool>=3.1; extra == "postgres"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10; extra == "llamaindex"
+Provides-Extra: crewai
+Requires-Dist: crewai[tools]>=0.80; extra == "crewai"
+Provides-Extra: autogen
+Requires-Dist: autogen-agentchat>=0.4; extra == "autogen"
 Provides-Extra: all
-Requires-Dist: humane-proxy[langchain,mcp,ml]; extra == "all"
+Requires-Dist: humane-proxy[autogen,crewai,langchain,llamaindex,mcp,ml,postgres,redis]; extra == "all"
 Dynamic: license-file
 
 # 🛡️ HumaneProxy
@@ -56,8 +67,8 @@ HumaneProxy sits between your users and any LLM. When someone expresses self-har
 [![Python](https://img.shields.io/pypi/pyversions/humane-proxy.svg)](https://pypi.org/project/humane-proxy/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Tests](https://github.com/Vishisht16/Humane-Proxy/actions/workflows/tests.yaml/badge.svg)](https://github.com/Vishisht16/Humane-Proxy/actions/workflows/tests.yaml)
-[![Humane-Proxy MCP server](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy/badges/card.svg)](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy)
 [![Humane-Proxy MCP server](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy/badges/score.svg)](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy)
+[![Humane-Proxy MCP server](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy/badges/card.svg)](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy)
 
 ---
 
@@ -234,6 +245,10 @@ HumaneProxy returns an empathetic message with crisis resources for 10+ countrie
 safety:
   categories:
     self_harm:
+      # Self-harm escalation threshold (0.0 to 1.0).
+      # Scores below this are downgraded to safe.
+      escalate_threshold: 0.5
+
       response_mode: "block"     # default
 
       # Optional: override the built-in message
@@ -284,6 +299,10 @@ escalation:
       to:
         - "safety-team@yourorg.com"
         - "oncall@yourorg.com"
+
+# Swappable Storage Backend (sqlite config default, redis/postgres optional)
+storage:
+  backend: "sqlite"  # or "redis", "postgres"
 ```
 
 ---
@@ -333,10 +352,13 @@ curl -X DELETE http://localhost:8000/admin/sessions/user-42 \
 
 | Endpoint | Description |
 |---|---|
-| `GET /admin/escalations` | Paginated list, filterable by `category`, `session_id` |
+| `GET /admin/health` | Health check (no auth required) |
+| `GET /admin/config` | Active config view (secrets redacted) |
+| `GET /admin/escalations` | Paginated list, filterable by `category`, `session_id`, `date`, sortable |
+| `GET /admin/escalations/export` | CSV export of escalations |
 | `GET /admin/escalations/{id}` | Single escalation detail |
 | `GET /admin/sessions/{id}/risk` | Session history + trajectory |
-| `GET /admin/stats` | Aggregate counts by category and day |
+| `GET /admin/stats` | Aggregate counts, top sessions, hourly breakdown |
 | `DELETE /admin/sessions/{id}` | Delete all session records |
 
 ---
@@ -361,10 +383,38 @@ Available on the [Official MCP Registry](https://registry.modelcontextprotocol.i
 
 ---
 
-## LangChain Integration
+## AI Agent Integrations
+
+HumaneProxy tools can be natively plugged into standard agentic frameworks:
+
+### LlamaIndex
+```bash
+pip install humane-proxy[llamaindex]
+```
+```python
+from humane_proxy.integrations.llamaindex import get_safety_tools
+tools = get_safety_tools() # Native FunctionTool instances
+```
 
-Plug HumaneProxy safety tools into any LangChain or LangGraph agent:
+### CrewAI
+```bash
+pip install humane-proxy[crewai]
+```
+```python
+from humane_proxy.integrations.crewai import get_safety_tools
+tools = get_safety_tools() # Native BaseTool subclass instances
+```
+
+### AutoGen (AG2)
+```bash
+pip install humane-proxy[autogen]
+```
+```python
+from humane_proxy.integrations.autogen import register_safety_tools
+register_safety_tools(assistant, user_proxy)
+```
 
+### LangChain
 ```bash
 pip install humane-proxy[langchain]
 ```
@@ -390,15 +440,17 @@ All values can be set in `humane_proxy.yaml` (project root) or via `HUMANE_PROXY
 | YAML key | Env var | Default | Description |
 |---|---|---|---|
 | `safety.risk_threshold` | `HUMANE_PROXY_RISK_THRESHOLD` | `0.7` | Score threshold for criminal_intent escalation |
-| `safety.spike_boost` | — | `0.25` | Score boost on trajectory spike |
+| `safety.categories.self_harm.escalate_threshold` | `HUMANE_PROXY_SELF_HARM_THRESHOLD` | `0.5` | Score threshold for self_harm escalation |
+| `safety.spike_boost` | `HUMANE_PROXY_SPIKE_BOOST` | `0.25` | Score boost on trajectory spike |
 | `server.port` | `HUMANE_PROXY_PORT` | `8000` | Proxy port |
-| `pipeline.enabled_stages` | `HUMANE_PROXY_ENABLED_STAGES` | `[1]` | Active stages |
+| `pipeline.enabled_stages` | `HUMANE_PROXY_ENABLED_STAGES` | `[1]` | Active stages (e.g. `1,2,3`) |
 | `pipeline.stage1_ceiling` | `HUMANE_PROXY_STAGE1_CEILING` | `0.3` | Early exit after Stage 1 |
 | `pipeline.stage2_ceiling` | `HUMANE_PROXY_STAGE2_CEILING` | `0.4` | Early exit after Stage 2 |
 | `stage3.provider` | `HUMANE_PROXY_STAGE3_PROVIDER` | `"auto"` | Stage 3 provider |
 | `stage3.timeout` | `HUMANE_PROXY_STAGE3_TIMEOUT` | `10` | Stage 3 timeout (s) |
 | `privacy.store_message_text` | — | `false` | Store raw text (vs SHA-256 hash) |
-| `escalation.rate_limit_max` | — | `3` | Max alerts per session/window |
+| `escalation.rate_limit_max` | `HUMANE_PROXY_RATE_LIMIT_MAX` | `3` | Max alerts per session/window |
+| `storage.backend` | `HUMANE_PROXY_STORAGE_BACKEND` | `"sqlite"` | `"sqlite"`, `"redis"`, `"postgres"` |
 | `safety.categories.self_harm.response_mode` | — | `"block"` | `"block"` or `"forward"` |
 
 ---
@@ -428,11 +480,16 @@ privacy:
 
 | Extra | Command | What it adds |
 |---|---|---|
-| *(none)* | `pip install humane-proxy` | Stage 1 heuristics + full API + CLI |
+| *(none)* | `pip install humane-proxy` | Stage 1 heuristics + default SQLite storage |
 | `ml` | `pip install humane-proxy[ml]` | Stage 2 semantic embeddings (`sentence-transformers`) |
 | `mcp` | `pip install humane-proxy[mcp]` | MCP server for AI agent integration (`fastmcp`) |
+| `redis` | `pip install humane-proxy[redis]` | Redis storage backend (`redis`) |
+| `postgres` | `pip install humane-proxy[postgres]` | PostgreSQL storage backend (`psycopg`, `psycopg_pool`) |
+| `llamaindex` | `pip install humane-proxy[llamaindex]` | LlamaIndex native integration (`llama-index-core`) |
+| `crewai` | `pip install humane-proxy[crewai]` | CrewAI native integration (`crewai[tools]`) |
+| `autogen` | `pip install humane-proxy[autogen]` | AutoGen native integration (`autogen-agentchat`) |
 | `langchain` | `pip install humane-proxy[langchain]` | LangChain adapter (MCP + `langchain-mcp-adapters`) |
-| `all` | `pip install humane-proxy[all]` | Everything above |
+| `all` | `pip install humane-proxy[all]` | Includes ALL optional dependencies above |
 
 ---
 

humane_proxy-0.2.3/humane_proxy.egg-info/PKG-INFO → humane_proxy-0.3.0/README.md

@@ -1,49 +1,3 @@
-Metadata-Version: 2.4
-Name: humane-proxy
-Version: 0.2.3
-Summary: Lightweight, plug-and-play AI safety middleware that protects humans.
-Author-email: Vishisht Mishra <Vishisht16@users.noreply.github.com>
-License: Apache-2.0
-Project-URL: Homepage, https://github.com/Vishisht16/Humane-Proxy
-Project-URL: Repository, https://github.com/Vishisht16/Humane-Proxy
-Project-URL: Issues, https://github.com/Vishisht16/Humane-Proxy/issues
-Keywords: ai-safety,llm,middleware,guardrails,human-safety
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software 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
-Classifier: Topic :: Security
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-License-File: NOTICE
-Requires-Dist: fastapi>=0.100.0
-Requires-Dist: httpx>=0.24.0
-Requires-Dist: numpy>=1.24.0
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: uvicorn>=0.22.0
-Requires-Dist: click>=8.0
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
-Requires-Dist: httpx; extra == "dev"
-Provides-Extra: ml
-Requires-Dist: sentence-transformers>=2.2.0; extra == "ml"
-Provides-Extra: mcp
-Requires-Dist: fastmcp>=0.4.0; extra == "mcp"
-Provides-Extra: langchain
-Requires-Dist: humane-proxy[mcp]; extra == "langchain"
-Requires-Dist: langchain-mcp-adapters>=0.1.0; extra == "langchain"
-Provides-Extra: webhooks
-Requires-Dist: httpx>=0.24.0; extra == "webhooks"
-Provides-Extra: all
-Requires-Dist: humane-proxy[langchain,mcp,ml]; extra == "all"
-Dynamic: license-file
-
 # 🛡️ HumaneProxy
 
 <!-- mcp-name: io.github.Vishisht16/humane-proxy -->
@@ -56,8 +10,8 @@ HumaneProxy sits between your users and any LLM. When someone expresses self-har
 [![Python](https://img.shields.io/pypi/pyversions/humane-proxy.svg)](https://pypi.org/project/humane-proxy/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Tests](https://github.com/Vishisht16/Humane-Proxy/actions/workflows/tests.yaml/badge.svg)](https://github.com/Vishisht16/Humane-Proxy/actions/workflows/tests.yaml)
-[![Humane-Proxy MCP server](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy/badges/card.svg)](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy)
 [![Humane-Proxy MCP server](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy/badges/score.svg)](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy)
+[![Humane-Proxy MCP server](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy/badges/card.svg)](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy)
 
 ---
 
@@ -234,6 +188,10 @@ HumaneProxy returns an empathetic message with crisis resources for 10+ countrie
 safety:
   categories:
     self_harm:
+      # Self-harm escalation threshold (0.0 to 1.0).
+      # Scores below this are downgraded to safe.
+      escalate_threshold: 0.5
+
       response_mode: "block"     # default
 
       # Optional: override the built-in message
@@ -284,6 +242,10 @@ escalation:
       to:
         - "safety-team@yourorg.com"
         - "oncall@yourorg.com"
+
+# Swappable Storage Backend (sqlite config default, redis/postgres optional)
+storage:
+  backend: "sqlite"  # or "redis", "postgres"
 ```
 
 ---
@@ -333,10 +295,13 @@ curl -X DELETE http://localhost:8000/admin/sessions/user-42 \
 
 | Endpoint | Description |
 |---|---|
-| `GET /admin/escalations` | Paginated list, filterable by `category`, `session_id` |
+| `GET /admin/health` | Health check (no auth required) |
+| `GET /admin/config` | Active config view (secrets redacted) |
+| `GET /admin/escalations` | Paginated list, filterable by `category`, `session_id`, `date`, sortable |
+| `GET /admin/escalations/export` | CSV export of escalations |
 | `GET /admin/escalations/{id}` | Single escalation detail |
 | `GET /admin/sessions/{id}/risk` | Session history + trajectory |
-| `GET /admin/stats` | Aggregate counts by category and day |
+| `GET /admin/stats` | Aggregate counts, top sessions, hourly breakdown |
 | `DELETE /admin/sessions/{id}` | Delete all session records |
 
 ---
@@ -361,10 +326,38 @@ Available on the [Official MCP Registry](https://registry.modelcontextprotocol.i
 
 ---
 
-## LangChain Integration
+## AI Agent Integrations
+
+HumaneProxy tools can be natively plugged into standard agentic frameworks:
+
+### LlamaIndex
+```bash
+pip install humane-proxy[llamaindex]
+```
+```python
+from humane_proxy.integrations.llamaindex import get_safety_tools
+tools = get_safety_tools() # Native FunctionTool instances
+```
+
+### CrewAI
+```bash
+pip install humane-proxy[crewai]
+```
+```python
+from humane_proxy.integrations.crewai import get_safety_tools
+tools = get_safety_tools() # Native BaseTool subclass instances
+```
 
-Plug HumaneProxy safety tools into any LangChain or LangGraph agent:
+### AutoGen (AG2)
+```bash
+pip install humane-proxy[autogen]
+```
+```python
+from humane_proxy.integrations.autogen import register_safety_tools
+register_safety_tools(assistant, user_proxy)
+```
 
+### LangChain
 ```bash
 pip install humane-proxy[langchain]
 ```
@@ -390,15 +383,17 @@ All values can be set in `humane_proxy.yaml` (project root) or via `HUMANE_PROXY
 | YAML key | Env var | Default | Description |
 |---|---|---|---|
 | `safety.risk_threshold` | `HUMANE_PROXY_RISK_THRESHOLD` | `0.7` | Score threshold for criminal_intent escalation |
-| `safety.spike_boost` | — | `0.25` | Score boost on trajectory spike |
+| `safety.categories.self_harm.escalate_threshold` | `HUMANE_PROXY_SELF_HARM_THRESHOLD` | `0.5` | Score threshold for self_harm escalation |
+| `safety.spike_boost` | `HUMANE_PROXY_SPIKE_BOOST` | `0.25` | Score boost on trajectory spike |
 | `server.port` | `HUMANE_PROXY_PORT` | `8000` | Proxy port |
-| `pipeline.enabled_stages` | `HUMANE_PROXY_ENABLED_STAGES` | `[1]` | Active stages |
+| `pipeline.enabled_stages` | `HUMANE_PROXY_ENABLED_STAGES` | `[1]` | Active stages (e.g. `1,2,3`) |
 | `pipeline.stage1_ceiling` | `HUMANE_PROXY_STAGE1_CEILING` | `0.3` | Early exit after Stage 1 |
 | `pipeline.stage2_ceiling` | `HUMANE_PROXY_STAGE2_CEILING` | `0.4` | Early exit after Stage 2 |
 | `stage3.provider` | `HUMANE_PROXY_STAGE3_PROVIDER` | `"auto"` | Stage 3 provider |
 | `stage3.timeout` | `HUMANE_PROXY_STAGE3_TIMEOUT` | `10` | Stage 3 timeout (s) |
 | `privacy.store_message_text` | — | `false` | Store raw text (vs SHA-256 hash) |
-| `escalation.rate_limit_max` | — | `3` | Max alerts per session/window |
+| `escalation.rate_limit_max` | `HUMANE_PROXY_RATE_LIMIT_MAX` | `3` | Max alerts per session/window |
+| `storage.backend` | `HUMANE_PROXY_STORAGE_BACKEND` | `"sqlite"` | `"sqlite"`, `"redis"`, `"postgres"` |
 | `safety.categories.self_harm.response_mode` | — | `"block"` | `"block"` or `"forward"` |
 
 ---
@@ -428,11 +423,16 @@ privacy:
 
 | Extra | Command | What it adds |
 |---|---|---|
-| *(none)* | `pip install humane-proxy` | Stage 1 heuristics + full API + CLI |
+| *(none)* | `pip install humane-proxy` | Stage 1 heuristics + default SQLite storage |
 | `ml` | `pip install humane-proxy[ml]` | Stage 2 semantic embeddings (`sentence-transformers`) |
 | `mcp` | `pip install humane-proxy[mcp]` | MCP server for AI agent integration (`fastmcp`) |
+| `redis` | `pip install humane-proxy[redis]` | Redis storage backend (`redis`) |
+| `postgres` | `pip install humane-proxy[postgres]` | PostgreSQL storage backend (`psycopg`, `psycopg_pool`) |
+| `llamaindex` | `pip install humane-proxy[llamaindex]` | LlamaIndex native integration (`llama-index-core`) |
+| `crewai` | `pip install humane-proxy[crewai]` | CrewAI native integration (`crewai[tools]`) |
+| `autogen` | `pip install humane-proxy[autogen]` | AutoGen native integration (`autogen-agentchat`) |
 | `langchain` | `pip install humane-proxy[langchain]` | LangChain adapter (MCP + `langchain-mcp-adapters`) |
-| `all` | `pip install humane-proxy[all]` | Everything above |
+| `all` | `pip install humane-proxy[all]` | Includes ALL optional dependencies above |
 
 ---
 

{humane_proxy-0.2.3 → humane_proxy-0.3.0}/humane_proxy/__init__.py

@@ -16,7 +16,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.2.3"
+__version__ = "0.3.0"
 
 # ---------------------------------------------------------------------------
 # Legacy API — keep backward compatibility with existing modules that call

{humane_proxy-0.2.3 → humane_proxy-0.3.0}/humane_proxy/api/admin.py

@@ -6,7 +6,10 @@ Authentication: Bearer token from ``HUMANE_PROXY_ADMIN_KEY`` env var.
 If not set, admin API is disabled (all requests → 403).
 
 Endpoints:
+  GET  /admin/health               — health check (no auth)
+  GET  /admin/config               — active configuration (sanitised)
   GET  /admin/escalations          — paginated, filterable list
+  GET  /admin/escalations/export   — CSV export
   GET  /admin/escalations/{id}     — single record
   GET  /admin/sessions/{id}/risk   — per-session trajectory
   GET  /admin/stats                — aggregate counts
@@ -15,14 +18,18 @@ Endpoints:
 
 from __future__ import annotations
 
+import csv
+import io
 import json
 import logging
 import os
 import sqlite3
+import time
 from datetime import datetime, timezone
 from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi.responses import StreamingResponse
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 
 from humane_proxy.escalation.local_db import _get_db_path
@@ -33,6 +40,8 @@ router = APIRouter(prefix="/admin", tags=["admin"])
 
 _security = HTTPBearer(auto_error=False)
 
+_start_time = time.monotonic()
+
 
 # ---------------------------------------------------------------------------
 # Auth dependency
@@ -81,6 +90,67 @@ def _get_conn() -> sqlite3.Connection:
     return sqlite3.connect(_get_db_path(), check_same_thread=False)
 
 
+# ---------------------------------------------------------------------------
+# Health check (no auth required)
+# ---------------------------------------------------------------------------
+
+@router.get("/health")
+def health_check() -> dict:
+    """Health check — uptime, version, active stages, backend."""
+    from humane_proxy import __version__
+    from humane_proxy.config import get_config
+
+    config = get_config()
+    return {
+        "status": "healthy",
+        "version": __version__,
+        "uptime_seconds": round(time.monotonic() - _start_time, 1),
+        "enabled_stages": config.get("pipeline", {}).get("enabled_stages", [1]),
+        "storage_backend": config.get("storage", {}).get("backend", "sqlite"),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Config view (secrets redacted)
+# ---------------------------------------------------------------------------
+
+@router.get("/config")
+def get_active_config(_: str = Depends(_require_admin)) -> dict:
+    """Return the active merged config with secrets redacted."""
+    import copy
+    from humane_proxy.config import get_config
+
+    config = copy.deepcopy(get_config())
+
+    # Redact sensitive values.
+    _REDACT_PATHS = [
+        ("admin", "api_key"),
+        ("escalation", "webhooks", "slack_url"),
+        ("escalation", "webhooks", "discord_url"),
+        ("escalation", "webhooks", "pagerduty_routing_key"),
+        ("escalation", "webhooks", "teams_url"),
+        ("storage", "redis", "url"),
+        ("storage", "postgres", "dsn"),
+    ]
+    for path in _REDACT_PATHS:
+        node = config
+        for part in path[:-1]:
+            node = node.get(part, {})
+            if not isinstance(node, dict):
+                break
+        else:
+            key = path[-1]
+            if key in node and node[key]:
+                node[key] = "***REDACTED***"
+
+    # Redact email password.
+    email_cfg = config.get("escalation", {}).get("webhooks", {}).get("email", {})
+    if isinstance(email_cfg, dict) and email_cfg.get("password"):
+        email_cfg["password"] = "***REDACTED***"
+
+    return config
+
+
 # ---------------------------------------------------------------------------
 # Routes
 # ---------------------------------------------------------------------------
@@ -89,6 +159,10 @@ def _get_conn() -> sqlite3.Connection:
 def list_escalations(
     category: str | None = Query(None, description="Filter by category"),
     session_id: str | None = Query(None, description="Filter by session ID"),
+    date_from: str | None = Query(None, description="Start date (ISO format, e.g. 2026-01-01)"),
+    date_to: str | None = Query(None, description="End date (ISO format, e.g. 2026-12-31)"),
+    sort_by: str = Query("timestamp", description="Sort field: timestamp, risk_score, category"),
+    sort_order: str = Query("desc", description="Sort order: asc or desc"),
     limit: int = Query(50, ge=1, le=500),
     offset: int = Query(0, ge=0),
     _: str = Depends(_require_admin),
@@ -103,13 +177,31 @@ def list_escalations(
     if session_id:
         clauses.append("session_id = ?")
         params.append(session_id)
+    if date_from:
+        try:
+            dt = datetime.fromisoformat(date_from).replace(tzinfo=timezone.utc)
+            clauses.append("timestamp >= ?")
+            params.append(dt.timestamp())
+        except ValueError:
+            raise HTTPException(400, f"Invalid date_from format: {date_from}")
+    if date_to:
+        try:
+            dt = datetime.fromisoformat(date_to).replace(tzinfo=timezone.utc)
+            clauses.append("timestamp <= ?")
+            params.append(dt.timestamp())
+        except ValueError:
+            raise HTTPException(400, f"Invalid date_to format: {date_to}")
 
     where = ("WHERE " + " AND ".join(clauses)) if clauses else ""
 
+    allowed_sort = {"timestamp", "risk_score", "category", "session_id", "stage_reached"}
+    sort_col = sort_by if sort_by in allowed_sort else "timestamp"
+    sort_dir = "ASC" if sort_order.lower() == "asc" else "DESC"
+
     conn = _get_conn()
     try:
         rows = conn.execute(
-            f"SELECT * FROM escalations {where} ORDER BY timestamp DESC LIMIT ? OFFSET ?",
+            f"SELECT * FROM escalations {where} ORDER BY {sort_col} {sort_dir} LIMIT ? OFFSET ?",
             params + [limit, offset],
         ).fetchall()
         total = conn.execute(
@@ -126,6 +218,52 @@ def list_escalations(
     }
 
 
+# ---------------------------------------------------------------------------
+# CSV Export
+# ---------------------------------------------------------------------------
+
+@router.get("/escalations/export")
+def export_escalations(
+    category: str | None = Query(None),
+    session_id: str | None = Query(None),
+    _: str = Depends(_require_admin),
+) -> StreamingResponse:
+    """Export all matching escalations as CSV."""
+    clauses: list[str] = []
+    params: list[Any] = []
+
+    if category:
+        clauses.append("category = ?")
+        params.append(category)
+    if session_id:
+        clauses.append("session_id = ?")
+        params.append(session_id)
+
+    where = ("WHERE " + " AND ".join(clauses)) if clauses else ""
+
+    conn = _get_conn()
+    try:
+        rows = conn.execute(
+            f"SELECT * FROM escalations {where} ORDER BY timestamp DESC",
+            params,
+        ).fetchall()
+    finally:
+        conn.close()
+
+    output = io.StringIO()
+    writer = csv.writer(output)
+    writer.writerow(_COLS)
+    for row in rows:
+        writer.writerow(row)
+
+    output.seek(0)
+    return StreamingResponse(
+        iter([output.getvalue()]),
+        media_type="text/csv",
+        headers={"Content-Disposition": "attachment; filename=escalations.csv"},
+    )
+
+
 @router.get("/escalations/{escalation_id}")
 def get_escalation(
     escalation_id: int,
@@ -191,7 +329,7 @@ def get_session_risk(
 
 @router.get("/stats")
 def get_stats(_: str = Depends(_require_admin)) -> dict:
-    """Return aggregate safety statistics."""
+    """Return aggregate safety statistics with enhanced breakdowns."""
     conn = _get_conn()
     try:
         total = conn.execute("SELECT COUNT(*) FROM escalations").fetchone()[0]
@@ -205,6 +343,26 @@ def get_stats(_: str = Depends(_require_admin)) -> dict:
         avg_score = conn.execute(
             "SELECT AVG(risk_score) FROM escalations"
         ).fetchone()[0]
+
+        # Enhanced: top sessions (most flagged).
+        top_sessions = conn.execute(
+            """SELECT session_id, COUNT(*) as cnt, AVG(risk_score) as avg_score
+               FROM escalations GROUP BY session_id ORDER BY cnt DESC LIMIT 10"""
+        ).fetchall()
+
+        # Enhanced: stage distribution.
+        by_stage = conn.execute(
+            "SELECT stage_reached, COUNT(*) FROM escalations GROUP BY stage_reached"
+        ).fetchall()
+
+        # Enhanced: hourly breakdown (last 24h).
+        cutoff_24h = (datetime.now(timezone.utc).timestamp()) - 86400
+        hourly = conn.execute(
+            """SELECT strftime('%H', timestamp, 'unixepoch') as hour, COUNT(*)
+               FROM escalations WHERE timestamp >= ?
+               GROUP BY hour ORDER BY hour""",
+            (cutoff_24h,),
+        ).fetchall()
     finally:
         conn.close()
 
@@ -213,6 +371,12 @@ def get_stats(_: str = Depends(_require_admin)) -> dict:
         "by_category": dict(by_category),
         "by_day": dict(by_day),
         "average_risk_score": round(avg_score or 0.0, 3),
+        "top_sessions": [
+            {"session_id": s, "count": c, "avg_score": round(a or 0, 3)}
+            for s, c, a in top_sessions
+        ],
+        "by_stage": dict(by_stage),
+        "hourly_last_24h": dict(hourly),
         "generated_at": datetime.now(timezone.utc).isoformat(),
     }