bakery-ia/AI_INSIGHTS_QUICK_START.md

# AI Insights Quick Start Guide

## TL;DR - Get AI Insights in 3 Steps

```bash
# 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:

```bash
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)**
```bash
curl -X POST http://localhost:8000/api/demo/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "demo_account_type": "professional",
    "subscription_tier": "professional"
  }' | jq
```

**Response**:
```json
{
  "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**:
```bash
# 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"**:
```json
{
  "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**:
```bash
# 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**:
```bash
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**:
```json
{
  "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**:
```bash
# 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**:
```bash
curl "http://localhost:8000/api/ai-insights/tenants/${TENANT_ID}/insights/metrics/summary" | jq
```

**Response**:
```json
{
  "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
```bash
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
```bash
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
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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**
```bash
# 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**
```bash
curl "http://localhost:8000/api/ai-insights/tenants/${TENANT_ID}/insights?export=csv" > insights.csv
```

### 3. **Monitor insight generation in real-time**
```bash
# 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**
```bash
# 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](./AI_INSIGHTS_DEMO_SETUP_GUIDE.md) - Comprehensive documentation
- [AI_INSIGHTS_DATA_FLOW.md](./AI_INSIGHTS_DATA_FLOW.md) - Architecture diagrams

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