monkeybrain-runtime 1.0.0__py3-none-any.whl

services/shipping/models/package.py

@@ -0,0 +1,152 @@
+from datetime import date, datetime, timezone
+from decimal import Decimal
+from enum import Enum
+from typing import Annotated, Optional
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field, computed_field, model_validator
+
+from services.shipping.models.delivery_note import DeliveryStatus
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class PackageType(str, Enum):
+    BOX = "box"
+    CARTON = "carton"
+    DRUM = "drum"
+    BAG = "bag"
+    CRATE = "crate"
+    TOTE = "tote"
+    ENVELOPE = "envelope"
+    OTHER = "other"
+
+
+class PackageItem(BaseModel):
+    """Product line packed inside a package."""
+
+    line_number: int = Field(..., ge=1)
+    product_code: str = Field(..., max_length=50)
+    description: str = Field(..., max_length=255)
+    batch_number: Optional[str] = Field(None, max_length=50)
+    serial_number: Optional[str] = Field(None, max_length=100)
+    expiry_date: Optional[date] = None
+    quantity: Annotated[Decimal, Field(gt=0)]
+    uom: str = Field(..., max_length=20)
+    unit_weight_kg: Optional[float] = Field(None, ge=0)
+    hazardous: bool = False
+    un_number: Optional[str] = Field(None, max_length=4)
+
+    model_config = {"str_strip_whitespace": True}
+
+
+class Package(BaseModel):
+    """Individual physical parcel, box, drum, or other container."""
+
+    id: UUID = Field(default_factory=uuid4)
+    package_code: str = Field(..., max_length=80, description="Barcode / tracking reference")
+    package_type: PackageType = PackageType.BOX
+    pallet_id: Optional[str] = Field(None, max_length=100)
+    delivery_note_id: Optional[str] = Field(None, max_length=100)
+    length_mm: Optional[int] = Field(None, gt=0)
+    width_mm: Optional[int] = Field(None, gt=0)
+    height_mm: Optional[int] = Field(None, gt=0)
+    gross_weight_kg: Optional[float] = Field(None, ge=0)
+    net_weight_kg: Optional[float] = Field(None, ge=0)
+    items: list[PackageItem] = Field(default_factory=list)
+    is_fragile: bool = False
+    is_hazardous: bool = False
+    un_number: Optional[str] = Field(None, max_length=4)
+    do_not_stack: bool = False
+    requires_refrigeration: bool = False
+    temp_min_celsius: Optional[float] = None
+    temp_max_celsius: Optional[float] = None
+    tracking_number: Optional[str] = Field(None, max_length=100)
+    status: DeliveryStatus = DeliveryStatus.PENDING
+    notes: Optional[str] = None
+    created_at: datetime = Field(default_factory=utc_now)
+    updated_at: Optional[datetime] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def volume_cm3(self) -> Optional[float]:
+        if self.length_mm and self.width_mm and self.height_mm:
+            return round(self.length_mm * self.width_mm * self.height_mm / 1_000, 2)
+        return None
+
+    @model_validator(mode="after")
+    def hazardous_needs_un(self) -> "Package":
+        if self.is_hazardous and not self.un_number:
+            raise ValueError("un_number required when is_hazardous is True")
+        return self
+
+    @model_validator(mode="after")
+    def refrigeration_range(self) -> "Package":
+        if self.requires_refrigeration:
+            if self.temp_min_celsius is None or self.temp_max_celsius is None:
+                raise ValueError("temp_min/max_celsius required when requires_refrigeration is True")
+            if self.temp_min_celsius >= self.temp_max_celsius:
+                raise ValueError("temp_min_celsius must be less than temp_max_celsius")
+        return self
+
+
+class PackageCreate(Package):
+    pass
+
+
+class PackageUpdate(BaseModel):
+    package_code: Optional[str] = Field(None, max_length=80)
+    package_type: Optional[PackageType] = None
+    pallet_id: Optional[str] = Field(None, max_length=100)
+    delivery_note_id: Optional[str] = Field(None, max_length=100)
+    length_mm: Optional[int] = Field(None, gt=0)
+    width_mm: Optional[int] = Field(None, gt=0)
+    height_mm: Optional[int] = Field(None, gt=0)
+    gross_weight_kg: Optional[float] = Field(None, ge=0)
+    net_weight_kg: Optional[float] = Field(None, ge=0)
+    items: Optional[list[PackageItem]] = None
+    is_fragile: Optional[bool] = None
+    is_hazardous: Optional[bool] = None
+    un_number: Optional[str] = Field(None, max_length=4)
+    do_not_stack: Optional[bool] = None
+    requires_refrigeration: Optional[bool] = None
+    temp_min_celsius: Optional[float] = None
+    temp_max_celsius: Optional[float] = None
+    tracking_number: Optional[str] = Field(None, max_length=100)
+    status: Optional[DeliveryStatus] = None
+    notes: Optional[str] = None
+    updated_at: Optional[datetime] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+    @model_validator(mode="after")
+    def hazardous_needs_un(self) -> "PackageUpdate":
+        if self.is_hazardous is True and not self.un_number:
+            raise ValueError("un_number required when is_hazardous is True")
+        return self
+
+    @model_validator(mode="after")
+    def refrigeration_range(self) -> "PackageUpdate":
+        if self.requires_refrigeration is True:
+            if self.temp_min_celsius is None or self.temp_max_celsius is None:
+                raise ValueError("temp_min/max_celsius required when requires_refrigeration is True")
+        if self.temp_min_celsius is not None and self.temp_max_celsius is not None:
+            if self.temp_min_celsius >= self.temp_max_celsius:
+                raise ValueError("temp_min_celsius must be less than temp_max_celsius")
+        return self
+
+
+class PackageResponse(Package):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedPackageResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[PackageResponse]

services/shipping/models/pallet.py

@@ -0,0 +1,137 @@
+from decimal import Decimal
+from enum import Enum
+from typing import Annotated, Optional
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field, computed_field, model_validator
+
+
+class PalletType(str, Enum):
+    EURO = "euro"
+    STANDARD = "standard"
+    BLOCK = "block"
+    STRINGER = "stringer"
+    PLASTIC = "plastic"
+    CUSTOM = "custom"
+
+
+class PalletCondition(str, Enum):
+    GOOD = "good"
+    DAMAGED = "damaged"
+    REPAIRED = "repaired"
+    QUARANTINED = "quarantined"
+    DISPOSED = "disposed"
+
+
+class PalletDimensions(BaseModel):
+    """Physical pallet dimensions (millimetres)."""
+
+    length_mm: Annotated[int, Field(gt=0)]
+    width_mm: Annotated[int, Field(gt=0)]
+    height_mm: Annotated[int, Field(gt=0)]
+
+
+class PalletContent(BaseModel):
+    """Line item loaded onto a pallet."""
+
+    line_number: int = Field(..., ge=1)
+    product_code: str = Field(..., min_length=1, max_length=50)
+    product_description: str = Field(..., max_length=255)
+    batch_number: Optional[str] = Field(None, max_length=50)
+    quantity: Annotated[Decimal, Field(gt=0)]
+    unit_of_measure: str = Field(..., max_length=20, examples=["EA", "KG", "L", "M"])
+    gross_weight_kg: Optional[Annotated[float, Field(ge=0)]] = None
+    net_weight_kg: Optional[Annotated[float, Field(ge=0)]] = None
+    hazardous: bool = False
+    un_number: Optional[str] = Field(
+        None, max_length=4, description="UN hazmat number if hazardous"
+    )
+
+
+class Pallet(BaseModel):
+    """Individual pallet / loading unit."""
+
+    id: UUID = Field(default_factory=uuid4)
+    pallet_label: str = Field(..., min_length=1, max_length=50, description="Barcode / SSCC label")
+    pallet_type: PalletType = PalletType.EURO
+    condition: PalletCondition = PalletCondition.GOOD
+    dimensions: Optional[PalletDimensions] = None
+    tare_weight_kg: Optional[Annotated[float, Field(ge=0)]] = None
+    max_load_kg: Optional[Annotated[float, Field(gt=0)]] = None
+    contents: list[PalletContent] = Field(default_factory=list)
+    is_stackable: bool = True
+    stack_limit: Optional[int] = Field(None, ge=1, description="Max units that can be stacked on top")
+    stretch_wrapped: bool = False
+    temperature_controlled: bool = False
+    temperature_min_celsius: Optional[float] = None
+    temperature_max_celsius: Optional[float] = None
+    notes: Optional[str] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def total_gross_weight_kg(self) -> float:
+        tare = self.tare_weight_kg or 0.0
+        payload = sum(c.gross_weight_kg or 0 for c in self.contents)
+        return round(tare + payload, 3)
+
+    @model_validator(mode="after")
+    def validate_temperature_fields(self) -> "Pallet":
+        if self.temperature_controlled:
+            if self.temperature_min_celsius is None or self.temperature_max_celsius is None:
+                raise ValueError(
+                    "temperature_min_celsius and temperature_max_celsius are required "
+                    "when temperature_controlled is True"
+                )
+            if self.temperature_min_celsius >= self.temperature_max_celsius:
+                raise ValueError("temperature_min_celsius must be less than temperature_max_celsius")
+        return self
+
+
+class PalletCreate(Pallet):
+    pass
+
+
+class PalletUpdate(BaseModel):
+    pallet_label: Optional[str] = Field(None, min_length=1, max_length=50)
+    pallet_type: Optional[PalletType] = None
+    condition: Optional[PalletCondition] = None
+    dimensions: Optional[PalletDimensions] = None
+    tare_weight_kg: Optional[Annotated[float, Field(ge=0)]] = None
+    max_load_kg: Optional[Annotated[float, Field(gt=0)]] = None
+    contents: Optional[list[PalletContent]] = None
+    is_stackable: Optional[bool] = None
+    stack_limit: Optional[int] = Field(None, ge=1)
+    stretch_wrapped: Optional[bool] = None
+    temperature_controlled: Optional[bool] = None
+    temperature_min_celsius: Optional[float] = None
+    temperature_max_celsius: Optional[float] = None
+    notes: Optional[str] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+    @model_validator(mode="after")
+    def validate_temperature_fields(self) -> "PalletUpdate":
+        if self.temperature_controlled is True:
+            if self.temperature_min_celsius is None or self.temperature_max_celsius is None:
+                raise ValueError(
+                    "temperature_min_celsius and temperature_max_celsius are required "
+                    "when temperature_controlled is True"
+                )
+        if self.temperature_min_celsius is not None and self.temperature_max_celsius is not None:
+            if self.temperature_min_celsius >= self.temperature_max_celsius:
+                raise ValueError("temperature_min_celsius must be less than temperature_max_celsius")
+        return self
+
+
+class PalletResponse(Pallet):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedPalletResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[PalletResponse]

services/shipping/models/route.py

@@ -0,0 +1,120 @@
+from datetime import date, datetime, timezone
+from enum import Enum
+from typing import Optional
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field, model_validator
+
+from services.shipping.models.carrier import Address
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class RouteStopType(str, Enum):
+    PICKUP = "pickup"
+    DELIVERY = "delivery"
+    TRANSFER = "transfer"
+    RETURN = "return"
+    DEPOT = "depot"
+    BREAK = "break"
+
+
+class GeoCoordinate(BaseModel):
+    latitude: float = Field(..., ge=-90, le=90)
+    longitude: float = Field(..., ge=-180, le=180)
+
+
+class RouteStop(BaseModel):
+    """A single stop on a planned delivery route."""
+
+    stop_sequence: int = Field(..., ge=1)
+    stop_type: RouteStopType
+    name: str = Field(..., max_length=200)
+    address: Address
+    coordinates: Optional[GeoCoordinate] = None
+    planned_arrival: Optional[datetime] = None
+    planned_departure: Optional[datetime] = None
+    actual_arrival: Optional[datetime] = None
+    actual_departure: Optional[datetime] = None
+    delivery_note_ids: list[str] = Field(default_factory=list)
+    pallet_ids_to_load: list[str] = Field(default_factory=list)
+    pallet_ids_to_unload: list[str] = Field(default_factory=list)
+    contact_name: Optional[str] = Field(None, max_length=150)
+    contact_phone: Optional[str] = Field(None, max_length=30)
+    special_instructions: Optional[str] = None
+    completed: bool = False
+
+
+class Route(BaseModel):
+    """Planned multi-stop delivery route assigned to a vehicle and driver."""
+
+    id: UUID = Field(default_factory=uuid4)
+    route_reference: str = Field(..., min_length=1, max_length=80)
+    planned_date: date
+    vehicle_id: Optional[str] = Field(None, max_length=100)
+    driver_id: Optional[str] = Field(None, max_length=100)
+    carrier_id: Optional[str] = Field(None, max_length=100)
+    stops: list[RouteStop] = Field(default_factory=list, min_length=1)
+    total_distance_km: Optional[float] = Field(None, ge=0)
+    estimated_duration_hours: Optional[float] = Field(None, ge=0)
+    actual_distance_km: Optional[float] = Field(None, ge=0)
+    actual_duration_hours: Optional[float] = Field(None, ge=0)
+    fuel_consumption_l: Optional[float] = Field(None, ge=0)
+    completed: bool = False
+    notes: Optional[str] = None
+    created_at: datetime = Field(default_factory=utc_now)
+    updated_at: Optional[datetime] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+    @model_validator(mode="after")
+    def stops_in_sequence(self) -> "Route":
+        seqs = [stop.stop_sequence for stop in self.stops]
+        if len(seqs) != len(set(seqs)):
+            raise ValueError("stop_sequence values must be unique within a route")
+        return self
+
+
+class RouteCreate(Route):
+    pass
+
+
+class RouteUpdate(BaseModel):
+    route_reference: Optional[str] = Field(None, min_length=1, max_length=80)
+    planned_date: Optional[date] = None
+    vehicle_id: Optional[str] = Field(None, max_length=100)
+    driver_id: Optional[str] = Field(None, max_length=100)
+    carrier_id: Optional[str] = Field(None, max_length=100)
+    stops: Optional[list[RouteStop]] = Field(None, min_length=1)
+    total_distance_km: Optional[float] = Field(None, ge=0)
+    estimated_duration_hours: Optional[float] = Field(None, ge=0)
+    actual_distance_km: Optional[float] = Field(None, ge=0)
+    actual_duration_hours: Optional[float] = Field(None, ge=0)
+    fuel_consumption_l: Optional[float] = Field(None, ge=0)
+    completed: Optional[bool] = None
+    notes: Optional[str] = None
+    updated_at: Optional[datetime] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+    @model_validator(mode="after")
+    def stops_in_sequence(self) -> "RouteUpdate":
+        if self.stops is not None:
+            seqs = [stop.stop_sequence for stop in self.stops]
+            if len(seqs) != len(set(seqs)):
+                raise ValueError("stop_sequence values must be unique within a route")
+        return self
+
+
+class RouteResponse(Route):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedRouteResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[RouteResponse]

services/shipping/models/shipping_information.py

@@ -0,0 +1,55 @@
+from datetime import datetime, timezone
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+def datetime_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class ShippingInformation(BaseModel):
+    order_id: str = Field(..., description="Unique identifier for the order")
+    shipping_id: str = Field(..., description="Unique identifier for the shipping record")
+    shipping_address: str = Field(..., description="Address where the component is being shipped to")
+    shipping_date: Optional[datetime] = Field(None, description="Date when the component was shipped")
+    expected_delivery_date: Optional[datetime] = Field(None, description="Date when the shipment is expected to arrive")
+    shipping_method: Optional[str] = Field(None, description="Method of shipment, for example Air, Sea, or Ground")
+    tracking_number: Optional[str] = Field(None, description="Tracking number provided by the shipping carrier")
+    carrier_name: Optional[str] = Field(None, description="Name of the shipping carrier or service")
+    shipment_status: Optional[str] = Field(None, description="Current status of the shipment")
+    weight: Optional[float] = Field(None, description="Weight of the shipment in kilograms")
+    shipping_cost: Optional[float] = Field(None, description="Cost of shipping the component")
+    insurance_details: Optional[str] = Field(None, description="Details about any insurance coverage for the shipment")
+    remarks: Optional[str] = Field(None, description="Additional notes or comments related to the shipment")
+
+
+class ShippingInformationCreate(ShippingInformation):
+    pass
+
+
+class ShippingInformationUpdate(BaseModel):
+    order_id: Optional[str] = None
+    shipping_address: Optional[str] = None
+    shipping_date: Optional[datetime] = None
+    expected_delivery_date: Optional[datetime] = None
+    shipping_method: Optional[str] = None
+    tracking_number: Optional[str] = None
+    carrier_name: Optional[str] = None
+    shipment_status: Optional[str] = None
+    weight: Optional[float] = None
+    shipping_cost: Optional[float] = None
+    insurance_details: Optional[str] = None
+    remarks: Optional[str] = None
+
+
+class ShippingInformationResponse(ShippingInformation):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedShippingInformationResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[ShippingInformationResponse]

services/shipping/models/shipping_provider_details.py

@@ -0,0 +1,42 @@
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class ShippingProviderDetails(BaseModel):
+    provider_id: str = Field(..., description="Unique identifier for the shipping provider")
+    provider_name: str = Field(..., description="Name of the shipping provider or carrier")
+    contact_number: Optional[str] = Field(None, description="Contact phone number for the shipping provider")
+    email_address: Optional[str] = Field(None, description="Email address of the shipping provider")
+    address: Optional[str] = Field(None, description="Physical address of the shipping provider")
+    service_areas: Optional[str] = Field(None, description="Geographic regions or areas serviced by the provider")
+    available_services: Optional[str] = Field(None, description="Details of shipping services offered, for example Air Freight or Express Delivery")
+    rating: Optional[float] = Field(None, description="Customer rating of the shipping provider out of 5")
+    website_url: Optional[str] = Field(None, description="Website URL of the shipping provider")
+
+
+class ShippingProviderDetailsCreate(ShippingProviderDetails):
+    pass
+
+
+class ShippingProviderDetailsUpdate(BaseModel):
+    provider_name: Optional[str] = None
+    contact_number: Optional[str] = None
+    email_address: Optional[str] = None
+    address: Optional[str] = None
+    service_areas: Optional[str] = None
+    available_services: Optional[str] = None
+    rating: Optional[float] = None
+    website_url: Optional[str] = None
+
+
+class ShippingProviderDetailsResponse(ShippingProviderDetails):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedShippingProviderDetailsResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[ShippingProviderDetailsResponse]

services/shipping/models/shipping_provider_metadata.py

@@ -0,0 +1,54 @@
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class ShippingProviderMetadata(BaseModel):
+    provider_id: str = Field(..., description="Unique identifier for the shipping provider")
+    base_shipping_rate: Optional[float] = Field(None, description="Base cost for shipping services in the provider's pricing model")
+    cost_per_kg: Optional[float] = Field(None, description="Cost per kilogram for shipping")
+    cost_per_km: Optional[float] = Field(None, description="Cost per kilometer for shipping")
+    surcharge_details: Optional[str] = Field(None, description="Details of any surcharges, for example fuel surcharge or peak season fees")
+    fleet_details: Optional[list[str]] = Field(None, description="Details about the provider's fleet, for example trucks, ships, or drones")
+    average_delivery_time: Optional[str] = Field(None, description="Average delivery time for shipments handled by the provider, for example 3-5 business days")
+    pricing_model: Optional[str] = Field(None, description="Description of the provider's pricing model, for example flat rate, per kilogram, or per distance")
+    insurance_offered: Optional[bool] = Field(None, description="Indicates whether the provider offers insurance for shipments")
+    category: str = Field(..., description="The category of the logistics capability, for example Transportation or Warehousing.")
+    capabilities: str = Field(..., description="Specific capability under the category.")
+    description: str = Field(..., description="A detailed description of the capability.")
+    key_features: list[str] = Field(..., description="Key features of the capability.")
+    certifications: Optional[list[str]] = Field(None, description="Relevant certifications for the capability.")
+    remarks: Optional[str] = Field(None, description="Additional notes or comments related to the provider or capability.")
+
+
+class ShippingProviderMetadataCreate(ShippingProviderMetadata):
+    pass
+
+
+class ShippingProviderMetadataUpdate(BaseModel):
+    base_shipping_rate: Optional[float] = None
+    cost_per_kg: Optional[float] = None
+    cost_per_km: Optional[float] = None
+    surcharge_details: Optional[str] = None
+    fleet_details: Optional[list[str]] = None
+    average_delivery_time: Optional[str] = None
+    pricing_model: Optional[str] = None
+    insurance_offered: Optional[bool] = None
+    category: Optional[str] = None
+    capabilities: Optional[str] = None
+    description: Optional[str] = None
+    key_features: Optional[list[str]] = None
+    certifications: Optional[list[str]] = None
+    remarks: Optional[str] = None
+
+
+class ShippingProviderMetadataResponse(ShippingProviderMetadata):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedShippingProviderMetadataResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[ShippingProviderMetadataResponse]

services/shipping/models/vehicle.py

@@ -0,0 +1,129 @@
+from datetime import date, datetime, timezone
+from enum import Enum
+from typing import Annotated, Optional
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field, model_validator
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class VehicleType(str, Enum):
+    VAN = "van"
+    BOX_TRUCK = "box_truck"
+    FLATBED = "flatbed"
+    REFRIGERATED_TRUCK = "refrigerated_truck"
+    TANKER = "tanker"
+    TRAILER = "trailer"
+    CONTAINER = "container"
+    OTHER = "other"
+
+
+class VehicleDimensions(BaseModel):
+    """Internal cargo dimensions (metres)."""
+
+    length_m: Annotated[float, Field(gt=0, le=25)]
+    width_m: Annotated[float, Field(gt=0, le=5)]
+    height_m: Annotated[float, Field(gt=0, le=5)]
+
+    @property
+    def volume_m3(self) -> float:
+        return round(self.length_m * self.width_m * self.height_m, 4)
+
+
+class Vehicle(BaseModel):
+    """Transport vehicle belonging to a carrier or manufacturer fleet."""
+
+    id: UUID = Field(default_factory=uuid4)
+    carrier_id: Optional[str] = Field(None, description="Owning carrier; None = own fleet")
+    vehicle_type: VehicleType
+    registration_plate: str = Field(..., min_length=1, max_length=20)
+    vin: Optional[str] = Field(None, min_length=17, max_length=17, description="Vehicle Identification Number")
+    make: Optional[str] = Field(None, max_length=50)
+    model: Optional[str] = Field(None, max_length=50)
+    year: Optional[int] = Field(None, ge=1900, le=2100)
+    max_payload_kg: Annotated[float, Field(gt=0)]
+    max_volume_m3: Optional[Annotated[float, Field(gt=0)]] = None
+    cargo_dimensions: Optional[VehicleDimensions] = None
+    has_tail_lift: bool = False
+    is_refrigerated: bool = False
+    temperature_range_celsius: Optional[tuple[float, float]] = Field(
+        None, description="Min and max temp if refrigerated"
+    )
+    driver_name: Optional[str] = Field(None, max_length=150)
+    driver_license_number: Optional[str] = Field(None, max_length=50)
+    driver_phone: Optional[str] = Field(None, max_length=30)
+    mot_expiry: Optional[date] = Field(None, description="MOT / roadworthiness certificate expiry")
+    insurance_expiry: Optional[date] = None
+    gps_tracker_id: Optional[str] = Field(None, max_length=100)
+    active: bool = True
+    notes: Optional[str] = None
+    created_at: datetime = Field(default_factory=utc_now)
+    updated_at: Optional[datetime] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+    @model_validator(mode="after")
+    def validate_temperature_range(self) -> "Vehicle":
+        if self.is_refrigerated and self.temperature_range_celsius is None:
+            raise ValueError("temperature_range_celsius is required for refrigerated vehicles")
+        if self.temperature_range_celsius is not None:
+            low, high = self.temperature_range_celsius
+            if low >= high:
+                raise ValueError("temperature_range_celsius[0] must be less than [1]")
+        return self
+
+
+class VehicleCreate(Vehicle):
+    pass
+
+
+class VehicleUpdate(BaseModel):
+    carrier_id: Optional[UUID] = None
+    vehicle_type: Optional[VehicleType] = None
+    registration_plate: Optional[str] = Field(None, min_length=1, max_length=20)
+    vin: Optional[str] = Field(None, min_length=17, max_length=17)
+    make: Optional[str] = Field(None, max_length=50)
+    model: Optional[str] = Field(None, max_length=50)
+    year: Optional[int] = Field(None, ge=1900, le=2100)
+    max_payload_kg: Optional[Annotated[float, Field(gt=0)]] = None
+    max_volume_m3: Optional[Annotated[float, Field(gt=0)]] = None
+    cargo_dimensions: Optional[VehicleDimensions] = None
+    has_tail_lift: Optional[bool] = None
+    is_refrigerated: Optional[bool] = None
+    temperature_range_celsius: Optional[tuple[float, float]] = None
+    driver_name: Optional[str] = Field(None, max_length=150)
+    driver_license_number: Optional[str] = Field(None, max_length=50)
+    driver_phone: Optional[str] = Field(None, max_length=30)
+    mot_expiry: Optional[date] = None
+    insurance_expiry: Optional[date] = None
+    gps_tracker_id: Optional[str] = Field(None, max_length=100)
+    active: Optional[bool] = None
+    notes: Optional[str] = None
+    updated_at: Optional[datetime] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+    @model_validator(mode="after")
+    def validate_temperature_range(self) -> "VehicleUpdate":
+        if self.is_refrigerated is True and self.temperature_range_celsius is None:
+            raise ValueError("temperature_range_celsius is required for refrigerated vehicles")
+        if self.temperature_range_celsius is not None:
+            low, high = self.temperature_range_celsius
+            if low >= high:
+                raise ValueError("temperature_range_celsius[0] must be less than [1]")
+        return self
+
+
+class VehicleResponse(Vehicle):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedVehicleResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[VehicleResponse]