AI Assistant - Quick Start Guide

🎯 Obiettivo: AI Assistant contestualizzato con costi <$5/mese

---

📋 Checklist Implementazione

✅ Fase 1: Database & Knowledge Base (Settimana 1-2)

1.1 Migrations

bash
php artisan make:migration create_ai_assistant_tables


Tabelle da creare:

[ ] ai_conversations (storico conversazioni)

[ ] ai_messages (messaggi chat)

[ ] ai_knowledge_templates (template risposte)

[ ] ai_cache (cache risposte)

[ ] ai_feedback (thumbs up/down)

[ ] ai_usage_analytics (metriche costi/uso)

`1.2 Seeding Knowledge Base`

bash
php artisan make:seeder AiKnowledgeTemplatesSeeder


Template da creare (30-40 totali):
AMBITO_PRODUZIONE (8 template):

[ ] prod_daily - "produzione di ieri/oggi"

[ ] prod_weekly - "produzione questa settimana"

[ ] prod_monthly - "produzione questo mese"

[ ] prod_total - "totale pezzi"

[ ] prod_trend - "trend produzione"

[ ] prod_comparison - "confronta periodi"

[ ] prod_by_material - "produzione per materiale"

[ ] prod_by_operator - "produzione per operatore"

AMBITO_DIAGNOSTICA (6 template):

[ ] diag_downtime - "perché fermata macchina"

[ ] diag_errors - "errori oggi/periodo"

[ ] diag_slow_ops - "operazioni lente"

[ ] diag_low_production - "produzione bassa"

[ ] diag_anomaly - "anomalia rilevata"

[ ] diag_gaps - "fermi non registrati"

AMBITO_OPERATORI (5 template):

[ ] op_ranking - "ranking operatori"

[ ] op_best - "operatore migliore"

[ ] op_performance - "performance operatore X"

[ ] op_comparison - "confronta operatori"

[ ] op_avg_stats - "statistiche medie operatore"

AMBITO_CONFIGURAZIONE (4 template):

[ ] config_profiles - "profili macchina"

[ ] config_fields - "campi disponibili"

[ ] config_last_import - "ultimo import CSV"

[ ] config_machine_info - "info macchina"

AMBITO_PIANIFICAZIONE (5 template):

[ ] plan_deadline - "ce la facciamo entro X?"

[ ] plan_time_estimate - "quanto ci vuole per X pezzi"

[ ] plan_capacity - "capacità produttiva"

[ ] plan_forecast - "previsione completamento"

[ ] plan_working_days - "giorni lavorativi necessari"

AMBITO_COMPARAZIONE (6 template):

[ ] comp_weeks - "questa settimana vs scorsa"

[ ] comp_days - "oggi vs ieri"

[ ] comp_months - "questo mese vs scorso"

[ ] comp_machines - "macchina A vs B"

[ ] comp_operators - "operatore A vs B"

[ ] comp_trend_7d - "trend ultimi 7 giorni"

AMBITO_OTTIMIZZAZIONE (4 template - richiedono LLM):

[ ] opt_suggestions - "come migliorare"

[ ] opt_bottlenecks - "colli di bottiglia"

[ ] opt_best_practices - "best practices"

[ ] opt_efficiency - "aumentare efficienza"

---

`✅ Fase 2: Services Layer (Settimana 3)`

`2.1 Intent Router`

bash
php artisan make:service I40/AI/IntentRouterService


File da creare:

[ ] app/Services/I40/AI/IntentPatterns.php (regex dictionary)

[ ] app/Services/I40/AI/IntentRouterService.php (pattern matching)

Funzionalità:

[ ] Normalizza query (lowercase, rimuovi punteggiatura)


[ ] Pattern matching con regex
[ ] Entity extraction (date, numeri, nomi)
[ ] Confidence score (0-1)
2.2 Knowledge Base Service

bash
php artisan make:service I40/AI/KnowledgeBaseService


Funzionalità:
[ ] Template lookup da DB
[ ] Parameter binding (date, machine_id, etc.)
[ ] SQL execution (safe, timeout, validation)
[ ] Context enrichment (media, confronti)
[ ] Response formatting
2.3 Cache Service

bash
php artisan make:service I40/AI/CacheService


Funzionalità:
[ ] Query hash generation (MD5)
[ ] Cache storage (TTL configurabile)
[ ] Cache invalidation (su nuovi dati)
[ ] Hit rate tracking
2.4 LLM Fallback Service

bash
php artisan make:service I40/AI/LLMFallbackService


Funzionalità:
[ ] Minimal prompt building
[ ] OpenAI API integration
[ ] Token usage tracking
[ ] Cost estimation
[ ] Temperature control (0.2-0.3)
2.5 Main Orchestrator

bash
php artisan make:service I40/AI/AiAssistantService


Funzionalità:
[ ] Orchestrates all services
[ ] Decision tree (template → LLM fallback)
[ ] Conversation context management
[ ] Analytics tracking
---
✅ Fase 3: Controller & Routes (Settimana 4)
3.1 Controller

bash
php artisan make:controller Admin/I40/AiAssistantController


Metodi da implementare:

[ ] chat(Request) - POST /ai/chat

[ ] conversations() - GET /ai/conversations

[ ] show($id) - GET /ai/conversations/{id}

[ ] feedback(Request) - POST /ai/feedback

[ ] analytics() - GET /ai/analytics (admin)

`3.2 Routes`

php
// routes/i40.php
Route::prefix('ai')->name('ai.')->middleware('auth')->group(function () {
    Route::post('/chat', [AiAssistantController::class, 'chat']);
    Route::get('/conversations', [AiAssistantController::class, 'conversations']);
    Route::get('/conversations/{id}', [AiAssistantController::class, 'show']);
    Route::post('/feedback', [AiAssistantController::class, 'feedback']);
    
    Route::middleware('role:admin')->group(function () {
        Route::get('/analytics', [AiAssistantController::class, 'analytics']);
    });
});


---
✅ Fase 4: Frontend Widget (Settimana 5)
4.1 Blade Component

bash
Crea file
touch resources/views/components/ai-chat-widget.blade.php


Features da implementare:
[ ] Chat UI (messaggi user/assistant)
[ ] Input textarea + send button
[ ] Suggestions buttons (iniziali + follow-up)
[ ] Loading indicator (typing animation)
[ ] Feedback buttons (thumbs up/down)
[ ] Badge ambito corrente
[ ] Minimize/maximize widget
[ ] Scroll to bottom auto
4.2 Integrazione in Analyze View

blade
<!-- resources/views/admin/i40/operations/analyze.blade.php -->
@section('content')
<!-- ... existing content ... -->

 @include('components.ai-chat-widget', [ 'machine' => $selectedMachine, ]) @endsection`

`4.3 Stile CSS`

bash
Aggiungi inline in widget oppure
touch public/css/ai-chat-widget.css


Classi CSS da implementare:

[ ] .ai-chat-widget (container fisso bottom-right)

[ ] .chat-header (gradient, clickable)

[ ] .messages-container (scroll, padding)

[ ] .message.user / .message.assistant (bubble style)

[ ] .follow-up-suggestions (button grid)

[ ] .typing-indicator (3 dots animati)

---

`✅ Fase 5: Testing & Refinement (Settimana 6)`

`5.1 Unit Tests`

bash
php artisan make:test I40/AI/IntentRouterTest --unit
php artisan make:test I40/AI/KnowledgeBaseTest --unit


Test da implementare:
[ ] Intent detection accuracy (70%+ coverage)
[ ] Entity extraction (date, numeri, nomi)
[ ] Template lookup (match corretto)
[ ] SQL safety (prevent injection)
[ ] Cache hit/miss
[ ] Cost estimation
5.2 Integration Tests

bash
php artisan make:test I40/AI/AiChatFlowTest


Scenarios da testare:
[ ] Query semplice (produzione ieri) → Template
[ ] Query complessa (ottimizzazione) → LLM
[ ] Cache hit (query ripetuta)
[ ] Feedback (thumbs up/down)
[ ] Conversation context (multi-turn)
5.3 User Acceptance Testing
[ ] 5 operatori testano con query reali
[ ] Raccolta feedback qualitativo
[ ] Identificazione template mancanti
[ ] Refinement pattern matching
[ ] Improvement response templates
---
📊 Dashboard Analytics (Admin)
View da creare

bash
touch resources/views/admin/i40/ai/analytics.blade.php


Metriche da mostrare:
Usage Stats:
[ ] Totale query (periodo)
[ ] Query con LLM (%)
[ ] Utenti attivi
[ ] Query per ambito (breakdown)
Performance:
[ ] Latency media (ms)
[ ] Cache hit rate (%)
[ ] Template usage (top 10)
Quality:
[ ] Satisfaction rate (%)
[ ] Feedback positivi/negativi
[ ] Query fallite (no template, no LLM response)
Costs:
[ ] Totale tokens usati
[ ] Costo stimato ($)
[ ] Proiezione mensile
Chart.js Graphs:
[ ] Query per giorno (line chart)
[ ] Query per ambito (pie chart)
[ ] Top template (bar chart)
[ ] Satisfaction trend (line chart)
---
🔧 Configuration
.env

bash
AI Assistant
OPENAI_API_KEY=sk-proj-...
OPENAI_MODEL=gpt-4o-mini
OPENAI_MAX_TOKENS=300
OPENAI_TEMPERATURE=0.2

AI_ENABLED=true AI_CACHE_TTL=3600 AI_MAX_CONVERSATIONS_PER_USER=100 AI_MAX_MESSAGES_PER_CONVERSATION=50`

`config/ai.php`

bash
php artisan vendor:publish --tag=openai-config

Configurazioni custom:`php return [ 'enabled' => env('AI_ENABLED', true), 'openai' => [ 'api_key' => env('OPENAI_API_KEY'), 'model' => env('OPENAI_MODEL', 'gpt-4o-mini'), 'max_tokens' => env('OPENAI_MAX_TOKENS', 300), 'temperature' => env('OPENAI_TEMPERATURE', 0.2), ], 'cache' => [ 'enabled' => true, 'ttl' => env('AI_CACHE_TTL', 3600), 'driver' => 'database', // o 'redis' ], 'limits' => [ 'max_conversations_per_user' => 100, 'max_messages_per_conversation' => 50, 'max_query_length' => 500, ], 'cost_tracking' => [ 'enabled' => true, 'input_cost_per_1m_tokens' => 0.15, // GPT-4o-mini 'output_cost_per_1m_tokens' => 0.60, ], ];`

---

`🚀 Deployment`

`Pre-Deploy Checklist`


[ ] Migrations run (production DB)
[ ] Seeder run (knowledge templates)
[ ] OpenAI API key configured
[ ] Cache driver configured (redis preferred)
[ ] Error logging configured
[ ] Analytics dashboard accessible (admin only)
Post-Deploy Monitoring
[ ] Query success rate > 95%
[ ] LLM usage < 20%
[ ] Latency < 1s (p95)
[ ] Costi < $5/mese (primi 50 utenti)
[ ] Satisfaction rate > 85%
---
📈 Roadmap Evolutiva
Fase 2 (Mese 2-3)
[ ] Voice input (Speech-to-Text)
[ ] Export conversazioni (PDF/Excel)
[ ] Alert automation (notifiche proattive)
[ ] Multi-macchina queries ("confronta tutte le macchine")
[ ] Grafici inline (Chart.js embeddati in risposta)
Fase 3 (Mese 4-6)
[ ] Fine-tuning LLM (modello custom su dominio)
[ ] Embeddings + Vector DB (semantic search)
[ ] Suggerimenti proattivi (dashboard insights)
[ ] Mobile app integration
[ ] Multi-lingua (EN, ES)
---
💰 Budget Stimato
Setup Iniziale (One-Time)
Sviluppo: 6 settimane × 40h = 240 ore
Testing: 1 settimana × 20h = 20 ore
Totale: ~260 ore
Costi Mensili Operativi
| Voce | Costo |
|------|-------|
| OpenAI API (50 utenti, 20% LLM) | $3-5/mese |
| Hosting (cache Redis) | $0 (già incluso) |
| Manutenzione (1h/settimana) | ~4 ore/mese |
Totale mensile: $3-5 + manutenzione
ROI Atteso
Risparmio tempo analisi dati: 30 min/giorno/utente → 25h/mese × 10 utenti = 250h/mese
Decisioni più rapide: Riduzione downtime macchina ~2h/mese = €400-1000/mese
ROI netto: €3.000-5.000/mese (conservativo)
---
✅ Success Criteria
Settimana 6 (MVP Launch)
✅ 80%+ query gestite da template (no LLM)
✅ Latency < 1s per 90% query
✅ Costi < $10/mese primi 50 utenti
✅ 5 operatori testano e approvano UX
Mese 3 (Produzione)
✅ 60%+ utenti usano AI settimanalmente
✅ Satisfaction rate > 85%
✅ 50%+ domande risolte autonomamente
✅ ROI positivo (risparmi > costi)

---

`🎯 Prossimo Step`

1. Revisionare Documentazione: - [ ] AI_ASSISTANT_ARCHITECTURE_v2.md (dettaglio tecnico) - [ ] EXECUTIVE_SUMMARY_AI_ASSISTANT.md (visione business) - [ ] QUICK_START_AI_IMPLEMENTATION.md (questa guida)

2. Decidere Priorità: - Partire subito? (Settimana 1: Database + Templates) - Testare PoC? (1 ambito, 5 template, controller minimo) - Approfondire costi? (Budget planning dettagliato)

3. Setup Iniziale:`bash # OpenAI API Key # Registrati su https://platform.openai.com # Crea API key # Aggiungi a .env # Verifica connection php artisan tinker >>> OpenAI::chat()->create(['model' => 'gpt-4o-mini', 'messages' => [['role' => 'user', 'content' => 'Test']]]);``

---

Pronto? Iniziamo! 🚀

Analisi Codice

Blocco 1 bash

php artisan make:migration create_ai_assistant_tables

Blocco 2 bash

php artisan make:seeder AiKnowledgeTemplatesSeeder

Blocco 3 bash

php artisan make:service I40/AI/IntentRouterService

Blocco 4 bash

php artisan make:service I40/AI/KnowledgeBaseService

Blocco 5 bash

php artisan make:service I40/AI/CacheService

Blocco 6 bash

php artisan make:service I40/AI/LLMFallbackService

Blocco 7 bash

php artisan make:service I40/AI/AiAssistantService

Blocco 8 bash

php artisan make:controller Admin/I40/AiAssistantController

Blocco 9 php

// routes/i40.php
Route::prefix('ai')->name('ai.')->middleware('auth')->group(function () {
    Route::post('/chat', [AiAssistantController::class, 'chat']);
    Route::get('/conversations', [AiAssistantController::class, 'conversations']);
    Route::get('/conversations/{id}', [AiAssistantController::class, 'show']);
    Route::post('/feedback', [AiAssistantController::class, 'feedback']);
    
    Route::middleware('role:admin')->group(function () {
        Route::get('/analytics', [AiAssistantController::class, 'analytics']);
    });
});

Blocco 10 bash

# Crea file
touch resources/views/components/ai-chat-widget.blade.php

Blocco 11 blade

<!-- resources/views/admin/i40/operations/analyze.blade.php -->

@section('content')
<!-- ... existing content ... -->

<!-- AI Chat Widget (Fixed bottom-right) -->
@include('components.ai-chat-widget', [
    'machine' => $selectedMachine,
])
@endsection

Blocco 12 bash

# Aggiungi inline in widget oppure
touch public/css/ai-chat-widget.css

Blocco 13 bash

php artisan make:test I40/AI/IntentRouterTest --unit
php artisan make:test I40/AI/KnowledgeBaseTest --unit

Blocco 14 bash

php artisan make:test I40/AI/AiChatFlowTest

Blocco 15 bash

touch resources/views/admin/i40/ai/analytics.blade.php

Blocco 16 bash

# AI Assistant
OPENAI_API_KEY=sk-proj-...
OPENAI_MODEL=gpt-4o-mini
OPENAI_MAX_TOKENS=300
OPENAI_TEMPERATURE=0.2

AI_ENABLED=true
AI_CACHE_TTL=3600
AI_MAX_CONVERSATIONS_PER_USER=100
AI_MAX_MESSAGES_PER_CONVERSATION=50

Blocco 17 bash

php artisan vendor:publish --tag=openai-config

Blocco 18 php

return [
    'enabled' => env('AI_ENABLED', true),
    
    'openai' => [
        'api_key' => env('OPENAI_API_KEY'),
        'model' => env('OPENAI_MODEL', 'gpt-4o-mini'),
        'max_tokens' => env('OPENAI_MAX_TOKENS', 300),
        'temperature' => env('OPENAI_TEMPERATURE', 0.2),
    ],
    
    'cache' => [
        'enabled' => true,
        'ttl' => env('AI_CACHE_TTL', 3600),
        'driver' => 'database', // o 'redis'
    ],
    
    'limits' => [
        'max_conversations_per_user' => 100,
        'max_messages_per_conversation' => 50,
        'max_query_length' => 500,
    ],
    
    'cost_tracking' => [
        'enabled' => true,
        'input_cost_per_1m_tokens' => 0.15, // GPT-4o-mini
        'output_cost_per_1m_tokens' => 0.60,
    ],
];

Blocco 19 bash

   # OpenAI API Key
   # Registrati su https://platform.openai.com
   # Crea API key
   # Aggiungi a .env
   
   # Verifica connection
   php artisan tinker
   >>> OpenAI::chat()->create(['model' => 'gpt-4o-mini', 'messages' => [['role' => 'user', 'content' => 'Test']]]);

Indice

Info Documento

AI Assistant - Quick Start Guide

AI Assistant - Quick Start Guide

📋 Checklist Implementazione

✅ Fase 1: Database & Knowledge Base (Settimana 1-2)

1.1 Migrations

1.2 Seeding Knowledge Base

✅ Fase 2: Services Layer (Settimana 3)

2.1 Intent Router

2.2 Knowledge Base Service

2.3 Cache Service

2.4 LLM Fallback Service

2.5 Main Orchestrator

✅ Fase 3: Controller & Routes (Settimana 4)

3.1 Controller

3.2 Routes

✅ Fase 4: Frontend Widget (Settimana 5)

4.1 Blade Component

Crea file

4.2 Integrazione in Analyze View

4.3 Stile CSS

Aggiungi inline in widget oppure

✅ Fase 5: Testing & Refinement (Settimana 6)

5.1 Unit Tests

5.2 Integration Tests

5.3 User Acceptance Testing

📊 Dashboard Analytics (Admin)

View da creare

🔧 Configuration

.env

AI Assistant

config/ai.php

🚀 Deployment

Pre-Deploy Checklist

Post-Deploy Monitoring

📈 Roadmap Evolutiva

Fase 2 (Mese 2-3)

Fase 3 (Mese 4-6)

💰 Budget Stimato

Setup Iniziale (One-Time)

Costi Mensili Operativi

ROI Atteso

✅ Success Criteria

Settimana 6 (MVP Launch)

Mese 3 (Produzione)

🎯 Prossimo Step

Analisi Codice

Blocco 1 bash

Blocco 2 bash

Blocco 3 bash

Blocco 4 bash

Blocco 5 bash

Blocco 6 bash

Blocco 7 bash

Blocco 8 bash

Blocco 9 php

Blocco 10 bash

Blocco 11 blade

Blocco 12 bash

Blocco 13 bash

Blocco 14 bash

Blocco 15 bash

Blocco 16 bash

Blocco 17 bash

Blocco 18 php

Blocco 19 bash

Documenti Correlati

Indice

Info Rapide

Documenti Correlati

Screenshot

`1.2 Seeding Knowledge Base`

`✅ Fase 2: Services Layer (Settimana 3)`

`2.1 Intent Router`

`3.2 Routes`

`4.3 Stile CSS`

`✅ Fase 5: Testing & Refinement (Settimana 6)`

`5.1 Unit Tests`

`config/ai.php`

`🚀 Deployment`

`Pre-Deploy Checklist`

`🎯 Prossimo Step`