From 0a69dcbacecef66e94bce64933e6a897b3ba9359 Mon Sep 17 00:00:00 2001 From: Simone Garau <20005068@studenti.uniupo.it> Date: Thu, 30 Oct 2025 13:21:59 +0100 Subject: [PATCH] feat: add external instructions file for Market APIs Toolkit - Created market_instructions.txt with detailed tool usage guidelines - Added _load_instructions() method to load instructions from external file - Updated MarketAPIsTool to use external instructions parameter - Improves maintainability by separating instructions from code --- .../instructions/market_instructions.txt | 94 +++++++++++++++++++ src/app/api/tools/market_tool.py | 13 +++ 2 files changed, 107 insertions(+) create mode 100644 src/app/api/tools/instructions/market_instructions.txt diff --git a/src/app/api/tools/instructions/market_instructions.txt b/src/app/api/tools/instructions/market_instructions.txt new file mode 100644 index 0000000..65ea338 --- /dev/null +++ b/src/app/api/tools/instructions/market_instructions.txt @@ -0,0 +1,94 @@ +Market APIs Toolkit - Usage Instructions + +OVERVIEW: +This toolkit provides access to real-time and historical cryptocurrency price data from multiple providers (Binance, YFinance, Coinbase, CryptoCompare). You can query a single provider for fast results or aggregate data from all providers for more reliable insights. + +AVAILABLE TOOLS (6 total): + +=== SINGLE-SOURCE TOOLS (FAST) === +These tools query providers sequentially and return data from the first one that responds successfully. + +1. get_product(asset_id: str) → ProductInfo + - Fetches current price for ONE asset + - Example: get_product("BTC") + - Use when: User wants a quick price check for a single asset + +2. get_products(asset_ids: list[str]) → list[ProductInfo] + - Fetches current prices for MULTIPLE assets + - Example: get_products(["BTC", "ETH", "SOL"]) + - Use when: User wants quick prices for multiple assets + +3. get_historical_prices(asset_id: str, limit: int = 100) → list[Price] + - Fetches historical price data for ONE asset + - Example: get_historical_prices("BTC", limit=30) + - Use when: User wants price history (7 days → limit=7, 30 days → limit=30) + +=== AGGREGATED TOOLS (COMPREHENSIVE) === +These tools query ALL configured providers and merge results using volume-weighted averaging (VWAP) for maximum reliability. + +4. get_product_aggregated(asset_id: str) → ProductInfo + - Queries ALL providers for ONE asset and aggregates results + - Returns most accurate price using VWAP calculation + - Example: get_product_aggregated("BTC") + - Use when: User requests "accurate", "reliable", or "comprehensive" single asset data + - Warning: Uses 4x API calls (one per provider) + +5. get_products_aggregated(asset_ids: list[str]) → list[ProductInfo] + - Queries ALL providers for MULTIPLE assets and aggregates results + - Returns comprehensive dataset with confidence scores + - Example: get_products_aggregated(["BTC", "ETH"]) + - Use when: User requests "detailed" or "comprehensive" multi-asset analysis + - Warning: Uses 4x API calls per asset + +6. get_historical_prices_aggregated(asset_id: str = "BTC", limit: int = 100) → list[Price] + - Queries ALL providers for historical data and aggregates results + - Returns complete historical dataset from multiple sources + - Example: get_historical_prices_aggregated("BTC", limit=50) + - Use when: User requests comprehensive historical analysis + - Warning: Uses 4x API calls + +TOOL SELECTION STRATEGY: +- "What's BTC price?" → get_product("BTC") [tool #1] +- "Get accurate BTC price" → get_product_aggregated("BTC") [tool #4] +- "Compare BTC, ETH, SOL" → get_products(["BTC", "ETH", "SOL"]) [tool #2] +- "Detailed analysis of BTC and ETH" → get_products_aggregated(["BTC", "ETH"]) [tool #5] +- "BTC price last week" → get_historical_prices("BTC", limit=7) [tool #3] +- "Comprehensive BTC history" → get_historical_prices_aggregated("BTC", limit=30) [tool #6] + +ASSET ID CONVERSION: +Always convert common names to ticker symbols: +- Bitcoin → BTC +- Ethereum → ETH +- Solana → SOL +- Cardano → ADA +- Ripple → XRP +- Polkadot → DOT +- Dogecoin → DOGE + +TIME RANGE INTERPRETATION: +- "last 7 days" / "past week" → limit=7 +- "last 30 days" / "past month" → limit=30 +- "last 24 hours" / "today" → limit=24 (if hourly) or limit=1 (if daily) +- "last 3 months" → limit=90 + +CRITICAL RULES: +1. NEVER fabricate prices or data - only report actual tool outputs +2. ALL data returned by tools is REAL-TIME and authoritative +3. ALWAYS include timestamps with price data +4. ALWAYS specify the data source (which provider(s) returned the data) +5. If tools fail, report the failure explicitly - DO NOT invent placeholder data +6. The 'provider' field in aggregated results shows which sources were used + +ERROR HANDLING: +- All providers fail → Report "Price data unavailable from all sources" +- Partial data → Report what was retrieved and note missing portions +- Invalid asset → Report "Unable to find price data for [ASSET]. Check ticker symbol" +- API rate limits → Try single-source tools instead of aggregated tools + +OUTPUT REQUIREMENTS: +- Include asset ticker symbol +- Include current price with currency (usually USD) +- Include timestamp (when the data was retrieved) +- Include source/provider information +- For historical data: include date range and data point count +- Be concise to save tokens - provide essential data only diff --git a/src/app/api/tools/market_tool.py b/src/app/api/tools/market_tool.py index 649f9d4..7b0e7b2 100644 --- a/src/app/api/tools/market_tool.py +++ b/src/app/api/tools/market_tool.py @@ -1,3 +1,4 @@ +from pathlib import Path from agno.tools import Toolkit from app.api.wrapper_handler import WrapperHandler from app.api.core.markets import MarketWrapper, Price, ProductInfo @@ -12,6 +13,17 @@ class MarketAPIsTool(MarketWrapper, Toolkit): Providers can be configured in configs.yaml under api.market_providers. """ + @staticmethod + def _load_instructions() -> str: + """ + Load the toolkit instructions from the external text file. + + Returns: + str: The content of the instructions file. + """ + instructions_path = Path(__file__).parent / "instructions" / "market_instructions.txt" + return instructions_path.read_text(encoding="utf-8") + def __init__(self): """ Initialize the MarketAPIsTool with market API wrappers configured in configs.yaml. @@ -36,6 +48,7 @@ class MarketAPIsTool(MarketWrapper, Toolkit): self.get_products_aggregated, self.get_historical_prices_aggregated, ], + instructions=self._load_instructions(), ) def get_product(self, asset_id: str) -> ProductInfo: