""" overwatch/models.py ------------------- Pydantic and SQLAlchemy models for the Overwatch structured event store. """ from __future__ import annotations import json import uuid from datetime import datetime, timezone from typing import Any, Dict, Literal, Union from pydantic import BaseModel, Field from sqlalchemy import Column, Index, Text from sqlalchemy.orm import declarative_base # --------------------------------------------------------------------------- # Type aliases # --------------------------------------------------------------------------- LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR"] ExtractionStage = Literal[ "upload", "layout_detection", "coordinate_extraction", "normalisation", "audit", ] ClassificationPhase = Literal[ "classification_started", "transaction_classified", "classification_completed", "rule_learned", ] Stage = Union[ExtractionStage, ClassificationPhase] # --------------------------------------------------------------------------- # Pydantic model (API / in-memory representation) # --------------------------------------------------------------------------- class OverwatchEvent(BaseModel): """Structured, typed event emitted at every processing stage.""" event_id: str = Field(default_factory=lambda: str(uuid.uuid4())) document_id: str document_name: str timestamp: str = Field( default_factory=lambda: datetime.now(timezone.utc).isoformat() ) log_level: LogLevel stage: Stage message: str = Field(max_length=500) metadata: Dict[str, Any] = Field(default_factory=dict) model_config = {"extra": "forbid"} # --------------------------------------------------------------------------- # SQLAlchemy ORM model (persistent representation) # --------------------------------------------------------------------------- OverwatchBase = declarative_base() class OverwatchEventORM(OverwatchBase): """SQLAlchemy ORM model for the ``overwatch_events`` table.""" __tablename__ = "overwatch_events" event_id = Column(Text, primary_key=True, default=lambda: str(uuid.uuid4())) document_id = Column(Text, nullable=False) document_name = Column(Text, nullable=False) timestamp = Column(Text, nullable=False) log_level = Column(Text, nullable=False) stage = Column(Text, nullable=False) message = Column(Text, nullable=False) # NOTE: 'metadata' is reserved by SQLAlchemy's declarative API. # The Python attribute is 'event_metadata'; the DB column is named 'metadata'. event_metadata = Column("metadata", Text, nullable=False, default="{}") __table_args__ = ( Index("idx_ow_timestamp", "timestamp"), Index("idx_ow_document_id", "document_id"), Index("idx_ow_document_name", "document_name"), Index("idx_ow_log_level", "log_level"), Index("idx_ow_stage", "stage"), ) @classmethod def from_event(cls, event: "OverwatchEvent") -> "OverwatchEventORM": """Create an ORM row from a Pydantic ``OverwatchEvent``. - Truncates ``message`` to 500 characters (belt-and-suspenders guard in addition to Pydantic's ``max_length`` validator). - JSON-serialises ``metadata``; non-serialisable values are converted to their ``str()`` representation via ``default=str``. """ return cls( event_id=event.event_id, document_id=event.document_id, document_name=event.document_name, timestamp=event.timestamp, log_level=event.log_level, stage=event.stage, message=event.message[:500], event_metadata=json.dumps(event.metadata, default=str), ) def to_event(self) -> "OverwatchEvent": """Reconstruct a Pydantic ``OverwatchEvent`` from this ORM row. - JSON-deserialises ``metadata``; falls back to an empty dict if the stored value is NULL or an empty string. """ return OverwatchEvent( event_id=self.event_id, document_id=self.document_id, document_name=self.document_name, timestamp=self.timestamp, log_level=self.log_level, stage=self.stage, message=self.message, metadata=json.loads(self.event_metadata or "{}"), )