# Claudio Opuscoli — Hackapizza 2.0

Sistema multi-agente per la gestione autonoma di un ristorante galattico nel Ciclo Cosmico 790.

Costruito con il framework [datapizza-ai](https://docs.datapizza.ai/), il sistema simula una **brigata di cucina** dove ogni agente ha un ruolo specializzato, tool dedicati e comunica con gli altri via message bus interno.

## Quick Start

### Prerequisiti

- Python >= 3.12
- [uv](https://docs.astral.sh/uv/) (consigliato)

### Setup

```bash
git clone <repo-url>
cd ClaudioOpuscoli
cp .env.example .env
# Compila il .env con le chiavi fornite dall'organizzazione
uv sync
```

### Configurazione `.env`

```
TEAM_ID=14
HACKAPIZZA_API_KEY=<chiave fornita>
REGOLO_API_KEY=<chiave fornita>
```

### Esecuzione diretta runtime

```bash
uv run hackapizza
```

Questa modalita avvia solo il runtime agenti. E' utile per debug tecnico, ma per l'operativita quotidiana e consigliata la modalita monitor-first sotto.

### Nuovo modo di avvio consigliato (monitor-first)

Per mantenere **una sola connessione SSE upstream** e controllare gli agenti da UI:

1. avvia il monitor proxy:

```bash
uv run python src/monitor/sse-proxy.py
```

2. apri `http://127.0.0.1:8765`
3. usa `Avvia runtime` / `Ferma runtime` / `Riavvia runtime`

In questa modalita:

- il proxy mantiene la connessione SSE al server;
- il runtime consuma SSE locale (`/events/{TEAM_ID}`);
- puoi fermare/riavviare gli agenti senza perdere monitor e log.
- la connessione SSE upstream resta una sola (gestita dal proxy).

### Regola pratica

- Se usi il monitor, non lanciare `uv run hackapizza` in parallelo.
- Se lanci `uv run hackapizza` da solo, assicurati che `SSE_URL` punti comunque al proxy locale se vuoi mantenere la strategia a connessione unica.

## Architettura

Il sistema si basa su 6 agenti LLM + 2 componenti deterministici, orchestrati da un event loop asyncio:

```
SSE Server ──► SSE Middleware ──► Message Bus ──► Agenti
                    │                               │
                    ▼                               ▼
               Brigata (det.)                  MCP Tools + DB
```

- **SSE Middleware** — riceve eventi dal server, li smista agli agenti
- **Message Bus** — comunicazione interna peer-to-peer (asyncio.Queue)
- **Brigata** — middleware deterministico per il serving (no LLM)
- **SQLite DB** — memoria storica oltre il limite di 2 turni del server

Per i dettagli su ogni agente vedi [AGENTS.md](AGENTS.md).

## Struttura progetto

```
src/hackapizza/
├── config.py              # Configurazione e variabili d'ambiente
├── main.py                # Entrypoint asyncio
├── models/                # Dataclass condivisi
│   ├── messages.py        # Messaggi interni tra agenti
│   └── game.py            # Recipe, MenuItem, MarketEntry, ecc.
├── infra/                 # Infrastruttura
│   ├── sse.py             # SSE listener + event router
│   ├── brigata.py         # Middleware serving deterministico
│   ├── api_client.py      # Client HTTP (GET endpoints)
│   ├── message_bus.py     # Bus comunicazione inter-agente
├── db/                    # Database SQLite
│   ├── schema.py          # Schema 6 tabelle
│   └── repository.py      # CRUD async
└── agents/                # Brigata di cucina
    ├── base.py            # BaseAgent (wrapper datapizza Agent)
    ├── prompts.py         # System prompt per ruolo
    ├── patron.py          # Orchestratore
    ├── chef.py            # Menu planning
    ├── magazzini.py       # Aste e mercato
    ├── maitre.py          # Servizio clienti
    ├── pr.py              # Comunicazioni esterne
    └── evaluator.py       # Analisi post-turno
```

## Stack

| Componente | Tecnologia |
|---|---|
| Framework agenti | datapizza-ai |
| LLM inference | Regolo.ai (gpt-oss-120b, gpt-oss-20b) |
| Database | SQLite (aiosqlite) |
| Async runtime | Python asyncio |
| HTTP/SSE | aiohttp |
| MCP | POST /mcp su server Hackapizza |

## Flusso di un turno

1. **game_started** — Patron legge il riepilogo del turno precedente
2. **speaking** — Chef pianifica il menu, PR negozia con altri ristoranti
3. **closed_bid** — Magazzini invia offerte all'asta cieca
4. **waiting** — Magazzini verifica inventario, Chef finalizza il menu, Patron apre il ristorante
5. **serving** — Maitre interpreta ordini e avvia preparazioni, Brigata serve i piatti pronti
6. **stopped** — Evaluator analizza le performance e scrive raccomandazioni

## Team

**Claudio Opuscoli** — Hackapizza 2.0, 2025