Configurazione dell'ambiente

Guida per passare dall'avvio in memoria volatile a un sistema pienamente persistente.

---

1. Amazon Bedrock

Accesso ai modelli

I modelli Bedrock vanno abilitati esplicitamente, una volta per account e regione: console AWS → Bedrock → Model access → richiedi accesso ai modelli che intendi usare.

Verifica cosa hai disponibile:

aws bedrock list-foundation-models --region eu-central-1 \
  --query "modelSummaries[].modelId" --output text | tr '\t' '\n'

Credenziali

Due modalità, nel file .env:

# A) profilo della AWS CLI (consigliata in locale)
AWS_REGION=eu-central-1
AWS_PROFILE=mio-profilo

# B) chiavi esplicite
AWS_REGION=eu-central-1
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

Permessi minimi richiesti:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"],
      "Resource": "*"
    }
  ]
}

Inference profile

Molti modelli recenti non accettano chiamate on-demand dirette e richiedono un inference profile regionale. In pratica: se ottieni

ValidationException: Invocation of model ID ... with on-demand throughput isn't supported

aggiungi il prefisso della tua area al model_id in config/models.yaml (eu. per l'Europa, us. per gli Stati Uniti, apac. per l'Asia-Pacifico).

Verifica rapida

cd backend && source .venv/bin/activate
python -c "
from app.llm.factory import get_chat_model
print(get_chat_model().invoke('Rispondi solo: ok').text())
"

---

2. Supabase

Connection string

Dashboard Supabase → Project Settings → Database → Connection string → URI.

Usa il pooler in modalità session (porta 5432): il checkpointer di LangGraph apre transazioni lunghe e ha bisogno di una sessione stabile.

DATABASE_URL=postgresql://postgres.<ref>:<password>@aws-0-<region>.pooler.supabase.com:5432/postgres
SUPABASE_URL=https://<ref>.supabase.co
SUPABASE_SERVICE_KEY=<service_role key>

La service_role key ha pieni poteri sul database: resta nel backend, non deve mai comparire nel frontend né in un repository.

Creare lo schema

cd backend
python -m app.db.migrate            # applica le migrazioni mancanti
python -m app.db.migrate --status   # mostra quali sono già applicate

In alternativa, incolla il contenuto di backend/app/db/migrations/001_init.sql nel SQL Editor di Supabase.

Cosa viene creato:

• schema liagraph con threads, messages, memories, thread_summaries, runs, spans, events;
• le viste v_daily_usage, v_model_usage, v_agent_usage;
• estensioni pgcrypto e pg_trgm;
• RLS attiva su tutte le tabelle senza policy: nessun accesso dall'API REST pubblica, solo dal backend via connessione diretta.

Le tabelle dei checkpoint di LangGraph vengono create automaticamente al primo avvio del backend, nello schema public.

Verifica

curl http://localhost:8000/api/health

Deve rispondere con "database": {"enabled": true} e "checkpointer": {"persistent": true}.

---

3. Variabili d'ambiente principali

L'elenco completo è in .env.example, commentato riga per riga.

---

4. Problemi frequenti