🚀 SCROTO Trading OS — Quantitative Intelligence & Autonomous Execution Portal

Benvenuti nella documentazione ufficiale di SCROTO (Stock Collapse Reinforcement Optimization Trading Oracle).

Il sistema è un'infrastruttura completa di trading algoritmico, ricerca quantitativa, monitoraggio dei rischi e intelligenza artificiale autonoma, interamente ospitata ed eseguita in locale su hardware dedicato Raspberry Pi 5 (16 GB).

🌐 Mappa dei Servizi Web & Dashboard Live

Tutti i servizi sono accessibili in HTTPS tramite il dominio del server: https://scrotopi.duckdns.org.

🏗️ I 6 Pilastri Architetturali del Sistema

                 ┌───────────────────────────────────────────────┐
                 │       MERCATI (Binance WS/REST & Yahoo)       │
                 └───────────────────────┬───────────────────────┘
                                         ▼
                 ┌───────────────────────────────────────────────┐
                 │    Ingestione & Feature Builder (28-dim)      │
                 │ (23 Indicatori, Frattali, LPPL, EWS, Regime)  │
                 └───────────────────────┬───────────────────────┘
                                         ▼
                 ┌───────────────────────────────────────────────┐
                 │     Collapse Optimizer (Entropic DP ψ=ψ(ψ))   │
                 └───────────────────────┬───────────────────────┘
                                         ▼
       ┌─────────────────────────────────┴─────────────────────────────────┐
       ▼                                                                   ▼
┌───────────────────────────────┐                       ┌───────────────────────────────────┐
│     MSPM RL Agents            │                       │    Stock Analyzer v4 (SA)         │
│  • DQN (EAM): Asset Selection │ ◄── [Score 0-100] ─── │  • 9 Stadi di Analisi Paralleli   │
│  • PPO (SAM): Portfolio Alloc │                       │  • FinBERT Sentiment Neurale      │
└──────────────┬────────────────┘                       │  • Macro Radar a 7 Segnali        │
               │                                        └───────────────────────────────────┘
               ▼
┌───────────────────────────────┐                       ┌───────────────────────────────────┐
│     Portfolio Manager         │                       │    LLM Agent & Mecha-Scroto Bot   │
│  • LocalSimulator (Paper)     │ ◄─── Tool-Calling ─── │  • Qwen2.5-1.5B Heretic quant Q5  │
│  • Anti-churn & Risk limits   │                       │  • Telegram Bot + RAG & CoVE      │
└──────────────┬────────────────┘                       └───────────────────────────────────┘
               ▼
┌───────────────────────────────┐
│  Persistenza SQLite (WAL)     │
│   + Caching Redis (scroto:*)  │
└───────────────────────────────┘

1. Ensemble Predictor Multivariato: combina 4 modelli complementari (LSTM, Transformer, XGBoost, ARIMA) guidati da un meta-learner con pesatura dinamica per cogliere sia i trend lineari sia le relazioni non lineari.
2. Stock Analyzer v4 & FinBERT: pipeline quantitativa a 9 stadi paralleli che elabora indicatori tecnici multi-timeframe, modelli predittivi ML, sentiment neurale su notizie finanziarie con FinBERT e produce il Composite Score (0-100) e trade plan con Stop Loss (ATR) e Take Profit.
3. Reinforcement Learning Autonomo (SA-RL): agente PPO (Strategic Agent Module - SAM) continuo a 15 dimensioni che alloca dinamicamente i pesi del portafoglio (azioni e liquidità USD), massimizzando lo Sharpe Ratio e penalizzando l'overtrading tramite filtro anti-churn.
4. Fisica dei Mercati Finanziari & Teoria del Caos: rilevamento delle bolle speculative e singolarità di crash tramite LPPL (Didier Sornette Log-Periodic Power Law), rugosità della serie temporale con Higuchi Fractal Dimension (HFD), esponente di persistenza di Hurst ($H$), esponente di Lyapunov ed Early Warning Signals (EWS).
5. Deep Retrain Orchestrator & A/B Shadow Testing: processo demone continuo che riaddestra periodicamente le reti neurali e le testa "in ombra" per 24 ore (288 cicli da 5 minuti). Il nuovo modello viene promosso in produzione solo se supera il modello attivo in reward cumulativo e mantiene uno Sharpe $ge 0.95$.
6. TurboQuant LLM & Mecha-Scroto Bot: interfaccia vocale e testuale su Telegram basata sul modello locale Qwen2.5-1.5B-Instruct-Heretic (quantizzazione Q5_K_M su llama-server con cache KV q8_0). L'LLM non inventa segnali: interroga tramite tool-calling deterministico i moduli quantitativi e restituisce insight sintetici con verifica CoVE (Chain-of-Verification) e RAG.

⚡ Operatività Rapida da Terminale

Tutti i processi del sistema sono coordinati da script unificati con gestione automatica di PID, log in logs/, watchdog anti-crash e controllo della memoria.

Riavvio Completo (Master Restart)

Dopo un riavvio della macchina o manutenzione, eseguire:

./RIZZA_TUTTO.sh

Comandi dell'Orchestratore Unificato

# Avvia tutti i demoni in background (nohup)
./start_scroto_system.sh

# Verifica lo stato di tutti i processi, porte e memoria
./start_scroto_system.sh --status

# Ferma tutti i processi gestiti e libera le porte
./start_scroto_system.sh --stop

# Riavvio rapido (Stop + Start)
./start_scroto_system.sh --restart

# Avvio minimale (Solo Dashboard, Bot Telegram e Pipeline SA-RL)
./start_scroto_system.sh --minimal

Servizio di Sistema (Systemd)

Il sistema è registrato come servizio di sistema per l'avvio automatico al boot:

sudo systemctl status scroto.service
sudo systemctl restart scroto.service

💻 Hardware Target & Ottimizzazioni Raspberry Pi 5

L'intera architettura è tarata specificamente per massimizzare il rendimento del processore Broadcom BCM2712 (Cortex-A76 quad-core @ 2.4 GHz) e dei 16 GB di RAM: - Istruzioni ARM NEON & ARM_FMA: compilazione ad hoc di llama.cpp per massimizzare i token/sec senza GPU dedicata. - KV-Cache compressa: cache dei token di contesto allocata a 8-bit (q8_0) con contesto a 8192 token, mantenendo l'ingombro dell'LLM sotto i 4 GB di RAM. - SQLite in modalità WAL: PRAGMA journal_mode=WAL e busy_timeout=15000 per garantire letture concorrenti veloci dalla dashboard e scritture simultanee dai demoni senza lock del database. - Watchdog di Emergenza Memoria: monitoraggio costante ogni 120s; se la memoria disponibile scende sotto 500 MB, il watchdog interviene per preservare la stabilità del sistema operativo.

📚 Indice della Documentazione Wiki

Consulta le guide approfondite nelle pagine dedicate della Wiki:

1. 📐 Architettura & Pipeline Dati — Ingestione dati, Feature Builder a 28 dimensioni, modelli Ensemble, fisica statistica dei mercati e Reinforcement Learning.
2. 📊 Servizi Web & Dashboard — Descrizione approfondita dei 10 tab della Dashboard Ratatouille, Stock Analyzer e configurazione Nginx.
3. 🤖 Bot Telegram Mecha-Scroto & Comandi — Manuale comandi completi del bot Telegram: analisi, screening, macro radar, RAG e report automatici.
4. 🧬 Addestramento & Pipeline SA-RL — Funzionamento del loop continuo SA-RL, Shadow Testing A/B a 24 ore, criteri di promozione e salvataggio modelli.
5. ⚙️ Operatività, Manutenzione & Troubleshooting — Gestione demoni, file di log, configurazione systemd, sincronizzazione laptop ThinkPad con Fossil e risoluzione problemi comuni.
6. 📖 Glossario Metriche & Domande Frequenti (FAQ) — Spiegazione dettagliata di Composite Score, Sharpe Ratio, LPPL, Hurst, drawdown e risposte alle domande più frequenti.

Ultimo aggiornamento della documentazione: 25 Ottobre 2026 — Repository SCROTO