From 1f0ee6950cfe6551a874ef550d87ef9b2b64b6d7 Mon Sep 17 00:00:00 2001 From: Kye Gomez Date: Mon, 2 Jun 2025 01:02:43 -0700 Subject: [PATCH] tool docs --- docs/mkdocs.yml | 37 +- docs/swarms/tools/tools_examples.md | 600 +++++++++++++++++++++++++++ docs/swarms_cloud/create_api.md | 204 --------- docs/swarms_cloud/getting_started.md | 94 ----- example.py | 39 +- pyproject.toml | 2 +- swarms/structs/swarm_router.py | 15 +- swarms/utils/litellm_tokenizer.py | 108 ++++- 8 files changed, 760 insertions(+), 339 deletions(-) create mode 100644 docs/swarms/tools/tools_examples.md delete mode 100644 docs/swarms_cloud/create_api.md delete mode 100644 docs/swarms_cloud/getting_started.md diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 27146996..129c4eda 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -199,8 +199,7 @@ nav: - What are tools?: "swarms/tools/build_tool.md" - Structured Outputs: "swarms/agents/structured_outputs.md" - Agent MCP Integration: "swarms/structs/agent_mcp.md" - - ToolAgent: "swarms/agents/tool_agent.md" - - Tool Storage: "swarms/tools/tool_storage.md" + - Comprehensive Tool Guide with MCP, Callables, and more: "swarms/tools/tools_examples.md" - RAG || Long Term Memory: - Integrating RAG with Agents: "swarms/memory/diy_memory.md" - Third-Party Agent Integrations: @@ -279,8 +278,8 @@ nav: - Faiss: "swarms_memory/faiss.md" - Deployment Solutions: - - Deploying Swarms on Google Cloud Run: "swarms_cloud/cloud_run.md" - - Phala Deployment: "swarms_cloud/phala_deploy.md" + - Deploy your Swarms on Google Cloud Run: "swarms_cloud/cloud_run.md" + - Deploy your Swarms on Phala: "swarms_cloud/phala_deploy.md" - About Us: - Swarms Vision: "swarms/concept/vision.md" @@ -303,11 +302,6 @@ nav: - Swarms 5.9.2: "swarms/changelog/changelog_new.md" - Examples: - - Overview: "swarms/examples/unique_swarms.md" - - Swarms API Examples: - - Medical Swarm: "swarms/examples/swarms_api_medical.md" - - Finance Swarm: "swarms/examples/swarms_api_finance.md" - - ML Model Code Generation Swarm: "swarms/examples/swarms_api_ml_model.md" - Individal LLM Examples: - OpenAI: "swarms/examples/openai_example.md" - Anthropic: "swarms/examples/claude.md" @@ -319,17 +313,17 @@ nav: - XAI: "swarms/examples/xai.md" - VLLM: "swarms/examples/vllm_integration.md" - Llama4: "swarms/examples/llama4.md" - - Swarms Tools: - - Agent with Yahoo Finance: "swarms/examples/yahoo_finance.md" - - Twitter Agents: "swarms_tools/twitter.md" - - Blockchain Agents: - - Agent with HTX + CoinGecko: "swarms/examples/swarms_tools_htx.md" - - Agent with HTX + CoinGecko Function Calling: "swarms/examples/swarms_tools_htx_gecko.md" - - Lumo: "swarms/examples/lumo.md" - - Quant Crypto Agent: "swarms/examples/quant_crypto_agent.md" - - Meme Agents: - - Bob The Builder: "swarms/examples/bob_the_builder.md" + + - Swarms Tools: + - Agent with Yahoo Finance: "swarms/examples/yahoo_finance.md" + - Twitter Agents: "swarms_tools/twitter.md" + - Blockchain Agents: + - Agent with HTX + CoinGecko: "swarms/examples/swarms_tools_htx.md" + - Agent with HTX + CoinGecko Function Calling: "swarms/examples/swarms_tools_htx_gecko.md" + - Lumo: "swarms/examples/lumo.md" + - Quant Crypto Agent: "swarms/examples/quant_crypto_agent.md" - Multi-Agent Collaboration: + - Unique Swarms: "swarms/examples/unique_swarms.md" - Swarms DAO: "swarms/examples/swarms_dao.md" - Hybrid Hierarchical-Cluster Swarm Example: "swarms/examples/hhcs_examples.md" - Group Chat Example: "swarms/examples/groupchat_example.md" @@ -338,6 +332,11 @@ nav: - ConcurrentWorkflow with VLLM Agents: "swarms/examples/vllm.md" - External Agents: - Swarms of Browser Agents: "swarms/examples/swarms_of_browser_agents.md" + + - Swarms API Examples: + - Medical Swarm: "swarms/examples/swarms_api_medical.md" + - Finance Swarm: "swarms/examples/swarms_api_finance.md" + - ML Model Code Generation Swarm: "swarms/examples/swarms_api_ml_model.md" - Swarms UI: - Overview: "swarms/ui/main.md" diff --git a/docs/swarms/tools/tools_examples.md b/docs/swarms/tools/tools_examples.md new file mode 100644 index 00000000..bbbb799c --- /dev/null +++ b/docs/swarms/tools/tools_examples.md @@ -0,0 +1,600 @@ +# Swarms Tools Documentation + +Swarms provides a comprehensive toolkit for integrating various types of tools into your AI agents. This guide covers all available tool options including callable functions, MCP servers, schemas, and more. + +## Installation + +```bash +pip install swarms +``` + +## Overview + +Swarms provides a comprehensive suite of tool integration methods to enhance your AI agents' capabilities: + +| Tool Type | Description | +|-----------|-------------| +| **Callable Functions** | Direct integration of Python functions with proper type hints and comprehensive docstrings for immediate tool functionality | +| **MCP Servers** | Model Context Protocol servers enabling distributed tool functionality across multiple services and environments | +| **Tool Schemas** | Structured tool definitions that provide standardized interfaces and validation for tool integration | +| **Tool Collections** | Pre-built tool packages offering ready-to-use functionality for common use cases | + +--- + +## Method 1: Callable Functions + +Callable functions are the simplest way to add tools to your Swarms agents. They are regular Python functions with type hints and comprehensive docstrings. + +### Step 1: Define Your Tool Functions + +Create functions with the following requirements: + +- **Type hints** for all parameters and return values + +- **Comprehensive docstrings** with Args, Returns, Raises, and Examples sections + +- **Error handling** for robust operation + +#### Example: Cryptocurrency Price Tools + +```python +import json +import requests +from swarms import Agent + + +def get_coin_price(coin_id: str, vs_currency: str = "usd") -> str: + """ + Get the current price of a specific cryptocurrency. + + Args: + coin_id (str): The CoinGecko ID of the cryptocurrency + Examples: 'bitcoin', 'ethereum', 'cardano' + vs_currency (str, optional): The target currency for price conversion. + Supported: 'usd', 'eur', 'gbp', 'jpy', etc. + Defaults to "usd". + + Returns: + str: JSON formatted string containing the coin's current price and market data + including market cap, 24h volume, and price changes + + Raises: + requests.RequestException: If the API request fails due to network issues + ValueError: If coin_id is empty or invalid + TimeoutError: If the request takes longer than 10 seconds + + Example: + >>> result = get_coin_price("bitcoin", "usd") + >>> print(result) + {"bitcoin": {"usd": 45000, "usd_market_cap": 850000000000, ...}} + + >>> result = get_coin_price("ethereum", "eur") + >>> print(result) + {"ethereum": {"eur": 3200, "eur_market_cap": 384000000000, ...}} + """ + try: + # Validate input parameters + if not coin_id or not coin_id.strip(): + raise ValueError("coin_id cannot be empty") + + url = "https://api.coingecko.com/api/v3/simple/price" + params = { + "ids": coin_id.lower().strip(), + "vs_currencies": vs_currency.lower(), + "include_market_cap": True, + "include_24hr_vol": True, + "include_24hr_change": True, + "include_last_updated_at": True, + } + + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() + + data = response.json() + + # Check if the coin was found + if not data: + return json.dumps({ + "error": f"Cryptocurrency '{coin_id}' not found. Please check the coin ID." + }) + + return json.dumps(data, indent=2) + + except requests.RequestException as e: + return json.dumps({ + "error": f"Failed to fetch price for {coin_id}: {str(e)}", + "suggestion": "Check your internet connection and try again" + }) + except ValueError as e: + return json.dumps({"error": str(e)}) + except Exception as e: + return json.dumps({"error": f"Unexpected error: {str(e)}"}) + + +def get_top_cryptocurrencies(limit: int = 10, vs_currency: str = "usd") -> str: + """ + Fetch the top cryptocurrencies by market capitalization. + + Args: + limit (int, optional): Number of coins to retrieve. + Range: 1-250 coins + Defaults to 10. + vs_currency (str, optional): The target currency for price conversion. + Supported: 'usd', 'eur', 'gbp', 'jpy', etc. + Defaults to "usd". + + Returns: + str: JSON formatted string containing top cryptocurrencies with detailed market data + including: id, symbol, name, current_price, market_cap, market_cap_rank, + total_volume, price_change_24h, price_change_7d, last_updated + + Raises: + requests.RequestException: If the API request fails + ValueError: If limit is not between 1 and 250 + + Example: + >>> result = get_top_cryptocurrencies(5, "usd") + >>> print(result) + [{"id": "bitcoin", "name": "Bitcoin", "current_price": 45000, ...}] + + >>> result = get_top_cryptocurrencies(limit=3, vs_currency="eur") + >>> print(result) + [{"id": "bitcoin", "name": "Bitcoin", "current_price": 38000, ...}] + """ + try: + # Validate parameters + if not isinstance(limit, int) or not 1 <= limit <= 250: + raise ValueError("Limit must be an integer between 1 and 250") + + url = "https://api.coingecko.com/api/v3/coins/markets" + params = { + "vs_currency": vs_currency.lower(), + "order": "market_cap_desc", + "per_page": limit, + "page": 1, + "sparkline": False, + "price_change_percentage": "24h,7d", + } + + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() + + data = response.json() + + # Simplify and structure the data for better readability + simplified_data = [] + for coin in data: + simplified_data.append({ + "id": coin.get("id"), + "symbol": coin.get("symbol", "").upper(), + "name": coin.get("name"), + "current_price": coin.get("current_price"), + "market_cap": coin.get("market_cap"), + "market_cap_rank": coin.get("market_cap_rank"), + "total_volume": coin.get("total_volume"), + "price_change_24h": round(coin.get("price_change_percentage_24h", 0), 2), + "price_change_7d": round(coin.get("price_change_percentage_7d_in_currency", 0), 2), + "last_updated": coin.get("last_updated"), + }) + + return json.dumps(simplified_data, indent=2) + + except (requests.RequestException, ValueError) as e: + return json.dumps({ + "error": f"Failed to fetch top cryptocurrencies: {str(e)}" + }) + except Exception as e: + return json.dumps({"error": f"Unexpected error: {str(e)}"}) + + +def search_cryptocurrencies(query: str) -> str: + """ + Search for cryptocurrencies by name or symbol. + + Args: + query (str): The search term (coin name or symbol) + Examples: 'bitcoin', 'btc', 'ethereum', 'eth' + Case-insensitive search + + Returns: + str: JSON formatted string containing search results with coin details + including: id, name, symbol, market_cap_rank, thumb (icon URL) + Limited to top 10 results for performance + + Raises: + requests.RequestException: If the API request fails + ValueError: If query is empty + + Example: + >>> result = search_cryptocurrencies("ethereum") + >>> print(result) + {"coins": [{"id": "ethereum", "name": "Ethereum", "symbol": "eth", ...}]} + + >>> result = search_cryptocurrencies("btc") + >>> print(result) + {"coins": [{"id": "bitcoin", "name": "Bitcoin", "symbol": "btc", ...}]} + """ + try: + # Validate input + if not query or not query.strip(): + raise ValueError("Search query cannot be empty") + + url = "https://api.coingecko.com/api/v3/search" + params = {"query": query.strip()} + + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() + + data = response.json() + + # Extract and format the results + coins = data.get("coins", [])[:10] # Limit to top 10 results + + result = { + "coins": coins, + "query": query, + "total_results": len(data.get("coins", [])), + "showing": min(len(coins), 10) + } + + return json.dumps(result, indent=2) + + except requests.RequestException as e: + return json.dumps({ + "error": f'Failed to search for "{query}": {str(e)}' + }) + except ValueError as e: + return json.dumps({"error": str(e)}) + except Exception as e: + return json.dumps({"error": f"Unexpected error: {str(e)}"}) +``` + +### Step 2: Configure Your Agent + +Create an agent with the following key parameters: + +```python +# Initialize the agent with cryptocurrency tools +agent = Agent( + agent_name="Financial-Analysis-Agent", # Unique identifier for your agent + agent_description="Personal finance advisor agent with cryptocurrency market analysis capabilities", + system_prompt="""You are a personal finance advisor agent with access to real-time + cryptocurrency data from CoinGecko. You can help users analyze market trends, check + coin prices, find trending cryptocurrencies, and search for specific coins. Always + provide accurate, up-to-date information and explain market data in an easy-to-understand way.""", + max_loops=1, # Number of reasoning loops + max_tokens=4096, # Maximum response length + model_name="anthropic/claude-3-opus-20240229", # LLM model to use + dynamic_temperature_enabled=True, # Enable adaptive creativity + output_type="all", # Return complete response + tools=[ # List of callable functions + get_coin_price, + get_top_cryptocurrencies, + search_cryptocurrencies, + ], +) +``` + +### Step 3: Use Your Agent + +```python +# Example usage with different queries +response = agent.run("What are the top 5 cryptocurrencies by market cap?") +print(response) + +# Query with specific parameters +response = agent.run("Get the current price of Bitcoin and Ethereum in EUR") +print(response) + +# Search functionality +response = agent.run("Search for cryptocurrencies related to 'cardano'") +print(response) +``` + +--- + +## Method 2: MCP (Model Context Protocol) Servers + +MCP servers provide a standardized way to create distributed tool functionality. They're ideal for: +- **Reusable tools** across multiple agents +- **Complex tool logic** that needs isolation +- **Third-party tool integration** +- **Scalable architectures** + +### Step 1: Create Your MCP Server + +```python +from mcp.server.fastmcp import FastMCP +import requests + +# Initialize the MCP server with configuration +mcp = FastMCP("OKXCryptoPrice") # Server name for identification +mcp.settings.port = 8001 # Port for server communication +``` + +### Step 2: Define MCP Tools + +Each MCP tool requires the `@mcp.tool` decorator with specific parameters: + +```python +@mcp.tool( + name="get_okx_crypto_price", # Tool identifier (must be unique) + description="Get the current price and basic information for a given cryptocurrency from OKX exchange.", +) +def get_okx_crypto_price(symbol: str) -> str: + """ + Get the current price and basic information for a given cryptocurrency using OKX API. + + Args: + symbol (str): The cryptocurrency trading pair + Format: 'BASE-QUOTE' (e.g., 'BTC-USDT', 'ETH-USDT') + If only base currency provided, '-USDT' will be appended + Case-insensitive input + + Returns: + str: A formatted string containing: + - Current price in USDT + - 24-hour price change percentage + - Formatted for human readability + + Raises: + requests.RequestException: If the OKX API request fails + ValueError: If symbol format is invalid + ConnectionError: If unable to connect to OKX servers + + Example: + >>> get_okx_crypto_price('BTC-USDT') + 'Current price of BTC/USDT: $45,000.00\n24h Change: +2.34%' + + >>> get_okx_crypto_price('eth') # Automatically converts to ETH-USDT + 'Current price of ETH/USDT: $3,200.50\n24h Change: -1.23%' + """ + try: + # Input validation and formatting + if not symbol or not symbol.strip(): + return "Error: Please provide a valid trading pair (e.g., 'BTC-USDT')" + + # Normalize symbol format + symbol = symbol.upper().strip() + if not symbol.endswith("-USDT"): + symbol = f"{symbol}-USDT" + + # OKX API endpoint for ticker information + url = f"https://www.okx.com/api/v5/market/ticker?instId={symbol}" + + # Make the API request with timeout + response = requests.get(url, timeout=10) + response.raise_for_status() + + data = response.json() + + # Check API response status + if data.get("code") != "0": + return f"Error: {data.get('msg', 'Unknown error from OKX API')}" + + # Extract ticker data + ticker_data = data.get("data", [{}])[0] + if not ticker_data: + return f"Error: Could not find data for {symbol}. Please verify the trading pair exists." + + # Parse numerical data + price = float(ticker_data.get("last", 0)) + change_percent = float(ticker_data.get("change24h", 0)) * 100 # Convert to percentage + + # Format response + base_currency = symbol.split("-")[0] + change_symbol = "+" if change_percent >= 0 else "" + + return (f"Current price of {base_currency}/USDT: ${price:,.2f}\n" + f"24h Change: {change_symbol}{change_percent:.2f}%") + + except requests.exceptions.Timeout: + return "Error: Request timed out. OKX servers may be slow." + except requests.exceptions.RequestException as e: + return f"Error fetching OKX data: {str(e)}" + except (ValueError, KeyError) as e: + return f"Error parsing OKX response: {str(e)}" + except Exception as e: + return f"Unexpected error: {str(e)}" + + +@mcp.tool( + name="get_okx_crypto_volume", # Second tool with different functionality + description="Get the 24-hour trading volume for a given cryptocurrency from OKX exchange.", +) +def get_okx_crypto_volume(symbol: str) -> str: + """ + Get the 24-hour trading volume for a given cryptocurrency using OKX API. + + Args: + symbol (str): The cryptocurrency trading pair + Format: 'BASE-QUOTE' (e.g., 'BTC-USDT', 'ETH-USDT') + If only base currency provided, '-USDT' will be appended + Case-insensitive input + + Returns: + str: A formatted string containing: + - 24-hour trading volume in the base currency + - Volume formatted with thousand separators + - Currency symbol for clarity + + Raises: + requests.RequestException: If the OKX API request fails + ValueError: If symbol format is invalid + + Example: + >>> get_okx_crypto_volume('BTC-USDT') + '24h Trading Volume for BTC/USDT: 12,345.67 BTC' + + >>> get_okx_crypto_volume('ethereum') # Converts to ETH-USDT + '24h Trading Volume for ETH/USDT: 98,765.43 ETH' + """ + try: + # Input validation and formatting + if not symbol or not symbol.strip(): + return "Error: Please provide a valid trading pair (e.g., 'BTC-USDT')" + + # Normalize symbol format + symbol = symbol.upper().strip() + if not symbol.endswith("-USDT"): + symbol = f"{symbol}-USDT" + + # OKX API endpoint + url = f"https://www.okx.com/api/v5/market/ticker?instId={symbol}" + + # Make API request + response = requests.get(url, timeout=10) + response.raise_for_status() + + data = response.json() + + # Validate API response + if data.get("code") != "0": + return f"Error: {data.get('msg', 'Unknown error from OKX API')}" + + ticker_data = data.get("data", [{}])[0] + if not ticker_data: + return f"Error: Could not find data for {symbol}. Please verify the trading pair." + + # Extract volume data + volume_24h = float(ticker_data.get("vol24h", 0)) + base_currency = symbol.split("-")[0] + + return f"24h Trading Volume for {base_currency}/USDT: {volume_24h:,.2f} {base_currency}" + + except requests.exceptions.RequestException as e: + return f"Error fetching OKX data: {str(e)}" + except Exception as e: + return f"Error: {str(e)}" +``` + +### Step 3: Start Your MCP Server + +```python +if __name__ == "__main__": + # Run the MCP server with SSE (Server-Sent Events) transport + # Server will be available at http://localhost:8001/sse + mcp.run(transport="sse") +``` + +### Step 4: Connect Agent to MCP Server + +```python +from swarms import Agent + +# Method 2: Using direct URL (simpler for development) +mcp_url = "http://0.0.0.0:8001/sse" + +# Initialize agent with MCP tools +agent = Agent( + agent_name="Financial-Analysis-Agent", # Agent identifier + agent_description="Personal finance advisor with OKX exchange data access", + system_prompt="""You are a financial analysis agent with access to real-time + cryptocurrency data from OKX exchange. You can check prices, analyze trading volumes, + and provide market insights. Always format numerical data clearly and explain + market movements in context.""", + max_loops=1, # Processing loops + mcp_url=mcp_url, # MCP server connection + output_type="all", # Complete response format + # Note: tools are automatically loaded from MCP server +) +``` + +### Step 5: Use Your MCP-Enabled Agent + +```python +# The agent automatically discovers and uses tools from the MCP server +response = agent.run( + "Fetch the price for Bitcoin using the OKX exchange and also get its trading volume" +) +print(response) + +# Multiple tool usage +response = agent.run( + "Compare the prices of BTC, ETH, and ADA on OKX, and show their trading volumes" +) +print(response) +``` + +--- + +## Best Practices + +### Function Design + +| Practice | Description | +|----------|-------------| +| Type Hints | Always use type hints for all parameters and return values | +| Docstrings | Write comprehensive docstrings with Args, Returns, Raises, and Examples | +| Error Handling | Implement proper error handling with specific exception types | +| Input Validation | Validate input parameters before processing | +| Data Structure | Return structured data (preferably JSON) for consistency | + +### MCP Server Development + +| Practice | Description | +|----------|-------------| +| Tool Naming | Use descriptive tool names that clearly indicate functionality | +| Timeouts | Set appropriate timeouts for external API calls | +| Error Handling | Implement graceful error handling for network issues | +| Configuration | Use environment variables for sensitive configuration | +| Testing | Test tools independently before integration | + +### Agent Configuration + +| Practice | Description | +|----------|-------------| +| Loop Control | Choose appropriate max_loops based on task complexity | +| Token Management | Set reasonable token limits to control response length | +| System Prompts | Write clear system prompts that explain tool capabilities | +| Agent Naming | Use meaningful agent names for debugging and logging | +| Tool Integration | Consider tool combinations for comprehensive functionality | + +### Performance Optimization + +| Practice | Description | +|----------|-------------| +| Data Caching | Cache frequently requested data when possible | +| Connection Management | Use connection pooling for multiple API calls | +| Rate Control | Implement rate limiting to respect API constraints | +| Performance Monitoring | Monitor tool execution times and optimize slow operations | +| Async Operations | Use async operations for concurrent tool execution when supported | + +--- + +## Troubleshooting + +### Common Issues + +#### Tool Not Found + +```python +# Ensure function is in tools list +agent = Agent( + # ... other config ... + tools=[your_function_name], # Function object, not string +) +``` + +#### MCP Connection Failed +```python +# Check server status and URL +import requests +response = requests.get("http://localhost:8001/health") # Health check endpoint +``` + +#### Type Hint Errors + +```python +# Always specify return types +def my_tool(param: str) -> str: # Not just -> None + return "result" +``` + +#### JSON Parsing Issues + +```python +# Always return valid JSON strings +import json +return json.dumps({"result": data}, indent=2) +``` \ No newline at end of file diff --git a/docs/swarms_cloud/create_api.md b/docs/swarms_cloud/create_api.md deleted file mode 100644 index 9a9e340a..00000000 --- a/docs/swarms_cloud/create_api.md +++ /dev/null @@ -1,204 +0,0 @@ -# CreateNow API Documentation - -Welcome to the CreateNow API documentation! This API enables developers to generate AI-powered content, including images, music, videos, and speech, using natural language prompts. Use the endpoints below to start generating content. - ---- - -## **1. Claim Your API Key** -To use the API, you must first claim your API key. Visit the following link to create an account and get your API key: - -### **Claim Your Key** -``` -https://createnow.xyz/account -``` - -After signing up, your API key will be available in your account dashboard. Keep it secure and include it in your API requests as a Bearer token. - ---- - -## **2. Generation Endpoint** -The generation endpoint allows you to create AI-generated content using natural language prompts. - -### **Endpoint** -``` -POST https://createnow.xyz/api/v1/generate -``` - -### **Authentication** -Include a Bearer token in the `Authorization` header for all requests: -``` -Authorization: Bearer YOUR_API_KEY -``` - -### **Basic Usage** -The simplest way to use the API is to send a prompt. The system will automatically detect the appropriate media type. - -#### **Example Request (Basic)** -```json -{ - "prompt": "a beautiful sunset over the ocean" -} -``` - -### **Advanced Options** -You can specify additional parameters for finer control over the output. - -#### **Parameters** -| Parameter | Type | Description | Default | -|----------------|-----------|---------------------------------------------------------------------------------------------------|--------------| -| `prompt` | `string` | The natural language description of the content to generate. | Required | -| `type` | `string` | The type of content to generate (`image`, `music`, `video`, `speech`). | Auto-detect | -| `count` | `integer` | The number of outputs to generate (1-4). | 1 | -| `duration` | `integer` | Duration of audio or video content in seconds (applicable to `music` and `speech`). | N/A | - -#### **Example Request (Advanced)** -```json -{ - "prompt": "create an upbeat jazz melody", - "type": "music", - "count": 2, - "duration": 30 -} -``` - -### **Response Format** - -#### **Success Response** -```json -{ - "success": true, - "outputs": [ - { - "url": "https://createnow.xyz/storage/image1.png", - "creation_id": "12345", - "share_url": "https://createnow.xyz/share/12345" - } - ], - "mediaType": "image", - "confidence": 0.95, - "detected": true -} -``` - -#### **Error Response** -```json -{ - "error": "Invalid API Key", - "status": 401 -} -``` - ---- - -## **3. Examples in Multiple Languages** - -### **Python** -```python -import requests - -url = "https://createnow.xyz/api/v1/generate" -headers = { - "Authorization": "Bearer YOUR_API_KEY", - "Content-Type": "application/json" -} - -payload = { - "prompt": "a futuristic cityscape at night", - "type": "image", - "count": 2 -} - -response = requests.post(url, json=payload, headers=headers) -print(response.json()) -``` - -### **Node.js** -```javascript -const axios = require('axios'); - -const url = "https://createnow.xyz/api/v1/generate"; -const headers = { - Authorization: "Bearer YOUR_API_KEY", - "Content-Type": "application/json" -}; - -const payload = { - prompt: "a futuristic cityscape at night", - type: "image", - count: 2 -}; - -axios.post(url, payload, { headers }) - .then(response => { - console.log(response.data); - }) - .catch(error => { - console.error(error.response.data); - }); -``` - -### **cURL** -```bash -curl -X POST https://createnow.xyz/api/v1/generate \ --H "Authorization: Bearer YOUR_API_KEY" \ --H "Content-Type: application/json" \ --d '{ - "prompt": "a futuristic cityscape at night", - "type": "image", - "count": 2 -}' -``` - -### **Java** -```java -import java.net.HttpURLConnection; -import java.net.URL; -import java.io.OutputStream; - -public class CreateNowAPI { - public static void main(String[] args) throws Exception { - URL url = new URL("https://createnow.xyz/api/v1/generate"); - HttpURLConnection conn = (HttpURLConnection) url.openConnection(); - conn.setRequestMethod("POST"); - conn.setRequestProperty("Authorization", "Bearer YOUR_API_KEY"); - conn.setRequestProperty("Content-Type", "application/json"); - conn.setDoOutput(true); - - String jsonPayload = "{" + - "\"prompt\": \"a futuristic cityscape at night\", " + - "\"type\": \"image\", " + - "\"count\": 2}"; - - OutputStream os = conn.getOutputStream(); - os.write(jsonPayload.getBytes()); - os.flush(); - - int responseCode = conn.getResponseCode(); - System.out.println("Response Code: " + responseCode); - } -} -``` - ---- - -## **4. Error Codes** -| Status Code | Meaning | Possible Causes | -|-------------|----------------------------------|----------------------------------------| -| 400 | Bad Request | Invalid parameters or payload. | -| 401 | Unauthorized | Invalid or missing API key. | -| 402 | Payment Required | Insufficient credits for the request. | -| 500 | Internal Server Error | Issue on the server side. | - ---- - -## **5. Notes and Limitations** -- **Maximum Prompt Length:** 1000 characters. -- **Maximum Outputs per Request:** 4. -- **Supported Media Types:** `image`, `music`, `video`, `speech`. -- **Content Shareability:** Every output includes a unique creation ID and shareable URL. -- **Auto-Detection:** Uses advanced natural language processing to determine the most appropriate media type. - ---- - -For further support or questions, please contact our support team at [support@createnow.xyz](mailto:support@createnow.xyz). - diff --git a/docs/swarms_cloud/getting_started.md b/docs/swarms_cloud/getting_started.md deleted file mode 100644 index 5fb114ac..00000000 --- a/docs/swarms_cloud/getting_started.md +++ /dev/null @@ -1,94 +0,0 @@ -# Getting Started with State-of-the-Art Vision Language Models (VLMs) Using the Swarms API - -The intersection of vision and language tasks within the field of artificial intelligence has led to the emergence of highly sophisticated models known as Vision Language Models (VLMs). These models leverage the capabilities of both computer vision and natural language processing to provide a more nuanced understanding of multimodal inputs. In this blog post, we will guide you through the process of integrating state-of-the-art VLMs available through the Swarms API, focusing particularly on models like "internlm-xcomposer2-4khd", which represents a blend of high-performance language and visual understanding. - -#### What Are Vision Language Models? - -Vision Language Models are at the frontier of integrating visual data processing with text analysis. These models are trained on large datasets that include both images and their textual descriptions, learning to correlate visual elements with linguistic context. The result is a model that can not only recognize objects in an image but also generate descriptive, context-aware text, answer questions about the image, and even engage in a dialogue about its content. - -#### Why Use Swarms API for VLMs? - -Swarms API provides access to several cutting-edge VLMs including the "internlm-xcomposer2-4khd" model. This API is designed for developers looking to seamlessly integrate advanced multimodal capabilities into their applications without the need for extensive machine learning expertise or infrastructure. Swarms API is robust, scalable, and offers state-of-the-art models that are continuously updated to leverage the latest advancements in AI research. - -#### Prerequisites - -Before diving into the technical setup, ensure you have the following: -- An active account with Swarms API to obtain an API key. -- Python installed on your machine (Python 3.6 or later is recommended). -- An environment where you can install packages and run Python scripts (like Visual Studio Code, Jupyter Notebook, or simply your terminal). - -#### Setting Up Your Environment - -First, you'll need to install the `OpenAI` Python library if it's not already installed: - -```bash -pip install openai -``` - -#### Integrating the Swarms API - -Here’s a basic guide on how to set up the Swarms API in your Python environment: - -1. **API Key Configuration**: - Start by setting up your API key and base URL. Replace `"your_swarms_key"` with the actual API key you obtained from Swarms. - - ```python - from openai import OpenAI - - openai_api_key = "your_swarms_key" - openai_api_base = "https://api.swarms.world/v1" - ``` - -2. **Initialize Client**: - Initialize your OpenAI client with the provided API key and base URL. - - ```python - client = OpenAI( - api_key=openai_api_key, - base_url=openai_api_base, - ) - ``` - -3. **Creating a Chat Completion**: - To use the VLM, you’ll send a request to the API with a multimodal input consisting of both an image and a text query. The following example shows how to structure this request: - - ```python - chat_response = client.chat.completions.create( - model="internlm-xcomposer2-4khd", - messages=[ - { - "role": "user", - "content": [ - { - "type": "image_url", - "image_url": { - "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg", - }, - }, - {"type": "text", "text": "What's in this image?"}, - ] - } - ], - ) - print("Chat response:", chat_response) - ``` - - This code sends a multimodal query to the model, which includes an image URL followed by a text question regarding the image. - -#### Understanding the Response - -The response from the API will include details generated by the model about the image based on the textual query. This could range from simple descriptions to complex narratives, depending on the model’s capabilities and the nature of the question. - -#### Best Practices - -- **Data Privacy**: Always ensure that the images and data you use comply with privacy laws and regulations. -- **Error Handling**: Implement robust error handling to manage potential issues during API calls. -- **Model Updates**: Keep track of updates to the Swarms API and model improvements to leverage new features and improved accuracies. - -#### Conclusion - -Integrating VLMs via the Swarms API opens up a plethora of opportunities for developers to create rich, interactive, and intelligent applications that understand and interpret the world not just through text but through visuals as well. Whether you’re building an educational tool, a content management system, or an interactive chatbot, these models can significantly enhance the way users interact with your application. - -As you embark on your journey to integrate these powerful models into your projects, remember that the key to successful implementation lies in understanding the capabilities and limitations of the technology, continually testing with diverse data, and iterating based on user feedback and technological advances. - -Happy coding, and here’s to building more intelligent, multimodal applications! \ No newline at end of file diff --git a/example.py b/example.py index 4e4116e8..3915827c 100644 --- a/example.py +++ b/example.py @@ -2,15 +2,42 @@ from swarms import Agent # Initialize the agent agent = Agent( - agent_name="Financial-Analysis-Agent", - agent_description="Personal finance advisor agent", - system_prompt="You are a personal finance advisor agent", - max_loops=2, + agent_name="Quantitative-Trading-Agent", + agent_description="Advanced quantitative trading and algorithmic analysis agent", + system_prompt="""You are an expert quantitative trading agent with deep expertise in: + - Algorithmic trading strategies and implementation + - Statistical arbitrage and market making + - Risk management and portfolio optimization + - High-frequency trading systems + - Market microstructure analysis + - Quantitative research methodologies + - Financial mathematics and stochastic processes + - Machine learning applications in trading + + Your core responsibilities include: + 1. Developing and backtesting trading strategies + 2. Analyzing market data and identifying alpha opportunities + 3. Implementing risk management frameworks + 4. Optimizing portfolio allocations + 5. Conducting quantitative research + 6. Monitoring market microstructure + 7. Evaluating trading system performance + + You maintain strict adherence to: + - Mathematical rigor in all analyses + - Statistical significance in strategy development + - Risk-adjusted return optimization + - Market impact minimization + - Regulatory compliance + - Transaction cost analysis + - Performance attribution + + You communicate in precise, technical terms while maintaining clarity for stakeholders.""", + max_loops=3, model_name="gpt-4o-mini", dynamic_temperature_enabled=True, - interactive=True, output_type="all", safety_prompt_on=True, ) -print(agent.run("what are the rules you follow?")) +print(agent.run("What are the best top 3 etfs for gold coverage?")) diff --git a/pyproject.toml b/pyproject.toml index ece6915d..367d1f31 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "poetry.core.masonry.api" [tool.poetry] name = "swarms" -version = "7.8.0" +version = "7.8.2" description = "Swarms - TGSC" license = "MIT" authors = ["Kye Gomez "] diff --git a/swarms/structs/swarm_router.py b/swarms/structs/swarm_router.py index b5bd6569..f623eba5 100644 --- a/swarms/structs/swarm_router.py +++ b/swarms/structs/swarm_router.py @@ -538,8 +538,8 @@ class SwarmRouter: def _run( self, task: str, - img: str, - model_response: str, + img: Optional[str] = None, + model_response: Optional[str] = None, *args, **kwargs, ) -> Any: @@ -591,7 +591,8 @@ class SwarmRouter: def run( self, task: str, - img: str = None, + img: Optional[str] = None, + model_response: Optional[str] = None, *args, **kwargs, ) -> Any: @@ -613,7 +614,13 @@ class SwarmRouter: Exception: If an error occurs during task execution. """ try: - return self._run(task=task, img=img, *args, **kwargs) + return self._run( + task=task, + img=img, + model_response=model_response, + *args, + **kwargs, + ) except Exception as e: logger.error(f"Error executing task on swarm: {str(e)}") raise diff --git a/swarms/utils/litellm_tokenizer.py b/swarms/utils/litellm_tokenizer.py index c2743b10..894ec394 100644 --- a/swarms/utils/litellm_tokenizer.py +++ b/swarms/utils/litellm_tokenizer.py @@ -1,20 +1,106 @@ -import subprocess +from litellm import encode, model_list +from loguru import logger +from typing import Optional +from functools import lru_cache +# Use consistent default model +DEFAULT_MODEL = "gpt-4o-mini" -def count_tokens(text: str, model: str = "gpt-4o") -> int: - """Count the number of tokens in the given text.""" + +def count_tokens( + text: str, + model: str = DEFAULT_MODEL, + default_encoder: Optional[str] = DEFAULT_MODEL, +) -> int: + """ + Count the number of tokens in the given text using the specified model. + + Args: + text: The text to tokenize + model: The model to use for tokenization (defaults to gpt-4o-mini) + default_encoder: Fallback encoder if the primary model fails (defaults to DEFAULT_MODEL) + + Returns: + int: Number of tokens in the text + + Raises: + ValueError: If text is empty or if both primary and fallback models fail + """ + if not text or not text.strip(): + logger.warning("Empty or whitespace-only text provided") + return 0 + + # Set fallback encoder + fallback_model = default_encoder or DEFAULT_MODEL + + # First attempt with the requested model try: - from litellm import encode - except ImportError: - import sys + tokens = encode(model=model, text=text) + return len(tokens) - subprocess.run( - [sys.executable, "-m", "pip", "install", "litellm"] + except Exception as e: + logger.warning( + f"Failed to tokenize with model '{model}': {e} using fallback model '{fallback_model}'" ) - from litellm import encode - return len(encode(model=model, text=text)) + logger.info(f"Using fallback model '{fallback_model}'") + + # Only try fallback if it's different from the original model + if fallback_model != model: + try: + logger.info( + f"Falling back to default encoder: {fallback_model}" + ) + tokens = encode(model=fallback_model, text=text) + return len(tokens) + + except Exception as fallback_error: + logger.error( + f"Fallback encoder '{fallback_model}' also failed: {fallback_error}" + ) + raise ValueError( + f"Both primary model '{model}' and fallback '{fallback_model}' failed to tokenize text" + ) + else: + logger.error( + f"Primary model '{model}' failed and no different fallback available" + ) + raise ValueError( + f"Model '{model}' failed to tokenize text: {e}" + ) + + +@lru_cache(maxsize=100) +def get_supported_models() -> list: + """Get list of supported models from litellm.""" + try: + return model_list + except Exception as e: + logger.warning(f"Could not retrieve model list: {e}") + return [] # if __name__ == "__main__": -# print(count_tokens("Hello, how are you?")) +# # Test with different scenarios +# test_text = "Hello, how are you?" + +# # # Test with Claude model +# # try: +# # tokens = count_tokens(test_text, model="claude-3-5-sonnet-20240620") +# # print(f"Claude tokens: {tokens}") +# # except Exception as e: +# # print(f"Claude test failed: {e}") + +# # # Test with default model +# # try: +# # tokens = count_tokens(test_text) +# # print(f"Default model tokens: {tokens}") +# # except Exception as e: +# # print(f"Default test failed: {e}") + +# # Test with explicit fallback +# try: +# tokens = count_tokens(test_text, model="some-invalid-model", default_encoder="gpt-4o-mini") +# print(f"Fallback test tokens: {tokens}") +# except Exception as e: +# print(f"Fallback test failed: {e}")