diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 86db5f3b..7695af97 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -208,6 +208,8 @@ nav: - Ollama: "swarms/examples/ollama.md" - OpenRouter: "swarms/examples/openrouter.md" - XAI: "swarms/examples/xai.md" + - Swarms Tools: + - Agent with HTX + CoinGecko: "swarms/examples/swarms_tools_htx.md" - Swarm Models: - Overview: "swarms/models/index.md" # - Models Available: "swarms/models/index.md" @@ -226,6 +228,8 @@ nav: - BaseMultiModalModel: "swarms/models/base_multimodal_model.md" - Multi Modal Models Available: "swarms/models/multimodal_models.md" - GPT4VisionAPI: "swarms/models/gpt4v.md" + - Swarms Tools: + - Overview: "swarms_tools/overview.md" - Swarms Cloud API: # - Overview: "swarms_cloud/main.md" - Overview: "swarms_cloud/vision.md" diff --git a/docs/swarms/examples/swarms_tools_htx.md b/docs/swarms/examples/swarms_tools_htx.md new file mode 100644 index 00000000..ab4333dd --- /dev/null +++ b/docs/swarms/examples/swarms_tools_htx.md @@ -0,0 +1,37 @@ +# Swarms Tools Example with HTX + CoinGecko + +- `pip3 install swarms swarms-tools` +- Add `OPENAI_API_KEY` to your `.env` file + +```python +from swarms import Agent +from swarms.prompts.finance_agent_sys_prompt import ( + FINANCIAL_AGENT_SYS_PROMPT, +) +from swarms_tools import ( + coin_gecko_coin_api, + fetch_htx_data, +) + + +# Initialize the agent +agent = Agent( + agent_name="Financial-Analysis-Agent", + agent_description="Personal finance advisor agent", + system_prompt=FINANCIAL_AGENT_SYS_PROMPT, + max_loops=1, + model_name="gpt-4o", + dynamic_temperature_enabled=True, + user_name="swarms_corp", + return_step_meta=False, + output_type="str", # "json", "dict", "csv" OR "string" "yaml" and + auto_generate_prompt=False, # Auto generate prompt for the agent based on name, description, and system prompt, task + max_tokens=4000, # max output tokens + saved_state_path="agent_00.json", + interactive=False, +) + +agent.run( + f"Analyze the $swarms token on HTX with data: {fetch_htx_data('swarms')}. Additionally, consider the following CoinGecko data: {coin_gecko_coin_api('swarms')}" +) +``` \ No newline at end of file diff --git a/docs/swarms_tools/overview.md b/docs/swarms_tools/overview.md new file mode 100644 index 00000000..ad896fa9 --- /dev/null +++ b/docs/swarms_tools/overview.md @@ -0,0 +1,239 @@ +# Swarms Tools + + +Welcome to **Swarms Tools**, the ultimate package for integrating **cutting-edge APIs** into Python functions with seamless multi-agent system compatibility. Designed for enterprises at the forefront of innovation, **Swarms Tools** is your key to simplifying complexity and unlocking operational excellence. + +--- + +## 🚀 Features + +- **Unified API Integration**: Ready-to-use Python functions for financial data, social media, IoT, and more. +- **Enterprise-Grade Design**: Comprehensive type hints, structured outputs, and robust documentation. +- **Agent-Ready Framework**: Optimized for seamless integration into Swarms' multi-agent orchestration systems. +- **Expandable Architecture**: Easily extend functionality with a standardized schema for new tools. + +--- + +## 🔧 Installation + +```bash +pip3 install -U swarms-tools +``` + +--- + +## 📂 Directory Structure + +```plaintext +swarms-tools/ +├── swarms_tools/ +│ ├── finance/ +│ │ ├── htx_tool.py +│ │ ├── eodh_api.py +│ │ └── coingecko_tool.py +│ ├── social_media/ +│ │ ├── telegram_tool.py +│ ├── utilities/ +│ │ └── logging.py +├── tests/ +│ ├── test_financial_data.py +│ └── test_social_media.py +└── README.md +``` + +--- + +## 💼 Use Cases + + + +## Finance + +Explore our diverse range of financial tools, designed to streamline your operations. If you need a tool not listed, feel free to submit an issue or accelerate integration by contributing a pull request with your tool of choice. + +| **Tool Name** | **Function** | **Description** | +|---------------------------|--------------------------|---------------------------------------------------------------------------------| +| `fetch_stock_news` | `fetch_stock_news` | Fetches the latest stock news and updates. | +| `fetch_htx_data` | `fetch_htx_data` | Retrieves financial data from the HTX platform. | +| `yahoo_finance_api` | `yahoo_finance_api` | Fetches comprehensive stock data from Yahoo Finance, including prices and trends. | +| `coin_gecko_coin_api` | `coin_gecko_coin_api` | Fetches cryptocurrency data from CoinGecko, including market and price information. | +| `helius_api_tool` | `helius_api_tool` | Retrieves blockchain account, transaction, or token data using the Helius API. | +| `okx_api_tool` | `okx_api_tool` | Fetches detailed cryptocurrency data for coins from the OKX exchange. | + + +### Financial Data Retrieval +Enable precise and actionable financial insights: + +#### Example 1: Fetch Historical Data +```python +from swarms_tools import fetch_htx_data + +# Fetch historical trading data for "Swarms Corporation" +response = fetch_htx_data("swarms") +print(response) +``` + +#### Example 2: Stock News Analysis +```python +from swarms_tools import fetch_stock_news + +# Retrieve latest stock news for Apple +news = fetch_stock_news("AAPL") +print(news) +``` + +#### Example 3: Cryptocurrency Metrics +```python +from swarms_tools import coin_gecko_coin_api + +# Fetch live data for Bitcoin +crypto_data = coin_gecko_coin_api("bitcoin") +print(crypto_data) +``` + +### Social Media Automation +Streamline communication and engagement: + +#### Example: Telegram Bot Messaging +```python +from swarms_tools import telegram_dm_or_tag_api + +def send_alert(response: str): + telegram_dm_or_tag_api(response) + +# Send a message to a user or group +send_alert("Mission-critical update from Swarms.") +``` + +--- + +## Dex Screener + +This is a tool that allows you to fetch data from the Dex Screener API. It supports multiple chains and multiple tokens. + +```python +from swarms_tools.finance.dex_screener import ( + fetch_latest_token_boosts, + fetch_dex_screener_profiles, +) + + +fetch_dex_screener_profiles() +fetch_latest_token_boosts() + +``` + +--- + + +## Structs +The tool chainer enables the execution of multiple tools in a sequence, allowing for the aggregation of their results in either a parallel or sequential manner. + +```python +# Example usage +from loguru import logger + +from swarms_tools.structs import tool_chainer + + +if __name__ == "__main__": + logger.add("tool_chainer.log", rotation="500 MB", level="INFO") + + # Example tools + def tool1(): + return "Tool1 Result" + + def tool2(): + return "Tool2 Result" + + # def tool3(): + # raise ValueError("Simulated error in Tool3") + + tools = [tool1, tool2] + + # Parallel execution + parallel_results = tool_chainer(tools, parallel=True) + print("Parallel Results:", parallel_results) + + # Sequential execution + # sequential_results = tool_chainer(tools, parallel=False) + # print("Sequential Results:", sequential_results) + +``` +--- + +## 🧩 Standardized Schema + +Every tool in **Swarms Tools** adheres to a strict schema for maintainability and interoperability: + +### Schema Template + +1. **Functionality**: + - Encapsulate API logic into a modular, reusable function. + +2. **Typing**: + - Leverage Python type hints for input validation and clarity. + + Example: + ```python + def fetch_data(symbol: str, date_range: str) -> str: + """ + Fetch financial data for a given symbol and date range. + + Args: + symbol (str): Ticker symbol of the asset. + date_range (str): Timeframe for the data (e.g., '1d', '1m', '1y'). + + Returns: + dict: A dictionary containing financial metrics. + """ + pass + ``` + +3. **Documentation**: + - Include detailed docstrings with parameter explanations and usage examples. + +4. **Output Standardization**: + - Ensure consistent outputs (e.g., strings) for easy downstream agent integration. + +5. **API-Key Management**: + - All API keys must be fetched with `os.getenv("YOUR_KEY")` + + +--- + +## 📖 Documentation + +Comprehensive documentation is available to guide developers and enterprises. Visit our [official docs](https://docs.swarms.world) for detailed API references, usage examples, and best practices. + +--- + +## 🛠 Contributing + +We welcome contributions from the global developer community. To contribute: + +1. **Fork the Repository**: Start by forking the repository. +2. **Create a Feature Branch**: Use a descriptive branch name: `feature/add-new-tool`. +3. **Commit Your Changes**: Write meaningful commit messages. +4. **Submit a Pull Request**: Open a pull request for review. + +--- + +## 🛡️ License + +This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details. + +--- + +## 🌠 Join the Future + +Explore the limitless possibilities of agent-based systems. Together, we can build a smarter, faster, and more interconnected world. + +**Visit us:** [Swarms Corporation](https://swarms.ai) +**Follow us:** [Twitter](https://twitter.com/swarms_corp) + +--- + +**"The future belongs to those who dare to automate it."** +**— The Swarms Corporation** + diff --git a/swarms/agents/create_agents_from_yaml.py b/swarms/agents/create_agents_from_yaml.py index 76aab346..fb1cd0e7 100644 --- a/swarms/agents/create_agents_from_yaml.py +++ b/swarms/agents/create_agents_from_yaml.py @@ -179,37 +179,43 @@ def create_agents_from_yaml( try: logger.info("Starting agent creation process...") - + # Load and validate configuration if yaml_file: logger.info(f"Loading configuration from {yaml_file}") config = load_yaml_safely(yaml_file, yaml_string) - + if not config.get("agents"): raise ValueError( "No agents defined in the YAML configuration. " "Please add at least one agent under the 'agents' section." ) - - logger.info(f"Found {len(config['agents'])} agent(s) to create") + + logger.info( + f"Found {len(config['agents'])} agent(s) to create" + ) # Create agents with retry logic for idx, agent_config in enumerate(config["agents"], 1): if not agent_config.get("agent_name"): agent_config["agent_name"] = f"Agent_{idx}" - + logger.info( f"Creating agent {idx}/{len(config['agents'])}: {agent_config['agent_name']}" ) if "model_name" in agent_config: - logger.info(f"Using specified model: {agent_config['model_name']}") + logger.info( + f"Using specified model: {agent_config['model_name']}" + ) model_instance = LiteLLM( model_name=agent_config["model_name"] ) else: model_name = "gpt-4" - logger.info(f"No model specified, using default: {model_name}") + logger.info( + f"No model specified, using default: {model_name}" + ) model_instance = LiteLLM(model_name=model_name) agent = create_agent_with_retry( @@ -230,9 +236,15 @@ def create_agents_from_yaml( raise ValueError( "swarm_architecture must be a dictionary containing swarm configuration" ) - - required_fields = {"name", "description", "swarm_type"} - missing_fields = required_fields - set(config["swarm_architecture"].keys()) + + required_fields = { + "name", + "description", + "swarm_type", + } + missing_fields = required_fields - set( + config["swarm_architecture"].keys() + ) if missing_fields: raise ValueError( f"SwarmRouter creation failed: Missing required fields in swarm_architecture: {', '.join(missing_fields)}" @@ -241,8 +253,10 @@ def create_agents_from_yaml( swarm_config = SwarmConfig( **config["swarm_architecture"] ) - - logger.info(f"Creating SwarmRouter with type: {swarm_config.swarm_type}") + + logger.info( + f"Creating SwarmRouter with type: {swarm_config.swarm_type}" + ) swarm_router = SwarmRouter( name=swarm_config.name, description=swarm_config.description, @@ -306,7 +320,9 @@ def create_agents_from_yaml( "No task specified in swarm_architecture. Please add a 'task' field " "to define what the swarm should do." ) - logger.info(f"Running swarm with task: {config['swarm_architecture']['task']}") + logger.info( + f"Running swarm with task: {config['swarm_architecture']['task']}" + ) return swarm_router.run( config["swarm_architecture"]["task"] ) @@ -331,8 +347,12 @@ def create_agents_from_yaml( result = agents[0] if len(agents) == 1 else agents elif return_type == "both": result = ( - (swarm_router if swarm_router else agents[0] if len(agents) == 1 else agents), - agents + ( + swarm_router + if swarm_router + else agents[0] if len(agents) == 1 else agents + ), + agents, ) elif return_type == "tasks": result = task_results diff --git a/swarms/cli/main.py b/swarms/cli/main.py index 4559ef9b..ef4151eb 100644 --- a/swarms/cli/main.py +++ b/swarms/cli/main.py @@ -277,58 +277,91 @@ def main(): check_login() elif args.command == "run-agents": try: - console.print(f"[yellow]Loading agents from {args.yaml_file}...[/yellow]") - + console.print( + f"[yellow]Loading agents from {args.yaml_file}...[/yellow]" + ) + if not os.path.exists(args.yaml_file): raise FileNotFoundError( f"YAML file not found: {args.yaml_file}\n" "Please make sure the file exists and you're in the correct directory." ) - + # Create progress display progress = Progress( SpinnerColumn(), - TextColumn("[progress.description]{task.description}"), + TextColumn( + "[progress.description]{task.description}" + ), console=console, ) - + with progress: # Add initial task - init_task = progress.add_task("Initializing...", total=None) - + init_task = progress.add_task( + "Initializing...", total=None + ) + # Load and validate YAML - progress.update(init_task, description="Loading YAML configuration...") - + progress.update( + init_task, + description="Loading YAML configuration...", + ) + # Create agents - progress.update(init_task, description="Creating agents...") + progress.update( + init_task, + description="Creating agents...", + ) result = create_agents_from_yaml( yaml_file=args.yaml_file, - return_type="run_swarm" + return_type="run_swarm", ) - + # Update progress on completion - progress.update(init_task, description="Processing complete!", completed=True) - + progress.update( + init_task, + description="Processing complete!", + completed=True, + ) + if result: # Format and display the results if isinstance(result, str): - console.print("\n[bold green]Results:[/bold green]") - console.print(Panel(result, title="Agent Output", border_style="green")) + console.print( + "\n[bold green]Results:[/bold green]" + ) + console.print( + Panel( + result, + title="Agent Output", + border_style="green", + ) + ) elif isinstance(result, dict): - console.print("\n[bold green]Results:[/bold green]") + console.print( + "\n[bold green]Results:[/bold green]" + ) for key, value in result.items(): - console.print(f"[cyan]{key}:[/cyan] {value}") + console.print( + f"[cyan]{key}:[/cyan] {value}" + ) else: - console.print("[green]✓ Agents completed their tasks successfully![/green]") + console.print( + "[green]✓ Agents completed their tasks successfully![/green]" + ) else: - console.print("[yellow]⚠ Agents completed but returned no results.[/yellow]") - + console.print( + "[yellow]⚠ Agents completed but returned no results.[/yellow]" + ) + except FileNotFoundError as e: show_error("File Error", str(e)) except ValueError as e: show_error( "Configuration Error", - str(e) + "\n\nPlease check your agents.yaml file format." + str(e) + + "\n\nPlease check your agents.yaml file format.", ) except Exception as e: # Enhanced error handling @@ -339,7 +372,7 @@ def main(): "The model's context length was exceeded. Try:\n" "1. Reducing max_tokens in your YAML config\n" "2. Reducing context_length in your YAML config\n" - "3. Using a model with larger context window" + "3. Using a model with larger context window", ) elif "api_key" in error_msg.lower(): show_error( @@ -347,7 +380,7 @@ def main(): "There seems to be an issue with the API key. Please:\n" "1. Check if your API key is set correctly\n" "2. Verify the API key is valid\n" - "3. Run 'swarms get-api-key' to get a new key" + "3. Run 'swarms get-api-key' to get a new key", ) else: show_error( @@ -355,7 +388,7 @@ def main(): f"An unexpected error occurred: {error_msg}\n" "1. Check your YAML configuration\n" "2. Verify your API keys are set\n" - "3. Check network connectivity" + "3. Check network connectivity", ) elif args.command == "book-call": webbrowser.open( diff --git a/swarms_tools_example.py b/swarms_tools_example.py new file mode 100644 index 00000000..96311883 --- /dev/null +++ b/swarms_tools_example.py @@ -0,0 +1,30 @@ +from swarms import Agent +from swarms.prompts.finance_agent_sys_prompt import ( + FINANCIAL_AGENT_SYS_PROMPT, +) +from swarms_tools import ( + coin_gecko_coin_api, + fetch_htx_data, +) + + +# Initialize the agent +agent = Agent( + agent_name="Financial-Analysis-Agent", + agent_description="Personal finance advisor agent", + system_prompt=FINANCIAL_AGENT_SYS_PROMPT, + max_loops=1, + model_name="gpt-4o", + dynamic_temperature_enabled=True, + user_name="swarms_corp", + return_step_meta=False, + output_type="str", # "json", "dict", "csv" OR "string" "yaml" and + auto_generate_prompt=False, # Auto generate prompt for the agent based on name, description, and system prompt, task + max_tokens=4000, # max output tokens + saved_state_path="agent_00.json", + interactive=False, +) + +agent.run( + f"Analyze the $swarms token on HTX with data: {fetch_htx_data('swarms')}. Additionally, consider the following CoinGecko data: {coin_gecko_coin_api('swarms')}" +)