Enhance documentation

README.md

@@ -87,56 +87,32 @@ Il file `.env` verrà automaticamente caricato nel container grazie alla configu
 
 # **Applicazione**
 
-**L'applicazione è attualmente in fase di sviluppo.** 
+***L'applicazione è attualmente in fase di sviluppo.***
 
-## Ultimo Aggiornamento
+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:
-Usando la libreria ``gradio`` è stata creata un'interfaccia web semplice per interagire con gli agenti. Gli agenti si trovano
+- **Market Agent**: ~~Agente unificato che supporta multiple fonti di dati (Coinbase + CryptoCompare) con auto-configurazione~~  (non proprio un agente per ora)
-nella cartella `src/app/agents` e sono:
-- **Market Agent**: Agente unificato che supporta multiple fonti di dati (Coinbase + CryptoCompare) con auto-configurazione
 - **News Agent**: Recupera le notizie finanziarie più recenti utilizzando. ***MOCK***
 - **Social Agent**: Analizza i sentimenti sui social media utilizzando. ***MOCK***
 - **Predictor Agent**: Utilizza i dati raccolti dagli altri agenti per fare previsioni.
 
+## Ultimo Aggiornamento
 ### Market Agent Features:
 - **Auto-configurazione**: Configura automaticamente i provider disponibili basandosi sulle env vars
 - **Multiple provider**: Supporta sia Coinbase (trading) che CryptoCompare (market data)
-- **Fallback intelligente**: Se un provider fallisce, prova automaticamente altri
 - **Interfaccia unificata**: Un'unica API per accedere a tutti i provider
-- **Provider-specific methods**: Accesso diretto alle funzionalità specifiche di ogni provider
 
-### Problemi noti
+### Problemi con i modelli LLM:
-1. Google ci sono differenze fra i modelli 1.x e i modelli 2.x. Si suggerisce la costruzione di due metodi differenti. 
+1. **Ollama gpt-oss**: il modello `gpt-oss` funziona ma non riesce a seguire le istruzioni.
-   2. `gemini-1.5-flash` funziona perfettamente
+2. **Ollama-gwen**: il modello `gwen` funziona più veloce di `gpt-oss` ma comunque non segue le istruzioni.
-   3. `gemini-2.5-flash` non funziona passando parametri come *temperature* e *max_tokens*, bisogna trovare la nuova sintassi.
-2. Ollama viene correttamente triggerato dalla selezione da interfaccia web ma la generazione della risposta non viene parsificata correttamente. 
 
 ### ToDo
-1. ~~Per lo scraping online bisogna iscriversi e recuperare le chiavi API~~
+1. [X] Per lo scraping online bisogna iscriversi e recuperare le chiavi API
-   2. **Market Agent**: ✅ [CryptoCompare](https://www.cryptocompare.com/cryptopian/api-keys) (implementato)
+2. [X] **Market Agent**: [CryptoCompare](https://www.cryptocompare.com/cryptopian/api-keys)
-   3. **Market Agent**: ✅ [Coinbase](https://www.coinbase.com/cloud/discover/api-keys) (implementato)
+3. [X] **Market Agent**: [Coinbase](https://www.coinbase.com/cloud/discover/api-keys)
-   4. **News Agent**: [CryptoPanic](https://cryptopanic.com/)
+4. [] **News Agent**: [CryptoPanic](https://cryptopanic.com/)
-   5. **Social Agent**: [post più hot da r/CryptoCurrency (Reddit)](https://www.reddit.com/)
+5. [] **Social Agent**: [post più hot da r/CryptoCurrency (Reddit)](https://www.reddit.com/)
-6. Capire come `gpt-oss` parsifica la risposta e per questioni "estetiche" si può pensare di visualizzare lo stream dei token. Vedere il sorgente `src/ollama_demo.py` per risolvere il problema.
+6. [] Capire come `gpt-oss` parsifica la risposta e per questioni "estetiche" si può pensare di visualizzare lo stream dei token. Vedere il sorgente `src/ollama_demo.py` per risolvere il problema.
 
 ## Tests
-Per testare il market agent implementato, puoi usare diversi metodi:
 
-**Test con pytest** (raccomandato):
+***Per ora ho cambiato tutto e quindi i test non funzionano***
-```sh
-# Esegui tutti i test
-uv run pytest tests/agents/test_market_agents.py -v
-
-# Esegui solo test veloci (esclude test API lenti)
-uv run pytest tests/agents/test_market_agents.py -v -m "not slow"
-
-# Esegui solo test che richiedono API
-uv run pytest tests/agents/test_market_agents.py -v -m "api"
-
-# Esegui test con output dettagliato
-uv run pytest tests/agents/test_market_agents.py -v -s
-```
-
-**Test rapido**:
-```sh
-uv run python -c "from src.app.agents.market_agent import MarketAgent; agent = MarketAgent(); print('Providers:', agent.get_available_providers()); print(agent.analyze('test'))"
-```

src/app/markets/base.py

@@ -2,6 +2,10 @@ from coinbase.rest.types.product_types import Candle, GetProductResponse
 
 
 class BaseWrapper:
+    """
+    Interfaccia per i wrapper delle API di mercato.
+    Implementa i metodi di base che ogni wrapper deve avere.
+    """
     def get_product(self, asset_id: str) -> 'ProductInfo':
         raise NotImplementedError
     def get_products(self, asset_ids: list[str]) -> list['ProductInfo']:
@@ -12,6 +16,10 @@ class BaseWrapper:
         raise NotImplementedError
 
 class ProductInfo:
+    """
+    Informazioni sul prodotto, come ottenute dalle API di mercato.
+    Implementa i metodi di conversione dai dati grezzi delle API.
+    """
     id: str
     symbol: str
     price: float
@@ -39,6 +47,10 @@ class ProductInfo:
         return product
 
 class Price:
+    """
+    Rappresenta i dati di prezzo per un asset, come ottenuti dalle API di mercato.
+    Implementa i metodi di conversione dai dati grezzi delle API.
+    """
     high: float
     low: float
     open: float

src/app/markets/binance.py

@@ -1,6 +1,9 @@
 # Versione pubblica senza autenticazione
 from binance.client import Client
 
+# TODO fare l'aggancio con API in modo da poterlo usare come wrapper di mercato
+# TODO implementare i metodi di BaseWrapper
+
 class PublicBinanceAgent:
     def __init__(self):
         # Client pubblico (senza credenziali)

src/app/markets/coinbase.py

@@ -2,6 +2,10 @@ from coinbase.rest import RESTClient
 from app.markets.base import ProductInfo, BaseWrapper, Price
 
 class CoinBaseWrapper(BaseWrapper):
+    """
+    Wrapper per le API di Coinbase.
+    La documentazione delle API è disponibile qui: https://docs.cdp.coinbase.com/api-reference/advanced-trade-api/rest-api/introduction
+    """
     def __init__(self, api_key:str, api_private_key:str, currency: str = "USD"):
         assert api_key is not None, "API key is required"
         assert api_private_key is not None, "API private key is required"

src/app/markets/cryptocompare.py

@@ -4,6 +4,11 @@ from app.markets.base import ProductInfo, BaseWrapper, Price
 BASE_URL = "https://min-api.cryptocompare.com"
 
 class CryptoCompareWrapper(BaseWrapper):
+    """
+    Wrapper per le API pubbliche di CryptoCompare.
+    La documentazione delle API è disponibile qui: https://developers.coindesk.com/documentation/legacy/Price/SingleSymbolPriceEndpoint
+    !!ATTENZIONE!! sembra essere una API legacy e potrebbe essere deprecata in futuro.
+    """
     def __init__(self, api_key:str, currency:str='USD'):
         assert api_key is not None, "API key is required"
 

src/app/tool.py

@@ -7,7 +7,16 @@ from app.models import Models
 
 
 class ToolAgent:
+    """
+    Classe principale che coordina gli agenti per rispondere alle richieste dell'utente.
+    available_models: lista dei modelli disponibili (Models.availables()).
+    all_styles: lista degli stili di previsione disponibili (PredictorStyle).
+    """
+
     def __init__(self, available_models: list[Models], all_styles: list[PredictorStyle]):
+        """
+        Inizializza l'agente con i modelli e gli stili disponibili.
+        """
         self.available_models = available_models
         self.all_styles = all_styles
 
@@ -15,6 +24,10 @@ class ToolAgent:
         self.choose_provider(0) # Default to the first model
 
     def choose_provider(self, index: int):
+        """
+        Sceglie il modello LLM da utilizzare in base all'indice fornito.
+        index: indice del modello nella lista available_models.
+        """
         # TODO Utilizzare AGNO per gestire i modelli... è molto più semplice e permette di cambiare modello facilmente
         # TODO https://docs.agno.com/introduction
         # Inoltre permette di creare dei team e workflow di agenti più facilmente
@@ -26,6 +39,8 @@ class ToolAgent:
     def interact(self, query: str, style_index: int):
         """
         Funzione principale che coordina gli agenti per rispondere alla richiesta dell'utente.
+        query: richiesta dell'utente (es. "Qual è la previsione per Bitcoin?")
+        style_index: indice dello stile di previsione nella lista all_styles.
         """
 
         # Step 1: raccolta analisi