fba-bench-core 1.0.0__py3-none-any.whl

fba_bench_core/domain/__init__.py

@@ -0,0 +1,75 @@
+"""Domain package exports for fba_bench_core.
+
+This module exposes the core domain contracts and the expanded event/command
+vocabulary introduced in Phase C.
+"""
+
+from .events import (  # Base types; Events; Commands; helpers
+    AdjustFulfillmentLatencyCommand,
+    AdjustPriceCommand,
+    AnomalyDetected,
+    AnyCommand,
+    AnyEvent,
+    BaseEvent,
+    Command,
+    CustomerComplaintLogged,
+    DemandSpiked,
+    ForecastUpdated,
+    FulfillmentDelayed,
+    LaunchPromotionCommand,
+    PlaceReplenishmentOrderCommand,
+    PriceChangedExternally,
+    PromotionLaunched,
+    ReforecastDemandCommand,
+    ResolveCustomerIssueCommand,
+    SaleOccurred,
+    StartCustomerOutreachCommand,
+    StockDepleted,
+    StockReplenished,
+    TransferInventoryCommand,
+    UpdateSafetyStockCommand,
+    get_command_class_for_type,
+    get_event_class_for_type,
+)
+from .models import (
+    Competitor,
+    CompetitorListing,
+    DemandProfile,
+    InventorySnapshot,
+    Product,
+)
+
+__all__ = [
+    # models
+    "Product",
+    "InventorySnapshot",
+    "CompetitorListing",
+    "Competitor",
+    "DemandProfile",
+    # events & commands
+    "BaseEvent",
+    "Command",
+    "SaleOccurred",
+    "PriceChangedExternally",
+    "DemandSpiked",
+    "StockReplenished",
+    "StockDepleted",
+    "FulfillmentDelayed",
+    "PromotionLaunched",
+    "CustomerComplaintLogged",
+    "ForecastUpdated",
+    "AnomalyDetected",
+    "AnyEvent",
+    "AdjustPriceCommand",
+    "LaunchPromotionCommand",
+    "PlaceReplenishmentOrderCommand",
+    "TransferInventoryCommand",
+    "UpdateSafetyStockCommand",
+    "ResolveCustomerIssueCommand",
+    "StartCustomerOutreachCommand",
+    "ReforecastDemandCommand",
+    "AdjustFulfillmentLatencyCommand",
+    "AnyCommand",
+    "get_event_class_for_type",
+    "get_command_class_for_type",
+]

fba_bench_core/domain/events/__init__.py

@@ -0,0 +1,230 @@
+"""Compatibility layer for fba_bench_core.domain.events.
+
+This module re-exports all event classes, command classes, unions (AnyEvent, AnyCommand),
+EventType enum, and helper functions from the modular domain/events submodules to
+provide full backward compatibility. Existing code importing from fba_bench_core.domain.events
+will continue to work unchanged.
+
+Do not add new definitions here; maintain only re-exports and registry logic.
+"""
+
+from __future__ import annotations
+
+import re
+from enum import Enum
+
+from .analytics import (
+    AdjustFulfillmentLatencyCommand,
+    AnomalyDetected,
+    ForecastUpdated,
+    NegotiateSupplyCommand,
+    ReforecastDemandCommand,
+)
+from .base import BaseEvent, Command
+from .inventory import (
+    AdjustInventoryCommand,
+    FulfillmentDelayed,
+    PlaceReplenishmentOrderCommand,
+    StockDepleted,
+    StockReplenished,
+    SupplyDisruption,
+    TransferInventoryCommand,
+    UpdateSafetyStockCommand,
+)
+from .marketing import (
+    CustomerComplaintLogged,
+    PromotionLaunched,
+    ResolveCustomerIssueCommand,
+    RespondToComplaintCommand,
+    StartCustomerOutreachCommand,
+)
+from .pricing import (
+    AdjustPriceCommand,
+    CompetitorAction,
+    DemandSpiked,
+    LaunchPromotionCommand,
+    MonitorCompetitorCommand,
+    PriceChangedExternally,
+    SaleOccurred,
+)
+
+# Unions for type checking
+AnyEvent = (
+    SaleOccurred
+    | PriceChangedExternally
+    | DemandSpiked
+    | CompetitorAction
+    | StockReplenished
+    | StockDepleted
+    | FulfillmentDelayed
+    | SupplyDisruption
+    | PromotionLaunched
+    | CustomerComplaintLogged
+    | ForecastUpdated
+    | AnomalyDetected
+)
+
+AnyCommand = (
+    AdjustPriceCommand
+    | LaunchPromotionCommand
+    | PlaceReplenishmentOrderCommand
+    | TransferInventoryCommand
+    | UpdateSafetyStockCommand
+    | AdjustInventoryCommand
+    | ResolveCustomerIssueCommand
+    | StartCustomerOutreachCommand
+    | RespondToComplaintCommand
+    | ReforecastDemandCommand
+    | AdjustFulfillmentLatencyCommand
+    | NegotiateSupplyCommand
+    | MonitorCompetitorCommand
+)
+
+
+# Registry setup (moved from original events.py)
+def _camel_to_snake(name: str) -> str:
+    s1 = re.sub(r"(.)([A-Z][a-z]+)", r"\1_\2", name)
+    s2 = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s1)
+    return s2.replace("__", "_").lower()
+
+
+def _extract_event_type_from_class(cls: type[BaseEvent]) -> str:
+    val = cls.__dict__.get("event_type", None)
+    if isinstance(val, str):
+        return val
+    return _camel_to_snake(cls.__name__)
+
+
+_event_registry: dict[str, type[BaseEvent]] = {
+    _extract_event_type_from_class(cls): cls
+    for cls in (
+        SaleOccurred,
+        PriceChangedExternally,
+        DemandSpiked,
+        CompetitorAction,
+        StockReplenished,
+        StockDepleted,
+        FulfillmentDelayed,
+        SupplyDisruption,
+        PromotionLaunched,
+        CustomerComplaintLogged,
+        ForecastUpdated,
+        AnomalyDetected,
+    )
+}
+
+
+def _extract_command_type_from_class(cls: type[Command]) -> str:
+    val = cls.__dict__.get("command_type", None)
+    if isinstance(val, str):
+        return val
+    return _camel_to_snake(cls.__name__)
+
+
+_command_registry: dict[str, type[Command]] = {}
+for cls in (
+    AdjustPriceCommand,
+    LaunchPromotionCommand,
+    PlaceReplenishmentOrderCommand,
+    TransferInventoryCommand,
+    UpdateSafetyStockCommand,
+    AdjustInventoryCommand,
+    ResolveCustomerIssueCommand,
+    StartCustomerOutreachCommand,
+    RespondToComplaintCommand,
+    ReforecastDemandCommand,
+    AdjustFulfillmentLatencyCommand,
+    NegotiateSupplyCommand,
+    MonitorCompetitorCommand,
+):
+    literal = cls.__dict__.get("command_type")
+    if isinstance(literal, str):
+        _command_registry[literal] = cls
+
+    derived = _camel_to_snake(cls.__name__)
+    _command_registry.setdefault(derived, cls)
+
+    if derived.endswith("_command"):
+        short = derived[: -len("_command")]
+        _command_registry.setdefault(short, cls)
+
+
+# EventType enum (dynamic, derived from the runtime registry)
+def _safe_member_name(s: str) -> str:
+    name = re.sub(r"\W+", "_", s).upper()
+    if not name:
+        name = "UNKNOWN"
+    if name[0].isdigit():
+        name = "_" + name
+    return name
+
+
+_event_type_members = {_safe_member_name(k): k for k in _event_registry.keys()}
+
+EventType = Enum("EventType", _event_type_members, type=str)
+
+# Attach metadata to enum members
+for member in EventType:
+    cls = _event_registry.get(member.value)
+    setattr(member, "event_class", cls)
+    setattr(
+        member,
+        "metadata",
+        {
+            "event_class": cls,
+            "doc": getattr(cls, "__doc__", None),
+            "event_type": member.value,
+        },
+    )
+
+
+# Helper functions
+def get_event_class_for_type(event_type: str) -> type[BaseEvent] | None:
+    """Return the event class for a given event_type or None if unknown."""
+    return _event_registry.get(event_type)
+
+
+def get_command_class_for_type(command_type: str) -> type[Command] | None:
+    """Return the command class for a given command_type or None if unknown."""
+    return _command_registry.get(command_type)
+
+
+__all__ = [
+    # Base types
+    "BaseEvent",
+    "Command",
+    # Events
+    "SaleOccurred",
+    "PriceChangedExternally",
+    "DemandSpiked",
+    "CompetitorAction",
+    "StockReplenished",
+    "StockDepleted",
+    "FulfillmentDelayed",
+    "SupplyDisruption",
+    "PromotionLaunched",
+    "CustomerComplaintLogged",
+    "ForecastUpdated",
+    "AnomalyDetected",
+    "AnyEvent",
+    # Commands
+    "AdjustPriceCommand",
+    "LaunchPromotionCommand",
+    "PlaceReplenishmentOrderCommand",
+    "TransferInventoryCommand",
+    "UpdateSafetyStockCommand",
+    "AdjustInventoryCommand",
+    "ResolveCustomerIssueCommand",
+    "StartCustomerOutreachCommand",
+    "RespondToComplaintCommand",
+    "ReforecastDemandCommand",
+    "AdjustFulfillmentLatencyCommand",
+    "NegotiateSupplyCommand",
+    "MonitorCompetitorCommand",
+    "AnyCommand",
+    # Registries / helpers
+    "get_event_class_for_type",
+    "get_command_class_for_type",
+    # EventType enum
+    "EventType",
+]

fba_bench_core/domain/events/analytics.py

@@ -0,0 +1,69 @@
+"""Analytics and system events and commands."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import ConfigDict, Field
+
+from ..models import DemandProfile
+from .base import BaseEvent, Command
+
+
+class ForecastUpdated(BaseEvent):
+    """Event emitted when a product forecast/demand profile is updated."""
+
+    event_type: Literal["forecast_updated"] = "forecast_updated"
+
+    product_id: str
+    demand_profile: DemandProfile
+
+
+class AnomalyDetected(BaseEvent):
+    """Generic anomaly detection event used by monitoring/analytics.
+
+    - summary: short text describing the anomaly type.
+    - metrics: optional structured metrics that explain the anomaly (small dict).
+    """
+
+    event_type: Literal["anomaly_detected"] = "anomaly_detected"
+
+    summary: str
+    metrics: dict[str, Any] | None = None
+    severity: Literal["low", "medium", "high", "critical"] | None = "low"
+
+
+class ReforecastDemandCommand(Command):
+    """Request to recompute demand forecasts for a product over a timeframe."""
+
+    command_type: Literal["reforecast_demand"] = "reforecast_demand"
+
+    product_id: str
+    timeframe_days: int = Field(..., gt=0)
+    reason: str | None = None
+
+
+class AdjustFulfillmentLatencyCommand(Command):
+    """Command to set or adjust fulfillment latency targets (in days)."""
+
+    command_type: Literal["adjust_fulfillment_latency"] = "adjust_fulfillment_latency"
+
+    product_id: str
+    new_latency_days: int = Field(..., ge=0)
+
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+
+class NegotiateSupplyCommand(Command):
+    """Command to negotiate supply terms with a supplier.
+
+    - negotiation_terms: structured terms being negotiated (e.g., price, lead_time).
+    """
+
+    command_type: Literal["negotiate_supply"] = "negotiate_supply"
+
+    supplier_id: str
+    product_id: str
+    negotiation_terms: dict[str, Any]
+
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")

fba_bench_core/domain/events/base.py

@@ -0,0 +1,59 @@
+"""Base classes for domain events and commands."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class BaseEvent(BaseModel):
+    """Base contract for all domain events.
+
+    Attributes:
+    - event_type: Literal discriminator provided by subclasses.
+    - timestamp: UTC timestamp when the event was recorded (defaults to now).
+    - tick: non-negative simulation or system tick.
+    - correlation_id: optional id to trace this event across services and workflows.
+    """
+
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    event_type: str
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    tick: int = Field(0, ge=0)
+    correlation_id: str | None = None
+
+
+class Command(BaseModel):
+    """Base contract for commands (intent to change system state).
+
+    Commands are issued by agents or systems. Include optional metadata to
+    enable observability and intent tracing:
+    - issued_by: human or system identifier that created the command.
+    - reason: free-text explanation for auditing.
+    - correlation_id: align with events for traceability.
+    - metadata: structured map for small typed values (avoid open-ended blobs).
+      We deliberately use extra="forbid" at the model level to prevent accidental
+      arbitrary attributes; metadata is the supported extensibility point.
+    """
+
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    command_type: str
+    issued_by: str | None = None
+    reason: str | None = None
+    correlation_id: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("metadata")
+    @classmethod
+    def _validate_metadata(cls, v: dict[str, Any]):
+        # Keep metadata shallow and keyed by str to encourage typed schemas.
+        if not isinstance(v, dict):
+            raise TypeError("metadata must be a dict[str, Any]")
+        for k in v.keys():
+            if not isinstance(k, str):
+                raise TypeError("metadata keys must be strings")
+        return v

fba_bench_core/domain/events/inventory.py

@@ -0,0 +1,119 @@
+"""Inventory and fulfillment-related events and commands."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field, model_validator
+
+from ..models import InventorySnapshot
+from .base import BaseEvent, Command
+
+
+class StockReplenished(BaseEvent):
+    """Event emitted when stock is replenished at a warehouse.
+
+    Either provide `snapshot_before` and `snapshot_after` (InventorySnapshot) or
+    provide `quantity_added` and `warehouse_location`. `quantity_added` must be > 0.
+    """
+
+    event_type: Literal["stock_replenished"] = "stock_replenished"
+
+    product_id: str
+    snapshot_before: InventorySnapshot | None = None
+    snapshot_after: InventorySnapshot | None = None
+    warehouse_location: str | None = None
+    quantity_added: int | None = Field(None, gt=0)
+
+    @model_validator(mode="after")
+    def _validate_snapshots_or_quantity(self):
+        if not (self.snapshot_before or self.snapshot_after or self.quantity_added):
+            raise ValueError(
+                "Provide snapshot_before/after or quantity_added to describe the replenishment"
+            )
+        return self
+
+
+class StockDepleted(BaseEvent):
+    """Event triggered when inventory reaches zero or falls below safety stock.
+
+    - safety_stock: optional configured safety stock level (int)
+    - current_snapshot: optional InventorySnapshot for reconciliation
+    """
+
+    event_type: Literal["stock_depleted"] = "stock_depleted"
+
+    product_id: str
+    safety_stock: int | None = None
+    current_snapshot: InventorySnapshot | None = None
+
+
+class FulfillmentDelayed(BaseEvent):
+    """Event emitted when an order fulfillment is delayed beyond SLA."""
+
+    event_type: Literal["fulfillment_delayed"] = "fulfillment_delayed"
+
+    order_id: str
+    delay_hours: float = Field(..., ge=0.0)
+    reason: str | None = None
+
+
+class SupplyDisruption(BaseEvent):
+    """Event emitted when a supply chain disruption occurs (e.g., supplier delay, shortage).
+
+    - disruption_type: type of disruption (e.g., 'supplier_delay', 'material_shortage', 'logistics_issue')
+    - impact_description: optional details on the impact.
+    """
+
+    event_type: Literal["supply_disruption"] = "supply_disruption"
+
+    product_id: str
+    supplier_id: str
+    disruption_type: str
+    impact_description: str | None = None
+
+
+class PlaceReplenishmentOrderCommand(Command):
+    """Command to place a replenishment order with a supplier."""
+
+    command_type: Literal["place_replenishment_order"] = "place_replenishment_order"
+
+    product_id: str
+    quantity: int = Field(..., gt=0)
+    supplier_id: str
+    target_warehouse: str | None = None
+    priority: Literal["low", "normal", "high", "urgent"] | None = "normal"
+
+
+class TransferInventoryCommand(Command):
+    """Command to transfer inventory between warehouses."""
+
+    command_type: Literal["transfer_inventory"] = "transfer_inventory"
+
+    product_id: str
+    from_warehouse: str
+    to_warehouse: str
+    quantity: int = Field(..., gt=0)
+
+
+class UpdateSafetyStockCommand(Command):
+    """Command to update safety stock thresholds for a product."""
+
+    command_type: Literal["update_safety_stock"] = "update_safety_stock"
+
+    product_id: str
+    new_safety_stock: int = Field(..., ge=0)
+
+
+class AdjustInventoryCommand(Command):
+    """Command to adjust inventory levels for a product (e.g., manual correction, write-off).
+
+    - adjustment_quantity: positive for increase, negative for decrease.
+    - warehouse_location: optional specific warehouse.
+    """
+
+    command_type: Literal["adjust_inventory"] = "adjust_inventory"
+
+    product_id: str
+    adjustment_quantity: int
+    warehouse_location: str | None = None

fba_bench_core/domain/events/marketing.py

@@ -0,0 +1,102 @@
+"""Marketing and customer engagement-related events and commands."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal
+from typing import Any, Literal
+
+from pydantic import Field, field_validator
+
+from .base import BaseEvent, Command
+
+
+class PromotionLaunched(BaseEvent):
+    """Event signalling that a promotion has been launched for products or categories.
+
+    - discount_percent is expressed as Decimal fraction (0.0 - 1.0).
+    """
+
+    event_type: Literal["promotion_launched"] = "promotion_launched"
+
+    promotion_id: str
+    product_ids: list[str] | None = None
+    category: str | None = None
+    discount_percent: Decimal = Field(..., ge=Decimal("0"), le=Decimal("1"))
+    start: datetime
+    end: datetime | None = None
+    channels: list[str] | None = None
+
+    @field_validator("discount_percent", mode="before")
+    @classmethod
+    def _coerce_discount(cls, v):
+        if isinstance(v, Decimal):
+            return v
+        try:
+            return Decimal(str(v))
+        except Exception as exc:
+            raise ValueError("Invalid discount_percent") from exc
+
+
+class CustomerComplaintLogged(BaseEvent):
+    """Event representing a logged customer complaint tied to an order."""
+
+    event_type: Literal["customer_complaint_logged"] = "customer_complaint_logged"
+
+    complaint_id: str
+    order_id: str | None = None
+    product_id: str | None = None
+    issue_type: str
+    details: str | None = None
+    resolution_deadline: datetime | None = None
+
+
+class ResolveCustomerIssueCommand(Command):
+    """Command for customer service agents to resolve a logged complaint.
+
+    - refund_amount uses Decimal for monetary values and must be >= 0.
+    """
+
+    command_type: Literal["resolve_customer_issue"] = "resolve_customer_issue"
+
+    complaint_id: str | None = None
+    order_id: str | None = None
+    resolution_action: str
+    refund_amount: Decimal | None = Field(None, ge=Decimal("0"))
+
+    @field_validator("refund_amount", mode="before")
+    @classmethod
+    def _coerce_refund(cls, v):
+        if v is None:
+            return v
+        if isinstance(v, Decimal):
+            return v
+        try:
+            return Decimal(str(v))
+        except Exception as exc:
+            raise ValueError("Invalid refund_amount") from exc
+
+
+class StartCustomerOutreachCommand(Command):
+    """Command to start an outreach/campaign targeted at a customer segment."""
+
+    command_type: Literal["start_customer_outreach"] = "start_customer_outreach"
+
+    segment: str
+    message_template: str
+    goal_metrics: dict[str, Any] | None = None
+    channels: list[str] | None = None
+
+
+class RespondToComplaintCommand(Command):
+    """Command to respond to a customer complaint.
+
+    - response_action: type of response (e.g., 'apology', 'refund', 'replacement')
+    - response_message: optional detailed message to the customer.
+    """
+
+    command_type: Literal["respond_to_complaint"] = "respond_to_complaint"
+
+    complaint_id: str
+    response_action: str
+    response_message: str | None = None