Upload folder using huggingface_hub

Dockerfile

@@ -1,11 +1,7 @@
 FROM python:3.12-slim
 RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
 WORKDIR /app
-
-ARG CLASSIC_TOKEN=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
-RUN git config --global url."https://x-access-token:${CLASSIC_TOKEN}@github.com/".insteadOf "https://github.com/"
-
 COPY requirements.txt .
 RUN pip install --no-cache-dir -r requirements.txt
 COPY . .
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,9 +1,3 @@
----
-title: ARF API Control Plane
-sdk: docker
-colorFrom: blue
-colorTo: green
----
 # arf-api
 
 ARF API Control Plane (FastAPI)
@@ -87,7 +81,7 @@ curl -X POST "http://localhost:8000/api/v1/v1/incidents/evaluate"   -H "Content-
     "justification": "Causal: If we apply restart_container instead of no_action, latency would change from 600.00 to 510.00 (Δ = -90.00). Based on heuristic causal model.",
     "confidence": 0.85,
     "risk_score": 0.54,
-    "status": "oss_advisory_only"
+    "status": "success"
   },
   "causal_explanation": {
     "factual_outcome": 600,
@@ -123,4 +117,5 @@ Notes
 -----
 
 - The governance endpoints use an in-process `RiskEngine` initialized at startup.
-- The outcome recording endpoint is not implemented in this repository and returns HTTP 501.
+- The outcome recording endpoint is not implemented in this repository and returns HTTP 501.
+

app/api/routes_incidents.py

@@ -198,7 +198,7 @@ async def evaluate_incident(
             ),
             "confidence": 1.0 - result.get("uncertainty", 0.0),
             "risk_score": result["risk_score"],
-            "status": "oss_advisory_only",
+            "status": "success",
         }
 
         response_data = {

app/core/usage_tracker.py

@@ -1,8 +1,10 @@
 """
 Usage Tracker for ARF API – quotas, tiers, and audit logging.
 Thread‑safe, atomic quota consumption, idempotent, fail‑closed.
-"""
 
+Extended for multi‑tenancy: each API key is linked to a tenant ID.
+Tenant ID is stored in the `api_keys` table and used for resource isolation.
+"""
 import json
 import sqlite3
 import threading
@@ -10,7 +12,7 @@ import time
 from contextlib import contextmanager
 from datetime import datetime, timedelta
 from dataclasses import dataclass
-from typing import Dict, Any, Optional, List, Tuple
+from typing import Dict, Any, Optional, List, Tuple, Callable
 from enum import Enum
 from fastapi import BackgroundTasks, HTTPException, Request
 
@@ -24,6 +26,7 @@ except ImportError:
 
 
 class Tier(str, Enum):
+    """Pricing tiers with associated quota limits and audit retention."""
     FREE = "free"
     PRO = "pro"
     PREMIUM = "premium"
@@ -31,16 +34,18 @@ class Tier(str, Enum):
 
     @property
     def monthly_evaluation_limit(self) -> Optional[int]:
+        """Monthly evaluation quota. None = unlimited."""
         limits = {
             Tier.FREE: 1000,
             Tier.PRO: 10_000,
             Tier.PREMIUM: 50_000,
-            Tier.ENTERPRISE: None,  # unlimited
+            Tier.ENTERPRISE: None,
         }
         return limits[self]
 
     @property
     def audit_log_retention_days(self) -> int:
+        """How many days to keep usage and decision audit logs."""
         retention = {
             Tier.FREE: 7,
             Tier.PRO: 30,
@@ -52,7 +57,7 @@ class Tier(str, Enum):
 
 @dataclass
 class UsageRecord:
-    """Single evaluation usage record."""
+    """Single API call usage record (for quota and debugging)."""
     api_key: str
     tier: Tier
     timestamp: float
@@ -66,6 +71,7 @@ class UsageRecord:
 class UsageTracker:
     """
     Thread‑safe usage tracker with atomic quota consumption and idempotency.
+    Extended to support tenant isolation: each API key is linked to a tenant.
     """
 
     def __init__(self, db_path: str = "arf_usage.db",
@@ -78,12 +84,11 @@ class UsageTracker:
         if redis_url and REDIS_AVAILABLE:
             self._redis_client = redis.from_url(redis_url)
         elif redis_url:
-            raise ImportError(
-                "Redis client not installed. Run: pip install redis")
+            raise ImportError("Redis client not installed. Run: pip install redis")
 
     @contextmanager
     def _get_conn(self):
-        """Get a thread‑local SQLite connection with write‑ahead logging and immediate transactions."""
+        """Get a thread‑local SQLite connection with WAL and immediate transactions."""
         if not hasattr(self._local, "conn"):
             self._local.conn = sqlite3.connect(
                 self.db_path, check_same_thread=False, isolation_level=None)
@@ -92,10 +97,13 @@ class UsageTracker:
         yield self._local.conn
 
     def _init_db(self):
+        """Initialise SQLite tables with tenant_id support."""
         with self._get_conn() as conn:
+            # Modified: api_keys now has tenant_id column
             conn.execute("""
                 CREATE TABLE IF NOT EXISTS api_keys (
                     key TEXT PRIMARY KEY,
+                    tenant_id TEXT NOT NULL,
                     tier TEXT NOT NULL,
                     created_at REAL NOT NULL,
                     last_used_at REAL,
@@ -139,16 +147,31 @@ class UsageTracker:
     def _get_month_key(self) -> str:
         return datetime.now().strftime("%Y-%m")
 
-    def get_or_create_api_key(self, key: str, tier: Tier = Tier.FREE) -> bool:
-        """Register a new API key. Returns True if key exists or was created."""
+    def get_or_create_api_key(self, key: str, tenant_id: str, tier: Tier = Tier.FREE) -> bool:
+        """
+        Register a new API key for a given tenant.
+
+        Args:
+            key: The API key (plain text, will be hashed in production).
+            tenant_id: UUID of the tenant (must already exist in main DB).
+            tier: Initial tier for the key.
+
+        Returns:
+            True if key was created (or already exists for the same tenant).
+        """
         with self._get_conn() as conn:
             row = conn.execute(
                 "SELECT key FROM api_keys WHERE key = ?", (key,)).fetchone()
             if row:
+                # Key already exists – ensure it belongs to the same tenant
+                existing_tenant = conn.execute(
+                    "SELECT tenant_id FROM api_keys WHERE key = ?", (key,)).fetchone()
+                if existing_tenant["tenant_id"] != tenant_id:
+                    raise ValueError(f"Key {key[:8]}... already belongs to a different tenant.")
                 return True
             conn.execute(
-                "INSERT INTO api_keys (key, tier, created_at, is_active) VALUES (?, ?, ?, ?)",
-                (key, tier.value, time.time(), 1)
+                "INSERT INTO api_keys (key, tenant_id, tier, created_at, is_active) VALUES (?, ?, ?, ?, ?)",
+                (key, tenant_id, tier.value, time.time(), 1)
             )
             conn.commit()
             return True
@@ -164,6 +187,17 @@ class UsageTracker:
                 return None
             return Tier(row["tier"])
 
+    def get_tenant_id(self, api_key: str) -> Optional[str]:
+        """Return the tenant ID associated with the API key, or None if key invalid."""
+        with self._get_conn() as conn:
+            row = conn.execute(
+                "SELECT tenant_id FROM api_keys WHERE key = ? AND is_active = 1",
+                (api_key,)
+            ).fetchone()
+            if not row:
+                return None
+            return row["tenant_id"]
+
     def update_api_key_tier(self, api_key: str, new_tier: Tier) -> bool:
         """Update the tier of an existing API key. Returns True if successful."""
         with self._get_conn() as conn:
@@ -173,41 +207,28 @@ class UsageTracker:
                 return False
             conn.execute(
                 "UPDATE api_keys SET tier = ? WHERE key = ?",
-                (new_tier.value,
-                 api_key))
+                (new_tier.value, api_key))
             conn.commit()
             return True
 
     # --------------------------------------------------------------------------
-    # Atomic quota consumption
+    # Atomic quota consumption (unchanged, but uses api_key which links to tenant)
     # --------------------------------------------------------------------------
-    def _consume_quota_atomic_sqlite(
-            self,
-            api_key: str,
-            tier: Tier,
-            month: str) -> bool:  # noqa: E501
-        """
-        Atomically increment counter only if under limit.
-        Returns True if quota was consumed, False if limit reached.
-        """
+    def _consume_quota_atomic_sqlite(self, api_key: str, tier: Tier, month: str) -> bool:
         limit = tier.monthly_evaluation_limit
         if limit is None:
-            # Unlimited – still increment for tracking but always succeed
             with self._get_conn() as conn:
                 conn.execute(
-                    """INSERT INTO monthly_counts (api_key, year_month, count)
-                       VALUES (?, ?, 1)
-                       ON CONFLICT(api_key, year_month) DO UPDATE SET count = count + 1""",
+                    "INSERT INTO monthly_counts (api_key, year_month, count) VALUES (?, ?, 1) "
+                    "ON CONFLICT(api_key, year_month) DO UPDATE SET count = count + 1",
                     (api_key, month)
                 )
                 conn.commit()
             return True
 
-        # Use BEGIN IMMEDIATE to lock the database for the transaction
         with self._get_conn() as conn:
             conn.execute("BEGIN IMMEDIATE")
             try:
-                # Get current count (or 0)
                 row = conn.execute(
                     "SELECT count FROM monthly_counts WHERE api_key = ? AND year_month = ?",
                     (api_key, month)
@@ -216,11 +237,9 @@ class UsageTracker:
                 if current >= limit:
                     conn.rollback()
                     return False
-                # Increment
                 conn.execute(
-                    """INSERT INTO monthly_counts (api_key, year_month, count)
-                       VALUES (?, ?, 1)
-                       ON CONFLICT(api_key, year_month) DO UPDATE SET count = count + 1""",
+                    "INSERT INTO monthly_counts (api_key, year_month, count) VALUES (?, ?, 1) "
+                    "ON CONFLICT(api_key, year_month) DO UPDATE SET count = count + 1",
                     (api_key, month)
                 )
                 conn.commit()
@@ -229,15 +248,9 @@ class UsageTracker:
                 conn.rollback()
                 raise
 
-    def _consume_quota_atomic_redis(
-            self,
-            api_key: str,
-            tier: Tier,
-            month: str) -> bool:
-        """Atomic Lua script for Redis: INCR only if below limit."""
+    def _consume_quota_atomic_redis(self, api_key: str, tier: Tier, month: str) -> bool:
         limit = tier.monthly_evaluation_limit
         if limit is None:
-            # Unlimited – just increment and return True
             redis_key = f"arf:quota:{api_key}:{month}"
             self._redis_client.incr(redis_key)
             self._redis_client.expire(redis_key, timedelta(days=31))
@@ -251,7 +264,7 @@ class UsageTracker:
             return 0
         end
         local new = redis.call('INCR', key)
-        redis.call('EXPIRE', key, 2678400)  -- 31 days
+        redis.call('EXPIRE', key, 2678400)
         return 1
         """
         redis_key = f"arf:quota:{api_key}:{month}"
@@ -259,144 +272,83 @@ class UsageTracker:
         return result == 1
 
     # --------------------------------------------------------------------------
-    # Idempotency handling
+    # Idempotency handling (unchanged)
     # --------------------------------------------------------------------------
     def _is_idempotent_key_used(self, key: str) -> bool:
-        """Check if idempotency key already processed."""
         with self._get_conn() as conn:
             row = conn.execute(
                 "SELECT 1 FROM idempotency_keys WHERE key = ?", (key,)).fetchone()
             return row is not None
 
     def _mark_idempotent_key_used(self, key: str, ttl_seconds: int = 86400):
-        """Store idempotency key with expiration (cleanup later)."""
         with self._get_conn() as conn:
             conn.execute(
                 "INSERT INTO idempotency_keys (key, consumed_at) VALUES (?, ?)",
                 (key, time.time())
             )
             conn.commit()
-        # Optionally schedule cleanup of old keys (can be done in a background
-        # thread)
 
     # --------------------------------------------------------------------------
-    # Core usage recording (atomic + idempotent)
+    # Core usage recording (atomic + idempotent) – unchanged
     # --------------------------------------------------------------------------
-    def consume_quota_and_log(
-        self,
-        record: UsageRecord,
-        idempotency_key: Optional[str] = None,
-    ) -> Tuple[bool, Optional[Dict[str, Any]]]:
-        """
-        Atomically consume quota and insert audit log.
-        Returns (success, existing_response) where existing_response is not None
-        only when idempotency_key matched a previous successful call.
-        """
-        # Idempotency check (if key provided)
-        if idempotency_key:
-            if self._is_idempotent_key_used(idempotency_key):
-                # Retrieve previous response from audit log (simplified – you may cache full response)
-                # For full idempotency, we would store the response body in idempotency table.
-                # Here we return a marker that caller should use cached
-                # response.
-                return False, {"idempotent": True,
-                               "message": "Already processed"}
+    def consume_quota_and_log(self, record: UsageRecord, idempotency_key: Optional[str] = None
+                              ) -> Tuple[bool, Optional[Dict[str, Any]]]:
+        if idempotency_key and self._is_idempotent_key_used(idempotency_key):
+            return False, {"idempotent": True, "message": "Already processed"}
 
         month = self._get_month_key()
-        # Atomic quota consumption
         if self._redis_client:
-            quota_ok = self._consume_quota_atomic_redis(
-                record.api_key, record.tier, month)
+            quota_ok = self._consume_quota_atomic_redis(record.api_key, record.tier, month)
         else:
-            quota_ok = self._consume_quota_atomic_sqlite(
-                record.api_key, record.tier, month)
+            quota_ok = self._consume_quota_atomic_sqlite(record.api_key, record.tier, month)
 
         if not quota_ok:
             return False, None
 
-        # Insert audit log (with idempotency key as unique constraint)
         try:
             with self._get_conn() as conn:
                 conn.execute(
                     """INSERT INTO usage_log
-                       (api_key, tier, timestamp, endpoint,
-                        request_body, response, error, processing_ms,
-                        idempotency_key)
+                       (api_key, tier, timestamp, endpoint, request_body, response, error, processing_ms, idempotency_key)
                        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""",
-                    (record.api_key,
-                     record.tier.value,
-                     record.timestamp,
-                     record.endpoint,
-                     json.dumps(
-                         record.request_body) if record.request_body else None,
-                        json.dumps(
-                         record.response) if record.response else None,
-                        record.error,
-                        record.processing_ms,
-                        idempotency_key,
-                     ))
+                    (record.api_key, record.tier.value, record.timestamp, record.endpoint,
+                     json.dumps(record.request_body) if record.request_body else None,
+                     json.dumps(record.response) if record.response else None,
+                     record.error, record.processing_ms, idempotency_key)
+                )
                 conn.commit()
         except sqlite3.IntegrityError as e:
-            # Duplicate idempotency_key – already inserted by another
-            # concurrent request
             if "UNIQUE constraint failed: usage_log.idempotency_key" in str(e):
-                return False, {"idempotent": True,
-                               "message": "Already processed"}
+                return False, {"idempotent": True, "message": "Already processed"}
             raise
 
         if idempotency_key:
             self._mark_idempotent_key_used(idempotency_key)
-        # Removed stray # noqa: E501 comment that was wrongly indented here
         return True, None
 
     # --------------------------------------------------------------------------
-    # Legacy interface (kept for compatibility but deprecated)
+    # Legacy interface (kept for compatibility)
     # --------------------------------------------------------------------------
-    def increment_usage_sync(
-            self,
-            record: UsageRecord,
-            idempotency_key: Optional[str] = None) -> bool:
-        """
-        Synchronously record usage and increment counter.
-        Returns True if within quota and recorded, False otherwise.
-        This method now uses the atomic implementation.
-        """
+    def increment_usage_sync(self, record: UsageRecord, idempotency_key: Optional[str] = None) -> bool:
         success, _ = self.consume_quota_and_log(record, idempotency_key)
         return success
 
-    async def increment_usage_async(
-        self,
-        record: UsageRecord,
-        background_tasks: BackgroundTasks,
-        idempotency_key: Optional[str] = None
-    ) -> bool:
-        """
-        Asynchronously record usage using FastAPI BackgroundTasks.
-        Still does the atomic check synchronously, then schedules the insert.
-        """
-        # First, do atomic quota check (synchronous) – we must ensure we don't double-consume.
-        # Because background tasks may run later, we still need to reserve quota now.
-        # Simplified: we call consume_quota_and_log synchronously – that defeats async benefit.
-        # Better to use a queue or Redis with background processing.
-        # For this fix, we'll use the sync method (blocking) but still support
-        # idempotency.
+    async def increment_usage_async(self, record: UsageRecord, background_tasks: BackgroundTasks,
+                                    idempotency_key: Optional[str] = None) -> bool:
         return self.increment_usage_sync(record, idempotency_key)
 
     # --------------------------------------------------------------------------
-    # Quota inspection (non‑atomic, for display only)
+    # Quota inspection
     # --------------------------------------------------------------------------
     def get_remaining_quota(self, api_key: str, tier: Tier) -> Optional[int]:
-        """Return remaining evaluations for the month (non‑atomic, for info only)."""
         limit = tier.monthly_evaluation_limit
         if limit is None:
             return None
-
         month = self._get_month_key()
         if self._redis_client:
             redis_key = f"arf:quota:{api_key}:{month}"
             count = int(self._redis_client.get(redis_key) or 0)
             return max(0, limit - count)
-
         with self._get_conn() as conn:
             row = conn.execute(
                 "SELECT count FROM monthly_counts WHERE api_key = ? AND year_month = ?",
@@ -406,16 +358,10 @@ class UsageTracker:
             return max(0, limit - count)
 
     # --------------------------------------------------------------------------
-    # Audit and maintenance
+    # Audit and maintenance (kept for usage_log)
     # --------------------------------------------------------------------------
-    def get_audit_logs(
-        self,
-        api_key: str,
-        start_date: Optional[datetime] = None,
-        end_date: Optional[datetime] = None,
-        limit: int = 100,
-    ) -> List[Dict[str, Any]]:
-        """Retrieve audit logs for a given API key."""
+    def get_audit_logs(self, api_key: str, start_date: Optional[datetime] = None,
+                       end_date: Optional[datetime] = None, limit: int = 100) -> List[Dict[str, Any]]:
         query = "SELECT * FROM usage_log WHERE api_key = ?"
         params = [api_key]
         if start_date:
@@ -426,47 +372,36 @@ class UsageTracker:
             params.append(end_date.timestamp())
         query += " ORDER BY timestamp DESC LIMIT ?"
         params.append(limit)
-
         with self._get_conn() as conn:
             rows = conn.execute(query, params).fetchall()
             return [dict(row) for row in rows]
 
     def clean_old_logs(self):
-        """Delete logs older than retention period for each tier, and old idempotency keys."""
         with self._get_conn() as conn:
-            # Delete old usage logs
             for tier in Tier:
                 retention_days = tier.audit_log_retention_days
-                if retention_days is None:
-                    continue
                 cutoff = time.time() - retention_days * 86400
                 conn.execute(
                     "DELETE FROM usage_log WHERE tier = ? AND timestamp < ?",
                     (tier.value, cutoff)
                 )
-            # Delete idempotency keys older than 7 days
             cutoff = time.time() - 7 * 86400
-            conn.execute(
-                "DELETE FROM idempotency_keys WHERE consumed_at < ?", (cutoff,))
+            conn.execute("DELETE FROM idempotency_keys WHERE consumed_at < ?", (cutoff,))
             conn.commit()
 
 
 # --------------------------------------------------------------------------
-# Global instance and FastAPI dependency (fail‑closed)
+# Global instance and FastAPI dependency
 # --------------------------------------------------------------------------
 tracker: Optional[UsageTracker] = None
 
 
-def init_tracker(
-        db_path: str = "arf_usage.db",
-        redis_url: Optional[str] = None):
-    """Initialize the global tracker. Must be called before enforce_quota."""
+def init_tracker(db_path: str = "arf_usage.db", redis_url: Optional[str] = None):
     global tracker
     tracker = UsageTracker(db_path, redis_url)
 
 
 def update_key_tier(api_key: str, new_tier: Tier) -> bool:
-    """Globally accessible helper to update API key tier."""
     if tracker is None:
         return False
     return tracker.update_api_key_tier(api_key, new_tier)
@@ -474,16 +409,11 @@ def update_key_tier(api_key: str, new_tier: Tier) -> bool:
 
 async def enforce_quota(request: Request, api_key: str = None):
     """
-    Dependency that checks API key and remaining quota.
-    FAILS CLOSED: if tracker not initialised, raises HTTP 503.
+    FastAPI dependency that enforces quota and attaches tenant_id to request state.
     """
-    # P0 fix: No fallback that allows all requests
     if tracker is None:
-        raise HTTPException(
-            status_code=503,
-            detail="Usage tracking service not initialised. Please contact administrator.")
+        raise HTTPException(status_code=503, detail="Usage tracking service not initialised.")
 
-    # Extract API key from header or query
     if api_key is None:
         auth_header = request.headers.get("Authorization")
         if auth_header and auth_header.startswith("Bearer "):
@@ -496,16 +426,19 @@ async def enforce_quota(request: Request, api_key: str = None):
 
     tier = tracker.get_tier(api_key)
     if tier is None:
-        raise HTTPException(
-            status_code=403,
-            detail="Invalid or inactive API key")
+        raise HTTPException(status_code=403, detail="Invalid or inactive API key")
 
     remaining = tracker.get_remaining_quota(api_key, tier)
     if remaining is not None and remaining <= 0:
-        raise HTTPException(status_code=429,
-                            detail="Monthly evaluation quota exceeded")
+        raise HTTPException(status_code=429, detail="Monthly evaluation quota exceeded")
+
+    # Retrieve tenant_id
+    tenant_id = tracker.get_tenant_id(api_key)
+    if not tenant_id:
+        raise HTTPException(status_code=403, detail="API key not associated with a tenant")
 
-    # Store in request state for later logging (optional)
     request.state.api_key = api_key
     request.state.tier = tier
-    return {"api_key": api_key, "tier": tier, "remaining": remaining}
+    request.state.tenant_id = tenant_id
+
+    return {"api_key": api_key, "tier": tier, "tenant_id": tenant_id, "remaining": remaining}

app/database/models_intents.py

@@ -1,50 +1,149 @@
-from sqlalchemy import Column, Integer, String, DateTime, Boolean, Text, JSON, Float, ForeignKey, UniqueConstraint
+"""
+Database models for the ARF API Control Plane.
+
+This module defines the SQLAlchemy ORM models for:
+    - Intents (InfrastructureIntent evaluations)
+    - Outcomes (recorded results of executed intents)
+    - Beta state (conjugate Bayesian posteriors per tenant and category)
+    - Audit logs (immutable decision records for compliance)
+    - Tenants (multi‑tenant isolation)
+
+All tables include a `tenant_id` column to enforce data partitioning.
+The BetaStateDB now stores parameters per (tenant, category) pair.
+"""
+
+from sqlalchemy import (
+    Column, Integer, String, DateTime, Boolean, Text, JSON,
+    Float, ForeignKey, UniqueConstraint, Index
+)
 from sqlalchemy.orm import relationship
 import datetime
 from .base import Base
 
 
+# ============================================================================
+# Tenant table – root of multi‑tenancy
+# ============================================================================
+
+class TenantDB(Base):
+    """
+    Represents a customer tenant (organisation). All other tables
+    reference this table via a foreign key `tenant_id`.
+
+    Attributes:
+        id (str): UUID of the tenant (primary key).
+        name (str): Human‑readable organisation name.
+        created_at (datetime): UTC timestamp of creation.
+        created_by (str, optional): Email or user ID of the creator.
+    """
+    __tablename__ = "tenants"
+
+    id = Column(String(64), primary_key=True, index=True)
+    name = Column(String(256), nullable=False)
+    created_at = Column(DateTime, default=datetime.datetime.utcnow, nullable=False)
+    created_by = Column(String(128), nullable=True)
+
+    # Relationships
+    api_keys = relationship("APIKeyDB", back_populates="tenant", cascade="all, delete-orphan")
+    intents = relationship("IntentDB", back_populates="tenant")
+    beta_states = relationship("BetaStateDB", back_populates="tenant")
+    audit_logs = relationship("DecisionAuditLogDB", back_populates="tenant")
+
+
+# ============================================================================
+# API keys (extended with tenant_id)
+# ============================================================================
+
+class APIKeyDB(Base):
+    """
+    Stores API keys for authentication and tiered quota. Each key belongs
+    to exactly one tenant. The `tier` determines monthly evaluation limits.
+
+    Attributes:
+        key (str): The hashed API key (primary key).
+        tenant_id (str): Foreign key to `tenants.id`.
+        tier (str): Tier enumeration value (free, pro, premium, enterprise).
+        created_at (datetime): UTC creation time.
+        last_used_at (datetime, optional): Timestamp of last successful request.
+        is_active (bool): Soft‑delete flag.
+    """
+    __tablename__ = "api_keys"
+
+    key = Column(String(256), primary_key=True, index=True)
+    tenant_id = Column(String(64), ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False, index=True)
+    tier = Column(String(32), nullable=False)
+    created_at = Column(DateTime, default=datetime.datetime.utcnow, nullable=False)
+    last_used_at = Column(DateTime, nullable=True)
+    is_active = Column(Boolean, default=True, nullable=False)
+
+    # Relationships
+    tenant = relationship("TenantDB", back_populates="api_keys")
+    usage_logs = relationship("UsageLogDB", back_populates="api_key")
+
+
+# ============================================================================
+# Intents (evaluations) – now tenant‑scoped
+# ============================================================================
+
 class IntentDB(Base):
+    """
+    Stores each InfrastructureIntent evaluation request and its resulting
+    risk score. One‑to‑many with OutcomeDB.
+
+    Attributes:
+        id (int): Auto‑increment primary key.
+        deterministic_id (str): Client‑provided idempotency identifier (unique).
+        tenant_id (str): Tenant that owns this intent.
+        intent_type (str): Type of intent (e.g., "provision_resource").
+        payload (JSON): Original API request payload.
+        oss_payload (JSON): Canonical OSS intent representation.
+        environment (str, optional): Environment label (prod, staging, etc.).
+        created_at (datetime): UTC timestamp of evaluation.
+        evaluated_at (datetime, optional): When the risk engine processed it.
+        risk_score (str, optional): String representation of the risk score.
+    """
     __tablename__ = "intents"
+
     id = Column(Integer, primary_key=True, index=True)
-    deterministic_id = Column(
-        String(64),
-        unique=True,
-        index=True,
-        nullable=False)
+    deterministic_id = Column(String(64), unique=True, index=True, nullable=False)
+    tenant_id = Column(String(64), ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False, index=True)
     intent_type = Column(String(64), nullable=False)
     payload = Column(JSON, nullable=False)
     oss_payload = Column(JSON, nullable=True)
     environment = Column(String(32), nullable=True)
-    created_at = Column(
-        DateTime,
-        default=datetime.datetime.utcnow,
-        nullable=False)
+    created_at = Column(DateTime, default=datetime.datetime.utcnow, nullable=False)
     evaluated_at = Column(DateTime, nullable=True)
     risk_score = Column(String(32), nullable=True)
-    outcomes = relationship(
-        "OutcomeDB",
-        back_populates="intent",
-        cascade="all, delete-orphan")
+
+    # Relationships
+    tenant = relationship("TenantDB", back_populates="intents")
+    outcomes = relationship("OutcomeDB", back_populates="intent", cascade="all, delete-orphan")
 
 
 class OutcomeDB(Base):
+    """
+    Records the outcome (success/failure) of a previously evaluated intent.
+    Only one outcome per intent is allowed (unique constraint on intent_id).
+
+    Attributes:
+        id (int): Primary key.
+        intent_id (int): Foreign key to `intents.id`.
+        success (bool): Whether the executed action succeeded.
+        recorded_by (str, optional): Identity of the caller (e.g., API key owner).
+        notes (str, optional): Free‑text notes.
+        recorded_at (datetime): UTC timestamp.
+        idempotency_key (str, optional): Unique idempotency key for this outcome.
+    """
     __tablename__ = "intent_outcomes"
+
     id = Column(Integer, primary_key=True, index=True)
-    intent_id = Column(
-        Integer,
-        ForeignKey(
-            "intents.id",
-            ondelete="CASCADE"),
-        nullable=False)
+    intent_id = Column(Integer, ForeignKey("intents.id", ondelete="CASCADE"), nullable=False)
     success = Column(Boolean, nullable=False)
     recorded_by = Column(String(128), nullable=True)
     notes = Column(Text, nullable=True)
-    recorded_at = Column(
-        DateTime,
-        default=datetime.datetime.utcnow,
-        nullable=False)
+    recorded_at = Column(DateTime, default=datetime.datetime.utcnow, nullable=False)
     idempotency_key = Column(String(128), unique=True, nullable=True)
+
     intent = relationship("IntentDB", back_populates="outcomes")
 
     __table_args__ = (
@@ -52,24 +151,83 @@ class OutcomeDB(Base):
     )
 
 
-# ---------------------------------------------------------------------------
-# NEW: Persistence for the conjugate Bayesian state
-# ---------------------------------------------------------------------------
+# ============================================================================
+# Bayesian conjugate state – now per tenant and per category
+# ============================================================================
+
 class BetaStateDB(Base):
     """
-    Stores the per‑category posterior parameters (α, β) of the BetaStore
-    so that online learning survives API restarts.
+    Stores the posterior parameters (α, β) of the conjugate Beta model
+    for each (tenant, category) pair. This allows online learning to be
+    isolated per customer.
 
-    Only one row per ActionCategory is expected; the 'category' column is
-    unique.  Updates are performed via merge / upsert.
+    Attributes:
+        id (int): Primary key.
+        tenant_id (str): Tenant that owns this state.
+        category (str): ActionCategory value (e.g., "database", "compute").
+        alpha (float): α parameter of the Beta distribution.
+        beta (float): β parameter of the Beta distribution.
+        updated_at (datetime): Last update timestamp (auto‑set).
     """
     __tablename__ = "beta_state"
 
     id = Column(Integer, primary_key=True, index=True)
-    category = Column(String(32), unique=True, nullable=False, index=True)
+    tenant_id = Column(String(64), ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False, index=True)
+    category = Column(String(32), nullable=False, index=True)
     alpha = Column(Float, nullable=False)
     beta = Column(Float, nullable=False)
-    updated_at = Column(
-        DateTime,
-        default=datetime.datetime.utcnow,
-        onupdate=datetime.datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.datetime.utcnow, onupdate=datetime.datetime.utcnow)
+
+    # Composite unique constraint: (tenant_id, category)
+    __table_args__ = (
+        UniqueConstraint("tenant_id", "category", name="uq_beta_state_tenant_category"),
+    )
+
+    # Relationships
+    tenant = relationship("TenantDB", back_populates="beta_states")
+
+
+# ============================================================================
+# NEW: Audit log for compliance (immutable decision records)
+# ============================================================================
+
+class DecisionAuditLogDB(Base):
+    """
+    Immutable, tamper‑evident record of every governance decision.
+    Designed for compliance (SOC2, ISO) and forensic analysis.
+
+    Attributes:
+        id (str): UUID primary key.
+        tenant_id (str): Tenant that owns the decision.
+        deterministic_id (str): Intent identifier (idempotency key).
+        timestamp (datetime): UTC decision time.
+        risk_score (float): Fused Bayesian risk score (0‑1).
+        action (str): Selected action (approve, deny, escalate).
+        justification (str): Human‑readable explanation.
+        memory_success_rate (float, optional): Memory‑based correction value.
+        memory_weight (float, optional): Weight assigned to memory.
+        counterfactual (JSON, optional): Structured counterfactual explanation.
+        trace_id (str, optional): OpenTelemetry trace ID for debugging.
+        signature (str, optional): Ed25519 signature for tamper‑proofing.
+    """
+    __tablename__ = "decision_audit_log"
+
+    id = Column(String(64), primary_key=True, default=lambda: str(uuid.uuid4()))
+    tenant_id = Column(String(64), ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False, index=True)
+    deterministic_id = Column(String(64), nullable=False, index=True)
+    timestamp = Column(DateTime, default=datetime.datetime.utcnow, nullable=False, index=True)
+    risk_score = Column(Float, nullable=False)
+    action = Column(String(32), nullable=False)
+    justification = Column(Text, nullable=False)
+    memory_success_rate = Column(Float, nullable=True)
+    memory_weight = Column(Float, nullable=True)
+    counterfactual = Column(JSON, nullable=True)
+    trace_id = Column(String(128), nullable=True)
+    signature = Column(String(256), nullable=True)
+
+    # Composite index for fast filtered queries
+    __table_args__ = (
+        Index("idx_audit_tenant_time", "tenant_id", "timestamp"),
+    )
+
+    tenant = relationship("TenantDB", back_populates="audit_logs")