bakery-ia/services/ai_insights/README.md

AI Insights Service

Intelligent insights and recommendations service for bakery operations optimization.

Overview

The AI Insights Service is a microservice that aggregates, scores, and manages intelligent recommendations across the bakery-ia platform. It provides:

• Unified Insight Management: Centralized storage and retrieval of AI-generated insights
• Confidence Scoring: Standardized confidence calculation across different insight types
• Impact Estimation: Business value quantification for recommendations
• Feedback Loop: Closed-loop learning from applied insights
• Cross-Service Intelligence: Correlation detection between insights from different services

Features

Core Capabilities

1. Insight Aggregation

   • Collect insights from Forecasting, Procurement, Production, and Sales services
   • Categorize and prioritize recommendations
   • Filter by confidence, category, priority, and actionability

2. Confidence Calculation

   • Multi-factor scoring: data quality, model performance, sample size, recency, historical accuracy
   • Insight-type specific adjustments
   • Specialized calculations for forecasting and optimization insights

3. Impact Estimation

   • Cost savings quantification
   • Revenue increase projections
   • Waste reduction calculations
   • Efficiency gain measurements
   • Quality improvement tracking

4. Feedback & Learning

   • Track application outcomes
   • Compare expected vs. actual impact
   • Calculate success rates
   • Enable model improvement

5. Orchestration Integration

   • Pre-orchestration insight gathering
   • Actionable insight filtering
   • Categorized recommendations for workflow phases

Architecture

Database Models

• AIInsight: Core insights table with classification, confidence, impact metrics
• InsightFeedback: Feedback tracking for closed-loop learning
• InsightCorrelation: Cross-service insight relationships

API Endpoints

POST   /api/v1/ai-insights/tenants/{tenant_id}/insights
GET    /api/v1/ai-insights/tenants/{tenant_id}/insights
GET    /api/v1/ai-insights/tenants/{tenant_id}/insights/{insight_id}
PATCH  /api/v1/ai-insights/tenants/{tenant_id}/insights/{insight_id}
DELETE /api/v1/ai-insights/tenants/{tenant_id}/insights/{insight_id}

GET    /api/v1/ai-insights/tenants/{tenant_id}/insights/orchestration-ready
GET    /api/v1/ai-insights/tenants/{tenant_id}/insights/metrics/summary
POST   /api/v1/ai-insights/tenants/{tenant_id}/insights/{insight_id}/apply
POST   /api/v1/ai-insights/tenants/{tenant_id}/insights/{insight_id}/feedback
POST   /api/v1/ai-insights/tenants/{tenant_id}/insights/refresh
GET    /api/v1/ai-insights/tenants/{tenant_id}/insights/export

Installation

Prerequisites

• Python 3.11+
• PostgreSQL 14+
• Redis 6+

Setup

1. Clone and navigate:

   cd services/ai_insights
   

2. Create virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configure environment:

   cp .env.example .env
   # Edit .env with your configuration
   

5. Run migrations:

   alembic upgrade head
   

6. Start the service:

   uvicorn app.main:app --reload
   

The service will be available at http://localhost:8000.

Configuration

Environment Variables

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	Required
REDIS_URL	Redis connection string	Required
FORECASTING_SERVICE_URL	Forecasting service URL	http://forecasting-service:8000
PROCUREMENT_SERVICE_URL	Procurement service URL	http://procurement-service:8000
PRODUCTION_SERVICE_URL	Production service URL	http://production-service:8000
MIN_CONFIDENCE_THRESHOLD	Minimum confidence for insights	60
DEFAULT_INSIGHT_TTL_DAYS	Days before insights expire	7

Usage Examples

Creating an Insight

import httpx

insight_data = {
    "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "recommendation",
    "priority": "high",
    "category": "procurement",
    "title": "Flour Price Increase Expected",
    "description": "Price predicted to rise 8% in next week. Consider ordering now.",
    "impact_type": "cost_savings",
    "impact_value": 120.50,
    "impact_unit": "euros",
    "confidence": 85,
    "metrics_json": {
        "current_price": 1.20,
        "predicted_price": 1.30,
        "order_quantity": 1000
    },
    "actionable": True,
    "recommendation_actions": [
        {"label": "Order Now", "action": "create_purchase_order"},
        {"label": "Review", "action": "review_forecast"}
    ],
    "source_service": "procurement",
    "source_data_id": "price_forecast_123"
}

response = httpx.post(
    "http://localhost:8000/api/v1/ai-insights/tenants/550e8400-e29b-41d4-a716-446655440000/insights",
    json=insight_data
)
print(response.json())

Querying Insights

# Get high-confidence actionable insights
response = httpx.get(
    "http://localhost:8000/api/v1/ai-insights/tenants/550e8400-e29b-41d4-a716-446655440000/insights",
    params={
        "actionable_only": True,
        "min_confidence": 80,
        "priority": "high",
        "page": 1,
        "page_size": 20
    }
)
insights = response.json()

Recording Feedback

feedback_data = {
    "insight_id": "insight-uuid",
    "action_taken": "create_purchase_order",
    "success": True,
    "expected_impact_value": 120.50,
    "actual_impact_value": 115.30,
    "result_data": {
        "order_id": "PO-12345",
        "actual_savings": 115.30
    },
    "applied_by": "user@example.com"
}

response = httpx.post(
    f"http://localhost:8000/api/v1/ai-insights/tenants/{tenant_id}/insights/{insight_id}/feedback",
    json=feedback_data
)

Development

Running Tests

pytest

Code Quality

# Format code
black app/

# Lint
flake8 app/

# Type checking
mypy app/

Creating a Migration

alembic revision --autogenerate -m "Description of changes"
alembic upgrade head

Insight Types

• optimization: Process improvements with measurable gains
• alert: Warnings requiring attention
• prediction: Future forecasts with confidence intervals
• recommendation: Suggested actions with estimated impact
• insight: General data-driven observations
• anomaly: Unusual patterns detected in data

Priority Levels

• critical: Immediate action required (e.g., stockout risk)
• high: Action recommended soon (e.g., price opportunity)
• medium: Consider acting (e.g., efficiency improvement)
• low: Informational (e.g., pattern observation)

Categories

• forecasting: Demand predictions and patterns
• inventory: Stock management and optimization
• production: Manufacturing efficiency and scheduling
• procurement: Purchasing and supplier management
• customer: Customer behavior and satisfaction
• cost: Cost optimization opportunities
• quality: Quality improvements
• efficiency: Process efficiency gains

Integration with Other Services

Forecasting Service

• Receives forecast accuracy insights
• Pattern detection alerts
• Demand anomaly notifications

Procurement Service

• Price forecast recommendations
• Supplier performance alerts
• Safety stock optimization

Production Service

• Yield prediction insights
• Schedule optimization recommendations
• Equipment maintenance alerts

Orchestrator Service

• Pre-orchestration insight gathering
• Actionable recommendation filtering
• Feedback recording for applied insights

API Documentation

Once the service is running, interactive API documentation is available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Monitoring

Health Check

curl http://localhost:8000/health

Metrics Endpoint

curl http://localhost:8000/api/v1/ai-insights/tenants/{tenant_id}/insights/metrics/summary

License

Copyright © 2025 Bakery IA. All rights reserved.

Support

For issues and questions, please contact the development team or create an issue in the project repository.