senti/backend/database/postgres/models/audit.py

from sqlalchemy import (
  Column, String, Boolean, DateTime, Integer,
  Text, Float, Index
)
from sqlalchemy.sql import func
from .base import Base

class AuditLog(Base):
  """
  Immutable audit trail. Never update, never delete.
  Every significant action is logged here.
  """
  __tablename__ = "audit_log"
  
  id = Column(Integer, primary_key=True)
  user_hash = Column(String(64), nullable=False, index=True)
  tenant_id = Column(String(64), nullable=True, index=True)
  
  # What happened
  action = Column(String(100), nullable=False)
  # PROCESS_QUERY | GENERATE_FILE | UPDATE_MEMORY |
  # LOGIN | LOGOUT | API_CALL | APPROVAL_DECISION
  
  # Where it happened
  source = Column(String(50))
  # api | whatsapp | ussd | web | app | hermes
  
  # Request/response summary (no raw PII)
  request_summary = Column(Text)
  response_summary = Column(Text)
  
  # Routing info
  intent_detected = Column(String(100))
  engine_used = Column(String(50))
  formula_version = Column(String(50))
  
  # Performance
  latency_ms = Column(Integer)
  
  # Result
  success = Column(Boolean, default=True)
  error_type = Column(String(100), nullable=True)
  
  # For institutional: AI decision trail
  ai_reasoning = Column(Text, nullable=True)
  confidence_score = Column(Float, nullable=True)
  
  # Pipeline / Telemetry & Feedback compatibility
  pipeline_id = Column(String(36), nullable=True, index=True)
  quality_score = Column(Float, nullable=True)
  tier_used = Column(String(50), nullable=True)
  experts_used = Column(String(200), nullable=True)
  
  # Timestamps
  created_at = Column(DateTime, server_default=func.now(), index=True)
  
  __table_args__ = (
    Index("ix_audit_user", "user_hash"),
    Index("ix_audit_created", "created_at"),
    Index("ix_audit_tenant", "tenant_id"),
    Index("ix_audit_action", "action"),
  )