Refactor project structure to organize APIs (#24)

* Refactor project structure "api"
* fix bug conversione delle valute fiat in stablecoin in BinanceWrapper
* Refactor: WrapperHandler for managing API wrappers with retry logic; update related modules and tests
* Refactor: Update ProductInfo and Price classes to include aggregation methods; remove standalone aggregation functions
* fix docs

src/app/api/markets/__init__.py

@@ -0,0 +1,86 @@
+from agno.tools import Toolkit
+from app.api.wrapper_handler import WrapperHandler
+from app.api.base.markets import MarketWrapper, Price, ProductInfo
+from app.api.markets.binance import BinanceWrapper
+from app.api.markets.coinbase import CoinBaseWrapper
+from app.api.markets.cryptocompare import CryptoCompareWrapper
+from app.api.markets.yfinance import YFinanceWrapper
+
+__all__ = [ "MarketAPIsTool", "BinanceWrapper", "CoinBaseWrapper", "CryptoCompareWrapper", "YFinanceWrapper", "ProductInfo", "Price" ]
+
+
+class MarketAPIsTool(MarketWrapper, Toolkit):
+    """
+    Class that aggregates multiple market API wrappers and manages them using WrapperHandler.
+    This class supports retrieving product information and historical prices.
+    This class can also aggregate data from multiple sources to provide a more comprehensive view of the market.
+    The following wrappers are included in this order:
+    - BinanceWrapper
+    - YFinanceWrapper
+    - CoinBaseWrapper
+    - CryptoCompareWrapper
+    """
+
+    def __init__(self, currency: str = "USD"):
+        """
+        Initialize the MarketAPIsTool with multiple market API wrappers.
+        The following wrappers are included in this order:
+        - BinanceWrapper
+        - YFinanceWrapper
+        - CoinBaseWrapper
+        - CryptoCompareWrapper
+        Args:
+            currency (str): Valuta in cui restituire i prezzi. Default è "USD".
+        """
+        kwargs = {"currency": currency or "USD"}
+        wrappers: list[type[MarketWrapper]] = [BinanceWrapper, YFinanceWrapper, CoinBaseWrapper, CryptoCompareWrapper]
+        self.handler = WrapperHandler.build_wrappers(wrappers, kwargs=kwargs)
+
+        Toolkit.__init__( # type: ignore
+            self,
+            name="Market APIs Toolkit",
+            tools=[
+                self.get_product,
+                self.get_products,
+                self.get_historical_prices,
+                self.get_products_aggregated,
+                self.get_historical_prices_aggregated,
+            ],
+        )
+
+    def get_product(self, asset_id: str) -> ProductInfo:
+        return self.handler.try_call(lambda w: w.get_product(asset_id))
+    def get_products(self, asset_ids: list[str]) -> list[ProductInfo]:
+        return self.handler.try_call(lambda w: w.get_products(asset_ids))
+    def get_historical_prices(self, asset_id: str, limit: int = 100) -> list[Price]:
+        return self.handler.try_call(lambda w: w.get_historical_prices(asset_id, limit))
+
+
+    def get_products_aggregated(self, asset_ids: list[str]) -> list[ProductInfo]:
+        """
+        Restituisce i dati aggregati per una lista di asset_id.\n
+        Attenzione che si usano tutte le fonti, quindi potrebbe usare molte chiamate API (che potrebbero essere a pagamento).
+        Args:
+            asset_ids (list[str]): Lista di asset_id da cercare.
+        Returns:
+            list[ProductInfo]: Lista di ProductInfo aggregati.
+        Raises:
+            Exception: If all wrappers fail to provide results.
+        """
+        all_products = self.handler.try_call_all(lambda w: w.get_products(asset_ids))
+        return ProductInfo.aggregate(all_products)
+
+    def get_historical_prices_aggregated(self, asset_id: str = "BTC", limit: int = 100) -> list[Price]:
+        """
+        Restituisce i dati storici aggregati per un asset_id. Usa i dati di tutte le fonti disponibili e li aggrega.\n
+        Attenzione che si usano tutte le fonti, quindi potrebbe usare molte chiamate API (che potrebbero essere a pagamento).
+        Args:
+            asset_id (str): Asset ID da cercare.
+            limit (int): Numero massimo di dati storici da restituire.
+        Returns:
+            list[Price]: Lista di Price aggregati.
+        Raises:
+            Exception: If all wrappers fail to provide results.
+        """
+        all_prices = self.handler.try_call_all(lambda w: w.get_historical_prices(asset_id, limit))
+        return Price.aggregate(all_prices)

src/app/api/markets/binance.py

@@ -0,0 +1,83 @@
+import os
+from typing import Any
+from binance.client import Client # type: ignore
+from app.api.base.markets import ProductInfo, MarketWrapper, Price
+
+
+def extract_product(currency: str, ticker_data: dict[str, Any]) -> ProductInfo:
+    product = ProductInfo()
+    product.id = ticker_data.get('symbol', '')
+    product.symbol = ticker_data.get('symbol', '').replace(currency, '')
+    product.price = float(ticker_data.get('price', 0))
+    product.volume_24h = float(ticker_data.get('volume', 0))
+    product.currency = currency
+    return product
+
+def extract_price(kline_data: list[Any]) -> Price:
+    timestamp = kline_data[0]
+
+    price = Price()
+    price.open = float(kline_data[1])
+    price.high = float(kline_data[2])
+    price.low = float(kline_data[3])
+    price.close = float(kline_data[4])
+    price.volume = float(kline_data[5])
+    price.set_timestamp(timestamp_ms=timestamp)
+    return price
+
+
+# Add here eventual other fiat not supported by Binance
+FIAT_TO_STABLECOIN = {
+    "USD": "USDT",
+}
+
+class BinanceWrapper(MarketWrapper):
+    """
+    Wrapper per le API autenticate di Binance.\n
+    Implementa l'interfaccia BaseWrapper per fornire accesso unificato
+    ai dati di mercato di Binance tramite le API REST con autenticazione.\n
+    https://binance-docs.github.io/apidocs/spot/en/
+    """
+
+    def __init__(self, currency: str = "USD"):
+        """
+        Inizializza il wrapper di Binance con le credenziali API e la valuta di riferimento.
+        Alcune valute fiat non sono supportate direttamente da Binance (es. "USD").
+        Infatti, se viene fornita una valuta fiat come "USD", questa viene automaticamente convertita in una stablecoin Tether ("USDT") per compatibilità con Binance.
+        Args:
+            currency (str): Valuta in cui restituire i prezzi. Se "USD" viene fornito, verrà utilizzato "USDT". Default è "USD".
+        """
+        api_key = os.getenv("BINANCE_API_KEY")
+        api_secret = os.getenv("BINANCE_API_SECRET")
+
+        self.currency = currency if currency not in FIAT_TO_STABLECOIN else FIAT_TO_STABLECOIN[currency]
+        self.client = Client(api_key=api_key, api_secret=api_secret)
+
+    def __format_symbol(self, asset_id: str) -> str:
+        """
+        Formatta l'asset_id nel formato richiesto da Binance.
+        """
+        return asset_id.replace('-', '') if '-' in asset_id else f"{asset_id}{self.currency}"
+
+    def get_product(self, asset_id: str) -> ProductInfo:
+        symbol = self.__format_symbol(asset_id)
+
+        ticker: dict[str, Any] = self.client.get_symbol_ticker(symbol=symbol) # type: ignore
+        ticker_24h: dict[str, Any] = self.client.get_ticker(symbol=symbol) # type: ignore
+        ticker['volume'] = ticker_24h.get('volume', 0)
+
+        return extract_product(self.currency, ticker)
+
+    def get_products(self, asset_ids: list[str]) -> list[ProductInfo]:
+        return [ self.get_product(asset_id) for asset_id in asset_ids ]
+
+    def get_historical_prices(self, asset_id: str, limit: int = 100) -> list[Price]:
+        symbol = self.__format_symbol(asset_id)
+
+        # Ottiene candele orarie degli ultimi 30 giorni
+        klines: list[list[Any]] = self.client.get_historical_klines( # type: ignore
+            symbol=symbol,
+            interval=Client.KLINE_INTERVAL_1HOUR,
+            limit=limit,
+        )
+        return [extract_price(kline) for kline in klines]

src/app/api/markets/coinbase.py

@@ -0,0 +1,90 @@
+import os
+from enum import Enum
+from datetime import datetime, timedelta
+from coinbase.rest import RESTClient # type: ignore
+from coinbase.rest.types.product_types import Candle, GetProductResponse, Product # type: ignore
+from app.api.base.markets import ProductInfo, MarketWrapper, Price
+
+
+def extract_product(product_data: GetProductResponse | Product) -> ProductInfo:
+    product = ProductInfo()
+    product.id = product_data.product_id or ""
+    product.symbol = product_data.base_currency_id or ""
+    product.price = float(product_data.price) if product_data.price else 0.0
+    product.volume_24h = float(product_data.volume_24h) if product_data.volume_24h else 0.0
+    return product
+
+def extract_price(candle_data: Candle) -> Price:
+    timestamp = int(candle_data.start) if candle_data.start else 0
+
+    price = Price()
+    price.high = float(candle_data.high) if candle_data.high else 0.0
+    price.low = float(candle_data.low) if candle_data.low else 0.0
+    price.open = float(candle_data.open) if candle_data.open else 0.0
+    price.close = float(candle_data.close) if candle_data.close else 0.0
+    price.volume = float(candle_data.volume) if candle_data.volume else 0.0
+    price.set_timestamp(timestamp_s=timestamp)
+    return price
+
+
+class Granularity(Enum):
+    UNKNOWN_GRANULARITY = 0
+    ONE_MINUTE = 60
+    FIVE_MINUTE = 300
+    FIFTEEN_MINUTE = 900
+    THIRTY_MINUTE = 1800
+    ONE_HOUR = 3600
+    TWO_HOUR = 7200
+    FOUR_HOUR = 14400
+    SIX_HOUR = 21600
+    ONE_DAY = 86400
+
+class CoinBaseWrapper(MarketWrapper):
+    """
+    Wrapper per le API di Coinbase Advanced Trade.\n
+    Implementa l'interfaccia BaseWrapper per fornire accesso unificato
+    ai dati di mercato di Coinbase tramite le API REST.\n
+    https://docs.cdp.coinbase.com/api-reference/advanced-trade-api/rest-api/introduction
+    """
+
+    def __init__(self, currency: str = "USD"):
+        api_key = os.getenv("COINBASE_API_KEY")
+        assert api_key, "COINBASE_API_KEY environment variable not set"
+
+        api_private_key = os.getenv("COINBASE_API_SECRET")
+        assert api_private_key, "COINBASE_API_SECRET environment variable not set"
+
+        self.currency = currency
+        self.client: RESTClient = RESTClient(
+            api_key=api_key,
+            api_secret=api_private_key
+        )
+
+    def __format(self, asset_id: str) -> str:
+        return asset_id if '-' in asset_id else f"{asset_id}-{self.currency}"
+
+    def get_product(self, asset_id: str) -> ProductInfo:
+        asset_id = self.__format(asset_id)
+        asset = self.client.get_product(asset_id) # type: ignore
+        return extract_product(asset)
+
+    def get_products(self, asset_ids: list[str]) -> list[ProductInfo]:
+        all_asset_ids = [self.__format(asset_id) for asset_id in asset_ids]
+        assets = self.client.get_products(product_ids=all_asset_ids) # type: ignore
+        assert assets.products is not None, "No products data received from Coinbase"
+        return [extract_product(asset) for asset in assets.products]
+
+    def get_historical_prices(self, asset_id: str, limit: int = 100) -> list[Price]:
+        asset_id = self.__format(asset_id)
+        end_time = datetime.now()
+        start_time = end_time - timedelta(days=14)
+
+        data = self.client.get_candles( # type: ignore
+            product_id=asset_id,
+            granularity=Granularity.ONE_HOUR.name,
+            start=str(int(start_time.timestamp())),
+            end=str(int(end_time.timestamp())),
+            limit=limit
+        )
+        assert data.candles is not None, "No candles data received from Coinbase"
+        return [extract_price(candle) for candle in data.candles]

src/app/api/markets/cryptocompare.py

@@ -0,0 +1,81 @@
+import os
+from typing import Any
+import requests
+from app.api.base.markets import ProductInfo, MarketWrapper, Price
+
+
+def extract_product(asset_data: dict[str, Any]) -> ProductInfo:
+    product = ProductInfo()
+    product.id = asset_data.get('FROMSYMBOL', '') + '-' + asset_data.get('TOSYMBOL', '')
+    product.symbol = asset_data.get('FROMSYMBOL', '')
+    product.price = float(asset_data.get('PRICE', 0))
+    product.volume_24h = float(asset_data.get('VOLUME24HOUR', 0))
+    assert product.price > 0, "Invalid price data received from CryptoCompare"
+    return product
+
+def extract_price(price_data: dict[str, Any]) -> Price:
+    timestamp = price_data.get('time', 0)
+
+    price = Price()
+    price.high = float(price_data.get('high', 0))
+    price.low = float(price_data.get('low', 0))
+    price.open = float(price_data.get('open', 0))
+    price.close = float(price_data.get('close', 0))
+    price.volume = float(price_data.get('volumeto', 0))
+    price.set_timestamp(timestamp_s=timestamp)
+    return price
+
+
+BASE_URL = "https://min-api.cryptocompare.com"
+
+class CryptoCompareWrapper(MarketWrapper):
+    """
+    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, currency:str='USD'):
+        api_key = os.getenv("CRYPTOCOMPARE_API_KEY")
+        assert api_key, "CRYPTOCOMPARE_API_KEY environment variable not set"
+
+        self.api_key = api_key
+        self.currency = currency
+
+    def __request(self, endpoint: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        if params is None:
+            params = {}
+        params['api_key'] = self.api_key
+
+        response = requests.get(f"{BASE_URL}{endpoint}", params=params)
+        return response.json()
+
+    def get_product(self, asset_id: str) -> ProductInfo:
+        response = self.__request("/data/pricemultifull", params = {
+            "fsyms": asset_id,
+            "tsyms": self.currency
+        })
+        data = response.get('RAW', {}).get(asset_id, {}).get(self.currency, {})
+        return extract_product(data)
+
+    def get_products(self, asset_ids: list[str]) -> list[ProductInfo]:
+        response = self.__request("/data/pricemultifull", params = {
+            "fsyms": ",".join(asset_ids),
+            "tsyms": self.currency
+        })
+        assets: list[ProductInfo] = []
+        data = response.get('RAW', {})
+        for asset_id in asset_ids:
+            asset_data = data.get(asset_id, {}).get(self.currency, {})
+            assets.append(extract_product(asset_data))
+        return assets
+
+    def get_historical_prices(self, asset_id: str, limit: int = 100) -> list[Price]:
+        response = self.__request("/data/v2/histohour", params = {
+            "fsym": asset_id,
+            "tsym": self.currency,
+            "limit": limit-1 # because the API returns limit+1 items (limit + current)
+        })
+
+        data = response.get('Data', {}).get('Data', [])
+        prices = [extract_price(price_data) for price_data in data]
+        return prices

src/app/api/markets/yfinance.py

@@ -0,0 +1,82 @@
+import json
+from agno.tools.yfinance import YFinanceTools
+from app.api.base.markets import MarketWrapper, ProductInfo, Price
+
+
+def extract_product(stock_data: dict[str, str]) -> ProductInfo:
+    """
+    Converte i dati di YFinanceTools in ProductInfo.
+    """
+    product = ProductInfo()
+    product.id = stock_data.get('Symbol', '')
+    product.symbol = product.id.split('-')[0]  # Rimuovi il suffisso della valuta per le crypto
+    product.price = float(stock_data.get('Current Stock Price', f"0.0 USD").split(" ")[0]) # prende solo il numero
+    product.volume_24h = 0.0 # YFinance non fornisce il volume 24h direttamente
+    product.currency = product.id.split('-')[1]  # La valuta è la parte dopo il '-'
+    return product
+
+def extract_price(hist_data: dict[str, str]) -> Price:
+    """
+    Converte i dati storici di YFinanceTools in Price.
+    """
+    timestamp = int(hist_data.get('Timestamp', '0'))
+
+    price = Price()
+    price.high = float(hist_data.get('High', 0.0))
+    price.low = float(hist_data.get('Low', 0.0))
+    price.open = float(hist_data.get('Open', 0.0))
+    price.close = float(hist_data.get('Close', 0.0))
+    price.volume = float(hist_data.get('Volume', 0.0))
+    price.set_timestamp(timestamp_ms=timestamp)
+    return price
+
+
+class YFinanceWrapper(MarketWrapper):
+    """
+    Wrapper per YFinanceTools che fornisce dati di mercato per azioni, ETF e criptovalute.
+    Implementa l'interfaccia BaseWrapper per compatibilità con il sistema esistente.
+    Usa YFinanceTools dalla libreria agno per coerenza con altri wrapper.
+    """
+
+    def __init__(self, currency: str = "USD"):
+        self.currency = currency
+        self.tool = YFinanceTools()
+
+    def _format_symbol(self, asset_id: str) -> str:
+        """
+        Formatta il simbolo per yfinance.
+        Per crypto, aggiunge '-' e la valuta (es. BTC -> BTC-USD).
+        """
+        asset_id = asset_id.upper()
+        return f"{asset_id}-{self.currency}" if '-' not in asset_id else asset_id
+
+    def get_product(self, asset_id: str) -> ProductInfo:
+        symbol = self._format_symbol(asset_id)
+        stock_info = self.tool.get_company_info(symbol)
+        stock_info = json.loads(stock_info)
+        return extract_product(stock_info)
+
+    def get_products(self, asset_ids: list[str]) -> list[ProductInfo]:
+        products: list[ProductInfo] = []
+        for asset_id in asset_ids:
+            product = self.get_product(asset_id)
+            products.append(product)
+        return products
+
+    def get_historical_prices(self, asset_id: str, limit: int = 100) -> list[Price]:
+        symbol = self._format_symbol(asset_id)
+
+        days = limit // 24 + 1  # Arrotonda per eccesso
+        hist_data = self.tool.get_historical_stock_prices(symbol, period=f"{days}d", interval="1h")
+        hist_data = json.loads(hist_data)
+
+        # Il formato dei dati è {timestamp: {Open: x, High: y, Low: z, Close: w, Volume: v}}
+        timestamps = sorted(hist_data.keys())[-limit:]
+
+        prices: list[Price] = []
+        for timestamp in timestamps:
+            temp = hist_data[timestamp]
+            temp['Timestamp'] = timestamp
+            price = extract_price(temp)
+            prices.append(price)
+        return prices