Progetto per 2/3 del voto.
Orale per 1/3 dei punti composto da:
- Presentazione (come se lo facessimo ad un cliente) di gruppo
- Orale singolo con domande del corso (teoria e strumenti visti)

L'obiettivo è quello di creare un sistema di consulenza finanziaria basato su LLM Agents che analizza il mercato delle criptovalute per fornire consigli di investimento personalizzati. Inoltre il sistema deve dimostrare la capacità di ragionare, gestire la persistenza dei dati, utilizzare fonti esterne e presentare un'analisi comprensibile e razionale, offrendo sia una consulenza ad ampio spettro che su una singola criptovaluta.

Indice

Installazione
Applicazione
- Struttura del codice del Progetto
- Tests

Installazione

L'installazione di questo progetto richiede 3 passaggi totali (+1 se si vuole sviluppare in locale) che devono essere eseguiti in sequenza. Se questi passaggi sono eseguiti correttamente, l'applicazione dovrebbe partire senza problemi. Altrimenti è molto probabile che si verifichino errori di vario tipo (moduli mancanti, chiavi API non trovate, ecc.).

Configurazioni dell'app e delle variabili d'ambiente
Installare Ollama e i modelli locali
Far partire il progetto con Docker (consigliato)
(Solo per sviluppo locale) Installare uv e creare l'ambiente virtuale

Important

Prima di iniziare, assicurarsi di avere clonato il repository e di essere nella cartella principale del progetto.

1. Configurazioni

Ci sono due file di configurazione principali che l'app utilizza: config.yaml e .env.
Il primo contiene le configurazioni generali dell'applicazione e può essere modificato a piacimento, mentre il secondo è utilizzato per le variabili d'ambiente.

Per il secondo, bisogna copiare il file .env.example in .env e successivamente modificalo con le tue API keys:

cp .env.example .env
nano .env  # esempio di modifica del file

Le API Keys devono essere inserite nelle variabili opportune dopo l'uguale e senza spazi. Esse si possono ottenere tramite i loro providers (alcune sono gratuite, altre a pagamento).
Nel file .env.example sono presenti tutte le variabili da compilare con anche il link per recuperare le chiavi, quindi, dopo aver copiato il file, basta seguire le istruzioni al suo interno.

Le chiavi non sono necessarie per far partire l'applicazione, ma senza di esse alcune funzionalità non saranno disponibili o saranno limitate. Per esempio senza la chiave di NewsAPI non si potranno recuperare le ultime notizie sul mercato delle criptovalute. Ciononostante, l'applicazione usa anche degli strumenti che non richiedono chiavi API, come Yahoo Finance e GNews, che permettono di avere comunque un'analisi di base del mercato.

2. Ollama

Per utilizzare modelli AI localmente, è necessario installare Ollama, un gestore di modelli LLM che consente di eseguire modelli direttamente sul proprio hardware. Si consiglia di utilizzare Ollama con il supporto GPU per prestazioni ottimali, ma è possibile eseguirlo anche solo con la CPU.

Per l'installazione scaricare Ollama dal loro sito ufficiale.

Dopo l'installazione, si possono iniziare a scaricare i modelli desiderati tramite il comando ollama pull <model>:<tag>.

I modelli usati dall'applicazione sono quelli specificati nel file config.yaml alla voce model. Se in locale si hanno dei modelli diversi, è possibile modificare questa voce per usare quelli disponibili. I modelli consigliati per questo progetto sono qwen3:4b e qwen3:1.7b.

3. Docker

Se si vuole solamente avviare il progetto, si consiglia di utilizzare Docker, dato che sono stati creati i files Dockerfile e docker-compose.yaml per creare il container con tutti i file necessari e già in esecuzione.

docker compose up --build -d

Se si sono seguiti i passaggi precedenti per la configurazione delle variabili d'ambiente, l'applicazione dovrebbe partire correttamente, dato che il file .env verrà automaticamente caricato nel container grazie alla configurazione in docker-compose.yaml.

4. UV (solo per sviluppo locale)

Per prima cosa installa uv se non è già presente sul sistema

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Dopodiché bisogna creare un ambiente virtuale per lo sviluppo locale e impostare PYTHONPATH. Questo passaggio è necessario per far sì che Python riesca a trovare tutti i moduli del progetto e ad installare tutte le dipendenze. Fortunatamente uv semplifica molto questo processo:

uv venv
uv pip install -e .

A questo punto si può già modificare il codice e, quando necessario, far partire il progetto tramite il comando:

uv run src/app

Applicazione

Caution

L'applicazione è attualmente in fase di sviluppo.

L'applicazione viene fatta partire tramite il file src/app/__main__.py che inizializza l'agente principale e gli agenti secondari.

In esso viene creato il server gradio per l'interfaccia web e viene anche inizializzato il bot di Telegram (se è stata inserita la chiave nel file .env ottenuta da BotFather).

L'interazione è guidata, sia tramite l'interfaccia web che tramite il bot di Telegram; l'utente può scegliere prima di tutto delle opzioni generali (come il modello e la strategia di investimento), dopodiché può inviare un messaggio di testo libero per chiedere consigli o informazioni specifiche. Per esempio: "Qual è l'andamento attuale di Bitcoin?" o "Consigliami quali sono le migliori criptovalute in cui investire questo mese".

L'applicazione, una volta ricevuta la richiesta, la passa al Team di agenti che si occupano di raccogliere i dati necessari per rispondere in modo completo e ragionato.

Gli agenti coinvolti nel Team sono:

Leader: Coordina gli altri agenti e fornisce la risposta finale all'utente.
Market Agent: Recupera i dati di mercato attuali delle criptovalute da Binance e Yahoo Finance.
News Agent: Recupera le ultime notizie sul mercato delle criptovalute da NewsAPI e GNews.
Social Agent: Recupera i dati dai social media (Reddit) per analizzare il sentiment del mercato.

Struttura del codice del Progetto

src
└── app
    ├── __main__.py
    ├── config.py    <-- Configurazioni app
    ├── agents       <-- Agenti, Team, prompts e simili
    ├── api          <-- Tutte le API esterne
    │   ├── core     <-- Classi core per le API
    │   ├── markets  <-- Market data provider (Es. Binance)
    │   ├── news     <-- News data provider (Es. NewsAPI)
    │   ├── social   <-- Social data provider (Es. Reddit)
    │   └── tools    <-- Tools per agenti creati dalle API
    └── interface    <-- Interfacce utente

Tests

Per eseguire i test, assicurati di aver configurato correttamente le variabili d'ambiente nel file .env come descritto sopra. Poi esegui il comando:

uv run pytest -v

# Oppure per test specifici
uv run pytest -v tests/api/test_binance.py
uv run pytest -v -k "test_news"

# Oppure usando i markers
uv run pytest -v -m api
uv run pytest -v -m "api and not slow"