bakery-ia/AI_INSIGHTS_DATA_FLOW.md

AI Insights Data Flow Diagram

Quick Reference: JSON Files → AI Insights

┌─────────────────────────────────────────────────────────────────┐
│                    DEMO SESSION CREATION                        │
│                                                                 │
│  POST /api/demo/sessions {"demo_account_type": "professional"} │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│              CLONE ORCHESTRATOR (Auto-triggered)                │
│                                                                 │
│  Loads JSON files from:                                         │
│  shared/demo/fixtures/professional/*.json                       │
│                                                                 │
│  Clones data to virtual_tenant_id                              │
└────────────────┬────────────────────┬────────────────┬──────────┘
                 │                    │                │
                 ▼                    ▼                ▼
    ┌────────────────────┐  ┌─────────────────┐  ┌──────────────┐
    │  03-inventory.json │  │ 06-production   │  │ 09-sales.json│
    │                    │  │    .json        │  │              │
    │ • stock_movements  │  │                 │  │ • sales_data │
    │   (90 days)        │  │ • batches with  │  │   (30+ days) │
    │ • PRODUCTION_USE   │  │   staff_assigned│  │              │
    │ • PURCHASE         │  │ • yield_%       │  │              │
    │ • Stockouts (!)    │  │ • duration      │  │              │
    └─────────┬──────────┘  └────────┬────────┘  └──────┬───────┘
              │                      │                   │
              │                      │                   │
              ▼                      ▼                   ▼
    ┌────────────────────┐  ┌─────────────────┐  ┌──────────────┐
    │ Inventory Service  │  │ Production      │  │ Forecasting  │
    │                    │  │ Service         │  │ Service      │
    │ ML Model:          │  │                 │  │              │
    │ Safety Stock       │  │ ML Model:       │  │ ML Model:    │
    │ Optimizer          │  │ Yield Predictor │  │ Demand       │
    │                    │  │                 │  │ Analyzer     │
    └─────────┬──────────┘  └────────┬────────┘  └──────┬───────┘
              │                      │                   │
              │ Analyzes 90 days     │ Correlates        │ Detects
              │ consumption          │ worker skills     │ trends &
              │ patterns             │ with yields       │ seasonality
              │                      │                   │
              ▼                      ▼                   ▼
    ┌────────────────────────────────────────────────────────────┐
    │  Each Service Posts Insights via AIInsightsClient          │
    │                                                            │
    │  POST /api/ai-insights/tenants/{virtual_tenant_id}/insights│
    └────────────────────────────┬───────────────────────────────┘
                                 │
                                 ▼
             ┌───────────────────────────────────────┐
             │      AI Insights Service              │
             │                                       │
             │  Database Tables:                     │
             │  • ai_insights                       │
             │  • insight_feedback                  │
             │  • insight_correlations              │
             │                                       │
             │  Stores:                              │
             │  • Title, description                 │
             │  • Priority, confidence               │
             │  • Impact metrics (€/year)            │
             │  • Recommendation actions             │
             │  • Expires in 7 days                  │
             └───────────────┬───────────────────────┘
                             │
                             ▼
             ┌───────────────────────────────────────┐
             │  RabbitMQ Events Published            │
             │                                       │
             │  • ai_safety_stock_optimization       │
             │  • ai_yield_prediction                │
             │  • ai_demand_forecast                 │
             │  • ai_price_forecast                  │
             │  • ai_supplier_performance            │
             └───────────────┬───────────────────────┘
                             │
                             ▼
             ┌───────────────────────────────────────┐
             │  Frontend Consumes                    │
             │                                       │
             │  GET /api/ai-insights/tenants/{id}/   │
             │      insights?filters...              │
             │                                       │
             │  Displays:                            │
             │  • AIInsightsPage.tsx                 │
             │  • AIInsightsWidget.tsx (dashboard)   │
             │  • Service-specific widgets           │
             └───────────────────────────────────────┘

Data Requirements by AI Model

1. Safety Stock Optimizer

Requires: 90 days of stock movements

// 03-inventory.json
{
  "stock_movements": [
    // Daily consumption (PRODUCTION_USE)
    { "movement_type": "PRODUCTION_USE", "quantity": 45.0, "movement_date": "BASE_TS - 1d" },
    { "movement_type": "PRODUCTION_USE", "quantity": 52.3, "movement_date": "BASE_TS - 2d" },
    // ... repeat 90 days per ingredient

    // Stockout events (critical!)
    { "movement_type": "PRODUCTION_USE", "quantity_after": 0.0, "movement_date": "BASE_TS - 15d" }
  ]
}

Generates:

• Optimal reorder points
• Cost savings from reduced safety stock
• Stockout risk alerts

---

2. Yield Predictor

Requires: Historical batches with worker data

// 06-production.json
{
  "batches": [
    {
      "yield_percentage": 96.5,
      "staff_assigned": ["50000000-0000-0000-0000-000000000001"],  // Expert worker
      "actual_duration_minutes": 175.5
    },
    {
      "yield_percentage": 88.2,
      "staff_assigned": ["50000000-0000-0000-0000-000000000005"],  // Junior worker
      "actual_duration_minutes": 195.0
    }
  ]
}

Generates:

• Yield predictions for upcoming batches
• Worker-product performance correlations
• Waste reduction opportunities

---

3. Demand Analyzer

Requires: Sales history (30+ days)

// 09-sales.json
{
  "sales_data": [
    { "product_id": "...", "quantity": 51.11, "sales_date": "BASE_TS - 1d" },
    { "product_id": "...", "quantity": 48.29, "sales_date": "BASE_TS - 2d" }
    // ... repeat 30+ days
  ]
}

Generates:

• Trend analysis (up/down)
• Seasonal patterns
• Production recommendations

---

4. Price Forecaster

Requires: Purchase order history

// 07-procurement.json
{
  "purchase_orders": [
    {
      "supplier_id": "...",
      "items": [{ "unit_price": 0.85, "ordered_quantity": 500 }],
      "order_date": "BASE_TS - 7d"
    },
    {
      "supplier_id": "...",
      "items": [{ "unit_price": 0.92, "ordered_quantity": 500 }],  // Price increased!
      "order_date": "BASE_TS - 1d"
    }
  ]
}

Generates:

• Price trend analysis
• Bulk buying opportunities
• Supplier cost comparisons

---

5. Supplier Performance Analyzer

Requires: Purchase orders with delivery tracking

// 07-procurement.json
{
  "purchase_orders": [
    {
      "supplier_id": "40000000-0000-0000-0000-000000000001",
      "required_delivery_date": "BASE_TS - 4h",
      "estimated_delivery_date": "BASE_TS - 4h",
      "status": "confirmed",  // Still not delivered = LATE
      "reasoning_data": {
        "metadata": {
          "delivery_delayed": true,
          "delay_hours": 4
        }
      }
    }
  ]
}

Generates:

• Supplier reliability scores
• Delivery performance alerts
• Risk management recommendations

---

Insight Types Generated

Service	Category	Priority	Example Title
Inventory	inventory	medium	"Safety stock optimization for Harina T55: Reduce from 200kg to 145kg, save €1,200/year"
Inventory	inventory	critical	"Stockout risk: Levadura Fresca below critical level (3 events in 90 days)"
Production	production	medium	"Yield prediction: Batch #4502 expected 94.2% yield - assign expert worker for 98%"
Production	production	high	"Waste reduction: Training junior staff on croissants could save €2,400/year"
Forecasting	forecasting	medium	"Demand trending up 15% for Croissants - increase production by 12 units next week"
Forecasting	forecasting	low	"Weekend sales 40% lower - optimize Saturday production to reduce waste"
Procurement	procurement	high	"Price alert: Mantequilla up 8% in 60 days - consider bulk purchase now"
Procurement	procurement	medium	"Supplier performance: Harinas del Norte late on 3/10 deliveries - consider backup"

---

Testing Checklist

Run this before creating a demo session:

cd /Users/urtzialfaro/Documents/bakery-ia

# 1. Generate AI insights data
python shared/demo/fixtures/professional/generate_ai_insights_data.py

# 2. Verify data counts
python -c "
import json

# Check inventory
with open('shared/demo/fixtures/professional/03-inventory.json') as f:
    inv = json.load(f)
    movements = len(inv.get('stock_movements', []))
    stockouts = sum(1 for m in inv['stock_movements'] if m.get('quantity_after') == 0.0)
    print(f'✓ Stock movements: {movements} (need 800+)')
    print(f'✓ Stockout events: {stockouts} (need 5+)')

# Check production
with open('shared/demo/fixtures/professional/06-production.json') as f:
    prod = json.load(f)
    batches_with_workers = sum(1 for b in prod['batches'] if b.get('staff_assigned'))
    batches_with_yield = sum(1 for b in prod['batches'] if b.get('yield_percentage'))
    print(f'✓ Batches with workers: {batches_with_workers} (need 200+)')
    print(f'✓ Batches with yield: {batches_with_yield} (need 200+)')

# Check sales
with open('shared/demo/fixtures/professional/09-sales.json') as f:
    sales = json.load(f)
    sales_count = len(sales.get('sales_data', []))
    print(f'✓ Sales records: {sales_count} (need 30+)')

# Check procurement
with open('shared/demo/fixtures/professional/07-procurement.json') as f:
    proc = json.load(f)
    po_count = len(proc.get('purchase_orders', []))
    delayed = sum(1 for po in proc['purchase_orders'] if po.get('reasoning_data', {}).get('metadata', {}).get('delivery_delayed'))
    print(f'✓ Purchase orders: {po_count} (need 5+)')
    print(f'✓ Delayed deliveries: {delayed} (need 1+)')
"

# 3. Validate JSON syntax
for file in shared/demo/fixtures/professional/*.json; do
  echo "Checking $file..."
  python -m json.tool "$file" > /dev/null && echo "  ✓ Valid" || echo "  ✗ INVALID JSON"
done

Expected Output:

✓ Stock movements: 842 (need 800+)
✓ Stockout events: 6 (need 5+)
✓ Batches with workers: 247 (need 200+)
✓ Batches with yield: 312 (need 200+)
✓ Sales records: 44 (need 30+)
✓ Purchase orders: 8 (need 5+)
✓ Delayed deliveries: 2 (need 1+)

Checking shared/demo/fixtures/professional/01-tenant.json...
  ✓ Valid
Checking shared/demo/fixtures/professional/02-auth.json...
  ✓ Valid
...

---

Troubleshooting Quick Guide

Problem	Cause	Solution
No insights generated	Missing stock movements	Run generate_ai_insights_data.py
Low confidence scores	< 60 days of data	Ensure 90 days of movements
No yield predictions	Missing staff_assigned	Run generator script
No supplier insights	No delayed deliveries	Check 07-procurement.json for delayed POs
Insights not in frontend	Tenant ID mismatch	Verify virtual_tenant_id matches
DB errors during cloning	JSON syntax error	Validate all JSON files

---

Files Modified by Generator

When you run generate_ai_insights_data.py, these files are updated:

1. 03-inventory.json:

   • Adds ~842 stock movements
   • Includes 5-8 stockout events
   • Spans 90 days of history

2. 06-production.json:

   • Adds staff_assigned to ~247 batches
   • Adds actual_duration_minutes
   • Correlates workers with yields

Backup your files first (optional):

cp shared/demo/fixtures/professional/03-inventory.json shared/demo/fixtures/professional/03-inventory.json.backup
cp shared/demo/fixtures/professional/06-production.json shared/demo/fixtures/professional/06-production.json.backup

To restore:

cp shared/demo/fixtures/professional/03-inventory.json.backup shared/demo/fixtures/professional/03-inventory.json
cp shared/demo/fixtures/professional/06-production.json.backup shared/demo/fixtures/professional/06-production.json