README.md

metadata

title: TimesFM Sales Forecasting
emoji: 🐠
colorFrom: yellow
colorTo: pink
sdk: gradio
sdk_version: 6.6.0
app_file: app.py
pinned: false
license: apache-2.0
short_description: Gradio app for sales forecasting with Google TimesFM

TimesFM WebApp

Web app in Gradio con backend Python per forecasting vendite con il modello Google TimesFM.

Struttura progetto

timesfm-webapp/
  .venv/
  app/
    main.py
  requirements.txt
  README.md

Prerequisiti

• Python 3.10+ installato nel sistema
• Accesso internet per scaricare librerie Python e modello TimesFM da Hugging Face/GitHub

Setup ambiente virtuale

Nel progetto e gia presente la cartella .venv. Se vuoi rigenerarla:

python -m venv .venv

Installazione dipendenze

.\.venv\Scripts\python.exe -m pip install -r requirements.txt

Configurazione token Hugging Face (HF)

Il progetto legge automaticamente il token dalle variabili ambiente:

• HF_TOKEN (consigliata)
• HUGGING_FACE_HUB_TOKEN
• HUGGINGFACE_HUB_TOKEN

Impostazione solo per la sessione PowerShell corrente:

$env:HF_TOKEN="hf_xxxxxxxxxxxxxxxxxxxxx"

Impostazione permanente per l'utente Windows:

setx HF_TOKEN "hf_xxxxxxxxxxxxxxxxxxxxx"

Dopo setx, chiudi e riapri PowerShell prima di avviare l'app.

Su Hugging Face Spaces non inserire il token nel codice: aggiungilo in Settings > Secrets con nome HF_TOKEN.

Avvio applicazione

Dalla root del progetto:

.\.venv\Scripts\python.exe app/main.py

Gradio mostrera un URL locale (tipicamente http://127.0.0.1:7860).

Come usare la web app

1. Carica un file storico vendite in formato CSV/XLS/XLSX.
2. Per default la web app usa:
   • prima colonna = data
   • seconda colonna = valore vendite I nomi delle colonne possono essere qualsiasi.
3. Se necessario, puoi cambiare manualmente le colonne dai menu a tendina.
4. Scegli l'orizzonte di forecast (1, 2, 3, 6, 12, 18, 24 mesi).
5. Clicca Esegui Forecast.

Output:

• Grafico 1: storico vendite.
• Grafico 2: storico + forecast + intervallo di confidenza (P10-P90).
• Tabella con forecast e quantili.

Note operative

• Il primo avvio e piu lento perche carica il modello TimesFM.
• Per risultati coerenti con la richiesta business, lo storico dovrebbe avere granularita mensile.