monkeybrain-runtime 1.0.0__py3-none-any.whl

services/changeover/helpers/changeover_kpis.py

@@ -0,0 +1,33 @@
+from typing import Optional
+
+from motor.motor_asyncio import AsyncIOMotorDatabase
+
+from services.changeover.helpers.changeover_common import create, delete, get_all, get_by_id, update
+from services.changeover.models.changeover_kpis import ChangeoverKPICreate, ChangeoverKPIUpdate
+
+COLLECTION = "changeover_kpis"
+
+
+async def get_all_kpis(db: AsyncIOMotorDatabase, page: int = 1, page_size: int = 20) -> tuple[list[dict], int]:
+    return await get_all(db, COLLECTION, page, page_size)
+
+
+async def get_kpi_by_id(db: AsyncIOMotorDatabase, kpi_id: str) -> Optional[dict]:
+    return await get_by_id(db, COLLECTION, kpi_id)
+
+
+async def get_kpis_by_workstation(db: AsyncIOMotorDatabase, workstation_id: str) -> list[dict]:
+    records, _ = await get_all(db, COLLECTION, query={"workstation_id": workstation_id}, page_size=1000)
+    return records
+
+
+async def create_kpi(db: AsyncIOMotorDatabase, data: ChangeoverKPICreate) -> dict:
+    return await create(db, COLLECTION, data)
+
+
+async def update_kpi(db: AsyncIOMotorDatabase, kpi_id: str, data: ChangeoverKPIUpdate) -> Optional[dict]:
+    return await update(db, COLLECTION, kpi_id, data)
+
+
+async def delete_kpi(db: AsyncIOMotorDatabase, kpi_id: str) -> bool:
+    return await delete(db, COLLECTION, kpi_id)

services/changeover/helpers/changeover_matrix.py

@@ -0,0 +1,60 @@
+from typing import Optional
+
+from motor.motor_asyncio import AsyncIOMotorDatabase
+
+from services.changeover.helpers.changeover_common import create, delete, get_all, get_by_id, update
+from services.changeover.models.changeover_matrix import (
+    ChangeoverMatrixEntryCreate,
+    ChangeoverMatrixEntryResponse,
+    ChangeoverMatrixEntryUpdate,
+)
+
+COLLECTION = "changeover_matrix"
+
+
+def _normalize_matrix_record(doc: Optional[dict]) -> Optional[dict]:
+    if not doc:
+        return None
+
+    record = dict(doc)
+    record.pop("_id", None)
+    entry_id = str(record.get("id") or record.get("entry_id") or "CHANGEOVER-MATRIX")
+    record["id"] = entry_id
+    record.setdefault("workstation_id", str(record.get("workstation") or "UNKNOWN-WORKSTATION"))
+    record["from_product_id"] = str(record.get("from_product_id") or record.get("from_product") or "UNKNOWN-FROM-PRODUCT")
+    record["to_product_id"] = str(record.get("to_product_id") or record.get("to_product") or record["from_product_id"])
+    record["standard_minutes"] = int(record.get("standard_minutes") or record.get("target_minutes") or record.get("duration_minutes") or 1)
+    record["requires_cleaning"] = bool(record.get("requires_cleaning") or False)
+    record["requires_tooling"] = bool(record.get("requires_tooling") or False)
+    record["min_operators"] = int(record.get("min_operators") or 1)
+    best = record.get("best_achieved_minutes")
+    if best is not None and int(best) > record["standard_minutes"]:
+        record["best_achieved_minutes"] = record["standard_minutes"]
+
+    return ChangeoverMatrixEntryResponse.model_validate(record).model_dump()
+
+
+async def get_all_matrix(db: AsyncIOMotorDatabase, page: int = 1, page_size: int = 20) -> tuple[list[dict], int]:
+    records, total = await get_all(db, COLLECTION, page, page_size)
+    return [_normalize_matrix_record(record) for record in records], total
+
+
+async def get_matrix_by_id(db: AsyncIOMotorDatabase, entry_id: str) -> Optional[dict]:
+    return _normalize_matrix_record(await get_by_id(db, COLLECTION, entry_id))
+
+
+async def get_matrix_by_workstation(db: AsyncIOMotorDatabase, workstation_id: str) -> list[dict]:
+    records, _ = await get_all(db, COLLECTION, query={"workstation_id": workstation_id}, page_size=1000)
+    return [_normalize_matrix_record(record) for record in records]
+
+
+async def create_matrix(db: AsyncIOMotorDatabase, data: ChangeoverMatrixEntryCreate) -> dict:
+    return _normalize_matrix_record(await create(db, COLLECTION, data))
+
+
+async def update_matrix(db: AsyncIOMotorDatabase, entry_id: str, data: ChangeoverMatrixEntryUpdate) -> Optional[dict]:
+    return _normalize_matrix_record(await update(db, COLLECTION, entry_id, data))
+
+
+async def delete_matrix(db: AsyncIOMotorDatabase, entry_id: str) -> bool:
+    return await delete(db, COLLECTION, entry_id)

services/changeover/helpers/changeover_procedures.py

@@ -0,0 +1,164 @@
+from datetime import datetime, timezone
+from typing import Optional
+
+from motor.motor_asyncio import AsyncIOMotorDatabase
+from pymongo import ReturnDocument
+
+from services.changeover.helpers.changeover_common import create, delete, dump, get_all, get_by_id, serialize, update
+from services.changeover.models.changeover_procedures import ChangeoverProcedureCreate, ChangeoverProcedureUpdate
+from services.changeover.models.changeover_tasks import ChangeoverTaskUpdate
+from services.common.models.enums import ChangeoverStatus, TaskStatus
+
+COLLECTION = "changeover_procedures"
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _task_is_complete(task: dict) -> bool:
+    return bool(task.get("is_complete")) or task.get("status") == TaskStatus.DONE.value
+
+
+def _procedure_completion_fields(tasks: list[dict]) -> dict:
+    if tasks and all(_task_is_complete(task) for task in tasks):
+        return {
+            "status": ChangeoverStatus.COMPLETED.value,
+            "completed_at": _now(),
+        }
+    return {
+        "status": ChangeoverStatus.IN_PROGRESS.value,
+        "completed_at": None,
+    }
+
+
+def _apply_task_completion(task: dict, is_complete: bool) -> None:
+    task["is_complete"] = is_complete
+    if is_complete:
+        now = _now()
+        task["status"] = TaskStatus.DONE.value
+        if not task.get("started_at"):
+            task["started_at"] = now
+        task["completed_at"] = task.get("completed_at") or now
+        task["blocked_reason"] = None
+    else:
+        task["status"] = TaskStatus.PENDING.value
+        task["completed_at"] = None
+
+
+async def get_all_procedures(db: AsyncIOMotorDatabase, page: int = 1, page_size: int = 20) -> tuple[list[dict], int]:
+    return await get_all(db, COLLECTION, page, page_size)
+
+
+async def get_procedure_by_id(db: AsyncIOMotorDatabase, procedure_id: str) -> Optional[dict]:
+    return await get_by_id(db, COLLECTION, procedure_id)
+
+
+async def get_procedures_by_factory(db: AsyncIOMotorDatabase, factory_id: str) -> list[dict]:
+    records, _ = await get_all(
+        db,
+        COLLECTION,
+        query={"$or": [{"plant_id": factory_id}, {"factory_id": factory_id}]},
+        page_size=1000,
+    )
+    return records
+
+
+async def get_procedures_by_plant(db: AsyncIOMotorDatabase, plant_id: str) -> list[dict]:
+    records, _ = await get_all(db, COLLECTION, query={"plant_id": plant_id}, page_size=1000)
+    return records
+
+
+async def create_procedure(db: AsyncIOMotorDatabase, data: ChangeoverProcedureCreate) -> dict:
+    doc = await create(db, COLLECTION, data)
+    completion_fields = _procedure_completion_fields(doc.get("tasks", []))
+    if completion_fields["status"] == ChangeoverStatus.COMPLETED.value:
+        await db[COLLECTION].update_one({"id": doc["id"]}, {"$set": completion_fields})
+        doc.update(completion_fields)
+    return doc
+
+
+async def update_procedure(db: AsyncIOMotorDatabase, procedure_id: str, data: ChangeoverProcedureUpdate) -> Optional[dict]:
+    updated = await update(db, COLLECTION, procedure_id, data)
+    if not updated or "tasks" not in data.model_dump(exclude_unset=True):
+        return updated
+
+    completion_fields = _procedure_completion_fields(updated.get("tasks", []))
+    result = await db[COLLECTION].find_one_and_update(
+        {"id": procedure_id},
+        {"$set": completion_fields},
+        return_document=ReturnDocument.AFTER,
+    )
+    return serialize(result) if result else None
+
+
+async def update_procedure_task(
+    db: AsyncIOMotorDatabase,
+    procedure_id: str,
+    task_id: str,
+    data: ChangeoverTaskUpdate,
+) -> Optional[dict]:
+    procedure = await get_procedure_by_id(db, procedure_id)
+    if not procedure:
+        return None
+
+    tasks = procedure.get("tasks", [])
+    fields = dump(data)
+    matched = False
+    for task in tasks:
+        if str(task.get("id")) != task_id:
+            continue
+        matched = True
+        task.update(fields)
+        if fields.get("is_complete") is not None:
+            _apply_task_completion(task, fields["is_complete"])
+        elif fields.get("status") == TaskStatus.DONE.value:
+            _apply_task_completion(task, True)
+        elif fields.get("completed_at") is not None:
+            task["is_complete"] = True
+        break
+
+    if not matched:
+        return None
+
+    update_fields = {"tasks": tasks, **_procedure_completion_fields(tasks)}
+    result = await db[COLLECTION].find_one_and_update(
+        {"id": procedure_id},
+        {"$set": update_fields},
+        return_document=ReturnDocument.AFTER,
+    )
+    return serialize(result) if result else None
+
+
+async def set_procedure_task_complete(
+    db: AsyncIOMotorDatabase,
+    procedure_id: str,
+    task_id: str,
+    is_complete: bool,
+) -> Optional[dict]:
+    procedure = await get_procedure_by_id(db, procedure_id)
+    if not procedure:
+        return None
+
+    tasks = procedure.get("tasks", [])
+    matched = False
+    for task in tasks:
+        if str(task.get("id")) == task_id:
+            matched = True
+            _apply_task_completion(task, is_complete)
+            break
+
+    if not matched:
+        return None
+
+    update_fields = {"tasks": tasks, **_procedure_completion_fields(tasks)}
+    result = await db[COLLECTION].find_one_and_update(
+        {"id": procedure_id},
+        {"$set": update_fields},
+        return_document=ReturnDocument.AFTER,
+    )
+    return serialize(result) if result else None
+
+
+async def delete_procedure(db: AsyncIOMotorDatabase, procedure_id: str) -> bool:
+    return await delete(db, COLLECTION, procedure_id)

services/changeover/helpers/changeover_windows.py

@@ -0,0 +1,96 @@
+from datetime import datetime, timedelta
+from typing import Optional
+
+from motor.motor_asyncio import AsyncIOMotorDatabase
+from pymongo import ReturnDocument
+
+from services.pm.helpers import calendar_bookings
+from services.changeover.helpers.changeover_common import create, delete, get_all, get_by_id, update
+from services.pm.models.calendar_booking import CalendarBookingCreate
+from services.changeover.models.changeover_windows import (
+    ChangeoverWindowCalendarBookingCreate,
+    ChangeoverWindowCreate,
+    ChangeoverWindowUpdate,
+)
+
+COLLECTION = "changeover_windows"
+
+
+def _to_datetime(value) -> datetime:
+    if isinstance(value, datetime):
+        return value
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def _calendar_title(window: dict) -> str:
+    return f"Changeover window - workstation {window['workstation_id']}"
+
+
+async def get_all_windows(db: AsyncIOMotorDatabase, page: int = 1, page_size: int = 20) -> tuple[list[dict], int]:
+    return await get_all(db, COLLECTION, page, page_size)
+
+
+async def get_window_by_id(db: AsyncIOMotorDatabase, window_id: str) -> Optional[dict]:
+    return await get_by_id(db, COLLECTION, window_id)
+
+
+async def get_windows_by_workstation(db: AsyncIOMotorDatabase, workstation_id: str) -> list[dict]:
+    records, _ = await get_all(db, COLLECTION, query={"workstation_id": workstation_id}, page_size=1000)
+    return records
+
+
+async def create_window(db: AsyncIOMotorDatabase, data: ChangeoverWindowCreate) -> dict:
+    return await create(db, COLLECTION, data)
+
+
+async def update_window(db: AsyncIOMotorDatabase, window_id: str, data: ChangeoverWindowUpdate) -> Optional[dict]:
+    return await update(db, COLLECTION, window_id, data)
+
+
+async def add_window_to_calendar(
+    db: AsyncIOMotorDatabase,
+    window_id: str,
+    data: ChangeoverWindowCalendarBookingCreate,
+) -> Optional[dict]:
+    window = await get_window_by_id(db, window_id)
+    if not window:
+        return None
+
+    existing_booking_id = window.get("calendar_booking_id")
+    if existing_booking_id:
+        existing_booking = await calendar_bookings.get_by_id(db, str(existing_booking_id))
+        if existing_booking:
+            return existing_booking
+
+    start_at = _to_datetime(window["start_dt"])
+    end_at = _to_datetime(window["end_dt"])
+    if data.include_buffer:
+        end_at = end_at + timedelta(minutes=window.get("buffer_minutes", 0))
+
+    booking = CalendarBookingCreate(
+        calendar_id=data.calendar_id or str(window["workstation_id"]),
+        title=data.title or _calendar_title(window),
+        start_at=start_at,
+        end_at=end_at,
+        booked_by=data.booked_by,
+        attendee_ids=data.attendee_ids,
+        description=data.description
+        or f"Changeover window {window_id} for workstation {window['workstation_id']}.",
+    )
+
+    if await calendar_bookings.has_conflict(db, booking.calendar_id, booking.start_at, booking.end_at):
+        return {"conflict": True}
+
+    created = await calendar_bookings.create(db, booking)
+    booking_id = created.get("id") or str(booking.id)
+    await db[COLLECTION].find_one_and_update(
+        {"id": window_id},
+        {"$set": {"calendar_booking_id": booking_id}},
+        return_document=ReturnDocument.AFTER,
+    )
+    created["id"] = booking_id
+    return created
+
+
+async def delete_window(db: AsyncIOMotorDatabase, window_id: str) -> bool:
+    return await delete(db, COLLECTION, window_id)

services/changeover/main.py

@@ -0,0 +1,52 @@
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from services.common.logging import configure_service_logging, install_request_logging
+from services.common.tracing import install_route_tracing
+
+from services.common.db import close_db, connect_db
+from services.changeover.routers.changeover_matrix import router as changeover_matrix_router
+from services.changeover.routers.changeover_procedures import router as changeover_procedures_router
+from services.changeover.routers.changeover_windows import router as changeover_windows_router
+from services.changeover.routers.changeover_kpis import router as changeover_kpis_router
+from services.changeover.routers.changeover_events import router as changeover_events_router
+
+
+logger = configure_service_logging("changeover")
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await connect_db()
+    yield
+    await close_db()
+
+
+app = FastAPI(
+    title="Changeover Service",
+    description="Microservice for changeover service.",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+install_request_logging(app, "changeover")
+install_route_tracing(app, "changeover")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(changeover_matrix_router, prefix="/api/v1/changeovers/matrix", tags=["Changeover Matrix"])
+app.include_router(changeover_procedures_router, prefix="/api/v1/changeovers/procedures", tags=["Changeover Procedures"])
+app.include_router(changeover_windows_router, prefix="/api/v1/changeovers", tags=["Changeover Windows"])
+app.include_router(changeover_kpis_router, prefix="/api/v1/changeovers", tags=["Changeover KPIs"])
+app.include_router(changeover_events_router, prefix="/api/v1/changeovers", tags=["Changeover Events"])
+
+
+@app.get("/health", tags=["Health"])
+async def health_check():
+    return {"status": "healthy"}

services/changeover/models/__init__.py

@@ -0,0 +1,11 @@
+"""changeover service models package."""
+
+__all__ = [
+    "changeover",
+    "changeover_events",
+    "changeover_kpis",
+    "changeover_matrix",
+    "changeover_procedures",
+    "changeover_tasks",
+    "changeover_windows",
+]

services/changeover/models/changeover.py

@@ -0,0 +1,73 @@
+from services.changeover.models.changeover_events import (
+    ChangeoverEvent,
+    ChangeoverEventCreate,
+    ChangeoverEventResponse,
+    ChangeoverEventUpdate,
+    PaginatedChangeoverEventResponse,
+)
+from services.changeover.models.changeover_kpis import (
+    ChangeoverKPI,
+    ChangeoverKPICreate,
+    ChangeoverKPIResponse,
+    ChangeoverKPIUpdate,
+    PaginatedChangeoverKPIResponse,
+)
+from services.changeover.models.changeover_matrix import (
+    ChangeoverMatrixEntry,
+    ChangeoverMatrixEntryCreate,
+    ChangeoverMatrixEntryResponse,
+    ChangeoverMatrixEntryUpdate,
+    PaginatedChangeoverMatrixEntryResponse,
+)
+from services.changeover.models.changeover_procedures import (
+    ChangeoverProcedure,
+    ChangeoverProcedureCreate,
+    ChangeoverProcedureResponse,
+    ChangeoverProcedureUpdate,
+    PaginatedChangeoverProcedureResponse,
+)
+from services.changeover.models.changeover_tasks import (
+    ChangeoverTask,
+    ChangeoverTaskCreate,
+    ChangeoverTaskUpdate,
+)
+from services.changeover.models.changeover_windows import (
+    ChangeoverWindow,
+    ChangeoverWindowCalendarBookingCreate,
+    ChangeoverWindowCreate,
+    ChangeoverWindowResponse,
+    ChangeoverWindowUpdate,
+    PaginatedChangeoverWindowResponse,
+)
+
+__all__ = [
+    "ChangeoverEvent",
+    "ChangeoverEventCreate",
+    "ChangeoverEventResponse",
+    "ChangeoverEventUpdate",
+    "ChangeoverKPI",
+    "ChangeoverKPICreate",
+    "ChangeoverKPIResponse",
+    "ChangeoverKPIUpdate",
+    "ChangeoverMatrixEntry",
+    "ChangeoverMatrixEntryCreate",
+    "ChangeoverMatrixEntryResponse",
+    "ChangeoverMatrixEntryUpdate",
+    "ChangeoverProcedure",
+    "ChangeoverProcedureCreate",
+    "ChangeoverProcedureResponse",
+    "ChangeoverProcedureUpdate",
+    "ChangeoverTask",
+    "ChangeoverTaskCreate",
+    "ChangeoverTaskUpdate",
+    "ChangeoverWindow",
+    "ChangeoverWindowCalendarBookingCreate",
+    "ChangeoverWindowCreate",
+    "ChangeoverWindowResponse",
+    "ChangeoverWindowUpdate",
+    "PaginatedChangeoverEventResponse",
+    "PaginatedChangeoverKPIResponse",
+    "PaginatedChangeoverMatrixEntryResponse",
+    "PaginatedChangeoverProcedureResponse",
+    "PaginatedChangeoverWindowResponse",
+]

services/changeover/models/changeover_events.py

@@ -0,0 +1,142 @@
+from datetime import datetime
+from typing import Optional
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field, computed_field, field_validator, model_validator
+
+from services.changeover.models.changeover_tasks import ChangeoverTask
+from services.common.models.enums import ChangeoverStatus, ChangeoverTrigger, ChangeoverType, TaskStatus
+
+
+class ChangeoverEvent(BaseModel):
+    """Concrete live or historical workstation changeover."""
+
+    model_config = ConfigDict(str_strip_whitespace=True)
+
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    workstation_id: str
+    factory_id: str
+    procedure_id: Optional[str] = Field(None, description="Source ChangeoverProcedure template")
+    shift_schedule_id: Optional[str] = Field(None, description="Shift during which the changeover occurs")
+    changeover_type: ChangeoverType
+    trigger: ChangeoverTrigger = ChangeoverTrigger.SCHEDULED
+    status: ChangeoverStatus = ChangeoverStatus.PLANNED
+    from_product_id: Optional[str] = None
+    to_product_id: Optional[str] = None
+    planned_start: datetime
+    planned_end: datetime
+    actual_start: Optional[datetime] = None
+    actual_end: Optional[datetime] = None
+    lead_operator_id: Optional[str] = None
+    team_member_ids: list[str] = Field(default_factory=list)
+    tasks: list[ChangeoverTask] = Field(default_factory=list)
+    downtime_minutes: Optional[float] = Field(None, ge=0, description="Unplanned stoppage time added during changeover")
+    quality_check_passed: Optional[bool] = Field(None, description="First-article / first-off quality result after changeover")
+    notes: Optional[str] = Field(None, max_length=800)
+
+    @field_validator("changeover_type", "trigger", "status", mode="before")
+    @classmethod
+    def normalize_enum_value(cls, value):
+        return value.lower() if isinstance(value, str) else value
+
+    @model_validator(mode="after")
+    def planned_end_after_start(self):
+        if self.planned_end <= self.planned_start:
+            raise ValueError("planned_end must be after planned_start")
+        return self
+
+    @model_validator(mode="after")
+    def actual_end_after_actual_start(self):
+        if self.actual_start and self.actual_end and self.actual_end <= self.actual_start:
+            raise ValueError("actual_end must be after actual_start")
+        return self
+
+    @model_validator(mode="after")
+    def completed_needs_actual_times(self):
+        if self.status == ChangeoverStatus.COMPLETED and (not self.actual_start or not self.actual_end):
+            raise ValueError("status=completed requires both actual_start and actual_end")
+        return self
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def planned_duration_minutes(self) -> float:
+        return (self.planned_end - self.planned_start).total_seconds() / 60
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def actual_duration_minutes(self) -> Optional[float]:
+        if self.actual_start and self.actual_end:
+            return (self.actual_end - self.actual_start).total_seconds() / 60
+        return None
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def variance_minutes(self) -> Optional[float]:
+        if self.actual_duration_minutes is not None:
+            return self.actual_duration_minutes - self.planned_duration_minutes
+        return None
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def completion_pct(self) -> float:
+        if not self.tasks:
+            return 0.0
+        done = sum(1 for t in self.tasks if t.status in {TaskStatus.DONE, TaskStatus.SKIPPED})
+        return round(done / len(self.tasks) * 100, 1)
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def is_running_late(self) -> bool:
+        if self.status != ChangeoverStatus.IN_PROGRESS or not self.actual_start:
+            return False
+        elapsed = (datetime.utcnow() - self.actual_start).total_seconds() / 60
+        return elapsed > self.planned_duration_minutes
+
+    def pending_tasks(self) -> list[ChangeoverTask]:
+        return [t for t in self.tasks if t.status == TaskStatus.PENDING]
+
+    def blocked_tasks(self) -> list[ChangeoverTask]:
+        return [t for t in self.tasks if t.status == TaskStatus.BLOCKED]
+
+
+class ChangeoverEventCreate(ChangeoverEvent):
+    pass
+
+
+class ChangeoverEventUpdate(BaseModel):
+    workstation_id: Optional[str] = None
+    factory_id: Optional[str] = None
+    procedure_id: Optional[str] = None
+    shift_schedule_id: Optional[str] = None
+    changeover_type: Optional[ChangeoverType] = None
+    trigger: Optional[ChangeoverTrigger] = None
+    status: Optional[ChangeoverStatus] = None
+    from_product_id: Optional[str] = None
+    to_product_id: Optional[str] = None
+    planned_start: Optional[datetime] = None
+    planned_end: Optional[datetime] = None
+    actual_start: Optional[datetime] = None
+    actual_end: Optional[datetime] = None
+    lead_operator_id: Optional[str] = None
+    team_member_ids: Optional[list[str]] = None
+    tasks: Optional[list[ChangeoverTask]] = None
+    downtime_minutes: Optional[float] = Field(None, ge=0)
+    quality_check_passed: Optional[bool] = None
+    notes: Optional[str] = Field(None, max_length=800)
+
+    @field_validator("changeover_type", "trigger", "status", mode="before")
+    @classmethod
+    def normalize_enum_value(cls, value):
+        return value.lower() if isinstance(value, str) else value
+
+
+class ChangeoverEventResponse(ChangeoverEvent):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedChangeoverEventResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[ChangeoverEventResponse]