Quartz 4

POC: API Esplicita per 4 Tipi di Segnale (Long/Short, Entry/Exit)

3 min read

File 2: docs/poc/poc_explicit_signals.md

Vedi le versioni precedenti:
(.venv) PS D:\01_DevOps\fire\fireDev_12> python scripts/poc/poc_explicit_signals_v5.py --watchlist "D:/01_DevOps/fire/fire_resource/watchlist/DOW_JONES_30.csv" --lookback 1 --signals long,short,closelong,closeshort

Proof of Concept: API Esplicita per Tipi di Segnale

1. Scopo

Questo Proof of Concept (POC) nasce da un’analisi sul comportamento desiderato dello Signal Scanner. È emerso che un utente potrebbe voler usare lo scanner non solo per trovare nuove opportunità di ingresso (Long), ma anche per monitorare segnali di uscita su posizioni esistenti o per cercare opportunità ribassiste (Short).

L’approccio precedente, basato su buy() e sell(), era ambiguo: un sell() poteva significare “chiudi posizione long” o “apri posizione short”.

L’obiettivo di questo POC era validare un’architettura API più robusta e chiara, basata su intenzioni esplicite:

  1. Prototipare una nuova BaseStrategy con quattro metodi distinti: enter_long, close_long, enter_short, close_short.
  2. Creare un ExplicitSignalEngine che reagisca a queste chiamate specifiche, eliminando ogni ambiguità.
  3. Dimostrare la flessibilità aggiungendo un filtro da riga di comando (--signals) per permettere all’utente di scegliere quali tipi di segnale visualizzare.

Questo POC ha validato che l’approccio dell’API esplicita è tecnicamente fattibile, rende il codice della strategia più leggibile e fornisce le fondamenta per uno scanner professionale e personalizzabile.

2. Come si Lancia

Prerequisiti:

  • Ambiente virtuale del progetto attivo.

Comando: Dalla directory principale del progetto, specificare la watchlist e i tipi di segnale desiderati.

  • Solo Ingressi Long e Short:
python scripts/poc/poc_explicit_signals_v5.py --watchlist "path/to/watchlist.csv" --lookback 7 --signals long,short
  • Solo Uscite da Posizioni Long:
python scripts/poc/poc_explicit_signals_v5.py --watchlist "path/to/watchlist.csv" --lookback 7 --signals closelong

3. Risultato Atteso

Lo script esegue la scansione e stampa un report che include solo i tipi di segnale specificati nel filtro --signals. L’output finale mostra per ogni ticker la data e il tipo esatto di segnale rilevato (es. 2025-11-26: Close Long).

Il successo del POC è dimostrato dalla capacità dello script di filtrare correttamente i segnali e di distinguere senza ambiguità tra le quattro diverse intenzioni di trading, confermando la validità del nuovo design dell’API.

Ecco la cronologia dei nomi dei nostri POC per lo scanner, così è tutto chiaro:

  • poc_fast_scanner.py (v1): La primissima versione con yfinance, che aveva il problema di return_class.
  • poc_fast_scanner.py (v2 - con requests): La versione che hai eseguito e che ha dato l’errore FileNotFoundError prima di correggere il path.
  • poc_fast_scanner_v2.py (nel mio messaggio): Questa era la mia proposta per il fix “stateless”, ma poi hai avuto l’idea del lookback.
  • poc_fast_scanner_v3.py: La versione che ha implementato il —lookback.
  • poc_fast_scanner_v4.py: La versione che ha iniziato a distinguere tra segnali di ingresso e di uscita.
  • poc_explicit_signals_v5.py: L’ultima e più evoluta versione, che introduce l’API Esplicita (enter_long, close_long, etc.) come soluzione architetturale definitiva.

Graph View

Backlinks