diff --git a/src/app/api/tools/instructions/market_instructions.md b/src/app/api/tools/instructions/market_instructions.md index 65ea338..1a7dc77 100644 --- a/src/app/api/tools/instructions/market_instructions.md +++ b/src/app/api/tools/instructions/market_instructions.md @@ -1,94 +1,26 @@ -Market APIs Toolkit - Usage Instructions +# Market APIs - 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. +## Tools (6) +**Single-source (fast):** First available provider +1. `get_product(asset_id)` - Current price, 1 asset +2. `get_products(asset_ids)` - Current prices, multiple assets +3. `get_historical_prices(asset_id, limit=100)` - Price history, 1 asset -AVAILABLE TOOLS (6 total): +**Aggregated (accurate):** All providers, VWAP calculation +4. `get_product_aggregated(asset_id)` - Accurate price, 1 asset (4x API calls) +5. `get_products_aggregated(asset_ids)` - Accurate prices, multiple (4x per asset) +6. `get_historical_prices_aggregated(asset_id, limit=100)` - Historical, all sources (4x calls) -=== SINGLE-SOURCE TOOLS (FAST) === -These tools query providers sequentially and return data from the first one that responds successfully. +## Selection Strategy +- Quick check → single-source (tools 1-3) +- Keywords "accurate", "reliable", "comprehensive" → aggregated (tools 4-6) -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 +## Key Mappings +**Assets:** Bitcoin→BTC, Ethereum→ETH, Solana→SOL, Cardano→ADA, Ripple→XRP, Polkadot→DOT, Dogecoin→DOGE +**Time:** "7 days"→limit=7, "30 days"→limit=30, "24h"→limit=24, "3 months"→limit=90 -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 +## Critical Rules +- Never fabricate data - only report actual tool outputs +- Include: ticker, price+currency, timestamp, provider source +- Failure handling: Report explicit error, no placeholder data +- Be concise to save tokens diff --git a/src/app/api/tools/instructions/news_instructions.md b/src/app/api/tools/instructions/news_instructions.md index e10d515..d05e420 100644 --- a/src/app/api/tools/instructions/news_instructions.md +++ b/src/app/api/tools/instructions/news_instructions.md @@ -1,98 +1,32 @@ -News APIs Toolkit - Usage Instructions +# News APIs - Instructions -OVERVIEW: -This toolkit provides access to cryptocurrency and general news articles from multiple providers (NewsAPI, Google News, CryptoPanic, DuckDuckGo). You can query a single provider for fast results or aggregate data from all providers for comprehensive coverage. +## Tools (4) +**Single-source (fast):** First available provider +1. `get_top_headlines(limit=100)` - Top crypto headlines +2. `get_latest_news(query, limit=100)` - Search specific topic -AVAILABLE TOOLS (4 total): +**Aggregated (comprehensive):** All providers (4x API calls) +3. `get_top_headlines_aggregated(limit=100)` - Headlines from all sources +4. `get_latest_news_aggregated(query, limit=100)` - Topic search, all sources -=== SINGLE-SOURCE TOOLS (FAST) === -These tools query providers sequentially and return data from the first one that responds successfully. +## Selection Strategy +- Quick overview → single-source (tools 1-2) +- Keywords "comprehensive", "all sources", "complete" → aggregated (tools 3-4) -1. get_top_headlines(limit: int = 100) → list[Article] - - Fetches top cryptocurrency headlines from the first available provider - - Example: get_top_headlines(limit=10) - - Use when: User wants a quick overview of current crypto news - - Returns: List of Article objects with title, source, url, published date - -2. get_latest_news(query: str, limit: int = 100) → list[Article] - - Searches for news articles on a specific topic - - Example: get_latest_news("Bitcoin ETF", limit=20) - - Use when: User wants news about a specific topic or event - - Returns: List of Article objects matching the search query - -=== AGGREGATED TOOLS (COMPREHENSIVE) === -These tools query ALL configured providers and return results from each source for maximum coverage. - -3. get_top_headlines_aggregated(limit: int = 100) → dict[str, list[Article]] - - Queries ALL providers for top headlines - - Returns dictionary mapping provider names to their article lists - - Example: get_top_headlines_aggregated(limit=15) - - Use when: User requests "comprehensive", "all sources", or "complete" news coverage - - Warning: Uses 4x API calls (one per provider) - -4. get_latest_news_aggregated(query: str, limit: int = 100) → dict[str, list[Article]] - - Queries ALL providers for news on a specific topic - - Returns dictionary mapping provider names to their article lists - - Example: get_latest_news_aggregated("Ethereum merge", limit=20) - - Use when: User requests detailed research or comprehensive topic coverage - - Warning: Uses 4x API calls - -TOOL SELECTION STRATEGY: -- "What's the latest crypto news?" → get_top_headlines(limit=10) [tool #1] -- "Find news about Bitcoin" → get_latest_news("Bitcoin", limit=20) [tool #2] -- "Get all sources for crypto news" → get_top_headlines_aggregated(limit=10) [tool #3] -- "Research Ethereum from all sources" → get_latest_news_aggregated("Ethereum", limit=15) [tool #4] - -QUERY FORMULATION: -When users ask about specific topics, construct clear search queries: +## Query Formulation - "Bitcoin regulation" → query="Bitcoin regulation" - "ETH price surge" → query="Ethereum price increase" -- "Crypto market crash" → query="cryptocurrency market crash" -- "NFT trends" → query="NFT trends" -- "DeFi security" → query="DeFi security vulnerabilities" +- Use full crypto names (Bitcoin not BTC), specific keywords for focus -ARTICLE STRUCTURE: -Each Article object typically contains: -- title: Article headline -- source: Publication/website name -- url: Link to full article -- published_at: Publication timestamp -- description: Article summary (when available) -- author: Article author (when available) +## Article Structure +Contains: title, source, url, published_at, description (optional), author (optional) -LIMIT GUIDELINES: -- Quick overview: limit=5-10 -- Standard news scan: limit=20-30 -- Deep research: limit=50-100 -- Each provider respects the limit independently in aggregated mode +## Limits +- Quick: 5-10 | Standard: 20-30 | Deep: 50-100 -CRITICAL RULES: -1. NEVER fabricate news articles or headlines - only report actual tool outputs -2. ALL articles returned by tools are REAL and from actual news sources -3. ALWAYS include article source and publication date when available -4. ALWAYS include article URLs so users can verify information -5. If tools fail, report the failure explicitly - DO NOT invent placeholder articles -6. In aggregated results, clearly separate articles by provider - -ERROR HANDLING: -- All providers fail → Report "News data unavailable from all sources" -- Partial data → Report available articles and note which sources failed -- No results for query → Report "No news articles found for '[QUERY]'. Try broader terms" -- API rate limits → Try single-source tools instead of aggregated tools - -OUTPUT REQUIREMENTS: -- Include article title (required) -- Include source/publication name (required) -- Include URL for verification (required) -- Include publication date/time when available -- Provide brief summary/description when available -- Group articles by source in aggregated mode -- Be concise to save tokens - focus on headlines and key info -- Deduplicate articles when same story appears from multiple sources - -SEARCH BEST PRACTICES: -- Use specific keywords for focused results -- Use broader terms if no results found -- Include cryptocurrency names in full (Bitcoin not just BTC) -- Consider alternative spellings or synonyms -- Avoid overly technical jargon in queries +## Critical Rules +- Never fabricate articles - only report actual tool outputs +- Always include: title, source, URL, publication date +- Failure handling: Report explicit error, suggest broader terms +- Deduplicate same stories across sources +- Be concise to save tokens diff --git a/src/app/api/tools/instructions/plan_memory_instructions.md b/src/app/api/tools/instructions/plan_memory_instructions.md index 959b7bc..811b67e 100644 --- a/src/app/api/tools/instructions/plan_memory_instructions.md +++ b/src/app/api/tools/instructions/plan_memory_instructions.md @@ -1,305 +1,64 @@ -# Plan Memory Tool - Usage Instructions +# Plan Memory Tool - Instructions -## OVERVIEW -This toolkit provides stateful, persistent memory for the Team Leader agent. It functions as your primary to-do list and state tracker, enabling you to create, execute step-by-step, and record the results of your execution plan. +## Purpose +Stateful task management for Team Leader: create, track, and record execution plans with persistent state. -## PURPOSE -- **Task Management**: Create and track execution plans with multiple steps -- **State Persistence**: Maintain execution state across multiple agent calls -- **Progress Tracking**: Monitor which tasks are pending, completed, or failed -- **Result Recording**: Store outcomes and results for each executed task +## Tools (4) -## AVAILABLE TOOLS (4 total) +### 1. `add_tasks(task_names: list[str])` → str +Adds tasks with 'pending' status. Prevents duplicates. Returns: "Added N new tasks." -### 1. **add_tasks(task_names: list[str])** → str -Adds one or more new tasks to the execution plan with 'pending' status. +**Best Practices:** +- Clear, descriptive names (e.g., "Fetch BTC price for last 7 days" not "Get data") +- Order logically (dependencies first) +- Include specific details in names -**Behavior:** -- If a task with the same name already exists, it will NOT be added again (prevents duplicates) -- All new tasks start with status='pending' and result=None -- Tasks are added to the end of the task list +### 2. `get_next_pending_task()` → Task | None +Returns FIRST pending task (FIFO order) or None if no pending tasks. -**Arguments:** -- `task_names` (list[str]): List of descriptive names for tasks to add +**Task Object:** `{name: str, status: "pending", result: None}` -**Returns:** -- Confirmation message: "Added N new tasks." +### 3. `update_task_status(task_name, status, result)` → str +Updates task after execution. Status: "completed" or "failed". Result: optional outcome/error. -**Example Usage:** +**Example:** ```python -add_tasks([ - "Fetch Bitcoin price data", - "Analyze market sentiment from news", - "Retrieve social media discussions", - "Generate comprehensive report" -]) -# Returns: "Added 4 new tasks." +update_task_status("Fetch BTC price", "completed", "BTC=$67,543 at 14:23:00") +update_task_status("Analyze sentiment", "failed", "API rate limit exceeded") ``` **Best Practices:** -- Use clear, descriptive task names that explain what needs to be done -- Break complex operations into smaller, manageable tasks -- Order tasks logically (dependencies first) -- Include specific details in task names (e.g., "Fetch BTC price for last 7 days" not "Get price") - ---- - -### 2. **get_next_pending_task()** → Task | None -Retrieves the FIRST task from the plan that has 'pending' status. - -**Behavior:** -- Returns tasks in the order they were added (FIFO - First In, First Out) -- Only returns tasks with status='pending' -- Returns None if no pending tasks exist - -**Returns:** -- Task object (dict) with keys: - - `name` (str): Task name - - `status` (str): Always "pending" when returned by this function - - `result` (str | None): Always None for pending tasks -- None if no pending tasks - -**Example Usage:** -```python -next_task = get_next_pending_task() -if next_task: - print(f"Next task to execute: {next_task['name']}") -else: - print("All tasks completed or no tasks in plan") -``` - -**Workflow Pattern:** -1. Call `get_next_pending_task()` to get next task -2. Execute the task using appropriate specialist agent/tool -3. Call `update_task_status()` with results -4. Repeat until `get_next_pending_task()` returns None - ---- - -### 3. **update_task_status(task_name: str, status: Literal["completed", "failed"], result: str | None)** → str -Updates the status and result of a specific task after execution. - -**Arguments:** -- `task_name` (str): Exact name of the task (must match name from add_tasks) -- `status` (str): New status - either "completed" or "failed" -- `result` (str | None): Optional description of outcome, error message, or summary - -**Returns:** -- Success: "Task 'Task Name' updated to {status}." -- Error: "Error: Task 'Task Name' not found." - -**Example Usage:** -```python -# After successfully executing a task: -update_task_status( - task_name="Fetch Bitcoin price data", - status="completed", - result="Retrieved BTC price: $67,543 from Binance at 2025-10-30 14:23:00" -) - -# After task failure: -update_task_status( - task_name="Analyze market sentiment", - status="failed", - result="Error: News API rate limit exceeded. Unable to fetch articles." -) -``` - -**Best Practices:** -- Always update status immediately after task execution -- Provide meaningful results that can be referenced later +- Update immediately after execution - Include key data in result (prices, counts, timestamps) -- For failures, include error details for debugging -- Keep results concise but informative +- For failures, include error details ---- +### 4. `list_all_tasks()` → list[str] +Lists all tasks with status and results. Format: "- {name}: {status} (Result: {result})" -### 4. **list_all_tasks()** → list[str] -Lists all tasks in the execution plan with their status and results. - -**Returns:** -- List of formatted strings, each describing one task -- Format: "- {task_name}: {status} (Result: {result})" -- Returns ["No tasks in the plan."] if task list is empty - -**Example Output:** -``` -[ - "- Fetch Bitcoin price data: completed (Result: BTC=$67,543 at 14:23:00)", - "- Analyze market sentiment: completed (Result: Bullish sentiment, 15 articles)", - "- Retrieve social media posts: pending (Result: N/A)", - "- Generate report: pending (Result: N/A)" -] -``` - -**Use Cases:** -- Review overall plan progress -- Check which tasks remain pending -- Retrieve results from completed tasks -- Debug failed tasks -- Provide status updates to user - ---- - -## WORKFLOW PATTERNS - -### **Pattern 1: Simple Sequential Execution** +## Workflow Pattern ```python -# Step 1: Create plan add_tasks(["Task A", "Task B", "Task C"]) - -# Step 2: Execute loop -while True: - task = get_next_pending_task() - if not task: - break - - # Execute task... - result = execute_task(task['name']) - - # Update status +while task := get_next_pending_task(): + result = execute(task['name']) update_task_status(task['name'], "completed", result) - -# Step 3: Review results all_tasks = list_all_tasks() ``` -### **Pattern 2: Conditional Execution** -```python -add_tasks(["Fetch data", "Analyze if data available", "Generate report"]) +## Critical Rules +1. Task names must be unique (exact match for updates) +2. Always update status after execution +3. Execute sequentially using get_next_pending_task() +4. Store meaningful results, not just "Done" +5. Handle failures: update status="failed" and continue +6. Review with list_all_tasks() before finishing -task = get_next_pending_task() -result = fetch_data() +## Good vs Poor Examples +**Good Task Names:** "Fetch BTC price from Binance for 7 days" | "Analyze Ethereum news sentiment" +**Poor Task Names:** "Get data" | "Step 1" | "Do analysis" -if result is None: - update_task_status("Fetch data", "failed", "No data available") - # Skip remaining tasks or add alternative tasks -else: - update_task_status("Fetch data", "completed", result) - # Continue to next task -``` +**Good Results:** "BTC: $67,543 (Binance, 2025-10-30 14:23)" | "15 articles, Bullish sentiment" +**Poor Results:** "Done" | "Success" | "OK" -### **Pattern 3: Dynamic Task Addition** -```python -add_tasks(["Check user request type"]) - -task = get_next_pending_task() -request_type = analyze_request() - -if request_type == "comprehensive": - # Add detailed tasks for comprehensive analysis - add_tasks([ - "Fetch from all providers", - "Aggregate results", - "Perform cross-validation" - ]) -else: - # Add simple tasks for quick lookup - add_tasks(["Fetch from single provider"]) - -update_task_status("Check user request type", "completed", f"Type: {request_type}") -``` - ---- - -## CRITICAL RULES - -1. **Task Names Must Be Unique**: Don't add duplicate task names - they will be ignored -2. **Exact Name Matching**: When updating status, task_name must EXACTLY match the name used in add_tasks -3. **Update After Execution**: ALWAYS call update_task_status after executing a task -4. **Sequential Execution**: Execute tasks in order using get_next_pending_task() -5. **Meaningful Results**: Store actionable information in results, not just "Done" or "Success" -6. **Handle Failures**: Don't stop plan execution when a task fails - update status and continue or adapt plan -7. **Review Before Finishing**: Call list_all_tasks() before completing user request to verify all tasks executed - ---- - -## TASK NAMING BEST PRACTICES - -**Good Task Names:** -- ✅ "Fetch BTC price from Binance for last 7 days" -- ✅ "Analyze news sentiment for Ethereum" -- ✅ "Retrieve Reddit posts about DeFi (limit=10)" -- ✅ "Calculate VWAP from aggregated provider data" -- ✅ "Generate comparison report for BTC vs ETH" - -**Poor Task Names:** -- ❌ "Get data" (too vague) -- ❌ "Step 1" (not descriptive) -- ❌ "Do analysis" (what kind of analysis?) -- ❌ "Fetch" (fetch what?) - ---- - -## RESULT CONTENT GUIDELINES - -**Good Results:** -- ✅ "BTC price: $67,543 (Binance, 2025-10-30 14:23:00)" -- ✅ "Analyzed 15 articles. Sentiment: Bullish. Key theme: ETF approval" -- ✅ "Retrieved 10 Reddit posts. Avg upvotes: 234. Trend: Positive on BTC" -- ✅ "Aggregated 3 providers: Binance, Coinbase, YFinance. VWAP: $67,521" - -**Poor Results:** -- ❌ "Done" -- ❌ "Success" -- ❌ "OK" -- ❌ "Completed successfully" - ---- - -## ERROR HANDLING - -**Common Errors:** -1. **Task Not Found**: Task name doesn't match exactly - - Solution: Check spelling, capitalization, and spacing - -2. **No Pending Tasks**: get_next_pending_task() returns None - - Solution: Verify tasks were added, check if all are completed/failed - -3. **Duplicate Task Names**: Task not added because name exists - - Solution: Use unique, descriptive names or update existing task - -**Recovery Strategies:** -- If specialist agent fails, mark task as "failed" with error details -- Add alternative tasks to work around failures -- Continue execution with remaining tasks -- Provide partial results if some tasks completed - ---- - -## INTEGRATION WITH SPECIALIST AGENTS - -When delegating to specialist agents (Market, News, Social), follow this pattern: - -```python -# 1. Create plan -add_tasks([ - "Fetch market data for BTC", - "Analyze news sentiment", - "Check social media trends" -]) - -# 2. Execute market task -task = get_next_pending_task() -# Delegate to Market Specialist... -market_result = market_agent.get_product("BTC") -update_task_status(task['name'], "completed", f"BTC Price: ${market_result.price}") - -# 3. Execute news task -task = get_next_pending_task() -# Delegate to News Specialist... -news_result = news_agent.get_latest_news("Bitcoin", limit=20) -update_task_status(task['name'], "completed", f"Found {len(news_result)} articles") - -# And so on... -``` - ---- - -## STATE PERSISTENCE - -**Important Notes:** -- Task state persists within a single agent session/conversation -- State is NOT persisted across different sessions or restarts -- If agent is reset, all tasks are lost -- For long-running operations, periodically call list_all_tasks() to preserve progress in conversation context +## State Persistence +- Persists within single session only (not across restarts) +- Call list_all_tasks() periodically to preserve context diff --git a/src/app/api/tools/instructions/social_instructions.md b/src/app/api/tools/instructions/social_instructions.md index 8675d38..0e5cf78 100644 --- a/src/app/api/tools/instructions/social_instructions.md +++ b/src/app/api/tools/instructions/social_instructions.md @@ -1,103 +1,39 @@ -Social Media Toolkit - Usage Instructions +# Social Media APIs - Instructions -OVERVIEW: -This toolkit provides access to cryptocurrency-related social media posts from multiple platforms (Reddit, X/Twitter, 4chan). You can query a single platform for fast results or aggregate data from all platforms for comprehensive social sentiment analysis. +## Tools (2) +**Single-source (fast):** First available platform +1. `get_top_crypto_posts(limit=5)` - Top crypto posts, first platform -AVAILABLE TOOLS (2 total): +**Aggregated (comprehensive):** All platforms (3x API calls: Reddit, X, 4chan) +2. `get_top_crypto_posts_aggregated(limit_per_wrapper=5)` - Posts from all platforms -=== SINGLE-SOURCE TOOLS (FAST) === -These tools query platforms sequentially and return data from the first one that responds successfully. +## Selection Strategy +- Quick snapshot → single-source (tool 1) +- Keywords "all platforms", "comprehensive", "compare" → aggregated (tool 2) -1. get_top_crypto_posts(limit: int = 5) → list[SocialPost] - - Fetches top cryptocurrency-related posts from the first available platform - - Example: get_top_crypto_posts(limit=10) - - Use when: User wants a quick snapshot of social media sentiment - - Returns: List of SocialPost objects with content, author, engagement metrics - - Default limit is intentionally small (5) due to post length +## Post Structure +Contains: content, author, platform, url, created_at, score/upvotes, comments_count, subreddit/board -=== AGGREGATED TOOLS (COMPREHENSIVE) === -These tools query ALL configured platforms and return results from each source for complete social coverage. +## Limits (posts are verbose) +- Quick: 5 (default) | Standard: 10-15 | Deep: 20-30 | Max: 50 -2. get_top_crypto_posts_aggregated(limit_per_wrapper: int = 5) → dict[str, list[SocialPost]] - - Queries ALL platforms for top crypto posts - - Returns dictionary mapping platform names to their post lists - - Example: get_top_crypto_posts_aggregated(limit_per_wrapper=10) - - Use when: User requests "all platforms", "comprehensive", or "complete" social analysis - - Warning: Uses 3x API calls (one per platform: Reddit, X, 4chan) +## Platform Notes +- **Reddit:** r/cryptocurrency, r/bitcoin, r/ethereum (upvotes metric) +- **X (Twitter):** High engagement crypto tweets (likes metric) +- **4chan:** /biz/ board (replies metric, may contain inappropriate language) -TOOL SELECTION STRATEGY: -- "What's trending in crypto on social media?" → get_top_crypto_posts(limit=10) [tool #1] -- "Show top crypto posts" → get_top_crypto_posts(limit=5) [tool #1] -- "Get crypto sentiment from all platforms" → get_top_crypto_posts_aggregated(limit_per_wrapper=10) [tool #2] -- "Compare Reddit and Twitter crypto posts" → get_top_crypto_posts_aggregated(limit_per_wrapper=15) [tool #2] +## Critical Rules +- Never fabricate posts - only report actual tool outputs +- Include: platform, author, URL, engagement metrics, timestamp +- Truncate content to max 280 chars +- Summarize sentiment trends, don't list all posts verbatim +- Frame as opinions, not facts - add disclaimers for unverified info +- Be VERY concise to save tokens -SOCIALPOST STRUCTURE: -Each SocialPost object typically contains: -- content: Post text/message -- author: Username/handle of poster -- platform: Source platform (Reddit, X, 4chan) -- url: Link to original post -- created_at: Post timestamp -- score/upvotes: Engagement metric (platform-dependent) -- comments_count: Number of comments/replies -- subreddit/board: Specific community (Reddit/4chan) - -LIMIT GUIDELINES: -Social media posts are longer than news headlines, so use smaller limits: -- Quick snapshot: limit=5 (default) -- Standard overview: limit=10-15 -- Deep analysis: limit=20-30 -- Maximum recommended: limit=50 (to avoid token overflow) - -PLATFORM-SPECIFIC NOTES: -- Reddit: Posts from r/cryptocurrency, r/bitcoin, r/ethereum and similar subreddits -- X (Twitter): Crypto-related tweets with high engagement -- 4chan: Posts from /biz/ board focused on crypto discussions -- Each platform has different engagement metrics (upvotes, likes, replies) - -CRITICAL RULES: -1. NEVER fabricate social media posts - only report actual tool outputs -2. ALL posts returned by tools are REAL from actual users -3. ALWAYS include platform source and author information -4. ALWAYS include post URLs for verification -5. Be aware of potential misinformation in social media content -6. If tools fail, report the failure explicitly - DO NOT invent placeholder posts -7. In aggregated results, clearly separate posts by platform -8. Social media reflects opinions, not facts - frame accordingly - -ERROR HANDLING: -- All platforms fail → Report "Social media data unavailable from all sources" -- Partial data → Report available posts and note which platforms failed -- No crypto posts found → Report "No cryptocurrency posts available at this time" -- API rate limits → Try single-source tool or reduce limit - -OUTPUT REQUIREMENTS: -- Include post content (truncate if too long, max 280 chars recommended) -- Include author/username (required) -- Include platform name (required) -- Include engagement metrics (upvotes, likes, comments) -- Include post URL for verification -- Include timestamp/date when available -- Group posts by platform in aggregated mode -- Summarize sentiment trends rather than listing all posts verbatim -- Be VERY concise to save tokens - social posts are verbose - -SENTIMENT ANALYSIS TIPS: -- Look for recurring topics across posts -- Note positive vs negative sentiment patterns -- Identify trending coins or topics -- Compare sentiment across platforms -- Highlight posts with high engagement -- Flag potential FUD (Fear, Uncertainty, Doubt) or shilling - -CONTENT WARNINGS: -- Social media may contain: - - Unverified information - - Speculation and rumors - - Promotional/shilling content - - Strong opinions or biased views - - Inappropriate language (especially 4chan) -- Always present social data with appropriate disclaimers +## Sentiment Analysis +- Identify recurring topics, positive/negative patterns, trending coins +- Compare sentiment across platforms, highlight high engagement +- Flag potential FUD or shilling - Do not treat social media posts as factual evidence - Encourage users to verify information from official sources diff --git a/src/app/api/tools/instructions/symbols_instructions.md b/src/app/api/tools/instructions/symbols_instructions.md index 80a7be0..74aa31d 100644 --- a/src/app/api/tools/instructions/symbols_instructions.md +++ b/src/app/api/tools/instructions/symbols_instructions.md @@ -1,352 +1,97 @@ -# Crypto Symbols Tool - Usage Instructions +# Crypto Symbols Tool - Instructions -## OVERVIEW -This toolkit provides access to cryptocurrency symbol lookup and search functionality. It maintains a cached database of cryptocurrency symbols from Yahoo Finance, enabling fast symbol resolution and name-based searches. +## Purpose +Cryptocurrency symbol lookup and name-based search using cached Yahoo Finance database. -## PURPOSE -- **Symbol Lookup**: Get complete list of available cryptocurrency symbols -- **Name Search**: Find cryptocurrency symbols by searching their names -- **Symbol Resolution**: Convert common names to trading symbols for use with market data APIs -- **Cache Management**: Maintains local cache for fast queries without repeated API calls +## Tools (2) -## AVAILABLE TOOLS (2 total) +### 1. `get_all_symbols()` → list[str] +Returns all available cryptocurrency symbols from cache. No API calls, instant response. -### 1. **get_all_symbols()** → list[str] -Returns a complete list of all cryptocurrency symbols available in the cached database. - -**Behavior:** -- Returns all symbols from the local cache (CSV file) -- No API calls - instant response -- Returns empty list if cache is not populated - -**Returns:** -- `list[str]`: List of cryptocurrency symbols (e.g., ["BTC-USD", "ETH-USD", "SOL-USD", ...]) - -**Example Usage:** -```python -all_symbols = get_all_symbols() -print(f"Total cryptocurrencies available: {len(all_symbols)}") -# Output: Total cryptocurrencies available: 1523 - -# Check if specific symbol exists -if "BTC-USD" in all_symbols: - print("Bitcoin is available") -``` +**Returns:** List like `["BTC-USD", "ETH-USD", "SOL-USD", ...]` (~1,500+ symbols) **Use Cases:** -- Verify if a cryptocurrency is supported before fetching data -- Get complete list of available assets for comprehensive analysis +- Verify symbol availability before API call +- List all supported cryptocurrencies - Validate user input against known symbols -- Browse all available cryptocurrencies -**Important Notes:** -- Symbols include suffix (e.g., "BTC-USD" not just "BTC") -- Cache must be populated first (happens automatically on initialization if cache file exists) -- Returns snapshot from last cache update, not real-time availability +### 2. `get_symbols_by_name(query: str)` → list[tuple[str, str]] +Searches cryptocurrency names (case-insensitive, substring match). Returns list of (symbol, name) tuples. ---- - -### 2. **get_symbols_by_name(query: str)** → list[tuple[str, str]] -Searches for cryptocurrency symbols whose names contain the query string (case-insensitive). - -**Arguments:** -- `query` (str): Search term to match against cryptocurrency names - -**Returns:** -- `list[tuple[str, str]]`: List of (symbol, name) tuples matching the query -- Returns empty list if no matches found - -**Example Usage:** +**Examples:** ```python -# Search for Bitcoin-related cryptocurrencies -results = get_symbols_by_name("bitcoin") -# Returns: [("BTC-USD", "Bitcoin USD"), ("BTT-USD", "Bitcoin Token USD"), ...] - -# Search for Ethereum -results = get_symbols_by_name("ethereum") -# Returns: [("ETH-USD", "Ethereum USD"), ("ETC-USD", "Ethereum Classic USD"), ...] - -# Partial name search -results = get_symbols_by_name("doge") -# Returns: [("DOGE-USD", "Dogecoin USD"), ...] - -# Check if found -if results: - symbol, name = results[0] - print(f"Found: {name} with symbol {symbol}") -else: - print("No cryptocurrencies found matching query") +get_symbols_by_name("bitcoin") # [("BTC-USD", "Bitcoin USD"), ("BCH-USD", "Bitcoin Cash USD"), ...] +get_symbols_by_name("ethereum") # [("ETH-USD", "Ethereum USD"), ("ETC-USD", "Ethereum Classic USD")] +get_symbols_by_name("doge") # [("DOGE-USD", "Dogecoin USD")] ``` -**Search Behavior:** -- Case-insensitive matching -- Partial match (substring search) -- Searches only in the "Name" field, not symbols -- Returns all matches, not just the first one - **Use Cases:** -- Convert user-friendly names to trading symbols -- Handle ambiguous user input ("bitcoin" → multiple results including Bitcoin, Bitcoin Cash, etc.) +- Convert user-friendly names to symbols +- Handle ambiguous input (multiple matches) - Discover cryptocurrencies by partial name -- Validate and suggest corrections for misspelled names -**Best Practices:** -- Use full or near-full names for precise matches -- Handle multiple results - ask user to clarify if ambiguous -- Always check if results list is empty before accessing -- Display both symbol and name to user for confirmation +## Workflow Patterns ---- - -## SYMBOL FORMAT - -**Yahoo Finance Symbol Format:** -- All symbols include currency suffix: `-USD` -- Example: `BTC-USD`, `ETH-USD`, `SOL-USD` - -**Common Conversions:** -``` -User Input → Search Query → Symbol Result -"Bitcoin" → "bitcoin" → "BTC-USD" -"Ethereum" → "ethereum" → "ETH-USD" -"Solana" → "solana" → "SOL-USD" -"Cardano" → "cardano" → "ADA-USD" -"Dogecoin" → "dogecoin" → "DOGE-USD" -``` - -**When Using Symbols with Market APIs:** -- Some APIs require just the base symbol: `BTC`, `ETH` -- Some APIs require the full Yahoo format: `BTC-USD` -- Check individual market API documentation for required format -- You may need to strip the `-USD` suffix: `symbol.split('-')[0]` - ---- - -## CACHE MANAGEMENT - -**Cache File Location:** -- Default: `resources/cryptos.csv` -- Contains: Symbol, Name, and other metadata columns - -**Cache Initialization:** -- Cache loaded automatically on tool initialization if file exists -- If cache file doesn't exist, `get_all_symbols()` returns empty list -- Cache can be refreshed using `fetch_crypto_symbols(force_refresh=True)` (admin function) - -**Cache Contents:** -- Approximately 1,500+ cryptocurrency symbols -- Includes major coins (BTC, ETH, SOL) and smaller altcoins -- Updated periodically from Yahoo Finance - -**Performance:** -- All queries are **instant** - no API calls during normal use -- Cache lookup is O(1) for get_all_symbols -- Search is O(n) for get_symbols_by_name but very fast for ~1,500 entries - ---- - -## WORKFLOW PATTERNS - -### **Pattern 1: Symbol Validation** +### Pattern 1: Symbol Validation ```python -# User asks for "Bitcoin" price -user_query = "bitcoin" - -# Search for matching symbols matches = get_symbols_by_name(user_query) - -if not matches: - # No matches found - return "Cryptocurrency not found. Please check the name." -elif len(matches) == 1: - # Single match - proceed - symbol, name = matches[0] - # Use symbol with market API: market_tool.get_product(symbol) -else: - # Multiple matches - ask user to clarify - options = "\n".join([f"- {name} ({symbol})" for symbol, name in matches]) - return f"Multiple matches found:\n{options}\nPlease specify which one." -``` - -### **Pattern 2: Symbol Discovery** -```python -# User asks "What coins are available?" -all_symbols = get_all_symbols() -total_count = len(all_symbols) - -# Show sample or summary -top_10 = all_symbols[:10] -return f"There are {total_count} cryptocurrencies available. Top 10: {', '.join(top_10)}" -``` - -### **Pattern 3: Fuzzy Matching** -```python -# User types "etherium" (misspelled) -query = "etherium" -matches = get_symbols_by_name(query) - -if not matches: - # Try alternative spellings - alternatives = ["ethereum", "ether"] - for alt in alternatives: - matches = get_symbols_by_name(alt) - if matches: - return f"Did you mean {matches[0][1]}? (Symbol: {matches[0][0]})" - return "No matches found" -else: - # Found matches - return matches -``` - -### **Pattern 4: Batch Symbol Resolution** -```python -# User asks for multiple cryptocurrencies -user_requests = ["Bitcoin", "Ethereum", "Solana", "UnknownCoin"] -resolved_symbols = [] -failed = [] - -for name in user_requests: - matches = get_symbols_by_name(name.lower()) - if matches: - resolved_symbols.append(matches[0][0]) # Take first match - else: - failed.append(name) - -# Now use resolved_symbols with market API -if resolved_symbols: - prices = market_tool.get_products(resolved_symbols) - -if failed: - print(f"Warning: Could not find symbols for: {', '.join(failed)}") -``` - ---- - -## INTEGRATION WITH MARKET TOOLS - -**Typical Workflow:** -1. User provides cryptocurrency name (e.g., "Bitcoin", "Ethereum") -2. Use `get_symbols_by_name()` to find matching symbol -3. Pass symbol to Market Tool APIs (get_product, get_products, etc.) -4. Return price data to user - -**Example Integration:** -```python -# Step 1: User request -user_input = "Get Bitcoin price" - -# Step 2: Extract cryptocurrency name and search -crypto_name = "bitcoin" # Extracted from user_input -matches = get_symbols_by_name(crypto_name) - if not matches: return "Cryptocurrency not found" - -symbol, full_name = matches[0] - -# Step 3: Fetch price data -price_data = market_tool.get_product(symbol) - -# Step 4: Return result -return f"{full_name} ({symbol}): ${price_data.price}" +elif len(matches) == 1: + symbol, name = matches[0] + # Use with market API +else: + # Multiple matches - ask user to clarify + return f"Multiple matches: {[name for _, name in matches]}" ``` ---- +### Pattern 2: Batch Resolution +```python +names = ["Bitcoin", "Ethereum", "UnknownCoin"] +resolved = [] +failed = [] +for name in names: + matches = get_symbols_by_name(name.lower()) + if matches: + resolved.append(matches[0][0]) + else: + failed.append(name) +# Use resolved with market_tool.get_products(resolved) +``` -## CRITICAL RULES +## Integration with Market Tools +1. User provides name (e.g., "Bitcoin") +2. Search: `get_symbols_by_name("bitcoin")` → `("BTC-USD", "Bitcoin USD")` +3. Fetch price: `market_tool.get_product("BTC-USD")` +4. Return result -1. **Always Search Before Using Names**: Never assume a name directly converts to a symbol -2. **Handle Multiple Matches**: Names like "Bitcoin" might match multiple cryptocurrencies -3. **Case-Insensitive Search**: Always use lowercase for query consistency -4. **Check Empty Results**: Always verify search results before accessing -5. **Symbol Format**: Remember Yahoo symbols have `-USD` suffix -6. **Cache Dependency**: Tools require cache to be populated (usually automatic) +## Symbol Format +- Yahoo Finance format: `BTC-USD`, `ETH-USD` (includes `-USD` suffix) +- Some APIs need base only: strip suffix with `symbol.split('-')[0]` → `"BTC"` ---- +## Common Mappings +Bitcoin→BTC-USD | Ethereum→ETH-USD | Solana→SOL-USD | Cardano→ADA-USD | Dogecoin→DOGE-USD -## COMMON USE CASES +## Critical Rules +1. Always search before using names - never assume direct conversion +2. Handle multiple matches (e.g., "Bitcoin" matches BTC and BCH) +3. Case-insensitive: always use `.lower()` for queries +4. Check empty results before accessing +5. Remember `-USD` suffix in Yahoo symbols -### **Use Case 1: Name to Symbol Conversion** -User says: "What's the price of Cardano?" -1. Search: `get_symbols_by_name("cardano")` -2. Get symbol: `"ADA-USD"` -3. Fetch price: `market_tool.get_product("ADA-USD")` +## Search Best Practices +- ✅ Full names: "ethereum", "bitcoin", "solana" +- ✅ Partial OK: "doge" finds "Dogecoin" +- ❌ Avoid: ticker symbols ("BTC"), too generic ("coin") -### **Use Case 2: Symbol Verification** -User provides: "BTC-USD" -1. Check: `"BTC-USD" in get_all_symbols()` -2. If True, proceed with API call -3. If False, suggest similar names +## Cache Notes +- Cache file: `resources/cryptos.csv` (~1,500+ symbols) +- No API calls during queries (instant response) +- Loaded automatically on initialization +- Static snapshot, not real-time -### **Use Case 3: Discovery** -User asks: "What cryptos start with 'Sol'?" -1. Search: `get_symbols_by_name("sol")` -2. Return all matches (Solana, etc.) - -### **Use Case 4: Ambiguity Resolution** -User says: "Bitcoin" -1. Search: `get_symbols_by_name("bitcoin")` -2. Results: `[("BTC-USD", "Bitcoin USD"), ("BCH-USD", "Bitcoin Cash USD"), ...]` -3. Ask user: "Did you mean Bitcoin (BTC) or Bitcoin Cash (BCH)?" - ---- - -## ERROR HANDLING - -**Common Issues:** - -1. **Empty Cache** - - Symptom: `get_all_symbols()` returns empty list - - Cause: Cache file missing or not loaded - - Solution: Ensure `resources/cryptos.csv` exists - -2. **No Search Results** - - Symptom: `get_symbols_by_name()` returns empty list - - Cause: Query doesn't match any cryptocurrency names - - Solution: Try broader search terms, check spelling, suggest alternatives - -3. **Multiple Matches** - - Symptom: Search returns many results - - Cause: Query is too broad (e.g., "coin") - - Solution: Ask user to be more specific, show all matches - -4. **Symbol Format Mismatch** - - Symptom: Market API fails with Yahoo symbol - - Cause: API expects different format - - Solution: Strip suffix: `symbol.split('-')[0]` → `"BTC-USD"` becomes `"BTC"` - ---- - -## SEARCH TIPS - -**Effective Searches:** -- ✅ Use full names: "ethereum", "bitcoin", "solana" -- ✅ Use common names: "ether" finds "Ethereum" -- ✅ Partial names work: "doge" finds "Dogecoin" - -**Ineffective Searches:** -- ❌ Ticker symbols: "BTC" (search by name, not symbol) -- ❌ Too generic: "coin", "token" (returns too many results) -- ❌ Abbreviations: "eth" might not match "Ethereum" (try full name) - -**Best Practice:** -If user provides a ticker symbol (BTC, ETH), first check if it exists in `get_all_symbols()`, then try name search as fallback. - ---- - -## PERFORMANCE NOTES - -- **get_all_symbols()**: O(1) - Instant -- **get_symbols_by_name()**: O(n) - Fast (< 1ms for ~1,500 entries) -- **No Network Calls**: All data served from local cache -- **Memory Efficient**: CSV loaded once on initialization - ---- - -## LIMITATIONS - -1. **Yahoo Finance Dependency**: Symbol list limited to what Yahoo Finance provides -2. **No Real-Time Updates**: Cache is static snapshot, not live data -3. **Name Matching Only**: Cannot search by symbol, market cap, or other criteria -4. **USD Pairs Only**: Only symbols with `-USD` suffix are included -5. **No Metadata**: Only symbol and name available, no price, volume, or market cap in this tool +## Error Handling +- Empty cache → Ensure `resources/cryptos.csv` exists +- No results → Try broader terms, check spelling +- Multiple matches → Show all, ask user to clarify +- Symbol format mismatch → Strip `-USD` suffix if needed