Quartz 4

Strategy API - Guida per Sviluppatori (v2)

4 min read

FIRE DD-STRATEGY-API.md

Versione: 2.0 Data: 2025-11-26 Scopo: Fornire una guida completa per gli sviluppatori sulla creazione di strategie di trading personalizzate, includendo l’API di BaseStrategy per la logica, la visualizzazione custom e i parametri dinamici. Documento Principale: ARCHITECTURE-OVERVIEW.md

1. Filosofia: Scrivi una Volta, Esegui Ovunque

L’API per le strategie di FIRE è progettata secondo il principio “Scrivi una Volta, Esegui Ovunque”. La logica di una strategia viene implementata una sola volta ereditando dalla classe BaseStrategy, e può essere poi utilizzata senza modifiche sia nel Backtester (per l’analisi storica) sia nello Signal Scanner (per la ricerca di opportunità in tempo reale).

L’obiettivo è fornire un’API che sia allo stesso tempo semplice per iniziare, ma potente abbastanza da permettere l’implementazione di logiche complesse e la personalizzazione completa dell’aspetto visuale.

2. La Struttura di una Strategia: init() e next()

Ogni strategia in FIRE è una classe Python che eredita da BaseStrategy e deve implementare due metodi fondamentali: init() e next().

from fire.strategies.base_strategy import BaseStrategy
 
class MiaStrategiaSemplice(BaseStrategy):
    
    def init(self):
        # Chiamato una sola volta, all'inizio.
        # È il posto giusto per calcolare indicatori.
        self.sma_20 = self.data['Close'].rolling(window=20).mean()
 
    def next(self):
        # Chiamato per ogni barra (giorno/ora) nella serie storica. 
        # Qui risiede la logica di trading.
        if self.close > self.sma_20.iloc[self.i]:
            if not self.position:
                self.buy()
  • init() (Inizializzazione): Viene eseguito una sola volta prima dell’inizio del backtest. Usalo per pre-calcolare indicatori o qualsiasi altro dato che non necessita di essere ricalcolato ad ogni barra. Questo ottimizza drasticamente le performance.
  • next() (Logica per Barra): È il cuore della strategia. Viene eseguito in un ciclo, una volta per ogni candela (barra) nella serie storica, dalla più vecchia alla più recente. Qui si implementano le condizioni di ingresso e di uscita.

3. L’API di Base: Interagire con il Mercato

All’interno dei metodi init() e next(), hai accesso a una serie di proprietà e metodi forniti da BaseStrategy.

Accesso ai Dati della Barra Corrente

  • self.open, self.high, self.low, self.close, self.volume
  • self.i: L’indice della barra corrente.

Gestione delle Posizioni

  • self.position (proprietà): Restituisce True se una posizione è aperta.
  • self.buy(comment: str = None): Apre una posizione long.
  • self.sell(comment: str = None): Chiude una posizione aperta.
  • self.trade_bars (proprietà): Restituisce il numero di barre da quando la posizione è stata aperta.

Accesso agli Indicatori (self.indicators)

FIRE include una libreria di indicatori pre-costruiti, accessibili tramite self.indicators.

def init(self):
    self.rsi = self.indicators.RSI(period=14)
 
def next(self):
    current_rsi = self.rsi.iloc[self.i]
    if current_rsi < 30:
        self.buy()

4. Aggiungere Visualizzazioni Custom (Stile Pine Script) [NUOVO]

Per replicare l’aspetto visuale di TradingView, BaseStrategy fornisce un’API dichiarativa. La tua strategia può richiedere al sistema di disegnare linee, forme e colori personalizzati.

Per la guida completa e dettagliata, consulta FIRE DD-STRATEGY-PLOTTING-API.

self.plot() - Disegnare Linee e Indicatori

Usato in init() per disegnare serie di dati come Medie Mobili.

def init(self):
    self.my_ema = self.data['Close'].ewm(span=20, adjust=False).mean()
    
    # Richiede al grafico di disegnare l'EMA
    self.plot(self.my_ema, name="EMA(20)", color="cyan", width=2)

self.plot_shape() e self.set_bar_color() - Evidenziare Segnali

Usati in next() per marcare eventi specifici.

def next(self):
    if self.close > self.my_ema.iloc[self.i]:
        # Disegna un cerchio blu sotto la barra
        self.plot_shape(style="circle", color="blue", location="below")
        
        # Colora la candela di giallo
        self.set_bar_color("yellow")

5. Rendere la Strategia Configurabile [NUOVO]

Invece di usare valori hardcoded (es. period=20), puoi rendere la tua strategia configurabile dall’utente attraverso la finestra di dialogo delle impostazioni.

Per la guida completa e dettagliata, consulta FIRE DD-STRATEGY-PARAMETERS.

self.add_parameter() - Definire i Parametri

Usa questo metodo nel costruttore (__init__) per dichiarare i parametri. FIRE costruirà automaticamente la UI.

class MiaStrategiaConfigurabile(BaseStrategy):
    def __init__(self):
        super().__init__()
        # Dichiara un campo numerico, uno booleano e un selettore colore
        self.add_parameter("ema_period", 20, type="int", min=1, label="Periodo EMA")
        self.add_parameter("show_ema", True, type="bool", label="Mostra EMA")
        self.add_parameter("signal_color", "yellow", type="color", label="Colore Segnale")

self.params - Usare i Parametri

I valori correnti (modificati dall’utente) sono sempre disponibili nel dizionario self.params.

def init(self):
    ema_period = self.params["ema_period"]
    show_ema = self.params["show_ema"]
 
    self.my_ema = self.data['Close'].ewm(span=ema_period, adjust=False).mean()
    
    if show_ema:
        self.plot(self.my_ema, name=f"EMA({ema_period})")

6. API Avanzata: Strategie Predittive (Ibride)

Puoi creare strategie che utilizzano previsioni generate da modelli AI.

6.1. Richiedere Dati di Arricchimento

Dichiara i provider di dati AI di cui hai bisogno.

class MiaStrategiaPredittiva(BaseStrategy):
    data_enrichment_providers = ['timesfm_forecast']
    # ...

Per dettagli, vedi FIRE DD-DATA-ENRICHMENT 1.0.

6.2. Accesso ai Dati di Forecast

Accedi ai dati predittivi tramite semplici proprietà:

  • self.forecast: Valore puntuale della previsione.
  • self.forecast_lower_band, self.forecast_upper_band: Intervalli di confidenza.

Esempio di Strategia Ibrida

def next(self):
    # Condizione ibrida: trend tecnico + conferma predittiva
    if self.close > self.sma.iloc[self.i] and self.forecast > self.close:
        self.buy()

7. Best Practice

  • Ottimizza in init(): Esegui i calcoli pesanti una sola volta in init().
  • Gestisci i NaN: Controlla i valori NaN all’inizio delle serie di indicatori per evitare errori.
  • Usa i Commenti: Fornisci commenti a buy() e sell() per sfruttare il tracciamento dei motivi di trade. Vedi FIRE DD-TRADE-REASON-TRACKING.

Con questo, il nostro piano di documentazione è completo. Abbiamo allineato la conoscenza del team con le nuove, potenti funzionalità del framework.

Graph View