Screening e ticker

Filtra e classifica i mercati per criteri, profilo di rischio o opportunità d’acquisto, risolvi nomi in ticker e aggiungi nuovi strumenti al monitoraggio.

stock_screener

Cosa fa. Screening di azioni per criteri finanziari (P/E, crescita, margini…). Interpreta criteri in linguaggio naturale (routing LLM).

Quando/come lo usa l’AI. Quando descrivi a parole cosa cerchi tra le azioni.

Parametri. Criteri in linguaggio naturale.

Restituisce. Azioni che soddisfano i criteri.

Possibili errori / stati.

• Failed to parse screening criteria — criteri non interpretabili.
• Failed to fetch screener metrics — errore nel recupero delle metriche.
• Unknown field: X — il filtro usa un campo inesistente; i campi stringa sono solo sector, industry, country.

Nota. Copre solo le azioni: la tabella dietro lo screener contiene 738 righe, tutte di tipo STOCK, e non esiste un filtro per tipo di asset. Per futures, fondi e forex servono list_futures, list_funds e list_forex_assets. I valori ammessi di sector, industry e country sono letti dal database (11 settori, 115 industrie, 32 paesi) e forniti al modello insieme alle metriche: vanno usati alla lettera. Il database segue la tassonomia yfinance, non GICS — Technology e non “Information Technology”, Healthcare e non “Health Care”, Financial Services e non “Financials”.

preset_screener

Cosa fa. Screening di azioni per profilo di rischio (low/mid/high) con filtri pre-costruiti. Istantaneo, senza routing LLM.

Quando/come lo usa l’AI. Per liste pronte per profilo.

Parametri. profile (low/mid/high), numero.

Restituisce. Azioni filtrate per profilo.

Possibili errori / stati.

• Unknown profile: … Use 'low', 'mid', or 'high'.
• Preset screener request failed — errore lato server.

preset_etf_screener

Cosa fa. Screening di ETF per profilo di rischio (low/mid/high) con filtri matematici. Deterministico.

Quando/come lo usa l’AI. Per liste pronte di ETF per profilo.

Parametri. profile, numero.

Restituisce. ETF filtrati per profilo, con profile_label che riporta le soglie realmente applicate.

Possibili errori / stati.

• Failed to screen ETFs — errore nel recupero o nel filtro lato server.

Nota. Soglie e liste di categorie configurabili in config.yaml → etf_screener; il filtro gira lato server (/etf/preset-screener/), non nel tool. low: obbligazionari/difensivi, AUM ≥ $1 mld, spese ≤ 0,20%; mid: mercato ampio, AUM ≥ $5 mld, spese ≤ 0,15%; high: tutto tranne obbligazionario/difensivo, AUM ≥ $500M. Nessun filtro sui rendimenti: pretendere 3Y/5Y positivi escluderebbe TLT e, sull’orizzonte a 5 anni, anche BND, AGG e LQD, che dopo lo shock dei tassi 2022 sono negativi — cioè svuoterebbe proprio il profilo prudente.

ranked_opportunities

Cosa fa. Classifica l’universo di azioni monitorate come opportunità d’acquisto con la pipeline deterministica di /top: filtri per profilo → percentili relativi al settore → composite score a 5 fattori (qualità, valore, crescita, momentum, sentiment).

Quando/come lo usa l’AI. Per la modalità STOCK di /screen-low|mid|high e per “migliori azioni da comprare”. A differenza di preset_screener (che ordina per market cap e restituisce i nomi più grandi), qui i candidati sono già pre-classificati per opportunità.

Parametri. profile (low/mid/high), strategy (balanced/trend/contrarian, default balanced), limit (50-150, default 50) — il “floor”, cioè la dimensione del pool di candidati. Il server lo restituisce raggruppato in lotti da 5 (data.batches).

Restituisce. {floor, batch_size, batch_count, batches}: candidati pre-classificati per composite_score, raggruppati in batches da 5. Ogni candidato è un oggetto piatto con composite_score + una serie curata di ~18 metriche (prezzo, market cap, Piotroski, Health, Altman Z, D/E, current ratio, ROE, P/E trailing e forward, FCF yield, crescita ricavi/utili, RSI, distanza dai massimi, upside analisti, beta, dividend yield % derivato da dividend_rate/prezzo) — quelle su cui /top calcola il punteggio. L’intero pool resta inline, niente round-trip su file.

Nota. Il parametro floor/batches riguarda solo il tool Dexter. L’agente scorea un lotto alla volta, raccoglie {ticker, ai_score} e li passa a finalize_ranking, che calcola final = composite_score + ai_score e ordina la top-N lato server (deterministico, niente sort a mano). limit mappa il f<FLOOR> di /screen-*. Riusa lato server lo scoring di /top (bot_commands/top.py); il re-scoring AI e le tesi li svolge il modello del terminale, NON i parametri AI di top_analysis (2 LLM diversi, configurazione separata). Il pool è deduplicato per azienda (es. SAP + SAP.F, GOOG + GOOGL → tenuto il listing con composite più alto). Risultati in cache ~10 min.

finalize_ranking

Cosa fa. Combina in modo deterministico gli ai_score assegnati dall’agente con il composite_score lato server e restituisce la top-N già ordinata.

Quando/come lo usa l’AI. Ultimo passo della modalità STOCK di /screen-low|mid|high, dopo aver valutato (ai_score) TUTTI i lotti di ranked_opportunities.

Parametri. profile e strategy (gli STESSI passati a ranked_opportunities), scores (lista di {ticker, ai_score 0-1} per ogni candidato valutato), top_n (1-40), ai_weight (0.1-1, default 0.35) e max_per_sector (opzionale, nessun limite se assente).

Restituisce. {…, ranked}: la top-N già ordinata per final = composite_score + ai_weight × ai_score, ogni riga con composite_score, ai_score, final e le ~18 metriche. Più sector_skipped (righe tagliate dal limite settoriale), unknown_tickers (ticker inviati ma non nel pool) e i conteggi scored/unscored.

Nota. Sposta aritmetica e ordinamento dall’LLM al server: una classifica di 50-150 righe non può più sbagliare la somma, perdere righe o variare tra un run e l’altro. Il composite_score è letto dallo stesso pool in cache di ranked_opportunities (join per ticker), mai dal modello. Il peso AI di default è 0.35, allineato a /top: con composite e ai_score entrambi 0-1, un valore di 1.0 permetterebbe al modello di ribaltare l’intero punteggio quantitativo. Il limite settoriale è applicato dopo l’ordinamento, così in ogni settore sopravvive il titolo migliore.

list_database_tickers

Cosa fa. Elenca le azioni nel database con settore, capitalizzazione e prezzo. Supporta filtri per settore e fascia di market cap.

Quando/come lo usa l’AI. Per esplorare l’universo monitorato o filtrare per settore/dimensione.

Parametri. Filtri opzionali (settore, market cap).

Restituisce. Lista di azioni con metadati.

Possibili errori / stati.

• Failed to list database tickers — errore lato DB.

get_available_stock_tickers

Cosa fa. Restituisce l’elenco di tutti i ticker azionari disponibili nel database.

Quando/come lo usa l’AI. Per sapere quali simboli sono utilizzabili con gli altri tool.

Parametri. Nessuno.

Restituisce. Lista dei ticker disponibili.

resolve_ticker

Cosa fa. Risolve un nome di società o un ticker ambiguo nel simbolo corretto (es. “TeamViewer” → “TMV.DE”).

Quando/come lo usa l’AI. Quando fornisci un nome anziché un ticker, o il ticker è ambiguo.

Parametri. Nome o ticker.

Restituisce. Il simbolo corretto.

add_ticker

Cosa fa. Aggiunge un’azione alla lista di monitoraggio e attende la sincronizzazione dei dati (fino a 60s).

Quando/come lo usa l’AI. Quando i tool finance restituiscono dati vuoti per un ticker che dovrebbe esistere.

Parametri. ticker.

Restituisce. Stato della sincronizzazione.

Possibili errori / stati.

• already_ready — già presente e con dati pronti.
• sync_complete — sync completata, dati disponibili.
• sync_in_progress — in sincronizzazione: riprova tra poco.
• sync_error — sync fallita: prova a rimuovere e riaggiungere il ticker.
• Failed to add … — verifica/aggiunta fallita.

add_future

Cosa fa. Aggiunge un contratto future al monitoraggio (ticker che termina con =F, es. GC=F, CL=F, ES=F).

Quando/come lo usa l’AI. Quando un future non è ancora tracciato.

Parametri. ticker (…=F).

Restituisce. Stato della sincronizzazione.

Possibili errori / stati.

• Stati already_tracked/sync_complete/sync_in_progress/sync_error.
• Failed to add future "…".

add_fund

Cosa fa. Aggiunge un fondo comune al monitoraggio (es. VFIAX, FXAIX). Il worker fa il backfill in modo asincrono.

Quando/come lo usa l’AI. Quando un fondo non è ancora tracciato.

Parametri. ticker.

Restituisce. Stato della sincronizzazione.

Possibili errori / stati.

• Stati already_tracked/sync_complete/sync_in_progress/sync_error.
• Failed to add fund "…".

add_forex

Cosa fa. Aggiunge una coppia forex al monitoraggio (formato XXXYYY=X, es. EURUSD=X, GBPUSD=X).

Quando/come lo usa l’AI. Quando una coppia forex non è ancora tracciata.

Parametri. ticker (…=X).

Restituisce. Stato della sincronizzazione.

Possibili errori / stati.

• Stati already_tracked/sync_complete/sync_in_progress/sync_error.
• Failed to add forex pair "…".