Aggiunto file di mappatura

AGENT.md

@@ -0,0 +1,41 @@
+# Agenda tecnica - Trading repo
+
+## Struttura e moduli
+- `signals_daily_kNN_prod_v.2.py`: generatore segnali EOD -> ordini t+1 (Equal_Weight/Risk_Parity); kNN pattern long-only, ranking top-N, sizing equal weight / risk parity con cap; fetch prezzi open via API Euronext; scrive audit `trades_audit_log.csv`, snapshot Excel datato e `open_trades/*.csv`, copia su Dropbox locale.
+- `Trading Pattern Recon w Hurst v.3.1.6.py`: workflow di ricerca/backtest (Hurst + pattern, forward walk, costruzione portafogli, metriche/grafici). Versioni precedenti in `archivio/` (3.1.1-3.1.5) + vecchio `signals_daily_kNN_prod.py` come riferimento storico.
+- `equity_from_log.py`: ricostruisce rendimenti/equity per strategia a partire da `trades_audit_log.csv` usando rendimenti DB; produce CSV debug ed equity + PNG drawdown.
+- `check_universe_prices.py`: validazione/fetch prezzi Euronext per universo, con retry; salva Excel datato.
+- `shared_utils.py`: helper comuni (config loader, connessione DB via `connection.txt`, z-score, libreria pattern kNN, Hurst). Config JSON in `config/pattern_knn_config.json`.
+
+## Dipendenze e I/O esterni
+- Librerie: pandas, numpy, sqlalchemy+pyodbc, matplotlib, openpyxl (per Excel), urllib/ssl per API HTTP.
+- DB SQL Server via stored procedure (`opt_RendimentoGiornaliero1_ALL` di default) e credenziali in `connection.txt`.
+- API prezzi Euronext `fin.scorer.app` (open/prevClose) per ordini e checker; rete richiesta.
+- File system: numerosi artefatti CSV/XLSX/PNG (trades, segnali, equity, heatmap) e path Dropbox hardcoded `C:\Users\Admin\Dropbox\...`.
+
+## Flussi principali
+- **Signals daily**: carica universo Excel -> ritorni DB per tutti gli ISIN -> Hurst map (251-252d) -> segnali kNN (WP=60, HA=10, k=25, theta per-ISIN da Hurst/100) -> ranking buy unico -> target Top-N (MAX_OPEN=15) -> per ogni strategia confronto con posizioni aperte (`open_trades/*.csv`), risk-exit SL/TP/Trailing/Time/Weak -> costruisce ordini OPEN/CLOSE t+1 con sizing e fetch prezzi open (cache unica) -> aggiorna audit log e snapshot Excel.
+- **Backtest/ricerca**: script Hurst+kNN su intero storico, walk-forward long-only, selezione portafogli dinamica, metriche finali e grafici (equity, heatmap, composizioni) salvati sotto root/`plots_by_topN`.
+- **Equity da log**: legge audit, scarica rendimenti DB, normalizza (gestisce percentuali/log-return), calcola rendimento giornaliero medio ponderato per strategia e salva CSV/PNG.
+- **Price checker**: controlla universo e tenta 3 fetch sequenziali per ISIN-mercato, loggando esito in Excel datato.
+
+## Artefatti e dati
+- Input: `Universo per Trading System.xlsx`, `connection.txt` (credenziali DB), file signals/grafici storici, `open_trades/*.csv` correnti, `trades_audit_log.csv` cumulativo.
+- Output: file datati `*_signals.xlsx`, `daily_returns_by_strategy.csv`, `equity_by_strategy.csv/png`, heatmap/composition/equity PNG, report `trades_report.xlsx`, summary `final_metrics*.xlsx`.
+
+## Punti critici / fragilita
+- Config duplicata/override nei due script principali: valori richiesti via `require_value` subito rimpiazzati da `.get` con default diversi; rischio incoerenze tra run.
+- Hardcode percorsi e naming (Dropbox, file universi, stored proc) senza parametri CLI -> difficile rilocare/automatizzare ed errori silenziosi se path mancano.
+- Fetch DB e API sequenziali per ISIN (nessun batching/parallelismo), con print blocking e retry lineari: potenziale collo di bottiglia e timeout su universi ampi.
+- Gestione errori best-effort: `_db_fetch_returns` ignora asset mancanti e continua, rischiando gap nascosti nelle serie; `_fetch_open_prices_once` usa `_safe_to_float` senza log dettagliato.
+- Audit/logging: `append_audit_rows` concatena senza dedupe/concorrenza; nessun controllo su idempotenza o coerenza tra `open_trades` e audit.
+- Sizing RP: guarda inv-vol 60d senza controllo di correlazione/covarianza; cap applicato prima della rinormalizzazione puo lasciare cash residuo non tracciato.
+- Risk-exit: calcolo PnL/Drawdown dalla serie daily con possibili `NaN`; nessun controllo timezone/duplicati; `WeakDays` usato ma poco gestito.
+- Dipendenze esterne: blocchi se `connection.txt` o `config` mancanti; API HTTP senza fallback/caching persistente.
+- Qualita codice: duplicazioni (config, utility importate due volte), nomi con spazi, script monolitici senza test; archivio versioni ridondanti.
+
+## Collo di bottiglia e aree di miglioramento
+- I/O seriale verso DB e API e il punto piu lento e fragile (rete). Cache e parallelizzazione mancano.
+- Persistenza su file Excel/CSV come single source of truth rende difficile la coerenza e l'automazione; non c'e validazione schema/typen.
+- Gestione configurazione e percorsi centralizzata ma hardcoded e duplicata; assente modello a pacchetto/moduli riusabili.
+- Monitoraggio/error handling minimale: molti `print`, nessun livello di log o alerting per run fallite.