Migrate admin rules and analytics to Supabase

README.md

@@ -31,7 +31,7 @@ This platform showcases how MCP can power intelligent, governed, multi-tenant AI
   - **Rule-Based Behavior Control**: Rules checked FIRST - brief response rules return quick answers, blocking rules prevent requests
   - **Comment Filtering**: Comment lines (starting with #) automatically ignored when uploading rules
   - **Supabase Integration**: Rules stored in Supabase for production scalability (with SQLite fallback)
-- 📊 **Comprehensive Analytics & Observability** – Full tenant-level analytics logging with SQLite backend:
+- 📊 **Comprehensive Analytics & Observability** – Full tenant-level analytics logging with Supabase backend (SQLite fallback for local dev):
   - Tool usage breakdown (RAG, Web, Admin, LLM) with latency and token tracking
   - RAG recall/precision indicators (average hits, scores, top scores)
   - Per-tenant query volume and active users
@@ -53,7 +53,7 @@ This platform showcases how MCP can power intelligent, governed, multi-tenant AI
 - 📈 **Real-Time Analytics Dashboard** – Per-tenant analytics with configurable time windows (7, 30, 90 days)
 - 🛠️ **Admin API Endpoints** – `/admin/violations`, `/admin/tools/logs`, `/admin/tenants` for comprehensive governance
 - 🧠 **Agent Debug & Planning** – `/agent/debug` and `/agent/plan` endpoints for observability and tool selection inspection
-- 💾 **Persistent Analytics Storage** – SQLite-based analytics store with indexes for fast queries
+- 💾 **Persistent Analytics Storage** – Supabase-backed analytics store (with automatic SQLite fallback) for fast, multi-tenant queries
 - 🗄️ **Supabase Integration** – Production-ready Supabase support for admin rules with automatic table creation
 
 ---

SUPABASE_MIGRATION_COMPLETE.md

@@ -0,0 +1,125 @@
+# Supabase Migration Complete ✅
+
+After running the migration, your data is now in Supabase. This document explains how to ensure **all future data** is saved to Supabase instead of SQLite.
+
+## ✅ What's Already Configured
+
+Both `RulesStore` and `AnalyticsStore` automatically detect and use Supabase when credentials are available. They will:
+
+1. **Check for Supabase credentials** in your `.env` file
+2. **Use Supabase if available** (preferred)
+3. **Fall back to SQLite** only if Supabase is not configured
+
+## 🔧 Required Configuration
+
+To ensure Supabase is used for all future data, make sure your `.env` file has:
+
+```env
+# Required for runtime (REST API)
+SUPABASE_URL=https://your-project-id.supabase.co
+SUPABASE_SERVICE_KEY=your_service_role_key_here
+
+# Optional: For direct PostgreSQL connection (migration only)
+POSTGRESQL_URL=postgresql://postgres:password@db.xxxxx.supabase.co:5432/postgres
+```
+
+**Important:**
+- `SUPABASE_URL` and `SUPABASE_SERVICE_KEY` are **required** for runtime
+- `POSTGRESQL_URL` is optional (only needed for migration script)
+- Both stores use the Supabase REST API at runtime, not direct PostgreSQL
+
+## ✅ Verify Configuration
+
+Run the verification script to confirm Supabase is configured:
+
+```bash
+python verify_supabase_setup.py
+```
+
+This will show:
+- ✅ Which backend each store is using
+- ⚠️  Any missing configuration
+- 📋 Summary of what will be saved where
+
+## 🚀 After Configuration
+
+1. **Restart your services:**
+   ```bash
+   # Stop your FastAPI server
+   # Stop your MCP server
+   # Then restart them
+   ```
+
+2. **Check startup logs:**
+   You should see messages like:
+   ```
+   ✅ RulesStore: Using Supabase backend
+   ✅ AnalyticsStore: Using Supabase backend
+   ✅ AgentOrchestrator Analytics: Using Supabase backend
+   ```
+
+3. **Test by adding data:**
+   - Add a rule via the admin panel
+   - Make a query to generate analytics
+   - Check Supabase Dashboard → Table Editor to verify data appears
+
+## 📊 Where Data is Saved
+
+| Data Type | Storage Location | Configuration |
+|-----------|-----------------|---------------|
+| Admin Rules | Supabase `admin_rules` table | `SUPABASE_URL` + `SUPABASE_SERVICE_KEY` |
+| Analytics Events | Supabase analytics tables | `SUPABASE_URL` + `SUPABASE_SERVICE_KEY` |
+| Tool Usage | Supabase `tool_usage_events` | `SUPABASE_URL` + `SUPABASE_SERVICE_KEY` |
+| Red Flags | Supabase `redflag_violations` | `SUPABASE_URL` + `SUPABASE_SERVICE_KEY` |
+| RAG Searches | Supabase `rag_search_events` | `SUPABASE_URL` + `SUPABASE_SERVICE_KEY` |
+| Agent Queries | Supabase `agent_query_events` | `SUPABASE_URL` + `SUPABASE_SERVICE_KEY` |
+
+## 🔍 Troubleshooting
+
+### Data still going to SQLite?
+
+1. **Check your `.env` file:**
+   ```bash
+   # Make sure these are set (no quotes, no spaces)
+   SUPABASE_URL=https://xxxxx.supabase.co
+   SUPABASE_SERVICE_KEY=eyJ... (full key)
+   ```
+
+2. **Verify credentials:**
+   ```bash
+   python verify_supabase_key.py
+   ```
+
+3. **Check startup logs:**
+   Look for warnings like:
+   ```
+   ⚠️  RulesStore: Using SQLite backend
+   ```
+   This means Supabase credentials are missing or invalid.
+
+4. **Restart services:**
+   Environment variables are loaded at startup. After changing `.env`, restart your services.
+
+### Tables don't exist?
+
+If you see errors about missing tables:
+
+1. Go to Supabase Dashboard → SQL Editor
+2. Run `supabase_admin_rules_table.sql` (for rules)
+3. Run `supabase_analytics_tables.sql` (for analytics)
+
+### API Key errors?
+
+- Make sure you're using the **service_role** key (not anon key)
+- Key should be ~200+ characters long
+- No quotes or spaces around the value in `.env`
+
+## 📝 Summary
+
+✅ **Migration complete** - Your existing data is in Supabase  
+✅ **Auto-detection enabled** - Stores automatically use Supabase when configured  
+✅ **Startup logging** - You'll see which backend is being used  
+✅ **Verification script** - Run `verify_supabase_setup.py` to check configuration  
+
+**Next time you add rules or generate analytics, they will automatically be saved to Supabase!** 🎉
+

SUPABASE_SETUP.md

@@ -73,27 +73,35 @@ print(f"Rules: {rules}")
 2. Select the `admin_rules` table
 3. You should see all your rules with tenant isolation
 
+## Supabase Analytics Tables
+
+To move analytics off SQLite, create the Supabase tables that mirror the local schema:
+
+1. Open the Supabase SQL Editor.
+2. Copy the contents of `supabase_analytics_tables.sql`.
+3. Run the script. It creates the following tables with indexes + RLS policies:
+   - `tool_usage_events`
+   - `redflag_violations`
+   - `rag_search_events`
+   - `agent_query_events`
+
+After the tables exist, the backend automatically detects Supabase credentials and writes analytics there (falling back to SQLite only when credentials or the Supabase client are missing).
+
 ## Migration from SQLite
 
-If you have existing rules in SQLite and want to migrate:
-
-1. Export from SQLite:
-   ```python
-   import sqlite3
-   conn = sqlite3.connect('data/admin_rules.db')
-   cursor = conn.execute("SELECT * FROM admin_rules")
-   rules = cursor.fetchall()
-   ```
-
-2. Import to Supabase:
-   ```python
-   from backend.api.storage.rules_store import RulesStore
-   store = RulesStore(use_supabase=True)
-   for rule in rules:
-       store.add_rule(rule['tenant_id'], rule['rule'], 
-                     pattern=rule.get('pattern'),
-                     severity=rule.get('severity', 'medium'))
-   ```
+If you already have local data that should be moved to Supabase, use the helper script:
+
+```bash
+python migrate_sqlite_to_supabase.py
+```
+
+The script:
+- Loads `.env` for Supabase credentials
+- Copies `data/admin_rules.db` → `admin_rules`
+- Copies all analytics tables in `data/analytics.db` → Supabase equivalents
+- Skips tables that already contain Supabase rows (pass `--force` to override)
+
+> **Tip:** Back up your SQLite databases before migrating. The script does not delete local data.
 
 ## Troubleshooting
 

backend/README.md

@@ -12,7 +12,7 @@ This folder contains the production-ready FastAPI stack plus the companion MCP s
 
 - Python 3.10+
 - PostgreSQL (with the `vector` extension) for RAG data, or Supabase with pgvector enabled
-- SQLite (auto-created in `data/`) for analytics and admin rules
+- Supabase (preferred) for admin rules + analytics, with automatic SQLite fallback in `data/`
 - Optional: Ollama running locally (default) or Groq API credentials for remote LLMs
 
 Create a virtual environment at the repo root, then:

backend/api/routes/admin.py

@@ -15,6 +15,17 @@ rules_store = RulesStore(auto_create_table=False)
 analytics_store = AnalyticsStore()
 rule_enhancer = RuleEnhancer()
 
+# Log which backend is being used
+if rules_store.use_supabase:
+    print("✅ RulesStore: Using Supabase backend")
+else:
+    print("⚠️  RulesStore: Using SQLite backend (set SUPABASE_URL + SUPABASE_SERVICE_KEY to use Supabase)")
+
+if analytics_store.use_supabase:
+    print("✅ AnalyticsStore: Using Supabase backend")
+else:
+    print("⚠️  AnalyticsStore: Using SQLite backend (set SUPABASE_URL + SUPABASE_SERVICE_KEY to use Supabase)")
+
 
 class RulePayload(BaseModel):
     rule: str

backend/api/services/agent_orchestrator.py

@@ -44,6 +44,13 @@ class AgentOrchestrator:
         self.selector = ToolSelector(llm_client=self.llm)
         self.tool_scorer = ToolScoringService()
         self.analytics = AnalyticsStore()
+        # Log backend being used (only once at startup)
+        if not hasattr(AgentOrchestrator, '_analytics_backend_logged'):
+            if self.analytics.use_supabase:
+                print("✅ AgentOrchestrator Analytics: Using Supabase backend")
+            else:
+                print("⚠️  AgentOrchestrator Analytics: Using SQLite backend")
+            AgentOrchestrator._analytics_backend_logged = True
 
     async def handle(self, req: AgentRequest) -> AgentResponse:
         start_time = time.time()

backend/api/storage/analytics_store.py

@@ -9,21 +9,55 @@ Tracks:
 - Per-tenant query volume
 """
 
-import sqlite3
 import json
+import os
+import sqlite3
 import time
-from pathlib import Path
-from typing import List, Dict, Any, Optional
 from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+try:
+    from supabase import Client, create_client
+
+    SUPABASE_AVAILABLE = True
+except ImportError:
+    Client = None  # type: ignore
+    SUPABASE_AVAILABLE = False
 
 
 class AnalyticsStore:
     """
-    SQLite-backed store for analytics logging.
-    Provides tenant-level analytics for tool usage, tokens, latency, and violations.
+    Analytics logging with dual-backend support.
+
+    - Uses Supabase when SUPABASE_URL/SUPABASE_SERVICE_KEY are configured
+    - Falls back to local SQLite (data/analytics.db) otherwise
     """
 
-    def __init__(self, db_path: Optional[str] = None):
+    def __init__(
+        self,
+        db_path: Optional[str] = None,
+        use_supabase: Optional[bool] = None,
+        auto_create_tables: bool = False,
+    ):
+        self.use_supabase = use_supabase
+        self._tables_verified = False
+        self.supabase_client: Optional[Client] = None
+
+        if self.use_supabase is None:
+            supabase_url = os.getenv("SUPABASE_URL")
+            supabase_key = os.getenv("SUPABASE_SERVICE_KEY")
+            self.use_supabase = bool(
+                supabase_url and supabase_key and SUPABASE_AVAILABLE
+            )
+
+        if self.use_supabase:
+            self._init_supabase(auto_create_tables)
+        else:
+            self._init_sqlite(db_path)
+
+    def _init_sqlite(self, db_path: Optional[str]):
+        """Initialize SQLite database path + schema."""
         if db_path is None:
             root_dir = Path(__file__).resolve().parents[3]
             data_dir = root_dir / "data"
@@ -31,14 +65,71 @@ class AnalyticsStore:
             self.db_path = data_dir / "analytics.db"
         else:
             self.db_path = Path(db_path)
-        
+
         self._init_db()
 
+    def _init_supabase(self, auto_create_tables: bool):
+        supabase_url = os.getenv("SUPABASE_URL")
+        supabase_key = os.getenv("SUPABASE_SERVICE_KEY")
+
+        if not supabase_url or not supabase_key:
+            print("⚠️  Supabase credentials missing. Falling back to SQLite for analytics.")
+            self.use_supabase = False
+            self._init_sqlite(None)
+            return
+
+        try:
+            self.supabase_client = create_client(supabase_url, supabase_key)
+            self.table_names = {
+                "tool_usage": "tool_usage_events",
+                "redflags": "redflag_violations",
+                "rag_search": "rag_search_events",
+                "agent_query": "agent_query_events",
+            }
+
+            if auto_create_tables:
+                self._ensure_supabase_tables()
+            else:
+                self._quick_table_check()
+        except Exception as exc:  # pragma: no cover - defensive logging
+            print(f"⚠️  Failed to initialize Supabase client for analytics: {exc}")
+            self.use_supabase = False
+            self._init_sqlite(None)
+
+    def _quick_table_check(self):
+        """Verify that all expected Supabase tables exist."""
+        if not self.supabase_client:
+            return
+        try:
+            for table in self.table_names.values():
+                # PostgREST select throws if table missing
+                self.supabase_client.table(table).select("id").limit(1).execute()
+            self._tables_verified = True
+        except Exception:
+            self._tables_verified = False
+
+    def _ensure_supabase_tables(self):
+        """
+        Best-effort table check. Actual table creation should be done by running
+        supabase_analytics_tables.sql (mentioned in README + SUPABASE_SETUP).
+        """
+        self._quick_table_check()
+        if not self._tables_verified:
+            sql_file = (
+                Path(__file__).resolve().parents[3] / "supabase_analytics_tables.sql"
+            )
+            print("⚠️  Supabase analytics tables not verified.")
+            if sql_file.exists():
+                print(f"   Run the SQL script: {sql_file}")
+            else:
+                print("   Missing supabase_analytics_tables.sql in repo root.")
+
     def _init_db(self):
         """Initialize database tables for analytics."""
         with sqlite3.connect(self.db_path) as conn:
             # Tool usage events table
-            conn.execute("""
+            conn.execute(
+                """
                 CREATE TABLE IF NOT EXISTS tool_usage_events (
                     id INTEGER PRIMARY KEY AUTOINCREMENT,
                     tenant_id TEXT NOT NULL,
@@ -51,10 +142,12 @@ class AnalyticsStore:
                     error_message TEXT,
                     metadata TEXT
                 )
-            """)
-            
+                """
+            )
+
             # Red-flag violations table
-            conn.execute("""
+            conn.execute(
+                """
                 CREATE TABLE IF NOT EXISTS redflag_violations (
                     id INTEGER PRIMARY KEY AUTOINCREMENT,
                     tenant_id TEXT NOT NULL,
@@ -67,10 +160,12 @@ class AnalyticsStore:
                     message_preview TEXT,
                     timestamp INTEGER NOT NULL
                 )
-            """)
-            
+                """
+            )
+
             # RAG search events with quality metrics
-            conn.execute("""
+            conn.execute(
+                """
                 CREATE TABLE IF NOT EXISTS rag_search_events (
                     id INTEGER PRIMARY KEY AUTOINCREMENT,
                     tenant_id TEXT NOT NULL,
@@ -81,10 +176,12 @@ class AnalyticsStore:
                     timestamp INTEGER NOT NULL,
                     latency_ms INTEGER
                 )
-            """)
-            
+                """
+            )
+
             # Agent query events (overall query tracking)
-            conn.execute("""
+            conn.execute(
+                """
                 CREATE TABLE IF NOT EXISTS agent_query_events (
                     id INTEGER PRIMARY KEY AUTOINCREMENT,
                     tenant_id TEXT NOT NULL,
@@ -97,31 +194,122 @@ class AnalyticsStore:
                     success BOOLEAN DEFAULT 1,
                     timestamp INTEGER NOT NULL
                 )
-            """)
-            
+                """
+            )
+
             # Create indexes separately (SQLite doesn't support inline INDEX in CREATE TABLE)
-            conn.execute("""
+            conn.execute(
+                """
                 CREATE INDEX IF NOT EXISTS idx_tool_usage_tenant_timestamp 
                 ON tool_usage_events(tenant_id, timestamp)
-            """)
-            
-            conn.execute("""
+                """
+            )
+
+            conn.execute(
+                """
                 CREATE INDEX IF NOT EXISTS idx_redflag_tenant_timestamp 
                 ON redflag_violations(tenant_id, timestamp)
-            """)
-            
-            conn.execute("""
+                """
+            )
+
+            conn.execute(
+                """
                 CREATE INDEX IF NOT EXISTS idx_rag_search_tenant_timestamp 
                 ON rag_search_events(tenant_id, timestamp)
-            """)
-            
-            conn.execute("""
+                """
+            )
+
+            conn.execute(
+                """
                 CREATE INDEX IF NOT EXISTS idx_agent_query_tenant_timestamp 
                 ON agent_query_events(tenant_id, timestamp)
-            """)
-            
+                """
+            )
+
             conn.commit()
 
+    # ------------------------------------------------------------------
+    # Logging helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _now_ts() -> int:
+        return int(time.time())
+
+    def _serialize_tools(self, tools_used: Optional[List[str]]) -> Optional[str]:
+        if tools_used:
+            return json.dumps(tools_used)
+        return None
+
+    def _serialize_metadata(self, metadata: Optional[Dict[str, Any]]):
+        if metadata:
+            return json.dumps(metadata)
+        return None
+
+    def _supabase_insert(self, table: str, payload: Dict[str, Any]):
+        if not self.supabase_client:
+            return
+        try:
+            self.supabase_client.table(table).insert(payload).execute()
+        except Exception as exc:  # pragma: no cover - logging only
+            print(f"❌ Supabase insert failed for {table}: {exc}")
+
+    def _supabase_simple_select(
+        self,
+        table: str,
+        tenant_id: str,
+        since_timestamp: Optional[int] = None,
+        limit: Optional[int] = None,
+        order_desc: bool = False,
+    ) -> List[Dict[str, Any]]:
+        if not self.supabase_client:
+            return []
+        query = (
+            self.supabase_client.table(table)
+            .select("*")
+            .eq("tenant_id", tenant_id)
+            .order("timestamp", desc=order_desc)
+        )
+        if since_timestamp is not None:
+            query = query.gte("timestamp", since_timestamp)
+        if limit is not None:
+            query = query.limit(limit)
+        response = query.execute()
+        return response.data or []
+
+    def _supabase_fetch_all(
+        self,
+        table: str,
+        tenant_id: str,
+        since_timestamp: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        """Fetch all rows for a tenant (used for aggregations)."""
+        if not self.supabase_client:
+            return []
+
+        rows: List[Dict[str, Any]] = []
+        start = 0
+        batch_size = 1000
+
+        while True:
+            query = (
+                self.supabase_client.table(table)
+                .select("*")
+                .eq("tenant_id", tenant_id)
+                .order("timestamp", desc=False)
+                .range(start, start + batch_size - 1)
+            )
+            if since_timestamp is not None:
+                query = query.gte("timestamp", since_timestamp)
+            response = query.execute()
+            batch = response.data or []
+            rows.extend(batch)
+            if len(batch) < batch_size:
+                break
+            start += batch_size
+
+        return rows
+
     def log_tool_usage(
         self,
         tenant_id: str,
@@ -134,22 +322,40 @@ class AnalyticsStore:
         user_id: Optional[str] = None
     ):
         """Log a tool usage event."""
+        if self.use_supabase and self.supabase_client:
+            payload = {
+                "tenant_id": tenant_id,
+                "user_id": user_id,
+                "tool_name": tool_name,
+                "timestamp": self._now_ts(),
+                "latency_ms": latency_ms,
+                "tokens_used": tokens_used,
+                "success": success,
+                "error_message": error_message,
+                "metadata": metadata,
+            }
+            self._supabase_insert(self.table_names["tool_usage"], payload)
+            return
+
         with sqlite3.connect(self.db_path) as conn:
-            conn.execute("""
+            conn.execute(
+                """
                 INSERT INTO tool_usage_events 
                 (tenant_id, user_id, tool_name, timestamp, latency_ms, tokens_used, success, error_message, metadata)
                 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-            """, (
-                tenant_id,
-                user_id,
-                tool_name,
-                int(time.time()),
-                latency_ms,
-                tokens_used,
-                1 if success else 0,
-                error_message,
-                json.dumps(metadata) if metadata else None
-            ))
+                """,
+                (
+                    tenant_id,
+                    user_id,
+                    tool_name,
+                    self._now_ts(),
+                    latency_ms,
+                    tokens_used,
+                    1 if success else 0,
+                    error_message,
+                    self._serialize_metadata(metadata),
+                ),
+            )
             conn.commit()
 
     def log_redflag_violation(
@@ -164,22 +370,42 @@ class AnalyticsStore:
         user_id: Optional[str] = None
     ):
         """Log a red-flag violation."""
+        truncated_message = message_preview[:200] if message_preview else None
+
+        if self.use_supabase and self.supabase_client:
+            payload = {
+                "tenant_id": tenant_id,
+                "user_id": user_id,
+                "rule_id": rule_id,
+                "rule_pattern": rule_pattern,
+                "severity": severity,
+                "matched_text": matched_text,
+                "confidence": confidence,
+                "message_preview": truncated_message,
+                "timestamp": self._now_ts(),
+            }
+            self._supabase_insert(self.table_names["redflags"], payload)
+            return
+
         with sqlite3.connect(self.db_path) as conn:
-            conn.execute("""
+            conn.execute(
+                """
                 INSERT INTO redflag_violations
                 (tenant_id, user_id, rule_id, rule_pattern, severity, matched_text, confidence, message_preview, timestamp)
                 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-            """, (
-                tenant_id,
-                user_id,
-                rule_id,
-                rule_pattern,
-                severity,
-                matched_text,
-                confidence,
-                message_preview[:200] if message_preview else None,
-                int(time.time())
-            ))
+                """,
+                (
+                    tenant_id,
+                    user_id,
+                    rule_id,
+                    rule_pattern,
+                    severity,
+                    matched_text,
+                    confidence,
+                    truncated_message,
+                    self._now_ts(),
+                ),
+            )
             conn.commit()
 
     def log_rag_search(
@@ -192,20 +418,37 @@ class AnalyticsStore:
         latency_ms: Optional[int] = None
     ):
         """Log a RAG search event with quality metrics."""
+        trimmed_query = query[:500]
+        if self.use_supabase and self.supabase_client:
+            payload = {
+                "tenant_id": tenant_id,
+                "query": trimmed_query,
+                "hits_count": hits_count,
+                "avg_score": avg_score,
+                "top_score": top_score,
+                "timestamp": self._now_ts(),
+                "latency_ms": latency_ms,
+            }
+            self._supabase_insert(self.table_names["rag_search"], payload)
+            return
+
         with sqlite3.connect(self.db_path) as conn:
-            conn.execute("""
+            conn.execute(
+                """
                 INSERT INTO rag_search_events
                 (tenant_id, query, hits_count, avg_score, top_score, timestamp, latency_ms)
                 VALUES (?, ?, ?, ?, ?, ?, ?)
-            """, (
-                tenant_id,
-                query[:500],  # Limit query length
-                hits_count,
-                avg_score,
-                top_score,
-                int(time.time()),
-                latency_ms
-            ))
+                """,
+                (
+                    tenant_id,
+                    trimmed_query,
+                    hits_count,
+                    avg_score,
+                    top_score,
+                    self._now_ts(),
+                    latency_ms,
+                ),
+            )
             conn.commit()
 
     def log_agent_query(
@@ -220,22 +463,43 @@ class AnalyticsStore:
         user_id: Optional[str] = None
     ):
         """Log an agent query event (overall query tracking)."""
+        truncated_message = message_preview[:200]
+        serialized_tools = self._serialize_tools(tools_used)
+
+        if self.use_supabase and self.supabase_client:
+            payload = {
+                "tenant_id": tenant_id,
+                "user_id": user_id,
+                "message_preview": truncated_message,
+                "intent": intent,
+                "tools_used": tools_used,
+                "total_tokens": total_tokens,
+                "total_latency_ms": total_latency_ms,
+                "success": success,
+                "timestamp": self._now_ts(),
+            }
+            self._supabase_insert(self.table_names["agent_query"], payload)
+            return
+
         with sqlite3.connect(self.db_path) as conn:
-            conn.execute("""
+            conn.execute(
+                """
                 INSERT INTO agent_query_events
                 (tenant_id, user_id, message_preview, intent, tools_used, total_tokens, total_latency_ms, success, timestamp)
                 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-            """, (
-                tenant_id,
-                user_id,
-                message_preview[:200],
-                intent,
-                json.dumps(tools_used) if tools_used else None,
-                total_tokens,
-                total_latency_ms,
-                1 if success else 0,
-                int(time.time())
-            ))
+                """,
+                (
+                    tenant_id,
+                    user_id,
+                    truncated_message,
+                    intent,
+                    serialized_tools,
+                    total_tokens,
+                    total_latency_ms,
+                    1 if success else 0,
+                    self._now_ts(),
+                ),
+            )
             conn.commit()
 
     def get_tool_usage_stats(
@@ -244,42 +508,78 @@ class AnalyticsStore:
         since_timestamp: Optional[int] = None
     ) -> Dict[str, Any]:
         """Get tool usage statistics for a tenant."""
-        with sqlite3.connect(self.db_path) as conn:
-            conn.row_factory = sqlite3.Row
-            
-            query = """
-                SELECT 
-                    tool_name,
-                    COUNT(*) as count,
-                    AVG(latency_ms) as avg_latency_ms,
-                    SUM(tokens_used) as total_tokens,
-                    SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) as success_count
-                FROM tool_usage_events
-                WHERE tenant_id = ?
-            """
-            params = [tenant_id]
-            
-            if since_timestamp:
-                query += " AND timestamp >= ?"
-                params.append(since_timestamp)
-            
-            query += " GROUP BY tool_name"
-            
-            cursor = conn.execute(query, params)
-            rows = cursor.fetchall()
-            
-            stats = {}
-            for row in rows:
-                tool_name = row["tool_name"]
-                stats[tool_name] = {
-                    "count": row["count"],
-                    "avg_latency_ms": round(row["avg_latency_ms"] or 0, 2),
-                    "total_tokens": row["total_tokens"] or 0,
-                    "success_count": row["success_count"],
-                    "error_count": row["count"] - row["success_count"]
-                }
-            
-            return stats
+        if self.use_supabase and self.supabase_client:
+            rows = self._supabase_fetch_all(
+                self.table_names["tool_usage"], tenant_id, since_timestamp
+            )
+        else:
+            with sqlite3.connect(self.db_path) as conn:
+                conn.row_factory = sqlite3.Row
+
+                query = """
+                    SELECT 
+                        tool_name,
+                        COUNT(*) as count,
+                        AVG(latency_ms) as avg_latency_ms,
+                        SUM(tokens_used) as total_tokens,
+                        SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) as success_count
+                    FROM tool_usage_events
+                    WHERE tenant_id = ?
+                """
+                params = [tenant_id]
+
+                if since_timestamp:
+                    query += " AND timestamp >= ?"
+                    params.append(since_timestamp)
+
+                query += " GROUP BY tool_name"
+
+                cursor = conn.execute(query, params)
+                rows = cursor.fetchall()
+
+                stats = {}
+                for row in rows:
+                    tool_name = row["tool_name"]
+                    stats[tool_name] = {
+                        "count": row["count"],
+                        "avg_latency_ms": round(row["avg_latency_ms"] or 0, 2),
+                        "total_tokens": row["total_tokens"] or 0,
+                        "success_count": row["success_count"],
+                        "error_count": row["count"] - row["success_count"],
+                    }
+
+                return stats
+
+        # Supabase aggregation (computed in Python)
+        stats: Dict[str, Dict[str, Any]] = {}
+        for row in rows:
+            tool_name = row.get("tool_name")
+            if not tool_name:
+                continue
+            entry = stats.setdefault(
+                tool_name,
+                {
+                    "count": 0,
+                    "avg_latency_ms": 0.0,
+                    "total_tokens": 0,
+                    "success_count": 0,
+                    "error_count": 0,
+                },
+            )
+            entry["count"] += 1
+            latency = row.get("latency_ms") or 0
+            entry["avg_latency_ms"] += latency
+            entry["total_tokens"] += row.get("tokens_used") or 0
+            if row.get("success"):
+                entry["success_count"] += 1
+            else:
+                entry["error_count"] += 1
+
+        for tool_name, entry in stats.items():
+            if entry["count"]:
+                entry["avg_latency_ms"] = round(entry["avg_latency_ms"] / entry["count"], 2)
+
+        return stats
 
     def get_redflag_violations(
         self,
@@ -288,25 +588,35 @@ class AnalyticsStore:
         since_timestamp: Optional[int] = None
     ) -> List[Dict[str, Any]]:
         """Get recent red-flag violations for a tenant."""
+        if self.use_supabase and self.supabase_client:
+            rows = self._supabase_simple_select(
+                self.table_names["redflags"],
+                tenant_id,
+                since_timestamp=since_timestamp,
+                limit=limit,
+                order_desc=True,
+            )
+            return rows
+
         with sqlite3.connect(self.db_path) as conn:
             conn.row_factory = sqlite3.Row
-            
+
             query = """
                 SELECT * FROM redflag_violations
                 WHERE tenant_id = ?
             """
             params = [tenant_id]
-            
+
             if since_timestamp:
                 query += " AND timestamp >= ?"
                 params.append(since_timestamp)
-            
+
             query += " ORDER BY timestamp DESC LIMIT ?"
             params.append(limit)
-            
+
             cursor = conn.execute(query, params)
             rows = cursor.fetchall()
-            
+
             return [dict(row) for row in rows]
 
     def get_activity_summary(
@@ -315,18 +625,40 @@ class AnalyticsStore:
         since_timestamp: Optional[int] = None
     ) -> Dict[str, Any]:
         """Get activity summary for a tenant."""
+        if self.use_supabase and self.supabase_client:
+            queries = self._supabase_fetch_all(
+                self.table_names["agent_query"], tenant_id, since_timestamp
+            )
+            redflags = self._supabase_fetch_all(
+                self.table_names["redflags"], tenant_id, since_timestamp
+            )
+
+            total_queries = len(queries)
+            active_users = len({row["user_id"] for row in queries if row.get("user_id")})
+            last_query_ts = max((row.get("timestamp") or 0) for row in queries) if queries else None
+            redflag_count = len(redflags)
+
+            return {
+                "total_queries": total_queries,
+                "active_users": active_users,
+                "redflag_count": redflag_count,
+                "last_query": datetime.fromtimestamp(last_query_ts).isoformat()
+                if last_query_ts
+                else None,
+            }
+
         with sqlite3.connect(self.db_path) as conn:
             conn.row_factory = sqlite3.Row
-            
+
             # Total queries
             query = "SELECT COUNT(*) as total FROM agent_query_events WHERE tenant_id = ?"
             params = [tenant_id]
             if since_timestamp:
                 query += " AND timestamp >= ?"
                 params.append(since_timestamp)
-            
+
             total_queries = conn.execute(query, params).fetchone()["total"]
-            
+
             # Active users (unique user_ids in the period)
             query = """
                 SELECT COUNT(DISTINCT user_id) as active_users
@@ -337,9 +669,9 @@ class AnalyticsStore:
             if since_timestamp:
                 query += " AND timestamp >= ?"
                 params.append(since_timestamp)
-            
+
             active_users = conn.execute(query, params).fetchone()["active_users"]
-            
+
             # Last query timestamp
             query = """
                 SELECT MAX(timestamp) as last_query
@@ -347,21 +679,23 @@ class AnalyticsStore:
                 WHERE tenant_id = ?
             """
             last_query_ts = conn.execute(query, [tenant_id]).fetchone()["last_query"]
-            
+
             # Red-flag count
             query = "SELECT COUNT(*) as count FROM redflag_violations WHERE tenant_id = ?"
             params = [tenant_id]
             if since_timestamp:
                 query += " AND timestamp >= ?"
                 params.append(since_timestamp)
-            
+
             redflag_count = conn.execute(query, params).fetchone()["count"]
-            
+
             return {
                 "total_queries": total_queries,
                 "active_users": active_users or 0,
                 "redflag_count": redflag_count,
-                "last_query": datetime.fromtimestamp(last_query_ts).isoformat() if last_query_ts else None
+                "last_query": datetime.fromtimestamp(last_query_ts).isoformat()
+                if last_query_ts
+                else None,
             }
 
     def get_rag_quality_metrics(
@@ -370,9 +704,37 @@ class AnalyticsStore:
         since_timestamp: Optional[int] = None
     ) -> Dict[str, Any]:
         """Get RAG quality metrics (recall/precision indicators)."""
+        if self.use_supabase and self.supabase_client:
+            rows = self._supabase_fetch_all(
+                self.table_names["rag_search"], tenant_id, since_timestamp
+            )
+
+            if not rows:
+                return {
+                    "total_searches": 0,
+                    "avg_hits_per_search": 0,
+                    "avg_score": 0,
+                    "avg_top_score": 0,
+                    "avg_latency_ms": 0,
+                }
+
+            total_searches = len(rows)
+            avg_hits = sum(row.get("hits_count") or 0 for row in rows) / total_searches
+            avg_avg_score = sum(row.get("avg_score") or 0 for row in rows) / total_searches
+            avg_top_score = sum(row.get("top_score") or 0 for row in rows) / total_searches
+            avg_latency = sum(row.get("latency_ms") or 0 for row in rows) / total_searches
+
+            return {
+                "total_searches": total_searches,
+                "avg_hits_per_search": round(avg_hits, 2),
+                "avg_score": round(avg_avg_score, 3),
+                "avg_top_score": round(avg_top_score, 3),
+                "avg_latency_ms": round(avg_latency, 2),
+            }
+
         with sqlite3.connect(self.db_path) as conn:
             conn.row_factory = sqlite3.Row
-            
+
             query = """
                 SELECT 
                     COUNT(*) as total_searches,
@@ -384,18 +746,18 @@ class AnalyticsStore:
                 WHERE tenant_id = ?
             """
             params = [tenant_id]
-            
+
             if since_timestamp:
                 query += " AND timestamp >= ?"
                 params.append(since_timestamp)
-            
+
             row = conn.execute(query, params).fetchone()
-            
+
             return {
                 "total_searches": row["total_searches"] or 0,
                 "avg_hits_per_search": round(row["avg_hits"] or 0, 2),
                 "avg_score": round(row["avg_avg_score"] or 0, 3),
                 "avg_top_score": round(row["avg_top_score"] or 0, 3),
-                "avg_latency_ms": round(row["avg_latency_ms"] or 0, 2)
+                "avg_latency_ms": round(row["avg_latency_ms"] or 0, 2),
             }
 

check_supabase_rules.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""
+Quick script to verify Supabase rules storage is working.
+Run this to check if rules are being saved to Supabase.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+# Load environment variables from .env file
+from dotenv import load_dotenv
+load_dotenv()
+
+# Add backend to path
+backend_dir = Path(__file__).resolve().parent
+sys.path.insert(0, str(backend_dir))
+
+from backend.api.storage.rules_store import RulesStore
+
+
+def main():
+    print("=" * 60)
+    print("Supabase Rules Storage Verification")
+    print("=" * 60)
+    
+    # Check environment variables
+    supabase_url = os.getenv("SUPABASE_URL")
+    supabase_key = os.getenv("SUPABASE_SERVICE_KEY")
+    
+    print("\n1. Checking Environment Variables:")
+    if supabase_url:
+        print(f"   ✅ SUPABASE_URL is set: {supabase_url[:50]}...")
+    else:
+        print("   ❌ SUPABASE_URL is not set")
+        print("      Add it to your .env file: SUPABASE_URL=https://your-project.supabase.co")
+    
+    if supabase_key:
+        print(f"   ✅ SUPABASE_SERVICE_KEY is set: {supabase_key[:20]}...")
+    else:
+        print("   ❌ SUPABASE_SERVICE_KEY is not set")
+        print("      Add it to your .env file: SUPABASE_SERVICE_KEY=your_service_role_key")
+    
+    if not supabase_url or not supabase_key:
+        print("\n⚠️  Supabase credentials are missing!")
+        print("   Rules will be saved to SQLite instead.")
+        print("   See SUPABASE_SETUP.md for setup instructions.")
+        print("\n   To use Supabase:")
+        print("   1. Add SUPABASE_URL and SUPABASE_SERVICE_KEY to your .env file")
+        print("   2. Create the admin_rules table in Supabase (see supabase_admin_rules_table.sql)")
+        print("   3. Restart your application")
+        return
+    
+    # Initialize RulesStore
+    print("\n2. Initializing RulesStore:")
+    try:
+        store = RulesStore(auto_create_table=True)
+        print(f"   ✅ RulesStore initialized")
+        print(f"   📦 Using Supabase: {store.use_supabase}")
+        
+        if not store.use_supabase:
+            print("   ⚠️  RulesStore is using SQLite, not Supabase!")
+            print("   Check that:")
+            print("   - SUPABASE_URL and SUPABASE_SERVICE_KEY are correct")
+            print("   - Supabase Python client is installed: pip install supabase")
+            return
+        
+    except Exception as e:
+        print(f"   ❌ Failed to initialize RulesStore: {e}")
+        return
+    
+    # Test adding a rule
+    print("\n3. Testing Rule Storage:")
+    test_tenant = "test_verification"
+    test_rule = "Test rule for Supabase verification"
+    
+    try:
+        # Delete test rule if it exists
+        store.delete_rule(test_tenant, test_rule)
+        
+        # Add test rule
+        success = store.add_rule(
+            test_tenant,
+            test_rule,
+            severity="medium",
+            description="Verification test rule"
+        )
+        
+        if success:
+            print(f"   ✅ Successfully added test rule to Supabase")
+        else:
+            print(f"   ❌ Failed to add rule to Supabase")
+            return
+        
+        # Retrieve rule
+        rules = store.get_rules(test_tenant)
+        if test_rule in rules:
+            print(f"   ✅ Successfully retrieved rule from Supabase")
+            print(f"   📋 Found {len(rules)} rule(s) for tenant '{test_tenant}'")
+        else:
+            print(f"   ❌ Rule not found after adding")
+            return
+        
+        # Get detailed rules
+        detailed_rules = store.get_rules_detailed(test_tenant)
+        if detailed_rules:
+            print(f"   ✅ Successfully retrieved detailed rules")
+            for rule in detailed_rules:
+                if rule['rule'] == test_rule:
+                    print(f"   📝 Rule details:")
+                    print(f"      - Pattern: {rule.get('pattern', 'N/A')}")
+                    print(f"      - Severity: {rule.get('severity', 'N/A')}")
+                    print(f"      - Enabled: {rule.get('enabled', 'N/A')}")
+        
+        # Cleanup test rule
+        store.delete_rule(test_tenant, test_rule)
+        print(f"   🧹 Cleaned up test rule")
+        
+    except Exception as e:
+        print(f"   ❌ Error during test: {e}")
+        import traceback
+        traceback.print_exc()
+        return
+    
+    print("\n" + "=" * 60)
+    print("✅ All checks passed! Rules are being saved to Supabase.")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()
+

migrate_sqlite_to_supabase.py

@@ -0,0 +1,826 @@
+#!/usr/bin/env python3
+"""
+One-shot migration script that copies existing SQLite data (admin rules + analytics)
+into Supabase tables. Run this after creating the Supabase schemas:
+
+1. supabase_admin_rules_table.sql
+2. supabase_analytics_tables.sql
+
+Usage:
+    python migrate_sqlite_to_supabase.py [--force]
+
+Connection Methods (choose one):
+- POSTGRESQL_URL (recommended): Direct PostgreSQL connection
+  Format: postgresql://user:password@host:port/database
+- SUPABASE_URL + SUPABASE_SERVICE_KEY: Supabase REST API
+  Requires: SUPABASE_URL and SUPABASE_SERVICE_KEY in your .env
+
+Notes:
+- Does not delete local SQLite data
+- Re-running without --force will skip tables that already contain Supabase rows
+- POSTGRESQL_URL method is faster and doesn't require service_role key
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import socket
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Iterable, List
+
+from dotenv import load_dotenv
+
+# Try to import both connection methods
+try:
+    from supabase import Client, create_client
+    SUPABASE_AVAILABLE = True
+except ImportError:
+    SUPABASE_AVAILABLE = False
+    Client = None
+
+try:
+    import psycopg2
+    from psycopg2.extras import execute_batch
+    PSYCOPG2_AVAILABLE = True
+except ImportError:
+    PSYCOPG2_AVAILABLE = False
+
+BATCH_SIZE = 500
+
+
+def chunked(items: List[Dict[str, Any]], size: int) -> Iterable[List[Dict[str, Any]]]:
+    for i in range(0, len(items), size):
+        yield items[i : i + size]
+
+
+def get_connection_method():
+    """Determine which connection method to use: PostgreSQL direct or Supabase API."""
+    load_dotenv()
+    postgres_url = os.getenv("POSTGRESQL_URL")
+    supabase_url = os.getenv("SUPABASE_URL")
+    supabase_key = os.getenv("SUPABASE_SERVICE_KEY")
+    
+    # Prefer PostgreSQL direct connection if available
+    if postgres_url and PSYCOPG2_AVAILABLE:
+        return "postgresql"
+    elif supabase_url and supabase_key and SUPABASE_AVAILABLE:
+        return "supabase"
+    else:
+        return None
+
+
+def get_postgres_connection():
+    """Get direct PostgreSQL connection using POSTGRESQL_URL."""
+    load_dotenv()
+    postgres_url = os.getenv("POSTGRESQL_URL")
+    
+    if not postgres_url:
+        raise RuntimeError(
+            "POSTGRESQL_URL not set in .env file.\n"
+            "   Format: postgresql://user:password@host:port/database"
+        )
+    
+    if not PSYCOPG2_AVAILABLE:
+        raise RuntimeError(
+            "psycopg2 not installed. Install it with: pip install psycopg2-binary"
+        )
+    
+    try:
+        conn = psycopg2.connect(postgres_url)
+        return conn
+    except Exception as e:
+        raise RuntimeError(
+            f"Failed to connect to PostgreSQL: {e}\n"
+            "   Check that POSTGRESQL_URL is correct and the database is accessible."
+        ) from e
+
+
+def load_supabase_client() -> Client:
+    load_dotenv()
+    url = os.getenv("SUPABASE_URL")
+    key = os.getenv("SUPABASE_SERVICE_KEY")
+    
+    if not url or not key:
+        raise RuntimeError(
+            "Supabase credentials missing. Set SUPABASE_URL and SUPABASE_SERVICE_KEY in your .env file.\n"
+            f"  SUPABASE_URL: {'✅ Set' if url else '❌ Missing'}\n"
+            f"  SUPABASE_SERVICE_KEY: {'✅ Set' if key else '❌ Missing'}"
+        )
+    
+    # Validate URL format
+    if not url.startswith("https://"):
+        raise RuntimeError(
+            f"Invalid SUPABASE_URL format. Expected https://... but got: {url[:50]}...\n"
+            "  Example: https://your-project-id.supabase.co"
+        )
+    
+    if ".supabase.co" not in url:
+        print(f"⚠️  Warning: SUPABASE_URL doesn't contain '.supabase.co': {url[:50]}...")
+        print("   Make sure this is the correct Supabase project URL.")
+    
+    # Validate and clean API key format
+    key_trimmed = key.strip()
+    if key_trimmed != key:
+        print("⚠️  Warning: SUPABASE_SERVICE_KEY has leading/trailing whitespace. Trimming...")
+    key = key_trimmed  # Use trimmed version
+    
+    if not key.startswith("eyJ"):
+        print("⚠️  Warning: SUPABASE_SERVICE_KEY doesn't start with 'eyJ' (expected JWT format)")
+        print("   Make sure you're using the service_role key, not the anon key.")
+    
+    if len(key) < 100:
+        print("⚠️  Warning: SUPABASE_SERVICE_KEY seems too short (should be ~200+ characters)")
+        print("   Make sure you copied the entire key from Supabase Dashboard.")
+    
+    # Mask URL and key for display
+    masked_url = url[:20] + "..." + url[-15:] if len(url) > 35 else url[:20] + "..."
+    masked_key = key[:10] + "..." + key[-10:] if len(key) > 20 else key[:10] + "..."
+    print(f"🔗 Connecting to Supabase: {masked_url}")
+    print(f"🔑 Using API key: {masked_key} ({len(key)} chars)")
+    
+    # Test DNS resolution first
+    try:
+        hostname = url.replace("https://", "").replace("http://", "").split("/")[0]
+        print(f"   Resolving DNS for: {hostname}...")
+        socket.gethostbyname(hostname)
+        print("   ✅ DNS resolution successful")
+    except socket.gaierror as dns_err:
+        raise RuntimeError(
+            f"❌ Cannot resolve DNS for Supabase URL: {url}\n"
+            "   This usually means:\n"
+            "   1. The Supabase project doesn't exist or was deleted\n"
+            "   2. The project is paused (check Supabase Dashboard)\n"
+            "   3. The URL is incorrect\n"
+            "   4. Network/DNS connectivity issue\n\n"
+            "   To fix:\n"
+            "   1. Go to https://app.supabase.com and check your project status\n"
+            "   2. If paused, resume it from the dashboard\n"
+            "   3. Copy the correct URL from Settings → API\n"
+            f"   DNS Error: {dns_err}"
+        ) from dns_err
+    
+    try:
+        client = create_client(url, key)
+        # Test connection with a simple query
+        print("   Testing connection...")
+        client.table("admin_rules").select("id").limit(0).execute()
+        print("   ✅ Connection successful!")
+        return client
+    except Exception as e:
+        error_msg = str(e)
+        if "getaddrinfo failed" in error_msg or "ConnectError" in str(type(e)):
+            raise RuntimeError(
+                f"❌ Cannot connect to Supabase URL: {url}\n"
+                "   Possible issues:\n"
+                "   1. URL is incomplete or incorrect (should be: https://xxxxx.supabase.co)\n"
+                "   2. Network connectivity problem\n"
+                "   3. Supabase project doesn't exist or is paused\n"
+                "   4. Firewall/proxy blocking the connection\n\n"
+                "   Check your Supabase project at: https://app.supabase.com\n"
+                f"   Error: {error_msg}"
+            ) from e
+        else:
+            # Check if it's an API key error
+            if "Invalid API key" in error_msg or "401" in error_msg:
+                raise RuntimeError(
+                    f"❌ Invalid API Key Error\n"
+                    "   The SUPABASE_SERVICE_KEY in your .env file is incorrect.\n\n"
+                    "   To fix:\n"
+                    "   1. Go to https://app.supabase.com → Your Project → Settings → API\n"
+                    "   2. Find the 'service_role' key (NOT the 'anon' key)\n"
+                    "   3. Click 'Reveal' to show the full key\n"
+                    "   4. Copy the ENTIRE key (it's very long, ~200+ characters)\n"
+                    "   5. Update SUPABASE_SERVICE_KEY in your .env file\n"
+                    "   6. Make sure there are NO quotes, spaces, or line breaks\n\n"
+                    f"   Current key length: {len(key)} characters\n"
+                    f"   Expected: ~200+ characters (JWT token starting with 'eyJ')\n\n"
+                    f"   Error details: {error_msg}"
+                ) from e
+            else:
+                raise RuntimeError(
+                    f"❌ Failed to connect to Supabase: {error_msg}\n"
+                    "   Check that:\n"
+                    "   1. SUPABASE_URL is correct and complete\n"
+                    "   2. SUPABASE_SERVICE_KEY is the service_role key (not anon key)\n"
+                    "   3. Your Supabase project is active (not paused)\n"
+                    "   4. The tables exist (run supabase_admin_rules_table.sql and supabase_analytics_tables.sql)"
+                ) from e
+
+
+def sqlite_rows(db_path: Path, query: str) -> List[Dict[str, Any]]:
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    rows = conn.execute(query).fetchall()
+    conn.close()
+    return [dict(row) for row in rows]
+
+
+def warn_if_table_has_rows(client: Client, table: str) -> bool:
+    response = client.table(table).select("id", count="exact").limit(1).execute()
+    count = getattr(response, "count", None)
+    return bool(count and count > 0)
+
+
+def iso_from_unix(ts: Any) -> str | None:
+    if ts is None:
+        return None
+    try:
+        return datetime.fromtimestamp(int(ts), tz=timezone.utc).isoformat()
+    except (ValueError, TypeError):
+        return None
+
+
+def migrate_rules(client: Client, db_path: Path, force: bool):
+    table = "admin_rules"
+    if not force and warn_if_table_has_rows(client, table):
+        print(f"⚠️  Supabase table '{table}' already has rows. Skipping (use --force to override).")
+        return
+
+    if not db_path.exists():
+        print(f"ℹ️  No local rules database found at {db_path}, skipping rules migration.")
+        return
+
+    rows = sqlite_rows(
+        db_path,
+        """
+        SELECT tenant_id, rule, pattern, severity, description, enabled, created_at
+        FROM admin_rules
+        """,
+    )
+    if not rows:
+        print("ℹ️  No rules to migrate.")
+        return
+
+    payload = []
+    for row in rows:
+        payload.append(
+            {
+                "tenant_id": row["tenant_id"],
+                "rule": row["rule"],
+                "pattern": row["pattern"] or row["rule"],
+                "severity": row.get("severity") or "medium",
+                "description": row.get("description") or row["rule"],
+                "enabled": bool(row.get("enabled", 1)),
+                "created_at": iso_from_unix(row.get("created_at")) or None,
+            }
+        )
+
+    for batch in chunked(payload, BATCH_SIZE):
+        client.table(table).upsert(batch, on_conflict="tenant_id,rule").execute()
+
+    print(f"✅ Migrated {len(payload)} admin rule(s) to Supabase.")
+
+
+def migrate_tool_usage(client: Client, db_path: Path, force: bool):
+    table = "tool_usage_events"
+    if not force and warn_if_table_has_rows(client, table):
+        print(f"⚠️  Supabase table '{table}' already has rows. Skipping (use --force to override).")
+        return
+
+    rows = sqlite_rows(db_path, "SELECT * FROM tool_usage_events")
+    if not rows:
+        print("ℹ️  No tool usage events to migrate.")
+        return
+
+    payload = []
+    for row in rows:
+        metadata = row.get("metadata")
+        payload.append(
+            {
+                "tenant_id": row["tenant_id"],
+                "user_id": row.get("user_id"),
+                "tool_name": row["tool_name"],
+                "timestamp": row["timestamp"],
+                "latency_ms": row.get("latency_ms"),
+                "tokens_used": row.get("tokens_used"),
+                "success": bool(row.get("success", 1)),
+                "error_message": row.get("error_message"),
+                "metadata": json.loads(metadata) if metadata else None,
+            }
+        )
+
+    for batch in chunked(payload, BATCH_SIZE):
+        client.table(table).insert(batch).execute()
+
+    print(f"✅ Migrated {len(payload)} tool usage event(s).")
+
+
+def migrate_redflags(client: Client, db_path: Path, force: bool):
+    table = "redflag_violations"
+    if not force and warn_if_table_has_rows(client, table):
+        print(f"⚠️  Supabase table '{table}' already has rows. Skipping (use --force to override).")
+        return
+
+    rows = sqlite_rows(db_path, "SELECT * FROM redflag_violations")
+    if not rows:
+        print("ℹ️  No red-flag violations to migrate.")
+        return
+
+    payload = []
+    for row in rows:
+        payload.append(
+            {
+                "tenant_id": row["tenant_id"],
+                "user_id": row.get("user_id"),
+                "rule_id": row["rule_id"],
+                "rule_pattern": row.get("rule_pattern"),
+                "severity": row["severity"],
+                "matched_text": row.get("matched_text"),
+                "confidence": row.get("confidence"),
+                "message_preview": row.get("message_preview"),
+                "timestamp": row["timestamp"],
+            }
+        )
+
+    for batch in chunked(payload, BATCH_SIZE):
+        client.table(table).insert(batch).execute()
+
+    print(f"✅ Migrated {len(payload)} red-flag violation(s).")
+
+
+def migrate_rag_searches(client: Client, db_path: Path, force: bool):
+    table = "rag_search_events"
+    if not force and warn_if_table_has_rows(client, table):
+        print(f"⚠️  Supabase table '{table}' already has rows. Skipping (use --force to override).")
+        return
+
+    rows = sqlite_rows(db_path, "SELECT * FROM rag_search_events")
+    if not rows:
+        print("ℹ️  No RAG search events to migrate.")
+        return
+
+    payload = []
+    for row in rows:
+        payload.append(
+            {
+                "tenant_id": row["tenant_id"],
+                "query": row["query"],
+                "hits_count": row.get("hits_count"),
+                "avg_score": row.get("avg_score"),
+                "top_score": row.get("top_score"),
+                "timestamp": row["timestamp"],
+                "latency_ms": row.get("latency_ms"),
+            }
+        )
+
+    for batch in chunked(payload, BATCH_SIZE):
+        client.table(table).insert(batch).execute()
+
+    print(f"✅ Migrated {len(payload)} RAG search event(s).")
+
+
+def migrate_agent_queries(client: Client, db_path: Path, force: bool):
+    table = "agent_query_events"
+    if not force and warn_if_table_has_rows(client, table):
+        print(f"⚠️  Supabase table '{table}' already has rows. Skipping (use --force to override).")
+        return
+
+    rows = sqlite_rows(db_path, "SELECT * FROM agent_query_events")
+    if not rows:
+        print("ℹ️  No agent query events to migrate.")
+        return
+
+    payload = []
+    for row in rows:
+        tools = row.get("tools_used")
+        payload.append(
+            {
+                "tenant_id": row["tenant_id"],
+                "user_id": row.get("user_id"),
+                "message_preview": row.get("message_preview"),
+                "intent": row.get("intent"),
+                "tools_used": json.loads(tools) if tools else None,
+                "total_tokens": row.get("total_tokens"),
+                "total_latency_ms": row.get("total_latency_ms"),
+                "success": bool(row.get("success", 1)),
+                "timestamp": row["timestamp"],
+            }
+        )
+
+    for batch in chunked(payload, BATCH_SIZE):
+        client.table(table).insert(batch).execute()
+
+    print(f"✅ Migrated {len(payload)} agent query event(s).")
+
+
+def migrate_rules_postgres(conn, db_path: Path, force: bool, check_table_func):
+    """Migrate rules using PostgreSQL direct connection."""
+    table = "admin_rules"
+    
+    # Check if table exists
+    if not table_exists_postgres(conn, table):
+        print(f"❌ Table '{table}' does not exist in PostgreSQL!")
+        print(f"   Please create it first by running 'supabase_admin_rules_table.sql' in Supabase SQL Editor")
+        print(f"   Skipping rules migration.")
+        return
+    
+    if not force and check_table_func(table):
+        print(f"⚠️  Supabase table '{table}' already has rows. Skipping (use --force to override).")
+        return
+
+    if not db_path.exists():
+        print(f"ℹ️  No local rules database found at {db_path}, skipping rules migration.")
+        return
+
+    rows = sqlite_rows(
+        db_path,
+        """
+        SELECT tenant_id, rule, pattern, severity, description, enabled, created_at
+        FROM admin_rules
+        """,
+    )
+    if not rows:
+        print("ℹ️  No rules to migrate.")
+        return
+
+    payload = []
+    for row in rows:
+        payload.append({
+            "tenant_id": row["tenant_id"],
+            "rule": row["rule"],
+            "pattern": row["pattern"] or row["rule"],
+            "severity": row.get("severity") or "medium",
+            "description": row.get("description") or row["rule"],
+            "enabled": bool(row.get("enabled", 1)),
+            "created_at": iso_from_unix(row.get("created_at")) or None,
+        })
+
+    columns = ["tenant_id", "rule", "pattern", "severity", "description", "enabled", "created_at"]
+    for batch in chunked(payload, BATCH_SIZE):
+        insert_batch_postgres(conn, table, columns, batch, on_conflict="tenant_id,rule")
+
+    print(f"✅ Migrated {len(payload)} admin rule(s) to Supabase.")
+
+
+def migrate_tool_usage_postgres(conn, db_path: Path, force: bool, check_table_func):
+    """Migrate tool usage events using PostgreSQL direct connection."""
+    table = "tool_usage_events"
+    
+    if not table_exists_postgres(conn, table):
+        print(f"❌ Table '{table}' does not exist in PostgreSQL!")
+        print(f"   Please create it first by running 'supabase_analytics_tables.sql' in Supabase SQL Editor")
+        print(f"   Skipping tool usage migration.")
+        return
+    
+    if not force and check_table_func(table):
+        print(f"⚠️  Supabase table '{table}' already has rows. Skipping (use --force to override).")
+        return
+
+    rows = sqlite_rows(db_path, "SELECT * FROM tool_usage_events")
+    if not rows:
+        print("ℹ️  No tool usage events to migrate.")
+        return
+
+    payload = []
+    for row in rows:
+        metadata = row.get("metadata")
+        payload.append({
+            "tenant_id": row["tenant_id"],
+            "user_id": row.get("user_id"),
+            "tool_name": row["tool_name"],
+            "timestamp": row["timestamp"],
+            "latency_ms": row.get("latency_ms"),
+            "tokens_used": row.get("tokens_used"),
+            "success": bool(row.get("success", 1)),
+            "error_message": row.get("error_message"),
+            "metadata": json.loads(metadata) if metadata else None,
+        })
+
+    columns = ["tenant_id", "user_id", "tool_name", "timestamp", "latency_ms", "tokens_used", "success", "error_message", "metadata"]
+    for batch in chunked(payload, BATCH_SIZE):
+        insert_batch_postgres(conn, table, columns, batch)
+
+    print(f"✅ Migrated {len(payload)} tool usage event(s).")
+
+
+def migrate_redflags_postgres(conn, db_path: Path, force: bool, check_table_func):
+    """Migrate redflag violations using PostgreSQL direct connection."""
+    table = "redflag_violations"
+    
+    if not table_exists_postgres(conn, table):
+        print(f"❌ Table '{table}' does not exist in PostgreSQL!")
+        print(f"   Please create it first by running 'supabase_analytics_tables.sql' in Supabase SQL Editor")
+        print(f"   Skipping redflag migration.")
+        return
+    
+    if not force and check_table_func(table):
+        print(f"⚠️  Supabase table '{table}' already has rows. Skipping (use --force to override).")
+        return
+
+    rows = sqlite_rows(db_path, "SELECT * FROM redflag_violations")
+    if not rows:
+        print("ℹ️  No red-flag violations to migrate.")
+        return
+
+    payload = []
+    for row in rows:
+        payload.append({
+            "tenant_id": row["tenant_id"],
+            "user_id": row.get("user_id"),
+            "rule_id": row["rule_id"],
+            "rule_pattern": row.get("rule_pattern"),
+            "severity": row["severity"],
+            "matched_text": row.get("matched_text"),
+            "confidence": row.get("confidence"),
+            "message_preview": row.get("message_preview"),
+            "timestamp": row["timestamp"],
+        })
+
+    columns = ["tenant_id", "user_id", "rule_id", "rule_pattern", "severity", "matched_text", "confidence", "message_preview", "timestamp"]
+    for batch in chunked(payload, BATCH_SIZE):
+        insert_batch_postgres(conn, table, columns, batch)
+
+    print(f"✅ Migrated {len(payload)} red-flag violation(s).")
+
+
+def migrate_rag_searches_postgres(conn, db_path: Path, force: bool, check_table_func):
+    """Migrate RAG search events using PostgreSQL direct connection."""
+    table = "rag_search_events"
+    
+    if not table_exists_postgres(conn, table):
+        print(f"❌ Table '{table}' does not exist in PostgreSQL!")
+        print(f"   Please create it first by running 'supabase_analytics_tables.sql' in Supabase SQL Editor")
+        print(f"   Skipping RAG search migration.")
+        return
+    
+    if not force and check_table_func(table):
+        print(f"⚠️  Supabase table '{table}' already has rows. Skipping (use --force to override).")
+        return
+
+    rows = sqlite_rows(db_path, "SELECT * FROM rag_search_events")
+    if not rows:
+        print("ℹ️  No RAG search events to migrate.")
+        return
+
+    payload = []
+    for row in rows:
+        payload.append({
+            "tenant_id": row["tenant_id"],
+            "query": row["query"],
+            "hits_count": row.get("hits_count"),
+            "avg_score": row.get("avg_score"),
+            "top_score": row.get("top_score"),
+            "timestamp": row["timestamp"],
+            "latency_ms": row.get("latency_ms"),
+        })
+
+    columns = ["tenant_id", "query", "hits_count", "avg_score", "top_score", "timestamp", "latency_ms"]
+    for batch in chunked(payload, BATCH_SIZE):
+        insert_batch_postgres(conn, table, columns, batch)
+
+    print(f"✅ Migrated {len(payload)} RAG search event(s).")
+
+
+def migrate_agent_queries_postgres(conn, db_path: Path, force: bool, check_table_func):
+    """Migrate agent query events using PostgreSQL direct connection."""
+    table = "agent_query_events"
+    
+    if not table_exists_postgres(conn, table):
+        print(f"❌ Table '{table}' does not exist in PostgreSQL!")
+        print(f"   Please create it first by running 'supabase_analytics_tables.sql' in Supabase SQL Editor")
+        print(f"   Skipping agent query migration.")
+        return
+    
+    if not force and check_table_func(table):
+        print(f"⚠️  Supabase table '{table}' already has rows. Skipping (use --force to override).")
+        return
+
+    rows = sqlite_rows(db_path, "SELECT * FROM agent_query_events")
+    if not rows:
+        print("ℹ️  No agent query events to migrate.")
+        return
+
+    payload = []
+    for row in rows:
+        tools = row.get("tools_used")
+        payload.append({
+            "tenant_id": row["tenant_id"],
+            "user_id": row.get("user_id"),
+            "message_preview": row.get("message_preview"),
+            "intent": row.get("intent"),
+            "tools_used": json.loads(tools) if tools else None,
+            "total_tokens": row.get("total_tokens"),
+            "total_latency_ms": row.get("total_latency_ms"),
+            "success": bool(row.get("success", 1)),
+            "timestamp": row["timestamp"],
+        })
+
+    columns = ["tenant_id", "user_id", "message_preview", "intent", "tools_used", "total_tokens", "total_latency_ms", "success", "timestamp"]
+    for batch in chunked(payload, BATCH_SIZE):
+        insert_batch_postgres(conn, table, columns, batch)
+
+    print(f"✅ Migrated {len(payload)} agent query event(s).")
+
+
+def table_exists_postgres(conn, table: str) -> bool:
+    """Check if PostgreSQL table exists."""
+    with conn.cursor() as cur:
+        cur.execute("""
+            SELECT EXISTS (
+                SELECT FROM information_schema.tables 
+                WHERE table_schema = 'public' 
+                AND table_name = %s
+            )
+        """, (table,))
+        return cur.fetchone()[0]
+
+
+def check_table_has_rows_postgres(conn, table: str) -> bool:
+    """Check if PostgreSQL table has rows."""
+    if not table_exists_postgres(conn, table):
+        return False
+    try:
+        with conn.cursor() as cur:
+            cur.execute(f"SELECT COUNT(*) FROM {table}")
+            count = cur.fetchone()[0]
+            return count > 0
+    except Exception as e:
+        error_str = str(e)
+        if "does not exist" in error_str or "relation" in error_str.lower():
+            return False
+        raise
+
+
+def check_table_has_rows_supabase(client: Client, table: str) -> bool:
+    """Check if Supabase table has rows."""
+    try:
+        response = client.table(table).select("id", count="exact").limit(1).execute()
+        count = getattr(response, "count", None)
+        return bool(count and count > 0)
+    except:
+        return False
+
+
+def insert_batch_postgres(conn, table: str, columns: List[str], batch: List[Dict[str, Any]], on_conflict: str = None):
+    """Insert batch into PostgreSQL table."""
+    if not batch:
+        return
+    
+    placeholders = ", ".join(["%s"] * len(columns))
+    cols = ", ".join(columns)
+    
+    if on_conflict:
+        # For admin_rules with unique constraint
+        update_cols = ", ".join([f"{col} = EXCLUDED.{col}" for col in columns if col != "id"])
+        query = f"INSERT INTO {table} ({cols}) VALUES ({placeholders}) ON CONFLICT ({on_conflict}) DO UPDATE SET {update_cols}"
+    else:
+        query = f"INSERT INTO {table} ({cols}) VALUES ({placeholders})"
+    
+    # Prepare values, converting dicts/lists to JSON for JSONB columns
+    values = []
+    for row in batch:
+        row_values = []
+        for col in columns:
+            val = row.get(col)
+            # Convert dict/list to JSON string for JSONB columns
+            if col in ["metadata", "tools_used"] and val is not None:
+                if isinstance(val, (dict, list)):
+                    val = json.dumps(val)
+            row_values.append(val)
+        values.append(row_values)
+    
+    with conn.cursor() as cur:
+        execute_batch(cur, query, values)
+    conn.commit()
+
+
+def insert_batch_supabase(client: Client, table: str, batch: List[Dict[str, Any]], on_conflict: str = None):
+    """Insert batch into Supabase table."""
+    if not batch:
+        return
+    
+    if on_conflict:
+        client.table(table).upsert(batch, on_conflict=on_conflict).execute()
+    else:
+        for chunk in chunked(batch, BATCH_SIZE):
+            client.table(table).insert(chunk).execute()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Migrate SQLite analytics/rules data into Supabase.")
+    parser.add_argument("--force", action="store_true", help="Insert even if Supabase tables already contain rows.")
+    args = parser.parse_args()
+
+    print("=" * 70)
+    print("SQLite to Supabase Migration Tool")
+    print("=" * 70)
+    print()
+
+    # Check for SQLite databases first
+    root = Path(__file__).resolve().parent
+    data_dir = root / "data"
+    rules_db = data_dir / "admin_rules.db"
+    analytics_db = data_dir / "analytics.db"
+
+    print("📁 Checking for local SQLite databases:")
+    print(f"   Rules DB: {rules_db} {'✅' if rules_db.exists() else '❌ Not found'}")
+    print(f"   Analytics DB: {analytics_db} {'✅' if analytics_db.exists() else '❌ Not found'}")
+    print()
+
+    if not rules_db.exists() and not analytics_db.exists():
+        print("⚠️  No SQLite databases found. Nothing to migrate.")
+        return
+
+    # Determine connection method
+    print("🔐 Checking connection method...")
+    method = get_connection_method()
+    
+    if method == "postgresql":
+        print("   ✅ Using PostgreSQL direct connection (POSTGRESQL_URL)")
+        conn = get_postgres_connection()
+        print("   ✅ Connected to PostgreSQL")
+        client = None
+        check_table = lambda t: check_table_has_rows_postgres(conn, t)
+        
+        # Check if required tables exist
+        print()
+        print("📋 Checking if required tables exist...")
+        required_tables = {
+            "admin_rules": "supabase_admin_rules_table.sql",
+            "tool_usage_events": "supabase_analytics_tables.sql",
+            "redflag_violations": "supabase_analytics_tables.sql",
+            "rag_search_events": "supabase_analytics_tables.sql",
+            "agent_query_events": "supabase_analytics_tables.sql",
+        }
+        missing_tables = {}
+        for table, sql_file in required_tables.items():
+            if table_exists_postgres(conn, table):
+                print(f"   ✅ {table}")
+            else:
+                print(f"   ❌ {table} (missing)")
+                if sql_file not in missing_tables:
+                    missing_tables[sql_file] = []
+                missing_tables[sql_file].append(table)
+        
+        if missing_tables:
+            print()
+            print("⚠️  Some tables are missing! Please create them first:")
+            print()
+            for sql_file, tables in missing_tables.items():
+                print(f"   Run '{sql_file}' in Supabase SQL Editor to create:")
+                for table in tables:
+                    print(f"      - {table}")
+            print()
+            print("   Steps:")
+            print("   1. Go to https://app.supabase.com → Your Project → SQL Editor")
+            print("   2. Click 'New query'")
+            for sql_file in missing_tables.keys():
+                print(f"   3. Open and copy contents of '{sql_file}' from your project")
+                print("   4. Paste into SQL Editor and click 'Run'")
+            print("   5. Run this migration script again")
+            print()
+            conn.close()
+            return
+    elif method == "supabase":
+        print("   ✅ Using Supabase API (SUPABASE_URL + SUPABASE_SERVICE_KEY)")
+        client = load_supabase_client()
+        conn = None
+        check_table = lambda t: check_table_has_rows_supabase(client, t)
+    else:
+        print("   ❌ No connection method available!")
+        print()
+        print("   Please set one of the following in your .env file:")
+        print("   - POSTGRESQL_URL=postgresql://user:password@host:port/database")
+        print("     OR")
+        print("   - SUPABASE_URL=https://xxxxx.supabase.co")
+        print("   - SUPABASE_SERVICE_KEY=your_service_role_key")
+        return
+    
+    print()
+
+    print("🚀 Starting migration...")
+    print()
+
+    # Migrate using the appropriate method
+    if method == "postgresql":
+        migrate_rules_postgres(conn, rules_db, args.force, check_table)
+        migrate_tool_usage_postgres(conn, analytics_db, args.force, check_table)
+        migrate_redflags_postgres(conn, analytics_db, args.force, check_table)
+        migrate_rag_searches_postgres(conn, analytics_db, args.force, check_table)
+        migrate_agent_queries_postgres(conn, analytics_db, args.force, check_table)
+        conn.close()
+    else:
+        migrate_rules(client, rules_db, args.force)
+        migrate_tool_usage(client, analytics_db, args.force)
+        migrate_redflags(client, analytics_db, args.force)
+        migrate_rag_searches(client, analytics_db, args.force)
+        migrate_agent_queries(client, analytics_db, args.force)
+
+    print()
+    print("=" * 70)
+    print("🎉 Migration completed!")
+    print("=" * 70)
+    print()
+    print("💡 Next steps:")
+    print("   1. Verify data in Supabase Dashboard → Table Editor")
+    print("   2. Restart your FastAPI/MCP services to use Supabase backend")
+    print("   3. (Optional) Back up SQLite files before deleting them")
+
+
+if __name__ == "__main__":
+    main()
+

setup_env.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""
+Helper script to create or update .env file with Supabase credentials.
+"""
+
+import os
+from pathlib import Path
+
+def main():
+    print("=" * 70)
+    print("Supabase .env Setup Helper")
+    print("=" * 70)
+    print()
+    
+    env_file = Path(".env")
+    env_example = Path("env.example")
+    
+    # Check if .env already exists
+    if env_file.exists():
+        print("⚠️  .env file already exists!")
+        response = input("   Do you want to update it? (y/n): ").strip().lower()
+        if response != 'y':
+            print("   Skipping. Edit .env manually if needed.")
+            return
+        print()
+    
+    # Read existing .env if it exists
+    existing_vars = {}
+    if env_file.exists():
+        with open(env_file, 'r') as f:
+            for line in f:
+                line = line.strip()
+                if line and not line.startswith('#') and '=' in line:
+                    key, value = line.split('=', 1)
+                    existing_vars[key.strip()] = value.strip()
+    
+    print("Enter your Supabase credentials:")
+    print("(You can find these at: https://app.supabase.com → Your Project → Settings → API)")
+    print()
+    
+    # Get Supabase URL
+    current_url = existing_vars.get('SUPABASE_URL', '')
+    if current_url:
+        print(f"Current SUPABASE_URL: {current_url[:50]}...")
+        response = input("Keep current? (y/n): ").strip().lower()
+        if response == 'y':
+            supabase_url = current_url
+        else:
+            supabase_url = input("Enter SUPABASE_URL (https://xxxxx.supabase.co): ").strip()
+    else:
+        supabase_url = input("Enter SUPABASE_URL (https://xxxxx.supabase.co): ").strip()
+    
+    # Get Supabase Service Key
+    current_key = existing_vars.get('SUPABASE_SERVICE_KEY', '')
+    if current_key:
+        print(f"Current SUPABASE_SERVICE_KEY: {current_key[:20]}...")
+        response = input("Keep current? (y/n): ").strip().lower()
+        if response == 'y':
+            supabase_key = current_key
+        else:
+            supabase_key = input("Enter SUPABASE_SERVICE_KEY (service_role key): ").strip()
+    else:
+        supabase_key = input("Enter SUPABASE_SERVICE_KEY (service_role key): ").strip()
+    
+    # Validate
+    if not supabase_url.startswith('https://'):
+        print("⚠️  Warning: SUPABASE_URL should start with https://")
+    if not supabase_key.startswith('eyJ'):
+        print("⚠️  Warning: SUPABASE_SERVICE_KEY should start with 'eyJ' (JWT token)")
+    
+    print()
+    print("📝 Creating/updating .env file...")
+    
+    # Read env.example as template
+    lines = []
+    if env_example.exists():
+        with open(env_example, 'r') as f:
+            lines = f.readlines()
+    else:
+        # Create basic template
+        lines = [
+            "# IntegraChat Environment Variables\n",
+            "# Supabase Configuration\n",
+            "SUPABASE_URL=\n",
+            "SUPABASE_SERVICE_KEY=\n",
+        ]
+    
+    # Update or add Supabase variables
+    updated_lines = []
+    url_found = False
+    key_found = False
+    
+    for line in lines:
+        if line.startswith('SUPABASE_URL='):
+            updated_lines.append(f'SUPABASE_URL={supabase_url}\n')
+            url_found = True
+        elif line.startswith('SUPABASE_SERVICE_KEY='):
+            updated_lines.append(f'SUPABASE_SERVICE_KEY={supabase_key}\n')
+            key_found = True
+        else:
+            updated_lines.append(line)
+    
+    # Add if not found
+    if not url_found:
+        updated_lines.append(f'SUPABASE_URL={supabase_url}\n')
+    if not key_found:
+        updated_lines.append(f'SUPABASE_SERVICE_KEY={supabase_key}\n')
+    
+    # Write .env file
+    with open(env_file, 'w') as f:
+        f.writelines(updated_lines)
+    
+    print(f"✅ .env file created/updated at: {env_file.absolute()}")
+    print()
+    print("Next steps:")
+    print("1. Make sure your Supabase project is active (not paused)")
+    print("2. Create the tables in Supabase:")
+    print("   - Run supabase_admin_rules_table.sql in SQL Editor")
+    print("   - Run supabase_analytics_tables.sql in SQL Editor")
+    print("3. Test the connection:")
+    print("   python check_supabase_rules.py")
+    print("4. Run the migration:")
+    print("   python migrate_sqlite_to_supabase.py")
+
+if __name__ == "__main__":
+    main()
+

supabase_analytics_tables.sql

@@ -0,0 +1,102 @@
+-- =============================================================
+-- Supabase Table Schemas for Analytics Storage
+-- =============================================================
+-- Run this SQL in the Supabase SQL Editor to mirror the SQLite
+-- analytics schema (tool usage, red flags, RAG searches, queries)
+-- =============================================================
+
+CREATE TABLE IF NOT EXISTS tool_usage_events (
+    id BIGSERIAL PRIMARY KEY,
+    tenant_id TEXT NOT NULL,
+    user_id TEXT,
+    tool_name TEXT NOT NULL,
+    "timestamp" BIGINT NOT NULL,
+    latency_ms INTEGER,
+    tokens_used INTEGER,
+    success BOOLEAN DEFAULT TRUE,
+    error_message TEXT,
+    metadata JSONB
+);
+
+CREATE INDEX IF NOT EXISTS idx_tool_usage_tenant_timestamp
+    ON tool_usage_events (tenant_id, "timestamp");
+
+
+CREATE TABLE IF NOT EXISTS redflag_violations (
+    id BIGSERIAL PRIMARY KEY,
+    tenant_id TEXT NOT NULL,
+    user_id TEXT,
+    rule_id TEXT NOT NULL,
+    rule_pattern TEXT,
+    severity TEXT NOT NULL,
+    matched_text TEXT,
+    confidence DOUBLE PRECISION,
+    message_preview TEXT,
+    "timestamp" BIGINT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_redflag_tenant_timestamp
+    ON redflag_violations (tenant_id, "timestamp");
+
+
+CREATE TABLE IF NOT EXISTS rag_search_events (
+    id BIGSERIAL PRIMARY KEY,
+    tenant_id TEXT NOT NULL,
+    query TEXT NOT NULL,
+    hits_count INTEGER,
+    avg_score DOUBLE PRECISION,
+    top_score DOUBLE PRECISION,
+    "timestamp" BIGINT NOT NULL,
+    latency_ms INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_rag_search_tenant_timestamp
+    ON rag_search_events (tenant_id, "timestamp");
+
+
+CREATE TABLE IF NOT EXISTS agent_query_events (
+    id BIGSERIAL PRIMARY KEY,
+    tenant_id TEXT NOT NULL,
+    user_id TEXT,
+    message_preview TEXT,
+    intent TEXT,
+    tools_used JSONB,
+    total_tokens INTEGER,
+    total_latency_ms INTEGER,
+    success BOOLEAN DEFAULT TRUE,
+    "timestamp" BIGINT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_query_tenant_timestamp
+    ON agent_query_events (tenant_id, "timestamp");
+
+
+-- =============================================================
+-- Optional: Enable Row Level Security and service-role policy
+-- =============================================================
+ALTER TABLE tool_usage_events ENABLE ROW LEVEL SECURITY;
+ALTER TABLE redflag_violations ENABLE ROW LEVEL SECURITY;
+ALTER TABLE rag_search_events ENABLE ROW LEVEL SECURITY;
+ALTER TABLE agent_query_events ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "Service role can manage tool usage"
+    ON tool_usage_events FOR ALL
+    USING (true) WITH CHECK (true);
+
+CREATE POLICY "Service role can manage red flags"
+    ON redflag_violations FOR ALL
+    USING (true) WITH CHECK (true);
+
+CREATE POLICY "Service role can manage rag searches"
+    ON rag_search_events FOR ALL
+    USING (true) WITH CHECK (true);
+
+CREATE POLICY "Service role can manage agent queries"
+    ON agent_query_events FOR ALL
+    USING (true) WITH CHECK (true);
+
+-- =============================================================
+-- After running this script restart your FastAPI/MCP services
+-- so they detect the Supabase analytics backend.
+-- =============================================================
+

verify_supabase_key.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""
+Quick script to verify your Supabase API key format and connection.
+"""
+
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+url = os.getenv("SUPABASE_URL")
+key = os.getenv("SUPABASE_SERVICE_KEY")
+
+print("=" * 70)
+print("Supabase API Key Verification")
+print("=" * 70)
+print()
+
+if not url:
+    print("❌ SUPABASE_URL is not set in .env file")
+    exit(1)
+
+if not key:
+    print("❌ SUPABASE_SERVICE_KEY is not set in .env file")
+    exit(1)
+
+# Clean the key
+key = key.strip()
+
+print(f"📋 SUPABASE_URL: {url[:30]}...")
+print(f"📋 SUPABASE_SERVICE_KEY: {key[:20]}...{key[-10:] if len(key) > 30 else ''} ({len(key)} chars)")
+print()
+
+# Check key format
+issues = []
+
+if not key.startswith("eyJ"):
+    issues.append("❌ Key doesn't start with 'eyJ' (not a JWT token)")
+
+if len(key) < 100:
+    issues.append(f"❌ Key is too short ({len(key)} chars, expected ~200+)")
+
+if len(key) > 500:
+    issues.append(f"⚠️  Key is unusually long ({len(key)} chars)")
+
+if " " in key or "\n" in key or "\t" in key:
+    issues.append("❌ Key contains whitespace (spaces, newlines, tabs)")
+
+if key.startswith('"') or key.endswith('"'):
+    issues.append("❌ Key is wrapped in quotes (remove quotes from .env)")
+
+if key.startswith("'") or key.endswith("'"):
+    issues.append("❌ Key is wrapped in single quotes (remove quotes from .env)")
+
+if issues:
+    print("⚠️  Issues found with API key format:")
+    for issue in issues:
+        print(f"   {issue}")
+    print()
+else:
+    print("✅ Key format looks good!")
+    print()
+
+# Try to connect
+print("🔗 Testing connection to Supabase...")
+try:
+    from supabase import create_client
+    client = create_client(url, key)
+    
+    # Try a simple query
+    try:
+        client.table("admin_rules").select("id").limit(0).execute()
+        print("✅ Connection successful! API key is valid.")
+        print()
+        print("💡 Next steps:")
+        print("   1. Make sure tables exist (run SQL scripts in Supabase)")
+        print("   2. Run: python migrate_sqlite_to_supabase.py")
+    except Exception as e:
+        error_str = str(e)
+        if "Invalid API key" in error_str or "401" in error_str:
+            print("❌ Connection failed: Invalid API key")
+            print()
+            print("🔧 How to fix:")
+            print("   1. Go to https://app.supabase.com")
+            print("   2. Select your project")
+            print("   3. Go to Settings → API")
+            print("   4. Find 'service_role' key (NOT 'anon' key)")
+            print("   5. Click 'Reveal' to show the full key")
+            print("   6. Copy the ENTIRE key (it's very long)")
+            print("   7. Update SUPABASE_SERVICE_KEY in .env file")
+            print("   8. Make sure NO quotes or spaces around the value")
+        elif "does not exist" in error_str or "relation" in error_str.lower():
+            print("⚠️  Connection works, but table doesn't exist yet")
+            print("   This is OK - create tables first, then migrate")
+        else:
+            print(f"❌ Connection error: {error_str}")
+            
+except ImportError:
+    print("❌ Supabase Python client not installed")
+    print("   Run: pip install supabase")
+except Exception as e:
+    print(f"❌ Error: {e}")
+
+print()
+print("=" * 70)
+

verify_supabase_setup.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""
+Verification script to ensure Supabase is configured and will be used for all future data.
+Run this after migration to confirm everything is set up correctly.
+"""
+
+import os
+import sys
+from pathlib import Path
+from dotenv import load_dotenv
+
+# Add backend to path
+backend_dir = Path(__file__).resolve().parent
+sys.path.insert(0, str(backend_dir))
+
+load_dotenv()
+
+from backend.api.storage.rules_store import RulesStore
+from backend.api.storage.analytics_store import AnalyticsStore
+
+def main():
+    print("=" * 70)
+    print("Supabase Configuration Verification")
+    print("=" * 70)
+    print()
+    
+    # Check environment variables
+    print("1. Checking Environment Variables:")
+    postgres_url = os.getenv("POSTGRESQL_URL")
+    supabase_url = os.getenv("SUPABASE_URL")
+    supabase_key = os.getenv("SUPABASE_SERVICE_KEY")
+    
+    has_postgres = bool(postgres_url)
+    has_supabase_api = bool(supabase_url and supabase_key)
+    
+    if has_postgres:
+        masked = postgres_url[:30] + "..." + postgres_url[-20:] if len(postgres_url) > 50 else postgres_url
+        print(f"   ✅ POSTGRESQL_URL is set: {masked}")
+    else:
+        print("   ❌ POSTGRESQL_URL is not set")
+    
+    if supabase_url:
+        print(f"   ✅ SUPABASE_URL is set: {supabase_url[:50]}...")
+    else:
+        print("   ❌ SUPABASE_URL is not set")
+    
+    if supabase_key:
+        if len(supabase_key) > 100:
+            print(f"   ✅ SUPABASE_SERVICE_KEY is set: {supabase_key[:20]}... ({len(supabase_key)} chars)")
+        else:
+            print(f"   ⚠️  SUPABASE_SERVICE_KEY seems incomplete ({len(supabase_key)} chars, expected 200+)")
+    else:
+        print("   ❌ SUPABASE_SERVICE_KEY is not set")
+    
+    print()
+    
+    # Check RulesStore
+    print("2. Checking RulesStore Configuration:")
+    try:
+        rules_store = RulesStore()
+        if rules_store.use_supabase:
+            print("   ✅ RulesStore is using Supabase")
+            print(f"   📦 Backend: Supabase (REST API)")
+        else:
+            print("   ❌ RulesStore is using SQLite (not Supabase)")
+            print("   ⚠️  Future rules will be saved to SQLite, not Supabase!")
+            print()
+            print("   To fix:")
+            print("   - Set SUPABASE_URL and SUPABASE_SERVICE_KEY in .env")
+    except Exception as e:
+        print(f"   ❌ Error initializing RulesStore: {e}")
+    
+    print()
+    
+    # Check AnalyticsStore
+    print("3. Checking AnalyticsStore Configuration:")
+    try:
+        analytics_store = AnalyticsStore()
+        if analytics_store.use_supabase:
+            print("   ✅ AnalyticsStore is using Supabase")
+            print(f"   📦 Backend: Supabase (REST API)")
+        else:
+            print("   ❌ AnalyticsStore is using SQLite (not Supabase)")
+            print("   ⚠️  Future analytics will be saved to SQLite, not Supabase!")
+            print()
+            print("   To fix:")
+            if has_postgres:
+                print("   - POSTGRESQL_URL is set, but AnalyticsStore needs SUPABASE_URL + SUPABASE_SERVICE_KEY")
+            else:
+                print("   - Set SUPABASE_URL and SUPABASE_SERVICE_KEY in .env")
+    except Exception as e:
+        print(f"   ❌ Error initializing AnalyticsStore: {e}")
+    
+    print()
+    
+    # Summary
+    print("4. Summary:")
+    rules_ok = rules_store.use_supabase if 'rules_store' in locals() else False
+    analytics_ok = analytics_store.use_supabase if 'analytics_store' in locals() else False
+    
+    if rules_ok and analytics_ok:
+        print("   ✅ All systems configured to use Supabase!")
+        print("   ✅ Future data will be saved to Supabase")
+        print()
+        print("   💡 Next steps:")
+        print("   1. Restart your FastAPI/MCP services to apply changes")
+        print("   2. Test by adding a rule or generating analytics")
+        print("   3. Verify data appears in Supabase Dashboard → Table Editor")
+    elif rules_ok or analytics_ok:
+        print("   ⚠️  Partial configuration:")
+        if rules_ok:
+            print("   ✅ Rules will use Supabase")
+        else:
+            print("   ❌ Rules will use SQLite")
+        if analytics_ok:
+            print("   ✅ Analytics will use Supabase")
+        else:
+            print("   ❌ Analytics will use SQLite")
+        print()
+        print("   To fully migrate to Supabase:")
+        print("   - Ensure SUPABASE_URL and SUPABASE_SERVICE_KEY are set in .env")
+        print("   - Restart your services")
+    else:
+        print("   ❌ Not configured for Supabase")
+        print("   ⚠️  All data will be saved to SQLite")
+        print()
+        print("   To migrate to Supabase:")
+        print("   1. Set SUPABASE_URL and SUPABASE_SERVICE_KEY in .env")
+        print("   2. Restart your services")
+        print("   3. Run this verification again")
+    
+    print()
+    print("=" * 70)
+
+if __name__ == "__main__":
+    main()
+