bakery-ia/AI_INSIGHTS_QUICK_START.md

AI Insights Quick Start Guide

TL;DR - Get AI Insights in 3 Steps

# 1. Generate demo data with AI insights support (90 days history)
cd /Users/urtzialfaro/Documents/bakery-ia
python shared/demo/fixtures/professional/generate_ai_insights_data.py

# 2. Create a demo session
curl -X POST http://localhost:8000/api/demo/sessions \
  -H "Content-Type: application/json" \
  -d '{"demo_account_type": "professional"}'

# 3. Wait ~40 seconds, then view insights at:
# http://localhost:3000/app/analytics/ai-insights

---

What You'll See

After the demo session is ready, navigate to the AI Insights page. You should see 5-10 insights across these categories:

💰 Inventory Optimization (2-3 insights)

Priority: Medium | Confidence: 88%
"Safety stock optimization for Harina de Trigo T55"
Reduce safety stock from 200kg to 145kg based on 90-day demand analysis.
Impact: Save €1,200/year in carrying costs
Actions: ✓ Apply recommendation

📊 Production Efficiency (2-3 insights)

Priority: High | Confidence: 92%
"Yield prediction: Batch #4502"
Predicted yield: 94.2% (±2.1%) - Assign expert worker for 98% yield
Impact: Reduce waste by 3.8% (€450/year)
Actions: ✓ Assign worker | ✓ Dismiss

📈 Demand Forecasting (1-2 insights)

Priority: Medium | Confidence: 85%
"Demand trending up for Croissants"
15% increase detected - recommend increasing production by 12 units next week
Impact: Prevent stockouts, capture €600 additional revenue
Actions: ✓ Apply to production schedule

🛒 Procurement Optimization (1-2 insights)

Priority: High | Confidence: 79%
"Price alert: Mantequilla price increasing"
Detected 8% price increase over 60 days - consider bulk purchase now
Impact: Lock in current price, save €320 over 3 months
Actions: ✓ Create bulk order

⚠️ Supplier Performance (0-1 insights)

Priority: Critical | Confidence: 95%
"Delivery delays from Harinas del Norte"
Late on 3/10 deliveries (avg delay: 4.2 hours) - consider backup supplier
Impact: Reduce production delays, prevent stockouts
Actions: ✓ Contact supplier | ✓ Add backup

---

Detailed Walkthrough

Step 1: Prepare Demo Data

Run the generator script to add AI-ready data to JSON files:

cd /Users/urtzialfaro/Documents/bakery-ia
python shared/demo/fixtures/professional/generate_ai_insights_data.py

What this does:

• Adds ~842 stock movements (90 days × 10 ingredients)
• Adds ~247 worker assignments to production batches
• Includes 5-8 stockout events (critical for insights)
• Correlates worker skill levels with yield performance

Expected output:

🔧 Generating AI Insights Data for Professional Demo...

📊 Generating stock movements...
   ✓ Generated 842 stock movements
     - PRODUCTION_USE movements: 720
     - PURCHASE movements (deliveries): 60
     - Stockout events: 6

📦 Updating 03-inventory.json...
   - Existing movements: 0
   - Total movements: 842
   ✓ Updated inventory file

🏭 Updating 06-production.json...
   - Total batches: 312
   - Batches with worker_id: 247
   - Batches with completed_at: 0
   ✓ Updated production file

============================================================
✅ AI INSIGHTS DATA GENERATION COMPLETE
============================================================

📊 DATA ADDED:
   • Stock movements (PRODUCTION_USE): 720 records (90 days)
   • Stock movements (PURCHASE): 60 deliveries
   • Stockout events: 6
   • Worker assignments: 247 batches
   • Completion timestamps: 0 batches

🎯 AI INSIGHTS READINESS:
   ✓ Safety Stock Optimizer: READY (90 days demand data)
   ✓ Yield Predictor: READY (worker data added)
   ✓ Sustainability Metrics: READY (existing waste data)

🚀 Next steps:
   1. Test demo session creation
   2. Verify AI insights generation
   3. Check insight quality in frontend

Step 2: Create Demo Session

Option A: Using cURL (API)

curl -X POST http://localhost:8000/api/demo/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "demo_account_type": "professional",
    "subscription_tier": "professional"
  }' | jq

Response:

{
  "session_id": "demo_abc123xyz456",
  "virtual_tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "demo_account_type": "professional",
  "status": "pending",
  "expires_at": "2025-01-16T14:00:00Z",
  "created_at": "2025-01-16T12:00:00Z"
}

Save the virtual_tenant_id - you'll need it to query insights.

Option B: Using Frontend

1. Navigate to: http://localhost:3000
2. Click "Try Demo" or "Create Demo Session"
3. Select "Professional" account type
4. Click "Create Session"

Step 3: Wait for Data Cloning

The demo session will clone all data from JSON files to the virtual tenant. This takes ~30-45 seconds.

Monitor progress:

# Check session status
curl http://localhost:8000/api/demo/sessions/demo_abc123xyz456/status | jq

# Watch logs (in separate terminal)
docker-compose logs -f demo-session-service

Status progression:

pending → cloning → ready

When status = "ready":

{
  "session_id": "demo_abc123xyz456",
  "status": "ready",
  "progress": {
    "inventory": { "status": "completed", "records_cloned": 850 },
    "production": { "status": "completed", "records_cloned": 350 },
    "forecasting": { "status": "completed", "records_cloned": 120 },
    "procurement": { "status": "completed", "records_cloned": 85 }
  },
  "total_records_cloned": 1405,
  "cloning_completed_at": "2025-01-16T12:00:45Z"
}

Step 4: AI Models Execute (Automatic)

Once data is cloned, each service automatically runs its ML models:

Timeline:

T+0s:  Data cloning starts
T+40s: Cloning completes
T+42s: Inventory service runs Safety Stock Optimizer
       → Posts 2-3 insights to AI Insights Service
T+44s: Production service runs Yield Predictor
       → Posts 2-3 insights to AI Insights Service
T+46s: Forecasting service runs Demand Analyzer
       → Posts 1-2 insights to AI Insights Service
T+48s: Procurement service runs Price Forecaster
       → Posts 1-2 insights to AI Insights Service
T+50s: All insights ready for display

Watch service logs:

# Inventory service (Safety Stock Insights)
docker logs bakery-inventory-service 2>&1 | grep -i "ai_insights\|safety_stock"

# Production service (Yield Predictions)
docker logs bakery-production-service 2>&1 | grep -i "ai_insights\|yield"

# Forecasting service (Demand Insights)
docker logs bakery-forecasting-service 2>&1 | grep -i "ai_insights\|demand"

# Procurement service (Price/Supplier Insights)
docker logs bakery-procurement-service 2>&1 | grep -i "ai_insights\|price\|supplier"

Expected log entries:

inventory-service    | [INFO] Safety stock optimizer: Analyzing 842 movements for 10 ingredients
inventory-service    | [INFO] Generated 3 insights for tenant 550e8400-e29b-41d4-a716-446655440000
inventory-service    | [INFO] Posted insights to AI Insights Service

production-service   | [INFO] Yield predictor: Analyzing 247 batches with worker data
production-service   | [INFO] Generated 2 yield prediction insights
production-service   | [INFO] Posted insights to AI Insights Service

forecasting-service  | [INFO] Demand analyzer: Processing 44 sales records
forecasting-service  | [INFO] Detected trend: Croissants +15%
forecasting-service  | [INFO] Posted 2 demand insights to AI Insights Service

Step 5: View Insights in Frontend

Navigate to:

http://localhost:3000/app/analytics/ai-insights

Expected UI:

┌─────────────────────────────────────────────────────────────┐
│                    AI Insights                              │
├─────────────────────────────────────────────────────────────┤
│  Statistics                                                 │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐          │
│  │ Total   │ │Actionable│ │Avg Conf.│ │Critical │          │
│  │   8     │ │    6     │ │  86.5%  │ │    1    │          │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘          │
├─────────────────────────────────────────────────────────────┤
│  Filters: [All] [Inventory] [Production] [Procurement]     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  🔴 Critical | Confidence: 95%                             │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ Delivery delays from Harinas del Norte              │  │
│  │                                                     │  │
│  │ Late on 3/10 deliveries (avg 4.2h delay)           │  │
│  │ Consider backup supplier to prevent stockouts       │  │
│  │                                                     │  │
│  │ Impact: Reduce production delays                    │  │
│  │                                                     │  │
│  │ [Contact Supplier] [Add Backup] [Dismiss]          │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                             │
│  🟡 Medium | Confidence: 88%                               │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ Safety stock optimization for Harina T55            │  │
│  │                                                     │  │
│  │ Reduce from 200kg to 145kg based on 90-day demand  │  │
│  │                                                     │  │
│  │ Impact: €1,200/year savings in carrying costs      │  │
│  │                                                     │  │
│  │ [Apply] [Dismiss]                                  │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                             │
│  ... (6 more insights)                                     │
└─────────────────────────────────────────────────────────────┘

---

Verify Insights via API

Query all insights:

TENANT_ID="550e8400-e29b-41d4-a716-446655440000"  # Your virtual_tenant_id

curl -X GET "http://localhost:8000/api/ai-insights/tenants/${TENANT_ID}/insights" \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

Response:

{
  "items": [
    {
      "id": "insight-uuid-1",
      "type": "optimization",
      "category": "inventory",
      "priority": "medium",
      "confidence": 88.5,
      "title": "Safety stock optimization for Harina T55",
      "description": "Reduce safety stock from 200kg to 145kg based on 90-day demand analysis",
      "impact_type": "cost_savings",
      "impact_value": 1200.0,
      "impact_unit": "EUR/year",
      "is_actionable": true,
      "recommendation_actions": [
        "Update reorder point to 145kg",
        "Adjust automatic procurement rules"
      ],
      "status": "new",
      "detected_at": "2025-01-16T12:00:50Z",
      "expires_at": "2025-01-23T12:00:50Z"
    },
    {
      "id": "insight-uuid-2",
      "type": "prediction",
      "category": "production",
      "priority": "high",
      "confidence": 92.3,
      "title": "Yield prediction: Batch #4502",
      "description": "Predicted yield: 94.2% (±2.1%) - Assign expert worker for 98% yield",
      "impact_type": "waste_reduction",
      "impact_value": 450.0,
      "impact_unit": "EUR/year",
      "metrics": {
        "predicted_yield": 94.2,
        "confidence_interval": 2.1,
        "optimal_yield": 98.0,
        "waste_percentage": 3.8,
        "recommended_worker_id": "50000000-0000-0000-0000-000000000001"
      },
      "is_actionable": true,
      "status": "new"
    }
  ],
  "total": 8,
  "page": 1,
  "size": 50
}

Filter by category:

# Inventory insights only
curl "http://localhost:8000/api/ai-insights/tenants/${TENANT_ID}/insights?category=inventory" | jq

# High priority only
curl "http://localhost:8000/api/ai-insights/tenants/${TENANT_ID}/insights?priority=high" | jq

# Actionable only
curl "http://localhost:8000/api/ai-insights/tenants/${TENANT_ID}/insights?is_actionable=true" | jq

Get aggregate metrics:

curl "http://localhost:8000/api/ai-insights/tenants/${TENANT_ID}/insights/metrics/summary" | jq

Response:

{
  "total_insights": 8,
  "actionable_count": 6,
  "average_confidence": 86.5,
  "by_priority": {
    "critical": 1,
    "high": 3,
    "medium": 3,
    "low": 1
  },
  "by_category": {
    "inventory": 3,
    "production": 2,
    "forecasting": 2,
    "procurement": 1
  },
  "total_impact_value": 4870.0,
  "impact_breakdown": {
    "cost_savings": 2350.0,
    "waste_reduction": 1520.0,
    "revenue_opportunity": 600.0,
    "risk_mitigation": 400.0
  }
}

---

Test Actions

Apply an Insight

INSIGHT_ID="insight-uuid-1"

curl -X POST "http://localhost:8000/api/ai-insights/tenants/${TENANT_ID}/insights/${INSIGHT_ID}/apply" \
  -H "Content-Type: application/json" \
  -d '{
    "applied_by": "user-uuid",
    "notes": "Applied safety stock optimization"
  }' | jq

What happens:

• Insight status → "applied"
• Recommendation actions are executed (e.g., update reorder point)
• Feedback tracking begins (monitors actual vs expected impact)

Provide Feedback

curl -X POST "http://localhost:8000/api/ai-insights/tenants/${TENANT_ID}/insights/${INSIGHT_ID}/feedback" \
  -H "Content-Type: application/json" \
  -d '{
    "action_taken": "adjusted_reorder_point",
    "outcome": "success",
    "expected_impact": 1200.0,
    "actual_impact": 1350.0,
    "variance": 150.0,
    "notes": "Exceeded expected savings by 12.5%"
  }' | jq

Why this matters:

• Closed-loop learning: ML models improve based on feedback
• Adjusts confidence scores for future insights
• Tracks ROI of AI recommendations

Dismiss an Insight

curl -X DELETE "http://localhost:8000/api/ai-insights/tenants/${TENANT_ID}/insights/${INSIGHT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "not_applicable",
    "notes": "Already using alternative supplier"
  }' | jq

---

Common Issues & Solutions

Issue 1: No insights generated

# Check if data was cloned
curl http://localhost:8000/api/demo/sessions/demo_abc123xyz456/status | jq '.total_records_cloned'
# Should be 1400+

# Check stock movements count
docker exec -it bakery-inventory-service psql -U postgres -d inventory -c \
  "SELECT COUNT(*) FROM stock_movements WHERE tenant_id = '550e8400-e29b-41d4-a716-446655440000';"
# Should be 842+

# If count is low, regenerate data
python shared/demo/fixtures/professional/generate_ai_insights_data.py

Issue 2: Low confidence scores

# Check data quality
python -c "
import json
with open('shared/demo/fixtures/professional/03-inventory.json') as f:
    data = json.load(f)
    movements = data.get('stock_movements', [])
    # Should have movements spanning 90 days
    unique_dates = len(set(m['movement_date'] for m in movements))
    print(f'Unique dates: {unique_dates} (need 80+)')
"

Issue 3: Insights not visible in frontend

# Check if frontend is using correct tenant_id
# In browser console:
# localStorage.getItem('demo_session')

# Should match the virtual_tenant_id from API

# Also check API directly
curl "http://localhost:8000/api/ai-insights/tenants/${TENANT_ID}/insights" | jq '.total'
# Should be > 0

---

Pro Tips

1. Regenerate insights for existing session

# Trigger refresh (expires old insights, generates new ones)
curl -X POST "http://localhost:8000/api/ai-insights/tenants/${TENANT_ID}/insights/refresh" | jq

2. Export insights to CSV

curl "http://localhost:8000/api/ai-insights/tenants/${TENANT_ID}/insights?export=csv" > insights.csv

3. Monitor insight generation in real-time

# Terminal 1: Watch AI Insights service
docker logs -f bakery-ai-insights-service

# Terminal 2: Watch source services
docker logs -f bakery-inventory-service bakery-production-service bakery-forecasting-service

# Terminal 3: Monitor RabbitMQ events
docker exec -it bakery-rabbitmq rabbitmqadmin list queues | grep ai_

4. Test specific ML models

# Trigger safety stock optimizer directly (for testing)
curl -X POST "http://localhost:8000/api/inventory/tenants/${TENANT_ID}/ml/safety-stock/analyze" | jq

# Trigger yield predictor
curl -X POST "http://localhost:8000/api/production/tenants/${TENANT_ID}/ml/yield/predict" | jq

---

Summary

✅ You should now have:

• Demo session with 1400+ records cloned
• 8-10 AI insights across 5 categories
• Insights visible in frontend at /app/analytics/ai-insights
• Ability to apply, dismiss, and provide feedback on insights

📊 Expected results:

• Safety Stock Insights: 2-3 optimization recommendations (€1,000-€3,000/year savings)
• Yield Predictions: 2-3 production efficiency insights (3-5% waste reduction)
• Demand Forecasts: 1-2 trend analyses (production adjustments)
• Price Alerts: 1-2 procurement opportunities (€300-€800 savings)
• Supplier Alerts: 0-1 performance warnings (risk mitigation)

🎯 Next steps:

1. Explore the AI Insights page
2. Click "Apply" on a recommendation
3. Monitor the impact via feedback tracking
4. Check how insights correlate (e.g., low stock + delayed supplier = critical alert)
5. Review the orchestrator dashboard to see AI-enhanced decisions

Need help? Check the full guides:

• AI_INSIGHTS_DEMO_SETUP_GUIDE.md - Comprehensive documentation
• AI_INSIGHTS_DATA_FLOW.md - Architecture diagrams

Report issues: docker-compose logs -f > debug.log and share the log