L'assistente IA¶

L'IA propone, la persona decide. L'assistente trova gli orari e risponde alle domande; non prenota e non paga mai al posto del cittadino.

Cosa fa¶

Come è fatto¶

L'IA vive in un server di inferenza separato (inference/), raggiungibile solo dall'app sulla rete interna di Docker e compatibile con lo standard di mercato delle API dei modelli linguistici (formato OpenAI).

sequenceDiagram
  autonumber
  actor C as Cittadino
  participant A as App (FastAPI)
  participant I as Server di inferenza
  participant L as LLM (opzionale)
  C->>A: "calcetto venerdì sera alle 20"
  A->>I: POST /v1/tasks/intent
  I->>I: motore a regole italiano (sempre)
  alt confidenza bassa e LLM configurato
    I->>I: rimozione dati personali (CF, email, telefono, IBAN)
    I->>L: chat/completions (JSON)
    L-->>I: campi estratti
    I->>I: validazione e normalizzazione dei campi
  end
  I-->>A: {attivita, data, fascia, ora, backend, generato_da_ia}
  A->>A: incrocia con il calendario reale (slot liberi)
  A-->>C: 2-4 orari proposti, la scelta è sua

Due motori, una sola interfaccia¶

Il modello linguistico estrae e basta: date relative ("domani", "venerdì"), orari validi e attività ammesse vengono sempre risolti e controllati dal codice. Un campo non valido restituito dal modello viene scartato.

Esempi reali¶

Risposte del server di inferenza (backend: rules) con data di riferimento lunedì 9 novembre 2026:

# dal container app (il server di inferenza non è pubblicato all'esterno)
docker exec spazio-comune-app python -c "import httpx; print(httpx.post(
  'http://inference:8080/v1/tasks/intent',
  json={'testo': 'calcetto venerdì sera alle 20', 'oggi': '2026-11-09'}).json())"

{"attivita": "calcetto", "data": "2026-11-13", "fascia": "sera", "ora": "20:00",
 "giocatori": null, "confidenza": 1.0, "backend": "rules", "generato_da_ia": false}

API del server di inferenza¶

Per altri sistemi agentici: il server MCP¶

Gli stessi strumenti (orari liberi da una frase, FAQ con fonte, calendario) sono disponibili ad agenti esterni tramite il server MCP, con la stessa regola: l'agente propone e restituisce un link, la persona prenota e paga.

Garanzie scritte nel codice¶

Ogni garanzia è verificata da test automatici (inference/tests/test_inference.py, app/tests/test_web.py).

• Non prenota e non paga. Nessun endpoint di inferenza modifica prenotazioni o pagamenti; l'assistente restituisce link a slot che il cittadino sceglie.
• Dati personali rimossi. Codice fiscale, email, telefono e IBAN vengono sostituiti ([CODICE_FISCALE], [EMAIL]…) prima di qualsiasi invio a un modello.
• Trasparenza. L'interfaccia dichiara che l'assistente è basato su IA e invita a non scrivere dati personali; ogni risposta riporta backend e generato_da_ia.
• Niente invenzioni. Le FAQ rispondono solo dai documenti ufficiali; se il modello risponde NON_PRESENTE, l'app rimanda all'ufficio.
• Degrado controllato. Se il server IA è spento o l'LLM non risponde entro il timeout, il sito funziona con il calendario classico e il motore a regole.
• Rete interna. Il server di inferenza è esposto solo all'app (expose, non ports).

Collegare un modello linguistico¶

# .env
INFERENCE_BACKEND=openai
LLM_BASE_URL=http://ollama:11434/v1
LLM_MODEL=qwen2.5:1.5b-instruct
LLM_API_KEY=ollama

docker compose --profile llm up --build -d
docker logs -f spazio-comune-ollama-pull   # attendere il download del modello

# .env
INFERENCE_BACKEND=openai
LLM_BASE_URL=https://<risorsa>.openai.azure.com/openai/v1
LLM_MODEL=<nome-deployment>
LLM_API_KEY=<chiave>

docker compose up -d --force-recreate inference

# .env
INFERENCE_BACKEND=rules

Verifica del backend attivo:

docker exec spazio-comune-app python -c "import httpx; print(httpx.get('http://inference:8080/health').json())"
# {'stato': 'ok', 'backend': 'rules', 'modello': 'rules-it-v1'}

Quadro normativo¶