From 0a2982d22f90a35a989130faca443e482a3beb5a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 7 Nov 2025 19:46:27 +0000
Subject: [PATCH] feat: Add complete set of PO reasoning helper functions

Added missing helper functions for all purchase order reasoning types:
- create_po_reasoning_supplier_contract: Contract-based orders
- create_po_reasoning_safety_stock: Safety stock replenishment
- create_po_reasoning_seasonal_demand: Seasonal preparation
- create_po_reasoning_production_requirement: Production needs
- create_po_reasoning_manual_request: Manual orders

These functions generate structured reasoning_data for i18n translation
and provide consistent reasoning structure across all PO types.

Fixes ImportError in demo-seed-purchase-orders pod.
---
 shared/schemas/reasoning_types.py | 139 ++++++++++++++++++++++++++++++
 1 file changed, 139 insertions(+)

diff --git a/shared/schemas/reasoning_types.py b/shared/schemas/reasoning_types.py
index 55233a6d..1e276b7f 100644
--- a/shared/schemas/reasoning_types.py
+++ b/shared/schemas/reasoning_types.py
@@ -206,6 +206,145 @@ def create_po_reasoning_forecast_demand(
     }
 
 
+def create_po_reasoning_supplier_contract(
+    supplier_name: str,
+    product_names: list,
+    contract_terms: str = "monthly",
+    contract_quantity: float = 0
+) -> Dict[str, Any]:
+    """Create reasoning data for supplier contract fulfillment"""
+    return {
+        "type": PurchaseOrderReasoningType.SUPPLIER_CONTRACT.value,
+        "parameters": {
+            "supplier_name": supplier_name,
+            "product_names": product_names,
+            "product_count": len(product_names),
+            "contract_terms": contract_terms,
+            "contract_quantity": contract_quantity
+        },
+        "consequence": {
+            "type": "contract_breach",
+            "severity": ConsequenceSeverity.HIGH.value,
+            "impact": "contract_penalties"
+        },
+        "metadata": {
+            "trigger_source": "contract_schedule",
+            "ai_assisted": False
+        }
+    }
+
+
+def create_po_reasoning_safety_stock(
+    supplier_name: str,
+    product_names: list,
+    current_safety_stock: float,
+    target_safety_stock: float,
+    reorder_point: float
+) -> Dict[str, Any]:
+    """Create reasoning data for safety stock replenishment"""
+    return {
+        "type": PurchaseOrderReasoningType.SAFETY_STOCK_REPLENISHMENT.value,
+        "parameters": {
+            "supplier_name": supplier_name,
+            "product_names": product_names,
+            "product_count": len(product_names),
+            "current_safety_stock": round(current_safety_stock, 1),
+            "target_safety_stock": round(target_safety_stock, 1),
+            "reorder_point": round(reorder_point, 1)
+        },
+        "consequence": {
+            "type": "stockout_risk",
+            "severity": ConsequenceSeverity.MEDIUM.value,
+            "impact": "reduced_buffer"
+        },
+        "metadata": {
+            "trigger_source": "orchestrator_auto",
+            "ai_assisted": True
+        }
+    }
+
+
+def create_po_reasoning_seasonal_demand(
+    supplier_name: str,
+    product_names: list,
+    season: str,
+    expected_demand_increase_pct: float
+) -> Dict[str, Any]:
+    """Create reasoning data for seasonal demand preparation"""
+    return {
+        "type": PurchaseOrderReasoningType.SEASONAL_DEMAND.value,
+        "parameters": {
+            "supplier_name": supplier_name,
+            "product_names": product_names,
+            "product_count": len(product_names),
+            "season": season,
+            "expected_demand_increase_pct": round(expected_demand_increase_pct, 1)
+        },
+        "consequence": {
+            "type": "missed_opportunity",
+            "severity": ConsequenceSeverity.MEDIUM.value,
+            "impact": "lost_seasonal_sales"
+        },
+        "metadata": {
+            "trigger_source": "orchestrator_auto",
+            "ai_assisted": True
+        }
+    }
+
+
+def create_po_reasoning_production_requirement(
+    supplier_name: str,
+    product_names: list,
+    production_batches: int,
+    required_by_date: str
+) -> Dict[str, Any]:
+    """Create reasoning data for production requirement"""
+    return {
+        "type": PurchaseOrderReasoningType.PRODUCTION_REQUIREMENT.value,
+        "parameters": {
+            "supplier_name": supplier_name,
+            "product_names": product_names,
+            "product_count": len(product_names),
+            "production_batches": production_batches,
+            "required_by_date": required_by_date
+        },
+        "consequence": {
+            "type": "production_delay",
+            "severity": ConsequenceSeverity.HIGH.value,
+            "impact": "blocked_production"
+        },
+        "metadata": {
+            "trigger_source": "production_schedule",
+            "ai_assisted": True
+        }
+    }
+
+
+def create_po_reasoning_manual_request(
+    supplier_name: str,
+    product_names: list,
+    requested_by: str,
+    reason: str = "manual_order"
+) -> Dict[str, Any]:
+    """Create reasoning data for manual purchase request"""
+    return {
+        "type": PurchaseOrderReasoningType.MANUAL_REQUEST.value,
+        "parameters": {
+            "supplier_name": supplier_name,
+            "product_names": product_names,
+            "product_count": len(product_names),
+            "requested_by": requested_by,
+            "reason": reason
+        },
+        "consequence": None,
+        "metadata": {
+            "trigger_source": "manual",
+            "ai_assisted": False
+        }
+    }
+
+
+
 def create_batch_reasoning_forecast_demand(
     product_name: str,
     predicted_demand: float,