monkeybrain-runtime 1.0.0__py3-none-any.whl

services/inventory/models/inventory_items.py

@@ -0,0 +1,168 @@
+from decimal import Decimal
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class InventoryItemModel(BaseModel):
+    # Primary identifiers
+    sku: str = Field(
+        ...,
+        description="Stock Keeping Unit. Unique alphanumeric identifier.",
+        min_length=3,
+        max_length=50,
+    )
+    name: str = Field(..., description="Name of the inventory item.", min_length=1)
+    description: str | None = Field(None, description="Detailed product description.")
+    category: str = Field(
+        ...,
+        description="Product category (e.g., Raw Materials, Electronics, Packaging).",
+    )
+
+    # Stock quantities and multi-location
+    warehouse_id: str = Field(
+        ...,
+        description="ID of the physical warehouse holding this stock.",
+    )
+    bin_location: str | None = Field(
+        None,
+        description="Specific aisle/shelf/bin location within the warehouse.",
+    )
+    quantity_on_hand: int = Field(
+        0,
+        description="Physical inventory currently present in the warehouse.",
+        ge=0,
+    )
+    quantity_allocated: int = Field(
+        0,
+        description="Stock reserved for pending customer orders.",
+        ge=0,
+    )
+    quantity_available: int = Field(
+        0,
+        description="Net stock available for new orders (On Hand - Allocated).",
+        ge=0,
+    )
+
+    # Reorder points and thresholds
+    reorder_point: int = Field(
+        ...,
+        description="Minimum stock level that triggers an automatic reorder alert.",
+        ge=0,
+    )
+    max_stock_level: int = Field(
+        ...,
+        description="Maximum storage capacity for this item to prevent overstocking.",
+        ge=1,
+    )
+    lead_time_days: int = Field(
+        14,
+        description="Average days required to receive stock from the supplier after ordering.",
+        ge=0,
+    )
+
+    # Financial and valuation metrics
+    cost_price: Decimal = Field(
+        ...,
+        description="Unit cost paid to the supplier.",
+        ge=Decimal("0.00"),
+    )
+    retail_price: Decimal = Field(
+        ...,
+        description="Standard selling price to consumers.",
+        ge=Decimal("0.00"),
+    )
+    currency: str = Field(
+        "USD",
+        description="Three-letter ISO currency code.",
+        min_length=3,
+        max_length=3,
+    )
+
+    # Supplier linkage
+    supplier_id: str = Field(
+        ...,
+        description="Associated supplier ID managing this capability/product.",
+    )
+
+    # Status flags
+    is_active: bool = Field(
+        True,
+        description="Indicates if the item is actively being sold or ordered.",
+    )
+    requires_inspection: bool = Field(
+        False,
+        description="Flag for whether incoming stock needs Quality Assurance testing.",
+    )
+
+    # System timestamps
+    last_counted_at: datetime | None = Field(
+        None,
+        description="Timestamp of the last physical inventory audit/cycle count.",
+    )
+
+    @field_validator("quantity_available")
+    @classmethod
+    def validate_available_qty(cls, value: int, info) -> int:
+        data = info.data
+        if "quantity_on_hand" in data and "quantity_allocated" in data:
+            expected = data["quantity_on_hand"] - data["quantity_allocated"]
+            if value != expected:
+                raise ValueError(
+                    f"quantity_available ({value}) must equal "
+                    f"quantity_on_hand - quantity_allocated ({expected})"
+                )
+        return value
+
+    @field_validator("max_stock_level")
+    @classmethod
+    def validate_stock_ceilings(cls, value: int, info) -> int:
+        data = info.data
+        if "reorder_point" in data and value <= data["reorder_point"]:
+            raise ValueError("max_stock_level must be greater than the reorder_point")
+        return value
+
+
+class InventoryItemCreate(InventoryItemModel):
+    """Schema for POST requests to create inventory."""
+
+
+class InventoryItemUpdate(BaseModel):
+    """Schema for PATCH requests. All fields are optional for partial updates."""
+
+    name: str | None = None
+    description: str | None = None
+    category: str | None = None
+    warehouse_id: str | None = None
+    bin_location: str | None = None
+    quantity_on_hand: int | None = None
+    quantity_allocated: int | None = None
+    quantity_available: int | None = None
+    reorder_point: int | None = None
+    max_stock_level: int | None = None
+    lead_time_days: int | None = None
+    cost_price: Decimal | None = None
+    retail_price: Decimal | None = None
+    currency: str | None = None
+    supplier_id: str | None = None
+    is_active: bool | None = None
+    requires_inspection: bool | None = None
+    last_counted_at: datetime | None = None
+
+
+class InventoryItemResponse(InventoryItemModel):
+    """Schema for standard API responses, including system tracking IDs."""
+
+    id: str = Field(..., description="Unique database item record ID.")
+    updated_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class PaginatedInventoryResponse(BaseModel):
+    """Schema for listing paginated stock indexes."""
+
+    total: int
+    page: int
+    page_size: int
+    results: list[InventoryItemResponse]

services/inventory/models/inventory_responses.py

@@ -0,0 +1,44 @@
+from typing import Optional
+
+from pydantic import BaseModel
+
+from services.inventory.models.inventory_enums import InventoryStatus
+from services.inventory.models.inventory_state import ProductInventoryRecord
+from services.inventory.models.inventory_transactions import InventoryTransactionRecord
+
+
+class PaginatedProductInventoryResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[ProductInventoryRecord]
+
+
+class PaginatedInventoryTransactionResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[InventoryTransactionRecord]
+
+
+class InventorySummaryLocation(BaseModel):
+    location_id: str
+    location_name: str
+    on_hand: float
+    available: float
+    status: InventoryStatus
+
+
+class InventorySummary(BaseModel):
+    product_id: str
+    sku: str
+    product_name: str
+    total_on_hand: float
+    total_reserved: float
+    total_available: float
+    total_incoming: float
+    locations_count: int
+    locations: list[InventorySummaryLocation]
+    is_below_reorder: bool
+    estimated_reorder_value: Optional[float] = None
+    currency: str

services/inventory/models/inventory_stage_outputs.py

@@ -0,0 +1,96 @@
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from services.products.models.product_common import utc_now
+
+
+class StageOutputUnitOfMeasure(str, Enum):
+    PIECE = "piece"
+    BOX = "box"
+    PALLET = "pallet"
+    KG = "kg"
+    LITER = "liter"
+    OTHER = "other"
+
+
+class InventoryStageOutputBase(BaseModel):
+    product_id: str = Field(..., min_length=1)
+    sku: str = Field(..., min_length=1, description="Stock Keeping Unit")
+    stage_id: str = Field(..., min_length=1)
+    stage_name: str | None = None
+    workstation_id: str | None = None
+    line_id: str | None = None
+
+    stage_count: int | None = Field(default=None, ge=0)
+    stage_quantity: float | None = Field(default=None, ge=0)
+    unit_of_measure: StageOutputUnitOfMeasure = StageOutputUnitOfMeasure.PIECE
+
+    is_final_stage: bool = False
+    final_product_count: int | None = Field(default=None, ge=0)
+    final_product_quantity: float | None = Field(default=None, ge=0)
+
+    recorded_by: str | None = None
+    recorded_at: datetime = Field(default_factory=utc_now)
+    notes: str | None = None
+    metadata: dict[str, Any] | None = None
+
+    @model_validator(mode="after")
+    def validate_stage_and_final_output(self):
+        if self.stage_count is None and self.stage_quantity is None:
+            raise ValueError("Provide at least one of: stage_count or stage_quantity")
+
+        if self.is_final_stage:
+            has_final_count = self.final_product_count is not None
+            has_final_quantity = self.final_product_quantity is not None
+            if not has_final_count and not has_final_quantity:
+                raise ValueError(
+                    "Final stage records require final_product_count or "
+                    "final_product_quantity"
+                )
+        elif self.final_product_count is not None or self.final_product_quantity is not None:
+            raise ValueError(
+                "final_product_count/final_product_quantity require is_final_stage=True"
+            )
+
+        return self
+
+
+class InventoryStageOutputCreate(InventoryStageOutputBase):
+    """Schema for recording product count or quantity at a production stage."""
+
+
+class InventoryStageOutputUpdate(BaseModel):
+    product_id: str | None = None
+    sku: str | None = None
+    stage_id: str | None = None
+    stage_name: str | None = None
+    workstation_id: str | None = None
+    line_id: str | None = None
+    stage_count: int | None = Field(default=None, ge=0)
+    stage_quantity: float | None = Field(default=None, ge=0)
+    unit_of_measure: StageOutputUnitOfMeasure | None = None
+    is_final_stage: bool | None = None
+    final_product_count: int | None = Field(default=None, ge=0)
+    final_product_quantity: float | None = Field(default=None, ge=0)
+    recorded_by: str | None = None
+    recorded_at: datetime | None = None
+    notes: str | None = None
+    metadata: dict[str, Any] | None = None
+
+
+class InventoryStageOutputResponse(InventoryStageOutputBase):
+    id: str
+    stage_output_id: str
+    updated_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class PaginatedInventoryStageOutputResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[InventoryStageOutputResponse]

services/inventory/models/inventory_state.py

@@ -0,0 +1,15 @@
+from services.products.models.product_inventory import (
+    PaginatedProductInventoryResponse,
+    ProductInventoryBase,
+    ProductInventoryCreate,
+    ProductInventoryRecord,
+    ProductInventoryUpdate,
+)
+
+__all__ = [
+    "PaginatedProductInventoryResponse",
+    "ProductInventoryBase",
+    "ProductInventoryCreate",
+    "ProductInventoryRecord",
+    "ProductInventoryUpdate",
+]

services/inventory/models/inventory_transactions.py

@@ -0,0 +1,80 @@
+from datetime import date, datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from services.inventory.models.inventory_enums import (
+    InventoryTransactionType,
+    ReferenceType,
+    StockMovementDirection,
+)
+from services.products.models.product_common import ensure_utc, utc_now
+
+
+class InventoryTransactionBase(BaseModel):
+    inventory_id: str
+    product_id: str
+    location_id: str
+    reference_type: Optional[ReferenceType] = None
+    reference_id: Optional[str] = None
+    transaction_type: InventoryTransactionType
+    direction: StockMovementDirection
+    quantity: float = Field(..., gt=0)
+    unit_cost: Optional[float] = Field(default=None, ge=0)
+    batch_number: Optional[str] = None
+    serial_numbers: Optional[list[str]] = None
+    expiry_date: Optional[date] = None
+    from_location_id: Optional[str] = None
+    to_location_id: Optional[str] = None
+    reason_code: Optional[str] = None
+    notes: Optional[str] = None
+
+    @field_validator("direction", mode="before")
+    @classmethod
+    def normalize_direction(cls, value):
+        if isinstance(value, str):
+            return value.strip().lower()
+        return value
+
+
+class InventoryTransactionRecord(InventoryTransactionBase):
+    transaction_id: str
+    total_value: Optional[float] = None
+    posted: bool = False
+    posted_at: Optional[datetime] = None
+    created_by: Optional[str] = None
+    updated_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 compute_values(self) -> "InventoryTransactionRecord":
+        self.created_at = ensure_utc(self.created_at)
+        self.updated_at = ensure_utc(self.updated_at)
+        self.posted_at = ensure_utc(self.posted_at)
+
+        if self.unit_cost is not None:
+            self.total_value = round(self.quantity * self.unit_cost, 2)
+        return self
+
+
+class InventoryTransactionCreate(InventoryTransactionBase):
+    pass
+
+
+class InventoryTransactionUpdate(BaseModel):
+    reference_type: Optional[ReferenceType] = None
+    reference_id: Optional[str] = None
+    transaction_type: Optional[InventoryTransactionType] = None
+    direction: Optional[StockMovementDirection] = None
+    quantity: Optional[float] = Field(default=None, gt=0)
+    unit_cost: Optional[float] = Field(default=None, ge=0)
+    notes: Optional[str] = None
+    updated_by: Optional[str] = None
+
+    @field_validator("direction", mode="before")
+    @classmethod
+    def normalize_direction(cls, value):
+        if isinstance(value, str):
+            return value.strip().lower()
+        return value

services/inventory/models/stock_adjustment_requests.py

@@ -0,0 +1,109 @@
+from datetime import date, datetime
+from enum import Enum
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+from services.inventory.models.inventory_enums import AdjustmentStatus, AdjustmentType, ReferenceType
+from services.products.models.product_common import utc_now
+
+
+class StockAdjustmentItemType(str, Enum):
+    PRODUCT = "product"
+    COMPONENT = "component"
+    SPARE_PART = "spare_part"
+    RAW_MATERIAL = "raw_material"
+
+
+class StockAdjustmentRequest(BaseModel):
+    request_id: str
+    item_type: StockAdjustmentItemType = StockAdjustmentItemType.RAW_MATERIAL
+    inventory_id: str
+    product_id: str
+    location_id: str
+    adjustment_type: AdjustmentType
+    quantity: float = Field(..., gt=0)
+    reason: str
+    reference: Optional[ReferenceType] = Field(
+        None,
+        json_schema_extra={
+            "placeholder": "Select reference type",
+            "ui_widget": "select",
+        },
+    )
+    batch_number: Optional[str] = None
+    serial_numbers: Optional[list[str]] = None
+    expiry_date: Optional[date] = None
+    status: AdjustmentStatus = "Pending"
+    approved_by: Optional[str] = None
+    approved_at: Optional[datetime] = None
+    rejected_reason: Optional[str] = None
+    notes: Optional[str] = None
+    metadata: Optional[dict[str, Any]] = None
+    requested_by: str
+    created_at: datetime = Field(default_factory=utc_now)
+    updated_at: datetime = Field(default_factory=utc_now)
+
+    @field_validator("approved_at", mode="before")
+    @classmethod
+    def blank_optional_datetime_to_none(cls, value):
+        if value == "":
+            return None
+        return value
+
+    @field_validator("created_at", "updated_at", mode="before")
+    @classmethod
+    def blank_timestamp_to_now(cls, value):
+        if value == "":
+            return utc_now()
+        return value
+
+
+class StockAdjustmentRequestCreate(StockAdjustmentRequest):
+    pass
+
+
+class StockAdjustmentRequestUpdate(BaseModel):
+    item_type: Optional[StockAdjustmentItemType] = None
+    inventory_id: Optional[str] = None
+    product_id: Optional[str] = None
+    location_id: Optional[str] = None
+    adjustment_type: Optional[AdjustmentType] = None
+    quantity: Optional[float] = Field(default=None, gt=0)
+    reason: Optional[str] = None
+    reference: Optional[ReferenceType] = Field(
+        None,
+        json_schema_extra={
+            "placeholder": "Select reference type",
+            "ui_widget": "select",
+        },
+    )
+    batch_number: Optional[str] = None
+    serial_numbers: Optional[list[str]] = None
+    expiry_date: Optional[date] = None
+    status: Optional[AdjustmentStatus] = None
+    approved_by: Optional[str] = None
+    approved_at: Optional[datetime] = None
+    rejected_reason: Optional[str] = None
+    notes: Optional[str] = None
+    metadata: Optional[dict[str, Any]] = None
+    requested_by: Optional[str] = None
+
+    @field_validator("approved_at", mode="before")
+    @classmethod
+    def blank_optional_datetime_to_none(cls, value):
+        if value == "":
+            return None
+        return value
+
+
+class StockAdjustmentRequestResponse(StockAdjustmentRequest):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedStockAdjustmentRequestResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[StockAdjustmentRequestResponse]

services/inventory/models/warehouse_cycle_counts.py

@@ -0,0 +1,119 @@
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from services.products.models.product_common import utc_now
+
+
+class CycleCountScope(str, Enum):
+    WAREHOUSE = "warehouse"
+    LOCATION = "location"
+    BIN = "bin"
+    SKU = "sku"
+
+
+class CycleCountStatus(str, Enum):
+    PLANNED = "planned"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    CANCELLED = "cancelled"
+
+
+class WarehouseCycleCountBase(BaseModel):
+    warehouse_id: str = Field(..., min_length=1)
+    cycle_count_number: str | None = None
+    scope: CycleCountScope = CycleCountScope.WAREHOUSE
+    status: CycleCountStatus = CycleCountStatus.PLANNED
+
+    location_id: str | None = None
+    bin_location: str | None = None
+    sku: str | None = None
+    product_id: str | None = None
+
+    expected_count: int | None = Field(default=None, ge=0)
+    counted_count: int | None = Field(default=None, ge=0)
+    expected_quantity: float | None = Field(default=None, ge=0)
+    counted_quantity: float | None = Field(default=None, ge=0)
+    unit_of_measure: str | None = None
+
+    variance_count: int | None = None
+    variance_quantity: float | None = None
+
+    scheduled_at: datetime | None = None
+    started_at: datetime | None = None
+    completed_at: datetime | None = None
+    counted_by: str | None = None
+    approved_by: str | None = None
+    notes: str | None = None
+    metadata: dict[str, Any] | None = None
+
+    created_at: datetime = Field(default_factory=utc_now)
+
+    @model_validator(mode="after")
+    def compute_variances(self):
+        if self.scope == CycleCountScope.LOCATION and not self.location_id:
+            raise ValueError("location_id is required when scope is location")
+        if self.scope == CycleCountScope.BIN and not self.bin_location:
+            raise ValueError("bin_location is required when scope is bin")
+        if self.scope == CycleCountScope.SKU and not self.sku:
+            raise ValueError("sku is required when scope is sku")
+
+        has_count = self.expected_count is not None or self.counted_count is not None
+        has_quantity = (
+            self.expected_quantity is not None or self.counted_quantity is not None
+        )
+        if not has_count and not has_quantity:
+            raise ValueError("Provide count or quantity fields for the cycle count")
+
+        if self.expected_count is not None and self.counted_count is not None:
+            self.variance_count = self.counted_count - self.expected_count
+        if self.expected_quantity is not None and self.counted_quantity is not None:
+            self.variance_quantity = round(
+                self.counted_quantity - self.expected_quantity,
+                4,
+            )
+        return self
+
+
+class WarehouseCycleCountCreate(WarehouseCycleCountBase):
+    """Schema for creating warehouse cycle count records."""
+
+
+class WarehouseCycleCountUpdate(BaseModel):
+    warehouse_id: str | None = None
+    cycle_count_number: str | None = None
+    scope: CycleCountScope | None = None
+    status: CycleCountStatus | None = None
+    location_id: str | None = None
+    bin_location: str | None = None
+    sku: str | None = None
+    product_id: str | None = None
+    expected_count: int | None = Field(default=None, ge=0)
+    counted_count: int | None = Field(default=None, ge=0)
+    expected_quantity: float | None = Field(default=None, ge=0)
+    counted_quantity: float | None = Field(default=None, ge=0)
+    unit_of_measure: str | None = None
+    scheduled_at: datetime | None = None
+    started_at: datetime | None = None
+    completed_at: datetime | None = None
+    counted_by: str | None = None
+    approved_by: str | None = None
+    notes: str | None = None
+    metadata: dict[str, Any] | None = None
+
+
+class WarehouseCycleCountResponse(WarehouseCycleCountBase):
+    id: str
+    cycle_count_id: str
+    updated_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class PaginatedWarehouseCycleCountResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[WarehouseCycleCountResponse]