Agente di Analisi e Consulenza Crypto

Questa è la repository per l'esame di Applicazioni Intelligenti che consiste in:

• 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
  • 1. Variabili d'Ambiente
  • 2. Ollama
  • 3. Docker
  • 4. UV (solo per sviluppo locale)
• Applicazione
  • Ultimo Aggiornamento
  • 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.).

1. Configurare le variabili d'ambiente
2. Installare Ollama e i modelli locali
3. Far partire il progetto con Docker (consigliato)
4. (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. Variabili d'Ambiente

Copia il file .env.example in .env e modificalo con le tue API keys:

cp .env.example .env

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 visibili in src/app/models.py. Di seguito metto lo stesso una lista di modelli, ma potrebbe non essere aggiornata:

• gpt-oss:latest
• qwen3:latest
• qwen3:4b
• 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.

# Configura le variabili d'ambiente
cp .env.example .env
nano .env  # Modifica il file

# Avvia il container
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

UV installerà python e creerà automaticamente l'ambiente virtuale con le dipendenze corrette (nota che questo passaggio è opzionale, dato che uv, ogni volta che si esegue un comando, controlla se l'ambiente è attivo e se le dipendenze sono installate):

uv sync --frozen --no-cache

A questo punto si può far partire il progetto tramite il comando:

uv run python src/app.py

Applicazione

L'applicazione è attualmente in fase di sviluppo.

Usando la libreria gradio è stata creata un'interfaccia web semplice per interagire con l'agente principale. Gli agenti secondari si trovano nella cartella src/app/agents e sono:

• Market Agent: Agente unificato che supporta multiple fonti di dati con auto-retry e gestione degli errori.
• News Agent: Recupera le notizie finanziarie più recenti sul mercato delle criptovalute.
• Social Agent: Analizza i sentimenti sui social media riguardo alle criptovalute.
• Predictor Agent: Utilizza i dati raccolti dagli altri agenti per fare previsioni.

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"