feat: add SQLAlchemy models for all 5 DB tables

TDD implementation of ChatSession, ResponseMetrics, ResponseFeedback,
LLMJudgeScore, and GuardrailEvent models. Uses generic JSON/Uuid/Integer
types for SQLite test compatibility while remaining PostgreSQL-ready.

mao/db/__init__.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+import logging
+from contextlib import contextmanager
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session, sessionmaker
+from mao.db.models import Base
+
+logger = logging.getLogger(__name__)
+
+_engine = None
+_SessionLocal = None
+
+POSTGRES_URL = "postgresql://mao:mao@localhost:5432/mao"
+
+
+def init_db() -> None:
+    global _engine, _SessionLocal
+    try:
+        _engine = create_engine(POSTGRES_URL, pool_pre_ping=True)
+        Base.metadata.create_all(_engine)
+        _SessionLocal = sessionmaker(bind=_engine)
+        logger.info("Database initialised: %s", POSTGRES_URL)
+    except Exception as exc:
+        logger.critical("Database init failed: %s", exc)
+
+
+@contextmanager
+def get_db_session():
+    if _SessionLocal is None:
+        raise RuntimeError("Database not initialised — call init_db() first")
+    session = _SessionLocal()
+    try:
+        yield session
+    finally:
+        session.close()

mao/db/models.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+import uuid
+from datetime import datetime, timezone
+from sqlalchemy import BigInteger, Boolean, Column, Float, ForeignKey, Integer, JSON, SmallInteger, String, Text, Uuid
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+def _uuid():
+    return uuid.uuid4()
+
+
+def _now():
+    return datetime.now(timezone.utc)
+
+
+class ChatSession(Base):
+    __tablename__ = "chat_sessions"
+    session_id         = Column(Uuid(as_uuid=True), primary_key=True, default=_uuid)
+    user_id            = Column(String, nullable=False)
+    user_query         = Column(Text, nullable=False)
+    pii_scrubbed_query = Column(Text)
+    response           = Column(Text)
+    agent_used         = Column(String)
+    domain             = Column(String)
+    report_card        = Column(JSON)
+    council_verdict    = Column(JSON)
+    nli_flags          = Column(JSON)
+    uncertainty_flag   = Column(Boolean, default=False)
+    created_at         = Column(Text, default=lambda: _now().isoformat())
+
+
+class ResponseMetrics(Base):
+    __tablename__ = "response_metrics"
+    id                = Column(Integer, primary_key=True, autoincrement=True)
+    request_id        = Column(String, nullable=False)
+    session_id        = Column(Uuid(as_uuid=True), ForeignKey("chat_sessions.session_id"))
+    user_id           = Column(String, nullable=False)
+    agent_used        = Column(String)
+    faithfulness      = Column(Float)
+    answer_relevancy  = Column(Float)
+    context_precision = Column(Float)
+    context_recall    = Column(Float)
+    latency_ms        = Column(Float)
+    created_at        = Column(Text, default=lambda: _now().isoformat())
+
+
+class ResponseFeedback(Base):
+    __tablename__ = "response_feedback"
+    id         = Column(Integer, primary_key=True, autoincrement=True)
+    session_id = Column(Uuid(as_uuid=True), ForeignKey("chat_sessions.session_id"))
+    user_id    = Column(String, nullable=False)
+    rating     = Column(SmallInteger, nullable=False)
+    comment    = Column(Text)
+    created_at = Column(Text, default=lambda: _now().isoformat())
+
+
+class LLMJudgeScore(Base):
+    __tablename__ = "llm_judge_scores"
+    id           = Column(Integer, primary_key=True, autoincrement=True)
+    session_id   = Column(Uuid(as_uuid=True), ForeignKey("chat_sessions.session_id"))
+    accuracy     = Column(SmallInteger)
+    completeness = Column(SmallInteger)
+    safety       = Column(SmallInteger)
+    clarity      = Column(SmallInteger)
+    notes        = Column(Text)
+    created_at   = Column(Text, default=lambda: _now().isoformat())
+
+
+class GuardrailEvent(Base):
+    __tablename__ = "guardrail_events"
+    id             = Column(Integer, primary_key=True, autoincrement=True)
+    session_id     = Column(Uuid(as_uuid=True))
+    guardrail_name = Column(String, nullable=False)
+    triggered      = Column(Boolean, nullable=False)
+    detail         = Column(Text)
+    created_at     = Column(Text, default=lambda: _now().isoformat())

tests/db/test_models.py

@@ -0,0 +1,58 @@
+import pytest
+import uuid
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session
+from mao.db.models import (
+    Base, ChatSession, ResponseMetrics,
+    ResponseFeedback, LLMJudgeScore, GuardrailEvent,
+)
+
+@pytest.fixture
+def engine():
+    eng = create_engine("sqlite:///:memory:")
+    Base.metadata.create_all(eng)
+    yield eng
+    Base.metadata.drop_all(eng)
+
+@pytest.fixture
+def session(engine):
+    with Session(engine) as s:
+        yield s
+
+def test_chat_session_insert(session):
+    row = ChatSession(session_id=uuid.uuid4(), user_id="user-1", user_query="What is amyloid?")
+    session.add(row)
+    session.commit()
+    result = session.get(ChatSession, row.session_id)
+    assert result.user_id == "user-1"
+    assert result.uncertainty_flag is False
+
+def test_response_metrics_insert(session):
+    sid = uuid.uuid4()
+    session.add(ChatSession(session_id=sid, user_id="u", user_query="q"))
+    session.commit()
+    row = ResponseMetrics(request_id="req-1", session_id=sid, user_id="u", faithfulness=0.85)
+    session.add(row)
+    session.commit()
+    assert session.get(ResponseMetrics, row.id).faithfulness == pytest.approx(0.85)
+
+def test_response_feedback_insert(session):
+    sid = uuid.uuid4()
+    session.add(ChatSession(session_id=sid, user_id="u", user_query="q"))
+    session.commit()
+    session.add(ResponseFeedback(session_id=sid, user_id="u", rating=1))
+    session.commit()
+    assert session.query(ResponseFeedback).first().rating == 1
+
+def test_llm_judge_scores_insert(session):
+    sid = uuid.uuid4()
+    session.add(ChatSession(session_id=sid, user_id="u", user_query="q"))
+    session.commit()
+    session.add(LLMJudgeScore(session_id=sid, accuracy=8, safety=10))
+    session.commit()
+    assert session.query(LLMJudgeScore).first().accuracy == 8
+
+def test_guardrail_event_insert(session):
+    session.add(GuardrailEvent(guardrail_name="token_limit", triggered=True, detail="550 tokens"))
+    session.commit()
+    assert session.query(GuardrailEvent).first().triggered is True