bakery-ia/services/ai_insights/QUICK_START.md

AI Insights Service - Quick Start Guide

Get the AI Insights Service running in 5 minutes.

Prerequisites

• Python 3.11+
• PostgreSQL 14+ (running)
• Redis 6+ (running)

Step 1: Setup Environment

cd services/ai_insights

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Step 2: Configure Database

# Copy environment template
cp .env.example .env

# Edit .env file
nano .env

Minimum required configuration:

DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/bakery_ai_insights
REDIS_URL=redis://localhost:6379/5

Step 3: Create Database

# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE bakery_ai_insights;
\q

Step 4: Run Migrations

# Run Alembic migrations
alembic upgrade head

You should see:

INFO  [alembic.runtime.migration] Running upgrade  -> 001, Initial schema for AI Insights Service

Step 5: Start the Service

uvicorn app.main:app --reload

You should see:

INFO:     Uvicorn running on http://127.0.0.1:8000
INFO:     Application startup complete.

Step 6: Verify Installation

Open browser to http://localhost:8000/docs

You should see the Swagger UI with all API endpoints.

Test Health Endpoint

curl http://localhost:8000/health

Expected response:

{
  "status": "healthy",
  "service": "ai-insights",
  "version": "1.0.0"
}

Step 7: Create Your First Insight

curl -X POST "http://localhost:8000/api/v1/ai-insights/tenants/550e8400-e29b-41d4-a716-446655440000/insights" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "recommendation",
    "priority": "high",
    "category": "forecasting",
    "title": "Test Insight - Weekend Demand Pattern",
    "description": "Weekend sales 20% higher than weekdays",
    "impact_type": "revenue_increase",
    "impact_value": 150.00,
    "impact_unit": "euros/week",
    "confidence": 85,
    "metrics_json": {
      "weekday_avg": 45.2,
      "weekend_avg": 54.2,
      "increase_pct": 20.0
    },
    "actionable": true,
    "recommendation_actions": [
      {"label": "Increase Production", "action": "adjust_production"}
    ],
    "source_service": "forecasting"
  }'

Step 8: Query Your Insights

curl "http://localhost:8000/api/v1/ai-insights/tenants/550e8400-e29b-41d4-a716-446655440000/insights?page=1&page_size=10"

Common Issues

Issue: "ModuleNotFoundError: No module named 'app'"

Solution: Make sure you're running from the services/ai_insights/ directory and virtual environment is activated.

Issue: "Connection refused" on database

Solution: Verify PostgreSQL is running:

# Check if PostgreSQL is running
pg_isready

# Start PostgreSQL (macOS with Homebrew)
brew services start postgresql

# Start PostgreSQL (Linux)
sudo systemctl start postgresql

Issue: "Redis connection error"

Solution: Verify Redis is running:

# Check if Redis is running
redis-cli ping

# Should return: PONG

# Start Redis (macOS with Homebrew)
brew services start redis

# Start Redis (Linux)
sudo systemctl start redis

Issue: "Alembic command not found"

Solution: Virtual environment not activated:

source venv/bin/activate

Next Steps

1. Explore API: Visit http://localhost:8000/docs
2. Read Documentation: See README.md for detailed documentation
3. Implementation Guide: See AI_INSIGHTS_IMPLEMENTATION_SUMMARY.md
4. Integration: Start integrating with other services

Useful Commands

# Check service status
curl http://localhost:8000/health

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

# Filter high-confidence insights
curl "http://localhost:8000/api/v1/ai-insights/tenants/{tenant_id}/insights?actionable_only=true&min_confidence=80"

# Stop the service
# Press Ctrl+C in the terminal running uvicorn

# Deactivate virtual environment
deactivate

Docker Quick Start (Alternative)

If you prefer Docker:

# Build image
docker build -t ai-insights .

# Run container
docker run -d \
  --name ai-insights \
  -p 8000:8000 \
  -e DATABASE_URL=postgresql+asyncpg://postgres:postgres@host.docker.internal:5432/bakery_ai_insights \
  -e REDIS_URL=redis://host.docker.internal:6379/5 \
  ai-insights

# Check logs
docker logs ai-insights

# Stop container
docker stop ai-insights
docker rm ai-insights

Support

• Documentation: See README.md
• API Docs: http://localhost:8000/docs
• Issues: Create GitHub issue or contact team

---

You're ready! The AI Insights Service is now running and ready to accept insights from other services.