Quartz 4

FIRE Script Engine & API Reference

3 min read

FIRE Script Engine: Technical Guide

1. Introduzione

Il Script Engine è il modulo che trasforma FIRE da un semplice tool a una Piattaforma Estendibile. Permette agli utenti di scrivere script Python personalizzati per eseguire analisi, generare report o manipolare dati, senza dover modificare il codice sorgente del core e senza dover ricompilare l’applicazione.

Principi Chiave:

  • Isolamento: Gli script girano in thread separati (QRunnable) per non bloccare la UI.
  • Sicurezza: Gli script non accedono direttamente agli oggetti interni di Qt (MainWindow, Worker), ma interagiscono tramite una Facade sicura (ScriptContext).
  • Hot-Reload: Basta salvare un file nella cartella FIRE_Scripts e premere “Refresh” nell’Hub per vederlo.

2. Anatomia di uno Script

Ogni script è un file .py standard che deve rispettare due requisiti:

  1. Un Header YAML nei commenti iniziali (Metadati).
  2. Una funzione def run(context): come punto di ingresso.

Esempio Minimo (My_Script.py)

"""
---
title: Hello World Analyzer
author: Me
version: 1.0
type: utility
description: Stampa un messaggio nei log di FIRE.
---
"""
 
def run(context):
    ticker = context.state.current_ticker
    context.ui.log(f"Ciao! Il ticker attivo è {ticker}", "SUCCESS")

I Metadati YAML supportati

  • title (Obbligatorio): Nome leggibile dello script.
  • type (Obbligatorio): Categoria (analyzer, exporter, utility).
  • author: Nome del creatore.
  • description: Breve spiegazione che appare nell’Hub.
  • tags: Lista di tag per la ricerca (es. [risk, volatility]).

3. ScriptContext API Reference

L’oggetto context passato alla funzione run è il ponte verso le funzionalità di FIRE.

3.1. context.data (Accesso Dati)

Fornisce accesso alla Smart Data Pipeline.

  • fetch(ticker, start_date, end_date, interval="1d") -> pd.DataFrame
    • Recupera dati storici OHLCV. Gestisce automaticamente cache, download e rettifiche (Split/Div) in base ai settings globali.
    • Return: DataFrame Pandas o vuoto se fallisce.
  • get_market_cache_dir() -> str
    • Restituisce il percorso assoluto della cartella dati locale.

3.2. context.state (Stato Applicazione - Read Only)

Permette di sapere “cosa sta guardando l’utente”.

  • current_ticker (str): Il simbolo attivo (es. “AAPL”).
  • current_timeframe (str): Il timeframe attivo (es. “1d”).
  • global_start_date (str): Data inizio globale (YYYY-MM-DD).
  • global_end_date (str): Data fine globale (YYYY-MM-DD).

3.3. context.ui (Interazione Utente)

Metodi thread-safe per comunicare con l’interfaccia.

  • log(message, level="INFO")
    • Scrive nel pannello log in basso. Livelli: DEBUG, INFO, WARNING, ERROR, SUCCESS.
  • show_message(title, message)
    • Apre un popup semplice (MessageBox) all’utente.
  • show_report(title, html_content)
    • Apre una finestra dedicata (Dock/Window) renderizzando l’HTML fornito. Ideale per grafici Plotly interattivi.

3.4. context.get_setting(key, default)

  • Permette di leggere valori dalla configurazione globale di FIRE (es. chiavi API).

4. Workflow di Sviluppo Script

  1. Creazione: Creare un file .py nella cartella definita in Settings → AI Tools → User Scripts Folder (Default: Documents/FIRE_Scripts).
  2. Discovery: Aprire Tools → Script Hub e premere “Refresh”. Lo script apparirà nella lista.
  3. Debug: Usare context.ui.log() per stampare informazioni di debug nel pannello di FIRE.
  4. Distribuzione: Il file .py può essere condiviso con altri utenti; non ha dipendenze hardcoded dai percorsi locali.

5. Esempi Avanzati

Generare un Grafico Plotly

import plotly.graph_objects as go
 
def run(context):
    df = context.data.fetch(context.state.current_ticker, "2023-01-01", "2024-01-01")
    
    fig = go.Figure(data=[go.Candlestick(
        x=df.index, open=df['Open'], high=df['High'], low=df['Low'], close=df['Close']
    )])
    
    html = fig.to_html(include_plotlyjs='cdn')
    context.ui.show_report("My Custom Chart", html)

**Vuoi che crei questo file?**
Se sì, abbiamo un set completo di documentazione per il rilascio.

Graph View