monkeybrain-runtime 1.0.0__py3-none-any.whl

services/workorders/models/batch_release_workflows.py

@@ -0,0 +1,190 @@
+from datetime import datetime, timezone
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, Field, model_validator
+
+
+BatchReleaseStatus = Literal["Draft", "In Review", "Ready For QA Release", "Released", "Rejected", "Blocked"]
+BatchReleaseDecision = Literal["Pending", "Released", "Rejected", "Hold"]
+PrerequisiteStatus = Literal["Pending", "Passed", "Failed", "Waived"]
+ExecutedPackageStatus = Literal["Pending", "Executed", "Reviewed", "Approved", "Rejected"]
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def ensure_utc(value: Optional[datetime]) -> Optional[datetime]:
+    if value is None:
+        return None
+    if value.tzinfo is None:
+        return value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc)
+
+
+class BatchReleasePrerequisite(BaseModel):
+    name: str = Field(..., min_length=1)
+    status: PrerequisiteStatus = "Pending"
+    owner_role: Optional[str] = None
+    owner_id: Optional[str] = None
+    evidence_document_ids: list[str] = Field(default_factory=list)
+    notes: Optional[str] = None
+
+
+class ExecutedBatchRecordPackage(BaseModel):
+    package_type: Literal["BMR", "BPR"]
+    status: ExecutedPackageStatus = "Pending"
+    document_ids: list[str] = Field(default_factory=list)
+    executed_by: Optional[str] = None
+    executed_at: Optional[datetime] = None
+    reviewed_by: Optional[str] = None
+    reviewed_at: Optional[datetime] = None
+    evidence_document_ids: list[str] = Field(default_factory=list)
+    report_template_ids: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def normalize_and_validate(self) -> "ExecutedBatchRecordPackage":
+        self.executed_at = ensure_utc(self.executed_at)
+        self.reviewed_at = ensure_utc(self.reviewed_at)
+        if self.status in {"Executed", "Reviewed", "Approved"}:
+            if not self.document_ids:
+                raise ValueError(f"executed {self.package_type} package must include document_ids.")
+            if not self.executed_by or not self.executed_at:
+                raise ValueError(f"executed {self.package_type} package must include executed_by and executed_at.")
+        if self.status in {"Reviewed", "Approved"} and (not self.reviewed_by or not self.reviewed_at):
+            raise ValueError(f"reviewed/approved {self.package_type} package must include reviewed_by and reviewed_at.")
+        return self
+
+
+class BatchReleaseWorkflow(BaseModel):
+    batch_release_workflow_id: str = Field(..., min_length=1)
+    batch_execution_record_id: str = Field(..., min_length=1)
+    batch_id: str = Field(..., min_length=1)
+    product_id: Optional[str] = None
+    bom_id: Optional[str] = None
+    process_definition_id: Optional[str] = None
+    process_route_id: Optional[str] = None
+    plant_id: Optional[str] = None
+    line_id: Optional[str] = None
+
+    status: BatchReleaseStatus = "Draft"
+    release_decision: BatchReleaseDecision = "Pending"
+    release_scope: str = Field(default="Executed BMR/BPR batch release", min_length=1)
+
+    bmr_document_ids: list[str] = Field(default_factory=list)
+    bpr_document_ids: list[str] = Field(default_factory=list)
+    executed_bmr_package: Optional[ExecutedBatchRecordPackage] = None
+    executed_bpr_package: Optional[ExecutedBatchRecordPackage] = None
+    batch_step_execution_ids: list[str] = Field(default_factory=list)
+    cleaning_record_ids: list[str] = Field(default_factory=list)
+    equipment_usage_ids: list[str] = Field(default_factory=list)
+    area_room_usage_ids: list[str] = Field(default_factory=list)
+    yield_reconciliation_record_ids: list[str] = Field(default_factory=list)
+    cpp_cqa_registry_ids: list[str] = Field(default_factory=list)
+    evidence_document_ids: list[str] = Field(default_factory=list)
+    report_template_ids: list[str] = Field(default_factory=list)
+
+    prerequisites: list[BatchReleasePrerequisite] = Field(default_factory=list)
+    qa_reviewer_id: Optional[str] = None
+    released_by: Optional[str] = None
+    released_at: Optional[datetime] = None
+    rejected_by: Optional[str] = None
+    rejected_at: Optional[datetime] = None
+    rejection_reason: Optional[str] = None
+    signature_ids: list[str] = Field(default_factory=list)
+    audit_event_ids: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    created_by: Optional[str] = None
+    created_at: datetime = Field(default_factory=utc_now)
+    updated_at: datetime = Field(default_factory=utc_now)
+
+    @model_validator(mode="after")
+    def normalize_and_validate(self) -> "BatchReleaseWorkflow":
+        self.released_at = ensure_utc(self.released_at)
+        self.rejected_at = ensure_utc(self.rejected_at)
+        self.created_at = ensure_utc(self.created_at) or utc_now()
+        self.updated_at = ensure_utc(self.updated_at) or utc_now()
+
+        if self.status == "Released" or self.release_decision == "Released":
+            if not self.qa_reviewer_id:
+                raise ValueError("released batch release workflows must include qa_reviewer_id.")
+            if not self.released_by or not self.released_at:
+                raise ValueError("released batch release workflows must include released_by and released_at.")
+            if not self.signature_ids:
+                raise ValueError("released batch release workflows must include signature_ids.")
+            if not self.bmr_document_ids or not self.bpr_document_ids:
+                raise ValueError("released batch release workflows must include executed BMR and BPR document references.")
+            if not self.executed_bmr_package or self.executed_bmr_package.status not in {"Executed", "Reviewed", "Approved"}:
+                raise ValueError("released batch release workflows must include an executed BMR package.")
+            if not self.executed_bpr_package or self.executed_bpr_package.status not in {"Executed", "Reviewed", "Approved"}:
+                raise ValueError("released batch release workflows must include an executed BPR package.")
+            if not self.report_template_ids:
+                raise ValueError("released batch release workflows must include report_template_ids.")
+            if not self.executed_bmr_package.report_template_ids:
+                raise ValueError("released batch release workflows must bind the executed BMR package to report_template_ids.")
+            if not self.executed_bpr_package.report_template_ids:
+                raise ValueError("released batch release workflows must bind the executed BPR package to report_template_ids.")
+            if not self.batch_step_execution_ids:
+                raise ValueError("released batch release workflows must include batch_step_execution_ids.")
+            if not self.yield_reconciliation_record_ids:
+                raise ValueError("released batch release workflows must include yield_reconciliation_record_ids.")
+            failed = [item.name for item in self.prerequisites if item.status not in {"Passed", "Waived"}]
+            if failed:
+                raise ValueError(f"released batch release workflows have unresolved prerequisites: {', '.join(failed)}.")
+        if self.status == "Rejected" or self.release_decision == "Rejected":
+            if not self.rejection_reason:
+                raise ValueError("rejected batch release workflows must include rejection_reason.")
+        return self
+
+
+class BatchReleaseWorkflowCreate(BatchReleaseWorkflow):
+    pass
+
+
+class BatchReleaseWorkflowUpdate(BaseModel):
+    status: Optional[BatchReleaseStatus] = None
+    release_decision: Optional[BatchReleaseDecision] = None
+    release_scope: Optional[str] = None
+    bmr_document_ids: Optional[list[str]] = None
+    bpr_document_ids: Optional[list[str]] = None
+    executed_bmr_package: Optional[ExecutedBatchRecordPackage] = None
+    executed_bpr_package: Optional[ExecutedBatchRecordPackage] = None
+    report_template_ids: Optional[list[str]] = None
+    batch_step_execution_ids: Optional[list[str]] = None
+    cleaning_record_ids: Optional[list[str]] = None
+    equipment_usage_ids: Optional[list[str]] = None
+    area_room_usage_ids: Optional[list[str]] = None
+    yield_reconciliation_record_ids: Optional[list[str]] = None
+    cpp_cqa_registry_ids: Optional[list[str]] = None
+    evidence_document_ids: Optional[list[str]] = None
+    prerequisites: Optional[list[BatchReleasePrerequisite]] = None
+    qa_reviewer_id: Optional[str] = None
+    released_by: Optional[str] = None
+    released_at: Optional[datetime] = None
+    rejected_by: Optional[str] = None
+    rejected_at: Optional[datetime] = None
+    rejection_reason: Optional[str] = None
+    signature_ids: Optional[list[str]] = None
+    audit_event_ids: Optional[list[str]] = None
+    metadata: Optional[dict[str, Any]] = None
+    updated_at: datetime = Field(default_factory=utc_now)
+
+    @model_validator(mode="after")
+    def normalize_datetimes(self) -> "BatchReleaseWorkflowUpdate":
+        self.released_at = ensure_utc(self.released_at)
+        self.rejected_at = ensure_utc(self.rejected_at)
+        self.updated_at = ensure_utc(self.updated_at) or utc_now()
+        return self
+
+
+class BatchReleaseWorkflowResponse(BatchReleaseWorkflow):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedBatchReleaseWorkflowResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[BatchReleaseWorkflowResponse]

services/workorders/models/batch_step_executions.py

@@ -0,0 +1,142 @@
+from datetime import datetime, timezone
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, Field, model_validator
+
+
+BatchStepExecutionStatus = Literal[
+    "Planned",
+    "In Progress",
+    "Completed",
+    "Skipped",
+    "Failed",
+    "Rejected",
+]
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def ensure_utc(value: Optional[datetime]) -> Optional[datetime]:
+    if value is None:
+        return None
+    if value.tzinfo is None:
+        return value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc)
+
+
+class BatchStepExecution(BaseModel):
+    batch_step_execution_id: str = Field(..., min_length=1)
+    batch_execution_record_id: str = Field(..., min_length=1)
+    batch_id: str = Field(..., min_length=1)
+    process_definition_id: str = Field(..., min_length=1)
+    process_step_id: str = Field(..., min_length=1)
+    sequence: int = Field(..., ge=1)
+    step_name: str = Field(..., min_length=1)
+    instruction_template_id: Optional[str] = None
+    instruction_step_id: Optional[str] = None
+
+    plant_id: Optional[str] = None
+    line_id: Optional[str] = None
+    stage_id: Optional[str] = None
+    workstation_id: Optional[str] = None
+    equipment_ids: list[str] = Field(default_factory=list)
+    machine_ids: list[str] = Field(default_factory=list)
+
+    operator_id: str = Field(..., min_length=1)
+    operator_name: Optional[str] = None
+    verifier_id: Optional[str] = None
+    verifier_name: Optional[str] = None
+    qa_reviewer_id: Optional[str] = None
+
+    status: BatchStepExecutionStatus = "Planned"
+    started_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    duration_minutes: Optional[float] = Field(default=None, ge=0)
+    actual_values: dict[str, Any] = Field(default_factory=dict)
+    exception_notes: Optional[str] = None
+    deviation_id: Optional[str] = None
+    executed_instruction_evidence_ids: list[str] = Field(default_factory=list)
+    signature_ids: list[str] = Field(default_factory=list)
+    evidence_document_ids: list[str] = Field(default_factory=list)
+    audit_event_ids: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    created_by: Optional[str] = None
+    created_at: datetime = Field(default_factory=utc_now)
+    updated_at: datetime = Field(default_factory=utc_now)
+
+    @model_validator(mode="after")
+    def normalize_and_validate(self) -> "BatchStepExecution":
+        self.started_at = ensure_utc(self.started_at)
+        self.completed_at = ensure_utc(self.completed_at)
+        self.created_at = ensure_utc(self.created_at) or utc_now()
+        self.updated_at = ensure_utc(self.updated_at) or utc_now()
+
+        if self.completed_at and self.started_at and self.completed_at < self.started_at:
+            raise ValueError("completed_at cannot be before started_at for a batch step execution.")
+        if self.duration_minutes is None and self.started_at and self.completed_at:
+            self.duration_minutes = round((self.completed_at - self.started_at).total_seconds() / 60, 4)
+        if self.status == "In Progress" and not self.started_at:
+            raise ValueError("in-progress batch step executions must include started_at.")
+        if self.status == "Completed" and not self.completed_at:
+            raise ValueError("completed batch step executions must include completed_at.")
+        if self.status == "Completed" and not self.signature_ids:
+            raise ValueError("completed batch step executions must include signature_ids.")
+        if self.status in {"Failed", "Rejected"} and not (self.exception_notes or self.deviation_id):
+            raise ValueError("failed/rejected batch step executions must include exception_notes or deviation_id.")
+        return self
+
+
+class BatchStepExecutionCreate(BatchStepExecution):
+    pass
+
+
+class BatchStepExecutionUpdate(BaseModel):
+    step_name: Optional[str] = None
+    instruction_template_id: Optional[str] = None
+    instruction_step_id: Optional[str] = None
+    plant_id: Optional[str] = None
+    line_id: Optional[str] = None
+    stage_id: Optional[str] = None
+    workstation_id: Optional[str] = None
+    equipment_ids: Optional[list[str]] = None
+    machine_ids: Optional[list[str]] = None
+    operator_id: Optional[str] = None
+    operator_name: Optional[str] = None
+    verifier_id: Optional[str] = None
+    verifier_name: Optional[str] = None
+    qa_reviewer_id: Optional[str] = None
+    status: Optional[BatchStepExecutionStatus] = None
+    started_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    duration_minutes: Optional[float] = Field(default=None, ge=0)
+    actual_values: Optional[dict[str, Any]] = None
+    exception_notes: Optional[str] = None
+    deviation_id: Optional[str] = None
+    executed_instruction_evidence_ids: Optional[list[str]] = None
+    signature_ids: Optional[list[str]] = None
+    evidence_document_ids: Optional[list[str]] = None
+    audit_event_ids: Optional[list[str]] = None
+    metadata: Optional[dict[str, Any]] = None
+    updated_at: datetime = Field(default_factory=utc_now)
+
+    @model_validator(mode="after")
+    def normalize_datetimes(self) -> "BatchStepExecutionUpdate":
+        self.started_at = ensure_utc(self.started_at)
+        self.completed_at = ensure_utc(self.completed_at)
+        self.updated_at = ensure_utc(self.updated_at) or utc_now()
+        return self
+
+
+class BatchStepExecutionResponse(BatchStepExecution):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedBatchStepExecutionResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[BatchStepExecutionResponse]

services/workorders/models/equipment_usage_ledger.py

@@ -0,0 +1,144 @@
+from datetime import datetime, timezone
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, Field, model_validator
+
+
+EquipmentUsageStatus = Literal["Planned", "In Use", "Completed", "Aborted", "Rejected"]
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def ensure_utc(dt: Optional[datetime]) -> Optional[datetime]:
+    if dt is None:
+        return None
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
+class EquipmentUsageLedgerEntry(BaseModel):
+    usage_id: str = Field(..., min_length=1)
+    batch_execution_record_id: str = Field(..., min_length=1)
+    batch_id: str = Field(..., min_length=1)
+    process_definition_id: Optional[str] = None
+    process_step_id: str = Field(..., min_length=1)
+    instruction_template_id: Optional[str] = None
+    instruction_step_id: Optional[str] = None
+
+    plant_id: Optional[str] = None
+    line_id: Optional[str] = None
+    stage_id: Optional[str] = None
+    workstation_id: Optional[str] = None
+    machine_id: Optional[str] = None
+    equipment_id: Optional[str] = None
+    asset_name: Optional[str] = None
+
+    operator_id: str = Field(..., min_length=1)
+    operator_name: Optional[str] = None
+    supervisor_id: Optional[str] = None
+    qa_reviewer_id: Optional[str] = None
+
+    status: EquipmentUsageStatus = "Planned"
+    started_at: datetime
+    ended_at: Optional[datetime] = None
+    duration_minutes: Optional[float] = Field(default=None, ge=0)
+    intended_use: Optional[str] = None
+
+    regulated: bool = True
+    gxp_impact: bool = True
+    cleaning_status_snapshot: Optional[str] = None
+    calibration_status_snapshot: Optional[str] = None
+    calibration_due_at_snapshot: Optional[datetime] = None
+    pre_use_checklist_id: Optional[str] = None
+    post_use_checklist_id: Optional[str] = None
+    signature_ids: list[str] = Field(default_factory=list)
+    audit_event_ids: list[str] = Field(default_factory=list)
+    evidence_document_ids: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    created_by: Optional[str] = None
+    created_at: datetime = Field(default_factory=utc_now)
+    updated_at: datetime = Field(default_factory=utc_now)
+
+    @model_validator(mode="after")
+    def normalize_and_validate(self) -> "EquipmentUsageLedgerEntry":
+        self.started_at = ensure_utc(self.started_at) or utc_now()
+        self.ended_at = ensure_utc(self.ended_at)
+        self.calibration_due_at_snapshot = ensure_utc(self.calibration_due_at_snapshot)
+        self.created_at = ensure_utc(self.created_at) or utc_now()
+        self.updated_at = ensure_utc(self.updated_at) or utc_now()
+
+        if not (self.machine_id or self.equipment_id):
+            raise ValueError("equipment usage ledger entries must reference a machine_id or equipment_id.")
+        if self.ended_at and self.ended_at < self.started_at:
+            raise ValueError("ended_at cannot be before started_at for an equipment usage ledger entry.")
+        if self.duration_minutes is None and self.ended_at:
+            elapsed = (self.ended_at - self.started_at).total_seconds() / 60
+            self.duration_minutes = round(max(elapsed, 0), 4)
+        if self.status == "Completed" and not self.ended_at:
+            raise ValueError("completed equipment usage ledger entries must include ended_at.")
+        if self.regulated and self.status == "Completed" and not self.signature_ids:
+            raise ValueError("completed regulated equipment usage entries must include signature_ids.")
+        return self
+
+
+class EquipmentUsageLedgerCreate(EquipmentUsageLedgerEntry):
+    pass
+
+
+class EquipmentUsageLedgerUpdate(BaseModel):
+    process_definition_id: Optional[str] = None
+    process_step_id: Optional[str] = None
+    instruction_template_id: Optional[str] = None
+    instruction_step_id: Optional[str] = None
+    plant_id: Optional[str] = None
+    line_id: Optional[str] = None
+    stage_id: Optional[str] = None
+    workstation_id: Optional[str] = None
+    machine_id: Optional[str] = None
+    equipment_id: Optional[str] = None
+    asset_name: Optional[str] = None
+    operator_id: Optional[str] = None
+    operator_name: Optional[str] = None
+    supervisor_id: Optional[str] = None
+    qa_reviewer_id: Optional[str] = None
+    status: Optional[EquipmentUsageStatus] = None
+    started_at: Optional[datetime] = None
+    ended_at: Optional[datetime] = None
+    duration_minutes: Optional[float] = Field(default=None, ge=0)
+    intended_use: Optional[str] = None
+    regulated: Optional[bool] = None
+    gxp_impact: Optional[bool] = None
+    cleaning_status_snapshot: Optional[str] = None
+    calibration_status_snapshot: Optional[str] = None
+    calibration_due_at_snapshot: Optional[datetime] = None
+    pre_use_checklist_id: Optional[str] = None
+    post_use_checklist_id: Optional[str] = None
+    signature_ids: Optional[list[str]] = None
+    audit_event_ids: Optional[list[str]] = None
+    evidence_document_ids: Optional[list[str]] = None
+    metadata: Optional[dict[str, Any]] = None
+    updated_at: datetime = Field(default_factory=utc_now)
+
+    @model_validator(mode="after")
+    def normalize_datetimes(self) -> "EquipmentUsageLedgerUpdate":
+        self.started_at = ensure_utc(self.started_at)
+        self.ended_at = ensure_utc(self.ended_at)
+        self.calibration_due_at_snapshot = ensure_utc(self.calibration_due_at_snapshot)
+        self.updated_at = ensure_utc(self.updated_at) or utc_now()
+        return self
+
+
+class EquipmentUsageLedgerResponse(EquipmentUsageLedgerEntry):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedEquipmentUsageLedgerResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[EquipmentUsageLedgerResponse]