SirRoboGarage/SAC_LSTM_Bot_garage/docs/bozza_requisiti.md

Implementazione Agente DRL Recurrent-SAC (SAC-GRU) Nativo per Robocode TankRoyale

Bot nativo basato sull'algoritmo Recurrent Soft Actor-Critic (SAC-GRU) addestrato per combattere nell'ambiente Robocode TankRoyale.

Il bot deve connettersi direttamente al server WebSocket di TankRoyale tramite un'interfaccia client API nativa, senza l'uso di middleware o socket intermediari extra. Il sistema deve garantire il rispetto del limite rigido di 30 ms per turno imposto dal simulatore, eseguendo l'inferenza e l'addestramento in modo concorrente all'interno dello stesso processo.

---

1. Architettura Multi-Thread e Concorrenza (30 ms Tick Constraint)

Per evitare il fenomeno degli "skipped turns", l'applicazione deve essere suddivisa in due thread principali coordinati nello stesso processo:

1. Thread 1: Realtime Async Event Loop (WebSocket Client)

   • Riceve i messaggi di evento dal server TankRoyale via WebSocket ad ogni tick.
   • Estragga e normalizza il vettore di stato a 17 dimensioni (S_t).
   • Esegue l'inferenza rapida dell'Actor (< 2 \text{ ms}) fornendo lo stato S_t e lo stato nascosto corrente della GRU (h_{t-1}).
   • Mappa le azioni restituite e invia immediatamente il BotIntent al server WebSocket.
   • Invia la transizione (S_t, A_t, R_t, S_{t+1}, D_t) a una coda/canale thread-safe (Thread-safe Channel).

2. Thread 2: Background Trainer Thread (SAC-GRU Engine)

   • Preleva le transizioni dal canale e le accumula in un Sequential Replay Buffer.
   • Quando il buffer contiene un numero sufficiente di esperienze, estrae mini-batch di sequenze temporali.
   • Esegue l'addestramento in background (Forward/Backward Pass dell'Actor, dei Dual Critic e dell'Alpha autotuning) sfruttando l'accelerazione hardware (GPU/CPU).
   • Aggiorna periodicamente i pesi della rete Actor usata dal Thread 1 in modo thread-safe (es. scambio atomico di puntatori o mutua esclusione leggera).

---

2. Specifiche dell'Ambiente DRL (POMDP)

2.1 Vettore di Stato (S \in \mathbb{R}^{17}, Normalizzato in [-1, 1])

• s[0]: Posizione X propria (X / \text{width})
• s[1]: Posizione Y propria (Y / \text{height})
• s[2]: Orientamento scafo ([-\pi, \pi] / \pi)
• s[3]: Velocità lineare propria ([-8, 8] / 8)
• s[4]: Orientamento cannone ([-\pi, \pi] / \pi)
• s[5]: Orientamento radar ([-\pi, \pi] / \pi)
• s[6]: Temperatura del cannone ([0, 3] / 3)
• s[7]: Energia propria ([0, 100] / 100)
• s[8]: Distanza dal muro NORD ((\text{height} - Y) / \text{height})
• s[9]: Distanza dal muro SUD (Y / \text{height})
• s[10]: Distanza dal muro EST ((\text{width} - X) / \text{width})
• s[11]: Distanza dal muro OVEST (X / \text{width})
• s[12]: Ultima distanza rilevata del nemico ([0, \text{max\_dist}] / \text{max\_dist})
• s[13]: Angolo relativo (bearing) del nemico ([-\pi, \pi] / \pi)
• s[14]: Orientamento del nemico ([-\pi, \pi] / \pi)
• s[15]: Velocità del nemico ([-8, 8] / 8)
• s[16]: Energia residua del nemico ([0, 100] / 100)

2.2 Vettore delle Azioni Continuo (A \in \mathbb{R}^4, Output [-1, 1])

• a[0]: Rotazione scafo \rightarrow Mappato su [-10^\circ, +10^\circ] per tick.
• a[1]: Traslazione \rightarrow Mappato su [-8, +8] px/tick.
• a[2]: Rotazione cannone \rightarrow Mappato su [-20^\circ, +20^\circ] per tick.
• a[3]: Potenza di sparo \rightarrow \text{ReLU}(a_3) \times 3.0 (Spara solo se > 0.1).

2.3 Reward Function

R_t = R_{\text{danno\_inflitto}} - R_{\text{danno\_subito}} + R_{\text{vittoria/sconfitta}} - R_{\text{muri}} - R_{\text{sparo\_vuoto}}

• Danno inflitto: + (4p + 2(p - 1)) con p \le 3.
• Danno subito: - (4p_{\text{nemico}} + 2(p_{\text{nemico}} - 1)).
• Muri: -5.0 per tick di impatto.
• Sparo a vuoto: -0.1 \times p.
• Vittoria/Sconfitta: +20.0 / -10.0.

---

3. Modelli Neurali e Meccanismi di Addestramento

Tutte le reti devono integrare una cella ricorsiva GRU (Gated Recurrent Unit) per gestire la parziale osservabilità dell'arena (radar in rotazione):

• Recurrent Actor Network \pi_\phi(a_t | s_{:t}, h_{t-1}):

  • Feature Extractor: Linear/Dense (17 \rightarrow 128) + Attivazione
  • Memory: GRU Layer (Input: 128, Hidden: 128)
  • Heads: Linear/Dense (128 \rightarrow 64) \rightarrow Outputs: \mu \in \mathbb{R}^4 e \log \sigma \in \mathbb{R}^4 (Clamped [-20, 2])
  • Sampling: Reparameterization Trick con squashing \tanh.

• Recurrent Dual-Critic Networks Q_{\theta_1, \theta_2}(s_{:t}, a_{:t}, h_{t-1}):

  • Fusion: Concatenazione di Stato e Azione (17 + 4 = 21)
  • Feature Extractor: Linear/Dense (21 \rightarrow 128) + Attivazione
  • Memory: GRU Layer (Input: 128, Hidden: 128)
  • Q-Head: Linear/Dense (128 \rightarrow 64) \rightarrow Output Q-Value scalare.

• Sequential Replay Buffer & Burn-in Strategy:

  • Campionamento di sequenze temporali contigue di lunghezza L = 24.
  • Burn-in (L_{\text{burn}} = 8 step): I primi 8 step vengono usati unicamente per aggiornare lo stato nascosto h della GRU, senza calcolo di loss o backpropagation.
  • Training (L_{\text{train}} = 16 step): I successivi 16 step calcolano le loss dell'Actor, dei Critic e l'autotuning del parametro di temperatura \alpha (con target H_{\text{target}} = -4.0).

---

4. Requisiti di Strutturazione del Codice

Fornisci il codice sorgente completo, modulare e pronto all'uso articolato nelle seguenti componenti:

1. Model Definitions: Classi/Strutture per Actor, Critic e Target Networks basate su GRU.
2. Sequential Replay Buffer: Struttura dati thread-safe con supporto per estrazione di sequenze e gestione Burn-in.
3. SAC-GRU Trainer Engine: Algoritmo di aggiornamento, calcolo loss, gradient clipping (1.0) e soft update (\tau = 0.005).