The AI Insights Service provides intelligent, actionable recommendations to bakery operators by analyzing patterns across inventory, production, procurement, and sales data. It acts as a virtual operations consultant, proactively identifying opportunities for cost savings, waste reduction, and operational improvements. This service transforms raw data into business intelligence that drives profitability.

Key Features

Intelligent Recommendations

Inventory Optimization - Smart reorder point suggestions and stock level adjustments
Production Planning - Optimal batch size and scheduling recommendations
Procurement Suggestions - Best supplier selection and order timing advice
Sales Opportunities - Identify trending products and underperforming items
Cost Reduction - Find areas to reduce waste and lower operational costs
Quality Improvements - Detect patterns affecting product quality

Unified Insight Management

Centralized Storage - All AI-generated insights in one place
Confidence Scoring - Standardized 0-100% confidence calculation across 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

Insight Aggregation
- Collect insights from Forecasting, Procurement, Production, and Sales services
- Categorize and prioritize recommendations
- Filter by confidence, category, priority, and actionability
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
Impact Estimation
- Cost savings quantification
- Revenue increase projections
- Waste reduction calculations
- Efficiency gain measurements
- Quality improvement tracking
Feedback & Learning
- Track application outcomes
- Compare expected vs. actual impact
- Calculate success rates
- Enable model improvement
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

Clone and navigate:
```
cd services/ai_insights
```

Create virtual environment:

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

Install dependencies:
```
pip install -r requirements.txt
```

Configure environment:

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

Run migrations:
```
alembic upgrade head
```
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)

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

Support

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

README.md

AI Insights Service

Overview