Berack/upo-app-agents
0
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

Added Prompt for tools #68

Merged
Simo93-rgb merged 5 commits from 64-prompt-for-tools into main 2025-10-31 00:13:02 +01:00
Conversation 4 Commits 5 Files Changed 17 +180 -874
5 changed files with 180 additions and 874 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit b755387050 - Show all commits

110
src/app/api/tools/instructions/market_instructions.md
View File

@@ -1,94 +1,26 @@
Market APIs Toolkit - Usage Instructions # Market APIs - Instructions
OVERVIEW: ## Tools (6)
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. **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) === ## Selection Strategy
These tools query providers sequentially and return data from the first one that responds successfully. - Quick check → single-source (tools 1-3)
- Keywords "accurate", "reliable", "comprehensive" → aggregated (tools 4-6)
1. get_product(asset_id: str) → ProductInfo ## Key Mappings
- Fetches current price for ONE asset **Assets:** Bitcoin→BTC, Ethereum→ETH, Solana→SOL, Cardano→ADA, Ripple→XRP, Polkadot→DOT, Dogecoin→DOGE
- Example: get_product("BTC") **Time:** "7 days"→limit=7, "30 days"→limit=30, "24h"→limit=24, "3 months"→limit=90
- Use when: User wants a quick price check for a single asset
2. get_products(asset_ids: list[str]) → list[ProductInfo] ## Critical Rules
- Fetches current prices for MULTIPLE assets - Never fabricate data - only report actual tool outputs
- Example: get_products(["BTC", "ETH", "SOL"]) - Include: ticker, price+currency, timestamp, provider source
- Use when: User wants quick prices for multiple assets - Failure handling: Report explicit error, no placeholder data
- Be concise to save tokens
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

112
src/app/api/tools/instructions/news_instructions.md
View File

@@ -1,98 +1,32 @@
News APIs Toolkit - Usage Instructions # News APIs - Instructions
OVERVIEW: ## Tools (4)
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. **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) === ## Selection Strategy
These tools query providers sequentially and return data from the first one that responds successfully. - 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] ## Query Formulation
- 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:
- "Bitcoin regulation" → query="Bitcoin regulation" - "Bitcoin regulation" → query="Bitcoin regulation"
- "ETH price surge" → query="Ethereum price increase" - "ETH price surge" → query="Ethereum price increase"
- "Crypto market crash" → query="cryptocurrency market crash" - Use full crypto names (Bitcoin not BTC), specific keywords for focus
- "NFT trends" → query="NFT trends"
- "DeFi security" → query="DeFi security vulnerabilities"
ARTICLE STRUCTURE: ## Article Structure
Each Article object typically contains: Contains: title, source, url, published_at, description (optional), author (optional)
- 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)
LIMIT GUIDELINES: ## Limits
- Quick overview: limit=5-10 - Quick: 5-10 | Standard: 20-30 | Deep: 50-100
- Standard news scan: limit=20-30
- Deep research: limit=50-100
- Each provider respects the limit independently in aggregated mode
CRITICAL RULES: ## Critical Rules
1. NEVER fabricate news articles or headlines - only report actual tool outputs - Never fabricate articles - only report actual tool outputs
2. ALL articles returned by tools are REAL and from actual news sources - Always include: title, source, URL, publication date
3. ALWAYS include article source and publication date when available - Failure handling: Report explicit error, suggest broader terms
4. ALWAYS include article URLs so users can verify information - Deduplicate same stories across sources
5. If tools fail, report the failure explicitly - DO NOT invent placeholder articles - Be concise to save tokens
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

321
src/app/api/tools/instructions/plan_memory_instructions.md
View File

@@ -1,305 +1,64 @@
# Plan Memory Tool - Usage Instructions # Plan Memory Tool - Instructions
## OVERVIEW ## Purpose
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. Stateful task management for Team Leader: create, track, and record execution plans with persistent state.
## PURPOSE ## Tools (4)
- **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
## 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 **Best Practices:**
Adds one or more new tasks to the execution plan with 'pending' status. - 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:** ### 2. `get_next_pending_task()` → Task | None
- If a task with the same name already exists, it will NOT be added again (prevents duplicates) Returns FIRST pending task (FIFO order) or None if no pending tasks.
- All new tasks start with status='pending' and result=None
- Tasks are added to the end of the task list
**Arguments:** **Task Object:** `{name: str, status: "pending", result: None}`
- `task_names` (list[str]): List of descriptive names for tasks to add
**Returns:** ### 3. `update_task_status(task_name, status, result)` → str
- Confirmation message: "Added N new tasks." Updates task after execution. Status: "completed" or "failed". Result: optional outcome/error.
**Example Usage:** **Example:**
```python ```python
add_tasks([ update_task_status("Fetch BTC price", "completed", "BTC=$67,543 at 14:23:00")
"Fetch Bitcoin price data", update_task_status("Analyze sentiment", "failed", "API rate limit exceeded")
"Analyze market sentiment from news",
"Retrieve social media discussions",
"Generate comprehensive report"
])
# Returns: "Added 4 new tasks."
``` ```
**Best Practices:** **Best Practices:**
- Use clear, descriptive task names that explain what needs to be done - Update immediately after execution
- 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
- Include key data in result (prices, counts, timestamps) - Include key data in result (prices, counts, timestamps)
- For failures, include error details for debugging - For failures, include error details
- Keep results concise but informative
--- ### 4. `list_all_tasks()` → list[str]
Lists all tasks with status and results. Format: "- {name}: {status} (Result: {result})"
### 4. **list_all_tasks()** → list[str] ## Workflow Pattern
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**
```python ```python
# Step 1: Create plan
add_tasks(["Task A", "Task B", "Task C"]) add_tasks(["Task A", "Task B", "Task C"])
while task := get_next_pending_task():
# Step 2: Execute loop result = execute(task['name'])
while True:
task = get_next_pending_task()
if not task:
break
# Execute task...
result = execute_task(task['name'])
# Update status
update_task_status(task['name'], "completed", result) update_task_status(task['name'], "completed", result)
# Step 3: Review results
all_tasks = list_all_tasks() all_tasks = list_all_tasks()
``` ```
### **Pattern 2: Conditional Execution** ## Critical Rules
```python 1. Task names must be unique (exact match for updates)
add_tasks(["Fetch data", "Analyze if data available", "Generate report"]) 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() ## Good vs Poor Examples
result = fetch_data() **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: **Good Results:** "BTC: $67,543 (Binance, 2025-10-30 14:23)" | "15 articles, Bullish sentiment"
update_task_status("Fetch data", "failed", "No data available") **Poor Results:** "Done" | "Success" | "OK"
# Skip remaining tasks or add alternative tasks
else:
update_task_status("Fetch data", "completed", result)
# Continue to next task
```
### **Pattern 3: Dynamic Task Addition** ## State Persistence
```python - Persists within single session only (not across restarts)
add_tasks(["Check user request type"]) - Call list_all_tasks() periodically to preserve context
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

120
src/app/api/tools/instructions/social_instructions.md
View File

@@ -1,103 +1,39 @@
Social Media Toolkit - Usage Instructions # Social Media APIs - Instructions
OVERVIEW: ## Tools (2)
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. **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) === ## Selection Strategy
These tools query platforms sequentially and return data from the first one that responds successfully. - Quick snapshot → single-source (tool 1)
- Keywords "all platforms", "comprehensive", "compare" → aggregated (tool 2)
1. get_top_crypto_posts(limit: int = 5) → list[SocialPost] ## Post Structure
- Fetches top cryptocurrency-related posts from the first available platform Contains: content, author, platform, url, created_at, score/upvotes, comments_count, subreddit/board
- 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
=== AGGREGATED TOOLS (COMPREHENSIVE) === ## Limits (posts are verbose)
These tools query ALL configured platforms and return results from each source for complete social coverage. - 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]] ## Platform Notes
- Queries ALL platforms for top crypto posts - **Reddit:** r/cryptocurrency, r/bitcoin, r/ethereum (upvotes metric)
- Returns dictionary mapping platform names to their post lists - **X (Twitter):** High engagement crypto tweets (likes metric)
- Example: get_top_crypto_posts_aggregated(limit_per_wrapper=10) - **4chan:** /biz/ board (replies metric, may contain inappropriate language)
- Use when: User requests "all platforms", "comprehensive", or "complete" social analysis
- Warning: Uses 3x API calls (one per platform: Reddit, X, 4chan)
TOOL SELECTION STRATEGY: ## Critical Rules
- "What's trending in crypto on social media?" → get_top_crypto_posts(limit=10) [tool #1] - Never fabricate posts - only report actual tool outputs
- "Show top crypto posts" → get_top_crypto_posts(limit=5) [tool #1] - Include: platform, author, URL, engagement metrics, timestamp
- "Get crypto sentiment from all platforms" → get_top_crypto_posts_aggregated(limit_per_wrapper=10) [tool #2] - Truncate content to max 280 chars
- "Compare Reddit and Twitter crypto posts" → get_top_crypto_posts_aggregated(limit_per_wrapper=15) [tool #2] - 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: ## Sentiment Analysis
Each SocialPost object typically contains: - Identify recurring topics, positive/negative patterns, trending coins
- content: Post text/message - Compare sentiment across platforms, highlight high engagement
- author: Username/handle of poster - Flag potential FUD or shilling
- 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
- Do not treat social media posts as factual evidence - Do not treat social media posts as factual evidence
- Encourage users to verify information from official sources - Encourage users to verify information from official sources

391
src/app/api/tools/instructions/symbols_instructions.md
View File

@@ -1,352 +1,97 @@
# Crypto Symbols Tool - Usage Instructions # Crypto Symbols Tool - Instructions
## OVERVIEW ## Purpose
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. Cryptocurrency symbol lookup and name-based search using cached Yahoo Finance database.
## PURPOSE ## Tools (2)
- **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
## 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:** List like `["BTC-USD", "ETH-USD", "SOL-USD", ...]` (~1,500+ symbols)
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")
```
**Use Cases:** **Use Cases:**
- Verify if a cryptocurrency is supported before fetching data - Verify symbol availability before API call
- Get complete list of available assets for comprehensive analysis - List all supported cryptocurrencies
- Validate user input against known symbols - Validate user input against known symbols
- Browse all available cryptocurrencies
**Important Notes:** ### 2. `get_symbols_by_name(query: str)` → list[tuple[str, str]]
- Symbols include suffix (e.g., "BTC-USD" not just "BTC") Searches cryptocurrency names (case-insensitive, substring match). Returns list of (symbol, name) tuples.
- Cache must be populated first (happens automatically on initialization if cache file exists)
- Returns snapshot from last cache update, not real-time availability
--- **Examples:**
### 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:**
```python ```python
# Search for Bitcoin-related cryptocurrencies get_symbols_by_name("bitcoin") # [("BTC-USD", "Bitcoin USD"), ("BCH-USD", "Bitcoin Cash USD"), ...]
results = get_symbols_by_name("bitcoin") get_symbols_by_name("ethereum") # [("ETH-USD", "Ethereum USD"), ("ETC-USD", "Ethereum Classic USD")]
# Returns: [("BTC-USD", "Bitcoin USD"), ("BTT-USD", "Bitcoin Token USD"), ...] get_symbols_by_name("doge") # [("DOGE-USD", "Dogecoin 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")
``` ```
**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:** **Use Cases:**
- Convert user-friendly names to trading symbols - Convert user-friendly names to symbols
- Handle ambiguous user input ("bitcoin" → multiple results including Bitcoin, Bitcoin Cash, etc.) - Handle ambiguous input (multiple matches)
- Discover cryptocurrencies by partial name - Discover cryptocurrencies by partial name
- Validate and suggest corrections for misspelled names
**Best Practices:** ## Workflow Patterns
- 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
--- ### Pattern 1: Symbol Validation
## 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**
```python ```python
# User asks for "Bitcoin" price
user_query = "bitcoin"
# Search for matching symbols
matches = get_symbols_by_name(user_query) 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: if not matches:
return "Cryptocurrency not found" return "Cryptocurrency not found"
elif len(matches) == 1:
symbol, full_name = matches[0] symbol, name = matches[0]
# Use with market API
# Step 3: Fetch price data else:
price_data = market_tool.get_product(symbol) # Multiple matches - ask user to clarify
return f"Multiple matches: {[name for _, name in matches]}"
# Step 4: Return result
return f"{full_name} ({symbol}): ${price_data.price}"
``` ```
--- ### 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 ## Symbol Format
2. **Handle Multiple Matches**: Names like "Bitcoin" might match multiple cryptocurrencies - Yahoo Finance format: `BTC-USD`, `ETH-USD` (includes `-USD` suffix)
3. **Case-Insensitive Search**: Always use lowercase for query consistency - Some APIs need base only: strip suffix with `symbol.split('-')[0]` → `"BTC"`
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)
--- ## 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** ## Search Best Practices
User says: "What's the price of Cardano?" - ✅ Full names: "ethereum", "bitcoin", "solana"
1. Search: `get_symbols_by_name("cardano")` - ✅ Partial OK: "doge" finds "Dogecoin"
2. Get symbol: `"ADA-USD"` - ❌ Avoid: ticker symbols ("BTC"), too generic ("coin")
3. Fetch price: `market_tool.get_product("ADA-USD")`
### **Use Case 2: Symbol Verification** ## Cache Notes
User provides: "BTC-USD" - Cache file: `resources/cryptos.csv` (~1,500+ symbols)
1. Check: `"BTC-USD" in get_all_symbols()` - No API calls during queries (instant response)
2. If True, proceed with API call - Loaded automatically on initialization
3. If False, suggest similar names - Static snapshot, not real-time
### **Use Case 3: Discovery** ## Error Handling
User asks: "What cryptos start with 'Sol'?" - Empty cache → Ensure `resources/cryptos.csv` exists
1. Search: `get_symbols_by_name("sol")` - No results → Try broader terms, check spelling
2. Return all matches (Solana, etc.) - Multiple matches → Show all, ask user to clarify
- Symbol format mismatch → Strip `-USD` suffix if needed
### **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