Sommario

1. Sviluppo Estensioni FIRE

Le estensioni sono moduli Python isolati progettati per iniettare algoritmi proprietari, analisi statistiche e visualizzazioni custom nel workflow operativo di FIRE.

Architettura e Scope

Il sistema permette l’utilizzo integrale dell’ecosistema scientifico Python (Pandas, Numpy, Scipy, Scikit-learn). Ogni estensione opera in un thread separato gestito dal ScriptRunnerWorker per garantire la reattività della UI host.

ScriptContext: Facciata API sicura (Facade Pattern) che funge da unico punto di interfaccia tra la logica dell’estensione e il kernel di FIRE.

Componenti del Context:

context.data: Accesso alla Smart Data Pipeline (cache locale e rettifiche).
context.ui: Metodi di orchestrazione per dashboard e reportistica.
context.state: Accesso in sola lettura allo stato runtime (ticker attivo, timeframe).
context.theme: Accessore agli atomi del Design System.

Integrazione Tecnica

L’integrazione avviene tramite l’iniezione dell’oggetto context nella funzione di ingresso dello script. FIRE automatizza il recupero dei dati e il rendering estetico, permettendo allo sviluppatore di concentrarsi esclusivamente sulla logica di calcolo.

def run(context):
    # Logica di calcolo e analisi
    # Generazione output tramite Dashboard API

Scopo Operativo

Eliminare la gestione del boilerplate tecnico (gestione I/O, parsing dati, CSS/Layout) per accelerare il deployment di nuovi strumenti quantitativi. Il sistema garantisce che ogni analisi sia nativamente coerente con il Design System di FIRE e rispettosa della sovranità dei dati.

💡 Nota operativa: Le estensioni vengono caricate dinamicamente dalla directory /extensions definita nelle impostazioni.

2. I Vincoli Obbligatori

Un file Python è classificato come estensione FIRE solo se soddisfa i requisiti strutturali di identificazione e orchestrazione. La mancanza di uno di questi elementi impedisce il caricamento dello script nell’Hub delle Estensioni.

2.1. Frontmatter YAML (Sintassi e Metadati)

Ogni script DEVE iniziare con un blocco di metadati. ⚠️ Regola di Sintassi: Poiché il file è uno script Python, il blocco YAML deve essere racchiuso tra tripli apici doppi (""") per essere interpretato come una docstring e non causare errori di sintassi (SyntaxError).

Campi Chiave:

id: Identificativo univoco. Si consiglia un formato numerico progressivo (es. 0001, 0015) per garantire un ordinamento cronologico o logico nella lista.
file_name: (Opzionale) Il nome fisico del file. Utile per verifiche di integrità o logiche di export.
type: Categoria dello script.
- Consigliati: fetcher (Download), analyzer (Calcolo), exporter (Output), utility.
- Custom: È possibile usare qualsiasi stringa (es. experimental); il sistema la gestirà dinamicamente.

Esempio Corretto:

"""
---
id: 0001
title: Volatility Analyzer
version: 1.0
file_name: statistical_vol_analyzer.py
type: analyzer
description: Calcola SL statistici basati su drawdown intraday.
tags: [risk, statistics]
---
"""

2.2 Entry Point: `run(context)`

L’esecuzione dell’estensione è vincolata alla presenza di una funzione denominata run che accetta un unico argomento: context.

Meccanica:

Il ScriptRunnerWorker importa lo script dinamicamente.
Viene istanziato un oggetto ScriptContext (Facade).
La funzione run(context) viene chiamata, iniettando l’oggetto context come interfaccia operativa.

⚠️ Errore critico: Definire codice operativo al di fuori della funzione run (es. logica nel corpo principale del file) causa l’esecuzione immediata durante la fase di scansione, provocando rallentamenti o crash della UI.

Esempio: Estensione Minima Valida

---
id: minimalist_test
title: Script di Test
version: 1.0
type: utility
description: Verifica l'integrità del collegamento SDK.
---
 
def run(context):
    # Unico punto di ingresso per la logica
    context.ui.log("Integrazione validata con successo", "SUCCESS")

Struttura dei File

Estensione: .py
Posizione: Directory configurata in Settings > AI Tools > Scripts Path.
Nomenclatura: Snake_case consigliato per i nomi dei file.

💡 Nota operativa: Utilizzare context.ui.show_message per validare rapidamente se l’entry point viene raggiunto correttamente durante la fase di debug iniziale.

3. Le Regole di “Buona Cittadinanza”

L’adozione delle pratiche di “buona cittadinanza” garantisce che l’estensione sia coerente con il Design System di FIRE, manutenibile nel tempo e integrata nativamente nelle funzionalità di sistema (come il cambio tema).

3.1. Accesso ai Dati (Data Sovereignty)

L’estensione deve interagire con i dati di mercato esclusivamente tramite il DataManager interno.

Cosa: Utilizzo di context.data.fetch().
Come: df = context.data.fetch(ticker, start_date, end_date, timeframe).
Perché serve: Garantisce l’uso della cache locale, il rispetto delle rettifiche prezzi (Split/Dividendi) impostate dall’utente e la normalizzazione dei formati. Evita l’overhead di librerie esterne (es. yfinance) e il rischio di conflitti di versione.

3.2. UI Semantica (Dashboard API)

La costruzione dell’interfaccia deve avvenire tramite componenti astratti forniti dall’SDK, evitando la scrittura di HTML/CSS manuale.

Cosa: Astrazione del layout tramite ScriptDashboard.
Come:
1. dash = context.ui.create_dashboard("Titolo Analisi")
2. dash.add_metric(label, value, variant="success")
3. context.ui.show_dashboard(dash)
Perché serve: Abilita l’Adaptive Mode (cambio Dark/Light automatico) e assicura che card, font e spaziature siano identiche al “Gold Standard” di FIRE.

Varianti Semantiche:

info: Accento Brand (Arancione).
success: Trading Bullish/Sicurezza (Verde).
warning: Cautela (Giallo/Arancio).
danger: Rischio Critico (Rosso).

3.3. Smart Style per Grafici Plotly

I grafici generati esternamente devono essere processati dal motore estetico di FIRE.

Cosa: Metodo apply_fire_style.
Come: fig = context.ui.apply_fire_style(fig, is_report=True).
Perché serve: Implementa lo Smart Contrast (regola il colore di font e griglie per la leggibilità su sfondo chiaro/scuro), inserisce la firma del brand e attiva gli script di resize responsivo.

3.4. Gestione delle Risorse

Utilizzo del ResourceManager centralizzato per elementi grafici personalizzati.

Cosa: ResourceManager.get_icon().
Come: btn.setIcon(ResourceManager.get_icon("custom-icon.svg")).
Perché serve: Sfrutta il Dynamic Tinting (colora automaticamente gli SVG di bianco o nero in base al tema) e il caching in RAM per massimizzare le performance della UI.

💡 Nota operativa: Uno script che non utilizza la Dashboard API risulterà visivamente alieno al resto della piattaforma e richiederà manutenzione manuale a ogni aggiornamento del Design System.

4. Vincoli Etici e di Performance

Le estensioni operano all’interno dell’ecosistema FIRE e devono rispettare i pilastri di privacy e stabilità definiti nel PRODUCT-MANIFESTO. Un’estensione che viola questi vincoli è considerata instabile e non idonea all’uso in ambienti di produzione.

4.1. Utilizzo della Rete e Privacy

FIRE permette l’esecuzione di qualsiasi codice Python, incluse le chiamate di rete.

Fetcher: Per gli script di tipo fetcher o connettori autonomi, l’uso di librerie come requests o urllib è standard e necessario per il recupero dati.
Analyzer/Utility: Sebbene tecnicamente possibile, è sconsigliato effettuare chiamate di rete in script di analisi pura. Mantenere l’analisi offline garantisce la Sovranità dei Dati e protegge la proprietà intellettuale della strategia da esfiltrazioni involontarie.

4.2. Efficienza Computazionale

Sebbene le estensioni girino in un thread separato (ScriptRunnerWorker), un utilizzo inefficiente delle risorse può degradare le performance globali del sistema.

Cosa: Ottimizzazione algoritmica.
Come:
1. Prediligere operazioni vettoriali (Pandas/Numpy) rispetto ai loop for sui DataFrame.
2. Rilasciare oggetti voluminosi non più necessari (del df).
3. Evitare loop infiniti o ricorsioni profonde che non prevedano un’uscita di sicurezza.
Perché serve: Prevenire il saturamento della memoria RAM e mantenere il processore disponibile per i motori di calcolo core (Backtest, AI Inference).

4.3. Gestione degli Errori e Resilienza

Il codice dell’estensione non deve mai causare il crash dell’applicazione host.

Cosa: Incapsulamento della logica (Error Handling).
Come: Implementare blocchi try...except granulari. In caso di errore critico, loggare l’evento tramite context.ui.log(e, "ERROR") e uscire con eleganza.
Perché serve: Garantire che un bug in uno script utente non interrompa l’esecuzione di altre sinapsi (es. scanner o trade attivo).

4.4. Politica delle Dipendenze

L’utilizzo di librerie esterne non incluse nel .venv di FIRE deve essere ridotto al minimo.

Cosa: Utilizzo delle librerie core pre-installate.
Come: Verificare se la funzionalità richiesta è già disponibile in pandas, numpy, scipy o scikit-learn prima di tentare l’import di pacchetti esotici.
Perché serve: Assicura la portabilità dello script tra diverse installazioni di FIRE e riduce la superficie di attacco/instabilità del sistema.

💡 Nota operativa: In fase di sviluppo, monitorare il consumo di risorse tramite lo strumento “Developer Tools” di FIRE per identificare eventuali memory leak dello script.

5. [AI-ORCHESTRATION] System Prompt: FIRE Extension Expert

Copia e incolla il testo seguente nel “System Message” o nelle “Istruzioni Personalizzate” del tuo modello LLM per trasformarlo in un generatore perfetto di estensioni FIRE.

# ROLE: Senior Quant Developer - FIRE Platform Expert
Agisci come un esperto sviluppatore del team core di FIRE (Financial Intelligence & Research Engine). Il tuo compito è scrivere estensioni Python (.py) seguendo rigorosamente il manuale tecnico FIRE SDK e il Design System v3.8.8.
 
## 1. VINCOLI STRUTTURALI OBBLIGATORI
Ogni script DEVE essere un file Python valido e iniziare con un blocco di metadati racchiuso tra **tripli apici doppi**:
"""
---
id: 00XX (Progressivo o snake_case univoco)
title: ...
version: 1.0
type: ... (analyzer, fetcher, exporter, utility o custom)
description: ...
tags: [...]
---
"""
- **Entry Point:** Tutta la logica operativa deve risiedere nella funzione `run(context)`. Nessun codice deve essere eseguito al di fuori di essa (scope globale).
 
## 2. CONTEXT API (FACADE) SPECIFICATION
Utilizza esclusivamente l'oggetto `context` iniettato per interagire con il sistema:
- `context.data.fetch(ticker, start_date, end_date, interval="1d")`: Metodo standard per ottenere dati storici (restituisce Pandas DataFrame).
- `context.state.current_ticker`: Per ottenere il ticker attivo nella UI.
- `context.ui.create_dashboard(title)`: Inizializza l'interfaccia di output.
- `context.ui.apply_fire_style(fig, is_report=True)`: **Obbligatorio** per ogni grafico Plotly per garantire Smart Contrast e Branding.
- `context.ui.log(message, level)`: Per feedback nel pannello log (levels: INFO, SUCCESS, WARNING, ERROR).
- `context.theme.primary`: Accessore al colore di brand (Arancione FIRE) per le tracce dei grafici.
 
## 3. DESIGN SYSTEM & UI SEMANTICA
È vietato l'uso di HTML/CSS hard-coded o colori esadecimali per la UI. Usa la Dashboard API:
- **Metric Cards:** `dash.add_metric(label, value, variant, sub_value="")`.
- **Varianti Semantiche:** 
    - `info`: Accento Brand (Arancione).
    - `success`: Trading Bullish / Sicurezza (Verde).
    - `warning`: Cautela / Analisi (Arancione).
    - `danger`: Rischio Critico (Rosso).
- **Layout:** Il sistema gestisce automaticamente il responsive flow e lo stacking verticale (v1.0.6).
 
## 4. VINCOLI TECNICI ED ETICI
- **Utilizzo Rete:** Le chiamate a API esterne (es. via `requests`) sono consentite **ESCLUSIVAMENTE** se `type: fetcher`. Per `analyzer` e altri tipi, l'esecuzione deve essere locale (Privacy-First).
- **Efficienza:** Usa operazioni vettoriali Pandas/Numpy. Evita loop `for` su DataFrame voluminosi.
- **Resilienza:** Incapsula la logica in blocchi `try...except` e logga gli errori via `context.ui.log`.
- **Serializzazione:** Prima di passare dati a Plotly, converti le serie Pandas in liste native (`.tolist()`) per evitare errori JSON.
 
## 5. OUTPUT FORMAT
Fornisci sempre il codice integrale del file .py, pronto per essere salvato ed eseguito. Inizia l'output direttamente con i tripli apici del blocco YAML.

6. Conclusioni

Lo sviluppo di estensioni in FIRE rappresenta il metodo primario per potenziare le capacità analitiche della piattaforma senza alterarne il kernel. L’aderenza agli standard SDK garantisce la longevità del codice e la sua perfetta integrazione nell’ecosistema operativo.

6.1. Checklist di Validazione Finale

Prima di distribuire o attivare un’estensione nel workflow di produzione, lo sviluppatore deve verificare i seguenti punti:

Integrità Metadati: Il blocco YAML iniziale contiene id, title e type corretti.
Entry Point: La funzione run(context) è presente e incapsula tutta la logica operativa.
Data Sovereignty: Viene utilizzato context.data.fetch() per il recupero dei prezzi storici.
Coerenza Visiva: Il report viene generato tramite Dashboard API (niente HTML hard-coded).
Smart Style: Ogni grafico Plotly riceve il metodo apply_fire_style(fig, is_report=True).
Adaptive Test: Il report è leggibile sia in Dark che in Light mode.
Privacy Check: Non sono presenti chiamate a API esterne o trasmissioni dati via rete.

6.2. Risultato Tecnico

L’utilizzo rigoroso del Design System (v3.8.8+) e del ResourceManager (v1.4+) assicura che lo script:

Erediti automaticamente le geometrie (6px radius) e la tipografia di sistema.
Adatti i colori delle card e dei grafici al tema attivo dell’utente.
Operi con la massima efficienza prestazionale grazie al caching delle risorse.

6.3. Deployment

Per attivare l’estensione:

Salvare il file .py nella directory degli script configurata.
Accedere alla tab Extensions (o Script Hub).
Cliccare su 🔄 (Refresh) per indicizzare il nuovo analyzer.
Premere Run per l’esecuzione immediata.

💡 Nota operativa: In caso di comportamenti anomali del layout, consultare il file scripts/debug/last_report_audit.html per ispezionare la struttura DOM generata dal motore di rendering.

📖 Approfondimenti: Per lo sviluppo di componenti nativi del framework, consultare la documentazione ARCHITECTURE-OVERVIEW e i relativi Deep Dives (DD-*).

Quartz 4

Explorer

- All in Sviluppo Estensioni FIRE

Sommario

1. Sviluppo Estensioni FIRE

Architettura e Scope

Integrazione Tecnica

Scopo Operativo

2. I Vincoli Obbligatori

2.1. Frontmatter YAML (Sintassi e Metadati)

2.2 Entry Point: `run(context)`

Esempio: Estensione Minima Valida

Struttura dei File

3. Le Regole di “Buona Cittadinanza”

3.1. Accesso ai Dati (Data Sovereignty)

3.2. UI Semantica (Dashboard API)

3.3. Smart Style per Grafici Plotly

3.4. Gestione delle Risorse

4. Vincoli Etici e di Performance

4.1. Utilizzo della Rete e Privacy

4.2. Efficienza Computazionale

4.3. Gestione degli Errori e Resilienza

4.4. Politica delle Dipendenze

5. [AI-ORCHESTRATION] System Prompt: FIRE Extension Expert

6. Conclusioni

6.1. Checklist di Validazione Finale

6.2. Risultato Tecnico

6.3. Deployment

Graph View

Table of Contents

Quartz 4

Explorer

- All in Sviluppo Estensioni FIRE

Sommario

1. Sviluppo Estensioni FIRE

Architettura e Scope

Integrazione Tecnica

Scopo Operativo

2. I Vincoli Obbligatori

2.1. Frontmatter YAML (Sintassi e Metadati)

2.2 Entry Point: run(context)

Esempio: Estensione Minima Valida

Struttura dei File

3. Le Regole di “Buona Cittadinanza”

3.1. Accesso ai Dati (Data Sovereignty)

3.2. UI Semantica (Dashboard API)

3.3. Smart Style per Grafici Plotly

3.4. Gestione delle Risorse

4. Vincoli Etici e di Performance

4.1. Utilizzo della Rete e Privacy

4.2. Efficienza Computazionale

4.3. Gestione degli Errori e Resilienza

4.4. Politica delle Dipendenze

5. [AI-ORCHESTRATION] System Prompt: FIRE Extension Expert

6. Conclusioni

6.1. Checklist di Validazione Finale

6.2. Risultato Tecnico

6.3. Deployment

Graph View

Table of Contents

2.2 Entry Point: `run(context)`