Flow Docs

ai-services-vision

7 min read

AI Services Vision

Stato: Framework presente, zero implementazione ML Ultima revisione: Marzo 2026

Contesto

L’architettura di Flow prevede un livello di servizi AI (ai_services/) basato su FastAPI. Attualmente il framework esiste ma non c’è nessuna implementazione ML reale. Questo documento definisce la visione a lungo termine e un piano di implementazione realistico per arrivare a raccomandazioni e matchmaking alimentati dai dati.

Principio fondamentale: Le raccomandazioni di Flow non devono sembrare algoritmiche. Devono sembrare suggerimenti di un amico che conosce bene la scena. “Potrebbe piacerti questo evento” è diverso da “Ti suggeriamo in base ai tuoi dati”.

Capacità AI previste

1. Raccomandazione eventi

Obiettivo: Mostrare nel feed gli eventi più rilevanti per ogni utente, ordinati per probabilità di interesse.

Input disponibili:

  • Storico RSVP dell’utente (eventi a cui ha partecipato)
  • Categorie/vibe preferite (da onboarding e comportamento)
  • Posizione geografica
  • Orari tipici di uscita
  • Amici che vengono allo stesso evento (social proof)
  • Crew attive
  • Karma e livello (proxy per tipo di utente)

Approccio a fasi:

Fase 0 (subito, no ML): Filtering basato su regole

  • Filtra per distanza e categoria
  • Boosta eventi dove almeno 1 amico ha RSVP
  • Ordina per data

Fase 1 (early stage, dati limitati): Collaborative filtering semplice

  • “Utenti simili a te hanno partecipato a questi eventi”
  • Similarità calcolata su RSVP overlap
  • Matrix factorization (SVD) o simile

Fase 2 (crescita, dati sufficienti): Neural collaborative filtering

  • Embedding per utenti ed eventi
  • Feature aggiuntive: orario, meteo, giorno settimana, prezzo
  • Modello two-tower (user tower + event tower)

Fase 3 (maturità): Real-time personalization

  • Feed personalizzato aggiornato in real-time
  • Consideration di eventi “trending” nella tua rete
  • A/B testing sistematico sulle raccomandazioni

2. Crew Matchmaking

Obiettivo: Suggerire eventi a una crew basandosi sugli interessi sovrapposti dei membri.

Input:

  • Interessi individuali di ogni membro
  • Storico eventi della crew
  • Vincoli logistici (budget, distanza, orario)
  • Tier di connessione tra i membri

Approccio: Il matchmaking crew è fondamentalmente un problema di aggregazione di preferenze (social choice theory). Le opzioni sono:

  • Majority voting: Proponi eventi dove la maggioranza dei membri ha espresso interesse
  • Least misery: Massimizza il minimo (nessun membro deve odiare la scelta)
  • Average satisfaction: Massimizza la media (qualcuno potrebbe essere molto infelice)

Per una piattaforma social, “least misery” tende a funzionare meglio per la coesione del gruppo.

Wizard crew: Il wizard di matchmaking già implementato può diventare il punto di raccolta delle preferenze individuali. L’AI aggrega e propone.

3. Ricerca semantica eventi

Obiettivo: “Voglio qualcosa di chill ma non noioso sabato sera” → lista eventi rilevanti.

Approccio:

  • Embedding testuale di descrizioni eventi (BERT, Sentence Transformers)
  • Query utente → embedding → cosine similarity con eventi
  • Hybrid search: semantico + keyword + filtri strutturati

Stack suggerito:

  • Elasticsearch o pgvector (PostgreSQL extension già citata nell’architettura)
  • Sentence Transformers (multilingual per supporto italiano)
  • La ricerca semantica può essere aggiunta come layer sopra la ricerca attuale (ILIKE) senza sostituirla

4. Analisi sentiment recensioni

Obiettivo: Aggregare automaticamente il sentiment delle recensioni post-evento, estrarre topic ricorrenti (“ottima musica”, “troppo affollato”, “staff scortese”).

Input: Recensioni testuali (schermata “Crea recensione” esiste già).

Output:

  • Score sentiment (positivo/neutro/negativo)
  • Topic extraction (es. “musica”, “affollamento”, “prezzi”)
  • Summary automatico (“92% positivo, ottima vibe ma bar lento”)

Stack: LLM con structured output. Con piccoli volumi, anche un modello leggero (es. GPT-4o mini o Claude Haiku) è sufficiente e cost-effective.

5. Moderazione contenuti

Obiettivo: Rilevare automaticamente contenuti inappropriati (foto avatar, descrizioni eventi, nomi crew).

Approccio:

  • Image moderation: API esistenti (AWS Rekognition, Google Vision) — no ML custom necessario
  • Text moderation: Classificatore leggero per slurs, spam, contenuti illegali
  • Zero-shot classification con LLM per casi edge

Architettura tecnica

Stack attuale

ai_services/
├── app/
│   └── main.py          (FastAPI app — solo scaffolding)
├── requirements.txt
└── Dockerfile

Stack target

ai_services/
├── app/
│   ├── main.py
│   ├── routers/
│   │   ├── recommendations.py    # GET /recommend/events?user_id=
│   │   ├── matchmaking.py        # POST /matchmaking/crew
│   │   └── search.py             # POST /search/semantic
│   ├── models/
│   │   ├── recommendation_model.py
│   │   └── embeddings.py
│   └── services/
│       ├── event_fetcher.py      # legge da Event Service
│       └── user_fetcher.py       # legge da User Service
├── training/
│   ├── data_pipeline.py          # ETL per training data
│   └── train_recommender.py
└── tests/

Comunicazione inter-servizi

L’AI service ha bisogno di leggere dati da Event Service e User Service. Opzioni:

  1. Direct DB read — l’AI service legge direttamente da MongoDB/PostgreSQL (più veloce, accoppiamento alto)
  2. Via API Gateway — chiama le API esistenti (più pulito, ma latenza extra)
  3. Read replica dedicata — un DB replica solo per letture AI (vedi architecture-issues Issue #5)

Per le raccomandazioni in real-time, la lettura diretta da read replica è la scelta più pragmatica.

Piano di implementazione realistico

Milestone 0 — Pre-ML (ora)

Senza ML, migliorare la rilevanza del feed con regole.

  • Boostare eventi con amici presenti (+50% score ranking)
  • Filtrare eventi per categoria preferita utente
  • Filtrare per distanza geografica
  • Mostrare “I tuoi amici vengono” nel feed card

Effort: 2-3 giorni. ROI: immediato.

Milestone 1 — Infrastruttura dati (prima del ML)

Senza dati buoni, il ML non serve.

  • Logging eventi utente (click, RSVP, scroll time, share) → user_events table
  • Schema event_embeddings per ricerca semantica
  • Pipeline ETL per preparare training data
  • A/B testing infrastructure per misurare impatto raccomandazioni

Effort: 1-2 settimane.

Milestone 2 — Raccomandazione collaborative filtering

  • Implementare modello SVD su RSVP matrix
  • Endpoint /recommend/events
  • Integrazione nel feed Flutter (sezione “Potrebbero piacerti”)

Effort: 1-2 settimane. Richiede: ~1000+ utenti con storico RSVP per funzionare bene.

Milestone 3 — Ricerca semantica

  • Generare embedding delle descrizioni eventi (batch job notturno)
  • pgvector in Supabase (extension già supportata)
  • Hybrid search: keyword + semantico
  • Integrazione nella SearchScreen

Effort: 1 settimana. Indipendente dal numero di utenti — funziona subito.

Milestone 4 — Crew matchmaking AI

  • Raccogliere preferenze individuali nel wizard crew
  • Implementare algoritmo “least misery” aggregation
  • Ranking finale con ML se dati sufficienti

Effort: 2-3 giorni logic, 1 settimana se ML.

Considerazioni etiche

Trasparenza: Gli utenti devono sapere che il feed è personalizzato. Un semplice “Scelti per te” è sufficiente — non serve spiegare l’algoritmo.

Filter bubble: Se le raccomandazioni sono troppo buone, gli utenti vedranno sempre lo stesso tipo di evento. Inserire diversità esplicita: almeno 20% del feed deve includere eventi “fuori dalla comfort zone”.

Privacy: I dati di comportamento (click, tempo di lettura) sono sensibili. Vanno trattati secondo GDPR. Nessun dato personale deve uscire dall’infrastruttura per il training.

Cold start: Un nuovo utente senza storico non può ricevere raccomandazioni personalizzate. Strategia cold start: onboarding con selezione esplicita di interessi, poi content-based filtering finché non ci sono abbastanza interazioni.

Metriche di successo

MetricaBaseline attualeTarget Milestone 2
CTR su eventi raccomandati— (non misurato)> 8%
RSVP rate da feed—> 3%
Diversity score (varianza categorie visitate)—> 0.6
Tempo medio a primo RSVP (new user)—< 5 minuti

Open Questions

  1. Quando ha senso investire in ML? Il ML richiede dati. Quanti utenti attivi con storico RSVP servono per un modello collaborative filtering utile? Stima: almeno 500-1000 utenti con ≥5 RSVP ciascuno.

  2. LLM per recommendation? Con l’avanzamento dei modelli, è possibile usare un LLM come “motore di raccomandazione” con prompt engineering invece di ML tradizionale. Costo più alto ma zero training, zero cold start. Da valutare quando la scala lo giustifica.

  3. Chi gestisce il modello in produzione? Il retraining del modello richiede un data scientist o un MLOps pipeline. Per uno startup early-stage, la regola è: non costruire ML che non puoi mantenere.

Riferimenti

  • ai_services/ — framework FastAPI esistente
  • architecture/technical-architecture.md — architettura generale
  • architecture/improvements.md — Issue #5: AI read replica
  • Feature tracker: project/feature-tracker.md — sezione AI Services

Graph View