3v324v23's picture
Merge Conflict solved | Build error solved
205f25f
Raw History Blame Contribute Delete
4.49 kB
"""
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 "{}"),
)