Merge branch 'main' into 38-news-problem

src/app/api/tools/market_tool.py

@@ -39,38 +39,91 @@ class MarketAPIsTool(MarketWrapper, Toolkit):
         )
 
     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))
+        """
+        Gets product information for a *single* asset from the *first available* provider.
 
+        This method sequentially queries multiple market data sources and returns
+        data from the first one that responds successfully.
+        Use this for a fast, specific lookup of one asset.
+
+        Args:
+            asset_id (str): The ID of the asset to retrieve information for.
+
+        Returns:
+            ProductInfo: An object containing the product information.
+        """
+        return self.handler.try_call(lambda w: w.get_product(asset_id))
+
+    def get_products(self, asset_ids: list[str]) -> list[ProductInfo]:
+        """
+        Gets product information for a *list* of assets from the *first available* provider.
+
+        This method sequentially queries multiple market data sources and returns
+        data from the first one that responds successfully.
+        Use this for a fast lookup of multiple assets.
+
+        Args:
+            asset_ids (list[str]): The list of asset IDs to retrieve information for.
+
+        Returns:
+            list[ProductInfo]: A list of objects containing product information.
+        """
+        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]:
+        """
+        Gets historical price data for a *single* asset from the *first available* provider.
+
+        This method sequentially queries multiple market data sources and returns
+        data from the first one that responds successfully.
+        Use this for a fast lookup of price history.
+
+        Args:
+            asset_id (str): The asset ID to retrieve price data for.
+            limit (int): The maximum number of price data points to return. Defaults to 100.
+
+        Returns:
+            list[Price]: A list of Price objects representing historical data.
+        """
+        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).
+        Gets product information for multiple assets from *all available providers* and *aggregates* the results.
+
+        This method queries all configured sources and then merges the data into a single,
+        comprehensive list. Use this for a complete report.
+        Warning: This may use a large number of API calls.
+
         Args:
-            asset_ids (list[str]): Lista di asset_id da cercare.
+            asset_ids (list[str]): The list of asset IDs to retrieve information for.
+
         Returns:
-            list[ProductInfo]: Lista di ProductInfo aggregati.
+            list[ProductInfo]: A single, aggregated list of ProductInfo objects from all sources.
+
         Raises:
-            Exception: If all wrappers fail to provide results.
+            Exception: If all providers fail to return 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).
+        Gets historical price data for a single asset from *all available providers* and *aggregates* the results.
+
+        This method queries all configured sources and then merges the data into a single,
+        comprehensive list of price points. Use this for a complete historical analysis.
+        Warning: This may use a large number of API calls.
+
         Args:
-            asset_id (str): Asset ID da cercare.
-            limit (int): Numero massimo di dati storici da restituire.
+            asset_id (str): The asset ID to retrieve price data for. Defaults to "BTC".
+            limit (int): The maximum number of price data points to retrieve *from each* provider. Defaults to 100.
+
         Returns:
-            list[Price]: Lista di Price aggregati.
+            list[Price]: A single, aggregated list of Price objects from all sources.
+
         Raises:
-            Exception: If all wrappers fail to provide results.
+            Exception: If all providers fail to return 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/tools/news_tool.py

@@ -41,31 +41,73 @@ class NewsAPIsTool(NewsWrapper, Toolkit):
         )
 
     def get_top_headlines(self, limit: int = 100) -> list[Article]:
+        """
+        Retrieves top headlines from the *first available* news provider.
+
+        This method sequentially queries multiple sources (e.g., Google, DuckDuckGo)
+        and returns results from the first one that responds successfully.
+        Use this for a fast, general overview of the news.
+
+        Args:
+            limit (int): The maximum number of articles to retrieve. Defaults to 100.
+
+        Returns:
+            list[Article]: A list of Article objects from the single successful provider.
+        """
         return self.handler.try_call(lambda w: w.get_top_headlines(limit))
+
     def get_latest_news(self, query: str, limit: int = 100) -> list[Article]:
+        """
+        Searches for the latest news on a specific topic from the *first available* provider.
+
+        This method sequentially queries multiple sources using the query
+        and returns results from the first one that responds successfully.
+        Use this for a fast, specific search.
+
+        Args:
+            query (str): The search topic to find relevant articles.
+            limit (int): The maximum number of articles to retrieve. Defaults to 100.
+
+        Returns:
+            list[Article]: A list of Article objects from the single successful provider.
+        """
         return self.handler.try_call(lambda w: w.get_latest_news(query, limit))
 
     def get_top_headlines_aggregated(self, limit: int = 100) -> dict[str, list[Article]]:
         """
-        Calls get_top_headlines on all wrappers/providers and returns a dictionary mapping their names to their articles.
+        Retrieves top headlines from *all available providers* and aggregates the results.
+
+        This method queries all configured sources and returns a dictionary
+        mapping each provider's name to its list of articles.
+        Use this when you need a comprehensive report or to compare sources.
+
         Args:
-            limit (int): Maximum number of articles to retrieve from each provider.
+            limit (int): The maximum number of articles to retrieve *from each* provider. Defaults to 100.
+
         Returns:
-            dict[str, list[Article]]: A dictionary mapping providers names to their list of Articles
+            dict[str, list[Article]]: A dictionary mapping provider names (str) to their list of Articles.
+
         Raises:
-            Exception: If all wrappers fail to provide results.
+            Exception: If all providers fail to return results.
         """
         return self.handler.try_call_all(lambda w: w.get_top_headlines(limit))
 
     def get_latest_news_aggregated(self, query: str, limit: int = 100) -> dict[str, list[Article]]:
         """
-        Calls get_latest_news on all wrappers/providers and returns a dictionary mapping their names to their articles.
+        Searches for news on a specific topic from *all available providers* and aggregates the results.
+
+        This method queries all configured sources using the query and returns a dictionary
+        mapping each provider's name to its list of articles.
+        Use this when you need a comprehensive report or to compare sources.
+
         Args:
-            query (str): The search query to find relevant news articles.
-            limit (int): Maximum number of articles to retrieve from each provider.
+            query (str): The search topic to find relevant articles.
+            limit (int): The maximum number of articles to retrieve *from each* provider. Defaults to 100.
+
         Returns:
-            dict[str, list[Article]]: A dictionary mapping providers names to their list of Articles
+            dict[str, list[Article]]: A dictionary mapping provider names (str) to their list of Articles.
+
         Raises:
-            Exception: If all wrappers fail to provide results.
+            Exception: If all providers fail to return results.
         """
         return self.handler.try_call_all(lambda w: w.get_latest_news(query, limit))

src/app/api/tools/social_tool.py

@@ -40,16 +40,36 @@ class SocialAPIsTool(SocialWrapper, Toolkit):
         )
 
     def get_top_crypto_posts(self, limit: int = 5) -> list[SocialPost]:
+        """
+        Retrieves top cryptocurrency-related posts from the *first available* social media provider.
+
+        This method sequentially queries multiple sources (e.g., Reddit, X)
+        and returns results from the first one that responds successfully.
+        Use this for a fast, general overview of top social posts.
+
+        Args:
+            limit (int): The maximum number of posts to retrieve. Defaults to 5.
+
+        Returns:
+            list[SocialPost]: A list of SocialPost objects from the single successful provider.
+        """
         return self.handler.try_call(lambda w: w.get_top_crypto_posts(limit))
 
     def get_top_crypto_posts_aggregated(self, limit_per_wrapper: int = 5) -> dict[str, list[SocialPost]]:
         """
-        Calls get_top_crypto_posts on all wrappers/providers and returns a dictionary mapping their names to their posts.
+        Retrieves top cryptocurrency-related posts from *all available providers* and aggregates the results.
+
+        This method queries all configured social media sources and returns a dictionary
+        mapping each provider's name to its list of posts.
+        Use this when you need a comprehensive report or to compare sources.
+
         Args:
-            limit_per_wrapper (int): Maximum number of posts to retrieve from each provider.
+            limit_per_wrapper (int): The maximum number of posts to retrieve *from each* provider. Defaults to 5.
+
         Returns:
-            dict[str, list[SocialPost]]: A dictionary where keys are wrapper names and values are lists of SocialPost objects.
+            dict[str, list[SocialPost]]: A dictionary mapping provider names (str) to their list of SocialPost objects.
+
         Raises:
-            Exception: If all wrappers fail to provide results.
+            Exception: If all providers fail to return results.
         """
         return self.handler.try_call_all(lambda w: w.get_top_crypto_posts(limit_per_wrapper))