source-command-api-trends

Use this skill when the user asks to run the migrated source command api-trends.

Command Template

CryptoGlossario — API Trends / Wikipedia Disambiguation

Scopo

Lo script scripts/update-popularity.py calcola il momentum score di ogni termine (rapporto pageview ultimi 4 mesi / media 12 mesi, normalizzato 0–100) e lo salva come searchScore. Il dato finisce nell'UI come indicatore di trend.

Per i pageview si appoggia a Wikipedia, cercando la pagina con il titolo esatto del termine. Su parole comuni (Alpha, Gas, Trend, Whale...) finisce sulla pagina sbagliata: la lettera greca, il fluido, lo sportello bancario. Risultato: momentum scollegato dal trend crypto.

Questa skill compila il campo wikipediaTitle per indirizzare lo script alla pagina corretta (o segnalare di saltare Wikipedia del tutto), poi esegue scripts/update-popularity.py per aggiornare il searchScore con la nuova mappatura.

Tre stati possibili per wikipediaTitle

Il sentinel __fallback__ ha doppia funzione: marca il termine come "già esaminato" (esce dalla coda pending) ed evita una 404 inutile a runtime.

Flusso di lavoro

1. Recuperare i pending

``bash bun run list:pending-wikipedia-titles 0 30 ``

Output: una riga JSON per termine, ordinati con i titoli brevi (< 8 caratteri) per primi — quelli più a rischio di omonimia. Ogni riga contiene id, slug, title, definition, disciplines.

Argomenti posizionali: <offset> <count>. Default: 0 30.

2. Decidere lo stato per ogni termine

Per ogni candidato, decidi una delle tre azioni:

#### a) Skip — non aggiungere al batch

Il termine ha già una pagina Wikipedia univoca e crypto-specifica. Lasciare wikipediaTitle assente va bene: lo script userà il title e troverà la pagina giusta.

Esempi: Bitcoin, Ethereum, DeFi, Airdrop, HODL, Merkle tree, SHA-256, EVM.

⚠️ Nota: questi termini ricompaiono al prossimo list:pending-wikipedia-titles perché tecnicamente sono ancora "non esaminati". Se vuoi toglierli dalla coda esplicitamente, setta wikipediaTitle al titolo identico al title (es. "Bitcoin" → "Bitcoin").

#### b) Set wikipediaTitle = "Some Page Title"

Il termine è ambiguo o troppo generico, ma esiste una pagina Wikipedia pertinente. Vedi sotto come trovarla e sceglierla.

Esempi: Alpha → Alpha (finance), Wallet → Cryptocurrency wallet, Trend → Market trend, Quest → Quest (video games).

#### c) Set wikipediaTitle = "__fallback__"

Il termine è specifico/recente e non esiste una pagina Wikipedia pertinente, oppure le pagine candidate sono tutte fuorvianti (es. l'unica pagina è una disambig page o parla di tutt'altro).

Esempi tipici di __fallback__:

• Acronimi crypto-only senza pagina propria: TVL, MEV, TWAP, TXID
• Neologismi di nicchia: mempool fee, on-chain governance, liquidity routing
• Termini in cui Wikipedia ha solo una pagina troppo generica: Token Burn → Cryptocurrency

3. Trovare e verificare il titolo

#### Wikipedia REST API (verifica una pagina specifica)

``bash UA="CryptoGlossario/1.0 (https://cryptoglossario.it; <email>)" curl -sL -H "User-Agent: $UA" \ "https://en.wikipedia.org/api/rest_v1/page/summary/Alpha_%28finance%29" ``

Restituisce title, description, extract, type. Esamina:

• type: standard → pagina valida
• type: disambiguation → non usare: è una pagina di disambiguazione
• description o extract menzionano crypto/blockchain/finance/computing/video games?

⚠️ User-Agent obbligatorio: senza header la REST API restituisce a tratti "Internal error" o risposte vuote.

#### Wikipedia Search API (cerca tra più candidati)

``bash curl -sL -H "User-Agent: $UA" \ "https://en.wikipedia.org/w/api.php?action=query&list=search&srsearch=alpha+finance&format=json&srlimit=3" ``

Aggiungi parole-contesto alla query (cryptocurrency, blockchain, finance, computing, video+games) per spostare il primo risultato verso il dominio giusto, poi conferma il titolo trovato con la REST API.

#### Criteri di scelta tra più candidati

In ordine di preferenza:

1. Suffisso di dominio rilevante: (finance), (cryptocurrency), (blockchain),

(computing), (video games), (database). Esempio: Sharding → Shard (database architecture).

1. Pagina nel dominio giusto (anche senza suffisso): Pump and Dump → Pump and dump,

Stablecoin → Stablecoin.

1. Pagina parente concettuale: se non esiste la voce specifica ma c'è il concetto più

ampio. Esempio: Soft Fork → Fork (blockchain), Tokenizer → Lexical analysis, Speculative Bubble → Economic bubble.

1. Pagina con redirect: usa il titolo finale (title nella response REST), non quello

richiesto.

Se nessuna opzione è chiaramente pertinente → __fallback__.

4. Scrivere il batch e applicare

Formato JSON:

``json [ { "slug": "alpha", "title": "Alpha", "wikipediaTitle": "Alpha (finance)" }, { "slug": "tvl-total-value-locked", "title": "TVL (Total Value Locked)", "wikipediaTitle": "__fallback__" } ] ``

Lo script accetta solo slug e wikipediaTitle; title è opzionale e serve solo come label nei log.

``bash bun run apply:api-trends /tmp/cg_wikititles_batch.json # dry-run bun run apply:api-trends /tmp/cg_wikititles_batch.json --apply ``

5. Aggiornare il momentum

Dopo aver verificato Wikipedia e applicato il batch, esegui sempre lo script di popolarità. Questo passaggio è obbligatorio: senza di lui wikipediaTitle è aggiornato, ma il termine può restare con un searchScore vecchio o neutro.

Prima fai un dry-run per controllare che Wikipedia/PyTrends stiano risolvendo i termini in modo sensato:

``bash python scripts/update-popularity.py --dry-run ``

Poi applica il ricalcolo:

``bash python scripts/update-popularity.py ``

Se stai lavorando in un ambiente in cui PyTrends rate-limita, aumenta lo sleep:

``bash python scripts/update-popularity.py --sleep 2 ``

Se un termine appena impostato va a (no wikipedia) → pytrends, il wikipediaTitle non risolve a una pagina valida — controlla l'encoding (parentesi, accenti) o riconsidera il titolo.

Strategia batch

• Dimensione: 20–30 termini per sessione. Oltre, la fatica di verifica fa scendere

la qualità.

• Ordine: list:pending-wikipedia-titles mette i titoli brevi per primi — sono i più

ambigui. Procedi in quell'ordine.

• Quando sei davvero incerto: non includere il termine nel batch — resta pending e

ricomparirà al prossimo giro.

• Non riusare lo stesso wikipediaTitle per termini diversi se le definizioni sono

diverse (es. Token AI vs Token crypto): puntano a pagine diverse.

Nota sul sistema di popolarità (provvisoria, aprile 2026)

Il momentum è calcolato tramite Wikipedia Pageviews API (sorgente primaria, ufficiale, gratuita) con PyTrends Google Trends come fallback. In futuro questo sistema verrà sostituito da un'unica chiamata API a pagamento (SerpAPI, Exploding Topics, simili) per ottenere dati di search volume più affidabili. Il campo wikipediaTitle rimarrà comunque utile: identifica univocamente il termine nel knowledge graph e può essere riutilizzato come query key dalla nuova API.