bakery-admin/bakery-ia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive documentation and final improvements

Browse Source 
Documentation Added:
- AI_INSIGHTS_DEMO_SETUP_GUIDE.md: Complete setup guide for demo sessions
- AI_INSIGHTS_DATA_FLOW.md: Architecture and data flow diagrams
- AI_INSIGHTS_QUICK_START.md: Quick reference guide
- DEMO_SESSION_ANALYSIS_REPORT.md: Detailed analysis of demo session d67eaae4
- ROOT_CAUSE_ANALYSIS_AND_FIXES.md: Complete analysis of 8 issues (6 fixed, 2 analyzed)
- COMPLETE_FIX_SUMMARY.md: Executive summary of all fixes
- FIX_MISSING_INSIGHTS.md: Forecasting and procurement fix guide
- FINAL_STATUS_SUMMARY.md: Status overview
- verify_fixes.sh: Automated verification script
- enhance_procurement_data.py: Procurement data enhancement script

Service Improvements:
- Demo session cleanup worker: Use proper settings for Redis configuration with TLS/auth
- Procurement service: Add Redis initialization with proper error handling and cleanup
- Production fixture: Remove duplicate worker assignments (cleaned 56 duplicates)
- Orchestrator fixture: Add purchase order metadata for better tracking

Impact:
- Complete documentation for troubleshooting and setup
- Improved Redis connection handling across services
- Clean production data without duplicates
- Better error handling and logging

🤖 Generated with Claude Code (https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Urtzi Alfaro
2025-12-16 11:32:45 +01:00
parent 4418ff0876
commit 9f3b39bd28
14 changed files with 3982 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

565
AI_INSIGHTS_QUICK_START.md Normal file
View File

@@ -0,0 +1,565 @@
# 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