Architettura in locale

Lo stack è orchestrato da docker-compose.yml nella root del repo. Quando dai make up vengono avviati 7 container (8 col profilo Ollama):

• ckan-mcp, istat-mcp, osm-mcp — i tre server MCP in modalità streamable-http.
• opendata-backend — FastAPI sulla porta 18000 (host) → 8000 (container).
• opendata-ai-ui — nginx che serve l'export statico di Next.js sulla porta 13000.
• postgres (schema opendata) e redis — cache + rate limit.
• opendata-ai-ollama — opzionale; presente solo nel profilo cpu/gpu. Con up-claude non viene avviato.

Prerequisiti

1. Clone della repo

La repo include un sottomodulo (vendor/agent-stack) che contiene lo schema Postgres come fonte di verità. Non è obbligatorio per girare in locale (il backend ha uno stub di migration), ma è consigliato:

# Clone con sottomoduli in un colpo solo
git clone --recurse-submodules https://github.com/agent-engineering-studio/opendata-ai.git
cd opendata-ai

# Oppure, se hai già clonato senza sottomoduli:
git submodule update --init --depth=1

2. File di configurazione

Copia il template .env.local.example in .env.local e personalizzalo. I valori di default sono già funzionanti per uno sviluppo da zero — bastano un paio di override.

cp .env.local.example .env.local
$EDITOR .env.local

Variabili più importanti

3. Avvio dello stack

Opzione A — Claude (consigliata per iniziare)

Non avvia il container Ollama. Più veloce, meno risorse, e gli esempi della landing rispondono subito.

# in .env.local
LLM_PROVIDER=claude
ANTHROPIC_API_KEY=sk-ant-...

make up-claude
make logs   # tail dei log di tutti i servizi

Opzione B — Ollama (locale, no chiavi cloud)

Avvia anche il container Ollama (immagine pre-baked qwen2.5:32k, ~7 GB). Profili:

# CPU-only (default su macOS / Windows / Linux senza GPU NVIDIA)
make up

# GPU (Linux + NVIDIA, supporta CUDA)
make up-gpu

# Su macOS con Apple Silicon, Ollama gira meglio sull'host (Metal):
ollama serve &              # in un altro terminale
make up-host-ollama         # collega lo stack all'host Ollama

Verifica

make ps                                    # tutti i servizi healthy
curl -s http://localhost:18000/health      # {"status":"ok"}

# UI: http://localhost:13000
# Backend OpenAPI: http://localhost:18000/docs
# A2A AgentCard: http://localhost:18000/.well-known/agent-card.json

4. Sanity-check dei server MCP

Una volta su, puoi verificare che ogni MCP risponda:

# Lista tool di ckan-mcp (porta host 18080)
curl -sX POST http://localhost:18080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list"}' | jq

# Round-trip stdio diretto (senza HTTP) — utile per debug
make mcp-stdio-ckan
make mcp-stdio-istat
make mcp-stdio-osm

5. Sviluppo dei singoli pacchetti

Per iterare sul codice Python senza ricostruire l'immagine Docker, installa i pacchetti in modalità editable nella stessa venv. Importante: opendata-backend richiede --pre perché agent-framework è pubblicato come pre-release.

# Crea una venv (il progetto si aspetta /tmp/oda-venv nei test, ma usa quello che preferisci)
python -m venv /tmp/oda-venv
source /tmp/oda-venv/bin/activate

# Pacchetti senza --pre
pip install -e ./opendata_core[dev]
pip install -e ./ckan-mcp-server[dev]
pip install -e ./istat-mcp-server[dev]
pip install -e ./osm-mcp[dev]

# Backend con --pre (agent-framework è pre-release)
pip install --pre -e ./opendata-backend[dev,azure,claude]

Eseguire il backend fuori da Docker

cd opendata-backend

# Postgres + Redis devono comunque essere su (li offre lo stack docker)
make ps

DATABASE_URL=postgresql+asyncpg://opendata:opendata@localhost:15432/opendata \
REDIS_URL=redis://localhost:16379/1 \
AUTH_ENABLED=false \
ANTHROPIC_API_KEY=sk-ant-... \
CKAN_MCP_URL=http://localhost:18080/mcp \
ISTAT_MCP_URL=http://localhost:18081/mcp \
OSM_MCP_URL=http://localhost:18085/mcp \
opendata-backend-api  # http://localhost:8000

Eseguire la UI fuori da Docker

cd opendata-ai-ui
npm install

# punta al backend su porta host
echo 'NEXT_PUBLIC_API_URL=http://localhost:18000' > .env.local

npm run dev    # http://localhost:3000

Tieni presente la regola R6: output: 'export' è abilitato in next.config.ts, quindi non puoi aggiungere route handler in app/api/*.

6. Lint e test

# Tutti i pacchetti Python
make lint
make test

# UI
cd opendata-ai-ui
npm run typecheck
npm run lint
npm run build   # equivalente a "next build" con static export

7. Stop e reset

make down              # ferma tutti i container (mantiene i volumi)
docker volume ls       # vedi i volumi del progetto (postgres_data, redis_data, ...)
docker compose --env-file .env.local down -v   # reset COMPLETO (perdi tutti i dati)

Layout del repo (alto livello)

opendata-ai/
├── opendata_core/          # client asincroni condivisi (CKAN, SDMX, OSM)
├── ckan-mcp-server/        # FastMCP wrapper CKAN (11 tool)
├── istat-mcp-server/       # FastMCP wrapper SDMX 2.1 (ISTAT/Eurostat/OECD)
├── osm-mcp/                # FastMCP wrapper OSM (geocoding, POI, routing, render)
├── opendata-backend/       # FastAPI + orchestrator + A2A + classify
├── opendata-ai-ui/         # Next.js 15 static export (questa interfaccia)
├── vendor/agent-stack/     # sottomodulo: schema Postgres opendata.*
├── infra/                  # config Ollama, Caddy (legacy single-tenant)
├── docker-compose.yml      # stack completo
├── Makefile                # tutti i comandi quotidiani
├── .env.local.example      # template configurazione dev
└── README.md

Risorse di approfondimento

• Repository GitHub: https://github.com/agent-engineering-studio/opendata-ai — codice sorgente, issue tracker, release.
• README principale: https://github.com/agent-engineering-studio/opendata-ai#readme — panoramica dell'architettura, tabella delle fonti dati, elenco endpoint.
• CLAUDE.md: opendata-ai/CLAUDE.md — invarianti architetturali, gotcha, regole operative (R1–R13).
• docker-compose.yml: definizione di tutti i servizi — porte host, dipendenze e profili.
• Issue tracker: https://github.com/agent-engineering-studio/opendata-ai/issues — bug report e richieste feature.

Prossimi passi