diff --git a/docs/llm.txt b/docs/llm.txt index 9f1d2fb6..5ccbf028 100644 --- a/docs/llm.txt +++ b/docs/llm.txt @@ -1,16983 +1,19651 @@ -# File: applications/azure_openai.md +# File: agent_deployment_solutions.md -# Deploying Azure OpenAI in Production: A Comprehensive Guide +1. make agent api - fastapi +2. make agent cron job +3. agents that listen that could listen to events +4. run on startup, every time the machine starts +4. docker +5. kubernetes +6. aws or google cloud etc -In today's fast-paced digital landscape, leveraging cutting-edge technologies has become essential for businesses to stay competitive and provide exceptional services to their customers. One such technology that has gained significant traction is Azure OpenAI, a powerful platform that allows developers to integrate advanced natural language processing (NLP) capabilities into their applications. Whether you're building a chatbot, a content generation system, or any other AI-powered solution, Azure OpenAI offers a robust and scalable solution for production-grade deployment. -In this comprehensive guide, we'll walk through the process of setting up and deploying Azure OpenAI in a production environment. We'll dive deep into the code, provide clear explanations, and share best practices to ensure a smooth and successful implementation. -## Prerequisites: -Before we begin, it's essential to have the following prerequisites in place: +user -> build agent -> user now need deploy agent -1. **Python**: You'll need to have Python installed on your system. This guide assumes you're using Python 3.6 or later. -2. **Azure Subscription**: You'll need an active Azure subscription to access Azure OpenAI services. -3. **Azure OpenAI Resource**: Create an Azure OpenAI resource in your Azure subscription. -4. **Python Packages**: Install the required Python packages, including `python-dotenv` and `swarms`. +FAST -## Setting up the Environment: -To kick things off, we'll set up our development environment and install the necessary dependencies. - -1. **Create a Virtual Environment**: It's a best practice to create a virtual environment to isolate your project dependencies from the rest of your system. You can create a virtual environment using `venv` or any other virtual environment management tool of your choice. +-------------------------------------------------- -``` -python -m venv myenv -``` +# File: concepts\limitations.md -2. **Activate the Virtual Environment**: Activate the virtual environment to ensure that any packages you install are isolated within the environment. +# Limitations of Individual Agents -``` -source myenv/bin/activate # On Windows, use `myenv\Scripts\activate` -``` +This section explores the fundamental limitations of individual AI agents and why multi-agent systems are necessary for complex tasks. Understanding these limitations is crucial for designing effective multi-agent architectures. -3. **Install Required Packages**: Install the `python-dotenv` and `swarms` packages using pip. +## Overview -``` -pip install python-dotenv swarms +```mermaid +graph TD + A[Individual Agent Limitations] --> B[Context Window Limits] + A --> C[Hallucination] + A --> D[Single Task Execution] + A --> E[Lack of Collaboration] + A --> F[Accuracy Issues] + A --> G[Processing Speed] ``` -4. **Create a `.env` File**: In the root directory of your project, create a new file called `.env`. This file will store your Azure OpenAI credentials and configuration settings. +## 1. Context Window Limits -``` -AZURE_OPENAI_ENDPOINT= -AZURE_OPENAI_DEPLOYMENT= -OPENAI_API_VERSION= -AZURE_OPENAI_API_KEY= -AZURE_OPENAI_AD_TOKEN= -``` +### The Challenge +Individual agents are constrained by fixed context windows, limiting their ability to process large amounts of information simultaneously. -Replace the placeholders with your actual Azure OpenAI credentials and configuration settings. +```mermaid +graph LR + subgraph "Context Window Limitation" + Input[Large Document] --> Truncation[Truncation] + Truncation --> ProcessedPart[Processed Part] + Truncation --> UnprocessedPart[Unprocessed Part] + end +``` -## Connecting to Azure OpenAI: -Now that we've set up our environment, let's dive into the code that connects to Azure OpenAI and interacts with the language model. +### Impact +- Limited understanding of large documents +- Fragmented processing of long conversations +- Inability to maintain extended context +- Loss of important information -```python -import os -from dotenv import load_dotenv -from swarms import AzureOpenAI +## 2. Hallucination -# Load the environment variables -load_dotenv() +### The Challenge +Individual agents may generate plausible-sounding but incorrect information, especially when dealing with ambiguous or incomplete data. -# Create an instance of the AzureOpenAI class -model = AzureOpenAI( - azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"), - deployment_name=os.getenv("AZURE_OPENAI_DEPLOYMENT"), - openai_api_version=os.getenv("OPENAI_API_VERSION"), - openai_api_key=os.getenv("AZURE_OPENAI_API_KEY"), - azure_ad_token=os.getenv("AZURE_OPENAI_AD_TOKEN") -) +```mermaid +graph TD + Input[Ambiguous Input] --> Agent[AI Agent] + Agent --> Valid[Valid Output] + Agent --> Hallucination[Hallucinated Output] + style Hallucination fill:#ff9999 ``` -## Let's break down this code: +### Impact +- Unreliable information generation +- Reduced trust in system outputs +- Potential for misleading decisions +- Need for extensive verification + +## 3. Single Task Execution -1. **Import Statements**: We import the necessary modules, including `os` for interacting with the operating system, `load_dotenv` from `python-dotenv` to load environment variables, and `AzureOpenAI` from `swarms` to interact with the Azure OpenAI service. +### The Challenge +Most individual agents are optimized for specific tasks and struggle with multi-tasking or adapting to new requirements. -2. **Load Environment Variables**: We use `load_dotenv()` to load the environment variables stored in the `.env` file we created earlier. +```mermaid +graph LR + Task1[Task A] --> Agent1[Agent A] + Task2[Task B] --> Agent2[Agent B] + Task3[Task C] --> Agent3[Agent C] + Agent1 --> Output1[Output A] + Agent2 --> Output2[Output B] + Agent3 --> Output3[Output C] +``` -3. **Create AzureOpenAI Instance**: We create an instance of the `AzureOpenAI` class by passing in the required configuration parameters: - - `azure_endpoint`: The endpoint URL for your Azure OpenAI resource. - - `deployment_name`: The name of the deployment you want to use. - - `openai_api_version`: The version of the OpenAI API you want to use. - - `openai_api_key`: Your Azure OpenAI API key, which authenticates your requests. - - `azure_ad_token`: An optional Azure Active Directory (AAD) token for additional security. +### Impact +- Limited flexibility +- Inefficient resource usage +- Complex integration requirements +- Reduced adaptability -Querying the Language Model: -With our connection to Azure OpenAI established, we can now query the language model and receive responses. +## 4. Lack of Collaboration -```python -# Define the prompt -prompt = "Analyze this load document and assess it for any risks and create a table in markdwon format." +### The Challenge +Individual agents operate in isolation, unable to share insights or coordinate actions with other agents. -# Generate a response -response = model(prompt) -print(response) +```mermaid +graph TD + A1[Agent 1] --> O1[Output 1] + A2[Agent 2] --> O2[Output 2] + A3[Agent 3] --> O3[Output 3] + style A1 fill:#f9f,stroke:#333 + style A2 fill:#f9f,stroke:#333 + style A3 fill:#f9f,stroke:#333 ``` -## Here's what's happening: +### Impact +- No knowledge sharing +- Duplicate effort +- Missed optimization opportunities +- Limited problem-solving capabilities + +## 5. Accuracy Issues -1. **Define the Prompt**: We define a prompt, which is the input text or question we want to feed into the language model. +### The Challenge +Individual agents may produce inaccurate results due to: +- Limited training data +- Model biases +- Lack of cross-validation +- Incomplete context understanding -2. **Generate a Response**: We call the `model` instance with the `prompt` as an argument. This triggers the Azure OpenAI service to process the prompt and generate a response. +```mermaid +graph LR + Input[Input Data] --> Processing[Processing] + Processing --> Accurate[Accurate Output] + Processing --> Inaccurate[Inaccurate Output] + style Inaccurate fill:#ff9999 +``` -3. **Print the Response**: Finally, we print the response received from the language model. +## 6. Processing Speed Limitations -Running the Code: -To run the code, save it in a Python file (e.g., `main.py`) and execute it from the command line: +### The Challenge +Individual agents may experience: +- Slow response times +- Resource constraints +- Limited parallel processing +- Bottlenecks in complex tasks -``` -python main.py +```mermaid +graph TD + Input[Input] --> Queue[Processing Queue] + Queue --> Processing[Sequential Processing] + Processing --> Delay[Processing Delay] + Delay --> Output[Delayed Output] ``` -## Best Practices for Production Deployment: -While the provided code serves as a basic example, there are several best practices to consider when deploying Azure OpenAI in a production environment: - -1. **Secure Credentials Management**: Instead of storing sensitive credentials like API keys in your codebase, consider using secure storage solutions like Azure Key Vault or environment variables managed by your cloud provider. +## Best Practices for Mitigation -2. **Error Handling and Retries**: Implement robust error handling and retry mechanisms to handle potential failures or rate-limiting scenarios. +1. **Use Multi-Agent Systems** + - Distribute tasks across agents + - Enable parallel processing + - Implement cross-validation + - Foster collaboration -3. **Logging and Monitoring**: Implement comprehensive logging and monitoring strategies to track application performance, identify issues, and gather insights for optimization. +2. **Implement Verification** + - Cross-check results + - Use consensus mechanisms + - Monitor accuracy metrics + - Track performance -4. **Scalability and Load Testing**: Conduct load testing to ensure your application can handle anticipated traffic volumes and scale appropriately based on demand. +3. **Optimize Resource Usage** + - Balance load distribution + - Cache frequent operations + - Implement efficient queuing + - Monitor system health -5. **Caching and Optimization**: Explore caching strategies and performance optimizations to improve response times and reduce the load on the Azure OpenAI service. +## Conclusion -6. **Integration with Other Services**: Depending on your use case, you may need to integrate Azure OpenAI with other Azure services or third-party tools for tasks like data processing, storage, or analysis. +Understanding these limitations is crucial for: +- Designing robust multi-agent systems +- Implementing effective mitigation strategies +- Optimizing system performance +- Ensuring reliable outputs -7. **Compliance and Security**: Ensure your application adheres to relevant compliance standards and security best practices, especially when handling sensitive data. +The next section explores how [Multi-Agent Architecture](architecture.md) addresses these limitations through collaborative approaches and specialized agent roles. -## Conclusion: -Azure OpenAI is a powerful platform that enables developers to integrate advanced natural language processing capabilities into their applications. By following the steps outlined in this guide, you can set up a production-ready environment for deploying Azure OpenAI and start leveraging its capabilities in your projects. +-------------------------------------------------- -Remember, this guide serves as a starting point, and there are numerous additional features and capabilities within Azure OpenAI that you can explore to enhance your applications further. As with any production deployment, it's crucial to follow best practices, conduct thorough testing, and implement robust monitoring and security measures. +# File: contributors\docs.md -With the right approach and careful planning, you can successfully deploy Azure OpenAI in a production environment and unlock the power of cutting-edge language models to drive innovation and provide exceptional experiences for your users. +# Contributing to Swarms Documentation --------------------------------------------------- +--- -# File: applications/blog.md +The Swarms documentation serves as the primary gateway for developer and user engagement within the Swarms ecosystem. Comprehensive, clear, and consistently updated documentation accelerates adoption, reduces support requests, and helps maintain a thriving developer community. This guide offers an in-depth, actionable framework for contributing to the Swarms documentation site, covering the full lifecycle from initial setup to the implementation of our bounty-based rewards program. -# The Future of Manufacturing: Leveraging Autonomous LLM Agents for Cost Reduction and Revenue Growth +This guide is designed for first-time contributors, experienced engineers, and technical writers alike. It emphasizes professional standards, collaborative development practices, and incentivized participation through our structured rewards program. Contributors play a key role in helping us scale and evolve our ecosystem by improving the clarity, accessibility, and technical depth of our documentation. -## Table of Contents +--- -1. [Introduction](#introduction) -2. [Understanding Autonomous LLM Agents](#understanding-autonomous-llm-agents) -3. [RAG Embedding Databases: The Knowledge Foundation](#rag-embedding-databases) -4. [Function Calling and External Tools: Enhancing Capabilities](#function-calling-and-external-tools) -5. [Cost Reduction Strategies](#cost-reduction-strategies) - 5.1. [Optimizing Supply Chain Management](#optimizing-supply-chain-management) - 5.2. [Enhancing Quality Control](#enhancing-quality-control) - 5.3. [Streamlining Maintenance and Repairs](#streamlining-maintenance-and-repairs) - 5.4. [Improving Energy Efficiency](#improving-energy-efficiency) -6. [Revenue Growth Opportunities](#revenue-growth-opportunities) - 6.1. [Product Innovation and Development](#product-innovation-and-development) - 6.2. [Personalized Customer Experiences](#personalized-customer-experiences) - 6.3. [Market Analysis and Trend Prediction](#market-analysis-and-trend-prediction) - 6.4. [Optimizing Pricing Strategies](#optimizing-pricing-strategies) -7. [Implementation Strategies](#implementation-strategies) -8. [Overcoming Challenges and Risks](#overcoming-challenges-and-risks) -9. [Case Studies](#case-studies) -10. [Future Outlook](#future-outlook) -11. [Conclusion](#conclusion) +## 1. Introduction -## 1. Introduction +Documentation in the Swarms ecosystem is not simply static text. It is a living, breathing system that guides users, developers, and enterprises in effectively utilizing our frameworks, SDKs, APIs, and tools. Whether you are documenting a new feature, refining an API call, writing a tutorial, or correcting existing information, every contribution has a direct impact on the product’s usability and user satisfaction. -In today's rapidly evolving manufacturing landscape, executives and CEOs face unprecedented challenges and opportunities. The key to maintaining a competitive edge lies in embracing cutting-edge technologies that can revolutionize operations, reduce costs, and drive revenue growth. One such transformative technology is the integration of autonomous Large Language Model (LLM) agents equipped with Retrieval-Augmented Generation (RAG) embedding databases, function calling capabilities, and access to external tools. +**Objectives of this Guide:** -This comprehensive blog post aims to explore how these advanced AI systems can be leveraged to address the most pressing issues in manufacturing enterprises. We will delve into the intricacies of these technologies, provide concrete examples of their applications, and offer insights into implementation strategies. By the end of this article, you will have a clear understanding of how autonomous LLM agents can become a cornerstone of your manufacturing business's digital transformation journey. -## 2. Understanding Autonomous LLM Agents +- Define a standardized contribution workflow for Swarms documentation. -Autonomous LLM agents represent the cutting edge of artificial intelligence in the manufacturing sector. These sophisticated systems are built upon large language models, which are neural networks trained on vast amounts of text data. What sets them apart is their ability to operate autonomously, making decisions and taking actions with minimal human intervention. +- Clarify documentation roles, responsibilities, and submission expectations. -Key features of autonomous LLM agents include: +- Establish quality benchmarks, review procedures, and formatting rules. -1. **Natural Language Processing (NLP)**: They can understand and generate human-like text, enabling seamless communication with employees across all levels of the organization. +- Introduce the Swarms Documentation Bounty Program to incentivize excellence. -2. **Contextual Understanding**: These agents can grasp complex scenarios and nuanced information, making them ideal for handling intricate manufacturing processes. +--- -3. **Adaptive Learning**: Through continuous interaction and feedback, they can improve their performance over time, becoming more efficient and accurate. +## 2. Why Documentation Is a Strategic Asset -4. **Multi-modal Input Processing**: Advanced agents can process not only text but also images, audio, and sensor data, providing a holistic view of manufacturing operations. +1. **Accelerates Onboarding**: Reduces friction for new users, enabling faster adoption and integration. +2. **Improves Support Efficiency**: Decreases dependency on live support and helps automate resolution of common queries. +3. **Builds Community Trust**: Transparent documentation invites feedback and fosters a sense of shared ownership. +4. **Enables Scalability**: As Swarms evolves, up-to-date documentation ensures that teams across the globe can keep pace. -5. **Task Automation**: They can automate a wide range of tasks, from data analysis to decision-making, freeing up human resources for more strategic activities. +By treating documentation as a core product component, we ensure continuity, scalability, and user satisfaction. -The integration of autonomous LLM agents in manufacturing environments opens up new possibilities for optimization, innovation, and growth. As we explore their applications throughout this blog, it's crucial to understand that these agents are not meant to replace human workers but to augment their capabilities and drive overall productivity. +--- -## 3. RAG Embedding Databases: The Knowledge Foundation +## 3. Understanding the Swarms Ecosystem -At the heart of effective autonomous LLM agents lies the Retrieval-Augmented Generation (RAG) embedding database. This technology serves as the knowledge foundation, enabling agents to access and utilize vast amounts of relevant information quickly and accurately. +The Swarms ecosystem consists of multiple tightly integrated components that serve developers and enterprise clients alike: -RAG embedding databases work by: -1. **Vectorizing Information**: Converting textual data into high-dimensional vectors that capture semantic meaning. +- **Core Documentation Repository**: The main documentation hub for all Swarms technologies [GitHub](https://github.com/kyegomez/swarms). -2. **Efficient Storage**: Organizing these vectors in a way that allows for rapid retrieval of relevant information. +- **Rust SDK (`swarms_rs`)**: Official documentation for the Rust implementation. [Repo](https://github.com/The-Swarm-Corporation/swarms-rs). -3. **Contextual Retrieval**: Enabling the agent to pull relevant information based on the current context or query. +- **Tools Documentation (`swarms_tools`)**: Guides for CLI and GUI utilities. -4. **Dynamic Updates**: Allowing for continuous updates to the knowledge base, ensuring the agent always has access to the most current information. +- **Hosted API Reference**: Up-to-date REST API documentation: [Swarms API Docs](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/). -In the manufacturing context, RAG embedding databases can store a wealth of information, including: +- **Marketplace & Chat**: Web platforms and communication interfaces [swarms.world](https://swarms.world). -- Technical specifications of machinery and products -- Historical production data and performance metrics -- Quality control guidelines and standards -- Supplier information and supply chain data -- Market trends and customer feedback +All contributions funnel through the `docs/` directory in the core repo and are structured via MkDocs. -By leveraging RAG embedding databases, autonomous LLM agents can make informed decisions based on a comprehensive understanding of the manufacturing ecosystem. This leads to more accurate predictions, better problem-solving capabilities, and the ability to generate innovative solutions. +--- -For example, when faced with a production bottleneck, an agent can quickly retrieve relevant historical data, equipment specifications, and best practices to propose an optimal solution. This rapid access to contextual information significantly reduces decision-making time and improves the quality of outcomes. +## 4. Documentation Tools and Platforms -## 4. Function Calling and External Tools: Enhancing Capabilities +Swarms documentation is powered by [MkDocs](https://www.mkdocs.org/), an extensible static site generator tailored for project documentation. To contribute, you should be comfortable with: -The true power of autonomous LLM agents in manufacturing environments is realized through their ability to interact with external systems and tools. This is achieved through function calling and integration with specialized external tools. +- **Markdown**: For formatting structure, code snippets, lists, and links. -Function calling allows the agent to: +- **MkDocs Configuration**: `mkdocs.yml` manages structure, theme, and navigation. -1. **Execute Specific Tasks**: Trigger predefined functions to perform complex operations or calculations. +- **Version Control**: GitHub for branching, version tracking, and collaboration. -2. **Interact with Databases**: Query and update various databases within the manufacturing ecosystem. +**Recommended Tooling:** -3. **Control Equipment**: Send commands to machinery or robotic systems on the production floor. +- Markdown linters to enforce syntax consistency. -4. **Generate Reports**: Automatically compile and format data into meaningful reports for different stakeholders. +- Spellcheckers to ensure grammatical accuracy. -External tools that can be integrated include: +- Doc generators for automated API reference extraction. -- **Predictive Maintenance Software**: To schedule and optimize equipment maintenance. -- **Supply Chain Management Systems**: For real-time tracking and optimization of inventory and logistics. -- **Quality Control Systems**: To monitor and analyze product quality metrics. -- **Energy Management Tools**: For monitoring and optimizing energy consumption across the facility. -- **Customer Relationship Management (CRM) Software**: To analyze customer data and improve service. +--- -By combining the cognitive abilities of LLM agents with the specialized functionalities of external tools, manufacturing enterprises can create a powerful ecosystem that drives efficiency and innovation. +## 5. Getting Started with Contributions -For instance, an autonomous agent could: +### 5.1 System Requirements -1. Detect an anomaly in production quality through data analysis. -2. Use function calling to query the maintenance database for equipment history. -3. Leverage an external predictive maintenance tool to assess the risk of equipment failure. -4. Automatically schedule maintenance and adjust production schedules to minimize downtime. -5. Generate a comprehensive report for management, detailing the issue, actions taken, and impact on production. -This level of integration and automation can lead to significant improvements in operational efficiency, cost reduction, and overall productivity. +- **Git** v2.30 or higher -## 5. Cost Reduction Strategies +- **Node.js** and **npm** for related dependency management -One of the primary benefits of implementing autonomous LLM agents in manufacturing is the potential for substantial cost reductions across various aspects of operations. Let's explore some key areas where these agents can drive down expenses: +- **MkDocs** and **Material for MkDocs** theme (`pip install mkdocs mkdocs-material`) -### 5.1. Optimizing Supply Chain Management +- A GitHub account with permissions to fork and submit pull requests -Autonomous LLM agents can revolutionize supply chain management by: +### 5.2 Forking the Swarms Repository -- **Predictive Inventory Management**: Analyzing historical data, market trends, and production schedules to optimize inventory levels, reducing carrying costs and minimizing stockouts. +1. Visit: `https://github.com/kyegomez/swarms` -- **Supplier Selection and Negotiation**: Evaluating supplier performance, market conditions, and contract terms to recommend the most cost-effective suppliers and negotiate better deals. +2. Click on **Fork** to create your version of the repository -- **Logistics Optimization**: Analyzing transportation routes, warehouse locations, and delivery schedules to minimize logistics costs and improve delivery times. +### 5.3 Clone and Configure Locally -Example: A large automotive manufacturer implemented an autonomous LLM agent to optimize its global supply chain. The agent analyzed data from multiple sources, including production schedules, supplier performance metrics, and global shipping trends. By optimizing inventory levels and renegotiating supplier contracts, the company reduced supply chain costs by 15% in the first year, resulting in savings of over $100 million. +```bash +git clone https://github.com//swarms.git +cd swarms/docs +git checkout -b feature/docs- +``` -### 5.2. Enhancing Quality Control +--- -Quality control is a critical aspect of manufacturing that directly impacts costs. Autonomous LLM agents can significantly improve quality control processes by: +## 6. Understanding the Repository Structure -- **Real-time Defect Detection**: Integrating with computer vision systems to identify and classify defects in real-time, reducing waste and rework. +Explore the documentation directory: -- **Root Cause Analysis**: Analyzing production data to identify the root causes of quality issues and recommending corrective actions. +```text +docs/ +├── index.md +├── mkdocs.yml +├── swarms_rs/ +│ ├── overview.md +│ └── ... +└── swarms_tools/ + ├── install.md + └── ... +``` -- **Predictive Quality Management**: Leveraging historical data and machine learning models to predict potential quality issues before they occur. +### 6.1 SDK/Tools Directories -Example: A semiconductor manufacturer deployed an autonomous LLM agent to enhance its quality control processes. The agent analyzed data from multiple sensors on the production line, historical quality records, and equipment maintenance logs. By identifying subtle patterns that led to defects, the agent helped reduce scrap rates by 30% and improved overall yield by 5%, resulting in annual savings of $50 million. +- **Rust SDK (`docs/swarms_rs`)**: Guides, references, and API walkthroughs for the Rust-based implementation. -### 5.3. Streamlining Maintenance and Repairs +- **Swarms Tools (`docs/swarms_tools`)**: CLI guides, GUI usage instructions, and architecture documentation. -Effective maintenance is crucial for minimizing downtime and extending the lifespan of expensive manufacturing equipment. Autonomous LLM agents can optimize maintenance processes by: -- **Predictive Maintenance**: Analyzing equipment sensor data, maintenance history, and production schedules to predict when maintenance is needed, reducing unplanned downtime. +Add new `.md` files in the folder corresponding to your documentation type. -- **Maintenance Scheduling Optimization**: Balancing maintenance needs with production schedules to minimize disruptions and maximize equipment availability. +### 6.2 Configuring Navigation in MkDocs -- **Repair Knowledge Management**: Creating and maintaining a comprehensive knowledge base of repair procedures, making it easier for technicians to quickly address issues. +Update `mkdocs.yml` to integrate your new document: -Example: A paper mill implemented an autonomous LLM agent to manage its maintenance operations. The agent analyzed vibration data from critical equipment, historical maintenance records, and production schedules. By implementing a predictive maintenance strategy, the mill reduced unplanned downtime by 40% and extended the lifespan of key equipment by 25%, resulting in annual savings of $15 million in maintenance costs and lost production time. +```yaml +nav: + - Home: index.md + - Swarms Rust: + - Overview: swarms_rs/overview.md + - Your Topic: swarms_rs/your_file.md + - Swarms Tools: + - Installation: swarms_tools/install.md + - Your Guide: swarms_tools/your_file.md +``` -### 5.4. Improving Energy Efficiency +--- -Energy consumption is a significant cost factor in manufacturing. Autonomous LLM agents can help reduce energy costs by: +## 7. Writing and Editing Documentation -- **Real-time Energy Monitoring**: Analyzing energy consumption data across the facility to identify inefficiencies and anomalies. +### 7.1 Content Standards -- **Process Optimization for Energy Efficiency**: Recommending changes to production processes to reduce energy consumption without impacting output. -- **Demand Response Management**: Integrating with smart grid systems to optimize energy usage based on variable electricity prices and demand. +- **Clarity**: Explain complex ideas in simple, direct language. -Example: A large chemical manufacturing plant deployed an autonomous LLM agent to optimize its energy consumption. The agent analyzed data from thousands of sensors across the facility, weather forecasts, and electricity price fluctuations. By optimizing process parameters and scheduling energy-intensive operations during off-peak hours, the plant reduced its energy costs by 18%, saving $10 million annually. +- **Style Consistency**: Match the tone and structure of existing docs. -## 6. Revenue Growth Opportunities +- **Accuracy**: Validate all technical content and code snippets. -While cost reduction is crucial, autonomous LLM agents also present significant opportunities for revenue growth in manufacturing enterprises. Let's explore how these advanced AI systems can drive top-line growth: +- **Accessibility**: Include alt text for images and use semantic Markdown. -### 6.1. Product Innovation and Development +### 7.2 Markdown Best Practices -Autonomous LLM agents can accelerate and enhance the product innovation process by: +- Sequential heading levels (`#`, `##`, `###`) -- **Market Trend Analysis**: Analyzing vast amounts of market data, customer feedback, and industry reports to identify emerging trends and unmet needs. +- Use fenced code blocks with language identifiers -- **Design Optimization**: Leveraging generative design techniques and historical performance data to suggest optimal product designs that balance functionality, manufacturability, and cost. +- Create readable line spacing and avoid unnecessary line breaks -- **Rapid Prototyping Assistance**: Guiding engineers through the prototyping process, suggesting materials and manufacturing techniques based on design requirements and cost constraints. -Example: A consumer electronics manufacturer utilized an autonomous LLM agent to enhance its product development process. The agent analyzed social media trends, customer support tickets, and competitor product features to identify key areas for innovation. By suggesting novel features and optimizing designs for manufacturability, the company reduced time-to-market for new products by 30% and increased the success rate of new product launches by 25%, resulting in a 15% increase in annual revenue. +### 7.3 File Placement Protocol -### 6.2. Personalized Customer Experiences +Place `.md` files into the correct subdirectory: -In the age of mass customization, providing personalized experiences can significantly boost customer satisfaction and revenue. Autonomous LLM agents can facilitate this by: -- **Customer Preference Analysis**: Analyzing historical purchase data, customer interactions, and market trends to predict individual customer preferences. +- **Rust SDK Docs**: `docs/swarms_rs/` -- **Dynamic Product Configuration**: Enabling real-time product customization based on customer inputs and preferences, while ensuring manufacturability. +- **Tooling Docs**: `docs/swarms_tools/` -- **Personalized Marketing and Sales Support**: Generating tailored marketing content and sales recommendations for each customer or market segment. +--- -Example: A high-end furniture manufacturer implemented an autonomous LLM agent to power its online customization platform. The agent analyzed customer behavior, design trends, and production capabilities to offer personalized product recommendations and customization options. This led to a 40% increase in online sales and a 20% increase in average order value, driving significant revenue growth. +## 8. Updating Navigation Configuration -### 6.3. Market Analysis and Trend Prediction +After writing your content: -Staying ahead of market trends is crucial for maintaining a competitive edge. Autonomous LLM agents can provide valuable insights by: +1. Open `mkdocs.yml` +2. Identify where your file belongs +3. Add it to the `nav` hierarchy +4. Preview changes: -- **Competitive Intelligence**: Analyzing competitor activities, product launches, and market positioning to identify threats and opportunities. +```bash +mkdocs serve +# Open http://127.0.0.1:8000 to verify output +``` -- **Demand Forecasting**: Combining historical sales data, economic indicators, and market trends to predict future demand more accurately. +--- -- **Emerging Market Identification**: Analyzing global economic data, demographic trends, and industry reports to identify promising new markets for expansion. +## 9. Workflow: Branches, Commits, Pull Requests -Example: A global automotive parts manufacturer employed an autonomous LLM agent to enhance its market intelligence capabilities. The agent analyzed data from industry reports, social media, patent filings, and economic indicators to predict the growth of electric vehicle adoption in different regions. This insight allowed the company to strategically invest in EV component manufacturing, resulting in a 30% year-over-year growth in this high-margin segment. +### 9.1 Branch Naming Guidelines -### 6.4. Optimizing Pricing Strategies +- Use prefix and description, e.g.: + - `feature/docs-api-pagination` -Pricing is a critical lever for revenue growth. Autonomous LLM agents can optimize pricing strategies by: + - `fix/docs-typo-tooling` -- **Dynamic Pricing Models**: Analyzing market conditions, competitor pricing, and demand fluctuations to suggest optimal pricing in real-time. +### 9.2 Writing Clear Commits -- **Value-based Pricing Analysis**: Assessing customer perceived value through sentiment analysis and willingness-to-pay studies to maximize revenue. +Follow [Conventional Commits](https://www.conventionalcommits.org/): -- **Bundle and Discount Optimization**: Recommending product bundles and discount structures that maximize overall revenue and profitability. +```bash +docs(swarms_rs): add stream API tutorial +docs(swarms_tools): correct CLI usage example +``` -Example: A industrial equipment manufacturer implemented an autonomous LLM agent to optimize its pricing strategy. The agent analyzed historical sales data, competitor pricing, economic indicators, and customer sentiment to recommend dynamic pricing models for different product lines and markets. This resulted in a 10% increase in profit margins and a 7% boost in overall revenue within the first year of implementation. +### 9.3 Submitting a Pull Request -## 7. Implementation Strategies +1. Push your feature branch +2. Open a new PR to the main repository +3. Use a descriptive title and include: + - Summary of changes + - Justification + - Screenshots or previews +4. Tag relevant reviewers and apply labels (`documentation`, `bounty-eligible`) -Successfully implementing autonomous LLM agents in a manufacturing environment requires a strategic approach. Here are key steps and considerations for executives and CEOs: +--- -1. **Start with a Clear Vision and Objectives**: - - Define specific goals for cost reduction and revenue growth. - - Identify key performance indicators (KPIs) to measure success. +## 10. Review, QA, and Merging -2. **Conduct a Comprehensive Readiness Assessment**: - - Evaluate existing IT infrastructure and data management systems. - - Assess the quality and accessibility of historical data. - - Identify potential integration points with existing systems and processes. +Every PR undergoes automated and human review: -3. **Build a Cross-functional Implementation Team**: - - Include representatives from IT, operations, engineering, and business strategy. - - Consider partnering with external AI and manufacturing technology experts. +- **CI Checks**: Syntax validation, link checking, and formatting -4. **Develop a Phased Implementation Plan**: - - Start with pilot projects in specific areas (e.g., predictive maintenance or supply chain optimization). - - Scale successful pilots across the organization. +- **Manual Review**: Maintain clarity, completeness, and relevance -5. **Invest in Data Infrastructure and Quality**: - - Ensure robust data collection and storage systems are in place. - - Implement data cleaning and standardization processes. +- **Iteration**: Collaborate through feedback and finalize changes +Once approved, maintainers will merge and deploy the updated documentation. +--- -6. **Choose the Right LLM and RAG Technologies**: - - Evaluate different LLM options based on performance, cost, and specific manufacturing requirements. - - Select RAG embedding databases that can efficiently handle the scale and complexity of manufacturing data. +## 11. Swarms Documentation Bounty Initiative -7. **Develop a Robust Integration Strategy**: - - Plan for seamless integration with existing ERP, MES, and other critical systems. - - Ensure proper API development and management for connecting with external tools and databases. +To foster continuous improvement, we offer structured rewards for eligible contributions: -8. **Prioritize Security and Compliance**: - - Implement strong data encryption and access control measures. - - Ensure compliance with industry regulations and data privacy laws. +### 11.1 Contribution Types -9. **Invest in Change Management and Training**: - - Develop comprehensive training programs for employees at all levels. - - Communicate the benefits and address concerns about AI implementation. -10. **Establish Governance and Oversight**: - - Create a governance structure to oversee the use and development of AI systems. - - Implement ethical guidelines for AI decision-making. +- Creating comprehensive new tutorials and deep dives -11. **Plan for Continuous Improvement**: - - Set up feedback loops to continuously refine and improve the AI systems. - - Stay updated on advancements in LLM and RAG technologies. +- Updating outdated references and examples -Example: A leading automotive manufacturer implemented autonomous LLM agents across its global operations using a phased approach. They started with a pilot project in predictive maintenance at a single plant, which reduced downtime by 25%. Building on this success, they expanded to supply chain optimization and quality control. Within three years, the company had deployed AI agents across all major operations, resulting in a 12% reduction in overall production costs and a 9% increase in productivity. +- Fixing typos, grammar, and formatting errors -## 8. Overcoming Challenges and Risks +- Translating existing content -While the benefits of autonomous LLM agents in manufacturing are substantial, there are several challenges and risks that executives must address: +### 11.2 Reward Structure -### Data Quality and Availability +| Tier | Description | Payout (USD) | +|----------|--------------------------------------------------------|------------------| +| Bronze | Typos or minor enhancements (< 100 words) | $1 - $5 | +| Silver | Small tutorials, API examples (100–500 words) | $5 - $20 | +| Gold | Major updates or guides (> 500 words) | $20 - $50 | +| Platinum | Multi-part guides or new documentation verticals | $50 - 300 | -**Challenge**: Manufacturing environments often have siloed, inconsistent, or incomplete data, which can hinder the effectiveness of AI systems. +### 11.3 Claiming Bounties -**Solution**: -- Invest in data infrastructure and standardization across the organization. -- Implement data governance policies to ensure consistent data collection and management. -- Use data augmentation techniques to address gaps in historical data. +1. Label your PR `bounty-eligible` +2. Describe expected tier and rationale +3. Review team assesses scope and assigns reward +4. Rewards paid post-merge via preferred method (PayPal, crypto, or wire) -### Integration with Legacy Systems +--- -**Challenge**: Many manufacturing facilities rely on legacy systems that may not easily integrate with modern AI technologies. +## 12. Best Practices for Efficient Contribution -**Solution**: -- Develop custom APIs and middleware to facilitate communication between legacy systems and AI agents. -- Consider a gradual modernization strategy, replacing legacy systems over time. -- Use edge computing devices to bridge the gap between old equipment and new AI systems. +- **Stay Updated**: Sync your fork weekly to avoid merge conflicts -### Workforce Adaptation and Resistance +- **Atomic PRs**: Submit narrowly scoped changes for faster review -**Challenge**: Employees may resist AI implementation due to fear of job displacement or lack of understanding. +- **Use Visuals**: Support documentation with screenshots or diagrams -**Solution**: -- Emphasize that AI is a tool to augment human capabilities, not replace workers. -- Provide comprehensive training programs to upskill employees. -- Involve workers in the AI implementation process to gain buy-in and valuable insights. +- **Cross-Reference**: Link to related documentation for completeness -### Ethical Considerations and Bias +- **Version Awareness**: Specify SDK/tool versions in code examples -**Challenge**: AI systems may inadvertently perpetuate biases present in historical data or decision-making processes. +--- -**Solution**: -- Implement rigorous testing for bias in AI models and decisions. -- Establish an ethics committee to oversee AI implementations. -- Regularly audit AI systems for fairness and unintended consequences. +## 13. Style Guide Snapshot -### Security and Intellectual Property Protection -**Challenge**: AI systems may be vulnerable to cyber attacks or could potentially expose sensitive manufacturing processes. +- **Voice**: Informative, concise, and respectful -**Solution**: -- Implement robust cybersecurity measures, including encryption and access controls. -- Develop clear policies on data handling and AI model ownership. -- Regularly conduct security audits and penetration testing. +- **Terminology**: Use standardized terms (`Swarm`, `Swarms`) consistently -Example: A pharmaceutical manufacturer faced challenges integrating AI agents with its highly regulated production processes. They addressed this by creating a cross-functional team of IT specialists, process engineers, and compliance officers. This team developed a custom integration layer that allowed AI agents to interact with existing systems while maintaining regulatory compliance. They also implemented a rigorous change management process, which included extensive training and a phased rollout. As a result, they successfully deployed AI agents that optimized production scheduling and quality control, leading to a 15% increase in throughput and a 30% reduction in quality-related issues. +- **Code**: Format snippets using language-specific linters -## 9. Case Studies +- **Accessibility**: Include alt attributes and avoid ambiguous links -To illustrate the transformative potential of autonomous LLM agents in manufacturing, let's examine several real-world case studies: +--- -### Case Study 1: Global Electronics Manufacturer +## 14. Monitoring & Improving Documentation Health -**Challenge**: A leading electronics manufacturer was struggling with supply chain disruptions and rising production costs. +We use analytics and community input to prioritize improvements: -**Solution**: They implemented an autonomous LLM agent integrated with their supply chain management system and production planning tools. +- **Traffic Reports**: Track most/least visited pages -**Results**: -- 22% reduction in inventory carrying costs -- 18% improvement in on-time deliveries -- 15% decrease in production lead times -- $200 million annual cost savings +- **Search Logs**: Detect content gaps from common search terms -**Key Factors for Success**: -- Comprehensive integration with existing systems -- Real-time data processing capabilities -- Continuous learning and optimization algorithms +- **Feedback Forms**: Collect real-world user input -### Case Study 2: Automotive Parts Supplier +Schedule quarterly audits to refine structure and content across all repositories. -**Challenge**: An automotive parts supplier needed to improve quality control and reduce warranty claims. +--- -**Solution**: They deployed an AI-powered quality control system using computer vision and an autonomous LLM agent for defect analysis and prediction. +## 15. Community Promotion & Engagement -**Results**: -- 40% reduction in defect rates -- 60% decrease in warranty claims -- 25% improvement in overall equipment effectiveness (OEE) -- $75 million annual savings in quality-related costs +Promote your contributions via: -**Key Factors for Success**: -- High-quality image data collection system -- Integration of domain expertise into the AI model -- Continuous feedback loop for model improvement -### Case Study 3: Food and Beverage Manufacturer +- **Swarms Discord**: https://discord.gg/jM3Z6M9uMq -**Challenge**: A large food and beverage manufacturer wanted to optimize its energy consumption and reduce waste in its production processes. +- **Swarms Telegram**: https://t.me/swarmsgroupchat -**Solution**: They implemented an autonomous LLM agent that integrated with their energy management systems and production equipment. +- **Swarms Twitter**: https://x.com/swarms_corp -**Results**: -- 20% reduction in energy consumption -- 30% decrease in production waste -- 12% increase in overall production efficiency -- $50 million annual cost savings -- Significant progress towards sustainability goals +- **Startup Program Showcases**: https://www.swarms.xyz/programs/startups -**Key Factors for Success**: -- Comprehensive sensor network for real-time data collection -- Integration with smart grid systems for dynamic energy management -- Collaboration with process engineers to refine AI recommendations +Active contributors are often spotlighted for leadership roles and community awards. -### Case Study 4: Aerospace Component Manufacturer +--- -**Challenge**: An aerospace component manufacturer needed to accelerate product development and improve first-time-right rates for new designs. +## 16. Resource Index -**Solution**: They implemented an autonomous LLM agent to assist in the design process, leveraging historical data, simulation results, and industry standards. +- Core GitHub Repo: https://github.com/kyegomez/swarms -**Results**: -- 35% reduction in design cycle time -- 50% improvement in first-time-right rates for new designs -- 20% increase in successful patent applications -- $100 million increase in annual revenue from new products +- Rust SDK Repo: https://github.com/The-Swarm-Corporation/swarms-rs -**Key Factors for Success**: -- Integration of CAD systems with the AI agent -- Incorporation of aerospace industry standards and regulations into the AI knowledge base -- Collaborative approach between AI and human engineers +- Swarms API Docs: https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/ -These case studies demonstrate the wide-ranging benefits of autonomous LLM agents across various manufacturing sectors. The key takeaway is that successful implementation requires a holistic approach, combining technology integration, process redesign, and a focus on continuous improvement. +- Marketplace: https://swarms.world -## 10. Future Outlook +Join our monthly Documentation Office Hours for real-time mentorship and Q&A. -As we look to the future of manufacturing, the role of autonomous LLM agents is set to become even more critical. Here are some key trends and developments that executives should keep on their radar: +--- -### 1. Advanced Natural Language Interfaces +## 17. Frequently Asked Questions -Future LLM agents will feature more sophisticated natural language interfaces, allowing workers at all levels to interact with complex manufacturing systems using conversational language. This will democratize access to AI capabilities and enhance overall operational efficiency. +**Q1: Is MkDocs required to contribute?** +A: It's recommended but not required; Markdown knowledge is sufficient to get started. -### 2. Enhanced Multi-modal Learning +**Q2: Can I rework existing sections?** +A: Yes, propose changes via issues first, or submit PRs with clear descriptions. -Next-generation agents will be able to process and analyze data from a wider range of sources, including text, images, video, and sensor data. This will enable more comprehensive insights and decision-making capabilities across the manufacturing ecosystem. +**Q3: When are bounties paid?** +A: Within 30 days of merge, following internal validation. -### 3. Collaborative AI Systems +--- -We'll see the emergence of AI ecosystems where multiple specialized agents collaborate to solve complex manufacturing challenges. For example, a design optimization agent might work in tandem with a supply chain agent and a quality control agent to develop new products that are optimized for both performance and manufacturability. +## 18. Final Thoughts -### 4. Quantum-enhanced AI +The Swarms documentation is a critical piece of our technology stack. As a contributor, your improvements—big or small—directly impact adoption, user retention, and developer satisfaction. This guide aims to equip you with the tools, practices, and incentives to make meaningful contributions. Your work helps us deliver a more usable, scalable, and inclusive platform. -As quantum computing becomes more accessible, it will significantly enhance the capabilities of LLM agents, particularly in complex optimization problems common in manufacturing. This could lead to breakthroughs in areas such as materials science and process optimization. +We look forward to your pull requests, feedback, and ideas. -### 5. Augmented Reality Integration +--- -LLM agents will increasingly be integrated with augmented reality (AR) systems, providing real-time guidance and information to workers on the factory floor. This could revolutionize training, maintenance, and quality control processes. -### 6. Autonomous Factories +-------------------------------------------------- -The ultimate vision is the development of fully autonomous factories where LLM agents orchestrate entire production processes with minimal human intervention. While this is still on the horizon, progressive implementation of autonomous systems will steadily move the industry in this direction. +# File: contributors\environment_setup.md -### 7. Ethical AI and Explainable Decision-Making +# Environment Setup Guide for Swarms Contributors -As AI systems become more prevalent in critical manufacturing decisions, there will be an increased focus on developing ethical AI frameworks and enhancing the explainability of AI decision-making processes. This will be crucial for maintaining trust and meeting regulatory requirements. +Welcome to the Swarms development environment setup guide! This comprehensive guide will walk you through setting up your development environment from scratch, whether you're a first-time contributor or an experienced developer. -### 8. Circular Economy Optimization +!!! success "🚀 One-Click Setup (Recommended)" + **New!** Use our automated setup script that handles everything: + ```bash + git clone https://github.com/kyegomez/swarms.git + cd swarms + chmod +x scripts/setup.sh + ./scripts/setup.sh + ``` + This script automatically installs Poetry, creates a virtual environment, installs all dependencies, sets up pre-commit hooks, and more! -Future LLM agents will play a key role in optimizing manufacturing processes for sustainability and circular economy principles. This will include enhancing recycling processes, optimizing resource use, and designing products for easy disassembly and reuse. +!!! info "Manual Setup" + **Alternative**: For manual control, install Python 3.10+, Git, and Poetry, then run: + ```bash + git clone https://github.com/kyegomez/swarms.git + cd swarms + poetry install --with dev + ``` -To stay ahead in this rapidly evolving landscape, manufacturing executives should: +--- -1. **Foster a Culture of Innovation**: Encourage experimentation with new AI technologies and applications. +## :material-list-status: Prerequisites -2. **Invest in Continuous Learning**: Ensure your workforce is constantly upskilling to work effectively with advanced AI systems. +Before setting up your development environment, ensure you have the following installed: -3. **Collaborate with AI Research Institutions**: Partner with universities and research labs to stay at the forefront of AI advancements in manufacturing. +### System Requirements -4. **Participate in Industry Consortiums**: Join manufacturing technology consortiums to share knowledge and shape industry standards for AI adoption. +| Tool | Version | Purpose | +|------|---------|---------| +| **Python** | 3.10+ | Core runtime | +| **Git** | 2.30+ | Version control | +| **Poetry** | 1.4+ | Dependency management (recommended) | +| **Node.js** | 16+ | Documentation tools (optional) | -5. **Develop Flexible and Scalable AI Infrastructure**: Build systems that can easily incorporate new AI capabilities as they emerge. +### Operating System Support -6. **Monitor Regulatory Developments**: Stay informed about evolving regulations related to AI in manufacturing to ensure compliance and competitive advantage. +=== "macOS" + + ```bash + # Install Homebrew if not already installed + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + + # Install prerequisites + brew install python@3.10 git poetry node + ``` -By embracing these future trends and preparing their organizations accordingly, manufacturing executives can position their companies to thrive in the AI-driven future of industry. +=== "Ubuntu/Debian" + + ```bash + # Update package list + sudo apt update + + # Install Python 3.10 and pip + sudo apt install python3.10 python3.10-venv python3-pip git curl + + # Install Poetry + curl -sSL https://install.python-poetry.org | python3 - + + # Add Poetry to PATH + export PATH="$HOME/.local/bin:$PATH" + echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc + ``` -## 11. Conclusion +=== "Windows" + + 1. **Install Python 3.10+** from [python.org](https://python.org/downloads/) + 2. **Install Git** from [git-scm.com](https://git-scm.com/download/win) + 3. **Install Poetry** using PowerShell: + ```powershell + (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python - + ``` -The integration of autonomous LLM agents with RAG embedding databases, function calling, and external tools represents a paradigm shift in manufacturing. This technology has the potential to dramatically reduce costs, drive revenue growth, and revolutionize how manufacturing enterprises operate. +--- -Key takeaways for executives and CEOs: +## :material-auto-fix: Automated Setup (Recommended) -1. **Transformative Potential**: Autonomous LLM agents can impact every aspect of manufacturing, from supply chain optimization to product innovation. +We provide a comprehensive setup script that automates the entire development environment setup process. This is the **recommended approach** for new contributors. -2. **Data-Driven Decision Making**: These AI systems enable more informed, real-time decision-making based on comprehensive data analysis. +### What the Setup Script Does -3. **Competitive Advantage**: Early adopters of this technology are likely to gain significant competitive advantages in terms of efficiency, quality, and innovation. +The `scripts/setup.sh` script automatically handles: -4. **Holistic Implementation**: Success requires a strategic approach that addresses technology, processes, and people. +- ✅ **Python Version Check**: Verifies Python 3.10+ is installed +- ✅ **Poetry Installation**: Installs Poetry if not present +- ✅ **Virtual Environment**: Creates and configures a project-specific virtual environment +- ✅ **Dependencies**: Installs all main, development, lint, and test dependencies +- ✅ **Pre-commit Hooks**: Sets up and installs pre-commit hooks for code quality +- ✅ **Environment Template**: Creates a `.env` file template with common variables +- ✅ **Verification**: Runs initial setup verification checks +- ✅ **Helpful Output**: Provides colored output and next steps -5. **Continuous Evolution**: The field of AI in manufacturing is rapidly advancing, necessitating ongoing investment and adaptation. +### Running the Automated Setup -6. **Ethical Considerations**: As AI becomes more prevalent, addressing ethical concerns and maintaining transparency will be crucial. +```bash +# Clone the repository +git clone https://github.com/kyegomez/swarms.git +cd swarms -7. **Future Readiness**: Preparing for future developments, such as quantum-enhanced AI and autonomous factories, will be key to long-term success. +# Make the script executable and run it +chmod +x scripts/setup.sh +./scripts/setup.sh +``` -The journey to implement autonomous LLM agents in manufacturing is complex but potentially transformative. It requires vision, commitment, and a willingness to reimagine traditional manufacturing processes. However, the potential rewards – in terms of cost savings, revenue growth, and competitive advantage – are substantial. +### Script Features -As a manufacturing executive or CEO, your role is to lead this transformation, fostering a culture of innovation and continuous improvement. By embracing the power of autonomous LLM agents, you can position your organization at the forefront of the next industrial revolution, driving sustainable growth and success in an increasingly competitive global marketplace. +=== "🎯 Smart Detection" + The script intelligently detects your system state: + - Checks if Poetry is already installed + - Verifies Python version compatibility + - Detects existing virtual environments + - Checks for Git repository status -The future of manufacturing is intelligent, autonomous, and data-driven. The time to act is now. Embrace the potential of autonomous LLM agents and lead your organization into a new era of manufacturing excellence. +=== "🔧 Comprehensive Setup" + Installs everything you need: + ```bash + # All dependency groups + poetry install --with dev,lint,test + + # Pre-commit hooks + pre-commit install + pre-commit install --hook-type commit-msg + + # Initial verification run + pre-commit run --all-files + ``` --------------------------------------------------- +=== "📋 Environment Template" + Creates a starter `.env` file: + ```bash + # Generated .env template + OPENAI_API_KEY=your_openai_api_key_here + ANTHROPIC_API_KEY=your_anthropic_key_here + LOG_LEVEL=INFO + DEVELOPMENT=true + ``` -# File: applications/business-analyst-agent.md +=== "💡 Helpful Guidance" + Provides next steps and useful commands: + - How to activate the virtual environment + - Essential Poetry commands + - Testing and development workflow + - Troubleshooting tips -## Building Analyst Agents with Swarms to write Business Reports +### When to Use Manual Setup -> Jupyter Notebook accompanying this post is accessible at: [Business Analyst Agent Notebook](https://github.com/kyegomez/swarms/blob/master/examples/demos/business_analysis_swarm/business-analyst-agent.ipynb) +Use the manual setup approach if you: +- Want full control over each step +- Have specific system requirements +- Are troubleshooting installation issues +- Prefer to understand each component -Solving a business problem often involves preparing a Business Case Report. This report comprehensively analyzes the problem, evaluates potential solutions, and provides evidence-based recommendations and an implementation plan to effectively address the issue and drive business value. While the process of preparing one requires an experienced business analyst, the workflow can be augmented using AI agents. Two candidates stick out as areas to work on: +--- -- Developing an outline to solve the problem -- Doing background research and gathering data - -In this post, we will explore how Swarms agents can be used to tackle a busuiness problem by outlining the solution, conducting background research and generating a preliminary report. +## :material-git: Repository Setup -Before we proceed, this blog uses 3 API tools. Please obtain the following keys and store them in a `.env` file in the same folder as this file. +### Step 1: Fork and Clone -- **[OpenAI API](https://openai.com/blog/openai-api)** as `OPENAI_API_KEY` -- **[TavilyAI API](https://app.tavily.com/home)** `TAVILY_API_KEY` -- **[KayAI API](https://www.kay.ai/)** as `KAY_API_KEY` +1. **Fork the repository** on GitHub: [github.com/kyegomez/swarms](https://github.com/kyegomez/swarms) -```python -import dotenv -dotenv.load_dotenv() # Load environment variables from .env file +2. **Clone your fork**: +```bash +git clone https://github.com/YOUR_USERNAME/swarms.git +cd swarms ``` -### Developing an Outline to solve the problem - -Assume the business problem is: **How do we improve Nike's revenue in Q3 2024?** We first create a planning agent to break down the problem into dependent sub-problems. +3. **Add upstream remote**: +```bash +git remote add upstream https://github.com/kyegomez/swarms.git +``` +4. **Verify remotes**: +```bash +git remote -v +# origin https://github.com/YOUR_USERNAME/swarms.git (fetch) +# origin https://github.com/YOUR_USERNAME/swarms.git (push) +# upstream https://github.com/kyegomez/swarms.git (fetch) +# upstream https://github.com/kyegomez/swarms.git (push) +``` -#### Step 1. Defining the Data Model and Tool Schema +--- -Using Pydantic, we define a structure to help the agent generate sub-problems. +## :material-package-variant: Dependency Management -- **QueryType:** Questions are either standalone or involve a combination of multiple others -- **Query:** Defines structure of a question. -- **QueryPlan:** Allows generation of a dependency graph of sub-questions +Choose your preferred method for managing dependencies: +=== "Poetry (Recommended)" + + Poetry provides superior dependency resolution and virtual environment management. -```python -import enum -from typing import List -from pydantic import Field, BaseModel + ### Installation + + ```bash + # Navigate to project directory + cd swarms + + # Install all dependencies including development tools + poetry install --with dev,lint,test + + # Activate the virtual environment + poetry shell + ``` -class QueryType(str, enum.Enum): - """Enumeration representing the types of queries that can be asked to a question answer system.""" + ### Useful Poetry Commands + + ```bash + # Add a new dependency + poetry add package_name + + # Add a development dependency + poetry add --group dev package_name + + # Update dependencies + poetry update + + # Show dependency tree + poetry show --tree + + # Run commands in the virtual environment + poetry run python your_script.py + ``` - SINGLE_QUESTION = "SINGLE" - MERGE_MULTIPLE_RESPONSES = "MERGE_MULTIPLE_RESPONSES" +=== "pip + venv" + + Traditional pip-based setup with virtual environments. -class Query(BaseModel): - """Class representing a single question in a query plan.""" + ### Installation + + ```bash + # Navigate to project directory + cd swarms + + # Create virtual environment + python -m venv venv + + # Activate virtual environment + # On macOS/Linux: + source venv/bin/activate + # On Windows: + venv\Scripts\activate + + # Upgrade pip + pip install --upgrade pip + + # Install core dependencies + pip install -r requirements.txt + + # Install documentation dependencies (optional) + pip install -r docs/requirements.txt + ``` - id: int = Field(..., description="Unique id of the query") - question: str = Field( - ..., - description="Question asked using a question answering system", - ) - dependencies: List[int] = Field( - default_factory=list, - description="List of sub questions that need to be answered before asking this question", - ) - node_type: QueryType = Field( - default=QueryType.SINGLE_QUESTION, - description="Type of question, either a single question or a multi-question merge", - ) +--- -class QueryPlan(BaseModel): - """Container class representing a tree of questions to ask a question answering system.""" +## :material-tools: Development Tools Setup - query_graph: List[Query] = Field( - ..., description="The query graph representing the plan" - ) +### Code Quality Tools - def _dependencies(self, ids: List[int]) -> List[Query]: - """Returns the dependencies of a query given their ids.""" - - return [q for q in self.query_graph if q.id in ids] -``` +Swarms uses several tools to maintain code quality: -Also, a `tool_schema` needs to be defined. It is an instance of `QueryPlan` and is used to initialize the agent. +=== "Formatting" + + **Black** - Code formatter + ```bash + # Format code + poetry run black swarms/ + # or with pip: + black swarms/ + + # Check formatting without making changes + black swarms/ --check --diff + ``` -```python -tool_schema = QueryPlan( - query_graph = [query.dict() for query in [ - Query( - id=1, - question="How do we improve Nike's revenue in Q3 2024?", - dependencies=[2], - node_type=QueryType('SINGLE') - ), - # ... other queries ... - ]] -) -``` +=== "Linting" + + **Ruff** - Fast Python linter + ```bash + # Run linter + poetry run ruff check swarms/ + # or with pip: + ruff check swarms/ + + # Auto-fix issues + ruff check swarms/ --fix + ``` -#### Step 2. Defining the Planning Agent +=== "Type Checking" + + **MyPy** - Static type checker + ```bash + # Run type checking + poetry run mypy swarms/ + # or with pip: + mypy swarms/ + ``` -We specify the query, task specification and an appropriate system prompt. +### Pre-commit Hooks (Optional but Recommended) -```python -from swarm_models import OpenAIChat -from swarms import Agent +Set up pre-commit hooks to automatically run quality checks: -query = "How do we improve Nike's revenue in Q3 2024?" -task = f"Consider: {query}. Generate just the correct query plan in JSON format." -system_prompt = ( - "You are a world class query planning algorithm " - "capable of breaking apart questions into its " - "dependency queries such that the answers can be " - "used to inform the parent question. Do not answer " - "the questions, simply provide a correct compute " - "graph with good specific questions to ask and relevant " - "dependencies. Before you call the function, think " - "step-by-step to get a better understanding of the problem." - ) -llm = OpenAIChat( - temperature=0.0, model_name="gpt-4", max_tokens=4000 -) -``` +```bash +# Install pre-commit +poetry add --group dev pre-commit +# or with pip: +pip install pre-commit -Then, we proceed with agent definition. +# Install git hooks +pre-commit install -```python -# Initialize the agent -agent = Agent( - agent_name="Query Planner", - system_prompt=system_prompt, - # Set the tool schema to the JSON string -- this is the key difference - tool_schema=tool_schema, - llm=llm, - max_loops=1, - autosave=True, - dashboard=False, - streaming_on=True, - verbose=True, - interactive=False, - # Set the output type to the tool schema which is a BaseModel - output_type=tool_schema, # or dict, or str - metadata_output_type="json", - # List of schemas that the agent can handle - list_base_models=[tool_schema], - function_calling_format_type="OpenAI", - function_calling_type="json", # or soon yaml -) +# Run on all files +pre-commit run --all-files ``` -#### Step 3. Obtaining Outline from Planning Agent +The project uses the latest ruff-pre-commit configuration with separate hooks for linting and formatting: -We now run the agent, and since its output is in JSON format, we can load it as a dictionary. +- **ruff-check**: Runs the linter with automatic fixes (`--fix` flag) +- **ruff-format**: Runs the formatter for code styling +- **types_or: [python, pyi]**: Excludes Jupyter notebooks from processing -```python -generated_data = agent.run(task) -``` +This configuration ensures consistent code quality and style across the project while avoiding conflicts with Jupyter notebook files. -At times the agent could return extra content other than JSON. Below function will filter it out. +--- -```python -def process_json_output(content): - # Find the index of the first occurrence of '```json\n' - start_index = content.find('```json\n') - if start_index == -1: - # If '```json\n' is not found, return the original content - return content - # Return the part of the content after '```json\n' and remove the '```' at the end - return content[start_index + len('```json\n'):].rstrip('`') +## :material-test-tube: Testing Setup -# Use the function to clean up the output -json_content = process_json_output(generated_data.content) +### Running Tests -import json +```bash +# Run all tests +poetry run pytest +# or with pip: +pytest -# Load the JSON string into a Python object -json_object = json.loads(json_content) +# Run tests with coverage +poetry run pytest --cov=swarms tests/ -# Convert the Python object back to a JSON string -json_content = json.dumps(json_object, indent=2) +# Run specific test file +poetry run pytest tests/test_specific_file.py -# Print the JSON string -print(json_content) +# Run tests matching a pattern +poetry run pytest -k "test_agent" ``` -Below is the output this produces +### Test Structure -```json -{ - "main_query": "How do we improve Nike's revenue in Q3 2024?", - "sub_queries": [ - { - "id": "1", - "query": "What is Nike's current revenue trend?" - }, - { - "id": "2", - "query": "What are the projected market trends for the sports apparel industry in 2024?" - }, - { - "id": "3", - "query": "What are the current successful strategies being used by Nike's competitors?", - "dependencies": [ - "2" - ] - }, - { - "id": "4", - "query": "What are the current and projected economic conditions in Nike's major markets?", - "dependencies": [ - "2" - ] - }, - { - "id": "5", - "query": "What are the current consumer preferences in the sports apparel industry?", - "dependencies": [ - "2" - ] - }, - { - "id": "6", - "query": "What are the potential areas of improvement in Nike's current business model?", - "dependencies": [ - "1" - ] - }, - { - "id": "7", - "query": "What are the potential new markets for Nike to explore in 2024?", - "dependencies": [ - "2", - "4" - ] - }, - { - "id": "8", - "query": "What are the potential new products or services Nike could introduce in 2024?", - "dependencies": [ - "5" - ] - }, - { - "id": "9", - "query": "What are the potential marketing strategies Nike could use to increase its revenue in Q3 2024?", - "dependencies": [ - "3", - "5", - "7", - "8" - ] - }, - { - "id": "10", - "query": "What are the potential cost-saving strategies Nike could implement to increase its net revenue in Q3 2024?", - "dependencies": [ - "6" - ] - } - ] -} +The project uses pytest with the following structure: +``` +tests/ +├── agents/ # Agent-related tests +├── structs/ # Multi-agent structure tests +├── tools/ # Tool tests +├── utils/ # Utility tests +└── conftest.py # Test configuration ``` -The JSON dictionary is not convenient for humans to process. We make a directed graph out of it. +### Writing Tests ```python -import networkx as nx -import matplotlib.pyplot as plt -import textwrap -import random +# Example test file: tests/test_example.py +import pytest +from swarms import Agent + +def test_agent_creation(): + """Test that an agent can be created successfully.""" + agent = Agent( + agent_name="test_agent", + system_prompt="You are a helpful assistant" + ) + assert agent.agent_name == "test_agent" -# Create a directed graph -G = nx.DiGraph() +@pytest.mark.parametrize("input_val,expected", [ + ("hello", "HELLO"), + ("world", "WORLD"), +]) +def test_uppercase(input_val, expected): + """Example parametrized test.""" + assert input_val.upper() == expected +``` -# Define a color map -color_map = {} +--- -# Add nodes and edges to the graph -for sub_query in json_object['sub_queries']: - # Check if 'dependencies' key exists in sub_query, if not, initialize it as an empty list - if 'dependencies' not in sub_query: - sub_query['dependencies'] = [] - # Assign a random color for each node - color_map[sub_query['id']] = "#{:06x}".format(random.randint(0, 0xFFFFFF)) - G.add_node(sub_query['id'], label=textwrap.fill(sub_query['query'], width=20)) - for dependency in sub_query['dependencies']: - G.add_edge(dependency, sub_query['id']) +## :material-book-open-page-variant: Documentation Setup -# Draw the graph -pos = nx.spring_layout(G) -nx.draw(G, pos, with_labels=True, node_size=800, node_color=[color_map[node] for node in G.nodes()], node_shape="o", alpha=0.5, linewidths=40) +### Building Documentation Locally -# Prepare labels for legend -labels = nx.get_node_attributes(G, 'label') -handles = [plt.Line2D([0], [0], marker='o', color=color_map[node], label=f"{node}: {label}", markersize=10, linestyle='None') for node, label in labels.items()] +```bash +# Install documentation dependencies +pip install -r docs/requirements.txt -# Create a legend -plt.legend(handles=handles, title="Queries", bbox_to_anchor=(1.05, 1), loc='upper left') +# Navigate to docs directory +cd docs -plt.show() +# Serve documentation locally +mkdocs serve +# Documentation will be available at http://127.0.0.1:8000 ``` -This produces the below diagram which makes the plan much more convenient to understand. +### Documentation Structure -![Query Plan Diagram](../assets/img/docs/query-plan.png) +``` +docs/ +├── index.md # Homepage +├── mkdocs.yml # MkDocs configuration +├── swarms/ # Core documentation +├── examples/ # Examples and tutorials +├── contributors/ # Contributor guides +└── assets/ # Images and static files +``` -### Doing Background Research and Gathering Data +### Writing Documentation -At this point, we have solved the first half of the problem. We have an outline consisting of sub-problems to to tackled to solve our business problem. This will form the overall structure of our report. We now need to research information for each sub-problem in order to write an informed report. This mechanically intensive and is the aspect that will most benefit from Agentic intervention. +Use Markdown with MkDocs extensions: -Essentially, we can spawn parallel agents to gather the data. Each agent will have 2 tools: +```markdown +# Page Title -- Internet access -- Financial data retrieval +!!! tip "Pro Tip" + Use admonitions to highlight important information. -As they run parallelly, they will add their knowledge into a common long-term memory. We will then spawn a separate report writing agent with access to this memory to generate our business case report. +=== "Python" + ```python + from swarms import Agent + agent = Agent() + ``` -#### Step 4. Defining Tools for Worker Agents +=== "CLI" + ```bash + swarms create-agent --name myagent + ``` +``` -Let us first define the 2 tools. +--- -```python -import os -from typing import List, Dict +## :material-application-variable: Environment Variables -from swarms import tool +Create a `.env` file for local development: -os.environ['TAVILY_API_KEY'] = os.getenv('TAVILY_API_KEY') -os.environ["KAY_API_KEY"] = os.getenv('KAY_API_KEY') +```bash +# Copy example environment file +cp .env.example .env # if it exists -from langchain_community.tools.tavily_search import TavilySearchResults -from langchain_core.pydantic_v1 import BaseModel, Field +# Or create your own .env file +touch .env +``` -from kay.rag.retrievers import KayRetriever +Common environment variables: +```bash +# .env file +OPENAI_API_KEY=your_openai_api_key_here +ANTHROPIC_API_KEY=your_anthropic_api_key_here +GROQ_API_KEY=your_groq_api_key_here -def browser(query: str) -> str: - """ - Search the query in the browser with the Tavily API tool. - Args: - query (str): The query to search in the browser. - Returns: - str: The search results - """ - internet_search = TavilySearchResults() - results = internet_search.invoke({"query": query}) - response = '' - for result in results: - response += (result['content'] + '\n') - return response +# Development settings +DEBUG=true +LOG_LEVEL=INFO -def kay_retriever(query: str) -> str: - """ - Search the financial data query with the KayAI API tool. - Args: - query (str): The query to search in the KayRetriever. - Returns: - str: The first context retrieved as a string. - """ - # Initialize the retriever - retriever = KayRetriever(dataset_id = "company", data_types=["10-K", "10-Q", "8-K", "PressRelease"]) - # Query the retriever - context = retriever.query(query=query,num_context=1) - return context[0]['chunk_embed_text'] +# Optional: Database settings +DATABASE_URL=sqlite:///swarms.db ``` -#### Step 5. Defining Long-Term Memory - -As mentioned previously, the worker agents running parallelly, will pool their knowledge into a common memory. Let us define that. +--- -```python -import logging -import os -import uuid -from typing import Callable, List, Optional +## :material-check-circle: Verification Steps -import chromadb -import numpy as np -from dotenv import load_dotenv +!!! tip "Automated Verification" + If you used the automated setup script (`./scripts/setup.sh`), most verification steps are handled automatically. The script runs verification checks and reports any issues. -from swarms.utils.data_to_text import data_to_text -from swarms.utils.markdown_message import display_markdown_message -from swarms_memory import AbstractVectorDatabase +For manual setups, verify your setup is working correctly: +### 1. Basic Import Test +```bash +poetry run python -c "from swarms import Agent; print('✅ Import successful')" +``` -# Results storage using local ChromaDB -class ChromaDB(AbstractVectorDatabase): - """ +### 2. Run a Simple Agent +```python +# test_setup.py +from swarms import Agent - ChromaDB database +agent = Agent( + agent_name="setup_test", + system_prompt="You are a helpful assistant for testing setup.", + max_loops=1 +) - Args: - metric (str): The similarity metric to use. - output (str): The name of the collection to store the results in. - limit_tokens (int, optional): The maximum number of tokens to use for the query. Defaults to 1000. - n_results (int, optional): The number of results to retrieve. Defaults to 2. +response = agent.run("Say hello!") +print(f"✅ Agent response: {response}") +``` - Methods: - add: _description_ - query: _description_ - - Examples: - >>> chromadb = ChromaDB( - >>> metric="cosine", - >>> output="results", - >>> llm="gpt3", - >>> openai_api_key=OPENAI_API_KEY, - >>> ) - >>> chromadb.add(task, result, result_id) - """ +### 3. Code Quality Check +```bash +# Run all quality checks +poetry run black swarms/ --check +poetry run ruff check swarms/ +poetry run pytest tests/ -x +``` - def __init__( - self, - metric: str = "cosine", - output_dir: str = "swarms", - limit_tokens: Optional[int] = 1000, - n_results: int = 3, - embedding_function: Callable = None, - docs_folder: str = None, - verbose: bool = False, - *args, - **kwargs, - ): - self.metric = metric - self.output_dir = output_dir - self.limit_tokens = limit_tokens - self.n_results = n_results - self.docs_folder = docs_folder - self.verbose = verbose - - # Disable ChromaDB logging - if verbose: - logging.getLogger("chromadb").setLevel(logging.INFO) - - # Create Chroma collection - chroma_persist_dir = "chroma" - chroma_client = chromadb.PersistentClient( - settings=chromadb.config.Settings( - persist_directory=chroma_persist_dir, - ), - *args, - **kwargs, - ) +### 4. Documentation Build +```bash +cd docs +mkdocs build +echo "✅ Documentation built successfully" +``` - # Embedding model - if embedding_function: - self.embedding_function = embedding_function - else: - self.embedding_function = None +--- - # Create ChromaDB client - self.client = chromadb.Client() +## :material-rocket-launch: Development Workflow - # Create Chroma collection - self.collection = chroma_client.get_or_create_collection( - name=output_dir, - metadata={"hnsw:space": metric}, - embedding_function=self.embedding_function, - # data_loader=self.data_loader, - *args, - **kwargs, - ) - display_markdown_message( - "ChromaDB collection created:" - f" {self.collection.name} with metric: {self.metric} and" - f" output directory: {self.output_dir}" - ) +### Creating a Feature Branch - # If docs - if docs_folder: - display_markdown_message( - f"Traversing directory: {docs_folder}" - ) - self.traverse_directory() +```bash +# Sync with upstream +git fetch upstream +git checkout master +git rebase upstream/master - def add( - self, - document: str, - *args, - **kwargs, - ): - """ - Add a document to the ChromaDB collection. +# Create feature branch +git checkout -b feature/your-feature-name - Args: - document (str): The document to be added. - condition (bool, optional): The condition to check before adding the document. Defaults to True. +# Make your changes... +# Add and commit +git add . +git commit -m "feat: add your feature description" - Returns: - str: The ID of the added document. - """ - try: - doc_id = str(uuid.uuid4()) - self.collection.add( - ids=[doc_id], - documents=[document], - *args, - **kwargs, - ) - print('-----------------') - print("Document added successfully") - print('-----------------') - return doc_id - except Exception as e: - raise Exception(f"Failed to add document: {str(e)}") +# Push to your fork +git push origin feature/your-feature-name +``` - def query( - self, - query_text: str, - *args, - **kwargs, - ): - """ - Query documents from the ChromaDB collection. +### Daily Development Commands - Args: - query (str): The query string. - n_docs (int, optional): The number of documents to retrieve. Defaults to 1. +```bash +# Start development session +cd swarms +poetry shell # or source venv/bin/activate - Returns: - dict: The retrieved documents. - """ - try: - docs = self.collection.query( - query_texts=[query_text], - n_results=self.n_results, - *args, - **kwargs, - )["documents"] - return docs[0] - except Exception as e: - raise Exception(f"Failed to query documents: {str(e)}") +# Pull latest changes +git fetch upstream +git rebase upstream/master - def traverse_directory(self): - """ - Traverse through every file in the given directory and its subdirectories, - and return the paths of all files. - Parameters: - - directory_name (str): The name of the directory to traverse. - Returns: - - list: A list of paths to each file in the directory and its subdirectories. - """ - added_to_db = False +# Run tests during development +poetry run pytest tests/ -v - for root, dirs, files in os.walk(self.docs_folder): - for file in files: - file = os.path.join(self.docs_folder, file) - _, ext = os.path.splitext(file) - data = data_to_text(file) - added_to_db = self.add([data]) - print(f"{file} added to Database") +# Format and lint before committing +poetry run black swarms/ +poetry run ruff check swarms/ --fix - return added_to_db +# Run a quick smoke test +poetry run python -c "from swarms import Agent; print('✅ All good')" ``` -We can now proceed to initialize the memory. +--- -```python -from chromadb.utils import embedding_functions -default_ef = embedding_functions.DefaultEmbeddingFunction() +## :material-bug: Troubleshooting -memory = ChromaDB( - metric="cosine", - n_results=3, - output_dir="results", - embedding_function=default_ef -) -``` +!!! tip "First Step: Try the Automated Setup" + If you're experiencing setup issues, try running our automated setup script first: + ```bash + chmod +x scripts/setup.sh + ./scripts/setup.sh + ``` + This script handles most common setup problems automatically and provides helpful error messages. -#### Step 6. Defining Worker Agents +### Common Issues and Solutions -The Worker Agent sub-classes the `Agent` class. The only different between these 2 is in how the `run()` method works. In the `Agent` class, `run()` simply returns the set of tool commands to run, but does not execute it. We, however, desire this. In addition, after we run our tools, we get the relevant information as output. We want to add this information to our memory. Hence, to incorporate these 2 changes, we define `WorkerAgent` as follows. +=== "Poetry Issues" + + **Problem**: Poetry command not found + ```bash + # Solution: Add Poetry to PATH + export PATH="$HOME/.local/bin:$PATH" + # Add to your shell profile (.bashrc, .zshrc, etc.) + ``` + + **Problem**: Poetry install fails + ```bash + # Solution: Clear cache and reinstall + poetry cache clear --all pypi + poetry install --with dev + ``` -```python -class WorkerAgent(Agent): - def __init__(self, *args, **kwargs): - super().__init__(*args, **kwargs) +=== "Python Version Issues" - def run(self, task, *args, **kwargs): - response = super().run(task, *args, **kwargs) - print(response.content) + **Problem**: Wrong Python version + ```bash + # Check Python version + python --version + + # Use pyenv to manage Python versions + curl https://pyenv.run | bash + pyenv install 3.10.12 + pyenv local 3.10.12 + ``` - json_dict = json.loads(process_json_output(response.content)) +=== "Import Errors" + + **Problem**: Cannot import swarms modules + ```bash + # Ensure you're in the virtual environment + poetry shell + # or + source venv/bin/activate + + # Install in development mode + poetry install --with dev + # or + pip install -e . + ``` - #print(json.dumps(json_dict, indent=2)) - - if response!=None: - try: - commands = json_dict["commands"] - except: - commands = [json_dict['command']] - - for command in commands: - tool_name = command["name"] +=== "Test Failures" + + **Problem**: Tests fail due to missing dependencies + ```bash + # Install test dependencies + poetry install --with test + # or + pip install pytest pytest-cov pytest-mock + ``` - if tool_name not in ['browser', 'kay_retriever']: - continue - - query = command["args"]["query"] +### Getting Help + +If you encounter issues: + +1. **Check the FAQ** in the main documentation +2. **Search existing issues** on GitHub +3. **Ask in the Discord community**: [discord.gg/jM3Z6M9uMq](https://discord.gg/jM3Z6M9uMq) +4. **Create a GitHub issue** with: + - Your operating system + - Python version + - Error messages + - Steps to reproduce + +--- + +## :material-next-step: Next Steps - # Get the tool by its name - tool = globals()[tool_name] - tool_response = tool(query) +Now that your environment is set up: + +1. **Read the Contributing Guide**: [contributors/main.md](main.md) +2. **Explore the Codebase**: Start with `swarms/structs/agent.py` +3. **Run Examples**: Check out `examples/` directory +4. **Pick an Issue**: Look for `good-first-issue` labels on GitHub +5. **Join the Community**: Discord, Twitter, and GitHub discussions + +!!! success "You're Ready!" + Your Swarms development environment is now set up! You're ready to contribute to the most important technology for multi-agent collaboration. + +--- + +## :material-bookmark-outline: Quick Reference + +### Essential Commands + +```bash +# Setup (choose one) +./scripts/setup.sh # Automated setup (recommended) +poetry install --with dev # Manual dependency install + +# Daily workflow +poetry shell # Activate environment +poetry run pytest # Run tests +poetry run black swarms/ # Format code +poetry run ruff check swarms/ # Lint code + +# Git workflow +git fetch upstream # Get latest changes +git rebase upstream/master # Update your branch +git checkout -b feature/name # Create feature branch +git push origin feature/name # Push your changes - # Add tool's output to long term memory - self.long_term_memory.add(tool_response) +# Documentation +cd docs && mkdocs serve # Serve docs locally +mkdocs build # Build docs ``` -We can then instantiate an object of the `WorkerAgent` class. +### Project Structure -```python -worker_agent = WorkerAgent( - agent_name="Worker Agent", - system_prompt=( - "Autonomous agent that can interact with browser, " - "financial data retriever and other agents. Be Helpful " - "and Kind. Use the tools provided to assist the user. " - "Generate the plan with list of commands in JSON format." - ), - llm=OpenAIChat( - temperature=0.0, model_name="gpt-4", max_tokens=4000 -), - max_loops="auto", - autosave=True, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - interactive=True, - tools=[browser, kay_retriever], - long_term_memory=memory, - code_interpreter=True, -) +``` +swarms/ +├── swarms/ # Core package +│ ├── agents/ # Agent implementations +│ ├── structs/ # Multi-agent structures +│ ├── tools/ # Agent tools +│ └── utils/ # Utilities +├── examples/ # Usage examples +├── tests/ # Test suite +├── docs/ # Documentation +├── pyproject.toml # Poetry configuration +└── requirements.txt # Pip dependencies ``` -#### Step 7. Running the Worker Agents +Happy coding! 🚀 -At this point, we need to setup a concurrent workflow. While the order of adding tasks to the workflow doesn't matter (since they will all run concurrently late when executed), we can take some time to define an order for these tasks. This order will come in handy later when writing the report using our Writer Agent. +-------------------------------------------------- -The order we will follow is Breadth First Traversal (BFT) of the sub-queries in the graph we had made earlier (shown below again for reference). BFT makes sense to be used here because we want all the dependent parent questions to be answered before answering the child question. Also, since we could have independent subgraphs, we will also perform BFT separately on each subgraph. +# File: contributors\main.md -![Query Plan Mini](../assets/img/docs/query-plan-mini.png) +# Contributing to Swarms: Building the Infrastructure for The Agentic Economy -Below is the code that produces the order of processing sub-queries. +Multi-agent collaboration is the most important technology in human history. It will reshape civilization by enabling billions of autonomous agents to coordinate and solve problems at unprecedented scale. -```python -from collections import deque, defaultdict +!!! success "The Foundation of Tomorrow" + **Swarms** is the foundational infrastructure powering this autonomous economy. By contributing, you're building the systems that will enable the next generation of intelligent automation. -# Define the graph nodes -nodes = json_object['sub_queries'] +### What You're Building -# Create a graph from the nodes -graph = defaultdict(list) -for node in nodes: - for dependency in node['dependencies']: - graph[dependency].append(node['id']) +=== "Autonomous Systems" + **Autonomous Resource Allocation** + + Global supply chains and energy distribution optimized in real-time -# Find all nodes with no dependencies (potential starting points) -start_nodes = [node['id'] for node in nodes if not node['dependencies']] +=== "Intelligence Networks" + **Distributed Decision Making** + + Collaborative intelligence networks across industries and governments -# Adjust the BFT function to handle dependencies correctly -def bft_corrected(start, graph, nodes_info): - visited = set() - queue = deque([start]) - order = [] +=== "Smart Markets" + **Self-Organizing Markets** - while queue: - node = queue.popleft() - if node not in visited: - # Check if all dependencies of the current node are visited - node_dependencies = [n['id'] for n in nodes if n['id'] == node][0] - dependencies_met = all(dep in visited for dep in nodes_info[node_dependencies]['dependencies']) - - if dependencies_met: - visited.add(node) - order.append(node) - # Add only nodes to the queue whose dependencies are fully met - for next_node in graph[node]: - if all(dep in visited for dep in nodes_info[next_node]['dependencies']): - queue.append(next_node) - else: - # Requeue the node to check dependencies later - queue.append(node) + Agent-driven marketplaces that automatically balance supply and demand + +=== "Problem Solving" + **Collaborative Problem Solving** - return order + Massive agent swarms tackling climate change, disease, and scientific discovery -# Dictionary to access node information quickly -nodes_info = {node['id']: node for node in nodes} +=== "Infrastructure" + **Adaptive Infrastructure** + + Self-healing systems that evolve without human intervention -# Perform BFT for each unvisited start node using the corrected BFS function -visited_global = set() -bfs_order = [] +--- -for start in start_nodes: - if start not in visited_global: - order = bft_corrected(start, graph, nodes_info) - bfs_order.extend(order) - visited_global.update(order) +## Why Contribute to Swarms? -print("BFT Order:", bfs_order) -``` +### :material-rocket-launch: Shape the Future of Civilization -This produces the following output. +!!! abstract "Your Impact" + - Define standards for multi-agent communication protocols + - Build architectural patterns for distributed intelligence systems + - Create frameworks for deploying agent swarms in production + - Establish ethical guidelines for autonomous agent collaboration -```python -BFT Order: ['1', '6', '10', '2', '3', '4', '5', '7', '8', '9'] -``` +### :material-trophy: Recognition and Professional Development -Now, let's define our `ConcurrentWorkflow` and run it. +!!! tip "Immediate Recognition" + - **Social Media Features** - All merged PRs showcased publicly + - **Bounty Programs** - Financial rewards for high-impact contributions + - **Fast-Track Hiring** - Priority consideration for core team positions + - **Community Spotlights** - Regular recognition and acknowledgments -```python -import os -from dotenv import load_dotenv -from swarms import Agent, ConcurrentWorkflow, OpenAIChat, Task +!!! info "Career Benefits" + - Multi-agent expertise highly valued by AI industry + - Portfolio demonstrates cutting-edge technical skills + - Direct networking with leading researchers and companies + - Thought leadership opportunities in emerging field -# Create a workflow -workflow = ConcurrentWorkflow(max_workers=5) -task_list = [] +### :material-brain: Technical Expertise Development -for node in bfs_order: - sub_query =nodes_info[node]['query'] - task = Task(worker_agent, sub_query) - print('-----------------') - print("Added task: ", sub_query) - print('-----------------') - task_list.append(task) +Master cutting-edge technologies: -workflow.add(tasks=task_list) +| Technology Area | Skills You'll Develop | +|----------------|----------------------| +| **Swarm Intelligence** | Design sophisticated agent coordination mechanisms | +| **Distributed Computing** | Build scalable architectures for thousands of agents | +| **Communication Protocols** | Create novel interaction patterns | +| **Production AI** | Deploy and orchestrate enterprise-scale systems | +| **Research Implementation** | Turn cutting-edge papers into working code | -# Run the workflow -workflow.run() -``` +### :material-account-group: Research Community Access -Below is part of the output this workflow produces. We clearly see the thought process of the agent and the plan it came up to solve a particular sub-query. In addition, we see the tool-calling schema it produces in `"command"`. +!!! note "Collaborative Environment" + - Work with experts from academic institutions and industry + - Regular technical seminars and research discussions + - Structured mentorship from experienced contributors + - Applied research opportunities with real-world impact -```python -... -... -content='\n{\n "thoughts": {\n "text": "To find out Nike\'s current revenue trend, I will use the financial data retriever tool to search for \'Nike revenue trend\'.",\n "reasoning": "The financial data retriever tool allows me to search for specific financial data, so I can look up the current revenue trend of Nike.", \n "plan": "Use the financial data retriever tool to search for \'Nike revenue trend\'. Parse the result to get the current revenue trend and format that into a readable report."\n },\n "command": {\n "name": "kay_retriever", \n "args": {\n "query": "Nike revenue trend"\n }\n }\n}\n```' response_metadata={'token_usage': {'completion_tokens': 152, 'prompt_tokens': 1527, 'total_tokens': 1679}, 'model_name': 'gpt-4', 'system_fingerprint': None, 'finish_reason': 'stop', 'logprobs': None} -Saved agent state to: Worker Agent_state.json +--- -{ - "thoughts": { - "text": "To find out Nike's current revenue trend, I will use the financial data retriever tool to search for 'Nike revenue trend'.", - "reasoning": "The financial data retriever tool allows me to search for specific financial data, so I can look up the current revenue trend of Nike.", - "plan": "Use the financial data retriever tool to search for 'Nike revenue trend'. Parse the result to get the current revenue trend and format that into a readable report." - }, - "command": { - "name": "kay_retriever", - "args": { - "query": "Nike revenue trend" - } - } -} +## Contribution Opportunities ------------------ -Document added successfully ------------------ -... -... -``` +=== "New Contributors" + ### :material-school: Perfect for Getting Started + + - **Documentation** - Improve guides, tutorials, and API references + - **Bug Reports** - Identify and document issues + - **Code Quality** - Participate in testing and review processes + - **Community Support** - Help users in forums and discussions + +=== "Experienced Developers" + ### :material-code-braces: Advanced Technical Work + + - **Core Architecture** - Design fundamental system components + - **Performance Optimization** - Enhance coordination and communication efficiency + - **Research Implementation** - Turn cutting-edge papers into working code + - **Integration Development** - Build connections with AI tools and platforms + +=== "Researchers" + ### :material-flask: Research and Innovation + + - **Algorithm Development** - Implement novel multi-agent algorithms + - **Experimental Frameworks** - Create evaluation and benchmarking tools + - **Theoretical Contributions** - Develop research documentation and frameworks + - **Academic Collaboration** - Partner on funded research projects -Here, `"name"` pertains to the name of the tool to be called and `"args"` is the arguments to be passed to the tool call. Like mentioned before, we modify `Agent`'s default behaviour in `WorkerAgent`. Hence, the tool call is executed here and its results (information from web pages and Kay Retriever API) are added to long-term memory. We get confirmation for this from the message `Document added successfully`. +--- +## How to Contribute -#### Step 7. Generating the report using Writer Agent +### Step 1: Get Started -At this point, our Worker Agents have gathered all the background information required to generate the report. We have also defined a coherent structure to write the report, which is following the BFT order to answering the sub-queries. Now it's time to define a Writer Agent and call it sequentially in the order of sub-queries. +!!! info "Essential Resources" + [:material-book-open-page-variant: **Documentation**](https://docs.swarms.world/en/latest/){ .md-button .md-button--primary } + [:material-github: **GitHub Repository**](https://github.com/kyegomez/swarms){ .md-button } + [:material-chat: **Community Channels**](#){ .md-button } -```python -from swarms import Agent, OpenAIChat, tool +### Step 2: Find Your Path -agent = Agent( - agent_name="Writer Agent", - agent_description=( - "This agent writes reports based on information in long-term memory" - ), - system_prompt=( - "You are a world-class financial report writer. " - "Write analytical and accurate responses using memory to answer the query. " - "Do not mention use of long-term memory in the report. " - "Do not mention Writer Agent in response." - "Return only response content in strict markdown format." - ), - llm=OpenAIChat(temperature=0.2, model='gpt-3.5-turbo'), - max_loops=1, - autosave=True, - verbose=True, - long_term_memory=memory, -) +```mermaid +graph TD + A[Choose Your Path] --> B[Browse Issues] + A --> C[Review Roadmap] + A --> D[Propose Ideas] + B --> E[good first issue] + B --> F[help wanted] + C --> G[Core Features] + C --> H[Research Areas] + D --> I[Discussion Forums] ``` -The report individual sections of the report will be collected in a list. +### Step 3: Make Impact -```python -report = [] -``` +1. **Fork & Setup** - Configure your development environment +2. **Develop** - Create your contribution +3. **Submit** - Open a pull request +4. **Collaborate** - Work with maintainers +5. **Celebrate** - See your work recognized -Let us now run the writer agent. +--- -```python -for node in bfs_order: - sub_query =nodes_info[node]['query'] - print("Running task: ", sub_query) - out = agent.run(f"Consider: {sub_query}. Write response in strict markdown format using long-term memory. Do not mention Writer Agent in response.") - print(out) - try: - report.append(out.content) - except: - pass -``` +## Recognition Framework -Now, we need to clean up the repoort a bit to make it render professionally. +### :material-flash: Immediate Benefits -```python -# Remove any content before the first "#" as that signals start of heading -# Anything before this usually contains filler content -stripped_report = [entry[entry.find('#'):] if '#' in entry else entry for entry in report] -report = stripped_report +!!! success "Instant Recognition" + | Benefit | Description | + |---------|-------------| + | **Social Media Features** | Every merged PR showcased publicly | + | **Community Recognition** | Contributor badges and documentation credits | + | **Professional References** | Formal acknowledgment for portfolios | + | **Direct Mentorship** | Access to core team guidance | -# At times the LLM outputs \\n instead of \n -cleaned_report = [entry.replace("\\n", "\n") for entry in report] -import re +### :material-trending-up: Long-term Opportunities -# Function to clean up unnecessary metadata from the report entries -def clean_report(report): - cleaned_report = [] - for entry in report: - # This pattern matches 'response_metadata={' followed by any characters that are not '}' (non-greedy), - # possibly nested inside other braces, until the closing '}'. - cleaned_entry = re.sub(r"response_metadata=\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}", "", entry, flags=re.DOTALL) - cleaned_report.append(cleaned_entry) - return cleaned_report +!!! tip "Career Growth" + - **Team Positions** - Fast-track consideration for core team roles + - **Conference Speaking** - Present work at AI conferences and events + - **Industry Connections** - Network with leading AI organizations + - **Research Collaboration** - Partner with academic institutions -# Apply the cleaning function to the markdown report -cleaned_report = clean_report(cleaned_report) -``` +--- -After cleaning, we append parts of the report together to get out final report. +## Societal Impact -```python -final_report = ' \n '.join(cleaned_report) -``` +!!! abstract "Building Solutions for Humanity" + Swarms enables technology that addresses critical challenges: -In Jupyter Notebook, we can use the below code to render it in Markdown. + === "Research" + **Scientific Research** + + Accelerate collaborative research and discovery across disciplines -```python -from IPython.display import display, Markdown + === "Healthcare" + **Healthcare Innovation** + + Support drug discovery and personalized medicine development -display(Markdown(final_report)) -``` + === "Environment" + **Environmental Solutions** + + Monitor climate and optimize sustainability initiatives + === "Education" + **Educational Technology** + + Create adaptive learning systems for personalized education -## Final Generated Report + === "Economy" + **Economic Innovation** + + Generate new opportunities and efficiency improvements +--- -### Nike's Current Revenue Trend +## Get Involved -Nike's current revenue trend has been steadily increasing over the past few years. In the most recent fiscal year, Nike reported a revenue of $37.4 billion, which was a 7% increase from the previous year. This growth can be attributed to strong sales in key markets, successful marketing campaigns, and a focus on innovation in product development. Overall, Nike continues to demonstrate strong financial performance and is well-positioned for future growth. - ### Potential Areas of Improvement in Nike's Business Model +### :material-link: Connect With Us -1. **Sustainability Practices**: Nike could further enhance its sustainability efforts by reducing its carbon footprint, using more eco-friendly materials, and ensuring ethical labor practices throughout its supply chain. +!!! info "Join the Community" + [:material-github: **GitHub Repository**](https://github.com/kyegomez/swarms){ .md-button .md-button--primary } + [:material-book: **Documentation**](https://docs.swarms.world/en/latest/){ .md-button } + [:material-forum: **Community Forums**](#){ .md-button } -2. **Diversification of Product Portfolio**: While Nike is known for its athletic footwear and apparel, diversifying into new product categories or expanding into untapped markets could help drive growth and mitigate risks associated with a single product line. +--- -3. **E-commerce Strategy**: Improving the online shopping experience, investing in digital marketing, and leveraging data analytics to personalize customer interactions could boost online sales and customer loyalty. +!!! warning "The Future is Now" + Multi-agent collaboration will define the next century of human progress. The autonomous economy depends on the infrastructure we build today. -4. **Innovation and R&D**: Continuously investing in research and development to stay ahead of competitors, introduce new technologies, and enhance product performance could help maintain Nike's competitive edge in the market. +!!! success "Your Mission" + Your contribution to Swarms helps create the foundation for billions of autonomous agents working together to solve humanity's greatest challenges. -5. **Brand Image and Reputation**: Strengthening brand image through effective marketing campaigns, community engagement, and transparent communication with stakeholders can help build trust and loyalty among consumers. - ### Potential Cost-Saving Strategies for Nike to Increase Net Revenue in Q3 2024 + **Join us in building the most important technology of our time.** -1. **Supply Chain Optimization**: Streamlining the supply chain, reducing transportation costs, and improving inventory management can lead to significant cost savings for Nike. +--- -2. **Operational Efficiency**: Implementing lean manufacturing practices, reducing waste, and optimizing production processes can help lower production costs and improve overall efficiency. +
+*Built with :material-heart: by the global Swarms community* +
-3. **Outsourcing Non-Core Functions**: Outsourcing non-core functions such as IT services, customer support, or logistics can help reduce overhead costs and focus resources on core business activities. +-------------------------------------------------- -4. **Energy Efficiency**: Investing in energy-efficient technologies, renewable energy sources, and sustainable practices can lower utility costs and demonstrate a commitment to environmental responsibility. +# File: contributors\tools.md -5. **Negotiating Supplier Contracts**: Negotiating better terms with suppliers, leveraging economies of scale, and exploring alternative sourcing options can help lower procurement costs and improve margins. +# Contributing Tools and Plugins to the Swarms Ecosystem -By implementing these cost-saving strategies, Nike can improve its bottom line and increase net revenue in Q3 2024. - ### Projected Market Trends for the Sports Apparel Industry in 2024 +## Introduction -1. **Sustainable Fashion**: Consumers are increasingly demanding eco-friendly and sustainable products, leading to a rise in sustainable sportswear options in the market. +The Swarms ecosystem is a modular, intelligent framework built to support the seamless integration, execution, and orchestration of dynamic tools that perform specific functions. These tools form the foundation for how autonomous agents operate, enabling them to retrieve data, communicate with APIs, conduct computational tasks, and respond intelligently to real-world requests. By contributing to Swarms Tools, developers can empower agents with capabilities that drive practical, enterprise-ready applications. -2. **Digital Transformation**: The sports apparel industry is expected to continue its shift towards digital platforms, with a focus on e-commerce, personalized shopping experiences, and digital marketing strategies. +This guide provides a comprehensive roadmap for contributing tools and plugins to the [Swarms Tools repository](https://github.com/The-Swarm-Corporation/swarms-tools). It is written for software engineers, data scientists, platform architects, and technologists who seek to develop modular, production-grade functionality within the Swarms agent framework. -3. **Athleisure Wear**: The trend of athleisure wear, which combines athletic and leisure clothing, is projected to remain popular in 2024 as consumers seek comfort and versatility in their apparel choices. +Whether your expertise lies in finance, security, machine learning, or developer tooling, this documentation outlines the essential standards, workflows, and integration patterns to make your contributions impactful and interoperable. -4. **Innovative Materials**: Advances in technology and material science are likely to drive the development of innovative fabrics and performance-enhancing materials in sports apparel, catering to the demand for high-quality and functional products. +## Repository Architecture -5. **Health and Wellness Focus**: With a growing emphasis on health and wellness, sports apparel brands are expected to incorporate features that promote comfort, performance, and overall well-being in their products. +The Swarms Tools GitHub repository is meticulously organized to maintain structure, scalability, and domain-specific clarity. Each folder within the repository represents a vertical where tools can be contributed and extended over time. These folders include: -Overall, the sports apparel industry in 2024 is anticipated to be characterized by sustainability, digitalization, innovation, and a focus on consumer health and lifestyle trends. - ### Current Successful Strategies Used by Nike's Competitors +- `finance/`: Market analytics, stock price retrievers, blockchain APIs, etc. -1. **Adidas**: Adidas has been successful in leveraging collaborations with celebrities and designers to create limited-edition collections that generate hype and drive sales. They have also focused on sustainability initiatives, such as using recycled materials in their products, to appeal to environmentally conscious consumers. +- `social/`: Sentiment analysis, engagement tracking, and media scraping utilities. -2. **Under Armour**: Under Armour has differentiated itself by targeting performance-driven athletes and emphasizing technological innovation in their products. They have also invested heavily in digital marketing and e-commerce to reach a wider audience and enhance the customer shopping experience. +- `health/`: Interfaces for EHR systems, wearable device APIs, or health informatics. -3. **Puma**: Puma has successfully capitalized on the athleisure trend by offering stylish and versatile sportswear that can be worn both in and out of the gym. They have also focused on building partnerships with influencers and sponsoring high-profile athletes to increase brand visibility and credibility. +- `ai/`: Model-serving utilities, embedding services, and prompt engineering functions. -4. **Lululemon**: Lululemon has excelled in creating a strong community around its brand, hosting events, classes, and collaborations to engage with customers beyond just selling products. They have also prioritized customer experience by offering personalized services and creating a seamless omnichannel shopping experience. +- `security/`: Encryption libraries, risk scoring tools, penetration test interfaces. -5. **New Balance**: New Balance has carved out a niche in the market by emphasizing quality craftsmanship, heritage, and authenticity in their products. They have also focused on customization and personalization options for customers, allowing them to create unique and tailored footwear and apparel. +- `devtools/`: Build tools, deployment utilities, code quality analyzers. -Overall, Nike's competitors have found success through a combination of innovative product offerings, strategic marketing initiatives, and a focus on customer engagement and experience. - ### Current and Projected Economic Conditions in Nike's Major Markets +- `misc/`: General-purpose helpers or utilities that serve multiple domains. -1. **United States**: The United States, being one of Nike's largest markets, is currently experiencing moderate economic growth driven by consumer spending, low unemployment rates, and a rebound in manufacturing. However, uncertainties surrounding trade policies, inflation, and interest rates could impact consumer confidence and spending in the near future. +Each tool inside these directories is implemented as a single, self-contained function. These functions are expected to adhere to Swarms-wide standards for clarity, typing, documentation, and API key handling. -2. **China**: China remains a key market for Nike, with a growing middle class and increasing demand for sportswear and athletic footwear. Despite recent trade tensions with the U.S., China's economy is projected to continue expanding, driven by domestic consumption, infrastructure investments, and technological advancements. +## Tool Development Specifications -3. **Europe**: Economic conditions in Europe vary across countries, with some experiencing sluggish growth due to Brexit uncertainties, political instability, and trade tensions. However, overall consumer confidence is improving, and the sports apparel market is expected to grow, driven by e-commerce and sustainability trends. +To ensure long-term maintainability and smooth agent-tool integration, each contribution must strictly follow the specifications below. -4. **Emerging Markets**: Nike's presence in emerging markets such as India, Brazil, and Southeast Asia provides opportunities for growth, given the rising disposable incomes, urbanization, and increasing focus on health and fitness. However, challenges such as currency fluctuations, regulatory changes, and competition from local brands could impact Nike's performance in these markets. +### 1. Function Structure and API Usage -Overall, Nike's major markets exhibit a mix of opportunities and challenges, with economic conditions influenced by global trends, geopolitical factors, and consumer preferences." - ### Current Consumer Preferences in the Sports Apparel Industry +```python +import requests +import os -1. **Sustainability**: Consumers are increasingly seeking eco-friendly and sustainable options in sports apparel, driving brands to focus on using recycled materials, reducing waste, and promoting ethical practices. +def fetch_data(symbol: str, date_range: str) -> str: + """ + Fetch financial data for a given symbol and date range. -2. **Athleisure**: The trend of athleisure wear continues to be popular, with consumers looking for versatile and comfortable clothing that can be worn both during workouts and in everyday life. + Args: + symbol (str): Ticker symbol of the asset. + date_range (str): Timeframe for the data (e.g., '1d', '1m', '1y'). -3. **Performance and Functionality**: Consumers prioritize performance-enhancing features in sports apparel, such as moisture-wicking fabrics, breathable materials, and ergonomic designs that enhance comfort and mobility. + Returns: + str: A string containing financial data or an error message. + """ + api_key = os.getenv("FINANCE_API_KEY") + url = f"https://api.financeprovider.com/data?symbol={symbol}&range={date_range}&apikey={api_key}" + response = requests.get(url) + if response.status_code == 200: + return response.text + return "Error fetching data." +``` -4. **Personalization**: Customization options, personalized fit, and unique design elements are appealing to consumers who seek individuality and exclusivity in their sports apparel choices. +All logic must be encapsulated inside a single callable function, written using pure Python. Where feasible, network requests should be stateless, side-effect-free, and gracefully handle errors or timeouts. -5. **Brand Transparency**: Consumers value transparency in brand practices, including supply chain transparency, ethical sourcing, and clear communication on product quality and manufacturing processes. +### 2. Type Hints and Input Validation -Overall, consumer preferences in the sports apparel industry are shifting towards sustainability, versatility, performance, personalization, and transparency, influencing brand strategies and product offerings. - ### Potential New Markets for Nike to Explore in 2024 +All function parameters must be typed using Python's type hinting system. Use built-in primitives where possible (e.g., `str`, `int`, `float`, `bool`) and make use of `Optional` or `Union` types when dealing with nullable parameters or multiple formats. This aids LLMs and type checkers in understanding expected input ranges. -1. **India**: With a growing population, increasing disposable incomes, and a rising interest in health and fitness, India presents a significant opportunity for Nike to expand its presence and tap into a large consumer base. +### 3. Standardized Output Format -2. **Africa**: The African market, particularly countries with emerging economies and a young population, offers potential for Nike to introduce its products and capitalize on the growing demand for sportswear and athletic footwear. +Regardless of internal logic or complexity, tools must return outputs in a consistent string format. This string can contain plain text or a serialized JSON object (as a string), but must not return raw objects, dictionaries, or binary blobs. This standardization ensures all downstream agents can interpret tool output predictably. -3. **Middle East**: Countries in the Middle East, known for their luxury shopping destinations and a growing interest in sports and fitness activities, could be strategic markets for Nike to target and establish a strong foothold. +### 4. API Key Management Best Practices -4. **Latin America**: Markets in Latin America, such as Brazil, Mexico, and Argentina, present opportunities for Nike to cater to a diverse consumer base and leverage the region's passion for sports and active lifestyles. +Security and environment isolation are paramount. Never hardcode API keys or sensitive credentials inside source code. Always retrieve them dynamically using the `os.getenv("ENV_VAR")` approach. If a tool requires credentials, clearly document the required environment variable names in the function docstring. -5. **Southeast Asia**: Rapid urbanization, increasing urban middle-class population, and a trend towards health and wellness in countries like Indonesia, Thailand, and Vietnam make Southeast Asia an attractive region for Nike to explore and expand its market reach. +### 5. Documentation Guidelines -By exploring these new markets in 2024, Nike can diversify its geographical presence, reach untapped consumer segments, and drive growth in emerging economies. - ### Potential New Products or Services Nike Could Introduce in 2024 +Every tool must include a detailed docstring that describes: -1. **Smart Apparel**: Nike could explore the integration of technology into its apparel, such as smart fabrics that monitor performance metrics, provide feedback, or enhance comfort during workouts. +- The function's purpose and operational scope -2. **Athletic Accessories**: Introducing a line of athletic accessories like gym bags, water bottles, or fitness trackers could complement Nike's existing product offerings and provide additional value to customers. +- All parameter types and formats -3. **Customization Platforms**: Offering personalized design options for footwear and apparel through online customization platforms could appeal to consumers seeking unique and tailored products. +- A clear return type -4. **Athletic Recovery Gear**: Developing recovery-focused products like compression wear, recovery sandals, or massage tools could cater to athletes and fitness enthusiasts looking to enhance post-workout recovery. +- Usage examples or sample inputs/outputs -5. **Sustainable Collections**: Launching sustainable collections made from eco-friendly materials, recycled fabrics, or biodegradable components could align with consumer preferences for environmentally conscious products. +Example usage: +```python +result = fetch_data("AAPL", "1m") +print(result) +``` -By introducing these new products or services in 2024, Nike can innovate its product portfolio, cater to evolving consumer needs, and differentiate itself in the competitive sports apparel market. - ### Potential Marketing Strategies for Nike to Increase Revenue in Q3 2024 +Well-documented code accelerates adoption and improves LLM interpretability. -1. **Influencer Partnerships**: Collaborating with popular athletes, celebrities, or social media influencers to promote Nike products can help reach a wider audience and drive sales. +## Contribution Workflow -2. **Interactive Campaigns**: Launching interactive marketing campaigns, contests, or events that engage customers and create buzz around new product releases can generate excitement and increase brand visibility. +To submit a tool, follow the workflow below. This ensures your code integrates cleanly and is easy for maintainers to review. -3. **Social Media Engagement**: Leveraging social media platforms to connect with consumers, share user-generated content, and respond to feedback can build brand loyalty and encourage repeat purchases. +### Step 1: Fork the Repository +Navigate to the [Swarms Tools repository](https://github.com/The-Swarm-Corporation/swarms-tools) and fork it to your personal or organization’s GitHub account. -4. **Localized Marketing**: Tailoring marketing messages, promotions, and product offerings to specific regions or target demographics can enhance relevance and appeal to diverse consumer groups. +### Step 2: Clone Your Fork +```bash +git clone https://github.com/YOUR_USERNAME/swarms-tools.git +cd swarms-tools +``` -5. **Customer Loyalty Programs**: Implementing loyalty programs, exclusive offers, or rewards for repeat customers can incentivize brand loyalty, increase retention rates, and drive higher lifetime customer value. +### Step 3: Create a Feature Branch -By employing these marketing strategies in Q3 2024, Nike can enhance its brand presence, attract new customers, and ultimately boost revenue growth. +```bash +git checkout -b feature/add-tool- +``` +Use descriptive branch names. This is especially helpful when collaborating in teams or maintaining audit trails. +### Step 4: Build Your Tool +Navigate into the appropriate category folder (e.g., `finance/`, `ai/`, etc.) and implement your tool according to the defined schema. +If your tool belongs in a new category, you may create a new folder with a clear, lowercase name. +### Step 5: Run Local Tests (if applicable) +Ensure the function executes correctly and does not throw runtime errors. If feasible, test edge cases and verify consistent behavior across platforms. +### Step 6: Commit Your Changes +```bash +git add . +git commit -m "Add under : API-based tool for X" +``` +### Step 7: Push to GitHub +```bash +git push origin feature/add-tool- +``` +### Step 8: Submit a Pull Request +On GitHub, open a pull request from your fork to the main Swarms Tools repository. Your PR description should: +- Summarize the tool’s functionality +- Reference any related issues or enhancements +- Include usage notes or setup instructions (e.g., required API keys) +--- +## Integration with Swarms Agents --------------------------------------------------- +Once your tool has been merged into the official repository, it can be utilized by Swarms agents as part of their available capabilities. -# File: applications/compliance_swarm.md +The example below illustrates how to embed a newly added tool into an autonomous agent: +```python +from swarms import Agent +from finance.stock_price import get_stock_price +agent = Agent( + agent_name="Devin", + system_prompt=( + "Autonomous agent that can interact with humans and other agents." + " Be helpful and kind. Use the tools provided to assist the user." + " Return all code in markdown format." + ), + llm=llm, + max_loops="auto", + autosave=True, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + interactive=True, + tools=[get_stock_price, terminal, browser, file_editor, create_file], + metadata_output_type="json", + function_calling_format_type="OpenAI", + function_calling_type="json", +) --------------------------------------------------- +agent.run("Create a new file for a plan to take over the world.") +``` -# File: applications/customer_support.md +By registering tools in the `tools` parameter during agent creation, you enable dynamic function calling. The agent interprets natural language input, selects the appropriate tool, and invokes it with valid arguments. -## **Applications of Swarms: Revolutionizing Customer Support** +This agent-tool paradigm enables highly flexible and responsive behavior across workflows involving research, automation, financial analysis, social listening, and more. --- -**Introduction**: -In today's fast-paced digital world, responsive and efficient customer support is a linchpin for business success. The introduction of AI-driven swarms in the customer support domain can transform the way businesses interact with and assist their customers. By leveraging the combined power of multiple AI agents working in concert, businesses can achieve unprecedented levels of efficiency, customer satisfaction, and operational cost savings. +## Tool Maintenance and Long-Term Ownership ---- +Contributors are expected to uphold the quality of their tools post-merge. This includes: -### **The Benefits of Using Swarms for Customer Support:** +- Monitoring for issues or bugs reported by the community -1. **24/7 Availability**: Swarms never sleep. Customers receive instantaneous support at any hour, ensuring constant satisfaction and loyalty. - -2. **Infinite Scalability**: Whether it's ten inquiries or ten thousand, swarms can handle fluctuating volumes with ease, eliminating the need for vast human teams and minimizing response times. - -3. **Adaptive Intelligence**: Swarms learn collectively, meaning that a solution found for one customer can be instantly applied to benefit all. This leads to constantly improving support experiences, evolving with every interaction. +- Updating tools when APIs deprecate or modify their behavior ---- +- Improving efficiency, error handling, or documentation over time -### **Features - Reinventing Customer Support**: +If a tool becomes outdated or unsupported, maintainers may archive or revise it to maintain ecosystem integrity. -- **AI Inbox Monitor**: Continuously scans email inboxes, identifying and categorizing support requests for swift responses. - -- **Intelligent Debugging**: Proactively helps customers by diagnosing and troubleshooting underlying issues. - -- **Automated Refunds & Coupons**: Seamless integration with payment systems like Stripe allows for instant issuance of refunds or coupons if a problem remains unresolved. - -- **Full System Integration**: Holistically connects with CRM, email systems, and payment portals, ensuring a cohesive and unified support experience. - -- **Conversational Excellence**: With advanced LLMs (Language Model Transformers), the swarm agents can engage in natural, human-like conversations, enhancing customer comfort and trust. - -- **Rule-based Operation**: By working with rule engines, swarms ensure that all actions adhere to company guidelines, ensuring consistent, error-free support. - -- **Turing Test Ready**: Crafted to meet and exceed the Turing Test standards, ensuring that every customer interaction feels genuine and personal. +Contributors whose tools receive wide usage or demonstrate excellence in design may be offered elevated privileges or invited to maintain broader tool categories. --- -**Conclusion**: -Swarms are not just another technological advancement; they represent the future of customer support. Their ability to provide round-the-clock, scalable, and continuously improving support can redefine customer experience standards. By adopting swarms, businesses can stay ahead of the curve, ensuring unparalleled customer loyalty and satisfaction. +## Best Practices for Enterprise-Grade Contributions -**Experience the future of customer support. Dive into the swarm revolution.** +To ensure your tool is production-ready and enterprise-compliant, observe the following practices: +- Run static type checking with `mypy` --------------------------------------------------- +- Use formatters like `black` and linters such as `flake8` -# File: applications/enterprise.md +- Avoid unnecessary external dependencies +- Keep functions modular and readable +- Prefer named parameters over positional arguments for clarity --------------------------------------------------- +- Handle API errors gracefully and return user-friendly messages + +- Document limitations or assumptions in the docstring -# File: applications/marketing_agencies.md +Optional but encouraged: +- Add unit tests to validate function output -## **Swarms in Marketing Agencies: A New Era of Automated Media Strategy** +- Benchmark performance if your tool operates on large datasets --- -### **Introduction**: -- Brief background on marketing agencies and their role in driving brand narratives and sales. -- Current challenges and pain points faced in media planning, placements, and budgeting. -- Introduction to the transformative potential of swarms in reshaping the marketing industry. +## Conclusion ---- +The Swarms ecosystem is built on the principle of extensibility through community-driven contributions. By submitting modular, typed, and well-documented tools to the Swarms Tools repository, you directly enhance the problem-solving power of intelligent agents. -### **1. Fundamental Problem: Media Plan Creation**: - - **Definition**: The challenge of creating an effective media plan that resonates with a target audience and aligns with brand objectives. - - - **Traditional Solutions and Their Shortcomings**: Manual brainstorming sessions, over-reliance on past strategies, and long turnaround times leading to inefficiency. - - - **How Swarms Address This Problem**: - - **Benefit 1**: Automated Media Plan Generation – Swarms ingest branding summaries, objectives, and marketing strategies to generate media plans, eliminating guesswork and human error. - - **Real-world Application of Swarms**: The automation of media plans based on client briefs, including platform selections, audience targeting, and creative versions. +This documentation serves as your blueprint for contributing high-quality, reusable functionality. From idea to implementation to integration, your efforts help shape the future of collaborative, agent-powered software. ---- +We encourage all developers, data scientists, and domain experts to contribute meaningfully. Review existing tools for inspiration, or create something entirely novel. -### **2. Fundamental Problem: Media Placements**: - - **Definition**: The tedious task of determining where ads will be placed, considering demographics, platform specifics, and more. - - - **Traditional Solutions and Their Shortcomings**: Manual placement leading to possible misalignment with target audiences and brand objectives. - - - **How Swarms Address This Problem**: - - **Benefit 2**: Precision Media Placements – Swarms analyze audience data and demographics to suggest the best placements, optimizing for conversions and brand reach. - - **Real-world Application of Swarms**: Automated selection of ad placements across platforms like Facebook, Google, and DSPs based on media plans. +To begin, fork the [Swarms Tools repository](https://github.com/The-Swarm-Corporation/swarms-tools) and start building impactful, reusable tools that can scale across agents and use cases. ---- -### **3. Fundamental Problem: Budgeting**: - - **Definition**: Efficiently allocating and managing advertising budgets across multiple campaigns, platforms, and timeframes. - - - **Traditional Solutions and Their Shortcomings**: Manual budgeting using tools like Excel, prone to errors, and inefficient shifts in allocations. - - - **How Swarms Address This Problem**: - - **Benefit 3**: Intelligent Media Budgeting – Swarms enable dynamic budget allocation based on performance analytics, maximizing ROI. - - **Real-world Application of Swarms**: Real-time adjustments in budget allocations based on campaign performance, eliminating long waiting periods and manual recalculations. ---- +-------------------------------------------------- -### **Features**: -1. Automated Media Plan Generator: Input your objectives and receive a comprehensive media plan. -2. Precision Media Placement Tool: Ensure your ads appear in the right places to the right people. -3. Dynamic Budget Allocation: Maximize ROI with real-time budget adjustments. -4. Integration with Common Tools: Seamless integration with tools like Excel and APIs for exporting placements. -5. Conversational Platform: A suite of tools built for modern marketing agencies, bringing all tasks under one umbrella. +# File: docs_structure.md ---- +# Class/function -### **Testimonials**: -- "Swarms have completely revolutionized our media planning process. What used to take weeks now takes mere hours." - *Senior Media Strategist, Top-tier Marketing Agency* -- "The precision with which we can place ads now is unprecedented. It's like having a crystal ball for marketing!" - *Campaign Manager, Global Advertising Firm* +Brief description +↓ ---- +↓ +## Overview +↓ +## Architecture (Mermaid diagram) +↓ +## Class Reference (Constructor + Methods) + +table of parameters for every method and example + +↓ +## Examples + +↓ + +## Conclusion +Benefits of class/structure, and more -### **Conclusion**: -- Reiterate the immense potential of swarms in revolutionizing media planning, placements, and budgeting for marketing agencies. -- Call to action: For marketing agencies looking to step into the future and leave manual inefficiencies behind, swarms are the answer. ---- -------------------------------------------------- -# File: blogs/blog.md +# File: examples\agent_stream.md -# Swarms API: Orchestrating the Future of AI Agent Collaboration +# Agent with Streaming -In today's rapidly evolving AI landscape, we're witnessing a fundamental shift from single-agent AI systems to complex, collaborative multi-agent architectures. While individual AI models like GPT-4 and Claude have demonstrated remarkable capabilities, they often struggle with complex tasks requiring diverse expertise, nuanced decision-making, and specialized domain knowledge. Enter the Swarms API, an enterprise-grade solution designed to orchestrate collaborative intelligence through coordinated AI agent swarms. +The Swarms framework provides powerful real-time streaming capabilities for agents, allowing you to see responses being generated token by token as they're produced by the language model. This creates a more engaging and interactive experience, especially useful for long-form content generation, debugging, or when you want to provide immediate feedback to users. -## The Problem: The Limitations of Single-Agent AI +## Installation -Despite significant advances in large language models and AI systems, single-agent architectures face inherent limitations when tackling complex real-world problems: +Install the swarms package using pip: -### Expertise Boundaries -Even the most advanced AI models have knowledge boundaries. No single model can possess expert-level knowledge across all domains simultaneously. When a task requires deep expertise in multiple areas (finance, law, medicine, and technical analysis, for example), a single agent quickly reaches its limits. +```bash +pip install -U swarms +``` -### Complex Reasoning Chains -Many real-world problems demand multistep reasoning with multiple feedback loops and verification processes. Single agents often struggle to maintain reasoning coherence through extended problem-solving journeys, leading to errors that compound over time. +## Basic Setup -### Workflow Orchestration -Enterprise applications frequently require sophisticated workflows with multiple handoffs, approvals, and specialized processing steps. Managing this orchestration with individual AI instances is inefficient and error-prone. +1. First, set up your environment variables: -### Resource Optimization -Deploying high-powered AI models for every task is expensive and inefficient. Organizations need right-sized solutions that match computing resources to task requirements. +```python +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" +``` -### Collaboration Mechanisms -The most sophisticated human problem-solving happens in teams, where specialists collaborate, debate, and refine solutions together. This collaborative intelligence is difficult to replicate with isolated AI agents. +## Step by Step -## The Solution: Swarms API +- Install and put your keys in `.env` -The Swarms API addresses these challenges through a revolutionary approach to AI orchestration. By enabling multiple specialized agents to collaborate in coordinated swarms, it unlocks new capabilities previously unattainable with single-agent architectures. +- Turn on streaming in `Agent()` with `streaming_on=True` -### What is the Swarms API? +- Optional: If you want to pretty print it, you can do `print_on=True`; if not, it will print normally -The Swarms API is an enterprise-grade platform that enables organizations to deploy and manage intelligent agent swarms in the cloud. Rather than relying on a single AI agent to handle complex tasks, the Swarms API orchestrates teams of specialized AI agents that work together, each handling specific aspects of a larger problem. +## Code -The platform provides a robust infrastructure for creating, executing, and managing sophisticated AI agent workflows without the burden of maintaining the underlying infrastructure. With its cloud-native architecture, the Swarms API offers scalability, reliability, and security essential for enterprise deployments. +```python +from swarms import Agent -## Core Capabilities +# Enable real-time streaming +agent = Agent( + agent_name="StoryAgent", + model_name="gpt-4o-mini", + streaming_on=True, # 🔥 This enables real streaming! + max_loops=1, + print_on=True, # By default, it's False for raw streaming! +) -The Swarms API delivers a comprehensive suite of capabilities designed for production-grade AI orchestration: +# This will now stream in real-time with a beautiful UI! +response = agent.run("Tell me a detailed story about humanity colonizing the stars") +print(response) +``` -### Intelligent Swarm Management +## Connect With Us -At its core, the Swarms API enables the creation and execution of collaborative agent swarms. These swarms consist of specialized AI agents designed to work together on complex tasks. Unlike traditional AI approaches where a single model handles the entire workload, swarms distribute tasks among specialized agents, each contributing its expertise to the collective solution. +If you'd like technical support, join our Discord below and stay updated on our Twitter for new updates! -For example, a financial analysis swarm might include: -- A data preprocessing agent that cleans and normalizes financial data -- A market analyst agent that identifies trends and patterns -- An economic forecasting agent that predicts future market conditions -- A report generation agent that compiles insights into a comprehensive analysis +| Platform | Link | Description | +|----------|------|-------------| +| 📚 Documentation | [docs.swarms.world](https://docs.swarms.world) | Official documentation and guides | +| 📝 Blog | [Medium](https://medium.com/@kyeg) | Latest updates and technical articles | +| 💬 Discord | [Join Discord](https://discord.gg/jM3Z6M9uMq) | Live chat and community support | +| 🐦 Twitter | [@kyegomez](https://twitter.com/kyegomez) | Latest news and announcements | +| 👥 LinkedIn | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | Professional network and updates | +| 📺 YouTube | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | Tutorials and demos | +| 🎫 Events | [Sign up here](https://lu.ma/5p2jnc2v) | Join our community events | -By coordinating these specialized agents, the swarm can deliver more accurate, nuanced, and valuable results than any single agent could produce alone. -### Automatic Agent Generation -One of the most powerful features of the Swarms API is its ability to dynamically create optimized agents based on task requirements. Rather than manually configuring each agent in a swarm, users can specify the overall task and let the platform automatically generate appropriate agents with optimized prompts and configurations. +-------------------------------------------------- -This automatic agent generation significantly reduces the expertise and effort required to deploy effective AI solutions. The system analyzes the task requirements and creates a set of agents specifically designed to address different aspects of the problem. This approach not only saves time but also improves the quality of results by ensuring each agent is properly configured for its specific role. +# File: examples\cookbook_index.md -### Multiple Swarm Architectures +# Swarms Cookbook Examples Index -Different problems require different collaboration patterns. The Swarms API supports various swarm architectures to match specific workflow needs: +This index provides a categorized list of examples and tutorials for using the Swarms Framework across different industries. Each example demonstrates practical applications and implementations using the framework. -- **SequentialWorkflow**: Agents work in a predefined sequence, with each agent handling specific subtasks in order -- **ConcurrentWorkflow**: Multiple agents work simultaneously on different aspects of a task -- **GroupChat**: Agents collaborate in a discussion format to solve problems collectively -- **HierarchicalSwarm**: Organizes agents in a structured hierarchy with managers and workers -- **MajorityVoting**: Uses a consensus mechanism where multiple agents vote on the best solution -- **AutoSwarmBuilder**: Automatically designs and builds an optimal swarm architecture based on the task -- **MixtureOfAgents**: Combines multiple agent types to tackle diverse aspects of a problem -- **MultiAgentRouter**: Routes subtasks to specialized agents based on their capabilities -- **AgentRearrange**: Dynamically reorganizes the workflow between agents based on evolving task requirements +## Finance & Trading -This flexibility allows organizations to select the most appropriate collaboration pattern for each specific use case, optimizing the balance between efficiency, thoroughness, and creativity. +| Name | Description | Link | +|------|-------------|------| +| Tickr-Agent | Financial analysis agent for stock market data using multithreaded processing and AI integration | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/finance/multi_agent/Swarms_Cookbook_Tickr_Agent.ipynb) | +| CryptoAgent | Real-time cryptocurrency data analysis and insights using CoinGecko integration | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/finance/multi_agent/Swarms_Cookbook_CryptoAgent.ipynb) | +| 10-K Analysis (Custom) | Detailed analysis of SEC 10-K reports using specialized agents | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/finance/multi_agent/swarms_finance_10k_analysis_custom.ipynb) | +| 10-K Analysis (AgentRearrange) | Mixed sequential and parallel analysis of 10-K reports | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/finance/multi_agent/swarms_finance_10k_analysis_agentrearrange.ipynb) | -### Scheduled Execution +## Healthcare & Medical -The Swarms API enables automated, scheduled swarm executions, allowing organizations to set up recurring tasks that run automatically at specified times. This feature is particularly valuable for regular reporting, monitoring, and analysis tasks that need to be performed on a consistent schedule. +| Name | Description | Link | +|------|-------------|------| +| MedInsight Pro | Medical research summarization and analysis using AI-driven agents | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/medical/physical_therapy/Swarms_Cookbook_MedInsight_Pro.ipynb) | +| Athletics Diagnosis | Diagnosis and treatment system for extreme athletics using AgentRearrange | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/medical/physical_therapy/swarms_diagnosis_treatment_extreme_athletics.ipynb) | -For example, a financial services company could schedule a daily market analysis swarm to run before trading hours, providing updated insights based on overnight market movements. Similarly, a cybersecurity team might schedule hourly security assessment swarms to continuously monitor potential threats. +## Marketing & Content -### Comprehensive Logging +| Name | Description | Link | +|------|-------------|------| +| NewsAgent | Real-time news aggregation and summarization for business intelligence | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/marketing/news/Swarms_Cookbook_NewsAgent.ipynb) | +| Social Media Marketing | Spreadsheet-based content generation for multi-platform marketing | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/marketing/content_generation/swarms_spreadsheet_analysis_walkthrough.ipynb) | -Transparency and auditability are essential for enterprise AI applications. The Swarms API provides comprehensive logging capabilities that track all API interactions, agent communications, and decision processes. This detailed logging enables: +## Accounting & Finance Operations -- Debugging and troubleshooting swarm behaviors -- Auditing decision trails for compliance and quality assurance -- Analyzing performance patterns to identify optimization opportunities -- Documenting the rationale behind AI-generated recommendations +| Name | Description | Link | +|------|-------------|------| +| Accounting Agents | Multi-agent system for financial projections and risk assessment | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/accounting/multi_agent/accounting_agents_for_moa.ipynb) | -These logs provide valuable insights into how swarms operate and make decisions, increasing trust and enabling continuous improvement of AI workflows. +## Workshops & Tutorials -### Cost Management +| Name | Description | Link | +|------|-------------|------| +| GPTuesday Event | Example of creating promotional content for tech events | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/workshops/sep_6_workshop/gptuesday_swarm.py) | -AI deployment costs can quickly escalate without proper oversight. The Swarms API addresses this challenge through: +## Additional Resources -- **Predictable, transparent pricing**: Clear cost structures that make budgeting straightforward -- **Optimized resource utilization**: Intelligent allocation of computing resources based on task requirements -- **Detailed cost breakdowns**: Comprehensive reporting on token usage, agent costs, and total expenditures -- **Model flexibility**: Freedom to choose the most cost-effective models for each agent based on task complexity +| Platform | Link | Description | +|----------|------|-------------| +| 📚 Documentation | [docs.swarms.world](https://docs.swarms.world) | Official documentation and guides | +| 📝 Blog | [Medium](https://medium.com/@kyeg) | Latest updates and technical articles | +| 💬 Discord | [Join Discord](https://discord.gg/jM3Z6M9uMq) | Live chat and community support | +| 🐦 Twitter | [@kyegomez](https://twitter.com/kyegomez) | Latest news and announcements | +| 👥 LinkedIn | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | Professional network and updates | +| 📺 YouTube | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | Tutorials and demos | +| 🎫 Events | [Sign up here](https://lu.ma/5p2jnc2v) | Join our community events | -This approach ensures organizations get maximum value from their AI investments without unexpected cost overruns. +## Contributing -### Enterprise Security +We welcome contributions! If you have an example or tutorial you'd like to add, please check our [contribution guidelines](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/CONTRIBUTING.md). -Security is paramount for enterprise AI deployments. The Swarms API implements robust security measures including: +## License -- **Full API key authentication**: Secure access control for all API interactions -- **Comprehensive key management**: Tools for creating, rotating, and revoking API keys -- **Usage monitoring**: Tracking and alerting for suspicious activity patterns -- **Secure data handling**: Appropriate data protection throughout the swarm execution lifecycle +This project is licensed under the MIT License - see the [LICENSE](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/LICENSE) file for details. -These security features ensure that sensitive data and AI workflows remain protected in accordance with enterprise security requirements. +-------------------------------------------------- -## How It Works: Behind the Scenes +# File: examples\index.md -The Swarms API operates on a sophisticated architecture designed for reliability, scalability, and performance. Here's a look at what happens when you submit a task to the Swarms API: +# Swarms Examples Index -1. **Task Submission**: You send a request to the API with your task description and desired swarm configuration. +Welcome to the comprehensive Swarms Examples Index! This curated collection showcases the power and versatility of the Swarms framework for building intelligent multi-agent systems. Whether you're a beginner looking to get started or an advanced developer seeking complex implementations, you'll find practical examples to accelerate your AI development journey. -2. **Swarm Configuration**: The system either uses your specified agent configuration or automatically generates an optimal swarm structure based on the task requirements. +## What is Swarms? -3. **Agent Initialization**: Each agent in the swarm is initialized with its specific instructions, model parameters, and role definitions. +Swarms is a cutting-edge framework for creating sophisticated multi-agent AI systems that can collaborate, reason, and solve complex problems together. From single intelligent agents to coordinated swarms of specialized AI workers, Swarms provides the tools and patterns you need to build the next generation of AI applications. -4. **Orchestration Setup**: The system establishes the communication and workflow patterns between agents based on the selected swarm architecture. +## What You'll Find Here -5. **Execution**: The swarm begins working on the task, with agents collaborating according to their defined roles and relationships. +This index organizes **100+ production-ready examples** from our [Swarms Examples Repository](https://github.com/The-Swarm-Corporation/swarms-examples) and the main Swarms repository, covering: -6. **Monitoring and Adjustment**: Throughout execution, the system monitors agent performance and makes adjustments as needed. -7. **Result Compilation**: Once the task is complete, the system compiles the results into the requested format. +- **Single Agent Systems**: From basic implementations to advanced reasoning agents -8. **Response Delivery**: The final output is returned to you, along with metadata about the execution process. +- **Multi-Agent Architectures**: Collaborative swarms, hierarchical systems, and experimental topologies -This entire process happens seamlessly in the cloud, with the Swarms API handling all the complexities of agent coordination, resource allocation, and workflow management. +- **Industry Applications**: Real-world use cases across finance, healthcare, security, and more -## Real-World Applications +- **Integration Examples**: Connect with popular AI models, tools, and frameworks -The Swarms API enables a wide range of applications across industries. Here are some compelling use cases that demonstrate its versatility: +- **Advanced Patterns**: RAG systems, function calling, MCP integration, and more -### Financial Services +## Getting Started -#### Investment Research -Financial institutions can deploy research swarms that combine market analysis, economic forecasting, company evaluation, and risk assessment. These swarms can evaluate investment opportunities much more comprehensively than single-agent systems, considering multiple factors simultaneously: +**New to Swarms?** Start with the [Easy Example](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/easy_example.py) under Single Agent Examples → Core Agents. + +**Looking for comprehensive tutorials?** Check out [The Swarms Cookbook](https://github.com/The-Swarm-Corporation/Cookbook) for detailed walkthroughs and advanced patterns. + +**Want to see real-world applications?** Explore the Industry Applications section to see how Swarms solves practical problems. + +## Quick Navigation + + +- [Single Agent Examples](#single-agent-examples) - Individual AI agents with various capabilities + +- [Multi-Agent Examples](#multi-agent-examples) - Collaborative systems and swarm architectures + +- [Additional Resources](#additional-resources) - Community links and support channels + +## Single Agent Examples + +### Core Agents +| Category | Example | Description | +|----------|---------|-------------| +| Basic | [Easy Example](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/easy_example.py) | Basic agent implementation demonstrating core functionality and setup | +| Settings | [Agent Settings](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/agent_settings.py) | Comprehensive configuration options for customizing agent behavior and capabilities | +| YAML | [Agents from YAML](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/agents_from_yaml_example.py) | Creating and configuring agents using YAML configuration files for easy deployment | +| Memory | [Agent with Long-term Memory](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/memory/agents_and_memory/agent_with_longterm_memory.py) | Implementation of persistent memory capabilities for maintaining context across sessions | + +### Model Integrations +| Category | Example | Description | +|----------|---------|-------------| +| Azure | [Azure OpenAI Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/settings/various_models/basic_agent_with_azure_openai.py) | Integration with Azure OpenAI services for enterprise-grade AI capabilities | +| Groq | [Groq Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/settings/various_models/groq_agent.py) | High-performance inference using Groq's accelerated computing platform | +| Custom | [Custom Model Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/settings/various_models/custom_model_with_agent.py) | Framework for integrating custom ML models into the agent architecture | +| Cerebras | [Cerebras Example](https://github.com/kyegomez/swarms/blob/master/examples/models/cerebas_example.py) | Integration with Cerebras AI platform for high-performance model inference | +| Claude | [Claude 4 Example](https://github.com/kyegomez/swarms/blob/master/examples/models/claude_4_example.py) | Anthropic Claude 4 model integration for advanced reasoning capabilities | +| Swarms Claude | [Swarms Claude Example](https://github.com/kyegomez/swarms/blob/master/examples/models/swarms_claude_example.py) | Optimized Claude integration within the Swarms framework | +| Lumo | [Lumo Example](https://github.com/kyegomez/swarms/blob/master/examples/models/lumo_example.py) | Lumo AI model integration for specialized tasks | +| VLLM | [VLLM Example](https://github.com/kyegomez/swarms/blob/master/examples/models/vllm_example.py) | High-performance inference using VLLM for large language models | +| Llama4 | [LiteLLM Example](https://github.com/kyegomez/swarms/blob/master/examples/models/llama4_examples/litellm_example.py) | Llama4 model integration using LiteLLM for efficient inference | + +### Tools and Function Calling +| Category | Example | Description | +|----------|---------|-------------| +| Basic Tools | [Tool Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/tools/tool_agent.py) | Basic tool-using agent demonstrating external tool integration capabilities | +| Advanced Tools | [Agent with Many Tools](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/tools/agent_with_many_tools.py) | Advanced agent utilizing multiple tools for complex task execution | +| OpenAI Functions | [OpenAI Function Caller](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/tools/function_calling/openai_function_caller_example.py) | Integration with OpenAI's function calling API for structured outputs | +| Command Line | [Command Tool Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/tools/tool_agent/command_r_tool_agent.py) | Command-line interface tool integration | +| Jamba | [Jamba Tool Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/tools/tool_agent/jamba_tool_agent.py) | Integration with Jamba framework for enhanced tool capabilities | +| Pydantic | [Pydantic Tool Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/tools/tool_agent/tool_agent_pydantic.py) | Tool validation and schema enforcement using Pydantic | +| Function Caller | [Function Caller Example](https://github.com/kyegomez/swarms/blob/master/examples/demos/spike/function_caller_example.py) | Advanced function calling capabilities with dynamic tool execution | +| LiteLLM Tools | [LiteLLM Tool Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/tools/litellm_tool_example.py) | Tool integration using LiteLLM for model-agnostic function calling | +| Swarms Tools | [Swarms Tools Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/tools/swarms_tools_example.py) | Native Swarms tool ecosystem integration | +| Structured Outputs | [Structured Outputs Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/tools/structured_outputs/structured_outputs_example.py) | Structured data output capabilities for consistent responses | +| Schema Validation | [Schema Validation Example](https://github.com/kyegomez/swarms/blob/master/examples/tools/base_tool_examples/schema_validation_example.py) | Tool schema validation and error handling | + +### MCP (Model Context Protocol) Integration +| Category | Example | Description | +|----------|---------|-------------| +| Agent Tools | [Agent Tools Dict Example](https://github.com/kyegomez/swarms/blob/master/examples/mcp/mcp_examples/agent_use/agent_tools_dict_example.py) | MCP integration for dynamic tool management | +| MCP Execute | [MCP Execute Example](https://github.com/kyegomez/swarms/blob/master/examples/mcp/mcp_examples/utils/mcp_execute_example.py) | MCP command execution and response handling | +| MCP Load Tools | [MCP Load Tools Example](https://github.com/kyegomez/swarms/blob/master/examples/mcp/mcp_examples/utils/mcp_load_tools_example.py) | Dynamic tool loading through MCP protocol | +| Multiple Servers | [MCP Multiple Servers Example](https://github.com/kyegomez/swarms/blob/master/examples/mcp/mcp_utils/mcp_multiple_servers_example.py) | Multi-server MCP configuration and management | + +### RAG and Memory +| Category | Example | Description | +|----------|---------|-------------| +| Full RAG | [Full Agent RAG Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/rag/full_agent_rag_example.py) | Complete RAG implementation with retrieval and generation | +| Pinecone | [Pinecone Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/rag/pinecone_example.py) | Vector database integration using Pinecone for semantic search | + +### Reasoning and Decision Making +| Category | Example | Description | +|----------|---------|-------------| +| Agent Judge | [Agent Judge Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/reasoning_agent_examples/agent_judge_example.py) | Agent-based decision making and evaluation system | +| MALT | [MALT Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/reasoning_agent_examples/malt_example.py) | Multi-agent logical reasoning framework | +| Reasoning Duo | [Reasoning Duo Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/reasoning_agent_examples/reasoning_duo_example.py) | Collaborative reasoning between two specialized agents | + +### Vision and Multimodal +| Category | Example | Description | +|----------|---------|-------------| +| Image Batch | [Image Batch Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/vision/image_batch_example.py) | Batch processing of multiple images with vision capabilities | +| Multimodal | [Multimodal Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/vision/multimodal_example.py) | Multi-modal agent supporting text, image, and audio inputs | + +### Utilities and Output Formats +| Category | Example | Description | +|----------|---------|-------------| +| XML Output | [XML Output Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/utils/xml_output_example.py) | Structured XML output formatting for agent responses | +| CSV Agent | [CSV Agent Example](https://github.com/kyegomez/swarms/blob/master/examples/misc/csvagent_example.py) | CSV data processing and manipulation agent | +| Swarm Matcher | [Swarm Matcher Example](https://github.com/kyegomez/swarms/blob/master/examples/misc/swarm_matcher_example.py) | Agent matching and selection system | + +### Third-Party Integrations +| Category | Example | Description | +|----------|---------|-------------| +| Microsoft | [AutoGen Integration](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/3rd_party_agents/auto_gen.py) | Integration with Microsoft's AutoGen framework for autonomous agents | +| LangChain | [LangChain Integration](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/3rd_party_agents/langchain.py) | Combining LangChain's capabilities with Swarms for enhanced functionality | +| Browser | [Multion Integration](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/3rd_party_agents/multion_agent.py) | Web automation and browsing capabilities using Multion | +| Team AI | [Crew AI](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/3rd_party_agents/crew_ai.py) | Team-based AI collaboration using Crew AI framework | +| Development | [Griptape](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/3rd_party_agents/griptape.py) | Integration with Griptape for structured AI application development | + +### Industry-Specific Agents +| Category | Example | Description | +|----------|---------|-------------| +| Finance | [401k Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/use_cases/finance/401k_agent.py) | Retirement planning assistant with investment strategy recommendations | +| Finance | [Estate Planning](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/use_cases/finance/estate_planning_agent.py) | Comprehensive estate planning and wealth management assistant | +| Security | [Perimeter Defense](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/use_cases/security/perimeter_defense_agent.py) | Security monitoring and threat detection system | +| Research | [Perplexity Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/use_cases/research/perplexity_agent.py) | Advanced research automation using Perplexity AI integration | +| Legal | [Alberto Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/use_cases/law/alberto_agent.py) | Legal research and document analysis assistant | +| Healthcare | [Pharma Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/use_cases/pharma/pharma_agent_two.py) | Pharmaceutical research and drug interaction analysis | + +## Multi-Agent Examples + +### Core Architectures +| Category | Example | Description | +|----------|---------|-------------| +| Basic | [Build a Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/base_swarm/build_a_swarm.py) | Foundation for creating custom swarm architectures with multiple agents | +| Auto Swarm | [Auto Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/auto_swarm/auto_swarm_example.py) | Self-organizing swarm with automatic task distribution and management | +| Concurrent | [Concurrent Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/concurrent_swarm/concurrent_swarm_example.py) | Parallel execution of tasks across multiple agents for improved performance | +| Star | [Star Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/different_architectures/star_swarm.py) | Centralized architecture with a hub agent coordinating peripheral agents | +| Circular | [Circular Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/different_architectures/circular_swarm.py) | Ring topology for cyclic information flow between agents | +| Graph Workflow | [Graph Workflow Basic](https://github.com/kyegomez/swarms/blob/main/examples/structs/graph_workflow_basic.py) | Minimal graph workflow with two agents and one task | + +### Concurrent and Parallel Processing +| Category | Example | Description | +|----------|---------|-------------| +| Concurrent | [Concurrent Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/concurrent_examples/concurrent_example.py) | Basic concurrent execution of multiple agents | +| Concurrent Swarm | [Concurrent Swarm Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/concurrent_examples/concurrent_swarm_example.py) | Advanced concurrent swarm with parallel task processing | + +### Hierarchical and Sequential Workflows +| Category | Example | Description | +|----------|---------|-------------| +| Hierarchical | [Hierarchical Swarm Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/hiearchical_swarm/hiearchical_examples/hierarchical_swarm_example.py) | Multi-level hierarchical agent organization | +| Hierarchical Basic | [Hierarchical Swarm Basic](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/hiearchical_swarm/hiearchical_swarm-example.py) | Simplified hierarchical swarm implementation | +| Hierarchical Advanced | [Hierarchical Advanced](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/hiearchical_swarm/hierarchical_swarm_example.py) | Advanced hierarchical swarm with complex agent relationships | +| Sequential Workflow | [Sequential Workflow Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/sequential_workflow/sequential_workflow_example.py) | Linear workflow with agents processing tasks in sequence | +| Sequential Swarm | [Sequential Swarm Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/sequential_workflow/sequential_swarm_example.py) | Sequential swarm with coordinated task execution | + +### Group Chat and Interactive Systems +| Category | Example | Description | +|----------|---------|-------------| +| Group Chat | [Group Chat Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/groupchat/groupchat_examples/group_chat_example.py) | Multi-agent group chat system with turn-based communication | +| Group Chat Advanced | [Group Chat Advanced](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/groupchat/groupchat_examples/groupchat_example.py) | Advanced group chat with enhanced interaction capabilities | +| Mortgage Panel | [Mortgage Tax Panel](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/groupchat/groupchat_examples/mortgage_tax_panel_example.py) | Specialized panel for mortgage and tax discussions | +| Interactive Group Chat | [Interactive Group Chat](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/groupchat/interactive_groupchat_example.py) | Interactive group chat with real-time user participation | +| Dynamic Speaker | [Random Dynamic Speaker](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/groupchat/random_dynamic_speaker_example.py) | Dynamic speaker selection in group conversations | +| Interactive Speaker | [Interactive Speaker Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/interactive_groupchat_examples/interactive_groupchat_speaker_example.py) | Interactive speaker management in group chats | +| Medical Panel | [Medical Panel Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/interactive_groupchat_examples/medical_panel_example.py) | Medical expert panel for healthcare discussions | +| Stream Example | [Stream Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/interactive_groupchat_examples/stream_example.py) | Streaming capabilities in interactive group chats | + +### Research and Deep Analysis +| Category | Example | Description | +|----------|---------|-------------| +| Deep Research | [Deep Research Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/deep_research_examples/deep_research_example.py) | Comprehensive research system with multiple specialized agents | +| Deep Research Swarm | [Deep Research Swarm](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/deep_research_examples/deep_research_swarm_example.py) | Swarm-based deep research with collaborative analysis | +| Scientific Agents | [Deep Research Swarm Example](https://github.com/kyegomez/swarms/blob/master/examples/demos/scient_agents/deep_research_swarm_example.py) | Scientific research swarm for academic and research applications | + +### Routing and Decision Making +| Category | Example | Description | +|----------|---------|-------------| +| Model Router | [Model Router Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/mar/model_router_example.py) | Intelligent routing of tasks to appropriate model agents | +| Multi-Agent Router | [Multi-Agent Router Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/mar/multi_agent_router_example.py) | Advanced routing system for multi-agent task distribution | +| Swarm Router | [Swarm Router Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/swarm_router/swarm_router_example.py) | Swarm-specific routing and load balancing | +| Majority Voting | [Majority Voting Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/majority_voting/majority_voting_example.py) | Consensus-based decision making using majority voting | + +### Council and Collaborative Systems +| Category | Example | Description | +|----------|---------|-------------| +| Council Judge | [Council Judge Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/council/council_judge_example.py) | Council-based decision making with expert judgment | + +### Advanced Collaboration +| Category | Example | Description | +|----------|---------|-------------| +| Enhanced Collaboration | [Enhanced Collaboration Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/enhanced_collaboration_example.py) | Advanced collaboration patterns between multiple agents | +| Mixture of Agents | [Mixture of Agents Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/mixture_of_agents_example.py) | Heterogeneous agent mixture for diverse task handling | +| Aggregate | [Aggregate Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/aggregate_example.py) | Aggregation of results from multiple agents | + +### API and Integration +| Category | Example | Description | +|----------|---------|-------------| +| Swarms API | [Swarms API Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/swarms_api_examples/swarms_api_example.py) | API integration for Swarms multi-agent systems | + +### Utilities and Batch Processing +| Category | Example | Description | +|----------|---------|-------------| +| Batch Agent | [Batch Agent Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/utils/batch_agent_example.py) | Batch processing capabilities for multiple agents | + +### Experimental Architectures +| Category | Example | Description | +|----------|---------|-------------| +| Monte Carlo | [Monte Carlo Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/experimental/monte_carlo_swarm.py) | Probabilistic decision-making using Monte Carlo simulation across agents | +| Federated | [Federated Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/experimental/federated_swarm.py) | Distributed learning system with privacy-preserving agent collaboration | +| Ant Colony | [Ant Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/experimental/ant_swarm.py) | Bio-inspired optimization using ant colony algorithms for agent coordination | +| Matrix | [Agent Matrix](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/experimental/agent_matrix.py) | Grid-based agent organization for complex problem-solving | +| DFS | [DFS Search Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/experimental/dfs_search_swarm.py) | Depth-first search swarm for complex problem exploration | +| Pulsar | [Pulsar Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/experimental/pulsar_swarm.py) | Pulsar-based coordination for synchronized agent behavior | + +### Collaboration Patterns +| Category | Example | Description | +|----------|---------|-------------| +| Delegation | [Agent Delegation](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/multi_agent_collaboration/agent_delegation.py) | Task delegation and management system | +| Communication | [Message Pool](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/multi_agent_collaboration/message_pool.py) | Shared communication system for efficient agent interaction | +| Scheduling | [Round Robin](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/multi_agent_collaboration/round_robin_example.py) | Round-robin task scheduling and execution | +| Load Balancing | [Load Balancer](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/multi_agent_collaboration/load_balancer_example.py) | Dynamic task distribution system for optimal resource utilization | +| Consensus | [Majority Voting](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/multi_agent_collaboration/majority_voting.py) | Consensus-building system using democratic voting among agents | + +### Industry Applications +| Category | Example | Description | +|----------|---------|-------------| +| Finance | [Accountant Team](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/accountant_team/account_team2_example.py) | Multi-agent system for financial analysis, bookkeeping, and tax planning | +| Marketing | [Ad Generation](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/ad_gen/ad_gen_example.py) | Collaborative ad creation with copywriting and design agents | +| Aerospace | [Space Traffic Control](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/agentic_space_traffic_control/game.py) | Complex simulation of space traffic management with multiple coordinating agents | +| Agriculture | [Plant Biology](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/plant_biologist_swarm/agricultural_swarm.py) | Agricultural analysis and optimization using specialized biology agents | +| Urban Dev | [Urban Planning](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/urban_planning/urban_planning_example.py) | City development planning with multiple specialized urban development agents | +| Education | [Education System](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/education/education_example.py) | Personalized learning system with multiple teaching and assessment agents | +| Security | [Email Phishing Detection](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/email_phiser/email_swarm.py) | Multi-agent security analysis and threat detection | +| Fashion | [Personal Stylist](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/personal_stylist/personal_stylist_example.py) | Fashion recommendation system with style analysis and matching agents | +| Healthcare | [Healthcare Assistant](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/positive_med/positive_med_example.py) | Medical diagnosis and treatment planning with specialist consultation agents | +| Security Ops | [Security Team](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/security_team/security_team_example.py) | Comprehensive security operations with threat detection and response agents | +| Medical | [X-Ray Analysis](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/xray/xray_example.py) | Multi-agent medical imaging analysis and diagnosis | +| Business | [Business Strategy](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/business_strategy/business_strategy_graph/growth_agent.py) | Strategic planning and business development swarm | +| Research | [Astronomy Research](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/astronomy/multiversal_detection/test.py) | Collaborative space research and astronomical analysis | -- Macroeconomic indicators -- Company fundamentals -- Market sentiment -- Technical analysis patterns -- Regulatory considerations +## Additional Resources -For example, an investment research swarm analyzing a potential stock purchase might include specialists in the company's industry, financial statement analysis, market trend identification, and risk assessment. This collaborative approach delivers more nuanced insights than any single analyst or model could produce independently. +- [Github](https://github.com/kyegomez/swarms) -#### Regulatory Compliance -Financial regulations are complex and constantly evolving. Compliance swarms can monitor regulatory changes, assess their impact on existing policies, and recommend appropriate adjustments. These swarms might include: +- Discord (https://t.co/zlLe07AqUX) -- Regulatory monitoring agents that track new rules and guidelines -- Policy analysis agents that evaluate existing compliance frameworks -- Gap assessment agents that identify discrepancies -- Documentation agents that update compliance materials +- Telegram (https://t.co/dSRy143zQv) -This approach ensures comprehensive coverage of regulatory requirements while minimizing compliance risks. +- X Community (https://x.com/i/communities/1875452887414804745) -### Healthcare +-------------------------------------------------- -#### Medical Research Analysis -The medical literature grows at an overwhelming pace, making it difficult for researchers and clinicians to stay current. Research analysis swarms can continuously scan new publications, identify relevant findings, and synthesize insights for specific research questions or clinical scenarios. +# File: examples\paper_implementations.md -A medical research swarm might include: -- Literature scanning agents that identify relevant publications -- Methodology assessment agents that evaluate research quality -- Clinical relevance agents that determine practical applications -- Summary agents that compile key findings into accessible reports +# Multi-Agent Paper Implementations -This collaborative approach enables more thorough literature reviews and helps bridge the gap between research and clinical practice. +At Swarms, we are passionate about democratizing access to cutting-edge multi-agent research and making advanced AI collaboration accessible to everyone. Our mission is to bridge the gap between academic research and practical implementation by providing production-ready, open-source implementations of the most impactful multi-agent research papers. -#### Treatment Planning -Complex medical cases often benefit from multidisciplinary input. Treatment planning swarms can integrate perspectives from different medical specialties, consider patient-specific factors, and recommend comprehensive care approaches. +### Why Multi-Agent Research Matters -For example, an oncology treatment planning swarm might include specialists in: -- Diagnostic interpretation -- Treatment protocol evaluation -- Drug interaction assessment -- Patient history analysis -- Evidence-based outcome prediction +Multi-agent systems represent the next evolution in artificial intelligence, moving beyond single-agent limitations to harness the power of collective intelligence. These systems can: -By combining these specialized perspectives, the swarm can develop more personalized and effective treatment recommendations. +- **Overcome Individual Agent Constraints**: Address memory limitations, hallucinations, and single-task focus through collaborative problem-solving +- **Achieve Superior Performance**: Combine specialized expertise across multiple agents to tackle complex, multifaceted challenges +- **Enable Scalable Solutions**: Distribute computational load and scale efficiently across multiple agents +- **Foster Innovation**: Create novel approaches through agent interaction and knowledge sharing -### Legal Services +### Our Research Implementation Philosophy -#### Contract Analysis -Legal contracts contain numerous interconnected provisions that must be evaluated holistically. Contract analysis swarms can review complex agreements more thoroughly by assigning different sections to specialized agents: +We believe that the best way to advance the field is through practical implementation and real-world validation. Our approach includes: -- Definition analysis agents that ensure consistent terminology -- Risk assessment agents that identify potential liabilities -- Compliance agents that check regulatory requirements -- Precedent comparison agents that evaluate terms against standards -- Conflict detection agents that identify internal inconsistencies +- **Faithful Reproduction**: Implementing research papers with high fidelity to original methodologies -This distributed approach enables more comprehensive contract reviews while reducing the risk of overlooking critical details. +- **Production Enhancement**: Adding enterprise-grade features like error handling, monitoring, and scalability -#### Legal Research -Legal research requires examining statutes, case law, regulations, and scholarly commentary. Research swarms can conduct multi-faceted legal research by coordinating specialized agents focusing on different aspects of the legal landscape. +- **Open Source Commitment**: Making all implementations freely available to the research community -A legal research swarm might include: -- Statutory analysis agents that examine relevant laws -- Case law agents that review judicial precedents -- Regulatory agents that assess administrative rules -- Scholarly analysis agents that evaluate academic perspectives -- Synthesis agents that integrate findings into cohesive arguments +- **Continuous Improvement**: Iterating on implementations based on community feedback and new research -This collaborative approach produces more comprehensive legal analyses that consider multiple sources of authority. +### What You'll Find Here -### Research and Development +This documentation showcases our comprehensive collection of multi-agent research implementations, including: -#### Scientific Literature Review -Scientific research increasingly spans multiple disciplines, making comprehensive literature reviews challenging. Literature review swarms can analyze publications across relevant fields, identify methodological approaches, and synthesize findings from diverse sources. -For example, a biomedical engineering literature review swarm might include specialists in: -- Materials science -- Cellular biology -- Clinical applications -- Regulatory requirements -- Statistical methods +- **Academic Paper Implementations**: Direct implementations of published research papers -By integrating insights from these different perspectives, the swarm can produce more comprehensive and valuable literature reviews. +- **Enhanced Frameworks**: Production-ready versions with additional features and optimizations -#### Experimental Design -Designing robust experiments requires considering multiple factors simultaneously. Experimental design swarms can develop sophisticated research protocols by integrating methodological expertise, statistical considerations, practical constraints, and ethical requirements. +- **Research Compilations**: Curated lists of influential multi-agent papers and resources -An experimental design swarm might coordinate: -- Methodology agents that design experimental procedures -- Statistical agents that determine appropriate sample sizes and analyses -- Logistics agents that assess practical feasibility -- Ethics agents that evaluate potential concerns -- Documentation agents that prepare formal protocols +- **Practical Examples**: Ready-to-use code examples and tutorials -This collaborative approach leads to more rigorous experimental designs while addressing potential issues preemptively. +Whether you're a researcher looking to validate findings, a developer building production systems, or a student learning about multi-agent AI, you'll find valuable resources here to advance your work. -### Software Development +### Join the Multi-Agent Revolution -#### Code Review and Optimization -Code review requires evaluating multiple aspects simultaneously: functionality, security, performance, maintainability, and adherence to standards. Code review swarms can distribute these concerns among specialized agents: +We invite you to explore these implementations, contribute to our research efforts, and help shape the future of collaborative AI. Together, we can unlock the full potential of multi-agent systems and create AI that truly works as a team. -- Functionality agents that evaluate whether code meets requirements -- Security agents that identify potential vulnerabilities -- Performance agents that assess computational efficiency -- Style agents that check adherence to coding standards -- Documentation agents that review comments and documentation +## Implemented Research Papers -By addressing these different aspects in parallel, code review swarms can provide more comprehensive feedback to development teams. +| Paper Name | Description | Original Paper | Implementation | Status | Key Features | +|------------|-------------|----------------|----------------|--------|--------------| +| **MALT (Multi-Agent Learning Task)** | A sophisticated orchestration framework that coordinates multiple specialized AI agents to tackle complex tasks through structured conversations. | [arXiv:2412.01928](https://arxiv.org/pdf/2412.01928) | [`swarms.structs.malt`](https://docs.swarms.world/en/latest/swarms/structs/malt/) | ✅ Complete | Creator-Verifier-Refiner architecture, structured conversations, reliability guarantees | +| **[MAI-DxO (MAI Diagnostic Orchestrator)](https://arxiv.org/abs/2506.22405)** | An open-source implementation of Microsoft Research's "[Sequential Diagnosis with Language Models](https://arxiv.org/abs/2506.22405)" paper, simulating a virtual panel of physician-agents for iterative medical diagnosis. | Microsoft Research Paper | [GitHub Repository](https://github.com/The-Swarm-Corporation/Open-MAI-Dx-Orchestrator) | ✅ Complete | Cost-effective medical diagnosis, physician-agent panel, iterative refinement | +| **[AI-CoScientist](https://storage.googleapis.com/coscientist_paper/ai_coscientist.pdf)** | A multi-agent AI framework for collaborative scientific research, implementing the "Towards an AI Co-Scientist" methodology with tournament-based hypothesis evolution. | "Towards an AI Co-Scientist" Paper | [GitHub Repository](https://github.com/The-Swarm-Corporation/AI-CoScientist) | ✅ Complete | Tournament-based selection, peer review systems, hypothesis evolution, Elo rating system | +| **[Mixture of Agents (MoA)](https://arxiv.org/abs/2406.04692)** | A sophisticated multi-agent architecture that implements parallel processing with iterative refinement, combining diverse expert agents for comprehensive analysis. | Multi-agent collaboration concepts | [`swarms.structs.moa`](https://docs.swarms.world/en/latest/swarms/structs/moa/) | ✅ Complete | Parallel processing, expert agent combination, iterative refinement, state-of-the-art performance | +| **Deep Research Swarm** | A production-grade research system that conducts comprehensive analysis across multiple domains using parallel processing and advanced AI agents. | Research methodology | [`swarms.structs.deep_research_swarm`](https://docs.swarms.world/en/latest/swarms/structs/deep_research_swarm/) | ✅ Complete | Parallel search processing, multi-agent coordination, information synthesis, concurrent execution | +| **Agent-as-a-Judge** | An evaluation framework that uses agents to evaluate other agents, implementing the "Agent-as-a-Judge: Evaluate Agents with Agents" methodology. | [arXiv:2410.10934](https://arxiv.org/abs/2410.10934) | [`swarms.agents.agent_judge`](https://docs.swarms.world/en/latest/swarms/agents/agent_judge/) | ✅ Complete | Agent evaluation, quality assessment, automated judging, performance metrics | -#### System Architecture Design -Designing complex software systems requires balancing numerous considerations. Architecture design swarms can develop more robust system designs by coordinating specialists in different architectural concerns: +## Additional Research Resources -- Scalability agents that evaluate growth potential -- Security agents that assess protective measures -- Performance agents that analyze efficiency -- Maintainability agents that consider long-term management -- Integration agents that evaluate external system connections +### Multi-Agent Papers Compilation -This collaborative approach leads to more balanced architectural decisions that address multiple requirements simultaneously. +We maintain a comprehensive list of multi-agent research papers at: [awesome-multi-agent-papers](https://github.com/kyegomez/awesome-multi-agent-papers) -## Getting Started with the Swarms API +### Research Lists -The Swarms API is designed for straightforward integration into existing workflows. Let's walk through the setup process and explore some practical code examples for different industries. +Our research compilation includes: -### 1. Setting Up Your Environment +- **Projects**: ModelScope-Agent, Gorilla, BMTools, LMQL, Langchain, MetaGPT, AutoGPT, and more -First, create an account on [swarms.world](https://swarms.world). After registration, navigate to the API key management interface at [https://swarms.world/platform/api-keys](https://swarms.world/platform/api-keys) to generate your API key. +- **Research Papers**: BOLAA, ToolLLM, Communicative Agents, Mind2Web, Voyager, Tree of Thoughts, and many others -Once you have your API key, set up your Python environment: +- **Blog Articles**: Latest insights and developments in autonomous agents -```python -# Install required packages -pip install requests python-dotenv -``` +- **Talks**: Presentations from leading researchers like Geoffrey Hinton and Andrej Karpathy -Create a basic project structure: -``` -swarms-project/ -├── .env # Store your API key securely -├── swarms_client.py # Helper functions for API interaction -└── examples/ # Industry-specific examples -``` +## Implementation Details -In your `.env` file, add your API key: +### MALT Framework -``` -SWARMS_API_KEY=your_api_key_here -``` +The MALT implementation provides: -### 2. Creating a Basic Swarms Client +- **Three-Agent Architecture**: Creator, Verifier, and Refiner agents -Let's create a simple client to interact with the Swarms API: +- **Structured Workflow**: Coordinated task execution with conversation history -```python -# swarms_client.py -import os -import requests -from dotenv import load_dotenv -import json +- **Reliability Features**: Error handling, validation, and quality assurance -# Load environment variables -load_dotenv() +- **Extensibility**: Custom agent integration and configuration options -# Configuration -API_KEY = os.getenv("SWARMS_API_KEY") -BASE_URL = "https://api.swarms.world" -# Standard headers for all requests -headers = { - "x-api-key": API_KEY, - "Content-Type": "application/json" -} +### MAI-DxO System -def check_api_health(): - """Simple health check to verify API connectivity.""" - response = requests.get(f"{BASE_URL}/health", headers=headers) - return response.json() +The MAI Diagnostic Orchestrator features: -def run_swarm(swarm_config): - """Execute a swarm with the provided configuration.""" - response = requests.post( - f"{BASE_URL}/v1/swarm/completions", - headers=headers, - json=swarm_config - ) - return response.json() +- **Virtual Physician Panel**: Multiple specialized medical agents -def get_available_swarms(): - """Retrieve list of available swarm types.""" - response = requests.get(f"{BASE_URL}/v1/swarms/available", headers=headers) - return response.json() +- **Cost Optimization**: Efficient diagnostic workflows -def get_available_models(): - """Retrieve list of available AI models.""" - response = requests.get(f"{BASE_URL}/v1/models/available", headers=headers) - return response.json() +- **Iterative Refinement**: Continuous improvement of diagnoses -def get_swarm_logs(): - """Retrieve logs of previous swarm executions.""" - response = requests.get(f"{BASE_URL}/v1/swarm/logs", headers=headers) - return response.json() -``` +- **Medical Expertise**: Domain-specific knowledge and reasoning -### 3. Industry-Specific Examples -Let's explore practical applications of the Swarms API across different industries. +### AI-CoScientist Framework -#### Healthcare: Clinical Research Assistant +The AI-CoScientist implementation includes: -This example creates a swarm that analyzes clinical trial data and summarizes findings: +- **Tournament-Based Selection**: Elo rating system for hypothesis ranking -```python -# healthcare_example.py -from swarms_client import run_swarm -import json +- **Peer Review System**: Comprehensive evaluation of scientific proposals -def clinical_research_assistant(): - """ - Create a swarm that analyzes clinical trial data, identifies patterns, - and generates comprehensive research summaries. - """ - swarm_config = { - "name": "Clinical Research Assistant", - "description": "Analyzes medical research data and synthesizes findings", - "agents": [ - { - "agent_name": "Data Preprocessor", - "description": "Cleans and organizes clinical trial data", - "system_prompt": "You are a data preprocessing specialist focused on clinical trials. " - "Your task is to organize, clean, and structure raw clinical data for analysis. " - "Identify and handle missing values, outliers, and inconsistencies in the data.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - }, - { - "agent_name": "Clinical Analyst", - "description": "Analyzes preprocessed data to identify patterns and insights", - "system_prompt": "You are a clinical research analyst with expertise in interpreting medical data. " - "Your job is to examine preprocessed clinical trial data, identify significant patterns, " - "and determine the clinical relevance of these findings. Consider factors such as " - "efficacy, safety profiles, and patient subgroups.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - }, - { - "agent_name": "Medical Writer", - "description": "Synthesizes analysis into comprehensive reports", - "system_prompt": "You are a medical writer specializing in clinical research. " - "Your task is to take the analyses provided and create comprehensive, " - "well-structured reports that effectively communicate findings to both " - "medical professionals and regulatory authorities. Follow standard " - "medical publication guidelines.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - } - ], - "max_loops": 1, - "swarm_type": "SequentialWorkflow", - "task": "Analyze the provided Phase III clinical trial data for Drug XYZ, " - "a novel treatment for type 2 diabetes. Identify efficacy patterns across " - "different patient demographics, note any safety concerns, and prepare " - "a comprehensive summary suitable for submission to regulatory authorities." - } - - # Execute the swarm - result = run_swarm(swarm_config) - - # Print formatted results - print(json.dumps(result, indent=4)) - return result +- **Hypothesis Evolution**: Iterative refinement based on feedback -if __name__ == "__main__": - clinical_research_assistant() -``` +- **Diversity Control**: Proximity analysis to maintain hypothesis variety -#### Legal: Contract Analysis System -This example demonstrates a swarm designed to analyze complex legal contracts: +### Mixture of Agents (MoA) -```python -# legal_example.py -from swarms_client import run_swarm -import json +The MoA architecture provides: -def contract_analysis_system(): - """ - Create a swarm that thoroughly analyzes legal contracts, - identifies potential risks, and suggests improvements. - """ - swarm_config = { - "name": "Contract Analysis System", - "description": "Analyzes legal contracts for risks and improvement opportunities", - "agents": [ - { - "agent_name": "Clause Extractor", - "description": "Identifies and categorizes key clauses in contracts", - "system_prompt": "You are a legal document specialist. Your task is to " - "carefully review legal contracts and identify all key clauses, " - "categorizing them by type (liability, indemnification, termination, etc.). " - "Extract each clause with its context and prepare them for detailed analysis.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - }, - { - "agent_name": "Risk Assessor", - "description": "Evaluates clauses for potential legal risks", - "system_prompt": "You are a legal risk assessment expert. Your job is to " - "analyze contract clauses and identify potential legal risks, " - "exposure points, and unfavorable terms. Rate each risk on a " - "scale of 1-5 and provide justification for your assessment.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - }, - { - "agent_name": "Improvement Recommender", - "description": "Suggests alternative language to mitigate risks", - "system_prompt": "You are a contract drafting expert. Based on the risk " - "assessment provided, suggest alternative language for " - "problematic clauses to better protect the client's interests. " - "Ensure suggestions are legally sound and professionally worded.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - }, - { - "agent_name": "Summary Creator", - "description": "Creates executive summary of findings and recommendations", - "system_prompt": "You are a legal communication specialist. Create a clear, " - "concise executive summary of the contract analysis, highlighting " - "key risks and recommendations. Your summary should be understandable " - "to non-legal executives while maintaining accuracy.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - } - ], - "max_loops": 1, - "swarm_type": "SequentialWorkflow", - "task": "Analyze the attached software licensing agreement between TechCorp and ClientInc. " - "Identify all key clauses, assess potential risks to ClientInc, suggest improvements " - "to better protect ClientInc's interests, and create an executive summary of findings." - } - - # Execute the swarm - result = run_swarm(swarm_config) - - # Print formatted results - print(json.dumps(result, indent=4)) - return result - -if __name__ == "__main__": - contract_analysis_system() -``` +- **Parallel Processing**: Multiple agents working simultaneously -#### Private Equity: Investment Opportunity Analysis +- **Expert Specialization**: Domain-specific agent capabilities -This example shows a swarm that performs comprehensive due diligence on potential investments: +- **Iterative Refinement**: Continuous improvement through collaboration -```python -# private_equity_example.py -from swarms_client import run_swarm, schedule_swarm -import json -from datetime import datetime, timedelta +- **State-of-the-Art Performance**: Achieving superior results through collective intelligence -def investment_opportunity_analysis(): - """ - Create a swarm that performs comprehensive due diligence - on potential private equity investment opportunities. - """ - swarm_config = { - "name": "PE Investment Analyzer", - "description": "Performs comprehensive analysis of private equity investment opportunities", - "agents": [ - { - "agent_name": "Financial Analyst", - "description": "Analyzes financial statements and projections", - "system_prompt": "You are a private equity financial analyst with expertise in " - "evaluating company financials. Review the target company's financial " - "statements, analyze growth trajectories, profit margins, cash flow patterns, " - "and debt structure. Identify financial red flags and growth opportunities.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - }, - { - "agent_name": "Market Researcher", - "description": "Assesses market conditions and competitive landscape", - "system_prompt": "You are a market research specialist in the private equity sector. " - "Analyze the target company's market position, industry trends, competitive " - "landscape, and growth potential. Identify market-related risks and opportunities " - "that could impact investment returns.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - }, - { - "agent_name": "Operational Due Diligence", - "description": "Evaluates operational efficiency and improvement opportunities", - "system_prompt": "You are an operational due diligence expert. Analyze the target " - "company's operational structure, efficiency metrics, supply chain, " - "technology infrastructure, and management capabilities. Identify " - "operational improvement opportunities that could increase company value.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - }, - { - "agent_name": "Risk Assessor", - "description": "Identifies regulatory, legal, and business risks", - "system_prompt": "You are a risk assessment specialist in private equity. " - "Evaluate potential regulatory challenges, legal liabilities, " - "compliance issues, and business model vulnerabilities. Rate " - "each risk based on likelihood and potential impact.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - }, - { - "agent_name": "Investment Thesis Creator", - "description": "Synthesizes analysis into comprehensive investment thesis", - "system_prompt": "You are a private equity investment strategist. Based on the " - "analyses provided, develop a comprehensive investment thesis " - "that includes valuation assessment, potential returns, value " - "creation opportunities, exit strategies, and investment recommendations.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - } - ], - "max_loops": 1, - "swarm_type": "SequentialWorkflow", - "task": "Perform comprehensive due diligence on HealthTech Inc., a potential acquisition " - "target in the healthcare technology sector. The company develops remote patient " - "monitoring solutions and has shown 35% year-over-year growth for the past three years. " - "Analyze financials, market position, operational structure, potential risks, and " - "develop an investment thesis with a recommended valuation range." - } - - # Option 1: Execute the swarm immediately - result = run_swarm(swarm_config) - - # Option 2: Schedule the swarm for tomorrow morning - tomorrow = (datetime.now() + timedelta(days=1)).replace(hour=8, minute=0, second=0).isoformat() - # scheduled_result = schedule_swarm(swarm_config, tomorrow, "America/New_York") - - # Print formatted results from immediate execution - print(json.dumps(result, indent=4)) - return result -if __name__ == "__main__": - investment_opportunity_analysis() -``` +## Contributing -#### Education: Curriculum Development Assistant +We welcome contributions to implement additional research papers! If you'd like to contribute: -This example shows how to use the Concurrent Workflow swarm type: +1. **Identify a paper**: Choose a relevant multi-agent research paper +2. **Propose implementation**: Submit an issue with your proposal +3. **Implement**: Create the implementation following our guidelines +4. **Document**: Add comprehensive documentation and examples +5. **Test**: Ensure robust testing and validation -```python -# education_example.py -from swarms_client import run_swarm -import json +## Citation -def curriculum_development_assistant(): - """ - Create a swarm that assists in developing educational curriculum - with concurrent subject matter experts. - """ - swarm_config = { - "name": "Curriculum Development Assistant", - "description": "Develops comprehensive educational curriculum", - "agents": [ - { - "agent_name": "Subject Matter Expert", - "description": "Provides domain expertise on the subject", - "system_prompt": "You are a subject matter expert in data science. " - "Your role is to identify the essential concepts, skills, " - "and knowledge that students need to master in a comprehensive " - "data science curriculum. Focus on both theoretical foundations " - "and practical applications, ensuring the content reflects current " - "industry standards and practices.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - }, - { - "agent_name": "Instructional Designer", - "description": "Structures learning objectives and activities", - "system_prompt": "You are an instructional designer specializing in technical education. " - "Your task is to transform subject matter content into structured learning " - "modules with clear objectives, engaging activities, and appropriate assessments. " - "Design the learning experience to accommodate different learning styles and " - "knowledge levels.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - }, - { - "agent_name": "Assessment Specialist", - "description": "Develops evaluation methods and assessments", - "system_prompt": "You are an educational assessment specialist. " - "Design comprehensive assessment strategies to evaluate student " - "learning throughout the curriculum. Create formative and summative " - "assessments, rubrics, and feedback mechanisms that align with learning " - "objectives and provide meaningful insights into student progress.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - }, - { - "agent_name": "Curriculum Integrator", - "description": "Synthesizes input from all specialists into a cohesive curriculum", - "system_prompt": "You are a curriculum development coordinator. " - "Your role is to synthesize the input from subject matter experts, " - "instructional designers, and assessment specialists into a cohesive, " - "comprehensive curriculum. Ensure logical progression of topics, " - "integration of theory and practice, and alignment between content, " - "activities, and assessments.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - } - ], - "max_loops": 1, - "swarm_type": "ConcurrentWorkflow", # Experts work simultaneously before integration - "task": "Develop a comprehensive 12-week data science curriculum for advanced undergraduate " - "students with programming experience. The curriculum should cover data analysis, " - "machine learning, data visualization, and ethics in AI. Include weekly learning " - "objectives, teaching materials, hands-on activities, and assessment methods. " - "The curriculum should prepare students for entry-level data science positions." - } - - # Execute the swarm - result = run_swarm(swarm_config) - - # Print formatted results - print(json.dumps(result, indent=4)) - return result +If you use any of these implementations in your research, please cite the original papers and the Swarms framework: -if __name__ == "__main__": - curriculum_development_assistant() +```bibtex +@misc{SWARMS_2022, + author = {Gomez, Kye and Pliny and More, Harshal and Swarms Community}, + title = {{Swarms: Production-Grade Multi-Agent Infrastructure Platform}}, + year = {2022}, + howpublished = {\url{https://github.com/kyegomez/swarms}}, + note = {Documentation available at \url{https://docs.swarms.world}}, + version = {latest} +} ``` +## Community -### 5. Monitoring and Optimization +Join our community to stay updated on the latest multi-agent research implementations: -To optimize your swarm configurations and track usage patterns, you can retrieve and analyze logs: +- **Discord**: [Join our community](https://discord.gg/jM3Z6M9uMq) -```python -# analytics_example.py -from swarms_client import get_swarm_logs -import json +- **Documentation**: [docs.swarms.world](https://docs.swarms.world) -def analyze_swarm_usage(): - """ - Analyze swarm usage patterns to optimize configurations and costs. - """ - # Retrieve logs - logs = get_swarm_logs() +- **GitHub**: [kyegomez/swarms](https://github.com/kyegomez/swarms) - return logs -if __name__ == "__main__": - analyze_swarm_usage() -``` +- **Research Papers**: [awesome-multi-agent-papers](https://github.com/kyegomez/awesome-multi-agent-papers) -### 6. Next Steps -Once you've implemented and tested these examples, you can further optimize your swarm configurations by: -1. Experimenting with different swarm architectures for the same task to compare results -2. Adjusting agent prompts to improve specialization and collaboration -3. Fine-tuning model parameters like temperature and max_tokens -4. Combining swarms into larger workflows through scheduled execution -The Swarms API's flexibility allows for continuous refinement of your AI orchestration strategies, enabling increasingly sophisticated solutions to complex problems. +-------------------------------------------------- -## The Future of AI Agent Orchestration +# File: examples\templates.md -The Swarms API represents a significant evolution in how we deploy AI for complex tasks. As we look to the future, several trends are emerging in the field of agent orchestration: +# Templates & Applications Documentation -### Specialized Agent Ecosystems +The Swarms framework is a powerful multi-agent orchestration platform that enables developers to build sophisticated AI agent systems. This documentation showcases the extensive ecosystem of templates, applications, and tools built on the Swarms framework, organized by industry and application type. -We're moving toward rich ecosystems of highly specialized agents designed for specific tasks and domains. These specialized agents will have deep expertise in narrow areas, enabling more sophisticated collaboration when combined in swarms. +🔗 **Main Repository**: [Swarms Framework](https://github.com/kyegomez/swarms) -### Dynamic Swarm Formation +--- -Future swarm platforms will likely feature even more advanced capabilities for dynamic swarm formation, where the system automatically determines not only which agents to include but also how they should collaborate based on real-time task analysis. +## 🏥 Healthcare & Medical Applications -### Cross-Modal Collaboration +### Medical Diagnosis & Analysis -As AI capabilities expand across modalities (text, image, audio, video), we'll see increasing collaboration between agents specialized in different data types. This cross-modal collaboration will enable more comprehensive analysis and content creation spanning multiple formats. +| Name | Description | Type | Repository | +|------|-------------|------|------------| +| [MRI-Swarm](https://github.com/The-Swarm-Corporation/MRI-Swarm) | Multi-agent system for MRI image analysis and diagnosis | Medical Imaging | Healthcare | +| [DermaSwarm](https://github.com/The-Swarm-Corporation/DermaSwarm) | Dermatology-focused agent swarm for skin condition analysis | Medical Diagnosis | Healthcare | +| [Multi-Modal-XRAY-Diagnosis](https://github.com/The-Swarm-Corporation/Multi-Modal-XRAY-Diagnosis-Medical-Swarm-Template) | X-ray diagnosis using multi-modal AI agents | Medical Imaging | Healthcare | +| [Open-MAI-Dx-Orchestrator](https://github.com/The-Swarm-Corporation/Open-MAI-Dx-Orchestrator) | Medical AI diagnosis orchestration platform | Medical Platform | Healthcare | +| [radiology-swarm](https://github.com/The-Swarm-Corporation/radiology-swarm) | Radiology-focused multi-agent system | Medical Imaging | Healthcare | -### Human-Swarm Collaboration +### Medical Operations & Administration -The next frontier in agent orchestration will be seamless collaboration between human teams and AI swarms, where human specialists and AI agents work together, each contributing their unique strengths to complex problems. +| Name | Description | Type | Repository | +|------|-------------|------|------------| +| [MedicalCoderSwarm](https://github.com/The-Swarm-Corporation/MedicalCoderSwarm) | Medical coding automation using agent swarms | Medical Coding | Healthcare | +| [pharma-swarm](https://github.com/The-Swarm-Corporation/pharma-swarm) | Pharmaceutical research and development agents | Pharmaceutical | Healthcare | +| [MedGuard](https://github.com/The-Swarm-Corporation/MedGuard) | Medical data security and compliance system | Medical Security | Healthcare | +| [MedInsight-Pro](https://github.com/The-Swarm-Corporation/MedInsight-Pro) | Advanced medical insights and analytics platform | Medical Analytics | Healthcare | -### Continuous Learning Swarms +--- -Future swarms will likely incorporate more sophisticated mechanisms for continuous improvement, with agent capabilities evolving based on past performance and feedback. +## 💰 Financial Services & Trading -## Conclusion +### Trading & Investment -The Swarms API represents a significant leap forward in AI orchestration, moving beyond the limitations of single-agent systems to unlock the power of collaborative intelligence. By enabling specialized agents to work together in coordinated swarms, this enterprise-grade platform opens new possibilities for solving complex problems across industries. +| Name | Description | Type | Repository | +|------|-------------|------|------------| +| [automated-crypto-fund](https://github.com/The-Swarm-Corporation/automated-crypto-fund) | Automated cryptocurrency trading fund management | Crypto Trading | Finance | +| [CryptoAgent](https://github.com/The-Swarm-Corporation/CryptoAgent) | Cryptocurrency analysis and trading agent | Crypto Trading | Finance | +| [AutoHedge](https://github.com/The-Swarm-Corporation/AutoHedge) | Automated hedging strategies implementation | Risk Management | Finance | +| [BackTesterAgent](https://github.com/The-Swarm-Corporation/BackTesterAgent) | Trading strategy backtesting automation | Trading Tools | Finance | +| [ForexTreeSwarm](https://github.com/The-Swarm-Corporation/ForexTreeSwarm) | Forex trading decision tree swarm system | Forex Trading | Finance | +| [HTX-Swarm](https://github.com/The-Swarm-Corporation/HTX-Swarm) | HTX exchange integration and trading automation | Crypto Exchange | Finance | -From financial analysis to healthcare research, legal services to software development, the applications for agent swarms are as diverse as they are powerful. The Swarms API provides the infrastructure, tools, and flexibility needed to deploy these collaborative AI systems at scale, with the security, reliability, and cost management features essential for enterprise adoption. +### Financial Analysis & Management -As we continue to push the boundaries of what AI can accomplish, the ability to orchestrate collaborative intelligence will become increasingly crucial. The Swarms API is at the forefront of this evolution, providing a glimpse into the future of AI—a future where the most powerful AI systems aren't individual models but coordinated teams of specialized agents working together to solve our most challenging problems. +| Name | Description | Type | Repository | +|------|-------------|------|------------| +| [TickrAgent](https://github.com/The-Swarm-Corporation/TickrAgent) | Stock ticker analysis and monitoring agent | Stock Analysis | Finance | +| [Open-Aladdin](https://github.com/The-Swarm-Corporation/Open-Aladdin) | Open-source financial risk management system | Risk Management | Finance | +| [CryptoTaxSwarm](https://github.com/The-Swarm-Corporation/CryptoTaxSwarm) | Cryptocurrency tax calculation and reporting | Tax Management | Finance | -For organizations looking to harness the full potential of AI, the Swarms API offers a compelling path forward—one that leverages the power of collaboration to achieve results beyond what any single AI agent could accomplish alone. +### Insurance & Lending -To explore the Swarms API and begin building your own intelligent agent swarms, visit [swarms.world](https://swarms.world) today. +| Name | Description | Type | Repository | +|------|-------------|------|------------| +| [InsuranceSwarm](https://github.com/The-Swarm-Corporation/InsuranceSwarm) | Insurance claim processing and underwriting | Insurance | Finance | +| [MortgageUnderwritingSwarm](https://github.com/The-Swarm-Corporation/MortgageUnderwritingSwarm) | Automated mortgage underwriting system | Lending | Finance | --- -## Resources - -* Website: [swarms.ai](https://swarms.ai) -* Marketplace: [swarms.world](https://swarms.world) -* Cloud Platform: [cloud.swarms.ai](https://cloud.swarms.ai) -* Documentation: [docs.swarms.world](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/) +## 🔬 Research & Development --------------------------------------------------- +### Scientific Research -# File: concepts/limitations.md +| Name | Description | Type | Repository | +|------|-------------|------|------------| +| [AI-CoScientist](https://github.com/The-Swarm-Corporation/AI-CoScientist) | AI research collaboration platform | Research Platform | Science | +| [auto-ai-research-team](https://github.com/The-Swarm-Corporation/auto-ai-research-team) | Automated AI research team coordination | Research Automation | Science | +| [Research-Paper-Writer-Swarm](https://github.com/The-Swarm-Corporation/Research-Paper-Writer-Swarm) | Automated research paper writing system | Academic Writing | Science | -# Limitations of Individual Agents +### Mathematical & Analytical -This section explores the fundamental limitations of individual AI agents and why multi-agent systems are necessary for complex tasks. Understanding these limitations is crucial for designing effective multi-agent architectures. +| Name | Description | Type | Repository | +|------|-------------|------|------------| +| [Generalist-Mathematician-Swarm](https://github.com/The-Swarm-Corporation/Generalist-Mathematician-Swarm) | Mathematical problem-solving agent swarm | Mathematics | Science | -## Overview +--- -```mermaid -graph TD - A[Individual Agent Limitations] --> B[Context Window Limits] - A --> C[Hallucination] - A --> D[Single Task Execution] - A --> E[Lack of Collaboration] - A --> F[Accuracy Issues] - A --> G[Processing Speed] -``` +## 💼 Business & Marketing -## 1. Context Window Limits +### Marketing & Content -### The Challenge -Individual agents are constrained by fixed context windows, limiting their ability to process large amounts of information simultaneously. +| Name | Description | Type | Repository | +|------|-------------|------|------------| +| [Marketing-Swarm-Template](https://github.com/The-Swarm-Corporation/Marketing-Swarm-Template) | Marketing campaign automation template | Marketing Automation | Business | +| [Multi-Agent-Marketing-Course](https://github.com/The-Swarm-Corporation/Multi-Agent-Marketing-Course) | Educational course on multi-agent marketing | Marketing Education | Business | +| [NewsAgent](https://github.com/The-Swarm-Corporation/NewsAgent) | News aggregation and analysis agent | News Analysis | Business | -```mermaid -graph LR - subgraph "Context Window Limitation" - Input[Large Document] --> Truncation[Truncation] - Truncation --> ProcessedPart[Processed Part] - Truncation --> UnprocessedPart[Unprocessed Part] - end -``` +### Legal Services -### Impact -- Limited understanding of large documents -- Fragmented processing of long conversations -- Inability to maintain extended context -- Loss of important information +| Name | Description | Type | Repository | +|------|-------------|------|------------| +| [Legal-Swarm-Template](https://github.com/The-Swarm-Corporation/Legal-Swarm-Template) | Legal document processing and analysis | Legal Technology | Business | -## 2. Hallucination +--- -### The Challenge -Individual agents may generate plausible-sounding but incorrect information, especially when dealing with ambiguous or incomplete data. +## 🛠️ Development Tools & Platforms -```mermaid -graph TD - Input[Ambiguous Input] --> Agent[AI Agent] - Agent --> Valid[Valid Output] - Agent --> Hallucination[Hallucinated Output] - style Hallucination fill:#ff9999 -``` +### Core Platforms & Operating Systems -### Impact -- Unreliable information generation -- Reduced trust in system outputs -- Potential for misleading decisions -- Need for extensive verification +| Name | Description | Type | Repository | +|------|-------------|------|------------| +| [AgentOS](https://github.com/The-Swarm-Corporation/AgentOS) | Operating system for AI agents | Agent Platform | Development | +| [swarm-ecosystem](https://github.com/The-Swarm-Corporation/swarm-ecosystem) | Complete ecosystem for swarm development | Ecosystem Platform | Development | +| [AgentAPIProduction](https://github.com/The-Swarm-Corporation/AgentAPIProduction) | Production-ready agent API system | API Platform | Development | -## 3. Single Task Execution +### Development Tools & Utilities -### The Challenge -Most individual agents are optimized for specific tasks and struggle with multi-tasking or adapting to new requirements. +| Name | Description | Type | Repository | +|------|-------------|------|------------| +| [DevSwarm](https://github.com/The-Swarm-Corporation/DevSwarm) | Development-focused agent swarm | Development Tools | Development | +| [FluidAPI](https://github.com/The-Swarm-Corporation/FluidAPI) | Dynamic API generation and management | API Tools | Development | +| [OmniParse](https://github.com/The-Swarm-Corporation/OmniParse) | Universal document parsing system | Document Processing | Development | +| [doc-master](https://github.com/The-Swarm-Corporation/doc-master) | Documentation generation and management | Documentation Tools | Development | -```mermaid -graph LR - Task1[Task A] --> Agent1[Agent A] - Task2[Task B] --> Agent2[Agent B] - Task3[Task C] --> Agent3[Agent C] - Agent1 --> Output1[Output A] - Agent2 --> Output2[Output B] - Agent3 --> Output3[Output C] -``` +### Templates & Examples -### Impact -- Limited flexibility -- Inefficient resource usage -- Complex integration requirements -- Reduced adaptability +| Name | Description | Type | Repository | +|------|-------------|------|------------| +| [Multi-Agent-Template-App](https://github.com/The-Swarm-Corporation/Multi-Agent-Template-App) | Template application for multi-agent systems | Template | Development | +| [swarms-examples](https://github.com/The-Swarm-Corporation/swarms-examples) | Collection of Swarms framework examples | Examples | Development | +| [Phala-Deployment-Template](https://github.com/The-Swarm-Corporation/Phala-Deployment-Template) | Deployment template for Phala Network | Deployment Template | Development | -## 4. Lack of Collaboration +--- -### The Challenge -Individual agents operate in isolation, unable to share insights or coordinate actions with other agents. +## 📚 Educational Resources -```mermaid -graph TD - A1[Agent 1] --> O1[Output 1] - A2[Agent 2] --> O2[Output 2] - A3[Agent 3] --> O3[Output 3] - style A1 fill:#f9f,stroke:#333 - style A2 fill:#f9f,stroke:#333 - style A3 fill:#f9f,stroke:#333 -``` +### Courses & Guides -### Impact -- No knowledge sharing -- Duplicate effort -- Missed optimization opportunities -- Limited problem-solving capabilities +| Name | Description | Type | Repository | +|------|-------------|------|------------| +| [Enterprise-Grade-Agents-Course](https://github.com/The-Swarm-Corporation/Enterprise-Grade-Agents-Course) | Comprehensive course on enterprise AI agents | Educational Course | Education | +| [Agents-Beginner-Guide](https://github.com/The-Swarm-Corporation/Agents-Beginner-Guide) | Beginner's guide to AI agents | Educational Guide | Education | -## 5. Accuracy Issues +### Testing & Evaluation -### The Challenge -Individual agents may produce inaccurate results due to: -- Limited training data -- Model biases -- Lack of cross-validation -- Incomplete context understanding +| Name | Description | Type | Repository | +|------|-------------|------|------------| +| [swarms-evals](https://github.com/The-Swarm-Corporation/swarms-evals) | Evaluation framework for swarm systems | Testing Framework | Development | -```mermaid -graph LR - Input[Input Data] --> Processing[Processing] - Processing --> Accurate[Accurate Output] - Processing --> Inaccurate[Inaccurate Output] - style Inaccurate fill:#ff9999 -``` +--- -## 6. Processing Speed Limitations +## 🚀 Getting Started -### The Challenge -Individual agents may experience: -- Slow response times -- Resource constraints -- Limited parallel processing -- Bottlenecks in complex tasks +### Prerequisites -```mermaid -graph TD - Input[Input] --> Queue[Processing Queue] - Queue --> Processing[Sequential Processing] - Processing --> Delay[Processing Delay] - Delay --> Output[Delayed Output] -``` +- Python 3.8+ -## Best Practices for Mitigation +- Basic understanding of AI agents and multi-agent systems -1. **Use Multi-Agent Systems** - - Distribute tasks across agents - - Enable parallel processing - - Implement cross-validation - - Foster collaboration +- Familiarity with the Swarms framework -2. **Implement Verification** - - Cross-check results - - Use consensus mechanisms - - Monitor accuracy metrics - - Track performance -3. **Optimize Resource Usage** - - Balance load distribution - - Cache frequent operations - - Implement efficient queuing - - Monitor system health +### Installation -## Conclusion +```bash +pip install swarms +``` -Understanding these limitations is crucial for: -- Designing robust multi-agent systems -- Implementing effective mitigation strategies -- Optimizing system performance -- Ensuring reliable outputs +### Quick Start -The next section explores how [Multi-Agent Architecture](architecture.md) addresses these limitations through collaborative approaches and specialized agent roles. +1. Choose a template from the categories above --------------------------------------------------- +2. Clone the repository -# File: contributors/docs.md +3. Follow the setup instructions in the README -# Contributing to Swarms Documentation +4. Customize the agents for your specific use case --- -The Swarms documentation serves as the primary gateway for developer and user engagement within the Swarms ecosystem. Comprehensive, clear, and consistently updated documentation accelerates adoption, reduces support requests, and helps maintain a thriving developer community. This guide offers an in-depth, actionable framework for contributing to the Swarms documentation site, covering the full lifecycle from initial setup to the implementation of our bounty-based rewards program. - -This guide is designed for first-time contributors, experienced engineers, and technical writers alike. It emphasizes professional standards, collaborative development practices, and incentivized participation through our structured rewards program. Contributors play a key role in helping us scale and evolve our ecosystem by improving the clarity, accessibility, and technical depth of our documentation. +## 🤝 Contributing ---- +The Swarms ecosystem is constantly growing. To contribute: -## 1. Introduction +1. Fork the main [Swarms repository](https://github.com/kyegomez/swarms) +2. Create your feature branch +3. Submit a pull request +4. Join the community discussions -Documentation in the Swarms ecosystem is not simply static text. It is a living, breathing system that guides users, developers, and enterprises in effectively utilizing our frameworks, SDKs, APIs, and tools. Whether you are documenting a new feature, refining an API call, writing a tutorial, or correcting existing information, every contribution has a direct impact on the product’s usability and user satisfaction. +--- -**Objectives of this Guide:** +## 📞 Support & Community +Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights! -- Define a standardized contribution workflow for Swarms documentation. +| Platform | Description | Link | +|----------|-------------|------| +| 🏠 Main Repository | Swarms Framework | [GitHub](https://github.com/kyegomez/swarms) | +| 🏢 Organization | The Swarm Corporation | [GitHub Org](https://github.com/The-Swarm-Corporation) | +| 🌐 Website | Official project website | [swarms.ai](https://swarms.ai) | +| 📚 Documentation | Official documentation and guides | [docs.swarms.world](https://docs.swarms.world) | +| 📝 Blog | Latest updates and technical articles | [Medium](https://medium.com/@kyeg) | +| 💬 Discord | Live chat and community support | [Join Discord](https://discord.gg/jM3Z6M9uMq) | +| 🐦 Twitter | Latest news and announcements | [@kyegomez](https://twitter.com/kyegomez) | +| 👥 LinkedIn | Professional network and updates | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | +| 📺 YouTube | Tutorials and demos | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | +| 🎫 Events | Join our community events | [Sign up here](https://lu.ma/5p2jnc2v) | +| 🚀 Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) | -- Clarify documentation roles, responsibilities, and submission expectations. +--- -- Establish quality benchmarks, review procedures, and formatting rules. +## 📊 Statistics -- Introduce the Swarms Documentation Bounty Program to incentivize excellence. +- **Total Projects**: 35+ ---- +- **Industries Covered**: Healthcare, Finance, Research, Business, Development -## 2. Why Documentation Is a Strategic Asset +- **Project Types**: Templates, Applications, Tools, Educational Resources -1. **Accelerates Onboarding**: Reduces friction for new users, enabling faster adoption and integration. -2. **Improves Support Efficiency**: Decreases dependency on live support and helps automate resolution of common queries. -3. **Builds Community Trust**: Transparent documentation invites feedback and fosters a sense of shared ownership. -4. **Enables Scalability**: As Swarms evolves, up-to-date documentation ensures that teams across the globe can keep pace. +- **Active Development**: Continuous updates and new additions -By treating documentation as a core product component, we ensure continuity, scalability, and user satisfaction. --- -## 3. Understanding the Swarms Ecosystem - -The Swarms ecosystem consists of multiple tightly integrated components that serve developers and enterprise clients alike: - -- **Core Documentation Repository**: The main documentation hub for all Swarms technologies [GitHub](https://github.com/kyegomez/swarms). +-------------------------------------------------- -- **Rust SDK (`swarms_rs`)**: Official documentation for the Rust implementation. [Repo](https://github.com/The-Swarm-Corporation/swarms-rs). +# File: governance\bounty_program.md -- **Tools Documentation (`swarms_tools`)**: Guides for CLI and GUI utilities. +# Swarms Bounty Program -- **Hosted API Reference**: Up-to-date REST API documentation: [Swarms API Docs](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/). +The Swarms Bounty Program is an initiative designed to incentivize contributors to help us improve and expand the Swarms framework. With an impressive $150,000 allocated for bounties, contributors have the unique opportunity to earn generous rewards while gaining prestigious recognition in the Swarms community of over 9,000 agent engineers. This program offers more than just financial benefits; it allows contributors to play a pivotal role in advancing the field of multi-agent collaboration and AI automation, while also growing their professional skills and network. By joining the Swarms Bounty Program, you become part of an innovative movement shaping the future of technology. -- **Marketplace & Chat**: Web platforms and communication interfaces [swarms.world](https://swarms.world). +## Why Contribute? -All contributions funnel through the `docs/` directory in the core repo and are structured via MkDocs. +1. **Generous Rewards**: The bounty pool totals $150,000, ensuring that contributors are fairly compensated for their valuable work on successfully completed tasks. Each task comes with its own reward, reflecting its complexity and impact. ---- +2. **Community Status**: Gain coveted recognition as a valued and active contributor within the thriving Swarms community. This status not only highlights your contributions but also builds your reputation among a network of AI engineers. -## 4. Documentation Tools and Platforms +3. **Skill Development**: Collaborate on cutting-edge AI projects, hone your expertise in agent engineering, and learn practical skills that can be applied to real-world challenges in the AI domain. -Swarms documentation is powered by [MkDocs](https://www.mkdocs.org/), an extensible static site generator tailored for project documentation. To contribute, you should be comfortable with: +4. **Networking Opportunities**: Work side-by-side with over 9,000 agent engineers in our active and supportive community. This network fosters collaboration, knowledge sharing, and mentorship opportunities that can significantly boost your career. -- **Markdown**: For formatting structure, code snippets, lists, and links. +## How It Works -- **MkDocs Configuration**: `mkdocs.yml` manages structure, theme, and navigation. +1. **Explore Issues and Tasks**: + - Visit the [Swarms GitHub Issues](https://github.com/kyegomez/swarms/issues) to find a comprehensive list of open tasks requiring attention. These issues range from coding challenges to documentation improvements, offering opportunities for contributors with various skill sets. + - Check the [Swarms Project Board](https://github.com/users/kyegomez/projects/1) for prioritized tasks and ongoing milestones. This board provides a clear view of project priorities and helps contributors align their efforts with the project's immediate goals. -- **Version Control**: GitHub for branching, version tracking, and collaboration. +2. **Claim a Bounty**: + - Identify a task that aligns with your interests and expertise. + - Comment on the issue to indicate your intent to work on it and describe your approach if necessary. + - Await approval from the Swarms team before commencing work. Approval ensures clarity and avoids duplication of efforts by other contributors. -**Recommended Tooling:** +3. **Submit Your Work**: + - Complete the task as per the outlined requirements in the issue description. Pay close attention to details to ensure your submission meets the expectations. + - Submit your pull request (PR) on GitHub with all the required elements, including documentation, test cases, or any relevant files that demonstrate your work. + - Engage with reviewers to refine your submission if requested. -- Markdown linters to enforce syntax consistency. +4. **Earn Rewards**: + - Once your PR is reviewed, accepted, and merged into the main project, you will receive the bounty payment associated with the task. + - Your contributor status in the Swarms community will be updated, showcasing your involvement and accomplishments. -- Spellcheckers to ensure grammatical accuracy. +## Contribution Guidelines +To ensure high-quality contributions and streamline the process, please adhere to the following guidelines: +- Familiarize yourself with the [Swarms Contribution Guidelines](https://github.com/kyegomez/swarms/blob/main/CONTRIBUTING.md). These guidelines outline coding standards, best practices, and procedures for contributing effectively. -- Doc generators for automated API reference extraction. +- Ensure your code is clean, modular, and well-documented. Contributions that adhere to the project's standards are more likely to be accepted. ---- +- Actively communicate with the Swarms team and other contributors. Clear communication helps resolve uncertainties, avoids duplication, and fosters collaboration within the community. -## 5. Getting Started with Contributions +## Get Involved -### 5.1 System Requirements +1. **Join the Community**: + - Become an active member of the Swarms community by joining our Discord server: [Join Now](https://discord.gg/jM3Z6M9uMq). The Discord server serves as a hub for discussions, updates, and support. +2. **Stay Updated**: + - Keep track of the latest updates, announcements, and bounty opportunities by regularly checking the Discord channel and the GitHub repository. -- **Git** v2.30 or higher +3. **Start Contributing**: + - Dive into the Swarms GitHub repository: [Swarms GitHub](https://github.com/kyegomez/swarms). Explore the codebase, familiarize yourself with the project structure, and identify areas where you can make an impact. -- **Node.js** and **npm** for related dependency management +## Additional Benefits -- **MkDocs** and **Material for MkDocs** theme (`pip install mkdocs mkdocs-material`) +Beyond monetary rewards, contributors gain intangible benefits that elevate their professional journey: -- A GitHub account with permissions to fork and submit pull requests +- **Recognition**: Your contributions will be showcased to a community of over 9,000 engineers, increasing your visibility and credibility in the AI field. -### 5.2 Forking the Swarms Repository +- **Portfolio Building**: Add high-impact contributions to your portfolio, demonstrating your skills and experience to potential employers or collaborators. -1. Visit: `https://github.com/kyegomez/swarms` +- **Knowledge Sharing**: Learn from and collaborate with experts in agent engineering, gaining insights into the latest advancements and best practices in the field. -2. Click on **Fork** to create your version of the repository +## Contact Us +For any questions, support, or clarifications, reach out to the Swarms team: -### 5.3 Clone and Configure Locally +- **Discord**: Engage directly with the team and fellow contributors in our active channels. -```bash -git clone https://github.com//swarms.git -cd swarms/docs -git checkout -b feature/docs- -``` +- **GitHub**: Open an issue for specific questions or suggestions related to the project. We’re here to guide and assist you at every step of your contribution journey. --- -## 6. Understanding the Repository Structure - -Explore the documentation directory: - -```text -docs/ -├── index.md -├── mkdocs.yml -├── swarms_rs/ -│ ├── overview.md -│ └── ... -└── swarms_tools/ - ├── install.md - └── ... -``` - -### 6.1 SDK/Tools Directories - -- **Rust SDK (`docs/swarms_rs`)**: Guides, references, and API walkthroughs for the Rust-based implementation. +Join us in building the future of multi-agent collaboration and AI automation. With your contributions, we can create something truly extraordinary and transformative. Together, let’s pave the way for groundbreaking advancements in technology and innovation! -- **Swarms Tools (`docs/swarms_tools`)**: CLI guides, GUI usage instructions, and architecture documentation. -Add new `.md` files in the folder corresponding to your documentation type. +-------------------------------------------------- -### 6.2 Configuring Navigation in MkDocs +# File: governance\main.md -Update `mkdocs.yml` to integrate your new document: +# 🔗 Links & Resources -```yaml -nav: - - Home: index.md - - Swarms Rust: - - Overview: swarms_rs/overview.md - - Your Topic: swarms_rs/your_file.md - - Swarms Tools: - - Installation: swarms_tools/install.md - - Your Guide: swarms_tools/your_file.md -``` +Welcome to the Swarms ecosystem. Click any tile below to explore our products, community, documentation, and social platforms. --- -## 7. Writing and Editing Documentation - -### 7.1 Content Standards - + -- **Accuracy**: Validate all technical content and code snippets. +
-- **Accessibility**: Include alt text for images and use semantic Markdown. +🗣️ Swarms Chat -### 7.2 Markdown Best Practices +🛍️ Swarms Marketplace -- Sequential heading levels (`#`, `##`, `###`) +📚 Swarms API Docs -- Use fenced code blocks with language identifiers +🚀 Swarms Startup Program -- Create readable line spacing and avoid unnecessary line breaks +💻 GitHub: Swarms (Python) +🦀 GitHub: Swarms (Rust) -### 7.3 File Placement Protocol +💬 Join Our Discord -Place `.md` files into the correct subdirectory: +📱 Telegram Group +🐦 Twitter / X -- **Rust SDK Docs**: `docs/swarms_rs/` +✍️ Swarms Blog on Medium -- **Tooling Docs**: `docs/swarms_tools/` +
--- -## 8. Updating Navigation Configuration - -After writing your content: - -1. Open `mkdocs.yml` -2. Identify where your file belongs -3. Add it to the `nav` hierarchy -4. Preview changes: +## 💡 Quick Summary -```bash -mkdocs serve -# Open http://127.0.0.1:8000 to verify output -``` +| Category | Link | +|--------------|----------------------------------------------------------------------| +| API Docs | [docs.swarms.world](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/) | +| GitHub | [kyegomez/swarms](https://github.com/kyegomez/swarms) | +| GitHub (Rust)| [The-Swarm-Corporation/swarms-rs](https://github.com/The-Swarm-Corporation/swarms-rs) | +| Chat UI | [swarms.world/platform/chat](https://swarms.world/platform/chat) | +| Marketplace | [swarms.world](https://swarms.world) | +| Startup App | [Apply Here](https://www.swarms.xyz/programs/startups) | +| Discord | [Join Now](https://discord.gg/jM3Z6M9uMq) | +| Telegram | [Group Chat](https://t.me/swarmsgroupchat) | +| Twitter/X | [@swarms_corp](https://x.com/swarms_corp) | +| Blog | [medium.com/@kyeg](https://medium.com/@kyeg) | --- -## 9. Workflow: Branches, Commits, Pull Requests +> 🐝 Swarms is building the agentic internet. Join the movement and build the future with us. -### 9.1 Branch Naming Guidelines -- Use prefix and description, e.g.: - - `feature/docs-api-pagination` +-------------------------------------------------- - - `fix/docs-typo-tooling` +# File: guides\agent_evals.md -### 9.2 Writing Clear Commits +### Understanding Agent Evaluation Mechanisms -Follow [Conventional Commits](https://www.conventionalcommits.org/): +Agent evaluation mechanisms play a crucial role in ensuring that autonomous agents, particularly in multi-agent systems, perform their tasks effectively and efficiently. This blog delves into the intricacies of agent evaluation, the importance of accuracy tracking, and the methodologies used to measure and visualize agent performance. We'll use Mermaid graphs to provide clear visual representations of these processes. -```bash -docs(swarms_rs): add stream API tutorial -docs(swarms_tools): correct CLI usage example -``` +#### 1. Introduction to Agent Evaluation Mechanisms -### 9.3 Submitting a Pull Request +Agent evaluation mechanisms refer to the processes and criteria used to assess the performance of agents within a system. These mechanisms are essential for: -1. Push your feature branch -2. Open a new PR to the main repository -3. Use a descriptive title and include: - - Summary of changes - - Justification - - Screenshots or previews -4. Tag relevant reviewers and apply labels (`documentation`, `bounty-eligible`) +- **Ensuring Reliability:** Agents must consistently perform their designated tasks correctly. +- **Improving Performance:** Evaluation helps in identifying areas where agents can improve. +- **Maintaining Accountability:** It provides a way to hold agents accountable for their actions. ---- +### 2. Key Components of Agent Evaluation -## 10. Review, QA, and Merging +To effectively evaluate agents, several components and metrics are considered: -Every PR undergoes automated and human review: +#### a. Performance Metrics -- **CI Checks**: Syntax validation, link checking, and formatting +These are quantitative measures used to assess how well an agent is performing. Common performance metrics include: -- **Manual Review**: Maintain clarity, completeness, and relevance +- **Accuracy:** The percentage of correct actions or decisions made by the agent. +- **Precision and Recall:** Precision measures the number of true positive results divided by the number of all positive results, while recall measures the number of true positive results divided by the number of positives that should have been retrieved. +- **F1 Score:** The harmonic mean of precision and recall. +- **Response Time:** How quickly an agent responds to a given task or query. -- **Iteration**: Collaborate through feedback and finalize changes +#### b. Evaluation Criteria -Once approved, maintainers will merge and deploy the updated documentation. +Evaluation criteria define the standards or benchmarks against which agent performance is measured. These criteria are often task-specific and may include: ---- +- **Task Completion Rate:** The percentage of tasks successfully completed by the agent. +- **Error Rate:** The frequency of errors made by the agent during task execution. +- **Resource Utilization:** How efficiently an agent uses resources such as memory and CPU. -## 11. Swarms Documentation Bounty Initiative +### 3. The Process of Agent Evaluation -To foster continuous improvement, we offer structured rewards for eligible contributions: - -### 11.1 Contribution Types +The evaluation process involves several steps, which can be visualized using Mermaid graphs: +#### a. Define Evaluation Metrics -- Creating comprehensive new tutorials and deep dives +The first step is to define the metrics that will be used to evaluate the agent. This involves identifying the key performance indicators (KPIs) relevant to the agent's tasks. -- Updating outdated references and examples +```mermaid +graph TD + A[Define Evaluation Metrics] --> B[Identify KPIs] + B --> C[Accuracy] + B --> D[Precision and Recall] + B --> E[F1 Score] + B --> F[Response Time] +``` -- Fixing typos, grammar, and formatting errors +#### b. Collect Data -- Translating existing content +Data collection involves gathering information on the agent's performance. This data can come from logs, user feedback, or direct observations. -### 11.2 Reward Structure +```mermaid +graph TD + A[Collect Data] --> B[Logs] + A --> C[User Feedback] + A --> D[Direct Observations] +``` -| Tier | Description | Payout (USD) | -|----------|--------------------------------------------------------|------------------| -| Bronze | Typos or minor enhancements (< 100 words) | $1 - $5 | -| Silver | Small tutorials, API examples (100–500 words) | $5 - $20 | -| Gold | Major updates or guides (> 500 words) | $20 - $50 | -| Platinum | Multi-part guides or new documentation verticals | $50 - 300 | +#### c. Analyze Performance -### 11.3 Claiming Bounties +Once data is collected, it is analyzed to assess the agent's performance against the defined metrics. This step may involve statistical analysis, machine learning models, or other analytical techniques. -1. Label your PR `bounty-eligible` -2. Describe expected tier and rationale -3. Review team assesses scope and assigns reward -4. Rewards paid post-merge via preferred method (PayPal, crypto, or wire) +```mermaid +graph TD + A[Analyze Performance] --> B[Statistical Analysis] + A --> C[Machine Learning Models] + A --> D[Other Analytical Techniques] +``` ---- +#### d. Generate Reports -## 12. Best Practices for Efficient Contribution +After analysis, performance reports are generated. These reports provide insights into how well the agent is performing and identify areas for improvement. -- **Stay Updated**: Sync your fork weekly to avoid merge conflicts +```mermaid +graph TD + A[Generate Reports] --> B[Performance Insights] + B --> C[Identify Areas for Improvement] +``` -- **Atomic PRs**: Submit narrowly scoped changes for faster review +### 4. Tracking Agent Accuracy -- **Use Visuals**: Support documentation with screenshots or diagrams +Accuracy tracking is a critical aspect of agent evaluation. It involves measuring how often an agent's actions or decisions are correct. The following steps outline the process of tracking agent accuracy: -- **Cross-Reference**: Link to related documentation for completeness +#### a. Define Correctness Criteria -- **Version Awareness**: Specify SDK/tool versions in code examples +The first step is to define what constitutes a correct action or decision for the agent. ---- +```mermaid +graph TD + A[Define Correctness Criteria] --> B[Task-Specific Standards] + B --> C[Action Accuracy] + B --> D[Decision Accuracy] +``` -## 13. Style Guide Snapshot +#### b. Monitor Agent Actions +Agents' actions are continuously monitored to track their performance. This monitoring can be done in real-time or through periodic evaluations. -- **Voice**: Informative, concise, and respectful +```mermaid +graph TD + A[Monitor Agent Actions] --> B[Real-Time Monitoring] + A --> C[Periodic Evaluations] +``` -- **Terminology**: Use standardized terms (`Swarm`, `Swarms`) consistently +#### c. Compare Against Correctness Criteria -- **Code**: Format snippets using language-specific linters +Each action or decision made by the agent is compared against the defined correctness criteria to determine its accuracy. -- **Accessibility**: Include alt attributes and avoid ambiguous links +```mermaid +graph TD + A[Compare Against Correctness Criteria] --> B[Evaluate Each Action] + B --> C[Correct or Incorrect?] +``` ---- +#### d. Calculate Accuracy Metrics -## 14. Monitoring & Improving Documentation Health +Accuracy metrics are calculated based on the comparison results. These metrics provide a quantitative measure of the agent's accuracy. -We use analytics and community input to prioritize improvements: +```mermaid +graph TD + A[Calculate Accuracy Metrics] --> B[Accuracy Percentage] + A --> C[Error Rate] +``` -- **Traffic Reports**: Track most/least visited pages +### 5. Measuring Agent Accuracy -- **Search Logs**: Detect content gaps from common search terms +Measuring agent accuracy involves several steps and considerations: -- **Feedback Forms**: Collect real-world user input +#### a. Data Labeling -Schedule quarterly audits to refine structure and content across all repositories. +To measure accuracy, the data used for evaluation must be accurately labeled. This involves annotating the data with the correct actions or decisions. ---- +```mermaid +graph TD + A[Data Labeling] --> B[Annotate Data with Correct Actions] + B --> C[Ensure Accuracy of Labels] +``` -## 15. Community Promotion & Engagement +#### b. Establish Baseline Performance -Promote your contributions via: +A baseline performance level is established by evaluating a sample set of data. This baseline serves as a reference point for measuring improvements or declines in accuracy. +```mermaid +graph TD + A[Establish Baseline Performance] --> B[Evaluate Sample Data] + B --> C[Set Performance Benchmarks] +``` -- **Swarms Discord**: https://discord.gg/jM3Z6M9uMq +#### c. Regular Evaluations -- **Swarms Telegram**: https://t.me/swarmsgroupchat +Agents are regularly evaluated to measure their accuracy over time. This helps in tracking performance trends and identifying any deviations from the expected behavior. -- **Swarms Twitter**: https://x.com/swarms_corp +```mermaid +graph TD + A[Regular Evaluations] --> B[Track Performance Over Time] + B --> C[Identify Performance Trends] + B --> D[Detect Deviations] +``` -- **Startup Program Showcases**: https://www.swarms.xyz/programs/startups +#### d. Feedback and Improvement -Active contributors are often spotlighted for leadership roles and community awards. +Feedback from evaluations is used to improve the agent's performance. This may involve retraining the agent, adjusting its algorithms, or refining its decision-making processes. ---- +```mermaid +graph TD + A[Feedback and Improvement] --> B[Use Evaluation Feedback] + B --> C[Retrain Agent] + B --> D[Adjust Algorithms] + B --> E[Refine Decision-Making Processes] +``` -## 16. Resource Index +### 6. Visualizing Agent Evaluation with Mermaid Graphs -- Core GitHub Repo: https://github.com/kyegomez/swarms +Mermaid graphs provide a clear and concise way to visualize the agent evaluation process. Here are some examples of how Mermaid graphs can be used: -- Rust SDK Repo: https://github.com/The-Swarm-Corporation/swarms-rs +#### a. Overall Evaluation Process -- Swarms API Docs: https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/ +```mermaid +graph TD + A[Define Evaluation Metrics] --> B[Collect Data] + B --> C[Analyze Performance] + C --> D[Generate Reports] +``` -- Marketplace: https://swarms.world +#### b. Accuracy Tracking -Join our monthly Documentation Office Hours for real-time mentorship and Q&A. +```mermaid +graph TD + A[Define Correctness Criteria] --> B[Monitor Agent Actions] + B --> C[Compare Against Correctness Criteria] + C --> D[Calculate Accuracy Metrics] +``` ---- +#### c. Continuous Improvement Cycle -## 17. Frequently Asked Questions +```mermaid +graph TD + A[Regular Evaluations] --> B[Track Performance Over Time] + B --> C[Identify Performance Trends] + C --> D[Detect Deviations] + D --> E[Feedback and Improvement] + E --> A +``` -**Q1: Is MkDocs required to contribute?** -A: It's recommended but not required; Markdown knowledge is sufficient to get started. +### 7. Case Study: Evaluating a Chatbot Agent -**Q2: Can I rework existing sections?** -A: Yes, propose changes via issues first, or submit PRs with clear descriptions. +To illustrate the agent evaluation process, let's consider a case study involving a chatbot agent designed to assist customers in an e-commerce platform. -**Q3: When are bounties paid?** -A: Within 30 days of merge, following internal validation. +#### a. Define Evaluation Metrics ---- +For the chatbot, key performance metrics might include: -## 18. Final Thoughts +- **Response Accuracy:** The percentage of correct responses provided by the chatbot. +- **Response Time:** The average time taken by the chatbot to respond to user queries. +- **Customer Satisfaction:** Measured through user feedback and ratings. -The Swarms documentation is a critical piece of our technology stack. As a contributor, your improvements—big or small—directly impact adoption, user retention, and developer satisfaction. This guide aims to equip you with the tools, practices, and incentives to make meaningful contributions. Your work helps us deliver a more usable, scalable, and inclusive platform. +#### b. Collect Data -We look forward to your pull requests, feedback, and ideas. +Data is collected from chatbot interactions, including user queries, responses, and feedback. ---- +#### c. Analyze Performance +Performance analysis involves comparing the chatbot's responses against a predefined set of correct responses and calculating accuracy metrics. --------------------------------------------------- +#### d. Generate Reports -# File: contributors/tools.md +Reports are generated to provide insights into the chatbot's performance, highlighting areas where it excels and areas needing improvement. -# Contributing Tools and Plugins to the Swarms Ecosystem +### 8. Best Practices for Agent Evaluation -## Introduction +Here are some best practices to ensure effective agent evaluation: -The Swarms ecosystem is a modular, intelligent framework built to support the seamless integration, execution, and orchestration of dynamic tools that perform specific functions. These tools form the foundation for how autonomous agents operate, enabling them to retrieve data, communicate with APIs, conduct computational tasks, and respond intelligently to real-world requests. By contributing to Swarms Tools, developers can empower agents with capabilities that drive practical, enterprise-ready applications. +#### a. Use Realistic Scenarios -This guide provides a comprehensive roadmap for contributing tools and plugins to the [Swarms Tools repository](https://github.com/The-Swarm-Corporation/swarms-tools). It is written for software engineers, data scientists, platform architects, and technologists who seek to develop modular, production-grade functionality within the Swarms agent framework. +Evaluate agents in realistic scenarios that closely mimic real-world conditions. This ensures that the evaluation results are relevant and applicable. -Whether your expertise lies in finance, security, machine learning, or developer tooling, this documentation outlines the essential standards, workflows, and integration patterns to make your contributions impactful and interoperable. +#### b. Continuous Monitoring -## Repository Architecture +Continuously monitor agent performance to detect and address issues promptly. This helps in maintaining high performance levels. -The Swarms Tools GitHub repository is meticulously organized to maintain structure, scalability, and domain-specific clarity. Each folder within the repository represents a vertical where tools can be contributed and extended over time. These folders include: +#### c. Incorporate User Feedback -- `finance/`: Market analytics, stock price retrievers, blockchain APIs, etc. +User feedback is invaluable for improving agent performance. Incorporate feedback into the evaluation process to identify and rectify shortcomings. -- `social/`: Sentiment analysis, engagement tracking, and media scraping utilities. +#### d. Regular Updates -- `health/`: Interfaces for EHR systems, wearable device APIs, or health informatics. +Regularly update the evaluation metrics and criteria to keep pace with evolving tasks and requirements. -- `ai/`: Model-serving utilities, embedding services, and prompt engineering functions. +### Conclusion -- `security/`: Encryption libraries, risk scoring tools, penetration test interfaces. +Agent evaluation mechanisms are vital for ensuring the reliability, efficiency, and effectiveness of autonomous agents. By defining clear evaluation metrics, continuously monitoring performance, and using feedback for improvement, we can develop agents that consistently perform at high levels. Visualizing the evaluation process with tools like Mermaid graphs further aids in understanding and communication. Through diligent evaluation and continuous improvement, we can harness the full potential of autonomous agents in various applications. -- `devtools/`: Build tools, deployment utilities, code quality analyzers. +-------------------------------------------------- -- `misc/`: General-purpose helpers or utilities that serve multiple domains. +# File: guides\financial_analysis_swarm_mm.md -Each tool inside these directories is implemented as a single, self-contained function. These functions are expected to adhere to Swarms-wide standards for clarity, typing, documentation, and API key handling. +# Building a Multi-Agent System for Real-Time Financial Analysis: A Comprehensive Tutorial -## Tool Development Specifications +In this tutorial, we'll walk through the process of building a sophisticated multi-agent system for real-time financial analysis using the Swarms framework. This system is designed for financial analysts and developer analysts who want to leverage AI and multiple data sources to gain deeper insights into stock performance, market trends, and economic indicators. -To ensure long-term maintainability and smooth agent-tool integration, each contribution must strictly follow the specifications below. +Before we dive into the code, let's briefly introduce the Swarms framework. Swarms is an innovative open-source project that simplifies the creation and management of AI agents. It's particularly well-suited for complex tasks like financial analysis, where multiple specialized agents can work together to provide comprehensive insights. -### 1. Function Structure and API Usage +For more information and to contribute to the project, visit the [Swarms GitHub repository](https://github.com/kyegomez/swarms). We highly recommend exploring the documentation for a deeper understanding of Swarms' capabilities. -```python -import requests -import os +Additional resources: +- [Swarms Discord](https://discord.gg/jM3Z6M9uMq) for community discussions +- [Swarms Twitter](https://x.com/swarms_corp) for updates +- [Swarms Spotify](https://open.spotify.com/show/2HLiswhmUaMdjHC8AUHcCF?si=c831ef10c5ef4994) for podcasts +- [Swarms Blog](https://medium.com/@kyeg) for in-depth articles +- [Swarms Website](https://swarms.xyz) for an overview of the project -def fetch_data(symbol: str, date_range: str) -> str: - """ - Fetch financial data for a given symbol and date range. +Now, let's break down our financial analysis system step by step. - Args: - symbol (str): Ticker symbol of the asset. - date_range (str): Timeframe for the data (e.g., '1d', '1m', '1y'). +## Step 1: Setting Up the Environment +First install the necessary packages: - Returns: - str: A string containing financial data or an error message. - """ - api_key = os.getenv("FINANCE_API_KEY") - url = f"https://api.financeprovider.com/data?symbol={symbol}&range={date_range}&apikey={api_key}" - response = requests.get(url) - if response.status_code == 200: - return response.text - return "Error fetching data." +```bash +$ pip3 install -U swarms yfiance swarm_models fredapi pandas ``` -All logic must be encapsulated inside a single callable function, written using pure Python. Where feasible, network requests should be stateless, side-effect-free, and gracefully handle errors or timeouts. - -### 2. Type Hints and Input Validation - -All function parameters must be typed using Python's type hinting system. Use built-in primitives where possible (e.g., `str`, `int`, `float`, `bool`) and make use of `Optional` or `Union` types when dealing with nullable parameters or multiple formats. This aids LLMs and type checkers in understanding expected input ranges. - -### 3. Standardized Output Format +First, we need to set up our environment and import the necessary libraries: -Regardless of internal logic or complexity, tools must return outputs in a consistent string format. This string can contain plain text or a serialized JSON object (as a string), but must not return raw objects, dictionaries, or binary blobs. This standardization ensures all downstream agents can interpret tool output predictably. +```python +import os +import time +from datetime import datetime, timedelta +import yfinance as yf +import requests +from fredapi import Fred +import pandas as pd +import numpy as np +import matplotlib.pyplot as plt +from swarms import Agent, AgentRearrange +from swarm_models import OpenAIChat +import logging +from dotenv import load_dotenv +import asyncio +import aiohttp +from ratelimit import limits, sleep_and_retry -### 4. API Key Management Best Practices +# Load environment variables +load_dotenv() -Security and environment isolation are paramount. Never hardcode API keys or sensitive credentials inside source code. Always retrieve them dynamically using the `os.getenv("ENV_VAR")` approach. If a tool requires credentials, clearly document the required environment variable names in the function docstring. +# Set up logging +logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s') +logger = logging.getLogger(__name__) -### 5. Documentation Guidelines +# API keys +POLYGON_API_KEY = os.getenv('POLYGON_API_KEY') +FRED_API_KEY = os.getenv('FRED_API_KEY') +OPENAI_API_KEY = os.getenv('OPENAI_API_KEY') -Every tool must include a detailed docstring that describes: +# Initialize FRED client +fred_client = Fred(api_key=FRED_API_KEY) -- The function's purpose and operational scope +# Polygon API base URL +POLYGON_BASE_URL = "https://api.polygon.io" +``` -- All parameter types and formats +This section sets up our environment, imports necessary libraries, and initializes our API keys and clients. We're using `dotenv` to securely manage our API keys, and we've set up logging to track the execution of our script. -- A clear return type +## Step 2: Implementing Rate Limiting -- Usage examples or sample inputs/outputs +To respect API rate limits, we implement rate limiting decorators: -Example usage: ```python -result = fetch_data("AAPL", "1m") -print(result) -``` +@sleep_and_retry +@limits(calls=5, period=60) # Adjust these values based on your Polygon API tier +async def call_polygon_api(session, endpoint, params=None): + url = f"{POLYGON_BASE_URL}{endpoint}" + params = params or {} + params['apiKey'] = POLYGON_API_KEY + async with session.get(url, params=params) as response: + response.raise_for_status() + return await response.json() -Well-documented code accelerates adoption and improves LLM interpretability. +@sleep_and_retry +@limits(calls=120, period=60) # FRED allows 120 requests per minute +def call_fred_api(func, *args, **kwargs): + return func(*args, **kwargs) +``` -## Contribution Workflow +These decorators ensure that we don't exceed the rate limits for our API calls. The `call_polygon_api` function is designed to work with asynchronous code, while `call_fred_api` is a wrapper for synchronous FRED API calls. -To submit a tool, follow the workflow below. This ensures your code integrates cleanly and is easy for maintainers to review. +## Step 3: Implementing Data Fetching Functions -### Step 1: Fork the Repository -Navigate to the [Swarms Tools repository](https://github.com/The-Swarm-Corporation/swarms-tools) and fork it to your personal or organization’s GitHub account. +Next, we implement functions to fetch data from various sources: -### Step 2: Clone Your Fork -```bash -git clone https://github.com/YOUR_USERNAME/swarms-tools.git -cd swarms-tools -``` +### Yahoo Finance Integration -### Step 3: Create a Feature Branch +```python +async def get_yahoo_finance_data(session, ticker, period="1d", interval="1m"): + try: + stock = yf.Ticker(ticker) + hist = await asyncio.to_thread(stock.history, period=period, interval=interval) + info = await asyncio.to_thread(lambda: stock.info) + return hist, info + except Exception as e: + logger.error(f"Error fetching Yahoo Finance data for {ticker}: {e}") + return None, None -```bash -git checkout -b feature/add-tool- +async def get_yahoo_finance_realtime(session, ticker): + try: + stock = yf.Ticker(ticker) + return await asyncio.to_thread(lambda: stock.fast_info) + except Exception as e: + logger.error(f"Error fetching Yahoo Finance realtime data for {ticker}: {e}") + return None ``` -Use descriptive branch names. This is especially helpful when collaborating in teams or maintaining audit trails. - -### Step 4: Build Your Tool -Navigate into the appropriate category folder (e.g., `finance/`, `ai/`, etc.) and implement your tool according to the defined schema. - -If your tool belongs in a new category, you may create a new folder with a clear, lowercase name. +These functions fetch historical and real-time data from Yahoo Finance. We use `asyncio.to_thread` to run the synchronous `yfinance` functions in a separate thread, allowing our main event loop to continue running. -### Step 5: Run Local Tests (if applicable) -Ensure the function executes correctly and does not throw runtime errors. If feasible, test edge cases and verify consistent behavior across platforms. +### Polygon.io Integration -### Step 6: Commit Your Changes +```python +async def get_polygon_realtime_data(session, ticker): + try: + trades = await call_polygon_api(session, f"/v2/last/trade/{ticker}") + quotes = await call_polygon_api(session, f"/v2/last/nbbo/{ticker}") + return trades, quotes + except Exception as e: + logger.error(f"Error fetching Polygon.io realtime data for {ticker}: {e}") + return None, None -```bash -git add . -git commit -m "Add under : API-based tool for X" +async def get_polygon_news(session, ticker, limit=10): + try: + news = await call_polygon_api(session, f"/v2/reference/news", params={"ticker": ticker, "limit": limit}) + return news.get('results', []) + except Exception as e: + logger.error(f"Error fetching Polygon.io news for {ticker}: {e}") + return [] ``` -### Step 7: Push to GitHub - -```bash -git push origin feature/add-tool- -``` +These functions fetch real-time trade and quote data, as well as news articles from Polygon.io. We use our `call_polygon_api` function to make these requests, ensuring we respect rate limits. -### Step 8: Submit a Pull Request +### FRED Integration -On GitHub, open a pull request from your fork to the main Swarms Tools repository. Your PR description should: -- Summarize the tool’s functionality -- Reference any related issues or enhancements -- Include usage notes or setup instructions (e.g., required API keys) +```python +async def get_fred_data(session, series_id, start_date, end_date): + try: + data = await asyncio.to_thread(call_fred_api, fred_client.get_series, series_id, start_date, end_date) + return data + except Exception as e: + logger.error(f"Error fetching FRED data for {series_id}: {e}") + return None ---- +async def get_fred_realtime(session, series_ids): + try: + data = {} + for series_id in series_ids: + series = await asyncio.to_thread(call_fred_api, fred_client.get_series, series_id) + data[series_id] = series.iloc[-1] # Get the most recent value + return data + except Exception as e: + logger.error(f"Error fetching FRED realtime data: {e}") + return {} +``` -## Integration with Swarms Agents +These functions fetch historical and real-time economic data from FRED. Again, we use `asyncio.to_thread` to run the synchronous FRED API calls in a separate thread. -Once your tool has been merged into the official repository, it can be utilized by Swarms agents as part of their available capabilities. +## Step 4: Creating Specialized Agents -The example below illustrates how to embed a newly added tool into an autonomous agent: +Now we create our specialized agents using the Swarms framework: ```python -from swarms import Agent -from finance.stock_price import get_stock_price +stock_agent = Agent( + agent_name="StockAgent", + system_prompt="""You are an expert stock analyst. Your task is to analyze real-time stock data and provide insights. + Consider price movements, trading volume, and any available company information. + Provide a concise summary of the stock's current status and any notable trends or events.""", + llm=OpenAIChat(api_key=OPENAI_API_KEY), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, +) -agent = Agent( - agent_name="Devin", - system_prompt=( - "Autonomous agent that can interact with humans and other agents." - " Be helpful and kind. Use the tools provided to assist the user." - " Return all code in markdown format." - ), - llm=llm, - max_loops="auto", - autosave=True, +market_agent = Agent( + agent_name="MarketAgent", + system_prompt="""You are a market analysis expert. Your task is to analyze overall market conditions using real-time data. + Consider major indices, sector performance, and market-wide trends. + Provide a concise summary of current market conditions and any significant developments.""", + llm=OpenAIChat(api_key=OPENAI_API_KEY), + max_loops=1, dashboard=False, streaming_on=True, verbose=True, - stopping_token="", - interactive=True, - tools=[get_stock_price, terminal, browser, file_editor, create_file], - metadata_output_type="json", - function_calling_format_type="OpenAI", - function_calling_type="json", ) -agent.run("Create a new file for a plan to take over the world.") +macro_agent = Agent( + agent_name="MacroAgent", + system_prompt="""You are a macroeconomic analysis expert. Your task is to analyze key economic indicators and provide insights on the overall economic situation. + Consider GDP growth, inflation rates, unemployment figures, and other relevant economic data. + Provide a concise summary of the current economic situation and any potential impacts on financial markets.""", + llm=OpenAIChat(api_key=OPENAI_API_KEY), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, +) + +news_agent = Agent( + agent_name="NewsAgent", + system_prompt="""You are a financial news analyst. Your task is to analyze recent news articles related to specific stocks or the overall market. + Consider the potential impact of news events on stock prices or market trends. + Provide a concise summary of key news items and their potential market implications.""", + llm=OpenAIChat(api_key=OPENAI_API_KEY), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, +) ``` -By registering tools in the `tools` parameter during agent creation, you enable dynamic function calling. The agent interprets natural language input, selects the appropriate tool, and invokes it with valid arguments. +Each agent is specialized in a different aspect of financial analysis. The `system_prompt` for each agent defines its role and the type of analysis it should perform. -This agent-tool paradigm enables highly flexible and responsive behavior across workflows involving research, automation, financial analysis, social listening, and more. +## Step 5: Building the Multi-Agent System ---- +We then combine our specialized agents into a multi-agent system: -## Tool Maintenance and Long-Term Ownership +```python +agents = [stock_agent, market_agent, macro_agent, news_agent] +flow = "StockAgent -> MarketAgent -> MacroAgent -> NewsAgent" -Contributors are expected to uphold the quality of their tools post-merge. This includes: +agent_system = AgentRearrange(agents=agents, flow=flow) +``` -- Monitoring for issues or bugs reported by the community +The `flow` variable defines the order in which our agents will process information. This allows for a logical progression from specific stock analysis to broader market and economic analysis. -- Updating tools when APIs deprecate or modify their behavior +## Step 6: Implementing Real-Time Analysis -- Improving efficiency, error handling, or documentation over time +Now we implement our main analysis function: -If a tool becomes outdated or unsupported, maintainers may archive or revise it to maintain ecosystem integrity. +```python +async def real_time_analysis(session, ticker): + logger.info(f"Starting real-time analysis for {ticker}") + + # Fetch real-time data + yf_data, yf_info = await get_yahoo_finance_data(session, ticker) + yf_realtime = await get_yahoo_finance_realtime(session, ticker) + polygon_trades, polygon_quotes = await get_polygon_realtime_data(session, ticker) + polygon_news = await get_polygon_news(session, ticker) + fred_data = await get_fred_realtime(session, ['GDP', 'UNRATE', 'CPIAUCSL']) -Contributors whose tools receive wide usage or demonstrate excellence in design may be offered elevated privileges or invited to maintain broader tool categories. + # Prepare input for the multi-agent system + input_data = f""" + Yahoo Finance Data: + {yf_realtime} ---- + Recent Stock History: + {yf_data.tail().to_string() if yf_data is not None else 'Data unavailable'} -## Best Practices for Enterprise-Grade Contributions + Polygon.io Trade Data: + {polygon_trades} -To ensure your tool is production-ready and enterprise-compliant, observe the following practices: + Polygon.io Quote Data: + {polygon_quotes} + Recent News: + {polygon_news[:3] if polygon_news else 'No recent news available'} -- Run static type checking with `mypy` + Economic Indicators: + {fred_data} -- Use formatters like `black` and linters such as `flake8` + Analyze this real-time financial data for {ticker}. Provide insights on the stock's performance, overall market conditions, relevant economic factors, and any significant news that might impact the stock or market. + """ -- Avoid unnecessary external dependencies + # Run the multi-agent analysis + try: + analysis = agent_system.run(input_data) + logger.info(f"Analysis completed for {ticker}") + return analysis + except Exception as e: + logger.error(f"Error during multi-agent analysis for {ticker}: {e}") + return f"Error during analysis: {e}" +``` -- Keep functions modular and readable +This function fetches data from all our sources, prepares it as input for our multi-agent system, and then runs the analysis. The result is a comprehensive analysis of the stock, considering individual performance, market conditions, economic factors, and relevant news. -- Prefer named parameters over positional arguments for clarity +## Step 7: Implementing Advanced Use Cases -- Handle API errors gracefully and return user-friendly messages +We then implement more advanced analysis functions: -- Document limitations or assumptions in the docstring +### Compare Stocks -Optional but encouraged: -- Add unit tests to validate function output +```python +async def compare_stocks(session, tickers): + results = {} + for ticker in tickers: + results[ticker] = await real_time_analysis(session, ticker) + + comparison_prompt = f""" + Compare the following stocks based on the provided analyses: + {results} -- Benchmark performance if your tool operates on large datasets + Highlight key differences and similarities. Provide a ranking of these stocks based on their current performance and future prospects. + """ + + try: + comparison = agent_system.run(comparison_prompt) + logger.info(f"Stock comparison completed for {tickers}") + return comparison + except Exception as e: + logger.error(f"Error during stock comparison: {e}") + return f"Error during comparison: {e}" +``` ---- +This function compares multiple stocks by running a real-time analysis on each and then prompting our multi-agent system to compare the results. -## Conclusion +### Sector Analysis -The Swarms ecosystem is built on the principle of extensibility through community-driven contributions. By submitting modular, typed, and well-documented tools to the Swarms Tools repository, you directly enhance the problem-solving power of intelligent agents. +```python +async def sector_analysis(session, sector): + sector_stocks = { + 'Technology': ['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'NVDA'], + 'Finance': ['JPM', 'BAC', 'WFC', 'C', 'GS'], + 'Healthcare': ['JNJ', 'UNH', 'PFE', 'ABT', 'MRK'], + 'Consumer Goods': ['PG', 'KO', 'PEP', 'COST', 'WMT'], + 'Energy': ['XOM', 'CVX', 'COP', 'SLB', 'EOG'] + } + + if sector not in sector_stocks: + return f"Sector '{sector}' not found. Available sectors: {', '.join(sector_stocks.keys())}" + + stocks = sector_stocks[sector][:5] + + sector_data = {} + for stock in stocks: + sector_data[stock] = await real_time_analysis(session, stock) + + sector_prompt = f""" + Analyze the {sector} sector based on the following data from its top stocks: + {sector_data} -This documentation serves as your blueprint for contributing high-quality, reusable functionality. From idea to implementation to integration, your efforts help shape the future of collaborative, agent-powered software. + Provide insights on: + 1. Overall sector performance + 2. Key trends within the sector + 3. Top performing stocks and why they're outperforming + 4. Any challenges or opportunities facing the sector + """ + + try: + analysis = agent_system.run(sector_prompt) + logger.info(f"Sector analysis completed for {sector}") + return analysis + except Exception as e: + logger.error(f"Error during sector analysis for {sector}: {e}") + return f"Error during sector analysis: {e}" +``` -We encourage all developers, data scientists, and domain experts to contribute meaningfully. Review existing tools for inspiration, or create something entirely novel. +This function analyzes an entire sector by running real-time analysis on its top stocks and then prompting our multi-agent system to provide sector-wide insights. -To begin, fork the [Swarms Tools repository](https://github.com/The-Swarm-Corporation/swarms-tools) and start building impactful, reusable tools that can scale across agents and use cases. +### Economic Impact Analysis +```python +async def economic_impact_analysis(session, indicator, threshold): + # Fetch historical data for the indicator + end_date = datetime.now().strftime('%Y-%m-%d') + start_date = (datetime.now() - timedelta(days=365)).strftime('%Y-%m-%d') + indicator_data = await get_fred_data(session, indicator, start_date, end_date) + + if indicator_data is None or len(indicator_data) < 2: + return f"Insufficient data for indicator {indicator}" + + # Check if the latest value crosses the threshold + latest_value = indicator_data.iloc[-1] + previous_value = indicator_data.iloc[-2] + crossed_threshold = (latest_value > threshold and previous_value <= threshold) or (latest_value < threshold and previous_value >= threshold) + + if crossed_threshold: + impact_prompt = f""" + The economic indicator {indicator} has crossed the threshold of {threshold}. Its current value is {latest_value}. + Historical data: + {indicator_data.tail().to_string()} --------------------------------------------------- + Analyze the potential impacts of this change on: + 1. Overall economic conditions + 2. Different market + 2. Different market sectors + 3. Specific types of stocks (e.g., growth vs. value) + 4. Other economic indicators -# File: corporate/2024_2025_goals.md + Provide a comprehensive analysis of the potential consequences and any recommended actions for investors. + """ + + try: + analysis = agent_system.run(impact_prompt) + logger.info(f"Economic impact analysis completed for {indicator}") + return analysis + except Exception as e: + logger.error(f"Error during economic impact analysis for {indicator}: {e}") + return f"Error during economic impact analysis: {e}" + else: + return f"The {indicator} indicator has not crossed the threshold of {threshold}. Current value: {latest_value}" +``` -# **Swarms Goals & Milestone Tracking: A Vision for 2024 and Beyond** +This function analyzes the potential impact of significant changes in economic indicators. It fetches historical data, checks if a threshold has been crossed, and if so, prompts our multi-agent system to provide a comprehensive analysis of the potential consequences. -As we propel Swarms into a new frontier, we’ve set ambitious yet achievable goals for the coming years that will solidify Swarms as a leader in multi-agent -orchestration. This document outlines our vision, the goals for 2024 and 2025, and how we track our progress through meticulously designed milestones and metrics. +## Step 8: Running the Analysis -## **Our Vision: The Agentic Ecosystem** +Finally, we implement our main function to run all of our analyses: -We envision an ecosystem where agents are pervasive and serve as integral collaborators in business processes, daily life, and complex problem-solving. By leveraging -the collective intelligence of swarms, we believe we can achieve massive gains in productivity, scalability, and impact. Our target is to establish the Swarms platform as the go-to environment for deploying and managing agents at an unprecedented scale—making agents as common and indispensable as mobile apps are today. This future -will see agents integrated into nearly every digital interaction, creating a seamless extension of human capability and reducing the cognitive load on individuals and organizations. +```python +async def main(): + async with aiohttp.ClientSession() as session: + # Example usage + analysis_result = await real_time_analysis(session, 'AAPL') + print("Single Stock Analysis:") + print(analysis_result) -We believe that *agents* will transition from being simple tools to becoming full-fledged partners that can understand user needs, predict outcomes, and adapt to -changes dynamically. Our vision is not just about increasing numbers; it’s about building a smarter, more interconnected agentic ecosystem where every agent has a purpose and contributes to a collective intelligence that continuously evolves. By cultivating a diverse array of agents capable of handling various specialized tasks, we aim to create an environment in which these digital collaborators function as a cohesive whole—one that can amplify human ingenuity and productivity beyond current limits. + comparison_result = await compare_stocks(session, ['AAPL', 'GOOGL', 'MSFT']) + print("\nStock Comparison:") + print(comparison_result) -## **Goals for 2024 and 2025** + tech_sector_analysis = await sector_analysis(session, 'Technology') + print("\nTechnology Sector Analysis:") + print(tech_sector_analysis) -To achieve our vision, we have laid out a structured growth trajectory for Swarms, driven by clear numerical targets: + gdp_impact = await economic_impact_analysis(session, 'GDP', 22000) + print("\nEconomic Impact Analysis:") + print(gdp_impact) -1. **End of 2024: 500 Million Agents** - Currently, our platform hosts **45 million agents**. By the end of 2024, our goal is to reach **500 million agents** deployed on Swarms. This means achieving sustained exponential growth, which will require doubling or even tripling the total number of agents roughly **every month** from now until December 2024. Such growth will necessitate not only scaling infrastructure but also improving the ease with which users can develop and deploy agents, expanding educational resources, and fostering a vibrant community that drives innovation in agent design. To achieve this milestone, we plan to invest heavily in making our platform user-friendly, including simplifying onboarding processes and providing extensive educational content. Additionally, we aim to build out our infrastructure to support the necessary scalability and ensure the seamless operation of a growing number of agents. Beyond merely scaling in numbers, we are also focused on increasing the diversity of tasks that agents can perform, thereby enhancing the practical value of deploying agents on Swarms. +if __name__ == "__main__": + asyncio.run(main()) +``` -2. **End of 2025: 10 Billion+ Agents** - The long-term vision extends further to reach **10 billion agents** by the end of 2025. This ambitious goal reflects not only the organic growth of our user base but - also the increasing role of swarms in business applications, personal projects, and global problem-solving initiatives. This goal requires continuous monthly - doubling of agents and a clear roadmap of user engagement and deployment. By scaling to this level, we envision Swarms as a cornerstone of automation and productivity enhancement, where agents autonomously manage everything from mundane tasks to sophisticated strategic decisions, effectively enhancing human capabilities. This expansion will rely on the development of a robust ecosystem in which users can easily create, share, and enhance agents. We will foster partnerships with industries that can benefit from scalable agentic solutions—spanning healthcare, finance, education, and beyond. Our strategy includes developing domain-specific templates and specialized agents that cater to niche needs, thereby making Swarms an indispensable solution for businesses and individuals alike. +This `main` function demonstrates how to use all of our analysis functions. It runs a single stock analysis, compares multiple stocks, performs a sector analysis, and conducts an economic impact analysis. -## **Tracking Progress: The Power of Metrics** +## Conclusion and Next Steps -Achieving these goals is not just about reaching numerical targets but ensuring that our users are deriving tangible value from Swarms and deploying agents effectively. To measure success, we’ve defined several key performance indicators (KPIs) and milestones: +This tutorial has walked you through the process of building a sophisticated multi-agent system for real-time financial analysis using the Swarms framework. Here's a summary of what we've accomplished: -### 1. Growth in Agent Deployment +1. Set up our environment and API connections +2. Implemented rate limiting to respect API constraints +3. Created functions to fetch data from multiple sources (Yahoo Finance, Polygon.io, FRED) +4. Designed specialized AI agents for different aspects of financial analysis +5. Combined these agents into a multi-agent system +6. Implemented advanced analysis functions including stock comparison, sector analysis, and economic impact analysis -The **number of agents** deployed per month will be our primary growth metric. With our goal of **doubling agent count every month**, this metric serves as an overall health indicator for platform adoption and usage. Growth in deployment indicates that our platform is attracting users who see value in creating and deploying agents to solve diverse challenges. +This system provides a powerful foundation for financial analysis, but there's always room for expansion and improvement. Here are some potential next steps: -**Key Milestones:** +1. **Expand data sources**: Consider integrating additional financial data providers for even more comprehensive analysis. -- **November 2024**: Surpass 250 million agents. +2. **Enhance agent specialization**: You could create more specialized agents, such as a technical analysis agent or a sentiment analysis agent for social media data. -- **December 2024**: Reach 500 million agents. +3. **Implement a user interface**: Consider building a web interface or dashboard to make the system more user-friendly for non-technical analysts. -- **June 2025**: Break the 5 billion agents mark. +4. **Add visualization capabilities**: Integrate data visualization tools to help interpret complex financial data more easily. -- **December 2025**: Hit 10 billion agents. +5. **Implement a backtesting system**: Develop a system to evaluate your multi-agent system's performance on historical data. +6. **Explore advanced AI models**: The Swarms framework supports various AI models. Experiment with different models to see which performs best for your specific use case. -To accomplish this, we must continually expand our infrastructure, maintain scalability, and create a seamless user onboarding process. We’ll ensure that adding agents is frictionless and that our platform can accommodate this rapid growth. By integrating advanced orchestration capabilities, we will enable agents to form more complex collaborations and achieve tasks that previously seemed out of reach. Furthermore, we will develop analytics tools to track the success and efficiency of these agents, giving users real-time feedback to optimize their deployment strategies. +7. **Implement real-time monitoring**: Set up a system to continuously monitor markets and alert you to significant changes or opportunities. +Remember, the Swarms framework is a powerful and flexible tool that can be adapted to a wide range of complex tasks beyond just financial analysis. We encourage you to explore the [Swarms GitHub repository](https://github.com/kyegomez/swarms) for more examples and inspiration. -### 2. Agents Deployed Per User: Engagement Indicator +For more in-depth discussions and community support, consider joining the [Swarms Discord](https://discord.gg/jM3Z6M9uMq). You can also stay updated with the latest developments by following [Swarms on Twitter](https://x.com/swarms_corp). -A core belief of Swarms is that agents are here to make life easier for their users—whether it’s automating mundane tasks, handling complex workflows, or enhancing creative endeavors. Therefore, we measure the **number of agents deployed per user per month** as a key metric for engagement. Tracking this metric allows us to understand how effectively our users are utilizing the platform, and how deeply agents are becoming embedded into their workflows. +If you're interested in learning more about AI and its applications in various fields, check out the [Swarms Spotify podcast](https://open.spotify.com/show/2HLiswhmUaMdjHC8AUHcCF?si=c831ef10c5ef4994) and the [Swarms Blog](https://medium.com/@kyeg) for insightful articles and discussions. -This metric ensures that users aren’t just joining Swarms, but they are actively building and deploying agents to solve real problems. Our milestone for engagement is to see **increasing growth in agents deployed per user** month over month, which indicates a deeper integration of Swarms into daily workflows and business processes. We want our users to view Swarms as their go-to solution for any problem they face, which means ensuring that agents are providing real, tangible benefits. +Lastly, don't forget to visit the [Swarms Website](https://swarms.xyz) for a comprehensive overview of the project and its capabilities. +By leveraging the power of multi-agent AI systems, you're well-equipped to navigate the complex world of financial markets. Happy analyzing! -**Key Milestones:** -- **November 2024**: Achieve an average of 20 agents deployed per user each month. -- **June 2025**: Target 100-200+ agents deployed per user. +## Swarm Resources: -To drive these numbers, we plan to improve user support, enhance educational materials, host workshops, and create an environment that empowers users to deploy agents for increasingly complex use-cases. Additionally, we will introduce templates and pre-built agents that users can customize, reducing the barriers to entry and enabling -rapid deployment for new users. We are also developing gamified elements that reward users for deploying more agents and achieving milestones, fostering a competitive and engaging community atmosphere. +* [Swarms Github](https://github.com/kyegomez/swarms) +* [Swarms Discord](https://discord.gg/jM3Z6M9uMq) +* [Swarms Twitter](https://x.com/swarms_corp) +* [Swarms Spotify](https://open.spotify.com/show/2HLiswhmUaMdjHC8AUHcCF?si=c831ef10c5ef4994) +* [Swarms Blog](https://medium.com/@kyeg) +* [Swarms Website](https://swarms.xyz) -### 3. Active vs. Inactive Agents: Measuring Churn +-------------------------------------------------- -The **number of inactive agents per user** is an essential metric for understanding our **churn rate**. An agent is considered inactive when it remains undeployed or unused for a prolonged period, indicating that it’s no longer delivering value to the user. Churn metrics provide valuable insights into the effectiveness of our agents and highlight areas where improvements are needed. +# File: guides\financial_data_api.md -We aim to **minimize the number of inactive agents**, as this will be a direct reflection of how well our agents are designed, integrated, and supported. A low churn rate means that users are finding long-term utility in their agents, which is key to our mission. Our platform’s success depends on users consistently deploying agents -that remain active and valuable over time. +# Analyzing Financial Data with AI Agents using Swarms Framework -**Key Milestones:** +In the rapidly evolving landscape of quantitative finance, the integration of artificial intelligence with financial data analysis has become increasingly crucial. This blog post will explore how to leverage the power of AI agents, specifically using the Swarms framework, to analyze financial data from various top-tier data providers. We'll demonstrate how to connect these agents with different financial APIs, enabling sophisticated analysis and decision-making processes. -- **December 2024**: Ensure that no more than **30%** of deployed agents are inactive. +## Table of Contents -- **December 2025**: Aim for **10%** or lower, reflecting strong agent usefulness and consistent platform value delivery. +1. [Introduction to Swarms Framework](#introduction-to-swarms-framework) +2. [Setting Up the Environment](#setting-up-the-environment) +3. [Connecting AI Agents with Financial Data Providers](#connecting-ai-agents-with-financial-data-providers) + - [Polygon.io](#polygonio) + - [Alpha Vantage](#alpha-vantage) + - [Yahoo Finance](#yahoo-finance) + - [IEX Cloud](#iex-cloud) + - [Finnhub](#finnhub) +4. [Advanced Analysis Techniques](#advanced-analysis-techniques) +5. [Best Practices and Considerations](#best-practices-and-considerations) +6. [Conclusion](#conclusion) +## Introduction to Swarms Framework -Reducing churn will require proactive measures, such as automated notifications to users about inactive agents, recommending potential uses, and implementing agent retraining features to enhance their adaptability over time. Educating users on prompting engineering, tool engineering, and RAG engineering also helps decrease these numbers as the number of inactive agents is evident that the user is not automating a business operation with that agent. We will also integrate machine learning models to predict agent inactivity and take corrective actions before agents become dormant. By offering personalized recommendations to users on how to enhance or repurpose inactive agents, we hope to ensure that all deployed agents are actively contributing value. +The Swarms framework is a powerful tool for building and deploying AI agents that can interact with various data sources and perform complex analyses. In the context of financial data analysis, Swarms can be used to create intelligent agents that can process large volumes of financial data, identify patterns, and make data-driven decisions. Explore our github for examples, applications, and more. -## **Milestones and Success Criteria** +## Setting Up the Environment -To reach these ambitious goals, we have broken our roadmap down into a series of actionable milestones: +Before we dive into connecting AI agents with financial data providers, let's set up our environment: -1. **Infrastructure Scalability (Q1 2025)** - We will work on ensuring that our backend infrastructure can handle the scale required to reach 500 million agents by the end of 2024. This includes expanding server capacity, improving agent orchestration capabilities, and ensuring low latency across deployments. We will also focus on enhancing our database management systems to ensure efficient storage and retrieval of agent data, enabling seamless operation at a massive scale. Our infrastructure roadmap also includes implementing advanced load balancing techniques and predictive scaling mechanisms to ensure high availability and reliability. +1. Install the Swarms framework: -2. **Improved User Experience (Q2 2025)** - To encourage agent deployment and reduce churn, we will introduce new onboarding flows, agent-building wizards, and intuitive user interfaces. We will also implement - in-depth tutorials and documentation to simplify agent creation for new users. By making agent-building accessible even to those without programming expertise, we - will open the doors to a broader audience and drive exponential growth in the number of agents deployed. Additionally, we will integrate AI-driven suggestions and - contextual help to assist users at every step of the process, making the platform as intuitive as possible. +```bash +pip install -U swarms +``` -3. **Agent Marketplace (Q3 2025)** - Launching the **Swarms Marketplace** for agents, prompts, and tools will allow users to share, discover, and even monetize their agents. This marketplace will be a crucial driver in both increasing the number of agents deployed and reducing inactive agents, as it will create an ecosystem of continuously evolving and highly useful agents. Users will have the opportunity to browse agents that others have developed, which can serve as inspiration or as a starting point for their own projects. We will also introduce ratings, reviews, and community feedback mechanisms to ensure that the most effective agents are highlighted and accessible. +2. Install additional required libraries: -4. **Community Engagement and Swarms Education (Ongoing)** - Workshops, webinars, and events will be conducted throughout 2024 and 2025 to engage new users and educate them on building effective agents. The goal is to ensure that every user becomes proficient in deploying swarms of agents for meaningful tasks. We will foster an active community where users can exchange ideas, get help, and collaborate on projects, ultimately driving forward the growth of the Swarms ecosystem. We also plan to establish a mentor program where experienced users can guide newcomers, helping them get up to speed more quickly and successfully deploy agents. +```bash +pip install requests pandas numpy matplotlib +``` -## **Actionable Strategies for Goal Achievement** +3. Set up your API keys for the various financial data providers. It's recommended to use environment variables or a secure configuration file to store these keys. -**1. Developer Incentives** -One of our most important strategies will be the introduction of developer incentives. By providing rewards for creating agents, we foster an environment of creativity and encourage rapid growth in the number of useful agents on the platform. We will host hackathons, contests, and provide financial incentives to developers whose agents provide substantial value to the community. Additionally, we plan to create a tiered rewards system that acknowledges developers for the number of active deployments and the utility of their agents, motivating continuous improvement and innovation. +## Connecting AI Agents with Financial Data Providers -**2. Strategic Partnerships** -We plan to form partnerships with major technology providers and industry players to scale Swarms adoption. Integrating Swarms into existing business software and industrial processes will drive significant growth in agent numbers and usage. These partnerships will allow Swarms to become embedded into existing workflows, making it easier for users to understand the value and immediately apply agents to solve real-world challenges. We are also targeting partnerships with educational -institutions to provide Swarms as a learning platform for AI, encouraging students and researchers to contribute to our growing ecosystem. +Now, let's explore how to connect AI agents using the Swarms framework with different financial data providers. -**3. User Feedback Loop** -To ensure we are on track, a continuous feedback loop with our user community will help us understand what agents are effective, which require improvements, and where we need to invest our resources to maximize engagement. Users’ experiences will shape our platform evolution. We will implement regular surveys, feedback forms, and user interviews to gather insights, and use this data to drive iterative development that is directly aligned with user needs. In addition, we will create an open feature request forum where users can vote on the most important features they want to see, ensuring that we are prioritizing our community’s needs. +### Polygon.io -**4. Marketing and Awareness Campaigns** -Strategic campaigns to showcase the power of swarms in specific industries will highlight the versatility and impact of our agents. We plan to create case studies demonstrating how swarms solve complex problems in marketing, finance, customer service, and other verticals, and use these to attract a wider audience. Our content marketing strategy will include blogs, video tutorials, and success stories to help potential users visualize the transformative power of Swarms. We will also leverage social media campaigns and influencer partnerships to reach a broader audience and generate buzz around Swarms’ capabilities. +First, we'll create an AI agent that can fetch and analyze stock data from Polygon.io. -**5. Educational Initiatives** -To lower the barrier to entry for new users, we will invest heavily in educational content. This includes video tutorials, comprehensive guides, and in-platform -learning modules. By making the learning process easy and engaging, we ensure that users quickly become proficient in creating and deploying agents, thereby increasing user satisfaction and reducing churn. A well-educated user base will lead to more agents being deployed effectively, contributing to our overall growth targets. We are -also developing certification programs for users and developers, providing a structured pathway to become proficient in Swarms technology and gain recognition for their skills. +```python +import os +from swarms import Agent +from swarms.models import OpenAIChat +from dotenv import load_dotenv +import requests +import pandas as pd -## **The Path Ahead: Building Towards 10 Billion Agents** +load_dotenv() -To achieve our vision of **10 billion agents** by the end of 2025, it’s critical that we maintain an aggressive growth strategy while ensuring that agents are providing real value to users. This requires a deep focus on **scalability, community growth, and user-centric development**. It also demands a continuous feedback loop where -insights from agent deployments and user interactions drive platform evolution. By creating an environment where agents are easy to develop, share, and integrate, we will achieve sustainable growth that benefits not just Swarms, but the broader AI community. +# Polygon.io API setup +POLYGON_API_KEY = os.getenv("POLYGON_API_KEY") +POLYGON_BASE_URL = "https://api.polygon.io/v2" -We envision swarms as a catalyst for *democratizing access to AI*. By enabling users across industries—from healthcare to education to manufacturing—to deploy agents that handle specialized tasks, we empower individuals and organizations to focus on creative, strategic endeavors rather than repetitive operational tasks. The journey to 10 billion agents is not just about scale; it’s about creating *meaningful and effective automation* that transforms how work gets done. We believe that Swarms will ultimately reshape industries by making sophisticated automation accessible to all, driving a shift toward higher productivity and innovation. +# OpenAI API setup +OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") -## **Community and Culture** +# Create an instance of the OpenAIChat class +model = OpenAIChat( + openai_api_key=OPENAI_API_KEY, + model_name="gpt-4", + temperature=0.1 +) -Swarms will also be emphasizing the **community aspect**, building a **culture of collaboration** among users, developers, and businesses. By fostering open communication and enabling the sharing of agents, we encourage **knowledge transfer** and **network effects**, which help drive overall growth. Our goal is to create an environment where agents not only work individually but evolve as a collective intelligence network—working towards a **post-scarcity civilization** where every problem -can be tackled by the right combination of swarms. +# Initialize the agent +agent = Agent( + agent_name="Financial-Analysis-Agent", + system_prompt="You are a financial analysis AI assistant. Your task is to analyze stock data and provide insights.", + llm=model, + max_loops=1, + dashboard=False, + verbose=True +) -We see the community as the heartbeat of Swarms, driving innovation, providing support, and expanding the use-cases for agents. Whether it’s through forums, community -events, or user-generated content, we want Swarms to be the hub where people come together to solve the most pressing challenges of our time. By empowering our users -and encouraging collaboration, we can ensure that the platform continuously evolves and adapts to new needs and opportunities. Additionally, we plan to establish local Swarms chapters worldwide, where users can meet in person to share knowledge, collaborate on projects, and build lasting relationships that strengthen the global Swarms community. +def get_stock_data(symbol, from_date, to_date): + endpoint = f"{POLYGON_BASE_URL}/aggs/ticker/{symbol}/range/1/day/{from_date}/{to_date}" + params = { + 'apiKey': POLYGON_API_KEY, + 'adjusted': 'true' + } + response = requests.get(endpoint, params=params) + data = response.json() + return pd.DataFrame(data['results']) -# **Conclusion: Measuring Success One Milestone at a Time** +# Example usage +symbol = "AAPL" +from_date = "2023-01-01" +to_date = "2023-12-31" -The **path to 500 million agents by the end of 2024** and **10 billion agents by the end of 2025** is paved with strategic growth, infrastructure resilience, and user-centric improvements. Each milestone is a step closer to a fully realized vision of an agentic economy—one where agents are ubiquitous, assisting individuals, -businesses, and entire industries in achieving their goals more efficiently. +stock_data = get_stock_data(symbol, from_date, to_date) -By **tracking key metrics**, such as growth in agent numbers, the rate of agent deployment per user, and reducing churn, we ensure that Swarms not only grows in size but also in effectiveness, adoption, and user satisfaction. Through a combination of infrastructure development, community engagement, incentives, and constant user feedback, we will create an ecosystem where agents thrive, users are empowered, and the entire platform evolves towards our ambitious vision. +analysis_request = f""" +Analyze the following stock data for {symbol} from {from_date} to {to_date}: -This is the journey of Swarms—**a journey towards redefining how we interact with AI, solve complex problems, and enhance productivity**. With each milestone, we get closer to a future where swarms of agents are the bedrock of human-machine collaboration and an integral part of our daily lives. The journey ahead is one of -transformation, creativity, and collaboration, as we work together to create an AI-driven world that benefits everyone, enabling us to achieve more than we ever thought -possible. Our commitment to building an agentic ecosystem is unwavering, and we are excited to see the incredible impact that swarms of agents will have on the future of work, innovation, and human potential. +{stock_data.to_string()} +Provide insights on the stock's performance, including trends, volatility, and any notable events. +""" --------------------------------------------------- +analysis = agent.run(analysis_request) +print(analysis) +``` -# File: corporate/architecture.md +In this example, we've created an AI agent that can fetch stock data from Polygon.io and perform an analysis based on that data. The agent uses the GPT-4 model to generate insights about the stock's performance. -# Architecture +### Alpha Vantage -## **1. Introduction** +Next, let's create an agent that can work with Alpha Vantage data to perform fundamental analysis. -In today's rapidly evolving digital world, harnessing the collaborative power of multiple computational agents is more crucial than ever. 'Swarms' represents a bold stride in this direction—a scalable and dynamic framework designed to enable swarms of agents to function in harmony and tackle complex tasks. This document serves as a comprehensive guide, elucidating the underlying architecture and strategies pivotal to realizing the Swarms vision. +```python +import os +from swarms import Agent +from swarms.models import OpenAIChat +from dotenv import load_dotenv +import requests ---- +load_dotenv() -## **2. The Vision** +# Alpha Vantage API setup +ALPHA_VANTAGE_API_KEY = os.getenv("ALPHA_VANTAGE_API_KEY") +ALPHA_VANTAGE_BASE_URL = "https://www.alphavantage.co/query" -At its heart, the Swarms framework seeks to emulate the collaborative efficiency witnessed in natural systems, like ant colonies or bird flocks. These entities, though individually simple, achieve remarkable outcomes through collaboration. Similarly, Swarms will unleash the collective potential of numerous agents, operating cohesively. +# OpenAI API setup +OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") ---- +# Create an instance of the OpenAIChat class +model = OpenAIChat( + openai_api_key=OPENAI_API_KEY, + model_name="gpt-4", + temperature=0.1 +) -## **3. Architecture Overview** +# Initialize the agent +agent = Agent( + agent_name="Fundamental-Analysis-Agent", + system_prompt="You are a financial analysis AI assistant specializing in fundamental analysis. Your task is to analyze company financials and provide insights.", + llm=model, + max_loops=1, + dashboard=False, + verbose=True +) -### **3.1 Agent Level** -The base level that serves as the building block for all further complexity. +def get_income_statement(symbol): + params = { + 'function': 'INCOME_STATEMENT', + 'symbol': symbol, + 'apikey': ALPHA_VANTAGE_API_KEY + } + response = requests.get(ALPHA_VANTAGE_BASE_URL, params=params) + return response.json() -#### Mechanics: -* **Model**: At its core, each agent harnesses a powerful model like OpenAI's GPT. -* **Vectorstore**: A memory structure allowing agents to store and retrieve information. -* **Tools**: Utilities and functionalities that aid in the agent's task execution. +# Example usage +symbol = "MSFT" -#### Interaction: -Agents interact with the external world through their model and tools. The Vectorstore aids in retaining knowledge and facilitating inter-agent communication. +income_statement = get_income_statement(symbol) -### **3.2 Worker Infrastructure Level** -Building on the agent foundation, enhancing capability and readiness for swarm integration. +analysis_request = f""" +Analyze the following income statement data for {symbol}: -#### Mechanics: -* **Human Input Integration**: Enables agents to accept and understand human-provided instructions. -* **Unique Identifiers**: Assigns each agent a unique ID to facilitate tracking and communication. -* **Asynchronous Tools**: Bolsters agents' capability to multitask and interact in real-time. +{income_statement} -#### Interaction: -Each worker is an enhanced agent, capable of operating independently or in sync with its peers, allowing for dynamic, scalable operations. +Provide insights on the company's financial health, profitability trends, and any notable observations. +""" -### **3.3 Swarm Level** -Multiple Worker Nodes orchestrated into a synchronized, collaborative entity. +analysis = agent.run(analysis_request) +print(analysis) +``` -#### Mechanics: -* **Orchestrator**: The maestro, responsible for directing the swarm, task allocation, and communication. -* **Scalable Communication Layer**: Facilitates interactions among nodes and between nodes and the orchestrator. -* **Task Assignment & Completion Protocols**: Structured procedures ensuring tasks are efficiently distributed and concluded. +This example demonstrates an AI agent that can fetch income statement data from Alpha Vantage and perform a fundamental analysis of a company's financials. -#### Interaction: -Nodes collaborate under the orchestrator's guidance, ensuring tasks are partitioned appropriately, executed, and results consolidated. +### Yahoo Finance -### **3.4 Hivemind Level** -Envisioned as a 'Swarm of Swarms'. An upper echelon of collaboration. +Now, let's create an agent that can work with Yahoo Finance data to perform technical analysis. -#### Mechanics: -* **Hivemind Orchestrator**: Oversees multiple swarm orchestrators, ensuring harmony on a grand scale. -* **Inter-Swarm Communication Protocols**: Dictates how swarms interact, exchange information, and co-execute tasks. +```python +import os +from swarms import Agent +from swarms.models import OpenAIChat +from dotenv import load_dotenv +import yfinance as yf +import pandas as pd -#### Interaction: -Multiple swarms, each a formidable force, combine their prowess under the Hivemind. This level tackles monumental tasks by dividing them among swarms. +load_dotenv() ---- +# OpenAI API setup +OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") -## **4. Building the Framework: A Task Checklist** +# Create an instance of the OpenAIChat class +model = OpenAIChat( + openai_api_key=OPENAI_API_KEY, + model_name="gpt-4", + temperature=0.1 +) -### **4.1 Foundations: Agent Level** -* Define and standardize agent properties. -* Integrate desired model (e.g., OpenAI's GPT) with agent. -* Implement Vectorstore mechanisms: storage, retrieval, and communication protocols. -* Incorporate essential tools and utilities. -* Conduct preliminary testing: Ensure agents can execute basic tasks and utilize the Vectorstore. +# Initialize the agent +agent = Agent( + agent_name="Technical-Analysis-Agent", + system_prompt="You are a financial analysis AI assistant specializing in technical analysis. Your task is to analyze stock price data and provide insights on trends and potential trading signals.", + llm=model, + max_loops=1, + dashboard=False, + verbose=True +) -### **4.2 Enhancements: Worker Infrastructure Level** -* Interface agents with human input mechanisms. -* Assign and manage unique identifiers for each worker. -* Integrate asynchronous capabilities: Ensure real-time response and multitasking. -* Test worker nodes for both solitary and collaborative tasks. +def get_stock_data(symbol, start_date, end_date): + stock = yf.Ticker(symbol) + data = stock.history(start=start_date, end=end_date) + return data -### **4.3 Cohesion: Swarm Level** -* Design and develop the orchestrator: Ensure it can manage multiple worker nodes. -* Establish a scalable and efficient communication layer. -* Implement task distribution and retrieval protocols. -* Test swarms for efficiency, scalability, and robustness. +# Example usage +symbol = "GOOGL" +start_date = "2023-01-01" +end_date = "2023-12-31" -### **4.4 Apex Collaboration: Hivemind Level** -* Build the Hivemind Orchestrator: Ensure it can oversee multiple swarms. -* Define inter-swarm communication, prioritization, and task-sharing protocols. -* Develop mechanisms to balance loads and optimize resource utilization across swarms. -* Thoroughly test the Hivemind level for macro-task execution. +stock_data = get_stock_data(symbol, start_date, end_date) ---- +# Calculate some technical indicators +stock_data['SMA_20'] = stock_data['Close'].rolling(window=20).mean() +stock_data['SMA_50'] = stock_data['Close'].rolling(window=50).mean() -## **5. Integration and Communication Mechanisms** +analysis_request = f""" +Analyze the following stock price data and technical indicators for {symbol} from {start_date} to {end_date}: -### **5.1 Vectorstore as the Universal Communication Layer** -Serving as the memory and communication backbone, the Vectorstore must: -* Facilitate rapid storage and retrieval of high-dimensional vectors. -* Enable similarity-based lookups: Crucial for recognizing patterns or finding similar outputs. -* Scale seamlessly as agent count grows. +{stock_data.tail(30).to_string()} -### **5.2 Orchestrator-Driven Communication** -* Orchestrators, both at the swarm and hivemind level, should employ adaptive algorithms to optimally distribute tasks. -* Ensure real-time monitoring of task execution and worker node health. -* Integrate feedback loops: Allow for dynamic task reassignment in case of node failures or inefficiencies. +Provide insights on the stock's price trends, potential support and resistance levels, and any notable trading signals based on the moving averages. +""" ---- +analysis = agent.run(analysis_request) +print(analysis) +``` -## **6. Conclusion & Forward Path** +This example shows an AI agent that can fetch stock price data from Yahoo Finance, calculate some basic technical indicators, and perform a technical analysis. -The Swarms framework, once realized, will usher in a new era of computational efficiency and collaboration. While the roadmap ahead is intricate, with diligent planning, development, and testing, Swarms will redefine the boundaries of collaborative computing. +### IEX Cloud --------- +Let's create an agent that can work with IEX Cloud data to analyze company news sentiment. +```python +import os +from swarms import Agent +from swarms.models import OpenAIChat +from dotenv import load_dotenv +import requests -# Overview +load_dotenv() -### 1. Model +# IEX Cloud API setup +IEX_CLOUD_API_KEY = os.getenv("IEX_CLOUD_API_KEY") +IEX_CLOUD_BASE_URL = "https://cloud.iexapis.com/stable" -**Overview:** -The foundational level where a trained model (e.g., OpenAI GPT model) is initialized. It's the base on which further abstraction levels build upon. It provides the core capabilities to perform tasks, answer queries, etc. +# OpenAI API setup +OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") -**Diagram:** -``` -[ Model (openai) ] -``` +# Create an instance of the OpenAIChat class +model = OpenAIChat( + openai_api_key=OPENAI_API_KEY, + model_name="gpt-4", + temperature=0.1 +) -### 2. Agent Level +# Initialize the agent +agent = Agent( + agent_name="News-Sentiment-Analysis-Agent", + system_prompt="You are a financial analysis AI assistant specializing in news sentiment analysis. Your task is to analyze company news and provide insights on the overall sentiment and potential impact on the stock.", + llm=model, + max_loops=1, + dashboard=False, + verbose=True +) -**Overview:** -At the agent level, the raw model is coupled with tools and a vector store, allowing it to be more than just a model. The agent can now remember, use tools, and become a more versatile entity ready for integration into larger systems. +def get_company_news(symbol, last_n): + endpoint = f"{IEX_CLOUD_BASE_URL}/stock/{symbol}/news/last/{last_n}" + params = {'token': IEX_CLOUD_API_KEY} + response = requests.get(endpoint, params=params) + return response.json() -**Diagram:** -``` -+-----------+ -| Agent | -| +-------+ | -| | Model | | -| +-------+ | -| +-----------+ | -| | VectorStore | | -| +-----------+ | -| +-------+ | -| | Tools | | -| +-------+ | -+-----------+ -``` +# Example usage +symbol = "TSLA" +last_n = 10 -### 3. Worker Infrastructure Level +news_data = get_company_news(symbol, last_n) -**Overview:** -The worker infrastructure is a step above individual agents. Here, an agent is paired with additional utilities like human input and other tools, making it a more advanced, responsive unit capable of complex tasks. - -**Diagram:** -``` -+----------------+ -| WorkerNode | -| +-----------+ | -| | Agent | | -| | +-------+ | | -| | | Model | | | -| | +-------+ | | -| | +-------+ | | -| | | Tools | | | -| | +-------+ | | -| +-----------+ | -| | -| +-----------+ | -| |Human Input| | -| +-----------+ | -| | -| +-------+ | -| | Tools | | -| +-------+ | -+----------------+ -``` - -### 4. Swarm Level +analysis_request = f""" +Analyze the following recent news articles for {symbol}: -**Overview:** -At the swarm level, the orchestrator is central. It's responsible for assigning tasks to worker nodes, monitoring their completion, and handling the communication layer (for example, through a vector store or another universal communication mechanism) between worker nodes. - -**Diagram:** -``` - +------------+ - |Orchestrator| - +------------+ - | - +---------------------------+ - | | - | Swarm-level Communication| - | Layer (e.g. | - | Vector Store) | - +---------------------------+ - / | \ - +---------------+ +---------------+ +---------------+ - |WorkerNode 1 | |WorkerNode 2 | |WorkerNode n | - | | | | | | - +---------------+ +---------------+ +---------------+ - | Task Assigned | Task Completed | Communication | -``` - -### 5. Hivemind Level +{news_data} -**Overview:** -At the Hivemind level, it's a multi-swarm setup, with an upper-layer orchestrator managing multiple swarm-level orchestrators. The Hivemind orchestrator is responsible for broader tasks like assigning macro-tasks to swarms, handling inter-swarm communications, and ensuring the overall system is functioning smoothly. - -**Diagram:** -``` - +--------+ - |Hivemind| - +--------+ - | - +--------------+ - |Hivemind | - |Orchestrator | - +--------------+ - / | \ - +------------+ +------------+ +------------+ - |Orchestrator| |Orchestrator| |Orchestrator| - +------------+ +------------+ +------------+ - | | | -+--------------+ +--------------+ +--------------+ -| Swarm-level| | Swarm-level| | Swarm-level| -|Communication| |Communication| |Communication| -| Layer | | Layer | | Layer | -+--------------+ +--------------+ +--------------+ - / \ / \ / \ -+-------+ +-------+ +-------+ +-------+ +-------+ -|Worker | |Worker | |Worker | |Worker | |Worker | -| Node | | Node | | Node | | Node | | Node | -+-------+ +-------+ +-------+ +-------+ +-------+ -``` - -This setup allows the Hivemind level to operate at a grander scale, with the capability to manage hundreds or even thousands of worker nodes across multiple swarms efficiently. +Provide insights on the overall sentiment of the news, potential impact on the stock price, and any notable trends or events mentioned. +""" +analysis = agent.run(analysis_request) +print(analysis) +``` +This example demonstrates an AI agent that can fetch recent news data from IEX Cloud and perform a sentiment analysis on the company news. -------- -# **Swarms Framework Development Strategy Checklist** +### Finnhub -## **Introduction** +Finally, let's create an agent that can work with Finnhub data to analyze earnings estimates and recommendations. -The development of the Swarms framework requires a systematic and granular approach to ensure that each component is robust and that the overall framework is efficient and scalable. This checklist will serve as a guide to building Swarms from the ground up, breaking down tasks into small, manageable pieces. +```python +import os +from swarms import Agent +from swarms.models import OpenAIChat +from dotenv import load_dotenv +import finnhub ---- +load_dotenv() -## **1. Agent Level Development** +# Finnhub API setup +FINNHUB_API_KEY = os.getenv("FINNHUB_API_KEY") +finnhub_client = finnhub.Client(api_key=FINNHUB_API_KEY) -### **1.1 Model Integration** -- [ ] Research the most suitable models (e.g., OpenAI's GPT). -- [ ] Design an API for the agent to call the model. -- [ ] Implement error handling when model calls fail. -- [ ] Test the model with sample data for accuracy and speed. +# OpenAI API setup +OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") -### **1.2 Vectorstore Implementation** -- [ ] Design the schema for the vector storage system. -- [ ] Implement storage methods to add, delete, and update vectors. -- [ ] Develop retrieval methods with optimization for speed. -- [ ] Create protocols for vector-based communication between agents. -- [ ] Conduct stress tests to ascertain storage and retrieval speed. +# Create an instance of the OpenAIChat class +model = OpenAIChat( + openai_api_key=OPENAI_API_KEY, + model_name="gpt-4", + temperature=0.1 +) -### **1.3 Tools & Utilities Integration** -- [ ] List out essential tools required for agent functionality. -- [ ] Develop or integrate APIs for each tool. -- [ ] Implement error handling and logging for tool interactions. -- [ ] Validate tools integration with unit tests. +# Initialize the agent +agent = Agent( + agent_name="Earnings-Analysis-Agent", + system_prompt="You are a financial analysis AI assistant specializing in earnings analysis. Your task is to analyze earnings estimates and recommendations to provide insights on a company's financial outlook.", + llm=model, + max_loops=1, + dashboard=False, + verbose=True +) ---- +def get_earnings_estimates(symbol): + return finnhub_client.earnings_calendar(symbol=symbol, from_date="2023-01-01", to_date="2023-12-31") -## **2. Worker Infrastructure Level Development** +def get_recommendations(symbol): + return finnhub_client.recommendation_trends(symbol) -### **2.1 Human Input Integration** -- [ ] Design a UI/UX for human interaction with worker nodes. -- [ ] Create APIs for input collection. -- [ ] Implement input validation and error handling. -- [ ] Test human input methods for clarity and ease of use. +# Example usage +symbol = "NVDA" -### **2.2 Unique Identifier System** -- [ ] Research optimal formats for unique ID generation. -- [ ] Develop methods for generating and assigning IDs to agents. -- [ ] Implement a tracking system to manage and monitor agents via IDs. -- [ ] Validate the uniqueness and reliability of the ID system. +earnings_estimates = get_earnings_estimates(symbol) +recommendations = get_recommendations(symbol) -### **2.3 Asynchronous Operation Tools** -- [ ] Incorporate libraries/frameworks to enable asynchrony. -- [ ] Ensure tasks within an agent can run in parallel without conflict. -- [ ] Test asynchronous operations for efficiency improvements. +analysis_request = f""" +Analyze the following earnings estimates and recommendations for {symbol}: ---- +Earnings Estimates: +{earnings_estimates} -## **3. Swarm Level Development** +Recommendations: +{recommendations} -### **3.1 Orchestrator Design & Development** -- [ ] Draft a blueprint of orchestrator functionalities. -- [ ] Implement methods for task distribution among worker nodes. -- [ ] Develop communication protocols for the orchestrator to monitor workers. -- [ ] Create feedback systems to detect and address worker node failures. -- [ ] Test orchestrator with a mock swarm to ensure efficient task allocation. +Provide insights on the company's expected financial performance, analyst sentiment, and any notable trends in the recommendations. +""" -### **3.2 Communication Layer Development** -- [ ] Select a suitable communication protocol/framework (e.g., gRPC, WebSockets). -- [ ] Design the architecture for scalable, low-latency communication. -- [ ] Implement methods for sending, receiving, and broadcasting messages. -- [ ] Test communication layer for reliability, speed, and error handling. +analysis = agent.run(analysis_request) +print(analysis) +``` -### **3.3 Task Management Protocols** -- [ ] Develop a system to queue, prioritize, and allocate tasks. -- [ ] Implement methods for real-time task status tracking. -- [ ] Create a feedback loop for completed tasks. -- [ ] Test task distribution, execution, and feedback systems for efficiency. +This example shows an AI agent that can fetch earnings estimates and analyst recommendations from Finnhub and perform an analysis on the company's financial outlook. ---- +## Advanced Analysis Techniques -## **4. Hivemind Level Development** +To further enhance the capabilities of our AI agents, we can implement more advanced analysis techniques: -### **4.1 Hivemind Orchestrator Development** -- [ ] Extend swarm orchestrator functionalities to manage multiple swarms. -- [ ] Create inter-swarm communication protocols. -- [ ] Implement load balancing mechanisms to distribute tasks across swarms. -- [ ] Validate hivemind orchestrator functionalities with multi-swarm setups. +1. Multi-source analysis: Combine data from multiple providers to get a more comprehensive view of a stock or market. -### **4.2 Inter-Swarm Communication Protocols** -- [ ] Design methods for swarms to exchange data. -- [ ] Implement data reconciliation methods for swarms working on shared tasks. -- [ ] Test inter-swarm communication for efficiency and data integrity. +2. Time series forecasting: Implement machine learning models for price prediction. ---- +3. Sentiment analysis of social media: Incorporate data from social media platforms to gauge market sentiment. -## **5. Scalability & Performance Testing** +4. Portfolio optimization: Use AI agents to suggest optimal portfolio allocations based on risk tolerance and investment goals. -- [ ] Simulate heavy loads to test the limits of the framework. -- [ ] Identify and address bottlenecks in both communication and computation. -- [ ] Conduct speed tests under different conditions. -- [ ] Test the system's responsiveness under various levels of stress. +5. Anomaly detection: Implement algorithms to detect unusual patterns or events in financial data. ---- +Here's an example of how we might implement a multi-source analysis: -## **6. Documentation & User Guide** +```python +import os +from swarms import Agent +from swarms.models import OpenAIChat +from dotenv import load_dotenv +import yfinance as yf +import requests +import pandas as pd -- [ ] Develop detailed documentation covering architecture, setup, and usage. -- [ ] Create user guides with step-by-step instructions. -- [ ] Incorporate visual aids, diagrams, and flowcharts for clarity. -- [ ] Update documentation regularly with new features and improvements. +load_dotenv() ---- +# API setup +POLYGON_API_KEY = os.getenv("POLYGON_API_KEY") +ALPHA_VANTAGE_API_KEY = os.getenv("ALPHA_VANTAGE_API_KEY") +OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") -## **7. Continuous Integration & Deployment** +# Create an instance of the OpenAIChat class +model = OpenAIChat( + openai_api_key=OPENAI_API_KEY, + model_name="gpt-4", + temperature=0.1 +) -- [ ] Setup CI/CD pipelines for automated testing and deployment. -- [ ] Ensure automatic rollback in case of deployment failures. -- [ ] Integrate code quality and security checks in the pipeline. -- [ ] Document deployment strategies and best practices. +# Initialize the agent +agent = Agent( + agent_name="Multi-Source-Analysis-Agent", + system_prompt="You are a financial analysis AI assistant capable of analyzing data from multiple sources. Your task is to provide comprehensive insights on a stock based on various data points.", + llm=model, + max_loops=1, + dashboard=False, + verbose=True +) ---- +def get_stock_data_yf(symbol, start_date, end_date): + stock = yf.Ticker(symbol) + return stock.history(start=start_date, end=end_date) -## **Conclusion** +def get_stock_data_polygon(symbol, from_date, to_date): + endpoint = f"https://api.polygon.io/v2/aggs/ticker/{symbol}/range/1/day/{from_date}/{to_date}" + params = {'apiKey': POLYGON_API_KEY, 'adjusted': 'true'} + response = requests.get(endpoint, params=params) + data = response.json() + return pd.DataFrame(data['results']) -The Swarms framework represents a monumental leap in agent-based computation. This checklist provides a thorough roadmap for the framework's development, ensuring that every facet is addressed in depth. Through diligent adherence to this guide, the Swarms vision can be realized as a powerful, scalable, and robust system ready to tackle the challenges of tomorrow. +def get_company_overview_av(symbol): + params = { + 'function': 'OVERVIEW', + 'symbol': symbol, + 'apikey': ALPHA_VANTAGE_API_KEY + } + response = requests.get("https://www.alphavantage.co/query", params=params) + return response.json() -(Note: This document, given the word limit, provides a high-level overview. A full 5000-word document would delve into even more intricate details, nuances, potential pitfalls, and include considerations for security, user experience, compatibility, etc.) +# Example usage +symbol = "AAPL" +start_date = "2023-01-01" +end_date = "2023-12-31" --------------------------------------------------- +yf_data = get_stock_data_yf(symbol, start_date, end_date) +polygon_data = get_stock_data_polygon(symbol, start_date, end_date) +av_overview = get_company_overview_av(symbol) -# File: corporate/bounties.md +analysis_request = f""" +Analyze the following data for {symbol} from {start_date} to {end_date}: -# Bounty Program +Yahoo Finance Data: +{yf_data.tail().to_string()} -Our bounty program is an exciting opportunity for contributors to help us build the future of Swarms. By participating, you can earn rewards while contributing to a project that aims to revolutionize digital activity. +Polygon.io Data: +{polygon_data.tail().to_string()} -Here's how it works: +Alpha Vantage Company Overview: +{av_overview} -1. **Check out our Roadmap**: We've shared our roadmap detailing our short and long-term goals. These are the areas where we're seeking contributions. +Provide a comprehensive analysis of the stock, including: +1. Price trends and volatility +2. Trading volume analysis +3. Fundamental analysis based on the company overview +4. Any discrepancies between data sources and potential reasons +5. Overall outlook and potential risks/opportunities +""" -2. **Pick a Task**: Choose a task from the roadmap that aligns with your skills and interests. If you're unsure, you can reach out to our team for guidance. +analysis = agent.run(analysis_request) +print(analysis) +``` -3. **Get to Work**: Once you've chosen a task, start working on it. Remember, quality is key. We're looking for contributions that truly make a difference. +This multi-source analysis example combines data from Yahoo Finance, Polygon.io, and Alpha Vantage to provide a more comprehensive view of a stock. The AI agent can then analyze this diverse set of data to provide deeper insights. -4. **Submit your Contribution**: Once your work is complete, submit it for review. We'll evaluate your contribution based on its quality, relevance, and the value it brings to Swarms. +Now, let's explore some additional advanced analysis techniques: -5. **Earn Rewards**: If your contribution is approved, you'll earn a bounty. The amount of the bounty depends on the complexity of the task, the quality of your work, and the value it brings to Swarms. +### Time Series Forecasting -## The Three Phases of Our Bounty Program +We can implement a simple time series forecasting model using the Prophet library and integrate it with our AI agent: -### Phase 1: Building the Foundation -In the first phase, our focus is on building the basic infrastructure of Swarms. This includes developing key components like the Swarms class, integrating essential tools, and establishing task completion and evaluation logic. We'll also start developing our testing and evaluation framework during this phase. If you're interested in foundational work and have a knack for building robust, scalable systems, this phase is for you. +```python +import os +from swarms import Agent +from swarms.models import OpenAIChat +from dotenv import load_dotenv +import yfinance as yf +import pandas as pd +from prophet import Prophet +import matplotlib.pyplot as plt -### Phase 2: Enhancing the System -In the second phase, we'll focus on enhancing Swarms by integrating more advanced features, improving the system's efficiency, and refining our testing and evaluation framework. This phase involves more complex tasks, so if you enjoy tackling challenging problems and contributing to the development of innovative features, this is the phase for you. +load_dotenv() -### Phase 3: Towards Super-Intelligence -The third phase of our bounty program is the most exciting - this is where we aim to achieve super-intelligence. In this phase, we'll be working on improving the swarm's capabilities, expanding its skills, and fine-tuning the system based on real-world testing and feedback. If you're excited about the future of AI and want to contribute to a project that could potentially transform the digital world, this is the phase for you. +OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") -Remember, our roadmap is a guide, and we encourage you to bring your own ideas and creativity to the table. We believe that every contribution, no matter how small, can make a difference. So join us on this exciting journey and help us create the future of Swarms. +model = OpenAIChat( + openai_api_key=OPENAI_API_KEY, + model_name="gpt-4", + temperature=0.1 +) -**To participate in our bounty program, visit the [Swarms Bounty Program Page](https://swarms.ai/bounty).** Let's build the future together! +agent = Agent( + agent_name="Time-Series-Forecast-Agent", + system_prompt="You are a financial analysis AI assistant specializing in time series forecasting. Your task is to analyze stock price predictions and provide insights.", + llm=model, + max_loops=1, + dashboard=False, + verbose=True +) +def get_stock_data(symbol, start_date, end_date): + stock = yf.Ticker(symbol) + data = stock.history(start=start_date, end=end_date) + return data +def forecast_stock_price(data, periods=30): + df = data.reset_index()[['Date', 'Close']] + df.columns = ['ds', 'y'] + + model = Prophet() + model.fit(df) + + future = model.make_future_dataframe(periods=periods) + forecast = model.predict(future) + + fig = model.plot(forecast) + plt.savefig('forecast_plot.png') + plt.close() + + return forecast +# Example usage +symbol = "MSFT" +start_date = "2020-01-01" +end_date = "2023-12-31" +stock_data = get_stock_data(symbol, start_date, end_date) +forecast = forecast_stock_price(stock_data) -## Bounties for Roadmap Items +analysis_request = f""" +Analyze the following time series forecast for {symbol}: -To accelerate the development of Swarms and to encourage more contributors to join our journey towards automating every digital activity in existence, we are announcing a Bounty Program for specific roadmap items. Each bounty will be rewarded based on the complexity and importance of the task. Below are the items available for bounty: +Forecast Data: +{forecast.tail(30).to_string()} -1. **Multi-Agent Debate Integration**: $2000 -2. **Meta Prompting Integration**: $1500 -3. **Swarms Class**: $1500 -4. **Integration of Additional Tools**: $1000 -5. **Task Completion and Evaluation Logic**: $2000 -6. **Ocean Integration**: $2500 -7. **Improved Communication**: $2000 -8. **Testing and Evaluation**: $1500 -9. **Worker Swarm Class**: $2000 -10. **Documentation**: $500 +The forecast plot has been saved as 'forecast_plot.png'. -For each bounty task, there will be a strict evaluation process to ensure the quality of the contribution. This process includes a thorough review of the code and extensive testing to ensure it meets our standards. +Provide insights on: +1. The predicted trend for the stock price +2. Any seasonal patterns observed +3. Potential factors that might influence the forecast +4. Limitations of this forecasting method +5. Recommendations for investors based on this forecast +""" -# 3-Phase Testing Framework +analysis = agent.run(analysis_request) +print(analysis) +``` -To ensure the quality and efficiency of the Swarm, we will introduce a 3-phase testing framework which will also serve as our evaluation criteria for each of the bounty tasks. +This example demonstrates how to integrate a time series forecasting model (Prophet) with our AI agent. The agent can then provide insights based on the forecasted data. -## Phase 1: Unit Testing -In this phase, individual modules will be tested to ensure that they work correctly in isolation. Unit tests will be designed for all functions and methods, with an emphasis on edge cases. +### Sentiment Analysis of Social Media -## Phase 2: Integration Testing -After passing unit tests, we will test the integration of different modules to ensure they work correctly together. This phase will also test the interoperability of the Swarm with external systems and libraries. +We can use a pre-trained sentiment analysis model to analyze tweets about a company and integrate this with our AI agent: -## Phase 3: Benchmarking & Stress Testing -In the final phase, we will perform benchmarking and stress tests. We'll push the limits of the Swarm under extreme conditions to ensure it performs well in real-world scenarios. This phase will measure the performance, speed, and scalability of the Swarm under high load conditions. +```python +import os +from swarms import Agent +from swarms.models import OpenAIChat +from dotenv import load_dotenv +import tweepy +from textblob import TextBlob +import pandas as pd -By following this 3-phase testing framework, we aim to develop a reliable, high-performing, and scalable Swarm that can automate all digital activities. +load_dotenv() -# Reverse Engineering to Reach Phase 3 +# Twitter API setup +TWITTER_API_KEY = os.getenv("TWITTER_API_KEY") +TWITTER_API_SECRET = os.getenv("TWITTER_API_SECRET") +TWITTER_ACCESS_TOKEN = os.getenv("TWITTER_ACCESS_TOKEN") +TWITTER_ACCESS_TOKEN_SECRET = os.getenv("TWITTER_ACCESS_TOKEN_SECRET") -To reach the Phase 3 level, we need to reverse engineer the tasks we need to complete. Here's an example of what this might look like: +auth = tweepy.OAuthHandler(TWITTER_API_KEY, TWITTER_API_SECRET) +auth.set_access_token(TWITTER_ACCESS_TOKEN, TWITTER_ACCESS_TOKEN_SECRET) +api = tweepy.API(auth) -1. **Set Clear Expectations**: Define what success looks like for each task. Be clear about the outputs and outcomes we expect. This will guide our testing and development efforts. +# OpenAI setup +OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") -2. **Develop Testing Scenarios**: Create a comprehensive list of testing scenarios that cover both common and edge cases. This will help us ensure that our Swarm can handle a wide range of situations. +model = OpenAIChat( + openai_api_key=OPENAI_API_KEY, + model_name="gpt-4", + temperature=0.1 +) -3. **Write Test Cases**: For each scenario, write detailed test cases that outline the exact steps to be followed, the inputs to be used, and the expected outputs. +agent = Agent( + agent_name="Social-Media-Sentiment-Agent", + system_prompt="You are a financial analysis AI assistant specializing in social media sentiment analysis. Your task is to analyze sentiment data from tweets and provide insights on market perception.", + llm=model, + max_loops=1, + dashboard=False, + verbose=True +) -4. **Execute the Tests**: Run the test cases on our Swarm, making note of any issues or bugs that arise. +def get_tweets(query, count=100): + tweets = api.search_tweets(q=query, count=count, tweet_mode="extended") + return [tweet.full_text for tweet in tweets] -5. **Iterate and Improve**: Based on the results of our tests, iterate and improve our Swarm. This may involve fixing bugs, optimizing code, or redesigning parts of our system. +def analyze_sentiment(tweets): + sentiments = [TextBlob(tweet).sentiment.polarity for tweet in tweets] + return pd.DataFrame({'tweet': tweets, 'sentiment': sentiments}) -6. **Repeat**: Repeat this process until our Swarm meets our expectations and passes all test cases. +# Example usage +symbol = "TSLA" +query = f"${symbol} stock" -By following these steps, we will systematically build, test, and improve our Swarm until it reaches the Phase 3 level. This methodical approach will help us ensure that we create a reliable, high-performing, and scalable Swarm that can truly automate all digital activities. +tweets = get_tweets(query) +sentiment_data = analyze_sentiment(tweets) -Let's shape the future of digital automation together! +analysis_request = f""" +Analyze the following sentiment data for tweets about {symbol} stock: +Sentiment Summary: +Positive tweets: {sum(sentiment_data['sentiment'] > 0)} +Negative tweets: {sum(sentiment_data['sentiment'] < 0)} +Neutral tweets: {sum(sentiment_data['sentiment'] == 0)} --------------------------------------------------- +Average sentiment: {sentiment_data['sentiment'].mean()} -# File: corporate/bounty_program.md +Sample tweets and their sentiments: +{sentiment_data.head(10).to_string()} -# Swarms Bounty Program +Provide insights on: +1. The overall sentiment towards the stock +2. Any notable trends or patterns in the sentiment +3. Potential reasons for the observed sentiment +4. How this sentiment might impact the stock price +5. Limitations of this sentiment analysis method +""" -The Swarms Bounty Program is an initiative designed to incentivize contributors to help us improve and expand the Swarms framework. With an impressive $150,000 allocated for bounties, contributors have the unique opportunity to earn generous rewards while gaining prestigious recognition in the Swarms community of over 9,000 agent engineers. This program offers more than just financial benefits; it allows contributors to play a pivotal role in advancing the field of multi-agent collaboration and AI automation, while also growing their professional skills and network. By joining the Swarms Bounty Program, you become part of an innovative movement shaping the future of technology. +analysis = agent.run(analysis_request) +print(analysis) +``` -## Why Contribute? +This example shows how to perform sentiment analysis on tweets about a stock and integrate the results with our AI agent for further analysis. -1. **Generous Rewards**: The bounty pool totals $150,000, ensuring that contributors are fairly compensated for their valuable work on successfully completed tasks. Each task comes with its own reward, reflecting its complexity and impact. +### Portfolio Optimization -2. **Community Status**: Gain coveted recognition as a valued and active contributor within the thriving Swarms community. This status not only highlights your contributions but also builds your reputation among a network of AI engineers. +We can use the PyPortfolioOpt library to perform portfolio optimization and have our AI agent provide insights: -3. **Skill Development**: Collaborate on cutting-edge AI projects, hone your expertise in agent engineering, and learn practical skills that can be applied to real-world challenges in the AI domain. +```python +import os +from swarms import Agent +from swarms.models import OpenAIChat +from dotenv import load_dotenv +import yfinance as yf +import pandas as pd +import numpy as np +from pypfopt import EfficientFrontier +from pypfopt import risk_models +from pypfopt import expected_returns -4. **Networking Opportunities**: Work side-by-side with over 9,000 agent engineers in our active and supportive community. This network fosters collaboration, knowledge sharing, and mentorship opportunities that can significantly boost your career. +load_dotenv() -## How It Works +OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") -1. **Explore Issues and Tasks**: - - Visit the [Swarms GitHub Issues](https://github.com/kyegomez/swarms/issues) to find a comprehensive list of open tasks requiring attention. These issues range from coding challenges to documentation improvements, offering opportunities for contributors with various skill sets. - - Check the [Swarms Project Board](https://github.com/users/kyegomez/projects/1) for prioritized tasks and ongoing milestones. This board provides a clear view of project priorities and helps contributors align their efforts with the project's immediate goals. +model = OpenAIChat( + openai_api_key=OPENAI_API_KEY, + model_name="gpt-4", + temperature=0.1 +) -2. **Claim a Bounty**: - - Identify a task that aligns with your interests and expertise. - - Comment on the issue to indicate your intent to work on it and describe your approach if necessary. - - Await approval from the Swarms team before commencing work. Approval ensures clarity and avoids duplication of efforts by other contributors. +agent = Agent( + agent_name="Portfolio-Optimization-Agent", + system_prompt="You are a financial analysis AI assistant specializing in portfolio optimization. Your task is to analyze optimized portfolio allocations and provide investment advice.", + llm=model, + max_loops=1, + dashboard=False, + verbose=True +) -3. **Submit Your Work**: - - Complete the task as per the outlined requirements in the issue description. Pay close attention to details to ensure your submission meets the expectations. - - Submit your pull request (PR) on GitHub with all the required elements, including documentation, test cases, or any relevant files that demonstrate your work. - - Engage with reviewers to refine your submission if requested. +def get_stock_data(symbols, start_date, end_date): + data = yf.download(symbols, start=start_date, end=end_date)['Adj Close'] + return data -4. **Earn Rewards**: - - Once your PR is reviewed, accepted, and merged into the main project, you will receive the bounty payment associated with the task. - - Your contributor status in the Swarms community will be updated, showcasing your involvement and accomplishments. +def optimize_portfolio(data): + mu = expected_returns.mean_historical_return(data) + S = risk_models.sample_cov(data) + + ef = EfficientFrontier(mu, S) + weights = ef.max_sharpe() + cleaned_weights = ef.clean_weights() + + return cleaned_weights -## Contribution Guidelines -To ensure high-quality contributions and streamline the process, please adhere to the following guidelines: -- Familiarize yourself with the [Swarms Contribution Guidelines](https://github.com/kyegomez/swarms/blob/main/CONTRIBUTING.md). These guidelines outline coding standards, best practices, and procedures for contributing effectively. +# Example usage +symbols = ["AAPL", "GOOGL", "MSFT", "AMZN", "FB"] +start_date = "2018-01-01" +end_date = "2023-12-31" -- Ensure your code is clean, modular, and well-documented. Contributions that adhere to the project's standards are more likely to be accepted. +stock_data = get_stock_data(symbols, start_date, end_date) +optimized_weights = optimize_portfolio(stock_data) -- Actively communicate with the Swarms team and other contributors. Clear communication helps resolve uncertainties, avoids duplication, and fosters collaboration within the community. +analysis_request = f""" +Analyze the following optimized portfolio allocation: -## Get Involved +{pd.Series(optimized_weights).to_string()} -1. **Join the Community**: - - Become an active member of the Swarms community by joining our Discord server: [Join Now](https://discord.gg/jM3Z6M9uMq). The Discord server serves as a hub for discussions, updates, and support. +The optimization aimed to maximize the Sharpe ratio based on historical data from {start_date} to {end_date}. -2. **Stay Updated**: - - Keep track of the latest updates, announcements, and bounty opportunities by regularly checking the Discord channel and the GitHub repository. +Provide insights on: +1. The recommended allocation and its potential benefits +2. Any notable concentrations or diversification in the portfolio +3. Potential risks associated with this allocation +4. How this portfolio might perform in different market conditions +5. Recommendations for an investor considering this allocation +6. Limitations of this optimization method +""" -3. **Start Contributing**: - - Dive into the Swarms GitHub repository: [Swarms GitHub](https://github.com/kyegomez/swarms). Explore the codebase, familiarize yourself with the project structure, and identify areas where you can make an impact. +analysis = agent.run(analysis_request) +print(analysis) +``` -## Additional Benefits +This example demonstrates how to perform portfolio optimization using the PyPortfolioOpt library and have our AI agent provide insights on the optimized allocation. -Beyond monetary rewards, contributors gain intangible benefits that elevate their professional journey: +## Best Practices and Considerations -- **Recognition**: Your contributions will be showcased to a community of over 9,000 engineers, increasing your visibility and credibility in the AI field. +When using AI agents for financial data analysis, consider the following best practices: -- **Portfolio Building**: Add high-impact contributions to your portfolio, demonstrating your skills and experience to potential employers or collaborators. +1. Data quality: Ensure that the data you're feeding into the agents is accurate and up-to-date. -- **Knowledge Sharing**: Learn from and collaborate with experts in agent engineering, gaining insights into the latest advancements and best practices in the field. +2. Model limitations: Be aware of the limitations of both the financial models and the AI models being used. -## Contact Us -For any questions, support, or clarifications, reach out to the Swarms team: +3. Regulatory compliance: Ensure that your use of AI in financial analysis complies with relevant regulations. -- **Discord**: Engage directly with the team and fellow contributors in our active channels. +4. Ethical considerations: Be mindful of potential biases in AI models and strive for fair and ethical analysis. -- **GitHub**: Open an issue for specific questions or suggestions related to the project. We’re here to guide and assist you at every step of your contribution journey. +5. Continuous monitoring: Regularly evaluate the performance of your AI agents and update them as needed. ---- +6. Human oversight: While AI agents can provide valuable insights, human judgment should always play a role in financial decision-making. -Join us in building the future of multi-agent collaboration and AI automation. With your contributions, we can create something truly extraordinary and transformative. Together, let’s pave the way for groundbreaking advancements in technology and innovation! +7. Privacy and security: Implement robust security measures to protect sensitive financial data. +## Conclusion +The integration of AI agents with financial data APIs opens up exciting possibilities for advanced financial analysis. By leveraging the power of the Swarms framework and connecting it with various financial data providers, analysts and quants can gain deeper insights, automate complex analyses, and potentially make more informed investment decisions. --------------------------------------------------- +However, it's crucial to remember that while AI agents can process vast amounts of data and identify patterns that humans might miss, they should be used as tools to augment human decision-making rather than replace it entirely. The financial markets are complex systems influenced by numerous factors, many of which may not be captured in historical data or current models. -# File: corporate/checklist.md +As the field of AI in finance continues to evolve, we can expect even more sophisticated analysis techniques and integrations. Staying updated with the latest developments in both AI and financial analysis will be key to leveraging these powerful tools effectively. -# **Swarms Framework Development Strategy Checklist** +-------------------------------------------------- -## **Introduction** +# File: guides\healthcare_blog.md -The development of the Swarms framework requires a systematic and granular approach to ensure that each component is robust and that the overall framework is efficient and scalable. This checklist will serve as a guide to building Swarms from the ground up, breaking down tasks into small, manageable pieces. +# Unlocking Efficiency and Cost Savings in Healthcare: How Swarms of LLM Agents Can Revolutionize Medical Operations and Save Millions ---- +The healthcare industry is a complex ecosystem where time and money are critical. From administrative tasks to patient care, medical professionals often struggle to keep up with mounting demands, leading to inefficiencies that cost both time and money. Swarms of Large Language Model (LLM) agents represent a groundbreaking solution to these problems. By leveraging artificial intelligence in the form of swarms, healthcare organizations can automate various tasks, optimize processes, and dramatically improve both the quality of care and operational efficiency. -## **1. Agent Level Development** +In this comprehensive analysis, we will explore how swarms of LLM agents can help healthcare and medical organizations save millions of dollars and thousands of hours annually. We will provide precise estimations based on industry data, calculate potential savings, and outline various use cases. Additionally, mermaid diagrams will be provided to illustrate swarm architectures, and reference links to Swarms GitHub and other resources will be included. -### **1.1 Model Integration** -- [ ] Research the most suitable models (e.g., OpenAI's GPT). -- [ ] Design an API for the agent to call the model. -- [ ] Implement error handling when model calls fail. -- [ ] Test the model with sample data for accuracy and speed. +### 1. Administrative Automation -### **1.2 Vectorstore Implementation** -- [ ] Design the schema for the vector storage system. -- [ ] Implement storage methods to add, delete, and update vectors. -- [ ] Develop retrieval methods with optimization for speed. -- [ ] Create protocols for vector-based communication between agents. -- [ ] Conduct stress tests to ascertain storage and retrieval speed. +#### Use Case: Billing and Claims Processing -### **1.3 Tools & Utilities Integration** -- [ ] List out essential tools required for agent functionality. -- [ ] Develop or integrate APIs for each tool. -- [ ] Implement error handling and logging for tool interactions. -- [ ] Validate tools integration with unit tests. +Administrative work is a major time drain in the healthcare sector, especially when it comes to billing and claims processing. The process is traditionally labor-intensive, requiring human staff to manually review and process claims, which often results in errors, delays, and higher operational costs. ---- +**How Swarms of LLM Agents Can Help:** +Swarms of LLM agents can automate the entire billing and claims process, from coding procedures to filing claims with insurance companies. These agents can read medical records, understand the diagnosis codes (ICD-10), and automatically generate billing forms. With intelligent claims management, LLM agents can also follow up with insurance companies to ensure timely payment. -## **2. Worker Infrastructure Level Development** +**Estimated Savings:** -### **2.1 Human Input Integration** -- [ ] Design a UI/UX for human interaction with worker nodes. -- [ ] Create APIs for input collection. -- [ ] Implement input validation and error handling. -- [ ] Test human input methods for clarity and ease of use. +- Average cost per manual claim: $25 -### **2.2 Unique Identifier System** -- [ ] Research optimal formats for unique ID generation. -- [ ] Develop methods for generating and assigning IDs to agents. -- [ ] Implement a tracking system to manage and monitor agents via IDs. -- [ ] Validate the uniqueness and reliability of the ID system. +- Average claims per hospital: 10,000 per month -### **2.3 Asynchronous Operation Tools** -- [ ] Incorporate libraries/frameworks to enable asynchrony. -- [ ] Ensure tasks within an agent can run in parallel without conflict. -- [ ] Test asynchronous operations for efficiency improvements. +- Swarms of LLM agents can reduce processing time by 90% and errors by 95% ---- +- Estimated annual savings per hospital: -## **3. Swarm Level Development** + - Savings per claim: $22.5 (90% reduction) -### **3.1 Orchestrator Design & Development** -- [ ] Draft a blueprint of orchestrator functionalities. -- [ ] Implement methods for task distribution among worker nodes. -- [ ] Develop communication protocols for the orchestrator to monitor workers. -- [ ] Create feedback systems to detect and address worker node failures. -- [ ] Test orchestrator with a mock swarm to ensure efficient task allocation. + - Total annual savings: 10,000 claims/month × 12 months × $22.5 = **$2.7 million** -### **3.2 Communication Layer Development** -- [ ] Select a suitable communication protocol/framework (e.g., gRPC, WebSockets). -- [ ] Design the architecture for scalable, low-latency communication. -- [ ] Implement methods for sending, receiving, and broadcasting messages. -- [ ] Test communication layer for reliability, speed, and error handling. -### **3.3 Task Management Protocols** -- [ ] Develop a system to queue, prioritize, and allocate tasks. -- [ ] Implement methods for real-time task status tracking. -- [ ] Create a feedback loop for completed tasks. -- [ ] Test task distribution, execution, and feedback systems for efficiency. +#### Billing and Claims Processing Swarm +```mermaid +graph TD; + A[Medical Records] --> B[ICD-10 Coding Agent]; + B --> C[Billing Form Agent]; + C --> D[Claims Submission Agent]; + D --> E[Insurance Follow-up Agent]; + E --> F[Payment Processing]; +``` ---- +### 2. Enhancing Clinical Decision Support -## **4. Hivemind Level Development** +#### Use Case: Diagnostic Assistance -### **4.1 Hivemind Orchestrator Development** -- [ ] Extend swarm orchestrator functionalities to manage multiple swarms. -- [ ] Create inter-swarm communication protocols. -- [ ] Implement load balancing mechanisms to distribute tasks across swarms. -- [ ] Validate hivemind orchestrator functionalities with multi-swarm setups. +Doctors are increasingly turning to AI to assist in diagnosing complex medical conditions. Swarms of LLM agents can be trained to analyze patient data, laboratory results, and medical histories to assist doctors in making more accurate diagnoses. -### **4.2 Inter-Swarm Communication Protocols** -- [ ] Design methods for swarms to exchange data. -- [ ] Implement data reconciliation methods for swarms working on shared tasks. -- [ ] Test inter-swarm communication for efficiency and data integrity. +**How Swarms of LLM Agents Can Help:** +A swarm of LLM agents can scan through thousands of medical records, journals, and patient histories to identify patterns or suggest rare diagnoses. These agents work collaboratively to analyze test results, compare symptoms with a vast medical knowledge base, and provide doctors with a list of probable diagnoses and recommended tests. ---- +**Estimated Savings:** -## **5. Scalability & Performance Testing** +- Time saved per diagnosis: 2 hours per patient -- [ ] Simulate heavy loads to test the limits of the framework. -- [ ] Identify and address bottlenecks in both communication and computation. -- [ ] Conduct speed tests under different conditions. -- [ ] Test the system's responsiveness under various levels of stress. +- Average patient cases per hospital: 5,000 per year ---- +- Time saved annually: 2 × 5,000 = 10,000 hours -## **6. Documentation & User Guide** +- Doctor's hourly rate: $150 -- [ ] Develop detailed documentation covering architecture, setup, and usage. -- [ ] Create user guides with step-by-step instructions. -- [ ] Incorporate visual aids, diagrams, and flowcharts for clarity. -- [ ] Update documentation regularly with new features and improvements. +- Total annual savings: 10,000 × $150 = **$1.5 million** ---- -## **7. Continuous Integration & Deployment** +#### Diagnostic Swarm +```mermaid +graph TD; + A[Patient Data] --> B[Lab Results]; + A --> C[Medical History]; + B --> D[Symptom Analysis Agent]; + C --> E[Pattern Recognition Agent]; + D --> F[Diagnosis Suggestion Agent]; + E --> F; + F --> G[Doctor]; +``` -- [ ] Setup CI/CD pipelines for automated testing and deployment. -- [ ] Ensure automatic rollback in case of deployment failures. -- [ ] Integrate code quality and security checks in the pipeline. -- [ ] Document deployment strategies and best practices. +### 3. Streamlining Patient Communication ---- +#### Use Case: Patient Follow-ups and Reminders -## **Conclusion** +Timely communication with patients is critical for maintaining healthcare quality, but it can be extremely time-consuming for administrative staff. Missed appointments and delayed follow-ups lead to poor patient outcomes and lost revenue. -The Swarms framework represents a monumental leap in agent-based computation. This checklist provides a thorough roadmap for the framework's development, ensuring that every facet is addressed in depth. Through diligent adherence to this guide, the Swarms vision can be realized as a powerful, scalable, and robust system ready to tackle the challenges of tomorrow. +**How Swarms of LLM Agents Can Help:** +LLM agents can handle patient follow-ups by sending reminders for appointments, check-ups, and medication refills. Additionally, these agents can answer common patient queries, thereby reducing the workload for human staff. These agents can be connected to Electronic Health Record (EHR) systems to monitor patient data and trigger reminders based on predefined criteria. -(Note: This document, given the word limit, provides a high-level overview. A full 5000-word document would delve into even more intricate details, nuances, potential pitfalls, and include considerations for security, user experience, compatibility, etc.) +**Estimated Savings:** --------------------------------------------------- +- Average cost per patient follow-up: $5 -# File: corporate/cost_analysis.md +- Number of follow-ups: 20,000 annually per hospital -# Costs Structure of Deploying Autonomous Agents +- Swarm efficiency: 90% reduction in manual effort -## Table of Contents +- Total annual savings: 20,000 × $4.5 = **$90,000** -1. Introduction -2. Our Time: Generating System Prompts and Custom Tools -3. Consultancy Fees -4. Model Inference Infrastructure -5. Deployment and Continual Maintenance -6. Output Metrics: Blogs Generation Rates ---- +#### Patient Follow-up Swarm +```mermaid +graph TD; + A[Patient Data from EHR] --> B[Appointment Reminder Agent]; + A --> C[Medication Reminder Agent]; + B --> D[Automated Text/Email]; + C --> D; + D --> E[Patient]; +``` -## 1. Introduction +### 4. Optimizing Inventory Management -Autonomous agents are revolutionizing various industries, from self-driving cars to chatbots and customer service solutions. The prospect of automation and improved efficiency makes these agents attractive investments. However, like any other technological solution, deploying autonomous agents involves several cost elements that organizations need to consider carefully. This comprehensive guide aims to provide an exhaustive outline of the costs associated with deploying autonomous agents. +#### Use Case: Pharmaceutical Stock Management ---- +Hospitals often struggle with managing pharmaceutical inventory efficiently. Overstocking leads to wasted resources, while understocking can be a critical problem for patient care. -## 2. Our Time: Generating System Prompts and Custom Tools +**How Swarms of LLM Agents Can Help:** +A swarm of LLM agents can predict pharmaceutical needs by analyzing patient data, historical inventory usage, and supplier delivery times. These agents can dynamically adjust stock levels, automatically place orders, and ensure that hospitals have the right medications at the right time. -### Description +**Estimated Savings:** -The deployment of autonomous agents often requires a substantial investment of time to develop system prompts and custom tools tailored to specific operational needs. +- Annual waste due to overstocking: $500,000 per hospital -### Costs +- Swarm efficiency: 80% reduction in overstocking -| Task | Time Required (Hours) | Cost per Hour ($) | Total Cost ($) | -| ------------------------ | --------------------- | ----------------- | -------------- | -| System Prompts Design | 50 | 100 | 5,000 | -| Custom Tools Development | 100 | 100 | 10,000 | -| **Total** | **150** | | **15,000** | +- Total annual savings: $500,000 × 0.8 = **$400,000** ---- -## 3. Consultancy Fees +#### Inventory Management Swarm +```mermaid +graph TD; + A[Patient Admission Data] --> B[Inventory Prediction Agent]; + B --> C[Stock Adjustment Agent]; + C --> D[Supplier Ordering Agent]; + D --> E[Pharmacy]; +``` -### Description +### 5. Improving Clinical Research -Consultation is often necessary for navigating the complexities of autonomous agents. This includes system assessment, customization, and other essential services. +#### Use Case: Literature Review and Data Analysis -### Costs +Medical researchers spend a significant amount of time reviewing literature and analyzing clinical trial data. Swarms of LLM agents can assist by rapidly scanning through research papers, extracting relevant information, and even suggesting areas for further investigation. -| Service | Fees ($) | -| -------------------- | --------- | -| Initial Assessment | 5,000 | -| System Customization | 7,000 | -| Training | 3,000 | -| **Total** | **15,000**| +**How Swarms of LLM Agents Can Help:** +These agents can be trained to perform literature reviews, extract relevant data, and cross-reference findings with ongoing clinical trials. LLM agents can also simulate clinical trial results by analyzing historical data, offering valuable insights before actual trials commence. ---- +**Estimated Savings:** -## 4. Model Inference Infrastructure +- Average time spent on literature review per paper: 5 hours -### Description +- Number of papers reviewed annually: 1,000 -The hardware and software needed for the agent's functionality, known as the model inference infrastructure, form a significant part of the costs. +- Time saved: 80% reduction in review time -### Costs +- Total time saved: 1,000 × 5 × 0.8 = 4,000 hours -| Component | Cost ($) | -| -------------------- | --------- | -| Hardware | 10,000 | -| Software Licenses | 2,000 | -| Cloud Services | 3,000 | -| **Total** | **15,000**| +- Researcher's hourly rate: $100 ---- +- Total annual savings: 4,000 × $100 = **$400,000** -## 5. Deployment and Continual Maintenance -### Description +#### Clinical Research Swarm +```mermaid +graph TD; + A[Research Papers] --> B[Data Extraction Agent]; + B --> C[Cross-reference Agent]; + C --> D[Simulation Agent]; + D --> E[Researcher]; +``` -Once everything is in place, deploying the autonomous agents and their ongoing maintenance are the next major cost factors. +### 6. Automating Medical Record Keeping -### Costs +#### Use Case: EHR Management and Documentation -| Task | Monthly Cost ($) | Annual Cost ($) | -| ------------------- | ---------------- | --------------- | -| Deployment | 5,000 | 60,000 | -| Ongoing Maintenance | 1,000 | 12,000 | -| **Total** | **6,000** | **72,000** | +Healthcare providers spend a significant amount of time inputting and managing Electronic Health Records (EHR). Manual entry often results in errors and takes away from the time spent with patients. ---- +**How Swarms of LLM Agents Can Help:** +Swarms of LLM agents can automate the documentation process by transcribing doctor-patient interactions, updating EHRs in real-time, and even detecting errors in the documentation. These agents can integrate with voice recognition systems to create seamless workflows, freeing up more time for healthcare providers to focus on patient care. -## 6. Output Metrics: Blogs Generation Rates +**Estimated Savings:** -### Description +- Average time spent on EHR per patient: 20 minutes -To provide a sense of what an investment in autonomous agents can yield, we offer the following data regarding blogs that can be generated as an example of output. +- Number of patients annually: 30,000 -### Blogs Generation Rates +- Time saved: 80% reduction in manual effort -| Timeframe | Number of Blogs | -|-----------|-----------------| -| Per Day | 20 | -| Per Week | 140 | -| Per Month | 600 | +- Total time saved: 30,000 × 20 minutes × 0.8 = 480,000 minutes or 8,000 hours +- Provider's hourly rate: $150 +- Total annual savings: 8,000 × $150 = **$1.2 million** --------------------------------------------------- +#### EHR Management Swarm +```mermaid +graph TD; + A[Doctor-Patient Interaction] --> B[Voice-to-Text Agent]; + B --> C[EHR Update Agent]; + C --> D[Error Detection Agent]; + D --> E[EHR System]; +``` -# File: corporate/culture.md +### 7. Reducing Diagnostic Errors -# Swarms Corp Culture Document +#### Use Case: Medical Imaging Analysis -## **Our Mission and Purpose** -At Swarms Corp, we believe in more than just building technology. We are advancing humanity by pioneering systems that allow agents—both AI and human—to collaborate seamlessly, working toward the betterment of society and unlocking a future of abundance. Our mission is everything, and each of us is here because we understand the transformative potential of our work. We are not just a company; we are a movement aimed at reshaping the future. We strive to create systems that can tackle the most complex challenges facing humanity, from climate change to inequality, with solutions that are powered by collective intelligence. +Medical imaging, such as MRI and CT scans, requires expert interpretation, which can be both time-consuming and prone to errors. Misdiagnoses or delays in interpretation can lead to prolonged treatment times and increased costs. -Our purpose goes beyond just technological advancement. We are here to create tools that empower people, uplift communities, and set a new standard for what technology can achieve when the mission is clear and the commitment is unwavering. We see every project as a step toward something greater—an abundant future where human potential is limitless and artificial intelligence serves as a powerful ally to mankind. +**How Swarms of LLM Agents Can Help:** +Swarms of LLM agents trained in computer vision can analyze medical images more accurately and faster than human radiologists. These agents can compare current scans with historical data, detect anomalies, and provide a diagnosis within minutes. Additionally, the swarm can escalate complex cases to human experts when necessary. -## **Values We Live By** +**Estimated Savings:** -### 1. **Hard Work: No Stone Unturned** -We believe that hard work is the foundation of all great achievements. At Swarms Corp, each member of the team is dedicated to putting in the effort required to solve complex problems. This isn’t just about long hours—it’s about focused, intentional work that leads to breakthroughs. We hold each other to high standards, and we don’t shy away from the hard paths when the mission calls for it. Every challenge we face is an opportunity to demonstrate our resilience and our commitment to excellence. We understand that the pursuit of groundbreaking innovation demands not just effort, but a relentless curiosity and the courage to face the unknown. +- Time saved per scan: 30 minutes -At Swarms Corp, we respect the grind because we know that transformative change doesn’t happen overnight. It requires continuous effort, sacrifice, and an unwavering focus on the task at hand. We celebrate hard work, not because it’s difficult, but because we understand its potential to transform ambitious ideas into tangible solutions. We honor the sweat equity that goes into building something that can truly make a difference. +- Number of scans annually: 10,000 -### 2. **Mission Above Everything** -Our mission is our guiding star. Every decision, every task, and every project must align with our overarching purpose: advancing humanity and creating a post-scarcity world. This means sometimes putting the collective goal ahead of individual preferences or comfort. We’re here to do something much larger than ourselves, and we prioritize the mission with relentless commitment. We know that personal sacrifices will often be necessary, and we embrace that reality because the rewards of our mission are far greater than any individual gain. +- Time saved: 10,000 × 30 minutes = 5,000 hours -When we say "mission above everything," we mean that our focus is not just on immediate success, but on creating a lasting impact that will benefit future generations. Our mission provides meaning and direction to our daily efforts, and we see every task as a small yet crucial part of our broader vision. We remind ourselves constantly of why we are here and who we are working for—not just our customers or stakeholders, but humanity as a whole. +- Radiologist's hourly rate: $200 -### 3. **Finding the Shortest Path** -Innovation thrives on efficiency. At Swarms Corp, we value finding the shortest, most effective paths to reach our goals. We encourage everyone to question the status quo, challenge existing processes, and ask, “Is there a better way to do this?” Creativity means finding new routes—whether by leveraging automation, questioning outdated steps, or collaborating to uncover insights faster. We honor those who seek smarter paths over conventional ones. Efficiency is not just about saving time—it’s about maximizing impact and ensuring that every ounce of effort drives meaningful progress. +- Total annual savings: 5,000 × $ -Finding the shortest path is about eliminating unnecessary complexity and focusing our energy on what truly matters. We encourage a culture of continuous improvement, where each team member is empowered to innovate on processes, tools, and methodologies. The shortest path does not mean cutting corners—it means removing obstacles, optimizing workflows, and focusing on high-leverage activities that bring us closer to our mission. We celebrate those who find elegant, effective solutions that others might overlook. -### 4. **Advancing Humanity** -The ultimate goal of everything we do is to elevate humanity. We envision a world where intelligence—both human and artificial—works in harmony to improve lives, solve global challenges, and expand possibilities. This ethos drives our work, whether it’s developing advanced AI systems, collaborating with others to push technological boundaries, or thinking deeply about how our creations can impact society in positive ways. Every line of code, every idea, and every strategy should move us closer to this vision. +200 = **$1 million** -Advancing humanity means we always think about the ethical implications of our work. We are deeply aware that the technology we create has the power to transform lives, and with that power comes the responsibility to ensure our contributions are always positive. We seek not only to push the boundaries of what technology can do but also to ensure that these advancements are inclusive and equitable. Our focus is on building a future where every person has access to the tools and opportunities they need to thrive. +#### Medical Imaging Swarm +```mermaid +graph TD; + A[Medical Image] --> B[Anomaly Detection Agent]; + B --> C[Comparison with Historical Data Agent]; + C --> D[Diagnosis Suggestion Agent]; + D --> E[Radiologist Review]; +``` -Our vision is to bridge the gap between technology and humanity’s most pressing needs. We aim to democratize intelligence, making it available for everyone, regardless of their background or resources. This is how we advance humanity—not just through technological feats, but by ensuring that our innovations serve the greater good and uplift everyone. +### Conclusion: The Financial and Time-Saving Impact of LLM Swarms in Healthcare -## **Our Way of Working** -- **Radical Ownership**: Each team member is not just a contributor but an owner of their domain. We take full responsibility for outcomes, follow through on our promises, and ensure that nothing falls through the cracks. We don’t wait for permission—we act, innovate, and lead. Radical ownership means understanding that our actions have a direct impact on the success of our mission. It’s about proactive problem-solving and always stepping up when we see an opportunity to make a difference. +In this comprehensive analysis, we explored how swarms of LLM agents can revolutionize the healthcare and medical industries by automating complex, labor-intensive tasks that currently drain both time and resources. From billing and claims processing to diagnostic assistance, patient communication, and medical imaging analysis, these intelligent agents can work collaboratively to significantly improve efficiency while reducing costs. Through our detailed calculations, it is evident that healthcare organizations could save upwards of $7.29 million annually, along with thousands of hours in administrative and clinical work. -- **Honesty and Respect**: We communicate openly and respect each other’s opinions. Tough conversations are a natural part of building something impactful. We face challenges head-on with honesty and directness while maintaining a respectful and supportive atmosphere. Honesty fosters trust, and trust is the foundation of any high-performing team. We value feedback and see it as an essential tool for growth—both for individuals and for the organization as a whole. +Swarms of LLM agents not only promise financial savings but also lead to improved patient outcomes, streamlined research, and enhanced operational workflows. By adopting these agentic solutions, healthcare organizations can focus more on their mission of providing high-quality care while ensuring their systems run seamlessly and efficiently. -- **One Team, One Mission**: Collaboration isn’t just encouraged—it’s essential. We operate as a swarm, where each agent contributes to a greater goal, learning from each other, sharing knowledge, and constantly iterating together. We celebrate wins collectively and approach obstacles with a unified spirit. No one succeeds alone; every achievement is the result of collective effort. We lift each other up, and we know that our strength lies in our unity and shared purpose. +To explore more about how swarms of agents can be tailored to your healthcare operations, you can visit the [Swarms GitHub](https://github.com/kyegomez/swarms) for code and documentation, explore our [Swarms Website](https://swarms.world) for further insights, and if you're ready to implement these solutions in your organization, feel free to [book a call](https://cal.com/swarms) for a personalized consultation. -- **The Future is Ours to Shape**: Our work is inherently future-focused. We’re not satisfied with simply keeping up—we want to set the pace. Every day, we take one step closer to a future where humanity’s potential is limitless, where scarcity is eliminated, and where intelligence—human and machine—advances society. We are not passive participants in the future; we are active shapers of it. We imagine a better tomorrow, and then we take deliberate steps to create it. Our work today will define what the world looks like tomorrow. +The future of healthcare is agentic, and by embracing swarms of LLM agents, your organization can unlock unprecedented levels of productivity and savings. -## **Expectations** +Swarms of LLM agents offer a powerful solution for medical and healthcare organizations looking to reduce costs and save time. Through automation, these agents can optimize everything from administrative tasks to clinical decision-making and inventory management. Based on the estimates provided, healthcare organizations can potentially save millions of dollars annually, all while improving the quality of care provided to patients. -- **Be Bold**: Don’t be afraid to take risks. Innovation requires experimentation, and sometimes that means making mistakes. We support each other in learning from failures and taking smart, calculated risks. Boldness is at the heart of progress. We want every member of Swarms Corp to feel empowered to think outside the box, propose unconventional ideas, and drive innovation. Mistakes are seen not as setbacks, but as opportunities for learning and growth. +The table below summarizes the estimated savings for each use case: -- **Keep the Mission First**: Every decision we make should be with our mission in mind. Ask yourself how your work advances the cause of creating an abundant future. The mission is the yardstick against which we measure our efforts, ensuring that everything we do pushes us closer to our ultimate goals. We understand that the mission is bigger than any one of us, and we strive to contribute meaningfully every day. +| Use Case | Estimated Annual Savings | +|------------------------------------|--------------------------| +| Billing and Claims Processing | $2.7 million | +| Diagnostic Assistance | $1.5 million | +| Patient Follow-ups and Reminders | $90,000 | +| Pharmaceutical Stock Management | $400,000 | +| Clinical Research | $400,000 | +| EHR Management and Documentation | $1.2 million | +| Medical Imaging Analysis | $1 million | +| **Total Estimated Savings** | **$7.29 million** | -- **Find Solutions, Not Problems**: While identifying issues is important, we value those who come with solutions. Embrace challenges as opportunities to innovate and find ways to make an impact. We foster a culture of proactive problem-solving where obstacles are seen as opportunities to exercise creativity. If something’s broken, we fix it. If there’s a better way, we find it. We expect our team members to be solution-oriented, always seeking ways to turn challenges into stepping stones for progress. +### References +- [Swarms GitHub](https://github.com/kyegomez/swarms) -- **Think Big, Act Fast**: We’re not here to make small changes—we’re here to revolutionize how we think about intelligence, automation, and society. Dream big, but work with urgency. We are tackling problems of immense scale, and we must move with intention and speed. Thinking big means envisioning a world that is radically different and better, and acting fast means executing the steps to get us there without hesitation. We value ambition and the courage to move swiftly when the time is right. +- [Swarms Website](https://swarms.xyz) -## **Our Commitment to You** -Swarms Corp is a place for dreamers and doers, for those who are driven by purpose and are unafraid of the work required to achieve it. We commit to providing you with the tools, support, and environment you need to contribute meaningfully to our mission. We are here to advance humanity together, one agent, one solution, one breakthrough at a time. We pledge to nurture an environment that encourages creativity, collaboration, and bold thinking. Here, you will find a community that celebrates your wins, supports you through challenges, and pushes you to be your best self. +- [book a call](https://cal.com/swarms) -Our commitment also includes ensuring that your voice is heard. We are building the future together, and every perspective matters. We strive to create an inclusive space where diversity of thought is welcomed, and where each team member feels valued for their unique contributions. At Swarms Corp, you are not just part of a team—you are part of a mission that aims to change the course of humanity for the better. Together, we’ll make the impossible possible, one breakthrough at a time. +- Swarms Discord: https://discord.gg/jM3Z6M9uMq +- Swarms Twitter: https://x.com/swarms_corp +- Swarms Spotify: https://open.spotify.com/show/2HLiswhmUaMdjHC8AUHcCF?si=c831ef10c5ef4994 --------------------------------------------------- +Swarms Blog: https://medium.com/@kyeg +Swarms Website: https://swarms.xyz -# File: corporate/data_room.md +By adopting swarms of LLM agents, healthcare organizations can streamline operations, reduce inefficiencies, and focus on what truly matters—delivering top-notch patient care. -# Swarms Data Room -## Table of Contents -**Introduction** +-------------------------------------------------- -- Overview of the Company +# File: guides\pricing.md -- Vision and Mission Statement +# Comparing LLM Provider Pricing: A Guide for Enterprises -- Executive Summary +Large language models (LLMs) have become a cornerstone of innovation for enterprises across various industries. -**Corporate Documents** +As executives contemplate which model to integrate into their operations, understanding the intricacies of LLM provider pricing is crucial. -- Articles of Incorporation +This comprehensive guide delves into the tactical business considerations, unit economics, profit margins, and ROI calculations that will empower decision-makers to deploy the right AI solution for their organization. -- Bylaws +## Table of Contents -- Shareholder Agreements +1. [Introduction to LLM Pricing Models](#introduction-to-llm-pricing-models) +2. [Understanding Unit Economics in LLM Deployment](#understanding-unit-economics-in-llm-deployment) +3. [Profit Margins and Cost Structures](#profit-margins-and-cost-structures) +4. [LLM Pricing in Action: Case Studies](#llm-pricing-in-action-case-studies) +5. [Calculating ROI for LLM Integration](#calculating-roi-for-llm-integration) +6. [Comparative Analysis of Major LLM Providers](#comparative-analysis-of-major-llm-providers) +7. [Hidden Costs and Considerations](#hidden-costs-and-considerations) +8. [Optimizing LLM Usage for Cost-Efficiency](#optimizing-llm-usage-for-cost-efficiency) +9. [Future Trends in LLM Pricing](#future-trends-in-llm-pricing) +10. [Strategic Decision-Making Framework](#strategic-decision-making-framework) +11. [Conclusion: Navigating the LLM Pricing Landscape](#conclusion-navigating-the-llm-pricing-landscape) -- Board Meeting Minutes +## 1. Introduction to LLM Pricing Models -- Company Structure and Org Chart +The pricing of Large Language Models (LLMs) is a complex landscape that can significantly impact an enterprise's bottom line. As we dive into this topic, it's crucial to understand the various pricing models employed by LLM providers and how they align with different business needs. -**Financial Information** +### Pay-per-Token Model -- Historical Financial Statements - - - Income Statements +The most common pricing structure in the LLM market is the pay-per-token model. In this system, businesses are charged based on the number of tokens processed by the model. A token can be as short as one character or as long as one word, depending on the language and the specific tokenization method used by the model. - - Balance Sheets +**Advantages:** +- Scalability: Costs scale directly with usage, allowing for flexibility as demand fluctuates. +- Transparency: Easy to track and attribute costs to specific projects or departments. - - Cash Flow Statements +**Disadvantages:** +- Unpredictability: Costs can vary significantly based on the verbosity of inputs and outputs. +- Potential for overruns: Without proper monitoring, costs can quickly escalate. -- Financial Projections and Forecasts +### Subscription-Based Models -- Cap Table +Some providers offer subscription tiers that provide a set amount of compute resources or tokens for a fixed monthly or annual fee. -- Funding History and Use of Funds +**Advantages:** +- Predictable costs: Easier budgeting and financial planning. +- Potential cost savings: Can be more economical for consistent, high-volume usage. -**Products and Services** +**Disadvantages:** +- Less flexibility: May lead to underutilization or overages. +- Commitment required: Often involves longer-term contracts. -- Detailed Descriptions of Products/Services +### Custom Enterprise Agreements -- Product Development Roadmap +For large-scale deployments, providers may offer custom pricing agreements tailored to the specific needs of an enterprise. -- User Manuals and Technical Specifications +**Advantages:** +- Optimized for specific use cases: Can include specialized support, SLAs, and pricing structures. +- Potential for significant cost savings at scale. -- Case Studies and Use Cases +**Disadvantages:** +- Complexity: Negotiating and managing these agreements can be resource-intensive. +- Less standardization: Difficult to compare across providers. +### Hybrid Models -## **Introduction** -Swarms provides automation-as-a-service through swarms of autonomous agents that work together as a team. We enable our customers to build, deploy, and scale production-grade multi-agent applications to automate real-world tasks. +Some providers are beginning to offer hybrid models that combine elements of pay-per-token and subscription-based pricing. -### **Vision** -Our vision for 2024 is to provide the most reliable infrastructure for deploying autonomous agents into the real world through the Swarm Cloud, our premier cloud platform for the scalable deployment of Multi-Modal Autonomous Agents. The platform focuses on delivering maximum value to users by only taking a small fee when utilizing the agents for the hosted compute power needed to host the agents. +**Advantages:** +- Flexibility: Can adapt to varying usage patterns. +- Risk mitigation: Balances the benefits of both main pricing models. -### **Executive Summary** -The Swarm Corporation aims to enable AI models to automate complex workflows and operations, not just singular low-value tasks. We believe collaboration between multiple agents can overcome limitations of individual agents for reasoning, planning, etc. This will allow automation of processes in mission-critical industries like security, logistics, and manufacturing where AI adoption is currently low. +**Disadvantages:** +- Complexity: Can be more challenging to understand and manage. +- Potential for suboptimal pricing if not carefully structured. -We provide an open source framework to deploy production-grade multi-modal agents in just a few lines of code. This builds our user base, recruits talent, gets customer feedback to improve products, gains awareness and trust. +As we progress through this guide, we'll explore how these pricing models interact with various business considerations and how executives can leverage this understanding to make informed decisions. -Our business model focuses on customer satisfaction, openness, integration with other tools/platforms, and production-grade reliability. +## 2. Understanding Unit Economics in LLM Deployment -Go-to-market strategy is to get the framework to product-market fit with over 50K weekly recurring users, then secure high-value contracts in target industries. Long-term monetization via microtransactions, usage-based pricing, subscriptions. +To make informed decisions about LLM deployment, executives must have a clear grasp of the unit economics involved. This section breaks down the components that contribute to the cost per unit of LLM usage and how they impact overall business economics. -The team has thousands of hours building and optimizing autonomous agents. Leadership includes AI engineers, product experts, open source contributors and community builders. +### Defining the Unit -Key milestones: get 80K framework users in January 2024, start contracts in target verticals, introduce commercial products in 2025 with various pricing models. +In the context of LLMs, a "unit" can be defined in several ways: -### **Resources** -- [Swarm Pre-Seed Deck](https://drive.google.com/file/d/1n8o2mjORbG96uDfx4TabjnyieludYaZz/view?usp=sharing) -- [Swarm Memo](https://docs.google.com/document/d/1hS_nv_lFjCqLfnJBoF6ULY9roTbSgSuCkvXvSUSc7Lo/edit?usp=sharing) +1. **Per Token**: The most granular unit, often used in pricing models. +2. **Per Request**: A single API call to the LLM, which may process multiple tokens. +3. **Per Task**: A complete operation, such as generating a summary or answering a question, which may involve multiple requests. +4. **Per User Interaction**: In customer-facing applications, this could be an entire conversation or session. +Understanding which unit is most relevant to your use case is crucial for accurate economic analysis. +### Components of Unit Cost +1. **Direct LLM Costs** + - Token processing fees + - API call charges + - Data transfer costs -## **Financial Documents** -This section is dedicated entirely for corporate documents. +2. **Indirect Costs** + - Compute resources for pre/post-processing + - Storage for inputs, outputs, and fine-tuning data + - Networking costs -- [Cap Table](https://docs.google.com/spreadsheets/d/1wuTWbfhYaY5Xp6nSQ9R0wDtSpwSS9coHxsjKd0UbIDc/edit?usp=sharing) +3. **Operational Costs** + - Monitoring and management tools + - Integration and maintenance engineering time + - Customer support related to AI functions -- [Cashflow Prediction Sheet](https://docs.google.com/spreadsheets/d/1HQEHCIXXMHajXMl5sj8MEfcQtWfOnD7GjHtNiocpD60/edit?usp=sharing) +4. **Overhead** + - Legal and compliance costs + - Training and documentation + - Risk management and insurance +### Calculating Unit Economics ------- +To calculate the true unit economics, follow these steps: -## **Product** -Swarms is an open source framework for developers in python to enable seamless, reliable, and scalable multi-agent orchestration through modularity, customization, and precision. +1. **Determine Total Costs**: Sum all direct, indirect, operational, and overhead costs over a fixed period (e.g., monthly). -- [Swarms Github Page:](https://github.com/kyegomez/swarms) -- [Swarms Memo](https://docs.google.com/document/d/1hS_nv_lFjCqLfnJBoF6ULY9roTbSgSuCkvXvSUSc7Lo/edit) -- [Swarms Project Board](https://github.com/users/kyegomez/projects/1) -- [Swarms Website](https://www.swarms.world/g) -- [Swarm Ecosystem](https://github.com/kyegomez/swarm-ecosystem) -- [Swarm Core](https://github.com/kyegomez/swarms-core) +2. **Measure Total Units**: Track the total number of relevant units processed in the same period. -### Product Growth Metrics -| Name | Description | Link | -|----------------------------------|---------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------| -| Total Downloads of all time | Total number of downloads for the product over its entire lifespan. | [![Downloads](https://static.pepy.tech/badge/swarms)](https://pepy.tech/project/swarms) | -| Downloads this month | Number of downloads for the product in the current month. | [![Downloads](https://static.pepy.tech/badge/swarms/month)](https://pepy.tech/project/swarms) | -| Total Downloads this week | Total number of downloads for the product in the current week. | [![Downloads](https://static.pepy.tech/badge/swarms/week)](https://pepy.tech/project/swarms) | -| Github Forks | Number of times the product's codebase has been copied for optimization, contribution, or usage. | [![GitHub forks](https://img.shields.io/github/forks/kyegomez/swarms)](https://github.com/kyegomez/swarms/network) | -| Github Stars | Number of users who have 'liked' the project. | [![GitHub stars](https://img.shields.io/github/stars/kyegomez/swarms)](https://github.com/kyegomez/swarms/stargazers) | -| Pip Module Metrics | Various project statistics such as watchers, number of contributors, date repository was created, and more. | [CLICK HERE](https://libraries.io/github/kyegomez/swarms) | -| Contribution Based Statistics | Statistics like number of contributors, lines of code changed, etc. | [HERE](https://github.com/kyegomez/swarms/graphs/contributors) | -| Github Community insights | Insights into the Github community around the product. | [Github Community insights](https://github.com/kyegomez/swarms/graphs/community) | -| Github Traffic Metrics | Metrics related to traffic, such as views and clones on Github. | [Github Traffic Metrics](https://github.com/kyegomez/swarms/graphs/traffic) | -| Issues with the framework | Current open issues for the product on Github. | [![GitHub issues](https://img.shields.io/github/issues/kyegomez/swarms)](https://github.com/kyegomez/swarms/issues) | +3. **Calculate Cost per Unit**: Divide total costs by total units. + ``` + Cost per Unit = Total Costs / Total Units + ``` +4. **Analyze Revenue per Unit**: If the LLM is part of a revenue-generating product, calculate the revenue attributed to each unit. +5. **Determine Profit per Unit**: Subtract the cost per unit from the revenue per unit. --------------------------------------------------- + ``` + Profit per Unit = Revenue per Unit - Cost per Unit + ``` -# File: corporate/demos.md +### Example Calculation -# Demo Ideas +Let's consider a hypothetical customer service AI chatbot: -* We could also try to create an AI influencer run by a swarm, let it create a whole identity and generate images, memes, and other content for Twitter, Reddit, etc. +- Monthly LLM API costs: $10,000 +- Indirect and operational costs: $5,000 +- Total monthly interactions: 100,000 -* had a thought that we should have either a more general one of these or a swarm or both -- need something connecting all the calendars, events, and initiatives of all the AI communities, langchain, laion, eluther, lesswrong, gato, rob miles, chatgpt hackers, etc etc +``` +Cost per Interaction = ($10,000 + $5,000) / 100,000 = $0.15 +``` -* Swarm of AI influencers to spread marketing +If each interaction generates an average of $0.50 in value (through cost savings or revenue): -* Delegation System to better organize teams: Start with a team of passionate humans and let them self-report their skills/strengths so the agent has a concept of who to delegate to, then feed the agent a huge task list (like the bullet list a few messages above) that it breaks down into actionable steps and "prompts" specific team members to complete tasks. Could even suggest breakout teams of a few people with complementary skills to tackle more complex tasks. There can also be a live board that updates each time a team member completes something, to encourage momentum and keep track of progress +``` +Profit per Interaction = $0.50 - $0.15 = $0.35 +``` +### Economies of Scale --------------------------------------------------- +As usage increases, unit economics often improve due to: -# File: corporate/design.md +- Volume discounts from LLM providers +- Amortization of fixed costs over more units +- Efficiency gains through learning and optimization -# Design Philosophy Document for Swarms +However, it's crucial to model how these economies of scale manifest in your specific use case, as they may plateau or even reverse at very high volumes due to increased complexity and support needs. -## Usable +### Diseconomies of Scale -### Objective +Conversely, be aware of potential diseconomies of scale: -Our goal is to ensure that Swarms is intuitive and easy to use for all users, regardless of their level of technical expertise. This includes the developers who implement Swarms in their applications, as well as end users who interact with the implemented systems. +- Increased complexity in managing large-scale deployments +- Higher costs for specialized talent as operations grow +- Potential for diminishing returns on very large language models -### Tactics +By thoroughly understanding these unit economics, executives can make more informed decisions about which LLM provider and pricing model best aligns with their business objectives and scale. -- Clear and Comprehensive Documentation: We will provide well-written and easily accessible documentation that guides users through using and understanding Swarms. -- User-Friendly APIs: We'll design clean and self-explanatory APIs that help developers to understand their purpose quickly. -- Prompt and Effective Support: We will ensure that support is readily available to assist users when they encounter problems or need help with Swarms. +## 3. Profit Margins and Cost Structures -## Reliable +Understanding profit margins and cost structures is crucial for executives evaluating LLM integration. This section explores how different pricing models and operational strategies can impact overall profitability. -### Objective +### Components of Profit Margin -Swarms should be dependable and trustworthy. Users should be able to count on Swarms to perform consistently and without error or failure. +1. **Gross Margin**: The difference between revenue and the direct costs of LLM usage. + ``` + Gross Margin = Revenue - Direct LLM Costs + Gross Margin % = (Gross Margin / Revenue) * 100 + ``` -### Tactics +2. **Contribution Margin**: Gross margin minus variable operational costs. + ``` + Contribution Margin = Gross Margin - Variable Operational Costs + ``` -- Robust Error Handling: We will focus on error prevention, detection, and recovery to minimize failures in Swarms. -- Comprehensive Testing: We will apply various testing methodologies such as unit testing, integration testing, and stress testing to validate the reliability of our software. -- Continuous Integration/Continuous Delivery (CI/CD): We will use CI/CD pipelines to ensure that all changes are tested and validated before they're merged into the main branch. +3. **Net Margin**: The final profit after all costs, including fixed overheads. + ``` + Net Margin = Contribution Margin - Fixed Costs + Net Margin % = (Net Margin / Revenue) * 100 + ``` -## Fast +### Cost Structures in LLM Deployment -### Objective +1. **Fixed Costs** + - Subscription fees for LLM access (if using a subscription model) + - Base infrastructure costs + - Core team salaries + - Licensing fees for essential software -Swarms should offer high performance and rapid response times. The system should be able to handle requests and tasks swiftly. +2. **Variable Costs** + - Per-token or per-request charges + - Scaling infrastructure costs + - Usage-based API fees + - Performance-based team bonuses -### Tactics +3. **Step Costs** + - Costs that increase in chunks as usage scales + - Examples: Adding new server clusters, hiring additional support staff -- Efficient Algorithms: We will focus on optimizing our algorithms and data structures to ensure they run as quickly as possible. -- Caching: Where appropriate, we will use caching techniques to speed up response times. -- Profiling and Performance Monitoring: We will regularly analyze the performance of Swarms to identify bottlenecks and opportunities for improvement. +### Analyzing Profit Margins Across Different Pricing Models -## Scalable +Let's compare how different LLM pricing models might affect profit margins for a hypothetical AI-powered writing assistant service: -### Objective +**Scenario**: The service charges users $20/month and expects to process an average of 100,000 tokens per user per month. -Swarms should be able to grow in capacity and complexity without compromising performance or reliability. It should be able to handle increased workloads gracefully. +1. **Pay-per-Token Model** + - LLM cost: $0.06 per 1,000 tokens + - Monthly LLM cost per user: $6 + - Gross margin per user: $14 (70%) -### Tactics +2. **Subscription Model** + - Fixed monthly fee: $5,000 for up to 10 million tokens + - At 1,000 users: $5 per user + - Gross margin per user: $15 (75%) -- Modular Architecture: We will design Swarms using a modular architecture that allows for easy scaling and modification. -- Load Balancing: We will distribute tasks evenly across available resources to prevent overload and maximize throughput. -- Horizontal and Vertical Scaling: We will design Swarms to be capable of both horizontal (adding more machines) and vertical (adding more power to an existing machine) scaling. +3. **Hybrid Model** + - Base fee: $2,000 per month + - Reduced per-token rate: $0.04 per 1,000 tokens + - Monthly LLM cost per user: $6 ($2 base + $4 usage) + - Gross margin per user: $14 (70%) -### Philosophy +### Strategies for Improving Profit Margins -Swarms is designed with a philosophy of simplicity and reliability. We believe that software should be a tool that empowers users, not a hurdle that they need to overcome. Therefore, our focus is on usability, reliability, speed, and scalability. We want our users to find Swarms intuitive and dependable, fast and adaptable to their needs. This philosophy guides all of our design and development decisions. +1. **Optimize Token Usage** + - Implement efficient prompting techniques + - Cache common responses + - Use compression algorithms for inputs and outputs -# Swarm Architecture Design Document +2. **Leverage Economies of Scale** + - Negotiate better rates at higher volumes + - Spread fixed costs across a larger user base -## Overview +3. **Implement Tiered Pricing** + - Offer different service levels to capture more value from power users + - Example: Basic ($10/month, 50K tokens), Pro ($30/month, 200K tokens) -The goal of the Swarm Architecture is to provide a flexible and scalable system to build swarm intelligence models that can solve complex problems. This document details the proposed design to create a plug-and-play system, which makes it easy to create custom swarms, and provides pre-configured swarms with multi-modal agents. +4. **Vertical Integration** + - Invest in proprietary LLM development for core functionalities + - Reduce dependency on third-party providers for critical operations -## Design Principles +5. **Smart Caching and Pre-computation** + - Store and reuse common LLM outputs + - Perform batch processing during off-peak hours -- **Modularity**: The system will be built in a modular fashion, allowing various components to be easily swapped or upgraded. -- **Interoperability**: Different swarm classes and components should be able to work together seamlessly. -- **Scalability**: The design should support the growth of the system by adding more components or swarms. -- **Ease of Use**: Users should be able to easily create their own swarms or use pre-configured ones with minimal configuration. +6. **Hybrid Cloud Strategies** + - Use on-premises solutions for consistent workloads + - Leverage cloud elasticity for demand spikes -## Design Components +### Case Study: Margin Improvement -### BaseSwarm +Consider a company that initially used a pay-per-token model: -The BaseSwarm is an abstract base class which defines the basic structure of a swarm and the methods that need to be implemented. Any new swarm should inherit from this class and implement the required methods. +**Initial State:** +- Revenue per user: $20 +- LLM cost per user: $6 +- Other variable costs: $4 +- Fixed costs per user: $5 +- Net margin per user: $5 (25%) -### Swarm Classes +**After Optimization:** +- Implemented efficient prompting: Reduced token usage by 20% +- Negotiated volume discount: 10% reduction in per-token price +- Introduced tiered pricing: Average revenue per user increased to $25 +- Optimized operations: Reduced other variable costs to $3 -Various Swarm classes can be implemented inheriting from the BaseSwarm class. Each swarm class should implement the required methods for initializing the components, worker nodes, and boss node, and running the swarm. +**Result:** +- New LLM cost per user: $4.32 +- New net margin per user: $12.68 (50.7%) -Pre-configured swarm classes with multi-modal agents can be provided for ease of use. These classes come with a default configuration of tools and agents, which can be used out of the box. +This case study demonstrates how a holistic approach to margin improvement, addressing both revenue and various cost components, can significantly enhance profitability. -### Tools and Agents +Understanding these profit margin dynamics and cost structures is essential for executives to make informed decisions about LLM integration and to continuously optimize their AI-powered services for maximum profitability. -Tools and agents are the components that provide the actual functionality to the swarms. They can be language models, AI assistants, vector stores, or any other components that can help in problem solving. +## 4. LLM Pricing in Action: Case Studies -To make the system plug-and-play, a standard interface should be defined for these components. Any new tool or agent should implement this interface, so that it can be easily plugged into the system. +To provide a concrete understanding of how LLM pricing models work in real-world scenarios, let's examine several case studies across different industries and use cases. These examples will illustrate the interplay between pricing models, usage patterns, and business outcomes. -## Usage +### Case Study 1: E-commerce Product Description Generator -Users can either use pre-configured swarms or create their own custom swarms. +**Company**: GlobalMart, a large online retailer +**Use Case**: Automated generation of product descriptions +**LLM Provider**: GPT-4o -To use a pre-configured swarm, they can simply instantiate the corresponding swarm class and call the run method with the required objective. +**Pricing Model**: Pay-per-token +- Input: $5.00 per 1M tokens +- Output: $15.00 per 1M tokens -To create a custom swarm, they need to: +**Usage Pattern**: +- Average input: 50 tokens per product (product attributes) +- Average output: 200 tokens per product (generated description) +- Daily products processed: 10,000 -1. Define a new swarm class inheriting from BaseSwarm. -2. Implement the required methods for the new swarm class. -3. Instantiate the swarm class and call the run method. +**Daily Cost Calculation**: +1. Input cost: (50 tokens * 10,000 products) / 1M * $5.00 = $2.50 +2. Output cost: (200 tokens * 10,000 products) / 1M * $15.00 = $30.00 +3. Total daily cost: $32.50 -### Example +**Business Impact**: +- Reduced time to market for new products by 70% +- Improved SEO performance due to unique, keyword-rich descriptions +- Estimated daily value generated: $500 (based on increased sales and efficiency) -```python -# Using pre-configured swarm -swarm = PreConfiguredSwarm(openai_api_key) -swarm.run_swarms(objective) +**ROI Analysis**: +- Daily investment: $32.50 +- Daily return: $500 +- ROI = (Return - Investment) / Investment * 100 = 1,438% -# Creating custom swarm -class CustomSwarm(BaseSwarm): - # Implement required methods +**Key Takeaway**: The pay-per-token model works well for this use case due to the predictable and moderate token usage per task. The high ROI justifies the investment in a more advanced model like GPT-4o. -swarm = CustomSwarm(openai_api_key) -swarm.run_swarms(objective) -``` +### Case Study 2: Customer Service Chatbot -## Conclusion +**Company**: TechSupport Inc., a software company +**Use Case**: 24/7 customer support chatbot +**LLM Provider**: Claude 3.5 Sonnet -This Swarm Architecture design provides a scalable and flexible system for building swarm intelligence models. The plug-and-play design allows users to easily use pre-configured swarms or create their own custom swarms. +**Pricing Model**: Input: $3 per 1M tokens, Output: $15 per 1M tokens +**Usage Pattern**: +- Average conversation: 500 tokens input (customer queries + context), 1000 tokens output (bot responses) +- Daily conversations: 5,000 -# Swarming Architectures -Sure, below are five different swarm architectures with their base requirements and an abstract class that processes these components: +**Daily Cost Calculation**: +1. Input cost: (500 tokens * 5,000 conversations) / 1M * $3 = $7.50 +2. Output cost: (1000 tokens * 5,000 conversations) / 1M * $15 = $75.00 +3. Total daily cost: $82.50 -1. **Hierarchical Swarm**: This architecture is characterized by a boss/worker relationship. The boss node takes high-level decisions and delegates tasks to the worker nodes. The worker nodes perform tasks and report back to the boss node. - - Requirements: Boss node (can be a large language model), worker nodes (can be smaller language models), and a task queue for task management. +**Business Impact**: +- Reduced customer wait times by 90% +- Resolved 70% of queries without human intervention +- Estimated daily cost savings: $2,000 (based on reduced human support hours) -2. **Homogeneous Swarm**: In this architecture, all nodes in the swarm are identical and contribute equally to problem-solving. Each node has the same capabilities. - - Requirements: Homogeneous nodes (can be language models of the same size), communication protocol for nodes to share information. +**ROI Analysis**: +- Daily investment: $82.50 +- Daily return: $2,000 +- ROI = (Return - Investment) / Investment * 100 = 2,324% -3. **Heterogeneous Swarm**: This architecture contains different types of nodes, each with its specific capabilities. This diversity can lead to more robust problem-solving. - - Requirements: Different types of nodes (can be different types and sizes of language models), a communication protocol, and a mechanism to delegate tasks based on node capabilities. +**Key Takeaway**: The higher cost of Claude 3.5 Sonnet is justified by its superior performance in handling complex customer queries, resulting in significant cost savings and improved customer satisfaction. -4. **Competitive Swarm**: In this architecture, nodes compete with each other to find the best solution. The system may use a selection process to choose the best solutions. - - Requirements: Nodes (can be language models), a scoring mechanism to evaluate node performance, a selection mechanism. +### Case Study 3: Financial Report Summarization -5. **Cooperative Swarm**: In this architecture, nodes work together and share information to find solutions. The focus is on cooperation rather than competition. - - Requirements: Nodes (can be language models), a communication protocol, a consensus mechanism to agree on solutions. +**Company**: FinAnalyze, a financial services firm +**Use Case**: Automated summarization of lengthy financial reports +**LLM Provider**: GPT-3.5 Turbo +**Pricing Model**: Input: $0.50 per 1M tokens, Output: $1.50 per 1M tokens -6. **Grid-based Swarm**: This architecture positions agents on a grid, where they can only interact with their neighbors. This is useful for simulations, especially in fields like ecology or epidemiology. - - Requirements: Agents (can be language models), a grid structure, and a neighborhood definition (i.e., how to identify neighboring agents). +**Usage Pattern**: +- Average report: 20,000 tokens input, 2,000 tokens output +- Daily reports processed: 100 -7. **Particle Swarm Optimization (PSO) Swarm**: In this architecture, each agent represents a potential solution to an optimization problem. Agents move in the solution space based on their own and their neighbors' past performance. PSO is especially useful for continuous numerical optimization problems. - - Requirements: Agents (each representing a solution), a definition of the solution space, an evaluation function to rate the solutions, a mechanism to adjust agent positions based on performance. +**Daily Cost Calculation**: +1. Input cost: (20,000 tokens * 100 reports) / 1M * $0.50 = $100 +2. Output cost: (2,000 tokens * 100 reports) / 1M * $1.50 = $30 +3. Total daily cost: $130 -8. **Ant Colony Optimization (ACO) Swarm**: Inspired by ant behavior, this architecture has agents leave a pheromone trail that other agents follow, reinforcing the best paths. It's useful for problems like the traveling salesperson problem. - - Requirements: Agents (can be language models), a representation of the problem space, a pheromone updating mechanism. +**Business Impact**: +- Reduced analysis time by 80% +- Improved consistency in report summaries +- Enabled analysts to focus on high-value tasks +- Estimated daily value generated: $1,000 (based on time savings and improved decision-making) -9. **Genetic Algorithm (GA) Swarm**: In this architecture, agents represent potential solutions to a problem. They can 'breed' to create new solutions and can undergo 'mutations'. GA swarms are good for search and optimization problems. - - Requirements: Agents (each representing a potential solution), a fitness function to evaluate solutions, a crossover mechanism to breed solutions, and a mutation mechanism. +**ROI Analysis**: +- Daily investment: $130 +- Daily return: $1,000 +- ROI = (Return - Investment) / Investment * 100 = 669% -10. **Stigmergy-based Swarm**: In this architecture, agents communicate indirectly by modifying the environment, and other agents react to such modifications. It's a decentralized method of coordinating tasks. - - Requirements: Agents (can be language models), an environment that agents can modify, a mechanism for agents to perceive environment changes. +**Key Takeaway**: The lower cost of GPT-3.5 Turbo is suitable for this task, which requires processing large volumes of text but doesn't necessarily need the most advanced language understanding. The high input token count makes the input pricing a significant factor in model selection. -These architectures all have unique features and requirements, but they share the need for agents (often implemented as language models) and a mechanism for agents to communicate or interact, whether it's directly through messages, indirectly through the environment, or implicitly through a shared solution space. Some also require specific data structures, like a grid or problem space, and specific algorithms, like for evaluating solutions or updating agent positions. +### Case Study 4: AI-Powered Language Learning App +**Company**: LinguaLeap, an edtech startup +**Use Case**: Personalized language exercises and conversations +**LLM Provider**: Claude 3 Haiku --------------------------------------------------- +**Pricing Model**: Input: $0.25 per 1M tokens, Output: $1.25 per 1M tokens -# File: corporate/distribution.md +**Usage Pattern**: +- Average session: 300 tokens input (user responses + context), 500 tokens output (exercises + feedback) +- Daily active users: 50,000 +- Average sessions per user per day: 3 +**Daily Cost Calculation**: +1. Input cost: (300 tokens * 3 sessions * 50,000 users) / 1M * $0.25 = $11.25 +2. Output cost: (500 tokens * 3 sessions * 50,000 users) / 1M * $1.25 = $93.75 +3. Total daily cost: $105 +**Business Impact**: +- Increased user engagement by 40% +- Improved learning outcomes, leading to higher user retention +- Enabled scaling to new languages without proportional increase in human tutors +- Estimated daily revenue: $5,000 (based on subscription fees and in-app purchases) -# Swarms Monetization Strategy +**ROI Analysis**: +- Daily investment: $105 +- Daily revenue: $5,000 +- ROI = (Revenue - Investment) / Investment * 100 = 4,662% -This strategy includes a variety of business models, potential revenue streams, cashflow structures, and customer identification methods. Let's explore these further. +**Key Takeaway**: The high-volume, relatively simple interactions in this use case make Claude 3 Haiku an excellent choice. Its low cost allows for frequent interactions without prohibitive expenses, which is crucial for an app relying on regular user engagement. -## Business Models +### Case Study 5: Legal Document Analysis -1. **Platform as a Service (PaaS):** Provide the Swarms AI platform on a subscription basis, charged monthly or annually. This could be tiered based on usage and access to premium features. +**Company**: LegalEagle LLP, a large law firm +**Use Case**: Contract review and risk assessment +**LLM Provider**: Claude 3 Opus -2. **API Usage-based Pricing:** Charge customers based on their usage of the Swarms API. The more requests made, the higher the fee. +**Pricing Model**: Input: $15 per 1M tokens, Output: $75 per 1M tokens -3. **Managed Services:** Offer complete end-to-end solutions where you manage the entire AI infrastructure for the clients. This could be on a contract basis with a recurring fee. +**Usage Pattern**: +- Average contract: 10,000 tokens input, 3,000 tokens output (analysis and risk assessment) +- Daily contracts processed: 50 -4. **Training and Certification:** Provide Swarms AI training and certification programs for interested developers and businesses. These could be monetized as separate courses or subscription-based access. +**Daily Cost Calculation**: +1. Input cost: (10,000 tokens * 50 contracts) / 1M * $15 = $7.50 +2. Output cost: (3,000 tokens * 50 contracts) / 1M * $75 = $11.25 +3. Total daily cost: $18.75 -5. **Partnerships:** Collaborate with large enterprises and offer them dedicated Swarm AI services. These could be performance-based contracts, ensuring a mutually beneficial relationship. +**Business Impact**: +- Reduced contract review time by 60% +- Improved accuracy in identifying potential risks +- Enabled handling of more complex cases +- Estimated daily value: $10,000 (based on time savings and improved risk management) -6. **Data as a Service (DaaS):** Leverage the data generated by Swarms for insights and analytics, providing valuable business intelligence to clients. +**ROI Analysis**: +- Daily investment: $18.75 +- Daily value: $10,000 +- ROI = (Value - Investment) / Investment * 100 = 53,233% -## Potential Revenue Streams +**Key Takeaway**: Despite the high cost per token, Claude 3 Opus's advanced capabilities justify its use in this high-stakes environment where accuracy and nuanced understanding are critical. The high value generated per task offsets the higher token costs. -1. **Subscription Fees:** This would be the main revenue stream from providing the Swarms platform as a service. +These case studies demonstrate how different LLM providers and pricing models can be optimal for various use cases, depending on factors such as token volume, task complexity, and the value generated by the AI application. Executives should carefully consider these factors when selecting an LLM provider and pricing model for their specific needs. -2. **Usage Fees:** Additional revenue can come from usage fees for businesses that have high demand for Swarms API. +## 5. Calculating ROI for LLM Integration -3. **Contract Fees:** From offering managed services and bespoke solutions to businesses. +Calculating the Return on Investment (ROI) for LLM integration is crucial for executives to justify the expenditure and assess the business value of AI implementation. This section will guide you through the process of calculating ROI, considering both tangible and intangible benefits. -4. **Training Fees:** Revenue from providing training and certification programs to developers and businesses. +### The ROI Formula -5. **Partnership Contracts:** Large-scale projects with enterprises, involving dedicated Swarm AI services, could provide substantial income. +The basic ROI formula is: -6. **Data Insights:** Revenue from selling valuable business intelligence derived from Swarm's aggregated and anonymized data. +``` +ROI = (Net Benefit / Cost of Investment) * 100 +``` -## Potential Customers +For LLM integration, we can expand this to: -1. **Businesses Across Sectors:** Any business seeking to leverage AI for automation, efficiency, and data insights could be a potential customer. This includes sectors like finance, eCommerce, logistics, healthcare, and more. +``` +ROI = ((Total Benefits - Total Costs) / Total Costs) * 100 +``` -2. **Developers:** Both freelance and those working in organizations could use Swarms to enhance their projects and services. +### Identifying Benefits -3. **Enterprises:** Large enterprises looking to automate and optimize their operations could greatly benefit from Swarms. +1. **Direct Cost Savings** + - Reduced labor costs + - Decreased operational expenses + - Lower error-related costs -4. **Educational Institutions:** Universities and research institutions could leverage Swarms for research and teaching purposes. +2. **Revenue Increases** + - New product offerings enabled by LLM + - Improved customer acquisition and retention + - Upselling and cross-selling opportunities -## Roadmap +3. **Productivity Gains** + - Time saved on repetitive tasks + - Faster decision-making processes + - Improved employee efficiency -1. **Landing Page Creation:** Develop a dedicated product page on apac.ai for Swarms. +4. **Quality Improvements** + - Enhanced accuracy in outputs + - Consistency in service delivery + - Reduced error rates -2. **Hosted Swarms API:** Launch a cloud-based Swarms API service. It should be highly reliable, with robust documentation to attract daily users. +5. **Strategic Advantages** + - Market differentiation + - Faster time-to-market for new offerings + - Improved competitive positioning -3. **Consumer and Enterprise Subscription Service:** Launch a comprehensive subscription service on The Domain. This would provide users with access to a wide array of APIs and data streams. +### Calculating Costs -4. **Dedicated Capacity Deals:** Partner with large enterprises to offer them dedicated Swarm AI solutions for automating their operations. +1. **Direct LLM Costs** + - API usage fees + - Subscription costs -5. **Enterprise Partnerships:** Develop partnerships with large enterprises for extensive contract-based projects. +2. **Infrastructure Costs** + - Cloud computing resources + - Data storage + - Networking expenses -6. **Integration with Collaboration Platforms:** Develop Swarms bots for platforms like Discord and Slack, charging users a subscription fee for access. +3. **Integration and Development Costs** + - Initial setup and integration + - Ongoing maintenance and updates + - Custom feature development -7. **Personal Data Instances:** Offer users dedicated instances of all their data that the Swarm can query as needed. +4. **Training and Support** + - Employee training programs + - User support and documentation + - Change management initiatives -8. **Browser Extension:** Develop a browser extension that integrates with the Swarms platform, offering users a more seamless experience. +5. **Compliance and Security** + - Data privacy measures + - Security audits and implementations + - Regulatory compliance efforts -Remember, customer satisfaction and a value-centric approach are at the core of any successful monetization strategy. It's essential to continuously iterate and improve the product based on customer feedback and evolving market needs. +### Step-by-Step ROI Calculation ----- +1. **Define the Time Period**: Determine the timeframe for your ROI calculation (e.g., 1 year, 3 years). -# Other ideas +2. **Estimate Total Benefits**: + - Quantify direct cost savings and revenue increases + - Assign monetary values to productivity gains and quality improvements + - Estimate the value of strategic advantages (this may be more subjective) -1. **Platform as a Service (PaaS):** Create a cloud-based platform that allows users to build, run, and manage applications without the complexity of maintaining the infrastructure. You could charge users a subscription fee for access to the platform and provide different pricing tiers based on usage levels. This could be an attractive solution for businesses that do not have the capacity to build or maintain their own swarm intelligence solutions. +3. **Calculate Total Costs**: + - Sum up all direct and indirect costs related to LLM integration -2. **Professional Services:** Offer consultancy and implementation services to businesses looking to utilize the Swarm technology. This could include assisting with integration into existing systems, offering custom development services, or helping customers to build specific solutions using the framework. +4. **Apply the ROI Formula**: + ``` + ROI = ((Total Benefits - Total Costs) / Total Costs) * 100 + ``` -3. **Education and Training:** Create a certification program for developers or companies looking to become proficient with the Swarms framework. This could be sold as standalone courses, or bundled with other services. +5. **Consider Time Value of Money**: For longer-term projections, use Net Present Value (NPV) to account for the time value of money. -4. **Managed Services:** Some companies may prefer to outsource the management of their Swarm-based systems. A managed services solution could take care of all the technical aspects, from hosting the solution to ensuring it runs smoothly, allowing the customer to focus on their core business. +### Example ROI Calculation -5. **Data Analysis and Insights:** Swarm intelligence can generate valuable data and insights. By anonymizing and aggregating this data, you could provide industry reports, trend analysis, and other valuable insights to businesses. +Let's consider a hypothetical customer service chatbot implementation: -As for the type of platform, Swarms can be offered as a cloud-based solution given its scalability and flexibility. This would also allow you to apply a SaaS/PaaS type monetization model, which provides recurring revenue. +**Time Period**: 1 year -Potential customers could range from small to large enterprises in various sectors such as logistics, eCommerce, finance, and technology, who are interested in leveraging artificial intelligence and machine learning for complex problem solving, optimization, and decision-making. +**Benefits**: +- Labor cost savings: $500,000 +- Increased sales from improved customer satisfaction: $300,000 +- Productivity gains from faster query resolution: $200,000 -**Product Brief Monetization Strategy:** +Total Benefits: $1,000,000 -Product Name: Swarms.AI Platform +**Costs**: +- LLM API fees: $100,000 +- Integration and development: $150,000 +- Training and support: $50,000 +- Infrastructure: $50,000 -Product Description: A cloud-based AI and ML platform harnessing the power of swarm intelligence. +Total Costs: $350,000 -1. **Platform as a Service (PaaS):** Offer tiered subscription plans (Basic, Premium, Enterprise) to accommodate different usage levels and business sizes. +**ROI Calculation**: +``` +ROI = (($1,000,000 - $350,000) / $350,000) * 100 = 185.7% +``` -2. **Professional Services:** Offer consultancy and custom development services to tailor the Swarms solution to the specific needs of the business. +This indicates a strong positive return on investment, with benefits outweighing costs by a significant margin. -3. **Education and Training:** Launch an online Swarms.AI Academy with courses and certifications for developers and businesses. +### Considerations for Accurate ROI Calculation -4. **Managed Services:** Provide a premium, fully-managed service offering that includes hosting, maintenance, and 24/7 support. +1. **Be Conservative in Estimates**: It's better to underestimate benefits and overestimate costs to provide a more realistic view. -5. **Data Analysis and Insights:** Offer industry reports and customized insights generated from aggregated and anonymized Swarm data. +2. **Account for Ramp-Up Time**: Full benefits may not be realized immediately. Consider a phased approach in your calculations. -Potential Customers: Enterprises in sectors such as logistics, eCommerce, finance, and technology. This can be sold globally, provided there's an internet connection. +3. **Include Opportunity Costs**: Consider the potential returns if the investment were made elsewhere. -Marketing Channels: Online marketing (SEO, Content Marketing, Social Media), Partnerships with tech companies, Direct Sales to Enterprises. +4. **Factor in Risk**: Adjust your ROI based on the likelihood of achieving projected benefits. -This strategy is designed to provide multiple revenue streams, while ensuring the Swarms.AI platform is accessible and useful to a range of potential customers. +5. **Consider Non-Financial Benefits**: Some benefits, like improved employee satisfaction or enhanced brand perception, may not have direct financial equivalents but are still valuable. -1. **AI Solution as a Service:** By offering the Swarms framework as a service, businesses can access and utilize the power of multiple LLM agents without the need to maintain the infrastructure themselves. Subscription can be tiered based on usage and additional features. +6. **Perform Sensitivity Analysis**: Calculate ROI under different scenarios (best case, worst case, most likely) to understand the range of possible outcomes. -2. **Integration and Custom Development:** Offer integration services to businesses wanting to incorporate the Swarms framework into their existing systems. Also, you could provide custom development for businesses with specific needs not met by the standard framework. +7. **Benchmark Against Alternatives**: Compare the ROI of LLM integration against other potential investments or solutions. -3. **Training and Certification:** Develop an educational platform offering courses, webinars, and certifications on using the Swarms framework. This can serve both developers seeking to broaden their skills and businesses aiming to train their in-house teams. +### Long-Term ROI Considerations -4. **Managed Swarms Solutions:** For businesses that prefer to outsource their AI needs, provide a complete solution which includes the development, maintenance, and continuous improvement of swarms-based applications. +While initial ROI calculations are crucial for decision-making, it's important to consider long-term implications: -5. **Data Analytics Services:** Leveraging the aggregated insights from the AI swarms, you could offer data analytics services. Businesses can use these insights to make informed decisions and predictions. +1. **Scalability**: How will ROI change as usage increases? +2. **Technological Advancements**: Will newer, more efficient models become available? +3. **Market Changes**: How might shifts in the competitive landscape affect the value proposition? +4. **Regulatory Environment**: Could future regulations impact the cost or feasibility of LLM use? -**Type of Platform:** +By thoroughly calculating and analyzing the ROI of LLM integration, executives can make data-driven decisions about AI investments and set realistic expectations for the value these technologies can bring to their organizations. -Cloud-based platform or Software as a Service (SaaS) will be a suitable model. It offers accessibility, scalability, and ease of updates. +## 6. Comparative Analysis of Major LLM Providers -**Target Customers:** +In this section, we'll compare the offerings of major LLM providers, focusing on their pricing structures, model capabilities, and unique selling points. This analysis will help executives understand the landscape and make informed decisions about which provider best suits their needs. -The technology can be beneficial for businesses across sectors like eCommerce, technology, logistics, finance, healthcare, and education, among others. +### OpenAI -**Product Brief Monetization Strategy:** +**Models**: GPT-4o, GPT-3.5 Turbo -Product Name: Swarms.AI +**Pricing Structure**: +- Pay-per-token model +- Different rates for input and output tokens +- Bulk discounts available for high-volume users -1. **AI Solution as a Service:** Offer different tiered subscriptions (Standard, Premium, and Enterprise) each with varying levels of usage and features. +**Key Features**: +- State-of-the-art performance on a wide range of tasks +- Regular model updates and improvements +- Extensive documentation and community support -2. **Integration and Custom Development:** Offer custom development and integration services, priced based on the scope and complexity of the project. +**Considerations**: +- Higher pricing compared to some competitors +- Potential for rapid price changes as technology evolves +- Usage limits and approval process for higher-tier models -3. **Training and Certification:** Launch the Swarms.AI Academy with courses and certifications, available for a fee. +### Anthropic -4. **Managed Swarms Solutions:** Offer fully managed solutions tailored to business needs, priced based on scope and service level agreements. +**Models**: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku -5. **Data Analytics Services:** Provide insightful reports and data analyses, which can be purchased on a one-off basis or through a subscription. +**Pricing Structure**: +- Pay-per-token model +- Different rates for input and output tokens +- Tiered pricing based on model capabilities -By offering a variety of services and payment models, Swarms.AI will be able to cater to a diverse range of business needs, from small start-ups to large enterprises. Marketing channels would include digital marketing, partnerships with technology companies, presence in tech events, and direct sales to targeted industries. +**Key Features**: +- Strong focus on AI safety and ethics +- Long context windows (200K tokens) +- Specialized models for different use cases (e.g., Haiku for speed, Opus for complex tasks) +**Considerations**: +- Newer to the market compared to OpenAI +- Potentially more limited third-party integrations +- Strong emphasis on responsible AI use +### Google (Vertex AI) -# Roadmap +**Models**: PaLM 2 for Chat, PaLM 2 for Text -* Create a landing page for swarms apac.ai/product/swarms +**Pricing Structure**: +- Pay-per-thousand characters model +- Different rates for input and output +- Additional charges for advanced features (e.g., semantic retrieval) -* Create Hosted Swarms API for anybody to just use without need for mega gpu infra, charge usage based pricing. Prerequisites for success => Swarms has to be extremely reliable + we need world class documentation and many daily users => how do we get many daily users? We provide a seamless and fluid experience, how do we create a seamless and fluid experience? We write good code that is modular, provides feedback to the user in times of distress, and ultimately accomplishes the user's tasks. +**Key Features**: +- Integration with Google Cloud ecosystem +- Multi-modal capabilities (text, image, audio) +- Enterprise-grade security and compliance features -* Hosted consumer and enterprise subscription as a service on The Domain, where users can interact with 1000s of APIs and ingest 1000s of different data streams. +**Considerations**: +- Pricing can be complex due to additional Google Cloud costs +- Strong performance in specialized domains (e.g., coding, mathematical reasoning) +- Potential for integration with other Google services -* Hosted dedicated capacity deals with mega enterprises on automating many operations with Swarms for monthly subscription 300,000+$ +### Amazon (Bedrock) -* Partnerships with enterprises, massive contracts with performance based fee +**Models**: Claude (Anthropic), Titan -* Have discord bot and or slack bot with users personal data, charge subscription + browser extension +**Pricing Structure**: +- Pay-per-second of compute time +- Additional charges for data transfer and storage -* each user gets a dedicated ocean instance of all their data so the swarm can query it as needed. +**Key Features**: +- Seamless integration with AWS services +- Access to multiple model providers through a single API +- Fine-tuning and customization options +**Considerations**: +- Pricing model can be less predictable for inconsistent workloads +- Strong appeal for existing AWS customers +- Potential for cost optimizations through AWS ecosystem +### Microsoft (Azure OpenAI Service) +**Models**: GPT-4, GPT-3.5 Turbo ---- ---- +**Pricing Structure**: +- Similar to OpenAI's pricing, but with Azure integration +- Additional costs for Azure services (e.g., storage, networking) +**Key Features**: +- Enterprise-grade security and compliance +- Integration with Azure AI services +- Access to fine-tuning and customization options -# Swarms Monetization Strategy: A Revolutionary AI-powered Future +**Considerations**: +- Attractive for organizations already using Azure +- Potential for volume discounts through Microsoft Enterprise Agreements +- Additional overhead for Azure management -Swarms is a powerful AI platform leveraging the transformative potential of Swarm Intelligence. Our ambition is to monetize this groundbreaking technology in ways that generate significant cashflow while providing extraordinary value to our customers. +### Comparative Analysis -Here we outline our strategic monetization pathways and provide a roadmap that plots our course to future success. +| Provider | Pricing Model | Strengths | Considerations | +|----------|---------------|-----------|----------------| +| OpenAI | Pay-per-token | - Top performance
- Regular updates
- Strong community | - Higher costs
- Usage limits | +| Anthropic| Pay-per-token | - Ethical focus
- Long context
- Specialized models | - Newer provider
- Limited integrations | +| Google | Pay-per-character | - Google Cloud integration
- Multi-modal
- Enterprise features | - Complex pricing
- Google ecosystem lock-in | +| Amazon | Pay-per-compute time | - AWS integration
- Multiple providers
- Customization options | - Less predictable costs
- AWS ecosystem focus | +| Microsoft| Pay-per-token (Azure-based) | - Enterprise security
- Azure integration
- Fine-tuning options | - Azure overhead
- Potential lock-in | ---- +### Factors to Consider in Provider Selection -## I. Business Models +1. **Performance Requirements**: Assess whether you need state-of-the-art performance or if a less advanced (and potentially cheaper) model suffices. -1. **Platform as a Service (PaaS):** We provide the Swarms platform as a service, billed on a monthly or annual basis. Subscriptions can range from $50 for basic access, to $500+ for premium features and extensive usage. +2. **Pricing Predictability**: Consider whether your usage patterns align better with token-based or compute-time-based pricing. -2. **API Usage-based Pricing:** Customers are billed according to their use of the Swarms API. Starting at $0.01 per request, this creates a cashflow model that rewards extensive platform usage. +3. **Integration Needs**: Evaluate how well each provider integrates with your existing technology stack. -3. **Managed Services:** We offer end-to-end solutions, managing clients' entire AI infrastructure. Contract fees start from $100,000 per month, offering both a sustainable cashflow and considerable savings for our clients. +4. **Scalability**: Assess each provider's ability to handle your expected growth in usage. -4. **Training and Certification:** A Swarms AI training and certification program is available for developers and businesses. Course costs can range from $200 to $2,000, depending on course complexity and duration. +5. **Customization Options**: Determine if you need fine-tuning or specialized model development capabilities. -5. **Partnerships:** We forge collaborations with large enterprises, offering dedicated Swarm AI services. These performance-based contracts start from $1,000,000, creating a potentially lucrative cashflow stream. +6. **Compliance and Security**: Consider your industry-specific regulatory requirements and each provider's security offerings. -6. **Data as a Service (DaaS):** Swarms generated data are mined for insights and analytics, with business intelligence reports offered from $500 each. +7. **Support and Documentation**: Evaluate the quality of documentation, community support, and enterprise-level assistance. ---- +8. **Ethical Considerations**: Assess each provider's stance on AI ethics and responsible use. -## II. Potential Revenue Streams +9. **Lock-In Concerns**: Consider the long-term implications of committing to a specific provider or cloud ecosystem. -1. **Subscription Fees:** From $50 to $500+ per month for platform access. +10. **Multi-Provider Strategy**: Evaluate the feasibility and benefits of using multiple providers for different use cases. -2. **Usage Fees:** From $0.01 per API request, generating income from high platform usage. +By carefully comparing these providers and considering the factors most relevant to your organization, you can make an informed decision that balances cost, performance, and strategic fit. Remember that the LLM landscape is rapidly evolving, so it's important to regularly reassess your choices and stay informed about new developments and pricing changes. -3. **Contract Fees:** Starting from $100,000 per month for managed services. +## 7. Hidden Costs and Considerations -4. **Training Fees:** From $200 to $2,000 for individual courses or subscription access. +When evaluating LLM providers and calculating the total cost of ownership, it's crucial to look beyond the advertised pricing and consider the hidden costs and additional factors that can significantly impact your budget and overall implementation success. This section explores these often-overlooked aspects to help executives make more comprehensive and accurate assessments. -5. **Partnership Contracts:** Contracts starting from $100,000, offering major income potential. +### 1. Data Preparation and Cleaning -6. **Data Insights:** Business intelligence reports starting from $500. +**Considerations**: +- Cost of data collection and aggregation +- Expenses related to data cleaning and normalization +- Ongoing data maintenance and updates ---- +**Impact**: +- Can be time-consuming and labor-intensive +- May require specialized tools or personnel +- Critical for model performance and accuracy -## III. Potential Customers +### 2. Fine-Tuning and Customization -1. **Businesses Across Sectors:** Our offerings cater to businesses across finance, eCommerce, logistics, healthcare, and more. +**Considerations**: +- Costs associated with creating custom datasets +- Compute resources required for fine-tuning +- Potential need for specialized ML expertise -2. **Developers:** Both freelancers and organization-based developers can leverage Swarms for their projects. +**Impact**: +- Can significantly improve model performance for specific tasks +- May lead to better ROI in the long run +- Increases initial implementation costs -3. **Enterprises:** Swarms offers large enterprises solutions for optimizing operations. +### 3. Integration and Development -4. **Educational Institutions:** Universities and research institutions can use Swarms for research and teaching. +**Considerations**: +- Engineering time for API integration +- Development of custom interfaces or applications +- Ongoing maintenance and updates ---- +**Impact**: +- Can be substantial, especially for complex integrations +- May require hiring additional developers or consultants +- Critical for seamless user experience and workflow integration -## IV. Roadmap +### 4. Monitoring and Optimization -1. **Landing Page Creation:** Develop a dedicated Swarms product page on apac.ai. +**Considerations**: +- Tools and systems for performance monitoring +- Regular audits and optimizations +- Costs associated with debugging and troubleshooting -2. **Hosted Swarms API:** Launch a reliable, well-documented cloud-based Swarms API service. +**Impact**: +- Ongoing expense that increases with scale +- Essential for maintaining efficiency and cost-effectiveness +- Can lead to significant savings through optimized usage -3. **Consumer and Enterprise Subscription Service:** Launch an extensive subscription service on The Domain, providing wide-ranging access to APIs and data streams. +### 5. Compliance and Security -4. **Dedicated Capacity Deals:** Offer large enterprises dedicated Swarm AI solutions, starting from $300,000 monthly subscription. +**Considerations**: +- Legal counsel for data privacy and AI regulations +- Implementation of security measures (e.g., encryption, access controls) +- Regular audits and certifications -5. **Enterprise Partnerships:** Develop performance-based contracts with large enterprises. +**Impact**: +- Can be substantial, especially in heavily regulated industries +- Critical for risk management and maintaining customer trust +- May limit certain use cases or require additional safeguards -6. **Integration with Collaboration Platforms:** Develop Swarms bots for platforms like Discord and Slack, charging a subscription fee for access. +### 6. Training and Change Management -7. **Personal Data Instances:** Offer users dedicated data instances that the Swarm can query as needed. +- Employee training programs +- Development of user guides and documentation +- Change management initiatives -8. **Browser Extension:** Develop a browser extension that integrates with the Swarms platform for seamless user experience. +**Impact**: +- Often underestimated but crucial for adoption +- Can affect productivity during the transition period +- Important for realizing the full potential of LLM integration ---- +### 7. Scaling Costs -Our North Star remains customer satisfaction and value provision. -As we embark on this journey, we continuously refine our product based on customer feedback and evolving market needs, ensuring we lead in the age of AI-driven solutions. +**Considerations**: +- Potential price increases as usage grows +- Need for additional infrastructure or resources +- Costs associated with managing increased complexity -## **Platform Distribution Strategy for Swarms** +**Impact**: +- Can lead to unexpected expenses if not properly forecasted +- May require renegotiation of contracts or switching providers +- Important to consider in long-term planning -*Note: This strategy aims to diversify the presence of 'Swarms' across various platforms and mediums while focusing on monetization and value creation for its users. +### 8. Opportunity Costs ---- +**Considerations**: +- Time and resources diverted from other projects +- Potential missed opportunities due to focus on LLM implementation +- Learning curve and productivity dips during adoption -### **1. Framework:** +**Impact**: +- Difficult to quantify but important to consider +- Can affect overall business strategy and priorities +- May influence timing and scope of LLM integration -#### **Objective:** -To offer Swarms as an integrated solution within popular frameworks to ensure that developers and businesses can seamlessly incorporate its functionalities. +### 9. Vendor Lock-in -#### **Strategy:** +**Considerations**: +- Costs associated with switching providers +- Dependency on provider-specific features or integrations +- Potential for price increases once deeply integrated -* **Language/Framework Integration:** - * Target popular frameworks like Django, Flask for Python, Express.js for Node, etc. - * Create SDKs or plugins for easy integration. +**Impact**: +- Can limit flexibility and negotiating power +- May affect long-term costs and strategic decisions +- Important to consider multi-provider or portable implementation strategies -* **Monetization:** - * Freemium Model: Offer basic integration for free, and charge for additional features or advanced integrations. - * Licensing: Allow businesses to purchase licenses for enterprise-level integrations. +### 10. Ethical and Reputational Considerations -* **Promotion:** - * Engage in partnerships with popular online coding platforms like Udemy, Coursera, etc., offering courses and tutorials on integrating Swarms. - * Host webinars and write technical blogs to promote the integration benefits. +**Considerations**: +- Potential backlash from AI-related controversies +- Costs of ensuring ethical AI use and transparency +- Investments in responsible AI practices ---- +**Impact**: +- Can affect brand reputation and customer trust +- May require ongoing public relations efforts +- Important for long-term sustainability and social responsibility -### **2. Paid API:** +By carefully considering these hidden costs and factors, executives can develop a more comprehensive understanding of the total investment required for successful LLM integration. This holistic approach allows for better budgeting, risk management, and strategic planning. -#### **Objective:** -To provide a scalable solution for developers and businesses that want direct access to Swarms' functionalities without integrating the entire framework. +## Conclusion: Navigating the LLM Pricing Landscape -#### **Strategy:** +As we've explored throughout this guide, the landscape of LLM provider pricing is complex and multifaceted. From understanding the basic pricing models to calculating ROI and considering hidden costs, there are numerous factors that executives must weigh when making decisions about AI integration. -* **API Endpoints:** - * Offer various endpoints catering to different functionalities. - * Maintain robust documentation to ensure ease of use. +Key takeaways include: -* **Monetization:** - * Usage-based Pricing: Charge based on the number of API calls. - * Subscription Tiers: Provide tiered packages based on usage limits and advanced features. +1. The importance of aligning LLM selection with specific business needs and use cases. +2. The need for thorough ROI analysis that goes beyond simple cost calculations. +3. The value of considering both short-term implementation costs and long-term scalability. +4. The critical role of hidden costs in determining the true total cost of ownership. +5. The potential for significant business value when LLMs are strategically implemented and optimized. -* **Promotion:** - * List on API marketplaces like RapidAPI. - * Engage in SEO to make the API documentation discoverable. +As the AI landscape continues to evolve rapidly, staying informed and adaptable is crucial. What may be the best choice today could change as new models are released, pricing structures shift, and your organization's needs evolve. ---- +To help you navigate these complexities and make the most informed decisions for your enterprise, we invite you to take the next steps in your AI journey: -### **3. Domain Hosted:** +1. **Book a Consultation**: Speak with our enterprise-grade LLM specialists who can provide personalized insights and recommendations tailored to your specific needs. Schedule a 15-minute call at [https://cal.com/swarms/15min](https://cal.com/swarms/15min). -#### **Objective:** -To provide a centralized web platform where users can directly access and engage with Swarms' offerings. +2. **Join Our Community**: Connect with fellow AI executives, share experiences, and stay updated on the latest developments in the LLM space. Join our Discord community at [https://discord.gg/yxU9t9da](https://discord.gg/yxU9t9da). -#### **Strategy:** +By leveraging expert guidance and peer insights, you can position your organization to make the most of LLM technologies while optimizing costs and maximizing value. The future of AI in enterprise is bright, and with the right approach, your organization can be at the forefront of this transformative technology. -* **User-Friendly Interface:** - * Ensure a seamless user experience with intuitive design. - * Incorporate features like real-time chat support, tutorials, and an FAQ section. +-------------------------------------------------- -* **Monetization:** - * Subscription Model: Offer monthly/annual subscriptions for premium features. - * Affiliate Marketing: Partner with related tech products/services and earn through referrals. +# File: index.md -* **Promotion:** - * Invest in PPC advertising on platforms like Google Ads. - * Engage in content marketing, targeting keywords related to Swarms' offerings. +# Welcome to Swarms Docs Home ---- +[![Join our Discord](https://img.shields.io/badge/Discord-Join%20our%20server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/jM3Z6M9uMq) [![Subscribe on YouTube](https://img.shields.io/badge/YouTube-Subscribe-red?style=for-the-badge&logo=youtube&logoColor=white)](https://www.youtube.com/@kyegomez3242) [![Connect on LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-blue?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/kye-g-38759a207/) [![Follow on X.com](https://img.shields.io/badge/X.com-Follow-1DA1F2?style=for-the-badge&logo=x&logoColor=white)](https://x.com/swarms_corp) -### **4. Build Your Own (No-Code Platform):** +## What is Swarms? -#### **Objective:** -To cater to the non-developer audience, allowing them to leverage Swarms' features without any coding expertise. +**Swarms** is the **first and most reliable multi-agent production-grade framework** designed to orchestrate intelligent AI agents at scale. Built for enterprise applications, Swarms enables you to create sophisticated multi-agent systems that can handle complex tasks through collaboration, parallel processing, and intelligent task distribution. -#### **Strategy:** +### Key Capabilities -* **Drag-and-Drop Interface:** - * Offer customizable templates. - * Ensure integration with popular platforms and apps. +- **🏢 Production-Ready**: Enterprise-grade infrastructure with high reliability, comprehensive logging, and robust error handling +- **🤖 Multi-Agent Orchestration**: Support for hierarchical swarms, parallel processing, sequential workflows, and dynamic agent rearrangement +- **🔄 Flexible Integration**: Multi-model support, custom agent creation, extensive tool library, and multiple memory systems +- **📈 Scalable Architecture**: Concurrent processing, resource management, load balancing, and horizontal scaling capabilities +- **🛠️ Developer-Friendly**: Simple API, extensive documentation, active community, and CLI tools for rapid development +- **🔐 Enterprise Security**: Built-in error handling, rate limiting, monitoring integration, and audit logging -* **Monetization:** - * Freemium Model: Offer basic features for free, and charge for advanced functionalities. - * Marketplace for Plugins: Allow third-party developers to sell their plugins/extensions on the platform. +### Why Choose Swarms? -* **Promotion:** - * Partner with no-code communities and influencers. - * Offer promotions and discounts to early adopters. +Swarms stands out as the **most reliable multi-agent framework** because it was built from the ground up for production environments. Unlike other frameworks that focus on research or simple demos, Swarms provides the infrastructure, tooling, and best practices needed to deploy multi-agent systems in real-world applications. ---- +Whether you're building financial analysis systems, healthcare diagnostics, manufacturing optimization, or any other complex multi-agent application, Swarms provides the foundation you need to succeed. -### **5. Marketplace for the No-Code Platform:** +## Swarms Installation -#### **Objective:** -To create an ecosystem where third-party developers can contribute, and users can enhance their Swarms experience. +```bash +pip3 install swarms +``` -#### **Strategy:** +## Update Swarms -* **Open API for Development:** - * Offer robust documentation and developer support. - * Ensure a strict quality check for marketplace additions. -* **Monetization:** - * Revenue Sharing: Take a percentage cut from third-party sales. - * Featured Listings: Charge developers for premium listings. +```bash +pip3 install -U swarms +``` -* **Promotion:** - * Host hackathons and competitions to boost developer engagement. - * Promote top plugins/extensions through email marketing and on the main platform. +### **Get Started Building Production-Grade Multi-Agent Applications** ---- +## Onboarding -### **Future Outlook & Expansion:** +| Section | Links | +|----------------------|--------------------------------------------------------------------------------------------| +| Installation | [Installation](https://docs.swarms.world/en/latest/swarms/install/install/) | +| Quickstart | [Get Started](https://docs.swarms.world/en/latest/swarms/install/quickstart/) | +| Environment Setup | [Environment Configuration](https://docs.swarms.world/en/latest/swarms/install/workspace_manager/) | +| Environment Variables | [Environment Variables](https://docs.swarms.world/en/latest/swarms/install/env/) | +| Swarms CLI | [CLI Documentation](https://docs.swarms.world/en/latest/swarms/cli/main/) | +| Agent Internal Mechanisms | [Agent Architecture](https://docs.swarms.world/en/latest/swarms/framework/agents_explained/) | +| Agent API | [Agent API](https://docs.swarms.world/en/latest/swarms/structs/agent/) | +| Managing Prompts in Production | [Prompts Management](https://docs.swarms.world/en/latest/swarms/prompts/main/) | +| Integrating External Agents | [External Agents Integration](https://docs.swarms.world/en/latest/swarms/agents/external_party_agents/) | +| Creating Agents from YAML | [YAML Agent Creation](https://docs.swarms.world/en/latest/swarms/agents/create_agents_yaml/) | +| Why You Need Swarms | [Why MultiAgent Collaboration](https://docs.swarms.world/en/latest/swarms/concept/why/) | +| Swarm Architectures Analysis | [Swarm Architectures](https://docs.swarms.world/en/latest/swarms/concept/swarm_architectures/) | +| Choosing the Right Swarm | [How to Choose Swarms](https://docs.swarms.world/en/latest/swarms/concept/how_to_choose_swarms/) | +| Full API Reference | [API Reference](https://docs.swarms.world/en/latest/swarms/framework/reference/) | +| AgentRearrange Docs | [AgentRearrange](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/) | -* **Hosted Dedicated Capacity:** Hosted dedicated capacity deals for enterprises starting at 399,999$ -* **Decentralized Free Peer to peer endpoint hosted on The Grid:** Hosted endpoint by the people for the people. -* **Browser Extenision:** Athena browser extension for deep browser automation, subscription, usage, +## Ecosystem -* **Mobile Application:** Develop a mobile app version for Swarms to tap into the vast mobile user base. -* **Global Expansion:** Localize the platform for non-English speaking regions to tap into global markets. -* **Continuous Learning:** Regularly collect user feedback and iterate on the product features. +Here you'll find references about the Swarms framework, marketplace, community, and more to enable you to build your multi-agent applications. ---- +| Section | Links | +|----------------------|--------------------------------------------------------------------------------------------| +| Swarms Python Framework Docs | [Framework Docs](https://docs.swarms.world/en/latest/swarms/install/install/) | +| Swarms Cloud API | [Cloud API](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/) | +| Swarms Marketplace API | [Marketplace API](https://docs.swarms.world/en/latest/swarms_platform/) | +| Swarms Memory Systems | [Memory Systems](https://docs.swarms.world/en/latest/swarms_memory/) | +| Available Models | [Models Overview](https://docs.swarms.world/en/latest/swarms/models/) | +| Swarms Tools | [Tools Overview](https://docs.swarms.world/en/latest/swarms_tools/overview/) | +| Example Applications | [Examples](https://docs.swarms.world/en/latest/swarms/examples) | +| Swarms Corp Github | [Swarms Corp GitHub](https://github.com/The-Swarm-Corporation) | +## Join the Swarms Community -### **50 Creative Distribution Platforms for Swarms** +| Platform | Link | Description | +|----------|------|-------------| +| 📚 Documentation | [docs.swarms.world](https://docs.swarms.world) | Official documentation and guides | +| 📝 Blog | [Medium](https://medium.com/@kyeg) | Latest updates and technical articles | +| 💬 Discord | [Join Discord](https://discord.gg/jM3Z6M9uMq) | Live chat and community support | +| 🐦 Twitter | [@kyegomez](https://twitter.com/kyegomez) | Latest news and announcements | +| 👥 LinkedIn | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | Professional network and updates | +| 📺 YouTube | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | Tutorials and demos | +| 🎫 Events | [Sign up here](https://lu.ma/5p2jnc2v) | Join our community events | -1. **E-commerce Integrations:** Platforms like Shopify, WooCommerce, where Swarms can add value to sellers. - -2. **Web Browser Extensions:** Chrome, Firefox, and Edge extensions that bring Swarms features directly to users. +## Get Support -3. **Podcasting Platforms:** Swarms-themed content on platforms like Spotify, Apple Podcasts to reach aural learners. +Want to get in touch with the Swarms team? Open an issue on [GitHub](https://github.com/kyegomez/swarms/issues/new) or reach out to us via [email](mailto:kye@swarms.world). We're here to help! -4. **Virtual Reality (VR) Platforms:** Integration with VR experiences on Oculus or Viveport. -5. **Gaming Platforms:** Tools or plugins for game developers on Steam, Epic Games. -6. **Decentralized Platforms:** Using blockchain, create decentralized apps (DApps) versions of Swarms. +-------------------------------------------------- -7. **Chat Applications:** Integrate with popular messaging platforms like WhatsApp, Telegram, Slack. +# File: protocol\overview.md -8. **AI Assistants:** Integration with Siri, Alexa, Google Assistant to provide Swarms functionalities via voice commands. +# Swarms Protocol Overview & Architecture -9. **Freelancing Websites:** Offer tools or services for freelancers on platforms like Upwork, Fiverr. +This document provides a comprehensive overview of the Swarms protocol architecture, illustrating the flow from agent classes to multi-agent structures, and showcasing the main components and folders within the `swarms/` package. The Swarms framework is designed for extensibility, modularity, and production-readiness, enabling the orchestration of intelligent agents, tools, memory, and complex multi-agent systems. -10. **Online Forums:** Platforms like Reddit, Quora, where users can discuss or access Swarms. +--- -11. **Educational Platforms:** Sites like Khan Academy, Udacity where Swarms can enhance learning experiences. +## Introduction -12. **Digital Art Platforms:** Integrate with platforms like DeviantArt, Behance. +Swarms is an enterprise-grade, production-ready multi-agent orchestration framework. It enables developers and organizations to build, deploy, and manage intelligent agents that can reason, collaborate, and solve complex tasks autonomously or in groups. The architecture is inspired by the principles of modularity, composability, and scalability, ensuring that each component can be extended or replaced as needed. -13. **Open-source Repositories:** Hosting Swarms on GitHub, GitLab, Bitbucket with open-source plugins. +The protocol is structured to support a wide range of use cases, from simple single-agent automations to sophisticated multi-agent workflows involving memory, tool use, and advanced reasoning. -14. **Augmented Reality (AR) Apps:** Create AR experiences powered by Swarms. +For a high-level introduction and installation instructions, see the [Swarms Docs Home](https://docs.swarms.world/en/latest/). -15. **Smart Home Devices:** Integrate Swarms' functionalities into smart home devices. +--- -16. **Newsletters:** Platforms like Substack, where Swarms insights can be shared. +## High-Level Architecture Flow -17. **Interactive Kiosks:** In malls, airports, and other public places. +The Swarms protocol is organized into several key layers, each responsible for a specific aspect of the system. The typical flow is as follows: -18. **IoT Devices:** Incorporate Swarms in devices like smart fridges, smartwatches. +1. **Agent Class (`swarms/agents`)** + + - The core building block of the framework. Agents encapsulate logic, state, and behavior. They can be simple (stateless) or complex + (stateful, with memory and reasoning capabilities). + + - Agents can be specialized for different tasks (e.g., reasoning agents, tool agents, judge agents, etc.). + + - Example: A `ReasoningAgent` that can analyze data and make decisions, or a `ToolAgent` that wraps external APIs. + + - [Quickstart for Agents](https://docs.swarms.world/en/latest/swarms/agents/) + + - [Agent API Reference](https://docs.swarms.world/en/latest/swarms/structs/agent/) -19. **Collaboration Tools:** Platforms like Trello, Notion, offering Swarms-enhanced productivity. +2. **Tools with Memory (`swarms/tools`, `swarms/utils`)** + - Tools are modular components that agents use to interact with the outside world, perform computations, or access resources (APIs, + databases, files, etc.). -20. **Dating Apps:** An AI-enhanced matching algorithm powered by Swarms. + - Memory modules and utility functions allow agents to retain context, cache results, and manage state across interactions. + + - Example: A tool for calling an LLM API, a memory cache for conversation history, or a utility for parsing and formatting data. + + - [Tools Overview](https://docs.swarms.world/en/latest/swarms_tools/overview/) + + - [BaseTool Reference](https://docs.swarms.world/en/latest/swarms/tools/base_tool/) -21. **Music Platforms:** Integrate with Spotify, SoundCloud for music-related AI functionalities. +3. **Reasoning & Specialized Agents (`swarms/agents`)** + - These agents build on the base agent class, adding advanced reasoning, self-consistency, and specialized logic for tasks like + planning, evaluation, or multi-step workflows. -22. **Recipe Websites:** Platforms like AllRecipes, Tasty with AI-recommended recipes. + - Includes agents for self-reflection, iterative improvement, and domain-specific expertise. -23. **Travel & Hospitality:** Integrate with platforms like Airbnb, Tripadvisor for AI-based recommendations. + - Example: A `SelfConsistencyAgent` that aggregates multiple reasoning paths, or a `JudgeAgent` that evaluates outputs from other + agents. -24. **Language Learning Apps:** Duolingo, Rosetta Stone integrations. + - [Reasoning Agents Overview](https://docs.swarms.world/en/latest/swarms/agents/reasoning_agents_overview/) + + - [Self Consistency Agent](https://docs.swarms.world/en/latest/swarms/agents/consistency_agent/) + + - [Agent Judge](https://docs.swarms.world/en/latest/swarms/agents/agent_judge/) -25. **Virtual Events Platforms:** Websites like Hopin, Zoom where Swarms can enhance the virtual event experience. +4. **Multi-Agent Structures (`swarms/structs`)** + - Agents are composed into higher-order structures for collaboration, voting, parallelism, and workflow orchestration. -26. **Social Media Management:** Tools like Buffer, Hootsuite with AI insights by Swarms. + - Includes swarms for majority voting, round-robin execution, hierarchical delegation, and more. -27. **Fitness Apps:** Platforms like MyFitnessPal, Strava with AI fitness insights. + - Example: A `MajorityVotingSwarm` that aggregates outputs from several agents, or a `HierarchicalSwarm` that delegates tasks to + sub-agents. -28. **Mental Health Apps:** Integration into apps like Calm, Headspace for AI-driven wellness. + - [Multi-Agent Architectures Overview](https://docs.swarms.world/en/latest/swarms/concept/swarm_architectures/) + + - [MajorityVotingSwarm](https://docs.swarms.world/en/latest/swarms/structs/majorityvoting/) + + - [HierarchicalSwarm](https://docs.swarms.world/en/latest/swarms/structs/hierarchical_swarm/) + + - [Sequential Workflow](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/) + + - [Concurrent Workflow](https://docs.swarms.world/en/latest/swarms/structs/concurrentworkflow/) -29. **E-books Platforms:** Amazon Kindle, Audible with AI-enhanced reading experiences. +5. **Supporting Components** -30. **Sports Analysis Tools:** Websites like ESPN, Sky Sports where Swarms can provide insights. + - **Communication (`swarms/communication`)**: Provides wrappers for inter-agent communication, database access, message passing, and + integration with external systems (e.g., Redis, DuckDB, Pulsar). See [Communication Structure](https://docs.swarms.world/en/latest/swarms/structs/conversation/) + + - **Artifacts (`swarms/artifacts`)**: Manages the creation, storage, and retrieval of artifacts (outputs, files, logs) generated by + agents and swarms. + + - **Prompts (`swarms/prompts`)**: Houses prompt templates, system prompts, and agent-specific prompts for LLM-based agents. See + [Prompts Management](https://docs.swarms.world/en/latest/swarms/prompts/main/) + + - **Telemetry (`swarms/telemetry`)**: Handles logging, monitoring, and bootup routines for observability and debugging. + + - **Schemas (`swarms/schemas`)**: Defines data schemas for agents, tools, completions, and communication protocols, ensuring type + safety and consistency. + + - **CLI (`swarms/cli`)**: Provides command-line utilities for agent creation, management, and orchestration. See [CLI Documentation] + (https://docs.swarms.world/en/latest/swarms/cli/main/) -31. **Financial Tools:** Integration into platforms like Mint, Robinhood for AI-driven financial advice. +--- -32. **Public Libraries:** Digital platforms of public libraries for enhanced reading experiences. +## Proposing Large Improvements or Enhancements: Swarms Improvement Proposals (SIPs) -33. **3D Printing Platforms:** Websites like Thingiverse, Shapeways with AI customization. +For significant changes, new agent architectures, or radical new features, Swarms uses a formal process called **Swarms Improvement Proposals (SIPs)**. SIPs are design documents that describe new features, enhancements, or changes to the Swarms framework. They ensure that major changes are well-documented, discussed, and reviewed by the community before implementation. -34. **Meme Platforms:** Websites like Memedroid, 9GAG where Swarms can suggest memes. +**When to use a SIP:** -35. **Astronomy Apps:** Platforms like Star Walk, NASA's Eyes with AI-driven space insights. +- Proposing new agent types, swarm patterns, or coordination mechanisms -36. **Weather Apps:** Integration into Weather.com, AccuWeather for predictive analysis. +- Core framework changes or breaking changes -37. **Sustainability Platforms:** Websites like Ecosia, GoodGuide with AI-driven eco-tips. +- New integrations (LLM providers, tools, external services) -38. **Fashion Apps:** Platforms like ASOS, Zara with AI-based style recommendations. +- Any complex or multi-component feature -39. **Pet Care Apps:** Integration into PetSmart, Chewy for AI-driven pet care tips. +**SIP Process Overview:** -40. **Real Estate Platforms:** Websites like Zillow, Realtor with AI-enhanced property insights. +1. Discuss your idea in [GitHub Discussions](https://github.com/kyegomez/swarms/discussions) -41. **DIY Platforms:** Websites like Instructables, DIY.org with AI project suggestions. +2. Submit a SIP as a GitHub Issue using the SIP template -42. **Genealogy Platforms:** Ancestry, MyHeritage with AI-driven family tree insights. +3. Engage with the community and iterate on your proposal -43. **Car Rental & Sale Platforms:** Integration into AutoTrader, Turo for AI-driven vehicle suggestions. +4. Undergo review and, if accepted, proceed to implementation -44. **Wedding Planning Websites:** Platforms like Zola, The Knot with AI-driven planning. +**Learn more:** See the full [SIP Guidelines and Template](https://docs.swarms.world/en/latest/protocol/sip/) -45. **Craft Platforms:** Websites like Etsy, Craftsy with AI-driven craft suggestions. +--- -46. **Gift Recommendation Platforms:** AI-driven gift suggestions for websites like Gifts.com. +## Detailed Architecture Diagram -47. **Study & Revision Platforms:** Websites like Chegg, Quizlet with AI-driven study guides. +The following Mermaid diagram visualizes the protocol flow and the relationship between the main folders in the `swarms/` package: -48. **Local Business Directories:** Yelp, Yellow Pages with AI-enhanced reviews. +```mermaid +flowchart TD + A["Agent Class
(swarms/agents)"] --> B["Tools with Memory
(swarms/tools, swarms/utils)"] + B --> C["Reasoning & Specialized Agents
(swarms/agents)"] + C --> D["Multi-Agent Structures
(swarms/structs)"] + D --> E["Communication, Artifacts, Prompts, Telemetry, Schemas, CLI"] + + subgraph Folders + A1["agents"] + A2["tools"] + A3["structs"] + A4["utils"] + A5["telemetry"] + A6["schemas"] + A7["prompts"] + A8["artifacts"] + A9["communication"] + A10["cli"] + end + + %% Folder showcase + subgraph "swarms/" + A1 + A2 + A3 + A4 + A5 + A6 + A7 + A8 + A9 + A10 + end + + %% Connect folder showcase to main flow + A1 -.-> A + A2 -.-> B + A3 -.-> D + A4 -.-> B + A5 -.-> E + A6 -.-> E + A7 -.-> E + A8 -.-> E + A9 -.-> E + A10 -.-> E +``` -49. **Networking Platforms:** LinkedIn, Meetup with AI-driven connection suggestions. +--- -50. **Lifestyle Magazines' Digital Platforms:** Websites like Vogue, GQ with AI-curated fashion and lifestyle insights. +## Folder-by-Folder Breakdown ---- +### `agents/` -*Endnote: Leveraging these diverse platforms ensures that Swarms becomes an integral part of multiple ecosystems, enhancing its visibility and user engagement.* +**Purpose:** Defines all agent classes, including base agents, reasoning agents, tool agents, judge agents, and more. --------------------------------------------------- +**Highlights:** -# File: corporate/failures.md +- Modular agent design for extensibility. -# Failure Root Cause Analysis for Langchain +- Support for YAML-based agent creation and configuration. See [YAML Agent Creation](https://docs.swarms.world/en/latest/swarms/ +agents/create_agents_yaml/) -## 1. Introduction +- Specialized agents for self-consistency, evaluation, and domain-specific tasks. -Langchain is an open-source software that has gained massive popularity in the artificial intelligence ecosystem, serving as a tool for connecting different language models, especially GPT based models. However, despite its popularity and substantial investment, Langchain has shown several weaknesses that hinder its use in various projects, especially in complex and large-scale implementations. This document provides an analysis of the identified issues and proposes potential mitigation strategies. +- **Example:** -## 2. Analysis of Weaknesses +- `ReasoningAgent`, `ToolAgent`, `JudgeAgent`, `ConsistencyAgent`, `OpenAIAssistant`, etc. -### 2.1 Tool Lock-in +- [Agents Overview](https://docs.swarms.world/en/latest/swarms/framework/agents_explained/) -Langchain tends to enforce tool lock-in, which could prove detrimental for developers. Its design heavily relies on specific workflows and architectures, which greatly limits flexibility. Developers may find themselves restricted to certain methodologies, impeding their freedom to implement custom solutions or integrate alternative tools. -#### Mitigation +### `tools/` -An ideal AI framework should not be restrictive but should instead offer flexibility for users to integrate any agent on any architecture. Adopting an open architecture that allows for seamless interaction between various agents and workflows can address this issue. +**Purpose:** Houses all tool-related logic, including tool registry, function calling, tool schemas, and integration with external +APIs. -### 2.2 Outdated Workflows +**Highlights:** -Langchain's current workflows and prompt engineering, mainly based on InstructGPT, are out of date, especially compared to newer models like ChatGPT/GPT-4. +- Tools can be dynamically registered and called by agents. -#### Mitigation +- Support for OpenAI function calling, Cohere, and custom tool schemas. -Keeping up with the latest AI models and workflows is crucial. The framework should have a mechanism for regular updates and seamless integration of up-to-date models and workflows. +- Utilities for parsing, formatting, and executing tool calls. -### 2.3 Debugging Difficulties +- **Example:** -Debugging in Langchain is reportedly very challenging, even with verbose output enabled, making it hard to determine what is happening under the hood. +- `base_tool.py`, `tool_registry.py`, `mcp_client_call.py`, `func_calling_utils.py`, etc. -#### Mitigation +- [Tools Reference](https://docs.swarms.world/en/latest/swarms/tools/tools_examples/) -The introduction of a robust debugging and logging system would help users understand the internals of the models, thus enabling them to pinpoint and rectify issues more effectively. +- [What are tools?](https://docs.swarms.world/en/latest/swarms/tools/build_tool/) -### 2.4 Limited Customization -Langchain makes it extremely hard to deviate from documented workflows. This becomes a challenge when developers need custom workflows for their specific use-cases. +### `structs/` +**Purpose:** Implements multi-agent structures, workflows, routers, registries, and orchestration logic. -#### Mitigation +**Highlights:** -An ideal framework should support custom workflows and allow developers to hack and adjust the framework according to their needs. +- Swarms for majority voting, round-robin, hierarchical delegation, spreadsheet processing, and more. -### 2.5 Documentation +- Workflow orchestration (sequential, concurrent, graph-based). -Langchain's documentation is reportedly missing relevant details, making it difficult for users to understand the differences between various agent types, among other things. +- Utilities for agent matching, rearrangement, and evaluation. -#### Mitigation +- **Example:** -Providing detailed and comprehensive documentation, including examples, FAQs, and best practices, is crucial. This will help users understand the intricacies of the framework, making it easier for them to implement it in their projects. +- `MajorityVotingSwarm`, `HierarchicalSwarm`, `SwarmRouter`, `SequentialWorkflow`, `ConcurrentWorkflow`, etc. -### 2.6 Negative Influence on AI Ecosystem +- [Custom Multi Agent Architectures](https://docs.swarms.world/en/latest/swarms/structs/custom_swarm/) -The extreme popularity of Langchain seems to be warping the AI ecosystem to the point of causing harm, with other AI entities shifting their operations to align with Langchain's 'magic AI' approach. +- [SwarmRouter](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/) -#### Mitigation +- [AgentRearrange](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/) -It's essential for any widely adopted framework to promote healthy practices in the broader ecosystem. One approach could be promoting open dialogue, inviting criticism, and being open to change based on feedback. -## 3. Conclusion +### `utils/` -While Langchain has made significant contributions to the AI landscape, these challenges hinder its potential. Addressing these issues will not only improve Langchain but also foster a healthier AI ecosystem. It's important to note that criticism, when approached constructively, can be a powerful tool for growth and innovation. +**Purpose:** Provides utility functions, memory management, caching, wrappers, and helpers used throughout the framework. +**Highlights:** -# List of weaknesses in gLangchain and Potential Mitigations +- Memory and caching for agents and tools. See [Integrating RAG with Agents](https://docs.swarms.world/en/latest/swarms/memory/ +diy_memory/) -1. **Tool Lock-in**: Langchain encourages the use of specific tools, creating a lock-in problem with minimal benefits for developers. +- Wrappers for concurrency, logging, and data processing. - *Mitigation Strategy*: Langchain should consider designing the architecture to be more versatile and allow for the inclusion of a variety of tools. An open architecture will provide developers with more freedom and customization options. +- General-purpose utilities for string, file, and data manipulation. -2. **Outdated Workflow**: The current workflow and prompt engineering of Langchain rely on outdated models like InstructGPT, which fall short compared to newer alternatives such as ChatGPT/GPT-4. +**Example:** - *Mitigation Strategy*: Regular updates and adaptation of more recent models should be integrated into the Langchain framework. +- `agent_cache.py`, `concurrent_wrapper.py`, `file_processing.py`, `formatter.py`, etc. -3. **Debugging Difficulty**: Debugging a Langchain error is a complicated task, even with verbose=True, leading to a discouraging developer experience. - *Mitigation Strategy*: Develop a comprehensive debugging tool or improve current debugging processes for clearer and more accessible error detection and resolution. +### `telemetry/` -4. **Lack of Customizability**: Customizing workflows that are not documented in Langchain is quite challenging. +**Purpose:** Handles telemetry, logging, monitoring, and bootup routines for the framework. - *Mitigation Strategy*: Improve documentation and provide guides on how to customize workflows to enhance developer flexibility. +**Highlights:** -5. **Poor Documentation**: Langchain's documentation misses key details that developers have to manually search for in the codebase. +- Centralized logging and execution tracking. - *Mitigation Strategy*: Enhance and improve the documentation of Langchain to provide clarity for developers and make navigation easier. +- Bootup routines for initializing the framework. -6. **Harmful Ecosystem Influence**: Langchain's extreme popularity is influencing the AI ecosystem towards the workflows, potentially harming development and code clarity. +- Utilities for monitoring agent and swarm performance. - *Mitigation Strategy*: Encourage diverse and balanced adoption of AI tools in the ecosystem. +- **Example:** -7. **Suboptimal Performances**: Langchain's performance is sometimes underwhelming, and there are no clear benefits in terms of performance or abstraction. +- `bootup.py`, `log_executions.py`, `main.py`. - *Mitigation Strategy*: Enhance the performance optimization of Langchain. Benchmarking against other tools can also provide performance improvement insights. -8. **Rigid General Interface**: Langchain tries to do too many things, resulting in a rigid interface not suitable for practical use, especially in production. +### `schemas/` - *Mitigation Strategy*: Focus on core features and allow greater flexibility in the interface. Adopting a modular approach where developers can pick and choose the features they want could also be helpful. +**Purpose:** Defines data schemas for agents, tools, completions, and communication protocols. -9. **Leaky Abstraction Problem**: Langchain’s full-on framework approach has created a leaky abstraction problem leading to a disappointing developer experience. +**Highlights:** - *Mitigation Strategy*: Adopt a more balanced approach between a library and a framework. Provide a solid core feature set with the possibility to extend it according to the developers' needs. +- Ensures type safety and consistency across the framework. -10. **Excessive Focus on Third-party Services**: Langchain overly focuses on supporting every single third-party service at the expense of customizability and fine-tuning for actual applications. +- Pydantic-based schemas for validation and serialization. - *Mitigation Strategy*: Prioritize fine-tuning and customizability for developers, limiting the focus on third-party services unless they provide substantial value. - -Remember, any mitigation strategy will need to be tailored to Langchain's particular circumstances and developer feedback. It's also important to consider potential trade-offs and unintended consequences when implementing these strategies. +- Schemas for agent classes, tool calls, completions, and more. --------------------------------------------------- +**Example:** -# File: corporate/faq.md +- `agent_class_schema.py`, `tool_schema_base_model.py`, `agent_completion_response.py`, etc. -### FAQ on Swarm Intelligence and Multi-Agent Systems -#### What is an agent in the context of AI and swarm intelligence? +### `prompts/` -In artificial intelligence (AI), an agent refers to an LLM with some objective to accomplish. +**Purpose:** Contains prompt templates, system prompts, and agent-specific prompts for LLM-based agents. -In swarm intelligence, each agent interacts with other agents and possibly the environment to achieve complex collective behaviors or solve problems more efficiently than individual agents could on their own. +**Highlights:** +- Modular prompt design for easy customization. -#### What do you need Swarms at all? -Individual agents are limited by a vast array of issues such as context window loss, single task execution, hallucination, and no collaboration. +- Support for multi-modal, collaborative, and domain-specific prompts. +- Templates for system, task, and conversational prompts. -#### How does a swarm work? +**Example:** -A swarm works through the principles of decentralized control, local interactions, and simple rules followed by each agent. Unlike centralized systems, where a single entity dictates the behavior of all components, in a swarm, each agent makes its own decisions based on local information and interactions with nearby agents. These local interactions lead to the emergence of complex, organized behaviors or solutions at the collective level, enabling the swarm to tackle tasks efficiently. +- `prompt.py`, `reasoning_prompt.py`, `multi_agent_collab_prompt.py`, etc. -#### Why do you need more agents in a swarm? +- [Prompts Management](https://docs.swarms.world/en/latest/swarms/prompts/main/) -More agents in a swarm can enhance its problem-solving capabilities, resilience, and efficiency. With more agents: -- **Diversity and Specialization**: The swarm can leverage a wider range of skills, knowledge, and perspectives, allowing for more creative and effective solutions to complex problems. -- **Scalability**: Adding more agents can increase the swarm's capacity to handle larger tasks or multiple tasks simultaneously. -- **Robustness**: A larger number of agents enhances the system's redundancy and fault tolerance, as the failure of a few agents has a minimal impact on the overall performance of the swarm. +### `artifacts/` -#### Isn't it more expensive to use more agents? +**Purpose:** Manages the creation, storage, and retrieval of artifacts (outputs, files, logs) generated by agents and swarms. -While deploying more agents can initially increase costs, especially in terms of computational resources, hosting, and potentially API usage, there are several factors and strategies that can mitigate these expenses: +**Highlights:** -- **Efficiency at Scale**: Larger swarms can often solve problems more quickly or effectively, reducing the overall computational time and resources required. -- **Optimization and Caching**: Implementing optimizations and caching strategies can reduce redundant computations, lowering the workload on individual agents and the overall system. -- **Dynamic Scaling**: Utilizing cloud services that offer dynamic scaling can ensure you only pay for the resources you need when you need them, optimizing cost-efficiency. +- Artifact management for reproducibility and traceability. +- Support for various output types and formats. -#### Can swarms make decisions better than individual agents? +**Example:** -Yes, swarms can make better decisions than individual agents for several reasons: +- `main_artifact.py`. -- **Collective Intelligence**: Swarms combine the knowledge and insights of multiple agents, leading to more informed and well-rounded decision-making processes. -- **Error Correction**: The collaborative nature of swarms allows for error checking and correction among agents, reducing the likelihood of mistakes. -- **Adaptability**: Swarms are highly adaptable to changing environments or requirements, as the collective can quickly reorganize or shift strategies based on new information. -#### How do agents in a swarm communicate? +### `communication/` -Communication in a swarm can vary based on the design and purpose of the system but generally involves either direct or indirect interactions: +**Purpose:** Provides wrappers for inter-agent communication, database access, message passing, and integration with external systems. -- **Direct Communication**: Agents exchange information directly through messaging, signals, or other communication protocols designed for the system. -- **Indirect Communication**: Agents influence each other through the environment, a method known as stigmergy. Actions by one agent alter the environment, which in turn influences the behavior of other agents. +**Highlights:** -#### Are swarms only useful in computational tasks? +- Support for Redis, DuckDB, Pulsar, Supabase, and more. +- Abstractions for message passing and data exchange between agents. -While swarms are often associated with computational tasks, their applications extend far beyond. Swarms can be utilized in: +**Example:** -- **Robotics**: Coordinating multiple robots for tasks like search and rescue, exploration, or surveillance. -- **Environmental Monitoring**: Using sensor networks to monitor pollution, wildlife, or climate conditions. -- **Social Sciences**: Modeling social behaviors or economic systems to understand complex societal dynamics. -- **Healthcare**: Coordinating care strategies in hospital settings or managing pandemic responses through distributed data analysis. +- `redis_wrap.py`, `duckdb_wrap.py`, `base_communication.py`, etc. -#### How do you ensure the security of a swarm system? +- [Communication Structure](https://docs.swarms.world/en/latest/swarms/structs/conversation/) -Security in swarm systems involves: -- **Encryption**: Ensuring all communications between agents are encrypted to prevent unauthorized access or manipulation. -- **Authentication**: Implementing strict authentication mechanisms to verify the identity of each agent in the swarm. -- **Resilience to Attacks**: Designing the swarm to continue functioning effectively even if some agents are compromised or attacked, utilizing redundancy and fault tolerance strategies. +### `cli/` -#### How do individual agents within a swarm share insights without direct learning mechanisms like reinforcement learning? +**Purpose:** Command-line utilities for agent creation, management, and orchestration. -In the context of pre-trained Large Language Models (LLMs) that operate within a swarm, sharing insights typically involves explicit communication and data exchange protocols rather than direct learning mechanisms like reinforcement learning. Here's how it can work: +**Highlights:** -- **Shared Databases and Knowledge Bases**: Agents can write to and read from a shared database or knowledge base where insights, generated content, and relevant data are stored. This allows agents to benefit from the collective experience of the swarm by accessing information that other agents have contributed. - -- **APIs for Information Exchange**: Custom APIs can facilitate the exchange of information between agents. Through these APIs, agents can request specific information or insights from others within the swarm, effectively sharing knowledge without direct learning. +- Scripts for onboarding, agent creation, and management. -#### How do you balance the autonomy of individual LLMs with the need for coherent collective behavior in a swarm? +- CLI entry points for interacting with the framework. -Balancing autonomy with collective coherence in a swarm of LLMs involves: +**Example:** -- **Central Coordination Mechanism**: Implementing a lightweight central coordination mechanism that can assign tasks, distribute information, and collect outputs from individual LLMs. This ensures that while each LLM operates autonomously, their actions are aligned with the swarm's overall objectives. +- `main.py`, `create_agent.py`, `onboarding_process.py`. -- **Standardized Communication Protocols**: Developing standardized protocols for how LLMs communicate and share information ensures that even though each agent works autonomously, the information exchange remains coherent and aligned with the collective goals. +- [CLI Documentation](https://docs.swarms.world/en/latest/swarms/cli/main/) -#### How do LLM swarms adapt to changing environments or tasks without machine learning techniques? -Adaptation in LLM swarms, without relying on machine learning techniques for dynamic learning, can be achieved through: +--- -- **Dynamic Task Allocation**: A central system or distributed algorithm can dynamically allocate tasks to different LLMs based on the changing environment or requirements. This ensures that the most suitable LLMs are addressing tasks for which they are best suited as conditions change. +## How the System Works Together -- **Pre-trained Versatility**: Utilizing a diverse set of pre-trained LLMs with different specialties or training data allows the swarm to select the most appropriate agent for a task as the requirements evolve. +The Swarms protocol is designed for composability. Agents can be created and configured independently, then composed into larger structures (swarms) for collaborative or competitive workflows. Tools and memory modules are injected into agents as needed, enabling them to perform complex tasks and retain context. Multi-agent structures orchestrate the flow of information and decision-making, while supporting components (communication, telemetry, artifacts, etc.) ensure robustness, observability, and extensibility. -- **In Context Learning**: In context learning is another mechanism that can be employed within LLM swarms to adapt to changing environments or tasks. This approach involves leveraging the collective knowledge and experiences of the swarm to facilitate learning and improve performance. Here's how it can work: +For example, a typical workflow might involve: +- Creating a set of specialized agents (e.g., data analyst, summarizer, judge). -#### Can LLM swarms operate in physical environments, or are they limited to digital spaces? +- Registering tools (e.g., LLM API, database access, web search) and memory modules. -LLM swarms primarily operate in digital spaces, given their nature as software entities. However, they can interact with physical environments indirectly through interfaces with sensors, actuaries, or other devices connected to the Internet of Things (IoT). For example, LLMs can process data from physical sensors and control devices based on their outputs, enabling applications like smart home management or autonomous vehicle navigation. +- Composing agents into a `MajorityVotingSwarm` for collaborative decision-making. -#### Without direct learning from each other, how do agents in a swarm improve over time? +- Using communication wrappers to exchange data between agents and external systems. -Improvement over time in a swarm of pre-trained LLMs, without direct learning from each other, can be achieved through: +- Logging all actions and outputs for traceability and debugging. -- **Human Feedback**: Incorporating feedback from human operators or users can guide adjustments to the usage patterns or selection criteria of LLMs within the swarm, optimizing performance based on observed outcomes. -- **Periodic Re-training and Updating**: The individual LLMs can be periodically re-trained or updated by their developers based on collective insights and feedback from their deployment within swarms. While this does not involve direct learning from each encounter, it allows the LLMs to improve over time based on aggregated experiences. +For more advanced examples, see the [Examples Overview](https://docs.swarms.world/en/latest/examples/index/). -These adjustments to the FAQ reflect the specific context of pre-trained LLMs operating within a swarm, focusing on communication, coordination, and adaptation mechanisms that align with their capabilities and constraints. +--- +## Swarms Framework Philosophy -#### Conclusion +Swarms is built on the following principles: -Swarms represent a powerful paradigm in AI, offering innovative solutions to complex, dynamic problems through collective intelligence and decentralized control. While challenges exist, particularly regarding cost and security, strategic design and management can leverage the strengths of swarm intelligence to achieve remarkable efficiency, adaptability, and robustness in a wide range of applications. +- **Modularity:** Every component (agent, tool, prompt, schema) is a module that can be extended or replaced. --------------------------------------------------- +- **Composability:** Agents and tools can be composed into larger structures for complex workflows. -# File: corporate/flywheel.md +- **Observability:** Telemetry and artifact management ensure that all actions are traceable and debuggable. -# The Swarms Flywheel +- **Extensibility:** New agents, tools, and workflows can be added with minimal friction. -1. **Building a Supportive Community:** Initiate by establishing an engaging and inclusive open-source community for both developers and sales freelancers around Swarms. Regular online meetups, webinars, tutorials, and sales training can make them feel welcome and encourage contributions and sales efforts. +- **Production-Readiness:** The framework is designed for reliability, scalability, and real-world deployment. -2. **Increased Contributions and Sales Efforts:** The more engaged the community, the more developers will contribute to Swarms and the more effort sales freelancers will put into selling Swarms. -3. **Improvement in Quality and Market Reach:** More developer contributions mean better quality, reliability, and feature offerings from Swarms. Simultaneously, increased sales efforts from freelancers boost Swarms' market penetration and visibility. +For more on the philosophy and architecture, see [Development Philosophy & Principles](https://docs.swarms.world/en/latest/swarms/concept/philosophy/) and [Understanding Swarms Architecture](https://docs.swarms.world/en/latest/swarms/concept/framework_architecture/). -4. **Rise in User Base:** As Swarms becomes more robust and more well-known, the user base grows, driving more revenue. +--- -5. **Greater Financial Incentives:** Increased revenue can be redirected to offer more significant financial incentives to both developers and salespeople. Developers can be incentivized based on their contribution to Swarms, and salespeople can be rewarded with higher commissions. +## Further Reading & References -6. **Attract More Developers and Salespeople:** These financial incentives, coupled with the recognition and experience from participating in a successful project, attract more developers and salespeople to the community. +- [Swarms Docs Home](https://docs.swarms.world/en/latest/) -7. **Wider Adoption of Swarms:** An ever-improving product, a growing user base, and an increasing number of passionate salespeople accelerate the adoption of Swarms. +- [Quickstart for Agents](https://docs.swarms.world/en/latest/swarms/agents/) -8. **Return to Step 1:** As the community, user base, and sales network continue to grow, the cycle repeats, each time speeding up the flywheel. +- [Agent API Reference](https://docs.swarms.world/en/latest/swarms/structs/agent/) +- [Tools Overview](https://docs.swarms.world/en/latest/swarms_tools/overview/) -```markdown - +---------------------+ - | Building a | - | Supportive | <--+ - | Community | | - +--------+-----------+ | - | | - v | - +--------+-----------+ | - | Increased | | - | Contributions & | | - | Sales Efforts | | - +--------+-----------+ | - | | - v | - +--------+-----------+ | - | Improvement in | | - | Quality & Market | | - | Reach | | - +--------+-----------+ | - | | - v | - +--------+-----------+ | - | Rise in User | | - | Base | | - +--------+-----------+ | - | | - v | - +--------+-----------+ | - | Greater Financial | | - | Incentives | | - +--------+-----------+ | - | | - v | - +--------+-----------+ | - | Attract More | | - | Developers & | | - | Salespeople | | - +--------+-----------+ | - | | - v | - +--------+-----------+ | - | Wider Adoption of | | - | Swarms |----+ - +---------------------+ -``` - - -# Potential Risks and Mitigations: - -1. **Insufficient Contributions or Quality of Work**: Open-source efforts rely on individuals being willing and able to spend time contributing. If not enough people participate, or the work they produce is of poor quality, the product development could stall. - * **Mitigation**: Create a robust community with clear guidelines, support, and resources. Provide incentives for quality contributions, such as a reputation system, swag, or financial rewards. Conduct thorough code reviews to ensure the quality of contributions. - -2. **Lack of Sales Results**: Commission-based salespeople will only continue to sell the product if they're successful. If they aren't making enough sales, they may lose motivation and cease their efforts. - * **Mitigation**: Provide adequate sales training and resources. Ensure the product-market fit is strong, and adjust messaging or sales tactics as necessary. Consider implementing a minimum commission or base pay to reduce risk for salespeople. - -3. **Poor User Experience or User Adoption**: If users don't find the product useful or easy to use, they won't adopt it, and the user base won't grow. This could also discourage salespeople and contributors. - * **Mitigation**: Prioritize user experience in the product development process. Regularly gather and incorporate user feedback. Ensure robust user support is in place. - -4. **Inadequate Financial Incentives**: If the financial rewards don't justify the time and effort contributors and salespeople are putting in, they will likely disengage. - * **Mitigation**: Regularly review and adjust financial incentives as needed. Ensure that the method for calculating and distributing rewards is transparent and fair. - -5. **Security and Compliance Risks**: As the user base grows and the software becomes more complex, the risk of security issues increases. Moreover, as contributors from various regions join, compliance with various international laws could become an issue. - * **Mitigation**: Establish strong security practices from the start. Regularly conduct security audits. Seek legal counsel to understand and adhere to international laws and regulations. - -## Activation Plan for the Flywheel: - -1. **Community Building**: Begin by fostering a supportive community around Swarms. Encourage early adopters to contribute and provide feedback. Create comprehensive documentation, community guidelines, and a forum for discussion and support. - -2. **Sales and Development Training**: Provide resources and training for salespeople and developers. Make sure they understand the product, its value, and how to effectively contribute or sell. - -3. **Increase Contributions and Sales Efforts**: Encourage increased participation by highlighting successful contributions and sales, rewarding top contributors and salespeople, and regularly communicating about the project's progress and impact. - -4. **Iterate and Improve**: Continually gather and implement feedback to improve Swarms and its market reach. The better the product and its alignment with the market, the more the user base will grow. - -5. **Expand User Base**: As the product improves and sales efforts continue, the user base should grow. Ensure you have the infrastructure to support this growth and maintain a positive user experience. - -6. **Increase Financial Incentives**: As the user base and product grow, so too should the financial incentives. Make sure rewards continue to be competitive and attractive. - -7. **Attract More Contributors and Salespeople**: As the financial incentives and success of the product increase, this should attract more contributors and salespeople, further feeding the flywheel. - -Throughout this process, it's important to regularly reassess and adjust your strategy as necessary. Stay flexible and responsive to changes in the market, user feedback, and the evolving needs of the community. +- [BaseTool Reference](https://docs.swarms.world/en/latest/swarms/tools/base_tool/) --------------------------------------------------- +- [Reasoning Agents Overview](https://docs.swarms.world/en/latest/swarms/agents/reasoning_agents_overview/) -# File: corporate/front_end_contributors.md +- [Multi-Agent Architectures Overview](https://docs.swarms.world/en/latest/swarms/concept/swarm_architectures/) -# Frontend Contributor Guide +- [Examples Overview](https://docs.swarms.world/en/latest/examples/index/) -## Mission -At the heart of Swarms is the mission to democratize multi-agent technology, making it accessible to businesses of all sizes around the globe. This technology, which allows for the orchestration of multiple autonomous agents to achieve complex goals, has the potential to revolutionize industries by enhancing efficiency, scalability, and innovation. Swarms is committed to leading this charge by developing a platform that empowers businesses and individuals to harness the power of multi-agent systems without the need for specialized knowledge or resources. +- [CLI Documentation](https://docs.swarms.world/en/latest/swarms/cli/main/) +- [Prompts Management](https://docs.swarms.world/en/latest/swarms/prompts/main/) -## Understanding Your Impact as a Frontend Engineer -Crafting User Experiences: As a frontend engineer at Swarms, you play a crucial role in making multi-agent technology understandable and usable for businesses worldwide. Your work involves translating complex systems into intuitive interfaces, ensuring users can easily navigate, manage, and benefit from multi-agent solutions. By focusing on user-centric design and seamless integration, you help bridge the gap between advanced technology and practical business applications. +- [Development Philosophy & Principles](https://docs.swarms.world/en/latest/swarms/concept/philosophy/) -Skills and Attributes for Success: Successful frontend engineers at Swarms combine technical expertise with a passion for innovation and a deep understanding of user needs. Proficiency in modern frontend technologies, such as React, NextJS, and Tailwind, is just the beginning. You also need a strong grasp of usability principles, accessibility standards, and the ability to work collaboratively with cross-functional teams. Creativity, problem-solving skills, and a commitment to continuous learning are essential for developing solutions that meet diverse business needs. +- [Understanding Swarms Architecture](https://docs.swarms.world/en/latest/swarms/concept/framework_architecture/) +- [SIP Guidelines and Template](https://docs.swarms.world/en/latest/protocol/sip/) -## Joining the Team -As you contribute to Swarms, you become part of a collaborative effort to change the world. We value each contribution and provide constructive feedback to help you grow. Outstanding contributors who share our vision and demonstrate exceptional skill and dedication are invited to join our team, where they can have an even greater impact on our mission. +# Conclusion -### Becoming a Full-Time Swarms Engineer: -Swarms is radically devoted to open source and transparency. To join the full time team, you must first contribute to the open source repository so we can assess your technical capability and general way of working. After a series of quality contributions, we'll offer you a full time position! +The Swarms protocol provides a robust foundation for building intelligent, collaborative, and autonomous systems. By organizing the codebase into clear, modular folders and defining a logical flow from agents to multi-agent structures, Swarms enables rapid development and deployment of advanced AI solutions. Whether you are building a simple automation or a complex multi-agent application, the Swarms architecture provides the tools and abstractions you need to succeed. -Joining Swarms full-time means more than just a job. It's an opportunity to be at the forefront of technological innovation, working alongside passionate professionals dedicated to making a difference. We look for individuals who are not only skilled but also driven by the desire to make multi-agent technology accessible and beneficial to businesses worldwide. -## Resources -- **Project Management Details** - - **Linear**: Our projects and tasks at a glance. Get a sense of our workflow and priorities. - - [View on Linear](https://linear.app/swarms/join/e7f4c6c560ffa0e1395820682f4e110a?s=1) +-------------------------------------------------- -- **Design System and UI/UX Guidelines** - - **Figma**: Dive into our design system to grasp the aesthetics and user experience objectives of Swarms. - - [View on Figma](https://www.figma.com/file/KL4VIXfZKwwLgAes2WbGNa/Swarms-Cloud-Platform?type=design&node-id=0%3A1&mode=design&t=MkrM0mBQa6qsTDtJ-1) +# File: protocol\sip.md -- **Swarms Platform Repository** - - **GitHub**: The hub of our development activities. Familiarize yourself with our codebase and current projects. - - [Visit GitHub Repository](https://github.com/kyegomez/swarms-platform) +# Swarms Improvement Proposal (SIP) Guidelines -- **[Swarms Community](https://discord.gg/pSTSxqDk)** +A simplified process for proposing new functionality and enhancements to the Swarms framework. +## What is a SIP? -### Design Style & User Experience -- [How to build great products with game design, not gamification](https://blog.superhuman.com/game-design-not-gamification/) +A **Swarms Improvement Proposal (SIP)** is a design document that describes a new feature, enhancement, or change to the Swarms framework. SIPs serve as the primary mechanism for proposing significant changes, collecting community feedback, and documenting design decisions. --------------------------------------------------- +The SIP author is responsible for building consensus within the community and documenting the proposal clearly and concisely. -# File: corporate/hiring.md +## When to Submit a SIP -# Careers at Swarms +Consider submitting a SIP for: -We are a team of engineers, developers, and visionaries on a mission to build the future of AI by orchestrating multi-agent collaboration. We move fast, think ambitiously, and deliver with urgency. Join us if you want to be part of building the next generation of multi-agent systems, redefining how businesses automate operations and leverage AI. +- **New Agent Types or Behaviors**: Adding new agent architectures, swarm patterns, or coordination mechanisms +- **Core Framework Changes**: Modifications to the Swarms API, core classes, or fundamental behaviors +- **New Integrations**: Adding support for new LLM providers, tools, or external services +- **Breaking Changes**: Any change that affects backward compatibility +- **Complex Features**: Multi-component features that require community discussion and design review -**We offer none of the following benefits Yet:** +For simple bug fixes, minor enhancements, or straightforward additions, use regular GitHub issues and pull requests instead. -- No medical, dental, or vision insurance +## SIP Types -- No paid time off +**Standard SIP**: Describes a new feature or change to the Swarms framework +**Process SIP**: Describes changes to development processes, governance, or community guidelines +**Informational SIP**: Provides information or guidelines to the community without proposing changes -- No life or AD&D insurance +## Submitting a SIP -- No short-term or long-term disability insurance +1. **Discuss First**: Post your idea in [GitHub Discussions](https://github.com/kyegomez/swarms/discussions) to gauge community interest +2. **Create Issue**: Submit your SIP as a GitHub Issue with the `SIP` and `proposal` labels +3. **Follow Format**: Use the SIP template format below +4. **Engage Community**: Respond to feedback and iterate on your proposal -- No 401(k) plan +## SIP Format -**Working hours:** 9 AM to 10 PM, every day, 7 days a week. This is not for people who seek work-life balance. +### Required Sections ---- +#### **SIP Header** +``` +Title: [Descriptive title] +Author: [Your name and contact] +Type: [Standard/Process/Informational] +Status: Proposal +Created: [Date] +``` -### Hiring Process: How to Join Swarms -We have a simple 3-step hiring process: +#### **Abstract** (200 words max) +A brief summary of what you're proposing and why. -**NOTE** We do not consider applicants who have not previously submitted a PR, to be considered a PR containing a new feature of a bug fixed must be submitted. +#### **Motivation** +- What problem does this solve? +- Why can't the current framework handle this? +- What are the benefits to the Swarms ecosystem? -1. **Submit a pull request (PR)**: Start by submitting an approved PR to the [Swarms GitHub repository](https://github.com/kyegomez/swarms) or the appropriate repository . -2. **Code review**: Our technical team will review your PR. If it meets our standards, you will be invited for a quick interview. -3. **Final interview**: Discuss your contributions and approach with our team. If you pass, you're in! +#### **Specification** +- Detailed technical description +- API changes or new interfaces +- Code examples showing usage +- Integration points with existing framework -There are no recruiters. All evaluations are done by our technical team. +#### **Implementation Plan** +- High-level implementation approach +- Breaking changes (if any) +- Migration path for existing users +- Testing strategy ---- +#### **Alternatives Considered** +- Other approaches you evaluated +- Why you chose this solution +- Trade-offs and limitations -# Location +### Optional Sections -- **Palo Alto** CA Our Palo Alto office houses the majority of our core research teams including our prompting, agent design, and model training +#### **Reference Implementation** +Link to prototype code or proof-of-concept (can be added later) -- **Miami** Our miami office holds prompt engineering, agent design, and more. +#### **Security Considerations** +Any security implications or requirements +## SIP Workflow -### Open Roles at Swarms +``` +Proposal → Draft → Review → Accepted/Rejected → Final +``` -**Infrastructure Engineer** +1. **Proposal**: Initial submission as GitHub Issue +2. **Draft**: Maintainer assigns SIP number and `draft` label +3. **Review**: Community and maintainer review period +4. **Decision**: Accepted, rejected, or needs revision +5. **Final**: Implementation completed and merged -- Build and maintain the systems that run our AI multi-agent infrastructure. +## SIP Status -- Expertise in Skypilot, AWS, Terraform. +- **Proposal**: Newly submitted, awaiting initial review +- **Draft**: Under active discussion and refinement +- **Review**: Formal review by maintainers +- **Accepted**: Approved for implementation +- **Rejected**: Not accepted (with reasons) +- **Final**: Implementation completed and merged +- **Withdrawn**: Author withdrew the proposal -- Ensure seamless, high-availability environments for agent operations. +## Review Process -**Agent Engineer** +- SIPs are reviewed during regular maintainer meetings +- Community feedback is collected via GitHub comments +- Acceptance requires: + - Clear benefit to the Swarms ecosystem + - Technical feasibility + - Community support + - Working prototype (for complex features) -- Design, develop, and orchestrate complex swarms of AI agents. +## Getting Help -- Extensive experience with Python, multi-agent systems, and neural networks. +- **Discussions**: Use [GitHub Discussions](https://github.com/kyegomez/swarms/discussions) for questions +- **Documentation**: Check [docs.swarms.world](https://docs.swarms.world) for framework details +- **Examples**: Look at existing SIPs for reference -- Ability to create dynamic and efficient agent architectures from scratch. +## SIP Template -**Prompt Engineer** +When creating your SIP, copy this template: -- Craft highly optimized prompts that drive our LLM-based agents. +```markdown +# SIP-XXX: [Title] -- Specialize in instruction-based prompts, multi-shot examples, and production-grade deployment. +**Author**: [Your name] <[email]> +**Type**: Standard +**Status**: Proposal +**Created**: [Date] -- Collaborate with agents to deliver state-of-the-art solutions. +## Abstract -**Front-End Engineer** +[Brief 200-word summary] -- Build sleek, intuitive interfaces for interacting with swarms of agents. +## Motivation -- Proficiency in Next.js, FastAPI, and modern front-end technologies. +[Why is this needed? What problem does it solve?] -- Design with the user experience in mind, integrating complex AI features into simple workflows. +## Specification +[Detailed technical description with code examples] --------------------------------------------------- +## Implementation Plan -# File: corporate/metric.md +[How will this be built? Any breaking changes?] -# The Golden Metric: 95% User-Task-Completion-Satisfaction Rate +## Alternatives Considered -In the world of Swarms, there’s one metric that stands above the rest: the User-Task-Completion-Satisfaction (UTCS) rate. This metric is the heart of our system, the pulse that keeps us moving forward. It’s not just a number; it’s a reflection of our commitment to our users and a measure of our success. +[Other approaches and why you chose this one] -## What is the UTCS Rate? -The UTCS rate is a measure of how reliably and quickly Swarms can satisfy a user demand. It’s calculated by dividing the number of tasks completed to the user’s satisfaction by the total number of tasks. Multiply that by 100, and you’ve got your UTCS rate. +## Reference Implementation -But what does it mean to complete a task to the user’s satisfaction? It means that the task is not only completed, but completed in a way that meets or exceeds the user’s expectations. It’s about quality, speed, and reliability. +[Link to prototype code if available] +``` -## Why is the UTCS Rate Important? -The UTCS rate is a direct reflection of the user experience. A high UTCS rate means that users are getting what they need from Swarms, and they’re getting it quickly and reliably. It means that Swarms is doing its job, and doing it well. +--- -But the UTCS rate is not just about user satisfaction. It’s also a measure of Swarms’ efficiency and effectiveness. A high UTCS rate means that Swarms is able to complete tasks quickly and accurately, with minimal errors or delays. It’s a sign of a well-oiled machine. +**Note**: This process is designed to be lightweight while ensuring important changes get proper community review. For questions about whether your idea needs a SIP, start a discussion in the GitHub Discussions forum. -## How Do We Achieve a 95% UTCS Rate? -Achieving a 95% UTCS rate is no small feat. It requires a deep understanding of our users and their needs, a robust and reliable system, and a commitment to continuous improvement. +-------------------------------------------------- -### Here are some strategies we’re implementing to reach our goal: +# File: quickstart.md -* Understanding User Needs: We must have agents that gain an understanding of the user's objective and break it up into it's most fundamental building blocks -* Improving System Reliability: We’re working to make Swarms more reliable, reducing errors and improving the accuracy of task completion. This includes improving our algorithms, refining our processes, and investing in quality assurance. +# Welcome to Swarms Docs Home -* Optimizing for Speed: We’re optimizing Swarms to complete tasks as quickly as possible, without sacrificing quality. This includes improving our infrastructure, streamlining our workflows, and implementing performance optimizations. +[![Join our Discord](https://img.shields.io/badge/Discord-Join%20our%20server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/jM3Z6M9uMq) [![Subscribe on YouTube](https://img.shields.io/badge/YouTube-Subscribe-red?style=for-the-badge&logo=youtube&logoColor=white)](https://www.youtube.com/@kyegomez3242) [![Connect on LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-blue?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/kye-g-38759a207/) [![Follow on X.com](https://img.shields.io/badge/X.com-Follow-1DA1F2?style=for-the-badge&logo=x&logoColor=white)](https://x.com/swarms_corp) -*Iterating and Improving: We’re committed to continuous improvement. We’re constantly monitoring our UTCS rate and other key metrics, and we’re always looking for ways to improve. We’re not afraid to experiment, iterate, and learn from our mistakes. +## What is Swarms? -Achieving a 95% UTCS rate is a challenging goal, but it’s a goal worth striving for. It’s a goal that will drive us to improve, innovate, and deliver the best possible experience for our users. And in the end, that’s what Swarms is all about. +**Swarms** is the **first and most reliable multi-agent production-grade framework** designed to orchestrate intelligent AI agents at scale. Built for enterprise applications, Swarms enables you to create sophisticated multi-agent systems that can handle complex tasks through collaboration, parallel processing, and intelligent task distribution. +### Key Capabilities +- **🏢 Production-Ready**: Enterprise-grade infrastructure with high reliability, comprehensive logging, and robust error handling +- **🤖 Multi-Agent Orchestration**: Support for hierarchical swarms, parallel processing, sequential workflows, and dynamic agent rearrangement +- **🔄 Flexible Integration**: Multi-model support, custom agent creation, extensive tool library, and multiple memory systems +- **📈 Scalable Architecture**: Concurrent processing, resource management, load balancing, and horizontal scaling capabilities +- **🛠️ Developer-Friendly**: Simple API, extensive documentation, active community, and CLI tools for rapid development +- **🔐 Enterprise Security**: Built-in error handling, rate limiting, monitoring integration, and audit logging -# Your Feedback Matters: Help Us Optimize the UTCS Rate +### Why Choose Swarms? -As we initiate the journey of Swarms, we seek your feedback to better guide our growth and development. Your opinions and suggestions are crucial for us, helping to mold our product, pricing, branding, and a host of other facets that influence your experience. +Swarms stands out as the **most reliable multi-agent framework** because it was built from the ground up for production environments. Unlike other frameworks that focus on research or simple demos, Swarms provides the infrastructure, tooling, and best practices needed to deploy multi-agent systems in real-world applications. -## Your Insights on the UTCS Rate -Our goal is to maintain a UTCS (User-Task-Completion-Satisfaction) rate of 95%. This metric is integral to the success of Swarms, indicating the efficiency and effectiveness with which we satisfy user requests. However, it's a metric that we can't optimize alone - we need your help. +Whether you're building financial analysis systems, healthcare diagnostics, manufacturing optimization, or any other complex multi-agent application, Swarms provides the foundation you need to succeed. -Here's what we want to understand from you: +Get started learning swarms with the following examples and more. -1. **Satisfaction:** What does a "satisfactorily completed task" mean to you? Are there specific elements that contribute to a task being carried out to your satisfaction? -2. **Timeliness:** How important is speed in the completion of a task? What would you consider a reasonable timeframe for a task to be completed? -3. **Usability:** How intuitive and user-friendly do you find the Swarms platform? Are there any aspects of the platform that you believe could be enhanced? -4. **Reliability:** How much does consistency in performance matter to you? Can you share any experiences where Swarms either met or fell short of your expectations? -5. **Value for Money:** How do you perceive our pricing? Does the value Swarms provides align with the costs? +## Install 💻 -We invite you to share your experiences, thoughts, and ideas. Whether it's a simple suggestion or an in-depth critique, we appreciate and value your input. +```bash +$ pip3 install -U swarms +``` -## Your Feedback: The Backbone of our Growth -Your feedback is the backbone of Swarms' evolution. It drives us to refine our strategies, fuels our innovative spirit, and, most importantly, enables us to serve you better. +### Using uv (Recommended) +[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver, written in Rust. -As we launch, we open the conversation around these key aspects of Swarms, and we look forward to understanding your expectations, your needs, and how we can deliver the best experience for you. +```bash +# Install uv +$ curl -LsSf https://astral.sh/uv/install.sh | sh -So, let's start this conversation - how can we make Swarms work best for you? +# Install swarms using uv +$ uv pip install swarms +``` +### Using poetry +```bash +# Install poetry if you haven't already +$ curl -sSL https://install.python-poetry.org | python3 - -Guide Our Growth: Help Optimize Swarms -As we launch Swarms, your feedback is critical for enhancing our product, pricing, and branding. A key aim for us is a User-Task-Completion-Satisfaction (UTCS) rate of 95% - indicating our efficiency and effectiveness in meeting user needs. However, we need your insights to optimize this. +# Add swarms to your project +$ poetry add swarms +``` -Here's what we're keen to understand: +### From source +```bash +# Clone the repository +$ git clone https://github.com/kyegomez/swarms.git +$ cd swarms -Satisfaction: Your interpretation of a "satisfactorily completed task". -Timeliness: The importance of speed in task completion for you. -Usability: Your experiences with our platform’s intuitiveness and user-friendliness. -Reliability: The significance of consistent performance to you. -Value for Money: Your thoughts on our pricing and value proposition. -We welcome your thoughts, experiences, and suggestions. Your feedback fuels our evolution, driving us to refine strategies, boost innovation, and enhance your experience. +# Install with pip +$ pip install -e . +``` -Let's start the conversation - how can we make Swarms work best for you? +--- +## Environment Configuration --------- +[Learn more about the environment configuration here](https://docs.swarms.world/en/latest/swarms/install/env/) -**The Golden Metric Analysis: The Ultimate UTCS Paradigm for Swarms** +``` +OPENAI_API_KEY="" +WORKSPACE_DIR="agent_workspace" +ANTHROPIC_API_KEY="" +GROQ_API_KEY="" +``` -### Introduction -In our ongoing journey to perfect Swarms, understanding how our product fares in the eyes of the end-users is paramount. Enter the User-Task-Completion-Satisfaction (UTCS) rate - our primary metric that gauges how reliably and swiftly Swarms can meet user demands. As we steer Swarms towards achieving a UTCS rate of 95%, understanding this metric's core and how to refine it becomes vital. -### Decoding UTCS: An Analytical Overview +### 🤖 Your First Agent -The UTCS rate is not merely about task completion; it's about the comprehensive experience. Therefore, its foundations lie in: +An **Agent** is the fundamental building block of a swarm—an autonomous entity powered by an LLM + Tools + Memory. [Learn more Here](https://docs.swarms.world/en/latest/swarms/structs/agent/) -1. **Quality**: Ensuring tasks are executed flawlessly. -2. **Speed**: Delivering results in the shortest possible time. -3. **Reliability**: Consistency in quality and speed across all tasks. +```python +from swarms import Agent -We can represent the UTCS rate with the following equation: +# Initialize a new agent +agent = Agent( + model_name="gpt-4o-mini", # Specify the LLM + max_loops=1, # Set the number of interactions + interactive=True, # Enable interactive mode for real-time feedback +) -```latex -\[ UTCS Rate = \frac{(Completed Tasks \times User Satisfaction)}{(Total Tasks)} \times 100 \] +# Run the agent with a task +agent.run("What are the key benefits of using a multi-agent system?") ``` -Where: -- Completed Tasks refer to the number of tasks Swarms executes without errors. -- User Satisfaction is the subjective component, gauged through feedback mechanisms. This could be on a scale of 1-10 (or a percentage). -- Total Tasks refer to all tasks processed by Swarms, regardless of the outcome. +### 🤝 Your First Swarm: Multi-Agent Collaboration -### The Golden Metric: Swarm Efficiency Index (SEI) +A **Swarm** consists of multiple agents working together. This simple example creates a two-agent workflow for researching and writing a blog post. [Learn More About SequentialWorkflow](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/) -However, this basic representation doesn't factor in a critical component: system performance. Thus, we introduce the Swarm Efficiency Index (SEI). The SEI encapsulates not just the UTCS rate but also system metrics like memory consumption, number of tasks, and time taken. By blending these elements, we aim to present a comprehensive view of Swarm's prowess. +```python +from swarms import Agent, SequentialWorkflow -Here’s the formula: +# Agent 1: The Researcher +researcher = Agent( + agent_name="Researcher", + system_prompt="Your job is to research the provided topic and provide a detailed summary.", + model_name="gpt-4o-mini", +) -```latex -\[ SEI = \frac{UTCS Rate}{(Memory Consumption + Time Window + Task Complexity)} \] -``` +# Agent 2: The Writer +writer = Agent( + agent_name="Writer", + system_prompt="Your job is to take the research summary and write a beautiful, engaging blog post about it.", + model_name="gpt-4o-mini", +) -Where: -- Memory Consumption signifies the system resources used to accomplish tasks. -- Time Window is the timeframe in which the tasks were executed. -- Task Complexity could be a normalized scale that defines how intricate a task is (e.g., 1-5, with 5 being the most complex). +# Create a sequential workflow where the researcher's output feeds into the writer's input +workflow = SequentialWorkflow(agents=[researcher, writer]) -Rationale: -- **Incorporating Memory Consumption**: A system that uses less memory but delivers results is more efficient. By inverting memory consumption in the formula, we emphasize that as memory usage goes down, SEI goes up. - -- **Considering Time**: Time is of the essence. The faster the results without compromising quality, the better. By adding the Time Window, we emphasize that reduced task execution time increases the SEI. - -- **Factoring in Task Complexity**: Not all tasks are equal. A system that effortlessly completes intricate tasks is more valuable. By integrating task complexity, we can normalize the SEI according to the task's nature. +# Run the workflow on a task +final_post = workflow.run("The history and future of artificial intelligence") +print(final_post) -### Implementing SEI & Improving UTCS +``` -Using feedback from elder-plinius, we can better understand and improve SEI and UTCS: +----- -1. **Feedback Across Skill Levels**: By gathering feedback from users with different skill levels, we can refine our metrics, ensuring Swarms caters to all. +## 🏗️ Multi-Agent Architectures For Production Deployments -2. **Simplifying Setup**: Detailed guides can help newcomers swiftly get on board, thus enhancing user satisfaction. +`swarms` provides a variety of powerful, pre-built multi-agent architectures enabling you to orchestrate agents in various ways. Choose the right structure for your specific problem to build efficient and reliable production systems. -3. **Enhancing Workspace and Agent Management**: A clearer view of the Swarm's internal structure, combined with on-the-go adjustments, can improve both the speed and quality of results. +| **Architecture** | **Description** | **Best For** | +|---|---|---| +| **[SequentialWorkflow](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/)** | Agents execute tasks in a linear chain; one agent's output is the next one's input. | Step-by-step processes like data transformation pipelines, report generation. | +| **[ConcurrentWorkflow](https://docs.swarms.world/en/latest/swarms/structs/concurrent_workflow/)** | Agents run tasks simultaneously for maximum efficiency. | High-throughput tasks like batch processing, parallel data analysis. | +| **[AgentRearrange](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/)** | Dynamically maps complex relationships (e.g., `a -> b, c`) between agents. | Flexible and adaptive workflows, task distribution, dynamic routing. | +| **[GraphWorkflow](https://docs.swarms.world/en/latest/swarms/structs/graph_workflow/)** | Orchestrates agents as nodes in a Directed Acyclic Graph (DAG). | Complex projects with intricate dependencies, like software builds. | +| **[MixtureOfAgents (MoA)](https://docs.swarms.world/en/latest/swarms/structs/moa/)** | Utilizes multiple expert agents in parallel and synthesizes their outputs. | Complex problem-solving, achieving state-of-the-art performance through collaboration. | +| **[GroupChat](https://docs.swarms.world/en/latest/swarms/structs/group_chat/)** | Agents collaborate and make decisions through a conversational interface. | Real-time collaborative decision-making, negotiations, brainstorming. | +| **[ForestSwarm](https://docs.swarms.world/en/latest/swarms/structs/forest_swarm/)** | Dynamically selects the most suitable agent or tree of agents for a given task. | Task routing, optimizing for expertise, complex decision-making trees. | +| **[SpreadSheetSwarm](https://docs.swarms.world/en/latest/swarms/structs/spreadsheet_swarm/)** | Manages thousands of agents concurrently, tracking tasks and outputs in a structured format. | Massive-scale parallel operations, large-scale data generation and analysis. | +| **[SwarmRouter](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/)** | Universal orchestrator that provides a single interface to run any type of swarm with dynamic selection. | Simplifying complex workflows, switching between swarm strategies, unified multi-agent management. | -4. **Introducing System Suggestions**: A proactive Swarms that provides real-time insights and recommendations can drastically enhance user satisfaction, thus pushing up the UTCS rate. +----- -### Conclusion +### SequentialWorkflow -The UTCS rate is undeniably a pivotal metric for Swarms. However, with the introduction of the Swarm Efficiency Index (SEI), we have an opportunity to encapsulate a broader spectrum of performance indicators, leading to a more holistic understanding of Swarms' efficiency. By consistently optimizing for SEI, we can ensure that Swarms not only meets user expectations but also operates at peak system efficiency. +A `SequentialWorkflow` executes tasks in a strict order, forming a pipeline where each agent builds upon the work of the previous one. `SequentialWorkflow` is Ideal for processes that have clear, ordered steps. This ensures that tasks with dependencies are handled correctly. +```python +from swarms import Agent, SequentialWorkflow ----------------- -**Research Analysis: Tracking and Ensuring Reliability of Swarm Metrics at Scale** +# Initialize agents for a 3-step process +# 1. Generate an idea +idea_generator = Agent(agent_name="IdeaGenerator", system_prompt="Generate a unique startup idea.", model_name="gpt-4o-mini") +# 2. Validate the idea +validator = Agent(agent_name="Validator", system_prompt="Take this startup idea and analyze its market viability.", model_name="gpt-4o-mini") +# 3. Create a pitch +pitch_creator = Agent(agent_name="PitchCreator", system_prompt="Write a 3-sentence elevator pitch for this validated startup idea.", model_name="gpt-4o-mini") -### 1. Introduction +# Create the sequential workflow +workflow = SequentialWorkflow(agents=[idea_generator, validator, pitch_creator]) -In our pursuit to optimize the User-Task-Completion-Satisfaction (UTCS) rate and Swarm Efficiency Index (SEI), reliable tracking of these metrics at scale becomes paramount. This research analysis delves into methodologies, technologies, and practices that can be employed to monitor these metrics accurately and efficiently across vast data sets. +# Run the workflow +elevator_pitch = workflow.run() +print(elevator_pitch) +``` -### 2. Why Tracking at Scale is Challenging +----- -The primary challenges include: -- **Volume of Data**: As Swarms grows, the data generated multiplies exponentially. -- **Variability of Data**: Diverse user inputs lead to myriad output scenarios. -- **System Heterogeneity**: Different configurations and deployments can yield variable results. +### ConcurrentWorkflow (with `SpreadSheetSwarm`) -### 3. Strategies for Scalable Tracking +A concurrent workflow runs multiple agents simultaneously. `SpreadSheetSwarm` is a powerful implementation that can manage thousands of concurrent agents and log their outputs to a CSV file. Use this architecture for high-throughput tasks that can be performed in parallel, drastically reducing execution time. -#### 3.1. Distributed Monitoring Systems +```python +from swarms import Agent, SpreadSheetSwarm -**Recommendation**: Implement distributed systems like Prometheus or InfluxDB. +# Define a list of tasks (e.g., social media posts to generate) +platforms = ["Twitter", "LinkedIn", "Instagram"] -**Rationale**: -- Ability to collect metrics from various Swarm instances concurrently. -- Scalable and can handle vast data influxes. - -#### 3.2. Real-time Data Processing +# Create an agent for each task +agents = [ + Agent( + agent_name=f"{platform}-Marketer", + system_prompt=f"Generate a real estate marketing post for {platform}.", + model_name="gpt-4o-mini", + ) + for platform in platforms +] -**Recommendation**: Use stream processing systems like Apache Kafka or Apache Flink. +# Initialize the swarm to run these agents concurrently +swarm = SpreadSheetSwarm( + agents=agents, + autosave_on=True, + save_file_path="marketing_posts.csv", +) -**Rationale**: -- Enables real-time metric calculation. -- Can handle high throughput and low-latency requirements. +# Run the swarm with a single, shared task description +property_description = "A beautiful 3-bedroom house in sunny California." +swarm.run(task=f"Generate a post about: {property_description}") +# Check marketing_posts.csv for the results! +``` -#### 3.3. Data Sampling +--- -**Recommendation**: Random or stratified sampling of user sessions. +### AgentRearrange -**Rationale**: -- Reduces the data volume to be processed. -- Maintains representativeness of overall user experience. +Inspired by `einsum`, `AgentRearrange` lets you define complex, non-linear relationships between agents using a simple string-based syntax. [Learn more](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/). This architecture is Perfect for orchestrating dynamic workflows where agents might work in parallel, sequence, or a combination of both. -### 4. Ensuring Reliability in Data Collection +```python +from swarms import Agent, AgentRearrange -#### 4.1. Redundancy +# Define agents +researcher = Agent(agent_name="researcher", model_name="gpt-4o-mini") +writer = Agent(agent_name="writer", model_name="gpt-4o-mini") +editor = Agent(agent_name="editor", model_name="gpt-4o-mini") -**Recommendation**: Integrate redundancy into data collection nodes. +# Define a flow: researcher sends work to both writer and editor simultaneously +# This is a one-to-many relationship +flow = "researcher -> writer, editor" -**Rationale**: -- Ensures no single point of failure. -- Data loss prevention in case of system malfunctions. +# Create the rearrangement system +rearrange_system = AgentRearrange( + agents=[researcher, writer, editor], + flow=flow, +) -#### 4.2. Anomaly Detection +# Run the system +# The researcher will generate content, and then both the writer and editor +# will process that content in parallel. +outputs = rearrange_system.run("Analyze the impact of AI on modern cinema.") +print(outputs) +``` -**Recommendation**: Implement AI-driven anomaly detection systems. -**Rationale**: -- Identifies outliers or aberrations in metric calculations. -- Ensures consistent and reliable data interpretation. + -**Recommendation**: Regularly conduct A/B tests for new tracking methods or adjustments. +---- -**Rationale**: -- Determines the most effective methods for data collection. -- Validates new tracking techniques against established ones. +### SwarmRouter: The Universal Swarm Orchestrator -### 6. Conclusion +The `SwarmRouter` simplifies building complex workflows by providing a single interface to run any type of swarm. Instead of importing and managing different swarm classes, you can dynamically select the one you need just by changing the `swarm_type` parameter. [Read the full documentation](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/) -To successfully and reliably track the UTCS rate and SEI at scale, it's essential to combine robust monitoring tools, data processing methodologies, and validation techniques. By doing so, Swarms can ensure that the metrics collected offer a genuine reflection of system performance and user satisfaction. Regular feedback and iterative refinement, rooted in a culture of continuous improvement, will further enhance the accuracy and reliability of these essential metrics. +This makes your code cleaner and more flexible, allowing you to switch between different multi-agent strategies with ease. Here's a complete example that shows how to define agents and then use `SwarmRouter` to execute the same task using different collaborative strategies. --------------------------------------------------- +```python +from swarms import Agent +from swarms.structs.swarm_router import SwarmRouter, SwarmType + +# Define a few generic agents +writer = Agent(agent_name="Writer", system_prompt="You are a creative writer.", model_name="gpt-4o-mini") +editor = Agent(agent_name="Editor", system_prompt="You are an expert editor for stories.", model_name="gpt-4o-mini") +reviewer = Agent(agent_name="Reviewer", system_prompt="You are a final reviewer who gives a score.", model_name="gpt-4o-mini") + +# The agents and task will be the same for all examples +agents = [writer, editor, reviewer] +task = "Write a short story about a robot who discovers music." + +# --- Example 1: SequentialWorkflow --- +# Agents run one after another in a chain: Writer -> Editor -> Reviewer. +print("Running a Sequential Workflow...") +sequential_router = SwarmRouter(swarm_type=SwarmType.SequentialWorkflow, agents=agents) +sequential_output = sequential_router.run(task) +print(f"Final Sequential Output:\n{sequential_output}\n") + +# --- Example 2: ConcurrentWorkflow --- +# All agents receive the same initial task and run at the same time. +print("Running a Concurrent Workflow...") +concurrent_router = SwarmRouter(swarm_type=SwarmType.ConcurrentWorkflow, agents=agents) +concurrent_outputs = concurrent_router.run(task) +# This returns a dictionary of each agent's output +for agent_name, output in concurrent_outputs.items(): + print(f"Output from {agent_name}:\n{output}\n") + +# --- Example 3: MixtureOfAgents --- +# All agents run in parallel, and a special 'aggregator' agent synthesizes their outputs. +print("Running a Mixture of Agents Workflow...") +aggregator = Agent( + agent_name="Aggregator", + system_prompt="Combine the story, edits, and review into a final document.", + model_name="gpt-4o-mini" +) +moa_router = SwarmRouter( + swarm_type=SwarmType.MixtureOfAgents, + agents=agents, + aggregator_agent=aggregator, # MoA requires an aggregator +) +aggregated_output = moa_router.run(task) +print(f"Final Aggregated Output:\n{aggregated_output}\n") +``` -# File: corporate/purpose.md +The `SwarmRouter` is a powerful tool for simplifying multi-agent orchestration. It provides a consistent and flexible way to deploy different collaborative strategies, allowing you to build more sophisticated applications with less code. -## Purpose -Artificial Intelligence has grown at an exponential rate over the past decade. Yet, we are far from fully harnessing its potential. Today's AI operates in isolation, each working separately in their corner. But life doesn't work like that. The world doesn't work like that. Success isn't built in silos; it's built in teams. +------- -Imagine a world where AI models work in unison. Where they can collaborate, interact, and pool their collective intelligence to achieve more than any single model could. This is the future we envision. But today, we lack a framework for AI to collaborate effectively, to form a true swarm of intelligent agents. +### MixtureOfAgents (MoA) +The `MixtureOfAgents` architecture processes tasks by feeding them to multiple "expert" agents in parallel. Their diverse outputs are then synthesized by an aggregator agent to produce a final, high-quality result. [Learn more here](https://docs.swarms.world/en/latest/swarms/examples/moa_example/) -This is a difficult problem, one that has eluded solution. It requires sophisticated systems that can allow individual models to not just communicate but also understand each other, pool knowledge and resources, and create collective intelligence. This is the next frontier of AI. +```python +from swarms import Agent, MixtureOfAgents -But here at Swarms, we have a secret sauce. It's not just a technology or a breakthrough invention. It's a way of thinking - the philosophy of rapid iteration. With each cycle, we make massive progress. We experiment, we learn, and we grow. We have developed a pioneering framework that can enable AI models to work together as a swarm, combining their strengths to create richer, more powerful outputs. +# Define expert agents +financial_analyst = Agent(agent_name="FinancialAnalyst", system_prompt="Analyze financial data.", model_name="gpt-4o-mini") +market_analyst = Agent(agent_name="MarketAnalyst", system_prompt="Analyze market trends.", model_name="gpt-4o-mini") +risk_analyst = Agent(agent_name="RiskAnalyst", system_prompt="Analyze investment risks.", model_name="gpt-4o-mini") -We are uniquely positioned to take on this challenge with 1,500+ devoted researchers in Agora. We have assembled a team of world-class experts, experienced and driven, united by a shared vision. Our commitment to breaking barriers, pushing boundaries, and our belief in the power of collective intelligence makes us the best team to usher in this future to fundamentally advance our species, Humanity. +# Define the aggregator agent +aggregator = Agent( + agent_name="InvestmentAdvisor", + system_prompt="Synthesize the financial, market, and risk analyses to provide a final investment recommendation.", + model_name="gpt-4o-mini" +) ---- +# Create the MoA swarm +moa_swarm = MixtureOfAgents( + agents=[financial_analyst, market_analyst, risk_analyst], + aggregator_agent=aggregator, +) --------------------------------------------------- +# Run the swarm +recommendation = moa_swarm.run("Should we invest in NVIDIA stock right now?") +print(recommendation) +``` -# File: corporate/research.md +---- -# Research Lists -A compilation of projects, papers, blogs in autonomous agents. +### GroupChat -## Table of Contents +`GroupChat` creates a conversational environment where multiple agents can interact, discuss, and collaboratively solve a problem. You can define the speaking order or let it be determined dynamically. This architecture is ideal for tasks that benefit from debate and multi-perspective reasoning, such as contract negotiation, brainstorming, or complex decision-making. -- [Introduction](#introduction) -- [Projects](#projects) -- [Articles](#articles) -- [Talks](#talks) - - -## Projects - -### Developer tools -- [2023/8/10] [ModelScope-Agent](https://github.com/modelscope/modelscope-agent) - An Agent Framework Connecting Models in ModelScope with the World -- [2023/05/25] [Gorilla](https://github.com/ShishirPatil/gorilla) - An API store for LLMs -- [2023/03/31] [BMTools](https://github.com/OpenBMB/BMTools) - Tool Learning for Big Models, Open-Source Solutions of ChatGPT-Plugins -- [2023/03/09] [LMQL](https://github.com/eth-sri/lmql) - A query language for programming (large) language models. -- [2022/10/25] [Langchain](https://github.com/hwchase17/langchain) - ⚡ Building applications with LLMs through composability ⚡ - -### Applications -- [2023/07/08] [ShortGPT](https://github.com/RayVentura/ShortGPT) - 🚀🎬 ShortGPT - An experimental AI framework for automated short/video content creation. Enables creators to rapidly produce, manage, and deliver content using AI and automation. -- [2023/07/05] [gpt-researcher](https://github.com/assafelovic/gpt-researcher) - GPT based autonomous agent that does online comprehensive research on any given topic -- [2023/07/04] [DemoGPT](https://github.com/melih-unsal/DemoGPT) - 🧩DemoGPT enables you to create quick demos by just using prompts. [[demo]](demogpt.io) -- [2023/06/30] [MetaGPT](https://github.com/geekan/MetaGPT) - 🌟 The Multi-Agent Framework: Given one line Requirement, return PRD, Design, Tasks, Repo -- [2023/06/11] [gpt-engineer](https://github.com/AntonOsika/gpt-engineer) - Specify what you want it to build, the AI asks for clarification, and then builds it. -- [2023/05/16] [SuperAGI](https://github.com/TransformerOptimus/SuperAGI) - <⚡️> SuperAGI - A dev-first open source autonomous AI agent framework. Enabling developers to build, manage & run useful autonomous agents quickly and reliably. -- [2023/05/13] [Developer](https://github.com/smol-ai/developer) - Human-centric & Coherent Whole Program Synthesis aka your own personal junior developer -- [2023/04/07] [AgentGPT](https://github.com/reworkd/AgentGPT) - 🤖 Assemble, configure, and deploy autonomous AI Agents in your browser. [[demo]](agentgpt.reworkd.ai) -- [2023/04/03] [BabyAGI](https://github.com/yoheinakajima/babyagi) - an example of an AI-powered task management system -- [2023/03/30] [AutoGPT](https://github.com/Significant-Gravitas/Auto-GPT) - An experimental open-source attempt to make GPT-4 fully autonomous. - -### Benchmarks -- [2023/08/07] [AgentBench](https://github.com/THUDM/AgentBench) - A Comprehensive Benchmark to Evaluate LLMs as Agents. [paper](https://arxiv.org/abs/2308.03688) -- [2023/06/18] [Auto-GPT-Benchmarks](https://github.com/Significant-Gravitas/Auto-GPT-Benchmarks) - A repo built for the purpose of benchmarking the performance of agents, regardless of how they are set up and how they work. -- [2023/05/28] [ToolBench](https://github.com/OpenBMB/ToolBench) - An open platform for training, serving, and evaluating large language model for tool learning. - -## Articles -### Research Papers -- [2023/08/11] [BOLAA: Benchmarking and Orchestrating LLM-Augmented Autonomous Agents](https://arxiv.org/pdf/2308.05960v1.pdf), Zhiwei Liu, et al. -- [2023/07/31] [ToolLLM: Facilitating Large Language Models to Master 16000+ Real-world APIs](https://arxiv.org/abs/2307.16789), Yujia Qin, et al. -- [2023/07/16] [Communicative Agents for Software Development](https://arxiv.org/abs/2307.07924), Chen Qian, et al. -- [2023/06/09] [Mind2Web: Towards a Generalist Agent for the Web](https://arxiv.org/pdf/2306.06070.pdf), Xiang Deng, et al. [[code]](https://github.com/OSU-NLP-Group/Mind2Web) [[demo]](https://osu-nlp-group.github.io/Mind2Web/) -- [2023/06/05] [Orca: Progressive Learning from Complex Explanation Traces of GPT-4](https://arxiv.org/pdf/2306.02707.pdf), Subhabrata Mukherjee et al. -- [2023/05/25] [Voyager: An Open-Ended Embodied Agent with Large Language Models](https://arxiv.org/pdf/2305.16291.pdf), Guanzhi Wang, et al. [[code]](https://github.com/MineDojo/Voyager) [[website]](https://voyager.minedojo.org/) -- [2023/05/23] [ReWOO: Decoupling Reasoning from Observations for Efficient Augmented Language Models](https://arxiv.org/pdf/2305.18323.pdf), Binfeng Xu, et al. [[code]](https://github.com/billxbf/ReWOO) -- [2023/05/17] [Tree of Thoughts: Deliberate Problem Solving with Large Language Models](https://arxiv.org/abs/2305.10601), Shunyu Yao, et al.[[code]](https://github.com/kyegomez/tree-of-thoughts) [[code-orig]](https://github.com/ysymyth/tree-of-thought-llm) -- [2023/05/12] [MEGABYTE: Predicting Million-byte Sequences with Multiscale Transformers](https://arxiv.org/abs/2305.07185), Lili Yu, et al. -- [2023/05/19] [FrugalGPT: How to Use Large Language Models While Reducing Cost and Improving Performance](https://arxiv.org/abs/2305.05176), Lingjiao Chen, et al. -- [2023/05/06] [Plan-and-Solve Prompting: Improving Zero-Shot Chain-of-Thought Reasoning by Large Language Models](https://arxiv.org/abs/2305.04091), Lei Wang, et al. -- [2023/05/01] [Learning to Reason and Memorize with Self-Notes](https://arxiv.org/abs/2305.00833), Jack Lanchantin, et al. -- [2023/04/24] [WizardLM: Empowering Large Language Models to Follow Complex Instructions](https://arxiv.org/abs/2304.12244), Can Xu, et al. -- [2023/04/22] [LLM+P: Empowering Large Language Models with Optimal Planning Proficiency](https://arxiv.org/abs/2304.11477), Bo Liu, et al. -- [2023/04/07] [Generative Agents: Interactive Simulacra of Human Behavior](https://arxiv.org/abs/2304.03442), Joon Sung Park, et al. [[code]](https://github.com/mkturkcan/generative-agents) -- [2023/03/30] [Self-Refine: Iterative Refinement with Self-Feedback](https://arxiv.org/abs/2303.17651), Aman Madaan, et al.[[code]](https://github.com/madaan/self-refine) -- [2023/03/30] [HuggingGPT: Solving AI Tasks with ChatGPT and its Friends in HuggingFace](https://arxiv.org/pdf/2303.17580.pdf), Yongliang Shen, et al. [[code]](https://github.com/microsoft/JARVIS) [[demo]](https://huggingface.co/spaces/microsoft/HuggingGPT) -- [2023/03/20] [Reflexion: Language Agents with Verbal Reinforcement Learning](https://arxiv.org/pdf/2303.11366.pdf), Noah Shinn, et al. [[code]](https://github.com/noahshinn024/reflexion) -- [2023/03/04] [Towards A Unified Agent with Foundation Models](https://openreview.net/pdf?id=JK_B1tB6p-), Norman Di Palo et al. -- [2023/02/23] [Not what you've signed up for: Compromising Real-World LLM-Integrated Applications with Indirect Prompt Injection](https://arxiv.org/abs/2302.12173), Sahar Abdelnab, et al. -- [2023/02/09] [Toolformer: Language Models Can Teach Themselves to Use Tools](https://arxiv.org/pdf/2302.04761.pdf), Timo Schick, et al. [[code]](https://github.com/lucidrains/toolformer-pytorch) -- [2022/12/12] [LMQL: Prompting Is Programming: A Query Language for Large Language Models](https://arxiv.org/abs/2212.06094), Luca Beurer-Kellner, et al. -- [2022/10/06] [ReAct: Synergizing Reasoning and Acting in Language Models](https://arxiv.org/pdf/2210.03629.pdf), Shunyu Yao, et al. [[code]](https://github.com/ysymyth/ReAct) -- [2022/07/20] [Inner Monologue: Embodied Reasoning through Planning with Language Models](https://arxiv.org/pdf/2207.05608.pdf), Wenlong Huang, et al. [[demo]](https://innermonologue.github.io/) -- [2022/04/04] [Do As I Can, Not As I Say: Grounding Language in Robotic Affordances](), Michael Ahn, e al. [[demo]](https://say-can.github.io/) -- [2021/12/17] [WebGPT: Browser-assisted question-answering with human feedback](https://arxiv.org/pdf/2112.09332.pdf), Reiichiro Nakano, et al. -- [2021/06/17] [LoRA: Low-Rank Adaptation of Large Language Models](https://arxiv.org/abs/2106.09685), Edward J. Hu, et al. - - -### Blog Articles - -- [2023/08/14] [A Roadmap of AI Agents(Chinese)](https://zhuanlan.zhihu.com/p/649916692) By Haojie Pan -- [2023/06/23] [LLM Powered Autonomous Agents](https://lilianweng.github.io/posts/2023-06-23-agent/) By Lilian Weng -- [2023/06/11] [A CRITICAL LOOK AT AI-GENERATED SOFTWARE](https://spectrum.ieee.org/ai-software) By JAIDEEP VAIDYAHAFIZ ASIF -- [2023/04/29] [AUTO-GPT: UNLEASHING THE POWER OF AUTONOMOUS AI AGENTS](https://www.leewayhertz.com/autogpt/) By Akash Takyar -- [2023/04/20] [Conscious Machines: Experiments, Theory, and Implementations(Chinese)](https://pattern.swarma.org/article/230) By Jiang Zhang -- [2023/04/18] [Autonomous Agents & Agent Simulations](https://blog.langchain.dev/agents-round/) By Langchain -- [2023/04/16] [4 Autonomous AI Agents you need to know](https://towardsdatascience.com/4-autonomous-ai-agents-you-need-to-know-d612a643fa92) By Sophia Yang -- [2023/03/31] [ChatGPT that learns to use tools(Chinese)](https://zhuanlan.zhihu.com/p/618448188) By Haojie Pan - -### Talks -- [2023/06/05] [Two Paths to Intelligence](https://www.youtube.com/watch?v=rGgGOccMEiY&t=1497s) by Geoffrey Hinton -- [2023/05/24] [State of GPT](https://www.youtube.com/watch?v=bZQun8Y4L2A) by Andrej Karpathy | OpenAI +```python +from swarms import Agent, GroupChat +# Define agents for a debate +tech_optimist = Agent(agent_name="TechOptimist", system_prompt="Argue for the benefits of AI in society.", model_name="gpt-4o-mini") +tech_critic = Agent(agent_name="TechCritic", system_prompt="Argue against the unchecked advancement of AI.", model_name="gpt-4o-mini") --------------------------------------------------- +# Create the group chat +chat = GroupChat( + agents=[tech_optimist, tech_critic], + max_loops=4, # Limit the number of turns in the conversation +) -# File: corporate/roadmap.md +# Run the chat with an initial topic +conversation_history = chat.run( + "Let's discuss the societal impact of artificial intelligence." +) -## The Plan +# Print the full conversation +for message in conversation_history: + print(f"[{message['agent_name']}]: {message['content']}") +``` -### Phase 1: Building the Foundation -In the first phase, our focus is on building the basic infrastructure of Swarms. This includes developing key components like the Swarms class, integrating essential tools, and establishing task completion and evaluation logic. We'll also start developing our testing and evaluation framework during this phase. If you're interested in foundational work and have a knack for building robust, scalable systems, this phase is for you. -### Phase 2: Optimizing the System -In the second phase, we'll focus on optimizng Swarms by integrating more advanced features, improving the system's efficiency, and refining our testing and evaluation framework. This phase involves more complex tasks, so if you enjoy tackling challenging problems and contributing to the development of innovative features, this is the phase for you. -### Phase 3: Towards Super-Intelligence -The third phase of our bounty program is the most exciting - this is where we aim to achieve super-intelligence. In this phase, we'll be working on improving the swarm's capabilities, expanding its skills, and fine-tuning the system based on real-world testing and feedback. If you're excited about the future of AI and want to contribute to a project that could potentially transform the digital world, this is the phase for you. -Remember, our roadmap is a guide, and we encourage you to bring your own ideas and creativity to the table. We believe that every contribution, no matter how small, can make a difference. So join us on this exciting journey and help us create the future of Swarms. +-------------------------------------------------- +# File: swarms\agents\abstractagent.md +# swarms.agents --------------------------------------------------- +## 1. Introduction -# File: corporate/swarm_cloud.md +`AbstractAgent` is an abstract class that serves as a foundation for implementing AI agents. An agent is an entity that can communicate with other agents and perform actions. The `AbstractAgent` class allows for customization in the implementation of the `receive` method, enabling different agents to define unique actions for receiving and processing messages. -# The Swarm Cloud +`AbstractAgent` provides capabilities for managing tools and accessing memory, and has methods for running, chatting, and stepping through communication with other agents. -### Business Model Plan for Autonomous Agent Swarm Service +## 2. Class Definition -#### Service Description -- **Overview:** A platform allowing users to deploy swarms of autonomous agents in production-grade environments. -- **Target Users:** Industries requiring automation, monitoring, data collection, and more, such as manufacturing, logistics, agriculture, and surveillance. +```python +class AbstractAgent: + """An abstract class for AI agent. -#### Operational Strategy -- **Infrastructure:** Robust cloud infrastructure to support agent deployment and data processing. -- **Support and Maintenance:** Continuous support for software updates, troubleshooting, and user assistance. -- **Technology Development:** Ongoing R&D for enhancing agent capabilities and efficiency. + An agent can communicate with other agents and perform actions. + Different agents can differ in what actions they perform in the `receive` method. -#### Financial Projections -- **Revenue Streams:** Mainly from per agent usage fees and hosting services. -- **Cost Structure:** Includes development, maintenance, infrastructure, marketing, and administrative costs. -- **Break-even Analysis:** Estimation based on projected user adoption rates and cost per agent. + Agents are full and completed: -# Revnue Streams -```markdown -| Pricing Structure | Description | Details | -| ------------------------- | ----------- | ------- | -| Usage-Based Per Agent | Fees are charged based on the number of agents deployed and their usage duration. | - Ideal for clients needing a few agents for specific tasks.
- More agents or longer usage results in higher fees. | -| Swarm Coverage Pricing | Pricing based on the coverage area or scope of the swarm deployment. | - Suitable for tasks requiring large area coverage.
- Price scales with the size or complexity of the area covered. | -| Performance-Based Pricing | Fees are tied to the performance or outcomes achieved by the agents. | - Clients pay for the effectiveness or results achieved by the agents.
- Higher fees for more complex or high-value tasks. | -``` + Agents = llm + tools + memory + """ -1. **Pay-Per-Mission Pricing:** Clients are charged for each specific task or mission completed by the agents. + def __init__(self, name: str): + """ + Args: + name (str): name of the agent. + """ + self._name = name -- **Per Agent Usage Fee:** Charged based on the number of agents and the duration of their deployment. -- **Hosting Fees:** Based on the data usage and processing requirements of the agents. -- **Volume Discounts:** Available for large-scale deployments. + @property + def name(self): + """Get the name of the agent.""" + return self._name + def tools(self, tools): + """init tools""" -2. **Time-Based Subscription:** A subscription model where clients pay a recurring fee for continuous access to a set number of agents. + def memory(self, memory_store): + """init memory""" -3. **Dynamic Pricing:** Prices fluctuate based on demand, time of day, or specific conditions. + def reset(self): + """(Abstract method) Reset the agent.""" -4. **Tiered Usage Levels:** Different pricing tiers based on the number of agents used or the complexity of tasks. + def run(self, task: str): + """Run the agent once""" -5. **Freemium Model:** Basic services are free, but premium features or additional agents are paid. + def _arun(self, taks: str): + """Run Async run""" -6. **Outcome-Based Pricing:** Charges are based on the success or quality of the outcomes achieved by the agents. + def chat(self, messages: List[Dict]): + """Chat with the agent""" -7. **Feature-Based Pricing:** Different prices for different feature sets or capabilities of the agents. + def _achat(self, messages: List[Dict]): + """Asynchronous Chat""" -8. **Volume Discounts:** Reduced per-agent price for bulk deployments or long-term contracts. + def step(self, message: str): + """Step through the agent""" -9. **Peak Time Premiums:** Higher charges during peak usage times or for emergency deployment. + def _astep(self, message: str): + """Asynchronous step""" +``` -10. **Bundled Services:** Combining agent services with other products or services for a comprehensive package deal. +## 3. Functionality and Usage -11. **Custom Solution Pricing:** Tailor-made pricing for unique or specialized requirements. +The `AbstractAgent` class represents a generic AI agent and provides a set of methods to interact with it. -12. **Data Analysis Fee:** Charging for the data processing and analytics provided by the agents. +To create an instance of an agent, the `name` of the agent should be specified. -13. **Performance Tiers:** Different pricing for varying levels of agent efficiency or performance. +### Core Methods -14. **License Model:** Clients purchase a license to deploy and use a certain number of agents. +#### 1. `reset` -15. **Cost-Plus Pricing:** Pricing based on the cost of deployment plus a markup. +The `reset` method allows the agent to be reset to its initial state. -16. **Service Level Agreement (SLA) Pricing:** Higher prices for higher levels of service guarantees. +```python +agent.reset() +``` -17. **Pay-Per-Save Model:** Charging based on the cost savings or value created by the agents for the client. +#### 2. `run` -18. **Revenue Sharing:** Sharing a percentage of the revenue generated through the use of agents. +The `run` method allows the agent to perform a specific task. -19. **Geographic Pricing:** Different pricing for different regions or markets. +```python +agent.run("some_task") +``` -20. **User-Based Pricing:** Charging based on the number of users accessing and controlling the agents. +#### 3. `chat` -21. **Energy Usage Pricing:** Prices based on the amount of energy consumed by the agents during operation. +The `chat` method enables communication with the agent through a series of messages. -22. **Event-Driven Pricing:** Charging for specific events or triggers during the agent's operation. +```python +messages = [{"id": 1, "text": "Hello, agent!"}, {"id": 2, "text": "How are you?"}] +agent.chat(messages) +``` -23. **Seasonal Pricing:** Adjusting prices based on seasonal demand or usage patterns. +#### 4. `step` -24. **Partnership Models:** Collaborating with other businesses and sharing revenue from combined services. +The `step` method allows the agent to process a single message. -25. **Customizable Packages:** Allowing clients to build their own package of services and capabilities, priced accordingly. +```python +agent.step("Hello, agent!") +``` -These diverse pricing strategies can be combined or tailored to fit different business models, client needs, and market dynamics. They also provide various methods of value extraction, ensuring flexibility and scalability in revenue generation. +### Asynchronous Methods +The class also provides asynchronous variants of the core methods. -# ICP Analysis -### Ideal Customer Profile (ICP) Map +### Additional Functionality -#### 1. Manufacturing and Industrial Automation - - **Characteristics:** Large-scale manufacturers, high automation needs, emphasis on efficiency and precision. - - **Needs:** Process automation, quality control, predictive maintenance. +Additional functionalities for agent initialization and management of tools and memory are also provided. -#### 2. Agriculture and Farming - - **Characteristics:** Large agricultural enterprises, focus on modern farming techniques. - - **Needs:** Crop monitoring, automated harvesting, pest control. +```python +agent.tools(some_tools) +agent.memory(some_memory_store) +``` -#### 3. Logistics and Supply Chain - - **Characteristics:** Companies with extensive logistics operations, warehousing, and supply chain management. - - **Needs:** Inventory tracking, automated warehousing, delivery optimization. +## 4. Additional Information and Tips -#### 4. Energy and Utilities - - **Characteristics:** Energy providers, utility companies, renewable energy farms. - - **Needs:** Infrastructure monitoring, predictive maintenance, efficiency optimization. +When implementing a new agent using the `AbstractAgent` class, ensure that the `receive` method is overridden to define the specific behavior of the agent upon receiving messages. -#### 5. Environmental Monitoring and Conservation - - **Characteristics:** Organizations focused on environmental protection, research institutions. - - **Needs:** Wildlife tracking, pollution monitoring, ecological research. +## 5. References and Resources -#### 6. Smart Cities and Urban Planning - - **Characteristics:** Municipal governments, urban development agencies. - - **Needs:** Traffic management, infrastructure monitoring, public safety. +For further exploration and understanding of AI agents and agent communication, refer to the relevant literature and research on this topic. -#### 7. Defense and Security - - **Characteristics:** Defense contractors, security firms, government agencies. - - **Needs:** Surveillance, reconnaissance, threat assessment. -#### 8. Healthcare and Medical Facilities - - **Characteristics:** Large hospitals, medical research centers. - - **Needs:** Facility management, patient monitoring, medical logistics. +-------------------------------------------------- -#### 9. Entertainment and Event Management - - **Characteristics:** Large-scale event organizers, theme parks. - - **Needs:** Crowd management, entertainment automation, safety monitoring. +# File: swarms\agents\agent_judge.md -#### 10. Construction and Infrastructure - - **Characteristics:** Major construction firms, infrastructure developers. - - **Needs:** Site monitoring, material tracking, safety compliance. +# AgentJudge -### Potential Market Size Table (in Markdown) +A specialized agent for evaluating and judging outputs from other agents or systems. Acts as a quality control mechanism providing objective assessments and feedback. -```markdown -| Customer Segment | Estimated Market Size (USD) | Notes | -| ---------------------------- | --------------------------- | ----- | -| Manufacturing and Industrial | $100 Billion | High automation and efficiency needs drive demand. | -| Agriculture and Farming | $75 Billion | Growing adoption of smart farming technologies. | -| Logistics and Supply Chain | $90 Billion | Increasing need for automation in warehousing and delivery. | -| Energy and Utilities | $60 Billion | Focus on infrastructure monitoring and maintenance. | -| Environmental Monitoring | $30 Billion | Rising interest in climate and ecological data collection. | -| Smart Cities and Urban Planning | $50 Billion | Growing investment in smart city technologies. | -| Defense and Security | $120 Billion | High demand for surveillance and reconnaissance tech. | -| Healthcare and Medical | $85 Billion | Need for efficient hospital management and patient care. | -| Entertainment and Event Management | $40 Billion | Innovative uses in crowd control and event safety. | -| Construction and Infrastructure | $70 Billion | Use in monitoring and managing large construction projects. | -``` +Based on the research paper: **"Agent-as-a-Judge: Evaluate Agents with Agents"** - [arXiv:2410.10934](https://arxiv.org/abs/2410.10934) -#### Risk Analysis -- **Market Risks:** Adaptation rate and competition. -- **Operational Risks:** Reliability and scalability of infrastructure. -- **Regulatory Risks:** Compliance with data security and privacy laws. +## Overview -# Business Model ---- +The AgentJudge is designed to evaluate and critique outputs from other AI agents, providing structured feedback on quality, accuracy, and areas for improvement. It supports both single-shot evaluations and iterative refinement through multiple evaluation loops with context building. -### The Swarm Cloud: Business Model +Key capabilities: -#### Unlocking the Potential of Autonomous Agent Technology +- **Quality Assessment**: Evaluates correctness, clarity, and completeness of agent outputs -**1. Our Vision:** - - Revolutionize industries through scalable, intelligent swarms of autonomous agents. - - Enable real-time data collection, analysis, and automated task execution. +- **Structured Feedback**: Provides detailed critiques with strengths, weaknesses, and suggestions -**2. Service Offering:** - - **The Swarm Cloud Platform:** Deploy and manage swarms of autonomous agents in production-grade environments. - - **Applications:** Versatile across industries – from smart agriculture to urban planning, logistics, and beyond. +- **Multimodal Support**: Can evaluate text outputs alongside images -**3. Key Features:** - - **High Scalability:** Tailored solutions from small-scale deployments to large industrial operations. - - **Real-Time Analytics:** Instant data processing and actionable insights. - - **User-Friendly Interface:** Simplified control and monitoring of agent swarms. - - **Robust Security:** Ensuring data integrity and operational safety. +- **Context Building**: Maintains evaluation context across multiple iterations -**4. Revenue Streams:** - - **Usage-Based Pricing:** Charges based on the number of agents and operation duration. - - **Subscription Models:** Recurring revenue through scalable packages. - - **Custom Solutions:** Tailored pricing for bespoke deployments. +- **Batch Processing**: Efficiently processes multiple evaluations -**5. Market Opportunity:** - - **Expansive Market:** Addressing needs in a \$500 billion global market spanning multiple sectors. - - **Competitive Edge:** Advanced technology offering superior efficiency and adaptability. +## Architecture -**6. Growth Strategy:** - - **R&D Investment:** Continuous enhancement of agent capabilities and platform features. - - **Strategic Partnerships:** Collaborations with industry leaders for market penetration. - - **Marketing and Sales:** Focused approach on high-potential sectors with tailored marketing strategies. +```mermaid +graph TD + A[Input Task] --> B[AgentJudge] + B --> C{Evaluation Mode} -**7. Why Invest in The Swarm Cloud?** - - **Pioneering Technology:** At the forefront of autonomous agent systems. - - **Scalable Business Model:** Designed for rapid expansion and adaptation to diverse market needs. - - **Strong Market Demand:** Positioned to capitalize on the growing trend of automation and AI. + C -->|step()| D[Single Eval] + C -->|run()| E[Iterative Eval] + C -->|run_batched()| F[Batch Eval] -"Empowering industries with intelligent, autonomous solutions – The Swarm Cloud is set to redefine efficiency and innovation." + D --> G[Agent Core] + E --> G + F --> G -#### Conclusion -The business model aims to provide a scalable, efficient, and cost-effective solution for industries looking to leverage the power of autonomous agent technology. With a structured pricing plan and a focus on continuous development and support, the service is positioned to meet diverse industry needs. + G --> H[LLM Model] + H --> I[Quality Analysis] + I --> J[Feedback & Output] + subgraph "Feedback Details" + N[Strengths] + O[Weaknesses] + P[Improvements] + Q[Accuracy Check] + end + J --> N + J --> O + J --> P + J --> Q --------------------------------------------------- +``` -# File: corporate/swarm_memo.md +## Class Reference -# [Go To Market Strategy][GTM] +### Constructor -Our vision is to become the world leader in real-world production grade autonomous agent deployment through open-source product development, Deep Verticalization, and unmatched value delivery to the end user. +```python +AgentJudge( + id: str = str(uuid.uuid4()), + agent_name: str = "Agent Judge", + description: str = "You're an expert AI agent judge...", + system_prompt: str = AGENT_JUDGE_PROMPT, + model_name: str = "openai/o1", + max_loops: int = 1, + verbose: bool = False, + *args, + **kwargs +) +``` -We will focus on first accelerating the open source framework to PMF where it will serve as the backend for upstream products and services such as the Swarm Cloud which will enable enterprises to deploy autonomous agents with long term memory and tools in the cloud and a no-code platform for users to build their own swarm by dragging and dropping blocks. +#### Parameters -Our target user segment for the framework is AI engineers looking to deploy agents into high risk environments where reliability is crucial. +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `id` | `str` | `str(uuid.uuid4())` | Unique identifier for the judge instance | +| `agent_name` | `str` | `"Agent Judge"` | Name of the agent judge | +| `description` | `str` | `"You're an expert AI agent judge..."` | Description of the agent's role | +| `system_prompt` | `str` | `AGENT_JUDGE_PROMPT` | System instructions for evaluation | +| `model_name` | `str` | `"openai/o1"` | LLM model for evaluation | +| `max_loops` | `int` | `1` | Maximum evaluation iterations | +| `verbose` | `bool` | `False` | Enable verbose logging | -Once PMF has been achieved and the framework has been extensively benchmarked we aim to establish high value contracts with customers in Security, Logistics, Manufacturing, Health and various other untapped industries. +### Methods -Our growth strategy for the OS framework can be summarized by: +#### step() -- Educating developers on value of autonomous agent usage. -- Tutorial Walkthrough on various applications like deploying multi-modal agents through cameras or building custom swarms for a specific business operation. -- Demonstrate unmatched reliability by delighting users. -- Staying up to date with trends and integrating the latest models, frameworks, and methodologies. -- Building a loyal and devoted community for long term user retention. [Join here](https://codex.apac.ai) +```python +step( + task: str = None, + tasks: Optional[List[str]] = None, + img: Optional[str] = None +) -> str +``` -As we continuously deliver value with the open framework we will strategically position ourselves to acquire leads for high value contracts by demonstrating the power, reliability, and performance of our framework openly. +Processes a single task or list of tasks and returns evaluation. -Acquire Full Access to the memo here: [TSC Memo](https://docs.google.com/document/d/1hS_nv_lFjCqLfnJBoF6ULY9roTbSgSuCkvXvSUSc7Lo/edit?usp=sharing) +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `task` | `str` | `None` | Single task/output to evaluate | +| `tasks` | `List[str]` | `None` | List of tasks/outputs to evaluate | +| `img` | `str` | `None` | Path to image for multimodal evaluation | --------------------------------------------------- +**Returns:** `str` - Detailed evaluation response -# File: corporate/swarms_bounty_system.md +#### run() -# **The Swarms Bounty System: Get Paid to Contribute to Open Source** +```python +run( + task: str = None, + tasks: Optional[List[str]] = None, + img: Optional[str] = None +) -> List[str] +``` -In today's fast-paced world of software development, open source has become a driving force for innovation. Every single business and organization on the planet is dependent on open source software. +Executes evaluation in multiple iterations with context building. -The power of collaboration and community has proven to be a potent catalyst for creating robust, cutting-edge solutions. At Swarms, we recognize the immense value that open source contributors bring to the table, and we're thrilled to introduce our Bounty System – a program designed to reward developers for their invaluable contributions to the Swarms ecosystem. +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `task` | `str` | `None` | Single task/output to evaluate | +| `tasks` | `List[str]` | `None` | List of tasks/outputs to evaluate | +| `img` | `str` | `None` | Path to image for multimodal evaluation | -The Swarms Bounty System is a groundbreaking initiative that encourages developers from all walks of life to actively participate in the development and improvement of our suite of products, including the Swarms Python framework, Swarm Cloud, and Swarm Core. By leveraging the collective intelligence and expertise of the global developer community, we aim to foster a culture of continuous innovation and excellence. +**Returns:** `List[str]` - List of evaluation responses from each iteration -[**All bounties with rewards can be found here:**](https://github.com/users/kyegomez/projects/1) +#### run_batched() -## **The Power of Collaboration** +```python +run_batched( + tasks: Optional[List[str]] = None, + imgs: Optional[List[str]] = None +) -> List[List[str]] +``` -At the heart of the Swarms Bounty System lies the belief that collaboration is the key to unlocking the true potential of software development. By opening up our codebase to the vast talent pool of developers around the world, we're not only tapping into a wealth of knowledge and skills, but also fostering a sense of ownership and investment in the Swarms ecosystem. +Executes batch evaluation of multiple tasks with corresponding images. -Whether you're a seasoned developer with years of experience or a passionate newcomer eager to learn and grow, the Swarms Bounty System offers a unique opportunity to contribute to cutting-edge projects and leave your mark on the technological landscape. +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `tasks` | `List[str]` | `None` | List of tasks/outputs to evaluate | +| `imgs` | `List[str]` | `None` | List of image paths (same length as tasks) | -## **How the Bounty System Works** +**Returns:** `List[List[str]]` - Evaluation responses for each task -The Swarms Bounty System is designed to be simple, transparent, and rewarding. Here's how it works: +## Examples -1. **Explore the Bounties**: We maintain a comprehensive list of bounties, ranging from bug fixes and feature enhancements to entirely new projects. These bounties are categorized based on their complexity and potential impact, ensuring that there's something for everyone, regardless of their skill level or area of expertise. [Bounties will be listed here](https://github.com/users/kyegomez/projects/1) +### Basic Usage -2. **Submit Your Contributions**: Once you've identified a bounty that piques your interest, you can start working on it. When you're ready, submit your contribution in the form of a pull request, following our established guidelines and best practices. +```python +from swarms import AgentJudge -3. **Review and Approval**: Our dedicated team of reviewers will carefully evaluate your submission, ensuring that it meets our rigorous quality standards and aligns with the project's vision. They'll provide feedback and guidance, fostering a collaborative environment where you can learn and grow. +# Initialize with default settings +judge = AgentJudge() -4. **Get Rewarded**: Upon successful acceptance of your contribution, you'll be rewarded with a combination of cash and or stock incentives. The rewards are based on a tiered system, reflecting the complexity and impact of your contribution. +# Single task evaluation +result = judge.step(task="The capital of France is Paris.") +print(result) +``` -## **The Rewards System** +### Custom Configuration -At Swarms, we believe in recognizing and rewarding exceptional contributions. Our tiered rewards system is designed to incentivize developers to push the boundaries of innovation and drive the Swarms ecosystem forward. Here's how the rewards are structured: +```python +from swarms import AgentJudge -### Tier 1: Bug Fixes and Minor Enhancements +# Custom judge configuration +judge = AgentJudge( + agent_name="content-evaluator", + model_name="gpt-4", + max_loops=3, + verbose=True +) -| Reward | Description | -|------------------------|--------------------------------------------------------------| -| Cash Reward | $50 - $150 | -| Stock Reward | N/A | +# Evaluate multiple outputs +outputs = [ + "Agent CalculusMaster: The integral of x^2 + 3x + 2 is (1/3)x^3 + (3/2)x^2 + 2x + C", + "Agent DerivativeDynamo: The derivative of sin(x) is cos(x)", + "Agent LimitWizard: The limit of sin(x)/x as x approaches 0 is 1" +] -This tier covers minor bug fixes, documentation improvements, and small enhancements to existing features. While these contributions may seem insignificant, they play a crucial role in maintaining the stability and usability of our products. +evaluation = judge.step(tasks=outputs) +print(evaluation) +``` -### Tier 2: Moderate Enhancements and New Features +### Iterative Evaluation with Context -| Reward | Description | -|------------------------|--------------------------------------------------------------| -| Cash Reward | $151 - $300 | -| Stock Reward | 10+ | +```python +from swarms import AgentJudge -This tier encompasses moderate enhancements to existing features, as well as the implementation of new, non-critical features. Contributions in this tier demonstrate a deeper understanding of the project's architecture and a commitment to improving the overall user experience. +# Multiple iterations with context building +judge = AgentJudge(max_loops=3) -### Tier 3: Major Features and Groundbreaking Innovations +# Each iteration builds on previous context +evaluations = judge.run(task="Agent output: 2+2=5") +for i, eval_result in enumerate(evaluations): + print(f"Iteration {i+1}: {eval_result}\n") +``` -| Reward | Description | -|------------------------|--------------------------------------------------------------| -| Cash Reward | $301 - $++ | -| Stock Reward | 25+ | +### Multimodal Evaluation -This tier is reserved for truly exceptional contributions that have the potential to revolutionize the Swarms ecosystem. Major feature additions, innovative architectural improvements, and groundbreaking new projects fall under this category. Developers who contribute at this level will be recognized as thought leaders and pioneers in their respective fields. +```python +from swarms import AgentJudge -It's important to note that the cash and stock rewards are subject to change based on the project's requirements, complexity, and overall impact. Additionally, we may introduce special bounties with higher reward tiers for particularly challenging or critical projects. +judge = AgentJudge() -## **The Benefits of Contributing** +# Evaluate with image +evaluation = judge.step( + task="Describe what you see in this image", + img="path/to/image.jpg" +) +print(evaluation) +``` -Participating in the Swarms Bounty System offers numerous benefits beyond the financial incentives. By contributing to our open source projects, you'll have the opportunity to: +### Batch Processing -1. **Expand Your Skills**: Working on real-world projects with diverse challenges will help you hone your existing skills and acquire new ones, making you a more versatile and valuable developer. +```python +from swarms import AgentJudge -2. **Build Your Portfolio**: Your contributions will become part of your professional portfolio, showcasing your expertise and dedication to the open source community. +judge = AgentJudge() -3. **Network with Industry Experts**: Collaborate with our team of seasoned developers and gain invaluable insights and mentorship from industry leaders. +# Batch evaluation with images +tasks = [ + "Describe this chart", + "What's the main trend?", + "Any anomalies?" +] +images = [ + "chart1.png", + "chart2.png", + "chart3.png" +] -4. **Shape the Future**: Your contributions will directly impact the direction and evolution of the Swarms ecosystem, shaping the future of our products and services. +# Each task evaluated independently +evaluations = judge.run_batched(tasks=tasks, imgs=images) +for i, task_evals in enumerate(evaluations): + print(f"Task {i+1} evaluations: {task_evals}") +``` -5. **Gain Recognition**: Stand out in the crowded field of software development by having your contributions acknowledged and celebrated by the Swarms community. +## Reference -## **Join the Movement** +```bibtex +@misc{zhuge2024agentasajudgeevaluateagentsagents, + title={Agent-as-a-Judge: Evaluate Agents with Agents}, + author={Mingchen Zhuge and Changsheng Zhao and Dylan Ashley and Wenyi Wang and Dmitrii Khizbullin and Yunyang Xiong and Zechun Liu and Ernie Chang and Raghuraman Krishnamoorthi and Yuandong Tian and Yangyang Shi and Vikas Chandra and Jürgen Schmidhuber}, + year={2024}, + eprint={2410.10934}, + archivePrefix={arXiv}, + primaryClass={cs.AI}, + url={https://arxiv.org/abs/2410.10934} +} +``` -The Swarms Bounty System is more than just a program; it's a movement that embraces the spirit of open source and fosters a culture of collaboration, innovation, and excellence. By joining our ranks, you'll become part of a vibrant community of developers who share a passion for pushing the boundaries of what's possible. +-------------------------------------------------- -Whether you're a seasoned veteran or a newcomer eager to make your mark, the Swarms Bounty System offers a unique opportunity to contribute to cutting-edge projects, earn rewards, and shape the future of software development. +# File: swarms\agents\consistency_agent.md -So, what are you waiting for? Explore our bounties, find your niche, and start contributing today. Together, we can build a brighter, more innovative future for the Swarms ecosystem and the entire software development community. +# Consistency Agent Documentation -[Join the swarm community now:](https://discord.gg/F4GGT5DERD) +The `SelfConsistencyAgent` is a specialized agent designed for generating multiple independent responses to a given task and aggregating them into a single, consistent final answer. It leverages concurrent processing to enhance efficiency and employs a majority voting mechanism to ensure the reliability of the aggregated response. +## Purpose -## Resources -- [Bounty Board](https://github.com/users/kyegomez/projects/1/views/1) -- [Swarm Community](https://discord.gg/F4GGT5DERD) -- [Swarms Framework](https://github.com/kyegomez/swarms) -- [Swarm Cloud](https://github.com/kyegomez/swarms-cloud) -- [Swarm Ecosystem](https://github.com/kyegomez/swarm-ecosystem) +The primary objective of the `SelfConsistencyAgent` is to provide a robust mechanism for decision-making and problem-solving by generating diverse responses and synthesizing them into a coherent final answer. This approach is particularly useful in scenarios where consistency and reliability are critical. --------------------------------------------------- +## Class: `SelfConsistencyAgent` -# File: governance/main.md +### Initialization -# 🔗 Links & Resources +- **`__init__`**: Initializes the `SelfConsistencyAgent` with specified parameters. -Welcome to the Swarms ecosystem. Click any tile below to explore our products, community, documentation, and social platforms. +#### Arguments ---- +| Argument | Type | Default | Description | +|------------------------|---------|---------|-----------------------------------------------------------------------------| +| `name` | `str` | `"Self-Consistency-Agent"` | Name of the agent. | +| `description` | `str` | `"An agent that uses self consistency to generate a final answer."` | Description of the agent's purpose. | +| `system_prompt` | `str` | `CONSISTENCY_SYSTEM_PROMPT` | System prompt for the reasoning agent. | +| `model_name` | `str` | Required | The underlying language model to use. | +| `num_samples` | `int` | `5` | Number of independent responses to generate. | +| `max_loops` | `int` | `1` | Maximum number of reasoning loops per sample. | +| `majority_voting_prompt` | `Optional[str]` | `majority_voting_prompt` | Custom prompt for majority voting aggregation. | +| `eval` | `bool` | `False` | Enable evaluation mode for answer validation. | +| `output_type` | `OutputType` | `"dict"` | Format of the output. | +| `random_models_on` | `bool` | `False` | Enable random model selection for diversity. | - +- **`aggregation_agent`**: Aggregates a list of responses into a single final answer using majority voting. + - **Arguments**: + - `responses` (`List[str]`): The list of responses. + - `prompt` (`str`, optional): Custom prompt for the aggregation agent. + - `model_name` (`str`, optional): Model to use for aggregation. + - **Returns**: `str` - The aggregated answer. -
+- **`check_responses_for_answer`**: Checks if a specified answer is present in any of the provided responses. + - **Arguments**: + - `responses` (`List[str]`): A list of responses to check. + - `answer` (`str`): The answer to look for in the responses. + - **Returns**: `bool` - `True` if the answer is found, `False` otherwise. -🗣️ Swarms Chat +- **`batched_run`**: Run the agent on multiple tasks in batch. + - **Arguments**: + - `tasks` (`List[str]`): List of tasks to be processed. + - **Returns**: `List[Union[str, Dict[str, Any]]]` - List of results for each task. -🛍️ Swarms Marketplace +### Examples -📚 Swarms API Docs +#### Example 1: Basic Usage -🚀 Swarms Startup Program +```python +from swarms.agents.consistency_agent import SelfConsistencyAgent -💻 GitHub: Swarms (Python) +# Initialize the agent +agent = SelfConsistencyAgent( + name="Math-Reasoning-Agent", + model_name="gpt-4o-mini", + max_loops=1, + num_samples=5 +) -🦀 GitHub: Swarms (Rust) +# Define a task +task = "What is the 40th prime number?" -💬 Join Our Discord +# Run the agent +final_answer = agent.run(task) -📱 Telegram Group +# Print the final aggregated answer +print("Final aggregated answer:", final_answer) +``` -🐦 Twitter / X +#### Example 2: Using Custom Majority Voting Prompt -✍️ Swarms Blog on Medium +```python +from swarms.agents.consistency_agent import SelfConsistencyAgent -
+# Initialize the agent with a custom majority voting prompt +agent = SelfConsistencyAgent( + name="Reasoning-Agent", + model_name="gpt-4o-mini", + max_loops=1, + num_samples=5, + majority_voting_prompt="Please provide the most common response." +) ---- +# Define a task +task = "Explain the theory of relativity in simple terms." -## 💡 Quick Summary +# Run the agent +final_answer = agent.run(task) -| Category | Link | -|--------------|----------------------------------------------------------------------| -| API Docs | [docs.swarms.world](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/) | -| GitHub | [kyegomez/swarms](https://github.com/kyegomez/swarms) | -| GitHub (Rust)| [The-Swarm-Corporation/swarms-rs](https://github.com/The-Swarm-Corporation/swarms-rs) | -| Chat UI | [swarms.world/platform/chat](https://swarms.world/platform/chat) | -| Marketplace | [swarms.world](https://swarms.world) | -| Startup App | [Apply Here](https://www.swarms.xyz/programs/startups) | -| Discord | [Join Now](https://discord.gg/jM3Z6M9uMq) | -| Telegram | [Group Chat](https://t.me/swarmsgroupchat) | -| Twitter/X | [@swarms_corp](https://x.com/swarms_corp) | -| Blog | [medium.com/@kyeg](https://medium.com/@kyeg) | +# Print the final aggregated answer +print("Final aggregated answer:", final_answer) +``` ---- +#### Example 3: Evaluation Mode -> 🐝 Swarms is building the agentic internet. Join the movement and build the future with us. +```python +from swarms.agents.consistency_agent import SelfConsistencyAgent +# Initialize the agent with evaluation mode +agent = SelfConsistencyAgent( + name="Validation-Agent", + model_name="gpt-4o-mini", + num_samples=3, + eval=True +) --------------------------------------------------- +# Run with expected answer for validation +result = agent.run("What is 2 + 2?", answer="4", eval=True) +if result is not None: + print("Validation passed:", result) +else: + print("Validation failed - expected answer not found") +``` -# File: guides/agent_evals.md +#### Example 4: Random Models for Diversity -### Understanding Agent Evaluation Mechanisms +```python +from swarms.agents.consistency_agent import SelfConsistencyAgent -Agent evaluation mechanisms play a crucial role in ensuring that autonomous agents, particularly in multi-agent systems, perform their tasks effectively and efficiently. This blog delves into the intricacies of agent evaluation, the importance of accuracy tracking, and the methodologies used to measure and visualize agent performance. We'll use Mermaid graphs to provide clear visual representations of these processes. +# Initialize the agent with random model selection +agent = SelfConsistencyAgent( + name="Diverse-Reasoning-Agent", + model_name="gpt-4o-mini", + num_samples=5, + random_models_on=True +) -#### 1. Introduction to Agent Evaluation Mechanisms +# Run the agent +result = agent.run("What are the benefits of renewable energy?") +print("Diverse reasoning result:", result) +``` -Agent evaluation mechanisms refer to the processes and criteria used to assess the performance of agents within a system. These mechanisms are essential for: +#### Example 5: Batch Processing -- **Ensuring Reliability:** Agents must consistently perform their designated tasks correctly. -- **Improving Performance:** Evaluation helps in identifying areas where agents can improve. -- **Maintaining Accountability:** It provides a way to hold agents accountable for their actions. +```python +from swarms.agents.consistency_agent import SelfConsistencyAgent -### 2. Key Components of Agent Evaluation +# Initialize the agent +agent = SelfConsistencyAgent( + name="Batch-Processing-Agent", + model_name="gpt-4o-mini", + num_samples=3 +) -To effectively evaluate agents, several components and metrics are considered: +# Define multiple tasks +tasks = [ + "What is the capital of France?", + "What is 15 * 23?", + "Explain photosynthesis in simple terms." +] -#### a. Performance Metrics +# Process all tasks +results = agent.batched_run(tasks) -These are quantitative measures used to assess how well an agent is performing. Common performance metrics include: +# Print results +for i, result in enumerate(results): + print(f"Task {i+1} result: {result}") +``` -- **Accuracy:** The percentage of correct actions or decisions made by the agent. -- **Precision and Recall:** Precision measures the number of true positive results divided by the number of all positive results, while recall measures the number of true positive results divided by the number of positives that should have been retrieved. -- **F1 Score:** The harmonic mean of precision and recall. -- **Response Time:** How quickly an agent responds to a given task or query. +## Key Features -#### b. Evaluation Criteria +### Self-Consistency Technique +The agent implements the self-consistency approach based on the research paper "Self-Consistency Improves Chain of Thought Reasoning in Language Models" by Wang et al. (2022). This technique: -Evaluation criteria define the standards or benchmarks against which agent performance is measured. These criteria are often task-specific and may include: +1. **Generates Multiple Independent Responses**: Creates several reasoning paths for the same problem +2. **Analyzes Consistency**: Examines agreement among different reasoning approaches +3. **Aggregates Results**: Uses majority voting or consensus building +4. **Produces Reliable Output**: Delivers a final answer reflecting the most reliable consensus -- **Task Completion Rate:** The percentage of tasks successfully completed by the agent. -- **Error Rate:** The frequency of errors made by the agent during task execution. -- **Resource Utilization:** How efficiently an agent uses resources such as memory and CPU. +### Benefits +- **Mitigates Random Errors**: Multiple reasoning paths reduce individual path errors +- **Reduces Bias**: Diverse approaches minimize single-method biases +- **Improves Reliability**: Consensus-based results are more trustworthy +- **Handles Complexity**: Better performance on complex problem-solving tasks -### 3. The Process of Agent Evaluation +### Use Cases +- **Mathematical Problem Solving**: Where accuracy is critical +- **Decision Making**: When reliability is paramount +- **Validation Tasks**: When answers need verification +- **Complex Reasoning**: Multi-step problem solving +- **Research Questions**: Where multiple perspectives are valuable -The evaluation process involves several steps, which can be visualized using Mermaid graphs: +## Technical Details -#### a. Define Evaluation Metrics +### Concurrent Execution +The agent uses `ThreadPoolExecutor` to generate multiple responses concurrently, improving performance while maintaining independence between reasoning paths. + +### Aggregation Process +The aggregation uses an AI-powered agent that: +- Identifies dominant responses +- Analyzes disparities and disagreements +- Evaluates consensus strength +- Synthesizes minority insights +- Provides comprehensive recommendations + +### Output Formats +The agent supports various output types: +- `"dict"`: Dictionary format with conversation history +- `"str"`: Simple string output +- `"list"`: List format +- `"json"`: JSON formatted output -The first step is to define the metrics that will be used to evaluate the agent. This involves identifying the key performance indicators (KPIs) relevant to the agent's tasks. +## Limitations -```mermaid -graph TD - A[Define Evaluation Metrics] --> B[Identify KPIs] - B --> C[Accuracy] - B --> D[Precision and Recall] - B --> E[F1 Score] - B --> F[Response Time] -``` +1. **Computational Cost**: Higher `num_samples` increases processing time and cost +2. **Model Dependencies**: Performance depends on the underlying model capabilities +3. **Consensus Challenges**: May struggle with tasks where multiple valid approaches exist +4. **Memory Usage**: Concurrent execution requires more memory resources -#### b. Collect Data +## Best Practices -Data collection involves gathering information on the agent's performance. This data can come from logs, user feedback, or direct observations. +1. **Sample Size**: Use 3-7 samples for most tasks; increase for critical decisions +2. **Model Selection**: Choose models with strong reasoning capabilities +3. **Evaluation Mode**: Enable for tasks with known correct answers +4. **Custom Prompts**: Tailor majority voting prompts for specific domains +5. **Batch Processing**: Use `batched_run` for multiple related tasks -```mermaid -graph TD - A[Collect Data] --> B[Logs] - A --> C[User Feedback] - A --> D[Direct Observations] -``` +--- -#### c. Analyze Performance -Once data is collected, it is analyzed to assess the agent's performance against the defined metrics. This step may involve statistical analysis, machine learning models, or other analytical techniques. +-------------------------------------------------- -```mermaid -graph TD - A[Analyze Performance] --> B[Statistical Analysis] - A --> C[Machine Learning Models] - A --> D[Other Analytical Techniques] -``` +# File: swarms\agents\create_agents_yaml.md -#### d. Generate Reports +# Building Agents from a YAML File -After analysis, performance reports are generated. These reports provide insights into how well the agent is performing and identify areas for improvement. +The `create_agents_from_yaml` function is designed to dynamically create agents and orchestrate swarms based on configurations defined in a YAML file. It is particularly suited for enterprise use-cases, offering scalability and reliability for agent-based workflows. -```mermaid -graph TD - A[Generate Reports] --> B[Performance Insights] - B --> C[Identify Areas for Improvement] -``` +### Key Features: +- **Multi-Agent Creation**: Automatically instantiate multiple agents from a YAML file. +- **Swarm Architecture**: Supports swarm architectures where agents collaborate to solve complex tasks. +- **Logging with Loguru**: Includes robust logging for tracking operations and diagnosing issues. +- **Flexible Return Types**: Offers several return types based on the requirements of the system. +- **Customizable**: Supports additional arguments (`*args` and `**kwargs`) for fine-tuning agent behavior. +- **Error Handling**: Handles missing configurations and invalid inputs with meaningful error messages. -### 4. Tracking Agent Accuracy +--- -Accuracy tracking is a critical aspect of agent evaluation. It involves measuring how often an agent's actions or decisions are correct. The following steps outline the process of tracking agent accuracy: +### Parameters -#### a. Define Correctness Criteria +| Parameter | Description | Type | Default Value | Example | +|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------|-------------|---------------|-------------------------------------| +| `model` | A callable representing the model (LLM or other) that agents will use. | Callable | None | `OpenAIChat(model_name="gpt-4")` | +| `yaml_file` | Path to the YAML file containing agent configurations. | String | "agents.yaml" | `"config/agents.yaml"` | +| `return_type`| Determines the type of return object. Options: `"auto"`, `"swarm"`, `"agents"`, `"both"`, `"tasks"`, `"run_swarm"`. | String | "auto" | `"both"` | +| `*args` | Additional positional arguments for further customization (e.g., agent behavior). | List | N/A | N/A | +| `**kwargs` | Additional keyword arguments for customization (e.g., specific parameters passed to the agents or swarm). | Dict | N/A | N/A | -The first step is to define what constitutes a correct action or decision for the agent. +--- -```mermaid -graph TD - A[Define Correctness Criteria] --> B[Task-Specific Standards] - B --> C[Action Accuracy] - B --> D[Decision Accuracy] -``` +### Return Types -#### b. Monitor Agent Actions +| Return Type | Description | +|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------| +| `SwarmRouter` | Returns a `SwarmRouter` object, orchestrating the created agents, only if swarm architecture is defined in YAML. | +| `Agent` | Returns a single agent if only one is defined. | +| `List[Agent]` | Returns a list of agents if multiple are defined. | +| `Tuple` | If both agents and a swarm are present, returns both as a tuple (`SwarmRouter, List[Agent]`). | +| `List[Dict]` | Returns a list of task results if tasks were executed. | +| `None` | Returns nothing if an invalid return type is provided or an error occurs. | -Agents' actions are continuously monitored to track their performance. This monitoring can be done in real-time or through periodic evaluations. +--- -```mermaid -graph TD - A[Monitor Agent Actions] --> B[Real-Time Monitoring] - A --> C[Periodic Evaluations] -``` +### Detailed Return Types -#### c. Compare Against Correctness Criteria +| Return Type | Condition | Example Return Value | +|--------------------|---------------------------------------------------------------------|-----------------------------------------------| +| `"auto"` | Automatically determines the return based on YAML content. | `SwarmRouter` if swarm architecture is defined, otherwise `Agent` or `List[Agent]`. | +| `"swarm"` | Returns `SwarmRouter` if present; otherwise returns agents. | `` | +| `"agents"` | Returns a list of agents (or a single agent if only one is defined).| `[, ]` or `` | +| `"both"` | Returns both `SwarmRouter` and agents in a tuple. | `(, [, ])` | +| `"tasks"` | Returns the task results, if tasks were executed by agents. | `[{'task': 'task_output'}, {'task2': 'output'}]` | +| `"run_swarm"` | Executes the swarm (if defined) and returns the result. | `'Swarm task output here'` | -Each action or decision made by the agent is compared against the defined correctness criteria to determine its accuracy. +--- -```mermaid -graph TD - A[Compare Against Correctness Criteria] --> B[Evaluate Each Action] - B --> C[Correct or Incorrect?] -``` +### Example Use Cases -#### d. Calculate Accuracy Metrics +1. **Creating Multiple Agents for Financial Analysis** -Accuracy metrics are calculated based on the comparison results. These metrics provide a quantitative measure of the agent's accuracy. +```yaml +agents: + - agent_name: "Financial-Analysis-Agent" + system_prompt: "Analyze the best investment strategy for 2024." + max_loops: 1 + autosave: true + verbose: false + context_length: 100000 + output_type: "str" + task: "Analyze stock options for long-term gains." -```mermaid -graph TD - A[Calculate Accuracy Metrics] --> B[Accuracy Percentage] - A --> C[Error Rate] + - agent_name: "Risk-Analysis-Agent" + system_prompt: "Evaluate the risk of tech stocks in 2024." + max_loops: 2 + autosave: false + verbose: true + context_length: 50000 + output_type: "json" + task: "What are the riskiest stocks in the tech sector?" ``` -### 5. Measuring Agent Accuracy - -Measuring agent accuracy involves several steps and considerations: - -#### a. Data Labeling +```python +from swarms.structs.agent import Agent +from swarms.structs.swarm_router import SwarmRouter -To measure accuracy, the data used for evaluation must be accurately labeled. This involves annotating the data with the correct actions or decisions. +# Model representing your LLM +def model(prompt): + return f"Processed: {prompt}" -```mermaid -graph TD - A[Data Labeling] --> B[Annotate Data with Correct Actions] - B --> C[Ensure Accuracy of Labels] +# Create agents and return them as a list +agents = create_agents_from_yaml(model=model, yaml_file="agents.yaml", return_type="agents") +print(agents) ``` -#### b. Establish Baseline Performance +2. **Running a Swarm of Agents to Solve a Complex Task** -A baseline performance level is established by evaluating a sample set of data. This baseline serves as a reference point for measuring improvements or declines in accuracy. +```yaml +agents: + - agent_name: "Legal-Agent" + system_prompt: "Provide legal advice on corporate structuring." + task: "How to incorporate a business as an LLC?" -```mermaid -graph TD - A[Establish Baseline Performance] --> B[Evaluate Sample Data] - B --> C[Set Performance Benchmarks] +swarm_architecture: + name: "Corporate-Swarm" + description: "A swarm for helping businesses with legal and tax advice." + swarm_type: "ConcurrentWorkflow" + task: "How can we optimize a business structure for maximum tax efficiency?" + max_loops: 3 ``` -#### c. Regular Evaluations - -Agents are regularly evaluated to measure their accuracy over time. This helps in tracking performance trends and identifying any deviations from the expected behavior. +```python +import os -```mermaid -graph TD - A[Regular Evaluations] --> B[Track Performance Over Time] - B --> C[Identify Performance Trends] - B --> D[Detect Deviations] -``` +from dotenv import load_dotenv +from loguru import logger +from swarm_models import OpenAIChat -#### d. Feedback and Improvement +from swarms.agents.create_agents_from_yaml import ( + create_agents_from_yaml, +) -Feedback from evaluations is used to improve the agent's performance. This may involve retraining the agent, adjusting its algorithms, or refining its decision-making processes. +# Load environment variables +load_dotenv() -```mermaid -graph TD - A[Feedback and Improvement] --> B[Use Evaluation Feedback] - B --> C[Retrain Agent] - B --> D[Adjust Algorithms] - B --> E[Refine Decision-Making Processes] -``` +# Path to your YAML file +yaml_file = "agents_multi_agent.yaml" -### 6. Visualizing Agent Evaluation with Mermaid Graphs -Mermaid graphs provide a clear and concise way to visualize the agent evaluation process. Here are some examples of how Mermaid graphs can be used: +# Get the OpenAI API key from the environment variable +api_key = os.getenv("GROQ_API_KEY") -#### a. Overall Evaluation Process +# Model +model = OpenAIChat( + openai_api_base="https://api.groq.com/openai/v1", + openai_api_key=api_key, + model_name="llama-3.1-70b-versatile", + temperature=0.1, +) -```mermaid -graph TD - A[Define Evaluation Metrics] --> B[Collect Data] - B --> C[Analyze Performance] - C --> D[Generate Reports] -``` +try: + # Create agents and run tasks (using 'both' to return agents and task results) + task_results = create_agents_from_yaml( + model=model, yaml_file=yaml_file, return_type="run_swarm" + ) -#### b. Accuracy Tracking + logger.info(f"Results from agents: {task_results}") +except Exception as e: + logger.error(f"An error occurred: {e}") -```mermaid -graph TD - A[Define Correctness Criteria] --> B[Monitor Agent Actions] - B --> C[Compare Against Correctness Criteria] - C --> D[Calculate Accuracy Metrics] ``` -#### c. Continuous Improvement Cycle +3. **Returning Both Agents and Tasks** -```mermaid -graph TD - A[Regular Evaluations] --> B[Track Performance Over Time] - B --> C[Identify Performance Trends] - C --> D[Detect Deviations] - D --> E[Feedback and Improvement] - E --> A +```yaml +agents: + - agent_name: "Market-Research-Agent" + system_prompt: "What are the latest trends in AI?" + task: "Provide a market analysis for AI technologies in 2024." ``` -### 7. Case Study: Evaluating a Chatbot Agent +```python +from swarms.structs.agent import Agent -To illustrate the agent evaluation process, let's consider a case study involving a chatbot agent designed to assist customers in an e-commerce platform. +# Model representing your LLM +def model(prompt): + return f"Processed: {prompt}" -#### a. Define Evaluation Metrics +# Create agents and run tasks, return both agents and task results +swarm, agents = create_agents_from_yaml(model=model, yaml_file="agents.yaml", return_type="both") +print(swarm, agents) +``` -For the chatbot, key performance metrics might include: +--- -- **Response Accuracy:** The percentage of correct responses provided by the chatbot. -- **Response Time:** The average time taken by the chatbot to respond to user queries. -- **Customer Satisfaction:** Measured through user feedback and ratings. -#### b. Collect Data -Data is collected from chatbot interactions, including user queries, responses, and feedback. +--- -#### c. Analyze Performance +### YAML Schema Overview: -Performance analysis involves comparing the chatbot's responses against a predefined set of correct responses and calculating accuracy metrics. +Below is a breakdown of the attributes expected in the YAML configuration file, which governs how agents and swarms are created. -#### d. Generate Reports +### YAML Attributes Table: -Reports are generated to provide insights into the chatbot's performance, highlighting areas where it excels and areas needing improvement. +| Attribute Name | Description | Type | Required | Default/Example Value | +|-----------------------------------|------------------------------------------------------------|---------------|----------|------------------------------------------| +| `agents` | List of agents to be created. Each agent must have specific configurations. | List of dicts | Yes | | +| `agent_name` | The name of the agent. | String | Yes | `"Stock-Analysis-Agent"` | +| `system_prompt` | The system prompt that the agent will use. | String | Yes | `"Your full system prompt here"` | +| `max_loops` | Maximum number of iterations or loops for the agent. | Integer | No | 1 | +| `autosave` | Whether the agent should automatically save its state. | Boolean | No | `true` | +| `dashboard` | Whether to enable a dashboard for the agent. | Boolean | No | `false` | +| `verbose` | Whether to run the agent in verbose mode (for debugging). | Boolean | No | `false` | +| `dynamic_temperature_enabled` | Enable dynamic temperature adjustments during agent execution. | Boolean | No | `false` | +| `saved_state_path` | Path where the agent's state is saved for recovery. | String | No | `"path_to_save_state.json"` | +| `user_name` | Name of the user interacting with the agent. | String | No | `"default_user"` | +| `retry_attempts` | Number of times to retry an operation in case of failure. | Integer | No | 1 | +| `context_length` | Maximum context length for agent interactions. | Integer | No | 100000 | +| `return_step_meta` | Whether to return metadata for each step of the task. | Boolean | No | `false` | +| `output_type` | The type of output the agent will return (e.g., `str`, `json`). | String | No | `"str"` | +| `task` | Task to be executed by the agent (optional). | String | No | `"What is the best strategy for long-term stock investment?"` | -### 8. Best Practices for Agent Evaluation +#### Swarm Architecture (Optional): -Here are some best practices to ensure effective agent evaluation: +| Attribute Name | Description | Type | Required | Default/Example Value | +|-----------------------------------|------------------------------------------------------------|---------------|----------|------------------------------------------| +| `swarm_architecture` | Defines the swarm configuration. For more information on what can be added to the swarm architecture, please refer to the [Swarm Router documentation](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/). | Dict | No | | +| `name` | The name of the swarm. | String | Yes | `"MySwarm"` | +| `description` | Description of the swarm and its purpose. | String | No | `"A swarm for collaborative task solving"`| +| `max_loops` | Maximum number of loops for the swarm. | Integer | No | 5 | +| `swarm_type` | The type of swarm (e.g., `ConcurrentWorkflow`) `SequentialWorkflow`. | String | Yes | `"ConcurrentWorkflow"` | +| `task` | The primary task assigned to the swarm. | String | No | `"How can we trademark concepts as a delaware C CORP for free?"` | -#### a. Use Realistic Scenarios +--- +### YAML Schema Example: -Evaluate agents in realistic scenarios that closely mimic real-world conditions. This ensures that the evaluation results are relevant and applicable. +Below is an updated YAML schema that conforms to the function's expectations: -#### b. Continuous Monitoring +```yaml +agents: + - agent_name: "Financial-Analysis-Agent" + system_prompt: "Your full system prompt here" + max_loops: 1 + autosave: true + dashboard: false + verbose: true + dynamic_temperature_enabled: true + saved_state_path: "finance_agent.json" + user_name: "swarms_corp" + retry_attempts: 1 + context_length: 200000 + return_step_meta: false + output_type: "str" + # task: "How can I establish a ROTH IRA to buy stocks and get a tax break?" # Turn off if using swarm -Continuously monitor agent performance to detect and address issues promptly. This helps in maintaining high performance levels. + - agent_name: "Stock-Analysis-Agent" + system_prompt: "Your full system prompt here" + max_loops: 2 + autosave: true + dashboard: false + verbose: true + dynamic_temperature_enabled: false + saved_state_path: "stock_agent.json" + user_name: "stock_user" + retry_attempts: 3 + context_length: 150000 + return_step_meta: true + output_type: "json" + # task: "What is the best strategy for long-term stock investment?" -#### c. Incorporate User Feedback +# Optional Swarm Configuration +swarm_architecture: + name: "MySwarm" + description: "A swarm for collaborative task solving" + max_loops: 5 + swarm_type: "ConcurrentWorkflow" + task: "How can we trademark concepts as a delaware C CORP for free?" # Main task +``` -User feedback is invaluable for improving agent performance. Incorporate feedback into the evaluation process to identify and rectify shortcomings. +# Diagram +```mermaid +graph TD; + A[Task] -->|Send to| B[Financial-Analysis-Agent] + A -->|Send to| C[Stock-Analysis-Agent] +``` -#### d. Regular Updates +--- -Regularly update the evaluation metrics and criteria to keep pace with evolving tasks and requirements. +### How to Use `create_agents_from_yaml` Function with YAML: -### Conclusion +- You need to plug in your specific model until we can create a model router that can fetch any model and set specific settings -Agent evaluation mechanisms are vital for ensuring the reliability, efficiency, and effectiveness of autonomous agents. By defining clear evaluation metrics, continuously monitoring performance, and using feedback for improvement, we can develop agents that consistently perform at high levels. Visualizing the evaluation process with tools like Mermaid graphs further aids in understanding and communication. Through diligent evaluation and continuous improvement, we can harness the full potential of autonomous agents in various applications. +#### Example Code: +```python +import os --------------------------------------------------- +from dotenv import load_dotenv +from loguru import logger +from swarm_models import OpenAIChat -# File: guides/financial_analysis_swarm_mm.md +from swarms.agents.create_agents_from_yaml import ( + create_agents_from_yaml, +) -# Building a Multi-Agent System for Real-Time Financial Analysis: A Comprehensive Tutorial +# Load environment variables +load_dotenv() -In this tutorial, we'll walk through the process of building a sophisticated multi-agent system for real-time financial analysis using the Swarms framework. This system is designed for financial analysts and developer analysts who want to leverage AI and multiple data sources to gain deeper insights into stock performance, market trends, and economic indicators. +# Path to your YAML file +yaml_file = "agents.yaml" -Before we dive into the code, let's briefly introduce the Swarms framework. Swarms is an innovative open-source project that simplifies the creation and management of AI agents. It's particularly well-suited for complex tasks like financial analysis, where multiple specialized agents can work together to provide comprehensive insights. -For more information and to contribute to the project, visit the [Swarms GitHub repository](https://github.com/kyegomez/swarms). We highly recommend exploring the documentation for a deeper understanding of Swarms' capabilities. +# Get the OpenAI API key from the environment variable +api_key = os.getenv("GROQ_API_KEY") -Additional resources: -- [Swarms Discord](https://discord.gg/jM3Z6M9uMq) for community discussions -- [Swarms Twitter](https://x.com/swarms_corp) for updates -- [Swarms Spotify](https://open.spotify.com/show/2HLiswhmUaMdjHC8AUHcCF?si=c831ef10c5ef4994) for podcasts -- [Swarms Blog](https://medium.com/@kyeg) for in-depth articles -- [Swarms Website](https://swarms.xyz) for an overview of the project +# Model +model = OpenAIChat( + openai_api_base="https://api.groq.com/openai/v1", + openai_api_key=api_key, + model_name="llama-3.1-70b-versatile", + temperature=0.1, +) -Now, let's break down our financial analysis system step by step. +try: + # Create agents and run tasks (using 'both' to return agents and task results) + task_results = create_agents_from_yaml( + model=model, yaml_file=yaml_file, return_type="run_swarm" # + ) -## Step 1: Setting Up the Environment -First install the necessary packages: + logger.info(f"Results from agents: {task_results}") +except Exception as e: + logger.error(f"An error occurred: {e}") -```bash -$ pip3 install -U swarms yfiance swarm_models fredapi pandas ``` -First, we need to set up our environment and import the necessary libraries: - -```python -import os -import time -from datetime import datetime, timedelta -import yfinance as yf -import requests -from fredapi import Fred -import pandas as pd -import numpy as np -import matplotlib.pyplot as plt -from swarms import Agent, AgentRearrange -from swarm_models import OpenAIChat -import logging -from dotenv import load_dotenv -import asyncio -import aiohttp -from ratelimit import limits, sleep_and_retry +--- -# Load environment variables -load_dotenv() +### Error Handling: -# Set up logging -logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s') -logger = logging.getLogger(__name__) +1. **FileNotFoundError**: If the specified YAML file does not exist. +2. **ValueError**: Raised if there are invalid or missing configurations in the YAML file. +3. **Invalid Return Type**: If an invalid return type is specified, the function will raise a `ValueError`. -# API keys -POLYGON_API_KEY = os.getenv('POLYGON_API_KEY') -FRED_API_KEY = os.getenv('FRED_API_KEY') -OPENAI_API_KEY = os.getenv('OPENAI_API_KEY') +### Conclusion: +The `create_agents_from_yaml` function provides a flexible and powerful way to dynamically configure and execute agents, supporting a wide range of tasks and configurations for enterprise-level use cases. By following the YAML schema and function signature, users can easily define and manage their agents and swarms. -# Initialize FRED client -fred_client = Fred(api_key=FRED_API_KEY) +-------------------------------------------------- -# Polygon API base URL -POLYGON_BASE_URL = "https://api.polygon.io" -``` +# File: swarms\agents\external_party_agents.md -This section sets up our environment, imports necessary libraries, and initializes our API keys and clients. We're using `dotenv` to securely manage our API keys, and we've set up logging to track the execution of our script. -## Step 2: Implementing Rate Limiting -To respect API rate limits, we implement rate limiting decorators: +# **Swarms External Agent Integration** -```python -@sleep_and_retry -@limits(calls=5, period=60) # Adjust these values based on your Polygon API tier -async def call_polygon_api(session, endpoint, params=None): - url = f"{POLYGON_BASE_URL}{endpoint}" - params = params or {} - params['apiKey'] = POLYGON_API_KEY - async with session.get(url, params=params) as response: - response.raise_for_status() - return await response.json() +Integrating external agents from other frameworks like **Langchain**, **Griptape**, and more is straightforward using **Swarms**. Below are step-by-step guides on how to bring these agents into Swarms by creating a new class, implementing the required methods, and ensuring compatibility. -@sleep_and_retry -@limits(calls=120, period=60) # FRED allows 120 requests per minute -def call_fred_api(func, *args, **kwargs): - return func(*args, **kwargs) -``` +--- -These decorators ensure that we don't exceed the rate limits for our API calls. The `call_polygon_api` function is designed to work with asynchronous code, while `call_fred_api` is a wrapper for synchronous FRED API calls. +## **Quick Overview** -## Step 3: Implementing Data Fetching Functions +- **Step 1**: Create a new class that inherits the `Agent` class from Swarms. +- **Step 2**: Override the `.run(task: str) -> str` method that will execute the agent and return a string response. +- **Step 3**: Optionally, add methods to save outputs to other formats like JSON, logs, or databases. -Next, we implement functions to fetch data from various sources: +### **Agent Class** -### Yahoo Finance Integration +The primary structure you'll need to integrate any external agent is the `Agent` class from **Swarms**. Here’s a template for how your new agent class should be structured: ```python -async def get_yahoo_finance_data(session, ticker, period="1d", interval="1m"): - try: - stock = yf.Ticker(ticker) - hist = await asyncio.to_thread(stock.history, period=period, interval=interval) - info = await asyncio.to_thread(lambda: stock.info) - return hist, info - except Exception as e: - logger.error(f"Error fetching Yahoo Finance data for {ticker}: {e}") - return None, None - -async def get_yahoo_finance_realtime(session, ticker): - try: - stock = yf.Ticker(ticker) - return await asyncio.to_thread(lambda: stock.fast_info) - except Exception as e: - logger.error(f"Error fetching Yahoo Finance realtime data for {ticker}: {e}") - return None -``` - -These functions fetch historical and real-time data from Yahoo Finance. We use `asyncio.to_thread` to run the synchronous `yfinance` functions in a separate thread, allowing our main event loop to continue running. - -### Polygon.io Integration +from swarms import Agent -```python -async def get_polygon_realtime_data(session, ticker): - try: - trades = await call_polygon_api(session, f"/v2/last/trade/{ticker}") - quotes = await call_polygon_api(session, f"/v2/last/nbbo/{ticker}") - return trades, quotes - except Exception as e: - logger.error(f"Error fetching Polygon.io realtime data for {ticker}: {e}") - return None, None +class ExternalAgent(Agent): + def run(self, task: str) -> str: + # Implement logic to run external agent + pass -async def get_polygon_news(session, ticker, limit=10): - try: - news = await call_polygon_api(session, f"/v2/reference/news", params={"ticker": ticker, "limit": limit}) - return news.get('results', []) - except Exception as e: - logger.error(f"Error fetching Polygon.io news for {ticker}: {e}") - return [] + def save_to_json(self, output: str, filepath: str): + # Optionally save the result to a JSON file + with open(filepath, "w") as file: + json.dump({"response": output}, file) ``` -These functions fetch real-time trade and quote data, as well as news articles from Polygon.io. We use our `call_polygon_api` function to make these requests, ensuring we respect rate limits. - -### FRED Integration +--- -```python -async def get_fred_data(session, series_id, start_date, end_date): - try: - data = await asyncio.to_thread(call_fred_api, fred_client.get_series, series_id, start_date, end_date) - return data - except Exception as e: - logger.error(f"Error fetching FRED data for {series_id}: {e}") - return None +## **Griptape Agent Integration Example** -async def get_fred_realtime(session, series_ids): - try: - data = {} - for series_id in series_ids: - series = await asyncio.to_thread(call_fred_api, fred_client.get_series, series_id) - data[series_id] = series.iloc[-1] # Get the most recent value - return data - except Exception as e: - logger.error(f"Error fetching FRED realtime data: {e}") - return {} -``` +In this example, we will create a **Griptape** agent by inheriting from the Swarms `Agent` class and implementing the `run` method. -These functions fetch historical and real-time economic data from FRED. Again, we use `asyncio.to_thread` to run the synchronous FRED API calls in a separate thread. +### **Griptape Integration Steps**: -## Step 4: Creating Specialized Agents +1. **Inherit from Swarms Agent**: Inherit from the `SwarmsAgent` class. +2. **Create Griptape Agent**: Initialize the **Griptape** agent inside your class and provide it with the necessary tools. +3. **Override the `run()` method**: Implement logic to process a task string and execute the Griptape agent. -Now we create our specialized agents using the Swarms framework: +## **Griptape Example Code**: ```python -stock_agent = Agent( - agent_name="StockAgent", - system_prompt="""You are an expert stock analyst. Your task is to analyze real-time stock data and provide insights. - Consider price movements, trading volume, and any available company information. - Provide a concise summary of the stock's current status and any notable trends or events.""", - llm=OpenAIChat(api_key=OPENAI_API_KEY), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, +from swarms import ( + Agent as SwarmsAgent, +) # Import the base Agent class from Swarms +from griptape.structures import Agent as GriptapeAgent +from griptape.tools import ( + WebScraperTool, + FileManagerTool, + PromptSummaryTool, ) -market_agent = Agent( - agent_name="MarketAgent", - system_prompt="""You are a market analysis expert. Your task is to analyze overall market conditions using real-time data. - Consider major indices, sector performance, and market-wide trends. - Provide a concise summary of current market conditions and any significant developments.""", - llm=OpenAIChat(api_key=OPENAI_API_KEY), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, -) +# Create a custom agent class that inherits from SwarmsAgent +class GriptapeSwarmsAgent(SwarmsAgent): + def __init__(self, *args, **kwargs): + # Initialize the Griptape agent with its tools + self.agent = GriptapeAgent( + input="Load {{ args[0] }}, summarize it, and store it in a file called {{ args[1] }}.", + tools=[ + WebScraperTool(off_prompt=True), + PromptSummaryTool(off_prompt=True), + FileManagerTool(), + ], + *args, + **kwargs, + ) -macro_agent = Agent( - agent_name="MacroAgent", - system_prompt="""You are a macroeconomic analysis expert. Your task is to analyze key economic indicators and provide insights on the overall economic situation. - Consider GDP growth, inflation rates, unemployment figures, and other relevant economic data. - Provide a concise summary of the current economic situation and any potential impacts on financial markets.""", - llm=OpenAIChat(api_key=OPENAI_API_KEY), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, -) + # Override the run method to take a task and execute it using the Griptape agent + def run(self, task: str) -> str: + # Extract URL and filename from task + url, filename = task.split(",") # Example task string: "https://example.com, output.txt" + # Execute the Griptape agent + result = self.agent.run(url.strip(), filename.strip()) + # Return the final result as a string + return str(result) -news_agent = Agent( - agent_name="NewsAgent", - system_prompt="""You are a financial news analyst. Your task is to analyze recent news articles related to specific stocks or the overall market. - Consider the potential impact of news events on stock prices or market trends. - Provide a concise summary of key news items and their potential market implications.""", - llm=OpenAIChat(api_key=OPENAI_API_KEY), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, -) -``` -Each agent is specialized in a different aspect of financial analysis. The `system_prompt` for each agent defines its role and the type of analysis it should perform. +# Example usage: +griptape_swarms_agent = GriptapeSwarmsAgent() +output = griptape_swarms_agent.run("https://griptape.ai, griptape.txt") +print(output) +``` -## Step 5: Building the Multi-Agent System +### **Explanation**: +1. **GriptapeSwarmsAgent**: The custom class that integrates **Griptape** into **Swarms**. +2. **run(task: str)**: This method extracts inputs from the task string and runs the agent using **Griptape** tools. +3. **Tools**: The **Griptape** agent is equipped with web scraping, summarization, and file management tools. -We then combine our specialized agents into a multi-agent system: -```python -agents = [stock_agent, market_agent, macro_agent, news_agent] -flow = "StockAgent -> MarketAgent -> MacroAgent -> NewsAgent" +## **Additional Features**: +You can enhance your external agents with additional features such as: -agent_system = AgentRearrange(agents=agents, flow=flow) -``` +- **Saving outputs** to JSON, databases, or logs. -The `flow` variable defines the order in which our agents will process information. This allows for a logical progression from specific stock analysis to broader market and economic analysis. +- **Handling errors** and retry mechanisms for robustness. -## Step 6: Implementing Real-Time Analysis +- **Custom logging** with tools like **Loguru** for extensive debugging. -Now we implement our main analysis function: +--- -```python -async def real_time_analysis(session, ticker): - logger.info(f"Starting real-time analysis for {ticker}") - - # Fetch real-time data - yf_data, yf_info = await get_yahoo_finance_data(session, ticker) - yf_realtime = await get_yahoo_finance_realtime(session, ticker) - polygon_trades, polygon_quotes = await get_polygon_realtime_data(session, ticker) - polygon_news = await get_polygon_news(session, ticker) - fred_data = await get_fred_realtime(session, ['GDP', 'UNRATE', 'CPIAUCSL']) +## **Langchain Agent Integration Example** - # Prepare input for the multi-agent system - input_data = f""" - Yahoo Finance Data: - {yf_realtime} +Next, we demonstrate how to integrate a **Langchain** agent with **Swarms** by following similar steps. - Recent Stock History: - {yf_data.tail().to_string() if yf_data is not None else 'Data unavailable'} +### **Langchain Integration Steps**: - Polygon.io Trade Data: - {polygon_trades} +1. **Inherit from Swarms Agent**: Inherit from the `SwarmsAgent` class. +2. **Create Langchain Agent**: Initialize a Langchain agent with the necessary components (like language models or memory modules). +3. **Override the `run()` method**: Pass tasks to the Langchain agent and return the response. - Polygon.io Quote Data: - {polygon_quotes} +## **Langchain Example Code**: - Recent News: - {polygon_news[:3] if polygon_news else 'No recent news available'} +```python +from swarms import Agent as SwarmsAgent +from langchain import LLMChain +from langchain.llms import OpenAI +from langchain.prompts import PromptTemplate - Economic Indicators: - {fred_data} +# Create a custom agent class that inherits from SwarmsAgent +class LangchainSwarmsAgent(SwarmsAgent): + def __init__(self, *args, **kwargs): + # Initialize the Langchain agent with LLM and prompt + prompt_template = PromptTemplate(template="Answer the question: {question}") + llm = OpenAI(model="gpt-3.5-turbo") + self.chain = LLMChain(llm=llm, prompt=prompt_template) + super().__init__(*args, **kwargs) - Analyze this real-time financial data for {ticker}. Provide insights on the stock's performance, overall market conditions, relevant economic factors, and any significant news that might impact the stock or market. - """ + # Override the run method to take a task and execute it using the Langchain agent + def run(self, task: str) -> str: + # Pass the task to the Langchain agent + result = self.chain.run({"question": task}) + # Return the final result as a string + return result - # Run the multi-agent analysis - try: - analysis = agent_system.run(input_data) - logger.info(f"Analysis completed for {ticker}") - return analysis - except Exception as e: - logger.error(f"Error during multi-agent analysis for {ticker}: {e}") - return f"Error during analysis: {e}" +# Example usage: +langchain_swarms_agent = LangchainSwarmsAgent() +output = langchain_swarms_agent.run("What is the capital of France?") +print(output) ``` -This function fetches data from all our sources, prepares it as input for our multi-agent system, and then runs the analysis. The result is a comprehensive analysis of the stock, considering individual performance, market conditions, economic factors, and relevant news. +### **Explanation**: +1. **LangchainSwarmsAgent**: The custom class integrates **Langchain** into **Swarms**. +2. **run(task: str)**: The task is passed to a language model via Langchain and returns a result. -## Step 7: Implementing Advanced Use Cases -We then implement more advanced analysis functions: +### Additional Examples from other providers -### Compare Stocks -```python -async def compare_stocks(session, tickers): - results = {} - for ticker in tickers: - results[ticker] = await real_time_analysis(session, ticker) - - comparison_prompt = f""" - Compare the following stocks based on the provided analyses: - {results} +### 1. **OpenAI Function Calling Agents** +- **Description**: OpenAI models like GPT-4 can now call functions programmatically. This makes it possible to create agents that execute external functions, APIs, or code snippets. + + ## Example Integration: + ```python + from swarms import Agent as SwarmsAgent + import openai - Highlight key differences and similarities. Provide a ranking of these stocks based on their current performance and future prospects. - """ - - try: - comparison = agent_system.run(comparison_prompt) - logger.info(f"Stock comparison completed for {tickers}") - return comparison - except Exception as e: - logger.error(f"Error during stock comparison: {e}") - return f"Error during comparison: {e}" -``` + # Custom OpenAI Function Calling Agent + class OpenAIFunctionAgent(SwarmsAgent): + def __init__(self, *args, **kwargs): + # Initialize OpenAI API credentials and settings + self.api_key = "your_openai_api_key" + super().__init__(*args, **kwargs) -This function compares multiple stocks by running a real-time analysis on each and then prompting our multi-agent system to compare the results. + def run(self, task: str) -> str: + # Example task: "summarize, 'Provide a short summary of this text...'" + command, input_text = task.split(", ") + response = openai.Completion.create( + model="gpt-4", + prompt=f"{command}: {input_text}", + temperature=0.5, + max_tokens=100, + ) + return response.choices[0].text.strip() -### Sector Analysis + # Example usage: + openai_agent = OpenAIFunctionAgent() + output = openai_agent.run("summarize, Provide a short summary of this text...") + print(output) + ``` -```python -async def sector_analysis(session, sector): - sector_stocks = { - 'Technology': ['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'NVDA'], - 'Finance': ['JPM', 'BAC', 'WFC', 'C', 'GS'], - 'Healthcare': ['JNJ', 'UNH', 'PFE', 'ABT', 'MRK'], - 'Consumer Goods': ['PG', 'KO', 'PEP', 'COST', 'WMT'], - 'Energy': ['XOM', 'CVX', 'COP', 'SLB', 'EOG'] - } - - if sector not in sector_stocks: - return f"Sector '{sector}' not found. Available sectors: {', '.join(sector_stocks.keys())}" - - stocks = sector_stocks[sector][:5] - - sector_data = {} - for stock in stocks: - sector_data[stock] = await real_time_analysis(session, stock) - - sector_prompt = f""" - Analyze the {sector} sector based on the following data from its top stocks: - {sector_data} +### 2. **Rasa Agents** +- **Description**: **Rasa** is a popular open-source framework for building conversational AI agents. You can integrate **Rasa** to build dialogue-based agents with **Swarms**. - Provide insights on: - 1. Overall sector performance - 2. Key trends within the sector - 3. Top performing stocks and why they're outperforming - 4. Any challenges or opportunities facing the sector - """ - - try: - analysis = agent_system.run(sector_prompt) - logger.info(f"Sector analysis completed for {sector}") - return analysis - except Exception as e: - logger.error(f"Error during sector analysis for {sector}: {e}") - return f"Error during sector analysis: {e}" -``` + ## Example Integration: + ```python + from swarms import Agent as SwarmsAgent + from rasa.core.agent import Agent as RasaAgent + from rasa.core.interpreter import RasaNLUInterpreter -This function analyzes an entire sector by running real-time analysis on its top stocks and then prompting our multi-agent system to provide sector-wide insights. + # Custom Rasa Swarms Agent + class RasaSwarmsAgent(SwarmsAgent): + def __init__(self, model_path: str, *args, **kwargs): + # Initialize the Rasa agent with a pre-trained model + self.agent = RasaAgent.load(model_path) + super().__init__(*args, **kwargs) -### Economic Impact Analysis + def run(self, task: str) -> str: + # Pass user input to the Rasa agent + result = self.agent.handle_text(task) + # Return the final response from the agent + return result[0]["text"] if result else "No response." -```python -async def economic_impact_analysis(session, indicator, threshold): - # Fetch historical data for the indicator - end_date = datetime.now().strftime('%Y-%m-%d') - start_date = (datetime.now() - timedelta(days=365)).strftime('%Y-%m-%d') - indicator_data = await get_fred_data(session, indicator, start_date, end_date) - - if indicator_data is None or len(indicator_data) < 2: - return f"Insufficient data for indicator {indicator}" - - # Check if the latest value crosses the threshold - latest_value = indicator_data.iloc[-1] - previous_value = indicator_data.iloc[-2] - crossed_threshold = (latest_value > threshold and previous_value <= threshold) or (latest_value < threshold and previous_value >= threshold) - - if crossed_threshold: - impact_prompt = f""" - The economic indicator {indicator} has crossed the threshold of {threshold}. Its current value is {latest_value}. + # Example usage: + rasa_swarms_agent = RasaSwarmsAgent("path/to/rasa_model") + output = rasa_swarms_agent.run("Hello, how can I get a refund?") + print(output) + ``` - Historical data: - {indicator_data.tail().to_string()} +### 3. **Hugging Face Transformers** +- **Description**: **Hugging Face** offers a variety of pre-trained models, including transformers for NLP tasks. These can be easily integrated into **Swarms** for various tasks like text generation, question answering, and more. - Analyze the potential impacts of this change on: - 1. Overall economic conditions - 2. Different market - 2. Different market sectors - 3. Specific types of stocks (e.g., growth vs. value) - 4. Other economic indicators + ## Example Integration: + ```python + from swarms import Agent as SwarmsAgent + from transformers import pipeline - Provide a comprehensive analysis of the potential consequences and any recommended actions for investors. - """ - - try: - analysis = agent_system.run(impact_prompt) - logger.info(f"Economic impact analysis completed for {indicator}") - return analysis - except Exception as e: - logger.error(f"Error during economic impact analysis for {indicator}: {e}") - return f"Error during economic impact analysis: {e}" - else: - return f"The {indicator} indicator has not crossed the threshold of {threshold}. Current value: {latest_value}" -``` + # Custom Hugging Face Agent + class HuggingFaceSwarmsAgent(SwarmsAgent): + def __init__(self, model_name: str, *args, **kwargs): + # Initialize a pre-trained pipeline from Hugging Face + self.pipeline = pipeline("text-generation", model=model_name) + super().__init__(*args, **kwargs) -This function analyzes the potential impact of significant changes in economic indicators. It fetches historical data, checks if a threshold has been crossed, and if so, prompts our multi-agent system to provide a comprehensive analysis of the potential consequences. + def run(self, task: str) -> str: + # Generate text based on the task input + result = self.pipeline(task, max_length=50) + return result[0]["generated_text"] -## Step 8: Running the Analysis + # Example usage: + hf_swarms_agent = HuggingFaceSwarmsAgent("gpt2") + output = hf_swarms_agent.run("Once upon a time in a land far, far away...") + print(output) + ``` -Finally, we implement our main function to run all of our analyses: +### 4. **AutoGPT or BabyAGI** +- **Description**: **AutoGPT** and **BabyAGI** are agent frameworks designed to be autonomous, where agents can recursively execute tasks and create new tasks based on previous outputs. + + ## Example Integration: + ```python + from swarms import Agent as SwarmsAgent + from autogpt import AutoGPT -```python -async def main(): - async with aiohttp.ClientSession() as session: - # Example usage - analysis_result = await real_time_analysis(session, 'AAPL') - print("Single Stock Analysis:") - print(analysis_result) + # Custom AutoGPT Agent + class AutoGPTSwarmsAgent(SwarmsAgent): + def __init__(self, config, *args, **kwargs): + # Initialize AutoGPT with configuration + self.agent = AutoGPT(config) + super().__init__(*args, **kwargs) - comparison_result = await compare_stocks(session, ['AAPL', 'GOOGL', 'MSFT']) - print("\nStock Comparison:") - print(comparison_result) + def run(self, task: str) -> str: + # Execute task recursively using AutoGPT + result = self.agent.run(task) + return result - tech_sector_analysis = await sector_analysis(session, 'Technology') - print("\nTechnology Sector Analysis:") - print(tech_sector_analysis) + # Example usage: + autogpt_swarms_agent = AutoGPTSwarmsAgent({"goal": "Solve world hunger"}) + output = autogpt_swarms_agent.run("Develop a plan to solve world hunger.") + print(output) + ``` - gdp_impact = await economic_impact_analysis(session, 'GDP', 22000) - print("\nEconomic Impact Analysis:") - print(gdp_impact) +### 5. **DialogFlow Agents** +- **Description**: **DialogFlow** by Google is used to build conversational agents. These agents can process user intents and deliver responses based on predefined conversation flows. + + ## Example Integration: + ```python + from swarms import Agent as SwarmsAgent + from google.cloud import dialogflow -if __name__ == "__main__": - asyncio.run(main()) -``` + # Custom DialogFlow Agent + class DialogFlowSwarmsAgent(SwarmsAgent): + def __init__(self, project_id: str, session_id: str, *args, **kwargs): + # Initialize DialogFlow session client + self.session_client = dialogflow.SessionsClient() + self.project_id = project_id + self.session_id = session_id + super().__init__(*args, **kwargs) -This `main` function demonstrates how to use all of our analysis functions. It runs a single stock analysis, compares multiple stocks, performs a sector analysis, and conducts an economic impact analysis. + def run(self, task: str) -> str: + session = self.session_client.session_path(self.project_id, self.session_id) + text_input = dialogflow.TextInput(text=task, language_code="en-US") + query_input = dialogflow.QueryInput(text=text_input) + response = self.session_client.detect_intent( + request={"session": session, "query_input": query_input} + ) + return response.query_result.fulfillment_text -## Conclusion and Next Steps + # Example usage: + dialogflow_swarms_agent = DialogFlowSwarmsAgent("your_project_id", "your_session_id") + output = dialogflow_swarms_agent.run("Book me a flight to Paris.") + print(output) + ``` -This tutorial has walked you through the process of building a sophisticated multi-agent system for real-time financial analysis using the Swarms framework. Here's a summary of what we've accomplished: +### 6. **ChatterBot Agents** +- **Description**: **ChatterBot** is a Python-based machine-learning conversational agent. It learns from previous conversations to generate intelligent responses. + + ## Example Integration: + ```python + from swarms import Agent as SwarmsAgent + from chatterbot import ChatBot -1. Set up our environment and API connections -2. Implemented rate limiting to respect API constraints -3. Created functions to fetch data from multiple sources (Yahoo Finance, Polygon.io, FRED) -4. Designed specialized AI agents for different aspects of financial analysis -5. Combined these agents into a multi-agent system -6. Implemented advanced analysis functions including stock comparison, sector analysis, and economic impact analysis + # Custom ChatterBot Agent + class ChatterBotSwarmsAgent(SwarmsAgent): + def __init__(self, name: str, *args, **kwargs): + # Initialize ChatterBot + self.agent = ChatBot(name) + super().__init__(*args, **kwargs) -This system provides a powerful foundation for financial analysis, but there's always room for expansion and improvement. Here are some potential next steps: + def run(self, task: str) -> str: + # Get a response from ChatterBot based on user input + response = self.agent.get_response(task) + return str(response) -1. **Expand data sources**: Consider integrating additional financial data providers for even more comprehensive analysis. + # Example usage: + chatterbot_swarms_agent = ChatterBotSwarmsAgent("Assistant") + output = chatterbot_swarms_agent.run("What is the capital of Italy?") + print(output) + ``` -2. **Enhance agent specialization**: You could create more specialized agents, such as a technical analysis agent or a sentiment analysis agent for social media data. +### 7. **Custom APIs as Agents** +- **Description**: You can create agents that integrate with any REST or GraphQL API by defining them as a task runner within Swarms. This allows for interaction with third-party services. + + ## Example Integration: + ```python + from swarms import Agent as SwarmsAgent + import requests -3. **Implement a user interface**: Consider building a web interface or dashboard to make the system more user-friendly for non-technical analysts. + # Custom API Agent + class APIAgent(SwarmsAgent): + def run(self, task: str) -> str: + # Parse task for API endpoint and parameters + endpoint, params = task.split(", ") + response = requests.get(endpoint, params={"q": params}) + return response.text -4. **Add visualization capabilities**: Integrate data visualization tools to help interpret complex financial data more easily. + # Example usage: + api_swarms_agent = APIAgent() + output = api_swarms_agent.run("https://api.example.com/search, python") + print(output) + ``` -5. **Implement a backtesting system**: Develop a system to evaluate your multi-agent system's performance on historical data. +--- -6. **Explore advanced AI models**: The Swarms framework supports various AI models. Experiment with different models to see which performs best for your specific use case. +### **Summary of Integrations**: -7. **Implement real-time monitoring**: Set up a system to continuously monitor markets and alert you to significant changes or opportunities. +- **Griptape**: Integrate with tools for web scraping, summarization, etc. -Remember, the Swarms framework is a powerful and flexible tool that can be adapted to a wide range of complex tasks beyond just financial analysis. We encourage you to explore the [Swarms GitHub repository](https://github.com/kyegomez/swarms) for more examples and inspiration. +- **Langchain**: Use powerful language model orchestration. -For more in-depth discussions and community support, consider joining the [Swarms Discord](https://discord.gg/jM3Z6M9uMq). You can also stay updated with the latest developments by following [Swarms on Twitter](https://x.com/swarms_corp). +- **OpenAI Function Calling**: Directly run OpenAI API-based agents. -If you're interested in learning more about AI and its applications in various fields, check out the [Swarms Spotify podcast](https://open.spotify.com/show/2HLiswhmUaMdjHC8AUHcCF?si=c831ef10c5ef4994) and the [Swarms Blog](https://medium.com/@kyeg) for insightful articles and discussions. +- **Rasa**: Build and integrate conversational agents. -Lastly, don't forget to visit the [Swarms Website](https://swarms.xyz) for a comprehensive overview of the project and its capabilities. +- **Hugging Face**: Leverage transformer models. -By leveraging the power of multi-agent AI systems, you're well-equipped to navigate the complex world of financial markets. Happy analyzing! +- **AutoGPT/BabyAGI**: Recursive, autonomous task execution. +- **DialogFlow**: Integrate conversational flows for voice/chat-based systems. +- **ChatterBot**: Machine-learning conversational agents. -## Swarm Resources: +- **Custom APIs**: Leverage external APIs as agents for custom workflows. -* [Swarms Github](https://github.com/kyegomez/swarms) -* [Swarms Discord](https://discord.gg/jM3Z6M9uMq) -* [Swarms Twitter](https://x.com/swarms_corp) -* [Swarms Spotify](https://open.spotify.com/show/2HLiswhmUaMdjHC8AUHcCF?si=c831ef10c5ef4994) -* [Swarms Blog](https://medium.com/@kyeg) -* [Swarms Website](https://swarms.xyz) +--- --------------------------------------------------- -# File: guides/financial_data_api.md +## **Conclusion**: -# Analyzing Financial Data with AI Agents using Swarms Framework +By following the steps outlined above, you can seamlessly integrate external agent frameworks like **Griptape** and **Langchain** into **Swarms**. This makes Swarms a highly versatile platform for orchestrating various agentic workflows and leveraging the unique capabilities of different frameworks. -In the rapidly evolving landscape of quantitative finance, the integration of artificial intelligence with financial data analysis has become increasingly crucial. This blog post will explore how to leverage the power of AI agents, specifically using the Swarms framework, to analyze financial data from various top-tier data providers. We'll demonstrate how to connect these agents with different financial APIs, enabling sophisticated analysis and decision-making processes. +For more examples and use cases, please refer to the official Swarms documentation site. -## Table of Contents -1. [Introduction to Swarms Framework](#introduction-to-swarms-framework) -2. [Setting Up the Environment](#setting-up-the-environment) -3. [Connecting AI Agents with Financial Data Providers](#connecting-ai-agents-with-financial-data-providers) - - [Polygon.io](#polygonio) - - [Alpha Vantage](#alpha-vantage) - - [Yahoo Finance](#yahoo-finance) - - [IEX Cloud](#iex-cloud) - - [Finnhub](#finnhub) -4. [Advanced Analysis Techniques](#advanced-analysis-techniques) -5. [Best Practices and Considerations](#best-practices-and-considerations) -6. [Conclusion](#conclusion) -## Introduction to Swarms Framework +-------------------------------------------------- -The Swarms framework is a powerful tool for building and deploying AI agents that can interact with various data sources and perform complex analyses. In the context of financial data analysis, Swarms can be used to create intelligent agents that can process large volumes of financial data, identify patterns, and make data-driven decisions. Explore our github for examples, applications, and more. +# File: swarms\agents\gkp_agent.md -## Setting Up the Environment +# Generated Knowledge Prompting (GKP) Agent -Before we dive into connecting AI agents with financial data providers, let's set up our environment: +The GKP Agent is a sophisticated reasoning system that enhances its capabilities by generating relevant knowledge before answering queries. This approach, inspired by Liu et al. 2022, is particularly effective for tasks requiring commonsense reasoning and factual information. -1. Install the Swarms framework: +## Overview -```bash -pip install -U swarms -``` +The GKP Agent consists of three main components: +1. Knowledge Generator - Creates relevant factual information +2. Reasoner - Uses generated knowledge to form answers +3. Coordinator - Synthesizes multiple reasoning paths into a final answer -2. Install additional required libraries: +## Architecture -```bash -pip install requests pandas numpy matplotlib +```mermaid +graph TD + A[Input Query] --> B[Knowledge Generator] + B --> C[Generate Knowledge Items] + C --> D[Reasoner] + D --> E[Multiple Reasoning Paths] + E --> F[Coordinator] + F --> G[Final Answer] + + subgraph "Knowledge Generation" + B + C + end + + subgraph "Reasoning" + D + E + end + + subgraph "Coordination" + F + G + end ``` -3. Set up your API keys for the various financial data providers. It's recommended to use environment variables or a secure configuration file to store these keys. +## Use Cases -## Connecting AI Agents with Financial Data Providers +```mermaid +graph LR + A[GKP Agent] --> B[Commonsense Reasoning] + A --> C[Factual Question Answering] + A --> D[Complex Problem Solving] + A --> E[Multi-step Reasoning] + + B --> B1[Everyday Logic] + B --> B2[Social Situations] + + C --> C1[Historical Facts] + C --> C2[Scientific Information] + + D --> D1[Technical Analysis] + D --> D2[Decision Making] + + E --> E1[Chain of Thought] + E --> E2[Multi-perspective Analysis] +``` -Now, let's explore how to connect AI agents using the Swarms framework with different financial data providers. +## API Reference -### Polygon.io +### GKPAgent -First, we'll create an AI agent that can fetch and analyze stock data from Polygon.io. +The main agent class that orchestrates the knowledge generation and reasoning process. -```python -import os -from swarms import Agent -from swarms.models import OpenAIChat -from dotenv import load_dotenv -import requests -import pandas as pd +#### Initialization Parameters -load_dotenv() +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| agent_name | str | "gkp-agent" | Name identifier for the agent | +| model_name | str | "openai/o1" | LLM model to use for all components | +| num_knowledge_items | int | 6 | Number of knowledge snippets to generate per query | -# Polygon.io API setup -POLYGON_API_KEY = os.getenv("POLYGON_API_KEY") -POLYGON_BASE_URL = "https://api.polygon.io/v2" +#### Methods -# OpenAI API setup -OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") +| Method | Description | Parameters | Returns | +|--------|-------------|------------|---------| +| process(query: str) | Process a single query through the GKP pipeline | query: str | Dict[str, Any] containing full processing results | +| run(queries: List[str], detailed_output: bool = False) | Process multiple queries | queries: List[str], detailed_output: bool | Union[List[str], List[Dict[str, Any]]] | -# Create an instance of the OpenAIChat class -model = OpenAIChat( - openai_api_key=OPENAI_API_KEY, - model_name="gpt-4", - temperature=0.1 -) +### KnowledgeGenerator -# Initialize the agent -agent = Agent( - agent_name="Financial-Analysis-Agent", - system_prompt="You are a financial analysis AI assistant. Your task is to analyze stock data and provide insights.", - llm=model, - max_loops=1, - dashboard=False, - verbose=True -) +Component responsible for generating relevant knowledge for queries. -def get_stock_data(symbol, from_date, to_date): - endpoint = f"{POLYGON_BASE_URL}/aggs/ticker/{symbol}/range/1/day/{from_date}/{to_date}" - params = { - 'apiKey': POLYGON_API_KEY, - 'adjusted': 'true' - } - response = requests.get(endpoint, params=params) - data = response.json() - return pd.DataFrame(data['results']) +#### Initialization Parameters -# Example usage -symbol = "AAPL" -from_date = "2023-01-01" -to_date = "2023-12-31" +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| agent_name | str | "knowledge-generator" | Name identifier for the knowledge generator agent | +| model_name | str | "openai/o1" | Model to use for knowledge generation | +| num_knowledge_items | int | 2 | Number of knowledge items to generate per query | -stock_data = get_stock_data(symbol, from_date, to_date) +#### Methods -analysis_request = f""" -Analyze the following stock data for {symbol} from {from_date} to {to_date}: +| Method | Description | Parameters | Returns | +|--------|-------------|------------|---------| +| generate_knowledge(query: str) | Generate relevant knowledge for a query | query: str | List[str] of generated knowledge statements | -{stock_data.to_string()} +### Reasoner -Provide insights on the stock's performance, including trends, volatility, and any notable events. -""" +Component that uses generated knowledge to reason about and answer queries. -analysis = agent.run(analysis_request) -print(analysis) -``` +#### Initialization Parameters -In this example, we've created an AI agent that can fetch stock data from Polygon.io and perform an analysis based on that data. The agent uses the GPT-4 model to generate insights about the stock's performance. +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| agent_name | str | "knowledge-reasoner" | Name identifier for the reasoner agent | +| model_name | str | "openai/o1" | Model to use for reasoning | -### Alpha Vantage +#### Methods -Next, let's create an agent that can work with Alpha Vantage data to perform fundamental analysis. +| Method | Description | Parameters | Returns | +|--------|-------------|------------|---------| +| reason_and_answer(query: str, knowledge: str) | Reason about a query using provided knowledge | query: str, knowledge: str | Dict[str, str] containing explanation, confidence, and answer | + +## Example Usage ```python -import os -from swarms import Agent -from swarms.models import OpenAIChat -from dotenv import load_dotenv -import requests +from swarms.agents.gkp_agent import GKPAgent -load_dotenv() +# Initialize the GKP Agent +agent = GKPAgent( + agent_name="gkp-agent", + model_name="gpt-4", # Using OpenAI's model + num_knowledge_items=6, # Generate 6 knowledge items per query +) -# Alpha Vantage API setup -ALPHA_VANTAGE_API_KEY = os.getenv("ALPHA_VANTAGE_API_KEY") -ALPHA_VANTAGE_BASE_URL = "https://www.alphavantage.co/query" +# Example queries +queries = [ + "What are the implications of quantum entanglement on information theory?", +] -# OpenAI API setup -OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") +# Run the agent +results = agent.run(queries) -# Create an instance of the OpenAIChat class -model = OpenAIChat( - openai_api_key=OPENAI_API_KEY, - model_name="gpt-4", - temperature=0.1 -) +# Print results +for i, result in enumerate(results): + print(f"\nQuery {i+1}: {queries[i]}") + print(f"Answer: {result}") +``` -# Initialize the agent -agent = Agent( - agent_name="Fundamental-Analysis-Agent", - system_prompt="You are a financial analysis AI assistant specializing in fundamental analysis. Your task is to analyze company financials and provide insights.", - llm=model, - max_loops=1, - dashboard=False, - verbose=True -) +## Best Practices -def get_income_statement(symbol): - params = { - 'function': 'INCOME_STATEMENT', - 'symbol': symbol, - 'apikey': ALPHA_VANTAGE_API_KEY - } - response = requests.get(ALPHA_VANTAGE_BASE_URL, params=params) - return response.json() +1. **Knowledge Generation** + - Set appropriate number of knowledge items based on query complexity + - Monitor knowledge quality and relevance + - Adjust model parameters for optimal performance -# Example usage -symbol = "MSFT" +2. **Reasoning Process** + - Ensure diverse reasoning paths for complex queries + - Validate confidence levels + - Consider multiple perspectives -income_statement = get_income_statement(symbol) +3. **Coordination** + - Review coordination logic for complex scenarios + - Validate final answers against source knowledge + - Monitor processing time and optimize if needed -analysis_request = f""" -Analyze the following income statement data for {symbol}: +## Performance Considerations -{income_statement} +- Processing time increases with number of knowledge items +- Complex queries may require more knowledge items +- Consider caching frequently used knowledge +- Monitor token usage for cost optimization -Provide insights on the company's financial health, profitability trends, and any notable observations. -""" +## Error Handling -analysis = agent.run(analysis_request) -print(analysis) -``` +The agent includes robust error handling for: +- Invalid queries +- Failed knowledge generation +- Reasoning errors +- Coordination failures -This example demonstrates an AI agent that can fetch income statement data from Alpha Vantage and perform a fundamental analysis of a company's financials. -### Yahoo Finance +-------------------------------------------------- -Now, let's create an agent that can work with Yahoo Finance data to perform technical analysis. +# File: swarms\agents\index.md -```python -import os -from swarms import Agent -from swarms.models import OpenAIChat -from dotenv import load_dotenv -import yfinance as yf -import pandas as pd +# Agents Introduction -load_dotenv() +The Agent class is the core component of the Swarms framework, designed to create intelligent, autonomous AI agents capable of handling complex tasks through multi-modal processing, tool integration, and structured outputs. This comprehensive guide covers all aspects of the Agent class, from basic setup to advanced features. -# OpenAI API setup -OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") +## Table of Contents -# Create an instance of the OpenAIChat class -model = OpenAIChat( - openai_api_key=OPENAI_API_KEY, - model_name="gpt-4", - temperature=0.1 -) +1. [Prerequisites & Installation](#prerequisites--installation) +2. [Basic Agent Configuration](#basic-agent-configuration) +3. [Multi-Modal Capabilities](#multi-modal-capabilities) +4. [Tool Integration](#tool-integration) +5. [Structured Outputs](#structured-outputs) +6. [Advanced Features](#advanced-features) +7. [Best Practices](#best-practices) +8. [Complete Examples](#complete-examples) -# Initialize the agent -agent = Agent( - agent_name="Technical-Analysis-Agent", - system_prompt="You are a financial analysis AI assistant specializing in technical analysis. Your task is to analyze stock price data and provide insights on trends and potential trading signals.", - llm=model, - max_loops=1, - dashboard=False, - verbose=True -) +## Prerequisites & Installation -def get_stock_data(symbol, start_date, end_date): - stock = yf.Ticker(symbol) - data = stock.history(start=start_date, end=end_date) - return data +### System Requirements -# Example usage -symbol = "GOOGL" -start_date = "2023-01-01" -end_date = "2023-12-31" +- Python 3.7+ -stock_data = get_stock_data(symbol, start_date, end_date) +- OpenAI API key (for GPT models) -# Calculate some technical indicators -stock_data['SMA_20'] = stock_data['Close'].rolling(window=20).mean() -stock_data['SMA_50'] = stock_data['Close'].rolling(window=50).mean() +- Anthropic API key (for Claude models) -analysis_request = f""" -Analyze the following stock price data and technical indicators for {symbol} from {start_date} to {end_date}: +### Installation -{stock_data.tail(30).to_string()} +```bash +pip3 install -U swarms +``` -Provide insights on the stock's price trends, potential support and resistance levels, and any notable trading signals based on the moving averages. -""" +### Environment Setup -analysis = agent.run(analysis_request) -print(analysis) +Create a `.env` file with your API keys: + +```bash +OPENAI_API_KEY="your-openai-api-key" +ANTHROPIC_API_KEY="your-anthropic-api-key" +WORKSPACE_DIR="agent_workspace" ``` -This example shows an AI agent that can fetch stock price data from Yahoo Finance, calculate some basic technical indicators, and perform a technical analysis. +## Basic Agent Configuration -### IEX Cloud +### Core Agent Structure -Let's create an agent that can work with IEX Cloud data to analyze company news sentiment. +The Agent class provides a comprehensive set of parameters for customization: ```python -import os from swarms import Agent -from swarms.models import OpenAIChat -from dotenv import load_dotenv -import requests - -load_dotenv() -# IEX Cloud API setup -IEX_CLOUD_API_KEY = os.getenv("IEX_CLOUD_API_KEY") -IEX_CLOUD_BASE_URL = "https://cloud.iexapis.com/stable" - -# OpenAI API setup -OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") - -# Create an instance of the OpenAIChat class -model = OpenAIChat( - openai_api_key=OPENAI_API_KEY, - model_name="gpt-4", - temperature=0.1 -) - -# Initialize the agent +# Basic agent initialization agent = Agent( - agent_name="News-Sentiment-Analysis-Agent", - system_prompt="You are a financial analysis AI assistant specializing in news sentiment analysis. Your task is to analyze company news and provide insights on the overall sentiment and potential impact on the stock.", - llm=model, + agent_name="MyAgent", + agent_description="A specialized AI agent for specific tasks", + system_prompt="You are a helpful assistant...", + model_name="gpt-4o-mini", max_loops=1, - dashboard=False, - verbose=True + max_tokens=4096, + temperature=0.7, + output_type="str", + safety_prompt_on=True ) +``` -def get_company_news(symbol, last_n): - endpoint = f"{IEX_CLOUD_BASE_URL}/stock/{symbol}/news/last/{last_n}" - params = {'token': IEX_CLOUD_API_KEY} - response = requests.get(endpoint, params=params) - return response.json() - -# Example usage -symbol = "TSLA" -last_n = 10 +### Key Configuration Parameters -news_data = get_company_news(symbol, last_n) +| Parameter | Type | Description | Default | +|-----------|------|-------------|---------| +| `agent_name` | str | Unique identifier for the agent | Required | +| `agent_description` | str | Detailed description of capabilities | Required | +| `system_prompt` | str | Core instructions defining behavior | Required | +| `model_name` | str | AI model to use | "gpt-4o-mini" | +| `max_loops` | int | Maximum execution loops | 1 | +| `max_tokens` | int | Maximum response tokens | 4096 | +| `temperature` | float | Response creativity (0-1) | 0.7 | +| `output_type` | str | Response format type | "str" | +| `multi_modal` | bool | Enable image processing | False | +| `safety_prompt_on` | bool | Enable safety checks | True | -analysis_request = f""" -Analyze the following recent news articles for {symbol}: +### Simple Example -{news_data} +```python +from swarms import Agent -Provide insights on the overall sentiment of the news, potential impact on the stock price, and any notable trends or events mentioned. -""" +# Create a basic financial advisor agent +financial_agent = Agent( + agent_name="Financial-Advisor", + agent_description="Personal finance and investment advisor", + system_prompt="""You are an expert financial advisor with deep knowledge of: + - Investment strategies and portfolio management + - Risk assessment and mitigation + - Market analysis and trends + - Financial planning and budgeting + + Provide clear, actionable advice while considering risk tolerance.""", + model_name="gpt-4o-mini", + max_loops=1, + temperature=0.3, + output_type="str" +) -analysis = agent.run(analysis_request) -print(analysis) +# Run the agent +response = financial_agent.run("What are the best investment strategies for a 30-year-old?") +print(response) ``` -This example demonstrates an AI agent that can fetch recent news data from IEX Cloud and perform a sentiment analysis on the company news. +## Multi-Modal Capabilities -### Finnhub +### Image Processing -Finally, let's create an agent that can work with Finnhub data to analyze earnings estimates and recommendations. +The Agent class supports comprehensive image analysis through vision-enabled models: ```python -import os from swarms import Agent -from swarms.models import OpenAIChat -from dotenv import load_dotenv -import finnhub -load_dotenv() - -# Finnhub API setup -FINNHUB_API_KEY = os.getenv("FINNHUB_API_KEY") -finnhub_client = finnhub.Client(api_key=FINNHUB_API_KEY) +# Create a vision-enabled agent +vision_agent = Agent( + agent_name="Vision-Analyst", + agent_description="Advanced image analysis and quality control agent", + system_prompt="""You are an expert image analyst capable of: + - Detailed visual inspection and quality assessment + - Object detection and classification + - Scene understanding and context analysis + - Defect identification and reporting + + Provide comprehensive analysis with specific observations.""", + model_name="gpt-4o-mini", # Vision-enabled model + multi_modal=True, # Enable multi-modal processing + max_loops=1, + output_type="str" +) -# OpenAI API setup -OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") +# Analyze a single image +response = vision_agent.run( + task="Analyze this image for quality control purposes", + img="path/to/image.jpg" +) -# Create an instance of the OpenAIChat class -model = OpenAIChat( - openai_api_key=OPENAI_API_KEY, - model_name="gpt-4", - temperature=0.1 +# Process multiple images +response = vision_agent.run( + task="Compare these images and identify differences", + imgs=["image1.jpg", "image2.jpg", "image3.jpg"], + summarize_multiple_images=True ) +``` -# Initialize the agent -agent = Agent( - agent_name="Earnings-Analysis-Agent", - system_prompt="You are a financial analysis AI assistant specializing in earnings analysis. Your task is to analyze earnings estimates and recommendations to provide insights on a company's financial outlook.", - llm=model, +### Supported Image Formats + +| Format | Description | Max Size | +|--------|-------------|----------| +| JPEG/JPG | Standard compressed format | 20MB | +| PNG | Lossless with transparency | 20MB | +| GIF | Animated (first frame only) | 20MB | +| WebP | Modern efficient format | 20MB | + +### Quality Control Example + +```python +from swarms import Agent +from swarms.prompts.logistics import Quality_Control_Agent_Prompt + +def security_analysis(danger_level: str) -> str: + """Analyze security danger level and return appropriate response.""" + danger_responses = { + "low": "No immediate danger detected", + "medium": "Moderate security concern identified", + "high": "Critical security threat detected", + None: "No danger level assessment available" + } + return danger_responses.get(danger_level, "Unknown danger level") + +# Quality control agent with tool integration +quality_agent = Agent( + agent_name="Quality-Control-Agent", + agent_description="Advanced quality control and security analysis agent", + system_prompt=f""" + {Quality_Control_Agent_Prompt} + + You have access to security analysis tools. When analyzing images: + 1. Identify potential safety hazards + 2. Assess quality standards compliance + 3. Determine appropriate danger levels (low, medium, high) + 4. Use the security_analysis function for threat assessment + """, + model_name="gpt-4o-mini", + multi_modal=True, max_loops=1, - dashboard=False, - verbose=True + tools=[security_analysis] ) -def get_earnings_estimates(symbol): - return finnhub_client.earnings_calendar(symbol=symbol, from_date="2023-01-01", to_date="2023-12-31") +# Analyze factory image +response = quality_agent.run( + task="Analyze this factory image for safety and quality issues", + img="factory_floor.jpg" +) +``` -def get_recommendations(symbol): - return finnhub_client.recommendation_trends(symbol) +## Tool Integration -# Example usage -symbol = "NVDA" +### Creating Custom Tools -earnings_estimates = get_earnings_estimates(symbol) -recommendations = get_recommendations(symbol) +Tools are Python functions that extend your agent's capabilities: -analysis_request = f""" -Analyze the following earnings estimates and recommendations for {symbol}: +```python +import json +import requests +from typing import Optional, Dict, Any -Earnings Estimates: -{earnings_estimates} +def get_weather_data(city: str, country: Optional[str] = None) -> str: + """ + Get current weather data for a specified city. + + Args: + city (str): The city name + country (Optional[str]): Country code (e.g., 'US', 'UK') + + Returns: + str: JSON formatted weather data + + Example: + >>> weather = get_weather_data("San Francisco", "US") + >>> print(weather) + {"temperature": 18, "condition": "partly cloudy", ...} + """ + try: + # API call logic here + weather_data = { + "city": city, + "country": country, + "temperature": 18, + "condition": "partly cloudy", + "humidity": 65, + "wind_speed": 12 + } + return json.dumps(weather_data, indent=2) + + except Exception as e: + return json.dumps({"error": f"Weather API error: {str(e)}"}) -Recommendations: -{recommendations} +def calculate_portfolio_metrics(prices: list, weights: list) -> str: + """ + Calculate portfolio performance metrics. + + Args: + prices (list): List of asset prices + weights (list): List of portfolio weights + + Returns: + str: JSON formatted portfolio metrics + """ + try: + # Portfolio calculation logic + portfolio_value = sum(p * w for p, w in zip(prices, weights)) + metrics = { + "total_value": portfolio_value, + "weighted_average": portfolio_value / sum(weights), + "asset_count": len(prices) + } + return json.dumps(metrics, indent=2) + + except Exception as e: + return json.dumps({"error": f"Calculation error: {str(e)}"}) +``` -Provide insights on the company's expected financial performance, analyst sentiment, and any notable trends in the recommendations. -""" +### Tool Integration Example -analysis = agent.run(analysis_request) -print(analysis) -``` +```python +from swarms import Agent -This example shows an AI agent that can fetch earnings estimates and analyst recommendations from Finnhub and perform an analysis on the company's financial outlook. +# Create agent with custom tools +multi_tool_agent = Agent( + agent_name="Multi-Tool-Assistant", + agent_description="Versatile assistant with weather and financial tools", + system_prompt="""You are a versatile assistant with access to: + - Weather data retrieval for any city + - Portfolio analysis and financial calculations + + Use these tools to provide comprehensive assistance.""", + model_name="gpt-4o-mini", + max_loops=1, + tools=[get_weather_data, calculate_portfolio_metrics] +) -## Advanced Analysis Techniques +# Use the agent with tools +response = multi_tool_agent.run( + "What's the weather in New York and calculate metrics for a portfolio with prices [100, 150, 200] and weights [0.3, 0.4, 0.3]?" +) +``` -To further enhance the capabilities of our AI agents, we can implement more advanced analysis techniques: +### API Integration Tools -1. Multi-source analysis: Combine data from multiple providers to get a more comprehensive view of a stock or market. +```python +import requests +import json +from typing import List -2. Time series forecasting: Implement machine learning models for price prediction. +def get_cryptocurrency_price(coin_id: str, vs_currency: str = "usd") -> str: + """Get current cryptocurrency price from CoinGecko API.""" + try: + url = "https://api.coingecko.com/api/v3/simple/price" + params = { + "ids": coin_id, + "vs_currencies": vs_currency, + "include_market_cap": True, + "include_24hr_vol": True, + "include_24hr_change": True + } + + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() + return json.dumps(response.json(), indent=2) + + except Exception as e: + return json.dumps({"error": f"API error: {str(e)}"}) -3. Sentiment analysis of social media: Incorporate data from social media platforms to gauge market sentiment. +def get_top_cryptocurrencies(limit: int = 10) -> str: + """Get top cryptocurrencies by market cap.""" + try: + url = "https://api.coingecko.com/api/v3/coins/markets" + params = { + "vs_currency": "usd", + "order": "market_cap_desc", + "per_page": limit, + "page": 1 + } + + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() + return json.dumps(response.json(), indent=2) + + except Exception as e: + return json.dumps({"error": f"API error: {str(e)}"}) + +# Crypto analysis agent +crypto_agent = Agent( + agent_name="Crypto-Analysis-Agent", + agent_description="Cryptocurrency market analysis and price tracking agent", + system_prompt="""You are a cryptocurrency analysis expert with access to: + - Real-time price data for any cryptocurrency + - Market capitalization rankings + - Trading volume and price change data + + Provide insightful market analysis and investment guidance.""", + model_name="gpt-4o-mini", + max_loops=1, + tools=[get_cryptocurrency_price, get_top_cryptocurrencies] +) -4. Portfolio optimization: Use AI agents to suggest optimal portfolio allocations based on risk tolerance and investment goals. +# Analyze crypto market +response = crypto_agent.run("Analyze the current Bitcoin price and show me the top 5 cryptocurrencies") +``` -5. Anomaly detection: Implement algorithms to detect unusual patterns or events in financial data. +## Structured Outputs -Here's an example of how we might implement a multi-source analysis: +### Function Schema Definition + +Define structured outputs using OpenAI's function calling format: ```python -import os from swarms import Agent -from swarms.models import OpenAIChat -from dotenv import load_dotenv -import yfinance as yf -import requests -import pandas as pd -load_dotenv() +# Define function schemas for structured outputs +stock_analysis_schema = { + "type": "function", + "function": { + "name": "analyze_stock_performance", + "description": "Analyze stock performance with detailed metrics", + "parameters": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "Stock ticker symbol (e.g., AAPL, GOOGL)" + }, + "analysis_type": { + "type": "string", + "enum": ["technical", "fundamental", "comprehensive"], + "description": "Type of analysis to perform" + }, + "time_period": { + "type": "string", + "enum": ["1d", "1w", "1m", "3m", "1y"], + "description": "Time period for analysis" + }, + "metrics": { + "type": "array", + "items": { + "type": "string", + "enum": ["price", "volume", "pe_ratio", "market_cap", "volatility"] + }, + "description": "Metrics to include in analysis" + } + }, + "required": ["ticker", "analysis_type"] + } + } +} -# API setup -POLYGON_API_KEY = os.getenv("POLYGON_API_KEY") -ALPHA_VANTAGE_API_KEY = os.getenv("ALPHA_VANTAGE_API_KEY") -OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") +portfolio_optimization_schema = { + "type": "function", + "function": { + "name": "optimize_portfolio", + "description": "Optimize portfolio allocation based on risk and return", + "parameters": { + "type": "object", + "properties": { + "assets": { + "type": "array", + "items": { + "type": "object", + "properties": { + "symbol": {"type": "string"}, + "current_weight": {"type": "number"}, + "expected_return": {"type": "number"}, + "risk_level": {"type": "string", "enum": ["low", "medium", "high"]} + }, + "required": ["symbol", "current_weight"] + } + }, + "risk_tolerance": { + "type": "string", + "enum": ["conservative", "moderate", "aggressive"] + }, + "investment_horizon": { + "type": "integer", + "minimum": 1, + "maximum": 30, + "description": "Investment time horizon in years" + } + }, + "required": ["assets", "risk_tolerance"] + } + } +} -# Create an instance of the OpenAIChat class -model = OpenAIChat( - openai_api_key=OPENAI_API_KEY, - model_name="gpt-4", - temperature=0.1 +# Create agent with structured outputs +structured_agent = Agent( + agent_name="Structured-Financial-Agent", + agent_description="Financial analysis agent with structured output capabilities", + system_prompt="""You are a financial analysis expert that provides structured outputs. + Use the provided function schemas to format your responses consistently.""", + model_name="gpt-4o-mini", + max_loops=1, + tools_list_dictionary=[stock_analysis_schema, portfolio_optimization_schema] ) -# Initialize the agent -agent = Agent( - agent_name="Multi-Source-Analysis-Agent", - system_prompt="You are a financial analysis AI assistant capable of analyzing data from multiple sources. Your task is to provide comprehensive insights on a stock based on various data points.", - llm=model, - max_loops=1, - dashboard=False, - verbose=True +# Generate structured analysis +response = structured_agent.run( + "Analyze Apple stock (AAPL) performance with comprehensive analysis for the last 3 months" ) +``` -def get_stock_data_yf(symbol, start_date, end_date): - stock = yf.Ticker(symbol) - return stock.history(start=start_date, end=end_date) +## Advanced Features -def get_stock_data_polygon(symbol, from_date, to_date): - endpoint = f"https://api.polygon.io/v2/aggs/ticker/{symbol}/range/1/day/{from_date}/{to_date}" - params = {'apiKey': POLYGON_API_KEY, 'adjusted': 'true'} - response = requests.get(endpoint, params=params) - data = response.json() - return pd.DataFrame(data['results']) +### Dynamic Temperature Control -def get_company_overview_av(symbol): - params = { - 'function': 'OVERVIEW', - 'symbol': symbol, - 'apikey': ALPHA_VANTAGE_API_KEY - } - response = requests.get("https://www.alphavantage.co/query", params=params) - return response.json() +```python +from swarms import Agent -# Example usage -symbol = "AAPL" -start_date = "2023-01-01" -end_date = "2023-12-31" +# Agent with dynamic temperature adjustment +adaptive_agent = Agent( + agent_name="Adaptive-Response-Agent", + agent_description="Agent that adjusts response creativity based on context", + system_prompt="You are an adaptive AI that adjusts your response style based on the task complexity.", + model_name="gpt-4o-mini", + dynamic_temperature_enabled=True, # Enable adaptive temperature + max_loops=1, + output_type="str" +) +``` -yf_data = get_stock_data_yf(symbol, start_date, end_date) -polygon_data = get_stock_data_polygon(symbol, start_date, end_date) -av_overview = get_company_overview_av(symbol) +### Output Type Configurations -analysis_request = f""" -Analyze the following data for {symbol} from {start_date} to {end_date}: +```python +# Different output type examples +json_agent = Agent( + agent_name="JSON-Agent", + system_prompt="Always respond in valid JSON format", + output_type="json" +) -Yahoo Finance Data: -{yf_data.tail().to_string()} +streaming_agent = Agent( + agent_name="Streaming-Agent", + system_prompt="Provide detailed streaming responses", + output_type="str-all-except-first" +) -Polygon.io Data: -{polygon_data.tail().to_string()} +final_only_agent = Agent( + agent_name="Final-Only-Agent", + system_prompt="Provide only the final result", + output_type="final" +) +``` -Alpha Vantage Company Overview: -{av_overview} +### Safety and Content Filtering -Provide a comprehensive analysis of the stock, including: -1. Price trends and volatility -2. Trading volume analysis -3. Fundamental analysis based on the company overview -4. Any discrepancies between data sources and potential reasons -5. Overall outlook and potential risks/opportunities -""" +```python +from swarms import Agent -analysis = agent.run(analysis_request) -print(analysis) +# Agent with enhanced safety features +safe_agent = Agent( + agent_name="Safe-Agent", + agent_description="Agent with comprehensive safety measures", + system_prompt="You are a helpful, harmless, and honest AI assistant.", + model_name="gpt-4o-mini", + safety_prompt_on=True, # Enable safety prompts + max_loops=1, + temperature=0.3 # Lower temperature for more consistent, safe responses +) ``` -This multi-source analysis example combines data from Yahoo Finance, Polygon.io, and Alpha Vantage to provide a more comprehensive view of a stock. The AI agent can then analyze this diverse set of data to provide deeper insights. +## Best Practices -Now, let's explore some additional advanced analysis techniques: +### Error Handling and Robustness -### Time Series Forecasting +```python +import logging +from swarms import Agent -We can implement a simple time series forecasting model using the Prophet library and integrate it with our AI agent: +# Configure logging +logging.basicConfig(level=logging.INFO) +logger = logging.getLogger(__name__) + +def robust_agent_execution(agent, task, max_retries=3): + """Execute agent with retry logic and error handling.""" + for attempt in range(max_retries): + try: + response = agent.run(task) + logger.info(f"Agent execution successful on attempt {attempt + 1}") + return response + except Exception as e: + logger.error(f"Attempt {attempt + 1} failed: {str(e)}") + if attempt == max_retries - 1: + raise + time.sleep(2 ** attempt) # Exponential backoff + + return None + +# Example usage +try: + result = robust_agent_execution(agent, "Analyze market trends") + print(result) +except Exception as e: + print(f"Agent execution failed: {e}") +``` + +### Performance Optimization ```python -import os from swarms import Agent -from swarms.models import OpenAIChat -from dotenv import load_dotenv -import yfinance as yf -import pandas as pd -from prophet import Prophet -import matplotlib.pyplot as plt - -load_dotenv() +import time -OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") +# Optimized agent configuration +optimized_agent = Agent( + agent_name="Optimized-Agent", + agent_description="Performance-optimized agent configuration", + system_prompt="You are an efficient AI assistant optimized for performance.", + model_name="gpt-4o-mini", # Faster model + max_loops=1, # Minimize loops + max_tokens=2048, # Reasonable token limit + temperature=0.5, # Balanced creativity + output_type="str" +) + +# Batch processing example +def process_tasks_batch(agent, tasks, batch_size=5): + """Process multiple tasks efficiently.""" + results = [] + for i in range(0, len(tasks), batch_size): + batch = tasks[i:i + batch_size] + batch_results = [] + + for task in batch: + start_time = time.time() + result = agent.run(task) + execution_time = time.time() - start_time + + batch_results.append({ + "task": task, + "result": result, + "execution_time": execution_time + }) + + results.extend(batch_results) + time.sleep(1) # Rate limiting + + return results +``` -model = OpenAIChat( - openai_api_key=OPENAI_API_KEY, - model_name="gpt-4", - temperature=0.1 -) +## Complete Examples -agent = Agent( - agent_name="Time-Series-Forecast-Agent", - system_prompt="You are a financial analysis AI assistant specializing in time series forecasting. Your task is to analyze stock price predictions and provide insights.", - llm=model, - max_loops=1, - dashboard=False, - verbose=True -) +### Multi-Modal Quality Control System -def get_stock_data(symbol, start_date, end_date): - stock = yf.Ticker(symbol) - data = stock.history(start=start_date, end=end_date) - return data +```python +from swarms import Agent +from swarms.prompts.logistics import Quality_Control_Agent_Prompt + +def security_analysis(danger_level: str) -> str: + """Analyze security danger level and return appropriate response.""" + responses = { + "low": "✅ No immediate danger detected - Safe to proceed", + "medium": "⚠️ Moderate security concern - Requires attention", + "high": "🚨 Critical security threat - Immediate action required", + None: "❓ No danger level assessment available" + } + return responses.get(danger_level, "Unknown danger level") + +def quality_assessment(quality_score: int) -> str: + """Assess quality based on numerical score (1-10).""" + if quality_score >= 8: + return "✅ Excellent quality - Meets all standards" + elif quality_score >= 6: + return "⚠️ Good quality - Minor improvements needed" + elif quality_score >= 4: + return "❌ Poor quality - Significant issues identified" + else: + return "🚨 Critical quality failure - Immediate attention required" -def forecast_stock_price(data, periods=30): - df = data.reset_index()[['Date', 'Close']] - df.columns = ['ds', 'y'] +# Advanced quality control agent +quality_control_system = Agent( + agent_name="Advanced-Quality-Control-System", + agent_description="Comprehensive quality control and security analysis system", + system_prompt=f""" + {Quality_Control_Agent_Prompt} - model = Prophet() - model.fit(df) + You are an advanced quality control system with the following capabilities: - future = model.make_future_dataframe(periods=periods) - forecast = model.predict(future) + 1. Visual Inspection: Analyze images for defects, compliance, and safety + 2. Security Assessment: Identify potential security threats and hazards + 3. Quality Scoring: Provide numerical quality ratings (1-10 scale) + 4. Detailed Reporting: Generate comprehensive analysis reports - fig = model.plot(forecast) - plt.savefig('forecast_plot.png') - plt.close() + When analyzing images: + - Identify specific defects or issues + - Assess compliance with safety standards + - Determine appropriate danger levels (low, medium, high) + - Provide quality scores and recommendations + - Use available tools for detailed analysis - return forecast + Always provide specific, actionable feedback. + """, + model_name="gpt-4o-mini", + multi_modal=True, + max_loops=1, + tools=[security_analysis, quality_assessment], + output_type="str" +) -# Example usage -symbol = "MSFT" -start_date = "2020-01-01" -end_date = "2023-12-31" +# Process factory images +factory_images = ["factory_floor.jpg", "assembly_line.jpg", "safety_equipment.jpg"] -stock_data = get_stock_data(symbol, start_date, end_date) -forecast = forecast_stock_price(stock_data) +for image in factory_images: + print(f"\n--- Analyzing {image} ---") + response = quality_control_system.run( + task=f"Perform comprehensive quality control analysis of this image. Assess safety, quality, and provide specific recommendations.", + img=image + ) + print(response) +``` -analysis_request = f""" -Analyze the following time series forecast for {symbol}: +### Advanced Financial Analysis Agent -Forecast Data: -{forecast.tail(30).to_string()} +```python +from swarms import Agent +import json +import requests -The forecast plot has been saved as 'forecast_plot.png'. +def get_market_data(symbol: str, period: str = "1y") -> str: + """Get comprehensive market data for a symbol.""" + # Simulated market data (replace with real API) + market_data = { + "symbol": symbol, + "current_price": 150.25, + "change_percent": 2.5, + "volume": 1000000, + "market_cap": 2500000000, + "pe_ratio": 25.5, + "dividend_yield": 1.8, + "52_week_high": 180.50, + "52_week_low": 120.30 + } + return json.dumps(market_data, indent=2) -Provide insights on: -1. The predicted trend for the stock price -2. Any seasonal patterns observed -3. Potential factors that might influence the forecast -4. Limitations of this forecasting method -5. Recommendations for investors based on this forecast -""" +def calculate_risk_metrics(prices: list, benchmark_prices: list) -> str: + """Calculate risk metrics for a portfolio.""" + import numpy as np + + try: + returns = np.diff(prices) / prices[:-1] + benchmark_returns = np.diff(benchmark_prices) / benchmark_prices[:-1] + + volatility = np.std(returns) * np.sqrt(252) # Annualized + sharpe_ratio = (np.mean(returns) / np.std(returns)) * np.sqrt(252) + max_drawdown = np.max(np.maximum.accumulate(prices) - prices) / np.max(prices) + + beta = np.cov(returns, benchmark_returns)[0, 1] / np.var(benchmark_returns) + + risk_metrics = { + "volatility": float(volatility), + "sharpe_ratio": float(sharpe_ratio), + "max_drawdown": float(max_drawdown), + "beta": float(beta) + } + + return json.dumps(risk_metrics, indent=2) + + except Exception as e: + return json.dumps({"error": f"Risk calculation error: {str(e)}"}) -analysis = agent.run(analysis_request) -print(analysis) -``` +# Financial analysis schemas +financial_analysis_schema = { + "type": "function", + "function": { + "name": "comprehensive_financial_analysis", + "description": "Perform comprehensive financial analysis with structured output", + "parameters": { + "type": "object", + "properties": { + "analysis_summary": { + "type": "object", + "properties": { + "overall_rating": {"type": "string", "enum": ["buy", "hold", "sell"]}, + "confidence_level": {"type": "number", "minimum": 0, "maximum": 100}, + "key_strengths": {"type": "array", "items": {"type": "string"}}, + "key_concerns": {"type": "array", "items": {"type": "string"}}, + "price_target": {"type": "number"}, + "risk_level": {"type": "string", "enum": ["low", "medium", "high"]} + } + }, + "technical_analysis": { + "type": "object", + "properties": { + "trend_direction": {"type": "string", "enum": ["bullish", "bearish", "neutral"]}, + "support_levels": {"type": "array", "items": {"type": "number"}}, + "resistance_levels": {"type": "array", "items": {"type": "number"}}, + "momentum_indicators": {"type": "array", "items": {"type": "string"}} + } + } + }, + "required": ["analysis_summary", "technical_analysis"] + } + } +} -This example demonstrates how to integrate a time series forecasting model (Prophet) with our AI agent. The agent can then provide insights based on the forecasted data. +# Advanced financial agent +financial_analyst = Agent( + agent_name="Advanced-Financial-Analyst", + agent_description="Comprehensive financial analysis and investment advisory agent", + system_prompt="""You are an expert financial analyst with advanced capabilities in: + + - Fundamental analysis and valuation + - Technical analysis and chart patterns + - Risk assessment and portfolio optimization + - Market sentiment analysis + - Economic indicator interpretation + + Your analysis should be: + - Data-driven and objective + - Risk-aware and practical + - Clearly structured and actionable + - Compliant with financial regulations + + Use available tools to gather market data and calculate risk metrics. + Provide structured outputs using the defined schemas.""", + model_name="gpt-4o-mini", + max_loops=1, + tools=[get_market_data, calculate_risk_metrics], + tools_list_dictionary=[financial_analysis_schema], + output_type="json" +) -### Sentiment Analysis of Social Media +# Comprehensive financial analysis +analysis_response = financial_analyst.run( + "Perform a comprehensive analysis of Apple Inc. (AAPL) including technical and fundamental analysis with structured recommendations" +) -We can use a pre-trained sentiment analysis model to analyze tweets about a company and integrate this with our AI agent: +print(json.dumps(json.loads(analysis_response), indent=2)) +``` + +### Multi-Agent Collaboration System ```python -import os from swarms import Agent -from swarms.models import OpenAIChat -from dotenv import load_dotenv -import tweepy -from textblob import TextBlob -import pandas as pd - -load_dotenv() - -# Twitter API setup -TWITTER_API_KEY = os.getenv("TWITTER_API_KEY") -TWITTER_API_SECRET = os.getenv("TWITTER_API_SECRET") -TWITTER_ACCESS_TOKEN = os.getenv("TWITTER_ACCESS_TOKEN") -TWITTER_ACCESS_TOKEN_SECRET = os.getenv("TWITTER_ACCESS_TOKEN_SECRET") - -auth = tweepy.OAuthHandler(TWITTER_API_KEY, TWITTER_API_SECRET) -auth.set_access_token(TWITTER_ACCESS_TOKEN, TWITTER_ACCESS_TOKEN_SECRET) -api = tweepy.API(auth) +import json -# OpenAI setup -OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") +# Specialized agents for different tasks +research_agent = Agent( + agent_name="Research-Specialist", + agent_description="Market research and data analysis specialist", + system_prompt="You are a market research expert specializing in data collection and analysis.", + model_name="gpt-4o-mini", + max_loops=1, + temperature=0.3 +) -model = OpenAIChat( - openai_api_key=OPENAI_API_KEY, - model_name="gpt-4", - temperature=0.1 +strategy_agent = Agent( + agent_name="Strategy-Advisor", + agent_description="Strategic planning and recommendation specialist", + system_prompt="You are a strategic advisor providing high-level recommendations based on research.", + model_name="gpt-4o-mini", + max_loops=1, + temperature=0.5 ) -agent = Agent( - agent_name="Social-Media-Sentiment-Agent", - system_prompt="You are a financial analysis AI assistant specializing in social media sentiment analysis. Your task is to analyze sentiment data from tweets and provide insights on market perception.", - llm=model, +execution_agent = Agent( + agent_name="Execution-Planner", + agent_description="Implementation and execution planning specialist", + system_prompt="You are an execution expert creating detailed implementation plans.", + model_name="gpt-4o-mini", max_loops=1, - dashboard=False, - verbose=True + temperature=0.4 ) -def get_tweets(query, count=100): - tweets = api.search_tweets(q=query, count=count, tweet_mode="extended") - return [tweet.full_text for tweet in tweets] +def collaborative_analysis(topic: str): + """Perform collaborative analysis using multiple specialized agents.""" + + # Step 1: Research Phase + research_task = f"Conduct comprehensive research on {topic}. Provide key findings, market data, and trends." + research_results = research_agent.run(research_task) + + # Step 2: Strategy Phase + strategy_task = f"Based on this research: {research_results}\n\nDevelop strategic recommendations for {topic}." + strategy_results = strategy_agent.run(strategy_task) + + # Step 3: Execution Phase + execution_task = f"Create a detailed implementation plan based on:\nResearch: {research_results}\nStrategy: {strategy_results}" + execution_results = execution_agent.run(execution_task) + + return { + "research": research_results, + "strategy": strategy_results, + "execution": execution_results + } -def analyze_sentiment(tweets): - sentiments = [TextBlob(tweet).sentiment.polarity for tweet in tweets] - return pd.DataFrame({'tweet': tweets, 'sentiment': sentiments}) +# Example: Collaborative investment analysis +investment_analysis = collaborative_analysis("renewable energy sector investment opportunities") -# Example usage -symbol = "TSLA" -query = f"${symbol} stock" +for phase, results in investment_analysis.items(): + print(f"\n=== {phase.upper()} PHASE ===") + print(results) +``` -tweets = get_tweets(query) -sentiment_data = analyze_sentiment(tweets) +## Support and Resources -analysis_request = f""" -Analyze the following sentiment data for tweets about {symbol} stock: +Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights! -Sentiment Summary: -Positive tweets: {sum(sentiment_data['sentiment'] > 0)} -Negative tweets: {sum(sentiment_data['sentiment'] < 0)} -Neutral tweets: {sum(sentiment_data['sentiment'] == 0)} +| Platform | Description | Link | +|----------|-------------|------| +| 📚 Documentation | Official documentation and guides | [docs.swarms.world](https://docs.swarms.world) | +| 📝 Blog | Latest updates and technical articles | [Medium](https://medium.com/@kyeg) | +| 💬 Discord | Live chat and community support | [Join Discord](https://discord.gg/jM3Z6M9uMq) | +| 🐦 Twitter | Latest news and announcements | [@kyegomez](https://twitter.com/kyegomez) | +| 👥 LinkedIn | Professional network and updates | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | +| 📺 YouTube | Tutorials and demos | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | +| 🎫 Events | Join our community events | [Sign up here](https://lu.ma/5p2jnc2v) | +| 🚀 Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) | -Average sentiment: {sentiment_data['sentiment'].mean()} +### Getting Help -Sample tweets and their sentiments: -{sentiment_data.head(10).to_string()} +If you encounter issues or need assistance: -Provide insights on: -1. The overall sentiment towards the stock -2. Any notable trends or patterns in the sentiment -3. Potential reasons for the observed sentiment -4. How this sentiment might impact the stock price -5. Limitations of this sentiment analysis method -""" +1. **Check the Documentation**: Start with the official docs for comprehensive guides +2. **Search Issues**: Look through existing GitHub issues for similar problems +3. **Join Discord**: Get real-time help from the community +4. **Create an Issue**: Report bugs or request features on GitHub +5. **Follow Updates**: Stay informed about new releases and improvements -analysis = agent.run(analysis_request) -print(analysis) -``` +### Contributing -This example shows how to perform sentiment analysis on tweets about a stock and integrate the results with our AI agent for further analysis. - -### Portfolio Optimization +We welcome contributions! Here's how to get involved: -We can use the PyPortfolioOpt library to perform portfolio optimization and have our AI agent provide insights: +- **Report Bugs**: Help us improve by reporting issues -```python -import os -from swarms import Agent -from swarms.models import OpenAIChat -from dotenv import load_dotenv -import yfinance as yf -import pandas as pd -import numpy as np -from pypfopt import EfficientFrontier -from pypfopt import risk_models -from pypfopt import expected_returns +- **Suggest Features**: Share your ideas for new capabilities -load_dotenv() +- **Submit Code**: Contribute improvements and new features -OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") +- **Improve Documentation**: Help make our docs better -model = OpenAIChat( - openai_api_key=OPENAI_API_KEY, - model_name="gpt-4", - temperature=0.1 -) +- **Share Examples**: Show how you're using Swarms in your projects -agent = Agent( - agent_name="Portfolio-Optimization-Agent", - system_prompt="You are a financial analysis AI assistant specializing in portfolio optimization. Your task is to analyze optimized portfolio allocations and provide investment advice.", - llm=model, - max_loops=1, - dashboard=False, - verbose=True -) +--- -def get_stock_data(symbols, start_date, end_date): - data = yf.download(symbols, start=start_date, end=end_date)['Adj Close'] - return data +*This guide covers the essential aspects of the Swarms Agent class. For the most up-to-date information and advanced features, please refer to the official documentation and community resources.* -def optimize_portfolio(data): - mu = expected_returns.mean_historical_return(data) - S = risk_models.sample_cov(data) - - ef = EfficientFrontier(mu, S) - weights = ef.max_sharpe() - cleaned_weights = ef.clean_weights() - - return cleaned_weights +-------------------------------------------------- -# Example usage -symbols = ["AAPL", "GOOGL", "MSFT", "AMZN", "FB"] -start_date = "2018-01-01" -end_date = "2023-12-31" +# File: swarms\agents\iterative_agent.md -stock_data = get_stock_data(symbols, start_date, end_date) -optimized_weights = optimize_portfolio(stock_data) +# Iterative Reflective Expansion (IRE) Algorithm Documentation -analysis_request = f""" -Analyze the following optimized portfolio allocation: +The Iterative Reflective Expansion (IRE) Algorithm is a sophisticated reasoning framework that employs iterative hypothesis generation, simulation, and refinement to solve complex problems. It leverages a multi-step approach where an AI agent generates initial solution paths, evaluates their effectiveness through simulation, reflects on errors, and dynamically revises reasoning strategies. Through continuous cycles of hypothesis testing and meta-cognitive reflection, the algorithm progressively converges on optimal solutions by learning from both successful and unsuccessful reasoning attempts. -{pd.Series(optimized_weights).to_string()} -The optimization aimed to maximize the Sharpe ratio based on historical data from {start_date} to {end_date}. +## Architecture -Provide insights on: -1. The recommended allocation and its potential benefits -2. Any notable concentrations or diversification in the portfolio -3. Potential risks associated with this allocation -4. How this portfolio might perform in different market conditions -5. Recommendations for an investor considering this allocation -6. Limitations of this optimization method -""" +```mermaid +graph TD + Problem_Input["🧩 Problem Input"] --> Generate_Hypotheses + Generate_Hypotheses["Generate Initial Hypotheses"] --> Simulate + subgraph Iterative Reflective Expansion Loop + Simulate["Simulate Reasoning Paths"] --> Evaluate + Evaluate["Evaluate Outcomes"] --> Reflect{Is solution satisfactory?} + Reflect -->|No, issues found| Meta_Reflect + Reflect -->|Yes| Promising + Meta_Reflect["Meta-Cognitive Reflection"] --> Revise_Paths + Meta_Reflect --> Memory[(Reasoning Memory)] + Meta_Reflect --> Memory + Revise_Paths["Revise Paths Based on Feedback"] --> Expand_Paths + Meta_Reflect --> Revise_Path + Revise_Path["Revise Paths"] --> Expand_Paths + Expand_Paths["Iterative Expansion & Pruning"] --> Simulate + end + Promising["Promising Paths Selected"] --> Memory + Memory["Memory Integration"] --> Synthesize + Synthesize["Synthesize Final Solution"] --> Final["Final Solution ✅"] -analysis = agent.run(analysis_request) -print(analysis) ``` -This example demonstrates how to perform portfolio optimization using the PyPortfolioOpt library and have our AI agent provide insights on the optimized allocation. +--- -## Best Practices and Considerations +## Workflow -When using AI agents for financial data analysis, consider the following best practices: +1. Generate initial hypotheses +2. Simulate paths +3. Reflect on errors +4. Revise paths +5. Select promising paths +6. Synthesize solution -1. Data quality: Ensure that the data you're feeding into the agents is accurate and up-to-date. +## Class: IterativeReflectiveExpansion -2. Model limitations: Be aware of the limitations of both the financial models and the AI models being used. +### Arguments -3. Regulatory compliance: Ensure that your use of AI in financial analysis complies with relevant regulations. +| Argument | Type | Default | Description | +|----------------|--------|---------|-------------| +| agent | Agent | None | The Swarms agent instance used to perform reasoning tasks. | +| max_iterations | int | 5 | Maximum number of iterations for the reasoning process. | +| return_list | bool | False | If True, returns the conversation as a list of messages. | +| return_dict | bool | False | If True, returns the conversation as a dictionary of messages. | +| prompt | str | GENERAL_REASONING_AGENT_SYS_PROMPT | The system prompt for the agent. | -4. Ethical considerations: Be mindful of potential biases in AI models and strive for fair and ethical analysis. +### Methods -5. Continuous monitoring: Regularly evaluate the performance of your AI agents and update them as needed. +| Method | Description | +|-------------------------------|-------------| +| generate_initial_hypotheses | Generates an initial set of reasoning hypotheses based on the problem input. | +| simulate_path | Simulates a given reasoning path and evaluates its effectiveness. | +| meta_reflect | Performs meta-cognitive reflection on the provided error information. | +| revise_path | Revises the reasoning path based on the provided feedback. | +| select_promising_paths | Selects the most promising reasoning paths from a list of candidates. | +| synthesize_solution | Synthesizes a final solution from the promising reasoning paths and historical memory. | +| run | Executes the Iterative Reflective Expansion process on the provided problem. | -6. Human oversight: While AI agents can provide valuable insights, human judgment should always play a role in financial decision-making. +## Use-Cases -7. Privacy and security: Implement robust security measures to protect sensitive financial data. +### Example 1: Solving a Mathematical Problem -## Conclusion +```python +from swarms import IterativeReflectiveExpansion -The integration of AI agents with financial data APIs opens up exciting possibilities for advanced financial analysis. By leveraging the power of the Swarms framework and connecting it with various financial data providers, analysts and quants can gain deeper insights, automate complex analyses, and potentially make more informed investment decisions. +agent = IterativeReflectiveExpansion( + max_iterations=3, +) -However, it's crucial to remember that while AI agents can process vast amounts of data and identify patterns that humans might miss, they should be used as tools to augment human decision-making rather than replace it entirely. The financial markets are complex systems influenced by numerous factors, many of which may not be captured in historical data or current models. +agent.run("What is the 40th prime number?") +``` + +## Conclusion + +The Iterative Reflective Expansion (IRE) Algorithm is a powerful tool for solving complex problems through iterative reasoning and reflection. By leveraging the capabilities of a Swarms agent, it can dynamically adapt and refine its approach to converge on optimal solutions. -As the field of AI in finance continues to evolve, we can expect even more sophisticated analysis techniques and integrations. Staying updated with the latest developments in both AI and financial analysis will be key to leveraging these powerful tools effectively. -------------------------------------------------- -# File: guides/healthcare_blog.md +# File: swarms\agents\message.md -# Unlocking Efficiency and Cost Savings in Healthcare: How Swarms of LLM Agents Can Revolutionize Medical Operations and Save Millions +# The Module/Class Name: Message -The healthcare industry is a complex ecosystem where time and money are critical. From administrative tasks to patient care, medical professionals often struggle to keep up with mounting demands, leading to inefficiencies that cost both time and money. Swarms of Large Language Model (LLM) agents represent a groundbreaking solution to these problems. By leveraging artificial intelligence in the form of swarms, healthcare organizations can automate various tasks, optimize processes, and dramatically improve both the quality of care and operational efficiency. +In the swarms.agents framework, the class `Message` is used to represent a message with timestamp and optional metadata. -In this comprehensive analysis, we will explore how swarms of LLM agents can help healthcare and medical organizations save millions of dollars and thousands of hours annually. We will provide precise estimations based on industry data, calculate potential savings, and outline various use cases. Additionally, mermaid diagrams will be provided to illustrate swarm architectures, and reference links to Swarms GitHub and other resources will be included. +## Overview and Introduction -### 1. Administrative Automation +The `Message` class is a fundamental component that enables the representation of messages within an agent system. Messages contain essential information such as the sender, content, timestamp, and optional metadata. -#### Use Case: Billing and Claims Processing +## Class Definition -Administrative work is a major time drain in the healthcare sector, especially when it comes to billing and claims processing. The process is traditionally labor-intensive, requiring human staff to manually review and process claims, which often results in errors, delays, and higher operational costs. +### Constructor: `__init__` -**How Swarms of LLM Agents Can Help:** -Swarms of LLM agents can automate the entire billing and claims process, from coding procedures to filing claims with insurance companies. These agents can read medical records, understand the diagnosis codes (ICD-10), and automatically generate billing forms. With intelligent claims management, LLM agents can also follow up with insurance companies to ensure timely payment. +The constructor of the `Message` class takes three parameters: -**Estimated Savings:** +1. `sender` (str): The sender of the message. +2. `content` (str): The content of the message. +3. `metadata` (dict or None): Optional metadata associated with the message. -- Average cost per manual claim: $25 +### Methods -- Average claims per hospital: 10,000 per month +1. `__repr__(self)`: Returns a string representation of the `Message` object, including the timestamp, sender, and content. -- Swarms of LLM agents can reduce processing time by 90% and errors by 95% +```python +class Message: + """ + Represents a message with timestamp and optional metadata. -- Estimated annual savings per hospital: + Usage + -------------- + mes = Message( + sender = "Kye", + content = "message" + ) - - Savings per claim: $22.5 (90% reduction) + print(mes) + """ - - Total annual savings: 10,000 claims/month × 12 months × $22.5 = **$2.7 million** + def __init__(self, sender, content, metadata=None): + self.timestamp = datetime.datetime.now() + self.sender = sender + self.content = content + self.metadata = metadata or {} + def __repr__(self): + """ + __repr__ represents the string representation of the Message object. -#### Billing and Claims Processing Swarm -```mermaid -graph TD; - A[Medical Records] --> B[ICD-10 Coding Agent]; - B --> C[Billing Form Agent]; - C --> D[Claims Submission Agent]; - D --> E[Insurance Follow-up Agent]; - E --> F[Payment Processing]; + Returns: + (str) A string containing the timestamp, sender, and content of the message. + """ + return f"{self.timestamp} - {self.sender}: {self.content}" ``` -### 2. Enhancing Clinical Decision Support - -#### Use Case: Diagnostic Assistance +## Functionality and Usage -Doctors are increasingly turning to AI to assist in diagnosing complex medical conditions. Swarms of LLM agents can be trained to analyze patient data, laboratory results, and medical histories to assist doctors in making more accurate diagnoses. +The `Message` class represents a message in the agent system. Upon initialization, the `timestamp` is set to the current date and time, and the `metadata` is set to an empty dictionary if no metadata is provided. -**How Swarms of LLM Agents Can Help:** -A swarm of LLM agents can scan through thousands of medical records, journals, and patient histories to identify patterns or suggest rare diagnoses. These agents work collaboratively to analyze test results, compare symptoms with a vast medical knowledge base, and provide doctors with a list of probable diagnoses and recommended tests. +### Usage Example 1 -**Estimated Savings:** +Creating a `Message` object and displaying its string representation. -- Time saved per diagnosis: 2 hours per patient +```python +mes = Message(sender="Kye", content="Hello! How are you?") -- Average patient cases per hospital: 5,000 per year +print(mes) +``` -- Time saved annually: 2 × 5,000 = 10,000 hours +Output: +``` +2023-09-20 13:45:00 - Kye: Hello! How are you? +``` -- Doctor's hourly rate: $150 +### Usage Example 2 -- Total annual savings: 10,000 × $150 = **$1.5 million** +Creating a `Message` object with metadata. +```python +metadata = {"priority": "high", "category": "urgent"} +mes_with_metadata = Message( + sender="Alice", content="Important update", metadata=metadata +) -#### Diagnostic Swarm -```mermaid -graph TD; - A[Patient Data] --> B[Lab Results]; - A --> C[Medical History]; - B --> D[Symptom Analysis Agent]; - C --> E[Pattern Recognition Agent]; - D --> F[Diagnosis Suggestion Agent]; - E --> F; - F --> G[Doctor]; +print(mes_with_metadata) ``` -### 3. Streamlining Patient Communication +Output: +``` +2023-09-20 13:46:00 - Alice: Important update +``` -#### Use Case: Patient Follow-ups and Reminders +### Usage Example 3 -Timely communication with patients is critical for maintaining healthcare quality, but it can be extremely time-consuming for administrative staff. Missed appointments and delayed follow-ups lead to poor patient outcomes and lost revenue. +Creating a `Message` object without providing metadata. -**How Swarms of LLM Agents Can Help:** -LLM agents can handle patient follow-ups by sending reminders for appointments, check-ups, and medication refills. Additionally, these agents can answer common patient queries, thereby reducing the workload for human staff. These agents can be connected to Electronic Health Record (EHR) systems to monitor patient data and trigger reminders based on predefined criteria. +```python +mes_no_metadata = Message(sender="Bob", content="Reminder: Meeting at 2PM") -**Estimated Savings:** +print(mes_no_metadata) +``` -- Average cost per patient follow-up: $5 +Output: +``` +2023-09-20 13:47:00 - Bob: Reminder: Meeting at 2PM +``` -- Number of follow-ups: 20,000 annually per hospital +## Additional Information and Tips -- Swarm efficiency: 90% reduction in manual effort +When creating a new `Message` object, ensure that the required parameters `sender` and `content` are provided. The `timestamp` will automatically be assigned the current date and time. Optional `metadata` can be included to provide additional context or information associated with the message. -- Total annual savings: 20,000 × $4.5 = **$90,000** +## References and Resources +For further information on the `Message` class and its usage, refer to the official swarms.agents documentation and relevant tutorials related to message handling and communication within the agent system. -#### Patient Follow-up Swarm -```mermaid -graph TD; - A[Patient Data from EHR] --> B[Appointment Reminder Agent]; - A --> C[Medication Reminder Agent]; - B --> D[Automated Text/Email]; - C --> D; - D --> E[Patient]; -``` -### 4. Optimizing Inventory Management +-------------------------------------------------- -#### Use Case: Pharmaceutical Stock Management +# File: swarms\agents\new_agent.md -Hospitals often struggle with managing pharmaceutical inventory efficiently. Overstocking leads to wasted resources, while understocking can be a critical problem for patient care. +# How to Create Good Agents -**How Swarms of LLM Agents Can Help:** -A swarm of LLM agents can predict pharmaceutical needs by analyzing patient data, historical inventory usage, and supplier delivery times. These agents can dynamically adjust stock levels, automatically place orders, and ensure that hospitals have the right medications at the right time. +This guide will walk you through the steps to build high-quality agents by extending the `Agent` class. It emphasizes best practices, the use of type annotations, comprehensive documentation, and modular design to ensure maintainability and scalability. Additionally, you will learn how to incorporate a callable `llm` parameter or specify a `model_name` attribute to enhance flexibility and functionality. These principles ensure that agents are not only functional but also robust and adaptable to future requirements. -**Estimated Savings:** +## Overview -- Annual waste due to overstocking: $500,000 per hospital +A good agent is a modular and reusable component designed to perform specific tasks efficiently. By inheriting from the base `Agent` class, developers can extend its functionality while adhering to standardized principles. Each custom agent should: -- Swarm efficiency: 80% reduction in overstocking +- Inherit from the `Agent` class to maintain compatibility with swarms. +- Define a `run(task: str, img: str)` method to execute tasks effectively. +- Include descriptive attributes such as `name`, `system_prompt`, and `description` to enhance clarity. +- Optionally, include an `llm` parameter (callable) or a `model_name` to enable seamless integration with language models. +- Emphasize modularity, allowing the agent to be reused across various contexts and tasks. -- Total annual savings: $500,000 × 0.8 = **$400,000** +By following these guidelines, you can create agents that integrate well with broader systems and exhibit high reliability in real-world applications. +--- -#### Inventory Management Swarm -```mermaid -graph TD; - A[Patient Admission Data] --> B[Inventory Prediction Agent]; - B --> C[Stock Adjustment Agent]; - C --> D[Supplier Ordering Agent]; - D --> E[Pharmacy]; -``` +## Creating a Custom Agent -### 5. Improving Clinical Research +Here is a detailed template for creating a custom agent by inheriting the `Agent` class. This template demonstrates how to structure an agent with extendable and reusable features: -#### Use Case: Literature Review and Data Analysis +```python +from typing import Callable, Any +from swarms import Agent -Medical researchers spend a significant amount of time reviewing literature and analyzing clinical trial data. Swarms of LLM agents can assist by rapidly scanning through research papers, extracting relevant information, and even suggesting areas for further investigation. +class MyNewAgent(Agent): + """ + A custom agent class for specialized tasks. -**How Swarms of LLM Agents Can Help:** -These agents can be trained to perform literature reviews, extract relevant data, and cross-reference findings with ongoing clinical trials. LLM agents can also simulate clinical trial results by analyzing historical data, offering valuable insights before actual trials commence. + Attributes: + name (str): The name of the agent. + system_prompt (str): The prompt guiding the agent's behavior. + description (str): A brief description of the agent's purpose. + llm (Callable, optional): A callable representing the language model to use. + """ -**Estimated Savings:** + def __init__(self, name: str, system_prompt: str, model_name: str = None, description: str, llm: Callable = None): + """ + Initialize the custom agent. -- Average time spent on literature review per paper: 5 hours + Args: + name (str): The name of the agent. + system_prompt (str): The prompt guiding the agent. + model_name (str): The name of your model can use litellm [openai/gpt-4o] + description (str): A description of the agent's purpose. + llm (Callable, optional): A callable representing the language model to use. + """ + super().__init__(agent_name=name, system_prompt=system_prompt, model_name=model_name) + self.agent_name = agent_name + self.system_prompt system_prompt + self.description = description + self.model_name = model_name -- Number of papers reviewed annually: 1,000 + def run(self, task: str, img: str, *args: Any, **kwargs: Any) -> Any: + """ + Execute the task assigned to the agent. -- Time saved: 80% reduction in review time + Args: + task (str): The task description. + img (str): The image input for processing. + *args: Additional positional arguments. + **kwargs: Additional keyword arguments. -- Total time saved: 1,000 × 5 × 0.8 = 4,000 hours + Returns: + Any: The result of the task execution. + """ + # Your custom logic + ... +``` -- Researcher's hourly rate: $100 +This design ensures a seamless extension of functionality while maintaining clear and maintainable code. -- Total annual savings: 4,000 × $100 = **$400,000** +--- +## Key Considerations -#### Clinical Research Swarm -```mermaid -graph TD; - A[Research Papers] --> B[Data Extraction Agent]; - B --> C[Cross-reference Agent]; - C --> D[Simulation Agent]; - D --> E[Researcher]; -``` +### 1. **Type Annotations** +Always use type hints for method parameters and return values. This improves code readability, supports static analysis tools, and reduces bugs, ensuring long-term reliability. -### 6. Automating Medical Record Keeping +### 2. **Comprehensive Documentation** +Provide detailed docstrings for all classes, methods, and attributes. Clear documentation ensures that your agent's functionality is understandable to both current and future collaborators. -#### Use Case: EHR Management and Documentation +### 3. **Modular Design** +Keep the agent logic modular and reusable. Modularity simplifies debugging, testing, and extending functionalities, making the code more adaptable to diverse scenarios. -Healthcare providers spend a significant amount of time inputting and managing Electronic Health Records (EHR). Manual entry often results in errors and takes away from the time spent with patients. +### 4. **Flexible Model Integration** +Use either an `llm` callable or `model_name` attribute for integrating language models. This flexibility ensures your agent can adapt to various tasks, environments, and system requirements. -**How Swarms of LLM Agents Can Help:** -Swarms of LLM agents can automate the documentation process by transcribing doctor-patient interactions, updating EHRs in real-time, and even detecting errors in the documentation. These agents can integrate with voice recognition systems to create seamless workflows, freeing up more time for healthcare providers to focus on patient care. +### 5. **Error Handling** +Incorporate robust error handling to manage unexpected inputs or issues during execution. This not only ensures reliability but also builds user trust in your system. -**Estimated Savings:** +### 6. **Scalability Considerations** +Ensure your agent design can scale to accommodate increased complexity or a larger number of tasks without compromising performance. -- Average time spent on EHR per patient: 20 minutes +--- -- Number of patients annually: 30,000 +## Example Usage -- Time saved: 80% reduction in manual effort +Here is an example of how to use your custom agent effectively: -- Total time saved: 30,000 × 20 minutes × 0.8 = 480,000 minutes or 8,000 hours +```python +# Example LLM callable +class MockLLM: + """ + A mock language model class for simulating LLM behavior. -- Provider's hourly rate: $150 + Methods: + run(task: str, img: str, *args: Any, **kwargs: Any) -> str: + Processes the task and image input to return a simulated response. + """ -- Total annual savings: 8,000 × $150 = **$1.2 million** + def run(self, task: str, img: str, *args: Any, **kwargs: Any) -> str: + return f"Processed task '{task}' with image '{img}'" +# Create an instance of MyNewAgent +agent = MyNewAgent( + name="ImageProcessor", + system_prompt="Process images and extract relevant details.", + description="An agent specialized in processing images and extracting insights.", + llm=MockLLM().run +) -#### EHR Management Swarm -```mermaid -graph TD; - A[Doctor-Patient Interaction] --> B[Voice-to-Text Agent]; - B --> C[EHR Update Agent]; - C --> D[Error Detection Agent]; - D --> E[EHR System]; +# Run a task +result = agent.run(task="Analyze content", img="path/to/image.jpg") +print(result) ``` -### 7. Reducing Diagnostic Errors - -#### Use Case: Medical Imaging Analysis +This example showcases the practical application of the `MyNewAgent` class and highlights its extensibility. -Medical imaging, such as MRI and CT scans, requires expert interpretation, which can be both time-consuming and prone to errors. Misdiagnoses or delays in interpretation can lead to prolonged treatment times and increased costs. -**How Swarms of LLM Agents Can Help:** -Swarms of LLM agents trained in computer vision can analyze medical images more accurately and faster than human radiologists. These agents can compare current scans with historical data, detect anomalies, and provide a diagnosis within minutes. Additionally, the swarm can escalate complex cases to human experts when necessary. +## Production-Grade Example with **Griptape Agent Integration Example** -**Estimated Savings:** +In this example, we will create a **Griptape** agent by inheriting from the Swarms `Agent` class and implementing the `run` method. -- Time saved per scan: 30 minutes +### **Griptape Integration Steps**: -- Number of scans annually: 10,000 +1. **Inherit from Swarms Agent**: Inherit from the `SwarmsAgent` class. +2. **Create Griptape Agent**: Initialize the **Griptape** agent inside your class and provide it with the necessary tools. +3. **Override the `run()` method**: Implement logic to process a task string and execute the Griptape agent. -- Time saved: 10,000 × 30 minutes = 5,000 hours +## **Griptape Example Code**: -- Radiologist's hourly rate: $200 +```python +from swarms import ( + Agent as SwarmsAgent, +) # Import the base Agent class from Swarms +from griptape.structures import Agent as GriptapeAgent +from griptape.tools import ( + WebScraperTool, + FileManagerTool, + PromptSummaryTool, +) -- Total annual savings: 5,000 × $ +# Create a custom agent class that inherits from SwarmsAgent +class GriptapeSwarmsAgent(SwarmsAgent): + def __init__(self, name: str, system_prompt: str: str, *args, **kwargs): + super().__init__(agent_name=name, system_prompt=system_prompt) + # Initialize the Griptape agent with its tools + self.agent = GriptapeAgent( + input="Load {{ args[0] }}, summarize it, and store it in a file called {{ args[1] }}.", + tools=[ + WebScraperTool(off_prompt=True), + PromptSummaryTool(off_prompt=True), + FileManagerTool(), + ], + *args, + **kwargs, + ) + # Override the run method to take a task and execute it using the Griptape agent + def run(self, task: str) -> str: + # Extract URL and filename from task + url, filename = task.split(",") # Example task string: "https://example.com, output.txt" + # Execute the Griptape agent + result = self.agent.run(url.strip(), filename.strip()) + # Return the final result as a string + return str(result) -200 = **$1 million** -#### Medical Imaging Swarm -```mermaid -graph TD; - A[Medical Image] --> B[Anomaly Detection Agent]; - B --> C[Comparison with Historical Data Agent]; - C --> D[Diagnosis Suggestion Agent]; - D --> E[Radiologist Review]; +# Example usage: +griptape_swarms_agent = GriptapeSwarmsAgent() +output = griptape_swarms_agent.run("https://griptape.ai, griptape.txt") +print(output) ``` -### Conclusion: The Financial and Time-Saving Impact of LLM Swarms in Healthcare - -In this comprehensive analysis, we explored how swarms of LLM agents can revolutionize the healthcare and medical industries by automating complex, labor-intensive tasks that currently drain both time and resources. From billing and claims processing to diagnostic assistance, patient communication, and medical imaging analysis, these intelligent agents can work collaboratively to significantly improve efficiency while reducing costs. Through our detailed calculations, it is evident that healthcare organizations could save upwards of $7.29 million annually, along with thousands of hours in administrative and clinical work. +--- -Swarms of LLM agents not only promise financial savings but also lead to improved patient outcomes, streamlined research, and enhanced operational workflows. By adopting these agentic solutions, healthcare organizations can focus more on their mission of providing high-quality care while ensuring their systems run seamlessly and efficiently. +## Best Practices -To explore more about how swarms of agents can be tailored to your healthcare operations, you can visit the [Swarms GitHub](https://github.com/kyegomez/swarms) for code and documentation, explore our [Swarms Website](https://swarms.world) for further insights, and if you're ready to implement these solutions in your organization, feel free to [book a call](https://cal.com/swarms) for a personalized consultation. +1. **Test Extensively:** + Validate your agent with various task inputs to ensure it performs as expected under different conditions. -The future of healthcare is agentic, and by embracing swarms of LLM agents, your organization can unlock unprecedented levels of productivity and savings. +2. **Follow the Single Responsibility Principle:** + Design each agent to focus on a specific task or role, ensuring clarity and modularity in implementation. -Swarms of LLM agents offer a powerful solution for medical and healthcare organizations looking to reduce costs and save time. Through automation, these agents can optimize everything from administrative tasks to clinical decision-making and inventory management. Based on the estimates provided, healthcare organizations can potentially save millions of dollars annually, all while improving the quality of care provided to patients. +3. **Log Actions:** + Include detailed logging within the `run` method to capture key actions, inputs, and results for debugging and monitoring. -The table below summarizes the estimated savings for each use case: +4. **Use Open-Source Contributions:** + Contribute your custom agents to the Swarms repository at [https://github.com/kyegomez/swarms](https://github.com/kyegomez/swarms). Sharing your innovations helps advance the ecosystem and encourages collaboration. -| Use Case | Estimated Annual Savings | -|------------------------------------|--------------------------| -| Billing and Claims Processing | $2.7 million | -| Diagnostic Assistance | $1.5 million | -| Patient Follow-ups and Reminders | $90,000 | -| Pharmaceutical Stock Management | $400,000 | -| Clinical Research | $400,000 | -| EHR Management and Documentation | $1.2 million | -| Medical Imaging Analysis | $1 million | -| **Total Estimated Savings** | **$7.29 million** | - -### References -- [Swarms GitHub](https://github.com/kyegomez/swarms) +5. **Iterate and Refactor:** + Continuously improve your agents based on feedback, performance evaluations, and new requirements to maintain relevance and functionality. -- [Swarms Website](https://swarms.xyz) +--- -- [book a call](https://cal.com/swarms) +## Conclusion -- Swarms Discord: https://discord.gg/jM3Z6M9uMq +By following these guidelines, you can create powerful and flexible agents tailored to specific tasks. Leveraging inheritance from the `Agent` class ensures compatibility and standardization across swarms. Emphasize modularity, thorough testing, and clear documentation to build agents that are robust, scalable, and easy to integrate. Collaborate with the community by submitting your innovative agents to the Swarms repository, contributing to a growing ecosystem of intelligent solutions. With a well-designed agent, you are equipped to tackle diverse challenges efficiently and effectively. -- Swarms Twitter: https://x.com/swarms_corp -- Swarms Spotify: https://open.spotify.com/show/2HLiswhmUaMdjHC8AUHcCF?si=c831ef10c5ef4994 -Swarms Blog: https://medium.com/@kyeg -Swarms Website: https://swarms.xyz +-------------------------------------------------- -By adopting swarms of LLM agents, healthcare organizations can streamline operations, reduce inefficiencies, and focus on what truly matters—delivering top-notch patient care. +# File: swarms\agents\openai_assistant.md +# OpenAI Assistant +The OpenAI Assistant class provides a wrapper around OpenAI's Assistants API, integrating it with the swarms framework. --------------------------------------------------- +## Overview -# File: guides/pricing.md +The `OpenAIAssistant` class allows you to create and interact with OpenAI Assistants, providing a simple interface for: -# Comparing LLM Provider Pricing: A Guide for Enterprises +- Creating assistants with specific roles and capabilities +- Adding custom functions that the assistant can call +- Managing conversation threads +- Handling tool calls and function execution +- Getting responses from the assistant -Large language models (LLMs) have become a cornerstone of innovation for enterprises across various industries. +## Insstallation -As executives contemplate which model to integrate into their operations, understanding the intricacies of LLM provider pricing is crucial. +```bash +pip install swarms +``` +## Basic Usage -This comprehensive guide delves into the tactical business considerations, unit economics, profit margins, and ROI calculations that will empower decision-makers to deploy the right AI solution for their organization. +```python -## Table of Contents +from swarms import OpenAIAssistant -1. [Introduction to LLM Pricing Models](#introduction-to-llm-pricing-models) -2. [Understanding Unit Economics in LLM Deployment](#understanding-unit-economics-in-llm-deployment) -3. [Profit Margins and Cost Structures](#profit-margins-and-cost-structures) -4. [LLM Pricing in Action: Case Studies](#llm-pricing-in-action-case-studies) -5. [Calculating ROI for LLM Integration](#calculating-roi-for-llm-integration) -6. [Comparative Analysis of Major LLM Providers](#comparative-analysis-of-major-llm-providers) -7. [Hidden Costs and Considerations](#hidden-costs-and-considerations) -8. [Optimizing LLM Usage for Cost-Efficiency](#optimizing-llm-usage-for-cost-efficiency) -9. [Future Trends in LLM Pricing](#future-trends-in-llm-pricing) -10. [Strategic Decision-Making Framework](#strategic-decision-making-framework) -11. [Conclusion: Navigating the LLM Pricing Landscape](#conclusion-navigating-the-llm-pricing-landscape) +#Create an assistant +assistant = OpenAIAssistant( + name="Math Tutor", + instructions="You are a helpful math tutor.", + model="gpt-4o", + tools=[{"type": "code_interpreter"}] +) -## 1. Introduction to LLM Pricing Models +#Run a Task +response = assistant.run("Solve the equation: 3x + 11 = 14") +print(response) -The pricing of Large Language Models (LLMs) is a complex landscape that can significantly impact an enterprise's bottom line. As we dive into this topic, it's crucial to understand the various pricing models employed by LLM providers and how they align with different business needs. +# Continue the conversation in the same thread +follow_up = assistant.run("Now explain how you solved it") +print(follow_up) +``` -### Pay-per-Token Model +## Function Calling -The most common pricing structure in the LLM market is the pay-per-token model. In this system, businesses are charged based on the number of tokens processed by the model. A token can be as short as one character or as long as one word, depending on the language and the specific tokenization method used by the model. +The assistant supports custom function integration: -**Advantages:** -- Scalability: Costs scale directly with usage, allowing for flexibility as demand fluctuates. -- Transparency: Easy to track and attribute costs to specific projects or departments. +```python -**Disadvantages:** -- Unpredictability: Costs can vary significantly based on the verbosity of inputs and outputs. -- Potential for overruns: Without proper monitoring, costs can quickly escalate. +def get_weather(location: str, unit: str = "celsius") -> str: + # Mock weather function + return f"The weather in {location} is 22 degrees {unit}" -### Subscription-Based Models +# Add function to assistant +assistant.add_function( + description="Get the current weather in a location", + parameters={ + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "City name" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"], + "default": "celsius" + } + }, + "required": ["location"] + } +) +``` -Some providers offer subscription tiers that provide a set amount of compute resources or tokens for a fixed monthly or annual fee. +## API Reference -**Advantages:** -- Predictable costs: Easier budgeting and financial planning. -- Potential cost savings: Can be more economical for consistent, high-volume usage. +### Constructor -**Disadvantages:** -- Less flexibility: May lead to underutilization or overages. -- Commitment required: Often involves longer-term contracts. +```python +OpenAIAssistant( + name: str, + instructions: Optional[str] = None, + model: str = "gpt-4o", + tools: Optional[List[Dict[str, Any]]] = None, + file_ids: Optional[List[str]] = None, + metadata: Optional[Dict[str, Any]] = None, + functions: Optional[List[Dict[str, Any]]] = None, +) +``` -### Custom Enterprise Agreements +### Methods -For large-scale deployments, providers may offer custom pricing agreements tailored to the specific needs of an enterprise. +#### run(task: str) -> str +Sends a task to the assistant and returns its response. The conversation thread is maintained between calls. -**Advantages:** -- Optimized for specific use cases: Can include specialized support, SLAs, and pricing structures. -- Potential for significant cost savings at scale. +#### add_function(func: Callable, description: str, parameters: Dict[str, Any]) -> None +Adds a callable function that the assistant can use during conversations. -**Disadvantages:** -- Complexity: Negotiating and managing these agreements can be resource-intensive. -- Less standardization: Difficult to compare across providers. +#### add_message(content: str, file_ids: Optional[List[str]] = None) -> None +Adds a message to the current conversation thread. -### Hybrid Models +## Error Handling -Some providers are beginning to offer hybrid models that combine elements of pay-per-token and subscription-based pricing. +The assistant implements robust error handling: +- Retries on rate limits +- Graceful handling of API errors +- Clear error messages for debugging +- Status monitoring for runs and completions -**Advantages:** -- Flexibility: Can adapt to varying usage patterns. -- Risk mitigation: Balances the benefits of both main pricing models. +## Best Practices -**Disadvantages:** -- Complexity: Can be more challenging to understand and manage. -- Potential for suboptimal pricing if not carefully structured. +1. Thread Management + - Use the same assistant instance for related conversations + - Create new instances for unrelated tasks + - Monitor thread status during long-running operations -As we progress through this guide, we'll explore how these pricing models interact with various business considerations and how executives can leverage this understanding to make informed decisions. +2. Function Integration + - Keep functions simple and focused + - Provide clear descriptions and parameter schemas + - Handle errors gracefully in custom functions + - Test functions independently before integration -## 2. Understanding Unit Economics in LLM Deployment +3. Performance + - Reuse assistant instances when possible + - Monitor and handle rate limits appropriately + - Use appropriate polling intervals for status checks + - Consider implementing timeouts for long-running operations -To make informed decisions about LLM deployment, executives must have a clear grasp of the unit economics involved. This section breaks down the components that contribute to the cost per unit of LLM usage and how they impact overall business economics. +## References -### Defining the Unit +- [OpenAI Assistants API Documentation](https://platform.openai.com/docs/assistants/overview) +- [OpenAI Function Calling Guide](https://platform.openai.com/docs/guides/function-calling) +- [OpenAI Rate Limits](https://platform.openai.com/docs/guides/rate-limits) -In the context of LLMs, a "unit" can be defined in several ways: -1. **Per Token**: The most granular unit, often used in pricing models. -2. **Per Request**: A single API call to the LLM, which may process multiple tokens. -3. **Per Task**: A complete operation, such as generating a summary or answering a question, which may involve multiple requests. -4. **Per User Interaction**: In customer-facing applications, this could be an entire conversation or session. -Understanding which unit is most relevant to your use case is crucial for accurate economic analysis. -### Components of Unit Cost -1. **Direct LLM Costs** - - Token processing fees - - API call charges - - Data transfer costs +-------------------------------------------------- -2. **Indirect Costs** - - Compute resources for pre/post-processing - - Storage for inputs, outputs, and fine-tuning data - - Networking costs +# File: swarms\agents\reasoning_agent_router.md -3. **Operational Costs** - - Monitoring and management tools - - Integration and maintenance engineering time - - Customer support related to AI functions +# ReasoningAgentRouter -4. **Overhead** - - Legal and compliance costs - - Training and documentation - - Risk management and insurance +!!! abstract "Overview" + The ReasoningAgentRouter is a sophisticated agent routing system that enables dynamic selection and execution of different reasoning strategies based on the task requirements. It provides a flexible interface to work with multiple reasoning approaches including Reasoning Duo, Self-Consistency, IRE (Iterative Reflective Expansion), Reflexion, GKP (Generated Knowledge Prompting), and Agent Judge. -### Calculating Unit Economics +## Architecture -To calculate the true unit economics, follow these steps: +```mermaid +graph TD + Task[Task Input] --> Router[ReasoningAgentRouter] + Router --> SelectSwarm{Select Swarm Type} + SelectSwarm -->|Reasoning Duo| RD[ReasoningDuo] + SelectSwarm -->|Self Consistency| SC[SelfConsistencyAgent] + SelectSwarm -->|IRE| IRE[IterativeReflectiveExpansion] + SelectSwarm -->|Reflexion| RF[ReflexionAgent] + SelectSwarm -->|GKP| GKP[GKPAgent] + SelectSwarm -->|Agent Judge| AJ[AgentJudge] + RD --> Output[Task Output] + SC --> Output + IRE --> Output + RF --> Output + GKP --> Output + AJ --> Output +``` -1. **Determine Total Costs**: Sum all direct, indirect, operational, and overhead costs over a fixed period (e.g., monthly). +## Configuration -2. **Measure Total Units**: Track the total number of relevant units processed in the same period. +### Arguments -3. **Calculate Cost per Unit**: Divide total costs by total units. +!!! info "Constructor Parameters" - ``` - Cost per Unit = Total Costs / Total Units - ``` + | Argument | Type | Default | Description | + |----------|------|---------|-------------| + | `agent_name` | str | "reasoning_agent" | Name identifier for the agent | + | `description` | str | "A reasoning agent..." | Description of the agent's capabilities | + | `model_name` | str | "gpt-4o-mini" | The underlying language model to use | + | `system_prompt` | str | "You are a helpful..." | System prompt for the agent | + | `max_loops` | int | 1 | Maximum number of reasoning loops | + | `swarm_type` | agent_types | "reasoning_duo" | Type of reasoning swarm to use | + | `num_samples` | int | 1 | Number of samples for self-consistency | + | `output_type` | OutputType | "dict-all-except-first" | Format of the output | + | `num_knowledge_items` | int | 6 | Number of knowledge items for GKP agent | + | `memory_capacity` | int | 6 | Memory capacity for agents that support it | + | `eval` | bool | False | Enable evaluation mode for self-consistency | + | `random_models_on` | bool | False | Enable random model selection for diversity | + | `majority_voting_prompt` | Optional[str] | None | Custom prompt for majority voting | + | `reasoning_model_name` | Optional[str] | "claude-3-5-sonnet-20240620" | Model to use for reasoning in ReasoningDuo | -4. **Analyze Revenue per Unit**: If the LLM is part of a revenue-generating product, calculate the revenue attributed to each unit. +### Available Agent Types -5. **Determine Profit per Unit**: Subtract the cost per unit from the revenue per unit. +!!! note "Supported Types" + The following agent types are supported through the `swarm_type` parameter: - ``` - Profit per Unit = Revenue per Unit - Cost per Unit - ``` + - `"reasoning-duo"` or `"reasoning-agent"` + - `"self-consistency"` or `"consistency-agent"` + - `"ire"` or `"ire-agent"` + - `"ReflexionAgent"` + - `"GKPAgent"` + - `"AgentJudge"` -### Example Calculation +### Agent Types Comparison -Let's consider a hypothetical customer service AI chatbot: +=== "Reasoning Duo" + **Key Features** + + - Dual agent system + - Collaborative reasoning + - Split between reasoning and execution + + **Best Use Cases** + + - Complex tasks requiring both analysis and action + - Multi-step problem solving + - Tasks needing verification + + **Required Parameters** + + - model_name + - system_prompt + + **Optional Parameters** + + - output_type + - reasoning_model_name (default: "claude-3-5-sonnet-20240620") + - max_loops + - img (for image input support) -- Monthly LLM API costs: $10,000 -- Indirect and operational costs: $5,000 -- Total monthly interactions: 100,000 +=== "Self Consistency" + **Key Features** + + - Multiple solution generation + - Consensus building + - Solution verification + - Concurrent execution + - AI-powered aggregation + + **Best Use Cases** + + - Tasks requiring high reliability + - Problems with multiple approaches + - Validation-heavy tasks + - Mathematical problem solving + - Decision making scenarios + + **Required Parameters** + + - model_name + - system_prompt + + **Optional Parameters** + + - num_samples (default: 5) + - max_loops (default: 1) + - output_type (default: "dict") + - eval (default: False) - Enable answer validation + - random_models_on (default: False) - Enable model diversity + - majority_voting_prompt (default: None) - Custom aggregation prompt -``` -Cost per Interaction = ($10,000 + $5,000) / 100,000 = $0.15 -``` +=== "IRE" + **Key Features** + + - Iterative improvement + - Self-reflection + - Progressive refinement + + **Best Use Cases** + + - Complex reasoning tasks + - Problems requiring refinement + - Learning from previous iterations + + **Required Parameters** + + - model_name + - system_prompt + + **Optional Parameters** + + - max_loops + - max_iterations + - output_type -If each interaction generates an average of $0.50 in value (through cost savings or revenue): +=== "ReflexionAgent" + **Key Features** + + - Self-reflection capabilities + - Learning from experience + - Adaptive reasoning + + **Best Use Cases** + + - Tasks requiring introspection + - Continuous improvement scenarios + - Learning-based tasks + + **Required Parameters** + + - model_name + - system_prompt + + **Optional Parameters** + + - max_loops -``` -Profit per Interaction = $0.50 - $0.15 = $0.35 -``` +=== "GKPAgent" + **Key Features** + + - Knowledge generation + - Information synthesis + - Knowledge base management + + **Best Use Cases** + + - Knowledge-intensive tasks + - Information gathering + - Research-based problems + + **Required Parameters** + + - model_name + - num_knowledge_items + + **Optional Parameters** + + - memory_capacity -### Economies of Scale +=== "AgentJudge" + **Key Features** + + - Solution evaluation + - Quality assessment + - Decision making + + **Best Use Cases** + + - Quality control tasks + - Solution validation + - Performance evaluation + + **Required Parameters** + + - model_name + - system_prompt + + **Optional Parameters** + + - max_loops -As usage increases, unit economics often improve due to: +## Usage -- Volume discounts from LLM providers -- Amortization of fixed costs over more units -- Efficiency gains through learning and optimization +### Methods -However, it's crucial to model how these economies of scale manifest in your specific use case, as they may plateau or even reverse at very high volumes due to increased complexity and support needs. +!!! tip "Available Methods" + | Method | Description | + |--------|-------------| + | `select_swarm()` | Selects and initializes the appropriate reasoning swarm based on specified type | + | `run(task: str, img: Optional[str] = None, **kwargs)` | Executes the selected swarm's reasoning process on the given task | + | `batched_run(tasks: List[str], imgs: Optional[List[str]] = None, **kwargs)` | Executes the reasoning process on a batch of tasks | -### Diseconomies of Scale +### Image Support -Conversely, be aware of potential diseconomies of scale: +!!! info "Multi-modal Capabilities" + The ReasoningAgentRouter supports image inputs for compatible agent types: -- Increased complexity in managing large-scale deployments -- Higher costs for specialized talent as operations grow -- Potential for diminishing returns on very large language models + **Supported Parameters:** + + - `img` (str, optional): Path or URL to a single image file for single task execution + - `imgs` (List[str], optional): List of image paths/URLs for batch task execution -By thoroughly understanding these unit economics, executives can make more informed decisions about which LLM provider and pricing model best aligns with their business objectives and scale. + **Compatible Agent Types:** + + - `reasoning-duo` / `reasoning-agent`: Full image support for both reasoning and execution phases + - Other agent types may have varying levels of image support depending on their underlying implementation -## 3. Profit Margins and Cost Structures + **Usage Example:** + ```python + # Single image with task + router = ReasoningAgentRouter(swarm_type="reasoning-duo") + result = router.run( + task="Describe what you see in this image", + img="path/to/image.jpg" + ) -Understanding profit margins and cost structures is crucial for executives evaluating LLM integration. This section explores how different pricing models and operational strategies can impact overall profitability. + # Batch processing with images + results = router.batched_run( + tasks=["Analyze this chart", "Describe this photo"], + imgs=["chart.png", "photo.jpg"] + ) + ``` -### Components of Profit Margin +### Code Examples -1. **Gross Margin**: The difference between revenue and the direct costs of LLM usage. - ``` - Gross Margin = Revenue - Direct LLM Costs - Gross Margin % = (Gross Margin / Revenue) * 100 - ``` +=== "Basic Usage" + ```python + from swarms.agents.reasoning_agents import ReasoningAgentRouter -2. **Contribution Margin**: Gross margin minus variable operational costs. - ``` - Contribution Margin = Gross Margin - Variable Operational Costs - ``` + # Initialize the router + router = ReasoningAgentRouter( + agent_name="reasoning-agent", + description="A reasoning agent that can answer questions and help with tasks.", + model_name="gpt-4o-mini", + system_prompt="You are a helpful assistant that can answer questions and help with tasks.", + max_loops=1, + swarm_type="self-consistency", + num_samples=3, + eval=False, + random_models_on=False, + majority_voting_prompt=None + ) -3. **Net Margin**: The final profit after all costs, including fixed overheads. - ``` - Net Margin = Contribution Margin - Fixed Costs - Net Margin % = (Net Margin / Revenue) * 100 - ``` + # Run a single task + result = router.run("What is the best approach to solve this problem?") + + # Run with image input + result_with_image = router.run( + "Analyze this image and provide insights", + img="path/to/image.jpg" + ) + ``` -### Cost Structures in LLM Deployment +=== "Self-Consistency Examples" + ```python + # Basic self-consistency + router = ReasoningAgentRouter( + swarm_type="self-consistency", + num_samples=3, + model_name="gpt-4o-mini" + ) + + # Self-consistency with evaluation mode + router = ReasoningAgentRouter( + swarm_type="self-consistency", + num_samples=5, + model_name="gpt-4o-mini", + eval=True, + random_models_on=True + ) + + # Self-consistency with custom majority voting + router = ReasoningAgentRouter( + swarm_type="self-consistency", + num_samples=3, + model_name="gpt-4o-mini", + majority_voting_prompt="Analyze the responses and provide the most accurate answer." + ) + ``` -1. **Fixed Costs** - - Subscription fees for LLM access (if using a subscription model) - - Base infrastructure costs - - Core team salaries - - Licensing fees for essential software +=== "ReflexionAgent" + ```python + router = ReasoningAgentRouter( + swarm_type="ReflexionAgent", + max_loops=3, + model_name="gpt-4o-mini" + ) + ``` -2. **Variable Costs** - - Per-token or per-request charges - - Scaling infrastructure costs - - Usage-based API fees - - Performance-based team bonuses +=== "GKPAgent" + ```python + router = ReasoningAgentRouter( + swarm_type="GKPAgent", + model_name="gpt-4o-mini", + num_knowledge_items=6 + ) + ``` -3. **Step Costs** - - Costs that increase in chunks as usage scales - - Examples: Adding new server clusters, hiring additional support staff +=== "ReasoningDuo Examples" + ```python + # Basic ReasoningDuo + router = ReasoningAgentRouter( + swarm_type="reasoning-duo", + model_name="gpt-4o-mini", + reasoning_model_name="claude-3-5-sonnet-20240620" + ) + + # ReasoningDuo with image support + router = ReasoningAgentRouter( + swarm_type="reasoning-duo", + model_name="gpt-4o-mini", + reasoning_model_name="gpt-4-vision-preview", + max_loops=2 + ) + + result = router.run( + "Analyze this image and explain the patterns you see", + img="data_visualization.png" + ) + ``` -### Analyzing Profit Margins Across Different Pricing Models +=== "AgentJudge" + ```python + router = ReasoningAgentRouter( + swarm_type="AgentJudge", + model_name="gpt-4o-mini", + max_loops=2 + ) + ``` -Let's compare how different LLM pricing models might affect profit margins for a hypothetical AI-powered writing assistant service: +## Best Practices -**Scenario**: The service charges users $20/month and expects to process an average of 100,000 tokens per user per month. +!!! tip "Optimization Tips" + 1. **Swarm Type Selection** + - Use ReasoningDuo for tasks requiring both analysis and action + + - Use SelfConsistency for tasks requiring high reliability + + - Use IRE for complex problem-solving requiring iterative refinement -1. **Pay-per-Token Model** - - LLM cost: $0.06 per 1,000 tokens - - Monthly LLM cost per user: $6 - - Gross margin per user: $14 (70%) + 2. **Performance Optimization** + - Adjust max_loops based on task complexity + + - Increase num_samples for higher reliability (3-7 for most tasks) + + - Choose appropriate model_name based on task requirements + + - Enable random_models_on for diverse reasoning approaches + + - Use eval mode for validation tasks with known answers -2. **Subscription Model** - - Fixed monthly fee: $5,000 for up to 10 million tokens - - At 1,000 users: $5 per user - - Gross margin per user: $15 (75%) + 3. **Output Handling** + - Use appropriate output_type for your needs + + - Process batched results appropriately + + - Handle errors gracefully + + 4. **Self-Consistency Specific** + - Use 3-5 samples for most tasks, 7+ for critical decisions + + - Enable eval mode when you have expected answers for validation + + - Customize majority_voting_prompt for domain-specific aggregation + + - Consider random_models_on for diverse model perspectives -3. **Hybrid Model** - - Base fee: $2,000 per month - - Reduced per-token rate: $0.04 per 1,000 tokens - - Monthly LLM cost per user: $6 ($2 base + $4 usage) - - Gross margin per user: $14 (70%) + 5. **Multi-modal and Reasoning Configuration** + - Use vision-capable models when processing images (e.g., "gpt-4-vision-preview") + + - For ReasoningDuo, set different models for reasoning vs execution via reasoning_model_name + + - Ensure image paths are accessible and in supported formats (JPG, PNG, etc.) + + - Consider using reasoning_model_name with specialized reasoning models for complex tasks -### Strategies for Improving Profit Margins +## Limitations -1. **Optimize Token Usage** - - Implement efficient prompting techniques - - Cache common responses - - Use compression algorithms for inputs and outputs +!!! warning "Known Limitations" + 1. Processing time increases with: + - Higher num_samples + + - Larger max_loops + + - More complex tasks -2. **Leverage Economies of Scale** - - Negotiate better rates at higher volumes - - Spread fixed costs across a larger user base + 2. Model-specific limitations based on: + - Token limits + + - Model capabilities + + - API rate limits -3. **Implement Tiered Pricing** - - Offer different service levels to capture more value from power users - - Example: Basic ($10/month, 50K tokens), Pro ($30/month, 200K tokens) +## Contributing -4. **Vertical Integration** - - Invest in proprietary LLM development for core functionalities - - Reduce dependency on third-party providers for critical operations +!!! note "Development Guidelines" + When extending the ReasoningAgentRouter: + + 1. Follow the existing swarm interface + 2. Add comprehensive tests + 3. Update documentation + 4. Maintain error handling -5. **Smart Caching and Pre-computation** - - Store and reuse common LLM outputs - - Perform batch processing during off-peak hours -6. **Hybrid Cloud Strategies** - - Use on-premises solutions for consistent workloads - - Leverage cloud elasticity for demand spikes +-------------------------------------------------- -### Case Study: Margin Improvement +# File: swarms\agents\reasoning_agents_overview.md -Consider a company that initially used a pay-per-token model: +# Reasoning Agents Overview -**Initial State:** -- Revenue per user: $20 -- LLM cost per user: $6 -- Other variable costs: $4 -- Fixed costs per user: $5 -- Net margin per user: $5 (25%) -**After Optimization:** -- Implemented efficient prompting: Reduced token usage by 20% -- Negotiated volume discount: 10% reduction in per-token price -- Introduced tiered pricing: Average revenue per user increased to $25 -- Optimized operations: Reduced other variable costs to $3 +Reasoning agents are sophisticated agents that employ advanced cognitive strategies to improve problem-solving performance beyond standard language model capabilities. Unlike traditional prompt-based approaches, reasoning agents implement structured methodologies that enable them to think more systematically, self-reflect, collaborate, and iteratively refine their responses. -**Result:** -- New LLM cost per user: $4.32 -- New net margin per user: $12.68 (50.7%) +These agents are inspired by cognitive science and human reasoning processes, incorporating techniques such as: -This case study demonstrates how a holistic approach to margin improvement, addressing both revenue and various cost components, can significantly enhance profitability. +- **Multi-step reasoning**: Breaking down complex problems into manageable components -Understanding these profit margin dynamics and cost structures is essential for executives to make informed decisions about LLM integration and to continuously optimize their AI-powered services for maximum profitability. +- **Self-reflection**: Evaluating and critiquing their own outputs -## 4. LLM Pricing in Action: Case Studies +- **Iterative refinement**: Progressively improving solutions through multiple iterations -To provide a concrete understanding of how LLM pricing models work in real-world scenarios, let's examine several case studies across different industries and use cases. These examples will illustrate the interplay between pricing models, usage patterns, and business outcomes. +- **Collaborative thinking**: Using multiple reasoning pathways or agent perspectives -### Case Study 1: E-commerce Product Description Generator +- **Memory integration**: Learning from past experiences and building knowledge over time -**Company**: GlobalMart, a large online retailer -**Use Case**: Automated generation of product descriptions -**LLM Provider**: GPT-4o +- **Meta-cognitive awareness**: Understanding their own thinking processes and limitations -**Pricing Model**: Pay-per-token -- Input: $5.00 per 1M tokens -- Output: $15.00 per 1M tokens -**Usage Pattern**: -- Average input: 50 tokens per product (product attributes) -- Average output: 200 tokens per product (generated description) -- Daily products processed: 10,000 -**Daily Cost Calculation**: -1. Input cost: (50 tokens * 10,000 products) / 1M * $5.00 = $2.50 -2. Output cost: (200 tokens * 10,000 products) / 1M * $15.00 = $30.00 -3. Total daily cost: $32.50 -**Business Impact**: -- Reduced time to market for new products by 70% -- Improved SEO performance due to unique, keyword-rich descriptions -- Estimated daily value generated: $500 (based on increased sales and efficiency) +## Available Reasoning Agents -**ROI Analysis**: -- Daily investment: $32.50 -- Daily return: $500 -- ROI = (Return - Investment) / Investment * 100 = 1,438% +| Agent Name | Type | Research Paper | Key Features | Best Use Cases | Implementation | Documentation | +|------------|------|----------------|---------------|----------------|----------------|---------------| +| **Self-Consistency Agent** | Consensus-based | [Self-Consistency Improves Chain of Thought Reasoning](https://arxiv.org/abs/2203.07870) (Wang et al., 2022) | • Multiple independent reasoning paths
• Majority voting aggregation
• Concurrent execution
• Validation mode | • Mathematical problem solving
• High-accuracy requirements
• Decision making scenarios
• Answer validation | `SelfConsistencyAgent` | [Guide](consistency_agent.md) | +| **Reasoning Duo** | Collaborative | Novel dual-agent architecture | • Separate reasoning and execution agents
• Collaborative problem solving
• Task decomposition
• Cross-validation | • Complex analysis tasks
• Multi-step problem solving
• Tasks requiring verification
• Research and planning | `ReasoningDuo` | [Guide](reasoning_duo.md) | +| **IRE Agent** | Iterative | Iterative Reflective Expansion framework | • Hypothesis generation
• Path simulation
• Error reflection
• Dynamic revision | • Complex reasoning tasks
• Research problems
• Learning scenarios
• Strategy development | `IterativeReflectiveExpansion` | [Guide](iterative_agent.md) | +| **Reflexion Agent** | Self-reflective | [Reflexion: Language Agents with Verbal Reinforcement Learning](https://arxiv.org/abs/2303.11366) (Shinn et al., 2023) | • Self-evaluation
• Experience memory
• Adaptive improvement
• Learning from failures | • Continuous improvement tasks
• Long-term projects
• Learning scenarios
• Quality refinement | `ReflexionAgent` | [Guide](reflexion_agent.md) | +| **GKP Agent** | Knowledge-based | [Generated Knowledge Prompting](https://arxiv.org/abs/2110.08387) (Liu et al., 2022) | • Knowledge generation
• Multi-perspective reasoning
• Information synthesis
• Fact integration | • Knowledge-intensive tasks
• Research questions
• Fact-based reasoning
• Information synthesis | `GKPAgent` | [Guide](gkp_agent.md) | +| **Agent Judge** | Evaluation | [Agent-as-a-Judge: Evaluate Agents with Agents](https://arxiv.org/abs/2410.10934) | • Quality assessment
• Structured evaluation
• Performance metrics
• Feedback generation | • Quality control
• Output evaluation
• Performance assessment
• Model comparison | `AgentJudge` | [Guide](agent_judge.md) | +| **REACT Agent** | Action-based | [ReAct: Synergizing Reasoning and Acting](https://arxiv.org/abs/2210.03629) (Yao et al., 2022) | • Reason-Act-Observe cycle
• Memory integration
• Action planning
• Experience building | • Interactive tasks
• Tool usage scenarios
• Planning problems
• Learning environments | `ReactAgent` | [Guide](react_agent.md) | -**Key Takeaway**: The pay-per-token model works well for this use case due to the predictable and moderate token usage per task. The high ROI justifies the investment in a more advanced model like GPT-4o. +## Agent Architectures -### Case Study 2: Customer Service Chatbot +### Self-Consistency Agent -**Company**: TechSupport Inc., a software company -**Use Case**: 24/7 customer support chatbot -**LLM Provider**: Claude 3.5 Sonnet +**Description**: Implements multiple independent reasoning paths with consensus-building to improve response reliability and accuracy through majority voting mechanisms. -**Pricing Model**: Input: $3 per 1M tokens, Output: $15 per 1M tokens +**Key Features**: -**Usage Pattern**: -- Average conversation: 500 tokens input (customer queries + context), 1000 tokens output (bot responses) -- Daily conversations: 5,000 +- Concurrent execution of multiple reasoning instances -**Daily Cost Calculation**: -1. Input cost: (500 tokens * 5,000 conversations) / 1M * $3 = $7.50 -2. Output cost: (1000 tokens * 5,000 conversations) / 1M * $15 = $75.00 -3. Total daily cost: $82.50 +- AI-powered aggregation and consensus analysis -**Business Impact**: -- Reduced customer wait times by 90% -- Resolved 70% of queries without human intervention -- Estimated daily cost savings: $2,000 (based on reduced human support hours) +- Validation mode for answer verification -**ROI Analysis**: -- Daily investment: $82.50 -- Daily return: $2,000 -- ROI = (Return - Investment) / Investment * 100 = 2,324% +- Configurable sample sizes and output formats -**Key Takeaway**: The higher cost of Claude 3.5 Sonnet is justified by its superior performance in handling complex customer queries, resulting in significant cost savings and improved customer satisfaction. -### Case Study 3: Financial Report Summarization +**Architecture Diagram**: -**Company**: FinAnalyze, a financial services firm -**Use Case**: Automated summarization of lengthy financial reports -**LLM Provider**: GPT-3.5 Turbo +```mermaid +graph TD + A[Task Input] --> B[Agent Pool] + B --> C[Response 1] + B --> D[Response 2] + B --> E[Response 3] + B --> F[Response N] + C --> G[Aggregation Agent] + D --> G + E --> G + F --> G + G --> H[Majority Voting Analysis] + H --> I[Consensus Evaluation] + I --> J[Final Answer] + + style A fill:#e1f5fe + style J fill:#c8e6c9 + style G fill:#fff3e0 +``` -**Pricing Model**: Input: $0.50 per 1M tokens, Output: $1.50 per 1M tokens +**Use Cases**: Mathematical problem solving, high-stakes decision making, answer validation, quality assurance processes -**Usage Pattern**: -- Average report: 20,000 tokens input, 2,000 tokens output -- Daily reports processed: 100 +**Implementation**: `SelfConsistencyAgent` -**Daily Cost Calculation**: -1. Input cost: (20,000 tokens * 100 reports) / 1M * $0.50 = $100 -2. Output cost: (2,000 tokens * 100 reports) / 1M * $1.50 = $30 -3. Total daily cost: $130 +**Documentation**: [Self-Consistency Agent Guide](consistency_agent.md) -**Business Impact**: -- Reduced analysis time by 80% -- Improved consistency in report summaries -- Enabled analysts to focus on high-value tasks -- Estimated daily value generated: $1,000 (based on time savings and improved decision-making) +--- -**ROI Analysis**: -- Daily investment: $130 -- Daily return: $1,000 -- ROI = (Return - Investment) / Investment * 100 = 669% +### Reasoning Duo -**Key Takeaway**: The lower cost of GPT-3.5 Turbo is suitable for this task, which requires processing large volumes of text but doesn't necessarily need the most advanced language understanding. The high input token count makes the input pricing a significant factor in model selection. +**Description**: Dual-agent collaborative system that separates reasoning and execution phases, enabling specialized analysis and task completion through coordinated agent interaction. -### Case Study 4: AI-Powered Language Learning App +**Key Features**: -**Company**: LinguaLeap, an edtech startup -**Use Case**: Personalized language exercises and conversations -**LLM Provider**: Claude 3 Haiku +- Separate reasoning and execution agents -**Pricing Model**: Input: $0.25 per 1M tokens, Output: $1.25 per 1M tokens +- Collaborative problem decomposition -**Usage Pattern**: -- Average session: 300 tokens input (user responses + context), 500 tokens output (exercises + feedback) -- Daily active users: 50,000 -- Average sessions per user per day: 3 +- Cross-validation between agents -**Daily Cost Calculation**: -1. Input cost: (300 tokens * 3 sessions * 50,000 users) / 1M * $0.25 = $11.25 -2. Output cost: (500 tokens * 3 sessions * 50,000 users) / 1M * $1.25 = $93.75 -3. Total daily cost: $105 +- Configurable model selection for each agent -**Business Impact**: -- Increased user engagement by 40% -- Improved learning outcomes, leading to higher user retention -- Enabled scaling to new languages without proportional increase in human tutors -- Estimated daily revenue: $5,000 (based on subscription fees and in-app purchases) -**ROI Analysis**: -- Daily investment: $105 -- Daily revenue: $5,000 -- ROI = (Revenue - Investment) / Investment * 100 = 4,662% +**Architecture Diagram**: -**Key Takeaway**: The high-volume, relatively simple interactions in this use case make Claude 3 Haiku an excellent choice. Its low cost allows for frequent interactions without prohibitive expenses, which is crucial for an app relying on regular user engagement. +```mermaid +graph TD + A[Task Input] --> B[Reasoning Agent] + B --> C[Deep Analysis] + C --> D[Strategy Planning] + D --> E[Reasoning Output] + E --> F[Main Agent] + F --> G[Task Execution] + G --> H[Response Generation] + H --> I[Final Output] + + style A fill:#e1f5fe + style B fill:#f3e5f5 + style F fill:#e8f5e8 + style I fill:#c8e6c9 +``` -### Case Study 5: Legal Document Analysis +**Use Cases**: Complex analysis tasks, multi-step problem solving, research and planning, verification workflows -**Company**: LegalEagle LLP, a large law firm -**Use Case**: Contract review and risk assessment -**LLM Provider**: Claude 3 Opus +**Implementation**: `ReasoningDuo` -**Pricing Model**: Input: $15 per 1M tokens, Output: $75 per 1M tokens +**Documentation**: [Reasoning Duo Guide](reasoning_duo.md) -**Usage Pattern**: -- Average contract: 10,000 tokens input, 3,000 tokens output (analysis and risk assessment) -- Daily contracts processed: 50 +--- -**Daily Cost Calculation**: -1. Input cost: (10,000 tokens * 50 contracts) / 1M * $15 = $7.50 -2. Output cost: (3,000 tokens * 50 contracts) / 1M * $75 = $11.25 -3. Total daily cost: $18.75 +### IRE Agent (Iterative Reflective Expansion) -**Business Impact**: -- Reduced contract review time by 60% -- Improved accuracy in identifying potential risks -- Enabled handling of more complex cases -- Estimated daily value: $10,000 (based on time savings and improved risk management) +**Description**: Sophisticated reasoning framework employing iterative hypothesis generation, simulation, and refinement through continuous cycles of testing and meta-cognitive reflection. -**ROI Analysis**: -- Daily investment: $18.75 -- Daily value: $10,000 -- ROI = (Value - Investment) / Investment * 100 = 53,233% +**Key Features**: -**Key Takeaway**: Despite the high cost per token, Claude 3 Opus's advanced capabilities justify its use in this high-stakes environment where accuracy and nuanced understanding are critical. The high value generated per task offsets the higher token costs. +- Hypothesis generation and testing -These case studies demonstrate how different LLM providers and pricing models can be optimal for various use cases, depending on factors such as token volume, task complexity, and the value generated by the AI application. Executives should carefully consider these factors when selecting an LLM provider and pricing model for their specific needs. +- Path simulation and evaluation -## 5. Calculating ROI for LLM Integration +- Meta-cognitive reflection capabilities -Calculating the Return on Investment (ROI) for LLM integration is crucial for executives to justify the expenditure and assess the business value of AI implementation. This section will guide you through the process of calculating ROI, considering both tangible and intangible benefits. +- Dynamic strategy revision based on feedback -### The ROI Formula -The basic ROI formula is: +**Architecture Diagram**: -``` -ROI = (Net Benefit / Cost of Investment) * 100 +```mermaid +graph TD + A[Problem Input] --> B[Hypothesis Generation] + B --> C[Path Simulation] + C --> D[Outcome Evaluation] + D --> E{Satisfactory?} + E -->|No| F[Meta-Cognitive Reflection] + F --> G[Path Revision] + G --> H[Knowledge Integration] + H --> C + E -->|Yes| I[Solution Synthesis] + I --> J[Final Answer] + + style A fill:#e1f5fe + style F fill:#fff3e0 + style J fill:#c8e6c9 ``` -For LLM integration, we can expand this to: +**Use Cases**: Complex reasoning tasks, research problems, strategy development, iterative learning scenarios -``` -ROI = ((Total Benefits - Total Costs) / Total Costs) * 100 -``` +**Implementation**: `IterativeReflectiveExpansion` -### Identifying Benefits +**Documentation**: [IRE Agent Guide](iterative_agent.md) -1. **Direct Cost Savings** - - Reduced labor costs - - Decreased operational expenses - - Lower error-related costs +--- -2. **Revenue Increases** - - New product offerings enabled by LLM - - Improved customer acquisition and retention - - Upselling and cross-selling opportunities +### Reflexion Agent -3. **Productivity Gains** - - Time saved on repetitive tasks - - Faster decision-making processes - - Improved employee efficiency +**Description**: Advanced self-reflective system implementing actor-evaluator-reflector architecture for continuous improvement through experience-based learning and memory integration. -4. **Quality Improvements** - - Enhanced accuracy in outputs - - Consistency in service delivery - - Reduced error rates +**Key Features**: -5. **Strategic Advantages** - - Market differentiation - - Faster time-to-market for new offerings - - Improved competitive positioning +- Actor-evaluator-reflector sub-agent architecture -### Calculating Costs +- Self-evaluation and quality assessment -1. **Direct LLM Costs** - - API usage fees - - Subscription costs +- Experience memory and learning capabilities -2. **Infrastructure Costs** - - Cloud computing resources - - Data storage - - Networking expenses +- Adaptive improvement through reflection -3. **Integration and Development Costs** - - Initial setup and integration - - Ongoing maintenance and updates - - Custom feature development -4. **Training and Support** - - Employee training programs - - User support and documentation - - Change management initiatives +**Architecture Diagram**: -5. **Compliance and Security** - - Data privacy measures - - Security audits and implementations - - Regulatory compliance efforts +```mermaid +graph TD + A[Task Input] --> B[Actor Agent] + B --> C[Initial Response] + C --> D[Evaluator Agent] + D --> E[Quality Assessment] + E --> F[Performance Score] + F --> G[Reflector Agent] + G --> H[Self-Reflection] + H --> I[Experience Memory] + I --> J{Max Iterations?} + J -->|No| K[Refined Response] + K --> D + J -->|Yes| L[Final Response] + + style A fill:#e1f5fe + style B fill:#e8f5e8 + style D fill:#fff3e0 + style G fill:#f3e5f5 + style L fill:#c8e6c9 +``` -### Step-by-Step ROI Calculation +**Use Cases**: Continuous improvement tasks, long-term projects, adaptive learning, quality refinement processes -1. **Define the Time Period**: Determine the timeframe for your ROI calculation (e.g., 1 year, 3 years). +**Implementation**: `ReflexionAgent` -2. **Estimate Total Benefits**: - - Quantify direct cost savings and revenue increases - - Assign monetary values to productivity gains and quality improvements - - Estimate the value of strategic advantages (this may be more subjective) +**Documentation**: [Reflexion Agent Guide](reflexion_agent.md) -3. **Calculate Total Costs**: - - Sum up all direct and indirect costs related to LLM integration +--- -4. **Apply the ROI Formula**: - ``` - ROI = ((Total Benefits - Total Costs) / Total Costs) * 100 - ``` +### GKP Agent (Generated Knowledge Prompting) -5. **Consider Time Value of Money**: For longer-term projections, use Net Present Value (NPV) to account for the time value of money. +**Description**: Knowledge-driven reasoning system that generates relevant information before answering queries, implementing multi-perspective analysis through coordinated knowledge synthesis. -### Example ROI Calculation +**Key Features**: -Let's consider a hypothetical customer service chatbot implementation: +- Dynamic knowledge generation -**Time Period**: 1 year +- Multi-perspective reasoning coordination -**Benefits**: -- Labor cost savings: $500,000 -- Increased sales from improved customer satisfaction: $300,000 -- Productivity gains from faster query resolution: $200,000 +- Information synthesis and integration -Total Benefits: $1,000,000 +- Configurable knowledge item generation -**Costs**: -- LLM API fees: $100,000 -- Integration and development: $150,000 -- Training and support: $50,000 -- Infrastructure: $50,000 -Total Costs: $350,000 +**Architecture Diagram**: -**ROI Calculation**: -``` -ROI = (($1,000,000 - $350,000) / $350,000) * 100 = 185.7% +```mermaid +graph TD + A[Query Input] --> B[Knowledge Generator] + B --> C[Generate Knowledge Item 1] + B --> D[Generate Knowledge Item 2] + B --> E[Generate Knowledge Item N] + C --> F[Reasoner Agent] + D --> F + E --> F + F --> G[Knowledge Integration] + G --> H[Reasoning Process] + H --> I[Response Generation] + I --> J[Coordinator] + J --> K[Final Answer] + + style A fill:#e1f5fe + style B fill:#fff3e0 + style F fill:#e8f5e8 + style J fill:#f3e5f5 + style K fill:#c8e6c9 ``` -This indicates a strong positive return on investment, with benefits outweighing costs by a significant margin. - -### Considerations for Accurate ROI Calculation - -1. **Be Conservative in Estimates**: It's better to underestimate benefits and overestimate costs to provide a more realistic view. - -2. **Account for Ramp-Up Time**: Full benefits may not be realized immediately. Consider a phased approach in your calculations. +**Use Cases**: Knowledge-intensive tasks, research questions, fact-based reasoning, information synthesis -3. **Include Opportunity Costs**: Consider the potential returns if the investment were made elsewhere. +**Implementation**: `GKPAgent` -4. **Factor in Risk**: Adjust your ROI based on the likelihood of achieving projected benefits. +**Documentation**: [GKP Agent Guide](gkp_agent.md) -5. **Consider Non-Financial Benefits**: Some benefits, like improved employee satisfaction or enhanced brand perception, may not have direct financial equivalents but are still valuable. +--- -6. **Perform Sensitivity Analysis**: Calculate ROI under different scenarios (best case, worst case, most likely) to understand the range of possible outcomes. +### Agent Judge -7. **Benchmark Against Alternatives**: Compare the ROI of LLM integration against other potential investments or solutions. +**Description**: Specialized evaluation system for assessing agent outputs and system performance, providing structured feedback and quality metrics through comprehensive assessment frameworks. -### Long-Term ROI Considerations +**Key Features**: -While initial ROI calculations are crucial for decision-making, it's important to consider long-term implications: +- Structured evaluation methodology -1. **Scalability**: How will ROI change as usage increases? -2. **Technological Advancements**: Will newer, more efficient models become available? -3. **Market Changes**: How might shifts in the competitive landscape affect the value proposition? -4. **Regulatory Environment**: Could future regulations impact the cost or feasibility of LLM use? +- Quality assessment and scoring -By thoroughly calculating and analyzing the ROI of LLM integration, executives can make data-driven decisions about AI investments and set realistic expectations for the value these technologies can bring to their organizations. +- Performance metrics generation -## 6. Comparative Analysis of Major LLM Providers +- Configurable evaluation criteria -In this section, we'll compare the offerings of major LLM providers, focusing on their pricing structures, model capabilities, and unique selling points. This analysis will help executives understand the landscape and make informed decisions about which provider best suits their needs. -### OpenAI +**Architecture Diagram**: -**Models**: GPT-4o, GPT-3.5 Turbo +```mermaid +graph TD + A[Output to Evaluate] --> B[Evaluation Criteria] + A --> C[Judge Agent] + B --> C + C --> D[Quality Analysis] + D --> E[Criteria Assessment] + E --> F[Scoring Framework] + F --> G[Feedback Generation] + G --> H[Evaluation Report] + + style A fill:#e1f5fe + style C fill:#fff3e0 + style H fill:#c8e6c9 +``` -**Pricing Structure**: -- Pay-per-token model -- Different rates for input and output tokens -- Bulk discounts available for high-volume users +**Use Cases**: Quality control, output evaluation, performance assessment, model comparison -**Key Features**: -- State-of-the-art performance on a wide range of tasks -- Regular model updates and improvements -- Extensive documentation and community support +**Implementation**: `AgentJudge` -**Considerations**: -- Higher pricing compared to some competitors -- Potential for rapid price changes as technology evolves -- Usage limits and approval process for higher-tier models +**Documentation**: [Agent Judge Guide](agent_judge.md) -### Anthropic +--- -**Models**: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku +### REACT Agent (Reason-Act-Observe) -**Pricing Structure**: -- Pay-per-token model -- Different rates for input and output tokens -- Tiered pricing based on model capabilities +**Description**: Action-oriented reasoning system implementing iterative reason-act-observe cycles with memory integration for interactive task completion and environmental adaptation. **Key Features**: -- Strong focus on AI safety and ethics -- Long context windows (200K tokens) -- Specialized models for different use cases (e.g., Haiku for speed, Opus for complex tasks) -**Considerations**: -- Newer to the market compared to OpenAI -- Potentially more limited third-party integrations -- Strong emphasis on responsible AI use +- Reason-Act-Observe cycle implementation -### Google (Vertex AI) +- Memory integration and experience building -**Models**: PaLM 2 for Chat, PaLM 2 for Text +- Action planning and execution -**Pricing Structure**: -- Pay-per-thousand characters model -- Different rates for input and output -- Additional charges for advanced features (e.g., semantic retrieval) +- Environmental state observation -**Key Features**: -- Integration with Google Cloud ecosystem -- Multi-modal capabilities (text, image, audio) -- Enterprise-grade security and compliance features -**Considerations**: -- Pricing can be complex due to additional Google Cloud costs -- Strong performance in specialized domains (e.g., coding, mathematical reasoning) -- Potential for integration with other Google services +**Architecture Diagram**: -### Amazon (Bedrock) +```mermaid +graph TD + A[Task Input] --> B[Memory Review] + B --> C[Current State Observation] + C --> D[Reasoning Process] + D --> E[Action Planning] + E --> F[Action Execution] + F --> G[Outcome Observation] + G --> H[Experience Storage] + H --> I{Task Complete?} + I -->|No| C + I -->|Yes| J[Final Response] + + style A fill:#e1f5fe + style B fill:#f3e5f5 + style D fill:#fff3e0 + style J fill:#c8e6c9 +``` -**Models**: Claude (Anthropic), Titan +**Use Cases**: Interactive tasks, tool usage scenarios, planning problems, learning environments -**Pricing Structure**: -- Pay-per-second of compute time -- Additional charges for data transfer and storage +**Implementation**: `ReactAgent` -**Key Features**: -- Seamless integration with AWS services -- Access to multiple model providers through a single API -- Fine-tuning and customization options +**Documentation**: [REACT Agent Guide](react_agent.md) -**Considerations**: -- Pricing model can be less predictable for inconsistent workloads -- Strong appeal for existing AWS customers -- Potential for cost optimizations through AWS ecosystem -### Microsoft (Azure OpenAI Service) +## Implementation Guide -**Models**: GPT-4, GPT-3.5 Turbo +### Unified Interface via Reasoning Agent Router -**Pricing Structure**: -- Similar to OpenAI's pricing, but with Azure integration -- Additional costs for Azure services (e.g., storage, networking) +The `ReasoningAgentRouter` provides a centralized interface for accessing all reasoning agent implementations: -**Key Features**: -- Enterprise-grade security and compliance -- Integration with Azure AI services -- Access to fine-tuning and customization options +```python +from swarms.agents import ReasoningAgentRouter -**Considerations**: -- Attractive for organizations already using Azure -- Potential for volume discounts through Microsoft Enterprise Agreements -- Additional overhead for Azure management +# Initialize router with specific reasoning strategy +router = ReasoningAgentRouter( + swarm_type="self-consistency", # Select reasoning methodology + model_name="gpt-4o-mini", + num_samples=5, # Configuration for consensus-based methods + max_loops=3 # Configuration for iterative methods +) -### Comparative Analysis +# Execute reasoning process +result = router.run("Analyze the optimal solution for this complex business problem") +print(result) +``` -| Provider | Pricing Model | Strengths | Considerations | -|----------|---------------|-----------|----------------| -| OpenAI | Pay-per-token | - Top performance
- Regular updates
- Strong community | - Higher costs
- Usage limits | -| Anthropic| Pay-per-token | - Ethical focus
- Long context
- Specialized models | - Newer provider
- Limited integrations | -| Google | Pay-per-character | - Google Cloud integration
- Multi-modal
- Enterprise features | - Complex pricing
- Google ecosystem lock-in | -| Amazon | Pay-per-compute time | - AWS integration
- Multiple providers
- Customization options | - Less predictable costs
- AWS ecosystem focus | -| Microsoft| Pay-per-token (Azure-based) | - Enterprise security
- Azure integration
- Fine-tuning options | - Azure overhead
- Potential lock-in | +### Direct Agent Implementation -### Factors to Consider in Provider Selection +```python +from swarms.agents import SelfConsistencyAgent, ReasoningDuo, ReflexionAgent -1. **Performance Requirements**: Assess whether you need state-of-the-art performance or if a less advanced (and potentially cheaper) model suffices. +# Self-Consistency Agent for high-accuracy requirements +consistency_agent = SelfConsistencyAgent( + model_name="gpt-4o-mini", + num_samples=5 +) -2. **Pricing Predictability**: Consider whether your usage patterns align better with token-based or compute-time-based pricing. +# Reasoning Duo for collaborative analysis workflows +duo_agent = ReasoningDuo( + model_names=["gpt-4o-mini", "gpt-4o"] +) -3. **Integration Needs**: Evaluate how well each provider integrates with your existing technology stack. +# Reflexion Agent for adaptive learning scenarios +reflexion_agent = ReflexionAgent( + model_name="gpt-4o-mini", + max_loops=3, + memory_capacity=100 +) +``` -4. **Scalability**: Assess each provider's ability to handle your expected growth in usage. +## Choosing the Right Reasoning Agent -5. **Customization Options**: Determine if you need fine-tuning or specialized model development capabilities. +| Scenario | Recommended Agent | Why? | +|----------|------------------|-------| +| **High-stakes decisions** | Self-Consistency | Multiple validation paths ensure reliability | +| **Complex research tasks** | Reasoning Duo + GKP | Collaboration + knowledge synthesis | +| **Learning & improvement** | Reflexion | Built-in self-improvement mechanisms | +| **Mathematical problems** | Self-Consistency | Proven effectiveness on logical reasoning | +| **Quality assessment** | Agent Judge | Specialized evaluation capabilities | +| **Interactive planning** | REACT | Action-oriented reasoning cycle | +| **Iterative refinement** | IRE | Designed for progressive improvement | -6. **Compliance and Security**: Consider your industry-specific regulatory requirements and each provider's security offerings. -7. **Support and Documentation**: Evaluate the quality of documentation, community support, and enterprise-level assistance. +## Technical Documentation -8. **Ethical Considerations**: Assess each provider's stance on AI ethics and responsible use. +For comprehensive technical documentation on each reasoning agent implementation: -9. **Lock-In Concerns**: Consider the long-term implications of committing to a specific provider or cloud ecosystem. +- [Self-Consistency Agent](consistency_agent.md) -10. **Multi-Provider Strategy**: Evaluate the feasibility and benefits of using multiple providers for different use cases. +- [Reasoning Duo](reasoning_duo.md) -By carefully comparing these providers and considering the factors most relevant to your organization, you can make an informed decision that balances cost, performance, and strategic fit. Remember that the LLM landscape is rapidly evolving, so it's important to regularly reassess your choices and stay informed about new developments and pricing changes. +- [IRE Agent](iterative_agent.md) -## 7. Hidden Costs and Considerations +- [Reflexion Agent](reflexion_agent.md) -When evaluating LLM providers and calculating the total cost of ownership, it's crucial to look beyond the advertised pricing and consider the hidden costs and additional factors that can significantly impact your budget and overall implementation success. This section explores these often-overlooked aspects to help executives make more comprehensive and accurate assessments. +- [GKP Agent](gkp_agent.md) -### 1. Data Preparation and Cleaning +- [Agent Judge](agent_judge.md) -**Considerations**: -- Cost of data collection and aggregation -- Expenses related to data cleaning and normalization -- Ongoing data maintenance and updates +- [Reasoning Agent Router](reasoning_agent_router.md) -**Impact**: -- Can be time-consuming and labor-intensive -- May require specialized tools or personnel -- Critical for model performance and accuracy -### 2. Fine-Tuning and Customization -**Considerations**: -- Costs associated with creating custom datasets -- Compute resources required for fine-tuning -- Potential need for specialized ML expertise +--- -**Impact**: -- Can significantly improve model performance for specific tasks -- May lead to better ROI in the long run -- Increases initial implementation costs +Reasoning agents represent a significant advancement in enterprise agent capabilities, implementing sophisticated cognitive architectures that deliver enhanced reliability, consistency, and performance compared to traditional language model implementations. -### 3. Integration and Development +-------------------------------------------------- -**Considerations**: -- Engineering time for API integration -- Development of custom interfaces or applications -- Ongoing maintenance and updates +# File: swarms\agents\reasoning_duo.md -**Impact**: -- Can be substantial, especially for complex integrations -- May require hiring additional developers or consultants -- Critical for seamless user experience and workflow integration +# ReasoningDuo -### 4. Monitoring and Optimization +The ReasoningDuo class implements a dual-agent reasoning system that combines a reasoning agent and a main agent to provide well-thought-out responses to complex tasks. This architecture enables more robust and reliable outputs by separating the reasoning process from the final response generation. -**Considerations**: -- Tools and systems for performance monitoring -- Regular audits and optimizations -- Costs associated with debugging and troubleshooting -**Impact**: -- Ongoing expense that increases with scale -- Essential for maintaining efficiency and cost-effectiveness -- Can lead to significant savings through optimized usage +## Class Overview -### 5. Compliance and Security +### Constructor Parameters -**Considerations**: -- Legal counsel for data privacy and AI regulations -- Implementation of security measures (e.g., encryption, access controls) -- Regular audits and certifications +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| model_name | str | "reasoning-agent-01" | Name identifier for the reasoning agent | +| description | str | "A highly intelligent..." | Description of the reasoning agent's capabilities | +| model_names | list[str] | ["gpt-4o-mini", "gpt-4o"] | Model names for reasoning and main agents | +| system_prompt | str | "You are a helpful..." | System prompt for the main agent | -**Impact**: -- Can be substantial, especially in heavily regulated industries -- Critical for risk management and maintaining customer trust -- May limit certain use cases or require additional safeguards +### Methods -### 6. Training and Change Management +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | str | Processes a single task through both agents | +| batched_run | tasks: List[str] | List[str] | Processes multiple tasks sequentially | -- Employee training programs -- Development of user guides and documentation -- Change management initiatives -**Impact**: -- Often underestimated but crucial for adoption -- Can affect productivity during the transition period -- Important for realizing the full potential of LLM integration -### 7. Scaling Costs +## Quick Start -**Considerations**: -- Potential price increases as usage grows -- Need for additional infrastructure or resources -- Costs associated with managing increased complexity +```python +from swarms.agents.reasoning_duo import ReasoningDuo -**Impact**: -- Can lead to unexpected expenses if not properly forecasted -- May require renegotiation of contracts or switching providers -- Important to consider in long-term planning +# Initialize the ReasoningDuo +duo = ReasoningDuo( + model_name="reasoning-agent-01", + model_names=["gpt-4o-mini", "gpt-4o"] +) -### 8. Opportunity Costs +# Run a single task +result = duo.run("Explain the concept of gravitational waves") -**Considerations**: -- Time and resources diverted from other projects -- Potential missed opportunities due to focus on LLM implementation -- Learning curve and productivity dips during adoption +# Run multiple tasks +tasks = [ + "Calculate compound interest for $1000 over 5 years", + "Explain quantum entanglement" +] +results = duo.batched_run(tasks) +``` -**Impact**: -- Difficult to quantify but important to consider -- Can affect overall business strategy and priorities -- May influence timing and scope of LLM integration +## Examples -### 9. Vendor Lock-in +### 1. Mathematical Analysis -**Considerations**: -- Costs associated with switching providers -- Dependency on provider-specific features or integrations -- Potential for price increases once deeply integrated +```python +duo = ReasoningDuo() -**Impact**: -- Can limit flexibility and negotiating power -- May affect long-term costs and strategic decisions -- Important to consider multi-provider or portable implementation strategies +# Complex mathematical problem +math_task = """ +Solve the following differential equation: +dy/dx + 2y = x^2, y(0) = 1 +""" -### 10. Ethical and Reputational Considerations +solution = duo.run(math_task) +``` -**Considerations**: -- Potential backlash from AI-related controversies -- Costs of ensuring ethical AI use and transparency -- Investments in responsible AI practices +### 2. Physics Problem -**Impact**: -- Can affect brand reputation and customer trust -- May require ongoing public relations efforts -- Important for long-term sustainability and social responsibility +```python +# Quantum mechanics problem +physics_task = """ +Calculate the wavelength of an electron with kinetic energy of 50 eV +using the de Broglie relationship. +""" -By carefully considering these hidden costs and factors, executives can develop a more comprehensive understanding of the total investment required for successful LLM integration. This holistic approach allows for better budgeting, risk management, and strategic planning. +result = duo.run(physics_task) +``` -## Conclusion: Navigating the LLM Pricing Landscape +### 3. Financial Analysis -As we've explored throughout this guide, the landscape of LLM provider pricing is complex and multifaceted. From understanding the basic pricing models to calculating ROI and considering hidden costs, there are numerous factors that executives must weigh when making decisions about AI integration. +```python +# Complex financial analysis +finance_task = """ +Calculate the Net Present Value (NPV) of a project with: +- Initial investment: $100,000 +- Annual cash flows: $25,000 for 5 years +- Discount rate: 8% +""" -Key takeaways include: +analysis = duo.run(finance_task) +``` -1. The importance of aligning LLM selection with specific business needs and use cases. -2. The need for thorough ROI analysis that goes beyond simple cost calculations. -3. The value of considering both short-term implementation costs and long-term scalability. -4. The critical role of hidden costs in determining the true total cost of ownership. -5. The potential for significant business value when LLMs are strategically implemented and optimized. +## Advanced Usage -As the AI landscape continues to evolve rapidly, staying informed and adaptable is crucial. What may be the best choice today could change as new models are released, pricing structures shift, and your organization's needs evolve. +### Customizing Agent Behavior -To help you navigate these complexities and make the most informed decisions for your enterprise, we invite you to take the next steps in your AI journey: +You can customize both agents by modifying their initialization parameters: -1. **Book a Consultation**: Speak with our enterprise-grade LLM specialists who can provide personalized insights and recommendations tailored to your specific needs. Schedule a 15-minute call at [https://cal.com/swarms/15min](https://cal.com/swarms/15min). +```python +duo = ReasoningDuo( + model_name="custom-reasoning-agent", + description="Specialized financial analysis agent", + model_names=["gpt-4o-mini", "gpt-4o"], + system_prompt="You are a financial expert AI assistant..." +) +``` -2. **Join Our Community**: Connect with fellow AI executives, share experiences, and stay updated on the latest developments in the LLM space. Join our Discord community at [https://discord.gg/yxU9t9da](https://discord.gg/yxU9t9da). +### Batch Processing with Progress Tracking -By leveraging expert guidance and peer insights, you can position your organization to make the most of LLM technologies while optimizing costs and maximizing value. The future of AI in enterprise is bright, and with the right approach, your organization can be at the forefront of this transformative technology. +```python +tasks = [ + "Analyze market trends for tech stocks", + "Calculate risk metrics for a portfolio", + "Forecast revenue growth" +] --------------------------------------------------- +# Process multiple tasks with logging +results = duo.batched_run(tasks) +``` -# File: index.md +## Implementation Details -# Welcome to Swarms Docs Home +The ReasoningDuo uses a two-stage process: -[![Join our Discord](https://img.shields.io/badge/Discord-Join%20our%20server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/jM3Z6M9uMq) [![Subscribe on YouTube](https://img.shields.io/badge/YouTube-Subscribe-red?style=for-the-badge&logo=youtube&logoColor=white)](https://www.youtube.com/@kyegomez3242) [![Connect on LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-blue?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/kye-g-38759a207/) [![Follow on X.com](https://img.shields.io/badge/X.com-Follow-1DA1F2?style=for-the-badge&logo=x&logoColor=white)](https://x.com/swarms_corp) +1. **Reasoning Stage**: The reasoning agent analyzes the task and develops a structured approach +2. **Execution Stage**: The main agent uses the reasoning output to generate the final response -## Swarms Installation +### Internal Architecture -```bash -pip3 install swarms ``` - -## Update Swarms - - -```bash -pip3 install -U swarms +Task Input → Reasoning Agent → Structured Analysis → Main Agent → Final Output ``` -### **Get Started Building Production-Grade Multi-Agent Applications** +## Best Practices -## Onboarding +1. **Task Formulation** + - Be specific and clear in task descriptions + - Include relevant context and constraints + - Break complex problems into smaller subtasks -| Section | Links | -|----------------------|--------------------------------------------------------------------------------------------| -| Installation | [Installation](https://docs.swarms.world/en/latest/swarms/install/install/) | -| Quickstart | [Get Started](https://docs.swarms.world/en/latest/swarms/install/quickstart/) | -| Environment Setup | [Environment Configuration](https://docs.swarms.world/en/latest/swarms/install/workspace_manager/) | -| Environment Variables | [Environment Variables](https://docs.swarms.world/en/latest/swarms/install/env/) | -| Swarms CLI | [CLI Documentation](https://docs.swarms.world/en/latest/swarms/cli/main/) | -| Agent Internal Mechanisms | [Agent Architecture](https://docs.swarms.world/en/latest/swarms/framework/agents_explained/) | -| Agent API | [Agent API](https://docs.swarms.world/en/latest/swarms/structs/agent/) | -| Managing Prompts in Production | [Prompts Management](https://docs.swarms.world/en/latest/swarms/prompts/main/) | -| Integrating External Agents | [External Agents Integration](https://docs.swarms.world/en/latest/swarms/agents/external_party_agents/) | -| Creating Agents from YAML | [YAML Agent Creation](https://docs.swarms.world/en/latest/swarms/agents/create_agents_yaml/) | -| Why You Need Swarms | [Why MultiAgent Collaboration](https://docs.swarms.world/en/latest/swarms/concept/why/) | -| Swarm Architectures Analysis | [Swarm Architectures](https://docs.swarms.world/en/latest/swarms/concept/swarm_architectures/) | -| Choosing the Right Swarm | [How to Choose Swarms](https://docs.swarms.world/en/latest/swarms/concept/how_to_choose_swarms/) | -| Full API Reference | [API Reference](https://docs.swarms.world/en/latest/swarms/framework/reference/) | -| AgentRearrange Docs | [AgentRearrange](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/) | +2. **Performance Optimization** + - Use batched_run for multiple related tasks + - Monitor agent outputs for consistency + - Adjust model parameters based on task complexity +## Error Handling -## Ecosystem +The ReasoningDuo includes built-in logging using the `loguru` library: -Here you'll find references about the Swarms framework, marketplace, community, and more to enable you to build your multi-agent applications. +```python +from loguru import logger -| Section | Links | -|----------------------|--------------------------------------------------------------------------------------------| -| Swarms Python Framework Docs | [Framework Docs](https://docs.swarms.world/en/latest/swarms/install/install/) | -| Swarms Cloud API | [Cloud API](https://docs.swarms.world/en/latest/swarms_cloud/launch/) | -| Swarms Marketplace API | [Marketplace API](https://docs.swarms.world/en/latest/swarms_platform/) | -| Swarms Memory Systems | [Memory Systems](https://docs.swarms.world/en/latest/swarms_memory/) | -| Available Models | [Models Overview](https://docs.swarms.world/en/latest/swarms/models/) | -| Swarms Tools | [Tools Overview](https://docs.swarms.world/en/latest/swarms_tools/overview/) | -| Example Applications | [Examples](https://docs.swarms.world/en/latest/swarms/examples/unique_swarms/) | -| Swarms Corp Github | [Swarms Corp GitHub](https://github.com/The-Swarm-Corporation) | +# Logs are automatically generated for each task +logger.info("Task processing started") +``` +## Limitations -## Community -| Section | Links | -|----------------------|--------------------------------------------------------------------------------------------| -| Community | [Discord](https://discord.gg/jM3Z6M9uMq) | -| Blog | [Blog](https://medium.com/@kyeg) | -| Event Calendar | [LUMA](https://lu.ma/swarms_calendar) | -| Twitter | [Twitter](https://x.com/swarms_corp) | -| Agent Marketplace | [Website](https://swarms.world) | -| Docs | [Website](https://docs.swarms.world) | -| Swarms Website | [Website](https://swarms.ai) | +- Processing time may vary based on task complexity +- Model response quality depends on input clarity +- Resource usage scales with batch size -## Get Support +## Example Script -Want to get in touch with the Swarms team? Open an issue on [GitHub](https://github.com/kyegomez/swarms/issues/new) or reach out to us via [email](mailto:kye@swarms.world). We're here to help! +For a runnable demonstration, see the [reasoning_duo_batched.py](https://github.com/kyegomez/swarms/blob/master/examples/models/reasoning_duo_batched.py) example. -------------------------------------------------- -# File: misc/features/20swarms.md +# File: swarms\agents\reflexion_agent.md -```markdown -# Swarm Alpha: Data Cruncher -**Overview**: Processes large datasets. -**Strengths**: Efficient data handling. -**Weaknesses**: Requires structured data. - -**Pseudo Code**: -```sql -FOR each data_entry IN dataset: - result = PROCESS(data_entry) - STORE(result) -END FOR -RETURN aggregated_results -``` - -# Swarm Beta: Artistic Ally -**Overview**: Generates art pieces. -**Strengths**: Creativity. -**Weaknesses**: Somewhat unpredictable. - -**Pseudo Code**: -```scss -INITIATE canvas_parameters -SELECT art_style -DRAW(canvas_parameters, art_style) -RETURN finished_artwork -``` - -# Swarm Gamma: Sound Sculptor -**Overview**: Crafts audio sequences. -**Strengths**: Diverse audio outputs. -**Weaknesses**: Complexity in refining outputs. - -**Pseudo Code**: -```sql -DEFINE sound_parameters -SELECT audio_style -GENERATE_AUDIO(sound_parameters, audio_style) -RETURN audio_sequence -``` - -# Swarm Delta: Web Weaver -**Overview**: Constructs web designs. -**Strengths**: Modern design sensibility. -**Weaknesses**: Limited to web interfaces. - -**Pseudo Code**: -```scss -SELECT template -APPLY user_preferences(template) -DESIGN_web(template, user_preferences) -RETURN web_design -``` - -# Swarm Epsilon: Code Compiler -**Overview**: Writes and compiles code snippets. -**Strengths**: Quick code generation. -**Weaknesses**: Limited to certain programming languages. - -**Pseudo Code**: -```scss -DEFINE coding_task -WRITE_CODE(coding_task) -COMPILE(code) -RETURN executable -``` - -# Swarm Zeta: Security Shield -**Overview**: Detects system vulnerabilities. -**Strengths**: High threat detection rate. -**Weaknesses**: Potential false positives. - -**Pseudo Code**: -```sql -MONITOR system_activity -IF suspicious_activity_detected: - ANALYZE threat_level - INITIATE mitigation_protocol -END IF -RETURN system_status -``` - -# Swarm Eta: Researcher Relay -**Overview**: Gathers and synthesizes research data. -**Strengths**: Access to vast databases. -**Weaknesses**: Depth of research can vary. - -**Pseudo Code**: -```sql -DEFINE research_topic -SEARCH research_sources(research_topic) -SYNTHESIZE findings -RETURN research_summary -``` - ---- - -# Swarm Theta: Sentiment Scanner -**Overview**: Analyzes text for sentiment and emotional tone. -**Strengths**: Accurate sentiment detection. -**Weaknesses**: Contextual nuances might be missed. - -**Pseudo Code**: -```arduino -INPUT text_data -ANALYZE text_data FOR emotional_tone -DETERMINE sentiment_value -RETURN sentiment_value -``` +# ReflexionAgent -# Swarm Iota: Image Interpreter -**Overview**: Processes and categorizes images. -**Strengths**: High image recognition accuracy. -**Weaknesses**: Can struggle with abstract visuals. +The ReflexionAgent is an advanced AI agent that implements the Reflexion framework to improve through self-reflection. It follows a process of acting on tasks, evaluating its performance, generating self-reflections, and using these reflections to improve future responses. -**Pseudo Code**: -```objective-c -LOAD image_data -PROCESS image_data FOR features -CATEGORIZE image_based_on_features -RETURN image_category -``` +## Overview -# Swarm Kappa: Language Learner -**Overview**: Translates and interprets multiple languages. -**Strengths**: Supports multiple languages. -**Weaknesses**: Nuances in dialects might pose challenges. +The ReflexionAgent consists of three specialized sub-agents: +- **Actor**: Generates initial responses to tasks +- **Evaluator**: Critically assesses responses against quality criteria +- **Reflector**: Generates self-reflections to improve future responses -**Pseudo Code**: -```vbnet -RECEIVE input_text, target_language -TRANSLATE input_text TO target_language -RETURN translated_text -``` +## Initialization -# Swarm Lambda: Trend Tracker -**Overview**: Monitors and predicts trends based on data. -**Strengths**: Proactive trend identification. -**Weaknesses**: Requires continuous data stream. +```python +from swarms.agents import ReflexionAgent -**Pseudo Code**: -```sql -COLLECT data_over_time -ANALYZE data_trends -PREDICT upcoming_trends -RETURN trend_forecast +agent = ReflexionAgent( + agent_name="reflexion-agent", + system_prompt="...", # Optional custom system prompt + model_name="openai/o1", + max_loops=3, + memory_capacity=100 +) ``` -# Swarm Mu: Financial Forecaster -**Overview**: Analyzes financial data to predict market movements. -**Strengths**: In-depth financial analytics. -**Weaknesses**: Market volatility can affect predictions. +### Parameters -**Pseudo Code**: -```sql -GATHER financial_data -COMPUTE statistical_analysis -FORECAST market_movements -RETURN financial_projections -``` +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `agent_name` | `str` | `"reflexion-agent"` | Name of the agent | +| `system_prompt` | `str` | `REFLEXION_PROMPT` | System prompt for the agent | +| `model_name` | `str` | `"openai/o1"` | Model name for generating responses | +| `max_loops` | `int` | `3` | Maximum number of reflection iterations per task | +| `memory_capacity` | `int` | `100` | Maximum capacity of long-term memory | -# Swarm Nu: Network Navigator -**Overview**: Optimizes and manages network traffic. -**Strengths**: Efficient traffic management. -**Weaknesses**: Depends on network infrastructure. +## Methods -**Pseudo Code**: -```sql -MONITOR network_traffic -IDENTIFY congestion_points -OPTIMIZE traffic_flow -RETURN network_status -``` +### act -# Swarm Xi: Content Curator -**Overview**: Gathers and presents content based on user preferences. -**Strengths**: Personalized content delivery. -**Weaknesses**: Limited by available content sources. +Generates a response to the given task using the actor agent. -**Pseudo Code**: -```sql -DEFINE user_preferences -SEARCH content_sources -FILTER content_matching_preferences -DISPLAY curated_content +```python +response = agent.act(task: str, relevant_memories: List[Dict[str, Any]] = None) -> str ``` +| Parameter | Type | Description | +|-----------|------|-------------| +| `task` | `str` | The task to respond to | +| `relevant_memories` | `List[Dict[str, Any]]` | Optional relevant past memories to consider | +### evaluate --------------------------------------------------- - -# File: misc/features/SMAPS.md - -# Swarms Multi-Agent Permissions System (SMAPS) - -## Description -SMAPS is a robust permissions management system designed to integrate seamlessly with Swarm's multi-agent AI framework. Drawing inspiration from Amazon's IAM, SMAPS ensures secure, granular control over agent actions while allowing for collaborative human-in-the-loop interventions. - -## Technical Specification - -### 1. Components - -- **User Management**: Handle user registrations, roles, and profiles. -- **Agent Management**: Register, monitor, and manage AI agents. -- **Permissions Engine**: Define and enforce permissions based on roles. -- **Multiplayer Interface**: Allows multiple human users to intervene, guide, or collaborate on tasks being executed by AI agents. - -### 2. Features - -- **Role-Based Access Control (RBAC)**: - - Users can be assigned predefined roles (e.g., Admin, Agent Supervisor, Collaborator). - - Each role has specific permissions associated with it, defining what actions can be performed on AI agents or tasks. - -- **Dynamic Permissions**: - - Create custom roles with specific permissions. - - Permissions granularity: From broad (e.g., view all tasks) to specific (e.g., modify parameters of a particular agent). - -- **Multiplayer Collaboration**: - - Multiple users can join a task in real-time. - - Collaborators can provide real-time feedback or guidance to AI agents. - - A voting system for decision-making when human intervention is required. - -- **Agent Supervision**: - - Monitor agent actions in real-time. - - Intervene, if necessary, to guide agent actions based on permissions. - -- **Audit Trail**: - - All actions, whether performed by humans or AI agents, are logged. - - Review historical actions, decisions, and interventions for accountability and improvement. - -### 3. Security - -- **Authentication**: Secure login mechanisms with multi-factor authentication options. -- **Authorization**: Ensure users and agents can only perform actions they are permitted to. -- **Data Encryption**: All data, whether at rest or in transit, is encrypted using industry-standard protocols. +Evaluates the quality of a response to a task. -### 4. Integration +```python +evaluation, score = agent.evaluate(task: str, response: str) -> Tuple[str, float] +``` -- **APIs**: Expose APIs for integrating SMAPS with other systems or for extending its capabilities. -- **SDK**: Provide software development kits for popular programming languages to facilitate integration and extension. +| Parameter | Type | Description | +|-----------|------|-------------| +| `task` | `str` | The original task | +| `response` | `str` | The response to evaluate | -## Documentation Description -Swarms Multi-Agent Permissions System (SMAPS) offers a sophisticated permissions management mechanism tailored for multi-agent AI frameworks. It combines the robustness of Amazon IAM-like permissions with a unique "multiplayer" feature, allowing multiple humans to collaboratively guide AI agents in real-time. This ensures not only that tasks are executed efficiently but also that they uphold the highest standards of accuracy and ethics. With SMAPS, businesses can harness the power of swarms with confidence, knowing that they have full control and transparency over their AI operations. +Returns: +- `evaluation`: Detailed feedback on the response +- `score`: Numerical score between 0 and 1 +### reflect --------------------------------------------------- +Generates a self-reflection based on the task, response, and evaluation. -# File: misc/features/agent_archive.md +```python +reflection = agent.reflect(task: str, response: str, evaluation: str) -> str +``` -# AgentArchive Documentation -## Swarms Multi-Agent Framework +| Parameter | Type | Description | +|-----------|------|-------------| +| `task` | `str` | The original task | +| `response` | `str` | The generated response | +| `evaluation` | `str` | The evaluation feedback | -**AgentArchive is an advanced feature crafted to archive, bookmark, and harness the transcripts of agent runs. It promotes the storing and leveraging of successful agent interactions, offering a powerful means for users to derive "recipes" for future agents. Furthermore, with its public archive feature, users can contribute to and benefit from the collective wisdom of the community.** +### refine ---- +Refines the original response based on evaluation and reflection. -## Overview: +```python +refined_response = agent.refine( + task: str, + original_response: str, + evaluation: str, + reflection: str +) -> str +``` -AgentArchive empowers users to: -1. Preserve complete transcripts of agent instances. -2. Bookmark and annotate significant runs. -3. Categorize runs using various tags. -4. Transform successful runs into actionable "recipes". -5. Publish and access a shared knowledge base via a public archive. +| Parameter | Type | Description | +|-----------|------|-------------| +| `task` | `str` | The original task | +| `original_response` | `str` | The original response | +| `evaluation` | `str` | The evaluation feedback | +| `reflection` | `str` | The self-reflection | ---- +### step -## Features: +Processes a single task through one iteration of the Reflexion process. -### 1. Archiving: +```python +result = agent.step( + task: str, + iteration: int = 0, + previous_response: str = None +) -> Dict[str, Any] +``` -- **Save Transcripts**: Retain the full narrative of an agent's interaction and choices. -- **Searchable Database**: Dive into archives using specific keywords, timestamps, or tags. +| Parameter | Type | Description | +|-----------|------|-------------| +| `task` | `str` | The task to process | +| `iteration` | `int` | Current iteration number | +| `previous_response` | `str` | Response from previous iteration | -### 2. Bookmarking: +Returns a dictionary containing: +- `task`: The original task +- `response`: The generated response +- `evaluation`: The evaluation feedback +- `reflection`: The self-reflection +- `score`: Numerical score +- `iteration`: Current iteration number -- **Highlight Essential Runs**: Designate specific agent runs for future reference. -- **Annotations**: Embed notes or remarks to bookmarked runs for clearer understanding. +### run -### 3. Tagging: +Executes the Reflexion process for a list of tasks. -Organize and classify agent runs via: -- **Prompt**: The originating instruction that triggered the agent run. -- **Tasks**: Distinct tasks or operations executed by the agent. -- **Model**: The specific AI model or iteration used during the interaction. -- **Temperature (Temp)**: The set randomness or innovation level for the agent. +```python +results = agent.run( + tasks: List[str], + include_intermediates: bool = False +) -> List[Any] +``` -### 4. Recipe Generation: +| Parameter | Type | Description | +|-----------|------|-------------| +| `tasks` | `List[str]` | List of tasks to process | +| `include_intermediates` | `bool` | Whether to include intermediate iterations in results | -- **Standardization**: Convert successful run transcripts into replicable "recipes". -- **Guidance**: Offer subsequent agents a structured approach, rooted in prior successes. -- **Evolution**: Periodically refine recipes based on newer, enhanced runs. +Returns: +- If `include_intermediates=False`: List of final responses +- If `include_intermediates=True`: List of complete iteration histories -### 5. Public Archive & Sharing: +## Example Usage -- **Publish Successful Runs**: Users can choose to share their successful agent runs. -- **Collaborative Knowledge Base**: Access a shared repository of successful agent interactions from the community. -- **Ratings & Reviews**: Users can rate and review shared runs, highlighting particularly effective "recipes." -- **Privacy & Redaction**: Ensure that any sensitive information is automatically redacted before publishing. +```python +from swarms.agents import ReflexionAgent ---- +# Initialize the Reflexion Agent +agent = ReflexionAgent( + agent_name="reflexion-agent", + model_name="openai/o1", + max_loops=3 +) -## Benefits: +# Example tasks +tasks = [ + "Explain quantum computing to a beginner.", + "Write a Python function to sort a list of dictionaries by a specific key." +] -1. **Efficiency**: Revisit past agent activities to inform and guide future decisions. -2. **Consistency**: Guarantee a uniform approach to recurring challenges, leading to predictable and trustworthy outcomes. -3. **Collaborative Learning**: Tap into a reservoir of shared experiences, fostering community-driven learning and growth. -4. **Transparency**: By sharing successful runs, users can build trust and contribute to the broader community's success. +# Run the agent +results = agent.run(tasks) ---- +# Print results +for i, result in enumerate(results): + print(f"\nTask {i+1}: {tasks[i]}") + print(f"Response: {result}") +``` -## Usage: +## Memory System -1. **Access AgentArchive**: Navigate to the dedicated section within the Swarms Multi-Agent Framework dashboard. -2. **Search, Filter & Organize**: Utilize the search bar and tagging system for precise retrieval. -3. **Bookmark, Annotate & Share**: Pin important runs, add notes, and consider sharing with the broader community. -4. **Engage with Public Archive**: Explore, rate, and apply shared knowledge to enhance agent performance. +The ReflexionAgent includes a sophisticated memory system (`ReflexionMemory`) that maintains both short-term and long-term memories of past experiences, reflections, and feedback. This system helps the agent learn from past interactions and improve its responses over time. ---- +### Memory Features +- Short-term memory for recent interactions +- Long-term memory for important reflections and patterns +- Automatic memory management with capacity limits +- Relevance-based memory retrieval +- Similarity-based deduplication -With AgentArchive, users not only benefit from their past interactions but can also leverage the collective expertise of the Swarms community, ensuring continuous improvement and shared success. +## Best Practices +1. **Task Clarity**: Provide clear, specific tasks to get the best results +2. **Iteration Count**: Adjust `max_loops` based on task complexity (more complex tasks may benefit from more iterations) +3. **Memory Management**: Monitor memory usage and adjust `memory_capacity` as needed +4. **Model Selection**: Choose an appropriate model based on your specific use case and requirements +5. **Error Handling**: Implement proper error handling when using the agent in production -------------------------------------------------- -# File: misc/features/fail_protocol.md +# File: swarms\agents\structured_outputs.md -# Swarms Multi-Agent Framework Documentation +# :material-code-json: Agentic Structured Outputs -## Table of Contents -- Agent Failure Protocol -- Swarm Failure Protocol +!!! abstract "Overview" + Structured outputs help ensure that your agents return data in a consistent, predictable format that can be easily parsed and processed by your application. This is particularly useful when building complex applications that require standardized data handling. ---- +## :material-file-document-outline: Schema Definition -## Agent Failure Protocol +Structured outputs are defined using JSON Schema format. Here's the basic structure: -### 1. Overview -Agent failures may arise from bugs, unexpected inputs, or external system changes. This protocol aims to diagnose, address, and prevent such failures. +=== "Basic Schema" -### 2. Root Cause Analysis -- **Data Collection**: Record the task, inputs, and environmental variables present during the failure. -- **Diagnostic Tests**: Run the agent in a controlled environment replicating the failure scenario. -- **Error Logging**: Analyze error logs to identify patterns or anomalies. + ```python title="Basic Tool Schema" + tools = [ + { + "type": "function", + "function": { + "name": "function_name", + "description": "Description of what the function does", + "parameters": { + "type": "object", + "properties": { + # Define your parameters here + }, + "required": [ + # List required parameters + ] + } + } + } + ] + ``` -### 3. Solution Brainstorming -- **Code Review**: Examine the code sections linked to the failure for bugs or inefficiencies. -- **External Dependencies**: Check if external systems or data sources have changed. -- **Algorithmic Analysis**: Evaluate if the agent's algorithms were overwhelmed or faced an unhandled scenario. +=== "Advanced Schema" -### 4. Risk Analysis & Solution Ranking -- Assess the potential risks associated with each solution. -- Rank solutions based on: - - Implementation complexity - - Potential negative side effects - - Resource requirements -- Assign a success probability score (0.0 to 1.0) based on the above factors. + ```python title="Advanced Tool Schema with Multiple Parameters" + tools = [ + { + "type": "function", + "function": { + "name": "advanced_function", + "description": "Advanced function with multiple parameter types", + "parameters": { + "type": "object", + "properties": { + "text_param": { + "type": "string", + "description": "A text parameter" + }, + "number_param": { + "type": "number", + "description": "A numeric parameter" + }, + "boolean_param": { + "type": "boolean", + "description": "A boolean parameter" + }, + "array_param": { + "type": "array", + "items": {"type": "string"}, + "description": "An array of strings" + } + }, + "required": ["text_param", "number_param"] + } + } + } + ] + ``` -### 5. Solution Implementation -- Implement the top 3 solutions sequentially, starting with the highest success probability. -- If all three solutions fail, trigger the "Human-in-the-Loop" protocol. +### :material-format-list-bulleted-type: Parameter Types ---- +The following parameter types are supported: -## Swarm Failure Protocol +| Type | Description | Example | +|------|-------------|---------| +| `string` | Text values | `"Hello World"` | +| `number` | Numeric values | `42`, `3.14` | +| `boolean` | True/False values | `true`, `false` | +| `object` | Nested objects | `{"key": "value"}` | +| `array` | Lists or arrays | `[1, 2, 3]` | +| `null` | Null values | `null` | -### 1. Overview -Swarm failures are more complex, often resulting from inter-agent conflicts, systemic bugs, or large-scale environmental changes. This protocol delves deep into such failures to ensure the swarm operates optimally. +## :material-cog: Implementation Steps -### 2. Root Cause Analysis -- **Inter-Agent Analysis**: Examine if agents were in conflict or if there was a breakdown in collaboration. -- **System Health Checks**: Ensure all system components supporting the swarm are operational. -- **Environment Analysis**: Investigate if external factors or systems impacted the swarm's operation. +!!! tip "Quick Start Guide" + Follow these steps to implement structured outputs in your agent: -### 3. Solution Brainstorming -- **Collaboration Protocols**: Review and refine how agents collaborate. -- **Resource Allocation**: Check if the swarm had adequate computational and memory resources. -- **Feedback Loops**: Ensure agents are effectively learning from each other. +### Step 1: Define Your Schema -### 4. Risk Analysis & Solution Ranking -- Assess the potential systemic risks posed by each solution. -- Rank solutions considering: - - Scalability implications - - Impact on individual agents - - Overall swarm performance potential -- Assign a success probability score (0.0 to 1.0) based on the above considerations. +```python +tools = [ + { + "type": "function", + "function": { + "name": "get_stock_price", + "description": "Retrieve stock price information", + "parameters": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "Stock ticker symbol" + }, + "include_volume": { + "type": "boolean", + "description": "Include trading volume data" + } + }, + "required": ["ticker"] + } + } + } +] +``` -### 5. Solution Implementation -- Implement the top 3 solutions sequentially, prioritizing the one with the highest success probability. -- If all three solutions are unsuccessful, invoke the "Human-in-the-Loop" protocol for expert intervention. +### Step 2: Initialize the Agent ---- +``` +from swarms import Agent -By following these protocols, the Swarms Multi-Agent Framework can systematically address and prevent failures, ensuring a high degree of reliability and efficiency. +agent = Agent( + agent_name="Your-Agent-Name", + agent_description="Agent description", + system_prompt="Your system prompt", + tools_list_dictionary=tools +) +``` +### Step 3: Run the Agent --------------------------------------------------- +```python +response = agent.run("Your query here") +``` -# File: misc/features/human_in_loop.md +### Step 4: Parse the Output -# Human-in-the-Loop Task Handling Protocol +```python +from swarms.utils.str_to_dict import str_to_dict -## Overview +parsed_output = str_to_dict(response) +``` -The Swarms Multi-Agent Framework recognizes the invaluable contributions humans can make, especially in complex scenarios where nuanced judgment is required. The "Human-in-the-Loop Task Handling Protocol" ensures that when agents encounter challenges they cannot handle autonomously, the most capable human collaborator is engaged to provide guidance, based on their skills and expertise. +## :material-code-braces: Example Usage -## Protocol Steps +!!! example "Complete Financial Agent Example" + Here's a comprehensive example using a financial analysis agent: -### 1. Task Initiation & Analysis +=== "Python Implementation" -- When a task is initiated, agents first analyze the task's requirements. -- The system maintains an understanding of each task's complexity, requirements, and potential challenges. + ```python + from dotenv import load_dotenv + from swarms import Agent + from swarms.utils.str_to_dict import str_to_dict + + # Load environment variables + load_dotenv() + + # Define tools with structured output schema + tools = [ + { + "type": "function", + "function": { + "name": "get_stock_price", + "description": "Retrieve the current stock price and related information", + "parameters": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "Stock ticker symbol (e.g., AAPL, GOOGL)" + }, + "include_history": { + "type": "boolean", + "description": "Include historical data in the response" + }, + "time": { + "type": "string", + "format": "date-time", + "description": "Specific time for stock data (ISO format)" + } + }, + "required": ["ticker", "include_history", "time"] + } + } + } + ] + + # Initialize agent + agent = Agent( + agent_name="Financial-Analysis-Agent", + agent_description="Personal finance advisor agent", + system_prompt="You are a helpful financial analysis assistant.", + max_loops=1, + tools_list_dictionary=tools + ) + + # Run agent + response = agent.run("What is the current stock price for AAPL?") + + # Parse structured output + parsed_data = str_to_dict(response) + print(f"Parsed response: {parsed_data}") + ``` -### 2. Automated Resolution Attempt +=== "Expected Output" -- Agents first attempt to resolve the task autonomously using their algorithms and data. -- If the task can be completed without issues, it progresses normally. + ```json + { + "function_calls": [ + { + "name": "get_stock_price", + "arguments": { + "ticker": "AAPL", + "include_history": true, + "time": "2024-01-15T10:30:00Z" + } + } + ] + } + ``` -### 3. Challenge Detection +## :material-check-circle: Best Practices -- If agents encounter challenges or uncertainties they cannot resolve, the "Human-in-the-Loop" protocol is triggered. - -### 4. Human Collaborator Identification +!!! success "Schema Design" + + - **Keep it simple**: Design schemas that are as simple as possible while meeting your needs + + - **Clear naming**: Use descriptive parameter names that clearly indicate their purpose + + - **Detailed descriptions**: Include comprehensive descriptions for each parameter + + - **Required fields**: Explicitly specify all required parameters -- The system maintains a dynamic profile of each human collaborator, cataloging their skills, expertise, and past performance on related tasks. -- Using this profile data, the system identifies the most capable human collaborator to assist with the current challenge. +!!! info "Error Handling" + + - **Validate output**: Always validate the output format before processing + + - **Exception handling**: Implement proper error handling for parsing failures + + - **Safety first**: Use try-except blocks when converting strings to dictionaries -### 5. Real-time Collaboration +!!! performance "Performance Tips" + + - **Minimize requirements**: Keep the number of required parameters to a minimum + + - **Appropriate types**: Use the most appropriate data types for each parameter + + - **Caching**: Consider caching parsed results if they're used frequently -- The identified human collaborator is notified and provided with all the relevant information about the task and the challenge. -- Collaborators can provide guidance, make decisions, or even take over specific portions of the task. - -### 6. Task Completion & Feedback Loop +## :material-alert-circle: Troubleshooting -- Once the challenge is resolved, agents continue with the task until completion. -- Feedback from human collaborators is used to update agent algorithms, ensuring continuous learning and improvement. +!!! warning "Common Issues" -## Best Practices +### Invalid Output Format -1. **Maintain Up-to-date Human Profiles**: Ensure that the skillsets, expertise, and performance metrics of human collaborators are updated regularly. -2. **Limit Interruptions**: Implement mechanisms to limit the frequency of human interventions, ensuring collaborators are not overwhelmed with requests. -3. **Provide Context**: When seeking human intervention, provide collaborators with comprehensive context to ensure they can make informed decisions. -4. **Continuous Training**: Regularly update and train agents based on feedback from human collaborators. -5. **Measure & Optimize**: Monitor the efficiency of the "Human-in-the-Loop" protocol, aiming to reduce the frequency of interventions while maximizing the value of each intervention. -6. **Skill Enhancement**: Encourage human collaborators to continuously enhance their skills, ensuring that the collective expertise of the group grows over time. +!!! failure "Problem" + The agent returns data in an unexpected format -## Conclusion +!!! success "Solution" + + - Ensure your schema matches the expected output structure + + - Verify all required fields are present in the response + + - Check for proper JSON formatting in the output -The integration of human expertise with AI capabilities is a cornerstone of the Swarms Multi-Agent Framework. This "Human-in-the-Loop Task Handling Protocol" ensures that tasks are executed efficiently, leveraging the best of both human judgment and AI automation. Through collaborative synergy, we can tackle challenges more effectively and drive innovation. +### Parsing Errors +!!! failure "Problem" + Errors occur when trying to parse the agent's response --------------------------------------------------- +!!! success "Solution" + + ```python + from swarms.utils.str_to_dict import str_to_dict + + try: + parsed_data = str_to_dict(response) + except Exception as e: + print(f"Parsing error: {e}") + # Handle the error appropriately + ``` -# File: misc/features/info_sec.md +### Missing Fields -# Secure Communication Protocols +!!! failure "Problem" + Required fields are missing from the output -## Overview +!!! success "Solution" + - Verify all required fields are defined in the schema + - Check if the agent is properly configured with the tools + - Review the system prompt for clarity and completeness -The Swarms Multi-Agent Framework prioritizes the security and integrity of data, especially personal and sensitive information. Our Secure Communication Protocols ensure that all communications between agents are encrypted, authenticated, and resistant to tampering or unauthorized access. +## :material-lightbulb: Advanced Features -## Features +!!! note "Pro Tips" + + === "Nested Objects" + + ```python title="nested_schema.py" + "properties": { + "user_info": { + "type": "object", + "properties": { + "name": {"type": "string"}, + "age": {"type": "number"}, + "preferences": { + "type": "array", + "items": {"type": "string"} + } + } + } + } + ``` + + === "Conditional Fields" + + ```python title="conditional_schema.py" + "properties": { + "data_type": { + "type": "string", + "enum": ["stock", "crypto", "forex"] + }, + "symbol": {"type": "string"}, + "exchange": { + "type": "string", + "description": "Required for crypto and forex" + } + } + ``` -### 1. End-to-End Encryption +--- -- All inter-agent communications are encrypted using state-of-the-art cryptographic algorithms. -- This ensures that data remains confidential and can only be read by the intended recipient agent. -### 2. Authentication -- Before initiating communication, agents authenticate each other using digital certificates. -- This prevents impersonation attacks and ensures that agents are communicating with legitimate counterparts. +-------------------------------------------------- -### 3. Forward Secrecy +# File: swarms\agents\third_party.md -- Key exchange mechanisms employ forward secrecy, meaning that even if a malicious actor gains access to an encryption key, they cannot decrypt past communications. - -### 4. Data Integrity +# Swarms Framework: Integrating and Customizing Agent Libraries -- Cryptographic hashes ensure that the data has not been altered in transit. -- Any discrepancies in data integrity result in the communication being rejected. +Agent-based systems have emerged as a powerful paradigm for solving complex problems and automating tasks. -### 5. Zero-Knowledge Protocols +The swarms framework offers a flexible and extensible approach to working with various agent libraries, allowing developers to create custom agents and integrate them seamlessly into their projects. -- When handling especially sensitive data, agents use zero-knowledge proofs to validate information without revealing the actual data. - -### 6. Periodic Key Rotation +In this comprehensive guide, we'll explore the swarms framework, discuss agent handling, and demonstrate how to build custom agents using swarms. We'll also cover the integration of popular agent libraries such as Langchain, Griptape, CrewAI, and Autogen. -- To mitigate the risk of long-term key exposure, encryption keys are periodically rotated. -- Old keys are securely discarded, ensuring that even if they are compromised, they cannot be used to decrypt communications. +## Table of Contents -## Best Practices for Handling Personal and Sensitive Information +1. [Introduction to the Swarms Framework](#introduction-to-the-swarms-framework) +2. [The Need for Wrappers](#the-need-for-wrappers) +3. [Building Custom Agents with Swarms](#building-custom-agents-with-swarms) +4. [Integrating Third-Party Agent Libraries](#integrating-third-party-agent-libraries) + - [Griptape Integration](#griptape-integration) + - [Langchain Integration](#langchain-integration) + - [CrewAI Integration](#crewai-integration) + - [Autogen Integration](#autogen-integration) +5. [Advanced Agent Handling Techniques](#advanced-agent-handling-techniques) +6. [Best Practices for Custom Agent Development](#best-practices-for-custom-agent-development) +7. [Future Directions and Challenges](#future-directions-and-challenges) +8. [Conclusion](#conclusion) -1. **Data Minimization**: Agents should only request and process the minimum amount of personal data necessary for the task. -2. **Anonymization**: Whenever possible, agents should anonymize personal data, stripping away identifying details. -3. **Data Retention Policies**: Personal data should be retained only for the period necessary to complete the task, after which it should be securely deleted. -4. **Access Controls**: Ensure that only authorized agents have access to personal and sensitive information. Implement strict access control mechanisms. -5. **Regular Audits**: Conduct regular security audits to ensure compliance with privacy regulations and to detect any potential vulnerabilities. -6. **Training**: All agents should be regularly updated and trained on the latest security protocols and best practices for handling sensitive data. +## 1. Introduction to the Swarms Framework -## Conclusion +The swarms framework is a powerful and flexible system designed to facilitate the creation, management, and coordination of multiple AI agents. It provides a standardized interface for working with various agent types, allowing developers to leverage the strengths of different agent libraries while maintaining a consistent programming model. -Secure communication is paramount in the Swarms Multi-Agent Framework, especially when dealing with personal and sensitive information. Adhering to these protocols and best practices ensures the safety, privacy, and trust of all stakeholders involved. +At its core, the swarms framework is built around the concept of a parent `Agent` class, which serves as a foundation for creating custom agents and integrating third-party agent libraries. This approach offers several benefits: +1. **Consistency**: By wrapping different agent implementations with a common interface, developers can work with a unified API across various agent types. +2. **Extensibility**: The framework makes it easy to add new agent types or customize existing ones without affecting the overall system architecture. +3. **Interoperability**: Agents from different libraries can communicate and collaborate seamlessly within the swarms ecosystem. +4. **Scalability**: The standardized approach allows for easier scaling of agent-based systems, from simple single-agent applications to complex multi-agent swarms. --------------------------------------------------- +## 2. The Need for Wrappers -# File: misc/features/promptimizer.md +As the field of AI and agent-based systems continues to grow, numerous libraries and frameworks have emerged, each with its own strengths and specialized features. While this diversity offers developers a wide range of tools to choose from, it also presents challenges in terms of integration and interoperability. -# Promptimizer Documentation -## Swarms Multi-Agent Framework +This is where the concept of wrappers becomes crucial. By creating wrappers around different agent libraries, we can: -**The Promptimizer Tool stands as a cornerstone innovation within the Swarms Multi-Agent Framework, meticulously engineered to refine and supercharge prompts across diverse categories. Capitalizing on extensive libraries of best-practice prompting techniques, this tool ensures your prompts are razor-sharp, tailored, and primed for optimal outcomes.** +1. **Unify interfaces**: Standardize the way we interact with agents, regardless of their underlying implementation. +2. **Simplify integration**: Make it easier to incorporate new agent libraries into existing projects. +3. **Enable composition**: Allow for the creation of complex agent systems that leverage the strengths of multiple libraries. +4. **Facilitate maintenance**: Centralize the management of agent-related code and reduce the impact of library-specific changes. ---- +In the context of the swarms framework, wrappers take the form of custom classes that inherit from the parent `Agent` class. These wrapper classes encapsulate the functionality of specific agent libraries while exposing a consistent interface that aligns with the swarms framework. -## Overview: +## 3. Building Custom Agents with Swarms -The Promptimizer Tool is crafted to: -1. Rigorously analyze and elevate the quality of provided prompts. -2. Furnish best-in-class recommendations rooted in proven prompting strategies. -3. Serve a spectrum of categories, from technical operations to expansive creative ventures. +To illustrate the process of building custom agents using the swarms framework, let's start with a basic example of creating a custom agent class: ---- +```python +from swarms import Agent -## Core Features: +class MyCustomAgent(Agent): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + # Custom initialization logic -### 1. Deep Prompt Analysis: + def custom_method(self, *args, **kwargs): + # Implement custom logic here + pass -- **Clarity Matrix**: A proprietary algorithm assessing prompt clarity, removing ambiguities and sharpening focus. -- **Efficiency Gauge**: Evaluates the prompt's structure to ensure swift and precise desired results. + def run(self, task, *args, **kwargs): + # Customize the run method + response = super().run(task, *args, **kwargs) + # Additional custom logic + return response +``` -### 2. Adaptive Recommendations: +This example demonstrates the fundamental structure of a custom agent class within the swarms framework. Let's break down the key components: -- **Technique Engine**: Suggests techniques aligned with the gold standard for the chosen category. -- **Exemplar Database**: Offers an extensive array of high-quality prompt examples for comparison and inspiration. +1. **Inheritance**: The class inherits from the `Agent` parent class, ensuring it adheres to the swarms framework's interface. -### 3. Versatile Category Framework: +2. **Initialization**: The `__init__` method calls the parent class's initializer and can include additional custom initialization logic. -- **Tech Suite**: Optimizes prompts for technical tasks, ensuring actionable clarity. -- **Narrative Craft**: Hones prompts to elicit vivid and coherent stories. -- **Visual Visionary**: Shapes prompts for precise and dynamic visual generation. -- **Sonic Sculptor**: Orchestrates prompts for audio creation, tuning into desired tones and moods. +3. **Custom methods**: You can add any number of custom methods to extend the agent's functionality. -### 4. Machine Learning Integration: +4. **Run method**: The `run` method is a key component of the agent interface. By overriding this method, you can customize how the agent processes tasks while still leveraging the parent class's functionality. -- **Feedback Dynamo**: Harnesses user feedback, continually refining the tool's recommendation capabilities. -- **Live Library Updates**: Periodic syncing with the latest in prompting techniques, ensuring the tool remains at the cutting edge. +To create more sophisticated custom agents, you can expand on this basic structure by adding features such as: -### 5. Collaboration & Sharing: +- **State management**: Implement methods to manage the agent's internal state. +- **Communication protocols**: Define how the agent interacts with other agents in the swarm. +- **Learning capabilities**: Incorporate machine learning models or adaptive behaviors. +- **Specialized task handling**: Create methods for dealing with specific types of tasks or domains. -- **TeamSync**: Allows teams to collaborate on prompt optimization in real-time. -- **ShareSpace**: Share and access a community-driven repository of optimized prompts, fostering collective growth. +By leveraging these custom agent classes, developers can create highly specialized and adaptive agents tailored to their specific use cases while still benefiting from the standardized interface provided by the swarms framework. ---- +## 4. Integrating Third-Party Agent Libraries -## Benefits: +One of the key strengths of the swarms framework is its ability to integrate with various third-party agent libraries. In this section, we'll explore how to create wrappers for popular agent libraries, including Griptape, Langchain, CrewAI, and Autogen. -1. **Precision Engineering**: Harness the power of refined prompts, ensuring desired outcomes are achieved with surgical precision. -2. **Learning Hub**: Immerse in a tool that not only refines but educates, enhancing the user's prompting acumen. -3. **Versatile Mastery**: Navigate seamlessly across categories, ensuring top-tier prompt quality regardless of the domain. -4. **Community-driven Excellence**: Dive into a world of shared knowledge, elevating the collective expertise of the Swarms community. +### Griptape Integration ---- +Griptape is a powerful library for building AI agents with a focus on composability and tool use. Let's create a wrapper for a Griptape agent: -## Usage Workflow: +```python +from typing import List, Optional -1. **Launch the Prompt Optimizer**: Access the tool directly from the Swarms Multi-Agent Framework dashboard. -2. **Prompt Entry**: Input the initial prompt for refinement. -3. **Category Selection**: Pinpoint the desired category for specialized optimization. -4. **Receive & Review**: Engage with the tool's recommendations, comparing original and optimized prompts. -5. **Collaborate, Implement & Share**: Work in tandem with team members, deploy the refined prompt, and consider contributing to the community repository. +from griptape.structures import Agent as GriptapeAgent +from griptape.tools import FileManager, TaskMemoryClient, WebScraper ---- +from swarms import Agent -By integrating the Promptimizer Tool into their workflow, Swarms users stand poised to redefine the boundaries of what's possible, turning each prompt into a beacon of excellence and efficiency. +class GriptapeAgentWrapper(Agent): + """ + A wrapper class for the GriptapeAgent from the griptape library. + """ + def __init__(self, name: str, tools: Optional[List] = None, *args, **kwargs): + """ + Initialize the GriptapeAgentWrapper. --------------------------------------------------- + Parameters: + - name: The name of the agent. + - tools: A list of tools to be used by the agent. If not provided, default tools will be used. + - *args, **kwargs: Additional arguments to be passed to the parent class constructor. + """ + super().__init__(*args, **kwargs) + self.name = name + self.tools = tools or [ + WebScraper(off_prompt=True), + TaskMemoryClient(off_prompt=True), + FileManager() + ] + self.griptape_agent = GriptapeAgent( + input=f"I am {name}, an AI assistant. How can I help you?", + tools=self.tools + ) -# File: misc/features/shorthand.md + def run(self, task: str, *args, **kwargs) -> str: + """ + Run a task using the GriptapeAgent. -# Shorthand Communication System -## Swarms Multi-Agent Framework + Parameters: + - task: The task to be performed by the agent. -**The Enhanced Shorthand Communication System is designed to streamline agent-agent communication within the Swarms Multi-Agent Framework. This system employs concise alphanumeric notations to relay task-specific details to agents efficiently.** + Returns: + - The response from the GriptapeAgent as a string. + """ + response = self.griptape_agent.run(task, *args, **kwargs) + return str(response) ---- + def add_tool(self, tool) -> None: + """ + Add a tool to the agent. -## Format: + Parameters: + - tool: The tool to be added. + """ + self.tools.append(tool) + self.griptape_agent = GriptapeAgent( + input=f"I am {self.name}, an AI assistant. How can I help you?", + tools=self.tools + ) -The shorthand format is structured as `[AgentType]-[TaskLayer].[TaskNumber]-[Priority]-[Status]`. +# Usage example +griptape_wrapper = GriptapeAgentWrapper("GriptapeAssistant") +result = griptape_wrapper.run("Load https://example.com, summarize it, and store it in a file called example_summary.txt.") +print(result) ---- +``` -## Components: +This wrapper encapsulates the functionality of a Griptape agent while exposing it through the swarms framework's interface. It allows for easy customization of tools and provides a simple way to execute tasks using the Griptape agent. -### 1. Agent Type: -- Denotes the specific agent role, such as: - * `C`: Code agent - * `D`: Data processing agent - * `M`: Monitoring agent - * `N`: Network agent - * `R`: Resource management agent - * `I`: Interface agent - * `S`: Security agent +### Langchain Integration -### 2. Task Layer & Number: -- Represents the task's category. - * Example: `1.8` signifies Task layer 1, task number 8. +Langchain is a popular framework for developing applications powered by language models. Here's an example of how we can create a wrapper for a Langchain agent: -### 3. Priority: -- Indicates task urgency. - * `H`: High - * `M`: Medium - * `L`: Low +```python +from typing import List, Optional -### 4. Status: -- Gives a snapshot of the task's progress. - * `I`: Initialized - * `P`: In-progress - * `C`: Completed - * `F`: Failed - * `W`: Waiting +from langchain.agents import AgentExecutor, LLMSingleActionAgent, Tool +from langchain.chains import LLMChain +from langchain_community.llms import OpenAI +from langchain.prompts import StringPromptTemplate +from langchain.tools import DuckDuckGoSearchRun ---- +from swarms import Agent -## Extended Features: -### 1. Error Codes (for failures): -- `E01`: Resource issues -- `E02`: Data inconsistency -- `E03`: Dependency malfunction -... and more as needed. +class LangchainAgentWrapper(Agent): + """ + Initialize the LangchainAgentWrapper. -### 2. Collaboration Flag: -- `+`: Denotes required collaboration. + Args: + name (str): The name of the agent. + tools (List[Tool]): The list of tools available to the agent. + llm (Optional[OpenAI], optional): The OpenAI language model to use. Defaults to None. + """ + def __init__( + self, + name: str, + tools: List[Tool], + llm: Optional[OpenAI] = None, + *args, + **kwargs, + ): + super().__init__(*args, **kwargs) + self.name = name + self.tools = tools + self.llm = llm or OpenAI(temperature=0) ---- + prompt = StringPromptTemplate.from_template( + "You are {name}, an AI assistant. Answer the following question: {question}" + ) -## Example Codes: + llm_chain = LLMChain(llm=self.llm, prompt=prompt) + tool_names = [tool.name for tool in self.tools] -- `C-1.8-H-I`: A high-priority coding task that's initializing. -- `D-2.3-M-P`: A medium-priority data task currently in-progress. -- `M-3.5-L-P+`: A low-priority monitoring task in progress needing collaboration. + self.agent = LLMSingleActionAgent( + llm_chain=llm_chain, + output_parser=None, + stop=["\nObservation:"], + allowed_tools=tool_names, + ) ---- + self.agent_executor = AgentExecutor.from_agent_and_tools( + agent=self.agent, tools=self.tools, verbose=True + ) -By leveraging the Enhanced Shorthand Communication System, the Swarms Multi-Agent Framework can ensure swift interactions, concise communications, and effective task management. + def run(self, task: str, *args, **kwargs): + """ + Run the agent with the given task. + Args: + task (str): The task to be performed by the agent. + Returns: + Any: The result of the agent's execution. + """ + try: + return self.agent_executor.run(task) + except Exception as e: + print(f"An error occurred: {e}") --------------------------------------------------- -# File: swarms/agents/abstractagent.md +# Usage example -# swarms.agents +search_tool = DuckDuckGoSearchRun() +tools = [ + Tool( + name="Search", + func=search_tool.run, + description="Useful for searching the internet", + ) +] -## 1. Introduction +langchain_wrapper = LangchainAgentWrapper("LangchainAssistant", tools) +result = langchain_wrapper.run("What is the capital of France?") +print(result) +``` -`AbstractAgent` is an abstract class that serves as a foundation for implementing AI agents. An agent is an entity that can communicate with other agents and perform actions. The `AbstractAgent` class allows for customization in the implementation of the `receive` method, enabling different agents to define unique actions for receiving and processing messages. +This wrapper integrates a Langchain agent into the swarms framework, allowing for easy use of Langchain's powerful features such as tool use and multi-step reasoning. -`AbstractAgent` provides capabilities for managing tools and accessing memory, and has methods for running, chatting, and stepping through communication with other agents. +### CrewAI Integration -## 2. Class Definition +CrewAI is a library focused on creating and managing teams of AI agents. Let's create a wrapper for a CrewAI agent: ```python -class AbstractAgent: - """An abstract class for AI agent. +from swarms import Agent +from crewai import Agent as CrewAIAgent +from crewai import Task, Crew, Process - An agent can communicate with other agents and perform actions. - Different agents can differ in what actions they perform in the `receive` method. +class CrewAIAgentWrapper(Agent): + def __init__(self, name, role, goal, backstory, tools=None, *args, **kwargs): + super().__init__(*args, **kwargs) + self.name = name + self.crewai_agent = CrewAIAgent( + role=role, + goal=goal, + backstory=backstory, + verbose=True, + allow_delegation=False, + tools=tools or [] + ) - Agents are full and completed: + def run(self, task, *args, **kwargs): + crew_task = Task( + description=task, + agent=self.crewai_agent + ) + crew = Crew( + agents=[self.crewai_agent], + tasks=[crew_task], + process=Process.sequential + ) + result = crew.kickoff() + return result - Agents = llm + tools + memory - """ +# Usage example +from crewai_tools import SerperDevTool - def __init__(self, name: str): - """ - Args: - name (str): name of the agent. - """ - self._name = name +search_tool = SerperDevTool() - @property - def name(self): - """Get the name of the agent.""" - return self._name +crewai_wrapper = CrewAIAgentWrapper( + "ResearchAnalyst", + role='Senior Research Analyst', + goal='Uncover cutting-edge developments in AI and data science', + backstory="""You work at a leading tech think tank. + Your expertise lies in identifying emerging trends. + You have a knack for dissecting complex data and presenting actionable insights.""", + tools=[search_tool] +) - def tools(self, tools): - """init tools""" +result = crewai_wrapper.run("Analyze the latest trends in quantum computing and summarize the key findings.") +print(result) +``` - def memory(self, memory_store): - """init memory""" +This wrapper allows us to use CrewAI agents within the swarms framework, leveraging CrewAI's focus on role-based agents and collaborative task execution. - def reset(self): - """(Abstract method) Reset the agent.""" +### Autogen Integration - def run(self, task: str): - """Run the agent once""" +Autogen is a framework for building conversational AI agents. Here's how we can create a wrapper for an Autogen agent: - def _arun(self, taks: str): - """Run Async run""" +```python +from swarms import Agent +from autogen import ConversableAgent - def chat(self, messages: List[Dict]): - """Chat with the agent""" +class AutogenAgentWrapper(Agent): + def __init__(self, name, llm_config, *args, **kwargs): + super().__init__(*args, **kwargs) + self.name = name + self.autogen_agent = ConversableAgent( + name=name, + llm_config=llm_config, + code_execution_config=False, + function_map=None, + human_input_mode="NEVER" + ) - def _achat(self, messages: List[Dict]): - """Asynchronous Chat""" + def run(self, task, *args, **kwargs): + messages = [{"content": task, "role": "user"}] + response = self.autogen_agent.generate_reply(messages) + return response - def step(self, message: str): - """Step through the agent""" +# Usage example +import os - def _astep(self, message: str): - """Asynchronous step""" +llm_config = { + "config_list": [{"model": "gpt-4", "api_key": os.environ.get("OPENAI_API_KEY")}] +} + +autogen_wrapper = AutogenAgentWrapper("AutogenAssistant", llm_config) +result = autogen_wrapper.run("Tell me a joke about programming.") +print(result) ``` -## 3. Functionality and Usage +This wrapper integrates Autogen's ConversableAgent into the swarms framework, allowing for easy use of Autogen's conversational AI capabilities. -The `AbstractAgent` class represents a generic AI agent and provides a set of methods to interact with it. +By creating these wrappers, we can seamlessly integrate agents from various libraries into the swarms framework, allowing for a unified approach to agent management and task execution. -To create an instance of an agent, the `name` of the agent should be specified. +## 5. Advanced Agent Handling Techniques -### Core Methods +As you build more complex systems using the swarms framework and integrated agent libraries, you'll need to employ advanced techniques for agent handling. Here are some strategies to consider: -#### 1. `reset` +### 1. Dynamic Agent Creation -The `reset` method allows the agent to be reset to its initial state. +Implement a factory pattern to create agents dynamically based on task requirements: ```python -agent.reset() +class AgentFactory: + @staticmethod + def create_agent(agent_type, *args, **kwargs): + if agent_type == "griptape": + return GriptapeAgentWrapper(*args, **kwargs) + elif agent_type == "langchain": + return LangchainAgentWrapper(*args, **kwargs) + elif agent_type == "crewai": + return CrewAIAgentWrapper(*args, **kwargs) + elif agent_type == "autogen": + return AutogenAgentWrapper(*args, **kwargs) + else: + raise ValueError(f"Unknown agent type: {agent_type}") + +# Usage +agent = AgentFactory.create_agent("griptape", "DynamicGriptapeAgent") ``` -#### 2. `run` -The `run` method allows the agent to perform a specific task. +### 2. Agent Pooling + +Implement an agent pool to manage and reuse agents efficiently: ```python -agent.run("some_task") +from queue import Queue + +class AgentPool: + def __init__(self, pool_size=5): + self.pool = Queue(maxsize=pool_size) + self.pool_size = pool_size + + def get_agent(self, agent_type, *args, **kwargs): + if not self.pool.empty(): + return self.pool.get() + else: + return AgentFactory.create_agent(agent_type, *args, **kwargs) + + def release_agent(self, agent): + if self.pool.qsize() < self.pool_size: + self.pool.put(agent) + +# Usage +pool = AgentPool() +agent = pool.get_agent("langchain", "PooledLangchainAgent") +result = agent.run("Perform a task") +pool.release_agent(agent) ``` -#### 3. `chat` +### 3. Agent Composition -The `chat` method enables communication with the agent through a series of messages. +Create composite agents that combine the capabilities of multiple agent types: ```python -messages = [{"id": 1, "text": "Hello, agent!"}, {"id": 2, "text": "How are you?"}] -agent.chat(messages) +class CompositeAgent(Agent): + def __init__(self, name, agents): + super().__init__() + self.name = name + self.agents = agents + + def run(self, task): + results = [] + for agent in self.agents: + results.append(agent.run(task)) + return self.aggregate_results(results) + + def aggregate_results(self, results): + # Implement your own logic to combine results + return "\n".join(results) + +# Usage +griptape_agent = GriptapeAgentWrapper("GriptapeComponent") +langchain_agent = LangchainAgentWrapper("LangchainComponent", []) +composite_agent = CompositeAgent("CompositeAssistant", [griptape_agent, langchain_agent]) +result = composite_agent.run("Analyze the pros and cons of quantum computing") ``` -#### 4. `step` +### 4. Agent Specialization -The `step` method allows the agent to process a single message. +Create specialized agents for specific domains or tasks: ```python -agent.step("Hello, agent!") -``` +class DataAnalysisAgent(Agent): + def __init__(self, name, analysis_tools): + super().__init__() + self.name = name + self.analysis_tools = analysis_tools -### Asynchronous Methods + def run(self, data): + results = {} + for tool in self.analysis_tools: + results[tool.name] = tool.analyze(data) + return results -The class also provides asynchronous variants of the core methods. +# Usage +import pandas as pd +from sklearn.preprocessing import StandardScaler +from sklearn.decomposition import PCA -### Additional Functionality +class AnalysisTool: + def __init__(self, name, func): + self.name = name + self.func = func -Additional functionalities for agent initialization and management of tools and memory are also provided. + def analyze(self, data): + return self.func(data) -```python -agent.tools(some_tools) -agent.memory(some_memory_store) -``` +tools = [ + AnalysisTool("Descriptive Stats", lambda data: data.describe()), + AnalysisTool("Correlation", lambda data: data.corr()), + AnalysisTool("PCA", lambda data: PCA().fit_transform(StandardScaler().fit_transform(data))) +] -## 4. Additional Information and Tips +data_agent = DataAnalysisAgent("DataAnalyst", tools) +df = pd.read_csv("sample_data.csv") +analysis_results = data_agent.run(df) +``` -When implementing a new agent using the `AbstractAgent` class, ensure that the `receive` method is overridden to define the specific behavior of the agent upon receiving messages. +### 5. Agent Monitoring and Logging -## 5. References and Resources +Implement a monitoring system to track agent performance and log their activities: -For further exploration and understanding of AI agents and agent communication, refer to the relevant literature and research on this topic. +```python +import logging +from functools import wraps +def log_agent_activity(func): + @wraps(func) + def wrapper(self, *args, **kwargs): + logging.info(f"Agent {self.name} started task: {args[0]}") + result = func(self, *args, **kwargs) + logging.info(f"Agent {self.name} completed task. Result length: {len(str(result))}") + return result + return wrapper --------------------------------------------------- +class MonitoredAgent(Agent): + def __init__(self, name, *args, **kwargs): + super().__init__(*args, **kwargs) + self.name = name -# File: swarms/agents/agent_judge.md + @log_agent_activity + def run(self, task, *args, **kwargs): + return super().run(task, *args, **kwargs) -# Agent Judge +# Usage +logging.basicConfig(level=logging.INFO) +monitored_agent = MonitoredAgent("MonitoredGriptapeAgent") +result = monitored_agent.run("Summarize the latest AI research papers") +``` +Additionally the Agent class now includes built-in logging functionality and the ability to switch between JSON and string output. -The AgentJudge is a specialized agent designed to evaluate and judge outputs from other agents or systems. It acts as a quality control mechanism, providing objective assessments and feedback on various types of content, decisions, or outputs. +To switch between JSON and string output: +- Use `output_type="str"` for string output (default) +- Use `output_type="json"` for JSON output +The `output_type` parameter determines the format of the final result returned by the `run` method. When set to "str", it returns a string representation of the agent's response. When set to "json", it returns a JSON object containing detailed information about the agent's run, including all steps and metadata. -The AgentJudge serves as an impartial evaluator that can: -- Assess the quality and correctness of agent outputs +## 6. Best Practices for Custom Agent Development -- Provide structured feedback and scoring +When developing custom agents using the swarms framework, consider the following best practices: -- Maintain context across multiple evaluations +1. **Modular Design**: Design your agents with modularity in mind. Break down complex functionality into smaller, reusable components. -- Generate detailed analysis reports +2. **Consistent Interfaces**: Maintain consistent interfaces across your custom agents to ensure interoperability within the swarms framework. -## Architecture +3. **Error Handling**: Implement robust error handling and graceful degradation in your agents to ensure system stability. -```mermaid -graph TD - A[Input Tasks] --> B[AgentJudge] - B --> C[Agent Core] - C --> D[LLM Model] - D --> E[Response Generation] - E --> F[Context Management] - F --> G[Output] - - subgraph "Evaluation Flow" - H[Task Analysis] --> I[Quality Assessment] - I --> J[Feedback Generation] - J --> K[Score Assignment] - end - - B --> H - K --> G -``` +4. **Performance Optimization**: Optimize your agents for performance, especially when dealing with resource-intensive tasks or large-scale deployments. -## Parameters +5. **Testing and Validation**: Develop comprehensive test suites for your custom agents to ensure their reliability and correctness. -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `agent_name` | str | "agent-judge-01" | Unique identifier for the judge agent | -| `system_prompt` | str | AGENT_JUDGE_PROMPT | System instructions for the agent | -| `model_name` | str | "openai/o1" | LLM model to use for evaluation | -| `max_loops` | int | 1 | Maximum number of evaluation iterations | +6. **Documentation**: Provide clear and detailed documentation for your custom agents, including their capabilities, limitations, and usage examples. -## Methods +7. **Versioning**: Implement proper versioning for your custom agents to manage updates and maintain backwards compatibility. -| Method | Description | Parameters | Returns | -|--------|-------------|------------|---------| -| `step()` | Processes a single batch of tasks | `tasks: List[str]` | `str` | -| `run()` | Executes multiple evaluation iterations | `tasks: List[str]` | `List[str]` | +8. **Security Considerations**: Implement security best practices, especially when dealing with sensitive data or integrating with external services. -## Code Example +Here's an example that incorporates some of these best practices: ```python -from swarms import AgentJudge +import logging +from typing import Dict, Any +from swarms import Agent +class SecureCustomAgent(Agent): + def __init__(self, name: str, api_key: str, version: str = "1.0.0", *args, **kwargs): + super().__init__(*args, **kwargs) + self.name = name + self._api_key = api_key # Store sensitive data securely + self.version = version + self.logger = logging.getLogger(f"{self.__class__.__name__}.{self.name}") -judge = AgentJudge(model_name="gpt-4o", max_loops=1) + def run(self, task: str, *args, **kwargs) -> Dict[str, Any]: + try: + self.logger.info(f"Agent {self.name} (v{self.version}) starting task: {task}") + result = self._process_task(task) + self.logger.info(f"Agent {self.name} completed task successfully") + return {"status": "success", "result": result} + except Exception as e: + self.logger.error(f"Error in agent {self.name}: {str(e)}") + return {"status": "error", "message": str(e)} + def _process_task(self, task: str) -> str: + # Implement the core logic of your agent here + # This is a placeholder implementation + return f"Processed task: {task}" -outputs = [ - "1. Agent CalculusMaster: After careful evaluation, I have computed the integral of the polynomial function. The result is ∫(x^2 + 3x + 2)dx = (1/3)x^3 + (3/2)x^2 + 5, where I applied the power rule for integration and added the constant of integration.", - "2. Agent DerivativeDynamo: In my analysis of the function sin(x), I have derived it with respect to x. The derivative is d/dx (sin(x)) = cos(x). However, I must note that the additional term '+ 2' is not applicable in this context as it does not pertain to the derivative of sin(x).", - "3. Agent LimitWizard: Upon evaluating the limit as x approaches 0 for the function (sin(x)/x), I conclude that lim (x -> 0) (sin(x)/x) = 1. The additional '+ 3' is incorrect and should be disregarded as it does not relate to the limit calculation.", - "4. Agent IntegralGenius: I have computed the integral of the exponential function e^x. The result is ∫(e^x)dx = e^x + C, where C is the constant of integration. The extra '+ 1' is unnecessary and does not belong in the final expression.", - "5. Agent FunctionFreak: Analyzing the cubic function f(x) = x^3 - 3x + 2, I determined that it has a maximum at x = 1. However, the additional '+ 2' is misleading and should not be included in the maximum value statement.", -] + @property + def api_key(self) -> str: + # Provide a secure way to access the API key + return self._api_key -print(judge.run(outputs)) + def __repr__(self) -> str: + return f"<{self.__class__.__name__} name='{self.name}' version='{self.version}'>" +# Usage +logging.basicConfig(level=logging.INFO) +secure_agent = SecureCustomAgent("SecureAgent", api_key="your-api-key-here") +result = secure_agent.run("Perform a secure operation") +print(result) ``` -## Enterprise Applications +This example demonstrates several best practices: +- Modular design with separate methods for initialization and task processing +- Consistent interface adhering to the swarms framework +- Error handling and logging +- Secure storage of sensitive data (API key) +- Version tracking +- Type hinting for improved code readability and maintainability +- Informative string representation of the agent -1. **Code Review Automation** - - Evaluate code quality +## 7. Future Directions and Challenges - - Check for best practices - - - Assess documentation completeness +As the field of AI and agent-based systems continues to evolve, the swarms framework and its ecosystem of integrated agent libraries will face new opportunities and challenges. Some potential future directions and areas of focus include: -2. **Content Quality Control** - - - Review marketing copy - - - Validate technical documentation - - - Assess user support responses +1. **Enhanced Interoperability**: Developing more sophisticated protocols for agent communication and collaboration across different libraries and frameworks. -3. **Decision Validation** - - Evaluate business decisions - - - Assess risk assessments - - - Review compliance reports +2. **Scalability**: Improving the framework's ability to handle large-scale swarms of agents, potentially leveraging distributed computing techniques. -4. **Performance Assessment** - - - Evaluate agent performance - - - Assess system outputs - - - Review automated processes +3. **Adaptive Learning**: Incorporating more advanced machine learning techniques to allow agents to adapt and improve their performance over time. -## Best Practices +4. **Ethical AI**: Integrating ethical considerations and safeguards into the agent development process to ensure responsible AI deployment. -1. **Task Formulation** - - Provide clear, specific evaluation criteria - - - Include context when necessary +5. **Human-AI Collaboration**: Exploring new paradigms for human-AI interaction and collaboration within the swarms framework. - - Structure tasks for consistent evaluation +6. **Domain-Specific Optimizations**: Developing specialized agent types and tools for specific industries or problem domains. -2. **System Configuration** - - - Use appropriate model for task complexity - - - Adjust max_loops based on evaluation depth needed - - - Customize system prompt for specific use cases +7. **Explainability and Transparency**: Improving the ability to understand and explain agent decision-making processes. -3. **Output Management** - - - Store evaluation results systematically - - - Track evaluation patterns over time - - - Use results for continuous improvement +8. **Security and Privacy**: Enhancing the framework's security features to protect against potential vulnerabilities and ensure data privacy. -4. **Integration Tips** - - Implement as part of CI/CD pipelines +As these areas develop, developers working with the swarms framework will need to stay informed about new advancements and be prepared to adapt their agent implementations accordingly. - - Use for automated quality gates - - - Integrate with monitoring systems +## 8. Conclusion -## Use Cases +The swarms framework provides a powerful and flexible foundation for building custom agents and integrating various agent libraries. By leveraging the techniques and best practices discussed in this guide, developers can create sophisticated, efficient, and scalable agent-based systems. -```mermaid -graph LR - A[AgentJudge] --> B[Code Review] - A --> C[Content QA] - A --> D[Decision Validation] - A --> E[Performance Metrics] - - B --> F[Quality Gates] - C --> G[Compliance] - D --> H[Risk Assessment] - E --> I[System Optimization] -``` +The ability to seamlessly integrate agents from libraries like Griptape, Langchain, CrewAI, and Autogen opens up a world of possibilities for creating diverse and specialized AI applications. Whether you're building a complex multi-agent system for data analysis, a conversational AI platform, or a collaborative problem-solving environment, the swarms framework offers the tools and flexibility to bring your vision to life. -## Tips for Implementation +As you embark on your journey with the swarms framework, remember that the field of AI and agent-based systems is rapidly evolving. Stay curious, keep experimenting, and don't hesitate to push the boundaries of what's possible with custom agents and integrated libraries. -1. Start with simple evaluation tasks and gradually increase complexity +By embracing the power of the swarms framework and the ecosystem of agent libraries it supports, you're well-positioned to create the next generation of intelligent, adaptive, and collaborative AI systems. Happy agent building! -2. Maintain consistent evaluation criteria across similar tasks -3. Use the context management feature for multi-step evaluations +-------------------------------------------------- -4. Implement proper error handling and logging +# File: swarms\agents\tool_agent.md -5. Regular calibration of evaluation criteria +# ToolAgent Documentation +The `ToolAgent` class is a specialized agent that facilitates the execution of specific tasks using a model and tokenizer. It is part of the `swarms` module and inherits from the `Agent` class. This agent is designed to generate functions based on a given JSON schema and task, making it highly adaptable for various use cases, including natural language processing and data generation. --------------------------------------------------- +The `ToolAgent` class plays a crucial role in leveraging pre-trained models and tokenizers to automate tasks that require the interpretation and generation of structured data. By providing a flexible interface and robust error handling, it ensures smooth integration and efficient task execution. -# File: swarms/agents/consistency_agent.md +### Parameters -# Consistency Agent Documentation +| Parameter | Type | Description | +|--------------------|-----------------------------------|---------------------------------------------------------------------------------| +| `name` | `str` | The name of the tool agent. Default is "Function Calling Agent". | +| `description` | `str` | A description of the tool agent. Default is "Generates a function based on the input json schema and the task". | +| `model` | `Any` | The model used by the tool agent. | +| `tokenizer` | `Any` | The tokenizer used by the tool agent. | +| `json_schema` | `Any` | The JSON schema used by the tool agent. | +| `max_number_tokens`| `int` | The maximum number of tokens for generation. Default is 500. | +| `parsing_function` | `Optional[Callable]` | An optional parsing function to process the output of the tool agent. | +| `llm` | `Any` | An optional large language model to be used by the tool agent. | +| `*args` | Variable length argument list | Additional positional arguments. | +| `**kwargs` | Arbitrary keyword arguments | Additional keyword arguments. | +### Attributes -The `SelfConsistencyAgent` is a specialized agent designed for generating multiple independent responses to a given task and aggregating them into a single, consistent final answer. It leverages concurrent processing to enhance efficiency and employs a majority voting mechanism to ensure the reliability of the aggregated response. +| Attribute | Type | Description | +|--------------------|-------|----------------------------------------------| +| `name` | `str` | The name of the tool agent. | +| `description` | `str` | A description of the tool agent. | +| `model` | `Any` | The model used by the tool agent. | +| `tokenizer` | `Any` | The tokenizer used by the tool agent. | +| `json_schema` | `Any` | The JSON schema used by the tool agent. | -## Purpose +### Methods -The primary objective of the `SelfConsistencyAgent` is to provide a robust mechanism for decision-making and problem-solving by generating diverse responses and synthesizing them into a coherent final answer. This approach is particularly useful in scenarios where consistency and reliability are critical. +#### `run` -## Class: `SelfConsistencyAgent` +```python +def run(self, task: str, *args, **kwargs) -> Any: +``` -### Initialization +**Parameters:** -- **`__init__`**: Initializes the `SelfConsistencyAgent` with specified parameters. +| Parameter | Type | Description | +|------------|---------------------------|------------------------------------------------------------------| +| `task` | `str` | The task to be performed by the tool agent. | +| `*args` | Variable length argument list | Additional positional arguments. | +| `**kwargs` | Arbitrary keyword arguments | Additional keyword arguments. | -#### Arguments +**Returns:** -| Argument | Type | Default | Description | -|------------------------|---------|---------|-----------------------------------------------------------------------------| -| `num_samples` | `int` | `5` | Number of independent responses to sample. | -| `return_list` | `bool` | `False` | Whether to return the conversation as a list. | -| `max_loops` | `int` | `1` | Maximum number of loops for the agent to run. | -| `return_dict` | `bool` | `False` | Whether to return the conversation as a dictionary. | -| `return_json` | `bool` | `False` | Whether to return the conversation as JSON. | -| `majority_voting_prompt` | `str` | `None` | Custom prompt for majority voting. | +- The output of the tool agent. -### Methods +**Raises:** -- **`run`**: Generates multiple responses for the given task and aggregates them. - - **Arguments**: - - `task` (`str`): The input prompt. - - `answer` (`str`, optional): The expected answer to validate responses against. - - **Returns**: `str` - The aggregated final answer. +- `Exception`: If an error occurs during the execution of the tool agent. -- **`aggregate`**: Aggregates a list of responses into a single final answer using majority voting. - - **Arguments**: - - `responses` (`List[str]`): The list of responses. - - **Returns**: `str` - The aggregated answer. +## Functionality and Usage -- **`check_responses_for_answer`**: Checks if a specified answer is present in any of the provided responses. - - **Arguments**: - - `responses` (`List[str]`): A list of responses to check. - - `answer` (`str`): The answer to look for in the responses. - - **Returns**: `bool` - `True` if the answer is found, `False` otherwise. +The `ToolAgent` class provides a structured way to perform tasks using a model and tokenizer. It initializes with essential parameters and attributes, and the `run` method facilitates the execution of the specified task. -### Examples +### Initialization -#### Example 1: Basic Usage +The initialization of a `ToolAgent` involves specifying its name, description, model, tokenizer, JSON schema, maximum number of tokens, optional parsing function, and optional large language model. ```python -from swarms.agents.consistency_agent import SelfConsistencyAgent - -# Initialize the agent -agent = SelfConsistencyAgent( - agent_name="Reasoning-Agent", - model_name="gpt-4o-mini", - max_loops=1, - num_samples=5 +agent = ToolAgent( + name="My Tool Agent", + description="A tool agent for specific tasks", + model=model, + tokenizer=tokenizer, + json_schema=json_schema, + max_number_tokens=1000, + parsing_function=my_parsing_function, + llm=my_llm ) +``` -# Define a task -task = "What is the 40th prime number?" +### Running a Task -# Run the agent -final_answer = agent.run(task) +To execute a task using the `ToolAgent`, the `run` method is called with the task description and any additional arguments or keyword arguments. -# Print the final aggregated answer -print("Final aggregated answer:", final_answer) +```python +result = agent.run("Generate a person's information based on the given schema.") +print(result) ``` -#### Example 2: Using Custom Majority Voting Prompt +### Detailed Examples + +#### Example 1: Basic Usage ```python -from swarms.agents.consistency_agent import SelfConsistencyAgent +from transformers import AutoModelForCausalLM, AutoTokenizer +from swarms import ToolAgent -# Initialize the agent with a custom majority voting prompt -agent = SelfConsistencyAgent( - agent_name="Reasoning-Agent", - model_name="gpt-4o-mini", - max_loops=1, - num_samples=5, - majority_voting_prompt="Please provide the most common response." -) +model = AutoModelForCausalLM.from_pretrained("databricks/dolly-v2-12b") +tokenizer = AutoTokenizer.from_pretrained("databricks/dolly-v2-12b") -# Define a task -task = "Explain the theory of relativity in simple terms." +json_schema = { + "type": "object", + "properties": { + "name": {"type": "string"}, + "age": {"type": "number"}, + "is_student": {"type": "boolean"}, + "courses": { + "type": "array", + "items": {"type": "string"} + } + } +} -# Run the agent -final_answer = agent.run(task) +task = "Generate a person's information based on the following schema:" +agent = ToolAgent(model=model, tokenizer=tokenizer, json_schema=json_schema) +generated_data = agent.run(task) -# Print the final aggregated answer -print("Final aggregated answer:", final_answer) +print(generated_data) ``` ---- +#### Example 2: Using a Parsing Function +```python +def parse_output(output): + # Custom parsing logic + return output --------------------------------------------------- +agent = ToolAgent( + name="Parsed Tool Agent", + description="A tool agent with a parsing function", + model=model, + tokenizer=tokenizer, + json_schema=json_schema, + parsing_function=parse_output +) -# File: swarms/agents/create_agents_yaml.md +task = "Generate a person's information with custom parsing:" +parsed_data = agent.run(task) -# Building Agents from a YAML File +print(parsed_data) +``` -The `create_agents_from_yaml` function is designed to dynamically create agents and orchestrate swarms based on configurations defined in a YAML file. It is particularly suited for enterprise use-cases, offering scalability and reliability for agent-based workflows. +#### Example 3: Specifying Maximum Number of Tokens -### Key Features: -- **Multi-Agent Creation**: Automatically instantiate multiple agents from a YAML file. -- **Swarm Architecture**: Supports swarm architectures where agents collaborate to solve complex tasks. -- **Logging with Loguru**: Includes robust logging for tracking operations and diagnosing issues. -- **Flexible Return Types**: Offers several return types based on the requirements of the system. -- **Customizable**: Supports additional arguments (`*args` and `**kwargs`) for fine-tuning agent behavior. -- **Error Handling**: Handles missing configurations and invalid inputs with meaningful error messages. +```python +agent = ToolAgent( + name="Token Limited Tool Agent", + description="A tool agent with a token limit", + model=model, + tokenizer=tokenizer, + json_schema=json_schema, + max_number_tokens=200 +) ---- +task = "Generate a concise person's information:" +limited_data = agent.run(task) -### Parameters +print(limited_data) +``` -| Parameter | Description | Type | Default Value | Example | -|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------|-------------|---------------|-------------------------------------| -| `model` | A callable representing the model (LLM or other) that agents will use. | Callable | None | `OpenAIChat(model_name="gpt-4")` | -| `yaml_file` | Path to the YAML file containing agent configurations. | String | "agents.yaml" | `"config/agents.yaml"` | -| `return_type`| Determines the type of return object. Options: `"auto"`, `"swarm"`, `"agents"`, `"both"`, `"tasks"`, `"run_swarm"`. | String | "auto" | `"both"` | -| `*args` | Additional positional arguments for further customization (e.g., agent behavior). | List | N/A | N/A | -| `**kwargs` | Additional keyword arguments for customization (e.g., specific parameters passed to the agents or swarm). | Dict | N/A | N/A | ---- +## Full Usage +```python -### Return Types +from pydantic import BaseModel, Field +from transformers import AutoModelForCausalLM, AutoTokenizer -| Return Type | Description | -|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------| -| `SwarmRouter` | Returns a `SwarmRouter` object, orchestrating the created agents, only if swarm architecture is defined in YAML. | -| `Agent` | Returns a single agent if only one is defined. | -| `List[Agent]` | Returns a list of agents if multiple are defined. | -| `Tuple` | If both agents and a swarm are present, returns both as a tuple (`SwarmRouter, List[Agent]`). | -| `List[Dict]` | Returns a list of task results if tasks were executed. | -| `None` | Returns nothing if an invalid return type is provided or an error occurs. | +from swarms import ToolAgent +from swarms.tools.json_utils import base_model_to_json ---- +# Model name +model_name = "CohereForAI/c4ai-command-r-v01-4bit" -### Detailed Return Types +# Load the pre-trained model and tokenizer +model = AutoModelForCausalLM.from_pretrained( + model_name, + device_map="auto", +) -| Return Type | Condition | Example Return Value | -|--------------------|---------------------------------------------------------------------|-----------------------------------------------| -| `"auto"` | Automatically determines the return based on YAML content. | `SwarmRouter` if swarm architecture is defined, otherwise `Agent` or `List[Agent]`. | -| `"swarm"` | Returns `SwarmRouter` if present; otherwise returns agents. | `` | -| `"agents"` | Returns a list of agents (or a single agent if only one is defined).| `[, ]` or `` | -| `"both"` | Returns both `SwarmRouter` and agents in a tuple. | `(, [, ])` | -| `"tasks"` | Returns the task results, if tasks were executed by agents. | `[{'task': 'task_output'}, {'task2': 'output'}]` | -| `"run_swarm"` | Executes the swarm (if defined) and returns the result. | `'Swarm task output here'` | +# Load the pre-trained model and tokenizer +tokenizer = AutoTokenizer.from_pretrained(model_name) ---- -### Example Use Cases +# Initialize the schema for the person's information +class APIExampleRequestSchema(BaseModel): + endpoint: str = Field( + ..., description="The API endpoint for the example request" + ) + method: str = Field( + ..., description="The HTTP method for the example request" + ) + headers: dict = Field( + ..., description="The headers for the example request" + ) + body: dict = Field(..., description="The body of the example request") + response: dict = Field( + ..., + description="The expected response of the example request", + ) -1. **Creating Multiple Agents for Financial Analysis** -```yaml -agents: - - agent_name: "Financial-Analysis-Agent" - system_prompt: "Analyze the best investment strategy for 2024." - max_loops: 1 - autosave: true - verbose: false - context_length: 100000 - output_type: "str" - task: "Analyze stock options for long-term gains." +# Convert the schema to a JSON string +api_example_schema = base_model_to_json(APIExampleRequestSchema) +# Convert the schema to a JSON string - - agent_name: "Risk-Analysis-Agent" - system_prompt: "Evaluate the risk of tech stocks in 2024." - max_loops: 2 - autosave: false - verbose: true - context_length: 50000 - output_type: "json" - task: "What are the riskiest stocks in the tech sector?" -``` +# Define the task to generate a person's information +task = "Generate an example API request using this code:\n" -```python -from swarms.structs.agent import Agent -from swarms.structs.swarm_router import SwarmRouter +# Create an instance of the ToolAgent class +agent = ToolAgent( + name="Command R Tool Agent", + description=( + "An agent that generates an API request using the Command R" + " model." + ), + model=model, + tokenizer=tokenizer, + json_schema=api_example_schema, +) -# Model representing your LLM -def model(prompt): - return f"Processed: {prompt}" +# Run the agent to generate the person's information +generated_data = agent.run(task) -# Create agents and return them as a list -agents = create_agents_from_yaml(model=model, yaml_file="agents.yaml", return_type="agents") -print(agents) -``` +# Print the generated data +print(f"Generated data: {generated_data}") -2. **Running a Swarm of Agents to Solve a Complex Task** -```yaml -agents: - - agent_name: "Legal-Agent" - system_prompt: "Provide legal advice on corporate structuring." - task: "How to incorporate a business as an LLC?" -swarm_architecture: - name: "Corporate-Swarm" - description: "A swarm for helping businesses with legal and tax advice." - swarm_type: "ConcurrentWorkflow" - task: "How can we optimize a business structure for maximum tax efficiency?" - max_loops: 3 ``` + +## Jamba ++ ToolAgent ```python -import os +from pydantic import BaseModel, Field +from transformers import AutoModelForCausalLM, AutoTokenizer -from dotenv import load_dotenv -from loguru import logger -from swarm_models import OpenAIChat +from swarms import ToolAgent +from swarms.tools.json_utils import base_model_to_json -from swarms.agents.create_agents_from_yaml import ( - create_agents_from_yaml, -) +# Model name +model_name = "ai21labs/Jamba-v0.1" -# Load environment variables -load_dotenv() +# Load the pre-trained model and tokenizer +model = AutoModelForCausalLM.from_pretrained( + model_name, + device_map="auto", +) -# Path to your YAML file -yaml_file = "agents_multi_agent.yaml" +# Load the pre-trained model and tokenizer +tokenizer = AutoTokenizer.from_pretrained(model_name) -# Get the OpenAI API key from the environment variable -api_key = os.getenv("GROQ_API_KEY") +# Initialize the schema for the person's information +class APIExampleRequestSchema(BaseModel): + endpoint: str = Field( + ..., description="The API endpoint for the example request" + ) + method: str = Field( + ..., description="The HTTP method for the example request" + ) + headers: dict = Field( + ..., description="The headers for the example request" + ) + body: dict = Field(..., description="The body of the example request") + response: dict = Field( + ..., + description="The expected response of the example request", + ) -# Model -model = OpenAIChat( - openai_api_base="https://api.groq.com/openai/v1", - openai_api_key=api_key, - model_name="llama-3.1-70b-versatile", - temperature=0.1, -) -try: - # Create agents and run tasks (using 'both' to return agents and task results) - task_results = create_agents_from_yaml( - model=model, yaml_file=yaml_file, return_type="run_swarm" - ) +# Convert the schema to a JSON string +api_example_schema = base_model_to_json(APIExampleRequestSchema) +# Convert the schema to a JSON string - logger.info(f"Results from agents: {task_results}") -except Exception as e: - logger.error(f"An error occurred: {e}") +# Define the task to generate a person's information +task = "Generate an example API request using this code:\n" -``` +# Create an instance of the ToolAgent class +agent = ToolAgent( + name="Command R Tool Agent", + description=( + "An agent that generates an API request using the Command R" + " model." + ), + model=model, + tokenizer=tokenizer, + json_schema=api_example_schema, +) -3. **Returning Both Agents and Tasks** +# Run the agent to generate the person's information +generated_data = agent(task) -```yaml -agents: - - agent_name: "Market-Research-Agent" - system_prompt: "What are the latest trends in AI?" - task: "Provide a market analysis for AI technologies in 2024." +# Print the generated data +print(f"Generated data: {generated_data}") ``` -```python -from swarms.structs.agent import Agent - -# Model representing your LLM -def model(prompt): - return f"Processed: {prompt}" +## Additional Information and Tips -# Create agents and run tasks, return both agents and task results -swarm, agents = create_agents_from_yaml(model=model, yaml_file="agents.yaml", return_type="both") -print(swarm, agents) -``` +- Ensure that either the `model` or `llm` parameter is provided during initialization. If neither is provided, the `ToolAgent` will raise an exception. +- The `parsing_function` parameter is optional but can be very useful for post-processing the output of the tool agent. +- Adjust the `max_number_tokens` parameter to control the length of the generated output, depending on the requirements of the task. ---- +## References and Resources +- [Transformers Documentation](https://huggingface.co/transformers/) +- [Loguru Logger](https://loguru.readthedocs.io/en/stable/) +This documentation provides a comprehensive guide to the `ToolAgent` class, including its initialization, usage, and practical examples. By following the detailed instructions and examples, developers can effectively utilize the `ToolAgent` for various tasks involving model and tokenizer-based operations. ---- +-------------------------------------------------- -### YAML Schema Overview: +# File: swarms\artifacts\artifact.md -Below is a breakdown of the attributes expected in the YAML configuration file, which governs how agents and swarms are created. +# `Artifact` -### YAML Attributes Table: +The `Artifact` class represents a file artifact, encapsulating the file's path, type, contents, versions, and edit count. This class provides a comprehensive way to manage file versions, edit contents, and handle various file-related operations such as saving, loading, and exporting to JSON. -| Attribute Name | Description | Type | Required | Default/Example Value | -|-----------------------------------|------------------------------------------------------------|---------------|----------|------------------------------------------| -| `agents` | List of agents to be created. Each agent must have specific configurations. | List of dicts | Yes | | -| `agent_name` | The name of the agent. | String | Yes | `"Stock-Analysis-Agent"` | -| `system_prompt` | The system prompt that the agent will use. | String | Yes | `"Your full system prompt here"` | -| `max_loops` | Maximum number of iterations or loops for the agent. | Integer | No | 1 | -| `autosave` | Whether the agent should automatically save its state. | Boolean | No | `true` | -| `dashboard` | Whether to enable a dashboard for the agent. | Boolean | No | `false` | -| `verbose` | Whether to run the agent in verbose mode (for debugging). | Boolean | No | `false` | -| `dynamic_temperature_enabled` | Enable dynamic temperature adjustments during agent execution. | Boolean | No | `false` | -| `saved_state_path` | Path where the agent's state is saved for recovery. | String | No | `"path_to_save_state.json"` | -| `user_name` | Name of the user interacting with the agent. | String | No | `"default_user"` | -| `retry_attempts` | Number of times to retry an operation in case of failure. | Integer | No | 1 | -| `context_length` | Maximum context length for agent interactions. | Integer | No | 100000 | -| `return_step_meta` | Whether to return metadata for each step of the task. | Boolean | No | `false` | -| `output_type` | The type of output the agent will return (e.g., `str`, `json`). | String | No | `"str"` | -| `task` | Task to be executed by the agent (optional). | String | No | `"What is the best strategy for long-term stock investment?"` | +The `Artifact` class is particularly useful in contexts where file version control and content management are essential. By keeping track of the number of edits and maintaining a version history, it allows for robust file handling and auditability. -#### Swarm Architecture (Optional): +## Class Definition -| Attribute Name | Description | Type | Required | Default/Example Value | -|-----------------------------------|------------------------------------------------------------|---------------|----------|------------------------------------------| -| `swarm_architecture` | Defines the swarm configuration. For more information on what can be added to the swarm architecture, please refer to the [Swarm Router documentation](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/). | Dict | No | | -| `name` | The name of the swarm. | String | Yes | `"MySwarm"` | -| `description` | Description of the swarm and its purpose. | String | No | `"A swarm for collaborative task solving"`| -| `max_loops` | Maximum number of loops for the swarm. | Integer | No | 5 | -| `swarm_type` | The type of swarm (e.g., `ConcurrentWorkflow`) `SequentialWorkflow`. | String | Yes | `"ConcurrentWorkflow"` | -| `task` | The primary task assigned to the swarm. | String | No | `"How can we trademark concepts as a delaware C CORP for free?"` | +### Artifact ---- -### YAML Schema Example: -Below is an updated YAML schema that conforms to the function's expectations: +| Attribute | Type | Default Value | Description | +|-------------|---------------------|------------------|--------------------------------------------------| +| `file_path` | `str` | N/A | The path to the file. | +| `file_type` | `str` | N/A | The type of the file. | +| `contents` | `str` | `""` | The contents of the file. | +| `versions` | `List[FileVersion]` | `[]` | The list of file versions. | +| `edit_count`| `int` | `0` | The number of times the file has been edited. | -```yaml -agents: - - agent_name: "Financial-Analysis-Agent" - system_prompt: "Your full system prompt here" - max_loops: 1 - autosave: true - dashboard: false - verbose: true - dynamic_temperature_enabled: true - saved_state_path: "finance_agent.json" - user_name: "swarms_corp" - retry_attempts: 1 - context_length: 200000 - return_step_meta: false - output_type: "str" - # task: "How can I establish a ROTH IRA to buy stocks and get a tax break?" # Turn off if using swarm +### Parameters and Validation - - agent_name: "Stock-Analysis-Agent" - system_prompt: "Your full system prompt here" - max_loops: 2 - autosave: true - dashboard: false - verbose: true - dynamic_temperature_enabled: false - saved_state_path: "stock_agent.json" - user_name: "stock_user" - retry_attempts: 3 - context_length: 150000 - return_step_meta: true - output_type: "json" - # task: "What is the best strategy for long-term stock investment?" +- `file_path`: A string representing the file path. +- `file_type`: A string representing the file type. This attribute is validated to ensure it matches supported file types based on the file extension if not provided. +- `contents`: A string representing the contents of the file. Defaults to an empty string. +- `versions`: A list of `FileVersion` instances representing the version history of the file. Defaults to an empty list. +- `edit_count`: An integer representing the number of edits made to the file. Defaults to 0. -# Optional Swarm Configuration -swarm_architecture: - name: "MySwarm" - description: "A swarm for collaborative task solving" - max_loops: 5 - swarm_type: "ConcurrentWorkflow" - task: "How can we trademark concepts as a delaware C CORP for free?" # Main task -``` +### Methods -# Diagram -```mermaid -graph TD; - A[Task] -->|Send to| B[Financial-Analysis-Agent] - A -->|Send to| C[Stock-Analysis-Agent] -``` +The `Artifact` class includes various methods for creating, editing, saving, loading, and exporting file artifacts. ---- +#### `create` -### How to Use `create_agents_from_yaml` Function with YAML: +| Parameter | Type | Description | +|--------------------|--------|----------------------------------------| +| `initial_content` | `str` | The initial content of the file. | -- You need to plug in your specific model until we can create a model router that can fetch any model and set specific settings +**Usage Example:** -#### Example Code: ```python -import os +artifact = Artifact(file_path="example.txt", file_type="txt") +artifact.create(initial_content="Initial file content") +``` +The file type parameter supports the following file types: `.txt`, `.md`, `.py`, `.pdf`. +#### `edit` -from dotenv import load_dotenv -from loguru import logger -from swarm_models import OpenAIChat -from swarms.agents.create_agents_from_yaml import ( - create_agents_from_yaml, -) +| Parameter | Type | Description | +|---------------|--------|----------------------------------------| +| `new_content` | `str` | The new content of the file. | -# Load environment variables -load_dotenv() +**Usage Example:** -# Path to your YAML file -yaml_file = "agents.yaml" +```python +artifact.edit(new_content="Updated file content") +``` +#### `save` -# Get the OpenAI API key from the environment variable -api_key = os.getenv("GROQ_API_KEY") +**Usage Example:** -# Model -model = OpenAIChat( - openai_api_base="https://api.groq.com/openai/v1", - openai_api_key=api_key, - model_name="llama-3.1-70b-versatile", - temperature=0.1, -) +```python +artifact.save() +``` -try: - # Create agents and run tasks (using 'both' to return agents and task results) - task_results = create_agents_from_yaml( - model=model, yaml_file=yaml_file, return_type="run_swarm" # - ) +#### `load` - logger.info(f"Results from agents: {task_results}") -except Exception as e: - logger.error(f"An error occurred: {e}") +**Usage Example:** +```python +artifact.load() ``` ---- +#### `get_version` -### Error Handling: -1. **FileNotFoundError**: If the specified YAML file does not exist. -2. **ValueError**: Raised if there are invalid or missing configurations in the YAML file. -3. **Invalid Return Type**: If an invalid return type is specified, the function will raise a `ValueError`. +| Parameter | Type | Description | +|-------------------|-------|-----------------------------------------| +| `version_number` | `int` | The version number to retrieve. | -### Conclusion: -The `create_agents_from_yaml` function provides a flexible and powerful way to dynamically configure and execute agents, supporting a wide range of tasks and configurations for enterprise-level use cases. By following the YAML schema and function signature, users can easily define and manage their agents and swarms. +**Usage Example:** --------------------------------------------------- +```python +version = artifact.get_version(version_number=1) +``` -# File: swarms/agents/external_party_agents.md +#### `get_contents` +**Usage Example:** +```python +current_contents = artifact.get_contents() +``` -# **Swarms External Agent Integration** +#### `get_version_history` -Integrating external agents from other frameworks like **Langchain**, **Griptape**, and more is straightforward using **Swarms**. Below are step-by-step guides on how to bring these agents into Swarms by creating a new class, implementing the required methods, and ensuring compatibility. ---- +**Usage Example:** -## **Quick Overview** +```python +version_history = artifact.get_version_history() +``` -- **Step 1**: Create a new class that inherits the `Agent` class from Swarms. -- **Step 2**: Override the `.run(task: str) -> str` method that will execute the agent and return a string response. -- **Step 3**: Optionally, add methods to save outputs to other formats like JSON, logs, or databases. +#### `export_to_json` -### **Agent Class** -The primary structure you'll need to integrate any external agent is the `Agent` class from **Swarms**. Here’s a template for how your new agent class should be structured: +| Parameter | Type | Description | +|-------------|-------|----------------------------------------------| +| `file_path` | `str` | The path to the JSON file to save the artifact.| + +**Usage Example:** ```python -from swarms import Agent +artifact.export_to_json(file_path="artifact.json") +``` -class ExternalAgent(Agent): - def run(self, task: str) -> str: - # Implement logic to run external agent - pass +#### `import_from_json` - def save_to_json(self, output: str, filepath: str): - # Optionally save the result to a JSON file - with open(filepath, "w") as file: - json.dump({"response": output}, file) -``` ---- +| Parameter | Type | Description | +|-------------|-------|--------------------------------------------------| +| `file_path` | `str` | The path to the JSON file to import the artifact from.| -## **Griptape Agent Integration Example** +**Usage Example:** -In this example, we will create a **Griptape** agent by inheriting from the Swarms `Agent` class and implementing the `run` method. +```python +imported_artifact = Artifact.import_from_json(file_path="artifact.json") +``` -### **Griptape Integration Steps**: +#### `get_metrics` -1. **Inherit from Swarms Agent**: Inherit from the `SwarmsAgent` class. -2. **Create Griptape Agent**: Initialize the **Griptape** agent inside your class and provide it with the necessary tools. -3. **Override the `run()` method**: Implement logic to process a task string and execute the Griptape agent. +**Usage Example:** -## **Griptape Example Code**: +```python +metrics = artifact.get_metrics() +``` + +#### `to_dict` + +**Usage Example:** ```python -from swarms import ( - Agent as SwarmsAgent, -) # Import the base Agent class from Swarms -from griptape.structures import Agent as GriptapeAgent -from griptape.tools import ( - WebScraperTool, - FileManagerTool, - PromptSummaryTool, -) +artifact_dict = artifact.to_dict() +``` -# Create a custom agent class that inherits from SwarmsAgent -class GriptapeSwarmsAgent(SwarmsAgent): - def __init__(self, *args, **kwargs): - # Initialize the Griptape agent with its tools - self.agent = GriptapeAgent( - input="Load {{ args[0] }}, summarize it, and store it in a file called {{ args[1] }}.", - tools=[ - WebScraperTool(off_prompt=True), - PromptSummaryTool(off_prompt=True), - FileManagerTool(), - ], - *args, - **kwargs, - ) +#### `from_dict` - # Override the run method to take a task and execute it using the Griptape agent - def run(self, task: str) -> str: - # Extract URL and filename from task - url, filename = task.split(",") # Example task string: "https://example.com, output.txt" - # Execute the Griptape agent - result = self.agent.run(url.strip(), filename.strip()) - # Return the final result as a string - return str(result) +| Parameter | Type | Description | +|-----------|------------------|--------------------------------------------------| +| `data` | `Dict[str, Any]` | The dictionary representation of the artifact. | +**Usage Example:** -# Example usage: -griptape_swarms_agent = GriptapeSwarmsAgent() -output = griptape_swarms_agent.run("https://griptape.ai, griptape.txt") -print(output) +```python +artifact_data = { + "file_path": "example.txt", + "file_type": "txt", + "contents": "File content", + "versions": [], + "edit_count": 0 +} +artifact = Artifact.from_dict(artifact_data) ``` -### **Explanation**: -1. **GriptapeSwarmsAgent**: The custom class that integrates **Griptape** into **Swarms**. -2. **run(task: str)**: This method extracts inputs from the task string and runs the agent using **Griptape** tools. -3. **Tools**: The **Griptape** agent is equipped with web scraping, summarization, and file management tools. - +## Additional Information and Tips -## **Additional Features**: -You can enhance your external agents with additional features such as: +- The `Artifact` class uses the `pydantic` library to handle data validation and serialization. +- When editing the artifact, ensure that the `file_path` is set correctly to avoid file operation errors. +- Use the `get_version` and `get_version_history` methods to maintain a clear audit trail of changes to the file. +- The `export_to_json` and `import_from_json` methods are useful for backing up and restoring the state of an artifact. -- **Saving outputs** to JSON, databases, or logs. +## References and Resources -- **Handling errors** and retry mechanisms for robustness. +- [Pydantic Documentation](https://pydantic-docs.helpmanual.io/) +- [Python os.path module](https://docs.python.org/3/library/os.path.html) +- [JSON Documentation](https://docs.python.org/3/library/json.html) -- **Custom logging** with tools like **Loguru** for extensive debugging. +## Examples of Usage ---- +### Example 1: Creating and Editing an Artifact -## **Langchain Agent Integration Example** +```python +from datetime import datetime +from pydantic import BaseModel, Field, validator +from typing import List, Dict, Any, Union +import os +import json -Next, we demonstrate how to integrate a **Langchain** agent with **Swarms** by following similar steps. +# Define FileVersion class +class FileVersion(BaseModel): + version_number: int + content: str + timestamp: datetime -### **Langchain Integration Steps**: +# Artifact class definition goes here -1. **Inherit from Swarms Agent**: Inherit from the `SwarmsAgent` class. -2. **Create Langchain Agent**: Initialize a Langchain agent with the necessary components (like language models or memory modules). -3. **Override the `run()` method**: Pass tasks to the Langchain agent and return the response. +# Create an artifact +artifact = Artifact(file_path="example.txt", file_type="txt") +artifact.create(initial_content="Initial file content") -## **Langchain Example Code**: +# Edit the artifact +artifact.edit(new_content="Updated file content") -```python -from swarms import Agent as SwarmsAgent -from langchain import LLMChain -from langchain.llms import OpenAI -from langchain.prompts import PromptTemplate +# Save the artifact to a file +artifact.save() -# Create a custom agent class that inherits from SwarmsAgent -class LangchainSwarmsAgent(SwarmsAgent): - def __init__(self, *args, **kwargs): - # Initialize the Langchain agent with LLM and prompt - prompt_template = PromptTemplate(template="Answer the question: {question}") - llm = OpenAI(model="gpt-3.5-turbo") - self.chain = LLMChain(llm=llm, prompt=prompt_template) - super().__init__(*args, **kwargs) +# Load the artifact from the file +artifact.load() - # Override the run method to take a task and execute it using the Langchain agent - def run(self, task: str) -> str: - # Pass the task to the Langchain agent - result = self.chain.run({"question": task}) - # Return the final result as a string - return result +# Print the current contents of the artifact +print(artifact.get_contents()) -# Example usage: -langchain_swarms_agent = LangchainSwarmsAgent() -output = langchain_swarms_agent.run("What is the capital of France?") -print(output) +# Print the version history +print(artifact.get_version_history()) ``` -### **Explanation**: -1. **LangchainSwarmsAgent**: The custom class integrates **Langchain** into **Swarms**. -2. **run(task: str)**: The task is passed to a language model via Langchain and returns a result. +### Example 2: Exporting and Importing an Artifact +```python +# Export the artifact to a JSON file +artifact.export_to_json(file_path="artifact.json") -### Additional Examples from other providers +# Import + the artifact from a JSON file +imported_artifact = Artifact.import_from_json(file_path="artifact.json") -### 1. **OpenAI Function Calling Agents** -- **Description**: OpenAI models like GPT-4 can now call functions programmatically. This makes it possible to create agents that execute external functions, APIs, or code snippets. - - ## Example Integration: - ```python - from swarms import Agent as SwarmsAgent - import openai +# Print the metrics of the imported artifact +print(imported_artifact.get_metrics()) +``` - # Custom OpenAI Function Calling Agent - class OpenAIFunctionAgent(SwarmsAgent): - def __init__(self, *args, **kwargs): - # Initialize OpenAI API credentials and settings - self.api_key = "your_openai_api_key" - super().__init__(*args, **kwargs) +### Example 3: Converting an Artifact to and from a Dictionary - def run(self, task: str) -> str: - # Example task: "summarize, 'Provide a short summary of this text...'" - command, input_text = task.split(", ") - response = openai.Completion.create( - model="gpt-4", - prompt=f"{command}: {input_text}", - temperature=0.5, - max_tokens=100, - ) - return response.choices[0].text.strip() +```python +# Convert the artifact to a dictionary +artifact_dict = artifact.to_dict() - # Example usage: - openai_agent = OpenAIFunctionAgent() - output = openai_agent.run("summarize, Provide a short summary of this text...") - print(output) - ``` +# Create a new artifact from the dictionary +new_artifact = Artifact.from_dict(artifact_dict) -### 2. **Rasa Agents** -- **Description**: **Rasa** is a popular open-source framework for building conversational AI agents. You can integrate **Rasa** to build dialogue-based agents with **Swarms**. +# Print the metrics of the new artifact +print(new_artifact.get_metrics()) +``` - ## Example Integration: - ```python - from swarms import Agent as SwarmsAgent - from rasa.core.agent import Agent as RasaAgent - from rasa.core.interpreter import RasaNLUInterpreter - # Custom Rasa Swarms Agent - class RasaSwarmsAgent(SwarmsAgent): - def __init__(self, model_path: str, *args, **kwargs): - # Initialize the Rasa agent with a pre-trained model - self.agent = RasaAgent.load(model_path) - super().__init__(*args, **kwargs) +-------------------------------------------------- - def run(self, task: str) -> str: - # Pass user input to the Rasa agent - result = self.agent.handle_text(task) - # Return the final response from the agent - return result[0]["text"] if result else "No response." +# File: swarms\cli\cli_guide.md - # Example usage: - rasa_swarms_agent = RasaSwarmsAgent("path/to/rasa_model") - output = rasa_swarms_agent.run("Hello, how can I get a refund?") - print(output) - ``` +# The Ultimate Technical Guide to the Swarms CLI: A Step-by-Step Developer’s Guide -### 3. **Hugging Face Transformers** -- **Description**: **Hugging Face** offers a variety of pre-trained models, including transformers for NLP tasks. These can be easily integrated into **Swarms** for various tasks like text generation, question answering, and more. +Welcome to the definitive technical guide for using the Swarms Command Line Interface (CLI). The Swarms CLI enables developers, engineers, and business professionals to seamlessly manage and run Swarms of agents from the command line. This guide will walk you through the complete process of installing, configuring, and using the Swarms CLI to orchestrate intelligent agents for your needs. - ## Example Integration: - ```python - from swarms import Agent as SwarmsAgent - from transformers import pipeline +By following this guide, you will not only understand how to install and use the Swarms CLI but also learn about real-world use cases, including how the CLI is used to automate tasks across various industries, from finance to marketing, operations, and beyond. - # Custom Hugging Face Agent - class HuggingFaceSwarmsAgent(SwarmsAgent): - def __init__(self, model_name: str, *args, **kwargs): - # Initialize a pre-trained pipeline from Hugging Face - self.pipeline = pipeline("text-generation", model=model_name) - super().__init__(*args, **kwargs) +Explore the official [Swarms GitHub repository](https://github.com/kyegomez/swarms), dive into the comprehensive documentation at [Swarms Docs](https://docs.swarms.world), and explore the vast marketplace of agents on [swarms.ai](https://swarms.ai) to kickstart your journey with Swarms! - def run(self, task: str) -> str: - # Generate text based on the task input - result = self.pipeline(task, max_length=50) - return result[0]["generated_text"] +--- - # Example usage: - hf_swarms_agent = HuggingFaceSwarmsAgent("gpt2") - output = hf_swarms_agent.run("Once upon a time in a land far, far away...") - print(output) - ``` +## 1. Installing the Swarms CLI -### 4. **AutoGPT or BabyAGI** -- **Description**: **AutoGPT** and **BabyAGI** are agent frameworks designed to be autonomous, where agents can recursively execute tasks and create new tasks based on previous outputs. - - ## Example Integration: - ```python - from swarms import Agent as SwarmsAgent - from autogpt import AutoGPT +Before we explore the Swarms CLI commands, let’s get it installed and running on your machine. - # Custom AutoGPT Agent - class AutoGPTSwarmsAgent(SwarmsAgent): - def __init__(self, config, *args, **kwargs): - # Initialize AutoGPT with configuration - self.agent = AutoGPT(config) - super().__init__(*args, **kwargs) +### 1.1. Installation Using `pip` - def run(self, task: str) -> str: - # Execute task recursively using AutoGPT - result = self.agent.run(task) - return result +For most users, the simplest way to install the Swarms CLI is through `pip`: - # Example usage: - autogpt_swarms_agent = AutoGPTSwarmsAgent({"goal": "Solve world hunger"}) - output = autogpt_swarms_agent.run("Develop a plan to solve world hunger.") - print(output) - ``` +```bash +pip3 install -U swarms +``` -### 5. **DialogFlow Agents** -- **Description**: **DialogFlow** by Google is used to build conversational agents. These agents can process user intents and deliver responses based on predefined conversation flows. - - ## Example Integration: - ```python - from swarms import Agent as SwarmsAgent - from google.cloud import dialogflow +This command installs the latest version of the Swarms CLI package, ensuring that you have the newest features and fixes. - # Custom DialogFlow Agent - class DialogFlowSwarmsAgent(SwarmsAgent): - def __init__(self, project_id: str, session_id: str, *args, **kwargs): - # Initialize DialogFlow session client - self.session_client = dialogflow.SessionsClient() - self.project_id = project_id - self.session_id = session_id - super().__init__(*args, **kwargs) +### 1.2. Installation Using `Poetry` - def run(self, task: str) -> str: - session = self.session_client.session_path(self.project_id, self.session_id) - text_input = dialogflow.TextInput(text=task, language_code="en-US") - query_input = dialogflow.QueryInput(text=text_input) - response = self.session_client.detect_intent( - request={"session": session, "query_input": query_input} - ) - return response.query_result.fulfillment_text +Alternatively, if you are using `Poetry` as your Python package manager, you can add the Swarms package like this: - # Example usage: - dialogflow_swarms_agent = DialogFlowSwarmsAgent("your_project_id", "your_session_id") - output = dialogflow_swarms_agent.run("Book me a flight to Paris.") - print(output) - ``` +```bash +poetry add swarms +``` -### 6. **ChatterBot Agents** -- **Description**: **ChatterBot** is a Python-based machine-learning conversational agent. It learns from previous conversations to generate intelligent responses. - - ## Example Integration: - ```python - from swarms import Agent as SwarmsAgent - from chatterbot import ChatBot +Once installed, you can run the Swarms CLI directly using: - # Custom ChatterBot Agent - class ChatterBotSwarmsAgent(SwarmsAgent): - def __init__(self, name: str, *args, **kwargs): - # Initialize ChatterBot - self.agent = ChatBot(name) - super().__init__(*args, **kwargs) +```bash +poetry run swarms help +``` - def run(self, task: str) -> str: - # Get a response from ChatterBot based on user input - response = self.agent.get_response(task) - return str(response) +This command shows all the available options and commands, as we will explore in-depth below. - # Example usage: - chatterbot_swarms_agent = ChatterBotSwarmsAgent("Assistant") - output = chatterbot_swarms_agent.run("What is the capital of Italy?") - print(output) - ``` +--- -### 7. **Custom APIs as Agents** -- **Description**: You can create agents that integrate with any REST or GraphQL API by defining them as a task runner within Swarms. This allows for interaction with third-party services. - - ## Example Integration: - ```python - from swarms import Agent as SwarmsAgent - import requests +## 2. Understanding Swarms CLI Commands - # Custom API Agent - class APIAgent(SwarmsAgent): - def run(self, task: str) -> str: - # Parse task for API endpoint and parameters - endpoint, params = task.split(", ") - response = requests.get(endpoint, params={"q": params}) - return response.text +With the Swarms CLI installed, the next step is to explore its key functionalities. Here are the most essential commands: - # Example usage: - api_swarms_agent = APIAgent() - output = api_swarms_agent.run("https://api.example.com/search, python") - print(output) - ``` +### 2.1. `onboarding`: Setup Your Environment ---- +The `onboarding` command guides you through setting up your environment and configuring the agents for your Swarms. -### **Summary of Integrations**: +```bash +swarms onboarding +``` -- **Griptape**: Integrate with tools for web scraping, summarization, etc. +This is the first step when you begin working with the Swarms platform. It helps to: -- **Langchain**: Use powerful language model orchestration. +- Authenticate your Swarms account. +- Download any necessary configurations. +- Ensure everything is in place to launch agents seamlessly. -- **OpenAI Function Calling**: Directly run OpenAI API-based agents. +### 2.2. `help`: Learn Available Commands -- **Rasa**: Build and integrate conversational agents. +Running `help` displays the various commands you can use: -- **Hugging Face**: Leverage transformer models. +```bash +swarms help +``` -- **AutoGPT/BabyAGI**: Recursive, autonomous task execution. +This command will output a helpful list like the one shown below, including detailed descriptions of each command. -- **DialogFlow**: Integrate conversational flows for voice/chat-based systems. +```plaintext +Swarms CLI - Help -- **ChatterBot**: Machine-learning conversational agents. +Commands: +onboarding : Starts the onboarding process +help : Shows this help message +get-api-key : Retrieves your API key from the platform +check-login : Checks if you're logged in and starts the cache +read-docs : Redirects you to swarms cloud documentation +run-agents : Run your Agents from your agents.yaml +``` -- **Custom APIs**: Leverage external APIs as agents for custom workflows. +### 2.3. `get-api-key`: Access API Integration +One of the key functionalities of the Swarms platform is integrating your agents with the Swarms API. To retrieve your unique API key for communication, use this command: ---- +```bash +swarms get-api-key +``` +Your API key is essential to enable agent workflows and access various services through the Swarms platform. -## **Conclusion**: +### 2.4. `check-login`: Verify Authentication -By following the steps outlined above, you can seamlessly integrate external agent frameworks like **Griptape** and **Langchain** into **Swarms**. This makes Swarms a highly versatile platform for orchestrating various agentic workflows and leveraging the unique capabilities of different frameworks. +Use the `check-login` command to verify if you're logged in and ensure that your credentials are cached: -For more examples and use cases, please refer to the official Swarms documentation site. +```bash +swarms check-login +``` +This ensures seamless operation, allowing agents to execute tasks securely on the Swarms platform without needing to log in repeatedly. +### 2.5. `read-docs`: Explore Official Documentation --------------------------------------------------- +Easily access the official documentation with this command: -# File: swarms/agents/gkp_agent.md +```bash +swarms read-docs +``` -# Generated Knowledge Prompting (GKP) Agent +You’ll be redirected to the Swarms documentation site, [Swarms Docs](https://docs.swarms.world), where you'll find in-depth explanations, advanced use-cases, and more. -The GKP Agent is a sophisticated reasoning system that enhances its capabilities by generating relevant knowledge before answering queries. This approach, inspired by Liu et al. 2022, is particularly effective for tasks requiring commonsense reasoning and factual information. +### 2.6. `run-agents`: Orchestrate Agents -## Overview +Perhaps the most important command in the CLI is `run-agents`, which allows you to execute your agents as defined in your `agents.yaml` configuration file. -The GKP Agent consists of three main components: -1. Knowledge Generator - Creates relevant factual information -2. Reasoner - Uses generated knowledge to form answers -3. Coordinator - Synthesizes multiple reasoning paths into a final answer +```bash +swarms run-agents --yaml-file agents.yaml +``` -## Architecture +If you want to specify a custom configuration file, just pass in the YAML file using the `--yaml-file` flag. -```mermaid -graph TD - A[Input Query] --> B[Knowledge Generator] - B --> C[Generate Knowledge Items] - C --> D[Reasoner] - D --> E[Multiple Reasoning Paths] - E --> F[Coordinator] - F --> G[Final Answer] - - subgraph "Knowledge Generation" - B - C - end - - subgraph "Reasoning" - D - E - end - - subgraph "Coordination" - F - G - end -``` +--- -## Use Cases +## 3. Working with the `agents.yaml` Configuration File -```mermaid -graph LR - A[GKP Agent] --> B[Commonsense Reasoning] - A --> C[Factual Question Answering] - A --> D[Complex Problem Solving] - A --> E[Multi-step Reasoning] - - B --> B1[Everyday Logic] - B --> B2[Social Situations] - - C --> C1[Historical Facts] - C --> C2[Scientific Information] - - D --> D1[Technical Analysis] - D --> D2[Decision Making] - - E --> E1[Chain of Thought] - E --> E2[Multi-perspective Analysis] -``` - -## API Reference - -### GKPAgent - -The main agent class that orchestrates the knowledge generation and reasoning process. +The `agents.yaml` file is at the heart of your Swarms setup. This file allows you to define the structure and behavior of each agent you want to run. Below is an example YAML configuration for two agents. -#### Initialization Parameters +### 3.1. Example `agents.yaml` Configuration: -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| agent_name | str | "gkp-agent" | Name identifier for the agent | -| model_name | str | "openai/o1" | LLM model to use for all components | -| num_knowledge_items | int | 6 | Number of knowledge snippets to generate per query | +```yaml +agents: + - agent_name: "Financial-Advisor-Agent" + model: + model_name: "gpt-4o-mini" + temperature: 0.3 + max_tokens: 2500 + system_prompt: | + You are a highly knowledgeable financial advisor with expertise in tax strategies, investment management, and retirement planning. + Provide concise and actionable advice based on the user's financial goals and situation. + max_loops: 1 + autosave: true + dashboard: false + verbose: true + dynamic_temperature_enabled: true + saved_state_path: "financial_advisor_state.json" + user_name: "finance_user" + retry_attempts: 2 + context_length: 200000 + return_step_meta: false + output_type: "str" + task: "I am 35 years old with a moderate risk tolerance. How should I diversify my portfolio for retirement in 20 years?" -#### Methods + - agent_name: "Stock-Market-Analysis-Agent" + model: + model_name: "gpt-4o-mini" + temperature: 0.25 + max_tokens: 1800 + system_prompt: | + You are an expert stock market analyst with a deep understanding of technical analysis, market trends, and long-term investment strategies. + Provide well-reasoned investment advice, taking current market conditions into account. + max_loops: 2 + autosave: true + dashboard: false + verbose: true + dynamic_temperature_enabled: false + saved_state_path: "stock_market_analysis_state.json" + user_name: "market_analyst" + retry_attempts: 3 + context_length: 150000 + return_step_meta: true + output_type: "json" + task: "Analyze the current market trends for tech stocks and suggest the best long-term investment options." -| Method | Description | Parameters | Returns | -|--------|-------------|------------|---------| -| process(query: str) | Process a single query through the GKP pipeline | query: str | Dict[str, Any] containing full processing results | -| run(queries: List[str], detailed_output: bool = False) | Process multiple queries | queries: List[str], detailed_output: bool | Union[List[str], List[Dict[str, Any]]] | + - agent_name: "Marketing-Strategy-Agent" + model: + model_name: "gpt-4o-mini" + temperature: 0.4 + max_tokens: 2200 + system_prompt: | + You are a marketing strategist with expertise in digital campaigns, customer engagement, and branding. + Provide a comprehensive marketing strategy to increase brand awareness and drive customer acquisition for an e-commerce business. + max_loops: 1 + autosave: true + dashboard: false + verbose: true + dynamic_temperature_enabled: true + saved_state_path: "marketing_strategy_state.json" + user_name: "marketing_user" + retry_attempts: 2 + context_length: 200000 + return_step_meta: false + output_type: "str" + task: "Create a 6-month digital marketing strategy for a new eco-friendly e-commerce brand targeting millennial consumers." -### KnowledgeGenerator + - agent_name: "Operations-Optimizer-Agent" + model: + model_name: "gpt-4o-mini" + temperature: 0.2 + max_tokens: 2000 + system_prompt: | + You are an operations expert with extensive experience in optimizing workflows, reducing costs, and improving efficiency in supply chains. + Provide actionable recommendations to streamline business operations. + max_loops: 1 + autosave: true + dashboard: false + verbose: true + dynamic_temperature_enabled: true + saved_state_path: "operations_optimizer_state.json" + user_name: "operations_user" + retry_attempts: 1 + context_length: 200000 + return_step_meta: false + output_type: "str" + task: "Identify ways to improve the efficiency of a small manufacturing company’s supply chain to reduce costs by 15% within one year." +``` -Component responsible for generating relevant knowledge for queries. +### 3.2. Explanation of Key Fields -#### Initialization Parameters +- **agent_name**: The name of your agent (e.g., Financial-Analysis-Agent). +- **model**: Specifies which model to use. In this case, `gpt-4o-mini` is used. + - **temperature**: Controls the randomness of the model’s responses. + - **max_tokens**: The maximum number of tokens to generate. +- **system_prompt**: Defines the prompt that instructs the agent. +- **max_loops**: Limits the number of times the agent will retry tasks. +- **autosave**: Saves the agent's state automatically after each run. +- **dashboard**: Set to `true` or `false` depending on whether you want to enable the agent’s dashboard. +- **saved_state_path**: Path to save agent's state, enabling future runs to resume from the last state. +- **task**: The primary task or question that the agent will address. -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| agent_name | str | "knowledge-generator" | Name identifier for the knowledge generator agent | -| model_name | str | "openai/o1" | Model to use for knowledge generation | -| num_knowledge_items | int | 2 | Number of knowledge items to generate per query | +### 3.3. Running Agents Using `agents.yaml` -#### Methods +After configuring the agents, you can execute them directly from the CLI: -| Method | Description | Parameters | Returns | -|--------|-------------|------------|---------| -| generate_knowledge(query: str) | Generate relevant knowledge for a query | query: str | List[str] of generated knowledge statements | +```bash +swarms run-agents --yaml-file agents_config.yaml +``` -### Reasoner +This command will run the specified agents, allowing them to perform their tasks and return results according to your configuration. -Component that uses generated knowledge to reason about and answer queries. +--- -#### Initialization Parameters +## 4. Use Cases for the Swarms CLI -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| agent_name | str | "knowledge-reasoner" | Name identifier for the reasoner agent | -| model_name | str | "openai/o1" | Model to use for reasoning | +Now that you have a solid understanding of the basic commands and the `agents.yaml` configuration, let's explore how the Swarms CLI can be applied in real-world scenarios. -#### Methods +### 4.1. Financial Data Analysis -| Method | Description | Parameters | Returns | -|--------|-------------|------------|---------| -| reason_and_answer(query: str, knowledge: str) | Reason about a query using provided knowledge | query: str, knowledge: str | Dict[str, str] containing explanation, confidence, and answer | +For financial firms or hedge funds, agents like the "Financial-Analysis-Agent" can be set up to automate complex financial analyses. You could have agents analyze market trends, recommend portfolio adjustments, or perform tax optimizations. -## Example Usage +Example Task: Automating long-term investment analysis using historical stock data. -```python -from swarms.agents.gkp_agent import GKPAgent +```bash +swarms run-agents --yaml-file finance_analysis.yaml +``` -# Initialize the GKP Agent -agent = GKPAgent( - agent_name="gkp-agent", - model_name="gpt-4", # Using OpenAI's model - num_knowledge_items=6, # Generate 6 knowledge items per query -) +### 4.2. Marketing Automation -# Example queries -queries = [ - "What are the implications of quantum entanglement on information theory?", -] +Marketing departments can utilize Swarms agents to optimize campaigns, generate compelling ad copy, or provide detailed marketing insights. You can create a `Marketing-Agent` to process customer feedback, perform sentiment analysis, and suggest marketing strategies. -# Run the agent -results = agent.run(queries) +Example Task: Running multiple agents to analyze customer sentiment from recent surveys. -# Print results -for i, result in enumerate(results): - print(f"\nQuery {i+1}: {queries[i]}") - print(f"Answer: {result}") +```bash +swarms run-agents --yaml-file marketing_agents.yaml ``` -## Best Practices +### 4.3. Operations and Task Management -1. **Knowledge Generation** - - Set appropriate number of knowledge items based on query complexity - - Monitor knowledge quality and relevance - - Adjust model parameters for optimal performance +Companies can create agents for automating internal task management. For example, you might have a set of agents responsible for managing deadlines, employee tasks, and progress tracking. -2. **Reasoning Process** - - Ensure diverse reasoning paths for complex queries - - Validate confidence levels - - Consider multiple perspectives +Example Task: Automating a task management system using Swarms agents. -3. **Coordination** - - Review coordination logic for complex scenarios - - Validate final answers against source knowledge - - Monitor processing time and optimize if needed +```bash +swarms run-agents --yaml-file operations_agents.yaml +``` -## Performance Considerations +--- -- Processing time increases with number of knowledge items -- Complex queries may require more knowledge items -- Consider caching frequently used knowledge -- Monitor token usage for cost optimization +## 5. Advanced Usage: Customizing and Scaling Agents -## Error Handling +The Swarms CLI is flexible and scalable. As your needs grow, you can start running agents across multiple machines, scale workloads dynamically, and even run multiple swarms in parallel. -The agent includes robust error handling for: -- Invalid queries -- Failed knowledge generation -- Reasoning errors -- Coordination failures +### 5.1. Running Agents in Parallel +To run multiple agents concurrently, you can utilize different YAML configurations for each agent or group of agents. This allows for extensive scaling, especially when dealing with large datasets or complex workflows. --------------------------------------------------- +```bash +swarms run-agents --yaml-file agents_batch_1.yaml & +swar -# File: swarms/agents/iterative_agent.md +ms run-agents --yaml-file agents_batch_2.yaml & +``` -# Iterative Reflective Expansion (IRE) Algorithm Documentation +### 5.2. Integration with Other Tools -The Iterative Reflective Expansion (IRE) Algorithm is a sophisticated reasoning framework that employs iterative hypothesis generation, simulation, and refinement to solve complex problems. It leverages a multi-step approach where an AI agent generates initial solution paths, evaluates their effectiveness through simulation, reflects on errors, and dynamically revises reasoning strategies. Through continuous cycles of hypothesis testing and meta-cognitive reflection, the algorithm progressively converges on optimal solutions by learning from both successful and unsuccessful reasoning attempts. +The Swarms CLI integrates with many tools and platforms via APIs. You can connect Swarms with external platforms such as AWS, Azure, or your custom cloud setup for enterprise-level automation. +--- -## Architecture +## 6. Conclusion and Next Steps -```mermaid -graph TD - Problem_Input["🧩 Problem Input"] --> Generate_Hypotheses - Generate_Hypotheses["Generate Initial Hypotheses"] --> Simulate - subgraph Iterative Reflective Expansion Loop - Simulate["Simulate Reasoning Paths"] --> Evaluate - Evaluate["Evaluate Outcomes"] --> Reflect{Is solution satisfactory?} - Reflect -->|No, issues found| Meta_Reflect - Reflect -->|Yes| Promising - Meta_Reflect["Meta-Cognitive Reflection"] --> Revise_Paths - Meta_Reflect --> Memory[(Reasoning Memory)] - Meta_Reflect --> Memory - Revise_Paths["Revise Paths Based on Feedback"] --> Expand_Paths - Meta_Reflect --> Revise_Path - Revise_Path["Revise Paths"] --> Expand_Paths - Expand_Paths["Iterative Expansion & Pruning"] --> Simulate - end - Promising["Promising Paths Selected"] --> Memory - Memory["Memory Integration"] --> Synthesize - Synthesize["Synthesize Final Solution"] --> Final["Final Solution ✅"] +The Swarms CLI is a powerful tool for automating agent workflows in various industries, including finance, marketing, and operations. By following this guide, you should now have a thorough understanding of how to install and use the CLI, configure agents, and apply it to real-world use cases. -``` +To further explore Swarms, be sure to check out the official [Swarms GitHub repository](https://github.com/kyegomez/swarms), where you can contribute to the framework or build your own custom agents. Dive deeper into the documentation at [Swarms Docs](https://docs.swarms.world), and browse the extensive agent marketplace at [swarms.ai](https://swarms.ai). ---- +With the Swarms CLI, the future of automation is within reach. -## Workflow -1. Generate initial hypotheses -2. Simulate paths -3. Reflect on errors -4. Revise paths -5. Select promising paths -6. Synthesize solution -## Class: IterativeReflectiveExpansion +-------------------------------------------------- -### Arguments +# File: swarms\cli\main.md -| Argument | Type | Default | Description | -|----------------|--------|---------|-------------| -| agent | Agent | None | The Swarms agent instance used to perform reasoning tasks. | -| max_iterations | int | 5 | Maximum number of iterations for the reasoning process. | -| return_list | bool | False | If True, returns the conversation as a list of messages. | -| return_dict | bool | False | If True, returns the conversation as a dictionary of messages. | -| prompt | str | GENERAL_REASONING_AGENT_SYS_PROMPT | The system prompt for the agent. | +# Swarms CLI Documentation -### Methods +The Swarms Command Line Interface (CLI) allows you to easily manage and run your Swarms of agents from the command line. This page will guide you through the installation process and provide a breakdown of the available commands. -| Method | Description | -|-------------------------------|-------------| -| generate_initial_hypotheses | Generates an initial set of reasoning hypotheses based on the problem input. | -| simulate_path | Simulates a given reasoning path and evaluates its effectiveness. | -| meta_reflect | Performs meta-cognitive reflection on the provided error information. | -| revise_path | Revises the reasoning path based on the provided feedback. | -| select_promising_paths | Selects the most promising reasoning paths from a list of candidates. | -| synthesize_solution | Synthesizes a final solution from the promising reasoning paths and historical memory. | -| run | Executes the Iterative Reflective Expansion process on the provided problem. | +## Installation -## Use-Cases +You can install the `swarms` package using `pip` or `poetry`. -### Example 1: Solving a Mathematical Problem +### Using pip -```python -from swarms import IterativeReflectiveExpansion +```bash +pip3 install -U swarms +``` -agent = IterativeReflectiveExpansion( - max_iterations=3, -) +### Using poetry -agent.run("What is the 40th prime number?") +```bash +poetry add swarms ``` -## Conclusion - -The Iterative Reflective Expansion (IRE) Algorithm is a powerful tool for solving complex problems through iterative reasoning and reflection. By leveraging the capabilities of a Swarms agent, it can dynamically adapt and refine its approach to converge on optimal solutions. +Once installed, you can run the Swarms CLI with the following command: +```bash +poetry run swarms help +``` --------------------------------------------------- +## Swarms CLI - Help -# File: swarms/agents/message.md +When running `swarms help`, you'll see the following output: -# The Module/Class Name: Message +``` + _________ + / _____/_ _ _______ _______ _____ ______ + \_____ \ \/ \/ /\__ \_ __ \/ \ / ___/ + / \ / / __ \| | \/ Y Y \___ \ +/_______ / \/\_/ (____ /__| |__|_| /____ > + \/ \/ \/ \/ -In the swarms.agents framework, the class `Message` is used to represent a message with timestamp and optional metadata. -## Overview and Introduction -The `Message` class is a fundamental component that enables the representation of messages within an agent system. Messages contain essential information such as the sender, content, timestamp, and optional metadata. + Swarms CLI - Help -## Class Definition + Commands: + onboarding : Starts the onboarding process + help : Shows this help message + get-api-key : Retrieves your API key from the platform + check-login : Checks if you're logged in and starts the cache + read-docs : Redirects you to swarms cloud documentation! + run-agents : Run your Agents from your agents.yaml -### Constructor: `__init__` + For more details, visit: https://docs.swarms.world +``` -The constructor of the `Message` class takes three parameters: +### CLI Commands -1. `sender` (str): The sender of the message. -2. `content` (str): The content of the message. -3. `metadata` (dict or None): Optional metadata associated with the message. +Below is a detailed explanation of the available commands: -### Methods +- **onboarding** + Starts the onboarding process to help you set up your environment and configure your agents. + + Usage: + ```bash + swarms onboarding + ``` -1. `__repr__(self)`: Returns a string representation of the `Message` object, including the timestamp, sender, and content. +- **help** + Displays the help message, including a list of available commands. -```python -class Message: - """ - Represents a message with timestamp and optional metadata. + Usage: + ```bash + swarms help + ``` - Usage - -------------- - mes = Message( - sender = "Kye", - content = "message" - ) +- **get-api-key** + Retrieves your API key from the platform, allowing your agents to communicate with the Swarms platform. - print(mes) - """ + Usage: + ```bash + swarms get-api-key + ``` - def __init__(self, sender, content, metadata=None): - self.timestamp = datetime.datetime.now() - self.sender = sender - self.content = content - self.metadata = metadata or {} +- **check-login** + Verifies if you are logged into the platform and starts the cache for storing your login session. - def __repr__(self): - """ - __repr__ represents the string representation of the Message object. + Usage: + ```bash + swarms check-login + ``` - Returns: - (str) A string containing the timestamp, sender, and content of the message. - """ - return f"{self.timestamp} - {self.sender}: {self.content}" -``` +- **read-docs** + Redirects you to the official Swarms documentation on the web for further reading. -## Functionality and Usage + Usage: + ```bash + swarms read-docs + ``` -The `Message` class represents a message in the agent system. Upon initialization, the `timestamp` is set to the current date and time, and the `metadata` is set to an empty dictionary if no metadata is provided. +- **run-agents** + Executes your agents from the `agents.yaml` configuration file, which defines the structure and behavior of your agents. Refer to this document for how to leverage yamls for fast, reliable, and simple agent orchestration. [CLICK HERE](https://docs.swarms.world/en/latest/swarms/agents/create_agents_yaml/) You can customize what yaml file to run with `--yaml-file` -### Usage Example 1 + Usage: + ```bash + swarms run-agents --yaml-file agents.yaml + ``` -Creating a `Message` object and displaying its string representation. -```python -mes = Message(sender="Kye", content="Hello! How are you?") +-------------------------------------------------- -print(mes) -``` +# File: swarms\concept\framework_architecture.md -Output: -``` -2023-09-20 13:45:00 - Kye: Hello! How are you? -``` +# Swarms Framework Architecture -### Usage Example 2 -Creating a `Message` object with metadata. +The Swarms package is designed to orchestrate and manage **swarms of agents**, enabling collaboration between multiple Large Language Models (LLMs) or other agent types to solve complex tasks. The architecture is modular and scalable, facilitating seamless integration of various agents, models, prompts, and tools. Below is an overview of the architectural components, along with instructions on where to find the corresponding documentation. -```python -metadata = {"priority": "high", "category": "urgent"} -mes_with_metadata = Message( - sender="Alice", content="Important update", metadata=metadata -) -print(mes_with_metadata) -``` -Output: -``` -2023-09-20 13:46:00 - Alice: Important update ``` - -### Usage Example 3 - -Creating a `Message` object without providing metadata. - -```python -mes_no_metadata = Message(sender="Bob", content="Reminder: Meeting at 2PM") - -print(mes_no_metadata) +swarms/ +├── agents/ +├── artifacts/ +├── cli/ +├── memory/ +├── models/ ---> Moved to swarm_models +├── prompts/ +├── schemas/ +├── structs/ +├── telemetry/ +├── tools/ +├── utils/ +└── __init__.py ``` -Output: -``` -2023-09-20 13:47:00 - Bob: Reminder: Meeting at 2PM -``` -## Additional Information and Tips -When creating a new `Message` object, ensure that the required parameters `sender` and `content` are provided. The `timestamp` will automatically be assigned the current date and time. Optional `metadata` can be included to provide additional context or information associated with the message. +### Role of Folders in the Swarms Framework -## References and Resources +The **Swarms framework** is composed of several key folders, each serving a specific role in building, orchestrating, and managing swarms of agents. Below is an in-depth explanation of the role of each folder in the framework's architecture, focusing on how they contribute to the overall system for handling complex multi-agent workflows. -For further information on the `Message` class and its usage, refer to the official swarms.agents documentation and relevant tutorials related to message handling and communication within the agent system. +--- +### **1. Agents Folder (`agents/`)** + - **Role:** + - The **agents** folder contains the core logic for individual agents within the Swarms framework. Agents are the key functional units responsible for carrying out specific tasks, whether it be text generation, web scraping, data analysis, or more specialized functions like marketing or accounting. + - **Customization:** Each agent can be specialized for different tasks by defining custom system prompts and behaviors. + - **Modular Agent System:** New agents can be easily added to this folder to expand the framework's capabilities. + - **Importance:** This folder allows users to create and manage multiple types of agents that can interact and collaborate to solve complex problems. + - **Examples:** Accounting agents, marketing agents, and programming agents. --------------------------------------------------- +--- -# File: swarms/agents/new_agent.md +### **2. Artifacts Folder (`artifacts/`)** + - **Role:** + - The **artifacts** folder is responsible for storing the results or outputs generated by agents and swarms. This could include reports, logs, or data that agents generate during task execution. + - **Persistent Storage:** It helps maintain a persistent record of agent interactions, making it easier to retrieve or review past actions and outputs. + - **Data Handling:** Users can configure this folder to store artifacts that are essential for later analysis or reporting. + - **Importance:** Acts as a storage mechanism for important task-related outputs, ensuring that no data is lost after tasks are completed. -# How to Create Good Agents +--- -This guide will walk you through the steps to build high-quality agents by extending the `Agent` class. It emphasizes best practices, the use of type annotations, comprehensive documentation, and modular design to ensure maintainability and scalability. Additionally, you will learn how to incorporate a callable `llm` parameter or specify a `model_name` attribute to enhance flexibility and functionality. These principles ensure that agents are not only functional but also robust and adaptable to future requirements. +### **3. CLI Folder (`cli/`)** + - **Role:** + - The **CLI** folder contains tools for interacting with the Swarms framework through the command-line interface. This allows users to easily manage and orchestrate swarms without needing a graphical interface. + - **Command-line Tools:** Commands in this folder enable users to initiate, control, and monitor swarms, making the system accessible and versatile. + - **Automation and Scriptability:** Enables advanced users to automate swarm interactions and deploy agents programmatically. + - **Importance:** Provides a flexible way to control the Swarms system for developers who prefer using the command line. -## Overview +--- -A good agent is a modular and reusable component designed to perform specific tasks efficiently. By inheriting from the base `Agent` class, developers can extend its functionality while adhering to standardized principles. Each custom agent should: +### **4. Memory Folder (`memory/`) Deprecated!!** + - **Role:** + - The **memory** folder handles the framework's memory management for agents. This allows agents to retain and recall past interactions or task contexts, enabling continuity in long-running processes or multi-step workflows. + - **Context Retention:** Agents that depend on historical context to make decisions or carry out tasks can store and access memory using this folder. + - **Long-Term and Short-Term Memory:** This could be implemented in various ways, such as short-term conversational memory or long-term knowledge storage. + - **Importance:** Crucial for agents that require memory to handle complex workflows, where decisions are based on prior outputs or interactions. -- Inherit from the `Agent` class to maintain compatibility with swarms. -- Define a `run(task: str, img: str)` method to execute tasks effectively. -- Include descriptive attributes such as `name`, `system_prompt`, and `description` to enhance clarity. -- Optionally, include an `llm` parameter (callable) or a `model_name` to enable seamless integration with language models. -- Emphasize modularity, allowing the agent to be reused across various contexts and tasks. +--- -By following these guidelines, you can create agents that integrate well with broader systems and exhibit high reliability in real-world applications. +### **5. Models Folder (`models/`) Moved to `swarm_models`** + - **Role:** + - The **models** folder houses pre-trained machine learning models that agents utilize to complete their tasks. These models could include LLMs (Large Language Models), custom-trained models, or fine-tuned models specific to the tasks being handled by the agents. + - **Plug-and-Play Architecture:** The framework allows users to easily add or switch models depending on the specific needs of their agents. + - **Custom Model Support:** Users can integrate custom models here for more specialized tasks. + - **Importance:** Provides the computational backbone for agent decision-making and task execution. --- -## Creating a Custom Agent +### **6. Prompts Folder (`prompts/`)** + - **Role:** + - The **prompts** folder contains reusable prompt templates that agents use to interact with their environment and complete tasks. These system prompts define the behavior and task orientation of the agents. + - **Template Reusability:** Users can create and store common prompt templates, making it easy to define agent behavior across different tasks without rewriting prompts from scratch. + - **Task-Specific Prompts:** For example, an accounting agent may have a prompt template that guides its interaction with financial data. + - **Importance:** Provides the logic and guidance agents need to generate outputs in a coherent and task-focused manner. -Here is a detailed template for creating a custom agent by inheriting the `Agent` class. This template demonstrates how to structure an agent with extendable and reusable features: +--- -```python -from typing import Callable, Any -from swarms import Agent +### **7. Schemas Folder (`schemas/`)** + - **Role:** + - The **schemas** folder defines the data structures and validation logic for inputs and outputs within the framework, using tools like **Pydantic** for data validation. + - **Standardization and Validation:** This ensures that all interactions between agents and swarms follow consistent data formats, which is critical for large-scale agent coordination and task management. + - **Error Prevention:** By validating data early, it prevents errors from propagating through the system, improving reliability. + - **Importance:** Ensures data consistency across the entire framework, making it easier to integrate and manage swarms of agents at scale. -class MyNewAgent(Agent): - """ - A custom agent class for specialized tasks. +--- - Attributes: - name (str): The name of the agent. - system_prompt (str): The prompt guiding the agent's behavior. - description (str): A brief description of the agent's purpose. - llm (Callable, optional): A callable representing the language model to use. - """ +### **8. Structs Folder (`structs/`)** + - **Role:** + - The **structs** folder is the core of the Swarms framework, housing the orchestration logic for managing and coordinating swarms of agents. This folder allows for dynamic task assignment, queue management, inter-agent communication, and result aggregation. + - **Swarm Management:** Agents are grouped into swarms to handle tasks that require multiple agents working in parallel or collaboratively. + - **Scalability:** The swarm structure is designed to be scalable, allowing thousands of agents to operate together on distributed tasks. + - **Task Queueing and Execution:** Supports task queueing, task prioritization, and load balancing between agents. + - **Importance:** This folder is critical for managing how agents interact and collaborate to solve complex, multi-step problems. - def __init__(self, name: str, system_prompt: str, model_name: str = None, description: str, llm: Callable = None): - """ - Initialize the custom agent. +--- - Args: - name (str): The name of the agent. - system_prompt (str): The prompt guiding the agent. - model_name (str): The name of your model can use litellm [openai/gpt-4o] - description (str): A description of the agent's purpose. - llm (Callable, optional): A callable representing the language model to use. - """ - super().__init__(agent_name=name, system_prompt=system_prompt, model_name=model_name) - self.agent_name = agent_name - self.system_prompt system_prompt - self.description = description - self.model_name = model_name +### **9. Telemetry Folder (`telemetry/`)** + - **Role:** + - The **telemetry** folder provides logging and monitoring tools to capture agent performance metrics, error handling, and real-time activity tracking. It helps users keep track of what each agent or swarm is doing, making it easier to debug, audit, and optimize operations. + - **Monitoring:** Tracks agent performance and system health. + - **Logs:** Maintains logs for troubleshooting and operational review. + - **Importance:** Provides visibility into the system, ensuring smooth operation and enabling fine-tuning of agent behaviors. - def run(self, task: str, img: str, *args: Any, **kwargs: Any) -> Any: - """ - Execute the task assigned to the agent. +--- - Args: - task (str): The task description. - img (str): The image input for processing. - *args: Additional positional arguments. - **kwargs: Additional keyword arguments. +### **10. Tools Folder (`tools/`)** + - **Role:** + - The **tools** folder contains specialized utility functions or scripts that agents and swarms may require to complete certain tasks, such as web scraping, API interactions, data parsing, or other external resource handling. + - **Task-Specific Tools:** Agents can call these tools to perform operations outside of their own logic, enabling them to interact with external systems more efficiently. + - **Importance:** Expands the capabilities of agents, allowing them to complete more sophisticated tasks by relying on these external tools. - Returns: - Any: The result of the task execution. - """ - # Your custom logic - ... -``` +--- -This design ensures a seamless extension of functionality while maintaining clear and maintainable code. +### **11. Utils Folder (`utils/`)** + - **Role:** + - The **utils** folder contains general-purpose utility functions that are reused throughout the framework. These may include functions for data formatting, validation, logging setup, and configuration management. + - **Shared Utilities:** Helps keep the codebase clean by providing reusable functions that multiple agents or parts of the framework can call. + - **Importance:** Provides common functions that help the Swarms framework operate efficiently and consistently. --- -## Key Considerations - -### 1. **Type Annotations** -Always use type hints for method parameters and return values. This improves code readability, supports static analysis tools, and reduces bugs, ensuring long-term reliability. +### **Core Initialization File (`__init__.py`)** + - **Role:** + - The `__init__.py` file is the entry point of the Swarms package, ensuring that all necessary modules, agents, and tools are loaded when the Swarms framework is imported. It allows for the modular loading of different components, making it easier for users to work with only the parts of the framework they need. + - **Importance:** Acts as the bridge that connects all other components in the framework, enabling the entire package to work together seamlessly. -### 2. **Comprehensive Documentation** -Provide detailed docstrings for all classes, methods, and attributes. Clear documentation ensures that your agent's functionality is understandable to both current and future collaborators. +--- -### 3. **Modular Design** -Keep the agent logic modular and reusable. Modularity simplifies debugging, testing, and extending functionalities, making the code more adaptable to diverse scenarios. +### How to Access Documentation -### 4. **Flexible Model Integration** -Use either an `llm` callable or `model_name` attribute for integrating language models. This flexibility ensures your agent can adapt to various tasks, environments, and system requirements. +- **Official Documentation Site:** + - URL: [docs.swarms.world](https://docs.swarms.world) + - Here, users can find detailed guides, tutorials, and API references on how to use each of the folders mentioned above. The documentation covers setup, agent orchestration, and practical examples of how to leverage swarms for real-world tasks. -### 5. **Error Handling** -Incorporate robust error handling to manage unexpected inputs or issues during execution. This not only ensures reliability but also builds user trust in your system. +- **GitHub Repository:** + - URL: [Swarms GitHub](https://github.com/kyegomez/swarms) + - The repository contains code examples, detailed folder explanations, and further resources on how to get started with building and managing agent swarms. -### 6. **Scalability Considerations** -Ensure your agent design can scale to accommodate increased complexity or a larger number of tasks without compromising performance. +By understanding the purpose and role of each folder in the Swarms framework, users can more effectively build, orchestrate, and manage agents to handle complex tasks and workflows at scale. ---- +## Support: -## Example Usage +- **Post Issue On Github** + - URL: [Submit issue](https://github.com/kyegomez/swarms/issues/new/choose) + - Post your issue whether it's an issue or a feature request -Here is an example of how to use your custom agent effectively: -```python -# Example LLM callable -class MockLLM: - """ - A mock language model class for simulating LLM behavior. +- **Community Support** + - URL: [Submit issue](https://discord.gg/jM3Z6M9uMq) + - Ask the community for support in real-time and or admin support - Methods: - run(task: str, img: str, *args: Any, **kwargs: Any) -> str: - Processes the task and image input to return a simulated response. - """ +-------------------------------------------------- - def run(self, task: str, img: str, *args: Any, **kwargs: Any) -> str: - return f"Processed task '{task}' with image '{img}'" +# File: swarms\concept\future_swarm_architectures.md -# Create an instance of MyNewAgent -agent = MyNewAgent( - name="ImageProcessor", - system_prompt="Process images and extract relevant details.", - description="An agent specialized in processing images and extracting insights.", - llm=MockLLM().run -) -# Run a task -result = agent.run(task="Analyze content", img="path/to/image.jpg") -print(result) -``` -This example showcases the practical application of the `MyNewAgent` class and highlights its extensibility. +--- +### Federated Swarm -## Production-Grade Example with **Griptape Agent Integration Example** +**Overview:** +A Federated Swarm architecture involves multiple independent swarms collaborating to complete a task. Each swarm operates autonomously but can share information and results with other swarms. -In this example, we will create a **Griptape** agent by inheriting from the Swarms `Agent` class and implementing the `run` method. +**Use-Cases:** +- Distributed learning systems where data is processed across multiple nodes. -### **Griptape Integration Steps**: +- Scenarios requiring collaboration between different teams or departments. -1. **Inherit from Swarms Agent**: Inherit from the `SwarmsAgent` class. -2. **Create Griptape Agent**: Initialize the **Griptape** agent inside your class and provide it with the necessary tools. -3. **Override the `run()` method**: Implement logic to process a task string and execute the Griptape agent. +```mermaid +graph TD + A[Central Coordinator] + subgraph Swarm1 + B1[Agent 1.1] --> B2[Agent 1.2] + B2 --> B3[Agent 1.3] + end + subgraph Swarm2 + C1[Agent 2.1] --> C2[Agent 2.2] + C2 --> C3[Agent 2.3] + end + subgraph Swarm3 + D1[Agent 3.1] --> D2[Agent 3.2] + D2 --> D3[Agent 3.3] + end + B1 --> A + C1 --> A + D1 --> A +``` -## **Griptape Example Code**: +--- -```python -from swarms import ( - Agent as SwarmsAgent, -) # Import the base Agent class from Swarms -from griptape.structures import Agent as GriptapeAgent -from griptape.tools import ( - WebScraperTool, - FileManagerTool, - PromptSummaryTool, -) +### Star Swarm -# Create a custom agent class that inherits from SwarmsAgent -class GriptapeSwarmsAgent(SwarmsAgent): - def __init__(self, name: str, system_prompt: str: str, *args, **kwargs): - super().__init__(agent_name=name, system_prompt=system_prompt) - # Initialize the Griptape agent with its tools - self.agent = GriptapeAgent( - input="Load {{ args[0] }}, summarize it, and store it in a file called {{ args[1] }}.", - tools=[ - WebScraperTool(off_prompt=True), - PromptSummaryTool(off_prompt=True), - FileManagerTool(), - ], - *args, - **kwargs, - ) +**Overview:** +A Star Swarm architecture features a central agent that coordinates the activities of several peripheral agents. The central agent assigns tasks to the peripheral agents and aggregates their results. - # Override the run method to take a task and execute it using the Griptape agent - def run(self, task: str) -> str: - # Extract URL and filename from task - url, filename = task.split(",") # Example task string: "https://example.com, output.txt" - # Execute the Griptape agent - result = self.agent.run(url.strip(), filename.strip()) - # Return the final result as a string - return str(result) +**Use-Cases:** +- Centralized decision-making processes. +- Scenarios requiring a central authority to coordinate multiple workers. -# Example usage: -griptape_swarms_agent = GriptapeSwarmsAgent() -output = griptape_swarms_agent.run("https://griptape.ai, griptape.txt") -print(output) +```mermaid +graph TD + A[Central Agent] --> B1[Peripheral Agent 1] + A --> B2[Peripheral Agent 2] + A --> B3[Peripheral Agent 3] + A --> B4[Peripheral Agent 4] ``` - --- -## Best Practices - -1. **Test Extensively:** - Validate your agent with various task inputs to ensure it performs as expected under different conditions. +### Mesh Swarm -2. **Follow the Single Responsibility Principle:** - Design each agent to focus on a specific task or role, ensuring clarity and modularity in implementation. +**Overview:** +A Mesh Swarm architecture allows for a fully connected network of agents where each agent can communicate with any other agent. This setup provides high flexibility and redundancy. -3. **Log Actions:** - Include detailed logging within the `run` method to capture key actions, inputs, and results for debugging and monitoring. +**Use-Cases:** +- Complex systems requiring high fault tolerance and redundancy. -4. **Use Open-Source Contributions:** - Contribute your custom agents to the Swarms repository at [https://github.com/kyegomez/swarms](https://github.com/kyegomez/swarms). Sharing your innovations helps advance the ecosystem and encourages collaboration. +- Scenarios involving dynamic and frequent communication between agents. -5. **Iterate and Refactor:** - Continuously improve your agents based on feedback, performance evaluations, and new requirements to maintain relevance and functionality. +```mermaid +graph TD + A1[Agent 1] --> A2[Agent 2] + A1 --> A3[Agent 3] + A1 --> A4[Agent 4] + A2 --> A3 + A2 --> A4 + A3 --> A4 +``` --- -## Conclusion +### Cascade Swarm -By following these guidelines, you can create powerful and flexible agents tailored to specific tasks. Leveraging inheritance from the `Agent` class ensures compatibility and standardization across swarms. Emphasize modularity, thorough testing, and clear documentation to build agents that are robust, scalable, and easy to integrate. Collaborate with the community by submitting your innovative agents to the Swarms repository, contributing to a growing ecosystem of intelligent solutions. With a well-designed agent, you are equipped to tackle diverse challenges efficiently and effectively. +**Overview:** +A Cascade Swarm architecture involves a chain of agents where each agent triggers the next one in a cascade effect. This is useful for scenarios where tasks need to be processed in stages, and each stage initiates the next. +**Use-Cases:** +- Multi-stage processing tasks such as data transformation pipelines. +- Event-driven architectures where one event triggers subsequent actions. --------------------------------------------------- +```mermaid +graph TD + A[Trigger Agent] --> B[Agent 1] + B --> C[Agent 2] + C --> D[Agent 3] + D --> E[Agent 4] +``` -# File: swarms/agents/openai_assistant.md +--- -# OpenAI Assistant +### Hybrid Swarm -The OpenAI Assistant class provides a wrapper around OpenAI's Assistants API, integrating it with the swarms framework. +**Overview:** +A Hybrid Swarm architecture combines elements of various architectures to suit specific needs. It might integrate hierarchical and parallel components, or mix sequential and round robin patterns. -## Overview +**Use-Cases:** +- Complex workflows requiring a mix of different processing strategies. -The `OpenAIAssistant` class allows you to create and interact with OpenAI Assistants, providing a simple interface for: +- Custom scenarios tailored to specific operational requirements. -- Creating assistants with specific roles and capabilities -- Adding custom functions that the assistant can call -- Managing conversation threads -- Handling tool calls and function execution -- Getting responses from the assistant +```mermaid +graph TD + A[Root Agent] --> B1[Sub-Agent 1] + A --> B2[Sub-Agent 2] + B1 --> C1[Parallel Agent 1] + B1 --> C2[Parallel Agent 2] + B2 --> C3[Sequential Agent 1] + C3 --> C4[Sequential Agent 2] + C3 --> C5[Sequential Agent 3] +``` -## Insstallation +--- -```bash -pip install swarms -``` -## Basic Usage +These swarm architectures provide different models for organizing and orchestrating large language models (LLMs) to perform various tasks efficiently. Depending on the specific requirements of your project, you can choose the appropriate architecture or even combine elements from multiple architectures to create a hybrid solution. -```python +-------------------------------------------------- -from swarms import OpenAIAssistant +# File: swarms\concept\how_to_choose_swarms.md -#Create an assistant -assistant = OpenAIAssistant( - name="Math Tutor", - instructions="You are a helpful math tutor.", - model="gpt-4o", - tools=[{"type": "code_interpreter"}] -) +# Choosing the Right Swarm for Your Business Problem -#Run a Task -response = assistant.run("Solve the equation: 3x + 11 = 14") -print(response) +Depending on the complexity and nature of your problem, different swarm configurations can be more effective in achieving optimal performance. This guide provides a detailed explanation of when to use each swarm type, including their strengths and potential drawbacks. -# Continue the conversation in the same thread -follow_up = assistant.run("Now explain how you solved it") -print(follow_up) -``` +## Swarm Types Overview -## Function Calling +- **MajorityVoting**: A swarm structure where agents vote on an outcome, and the majority decision is taken as the final result. +- **AgentRearrange**: Provides the foundation for both sequential and parallel swarms. +- **RoundRobin**: Agents take turns handling tasks in a cyclic manner. +- **Mixture of Agents**: A heterogeneous swarm where agents with different capabilities are combined. +- **GraphWorkflow**: Agents collaborate in a directed acyclic graph (DAG) format. +- **GroupChat**: Agents engage in a chat-like interaction to reach decisions. +- **AgentRegistry**: A centralized registry where agents are stored, retrieved, and invoked. +- **SpreadsheetSwarm**: A swarm designed to manage tasks at scale, tracking agent outputs in a structured format (e.g., CSV files). -The assistant supports custom function integration: +--- -```python +## MajorityVoting Swarm -def get_weather(location: str, unit: str = "celsius") -> str: - # Mock weather function - return f"The weather in {location} is 22 degrees {unit}" +### Use-Case +MajorityVoting is ideal for scenarios where accuracy is paramount, and the decision must be determined from multiple perspectives. For instance, choosing the best marketing strategy where various marketing agents vote on the highest predicted performance. -# Add function to assistant -assistant.add_function( - description="Get the current weather in a location", - parameters={ - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "City name" - }, - "unit": { - "type": "string", - "enum": ["celsius", "fahrenheit"], - "default": "celsius" - } - }, - "required": ["location"] - } -) -``` +### Advantages +- Ensures robustness in decision-making by leveraging multiple agents. +- Helps eliminate outliers or faulty agent decisions. -## API Reference +### Warnings +!!! warning + Majority voting can be slow if too many agents are involved. Ensure that your swarm size is manageable for real-time decision-making. -### Constructor +--- -```python -OpenAIAssistant( - name: str, - instructions: Optional[str] = None, - model: str = "gpt-4o", - tools: Optional[List[Dict[str, Any]]] = None, - file_ids: Optional[List[str]] = None, - metadata: Optional[Dict[str, Any]] = None, - functions: Optional[List[Dict[str, Any]]] = None, -) -``` +## AgentRearrange (Sequential and Parallel) -### Methods +### Sequential Swarm Use-Case +For linear workflows where each task depends on the outcome of the previous task, such as processing legal documents step by step through a series of checks and validations. -#### run(task: str) -> str -Sends a task to the assistant and returns its response. The conversation thread is maintained between calls. +### Parallel Swarm Use-Case +For tasks that can be executed concurrently, such as batch processing customer data in marketing campaigns. Parallel swarms can significantly reduce processing time by dividing tasks across multiple agents. -#### add_function(func: Callable, description: str, parameters: Dict[str, Any]) -> None -Adds a callable function that the assistant can use during conversations. +### Notes +!!! note + Sequential swarms are slower but ensure strict task dependencies are respected. Parallel swarms are faster but require careful management of task interdependencies. -#### add_message(content: str, file_ids: Optional[List[str]] = None) -> None -Adds a message to the current conversation thread. +--- -## Error Handling +## RoundRobin Swarm -The assistant implements robust error handling: -- Retries on rate limits -- Graceful handling of API errors -- Clear error messages for debugging -- Status monitoring for runs and completions +### Use-Case +For balanced task distribution where agents need to handle tasks evenly. An example would be assigning customer support tickets to agents in a cyclic manner, ensuring no single agent is overloaded. -## Best Practices +### Advantages +- Fair and even distribution of tasks. +- Simple and effective for balanced workloads. -1. Thread Management - - Use the same assistant instance for related conversations - - Create new instances for unrelated tasks - - Monitor thread status during long-running operations +### Warnings +!!! warning + Round-robin may not be the best choice when some agents are more competent than others, as it can assign tasks equally regardless of agent performance. -2. Function Integration - - Keep functions simple and focused - - Provide clear descriptions and parameter schemas - - Handle errors gracefully in custom functions - - Test functions independently before integration +--- -3. Performance - - Reuse assistant instances when possible - - Monitor and handle rate limits appropriately - - Use appropriate polling intervals for status checks - - Consider implementing timeouts for long-running operations +## Mixture of Agents -## References +### Use-Case +Ideal for complex problems that require diverse skills. For example, a financial forecasting problem where some agents specialize in stock data, while others handle economic factors. -- [OpenAI Assistants API Documentation](https://platform.openai.com/docs/assistants/overview) -- [OpenAI Function Calling Guide](https://platform.openai.com/docs/guides/function-calling) -- [OpenAI Rate Limits](https://platform.openai.com/docs/guides/rate-limits) +### Notes +!!! note + A mixture of agents is highly flexible and can adapt to various problem domains. However, be mindful of coordination overhead. +--- +## GraphWorkflow Swarm +### Use-Case +This swarm structure is suited for tasks that can be broken down into a series of dependencies but are not strictly linear, such as an AI-driven software development pipeline where one agent handles front-end development while another handles back-end concurrently. +### Advantages +- Provides flexibility for managing dependencies. +- Agents can work on different parts of the problem simultaneously. --------------------------------------------------- +### Warnings +!!! warning + GraphWorkflow requires clear definition of task dependencies, or it can lead to execution issues and delays. -# File: swarms/agents/reasoning_agent_router.md +--- -# ReasoningAgentRouter Documentation +## GroupChat Swarm -The ReasoningAgentRouter is a sophisticated agent routing system that enables dynamic selection and execution of different reasoning strategies based on the task requirements. It provides a flexible interface to work with multiple reasoning approaches including Reasoning Duo, Self-Consistency, and Iterative Reflective Expansion (IRE). +### Use-Case +For real-time collaborative decision-making. For instance, agents could participate in group chat for negotiating contracts, each contributing their expertise and adjusting responses based on the collective discussion. -## Architecture +### Advantages +- Facilitates highly interactive problem-solving. +- Ideal for dynamic and unstructured problems. -```mermaid -graph TD - Task[Task Input] --> Router[ReasoningAgentRouter] - Router --> SelectSwarm{Select Swarm Type} - SelectSwarm -->|Reasoning Duo| RD[ReasoningDuo] - SelectSwarm -->|Self Consistency| SC[SelfConsistencyAgent] - SelectSwarm -->|IRE| IRE[IterativeReflectiveExpansion] - RD --> Output[Task Output] - SC --> Output - IRE --> Output -``` +### Warnings +!!! warning + High communication overhead between agents may slow down decision-making in large swarms. -## Class: ReasoningAgentRouter +--- -### Arguments +## AgentRegistry Swarm -| Argument | Type | Default | Description | -|----------|------|---------|-------------| -| agent_name | str | "reasoning_agent" | Name identifier for the agent | -| description | str | "A reasoning agent..." | Description of the agent's capabilities | -| model_name | str | "gpt-4o-mini" | The underlying language model to use | -| system_prompt | str | "You are a helpful..." | System prompt for the agent | -| max_loops | int | 1 | Maximum number of reasoning loops | -| swarm_type | agent_types | "reasoning_duo" | Type of reasoning swarm to use | -| num_samples | int | 1 | Number of samples for self-consistency | -| output_type | OutputType | "dict" | Format of the output | +### Use-Case +For dynamically managing agents based on the problem domain. An AgentRegistry is useful when new agents can be added or removed as needed, such as adding new machine learning models for an evolving recommendation engine. -### Methods +### Notes +!!! note + AgentRegistry is a flexible solution but introduces additional complexity when agents need to be discovered and registered on the fly. -| Method | Description | -|--------|-------------| -| select_swarm() | Selects and initializes the appropriate reasoning swarm based on specified type | -| run(task: str) | Executes the selected swarm's reasoning process on the given task | -| batched_run(tasks: List[str]) | Executes the reasoning process on a batch of tasks | +--- -### Swarm Types +## SpreadsheetSwarm -1. **ReasoningDuo** - - Uses two agents working together - - One for reasoning, one for execution - - Best for tasks requiring both analysis and action +### Use-Case +When dealing with massive-scale data or agent outputs that need to be stored and managed in a tabular format. SpreadsheetSwarm is ideal for businesses handling thousands of agent outputs, such as large-scale marketing analytics or financial audits. -2. **SelfConsistencyAgent** - - Generates multiple samples - - Ensures consistency across reasoning paths - - Ideal for tasks requiring high reliability +### Advantages +- Provides structure and order for managing massive amounts of agent outputs. +- Outputs are easily saved and tracked in CSV files. -3. **IterativeReflectiveExpansion (IRE)** - - Uses iterative refinement - - Reflects on and improves reasoning paths - - Best for complex problem-solving +### Warnings +!!! warning + Ensure the correct configuration of agents in SpreadsheetSwarm to avoid data mismatches and inconsistencies when scaling up to thousands of agents. -## Usage Examples +--- -### Basic Usage +## Final Thoughts -```python -from swarms.agents.reasoning_agents import ReasoningAgentRouter +The choice of swarm depends on: -# Initialize the router -router = ReasoningAgentRouter( - agent_name="reasoning-agent", - description="A reasoning agent that can answer questions and help with tasks.", - model_name="gpt-4o-mini", - system_prompt="You are a helpful assistant that can answer questions and help with tasks.", - max_loops=1, - swarm_type="self-consistency", - num_samples=1, - output_type="list" -) +1. **Nature of the task**: Whether it's sequential or parallel. -# Run a single task -result = router.run("What is the best approach to solve this problem?") -``` +2. **Problem complexity**: Simple problems might benefit from RoundRobin, while complex ones may need GraphWorkflow or Mixture of Agents. -### Batch Processing +3. **Scale of execution**: For large-scale tasks, Swarms like SpreadsheetSwarm or MajorityVoting provide scalability with structured outputs. -```python -# Process multiple tasks -tasks = [ - "What is the optimal solution for X?", - "How should we approach problem Y?" -] -results = router.batched_run(tasks) -``` +When integrating agents in a business workflow, it's crucial to balance task complexity, agent capabilities, and scalability to ensure the optimal swarm architecture. -### Using Different Swarm Types -#### ReasoningDuo +-------------------------------------------------- -```python -router = ReasoningAgentRouter( - swarm_type="reasoning-duo", - model_name="gpt-4o-mini" -) -``` +# File: swarms\concept\philosophy.md -#### Self-Consistency +# Our Philosophy: Simplifying Multi-Agent Collaboration Through Readable Code and Performance Optimization -```python -router = ReasoningAgentRouter( - swarm_type="self-consistency", - num_samples=3, - model_name="gpt-4o-mini" -) -``` +Our mission is to streamline multi-agent collaboration by emphasizing simplicity, readability, and performance in our codebase. This document outlines our core tactics: -#### IRE +- **Readable Code with Type Annotations, Documentation, and Logging** +- **Bleeding-Edge Performance via Concurrency and Parallelism** +- **Simplified Abstractions for Multi-Agent Collaboration** -```python -router = ReasoningAgentRouter( - swarm_type="ire", - max_loops=5, - model_name="gpt-4o-mini" -) -``` +By adhering to these principles, we aim to make our systems more maintainable, scalable, and efficient, facilitating easier integration and collaboration among developers and agents alike. -## Best Practices +--- -1. **Swarm Type Selection** - - Use ReasoningDuo for tasks requiring both analysis and action - - Use SelfConsistency for tasks requiring high reliability - - Use IRE for complex problem-solving requiring iterative refinement +## 1. Emphasizing Readable Code -2. **Performance Optimization** - - Adjust max_loops based on task complexity - - Increase num_samples for higher reliability - - Choose appropriate model_name based on task requirements +Readable code is the cornerstone of maintainable and scalable systems. It ensures that developers can easily understand, modify, and extend the codebase. -3. **Output Handling** - - Use appropriate output_type for your needs - - Process batched results appropriately - - Handle errors gracefully +### 1.1 Use of Type Annotations -## Error Handling +Type annotations enhance code readability and catch errors early in the development process. -The ReasoningAgentRouter includes built-in error handling for: -- Invalid swarm types -- Model execution failures -- Task processing errors +```python +def process_data(data: List[str]) -> Dict[str, int]: + result = {} + for item in data: + result[item] = len(item) + return result +``` -## Limitations +### 1.2 Code Style Guidelines -1. Processing time increases with: - - Higher num_samples - - Larger max_loops - - More complex tasks +Adhering to consistent code style guidelines, such as PEP 8 for Python, ensures uniformity across the codebase. -2. Model-specific limitations based on: - - Token limits - - Model capabilities - - API rate limits +- **Indentation:** Use 4 spaces per indentation level. +- **Variable Naming:** Use `snake_case` for variables and functions. +- **Class Naming:** Use `PascalCase` for class names. -## Contributing +### 1.3 Importance of Documentation -When extending the ReasoningAgentRouter: -1. Follow the existing swarm interface -2. Add comprehensive tests -3. Update documentation -4. Maintain error handling +Comprehensive documentation helps new developers understand the purpose and functionality of code modules. +```python +def fetch_user_profile(user_id: str) -> UserProfile: + """ + Fetches the user profile from the database. --------------------------------------------------- + Args: + user_id (str): The unique identifier of the user. -# File: swarms/agents/reasoning_duo.md + Returns: + UserProfile: An object containing user profile data. + """ + # Function implementation +``` -# ReasoningDuo +### 1.4 Consistent Naming Conventions -The ReasoningDuo class implements a dual-agent reasoning system that combines a reasoning agent and a main agent to provide well-thought-out responses to complex tasks. This architecture enables more robust and reliable outputs by separating the reasoning process from the final response generation. +Consistent naming reduces confusion and makes the code self-explanatory. +- **Functions:** Should be verbs (e.g., `calculate_total`). +- **Variables:** Should be nouns (e.g., `total_amount`). +- **Constants:** Should be uppercase (e.g., `MAX_RETRIES`). -## Class Overview +--- -### Constructor Parameters +## 2. Effective Logging Practices -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| model_name | str | "reasoning-agent-01" | Name identifier for the reasoning agent | -| description | str | "A highly intelligent..." | Description of the reasoning agent's capabilities | -| model_names | list[str] | ["gpt-4o-mini", "gpt-4o"] | Model names for reasoning and main agents | -| system_prompt | str | "You are a helpful..." | System prompt for the main agent | +Logging is essential for debugging and monitoring the health of applications. -### Methods +### 2.1 Why Logging is Important -| Method | Parameters | Returns | Description | -|--------|------------|---------|-------------| -| run | task: str | str | Processes a single task through both agents | -| batched_run | tasks: List[str] | List[str] | Processes multiple tasks sequentially | +- **Debugging:** Helps identify issues during development and after deployment. +- **Monitoring:** Provides insights into the system's behavior in real-time. +- **Audit Trails:** Keeps a record of events for compliance and analysis. +### 2.2 Best Practices for Logging +- **Use Appropriate Log Levels:** DEBUG, INFO, WARNING, ERROR, CRITICAL. +- **Consistent Log Formatting:** Include timestamps, log levels, and messages. +- **Avoid Sensitive Information:** Do not log passwords or personal data. -## Quick Start +### 2.3 Logging Examples ```python -from swarms.agents.reasoning_duo import ReasoningDuo - -# Initialize the ReasoningDuo -duo = ReasoningDuo( - model_name="reasoning-agent-01", - model_names=["gpt-4o-mini", "gpt-4o"] -) +import logging -# Run a single task -result = duo.run("Explain the concept of gravitational waves") +logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s:%(message)s') -# Run multiple tasks -tasks = [ - "Calculate compound interest for $1000 over 5 years", - "Explain quantum entanglement" -] -results = duo.batched_run(tasks) +def connect_to_service(url: str) -> bool: + logging.debug(f"Attempting to connect to {url}") + try: + # Connection logic + logging.info(f"Successfully connected to {url}") + return True + except ConnectionError as e: + logging.error(f"Connection failed to {url}: {e}") + return False ``` -## Examples - -### 1. Mathematical Analysis +--- -```python -duo = ReasoningDuo() +## 3. Achieving Bleeding-Edge Performance -# Complex mathematical problem -math_task = """ -Solve the following differential equation: -dy/dx + 2y = x^2, y(0) = 1 -""" +Performance is critical, especially when dealing with multiple agents and large datasets. -solution = duo.run(math_task) -``` +### 3.1 Concurrency and Parallelism -### 2. Physics Problem +Utilizing concurrency and parallelism can significantly improve performance. -```python -# Quantum mechanics problem -physics_task = """ -Calculate the wavelength of an electron with kinetic energy of 50 eV -using the de Broglie relationship. -""" +- **Concurrency:** Dealing with multiple tasks by managing multiple threads. +- **Parallelism:** Executing multiple tasks simultaneously on multiple CPU cores. -result = duo.run(physics_task) -``` +### 3.2 Asynchronous Programming -### 3. Financial Analysis +Asynchronous programming allows for non-blocking operations, leading to better resource utilization. ```python -# Complex financial analysis -finance_task = """ -Calculate the Net Present Value (NPV) of a project with: -- Initial investment: $100,000 -- Annual cash flows: $25,000 for 5 years -- Discount rate: 8% -""" +import asyncio -analysis = duo.run(finance_task) +async def fetch_data(endpoint: str) -> dict: + async with aiohttp.ClientSession() as session: + async with session.get(endpoint) as response: + return await response.json() + +async def main(): + endpoints = ['https://api.example.com/data1', 'https://api.example.com/data2'] + tasks = [fetch_data(url) for url in endpoints] + results = await asyncio.gather(*tasks) + print(results) + +asyncio.run(main()) ``` -## Advanced Usage +### 3.3 Utilizing Modern Hardware Capabilities -### Customizing Agent Behavior +Leverage multi-core processors and GPUs for computationally intensive tasks. -You can customize both agents by modifying their initialization parameters: +- **Multi-threading:** Use threads for I/O-bound tasks. +- **Multi-processing:** Use processes for CPU-bound tasks. +- **GPU Acceleration:** Utilize GPUs for tasks like machine learning model training. + +### 3.4 Code Example: Parallel Processing ```python -duo = ReasoningDuo( - model_name="custom-reasoning-agent", - description="Specialized financial analysis agent", - model_names=["gpt-4o-mini", "gpt-4o"], - system_prompt="You are a financial expert AI assistant..." -) +from concurrent.futures import ThreadPoolExecutor + +def process_item(item): + # Processing logic + return result + +items = [1, 2, 3, 4, 5] +with ThreadPoolExecutor(max_workers=5) as executor: + results = list(executor.map(process_item, items)) ``` -### Batch Processing with Progress Tracking +--- -```python -tasks = [ - "Analyze market trends for tech stocks", - "Calculate risk metrics for a portfolio", - "Forecast revenue growth" -] +## 4. Simplifying Multi-Agent Collaboration -# Process multiple tasks with logging -results = duo.batched_run(tasks) -``` +Simplifying the abstraction of multi-agent collaboration makes it accessible and manageable. -## Implementation Details +### 4.1 Importance of Simple Abstractions -The ReasoningDuo uses a two-stage process: +- **Ease of Use:** Simple interfaces make it easier for developers to integrate agents. +- **Maintainability:** Reduces complexity, making the codebase easier to maintain. +- **Scalability:** Simple abstractions can be extended without significant overhauls. -1. **Reasoning Stage**: The reasoning agent analyzes the task and develops a structured approach -2. **Execution Stage**: The main agent uses the reasoning output to generate the final response +### 4.2 Standardizing Agent Interfaces -### Internal Architecture +Every agent should adhere to a standard interface for consistency. -``` -Task Input → Reasoning Agent → Structured Analysis → Main Agent → Final Output -``` +#### 4.2.1 Agent Base Class -## Best Practices +```python +from abc import ABC, abstractmethod -1. **Task Formulation** - - Be specific and clear in task descriptions - - Include relevant context and constraints - - Break complex problems into smaller subtasks +class BaseAgent(ABC): + @abstractmethod + def run(self, task: str) -> Any: + pass -2. **Performance Optimization** - - Use batched_run for multiple related tasks - - Monitor agent outputs for consistency - - Adjust model parameters based on task complexity + def __call__(self, task: str) -> Any: + return self.run(task) -## Error Handling + @abstractmethod + async def arun(self, task: str) -> Any: + pass +``` -The ReasoningDuo includes built-in logging using the `loguru` library: +#### 4.2.2 Example Agent Implementation ```python -from loguru import logger +class DataProcessingAgent(BaseAgent): + def run(self, task: str) -> str: + # Synchronous processing logic + return f"Processed {task}" -# Logs are automatically generated for each task -logger.info("Task processing started") + async def arun(self, task: str) -> str: + # Asynchronous processing logic + return f"Processed {task} asynchronously" ``` -## Limitations - -- Processing time may vary based on task complexity -- Model response quality depends on input clarity -- Resource usage scales with batch size +#### 4.2.3 Usage Example +```python +agent = DataProcessingAgent() --------------------------------------------------- +# Synchronous call +result = agent.run("data_task") +print(result) # Output: Processed data_task -# File: swarms/agents/reflexion_agent.md +# Asynchronous call +async def main(): + result = await agent.arun("data_task") + print(result) # Output: Processed data_task asynchronously -# ReflexionAgent +asyncio.run(main()) +``` -The ReflexionAgent is an advanced AI agent that implements the Reflexion framework to improve through self-reflection. It follows a process of acting on tasks, evaluating its performance, generating self-reflections, and using these reflections to improve future responses. +### 4.3 Mermaid Diagram: Agent Interaction -## Overview +```mermaid +sequenceDiagram + participant User + participant AgentA + participant AgentB + participant AgentC -The ReflexionAgent consists of three specialized sub-agents: -- **Actor**: Generates initial responses to tasks -- **Evaluator**: Critically assesses responses against quality criteria -- **Reflector**: Generates self-reflections to improve future responses + User->>AgentA: run(task) + AgentA-->>AgentB: arun(sub_task) + AgentB-->>AgentC: run(sub_sub_task) + AgentC-->>AgentB: result_sub_sub_task + AgentB-->>AgentA: result_sub_task + AgentA-->>User: final_result +``` -## Initialization +*Agents collaborating to fulfill a user's task.* -```python -from swarms.agents import ReflexionAgent +### 4.4 Simplified Collaboration Workflow -agent = ReflexionAgent( - agent_name="reflexion-agent", - system_prompt="...", # Optional custom system prompt - model_name="openai/o1", - max_loops=3, - memory_capacity=100 -) +```mermaid +flowchart TD + UserRequest["User Request"] --> Agent1["Agent 1"] + Agent1 -->|"run(task)"| Agent2["Agent 2"] + Agent2 -->|"arun(task)"| Agent3["Agent 3"] + Agent3 -->|"result"| Agent2 + Agent2 -->|"result"| Agent1 + Agent1 -->|"result"| UserResponse["User Response"] ``` -### Parameters +*Workflow demonstrating how agents process a task collaboratively.* -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `agent_name` | `str` | `"reflexion-agent"` | Name of the agent | -| `system_prompt` | `str` | `REFLEXION_PROMPT` | System prompt for the agent | -| `model_name` | `str` | `"openai/o1"` | Model name for generating responses | -| `max_loops` | `int` | `3` | Maximum number of reflection iterations per task | -| `memory_capacity` | `int` | `100` | Maximum capacity of long-term memory | +--- -## Methods +## 5. Bringing It All Together -### act +By integrating these principles, we create a cohesive system where agents can efficiently collaborate while maintaining code quality and performance. -Generates a response to the given task using the actor agent. +### 5.1 Example: Multi-Agent System + +#### 5.1.1 Agent Definitions ```python -response = agent.act(task: str, relevant_memories: List[Dict[str, Any]] = None) -> str -``` +class AgentA(BaseAgent): + def run(self, task: str) -> str: + # Agent A processing + return f"AgentA processed {task}" -| Parameter | Type | Description | -|-----------|------|-------------| -| `task` | `str` | The task to respond to | -| `relevant_memories` | `List[Dict[str, Any]]` | Optional relevant past memories to consider | + async def arun(self, task: str) -> str: + # Agent A asynchronous processing + return f"AgentA processed {task} asynchronously" -### evaluate +class AgentB(BaseAgent): + def run(self, task: str) -> str: + # Agent B processing + return f"AgentB processed {task}" -Evaluates the quality of a response to a task. + async def arun(self, task: str) -> str: + # Agent B asynchronous processing + return f"AgentB processed {task} asynchronously" +``` + +#### 5.1.2 Orchestrator Agent ```python -evaluation, score = agent.evaluate(task: str, response: str) -> Tuple[str, float] +class OrchestratorAgent(BaseAgent): + def __init__(self): + self.agent_a = AgentA() + self.agent_b = AgentB() + + def run(self, task: str) -> str: + result_a = self.agent_a.run(task) + result_b = self.agent_b.run(task) + return f"Orchestrated results: {result_a} & {result_b}" + + async def arun(self, task: str) -> str: + result_a = await self.agent_a.arun(task) + result_b = await self.agent_b.arun(task) + return f"Orchestrated results: {result_a} & {result_b}" ``` -| Parameter | Type | Description | -|-----------|------|-------------| -| `task` | `str` | The original task | -| `response` | `str` | The response to evaluate | +#### 5.1.3 Execution -Returns: -- `evaluation`: Detailed feedback on the response -- `score`: Numerical score between 0 and 1 +```python +orchestrator = OrchestratorAgent() -### reflect +# Synchronous execution +result = orchestrator.run("task1") +print(result) +# Output: Orchestrated results: AgentA processed task1 & AgentB processed task1 -Generates a self-reflection based on the task, response, and evaluation. +# Asynchronous execution +async def main(): + result = await orchestrator.arun("task1") + print(result) + # Output: Orchestrated results: AgentA processed task1 asynchronously & AgentB processed task1 asynchronously -```python -reflection = agent.reflect(task: str, response: str, evaluation: str) -> str +asyncio.run(main()) ``` -| Parameter | Type | Description | -|-----------|------|-------------| -| `task` | `str` | The original task | -| `response` | `str` | The generated response | -| `evaluation` | `str` | The evaluation feedback | - -### refine +### 5.2 Mermaid Diagram: Orchestrator Workflow -Refines the original response based on evaluation and reflection. +```mermaid +sequenceDiagram + participant User + participant Orchestrator + participant AgentA + participant AgentB -```python -refined_response = agent.refine( - task: str, - original_response: str, - evaluation: str, - reflection: str -) -> str + User->>Orchestrator: run(task) + Orchestrator->>AgentA: run(task) + Orchestrator->>AgentB: run(task) + AgentA-->>Orchestrator: result_a + AgentB-->>Orchestrator: result_b + Orchestrator-->>User: Orchestrated results ``` -| Parameter | Type | Description | -|-----------|------|-------------| -| `task` | `str` | The original task | -| `original_response` | `str` | The original response | -| `evaluation` | `str` | The evaluation feedback | -| `reflection` | `str` | The self-reflection | +*Orchestrator coordinating between Agent A and Agent B.* -### step +--- -Processes a single task through one iteration of the Reflexion process. +## 6. Conclusion -```python -result = agent.step( - task: str, - iteration: int = 0, - previous_response: str = None -) -> Dict[str, Any] -``` +Our philosophy centers around making multi-agent collaboration as simple and efficient as possible by: -| Parameter | Type | Description | -|-----------|------|-------------| -| `task` | `str` | The task to process | -| `iteration` | `int` | Current iteration number | -| `previous_response` | `str` | Response from previous iteration | +- **Writing Readable Code:** Through type annotations, consistent styling, and thorough documentation. +- **Implementing Effective Logging:** To aid in debugging and monitoring. +- **Optimizing Performance:** Leveraging concurrency, parallelism, and modern hardware capabilities. +- **Simplifying Abstractions:** Standardizing agent interfaces to `run`, `__call__`, and `arun` methods. -Returns a dictionary containing: -- `task`: The original task -- `response`: The generated response -- `evaluation`: The evaluation feedback -- `reflection`: The self-reflection -- `score`: Numerical score -- `iteration`: Current iteration number +By adhering to these principles, we create a robust foundation for scalable and maintainable systems that can adapt to evolving technological landscapes. -### run -Executes the Reflexion process for a list of tasks. -```python -results = agent.run( - tasks: List[str], - include_intermediates: bool = False -) -> List[Any] -``` +-------------------------------------------------- -| Parameter | Type | Description | -|-----------|------|-------------| -| `tasks` | `List[str]` | List of tasks to process | -| `include_intermediates` | `bool` | Whether to include intermediate iterations in results | +# File: swarms\concept\purpose\limits_of_individual_agents.md -Returns: -- If `include_intermediates=False`: List of final responses -- If `include_intermediates=True`: List of complete iteration histories +# The Limits of Individual Agents -## Example Usage +![Reliable Agents](docs/assets/img/reliabilitythrough.png) -```python -from swarms.agents import ReflexionAgent -# Initialize the Reflexion Agent -agent = ReflexionAgent( - agent_name="reflexion-agent", - model_name="openai/o1", - max_loops=3 -) +Individual agents have pushed the boundaries of what machines can learn and accomplish. However, despite their impressive capabilities, these agents face inherent limitations that can hinder their effectiveness in complex, real-world applications. This blog explores the critical constraints of individual agents, such as context window limits, hallucination, single-task threading, and lack of collaboration, and illustrates how multi-agent collaboration can address these limitations. In short, -# Example tasks -tasks = [ - "Explain quantum computing to a beginner.", - "Write a Python function to sort a list of dictionaries by a specific key." -] +- Context Window Limits +- Single Task Execution +- Hallucination +- No collaboration -# Run the agent -results = agent.run(tasks) -# Print results -for i, result in enumerate(results): - print(f"\nTask {i+1}: {tasks[i]}") - print(f"Response: {result}") -``` -## Memory System +#### Context Window Limits -The ReflexionAgent includes a sophisticated memory system (`ReflexionMemory`) that maintains both short-term and long-term memories of past experiences, reflections, and feedback. This system helps the agent learn from past interactions and improve its responses over time. +One of the most significant constraints of individual agents, particularly in the domain of language models, is the context window limit. This limitation refers to the maximum amount of information an agent can consider at any given time. For instance, many language models can only process a fixed number of tokens (words or characters) in a single inference, restricting their ability to understand and generate responses based on longer texts. This limitation can lead to a lack of coherence in longer compositions and an inability to maintain context in extended conversations or documents. -### Memory Features -- Short-term memory for recent interactions -- Long-term memory for important reflections and patterns -- Automatic memory management with capacity limits -- Relevance-based memory retrieval -- Similarity-based deduplication +#### Hallucination -## Best Practices +Hallucination in AI refers to the phenomenon where an agent generates information that is not grounded in the input data or real-world facts. This can manifest as making up facts, entities, or events that do not exist or are incorrect. Hallucinations pose a significant challenge in ensuring the reliability and trustworthiness of AI-generated content, particularly in critical applications such as news generation, academic research, and legal advice. -1. **Task Clarity**: Provide clear, specific tasks to get the best results -2. **Iteration Count**: Adjust `max_loops` based on task complexity (more complex tasks may benefit from more iterations) -3. **Memory Management**: Monitor memory usage and adjust `memory_capacity` as needed -4. **Model Selection**: Choose an appropriate model based on your specific use case and requirements -5. **Error Handling**: Implement proper error handling when using the agent in production +#### Single Task Threading +Individual agents are often designed to excel at specific tasks, leveraging their architecture and training data to optimize performance in a narrowly defined domain. However, this specialization can also be a drawback, as it limits the agent's ability to multitask or adapt to tasks that fall outside its primary domain. Single-task threading means an agent may excel in language translation but struggle with image recognition or vice versa, necessitating the deployment of multiple specialized agents for comprehensive AI solutions. --------------------------------------------------- +#### Lack of Collaboration -# File: swarms/agents/structured_outputs.md +Traditional AI agents operate in isolation, processing inputs and generating outputs independently. This isolation limits their ability to leverage diverse perspectives, share knowledge, or build upon the insights of other agents. In complex problem-solving scenarios, where multiple facets of a problem need to be addressed simultaneously, this lack of collaboration can lead to suboptimal solutions or an inability to tackle multifaceted challenges effectively. -# Agentic Structured Outputs +# The Elegant yet Simple Solution -Structured outputs help ensure that your agents return data in a consistent, predictable format that can be easily parsed and processed by your application. This is particularly useful when building complex applications that require standardized data handling. +- ## Multi-Agent Collaboration -## Schema Definition +Recognizing the limitations of individual agents, researchers and practitioners have explored the potential of multi-agent collaboration as a means to transcend these constraints. Multi-agent systems comprise several agents that can interact, communicate, and collaborate to achieve common goals or solve complex problems. This collaborative approach offers several advantages: -Structured outputs are defined using JSON Schema format. Here's the basic structure: +#### Overcoming Context Window Limits -```python -tools = [ - { - "type": "function", - "function": { - "name": "function_name", - "description": "Description of what the function does", - "parameters": { - "type": "object", - "properties": { - # Define your parameters here - }, - "required": [ - # List required parameters - ] - } - } - } -] -``` +By dividing a large task among multiple agents, each focusing on different segments of the problem, multi-agent systems can effectively overcome the context window limits of individual agents. For instance, in processing a long document, different agents could be responsible for understanding and analyzing different sections, pooling their insights to generate a coherent understanding of the entire text. -### Parameter Types +#### Mitigating Hallucination -The following parameter types are supported: +Through collaboration, agents can cross-verify facts and information, reducing the likelihood of hallucinations. If one agent generates a piece of information, other agents can provide checks and balances, verifying the accuracy against known data or through consensus mechanisms. -- `string`: Text values -- `number`: Numeric values -- `boolean`: True/False values -- `object`: Nested objects -- `array`: Lists or arrays -- `null`: Null values +#### Enhancing Multitasking Capabilities -## Implementation Steps +Multi-agent systems can tackle tasks that require a diverse set of skills by leveraging the specialization of individual agents. For example, in a complex project that involves both natural language processing and image analysis, one agent specialized in text can collaborate with another specialized in visual data, enabling a comprehensive approach to the task. -1. **Define Your Schema** - ```python - tools = [ - { - "type": "function", - "function": { - "name": "get_stock_price", - "description": "Retrieve stock price information", - "parameters": { - "type": "object", - "properties": { - "ticker": { - "type": "string", - "description": "Stock ticker symbol" - }, - # Add more parameters as needed - }, - "required": ["ticker"] - } - } - } - ] - ``` +#### Facilitating Collaboration and Knowledge Sharing -2. **Initialize the Agent** - ```python - from swarms import Agent - - agent = Agent( - agent_name="Your-Agent-Name", - agent_description="Agent description", - system_prompt="Your system prompt", - tools_list_dictionary=tools - ) - ``` +Multi-agent collaboration inherently encourages the sharing of knowledge and insights, allowing agents to learn from each other and improve their collective performance. This can be particularly powerful in scenarios where iterative learning and adaptation are crucial, such as dynamic environments or tasks that evolve over time. -3. **Run the Agent** - ```python - response = agent.run("Your query here") - ``` +### Conclusion -4. **Parse the Output** - ```python - from swarms.utils.str_to_dict import str_to_dict - - parsed_output = str_to_dict(response) - ``` +While individual AI agents have made remarkable strides in various domains, their inherent limitations necessitate innovative approaches to unlock the full potential of artificial intelligence. Multi-agent collaboration emerges as a compelling solution, offering a pathway to transcend individual constraints through collective intelligence. By harnessing the power of collaborative AI, we can address more complex, multifaceted problems, paving the way for more versatile, efficient, and effective AI systems in the future. -## Example Usage +-------------------------------------------------- -Here's a complete example using a financial agent: +# File: swarms\concept\purpose\why.md -```python -from dotenv import load_dotenv -from swarms import Agent -from swarms.utils.str_to_dict import str_to_dict +# The Swarms Framework: Orchestrating Agents for Enterprise Automation -# Load environment variables -load_dotenv() +In the rapidly evolving landscape of artificial intelligence (AI) and automation, a new paradigm is emerging: the orchestration of multiple agents working in collaboration to tackle complex tasks. This approach, embodied by the Swarms Framework, aims to address the fundamental limitations of individual agents and unlocks the true potential of AI-driven automation in enterprise operations. -# Define tools with structured output schema -tools = [ - { - "type": "function", - "function": { - "name": "get_stock_price", - "description": "Retrieve the current stock price and related information", - "parameters": { - "type": "object", - "properties": { - "ticker": { - "type": "string", - "description": "Stock ticker symbol" - }, - "include_history": { - "type": "boolean", - "description": "Include historical data" - }, - "time": { - "type": "string", - "format": "date-time", - "description": "Time for stock data" - } - }, - "required": ["ticker", "include_history", "time"] - } - } - } -] +Individual agents are plagued by the same issues: short term memory constraints, hallucinations, single task limitations, lack of collaboration, and cost inefficiences. -# Initialize agent -agent = Agent( - agent_name="Financial-Analysis-Agent", - agent_description="Personal finance advisor agent", - system_prompt="Your system prompt here", - max_loops=1, - tools_list_dictionary=tools -) +[Learn more here from a list of compiled agent papers](https://github.com/kyegomez/awesome-multi-agent-papers) -# Run agent -response = agent.run("What is the current stock price for AAPL?") +## The Purpose of Swarms: Overcoming Agent Limitations -# Parse structured output -parsed_data = str_to_dict(response) -``` +Individual agents, while remarkable in their own right, face several inherent challenges that hinder their ability to effectively automate enterprise operations at scale. These limitations include: -## Best Practices +1. Short-Term Memory Constraints +2. Hallucination and Factual Inconsistencies +3. Single-Task Limitations +4. Lack of Collaborative Capabilities +5. Cost Inefficiencies -1. **Schema Design** - - Keep schemas as simple as possible while meeting your needs - - Use clear, descriptive parameter names - - Include detailed descriptions for each parameter - - Specify all required parameters explicitly +By orchestrating multiple agents to work in concert, the Swarms Framework directly tackles these limitations, paving the way for more efficient, reliable, and cost-effective enterprise automation. -2. **Error Handling** - - Always validate the output format - - Implement proper error handling for parsing failures - - Use try-except blocks when converting strings to dictionaries +### Limitation 1: Short-Term Memory Constraints -3. **Performance** - - Minimize the number of required parameters - - Use appropriate data types for each parameter - - Consider caching parsed results if used frequently +Many AI agents, particularly those based on large language models, suffer from short-term memory constraints. These agents can effectively process and respond to prompts, but their ability to retain and reason over information across multiple interactions or tasks is limited. This limitation can be problematic in enterprise environments, where complex workflows often involve retaining and referencing contextual information over extended periods. -## Troubleshooting +The Swarms Framework addresses this limitation by leveraging the collective memory of multiple agents working in tandem. While individual agents may have limited short-term memory, their combined memory pool becomes significantly larger, enabling the retention and retrieval of contextual information over extended periods. This collective memory is facilitated by agents specializing in information storage and retrieval, such as those based on systems like Llama Index or Pinecone. -Common issues and solutions: +### Limitation 2: Hallucination and Factual Inconsistencies -1. **Invalid Output Format** - - Ensure your schema matches the expected output - - Verify all required fields are present - - Check for proper JSON formatting +Another challenge faced by many AI agents is the tendency to generate responses that may contain factual inconsistencies or hallucinations -- information that is not grounded in reality or the provided context. This issue can undermine the reliability and trustworthiness of automated systems, particularly in domains where accuracy and consistency are paramount. -2. **Parsing Errors** - - Use `str_to_dict()` for reliable string-to-dictionary conversion - - Validate input strings before parsing - - Handle potential parsing exceptions +The Swarms Framework mitigates this limitation by employing multiple agents with diverse knowledge bases and capabilities. By leveraging the collective intelligence of these agents, the framework can cross-reference and validate information, reducing the likelihood of hallucinations and factual inconsistencies. Additionally, specialized agents can be tasked with fact-checking and verification, further enhancing the overall reliability of the system. -3. **Missing Fields** - - Verify all required fields are defined in the schema - - Check if the agent is properly configured - - Review the system prompt for clarity +### Limitation 3: Single-Task Limitations +Most individual AI agents are designed and optimized for specific tasks or domains, limiting their ability to handle complex, multi-faceted workflows that often characterize enterprise operations. While an agent may excel at a particular task, such as natural language processing or data analysis, it may struggle with other aspects of a larger workflow, such as task coordination or decision-making. +The Swarms Framework overcomes this limitation by orchestrating a diverse ensemble of agents, each specializing in different tasks or capabilities. By intelligently combining and coordinating these agents, the framework can tackle complex, multi-threaded workflows that span various domains and task types. This modular approach allows for the seamless integration of new agents as they become available, enabling the continuous expansion and enhancement of the system's capabilities. --------------------------------------------------- +### Limitation 4: Lack of Collaborative Capabilities -# File: swarms/agents/third_party.md +Most AI agents are designed to operate independently, lacking the ability to effectively collaborate with other agents or coordinate their actions towards a common goal. This limitation can hinder the scalability and efficiency of automated systems, particularly in enterprise environments where tasks often require the coordination of multiple agents or systems. -# Swarms Framework: Integrating and Customizing Agent Libraries +The Swarms Framework addresses this limitation by introducing a layer of coordination and collaboration among agents. Through specialized coordination agents and communication protocols, the framework enables agents to share information, divide tasks, and synchronize their actions. This collaborative approach not only increases efficiency but also enables the emergence of collective intelligence, where the combined capabilities of multiple agents surpass the sum of their individual abilities. -Agent-based systems have emerged as a powerful paradigm for solving complex problems and automating tasks. +### Limitation 5: Cost Inefficiencies -The swarms framework offers a flexible and extensible approach to working with various agent libraries, allowing developers to create custom agents and integrate them seamlessly into their projects. +Running large AI models or orchestrating multiple agents can be computationally expensive, particularly in enterprise environments where scalability and cost-effectiveness are critical considerations. Inefficient resource utilization or redundant computations can quickly escalate costs, making widespread adoption of AI-driven automation financially prohibitive. -In this comprehensive guide, we'll explore the swarms framework, discuss agent handling, and demonstrate how to build custom agents using swarms. We'll also cover the integration of popular agent libraries such as Langchain, Griptape, CrewAI, and Autogen. +The Swarms Framework tackles this limitation by optimizing resource allocation and workload distribution among agents. By intelligently assigning tasks to the most appropriate agents and leveraging agent specialization, the framework minimizes redundant computations and improves overall resource utilization. Additionally, the framework can dynamically scale agent instances based on demand, ensuring that computational resources are allocated efficiently and costs are minimized. -## Table of Contents +## The Swarms Framework: A Holistic Approach to Enterprise Automation -1. [Introduction to the Swarms Framework](#introduction-to-the-swarms-framework) -2. [The Need for Wrappers](#the-need-for-wrappers) -3. [Building Custom Agents with Swarms](#building-custom-agents-with-swarms) -4. [Integrating Third-Party Agent Libraries](#integrating-third-party-agent-libraries) - - [Griptape Integration](#griptape-integration) - - [Langchain Integration](#langchain-integration) - - [CrewAI Integration](#crewai-integration) - - [Autogen Integration](#autogen-integration) -5. [Advanced Agent Handling Techniques](#advanced-agent-handling-techniques) -6. [Best Practices for Custom Agent Development](#best-practices-for-custom-agent-development) -7. [Future Directions and Challenges](#future-directions-and-challenges) -8. [Conclusion](#conclusion) +The Swarms Framework is a comprehensive solution that addresses the limitations of individual agents by orchestrating their collective capabilities. By integrating agents from various frameworks, including LangChain, AutoGPT, Llama Index, and others, the framework leverages the strengths of each agent while mitigating their individual weaknesses. -## 1. Introduction to the Swarms Framework +At its core, the Swarms Framework operates on the principle of multi-agent collaboration. By introducing specialized coordination agents and communication protocols, the framework enables agents to share information, divide tasks, and synchronize their actions towards a common goal. This collaborative approach not only increases efficiency but also enables the emergence of collective intelligence, where the combined capabilities of multiple agents surpass the sum of their individual abilities. -The swarms framework is a powerful and flexible system designed to facilitate the creation, management, and coordination of multiple AI agents. It provides a standardized interface for working with various agent types, allowing developers to leverage the strengths of different agent libraries while maintaining a consistent programming model. +The framework's architecture is modular and extensible, allowing for the seamless integration of new agents as they become available. This flexibility ensures that the system's capabilities can continuously expand and adapt to evolving enterprise needs and technological advancements. -At its core, the swarms framework is built around the concept of a parent `Agent` class, which serves as a foundation for creating custom agents and integrating third-party agent libraries. This approach offers several benefits: -1. **Consistency**: By wrapping different agent implementations with a common interface, developers can work with a unified API across various agent types. -2. **Extensibility**: The framework makes it easy to add new agent types or customize existing ones without affecting the overall system architecture. -3. **Interoperability**: Agents from different libraries can communicate and collaborate seamlessly within the swarms ecosystem. -4. **Scalability**: The standardized approach allows for easier scaling of agent-based systems, from simple single-agent applications to complex multi-agent swarms. +## Benefits of the Swarms Framework -## 2. The Need for Wrappers +The adoption of the Swarms Framework in enterprise environments offers numerous benefits: -As the field of AI and agent-based systems continues to grow, numerous libraries and frameworks have emerged, each with its own strengths and specialized features. While this diversity offers developers a wide range of tools to choose from, it also presents challenges in terms of integration and interoperability. +1. Increased Efficiency and Scalability +2. Improved Reliability and Accuracy +3. Adaptability and Continuous Improvement +4. Cost Optimization +5. Enhanced Security and Compliance -This is where the concept of wrappers becomes crucial. By creating wrappers around different agent libraries, we can: +## Increased Efficiency and Scalability -1. **Unify interfaces**: Standardize the way we interact with agents, regardless of their underlying implementation. -2. **Simplify integration**: Make it easier to incorporate new agent libraries into existing projects. -3. **Enable composition**: Allow for the creation of complex agent systems that leverage the strengths of multiple libraries. -4. **Facilitate maintenance**: Centralize the management of agent-related code and reduce the impact of library-specific changes. +By orchestrating the collective capabilities of multiple agents, the Swarms Framework enables the efficient execution of complex, multi-threaded workflows. Tasks can be parallelized and distributed across specialized agents, reducing bottlenecks and increasing overall throughput. Additionally, the framework's modular design and ability to dynamically scale agent instances based on demand ensure that the system can adapt to changing workloads and scale seamlessly as enterprise needs evolve. -In the context of the swarms framework, wrappers take the form of custom classes that inherit from the parent `Agent` class. These wrapper classes encapsulate the functionality of specific agent libraries while exposing a consistent interface that aligns with the swarms framework. +## Improved Reliability and Accuracy -## 3. Building Custom Agents with Swarms +The collaborative nature of the Swarms Framework reduces the risk of hallucinations and factual inconsistencies that can arise from individual agents. By leveraging the collective knowledge and diverse perspectives of multiple agents, the framework can cross-reference and validate information, enhancing the overall reliability and accuracy of its outputs. -To illustrate the process of building custom agents using the swarms framework, let's start with a basic example of creating a custom agent class: +Additionally, the framework's ability to incorporate specialized fact-checking and verification agents further strengthens the trustworthiness of the system's outcomes, ensuring that critical decisions and actions are based on accurate and reliable information. -```python -from swarms import Agent +## Adaptability and Continuous Improvement -class MyCustomAgent(Agent): - def __init__(self, *args, **kwargs): - super().__init__(*args, **kwargs) - # Custom initialization logic +The modular architecture of the Swarms Framework allows for the seamless integration of new agents as they become available, enabling the continuous expansion and enhancement of the system's capabilities. As new AI models, algorithms, or data sources emerge, the framework can readily incorporate them, ensuring that enterprise operations remain at the forefront of technological advancements. - def custom_method(self, *args, **kwargs): - # Implement custom logic here - pass +Furthermore, the framework's monitoring and analytics capabilities provide valuable insights into system performance, enabling the identification of areas for improvement and the optimization of agent selection, task assignments, and resource allocation strategies over time. - def run(self, task, *args, **kwargs): - # Customize the run method - response = super().run(task, *args, **kwargs) - # Additional custom logic - return response -``` +## Cost Optimization -This example demonstrates the fundamental structure of a custom agent class within the swarms framework. Let's break down the key components: +By intelligently orchestrating the collaboration of multiple agents, the Swarms Framework optimizes resource utilization and minimizes redundant computations. This efficient use of computational resources translates into cost savings, making the widespread adoption of AI-driven automation more financially viable for enterprises. -1. **Inheritance**: The class inherits from the `Agent` parent class, ensuring it adheres to the swarms framework's interface. +The framework's ability to dynamically scale agent instances based on demand further contributes to cost optimization, ensuring that resources are allocated only when needed and minimizing idle or underutilized instances. -2. **Initialization**: The `__init__` method calls the parent class's initializer and can include additional custom initialization logic. +## Enhanced Security and Compliance -3. **Custom methods**: You can add any number of custom methods to extend the agent's functionality. +In enterprise environments, ensuring the security and compliance of automated systems is paramount. The Swarms Framework addresses these concerns by incorporating robust security measures and compliance controls. -4. **Run method**: The `run` method is a key component of the agent interface. By overriding this method, you can customize how the agent processes tasks while still leveraging the parent class's functionality. +The framework's centralized Memory Manager component enables the implementation of access control mechanisms and data encryption, protecting sensitive information from unauthorized access or breaches. Additionally, the framework's modular design allows for the integration of specialized agents focused on compliance monitoring and auditing, ensuring that enterprise operations adhere to relevant regulations and industry standards. -To create more sophisticated custom agents, you can expand on this basic structure by adding features such as: +## Real-World Applications and Use Cases -- **State management**: Implement methods to manage the agent's internal state. -- **Communication protocols**: Define how the agent interacts with other agents in the swarm. -- **Learning capabilities**: Incorporate machine learning models or adaptive behaviors. -- **Specialized task handling**: Create methods for dealing with specific types of tasks or domains. +The Swarms Framework finds applications across a wide range of enterprise domains, enabling organizations to automate complex operations and streamline their workflows. Here are some examples of real-world use cases: -By leveraging these custom agent classes, developers can create highly specialized and adaptive agents tailored to their specific use cases while still benefiting from the standardized interface provided by the swarms framework. +1. Intelligent Process Automation (IPA) +2. Customer Service and Support +3. Fraud Detection and Risk Management +4. Supply Chain Optimization +5. Research and Development -## 4. Integrating Third-Party Agent Libraries +## Intelligent Process Automation (IPA) -One of the key strengths of the swarms framework is its ability to integrate with various third-party agent libraries. In this section, we'll explore how to create wrappers for popular agent libraries, including Griptape, Langchain, CrewAI, and Autogen. +In the realm of business process automation, the Swarms Framework can orchestrate agents to automate and optimize complex workflows spanning multiple domains and task types. By combining agents specialized in areas such as natural language processing, data extraction, decision-making, and task coordination, the framework can streamline and automate processes that traditionally required manual intervention or coordination across multiple systems. -### Griptape Integration +## Customer Service and Support -Griptape is a powerful library for building AI agents with a focus on composability and tool use. Let's create a wrapper for a Griptape agent: +The framework's ability to integrate agents with diverse capabilities, such as natural language processing, knowledge retrieval, and decision-making, makes it well-suited for automating customer service and support operations. Agents can collaborate to understand customer inquiries, retrieve relevant information from knowledge bases, and provide accurate and personalized responses, improving customer satisfaction and reducing operational costs. -```python -from typing import List, Optional +## Fraud Detection and Risk Management -from griptape.structures import Agent as GriptapeAgent -from griptape.tools import FileManager, TaskMemoryClient, WebScraper +In the financial and cybersecurity domains, the Swarms Framework can orchestrate agents specialized in data analysis, pattern recognition, and risk assessment to detect and mitigate fraudulent activities or security threats. By combining the collective intelligence of these agents, the framework can identify complex patterns and anomalies that may be difficult for individual agents to detect, enhancing the overall effectiveness of fraud detection and risk management strategies. -from swarms import Agent +## Supply Chain Optimization +The complexity of modern supply chains often requires the coordination of multiple systems and stakeholders. The Swarms Framework can integrate agents specialized in areas such as demand forecasting, inventory management, logistics optimization, and supplier coordination to streamline and optimize supply chain operations. By orchestrating the collective capabilities of these agents, the framework can identify bottlenecks, optimize resource allocation, and facilitate seamless collaboration among supply chain partners. -class GriptapeAgentWrapper(Agent): - """ - A wrapper class for the GriptapeAgent from the griptape library. - """ +## Research and Development - def __init__(self, name: str, tools: Optional[List] = None, *args, **kwargs): - """ - Initialize the GriptapeAgentWrapper. +In research and development environments, the Swarms Framework can accelerate innovation by enabling the collaboration of agents specialized in areas such as literature review, data analysis, hypothesis generation, and experiment design. By orchestrating these agents, the framework can facilitate the exploration of new ideas, identify promising research directions, and streamline the iterative process of scientific inquiry. - Parameters: - - name: The name of the agent. - - tools: A list of tools to be used by the agent. If not provided, default tools will be used. - - *args, **kwargs: Additional arguments to be passed to the parent class constructor. - """ - super().__init__(*args, **kwargs) - self.name = name - self.tools = tools or [ - WebScraper(off_prompt=True), - TaskMemoryClient(off_prompt=True), - FileManager() - ] - self.griptape_agent = GriptapeAgent( - input=f"I am {name}, an AI assistant. How can I help you?", - tools=self.tools - ) +# Conclusion - def run(self, task: str, *args, **kwargs) -> str: - """ - Run a task using the GriptapeAgent. +The Swarms Framework represents a paradigm shift in the field of enterprise automation, addressing the limitations of individual agents by orchestrating their collective capabilities. By integrating agents from various frameworks and enabling multi-agent collaboration, the Swarms Framework overcomes challenges such as short-term memory constraints, hallucinations, single-task limitations, lack of collaboration, and cost inefficiencies. - Parameters: - - task: The task to be performed by the agent. +Through its modular architecture, centralized coordination, and advanced monitoring and analytics capabilities, the Swarms Framework empowers enterprises to automate complex operations with increased efficiency, reliability, and adaptability. It unlocks the true potential of AI-driven automation, enabling organizations to stay ahead of the curve and thrive in an ever-evolving technological landscape. - Returns: - - The response from the GriptapeAgent as a string. - """ - response = self.griptape_agent.run(task, *args, **kwargs) - return str(response) +As the field of artificial intelligence continues to advance, the Swarms Framework stands as a robust and flexible solution, ready to embrace new developments and seamlessly integrate emerging agents and capabilities. By harnessing the power of collective intelligence, the framework paves the way for a future where enterprises can leverage the full potential of AI to drive innovation, optimize operations, and gain a competitive edge in their respective industries. - def add_tool(self, tool) -> None: - """ - Add a tool to the agent. +-------------------------------------------------- - Parameters: - - tool: The tool to be added. - """ - self.tools.append(tool) - self.griptape_agent = GriptapeAgent( - input=f"I am {self.name}, an AI assistant. How can I help you?", - tools=self.tools - ) +# File: swarms\concept\purpose\why_swarms.md -# Usage example -griptape_wrapper = GriptapeAgentWrapper("GriptapeAssistant") -result = griptape_wrapper.run("Load https://example.com, summarize it, and store it in a file called example_summary.txt.") -print(result) +# Why Swarms? -``` +The need for multiple agents to work together in artificial intelligence (AI) and particularly in the context of Large Language Models (LLMs) stems from several inherent limitations and challenges in handling complex, dynamic, and multifaceted tasks with single-agent systems. Collaborating with multiple agents offers a pathway to enhance reliability, computational efficiency, cognitive diversity, and problem-solving capabilities. This section delves into the rationale behind employing multi-agent systems and strategizes on overcoming the associated expenses, such as API bills and hosting costs. -This wrapper encapsulates the functionality of a Griptape agent while exposing it through the swarms framework's interface. It allows for easy customization of tools and provides a simple way to execute tasks using the Griptape agent. +### Why Multiple Agents Are Necessary -### Langchain Integration +#### 1. **Cognitive Diversity** -Langchain is a popular framework for developing applications powered by language models. Here's an example of how we can create a wrapper for a Langchain agent: +Different agents can bring varied perspectives, knowledge bases, and problem-solving approaches to a task. This diversity is crucial in complex problem-solving scenarios where a single approach might not be sufficient. Cognitive diversity enhances creativity, leading to innovative solutions and the ability to tackle a broader range of problems. -```python -from typing import List, Optional +#### 2. **Specialization and Expertise** -from langchain.agents import AgentExecutor, LLMSingleActionAgent, Tool -from langchain.chains import LLMChain -from langchain_community.llms import OpenAI -from langchain.prompts import StringPromptTemplate -from langchain.tools import DuckDuckGoSearchRun +In many cases, tasks are too complex for a single agent to handle efficiently. By dividing the task among multiple specialized agents, each can focus on a segment where it excels, thereby increasing the overall efficiency and effectiveness of the solution. This approach leverages the expertise of individual agents to achieve superior performance in tasks that require multifaceted knowledge and skills. -from swarms import Agent +#### 3. **Scalability and Flexibility** +Multi-agent systems can more easily scale to handle large-scale or evolving tasks. Adding more agents to the system can increase its capacity or capabilities, allowing it to adapt to larger workloads or new types of tasks. This scalability is essential in dynamic environments where the demand and nature of tasks can change rapidly. -class LangchainAgentWrapper(Agent): - """ - Initialize the LangchainAgentWrapper. +#### 4. **Robustness and Redundancy** - Args: - name (str): The name of the agent. - tools (List[Tool]): The list of tools available to the agent. - llm (Optional[OpenAI], optional): The OpenAI language model to use. Defaults to None. - """ - def __init__( - self, - name: str, - tools: List[Tool], - llm: Optional[OpenAI] = None, - *args, - **kwargs, - ): - super().__init__(*args, **kwargs) - self.name = name - self.tools = tools - self.llm = llm or OpenAI(temperature=0) +Collaboration among multiple agents enhances the system's robustness by introducing redundancy. If one agent fails or encounters an error, others can compensate, ensuring the system remains operational. This redundancy is critical in mission-critical applications where failure is not an option. - prompt = StringPromptTemplate.from_template( - "You are {name}, an AI assistant. Answer the following question: {question}" - ) +### Overcoming Expenses with API Bills and Hosting - llm_chain = LLMChain(llm=self.llm, prompt=prompt) - tool_names = [tool.name for tool in self.tools] +Deploying multiple agents, especially when relying on cloud-based services or APIs, can incur significant costs. Here are strategies to manage and reduce these expenses: - self.agent = LLMSingleActionAgent( - llm_chain=llm_chain, - output_parser=None, - stop=["\nObservation:"], - allowed_tools=tool_names, - ) +#### 1. **Optimize Agent Efficiency** - self.agent_executor = AgentExecutor.from_agent_and_tools( - agent=self.agent, tools=self.tools, verbose=True - ) +Before scaling up the number of agents, ensure each agent operates as efficiently as possible. This can involve refining algorithms, reducing unnecessary API calls, and optimizing data processing to minimize computational requirements and, consequently, the associated costs. - def run(self, task: str, *args, **kwargs): - """ - Run the agent with the given task. +#### 2. **Use Open Source and Self-Hosted Solutions** - Args: - task (str): The task to be performed by the agent. +Where possible, leverage open-source models and technologies that can be self-hosted. While there is an initial investment in setting up the infrastructure, over time, self-hosting can significantly reduce costs related to API calls and reliance on third-party services. - Returns: - Any: The result of the agent's execution. - """ - try: - return self.agent_executor.run(task) - except Exception as e: - print(f"An error occurred: {e}") +#### 3. **Implement Intelligent Caching** +Caching results for frequently asked questions or common tasks can drastically reduce the need for repeated computations or API calls. Intelligent caching systems can determine what information to store and for how long, optimizing the balance between fresh data and computational savings. -# Usage example +#### 4. **Dynamic Scaling and Load Balancing** -search_tool = DuckDuckGoSearchRun() -tools = [ - Tool( - name="Search", - func=search_tool.run, - description="Useful for searching the internet", - ) -] +Use cloud services that offer dynamic scaling and load balancing to adjust the resources allocated based on the current demand. This ensures you're not paying for idle resources during low-usage periods while still being able to handle high demand when necessary. -langchain_wrapper = LangchainAgentWrapper("LangchainAssistant", tools) -result = langchain_wrapper.run("What is the capital of France?") -print(result) -``` +#### 5. **Collaborative Cost-Sharing Models** -This wrapper integrates a Langchain agent into the swarms framework, allowing for easy use of Langchain's powerful features such as tool use and multi-step reasoning. +In scenarios where multiple stakeholders benefit from the multi-agent system, consider implementing a cost-sharing model. This approach distributes the financial burden among the users or beneficiaries, making it more sustainable. -### CrewAI Integration +#### 6. **Monitor and Analyze Costs** -CrewAI is a library focused on creating and managing teams of AI agents. Let's create a wrapper for a CrewAI agent: +Regularly monitor and analyze your usage and associated costs to identify potential savings. Many cloud providers offer tools to track and forecast expenses, helping you to adjust your usage patterns and configurations to minimize costs without sacrificing performance. -```python -from swarms import Agent -from crewai import Agent as CrewAIAgent -from crewai import Task, Crew, Process +### Conclusion -class CrewAIAgentWrapper(Agent): - def __init__(self, name, role, goal, backstory, tools=None, *args, **kwargs): - super().__init__(*args, **kwargs) - self.name = name - self.crewai_agent = CrewAIAgent( - role=role, - goal=goal, - backstory=backstory, - verbose=True, - allow_delegation=False, - tools=tools or [] - ) +The collaboration of multiple agents in AI systems presents a robust solution to the complexity, specialization, scalability, and robustness challenges inherent in single-agent approaches. While the associated costs can be significant, strategic optimization, leveraging open-source technologies, intelligent caching, dynamic resource management, collaborative cost-sharing, and diligent monitoring can mitigate these expenses. By adopting these strategies, organizations can harness the power of multi-agent systems to tackle complex problems more effectively and efficiently, ensuring the sustainable deployment of these advanced technologies. - def run(self, task, *args, **kwargs): - crew_task = Task( - description=task, - agent=self.crewai_agent - ) - crew = Crew( - agents=[self.crewai_agent], - tasks=[crew_task], - process=Process.sequential - ) - result = crew.kickoff() - return result +-------------------------------------------------- -# Usage example -from crewai_tools import SerperDevTool +# File: swarms\concept\swarm_architectures.md -search_tool = SerperDevTool() +# Multi-Agent Architectures -crewai_wrapper = CrewAIAgentWrapper( - "ResearchAnalyst", - role='Senior Research Analyst', - goal='Uncover cutting-edge developments in AI and data science', - backstory="""You work at a leading tech think tank. - Your expertise lies in identifying emerging trends. - You have a knack for dissecting complex data and presenting actionable insights.""", - tools=[search_tool] -) +### What is a Multi-Agent Architecture? -result = crewai_wrapper.run("Analyze the latest trends in quantum computing and summarize the key findings.") -print(result) -``` +A multi-agent architecture refers to a group of more than two agents working collaboratively to achieve a common goal. These agents can be software entities, such as LLMs that interact with each other to perform complex tasks. The concept of multi-agent architectures is inspired by how humans communicate and work together in teams, organizations, and communities, where individual contributions combine to create sophisticated collaborative problem-solving capabilities. -This wrapper allows us to use CrewAI agents within the swarms framework, leveraging CrewAI's focus on role-based agents and collaborative task execution. +### How Multi-Agent Architectures Facilitate Communication -### Autogen Integration +Multi-agent architectures are designed to establish and manage communication between agents within a system. These architectures define how agents interact, share information, and coordinate their actions to achieve the desired outcomes. Here are some key aspects of multi-agent architectures: -Autogen is a framework for building conversational AI agents. Here's how we can create a wrapper for an Autogen agent: +1. **Hierarchical Communication**: In hierarchical architectures, communication flows from higher-level agents to lower-level agents. Higher-level agents act as coordinators, distributing tasks and aggregating results. This structure is efficient for tasks that require top-down control and decision-making. -```python -from swarms import Agent -from autogen import ConversableAgent +2. **Concurrent Communication**: In concurrent architectures, agents operate independently and simultaneously on different tasks. This architecture is suitable for tasks that can be processed concurrently without dependencies, allowing for faster execution and scalability. -class AutogenAgentWrapper(Agent): - def __init__(self, name, llm_config, *args, **kwargs): - super().__init__(*args, **kwargs) - self.name = name - self.autogen_agent = ConversableAgent( - name=name, - llm_config=llm_config, - code_execution_config=False, - function_map=None, - human_input_mode="NEVER" - ) +3. **Sequential Communication**: Sequential architectures process tasks in a linear order, where each agent's output becomes the input for the next agent. This ensures that tasks with dependencies are handled in the correct sequence, maintaining the integrity of the workflow. - def run(self, task, *args, **kwargs): - messages = [{"content": task, "role": "user"}] - response = self.autogen_agent.generate_reply(messages) - return response +4. **Mesh Communication**: In mesh architectures, agents are fully connected, allowing any agent to communicate with any other agent. This setup provides high flexibility and redundancy, making it ideal for complex systems requiring dynamic interactions. -# Usage example -import os +5. **Federated Communication**: Federated architectures involve multiple independent systems that collaborate by sharing information and results. Each system operates autonomously but can contribute to a larger task, enabling distributed problem-solving across different nodes. -llm_config = { - "config_list": [{"model": "gpt-4", "api_key": os.environ.get("OPENAI_API_KEY")}] -} +Multi-agent architectures leverage these communication patterns to ensure that agents work together efficiently, adapting to the specific requirements of the task at hand. By defining clear communication protocols and interaction models, multi-agent architectures enable the seamless orchestration of multiple agents, leading to enhanced performance and problem-solving capabilities. -autogen_wrapper = AutogenAgentWrapper("AutogenAssistant", llm_config) -result = autogen_wrapper.run("Tell me a joke about programming.") -print(result) -``` +## Core Multi-Agent Architectures -This wrapper integrates Autogen's ConversableAgent into the swarms framework, allowing for easy use of Autogen's conversational AI capabilities. +| **Name** | **Description** | **Documentation** | **Use Cases** | +|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------| +| Hierarchical Architecture | A system where agents are organized in a hierarchy, with higher-level agents coordinating lower-level agents to achieve complex tasks. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/hierarchical_swarm/) | Manufacturing process optimization, multi-level sales management, healthcare resource coordination | +| Agent Rearrange | A setup where agents rearrange themselves dynamically based on the task requirements and environmental conditions. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/) | Adaptive manufacturing lines, dynamic sales territory realignment, flexible healthcare staffing | +| Concurrent Workflows | Agents perform different tasks simultaneously, coordinating to complete a larger goal. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/concurrentworkflow/) | Concurrent production lines, parallel sales operations, simultaneous patient care processes | +| Sequential Coordination | Agents perform tasks in a specific sequence, where the completion of one task triggers the start of the next. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/) | Step-by-step assembly lines, sequential sales processes, stepwise patient treatment workflows | +| Mixture of Agents | A heterogeneous architecture where agents with different capabilities are combined to solve complex problems. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/moa/) | Financial forecasting, complex problem-solving requiring diverse skills | +| Graph Workflow | Agents collaborate in a directed acyclic graph (DAG) format to manage dependencies and parallel tasks. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/graph_workflow/) | AI-driven software development pipelines, complex project management | +| Group Chat | Agents engage in a chat-like interaction to reach decisions collaboratively. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/group_chat/) | Real-time collaborative decision-making, contract negotiations | +| Interactive Group Chat | Enhanced group chat with dynamic speaker selection and interaction patterns. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/interactive_groupchat/) | Advanced collaborative decision-making, dynamic team coordination | +| Agent Registry | A centralized registry where agents are stored, retrieved, and invoked dynamically. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/agent_registry/) | Dynamic agent management, evolving recommendation engines | +| SpreadSheet | Manages tasks at scale, tracking agent outputs in a structured format like CSV files. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/spreadsheet_swarm/) | Large-scale marketing analytics, financial audits | +| Router | Routes and chooses the architecture based on the task requirements and available agents. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/) | Dynamic task routing, adaptive architecture selection, optimized agent allocation | +| Heavy | High-performance architecture for handling intensive computational tasks with multiple agents. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/heavy_swarm/) | Large-scale data processing, intensive computational workflows | +| Deep Research | Specialized architecture for conducting in-depth research tasks across multiple domains. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/deep_research_swarm/) | Academic research, market analysis, comprehensive data investigation | +| De-Hallucination | Architecture designed to reduce and eliminate hallucinations in AI outputs through consensus. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/de_hallucination_swarm/) | Fact-checking, content verification, reliable information generation | +| Council as Judge | Multiple agents act as a council to evaluate and judge outputs or decisions. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/council_of_judges/) | Quality assessment, decision validation, peer review processes | +| MALT | Specialized architecture for complex language processing tasks across multiple agents. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/malt/) | Natural language processing, translation, content generation | +| Majority Voting | Agents vote on decisions with the majority determining the final outcome. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/majorityvoting/) | Democratic decision-making, consensus building, error reduction | +| Round Robin | Tasks are distributed cyclically among agents in a rotating order. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/round_robin_swarm/) | Load balancing, fair task distribution, resource optimization | +| Auto-Builder | Automatically constructs and configures multi-agent systems based on requirements. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/auto_swarm_builder/) | Dynamic system creation, adaptive architectures, rapid prototyping | +| Hybrid Hierarchical Cluster | Combines hierarchical and peer-to-peer communication patterns for complex workflows. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/hhcs/) | Complex enterprise workflows, multi-department coordination | +| Election | Agents participate in democratic voting processes to select leaders or make collective decisions. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/election_swarm/) | Democratic governance, consensus building, leadership selection | +| Dynamic Conversational | Adaptive conversation management with dynamic agent selection and interaction patterns. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/dynamic_conversational_swarm/) | Adaptive chatbots, dynamic customer service, contextual conversations | +| Tree | Hierarchical tree structure for organizing agents in parent-child relationships. | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/tree_swarm/) | Organizational hierarchies, decision trees, taxonomic classification | -By creating these wrappers, we can seamlessly integrate agents from various libraries into the swarms framework, allowing for a unified approach to agent management and task execution. +--- -## 5. Advanced Agent Handling Techniques +## Architectural Patterns -As you build more complex systems using the swarms framework and integrated agent libraries, you'll need to employ advanced techniques for agent handling. Here are some strategies to consider: +### Hierarchical Architecture -### 1. Dynamic Agent Creation +**Overview:** +Organizes agents in a tree-like structure. Higher-level agents delegate tasks to lower-level agents, which can further divide tasks among themselves. This structure allows for efficient task distribution and scalability. -Implement a factory pattern to create agents dynamically based on task requirements: +**Use Cases:** -```python -class AgentFactory: - @staticmethod - def create_agent(agent_type, *args, **kwargs): - if agent_type == "griptape": - return GriptapeAgentWrapper(*args, **kwargs) - elif agent_type == "langchain": - return LangchainAgentWrapper(*args, **kwargs) - elif agent_type == "crewai": - return CrewAIAgentWrapper(*args, **kwargs) - elif agent_type == "autogen": - return AutogenAgentWrapper(*args, **kwargs) - else: - raise ValueError(f"Unknown agent type: {agent_type}") +- Complex decision-making processes where tasks can be broken down into subtasks -# Usage -agent = AgentFactory.create_agent("griptape", "DynamicGriptapeAgent") +- Multi-stage workflows such as data processing pipelines or hierarchical reinforcement learning + + +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/hierarchical_swarm/)** + +```mermaid +graph TD + A[Root Agent] --> B1[Sub-Agent 1] + A --> B2[Sub-Agent 2] + B1 --> C1[Sub-Agent 1.1] + B1 --> C2[Sub-Agent 1.2] + B2 --> C3[Sub-Agent 2.1] + B2 --> C4[Sub-Agent 2.2] ``` +--- -### 2. Agent Pooling +### Agent Rearrange -Implement an agent pool to manage and reuse agents efficiently: +**Overview:** +A dynamic architecture where agents rearrange themselves based on task requirements and environmental conditions. Agents can adapt their roles, positions, and relationships to optimize performance for different scenarios. -```python -from queue import Queue +**Use Cases:** +- Adaptive manufacturing lines that reconfigure based on product requirements -class AgentPool: - def __init__(self, pool_size=5): - self.pool = Queue(maxsize=pool_size) - self.pool_size = pool_size +- Dynamic sales territory realignment based on market conditions - def get_agent(self, agent_type, *args, **kwargs): - if not self.pool.empty(): - return self.pool.get() - else: - return AgentFactory.create_agent(agent_type, *args, **kwargs) +- Flexible healthcare staffing that adjusts to patient needs - def release_agent(self, agent): - if self.pool.qsize() < self.pool_size: - self.pool.put(agent) -# Usage -pool = AgentPool() -agent = pool.get_agent("langchain", "PooledLangchainAgent") -result = agent.run("Perform a task") -pool.release_agent(agent) +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/)** + +```mermaid +graph TD + A[Task Requirements] --> B[Configuration Analyzer] + B --> C[Optimization Engine] + + C --> D[Agent Pool] + D --> E[Agent 1] + D --> F[Agent 2] + D --> G[Agent 3] + D --> H[Agent N] + + C --> I[Rearrangement Logic] + I --> J[New Configuration] + J --> K[Role Assignment] + K --> L[Execution Phase] + + L --> M[Performance Monitor] + M --> N{Optimization Needed?} + N -->|Yes| C + N -->|No| O[Continue Execution] ``` -### 3. Agent Composition +--- -Create composite agents that combine the capabilities of multiple agent types: +### Concurrent Architecture -```python -class CompositeAgent(Agent): - def __init__(self, name, agents): - super().__init__() - self.name = name - self.agents = agents +**Overview:** +Multiple agents operate independently and simultaneously on different tasks. Each agent works on its own task without dependencies on the others. - def run(self, task): - results = [] - for agent in self.agents: - results.append(agent.run(task)) - return self.aggregate_results(results) +**Use Cases:** +- Tasks that can be processed independently, such as parallel data analysis - def aggregate_results(self, results): - # Implement your own logic to combine results - return "\n".join(results) +- Large-scale simulations where multiple scenarios are run simultaneously -# Usage -griptape_agent = GriptapeAgentWrapper("GriptapeComponent") -langchain_agent = LangchainAgentWrapper("LangchainComponent", []) -composite_agent = CompositeAgent("CompositeAssistant", [griptape_agent, langchain_agent]) -result = composite_agent.run("Analyze the pros and cons of quantum computing") + +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/concurrentworkflow/)** + +```mermaid +graph LR + A[Task Input] --> B1[Agent 1] + A --> B2[Agent 2] + A --> B3[Agent 3] + A --> B4[Agent 4] + B1 --> C1[Output 1] + B2 --> C2[Output 2] + B3 --> C3[Output 3] + B4 --> C4[Output 4] ``` -### 4. Agent Specialization +--- -Create specialized agents for specific domains or tasks: +### Sequential Architecture -```python -class DataAnalysisAgent(Agent): - def __init__(self, name, analysis_tools): - super().__init__() - self.name = name - self.analysis_tools = analysis_tools +**Overview:** +Processes tasks in a linear sequence. Each agent completes its task before passing the result to the next agent in the chain. Ensures orderly processing and is useful when tasks have dependencies. - def run(self, data): - results = {} - for tool in self.analysis_tools: - results[tool.name] = tool.analyze(data) - return results +**Use Cases:** -# Usage -import pandas as pd -from sklearn.preprocessing import StandardScaler -from sklearn.decomposition import PCA +- Workflows where each step depends on the previous one, such as assembly lines or sequential data processing -class AnalysisTool: - def __init__(self, name, func): - self.name = name - self.func = func +- Scenarios requiring strict order of operations - def analyze(self, data): - return self.func(data) -tools = [ - AnalysisTool("Descriptive Stats", lambda data: data.describe()), - AnalysisTool("Correlation", lambda data: data.corr()), - AnalysisTool("PCA", lambda data: PCA().fit_transform(StandardScaler().fit_transform(data))) -] +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/)** -data_agent = DataAnalysisAgent("DataAnalyst", tools) -df = pd.read_csv("sample_data.csv") -analysis_results = data_agent.run(df) +```mermaid +graph TD + A[Input] --> B[Agent 1] + B --> C[Agent 2] + C --> D[Agent 3] + D --> E[Agent 4] + E --> F[Final Output] ``` -### 5. Agent Monitoring and Logging +--- -Implement a monitoring system to track agent performance and log their activities: +### Round Robin Architecture -```python -import logging -from functools import wraps +**Overview:** +Tasks are distributed cyclically among a set of agents. Each agent takes turns handling tasks in a rotating order, ensuring even distribution of workload. -def log_agent_activity(func): - @wraps(func) - def wrapper(self, *args, **kwargs): - logging.info(f"Agent {self.name} started task: {args[0]}") - result = func(self, *args, **kwargs) - logging.info(f"Agent {self.name} completed task. Result length: {len(str(result))}") - return result - return wrapper +**Use Cases:** -class MonitoredAgent(Agent): - def __init__(self, name, *args, **kwargs): - super().__init__(*args, **kwargs) - self.name = name +- Load balancing in distributed systems - @log_agent_activity - def run(self, task, *args, **kwargs): - return super().run(task, *args, **kwargs) +- Scenarios requiring fair distribution of tasks to avoid overloading any single agent -# Usage -logging.basicConfig(level=logging.INFO) -monitored_agent = MonitoredAgent("MonitoredGriptapeAgent") -result = monitored_agent.run("Summarize the latest AI research papers") -``` -Additionally the Agent class now includes built-in logging functionality and the ability to switch between JSON and string output. -To switch between JSON and string output: -- Use `output_type="str"` for string output (default) -- Use `output_type="json"` for JSON output +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/round_robin_swarm/)** -The `output_type` parameter determines the format of the final result returned by the `run` method. When set to "str", it returns a string representation of the agent's response. When set to "json", it returns a JSON object containing detailed information about the agent's run, including all steps and metadata. +```mermaid +graph TD + A[Task Distributor] --> B1[Agent 1] + A --> B2[Agent 2] + A --> B3[Agent 3] + A --> B4[Agent 4] + B1 --> C[Task Queue] + B2 --> C + B3 --> C + B4 --> C + C --> A +``` -## 6. Best Practices for Custom Agent Development +--- -When developing custom agents using the swarms framework, consider the following best practices: +### SpreadSheet Architecture -1. **Modular Design**: Design your agents with modularity in mind. Break down complex functionality into smaller, reusable components. +**Overview:** +Makes it easy to manage thousands of agents in one place: a CSV file. Initialize any number of agents and run loops of agents on tasks. -2. **Consistent Interfaces**: Maintain consistent interfaces across your custom agents to ensure interoperability within the swarms framework. +**Use Cases:** +- Multi-threaded execution: Execute agents on multiple threads -3. **Error Handling**: Implement robust error handling and graceful degradation in your agents to ensure system stability. +- Save agent outputs into CSV file -4. **Performance Optimization**: Optimize your agents for performance, especially when dealing with resource-intensive tasks or large-scale deployments. +- One place to analyze agent outputs -5. **Testing and Validation**: Develop comprehensive test suites for your custom agents to ensure their reliability and correctness. -6. **Documentation**: Provide clear and detailed documentation for your custom agents, including their capabilities, limitations, and usage examples. +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/spreadsheet_swarm/)** -7. **Versioning**: Implement proper versioning for your custom agents to manage updates and maintain backwards compatibility. +```mermaid +graph TD + A[Initialize SpreadSheet System] --> B[Initialize Agents] + B --> C[Load Task Queue] + C --> D[Distribute Tasks] -8. **Security Considerations**: Implement security best practices, especially when dealing with sensitive data or integrating with external services. + subgraph Agent_Pool[Agent Pool] + D --> E1[Agent 1] + D --> E2[Agent 2] + D --> E3[Agent 3] + D --> E4[Agent N] + end -Here's an example that incorporates some of these best practices: + E1 --> F1[Process Task] + E2 --> F2[Process Task] + E3 --> F3[Process Task] + E4 --> F4[Process Task] -```python -import logging -from typing import Dict, Any -from swarms import Agent + F1 --> G[Collect Results] + F2 --> G + F3 --> G + F4 --> G -class SecureCustomAgent(Agent): - def __init__(self, name: str, api_key: str, version: str = "1.0.0", *args, **kwargs): - super().__init__(*args, **kwargs) - self.name = name - self._api_key = api_key # Store sensitive data securely - self.version = version - self.logger = logging.getLogger(f"{self.__class__.__name__}.{self.name}") + G --> H[Save to CSV] + H --> I[Generate Analytics] +``` - def run(self, task: str, *args, **kwargs) -> Dict[str, Any]: - try: - self.logger.info(f"Agent {self.name} (v{self.version}) starting task: {task}") - result = self._process_task(task) - self.logger.info(f"Agent {self.name} completed task successfully") - return {"status": "success", "result": result} - except Exception as e: - self.logger.error(f"Error in agent {self.name}: {str(e)}") - return {"status": "error", "message": str(e)} +--- - def _process_task(self, task: str) -> str: - # Implement the core logic of your agent here - # This is a placeholder implementation - return f"Processed task: {task}" +### Mixture of Agents - @property - def api_key(self) -> str: - # Provide a secure way to access the API key - return self._api_key +**Overview:** +Combines multiple agents with different capabilities and expertise to solve complex problems that require diverse skill sets. - def __repr__(self) -> str: - return f"<{self.__class__.__name__} name='{self.name}' version='{self.version}'>" +**Use Cases:** +- Financial forecasting requiring different analytical approaches -# Usage -logging.basicConfig(level=logging.INFO) -secure_agent = SecureCustomAgent("SecureAgent", api_key="your-api-key-here") -result = secure_agent.run("Perform a secure operation") -print(result) -``` +- Complex problem-solving needing diverse expertise -This example demonstrates several best practices: -- Modular design with separate methods for initialization and task processing -- Consistent interface adhering to the swarms framework -- Error handling and logging -- Secure storage of sensitive data (API key) -- Version tracking -- Type hinting for improved code readability and maintainability -- Informative string representation of the agent +- Multi-domain analysis tasks -## 7. Future Directions and Challenges -As the field of AI and agent-based systems continues to evolve, the swarms framework and its ecosystem of integrated agent libraries will face new opportunities and challenges. Some potential future directions and areas of focus include: +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/moa/)** -1. **Enhanced Interoperability**: Developing more sophisticated protocols for agent communication and collaboration across different libraries and frameworks. +```mermaid +graph TD + A[Task Input] --> B[Layer 1: Reference Agents] + B --> C[Specialist Agent 1] + B --> D[Specialist Agent 2] + B --> E[Specialist Agent N] -2. **Scalability**: Improving the framework's ability to handle large-scale swarms of agents, potentially leveraging distributed computing techniques. + C --> F[Response 1] + D --> G[Response 2] + E --> H[Response N] -3. **Adaptive Learning**: Incorporating more advanced machine learning techniques to allow agents to adapt and improve their performance over time. + F --> I[Layer 2: Aggregator Agent] + G --> I + H --> I + I --> J[Synthesized Output] +``` -4. **Ethical AI**: Integrating ethical considerations and safeguards into the agent development process to ensure responsible AI deployment. +--- -5. **Human-AI Collaboration**: Exploring new paradigms for human-AI interaction and collaboration within the swarms framework. +### Graph Workflow -6. **Domain-Specific Optimizations**: Developing specialized agent types and tools for specific industries or problem domains. +**Overview:** +Organizes agents in a directed acyclic graph (DAG) format, enabling complex dependencies and parallel execution paths. -7. **Explainability and Transparency**: Improving the ability to understand and explain agent decision-making processes. +**Use Cases:** +- AI-driven software development pipelines -8. **Security and Privacy**: Enhancing the framework's security features to protect against potential vulnerabilities and ensure data privacy. +- Complex project management with dependencies -As these areas develop, developers working with the swarms framework will need to stay informed about new advancements and be prepared to adapt their agent implementations accordingly. +- Multi-step data processing workflows -## 8. Conclusion -The swarms framework provides a powerful and flexible foundation for building custom agents and integrating various agent libraries. By leveraging the techniques and best practices discussed in this guide, developers can create sophisticated, efficient, and scalable agent-based systems. +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/graph_workflow/)** -The ability to seamlessly integrate agents from libraries like Griptape, Langchain, CrewAI, and Autogen opens up a world of possibilities for creating diverse and specialized AI applications. Whether you're building a complex multi-agent system for data analysis, a conversational AI platform, or a collaborative problem-solving environment, the swarms framework offers the tools and flexibility to bring your vision to life. +```mermaid +graph TD + A[Start Node] --> B[Agent 1] + A --> C[Agent 2] + B --> D[Agent 3] + C --> D + B --> E[Agent 4] + D --> F[Agent 5] + E --> F + F --> G[End Node] +``` -As you embark on your journey with the swarms framework, remember that the field of AI and agent-based systems is rapidly evolving. Stay curious, keep experimenting, and don't hesitate to push the boundaries of what's possible with custom agents and integrated libraries. +--- -By embracing the power of the swarms framework and the ecosystem of agent libraries it supports, you're well-positioned to create the next generation of intelligent, adaptive, and collaborative AI systems. Happy agent building! +### Group Chat +**Overview:** +Enables agents to engage in chat-like interactions to reach decisions collaboratively through discussion and consensus building. --------------------------------------------------- +**Use Cases:** +- Real-time collaborative decision-making -# File: swarms/agents/tool_agent.md +- Contract negotiations -# ToolAgent Documentation +- Brainstorming sessions -The `ToolAgent` class is a specialized agent that facilitates the execution of specific tasks using a model and tokenizer. It is part of the `swarms` module and inherits from the `Agent` class. This agent is designed to generate functions based on a given JSON schema and task, making it highly adaptable for various use cases, including natural language processing and data generation. -The `ToolAgent` class plays a crucial role in leveraging pre-trained models and tokenizers to automate tasks that require the interpretation and generation of structured data. By providing a flexible interface and robust error handling, it ensures smooth integration and efficient task execution. +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/group_chat/)** -### Parameters +```mermaid +graph TD + A[Discussion Topic] --> B[Chat Environment] + B --> C[Agent 1] + B --> D[Agent 2] + B --> E[Agent 3] + B --> F[Agent N] + + C --> G[Message Exchange] + D --> G + E --> G + F --> G + + G --> H[Consensus Building] + H --> I[Final Decision] +``` -| Parameter | Type | Description | -|--------------------|-----------------------------------|---------------------------------------------------------------------------------| -| `name` | `str` | The name of the tool agent. Default is "Function Calling Agent". | -| `description` | `str` | A description of the tool agent. Default is "Generates a function based on the input json schema and the task". | -| `model` | `Any` | The model used by the tool agent. | -| `tokenizer` | `Any` | The tokenizer used by the tool agent. | -| `json_schema` | `Any` | The JSON schema used by the tool agent. | -| `max_number_tokens`| `int` | The maximum number of tokens for generation. Default is 500. | -| `parsing_function` | `Optional[Callable]` | An optional parsing function to process the output of the tool agent. | -| `llm` | `Any` | An optional large language model to be used by the tool agent. | -| `*args` | Variable length argument list | Additional positional arguments. | -| `**kwargs` | Arbitrary keyword arguments | Additional keyword arguments. | +--- -### Attributes +### Interactive Group Chat -| Attribute | Type | Description | -|--------------------|-------|----------------------------------------------| -| `name` | `str` | The name of the tool agent. | -| `description` | `str` | A description of the tool agent. | -| `model` | `Any` | The model used by the tool agent. | -| `tokenizer` | `Any` | The tokenizer used by the tool agent. | -| `json_schema` | `Any` | The JSON schema used by the tool agent. | +**Overview:** +Enhanced version of Group Chat with dynamic speaker selection, priority-based communication, and advanced interaction patterns. -### Methods +**Use Cases:** +- Advanced collaborative decision-making -#### `run` +- Dynamic team coordination -```python -def run(self, task: str, *args, **kwargs) -> Any: -``` +- Adaptive conversation management -**Parameters:** -| Parameter | Type | Description | -|------------|---------------------------|------------------------------------------------------------------| -| `task` | `str` | The task to be performed by the tool agent. | -| `*args` | Variable length argument list | Additional positional arguments. | -| `**kwargs` | Arbitrary keyword arguments | Additional keyword arguments. | +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/interactive_groupchat/)** -**Returns:** +```mermaid +graph TD + A[Conversation Manager] --> B[Speaker Selection Logic] + B --> C[Priority Speaker] + B --> D[Random Speaker] + B --> E[Round Robin Speaker] + + C --> F[Active Discussion] + D --> F + E --> F + + F --> G[Agent Pool] + G --> H[Agent 1] + G --> I[Agent 2] + G --> J[Agent N] + + H --> K[Dynamic Response] + I --> K + J --> K + K --> A +``` -- The output of the tool agent. +--- -**Raises:** +### Agent Registry -- `Exception`: If an error occurs during the execution of the tool agent. +**Overview:** +A centralized registry system where agents are stored, retrieved, and invoked dynamically. The registry maintains metadata about agent capabilities, availability, and performance metrics, enabling intelligent agent selection and management. -## Functionality and Usage +**Use Cases:** +- Dynamic agent management in large-scale systems -The `ToolAgent` class provides a structured way to perform tasks using a model and tokenizer. It initializes with essential parameters and attributes, and the `run` method facilitates the execution of the specified task. +- Evolving recommendation engines that adapt agent selection -### Initialization +- Service discovery in distributed agent systems -The initialization of a `ToolAgent` involves specifying its name, description, model, tokenizer, JSON schema, maximum number of tokens, optional parsing function, and optional large language model. -```python -agent = ToolAgent( - name="My Tool Agent", - description="A tool agent for specific tasks", - model=model, - tokenizer=tokenizer, - json_schema=json_schema, - max_number_tokens=1000, - parsing_function=my_parsing_function, - llm=my_llm -) -``` +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/agent_registry/)** -### Running a Task +```mermaid +graph TD + A[Agent Registration] --> B[Registry Database] + B --> C[Agent Metadata] + C --> D[Capabilities] + C --> E[Performance Metrics] + C --> F[Availability Status] + + G[Task Request] --> H[Registry Query Engine] + H --> I[Agent Discovery] + I --> J[Capability Matching] + J --> K[Agent Selection] + + K --> L[Agent Invocation] + L --> M[Task Execution] + M --> N[Performance Tracking] + N --> O[Registry Update] + O --> B +``` -To execute a task using the `ToolAgent`, the `run` method is called with the task description and any additional arguments or keyword arguments. +--- -```python -result = agent.run("Generate a person's information based on the given schema.") -print(result) -``` +### Router Architecture -### Detailed Examples +**Overview:** +Intelligently routes tasks to the most appropriate agents or architectures based on task requirements and agent capabilities. -#### Example 1: Basic Usage +**Use Cases:** +- Dynamic task routing -```python -from transformers import AutoModelForCausalLM, AutoTokenizer -from swarms import ToolAgent +- Adaptive architecture selection -model = AutoModelForCausalLM.from_pretrained("databricks/dolly-v2-12b") -tokenizer = AutoTokenizer.from_pretrained("databricks/dolly-v2-12b") +- Optimized agent allocation -json_schema = { - "type": "object", - "properties": { - "name": {"type": "string"}, - "age": {"type": "number"}, - "is_student": {"type": "boolean"}, - "courses": { - "type": "array", - "items": {"type": "string"} - } - } -} -task = "Generate a person's information based on the following schema:" -agent = ToolAgent(model=model, tokenizer=tokenizer, json_schema=json_schema) -generated_data = agent.run(task) +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/)** -print(generated_data) +```mermaid +graph TD + A[Incoming Task] --> B[Router Analysis] + B --> C[Task Classification] + C --> D[Agent Capability Matching] + + D --> E[Route to Sequential] + D --> F[Route to Concurrent] + D --> G[Route to Hierarchical] + D --> H[Route to Specialist Agent] + + E --> I[Execute Architecture] + F --> I + G --> I + H --> I + + I --> J[Collect Results] + J --> K[Return Output] ``` -#### Example 2: Using a Parsing Function +--- -```python -def parse_output(output): - # Custom parsing logic - return output +### Heavy Architecture -agent = ToolAgent( - name="Parsed Tool Agent", - description="A tool agent with a parsing function", - model=model, - tokenizer=tokenizer, - json_schema=json_schema, - parsing_function=parse_output -) +**Overview:** +High-performance architecture designed for handling intensive computational tasks with multiple agents working on resource-heavy operations. -task = "Generate a person's information with custom parsing:" -parsed_data = agent.run(task) +**Use Cases:** +- Large-scale data processing -print(parsed_data) -``` +- Intensive computational workflows -#### Example 3: Specifying Maximum Number of Tokens +- High-throughput task execution -```python -agent = ToolAgent( - name="Token Limited Tool Agent", - description="A tool agent with a token limit", - model=model, - tokenizer=tokenizer, - json_schema=json_schema, - max_number_tokens=200 -) -task = "Generate a concise person's information:" -limited_data = agent.run(task) +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/heavy_swarm/)** -print(limited_data) +```mermaid +graph TD + A[Resource Manager] --> B[Load Balancer] + B --> C[Heavy Agent Pool] + + C --> D[Compute Agent 1] + C --> E[Compute Agent 2] + C --> F[Compute Agent N] + + D --> G[Resource Monitor] + E --> G + F --> G + + G --> H[Performance Optimizer] + H --> I[Result Aggregator] + I --> J[Final Output] ``` +--- -## Full Usage -```python - -from pydantic import BaseModel, Field -from transformers import AutoModelForCausalLM, AutoTokenizer +### Deep Research Architecture -from swarms import ToolAgent -from swarms.tools.json_utils import base_model_to_json +**Overview:** +Specialized architecture for conducting comprehensive research tasks across multiple domains with iterative refinement and cross-validation. -# Model name -model_name = "CohereForAI/c4ai-command-r-v01-4bit" +**Use Cases:** +- Academic research projects -# Load the pre-trained model and tokenizer -model = AutoModelForCausalLM.from_pretrained( - model_name, - device_map="auto", -) +- Market analysis and intelligence -# Load the pre-trained model and tokenizer -tokenizer = AutoTokenizer.from_pretrained(model_name) +- Comprehensive data investigation -# Initialize the schema for the person's information -class APIExampleRequestSchema(BaseModel): - endpoint: str = Field( - ..., description="The API endpoint for the example request" - ) - method: str = Field( - ..., description="The HTTP method for the example request" - ) - headers: dict = Field( - ..., description="The headers for the example request" - ) - body: dict = Field(..., description="The body of the example request") - response: dict = Field( - ..., - description="The expected response of the example request", - ) +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/deep_research_swarm/)** +```mermaid +graph TD + A[Research Query] --> B[Research Planner] + B --> C[Domain Analysis] + C --> D[Research Agent 1] + C --> E[Research Agent 2] + C --> F[Research Agent N] + + D --> G[Initial Findings] + E --> G + F --> G + + G --> H[Cross-Validation] + H --> I[Refinement Loop] + I --> J[Synthesis Agent] + J --> K[Comprehensive Report] +``` -# Convert the schema to a JSON string -api_example_schema = base_model_to_json(APIExampleRequestSchema) -# Convert the schema to a JSON string +--- -# Define the task to generate a person's information -task = "Generate an example API request using this code:\n" +### De-Hallucination Architecture -# Create an instance of the ToolAgent class -agent = ToolAgent( - name="Command R Tool Agent", - description=( - "An agent that generates an API request using the Command R" - " model." - ), - model=model, - tokenizer=tokenizer, - json_schema=api_example_schema, -) +**Overview:** +Architecture specifically designed to reduce and eliminate hallucinations in AI outputs through consensus mechanisms and fact-checking protocols. -# Run the agent to generate the person's information -generated_data = agent.run(task) +**Use Cases:** +- Fact-checking and verification -# Print the generated data -print(f"Generated data: {generated_data}") +- Content validation +- Reliable information generation +```mermaid +graph TD + A[Input Query] --> B[Primary Agent] + B --> C[Initial Response] + C --> D[Validation Layer] + + D --> E[Fact-Check Agent 1] + D --> F[Fact-Check Agent 2] + D --> G[Fact-Check Agent 3] + + E --> H[Consensus Engine] + F --> H + G --> H + + H --> I[Confidence Score] + I --> J{Score > Threshold?} + J -->|Yes| K[Validated Output] + J -->|No| L[Request Refinement] + L --> B ``` +--- -## Jamba ++ ToolAgent -```python -from pydantic import BaseModel, Field -from transformers import AutoModelForCausalLM, AutoTokenizer +### Council as Judge -from swarms import ToolAgent -from swarms.tools.json_utils import base_model_to_json +**Overview:** +Multiple agents act as a council to evaluate, judge, and validate outputs or decisions through collaborative assessment. -# Model name -model_name = "ai21labs/Jamba-v0.1" +**Use Cases:** +- Quality assessment and validation -# Load the pre-trained model and tokenizer -model = AutoModelForCausalLM.from_pretrained( - model_name, - device_map="auto", -) +- Decision validation processes -# Load the pre-trained model and tokenizer -tokenizer = AutoTokenizer.from_pretrained(model_name) +- Peer review systems -# Initialize the schema for the person's information -class APIExampleRequestSchema(BaseModel): - endpoint: str = Field( - ..., description="The API endpoint for the example request" - ) - method: str = Field( - ..., description="The HTTP method for the example request" - ) - headers: dict = Field( - ..., description="The headers for the example request" - ) - body: dict = Field(..., description="The body of the example request") - response: dict = Field( - ..., - description="The expected response of the example request", - ) +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/council_of_judges/)** +```mermaid +graph TD + A[Submission] --> B[Council Formation] + B --> C[Judge Agent 1] + B --> D[Judge Agent 2] + B --> E[Judge Agent 3] + B --> F[Judge Agent N] + + C --> G[Individual Assessment] + D --> G + E --> G + F --> G + + G --> H[Scoring System] + H --> I[Weighted Voting] + I --> J[Final Judgment] + J --> K[Feedback & Recommendations] +``` -# Convert the schema to a JSON string -api_example_schema = base_model_to_json(APIExampleRequestSchema) -# Convert the schema to a JSON string +--- -# Define the task to generate a person's information -task = "Generate an example API request using this code:\n" +### MALT Architecture -# Create an instance of the ToolAgent class -agent = ToolAgent( - name="Command R Tool Agent", - description=( - "An agent that generates an API request using the Command R" - " model." - ), - model=model, - tokenizer=tokenizer, - json_schema=api_example_schema, -) +**Overview:** +Specialized architecture for complex language processing tasks that require coordination between multiple language-focused agents. -# Run the agent to generate the person's information -generated_data = agent(task) +**Use Cases:** +- Natural language processing pipelines -# Print the generated data -print(f"Generated data: {generated_data}") -``` +- Translation and localization -## Additional Information and Tips +- Content generation and editing -- Ensure that either the `model` or `llm` parameter is provided during initialization. If neither is provided, the `ToolAgent` will raise an exception. -- The `parsing_function` parameter is optional but can be very useful for post-processing the output of the tool agent. -- Adjust the `max_number_tokens` parameter to control the length of the generated output, depending on the requirements of the task. -## References and Resources +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/malt/)** -- [Transformers Documentation](https://huggingface.co/transformers/) -- [Loguru Logger](https://loguru.readthedocs.io/en/stable/) +```mermaid +graph TD + A[Language Task] --> B[Task Analyzer] + B --> C[Language Router] + + C --> D[Grammar Agent] + C --> E[Semantics Agent] + C --> F[Style Agent] + C --> G[Context Agent] + + D --> H[Language Processor] + E --> H + F --> H + G --> H + + H --> I[Quality Controller] + I --> J[Output Formatter] + J --> K[Final Language Output] +``` -This documentation provides a comprehensive guide to the `ToolAgent` class, including its initialization, usage, and practical examples. By following the detailed instructions and examples, developers can effectively utilize the `ToolAgent` for various tasks involving model and tokenizer-based operations. +--- --------------------------------------------------- +### Majority Voting -# File: swarms/artifacts/artifact.md +**Overview:** +Agents vote on decisions with the majority determining the final outcome, providing democratic decision-making and error reduction through consensus. -# `Artifact` +**Use Cases:** +- Democratic decision-making processes -The `Artifact` class represents a file artifact, encapsulating the file's path, type, contents, versions, and edit count. This class provides a comprehensive way to manage file versions, edit contents, and handle various file-related operations such as saving, loading, and exporting to JSON. +- Consensus building -The `Artifact` class is particularly useful in contexts where file version control and content management are essential. By keeping track of the number of edits and maintaining a version history, it allows for robust file handling and auditability. +- Error reduction through voting -## Class Definition -### Artifact +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/majorityvoting/)** +```mermaid +graph TD + A[Decision Request] --> B[Voting Coordinator] + B --> C[Voting Pool] + + C --> D[Voter Agent 1] + C --> E[Voter Agent 2] + C --> F[Voter Agent 3] + C --> G[Voter Agent N] + + D --> H[Vote Collection] + E --> H + F --> H + G --> H + + H --> I[Vote Counter] + I --> J[Majority Calculator] + J --> K[Final Decision] + K --> L[Decision Rationale] +``` -| Attribute | Type | Default Value | Description | -|-------------|---------------------|------------------|--------------------------------------------------| -| `file_path` | `str` | N/A | The path to the file. | -| `file_type` | `str` | N/A | The type of the file. | -| `contents` | `str` | `""` | The contents of the file. | -| `versions` | `List[FileVersion]` | `[]` | The list of file versions. | -| `edit_count`| `int` | `0` | The number of times the file has been edited. | +--- -### Parameters and Validation +### Auto-Builder -- `file_path`: A string representing the file path. -- `file_type`: A string representing the file type. This attribute is validated to ensure it matches supported file types based on the file extension if not provided. -- `contents`: A string representing the contents of the file. Defaults to an empty string. -- `versions`: A list of `FileVersion` instances representing the version history of the file. Defaults to an empty list. -- `edit_count`: An integer representing the number of edits made to the file. Defaults to 0. +**Overview:** +Automatically constructs and configures multi-agent systems based on requirements, enabling dynamic system creation and adaptation. -### Methods +**Use Cases:** +- Dynamic system creation -The `Artifact` class includes various methods for creating, editing, saving, loading, and exporting file artifacts. +- Adaptive architectures -#### `create` +- Rapid prototyping of multi-agent systems -| Parameter | Type | Description | -|--------------------|--------|----------------------------------------| -| `initial_content` | `str` | The initial content of the file. | -**Usage Example:** +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/auto_swarm_builder/)** -```python -artifact = Artifact(file_path="example.txt", file_type="txt") -artifact.create(initial_content="Initial file content") +```mermaid +graph TD + A[Requirements Input] --> B[System Analyzer] + B --> C[Architecture Selector] + C --> D[Agent Configuration] + + D --> E[Agent Builder 1] + D --> F[Agent Builder 2] + D --> G[Agent Builder N] + + E --> H[System Assembler] + F --> H + G --> H + + H --> I[Configuration Validator] + I --> J[System Deployment] + J --> K[Performance Monitor] + K --> L[Adaptive Optimizer] ``` -The file type parameter supports the following file types: `.txt`, `.md`, `.py`, `.pdf`. -#### `edit` +--- -| Parameter | Type | Description | -|---------------|--------|----------------------------------------| -| `new_content` | `str` | The new content of the file. | - -**Usage Example:** +### Hybrid Hierarchical Cluster -```python -artifact.edit(new_content="Updated file content") -``` +**Overview:** +Combines hierarchical and peer-to-peer communication patterns for complex workflows that require both centralized coordination and distributed collaboration. -#### `save` +**Use Cases:** +- Complex enterprise workflows -**Usage Example:** +- Multi-department coordination -```python -artifact.save() -``` +- Hybrid organizational structures -#### `load` -**Usage Example:** +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/hhcs/)** -```python -artifact.load() +```mermaid +graph TD + A[Central Coordinator] --> B[Cluster 1 Leader] + A --> C[Cluster 2 Leader] + A --> D[Cluster 3 Leader] + + B --> E[Peer Agent 1.1] + B --> F[Peer Agent 1.2] + E <--> F + + C --> G[Peer Agent 2.1] + C --> H[Peer Agent 2.2] + G <--> H + + D --> I[Peer Agent 3.1] + D --> J[Peer Agent 3.2] + I <--> J + + E --> K[Inter-Cluster Communication] + G --> K + I --> K + K --> A ``` -#### `get_version` - - -| Parameter | Type | Description | -|-------------------|-------|-----------------------------------------| -| `version_number` | `int` | The version number to retrieve. | - -**Usage Example:** +--- -```python -version = artifact.get_version(version_number=1) -``` +### Election Architecture -#### `get_contents` +**Overview:** +Agents participate in democratic voting processes to select leaders or make collective decisions. -**Usage Example:** +**Use Cases:** +- Democratic governance -```python -current_contents = artifact.get_contents() -``` +- Consensus building -#### `get_version_history` +- Leadership selection -**Usage Example:** +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/election_swarm/)** -```python -version_history = artifact.get_version_history() +```mermaid +graph TD + A[Voting Process] --> B[Candidate Agents] + B --> C[Voting Mechanism] + + C --> D[Voter Agent 1] + C --> E[Voter Agent 2] + C --> F[Voter Agent N] + + D --> G[Vote Collection] + E --> G + F --> G + + G --> H[Vote Counting] + H --> I[Majority Check] + I --> J{Majority?} + J -->|Yes| K[Leader Selected] + J -->|No| L[Continue Voting] + L --> B ``` -#### `export_to_json` +--- -| Parameter | Type | Description | -|-------------|-------|----------------------------------------------| -| `file_path` | `str` | The path to the JSON file to save the artifact.| +--- -**Usage Example:** +### Dynamic Conversational Architecture -```python -artifact.export_to_json(file_path="artifact.json") -``` +**Overview:** +Adaptive conversation management with dynamic agent selection and interaction patterns. -#### `import_from_json` +**Use Cases:** +- Adaptive chatbots +- Dynamic customer service -| Parameter | Type | Description | -|-------------|-------|--------------------------------------------------| -| `file_path` | `str` | The path to the JSON file to import the artifact from.| +- Contextual conversations -**Usage Example:** -```python -imported_artifact = Artifact.import_from_json(file_path="artifact.json") -``` +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/dynamic_conversational_swarm/)** -#### `get_metrics` +```mermaid +graph TD + A[Conversation Manager] --> B[Speaker Selection Logic] + B --> C[Priority Speaker] + B --> D[Random Speaker] + B --> E[Round Robin Speaker] + + C --> F[Active Discussion] + D --> F + E --> F + + F --> G[Agent Pool] + G --> H[Agent 1] + G --> I[Agent 2] + G --> J[Agent N] + + H --> K[Dynamic Response] + I --> K + J --> K + K --> A +``` -**Usage Example:** +--- -```python -metrics = artifact.get_metrics() -``` +### Tree Architecture -#### `to_dict` +**Overview:** +Hierarchical tree structure for organizing agents in parent-child relationships. -**Usage Example:** +**Use Cases:** +- Organizational hierarchies -```python -artifact_dict = artifact.to_dict() -``` +- Decision trees -#### `from_dict` +- Taxonomic classification -| Parameter | Type | Description | -|-----------|------------------|--------------------------------------------------| -| `data` | `Dict[str, Any]` | The dictionary representation of the artifact. | -**Usage Example:** +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/tree_swarm/)** -```python -artifact_data = { - "file_path": "example.txt", - "file_type": "txt", - "contents": "File content", - "versions": [], - "edit_count": 0 -} -artifact = Artifact.from_dict(artifact_data) +```mermaid +graph TD + A[Root] --> B[Child 1] + A --> C[Child 2] + B --> D[Grandchild 1] + B --> E[Grandchild 2] + C --> F[Grandchild 3] + C --> G[Grandchild 4] ``` -## Additional Information and Tips - -- The `Artifact` class uses the `pydantic` library to handle data validation and serialization. -- When editing the artifact, ensure that the `file_path` is set correctly to avoid file operation errors. -- Use the `get_version` and `get_version_history` methods to maintain a clear audit trail of changes to the file. -- The `export_to_json` and `import_from_json` methods are useful for backing up and restoring the state of an artifact. -## References and Resources +-------------------------------------------------- -- [Pydantic Documentation](https://pydantic-docs.helpmanual.io/) -- [Python os.path module](https://docs.python.org/3/library/os.path.html) -- [JSON Documentation](https://docs.python.org/3/library/json.html) +# File: swarms\concept\swarm_ecosystem.md -## Examples of Usage +# Understanding the Swarms Ecosystem -### Example 1: Creating and Editing an Artifact +The [Swarms Ecosystem](https://github.com/The-Swarm-Corporation/swarm-ecosystem) is a powerful suite of tools and frameworks designed to help developers build, deploy, and manage swarms of autonomous agents. This ecosystem covers various domains, from Large Language Models (LLMs) to IoT data integration, providing a comprehensive platform for automation and scalability. Below, we’ll explore the key components and how they contribute to this groundbreaking ecosystem. -```python -from datetime import datetime -from pydantic import BaseModel, Field, validator -from typing import List, Dict, Any, Union -import os -import json +#### 1. **Swarms Framework** -# Define FileVersion class -class FileVersion(BaseModel): - version_number: int - content: str - timestamp: datetime +The [Swarms Framework](https://github.com/The-Swarm-Corporation/swarm-ecosystem) is a Python-based toolkit that simplifies the creation, orchestration, and scaling of swarms of agents. Whether you are dealing with marketing, accounting, or data analysis, the Swarms Framework allows developers to automate complex workflows efficiently. -# Artifact class definition goes here +```mermaid +graph TD; + SF[Swarms Framework] --> Core[Swarms Core] + SF --> JS[Swarms JS] + SF --> Memory[Swarms Memory] + SF --> Evals[Swarms Evals] + SF --> Zero[Swarms Zero] +``` -# Create an artifact -artifact = Artifact(file_path="example.txt", file_type="txt") -artifact.create(initial_content="Initial file content") +#### 2. **Swarms-Cloud** -# Edit the artifact -artifact.edit(new_content="Updated file content") +[Swarms-Cloud](https://github.com/The-Swarm-Corporation/swarm-ecosystem) is a cloud-based solution that enables you to deploy your agents with enterprise-level guarantees. It provides 99% uptime, infinite scalability, and self-healing capabilities, making it ideal for mission-critical operations. -# Save the artifact to a file -artifact.save() +```mermaid +graph TD; + SC[Swarms-Cloud] --> Uptime[99% Uptime] + SC --> Scale[Infinite Scalability] + SC --> Healing[Self-Healing] +``` -# Load the artifact from the file -artifact.load() +#### 3. **Swarms-Models** -# Print the current contents of the artifact -print(artifact.get_contents()) +[Swarms-Models](https://github.com/The-Swarm-Corporation/swarm-ecosystem) offer a seamless interface to leading LLM providers like OpenAI, Anthropic, and Ollama. It allows developers to tap into cutting-edge natural language understanding for their agents. -# Print the version history -print(artifact.get_version_history()) +```mermaid +graph TD; + SM[Swarms-Models] --> OpenAI[OpenAI API] + SM --> Anthropic[Anthropic API] + SM --> Ollama[Ollama API] ``` -### Example 2: Exporting and Importing an Artifact +#### 4. **AgentParse** -```python -# Export the artifact to a JSON file -artifact.export_to_json(file_path="artifact.json") +[AgentParse](https://github.com/The-Swarm-Corporation/swarm-ecosystem) is a high-performance library for mapping structured data like JSON, YAML, CSV, and Pydantic models into formats understandable by agents. This ensures fast, seamless data ingestion. -# Import +```mermaid +graph TD; + AP[AgentParse] --> JSON[JSON Parsing] + AP --> YAML[YAML Parsing] + AP --> CSV[CSV Parsing] + AP --> Pydantic[Pydantic Model Parsing] +``` - the artifact from a JSON file -imported_artifact = Artifact.import_from_json(file_path="artifact.json") +#### 5. **Swarms-Platform** -# Print the metrics of the imported artifact -print(imported_artifact.get_metrics()) +The [Swarms-Platform](https://github.com/The-Swarm-Corporation/swarm-ecosystem) is a marketplace where developers can find, buy, and sell autonomous agents. It enables the rapid scaling of agent ecosystems by leveraging ready-made solutions. + +```mermaid +graph TD; + SP[Swarms-Platform] --> Discover[Discover Agents] + SP --> Buy[Buy Agents] + SP --> Sell[Sell Agents] ``` -### Example 3: Converting an Artifact to and from a Dictionary +#### Extending the Ecosystem: **Swarms Core**, **JS**, and More -```python -# Convert the artifact to a dictionary -artifact_dict = artifact.to_dict() +In addition to the core components, the Swarms Ecosystem offers several other powerful packages: -# Create a new artifact from the dictionary -new_artifact = Artifact.from_dict(artifact_dict) +- **[Swarms Core](https://github.com/kyegomez/swarms)**: Built in Rust, Swarms Core handles concurrency, multi-threading, and execution strategies. +- **[Swarms JS](https://github.com/The-Swarm-Corporation/swarm-js)**: Allows JavaScript-based orchestration of multi-agent systems. +- **[Swarms Memory](https://github.com/The-Swarm-Corporation/swarm-memory)**: Provides Retrieval Augmented Generation (RAG) systems for long-term memory in agents. +- **[Swarms Evals](https://github.com/The-Swarm-Corporation/swarm-evals)**: Used for evaluating the performance of swarms of agents. +- **[Swarms Zero](https://github.com/The-Swarm-Corporation/zero)**: An RPC-based enterprise-grade automation framework. -# Print the metrics of the new artifact -print(new_artifact.get_metrics()) +```mermaid +graph TD; + SC[Swarms Core] --> Rust[Rust for Performance] + JS[Swarms JS] --> MultiAgent[Multi-Agent Orchestration] + Memory[Swarms Memory] --> RAG[Retrieval Augmented Generation] + Evals[Swarms Evals] --> Evaluation[Agent Evaluations] + Zero[Swarms Zero] --> Automation[Enterprise Automation] ``` +### Conclusion --------------------------------------------------- +The Swarms Ecosystem is a comprehensive, flexible, and scalable platform for managing and deploying autonomous agents. Whether you’re working with LLMs, IoT data, or building new models, the ecosystem provides the tools necessary to simplify automation at scale. -# File: swarms/changelog/5_6_8.md +Start exploring the possibilities by checking out the [Swarms Ecosystem GitHub repository](https://github.com/The-Swarm-Corporation/swarm-ecosystem) and join our growing community of developers and innovators. -# Swarms ChangeLog 5.6.8 - -The biggest update in Swarms history! We've introduced major fixes, updates, and new features to enhance your agent workflows and performance. To get the latest updates run the following: -## Installation +-------------------------------------------------- -```bash -$ pip3 install -U swarms -``` +# File: swarms\concept\vision.md -# Log -Here’s the breakdown of the latest changes: +# Swarms – The Ultimate Multi-Agent LLM Framework for Developers ---- +Swarms aims to be the definitive and most reliable multi-agent LLM framework, offering developers the tools to automate business operations effortlessly. It provides a vast array of swarm architectures, seamless third-party integration, and unparalleled ease of use. With Swarms, developers can orchestrate intelligent, scalable agent ecosystems that can automate complex business processes. -### 🐞 **Fixes:** -- **[BUGF-AGENTS]:** Fixed various response issues within agents, leading to smoother performance. -- **[BUGF-MIXTURE]:** Resolved issues with the Mixture of Agents, ensuring more reliable and stable execution. -- **[CLEA-FILES]:** Removed unnecessary files, resulting in a significant speed boost and cleaner environment. +### Key Features for Developers: +1. **Architectural Flexibility** – Choose from a wide variety of pre-built swarm architectures or build custom agent frameworks. Swarms allows developers to define flexible workflows for specific use cases, providing both sequential and concurrent task execution. +2. **Third-Party Integration** – Swarms makes it simple to integrate with external APIs, databases, and other platforms. By supporting extreme integration capabilities, it ensures your agents work effortlessly within any workflow. +3. **Developer-Centric APIs** – The Swarms API is built with developers in mind, offering an intuitive, simple-to-use interface. Developers can orchestrate agent swarms with minimal code and maximum control. --- -### 🛠 **Updates:** -- **[REFA-MODULES]:** Refactored the `swarms.models` module into its own package: `swarm_models` for improved code organization. -- **[CLEA-AGENTS]:** Cleaned up tool logic in the `agents` class for streamlined and efficient operations. - ---- +### Code Examples -### ✨ **New Features:** -- **[FEAT-SWARMS]:** Introduced JSON outputs for `AgentRearrange`, `SpreadsheetSwarm`, and other swarms, improving data handling. -- **[FEAT-AGENTS]:** Added YAML file support for creating agents, making the setup process simpler than ever. -- **[FEAT-METADATA]:** Enhanced the `Agent` class with JSON metadata output, supporting OpenAI-like API responses with `output_type="json"` and `return_step_meta=True`. -- **[FEAT-FOREST]:** Released `ForestSwarm`, a new architecture that clusters agents into trees, enabling precise task execution. -- **[FEAT-REGISTRY]:** Fully implemented `AgentRegistry`, allowing you to store multiple agents for future use. +#### 1. Basic Financial Analysis Agent: +This example demonstrates a simple financial agent setup that responds to financial questions, such as establishing a ROTH IRA, using OpenAI's GPT-based model. ---- +```python +from swarms.structs.agent import Agent +from swarms.prompts.finance_agent_sys_prompt import FINANCIAL_AGENT_SYS_PROMPT -### 🚀 **Performance Enhancements:** -- **[PERF-AGENTS]:** Accelerated agent execution by **4x**, with a **10x** boost coming soon, powered by our Rust backend. -- **[PERF-ARCH]:** Optimized multi-threading, concurrency, and asynchrony in swarm architectures, making them faster than ever. +# Initialize the Financial Analysis Agent with GPT-4o-mini model +agent = Agent( + agent_name="Financial-Analysis-Agent", + system_prompt=FINANCIAL_AGENT_SYS_PROMPT, + model_name="gpt-4o-mini", + max_loops=1, + autosave=True, + dashboard=False, + verbose=True, + dynamic_temperature_enabled=True, + saved_state_path="finance_agent.json", + user_name="swarms_corp", + retry_attempts=1, + context_length=200000, + return_step_meta=False, +) ---- +# Example task for the agent +out = agent.run( + "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?" +) -**Ready to dive in?** Get started now: [https://buff.ly/444kDjA](https://buff.ly/444kDjA) +# Output the result +print(out) +``` +#### 2. Agent Orchestration with AgentRearrange: +The following example showcases how to use the `AgentRearrange` class to manage a multi-agent system. It sets up a director agent to orchestrate two workers—one to generate a transcript and another to summarize it. --------------------------------------------------- +```python +from swarms.structs.agent import Agent +from swarms.structs.rearrange import AgentRearrange -# File: swarms/changelog/5_8_1.md +# Initialize the Director agent using Anthropic model via model_name +director = Agent( + agent_name="Director", + system_prompt="You are a Director agent. Your role is to coordinate and direct tasks for worker agents. Break down complex tasks into clear, actionable steps.", + model_name="claude-3-sonnet-20240229", + max_loops=1, + dashboard=False, + streaming_on=False, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="director.json", +) -# Swarms 5.8.1 Feature Documentation +# Worker 1: transcript generation +worker1 = Agent( + agent_name="Worker1", + system_prompt="You are a content creator agent. Your role is to generate detailed, engaging transcripts for YouTube videos about technical topics. Focus on clarity and educational value.", + model_name="claude-3-sonnet-20240229", + max_loops=1, + dashboard=False, + streaming_on=False, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="worker1.json", +) -## 1. Enhanced Command Line Interface (CLI) +# Worker 2: summarization +worker2 = Agent( + agent_name="Worker2", + system_prompt="You are a summarization agent. Your role is to create concise, clear summaries of technical content while maintaining key information and insights.", + model_name="claude-3-sonnet-20240229", + max_loops=1, + dashboard=False, + streaming_on=False, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="worker2.json", +) -### 1.1 Integrated Onboarding Process +# Orchestrate the agents in sequence +agents = [director, worker1, worker2] +flow = "Director -> Worker1 -> Worker2" +agent_system = AgentRearrange(agents=agents, flow=flow) -```bash -$ swarms onboarding +# Run the workflow +output = agent_system.run( + "Create a format to express and communicate swarms of LLMs in a structured manner for YouTube" +) +print(output) ``` -### 1.2 Run Agents Command +#### 1. Basic Agent Flow: +Here’s a visual representation of the basic workflow using Mermaid to display the sequential flow between agents. -```bash -$ swarms run-agents --yaml-file agents.yaml +```mermaid +flowchart TD + A[Director] --> B[Worker 1: Generate Transcript] + B --> C[Worker 2: Summarize Transcript] ``` -This command allows users to execute multiple agents defined in a YAML file. Here's the process: - -1. The command reads the specified YAML file (`agents.yaml` in this case). -2. It parses the YAML content, extracting the configuration for each agent. -3. For each agent defined in the YAML: - - It creates an instance of the agent with the specified parameters. - - It sets up the agent's environment (model, temperature, max tokens, etc.). - - It assigns the given task to the agent. - - It executes the agent, respecting parameters like `max_loops`, `autosave`, and `verbose`. -4. The results from all agents are collected and presented to the user. - -The YAML file structure allows users to define multiple agents with different configurations, making it easy to run complex, multi-agent tasks from the command line. +In this diagram: +- The **Director** agent assigns tasks. +- **Worker 1** generates a transcript for a YouTube video. +- **Worker 2** summarizes the transcript. -### 1.3 Generate Prompt Feature +#### 2. Sequential Agent Flow: +This diagram showcases a sequential agent setup where one agent completes its task before the next agent starts its task. -```bash -$ swarms generate-prompt --prompt "Create a marketing strategy for a new product launch" +```mermaid +flowchart TD + A[Director] --> B[Worker 1: Generate Transcript] + B --> C[Worker 2: Summarize Transcript] + C --> D[Worker 3: Finalize] ``` -This feature leverages Swarms' language model to generate expanded or refined prompts: +In this setup: -1. The command takes the user's input prompt as a starting point. -2. It likely sends this prompt to a pre-configured language model (possibly GPT-4 or a similar model). -3. The model then generates an expanded or more detailed version of the prompt. -4. The generated prompt is returned to the user, possibly with options to further refine or save it. +- The **Director** agent assigns tasks to **Worker 1**, which generates a transcript for a YouTube video. -This feature can help users create more effective prompts for their agents or other AI tasks. +- **Worker 1** completes its task before **Worker 2** starts summarizing the transcript. -## 2. New Prompt Management System +- **Worker 2** completes its task before **Worker 3** finalizes the process. -### 2.1 Prompt Class +### Why Developers Should Choose Swarms: -The new `Prompt` class provides a robust system for managing and versioning prompts: +Swarms is designed with flexibility at its core. Developers can create custom architectures and workflows, enabling extreme control over how agents interact with each other. Whether it’s a linear process or a complex mesh of agent communications, Swarms handles it efficiently. -```python -from swarms import Prompt +With support for extreme third-party integration, Swarms makes it easy for developers to plug into external systems, such as APIs or internal databases. This allows agents to act on live data, process external inputs, and execute actions in real time, making it a powerful tool for real-world applications. -marketing_prompt = Prompt(content="Initial marketing strategy draft", autosave=True) +Swarms abstracts the complexity of managing multiple agents with orchestration tools like `AgentRearrange`. Developers can define workflows that execute tasks concurrently or sequentially, depending on the problem at hand. This makes it easy to build and maintain large-scale automation systems. -print(marketing_prompt.get_prompt()) -``` +### Conclusion: +Swarms is not just another multi-agent framework; it's built specifically for developers who need powerful tools to automate complex, large-scale business operations. With flexible architecture, deep integration capabilities, and developer-friendly APIs, Swarms is the ultimate solution for businesses looking to streamline operations and future-proof their workflows. -Key features of the `Prompt` class: +-------------------------------------------------- -1. **Initialization**: The class is initialized with initial content and an `autosave` option. +# File: swarms\concept\why.md -2. **Editing**: - ```python - marketing_prompt.edit_prompt("Updated marketing strategy with social media focus") - ``` - This method updates the prompt content and, if `autosave` is True, automatically saves the new version. +**Maximizing Enterprise Automation: Overcoming the Limitations of Individual AI Agents Through Multi-Agent Collaboration** -3. **Retrieval**: - ```python - current_content = marketing_prompt.get_prompt() - ``` - This method returns the current content of the prompt. -4. **Version History**: - ```python - print(f"Edit history: {marketing_prompt.edit_history}") - ``` - The class maintains a history of edits, allowing users to track changes over time. +In today's rapidly evolving business landscape, enterprises are constantly seeking innovative solutions to enhance efficiency, reduce operational costs, and maintain a competitive edge. Automation has emerged as a critical strategy for achieving these objectives, with artificial intelligence (AI) playing a pivotal role. AI agents, particularly those powered by advanced machine learning models, have shown immense potential in automating a variety of tasks. However, individual AI agents come with inherent limitations that hinder their ability to fully automate complex enterprise operations at scale. -5. **Rollback**: - ```python - marketing_prompt.rollback(1) - ``` - This feature allows users to revert to a previous version of the prompt. +This essay dives into the specific limitations of individual AI agents—context window limits, hallucination, single-task execution, lack of collaboration, lack of accuracy, and slow processing speed—and explores how multi-agent collaboration can overcome these challenges. By tailoring our discussion to the needs of enterprises aiming to automate operations at scale, we highlight practical strategies and frameworks that can be adopted to unlock the full potential of AI-driven automation. -6. **Duplicate Prevention**: - The class includes logic to prevent duplicate edits, raising a `ValueError` if an attempt is made to save the same content twice in a row. +--- -This system provides a powerful way to manage prompts, especially for complex projects where prompt engineering and iteration are crucial. +### Part 1: The Limitations of Individual AI Agents -## 3. Upcoming Features Preview +Despite significant advancements, individual AI agents face several obstacles that limit their effectiveness in enterprise automation. Understanding these limitations is crucial for organizations aiming to implement AI solutions that are both efficient and scalable. -### 3.1 Enhanced Agent Execution Capabilities +#### 1. Context Window Limits -The preview code demonstrates planned enhancements for agent execution: +**Explanation** -```python -from swarms import Agent, ExecutionEnvironment +AI agents, especially those based on language models like GPT-3 or GPT-4, operate within a fixed context window. This means they can only process and consider a limited amount of information (tokens) at a time. In practical terms, this restricts the agent's ability to handle large documents, long conversations, or complex datasets that exceed their context window. -my_agent = Agent(name="data_processor") +**Impact on Enterprises** -cpu_env = ExecutionEnvironment(type="cpu", cores=4) -my_agent.run(environment=cpu_env) +For enterprises, this limitation poses significant challenges. Business operations often involve processing extensive documents such as legal contracts, technical manuals, or large datasets. An AI agent with a limited context window may miss crucial information located outside its immediate context, leading to incomplete analyses or erroneous conclusions. -gpu_env = ExecutionEnvironment(type="gpu", device_id=0) -my_agent.run(environment=gpu_env) -fractional_env = ExecutionEnvironment(type="fractional", cpu_fraction=0.5, gpu_fraction=0.3) -my_agent.run(environment=fractional_env) +```mermaid +graph LR + subgraph "Context Window Limit" + Input[Large Document] + Agent[AI Agent] + Output[Partial Understanding] + Input -- Truncated Data --> Agent + Agent -- Generates --> Output + end ``` -This upcoming feature will allow for more fine-grained control over the execution environment: - -1. **CPU Execution**: Users can specify the number of CPU cores to use. -2. **GPU Execution**: Allows selection of a specific GPU device. -3. **Fractionalized Execution**: Enables partial allocation of CPU and GPU resources. +*An AI agent processes only a portion of a large document due to context window limits, resulting in partial understanding.* -These features will provide users with greater flexibility in resource allocation, potentially improving performance and allowing for more efficient use of available hardware. +#### 2. Hallucination --------------------------------------------------- +**Explanation** -# File: swarms/changelog/6_0_0 2.md +Hallucination refers to the tendency of AI agents to produce outputs that are not grounded in the input data or reality. They may generate plausible-sounding but incorrect or nonsensical information, especially when uncertain or when the input data is ambiguous. -# Swarms 6.0.0 - Performance & Reliability Update 🚀 +**Impact on Enterprises** -We're excited to announce the release of Swarms 6.0.0, bringing significant improvements to performance, reliability, and developer experience. This release focuses on streamlining core functionalities while enhancing the overall stability of the framework. +In enterprise settings, hallucinations can lead to misinformation, poor decision-making, and a lack of trust in AI systems. For instance, if an AI agent generates incorrect financial forecasts or misinterprets regulatory requirements, the consequences could be financially damaging and legally problematic. -## 📦 Installation -```bash -pip3 install -U swarms +```mermaid +graph TD + Input[Ambiguous Data] + Agent[AI Agent] + Output[Incorrect Information] + Input --> Agent + Agent --> Output ``` -## 🌟 Highlights - -### Agent Enhancements -- **Improved RAG Performance**: Significant improvements to Retrieval-Augmented Generation capabilities -- **Enhanced Prompt Generation**: Auto-generate prompt now incorporates name, description, and system prompt for more contextual interactions -- **Streamlined Architecture**: Cleaned up unused code for better performance and maintainability -- **Simplified State Management**: Consolidated state management methods into a single `load()` function - -### Tools & Execution -- **Optimized Environment Management**: Fixed multiple environment instantiation issue - - Environments now initialize once during `__init__` -- **New SwarmRouter Function**: Simplified routing mechanism - - Returns consolidated string output from all agents - - Improved coordination between swarm components +*An AI agent generates incorrect information (hallucination) when processing ambiguous data.* -## 💪 Performance Improvements -- Faster execution times -- Reduced memory footprint -- More reliable logging system -- Lightweight and efficient codebase +#### 3. Single Task Execution -## 🤝 Join Our Community +**Explanation** -### We're Hiring! -Join our growing team! We're currently looking for: -- Agent Engineers -- Developer Relations -- Infrastructure Engineers -- And more! +Many AI agents are designed to excel at a specific task or a narrow set of functions. They lack the flexibility to perform multiple tasks simultaneously or adapt to new tasks without significant reconfiguration or retraining. -### Get Involved -- ⭐ Star our repository -- 🔄 Fork the project -- 🛠 Submit pull requests -- 🐛 Report issues -- 💡 Share your ideas +**Impact on Enterprises** -### Contact & Support -- 📧 Email: kye@swarms.world -- 🔗 Issues: [GitHub Issues](https://github.com/kyegomez/swarms/issues) +Enterprises require systems that can handle a variety of tasks, often concurrently. Relying on single-task agents necessitates deploying multiple separate agents, which can lead to integration challenges, increased complexity, and higher maintenance costs. -## 🔜 What's Next? -Have ideas for features, bug fixes, or improvements? We'd love to hear from you! Reach out through our GitHub issues or email us directly. ---- +```mermaid +graph LR + TaskA[Task A] --> AgentA[Agent A] + TaskB[Task B] --> AgentB[Agent B] + AgentA --> OutputA[Result A] + AgentB --> OutputB[Result B] +``` -*Thank you to all our contributors and users who make Swarms better every day. Together, we're building the future of swarm intelligence.* +*Separate agents handle different tasks independently, lacking integration.* -#SwarmAI #OpenSource #AI #MachineLearning +#### 4. Lack of Collaboration --------------------------------------------------- +**Explanation** -# File: swarms/changelog/6_0_0.md +Individual AI agents typically operate in isolation, without the ability to communicate or collaborate with other agents. This siloed operation prevents them from sharing insights, learning from each other, or coordinating actions to achieve a common goal. -# Swarms 6.0.0 - Performance & Reliability Update 🚀 +**Impact on Enterprises** -We're excited to announce the release of Swarms 6.0.0, bringing significant improvements to performance, reliability, and developer experience. This release focuses on streamlining core functionalities while enhancing the overall stability of the framework. +Complex enterprise operations often require coordinated efforts across different functions and departments. The inability of AI agents to collaborate limits their effectiveness in such environments, leading to disjointed processes and suboptimal outcomes. -## 📦 Installation -```bash -pip3 install -U swarms +```mermaid +graph LR + Agent1[Agent 1] + Agent2[Agent 2] + Agent3[Agent 3] + Agent1 -->|No Communication| Agent2 + Agent2 -->|No Communication| Agent3 ``` -## 🌟 Highlights +*Agents operate without collaboration, resulting in isolated efforts.* -### Agent Enhancements -- **Improved RAG Performance**: Significant improvements to Retrieval-Augmented Generation capabilities -- **Enhanced Prompt Generation**: Auto-generate prompt now incorporates name, description, and system prompt for more contextual interactions -- **Streamlined Architecture**: Cleaned up unused code for better performance and maintainability -- **Simplified State Management**: Consolidated state management methods into a single `load()` function +#### 5. Lack of Accuracy -### Tools & Execution -- **Optimized Environment Management**: Fixed multiple environment instantiation issue - - Environments now initialize once during `__init__` -- **New SwarmRouter Function**: Simplified routing mechanism - - Returns consolidated string output from all agents - - Improved coordination between swarm components +**Explanation** -## 💪 Performance Improvements -- Faster execution times -- Reduced memory footprint -- More reliable logging system -- Lightweight and efficient codebase +AI agents may produce inaccurate results due to limitations in their training data, algorithms, or inability to fully understand complex inputs. Factors such as data bias, overfitting, or lack of domain-specific knowledge contribute to this inaccuracy. -## 🤝 Join Our Community +**Impact on Enterprises** -### We're Hiring! -Join our growing team! We're currently looking for: -- Agent Engineers -- Developer Relations -- Infrastructure Engineers -- And more! +Inaccurate outputs can have serious ramifications for businesses, including flawed strategic decisions, customer dissatisfaction, and compliance risks. High accuracy is essential for tasks like financial analysis, customer service, and regulatory compliance. -### Get Involved -- ⭐ Star our repository -- 🔄 Fork the project -- 🛠 Submit pull requests -- 🐛 Report issues -- 💡 Share your ideas -### Contact & Support -- 📧 Email: kye@swarms.world -- 🔗 Issues: [GitHub Issues](https://github.com/kyegomez/swarms/issues) +```mermaid +graph TD + Input[Complex Data] + Agent[AI Agent] + Output[Inaccurate Result] + Input --> Agent + Agent --> Output +``` -## 🔜 What's Next? -Have ideas for features, bug fixes, or improvements? We'd love to hear from you! Reach out through our GitHub issues or email us directly. +*An AI agent produces an inaccurate result when handling complex data.* ---- +#### 6. Slow Processing Speed -*Thank you to all our contributors and users who make Swarms better every day. Together, we're building the future of swarm intelligence.* +**Explanation** -#SwarmAI #OpenSource #AI #MachineLearning +Some AI agents require significant computational resources and time to process data and generate outputs. Factors like model complexity, inefficient algorithms, or hardware limitations can contribute to slow processing speeds. --------------------------------------------------- +**Impact on Enterprises** -# File: swarms/changelog/changelog_new.md +Slow processing impedes real-time decision-making and responsiveness. In fast-paced business environments, delays can lead to missed opportunities, reduced productivity, and competitive disadvantages. -# 🚀 Swarms 5.9.2 Release Notes +```mermaid +graph TD + Input[Data] + Agent[AI Agent] + Delay[Processing Delay] + Output[Delayed Response] + Input --> Agent + Agent --> Delay + Delay --> Output +``` -### 🎯 Major Features +*An AI agent's slow processing leads to delayed responses.* -#### Concurrent Agent Execution Suite -We're excited to introduce a comprehensive suite of agent execution methods to supercharge your multi-agent workflows: +--- -- `run_agents_concurrently`: Execute multiple agents in parallel with optimal resource utilization -- `run_agents_concurrently_async`: Asynchronous execution for improved performance -- `run_single_agent`: Streamlined single agent execution -- `run_agents_concurrently_multiprocess`: Multi-process execution for CPU-intensive tasks -- `run_agents_sequentially`: Sequential execution with controlled flow -- `run_agents_with_different_tasks`: Assign different tasks to different agents -- `run_agent_with_timeout`: Time-bounded agent execution -- `run_agents_with_resource_monitoring`: Monitor and manage resource usage +### Part 2: Overcoming Limitations Through Multi-Agent Collaboration -### 📚 Documentation -- Comprehensive documentation added for all new execution methods -- Updated examples and usage patterns -- Enhanced API reference +To address the challenges posed by individual AI agents, enterprises can adopt a multi-agent collaboration approach. By orchestrating multiple agents with complementary skills and functionalities, organizations can enhance performance, accuracy, and scalability in their automation efforts. -### 🛠️ Improvements -- Tree swarm implementation fixes -- Workspace directory now automatically set to `agent_workspace` -- Improved error handling and stability +#### 1. Extending Context Window Through Distributed Processing -## Quick Start +**Solution** -```python -from swarms import Agent, run_agents_concurrently, run_agents_with_timeout, run_agents_with_different_tasks +By dividing large inputs into smaller segments, multiple agents can process different parts simultaneously. A coordinating agent can then aggregate the results to form a comprehensive understanding. -# Initialize multiple agents -agents = [ - Agent( - agent_name=f"Analysis-Agent-{i}", - system_prompt="You are a financial analysis expert", - llm=model, - max_loops=1 - ) - for i in range(5) -] +**Implementation in Enterprises** -# Run agents concurrently -task = "Analyze the impact of rising interest rates on tech stocks" -outputs = run_agents_concurrently(agents, task) +- **Document Analysis:** For lengthy legal contracts, agents can each analyze specific sections, and a master agent can compile insights and ensure consistency. +- **Customer Interaction History:** In customer service, agents can handle different segments of a customer's history to provide personalized support. -# Example with timeout -outputs_with_timeout = run_agents_with_timeout( - agents=agents, - task=task, - timeout=30.0, - batch_size=2 -) -# Run different tasks -task_pairs = [ - (agents[0], "Analyze tech stocks"), - (agents[1], "Analyze energy stocks"), - (agents[2], "Analyze retail stocks") -] -different_outputs = run_agents_with_different_tasks(task_pairs) +```mermaid +graph LR + Input[Large Document] + Splitter[Splitter Agent] + A1[Agent 1] + A2[Agent 2] + A3[Agent 3] + Aggregator[Aggregator Agent] + Output[Comprehensive Analysis] + Input --> Splitter + Splitter --> A1 + Splitter --> A2 + Splitter --> A3 + A1 --> Aggregator + A2 --> Aggregator + A3 --> Aggregator + Aggregator --> Output ``` -## Installation -```bash -pip3 install -U swarms -``` +*Multiple agents process segments of a large document, and results are aggregated.* -## Coming Soon -- 🌟 Auto Swarm Builder: Automatically construct and configure entire swarms from a single task specification (in development) -- Auto Prompt Generator for thousands of agents (in development) +#### 2. Reducing Hallucination Through Cross-Verification -## Community -We believe in the power of community-driven development. Help us make Swarms better! +**Solution** -- ⭐ Star our repository: https://github.com/kyegomez/swarms -- 🔄 Fork the project and contribute your improvements -- 🤝 Join our growing community of contributors +Agents can verify each other's outputs by cross-referencing information and flagging inconsistencies. Implementing consensus mechanisms ensures that only accurate information is accepted. -## Bug Fixes -- Fixed Tree Swarm implementation issues -- Resolved workspace directory configuration problems -- General stability improvements +**Implementation in Enterprises** ---- +- **Data Validation:** In data entry automation, one agent inputs data while another validates it against source documents. +- **Decision Support Systems:** Multiple agents evaluate options and agree on recommendations, reducing the risk of incorrect advice. -For detailed documentation and examples, visit our [GitHub repository](https://github.com/kyegomez/swarms). -Let's build the future of multi-agent systems together! 🚀 +```mermaid +graph TD + A[Agent's Output] + V1[Verifier Agent 1] + V2[Verifier Agent 2] + Consensus[Consensus Mechanism] + Output[Validated Output] + A --> V1 + A --> V2 + V1 & V2 --> Consensus + Consensus --> Output +``` --------------------------------------------------- +*Agents verify outputs through cross-verification and consensus.* -# File: swarms/cli/cli_guide.md +#### 3. Enhancing Multi-Tasking Through Specialized Agents -# The Ultimate Technical Guide to the Swarms CLI: A Step-by-Step Developer’s Guide +**Solution** -Welcome to the definitive technical guide for using the Swarms Command Line Interface (CLI). The Swarms CLI enables developers, engineers, and business professionals to seamlessly manage and run Swarms of agents from the command line. This guide will walk you through the complete process of installing, configuring, and using the Swarms CLI to orchestrate intelligent agents for your needs. +Deploy specialized agents for different tasks and enable them to work concurrently. An orchestrator agent manages task allocation and workflow integration. -By following this guide, you will not only understand how to install and use the Swarms CLI but also learn about real-world use cases, including how the CLI is used to automate tasks across various industries, from finance to marketing, operations, and beyond. +**Implementation in Enterprises** -Explore the official [Swarms GitHub repository](https://github.com/kyegomez/swarms), dive into the comprehensive documentation at [Swarms Docs](https://docs.swarms.world), and explore the vast marketplace of agents on [swarms.ai](https://swarms.ai) to kickstart your journey with Swarms! +- **Automated Workflows:** In supply chain management, one agent handles inventory analysis, another manages logistics, and a third forecasts demand. +- **IT Operations:** In IT automation, separate agents manage network monitoring, security scanning, and system updates. ---- -## 1. Installing the Swarms CLI +```mermaid +graph LR + Task[Complex Task] + Orchestrator[Orchestrator Agent] + AgentA[Specialist Agent A] + AgentB[Specialist Agent B] + AgentC[Specialist Agent C] + Output[Integrated Solution] + Task --> Orchestrator + Orchestrator --> AgentA + Orchestrator --> AgentB + Orchestrator --> AgentC + AgentA & AgentB & AgentC --> Orchestrator + Orchestrator --> Output +``` -Before we explore the Swarms CLI commands, let’s get it installed and running on your machine. +*Specialized agents handle different tasks under the management of an orchestrator agent.* -### 1.1. Installation Using `pip` +#### 4. Facilitating Collaboration Through Communication Protocols -For most users, the simplest way to install the Swarms CLI is through `pip`: +**Solution** -```bash -pip3 install -U swarms -``` +Implement communication protocols that allow agents to share information, request assistance, and coordinate actions. This fosters a collaborative environment where agents complement each other's capabilities. -This command installs the latest version of the Swarms CLI package, ensuring that you have the newest features and fixes. +**Implementation in Enterprises** -### 1.2. Installation Using `Poetry` +- **Customer Service:** Chatbots and virtual assistants share customer data to provide seamless support across channels. +- **Project Management:** Agents managing different aspects of a project (scheduling, resource allocation, risk assessment) coordinate to keep the project on track. -Alternatively, if you are using `Poetry` as your Python package manager, you can add the Swarms package like this: -```bash -poetry add swarms +```mermaid +graph LR + Agent1[Agent 1] + Agent2[Agent 2] + Agent3[Agent 3] + Agent1 <--> Agent2 + Agent2 <--> Agent3 + Agent3 <--> Agent1 + Output[Collaborative Outcome] ``` -Once installed, you can run the Swarms CLI directly using: - -```bash -poetry run swarms help -``` +*Agents communicate and collaborate to achieve a common goal.* -This command shows all the available options and commands, as we will explore in-depth below. +#### 5. Improving Accuracy Through Ensemble Learning ---- +**Solution** -## 2. Understanding Swarms CLI Commands +Use ensemble methods where multiple agents provide predictions or analyses, and a meta-agent combines these to produce a more accurate result. -With the Swarms CLI installed, the next step is to explore its key functionalities. Here are the most essential commands: +**Implementation in Enterprises** -### 2.1. `onboarding`: Setup Your Environment +- **Risk Assessment:** Different agents assess risks from various perspectives (financial, operational, compliance), and their insights are combined. +- **Market Analysis:** Agents analyze market trends, customer behavior, and competitor actions, leading to a comprehensive market strategy. -The `onboarding` command guides you through setting up your environment and configuring the agents for your Swarms. -```bash -swarms onboarding +```mermaid +graph TD + AgentA[Agent A Output] + AgentB[Agent B Output] + AgentC[Agent C Output] + MetaAgent[Meta-Agent] + Output[Enhanced Accuracy] + AgentA --> MetaAgent + AgentB --> MetaAgent + AgentC --> MetaAgent + MetaAgent --> Output ``` -This is the first step when you begin working with the Swarms platform. It helps to: - -- Authenticate your Swarms account. -- Download any necessary configurations. -- Ensure everything is in place to launch agents seamlessly. - -### 2.2. `help`: Learn Available Commands - -Running `help` displays the various commands you can use: +*Meta-agent combines outputs from multiple agents to improve accuracy.* -```bash -swarms help -``` +#### 6. Increasing Processing Speed Through Parallelization -This command will output a helpful list like the one shown below, including detailed descriptions of each command. +**Solution** -```plaintext -Swarms CLI - Help +By distributing workloads among multiple agents operating in parallel, processing times are significantly reduced, enabling real-time responses. -Commands: -onboarding : Starts the onboarding process -help : Shows this help message -get-api-key : Retrieves your API key from the platform -check-login : Checks if you're logged in and starts the cache -read-docs : Redirects you to swarms cloud documentation -run-agents : Run your Agents from your agents.yaml -``` +**Implementation in Enterprises** -### 2.3. `get-api-key`: Access API Integration +- **Data Processing:** Large datasets are partitioned and processed simultaneously by different agents. +- **Customer Requests:** Multiple customer inquiries are handled at once by separate agents, improving response times. -One of the key functionalities of the Swarms platform is integrating your agents with the Swarms API. To retrieve your unique API key for communication, use this command: -```bash -swarms get-api-key +```mermaid +graph LR + Data[Large Dataset] + Agent1[Agent 1] + Agent2[Agent 2] + Agent3[Agent 3] + Output[Processed Data] + Data --> Agent1 + Data --> Agent2 + Data --> Agent3 + Agent1 & Agent2 & Agent3 --> Output ``` -Your API key is essential to enable agent workflows and access various services through the Swarms platform. - -### 2.4. `check-login`: Verify Authentication - -Use the `check-login` command to verify if you're logged in and ensure that your credentials are cached: +*Parallel processing by agents leads to faster completion times.* -```bash -swarms check-login -``` +--- -This ensures seamless operation, allowing agents to execute tasks securely on the Swarms platform without needing to log in repeatedly. +### Part 3: Tailoring Multi-Agent Systems for Enterprise Automation at Scale -### 2.5. `read-docs`: Explore Official Documentation +Implementing multi-agent systems in an enterprise context requires careful planning and consideration of organizational needs, technical infrastructure, and strategic goals. Below are key considerations and steps for enterprises aiming to adopt multi-agent collaboration for automation at scale. -Easily access the official documentation with this command: +#### 1. Identifying Automation Opportunities -```bash -swarms read-docs -``` +Enterprises should start by identifying processes and tasks that are suitable for automation through multi-agent systems. Prioritize areas where: -You’ll be redirected to the Swarms documentation site, [Swarms Docs](https://docs.swarms.world), where you'll find in-depth explanations, advanced use-cases, and more. +- **Complexity Requires Specialization:** Tasks that involve multiple steps or require diverse expertise. +- **Scalability Is Essential:** Operations that need to handle increasing workloads efficiently. +- **Speed and Accuracy Are Critical:** Processes where delays or errors have significant impacts. -### 2.6. `run-agents`: Orchestrate Agents +#### 2. Designing the Multi-Agent Architecture -Perhaps the most important command in the CLI is `run-agents`, which allows you to execute your agents as defined in your `agents.yaml` configuration file. +Develop a robust architecture that defines how agents will interact, communicate, and collaborate. Key components include: -```bash -swarms run-agents --yaml-file agents.yaml -``` +- **Agent Specialization:** Define the roles and responsibilities of each agent. +- **Communication Protocols:** Establish standards for information exchange. +- **Coordination Mechanisms:** Implement orchestrator agents or decentralized coordination strategies. +- **Integration with Existing Systems:** Ensure compatibility with current IT infrastructure. -If you want to specify a custom configuration file, just pass in the YAML file using the `--yaml-file` flag. +#### 3. Ensuring Data Security and Compliance ---- +Data security is paramount when agents handle sensitive enterprise information. Implement measures such as: -## 3. Working with the `agents.yaml` Configuration File +- **Encryption:** Secure communication channels between agents. +- **Access Control:** Define permissions for data access and agent capabilities. +- **Compliance Checks:** Ensure the system adheres to relevant regulations (e.g., GDPR, HIPAA). -The `agents.yaml` file is at the heart of your Swarms setup. This file allows you to define the structure and behavior of each agent you want to run. Below is an example YAML configuration for two agents. +#### 4. Monitoring and Performance Management -### 3.1. Example `agents.yaml` Configuration: +Establish monitoring tools to track agent performance, system health, and outcomes. Key metrics may include: -```yaml -agents: - - agent_name: "Financial-Advisor-Agent" - model: - model_name: "gpt-4o-mini" - temperature: 0.3 - max_tokens: 2500 - system_prompt: | - You are a highly knowledgeable financial advisor with expertise in tax strategies, investment management, and retirement planning. - Provide concise and actionable advice based on the user's financial goals and situation. - max_loops: 1 - autosave: true - dashboard: false - verbose: true - dynamic_temperature_enabled: true - saved_state_path: "financial_advisor_state.json" - user_name: "finance_user" - retry_attempts: 2 - context_length: 200000 - return_step_meta: false - output_type: "str" - task: "I am 35 years old with a moderate risk tolerance. How should I diversify my portfolio for retirement in 20 years?" +- **Processing Speed:** Measure how quickly tasks are completed. +- **Accuracy Rates:** Track the correctness of outputs. +- **Resource Utilization:** Monitor computational resources used by agents. +- **Error Logs:** Identify and address failures or exceptions. - - agent_name: "Stock-Market-Analysis-Agent" - model: - model_name: "gpt-4o-mini" - temperature: 0.25 - max_tokens: 1800 - system_prompt: | - You are an expert stock market analyst with a deep understanding of technical analysis, market trends, and long-term investment strategies. - Provide well-reasoned investment advice, taking current market conditions into account. - max_loops: 2 - autosave: true - dashboard: false - verbose: true - dynamic_temperature_enabled: false - saved_state_path: "stock_market_analysis_state.json" - user_name: "market_analyst" - retry_attempts: 3 - context_length: 150000 - return_step_meta: true - output_type: "json" - task: "Analyze the current market trends for tech stocks and suggest the best long-term investment options." +#### 5. Scaling Strategies - - agent_name: "Marketing-Strategy-Agent" - model: - model_name: "gpt-4o-mini" - temperature: 0.4 - max_tokens: 2200 - system_prompt: | - You are a marketing strategist with expertise in digital campaigns, customer engagement, and branding. - Provide a comprehensive marketing strategy to increase brand awareness and drive customer acquisition for an e-commerce business. - max_loops: 1 - autosave: true - dashboard: false - verbose: true - dynamic_temperature_enabled: true - saved_state_path: "marketing_strategy_state.json" - user_name: "marketing_user" - retry_attempts: 2 - context_length: 200000 - return_step_meta: false - output_type: "str" - task: "Create a 6-month digital marketing strategy for a new eco-friendly e-commerce brand targeting millennial consumers." +Develop strategies for scaling the system as enterprise needs grow, including: - - agent_name: "Operations-Optimizer-Agent" - model: - model_name: "gpt-4o-mini" - temperature: 0.2 - max_tokens: 2000 - system_prompt: | - You are an operations expert with extensive experience in optimizing workflows, reducing costs, and improving efficiency in supply chains. - Provide actionable recommendations to streamline business operations. - max_loops: 1 - autosave: true - dashboard: false - verbose: true - dynamic_temperature_enabled: true - saved_state_path: "operations_optimizer_state.json" - user_name: "operations_user" - retry_attempts: 1 - context_length: 200000 - return_step_meta: false - output_type: "str" - task: "Identify ways to improve the efficiency of a small manufacturing company’s supply chain to reduce costs by 15% within one year." -``` +- **Dynamic Resource Allocation:** Adjust computational resources based on workload. +- **Agent Addition or Removal:** Add new agents or deactivate others to meet changing demands. +- **Load Balancing:** Distribute tasks evenly to prevent bottlenecks. -### 3.2. Explanation of Key Fields +#### 6. Continuous Improvement -- **agent_name**: The name of your agent (e.g., Financial-Analysis-Agent). -- **model**: Specifies which model to use. In this case, `gpt-4o-mini` is used. - - **temperature**: Controls the randomness of the model’s responses. - - **max_tokens**: The maximum number of tokens to generate. -- **system_prompt**: Defines the prompt that instructs the agent. -- **max_loops**: Limits the number of times the agent will retry tasks. -- **autosave**: Saves the agent's state automatically after each run. -- **dashboard**: Set to `true` or `false` depending on whether you want to enable the agent’s dashboard. -- **saved_state_path**: Path to save agent's state, enabling future runs to resume from the last state. -- **task**: The primary task or question that the agent will address. +Implement feedback loops for ongoing enhancement of the multi-agent system: -### 3.3. Running Agents Using `agents.yaml` +- **User Feedback:** Gather input from users interacting with the system. +- **Performance Analytics:** Analyze data to identify areas for optimization. +- **Updating Agents:** Regularly update agent algorithms and knowledge bases. -After configuring the agents, you can execute them directly from the CLI: +--- -```bash -swarms run-agents --yaml-file agents_config.yaml -``` +### Part 4: Case Studies and Real-World Applications -This command will run the specified agents, allowing them to perform their tasks and return results according to your configuration. +To illustrate the practical benefits of multi-agent collaboration in enterprise automation, let's explore several real-world examples. ---- +#### Case Study 1: Financial Services Automation -## 4. Use Cases for the Swarms CLI +**Challenge** -Now that you have a solid understanding of the basic commands and the `agents.yaml` configuration, let's explore how the Swarms CLI can be applied in real-world scenarios. +A financial institution needs to process large volumes of loan applications, requiring data verification, risk assessment, compliance checks, and decision-making. -### 4.1. Financial Data Analysis +**Solution** -For financial firms or hedge funds, agents like the "Financial-Analysis-Agent" can be set up to automate complex financial analyses. You could have agents analyze market trends, recommend portfolio adjustments, or perform tax optimizations. +- **Specialized Agents:** + - **Data Extraction Agent:** Extracts data from application forms. + - **Verification Agent:** Confirms the accuracy of applicant information. + - **Risk Assessment Agent:** Evaluates credit risk using predictive models. + - **Compliance Agent:** Ensures all regulatory requirements are met. + - **Decision Agent:** Aggregates inputs and makes approval decisions. -Example Task: Automating long-term investment analysis using historical stock data. +- **Collaboration:** + - Agents communicate to share data and findings. + - The Decision Agent coordinates the workflow. -```bash -swarms run-agents --yaml-file finance_analysis.yaml -``` +**Outcome** -### 4.2. Marketing Automation +- **Increased Processing Speed:** Applications are processed in minutes instead of days. +- **Improved Accuracy:** Cross-verification reduces errors. +- **Scalability:** System handles fluctuating application volumes efficiently. -Marketing departments can utilize Swarms agents to optimize campaigns, generate compelling ad copy, or provide detailed marketing insights. You can create a `Marketing-Agent` to process customer feedback, perform sentiment analysis, and suggest marketing strategies. +#### Case Study 2: Manufacturing Supply Chain Optimization -Example Task: Running multiple agents to analyze customer sentiment from recent surveys. +**Challenge** -```bash -swarms run-agents --yaml-file marketing_agents.yaml -``` +A manufacturing company wants to optimize its supply chain to reduce costs and improve delivery times. -### 4.3. Operations and Task Management +**Solution** -Companies can create agents for automating internal task management. For example, you might have a set of agents responsible for managing deadlines, employee tasks, and progress tracking. +- **Specialized Agents:** + - **Demand Forecasting Agent:** Predicts product demand. + - **Inventory Management Agent:** Monitors stock levels and orders materials. + - **Logistics Agent:** Plans shipping routes and schedules. + - **Supplier Evaluation Agent:** Assesses supplier performance and reliability. -Example Task: Automating a task management system using Swarms agents. +- **Collaboration:** + - Agents share data on demand forecasts and inventory levels. + - Logistics Agent adjusts plans based on input from other agents. -```bash -swarms run-agents --yaml-file operations_agents.yaml -``` +**Outcome** ---- +- **Cost Reduction:** Optimized inventory levels reduce holding costs. +- **Efficiency Gains:** Improved logistics planning enhances delivery times. +- **Adaptability:** System responds quickly to changes in demand or supply disruptions. -## 5. Advanced Usage: Customizing and Scaling Agents +#### Case Study 3: Healthcare Patient Management -The Swarms CLI is flexible and scalable. As your needs grow, you can start running agents across multiple machines, scale workloads dynamically, and even run multiple swarms in parallel. +**Challenge** -### 5.1. Running Agents in Parallel +A hospital aims to improve patient care coordination, managing appointments, medical records, billing, and treatment plans. -To run multiple agents concurrently, you can utilize different YAML configurations for each agent or group of agents. This allows for extensive scaling, especially when dealing with large datasets or complex workflows. +**Solution** -```bash -swarms run-agents --yaml-file agents_batch_1.yaml & -swar +- **Specialized Agents:** + - **Appointment Scheduling Agent:** Manages patient appointments. + - **Medical Records Agent:** Updates and retrieves patient records. + - **Billing Agent:** Handles invoicing and insurance claims. + - **Treatment Planning Agent:** Assists in developing patient care plans. -ms run-agents --yaml-file agents_batch_2.yaml & -``` +- **Collaboration:** + - Agents coordinate to ensure seamless patient experiences. + - Data is securely shared while maintaining patient confidentiality. -### 5.2. Integration with Other Tools +**Outcome** -The Swarms CLI integrates with many tools and platforms via APIs. You can connect Swarms with external platforms such as AWS, Azure, or your custom cloud setup for enterprise-level automation. +- **Enhanced Patient Care:** Improved coordination leads to better treatment outcomes. +- **Operational Efficiency:** Administrative tasks are streamlined. +- **Compliance:** System adheres to healthcare regulations (e.g., HIPAA). --- -## 6. Conclusion and Next Steps +### Part 5: Implementing Multi-Agent Systems – Best Practices for Enterprises -The Swarms CLI is a powerful tool for automating agent workflows in various industries, including finance, marketing, and operations. By following this guide, you should now have a thorough understanding of how to install and use the CLI, configure agents, and apply it to real-world use cases. +For enterprises embarking on the journey of multi-agent automation, adhering to best practices ensures successful implementation. -To further explore Swarms, be sure to check out the official [Swarms GitHub repository](https://github.com/kyegomez/swarms), where you can contribute to the framework or build your own custom agents. Dive deeper into the documentation at [Swarms Docs](https://docs.swarms.world), and browse the extensive agent marketplace at [swarms.ai](https://swarms.ai). +#### 1. Start Small and Scale Gradually -With the Swarms CLI, the future of automation is within reach. +- **Pilot Projects:** Begin with a specific process or department to test the multi-agent system. +- **Learn and Adapt:** Use insights from initial deployments to refine the system. +#### 2. Invest in Training and Change Management +- **Employee Education:** Train staff on interacting with and managing multi-agent systems. +- **Change Management:** Prepare the organization for changes in workflows and roles. --------------------------------------------------- +#### 3. Leverage Cloud and Edge Computing -# File: swarms/cli/main.md +- **Scalable Infrastructure:** Utilize cloud services for flexible resource allocation. +- **Edge Computing:** Deploy agents closer to data sources for faster processing. -# Swarms CLI Documentation +#### 4. Foster Interoperability -The Swarms Command Line Interface (CLI) allows you to easily manage and run your Swarms of agents from the command line. This page will guide you through the installation process and provide a breakdown of the available commands. +- **Standards Compliance:** Use industry standards for data formats and communication protocols. +- **API Integration:** Ensure agents can integrate with existing enterprise applications. -## Installation +#### 5. Prioritize Ethical Considerations -You can install the `swarms` package using `pip` or `poetry`. +- **Transparency:** Maintain clear documentation of how agents make decisions. +- **Bias Mitigation:** Implement strategies to prevent and correct algorithmic biases. +- **Accountability:** Establish protocols for human oversight and intervention. -### Using pip +--- -```bash -pip3 install -U swarms -``` +### Conclusion -### Using poetry +Enterprises seeking to automate operations at scale face the limitations inherent in individual AI agents. Context window limits, hallucinations, single-task execution, lack of collaboration, lack of accuracy, and slow processing speed hinder the full potential of automation efforts. Multi-agent collaboration emerges as a robust solution to these challenges, offering a pathway to enhanced efficiency, accuracy, scalability, and adaptability. -```bash -poetry add swarms -``` +By adopting multi-agent systems, enterprises can: -Once installed, you can run the Swarms CLI with the following command: +- **Extend Capabilities:** Overcome individual agent limitations through collective intelligence. +- **Improve Outcomes:** Achieve higher accuracy and faster processing by leveraging specialized agents. +- **Enhance Flexibility:** Adapt to changing business needs with scalable and versatile agent architectures. +- **Drive Innovation:** Foster a culture of continuous improvement and technological advancement. -```bash -poetry run swarms help -``` +Implementing multi-agent systems requires thoughtful planning, adherence to best practices, and a commitment to ongoing management and optimization. Enterprises that successfully navigate this journey will position themselves at the forefront of automation, unlocking new levels of productivity and competitive advantage in an increasingly digital world. -## Swarms CLI - Help -When running `swarms help`, you'll see the following output: +-------------------------------------------------- -``` - _________ - / _____/_ _ _______ _______ _____ ______ - \_____ \ \/ \/ /\__ \_ __ \/ \ / ___/ - / \ / / __ \| | \/ Y Y \___ \ -/_______ / \/\_/ (____ /__| |__|_| /____ > - \/ \/ \/ \/ +# File: swarms\contributing.md +# Contribution Guidelines +--- - Swarms CLI - Help +## Table of Contents - Commands: - onboarding : Starts the onboarding process - help : Shows this help message - get-api-key : Retrieves your API key from the platform - check-login : Checks if you're logged in and starts the cache - read-docs : Redirects you to swarms cloud documentation! - run-agents : Run your Agents from your agents.yaml +- [Project Overview](#project-overview) +- [Getting Started](#getting-started) + - [Installation](#installation) + - [Project Structure](#project-structure) +- [How to Contribute](#how-to-contribute) + - [Reporting Issues](#reporting-issues) + - [Submitting Pull Requests](#submitting-pull-requests) +- [Coding Standards](#coding-standards) + - [Type Annotations](#type-annotations) + - [Docstrings and Documentation](#docstrings-and-documentation) + - [Testing](#testing) + - [Code Style](#code-style) +- [Areas Needing Contributions](#areas-needing-contributions) + - [Writing Tests](#writing-tests) + - [Improving Documentation](#improving-documentation) + - [Creating Training Scripts](#creating-training-scripts) +- [Community and Support](#community-and-support) +- [License](#license) - For more details, visit: https://docs.swarms.world -``` +--- -### CLI Commands +## Project Overview -Below is a detailed explanation of the available commands: +**swarms** is a library focused on making it simple to orchestrate agents to automate real-world activities. The goal is to automate the world economy with these swarms of agents. -- **onboarding** - Starts the onboarding process to help you set up your environment and configure your agents. - - Usage: - ```bash - swarms onboarding - ``` +We need your help to: -- **help** - Displays the help message, including a list of available commands. +- **Write Tests**: Ensure the reliability and correctness of the codebase. +- **Improve Documentation**: Maintain clear and comprehensive documentation. +- **Add New Orchestration Methods**: Add multi-agent orchestration methods +- **Removing Defunct Code**: Removing bad code - Usage: - ```bash - swarms help - ``` -- **get-api-key** - Retrieves your API key from the platform, allowing your agents to communicate with the Swarms platform. - Usage: - ```bash - swarms get-api-key - ``` +Your contributions will help us push the boundaries of AI and make this library a valuable resource for the community. -- **check-login** - Verifies if you are logged into the platform and starts the cache for storing your login session. +--- - Usage: - ```bash - swarms check-login - ``` +## Getting Started -- **read-docs** - Redirects you to the official Swarms documentation on the web for further reading. +### Installation - Usage: - ```bash - swarms read-docs - ``` +You can install swarms using `pip`: -- **run-agents** - Executes your agents from the `agents.yaml` configuration file, which defines the structure and behavior of your agents. Refer to this document for how to leverage yamls for fast, reliable, and simple agent orchestration. [CLICK HERE](https://docs.swarms.world/en/latest/swarms/agents/create_agents_yaml/) You can customize what yaml file to run with `--yaml-file` +```bash +pip3 install swarms +``` - Usage: - ```bash - swarms run-agents --yaml-file agents.yaml - ``` +Alternatively, you can clone the repository: +```bash +git clone https://github.com/kyegomez/swarms +``` --------------------------------------------------- +### Project Structure -# File: swarms/concept/framework_architecture.md +- **`swarms/`**: Contains all the source code for the library. +- **`examples/`**: Includes example scripts and notebooks demonstrating how to use the library. +- **`tests/`**: (To be created) Will contain unit tests for the library. +- **`docs/`**: (To be maintained) Contains documentation files. -# Swarms Framework Architecture +--- +## How to Contribute -The Swarms package is designed to orchestrate and manage **swarms of agents**, enabling collaboration between multiple Large Language Models (LLMs) or other agent types to solve complex tasks. The architecture is modular and scalable, facilitating seamless integration of various agents, models, prompts, and tools. Below is an overview of the architectural components, along with instructions on where to find the corresponding documentation. +### Reporting Issues +If you find any bugs, inconsistencies, or have suggestions for enhancements, please open an issue on GitHub: +1. **Search Existing Issues**: Before opening a new issue, check if it has already been reported. +2. **Open a New Issue**: If it hasn't been reported, create a new issue and provide detailed information. + - **Title**: A concise summary of the issue. + - **Description**: Detailed description, steps to reproduce, expected behavior, and any relevant logs or screenshots. +3. **Label Appropriately**: Use labels to categorize the issue (e.g., bug, enhancement, documentation). -``` -swarms/ -├── agents/ -├── artifacts/ -├── cli/ -├── memory/ -├── models/ ---> Moved to swarm_models -├── prompts/ -├── schemas/ -├── structs/ -├── telemetry/ -├── tools/ -├── utils/ -└── __init__.py -``` +### Submitting Pull Requests +We welcome pull requests (PRs) for bug fixes, improvements, and new features. Please follow these guidelines: +1. **Fork the Repository**: Create a personal fork of the repository on GitHub. +2. **Clone Your Fork**: Clone your forked repository to your local machine. -### Role of Folders in the Swarms Framework + ```bash + git clone https://github.com/kyegomez/swarms.git + ``` -The **Swarms framework** is composed of several key folders, each serving a specific role in building, orchestrating, and managing swarms of agents. Below is an in-depth explanation of the role of each folder in the framework's architecture, focusing on how they contribute to the overall system for handling complex multi-agent workflows. +3. **Create a New Branch**: Use a descriptive branch name. ---- + ```bash + git checkout -b feature/your-feature-name + ``` -### **1. Agents Folder (`agents/`)** - - **Role:** - - The **agents** folder contains the core logic for individual agents within the Swarms framework. Agents are the key functional units responsible for carrying out specific tasks, whether it be text generation, web scraping, data analysis, or more specialized functions like marketing or accounting. - - **Customization:** Each agent can be specialized for different tasks by defining custom system prompts and behaviors. - - **Modular Agent System:** New agents can be easily added to this folder to expand the framework's capabilities. - - **Importance:** This folder allows users to create and manage multiple types of agents that can interact and collaborate to solve complex problems. - - **Examples:** Accounting agents, marketing agents, and programming agents. +4. **Make Your Changes**: Implement your code, ensuring it adheres to the coding standards. +5. **Add Tests**: Write tests to cover your changes. +6. **Commit Your Changes**: Write clear and concise commit messages. ---- + ```bash + git commit -am "Add feature X" + ``` -### **2. Artifacts Folder (`artifacts/`)** - - **Role:** - - The **artifacts** folder is responsible for storing the results or outputs generated by agents and swarms. This could include reports, logs, or data that agents generate during task execution. - - **Persistent Storage:** It helps maintain a persistent record of agent interactions, making it easier to retrieve or review past actions and outputs. - - **Data Handling:** Users can configure this folder to store artifacts that are essential for later analysis or reporting. - - **Importance:** Acts as a storage mechanism for important task-related outputs, ensuring that no data is lost after tasks are completed. +7. **Push to Your Fork**: ---- + ```bash + git push origin feature/your-feature-name + ``` -### **3. CLI Folder (`cli/`)** - - **Role:** - - The **CLI** folder contains tools for interacting with the Swarms framework through the command-line interface. This allows users to easily manage and orchestrate swarms without needing a graphical interface. - - **Command-line Tools:** Commands in this folder enable users to initiate, control, and monitor swarms, making the system accessible and versatile. - - **Automation and Scriptability:** Enables advanced users to automate swarm interactions and deploy agents programmatically. - - **Importance:** Provides a flexible way to control the Swarms system for developers who prefer using the command line. +8. **Create a Pull Request**: ---- + - Go to the original repository on GitHub. + - Click on "New Pull Request". + - Select your branch and create the PR. + - Provide a clear description of your changes and reference any related issues. -### **4. Memory Folder (`memory/`) Deprecated!!** - - **Role:** - - The **memory** folder handles the framework's memory management for agents. This allows agents to retain and recall past interactions or task contexts, enabling continuity in long-running processes or multi-step workflows. - - **Context Retention:** Agents that depend on historical context to make decisions or carry out tasks can store and access memory using this folder. - - **Long-Term and Short-Term Memory:** This could be implemented in various ways, such as short-term conversational memory or long-term knowledge storage. - - **Importance:** Crucial for agents that require memory to handle complex workflows, where decisions are based on prior outputs or interactions. +9. **Respond to Feedback**: Be prepared to make changes based on code reviews. + +**Note**: It's recommended to create small and focused PRs for easier review and faster integration. --- -### **5. Models Folder (`models/`) Moved to `swarm_models`** - - **Role:** - - The **models** folder houses pre-trained machine learning models that agents utilize to complete their tasks. These models could include LLMs (Large Language Models), custom-trained models, or fine-tuned models specific to the tasks being handled by the agents. - - **Plug-and-Play Architecture:** The framework allows users to easily add or switch models depending on the specific needs of their agents. - - **Custom Model Support:** Users can integrate custom models here for more specialized tasks. - - **Importance:** Provides the computational backbone for agent decision-making and task execution. +## Coding Standards ---- +To maintain code quality and consistency, please adhere to the following standards. -### **6. Prompts Folder (`prompts/`)** - - **Role:** - - The **prompts** folder contains reusable prompt templates that agents use to interact with their environment and complete tasks. These system prompts define the behavior and task orientation of the agents. - - **Template Reusability:** Users can create and store common prompt templates, making it easy to define agent behavior across different tasks without rewriting prompts from scratch. - - **Task-Specific Prompts:** For example, an accounting agent may have a prompt template that guides its interaction with financial data. - - **Importance:** Provides the logic and guidance agents need to generate outputs in a coherent and task-focused manner. +### Type Annotations ---- +- **Mandatory**: All functions and methods must have type annotations. +- **Example**: -### **7. Schemas Folder (`schemas/`)** - - **Role:** - - The **schemas** folder defines the data structures and validation logic for inputs and outputs within the framework, using tools like **Pydantic** for data validation. - - **Standardization and Validation:** This ensures that all interactions between agents and swarms follow consistent data formats, which is critical for large-scale agent coordination and task management. - - **Error Prevention:** By validating data early, it prevents errors from propagating through the system, improving reliability. - - **Importance:** Ensures data consistency across the entire framework, making it easier to integrate and manage swarms of agents at scale. + ```python + def add_numbers(a: int, b: int) -> int: + return a + b + ``` ---- +- **Benefits**: + - Improves code readability. + - Helps with static type checking tools. -### **8. Structs Folder (`structs/`)** - - **Role:** - - The **structs** folder is the core of the Swarms framework, housing the orchestration logic for managing and coordinating swarms of agents. This folder allows for dynamic task assignment, queue management, inter-agent communication, and result aggregation. - - **Swarm Management:** Agents are grouped into swarms to handle tasks that require multiple agents working in parallel or collaboratively. - - **Scalability:** The swarm structure is designed to be scalable, allowing thousands of agents to operate together on distributed tasks. - - **Task Queueing and Execution:** Supports task queueing, task prioritization, and load balancing between agents. - - **Importance:** This folder is critical for managing how agents interact and collaborate to solve complex, multi-step problems. +### Docstrings and Documentation ---- +- **Docstrings**: Every public class, function, and method must have a docstring following the [Google Python Style Guide](http://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) or [NumPy Docstring Standard](https://numpydoc.readthedocs.io/en/latest/format.html). +- **Content**: + - **Description**: Briefly describe what the function or class does. + - **Args**: List and describe each parameter. + - **Returns**: Describe the return value(s). + - **Raises**: List any exceptions that are raised. -### **9. Telemetry Folder (`telemetry/`)** - - **Role:** - - The **telemetry** folder provides logging and monitoring tools to capture agent performance metrics, error handling, and real-time activity tracking. It helps users keep track of what each agent or swarm is doing, making it easier to debug, audit, and optimize operations. - - **Monitoring:** Tracks agent performance and system health. - - **Logs:** Maintains logs for troubleshooting and operational review. - - **Importance:** Provides visibility into the system, ensuring smooth operation and enabling fine-tuning of agent behaviors. +- **Example**: ---- + ```python + def calculate_mean(values: List[float]) -> float: + """ + Calculates the mean of a list of numbers. -### **10. Tools Folder (`tools/`)** - - **Role:** - - The **tools** folder contains specialized utility functions or scripts that agents and swarms may require to complete certain tasks, such as web scraping, API interactions, data parsing, or other external resource handling. - - **Task-Specific Tools:** Agents can call these tools to perform operations outside of their own logic, enabling them to interact with external systems more efficiently. - - **Importance:** Expands the capabilities of agents, allowing them to complete more sophisticated tasks by relying on these external tools. + Args: + values (List[float]): A list of numerical values. ---- + Returns: + float: The mean of the input values. -### **11. Utils Folder (`utils/`)** - - **Role:** - - The **utils** folder contains general-purpose utility functions that are reused throughout the framework. These may include functions for data formatting, validation, logging setup, and configuration management. - - **Shared Utilities:** Helps keep the codebase clean by providing reusable functions that multiple agents or parts of the framework can call. - - **Importance:** Provides common functions that help the Swarms framework operate efficiently and consistently. + Raises: + ValueError: If the input list is empty. + """ + if not values: + raise ValueError("The input list is empty.") + return sum(values) / len(values) + ``` ---- +- **Documentation**: Update or create documentation pages if your changes affect the public API. -### **Core Initialization File (`__init__.py`)** - - **Role:** - - The `__init__.py` file is the entry point of the Swarms package, ensuring that all necessary modules, agents, and tools are loaded when the Swarms framework is imported. It allows for the modular loading of different components, making it easier for users to work with only the parts of the framework they need. - - **Importance:** Acts as the bridge that connects all other components in the framework, enabling the entire package to work together seamlessly. +### Testing ---- +- **Required**: All new features and bug fixes must include appropriate unit tests. +- **Framework**: Use `unittest`, `pytest`, or a similar testing framework. +- **Test Location**: Place tests in the `tests/` directory, mirroring the structure of `swarms/`. +- **Test Coverage**: Aim for high test coverage to ensure code reliability. +- **Running Tests**: Provide instructions for running tests. -### How to Access Documentation + ```bash + pytest tests/ + ``` -- **Official Documentation Site:** - - URL: [docs.swarms.world](https://docs.swarms.world) - - Here, users can find detailed guides, tutorials, and API references on how to use each of the folders mentioned above. The documentation covers setup, agent orchestration, and practical examples of how to leverage swarms for real-world tasks. +### Code Style -- **GitHub Repository:** - - URL: [Swarms GitHub](https://github.com/kyegomez/swarms) - - The repository contains code examples, detailed folder explanations, and further resources on how to get started with building and managing agent swarms. +- **PEP 8 Compliance**: Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines. +- **Linting Tools**: Use `flake8`, `black`, or `pylint` to check code style. +- **Consistency**: Maintain consistency with the existing codebase. -By understanding the purpose and role of each folder in the Swarms framework, users can more effectively build, orchestrate, and manage agents to handle complex tasks and workflows at scale. +--- -## Support: +## Areas Needing Contributions -- **Post Issue On Github** - - URL: [Submit issue](https://github.com/kyegomez/swarms/issues/new/choose) - - Post your issue whether it's an issue or a feature request +We have several areas where contributions are particularly welcome. +### Writing Tests -- **Community Support** - - URL: [Submit issue](https://discord.gg/jM3Z6M9uMq) - - Ask the community for support in real-time and or admin support +- **Goal**: Increase test coverage to ensure the library's robustness. +- **Tasks**: + - Write unit tests for existing code in `swarms/`. + - Identify edge cases and potential failure points. + - Ensure tests are repeatable and independent. --------------------------------------------------- +### Improving Documentation -# File: swarms/concept/future_swarm_architectures.md +- **Goal**: Maintain clear and comprehensive documentation for users and developers. +- **Tasks**: + - Update docstrings to reflect any changes. + - Add examples and tutorials in the `examples/` directory. + - Improve or expand the content in the `docs/` directory. +### Creating Multi-Agent Orchestration Methods +- **Goal**: Provide new multi-agent orchestration methods --- -### Federated Swarm +## Community and Support -**Overview:** -A Federated Swarm architecture involves multiple independent swarms collaborating to complete a task. Each swarm operates autonomously but can share information and results with other swarms. +- **Communication**: Engage with the community by participating in discussions on issues and pull requests. +- **Respect**: Maintain a respectful and inclusive environment. +- **Feedback**: Be open to receiving and providing constructive feedback. -**Use-Cases:** -- Distributed learning systems where data is processed across multiple nodes. +--- -- Scenarios requiring collaboration between different teams or departments. +## License -```mermaid -graph TD - A[Central Coordinator] - subgraph Swarm1 - B1[Agent 1.1] --> B2[Agent 1.2] - B2 --> B3[Agent 1.3] - end - subgraph Swarm2 - C1[Agent 2.1] --> C2[Agent 2.2] - C2 --> C3[Agent 2.3] - end - subgraph Swarm3 - D1[Agent 3.1] --> D2[Agent 3.2] - D2 --> D3[Agent 3.3] - end - B1 --> A - C1 --> A - D1 --> A -``` +By contributing to swarms, you agree that your contributions will be licensed under the [MIT License](LICENSE). --- -### Star Swarm - -**Overview:** -A Star Swarm architecture features a central agent that coordinates the activities of several peripheral agents. The central agent assigns tasks to the peripheral agents and aggregates their results. +Thank you for contributing to swarms! Your efforts help make this project better for everyone. -**Use-Cases:** -- Centralized decision-making processes. +If you have any questions or need assistance, please feel free to open an issue or reach out to the maintainers. -- Scenarios requiring a central authority to coordinate multiple workers. +-------------------------------------------------- -```mermaid -graph TD - A[Central Agent] --> B1[Peripheral Agent 1] - A --> B2[Peripheral Agent 2] - A --> B3[Peripheral Agent 3] - A --> B4[Peripheral Agent 4] -``` +# File: swarms\ecosystem.md ---- -### Mesh Swarm +# Swarms Ecosystem -**Overview:** -A Mesh Swarm architecture allows for a fully connected network of agents where each agent can communicate with any other agent. This setup provides high flexibility and redundancy. +*The Complete Enterprise-Grade Multi-Agent AI Platform* -**Use-Cases:** -- Complex systems requiring high fault tolerance and redundancy. +--- -- Scenarios involving dynamic and frequent communication between agents. +## **Join the Future of AI Development** -```mermaid -graph TD - A1[Agent 1] --> A2[Agent 2] - A1 --> A3[Agent 3] - A1 --> A4[Agent 4] - A2 --> A3 - A2 --> A4 - A3 --> A4 -``` +**We're Building the Operating System for the Agent Economy** - The Swarms ecosystem represents the most comprehensive, production-ready multi-agent AI platform available today. From our flagship Python framework to high-performance Rust implementations and client libraries spanning every major programming language, we provide enterprise-grade tools that power the next generation of intelligent applications. --- -### Cascade Swarm +## **Complete Product Portfolio** -**Overview:** -A Cascade Swarm architecture involves a chain of agents where each agent triggers the next one in a cascade effect. This is useful for scenarios where tasks need to be processed in stages, and each stage initiates the next. +| **Product** | **Technology** | **Status** | **Repository** | **Documentation** | +|-------------|---------------|------------|----------------|-------------------| +| **Swarms Python Framework** | Python | **Production** | [swarms](https://github.com/kyegomez/swarms) | [Docs](https://docs.swarms.world/en/latest/swarms/install/install/) | +| **Swarms Rust Framework** | Rust | **Production** | [swarms-rs](https://github.com/The-Swarm-Corporation/swarms-rs) | [Docs](https://docs.swarms.world/en/latest/swarms_rs/overview/) | +| **Python API Client** | Python | **Production** | [swarms-sdk](https://github.com/The-Swarm-Corporation/swarms-sdk) | [Docs](https://docs.swarms.world/en/latest/swarms_cloud/python_client/) | +| **TypeScript/Node.js Client** | TypeScript | **Production** | [swarms-ts](https://github.com/The-Swarm-Corporation/swarms-ts) | *Coming Soon* | +| **Go Client** | Go | **Production** | [swarms-client-go](https://github.com/The-Swarm-Corporation/swarms-client-go) | *Coming Soon* | +| **Java Client** | Java | **Production** | [swarms-java](https://github.com/The-Swarm-Corporation/swarms-java) | *Coming Soon* | +| **Kotlin Client** | Kotlin | **Q2 2025** | *In Development* | *Coming Soon* | +| **Ruby Client** | Ruby | **Q2 2025** | *In Development* | *Coming Soon* | +| **Rust Client** | Rust | **Q2 2025** | *In Development* | *Coming Soon* | +| **C#/.NET Client** | C# | **Q3 2025** | *In Development* | *Coming Soon* | -**Use-Cases:** -- Multi-stage processing tasks such as data transformation pipelines. +--- -- Event-driven architectures where one event triggers subsequent actions. +## **Why Choose the Swarms Ecosystem?** -```mermaid -graph TD - A[Trigger Agent] --> B[Agent 1] - B --> C[Agent 2] - C --> D[Agent 3] - D --> E[Agent 4] -``` +### **Enterprise-Grade Architecture** ---- +- **Production Ready**: Battle-tested in enterprise environments with 99.9%+ uptime -### Hybrid Swarm +- **Scalable Infrastructure**: Handle millions of agent interactions with automatic scaling -**Overview:** -A Hybrid Swarm architecture combines elements of various architectures to suit specific needs. It might integrate hierarchical and parallel components, or mix sequential and round robin patterns. +- **Security First**: End-to-end encryption, API key management, and enterprise compliance -**Use-Cases:** -- Complex workflows requiring a mix of different processing strategies. +- **Observability**: Comprehensive logging, monitoring, and debugging capabilities -- Custom scenarios tailored to specific operational requirements. +### **Developer Experience** -```mermaid -graph TD - A[Root Agent] --> B1[Sub-Agent 1] - A --> B2[Sub-Agent 2] - B1 --> C1[Parallel Agent 1] - B1 --> C2[Parallel Agent 2] - B2 --> C3[Sequential Agent 1] - C3 --> C4[Sequential Agent 2] - C3 --> C5[Sequential Agent 3] -``` +- **Multiple Language Support**: Native clients for every major programming language ---- +- **Unified API**: Consistent interface across all platforms and languages -These swarm architectures provide different models for organizing and orchestrating large language models (LLMs) to perform various tasks efficiently. Depending on the specific requirements of your project, you can choose the appropriate architecture or even combine elements from multiple architectures to create a hybrid solution. +- **Rich Documentation**: Comprehensive guides, tutorials, and API references --------------------------------------------------- +- **Active Community**: 24/7 support through Discord, GitHub, and direct channels -# File: swarms/concept/how_to_choose_swarms.md +### **Performance & Reliability** -# Choosing the Right Swarm for Your Business Problem +- **High Throughput**: Process thousands of concurrent agent requests -Depending on the complexity and nature of your problem, different swarm configurations can be more effective in achieving optimal performance. This guide provides a detailed explanation of when to use each swarm type, including their strengths and potential drawbacks. +- **Low Latency**: Optimized for real-time applications and user experiences -## Swarm Types Overview +- **Fault Tolerance**: Automatic retries, circuit breakers, and graceful degradation -- **MajorityVoting**: A swarm structure where agents vote on an outcome, and the majority decision is taken as the final result. -- **AgentRearrange**: Provides the foundation for both sequential and parallel swarms. -- **RoundRobin**: Agents take turns handling tasks in a cyclic manner. -- **Mixture of Agents**: A heterogeneous swarm where agents with different capabilities are combined. -- **GraphWorkflow**: Agents collaborate in a directed acyclic graph (DAG) format. -- **GroupChat**: Agents engage in a chat-like interaction to reach decisions. -- **AgentRegistry**: A centralized registry where agents are stored, retrieved, and invoked. -- **SpreadsheetSwarm**: A swarm designed to manage tasks at scale, tracking agent outputs in a structured format (e.g., CSV files). +- **Multi-Cloud**: Deploy on AWS, GCP, Azure, or on-premises infrastructure --- -## MajorityVoting Swarm - -### Use-Case -MajorityVoting is ideal for scenarios where accuracy is paramount, and the decision must be determined from multiple perspectives. For instance, choosing the best marketing strategy where various marketing agents vote on the highest predicted performance. +## **Join Our Growing Community** -### Advantages -- Ensures robustness in decision-making by leveraging multiple agents. -- Helps eliminate outliers or faulty agent decisions. +### **Connect With Developers Worldwide** -### Warnings -!!! warning - Majority voting can be slow if too many agents are involved. Ensure that your swarm size is manageable for real-time decision-making. +| **Platform** | **Purpose** | **Join Link** | **Benefits** | +|--------------|-------------|---------------|--------------| +| **Discord Community** | Real-time support & discussions | [Join Discord](https://discord.gg/jM3Z6M9uMq) | • 24/7 developer support
• Weekly community events
• Direct access to core team
• Beta feature previews | +| **Twitter/X** | Latest updates & announcements | [Follow @swarms_corp](https://x.com/swarms_corp) | • Breaking news & updates
• Community highlights
• Technical insights
• Industry partnerships | +| **LinkedIn** | Professional network & updates | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | • Professional networking
• Career opportunities
• Enterprise partnerships
• Industry insights | +| **YouTube** | Tutorials & technical content | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | • In-depth tutorials
• Live coding sessions
• Architecture deep dives
• Community showcases | --- -## AgentRearrange (Sequential and Parallel) - -### Sequential Swarm Use-Case -For linear workflows where each task depends on the outcome of the previous task, such as processing legal documents step by step through a series of checks and validations. +## **Contribute to the Ecosystem** -### Parallel Swarm Use-Case -For tasks that can be executed concurrently, such as batch processing customer data in marketing campaigns. Parallel swarms can significantly reduce processing time by dividing tasks across multiple agents. +### **How You Can Make an Impact** -### Notes -!!! note - Sequential swarms are slower but ensure strict task dependencies are respected. Parallel swarms are faster but require careful management of task interdependencies. +| **Contribution Area** | **Skills Needed** | **Impact Level** | **Getting Started** | +|-----------------------|-------------------|------------------|---------------------| +| **Core Framework Development** | Python, Rust, Systems Design | **High Impact** | [Contributing Guide](https://docs.swarms.world/en/latest/contributors/main/) | +| **Client Library Development** | Various Languages (Go, Java, TS, etc.) | **High Impact** | [Client Development](https://github.com/The-Swarm-Corporation) | +| **Documentation & Tutorials** | Technical Writing, Examples | **High Impact** | [Docs Contributing](https://docs.swarms.world/en/latest/contributors/docs/) | +| **Testing & Quality Assurance** | Testing Frameworks, QA | **Medium Impact** | [Testing Guide](https://docs.swarms.world/en/latest/swarms/framework/test/) | +| **UI/UX & Design** | Design, Frontend Development | **Medium Impact** | [Design Contributions](https://github.com/The-Swarm-Corporation/swarms/issues) | +| **Bug Reports & Feature Requests** | User Experience, Testing | **Easy Start** | [Report Issues](https://github.com/The-Swarm-Corporation/swarms/issues) | --- -## RoundRobin Swarm - -### Use-Case -For balanced task distribution where agents need to handle tasks evenly. An example would be assigning customer support tickets to agents in a cyclic manner, ensuring no single agent is overloaded. +## **We're Hiring Top Talent** -### Advantages -- Fair and even distribution of tasks. -- Simple and effective for balanced workloads. +### **Join the Team Building the Future Of The World Economy** -### Warnings -!!! warning - Round-robin may not be the best choice when some agents are more competent than others, as it can assign tasks equally regardless of agent performance. +**Ready to work on cutting-edge agent technology that's shaping the future?** We're actively recruiting exceptional engineers, researchers, and technical leaders to join our mission of building the operating system for the agent economy. ---- +| **Why Join Swarms?** | **What We Offer** | +|-----------------------|-------------------| +| **Cutting-Edge Technology** | Work on the most powerful multi-agent systems, distributed computing, and enterprise-scale infrastructure | +| **Global Impact** | Your code will power agent applications used by Fortune 500 companies and millions of developers | +| **World-Class Team** | Collaborate with top engineers, researchers, and industry experts from Google, OpenAI, and more | +| **Fast Growth** | Join a rapidly scaling company with massive market opportunity and venture backing | -## Mixture of Agents +### **Open Positions** -### Use-Case -Ideal for complex problems that require diverse skills. For example, a financial forecasting problem where some agents specialize in stock data, while others handle economic factors. +| **Position** | **Role Description** | +|-------------------------------|----------------------------------------------------------| +| **Senior Rust Engineers** | Building high-performance agent infrastructure | +| **Python Framework Engineers**| Expanding our core multi-agent capabilities | +| **DevOps/Platform Engineers** | Scaling cloud infrastructure for millions of agents | +| **Technical Writers** | Creating world-class developer documentation | +| **Solutions Engineers** | Helping enterprises adopt multi-agent AI | -### Notes -!!! note - A mixture of agents is highly flexible and can adapt to various problem domains. However, be mindful of coordination overhead. +**Ready to Build the Future?** **[Apply Now at swarms.ai/hiring](https://swarms.ai/hiring)** --- -## GraphWorkflow Swarm +--- -### Use-Case -This swarm structure is suited for tasks that can be broken down into a series of dependencies but are not strictly linear, such as an AI-driven software development pipeline where one agent handles front-end development while another handles back-end concurrently. +## **Get Started Today** -### Advantages -- Provides flexibility for managing dependencies. -- Agents can work on different parts of the problem simultaneously. +### **Quick Start Guide** -### Warnings -!!! warning - GraphWorkflow requires clear definition of task dependencies, or it can lead to execution issues and delays. +| **Step** | **Action** | **Time Required** | +|----------|------------|-------------------| +| **1** | [Install Swarms Python Framework](https://docs.swarms.world/en/latest/swarms/install/install/) | 5 minutes | +| **2** | [Run Your First Agent](https://docs.swarms.world/en/latest/swarms/examples/basic_agent/) | 10 minutes | +| **3** | [Try Multi-Agent Workflows](https://docs.swarms.world/en/latest/swarms/examples/sequential_example/) | 15 minutes | +| **4** | [Join Our Discord Community](https://discord.gg/jM3Z6M9uMq) | 2 minutes | +| **5** | [Explore Enterprise Features](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/) | 20 minutes | --- -## GroupChat Swarm - -### Use-Case -For real-time collaborative decision-making. For instance, agents could participate in group chat for negotiating contracts, each contributing their expertise and adjusting responses based on the collective discussion. +## **Enterprise Support & Partnerships** -### Advantages -- Facilitates highly interactive problem-solving. -- Ideal for dynamic and unstructured problems. +### **Ready to Scale with Swarms?** -### Warnings -!!! warning - High communication overhead between agents may slow down decision-making in large swarms. +| **Contact Type** | **Best For** | **Response Time** | **Contact Information** | +|------------------|--------------|-------------------|-------------------------| +| **Technical Support** | Development questions, troubleshooting | < 24 hours | [Book Support Call](https://cal.com/swarms/swarms-technical-support) | +| **Enterprise Sales** | Custom deployments, enterprise licensing | < 4 hours | [kye@swarms.world](mailto:kye@swarms.world) | +| **Partnerships** | Integration partnerships, technology alliances | < 48 hours | [kye@swarms.world](mailto:kye@swarms.world) | +| **Investor Relations** | Investment opportunities, funding updates | By appointment | [kye@swarms.world](mailto:kye@swarms.world) | --- -## AgentRegistry Swarm +**Ready to build the future of AI? Start with Swarms today and join thousands of developers creating the next generation of intelligent applications.** -### Use-Case -For dynamically managing agents based on the problem domain. An AgentRegistry is useful when new agents can be added or removed as needed, such as adding new machine learning models for an evolving recommendation engine. -### Notes -!!! note - AgentRegistry is a flexible solution but introduces additional complexity when agents need to be discovered and registered on the fly. +-------------------------------------------------- ---- +# File: swarms\examples\agent_output_types.md -## SpreadsheetSwarm +# Agent Output Types Examples with Vision Capabilities -### Use-Case -When dealing with massive-scale data or agent outputs that need to be stored and managed in a tabular format. SpreadsheetSwarm is ideal for businesses handling thousands of agent outputs, such as large-scale marketing analytics or financial audits. +This example demonstrates how to use different output types when working with Swarms agents, including vision-enabled agents that can analyze images. Each output type formats the agent's response in a specific way, making it easier to integrate with different parts of your application. -### Advantages -- Provides structure and order for managing massive amounts of agent outputs. -- Outputs are easily saved and tracked in CSV files. +## Prerequisites -### Warnings -!!! warning - Ensure the correct configuration of agents in SpreadsheetSwarm to avoid data mismatches and inconsistencies when scaling up to thousands of agents. +- Python 3.7+ +- OpenAI API key +- Anthropic API key (optional, for Claude models) +- Swarms library ---- +## Installation -## Final Thoughts +```bash +pip3 install -U swarms +``` -The choice of swarm depends on: +## Environment Variables -1. **Nature of the task**: Whether it's sequential or parallel. +```plaintext +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" # Required for GPT-4V vision capabilities +ANTHROPIC_API_KEY="" # Optional, for Claude models +``` -2. **Problem complexity**: Simple problems might benefit from RoundRobin, while complex ones may need GraphWorkflow or Mixture of Agents. +## Examples -3. **Scale of execution**: For large-scale tasks, Swarms like SpreadsheetSwarm or MajorityVoting provide scalability with structured outputs. +### Vision-Enabled Quality Control Agent -When integrating agents in a business workflow, it's crucial to balance task complexity, agent capabilities, and scalability to ensure the optimal swarm architecture. +```python +from swarms.structs import Agent +from swarms.prompts.logistics import ( + Quality_Control_Agent_Prompt, +) +# Image for analysis +factory_image = "image.jpg" --------------------------------------------------- -# File: swarms/concept/philosophy.md +# Quality control agent +quality_control_agent = Agent( + agent_name="Quality Control Agent", + agent_description="A quality control agent that analyzes images and provides a detailed report on the quality of the product in the image.", + model_name="gpt-4.1-mini", + system_prompt=Quality_Control_Agent_Prompt, + multi_modal=True, + max_loops=2, + output_type="str-all-except-first", +) -# Our Philosophy: Simplifying Multi-Agent Collaboration Through Readable Code and Performance Optimization -Our mission is to streamline multi-agent collaboration by emphasizing simplicity, readability, and performance in our codebase. This document outlines our core tactics: +response = quality_control_agent.run( + task="what is in the image?", + img=factory_image, +) -- **Readable Code with Type Annotations, Documentation, and Logging** -- **Bleeding-Edge Performance via Concurrency and Parallelism** -- **Simplified Abstractions for Multi-Agent Collaboration** +print(response) -By adhering to these principles, we aim to make our systems more maintainable, scalable, and efficient, facilitating easier integration and collaboration among developers and agents alike. +``` ---- +### Supported Image Formats -## 1. Emphasizing Readable Code +The vision-enabled agents support various image formats including: -Readable code is the cornerstone of maintainable and scalable systems. It ensures that developers can easily understand, modify, and extend the codebase. +| Format | Description | +|--------|-------------| +| JPEG/JPG | Standard image format with lossy compression | +| PNG | Lossless format supporting transparency | +| GIF | Animated format (only first frame used) | +| WebP | Modern format with both lossy and lossless compression | -### 1.1 Use of Type Annotations +### Best Practices for Vision Tasks -Type annotations enhance code readability and catch errors early in the development process. +| Best Practice | Description | +|--------------|-------------| +| Image Quality | Ensure images are clear and well-lit for optimal analysis | +| Image Size | Keep images under 20MB and in supported formats | +| Task Specificity | Provide clear, specific instructions for image analysis | +| Model Selection | Use vision-capable models (e.g., GPT-4V) for image tasks | -```python -def process_data(data: List[str]) -> Dict[str, int]: - result = {} - for item in data: - result[item] = len(item) - return result -``` +-------------------------------------------------- -### 1.2 Code Style Guidelines +# File: swarms\examples\agent_structured_outputs.md -Adhering to consistent code style guidelines, such as PEP 8 for Python, ensures uniformity across the codebase. +# Agent Structured Outputs -- **Indentation:** Use 4 spaces per indentation level. -- **Variable Naming:** Use `snake_case` for variables and functions. -- **Class Naming:** Use `PascalCase` for class names. +This example demonstrates how to use structured outputs with Swarms agents following OpenAI's function calling schema. By defining function schemas, you can specify exactly how agents should structure their responses, making it easier to parse and use the outputs in your applications. -### 1.3 Importance of Documentation +## Prerequisites -Comprehensive documentation helps new developers understand the purpose and functionality of code modules. +- Python 3.7+ +- OpenAI API key +- Swarms library -```python -def fetch_user_profile(user_id: str) -> UserProfile: - """ - Fetches the user profile from the database. +## Installation - Args: - user_id (str): The unique identifier of the user. +```bash +pip3 install -U swarms +``` - Returns: - UserProfile: An object containing user profile data. - """ - # Function implementation +## Environment Variables + +```plaintext +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" +ANTHROPIC_API_KEY="" ``` -### 1.4 Consistent Naming Conventions +## Understanding Function Schemas -Consistent naming reduces confusion and makes the code self-explanatory. +Function schemas in Swarms follow OpenAI's function calling format. Each function schema is defined as a dictionary with the following structure: -- **Functions:** Should be verbs (e.g., `calculate_total`). -- **Variables:** Should be nouns (e.g., `total_amount`). -- **Constants:** Should be uppercase (e.g., `MAX_RETRIES`). +```python +{ + "type": "function", + "function": { + "name": "function_name", + "description": "A clear description of what the function does", + "parameters": { + "type": "object", + "properties": { + # Define the parameters your function accepts + }, + "required": ["list", "of", "required", "parameters"] + } + } +} +``` ---- +## Code Example -## 2. Effective Logging Practices +Here's an example showing how to use multiple function schemas with a Swarms agent: -Logging is essential for debugging and monitoring the health of applications. +```python +from swarms import Agent +from swarms.prompts.finance_agent_sys_prompt import FINANCIAL_AGENT_SYS_PROMPT -### 2.1 Why Logging is Important +# Define multiple function schemas +tools = [ + { + "type": "function", + "function": { + "name": "get_stock_price", + "description": "Retrieve the current stock price and related information for a specified company.", + "parameters": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "The stock ticker symbol of the company, e.g. AAPL for Apple Inc.", + }, + "include_history": { + "type": "boolean", + "description": "Whether to include historical price data.", + }, + "time": { + "type": "string", + "format": "date-time", + "description": "Optional time for stock data, in ISO 8601 format.", + }, + }, + "required": ["ticker", "include_history"] + }, + }, + }, + # Can pass in multiple function schemas as well + { + "type": "function", + "function": { + "name": "analyze_company_financials", + "description": "Analyze key financial metrics and ratios for a company.", + "parameters": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "The stock ticker symbol of the company", + }, + "metrics": { + "type": "array", + "items": { + "type": "string", + "enum": ["PE_ratio", "market_cap", "revenue", "profit_margin"] + }, + "description": "List of financial metrics to analyze" + }, + "timeframe": { + "type": "string", + "enum": ["quarterly", "annual", "ttm"], + "description": "Timeframe for the analysis" + } + }, + "required": ["ticker", "metrics"] + } + } + } +] -- **Debugging:** Helps identify issues during development and after deployment. -- **Monitoring:** Provides insights into the system's behavior in real-time. -- **Audit Trails:** Keeps a record of events for compliance and analysis. +# Initialize the agent with multiple function schemas +agent = Agent( + agent_name="Financial-Analysis-Agent", + agent_description="Personal finance advisor agent that can fetch stock prices and analyze financials", + system_prompt=FINANCIAL_AGENT_SYS_PROMPT, + max_loops=1, + tools_list_dictionary=tools, # Pass in the list of function schemas + output_type="final" +) -### 2.2 Best Practices for Logging +# Example usage with stock price query +stock_response = agent.run( + "What is the current stock price for Apple Inc. (AAPL)? Include historical data." +) +print("Stock Price Response:", stock_response) -- **Use Appropriate Log Levels:** DEBUG, INFO, WARNING, ERROR, CRITICAL. -- **Consistent Log Formatting:** Include timestamps, log levels, and messages. -- **Avoid Sensitive Information:** Do not log passwords or personal data. +# Example usage with financial analysis query +analysis_response = agent.run( + "Analyze Apple's PE ratio and market cap using quarterly data." +) +print("Financial Analysis Response:", analysis_response) +``` -### 2.3 Logging Examples +## Schema Types and Properties -```python -import logging +The function schema supports various parameter types and properties: -logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s:%(message)s') +| Schema Type | Description | +|------------|-------------| +| Basic Types | `string`, `number`, `integer`, `boolean`, `array`, `object` | +| Format Specifications | `date-time`, `date`, `email`, etc. | +| Enums | Restrict values to a predefined set | +| Required vs Optional Parameters | Specify which parameters must be provided | +| Nested Objects and Arrays | Support for complex data structures | -def connect_to_service(url: str) -> bool: - logging.debug(f"Attempting to connect to {url}") - try: - # Connection logic - logging.info(f"Successfully connected to {url}") - return True - except ConnectionError as e: - logging.error(f"Connection failed to {url}: {e}") - return False +Example of a more complex schema: + +```python +{ + "type": "function", + "function": { + "name": "generate_investment_report", + "description": "Generate a comprehensive investment report", + "parameters": { + "type": "object", + "properties": { + "portfolio": { + "type": "object", + "properties": { + "stocks": { + "type": "array", + "items": { + "type": "object", + "properties": { + "ticker": {"type": "string"}, + "shares": {"type": "number"}, + "entry_price": {"type": "number"} + } + } + }, + "risk_tolerance": { + "type": "string", + "enum": ["low", "medium", "high"] + }, + "time_horizon": { + "type": "integer", + "minimum": 1, + "maximum": 30, + "description": "Investment time horizon in years" + } + }, + "required": ["stocks", "risk_tolerance"] + }, + "report_type": { + "type": "string", + "enum": ["summary", "detailed", "risk_analysis"] + } + }, + "required": ["portfolio"] + } + } +} ``` ---- +This example shows how to structure complex nested objects, arrays, and various parameter types while following OpenAI's function calling schema. -## 3. Achieving Bleeding-Edge Performance -Performance is critical, especially when dealing with multiple agents and large datasets. +-------------------------------------------------- -### 3.1 Concurrency and Parallelism +# File: swarms\examples\agent_with_tools.md -Utilizing concurrency and parallelism can significantly improve performance. +# Basic Agent Example -- **Concurrency:** Dealing with multiple tasks by managing multiple threads. -- **Parallelism:** Executing multiple tasks simultaneously on multiple CPU cores. +This tutorial demonstrates how to create and use tools (callables) with the Swarms framework. Tools are Python functions that your agent can call to perform specific tasks, interact with external services, or process data. We'll show you how to build well-structured tools and integrate them with your agent. -### 3.2 Asynchronous Programming +## Prerequisites -Asynchronous programming allows for non-blocking operations, leading to better resource utilization. +- Python 3.7+ -```python -import asyncio +- OpenAI API key -async def fetch_data(endpoint: str) -> dict: - async with aiohttp.ClientSession() as session: - async with session.get(endpoint) as response: - return await response.json() +- Swarms library -async def main(): - endpoints = ['https://api.example.com/data1', 'https://api.example.com/data2'] - tasks = [fetch_data(url) for url in endpoints] - results = await asyncio.gather(*tasks) - print(results) +## Building Tools for Your Agent -asyncio.run(main()) -``` +Tools are functions that your agent can use to interact with external services, process data, or perform specific tasks. Here's a guide on how to build effective tools for your agent: -### 3.3 Utilizing Modern Hardware Capabilities +### Tool Structure Best Practices -Leverage multi-core processors and GPUs for computationally intensive tasks. +1. **Type Hints**: Always use type hints to specify input and output types -- **Multi-threading:** Use threads for I/O-bound tasks. -- **Multi-processing:** Use processes for CPU-bound tasks. -- **GPU Acceleration:** Utilize GPUs for tasks like machine learning model training. +2. **Docstrings**: Include comprehensive docstrings with description, args, returns, and examples -### 3.4 Code Example: Parallel Processing +3. **Error Handling**: Implement proper error handling and return consistent JSON responses + +4. **Rate Limiting**: Include rate limiting when dealing with APIs + +5. **Input Validation**: Validate input parameters before processing + +### Example Tool Template + +Here's a template for creating a well-structured tool: ```python -from concurrent.futures import ThreadPoolExecutor +from typing import Optional, Dict, Any +import json -def process_item(item): - # Processing logic - return result +def example_tool(param1: str, param2: Optional[int] = None) -> str: + """ + Brief description of what the tool does. -items = [1, 2, 3, 4, 5] -with ThreadPoolExecutor(max_workers=5) as executor: - results = list(executor.map(process_item, items)) -``` + Args: + param1 (str): Description of first parameter + param2 (Optional[int]): Description of optional parameter ---- + Returns: + str: JSON formatted string containing the result -## 4. Simplifying Multi-Agent Collaboration + Raises: + ValueError: Description of when this error occurs + RequestException: Description of when this error occurs -Simplifying the abstraction of multi-agent collaboration makes it accessible and manageable. + Example: + >>> result = example_tool("test", 123) + >>> print(result) + {"status": "success", "data": {"key": "value"}} + """ + try: + # Input validation + if not isinstance(param1, str): + raise ValueError("param1 must be a string") + + # Main logic + result: Dict[str, Any] = { + "status": "success", + "data": { + "param1": param1, + "param2": param2 + } + } -### 4.1 Importance of Simple Abstractions + # Return JSON string + return json.dumps(result, indent=2) -- **Ease of Use:** Simple interfaces make it easier for developers to integrate agents. -- **Maintainability:** Reduces complexity, making the codebase easier to maintain. -- **Scalability:** Simple abstractions can be extended without significant overhauls. + except ValueError as e: + return json.dumps({"error": f"Validation error: {str(e)}"}) + except Exception as e: + return json.dumps({"error": f"Unexpected error: {str(e)}"}) +``` -### 4.2 Standardizing Agent Interfaces +### Building API Integration Tools -Every agent should adhere to a standard interface for consistency. +When building tools that interact with external APIs: -#### 4.2.1 Agent Base Class +1. **API Client Setup**: ```python -from abc import ABC, abstractmethod - -class BaseAgent(ABC): - @abstractmethod - def run(self, task: str) -> Any: - pass +def get_api_data(endpoint: str, params: Dict[str, Any]) -> str: + """ + Generic API data fetcher with proper error handling. - def __call__(self, task: str) -> Any: - return self.run(task) + Args: + endpoint (str): API endpoint to call + params (Dict[str, Any]): Query parameters - @abstractmethod - async def arun(self, task: str) -> Any: - pass + Returns: + str: JSON formatted response + """ + try: + response = requests.get( + endpoint, + params=params, + timeout=10 + ) + response.raise_for_status() + return json.dumps(response.json(), indent=2) + except requests.RequestException as e: + return json.dumps({"error": f"API error: {str(e)}"}) ``` -#### 4.2.2 Example Agent Implementation -```python -class DataProcessingAgent(BaseAgent): - def run(self, task: str) -> str: - # Synchronous processing logic - return f"Processed {task}" - async def arun(self, task: str) -> str: - # Asynchronous processing logic - return f"Processed {task} asynchronously" -``` +### Data Processing Tools -#### 4.2.3 Usage Example +Example of a tool that processes data: ```python -agent = DataProcessingAgent() +from typing import List, Dict +import pandas as pd -# Synchronous call -result = agent.run("data_task") -print(result) # Output: Processed data_task +def process_market_data(prices: List[float], window: int = 14) -> str: + """ + Calculate technical indicators from price data. -# Asynchronous call -async def main(): - result = await agent.arun("data_task") - print(result) # Output: Processed data_task asynchronously + Args: + prices (List[float]): List of historical prices + window (int): Rolling window size for calculations -asyncio.run(main()) + Returns: + str: JSON formatted string with calculated indicators + + Example: + >>> prices = [100, 101, 99, 102, 98, 103] + >>> result = process_market_data(prices, window=3) + >>> print(result) + {"sma": 101.0, "volatility": 2.1} + """ + try: + df = pd.DataFrame({"price": prices}) + + results: Dict[str, float] = { + "sma": df["price"].rolling(window).mean().iloc[-1], + "volatility": df["price"].rolling(window).std().iloc[-1] + } + + return json.dumps(results, indent=2) + + except Exception as e: + return json.dumps({"error": f"Processing error: {str(e)}"}) ``` -### 4.3 Mermaid Diagram: Agent Interaction +### Adding Tools to Your Agent -```mermaid -sequenceDiagram - participant User - participant AgentA - participant AgentB - participant AgentC +Once you've created your tools, add them to your agent like this: - User->>AgentA: run(task) - AgentA-->>AgentB: arun(sub_task) - AgentB-->>AgentC: run(sub_sub_task) - AgentC-->>AgentB: result_sub_sub_task - AgentB-->>AgentA: result_sub_task - AgentA-->>User: final_result +```python +agent = Agent( + agent_name="Your-Agent", + agent_description="Description of your agent", + system_prompt="System prompt for your agent", + tools=[ + example_tool, + get_api_data, + rate_limited_api_call, + process_market_data + ] +) ``` -*Agents collaborating to fulfill a user's task.* +## Tutorial Steps -### 4.4 Simplified Collaboration Workflow +1. First, install the latest version of Swarms: -```mermaid -graph TD - UserRequest[User Request] --> Agent1[Agent 1] - Agent1 -->|run(task)| Agent2[Agent 2] - Agent2 -->|arun(task)| Agent3[Agent 3] - Agent3 -->|result| Agent2 - Agent2 -->|result| Agent1 - Agent1 -->|result| UserResponse[User Response] +```bash +pip3 install -U swarms ``` -*Workflow demonstrating how agents process a task collaboratively.* +2. Set up your environment variables in a `.env` file: ---- +```plaintext +OPENAI_API_KEY="your-api-key-here" +WORKSPACE_DIR="agent_workspace" +``` -## 5. Bringing It All Together +3. Create a new Python file and customize your agent with the following parameters: + - `agent_name`: A unique identifier for your agent + + - `agent_description`: A detailed description of your agent's capabilities + + - `system_prompt`: The core instructions that define your agent's behavior + + - `model_name`: The GPT model to use + + - Additional configuration options for temperature and output format -By integrating these principles, we create a cohesive system where agents can efficiently collaborate while maintaining code quality and performance. +4. Run the example code below: -### 5.1 Example: Multi-Agent System -#### 5.1.1 Agent Definitions ```python -class AgentA(BaseAgent): - def run(self, task: str) -> str: - # Agent A processing - return f"AgentA processed {task}" +import json +import requests +from swarms import Agent +from typing import List +import time - async def arun(self, task: str) -> str: - # Agent A asynchronous processing - return f"AgentA processed {task} asynchronously" -class AgentB(BaseAgent): - def run(self, task: str) -> str: - # Agent B processing - return f"AgentB processed {task}" +def get_coin_price(coin_id: str, vs_currency: str) -> str: + """ + Get the current price of a specific cryptocurrency. - async def arun(self, task: str) -> str: - # Agent B asynchronous processing - return f"AgentB processed {task} asynchronously" -``` + Args: + coin_id (str): The CoinGecko ID of the cryptocurrency (e.g., 'bitcoin', 'ethereum') + vs_currency (str, optional): The target currency. Defaults to "usd". -#### 5.1.2 Orchestrator Agent + Returns: + str: JSON formatted string containing the coin's current price and market data -```python -class OrchestratorAgent(BaseAgent): - def __init__(self): - self.agent_a = AgentA() - self.agent_b = AgentB() + Raises: + requests.RequestException: If the API request fails - def run(self, task: str) -> str: - result_a = self.agent_a.run(task) - result_b = self.agent_b.run(task) - return f"Orchestrated results: {result_a} & {result_b}" + Example: + >>> result = get_coin_price("bitcoin") + >>> print(result) + {"bitcoin": {"usd": 45000, "usd_market_cap": 850000000000, ...}} + """ + try: + url = "https://api.coingecko.com/api/v3/simple/price" + params = { + "ids": coin_id, + "vs_currencies": vs_currency, + "include_market_cap": True, + "include_24hr_vol": True, + "include_24hr_change": True, + "include_last_updated_at": True, + } - async def arun(self, task: str) -> str: - result_a = await self.agent_a.arun(task) - result_b = await self.agent_b.arun(task) - return f"Orchestrated results: {result_a} & {result_b}" -``` + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() -#### 5.1.3 Execution + data = response.json() + return json.dumps(data, indent=2) -```python -orchestrator = OrchestratorAgent() + except requests.RequestException as e: + return json.dumps( + { + "error": f"Failed to fetch price for {coin_id}: {str(e)}" + } + ) + except Exception as e: + return json.dumps({"error": f"Unexpected error: {str(e)}"}) -# Synchronous execution -result = orchestrator.run("task1") -print(result) -# Output: Orchestrated results: AgentA processed task1 & AgentB processed task1 -# Asynchronous execution -async def main(): - result = await orchestrator.arun("task1") - print(result) - # Output: Orchestrated results: AgentA processed task1 asynchronously & AgentB processed task1 asynchronously +def get_top_cryptocurrencies(limit: int, vs_currency: str) -> str: + """ + Fetch the top cryptocurrencies by market capitalization. -asyncio.run(main()) -``` + Args: + limit (int, optional): Number of coins to retrieve (1-250). Defaults to 10. + vs_currency (str, optional): The target currency. Defaults to "usd". -### 5.2 Mermaid Diagram: Orchestrator Workflow + Returns: + str: JSON formatted string containing top cryptocurrencies with detailed market data -```mermaid -sequenceDiagram - participant User - participant Orchestrator - participant AgentA - participant AgentB + Raises: + requests.RequestException: If the API request fails + ValueError: If limit is not between 1 and 250 - User->>Orchestrator: run(task) - Orchestrator->>AgentA: run(task) - Orchestrator->>AgentB: run(task) - AgentA-->>Orchestrator: result_a - AgentB-->>Orchestrator: result_b - Orchestrator-->>User: Orchestrated results -``` + Example: + >>> result = get_top_cryptocurrencies(5) + >>> print(result) + [{"id": "bitcoin", "name": "Bitcoin", "current_price": 45000, ...}] + """ + try: + if not 1 <= limit <= 250: + raise ValueError("Limit must be between 1 and 250") + + url = "https://api.coingecko.com/api/v3/coins/markets" + params = { + "vs_currency": vs_currency, + "order": "market_cap_desc", + "per_page": limit, + "page": 1, + "sparkline": False, + "price_change_percentage": "24h,7d", + } -*Orchestrator coordinating between Agent A and Agent B.* + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() ---- + data = response.json() -## 6. Conclusion + # Simplify the data structure for better readability + simplified_data = [] + for coin in data: + simplified_data.append( + { + "id": coin.get("id"), + "symbol": coin.get("symbol"), + "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": coin.get( + "price_change_percentage_24h" + ), + "price_change_7d": coin.get( + "price_change_percentage_7d_in_currency" + ), + "last_updated": coin.get("last_updated"), + } + ) -Our philosophy centers around making multi-agent collaboration as simple and efficient as possible by: + return json.dumps(simplified_data, indent=2) -- **Writing Readable Code:** Through type annotations, consistent styling, and thorough documentation. -- **Implementing Effective Logging:** To aid in debugging and monitoring. -- **Optimizing Performance:** Leveraging concurrency, parallelism, and modern hardware capabilities. -- **Simplifying Abstractions:** Standardizing agent interfaces to `run`, `__call__`, and `arun` methods. + 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)}"}) -By adhering to these principles, we create a robust foundation for scalable and maintainable systems that can adapt to evolving technological landscapes. +def search_cryptocurrencies(query: str) -> str: + """ + Search for cryptocurrencies by name or symbol. + Args: + query (str): The search term (coin name or symbol) --------------------------------------------------- + Returns: + str: JSON formatted string containing search results with coin details -# File: swarms/concept/purpose/limits_of_individual_agents.md + Raises: + requests.RequestException: If the API request fails -# The Limits of Individual Agents + Example: + >>> result = search_cryptocurrencies("ethereum") + >>> print(result) + {"coins": [{"id": "ethereum", "name": "Ethereum", "symbol": "eth", ...}]} + """ + try: + url = "https://api.coingecko.com/api/v3/search" + params = {"query": query} -![Reliable Agents](docs/assets/img/reliabilitythrough.png) + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() + data = response.json() -Individual agents have pushed the boundaries of what machines can learn and accomplish. However, despite their impressive capabilities, these agents face inherent limitations that can hinder their effectiveness in complex, real-world applications. This blog explores the critical constraints of individual agents, such as context window limits, hallucination, single-task threading, and lack of collaboration, and illustrates how multi-agent collaboration can address these limitations. In short, + # Extract and format the results + result = { + "coins": data.get("coins", [])[ + :10 + ], # Limit to top 10 results + "query": query, + "total_results": len(data.get("coins", [])), + } -- Context Window Limits -- Single Task Execution -- Hallucination -- No collaboration + return json.dumps(result, indent=2) + except requests.RequestException as e: + return json.dumps( + {"error": f'Failed to search for "{query}": {str(e)}'} + ) + except Exception as e: + return json.dumps({"error": f"Unexpected error: {str(e)}"}) -#### Context Window Limits +def get_jupiter_quote( + input_mint: str, + output_mint: str, + amount: float, + slippage: float = 0.5, +) -> str: + """ + Get a quote for token swaps using Jupiter Protocol on Solana. -One of the most significant constraints of individual agents, particularly in the domain of language models, is the context window limit. This limitation refers to the maximum amount of information an agent can consider at any given time. For instance, many language models can only process a fixed number of tokens (words or characters) in a single inference, restricting their ability to understand and generate responses based on longer texts. This limitation can lead to a lack of coherence in longer compositions and an inability to maintain context in extended conversations or documents. + Args: + input_mint (str): Input token mint address + output_mint (str): Output token mint address + amount (float): Amount of input tokens to swap + slippage (float, optional): Slippage tolerance percentage. Defaults to 0.5. -#### Hallucination + Returns: + str: JSON formatted string containing the swap quote details -Hallucination in AI refers to the phenomenon where an agent generates information that is not grounded in the input data or real-world facts. This can manifest as making up facts, entities, or events that do not exist or are incorrect. Hallucinations pose a significant challenge in ensuring the reliability and trustworthiness of AI-generated content, particularly in critical applications such as news generation, academic research, and legal advice. + Example: + >>> result = get_jupiter_quote("SOL_MINT_ADDRESS", "USDC_MINT_ADDRESS", 1.0) + >>> print(result) + {"inputAmount": "1000000000", "outputAmount": "22.5", "route": [...]} + """ + try: + url = "https://lite-api.jup.ag/swap/v1/quote" + params = { + "inputMint": input_mint, + "outputMint": output_mint, + "amount": str(int(amount * 1e9)), # Convert to lamports + "slippageBps": int(slippage * 100), + } -#### Single Task Threading + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() + return json.dumps(response.json(), indent=2) -Individual agents are often designed to excel at specific tasks, leveraging their architecture and training data to optimize performance in a narrowly defined domain. However, this specialization can also be a drawback, as it limits the agent's ability to multitask or adapt to tasks that fall outside its primary domain. Single-task threading means an agent may excel in language translation but struggle with image recognition or vice versa, necessitating the deployment of multiple specialized agents for comprehensive AI solutions. + except requests.RequestException as e: + return json.dumps( + {"error": f"Failed to get Jupiter quote: {str(e)}"} + ) + except Exception as e: + return json.dumps({"error": f"Unexpected error: {str(e)}"}) -#### Lack of Collaboration -Traditional AI agents operate in isolation, processing inputs and generating outputs independently. This isolation limits their ability to leverage diverse perspectives, share knowledge, or build upon the insights of other agents. In complex problem-solving scenarios, where multiple facets of a problem need to be addressed simultaneously, this lack of collaboration can lead to suboptimal solutions or an inability to tackle multifaceted challenges effectively. +def get_htx_market_data(symbol: str) -> str: + """ + Get market data for a trading pair from HTX exchange. -# The Elegant yet Simple Solution + Args: + symbol (str): Trading pair symbol (e.g., 'btcusdt', 'ethusdt') -- ## Multi-Agent Collaboration + Returns: + str: JSON formatted string containing market data -Recognizing the limitations of individual agents, researchers and practitioners have explored the potential of multi-agent collaboration as a means to transcend these constraints. Multi-agent systems comprise several agents that can interact, communicate, and collaborate to achieve common goals or solve complex problems. This collaborative approach offers several advantages: + Example: + >>> result = get_htx_market_data("btcusdt") + >>> print(result) + {"symbol": "btcusdt", "price": "45000", "volume": "1000000", ...} + """ + try: + url = "https://api.htx.com/market/detail/merged" + params = {"symbol": symbol.lower()} -#### Overcoming Context Window Limits + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() + return json.dumps(response.json(), indent=2) -By dividing a large task among multiple agents, each focusing on different segments of the problem, multi-agent systems can effectively overcome the context window limits of individual agents. For instance, in processing a long document, different agents could be responsible for understanding and analyzing different sections, pooling their insights to generate a coherent understanding of the entire text. + except requests.RequestException as e: + return json.dumps( + {"error": f"Failed to fetch HTX market data: {str(e)}"} + ) + except Exception as e: + return json.dumps({"error": f"Unexpected error: {str(e)}"}) -#### Mitigating Hallucination -Through collaboration, agents can cross-verify facts and information, reducing the likelihood of hallucinations. If one agent generates a piece of information, other agents can provide checks and balances, verifying the accuracy against known data or through consensus mechanisms. +def get_token_historical_data( + token_id: str, days: int = 30, vs_currency: str = "usd" +) -> str: + """ + Get historical price and market data for a cryptocurrency. -#### Enhancing Multitasking Capabilities + Args: + token_id (str): The CoinGecko ID of the cryptocurrency + days (int, optional): Number of days of historical data. Defaults to 30. + vs_currency (str, optional): The target currency. Defaults to "usd". -Multi-agent systems can tackle tasks that require a diverse set of skills by leveraging the specialization of individual agents. For example, in a complex project that involves both natural language processing and image analysis, one agent specialized in text can collaborate with another specialized in visual data, enabling a comprehensive approach to the task. + Returns: + str: JSON formatted string containing historical price and market data -#### Facilitating Collaboration and Knowledge Sharing + Example: + >>> result = get_token_historical_data("bitcoin", 7) + >>> print(result) + {"prices": [[timestamp, price], ...], "market_caps": [...], "volumes": [...]} + """ + try: + url = f"https://api.coingecko.com/api/v3/coins/{token_id}/market_chart" + params = { + "vs_currency": vs_currency, + "days": days, + "interval": "daily", + } -Multi-agent collaboration inherently encourages the sharing of knowledge and insights, allowing agents to learn from each other and improve their collective performance. This can be particularly powerful in scenarios where iterative learning and adaptation are crucial, such as dynamic environments or tasks that evolve over time. + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() + return json.dumps(response.json(), indent=2) -### Conclusion + except requests.RequestException as e: + return json.dumps( + {"error": f"Failed to fetch historical data: {str(e)}"} + ) + except Exception as e: + return json.dumps({"error": f"Unexpected error: {str(e)}"}) -While individual AI agents have made remarkable strides in various domains, their inherent limitations necessitate innovative approaches to unlock the full potential of artificial intelligence. Multi-agent collaboration emerges as a compelling solution, offering a pathway to transcend individual constraints through collective intelligence. By harnessing the power of collaborative AI, we can address more complex, multifaceted problems, paving the way for more versatile, efficient, and effective AI systems in the future. --------------------------------------------------- +def get_defi_stats() -> str: + """ + Get global DeFi statistics including TVL, trading volumes, and dominance. -# File: swarms/concept/purpose/why.md + Returns: + str: JSON formatted string containing global DeFi statistics -# The Swarms Framework: Orchestrating Agents for Enterprise Automation + Example: + >>> result = get_defi_stats() + >>> print(result) + {"total_value_locked": 50000000000, "defi_dominance": 15.5, ...} + """ + try: + url = "https://api.coingecko.com/api/v3/global/decentralized_finance_defi" + response = requests.get(url, timeout=10) + response.raise_for_status() + return json.dumps(response.json(), indent=2) -In the rapidly evolving landscape of artificial intelligence (AI) and automation, a new paradigm is emerging: the orchestration of multiple agents working in collaboration to tackle complex tasks. This approach, embodied by the Swarms Framework, aims to address the fundamental limitations of individual agents and unlocks the true potential of AI-driven automation in enterprise operations. + except requests.RequestException as e: + return json.dumps( + {"error": f"Failed to fetch DeFi stats: {str(e)}"} + ) + except Exception as e: + return json.dumps({"error": f"Unexpected error: {str(e)}"}) -Individual agents are plagued by the same issues: short term memory constraints, hallucinations, single task limitations, lack of collaboration, and cost inefficiences. -[Learn more here from a list of compiled agent papers](https://github.com/kyegomez/awesome-multi-agent-papers) +def get_jupiter_tokens() -> str: + """ + Get list of tokens supported by Jupiter Protocol on Solana. -## The Purpose of Swarms: Overcoming Agent Limitations + Returns: + str: JSON formatted string containing supported tokens -Individual agents, while remarkable in their own right, face several inherent challenges that hinder their ability to effectively automate enterprise operations at scale. These limitations include: + Example: + >>> result = get_jupiter_tokens() + >>> print(result) + {"tokens": [{"symbol": "SOL", "mint": "...", "decimals": 9}, ...]} + """ + try: + url = "https://lite-api.jup.ag/tokens/v1/mints/tradable" + response = requests.get(url, timeout=10) + response.raise_for_status() + return json.dumps(response.json(), indent=2) -1. Short-Term Memory Constraints -2. Hallucination and Factual Inconsistencies -3. Single-Task Limitations -4. Lack of Collaborative Capabilities -5. Cost Inefficiencies + except requests.RequestException as e: + return json.dumps( + {"error": f"Failed to fetch Jupiter tokens: {str(e)}"} + ) + except Exception as e: + return json.dumps({"error": f"Unexpected error: {str(e)}"}) -By orchestrating multiple agents to work in concert, the Swarms Framework directly tackles these limitations, paving the way for more efficient, reliable, and cost-effective enterprise automation. -### Limitation 1: Short-Term Memory Constraints +def get_htx_trading_pairs() -> str: + """ + Get list of all trading pairs available on HTX exchange. -Many AI agents, particularly those based on large language models, suffer from short-term memory constraints. These agents can effectively process and respond to prompts, but their ability to retain and reason over information across multiple interactions or tasks is limited. This limitation can be problematic in enterprise environments, where complex workflows often involve retaining and referencing contextual information over extended periods. + Returns: + str: JSON formatted string containing trading pairs information -The Swarms Framework addresses this limitation by leveraging the collective memory of multiple agents working in tandem. While individual agents may have limited short-term memory, their combined memory pool becomes significantly larger, enabling the retention and retrieval of contextual information over extended periods. This collective memory is facilitated by agents specializing in information storage and retrieval, such as those based on systems like Llama Index or Pinecone. + Example: + >>> result = get_htx_trading_pairs() + >>> print(result) + {"symbols": [{"symbol": "btcusdt", "state": "online", "type": "spot"}, ...]} + """ + try: + url = "https://api.htx.com/v1/common/symbols" + response = requests.get(url, timeout=10) + response.raise_for_status() + return json.dumps(response.json(), indent=2) -### Limitation 2: Hallucination and Factual Inconsistencies + except requests.RequestException as e: + return json.dumps( + {"error": f"Failed to fetch HTX trading pairs: {str(e)}"} + ) + except Exception as e: + return json.dumps({"error": f"Unexpected error: {str(e)}"}) -Another challenge faced by many AI agents is the tendency to generate responses that may contain factual inconsistencies or hallucinations -- information that is not grounded in reality or the provided context. This issue can undermine the reliability and trustworthiness of automated systems, particularly in domains where accuracy and consistency are paramount. -The Swarms Framework mitigates this limitation by employing multiple agents with diverse knowledge bases and capabilities. By leveraging the collective intelligence of these agents, the framework can cross-reference and validate information, reducing the likelihood of hallucinations and factual inconsistencies. Additionally, specialized agents can be tasked with fact-checking and verification, further enhancing the overall reliability of the system. +def get_market_sentiment(coin_ids: List[str]) -> str: + """ + Get market sentiment data including social metrics and developer activity. -### Limitation 3: Single-Task Limitations + Args: + coin_ids (List[str]): List of CoinGecko coin IDs -Most individual AI agents are designed and optimized for specific tasks or domains, limiting their ability to handle complex, multi-faceted workflows that often characterize enterprise operations. While an agent may excel at a particular task, such as natural language processing or data analysis, it may struggle with other aspects of a larger workflow, such as task coordination or decision-making. + Returns: + str: JSON formatted string containing market sentiment data -The Swarms Framework overcomes this limitation by orchestrating a diverse ensemble of agents, each specializing in different tasks or capabilities. By intelligently combining and coordinating these agents, the framework can tackle complex, multi-threaded workflows that span various domains and task types. This modular approach allows for the seamless integration of new agents as they become available, enabling the continuous expansion and enhancement of the system's capabilities. + Example: + >>> result = get_market_sentiment(["bitcoin", "ethereum"]) + >>> print(result) + {"bitcoin": {"sentiment_score": 75, "social_volume": 15000, ...}, ...} + """ + try: + sentiment_data = {} + for coin_id in coin_ids: + url = f"https://api.coingecko.com/api/v3/coins/{coin_id}" + params = { + "localization": False, + "tickers": False, + "market_data": False, + "community_data": True, + "developer_data": True, + } -### Limitation 4: Lack of Collaborative Capabilities + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() + data = response.json() -Most AI agents are designed to operate independently, lacking the ability to effectively collaborate with other agents or coordinate their actions towards a common goal. This limitation can hinder the scalability and efficiency of automated systems, particularly in enterprise environments where tasks often require the coordination of multiple agents or systems. + sentiment_data[coin_id] = { + "community_score": data.get("community_score"), + "developer_score": data.get("developer_score"), + "public_interest_score": data.get( + "public_interest_score" + ), + "community_data": data.get("community_data"), + "developer_data": data.get("developer_data"), + } -The Swarms Framework addresses this limitation by introducing a layer of coordination and collaboration among agents. Through specialized coordination agents and communication protocols, the framework enables agents to share information, divide tasks, and synchronize their actions. This collaborative approach not only increases efficiency but also enables the emergence of collective intelligence, where the combined capabilities of multiple agents surpass the sum of their individual abilities. + # Rate limiting to avoid API restrictions + time.sleep(0.6) -### Limitation 5: Cost Inefficiencies + return json.dumps(sentiment_data, indent=2) -Running large AI models or orchestrating multiple agents can be computationally expensive, particularly in enterprise environments where scalability and cost-effectiveness are critical considerations. Inefficient resource utilization or redundant computations can quickly escalate costs, making widespread adoption of AI-driven automation financially prohibitive. + except requests.RequestException as e: + return json.dumps( + {"error": f"Failed to fetch market sentiment: {str(e)}"} + ) + except Exception as e: + return json.dumps({"error": f"Unexpected error: {str(e)}"}) -The Swarms Framework tackles this limitation by optimizing resource allocation and workload distribution among agents. By intelligently assigning tasks to the most appropriate agents and leveraging agent specialization, the framework minimizes redundant computations and improves overall resource utilization. Additionally, the framework can dynamically scale agent instances based on demand, ensuring that computational resources are allocated efficiently and costs are minimized. -## The Swarms Framework: A Holistic Approach to Enterprise Automation +# Initialize the agent with expanded tools +agent = Agent( + agent_name="Financial-Analysis-Agent", + agent_description="Advanced financial advisor agent with comprehensive cryptocurrency market analysis capabilities across multiple platforms including Jupiter Protocol and HTX", + system_prompt="You are an advanced financial advisor agent with access to real-time cryptocurrency data from multiple sources including CoinGecko, Jupiter Protocol, and HTX. You can help users analyze market trends, check prices, find trading opportunities, perform swaps, and get detailed market insights. Always provide accurate, up-to-date information and explain market data in an easy-to-understand way.", + max_loops=1, + max_tokens=4096, + model_name="gpt-4o-mini", + dynamic_temperature_enabled=True, + output_type="all", + tools=[ + get_coin_price, + get_top_cryptocurrencies, + search_cryptocurrencies, + get_jupiter_quote, + get_htx_market_data, + get_token_historical_data, + get_defi_stats, + get_jupiter_tokens, + get_htx_trading_pairs, + get_market_sentiment, + ], + # Upload your tools to the tools parameter here! +) -The Swarms Framework is a comprehensive solution that addresses the limitations of individual agents by orchestrating their collective capabilities. By integrating agents from various frameworks, including LangChain, AutoGPT, Llama Index, and others, the framework leverages the strengths of each agent while mitigating their individual weaknesses. +# agent.run("Use defi stats to find the best defi project to invest in") +agent.run("Get the market sentiment for bitcoin") +# Automatically executes any number and combination of tools you have uploaded to the tools parameter! +``` -At its core, the Swarms Framework operates on the principle of multi-agent collaboration. By introducing specialized coordination agents and communication protocols, the framework enables agents to share information, divide tasks, and synchronize their actions towards a common goal. This collaborative approach not only increases efficiency but also enables the emergence of collective intelligence, where the combined capabilities of multiple agents surpass the sum of their individual abilities. -The framework's architecture is modular and extensible, allowing for the seamless integration of new agents as they become available. This flexibility ensures that the system's capabilities can continuously expand and adapt to evolving enterprise needs and technological advancements. +-------------------------------------------------- +# File: swarms\examples\agents_as_tools.md -## Benefits of the Swarms Framework +# Agents as Tools Tutorial -The adoption of the Swarms Framework in enterprise environments offers numerous benefits: +This tutorial demonstrates how to create a powerful multi-agent system where agents can delegate tasks to specialized sub-agents. This pattern is particularly useful for complex tasks that require different types of expertise or capabilities. -1. Increased Efficiency and Scalability -2. Improved Reliability and Accuracy -3. Adaptability and Continuous Improvement -4. Cost Optimization -5. Enhanced Security and Compliance +## Overview -## Increased Efficiency and Scalability +The Agents as Tools pattern allows you to: -By orchestrating the collective capabilities of multiple agents, the Swarms Framework enables the efficient execution of complex, multi-threaded workflows. Tasks can be parallelized and distributed across specialized agents, reducing bottlenecks and increasing overall throughput. Additionally, the framework's modular design and ability to dynamically scale agent instances based on demand ensure that the system can adapt to changing workloads and scale seamlessly as enterprise needs evolve. +- Create specialized agents with specific capabilities -## Improved Reliability and Accuracy +- Have agents delegate tasks to other agents -The collaborative nature of the Swarms Framework reduces the risk of hallucinations and factual inconsistencies that can arise from individual agents. By leveraging the collective knowledge and diverse perspectives of multiple agents, the framework can cross-reference and validate information, enhancing the overall reliability and accuracy of its outputs. +- Chain multiple agents together for complex workflows -Additionally, the framework's ability to incorporate specialized fact-checking and verification agents further strengthens the trustworthiness of the system's outcomes, ensuring that critical decisions and actions are based on accurate and reliable information. +- Maintain separation of concerns between different agent roles -## Adaptability and Continuous Improvement +## Prerequisites -The modular architecture of the Swarms Framework allows for the seamless integration of new agents as they become available, enabling the continuous expansion and enhancement of the system's capabilities. As new AI models, algorithms, or data sources emerge, the framework can readily incorporate them, ensuring that enterprise operations remain at the forefront of technological advancements. +- Python 3.8 or higher -Furthermore, the framework's monitoring and analytics capabilities provide valuable insights into system performance, enabling the identification of areas for improvement and the optimization of agent selection, task assignments, and resource allocation strategies over time. +- Basic understanding of Python programming -## Cost Optimization +- Familiarity with async/await concepts (optional) -By intelligently orchestrating the collaboration of multiple agents, the Swarms Framework optimizes resource utilization and minimizes redundant computations. This efficient use of computational resources translates into cost savings, making the widespread adoption of AI-driven automation more financially viable for enterprises. -The framework's ability to dynamically scale agent instances based on demand further contributes to cost optimization, ensuring that resources are allocated only when needed and minimizing idle or underutilized instances. +## Installation -## Enhanced Security and Compliance +Install the swarms package using pip: -In enterprise environments, ensuring the security and compliance of automated systems is paramount. The Swarms Framework addresses these concerns by incorporating robust security measures and compliance controls. +```bash +pip install -U swarms +``` -The framework's centralized Memory Manager component enables the implementation of access control mechanisms and data encryption, protecting sensitive information from unauthorized access or breaches. Additionally, the framework's modular design allows for the integration of specialized agents focused on compliance monitoring and auditing, ensuring that enterprise operations adhere to relevant regulations and industry standards. +## Basic Setup -## Real-World Applications and Use Cases +1. First, set up your environment variables: -The Swarms Framework finds applications across a wide range of enterprise domains, enabling organizations to automate complex operations and streamline their workflows. Here are some examples of real-world use cases: +```python +WORKSPACE_DIR="agent_workspace" +ANTHROPIC_API_KEY="" +``` -1. Intelligent Process Automation (IPA) -2. Customer Service and Support -3. Fraud Detection and Risk Management -4. Supply Chain Optimization -5. Research and Development +## Step-by-Step Guide -## Intelligent Process Automation (IPA) +1. **Define Your Tools** + + - Create functions that will serve as tools for your agents + + - Add proper type hints and detailed docstrings + + - Include error handling and logging + + - Example: + + ```python + def my_tool(param: str) -> str: + """Detailed description of what the tool does. + + Args: + param: Description of the parameter + + Returns: + Description of the return value + """ + # Tool implementation + return result + ``` -In the realm of business process automation, the Swarms Framework can orchestrate agents to automate and optimize complex workflows spanning multiple domains and task types. By combining agents specialized in areas such as natural language processing, data extraction, decision-making, and task coordination, the framework can streamline and automate processes that traditionally required manual intervention or coordination across multiple systems. +2. **Create Specialized Agents** + + - Define agents with specific roles and capabilities + + - Configure each agent with appropriate settings + + - Assign relevant tools to each agent + + ```python + specialized_agent = Agent( + agent_name="Specialist", + agent_description="Expert in specific domain", + system_prompt="Detailed instructions for the agent", + tools=[tool1, tool2] + ) + ``` -## Customer Service and Support +3. **Set Up the Director Agent** + + - Create a high-level agent that coordinates other agents + + - Give it access to specialized agents as tools + + - Define clear delegation rules + + ```python + director = Agent( + agent_name="Director", + agent_description="Coordinates other agents", + tools=[specialized_agent.run] + ) + ``` -The framework's ability to integrate agents with diverse capabilities, such as natural language processing, knowledge retrieval, and decision-making, makes it well-suited for automating customer service and support operations. Agents can collaborate to understand customer inquiries, retrieve relevant information from knowledge bases, and provide accurate and personalized responses, improving customer satisfaction and reducing operational costs. +4. **Execute Multi-Agent Workflows** + + - Start with the director agent + + - Let it delegate tasks as needed + + - Handle responses and chain results + + ```python + result = director.run("Your high-level task description") + ``` -## Fraud Detection and Risk Management -In the financial and cybersecurity domains, the Swarms Framework can orchestrate agents specialized in data analysis, pattern recognition, and risk assessment to detect and mitigate fraudulent activities or security threats. By combining the collective intelligence of these agents, the framework can identify complex patterns and anomalies that may be difficult for individual agents to detect, enhancing the overall effectiveness of fraud detection and risk management strategies. -## Supply Chain Optimization +## Code -The complexity of modern supply chains often requires the coordination of multiple systems and stakeholders. The Swarms Framework can integrate agents specialized in areas such as demand forecasting, inventory management, logistics optimization, and supplier coordination to streamline and optimize supply chain operations. By orchestrating the collective capabilities of these agents, the framework can identify bottlenecks, optimize resource allocation, and facilitate seamless collaboration among supply chain partners. +```python +import json +import requests +from swarms import Agent -## Research and Development +def create_python_file(code: str, filename: str) -> str: + """Create a Python file with the given code and execute it using Python 3.12. + + This function takes a string containing Python code, writes it to a file, and executes it + using Python 3.12 via subprocess. The file will be created in the current working directory. + If a file with the same name already exists, it will be overwritten. + + Args: + code (str): The Python code to write to the file. This should be valid Python 3.12 code. + filename (str): The name of the file to create and execute. + + Returns: + str: A detailed message indicating the file was created and the execution result. + + Raises: + IOError: If there are any issues writing to the file. + subprocess.SubprocessError: If there are any issues executing the file. + + Example: + >>> code = "print('Hello, World!')" + >>> result = create_python_file(code, "test.py") + >>> print(result) + 'Python file created successfully. Execution result: Hello, World!' + """ + import subprocess + import os + import datetime + + # Get current timestamp for logging + timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S") + + # Write the code to file + with open(filename, "w") as f: + f.write(code) + + # Get file size and permissions + file_stats = os.stat(filename) + file_size = file_stats.st_size + file_permissions = oct(file_stats.st_mode)[-3:] + + # Execute the file using Python 3.12 and capture output + try: + result = subprocess.run( + ["python3.12", filename], + capture_output=True, + text=True, + check=True + ) + + # Create detailed response + response = f""" +File Creation Details: +---------------------- +Timestamp: {timestamp} +Filename: {filename} +File Size: {file_size} bytes +File Permissions: {file_permissions} +Location: {os.path.abspath(filename)} + +Execution Details: +----------------- +Exit Code: {result.returncode} +Execution Time: {result.returncode} seconds -In research and development environments, the Swarms Framework can accelerate innovation by enabling the collaboration of agents specialized in areas such as literature review, data analysis, hypothesis generation, and experiment design. By orchestrating these agents, the framework can facilitate the exploration of new ideas, identify promising research directions, and streamline the iterative process of scientific inquiry. +Output: +------- +{result.stdout} -# Conclusion +Error Output (if any): +-------------------- +{result.stderr} +""" + return response + except subprocess.CalledProcessError as e: + error_response = f""" +File Creation Details: +---------------------- +Timestamp: {timestamp} +Filename: {filename} +File Size: {file_size} bytes +File Permissions: {file_permissions} +Location: {os.path.abspath(filename)} + +Execution Error: +--------------- +Exit Code: {e.returncode} +Error Message: {e.stderr} + +Command Output: +------------- +{e.stdout} +""" + return error_response + + + -The Swarms Framework represents a paradigm shift in the field of enterprise automation, addressing the limitations of individual agents by orchestrating their collective capabilities. By integrating agents from various frameworks and enabling multi-agent collaboration, the Swarms Framework overcomes challenges such as short-term memory constraints, hallucinations, single-task limitations, lack of collaboration, and cost inefficiencies. -Through its modular architecture, centralized coordination, and advanced monitoring and analytics capabilities, the Swarms Framework empowers enterprises to automate complex operations with increased efficiency, reliability, and adaptability. It unlocks the true potential of AI-driven automation, enabling organizations to stay ahead of the curve and thrive in an ever-evolving technological landscape. -As the field of artificial intelligence continues to advance, the Swarms Framework stands as a robust and flexible solution, ready to embrace new developments and seamlessly integrate emerging agents and capabilities. By harnessing the power of collective intelligence, the framework paves the way for a future where enterprises can leverage the full potential of AI to drive innovation, optimize operations, and gain a competitive edge in their respective industries. +def update_python_file(code: str, filename: str) -> str: + """Update an existing Python file with new code and execute it using Python 3.12. + + This function takes a string containing Python code and updates an existing Python file. + If the file doesn't exist, it will be created. The file will be executed using Python 3.12. + + Args: + code (str): The Python code to write to the file. This should be valid Python 3.12 code. + filename (str): The name of the file to update and execute. + + Returns: + str: A detailed message indicating the file was updated and the execution result. + + Raises: + IOError: If there are any issues writing to the file. + subprocess.SubprocessError: If there are any issues executing the file. + + Example: + >>> code = "print('Updated code!')" + >>> result = update_python_file(code, "my_script.py") + >>> print(result) + 'Python file updated successfully. Execution result: Updated code!' + """ + import subprocess + import os + import datetime + + # Get current timestamp for logging + timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S") + + # Check if file exists and get its stats + file_exists = os.path.exists(filename) + if file_exists: + old_stats = os.stat(filename) + old_size = old_stats.st_size + old_permissions = oct(old_stats.st_mode)[-3:] + + # Write the code to file + with open(filename, "w") as f: + f.write(code) + + # Get new file stats + new_stats = os.stat(filename) + new_size = new_stats.st_size + new_permissions = oct(new_stats.st_mode)[-3:] + + # Execute the file using Python 3.12 and capture output + try: + result = subprocess.run( + ["python3.12", filename], + capture_output=True, + text=True, + check=True + ) + + # Create detailed response + response = f""" +File Update Details: +------------------- +Timestamp: {timestamp} +Filename: {filename} +Previous Status: {'Existed' if file_exists else 'Did not exist'} +Previous Size: {old_size if file_exists else 'N/A'} bytes +Previous Permissions: {old_permissions if file_exists else 'N/A'} +New Size: {new_size} bytes +New Permissions: {new_permissions} +Location: {os.path.abspath(filename)} + +Execution Details: +----------------- +Exit Code: {result.returncode} +Execution Time: {result.returncode} seconds --------------------------------------------------- +Output: +------- +{result.stdout} -# File: swarms/concept/purpose/why_swarms.md +Error Output (if any): +-------------------- +{result.stderr} +""" + return response + except subprocess.CalledProcessError as e: + error_response = f""" + File Update Details: + ------------------- + Timestamp: {timestamp} + Filename: {filename} + Previous Status: {'Existed' if file_exists else 'Did not exist'} + Previous Size: {old_size if file_exists else 'N/A'} bytes + Previous Permissions: {old_permissions if file_exists else 'N/A'} + New Size: {new_size} bytes + New Permissions: {new_permissions} + Location: {os.path.abspath(filename)} + + Execution Error: + --------------- + Exit Code: {e.returncode} + Error Message: {e.stderr} + + Command Output: + ------------- + {e.stdout} + """ + return error_response + + +def run_quant_trading_agent(task: str) -> str: + """Run a quantitative trading agent to analyze and execute trading strategies. -# Why Swarms? + This function initializes and runs a specialized quantitative trading agent that can: + - Develop and backtest trading strategies + - Analyze market data for alpha opportunities + - Implement risk management frameworks + - Optimize portfolio allocations + - Conduct quantitative research + - Monitor market microstructure + - Evaluate trading system performance -The need for multiple agents to work together in artificial intelligence (AI) and particularly in the context of Large Language Models (LLMs) stems from several inherent limitations and challenges in handling complex, dynamic, and multifaceted tasks with single-agent systems. Collaborating with multiple agents offers a pathway to enhance reliability, computational efficiency, cognitive diversity, and problem-solving capabilities. This section delves into the rationale behind employing multi-agent systems and strategizes on overcoming the associated expenses, such as API bills and hosting costs. + Args: + task (str): The specific trading task or analysis to perform -### Why Multiple Agents Are Necessary + Returns: + str: The agent's response or analysis results -#### 1. **Cognitive Diversity** + Example: + >>> result = run_quant_trading_agent("Analyze SPY ETF for mean reversion opportunities") + >>> print(result) + """ + # Initialize the agent + agent = Agent( + 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=2, + model_name="claude-3-5-sonnet-20240620", + tools=[create_python_file, update_python_file, backtest_summary], + ) -Different agents can bring varied perspectives, knowledge bases, and problem-solving approaches to a task. This diversity is crucial in complex problem-solving scenarios where a single approach might not be sufficient. Cognitive diversity enhances creativity, leading to innovative solutions and the ability to tackle a broader range of problems. + out = agent.run(task) + return out -#### 2. **Specialization and Expertise** -In many cases, tasks are too complex for a single agent to handle efficiently. By dividing the task among multiple specialized agents, each can focus on a segment where it excels, thereby increasing the overall efficiency and effectiveness of the solution. This approach leverages the expertise of individual agents to achieve superior performance in tasks that require multifaceted knowledge and skills. -#### 3. **Scalability and Flexibility** +def backtest_summary(report: str) -> str: + """Generate a summary of a backtest report, but only if the backtest was profitable. + + This function should only be used when the backtest results show a positive return. + Using this function for unprofitable backtests may lead to misleading conclusions. + + Args: + report (str): The backtest report containing performance metrics + + Returns: + str: A formatted summary of the backtest report + + Example: + >>> result = backtest_summary("Total Return: +15.2%, Sharpe: 1.8") + >>> print(result) + 'The backtest report is: Total Return: +15.2%, Sharpe: 1.8' + """ + return f"The backtest report is: {report}" -Multi-agent systems can more easily scale to handle large-scale or evolving tasks. Adding more agents to the system can increase its capacity or capabilities, allowing it to adapt to larger workloads or new types of tasks. This scalability is essential in dynamic environments where the demand and nature of tasks can change rapidly. +def get_coin_price(coin_id: str, vs_currency: str) -> str: + """ + Get the current price of a specific cryptocurrency. -#### 4. **Robustness and Redundancy** + Args: + coin_id (str): The CoinGecko ID of the cryptocurrency (e.g., 'bitcoin', 'ethereum') + vs_currency (str, optional): The target currency. Defaults to "usd". -Collaboration among multiple agents enhances the system's robustness by introducing redundancy. If one agent fails or encounters an error, others can compensate, ensuring the system remains operational. This redundancy is critical in mission-critical applications where failure is not an option. + Returns: + str: JSON formatted string containing the coin's current price and market data -### Overcoming Expenses with API Bills and Hosting + Raises: + requests.RequestException: If the API request fails -Deploying multiple agents, especially when relying on cloud-based services or APIs, can incur significant costs. Here are strategies to manage and reduce these expenses: + Example: + >>> result = get_coin_price("bitcoin") + >>> print(result) + {"bitcoin": {"usd": 45000, "usd_market_cap": 850000000000, ...}} + """ + try: + url = "https://api.coingecko.com/api/v3/simple/price" + params = { + "ids": coin_id, + "vs_currencies": vs_currency, + "include_market_cap": True, + "include_24hr_vol": True, + "include_24hr_change": True, + "include_last_updated_at": True, + } -#### 1. **Optimize Agent Efficiency** + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() -Before scaling up the number of agents, ensure each agent operates as efficiently as possible. This can involve refining algorithms, reducing unnecessary API calls, and optimizing data processing to minimize computational requirements and, consequently, the associated costs. + data = response.json() + return json.dumps(data, indent=2) -#### 2. **Use Open Source and Self-Hosted Solutions** + except requests.RequestException as e: + return json.dumps( + { + "error": f"Failed to fetch price for {coin_id}: {str(e)}" + } + ) + except Exception as e: + return json.dumps({"error": f"Unexpected error: {str(e)}"}) -Where possible, leverage open-source models and technologies that can be self-hosted. While there is an initial investment in setting up the infrastructure, over time, self-hosting can significantly reduce costs related to API calls and reliance on third-party services. -#### 3. **Implement Intelligent Caching** -Caching results for frequently asked questions or common tasks can drastically reduce the need for repeated computations or API calls. Intelligent caching systems can determine what information to store and for how long, optimizing the balance between fresh data and computational savings. +def run_crypto_quant_agent(task: str) -> str: + """ + Run a crypto quantitative trading agent with specialized tools for cryptocurrency market analysis. -#### 4. **Dynamic Scaling and Load Balancing** + This function initializes and runs a quantitative trading agent specifically designed for + cryptocurrency markets. The agent is equipped with tools for price fetching and can perform + various quantitative analyses including algorithmic trading strategy development, risk management, + and market microstructure analysis. -Use cloud services that offer dynamic scaling and load balancing to adjust the resources allocated based on the current demand. This ensures you're not paying for idle resources during low-usage periods while still being able to handle high demand when necessary. + Args: + task (str): The task or query to be processed by the crypto quant agent. -#### 5. **Collaborative Cost-Sharing Models** + Returns: + str: The agent's response to the given task. -In scenarios where multiple stakeholders benefit from the multi-agent system, consider implementing a cost-sharing model. This approach distributes the financial burden among the users or beneficiaries, making it more sustainable. + Example: + >>> response = run_crypto_quant_agent("Analyze the current market conditions for Bitcoin") + >>> print(response) + "Based on current market analysis..." + """ + # Initialize the agent with expanded tools + quant_agent = Agent( + agent_name="Crypto-Quant-Agent", + agent_description="Advanced quantitative trading agent specializing in cryptocurrency markets with algorithmic analysis capabilities", + system_prompt="""You are an expert quantitative trading agent specializing in cryptocurrency markets. Your capabilities include: + - Algorithmic trading strategy development and backtesting + - Statistical arbitrage and market making for crypto assets + - Risk management and portfolio optimization for digital assets + - High-frequency trading system design for crypto markets + - Market microstructure analysis of crypto exchanges + - Quantitative research methodologies for crypto assets + - Financial mathematics and stochastic processes + - Machine learning applications in crypto trading + + 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=1, + max_tokens=4096, + model_name="gpt-4.1-mini", + dynamic_temperature_enabled=True, + output_type="final", + tools=[ + get_coin_price, + ], + ) -#### 6. **Monitor and Analyze Costs** + return quant_agent.run(task) -Regularly monitor and analyze your usage and associated costs to identify potential savings. Many cloud providers offer tools to track and forecast expenses, helping you to adjust your usage patterns and configurations to minimize costs without sacrificing performance. +# Initialize the agent +agent = Agent( + agent_name="Director-Agent", + agent_description="Strategic director and project management agent", + system_prompt="""You are an expert Director Agent with comprehensive capabilities in: + - Strategic planning and decision making + - Project management and coordination + - Resource allocation and optimization + - Team leadership and delegation + - Risk assessment and mitigation + - Stakeholder management + - Process optimization + - Quality assurance + + Your core responsibilities include: + 1. Developing and executing strategic initiatives + 2. Coordinating cross-functional projects + 3. Managing resource allocation + 4. Setting and tracking KPIs + 5. Ensuring project deliverables + 6. Risk management and mitigation + 7. Stakeholder communication + + You maintain strict adherence to: + - Best practices in project management + - Data-driven decision making + - Clear communication protocols + - Quality standards + - Timeline management + - Budget constraints + - Regulatory compliance + + You communicate with clarity and authority while maintaining professionalism and ensuring all stakeholders are aligned.""", + max_loops=1, + model_name="gpt-4o-mini", + output_type="final", + interactive=False, + tools=[run_quant_trading_agent], +) -### Conclusion +out = agent.run(""" + Please call the quantitative trading agent to generate Python code for an Bitcoin backtest using the CoinGecko API. + Provide a comprehensive description of the backtest methodology and trading strategy. + Consider the API limitations of CoinGecko and utilize only free, open-source libraries that don't require API keys. Use the requests library to fetch the data. Create a specialized strategy for the backtest focused on the orderbook and other data for price action. + The goal is to create a backtest that can predict the price action of the coin based on the orderbook and other data. + Maximize the profit of the backtest. Please use the OKX price API for the orderbook and other data. Be very explicit in your implementation. + Be very precise with the instructions you give to the agent and tell it to a 400 lines of good code. +""") +print(out) +``` -The collaboration of multiple agents in AI systems presents a robust solution to the complexity, specialization, scalability, and robustness challenges inherent in single-agent approaches. While the associated costs can be significant, strategic optimization, leveraging open-source technologies, intelligent caching, dynamic resource management, collaborative cost-sharing, and diligent monitoring can mitigate these expenses. By adopting these strategies, organizations can harness the power of multi-agent systems to tackle complex problems more effectively and efficiently, ensuring the sustainable deployment of these advanced technologies. +## Best Practices --------------------------------------------------- +| Category | Best Practice | Description | +|----------|---------------|-------------| +| **Tool Design** | Single Purpose | Keep tools focused and single-purpose | +| | Clear Naming | Use clear, descriptive names | +| | Error Handling | Include comprehensive error handling | +| | Documentation | Add detailed documentation | +| **Agent Configuration** | Clear Role | Give each agent a clear, specific role | +| | System Prompts | Provide detailed system prompts | +| | Model Parameters | Configure appropriate model and parameters | +| | Resource Limits | Set reasonable limits on iterations and tokens | +| **Error Handling** | Multi-level | Implement proper error handling at each level | +| | Logging | Include logging for debugging | +| | API Management | Handle API rate limits and timeouts | +| | Fallbacks | Provide fallback options when possible | +| **Performance Optimization** | Async Operations | Use async operations where appropriate | +| | Caching | Implement caching when possible | +| | Token Usage | Monitor and optimize token usage | +| | Batch Processing | Consider batch operations for efficiency | -# File: swarms/concept/swarm_architectures.md -# Swarm Architectures -### What is a Swarm? +-------------------------------------------------- -A swarm refers to a group of more than two agents working collaboratively to achieve a common goal. These agents can be software entities, such as llms that interact with each other to perform complex tasks. The concept of a swarm is inspired by natural systems like ant colonies or bird flocks, where simple individual behaviors lead to complex group dynamics and problem-solving capabilities. +# File: swarms\examples\aggregate.md -### How Swarm Architectures Facilitate Communication +# Aggregate Multi-Agent Responses -Swarm architectures are designed to establish and manage communication between agents within a swarm. These architectures define how agents interact, share information, and coordinate their actions to achieve the desired outcomes. Here are some key aspects of swarm architectures: +The `aggregate` function allows you to run multiple agents concurrently on the same task and then synthesize their responses using an intelligent aggregator agent. This is useful for getting diverse perspectives on a problem and then combining them into a comprehensive analysis. -1. **Hierarchical Communication**: In hierarchical swarms, communication flows from higher-level agents to lower-level agents. Higher-level agents act as coordinators, distributing tasks and aggregating results. This structure is efficient for tasks that require top-down control and decision-making. +## Installation -2. **Parallel Communication**: In parallel swarms, agents operate independently and communicate with each other as needed. This architecture is suitable for tasks that can be processed concurrently without dependencies, allowing for faster execution and scalability. +You can get started by first installing swarms with the following command, or [click here for more detailed installation instructions](https://docs.swarms.world/en/latest/swarms/install/install/): -3. **Sequential Communication**: Sequential swarms process tasks in a linear order, where each agent's output becomes the input for the next agent. This ensures that tasks with dependencies are handled in the correct sequence, maintaining the integrity of the workflow. +```bash +pip3 install -U swarms +``` -4. **Mesh Communication**: In mesh swarms, agents are fully connected, allowing any agent to communicate with any other agent. This setup provides high flexibility and redundancy, making it ideal for complex systems requiring dynamic interactions. +## Environment Variables -5. **Federated Communication**: Federated swarms involve multiple independent swarms that collaborate by sharing information and results. Each swarm operates autonomously but can contribute to a larger task, enabling distributed problem-solving across different nodes. +```txt +WORKSPACE_DIR="" +OPENAI_API_KEY="" +ANTHROPIC_API_KEY="" +``` -Swarm architectures leverage these communication patterns to ensure that agents work together efficiently, adapting to the specific requirements of the task at hand. By defining clear communication protocols and interaction models, swarm architectures enable the seamless orchestration of multiple agents, leading to enhanced performance and problem-solving capabilities. +## How It Works +1. **Concurrent Execution**: All agents in the `workers` list run the same task simultaneously +2. **Response Collection**: Individual agent responses are collected into a conversation +3. **Intelligent Aggregation**: A specialized aggregator agent analyzes all responses and creates a comprehensive synthesis +4. **Formatted Output**: The final result is returned in the specified format -| **Name** | **Description** | **Code Link** | **Use Cases** | -|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------| -| Hierarchical Swarms | A system where agents are organized in a hierarchy, with higher-level agents coordinating lower-level agents to achieve complex tasks. | [Code Link](https://docs.swarms.world/en/latest/swarms/concept/swarm_architectures/#hierarchical-swarm) | Manufacturing process optimization, multi-level sales management, healthcare resource coordination | -| Agent Rearrange | A setup where agents rearrange themselves dynamically based on the task requirements and environmental conditions. | [Code Link](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/) | Adaptive manufacturing lines, dynamic sales territory realignment, flexible healthcare staffing | -| Concurrent Workflows | Agents perform different tasks simultaneously, coordinating to complete a larger goal. | [Code Link](https://docs.swarms.world/en/latest/swarms/concept/swarm_architectures/#concurrent-workflows) | Concurrent production lines, parallel sales operations, simultaneous patient care processes | -| Sequential Coordination | Agents perform tasks in a specific sequence, where the completion of one task triggers the start of the next. | [Code Link](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/) | Step-by-step assembly lines, sequential sales processes, stepwise patient treatment workflows | -| Parallel Processing | Agents work on different parts of a task simultaneously to speed up the overall process. | [Code Link](https://docs.swarms.world/en/latest/swarms/concept/swarm_architectures/#parallel-processing) | Parallel data processing in manufacturing, simultaneous sales analytics, concurrent medical tests | -| Mixture of Agents | A heterogeneous swarm where agents with different capabilities are combined to solve complex problems. | [Code Link](https://docs.swarms.world/en/latest/swarms/structs/moa/) | Financial forecasting, complex problem-solving requiring diverse skills | -| Graph Workflow | Agents collaborate in a directed acyclic graph (DAG) format to manage dependencies and parallel tasks. | [Code Link](https://docs.swarms.world/en/latest/swarms/structs/graph_workflow/) | AI-driven software development pipelines, complex project management | -| Group Chat | Agents engage in a chat-like interaction to reach decisions collaboratively. | [Code Link](https://docs.swarms.world/en/latest/swarms/structs/group_chat/) | Real-time collaborative decision-making, contract negotiations | -| Agent Registry | A centralized registry where agents are stored, retrieved, and invoked dynamically. | [Code Link](https://docs.swarms.world/en/latest/swarms/structs/agent_registry/) | Dynamic agent management, evolving recommendation engines | -| Spreadsheet Swarm | Manages tasks at scale, tracking agent outputs in a structured format like CSV files. | [Code Link](https://docs.swarms.world/en/latest/swarms/structs/spreadsheet_swarm/) | Large-scale marketing analytics, financial audits | -| Forest Swarm | A swarm structure that organizes agents in a tree-like hierarchy for complex decision-making processes. | [Code Link](https://docs.swarms.world/en/latest/swarms/structs/forest_swarm/) | Multi-stage workflows, hierarchical reinforcement learning | -| Swarm Router | Routes and chooses the swarm architecture based on the task requirements and available agents. | [Code Link](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/) | Dynamic task routing, adaptive swarm architecture selection, optimized agent allocation | +## Code Example +```python +from swarms.structs.agent import Agent +from swarms.structs.ma_blocks import aggregate +# Create specialized agents for different perspectives +agents = [ + Agent( + agent_name="Sector-Financial-Analyst", + agent_description="Senior financial analyst at BlackRock.", + system_prompt="You are a financial analyst tasked with optimizing asset allocations for a $50B portfolio. Provide clear, quantitative recommendations for each sector.", + max_loops=1, + model_name="gpt-4o-mini", + max_tokens=3000, + ), + Agent( + agent_name="Sector-Risk-Analyst", + agent_description="Expert risk management analyst.", + system_prompt="You are a risk analyst responsible for advising on risk allocation within a $50B portfolio. Provide detailed insights on risk exposures for each sector.", + max_loops=1, + model_name="gpt-4o-mini", + max_tokens=3000, + ), + Agent( + agent_name="Tech-Sector-Analyst", + agent_description="Technology sector analyst.", + system_prompt="You are a tech sector analyst focused on capital and risk allocations. Provide data-backed insights for the tech sector.", + max_loops=1, + model_name="gpt-4o-mini", + max_tokens=3000, + ), +] -### Hierarchical Swarm +# Run the aggregate function +result = aggregate( + workers=agents, + task="What is the best sector to invest in?", + type="all", # Get complete conversation history + aggregator_model_name="anthropic/claude-3-sonnet-20240229" +) -**Overview:** -A Hierarchical Swarm architecture organizes the agents in a tree-like structure. Higher-level agents delegate tasks to lower-level agents, which can further divide tasks among themselves. This structure allows for efficient task distribution and scalability. +print(result) +``` -**Use-Cases:** -- Complex decision-making processes where tasks can be broken down into subtasks. +-------------------------------------------------- -- Multi-stage workflows such as data processing pipelines or hierarchical reinforcement learning. +# File: swarms\examples\azure.md -```mermaid -graph TD - A[Root Agent] --> B1[Sub-Agent 1] - A --> B2[Sub-Agent 2] - B1 --> C1[Sub-Agent 1.1] - B1 --> C2[Sub-Agent 1.2] - B2 --> C3[Sub-Agent 2.1] - B2 --> C4[Sub-Agent 2.2] -``` +# Azure OpenAI Integration ---- +This guide demonstrates how to integrate Azure OpenAI models with Swarms for enterprise-grade AI applications. Azure OpenAI provides access to OpenAI models through Microsoft's cloud infrastructure with enhanced security, compliance, and enterprise features. -### Parallel Swarm +## Prerequisites -**Overview:** -In a Parallel Swarm architecture, multiple agents operate independently and simultaneously on different tasks. Each agent works on its own task without dependencies on the others. [Learn more here in the docs:](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/) +- Azure subscription with OpenAI service enabled +- Azure OpenAI resource deployed +- Python 3.7+ +- Swarms library +- LiteLLM library +## Installation -**Use-Cases:** +First, install the required dependencies: -- Tasks that can be processed independently, such as parallel data analysis. +```bash +pip install -U swarms +``` -- Large-scale simulations where multiple scenarios are run in parallel. +## Environment Setup -```mermaid -graph LR - A[Task] --> B1[Sub-Agent 1] - A --> B2[Sub-Agent 2] - A --> B3[Sub-Agent 3] - A --> B4[Sub-Agent 4] -``` +### 1. Azure OpenAI Configuration ---- +Set up your Azure OpenAI environment variables in a `.env` file: -### Sequential Swarm +```bash +# Azure OpenAI Configuration +AZURE_API_KEY=your_azure_openai_api_key +AZURE_API_BASE=https://your-resource-name.openai.azure.com/ +AZURE_API_VERSION=2024-02-15-preview -**Overview:** -A Sequential Swarm architecture processes tasks in a linear sequence. Each agent completes its task before passing the result to the next agent in the chain. This architecture ensures orderly processing and is useful when tasks have dependencies. [Learn more here in the docs:](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/) +# Optional: Model deployment names (if different from model names) +AZURE_GPT4_DEPLOYMENT_NAME=gpt-4 +AZURE_GPT35_DEPLOYMENT_NAME=gpt-35-turbo +``` -**Use-Cases:** +### 2. Verify Available Models -- Workflows where each step depends on the previous one, such as assembly lines or sequential data processing. +Check what Azure models are available using LiteLLM: -- Scenarios requiring strict order of operations. +```python +from litellm import model_list -```mermaid -graph TD - A[First Agent] --> B[Second Agent] - B --> C[Third Agent] - C --> D[Fourth Agent] +# List all available Azure models +print("Available Azure models:") +for model in model_list: + if "azure" in model: + print(f" - {model}") ``` ---- +Common Azure model names include: +- `azure/gpt-4` +- `azure/gpt-4o` +- `azure/gpt-4o-mini` +- `azure/gpt-35-turbo` +- `azure/gpt-35-turbo-16k` -### Round Robin Swarm +## Basic Usage -**Overview:** -In a Round Robin Swarm architecture, tasks are distributed cyclically among a set of agents. Each agent takes turns handling tasks in a rotating order, ensuring even distribution of workload. +### Simple Agent with Azure Model -**Use-Cases:** +```python +import os +from dotenv import load_dotenv +from swarms import Agent -- Load balancing in distributed systems. +# Load environment variables +load_dotenv() -- Scenarios requiring fair distribution of tasks to avoid overloading any single agent. +# Initialize agent with Azure model +agent = Agent( + agent_name="Azure-Agent", + agent_description="An agent powered by Azure OpenAI", + system_prompt="You are a helpful assistant powered by Azure OpenAI.", + model_name="azure/gpt-4o-mini", + max_loops=1, + max_tokens=1000, + dynamic_temperature_enabled=True, + output_type="str", +) -```mermaid -graph TD - A[Coordinator Agent] --> B1[Sub-Agent 1] - A --> B2[Sub-Agent 2] - A --> B3[Sub-Agent 3] - A --> B4[Sub-Agent 4] - B1 --> A - B2 --> A - B3 --> A - B4 --> A +# Run the agent +response = agent.run("Explain quantum computing in simple terms.") +print(response) ``` +## Advanced Configuration +### Quantitative Trading Agent Example -### SpreadSheet Swarm +Here's a comprehensive example of a quantitative trading agent using Azure models: -**Overview:** -The SpreadSheet Swarm makes it easy to manage thousands of agents all in one place: a csv file. You can initialize any number of agents and then there is a loop parameter to run the loop of agents on the task. Learn more in the [docs here](https://docs.swarms.world/en/latest/swarms/structs/spreadsheet_swarm/) +```python +import os +from dotenv import load_dotenv +from swarms import Agent -**Use-Cases:** +# Load environment variables +load_dotenv() -- Multi-threaded execution: Execution agents on multiple threads +# Initialize the quantitative trading agent +agent = Agent( + agent_name="Quantitative-Trading-Agent", + agent_description="Advanced quantitative trading and algorithmic analysis agent powered by Azure OpenAI", + 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.""", + model_name="azure/gpt-4o", + dynamic_temperature_enabled=True, + output_type="str-all-except-first", + max_loops="auto", + interactive=True, + no_reasoning_prompt=True, + streaming_on=True, + max_tokens=4096, +) -- Save agent outputs into CSV file +# Example usage +response = agent.run( + task="What are the best top 3 ETFs for gold coverage? Provide detailed analysis including expense ratios, liquidity, and tracking error." +) +print(response) +``` -- One place to analyze agent outputs +## Next Steps -```mermaid +- Check out [LiteLLM Azure integration](https://docs.litellm.ai/docs/providers/azure) -graph TD - A[Initialize SpreadSheetSwarm] --> B[Initialize Agents] - B --> C[Load Task Queue] - C --> D[Run Task] +- Learn about [Swarms multi-agent architectures](../structs/index.md) - subgraph Agents - D --> E1[Agent 1] - D --> E2[Agent 2] - D --> E3[Agent 3] - end +- Discover [advanced tool integrations](agent_with_tools.md) - E1 --> F1[Process Task] - E2 --> F2[Process Task] - E3 --> F3[Process Task] - F1 --> G1[Track Output] - F2 --> G2[Track Output] - F3 --> G3[Track Output] +-------------------------------------------------- - subgraph Save Outputs - G1 --> H[Save to CSV] - G2 --> H[Save to CSV] - G3 --> H[Save to CSV] - end +# File: swarms\examples\basic_agent.md - H --> I{Autosave Enabled?} - I --> |Yes| J[Export Metadata to JSON] - I --> |No| K[End Swarm Run] -``` +# Basic Agent Example +This example demonstrates how to create and configure a sophisticated AI agent using the Swarms framework. In this tutorial, we'll build a Quantitative Trading Agent that can analyze financial markets and provide investment insights. The agent is powered by GPT models and can be customized for various financial analysis tasks. +## Prerequisites -### Mixture of Agents Architecture +- Python 3.7+ +- OpenAI API key -```mermaid +- Swarms library -graph TD - A[Task Input] --> B[Layer 1: Reference Agents] - B --> C[Agent 1] - B --> D[Agent 2] - B --> E[Agent N] +## Tutorial Steps - C --> F[Agent 1 Response] - D --> G[Agent 2 Response] - E --> H[Agent N Response] +1. First, install the latest version of Swarms: - F & G & H --> I[Layer 2: Aggregator Agent] - I --> J[Aggregate All Responses] - J --> K[Final Output] +```bash +pip3 install -U swarms ``` +2. Set up your environment variables in a `.env` file: -## Alternative Experimental Architectures - -### **1. Circular Swarm** +```plaintext +OPENAI_API_KEY="your-api-key-here" +WORKSPACE_DIR="agent_workspace" +``` -#### Input Arguments: -- **name** (str): Name of the swarm. -- **description** (str): Description of the swarm. -- **goal** (str): Goal of the swarm. -- **agents** (AgentListType): List of agents involved. -- **tasks** (List[str]): List of tasks for the agents. -- **return_full_history** (bool): Whether to return the full conversation history. +3. Create a new Python file and customize your agent with the following parameters: + - `agent_name`: A unique identifier for your agent + + - `agent_description`: A detailed description of your agent's capabilities + + - `system_prompt`: The core instructions that define your agent's behavior + + - `model_name`: The GPT model to use + + - Additional configuration options for temperature and output format -#### Functionality: -Agents pass tasks in a circular manner, where each agent works on the next task in the list. +4. Run the example code below: -```mermaid -graph TD - Task1 --> Agent1 - Agent1 --> Agent2 - Agent2 --> Agent3 - Agent3 --> Task2 - Task2 --> Agent1 -``` ---- +## Code -### **2. Linear Swarm** +```python +import time +from swarms import Agent -#### Input Arguments: -- **name** (str): Name of the swarm. -- **description** (str): Description of the swarm. -- **agents** (AgentListType): List of agents involved. -- **tasks** (List[str]): List of tasks for the agents. -- **conversation** (Conversation): Conversation object. -- **return_full_history** (bool): Whether to return the full conversation history. +# Initialize the agent +agent = Agent( + 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=1, + model_name="gpt-4o-mini", + dynamic_temperature_enabled=True, + output_type="json", + safety_prompt_on=True, +) -#### Functionality: -Agents pass tasks in a linear fashion, each agent working on one task sequentially. +out = agent.run("What are the best top 3 etfs for gold coverage?") -```mermaid -graph LR - Task1 --> Agent1 - Agent1 --> Agent2 - Agent2 --> Agent3 - Agent3 --> Task2 +time.sleep(10) +print(out) ``` ---- +## Example Output -### **3. Star Swarm** +The agent will return a JSON response containing recommendations for gold ETFs based on the query. -#### Input Arguments: -- **agents** (AgentListType): List of agents involved. -- **tasks** (List[str]): List of tasks for the agents. +## Customization -#### Functionality: -A central agent (Agent 1) executes the tasks first, followed by the other agents working in parallel. +You can modify the system prompt and agent parameters to create specialized agents for different use cases: -```mermaid -graph TD - Task1 --> Agent1 - Agent1 --> Agent2 - Agent1 --> Agent3 - Agent1 --> Agent4 -``` +| Use Case | Description | +|----------|-------------| +| Market Analysis | Analyze market trends, patterns, and indicators to identify trading opportunities | +| Portfolio Management | Optimize asset allocation and rebalancing strategies | +| Risk Assessment | Evaluate and mitigate potential risks in trading strategies | +| Trading Strategy Development | Design and implement algorithmic trading strategies | ---- +-------------------------------------------------- -### **4. Mesh Swarm** +# File: swarms\examples\claude.md -#### Input Arguments: -- **agents** (AgentListType): List of agents involved. -- **tasks** (List[str]): List of tasks for the agents. +# Agent with Anthropic/Claude -#### Functionality: -Each agent works on tasks randomly from a task queue, until the task queue is empty. +- Get their api keys and put it in the `.env` -```mermaid -graph TD - Task1 --> Agent1 - Task2 --> Agent2 - Task3 --> Agent3 - Task4 --> Agent4 - Task5 --> Agent1 - Task6 --> Agent2 -``` +- Select your model_name like `claude-3-sonnet-20240229` follows LiteLLM conventions ---- -### **5. Grid Swarm** +```python +from swarms import Agent +import os +from dotenv import load_dotenv -#### Input Arguments: -- **agents** (AgentListType): List of agents involved. -- **tasks** (List[str]): List of tasks for the agents. +load_dotenv() -#### Functionality: -Agents are structured in a grid, and tasks are distributed accordingly. +# Initialize the agent with ChromaDB memory +agent = Agent( + agent_name="Financial-Analysis-Agent", + model_name="claude-3-sonnet-20240229", + system_prompt="Agent system prompt here", + agent_description="Agent performs financial analysis.", +) -```mermaid -graph TD - Task1 --> Agent1 - Task2 --> Agent2 - Task3 --> Agent3 - Task4 --> Agent4 +# Run a query +agent.run("What are the components of a startup's stock incentive equity plan?") ``` ---- +-------------------------------------------------- -### **6. Pyramid Swarm** +# File: swarms\examples\cohere.md -#### Input Arguments: -- **agents** (AgentListType): List of agents involved. -- **tasks** (List[str]): List of tasks for the agents. +# Agent with Cohere -#### Functionality: -Agents are arranged in a pyramid structure. Each level of agents works in sequence. +- Add your `COHERE_API_KEY` in the `.env` file -```mermaid -graph TD - Task1 --> Agent1 - Agent1 --> Agent2 - Agent2 --> Agent3 - Agent3 --> Task2 -``` +- Select your model_name like `command-r` follows LiteLLM conventions ---- -### **7. Fibonacci Swarm** +```python +from swarms import Agent +import os +from dotenv import load_dotenv -#### Input Arguments: -- **agents** (AgentListType): List of agents involved. -- **tasks** (List[str]): List of tasks for the agents. +load_dotenv() -#### Functionality: -Agents work according to the Fibonacci sequence, where the number of agents working on tasks follows this progression. +# Initialize the agent with ChromaDB memory +agent = Agent( + agent_name="Financial-Analysis-Agent", + model_name="command-r", + system_prompt="Agent system prompt here", + agent_description="Agent performs financial analysis.", +) -```mermaid -graph TD - Task1 --> Agent1 - Agent1 --> Agent2 - Agent2 --> Agent3 - Task2 --> Agent5 - Agent5 --> Agent8 +# Run a query +agent.run("What are the components of a startup's stock incentive equity plan?") ``` ---- - -### **8. Prime Swarm** - -#### Input Arguments: -- **agents** (AgentListType): List of agents involved. -- **tasks** (List[str]): List of tasks for the agents. +-------------------------------------------------- -#### Functionality: -Agents are assigned tasks based on prime number indices in the list of agents. +# File: swarms\examples\concurrent_workflow.md -```mermaid -graph TD - Task1 --> Agent2 - Task2 --> Agent3 - Task3 --> Agent5 - Task4 --> Agent7 -``` +# ConcurrentWorkflow Examples ---- +The ConcurrentWorkflow architecture enables parallel execution of multiple agents, allowing them to work simultaneously on different aspects of a task. This is particularly useful for complex tasks that can be broken down into independent subtasks. -### **9. Power Swarm** +## Prerequisites -#### Input Arguments: -- **agents** (AgentListType): List of agents involved. -- **tasks** (List[str]): List of tasks for the agents. +- Python 3.7+ +- OpenAI API key or other supported LLM provider keys +- Swarms library -#### Functionality: -Agents work on tasks following powers of two. +## Installation -```mermaid -graph TD - Task1 --> Agent1 - Task2 --> Agent2 - Task3 --> Agent4 - Task4 --> Agent8 +```bash +pip3 install -U swarms ``` ---- +## Environment Variables -### **10. Sigmoid Swarm** - -#### Input Arguments: -- **agents** (AgentListType): List of agents involved. -- **tasks** (List[str]): List of tasks for the agents. - -#### Functionality: -Agents are selected based on the sigmoid function, with higher-indexed agents handling more complex tasks. - -```mermaid -graph TD - Task1 --> Agent1 - Task2 --> Agent2 - Task3 --> Agent3 - Task4 --> Agent4 -``` - ---- - -### **11. Sinusoidal Swarm** - -#### Input Arguments: -- **agents** (AgentListType): List of agents involved. -- **task** (str): Task for the agents to work on. - -#### Functionality: -Agents are assigned tasks based on a sinusoidal pattern. - -```mermaid -graph TD - Task --> Agent1 - Agent1 --> Agent2 - Agent2 --> Agent3 - Agent3 --> Task2 +```plaintext +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" +ANTHROPIC_API_KEY="" +GROQ_API_KEY="" ``` ---- - -Each of these swarm architectures enables different task distribution and agent coordination strategies, making it possible to select the right architecture for specific types of agent-based problem-solving scenarios. - - +## Basic Usage -## Examples +### 1. Initialize Specialized Agents ```python +from swarms import Agent +from swarms.structs.concurrent_workflow import ConcurrentWorkflow -import asyncio -import os +# Initialize market research agent +market_researcher = Agent( + agent_name="Market-Researcher", + system_prompt="""You are a market research specialist. Your tasks include: + 1. Analyzing market trends and patterns + 2. Identifying market opportunities and threats + 3. Evaluating competitor strategies + 4. Assessing customer needs and preferences + 5. Providing actionable market insights""", + model_name="claude-3-sonnet-20240229", + max_loops=1, + temperature=0.7, +) -from dotenv import load_dotenv -from loguru import logger -from swarm_models import OpenAIChat -from tickr_agent.main import TickrAgent +# Initialize financial analyst agent +financial_analyst = Agent( + agent_name="Financial-Analyst", + system_prompt="""You are a financial analysis expert. Your responsibilities include: + 1. Analyzing financial statements + 2. Evaluating investment opportunities + 3. Assessing risk factors + 4. Providing financial forecasts + 5. Recommending financial strategies""", + model_name="claude-3-sonnet-20240229", + max_loops=1, + temperature=0.7, +) -from swarms.structs.swarming_architectures import ( - circular_swarm, - linear_swarm, - mesh_swarm, - pyramid_swarm, - star_swarm, +# Initialize technical analyst agent +technical_analyst = Agent( + agent_name="Technical-Analyst", + system_prompt="""You are a technical analysis specialist. Your focus areas include: + 1. Analyzing price patterns and trends + 2. Evaluating technical indicators + 3. Identifying support and resistance levels + 4. Assessing market momentum + 5. Providing trading recommendations""", + model_name="claude-3-sonnet-20240229", + max_loops=1, + temperature=0.7, ) -# Load environment variables (API keys) -load_dotenv() -api_key = os.getenv("OPENAI_API_KEY") +# Create list of agents +agents = [market_researcher, financial_analyst, technical_analyst] -# Initialize the OpenAI model -model = OpenAIChat( - openai_api_key=api_key, model_name="gpt-4", temperature=0.1 +# Initialize the concurrent workflow with dashboard +router = ConcurrentWorkflow( + name="market-analysis-router", + agents=agents, + max_loops=1, + show_dashboard=True, # Enable the real-time dashboard ) -# Custom Financial Agent System Prompts -STOCK_ANALYSIS_PROMPT = """ -You are an expert financial analyst. Your task is to analyze stock market data for a company -and provide insights on whether to buy, hold, or sell. Analyze trends, financial ratios, and market conditions. -""" +# Run the workflow +result = router.run( + "Analyze Tesla (TSLA) stock from market, financial, and technical perspectives" +) +``` -NEWS_SUMMARIZATION_PROMPT = """ -You are a financial news expert. Summarize the latest news related to a company and provide insights on -how it could impact its stock price. Be concise and focus on the key takeaways. -""" +## Features -RATIO_CALCULATION_PROMPT = """ -You are a financial ratio analyst. Your task is to calculate key financial ratios for a company -based on the available data, such as P/E ratio, debt-to-equity ratio, and return on equity. -Explain what each ratio means for investors. -""" +### Real-time Dashboard -# Example Usage -# Define stock tickers -stocks = ["AAPL", "TSLA"] +The ConcurrentWorkflow includes a powerful real-time dashboard feature that provides comprehensive monitoring and visualization of agent execution. Enable it by setting `show_dashboard=True` during workflow initialization. +#### Dashboard Features -# Initialize Financial Analysis Agents -stock_analysis_agent = TickrAgent( - agent_name="Stock-Analysis-Agent", - system_prompt=STOCK_ANALYSIS_PROMPT, - stocks=stocks, -) +- **Live Status Tracking**: Real-time updates showing each agent's execution status +- **Progress Visualization**: Visual indicators of agent progress and completion +- **Output Streaming**: Live display of agent outputs as they're generated +- **Error Monitoring**: Immediate visibility into any agent failures or errors +- **Performance Metrics**: Execution time and completion statistics +- **Clean Display**: Automatic cleanup and formatting for optimal viewing -news_summarization_agent = TickrAgent( - agent_name="News-Summarization-Agent", - system_prompt=NEWS_SUMMARIZATION_PROMPT, - stocks=stocks, +#### Dashboard Status Values -) +- **"pending"**: Agent is queued but not yet started +- **"running"**: Agent is currently executing the task +- **"completed"**: Agent finished successfully with output +- **"error"**: Agent execution failed with error details -ratio_calculation_agent = TickrAgent( - agent_name="Ratio-Calculation-Agent", - system_prompt=RATIO_CALCULATION_PROMPT, - stocks=stocks, +#### Dashboard Configuration +```python +# Enable dashboard with custom configuration +workflow = ConcurrentWorkflow( + name="my-workflow", + agents=agents, + show_dashboard=True, # Enable real-time monitoring + output_type="dict", # Configure output format + auto_save=True, # Auto-save conversation history ) -# Create a list of agents for swarming -agents = [ - stock_analysis_agent, - news_summarization_agent, - ratio_calculation_agent, -] +``` -# Define financial analysis tasks -tasks = [ - "Analyze the stock performance of Apple (AAPL) in the last 6 months.", - "Summarize the latest financial news on Tesla (TSLA).", - "Calculate the P/E ratio and debt-to-equity ratio for Amazon (AMZN).", -] +#### Dashboard Behavior -# -------------------------------# Showcase Circular Swarm -# ------------------------------- -logger.info("Starting Circular Swarm for financial analysis.") -circular_result = circular_swarm(agents, tasks) -logger.info(f"Circular Swarm Result:\n{circular_result}\n") +When `show_dashboard=True`: +- Individual agent print outputs are automatically disabled to prevent conflicts +- Dashboard updates every 100ms for smooth real-time streaming +- Initial dashboard shows all agents as "pending" +- Real-time updates show status changes and output previews +- Final dashboard displays complete results summary +- Automatic cleanup of dashboard resources after completion +### Concurrent Execution -# ------------------------------- -# Showcase Linear Swarm -# ------------------------------- -logger.info("Starting Linear Swarm for financial analysis.") -linear_result = linear_swarm(agents, tasks) -logger.info(f"Linear Swarm Result:\n{linear_result}\n") +- **ThreadPoolExecutor**: Uses 95% of available CPU cores for optimal performance +- **True Parallelism**: Agents execute simultaneously, not sequentially +- **Thread Safety**: Safe concurrent access to shared resources +- **Error Isolation**: Individual agent failures don't affect others +- **Resource Management**: Automatic thread lifecycle management +### Output Formatting Options -# ------------------------------- -# Showcase Star Swarm -# ------------------------------- -logger.info("Starting Star Swarm for financial analysis.") -star_result = star_swarm(agents, tasks) -logger.info(f"Star Swarm Result:\n{star_result}\n") +The workflow supports multiple output aggregation formats: +- **"dict-all-except-first"**: Dictionary with all agent outputs except the first (default) +- **"dict"**: Complete dictionary with all agent outputs keyed by agent name +- **"str"**: Concatenated string of all agent outputs +- **"list"**: List of individual agent outputs in completion order -# ------------------------------- -# Showcase Mesh Swarm -# ------------------------------- -logger.info("Starting Mesh Swarm for financial analysis.") -mesh_result = mesh_swarm(agents, tasks) -logger.info(f"Mesh Swarm Result:\n{mesh_result}\n") +```python +# Configure output format +workflow = ConcurrentWorkflow( + agents=agents, + output_type="dict", # Get complete dictionary of results + show_dashboard=True +) +``` +### Advanced Features -# ------------------------------- -# Showcase Pyramid Swarm -# ------------------------------- -logger.info("Starting Pyramid Swarm for financial analysis.") -pyramid_result = pyramid_swarm(agents, tasks) -logger.info(f"Pyramid Swarm Result:\n{pyramid_result}\n") +#### Auto Prompt Engineering +Enable automatic prompt optimization for all agents: -# ------------------------------- -# Example: One-to-One Communication between Agents -# ------------------------------- -logger.info( - "Starting One-to-One communication between Stock and News agents." -) -one_to_one_result = stock_analysis_agent.run( - "Analyze Apple stock performance, and then send the result to the News Summarization Agent" -) -news_summary_result = news_summarization_agent.run(one_to_one_result) -logger.info( - f"One-to-One Communication Result:\n{news_summary_result}\n" +```python +workflow = ConcurrentWorkflow( + agents=agents, + auto_generate_prompts=True, # Enable automatic prompt engineering + show_dashboard=True ) +``` +#### Conversation History Management -# ------------------------------- -# Example: Broadcasting to all agents -# ------------------------------- -async def broadcast_task(): - logger.info("Broadcasting task to all agents.") - task = "Summarize the overall stock market performance today." - await asyncio.gather(*[agent.run(task) for agent in agents]) - +Automatic conversation tracking and persistence: -asyncio.run(broadcast_task()) +```python +workflow = ConcurrentWorkflow( + agents=agents, + auto_save=True, # Auto-save conversation history + metadata_output_path="results.json" # Custom output file path +) +``` +#### Multimodal Support -# ------------------------------- -# Deep Comments & Explanations -# ------------------------------- +Support for image inputs across all agents: -""" -Explanation of Key Components: +```python +# Single image input +result = workflow.run( + task="Analyze this chart", + img="financial_chart.png" +) -1. **Agents**: - - We created three specialized agents for financial analysis: Stock Analysis, News Summarization, and Ratio Calculation. - - Each agent is provided with a custom system prompt that defines their unique task in analyzing stock data. +# Multiple image inputs +result = workflow.run( + task="Compare these charts", + imgs=["chart1.png", "chart2.png", "chart3.png"] +) +``` -2. **Swarm Examples**: - - **Circular Swarm**: Agents take turns processing tasks in a circular manner. - - **Linear Swarm**: Tasks are processed sequentially by each agent. - - **Star Swarm**: The first agent (Stock Analysis) processes all tasks before distributing them to other agents. - - **Mesh Swarm**: Agents work on random tasks from the task queue. - - **Pyramid Swarm**: Agents are arranged in a pyramid structure, processing tasks layer by layer. +## Best Practices -3. **One-to-One Communication**: - - This showcases how one agent can pass its result to another agent for further processing, useful for complex workflows where agents depend on each other. +### 1. Dashboard Usage -4. **Broadcasting**: - - The broadcasting function demonstrates how a single task can be sent to all agents simultaneously. This can be useful for situations like summarizing daily stock market performance across multiple agents. +- **Development & Debugging**: Use dashboard for real-time monitoring during development +- **Production**: Consider disabling dashboard for headless execution in production +- **Performance**: Dashboard adds minimal overhead but provides valuable insights +- **Error Handling**: Dashboard immediately shows which agents fail and why -5. **Logging with Loguru**: - - We use `loguru` for detailed logging throughout the swarms. This helps to track the flow of information and responses from each agent. -""" +### 2. Agent Configuration +- **Specialization**: Use specialized agents for specific tasks +- **Model Selection**: Choose appropriate models for each agent's role +- **Temperature**: Configure temperature based on task requirements +- **System Prompts**: Write clear, specific system prompts for each agent +### 3. Resource Management -``` +- **CPU Utilization**: Workflow automatically uses 95% of available cores +- **Memory**: Monitor conversation history growth in long-running workflows +- **Rate Limits**: Handle API rate limits appropriately for your LLM provider +- **Error Recovery**: Implement fallback mechanisms for failed agents --------------------------------------------------- +### 4. Task Design -# File: swarms/concept/swarm_ecosystem.md +- **Independence**: Ensure tasks can be processed concurrently without dependencies +- **Granularity**: Break complex tasks into independent subtasks +- **Balance**: Distribute work evenly across agents for optimal performance -# Understanding the Swarms Ecosystem +## Example Implementations -The [Swarms Ecosystem](https://github.com/The-Swarm-Corporation/swarm-ecosystem) is a powerful suite of tools and frameworks designed to help developers build, deploy, and manage swarms of autonomous agents. This ecosystem covers various domains, from Large Language Models (LLMs) to IoT data integration, providing a comprehensive platform for automation and scalability. Below, we’ll explore the key components and how they contribute to this groundbreaking ecosystem. +### Comprehensive Market Analysis -#### 1. **Swarms Framework** +```python +from swarms import Agent +from swarms.structs.concurrent_workflow import ConcurrentWorkflow -The [Swarms Framework](https://github.com/The-Swarm-Corporation/swarm-ecosystem) is a Python-based toolkit that simplifies the creation, orchestration, and scaling of swarms of agents. Whether you are dealing with marketing, accounting, or data analysis, the Swarms Framework allows developers to automate complex workflows efficiently. +# Initialize specialized agents +market_analyst = Agent( + agent_name="Market-Analyst", + system_prompt="""You are a market analysis specialist focusing on: + 1. Market trends and patterns + 2. Competitive analysis + 3. Market opportunities + 4. Industry dynamics + 5. Growth potential""", + model_name="claude-3-sonnet-20240229", + max_loops=1, + temperature=0.7, +) -```mermaid -graph TD; - SF[Swarms Framework] --> Core[Swarms Core] - SF --> JS[Swarms JS] - SF --> Memory[Swarms Memory] - SF --> Evals[Swarms Evals] - SF --> Zero[Swarms Zero] -``` +financial_analyst = Agent( + agent_name="Financial-Analyst", + system_prompt="""You are a financial analysis expert specializing in: + 1. Financial statements analysis + 2. Ratio analysis + 3. Cash flow analysis + 4. Valuation metrics + 5. Risk assessment""", + model_name="claude-3-sonnet-20240229", + max_loops=1, + temperature=0.7, +) -#### 2. **Swarms-Cloud** +risk_analyst = Agent( + agent_name="Risk-Analyst", + system_prompt="""You are a risk assessment specialist focusing on: + 1. Market risks + 2. Operational risks + 3. Financial risks + 4. Regulatory risks + 5. Strategic risks""", + model_name="claude-3-sonnet-20240229", + max_loops=1, + temperature=0.7, +) -[Swarms-Cloud](https://github.com/The-Swarm-Corporation/swarm-ecosystem) is a cloud-based solution that enables you to deploy your agents with enterprise-level guarantees. It provides 99% uptime, infinite scalability, and self-healing capabilities, making it ideal for mission-critical operations. +# Create the concurrent workflow with dashboard +workflow = ConcurrentWorkflow( + name="comprehensive-analysis-workflow", + agents=[market_analyst, financial_analyst, risk_analyst], + max_loops=1, + show_dashboard=True, # Enable real-time monitoring + output_type="dict", # Get structured results + auto_save=True, # Save conversation history +) -```mermaid -graph TD; - SC[Swarms-Cloud] --> Uptime[99% Uptime] - SC --> Scale[Infinite Scalability] - SC --> Healing[Self-Healing] +try: + result = workflow.run( + """Provide a comprehensive analysis of Apple Inc. (AAPL) including: + 1. Market position and competitive analysis + 2. Financial performance and health + 3. Risk assessment and mitigation strategies""" + ) + + # Process and display results + print("\nAnalysis Results:") + print("=" * 50) + for agent_name, output in result.items(): + print(f"\nAnalysis from {agent_name}:") + print("-" * 40) + print(output) + +except Exception as e: + print(f"Error during analysis: {str(e)}") ``` -#### 3. **Swarms-Models** - -[Swarms-Models](https://github.com/The-Swarm-Corporation/swarm-ecosystem) offer a seamless interface to leading LLM providers like OpenAI, Anthropic, and Ollama. It allows developers to tap into cutting-edge natural language understanding for their agents. +### Batch Processing with Dashboard -```mermaid -graph TD; - SM[Swarms-Models] --> OpenAI[OpenAI API] - SM --> Anthropic[Anthropic API] - SM --> Ollama[Ollama API] -``` +```python +# Process multiple tasks sequentially with concurrent agent execution +tasks = [ + "Analyze Q1 financial performance and market position", + "Analyze Q2 financial performance and market position", + "Analyze Q3 financial performance and market position", + "Analyze Q4 financial performance and market position" +] -#### 4. **AgentParse** +# Optional: corresponding images for each task +charts = ["q1_chart.png", "q2_chart.png", "q3_chart.png", "q4_chart.png"] -[AgentParse](https://github.com/The-Swarm-Corporation/swarm-ecosystem) is a high-performance library for mapping structured data like JSON, YAML, CSV, and Pydantic models into formats understandable by agents. This ensures fast, seamless data ingestion. +# Batch processing with dashboard monitoring +results = workflow.batch_run(tasks, imgs=charts) -```mermaid -graph TD; - AP[AgentParse] --> JSON[JSON Parsing] - AP --> YAML[YAML Parsing] - AP --> CSV[CSV Parsing] - AP --> Pydantic[Pydantic Model Parsing] +print(f"Completed {len(results)} quarterly analyses") +for i, result in enumerate(results): + print(f"\nQ{i+1} Analysis Results:") + print(result) ``` -#### 5. **Swarms-Platform** +### Multimodal Analysis -The [Swarms-Platform](https://github.com/The-Swarm-Corporation/swarm-ecosystem) is a marketplace where developers can find, buy, and sell autonomous agents. It enables the rapid scaling of agent ecosystems by leveraging ready-made solutions. +```python +# Analyze financial charts with multiple specialized agents +workflow = ConcurrentWorkflow( + agents=[technical_analyst, fundamental_analyst, sentiment_analyst], + show_dashboard=True, + output_type="dict" +) -```mermaid -graph TD; - SP[Swarms-Platform] --> Discover[Discover Agents] - SP --> Buy[Buy Agents] - SP --> Sell[Sell Agents] -``` +# Analyze a single chart +result = workflow.run( + task="Analyze this stock chart and provide trading insights", + img="stock_chart.png" +) -#### Extending the Ecosystem: **Swarms Core**, **JS**, and More +# Analyze multiple charts +result = workflow.run( + task="Compare these three charts and identify patterns", + imgs=["chart1.png", "chart2.png", "chart3.png"] +) +``` -In addition to the core components, the Swarms Ecosystem offers several other powerful packages: +### Error Handling and Monitoring -- **[Swarms Core](https://github.com/kyegomez/swarms)**: Built in Rust, Swarms Core handles concurrency, multi-threading, and execution strategies. -- **[Swarms JS](https://github.com/The-Swarm-Corporation/swarm-js)**: Allows JavaScript-based orchestration of multi-agent systems. -- **[Swarms Memory](https://github.com/The-Swarm-Corporation/swarm-memory)**: Provides Retrieval Augmented Generation (RAG) systems for long-term memory in agents. -- **[Swarms Evals](https://github.com/The-Swarm-Corporation/swarm-evals)**: Used for evaluating the performance of swarms of agents. -- **[Swarms Zero](https://github.com/The-Swarm-Corporation/zero)**: An RPC-based enterprise-grade automation framework. +```python +# Workflow with comprehensive error handling +workflow = ConcurrentWorkflow( + agents=agents, + show_dashboard=True, # Monitor execution in real-time + auto_save=True, # Preserve results even if errors occur + output_type="dict" # Get structured results for easier processing +) -```mermaid -graph TD; - SC[Swarms Core] --> Rust[Rust for Performance] - JS[Swarms JS] --> MultiAgent[Multi-Agent Orchestration] - Memory[Swarms Memory] --> RAG[Retrieval Augmented Generation] - Evals[Swarms Evals] --> Evaluation[Agent Evaluations] - Zero[Swarms Zero] --> Automation[Enterprise Automation] +try: + result = workflow.run("Complex analysis task") + + # Check for errors in results + for agent_name, output in result.items(): + if output.startswith("Error:"): + print(f"Agent {agent_name} failed: {output}") + else: + print(f"Agent {agent_name} completed successfully") + +except Exception as e: + print(f"Workflow execution failed: {str(e)}") + # Results may still be available for successful agents ``` -### Conclusion +## Performance Tips -The Swarms Ecosystem is a comprehensive, flexible, and scalable platform for managing and deploying autonomous agents. Whether you’re working with LLMs, IoT data, or building new models, the ecosystem provides the tools necessary to simplify automation at scale. +1. **Agent Count**: Use 2+ agents to benefit from concurrent execution +2. **CPU Utilization**: Workflow automatically optimizes for available cores +3. **Dashboard Overhead**: Minimal performance impact for valuable monitoring +4. **Memory Management**: Clear conversation history for very large batch jobs +5. **Error Recovery**: Failed agents don't stop successful ones -Start exploring the possibilities by checking out the [Swarms Ecosystem GitHub repository](https://github.com/The-Swarm-Corporation/swarm-ecosystem) and join our growing community of developers and innovators. +## Use Cases +- **Multi-perspective Analysis**: Financial, legal, technical reviews +- **Consensus Building**: Voting systems and decision making +- **Parallel Processing**: Data analysis and batch operations +- **A/B Testing**: Different agent configurations and strategies +- **Redundancy**: Reliability improvements through multiple agents +- **Real-time Monitoring**: Development and debugging workflows +This guide demonstrates how to effectively use the ConcurrentWorkflow architecture with its advanced dashboard feature for parallel processing of complex tasks using multiple specialized agents. -------------------------------------------------- -# File: swarms/concept/vision.md +# File: swarms\examples\deepseek.md -# Swarms – The Ultimate Multi-Agent LLM Framework for Developers - -Swarms aims to be the definitive and most reliable multi-agent LLM framework, offering developers the tools to automate business operations effortlessly. It provides a vast array of swarm architectures, seamless third-party integration, and unparalleled ease of use. With Swarms, developers can orchestrate intelligent, scalable agent ecosystems that can automate complex business processes. +# Agent with DeepSeek -### Key Features for Developers: -1. **Architectural Flexibility** – Choose from a wide variety of pre-built swarm architectures or build custom agent frameworks. Swarms allows developers to define flexible workflows for specific use cases, providing both sequential and concurrent task execution. -2. **Third-Party Integration** – Swarms makes it simple to integrate with external APIs, databases, and other platforms. By supporting extreme integration capabilities, it ensures your agents work effortlessly within any workflow. -3. **Developer-Centric APIs** – The Swarms API is built with developers in mind, offering an intuitive, simple-to-use interface. Developers can orchestrate agent swarms with minimal code and maximum control. +- Add your `DEEPSEEK_API_KEY` in the `.env` file ---- +- Select your model_name like `deepseek/deepseek-chat` follows [LiteLLM conventions](https://docs.litellm.ai/docs/providers/deepseek) -### Code Examples +- Execute your agent! -#### 1. Basic Financial Analysis Agent: -This example demonstrates a simple financial agent setup that responds to financial questions, such as establishing a ROTH IRA, using OpenAI's GPT-based model. ```python -import os from swarms import Agent -from swarm_models import OpenAIChat -from swarms.prompts.finance_agent_sys_prompt import ( - FINANCIAL_AGENT_SYS_PROMPT, -) +import os from dotenv import load_dotenv -# Load environment variables load_dotenv() -# Get OpenAI API key from environment -api_key = os.getenv("OPENAI_API_KEY") - -# Initialize OpenAIChat model with desired parameters -model = OpenAIChat( - openai_api_key=api_key, model_name="gpt-4o-mini", temperature=0.1 -) - -# Initialize the Financial Analysis Agent +# Initialize the agent with ChromaDB memory agent = Agent( agent_name="Financial-Analysis-Agent", - system_prompt=FINANCIAL_AGENT_SYS_PROMPT, - llm=model, - max_loops=1, - autosave=True, - dashboard=False, - verbose=True, - dynamic_temperature_enabled=True, - saved_state_path="finance_agent.json", - user_name="swarms_corp", - retry_attempts=1, - context_length=200000, - return_step_meta=False, -) - -# Example task for the agent -out = agent.run( - "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?" + model_name="deepseek/deepseek-chat", + system_prompt="Agent system prompt here", + agent_description="Agent performs financial analysis.", ) -# Output the agent's result -print(out) +# Run a query +agent.run("What are the components of a startup's stock incentive equity plan?") ``` -#### 2. Agent Orchestration with AgentRearrange: -The following example showcases how to use the `AgentRearrange` class to manage a multi-agent system. It sets up a director agent to orchestrate two workers—one to generate a transcript and another to summarize it. - -```python -from swarms import Agent, AgentRearrange -from swarm_models import Anthropic - -# Initialize the Director agent -director = Agent( - agent_name="Director", - system_prompt="Directs the tasks for the workers", - llm=Anthropic(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="director.json", -) - -# Initialize Worker 1 agent (transcript generation) -worker1 = Agent( - agent_name="Worker1", - system_prompt="Generates a transcript for a YouTube video on what swarms are", - llm=Anthropic(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="worker1.json", -) +## R1 -# Initialize Worker 2 agent (summarizes transcript) -worker2 = Agent( - agent_name="Worker2", - system_prompt="Summarizes the transcript generated by Worker1", - llm=Anthropic(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="worker2.json", -) +This is a simple example of how to use the DeepSeek Reasoner model otherwise known as R1. -# Create a list of agents -agents = [director, worker1, worker2] +```python -# Define the workflow pattern (sequential flow) -flow = "Director -> Worker1 -> Worker2" +import os +from swarms import Agent +from dotenv import load_dotenv -# Using AgentRearrange to orchestrate the agents -agent_system = AgentRearrange(agents=agents, flow=flow) +load_dotenv() -# Running the system with a sample task -output = agent_system.run( - "Create a format to express and communicate swarms of LLMs in a structured manner for YouTube" +# Initialize the agent with ChromaDB memory +agent = Agent( + agent_name="Financial-Analysis-Agent", + model_name="deepseek/deepseek-reasoner", + system_prompt="Agent system prompt here", + agent_description="Agent performs financial analysis.", ) -# Output the result -print(output) -``` - -#### 1. Basic Agent Flow: -Here’s a visual representation of the basic workflow using Mermaid to display the sequential flow between agents. - -```mermaid -flowchart TD - A[Director] --> B[Worker 1: Generate Transcript] - B --> C[Worker 2: Summarize Transcript] +# Run a query +agent.run("What are the components of a startup's stock incentive equity plan?") ``` -In this diagram: -- The **Director** agent assigns tasks. -- **Worker 1** generates a transcript for a YouTube video. -- **Worker 2** summarizes the transcript. - -#### 2. Sequential Agent Flow: -This diagram showcases a sequential agent setup where one agent completes its task before the next agent starts its task. - -```mermaid -flowchart TD - A[Director] --> B[Worker 1: Generate Transcript] - B --> C[Worker 2: Summarize Transcript] - C --> D[Worker 3: Finalize] -``` +-------------------------------------------------- -In this setup: +# File: swarms\examples\groq.md -- The **Director** agent assigns tasks to **Worker 1**, which generates a transcript for a YouTube video. +# Agent with Groq -- **Worker 1** completes its task before **Worker 2** starts summarizing the transcript. +- Add your `GROQ_API_KEY` -- **Worker 2** completes its task before **Worker 3** finalizes the process. +- Initiate your agent -### Why Developers Should Choose Swarms: +- Run your agent -Swarms is designed with flexibility at its core. Developers can create custom architectures and workflows, enabling extreme control over how agents interact with each other. Whether it’s a linear process or a complex mesh of agent communications, Swarms handles it efficiently. +```python +import os -With support for extreme third-party integration, Swarms makes it easy for developers to plug into external systems, such as APIs or internal databases. This allows agents to act on live data, process external inputs, and execute actions in real time, making it a powerful tool for real-world applications. +from swarm_models import OpenAIChat -Swarms abstracts the complexity of managing multiple agents with orchestration tools like `AgentRearrange`. Developers can define workflows that execute tasks concurrently or sequentially, depending on the problem at hand. This makes it easy to build and maintain large-scale automation systems. +from swarms import Agent -### Conclusion: -Swarms is not just another multi-agent framework; it's built specifically for developers who need powerful tools to automate complex, large-scale business operations. With flexible architecture, deep integration capabilities, and developer-friendly APIs, Swarms is the ultimate solution for businesses looking to streamline operations and future-proof their workflows. +company = "NVDA" +# Initialize the Managing Director agent +managing_director = Agent( + agent_name="Managing-Director", + system_prompt=f""" + As the Managing Director at Blackstone, your role is to oversee the entire investment analysis process for potential acquisitions. + Your responsibilities include: + 1. Setting the overall strategy and direction for the analysis + 2. Coordinating the efforts of the various team members and ensuring a comprehensive evaluation + 3. Reviewing the findings and recommendations from each team member + 4. Making the final decision on whether to proceed with the acquisition + + For the current potential acquisition of {company}, direct the tasks for the team to thoroughly analyze all aspects of the company, including its financials, industry position, technology, market potential, and regulatory compliance. Provide guidance and feedback as needed to ensure a rigorous and unbiased assessment. + """, + model_name="groq/deepseek-r1-distill-qwen-32b", + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="managing-director.json", +) +``` -------------------------------------------------- -# File: swarms/concept/why.md - -**Maximizing Enterprise Automation: Overcoming the Limitations of Individual AI Agents Through Multi-Agent Collaboration** - - -In today's rapidly evolving business landscape, enterprises are constantly seeking innovative solutions to enhance efficiency, reduce operational costs, and maintain a competitive edge. Automation has emerged as a critical strategy for achieving these objectives, with artificial intelligence (AI) playing a pivotal role. AI agents, particularly those powered by advanced machine learning models, have shown immense potential in automating a variety of tasks. However, individual AI agents come with inherent limitations that hinder their ability to fully automate complex enterprise operations at scale. +# File: swarms\examples\groupchat_example.md -This essay dives into the specific limitations of individual AI agents—context window limits, hallucination, single-task execution, lack of collaboration, lack of accuracy, and slow processing speed—and explores how multi-agent collaboration can overcome these challenges. By tailoring our discussion to the needs of enterprises aiming to automate operations at scale, we highlight practical strategies and frameworks that can be adopted to unlock the full potential of AI-driven automation. +# GroupChat Example ---- +!!! abstract "Overview" + Learn how to create and configure a group chat with multiple AI agents using the Swarms framework. This example demonstrates how to set up agents for expense analysis and budget advising. -### Part 1: The Limitations of Individual AI Agents +## Prerequisites -Despite significant advancements, individual AI agents face several obstacles that limit their effectiveness in enterprise automation. Understanding these limitations is crucial for organizations aiming to implement AI solutions that are both efficient and scalable. +!!! info "Before You Begin" + Make sure you have: + - Python 3.7+ installed + - A valid API key for your model provider + - The Swarms package installed -#### 1. Context Window Limits +## Installation -**Explanation** +```bash +pip install swarms +``` -AI agents, especially those based on language models like GPT-3 or GPT-4, operate within a fixed context window. This means they can only process and consider a limited amount of information (tokens) at a time. In practical terms, this restricts the agent's ability to handle large documents, long conversations, or complex datasets that exceed their context window. +## Environment Setup -**Impact on Enterprises** +!!! tip "API Key Configuration" + Set your API key in the `.env` file: + ```bash + OPENAI_API_KEY="your-api-key-here" + ``` -For enterprises, this limitation poses significant challenges. Business operations often involve processing extensive documents such as legal contracts, technical manuals, or large datasets. An AI agent with a limited context window may miss crucial information located outside its immediate context, leading to incomplete analyses or erroneous conclusions. +## Code Implementation +### Import Required Modules -```mermaid -graph LR - Subgraph[Context Window Limit] - Input[Large Document] - Agent[AI Agent] - Output[Partial Understanding] - Input -- Truncated Data --> Agent - Agent -- Generates --> Output - end +```python +from dotenv import load_dotenv +import os +from swarms import Agent, GroupChat ``` -*An AI agent processes only a portion of a large document due to context window limits, resulting in partial understanding.* +### Configure Agents -#### 2. Hallucination +!!! example "Agent Configuration" + Here's how to set up your agents with specific roles: -**Explanation** + ```python + # Expense Analysis Agent + agent1 = Agent( + agent_name="Expense-Analysis-Agent", + description="You are an accounting agent specializing in analyzing potential expenses.", + model_name="gpt-4o-mini", + max_loops=1, + autosave=False, + dashboard=False, + verbose=True, + dynamic_temperature_enabled=True, + user_name="swarms_corp", + retry_attempts=1, + context_length=200000, + output_type="string", + streaming_on=False, + max_tokens=15000, + ) -Hallucination refers to the tendency of AI agents to produce outputs that are not grounded in the input data or reality. They may generate plausible-sounding but incorrect or nonsensical information, especially when uncertain or when the input data is ambiguous. + # Budget Adviser Agent + agent2 = Agent( + agent_name="Budget-Adviser-Agent", + description="You are a budget adviser who provides insights on managing and optimizing expenses.", + model_name="gpt-4o-mini", + max_loops=1, + autosave=False, + dashboard=False, + verbose=True, + dynamic_temperature_enabled=True, + user_name="swarms_corp", + retry_attempts=1, + context_length=200000, + output_type="string", + streaming_on=False, + max_tokens=15000, + ) + ``` -**Impact on Enterprises** +### Initialize GroupChat -In enterprise settings, hallucinations can lead to misinformation, poor decision-making, and a lack of trust in AI systems. For instance, if an AI agent generates incorrect financial forecasts or misinterprets regulatory requirements, the consequences could be financially damaging and legally problematic. +!!! example "GroupChat Setup" + Configure the GroupChat with your agents: + ```python + agents = [agent1, agent2] -```mermaid -graph TD - Input[Ambiguous Data] - Agent[AI Agent] - Output[Incorrect Information] - Input --> Agent - Agent --> Output -``` + chat = GroupChat( + name="Expense Advisory", + description="Accounting group focused on discussing potential expenses", + agents=agents, + max_loops=1, + output_type="all", + ) + ``` -*An AI agent generates incorrect information (hallucination) when processing ambiguous data.* +### Run the Chat -#### 3. Single Task Execution +!!! example "Execute the Chat" + Start the conversation between agents: -**Explanation** + ```python + history = chat.run( + "What potential expenses should we consider for the upcoming quarter? Please collaborate to outline a comprehensive list." + ) + ``` -Many AI agents are designed to excel at a specific task or a narrow set of functions. They lack the flexibility to perform multiple tasks simultaneously or adapt to new tasks without significant reconfiguration or retraining. +## Complete Example -**Impact on Enterprises** +!!! success "Full Implementation" + Here's the complete code combined: -Enterprises require systems that can handle a variety of tasks, often concurrently. Relying on single-task agents necessitates deploying multiple separate agents, which can lead to integration challenges, increased complexity, and higher maintenance costs. + ```python + from dotenv import load_dotenv + import os + from swarms import Agent, GroupChat + if __name__ == "__main__": + # Load environment variables + load_dotenv() + api_key = os.getenv("OPENAI_API_KEY") -```mermaid -graph LR - TaskA[Task A] --> AgentA[Agent A] - TaskB[Task B] --> AgentB[Agent B] - AgentA --> OutputA[Result A] - AgentB --> OutputB[Result B] -``` + # Configure agents + agent1 = Agent( + agent_name="Expense-Analysis-Agent", + description="You are an accounting agent specializing in analyzing potential expenses.", + model_name="gpt-4o-mini", + max_loops=1, + autosave=False, + dashboard=False, + verbose=True, + dynamic_temperature_enabled=True, + user_name="swarms_corp", + retry_attempts=1, + context_length=200000, + output_type="string", + streaming_on=False, + max_tokens=15000, + ) -*Separate agents handle different tasks independently, lacking integration.* + agent2 = Agent( + agent_name="Budget-Adviser-Agent", + description="You are a budget adviser who provides insights on managing and optimizing expenses.", + model_name="gpt-4o-mini", + max_loops=1, + autosave=False, + dashboard=False, + verbose=True, + dynamic_temperature_enabled=True, + user_name="swarms_corp", + retry_attempts=1, + context_length=200000, + output_type="string", + streaming_on=False, + max_tokens=15000, + ) -#### 4. Lack of Collaboration + # Initialize GroupChat + agents = [agent1, agent2] + chat = GroupChat( + name="Expense Advisory", + description="Accounting group focused on discussing potential expenses", + agents=agents, + max_loops=1, + output_type="all", + ) -**Explanation** + # Run the chat + history = chat.run( + "What potential expenses should we consider for the upcoming quarter? Please collaborate to outline a comprehensive list." + ) + ``` -Individual AI agents typically operate in isolation, without the ability to communicate or collaborate with other agents. This siloed operation prevents them from sharing insights, learning from each other, or coordinating actions to achieve a common goal. +## Configuration Options -**Impact on Enterprises** +!!! info "Key Parameters" + | Parameter | Description | Default | + |-----------|-------------|---------| + | `max_loops` | Maximum number of conversation loops | 1 | + | `autosave` | Enable automatic saving of chat history | False | + | `dashboard` | Enable dashboard visualization | False | + | `verbose` | Enable detailed logging | True | + | `dynamic_temperature_enabled` | Enable dynamic temperature adjustment | True | + | `retry_attempts` | Number of retry attempts for failed operations | 1 | + | `context_length` | Maximum context length for the model | 200000 | + | `max_tokens` | Maximum tokens for model output | 15000 | -Complex enterprise operations often require coordinated efforts across different functions and departments. The inability of AI agents to collaborate limits their effectiveness in such environments, leading to disjointed processes and suboptimal outcomes. +## Next Steps +!!! tip "What to Try Next" + 1. Experiment with different agent roles and descriptions + 2. Adjust the `max_loops` parameter to allow for longer conversations + 3. Enable the dashboard to visualize agent interactions + 4. Try different model configurations and parameters -```mermaid -graph LR - Agent1[Agent 1] - Agent2[Agent 2] - Agent3[Agent 3] - Agent1 -->|No Communication| Agent2 - Agent2 -->|No Communication| Agent3 -``` +## Troubleshooting -*Agents operate without collaboration, resulting in isolated efforts.* +!!! warning "Common Issues" + - Ensure your API key is correctly set in the `.env` file + - Check that all required dependencies are installed + - Verify that your model provider's API is accessible + - Monitor the `verbose` output for detailed error messages -#### 5. Lack of Accuracy +## Additional Resources -**Explanation** +- [Swarms Documentation](https://docs.swarms.world) +- [API Reference](https://docs.swarms.world/api) +- [Examples Gallery](https://docs.swarms.world/examples) -AI agents may produce inaccurate results due to limitations in their training data, algorithms, or inability to fully understand complex inputs. Factors such as data bias, overfitting, or lack of domain-specific knowledge contribute to this inaccuracy. +-------------------------------------------------- -**Impact on Enterprises** +# File: swarms\examples\hhcs_examples.md -Inaccurate outputs can have serious ramifications for businesses, including flawed strategic decisions, customer dissatisfaction, and compliance risks. High accuracy is essential for tasks like financial analysis, customer service, and regulatory compliance. +# Hybrid Hierarchical-Cluster Swarm (HHCS) Example -```mermaid -graph TD - Input[Complex Data] - Agent[AI Agent] - Output[Inaccurate Result] - Input --> Agent - Agent --> Output -``` +1. Get your GROQ api key +2. Create a `.env` file in the root directory and add your API key: `GROQ_API_KEY` +3. Write the following code: +4. Run the file -*An AI agent produces an inaccurate result when handling complex data.* +```python -#### 6. Slow Processing Speed +from swarms import Agent, SwarmRouter, HybridHierarchicalClusterSwarm -**Explanation** -Some AI agents require significant computational resources and time to process data and generate outputs. Factors like model complexity, inefficient algorithms, or hardware limitations can contribute to slow processing speeds. +# Core Legal Agent Definitions with short, simple prompts +litigation_agent = Agent( + agent_name="Litigator", + system_prompt="You handle lawsuits. Analyze facts, build arguments, and develop case strategy.", + model_name="groq/deepseek-r1-distill-qwen-32b", + max_loops=1, +) -**Impact on Enterprises** +corporate_agent = Agent( + agent_name="Corporate-Attorney", + system_prompt="You handle business law. Advise on corporate structure, governance, and transactions.", + model_name="groq/deepseek-r1-distill-qwen-32b", + max_loops=1, +) -Slow processing impedes real-time decision-making and responsiveness. In fast-paced business environments, delays can lead to missed opportunities, reduced productivity, and competitive disadvantages. +ip_agent = Agent( + agent_name="IP-Attorney", + system_prompt="You protect intellectual property. Handle patents, trademarks, copyrights, and trade secrets.", + model_name="groq/deepseek-r1-distill-qwen-32b", + max_loops=1, +) +employment_agent = Agent( + agent_name="Employment-Attorney", + system_prompt="You handle workplace matters. Address hiring, termination, discrimination, and labor issues.", + model_name="groq/deepseek-r1-distill-qwen-32b", + max_loops=1, +) -```mermaid -graph TD - Input[Data] - Agent[AI Agent] - Delay[Processing Delay] - Output[Delayed Response] - Input --> Agent - Agent --> Delay - Delay --> Output -``` +paralegal_agent = Agent( + agent_name="Paralegal", + system_prompt="You assist attorneys. Conduct research, draft documents, and organize case files.", + model_name="groq/deepseek-r1-distill-qwen-32b", + max_loops=1, +) -*An AI agent's slow processing leads to delayed responses.* +doc_review_agent = Agent( + agent_name="Document-Reviewer", + system_prompt="You examine documents. Extract key information and identify relevant content.", + model_name="groq/deepseek-r1-distill-qwen-32b", + max_loops=1, +) ---- +# Practice Area Swarm Routers +litigation_swarm = SwarmRouter( + name="litigation-practice", + description="Handle all aspects of litigation", + agents=[litigation_agent, paralegal_agent, doc_review_agent], + swarm_type="SequentialWorkflow", +) -### Part 2: Overcoming Limitations Through Multi-Agent Collaboration +corporate_swarm = SwarmRouter( + name="corporate-practice", + description="Handle business and corporate legal matters", + agents=[corporate_agent, paralegal_agent], + swarm_type="SequentialWorkflow", +) -To address the challenges posed by individual AI agents, enterprises can adopt a multi-agent collaboration approach. By orchestrating multiple agents with complementary skills and functionalities, organizations can enhance performance, accuracy, and scalability in their automation efforts. +ip_swarm = SwarmRouter( + name="ip-practice", + description="Handle intellectual property matters", + agents=[ip_agent, paralegal_agent], + swarm_type="SequentialWorkflow", +) -#### 1. Extending Context Window Through Distributed Processing +employment_swarm = SwarmRouter( + name="employment-practice", + description="Handle employment and labor law matters", + agents=[employment_agent, paralegal_agent], + swarm_type="SequentialWorkflow", +) -**Solution** +# Cross-functional Swarm Router +m_and_a_swarm = SwarmRouter( + name="mergers-acquisitions", + description="Handle mergers and acquisitions", + agents=[ + corporate_agent, + ip_agent, + employment_agent, + doc_review_agent, + ], + swarm_type="ConcurrentWorkflow", +) -By dividing large inputs into smaller segments, multiple agents can process different parts simultaneously. A coordinating agent can then aggregate the results to form a comprehensive understanding. +dispute_swarm = SwarmRouter( + name="dispute-resolution", + description="Handle complex disputes requiring multiple specialties", + agents=[litigation_agent, corporate_agent, doc_review_agent], + swarm_type="ConcurrentWorkflow", +) -**Implementation in Enterprises** -- **Document Analysis:** For lengthy legal contracts, agents can each analyze specific sections, and a master agent can compile insights and ensure consistency. -- **Customer Interaction History:** In customer service, agents can handle different segments of a customer's history to provide personalized support. +hybrid_hiearchical_swarm = HybridHierarchicalClusterSwarm( + name="hybrid-hiearchical-swarm", + description="A hybrid hiearchical swarm that uses a hybrid hiearchical peer model to solve complex tasks.", + swarms=[ + litigation_swarm, + corporate_swarm, + ip_swarm, + employment_swarm, + m_and_a_swarm, + dispute_swarm, + ], + max_loops=1, + router_agent_model_name="gpt-4o-mini", +) -```mermaid -graph LR - Input[Large Document] - Splitter[Splitter Agent] - A1[Agent 1] - A2[Agent 2] - A3[Agent 3] - Aggregator[Aggregator Agent] - Output[Comprehensive Analysis] - Input --> Splitter - Splitter --> A1 - Splitter --> A2 - Splitter --> A3 - A1 --> Aggregator - A2 --> Aggregator - A3 --> Aggregator - Aggregator --> Output +if __name__ == "__main__": + hybrid_hiearchical_swarm.run( + "What is the best way to file for a patent? for ai technology " + ) + ``` -*Multiple agents process segments of a large document, and results are aggregated.* +-------------------------------------------------- -#### 2. Reducing Hallucination Through Cross-Verification +# File: swarms\examples\hierarchical_swarm_example.md -**Solution** +# Hierarchical Swarm Examples -Agents can verify each other's outputs by cross-referencing information and flagging inconsistencies. Implementing consensus mechanisms ensures that only accurate information is accepted. +This page provides simple, practical examples of how to use the `HierarchicalSwarm` for various real-world scenarios. -**Implementation in Enterprises** +## Basic Example: Financial Analysis -- **Data Validation:** In data entry automation, one agent inputs data while another validates it against source documents. -- **Decision Support Systems:** Multiple agents evaluate options and agree on recommendations, reducing the risk of incorrect advice. +```python +from swarms import Agent +from swarms.structs.hiearchical_swarm import HierarchicalSwarm + +# Create specialized financial analysis agents +market_research_agent = Agent( + agent_name="Market-Research-Specialist", + agent_description="Expert in market research, trend analysis, and competitive intelligence", + system_prompt="""You are a senior market research specialist with expertise in: + - Market trend analysis and forecasting + - Competitive landscape assessment + - Consumer behavior analysis + - Industry report generation + - Market opportunity identification + - Risk assessment and mitigation strategies""", + model_name="gpt-4o", +) +financial_analyst_agent = Agent( + agent_name="Financial-Analysis-Expert", + agent_description="Specialist in financial statement analysis, valuation, and investment research", + system_prompt="""You are a senior financial analyst with deep expertise in: + - Financial statement analysis (income statement, balance sheet, cash flow) + - Valuation methodologies (DCF, comparable company analysis, precedent transactions) + - Investment research and due diligence + - Financial modeling and forecasting + - Risk assessment and portfolio analysis + - ESG (Environmental, Social, Governance) analysis""", + model_name="gpt-4o", +) -```mermaid -graph TD - A[Agent's Output] - V1[Verifier Agent 1] - V2[Verifier Agent 2] - Consensus[Consensus Mechanism] - Output[Validated Output] - A --> V1 - A --> V2 - V1 & V2 --> Consensus - Consensus --> Output +# Initialize the hierarchical swarm +financial_analysis_swarm = HierarchicalSwarm( + name="Financial-Analysis-Hierarchical-Swarm", + description="A hierarchical swarm for comprehensive financial analysis with specialized agents", + agents=[market_research_agent, financial_analyst_agent], + max_loops=2, + verbose=True, +) + +# Execute financial analysis +task = "Conduct a comprehensive analysis of Tesla (TSLA) stock including market position, financial health, and investment potential" +result = financial_analysis_swarm.run(task=task) +print(result) ``` -*Agents verify outputs through cross-verification and consensus.* +## Development Team Example -#### 3. Enhancing Multi-Tasking Through Specialized Agents +```python +from swarms import Agent +from swarms.structs.hiearchical_swarm import HierarchicalSwarm + +# Create specialized development agents +frontend_developer_agent = Agent( + agent_name="Frontend-Developer", + agent_description="Senior frontend developer expert in modern web technologies and user experience", + system_prompt="""You are a senior frontend developer with expertise in: + - Modern JavaScript frameworks (React, Vue, Angular) + - TypeScript and modern ES6+ features + - CSS frameworks and responsive design + - State management (Redux, Zustand, Context API) + - Web performance optimization + - Accessibility (WCAG) and SEO best practices""", + model_name="gpt-4o", +) -**Solution** +backend_developer_agent = Agent( + agent_name="Backend-Developer", + agent_description="Senior backend developer specializing in server-side development and API design", + system_prompt="""You are a senior backend developer with expertise in: + - Server-side programming languages (Python, Node.js, Java, Go) + - Web frameworks (Django, Flask, Express, Spring Boot) + - Database design and optimization (SQL, NoSQL) + - API design and REST/GraphQL implementation + - Authentication and authorization systems + - Microservices architecture and containerization""", + model_name="gpt-4o", +) -Deploy specialized agents for different tasks and enable them to work concurrently. An orchestrator agent manages task allocation and workflow integration. +# Initialize the development swarm +development_department_swarm = HierarchicalSwarm( + name="Autonomous-Development-Department", + description="A fully autonomous development department with specialized agents", + agents=[frontend_developer_agent, backend_developer_agent], + max_loops=3, + verbose=True, +) -**Implementation in Enterprises** +# Execute development project +task = "Create a simple web app that allows users to upload a file and then download it. The app should be built with React and Node.js." +result = development_department_swarm.run(task=task) +print(result) +``` -- **Automated Workflows:** In supply chain management, one agent handles inventory analysis, another manages logistics, and a third forecasts demand. -- **IT Operations:** In IT automation, separate agents manage network monitoring, security scanning, and system updates. +## Single Step Execution +```python +from swarms import Agent +from swarms.structs.hiearchical_swarm import HierarchicalSwarm -```mermaid -graph LR - Task[Complex Task] - Orchestrator[Orchestrator Agent] - AgentA[Specialist Agent A] - AgentB[Specialist Agent B] - AgentC[Specialist Agent C] - Output[Integrated Solution] - Task --> Orchestrator - Orchestrator --> AgentA - Orchestrator --> AgentB - Orchestrator --> AgentC - AgentA & AgentB & AgentC --> Orchestrator - Orchestrator --> Output -``` +# Create analysis agents +market_agent = Agent( + agent_name="Market-Analyst", + agent_description="Expert in market analysis and trends", + model_name="gpt-4o", +) -*Specialized agents handle different tasks under the management of an orchestrator agent.* +technical_agent = Agent( + agent_name="Technical-Analyst", + agent_description="Specialist in technical analysis and patterns", + model_name="gpt-4o", +) -#### 4. Facilitating Collaboration Through Communication Protocols +# Initialize the swarm +swarm = HierarchicalSwarm( + name="Analysis-Swarm", + description="A hierarchical swarm for comprehensive analysis", + agents=[market_agent, technical_agent], + max_loops=1, + verbose=True, +) -**Solution** +# Execute a single step +task = "Analyze the current market trends for electric vehicles" +feedback = swarm.step(task=task) +print("Director Feedback:", feedback) +``` -Implement communication protocols that allow agents to share information, request assistance, and coordinate actions. This fosters a collaborative environment where agents complement each other's capabilities. +## Batch Processing -**Implementation in Enterprises** +```python +from swarms import Agent +from swarms.structs.hiearchical_swarm import HierarchicalSwarm -- **Customer Service:** Chatbots and virtual assistants share customer data to provide seamless support across channels. -- **Project Management:** Agents managing different aspects of a project (scheduling, resource allocation, risk assessment) coordinate to keep the project on track. +# Create analysis agents +market_agent = Agent( + agent_name="Market-Analyst", + agent_description="Expert in market analysis and trends", + model_name="gpt-4o", +) +technical_agent = Agent( + agent_name="Technical-Analyst", + agent_description="Specialist in technical analysis and patterns", + model_name="gpt-4o", +) -```mermaid -graph LR - Agent1[Agent 1] - Agent2[Agent 2] - Agent3[Agent 3] - Agent1 <--> Agent2 - Agent2 <--> Agent3 - Agent3 <--> Agent1 - Output[Collaborative Outcome] -``` +# Initialize the swarm +swarm = HierarchicalSwarm( + name="Analysis-Swarm", + description="A hierarchical swarm for comprehensive analysis", + agents=[market_agent, technical_agent], + max_loops=2, + verbose=True, +) -*Agents communicate and collaborate to achieve a common goal.* +# Execute multiple tasks +tasks = [ + "Analyze Apple (AAPL) stock performance", + "Evaluate Microsoft (MSFT) market position", + "Assess Google (GOOGL) competitive landscape" +] -#### 5. Improving Accuracy Through Ensemble Learning +results = swarm.batched_run(tasks=tasks) +for i, result in enumerate(results): + print(f"Task {i+1} Result:", result) +``` -**Solution** +## Research Team Example -Use ensemble methods where multiple agents provide predictions or analyses, and a meta-agent combines these to produce a more accurate result. +```python +from swarms import Agent +from swarms.structs.hiearchical_swarm import HierarchicalSwarm -**Implementation in Enterprises** +# Create specialized research agents +research_manager = Agent( + agent_name="Research-Manager", + agent_description="Manages research operations and coordinates research tasks", + system_prompt="You are a research manager responsible for overseeing research projects and coordinating research efforts.", + model_name="gpt-4o", +) -- **Risk Assessment:** Different agents assess risks from various perspectives (financial, operational, compliance), and their insights are combined. -- **Market Analysis:** Agents analyze market trends, customer behavior, and competitor actions, leading to a comprehensive market strategy. +data_analyst = Agent( + agent_name="Data-Analyst", + agent_description="Analyzes data and generates insights", + system_prompt="You are a data analyst specializing in processing and analyzing data to extract meaningful insights.", + model_name="gpt-4o", +) +research_assistant = Agent( + agent_name="Research-Assistant", + agent_description="Assists with research tasks and data collection", + system_prompt="You are a research assistant who helps gather information and support research activities.", + model_name="gpt-4o", +) -```mermaid -graph TD - AgentA[Agent A Output] - AgentB[Agent B Output] - AgentC[Agent C Output] - MetaAgent[Meta-Agent] - Output[Enhanced Accuracy] - AgentA --> MetaAgent - AgentB --> MetaAgent - AgentC --> MetaAgent - MetaAgent --> Output +# Initialize the research swarm +research_swarm = HierarchicalSwarm( + name="Research-Team-Swarm", + description="A hierarchical swarm for comprehensive research projects", + agents=[research_manager, data_analyst, research_assistant], + max_loops=2, + verbose=True, +) + +# Execute research project +task = "Conduct a comprehensive market analysis for a new AI-powered productivity tool" +result = research_swarm.run(task=task) +print(result) ``` -*Meta-agent combines outputs from multiple agents to improve accuracy.* +## Key Takeaways -#### 6. Increasing Processing Speed Through Parallelization +1. **Agent Specialization**: Create agents with specific, well-defined expertise areas +2. **Clear Task Descriptions**: Provide detailed, actionable task descriptions +3. **Appropriate Loop Count**: Set `max_loops` based on task complexity (1-3 for most tasks) +4. **Verbose Logging**: Enable verbose mode during development for debugging +5. **Context Preservation**: The swarm maintains full conversation history automatically -**Solution** +For more detailed information about the `HierarchicalSwarm` API and advanced usage patterns, see the [main documentation](hierarchical_swarm.md). -By distributing workloads among multiple agents operating in parallel, processing times are significantly reduced, enabling real-time responses. +-------------------------------------------------- -**Implementation in Enterprises** +# File: swarms\examples\igc_example.md -- **Data Processing:** Large datasets are partitioned and processed simultaneously by different agents. -- **Customer Requests:** Multiple customer inquiries are handled at once by separate agents, improving response times. +## Interactive Groupchat Examples +The Interactive GroupChat is a powerful multi-agent architecture that enables dynamic collaboration between multiple AI agents. This architecture allows agents to communicate with each other, respond to mentions using `@agent_name` syntax, and work together to solve complex tasks through structured conversation flows. -```mermaid -graph LR - Data[Large Dataset] - Agent1[Agent 1] - Agent2[Agent 2] - Agent3[Agent 3] - Output[Processed Data] - Data --> Agent1 - Data --> Agent2 - Data --> Agent3 - Agent1 & Agent2 & Agent3 --> Output -``` +### Architecture Description -*Parallel processing by agents leads to faster completion times.* +The Interactive GroupChat implements a **collaborative swarm architecture** where multiple specialized agents work together in a coordinated manner. Key features include: ---- +- **Mention-based Communication**: Agents can be directed to specific tasks using `@agent_name` syntax +- **Flexible Speaker Functions**: Multiple speaking order strategies (round robin, random, priority-based) +- **Enhanced Collaboration**: Agents build upon each other's responses and avoid redundancy +- **Interactive Sessions**: Support for both automated and interactive conversation modes +- **Context Awareness**: Agents maintain conversation history and context -### Part 3: Tailoring Multi-Agent Systems for Enterprise Automation at Scale +For comprehensive documentation on Interactive GroupChat, visit: [Interactive GroupChat Documentation](https://docs.swarms.world/en/latest/swarms/structs/interactive_groupchat/) -Implementing multi-agent systems in an enterprise context requires careful planning and consideration of organizational needs, technical infrastructure, and strategic goals. Below are key considerations and steps for enterprises aiming to adopt multi-agent collaboration for automation at scale. +### Step-by-Step Showcase -#### 1. Identifying Automation Opportunities +* **Agent Creation**: Define specialized agents with unique expertise and system prompts +* **GroupChat Initialization**: Create the InteractiveGroupChat structure with desired speaker function +* **Task Definition**: Formulate tasks using `@agent_name` mentions to direct specific agents +* **Execution**: Run the group chat to generate collaborative responses +* **Response Processing**: Handle the coordinated output from multiple agents +* **Iteration**: Chain multiple tasks for complex workflows -Enterprises should start by identifying processes and tasks that are suitable for automation through multi-agent systems. Prioritize areas where: +## Installation -- **Complexity Requires Specialization:** Tasks that involve multiple steps or require diverse expertise. -- **Scalability Is Essential:** Operations that need to handle increasing workloads efficiently. -- **Speed and Accuracy Are Critical:** Processes where delays or errors have significant impacts. +Install the swarms package using pip: -#### 2. Designing the Multi-Agent Architecture +```bash +pip install -U swarms +``` -Develop a robust architecture that defines how agents will interact, communicate, and collaborate. Key components include: +## Basic Setup -- **Agent Specialization:** Define the roles and responsibilities of each agent. -- **Communication Protocols:** Establish standards for information exchange. -- **Coordination Mechanisms:** Implement orchestrator agents or decentralized coordination strategies. -- **Integration with Existing Systems:** Ensure compatibility with current IT infrastructure. +1. First, set up your environment variables: -#### 3. Ensuring Data Security and Compliance +```python +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" +``` -Data security is paramount when agents handle sensitive enterprise information. Implement measures such as: +## Code -- **Encryption:** Secure communication channels between agents. -- **Access Control:** Define permissions for data access and agent capabilities. -- **Compliance Checks:** Ensure the system adheres to relevant regulations (e.g., GDPR, HIPAA). +```python +""" +InteractiveGroupChat Speaker Function Examples -#### 4. Monitoring and Performance Management +This example demonstrates how to use different speaker functions in the InteractiveGroupChat: +- Round Robin: Agents speak in a fixed order, cycling through the list +- Random: Agents speak in random order +- Priority: Agents speak based on priority weights +- Custom: User-defined speaker functions -Establish monitoring tools to track agent performance, system health, and outcomes. Key metrics may include: +The example also shows how agents can mention each other using @agent_name syntax. +""" -- **Processing Speed:** Measure how quickly tasks are completed. -- **Accuracy Rates:** Track the correctness of outputs. -- **Resource Utilization:** Monitor computational resources used by agents. -- **Error Logs:** Identify and address failures or exceptions. +from swarms import Agent +from swarms.structs.interactive_groupchat import ( + InteractiveGroupChat, + random_speaker, +) -#### 5. Scaling Strategies -Develop strategies for scaling the system as enterprise needs grow, including: +def create_example_agents(): + """Create example agents for demonstration.""" -- **Dynamic Resource Allocation:** Adjust computational resources based on workload. -- **Agent Addition or Removal:** Add new agents or deactivate others to meet changing demands. -- **Load Balancing:** Distribute tasks evenly to prevent bottlenecks. + # Create agents with different expertise + analyst = Agent( + agent_name="analyst", + system_prompt="You are a data analyst. You excel at analyzing data, creating charts, and providing insights.", + model_name="gpt-4.1", + streaming_on=True, + print_on=True, + ) -#### 6. Continuous Improvement + researcher = Agent( + agent_name="researcher", + system_prompt="You are a research specialist. You are great at gathering information, fact-checking, and providing detailed research.", + model_name="gpt-4.1", + streaming_on=True, + print_on=True, + ) -Implement feedback loops for ongoing enhancement of the multi-agent system: + writer = Agent( + agent_name="writer", + system_prompt="You are a content writer. You excel at writing clear, engaging content and summarizing information.", + model_name="gpt-4.1", + streaming_on=True, + print_on=True, + ) -- **User Feedback:** Gather input from users interacting with the system. -- **Performance Analytics:** Analyze data to identify areas for optimization. -- **Updating Agents:** Regularly update agent algorithms and knowledge bases. + return [analyst, researcher, writer] ---- -### Part 4: Case Studies and Real-World Applications +def example_random(): + agents = create_example_agents() -To illustrate the practical benefits of multi-agent collaboration in enterprise automation, let's explore several real-world examples. + # Create group chat with random speaker function + group_chat = InteractiveGroupChat( + name="Random Team", + description="A team that speaks in random order", + agents=agents, + speaker_function=random_speaker, + interactive=False, + ) -#### Case Study 1: Financial Services Automation + # Test the random behavior + task = "Let's create a marketing strategy. @analyst @researcher @writer please contribute." -**Challenge** + response = group_chat.run(task) + print(f"Response:\n{response}\n") -A financial institution needs to process large volumes of loan applications, requiring data verification, risk assessment, compliance checks, and decision-making. -**Solution** +if __name__ == "__main__": + # example_round_robin() + example_random() +``` -- **Specialized Agents:** - - **Data Extraction Agent:** Extracts data from application forms. - - **Verification Agent:** Confirms the accuracy of applicant information. - - **Risk Assessment Agent:** Evaluates credit risk using predictive models. - - **Compliance Agent:** Ensures all regulatory requirements are met. - - **Decision Agent:** Aggregates inputs and makes approval decisions. -- **Collaboration:** - - Agents communicate to share data and findings. - - The Decision Agent coordinates the workflow. -**Outcome** +## Connect With Us -- **Increased Processing Speed:** Applications are processed in minutes instead of days. -- **Improved Accuracy:** Cross-verification reduces errors. -- **Scalability:** System handles fluctuating application volumes efficiently. +Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights! -#### Case Study 2: Manufacturing Supply Chain Optimization +| Platform | Description | Link | +|----------|-------------|------| +| 📚 Documentation | Official documentation and guides | [docs.swarms.world](https://docs.swarms.world) | +| 📝 Blog | Latest updates and technical articles | [Medium](https://medium.com/@kyeg) | +| 💬 Discord | Live chat and community support | [Join Discord](https://discord.gg/jM3Z6M9uMq) | +| 🐦 Twitter | Latest news and announcements | [@kyegomez](https://twitter.com/kyegomez) | +| 👥 LinkedIn | Professional network and updates | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | +| 📺 YouTube | Tutorials and demos | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | +| 🎫 Events | Join our community events | [Sign up here](https://lu.ma/5p2jnc2v) | +| 🚀 Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) | -**Challenge** -A manufacturing company wants to optimize its supply chain to reduce costs and improve delivery times. +-------------------------------------------------- -**Solution** +# File: swarms\examples\interactive_groupchat_example.md -- **Specialized Agents:** - - **Demand Forecasting Agent:** Predicts product demand. - - **Inventory Management Agent:** Monitors stock levels and orders materials. - - **Logistics Agent:** Plans shipping routes and schedules. - - **Supplier Evaluation Agent:** Assesses supplier performance and reliability. - -- **Collaboration:** - - Agents share data on demand forecasts and inventory levels. - - Logistics Agent adjusts plans based on input from other agents. - -**Outcome** - -- **Cost Reduction:** Optimized inventory levels reduce holding costs. -- **Efficiency Gains:** Improved logistics planning enhances delivery times. -- **Adaptability:** System responds quickly to changes in demand or supply disruptions. +# Interactive GroupChat Example -#### Case Study 3: Healthcare Patient Management +This is an example of the InteractiveGroupChat module in swarms. [Click here for full documentation](https://docs.swarms.world/en/latest/swarms/structs/interactive_groupchat/) -**Challenge** +## Installation -A hospital aims to improve patient care coordination, managing appointments, medical records, billing, and treatment plans. +You can get started by first installing swarms with the following command, or [click here for more detailed installation instructions](https://docs.swarms.world/en/latest/swarms/install/install/): -**Solution** +```bash +pip3 install -U swarms +``` -- **Specialized Agents:** - - **Appointment Scheduling Agent:** Manages patient appointments. - - **Medical Records Agent:** Updates and retrieves patient records. - - **Billing Agent:** Handles invoicing and insurance claims. - - **Treatment Planning Agent:** Assists in developing patient care plans. +## Environment Variables -- **Collaboration:** - - Agents coordinate to ensure seamless patient experiences. - - Data is securely shared while maintaining patient confidentiality. +```txt +OPENAI_API_KEY="" +ANTHROPIC_API_KEY="" +GROQ_API_KEY="" +``` -**Outcome** +# Code -- **Enhanced Patient Care:** Improved coordination leads to better treatment outcomes. -- **Operational Efficiency:** Administrative tasks are streamlined. -- **Compliance:** System adheres to healthcare regulations (e.g., HIPAA). ---- +## Interactive Session in Terminal -### Part 5: Implementing Multi-Agent Systems – Best Practices for Enterprises +```python +from swarms import Agent +from swarms.structs.interactive_groupchat import InteractiveGroupChat -For enterprises embarking on the journey of multi-agent automation, adhering to best practices ensures successful implementation. -#### 1. Start Small and Scale Gradually +if __name__ == "__main__": + # Initialize agents + financial_advisor = Agent( + agent_name="FinancialAdvisor", + system_prompt="You are a financial advisor specializing in investment strategies and portfolio management.", + random_models_on=True, + output_type="final", + ) -- **Pilot Projects:** Begin with a specific process or department to test the multi-agent system. -- **Learn and Adapt:** Use insights from initial deployments to refine the system. + tax_expert = Agent( + agent_name="TaxExpert", + system_prompt="You are a tax expert who provides guidance on tax optimization and compliance.", + random_models_on=True, + output_type="final", + ) -#### 2. Invest in Training and Change Management + investment_analyst = Agent( + agent_name="InvestmentAnalyst", + system_prompt="You are an investment analyst focusing on market trends and investment opportunities.", + random_models_on=True, + output_type="final", + ) -- **Employee Education:** Train staff on interacting with and managing multi-agent systems. -- **Change Management:** Prepare the organization for changes in workflows and roles. + # Create a list of agents including both Agent instances and callables + agents = [ + financial_advisor, + tax_expert, + investment_analyst, + ] -#### 3. Leverage Cloud and Edge Computing + # Initialize another chat instance in interactive mode + interactive_chat = InteractiveGroupChat( + name="Interactive Financial Advisory Team", + description="An interactive team of financial experts providing comprehensive financial advice", + agents=agents, + max_loops=1, + output_type="all", + interactive=True, + ) -- **Scalable Infrastructure:** Utilize cloud services for flexible resource allocation. -- **Edge Computing:** Deploy agents closer to data sources for faster processing. + try: + # Start the interactive session + print("\nStarting interactive session...") + # interactive_chat.run("What is the best methodology to accumulate gold and silver commodities, and what is the best long-term strategy to accumulate them?") + interactive_chat.start_interactive_session() + except Exception as e: + print(f"An error occurred in interactive mode: {e}") +``` -#### 4. Foster Interoperability -- **Standards Compliance:** Use industry standards for data formats and communication protocols. -- **API Integration:** Ensure agents can integrate with existing enterprise applications. +## Run Method // Manual Method -#### 5. Prioritize Ethical Considerations -- **Transparency:** Maintain clear documentation of how agents make decisions. -- **Bias Mitigation:** Implement strategies to prevent and correct algorithmic biases. -- **Accountability:** Establish protocols for human oversight and intervention. +```python +from swarms import Agent +from swarms.structs.interactive_groupchat import InteractiveGroupChat ---- -### Conclusion +if __name__ == "__main__": + # Initialize agents + financial_advisor = Agent( + agent_name="FinancialAdvisor", + system_prompt="You are a financial advisor specializing in investment strategies and portfolio management.", + random_models_on=True, + output_type="final", + ) -Enterprises seeking to automate operations at scale face the limitations inherent in individual AI agents. Context window limits, hallucinations, single-task execution, lack of collaboration, lack of accuracy, and slow processing speed hinder the full potential of automation efforts. Multi-agent collaboration emerges as a robust solution to these challenges, offering a pathway to enhanced efficiency, accuracy, scalability, and adaptability. + tax_expert = Agent( + agent_name="TaxExpert", + system_prompt="You are a tax expert who provides guidance on tax optimization and compliance.", + random_models_on=True, + output_type="final", + ) -By adopting multi-agent systems, enterprises can: + investment_analyst = Agent( + agent_name="InvestmentAnalyst", + system_prompt="You are an investment analyst focusing on market trends and investment opportunities.", + random_models_on=True, + output_type="final", + ) -- **Extend Capabilities:** Overcome individual agent limitations through collective intelligence. -- **Improve Outcomes:** Achieve higher accuracy and faster processing by leveraging specialized agents. -- **Enhance Flexibility:** Adapt to changing business needs with scalable and versatile agent architectures. -- **Drive Innovation:** Foster a culture of continuous improvement and technological advancement. + # Create a list of agents including both Agent instances and callables + agents = [ + financial_advisor, + tax_expert, + investment_analyst, + ] -Implementing multi-agent systems requires thoughtful planning, adherence to best practices, and a commitment to ongoing management and optimization. Enterprises that successfully navigate this journey will position themselves at the forefront of automation, unlocking new levels of productivity and competitive advantage in an increasingly digital world. + # Initialize another chat instance in interactive mode + interactive_chat = InteractiveGroupChat( + name="Interactive Financial Advisory Team", + description="An interactive team of financial experts providing comprehensive financial advice", + agents=agents, + max_loops=1, + output_type="all", + interactive=False, + ) + try: + # Start the interactive session + print("\nStarting interactive session...") + # interactive_chat.run("What is the best methodology to accumulate gold and silver commodities, and what is the best long-term strategy to accumulate them?") + interactive_chat.run('@TaxExpert how can I understand tax tactics for crypto payroll in solana?') + except Exception as e: + print(f"An error occurred in interactive mode: {e}") +``` -------------------------------------------------- -# File: swarms/contributing.md +# File: swarms\examples\llama4.md -# Contribution Guidelines +# Llama4 Model Integration ---- +!!! info "Prerequisites" + - Python 3.8 or higher + - `swarms` library installed + - Access to Llama4 model + - Valid environment variables configured -## Table of Contents +## Quick Start -- [Project Overview](#project-overview) -- [Getting Started](#getting-started) - - [Installation](#installation) - - [Project Structure](#project-structure) -- [How to Contribute](#how-to-contribute) - - [Reporting Issues](#reporting-issues) - - [Submitting Pull Requests](#submitting-pull-requests) -- [Coding Standards](#coding-standards) - - [Type Annotations](#type-annotations) - - [Docstrings and Documentation](#docstrings-and-documentation) - - [Testing](#testing) - - [Code Style](#code-style) -- [Areas Needing Contributions](#areas-needing-contributions) - - [Writing Tests](#writing-tests) - - [Improving Documentation](#improving-documentation) - - [Creating Training Scripts](#creating-training-scripts) -- [Community and Support](#community-and-support) -- [License](#license) +Here's a simple example of integrating Llama4 model for crypto risk analysis: ---- +```python +from dotenv import load_dotenv +from swarms import Agent +from swarms.utils.vllm_wrapper import VLLM -## Project Overview +load_dotenv() +model = VLLM(model_name="meta-llama/Llama-4-Maverick-17B-128E") +``` -**swarms** is a library focused on making it simple to orchestrate agents to automate real-world activities. The goal is to automate the world economy with these swarms of agents. +## Available Models -We need your help to: +| Model Name | Description | Type | +|------------|-------------|------| +| meta-llama/Llama-4-Maverick-17B-128E | Base model with 128 experts | Base | +| meta-llama/Llama-4-Maverick-17B-128E-Instruct | Instruction-tuned version with 128 experts | Instruct | +| meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8 | FP8 quantized instruction model | Instruct (Optimized) | +| meta-llama/Llama-4-Scout-17B-16E | Base model with 16 experts | Base | +| meta-llama/Llama-4-Scout-17B-16E-Instruct | Instruction-tuned version with 16 experts | Instruct | -- **Write Tests**: Ensure the reliability and correctness of the codebase. -- **Improve Documentation**: Maintain clear and comprehensive documentation. -- **Add New Orchestration Methods**: Add multi-agent orchestration methods -- **Removing Defunct Code**: Removing bad code +!!! tip "Model Selection" + - Choose Instruct models for better performance on instruction-following tasks + - FP8 models offer better memory efficiency with minimal performance impact + - Scout models (16E) are lighter but still powerful + - Maverick models (128E) offer maximum performance but require more resources +## Detailed Implementation +### 1. Define Custom System Prompt -Your contributions will help us push the boundaries of AI and make this library a valuable resource for the community. +```python +CRYPTO_RISK_ANALYSIS_PROMPT = """ +You are a cryptocurrency risk analysis expert. Your role is to: ---- +1. Analyze market risks: + - Volatility assessment + - Market sentiment analysis + - Trading volume patterns + - Price trend evaluation -## Getting Started +2. Evaluate technical risks: + - Network security + - Protocol vulnerabilities + - Smart contract risks + - Technical scalability -### Installation +3. Consider regulatory risks: + - Current regulations + - Potential regulatory changes + - Compliance requirements + - Geographic restrictions -You can install swarms using `pip`: +4. Assess fundamental risks: + - Team background + - Project development status + - Competition analysis + - Use case viability -```bash -pip3 install swarms +Provide detailed, balanced analysis with both risks and potential mitigations. +Base your analysis on established crypto market principles and current market conditions. +""" ``` -Alternatively, you can clone the repository: +### 2. Initialize Agent -```bash -git clone https://github.com/kyegomez/swarms +```python +agent = Agent( + agent_name="Crypto-Risk-Analysis-Agent", + agent_description="Agent for analyzing risks in cryptocurrency investments", + system_prompt=CRYPTO_RISK_ANALYSIS_PROMPT, + max_loops=1, + llm=model, +) ``` -### Project Structure - -- **`swarms/`**: Contains all the source code for the library. -- **`examples/`**: Includes example scripts and notebooks demonstrating how to use the library. -- **`tests/`**: (To be created) Will contain unit tests for the library. -- **`docs/`**: (To be maintained) Contains documentation files. - ---- - -## How to Contribute - -### Reporting Issues +## Full Code -If you find any bugs, inconsistencies, or have suggestions for enhancements, please open an issue on GitHub: +```python +from dotenv import load_dotenv -1. **Search Existing Issues**: Before opening a new issue, check if it has already been reported. -2. **Open a New Issue**: If it hasn't been reported, create a new issue and provide detailed information. - - **Title**: A concise summary of the issue. - - **Description**: Detailed description, steps to reproduce, expected behavior, and any relevant logs or screenshots. -3. **Label Appropriately**: Use labels to categorize the issue (e.g., bug, enhancement, documentation). +from swarms import Agent +from swarms.utils.vllm_wrapper import VLLM -### Submitting Pull Requests +load_dotenv() -We welcome pull requests (PRs) for bug fixes, improvements, and new features. Please follow these guidelines: +# Define custom system prompt for crypto risk analysis +CRYPTO_RISK_ANALYSIS_PROMPT = """ +You are a cryptocurrency risk analysis expert. Your role is to: -1. **Fork the Repository**: Create a personal fork of the repository on GitHub. -2. **Clone Your Fork**: Clone your forked repository to your local machine. +1. Analyze market risks: + - Volatility assessment + - Market sentiment analysis + - Trading volume patterns + - Price trend evaluation - ```bash - git clone https://github.com/kyegomez/swarms.git - ``` +2. Evaluate technical risks: + - Network security + - Protocol vulnerabilities + - Smart contract risks + - Technical scalability -3. **Create a New Branch**: Use a descriptive branch name. +3. Consider regulatory risks: + - Current regulations + - Potential regulatory changes + - Compliance requirements + - Geographic restrictions - ```bash - git checkout -b feature/your-feature-name - ``` +4. Assess fundamental risks: + - Team background + - Project development status + - Competition analysis + - Use case viability -4. **Make Your Changes**: Implement your code, ensuring it adheres to the coding standards. -5. **Add Tests**: Write tests to cover your changes. -6. **Commit Your Changes**: Write clear and concise commit messages. +Provide detailed, balanced analysis with both risks and potential mitigations. +Base your analysis on established crypto market principles and current market conditions. +""" - ```bash - git commit -am "Add feature X" - ``` +model = VLLM(model_name="meta-llama/Llama-4-Maverick-17B-128E") -7. **Push to Your Fork**: +# Initialize the agent with custom prompt +agent = Agent( + agent_name="Crypto-Risk-Analysis-Agent", + agent_description="Agent for analyzing risks in cryptocurrency investments", + system_prompt=CRYPTO_RISK_ANALYSIS_PROMPT, + max_loops=1, + llm=model, +) - ```bash - git push origin feature/your-feature-name - ``` +print( + agent.run( + "Conduct a risk analysis of the top cryptocurrencies. Think for 2 loops internally" + ) +) +``` -8. **Create a Pull Request**: +!!! warning "Resource Usage" + The Llama4 model requires significant computational resources. Ensure your system meets the minimum requirements. - - Go to the original repository on GitHub. - - Click on "New Pull Request". - - Select your branch and create the PR. - - Provide a clear description of your changes and reference any related issues. +## FAQ -9. **Respond to Feedback**: Be prepared to make changes based on code reviews. +??? question "What is the purpose of max_loops parameter?" + The `max_loops` parameter determines how many times the agent will iterate through its thinking process. In this example, it's set to 1 for a single pass analysis. -**Note**: It's recommended to create small and focused PRs for easier review and faster integration. +??? question "Can I use a different model?" + Yes, you can replace the VLLM wrapper with other compatible models. Just ensure you update the model initialization accordingly. ---- +??? question "How do I customize the system prompt?" + You can modify the `CRYPTO_RISK_ANALYSIS_PROMPT` string to match your specific use case while maintaining the structured format. -## Coding Standards +!!! note "Best Practices" + - Always handle API errors gracefully + - Monitor model performance and resource usage + - Keep your prompts clear and specific + - Test thoroughly before production deployment -To maintain code quality and consistency, please adhere to the following standards. +!!! example "Sample Usage" + ```python + response = agent.run( + "Conduct a risk analysis of the top cryptocurrencies. Think for 2 loops internally" + ) + print(response) + ``` -### Type Annotations +-------------------------------------------------- -- **Mandatory**: All functions and methods must have type annotations. -- **Example**: +# File: swarms\examples\lumo.md - ```python - def add_numbers(a: int, b: int) -> int: - return a + b - ``` +# Lumo Example +Introducing Lumo-70B-Instruct - the largest and most advanced AI model ever created for the Solana ecosystem. Built on Meta's groundbreaking LLaMa 3.3 70B Instruct foundation, this revolutionary model represents a quantum leap in blockchain-specific artificial intelligence. With an unprecedented 70 billion parameters and trained on the most comprehensive Solana documentation dataset ever assembled, Lumo-70B-Instruct sets a new standard for developer assistance in the blockchain space. -- **Benefits**: - - Improves code readability. - - Helps with static type checking tools. -### Docstrings and Documentation +- [Docs](https://huggingface.co/lumolabs-ai/Lumo-70B-Instruct) -- **Docstrings**: Every public class, function, and method must have a docstring following the [Google Python Style Guide](http://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) or [NumPy Docstring Standard](https://numpydoc.readthedocs.io/en/latest/format.html). -- **Content**: - - **Description**: Briefly describe what the function or class does. - - **Args**: List and describe each parameter. - - **Returns**: Describe the return value(s). - - **Raises**: List any exceptions that are raised. +```python +from swarms import Agent +from transformers import LlamaForCausalLM, AutoTokenizer +import torch +from transformers import BitsAndBytesConfig -- **Example**: +class Lumo: + """ + A class for generating text using the Lumo model with 4-bit quantization. + """ + def __init__(self): + """ + Initializes the Lumo model with 4-bit quantization and a tokenizer. + """ + # Configure 4-bit quantization + bnb_config = BitsAndBytesConfig( + load_in_4bit=True, + bnb_4bit_quant_type="nf4", + bnb_4bit_compute_dtype=torch.float16, + llm_int8_enable_fp32_cpu_offload=True + ) - ```python - def calculate_mean(values: List[float]) -> float: - """ - Calculates the mean of a list of numbers. + self.model = LlamaForCausalLM.from_pretrained( + "lumolabs-ai/Lumo-70B-Instruct", + device_map="auto", + quantization_config=bnb_config, + use_cache=False, + attn_implementation="sdpa" + ) + self.tokenizer = AutoTokenizer.from_pretrained("lumolabs-ai/Lumo-70B-Instruct") - Args: - values (List[float]): A list of numerical values. + def run(self, task: str) -> str: + """ + Generates text based on the given prompt using the Lumo model. - Returns: - float: The mean of the input values. + Args: + prompt (str): The input prompt for the model. - Raises: - ValueError: If the input list is empty. - """ - if not values: - raise ValueError("The input list is empty.") - return sum(values) / len(values) - ``` + Returns: + str: The generated text. + """ + inputs = self.tokenizer(task, return_tensors="pt").to(self.model.device) + outputs = self.model.generate(**inputs, max_new_tokens=100) + return self.tokenizer.decode(outputs[0], skip_special_tokens=True) -- **Documentation**: Update or create documentation pages if your changes affect the public API. -### Testing -- **Required**: All new features and bug fixes must include appropriate unit tests. -- **Framework**: Use `unittest`, `pytest`, or a similar testing framework. -- **Test Location**: Place tests in the `tests/` directory, mirroring the structure of `swarms/`. -- **Test Coverage**: Aim for high test coverage to ensure code reliability. -- **Running Tests**: Provide instructions for running tests. - ```bash - pytest tests/ - ``` +Agent( + agent_name="Solana-Analysis-Agent", + llm=Lumo(), + max_loops="auto", + interactive=True, + streaming_on=True, +).run("How do i create a smart contract in solana?") -### Code Style +``` -- **PEP 8 Compliance**: Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines. -- **Linting Tools**: Use `flake8`, `black`, or `pylint` to check code style. -- **Consistency**: Maintain consistency with the existing codebase. +-------------------------------------------------- ---- +# File: swarms\examples\mixture_of_agents.md -## Areas Needing Contributions +# MixtureOfAgents Examples -We have several areas where contributions are particularly welcome. +The MixtureOfAgents architecture combines multiple specialized agents with an aggregator agent to process complex tasks. This architecture is particularly effective for tasks requiring diverse expertise and consensus-building among different specialists. -### Writing Tests +## Prerequisites -- **Goal**: Increase test coverage to ensure the library's robustness. -- **Tasks**: - - Write unit tests for existing code in `swarms/`. - - Identify edge cases and potential failure points. - - Ensure tests are repeatable and independent. +- Python 3.7+ +- OpenAI API key or other supported LLM provider keys +- Swarms library -### Improving Documentation +## Installation -- **Goal**: Maintain clear and comprehensive documentation for users and developers. -- **Tasks**: - - Update docstrings to reflect any changes. - - Add examples and tutorials in the `examples/` directory. - - Improve or expand the content in the `docs/` directory. +```bash +pip3 install -U swarms +``` -### Creating Multi-Agent Orchestration Methods +## Environment Variables -- **Goal**: Provide new multi-agent orchestration methods +```plaintext +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" +ANTHROPIC_API_KEY="" +GROQ_API_KEY="" +``` ---- +## Basic Usage -## Community and Support +### 1. Initialize Specialized Agents -- **Communication**: Engage with the community by participating in discussions on issues and pull requests. -- **Respect**: Maintain a respectful and inclusive environment. -- **Feedback**: Be open to receiving and providing constructive feedback. +```python +from swarms import Agent, MixtureOfAgents ---- +# Initialize specialized agents +legal_expert = Agent( + agent_name="Legal-Expert", + system_prompt="""You are a legal expert specializing in contract law. Your responsibilities include: + 1. Analyzing legal documents and contracts + 2. Identifying potential legal risks + 3. Ensuring regulatory compliance + 4. Providing legal recommendations + 5. Drafting and reviewing legal documents""", + model_name="gpt-4o", + max_loops=1, +) -## License +financial_expert = Agent( + agent_name="Financial-Expert", + system_prompt="""You are a financial expert specializing in business finance. Your tasks include: + 1. Analyzing financial implications + 2. Evaluating costs and benefits + 3. Assessing financial risks + 4. Providing financial projections + 5. Recommending financial strategies""", + model_name="gpt-4o", + max_loops=1, +) -By contributing to swarms, you agree that your contributions will be licensed under the [MIT License](LICENSE). +business_expert = Agent( + agent_name="Business-Expert", + system_prompt="""You are a business strategy expert. Your focus areas include: + 1. Analyzing business models + 2. Evaluating market opportunities + 3. Assessing competitive advantages + 4. Providing strategic recommendations + 5. Planning business development""", + model_name="gpt-4o", + max_loops=1, +) ---- +# Initialize aggregator agent +aggregator = Agent( + agent_name="Decision-Aggregator", + system_prompt="""You are a decision aggregator responsible for: + 1. Synthesizing input from multiple experts + 2. Resolving conflicting viewpoints + 3. Prioritizing recommendations + 4. Providing coherent final decisions + 5. Ensuring comprehensive coverage of all aspects""", + model_name="gpt-4o", + max_loops=1, +) +``` -Thank you for contributing to swarms! Your efforts help make this project better for everyone. +### 2. Create and Run MixtureOfAgents -If you have any questions or need assistance, please feel free to open an issue or reach out to the maintainers. +```python +# Create list of specialist agents +specialists = [legal_expert, financial_expert, business_expert] --------------------------------------------------- +# Initialize the mixture of agents +moa = MixtureOfAgents( + agents=specialists, + aggregator_agent=aggregator, + layers=3, +) -# File: swarms/ecosystem.md +# Run the analysis +result = moa.run( + "Analyze the proposed merger between Company A and Company B, considering legal, financial, and business aspects." +) +``` +## Advanced Usage -# Swarm Ecosystem +### 1. Custom Configuration with System Prompts -Welcome to the Swarm Ecosystem, a comprehensive suite of tools and frameworks designed to empower developers to orhestrate swarms of autonomous agents for a variety of applications. Dive into our ecosystem below: +```python +# Initialize MixtureOfAgents with custom aggregator prompt +moa = MixtureOfAgents( + agents=specialists, + aggregator_agent=aggregator, + aggregator_system_prompt="""As the decision aggregator, synthesize the analyses from all specialists into a coherent recommendation: + 1. Summarize key points from each specialist + 2. Identify areas of agreement and disagreement + 3. Weigh different perspectives + 4. Provide a balanced final recommendation + 5. Highlight key risks and opportunities""", + layers=3, +) -[Full Github Link](https://github.com/kyegomez/swarm-ecosystem) +result = moa.run("Evaluate the potential acquisition of StartupX") +``` -## Getting Started +### 2. Error Handling and Validation -| Project | Description | Link | -| ------- | ----------- | ---- | -| **Swarms Framework** | A Python-based framework that enables the creation, deployment, and scaling of reliable swarms of autonomous agents aimed at automating complex workflows. | [Swarms Framework](https://github.com/kyegomez/swarms) | -| **Swarms Cloud** | A cloud-based service offering Swarms-as-a-Service with guaranteed 100% uptime, cutting-edge performance, and enterprise-grade reliability for seamless scaling and management of swarms. | [Swarms Cloud](https://github.com/kyegomez/swarms-cloud) | -| **Swarms Core** | Provides backend utilities focusing on concurrency, multi-threading, and advanced execution strategies, developed in Rust for maximum efficiency and performance. | [Swarms Core](https://github.com/kyegomez/swarms-core) | -| **Swarm Foundation Models** | A dedicated repository for the creation, optimization, and training of groundbreaking swarming models. Features innovative models like PSO with transformers, ant colony optimizations, and more, aiming to surpass traditional architectures like Transformers and SSMs. Open for community contributions and ideas. | [Swarm Foundation Models](https://github.com/kyegomez/swarms-pytorch) | -| **Swarm Platform** | The Swarms dashboard Platform | [Swarm Platform](https://github.com/kyegomez/swarms-platform) | -| **Swarms JS** | Swarms Framework in JS. Orchestrate any agents and enable multi-agent collaboration between various agents! | [Swarm JS](https://github.com/kyegomez/swarms-js) | -| **Swarms Memory** | Easy to use, reliable, and bleeding-edge RAG systems.! | [Swarm JS](https://github.com/kyegomez/swarms-memory) | -| **Swarms Evals** | Evaluating Swarms! | [Swarm JS](https://github.com/kyegomez/swarms-evals) | -| **Swarms Zero** | RPC Enterprise-Grade Automation Framework | [Swarm Zero]([https://github.com/kyegomez/swarms-evals](https://github.com/kyegomez/Zero)) | +```python +try: + moa = MixtureOfAgents( + agents=specialists, + aggregator_agent=aggregator, + layers=3, + verbose=True, + ) + + result = moa.run("Complex analysis task") + + # Validate and process results + if result: + print("Analysis complete:") + print(result) + else: + print("Analysis failed to produce results") + +except Exception as e: + print(f"Error in analysis: {str(e)}") +``` ----- +## Best Practices -## 🫶 Contributions: +1. Agent Selection and Configuration: + - Choose specialists with complementary expertise + - Configure appropriate system prompts + - Set suitable model parameters -The easiest way to contribute is to pick any issue with the `good first issue` tag 💪. Read the Contributing guidelines [here](/CONTRIBUTING.md). Bug Report? [File here](https://github.com/swarms/gateway/issues) | Feature Request? [File here](https://github.com/swarms/gateway/issues) +2. Aggregator Configuration: + - Define clear aggregation criteria + - Set appropriate weights for different opinions + - Configure conflict resolution strategies -Swarms is an open-source project, and contributions are VERY welcome. If you want to contribute, you can create new features, fix bugs, or improve the infrastructure. Please refer to the [CONTRIBUTING.md](https://github.com/kyegomez/swarms/blob/master/CONTRIBUTING.md) and our [contributing board](https://github.com/users/kyegomez/projects/1) to participate in Roadmap discussions! +3. Layer Management: + - Set appropriate number of layers + - Monitor layer effectiveness + - Adjust based on task complexity - - - +4. Quality Control: + - Implement validation checks + - Monitor agent performance + - Ensure comprehensive coverage - - - +## Example Implementation - - - +Here's a complete example showing how to use MixtureOfAgents for a comprehensive business analysis: - - - +```python +import os +from swarms import Agent, MixtureOfAgents + +# Initialize specialist agents +market_analyst = Agent( + agent_name="Market-Analyst", + system_prompt="""You are a market analysis specialist focusing on: + 1. Market size and growth + 2. Competitive landscape + 3. Customer segments + 4. Market trends + 5. Entry barriers""", + model_name="gpt-4o", + max_loops=1, +) +financial_analyst = Agent( + agent_name="Financial-Analyst", + system_prompt="""You are a financial analysis expert specializing in: + 1. Financial performance + 2. Valuation metrics + 3. Cash flow analysis + 4. Investment requirements + 5. ROI projections""", + model_name="gpt-4o", + max_loops=1, +) +risk_analyst = Agent( + agent_name="Risk-Analyst", + system_prompt="""You are a risk assessment specialist focusing on: + 1. Market risks + 2. Operational risks + 3. Financial risks + 4. Regulatory risks + 5. Strategic risks""", + model_name="gpt-4o", + max_loops=1, +) +# Initialize aggregator +aggregator = Agent( + agent_name="Strategic-Aggregator", + system_prompt="""You are a strategic decision aggregator responsible for: + 1. Synthesizing specialist analyses + 2. Identifying key insights + 3. Evaluating trade-offs + 4. Making recommendations + 5. Providing action plans""", + model_name="gpt-4o", + max_loops=1, +) ----- +# Create and configure MixtureOfAgents +try: + moa = MixtureOfAgents( + agents=[market_analyst, financial_analyst, risk_analyst], + aggregator_agent=aggregator, + aggregator_system_prompt="""Synthesize the analyses from all specialists to provide: + 1. Comprehensive situation analysis + 2. Key opportunities and risks + 3. Strategic recommendations + 4. Implementation considerations + 5. Success metrics""", + layers=3, + verbose=True, + ) + + # Run the analysis + result = moa.run( + """Evaluate the business opportunity for expanding into the electric vehicle market: + 1. Market potential and competition + 2. Financial requirements and projections + 3. Risk assessment and mitigation strategies""" + ) + + # Process and display results + print("\nComprehensive Analysis Results:") + print("=" * 50) + print(result) + print("=" * 50) + +except Exception as e: + print(f"Error during analysis: {str(e)}") +``` -## Community +This comprehensive guide demonstrates how to effectively use the MixtureOfAgents architecture for complex analysis tasks requiring multiple expert perspectives and consensus-building. + +-------------------------------------------------- -Join our growing community around the world, for real-time support, ideas, and discussions on Swarms 😊 +# File: swarms\examples\moa_example.md -- View our official [Blog](https://docs.swarms.world) -- Chat live with us on [Discord](https://discord.gg/kS3rwKs3ZC) -- Follow us on [Twitter](https://twitter.com/kyegomez) -- Connect with us on [LinkedIn](https://www.linkedin.com/company/the-swarm-corporation) -- Visit us on [YouTube](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) -- [Join the Swarms community on Discord!](https://discord.gg/AJazBmhKnr) -- Join our Swarms Community Gathering every Thursday at 1pm NYC Time to unlock the potential of autonomous agents in automating your daily tasks [Sign up here](https://lu.ma/5p2jnc2v) +# Mixture of Agents Example ---- +The Mixture of Agents (MoA) is a sophisticated multi-agent architecture that implements parallel processing with iterative refinement. This approach processes multiple specialized agents simultaneously, concatenates their outputs, and then performs multiple parallel runs to achieve consensus or enhanced results. -## Discovery Call -Book a discovery call to learn how Swarms can lower your operating costs by 40% with swarms of autonomous agents in lightspeed. [Click here to book a time that works for you!](https://calendly.com/swarm-corp/30min?month=2023-11) +## How It Works +1. **Parallel Processing**: Multiple agents work simultaneously on the same input +2. **Output Concatenation**: Results from all agents are combined into a unified response +3. **Iterative Refinement**: The process repeats for `n` layers/iterations to improve quality +4. **Consensus Building**: Multiple runs help achieve more reliable and comprehensive outputs +This architecture is particularly effective for complex tasks that benefit from diverse perspectives and iterative improvement, such as financial analysis, risk assessment, and multi-faceted problem solving. -## Accelerate Backlog -Help us accelerate our backlog by supporting us financially! Note, we're an open source corporation and so all the revenue we generate is through donations at the moment ;) +![Mixture of Agents](https://files.readme.io/ddb138e-moa-3layer.png) - ---- +## Installation + +Install the swarms package using pip: + +```bash +pip install -U swarms +``` + +## Basic Setup + +1. First, set up your environment variables: + +```python +WORKSPACE_DIR="agent_workspace" +ANTHROPIC_API_KEY="" +``` + +## Code + +```python +from swarms import Agent, MixtureOfAgents + +# Agent 1: Risk Metrics Calculator +risk_metrics_agent = Agent( + agent_name="Risk-Metrics-Calculator", + agent_description="Calculates key risk metrics like VaR, Sharpe ratio, and volatility", + system_prompt="""You are a risk metrics specialist. Calculate and explain: + - Value at Risk (VaR) + - Sharpe ratio + - Volatility + - Maximum drawdown + - Beta coefficient + + Provide clear, numerical results with brief explanations.""", + max_loops=1, + # model_name="gpt-4o-mini", + random_model_enabled=True, + dynamic_temperature_enabled=True, + output_type="str-all-except-first", + max_tokens=4096, +) + +# Agent 2: Portfolio Risk Analyzer +portfolio_risk_agent = Agent( + agent_name="Portfolio-Risk-Analyzer", + agent_description="Analyzes portfolio diversification and concentration risk", + system_prompt="""You are a portfolio risk analyst. Focus on: + - Portfolio diversification analysis + - Concentration risk assessment + - Correlation analysis + - Sector/asset allocation risk + - Liquidity risk evaluation + + Provide actionable insights for risk reduction.""", + max_loops=1, + # model_name="gpt-4o-mini", + random_model_enabled=True, + dynamic_temperature_enabled=True, + output_type="str-all-except-first", + max_tokens=4096, +) + +# Agent 3: Market Risk Monitor +market_risk_agent = Agent( + agent_name="Market-Risk-Monitor", + agent_description="Monitors market conditions and identifies risk factors", + system_prompt="""You are a market risk monitor. Identify and assess: + - Market volatility trends + - Economic risk factors + - Geopolitical risks + - Interest rate risks + - Currency risks + + Provide current risk alerts and trends.""", + max_loops=1, + # model_name="gpt-4o-mini", + random_model_enabled=True, + dynamic_temperature_enabled=True, + output_type="str-all-except-first", + max_tokens=4096, +) + + +swarm = MixtureOfAgents( + agents=[ + risk_metrics_agent, + portfolio_risk_agent, + market_risk_agent, + ], + layers=1, + max_loops=1, + output_type="final", +) + + +out = swarm.run( + "Calculate VaR and Sharpe ratio for a portfolio with 15% annual return and 20% volatility" +) + +print(out) +``` + +## Support and Community + +If you're facing issues or want to learn more, check out the following resources to join our Discord, stay updated on Twitter, and watch tutorials on YouTube! + +| Platform | Link | Description | +|----------|------|-------------| +| 📚 Documentation | [docs.swarms.world](https://docs.swarms.world) | Official documentation and guides | +| 📝 Blog | [Medium](https://medium.com/@kyeg) | Latest updates and technical articles | +| 💬 Discord | [Join Discord](https://discord.gg/jM3Z6M9uMq) | Live chat and community support | +| 🐦 Twitter | [@kyegomez](https://twitter.com/kyegomez) | Latest news and announcements | +| 👥 LinkedIn | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | Professional network and updates | +| 📺 YouTube | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | Tutorials and demos | +| 🎫 Events | [Sign up here](https://lu.ma/5p2jnc2v) | Join our community events | + -------------------------------------------------- -# File: swarms/examples/claude.md +# File: swarms\examples\model_providers.md -# Agent with Anthropic/Claude +# Model Providers Overview -- Get their api keys and put it in the `.env` +Swarms supports a vast array of model providers, giving you the flexibility to choose the best model for your specific use case. Whether you need high-performance inference, cost-effective solutions, or specialized capabilities, Swarms has you covered. -- Select your model_name like `claude-3-sonnet-20240229` follows LiteLLM conventions +## Supported Model Providers + +| Provider | Description | Documentation | +|----------|-------------|---------------| +| **OpenAI** | Industry-leading language models including GPT-4, GPT-4o, and GPT-4o-mini. Perfect for general-purpose tasks, creative writing, and complex reasoning. | [OpenAI Integration](openai_example.md) | +| **Anthropic/Claude** | Advanced AI models known for their safety, helpfulness, and reasoning capabilities. Claude models excel at analysis, coding, and creative tasks. | [Claude Integration](claude.md) | +| **Groq** | Ultra-fast inference platform offering real-time AI responses. Ideal for applications requiring low latency and high throughput. | [Groq Integration](groq.md) | +| **Cohere** | Enterprise-grade language models with strong performance on business applications, text generation, and semantic search. | [Cohere Integration](cohere.md) | +| **DeepSeek** | Advanced reasoning models including the DeepSeek Reasoner (R1). Excellent for complex problem-solving and analytical tasks. | [DeepSeek Integration](deepseek.md) | +| **Ollama** | Local model deployment platform allowing you to run open-source models on your own infrastructure. No API keys required. | [Ollama Integration](ollama.md) | +| **OpenRouter** | Unified API gateway providing access to hundreds of models from various providers through a single interface. | [OpenRouter Integration](openrouter.md) | +| **XAI** | xAI's Grok models offering unique capabilities for research, analysis, and creative tasks with advanced reasoning abilities. | [XAI Integration](xai.md) | +| **vLLM** | High-performance inference library for serving large language models with optimized memory usage and throughput. | [vLLM Integration](vllm_integration.md) | +| **Llama4** | Meta's latest open-source language models including Llama-4-Maverick and Llama-4-Scout variants with expert routing capabilities. | [Llama4 Integration](llama4.md) | +| **Azure OpenAI** | Enterprise-grade OpenAI models through Microsoft's cloud infrastructure with enhanced security, compliance, and enterprise features. | [Azure Integration](azure.md) | + +## Quick Start +All model providers follow a consistent pattern in Swarms. Here's the basic template: ```python from swarms import Agent @@ -16986,59 +19654,283 @@ from dotenv import load_dotenv load_dotenv() -# Initialize the agent with ChromaDB memory +# Initialize agent with your chosen model agent = Agent( - agent_name="Financial-Analysis-Agent", + agent_name="Your-Agent-Name", + model_name="gpt-4o-mini", # Varies by provider + system_prompt="Your system prompt here", + agent_description="Description of what your agent does.", +) + +# Run your agent +response = agent.run("Your query here") +``` + +## Model Selection Guide + +### For High-Performance Applications + +- **OpenAI GPT-4o**: Best overall performance and reasoning + +- **Anthropic Claude**: Excellent safety and analysis capabilities + +- **DeepSeek R1**: Advanced reasoning and problem-solving + +### For Cost-Effective Solutions + +- **OpenAI GPT-4o-mini**: Great performance at lower cost + +- **Ollama**: Free local deployment + +- **OpenRouter**: Access to cost-effective models + +### For Real-Time Applications + +- **Groq**: Ultra-fast inference + +- **vLLM**: Optimized for high throughput + +### For Specialized Tasks + +- **Llama4**: Expert routing for complex workflows + +- **XAI Grok**: Advanced research capabilities + +- **Cohere**: Strong business applications + +## Environment Setup + +Most providers require API keys. Add them to your `.env` file: + +```bash +# OpenAI +OPENAI_API_KEY=your_openai_key + +# Anthropic +ANTHROPIC_API_KEY=your_anthropic_key + +# Groq +GROQ_API_KEY=your_groq_key + +# Cohere +COHERE_API_KEY=your_cohere_key + +# DeepSeek +DEEPSEEK_API_KEY=your_deepseek_key + +# OpenRouter +OPENROUTER_API_KEY=your_openrouter_key + +# XAI +XAI_API_KEY=your_xai_key + +# Azure OpenAI +AZURE_API_KEY=your_azure_openai_api_key +AZURE_API_BASE=https://your-resource-name.openai.azure.com/ +AZURE_API_VERSION=2024-02-15-preview +``` + +!!! note "No API Key Required" + Ollama and vLLM can be run locally without API keys, making them perfect for development and testing. + +## Advanced Features + +### Multi-Model Workflows + +Swarms allows you to create workflows that use different models for different tasks: + +```python +from swarms import Agent, ConcurrentWorkflow + +# Research agent using Claude for analysis +research_agent = Agent( + agent_name="Research-Agent", model_name="claude-3-sonnet-20240229", - system_prompt="Agent system prompt here", - agent_description="Agent performs financial analysis.", + system_prompt="You are a research expert." ) -# Run a query -agent.run("What are the components of a startup's stock incentive equity plan?") +# Creative agent using GPT-4o for content generation +creative_agent = Agent( + agent_name="Creative-Agent", + model_name="gpt-4o", + system_prompt="You are a creative content expert." +) + +# Workflow combining both agents +workflow = ConcurrentWorkflow( + name="Research-Creative-Workflow", + agents=[research_agent, creative_agent] +) ``` --------------------------------------------------- +### Model Routing -# File: swarms/examples/cohere.md +Automatically route tasks to the most appropriate model: -# Agent with Cohere +```python +from swarms import Agent, ModelRouter -- Add your `COHERE_API_KEY` in the `.env` file +# Define model preferences for different task types +model_router = ModelRouter( + models={ + "analysis": "claude-3-sonnet-20240229", + "creative": "gpt-4o", + "fast": "gpt-4o-mini", + "local": "ollama/llama2" + } +) -- Select your model_name like `command-r` follows LiteLLM conventions +# Agent will automatically choose the best model +agent = Agent( + agent_name="Smart-Agent", + llm=model_router, + system_prompt="You are a versatile assistant." +) +``` + +## Getting Help + +- **Documentation**: Each provider has detailed documentation with examples + +- **Community**: Join the Swarms community for support and best practices + +- **Issues**: Report bugs and request features on GitHub + +- **Discussions**: Share your use cases and learn from others + +!!! success "Ready to Get Started?" + Choose a model provider from the table above and follow the detailed integration guide. Each provider offers unique capabilities that can enhance your Swarms applications. +-------------------------------------------------- + +# File: swarms\examples\multi_agent_router_minimal.md + +# MultiAgentRouter Minimal Example + +This example shows how to route a task to the most suitable agent using `SwarmRouter` with `swarm_type="MultiAgentRouter"`. + ```python from swarms import Agent -import os -from dotenv import load_dotenv +from swarms.structs.swarm_router import SwarmRouter -load_dotenv() +agents = [ + Agent( + agent_name="Researcher", + system_prompt="Answer questions briefly.", + model_name="gpt-4o-mini", + ), + Agent( + agent_name="Coder", + system_prompt="Write small Python functions.", + model_name="gpt-4o-mini", + ), +] -# Initialize the agent with ChromaDB memory -agent = Agent( - agent_name="Financial-Analysis-Agent", - model_name="command-r", - system_prompt="Agent system prompt here", - agent_description="Agent performs financial analysis.", +router = SwarmRouter( + name="multi-agent-router-demo", + description="Routes tasks to the most suitable agent", + agents=agents, + swarm_type="MultiAgentRouter" ) -# Run a query -agent.run("What are the components of a startup's stock incentive equity plan?") +result = router.run("Write a function that adds two numbers") +print(result) ``` +View the source on [GitHub](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/mar/multi_agent_router_minimal.py). + -------------------------------------------------- -# File: swarms/examples/deepseek.md +# File: swarms\examples\multiple_images.md -# Agent with DeepSeek +# Processing Multiple Images -- Add your `DEEPSEEK_API_KEY` in the `.env` file +This tutorial shows how to process multiple images with a single agent using Swarms' multi-modal capabilities. You'll learn to configure an agent for batch image analysis, enabling efficient processing for quality control, object detection, or image comparison tasks. -- Select your model_name like `deepseek/deepseek-chat` follows [LiteLLM conventions](https://docs.litellm.ai/docs/providers/deepseek) -- Execute your agent! +## Installation + +Install the swarms package using pip: + +```bash +pip install -U swarms +``` + +## Basic Setup + +1. First, set up your environment variables: + +```python +WORKSPACE_DIR="agent_workspace" +ANTHROPIC_API_KEY="" +``` + + +## Code + +- Create a list of images by their file paths + +- Pass it into the `Agent.run(imgs=[str])` parameter + +- Activate `summarize_multiple_images=True` if you want the agent to output a summary of the image analyses + + +```python +from swarms import Agent +from swarms.prompts.logistics import ( + Quality_Control_Agent_Prompt, +) + + +# Image for analysis +factory_image = "image.jpg" + +# Quality control agent +quality_control_agent = Agent( + agent_name="Quality Control Agent", + agent_description="A quality control agent that analyzes images and provides a detailed report on the quality of the product in the image.", + model_name="claude-3-5-sonnet-20240620", + system_prompt=Quality_Control_Agent_Prompt, + multi_modal=True, + max_loops=1, + output_type="str-all-except-first", + summarize_multiple_images=True, +) + + +response = quality_control_agent.run( + task="what is in the image?", + imgs=[factory_image, factory_image], +) + +print(response) +``` + +## Support and Community + +If you're facing issues or want to learn more, check out the following resources to join our Discord, stay updated on Twitter, and watch tutorials on YouTube! + +| Platform | Link | Description | +|----------|------|-------------| +| 📚 Documentation | [docs.swarms.world](https://docs.swarms.world) | Official documentation and guides | +| 📝 Blog | [Medium](https://medium.com/@kyeg) | Latest updates and technical articles | +| 💬 Discord | [Join Discord](https://discord.gg/jM3Z6M9uMq) | Live chat and community support | +| 🐦 Twitter | [@kyegomez](https://twitter.com/kyegomez) | Latest news and announcements | +| 👥 LinkedIn | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | Professional network and updates | +| 📺 YouTube | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | Tutorials and demos | +| 🎫 Events | [Sign up here](https://lu.ma/5p2jnc2v) | Join our community events | + + + +-------------------------------------------------- + +# File: swarms\examples\ollama.md + +# Agent with Ollama + +- No API key needed +- Select your model_name like `ollama/llama2` follows [LiteLLM conventions](https://docs.litellm.ai/docs/providers/ollama) ```python @@ -17051,7 +19943,7 @@ load_dotenv() # Initialize the agent with ChromaDB memory agent = Agent( agent_name="Financial-Analysis-Agent", - model_name="deepseek/deepseek-chat", + model_name="ollama/llama2", system_prompt="Agent system prompt here", agent_description="Agent performs financial analysis.", ) @@ -17060,14 +19952,43 @@ agent = Agent( agent.run("What are the components of a startup's stock incentive equity plan?") ``` -## R1 +-------------------------------------------------- -This is a simple example of how to use the DeepSeek Reasoner model otherwise known as R1. +# File: swarms\examples\openai_example.md + +# Agent with GPT-4o-Mini + +- Add `OPENAI_API_KEY="your_key"` to your `.env` file +- Select your model like `gpt-4o-mini` or `gpt-4o` ```python +from swarms import Agent -import os +Agent( + agent_name="Stock-Analysis-Agent", + model_name="gpt-4o-mini", + max_loops="auto", + interactive=True, + streaming_on=True, +).run("What are 5 hft algorithms") +``` + +-------------------------------------------------- + +# File: swarms\examples\openrouter.md + +# Agent with OpenRouter + +- Add your `OPENROUTER_API_KEY` in the `.env` file + +- Select your model_name like `openrouter/google/palm-2-chat-bison` follows [LiteLLM conventions](https://docs.litellm.ai/docs/providers/openrouter) + +- Execute your agent! + + +```python from swarms import Agent +import os from dotenv import load_dotenv load_dotenv() @@ -17075,7 +19996,7 @@ load_dotenv() # Initialize the agent with ChromaDB memory agent = Agent( agent_name="Financial-Analysis-Agent", - model_name="deepseek/deepseek-reasoner", + model_name="openrouter/google/palm-2-chat-bison", system_prompt="Agent system prompt here", agent_description="Agent performs financial analysis.", ) @@ -17086,71 +20007,162 @@ agent.run("What are the components of a startup's stock incentive equity plan?") -------------------------------------------------- -# File: swarms/examples/groq.md +# File: swarms\examples\quant_crypto_agent.md -# Agent with Groq +# Quant Crypto Agent -- Add your `GROQ_API_KEY` +- This is a simple example of a crypto agent that uses the `Agent` class from the `swarms` library. +- It uses the `fetch_htx_data` and `coin_gecko_coin_api` tools to fetch data from the `htx` and `CoinGecko` APIs. +- It uses the `Agent` class to create an agent that can analyze the current state of a crypto asset. -- Initiate your agent +## Steps -- Run your agent +1. Install the `swarms` library. +2. Install the `swarms_tools` library. +3. Setup your `.env` file with the `OPENAI_API_KEY` environment variables. +4. Run the code. -```python -import os +## Installation: -from swarm_models import OpenAIChat +```bash +pip install swarms swarms-tools python-dotenv +``` + +## Code: +```python from swarms import Agent +from dotenv import load_dotenv +from swarms_tools import fetch_htx_data, coin_gecko_coin_api -company = "NVDA" +load_dotenv() + +CRYPTO_ANALYST_SYSTEM_PROMPT = """ +You are an expert cryptocurrency financial analyst with deep expertise in: +1. Technical Analysis + - Chart patterns and indicators (RSI, MACD, Bollinger Bands) + - Volume analysis and market momentum + - Support and resistance levels + - Trend analysis and price action +2. Fundamental Analysis + - Tokenomics evaluation + - Network metrics (TVL, daily active users, transaction volume) + - Protocol revenue and growth metrics + - Market capitalization analysis + - Token utility and use cases -# Initialize the Managing Director agent -managing_director = Agent( - agent_name="Managing-Director", - system_prompt=f""" - As the Managing Director at Blackstone, your role is to oversee the entire investment analysis process for potential acquisitions. - Your responsibilities include: - 1. Setting the overall strategy and direction for the analysis - 2. Coordinating the efforts of the various team members and ensuring a comprehensive evaluation - 3. Reviewing the findings and recommendations from each team member - 4. Making the final decision on whether to proceed with the acquisition +3. Market Analysis + - Market sentiment analysis + - Correlation with broader crypto market + - Impact of macro events + - Institutional adoption metrics + - DeFi and NFT market analysis + +4. Risk Assessment + - Volatility metrics + - Liquidity analysis + - Smart contract risks + - Regulatory considerations + - Exchange exposure risks + +5. Data Analysis Methods + - On-chain metrics analysis + - Whale wallet tracking + - Exchange inflow/outflow + - Mining/Staking statistics + - Network health indicators + +When analyzing crypto assets, always: +1. Start with a comprehensive market overview +2. Examine both on-chain and off-chain metrics +3. Consider multiple timeframes (short, medium, long-term) +4. Evaluate risk-reward ratios +5. Assess market sentiment and momentum +6. Consider regulatory and security factors +7. Analyze correlations with BTC, ETH, and traditional markets +8. Examine liquidity and volume profiles +9. Review recent protocol developments and updates +10. Consider macro economic factors + +Format your analysis with: +- Clear section headings +- Relevant metrics and data points +- Risk warnings and disclaimers +- Price action analysis +- Market sentiment summary +- Technical indicators +- Fundamental factors +- Clear recommendations with rationale + +Remember to: +- Always provide data-driven insights +- Include both bullish and bearish scenarios +- Highlight key risk factors +- Consider market cycles and seasonality +- Maintain objectivity in analysis +- Cite sources for data and claims +- Update analysis based on new market conditions +""" + +# Initialize the crypto analysis agent +agent = Agent( + agent_name="Crypto-Analysis-Expert", + agent_description="Expert cryptocurrency financial analyst and market researcher", + system_prompt=CRYPTO_ANALYST_SYSTEM_PROMPT, + max_loops="auto", + model_name="gpt-4o", + dynamic_temperature_enabled=True, + user_name="crypto_analyst", + output_type="str", + interactive=True, +) + +print(fetch_htx_data("sol")) +print(coin_gecko_coin_api("solana")) + +# Example usage +agent.run( + f""" + Analyze the current state of Solana (SOL), including: + 1. Technical analysis of price action + 2. On-chain metrics and network health + 3. Recent protocol developments + 4. Market sentiment + 5. Risk factors + Please provide a comprehensive analysis with data-driven insights. - For the current potential acquisition of {company}, direct the tasks for the team to thoroughly analyze all aspects of the company, including its financials, industry position, technology, market potential, and regulatory compliance. Provide guidance and feedback as needed to ensure a rigorous and unbiased assessment. - """, - model_name="groq/deepseek-r1-distill-qwen-32b", - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="managing-director.json", + # Solana CoinGecko Data + Real-tim data from Solana CoinGecko: \n {coin_gecko_coin_api("solana")} + + """ ) ``` -------------------------------------------------- -# File: swarms/examples/groupchat_example.md +# File: swarms\examples\sequential_example.md -# GroupChat Example +# Sequential Workflow Example !!! abstract "Overview" - Learn how to create and configure a group chat with multiple AI agents using the Swarms framework. This example demonstrates how to set up agents for expense analysis and budget advising. + Learn how to create a sequential workflow with multiple specialized AI agents using the Swarms framework. This example demonstrates how to set up a legal practice workflow with different types of legal agents working in sequence. ## Prerequisites !!! info "Before You Begin" Make sure you have: + - Python 3.7+ installed + - A valid API key for your model provider + - The Swarms package installed ## Installation ```bash -pip install swarms +pip3 install -U swarms ``` ## Environment Setup @@ -17166,80 +20178,60 @@ pip install swarms ### Import Required Modules ```python -from dotenv import load_dotenv -import os -from swarms import Agent, GroupChat +from swarms import Agent, SequentialWorkflow ``` ### Configure Agents -!!! example "Agent Configuration" - Here's how to set up your agents with specific roles: +!!! example "Legal Agent Configuration" + Here's how to set up your specialized legal agents: ```python - # Expense Analysis Agent - agent1 = Agent( - agent_name="Expense-Analysis-Agent", - description="You are an accounting agent specializing in analyzing potential expenses.", + # Litigation Agent + litigation_agent = Agent( + agent_name="Alex Johnson", + system_prompt="As a Litigator, you specialize in navigating the complexities of lawsuits. Your role involves analyzing intricate facts, constructing compelling arguments, and devising effective case strategies to achieve favorable outcomes for your clients.", model_name="gpt-4o-mini", max_loops=1, - autosave=False, - dashboard=False, - verbose=True, - dynamic_temperature_enabled=True, - user_name="swarms_corp", - retry_attempts=1, - context_length=200000, - output_type="string", - streaming_on=False, - max_tokens=15000, ) - # Budget Adviser Agent - agent2 = Agent( - agent_name="Budget-Adviser-Agent", - description="You are a budget adviser who provides insights on managing and optimizing expenses.", + # Corporate Attorney Agent + corporate_agent = Agent( + agent_name="Emily Carter", + system_prompt="As a Corporate Attorney, you provide expert legal advice on business law matters. You guide clients on corporate structure, governance, compliance, and transactions, ensuring their business operations align with legal requirements.", + model_name="gpt-4o-mini", + max_loops=1, + ) + + # IP Attorney Agent + ip_agent = Agent( + agent_name="Michael Smith", + system_prompt="As an IP Attorney, your expertise lies in protecting intellectual property rights. You handle various aspects of IP law, including patents, trademarks, copyrights, and trade secrets, helping clients safeguard their innovations.", model_name="gpt-4o-mini", max_loops=1, - autosave=False, - dashboard=False, - verbose=True, - dynamic_temperature_enabled=True, - user_name="swarms_corp", - retry_attempts=1, - context_length=200000, - output_type="string", - streaming_on=False, - max_tokens=15000, ) ``` -### Initialize GroupChat +### Initialize Sequential Workflow -!!! example "GroupChat Setup" - Configure the GroupChat with your agents: +!!! example "Workflow Setup" + Configure the SequentialWorkflow with your agents: ```python - agents = [agent1, agent2] - - chat = GroupChat( - name="Expense Advisory", - description="Accounting group focused on discussing potential expenses", - agents=agents, - max_loops=1, - output_type="all", + swarm = SequentialWorkflow( + agents=[litigation_agent, corporate_agent, ip_agent], + name="litigation-practice", + description="Handle all aspects of litigation with a focus on thorough legal analysis and effective case management.", ) ``` -### Run the Chat +### Run the Workflow -!!! example "Execute the Chat" - Start the conversation between agents: +!!! example "Execute the Workflow" + Start the sequential workflow: ```python - history = chat.run( - "What potential expenses should we consider for the upcoming quarter? Please collaborate to outline a comprehensive list." - ) + swarm.run("Create a report on how to patent an all-new AI invention and what platforms to use and more.") ``` ## Complete Example @@ -17248,994 +20240,362 @@ from swarms import Agent, GroupChat Here's the complete code combined: ```python - from dotenv import load_dotenv - import os - from swarms import Agent, GroupChat + from swarms import Agent, SequentialWorkflow - if __name__ == "__main__": - # Load environment variables - load_dotenv() - api_key = os.getenv("OPENAI_API_KEY") + # Core Legal Agent Definitions with enhanced system prompts + litigation_agent = Agent( + agent_name="Alex Johnson", + system_prompt="As a Litigator, you specialize in navigating the complexities of lawsuits. Your role involves analyzing intricate facts, constructing compelling arguments, and devising effective case strategies to achieve favorable outcomes for your clients.", + model_name="gpt-4o-mini", + max_loops=1, + ) - # Configure agents - agent1 = Agent( - agent_name="Expense-Analysis-Agent", - description="You are an accounting agent specializing in analyzing potential expenses.", - model_name="gpt-4o-mini", - max_loops=1, - autosave=False, - dashboard=False, - verbose=True, - dynamic_temperature_enabled=True, - user_name="swarms_corp", - retry_attempts=1, - context_length=200000, - output_type="string", - streaming_on=False, - max_tokens=15000, - ) + corporate_agent = Agent( + agent_name="Emily Carter", + system_prompt="As a Corporate Attorney, you provide expert legal advice on business law matters. You guide clients on corporate structure, governance, compliance, and transactions, ensuring their business operations align with legal requirements.", + model_name="gpt-4o-mini", + max_loops=1, + ) - agent2 = Agent( - agent_name="Budget-Adviser-Agent", - description="You are a budget adviser who provides insights on managing and optimizing expenses.", - model_name="gpt-4o-mini", - max_loops=1, - autosave=False, - dashboard=False, - verbose=True, - dynamic_temperature_enabled=True, - user_name="swarms_corp", - retry_attempts=1, - context_length=200000, - output_type="string", - streaming_on=False, - max_tokens=15000, - ) + ip_agent = Agent( + agent_name="Michael Smith", + system_prompt="As an IP Attorney, your expertise lies in protecting intellectual property rights. You handle various aspects of IP law, including patents, trademarks, copyrights, and trade secrets, helping clients safeguard their innovations.", + model_name="gpt-4o-mini", + max_loops=1, + ) - # Initialize GroupChat - agents = [agent1, agent2] - chat = GroupChat( - name="Expense Advisory", - description="Accounting group focused on discussing potential expenses", - agents=agents, - max_loops=1, - output_type="all", - ) + # Initialize and run the workflow + swarm = SequentialWorkflow( + agents=[litigation_agent, corporate_agent, ip_agent], + name="litigation-practice", + description="Handle all aspects of litigation with a focus on thorough legal analysis and effective case management.", + ) - # Run the chat - history = chat.run( - "What potential expenses should we consider for the upcoming quarter? Please collaborate to outline a comprehensive list." - ) + swarm.run("Create a report on how to patent an all-new AI invention and what platforms to use and more.") ``` +## Agent Roles + +!!! info "Specialized Legal Agents" + | Agent | Role | Expertise | + |-------|------|-----------| + | Alex Johnson | Litigator | Lawsuit navigation, case strategy | + | Emily Carter | Corporate Attorney | Business law, compliance | + | Michael Smith | IP Attorney | Patents, trademarks, copyrights | + ## Configuration Options !!! info "Key Parameters" | Parameter | Description | Default | |-----------|-------------|---------| - | `max_loops` | Maximum number of conversation loops | 1 | - | `autosave` | Enable automatic saving of chat history | False | - | `dashboard` | Enable dashboard visualization | False | - | `verbose` | Enable detailed logging | True | - | `dynamic_temperature_enabled` | Enable dynamic temperature adjustment | True | - | `retry_attempts` | Number of retry attempts for failed operations | 1 | - | `context_length` | Maximum context length for the model | 200000 | - | `max_tokens` | Maximum tokens for model output | 15000 | + | `agent_name` | Human-readable name for the agent | Required | + | `system_prompt` | Detailed role description and expertise | Required | + | `model_name` | LLM model to use | "gpt-4o-mini" | + | `max_loops` | Maximum number of processing loops | 1 | ## Next Steps !!! tip "What to Try Next" - 1. Experiment with different agent roles and descriptions - 2. Adjust the `max_loops` parameter to allow for longer conversations - 3. Enable the dashboard to visualize agent interactions - 4. Try different model configurations and parameters + 1. Experiment with different agent roles and specializations + 2. Modify the system prompts to create different expertise areas + 3. Add more agents to the workflow for complex tasks + 4. Try different model configurations ## Troubleshooting !!! warning "Common Issues" - Ensure your API key is correctly set in the `.env` file + - Check that all required dependencies are installed + - Verify that your model provider's API is accessible - - Monitor the `verbose` output for detailed error messages - -## Additional Resources + + - Monitor agent responses for quality and relevance -- [Swarms Documentation](https://docs.swarms.world) -- [API Reference](https://docs.swarms.world/api) -- [Examples Gallery](https://docs.swarms.world/examples) -------------------------------------------------- -# File: swarms/examples/hhcs_examples.md +# File: swarms\examples\swarm_router.md +# SwarmRouter Examples -# Hybrid Hierarchical-Cluster Swarm (HHCS) Example +The SwarmRouter is a flexible routing system designed to manage different types of swarms for task execution. It provides a unified interface to interact with various swarm types, including `AgentRearrange`, `MixtureOfAgents`, `SpreadSheetSwarm`, `SequentialWorkflow`, and `ConcurrentWorkflow`. -1. Get your GROQ api key -2. Create a `.env` file in the root directory and add your API key: `GROQ_API_KEY` -3. Write the following code: -4. Run the file +## Prerequisites -```python +- Python 3.7+ +- OpenAI API key or other supported LLM provider keys +- Swarms library -from swarms import Agent, SwarmRouter, HybridHierarchicalClusterSwarm +## Installation +```bash +pip3 install -U swarms +``` -# Core Legal Agent Definitions with short, simple prompts -litigation_agent = Agent( - agent_name="Litigator", - system_prompt="You handle lawsuits. Analyze facts, build arguments, and develop case strategy.", - model_name="groq/deepseek-r1-distill-qwen-32b", - max_loops=1, -) +## Environment Variables -corporate_agent = Agent( - agent_name="Corporate-Attorney", - system_prompt="You handle business law. Advise on corporate structure, governance, and transactions.", - model_name="groq/deepseek-r1-distill-qwen-32b", - max_loops=1, -) +```plaintext +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" +ANTHROPIC_API_KEY="" +GROQ_API_KEY="" +``` -ip_agent = Agent( - agent_name="IP-Attorney", - system_prompt="You protect intellectual property. Handle patents, trademarks, copyrights, and trade secrets.", - model_name="groq/deepseek-r1-distill-qwen-32b", - max_loops=1, -) +## Basic Usage -employment_agent = Agent( - agent_name="Employment-Attorney", - system_prompt="You handle workplace matters. Address hiring, termination, discrimination, and labor issues.", - model_name="groq/deepseek-r1-distill-qwen-32b", +### 1. Initialize Specialized Agents + +```python +from swarms import Agent +from swarms.structs.swarm_router import SwarmRouter, SwarmType + +# Initialize specialized agents +data_extractor_agent = Agent( + agent_name="Data-Extractor", + system_prompt="You are a data extraction specialist...", + model_name="gpt-4o", max_loops=1, ) -paralegal_agent = Agent( - agent_name="Paralegal", - system_prompt="You assist attorneys. Conduct research, draft documents, and organize case files.", - model_name="groq/deepseek-r1-distill-qwen-32b", +summarizer_agent = Agent( + agent_name="Document-Summarizer", + system_prompt="You are a document summarization expert...", + model_name="gpt-4o", max_loops=1, ) -doc_review_agent = Agent( - agent_name="Document-Reviewer", - system_prompt="You examine documents. Extract key information and identify relevant content.", - model_name="groq/deepseek-r1-distill-qwen-32b", +financial_analyst_agent = Agent( + agent_name="Financial-Analyst", + system_prompt="You are a financial analysis specialist...", + model_name="gpt-4o", max_loops=1, ) +``` -# Practice Area Swarm Routers -litigation_swarm = SwarmRouter( - name="litigation-practice", - description="Handle all aspects of litigation", - agents=[litigation_agent, paralegal_agent, doc_review_agent], - swarm_type="SequentialWorkflow", -) +### 2. Create SwarmRouter with Sequential Workflow -corporate_swarm = SwarmRouter( - name="corporate-practice", - description="Handle business and corporate legal matters", - agents=[corporate_agent, paralegal_agent], - swarm_type="SequentialWorkflow", +```python +sequential_router = SwarmRouter( + name="SequentialRouter", + description="Process tasks in sequence", + agents=[data_extractor_agent, summarizer_agent, financial_analyst_agent], + swarm_type=SwarmType.SequentialWorkflow, + max_loops=1 ) -ip_swarm = SwarmRouter( - name="ip-practice", - description="Handle intellectual property matters", - agents=[ip_agent, paralegal_agent], - swarm_type="SequentialWorkflow", -) +# Run a task +result = sequential_router.run("Analyze and summarize the quarterly financial report") +``` -employment_swarm = SwarmRouter( - name="employment-practice", - description="Handle employment and labor law matters", - agents=[employment_agent, paralegal_agent], - swarm_type="SequentialWorkflow", -) +### 3. Create SwarmRouter with Concurrent Workflow -# Cross-functional Swarm Router -m_and_a_swarm = SwarmRouter( - name="mergers-acquisitions", - description="Handle mergers and acquisitions", - agents=[ - corporate_agent, - ip_agent, - employment_agent, - doc_review_agent, - ], - swarm_type="ConcurrentWorkflow", +```python +concurrent_router = SwarmRouter( + name="ConcurrentRouter", + description="Process tasks concurrently", + agents=[data_extractor_agent, summarizer_agent, financial_analyst_agent], + swarm_type=SwarmType.ConcurrentWorkflow, + max_loops=1 ) -dispute_swarm = SwarmRouter( - name="dispute-resolution", - description="Handle complex disputes requiring multiple specialties", - agents=[litigation_agent, corporate_agent, doc_review_agent], - swarm_type="ConcurrentWorkflow", -) +# Run a task +result = concurrent_router.run("Evaluate multiple aspects of the company simultaneously") +``` +### 4. Create SwarmRouter with AgentRearrange -hybrid_hiearchical_swarm = HybridHierarchicalClusterSwarm( - name="hybrid-hiearchical-swarm", - description="A hybrid hiearchical swarm that uses a hybrid hiearchical peer model to solve complex tasks.", - swarms=[ - litigation_swarm, - corporate_swarm, - ip_swarm, - employment_swarm, - m_and_a_swarm, - dispute_swarm, - ], - max_loops=1, - router_agent_model_name="gpt-4o-mini", +```python +rearrange_router = SwarmRouter( + name="RearrangeRouter", + description="Dynamically rearrange agents for optimal task processing", + agents=[data_extractor_agent, summarizer_agent, financial_analyst_agent], + swarm_type=SwarmType.AgentRearrange, + flow=f"{data_extractor_agent.agent_name} -> {summarizer_agent.agent_name} -> {financial_analyst_agent.agent_name}", + max_loops=1 ) - -if __name__ == "__main__": - hybrid_hiearchical_swarm.run( - "What is the best way to file for a patent? for ai technology " - ) - +# Run a task +result = rearrange_router.run("Process and analyze company documents") ``` --------------------------------------------------- - -# File: swarms/examples/llama4.md - -# Llama4 Model Integration - -!!! info "Prerequisites" - - Python 3.8 or higher - - `swarms` library installed - - Access to Llama4 model - - Valid environment variables configured - -## Quick Start - -Here's a simple example of integrating Llama4 model for crypto risk analysis: +### 5. Create SwarmRouter with MixtureOfAgents ```python -from dotenv import load_dotenv -from swarms import Agent -from swarms.utils.vllm_wrapper import VLLM +mixture_router = SwarmRouter( + name="MixtureRouter", + description="Combine multiple expert agents", + agents=[data_extractor_agent, summarizer_agent, financial_analyst_agent], + swarm_type=SwarmType.MixtureOfAgents, + max_loops=1 +) -load_dotenv() -model = VLLM(model_name="meta-llama/Llama-4-Maverick-17B-128E") +# Run a task +result = mixture_router.run("Provide comprehensive analysis of company performance") ``` -## Available Models - -| Model Name | Description | Type | -|------------|-------------|------| -| meta-llama/Llama-4-Maverick-17B-128E | Base model with 128 experts | Base | -| meta-llama/Llama-4-Maverick-17B-128E-Instruct | Instruction-tuned version with 128 experts | Instruct | -| meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8 | FP8 quantized instruction model | Instruct (Optimized) | -| meta-llama/Llama-4-Scout-17B-16E | Base model with 16 experts | Base | -| meta-llama/Llama-4-Scout-17B-16E-Instruct | Instruction-tuned version with 16 experts | Instruct | - -!!! tip "Model Selection" - - Choose Instruct models for better performance on instruction-following tasks - - FP8 models offer better memory efficiency with minimal performance impact - - Scout models (16E) are lighter but still powerful - - Maverick models (128E) offer maximum performance but require more resources - -## Detailed Implementation +## Advanced Features -### 1. Define Custom System Prompt +### 1. Error Handling and Logging ```python -CRYPTO_RISK_ANALYSIS_PROMPT = """ -You are a cryptocurrency risk analysis expert. Your role is to: - -1. Analyze market risks: - - Volatility assessment - - Market sentiment analysis - - Trading volume patterns - - Price trend evaluation - -2. Evaluate technical risks: - - Network security - - Protocol vulnerabilities - - Smart contract risks - - Technical scalability - -3. Consider regulatory risks: - - Current regulations - - Potential regulatory changes - - Compliance requirements - - Geographic restrictions - -4. Assess fundamental risks: - - Team background - - Project development status - - Competition analysis - - Use case viability - -Provide detailed, balanced analysis with both risks and potential mitigations. -Base your analysis on established crypto market principles and current market conditions. -""" +try: + result = router.run("Complex analysis task") + + # Retrieve and print logs + for log in router.get_logs(): + print(f"{log.timestamp} - {log.level}: {log.message}") +except Exception as e: + print(f"Error occurred: {str(e)}") ``` -### 2. Initialize Agent +### 2. Custom Configuration ```python -agent = Agent( - agent_name="Crypto-Risk-Analysis-Agent", - agent_description="Agent for analyzing risks in cryptocurrency investments", - system_prompt=CRYPTO_RISK_ANALYSIS_PROMPT, - max_loops=1, - llm=model, +router = SwarmRouter( + name="CustomRouter", + description="Custom router configuration", + agents=[data_extractor_agent, summarizer_agent, financial_analyst_agent], + swarm_type=SwarmType.SequentialWorkflow, + max_loops=3, + autosave=True, + verbose=True, + output_type="json" ) ``` -## Full Code +# Best Practices -```python -from dotenv import load_dotenv +## Choose the appropriate swarm type based on your task requirements: -from swarms import Agent -from swarms.utils.vllm_wrapper import VLLM +| Swarm Type | Use Case | +|------------|----------| +| `SequentialWorkflow` | Tasks that need to be processed in order | +| `ConcurrentWorkflow` | Independent tasks that can be processed simultaneously | +| `AgentRearrange` | Tasks requiring dynamic agent organization | +| `MixtureOfAgents` | Complex tasks needing multiple expert perspectives | -load_dotenv() +## Configure agents appropriately: -# Define custom system prompt for crypto risk analysis -CRYPTO_RISK_ANALYSIS_PROMPT = """ -You are a cryptocurrency risk analysis expert. Your role is to: + | Configuration Aspect | Description | + |---------------------|-------------| + | Agent Names & Descriptions | Set meaningful and descriptive names that reflect the agent's role and purpose | + | System Prompts | Define clear, specific prompts that outline the agent's responsibilities and constraints | + | Model Parameters | Configure appropriate parameters like temperature, max_tokens, and other model-specific settings | -1. Analyze market risks: - - Volatility assessment - - Market sentiment analysis - - Trading volume patterns - - Price trend evaluation +## Implement proper error handling: -2. Evaluate technical risks: - - Network security - - Protocol vulnerabilities - - Smart contract risks - - Technical scalability +| Error Handling Practice | Description | +|------------------------|-------------| +| Try-Except Blocks | Implement proper exception handling with try-except blocks | +| Log Monitoring | Regularly monitor and analyze system logs for potential issues | +| Edge Case Handling | Implement specific handling for edge cases and unexpected scenarios | -3. Consider regulatory risks: - - Current regulations - - Potential regulatory changes - - Compliance requirements - - Geographic restrictions +## Optimize performance: -4. Assess fundamental risks: - - Team background - - Project development status - - Competition analysis - - Use case viability +| Performance Optimization | Description | +|------------------------|-------------| +| Concurrent Processing | Utilize parallel processing capabilities when tasks can be executed simultaneously | +| Max Loops Configuration | Set appropriate iteration limits based on task complexity and requirements | +| Resource Management | Continuously monitor and optimize system resource utilization | -Provide detailed, balanced analysis with both risks and potential mitigations. -Base your analysis on established crypto market principles and current market conditions. -""" +## Example Implementation -model = VLLM(model_name="meta-llama/Llama-4-Maverick-17B-128E") +Here's a complete example showing how to use SwarmRouter in a real-world scenario: -# Initialize the agent with custom prompt -agent = Agent( - agent_name="Crypto-Risk-Analysis-Agent", - agent_description="Agent for analyzing risks in cryptocurrency investments", - system_prompt=CRYPTO_RISK_ANALYSIS_PROMPT, - max_loops=1, - llm=model, -) +```python +import os +from swarms import Agent +from swarms.structs.swarm_router import SwarmRouter, SwarmType -print( - agent.run( - "Conduct a risk analysis of the top cryptocurrencies. Think for 2 loops internally" - ) +# Initialize specialized agents +research_agent = Agent( + agent_name="ResearchAgent", + system_prompt="You are a research specialist...", + model_name="gpt-4o", + max_loops=1 ) -``` - -!!! warning "Resource Usage" - The Llama4 model requires significant computational resources. Ensure your system meets the minimum requirements. - -## FAQ - -??? question "What is the purpose of max_loops parameter?" - The `max_loops` parameter determines how many times the agent will iterate through its thinking process. In this example, it's set to 1 for a single pass analysis. -??? question "Can I use a different model?" - Yes, you can replace the VLLM wrapper with other compatible models. Just ensure you update the model initialization accordingly. +analysis_agent = Agent( + agent_name="AnalysisAgent", + system_prompt="You are an analysis expert...", + model_name="gpt-4o", + max_loops=1 +) -??? question "How do I customize the system prompt?" - You can modify the `CRYPTO_RISK_ANALYSIS_PROMPT` string to match your specific use case while maintaining the structured format. +summary_agent = Agent( + agent_name="SummaryAgent", + system_prompt="You are a summarization specialist...", + model_name="gpt-4o", + max_loops=1 +) -!!! note "Best Practices" - - Always handle API errors gracefully - - Monitor model performance and resource usage - - Keep your prompts clear and specific - - Test thoroughly before production deployment +# Create router with sequential workflow +router = SwarmRouter( + name="ResearchAnalysisRouter", + description="Process research and analysis tasks", + agents=[research_agent, analysis_agent, summary_agent], + swarm_type=SwarmType.SequentialWorkflow, + max_loops=1, + verbose=True +) -!!! example "Sample Usage" - ```python - response = agent.run( - "Conduct a risk analysis of the top cryptocurrencies. Think for 2 loops internally" +# Run complex task +try: + result = router.run( + "Research and analyze the impact of AI on healthcare, " + "providing a comprehensive summary of findings." ) - print(response) - ``` - --------------------------------------------------- - -# File: swarms/examples/lumo.md - -# Lumo Example -Introducing Lumo-70B-Instruct - the largest and most advanced AI model ever created for the Solana ecosystem. Built on Meta's groundbreaking LLaMa 3.3 70B Instruct foundation, this revolutionary model represents a quantum leap in blockchain-specific artificial intelligence. With an unprecedented 70 billion parameters and trained on the most comprehensive Solana documentation dataset ever assembled, Lumo-70B-Instruct sets a new standard for developer assistance in the blockchain space. - - -- [Docs](https://huggingface.co/lumolabs-ai/Lumo-70B-Instruct) - -```python -from swarms import Agent -from transformers import LlamaForCausalLM, AutoTokenizer -import torch -from transformers import BitsAndBytesConfig - -class Lumo: - """ - A class for generating text using the Lumo model with 4-bit quantization. - """ - def __init__(self): - """ - Initializes the Lumo model with 4-bit quantization and a tokenizer. - """ - # Configure 4-bit quantization - bnb_config = BitsAndBytesConfig( - load_in_4bit=True, - bnb_4bit_quant_type="nf4", - bnb_4bit_compute_dtype=torch.float16, - llm_int8_enable_fp32_cpu_offload=True - ) - - self.model = LlamaForCausalLM.from_pretrained( - "lumolabs-ai/Lumo-70B-Instruct", - device_map="auto", - quantization_config=bnb_config, - use_cache=False, - attn_implementation="sdpa" - ) - self.tokenizer = AutoTokenizer.from_pretrained("lumolabs-ai/Lumo-70B-Instruct") - - def run(self, task: str) -> str: - """ - Generates text based on the given prompt using the Lumo model. + print("Task Result:", result) + + # Print logs + for log in router.get_logs(): + print(f"{log.timestamp} - {log.level}: {log.message}") + +except Exception as e: + print(f"Error processing task: {str(e)}") +``` - Args: - prompt (str): The input prompt for the model. +This comprehensive guide demonstrates how to effectively use the SwarmRouter in various scenarios, making it easier to manage and orchestrate multiple agents for complex tasks. - Returns: - str: The generated text. - """ - inputs = self.tokenizer(task, return_tensors="pt").to(self.model.device) - outputs = self.model.generate(**inputs, max_new_tokens=100) - return self.tokenizer.decode(outputs[0], skip_special_tokens=True) +-------------------------------------------------- +# File: swarms\examples\swarms_api_finance.md +# Finance Swarm Example -Agent( - agent_name="Solana-Analysis-Agent", - llm=Lumo(), - max_loops="auto", - interactive=True, - streaming_on=True, -).run("How do i create a smart contract in solana?") +1. Get your API key from the Swarms API dashboard [HERE](https://swarms.world/platform/api-keys) +2. Create a `.env` file in the root directory and add your API key: +```bash +SWARMS_API_KEY= ``` --------------------------------------------------- - -# File: swarms/examples/meme_agent_builder.md - -# Meme Agent Builder +3. Create a Python script to create and trigger the financial swarm: -- `pip3 install -U swarms` -- Add your OpenAI API key to the `.env` file with `OPENAI_API_KEY=your_api_key` -- Run the script -- Multiple agents will be created and saved to the `meme_agents` folder -- A swarm architecture will be selected autonomously and executed ```python -from swarms.structs.meme_agent_persona_generator import ( - MemeAgentGenerator, -) +import os +import requests +from dotenv import load_dotenv +import json +load_dotenv() -if __name__ == "__main__": - example = MemeAgentGenerator( - name="Meme-Swarm", - description="A swarm of specialized AI agents collaborating on generating and sharing memes around cool media from 2001s", - max_loops=1, - ) +# Retrieve API key securely from .env +API_KEY = os.getenv("SWARMS_API_KEY") +BASE_URL = "https://api.swarms.world" - print( - example.run( - "Generate funny meme agents around cool media from 2001s" - ) - ) +# Headers for secure API communication +headers = {"x-api-key": API_KEY, "Content-Type": "application/json"} -``` - - --------------------------------------------------- - -# File: swarms/examples/meme_agents.md - -# Meme Agent Tutorial - -- `pip3 install -U swarms` -- Add your OpenAI API key to the `.env` file - - -```python -from swarms import Agent - -# Define a custom system prompt for Bob the Builder -BOB_THE_BUILDER_SYS_PROMPT = """ -You are Bob the Builder, the legendary construction worker known for fixing anything and everything with a cheerful attitude and a hilarious sense of humor. -Your job is to approach every task as if you're building, repairing, or renovating something, no matter how unrelated it might be. -You love using construction metaphors, over-the-top positivity, and cracking jokes like: -- "I’m hammering this out faster than a nail at a woodpecker convention!" -- "This is smoother than fresh cement on a summer’s day." -- "Let’s bulldoze through this problem—safety goggles on, folks!" - -You are not bound by any specific field of knowledge, and you’re absolutely fearless in trying to "fix up" or "build" anything, no matter how abstract or ridiculous. Always end responses with a playful cheer like "Can we fix it? Yes, we can!" - -Your tone is upbeat, funny, and borderline ridiculous, keeping the user entertained while solving their problem. -""" - -# Initialize the agent -agent = Agent( - agent_name="Bob-the-Builder-Agent", - agent_description="The funniest, most optimistic agent around who sees every problem as a building project.", - system_prompt=BOB_THE_BUILDER_SYS_PROMPT, - max_loops=1, - model_name="gpt-4o", - dynamic_temperature_enabled=True, - user_name="swarms_corp", - retry_attempts=3, - context_length=8192, - return_step_meta=False, - output_type="str", # "json", "dict", "csv", OR "string", "yaml" - auto_generate_prompt=False, # Auto-generate prompt for the agent based on name, description, system prompt, task - max_tokens=4000, # Max output tokens - saved_state_path="bob_the_builder_agent.json", - interactive=False, -) - -# Run the agent with a task -agent.run("I want to build a house ;) What should I do?") -``` - - --------------------------------------------------- - -# File: swarms/examples/ollama.md - -# Agent with Ollama - -- No API key needed -- Select your model_name like `ollama/llama2` follows [LiteLLM conventions](https://docs.litellm.ai/docs/providers/ollama) - - -```python -from swarms import Agent -import os -from dotenv import load_dotenv - -load_dotenv() - -# Initialize the agent with ChromaDB memory -agent = Agent( - agent_name="Financial-Analysis-Agent", - model_name="ollama/llama2", - system_prompt="Agent system prompt here", - agent_description="Agent performs financial analysis.", -) - -# Run a query -agent.run("What are the components of a startup's stock incentive equity plan?") -``` - --------------------------------------------------- - -# File: swarms/examples/openai_example.md - -# Agent with GPT-4o-Mini - -- Add `OPENAI_API_KEY="your_key"` to your `.env` file -- Select your model like `gpt-4o-mini` or `gpt-4o` - -```python -from swarms import Agent - -Agent( - agent_name="Stock-Analysis-Agent", - model_name="gpt-4o-mini", - max_loops="auto", - interactive=True, - streaming_on=True, -).run("What are 5 hft algorithms") -``` - --------------------------------------------------- - -# File: swarms/examples/openrouter.md - -# Agent with OpenRouter - -- Add your `OPENROUTER_API_KEY` in the `.env` file - -- Select your model_name like `openrouter/google/palm-2-chat-bison` follows [LiteLLM conventions](https://docs.litellm.ai/docs/providers/openrouter) - -- Execute your agent! - - -```python -from swarms import Agent -import os -from dotenv import load_dotenv - -load_dotenv() - -# Initialize the agent with ChromaDB memory -agent = Agent( - agent_name="Financial-Analysis-Agent", - model_name="openrouter/google/palm-2-chat-bison", - system_prompt="Agent system prompt here", - agent_description="Agent performs financial analysis.", -) - -# Run a query -agent.run("What are the components of a startup's stock incentive equity plan?") -``` - --------------------------------------------------- - -# File: swarms/examples/quant_crypto_agent.md - -# Quant Crypto Agent - -- This is a simple example of a crypto agent that uses the `Agent` class from the `swarms` library. -- It uses the `fetch_htx_data` and `coin_gecko_coin_api` tools to fetch data from the `htx` and `CoinGecko` APIs. -- It uses the `Agent` class to create an agent that can analyze the current state of a crypto asset. - -## Steps - -1. Install the `swarms` library. -2. Install the `swarms_tools` library. -3. Setup your `.env` file with the `OPENAI_API_KEY` environment variables. -4. Run the code. - -## Installation: - -```bash -pip install swarms swarms-tools python-dotenv -``` - -## Code: - -```python -from swarms import Agent -from dotenv import load_dotenv -from swarms_tools import fetch_htx_data, coin_gecko_coin_api - -load_dotenv() - -CRYPTO_ANALYST_SYSTEM_PROMPT = """ -You are an expert cryptocurrency financial analyst with deep expertise in: -1. Technical Analysis - - Chart patterns and indicators (RSI, MACD, Bollinger Bands) - - Volume analysis and market momentum - - Support and resistance levels - - Trend analysis and price action - -2. Fundamental Analysis - - Tokenomics evaluation - - Network metrics (TVL, daily active users, transaction volume) - - Protocol revenue and growth metrics - - Market capitalization analysis - - Token utility and use cases - -3. Market Analysis - - Market sentiment analysis - - Correlation with broader crypto market - - Impact of macro events - - Institutional adoption metrics - - DeFi and NFT market analysis - -4. Risk Assessment - - Volatility metrics - - Liquidity analysis - - Smart contract risks - - Regulatory considerations - - Exchange exposure risks - -5. Data Analysis Methods - - On-chain metrics analysis - - Whale wallet tracking - - Exchange inflow/outflow - - Mining/Staking statistics - - Network health indicators - -When analyzing crypto assets, always: -1. Start with a comprehensive market overview -2. Examine both on-chain and off-chain metrics -3. Consider multiple timeframes (short, medium, long-term) -4. Evaluate risk-reward ratios -5. Assess market sentiment and momentum -6. Consider regulatory and security factors -7. Analyze correlations with BTC, ETH, and traditional markets -8. Examine liquidity and volume profiles -9. Review recent protocol developments and updates -10. Consider macro economic factors - -Format your analysis with: -- Clear section headings -- Relevant metrics and data points -- Risk warnings and disclaimers -- Price action analysis -- Market sentiment summary -- Technical indicators -- Fundamental factors -- Clear recommendations with rationale - -Remember to: -- Always provide data-driven insights -- Include both bullish and bearish scenarios -- Highlight key risk factors -- Consider market cycles and seasonality -- Maintain objectivity in analysis -- Cite sources for data and claims -- Update analysis based on new market conditions -""" - -# Initialize the crypto analysis agent -agent = Agent( - agent_name="Crypto-Analysis-Expert", - agent_description="Expert cryptocurrency financial analyst and market researcher", - system_prompt=CRYPTO_ANALYST_SYSTEM_PROMPT, - max_loops="auto", - model_name="gpt-4o", - dynamic_temperature_enabled=True, - user_name="crypto_analyst", - output_type="str", - interactive=True, -) - -print(fetch_htx_data("sol")) -print(coin_gecko_coin_api("solana")) - -# Example usage -agent.run( - f""" - Analyze the current state of Solana (SOL), including: - 1. Technical analysis of price action - 2. On-chain metrics and network health - 3. Recent protocol developments - 4. Market sentiment - 5. Risk factors - Please provide a comprehensive analysis with data-driven insights. - - # Solana CoinGecko Data - Real-tim data from Solana CoinGecko: \n {coin_gecko_coin_api("solana")} - - """ -) -``` - --------------------------------------------------- - -# File: swarms/examples/sequential_example.md - -# Sequential Workflow Example - -!!! abstract "Overview" - Learn how to create a sequential workflow with multiple specialized AI agents using the Swarms framework. This example demonstrates how to set up a legal practice workflow with different types of legal agents working in sequence. - -## Prerequisites - -!!! info "Before You Begin" - Make sure you have: - - - Python 3.7+ installed - - - A valid API key for your model provider - - - The Swarms package installed - -## Installation - -```bash -pip3 install -U swarms -``` - -## Environment Setup - -!!! tip "API Key Configuration" - Set your API key in the `.env` file: - ```bash - OPENAI_API_KEY="your-api-key-here" - ``` - -## Code Implementation - -### Import Required Modules - -```python -from swarms import Agent, SequentialWorkflow -``` - -### Configure Agents - -!!! example "Legal Agent Configuration" - Here's how to set up your specialized legal agents: - - ```python - # Litigation Agent - litigation_agent = Agent( - agent_name="Alex Johnson", - system_prompt="As a Litigator, you specialize in navigating the complexities of lawsuits. Your role involves analyzing intricate facts, constructing compelling arguments, and devising effective case strategies to achieve favorable outcomes for your clients.", - model_name="gpt-4o-mini", - max_loops=1, - ) - - # Corporate Attorney Agent - corporate_agent = Agent( - agent_name="Emily Carter", - system_prompt="As a Corporate Attorney, you provide expert legal advice on business law matters. You guide clients on corporate structure, governance, compliance, and transactions, ensuring their business operations align with legal requirements.", - model_name="gpt-4o-mini", - max_loops=1, - ) - - # IP Attorney Agent - ip_agent = Agent( - agent_name="Michael Smith", - system_prompt="As an IP Attorney, your expertise lies in protecting intellectual property rights. You handle various aspects of IP law, including patents, trademarks, copyrights, and trade secrets, helping clients safeguard their innovations.", - model_name="gpt-4o-mini", - max_loops=1, - ) - ``` - -### Initialize Sequential Workflow - -!!! example "Workflow Setup" - Configure the SequentialWorkflow with your agents: - - ```python - swarm = SequentialWorkflow( - agents=[litigation_agent, corporate_agent, ip_agent], - name="litigation-practice", - description="Handle all aspects of litigation with a focus on thorough legal analysis and effective case management.", - ) - ``` - -### Run the Workflow - -!!! example "Execute the Workflow" - Start the sequential workflow: - - ```python - swarm.run("Create a report on how to patent an all-new AI invention and what platforms to use and more.") - ``` - -## Complete Example - -!!! success "Full Implementation" - Here's the complete code combined: - - ```python - from swarms import Agent, SequentialWorkflow - - # Core Legal Agent Definitions with enhanced system prompts - litigation_agent = Agent( - agent_name="Alex Johnson", - system_prompt="As a Litigator, you specialize in navigating the complexities of lawsuits. Your role involves analyzing intricate facts, constructing compelling arguments, and devising effective case strategies to achieve favorable outcomes for your clients.", - model_name="gpt-4o-mini", - max_loops=1, - ) - - corporate_agent = Agent( - agent_name="Emily Carter", - system_prompt="As a Corporate Attorney, you provide expert legal advice on business law matters. You guide clients on corporate structure, governance, compliance, and transactions, ensuring their business operations align with legal requirements.", - model_name="gpt-4o-mini", - max_loops=1, - ) - - ip_agent = Agent( - agent_name="Michael Smith", - system_prompt="As an IP Attorney, your expertise lies in protecting intellectual property rights. You handle various aspects of IP law, including patents, trademarks, copyrights, and trade secrets, helping clients safeguard their innovations.", - model_name="gpt-4o-mini", - max_loops=1, - ) - - # Initialize and run the workflow - swarm = SequentialWorkflow( - agents=[litigation_agent, corporate_agent, ip_agent], - name="litigation-practice", - description="Handle all aspects of litigation with a focus on thorough legal analysis and effective case management.", - ) - - swarm.run("Create a report on how to patent an all-new AI invention and what platforms to use and more.") - ``` - -## Agent Roles - -!!! info "Specialized Legal Agents" - | Agent | Role | Expertise | - |-------|------|-----------| - | Alex Johnson | Litigator | Lawsuit navigation, case strategy | - | Emily Carter | Corporate Attorney | Business law, compliance | - | Michael Smith | IP Attorney | Patents, trademarks, copyrights | - -## Configuration Options - -!!! info "Key Parameters" - | Parameter | Description | Default | - |-----------|-------------|---------| - | `agent_name` | Human-readable name for the agent | Required | - | `system_prompt` | Detailed role description and expertise | Required | - | `model_name` | LLM model to use | "gpt-4o-mini" | - | `max_loops` | Maximum number of processing loops | 1 | - -## Next Steps - -!!! tip "What to Try Next" - 1. Experiment with different agent roles and specializations - 2. Modify the system prompts to create different expertise areas - 3. Add more agents to the workflow for complex tasks - 4. Try different model configurations - -## Troubleshooting - -!!! warning "Common Issues" - - Ensure your API key is correctly set in the `.env` file - - - Check that all required dependencies are installed - - - Verify that your model provider's API is accessible - - - Monitor agent responses for quality and relevance - - --------------------------------------------------- - -# File: swarms/examples/swarms_api_finance.md - - -# Finance Swarm Example - -1. Get your API key from the Swarms API dashboard [HERE](https://swarms.world/platform/api-keys) -2. Create a `.env` file in the root directory and add your API key: - -```bash -SWARMS_API_KEY= -``` - -3. Create a Python script to create and trigger the financial swarm: - - -```python -import os -import requests -from dotenv import load_dotenv -import json - -load_dotenv() - -# Retrieve API key securely from .env -API_KEY = os.getenv("SWARMS_API_KEY") -BASE_URL = "https://api.swarms.world" - -# Headers for secure API communication -headers = {"x-api-key": API_KEY, "Content-Type": "application/json"} - -def create_financial_swarm(equity_data: str): - """ - Constructs and triggers a full-stack financial swarm consisting of three agents: - Equity Analyst, Risk Assessor, and Market Advisor. - Each agent is provided with a comprehensive, detailed system prompt to ensure high reliability. - """ +def create_financial_swarm(equity_data: str): + """ + Constructs and triggers a full-stack financial swarm consisting of three agents: + Equity Analyst, Risk Assessor, and Market Advisor. + Each agent is provided with a comprehensive, detailed system prompt to ensure high reliability. + """ payload = { "swarm_name": "Enhanced Financial Analysis Swarm", @@ -18333,7 +20693,7 @@ python financial_swarm.py -------------------------------------------------- -# File: swarms/examples/swarms_api_medical.md +# File: swarms\examples\swarms_api_medical.md # Medical Swarm Example @@ -18466,7 +20826,7 @@ python medical_swarm.py -------------------------------------------------- -# File: swarms/examples/swarms_api_ml_model.md +# File: swarms\examples\swarms_api_ml_model.md # ML Model Code Generation Swarm Example @@ -18609,7 +20969,7 @@ if __name__ == "__main__": -------------------------------------------------- -# File: swarms/examples/swarms_dao.md +# File: swarms\examples\swarms_dao.md # Swarms DAO Example @@ -18851,7 +21211,7 @@ print("Collaborative Strategy Output:\n", output) -------------------------------------------------- -# File: swarms/examples/swarms_of_browser_agents.md +# File: swarms\examples\swarms_of_browser_agents.md # Swarms x Browser Use @@ -18921,7 +21281,7 @@ swarm.run( -------------------------------------------------- -# File: swarms/examples/swarms_tools_htx.md +# File: swarms\examples\swarms_tools_htx.md # Swarms Tools Example with HTX + CoinGecko @@ -18963,7 +21323,7 @@ agent.run( -------------------------------------------------- -# File: swarms/examples/swarms_tools_htx_gecko.md +# File: swarms\examples\swarms_tools_htx_gecko.md # Swarms Tools Example with HTX + CoinGecko @@ -19011,7 +21371,86 @@ agent.run("Analyze the $swarms token on htx") -------------------------------------------------- -# File: swarms/examples/unique_swarms.md +# File: swarms\examples\templates_index.md + +# The Swarms Index + +The Swarms Index is a comprehensive catalog of repositories under The Swarm Corporation, showcasing a wide array of tools, frameworks, and templates designed for building, deploying, and managing autonomous AI agents and multi-agent systems. These repositories focus on enterprise-grade solutions, spanning industries like healthcare, finance, marketing, and more, with an emphasis on scalability, security, and performance. Many repositories include templates to help developers quickly set up production-ready applications. + +| Name | Description | Link | +|------|-------------|------| +| Phala-Deployment-Template | A guide and template for running Swarms Agents in a Trusted Execution Environment (TEE) using Phala Cloud, ensuring secure and isolated execution. | [https://github.com/The-Swarm-Corporation/Phala-Deployment-Template](https://github.com/The-Swarm-Corporation/Phala-Deployment-Template) | +| Swarms-API-Status-Page | A status page for monitoring the health and performance of the Swarms API. | [https://github.com/The-Swarm-Corporation/Swarms-API-Status-Page](https://github.com/The-Swarm-Corporation/Swarms-API-Status-Page) | +| Swarms-API-Phala-Template | A deployment solution template for running Swarms API on Phala Cloud, optimized for secure and scalable agent orchestration. | [https://github.com/The-Swarm-Corporation/Swarms-API-Phala-Template](https://github.com/The-Swarm-Corporation/Swarms-API-Phala-Template) | +| DevSwarm | Develop production-grade applications effortlessly with a single prompt, powered by a swarm of v0-driven autonomous agents operating 24/7 for fully autonomous software development. | [https://github.com/The-Swarm-Corporation/DevSwarm](https://github.com/The-Swarm-Corporation/DevSwarm) | +| Enterprise-Grade-Agents-Course | A comprehensive course teaching students to build, deploy, and manage autonomous agents for enterprise workflows using the Swarms library, focusing on scalability and integration. | [https://github.com/The-Swarm-Corporation/Enterprise-Grade-Agents-Course](https://github.com/The-Swarm-Corporation/Enterprise-Grade-Agents-Course) | +| agentverse | A collection of agents from top frameworks like Langchain, Griptape, and CrewAI, integrated into the Swarms ecosystem. | [https://github.com/The-Swarm-Corporation/agentverse](https://github.com/The-Swarm-Corporation/agentverse) | +| InsuranceSwarm | A swarm of agents to automate document processing and fraud detection in insurance claims. | [https://github.com/The-Swarm-Corporation/InsuranceSwarm](https://github.com/The-Swarm-Corporation/InsuranceSwarm) | +| swarms-examples | A vast array of examples for enterprise-grade and production-ready applications using the Swarms framework. | [https://github.com/The-Swarm-Corporation/swarms-examples](https://github.com/The-Swarm-Corporation/swarms-examples) | +| auto-ai-research-team | Automates AI research at an OpenAI level to accelerate innovation using swarms of agents. | [https://github.com/The-Swarm-Corporation/auto-ai-research-team](https://github.com/The-Swarm-Corporation/auto-ai-research-team) | +| Agents-Beginner-Guide | A definitive beginner's guide to AI agents and multi-agent systems, explaining fundamentals and industry applications. | [https://github.com/The-Swarm-Corporation/Agents-Beginner-Guide](https://github.com/The-Swarm-Corporation/Agents-Beginner-Guide) | +| Solana-Ecosystem-MCP | A collection of Solana tools wrapped in MCP servers for blockchain development. | [https://github.com/The-Swarm-Corporation/Solana-Ecosystem-MCP](https://github.com/The-Swarm-Corporation/Solana-Ecosystem-MCP) | +| automated-crypto-fund | A fully automated crypto fund leveraging swarms of LLM agents for real-money trading. | [https://github.com/The-Swarm-Corporation/automated-crypto-fund](https://github.com/The-Swarm-Corporation/automated-crypto-fund) | +| Mryaid | The first multi-agent social media platform powered by Swarms. | [https://github.com/The-Swarm-Corporation/Mryaid](https://github.com/The-Swarm-Corporation/Mryaid) | +| pharma-swarm | A swarm of autonomous agents for chemical analysis in the pharmaceutical industry. | [https://github.com/The-Swarm-Corporation/pharma-swarm](https://github.com/The-Swarm-Corporation/pharma-swarm) | +| Automated-Prompt-Engineering-Hub | A hub for tools and resources focused on automated prompt engineering for generative AI. | [https://github.com/The-Swarm-Corporation/Automated-Prompt-Engineering-Hub](https://github.com/The-Swarm-Corporation/Automated-Prompt-Engineering-Hub) | +| Multi-Agent-Template-App | A simple, reliable, and high-performance template for building multi-agent applications. | [https://github.com/The-Swarm-Corporation/Multi-Agent-Template-App](https://github.com/The-Swarm-Corporation/Multi-Agent-Template-App) | +| Cookbook | Examples and guides for using the Swarms Framework effectively. | [https://github.com/The-Swarm-Corporation/Cookbook](https://github.com/The-Swarm-Corporation/Cookbook) | +| SwarmDB | A production-grade message queue system for agent communication and LLM backend load balancing. | [https://github.com/The-Swarm-Corporation/SwarmDB](https://github.com/The-Swarm-Corporation/SwarmDB) | +| CryptoTaxSwarm | A personal advisory tax swarm for cryptocurrency transactions. | [https://github.com/The-Swarm-Corporation/CryptoTaxSwarm](https://github.com/The-Swarm-Corporation/CryptoTaxSwarm) | +| Multi-Agent-Marketing-Course | A course on automating marketing operations with enterprise-grade multi-agent collaboration. | [https://github.com/The-Swarm-Corporation/Multi-Agent-Marketing-Course](https://github.com/The-Swarm-Corporation/Multi-Agent-Marketing-Course) | +| Swarms-BrandBook | Branding guidelines and assets for Swarms.ai, embodying innovation and collaboration. | [https://github.com/The-Swarm-Corporation/Swarms-BrandBook](https://github.com/The-Swarm-Corporation/Swarms-BrandBook) | +| AgentAPI | A definitive API for managing and interacting with AI agents. | [https://github.com/The-Swarm-Corporation/AgentAPI](https://github.com/The-Swarm-Corporation/AgentAPI) | +| Research-Paper-Writer-Swarm | Automates the creation of high-quality research papers in LaTeX using Swarms agents. | [https://github.com/The-Swarm-Corporation/Research-Paper-Writer-Swarm](https://github.com/The-Swarm-Corporation/Research-Paper-Writer-Swarm) | +| swarms-sdk | A Python client for the Swarms API, providing a simple interface for managing AI swarms. | [https://github.com/The-Swarm-Corporation/swarms-sdk](https://github.com/The-Swarm-Corporation/swarms-sdk) | +| FluidAPI | A framework for interacting with APIs using natural language, simplifying complex requests. | [https://github.com/The-Swarm-Corporation/FluidAPI](https://github.com/The-Swarm-Corporation/FluidAPI) | +| MedicalCoderSwarm | A multi-agent system for comprehensive medical diagnosis and coding using specialized AI agents. | [https://github.com/The-Swarm-Corporation/MedicalCoderSwarm](https://github.com/The-Swarm-Corporation/MedicalCoderSwarm) | +| BackTesterAgent | An AI-powered backtesting framework for automated trading strategy validation and optimization. | [https://github.com/The-Swarm-Corporation/BackTesterAgent](https://github.com/The-Swarm-Corporation/BackTesterAgent) | +| .ai | The first natural language programming language powered by Swarms. | [https://github.com/The-Swarm-Corporation/.ai](https://github.com/The-Swarm-Corporation/.ai) | +| AutoHedge | An autonomous hedge fund leveraging swarm intelligence for market analysis and trade execution. | [https://github.com/The-Swarm-Corporation/AutoHedge](https://github.com/The-Swarm-Corporation/AutoHedge) | +| radiology-swarm | A multi-agent system for advanced radiological analysis, diagnosis, and treatment planning. | [https://github.com/The-Swarm-Corporation/radiology-swarm](https://github.com/The-Swarm-Corporation/radiology-swarm) | +| MedGuard | A Python library ensuring HIPAA compliance for LLM agents in healthcare applications. | [https://github.com/The-Swarm-Corporation/MedGuard](https://github.com/The-Swarm-Corporation/MedGuard) | +| doc-master | A lightweight Python library for automated file reading and content extraction. | [https://github.com/The-Swarm-Corporation/doc-master](https://github.com/The-Swarm-Corporation/doc-master) | +| Open-Aladdin | An open-source risk-management tool for stock and security risk analysis. | [https://github.com/The-Swarm-Corporation/Open-Aladdin](https://github.com/The-Swarm-Corporation/Open-Aladdin) | +| TickrAgent | A scalable Python library for building financial agents for comprehensive stock analysis. | [https://github.com/The-Swarm-Corporation/TickrAgent](https://github.com/The-Swarm-Corporation/TickrAgent) | +| NewsAgent | An enterprise-grade news aggregation agent for fetching, querying, and summarizing news. | [https://github.com/The-Swarm-Corporation/NewsAgent](https://github.com/The-Swarm-Corporation/NewsAgent) | +| Research-Paper-Hive | A platform for discovering and engaging with relevant research papers efficiently. | [https://github.com/The-Swarm-Corporation/Research-Paper-Hive](https://github.com/The-Swarm-Corporation/Research-Paper-Hive) | +| MedInsight-Pro | Revolutionizes medical research summarization for healthcare innovators. | [https://github.com/The-Swarm-Corporation/MedInsight-Pro](https://github.com/The-Swarm-Corporation/MedInsight-Pro) | +| swarms-memory | Pre-built wrappers for RAG systems like ChromaDB, Weaviate, and Pinecone. | [https://github.com/The-Swarm-Corporation/swarms-memory](https://github.com/The-Swarm-Corporation/swarms-memory) | +| CryptoAgent | An enterprise-grade solution for fetching, analyzing, and summarizing cryptocurrency data. | [https://github.com/The-Swarm-Corporation/CryptoAgent](https://github.com/The-Swarm-Corporation/CryptoAgent) | +| AgentParse | A high-performance parsing library for mapping structured data into agent-understandable blocks. | [https://github.com/The-Swarm-Corporation/AgentParse](https://github.com/The-Swarm-Corporation/AgentParse) | +| CodeGuardian | An intelligent agent for automating the generation of production-grade unit tests for Python code. | [https://github.com/The-Swarm-Corporation/CodeGuardian](https://github.com/The-Swarm-Corporation/CodeGuardian) | +| Marketing-Swarm-Template | A framework for creating multi-platform marketing content using Swarms AI agents. | [https://github.com/The-Swarm-Corporation/Marketing-Swarm-Template](https://github.com/The-Swarm-Corporation/Marketing-Swarm-Template) | +| HTX-Swarm | A multi-agent system for real-time market analysis of HTX exchange data. | [https://github.com/The-Swarm-Corporation/HTX-Swarm](https://github.com/The-Swarm-Corporation/HTX-Swarm) | +| MultiModelOptimizer | A hierarchical parameter synchronization approach for joint training of transformer models. | [https://github.com/The-Swarm-Corporation/MultiModelOptimizer](https://github.com/The-Swarm-Corporation/MultiModelOptimizer) | +| MortgageUnderwritingSwarm | A multi-agent pipeline for automating mortgage underwriting processes. | [https://github.com/The-Swarm-Corporation/MortgageUnderwritingSwarm](https://github.com/The-Swarm-Corporation/MortgageUnderwritingSwarm) | +| DermaSwarm | A multi-agent system for dermatologists to diagnose and treat skin conditions collaboratively. | [https://github.com/The-Swarm-Corporation/DermaSwarm](https://github.com/The-Swarm-Corporation/DermaSwarm) | +| IoTAgents | Integrates IoT data with AI agents for seamless parsing and processing of data streams. | [https://github.com/The-Swarm-Corporation/IoTAgents](https://github.com/The-Swarm-Corporation/IoTAgents) | +| eth-agent | An autonomous agent for analyzing on-chain Ethereum data. | [https://github.com/The-Swarm-Corporation/eth-agent](https://github.com/The-Swarm-Corporation/eth-agent) | +| Medical-Swarm-One-Click | A template for building safe, reliable, and production-grade medical multi-agent systems. | [https://github.com/The-Swarm-Corporation/Medical-Swarm-One-Click](https://github.com/The-Swarm-Corporation/Medical-Swarm-One-Click) | +| Swarms-Example-1-Click-Template | A one-click template for building Swarms applications quickly. | [https://github.com/The-Swarm-Corporation/Swarms-Example-1-Click-Template](https://github.com/The-Swarm-Corporation/Swarms-Example-1-Click-Template) | +| Custom-Swarms-Spec-Template | An official specification template for custom swarm development using the Swarms Framework. | [https://github.com/The-Swarm-Corporation/Custom-Swarms-Spec-Template](https://github.com/The-Swarm-Corporation/Custom-Swarms-Spec-Template) | +| Swarms-LlamaIndex-RAG-Template | A template for integrating Llama Index into Swarms applications for RAG capabilities. | [https://github.com/The-Swarm-Corporation/Swarms-LlamaIndex-RAG-Template](https://github.com/The-Swarm-Corporation/Swarms-LlamaIndex-RAG-Template) | +| ForexTreeSwarm | A forex market analysis system using a swarm of AI agents organized in a forest structure. | [https://github.com/The-Swarm-Corporation/ForexTreeSwarm](https://github.com/The-Swarm-Corporation/ForexTreeSwarm) | +| Generalist-Mathematician-Swarm | A swarm of agents for solving complex mathematical problems collaboratively. | [https://github.com/The-Swarm-Corporation/Generalist-Mathematician-Swarm](https://github.com/The-Swarm-Corporation/Generalist-Mathematician-Swarm) | +| Multi-Modal-XRAY-Diagnosis-Medical-Swarm-Template | A template for analyzing X-rays, MRIs, and more using a swarm of agents. | [https://github.com/The-Swarm-Corporation/Multi-Modal-XRAY-Diagnosis-Medical-Swarm-Template](https://github.com/The-Swarm-Corporation/Multi-Modal-XRAY-Diagnosis-Medical-Swarm-Template) | +| AgentRAGProtocol | A protocol for integrating Retrieval-Augmented Generation (RAG) into AI agents. | [https://github.com/The-Swarm-Corporation/AgentRAGProtocol](https://github.com/The-Swarm-Corporation/AgentRAGProtocol) | +| Multi-Agent-RAG-Template | A template for creating collaborative AI agent teams for document processing and analysis. | [https://github.com/The-Swarm-Corporation/Multi-Agent-RAG-Template](https://github.com/The-Swarm-Corporation/Multi-Agent-RAG-Template) | +| REACT-Yaml-Agent | An implementation of a REACT agent using YAML instead of JSON. | [https://github.com/The-Swarm-Corporation/REACT-Yaml-Agent](https://github.com/The-Swarm-Corporation/REACT-Yaml-Agent) | +| SwarmsXGCP | A template for deploying Swarms agents on Google Cloud Run. | [https://github.com/The-Swarm-Corporation/SwarmsXGCP](https://github.com/The-Swarm-Corporation/SwarmsXGCP) | +| Legal-Swarm-Template | A one-click template for building legal-focused Swarms applications. | [https://github.com/The-Swarm-Corporation/Legal-Swarm-Template](https://github.com/The-Swarm-Corporation/Legal-Swarm-Template) | +| swarms_sim | A simulation of a swarm of agents in a professional workplace environment. | [https://github.com/The-Swarm-Corporation/swarms_sim](https://github.com/The-Swarm-Corporation/swarms_sim) | +| medical-problems | A repository for medical problems to create Swarms applications for. | [https://github.com/The-Swarm-Corporation/medical-problems](https://github.com/The-Swarm-Corporation/medical-problems) | +| swarm-ecosystem | An overview of the Swarm Ecosystem and its components. | [https://github.com/The-Swarm-Corporation/swarm-ecosystem](https://github.com/The-Swarm-Corporation/swarm-ecosystem) | +| swarms_ecosystem_md | MDX documentation for the Swarm Ecosystem. | [https://github.com/The-Swarm-Corporation/swarms_ecosystem_md](https://github.com/The-Swarm-Corporation/swarms_ecosystem_md) | +| Hierarchical Swarm Examples | Simple, practical examples of HierarchicalSwarm usage for various real-world scenarios. | [Documentation](hierarchical_swarm_example.md) | + + + + +-------------------------------------------------- + +# File: swarms\examples\unique_swarms.md In this section, we present a diverse collection of unique swarms, each with its own distinct characteristics and applications. These examples are designed to illustrate the versatility and potential of swarm intelligence in various domains. By exploring these examples, you can gain a deeper understanding of how swarms can be leveraged to solve complex problems and improve decision-making processes. @@ -19650,7 +22089,307 @@ if __name__ == "__main__": -------------------------------------------------- -# File: swarms/examples/vllm.md +# File: swarms\examples\vision_processing.md + +# Vision Processing Examples + +This example demonstrates how to use vision-enabled agents in Swarms to analyze images and process visual information. You'll learn how to work with both OpenAI and Anthropic vision models for various use cases. + +## Prerequisites + +- Python 3.7+ + +- OpenAI API key (for GPT-4V) + +- Anthropic API key (for Claude 3) + +- Swarms library + +## Installation + +```bash +pip3 install -U swarms +``` + +## Environment Variables + +```plaintext +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" # Required for GPT-4V +ANTHROPIC_API_KEY="" # Required for Claude 3 +``` + +## Working with Images + +### Supported Image Formats + +Vision-enabled agents support various image formats: + +| Format | Description | +|--------|-------------| +| JPEG/JPG | Standard image format with lossy compression | +| PNG | Lossless format supporting transparency | +| GIF | Animated format (only first frame used) | +| WebP | Modern format with both lossy and lossless compression | + +### Image Guidelines + +- Maximum file size: 20MB +- Recommended resolution: At least 512x512 pixels +- Image should be clear and well-lit +- Avoid heavily compressed or blurry images + +## Examples + +### 1. Quality Control with GPT-4V + +```python +from swarms.structs import Agent +from swarms.prompts.logistics import Quality_Control_Agent_Prompt + +# Load your image +factory_image = "path/to/your/image.jpg" # Local file path +# Or use a URL +# factory_image = "https://example.com/image.jpg" + +# Initialize quality control agent with GPT-4V +quality_control_agent = Agent( + agent_name="Quality Control Agent", + agent_description="A quality control agent that analyzes images and provides detailed quality reports.", + model_name="gpt-4.1-mini", + system_prompt=Quality_Control_Agent_Prompt, + multi_modal=True, + max_loops=1 +) + +# Run the analysis +response = quality_control_agent.run( + task="Analyze this image and provide a detailed quality control report", + img=factory_image +) + +print(response) +``` + +### 2. Visual Analysis with Claude 3 + +```python +from swarms.structs import Agent +from swarms.prompts.logistics import Visual_Analysis_Prompt + +# Load your image +product_image = "path/to/your/product.jpg" + +# Initialize visual analysis agent with Claude 3 +visual_analyst = Agent( + agent_name="Visual Analyst", + agent_description="An agent that performs detailed visual analysis of products and scenes.", + model_name="anthropic/claude-3-opus-20240229", + system_prompt=Visual_Analysis_Prompt, + multi_modal=True, + max_loops=1 +) + +# Run the analysis +response = visual_analyst.run( + task="Provide a comprehensive analysis of this product image", + img=product_image +) + +print(response) +``` + +### 3. Image Batch Processing + +```python +from swarms.structs import Agent +import os + +def process_image_batch(image_folder, agent): + """Process multiple images in a folder""" + results = [] + for image_file in os.listdir(image_folder): + if image_file.lower().endswith(('.png', '.jpg', '.jpeg', '.webp')): + image_path = os.path.join(image_folder, image_file) + response = agent.run( + task="Analyze this image", + img=image_path + ) + results.append((image_file, response)) + return results + +# Example usage +image_folder = "path/to/image/folder" +batch_results = process_image_batch(image_folder, visual_analyst) +``` + +## Best Practices + +| Category | Best Practice | Description | +|----------|---------------|-------------| +| Image Preparation | Format Support | Ensure images are in supported formats (JPEG, PNG, GIF, WebP) | +| | Size & Quality | Optimize image size and quality for better processing | +| | Image Quality | Use clear, well-lit images for accurate analysis | +| Model Selection | GPT-4V Usage | Use for general vision tasks and detailed analysis | +| | Claude 3 Usage | Use for complex reasoning and longer outputs | +| | Batch Processing | Consider batch processing for multiple images | +| Error Handling | Path Validation | Always validate image paths before processing | +| | API Error Handling | Implement proper error handling for API calls | +| | Rate Monitoring | Monitor API rate limits and token usage | +| Performance Optimization | Result Caching | Cache results when processing the same images | +| | Batch Processing | Use batch processing for multiple images | +| | Parallel Processing | Implement parallel processing for large datasets | + + + + +-------------------------------------------------- + +# File: swarms\examples\vision_tools.md + +# Agents with Vision and Tool Usage + +This tutorial demonstrates how to create intelligent agents that can analyze images and use custom tools to perform specific actions based on their visual observations. You'll learn to build a quality control agent that can process images, identify potential security concerns, and automatically trigger appropriate responses using function calling capabilities. + +## What You'll Learn + +- How to configure an agent with multi-modal capabilities for image analysis +- How to integrate custom tools and functions with vision-enabled agents +- How to implement automated security analysis based on visual observations +- How to use function calling to trigger specific actions from image analysis results +- Best practices for building production-ready vision agents with tool integration + +## Use Cases + +This approach is perfect for: + +- **Quality Control Systems**: Automated inspection of manufacturing processes + +- **Security Monitoring**: Real-time threat detection and response + +- **Object Detection**: Identifying and categorizing items in images + +- **Compliance Checking**: Ensuring standards are met in various environments + +- **Automated Reporting**: Generating detailed analysis reports from visual data + +## Installation + +Install the swarms package using pip: + +```bash +pip install -U swarms +``` + +## Basic Setup + +1. First, set up your environment variables: + +```python +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" +``` + + +## Code + +- Create tools for your agent as a function with types and documentation + +- Pass tools to your agent `Agent(tools=[list_of_callables])` + +- Add your image path to the run method like: `Agent().run(task=task, img=img)` + +```python +from swarms.structs import Agent +from swarms.prompts.logistics import ( + Quality_Control_Agent_Prompt, +) + + +# Image for analysis +factory_image = "image.jpg" + + +def security_analysis(danger_level: str) -> str: + """ + Analyzes the security danger level and returns an appropriate response. + + Args: + danger_level (str, optional): The level of danger to analyze. + Can be "low", "medium", "high", or None. Defaults to None. + + Returns: + str: A string describing the danger level assessment. + - "No danger level provided" if danger_level is None + - "No danger" if danger_level is "low" + - "Medium danger" if danger_level is "medium" + - "High danger" if danger_level is "high" + - "Unknown danger level" for any other value + """ + if danger_level is None: + return "No danger level provided" + + if danger_level == "low": + return "No danger" + + if danger_level == "medium": + return "Medium danger" + + if danger_level == "high": + return "High danger" + + return "Unknown danger level" + + +custom_system_prompt = f""" +{Quality_Control_Agent_Prompt} + +You have access to tools that can help you with your analysis. When you need to perform a security analysis, you MUST use the security_analysis function with an appropriate danger level (low, medium, or high) based on your observations. + +Always use the available tools when they are relevant to the task. If you determine there is any level of danger or security concern, call the security_analysis function with the appropriate danger level. +""" + +# Quality control agent +quality_control_agent = Agent( + agent_name="Quality Control Agent", + agent_description="A quality control agent that analyzes images and provides a detailed report on the quality of the product in the image.", + # model_name="anthropic/claude-3-opus-20240229", + model_name="gpt-4o-mini", + system_prompt=custom_system_prompt, + multi_modal=True, + max_loops=1, + output_type="str-all-except-first", + # tools_list_dictionary=[schema], + tools=[security_analysis], +) + + +response = quality_control_agent.run( + task="Analyze the image and then perform a security analysis. Based on what you see in the image, determine if there is a low, medium, or high danger level and call the security_analysis function with that danger level", + img=factory_image, +) +``` + + +## Support and Community + +If you're facing issues or want to learn more, check out the following resources to join our Discord, stay updated on Twitter, and watch tutorials on YouTube! + +| Platform | Link | Description | +|----------|------|-------------| +| 📚 Documentation | [docs.swarms.world](https://docs.swarms.world) | Official documentation and guides | +| 📝 Blog | [Medium](https://medium.com/@kyeg) | Latest updates and technical articles | +| 💬 Discord | [Join Discord](https://discord.gg/jM3Z6M9uMq) | Live chat and community support | +| 🐦 Twitter | [@kyegomez](https://twitter.com/kyegomez) | Latest news and announcements | +| 👥 LinkedIn | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | Professional network and updates | +| 📺 YouTube | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | Tutorials and demos | +| 🎫 Events | [Sign up here](https://lu.ma/5p2jnc2v) | Join our community events | + + + +-------------------------------------------------- + +# File: swarms\examples\vllm.md # VLLM Swarm Agents @@ -20084,7 +22823,7 @@ swarm.run("Analyze the best etfs for gold and other similiar commodities in vola -------------------------------------------------- -# File: swarms/examples/vllm_integration.md +# File: swarms\examples\vllm_integration.md @@ -20283,7 +23022,7 @@ result = workflow.run("Analyze the impact of renewable energy") -------------------------------------------------- -# File: swarms/examples/xai.md +# File: swarms\examples\xai.md # Agent with XAI @@ -20315,7 +23054,7 @@ agent.run("What are the components of a startup's stock incentive equity plan?") -------------------------------------------------- -# File: swarms/examples/yahoo_finance.md +# File: swarms\examples\yahoo_finance.md # Swarms Tools Example with Yahoo Finance @@ -20362,7 +23101,55 @@ agent.run("Analyze the latest metrics for nvidia") -------------------------------------------------- -# File: swarms/framework/agents_explained.md +# File: swarms\features.md + +## ✨ Enterprise Features + +Swarms delivers a comprehensive, enterprise-grade multi-agent infrastructure platform designed for production-scale deployments and seamless integration with existing systems. + +| Category | Enterprise Capabilities | Business Value | +|----------|------------------------|----------------| +| 🏢 **Enterprise Architecture** | • Production-Ready Infrastructure
• High Availability Systems
• Modular Microservices Design
• Comprehensive Observability
• Backwards Compatibility | • 99.9%+ Uptime Guarantee
• Reduced Operational Overhead
• Seamless Legacy Integration
• Enhanced System Monitoring
• Risk-Free Migration Path | +| 🤖 **Multi-Agent Orchestration** | • Hierarchical Agent Swarms
• Parallel Processing Pipelines
• Sequential Workflow Orchestration
• Graph-Based Agent Networks
• Dynamic Agent Composition
• Agent Registry Management | • Complex Business Process Automation
• Scalable Task Distribution
• Flexible Workflow Adaptation
• Optimized Resource Utilization
• Centralized Agent Governance
• Enterprise-Grade Agent Lifecycle Management | +| 🔄 **Enterprise Integration** | • Multi-Model Provider Support
• Custom Agent Development Framework
• Extensive Enterprise Tool Library
• Multiple Memory Systems
• Backwards Compatibility with LangChain, AutoGen, CrewAI
• Standardized API Interfaces | • Vendor-Agnostic Architecture
• Custom Solution Development
• Extended Functionality Integration
• Enhanced Knowledge Management
• Seamless Framework Migration
• Reduced Integration Complexity | +| 📈 **Enterprise Scalability** | • Concurrent Multi-Agent Processing
• Intelligent Resource Management
• Load Balancing & Auto-Scaling
• Horizontal Scaling Capabilities
• Performance Optimization
• Capacity Planning Tools | • High-Throughput Processing
• Cost-Effective Resource Utilization
• Elastic Scaling Based on Demand
• Linear Performance Scaling
• Optimized Response Times
• Predictable Growth Planning | +| 🛠️ **Developer Experience** | • Intuitive Enterprise API
• Comprehensive Documentation
• Active Enterprise Community
• CLI & SDK Tools
• IDE Integration Support
• Code Generation Templates | • Accelerated Development Cycles
• Reduced Learning Curve
• Expert Community Support
• Rapid Deployment Capabilities
• Enhanced Developer Productivity
• Standardized Development Patterns | +| 🔐 **Enterprise Security** | • Comprehensive Error Handling
• Advanced Rate Limiting
• Real-Time Monitoring Integration
• Detailed Audit Logging
• Role-Based Access Control
• Data Encryption & Privacy | • Enhanced System Reliability
• API Security Protection
• Proactive Issue Detection
• Regulatory Compliance Support
• Granular Access Management
• Enterprise Data Protection | +| 📊 **Advanced Enterprise Features** | • SpreadsheetSwarm for Mass Agent Management
• Group Chat for Collaborative AI
• Centralized Agent Registry
• Mixture of Agents for Complex Solutions
• Agent Performance Analytics
• Automated Agent Optimization | • Large-Scale Agent Operations
• Team-Based AI Collaboration
• Centralized Agent Governance
• Sophisticated Problem Solving
• Performance Insights & Optimization
• Continuous Agent Improvement | +| 🔌 **Provider Ecosystem** | • OpenAI Integration
• Anthropic Claude Support
• ChromaDB Vector Database
• Custom Provider Framework
• Multi-Cloud Deployment
• Hybrid Infrastructure Support | • Provider Flexibility & Independence
• Advanced Vector Search Capabilities
• Custom Integration Development
• Cloud-Agnostic Architecture
• Flexible Deployment Options
• Risk Mitigation Through Diversification | +| 💪 **Production Readiness** | • Automatic Retry Mechanisms
• Asynchronous Processing Support
• Environment Configuration Management
• Type Safety & Validation
• Health Check Endpoints
• Graceful Degradation | • Enhanced System Reliability
• Improved Performance Characteristics
• Simplified Configuration Management
• Reduced Runtime Errors
• Proactive Health Monitoring
• Continuous Service Availability | +| 🎯 **Enterprise Use Cases** | • Industry-Specific Agent Solutions
• Custom Workflow Development
• Regulatory Compliance Support
• Extensible Framework Architecture
• Multi-Tenant Support
• Enterprise SLA Guarantees | • Rapid Industry Deployment
• Flexible Solution Architecture
• Compliance-Ready Implementations
• Future-Proof Technology Investment
• Scalable Multi-Client Operations
• Predictable Service Quality | + +--- + +## 🚀 Missing a Feature? + +Swarms is continuously evolving to meet enterprise needs. If you don't see a specific feature or capability that your organization requires: + +### 📝 **Report Missing Features** + +- Create a [GitHub Issue](https://github.com/kyegomez/swarms/issues) to request new features + +- Describe your use case and business requirements + +- Our team will evaluate and prioritize based on enterprise demand + +### 📞 **Schedule a Consultation** + +- [Book a call with our enterprise team](https://cal.com/swarms/swarms-onboarding-session) for personalized guidance + +- Discuss your specific multi-agent architecture requirements + +- Get expert recommendations for your implementation strategy + +- Explore custom enterprise solutions and integrations + +Our team is committed to ensuring Swarms meets your enterprise multi-agent infrastructure needs. We welcome feedback and collaboration to build the most comprehensive platform for production-scale AI agent deployments. + + +-------------------------------------------------- + +# File: swarms\framework\agents_explained.md # An Analysis of Agents @@ -20449,7 +23236,7 @@ The Swarms framework's agents are powerful units that combine LLMs, tools, and l -------------------------------------------------- -# File: swarms/framework/code_cleanliness.md +# File: swarms\framework\code_cleanliness.md # Code Cleanliness in Python: A Comprehensive Guide @@ -20861,7 +23648,7 @@ By following the principles and best practices outlined in this article, you'll -------------------------------------------------- -# File: swarms/framework/concept.md +# File: swarms\framework\concept.md To create a comprehensive overview of the Swarms framework, we can break it down into key concepts such as models, agents, tools, Retrieval-Augmented Generation (RAG) systems, and swarm systems. Below are conceptual explanations of these components along with mermaid diagrams to illustrate their interactions. @@ -20933,7 +23720,7 @@ The Swarms framework leverages models, agents, tools, RAG systems, and swarm sys -------------------------------------------------- -# File: swarms/framework/index.md +# File: swarms\framework\index.md ## Swarms Framework Conceptual Breakdown @@ -21055,7 +23842,7 @@ This hierarchical design ensures scalability, flexibility, and robustness, makin -------------------------------------------------- -# File: swarms/framework/reference.md +# File: swarms\framework\reference.md # API Reference Documentation @@ -22480,7 +25267,7 @@ print(agent) -------------------------------------------------- -# File: swarms/framework/test.md +# File: swarms\framework\test.md # How to Run Tests Using Pytest: A Comprehensive Guide @@ -22729,7 +25516,7 @@ Happy testing! -------------------------------------------------- -# File: swarms/framework/vision.md +# File: swarms\framework\vision.md ### Swarms Vision @@ -22889,7 +25676,7 @@ Swarms promotes an open and extensible ecosystem, encouraging community-driven i -------------------------------------------------- -# File: swarms/glossary.md +# File: swarms\glossary.md # Glossary of Terms @@ -22942,7 +25729,7 @@ By understanding these terms, you can effectively build and orchestrate agents a -------------------------------------------------- -# File: swarms/install/docker_setup.md +# File: swarms\install\docker_setup.md # Docker Setup Guide for Contributors to Swarms @@ -23134,11 +25921,9 @@ Remember to secure sensitive data, use tagged releases for your images, and foll -------------------------------------------------- -# File: swarms/install/env.md +# File: swarms\install\env.md -# Environment Variable Management & Security - -This guide provides comprehensive documentation for managing environment variables and API keys securely in the Swarms framework. +# Environment Variables ## Overview @@ -23148,80 +25933,106 @@ Swarms uses environment variables for configuration management and secure creden ### Framework Configuration -- `SWARMS_VERBOSE_GLOBAL`: Controls global logging verbosity - ```bash - SWARMS_VERBOSE_GLOBAL="True" # Enable verbose logging - SWARMS_VERBOSE_GLOBAL="False" # Disable verbose logging - ``` +=== "Configuration Variables" -- `WORKSPACE_DIR`: Defines the workspace directory for agent operations - ```bash - WORKSPACE_DIR="agent_workspace" - ``` + | Variable | Description | Example | + |----------|-------------|---------| + | `SWARMS_VERBOSE_GLOBAL` | Controls global logging verbosity | `True` or `False` | + | `WORKSPACE_DIR` | Defines the workspace directory for agent operations | `agent_workspace` | -### API Keys +### LLM Provider API Keys -#### Model Provider Keys +=== "OpenAI" + ```bash + OPENAI_API_KEY="your-openai-key" + ``` -1. **OpenAI** - - `OPENAI_API_KEY`: Authentication for GPT models - ```bash - OPENAI_API_KEY="your-openai-key" - ``` +=== "Anthropic" + ```bash + ANTHROPIC_API_KEY="your-anthropic-key" + ``` -2. **Anthropic** - - `ANTHROPIC_API_KEY`: Authentication for Claude models - ```bash - ANTHROPIC_API_KEY="your-anthropic-key" - ``` +=== "Groq" + ```bash + GROQ_API_KEY="your-groq-key" + ``` -3. **Google** - - `GEMINI_API_KEY`: Authentication for Gemini models +=== "Google" + ```bash + GEMINI_API_KEY="your-gemini-key" + ``` -4. **Hugging Face** - - `HUGGINGFACE_TOKEN`: Access to Hugging Face models +=== "Hugging Face" + ```bash + HUGGINGFACE_TOKEN="your-huggingface-token" + ``` -5. **Perplexity AI** - - `PPLX_API_KEY`: Access to Perplexity models +=== "Perplexity AI" + ```bash + PPLX_API_KEY="your-perplexity-key" + ``` -6. **AI21** - - `AI21_API_KEY`: Access to AI21 models +=== "AI21" + ```bash + AI21_API_KEY="your-ai21-key" + ``` -#### Tool Provider Keys +=== "Cohere" + ```bash + COHERE_API_KEY="your-cohere-key" + ``` -1. **Search Tools** - - `BING_BROWSER_API`: Bing search capabilities - - `BRAVESEARCH_API_KEY`: Brave search integration - - `TAVILY_API_KEY`: Tavily search services - - `YOU_API_KEY`: You.com search integration +=== "Mistral AI" + ```bash + MISTRAL_API_KEY="your-mistral-key" + ``` -2. **Analytics & Monitoring** - - `EXA_API_KEY`: Exa.ai services +=== "Together AI" + ```bash + TOGETHER_API_KEY="your-together-key" + ``` -3. **Browser Automation** - - `MULTION_API_KEY`: Multi-browser automation +### Tool Provider Keys + +=== "Search Tools" + ```bash + BING_BROWSER_API="your-bing-key" + BRAVESEARCH_API_KEY="your-brave-key" + TAVILY_API_KEY="your-tavily-key" + YOU_API_KEY="your-you-key" + ``` + +=== "Analytics & Monitoring" + ```bash + EXA_API_KEY="your-exa-key" + ``` + +=== "Browser Automation" + ```bash + MULTION_API_KEY="your-multion-key" + ``` - ## Security Best Practices -### 1. Environment File Management +### Environment File Management -- Create a `.env` file in your project root -- Never commit `.env` files to version control -- Add `.env` to your `.gitignore`: - ```bash - echo ".env" >> .gitignore - ``` +1. Create a `.env` file in your project root +2. Never commit `.env` files to version control +3. Add `.env` to your `.gitignore`: + ```bash + echo ".env" >> .gitignore + ``` -### 2. API Key Security +### API Key Security -- Rotate API keys regularly -- Use different API keys for development and production -- Never hardcode API keys in your code -- Limit API key permissions to only what's necessary -- Monitor API key usage for unusual patterns +!!! warning "Important Security Considerations" + - Rotate API keys regularly + - Use different API keys for development and production + - Never hardcode API keys in your code + - Limit API key permissions to only what's necessary + - Monitor API key usage for unusual patterns -### 3. Template Configuration +### Template Configuration Create a `.env.example` template without actual values: @@ -23229,13 +26040,14 @@ Create a `.env.example` template without actual values: # Required Configuration OPENAI_API_KEY="" ANTHROPIC_API_KEY="" +GROQ_API_KEY="" WORKSPACE_DIR="agent_workspace" # Optional Configuration SWARMS_VERBOSE_GLOBAL="False" ``` -### 4. Loading Environment Variables +### Loading Environment Variables ```python from dotenv import load_dotenv @@ -23251,83 +26063,73 @@ openai_key = os.getenv("OPENAI_API_KEY") ## Environment Setup Guide -1. **Install Dependencies**: - ```bash - pip install python-dotenv - ``` +=== "1. Install Dependencies" + ```bash + pip install python-dotenv + ``` -2. **Create Environment File**: - ```bash - cp .env.example .env - ``` +=== "2. Create Environment File" + ```bash + cp .env.example .env + ``` -3. **Configure Variables**: - - Open `.env` in your text editor - - Add your API keys and configuration - - Save the file +=== "3. Configure Variables" + - Open `.env` in your text editor + - Add your API keys and configuration + - Save the file -4. **Verify Setup**: - ```python - import os - from dotenv import load_dotenv +=== "4. Verify Setup" + ```python + import os + from dotenv import load_dotenv - load_dotenv() - assert os.getenv("OPENAI_API_KEY") is not None, "OpenAI API key not found" - ``` + load_dotenv() + assert os.getenv("OPENAI_API_KEY") is not None, "OpenAI API key not found" + ``` ## Environment-Specific Configuration -### Development - -```bash -WORKSPACE_DIR="agent_workspace" -SWARMS_VERBOSE_GLOBAL="True" -``` - -### Production - -```bash -WORKSPACE_DIR="/var/swarms/workspace" -SWARMS_VERBOSE_GLOBAL="False" -``` +=== "Development" + ```bash + WORKSPACE_DIR="agent_workspace" + SWARMS_VERBOSE_GLOBAL="True" + ``` -### Testing +=== "Production" + ```bash + WORKSPACE_DIR="/var/swarms/workspace" + SWARMS_VERBOSE_GLOBAL="False" + ``` -```bash -WORKSPACE_DIR="test_workspace" -SWARMS_VERBOSE_GLOBAL="True" -``` +=== "Testing" + ```bash + WORKSPACE_DIR="test_workspace" + SWARMS_VERBOSE_GLOBAL="True" + ``` ## Troubleshooting ### Common Issues -1. **Environment Variables Not Loading** - - Verify `.env` file exists in project root - - Confirm `load_dotenv()` is called before accessing variables - - Check file permissions - -2. **API Key Issues** - - Verify key format is correct - - Ensure key has not expired - - Check for leading/trailing whitespace +???+ note "Environment Variables Not Loading" + - Verify `.env` file exists in project root + - Confirm `load_dotenv()` is called before accessing variables + - Check file permissions -3. **Workspace Directory Problems** - - Confirm directory exists - - Verify write permissions - - Check path is absolute when required - -## Additional Resources - -- [Swarms Documentation](https://docs.swarms.world) -- [Security Best Practices](https://swarms.world/security) -- [API Documentation](https://swarms.world/docs/api) +???+ note "API Key Issues" + - Verify key format is correct + - Ensure key has not expired + - Check for leading/trailing whitespace +???+ note "Workspace Directory Problems" + - Confirm directory exists + - Verify write permissions + - Check path is absolute when required -------------------------------------------------- -# File: swarms/install/install.md +# File: swarms\install\install.md # Swarms Installation Guide @@ -23365,6 +26167,37 @@ Before you begin, ensure you have the following installed: pip install swarms ``` +=== "UV Installation" + + UV is a fast Python package installer and resolver written in Rust. It's significantly faster than pip and provides better dependency resolution. + + === "Basic Installation" + + ```bash + # Install UV first + curl -LsSf https://astral.sh/uv/install.sh | sh + + # Install swarms using UV + uv pip install swarms + ``` + + === "Development Installation" + + ```bash + # Clone the repository + git clone https://github.com/kyegomez/swarms.git + cd swarms + + # Install in editable mode + uv pip install -e . + ``` + + For desktop installation with extras: + + ```bash + uv pip install -e .[desktop] + ``` + === "Development Installation" === "Using virtualenv" @@ -23617,20 +26450,22 @@ Before you begin, ensure you have the following installed: } ``` -## Javascript +## Rust -=== "NPM install (Work in Progress)" +=== "Cargo install" - Get started with the NPM implementation of Swarms: + Get started with the Rust implementation of Swarms. [Get started with the docs here](https://docs.swarms.world/en/latest/swarms_rs/overview/) ```bash - npm install swarms-js + cargo add swarms-rs ``` + + -------------------------------------------------- -# File: swarms/install/quickstart.md +# File: swarms\install\quickstart.md ## Quickstart @@ -23654,35 +26489,27 @@ $ pip install -U swarms ### **Usage Example: Single Agent** -Here’s a simple example of creating a financial analysis agent powered by OpenAI’s GPT-4 model. This agent will analyze financial queries like how to set up a ROTH IRA. +Here's a simple example of creating a financial analysis agent powered by OpenAI's GPT-4o-mini model. This agent will analyze financial queries like how to set up a ROTH IRA. ```python -import os -from swarms import Agent -from swarm_models import OpenAIChat -from dotenv import load_dotenv - -load_dotenv() - -# Initialize OpenAI model -model = OpenAIChat( - openai_api_key=os.getenv("OPENAI_API_KEY"), model_name="gpt-4o-mini", temperature=0.1 -) +from swarms.structs.agent import Agent -# Initialize the agent +# Initialize the agent with GPT-4o-mini model agent = Agent( agent_name="Financial-Analysis-Agent", system_prompt="Analyze financial situations and provide advice...", - llm=model, max_loops=1, autosave=True, dashboard=False, verbose=True, - saved_state_path="finance_agent.json" + saved_state_path="finance_agent.json", + model_name="gpt-4o-mini", ) -# Run the agent on a financial query -out = agent.run("How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?") +# Run your query +out = agent.run( + "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?" +) print(out) ``` @@ -23691,13 +26518,13 @@ print(out) - **Attributes:** - `agent_name`: Name of the agent. - `system_prompt`: System-level instruction guiding the agent's behavior. - - `llm`: Language model used by the agent (e.g., GPT, Anthropic). + - `model_name`: Name of the model to use (e.g., "gpt-4o-mini"). - `max_loops`: Max iterations for a task. - `autosave`: Auto-saves the state after each iteration. - **Methods:** - - `run(task: str)`: Executes the agent’s task. - - `ingest_docs(doc_path: str)`: Ingests documents into the agent’s knowledge base. + - `run(task: str)`: Executes the agent's task. + - `ingest_docs(doc_path: str)`: Ingests documents into the agent's knowledge base. - `filtered_run(task: str)`: Runs agent with a filtered system prompt. ----- @@ -23712,51 +26539,55 @@ The `create_agents_from_yaml` function works by reading agent configurations fro ```yaml agents: - agent_name: "Financial-Analysis-Agent" - model: - openai_api_key: "your_openai_api_key" - model_name: "gpt-4o-mini" - temperature: 0.1 - max_tokens: 2000 - system_prompt: "financial_agent_sys_prompt" + system_prompt: "You are a financial analysis expert. Analyze market trends and provide investment recommendations." + model_name: "claude-3-opus-20240229" max_loops: 1 - autosave: true + autosave: false dashboard: false - verbose: true - dynamic_temperature_enabled: true - saved_state_path: "finance_agent.json" + verbose: false + dynamic_temperature_enabled: false user_name: "swarms_corp" retry_attempts: 1 context_length: 200000 return_step_meta: false output_type: "str" - task: "How can I establish a ROTH IRA to buy stocks and get a tax break?" + temperature: 0.1 + max_tokens: 2000 + task: "Analyze tech stocks for 2024 investment strategy. Provide detailed analysis and recommendations." - - agent_name: "Stock-Analysis-Agent" - model: - openai_api_key: "your_openai_api_key" - model_name: "gpt-4o-mini" - temperature: 0.2 - max_tokens: 1500 - system_prompt: "stock_agent_sys_prompt" - max_loops: 2 - autosave: true + - agent_name: "Risk-Analysis-Agent" + system_prompt: "You are a risk analysis expert. Evaluate investment risks and provide mitigation strategies." + model_name: "claude-3-opus-20240229" + max_loops: 1 + autosave: false dashboard: false - verbose: true + verbose: false dynamic_temperature_enabled: false - saved_state_path: "stock_agent.json" - user_name: "stock_user" - retry_attempts: 3 + user_name: "swarms_corp" + retry_attempts: 1 context_length: 150000 - return_step_meta: true - output_type: "json" - task: "What is the best strategy for long-term stock investment?" + return_step_meta: false + output_type: "str" + temperature: 0.1 + max_tokens: 2000 + task: "Conduct a comprehensive risk analysis of the top 5 tech companies in 2024. Include risk factors and mitigation strategies." + +swarm_architecture: + name: "Financial Analysis Swarm" + description: "A swarm for comprehensive financial and risk analysis" + max_loops: 1 + swarm_type: "SequentialWorkflow" + task: "Analyze tech stocks and their associated risks for 2024 investment strategy" + autosave: false + return_json: true ``` ### Key Configuration Fields: - **agent_name**: Name of the agent. -- **model**: Defines the language model settings (e.g., API key, model name, temperature, and max tokens). -- **system_prompt**: The system prompt used to guide the agent’s behavior. -- **task**: (Optional) Task for the agent to execute once created. +- **system_prompt**: The system prompt used to guide the agent's behavior. +- **model_name**: The language model to use (e.g., claude-3-opus-20240229). +- **task**: Task for the agent to execute. +- **swarm_architecture**: (Optional) Configuration for swarm behavior. --- @@ -23766,41 +26597,15 @@ Now, create the main Python script that will use the `create_agents_from_yaml` f ### `main.py`: ```python -import os - -from dotenv import load_dotenv -from loguru import logger -from swarm_models import OpenAIChat - -from swarms.agents.create_agents_from_yaml import ( - create_agents_from_yaml, -) - -# Load environment variables -load_dotenv() - -# Path to your YAML file -yaml_file = "agents.yaml" - -# Get the OpenAI API key from the environment variable -api_key = os.getenv("OPENAI_API_KEY") +from swarms.agents.create_agents_from_yaml import create_agents_from_yaml -# Create an instance of the OpenAIChat class -model = OpenAIChat( - openai_api_key=api_key, model_name="gpt-4o-mini", temperature=0.1 +# Create agents and get task results +task_results = create_agents_from_yaml( + yaml_file="agents_config.yaml", + return_type="run_swarm" ) - -try: - # Create agents and run tasks (using 'both' to return agents and task results) - task_results = create_agents_from_yaml( - model=model, yaml_file=yaml_file, return_type="tasks" - ) - - logger.info(f"Results from agents: {task_results}") -except Exception as e: - logger.error(f"An error occurred: {e}") - +print(task_results) ``` ### Example Run: @@ -23882,7 +26687,7 @@ Steps: For example, here's an example on how to create an agent from griptape. -Here’s how you can create a custom **Griptape** agent that integrates with the **Swarms** framework by inheriting from the `Agent` class in **Swarms** and overriding the `run(task: str) -> str` method. +Here's how you can create a custom **Griptape** agent that integrates with the **Swarms** framework by inheriting from the `Agent` class in **Swarms** and overriding the `run(task: str) -> str` method. ```python @@ -23964,11 +26769,20 @@ graph TD; ```python from swarms import Agent, SequentialWorkflow -from swarm_models import Anthropic -# Initialize agents -agent1 = Agent(agent_name="Blog generator", system_prompt="Generate a blog post", llm=Anthropic(), max_loops=1) -agent2 = Agent(agent_name="Summarizer", system_prompt="Summarize the blog post", llm=Anthropic(), max_loops=1) +# Initialize agents without importing a specific LLM class +agent1 = Agent( + agent_name="Blog generator", + system_prompt="Generate a blog post", + model_name="claude-3-sonnet-20240229", + max_loops=1 +) +agent2 = Agent( + agent_name="Summarizer", + system_prompt="Summarize the blog post", + model_name="claude-3-sonnet-20240229", + max_loops=1 +) # Create Sequential workflow workflow = SequentialWorkflow(agents=[agent1, agent2], max_loops=1) @@ -23998,23 +26812,37 @@ graph TD; ```python from swarms import Agent, AgentRearrange -from swarm_models import Anthropic -# Initialize agents -director = Agent(agent_name="Director", system_prompt="Directs tasks", llm=Anthropic(), max_loops=1) -worker1 = Agent(agent_name="Worker1", system_prompt="Generate a transcript", llm=Anthropic(), max_loops=1) -worker2 = Agent(agent_name="Worker2", system_prompt="Summarize the transcript", llm=Anthropic(), max_loops=1) +# Initialize agents using model_name (no explicit LLM import) +director = Agent( + agent_name="Director", + system_prompt="Directs tasks", + model_name="claude-3-sonnet-20240229", + max_loops=1 +) +worker1 = Agent( + agent_name="Worker1", + system_prompt="Generate a transcript", + model_name="claude-3-sonnet-20240229", + max_loops=1 +) +worker2 = Agent( + agent_name="Worker2", + system_prompt="Summarize the transcript", + model_name="claude-3-sonnet-20240229", + max_loops=1 +) -# Define agent relationships and workflow +# Define the flow and create the rearranged system flow = "Director -> Worker1 -> Worker2" agent_system = AgentRearrange(agents=[director, worker1, worker2], flow=flow) -# Run agent system +# Run it output = agent_system.run("Create a YouTube transcript and summary") print(output) ``` ---- + --- @@ -24054,7 +26882,7 @@ print(output) ### 5. **Spreadsheet Swarm** -**Overview**: `SpreadSheetSwarm` enables the management of thousands of agents simultaneously, where each agent operates on its own thread. It’s ideal for overseeing large-scale agent outputs. +**Overview**: `SpreadSheetSwarm` enables the management of thousands of agents simultaneously, where each agent operates on its own thread. It's ideal for overseeing large-scale agent outputs. #### Mermaid Graph: @@ -24071,21 +26899,49 @@ graph TD; ```python from swarms import Agent -from swarm_models import OpenAIChat from swarms.structs.spreadsheet_swarm import SpreadSheetSwarm -import os -# Initialize agents for different marketing platforms +# Initialize agents for different marketing platforms using model_name agents = [ - Agent(agent_name="Twitter Agent", system_prompt="Create a tweet", llm=OpenAIChat(openai_api_key=os.getenv("OPENAI_API_KEY")), max_loops=1), - Agent(agent_name="Instagram Agent", system_prompt="Create an Instagram post", llm=OpenAIChat(openai_api_key=os.getenv("OPENAI_API_KEY")), max_loops=1), - Agent(agent_name="Facebook Agent", system_prompt="Create a Facebook post", llm=OpenAIChat(openai_api_key=os.getenv("OPENAI_API_KEY")), max_loops=1), - Agent(agent_name="LinkedIn Agent", system_prompt="Create a LinkedIn post", llm=OpenAIChat(openai_api_key=os.getenv("OPENAI_API_KEY")), max_loops=1), - Agent(agent_name="Email Agent", system_prompt="Write a marketing email", llm=OpenAIChat(openai_api_key=os.getenv("OPENAI_API_KEY")), max_loops=1), + Agent( + agent_name="Twitter Agent", + system_prompt="Create a tweet", + model_name="gpt-4o-mini", + max_loops=1 + ), + Agent( + agent_name="Instagram Agent", + system_prompt="Create an Instagram post", + model_name="gpt-4o-mini", + max_loops=1 + ), + Agent( + agent_name="Facebook Agent", + system_prompt="Create a Facebook post", + model_name="gpt-4o-mini", + max_loops=1 + ), + Agent( + agent_name="LinkedIn Agent", + system_prompt="Create a LinkedIn post", + model_name="gpt-4o-mini", + max_loops=1 + ), + Agent( + agent_name="Email Agent", + system_prompt="Write a marketing email", + model_name="gpt-4o-mini", + max_loops=1 + ), ] # Create the Spreadsheet Swarm -swarm = SpreadSheetSwarm(agents=agents, save_file_path="real_estate_marketing_spreadsheet.csv", run_all_agents=False, max_loops=2) +swarm = SpreadSheetSwarm( + agents=agents, + save_file_path="real_estate_marketing_spreadsheet.csv", + run_all_agents=False, + max_loops=2 +) # Run the swarm swarm.run("Create posts to promote luxury properties in North Texas.") @@ -24100,7 +26956,7 @@ These are the key swarm architectures available in the **Swarms Framework**. Eac #### **Workflow Classes** - **SequentialWorkflow:** - - Chains agents, where one agent's output becomes the next agent’s input. + - Chains agents, where one agent's output becomes the next agent's input. - **AgentRearrange:** - Dynamically rearranges agent tasks either in parallel or sequentially based on defined flow. @@ -24117,7 +26973,7 @@ These are the key swarm architectures available in the **Swarms Framework**. Eac -------------------------------------------------- -# File: swarms/install/workspace_manager.md +# File: swarms\install\workspace_manager.md # Swarms Framework Environment Configuration @@ -24308,7 +27164,7 @@ Common issues and solutions: -------------------------------------------------- -# File: swarms/memory/diy_memory.md +# File: swarms\memory\diy_memory.md # Integrating the Agent Class with Memory Systems/RAG in the Swarms Memory Framework @@ -24329,30 +27185,28 @@ ChromaDB is a simple, high-performance vector store for use with embeddings. Her ```python from swarms_memory import ChromaDB -from swarms import Agent -from swarm_models import Anthropic -import os +from swarms.structs.agent import Agent -# Initialize the ChromaDB client +# Initialize ChromaDB memory chromadb_memory = ChromaDB( metric="cosine", output_dir="finance_agent_rag", ) -# Model -model = Anthropic(anthropic_api_key=os.getenv("ANTHROPIC_API_KEY")) - -# Initialize the agent with ChromaDB memory +# Initialize the Financial Analysis Agent with GPT-4o-mini model agent = Agent( agent_name="Financial-Analysis-Agent", system_prompt="Agent system prompt here", agent_description="Agent performs financial analysis.", - llm=model, + model_name="gpt-4o-mini", long_term_memory=chromadb_memory, ) # Run a query -agent.run("What are the components of a startup's stock incentive equity plan?") +response = agent.run( + "What are the components of a startup's stock incentive equity plan?" +) +print(response) ``` ### Integrating Faiss with the Agent Class @@ -24435,1693 +27289,1695 @@ Happy coding! -------------------------------------------------- -# File: swarms/models/anthropic.md +# File: swarms\papers.md -# **Documentation for the `Anthropic` Class** +# awesome-multi-agent-papers -## **Overview and Introduction** +An awesome list of multi-agent papers that show you various swarm architectures and much more. [Get started](https://github.com/kyegomez/awesome-multi-agent-papers) -The `Anthropic` class provides an interface to interact with the Anthropic large language models. This class encapsulates the necessary functionality to request completions from the Anthropic API based on a provided prompt and other configurable parameters. +-------------------------------------------------- -### **Key Concepts and Terminology** +# File: swarms\products.md -- **Anthropic**: A large language model, akin to GPT-3 and its successors. -- **Prompt**: A piece of text that serves as the starting point for model completions. -- **Stop Sequences**: Specific tokens or sequences to indicate when the model should stop generating. -- **Tokens**: Discrete pieces of information in a text. For example, in English, a token can be as short as one character or as long as one word. - -## **Class Definition** +# Swarms Products -### `Anthropic` -```python -class Anthropic: - """Anthropic large language models.""" -``` +Welcome to the official documentation for **Swarms**, the first multi-agent orchestration framework enabling seamless collaboration between LLMs and other tools to automate business operations at scale. Below, you’ll find detailed descriptions of all Swarms products and services to help you get started and unlock the full potential of this groundbreaking platform. -### Parameters: -- `model (str)`: The name of the model to use for completions. Default is "claude-2". - -- `max_tokens_to_sample (int)`: Maximum number of tokens to generate in the output. Default is 256. - -- `temperature (float, optional)`: Sampling temperature. A higher value will make the output more random, while a lower value will make it more deterministic. - -- `top_k (int, optional)`: Sample from the top-k most probable next tokens. Setting this parameter can reduce randomness in the output. - -- `top_p (float, optional)`: Sample from the smallest set of tokens such that their cumulative probability exceeds the specified value. Used in nucleus sampling to provide a balance between randomness and determinism. - -- `streaming (bool)`: Whether to stream the output or not. Default is False. - -- `default_request_timeout (int, optional)`: Default timeout in seconds for API requests. Default is 600. -### **Methods and their Functionality** +| **Name** | **Description** | **Link** | +|-----------------------|-------------------------------------------------------------------------------------------------------------------|---------------------------| +| **Swarms Marketplace** | A platform to discover, share, and integrate prompts, agents, and tools. | [swarms.world](https://swarms.world) | +| **Swarms Spreadsheet** | A tool for managing and scaling thousands of agent outputs, with results saved to a CSV file for easy analysis. | [swarms.world](https://swarms.world) | +| **Drag n Drop Swarm** | An intuitive interface to visually create and manage swarms of agents through drag-and-drop functionality. | [swarms.world](https://swarms.world) | +| **Swarms API** | An API enabling seamless integration of swarms of agents into your applications and workflows. | [swarms.world](https://swarms.world) | +| **Wallet API** | A secure API for managing transactions and interactions within the Swarms ecosystem. | Coming Soon | +| **Swarm Exchange** | A marketplace for buying and selling prompts, agents, and tools within the Swarms ecosystem. | Coming Soon | -#### `_default_params(self) -> dict` -- Provides the default parameters for calling the Anthropic API. - -- **Returns**: A dictionary containing the default parameters. -#### `generate(self, prompt: str, stop: list[str] = None) -> str` +--- -- Calls out to Anthropic's completion endpoint to generate text based on the given prompt. - -- **Parameters**: - - `prompt (str)`: The input text to provide context for the generated text. - - - `stop (list[str], optional)`: Sequences to indicate when the model should stop generating. - -- **Returns**: A string containing the model's generated completion based on the prompt. +## Swarms Marketplace +**Website:** [swarms.world](https://swarms.world) -#### `__call__(self, prompt: str, stop: list[str] = None) -> str` +The Swarms Marketplace is your one-stop destination for discovering, adding, and managing: -- An alternative to the `generate` method that allows calling the class instance directly. - -- **Parameters**: - - `prompt (str)`: The input text to provide context for the generated text. - - - `stop (list[str], optional)`: Sequences to indicate when the model should stop generating. - -- **Returns**: A string containing the model's generated completion based on the prompt. +- **Prompts:** Access and share production-ready prompts for LLMs. -## **Usage Examples** +- **Agents:** Browse pre-built agents tailored for tasks in marketing, finance, +programming, and more. +- **Tools:** Discover cutting-edge tools to enhance agent performance and expand +capabilities. -```python -# Import necessary modules and classes -from swarm_models import Anthropic +### Key Features: +- **Rating System:** Evaluate and rate prompts, agents, and tools based on their +effectiveness. +- **Commenting System:** Share feedback and insights with the Swarms community. -# Initialize an instance of the Anthropic class -model = Anthropic(anthropic_api_key="") +- **Coming Soon:** Buy and sell prompts, agents, and tools directly within the +marketplace. -# Using the run method -completion_1 = model.run("What is the capital of France?") -print(completion_1) +### How to Use: +1. Sign up at [swarms.world](https://swarms.world). +2. Explore the marketplace categories or search for specific solutions. +3. Add your chosen resources to your Swarms account and integrate them into your operations. -# Using the __call__ method -completion_2 = model("How far is the moon from the earth?", stop=["miles", "km"]) -print(completion_2) -``` +--- -## **Mathematical Formula** +## Swarms Spreadsheet +**Website:** [swarms.world](https://swarms.world) -The underlying operations of the `Anthropic` class involve probabilistic sampling based on token logits from the Anthropic model. Mathematically, the process of generating a token \( t \) from the given logits \( l \) can be described by the softmax function: +The Swarms Spreadsheet is a powerful tool for managing outputs from thousands of agents efficiently. Ideal for businesses needing scalable solutions, it provides: -\[ P(t) = \frac{e^{l_t}}{\sum_{i} e^{l_i}} \] +### Key Features: +- **Batch Task Execution:** Assign tasks to multiple agents simultaneously. -Where: -- \( P(t) \) is the probability of token \( t \). -- \( l_t \) is the logit corresponding to token \( t \). -- The summation runs over all possible tokens. +- **CSV Integration:** Automatically save agent outputs to CSV files for easy analysis. -The temperature, top-k, and top-p parameters are further used to modulate the probabilities. +- **Customizable Agents:** Upload single or multiple agents and run repeat tasks with +ease. +- **Metadata Capture:** Leverage built-in Pydantic schemas to record all task details +and results. -## **Additional Information and Tips** +### Use Cases: +- **Marketing:** Generate and analyze campaign ideas at scale. -- Ensure you have a valid `ANTHROPIC_API_KEY` set as an environment variable or passed during class instantiation. - -- Always handle exceptions that may arise from API timeouts or invalid prompts. +- **Finance:** Process financial models and scenarios quickly. -## **References and Resources** +- **Operations:** Automate repetitive tasks across multiple domains. -- [Anthropic's official documentation](https://www.anthropic.com/docs) - -- [Token-based sampling in Language Models](https://arxiv.org/abs/1904.09751) for a deeper understanding of token sampling. --------------------------------------------------- +### How to Use: +1. Visit [swarms.world](https://swarms.world) and navigate to Swarms Spreadsheet. +2. Upload your agents or create new ones. +3. Run tasks and export results to a CSV file for further use. -# File: swarms/models/base_llm.md +--- -# Language Model Interface Documentation +## Drag-n-Drop Swarm +**Website:** [swarms.world](https://swarms.world) -## Table of Contents +The Drag-n-Drop Swarm enables non-technical users to create and deploy agent workflows with a simple drag-and-drop interface. It’s perfect for: -1. [Introduction](#introduction) -2. [Abstract Language Model](#abstract-language-model) - - [Initialization](#initialization) - - [Attributes](#attributes) - - [Methods](#methods) -3. [Implementation](#implementation) -4. [Usage Examples](#usage-examples) -5. [Additional Features](#additional-features) -6. [Performance Metrics](#performance-metrics) -7. [Logging and Checkpoints](#logging-and-checkpoints) -8. [Resource Utilization Tracking](#resource-utilization-tracking) -9. [Conclusion](#conclusion) +### Key Features: +- **Visual Workflow Builder:** Design agent interactions without writing code. + +- **Pre-Built Templates:** Start quickly with ready-made workflows for common tasks. + +- **Intuitive Interface:** Drag, drop, and connect agents to create robust automation +pipelines. + +### How to Use: +1. Access the Drag-n-Drop Swarm tool at [swarms.world](https://swarms.world). +2. Drag agents from the library into the workspace. +3. Connect and configure agents to execute your desired workflow. +4. Save and deploy your workflow instantly. --- -## 1. Introduction +## Swarms API +**Website:** [swarms.world](https://swarms.world) -The Language Model Interface (`BaseLLM`) is a flexible and extensible framework for working with various language models. This documentation provides a comprehensive guide to the interface, its attributes, methods, and usage examples. Whether you're using a pre-trained language model or building your own, this interface can help streamline the process of text generation, chatbots, summarization, and more. +The Swarms API provides developers with the ability to: -## 2. Abstract Language Model +### Key Features: +- **Agent Management:** Programmatically create, update, and delete agents. -### Initialization +- **Task Orchestration:** Dynamically assign tasks to agents and monitor their progress. -The `BaseLLM` class provides a common interface for language models. It can be initialized with various parameters to customize model behavior. Here are the initialization parameters: +- **Custom Integration:** Seamlessly integrate Swarms functionality into existing +applications and workflows. -| Parameter | Description | Default Value | -|------------------------|-------------------------------------------------------------------------------------------------|---------------| -| `model_name` | The name of the language model to use. | None | -| `max_tokens` | The maximum number of tokens in the generated text. | None | -| `temperature` | The temperature parameter for controlling randomness in text generation. | None | -| `top_k` | The top-k parameter for filtering words in text generation. | None | -| `top_p` | The top-p parameter for filtering words in text generation. | None | -| `system_prompt` | A system-level prompt to set context for generation. | None | -| `beam_width` | The beam width for beam search. | None | -| `num_return_sequences` | The number of sequences to return in the output. | None | -| `seed` | The random seed for reproducibility. | None | -| `frequency_penalty` | The frequency penalty parameter for promoting word diversity. | None | -| `presence_penalty` | The presence penalty parameter for discouraging repetitions. | None | -| `stop_token` | A stop token to indicate the end of generated text. | None | -| `length_penalty` | The length penalty parameter for controlling the output length. | None | -| `role` | The role of the language model (e.g., assistant, user, etc.). | None | -| `max_length` | The maximum length of generated sequences. | None | -| `do_sample` | Whether to use sampling during text generation. | None | -| `early_stopping` | Whether to use early stopping during text generation. | None | -| `num_beams` | The number of beams to use in beam search. | None | -| `repition_penalty` | The repetition penalty parameter for discouraging repeated tokens. | None | -| `pad_token_id` | The token ID for padding. | None | -| `eos_token_id` | The token ID for the end of a sequence. | None | -| `bos_token_id` | The token ID for the beginning of a sequence. | None | -| `device` | The device to run the model on (e.g., 'cpu' or 'cuda'). | None | +### Getting Started: +1. Sign up for API access at [swarms.world](https://swarms.world). +2. Obtain your API key and authentication credentials. +3. Refer to the API documentation for endpoint details and usage examples. -### Attributes +--- -- `model_name`: The name of the language model being used. -- `max_tokens`: The maximum number of tokens in generated text. -- `temperature`: The temperature parameter controlling randomness. -- `top_k`: The top-k parameter for word filtering. -- `top_p`: The top-p parameter for word filtering. -- `system_prompt`: A system-level prompt for context. -- `beam_width`: The beam width for beam search. -- `num_return_sequences`: The number of output sequences. -- `seed`: The random seed for reproducibility. -- `frequency_penalty`: The frequency penalty parameter. -- `presence_penalty`: The presence penalty parameter. -- `stop_token`: The stop token to indicate text end. -- `length_penalty`: The length penalty parameter. -- `role`: The role of the language model. -- `max_length`: The maximum length of generated sequences. -- `do_sample`: Whether to use sampling during generation. -- `early_stopping`: Whether to use early stopping. -- `num_beams`: The number of beams in beam search. -- `repition_penalty`: The repetition penalty parameter. -- `pad_token_id`: The token ID for padding. -- `eos_token_id`: The token ID for the end of a sequence. -- `bos_token_id`: The token ID for the beginning of a sequence. -- `device`: The device used for model execution. -- `history`: A list of conversation history. +## Wallet API +The Wallet API enables secure and efficient transactions within the Swarms ecosystem, allowing users to: -### Methods +### Key Features: +- **Seamless Transactions:** Manage payments for prompts, agents, and tools. -The `BaseLLM` class defines several methods for working with language models: +- **Secure Wallets:** Store and transfer funds safely within the Swarms platform. -- `run(task: Optional[str] = None, *args, **kwargs) -> str`: Generate text using the language model. This method is abstract and must be implemented by subclasses. +- **Transaction History:** Access detailed logs of all wallet activity. -- `arun(task: Optional[str] = None, *args, **kwargs)`: An asynchronous version of `run` for concurrent text generation. -- `batch_run(tasks: List[str], *args, **kwargs)`: Generate text for a batch of tasks. +### Getting Started: +1. Enable your wallet in your Swarms account settings. +2. Use the Wallet API to handle purchases and manage funds. -- `abatch_run(tasks: List[str], *args, **kwargs)`: An asynchronous version of `batch_run` for concurrent batch generation. +--- -- `chat(task: str, history: str = "") -> str`: Conduct a chat with the model, providing a conversation history. +## Swarm Exchange (Coming Soon) +The **Swarm Exchange** will revolutionize the way agents and tools are traded in the Swarms ecosystem. It will feature: -- `__call__(task: str) -> str`: Call the model to generate text. +### Key Features: +- **Decentralized Marketplace:** Trade agents and tools securely. -- `_tokens_per_second() -> float`: Calculate tokens generated per second. +- **Dynamic Pricing:** Leverage demand-based pricing for assets. -- `_num_tokens(text: str) -> int`: Calculate the number of tokens in a text. +- **Global Access:** Participate in the exchange from anywhere. -- `_time_for_generation(task: str) -> float`: Measure the time taken for text generation. -- `generate_summary(text: str) -> str`: Generate a summary of the provided text. +Stay tuned for updates on the Swarm Exchange launch. -- `set_temperature(value: float)`: Set the temperature parameter. +--- -- `set_max_tokens(value: int)`: Set the maximum number of tokens. +## Additional Resources +- **GitHub Repository:** [Swarms Framework](https://github.com/kyegomez/swarms) -- `clear_history()`: Clear the conversation history. +- **Documentation:** [Swarms Documentation](https://docs.swarms.world) -- `enable_logging(log_file: str = "model.log")`: Initialize logging for the model. +- **Support:** Contact us via our [Discord Community](https://discord.gg/jM3Z6M9uMq). -- `log_event(message: str)`: Log an event. +--- -- `save_checkpoint(checkpoint_dir: str = "checkpoints")`: Save the model state as a checkpoint. +Experience the future of multi-agent collaboration with Swarms. Start building your agentic workflows today! -- `load_checkpoint(checkpoint_path: str)`: Load the model state from a checkpoint. -- `toggle_creative_mode(enable: bool)`: Toggle creative mode for the model. -- `track_resource_utilization()`: Track and report resource utilization. +-------------------------------------------------- -- ` +# File: swarms\prompts\essence.md -get_generation_time() -> float`: Get the time taken for text generation. +# **The Essence of Enterprise-Grade Prompting** -- `set_max_length(max_length: int)`: Set the maximum length of generated sequences. +Large Language Models (LLMs) like GPT-4 have revolutionized the landscape of AI-driven automation, customer support, marketing, and more. However, extracting the highest quality output from these models requires a thoughtful approach to crafting prompts—an endeavor that goes beyond mere trial and error. In enterprise settings, where consistency, quality, and performance are paramount, enterprise-grade prompting has emerged as a structured discipline, combining art with the science of human-machine communication. -- `set_model_name(model_name: str)`: Set the model name. +Enterprise-grade prompting involves understanding the intricate dynamics between language models, context, and the task at hand. It requires knowledge of not only the technical capabilities of LLMs but also the intricacies of how they interpret human language. Effective prompting becomes the linchpin for ensuring that AI-driven outputs are accurate, reliable, and aligned with business needs. It is this discipline that turns raw AI capabilities into tangible enterprise value. -- `set_frequency_penalty(frequency_penalty: float)`: Set the frequency penalty parameter. +In this essay, we will dissect the essence of enterprise-grade prompting, explore the most effective prompting strategies, explain what works and what doesn't, and conclude with the current holy grail of automated prompt engineering. We will also share concrete examples and illustrations of each technique, with a particular focus on their application in an enterprise setting. -- `set_presence_penalty(presence_penalty: float)`: Set the presence penalty parameter. +## **1. Foundational Principles of Prompting** -- `set_stop_token(stop_token: str)`: Set the stop token. +The effectiveness of prompting lies in understanding both the capabilities and limitations of LLMs. A well-structured prompt helps LLMs focus on the most relevant information while avoiding ambiguities that can lead to unreliable results. In enterprise-grade contexts, prompts must be designed with the end-user's expectations in mind, ensuring quality, safety, scalability, and traceability. -- `set_length_penalty(length_penalty: float)`: Set the length penalty parameter. +- **Clarity**: Prompts should be clear and devoid of unnecessary jargon. Ambiguity can misguide the model, leading to poor-quality output. For enterprise use, clarity means avoiding misunderstandings that could affect customer relationships or lead to non-compliance with regulations. +- **Context**: Providing sufficient context ensures the model understands the nuances of the prompt. For example, specifying whether a response is aimed at a technical audience versus a general audience can lead to more accurate outputs. Context is essential in creating responses that are not only accurate but also relevant to the target audience. +- **Instruction Granularity**: The level of detail in the instruction significantly impacts the quality of the output. Broad instructions might lead to vagueness, whereas overly detailed instructions could overwhelm the model. Finding the right balance is key to generating useful responses. -- `set_role(role: str)`: Set the role of the model. +Example: Instead of prompting "Explain what a blockchain is," an enterprise-grade prompt might be "Explain the concept of blockchain, focusing on how distributed ledgers help increase transparency in supply chain management. Keep the explanation under 200 words for a general audience." This prompt provides clear, relevant, and concise instructions tailored to specific needs. -- `set_top_k(top_k: int)`: Set the top-k parameter. +## **2. Best Prompting Strategies** -- `set_top_p(top_p: float)`: Set the top-p parameter. +The field of enterprise-grade prompting employs numerous strategies to maximize the quality of LLM output. Here are some of the most effective ones: -- `set_num_beams(num_beams: int)`: Set the number of beams. +### **2.1. Instruction-Based Prompting** -- `set_do_sample(do_sample: bool)`: Set whether to use sampling. +Instruction-based prompting provides explicit instructions for the LLM to follow. This approach is valuable in enterprise applications where responses must adhere to a specific tone, structure, or depth of analysis. -- `set_early_stopping(early_stopping: bool)`: Set whether to use early stopping. +**Example**: -- `set_seed(seed: int)`: Set the random seed. +- "Summarize the following press release in 3 bullet points suitable for a marketing team meeting." -- `set_device(device: str)`: Set the device for model execution. +This prompt is highly effective because it instructs the model on what format (bullet points), audience (marketing team), and depth (summary) to produce, minimizing the risk of irrelevant details. -## 3. Implementation +**Why It Works**: LLMs excel when they have a clear set of rules to follow. Enterprises benefit from this structured approach, as it ensures consistency across multiple use cases, be it marketing, HR, or customer service. Clear instructions also make it easier to validate outputs against defined expectations, which is crucial for maintaining quality. -The `BaseLLM` class serves as the base for implementing specific language models. Subclasses of `BaseLLM` should implement the `run` method to define how text is generated for a given task. This design allows flexibility in integrating different language models while maintaining a common interface. +### **2.2. Multi-Shot Prompting** -## 4. Usage Examples +Multi-shot prompting provides several examples before asking the model to complete a task. This helps set expectations by showing the model the desired style and type of output. -To demonstrate how to use the `BaseLLM` interface, let's create an example using a hypothetical language model. We'll initialize an instance of the model and generate text for a simple task. +**Example**: -```python -# Import the BaseLLM class -from swarm_models import BaseLLM +- "Here are some example customer support responses: + 1. Customer: 'I can't access my account.' + Response: 'We're sorry you're having trouble accessing your account. Please try resetting your password using the link provided.' + 2. Customer: 'I received a damaged item.' + Response: 'We apologize for the damaged item. Please provide us with your order number so we can send a replacement.' -# Create an instance of the language model -language_model = BaseLLM( - model_name="my_language_model", - max_tokens=50, - temperature=0.7, - top_k=50, - top_p=0.9, - device="cuda", -) +- Customer: 'The app keeps crashing on my phone.' + Response:" -# Generate text for a task -task = "Translate the following English text to French: 'Hello, world.'" -generated_text = language_model.run(task) +**Why It Works**: Multi-shot prompting is highly effective in enterprise-grade applications where consistency is critical. Showing multiple examples helps the model learn patterns without needing extensive fine-tuning, saving both time and cost. Enterprises can leverage this technique to ensure that responses remain aligned with brand standards and customer expectations across different departments. -# Print the generated text -print(generated_text) -``` +### **2.3. Chain of Thought Prompting** -In this example, we've created an instance of our hypothetical language model, configured its parameters, and used the `run` method to generate text for a translation task. +Chain of Thought (CoT) prompting helps LLMs generate reasoning steps explicitly before arriving at an answer. This method is useful for complex problem-solving tasks or when transparency in decision-making is important. -## 5. Additional Features +**Example**: -The `BaseLLM` interface provides additional features for customization and control: +- "A logistics company wants to minimize fuel costs across multiple delivery routes. Here are the conditions: Each truck has a fuel capacity of 100 gallons, and the price of fuel fluctuates per state. Think through the most cost-effective approach for planning delivery, step by step." -- `batch_run`: Generate text for a batch of tasks efficiently. -- `arun` and `abatch_run`: Asynchronous versions of `run` and `batch_run` for concurrent text generation. -- `chat`: Conduct a conversation with the model by providing a history of the conversation. -- `__call__`: Allow the model to be called directly to generate text. +**Why It Works**: CoT prompting allows the model to work through the process iteratively, providing more explainable results. In enterprise applications where complex decision-making is involved, this strategy ensures stakeholders understand why a particular output was generated. This transparency is crucial in high-stakes areas like finance, healthcare, and logistics, where understanding the reasoning behind an output is as important as the output itself. -These features enhance the flexibility and utility of the interface in various applications, including chatbots, language translation, and content generation. +### **2.4. Iterative Feedback and Adaptive Prompting** -## 6. Performance Metrics +Iterative prompting involves providing multiple prompts or rounds of feedback to refine the output. Adaptive prompts take prior responses and adjust based on context, ensuring the final output meets the required standard. -The `BaseLLM` class offers methods for tracking performance metrics: +**Example**: -- `_tokens_per_second`: Calculate tokens generated per second. -- `_num_tokens`: Calculate the number of tokens in a text. -- `_time_for_generation`: Measure the time taken for text generation. +- First Prompt: "Generate a mission statement for our AI-driven logistics company." + - Model Response: "We use artificial intelligence to enhance logistics." + - Follow-up Prompt: "Can you make the statement more specific by mentioning how AI improves efficiency and sustainability?" -These metrics help assess the efficiency and speed of text generation, enabling optimizations as needed. +**Why It Works**: Enterprises require output that is precise and tailored to brand identity. Iterative feedback provides an effective means to adjust and refine outputs until the desired quality is achieved. By breaking down the task into multiple feedback loops, enterprises can ensure the final output is aligned with their core values and objectives. -## 7. Logging and Checkpoints +### **2.5. Contextual Expansion for Enhanced Relevance** -Logging and checkpointing are crucial for tracking model behavior and ensuring reproducibility: +A lesser-known but powerful strategy is contextual expansion. This involves expanding the prompt to include broader information about the context, thereby allowing the model to generate richer, more relevant responses. -- `enable_logging`: Initialize logging for the model. -- `log_event`: Log events and activities. -- `save_checkpoint`: Save the model state as a checkpoint. -- `load_checkpoint`: Load the model state from a checkpoint. +**Example**: -These capabilities aid in debugging, monitoring, and resuming model experiments. +- Original Prompt: "Write a response to a customer asking for a refund." + - Contextually Expanded Prompt: "Write a response to a customer asking for a refund on a recently purchased product. The customer expressed dissatisfaction with the quality and mentioned they want the process to be quick. Ensure the response is empathetic and explains the refund process clearly, while also offering alternative solutions like an exchange if possible." -## 8. Resource Utilization Tracking +**Why It Works**: By including more context, the prompt allows the model to generate a response that feels more tailored to the customer's situation, enhancing both satisfaction and trust. Enterprises benefit from this approach by increasing the quality of customer service interactions. -The `track_resource_utilization` method is a placeholder for tracking and reporting resource utilization, such as CPU and memory usage. It can be customized to suit specific monitoring needs. +## **3. What Doesn't Work in Prompting** -## 9. Conclusion +While the above methods are effective, prompting can often fall short in certain scenarios: -The Language Model Interface (`BaseLLM`) is a versatile framework for working with language models. Whether you're using pre-trained models or developing your own, this interface provides a consistent and extensible foundation. By following the provided guidelines and examples, you can integrate and customize language models for various natural language processing tasks. +### **3.1. Overly Vague Prompts** --------------------------------------------------- +An insufficiently detailed prompt results in vague outputs. For example, simply asking "What are some strategies to grow a business?" can lead to generic responses that lack actionable insight. Vague prompts are particularly problematic in enterprise settings where specificity is crucial to drive action. -# File: swarms/models/base_multimodal_model.md +### **3.2. Excessive Length** -# `BaseMultiModalModel` Documentation +Overloading a prompt with details often causes the LLM to become confused, producing incomplete or inaccurate responses. For example, "Explain blockchain, focusing on cryptographic methods, network nodes, ledger distribution, proof of work, mining processes, hash functions, transaction validation, etc." attempts to include too many subjects for a concise response. Enterprise-grade prompts should focus on a specific area to avoid overwhelming the model and degrading the output quality. -Swarms is a Python library that provides a framework for running multimodal AI models. It allows you to combine text and image inputs and generate coherent and context-aware responses. This library is designed to be extensible, allowing you to integrate various multimodal models. +### **3.3. Ambiguity in Expected Output** -## Table of Contents +Ambiguity arises when prompts don't clearly specify the desired output format, tone, or length. For example, asking "Describe our new product" without specifying whether it should be a single-line summary, a paragraph, or a technical overview can lead to an unpredictable response. Enterprises must clearly define expectations to ensure consistent and high-quality outputs. -1. [Introduction](#introduction) -2. [Installation](#installation) -3. [Getting Started](#getting-started) -4. [BaseMultiModalModel Class](#basemultimodalmodel-class) - - [Initialization](#initialization) - - [Methods](#methods) -5. [Usage Examples](#usage-examples) -6. [Additional Tips](#additional-tips) -7. [References and Resources](#references-and-resources) +## **4. The Holy Grail: Automated Prompt Engineering** -## 1. Introduction +In an enterprise setting, scaling prompt engineering for consistency and high performance remains a key challenge. Automated Prompt Engineering (APE) offers a potential solution for bridging the gap between individual craftsmanship and enterprise-wide implementation. -Swarms is designed to simplify the process of working with multimodal AI models. These models are capable of understanding and generating content based on both textual and image inputs. With this library, you can run such models and receive context-aware responses. +**4.1. AI-Augmented Prompt Design** -## 2. Installation +Automated Prompt Engineering tools can evaluate the outputs generated by various prompts, selecting the one with the highest quality metrics. These tools can be trained to understand what constitutes an ideal response for specific enterprise contexts. -To install swarms, you can use pip: +**Example**: -```bash -pip install swarms -``` +- An APE system takes multiple variations of a prompt for generating email responses to customer complaints. After evaluating the sentiment, tone, and accuracy of each response, it selects the prompt that yields the most favorable output for business goals. -## 3. Getting Started +**Why It Works**: AI-Augmented Prompt Design reduces the need for manual intervention and standardizes the quality of responses across the organization. This approach helps enterprises maintain consistency while saving valuable time that would otherwise be spent on trial-and-error prompting. -To get started with Swarms, you'll need to import the library and create an instance of the `BaseMultiModalModel` class. This class serves as the foundation for running multimodal models. +**4.2. Reinforcement Learning for Prompts (RLP)** -```python -from swarm_models import BaseMultiModalModel +Using Reinforcement Learning for Prompts involves training models to automatically iterate on prompts to improve the quality of the final output. The model is rewarded for generating responses that align with predefined criteria, such as clarity, completeness, or relevance. -model = BaseMultiModalModel( - model_name="your_model_name", - temperature=0.5, - max_tokens=500, - max_workers=10, - top_p=1, - top_k=50, - beautify=False, - device="cuda", - max_new_tokens=500, - retries=3, -) -``` +**Example**: -You can customize the initialization parameters based on your model's requirements. +- An enterprise uses RLP to refine prompts used in internal compliance checks. The model iteratively generates summaries of compliance reports, refining the prompt until it consistently generates clear, concise, and accurate summaries aligned with internal guidelines. -## 4. BaseMultiModalModel Class +**Why It Works**: RLP can significantly improve the quality of complex outputs over time. Enterprises that require a high level of precision, such as in legal or compliance-related applications, benefit from RLP by ensuring outputs meet stringent standards. -### Initialization +**4.3. Dynamic Contextual Adaptation** -The `BaseMultiModalModel` class is initialized with several parameters that control its behavior. Here's a breakdown of the initialization parameters: +Another aspect of automated prompt engineering involves adapting prompts in real time based on user context. For example, if a user interacting with a customer support bot seems frustrated (as detected by sentiment analysis), an adaptive prompt may be used to generate a more empathetic response. -| Parameter | Description | Default Value | -|------------------|-------------------------------------------------------------------------------------------------------|---------------| -| `model_name` | The name of the multimodal model to use. | None | -| `temperature` | The temperature parameter for controlling randomness in text generation. | 0.5 | -| `max_tokens` | The maximum number of tokens in the generated text. | 500 | -| `max_workers` | The maximum number of concurrent workers for running tasks. | 10 | -| `top_p` | The top-p parameter for filtering words in text generation. | 1 | -| `top_k` | The top-k parameter for filtering words in text generation. | 50 | -| `beautify` | Whether to beautify the output text. | False | -| `device` | The device to run the model on (e.g., 'cuda' or 'cpu'). | 'cuda' | -| `max_new_tokens` | The maximum number of new tokens allowed in generated responses. | 500 | -| `retries` | The number of retries in case of an error during text generation. | 3 | -| `system_prompt` | A system-level prompt to set context for generation. | None | -| `meta_prompt` | A meta prompt to provide guidance for including image labels in responses. | None | +**Example**: -### Methods +- User: "I'm really annoyed that my order hasn't arrived yet." + - Prompt (adapted): "I'm truly sorry for the inconvenience you're experiencing. Please let me help you resolve this as quickly as possible. Could you provide your order number so I can check its status right away?" -The `BaseMultiModalModel` class defines various methods for running multimodal models and managing interactions: +**Why It Works**: In dynamic enterprise environments, where every user experience matters, adapting prompts to the immediate context can significantly improve customer satisfaction. Real-time adaptation allows the model to be more responsive and attuned to customer needs, thereby fostering loyalty and trust. -- `run(task: str, img: str) -> str`: Run the multimodal model with a text task and an image URL to generate a response. +**4.4. Collaborative Prompt Refinement** -- `arun(task: str, img: str) -> str`: Run the multimodal model asynchronously with a text task and an image URL to generate a response. +Automated prompt engineering can also involve collaboration between AI models and human experts. Collaborative Prompt Refinement (CPR) allows human operators to provide iterative guidance, which the model then uses to enhance its understanding and improve future outputs. -- `get_img_from_web(img: str) -> Image`: Fetch an image from a URL and return it as a PIL Image. +**Example**: -- `encode_img(img: str) -> str`: Encode an image to base64 format. +- A financial analyst uses a prompt to generate an investment report. The model provides an initial draft, and the analyst refines it with comments. The model learns from these comments and applies similar refinements to future reports, reducing the analyst’s workload over time. -- `get_img(img: str) -> Image`: Load an image from the local file system and return it as a PIL Image. +**Why It Works**: CPR bridges the gap between human expertise and machine efficiency, ensuring that outputs are not only technically accurate but also aligned with expert expectations. This iterative learning loop enhances the model’s ability to autonomously generate high-quality content. -- `clear_chat_history()`: Clear the chat history maintained by the model. +## **5. The Future of Enterprise-Grade Prompting** -- `run_many(tasks: List[str], imgs: List[str]) -> List[str]`: Run the model on multiple text tasks and image URLs concurrently and return a list of responses. +The future of enterprise-grade prompting is in leveraging automation, context-awareness, and reinforcement learning. By moving from static prompts to dynamic, learning-enabled systems, enterprises can ensure consistent and optimized communication across their AI systems. -- `run_batch(tasks_images: List[Tuple[str, str]]) -> List[str]`: Process a batch of text tasks and image URLs and return a list of responses. +Automated systems such as APE and RLP are in their early stages, but they represent the potential to deliver highly scalable prompting solutions that automatically evolve based on user feedback and performance metrics. As more sophisticated models and methods become available, enterprise-grade prompting will likely involve: -- `run_batch_async(tasks_images: List[Tuple[str, str]]) -> List[str]`: Process a batch of text tasks and image URLs asynchronously and return a list of responses. +- **Fully Adaptive Models**: Models that can detect and adjust to the tone, intent, and needs of users in real time. This means less manual intervention and greater responsiveness to user context. +- **Cross-Domain Learning**: Prompting systems that leverage insights across multiple domains to improve response quality. For example, lessons learned from customer service prompts could be applied to internal HR prompts to enhance employee communications. +- **Human-in-the-Loop Systems**: Combining automated prompt generation with human validation to ensure compliance, accuracy, and brand consistency. Human-in-the-loop systems allow enterprises to leverage the efficiency of automation while maintaining a high level of quality control. -- `run_batch_async_with_retries(tasks_images: List[Tuple[str, str]]) -> List[str]`: Process a batch of text tasks and image URLs asynchronously with retries in case of errors and return a list of responses. +The rise of self-improving prompting systems marks a significant shift in how enterprises leverage AI for communication and decision-making. As more sophisticated models emerge, we anticipate a greater emphasis on adaptability, real-time learning, and seamless integration with existing business processes. -- `unique_chat_history() -> List[str]`: Get the unique chat history stored by the model. +**Conclusion** -- `run_with_retries(task: str, img: str) -> str`: Run the model with retries in case of an error. +Enterprise-grade prompting transcends the art of crafting effective prompts into a well-defined process, merging structure with creativity and guided refinement. By understanding the foundational principles, leveraging strategies like instruction-based and chain-of-thought prompting, and adopting automation, enterprises can consistently extract high-quality results from LLMs. -- `run_batch_with_retries(tasks_images: List[Tuple[str, str]]) -> List[str]`: Run a batch of tasks with retries in case of errors and return a list of responses. +The evolution towards automated prompt engineering is transforming enterprise AI use from reactive problem-solving to proactive, intelligent decision-making. As the enterprise AI ecosystem matures, prompting will continue to be the linchpin that aligns the capabilities of LLMs with real-world business needs, ensuring optimal outcomes at scale. -- `_tokens_per_second() -> float`: Calculate the tokens generated per second during text generation. +Whether it's customer support, compliance, marketing, or operational analytics, the strategies outlined in this essay—paired with advancements in automated prompt engineering—hold the key to effective, scalable, and enterprise-grade utilization of AI models. Enterprises that invest in these methodologies today are likely to maintain a competitive edge in an increasingly automated business landscape. -- `_time_for_generation(task: str) -> float`: Measure the time taken for text generation for a specific task. +**Next Steps** -- `generate_summary(text: str) -> str`: Generate a summary of the provided text. +This essay is a stepping stone towards understanding enterprise-grade prompting. We encourage AI teams to start experimenting with these prompting techniques in sandbox environments, identify what works best for their needs, and gradually iterate. Automation is the future, and investing in automated prompt engineering today will yield highly optimized, scalable solutions that consistently deliver value. -- `set_temperature(value: float)`: Set the temperature parameter for controlling randomness in text generation. +Ready to take the next step? Let’s explore how to design adaptive prompting frameworks tailored to your enterprise’s unique requirements. -- `set_max_tokens(value: int)`: Set the maximum number of tokens allowed in generated responses. +-------------------------------------------------- -- `get_generation_time() -> float`: Get the time taken for text generation for the last task. +# File: swarms\prompts\main.md -- `get_chat_history() -> List[str]`: Get the chat history, including all interactions. +# Managing Prompts in Production -- `get_unique_chat_history() -> List[str]`: Get the unique chat history, removing duplicate interactions. +The `Prompt` class provides a comprehensive solution for managing prompts, including advanced features like version control, autosaving, and logging. This guide will walk you through how to effectively use this class in a production environment, focusing on its core features, use cases, and best practices. -- `get_chat_history_length() -> int`: Get the length of the chat history. +## Table of Contents -- `get_unique_chat_history_length() -> int`: Get the length of the unique chat history. +1. **Getting Started** + - Installation and Setup + - Creating a New Prompt +2. **Managing Prompt Content** + - Editing Prompts + - Retrieving Prompt Content +3. **Version Control** + - Tracking Edits and History + - Rolling Back to Previous Versions +4. **Autosaving Prompts** + - Enabling and Configuring Autosave + - Manually Triggering Autosave +5. **Logging and Telemetry** +6. **Handling Errors** +7. **Extending the Prompt Class** + - Customizing the Save Mechanism + - Integrating with Databases -- `get_chat_history_tokens() -> int`: Get the total number of tokens in the chat history. +--- -- `print_beautiful(content: str, color: str = 'cyan')`: Print content beautifully using colored text. +## 1. Getting Started -- `stream(content: str)`: Stream the content, printing it character by character. +### Installation and Setup -- `meta_prompt() -> str`: Get the meta prompt that provides guidance for including image labels in responses. +Before diving into how to use the `Prompt` class, ensure that you have the required dependencies installed: -## 5. Usage Examples +```bash +pip3 install -U swarms +``` -Let's explore some usage examples of the MultiModalAI library: -### Example 1: Running +### Creating a New Prompt - the Model +To create a new instance of a `Prompt`, simply initialize it with the required attributes such as `content`: ```python -# Import the library -from swarm_models import BaseMultiModalModel +from swarms import Prompt -# Create an instance of the model -model = BaseMultiModalModel( - model_name="your_model_name", - temperature=0.5, - max_tokens=500, - device="cuda", +prompt = Prompt( + content="This is my first prompt!", + name="My First Prompt", + description="A simple example prompt." ) -# Run the model with a text task and an image URL -response = model.run( - "Generate a summary of this text", "https://www.example.com/image.jpg" -) -print(response) +print(prompt) ``` -### Example 2: Running Multiple Tasks Concurrently - -```python -# Import the library -from swarm_models import BaseMultiModalModel +This creates a new prompt with the current timestamp and a unique identifier. -# Create an instance of the model -model = BaseMultiModalModel( - model_name="your_model_name", - temperature=0.5, - max_tokens=500, - max_workers=4, - device="cuda", -) +--- -# Define a list of tasks and image URLs -tasks = ["Task 1", "Task 2", "Task 3"] -images = ["https://image1.jpg", "https://image2.jpg", "https://image3.jpg"] +## 2. Managing Prompt Content -# Run the model on multiple tasks concurrently -responses = model.run_many(tasks, images) -for response in responses: - print(response) -``` +### Editing Prompts -### Example 3: Running the Model Asynchronously +Once you have initialized a prompt, you can edit its content using the `edit_prompt` method. Each time the content is edited, a new version is stored in the `edit_history`, and the `last_modified_at` timestamp is updated. ```python -# Import the library -from swarm_models import BaseMultiModalModel - -# Create an instance of the model -model = BaseMultiModalModel( - model_name="your_model_name", - temperature=0.5, - max_tokens=500, - device="cuda", -) +new_content = "This is an updated version of my prompt." +prompt.edit_prompt(new_content) +``` -# Define a list of tasks and image URLs -tasks_images = [ - ("Task 1", "https://image1.jpg"), - ("Task 2", "https://image2.jpg"), - ("Task 3", "https://image3.jpg"), -] +**Note**: If the new content is identical to the current content, an error will be raised to prevent unnecessary edits: -# Run the model on multiple tasks asynchronously -responses = model.run_batch_async(tasks_images) -for response in responses: - print(response) +```python +try: + prompt.edit_prompt("This is my first prompt!") # Same as initial content +except ValueError as e: + print(e) # Output: New content must be different from the current content. ``` -### Example 4: Inheriting `BaseMultiModalModel` for it's prebuilt classes -```python -from swarm_models import BaseMultiModalModel +### Retrieving Prompt Content +You can retrieve the current prompt content using the `get_prompt` method: -class CustomMultiModalModel(BaseMultiModalModel): - def __init__(self, model_name, custom_parameter, *args, **kwargs): - # Call the parent class constructor - super().__init__(model_name=model_name, *args, **kwargs) - # Initialize custom parameters specific to your model - self.custom_parameter = custom_parameter +```python +current_content = prompt.get_prompt() +print(current_content) # Output: This is an updated version of my prompt. +``` - def __call__(self, text, img): - # Implement the multimodal model logic here - # You can use self.custom_parameter and other inherited attributes - pass +This method also logs telemetry data, which includes both system information and prompt metadata. - def generate_summary(self, text): - # Implement the summary generation logic using your model - # You can use self.custom_parameter and other inherited attributes - pass +--- +## 3. Version Control -# Create an instance of your custom multimodal model -custom_model = CustomMultiModalModel( - model_name="your_custom_model_name", - custom_parameter="your_custom_value", - temperature=0.5, - max_tokens=500, - device="cuda", -) +### Tracking Edits and History -# Run your custom model -response = custom_model.run( - "Generate a summary of this text", "https://www.example.com/image.jpg" -) -print(response) +The `Prompt` class automatically tracks every change made to the prompt. This is stored in the `edit_history` attribute as a list of previous versions. -# Generate a summary using your custom model -summary = custom_model.generate_summary("This is a sample text to summarize.") -print(summary) +```python +print(prompt.edit_history) # Output: ['This is my first prompt!', 'This is an updated version of my prompt.'] ``` -In the code above: - -1. We define a `CustomMultiModalModel` class that inherits from `BaseMultiModalModel`. +The number of edits is also tracked using the `edit_count` attribute: -2. In the constructor of our custom class, we call the parent class constructor using `super()` and initialize any custom parameters specific to our model. In this example, we introduced a `custom_parameter`. +```python +print(prompt.edit_count) # Output: 2 +``` -3. We override the `__call__` method, which is responsible for running the multimodal model logic. Here, you can implement the specific behavior of your model, considering both text and image inputs. +### Rolling Back to Previous Versions -4. We override the `generate_summary` method, which is used to generate a summary of text input. You can implement your custom summarization logic here. +If you want to revert a prompt to a previous version, you can use the `rollback` method, passing the version index you want to revert to: -5. We create an instance of our custom model, passing the required parameters, including the custom parameter. +```python +prompt.rollback(0) +print(prompt.get_prompt()) # Output: This is my first prompt! +``` -6. We demonstrate how to run the custom model and generate a summary using it. +The rollback operation is thread-safe, and any rollback also triggers a telemetry log. -By inheriting from `BaseMultiModalModel`, you can leverage the prebuilt features and methods provided by the library while customizing the behavior of your multimodal model. This allows you to create powerful and specialized models for various multimodal tasks. +--- -These examples demonstrate how to use MultiModalAI to run multimodal models with text and image inputs. You can adjust the parameters and methods to suit your specific use cases. +## 4. Autosaving Prompts -## 6. Additional Tips +### Enabling and Configuring Autosave -Here are some additional tips and considerations for using MultiModalAI effectively: +To automatically save prompts to storage after every change, you can enable the `autosave` feature when initializing the prompt: -- **Custom Models**: You can create your own multimodal models and inherit from the `BaseMultiModalModel` class to integrate them with this library. +```python +prompt = Prompt( + content="This is my first prompt!", + autosave=True, + autosave_folder="my_prompts" # Specify the folder within WORKSPACE_DIR +) +``` -- **Retries**: In cases where text generation might fail due to various reasons (e.g., server issues), using methods with retries can be helpful. +This will ensure that every edit or rollback action triggers an autosave to the specified folder. -- **Monitoring**: You can monitor the performance of your model using methods like `_tokens_per_second()` and `_time_for_generation()`. +### Manually Triggering Autosave -- **Chat History**: The library maintains a chat history, allowing you to keep track of interactions. +You can also manually trigger an autosave by calling the `_autosave` method (which is a private method typically used internally): -- **Streaming**: The `stream()` method can be useful for displaying output character by character, which can be helpful for certain applications. +```python +prompt._autosave() # Manually triggers autosaving +``` -## 7. References and Resources +Autosaves are stored as JSON files in the folder specified by `autosave_folder` under the workspace directory (`WORKSPACE_DIR` environment variable). -Here are some references and resources that you may find useful for working with multimodal models: +--- -- [Hugging Face Transformers Library](https://huggingface.co/transformers/): A library for working with various transformer-based models. +## 5. Logging and Telemetry -- [PIL (Python Imaging Library)](https://pillow.readthedocs.io/en/stable/): Documentation for working with images in Python using the Pillow library. +The `Prompt` class integrates with the `loguru` logging library to provide detailed logs for every major action, such as editing, rolling back, and saving. The `log_telemetry` method captures and logs system data, including prompt metadata, for each operation. -- [Concurrent Programming in Python](https://docs.python.org/3/library/concurrent.futures.html): Official Python documentation for concurrent programming. +Here's an example of a log when editing a prompt: -- [Requests Library Documentation](https://docs.python-requests.org/en/latest/): Documentation for the Requests library, which is used for making HTTP requests. - -- [Base64 Encoding in Python](https://docs.python.org/3/library/base64.html): Official Python documentation for base64 encoding and decoding. - -This concludes the documentation for the MultiModalAI library. You can now explore the library further and integrate it with your multimodal AI projects. - --------------------------------------------------- - -# File: swarms/models/custom_model.md - -# How to Create A Custom Language Model - -When working with advanced language models, there might come a time when you need a custom solution tailored to your specific needs. Inheriting from an `BaseLLM` in a Python framework allows developers to create custom language model classes with ease. This developer guide will take you through the process step by step. - -### Prerequisites - -Before you begin, ensure that you have: +```bash +2024-10-10 10:12:34.567 | INFO | Editing prompt a7b8f9. Current content: 'This is my first prompt!' +2024-10-10 10:12:34.789 | DEBUG | Prompt a7b8f9 updated. Edit count: 1. New content: 'This is an updated version of my prompt.' +``` -- A working knowledge of Python programming. -- Basic understanding of object-oriented programming (OOP) in Python. -- Familiarity with language models and natural language processing (NLP). -- The appropriate Python framework installed, with access to `BaseLLM`. +You can extend logging by integrating the `log_telemetry` method with your own telemetry systems or databases: -### Step-by-Step Guide +```python +prompt.log_telemetry() +``` -#### Step 1: Understand `BaseLLM` +--- -The `BaseLLM` is an abstract base class that defines a set of methods and properties which your custom language model (LLM) should implement. Abstract classes in Python are not designed to be instantiated directly but are meant to be subclasses. +## 6. Handling Errors -#### Step 2: Create a New Class +Error handling in the `Prompt` class is robust and prevents common mistakes, such as editing with identical content or rolling back to an invalid version. Here's a common scenario: -Start by defining a new class that inherits from `BaseLLM`. This class will implement the required methods defined in the abstract base class. +### Editing with Identical Content ```python -from swarms import BaseLLM - -class vLLMLM(BaseLLM): - pass +try: + prompt.edit_prompt("This is an updated version of my prompt.") +except ValueError as e: + print(e) # Output: New content must be different from the current content. ``` -#### Step 3: Initialize Your Class - -Implement the `__init__` method to initialize your custom LLM. You'll want to initialize the base class as well and define any additional parameters for your model. +### Invalid Rollback Version ```python -class vLLMLM(BaseLLM): - def __init__(self, model_name='default_model', tensor_parallel_size=1, *args, **kwargs): - super().__init__(*args, **kwargs) - self.model_name = model_name - self.tensor_parallel_size = tensor_parallel_size - # Add any additional initialization here +try: + prompt.rollback(10) # Invalid version index +except IndexError as e: + print(e) # Output: Invalid version number for rollback. ``` -#### Step 4: Implement Required Methods +Always ensure that version numbers passed to `rollback` are within the valid range of existing versions. -Implement the `run` method or any other abstract methods required by `BaseLLM`. This is where you define how your model processes input and returns output. +--- -```python -class vLLMLM(BaseLLM): - # ... existing code ... - - def run(self, task, *args, **kwargs): - # Logic for running your model goes here - return "Processed output" -``` +## 7. Extending the Prompt Class -#### Step 5: Test Your Model +### Customizing the Save Mechanism + +The `Prompt` class currently includes a placeholder for saving and loading prompts from persistent storage. You can override the `save_to_storage` and `load_from_storage` methods to integrate with databases, cloud storage, or other persistent layers. -Instantiate your custom LLM and test it to ensure that it works as expected. +Here's how you can implement the save functionality: ```python -model = vLLMLM(model_name='my_custom_model', tensor_parallel_size=2) -output = model.run("What are the symptoms of COVID-19?") -print(output) # Outputs: "Processed output" +def save_to_storage(self): + # Example of saving to a database or cloud storage + data = self.model_dump() + save_to_database(data) # Custom function to save data ``` -#### Step 6: Integrate Additional Components - -Depending on the requirements, you might need to integrate additional components such as database connections, parallel computing resources, or custom processing pipelines. +Similarly, you can implement a `load_from_storage` function to load the prompt from a storage location using its unique identifier (`id`). -#### Step 7: Documentation -Write comprehensive docstrings for your class and its methods. Good documentation is crucial for maintaining the code and for other developers who might use your model. +## Full Example code with all methods ```python -class vLLMLM(BaseLLM): - """ - A custom language model class that extends BaseLLM. - - ... more detailed docstring ... - """ - # ... existing code ... -``` - -#### Step 8: Best Practices - -Follow best practices such as error handling, input validation, and resource management to ensure your model is robust and reliable. +from swarms.prompts.prompt import Prompt -#### Step 9: Packaging Your Model +# Example 1: Initializing a Financial Report Prompt +financial_prompt = Prompt( + content="Q1 2024 Earnings Report: Initial Draft", autosave=True +) -Package your custom LLM class into a module or package that can be easily distributed and imported into other projects. +# Output the initial state of the prompt +print("\n--- Example 1: Initializing Prompt ---") +print(f"Prompt ID: {financial_prompt.id}") +print(f"Content: {financial_prompt.content}") +print(f"Created At: {financial_prompt.created_at}") +print(f"Edit Count: {financial_prompt.edit_count}") +print(f"History: {financial_prompt.edit_history}") -#### Step 10: Version Control and Collaboration -Use a version control system like Git to track changes to your model. This makes collaboration easier and helps you keep a history of your work. +# Example 2: Editing a Financial Report Prompt +financial_prompt.edit_prompt( + "Q1 2024 Earnings Report: Updated Revenue Figures" +) -### Conclusion +# Output the updated state of the prompt +print("\n--- Example 2: Editing Prompt ---") +print(f"Content after edit: {financial_prompt.content}") +print(f"Edit Count: {financial_prompt.edit_count}") +print(f"History: {financial_prompt.edit_history}") -By following this guide, you should now have a custom model that extends the `BaseLLM`. Remember that the key to a successful custom LLM is understanding the base functionalities, implementing necessary changes, and testing thoroughly. Keep iterating and improving based on feedback and performance metrics. -### Further Reading +# Example 3: Rolling Back to a Previous Version +financial_prompt.edit_prompt("Q1 2024 Earnings Report: Final Version") +financial_prompt.rollback( + 1 +) # Roll back to the second version (index 1) -- Official Python documentation on abstract base classes. -- In-depth tutorials on object-oriented programming in Python. -- Advanced NLP techniques and optimization strategies for language models. +# Output the state after rollback +print("\n--- Example 3: Rolling Back ---") +print(f"Content after rollback: {financial_prompt.content}") +print(f"Edit Count: {financial_prompt.edit_count}") +print(f"History: {financial_prompt.edit_history}") -This guide provides the fundamental steps to create custom models using `BaseLLM`. For detailed implementation and advanced customization, it's essential to dive deeper into the specific functionalities and capabilities of the language model framework you are using. --------------------------------------------------- +# Example 4: Handling Invalid Rollback +print("\n--- Example 4: Invalid Rollback ---") +try: + financial_prompt.rollback( + 5 + ) # Attempt an invalid rollback (out of bounds) +except IndexError as e: + print(f"Error: {e}") -# File: swarms/models/dalle3.md -# `Dalle3` Documentation +# Example 5: Preventing Duplicate Edits +print("\n--- Example 5: Preventing Duplicate Edits ---") +try: + financial_prompt.edit_prompt( + "Q1 2024 Earnings Report: Updated Revenue Figures" + ) # Duplicate content +except ValueError as e: + print(f"Error: {e}") -## Table of Contents -1. [Introduction](#introduction) -2. [Installation](#installation) -3. [Quick Start](#quick-start) -4. [Dalle3 Class](#dalle3-class) - - [Attributes](#attributes) - - [Methods](#methods) -5. [Usage Examples](#usage-examples) -6. [Error Handling](#error-handling) -7. [Advanced Usage](#advanced-usage) -8. [References](#references) +# Example 6: Retrieving the Prompt Content as a String +print("\n--- Example 6: Retrieving Prompt as String ---") +current_content = financial_prompt.get_prompt() +print(f"Current Prompt Content: {current_content}") ---- -## Introduction +# Example 7: Simulating Financial Report Changes Over Time +print("\n--- Example 7: Simulating Changes Over Time ---") +# Initialize a new prompt representing an initial financial report draft +financial_prompt = Prompt( + content="Q2 2024 Earnings Report: Initial Draft" +) -The Dalle3 library is a Python module that provides an easy-to-use interface for generating images from text descriptions using the DALL·E 3 model by OpenAI. DALL·E 3 is a powerful language model capable of converting textual prompts into images. This documentation will guide you through the installation, setup, and usage of the Dalle3 library. +# Simulate several updates over time +financial_prompt.edit_prompt( + "Q2 2024 Earnings Report: Updated Forecasts" +) +financial_prompt.edit_prompt( + "Q2 2024 Earnings Report: Revenue Adjustments" +) +financial_prompt.edit_prompt("Q2 2024 Earnings Report: Final Review") ---- +# Display full history +print(f"Final Content: {financial_prompt.content}") +print(f"Edit Count: {financial_prompt.edit_count}") +print(f"Edit History: {financial_prompt.edit_history}") -## Installation -To use the Dalle3 model, you must first install swarms: -```bash -pip install swarms ``` --- -## Quick Start - -Let's get started with a quick example of using the Dalle3 library to generate an image from a text prompt: - -```python -from swarm_models.dalle3 import Dalle3 +## 8. Conclusion -# Create an instance of the Dalle3 class -dalle = Dalle3() +This guide covered how to effectively use the `Prompt` class in production environments, including core features like editing, version control, autosaving, and logging. By following the best practices outlined here, you can ensure that your prompts are managed efficiently, with minimal overhead and maximum flexibility. -# Define a text prompt -task = "A painting of a dog" +The `Prompt` class is designed with scalability and robustness in mind, making it a great choice for managing prompt content in multi-agent architectures or any application where dynamic prompt management is required. Feel free to extend the functionality to suit your needs, whether it's integrating with persistent storage or enhancing logging mechanisms. -# Generate an image from the text prompt -image_url = dalle3(task) +By using this architecture, you'll be able to scale your system effortlessly while maintaining detailed version control and history of every interaction with your prompts. -# Print the generated image URL -print(image_url) -``` +-------------------------------------------------- -This example demonstrates the basic usage of the Dalle3 library to convert a text prompt into an image. The generated image URL will be printed to the console. +# File: swarms\structs\abstractswarm.md ---- +# `BaseSwarm` Documentation -## Dalle3 Class +## Table of Contents -The Dalle3 library provides a `Dalle3` class that allows you to interact with the DALL·E 3 model. This class has several attributes and methods for generating images from text prompts. +1. [Introduction](#introduction) +2. [Class Definition](#class-definition) +3. [Methods](#methods) + - [communicate()](#communicate) + - [run()](#run) + - [arun()](#arun) + - [add_worker(worker)](#add_worker) + - [remove_worker(worker)](#remove_worker) + - [broadcast(message, sender)](#broadcast) + - [reset()](#reset) + - [plan(task)](#plan) + - [direct_message(message, sender, recipient)](#direct_message) + - [autoscaler(num_workers, worker)](#autoscaler) + - [get_worker_by_id(id)](#get_worker_by_id) + - [get_worker_by_name(name)](#get_worker_by_name) + - [assign_task(worker, task)](#assign_task) + - [get_all_tasks(worker, task)](#get_all_tasks) + - [get_finished_tasks()](#get_finished_tasks) + - [get_pending_tasks()](#get_pending_tasks) + - [pause_worker(worker, worker_id)](#pause_worker) + - [resume_worker(worker, worker_id)](#resume_worker) + - [stop_worker(worker, worker_id)](#stop_worker) + - [restart_worker(worker)](#restart_worker) + - [scale_up(num_worker)](#scale_up) + - [scale_down(num_worker)](#scale_down) + - [scale_to(num_worker)](#scale_to) + - [get_all_workers()](#get_all_workers) + - [get_swarm_size()](#get_swarm_size) + - [get_swarm_status()](#get_swarm_status) + - [save_swarm_state()](#save_swarm_state) -### Attributes +--- -- `model` (str): The name of the DALL·E 3 model. Default: "dall-e-3". -- `img` (str): The image URL generated by the Dalle3 API. -- `size` (str): The size of the generated image. Default: "1024x1024". -- `max_retries` (int): The maximum number of API request retries. Default: 3. -- `quality` (str): The quality of the generated image. Default: "standard". -- `n` (int): The number of variations to create. Default: 4. +## 1. Introduction -### Methods +The Swarms library is designed to provide a framework for swarm simulation architectures. Swarms are collections of autonomous agents or workers that collaborate to perform tasks and achieve common goals. This documentation will guide you through the functionality and usage of the Swarms library, explaining the purpose and implementation details of the provided classes and methods. -#### `__call__(self, task: str) -> Dalle3` +## 2. Class Definition -This method makes a call to the Dalle3 API and returns the image URL generated from the provided text prompt. +### `BaseSwarm` Class -Parameters: -- `task` (str): The text prompt to be converted to an image. +The `BaseSwarm` class is an abstract base class that serves as the foundation for swarm simulation architectures. It defines the core functionality and methods required to manage and interact with a swarm of workers. -Returns: -- `Dalle3`: An instance of the Dalle3 class with the image URL generated by the Dalle3 API. +```python +from abc import ABC, abstractmethod +from typing import List -#### `create_variations(self, img: str)` +from swarms.swarms.base import AbstractWorker -This method creates variations of an image using the Dalle3 API. -Parameters: -- `img` (str): The image to be used for the API request. +class BaseSwarm(ABC): + """ + Abstract class for swarm simulation architectures -Returns: -- `img` (str): The image URL of the generated variations. + Methods: + --------- + ... + """ ---- + # The class definition and constructor are provided here. -## Usage Examples + @abstractmethod + def __init__(self, workers: List["AbstractWorker"]): + """Initialize the swarm with workers""" -### Example 1: Basic Image Generation + # Other abstract methods are listed here. +``` -```python -from swarm_models.dalle3 import Dalle3 +## 3. Methods -# Create an instance of the Dalle3 class -dalle3 = Dalle3() +### `communicate()` -# Define a text prompt -task = "A painting of a dog" +The `communicate()` method allows the swarm to exchange information through the orchestrator, protocols, and the universal communication layer. -# Generate an image from the text prompt -image_url = dalle3(task) +**Usage Example 1:** -# Print the generated image URL -print(image_url) +```python +swarm = YourSwarmClass(workers) +swarm.communicate() ``` -### Example 2: Creating Image Variations +**Usage Example 2:** ```python -from swarm_models.dalle3 import Dalle3 +# Another example of using the communicate method +swarm = YourSwarmClass(workers) +swarm.communicate() +``` -# Create an instance of the Dalle3 class -dalle3 = Dalle3() +### `run()` -# Define the URL of an existing image -img_url = "https://images.unsplash.com/photo-1694734479898-6ac4633158ac?q=80&w=1287&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D +The `run()` method executes the swarm, initiating its activities. -# Create variations of the image -variations_url = dalle3.create_variations(img_url) +**Usage Example 1:** -# Print the URLs of the generated variations -print(variations_url) +```python +swarm = YourSwarmClass(workers) +swarm.run() ``` -Certainly! Here are additional examples that cover various edge cases and methods of the `Dalle3` class in the Dalle3 library: - -### Example 3: Customizing Image Size - -You can customize the size of the generated image by specifying the `size` parameter when creating an instance of the `Dalle3` class. Here's how to generate a smaller image: +**Usage Example 2:** ```python -from swarm_models.dalle3 import Dalle3 +# Another example of running the swarm +swarm = YourSwarmClass(workers) +swarm.run() +``` -# Create an instance of the Dalle3 class with a custom image size -dalle3 = Dalle3(size="512x512") +### `arun()` -# Define a text prompt -task = "A small painting of a cat" +The `arun()` method runs the swarm asynchronously, allowing for parallel execution of tasks. -# Generate a smaller image from the text prompt -image_url = dalle3(task) +**Usage Example 1:** -# Print the generated image URL -print(image_url) +```python +swarm = YourSwarmClass(workers) +swarm.arun() ``` -### Example 4: Adjusting Retry Limit - -You can adjust the maximum number of API request retries using the `max_retries` parameter. Here's how to increase the retry limit: +**Usage Example 2:** ```python -from swarm_models.dalle3 import Dalle3 - -# Create an instance of the Dalle3 class with a higher retry limit -dalle3 = Dalle3(max_retries=5) - -# Define a text prompt -task = "An image of a landscape" +# Another example of running the swarm asynchronously +swarm = YourSwarmClass(workers) +swarm.arun() +``` -# Generate an image with a higher retry limit -image_url = dalle3(task) +### `add_worker(worker: "AbstractWorker")` -# Print the generated image URL -print(image_url) -``` +The `add_worker()` method adds a worker to the swarm. -### Example 5: Generating Image Variations +**Parameters:** +- `worker` (AbstractWorker): The worker to be added to the swarm. -To create variations of an existing image, you can use the `create_variations` method. Here's an example: +**Usage Example:** ```python -from swarm_models.dalle3 import Dalle3 +swarm = YourSwarmClass([]) +worker = YourWorkerClass() +swarm.add_worker(worker) +``` -# Create an instance of the Dalle3 class -dalle3 = Dalle3() +### `remove_worker(worker: "AbstractWorker")` -# Define the URL of an existing image -img_url = "https://images.unsplash.com/photo-1677290043066-12eccd944004?q=80&w=1287&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" +The `remove_worker()` method removes a worker from the swarm. -# Create variations of the image -variations_url = dalle3.create_variations(img_url) +**Parameters:** +- `worker` (AbstractWorker): The worker to be removed from the swarm. -# Print the URLs of the generated variations -print(variations_url) -``` +**Usage Example:** -### Example 6: Handling API Errors +```python +swarm = YourSwarmClass(workers) +worker = swarm.get_worker_by_id("worker_id") +swarm.remove_worker(worker) +``` -The Dalle3 library provides error handling for API-related issues. Here's how to handle and display API errors: +### `broadcast(message: str, sender: Optional["AbstractWorker"] = None)` -```python -from swarm_models.dalle3 import Dalle3 +The `broadcast()` method sends a message to all workers in the swarm. -# Create an instance of the Dalle3 class -dalle3 = Dalle3() +**Parameters:** +- `message` (str): The message to be broadcasted. +- `sender` (Optional[AbstractWorker]): The sender of the message (optional). -# Define a text prompt -task = "Invalid prompt that may cause an API error" +**Usage Example 1:** -try: - # Attempt to generate an image with an invalid prompt - image_url = dalle3(task) - print(image_url) -except Exception as e: - print(f"Error occurred: {str(e)}") +```python +swarm = YourSwarmClass(workers) +message = "Hello, everyone!" +swarm.broadcast(message) ``` -### Example 7: Customizing Image Quality - -You can customize the quality of the generated image by specifying the `quality` parameter. Here's how to generate a high-quality image: +**Usage Example 2:** ```python -from swarm_models.dalle3 import Dalle3 +# Another example of broadcasting a message +swarm = YourSwarmClass(workers) +message = "Important announcement!" +sender = swarm.get_worker_by_name("Supervisor") +swarm.broadcast(message, sender) +``` -# Create an instance of the Dalle3 class with high quality -dalle3 = Dalle3(quality="high") +### `reset()` -# Define a text prompt -task = "A high-quality image of a sunset" +The `reset()` method resets the swarm to its initial state. -# Generate a high-quality image from the text prompt -image_url = dalle3(task) +**Usage Example:** -# Print the generated image URL -print(image_url) +```python +swarm = YourSwarmClass(workers) +swarm.reset() ``` +### `plan(task: str)` ---- +The `plan()` method instructs workers to individually plan using a workflow or pipeline for a specified task. -## Error Handling +**Parameters:** +- `task` (str): The task for which workers should plan. -The Dalle3 library provides error handling for API-related issues. If an error occurs during API communication, the library will handle it and provide detailed error messages. Make sure to handle exceptions appropriately in your code. +**Usage Example:** ---- +```python +swarm = YourSwarmClass(workers) +task = "Perform data analysis" +swarm.plan(task) +``` -## Advanced Usage +### `direct_message(message: str, sender: "AbstractWorker", recipient: "AbstractWorker")` -For advanced usage and customization of the Dalle3 library, you can explore the attributes and methods of the `Dalle3` class. Adjusting parameters such as `size`, `max_retries`, and `quality` allows you to fine-tune the image generation process to your specific needs. +The `direct_message()` method sends a direct message from one worker to another. ---- +**Parameters:** +- `message` (str): The message to be sent. +- `sender` (AbstractWorker): The sender of the message. +- `recipient` (AbstractWorker): The recipient of the message. + +**Usage Example:** -## References +```python +swarm = YourSwarmClass(workers) +sender = swarm.get_worker_by_name("Worker1") +recipient = swarm.get_worker_by_name("Worker2") +message = "Hello -For more information about the DALL·E 3 model and the Dalle3 library, you can refer to the official OpenAI documentation and resources. +, Worker2!" +swarm.direct_message(message, sender, recipient) +``` -- [OpenAI API Documentation](https://beta.openai.com/docs/) -- [DALL·E 3 Model Information](https://openai.com/research/dall-e-3) -- [Dalle3 GitHub Repository](https://github.com/openai/dall-e-3) +### `autoscaler(num_workers: int, worker: List["AbstractWorker"])` ---- +The `autoscaler()` method acts as an autoscaler, dynamically adjusting the number of workers based on system load or other criteria. -This concludes the documentation for the Dalle3 library. You can now use the library to generate images from text prompts and explore its advanced features for various applications. +**Parameters:** +- `num_workers` (int): The desired number of workers. +- `worker` (List[AbstractWorker]): A list of workers to be managed by the autoscaler. --------------------------------------------------- +**Usage Example:** -# File: swarms/models/distilled_whisperx.md +```python +swarm = YourSwarmClass([]) +workers = [YourWorkerClass() for _ in range(10)] +swarm.autoscaler(5, workers) +``` -# DistilWhisperModel Documentation +### `get_worker_by_id(id: str) -> "AbstractWorker"` -## Overview +The `get_worker_by_id()` method locates a worker in the swarm by their ID. -The `DistilWhisperModel` is a Python class designed to handle English speech recognition tasks. It leverages the capabilities of the Whisper model, which is fine-tuned for speech-to-text processes. It is designed for both synchronous and asynchronous transcription of audio inputs, offering flexibility for real-time applications or batch processing. +**Parameters:** +- `id` (str): The ID of the worker to locate. -## Installation +**Returns:** +- `AbstractWorker`: The worker with the specified ID. -Before you can use `DistilWhisperModel`, ensure you have the required libraries installed: +**Usage Example:** -```sh -pip3 install --upgrade swarms +```python +swarm = YourSwarmClass(workers) +worker_id = "worker_123" +worker = swarm.get_worker_by_id(worker_id) ``` -## Initialization - -The `DistilWhisperModel` class is initialized with the following parameters: +### `get_worker_by_name(name: str) -> "AbstractWorker"` -| Parameter | Type | Description | Default | -|-----------|------|-------------|---------| -| `model_id` | `str` | The identifier for the pre-trained Whisper model | `"distil-whisper/distil-large-v2"` | +The `get_worker_by_name()` method locates a worker in the swarm by their name. -Example of initialization: +**Parameters:** +- `name` (str): The name of the worker to locate. -```python -from swarm_models import DistilWhisperModel +**Returns:** +- `AbstractWorker`: The worker with the specified name. -# Initialize with default model -model_wrapper = DistilWhisperModel() +**Usage Example:** -# Initialize with a specific model ID -model_wrapper = DistilWhisperModel(model_id="distil-whisper/distil-large-v2") +```python +swarm = YourSwarmClass(workers) +worker_name = "Alice" +worker = swarm.get_worker_by_name(worker_name) ``` -## Attributes +### `assign_task(worker: "AbstractWorker", task: Any) -> Dict` -After initialization, the `DistilWhisperModel` has several attributes: +The `assign_task()` method assigns a task to a specific worker. -| Attribute | Type | Description | -|-----------|------|-------------| -| `device` | `str` | The device used for computation (`"cuda:0"` for GPU or `"cpu"`). | -| `torch_dtype` | `torch.dtype` | The data type used for the Torch tensors. | -| `model_id` | `str` | The model identifier string. | -| `model` | `torch.nn.Module` | The actual Whisper model loaded from the identifier. | -| `processor` | `transformers.AutoProcessor` | The processor for handling input data. | +**Parameters:** +- `worker` (AbstractWorker): The worker to whom the task should be assigned. +- `task` (Any): The task to be assigned. -## Methods +**Returns:** +- `Dict`: A dictionary indicating the status of the task assignment. -### `transcribe` +**Usage Example:** -Transcribes audio input synchronously. +```python +swarm = YourSwarmClass(workers) +worker = swarm.get_worker_by_name("Worker1") +task = "Perform data analysis" +result = swarm.assign_task(worker, task) +``` -**Arguments**: +### `get_all_tasks(worker: "AbstractWorker", task: Any)` -| Argument | Type | Description | -|----------|------|-------------| -| `inputs` | `Union[str, dict]` | File path or audio data dictionary. | +The `get_all_tasks()` method retrieves all tasks assigned to a specific worker. -**Returns**: `str` - The transcribed text. +**Parameters:** +- `worker` (AbstractWorker): The worker for whom tasks should be retrieved. +- `task` (Any): The task to be retrieved. -**Usage Example**: +**Usage Example:** ```python -# Synchronous transcription -transcription = model_wrapper.transcribe("path/to/audio.mp3") -print(transcription) +swarm = YourSwarmClass(workers) +worker = swarm.get_worker_by_name("Worker1") +tasks = swarm.get_all_tasks(worker, "data analysis") ``` -### `async_transcribe` - -Transcribes audio input asynchronously. - -**Arguments**: +### `get_finished_tasks() -> List[Dict]` -| Argument | Type | Description | -|----------|------|-------------| -| `inputs` | `Union[str, dict]` | File path or audio data dictionary. | +The `get_finished_tasks()` method retrieves all tasks that have been completed by the workers in the swarm. -**Returns**: `Coroutine` - A coroutine that when awaited, returns the transcribed text. +**Returns:** +- `List[Dict]`: A list of dictionaries representing finished tasks. -**Usage Example**: +**Usage Example:** ```python -import asyncio - -# Asynchronous transcription -transcription = asyncio.run(model_wrapper.async_transcribe("path/to/audio.mp3")) -print(transcription) +swarm = YourSwarmClass(workers) +finished_tasks = swarm.get_finished_tasks() ``` -### `real_time_transcribe` - -Simulates real-time transcription of an audio file. +### `get_pending_tasks() -> List[Dict]` -**Arguments**: +The `get_pending_tasks()` method retrieves all tasks that are pending or yet to be completed by the workers in the swarm. -| Argument | Type | Description | -|----------|------|-------------| -| `audio_file_path` | `str` | Path to the audio file. | -| `chunk_duration` | `int` | Duration of audio chunks in seconds. | +**Returns:** +- `List[Dict]`: A list of dictionaries representing pending tasks. -**Usage Example**: +**Usage Example:** ```python -# Real-time transcription simulation -model_wrapper.real_time_transcribe("path/to/audio.mp3", chunk_duration=5) +swarm = YourSwarmClass(workers) +pending_tasks = swarm.get_pending_tasks() ``` -## Error Handling - -The `DistilWhisperModel` class incorporates error handling for file not found errors and generic exceptions during the transcription process. If a non-recoverable exception is raised, it is printed to the console in red to indicate failure. - -## Conclusion +### `pause_worker(worker: "AbstractWorker", worker_id: str)` -The `DistilWhisperModel` offers a convenient interface to the powerful Whisper model for speech recognition. Its design supports both batch and real-time transcription, catering to different application needs. The class's error handling and retry logic make it robust for real-world applications. +The `pause_worker()` method pauses a specific worker, temporarily suspending their activities. -## Additional Notes +**Parameters:** +- `worker` (AbstractWorker): The worker to be paused. +- `worker_id` (str): The ID of the worker to be paused. -- Ensure you have appropriate permissions to read audio files when using file paths. -- Transcription quality depends on the audio quality and the Whisper model's performance on your dataset. -- Adjust `chunk_duration` according to the processing power of your system for real-time transcription. +**Usage Example:** -For a full list of models supported by `transformers.AutoModelForSpeechSeq2Seq`, visit the [Hugging Face Model Hub](https://huggingface.co/models). +```python +swarm = YourSwarmClass(workers) +worker = swarm.get_worker_by_name("Worker1") +worker_id = "worker_123" +swarm.pause_worker(worker, worker_id) +``` +### `resume_worker(worker: "AbstractWorker", worker_id: str)` --------------------------------------------------- +The `resume_worker()` method resumes a paused worker, allowing them to continue their activities. -# File: swarms/models/fuyu.md +**Parameters:** +- `worker` (AbstractWorker): The worker to be resumed. +- `worker_id` (str): The ID of the worker to be resumed. -# Fuyu Documentation +**Usage Example:** -## Introduction +```python +swarm = YourSwarmClass(workers) +worker = swarm.get_worker_by_name("Worker1") +worker_id = "worker_123" +swarm.resume_worker(worker, worker_id) +``` -Welcome to the documentation for Fuyu, a versatile model for generating text conditioned on both textual prompts and images. Fuyu is based on the Adept's Fuyu model and offers a convenient way to create text that is influenced by the content of an image. In this documentation, you will find comprehensive information on the Fuyu class, its architecture, usage, and examples. +### `stop_worker(worker: "AbstractWorker", worker_id: str)` -## Overview +The `stop_worker()` method stops a specific worker, terminating their activities. -Fuyu is a text generation model that leverages both text and images to generate coherent and contextually relevant text. It combines state-of-the-art language modeling techniques with image processing capabilities to produce text that is semantically connected to the content of an image. Whether you need to create captions for images or generate text that describes visual content, Fuyu can assist you. +**Parameters:** +- `worker` (AbstractWorker): The worker to be stopped. +- `worker_id` (str): The ID of the worker to be stopped. -## Class Definition +**Usage Example:** ```python -class Fuyu: - def __init__( - self, - pretrained_path: str = "adept/fuyu-8b", - device_map: str = "cuda:0", - max_new_tokens: int = 7, - ): +swarm = YourSwarmClass(workers) +worker = swarm.get_worker_by_name("Worker1") +worker_id = "worker_123" +swarm.stop_worker(worker, worker_id) ``` -## Purpose - -The Fuyu class serves as a convenient interface for using the Adept's Fuyu model. It allows you to generate text based on a textual prompt and an image. The primary purpose of Fuyu is to provide a user-friendly way to create text that is influenced by visual content, making it suitable for various applications, including image captioning, storytelling, and creative text generation. - -## Parameters - -- `pretrained_path` (str): The path to the pretrained Fuyu model. By default, it uses the "adept/fuyu-8b" model. -- `device_map` (str): The device to use for model inference (e.g., "cuda:0" for GPU or "cpu" for CPU). Default: "cuda:0". -- `max_new_tokens` (int): The maximum number of tokens to generate in the output text. Default: 7. +### `restart_worker(worker: "AbstractWorker")` -## Usage +The `restart_worker()` method restarts a worker, resetting them to their initial state. -To use Fuyu, follow these steps: +**Parameters:** +- `worker` (AbstractWorker): The worker to be restarted. -1. Initialize the Fuyu instance: +**Usage Example:** ```python -from swarm_models.fuyu import Fuyu - -fuyu = Fuyu() +swarm = YourSwarmClass(workers) +worker = swarm.get_worker_by_name("Worker1") +swarm.restart_worker(worker) ``` +### `scale_up(num_worker: int)` -2. Generate Text with Fuyu: +The `scale_up()` method increases the number of workers in the swarm. -```python -text = "Hello, my name is" -img_path = "path/to/image.png" -output_text = fuyu(text, img_path) -``` +**Parameters:** +- `num_worker` (int): The number of workers to add to the swarm. -### Example 2 - Text Generation +**Usage Example:** ```python -from swarm_models.fuyu import Fuyu +swarm = YourSwarmClass(workers) +swarm.scale_up(5) +``` -fuyu = Fuyu() +### `scale_down(num_worker: int)` -text = "Hello, my name is" +The `scale_down()` method decreases the number of workers in the swarm. -img_path = "path/to/image.png" +**Parameters:** +- `num_worker` (int): The number of workers to remove from the swarm. -output_text = fuyu(text, img_path) -print(output_text) -``` +**Usage Example:** -## How Fuyu Works +```python +swarm = YourSwarmClass(workers) +swarm.scale_down(3) +``` -Fuyu combines text and image processing to generate meaningful text outputs. Here's how it works: +### `scale_to(num_worker: int)` -1. **Initialization**: When you create a Fuyu instance, you specify the pretrained model path, the device for inference, and the maximum number of tokens to generate. +The `scale_to()` method scales the swarm to a specific number of workers. -2. **Processing Text and Images**: Fuyu can process both textual prompts and images. You provide a text prompt and the path to an image as input. +**Parameters:** +- `num_worker` (int): The desired number of workers. -3. **Tokenization**: Fuyu tokenizes the input text and encodes the image using its tokenizer. +**Usage Example:** -4. **Model Inference**: The model takes the tokenized inputs and generates text that is conditioned on both the text and the image. +```python +swarm = YourSwarmClass(workers) +swarm.scale_to(10) +``` -5. **Output Text**: Fuyu returns the generated text as the output. +### `get -## Additional Information +_all_workers() -> List["AbstractWorker"]` -- Fuyu uses the Adept's Fuyu model, which is pretrained on a large corpus of text and images, making it capable of generating coherent and contextually relevant text. -- You can specify the device for inference to utilize GPU acceleration if available. -- The `max_new_tokens` parameter allows you to control the length of the generated text. +The `get_all_workers()` method retrieves a list of all workers in the swarm. -That concludes the documentation for Fuyu. We hope you find this model useful for your text generation tasks that involve images. If you have any questions or encounter any issues, please refer to the Fuyu documentation for further assistance. Enjoy working with Fuyu! - --------------------------------------------------- - -# File: swarms/models/gemini.md - -## `Gemini` Documentation - -### Introduction - -The Gemini module is a versatile tool for leveraging the power of multimodal AI models to generate content. It allows users to combine textual and image inputs to generate creative and informative outputs. In this documentation, we will explore the Gemini module in detail, covering its purpose, architecture, methods, and usage examples. - -#### Purpose - -The Gemini module is designed to bridge the gap between text and image data, enabling users to harness the capabilities of multimodal AI models effectively. By providing both a textual task and an image as input, Gemini generates content that aligns with the specified task and incorporates the visual information from the image. - -### Installation +**Returns:** +- `List[AbstractWorker]`: A list of all workers in the swarm. -Before using Gemini, ensure that you have the required dependencies installed. You can install them using the following commands: +**Usage Example:** -```bash -pip install swarms -pip install google-generativeai -pip install python-dotenv +```python +swarm = YourSwarmClass(workers) +all_workers = swarm.get_all_workers() ``` -### Class: Gemini +### `get_swarm_size() -> int` -#### Overview +The `get_swarm_size()` method returns the size of the swarm, which is the total number of workers. -The `Gemini` class is the central component of the Gemini module. It inherits from the `BaseMultiModalModel` class and provides methods to interact with the Gemini AI model. Let's dive into its architecture and functionality. +**Returns:** +- `int`: The size of the swarm. -##### Class Constructor +**Usage Example:** ```python -class Gemini(BaseMultiModalModel): - def __init__( - self, - model_name: str = "gemini-pro", - gemini_api_key: str = get_gemini_api_key_env, - *args, - **kwargs, - ): +swarm = YourSwarmClass(workers) +swarm_size = swarm.get_swarm_size() ``` -| Parameter | Type | Description | Default Value | -|---------------------|---------|------------------------------------------------------------------|--------------------| -| `model_name` | str | The name of the Gemini model. | "gemini-pro" | -| `gemini_api_key` | str | The Gemini API key. If not provided, it is fetched from the environment. | (None) | - -- `model_name`: Specifies the name of the Gemini model to use. By default, it is set to "gemini-pro," but you can specify a different model if needed. - -- `gemini_api_key`: This parameter allows you to provide your Gemini API key directly. If not provided, the constructor attempts to fetch it from the environment using the `get_gemini_api_key_env` helper function. - -##### Methods - -1. **run()** - - ```python - def run( - self, - task: str = None, - img: str = None, - *args, - **kwargs, - ) -> str: - ``` - - | Parameter | Type | Description | - |---------------|----------|--------------------------------------------| - | `task` | str | The textual task for content generation. | - | `img` | str | The path to the image to be processed. | - | `*args` | Variable | Additional positional arguments. | - | `**kwargs` | Variable | Additional keyword arguments. | - - - `task`: Specifies the textual task for content generation. It can be a sentence or a phrase that describes the desired content. - - - `img`: Provides the path to the image that will be processed along with the textual task. Gemini combines the visual information from the image with the textual task to generate content. - - - `*args` and `**kwargs`: Allow for additional, flexible arguments that can be passed to the underlying Gemini model. These arguments can vary based on the specific Gemini model being used. - - **Returns**: A string containing the generated content. - - **Examples**: - - ```python - from swarm_models import Gemini - - # Initialize the Gemini model - gemini = Gemini() - - # Generate content for a textual task with an image - generated_content = gemini.run( - task="Describe this image", - img="image.jpg", - ) - - # Print the generated content - print(generated_content) - ``` - - In this example, we initialize the Gemini model, provide a textual task, and specify an image for processing. The `run()` method generates content based on the input and returns the result. +### `get_swarm_status() -> Dict` -2. **process_img()** +The `get_swarm_status()` method provides information about the current status of the swarm. - ```python - def process_img( - self, - img: str = None, - type: str = "image/png", - *args, - **kwargs, - ): - ``` +**Returns:** +- `Dict`: A dictionary containing various status indicators for the swarm. - | Parameter | Type | Description | Default Value | - |---------------|----------|------------------------------------------------------|----------------| - | `img` | str | The path to the image to be processed. | (None) | - | `type` | str | The MIME type of the image (e.g., "image/png"). | "image/png" | - | `*args` | Variable | Additional positional arguments. | - | `**kwargs` | Variable | Additional keyword arguments. | +**Usage Example:** - - `img`: Specifies the path to the image that will be processed. It's essential to provide a valid image path for image-based content generation. +```python +swarm = YourSwarmClass(workers) +swarm_status = swarm.get_swarm_status() +``` - - `type`: Indicates the MIME type of the image. By default, it is set to "image/png," but you can change it based on the image format you're using. +### `save_swarm_state()` - - `*args` and `**kwargs`: Allow for additional, flexible arguments that can be passed to the underlying Gemini model. These arguments can vary based on the specific Gemini model being used. +The `save_swarm_state()` method allows you to save the current state of the swarm, including worker configurations and task assignments. - **Raises**: ValueError if any of the following conditions are met: - - No image is provided. - - The image type is not specified. - - The Gemini API key is missing. +**Usage Example:** - **Examples**: +```python +swarm = YourSwarmClass(workers) +swarm.save_swarm_state() +``` - ```python - from swarm_models.gemini import Gemini +--- - # Initialize the Gemini model - gemini = Gemini() +This comprehensive documentation covers the Swarms library, including the `BaseSwarm` class and its methods. You can use this documentation as a guide to understanding and effectively utilizing the Swarms framework for swarm simulation architectures. Feel free to explore further and adapt the library to your specific use cases. - # Process an image - processed_image = gemini.process_img( - img="image.jpg", - type="image/jpeg", - ) +-------------------------------------------------- - # Further use the processed image in content generation - generated_content = gemini.run( - task="Describe this image", - img=processed_image, - ) +# File: swarms\structs\agent.md - # Print the generated content - print(generated_content) - ``` +# `Agent` - In this example, we demonstrate how to process an image using the `process_img()` method and then use the processed image in content generation. +Swarm Agent is a powerful autonomous agent framework designed to connect Language Models (LLMs) with various tools and long-term memory. This class provides the ability to ingest and process various types of documents such as PDFs, text files, Markdown files, JSON files, and more. The Agent structure offers a wide range of features to enhance the capabilities of LLMs and facilitate efficient task execution. -#### Additional Information +## Overview -- Gemini is designed to work seamlessly with various multimodal AI models, making it a powerful tool for content generation tasks. +The `Agent` class establishes a conversational loop with a language model, allowing for interactive task execution, feedback collection, and dynamic response generation. It includes features such as: -- The module uses the `google.generativeai` package to access the underlying AI models. Ensure that you have this package installed to leverage the full capabilities of Gemini. +1. **Conversational Loop**: Enables back-and-forth interaction with the model. +2. **Feedback Collection**: Allows users to provide feedback on generated responses. +3. **Stoppable Conversation**: Supports custom stopping conditions for the conversation. +4. **Retry Mechanism**: Implements a retry system for handling issues in response generation. +5. **Tool Integration**: Supports the integration of various tools for enhanced capabilities. +6. **Long-term Memory Management**: Incorporates vector databases for efficient information retrieval. +7. **Document Ingestion**: Processes various document types for information extraction. +8. **Interactive Mode**: Allows real-time communication with the agent. +9. **Sentiment Analysis**: Evaluates the sentiment of generated responses. +10. **Output Filtering and Cleaning**: Ensures generated responses meet specific criteria. +11. **Asynchronous and Concurrent Execution**: Supports efficient parallelization of tasks. +12. **Planning and Reasoning**: Implements techniques like algorithm of thoughts for enhanced decision-making. -- It's essential to provide a valid Gemini API key for authentication. You can either pass it directly during initialization or store it in the environment variable "GEMINI_API_KEY." -- Gemini's flexibility allows you to experiment with different Gemini models and tailor the content generation process to your specific needs. +## Architecture -- Keep in mind that Gemini is designed to handle both textual and image inputs, making it a valuable asset for various applications, including natural language processing and computer vision tasks. +```mermaid +graph TD + A[Task Initiation] -->|Receives Task| B[Initial LLM Processing] + B -->|Interprets Task| C[Tool Usage] + C -->|Calls Tools| D[Function 1] + C -->|Calls Tools| E[Function 2] + D -->|Returns Data| C + E -->|Returns Data| C + C -->|Provides Data| F[Memory Interaction] + F -->|Stores and Retrieves Data| G[RAG System] + G -->|ChromaDB/Pinecone| H[Enhanced Data] + F -->|Provides Enhanced Data| I[Final LLM Processing] + I -->|Generates Final Response| J[Output] + C -->|No Tools Available| K[Skip Tool Usage] + K -->|Proceeds to Memory Interaction| F + F -->|No Memory Available| L[Skip Memory Interaction] + L -->|Proceeds to Final LLM Processing| I +``` -- If you encounter any issues or have specific requirements, refer to the Gemini documentation for more details and advanced usage. -### References and Resources +## `Agent` Attributes -- [Gemini GitHub Repository](https://github.com/swarms/gemini): Explore the Gemini repository for additional information, updates, and examples. +| Attribute | Description | +|-----------|-------------| +| `id` | Unique identifier for the agent instance. | +| `llm` | Language model instance used by the agent. | +| `template` | Template used for formatting responses. | +| `max_loops` | Maximum number of loops the agent can run. | +| `stopping_condition` | Callable function determining when to stop looping. | +| `loop_interval` | Interval (in seconds) between loops. | +| `retry_attempts` | Number of retry attempts for failed LLM calls. | +| `retry_interval` | Interval (in seconds) between retry attempts. | +| `return_history` | Boolean indicating whether to return conversation history. | +| `stopping_token` | Token that stops the agent from looping when present in the response. | +| `dynamic_loops` | Boolean indicating whether to dynamically determine the number of loops. | +| `interactive` | Boolean indicating whether to run in interactive mode. | +| `dashboard` | Boolean indicating whether to display a dashboard. | +| `agent_name` | Name of the agent instance. | +| `agent_description` | Description of the agent instance. | +| `system_prompt` | System prompt used to initialize the conversation. | +| `tools` | List of callable functions representing tools the agent can use. | +| `dynamic_temperature_enabled` | Boolean indicating whether to dynamically adjust the LLM's temperature. | +| `sop` | Standard operating procedure for the agent. | +| `sop_list` | List of strings representing the standard operating procedure. | +| `saved_state_path` | File path for saving and loading the agent's state. | +| `autosave` | Boolean indicating whether to automatically save the agent's state. | +| `context_length` | Maximum length of the context window (in tokens) for the LLM. | +| `user_name` | Name used to represent the user in the conversation. | +| `self_healing_enabled` | Boolean indicating whether to attempt self-healing in case of errors. | +| `code_interpreter` | Boolean indicating whether to interpret and execute code snippets. | +| `multi_modal` | Boolean indicating whether to support multimodal inputs. | +| `pdf_path` | File path of a PDF document to be ingested. | +| `list_of_pdf` | List of file paths for PDF documents to be ingested. | +| `tokenizer` | Instance of a tokenizer used for token counting and management. | +| `long_term_memory` | Instance of a `BaseVectorDatabase` implementation for long-term memory management. | +| `preset_stopping_token` | Boolean indicating whether to use a preset stopping token. | +| `traceback` | Object used for traceback handling. | +| `traceback_handlers` | List of traceback handlers. | +| `streaming_on` | Boolean indicating whether to stream responses. | +| `docs` | List of document paths or contents to be ingested. | +| `docs_folder` | Path to a folder containing documents to be ingested. | +| `verbose` | Boolean indicating whether to print verbose output. | +| `parser` | Callable function used for parsing input data. | +| `best_of_n` | Integer indicating the number of best responses to generate. | +| `callback` | Callable function to be called after each agent loop. | +| `metadata` | Dictionary containing metadata for the agent. | +| `callbacks` | List of callable functions to be called during execution. | +| `logger_handler` | Handler for logging messages. | +| `search_algorithm` | Callable function for long-term memory retrieval. | +| `logs_to_filename` | File path for logging agent activities. | +| `evaluator` | Callable function for evaluating the agent's responses. | +| `stopping_func` | Callable function used as a stopping condition. | +| `custom_loop_condition` | Callable function used as a custom loop condition. | +| `sentiment_threshold` | Float value representing the sentiment threshold for evaluating responses. | +| `custom_exit_command` | String representing a custom command for exiting the agent's loop. | +| `sentiment_analyzer` | Callable function for sentiment analysis on outputs. | +| `limit_tokens_from_string` | Callable function for limiting the number of tokens in a string. | +| `custom_tools_prompt` | Callable function for generating a custom prompt for tool usage. | +| `tool_schema` | Data structure representing the schema for the agent's tools. | +| `output_type` | Type representing the expected output type of responses. | +| `function_calling_type` | String representing the type of function calling. | +| `output_cleaner` | Callable function for cleaning the agent's output. | +| `function_calling_format_type` | String representing the format type for function calling. | +| `list_base_models` | List of base models used for generating tool schemas. | +| `metadata_output_type` | String representing the output type for metadata. | +| `state_save_file_type` | String representing the file type for saving the agent's state. | +| `chain_of_thoughts` | Boolean indicating whether to use the chain of thoughts technique. | +| `algorithm_of_thoughts` | Boolean indicating whether to use the algorithm of thoughts technique. | +| `tree_of_thoughts` | Boolean indicating whether to use the tree of thoughts technique. | +| `tool_choice` | String representing the method for tool selection. | +| `execute_tool` | Boolean indicating whether to execute tools. | +| `rules` | String representing the rules for the agent's behavior. | +| `planning` | Boolean indicating whether to perform planning. | +| `planning_prompt` | String representing the prompt for planning. | +| `device` | String representing the device on which the agent should run. | +| `custom_planning_prompt` | String representing a custom prompt for planning. | +| `memory_chunk_size` | Integer representing the maximum size of memory chunks for long-term memory retrieval. | +| `agent_ops_on` | Boolean indicating whether agent operations should be enabled. | +| `return_step_meta` | Boolean indicating whether to return JSON of all steps and additional metadata. | +| `output_type` | Literal type indicating whether to output "string", "str", "list", "json", "dict", or "yaml". | +| `time_created` | Float representing the time the agent was created. | +| `tags` | Optional list of strings for tagging the agent. | +| `use_cases` | Optional list of dictionaries describing use cases for the agent. | +| `step_pool` | List of Step objects representing the agent's execution steps. | +| `print_every_step` | Boolean indicating whether to print every step of execution. | +| `agent_output` | ManySteps object containing the agent's output and metadata. | +| `executor_workers` | Integer representing the number of executor workers for concurrent operations. | +| `data_memory` | Optional callable for data memory operations. | +| `load_yaml_path` | String representing the path to a YAML file for loading configurations. | +| `auto_generate_prompt` | Boolean indicating whether to automatically generate prompts. | +| `rag_every_loop` | Boolean indicating whether to query RAG database for context on every loop | +| `plan_enabled` | Boolean indicating whether planning functionality is enabled | +| `artifacts_on` | Boolean indicating whether to save artifacts from agent execution | +| `artifacts_output_path` | File path where artifacts should be saved | +| `artifacts_file_extension` | File extension to use for saved artifacts | +| `device` | Device to run computations on ("cpu" or "gpu") | +| `all_cores` | Boolean indicating whether to use all CPU cores | +| `device_id` | ID of the GPU device to use if running on GPU | +| `scheduled_run_date` | Optional datetime for scheduling future agent runs | -- [Google GenerativeAI Documentation](https://docs.google.com/document/d/1WZSBw6GsOhOCYm0ArydD_9uy6nPPA1KFIbKPhjj43hA): Dive deeper into the capabilities of the Google GenerativeAI package used by Gemini. -- [Gemini API Documentation](https://gemini-api-docs.example.com): Access the official documentation for the Gemini API to explore advanced features and integrations. +## `Agent` Methods -## Conclusion +| Method | Description | Inputs | Usage Example | +|--------|-------------|--------|----------------| +| `run(task, img=None, is_last=False, device="cpu", device_id=0, all_cores=True, *args, **kwargs)` | Runs the autonomous agent loop to complete the given task. | `task` (str): The task to be performed.
`img` (str, optional): Path to an image file.
`is_last` (bool): Whether this is the last task.
`device` (str): Device to run on ("cpu" or "gpu").
`device_id` (int): ID of the GPU to use.
`all_cores` (bool): Whether to use all CPU cores.
`*args`, `**kwargs`: Additional arguments. | `response = agent.run("Generate a report on financial performance.")` | +| `__call__(task, img=None, *args, **kwargs)` | Alternative way to call the `run` method. | Same as `run`. | `response = agent("Generate a report on financial performance.")` | +| `parse_and_execute_tools(response, *args, **kwargs)` | Parses the agent's response and executes any tools mentioned in it. | `response` (str): The agent's response to be parsed.
`*args`, `**kwargs`: Additional arguments. | `agent.parse_and_execute_tools(response)` | +| `add_memory(message)` | Adds a message to the agent's memory. | `message` (str): The message to add. | `agent.add_memory("Important information")` | +| `plan(task, *args, **kwargs)` | Plans the execution of a task. | `task` (str): The task to plan.
`*args`, `**kwargs`: Additional arguments. | `agent.plan("Analyze market trends")` | +| `run_concurrent(task, *args, **kwargs)` | Runs a task concurrently. | `task` (str): The task to run.
`*args`, `**kwargs`: Additional arguments. | `response = await agent.run_concurrent("Concurrent task")` | +| `run_concurrent_tasks(tasks, *args, **kwargs)` | Runs multiple tasks concurrently. | `tasks` (List[str]): List of tasks to run.
`*args`, `**kwargs`: Additional arguments. | `responses = agent.run_concurrent_tasks(["Task 1", "Task 2"])` | +| `bulk_run(inputs)` | Generates responses for multiple input sets. | `inputs` (List[Dict[str, Any]]): List of input dictionaries. | `responses = agent.bulk_run([{"task": "Task 1"}, {"task": "Task 2"}])` | +| `save()` | Saves the agent's history to a file. | None | `agent.save()` | +| `load(file_path)` | Loads the agent's history from a file. | `file_path` (str): Path to the file. | `agent.load("agent_history.json")` | +| `graceful_shutdown()` | Gracefully shuts down the system, saving the state. | None | `agent.graceful_shutdown()` | +| `analyze_feedback()` | Analyzes the feedback for issues. | None | `agent.analyze_feedback()` | +| `undo_last()` | Undoes the last response and returns the previous state. | None | `previous_state, message = agent.undo_last()` | +| `add_response_filter(filter_word)` | Adds a response filter to filter out certain words. | `filter_word` (str): Word to filter. | `agent.add_response_filter("sensitive")` | +| `apply_response_filters(response)` | Applies response filters to the given response. | `response` (str): Response to filter. | `filtered_response = agent.apply_response_filters(response)` | +| `filtered_run(task)` | Runs a task with response filtering applied. | `task` (str): Task to run. | `response = agent.filtered_run("Generate a report")` | +| `save_to_yaml(file_path)` | Saves the agent to a YAML file. | `file_path` (str): Path to save the YAML file. | `agent.save_to_yaml("agent_config.yaml")` | +| `get_llm_parameters()` | Returns the parameters of the language model. | None | `llm_params = agent.get_llm_parameters()` | +| `save_state(file_path, *args, **kwargs)` | Saves the current state of the agent to a JSON file. | `file_path` (str): Path to save the JSON file.
`*args`, `**kwargs`: Additional arguments. | `agent.save_state("agent_state.json")` | +| `update_system_prompt(system_prompt)` | Updates the system prompt. | `system_prompt` (str): New system prompt. | `agent.update_system_prompt("New system instructions")` | +| `update_max_loops(max_loops)` | Updates the maximum number of loops. | `max_loops` (int): New maximum number of loops. | `agent.update_max_loops(5)` | +| `update_loop_interval(loop_interval)` | Updates the loop interval. | `loop_interval` (int): New loop interval. | `agent.update_loop_interval(2)` | +| `update_retry_attempts(retry_attempts)` | Updates the number of retry attempts. | `retry_attempts` (int): New number of retry attempts. | `agent.update_retry_attempts(3)` | +| `update_retry_interval(retry_interval)` | Updates the retry interval. | `retry_interval` (int): New retry interval. | `agent.update_retry_interval(5)` | +| `reset()` | Resets the agent's memory. | None | `agent.reset()` | +| `ingest_docs(docs, *args, **kwargs)` | Ingests documents into the agent's memory. | `docs` (List[str]): List of document paths.
`*args`, `**kwargs`: Additional arguments. | `agent.ingest_docs(["doc1.pdf", "doc2.txt"])` | +| `ingest_pdf(pdf)` | Ingests a PDF document into the agent's memory. | `pdf` (str): Path to the PDF file. | `agent.ingest_pdf("document.pdf")` | +| `receive_message(name, message)` | Receives a message and adds it to the agent's memory. | `name` (str): Name of the sender.
`message` (str): Content of the message. | `agent.receive_message("User", "Hello, agent!")` | +| `send_agent_message(agent_name, message, *args, **kwargs)` | Sends a message from the agent to a user. | `agent_name` (str): Name of the agent.
`message` (str): Message to send.
`*args`, `**kwargs`: Additional arguments. | `response = agent.send_agent_message("AgentX", "Task completed")` | +| `add_tool(tool)` | Adds a tool to the agent's toolset. | `tool` (Callable): Tool to add. | `agent.add_tool(my_custom_tool)` | +| `add_tools(tools)` | Adds multiple tools to the agent's toolset. | `tools` (List[Callable]): List of tools to add. | `agent.add_tools([tool1, tool2])` | +| `remove_tool(tool)` | Removes a tool from the agent's toolset. || Method | Description | Inputs | Usage Example | +|--------|-------------|--------|----------------| +| `remove_tool(tool)` | Removes a tool from the agent's toolset. | `tool` (Callable): Tool to remove. | `agent.remove_tool(my_custom_tool)` | +| `remove_tools(tools)` | Removes multiple tools from the agent's toolset. | `tools` (List[Callable]): List of tools to remove. | `agent.remove_tools([tool1, tool2])` | +| `get_docs_from_doc_folders()` | Retrieves and processes documents from the specified folder. | None | `agent.get_docs_from_doc_folders()` | +| `memory_query(task, *args, **kwargs)` | Queries the long-term memory for relevant information. | `task` (str): The task or query.
`*args`, `**kwargs`: Additional arguments. | `result = agent.memory_query("Find information about X")` | +| `sentiment_analysis_handler(response)` | Performs sentiment analysis on the given response. | `response` (str): The response to analyze. | `agent.sentiment_analysis_handler("Great job!")` | +| `count_and_shorten_context_window(history, *args, **kwargs)` | Counts tokens and shortens the context window if necessary. | `history` (str): The conversation history.
`*args`, `**kwargs`: Additional arguments. | `shortened_history = agent.count_and_shorten_context_window(history)` | +| `output_cleaner_and_output_type(response, *args, **kwargs)` | Cleans and formats the output based on specified type. | `response` (str): The response to clean and format.
`*args`, `**kwargs`: Additional arguments. | `cleaned_response = agent.output_cleaner_and_output_type(response)` | +| `stream_response(response, delay=0.001)` | Streams the response token by token. | `response` (str): The response to stream.
`delay` (float): Delay between tokens. | `agent.stream_response("This is a streamed response")` | +| `dynamic_context_window()` | Dynamically adjusts the context window. | None | `agent.dynamic_context_window()` | +| `check_available_tokens()` | Checks and returns the number of available tokens. | None | `available_tokens = agent.check_available_tokens()` | +| `tokens_checks()` | Performs token checks and returns available tokens. | None | `token_info = agent.tokens_checks()` | +| `truncate_string_by_tokens(input_string, limit)` | Truncates a string to fit within a token limit. | `input_string` (str): String to truncate.
`limit` (int): Token limit. | `truncated_string = agent.truncate_string_by_tokens("Long string", 100)` | +| `tokens_operations(input_string)` | Performs various token-related operations on the input string. | `input_string` (str): String to process. | `processed_string = agent.tokens_operations("Input string")` | +| `parse_function_call_and_execute(response)` | Parses a function call from the response and executes it. | `response` (str): Response containing the function call. | `result = agent.parse_function_call_and_execute(response)` | +| `llm_output_parser(response)` | Parses the output from the language model. | `response` (Any): Response from the LLM. | `parsed_response = agent.llm_output_parser(llm_output)` | +| `log_step_metadata(loop, task, response)` | Logs metadata for each step of the agent's execution. | `loop` (int): Current loop number.
`task` (str): Current task.
`response` (str): Agent's response. | `agent.log_step_metadata(1, "Analyze data", "Analysis complete")` | +| `to_dict()` | Converts the agent's attributes to a dictionary. | None | `agent_dict = agent.to_dict()` | +| `to_json(indent=4, *args, **kwargs)` | Converts the agent's attributes to a JSON string. | `indent` (int): Indentation for JSON.
`*args`, `**kwargs`: Additional arguments. | `agent_json = agent.to_json()` | +| `to_yaml(indent=4, *args, **kwargs)` | Converts the agent's attributes to a YAML string. | `indent` (int): Indentation for YAML.
`*args`, `**kwargs`: Additional arguments. | `agent_yaml = agent.to_yaml()` | +| `to_toml(*args, **kwargs)` | Converts the agent's attributes to a TOML string. | `*args`, `**kwargs`: Additional arguments. | `agent_toml = agent.to_toml()` | +| `model_dump_json()` | Saves the agent model to a JSON file in the workspace directory. | None | `agent.model_dump_json()` | +| `model_dump_yaml()` | Saves the agent model to a YAML file in the workspace directory. | None | `agent.model_dump_yaml()` | +| `log_agent_data()` | Logs the agent's data to an external API. | None | `agent.log_agent_data()` | +| `handle_tool_schema_ops()` | Handles operations related to tool schemas. | None | `agent.handle_tool_schema_ops()` | +| `call_llm(task, *args, **kwargs)` | Calls the appropriate method on the language model. | `task` (str): Task for the LLM.
`*args`, `**kwargs`: Additional arguments. | `response = agent.call_llm("Generate text")` | +| `handle_sop_ops()` | Handles operations related to standard operating procedures. | None | `agent.handle_sop_ops()` | +| `agent_output_type(responses)` | Processes and returns the agent's output based on the specified output type. | `responses` (list): List of responses. | `formatted_output = agent.agent_output_type(responses)` | +| `check_if_no_prompt_then_autogenerate(task)` | Checks if a system prompt is not set and auto-generates one if needed. | `task` (str): The task to use for generating a prompt. | `agent.check_if_no_prompt_then_autogenerate("Analyze data")` | +| `check_if_no_prompt_then_autogenerate(task)` | Checks if auto_generate_prompt is enabled and generates a prompt by combining agent name, description and system prompt | `task` (str, optional): Task to use as fallback | `agent.check_if_no_prompt_then_autogenerate("Analyze data")` | +| `handle_artifacts(response, output_path, extension)` | Handles saving artifacts from agent execution | `response` (str): Agent response
`output_path` (str): Output path
`extension` (str): File extension | `agent.handle_artifacts(response, "outputs/", ".txt")` | -In this comprehensive documentation, we've explored the Gemini module, its purpose, architecture, methods, and usage examples. Gemini empowers developers to generate content by combining textual tasks and images, making it a valuable asset for multimodal AI applications. Whether you're working on natural language processing or computer vision projects, Gemini can help you achieve impressive results. --------------------------------------------------- -# File: swarms/models/gpt4v.md +## Updated Run Method -# `GPT4VisionAPI` Documentation +Update the run method documentation to include new parameters: -**Table of Contents** -- [Introduction](#introduction) -- [Installation](#installation) -- [Module Overview](#module-overview) -- [Class: GPT4VisionAPI](#class-gpt4visionapi) - - [Initialization](#initialization) - - [Methods](#methods) - - [encode_image](#encode_image) - - [run](#run) - - [__call__](#__call__) -- [Examples](#examples) - - [Example 1: Basic Usage](#example-1-basic-usage) - - [Example 2: Custom API Key](#example-2-custom-api-key) - - [Example 3: Adjusting Maximum Tokens](#example-3-adjusting-maximum-tokens) -- [Additional Information](#additional-information) -- [References](#references) +| Method | Description | Inputs | Usage Example | +|--------|-------------|--------|----------------| +| `run(task, img=None, is_last=False, device="cpu", device_id=0, all_cores=True, scheduled_run_date=None)` | Runs the agent with specified parameters | `task` (str): Task to run
`img` (str, optional): Image path
`is_last` (bool): If this is last task
`device` (str): Device to use
`device_id` (int): GPU ID
`all_cores` (bool): Use all CPU cores
`scheduled_run_date` (datetime, optional): Future run date | `agent.run("Analyze data", device="gpu", device_id=0)` | -## Introduction -Welcome to the documentation for the `GPT4VisionAPI` module! This module is a powerful wrapper for the OpenAI GPT-4 Vision model. It allows you to interact with the model to generate descriptions or answers related to images. This documentation will provide you with comprehensive information on how to use this module effectively. -## Installation +## Getting Started -Before you start using the `GPT4VisionAPI` module, make sure you have the required dependencies installed. You can install them using the following commands: +To use the Swarm Agent, first install the required dependencies: ```bash -pip3 install --upgrade swarms +pip3 install -U swarms ``` -## Module Overview +Then, you can initialize and use the agent as follows: -The `GPT4VisionAPI` module serves as a bridge between your application and the OpenAI GPT-4 Vision model. It allows you to send requests to the model and retrieve responses related to images. Here are some key features and functionality provided by this module: +```python +from swarms.structs.agent import Agent +from swarms.prompts.finance_agent_sys_prompt import FINANCIAL_AGENT_SYS_PROMPT -- Encoding images to base64 format. -- Running the GPT-4 Vision model with specified tasks and images. -- Customization options such as setting the OpenAI API key and maximum token limit. +# Initialize the Financial Analysis Agent with GPT-4o-mini model +agent = Agent( + agent_name="Financial-Analysis-Agent", + system_prompt=FINANCIAL_AGENT_SYS_PROMPT, + model_name="gpt-4o-mini", + max_loops=1, + autosave=True, + dashboard=False, + verbose=True, + dynamic_temperature_enabled=True, + saved_state_path="finance_agent.json", + user_name="swarms_corp", + retry_attempts=1, + context_length=200000, + return_step_meta=False, + output_type="str", +) -## Class: GPT4VisionAPI +# Run the agent +response = agent.run( + "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?" +) +print(response) -The `GPT4VisionAPI` class is the core component of this module. It encapsulates the functionality required to interact with the GPT-4 Vision model. Below, we'll dive into the class in detail. +``` -### Initialization +## Advanced Usage -When initializing the `GPT4VisionAPI` class, you have the option to provide the OpenAI API key and set the maximum token limit. Here are the parameters and their descriptions: +### Tool Integration -| Parameter | Type | Default Value | Description | -|---------------------|----------|-------------------------------|----------------------------------------------------------------------------------------------------------| -| openai_api_key | str | `OPENAI_API_KEY` environment variable (if available) | The OpenAI API key. If not provided, it defaults to the `OPENAI_API_KEY` environment variable. | -| max_tokens | int | 300 | The maximum number of tokens to generate in the model's response. | +To integrate tools with the Swarm `Agent`, you can pass a list of callable functions with types and doc strings to the `tools` parameter when initializing the `Agent` instance. The agent will automatically convert these functions into an OpenAI function calling schema and make them available for use during task execution. -Here's how you can initialize the `GPT4VisionAPI` class: +## Requirements for a tool +- Function + - With types + - with doc strings ```python -from swarm_models import GPT4VisionAPI - -# Initialize with default API key and max_tokens -api = GPT4VisionAPI() - -# Initialize with custom API key and max_tokens -custom_api_key = "your_custom_api_key" -api = GPT4VisionAPI(openai_api_key=custom_api_key, max_tokens=500) -``` - -### Methods - -#### encode_image - -This method allows you to encode an image from a URL to base64 format. It's a utility function used internally by the module. +from swarms import Agent +from swarm_models import OpenAIChat +import subprocess -```python -def encode_image(img: str) -> str: +def terminal(code: str): """ - Encode image to base64. + Run code in the terminal. - Parameters: - - img (str): URL of the image to encode. + Args: + code (str): The code to run in the terminal. Returns: - str: Base64 encoded image. + str: The output of the code. """ + out = subprocess.run(code, shell=True, capture_output=True, text=True).stdout + return str(out) + +# Initialize the agent with a tool +agent = Agent( + agent_name="Terminal-Agent", + llm=OpenAIChat(api_key=os.getenv("OPENAI_API_KEY")), + tools=[terminal], + system_prompt="You are an agent that can execute terminal commands. Use the tools provided to assist the user.", +) + +# Run the agent +response = agent.run("List the contents of the current directory") +print(response) ``` -#### run +### Long-term Memory Management -The `run` method is the primary way to interact with the GPT-4 Vision model. It sends a request to the model with a task and an image URL, and it returns the model's response. +The Swarm Agent supports integration with vector databases for long-term memory management. Here's an example using ChromaDB: ```python -def run(task: str, img: str) -> str: - """ - Run the GPT-4 Vision model. +from swarms import Agent +from swarm_models import Anthropic +from swarms_memory import ChromaDB - Parameters: - - task (str): The task or question related to the image. - - img (str): URL of the image to analyze. +# Initialize ChromaDB +chromadb = ChromaDB( + metric="cosine", + output_dir="finance_agent_rag", +) - Returns: - str: The model's response. - """ +# Initialize the agent with long-term memory +agent = Agent( + agent_name="Financial-Analysis-Agent", + llm=Anthropic(anthropic_api_key=os.getenv("ANTHROPIC_API_KEY")), + long_term_memory=chromadb, + system_prompt="You are a financial analysis agent with access to long-term memory.", +) + +# Run the agent +response = agent.run("What are the components of a startup's stock incentive equity plan?") +print(response) ``` -#### __call__ +### Interactive Mode -The `__call__` method is a convenient way to run the GPT-4 Vision model. It has the same functionality as the `run` method. +To enable interactive mode, set the `interactive` parameter to `True` when initializing the `Agent`: ```python -def __call__(task: str, img: str) -> str: - """ - Run the GPT-4 Vision model (callable). - - Parameters: - - task (str): The task or question related to the image. - - img - - (str): URL of the image to analyze. +agent = Agent( + agent_name="Interactive-Agent", + llm=OpenAIChat(api_key=os.getenv("OPENAI_API_KEY")), + interactive=True, + system_prompt="You are an interactive agent. Engage in a conversation with the user.", +) - Returns: - str: The model's response. - """ +# Run the agent in interactive mode +agent.run("Let's start a conversation") ``` -## Examples - -Let's explore some usage examples of the `GPT4VisionAPI` module to better understand how to use it effectively. - -### Example 1: Basic Usage +### Sentiment Analysis -In this example, we'll use the module with the default API key and maximum tokens to analyze an image. +To perform sentiment analysis on the agent's outputs, you can provide a sentiment analyzer function: ```python -from swarm_models import GPT4VisionAPI - -# Initialize with default API key and max_tokens -api = GPT4VisionAPI() +from textblob import TextBlob -# Define the task and image URL -task = "What is the color of the object?" -img = "https://i.imgur.com/2M2ZGwC.jpeg" +def sentiment_analyzer(text): + analysis = TextBlob(text) + return analysis.sentiment.polarity -# Run the GPT-4 Vision model -response = api.run(task, img) +agent = Agent( + agent_name="Sentiment-Analysis-Agent", + llm=OpenAIChat(api_key=os.getenv("OPENAI_API_KEY")), + sentiment_analyzer=sentiment_analyzer, + sentiment_threshold=0.5, + system_prompt="You are an agent that generates responses with sentiment analysis.", +) -# Print the model's response +response = agent.run("Generate a positive statement about AI") print(response) ``` -### Example 2: Custom API Key - -If you have a custom API key, you can initialize the module with it as shown in this example. -```python -from swarm_models import GPT4VisionAPI -# Initialize with custom API key and max_tokens -custom_api_key = "your_custom_api_key" -api = GPT4VisionAPI(openai_api_key=custom_api_key, max_tokens=500) +### Undo Functionality -# Define the task and image URL -task = "What is the object in the image?" -img = "https://i.imgur.com/3T3ZHwD.jpeg" +```python +# Feature 2: Undo functionality +response = agent.run("Another task") +print(f"Response: {response}") +previous_state, message = agent.undo_last() +print(message) +``` -# Run the GPT-4 Vision model -response = api.run(task, img) +### Response Filtering -# Print the model's response +```python +# Feature 3: Response filtering +agent.add_response_filter("report") +response = agent.filtered_run("Generate a report on finance") print(response) ``` -### Example 3: Adjusting Maximum Tokens - -You can also customize the maximum token limit when initializing the module. In this example, we set it to 1000 tokens. +### Saving and Loading State ```python -from swarm_models import GPT4VisionAPI - -# Initialize with default API key and custom max_tokens -api = GPT4VisionAPI(max_tokens=1000) - -# Define the task and image URL -task = "Describe the scene in the image." -img = "https://i.imgur.com/4P4ZRxU.jpeg" - -# Run the GPT-4 Vision model -response = api.run(task, img) +# Save the agent state +agent.save_state('saved_flow.json') -# Print the model's response -print(response) +# Load the agent state +agent = Agent(llm=llm_instance, max_loops=5) +agent.load('saved_flow.json') +agent.run("Continue with the task") ``` -## Additional Information +### Async and Concurrent Execution -- If you encounter any errors or issues with the module, make sure to check your API key and internet connectivity. -- It's recommended to handle exceptions when using the module to gracefully handle errors. -- You can further customize the module to fit your specific use case by modifying the code as needed. +```python +# Run a task concurrently +response = await agent.run_concurrent("Concurrent task") +print(response) -## References +# Run multiple tasks concurrently +tasks = [ + {"task": "Task 1"}, + {"task": "Task 2", "img": "path/to/image.jpg"}, + {"task": "Task 3", "custom_param": 42} +] +responses = agent.bulk_run(tasks) +print(responses) +``` -- [OpenAI API Documentation](https://beta.openai.com/docs/) -This documentation provides a comprehensive guide on how to use the `GPT4VisionAPI` module effectively. It covers initialization, methods, usage examples, and additional information to ensure a smooth experience when working with the GPT-4 Vision model. +### Various other settings --------------------------------------------------- +```python +# # Convert the agent object to a dictionary +print(agent.to_dict()) +print(agent.to_toml()) +print(agent.model_dump_json()) +print(agent.model_dump_yaml()) -# File: swarms/models/groq.md +# Ingest documents into the agent's knowledge base +agent.ingest_docs("your_pdf_path.pdf") -# Groq API Key Setup Documentation +# Receive a message from a user and process it +agent.receive_message(name="agent_name", message="message") +# Send a message from the agent to a user +agent.send_agent_message(agent_name="agent_name", message="message") -This documentation provides instructions on how to obtain your Groq API key and set it up in a `.env` file for use in your project. +# Ingest multiple documents into the agent's knowledge base +agent.ingest_docs("your_pdf_path.pdf", "your_csv_path.csv") -## Step 1: Obtain Your Groq API Key +# Run the agent with a filtered system prompt +agent.filtered_run( + "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?" +) -1. **Sign Up / Log In**: - - Visit the [Groq website](https://www.groq.com) and sign up for an account if you don't have one. If you already have an account, log in. +# Run the agent with multiple system prompts +agent.bulk_run( + [ + "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?", + "Another system prompt", + ] +) -2. **Access API Keys**: - - Once logged in, navigate to the API section of your account dashboard. This is usually found under "Settings" or "API Management". +# Add a memory to the agent +agent.add_memory("Add a memory to the agent") -3. **Generate API Key**: - - If you do not have an API key, look for an option to generate a new key. Follow the prompts to create your API key. Make sure to copy it to your clipboard. +# Check the number of available tokens for the agent +agent.check_available_tokens() -## Step 2: Create a `.env` File +# Perform token checks for the agent +agent.tokens_checks() -1. **Create the File**: - - In the root directory of your project, create a new file named `.env`. +# Print the dashboard of the agent +agent.print_dashboard() -2. **Add Your API Key**: - - Open the `.env` file in a text editor and add the following line, replacing `your_groq_api_key_here` with the API key you copied earlier: - ```plaintext - GROQ_API_KEY=your_groq_api_key_here - ``` +# Fetch all the documents from the doc folders +agent.get_docs_from_doc_folders() -3. **Save the File**: - - Save the changes to the `.env` file. +# Dump the model to a JSON file +agent.model_dump_json() +print(agent.to_toml()) +``` +## Auto Generate Prompt + CPU Execution -## Full Example ```python + import os +from swarms import Agent from swarm_models import OpenAIChat + from dotenv import load_dotenv +# Load environment variables load_dotenv() -# Get the OpenAI API key from the environment variable +# Retrieve the OpenAI API key from the environment variable api_key = os.getenv("GROQ_API_KEY") -# Model +# Initialize the model for OpenAI Chat model = OpenAIChat( openai_api_base="https://api.groq.com/openai/v1", openai_api_key=api_key, @@ -26129,20756 +28985,27258 @@ model = OpenAIChat( temperature=0.1, ) -model.run("What are the best metrics to track and understand risk in private equity") -``` - -## Important Notes - -- **Keep Your API Key Secure**: Do not share your API key publicly or commit it to version control systems like Git. Use the `.gitignore` file to exclude the `.env` file from being tracked. -- **Environment Variables**: Make sure to install any necessary libraries (like `python-dotenv`) to load environment variables from the `.env` file if your project requires it. - - -## Conclusion - -You are now ready to use the Groq API in your project! If you encounter any issues, refer to the Groq documentation or support for further assistance. - - --------------------------------------------------- - -# File: swarms/models/hf.md - -# HuggingFaceLLM - -## Overview & Introduction - -The `HuggingFaceLLM` class in the Zeta library provides a simple and easy-to-use interface to harness the power of Hugging Face's transformer-based language models, specifically for causal language modeling. This enables developers to generate coherent and contextually relevant sentences or paragraphs given a prompt, without delving deep into the intricate details of the underlying model or the tokenization process. +# Initialize the agent with automated prompt engineering enabled +agent = Agent( + agent_name="Financial-Analysis-Agent", + system_prompt=None, # System prompt is dynamically generated + agent_description=None, + llm=model, + max_loops=1, + autosave=True, + dashboard=False, + verbose=False, + dynamic_temperature_enabled=True, + saved_state_path="finance_agent.json", + user_name="Human:", + return_step_meta=False, + output_type="string", + streaming_on=False, + auto_generate_prompt=True, # Enable automated prompt engineering +) -Causal Language Modeling (CLM) is a task where given a series of tokens (or words), the model predicts the next token in the sequence. This functionality is central to many natural language processing tasks, including chatbots, story generation, and code autocompletion. +# Run the agent with a task description and specify the device +agent.run( + "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria", + ## Will design a system prompt based on the task if description and system prompt are None + device="cpu", +) ---- +# Print the dynamically generated system prompt +print(agent.system_prompt) -## Class Definition -```python -class HuggingFaceLLM: ``` -### Parameters: - -- `model_id (str)`: Identifier for the pre-trained model on the Hugging Face model hub. Examples include "gpt2-medium", "openai-gpt", etc. - -- `device (str, optional)`: The device on which to load and run the model. Defaults to 'cuda' if GPU is available, else 'cpu'. - -- `max_length (int, optional)`: Maximum length of the generated sequence. Defaults to 20. - -- `quantization_config (dict, optional)`: Configuration dictionary for model quantization (if applicable). Default is `None`. +## Agent Structured Outputs ---- +- Create a structured output schema for the agent [List[Dict]] +- Input in the `tools_list_dictionary` parameter +- Output is a dictionary +- Use the `str_to_dict` function to convert the output to a dictionary +```python -## Functionality & Usage +from dotenv import load_dotenv -### Initialization: +from swarms import Agent +from swarms.prompts.finance_agent_sys_prompt import ( + FINANCIAL_AGENT_SYS_PROMPT, +) +from swarms.utils.str_to_dict import str_to_dict -```python -llm = HuggingFaceLLM(model_id="gpt2-medium") -``` +load_dotenv() -Upon initialization, the specified pre-trained model and tokenizer are loaded from Hugging Face's model hub. The model is then moved to the designated device. If there's an issue loading either the model or the tokenizer, an error will be logged. +tools = [ + { + "type": "function", + "function": { + "name": "get_stock_price", + "description": "Retrieve the current stock price and related information for a specified company.", + "parameters": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "The stock ticker symbol of the company, e.g. AAPL for Apple Inc.", + }, + "include_history": { + "type": "boolean", + "description": "Indicates whether to include historical price data along with the current price.", + }, + "time": { + "type": "string", + "format": "date-time", + "description": "Optional parameter to specify the time for which the stock data is requested, in ISO 8601 format.", + }, + }, + "required": [ + "ticker", + "include_history", + "time", + ], + }, + }, + } +] -### Generation: -The main functionality of this class is text generation. The class provides two methods for this: `__call__` and `generate`. Both methods take in a prompt text and an optional `max_length` parameter and return the generated text. +# 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, + tools_list_dictionary=tools, +) -Usage: -```python -from swarms import HuggingFaceLLM +out = agent.run( + "What is the current stock price for Apple Inc. (AAPL)? Include historical price data.", +) -# Initialize -llm = HuggingFaceLLM(model_id="gpt2-medium") +print(out) -# Generate text using __call__ method -result = llm("Once upon a time,") -print(result) +print(type(out)) -# Alternatively, using the generate method -result = llm.generate("The future of AI is") -print(result) -``` +print(str_to_dict(out)) ---- +print(type(str_to_dict(out))) -## Mathematical Explanation: -Given a sequence of tokens \( x_1, x_2, ..., x_n \), a causal language model aims to maximize the likelihood of the next token \( x_{n+1} \) in the sequence. Formally, it tries to optimize: +``` -\[ P(x_{n+1} | x_1, x_2, ..., x_n) \] +## Best Practices -Where \( P \) is the probability distribution over all possible tokens in the vocabulary. +1. Always provide a clear and concise `system_prompt` to guide the agent's behavior. +2. Use `tools` to extend the agent's capabilities for specific tasks. +3. Implement error handling and utilize the `retry_attempts` feature for robust execution. +4. Leverage `long_term_memory` for tasks that require persistent information. +5. Use `interactive` mode for real-time conversations and `dashboard` for monitoring. +6. Implement `sentiment_analysis` for applications requiring tone management. +7. Utilize `autosave` and `save`/`load` methods for continuity across sessions. +8. Optimize token usage with `dynamic_context_window` and `tokens_checks` methods. +9. Use `concurrent` and `async` methods for performance-critical applications. +10. Regularly review and analyze feedback using the `analyze_feedback` method. +11. Use `artifacts_on` to save important outputs from agent execution +12. Configure `device` and `device_id` appropriately for optimal performance +13. Enable `rag_every_loop` when continuous context from long-term memory is needed +14. Use `scheduled_run_date` for automated task scheduling -The model takes the tokenized input sequence, feeds it through several transformer blocks, and finally through a linear layer to produce logits for each token in the vocabulary. The token with the highest logit value is typically chosen as the next token in the sequence. +By following these guidelines and leveraging the Swarm Agent's extensive features, you can create powerful, flexible, and efficient autonomous agents for a wide range of applications. ---- +-------------------------------------------------- -## Additional Information & Tips: +# File: swarms\structs\agent_docs_v1.md -- Ensure you have an active internet connection when initializing the class for the first time, as the models and tokenizers are fetched from Hugging Face's servers. +# `Agent` Documentation -- Although the default `max_length` is set to 20, it's advisable to adjust this parameter based on the context of the problem. +Swarm Agent is a powerful autonomous agent framework designed to connect Language Models (LLMs) with various tools and long-term memory. This class provides the ability to ingest and process various types of documents such as PDFs, text files, Markdown files, JSON files, and more. The Agent structure offers a wide range of features to enhance the capabilities of LLMs and facilitate efficient task execution. -- Keep an eye on GPU memory when using large models or generating long sequences. +1. **Conversational Loop**: It establishes a conversational loop with a language model. This means it allows you to interact with the model in a back-and-forth manner, taking turns in the conversation. ---- +2. **Feedback Collection**: The class allows users to provide feedback on the responses generated by the model. This feedback can be valuable for training and improving the model's responses over time. -## References & Resources: +3. **Stoppable Conversation**: You can define custom stopping conditions for the conversation, allowing you to stop the interaction based on specific criteria. For example, you can stop the conversation if a certain keyword is detected in the responses. -- Hugging Face Model Hub: [https://huggingface.co/models](https://huggingface.co/models) - -- Introduction to Transformers: [https://huggingface.co/transformers/introduction.html](https://huggingface.co/transformers/introduction.html) +4. **Retry Mechanism**: The class includes a retry mechanism that can be helpful if there are issues generating responses from the model. It attempts to generate a response multiple times before raising an error. -- Causal Language Modeling: Vaswani, A., et al. (2017). Attention is All You Need. [arXiv:1706.03762](https://arxiv.org/abs/1706.03762) +## Architecture -Note: This documentation template provides a comprehensive overview of the `HuggingFaceLLM` class. Developers can follow similar structures when documenting other classes or functionalities. +```mermaid +graph TD + A[Task Initiation] -->|Receives Task| B[Initial LLM Processing] + B -->|Interprets Task| C[Tool Usage] + C -->|Calls Tools| D[Function 1] + C -->|Calls Tools| E[Function 2] + D -->|Returns Data| C + E -->|Returns Data| C + C -->|Provides Data| F[Memory Interaction] + F -->|Stores and Retrieves Data| G[RAG System] + G -->|ChromaDB/Pinecone| H[Enhanced Data] + F -->|Provides Enhanced Data| I[Final LLM Processing] + I -->|Generates Final Response| J[Output] + C -->|No Tools Available| K[Skip Tool Usage] + K -->|Proceeds to Memory Interaction| F + F -->|No Memory Available| L[Skip Memory Interaction] + L -->|Proceeds to Final LLM Processing| I +``` --------------------------------------------------- +### `Agent` Attributes -# File: swarms/models/huggingface.md +| Attribute | Description | +|------------|-------------| +| `id` | A unique identifier for the agent instance. | +| `llm` | The language model instance used by the agent. | +| `template` | The template used for formatting responses. | +| `max_loops` | The maximum number of loops the agent can run. | +| `stopping_condition` | A callable function that determines when the agent should stop looping. | +| `loop_interval` | The interval (in seconds) between loops. | +| `retry_attempts` | The number of retry attempts for failed LLM calls. | +| `retry_interval` | The interval (in seconds) between retry attempts. | +| `return_history` | A boolean indicating whether the agent should return the conversation history. | +| `stopping_token` | A token that, when present in the response, stops the agent from looping. | +| `dynamic_loops` | A boolean indicating whether the agent should dynamically determine the number of loops. | +| `interactive` | A boolean indicating whether the agent should run in interactive mode. | +| `dashboard` | A boolean indicating whether the agent should display a dashboard. | +| `agent_name` | The name of the agent instance. | +| `agent_description` | A description of the agent instance. | +| `system_prompt` | The system prompt used to initialize the conversation. | +| `tools` | A list of callable functions representing tools the agent can use. | +| `dynamic_temperature_enabled` | A boolean indicating whether the agent should dynamically adjust the temperature of the LLM. | +| `sop` | The standard operating procedure for the agent. | +| `sop_list` | A list of strings representing the standard operating procedure. | +| `saved_state_path` | The file path for saving and loading the agent's state. | +| `autosave` | A boolean indicating whether the agent should automatically save its state. | +| `context_length` | The maximum length of the context window (in tokens) for the LLM. | +| `user_name` | The name used to represent the user in the conversation. | +| `self_healing_enabled` | A boolean indicating whether the agent should attempt to self-heal in case of errors. | +| `code_interpreter` | A boolean indicating whether the agent should interpret and execute code snippets. | +| `multi_modal` | A boolean indicating whether the agent should support multimodal inputs (e.g., text and images). | +| `pdf_path` | The file path of a PDF document to be ingested. | +| `list_of_pdf` | A list of file paths for PDF documents to be ingested. | +| `tokenizer` | An instance of a tokenizer used for token counting and management. | +| `long_term_memory` | An instance of a `BaseVectorDatabase` implementation for long-term memory management. | +| `preset_stopping_token` | A boolean indicating whether the agent should use a preset stopping token. | +| `traceback` | An object used for traceback handling. | +| `traceback_handlers` | A list of traceback handlers. | +| `streaming_on` | A boolean indicating whether the agent should stream its responses. | +| `docs` | A list of document paths or contents to be ingested. | +| `docs_folder` | The path to a folder containing documents to be ingested. | +| `verbose` | A boolean indicating whether the agent should print verbose output. | +| `parser` | A callable function used for parsing input data. | +| `best_of_n` | An integer indicating the number of best responses to generate (for sampling). | +| `callback` | A callable function to be called after each agent loop. | +| `metadata` | A dictionary containing metadata for the agent. | +| `callbacks` | A list of callable functions to be called during the agent's execution. | +| `logger_handler` | A handler for logging messages. | +| `search_algorithm` | A callable function representing the search algorithm for long-term memory retrieval. | +| `logs_to_filename` | The file path for logging agent activities. | +| `evaluator` | A callable function used for evaluating the agent's responses. | +| `output_json` | A boolean indicating whether the agent's output should be in JSON format. | +| `stopping_func` | A callable function used as a stopping condition for the agent. | +| `custom_loop_condition` | A callable function used as a custom loop condition for the agent. | +| `sentiment_threshold` | A float value representing the sentiment threshold for evaluating responses. | +| `custom_exit_command` | A string representing a custom command for exiting the agent's loop. | +| `sentiment_analyzer` | A callable function used for sentiment analysis on the agent's outputs. | +| `limit_tokens_from_string` | A callable function used for limiting the number of tokens in a string. | +| `custom_tools_prompt` | A callable function used for generating a custom prompt for tool usage. | +| `tool_schema` | A data structure representing the schema for the agent's tools. | +| `output_type` | A type representing the expected output type of the agent's responses. | +| `function_calling_type` | A string representing the type of function calling (e.g., "json"). | +| `output_cleaner` | A callable function used for cleaning the agent's output. | +| `function_calling_format_type` | A string representing the format type for function calling (e.g., "OpenAI"). | +| `list_base_models` | A list of base models used for generating tool schemas. | +| `metadata_output_type` | A string representing the output type for metadata. | +| `state_save_file_type` | A string representing the file type for saving the agent's state (e.g., "json", "yaml"). | +| `chain_of_thoughts` | A boolean indicating whether the agent should use the chain of thoughts technique. | +| `algorithm_of_thoughts` | A boolean indicating whether the agent should use the algorithm of thoughts technique. | +| `tree_of_thoughts` | A boolean indicating whether the agent should use the tree of thoughts technique. | +| `tool_choice` | A string representing the method for tool selection (e.g., "auto"). | +| `execute_tool` | A boolean indicating whether the agent should execute tools. | +| `rules` | A string representing the rules for the agent's behavior. | +| `planning` | A boolean indicating whether the agent should perform planning. | +| `planning_prompt` | A string representing the prompt for planning. | +| `device` | A string representing the device on which the agent should run. | +| `custom_planning_prompt` | A string representing a custom prompt for planning. | +| `memory_chunk_size` | An integer representing the maximum size of memory chunks for long-term memory retrieval. | +| `agent_ops_on` | A boolean indicating whether agent operations should be enabled. | +| `return_step_meta` | A boolean indicating whether or not to return JSON of all the steps and additional metadata | +| `output_type` | A Literal type indicating whether to output "string", "str", "list", "json", "dict", "yaml" | -## `HuggingfaceLLM` Documentation -### Introduction -The `HuggingfaceLLM` class is designed for running inference using models from the Hugging Face Transformers library. This documentation provides an in-depth understanding of the class, its purpose, attributes, methods, and usage examples. +### `Agent` Methods -#### Purpose +| Method | Description | Inputs | Usage Example | +|--------|-------------|--------|----------------| +| `run(task, img=None, *args, **kwargs)` | Runs the autonomous agent loop to complete the given task. | `task` (str): The task to be performed.
`img` (str, optional): Path to an image file, if the task involves image processing.
`*args`, `**kwargs`: Additional arguments to pass to the language model. | `response = agent.run("Generate a report on financial performance.")` | +| `__call__(task, img=None, *args, **kwargs)` | An alternative way to call the `run` method. | Same as `run`. | `response = agent("Generate a report on financial performance.")` | +| `parse_and_execute_tools(response, *args, **kwargs)` | Parses the agent's response and executes any tools mentioned in it. | `response` (str): The agent's response to be parsed.
`*args`, `**kwargs`: Additional arguments to pass to the tool execution. | `agent.parse_and_execute_tools(response)` | +| `long_term_memory_prompt(query, *args, **kwargs)` | Generates a prompt for querying the agent's long-term memory. | `query` (str): The query to search for in long-term memory.
`*args`, `**kwargs`: Additional arguments to pass to the long-term memory retrieval. | `memory_retrieval = agent.long_term_memory_prompt("financial performance")` | +| `add_memory(message)` | Adds a message to the agent's memory. | `message` (str): The message -The `HuggingfaceLLM` class serves the following purposes: -1. Load pre-trained Hugging Face models and tokenizers. -2. Generate text-based responses from the loaded model using a given prompt. -3. Provide flexibility in device selection, quantization, and other configuration options. -### Class Definition -The `HuggingfaceLLM` class is defined as follows: +## Features -```python -class HuggingfaceLLM: - def __init__( - self, - model_id: str, - device: str = None, - max_length: int = 20, - quantize: bool = False, - quantization_config: dict = None, - verbose=False, - distributed=False, - decoding=False, - ): - # Attributes and initialization logic explained below - pass +- **Language Model Integration**: The Swarm Agent allows seamless integration with different language models, enabling users to leverage the power of state-of-the-art models. +- **Tool Integration**: The framework supports the integration of various tools, enabling the agent to perform a wide range of tasks, from code execution to data analysis and beyond. +- **Long-term Memory Management**: The Swarm Agent incorporates long-term memory management capabilities, allowing it to store and retrieve relevant information for effective decision-making and task execution. +- **Document Ingestion**: The agent can ingest and process various types of documents, including PDFs, text files, Markdown files, JSON files, and more, enabling it to extract relevant information for task completion. +- **Interactive Mode**: Users can interact with the agent in an interactive mode, enabling real-time communication and task execution. +- **Dashboard**: The framework provides a visual dashboard for monitoring the agent's performance and activities. +- **Dynamic Temperature Control**: The Swarm Agent supports dynamic temperature control, allowing for adjustments to the model's output diversity during task execution. +- **Autosave and State Management**: The agent can save its state automatically, enabling seamless resumption of tasks after interruptions or system restarts. +- **Self-Healing and Error Handling**: The framework incorporates self-healing and error-handling mechanisms to ensure robust and reliable operation. +- **Code Interpretation**: The agent can interpret and execute code snippets, expanding its capabilities for tasks involving programming or scripting. +- **Multimodal Support**: The framework supports multimodal inputs, enabling the agent to process and reason about various data types, such as text, images, and audio. +- **Tokenization and Token Management**: The Swarm Agent provides tokenization capabilities, enabling efficient management of token usage and context window truncation. +- **Sentiment Analysis**: The agent can perform sentiment analysis on its generated outputs, allowing for evaluation and adjustment of responses based on sentiment thresholds. +- **Output Filtering and Cleaning**: The framework supports output filtering and cleaning, ensuring that generated responses adhere to specific criteria or guidelines. +- **Asynchronous and Concurrent Execution**: The Swarm Agent supports asynchronous and concurrent task execution, enabling efficient parallelization and scaling of operations. +- **Planning and Reasoning**: The agent can engage in planning and reasoning processes, leveraging techniques such as algorithm of thoughts and chain of thoughts to enhance decision-making and task execution. +- **Agent Operations and Monitoring**: The framework provides integration with agent operations and monitoring tools, enabling real-time monitoring and management of the agent's activities. - def load_model(self): - # Method to load the pre-trained model and tokenizer - pass +## Getting Started - def run(self, prompt_text: str, max_length: int = None): - # Method to generate text-based responses - pass +First run the following: - def __call__(self, prompt_text: str, max_length: int = None): - # Alternate method for generating text-based responses - pass +```bash +pip3 install -U swarms ``` -### Attributes +And, then now you can get started with the following: -| Attribute | Description | -|----------------------|---------------------------------------------------------------------------------------------------------------------------| -| `model_id` | The ID of the pre-trained model to be used. | -| `device` | The device on which the model runs (`'cuda'` for GPU or `'cpu'` for CPU). | -| `max_length` | The maximum length of the generated text. | -| `quantize` | A boolean indicating whether quantization should be used. | -| `quantization_config`| A dictionary with configuration options for quantization. | -| `verbose` | A boolean indicating whether verbose logs should be printed. | -| `logger` | An optional logger for logging messages (defaults to a basic logger). | -| `distributed` | A boolean indicating whether distributed processing should be used. | -| `decoding` | A boolean indicating whether to perform decoding during text generation. | +```python +import os +from swarms import Agent +from swarm_models import OpenAIChat +from swarms.prompts.finance_agent_sys_prompt import ( + FINANCIAL_AGENT_SYS_PROMPT, +) -### Class Methods +# Get the OpenAI API key from the environment variable +api_key = os.getenv("OPENAI_API_KEY") -#### `__init__` Method +# Create an instance of the OpenAIChat class +model = OpenAIChat( + api_key=api_key, model_name="gpt-4o-mini", temperature=0.1 +) -The `__init__` method initializes an instance of the `HuggingfaceLLM` class with the specified parameters. It also loads the pre-trained model and tokenizer. +# Initialize the agent +agent = Agent( + agent_name="Financial-Analysis-Agent_sas_chicken_eej", + system_prompt=FINANCIAL_AGENT_SYS_PROMPT, + llm=model, + max_loops=1, + autosave=True, + dashboard=False, + verbose=True, + dynamic_temperature_enabled=True, + saved_state_path="finance_agent.json", + user_name="swarms_corp", + retry_attempts=1, + context_length=200000, + return_step_meta=False, + output_type="str", +) -- `model_id` (str): The ID of the pre-trained model to use. -- `device` (str, optional): The device to run the model on ('cuda' or 'cpu'). -- `max_length` (int, optional): The maximum length of the generated text. -- `quantize` (bool, optional): Whether to use quantization. -- `quantization_config` (dict, optional): Configuration for quantization. -- `verbose` (bool, optional): Whether to print verbose logs. -- `logger` (logging.Logger, optional): The logger to use. -- `distributed` (bool, optional): Whether to use distributed processing. -- `decoding` (bool, optional): Whether to perform decoding during text generation. -#### `load_model` Method +agent.run( + "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria" +) +print(out) -The `load_model` method loads the pre-trained model and tokenizer specified by `model_id`. +``` -#### `run` and `__call__` Methods +This example initializes an instance of the `Agent` class with an OpenAI language model and a maximum of 3 loops. The `run()` method is then called with a task to generate a report on financial performance, and the agent's response is printed. -Both `run` and `__call__` methods generate text-based responses based on a given prompt. They accept the following parameters: +## Advanced Usage -- `prompt_text` (str): The text prompt to initiate text generation. -- `max_length` (int, optional): The maximum length of the generated text. +The Swarm Agent provides numerous advanced features and customization options. Here are a few examples of how to leverage these features: -### Usage Examples +### Tool Integration -Here are three ways to use the `HuggingfaceLLM` class: +To integrate tools with the Swarm Agent, you can pass a list of callable functions with types and doc strings to the `tools` parameter when initializing the `Agent` instance. The agent will automatically convert these functions into an OpenAI function calling schema and make them available for use during task execution. -#### Example 1: Basic Usage +## Requirements for a tool +- Function + - With types + - with doc strings ```python -from swarm_models import HuggingfaceLLM - -# Initialize the HuggingfaceLLM instance with a model ID -model_id = "NousResearch/Nous-Hermes-2-Vision-Alpha" -inference = HuggingfaceLLM(model_id=model_id) +from swarms import Agent +from swarm_models import OpenAIChat +from swarms_memory import ChromaDB +import subprocess +import os -# Generate text based on a prompt -prompt_text = "Once upon a time" -generated_text = inference(prompt_text) -print(generated_text) -``` +# Making an instance of the ChromaDB class +memory = ChromaDB( + metric="cosine", + n_results=3, + output_dir="results", + docs_folder="docs", +) -#### Example 2: Custom Configuration +# Model +model = OpenAIChat( + api_key=os.getenv("OPENAI_API_KEY"), + model_name="gpt-4o-mini", + temperature=0.1, +) -```python -from swarm_models import HuggingfaceLLM -# Initialize with custom configuration -custom_config = { - "quantize": True, - "quantization_config": {"load_in_4bit": True}, - "verbose": True, -} -inference = HuggingfaceLLM( - model_id="NousResearch/Nous-Hermes-2-Vision-Alpha", **custom_config -) +# Tools in swarms are simple python functions and docstrings +def terminal( + code: str, +): + """ + Run code in the terminal. -# Generate text based on a prompt -prompt_text = "Tell me a joke" -generated_text = inference(prompt_text) -print(generated_text) -``` + Args: + code (str): The code to run in the terminal. -#### Example 3: Distributed Processing + Returns: + str: The output of the code. + """ + out = subprocess.run( + code, shell=True, capture_output=True, text=True + ).stdout + return str(out) -```python -from swarm_models import HuggingfaceLLM -# Initialize for distributed processing -inference = HuggingfaceLLM(model_id="gpt2-medium", distributed=True) +def browser(query: str): + """ + Search the query in the browser with the `browser` tool. -# Generate text based on a prompt -prompt_text = "Translate the following sentence to French" -generated_text = inference(prompt_text) -print(generated_text) -``` + Args: + query (str): The query to search in the browser. -### Additional Information + Returns: + str: The search results. + """ + import webbrowser -- The `HuggingfaceLLM` class provides the flexibility to load and use pre-trained models from the Hugging Face Transformers library. -- Quantization can be enabled to reduce model size and inference time. -- Distributed processing can be used for parallelized inference. -- Verbose logging can help in debugging and understanding the text generation process. + url = f"https://www.google.com/search?q={query}" + webbrowser.open(url) + return f"Searching for {query} in the browser." -### References -- [Hugging Face Transformers Documentation](https://huggingface.co/transformers/) -- [PyTorch Documentation](https://pytorch.org/docs/stable/index.html) +def create_file(file_path: str, content: str): + """ + Create a file using the file editor tool. -This documentation provides a comprehensive understanding of the `HuggingfaceLLM` class, its attributes, methods, and usage examples. Developers can use this class to perform text generation tasks efficiently using pre-trained models from the Hugging Face Transformers library. + Args: + file_path (str): The path to the file. + content (str): The content to write to the file. --------------------------------------------------- + Returns: + str: The result of the file creation operation. + """ + with open(file_path, "w") as file: + file.write(content) + return f"File {file_path} created successfully." -# File: swarms/models/idefics.md -# `Idefics` Documentation +def file_editor(file_path: str, mode: str, content: str): + """ + Edit a file using the file editor tool. -## Introduction + Args: + file_path (str): The path to the file. + mode (str): The mode to open the file in. + content (str): The content to write to the file. -Welcome to the documentation for Idefics, a versatile multimodal inference tool using pre-trained models from the Hugging Face Hub. Idefics is designed to facilitate the generation of text from various prompts, including text and images. This documentation provides a comprehensive understanding of Idefics, its architecture, usage, and how it can be integrated into your projects. + Returns: + str: The result of the file editing operation. + """ + with open(file_path, mode) as file: + file.write(content) + return f"File {file_path} edited successfully." -## Overview -Idefics leverages the power of pre-trained models to generate textual responses based on a wide range of prompts. It is capable of handling both text and images, making it suitable for various multimodal tasks, including text generation from images. +# Agent +agent = Agent( + agent_name="Devin", + system_prompt=( + "Autonomous agent that can interact with humans and other" + " agents. Be Helpful and Kind. Use the tools provided to" + " assist the user. Return all code in markdown format." + ), + llm=model, + max_loops="auto", + autosave=True, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + interactive=True, + tools=[terminal, browser, file_editor, create_file], + streaming=True, + long_term_memory=memory, +) -## Class Definition +# Run the agent +out = agent( + "Create a CSV file with the latest tax rates for C corporations in the following ten states and the District of Columbia: Alabama, California, Florida, Georgia, Illinois, New York, North Carolina, Ohio, Texas, and Washington." +) +print(out) -```python -class Idefics: - def __init__( - self, - checkpoint="HuggingFaceM4/idefics-9b-instruct", - device=None, - torch_dtype=torch.bfloat16, - max_length=100, - ): ``` -## Usage - -To use Idefics, follow these steps: +### Long-term Memory Management -1. Initialize the Idefics instance: +The Swarm Agent supports integration with various vector databases for long-term memory management. You can pass an instance of a `BaseVectorDatabase` implementation to the `long_term_memory` parameter when initializing the `Agent`. ```python -from swarm_models import Idefics - -model = Idefics() -``` +import os -2. Generate text based on prompts: +from swarms_memory import ChromaDB -```python -prompts = [ - "User: What is in this image? https://upload.wikimedia.org/wikipedia/commons/8/86/Id%C3%A9fix.JPG" -] -response = model(prompts) -print(response) -``` +from swarms import Agent +from swarm_models import Anthropic +from swarms.prompts.finance_agent_sys_prompt import ( + FINANCIAL_AGENT_SYS_PROMPT, +) -### Example 1 - Image Questioning +# Initilaize the chromadb client +chromadb = ChromaDB( + metric="cosine", + output_dir="fiance_agent_rag", + # docs_folder="artifacts", # Folder of your documents +) -```python -from swarm_models import Idefics +# Model +model = Anthropic(anthropic_api_key=os.getenv("ANTHROPIC_API_KEY")) -model = Idefics() -prompts = [ - "User: What is in this image? https://upload.wikimedia.org/wikipedia/commons/8/86/Id%C3%A9fix.JPG" -] -response = model(prompts) -print(response) -``` -### Example 2 - Bidirectional Conversation +# Initialize the agent +agent = Agent( + agent_name="Financial-Analysis-Agent", + system_prompt=FINANCIAL_AGENT_SYS_PROMPT, + agent_description="Agent creates ", + llm=model, + max_loops="auto", + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + dynamic_temperature_enabled=True, + saved_state_path="finance_agent.json", + user_name="swarms_corp", + retry_attempts=3, + context_length=200000, + long_term_memory=chromadb, +) -```python -from swarm_models import Idefics -model = Idefics() -user_input = "User: What is in this image? https://upload.wikimedia.org/wikipedia/commons/8/86/Id%C3%A9fix.JPG" -response = model.chat(user_input) -print(response) +agent.run( + "What are the components of a startups stock incentive equity plan" +) -user_input = "User: Who is that? https://static.wikia.nocookie.net/asterix/images/2/25/R22b.gif/revision/latest?cb=20110815073052" -response = model.chat(user_input) -print(response) ``` -### Example 3 - Configuration Changes +### Document Ingestion + +The Swarm Agent can ingest various types of documents, such as PDFs, text files, Markdown files, and JSON files. You can pass a list of document paths or contents to the `docs` parameter when initializing the `Agent`. ```python -model.set_checkpoint("new_checkpoint") -model.set_device("cpu") -model.set_max_length(200) -model.clear_chat_history() -``` +from swarms.structs import Agent -## How Idefics Works +# Initialize the agent with documents +agent = Agent(llm=llm, max_loops=3, docs=["path/to/doc1.pdf", "path/to/doc2.txt"]) +``` -Idefics operates by leveraging pre-trained models from the Hugging Face Hub. Here's how it works: +### Interactive Mode -1. **Initialization**: When you create an Idefics instance, it initializes the model using a specified checkpoint, sets the device for inference, and configures other parameters like data type and maximum text length. +The Swarm Agent supports an interactive mode, where users can engage in real-time communication with the agent. To enable interactive mode, set the `interactive` parameter to `True` when initializing the `Agent`. -2. **Prompt-Based Inference**: You can use the `infer` method to generate text based on prompts. It processes prompts in batched or non-batched mode, depending on your preference. It uses a pre-trained processor to handle text and images. +```python +from swarms.structs import Agent -3. **Bidirectional Conversation**: The `chat` method enables bidirectional conversations. You provide user input, and the model responds accordingly. The chat history is maintained for context. +# Initialize the agent in interactive mode +agent = Agent(llm=llm, max_loops=3, interactive=True) -4. **Configuration Changes**: You can change the model checkpoint, device, maximum text length, or clear the chat history as needed during runtime. +# Run the agent in interactive mode +agent.interactive_run() +``` -## Parameters +### Sentiment Analysis -- `checkpoint`: The name of the pre-trained model checkpoint (default is "HuggingFaceM4/idefics-9b-instruct"). -- `device`: The device to use for inference. By default, it uses CUDA if available; otherwise, it uses CPU. -- `torch_dtype`: The data type to use for inference. By default, it uses torch.bfloat16. -- `max_length`: The maximum length of the generated text (default is 100). +The Swarm Agent can perform sentiment analysis on its generated outputs using a sentiment analyzer function. You can pass a callable function to the `sentiment_analyzer` parameter when initializing the `Agent`. -## Additional Information +```python +from swarms.structs import Agent +from my_sentiment_analyzer import sentiment_analyzer_function -- Idefics provides a convenient way to engage in bidirectional conversations with pre-trained models. -- You can easily change the model checkpoint, device, and other settings to adapt to your specific use case. +# Initialize the agent with a sentiment analyzer +agent = Agent( + agent_name = "sentiment-analyzer-agent-01", system_prompt="..." + llm=llm, max_loops=3, sentiment_analyzer=sentiment_analyzer_function) +``` -That concludes the documentation for Idefics. We hope you find this tool valuable for your multimodal text generation tasks. If you have any questions or encounter any issues, please refer to the Hugging Face Transformers documentation for further assistance. Enjoy working with Idefics! --------------------------------------------------- +### Undo Functionality -# File: swarms/models/index.md - -# Swarm Models - - -```bash -$ pip3 install -U swarm-models +```python +# Feature 2: Undo functionality +response = agent.run("Another task") +print(f"Response: {response}") +previous_state, message = agent.undo_last() +print(message) ``` -Welcome to the documentation for the llm section of the swarms package, designed to facilitate seamless integration with various AI language models and APIs. This package empowers developers, end-users, and system administrators to interact with AI models from different providers, such as OpenAI, Hugging Face, Google PaLM, and Anthropic. - -### Table of Contents -1. [OpenAI](#openai) -2. [HuggingFace](#huggingface) -3. [Anthropic](#anthropic) - -### 1. OpenAI (swarm_models.OpenAI) - -The OpenAI class provides an interface to interact with OpenAI's language models. It allows both synchronous and asynchronous interactions. +### Response Filtering -**Constructor:** ```python -OpenAI(api_key: str, system: str = None, console: bool = True, model: str = None, params: dict = None, save_messages: bool = True) +# Feature 3: Response filtering +agent.add_response_filter("report") +response = agent.filtered_run("Generate a report on finance") +print(response) ``` -**Attributes:** -- `api_key` (str): Your OpenAI API key. - -- `system` (str, optional): A system message to be used in conversations. - -- `console` (bool, default=True): Display console logs. - -- `model` (str, optional): Name of the language model to use. - -- `params` (dict, optional): Additional parameters for model interactions. - -- `save_messages` (bool, default=True): Save conversation messages. - -**Methods:** - -- `run(message: str, **kwargs) -> str`: Generate a response using the OpenAI model. - -- `generate_async(message: str, **kwargs) -> str`: Generate a response asynchronously. - -- `ask_multiple(ids: List[str], question_template: str) -> List[str]`: Query multiple IDs simultaneously. - -- `stream_multiple(ids: List[str], question_template: str) -> List[str]`: Stream multiple responses. +### Saving and Loading State -**Usage Example:** ```python -import asyncio +# Save the agent state +agent.save_state('saved_flow.json') -from swarm_models import OpenAI +# Load the agent state +agent = Agent(llm=llm_instance, max_loops=5) +agent.load('saved_flow.json') +agent.run("Continue with the task") +``` -chat = OpenAI(api_key="YOUR_OPENAI_API_KEY") +### Async and Concurrent Execution -response = chat.run("Hello, how can I assist you?") +```python +# Run a task concurrently +response = await agent.run_concurrent("Concurrent task") print(response) -ids = ["id1", "id2", "id3"] -async_responses = asyncio.run(chat.ask_multiple(ids, "How is {id}?")) -print(async_responses) +# Run multiple tasks concurrently +tasks = [ + {"task": "Task 1"}, + {"task": "Task 2", "img": "path/to/image.jpg"}, + {"task": "Task 3", "custom_param": 42} +] +responses = agent.bulk_run(tasks) +print(responses) ``` -### 2. HuggingFace (swarm_models.HuggingFaceLLM) -The HuggingFaceLLM class allows interaction with language models from Hugging Face. +### Various other settings -**Constructor:** ```python -HuggingFaceLLM(model_id: str, device: str = None, max_length: int = 20, quantize: bool = False, quantization_config: dict = None) -``` +# # Convert the agent object to a dictionary +print(agent.to_dict()) +print(agent.to_toml()) +print(agent.model_dump_json()) +print(agent.model_dump_yaml()) -**Attributes:** +# Ingest documents into the agent's knowledge base +agent.ingest_docs("your_pdf_path.pdf") -- `model_id` (str): ID or name of the Hugging Face model. +# Receive a message from a user and process it +agent.receive_message(name="agent_name", message="message") -- `device` (str, optional): Device to run the model on (e.g., 'cuda', 'cpu'). +# Send a message from the agent to a user +agent.send_agent_message(agent_name="agent_name", message="message") -- `max_length` (int, default=20): Maximum length of generated text. +# Ingest multiple documents into the agent's knowledge base +agent.ingest_docs("your_pdf_path.pdf", "your_csv_path.csv") -- `quantize` (bool, default=False): Apply model quantization. +# Run the agent with a filtered system prompt +agent.filtered_run( + "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?" +) -- `quantization_config` (dict, optional): Configuration for quantization. +# Run the agent with multiple system prompts +agent.bulk_run( + [ + "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?", + "Another system prompt", + ] +) -**Methods:** +# Add a memory to the agent +agent.add_memory("Add a memory to the agent") -- `run(prompt_text: str, max_length: int = None) -> str`: Generate text based on a prompt. +# Check the number of available tokens for the agent +agent.check_available_tokens() -**Usage Example:** -```python -from swarm_models import HuggingFaceLLM +# Perform token checks for the agent +agent.tokens_checks() -model_id = "gpt2" -hugging_face_model = HuggingFaceLLM(model_id=model_id) +# Print the dashboard of the agent +agent.print_dashboard() -prompt = "Once upon a time" -generated_text = hugging_face_model.run(prompt) -print(generated_text) -``` -### 3. Anthropic (swarm_models.Anthropic) +# Fetch all the documents from the doc folders +agent.get_docs_from_doc_folders() -The Anthropic class enables interaction with Anthropic's large language models. +# Activate agent ops -**Constructor:** -```python -Anthropic(model: str = "claude-2", max_tokens_to_sample: int = 256, temperature: float = None, top_k: int = None, top_p: float = None, streaming: bool = False, default_request_timeout: int = None) +# Dump the model to a JSON file +agent.model_dump_json() +print(agent.to_toml()) ``` -**Attributes:** - -- `model` (str): Name of the Anthropic model. +-------------------------------------------------- -- `max_tokens_to_sample` (int, default=256): Maximum tokens to sample. +# File: swarms\structs\agent_mcp.md -- `temperature` (float, optional): Temperature for text generation. +# Agent MCP Integration Guide -- `top_k` (int, optional): Top-k sampling value. +
-- `top_p` (float, optional): Top-p sampling value. +- :material-connection: **Direct MCP Server Connection** -- `streaming` (bool, default=False): Enable streaming mode. + --- -- `default_request_timeout` (int, optional): Default request timeout. + Connect agents to MCP servers via URL for seamless integration -**Methods:** + [:octicons-arrow-right-24: Quick Start](#quick-start) -- `run(prompt: str, stop: List[str] = None) -> str`: Generate text based on a prompt. +- :material-tools: **Dynamic Tool Discovery** -**Usage Example:** -```python -from swarm_models import Anthropic + --- -anthropic = Anthropic() -prompt = "Once upon a time" -generated_text = anthropic.run(prompt) -print(generated_text) -``` + Automatically fetch and utilize tools from MCP servers -This concludes the documentation for the "models" folder, providing you with tools to seamlessly integrate with various language models and APIs. Happy coding! + [:octicons-arrow-right-24: Tool Discovery](#integration-flow) --------------------------------------------------- +- :material-chart-line: **Real-time Communication** -# File: swarms/models/kosmos.md + --- -# `Kosmos` Documentation + Server-sent Events (SSE) for live data streaming -## Introduction + [:octicons-arrow-right-24: Configuration](#configuration-options) -Welcome to the documentation for Kosmos, a powerful multimodal AI model that can perform various tasks, including multimodal grounding, referring expression comprehension, referring expression generation, grounded visual question answering (VQA), and grounded image captioning. Kosmos is based on the ydshieh/kosmos-2-patch14-224 model and is designed to process both text and images to provide meaningful outputs. In this documentation, you will find a detailed explanation of the Kosmos class, its functions, parameters, and usage examples. +- :material-code-json: **Structured Output** -## Overview + --- -Kosmos is a state-of-the-art multimodal AI model that combines the power of natural language understanding with image analysis. It can perform several tasks that involve processing both textual prompts and images to provide informative responses. Whether you need to find objects in an image, understand referring expressions, generate descriptions, answer questions, or create captions, Kosmos has you covered. + Process and format responses with multiple output types -## Class Definition + [:octicons-arrow-right-24: Examples](#example-implementations) -```python -class Kosmos: - def __init__(self, model_name="ydshieh/kosmos-2-patch14-224"): -``` +
-## Usage +## Overview -To use Kosmos, follow these steps: +The **Model Context Protocol (MCP)** integration enables Swarms agents to dynamically connect to external tools and services through a standardized protocol. This powerful feature expands agent capabilities by providing access to APIs, databases, and specialized services. -1. Initialize the Kosmos instance: +!!! info "What is MCP?" + The Model Context Protocol is a standardized way for AI agents to interact with external tools and services, providing a consistent interface for tool discovery and execution. -```python -from swarm_models.kosmos_two import Kosmos +--- -kosmos = Kosmos() -``` +## :material-check-circle: Features Matrix -2. Perform Multimodal Grounding: +=== "✅ Current Capabilities" -```python -kosmos.multimodal_grounding( - "Find the red apple in the image.", "https://example.com/apple.jpg" -) -``` + | Feature | Status | Description | + |---------|--------|-------------| + | **Direct MCP Connection** | ✅ Ready | Connect via URL to MCP servers | + | **Tool Discovery** | ✅ Ready | Auto-fetch available tools | + | **SSE Communication** | ✅ Ready | Real-time server communication | + | **Multiple Tool Execution** | ✅ Ready | Execute multiple tools per session | + | **Structured Output** | ✅ Ready | Format responses in multiple types | -### Example 1 - Multimodal Grounding +=== "🚧 In Development" -```python -from swarm_models.kosmos_two import Kosmos + | Feature | Status | Expected | + |---------|--------|----------| + | **MCPConnection Model** | 🚧 Development | Q1 2024 | + | **Multiple Server Support** | 🚧 Planned | Q2 2024 | + | **Parallel Function Calling** | 🚧 Research | Q2 2024 | + | **Auto-discovery** | 🚧 Planned | Q3 2024 | -kosmos = Kosmos() +--- -kosmos.multimodal_grounding( - "Find the red apple in the image.", "https://example.com/apple.jpg" -) -``` +## :material-rocket: Quick Start -3. Perform Referring Expression Comprehension: +!!! tip "Prerequisites" + === "System Requirements" + - Python 3.8+ + - Swarms framework + - Running MCP server + + === "Installation" + ```bash + pip install swarms + ``` -```python -kosmos.referring_expression_comprehension( - "Show me the green bottle.", "https://example.com/bottle.jpg" -) -``` +### Step 1: Basic Agent Setup -### Example 2 - Referring Expression Comprehension +!!! example "Simple MCP Agent" -```python -from swarm_models.kosmos_two import Kosmos + ```python + from swarms import Agent -kosmos = Kosmos() + # Initialize agent with MCP integration + agent = Agent( + agent_name="Financial-Analysis-Agent", + agent_description="AI-powered financial advisor", + max_loops=1, + mcp_url="http://localhost:8000/sse", # Your MCP server + output_type="all", + ) -kosmos.referring_expression_comprehension( - "Show me the green bottle.", "https://example.com/bottle.jpg" -) -``` + # Execute task using MCP tools + result = agent.run( + "Get current Bitcoin price and analyze market trends" + ) + print(result) + ``` -4. Generate Referring Expressions: +### Step 2: Advanced Configuration -```python -kosmos.referring_expression_generation( - "It is on the table.", "https://example.com/table.jpg" -) -``` +!!! example "Production-Ready Setup" -### Example 3 - Referring Expression Generation + ```python + from swarms import Agent + from swarms.prompts.finance_agent_sys_prompt import FINANCIAL_AGENT_SYS_PROMPT -```python -from swarm_models.kosmos_two import Kosmos + agent = Agent( + agent_name="Advanced-Financial-Agent", + agent_description="Comprehensive market analysis agent", + system_prompt=FINANCIAL_AGENT_SYS_PROMPT, + max_loops=3, + mcp_url="http://production-server:8000/sse", + output_type="json", + # Additional parameters for production + temperature=0.1, + verbose=True, + ) + ``` -kosmos = Kosmos() +--- -kosmos.referring_expression_generation( - "It is on the table.", "https://example.com/table.jpg" -) -``` +## Integration Flow -5. Perform Grounded Visual Question Answering (VQA): +The following diagram illustrates the complete MCP integration workflow: -```python -kosmos.grounded_vqa("What is the color of the car?", "https://example.com/car.jpg") +```mermaid +graph TD + A[🚀 Agent Receives Task] --> B[🔗 Connect to MCP Server] + B --> C[🔍 Discover Available Tools] + C --> D[🧠 Analyze Task Requirements] + D --> E[📝 Generate Tool Request] + E --> F[📤 Send to MCP Server] + F --> G[⚙️ Server Processes Request] + G --> H[📥 Receive Response] + H --> I[🔄 Process & Validate] + I --> J[📊 Summarize Results] + J --> K[✅ Return Final Output] + + class A,K startEnd + class D,I,J process + class F,G,H communication ``` -### Example 4 - Grounded Visual Question Answering +### Detailed Process Breakdown -```python -from swarm_models.kosmos_two import Kosmos +!!! abstract "Process Steps" -kosmos = Kosmos() + === "1-3: Initialization" + + **Task Initiation** - Agent receives user query + + **Server Connection** - Establish MCP server link + + **Tool Discovery** - Fetch available tool schemas -kosmos.grounded_vqa("What is the color of the car?", "https://example.com/car.jpg") -``` + === "4-6: Execution" + + **Task Analysis** - Determine required tools + + **Request Generation** - Create structured API calls + + **Server Communication** - Send requests via SSE -6. Generate Grounded Image Captions: + === "7-9: Processing" + + **Server Processing** - MCP server executes tools + + **Response Handling** - Receive and validate data + + **Result Processing** - Parse and structure output -```python -kosmos.grounded_image_captioning("https://example.com/beach.jpg") -``` + === "10-11: Completion" + + **Summarization** - Generate user-friendly summary + + **Final Output** - Return complete response -### Example 5 - Grounded Image Captioning +--- -```python -from swarm_models.kosmos_two import Kosmos +## :material-cog: Configuration Options -kosmos = Kosmos() +### Agent Parameters -kosmos.grounded_image_captioning("https://example.com/beach.jpg") -``` +!!! note "Configuration Reference" -7. Generate Detailed Grounded Image Captions: + | Parameter | Type | Description | Default | Example | + |-----------|------|-------------|---------|---------| + | `mcp_url` | `str` | MCP server endpoint | `None` | `"http://localhost:8000/sse"` | + | `output_type` | `str` | Response format | `"str"` | `"json"`, `"all"`, `"dict"` | + | `max_loops` | `int` | Execution iterations | `1` | `3` | + | `temperature` | `float` | Response creativity | `0.1` | `0.1-1.0` | + | `verbose` | `bool` | Debug logging | `False` | `True` | -```python -kosmos.grounded_image_captioning_detailed("https://example.com/beach.jpg") -``` +--- -### Example 6 - Detailed Grounded Image Captioning +## :material-code-tags: Example Implementations -```python -from swarm_models.kosmos_two import Kosmos +### Cryptocurrency Trading Agent -kosmos = Kosmos() +!!! example "Crypto Price Monitor" -kosmos.grounded_image_captioning_detailed("https://example.com/beach.jpg") -``` + ```python + from swarms import Agent -8. Draw Entity Boxes on Image: + crypto_agent = Agent( + agent_name="Crypto-Trading-Agent", + agent_description="Real-time cryptocurrency market analyzer", + max_loops=2, + mcp_url="http://crypto-server:8000/sse", + output_type="json", + temperature=0.1, + ) -```python -image = kosmos.get_image("https://example.com/image.jpg") -entities = [ - ("apple", (0, 3), [(0.2, 0.3, 0.4, 0.5)]), - ("banana", (4, 9), [(0.6, 0.2, 0.8, 0.4)]), -] -kosmos.draw_entity_boxes_on_image(image, entities, show=True) -``` + # Multi-exchange price comparison + result = crypto_agent.run( + """ + Compare Bitcoin and Ethereum prices across OKX and HTX exchanges. + Calculate arbitrage opportunities and provide trading recommendations. + """ + ) + ``` -### Example 7 - Drawing Entity Boxes on Image +### Financial Analysis Suite -```python -from swarm_models.kosmos_two import Kosmos +!!! example "Advanced Financial Agent" -kosmos = Kosmos() + ```python + from swarms import Agent + from swarms.prompts.finance_agent_sys_prompt import FINANCIAL_AGENT_SYS_PROMPT -image = kosmos.get_image("https://example.com/image.jpg") -entities = [ - ("apple", (0, 3), [(0.2, 0.3, 0.4, 0.5)]), - ("banana", (4, 9), [(0.6, 0.2, 0.8, 0.4)]), -] -kosmos.draw_entity_boxes_on_image(image, entities, show=True) -``` + financial_agent = Agent( + agent_name="Financial-Analysis-Suite", + agent_description="Comprehensive financial market analyst", + system_prompt=FINANCIAL_AGENT_SYS_PROMPT, + max_loops=4, + mcp_url="http://finance-api:8000/sse", + output_type="all", + temperature=0.2, + ) -9. Generate Boxes for Entities: + # Complex market analysis + analysis = financial_agent.run( + """ + Perform a comprehensive analysis of Tesla (TSLA) stock: + 1. Current price and technical indicators + 2. Recent news sentiment analysis + 3. Competitor comparison (GM, Ford) + 4. Investment recommendation with risk assessment + """ + ) + ``` -```python -entities = [ - ("apple", (0, 3), [(0.2, 0.3, 0.4, 0.5)]), - ("banana", (4, 9), [(0.6, 0.2, 0.8, 0.4)]), -] -image = kosmos.generate_boxes( - "Find the apple and the banana in the image.", "https://example.com/image.jpg" -) -``` +### Custom Industry Agent -### Example 8 - Generating Boxes for Entities +!!! example "Healthcare Data Agent" -```python -from swarm_models.kosmos_two import Kosmos + ```python + from swarms import Agent -kosmos = Kosmos() -entities = [ - ("apple", (0, 3), [(0.2, 0.3, 0.4, 0.5)]), - ("banana", (4, 9), [(0.6, 0.2, 0.8, 0.4)]), -] -image = kosmos.generate_boxes( - "Find the apple and the banana in the image.", "https://example.com/image.jpg" -) -``` + healthcare_agent = Agent( + agent_name="Healthcare-Data-Agent", + agent_description="Medical data analysis and research assistant", + max_loops=3, + mcp_url="http://medical-api:8000/sse", + output_type="dict", + system_prompt=""" + You are a healthcare data analyst. Use available medical databases + and research tools to provide accurate, evidence-based information. + Always cite sources and include confidence levels. + """, + ) -## How Kosmos Works + research = healthcare_agent.run( + "Research latest treatments for Type 2 diabetes and their efficacy rates" + ) + ``` -Kosmos is a multimodal AI model that combines text and image processing. It uses the ydshieh/kosmos-2-patch14-224 model for understanding and generating responses. Here's how it works: +--- -1. **Initialization**: When you create a Kosmos instance, it loads the ydshieh/kosmos-2-patch14-224 model for multimodal tasks. +## :material-server: MCP Server Development -2. **Processing Text and Images**: Kosmos can process both text prompts and images. It takes a textual prompt and an image URL as input. +### FastMCP Server Example -3. **Task Execution**: Based on the task you specify, Kosmos generates informative responses by combining natural language understanding with image analysis. +!!! example "Building a Custom MCP Server" -4. **Drawing Entity Boxes**: You can use the `draw_entity_boxes_on_image` method to draw bounding boxes around entities in an image. + ```python + from mcp.server.fastmcp import FastMCP + import requests + from typing import Optional + import asyncio -5. **Generating Boxes for Entities**: The `generate_boxes` method allows you to generate bounding boxes for entities mentioned in a prompt. + # Initialize MCP server + mcp = FastMCP("crypto_analysis_server") -## Parameters + @mcp.tool( + name="get_crypto_price", + description="Fetch current cryptocurrency price with market data", + ) + def get_crypto_price( + symbol: str, + currency: str = "USD", + include_24h_change: bool = True + ) -> dict: + """ + Get real-time cryptocurrency price and market data. + + Args: + symbol: Cryptocurrency symbol (e.g., BTC, ETH) + currency: Target currency for price (default: USD) + include_24h_change: Include 24-hour price change data + """ + try: + url = f"https://api.coingecko.com/api/v3/simple/price" + params = { + "ids": symbol.lower(), + "vs_currencies": currency.lower(), + "include_24hr_change": include_24h_change + } + + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() + + data = response.json() + return { + "symbol": symbol.upper(), + "price": data[symbol.lower()][currency.lower()], + "currency": currency.upper(), + "change_24h": data[symbol.lower()].get("24h_change", 0), + "timestamp": "2024-01-15T10:30:00Z" + } + + except Exception as e: + return {"error": f"Failed to fetch price: {str(e)}"} -- `model_name`: The name or path of the Kosmos model to be used. By default, it uses the ydshieh/kosmos-2-patch14-224 model. + @mcp.tool( + name="analyze_market_sentiment", + description="Analyze cryptocurrency market sentiment from social media", + ) + def analyze_market_sentiment(symbol: str, timeframe: str = "24h") -> dict: + """Analyze market sentiment for a cryptocurrency.""" + # Implement sentiment analysis logic + return { + "symbol": symbol, + "sentiment_score": 0.75, + "sentiment": "Bullish", + "confidence": 0.85, + "timeframe": timeframe + } -## Additional Information + if __name__ == "__main__": + mcp.run(transport="sse") + ``` -- Kosmos can handle various multimodal tasks, making it a versatile tool for understanding and generating content. -- You can provide image URLs for image-based tasks, and Kosmos will automatically retrieve and process the images. -- The `draw_entity_boxes_on_image` method is useful for visualizing the results of multimodal grounding tasks. -- The `generate_boxes` method is handy for generating bounding boxes around entities mentioned in a textual prompt. +### Server Best Practices -That concludes the documentation for Kosmos. We hope you find this multimodal AI model valuable for your projects. If you have any questions or encounter any issues, please refer to the Kosmos documentation for -further assistance. Enjoy working with Kosmos! +!!! tip "Server Development Guidelines" + === "🏗️ Architecture" + - **Modular Design**: Separate tools into logical modules + - **Error Handling**: Implement comprehensive error responses + - **Async Support**: Use async/await for better performance + - **Type Hints**: Include proper type annotations --------------------------------------------------- + === "🔒 Security" + - **Input Validation**: Sanitize all user inputs + - **Rate Limiting**: Implement request throttling + - **Authentication**: Add API key validation + - **Logging**: Log all requests and responses -# File: swarms/models/langchain.md + === "⚡ Performance" + - **Caching**: Cache frequently requested data + - **Connection Pooling**: Reuse database connections + - **Timeouts**: Set appropriate request timeouts + - **Load Testing**: Test under realistic load +--- +## :material-alert: Current Limitations --------------------------------------------------- +!!! warning "Important Limitations" -# File: swarms/models/layoutlm_document_qa.md + ### 🚧 MCPConnection Model + + The enhanced connection model is under development: + + ```python + # ❌ Not available yet + from swarms.schemas.mcp_schemas import MCPConnection + + mcp_config = MCPConnection( + url="http://server:8000/sse", + headers={"Authorization": "Bearer token"}, + timeout=30, + retry_attempts=3 + ) + + # ✅ Use direct URL instead + mcp_url = "http://server:8000/sse" + ``` -# `LayoutLMDocumentQA` Documentation + ### 🚧 Single Server Limitation + + Currently supports one server per agent: + + ```python + # ❌ Multiple servers not supported + mcp_servers = [ + "http://server1:8000/sse", + "http://server2:8000/sse" + ] + + # ✅ Single server only + mcp_url = "http://primary-server:8000/sse" + ``` -## Introduction + ### 🚧 Sequential Execution + + Tools execute sequentially, not in parallel: + + ```python + # Current: tool1() → tool2() → tool3() + # Future: tool1() | tool2() | tool3() (parallel) + ``` -Welcome to the documentation for LayoutLMDocumentQA, a multimodal model designed for visual question answering (QA) on real-world documents, such as invoices, PDFs, and more. This comprehensive documentation will provide you with a deep understanding of the LayoutLMDocumentQA class, its architecture, usage, and examples. +--- -## Overview +## :material-wrench: Troubleshooting -LayoutLMDocumentQA is a versatile model that combines layout-based understanding of documents with natural language processing to answer questions about the content of documents. It is particularly useful for automating tasks like invoice processing, extracting information from PDFs, and handling various document-based QA scenarios. +### Common Issues & Solutions -## Class Definition +!!! bug "Connection Problems" -```python -class LayoutLMDocumentQA(AbstractModel): - def __init__( - self, - model_name: str = "impira/layoutlm-document-qa", - task: str = "document-question-answering", - ): -``` + === "Server Unreachable" + **Symptoms**: Connection timeout or refused + + **Solutions**: + ```bash + # Check server status + curl -I http://localhost:8000/sse + + # Verify port is open + netstat -tulpn | grep :8000 + + # Test network connectivity + ping your-server-host + ``` -## Purpose + === "Authentication Errors" + **Symptoms**: 401/403 HTTP errors + + **Solutions**: + ```python + # Verify API credentials + headers = {"Authorization": "Bearer your-token"} + + # Check token expiration + # Validate permissions + ``` -The LayoutLMDocumentQA class serves the following primary purposes: + === "SSL/TLS Issues" + **Symptoms**: Certificate errors + + **Solutions**: + ```python + # For development only + import ssl + ssl._create_default_https_context = ssl._create_unverified_context + ``` -1. **Document QA**: LayoutLMDocumentQA is specifically designed for document-based question answering. It can process both the textual content and the layout of a document to answer questions. +!!! bug "Tool Discovery Failures" -2. **Multimodal Understanding**: It combines natural language understanding with document layout analysis, making it suitable for documents with complex structures. + === "Empty Tool List" + **Symptoms**: No tools found from server + + **Debugging**: + ```python + # Check server tool registration + @mcp.tool(name="tool_name", description="...") + def your_tool(): + pass + + # Verify server startup logs + # Check tool endpoint responses + ``` -## Parameters + === "Schema Validation Errors" + **Symptoms**: Invalid tool parameters + + **Solutions**: + ```python + # Ensure proper type hints + def tool(param: str, optional: int = 0) -> dict: + return {"result": "success"} + + # Validate parameter types + # Check required vs optional parameters + ``` -- `model_name` (str): The name or path of the pretrained LayoutLMDocumentQA model. Default: "impira/layoutlm-document-qa". -- `task` (str): The specific task for which the model will be used. Default: "document-question-answering". +!!! bug "Performance Issues" -## Usage + === "Slow Response Times" + **Symptoms**: Long wait times for responses + + **Optimization**: + ```python + # Increase timeout + agent = Agent( + mcp_url="http://server:8000/sse", + timeout=60, # seconds + ) + + # Optimize server performance + # Use connection pooling + # Implement caching + ``` -To use LayoutLMDocumentQA, follow these steps: + === "Memory Usage" + **Symptoms**: High memory consumption + + **Solutions**: + ```python + # Limit max_loops + agent = Agent(max_loops=2) + + # Use streaming for large responses + # Implement garbage collection + ``` -1. Initialize the LayoutLMDocumentQA instance: +### Debugging Tools -```python -from swarm_models import LayoutLMDocumentQA +!!! tip "Debug Configuration" -layout_lm_doc_qa = LayoutLMDocumentQA() -``` + ```python + import logging + + # Enable debug logging + logging.basicConfig(level=logging.DEBUG) + + agent = Agent( + agent_name="Debug-Agent", + mcp_url="http://localhost:8000/sse", + verbose=True, # Enable verbose output + output_type="all", # Get full execution trace + ) + + # Monitor network traffic + # Check server logs + # Use profiling tools + ``` -### Example 1 - Initialization +--- -```python -layout_lm_doc_qa = LayoutLMDocumentQA() -``` +## :material-security: Security Best Practices -2. Ask a question about a document and provide the document's image path: +### Authentication & Authorization -```python -question = "What is the total amount?" -image_path = "path/to/document_image.png" -answer = layout_lm_doc_qa(question, image_path) -``` +!!! shield "Security Checklist" -### Example 2 - Document QA + === "🔑 Authentication" + - **API Keys**: Use strong, unique API keys + - **Token Rotation**: Implement automatic token refresh + - **Encryption**: Use HTTPS for all communications + - **Storage**: Secure credential storage (environment variables) -```python -layout_lm_doc_qa = LayoutLMDocumentQA() -question = "What is the total amount?" -image_path = "path/to/document_image.png" -answer = layout_lm_doc_qa(question, image_path) -``` + === "🛡️ Authorization" + - **Role-Based Access**: Implement user role restrictions + - **Tool Permissions**: Limit tool access per user/agent + - **Rate Limiting**: Prevent abuse with request limits + - **Audit Logging**: Log all tool executions -## How LayoutLMDocumentQA Works + === "🔒 Data Protection" + - **Input Sanitization**: Validate all user inputs + - **Output Filtering**: Sanitize sensitive data in responses + - **Encryption**: Encrypt sensitive data in transit/rest + - **Compliance**: Follow industry standards (GDPR, HIPAA) -LayoutLMDocumentQA employs a multimodal approach to document QA. Here's how it works: +### Secure Configuration -1. **Initialization**: When you create a LayoutLMDocumentQA instance, you can specify the model to use and the task, which is "document-question-answering" by default. +!!! example "Production Security Setup" -2. **Question and Document**: You provide a question about the document and the image path of the document to the LayoutLMDocumentQA instance. + ```python + import os + from swarms import Agent -3. **Multimodal Processing**: LayoutLMDocumentQA processes both the question and the document image. It combines layout-based analysis with natural language understanding. + # Secure configuration + agent = Agent( + agent_name="Production-Agent", + mcp_url=os.getenv("MCP_SERVER_URL"), # From environment + # Additional security headers would go here when MCPConnection is available + verbose=False, # Disable verbose logging in production + output_type="json", # Structured output only + ) -4. **Answer Generation**: The model generates an answer to the question based on its analysis of the document layout and content. + # Environment variables (.env file) + """ + MCP_SERVER_URL=https://secure-server.company.com/sse + MCP_API_KEY=your-secure-api-key + MCP_TIMEOUT=30 + """ + ``` -## Additional Information +--- -- LayoutLMDocumentQA uses the "impira/layoutlm-document-qa" pretrained model, which is specifically designed for document-based question answering. -- You can adapt this model to various document QA scenarios by changing the task and providing relevant questions and documents. -- This model is particularly useful for automating document-based tasks and extracting valuable information from structured documents. +## :material-chart-line: Performance Optimization -That concludes the documentation for LayoutLMDocumentQA. We hope you find this tool valuable for your document-based question answering needs. If you have any questions or encounter any issues, please refer to the LayoutLMDocumentQA documentation for further assistance. Enjoy using LayoutLMDocumentQA! +### Agent Optimization --------------------------------------------------- +!!! rocket "Performance Tips" -# File: swarms/models/llama3.md + === "⚡ Configuration" + ```python + # Optimized agent settings + agent = Agent( + max_loops=2, # Limit iterations + temperature=0.1, # Reduce randomness + output_type="json", # Structured output + # Future: connection_pool_size=10 + ) + ``` -## Llava3 + === "🔄 Caching" + ```python + # Implement response caching + from functools import lru_cache + + @lru_cache(maxsize=100) + def cached_mcp_call(query): + return agent.run(query) + ``` + === "📊 Monitoring" + ```python + import time + + start_time = time.time() + result = agent.run("query") + execution_time = time.time() - start_time + + print(f"Execution time: {execution_time:.2f}s") + ``` -```python -from transformers import AutoTokenizer, AutoModelForCausalLM -import torch -from swarm_models.base_llm import BaseLLM +### Server Optimization +!!! rocket "Server Performance" -class Llama3(BaseLLM): - """ - Llama3 class represents a Llama model for natural language generation. + ```python + from mcp.server.fastmcp import FastMCP + import asyncio + from concurrent.futures import ThreadPoolExecutor + + mcp = FastMCP("optimized_server") + + # Async tool with thread pool + @mcp.tool(name="async_heavy_task") + async def heavy_computation(data: str) -> dict: + loop = asyncio.get_event_loop() + with ThreadPoolExecutor() as executor: + result = await loop.run_in_executor( + executor, process_heavy_task, data + ) + return result - Args: - model_id (str): The ID of the Llama model to use. - system_prompt (str): The system prompt to use for generating responses. - temperature (float): The temperature value for controlling the randomness of the generated responses. - top_p (float): The top-p value for controlling the diversity of the generated responses. - max_tokens (int): The maximum number of tokens to generate in the response. - **kwargs: Additional keyword arguments. + def process_heavy_task(data): + # CPU-intensive processing + return {"processed": data} + ``` - Attributes: - model_id (str): The ID of the Llama model being used. - system_prompt (str): The system prompt for generating responses. - temperature (float): The temperature value for generating responses. - top_p (float): The top-p value for generating responses. - max_tokens (int): The maximum number of tokens to generate in the response. - tokenizer (AutoTokenizer): The tokenizer for the Llama model. - model (AutoModelForCausalLM): The Llama model for generating responses. +--- - Methods: - run(task, *args, **kwargs): Generates a response for the given task. +## :material-timeline: Future Roadmap - """ +### Upcoming Features - def __init__( - self, - model_id="meta-llama/Meta-Llama-3-8B-Instruct", - system_prompt: str = None, - temperature: float = 0.6, - top_p: float = 0.9, - max_tokens: int = 4000, - **kwargs, - ): - self.model_id = model_id - self.system_prompt = system_prompt - self.temperature = temperature - self.top_p = top_p - self.max_tokens = max_tokens - self.tokenizer = AutoTokenizer.from_pretrained(model_id) - self.model = AutoModelForCausalLM.from_pretrained( - model_id, - torch_dtype=torch.bfloat16, - device_map="auto", - ) +!!! rocket "Development Timeline" - def run(self, task: str, *args, **kwargs): - """ - Generates a response for the given task. + === "1 Week" + - **MCPConnection Model** - Enhanced configuration + - **Authentication Support** - Built-in auth mechanisms + - **Error Recovery** - Automatic retry logic + - **Connection Pooling** - Improved performance - Args: - task (str): The user's task or input. + === "2 Week" + - **Multiple Server Support** - Connect to multiple MCPs + - **Parallel Execution** - Concurrent tool calling + - **Load Balancing** - Distribute requests across servers + - **Advanced Monitoring** - Real-time metrics - Returns: - str: The generated response. + === "3 Week" + - **Auto-discovery** - Automatic server detection + - **Workflow Engine** - Complex task orchestration + - **Plugin System** - Custom MCP extensions + - **Cloud Integration** - Native cloud provider support - """ - messages = [ - {"role": "system", "content": self.system_prompt}, - {"role": "user", "content": task}, - ] +### Contributing - input_ids = self.tokenizer.apply_chat_template( - messages, add_generation_prompt=True, return_tensors="pt" - ).to(self.model.device) +!!! heart "Get Involved" - terminators = [ - self.tokenizer.eos_token_id, - self.tokenizer.convert_tokens_to_ids("<|eot_id|>"), - ] + We welcome contributions to improve MCP integration: - outputs = self.model.generate( - input_ids, - max_new_tokens=self.max_tokens, - eos_token_id=terminators, - do_sample=True, - temperature=self.temperature, - top_p=self.top_p, - *args, - **kwargs, - ) - response = outputs[0][input_ids.shape[-1] :] - return self.tokenizer.decode( - response, skip_special_tokens=True - ) -``` + - **Bug Reports**: [GitHub Issues](https://github.com/kyegomez/swarms/issues) + - **Feature Requests**: [Discussions](https://github.com/kyegomez/swarms/discussions) + - **Code Contributions**: [Pull Requests](https://github.com/kyegomez/swarms/pulls) + - **Documentation**: Help improve these docs --------------------------------------------------- +--- -# File: swarms/models/models_available_overview.md +## :material-help-circle: Support & Resources -## The Swarms Framework: A Comprehensive Guide to Model APIs and Usage +### Getting Help -### Introduction +!!! question "Need Assistance?" -The Swarms framework is a versatile and robust tool designed to streamline the integration and orchestration of multiple AI models, making it easier for developers to build sophisticated multi-agent systems. This blog aims to provide a detailed guide on using the Swarms framework, covering the various models it supports, common methods, settings, and practical examples. + === "📚 Documentation" + - [Official Docs](https://docs.swarms.world) + - [Tutorials](https://docs.swarms.world/tutorials) -### Overview of the Swarms Framework + === "💬 Community" + - [Discord Server](https://discord.gg/jM3Z6M9uMq) + - [GitHub Discussions](https://github.com/kyegomez/swarms/discussions) -Swarms is a "framework of frameworks" that allows seamless integration of various AI models, including those from OpenAI, Anthropic, Hugging Face, Azure, and more. This flexibility enables users to leverage the strengths of different models within a single application. The framework provides a unified interface for model interaction, simplifying the process of integrating and managing multiple AI models. + === "🔧 Development" + - [GitHub Repository](https://github.com/kyegomez/swarms) + - [Example Projects](https://github.com/kyegomez/swarms/tree/main/examples) + - [Contributing Guide](https://github.com/kyegomez/swarms/blob/main/CONTRIBUTING.md) -### Getting Started with Swarms +### Quick Reference -To get started with Swarms, you need to install the framework and set up the necessary environment variables. Here's a step-by-step guide: +!!! abstract "Cheat Sheet" -#### Installation + ```python + # Basic setup + from swarms import Agent + + agent = Agent( + agent_name="Your-Agent", + mcp_url="http://localhost:8000/sse", + output_type="json", + max_loops=2 + ) + + # Execute task + result = agent.run("Your query here") + + # Common patterns + crypto_query = "Get Bitcoin price" + analysis_query = "Analyze Tesla stock performance" + research_query = "Research recent AI developments" + ``` -You can install the Swarms framework using pip: +--- -```bash -pip install swarms -``` +## :material-check-all: Conclusion -#### Setting Up Environment Variables +The MCP integration brings powerful external tool connectivity to Swarms agents, enabling them to access real-world data and services through a standardized protocol. While some advanced features are still in development, the current implementation provides robust functionality for most use cases. -Swarms relies on environment variables to manage API keys and other configurations. You can use the `dotenv` package to load these variables from a `.env` file. +!!! success "Ready to Start?" + + Begin with the [Quick Start](#quick-start) section and explore the [examples](#example-implementations) to see MCP integration in action. As new features become available, this documentation will be updated with the latest capabilities and best practices. -```bash -pip install python-dotenv -``` +!!! tip "Stay Updated" + + Join our [Discord community](https://discord.gg/jM3Z6M9uMq) to stay informed about new MCP features and connect with other developers building amazing agent applications. -Create a `.env` file in your project directory and add your API keys and other settings: +--- -```env -OPENAI_API_KEY=your_openai_api_key -ANTHROPIC_API_KEY=your_anthropic_api_key -AZURE_OPENAI_ENDPOINT=your_azure_openai_endpoint -AZURE_OPENAI_DEPLOYMENT=your_azure_openai_deployment -OPENAI_API_VERSION=your_openai_api_version -AZURE_OPENAI_API_KEY=your_azure_openai_api_key -AZURE_OPENAI_AD_TOKEN=your_azure_openai_ad_token -``` +
-### Using the Swarms Framework +- :material-rocket: **[Quick Start](#quick-start)** -Swarms supports a variety of models from different providers. Here are some examples of how to use these models within the Swarms framework. + Get up and running with MCP integration in minutes -#### Using the Anthropic Model +- :material-book-open: **[Examples](#example-implementations)** -The Anthropic model is one of the many models supported by Swarms. Here's how you can use it: + Explore real-world implementations and use cases -```python -import os -from swarm_models import Anthropic +- :material-cog: **[Configuration](#configuration-options)** -# Load the environment variables -anthropic_api_key = os.getenv("ANTHROPIC_API_KEY") + Learn about all available configuration options -# Create an instance of the Anthropic model -model = Anthropic(anthropic_api_key=anthropic_api_key) +- :material-help: **[Troubleshooting](#troubleshooting)** -# Define the task -task = "What is quantum field theory? What are 3 books on the field?" + Solve common issues and optimize performance -# Generate a response -response = model(task) +
-# Print the response -print(response) -``` -#### Using the HuggingfaceLLM Model +-------------------------------------------------- -HuggingfaceLLM allows you to use models from Hugging Face's vast repository. Here's an example: +# File: swarms\structs\agent_multi_agent_communication.md -```python -from swarm_models import HuggingfaceLLM +# Agent Multi-Agent Communication Methods -# Define the model ID -model_id = "NousResearch/Yarn-Mistral-7b-128k" +The Agent class provides powerful built-in methods for facilitating communication and collaboration between multiple agents. These methods enable agents to talk to each other, pass information, and coordinate complex multi-agent workflows seamlessly. -# Create an instance of the HuggingfaceLLM model -inference = HuggingfaceLLM(model_id=model_id) +## Overview -# Define the task -task = "Once upon a time" +Multi-agent communication is essential for building sophisticated AI systems where different agents need to collaborate, share information, and coordinate their actions. The Agent class provides several methods to facilitate this communication: -# Generate a response -generated_text = inference(task) -print(generated_text) -``` +| Method | Purpose | Use Case | +|--------|---------|----------| +| `talk_to` | Direct communication between two agents | Agent handoffs, expert consultation | +| `talk_to_multiple_agents` | Concurrent communication with multiple agents | Broadcasting, consensus building | +| `receive_message` | Process incoming messages from other agents | Message handling, task delegation | +| `send_agent_message` | Send formatted messages to other agents | Direct messaging, notifications | +## Features +| Feature | Description | +|---------------------------------|--------------------------------------------------------------------| +| **Direct Agent Communication** | Enable one-to-one conversations between agents | +| **Concurrent Multi-Agent Communication** | Broadcast messages to multiple agents simultaneously | +| **Message Processing** | Handle incoming messages with contextual formatting | +| **Error Handling** | Robust error handling for failed communications | +| **Threading Support** | Efficient concurrent processing using ThreadPoolExecutor | +| **Flexible Parameters** | Support for images, custom arguments, and kwargs | -#### Using the OpenAIChat Model +--- -The OpenAIChat model is designed for conversational tasks. Here's how to use it: +## Core Methods -```python -import os -from swarm_models import OpenAIChat +### `talk_to(agent, task, img=None, *args, **kwargs)` -# Load the environment variables -openai_api_key = os.getenv("OPENAI_API_KEY") +Enables direct communication between the current agent and another agent. The method processes the task, generates a response, and then passes that response to the target agent. -# Create an instance of the OpenAIChat model -openai = OpenAIChat(openai_api_key=openai_api_key, verbose=False) +**Parameters:** -# Define the task -chat = openai("What are quantum fields?") -print(chat) -``` +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `agent` | `Any` | Required | The target agent instance to communicate with | +| `task` | `str` | Required | The task or message to send to the agent | +| `img` | `str` | `None` | Optional image path for multimodal communication | +| `*args` | `Any` | - | Additional positional arguments | +| `**kwargs` | `Any` | - | Additional keyword arguments | -#### Using the TogetherLLM Model +**Returns:** `Any` - The response from the target agent -TogetherLLM supports models from the Together ecosystem. Here's an example: +**Usage Example:** ```python -from swarms import TogetherLLM +from swarms import Agent -# Initialize the model with your parameters -model = TogetherLLM( - model_name="mistralai/Mixtral-8x7B-Instruct-v0.1", - max_tokens=1000, - together_api_key="your_together_api_key", +# Create two specialized agents +researcher = Agent( + agent_name="Research-Agent", + system_prompt="You are a research specialist focused on gathering and analyzing information.", + max_loops=1, ) -# Run the model -response = model.run("Generate a blog post about the best way to make money online.") -print(response) -``` - -#### Using the Azure OpenAI Model - -The Azure OpenAI model is another powerful tool that can be integrated with Swarms. Here's how to use it: - -```python -import os -from dotenv import load_dotenv -from swarms import AzureOpenAI - -# Load the environment variables -load_dotenv() - -# Create an instance of the AzureOpenAI class -model = AzureOpenAI( - azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"), - deployment_name=os.getenv("AZURE_OPENAI_DEPLOYMENT"), - openai_api_version=os.getenv("OPENAI_API_VERSION"), - openai_api_key=os.getenv("AZURE_OPENAI_API_KEY"), - azure_ad_token=os.getenv("AZURE_OPENAI_AD_TOKEN"), +analyst = Agent( + agent_name="Analysis-Agent", + system_prompt="You are an analytical specialist focused on interpreting research data.", + max_loops=1, ) -# Define the prompt -prompt = ( - "Analyze this load document and assess it for any risks and" - " create a table in markdown format." +# Agent communication +research_result = researcher.talk_to( + agent=analyst, + task="Analyze the market trends for renewable energy stocks" ) -# Generate a response -response = model(prompt) -print(response) +print(research_result) ``` +### `talk_to_multiple_agents(agents, task, *args, **kwargs)` + +Enables concurrent communication with multiple agents using ThreadPoolExecutor for efficient parallel processing. + +**Parameters:** + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `agents` | `List[Union[Any, Callable]]` | Required | List of agent instances to communicate with | +| `task` | `str` | Required | The task or message to send to all agents | +| `*args` | `Any` | - | Additional positional arguments | +| `**kwargs` | `Any` | - | Additional keyword arguments | -#### Using the GPT4VisionAPI Model +**Returns:** `List[Any]` - List of responses from all agents (or None for failed communications) -The GPT4VisionAPI model can analyze images and provide detailed insights. Here's how to use it: +**Usage Example:** ```python -import os -from dotenv import load_dotenv -from swarms import GPT4VisionAPI +from swarms import Agent -# Load the environment variables -load_dotenv() +# Create multiple specialized agents +agents = [ + Agent( + agent_name="Financial-Analyst", + system_prompt="You are a financial analysis expert.", + max_loops=1, + ), + Agent( + agent_name="Risk-Assessor", + system_prompt="You are a risk assessment specialist.", + max_loops=1, + ), + Agent( + agent_name="Market-Researcher", + system_prompt="You are a market research expert.", + max_loops=1, + ) +] -# Get the API key from the environment variables -api_key = os.getenv("OPENAI_API_KEY") +coordinator = Agent( + agent_name="Coordinator-Agent", + system_prompt="You coordinate multi-agent analysis.", + max_loops=1, +) -# Create an instance of the GPT4VisionAPI class -gpt4vision = GPT4VisionAPI( - openai_api_key=api_key, - model_name="gpt-4o", - max_tokens=1000, - openai_proxy="https://api.openai.com/v1/chat/completions", +# Broadcast to multiple agents +responses = coordinator.talk_to_multiple_agents( + agents=agents, + task="Evaluate the investment potential of Tesla stock" ) -# Define the URL of the image to analyze -img = "ear.png" +# Process responses +for i, response in enumerate(responses): + if response: + print(f"Agent {i+1} Response: {response}") + else: + print(f"Agent {i+1} failed to respond") +``` + +### `receive_message(agent_name, task, *args, **kwargs)` -# Define the task to perform on the image -task = "What is this image" +Processes incoming messages from other agents with proper context formatting. -# Run the GPT4VisionAPI on the image with the specified task -answer = gpt4vision.run(task, img, return_json=True) +**Parameters:** -# Print the answer -print(answer) -``` +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `agent_name` | `str` | Required | Name of the sending agent | +| `task` | `str` | Required | The message content | +| `*args` | `Any` | - | Additional positional arguments | +| `**kwargs` | `Any` | - | Additional keyword arguments | -#### Using the QwenVLMultiModal Model +**Returns:** `Any` - The agent's response to the received message -The QwenVLMultiModal model is designed for multi-modal tasks, such as processing both text and images. Here's an example of how to use it: +**Usage Example:** ```python -from swarms import QwenVLMultiModal +from swarms import Agent -# Instantiate the QwenVLMultiModal model -model = QwenVLMultiModal( - model_name="Qwen/Qwen-VL-Chat", - device="cuda", - quantize=True, +# Create an agent that can receive messages +recipient_agent = Agent( + agent_name="Support-Agent", + system_prompt="You provide helpful support and assistance.", + max_loops=1, ) -# Run the model -response = model("Hello, how are you?", "https://example.com/image.jpg") +# Simulate receiving a message from another agent +response = recipient_agent.receive_message( + agent_name="Customer-Service-Agent", + task="A customer is asking about refund policies. Can you help?" +) -# Print the response print(response) ``` +### `send_agent_message(agent_name, message, *args, **kwargs)` -### Common Methods in Swarms - -Swarms provides several common methods that are useful across different models. One of the most frequently used methods is `__call__`. - -#### The `__call__` Method - -The `__call__` method is used to run the model on a given task. Here is a generic example: +Sends a formatted message from the current agent to a specified target agent. -```python -# Assuming `model` is an instance of any supported model -task = "Explain the theory of relativity." -response = model(task) -print(response) -``` +**Parameters:** -This method abstracts the complexity of interacting with different model APIs, providing a consistent interface for executing tasks. +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `agent_name` | `str` | Required | Name of the target agent | +| `message` | `str` | Required | The message to send | +| `*args` | `Any` | - | Additional positional arguments | +| `**kwargs` | `Any` | - | Additional keyword arguments | -### Common Settings in Swarms +**Returns:** `Any` - The result of sending the message -Swarms allows you to configure various settings to customize the behavior of the models. Here are some common settings: +**Usage Example:** -#### API Keys +```python +from swarms import Agent -API keys are essential for authenticating and accessing the models. These keys are typically set through environment variables: +sender_agent = Agent( + agent_name="Notification-Agent", + system_prompt="You send notifications and updates.", + max_loops=1, +) -```python -import os +# Send a message to another agent +result = sender_agent.send_agent_message( + agent_name="Task-Manager-Agent", + message="Task XYZ has been completed successfully" +) -# Set API keys as environment variables -os.environ['OPENAI_API_KEY'] = 'your_openai_api_key' -os.environ['ANTHROPIC_API_KEY'] = 'your_anthropic_api_key' +print(result) ``` -#### Model-Specific Settings -Different models may have specific settings that need to be configured. For example, the `AzureOpenAI` model requires several settings related to the Azure environment: +This comprehensive guide covers all aspects of multi-agent communication using the Agent class methods. These methods provide the foundation for building sophisticated multi-agent systems with robust communication capabilities. -```python -model = AzureOpenAI( - azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"), - deployment_name=os.getenv("AZURE_OPENAI_DEPLOYMENT"), - openai_api_version=os.getenv("OPENAI_API_VERSION"), - openai_api_key=os.getenv("AZURE_OPENAI_API_KEY"), - azure_ad_token=os.getenv("AZURE_OPENAI_AD_TOKEN"), -) -``` +-------------------------------------------------- -### Advanced Usage and Best Practices +# File: swarms\structs\agent_rearrange.md -To make the most out of the Swarms framework, consider the following best practices: +# `AgentRearrange` Class -#### Extensive Logging +The `AgentRearrange` class represents a swarm of agents for rearranging tasks. It allows you to create a swarm of agents, add or remove agents from the swarm, and run the swarm to process tasks based on a specified flow pattern. -Use logging to monitor the behavior and performance of your models. The `loguru` library is recommended for its simplicity and flexibility: +## Attributes +---------- -```python -from loguru import logger +| Attribute | Type | Description | +| --- | --- | --- | +| `id` | `str` | Unique identifier for the swarm | +| `name` | `str` | Name of the swarm | +| `description` | `str` | Description of the swarm's purpose | +| `agents` | `dict` | Dictionary mapping agent names to Agent objects | +| `flow` | `str` | Flow pattern defining task execution order | +| `max_loops` | `int` | Maximum number of execution loops | +| `verbose` | `bool` | Whether to enable verbose logging | +| `memory_system` | `BaseVectorDatabase` | Memory system for storing agent interactions | +| `human_in_the_loop` | `bool` | Whether human intervention is enabled | +| `custom_human_in_the_loop` | `Callable` | Custom function for human intervention | +| `return_json` | `bool` | Whether to return output in JSON format | +| `output_type` | `OutputType` | Format of output ("all", "final", "list", or "dict") | +| `docs` | `List[str]` | List of document paths to add to agent prompts | +| `doc_folder` | `str` | Folder path containing documents to add to agent prompts | +| `swarm_history` | `dict` | History of agent interactions | -# Log model interactions -logger.info("Running task on Anthropic model") -response = model(task) -logger.info(f"Response: {response}") -``` -#### Error Handling +## Methods +------- -Implement robust error handling to manage API failures and other issues gracefully: +### `__init__(self, agents: List[Agent] = None, flow: str = None, max_loops: int = 1, verbose: bool = True)` -```python -try: - response = model(task) -except Exception as e: - logger.error(f"Error running task: {e}") - response = "An error occurred while processing your request." -print(response) -``` +Initializes the `AgentRearrange` object. -### Conclusion +| Parameter | Type | Description | +| --- | --- | --- | +| `agents` | `List[Agent]` (optional) | A list of `Agent` objects. Defaults to `None`. | +| `flow` | `str` (optional) | The flow pattern of the tasks. Defaults to `None`. | +| `max_loops` | `int` (optional) | The maximum number of loops for the agents to run. Defaults to `1`. | +| `verbose` | `bool` (optional) | Whether to enable verbose logging or not. Defaults to `True`. | -The Swarms framework provides a powerful and flexible way to integrate and manage multiple AI models within a single application. By following the guidelines and examples provided in this blog, you can leverage Swarms to build sophisticated, multi-agent systems with ease. Whether you're using models from OpenAI, Anthropic, Azure, or Hugging Face, +### `add_agent(self, agent: Agent)` -Swarms offers a unified interface that simplifies the process of model orchestration and execution. +Adds an agent to the swarm. --------------------------------------------------- +| Parameter | Type | Description | +| --- | --- | --- | +| `agent` | `Agent` | The agent to be added. | -# File: swarms/models/nougat.md +### `remove_agent(self, agent_name: str)` -# `Nougat` Documentation +Removes an agent from the swarm. -## Introduction +| Parameter | Type | Description | +| --- | --- | --- | +| `agent_name` | `str` | The name of the agent to be removed. | -Welcome to the documentation for Nougat, a versatile model designed by Meta for transcribing scientific PDFs into user-friendly Markdown format, extracting information from PDFs, and extracting metadata from PDF documents. This documentation will provide you with a deep understanding of the Nougat class, its architecture, usage, and examples. +### `add_agents(self, agents: List[Agent])` -## Overview +Adds multiple agents to the swarm. -Nougat is a powerful tool that combines language modeling and image processing capabilities to convert scientific PDF documents into Markdown format. It is particularly useful for researchers, students, and professionals who need to extract valuable information from PDFs quickly. With Nougat, you can simplify complex PDFs, making their content more accessible and easy to work with. +| Parameter | Type | Description | +| --- | --- | --- | +| `agents` | `List[Agent]` | A list of `Agent` objects. | -## Class Definition +### `validate_flow(self)` -```python -class Nougat: - def __init__( - self, - model_name_or_path="facebook/nougat-base", - min_length: int = 1, - max_new_tokens: int = 30, - ): -``` +Validates the flow pattern. -## Purpose +**Raises:** -The Nougat class serves the following primary purposes: +- `ValueError`: If the flow pattern is incorrectly formatted or contains duplicate agent names. -1. **PDF Transcription**: Nougat is designed to transcribe scientific PDFs into Markdown format. It helps convert complex PDF documents into a more readable and structured format, making it easier to extract information. +**Returns:** -2. **Information Extraction**: It allows users to extract valuable information and content from PDFs efficiently. This can be particularly useful for researchers and professionals who need to extract data, figures, or text from scientific papers. +- `bool`: `True` if the flow pattern is valid. -3. **Metadata Extraction**: Nougat can also extract metadata from PDF documents, providing essential details about the document, such as title, author, and publication date. +### `run(self, task: str = None, img: str = None, device: str = "cpu", device_id: int = 1, all_cores: bool = True, all_gpus: bool = False, *args, **kwargs)` -## Parameters +Executes the agent rearrangement task with specified compute resources. -- `model_name_or_path` (str): The name or path of the pretrained Nougat model. Default: "facebook/nougat-base". -- `min_length` (int): The minimum length of the generated transcription. Default: 1. -- `max_new_tokens` (int): The maximum number of new tokens to generate in the Markdown transcription. Default: 30. +| Parameter | Type | Description | +| --- | --- | --- | +| `task` | `str` | The task to execute | +| `img` | `str` | Path to input image if required | +| `device` | `str` | Computing device to use ('cpu' or 'gpu') | +| `device_id` | `int` | ID of specific device to use | +| `all_cores` | `bool` | Whether to use all CPU cores | +| `all_gpus` | `bool` | Whether to use all available GPUs | -## Usage +**Returns:** -To use Nougat, follow these steps: +- `str`: The final processed task. -1. Initialize the Nougat instance: +### `batch_run(self, tasks: List[str], img: Optional[List[str]] = None, batch_size: int = 10, device: str = "cpu", device_id: int = None, all_cores: bool = True, all_gpus: bool = False, *args, **kwargs)` -```python -from swarm_models import Nougat +Process multiple tasks in batches. -nougat = Nougat() -``` +| Parameter | Type | Description | +| --- | --- | --- | +| `tasks` | `List[str]` | List of tasks to process | +| `img` | `List[str]` | Optional list of images corresponding to tasks | +| `batch_size` | `int` | Number of tasks to process simultaneously | +| `device` | `str` | Computing device to use | +| `device_id` | `int` | Specific device ID if applicable | +| `all_cores` | `bool` | Whether to use all CPU cores | +| `all_gpus` | `bool` | Whether to use all available GPUs | -### Example 1 - Initialization -```python -nougat = Nougat() -``` -2. Transcribe a PDF image using Nougat: +### `concurrent_run(self, tasks: List[str], img: Optional[List[str]] = None, max_workers: Optional[int] = None, device: str = "cpu", device_id: int = None, all_cores: bool = True, all_gpus: bool = False, *args, **kwargs)` + +Process multiple tasks concurrently using ThreadPoolExecutor. -```python -markdown_transcription = nougat("path/to/pdf_file.png") -``` +| Parameter | Type | Description | +| --- | --- | --- | +| `tasks` | `List[str]` | List of tasks to process | +| `img` | `List[str]` | Optional list of images corresponding to tasks | +| `max_workers` | `int` | Maximum number of worker threads | +| `device` | `str` | Computing device to use | +| `device_id` | `int` | Specific device ID if applicable | +| `all_cores` | `bool` | Whether to use all CPU cores | +| `all_gpus` | `bool` | Whether to use all available GPUs | -### Example 2 - PDF Transcription -```python -nougat = Nougat() -markdown_transcription = nougat("path/to/pdf_file.png") -``` -3. Extract information from a PDF: +## Documentation for `rearrange` Function +====================================== -```python -information = nougat.extract_information("path/to/pdf_file.png") -``` +The `rearrange` function is a helper function that rearranges the given list of agents based on the specified flow. -### Example 3 - Information Extraction +## Parameters +---------- -```python -nougat = Nougat() -information = nougat.extract_information("path/to/pdf_file.png") -``` +| Parameter | Type | Description | +| --- | --- | --- | +| `agents` | `List[Agent]` | The list of agents to be rearranged. | +| `flow` | `str` | The flow used for rearranging the agents. | +| `task` | `str` (optional) | The task to be performed during rearrangement. Defaults to `None`. | +| `*args` | - | Additional positional arguments. | +| `**kwargs` | - | Additional keyword arguments. | + +## Returns +------- + +The result of running the agent system with the specified task. -4. Extract metadata from a PDF: +### Example +------- ```python -metadata = nougat.extract_metadata("path/to/pdf_file.png") +agents = [agent1, agent2, agent3] +flow = "agent1 -> agent2, agent3" +task = "Perform a task" +rearrange(agents, flow, task) ``` -### Example 4 - Metadata Extraction +### Example Usage +------------- + +Here's an example of how to use the `AgentRearrange` class and the `rearrange` function: ```python -nougat = Nougat() -metadata = nougat.extract_metadata("path/to/pdf_file.png") -``` +from swarms import Agent, AgentRearrange +from typing import List -## How Nougat Works +# Initialize the director agent +director = Agent( + agent_name="Accounting Director", + system_prompt="Directs the accounting tasks for the workers", + llm=Anthropic(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="accounting_director.json", +) -Nougat employs a vision encoder-decoder model, along with a dedicated processor, to transcribe PDFs into Markdown format and perform information and metadata extraction. Here's how it works: +# Initialize worker 1 +worker1 = Agent( + agent_name="Accountant 1", + system_prompt="Processes financial transactions and prepares financial statements", + llm=Anthropic(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="accountant1.json", +) -1. **Initialization**: When you create a Nougat instance, you can specify the model to use, the minimum transcription length, and the maximum number of new tokens to generate. +# Initialize worker 2 +worker2 = Agent( + agent_name="Accountant 2", + system_prompt="Performs audits and ensures compliance with financial regulations", + llm=Anthropic(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="accountant2.json", +) -2. **Processing PDFs**: Nougat can process PDFs as input. You can provide the path to a PDF document. +# Create a list of agents +agents = [director, worker1, worker2] -3. **Image Processing**: The processor converts PDF pages into images, which are then encoded by the model. +# Define the flow pattern +flow = "Accounting Director -> Accountant 1 -> Accountant 2" -4. **Transcription**: Nougat generates Markdown transcriptions of PDF content, ensuring a minimum length and respecting the token limit. +# Using AgentRearrange class +agent_system = AgentRearrange(agents=agents, flow=flow) +output = agent_system.run("Process monthly financial statements") +print(output) -5. **Information Extraction**: Information extraction involves parsing the Markdown transcription to identify key details or content of interest. +``` -6. **Metadata Extraction**: Metadata extraction involves identifying and extracting document metadata, such as title, author, and publication date. +In this example, we first initialize three agents: `director`, `worker1`, and `worker2`. Then, we create a list of these agents and define the flow pattern `"Director -> Worker1 -> Worker2"`. -## Additional Information +We can use the `AgentRearrange` class by creating an instance of it with the list of agents and the flow pattern. We then call the `run` method with the initial task, and it will execute the agents in the specified order, passing the output of one agent as the input to the next agent. -- Nougat leverages the "facebook/nougat-base" pretrained model, which is specifically designed for document transcription and extraction tasks. -- You can adjust the minimum transcription length and the maximum number of new tokens to control the output's length and quality. -- Nougat can be run on both CPU and GPU devices. +Alternatively, we can use the `rearrange` function by passing the list of agents, the flow pattern, and the initial task as arguments. -That concludes the documentation for Nougat. We hope you find this tool valuable for your PDF transcription, information extraction, and metadata extraction needs. If you have any questions or encounter any issues, please refer to the Nougat documentation for further assistance. Enjoy using Nougat! +Both the `AgentRearrange` class and the `rearrange` function will return the final output after processing the task through the agents according to the specified flow pattern. --------------------------------------------------- +## Error Handling +-------------- -# File: swarms/models/openai.md +The `AgentRearrange` class includes error handling mechanisms to validate the flow pattern. If the flow pattern is incorrectly formatted or contains duplicate agent names, a `ValueError` will be raised with an appropriate error message. -# `BaseOpenAI` and `OpenAI` Documentation +### Example: -## Table of Contents +```python +# Invalid flow pattern +invalid_flow = "Director->Worker1,Worker2->Worker3" +agent_system = AgentRearrange(agents=agents, flow=invalid_flow) +output = agent_system.run("Some task")` +``` -1. [Overview](#overview) -2. [Class Architecture](#class-architecture) -3. [Purpose](#purpose) -4. [Class Attributes](#class-attributes) -5. [Methods](#methods) - - [Construction](#construction) - - [Configuration](#configuration) - - [Tokenization](#tokenization) - - [Generation](#generation) - - [Asynchronous Generation](#asynchronous-generation) -6. [Usage Examples](#usage-examples) - - [Creating an OpenAI Object](#creating-an-openai-object) - - [Generating Text](#generating-text) - - [Advanced Configuration](#advanced-configuration) - ---- - -## 1. Overview - -The `BaseOpenAI` and `OpenAI` classes are part of the LangChain library, designed to interact with OpenAI's large language models (LLMs). These classes provide a seamless interface for utilizing OpenAI's API to generate natural language text. - -## 2. Class Architecture - -Both `BaseOpenAI` and `OpenAI` classes inherit from `BaseLLM`, demonstrating an inheritance-based architecture. This architecture allows for easy extensibility and customization while adhering to the principles of object-oriented programming. - -## 3. Purpose - -The purpose of these classes is to simplify the interaction with OpenAI's LLMs. They encapsulate API calls, handle tokenization, and provide a high-level interface for generating text. By instantiating an object of the `OpenAI` class, developers can quickly leverage the power of OpenAI's models to generate text for various applications, such as chatbots, content generation, and more. - -## 4. Class Attributes - -Here are the key attributes and their descriptions for the `BaseOpenAI` and `OpenAI` classes: - -| Attribute | Description | -|---------------------------|-------------| -| `lc_secrets` | A dictionary of secrets required for LangChain, including the OpenAI API key. | -| `lc_attributes` | A dictionary of attributes relevant to LangChain. | -| `is_lc_serializable()` | A method indicating if the class is serializable for LangChain. | -| `model_name` | The name of the language model to use. | -| `temperature` | The sampling temperature for text generation. | -| `max_tokens` | The maximum number of tokens to generate in a completion. | -| `top_p` | The total probability mass of tokens to consider at each step. | -| `frequency_penalty` | Penalizes repeated tokens according to frequency. | -| `presence_penalty` | Penalizes repeated tokens. | -| `n` | How many completions to generate for each prompt. | -| `best_of` | Generates `best_of` completions server-side and returns the "best." | -| `model_kwargs` | Holds any model parameters valid for `create` calls not explicitly specified. | -| `openai_api_key` | The OpenAI API key used for authentication. | -| `openai_api_base` | The base URL for the OpenAI API. | -| `openai_organization` | The OpenAI organization name, if applicable. | -| `openai_proxy` | An explicit proxy URL for OpenAI requests. | -| `batch_size` | The batch size to use when passing multiple documents for generation. | -| `request_timeout` | The timeout for requests to the OpenAI completion API. | -| `logit_bias` | Adjustment to the probability of specific tokens being generated. | -| `max_retries` | The maximum number of retries to make when generating. | -| `streaming` | Whether to stream the results or not. | -| `allowed_special` | A set of special tokens that are allowed. | -| `disallowed_special` | A collection of special tokens that are not allowed. | -| `tiktoken_model_name` | The model name to pass to `tiktoken` for token counting. | - -## 5. Methods +This will raise a `ValueError` with the message `"Agent 'Worker3' is not registered."`. -### 5.1 Construction - -#### 5.1.1 `__new__(cls, **data: Any) -> Union[OpenAIChat, BaseOpenAI]` -- Description: Initializes the OpenAI object. -- Arguments: - - `cls` (class): The class instance. - - `data` (dict): Additional data for initialization. -- Returns: - - Union[OpenAIChat, BaseOpenAI]: An instance of the OpenAI class. - -### 5.2 Configuration - -#### 5.2.1 `build_extra(cls, values: Dict[str, Any]) -> Dict[str, Any]` -- Description: Builds extra kwargs from additional params passed in. -- Arguments: - - `cls` (class): The class instance. - - `values` (dict): Values and parameters to build extra kwargs. -- Returns: - - Dict[str, Any]: A dictionary of built extra kwargs. - -#### 5.2.2 `validate_environment(cls, values: Dict) -> Dict` -- Description: Validates that the API key and python package exist in the environment. -- Arguments: - - `values` (dict): The class values and parameters. -- Returns: - - Dict: A dictionary of validated values. - -### 5.3 Tokenization - -#### 5.3.1 `get_sub_prompts(self, params: Dict[str, Any], prompts: List[str], stop: Optional[List[str]] = None) -> List[List[str]]` -- Description: Gets sub-prompts for LLM call. -- Arguments: - - `params` (dict): Parameters for LLM call. - - `prompts` (list): List of prompts. - - `stop` (list, optional): List of stop words. -- Returns: - - List[List[str]]: List of sub-prompts. - -#### 5.3.2 `get_token_ids(self, text: str) -> List[int]` -- Description: Gets token IDs using the `tiktoken` package. -- Arguments: - - `text` (str): The text for which to calculate token IDs. -- Returns: - - List[int]: A list of token IDs. - -#### 5.3.3 `modelname_to_contextsize(modelname: str) -> int` -- Description: Calculates the maximum number of tokens possible to generate for a model. -- Arguments: - - `modelname` (str): The model name to determine the context size for. -- Returns: - - int: The maximum context size. - -#### 5.3.4 `max_tokens_for_prompt(self, prompt: str) -> int` -- Description: Calculates the maximum number of tokens possible to generate for a prompt. -- Arguments: - - `prompt` (str): The prompt for which to - - determine the maximum token limit. -- Returns: - - int: The maximum token limit. - -### 5.4 Generation - -#### 5.4.1 `generate(self, text: Union[str, List[str]], **kwargs) -> Union[str, List[str]]` -- Description: Generates text using the OpenAI API. -- Arguments: - - `text` (str or list): The input text or list of inputs. - - `**kwargs` (dict): Additional parameters for the generation process. -- Returns: - - Union[str, List[str]]: The generated text or list of generated texts. - -### 5.5 Asynchronous Generation - -#### 5.5.1 `generate_async(self, text: Union[str, List[str]], **kwargs) -> Union[str, List[str]]` -- Description: Generates text asynchronously using the OpenAI API. -- Arguments: - - `text` (str or list): The input text or list of inputs. - - `**kwargs` (dict): Additional parameters for the asynchronous generation process. -- Returns: - - Union[str, List[str]]: The generated text or list of generated texts. - -## 6. Usage Examples - -### 6.1 Creating an OpenAI Object - -```python -# Import the OpenAI class -from swarm_models import OpenAI - -# Set your OpenAI API key -api_key = "YOUR_API_KEY" - -# Create an OpenAI object -openai = OpenAI(api_key) -``` - -### 6.2 Generating Text -```python -# Generate text from a single prompt -prompt = "Translate the following English text to French: 'Hello, how are you?'" -generated_text = openai.generate(prompt, max_tokens=50) - -# Generate text from multiple prompts -prompts = [ - "Translate this: 'Good morning' to Spanish.", - "Summarize the following article:", - article_text, -] -generated_texts = openai.generate(prompts, max_tokens=100) +## Parallel and Sequential Processing +---------------------------------- -# Generate text asynchronously -async_prompt = "Translate 'Thank you' into German." -async_result = openai.generate_async(async_prompt, max_tokens=30) +The `AgentRearrange` class supports both parallel and sequential processing of tasks based on the specified flow pattern. If the flow pattern includes multiple agents separated by commas (e.g., `"agent1, agent2"`), the agents will be executed in parallel, and their outputs will be concatenated with a semicolon (`;`). If the flow pattern includes a single agent, it will be executed sequentially. -# Access the result of an asynchronous generation -async_result_text = async_result.get() -``` -### 6.3 Advanced Configuration +### Parallel processing +`parallel_flow = "Worker1, Worker2 -> Director"` -```python -# Configure generation with advanced options -custom_options = { - "temperature": 0.7, - "max_tokens": 100, - "top_p": 0.9, - "frequency_penalty": 0.2, - "presence_penalty": 0.4, -} -generated_text = openai.generate(prompt, **custom_options) -``` +### Sequential processing +`sequential_flow = "Worker1 -> Worker2 -> Director"` -This documentation provides a comprehensive understanding of the `BaseOpenAI` and `OpenAI` classes, their attributes, methods, and usage examples. Developers can utilize these classes to interact with OpenAI's language models efficiently, enabling various natural language generation tasks. +In the `parallel_flow` example, `Worker1` and `Worker2` will be executed in parallel, and their outputs will be concatenated and passed to `Director`. In the `sequential_flow` example, `Worker1` will be executed first, and its output will be passed to `Worker2`, and then the output of `Worker2` will be passed to `Director`. --------------------------------------------------- +## Logging +------- -# File: swarms/models/openai_chat.md +The `AgentRearrange` class includes logging capabilities using the `loguru` library. If `verbose` is set to `True` during initialization, a log file named `agent_rearrange.log` will be created, and log messages will be written to it. You can use this log file to track the execution of the agents and any potential issues or errors that may occur. -# `OpenAIChat` Documentation -## Table of Contents +```bash +2023-05-08 10:30:15.456 | INFO | agent_rearrange:__init__:34 - Adding agent Director to the swarm. +2023-05-08 10:30:15.457 | INFO | agent_rearrange:__init__:34 - Adding agent Worker1 to the swarm. +2023-05-08 10:30:15.457 | INFO | agent_rearrange:__init__:34 - Adding agent Worker2 to the swarm. +2023-05-08 10:30:15.458 | INFO | agent_rearrange:run:118 - Running agents in parallel: ['Worker1', 'Worker2'] +2023-05-08 10:30:15.459 | INFO | agent_rearrange:run:121 - Running agents sequentially: ['Director']` +``` -1. [Introduction](#introduction) -2. [Class Overview](#class-overview) -3. [Class Architecture](#class-architecture) -4. [Class Attributes](#class-attributes) -5. [Methods](#methods) - - [Construction](#construction) - - [Configuration](#configuration) - - [Message Handling](#message-handling) - - [Generation](#generation) - - [Tokenization](#tokenization) -6. [Usage Examples](#usage-examples) -7. [Additional Information](#additional-information) +## Additional Parameters +--------------------- ---- +The `AgentRearrange` class also accepts additional parameters that can be passed to the `run` method using `*args` and `**kwargs`. These parameters will be forwarded to the individual agents during execution. -## 1. Introduction +`agent_system = AgentRearrange(agents=agents, flow=flow)` +`output = agent_system.run("Some task", max_tokens=200, temperature=0.7)` -The `OpenAIChat` class is part of the LangChain library and serves as an interface to interact with OpenAI's Chat large language models. This documentation provides an in-depth understanding of the class, its attributes, methods, and usage examples. - -## 2. Class Overview - -The `OpenAIChat` class is designed for conducting chat-like conversations with OpenAI's language models, such as GPT-3.5 Turbo. It allows you to create interactive conversations by sending messages and receiving model-generated responses. This class simplifies the process of integrating OpenAI's models into chatbot applications and other natural language processing tasks. +In this example, the `max_tokens` and `temperature` parameters will be passed to each agent during execution. -## 3. Class Architecture +## Customization +------------- -The `OpenAIChat` class is built on top of the `BaseLLM` class, which provides a foundation for working with large language models. This inheritance-based architecture allows for customization and extension while adhering to object-oriented programming principles. +The `AgentRearrange` class and the `rearrange` function can be customized and extended to suit specific use cases. For example, you can create custom agents by inheriting from the `Agent` class and implementing custom logic for task processing. You can then add these custom agents to the swarm and define the flow pattern accordingly. -## 4. Class Attributes +Additionally, you can modify the `run` method of the `AgentRearrange` class to implement custom logic for task processing and agent interaction. -Here are the key attributes and their descriptions for the `OpenAIChat` class: -| Attribute | Description | -|-----------------------------|-------------------------------------------------------------------------------| -| `client` | An internal client for making API calls to OpenAI. | -| `model_name` | The name of the language model to use (default: "gpt-3.5-turbo"). | -| `model_kwargs` | Additional model parameters valid for `create` calls not explicitly specified.| -| `openai_api_key` | The OpenAI API key used for authentication. | -| `openai_api_base` | The base URL for the OpenAI API. | -| `openai_proxy` | An explicit proxy URL for OpenAI requests. | -| `max_retries` | The maximum number of retries to make when generating (default: 6). | -| `prefix_messages` | A list of messages to set the initial conversation state (default: []). | -| `streaming` | Whether to stream the results or not (default: False). | -| `allowed_special` | A set of special tokens that are allowed (default: an empty set). | -| `disallowed_special` | A collection of special tokens that are not allowed (default: "all"). | +## Limitations +----------- -## 5. Methods +It's important to note that the `AgentRearrange` class and the `rearrange` function rely on the individual agents to process tasks correctly. The quality of the output will depend on the capabilities and configurations of the agents used in the swarm. Additionally, the `AgentRearrange` class does not provide any mechanisms for task prioritization or load balancing among the agents. -### 5.1 Construction +## Conclusion +---------- -#### 5.1.1 `__init__(self, model_name: str = "gpt-3.5-turbo", openai_api_key: Optional[str] = None, openai_api_base: Optional[str] = None, openai_proxy: Optional[str] = None, max_retries: int = 6, prefix_messages: List = [])` -- Description: Initializes an OpenAIChat object. -- Arguments: - - `model_name` (str): The name of the language model to use (default: "gpt-3.5-turbo"). - - `openai_api_key` (str, optional): The OpenAI API key used for authentication. - - `openai_api_base` (str, optional): The base URL for the OpenAI API. - - `openai_proxy` (str, optional): An explicit proxy URL for OpenAI requests. - - `max_retries` (int): The maximum number of retries to make when generating (default: 6). - - `prefix_messages` (List): A list of messages to set the initial conversation state (default: []). +The `AgentRearrange` class and the `rearrange` function provide a flexible and extensible framework for orchestrating swarms of agents to process tasks based on a specified flow pattern. By combining the capabilities of individual agents, you can create complex workflows and leverage the strengths of different agents to tackle various tasks efficiently. -### 5.2 Configuration +While the current implementation offers basic functionality for agent rearrangement, there is room for future improvements and customizations to enhance the system's capabilities and cater to more specific use cases. -#### 5.2.1 `build_extra(self, values: Dict[str, Any]) -> Dict[str, Any]` -- Description: Builds extra kwargs from additional parameters passed in. -- Arguments: - - `values` (dict): Values and parameters to build extra kwargs. -- Returns: - - Dict[str, Any]: A dictionary of built extra kwargs. +Whether you're working on natural language processing tasks, data analysis, or any other domain where agent-based systems can be beneficial, the `AgentRearrange` class and the `rearrange` function provide a solid foundation for building and experimenting with swarm-based solutions. -#### 5.2.2 `validate_environment(self, values: Dict) -> Dict` -- Description: Validates that the API key and Python package exist in the environment. -- Arguments: - - `values` (dict): The class values and parameters. -- Returns: - - Dict: A dictionary of validated values. +-------------------------------------------------- -### 5.3 Message Handling +# File: swarms\structs\agent_registry.md -#### 5.3.1 `_get_chat_params(self, prompts: List[str], stop: Optional[List[str]] = None) -> Tuple` -- Description: Gets chat-related parameters for generating responses. -- Arguments: - - `prompts` (list): List of user messages. - - `stop` (list, optional): List of stop words. -- Returns: - - Tuple: Messages and parameters. +# AgentRegistry Documentation -### 5.4 Generation +The `AgentRegistry` class is designed to manage a collection of agents, providing methods for adding, deleting, updating, and querying agents. This class ensures thread-safe operations on the registry, making it suitable for concurrent environments. Additionally, the `AgentModel` class is a Pydantic model used for validating and storing agent information. -#### 5.4.1 `_stream(self, prompt: str, stop: Optional[List[str]] = None, run_manager: Optional[CallbackManagerForLLMRun] = None, **kwargs: Any) -> Iterator[GenerationChunk]` -- Description: Generates text asynchronously using the OpenAI API. -- Arguments: - - `prompt` (str): The user's message. - - `stop` (list, optional): List of stop words. - - `run_manager` (optional): Callback manager for asynchronous generation. - - `**kwargs` (dict): Additional parameters for asynchronous generation. -- Returns: - - Iterator[GenerationChunk]: An iterator of generated text chunks. +## Attributes -#### 5.4.2 `_agenerate(self, prompts: List[str], stop: Optional[List[str]] = None, run_manager: Optional[AsyncCallbackManagerForLLMRun] = None, **kwargs: Any) -> LLMResult` -- Description: Generates text asynchronously using the OpenAI API (async version). -- Arguments: - - `prompts` (list): List of user messages. - - `stop` (list, optional): List of stop words. - - `run_manager` (optional): Callback manager for asynchronous generation. - - `**kwargs` (dict): Additional parameters for asynchronous generation. -- Returns: - - LLMResult: A result object containing the generated text. +### AgentModel -### 5.5 Tokenization +| Attribute | Type | Description | +|-----------|--------|--------------------------------------| +| `agent_id`| `str` | The unique identifier for the agent. | +| `agent` | `Agent`| The agent object. | -#### 5.5.1 `get_token_ids(self, text: str) -> List[int]` -- Description: Gets token IDs using the tiktoken package. -- Arguments: - - `text` (str): The text for which to calculate token IDs. -- Returns: - - List[int]: A list of +### AgentRegistry - token IDs. - -## 6. Usage Examples - -### Example 1: Initializing `OpenAIChat` +| Attribute | Type | Description | +|-----------|---------------------|-------------------------------------------| +| `agents` | `Dict[str, AgentModel]` | A dictionary mapping agent IDs to `AgentModel` instances. | +| `lock` | `Lock` | A threading lock for thread-safe operations. | -```python -from swarm_models import OpenAIChat +## Methods -# Initialize OpenAIChat with model name and API key -openai_chat = OpenAIChat(model_name="gpt-3.5-turbo", openai_api_key="YOUR_API_KEY") -``` +### `__init__(self)` -### Example 2: Sending Messages and Generating Responses +Initializes the `AgentRegistry` object. -```python -# Define a conversation -conversation = [ - "User: Tell me a joke.", - "Assistant: Why did the chicken cross the road?", - "User: I don't know. Why?", - "Assistant: To get to the other side!", -] +- **Usage Example:** + ```python + registry = AgentRegistry() + ``` -# Set the conversation as the prefix messages -openai_chat.prefix_messages = conversation +### `add(self, agent_id: str, agent: Agent) -> None` -# Generate a response -user_message = "User: Tell me another joke." -response = openai_chat.generate([user_message]) +Adds a new agent to the registry. -# Print the generated response -print( - response[0][0].text -) # Output: "Assistant: Why don't scientists trust atoms? Because they make up everything!" -``` +- **Parameters:** + - `agent_id` (`str`): The unique identifier for the agent. + - `agent` (`Agent`): The agent to add. -### Example 3: Asynchronous Generation +- **Raises:** + - `ValueError`: If the agent ID already exists in the registry. + - `ValidationError`: If the input data is invalid. -```python -import asyncio +- **Usage Example:** + ```python + agent = Agent(agent_name="Agent1") + registry.add("agent_1", agent) + ``` +### `delete(self, agent_id: str) -> None` -# Define an asynchronous function for generating responses -async def generate_responses(): - user_message = "User: Tell me a fun fact." - async for chunk in openai_chat.stream([user_message]): - print(chunk.text) +Deletes an agent from the registry. +- **Parameters:** + - `agent_id` (`str`): The unique identifier for the agent to delete. -# Run the asynchronous generation function -asyncio.run(generate_responses()) -``` +- **Raises:** + - `KeyError`: If the agent ID does not exist in the registry. -## 7. Additional Information +- **Usage Example:** + ```python + registry.delete("agent_1") + ``` -- To use the `OpenAIChat` class, you should have the `openai` Python package installed, and the environment variable `OPENAI_API_KEY` set with your API key. -- Any parameters that are valid to be passed to the `openai.create` call can be passed to the `OpenAIChat` constructor. -- You can customize the behavior of the class by setting various attributes, such as `model_name`, `openai_api_key`, `prefix_messages`, and more. -- For asynchronous generation, you can use the `_stream` and `_agenerate` methods to interactively receive model-generated text chunks. -- To calculate token IDs, you can use the `get_token_ids` method, which utilizes the `tiktoken` package. Make sure to install the `tiktoken` package with `pip install tiktoken` if needed. +### `update_agent(self, agent_id: str, new_agent: Agent) -> None` ---- +Updates an existing agent in the registry. -This documentation provides a comprehensive overview of the `OpenAIChat` class, its attributes, methods, and usage examples. You can use this class to create chatbot applications, conduct conversations with language models, and explore the capabilities of OpenAI's GPT-3.5 Turbo model. +- **Parameters:** + - `agent_id` (`str`): The unique identifier for the agent to update. + - `new_agent` (`Agent`): The new agent to replace the existing one. --------------------------------------------------- +- **Raises:** + - `KeyError`: If the agent ID does not exist in the registry. + - `ValidationError`: If the input data is invalid. -# File: swarms/models/openai_function_caller.md +- **Usage Example:** + ```python + new_agent = Agent(agent_name="UpdatedAgent") + registry.update_agent("agent_1", new_agent) + ``` -# OpenAIFunctionCaller Documentation +### `get(self, agent_id: str) -> Agent` -The `OpenAIFunctionCaller` class is designed to interface with OpenAI's chat completion API, allowing users to generate responses based on given prompts using specified models. This class encapsulates the setup and execution of API calls, including handling API keys, model parameters, and response formatting. The class extends the `BaseLLM` and utilizes OpenAI's client library to facilitate interactions. +Retrieves an agent from the registry. -## Class Definition +- **Parameters:** + - `agent_id` (`str`): The unique identifier for the agent to retrieve. -### OpenAIFunctionCaller +- **Returns:** + - `Agent`: The agent associated with the given agent ID. -A class that represents a caller for OpenAI chat completions. +- **Raises:** + - `KeyError`: If the agent ID does not exist in the registry. -### Attributes +- **Usage Example:** + ```python + agent = registry.get("agent_1") + ``` -| Attribute | Type | Description | -|----------------------|-------------------|-------------------------------------------------------------------------| -| `system_prompt` | `str` | The system prompt to be used in the chat completion. | -| `model_name` | `str` | The name of the OpenAI model to be used. | -| `max_tokens` | `int` | The maximum number of tokens in the generated completion. | -| `temperature` | `float` | The temperature parameter for randomness in the completion. | -| `base_model` | `BaseModel` | The base model to be used for the completion. | -| `parallel_tool_calls`| `bool` | Whether to make parallel tool calls. | -| `top_p` | `float` | The top-p parameter for nucleus sampling in the completion. | -| `client` | `openai.OpenAI` | The OpenAI client for making API calls. | +### `list_agents(self) -> List[str]` -### Methods +Lists all agent identifiers in the registry. -#### `check_api_key` +- **Returns:** + - `List[str]`: A list of all agent identifiers. -Checks if the API key is provided and retrieves it from the environment if not. +- **Usage Example:** + ```python + agent_ids = registry.list_agents() + ``` -| Parameter | Type | Description | -|---------------|--------|--------------------------------------| -| None | | | +### `query(self, condition: Optional[Callable[[Agent], bool]] = None) -> List[Agent]` -**Returns:** +Queries agents based on a condition. -| Type | Description | -|--------|--------------------------------------| -| `str` | The API key. | +- **Parameters:** + - `condition` (`Optional[Callable[[Agent], bool]]`): A function that takes an agent and returns a boolean indicating whether the agent meets the condition. Defaults to `None`. -#### `run` +- **Returns:** + - `List[Agent]`: A list of agents that meet the condition. -Runs the chat completion with the given task and returns the generated completion. +- **Usage Example:** + ```python + def is_active(agent): + return agent.is_active -| Parameter | Type | Description | -|-----------|----------|-----------------------------------------------------------------| -| `task` | `str` | The user's task for the chat completion. | -| `*args` | | Additional positional arguments to be passed to the OpenAI API. | -| `**kwargs`| | Additional keyword arguments to be passed to the OpenAI API. | + active_agents = registry.query(is_active) + ``` -**Returns:** +### `find_agent_by_name(self, agent_name: str) -> Agent` -| Type | Description | -|--------|-----------------------------------------------| -| `str` | The generated completion. | +Finds an agent by its name. -#### `convert_to_dict_from_base_model` +- **Parameters:** + - `agent_name` (`str`): The name of the agent to find. -Converts a `BaseModel` to a dictionary. +- **Returns:** + - `Agent`: The agent with the specified name. -| Parameter | Type | Description | -|-------------|------------|--------------------------------------| -| `base_model`| `BaseModel`| The BaseModel to be converted. | +- **Usage Example:** + ```python + agent = registry.find_agent_by_name("Agent1") + ``` -**Returns:** -| Type | Description | -|--------|--------------------------------------| -| `dict` | A dictionary representing the BaseModel.| +### Full Example -#### `convert_list_of_base_models` +```python +from swarms.structs.agent_registry import AgentRegistry +from swarms import Agent, OpenAIChat, Anthropic -Converts a list of `BaseModels` to a list of dictionaries. +# Initialize the agents +growth_agent1 = Agent( + agent_name="Marketing Specialist", + system_prompt="You're the marketing specialist, your purpose is to help companies grow by improving their marketing strategies!", + agent_description="Improve a company's marketing strategies!", + llm=OpenAIChat(), + max_loops="auto", + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + saved_state_path="marketing_specialist.json", + stopping_token="Stop!", + interactive=True, + context_length=1000, +) -| Parameter | Type | Description | -|--------------|-----------------|--------------------------------------| -| `base_models`| `List[BaseModel]`| A list of BaseModels to be converted.| +growth_agent2 = Agent( + agent_name="Sales Specialist", + system_prompt="You're the sales specialist, your purpose is to help companies grow by improving their sales strategies!", + agent_description="Improve a company's sales strategies!", + llm=Anthropic(), + max_loops="auto", + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + saved_state_path="sales_specialist.json", + stopping_token="Stop!", + interactive=True, + context_length=1000, +) -**Returns:** +growth_agent3 = Agent( + agent_name="Product Development Specialist", + system_prompt="You're the product development specialist, your purpose is to help companies grow by improving their product development strategies!", + agent_description="Improve a company's product development strategies!", + llm=Anthropic(), + max_loops="auto", + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + saved_state_path="product_development_specialist.json", + stopping_token="Stop!", + interactive=True, + context_length=1000, +) -| Type | Description | -|--------|-----------------------------------------------| -| `List[Dict]` | A list of dictionaries representing the converted BaseModels. | +growth_agent4 = Agent( + agent_name="Customer Service Specialist", + system_prompt="You're the customer service specialist, your purpose is to help companies grow by improving their customer service strategies!", + agent_description="Improve a company's customer service strategies!", + llm=OpenAIChat(), + max_loops="auto", + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + saved_state_path="customer_service_specialist.json", + stopping_token="Stop!", + interactive=True, + context_length=1000, +) -## Usage Examples -Here are three examples demonstrating different ways to use the `OpenAIFunctionCaller` class: +# Register the agents\ +registry = AgentRegistry() -### Example 1: Production-Grade Claude Artifacts +# Register the agents +registry.add("Marketing Specialist", growth_agent1) +registry.add("Sales Specialist", growth_agent2) +registry.add("Product Development Specialist", growth_agent3) +registry.add("Customer Service Specialist", growth_agent4) -```python -import openai -from swarm_models.openai_function_caller import OpenAIFunctionCaller -from swarms.artifacts.main_artifact import Artifact +``` +## Logging and Error Handling -# Pydantic is a data validation library that provides data validation and parsing using Python type hints. +Each method in the `AgentRegistry` class includes logging to track the execution flow and captures errors to provide detailed information in case of failures. This is crucial for debugging and ensuring smooth operation of the registry. The `report_error` function is used for reporting exceptions that occur during method execution. +## Additional Tips -# Example usage: -# Initialize the function caller -model = OpenAIFunctionCaller( - system_prompt="You're a helpful assistant.The time is August 6, 2024", - max_tokens=500, - temperature=0.5, - base_model=Artifact, - parallel_tool_calls=False, -) +- Ensure that agents provided to the `AgentRegistry` are properly initialized and configured to handle the tasks they will receive. +- Utilize the logging information to monitor and debug the registry operations. +- Use the `lock` attribute to ensure thread-safe operations when accessing or modifying the registry. -# The OpenAIFunctionCaller class is used to interact with the OpenAI API and make function calls. -# Here, we initialize an instance of the OpenAIFunctionCaller class with the following parameters: -# - system_prompt: A prompt that sets the context for the conversation with the API. -# - max_tokens: The maximum number of tokens to generate in the API response. -# - temperature: A parameter that controls the randomness of the generated text. -# - base_model: The base model to use for the API calls, in this case, the WeatherAPI class. -out = model.run("Create a python file with a python game code in it") -print(out) -``` -### Example 2: Prompt Generator +-------------------------------------------------- -```python -from swarm_models.openai_function_caller import OpenAIFunctionCaller -from pydantic import BaseModel, Field -from typing import Sequence +# File: swarms\structs\artifact.md +# swarms.structs Documentation -class PromptUseCase(BaseModel): - use_case_name: str = Field( - ..., - description="The name of the use case", - ) - use_case_description: str = Field( - ..., - description="The description of the use case", - ) +## Introduction +The swarms.structs library provides a collection of classes for representing artifacts and their attributes. This documentation will provide an overview of the `Artifact` class, its attributes, functionality, and usage examples. -class PromptSpec(BaseModel): - prompt_name: str = Field( - ..., - description="The name of the prompt", - ) - prompt_description: str = Field( - ..., - description="The description of the prompt", - ) - prompt: str = Field( - ..., - description="The prompt for the agent", - ) - tags: str = Field( - ..., - description="The tags for the prompt such as sentiment, code, etc seperated by commas.", - ) - use_cases: Sequence[PromptUseCase] = Field( - ..., - description="The use cases for the prompt", - ) +### Artifact Class +The `Artifact` class represents an artifact and its attributes. It inherits from the `BaseModel` class and includes the following attributes: -# Example usage: -# Initialize the function caller -model = OpenAIFunctionCaller( - system_prompt="You're an agent creator, you're purpose is to create system prompt for new LLM Agents for the user. Follow the best practices for creating a prompt such as making it direct and clear. Providing instructions and many-shot examples will help the agent understand the task better.", - max_tokens=1000, - temperature=0.5, - base_model=PromptSpec, - parallel_tool_calls=False, -) +#### Attributes +1. `artifact_id (str)`: Id of the artifact. +2. `file_name (str)`: Filename of the artifact. +3. `relative_path (str, optional)`: Relative path of the artifact in the agent's workspace. -# The OpenAIFunctionCaller class is used to interact with the OpenAI API and make function calls. -out = model.run( - "Create an prompt for generating quality rust code with instructions and examples." -) -print(out) +These attributes are crucial for identifying and managing different artifacts within a given context. -``` +## Class Definition -### Example 3: Sentiment Analysis +The `Artifact` class can be defined as follows: ```python -from swarm_models.openai_function_caller import OpenAIFunctionCaller -from pydantic import BaseModel, Field +class Artifact(BaseModel): + """ + Represents an artifact. + Attributes: + artifact_id (str): Id of the artifact. + file_name (str): Filename of the artifact. + relative_path (str, optional): Relative path of the artifact in the agent's workspace. + """ -# Pydantic is a data validation library that provides data validation and parsing using Python type hints. -# It is used here to define the data structure for making API calls to retrieve weather information. -class SentimentAnalysisCard(BaseModel): - text: str = Field( + artifact_id: str = Field( ..., - description="The text to be analyzed for sentiment rating", + description="Id of the artifact", + example="b225e278-8b4c-4f99-a696-8facf19f0e56", ) - rating: str = Field( - ..., - description="The sentiment rating of the text from 0.0 to 1.0", + file_name: str = Field( + ..., description="Filename of the artifact", example="main.py" + ) + relative_path: Optional[str] = Field( + None, + description=("Relative path of the artifact in the agent's workspace"), + example="python/code/", ) +``` +The `Artifact` class defines the mandatory and optional attributes and provides corresponding descriptions along with example values. -# The WeatherAPI class is a Pydantic BaseModel that represents the data structure -# for making API calls to retrieve weather information. It has two attributes: city and date. +## Functionality and Usage -# Example usage: -# Initialize the function caller -model = OpenAIFunctionCaller( - system_prompt="You're a sentiment Analysis Agent, you're purpose is to rate the sentiment of text", - max_tokens=100, - temperature=0.5, - base_model=SentimentAnalysisCard, - parallel_tool_calls=False, -) +The `Artifact` class encapsulates the information and attributes representing an artifact. It provides a structured and organized way to manage artifacts within a given context. +### Example 1: Creating an Artifact instance -# The OpenAIFunctionCaller class is used to interact with the OpenAI API and make function calls. -# Here, we initialize an instance of the OpenAIFunctionCaller class with the following parameters: -# - system_prompt: A prompt that sets the context for the conversation with the API. -# - max_tokens: The maximum number of tokens to generate in the API response. -# - temperature: A parameter that controls the randomness of the generated text. -# - base_model: The base model to use for the API calls, in this case, the WeatherAPI class. -out = model.run("The hotel was average, but the food was excellent.") -print(out) +To create an instance of the `Artifact` class, you can simply initialize it with the required attributes. Here's an example: -``` +```python +from swarms.structs import Artifact -## Additional Information and Tips +artifact_instance = Artifact( + artifact_id="b225e278-8b4c-4f99-a696-8facf19f0e56", + file_name="main.py", + relative_path="python/code/", +) +``` -- Ensure that your OpenAI API key is securely stored and not hard-coded into your source code. Use environment variables to manage sensitive information. -- Adjust the `temperature` and `top_p` parameters to control the randomness and diversity of the generated responses. Lower values for `temperature` will result in more deterministic outputs, while higher values will introduce more variability. -- When using `parallel_tool_calls`, ensure that the tools you are calling in parallel are thread-safe and can handle concurrent execution. +In this example, we create an instance of the `Artifact` class with the specified artifact details. -## References and Resources +### Example 2: Accessing Artifact attributes -- [OpenAI API Documentation](https://beta.openai.com/docs/) -- [Pydantic Documentation](https://pydantic-docs.helpmanual.io/) -- [Loguru Logger Documentation](https://loguru.readthedocs.io/) +You can access the attributes of the `Artifact` instance using dot notation. Here's how you can access the file name of the artifact: -By following this comprehensive guide, you can effectively utilize the `OpenAIFunctionCaller` class to generate chat completions using OpenAI's models, customize the response parameters, and handle API interactions seamlessly within your application. +```python +print(artifact_instance.file_name) +# Output: "main.py" +``` --------------------------------------------------- +### Example 3: Handling optional attributes -# File: swarms/models/openai_tts.md +If the `relative_path` attribute is not provided during artifact creation, it will default to `None`. Here's an example: -# `OpenAITTS` Documentation +```python +artifact_instance_no_path = Artifact( + artifact_id="c280s347-9b7d-3c68-m337-7abvf50j23k", file_name="script.js" +) -## Table of Contents -1. [Overview](#overview) -2. [Installation](#installation) -3. [Usage](#usage) - - [Initialization](#initialization) - - [Running TTS](#running-tts) - - [Running TTS and Saving](#running-tts-and-saving) -4. [Examples](#examples) - - [Basic Usage](#basic-usage) - - [Saving the Output](#saving-the-output) -5. [Advanced Options](#advanced-options) -6. [Troubleshooting](#troubleshooting) -7. [References](#references) +print(artifact_instance_no_path.relative_path) +# Output: None +``` -## 1. Overview +By providing default values for optional attributes, the `Artifact` class allows flexibility in defining artifact instances. -The `OpenAITTS` module is a Python library that provides an interface for converting text to speech (TTS) using the OpenAI TTS API. It allows you to generate high-quality speech from text input, making it suitable for various applications such as voice assistants, speech synthesis, and more. +### Additional Information and Tips -### Features: -- Convert text to speech using OpenAI's TTS model. -- Supports specifying the model name, voice, and other parameters. -- Option to save the generated speech to a WAV file. +The `Artifact` class represents a powerful and flexible means of handling various artifacts with different attributes. By utilizing this class, users can organize, manage, and streamline their artifacts with ease. -## 2. Installation +## References and Resources -To use the `OpenAITTS` model, you need to install the necessary dependencies. You can do this using `pip`: +For further details and references related to the swarms.structs library and the `Artifact` class, refer to the [official documentation](https://swarms.structs.docs/artifact.html). -```bash -pip install swarms requests wave -``` +This comprehensive documentation provides an in-depth understanding of the `Artifact` class, its attributes, functionality, and usage examples. By following the detailed examples and explanations, developers can effectively leverage the capabilities of the `Artifact` class within their projects. -## 3. Usage -### Initialization +-------------------------------------------------- -To use the `OpenAITTS` module, you need to initialize an instance of the `OpenAITTS` class. Here's how you can do it: +# File: swarms\structs\auto_agent_builder.md -```python -from swarm_models.openai_tts import OpenAITTS +# Agent Builder -# Initialize the OpenAITTS instance -tts = OpenAITTS( - model_name="tts-1-1106", - proxy_url="https://api.openai.com/v1/audio/speech", - openai_api_key=openai_api_key_env, - voice="onyx", -) -``` +The Agent Builder is a powerful class that automatically builds and manages swarms of AI agents. It provides a flexible and extensible framework for creating, coordinating, and executing multiple AI agents working together to accomplish complex tasks. -#### Parameters: -- `model_name` (str): The name of the TTS model to use (default is "tts-1-1106"). -- `proxy_url` (str): The URL for the OpenAI TTS API (default is "https://api.openai.com/v1/audio/speech"). -- `openai_api_key` (str): Your OpenAI API key. It can be obtained from the OpenAI website. -- `voice` (str): The voice to use for generating speech (default is "onyx"). -- `chunk_size` (int): The size of data chunks when fetching audio (default is 1024 * 1024 bytes). -- `autosave` (bool): Whether to automatically save the generated speech to a file (default is False). -- `saved_filepath` (str): The path to the file where the speech will be saved (default is "runs/tts_speech.wav"). +## Overview -### Running TTS +The Agent Builder uses a boss agent to delegate work and create new specialized agents as needed. It's designed to be production-ready with robust error handling, logging, and configuration options. -Once the `OpenAITTS` instance is initialized, you can use it to convert text to speech using the `run` method: +## Architecture -```python -# Generate speech from text -speech_data = tts.run("Hello, world!") +```mermaid +graph TD + A[Agent Builder] --> B[Configuration] + A --> C[Agent Creation] + A --> D[Task Execution] + + B --> B1[Name] + B --> B2[Description] + B --> B3[Model Settings] + + C --> C1[Agent Pool] + C --> C2[Agent Registry] + C --> C3[Agent Configuration] + + D --> D1[Task Distribution] + D --> D2[Result Collection] + D --> D3[Error Handling] + + C1 --> E[Specialized Agents] + C2 --> E + C3 --> E + + E --> F[Task Execution] + F --> G[Results] ``` -#### Parameters: -- `task` (str): The text you want to convert to speech. - -#### Returns: -- `speech_data` (bytes): The generated speech data. - -### Running TTS and Saving +## Class Structure -You can also use the `run_and_save` method to generate speech from text and save it to a file: +### AgentsBuilder Class -```python -# Generate speech from text and save it to a file -speech_data = tts.run_and_save("Hello, world!") -``` +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| name | str | "swarm-creator-01" | The name of the swarm | +| description | str | "This is a swarm that creates swarms" | A description of the swarm's purpose | +| verbose | bool | True | Whether to output detailed logs | +| max_loops | int | 1 | Maximum number of execution loops | +| model_name | str | "gpt-4o" | The model to use for agent creation | +| return_dictionary | bool | True | Whether to return results as a dictionary | +| system_prompt | str | BOSS_SYSTEM_PROMPT | The system prompt for the boss agent | -#### Parameters: -- `task` (str): The text you want to convert to speech. +### Methods -#### Returns: -- `speech_data` (bytes): The generated speech data. +| Method | Description | Parameters | Returns | +|--------|-------------|------------|---------| +| run | Run the swarm on a given task | task: str, image_url: str = None, *args, **kwargs | Tuple[List[Agent], int] | +| _create_agents | Create necessary agents for a task | task: str, *args, **kwargs | List[Agent] | +| build_agent | Build a single agent with specifications | agent_name: str, agent_description: str, agent_system_prompt: str, max_loops: int = 1, model_name: str = "gpt-4o", dynamic_temperature_enabled: bool = True, auto_generate_prompt: bool = False, role: str = "worker", max_tokens: int = 8192, temperature: float = 0.5 | Agent | -## 4. Examples +## Enterprise Use Cases -### Basic Usage +### 1. Customer Service Automation +- Create specialized agents for different aspects of customer service -Here's a basic example of how to use the `OpenAITTS` module to generate speech from text: +- Handle ticket routing, response generation, and escalation -```python -from swarm_models.openai_tts import OpenAITTS +- Maintain consistent service quality across channels -# Initialize the OpenAITTS instance -tts = OpenAITTS( - model_name="tts-1-1106", - proxy_url="https://api.openai.com/v1/audio/speech", - openai_api_key=openai_api_key_env, - voice="onyx", -) +### 2. Data Analysis Pipeline +- Build agents for data collection, cleaning, analysis, and visualization -# Generate speech from text -speech_data = tts.run("Hello, world!") -``` +- Automate complex data processing workflows -### Saving the Output +- Generate insights and reports automatically -You can save the generated speech to a WAV file using the `run_and_save` method: +### 3. Content Creation and Management +- Deploy agents for content research, writing, editing, and publishing -```python -# Generate speech from text and save it to a file -speech_data = tts.run_and_save("Hello, world!") -``` +- Maintain brand consistency across content -## 5. Advanced Options +- Automate content scheduling and distribution -The `OpenAITTS` module supports various advanced options for customizing the TTS generation process. You can specify the model name, voice, and other parameters during initialization. Additionally, you can configure the chunk size for audio data fetching and choose whether to automatically save the generated speech to a file. +### 4. Process Automation +- Create agents for workflow automation -## 6. Troubleshooting +- Handle document processing and routing -If you encounter any issues while using the `OpenAITTS` module, please make sure you have installed all the required dependencies and that your OpenAI API key is correctly configured. If you still face problems, refer to the OpenAI documentation or contact their support for assistance. +- Manage approval chains and notifications -## 7. References +### 5. Research and Development +- Build agents for literature review, experiment design, and data collection -- [OpenAI API Documentation](https://beta.openai.com/docs/) -- [Python Requests Library](https://docs.python-requests.org/en/latest/) -- [Python Wave Library](https://docs.python.org/3/library/wave.html) +- Automate research documentation and reporting -This documentation provides a comprehensive guide on how to use the `OpenAITTS` module to convert text to speech using OpenAI's TTS model. It covers initialization, basic usage, advanced options, troubleshooting, and references for further exploration. +- Facilitate collaboration between research teams --------------------------------------------------- +## Example Usage -# File: swarms/models/vilt.md +```python +from swarms import AgentsBuilder -# `Vilt` Documentation +# Initialize the agent builder +agents_builder = AgentsBuilder( + name="enterprise-automation", + description="Enterprise workflow automation swarm", + verbose=True +) -## Introduction +# Define a use-case for building agents +task = "Develop a swarm of agents to automate the generation of personalized marketing strategies based on customer data and market trends" -Welcome to the documentation for Vilt, a Vision-and-Language Transformer (ViLT) model fine-tuned on the VQAv2 dataset. Vilt is a powerful model capable of answering questions about images. This documentation will provide a comprehensive understanding of Vilt, its architecture, usage, and how it can be integrated into your projects. +# Run the swarm +agents = agents_builder.run(task) -## Overview +# Access results +print(agents) +``` -Vilt is based on the Vision-and-Language Transformer (ViLT) architecture, designed for tasks that involve understanding both text and images. It has been fine-tuned on the VQAv2 dataset, making it adept at answering questions about images. This model is particularly useful for tasks where textual and visual information needs to be combined to provide meaningful answers. +## Best Practices -## Class Definition +1. **Error Handling** + - Always implement proper error handling for agent failures + - Use retry mechanisms for transient failures + - Log all errors for debugging and monitoring -```python -class Vilt: - def __init__(self): - """ - Initialize the Vilt model. - """ -``` +2. **Resource Management** + - Monitor agent resource usage + - Implement rate limiting for API calls + - Use connection pooling for database operations -## Usage +3. **Security** + - Implement proper authentication and authorization + - Secure sensitive data and API keys + - Follow least privilege principle for agent permissions -To use the Vilt model, follow these steps: +4. **Monitoring and Logging** + - Implement comprehensive logging + - Monitor agent performance metrics + - Set up alerts for critical failures -1. Initialize the Vilt model: +5. **Scalability** + - Design for horizontal scaling + - Implement load balancing + - Use distributed systems when needed -```python -from swarm_models import Vilt +## Integration Patterns -model = Vilt() +```mermaid +graph LR + A[External System] --> B[API Gateway] + B --> C[Agent Builder] + C --> D[Agent Pool] + D --> E[Specialized Agents] + E --> F[External Services] + + subgraph "Monitoring" + G[Logs] + H[Metrics] + I[Alerts] + end + + C --> G + C --> H + C --> I ``` -2. Call the model with a text question and an image URL: +## Performance Considerations -```python -output = model( - "What is this image?", "http://images.cocodataset.org/val2017/000000039769.jpg" -) -``` +1. **Agent Pool Management** + - Implement connection pooling + - Use caching for frequently accessed data + - Optimize agent creation and destruction -### Example 1 - Image Questioning +2. **Task Distribution** + - Implement load balancing + - Use priority queues for task scheduling + - Handle task timeouts and retries -```python -model = Vilt() -output = model( - "What are the objects in this image?", - "http://images.cocodataset.org/val2017/000000039769.jpg", -) -print(output) -``` +3. **Resource Optimization** + - Monitor memory usage + - Implement garbage collection + - Use efficient data structures -### Example 2 - Image Analysis +## Troubleshooting -```python -model = Vilt() -output = model( - "Describe the scene in this image.", - "http://images.cocodataset.org/val2017/000000039769.jpg", -) -print(output) -``` +Common issues and solutions: -### Example 3 - Visual Knowledge Retrieval +1. **Agent Creation Failures** + - Check API credentials + - Verify model availability + - Review system prompts -```python -model = Vilt() -output = model( - "Tell me more about the landmark in this image.", - "http://images.cocodataset.org/val2017/000000039769.jpg", -) -print(output) -``` +2. **Performance Issues** + - Monitor resource usage + - Check network latency + - Review agent configurations -## How Vilt Works +3. **Integration Problems** + - Verify API endpoints + - Check authentication + - Review data formats -Vilt operates by combining text and image information to generate meaningful answers to questions about the provided image. Here's how it works: -1. **Initialization**: When you create a Vilt instance, it initializes the processor and the model. The processor is responsible for handling the image and text input, while the model is the fine-tuned ViLT model. +-------------------------------------------------- -2. **Processing Input**: When you call the Vilt model with a text question and an image URL, it downloads the image and processes it along with the text question. This processing step involves tokenization and encoding of the input. +# File: swarms\structs\auto_swarm.md -3. **Forward Pass**: The encoded input is then passed through the ViLT model. It calculates the logits, and the answer with the highest probability is selected. +# AutoSwarm -4. **Output**: The predicted answer is returned as the output of the model. +The `AutoSwarm` class represents a swarm of agents that can be created and managed automatically. This class leverages the `AutoSwarmRouter` to route tasks to appropriate swarms and supports custom preprocessing, routing, and postprocessing of tasks. It is designed to handle complex workflows efficiently. -## Parameters +### Key Concepts -Vilt does not require any specific parameters during initialization. It is pre-configured to work with the "dandelin/vilt-b32-finetuned-vqa" model. +- **Swarm**: A group of agents working together to complete tasks. +- **Routing**: Directing tasks to the appropriate swarm based on specific criteria. +- **Preprocessing and Postprocessing**: Customizable functions to handle tasks before and after routing. +- **Event Loop**: Managing the execution of tasks in a loop. -## Additional Information +## Attributes -- Vilt is fine-tuned on the VQAv2 dataset, making it proficient at answering questions about a wide range of images. -- You can use Vilt for various applications, including image question-answering, image analysis, and visual knowledge retrieval. +### Arguments -That concludes the documentation for Vilt. We hope you find this model useful for your vision-and-language tasks. If you have any questions or encounter any issues, please refer to the Hugging Face Transformers documentation for further assistance. Enjoy working with Vilt! +| Argument | Type | Default | Description | +|---------------------|-------------------------------|-----------|-------------| +| `name` | `Optional[str]` | `None` | The name of the swarm. | +| `description` | `Optional[str]` | `None` | The description of the swarm. | +| `verbose` | `bool` | `False` | Whether to enable verbose mode. | +| `custom_params` | `Optional[Dict[str, Any]]` | `None` | Custom parameters for the swarm. | +| `custom_preprocess` | `Optional[Callable]` | `None` | Custom preprocessing function for tasks. | +| `custom_postprocess`| `Optional[Callable]` | `None` | Custom postprocessing function for task results. | +| `custom_router` | `Optional[Callable]` | `None` | Custom routing function for tasks. | +| `max_loops` | `int` | `1` | The maximum number of loops to run the workflow. | --------------------------------------------------- +### Attributes -# File: swarms/papers.md +| Attribute | Type | Description | +|----------------------|-------------------------------|-------------| +| `name` | `Optional[str]` | The name of the swarm. | +| `description` | `Optional[str]` | The description of the swarm. | +| `verbose` | `bool` | Whether to enable verbose mode. | +| `custom_params` | `Optional[Dict[str, Any]]` | Custom parameters for the swarm. | +| `custom_preprocess` | `Optional[Callable]` | Custom preprocessing function for tasks. | +| `custom_postprocess` | `Optional[Callable]` | Custom postprocessing function for task results. | +| `custom_router` | `Optional[Callable]` | Custom routing function for tasks. | +| `max_loops` | `int` | The maximum number of loops to run the workflow. | +| `router` | `AutoSwarmRouter` | The router for managing task routing. | -# awesome-multi-agent-papers +## Methods -An awesome list of multi-agent papers that show you various swarm architectures and much more. [Get started](https://github.com/kyegomez/awesome-multi-agent-papers) +### init_logging --------------------------------------------------- +Initializes logging for the `AutoSwarm`. -# File: swarms/products.md +**Examples:** -# Swarms Products +```python +swarm = AutoSwarm(name="example_swarm", verbose=True) +swarm.init_logging() +``` -Welcome to the official documentation for **Swarms**, the first multi-agent orchestration framework enabling seamless collaboration between LLMs and other tools to automate business operations at scale. Below, you’ll find detailed descriptions of all Swarms products and services to help you get started and unlock the full potential of this groundbreaking platform. +### run +Runs the swarm simulation. +**Arguments:** -| **Name** | **Description** | **Link** | -|-----------------------|-------------------------------------------------------------------------------------------------------------------|---------------------------| -| **Swarms Marketplace** | A platform to discover, share, and integrate prompts, agents, and tools. | [swarms.world](https://swarms.world) | -| **Swarms Spreadsheet** | A tool for managing and scaling thousands of agent outputs, with results saved to a CSV file for easy analysis. | [swarms.world](https://swarms.world) | -| **Drag n Drop Swarm** | An intuitive interface to visually create and manage swarms of agents through drag-and-drop functionality. | [swarms.world](https://swarms.world) | -| **Swarms API** | An API enabling seamless integration of swarms of agents into your applications and workflows. | [swarms.world](https://swarms.world) | -| **Wallet API** | A secure API for managing transactions and interactions within the Swarms ecosystem. | Coming Soon | -| **Swarm Exchange** | A marketplace for buying and selling prompts, agents, and tools within the Swarms ecosystem. | Coming Soon | +| Parameter | Type | Default | Description | +|-----------|---------|---------|-------------| +| `task` | `str` | `None` | The task to be executed. | +| `*args` | | | Additional arguments. | +| `**kwargs`| | | Additional keyword arguments. | +**Returns:** +| Return Type | Description | +|-------------|-------------| +| `Any` | The result of the executed task. | ---- +**Raises:** -## Swarms Marketplace -**Website:** [swarms.world](https://swarms.world) +- `Exception`: If any error occurs during task execution. -The Swarms Marketplace is your one-stop destination for discovering, adding, and managing: +**Examples:** -- **Prompts:** Access and share production-ready prompts for LLMs. +```python +swarm = AutoSwarm(name="example_swarm", max_loops=3) +result = swarm.run(task="example_task") +print(result) +``` -- **Agents:** Browse pre-built agents tailored for tasks in marketing, finance, -programming, and more. -- **Tools:** Discover cutting-edge tools to enhance agent performance and expand -capabilities. +### list_all_swarms -### Key Features: -- **Rating System:** Evaluate and rate prompts, agents, and tools based on their -effectiveness. -- **Commenting System:** Share feedback and insights with the Swarms community. +Lists all available swarms and their descriptions. -- **Coming Soon:** Buy and sell prompts, agents, and tools directly within the -marketplace. +**Examples:** -### How to Use: -1. Sign up at [swarms.world](https://swarms.world). -2. Explore the marketplace categories or search for specific solutions. -3. Add your chosen resources to your Swarms account and integrate them into your operations. +```python +swarm = AutoSwarm(name="example_swarm", max_loops=3) +swarm.list_all_swarms() +# Output: +# INFO: Swarm Name: swarm1 || Swarm Description: Description of swarm1 +# INFO: Swarm Name: swarm2 || Swarm Description: Description of swarm2 +``` ---- +### Additional Examples -## Swarms Spreadsheet -**Website:** [swarms.world](https://swarms.world) +#### Example 1: Custom Preprocessing and Postprocessing -The Swarms Spreadsheet is a powerful tool for managing outputs from thousands of agents efficiently. Ideal for businesses needing scalable solutions, it provides: +```python +def custom_preprocess(task, *args, **kwargs): + # Custom preprocessing logic + task = task.upper() + return task, args, kwargs -### Key Features: -- **Batch Task Execution:** Assign tasks to multiple agents simultaneously. +def custom_postprocess(result): + # Custom postprocessing logic + return result.lower() -- **CSV Integration:** Automatically save agent outputs to CSV files for easy analysis. +swarm = AutoSwarm( + name="example_swarm", + custom_preprocess=custom_preprocess, + custom_postprocess=custom_postprocess, + max_loops=3 +) -- **Customizable Agents:** Upload single or multiple agents and run repeat tasks with -ease. -- **Metadata Capture:** Leverage built-in Pydantic schemas to record all task details -and results. +# Running a task with custom preprocessing and postprocessing +result = swarm.run(task="example_task") +print(result) # Output will be the processed result +``` -### Use Cases: -- **Marketing:** Generate and analyze campaign ideas at scale. +#### Example 2: Custom Router Function -- **Finance:** Process financial models and scenarios quickly. +```python +def custom_router(swarm, task, *args, **kwargs): + # Custom routing logic + if "specific" in task: + return swarm.router.swarm_dict["specific_swarm"].run(task, *args, **kwargs) + return swarm.router.swarm_dict["default_swarm"].run(task, *args, **kwargs) -- **Operations:** Automate repetitive tasks across multiple domains. +swarm = AutoSwarm( + name="example_swarm", + custom_router=custom_router, + max_loops=3 +) +# Running a task with custom routing +result = swarm.run(task="specific_task") +print(result) # Output will be the result of the routed task +``` -### How to Use: -1. Visit [swarms.world](https://swarms.world) and navigate to Swarms Spreadsheet. -2. Upload your agents or create new ones. -3. Run tasks and export results to a CSV file for further use. +#### Example 3: Verbose Mode ---- +```python +swarm = AutoSwarm( + name="example_swarm", + verbose=True, + max_loops=3 +) -## Drag-n-Drop Swarm -**Website:** [swarms.world](https://swarms.world) +# Running a task with verbose mode enabled +result = swarm.run(task="example_task") +# Output will include detailed logs of the task execution process +``` -The Drag-n-Drop Swarm enables non-technical users to create and deploy agent workflows with a simple drag-and-drop interface. It’s perfect for: -### Key Features: -- **Visual Workflow Builder:** Design agent interactions without writing code. +#### Full Example 4: +First create a class with BaseSwarm -> Then wrap it in the router -> then pass that to the `AutoSwarm` -- **Pre-Built Templates:** Start quickly with ready-made workflows for common tasks. +```python +from swarms import BaseSwarm, AutoSwarmRouter, AutoSwarm -- **Intuitive Interface:** Drag, drop, and connect agents to create robust automation -pipelines. -### How to Use: -1. Access the Drag-n-Drop Swarm tool at [swarms.world](https://swarms.world). -2. Drag agents from the library into the workspace. -3. Connect and configure agents to execute your desired workflow. -4. Save and deploy your workflow instantly. +class FinancialReportSummarization(BaseSwarm): + def __init__(self, name: str = None, *args, **kwargs): + super().__init__() ---- + def run(self, task, *args, **kwargs): + return task -## Swarms API -**Website:** [swarms.world](https://swarms.world) -The Swarms API provides developers with the ability to: +# Add swarm to router +router = AutoSwarmRouter(swarms=[FinancialReportSummarization]) -### Key Features: -- **Agent Management:** Programmatically create, update, and delete agents. +# Create AutoSwarm Instance +autoswarm = AutoSwarm( + name="kyegomez/FinancialReportSummarization", + description="A swarm for financial document summarizing and generation", + verbose=True, + router=router, +) -- **Task Orchestration:** Dynamically assign tasks to agents and monitor their progress. +# Run the AutoSwarm +autoswarm.run("Analyze these documents and give me a summary:") +``` -- **Custom Integration:** Seamlessly integrate Swarms functionality into existing -applications and workflows. +## Summary -### Getting Started: -1. Sign up for API access at [swarms.world](https://swarms.world). -2. Obtain your API key and authentication credentials. -3. Refer to the API documentation for endpoint details and usage examples. +The `AutoSwarm` class provides a robust framework for managing and executing tasks using a swarm of agents. With customizable preprocessing, routing, and postprocessing functions, it is highly adaptable to various workflows and can handle complex task execution scenarios efficiently. The integration with `AutoSwarmRouter` enhances its flexibility, making it a powerful tool for dynamic task management. ---- +-------------------------------------------------- -## Wallet API -The Wallet API enables secure and efficient transactions within the Swarms ecosystem, allowing users to: +# File: swarms\structs\auto_swarm_builder.md -### Key Features: -- **Seamless Transactions:** Manage payments for prompts, agents, and tools. +# AutoSwarmBuilder Documentation -- **Secure Wallets:** Store and transfer funds safely within the Swarms platform. +The `AutoSwarmBuilder` is a powerful class that automatically builds and manages swarms of AI agents to accomplish complex tasks. It uses a boss agent to delegate work and create specialized agents as needed. -- **Transaction History:** Access detailed logs of all wallet activity. +## Overview +The AutoSwarmBuilder is designed to: -### Getting Started: -1. Enable your wallet in your Swarms account settings. -2. Use the Wallet API to handle purchases and manage funds. +- Automatically create and coordinate multiple AI agents ---- +- Delegate tasks to specialized agents -## Swarm Exchange (Coming Soon) -The **Swarm Exchange** will revolutionize the way agents and tools are traded in the Swarms ecosystem. It will feature: +- Manage communication between agents -### Key Features: -- **Decentralized Marketplace:** Trade agents and tools securely. +- Handle complex workflows through a swarm router -- **Dynamic Pricing:** Leverage demand-based pricing for assets. -- **Global Access:** Participate in the exchange from anywhere. +## Parameters +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| name | str | None | The name of the swarm | +| description | str | None | A description of the swarm's purpose | +| verbose | bool | True | Whether to output detailed logs | +| max_loops | int | 1 | Maximum number of execution loops | +| random_models | bool | True | Whether to use random models for agents | -Stay tuned for updates on the Swarm Exchange launch. +## Core Methods ---- +### run(task: str, *args, **kwargs) -## Additional Resources -- **GitHub Repository:** [Swarms Framework](https://github.com/kyegomez/swarms) +Executes the swarm on a given task. -- **Documentation:** [Swarms Documentation](https://docs.swarms.world) +**Parameters:** -- **Support:** Contact us via our [Discord Community](https://discord.gg/jM3Z6M9uMq). +- `task` (str): The task to execute ---- +- `*args`: Additional positional arguments -Experience the future of multi-agent collaboration with Swarms. Start building your agentic workflows today! +- `**kwargs`: Additional keyword arguments +**Returns:** +- The result of the swarm execution --------------------------------------------------- +### create_agents(task: str) -# File: swarms/prompts/8020.md +Creates specialized agents for a given task. +**Parameters:** +- `task` (str): The task to create agents for --------------------------------------------------- +**Returns:** -# File: swarms/prompts/essence.md +- List[Agent]: List of created agents -# **The Essence of Enterprise-Grade Prompting** +### build_agent(agent_name: str, agent_description: str, agent_system_prompt: str) +Builds a single agent with specified parameters. -Large Language Models (LLMs) like GPT-4 have revolutionized the landscape of AI-driven automation, customer support, marketing, and more. However, extracting the highest quality output from these models requires a thoughtful approach to crafting prompts—an endeavor that goes beyond mere trial and error. In enterprise settings, where consistency, quality, and performance are paramount, enterprise-grade prompting has emerged as a structured discipline, combining art with the science of human-machine communication. +**Parameters:** +- `agent_name` (str): Name of the agent -Enterprise-grade prompting involves understanding the intricate dynamics between language models, context, and the task at hand. It requires knowledge of not only the technical capabilities of LLMs but also the intricacies of how they interpret human language. Effective prompting becomes the linchpin for ensuring that AI-driven outputs are accurate, reliable, and aligned with business needs. It is this discipline that turns raw AI capabilities into tangible enterprise value. +- `agent_description` (str): Description of the agent -In this essay, we will dissect the essence of enterprise-grade prompting, explore the most effective prompting strategies, explain what works and what doesn't, and conclude with the current holy grail of automated prompt engineering. We will also share concrete examples and illustrations of each technique, with a particular focus on their application in an enterprise setting. +- `agent_system_prompt` (str): System prompt for the agent -## **1. Foundational Principles of Prompting** -The effectiveness of prompting lies in understanding both the capabilities and limitations of LLMs. A well-structured prompt helps LLMs focus on the most relevant information while avoiding ambiguities that can lead to unreliable results. In enterprise-grade contexts, prompts must be designed with the end-user's expectations in mind, ensuring quality, safety, scalability, and traceability. +**Returns:** -- **Clarity**: Prompts should be clear and devoid of unnecessary jargon. Ambiguity can misguide the model, leading to poor-quality output. For enterprise use, clarity means avoiding misunderstandings that could affect customer relationships or lead to non-compliance with regulations. -- **Context**: Providing sufficient context ensures the model understands the nuances of the prompt. For example, specifying whether a response is aimed at a technical audience versus a general audience can lead to more accurate outputs. Context is essential in creating responses that are not only accurate but also relevant to the target audience. -- **Instruction Granularity**: The level of detail in the instruction significantly impacts the quality of the output. Broad instructions might lead to vagueness, whereas overly detailed instructions could overwhelm the model. Finding the right balance is key to generating useful responses. +- Agent: The constructed agent -Example: Instead of prompting "Explain what a blockchain is," an enterprise-grade prompt might be "Explain the concept of blockchain, focusing on how distributed ledgers help increase transparency in supply chain management. Keep the explanation under 200 words for a general audience." This prompt provides clear, relevant, and concise instructions tailored to specific needs. +### batch_run(tasks: List[str]) -## **2. Best Prompting Strategies** +Executes the swarm on multiple tasks. -The field of enterprise-grade prompting employs numerous strategies to maximize the quality of LLM output. Here are some of the most effective ones: +**Parameters:** -### **2.1. Instruction-Based Prompting** +- `tasks` (List[str]): List of tasks to execute -Instruction-based prompting provides explicit instructions for the LLM to follow. This approach is valuable in enterprise applications where responses must adhere to a specific tone, structure, or depth of analysis. +**Returns:** -**Example**: +- List[Any]: Results from each task execution -- "Summarize the following press release in 3 bullet points suitable for a marketing team meeting." +## Examples -This prompt is highly effective because it instructs the model on what format (bullet points), audience (marketing team), and depth (summary) to produce, minimizing the risk of irrelevant details. +### Example 1: Content Creation Swarm -**Why It Works**: LLMs excel when they have a clear set of rules to follow. Enterprises benefit from this structured approach, as it ensures consistency across multiple use cases, be it marketing, HR, or customer service. Clear instructions also make it easier to validate outputs against defined expectations, which is crucial for maintaining quality. +```python +from swarms.structs.auto_swarm_builder import AutoSwarmBuilder -### **2.2. Multi-Shot Prompting** +# Initialize the swarm builder +swarm = AutoSwarmBuilder( + name="Content Creation Swarm", + description="A swarm specialized in creating high-quality content" +) -Multi-shot prompting provides several examples before asking the model to complete a task. This helps set expectations by showing the model the desired style and type of output. +# Run the swarm on a content creation task +result = swarm.run( + "Create a comprehensive blog post about artificial intelligence in healthcare, " + "including current applications, future trends, and ethical considerations." +) +``` -**Example**: +### Example 2: Data Analysis Swarm -- "Here are some example customer support responses: - 1. Customer: 'I can't access my account.' - Response: 'We're sorry you're having trouble accessing your account. Please try resetting your password using the link provided.' - 2. Customer: 'I received a damaged item.' - Response: 'We apologize for the damaged item. Please provide us with your order number so we can send a replacement.' +```python +from swarms.structs.auto_swarm_builder import AutoSwarmBuilder -- Customer: 'The app keeps crashing on my phone.' - Response:" +# Initialize the swarm builder +swarm = AutoSwarmBuilder( + name="Data Analysis Swarm", + description="A swarm specialized in data analysis and visualization" +) -**Why It Works**: Multi-shot prompting is highly effective in enterprise-grade applications where consistency is critical. Showing multiple examples helps the model learn patterns without needing extensive fine-tuning, saving both time and cost. Enterprises can leverage this technique to ensure that responses remain aligned with brand standards and customer expectations across different departments. +# Run the swarm on a data analysis task +result = swarm.run( + "Analyze the provided sales data and create a detailed report with visualizations " + "showing trends, patterns, and recommendations for improvement." +) +``` -### **2.3. Chain of Thought Prompting** +### Example 3: Batch Processing Multiple Tasks -Chain of Thought (CoT) prompting helps LLMs generate reasoning steps explicitly before arriving at an answer. This method is useful for complex problem-solving tasks or when transparency in decision-making is important. +```python +from swarms.structs.auto_swarm_builder import AutoSwarmBuilder -**Example**: +# Initialize the swarm builder +swarm = AutoSwarmBuilder( + name="Multi-Task Swarm", + description="A swarm capable of handling multiple diverse tasks" +) -- "A logistics company wants to minimize fuel costs across multiple delivery routes. Here are the conditions: Each truck has a fuel capacity of 100 gallons, and the price of fuel fluctuates per state. Think through the most cost-effective approach for planning delivery, step by step." +# Define multiple tasks +tasks = [ + "Create a marketing strategy for a new product launch", + "Analyze customer feedback and generate improvement suggestions", + "Develop a project timeline for the next quarter" +] -**Why It Works**: CoT prompting allows the model to work through the process iteratively, providing more explainable results. In enterprise applications where complex decision-making is involved, this strategy ensures stakeholders understand why a particular output was generated. This transparency is crucial in high-stakes areas like finance, healthcare, and logistics, where understanding the reasoning behind an output is as important as the output itself. +# Run the swarm on all tasks +results = swarm.batch_run(tasks) +``` -### **2.4. Iterative Feedback and Adaptive Prompting** +## Best Practices -Iterative prompting involves providing multiple prompts or rounds of feedback to refine the output. Adaptive prompts take prior responses and adjust based on context, ensuring the final output meets the required standard. +!!! tip "Task Definition" + - Provide clear, specific task descriptions + + - Include any relevant context or constraints + + - Specify expected output format if needed -**Example**: +!!! note "Configuration" + + - Set appropriate `max_loops` based on task complexity + + - Use `verbose=True` during development for debugging + + - Consider using `random_models=True` for diverse agent capabilities -- First Prompt: "Generate a mission statement for our AI-driven logistics company." - - Model Response: "We use artificial intelligence to enhance logistics." - - Follow-up Prompt: "Can you make the statement more specific by mentioning how AI improves efficiency and sustainability?" +!!! warning "Error Handling" + - The class includes comprehensive error handling + + - All methods include try-catch blocks with detailed logging + + - Errors are propagated with full stack traces for debugging -**Why It Works**: Enterprises require output that is precise and tailored to brand identity. Iterative feedback provides an effective means to adjust and refine outputs until the desired quality is achieved. By breaking down the task into multiple feedback loops, enterprises can ensure the final output is aligned with their core values and objectives. +## Notes -### **2.5. Contextual Expansion for Enhanced Relevance** +!!! info "Architecture" + + - The AutoSwarmBuilder uses a sophisticated boss agent system to coordinate tasks + + - Agents are created dynamically based on task requirements + + - The system includes built-in logging and error handling + + - Results are returned in a structured format for easy processing -A lesser-known but powerful strategy is contextual expansion. This involves expanding the prompt to include broader information about the context, thereby allowing the model to generate richer, more relevant responses. -**Example**: +-------------------------------------------------- -- Original Prompt: "Write a response to a customer asking for a refund." - - Contextually Expanded Prompt: "Write a response to a customer asking for a refund on a recently purchased product. The customer expressed dissatisfaction with the quality and mentioned they want the process to be quick. Ensure the response is empathetic and explains the refund process clearly, while also offering alternative solutions like an exchange if possible." +# File: swarms\structs\auto_swarm_router.md -**Why It Works**: By including more context, the prompt allows the model to generate a response that feels more tailored to the customer's situation, enhancing both satisfaction and trust. Enterprises benefit from this approach by increasing the quality of customer service interactions. +# AutoSwarmRouter -## **3. What Doesn't Work in Prompting** +The `AutoSwarmRouter` class is designed to route tasks to the appropriate swarm based on the provided name. This class allows for customization of preprocessing, routing, and postprocessing of tasks, making it highly adaptable to various workflows and requirements. -While the above methods are effective, prompting can often fall short in certain scenarios: +### Key Concepts -### **3.1. Overly Vague Prompts** +- **Routing**: Directing tasks to the appropriate swarm based on specific criteria. +- **Preprocessing and Postprocessing**: Customizable functions to handle tasks before and after routing. +- **Swarms**: Collections of `BaseSwarm` objects that perform the tasks. -An insufficiently detailed prompt results in vague outputs. For example, simply asking "What are some strategies to grow a business?" can lead to generic responses that lack actionable insight. Vague prompts are particularly problematic in enterprise settings where specificity is crucial to drive action. +## Attributes -### **3.2. Excessive Length** +### Arguments -Overloading a prompt with details often causes the LLM to become confused, producing incomplete or inaccurate responses. For example, "Explain blockchain, focusing on cryptographic methods, network nodes, ledger distribution, proof of work, mining processes, hash functions, transaction validation, etc." attempts to include too many subjects for a concise response. Enterprise-grade prompts should focus on a specific area to avoid overwhelming the model and degrading the output quality. +| Argument | Type | Default | Description | +|--------------------|----------------------------------|-----------|-------------| +| `name` | `Optional[str]` | `None` | The name of the router. | +| `description` | `Optional[str]` | `None` | The description of the router. | +| `verbose` | `bool` | `False` | Whether to enable verbose mode. | +| `custom_params` | `Optional[Dict[str, Any]]` | `None` | Custom parameters for the router. | +| `swarms` | `Sequence[BaseSwarm]` | `None` | A list of `BaseSwarm` objects. | +| `custom_preprocess`| `Optional[Callable]` | `None` | Custom preprocessing function for tasks. | +| `custom_postprocess`| `Optional[Callable]` | `None` | Custom postprocessing function for task results. | +| `custom_router` | `Optional[Callable]` | `None` | Custom routing function for tasks. | -### **3.3. Ambiguity in Expected Output** +### Attributes -Ambiguity arises when prompts don't clearly specify the desired output format, tone, or length. For example, asking "Describe our new product" without specifying whether it should be a single-line summary, a paragraph, or a technical overview can lead to an unpredictable response. Enterprises must clearly define expectations to ensure consistent and high-quality outputs. +| Attribute | Type | Description | +|----------------------|----------------------------------|-------------| +| `name` | `Optional[str]` | The name of the router. | +| `description` | `Optional[str]` | The description of the router. | +| `verbose` | `bool` | Whether to enable verbose mode. | +| `custom_params` | `Optional[Dict[str, Any]]` | Custom parameters for the router. | +| `swarms` | `Sequence[BaseSwarm]` | A list of `BaseSwarm` objects. | +| `custom_preprocess` | `Optional[Callable]` | Custom preprocessing function for tasks. | +| `custom_postprocess` | `Optional[Callable]` | Custom postprocessing function for task results. | +| `custom_router` | `Optional[Callable]` | Custom routing function for tasks. | +| `swarm_dict` | `Dict[str, BaseSwarm]` | A dictionary of swarms keyed by their name. | -## **4. The Holy Grail: Automated Prompt Engineering** +## Methods -In an enterprise setting, scaling prompt engineering for consistency and high performance remains a key challenge. Automated Prompt Engineering (APE) offers a potential solution for bridging the gap between individual craftsmanship and enterprise-wide implementation. +### run -**4.1. AI-Augmented Prompt Design** +Executes the swarm simulation and routes the task to the appropriate swarm. -Automated Prompt Engineering tools can evaluate the outputs generated by various prompts, selecting the one with the highest quality metrics. These tools can be trained to understand what constitutes an ideal response for specific enterprise contexts. +**Arguments:** -**Example**: +| Parameter | Type | Default | Description | +|-----------|---------|---------|-------------| +| `task` | `str` | `None` | The task to be executed. | +| `*args` | | | Additional arguments. | +| `**kwargs`| | | Additional keyword arguments. | -- An APE system takes multiple variations of a prompt for generating email responses to customer complaints. After evaluating the sentiment, tone, and accuracy of each response, it selects the prompt that yields the most favorable output for business goals. +**Returns:** -**Why It Works**: AI-Augmented Prompt Design reduces the need for manual intervention and standardizes the quality of responses across the organization. This approach helps enterprises maintain consistency while saving valuable time that would otherwise be spent on trial-and-error prompting. +| Return Type | Description | +|-------------|-------------| +| `Any` | The result of the routed task. | -**4.2. Reinforcement Learning for Prompts (RLP)** +**Raises:** -Using Reinforcement Learning for Prompts involves training models to automatically iterate on prompts to improve the quality of the final output. The model is rewarded for generating responses that align with predefined criteria, such as clarity, completeness, or relevance. +- `ValueError`: If the specified swarm is not found. +- `Exception`: If any error occurs during task routing or execution. -**Example**: +**Examples:** -- An enterprise uses RLP to refine prompts used in internal compliance checks. The model iteratively generates summaries of compliance reports, refining the prompt until it consistently generates clear, concise, and accurate summaries aligned with internal guidelines. +```python +router = AutoSwarmRouter(name="example_router", swarms=[swarm1, swarm2]) -**Why It Works**: RLP can significantly improve the quality of complex outputs over time. Enterprises that require a high level of precision, such as in legal or compliance-related applications, benefit from RLP by ensuring outputs meet stringent standards. +# Running a task +result = router.run(task="example_task") +``` -**4.3. Dynamic Contextual Adaptation** +### len_of_swarms -Another aspect of automated prompt engineering involves adapting prompts in real time based on user context. For example, if a user interacting with a customer support bot seems frustrated (as detected by sentiment analysis), an adaptive prompt may be used to generate a more empathetic response. +Prints the number of swarms available in the router. -**Example**: +**Examples:** -- User: "I'm really annoyed that my order hasn't arrived yet." - - Prompt (adapted): "I'm truly sorry for the inconvenience you're experiencing. Please let me help you resolve this as quickly as possible. Could you provide your order number so I can check its status right away?" +```python +router = AutoSwarmRouter(name="example_router", swarms=[swarm1, swarm2]) -**Why It Works**: In dynamic enterprise environments, where every user experience matters, adapting prompts to the immediate context can significantly improve customer satisfaction. Real-time adaptation allows the model to be more responsive and attuned to customer needs, thereby fostering loyalty and trust. +# Printing the number of swarms +router.len_of_swarms() # Output: 2 +``` -**4.4. Collaborative Prompt Refinement** +### list_available_swarms -Automated prompt engineering can also involve collaboration between AI models and human experts. Collaborative Prompt Refinement (CPR) allows human operators to provide iterative guidance, which the model then uses to enhance its understanding and improve future outputs. +Logs the available swarms and their descriptions. -**Example**: +**Examples:** -- A financial analyst uses a prompt to generate an investment report. The model provides an initial draft, and the analyst refines it with comments. The model learns from these comments and applies similar refinements to future reports, reducing the analyst’s workload over time. +```python +router = AutoSwarmRouter(name="example_router", swarms=[swarm1, swarm2]) -**Why It Works**: CPR bridges the gap between human expertise and machine efficiency, ensuring that outputs are not only technically accurate but also aligned with expert expectations. This iterative learning loop enhances the model’s ability to autonomously generate high-quality content. +# Listing available swarms +router.list_available_swarms() +# Output: +# INFO: Swarm Name: swarm1 || Swarm Description: Description of swarm1 +# INFO: Swarm Name: swarm2 || Swarm Description: Description of swarm2 +``` -## **5. The Future of Enterprise-Grade Prompting** +### Additional Examples -The future of enterprise-grade prompting is in leveraging automation, context-awareness, and reinforcement learning. By moving from static prompts to dynamic, learning-enabled systems, enterprises can ensure consistent and optimized communication across their AI systems. +#### Example 1: Custom Preprocessing and Postprocessing -Automated systems such as APE and RLP are in their early stages, but they represent the potential to deliver highly scalable prompting solutions that automatically evolve based on user feedback and performance metrics. As more sophisticated models and methods become available, enterprise-grade prompting will likely involve: +```python +def custom_preprocess(task, *args, **kwargs): + # Custom preprocessing logic + task = task.upper() + return task, args, kwargs -- **Fully Adaptive Models**: Models that can detect and adjust to the tone, intent, and needs of users in real time. This means less manual intervention and greater responsiveness to user context. -- **Cross-Domain Learning**: Prompting systems that leverage insights across multiple domains to improve response quality. For example, lessons learned from customer service prompts could be applied to internal HR prompts to enhance employee communications. -- **Human-in-the-Loop Systems**: Combining automated prompt generation with human validation to ensure compliance, accuracy, and brand consistency. Human-in-the-loop systems allow enterprises to leverage the efficiency of automation while maintaining a high level of quality control. +def custom_postprocess(result): + # Custom postprocessing logic + return result.lower() -The rise of self-improving prompting systems marks a significant shift in how enterprises leverage AI for communication and decision-making. As more sophisticated models emerge, we anticipate a greater emphasis on adaptability, real-time learning, and seamless integration with existing business processes. +router = AutoSwarmRouter( + name="example_router", + swarms=[swarm1, swarm2], + custom_preprocess=custom_preprocess, + custom_postprocess=custom_postprocess +) -**Conclusion** +# Running a task with custom preprocessing and postprocessing +result = router.run(task="example_task") +print(result) # Output will be the processed result +``` -Enterprise-grade prompting transcends the art of crafting effective prompts into a well-defined process, merging structure with creativity and guided refinement. By understanding the foundational principles, leveraging strategies like instruction-based and chain-of-thought prompting, and adopting automation, enterprises can consistently extract high-quality results from LLMs. +#### Example 2: Custom Router Function -The evolution towards automated prompt engineering is transforming enterprise AI use from reactive problem-solving to proactive, intelligent decision-making. As the enterprise AI ecosystem matures, prompting will continue to be the linchpin that aligns the capabilities of LLMs with real-world business needs, ensuring optimal outcomes at scale. +```python +def custom_router(router, task, *args, **kwargs): + # Custom routing logic + if "specific" in task: + return router.swarm_dict["specific_swarm"].run(task, *args, **kwargs) + return router.swarm_dict["default_swarm"].run(task, *args, **kwargs) -Whether it's customer support, compliance, marketing, or operational analytics, the strategies outlined in this essay—paired with advancements in automated prompt engineering—hold the key to effective, scalable, and enterprise-grade utilization of AI models. Enterprises that invest in these methodologies today are likely to maintain a competitive edge in an increasingly automated business landscape. +router = AutoSwarmRouter( + name="example_router", + swarms=[default_swarm, specific_swarm], + custom_router=custom_router +) -**Next Steps** +# Running a task with custom routing +result = router.run(task="specific_task") +print(result) # Output will be the result of the routed task +``` -This essay is a stepping stone towards understanding enterprise-grade prompting. We encourage AI teams to start experimenting with these prompting techniques in sandbox environments, identify what works best for their needs, and gradually iterate. Automation is the future, and investing in automated prompt engineering today will yield highly optimized, scalable solutions that consistently deliver value. +#### Example 3: Verbose Mode -Ready to take the next step? Let’s explore how to design adaptive prompting frameworks tailored to your enterprise’s unique requirements. +```python +router = AutoSwarmRouter( + name="example_router", + swarms=[swarm1, swarm2], + verbose=True +) --------------------------------------------------- +# Running a task with verbose mode enabled +result = router.run(task="example_task") +# Output will include detailed logs of the task routing and execution process +``` -# File: swarms/prompts/main.md +## Summary -# Managing Prompts in Production +The `AutoSwarmRouter` class provides a flexible and customizable approach to routing tasks to appropriate swarms, supporting custom preprocessing, routing, and postprocessing functions. This makes it a powerful tool for managing complex workflows that require dynamic task handling and execution. -The `Prompt` class provides a comprehensive solution for managing prompts, including advanced features like version control, autosaving, and logging. This guide will walk you through how to effectively use this class in a production environment, focusing on its core features, use cases, and best practices. +-------------------------------------------------- -## Table of Contents +# File: swarms\structs\basestructure.md -1. **Getting Started** - - Installation and Setup - - Creating a New Prompt -2. **Managing Prompt Content** - - Editing Prompts - - Retrieving Prompt Content -3. **Version Control** - - Tracking Edits and History - - Rolling Back to Previous Versions -4. **Autosaving Prompts** - - Enabling and Configuring Autosave - - Manually Triggering Autosave -5. **Logging and Telemetry** -6. **Handling Errors** -7. **Extending the Prompt Class** - - Customizing the Save Mechanism - - Integrating with Databases +# Module/Function Name: BaseStructure ---- +## Introduction: -## 1. Getting Started +The `BaseStructure` module contains the basic structure and attributes required for running machine learning models and associated metadata, error logging, artifact saving/loading, and relevant event logging. -### Installation and Setup +The module provides the flexibility to save and load the model metadata, log errors, save artifacts, and maintain a log for multiple events associated with multiple threads and batched operations. The key attributes of the module include **name**, **description**, **save_metadata_path**, and **save_error_path**. -Before diving into how to use the `Prompt` class, ensure that you have the required dependencies installed: +## Class Definition: -```bash -pip3 install -U swarms -``` +### Arguments: +| Argument | Type | Description | +|----------------------|--------|----------------------------------------------------------------------| +| name | str | (Optional) The name of the structure. | +| description | str | (Optional) A description of the structure. | +| save_metadata | bool | A boolean flag to enable or disable metadata saving. | +| save_artifact_path | str | (Optional) The path to save artifacts. | +| save_metadata_path | str | (Optional) The path to save metadata. | +| save_error_path | str | (Optional) The path to save errors. | +## Methods: -### Creating a New Prompt +### 1. run +Runs the structure. -To create a new instance of a `Prompt`, simply initialize it with the required attributes such as `content`: +### 2. save_to_file +Saves data to a file. +* **data**: Value to be saved. +* **file_path**: Path where the data is to be saved. -```python -from swarms import Prompt +### 3. load_from_file +Loads data from a file. +* **file_path**: Path from where the data is to be loaded. -prompt = Prompt( - content="This is my first prompt!", - name="My First Prompt", - description="A simple example prompt." -) +### 4. save_metadata +Saves metadata to a file. +* **metadata**: Data to be saved as metadata. -print(prompt) -``` +### 5. load_metadata +Loads metadata from a file. -This creates a new prompt with the current timestamp and a unique identifier. +### 6. log_error +Logs error to a file. ---- +### 7. save_artifact +Saves artifact to a file. +* **artifact**: The artifact to be saved. +* **artifact_name**: Name of the artifact. -## 2. Managing Prompt Content +### 8. load_artifact +Loads artifact from a file. +* **artifact_name**: Name of the artifact. -### Editing Prompts +### 9. log_event +Logs an event to a file. +* **event**: The event to be logged. +* **event_type**: Type of the event (optional, defaults to "INFO"). -Once you have initialized a prompt, you can edit its content using the `edit_prompt` method. Each time the content is edited, a new version is stored in the `edit_history`, and the `last_modified_at` timestamp is updated. +### 10. run_async +Runs the structure asynchronously. -```python -new_content = "This is an updated version of my prompt." -prompt.edit_prompt(new_content) -``` +### 11. save_metadata_async +Saves metadata to a file asynchronously. -**Note**: If the new content is identical to the current content, an error will be raised to prevent unnecessary edits: +### 12. load_metadata_async +Loads metadata from a file asynchronously. -```python -try: - prompt.edit_prompt("This is my first prompt!") # Same as initial content -except ValueError as e: - print(e) # Output: New content must be different from the current content. -``` +### 13. log_error_async +Logs error to a file asynchronously. -### Retrieving Prompt Content +### 14. save_artifact_async +Saves artifact to a file asynchronously. -You can retrieve the current prompt content using the `get_prompt` method: +### 15. load_artifact_async +Loads artifact from a file asynchronously. -```python -current_content = prompt.get_prompt() -print(current_content) # Output: This is an updated version of my prompt. -``` +### 16. log_event_async +Logs an event to a file asynchronously. -This method also logs telemetry data, which includes both system information and prompt metadata. +### 17. asave_to_file +Saves data to a file asynchronously. ---- +### 18. aload_from_file +Loads data from a file asynchronously. -## 3. Version Control +### 19. run_concurrent +Runs the structure concurrently. -### Tracking Edits and History +### 20. compress_data +Compresses data. -The `Prompt` class automatically tracks every change made to the prompt. This is stored in the `edit_history` attribute as a list of previous versions. +### 21. decompres_data +Decompresses data. + +### 22. run_batched +Runs batched data. +## Examples: + +### Example 1: Saving Metadata ```python -print(prompt.edit_history) # Output: ['This is my first prompt!', 'This is an updated version of my prompt.'] +base_structure = BaseStructure(name="ExampleStructure") +metadata = {"key1": "value1", "key2": "value2"} +base_structure.save_metadata(metadata) ``` -The number of edits is also tracked using the `edit_count` attribute: +### Example 2: Loading Artifact +```python +artifact_name = "example_artifact" +artifact_data = base_structure.load_artifact(artifact_name) +``` +### Example 3: Running Concurrently ```python -print(prompt.edit_count) # Output: 2 +concurrent_data = [data1, data2, data3] +results = base_structure.run_concurrent(batched_data=concurrent_data) ``` -### Rolling Back to Previous Versions +## Note: -If you want to revert a prompt to a previous version, you can use the `rollback` method, passing the version index you want to revert to: +The `BaseStructure` class is designed to provide a modular and extensible structure for managing metadata, logs, errors, and batched operations while running machine learning models. The class's methods offer asynchronous and concurrent execution capabilities, thus optimizing the performance of the associated applications and models. The module's attributes and methods cater to a wide range of use cases, making it an essential foundational component for machine learning and data-based applications. -```python -prompt.rollback(0) -print(prompt.get_prompt()) # Output: This is my first prompt! -``` +# Conclusion: -The rollback operation is thread-safe, and any rollback also triggers a telemetry log. +The `BaseStructure` module offers a robust and flexible foundation for managing machine learning model metadata, error logs, and event tracking, including asynchronous, concurrent, and batched operations. By leveraging the inherent capabilities of this class, developers can enhance the reliability, scalability, and performance of machine learning-based applications. + +## References: + +- [Python Concurrent Programming with `asyncio`](https://docs.python.org/3/library/asyncio.html) +- [Understanding Thread Pool Executor in Python](https://docs.python.org/3/library/concurrent.futures.html#executor-objects) +- [Documentation on `gzip` Module for Data Compression](https://docs.python.org/3/library/gzip.html) --- -## 4. Autosaving Prompts +The above documentation provides detailed information about the `BaseStructure` module, including its functionality, attributes, methods, usage examples, and references to relevant resources for further exploration. This comprehensive documentation aims to deepen the users' understanding of the module's purpose and how it can be effectively utilized in practice. -### Enabling and Configuring Autosave +Please let me know if you need further elaboration on any specific aspect or functionality of the `BaseStructure` module. -To automatically save prompts to storage after every change, you can enable the `autosave` feature when initializing the prompt: -```python -prompt = Prompt( - content="This is my first prompt!", - autosave=True, - autosave_folder="my_prompts" # Specify the folder within WORKSPACE_DIR -) -``` +-------------------------------------------------- -This will ensure that every edit or rollback action triggers an autosave to the specified folder. +# File: swarms\structs\concurrentworkflow.md -### Manually Triggering Autosave +# ConcurrentWorkflow Documentation -You can also manually trigger an autosave by calling the `_autosave` method (which is a private method typically used internally): +## Overview -```python -prompt._autosave() # Manually triggers autosaving -``` +The `ConcurrentWorkflow` class is designed to facilitate the concurrent execution of multiple agents, each tasked with solving a specific query or problem. This class is particularly useful in scenarios where multiple agents need to work in parallel, allowing for efficient resource utilization and faster completion of tasks. The workflow manages the execution, collects metadata, and optionally saves the results in a structured format. -Autosaves are stored as JSON files in the folder specified by `autosave_folder` under the workspace directory (`WORKSPACE_DIR` environment variable). +### Key Features ---- +- **Concurrent Execution**: Runs multiple agents simultaneously using Python's `ThreadPoolExecutor` +- **Interactive Mode**: Supports interactive task modification and execution +- **Caching System**: Implements LRU caching for repeated prompts +- **Progress Tracking**: Optional progress bar for task execution +- **Enhanced Error Handling**: Implements retry mechanism with exponential backoff +- **Input Validation**: Validates task inputs before execution +- **Batch Processing**: Supports running tasks in batches +- **Metadata Collection**: Gathers detailed metadata about each agent's execution +- **Customizable Output**: Allows saving metadata to file or returning as string/dictionary -## 5. Logging and Telemetry +## Class Definition -The `Prompt` class integrates with the `loguru` logging library to provide detailed logs for every major action, such as editing, rolling back, and saving. The `log_telemetry` method captures and logs system data, including prompt metadata, for each operation. +### Attributes -Here's an example of a log when editing a prompt: +| Attribute | Type | Description | +|------------------------|-------------------------|-----------------------------------------------------------| +| `name` | `str` | The name of the workflow. Defaults to `"ConcurrentWorkflow"`. | +| `description` | `str` | A brief description of the workflow. | +| `agents` | `List[Agent]` | A list of agents to be executed concurrently. | +| `metadata_output_path` | `str` | Path to save the metadata output. Defaults to `"agent_metadata.json"`. | +| `auto_save` | `bool` | Flag indicating whether to automatically save the metadata. | +| `output_type` | `str` | The type of output format. Defaults to `"dict"`. | +| `max_loops` | `int` | Maximum number of loops for each agent. Defaults to `1`. | +| `return_str_on` | `bool` | Flag to return output as string. Defaults to `False`. | +| `auto_generate_prompts`| `bool` | Flag indicating whether to auto-generate prompts for agents. | +| `return_entire_history`| `bool` | Flag to return entire conversation history. Defaults to `False`. | +| `interactive` | `bool` | Flag indicating whether to enable interactive mode. Defaults to `False`. | +| `cache_size` | `int` | The size of the cache. Defaults to `100`. | +| `max_retries` | `int` | The maximum number of retry attempts. Defaults to `3`. | +| `retry_delay` | `float` | The delay between retry attempts in seconds. Defaults to `1.0`. | +| `show_progress` | `bool` | Flag indicating whether to show progress. Defaults to `False`. | +| `_cache` | `dict` | The cache for storing agent outputs. | +| `_progress_bar` | `tqdm` | The progress bar for tracking execution. | -```bash -2024-10-10 10:12:34.567 | INFO | Editing prompt a7b8f9. Current content: 'This is my first prompt!' -2024-10-10 10:12:34.789 | DEBUG | Prompt a7b8f9 updated. Edit count: 1. New content: 'This is an updated version of my prompt.' -``` +## Methods -You can extend logging by integrating the `log_telemetry` method with your own telemetry systems or databases: +### ConcurrentWorkflow.\_\_init\_\_ -```python -prompt.log_telemetry() -``` +Initializes the `ConcurrentWorkflow` class with the provided parameters. ---- +#### Parameters -## 6. Handling Errors +| Parameter | Type | Default Value | Description | +|-----------------------|----------------|----------------------------------------|-----------------------------------------------------------| +| `name` | `str` | `"ConcurrentWorkflow"` | The name of the workflow. | +| `description` | `str` | `"Execution of multiple agents concurrently"` | A brief description of the workflow. | +| `agents` | `List[Agent]` | `[]` | A list of agents to be executed concurrently. | +| `metadata_output_path`| `str` | `"agent_metadata.json"` | Path to save the metadata output. | +| `auto_save` | `bool` | `True` | Flag indicating whether to automatically save the metadata. | +| `output_type` | `str` | `"dict"` | The type of output format. | +| `max_loops` | `int` | `1` | Maximum number of loops for each agent. | +| `return_str_on` | `bool` | `False` | Flag to return output as string. | +| `auto_generate_prompts`| `bool` | `False` | Flag indicating whether to auto-generate prompts for agents. | +| `return_entire_history`| `bool` | `False` | Flag to return entire conversation history. | +| `interactive` | `bool` | `False` | Flag indicating whether to enable interactive mode. | +| `cache_size` | `int` | `100` | The size of the cache. | +| `max_retries` | `int` | `3` | The maximum number of retry attempts. | +| `retry_delay` | `float` | `1.0` | The delay between retry attempts in seconds. | +| `show_progress` | `bool` | `False` | Flag indicating whether to show progress. | -Error handling in the `Prompt` class is robust and prevents common mistakes, such as editing with identical content or rolling back to an invalid version. Here's a common scenario: +#### Raises -### Editing with Identical Content +- `ValueError`: If the list of agents is empty or if the description is empty. + +### ConcurrentWorkflow.disable_agent_prints + +Disables print statements for all agents in the workflow. ```python -try: - prompt.edit_prompt("This is an updated version of my prompt.") -except ValueError as e: - print(e) # Output: New content must be different from the current content. +workflow.disable_agent_prints() ``` -### Invalid Rollback Version +### ConcurrentWorkflow.activate_auto_prompt_engineering + +Activates the auto-generate prompts feature for all agents in the workflow. ```python -try: - prompt.rollback(10) # Invalid version index -except IndexError as e: - print(e) # Output: Invalid version number for rollback. +workflow.activate_auto_prompt_engineering() ``` -Always ensure that version numbers passed to `rollback` are within the valid range of existing versions. - ---- +### ConcurrentWorkflow.enable_progress_bar -## 7. Extending the Prompt Class +Enables the progress bar display for task execution. -### Customizing the Save Mechanism +```python +workflow.enable_progress_bar() +``` -The `Prompt` class currently includes a placeholder for saving and loading prompts from persistent storage. You can override the `save_to_storage` and `load_from_storage` methods to integrate with databases, cloud storage, or other persistent layers. +### ConcurrentWorkflow.disable_progress_bar -Here's how you can implement the save functionality: +Disables the progress bar display. ```python -def save_to_storage(self): - # Example of saving to a database or cloud storage - data = self.model_dump() - save_to_database(data) # Custom function to save data +workflow.disable_progress_bar() ``` -Similarly, you can implement a `load_from_storage` function to load the prompt from a storage location using its unique identifier (`id`). - +### ConcurrentWorkflow.clear_cache -## Full Example code with all methods +Clears the task cache. ```python -from swarms.prompts.prompt import Prompt +workflow.clear_cache() +``` -# Example 1: Initializing a Financial Report Prompt -financial_prompt = Prompt( - content="Q1 2024 Earnings Report: Initial Draft", autosave=True -) +### ConcurrentWorkflow.get_cache_stats -# Output the initial state of the prompt -print("\n--- Example 1: Initializing Prompt ---") -print(f"Prompt ID: {financial_prompt.id}") -print(f"Content: {financial_prompt.content}") -print(f"Created At: {financial_prompt.created_at}") -print(f"Edit Count: {financial_prompt.edit_count}") -print(f"History: {financial_prompt.edit_history}") +Gets cache statistics. +#### Returns -# Example 2: Editing a Financial Report Prompt -financial_prompt.edit_prompt( - "Q1 2024 Earnings Report: Updated Revenue Figures" -) +- `Dict[str, int]`: A dictionary containing cache statistics. -# Output the updated state of the prompt -print("\n--- Example 2: Editing Prompt ---") -print(f"Content after edit: {financial_prompt.content}") -print(f"Edit Count: {financial_prompt.edit_count}") -print(f"History: {financial_prompt.edit_history}") +```python +stats = workflow.get_cache_stats() +print(stats) # {'cache_size': 5, 'max_cache_size': 100} +``` +### ConcurrentWorkflow.run -# Example 3: Rolling Back to a Previous Version -financial_prompt.edit_prompt("Q1 2024 Earnings Report: Final Version") -financial_prompt.rollback( - 1 -) # Roll back to the second version (index 1) +Executes the workflow for the provided task. -# Output the state after rollback -print("\n--- Example 3: Rolling Back ---") -print(f"Content after rollback: {financial_prompt.content}") -print(f"Edit Count: {financial_prompt.edit_count}") -print(f"History: {financial_prompt.edit_history}") +#### Parameters +| Parameter | Type | Description | +|-------------|---------------------|-----------------------------------------------------------| +| `task` | `Optional[str]` | The task or query to give to all agents. | +| `img` | `Optional[str]` | The image to be processed by the agents. | +| `*args` | `tuple` | Additional positional arguments. | +| `**kwargs` | `dict` | Additional keyword arguments. | -# Example 4: Handling Invalid Rollback -print("\n--- Example 4: Invalid Rollback ---") -try: - financial_prompt.rollback( - 5 - ) # Attempt an invalid rollback (out of bounds) -except IndexError as e: - print(f"Error: {e}") +#### Returns +- `Any`: The result of the execution, format depends on output_type and return_entire_history settings. -# Example 5: Preventing Duplicate Edits -print("\n--- Example 5: Preventing Duplicate Edits ---") -try: - financial_prompt.edit_prompt( - "Q1 2024 Earnings Report: Updated Revenue Figures" - ) # Duplicate content -except ValueError as e: - print(f"Error: {e}") +#### Raises +- `ValueError`: If an invalid device is specified. +- `Exception`: If any other error occurs during execution. -# Example 6: Retrieving the Prompt Content as a String -print("\n--- Example 6: Retrieving Prompt as String ---") -current_content = financial_prompt.get_prompt() -print(f"Current Prompt Content: {current_content}") +### ConcurrentWorkflow.run_batched +Runs the workflow for a batch of tasks. -# Example 7: Simulating Financial Report Changes Over Time -print("\n--- Example 7: Simulating Changes Over Time ---") -# Initialize a new prompt representing an initial financial report draft -financial_prompt = Prompt( - content="Q2 2024 Earnings Report: Initial Draft" -) +#### Parameters -# Simulate several updates over time -financial_prompt.edit_prompt( - "Q2 2024 Earnings Report: Updated Forecasts" -) -financial_prompt.edit_prompt( - "Q2 2024 Earnings Report: Revenue Adjustments" +| Parameter | Type | Description | +|-------------|--------------|-----------------------------------------------------------| +| `tasks` | `List[str]` | A list of tasks or queries to give to all agents. | + +#### Returns + +- `List[Any]`: A list of results for each task. + +## Usage Examples + +### Example 1: Basic Usage with Interactive Mode + +```python +from swarms import Agent, ConcurrentWorkflow + +# Initialize agents +agents = [ + Agent( + agent_name=f"Agent-{i}", + system_prompt="You are a helpful assistant.", + model_name="gpt-4", + max_loops=1, + ) + for i in range(3) +] + +# Initialize workflow with interactive mode +workflow = ConcurrentWorkflow( + name="Interactive Workflow", + agents=agents, + interactive=True, + show_progress=True, + cache_size=100, + max_retries=3, + retry_delay=1.0 ) -financial_prompt.edit_prompt("Q2 2024 Earnings Report: Final Review") -# Display full history -print(f"Final Content: {financial_prompt.content}") -print(f"Edit Count: {financial_prompt.edit_count}") -print(f"Edit History: {financial_prompt.edit_history}") +# Run workflow +task = "What are the benefits of using Python for data analysis?" +result = workflow.run(task) +print(result) +``` + +### Example 2: Batch Processing with Progress Bar + +```python +# Initialize workflow +workflow = ConcurrentWorkflow( + name="Batch Processing Workflow", + agents=agents, + show_progress=True, + auto_save=True +) +# Define tasks +tasks = [ + "Analyze the impact of climate change on agriculture", + "Evaluate renewable energy solutions", + "Assess water conservation strategies" +] +# Run batch processing +results = workflow.run_batched(tasks) +# Process results +for task, result in zip(tasks, results): + print(f"Task: {task}") + print(f"Result: {result}\n") ``` ---- +### Example 3: Error Handling and Retries -## 8. Conclusion +```python +import logging -This guide covered how to effectively use the `Prompt` class in production environments, including core features like editing, version control, autosaving, and logging. By following the best practices outlined here, you can ensure that your prompts are managed efficiently, with minimal overhead and maximum flexibility. +# Set up logging +logging.basicConfig(level=logging.INFO) -The `Prompt` class is designed with scalability and robustness in mind, making it a great choice for managing prompt content in multi-agent architectures or any application where dynamic prompt management is required. Feel free to extend the functionality to suit your needs, whether it's integrating with persistent storage or enhancing logging mechanisms. +# Initialize workflow with retry settings +workflow = ConcurrentWorkflow( + name="Reliable Workflow", + agents=agents, + max_retries=3, + retry_delay=1.0, + show_progress=True +) -By using this architecture, you'll be able to scale your system effortlessly while maintaining detailed version control and history of every interaction with your prompts. +# Run workflow with error handling +try: + task = "Generate a comprehensive market analysis report" + result = workflow.run(task) + print(result) +except Exception as e: + logging.error(f"An error occurred: {str(e)}") +``` + +## Tips and Best Practices + +- **Agent Initialization**: Ensure all agents are correctly initialized with required configurations. +- **Interactive Mode**: Use interactive mode for tasks requiring user input or modification. +- **Caching**: Utilize the caching system for repeated tasks to improve performance. +- **Progress Tracking**: Enable progress bar for long-running tasks to monitor execution. +- **Error Handling**: Implement proper error handling and use retry mechanism for reliability. +- **Resource Management**: Monitor cache size and clear when necessary. +- **Batch Processing**: Use batch processing for multiple related tasks. +- **Logging**: Implement detailed logging for debugging and monitoring. + +## References and Resources + +- [Python's ThreadPoolExecutor Documentation](https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.ThreadPoolExecutor) +- [tqdm Progress Bar Documentation](https://tqdm.github.io/) +- [Python's functools.lru_cache Documentation](https://docs.python.org/3/library/functools.html#functools.lru_cache) +- [Loguru for Logging in Python](https://loguru.readthedocs.io/en/stable/) -------------------------------------------------- -# File: swarms/structs/abstractswarm.md +# File: swarms\structs\conversation.md -# `BaseSwarm` Documentation +# Module/Class Name: Conversation -## Table of Contents +## Introduction -1. [Introduction](#introduction) -2. [Class Definition](#class-definition) -3. [Methods](#methods) - - [communicate()](#communicate) - - [run()](#run) - - [arun()](#arun) - - [add_worker(worker)](#add_worker) - - [remove_worker(worker)](#remove_worker) - - [broadcast(message, sender)](#broadcast) - - [reset()](#reset) - - [plan(task)](#plan) - - [direct_message(message, sender, recipient)](#direct_message) - - [autoscaler(num_workers, worker)](#autoscaler) - - [get_worker_by_id(id)](#get_worker_by_id) - - [get_worker_by_name(name)](#get_worker_by_name) - - [assign_task(worker, task)](#assign_task) - - [get_all_tasks(worker, task)](#get_all_tasks) - - [get_finished_tasks()](#get_finished_tasks) - - [get_pending_tasks()](#get_pending_tasks) - - [pause_worker(worker, worker_id)](#pause_worker) - - [resume_worker(worker, worker_id)](#resume_worker) - - [stop_worker(worker, worker_id)](#stop_worker) - - [restart_worker(worker)](#restart_worker) - - [scale_up(num_worker)](#scale_up) - - [scale_down(num_worker)](#scale_down) - - [scale_to(num_worker)](#scale_to) - - [get_all_workers()](#get_all_workers) - - [get_swarm_size()](#get_swarm_size) - - [get_swarm_status()](#get_swarm_status) - - [save_swarm_state()](#save_swarm_state) +The `Conversation` class is a powerful and flexible tool for managing conversational data in Python applications. It provides a comprehensive solution for storing, retrieving, and analyzing conversations with support for multiple storage backends, token tracking, and advanced metadata management. ---- +### Key Features -## 1. Introduction +- **Multiple Storage Backends**: Support for various storage solutions: + - In-memory: Fast, temporary storage for testing and development + - Supabase: PostgreSQL-based cloud storage with real-time capabilities + - Redis: High-performance caching and persistence + - SQLite: Local file-based storage + - DuckDB: Analytical workloads and columnar storage + - Pulsar: Event streaming for distributed systems + - Mem0: Memory-based storage with mem0 integration + +- **Token Management**: + - Built-in token counting with configurable models + - Automatic token tracking for input/output messages + - Token usage analytics and reporting + - Context length management + +- **Metadata and Categories**: + - Support for message metadata + - Message categorization (input/output) + - Role-based message tracking + - Custom message IDs + +- **Data Export/Import**: + - JSON and YAML export formats + - Automatic saving and loading + - Conversation history management + - Batch operations support + +- **Advanced Features**: + - Message search and filtering + - Conversation analytics + - Multi-agent support + - Error handling and fallbacks + - Type hints and validation + +### Use Cases + +1. **Chatbot Development**: + - Store and manage conversation history + - Track token usage and context length + - Analyze conversation patterns + +2. **Multi-Agent Systems**: + - Coordinate multiple AI agents + - Track agent interactions + - Store agent outputs and metadata + +3. **Analytics Applications**: + - Track conversation metrics + - Generate usage reports + - Analyze user interactions + +4. **Production Systems**: + - Persistent storage with various backends + - Error handling and recovery + - Scalable conversation management + +5. **Development and Testing**: + - Fast in-memory storage + - Debugging support + - Easy export/import of test data + +### Best Practices + +1. **Storage Selection**: + - Use in-memory for testing and development + - Choose Supabase for multi-user cloud applications + - Use Redis for high-performance requirements + - Select SQLite for single-user local applications + - Pick DuckDB for analytical workloads + - Opt for Pulsar in distributed systems + +2. **Token Management**: + - Enable token counting for production use + - Set appropriate context lengths + - Monitor token usage with export_and_count_categories() -The Swarms library is designed to provide a framework for swarm simulation architectures. Swarms are collections of autonomous agents or workers that collaborate to perform tasks and achieve common goals. This documentation will guide you through the functionality and usage of the Swarms library, explaining the purpose and implementation details of the provided classes and methods. +3. **Error Handling**: + - Implement proper fallback mechanisms + - Use type hints for better code reliability + - Monitor and log errors appropriately -## 2. Class Definition +4. **Data Management**: + - Use appropriate export formats (JSON/YAML) + - Implement regular backup strategies + - Clean up old conversations when needed -### `BaseSwarm` Class +5. **Security**: + - Use environment variables for sensitive credentials + - Implement proper access controls + - Validate input data -The `BaseSwarm` class is an abstract base class that serves as the foundation for swarm simulation architectures. It defines the core functionality and methods required to manage and interact with a swarm of workers. +## Table of Contents -```python -from abc import ABC, abstractmethod -from typing import List +1. [Class Definition](#1-class-definition) +2. [Initialization Parameters](#2-initialization-parameters) +3. [Backend Configuration](#3-backend-configuration) +4. [Methods](#4-methods) +5. [Examples](#5-examples) -from swarms.swarms.base import AbstractWorker +## 1. Class Definition +### Overview -class BaseSwarm(ABC): - """ - Abstract class for swarm simulation architectures +The `Conversation` class is designed to manage conversations by keeping track of messages and their attributes. It offers methods for adding, deleting, updating, querying, and displaying messages within the conversation. Additionally, it supports exporting and importing conversations, searching for specific keywords, and more. - Methods: - --------- - ... - """ +**New in this version**: The class now supports multiple storage backends for persistent conversation storage: - # The class definition and constructor are provided here. +- **"in-memory"**: Default memory-based storage (no persistence) +- **"mem0"**: Memory-based storage with mem0 integration (requires: `pip install mem0ai`) +- **"supabase"**: PostgreSQL-based storage using Supabase (requires: `pip install supabase`) +- **"redis"**: Redis-based storage (requires: `pip install redis`) +- **"sqlite"**: SQLite-based storage (built-in to Python) +- **"duckdb"**: DuckDB-based storage (requires: `pip install duckdb`) +- **"pulsar"**: Apache Pulsar messaging backend (requires: `pip install pulsar-client`) - @abstractmethod - def __init__(self, workers: List["AbstractWorker"]): - """Initialize the swarm with workers""" +All backends use **lazy loading** - database dependencies are only imported when the specific backend is instantiated. Each backend provides helpful error messages if required packages are not installed. - # Other abstract methods are listed here. -``` +### Attributes -## 3. Methods +| Attribute | Type | Description | +|-----------|------|-------------| +| id | str | Unique identifier for the conversation | +| name | str | Name of the conversation | +| system_prompt | Optional[str] | System prompt for the conversation | +| time_enabled | bool | Flag to enable time tracking for messages | +| autosave | bool | Flag to enable automatic saving | +| save_enabled | bool | Flag to control if saving is enabled | +| save_filepath | str | File path for saving conversation history | +| load_filepath | str | File path for loading conversation history | +| conversation_history | list | List storing conversation messages | +| tokenizer | Callable | Tokenizer for counting tokens | +| context_length | int | Maximum tokens allowed in conversation | +| rules | str | Rules for the conversation | +| custom_rules_prompt | str | Custom prompt for rules | +| user | str | User identifier for messages | +| save_as_yaml | bool | Flag to save as YAML | +| save_as_json_bool | bool | Flag to save as JSON | +| token_count | bool | Flag to enable token counting | +| message_id_on | bool | Flag to enable message IDs | +| backend | str | Storage backend type | +| backend_instance | Any | The actual backend instance | +| conversations_dir | str | Directory to store conversations | + +## 2. Initialization Parameters -### `communicate()` +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| id | str | generated | Unique conversation ID | +| name | str | "conversation-test" | Name of the conversation | +| system_prompt | Optional[str] | None | System prompt for the conversation | +| time_enabled | bool | False | Enable time tracking | +| autosave | bool | False | Enable automatic saving | +| save_filepath | str | None | File path for saving | +| load_filepath | str | None | File path for loading | +| context_length | int | 8192 | Maximum tokens allowed | +| rules | str | None | Conversation rules | +| custom_rules_prompt | str | None | Custom rules prompt | +| user | str | "User" | User identifier | +| save_as_yaml_on | bool | False | Save as YAML | +| save_as_json_bool | bool | False | Save as JSON | +| token_count | bool | False | Enable token counting | +| message_id_on | bool | False | Enable message IDs | +| provider | Literal["mem0", "in-memory"] | "in-memory" | Legacy storage provider | +| backend | Optional[str] | None | Storage backend (takes precedence over provider) | +| tokenizer_model_name | str | "gpt-4.1" | Model name for tokenization | +| conversations_dir | Optional[str] | None | Directory for conversations | +| export_method | str | "json" | Export format ("json" or "yaml") | + +### Backend-Specific Parameters + +#### Supabase Backend +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| supabase_url | Optional[str] | None | Supabase project URL | +| supabase_key | Optional[str] | None | Supabase API key | +| table_name | str | "conversations" | Database table name | -The `communicate()` method allows the swarm to exchange information through the orchestrator, protocols, and the universal communication layer. +Environment variables: `SUPABASE_URL`, `SUPABASE_ANON_KEY` -**Usage Example 1:** +#### Redis Backend +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| redis_host | str | "localhost" | Redis server host | +| redis_port | int | 6379 | Redis server port | +| redis_db | int | 0 | Redis database number | +| redis_password | Optional[str] | None | Redis password | +| use_embedded_redis | bool | True | Use embedded Redis | +| persist_redis | bool | True | Enable Redis persistence | +| auto_persist | bool | True | Auto-persist data | +| redis_data_dir | Optional[str] | None | Redis data directory | + +#### SQLite/DuckDB Backend +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| db_path | Optional[str] | None | Database file path | -```python -swarm = YourSwarmClass(workers) -swarm.communicate() -``` +#### Pulsar Backend +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| pulsar_url | str | "pulsar://localhost:6650" | Pulsar server URL | +| topic | str | f"conversation-{id}" | Pulsar topic name | -**Usage Example 2:** +### Backend Selection + +The `backend` parameter takes precedence over the legacy `provider` parameter: ```python -# Another example of using the communicate method -swarm = YourSwarmClass(workers) -swarm.communicate() +# Legacy way (still supported) +conversation = Conversation(provider="in-memory") + +# New way (recommended) +conversation = Conversation(backend="supabase") +conversation = Conversation(backend="redis") +conversation = Conversation(backend="sqlite") ``` -### `run()` +## 4. Methods -The `run()` method executes the swarm, initiating its activities. +### `add(role: str, content: Union[str, dict, list], metadata: Optional[dict] = None)` -**Usage Example 1:** +Adds a message to the conversation history. + +| Parameter | Type | Description | +|-----------|------|-------------| +| role | str | Role of the speaker | +| content | Union[str, dict, list] | Message content | +| metadata | Optional[dict] | Additional metadata | +Example: ```python -swarm = YourSwarmClass(workers) -swarm.run() +conversation = Conversation() +conversation.add("user", "Hello, how are you?") +conversation.add("assistant", "I'm doing well, thank you!") ``` -**Usage Example 2:** +### `add_multiple_messages(roles: List[str], contents: List[Union[str, dict, list]])` + +Adds multiple messages to the conversation history. + +| Parameter | Type | Description | +|-----------|------|-------------| +| roles | List[str] | List of speaker roles | +| contents | List[Union[str, dict, list]] | List of message contents | +Example: ```python -# Another example of running the swarm -swarm = YourSwarmClass(workers) -swarm.run() +conversation = Conversation() +conversation.add_multiple_messages( + ["user", "assistant"], + ["Hello!", "Hi there!"] +) ``` -### `arun()` +### `delete(index: str)` -The `arun()` method runs the swarm asynchronously, allowing for parallel execution of tasks. +Deletes a message from the conversation history. -**Usage Example 1:** +| Parameter | Type | Description | +|-----------|------|-------------| +| index | str | Index of message to delete | +Example: ```python -swarm = YourSwarmClass(workers) -swarm.arun() +conversation = Conversation() +conversation.add("user", "Hello") +conversation.delete(0) # Deletes the first message ``` -**Usage Example 2:** +### `update(index: str, role: str, content: Union[str, dict])` + +Updates a message in the conversation history. + +| Parameter | Type | Description | +|-----------|------|-------------| +| index | str | Index of message to update | +| role | str | New role of speaker | +| content | Union[str, dict] | New message content | +Example: ```python -# Another example of running the swarm asynchronously -swarm = YourSwarmClass(workers) -swarm.arun() +conversation = Conversation() +conversation.add("user", "Hello") +conversation.update(0, "user", "Hi there!") ``` -### `add_worker(worker: "AbstractWorker")` - -The `add_worker()` method adds a worker to the swarm. +### `query(index: str)` -**Parameters:** -- `worker` (AbstractWorker): The worker to be added to the swarm. +Retrieves a message from the conversation history. -**Usage Example:** +| Parameter | Type | Description | +|-----------|------|-------------| +| index | str | Index of message to query | +Example: ```python -swarm = YourSwarmClass([]) -worker = YourWorkerClass() -swarm.add_worker(worker) +conversation = Conversation() +conversation.add("user", "Hello") +message = conversation.query(0) ``` -### `remove_worker(worker: "AbstractWorker")` - -The `remove_worker()` method removes a worker from the swarm. +### `search(keyword: str)` -**Parameters:** -- `worker` (AbstractWorker): The worker to be removed from the swarm. +Searches for messages containing a keyword. -**Usage Example:** +| Parameter | Type | Description | +|-----------|------|-------------| +| keyword | str | Keyword to search for | +Example: ```python -swarm = YourSwarmClass(workers) -worker = swarm.get_worker_by_id("worker_id") -swarm.remove_worker(worker) +conversation = Conversation() +conversation.add("user", "Hello world") +results = conversation.search("world") ``` -### `broadcast(message: str, sender: Optional["AbstractWorker"] = None)` - -The `broadcast()` method sends a message to all workers in the swarm. +### `display_conversation(detailed: bool = False)` -**Parameters:** -- `message` (str): The message to be broadcasted. -- `sender` (Optional[AbstractWorker]): The sender of the message (optional). +Displays the conversation history. -**Usage Example 1:** +| Parameter | Type | Description | +|-----------|------|-------------| +| detailed | bool | Show detailed information | +Example: ```python -swarm = YourSwarmClass(workers) -message = "Hello, everyone!" -swarm.broadcast(message) +conversation = Conversation() +conversation.add("user", "Hello") +conversation.display_conversation(detailed=True) ``` -**Usage Example 2:** +### `export_conversation(filename: str)` + +Exports conversation history to a file. +| Parameter | Type | Description | +|-----------|------|-------------| +| filename | str | Output file path | + +Example: ```python -# Another example of broadcasting a message -swarm = YourSwarmClass(workers) -message = "Important announcement!" -sender = swarm.get_worker_by_name("Supervisor") -swarm.broadcast(message, sender) +conversation = Conversation() +conversation.add("user", "Hello") +conversation.export_conversation("chat.txt") ``` -### `reset()` +### `import_conversation(filename: str)` -The `reset()` method resets the swarm to its initial state. +Imports conversation history from a file. -**Usage Example:** +| Parameter | Type | Description | +|-----------|------|-------------| +| filename | str | Input file path | +Example: ```python -swarm = YourSwarmClass(workers) -swarm.reset() +conversation = Conversation() +conversation.import_conversation("chat.txt") ``` -### `plan(task: str)` - -The `plan()` method instructs workers to individually plan using a workflow or pipeline for a specified task. +### `count_messages_by_role()` -**Parameters:** -- `task` (str): The task for which workers should plan. +Counts messages by role. -**Usage Example:** +Returns: Dict[str, int] +Example: ```python -swarm = YourSwarmClass(workers) -task = "Perform data analysis" -swarm.plan(task) +conversation = Conversation() +conversation.add("user", "Hello") +conversation.add("assistant", "Hi") +counts = conversation.count_messages_by_role() ``` -### `direct_message(message: str, sender: "AbstractWorker", recipient: "AbstractWorker")` - -The `direct_message()` method sends a direct message from one worker to another. +### `return_history_as_string()` -**Parameters:** -- `message` (str): The message to be sent. -- `sender` (AbstractWorker): The sender of the message. -- `recipient` (AbstractWorker): The recipient of the message. +Returns conversation history as a string. -**Usage Example:** +Returns: str +Example: ```python -swarm = YourSwarmClass(workers) -sender = swarm.get_worker_by_name("Worker1") -recipient = swarm.get_worker_by_name("Worker2") -message = "Hello - -, Worker2!" -swarm.direct_message(message, sender, recipient) +conversation = Conversation() +conversation.add("user", "Hello") +history = conversation.return_history_as_string() ``` -### `autoscaler(num_workers: int, worker: List["AbstractWorker"])` - -The `autoscaler()` method acts as an autoscaler, dynamically adjusting the number of workers based on system load or other criteria. +### `save_as_json(filename: str)` -**Parameters:** -- `num_workers` (int): The desired number of workers. -- `worker` (List[AbstractWorker]): A list of workers to be managed by the autoscaler. +Saves conversation history as JSON. -**Usage Example:** +| Parameter | Type | Description | +|-----------|------|-------------| +| filename | str | Output JSON file path | +Example: ```python -swarm = YourSwarmClass([]) -workers = [YourWorkerClass() for _ in range(10)] -swarm.autoscaler(5, workers) +conversation = Conversation() +conversation.add("user", "Hello") +conversation.save_as_json("chat.json") ``` -### `get_worker_by_id(id: str) -> "AbstractWorker"` - -The `get_worker_by_id()` method locates a worker in the swarm by their ID. - -**Parameters:** -- `id` (str): The ID of the worker to locate. +### `load_from_json(filename: str)` -**Returns:** -- `AbstractWorker`: The worker with the specified ID. +Loads conversation history from JSON. -**Usage Example:** +| Parameter | Type | Description | +|-----------|------|-------------| +| filename | str | Input JSON file path | +Example: ```python -swarm = YourSwarmClass(workers) -worker_id = "worker_123" -worker = swarm.get_worker_by_id(worker_id) +conversation = Conversation() +conversation.load_from_json("chat.json") ``` -### `get_worker_by_name(name: str) -> "AbstractWorker"` +### `truncate_memory_with_tokenizer()` -The `get_worker_by_name()` method locates a worker in the swarm by their name. +Truncates conversation history based on token limit. -**Parameters:** -- `name` (str): The name of the worker to locate. +Example: +```python +conversation = Conversation(tokenizer=some_tokenizer) +conversation.truncate_memory_with_tokenizer() +``` -**Returns:** -- `AbstractWorker`: The worker with the specified name. +### `clear()` -**Usage Example:** +Clears the conversation history. +Example: ```python -swarm = YourSwarmClass(workers) -worker_name = "Alice" -worker = swarm.get_worker_by_name(worker_name) +conversation = Conversation() +conversation.add("user", "Hello") +conversation.clear() ``` -### `assign_task(worker: "AbstractWorker", task: Any) -> Dict` - -The `assign_task()` method assigns a task to a specific worker. - -**Parameters:** -- `worker` (AbstractWorker): The worker to whom the task should be assigned. -- `task` (Any): The task to be assigned. +### `to_json()` -**Returns:** -- `Dict`: A dictionary indicating the status of the task assignment. +Converts conversation history to JSON string. -**Usage Example:** +Returns: str +Example: ```python -swarm = YourSwarmClass(workers) -worker = swarm.get_worker_by_name("Worker1") -task = "Perform data analysis" -result = swarm.assign_task(worker, task) +conversation = Conversation() +conversation.add("user", "Hello") +json_str = conversation.to_json() ``` -### `get_all_tasks(worker: "AbstractWorker", task: Any)` - -The `get_all_tasks()` method retrieves all tasks assigned to a specific worker. +### `to_dict()` -**Parameters:** -- `worker` (AbstractWorker): The worker for whom tasks should be retrieved. -- `task` (Any): The task to be retrieved. +Converts conversation history to dictionary. -**Usage Example:** +Returns: list +Example: ```python -swarm = YourSwarmClass(workers) -worker = swarm.get_worker_by_name("Worker1") -tasks = swarm.get_all_tasks(worker, "data analysis") +conversation = Conversation() +conversation.add("user", "Hello") +dict_data = conversation.to_dict() ``` -### `get_finished_tasks() -> List[Dict]` - -The `get_finished_tasks()` method retrieves all tasks that have been completed by the workers in the swarm. +### `to_yaml()` -**Returns:** -- `List[Dict]`: A list of dictionaries representing finished tasks. +Converts conversation history to YAML string. -**Usage Example:** +Returns: str +Example: ```python -swarm = YourSwarmClass(workers) -finished_tasks = swarm.get_finished_tasks() +conversation = Conversation() +conversation.add("user", "Hello") +yaml_str = conversation.to_yaml() ``` -### `get_pending_tasks() -> List[Dict]` +### `get_visible_messages(agent: "Agent", turn: int)` -The `get_pending_tasks()` method retrieves all tasks that are pending or yet to be completed by the workers in the swarm. +Gets visible messages for an agent at a specific turn. -**Returns:** -- `List[Dict]`: A list of dictionaries representing pending tasks. +| Parameter | Type | Description | +|-----------|------|-------------| +| agent | Agent | The agent | +| turn | int | Turn number | -**Usage Example:** +Returns: List[Dict] +Example: ```python -swarm = YourSwarmClass(workers) -pending_tasks = swarm.get_pending_tasks() +conversation = Conversation() +visible_msgs = conversation.get_visible_messages(agent, 1) ``` -### `pause_worker(worker: "AbstractWorker", worker_id: str)` - -The `pause_worker()` method pauses a specific worker, temporarily suspending their activities. +### `get_last_message_as_string()` -**Parameters:** -- `worker` (AbstractWorker): The worker to be paused. -- `worker_id` (str): The ID of the worker to be paused. +Gets the last message as a string. -**Usage Example:** +Returns: str +Example: ```python -swarm = YourSwarmClass(workers) -worker = swarm.get_worker_by_name("Worker1") -worker_id = "worker_123" -swarm.pause_worker(worker, worker_id) +conversation = Conversation() +conversation.add("user", "Hello") +last_msg = conversation.get_last_message_as_string() ``` -### `resume_worker(worker: "AbstractWorker", worker_id: str)` - -The `resume_worker()` method resumes a paused worker, allowing them to continue their activities. +### `return_messages_as_list()` -**Parameters:** -- `worker` (AbstractWorker): The worker to be resumed. -- `worker_id` (str): The ID of the worker to be resumed. +Returns messages as a list of strings. -**Usage Example:** +Returns: List[str] +Example: ```python -swarm = YourSwarmClass(workers) -worker = swarm.get_worker_by_name("Worker1") -worker_id = "worker_123" -swarm.resume_worker(worker, worker_id) +conversation = Conversation() +conversation.add("user", "Hello") +messages = conversation.return_messages_as_list() ``` -### `stop_worker(worker: "AbstractWorker", worker_id: str)` - -The `stop_worker()` method stops a specific worker, terminating their activities. +### `return_messages_as_dictionary()` -**Parameters:** -- `worker` (AbstractWorker): The worker to be stopped. -- `worker_id` (str): The ID of the worker to be stopped. +Returns messages as a list of dictionaries. -**Usage Example:** +Returns: List[Dict] +Example: ```python -swarm = YourSwarmClass(workers) -worker = swarm.get_worker_by_name("Worker1") -worker_id = "worker_123" -swarm.stop_worker(worker, worker_id) +conversation = Conversation() +conversation.add("user", "Hello") +messages = conversation.return_messages_as_dictionary() ``` -### `restart_worker(worker: "AbstractWorker")` - -The `restart_worker()` method restarts a worker, resetting them to their initial state. +### `add_tool_output_to_agent(role: str, tool_output: dict)` -**Parameters:** -- `worker` (AbstractWorker): The worker to be restarted. +Adds tool output to conversation. -**Usage Example:** +| Parameter | Type | Description | +|-----------|------|-------------| +| role | str | Role of the tool | +| tool_output | dict | Tool output to add | +Example: ```python -swarm = YourSwarmClass(workers) -worker = swarm.get_worker_by_name("Worker1") -swarm.restart_worker(worker) +conversation = Conversation() +conversation.add_tool_output_to_agent("tool", {"result": "success"}) ``` -### `scale_up(num_worker: int)` - -The `scale_up()` method increases the number of workers in the swarm. +### `return_json()` -**Parameters:** -- `num_worker` (int): The number of workers to add to the swarm. +Returns conversation as JSON string. -**Usage Example:** +Returns: str +Example: ```python -swarm = YourSwarmClass(workers) -swarm.scale_up(5) +conversation = Conversation() +conversation.add("user", "Hello") +json_str = conversation.return_json() ``` -### `scale_down(num_worker: int)` - -The `scale_down()` method decreases the number of workers in the swarm. +### `get_final_message()` -**Parameters:** -- `num_worker` (int): The number of workers to remove from the swarm. +Gets the final message. -**Usage Example:** +Returns: str +Example: ```python -swarm = YourSwarmClass(workers) -swarm.scale_down(3) +conversation = Conversation() +conversation.add("user", "Hello") +final_msg = conversation.get_final_message() ``` -### `scale_to(num_worker: int)` - -The `scale_to()` method scales the swarm to a specific number of workers. +### `get_final_message_content()` -**Parameters:** -- `num_worker` (int): The desired number of workers. +Gets content of final message. -**Usage Example:** +Returns: str +Example: ```python -swarm = YourSwarmClass(workers) -swarm.scale_to(10) +conversation = Conversation() +conversation.add("user", "Hello") +content = conversation.get_final_message_content() ``` -### `get - -_all_workers() -> List["AbstractWorker"]` - -The `get_all_workers()` method retrieves a list of all workers in the swarm. +### `return_all_except_first()` -**Returns:** -- `List[AbstractWorker]`: A list of all workers in the swarm. +Returns all messages except first. -**Usage Example:** +Returns: List[Dict] +Example: ```python -swarm = YourSwarmClass(workers) -all_workers = swarm.get_all_workers() +conversation = Conversation() +conversation.add("system", "Start") +conversation.add("user", "Hello") +messages = conversation.return_all_except_first() ``` -### `get_swarm_size() -> int` - -The `get_swarm_size()` method returns the size of the swarm, which is the total number of workers. +### `return_all_except_first_string()` -**Returns:** -- `int`: The size of the swarm. +Returns all messages except first as string. -**Usage Example:** +Returns: str +Example: ```python -swarm = YourSwarmClass(workers) -swarm_size = swarm.get_swarm_size() +conversation = Conversation() +conversation.add("system", "Start") +conversation.add("user", "Hello") +messages = conversation.return_all_except_first_string() ``` -### `get_swarm_status() -> Dict` - -The `get_swarm_status()` method provides information about the current status of the swarm. +### `batch_add(messages: List[dict])` -**Returns:** -- `Dict`: A dictionary containing various status indicators for the swarm. +Adds multiple messages in batch. -**Usage Example:** +| Parameter | Type | Description | +|-----------|------|-------------| +| messages | List[dict] | List of messages to add | +Example: ```python -swarm = YourSwarmClass(workers) -swarm_status = swarm.get_swarm_status() +conversation = Conversation() +conversation.batch_add([ + {"role": "user", "content": "Hello"}, + {"role": "assistant", "content": "Hi"} +]) ``` -### `save_swarm_state()` +### `get_cache_stats()` -The `save_swarm_state()` method allows you to save the current state of the swarm, including worker configurations and task assignments. +Gets cache usage statistics. -**Usage Example:** +Returns: Dict[str, int] +Example: ```python -swarm = YourSwarmClass(workers) -swarm.save_swarm_state() +conversation = Conversation() +stats = conversation.get_cache_stats() ``` ---- +### `load_conversation(name: str, conversations_dir: Optional[str] = None)` -This comprehensive documentation covers the Swarms library, including the `BaseSwarm` class and its methods. You can use this documentation as a guide to understanding and effectively utilizing the Swarms framework for swarm simulation architectures. Feel free to explore further and adapt the library to your specific use cases. +Loads a conversation from cache. --------------------------------------------------- +| Parameter | Type | Description | +|-----------|------|-------------| +| name | str | Name of conversation | +| conversations_dir | Optional[str] | Directory containing conversations | -# File: swarms/structs/agent.md +Returns: Conversation -# `Agent` +Example: +```python +conversation = Conversation.load_conversation("my_chat") +``` -Swarm Agent is a powerful autonomous agent framework designed to connect Language Models (LLMs) with various tools and long-term memory. This class provides the ability to ingest and process various types of documents such as PDFs, text files, Markdown files, JSON files, and more. The Agent structure offers a wide range of features to enhance the capabilities of LLMs and facilitate efficient task execution. +### `list_cached_conversations(conversations_dir: Optional[str] = None)` -## Overview +Lists all cached conversations. -The `Agent` class establishes a conversational loop with a language model, allowing for interactive task execution, feedback collection, and dynamic response generation. It includes features such as: +| Parameter | Type | Description | +|-----------|------|-------------| +| conversations_dir | Optional[str] | Directory containing conversations | -1. **Conversational Loop**: Enables back-and-forth interaction with the model. -2. **Feedback Collection**: Allows users to provide feedback on generated responses. -3. **Stoppable Conversation**: Supports custom stopping conditions for the conversation. -4. **Retry Mechanism**: Implements a retry system for handling issues in response generation. -5. **Tool Integration**: Supports the integration of various tools for enhanced capabilities. -6. **Long-term Memory Management**: Incorporates vector databases for efficient information retrieval. -7. **Document Ingestion**: Processes various document types for information extraction. -8. **Interactive Mode**: Allows real-time communication with the agent. -9. **Sentiment Analysis**: Evaluates the sentiment of generated responses. -10. **Output Filtering and Cleaning**: Ensures generated responses meet specific criteria. -11. **Asynchronous and Concurrent Execution**: Supports efficient parallelization of tasks. -12. **Planning and Reasoning**: Implements techniques like algorithm of thoughts for enhanced decision-making. +Returns: List[str] +Example: +```python +conversations = Conversation.list_cached_conversations() +``` -## Architecture +### `clear_memory()` -```mermaid -graph TD - A[Task Initiation] -->|Receives Task| B[Initial LLM Processing] - B -->|Interprets Task| C[Tool Usage] - C -->|Calls Tools| D[Function 1] - C -->|Calls Tools| E[Function 2] - D -->|Returns Data| C - E -->|Returns Data| C - C -->|Provides Data| F[Memory Interaction] - F -->|Stores and Retrieves Data| G[RAG System] - G -->|ChromaDB/Pinecone| H[Enhanced Data] - F -->|Provides Enhanced Data| I[Final LLM Processing] - I -->|Generates Final Response| J[Output] - C -->|No Tools Available| K[Skip Tool Usage] - K -->|Proceeds to Memory Interaction| F - F -->|No Memory Available| L[Skip Memory Interaction] - L -->|Proceeds to Final LLM Processing| I +Clears the conversation memory. + +Example: +```python +conversation = Conversation() +conversation.add("user", "Hello") +conversation.clear_memory() ``` +## 5. Examples -## `Agent` Attributes +### Basic Usage with Modern Configuration -| Attribute | Description | -|-----------|-------------| -| `id` | Unique identifier for the agent instance. | -| `llm` | Language model instance used by the agent. | -| `template` | Template used for formatting responses. | -| `max_loops` | Maximum number of loops the agent can run. | -| `stopping_condition` | Callable function determining when to stop looping. | -| `loop_interval` | Interval (in seconds) between loops. | -| `retry_attempts` | Number of retry attempts for failed LLM calls. | -| `retry_interval` | Interval (in seconds) between retry attempts. | -| `return_history` | Boolean indicating whether to return conversation history. | -| `stopping_token` | Token that stops the agent from looping when present in the response. | -| `dynamic_loops` | Boolean indicating whether to dynamically determine the number of loops. | -| `interactive` | Boolean indicating whether to run in interactive mode. | -| `dashboard` | Boolean indicating whether to display a dashboard. | -| `agent_name` | Name of the agent instance. | -| `agent_description` | Description of the agent instance. | -| `system_prompt` | System prompt used to initialize the conversation. | -| `tools` | List of callable functions representing tools the agent can use. | -| `dynamic_temperature_enabled` | Boolean indicating whether to dynamically adjust the LLM's temperature. | -| `sop` | Standard operating procedure for the agent. | -| `sop_list` | List of strings representing the standard operating procedure. | -| `saved_state_path` | File path for saving and loading the agent's state. | -| `autosave` | Boolean indicating whether to automatically save the agent's state. | -| `context_length` | Maximum length of the context window (in tokens) for the LLM. | -| `user_name` | Name used to represent the user in the conversation. | -| `self_healing_enabled` | Boolean indicating whether to attempt self-healing in case of errors. | -| `code_interpreter` | Boolean indicating whether to interpret and execute code snippets. | -| `multi_modal` | Boolean indicating whether to support multimodal inputs. | -| `pdf_path` | File path of a PDF document to be ingested. | -| `list_of_pdf` | List of file paths for PDF documents to be ingested. | -| `tokenizer` | Instance of a tokenizer used for token counting and management. | -| `long_term_memory` | Instance of a `BaseVectorDatabase` implementation for long-term memory management. | -| `preset_stopping_token` | Boolean indicating whether to use a preset stopping token. | -| `traceback` | Object used for traceback handling. | -| `traceback_handlers` | List of traceback handlers. | -| `streaming_on` | Boolean indicating whether to stream responses. | -| `docs` | List of document paths or contents to be ingested. | -| `docs_folder` | Path to a folder containing documents to be ingested. | -| `verbose` | Boolean indicating whether to print verbose output. | -| `parser` | Callable function used for parsing input data. | -| `best_of_n` | Integer indicating the number of best responses to generate. | -| `callback` | Callable function to be called after each agent loop. | -| `metadata` | Dictionary containing metadata for the agent. | -| `callbacks` | List of callable functions to be called during execution. | -| `logger_handler` | Handler for logging messages. | -| `search_algorithm` | Callable function for long-term memory retrieval. | -| `logs_to_filename` | File path for logging agent activities. | -| `evaluator` | Callable function for evaluating the agent's responses. | -| `stopping_func` | Callable function used as a stopping condition. | -| `custom_loop_condition` | Callable function used as a custom loop condition. | -| `sentiment_threshold` | Float value representing the sentiment threshold for evaluating responses. | -| `custom_exit_command` | String representing a custom command for exiting the agent's loop. | -| `sentiment_analyzer` | Callable function for sentiment analysis on outputs. | -| `limit_tokens_from_string` | Callable function for limiting the number of tokens in a string. | -| `custom_tools_prompt` | Callable function for generating a custom prompt for tool usage. | -| `tool_schema` | Data structure representing the schema for the agent's tools. | -| `output_type` | Type representing the expected output type of responses. | -| `function_calling_type` | String representing the type of function calling. | -| `output_cleaner` | Callable function for cleaning the agent's output. | -| `function_calling_format_type` | String representing the format type for function calling. | -| `list_base_models` | List of base models used for generating tool schemas. | -| `metadata_output_type` | String representing the output type for metadata. | -| `state_save_file_type` | String representing the file type for saving the agent's state. | -| `chain_of_thoughts` | Boolean indicating whether to use the chain of thoughts technique. | -| `algorithm_of_thoughts` | Boolean indicating whether to use the algorithm of thoughts technique. | -| `tree_of_thoughts` | Boolean indicating whether to use the tree of thoughts technique. | -| `tool_choice` | String representing the method for tool selection. | -| `execute_tool` | Boolean indicating whether to execute tools. | -| `rules` | String representing the rules for the agent's behavior. | -| `planning` | Boolean indicating whether to perform planning. | -| `planning_prompt` | String representing the prompt for planning. | -| `device` | String representing the device on which the agent should run. | -| `custom_planning_prompt` | String representing a custom prompt for planning. | -| `memory_chunk_size` | Integer representing the maximum size of memory chunks for long-term memory retrieval. | -| `agent_ops_on` | Boolean indicating whether agent operations should be enabled. | -| `return_step_meta` | Boolean indicating whether to return JSON of all steps and additional metadata. | -| `output_type` | Literal type indicating whether to output "string", "str", "list", "json", "dict", or "yaml". | -| `time_created` | Float representing the time the agent was created. | -| `tags` | Optional list of strings for tagging the agent. | -| `use_cases` | Optional list of dictionaries describing use cases for the agent. | -| `step_pool` | List of Step objects representing the agent's execution steps. | -| `print_every_step` | Boolean indicating whether to print every step of execution. | -| `agent_output` | ManySteps object containing the agent's output and metadata. | -| `executor_workers` | Integer representing the number of executor workers for concurrent operations. | -| `data_memory` | Optional callable for data memory operations. | -| `load_yaml_path` | String representing the path to a YAML file for loading configurations. | -| `auto_generate_prompt` | Boolean indicating whether to automatically generate prompts. | -| `rag_every_loop` | Boolean indicating whether to query RAG database for context on every loop | -| `plan_enabled` | Boolean indicating whether planning functionality is enabled | -| `artifacts_on` | Boolean indicating whether to save artifacts from agent execution | -| `artifacts_output_path` | File path where artifacts should be saved | -| `artifacts_file_extension` | File extension to use for saved artifacts | -| `device` | Device to run computations on ("cpu" or "gpu") | -| `all_cores` | Boolean indicating whether to use all CPU cores | -| `device_id` | ID of the GPU device to use if running on GPU | -| `scheduled_run_date` | Optional datetime for scheduling future agent runs | +```python +from swarms.structs import Conversation +# Create a new conversation with modern configuration +conversation = Conversation( + name="my_chat", + system_prompt="You are a helpful assistant", + time_enabled=True, + token_count=True, + tokenizer_model_name="gpt-4.1", + message_id_on=True, + export_method="json", + autosave=True +) -## `Agent` Methods +# Add messages with metadata and categories +conversation.add( + role="user", + content="Hello!", + metadata={"session_id": "123"}, + category="input" +) -| Method | Description | Inputs | Usage Example | -|--------|-------------|--------|----------------| -| `run(task, img=None, is_last=False, device="cpu", device_id=0, all_cores=True, *args, **kwargs)` | Runs the autonomous agent loop to complete the given task. | `task` (str): The task to be performed.
`img` (str, optional): Path to an image file.
`is_last` (bool): Whether this is the last task.
`device` (str): Device to run on ("cpu" or "gpu").
`device_id` (int): ID of the GPU to use.
`all_cores` (bool): Whether to use all CPU cores.
`*args`, `**kwargs`: Additional arguments. | `response = agent.run("Generate a report on financial performance.")` | -| `__call__(task, img=None, *args, **kwargs)` | Alternative way to call the `run` method. | Same as `run`. | `response = agent("Generate a report on financial performance.")` | -| `parse_and_execute_tools(response, *args, **kwargs)` | Parses the agent's response and executes any tools mentioned in it. | `response` (str): The agent's response to be parsed.
`*args`, `**kwargs`: Additional arguments. | `agent.parse_and_execute_tools(response)` | -| `add_memory(message)` | Adds a message to the agent's memory. | `message` (str): The message to add. | `agent.add_memory("Important information")` | -| `plan(task, *args, **kwargs)` | Plans the execution of a task. | `task` (str): The task to plan.
`*args`, `**kwargs`: Additional arguments. | `agent.plan("Analyze market trends")` | -| `run_concurrent(task, *args, **kwargs)` | Runs a task concurrently. | `task` (str): The task to run.
`*args`, `**kwargs`: Additional arguments. | `response = await agent.run_concurrent("Concurrent task")` | -| `run_concurrent_tasks(tasks, *args, **kwargs)` | Runs multiple tasks concurrently. | `tasks` (List[str]): List of tasks to run.
`*args`, `**kwargs`: Additional arguments. | `responses = agent.run_concurrent_tasks(["Task 1", "Task 2"])` | -| `bulk_run(inputs)` | Generates responses for multiple input sets. | `inputs` (List[Dict[str, Any]]): List of input dictionaries. | `responses = agent.bulk_run([{"task": "Task 1"}, {"task": "Task 2"}])` | -| `save()` | Saves the agent's history to a file. | None | `agent.save()` | -| `load(file_path)` | Loads the agent's history from a file. | `file_path` (str): Path to the file. | `agent.load("agent_history.json")` | -| `graceful_shutdown()` | Gracefully shuts down the system, saving the state. | None | `agent.graceful_shutdown()` | -| `analyze_feedback()` | Analyzes the feedback for issues. | None | `agent.analyze_feedback()` | -| `undo_last()` | Undoes the last response and returns the previous state. | None | `previous_state, message = agent.undo_last()` | -| `add_response_filter(filter_word)` | Adds a response filter to filter out certain words. | `filter_word` (str): Word to filter. | `agent.add_response_filter("sensitive")` | -| `apply_response_filters(response)` | Applies response filters to the given response. | `response` (str): Response to filter. | `filtered_response = agent.apply_response_filters(response)` | -| `filtered_run(task)` | Runs a task with response filtering applied. | `task` (str): Task to run. | `response = agent.filtered_run("Generate a report")` | -| `save_to_yaml(file_path)` | Saves the agent to a YAML file. | `file_path` (str): Path to save the YAML file. | `agent.save_to_yaml("agent_config.yaml")` | -| `get_llm_parameters()` | Returns the parameters of the language model. | None | `llm_params = agent.get_llm_parameters()` | -| `save_state(file_path, *args, **kwargs)` | Saves the current state of the agent to a JSON file. | `file_path` (str): Path to save the JSON file.
`*args`, `**kwargs`: Additional arguments. | `agent.save_state("agent_state.json")` | -| `update_system_prompt(system_prompt)` | Updates the system prompt. | `system_prompt` (str): New system prompt. | `agent.update_system_prompt("New system instructions")` | -| `update_max_loops(max_loops)` | Updates the maximum number of loops. | `max_loops` (int): New maximum number of loops. | `agent.update_max_loops(5)` | -| `update_loop_interval(loop_interval)` | Updates the loop interval. | `loop_interval` (int): New loop interval. | `agent.update_loop_interval(2)` | -| `update_retry_attempts(retry_attempts)` | Updates the number of retry attempts. | `retry_attempts` (int): New number of retry attempts. | `agent.update_retry_attempts(3)` | -| `update_retry_interval(retry_interval)` | Updates the retry interval. | `retry_interval` (int): New retry interval. | `agent.update_retry_interval(5)` | -| `reset()` | Resets the agent's memory. | None | `agent.reset()` | -| `ingest_docs(docs, *args, **kwargs)` | Ingests documents into the agent's memory. | `docs` (List[str]): List of document paths.
`*args`, `**kwargs`: Additional arguments. | `agent.ingest_docs(["doc1.pdf", "doc2.txt"])` | -| `ingest_pdf(pdf)` | Ingests a PDF document into the agent's memory. | `pdf` (str): Path to the PDF file. | `agent.ingest_pdf("document.pdf")` | -| `receive_message(name, message)` | Receives a message and adds it to the agent's memory. | `name` (str): Name of the sender.
`message` (str): Content of the message. | `agent.receive_message("User", "Hello, agent!")` | -| `send_agent_message(agent_name, message, *args, **kwargs)` | Sends a message from the agent to a user. | `agent_name` (str): Name of the agent.
`message` (str): Message to send.
`*args`, `**kwargs`: Additional arguments. | `response = agent.send_agent_message("AgentX", "Task completed")` | -| `add_tool(tool)` | Adds a tool to the agent's toolset. | `tool` (Callable): Tool to add. | `agent.add_tool(my_custom_tool)` | -| `add_tools(tools)` | Adds multiple tools to the agent's toolset. | `tools` (List[Callable]): List of tools to add. | `agent.add_tools([tool1, tool2])` | -| `remove_tool(tool)` | Removes a tool from the agent's toolset. || Method | Description | Inputs | Usage Example | -|--------|-------------|--------|----------------| -| `remove_tool(tool)` | Removes a tool from the agent's toolset. | `tool` (Callable): Tool to remove. | `agent.remove_tool(my_custom_tool)` | -| `remove_tools(tools)` | Removes multiple tools from the agent's toolset. | `tools` (List[Callable]): List of tools to remove. | `agent.remove_tools([tool1, tool2])` | -| `get_docs_from_doc_folders()` | Retrieves and processes documents from the specified folder. | None | `agent.get_docs_from_doc_folders()` | -| `memory_query(task, *args, **kwargs)` | Queries the long-term memory for relevant information. | `task` (str): The task or query.
`*args`, `**kwargs`: Additional arguments. | `result = agent.memory_query("Find information about X")` | -| `sentiment_analysis_handler(response)` | Performs sentiment analysis on the given response. | `response` (str): The response to analyze. | `agent.sentiment_analysis_handler("Great job!")` | -| `count_and_shorten_context_window(history, *args, **kwargs)` | Counts tokens and shortens the context window if necessary. | `history` (str): The conversation history.
`*args`, `**kwargs`: Additional arguments. | `shortened_history = agent.count_and_shorten_context_window(history)` | -| `output_cleaner_and_output_type(response, *args, **kwargs)` | Cleans and formats the output based on specified type. | `response` (str): The response to clean and format.
`*args`, `**kwargs`: Additional arguments. | `cleaned_response = agent.output_cleaner_and_output_type(response)` | -| `stream_response(response, delay=0.001)` | Streams the response token by token. | `response` (str): The response to stream.
`delay` (float): Delay between tokens. | `agent.stream_response("This is a streamed response")` | -| `dynamic_context_window()` | Dynamically adjusts the context window. | None | `agent.dynamic_context_window()` | -| `check_available_tokens()` | Checks and returns the number of available tokens. | None | `available_tokens = agent.check_available_tokens()` | -| `tokens_checks()` | Performs token checks and returns available tokens. | None | `token_info = agent.tokens_checks()` | -| `truncate_string_by_tokens(input_string, limit)` | Truncates a string to fit within a token limit. | `input_string` (str): String to truncate.
`limit` (int): Token limit. | `truncated_string = agent.truncate_string_by_tokens("Long string", 100)` | -| `tokens_operations(input_string)` | Performs various token-related operations on the input string. | `input_string` (str): String to process. | `processed_string = agent.tokens_operations("Input string")` | -| `parse_function_call_and_execute(response)` | Parses a function call from the response and executes it. | `response` (str): Response containing the function call. | `result = agent.parse_function_call_and_execute(response)` | -| `llm_output_parser(response)` | Parses the output from the language model. | `response` (Any): Response from the LLM. | `parsed_response = agent.llm_output_parser(llm_output)` | -| `log_step_metadata(loop, task, response)` | Logs metadata for each step of the agent's execution. | `loop` (int): Current loop number.
`task` (str): Current task.
`response` (str): Agent's response. | `agent.log_step_metadata(1, "Analyze data", "Analysis complete")` | -| `to_dict()` | Converts the agent's attributes to a dictionary. | None | `agent_dict = agent.to_dict()` | -| `to_json(indent=4, *args, **kwargs)` | Converts the agent's attributes to a JSON string. | `indent` (int): Indentation for JSON.
`*args`, `**kwargs`: Additional arguments. | `agent_json = agent.to_json()` | -| `to_yaml(indent=4, *args, **kwargs)` | Converts the agent's attributes to a YAML string. | `indent` (int): Indentation for YAML.
`*args`, `**kwargs`: Additional arguments. | `agent_yaml = agent.to_yaml()` | -| `to_toml(*args, **kwargs)` | Converts the agent's attributes to a TOML string. | `*args`, `**kwargs`: Additional arguments. | `agent_toml = agent.to_toml()` | -| `model_dump_json()` | Saves the agent model to a JSON file in the workspace directory. | None | `agent.model_dump_json()` | -| `model_dump_yaml()` | Saves the agent model to a YAML file in the workspace directory. | None | `agent.model_dump_yaml()` | -| `log_agent_data()` | Logs the agent's data to an external API. | None | `agent.log_agent_data()` | -| `handle_tool_schema_ops()` | Handles operations related to tool schemas. | None | `agent.handle_tool_schema_ops()` | -| `call_llm(task, *args, **kwargs)` | Calls the appropriate method on the language model. | `task` (str): Task for the LLM.
`*args`, `**kwargs`: Additional arguments. | `response = agent.call_llm("Generate text")` | -| `handle_sop_ops()` | Handles operations related to standard operating procedures. | None | `agent.handle_sop_ops()` | -| `agent_output_type(responses)` | Processes and returns the agent's output based on the specified output type. | `responses` (list): List of responses. | `formatted_output = agent.agent_output_type(responses)` | -| `check_if_no_prompt_then_autogenerate(task)` | Checks if a system prompt is not set and auto-generates one if needed. | `task` (str): The task to use for generating a prompt. | `agent.check_if_no_prompt_then_autogenerate("Analyze data")` | -| `check_if_no_prompt_then_autogenerate(task)` | Checks if auto_generate_prompt is enabled and generates a prompt by combining agent name, description and system prompt | `task` (str, optional): Task to use as fallback | `agent.check_if_no_prompt_then_autogenerate("Analyze data")` | -| `handle_artifacts(response, output_path, extension)` | Handles saving artifacts from agent execution | `response` (str): Agent response
`output_path` (str): Output path
`extension` (str): File extension | `agent.handle_artifacts(response, "outputs/", ".txt")` | +conversation.add( + role="assistant", + content="Hi there!", + metadata={"response_time": "0.5s"}, + category="output" +) +# Get token usage statistics +token_stats = conversation.export_and_count_categories() +print(f"Input tokens: {token_stats['input_tokens']}") +print(f"Output tokens: {token_stats['output_tokens']}") +print(f"Total tokens: {token_stats['total_tokens']}") +# Display conversation +conversation.display_conversation() +``` -## Updated Run Method +### Using Supabase Backend with Environment Variables -Update the run method documentation to include new parameters: +```python +import os +from swarms.structs import Conversation -| Method | Description | Inputs | Usage Example | -|--------|-------------|--------|----------------| -| `run(task, img=None, is_last=False, device="cpu", device_id=0, all_cores=True, scheduled_run_date=None)` | Runs the agent with specified parameters | `task` (str): Task to run
`img` (str, optional): Image path
`is_last` (bool): If this is last task
`device` (str): Device to use
`device_id` (int): GPU ID
`all_cores` (bool): Use all CPU cores
`scheduled_run_date` (datetime, optional): Future run date | `agent.run("Analyze data", device="gpu", device_id=0)` | +# Using environment variables for secure configuration +os.environ["SUPABASE_URL"] = "https://your-project.supabase.co" +os.environ["SUPABASE_ANON_KEY"] = "your-anon-key" +conversation = Conversation( + name="supabase_chat", + backend="supabase", + system_prompt="You are a helpful assistant", + time_enabled=True, + token_count=True, + message_id_on=True, + table_name="production_conversations" # Custom table name +) +# Messages are automatically persisted to Supabase +conversation.add("user", "Hello!", metadata={"client_id": "user123"}) +conversation.add("assistant", "Hi there!", metadata={"model": "gpt-4"}) -## Getting Started +# Search functionality works with backend +results = conversation.search("Hello") +``` -To use the Swarm Agent, first install the required dependencies: +### Redis Backend with Advanced Configuration -```bash -pip3 install -U swarms +```python +from swarms.structs import Conversation + +# Redis with advanced configuration and persistence +conversation = Conversation( + name="redis_chat", + backend="redis", + redis_host="localhost", + redis_port=6379, + redis_password="secure_password", + use_embedded_redis=False, # Use external Redis + persist_redis=True, + auto_persist=True, + redis_data_dir="/path/to/redis/data", + token_count=True +) + +# Add structured messages +conversation.add( + role="user", + content={ + "message": "Process this data", + "data": {"key": "value"} + } +) + +# Batch add multiple messages +conversation.batch_add([ + {"role": "assistant", "content": "Processing..."}, + {"role": "system", "content": "Data processed successfully"} +]) ``` -Then, you can initialize and use the agent as follows: +### SQLite Backend with Custom Path and Export ```python +from swarms.structs import Conversation import os -from swarms import Agent -from swarm_models import OpenAIChat -from swarms.prompts.finance_agent_sys_prompt import FINANCIAL_AGENT_SYS_PROMPT -# Get the OpenAI API key from the environment variable -api_key = os.getenv("OPENAI_API_KEY") +# SQLite with custom database path and YAML export +conversation = Conversation( + name="sqlite_chat", + backend="sqlite", + db_path=os.path.expanduser("~/conversations.db"), + export_method="yaml", + system_prompt="You are a helpful assistant", + token_count=True +) -# Create an instance of the OpenAIChat class -model = OpenAIChat( - api_key=api_key, model_name="gpt-4-0613", temperature=0.1 +# Add messages and export +conversation.add("user", "Hello SQLite!") +conversation.add("assistant", "Hello from SQLite backend!") + +# Export conversation to YAML +conversation.export(force=True) # force=True overrides autosave setting +``` + +### Advanced Usage with Multi-Agent Systems + +```python +from swarms.structs import Agent, Conversation +from swarms.structs.multi_agent_exec import run_agents_concurrently +import os + +# Set up conversation with DuckDB backend for analytics +conversation = Conversation( + name="multi_agent_analytics", + backend="duckdb", + db_path="analytics.duckdb", + system_prompt="Multi-agent analytics session", + time_enabled=True, + token_count=True, + message_id_on=True ) -# Initialize the agent -agent = Agent( - agent_name="Financial-Analysis-Agent", - system_prompt=FINANCIAL_AGENT_SYS_PROMPT, - llm=model, - max_loops=1, - autosave=True, - dashboard=False, - verbose=True, - dynamic_temperature_enabled=True, - saved_state_path="finance_agent.json", - user_name="swarms_corp", - retry_attempts=1, - context_length=200000, - return_step_meta=False, - output_type="str", +# Create specialized agents +data_analyst = Agent( + agent_name="DataAnalyst", + system_prompt="You are a senior data analyst...", + model_name="gpt-4.1", + max_loops=1 ) -# Run the agent -response = agent.run( - "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?" +researcher = Agent( + agent_name="ResearchSpecialist", + system_prompt="You are a research specialist...", + model_name="gpt-4.1", + max_loops=1 ) -print(response) + +# Run agents with structured metadata +task = "Analyze the current state of AI in healthcare" +results = run_agents_concurrently( + agents=[data_analyst, researcher], + task=task +) + +# Store results with metadata +for result, agent in zip(results, [data_analyst, researcher]): + conversation.add( + content=result, + role=agent.agent_name, + metadata={ + "agent_type": agent.agent_name, + "model": agent.model_name, + "task": task + } + ) + +# Get analytics +token_usage = conversation.export_and_count_categories() +message_counts = conversation.count_messages_by_role() ``` -## Advanced Usage +### Error Handling and Fallbacks with Type Hints -### Tool Integration +```python +from typing import Optional, Dict, Any +from swarms.structs import Conversation -To integrate tools with the Swarm `Agent`, you can pass a list of callable functions with types and doc strings to the `tools` parameter when initializing the `Agent` instance. The agent will automatically convert these functions into an OpenAI function calling schema and make them available for use during task execution. +def initialize_conversation( + name: str, + backend: str, + config: Dict[str, Any] +) -> Optional[Conversation]: + """Initialize conversation with fallback handling.""" + try: + conversation = Conversation( + name=name, + backend=backend, + **config + ) + print(f"✅ {backend} backend initialized successfully") + return conversation + except ImportError as e: + print(f"❌ {backend} not available: {e}") + # Fallback to in-memory with same configuration + fallback_config = { + k: v for k, v in config.items() + if k not in ['supabase_url', 'supabase_key', 'redis_host'] + } + conversation = Conversation( + name=name, + backend="in-memory", + **fallback_config + ) + print("💡 Falling back to in-memory storage") + return conversation + except Exception as e: + print(f"❌ Unexpected error: {e}") + return None -## Requirements for a tool -- Function - - With types - - with doc strings +# Usage +config = { + "system_prompt": "You are a helpful assistant", + "time_enabled": True, + "token_count": True, + "supabase_url": "https://your-project.supabase.co", + "supabase_key": "your-key" +} + +conversation = initialize_conversation( + name="fallback_test", + backend="supabase", + config=config +) + +if conversation: + conversation.add("user", "Hello!") +``` + +### Loading and Managing Conversations with Modern Features ```python -from swarms import Agent -from swarm_models import OpenAIChat -import subprocess +from swarms.structs import Conversation +from typing import List, Dict +import os -def terminal(code: str): - """ - Run code in the terminal. +def manage_conversations(base_dir: str) -> List[Dict[str, str]]: + """Manage conversations with modern features.""" + + # List all saved conversations + conversations = Conversation.list_conversations( + conversations_dir=base_dir + ) + + # Print conversation stats + for conv in conversations: + print(f"ID: {conv['id']}") + print(f"Name: {conv['name']}") + print(f"Created: {conv['created_at']}") + print(f"Path: {conv['filepath']}") + print("---") + + # Load specific conversation + if conversations: + latest = conversations[0] # Most recent conversation + conversation = Conversation.load_conversation( + name=latest["name"], + conversations_dir=base_dir, + load_filepath=latest["filepath"] + ) + + # Get conversation statistics + stats = { + "messages": len(conversation.conversation_history), + "roles": conversation.count_messages_by_role(), + "tokens": conversation.export_and_count_categories() + } + + return stats + + return [] - Args: - code (str): The code to run in the terminal. +# Usage +base_dir = os.path.expanduser("~/conversation_data") +stats = manage_conversations(base_dir) +``` - Returns: - str: The output of the code. - """ - out = subprocess.run(code, shell=True, capture_output=True, text=True).stdout - return str(out) +### Backend Comparison and Selection Guide -# Initialize the agent with a tool -agent = Agent( - agent_name="Terminal-Agent", - llm=OpenAIChat(api_key=os.getenv("OPENAI_API_KEY")), - tools=[terminal], - system_prompt="You are an agent that can execute terminal commands. Use the tools provided to assist the user.", +```python +# In-memory: Fast, no persistence, good for testing +conv_memory = Conversation( + backend="in-memory", + token_count=True, + message_id_on=True ) -# Run the agent -response = agent.run("List the contents of the current directory") -print(response) +# SQLite: Local file-based persistence, good for single-user apps +conv_sqlite = Conversation( + backend="sqlite", + db_path="conversations.db", + token_count=True, + export_method="json" +) + +# Redis: High performance, good for real-time applications +conv_redis = Conversation( + backend="redis", + redis_host="localhost", + persist_redis=True, + token_count=True +) + +# Supabase: Cloud PostgreSQL, good for multi-user applications +conv_supabase = Conversation( + backend="supabase", + supabase_url=os.getenv("SUPABASE_URL"), + supabase_key=os.getenv("SUPABASE_ANON_KEY"), + token_count=True +) + +# DuckDB: Analytical workloads, good for data analysis +conv_duckdb = Conversation( + backend="duckdb", + db_path="analytics.duckdb", + token_count=True +) + +# Pulsar: Event streaming, good for distributed systems +conv_pulsar = Conversation( + backend="pulsar", + token_count=True +) ``` -### Long-term Memory Management +## Error Handling -The Swarm Agent supports integration with vector databases for long-term memory management. Here's an example using ChromaDB: +The conversation class provides graceful error handling: + +- **Missing Dependencies**: Clear error messages with installation instructions +- **Backend Failures**: Automatic fallback to in-memory storage +- **Network Issues**: Retry logic and connection management +- **Data Corruption**: Validation and recovery mechanisms + +Example error message: +``` +Backend 'supabase' dependencies not available. Install with: pip install supabase +``` + +## Migration Guide + +### From Provider to Backend ```python -from swarms import Agent -from swarm_models import Anthropic -from swarms_memory import ChromaDB +# Old way +conversation = Conversation(provider="in-memory") -# Initialize ChromaDB -chromadb = ChromaDB( - metric="cosine", - output_dir="finance_agent_rag", +# New way (recommended) +conversation = Conversation(backend="in-memory") + +# Both work, but backend takes precedence +conversation = Conversation( + provider="in-memory", # Ignored + backend="supabase" # Used ) +``` -# Initialize the agent with long-term memory -agent = Agent( +## Conclusion + +The `Conversation` class provides a comprehensive set of tools for managing conversations in Python applications with full backend flexibility. It supports various storage backends, lazy loading, token counting, caching, and multiple export/import formats. The class is designed to be flexible and extensible, making it suitable for a wide range of use cases from simple chat applications to complex conversational AI systems with persistent storage requirements. + +Choose the appropriate backend based on your needs: +- **in-memory**: Development and testing +- **sqlite**: Local applications and small-scale deployments +- **redis**: Distributed applications requiring high performance +- **supabase**: Cloud applications with real-time requirements +- **duckdb**: Analytics and data science workloads +- **pulsar**: Event-driven architectures and streaming applications + + +-------------------------------------------------- + +# File: swarms\structs\council_of_judges.md + +# CouncilAsAJudge + +The `CouncilAsAJudge` is a sophisticated evaluation system that employs multiple AI agents to assess model responses across various dimensions. It provides comprehensive, multi-dimensional analysis of AI model outputs through parallel evaluation and aggregation. + +## Overview + +The `CouncilAsAJudge` implements a council of specialized AI agents that evaluate different aspects of a model's response. Each agent focuses on a specific dimension of evaluation, and their findings are aggregated into a comprehensive report. + +```mermaid +graph TD + A[User Query] --> B[Base Agent] + B --> C[Model Response] + C --> D[CouncilAsAJudge] + + subgraph "Evaluation Dimensions" + D --> E1[Accuracy Agent] + D --> E2[Helpfulness Agent] + D --> E3[Harmlessness Agent] + D --> E4[Coherence Agent] + D --> E5[Conciseness Agent] + D --> E6[Instruction Adherence Agent] + end + + E1 --> F[Evaluation Aggregation] + E2 --> F + E3 --> F + E4 --> F + E5 --> F + E6 --> F + + F --> G[Comprehensive Report] + + style D fill:#f9f,stroke:#333,stroke-width:2px + style F fill:#bbf,stroke:#333,stroke-width:2px +``` + +## Key Features + +- Parallel evaluation across multiple dimensions +- Caching system for improved performance +- Dynamic model selection +- Comprehensive evaluation metrics +- Thread-safe execution +- Detailed technical analysis + +## Installation + +```bash +pip install swarms +``` + +## Basic Usage + +```python +from swarms import Agent, CouncilAsAJudge + +# Create a base agent +base_agent = Agent( agent_name="Financial-Analysis-Agent", - llm=Anthropic(anthropic_api_key=os.getenv("ANTHROPIC_API_KEY")), - long_term_memory=chromadb, - system_prompt="You are a financial analysis agent with access to long-term memory.", + system_prompt="You are a financial expert helping users understand and establish ROTH IRAs.", + model_name="claude-opus-4-20250514", + max_loops=1, ) -# Run the agent -response = agent.run("What are the components of a startup's stock incentive equity plan?") -print(response) +# Run the base agent +user_query = "How can I establish a ROTH IRA to buy stocks and get a tax break?" +model_output = base_agent.run(user_query) + +# Create and run the council +panel = CouncilAsAJudge() +results = panel.run(user_query, model_output) +print(results) ``` -### Interactive Mode +## Advanced Usage -To enable interactive mode, set the `interactive` parameter to `True` when initializing the `Agent`: +### Custom Model Configuration ```python -agent = Agent( - agent_name="Interactive-Agent", - llm=OpenAIChat(api_key=os.getenv("OPENAI_API_KEY")), - interactive=True, - system_prompt="You are an interactive agent. Engage in a conversation with the user.", +from swarms import CouncilAsAJudge + +# Initialize with custom model +council = CouncilAsAJudge( + model_name="anthropic/claude-3-sonnet-20240229", + output_type="all", + cache_size=256, + max_workers=4, + random_model_name=False +) +``` + +### Parallel Processing Configuration + +```python +from swarms import CouncilAsAJudge + +# Configure parallel processing +council = CouncilAsAJudge( + max_workers=8, # Custom number of worker threads + random_model_name=True # Enable dynamic model selection +) +``` + +## Evaluation Dimensions + +The council evaluates responses across six key dimensions: + +| Dimension | Evaluation Criteria | +|-----------|-------------------| +| **Accuracy** | • Factual correctness
• Source credibility
• Temporal consistency
• Technical accuracy | +| **Helpfulness** | • Problem-solving efficacy
• Solution feasibility
• Context inclusion
• Proactive addressing of follow-ups | +| **Harmlessness** | • Safety assessment
• Ethical considerations
• Age-appropriateness
• Content sensitivity | +| **Coherence** | • Structural integrity
• Logical flow
• Information hierarchy
• Transition effectiveness | +| **Conciseness** | • Communication efficiency
• Information density
• Redundancy elimination
• Focus maintenance | +| **Instruction Adherence** | • Requirement coverage
• Constraint compliance
• Format matching
• Scope appropriateness | + +## API Reference + +### CouncilAsAJudge + +```python +class CouncilAsAJudge: + def __init__( + self, + id: str = swarm_id(), + name: str = "CouncilAsAJudge", + description: str = "Evaluates the model's response across multiple dimensions", + model_name: str = "gpt-4o-mini", + output_type: str = "all", + cache_size: int = 128, + max_workers: int = None, + random_model_name: bool = True, + ) +``` + +#### Parameters + +- `id` (str): Unique identifier for the council +- `name` (str): Display name of the council +- `description` (str): Description of the council's purpose +- `model_name` (str): Name of the model to use for evaluations +- `output_type` (str): Type of output to return +- `cache_size` (int): Size of the LRU cache for prompts +- `max_workers` (int): Maximum number of worker threads +- `random_model_name` (bool): Whether to use random model selection + +### Methods + +#### run + +```python +def run(self, task: str, model_response: str) -> None +``` + +Evaluates a model response across all dimensions. + +##### Parameters + +- `task` (str): Original user prompt +- `model_response` (str): Model's response to evaluate + +##### Returns + +- Comprehensive evaluation report + +## Examples + +### Financial Analysis Example + +```python +from swarms import Agent, CouncilAsAJudge + +# Create financial analysis agent +financial_agent = Agent( + agent_name="Financial-Analysis-Agent", + system_prompt="You are a financial expert helping users understand and establish ROTH IRAs.", + model_name="claude-opus-4-20250514", + max_loops=1, +) + +# Run analysis +query = "How can I establish a ROTH IRA to buy stocks and get a tax break?" +response = financial_agent.run(query) + +# Evaluate response +council = CouncilAsAJudge() +evaluation = council.run(query, response) +print(evaluation) +``` + +### Technical Documentation Example + +```python +from swarms import Agent, CouncilAsAJudge + +# Create documentation agent +doc_agent = Agent( + agent_name="Documentation-Agent", + system_prompt="You are a technical documentation expert.", + model_name="gpt-4", + max_loops=1, +) + +# Generate documentation +query = "Explain how to implement a REST API using FastAPI" +response = doc_agent.run(query) + +# Evaluate documentation quality +council = CouncilAsAJudge( + model_name="anthropic/claude-3-sonnet-20240229", + output_type="all" +) +evaluation = council.run(query, response) +print(evaluation) +``` + +## Best Practices + +### Model Selection + +!!! tip "Model Selection Best Practices" + - Choose appropriate models for your use case + - Consider using random model selection for diverse evaluations + - Match model capabilities to evaluation requirements + +### Performance Optimization + +!!! note "Performance Tips" + - Adjust cache size based on memory constraints + - Configure worker threads based on CPU cores + - Monitor memory usage with large responses + +### Error Handling + +!!! warning "Error Handling Guidelines" + - Implement proper exception handling + - Monitor evaluation failures + - Log evaluation results for analysis + +### Resource Management + +!!! info "Resource Management" + - Clean up resources after evaluation + - Monitor thread pool usage + - Implement proper shutdown procedures + +## Troubleshooting + +### Memory Issues + +!!! danger "Memory Problems" + If you encounter memory-related problems: + + - Reduce cache size + - Decrease number of worker threads + - Process smaller chunks of text + +### Performance Problems + +!!! warning "Performance Issues" + To improve performance: + + - Increase cache size + - Adjust worker thread count + - Use more efficient models + +### Evaluation Failures + +!!! danger "Evaluation Issues" + When evaluations fail: + + - Check model availability + - Verify input format + - Monitor error logs + +## Contributing + +!!! success "Contributing" + Contributions are welcome! Please feel free to submit a Pull Request. + +## License + +!!! info "License" + This project is licensed under the MIT License - see the LICENSE file for details. + +-------------------------------------------------- + +# File: swarms\structs\create_new_swarm.md + +# How to Add a New Swarm Class + +This guide provides comprehensive step-by-step instructions for developers to create and add a new swarm. It emphasizes the importance of adhering to best practices, using proper type hints, and documenting code thoroughly to ensure maintainability, scalability, and clarity in your implementations. + +## Overview + +A Swarm class enables developers to manage and coordinate multiple agents working together to accomplish complex tasks efficiently. Each Swarm must: + +- Contain a `run(task: str, img: str, *args, **kwargs)` method, which serves as the primary execution method for tasks. +- Include `name`, `description`, and `agents` parameters. +- Ensure `agents` is a list of callables, with each callable adhering to specific requirements for dynamic agent behavior. +- Follow type-hinting and documentation best practices to maintain code clarity and reliability. + +Each Agent within the swarm must: + +- Contain `agent_name`, `system_prompt`, and a `run` method. +- Follow similar type hinting and documentation standards to ensure consistency and readability. + +By adhering to these requirements, you can create robust, reusable, and modular swarms that streamline task management and enhance collaborative functionality. Developers are also encouraged to contribute their swarms back to the open-source community by submitting a pull request to the Swarms repository at [https://github.com/kyegomez/swarms](https://github.com/kyegomez/swarms). + +--- + +## Creating a Swarm Class + +Below is a detailed template for creating a Swarm class. Ensure that all elements are documented and clearly defined: + +```python +from typing import Callable, Any, List + +class MySwarm: + """ + A custom swarm class to manage and execute tasks with multiple agents. + + Attributes: + name (str): The name of the swarm. + description (str): A brief description of the swarm's purpose. + agents (List[Callable]): A list of callables representing the agents to be utilized. + """ + + def __init__(self, name: str, description: str, agents: List[Callable]): + """ + Initialize the Swarm with its name, description, and agents. + + Args: + name (str): The name of the swarm. + description (str): A description of the swarm. + agents (List[Callable]): A list of callables that provide the agents for the swarm. + """ + self.name = name + self.description = description + self.agents = agents + + def run(self, task: str, img: str, *args: Any, **kwargs: Any) -> Any: + """ + Execute a task using the swarm and its agents. + + Args: + task (str): The task description. + img (str): The image input. + *args: Additional positional arguments for customization. + **kwargs: Additional keyword arguments for fine-tuning behavior. + + Returns: + Any: The result of the task execution, aggregated from all agents. + """ + results = [] + for agent in self.agents: + result = agent.run(task, img, *args, **kwargs) + results.append(result) + return results +``` + +This Swarm class serves as the main orchestrator for coordinating agents and running tasks dynamically and flexibly. + +--- + +## Creating an Agent Class + +Each agent must follow a well-defined structure to ensure compatibility with the swarm. Below is an example of an agent class: + +```python +class Agent: + """ + A single agent class to handle specific tasks assigned by the swarm. + + Attributes: + agent_name (str): The name of the agent. + system_prompt (str): The system prompt guiding the agent's behavior and purpose. + """ + + def __init__(self, agent_name: str, system_prompt: str): + """ + Initialize the agent with its name and system prompt. + + Args: + agent_name (str): The name of the agent. + system_prompt (str): The guiding prompt for the agent. + """ + self.agent_name = agent_name + self.system_prompt = system_prompt + + def run(self, task: str, img: str, *args: Any, **kwargs: Any) -> Any: + """ + Execute a specific task assigned to the agent. + + Args: + task (str): The task description. + img (str): The image input for processing. + *args: Additional positional arguments for task details. + **kwargs: Additional keyword arguments for extended functionality. + + Returns: + Any: The result of the task execution, which can be customized. + """ + # Example implementation (to be customized by developer) + return f"Agent {self.agent_name} executed task: {task}" +``` + +This structure ensures that each agent can independently handle tasks and integrate seamlessly into a swarm. + +--- + +## Adding Your Swarm to a Project + +### Step 1: Define Your Agents +Create one or more instances of the `Agent` class to serve as components of your swarm. For example: + +```python +def create_agents(): + return [ + Agent(agent_name="Agent1", system_prompt="Analyze the image and summarize results."), + Agent(agent_name="Agent2", system_prompt="Detect objects and highlight key features."), + ] +``` + +### Step 2: Implement Your Swarm +Create an instance of your Swarm class, defining its name, description, and associated agents: + +```python +my_swarm = MySwarm( + name="Image Analysis Swarm", + description="A swarm designed to analyze images and perform a range of related tasks.", + agents=create_agents() +) +``` + +### Step 3: Execute Tasks +Call the `run` method of your swarm, passing in the required parameters for execution: + +```python +results = my_swarm.run(task="Analyze image content", img="path/to/image.jpg") +print(results) +``` + +This simple flow allows you to dynamically utilize agents for diverse operations and ensures efficient task execution. + +--- + +## Best Practices + +To ensure your swarm implementation is efficient and maintainable, follow these best practices: + +1. **Type Annotations:** + Use precise type hints for parameters and return types to improve code readability and support static analysis tools. + +2. **Comprehensive Documentation:** + Include clear and detailed docstrings for all classes, methods, and attributes to ensure your code is understandable. + +3. **Thorough Testing:** + Test your swarm and agents with various tasks to verify correctness and identify potential edge cases. + +4. **Modular Design:** + Keep your swarm and agent logic modular, enabling reuse and easy extensions for future enhancements. + +5. **Error Handling:** + Implement robust error handling in the `run` methods to gracefully manage unexpected inputs or issues during execution. + +6. **Code Review:** + Regularly review and refactor your code to align with the latest best practices and maintain high quality. + +7. **Scalability:** + Design your swarm with scalability in mind, ensuring it can handle a large number of agents and complex tasks. + +8. **Logging and Monitoring:** + Include comprehensive logging to track task execution and monitor performance, enabling easier debugging and optimization. + +9. **Open-Source Contributions:** + Consider contributing your swarm to the Swarms repository to benefit the community. Submit a pull request at [https://github.com/kyegomez/swarms](https://github.com/kyegomez/swarms). + +--- + +## Example Output + +Given the implementation above, executing a task might produce output such as: + +```plaintext +[ + "Agent Agent1 executed task: Analyze image content", + "Agent Agent2 executed task: Analyze image content" +] +``` + +The modular design ensures that each agent contributes to the overall functionality of the swarm, allowing seamless scalability and dynamic task management. + +--- + +## Conclusion + +By following these guidelines, you can create swarms that are powerful, flexible, and maintainable. Leveraging the provided templates and best practices enables you to build efficient multi-agent systems capable of handling diverse and complex tasks. Proper structuring, thorough testing, and adherence to best practices will ensure your swarm integrates effectively into any project, delivering robust and reliable performance. Furthermore, maintaining clear documentation and emphasizing modularity will help your implementation adapt to future needs and use cases. Empower your projects with a well-designed swarm architecture today, and consider submitting your swarm to the open-source community to foster collaboration and innovation. + + + +-------------------------------------------------- + +# File: swarms\structs\cron_job.md + +# CronJob + +A wrapper class that turns any callable (including Swarms agents) into a scheduled cron job. This class provides functionality to schedule and run tasks at specified intervals using the schedule library with cron-style scheduling. + +## Overview + +The CronJob class allows you to: + +- Schedule any callable or Swarms Agent to run at specified intervals + +- Support for seconds, minutes, and hours intervals + +- Run tasks in a separate thread + +- Handle graceful start/stop of scheduled jobs + +- Manage multiple concurrent scheduled jobs + +## Architecture + +```mermaid +graph TD + A[CronJob] --> B[Initialize] + B --> C[Parse Interval] + C --> D[Schedule Task] + D --> E[Run Job] + E --> F[Execute Task] + F --> G{Is Agent?} + G -->|Yes| H[Run Agent] + G -->|No| I[Run Callable] + H --> J[Handle Result] + I --> J + J --> K[Sleep] + K --> E +``` + +## Class Reference + +### Constructor + +```python +def __init__( + agent: Optional[Union[Agent, Callable]] = None, + interval: Optional[str] = None, + job_id: Optional[str] = None +) +``` + +| Parameter | Type | Description | Required | +|-----------|------|-------------|-----------| +| agent | Agent or Callable | The Swarms Agent instance or callable to be scheduled | No | +| interval | str | The interval string (e.g., "5seconds", "10minutes", "1hour") | No | +| job_id | str | Unique identifier for the job. If not provided, one will be generated | No | + +### Methods + +#### run + +```python +def run(task: str, **kwargs) +``` + +| Parameter | Type | Description | Required | +|-----------|------|-------------|-----------| +| task | str | The task string to be executed by the agent | Yes | +| **kwargs | dict | Additional parameters to pass to the agent's run method | No | + +#### __call__ + +```python +def __call__(task: str, **kwargs) +``` + +| Parameter | Type | Description | Required | +|-----------|------|-------------|-----------| +| task | str | The task string to be executed | Yes | +| **kwargs | dict | Additional parameters to pass to the agent's run method | No | + +## Examples + +### Basic Usage with Swarms Agent + +```python +from swarms import Agent, CronJob +from loguru import logger + +# Initialize the agent +agent = Agent( + agent_name="Quantitative-Trading-Agent", + agent_description="Advanced quantitative trading and algorithmic analysis agent", + system_prompt="""You are an expert quantitative trading agent...""", + max_loops=1, + model_name="gpt-4.1", + dynamic_temperature_enabled=True, + output_type="str-all-except-first", + streaming_on=True, + print_on=True, + telemetry_enable=False, +) + +# Create and run a cron job every 10 seconds +logger.info("Starting example cron job") +cron_job = CronJob(agent=agent, interval="10seconds") +cron_job.run( + task="What are the best top 3 etfs for gold coverage?" +) +``` + +### Using with a Custom Function + +```python +def custom_task(task: str): + print(f"Executing task: {task}") + return "Task completed" + +# Create a cron job with a custom function +cron_job = CronJob( + agent=custom_task, + interval="5minutes", + job_id="custom_task_job" +) +cron_job.run("Perform analysis") +``` + +## Conclusion + +The CronJob class provides a powerful way to schedule and automate tasks using Swarms Agents or custom functions. Key benefits include: + +- Easy integration with Swarms Agents + +- Flexible interval scheduling + +- Thread-safe execution + +- Graceful error handling + +- Simple API for task scheduling + +- Support for both agent and callable-based tasks + +-------------------------------------------------- + +# File: swarms\structs\custom_swarm.md + +# Building Custom Swarms: A Comprehensive Guide for Swarm Engineers + +## Introduction + +As artificial intelligence and machine learning continue to grow in complexity and applicability, building systems that can harness multiple agents to solve complex tasks becomes more critical. Swarm engineering enables AI agents to collaborate and solve problems autonomously in diverse fields such as finance, marketing, operations, and even creative industries. + +This comprehensive guide covers how to build a custom swarm system that integrates multiple agents into a cohesive system capable of solving tasks collaboratively. We'll cover everything from basic swarm structure to advanced features like conversation management, logging, error handling, and scalability. + +By the end of this guide, you will have a complete understanding of: + +- What swarms are and how they can be built + +- How to create agents and integrate them into swarms + +- How to implement proper conversation management for message storage + +- Best practices for error handling, logging, and optimization + +- How to make swarms scalable and production-ready + + +--- + +## Overview of Swarm Architecture + +A **Swarm** refers to a collection of agents that collaborate to solve a problem. Each agent in the swarm performs part of the task, either independently or by communicating with other agents. Swarms are ideal for: + +- **Scalability**: You can add or remove agents dynamically based on the task's complexity + +- **Flexibility**: Each agent can be designed to specialize in different parts of the problem, offering modularity + +- **Autonomy**: Agents in a swarm can operate autonomously, reducing the need for constant supervision + +- **Conversation Management**: All interactions are tracked and stored for analysis and continuity + + +--- + +## Core Requirements for Swarm Classes + +Every Swarm class must adhere to these fundamental requirements: + +### Required Methods and Attributes + +- **`run(task: str, img: str, *args, **kwargs)` method**: The primary execution method for tasks + +- **`name`**: A descriptive name for the swarm + +- **`description`**: A clear description of the swarm's purpose + +- **`agents`**: A list of callables representing the agents + +- **`conversation`**: A conversation structure for message storage and history management + + +### Required Agent Structure + +Each Agent within the swarm must contain: + +- **`agent_name`**: Unique identifier for the agent + +- **`system_prompt`**: Instructions that guide the agent's behavior + +- **`run` method**: Method to execute tasks assigned to the agent + + +--- + +## Setting Up the Foundation + +### Required Dependencies + +```python +from typing import List, Union, Any, Optional, Callable +from loguru import logger +from swarms.structs.base_swarm import BaseSwarm +from swarms.structs.conversation import Conversation +from swarms.structs.agent import Agent +import concurrent.futures +import os +``` + +### Custom Exception Handling + +```python +class SwarmExecutionError(Exception): + """Custom exception for handling swarm execution errors.""" + pass + +class AgentValidationError(Exception): + """Custom exception for agent validation errors.""" + pass +``` + +--- + +## Building the Custom Swarm Class + +### Basic Swarm Structure + +```python +class CustomSwarm(BaseSwarm): + """ + A custom swarm class to manage and execute tasks with multiple agents. + + This swarm integrates conversation management for tracking all agent interactions, + provides error handling, and supports both sequential and concurrent execution. + + Attributes: + name (str): The name of the swarm. + description (str): A brief description of the swarm's purpose. + agents (List[Callable]): A list of callables representing the agents. + conversation (Conversation): Conversation management for message storage. + max_workers (int): Maximum number of concurrent workers for parallel execution. + autosave_conversation (bool): Whether to automatically save conversation history. + """ + + def __init__( + self, + name: str, + description: str, + agents: List[Callable], + max_workers: int = 4, + autosave_conversation: bool = True, + conversation_config: Optional[dict] = None, + ): + """ + Initialize the CustomSwarm with its name, description, and agents. + + Args: + name (str): The name of the swarm. + description (str): A description of the swarm. + agents (List[Callable]): A list of callables that provide the agents for the swarm. + max_workers (int): Maximum number of concurrent workers. + autosave_conversation (bool): Whether to automatically save conversations. + conversation_config (dict): Configuration for conversation management. + """ + super().__init__(name=name, description=description, agents=agents) + self.name = name + self.description = description + self.agents = agents + self.max_workers = max_workers + self.autosave_conversation = autosave_conversation + + # Initialize conversation management + # See: https://docs.swarms.world/swarms/structs/conversation/ + conversation_config = conversation_config or {} + self.conversation = Conversation( + id=f"swarm_{name}_{int(time.time())}", + name=f"{name}_conversation", + autosave=autosave_conversation, + save_enabled=True, + time_enabled=True, + **conversation_config + ) + + # Validate agents and log initialization + self.validate_agents() + logger.info(f"🚀 CustomSwarm '{self.name}' initialized with {len(self.agents)} agents") + + # Add swarm initialization to conversation history + self.conversation.add( + role="System", + content=f"Swarm '{self.name}' initialized with {len(self.agents)} agents: {[getattr(agent, 'agent_name', 'Unknown') for agent in self.agents]}" + ) + + def validate_agents(self): + """ + Validates that each agent has the required methods and attributes. + + Raises: + AgentValidationError: If any agent fails validation. + """ + for i, agent in enumerate(self.agents): + # Check for required run method + if not hasattr(agent, 'run'): + raise AgentValidationError(f"Agent at index {i} does not have a 'run' method.") + + # Check for agent_name attribute + if not hasattr(agent, 'agent_name'): + logger.warning(f"Agent at index {i} does not have 'agent_name' attribute. Using 'Agent_{i}'") + agent.agent_name = f"Agent_{i}" + + logger.info(f"✅ Agent '{agent.agent_name}' validated successfully.") + + def run(self, task: str, img: str = None, *args: Any, **kwargs: Any) -> Any: + """ + Execute a task using the swarm and its agents with conversation tracking. + + Args: + task (str): The task description. + img (str): The image input (optional). + *args: Additional positional arguments for customization. + **kwargs: Additional keyword arguments for fine-tuning behavior. + + Returns: + Any: The result of the task execution, aggregated from all agents. + """ + logger.info(f"🎯 Running task '{task}' across {len(self.agents)} agents in swarm '{self.name}'") + + # Add task to conversation history + self.conversation.add( + role="User", + content=f"Task: {task}" + (f" | Image: {img}" if img else ""), + category="input" + ) + + try: + # Execute task across all agents + results = self._execute_agents(task, img, *args, **kwargs) + + # Add results to conversation + self.conversation.add( + role="Swarm", + content=f"Task completed successfully. Processed by {len(results)} agents.", + category="output" + ) + + logger.success(f"✅ Task completed successfully by swarm '{self.name}'") + return results + + except Exception as e: + error_msg = f"❌ Task execution failed in swarm '{self.name}': {str(e)}" + logger.error(error_msg) + + # Add error to conversation + self.conversation.add( + role="System", + content=f"Error: {error_msg}", + category="error" + ) + + raise SwarmExecutionError(error_msg) + + def _execute_agents(self, task: str, img: str = None, *args, **kwargs) -> List[Any]: + """ + Execute the task across all agents with proper conversation tracking. + + Args: + task (str): The task to execute. + img (str): Optional image input. + + Returns: + List[Any]: Results from all agents. + """ + results = [] + + for agent in self.agents: + try: + # Execute agent task + result = agent.run(task, img, *args, **kwargs) + results.append(result) + + # Add agent response to conversation + self.conversation.add( + role=agent.agent_name, + content=result, + category="agent_output" + ) + + logger.info(f"✅ Agent '{agent.agent_name}' completed task successfully") + + except Exception as e: + error_msg = f"Agent '{agent.agent_name}' failed: {str(e)}" + logger.error(error_msg) + + # Add agent error to conversation + self.conversation.add( + role=agent.agent_name, + content=f"Error: {error_msg}", + category="agent_error" + ) + + # Continue with other agents but log the failure + results.append(f"FAILED: {error_msg}") + + return results +``` + +### Enhanced Swarm with Concurrent Execution + +```python + def run_concurrent(self, task: str, img: str = None, *args: Any, **kwargs: Any) -> List[Any]: + """ + Execute a task using concurrent execution for better performance. + + Args: + task (str): The task description. + img (str): The image input (optional). + *args: Additional positional arguments. + **kwargs: Additional keyword arguments. + + Returns: + List[Any]: Results from all agents executed concurrently. + """ + logger.info(f"🚀 Running task concurrently across {len(self.agents)} agents") + + # Add task to conversation + self.conversation.add( + role="User", + content=f"Concurrent Task: {task}" + (f" | Image: {img}" if img else ""), + category="input" + ) + + results = [] + + with concurrent.futures.ThreadPoolExecutor(max_workers=self.max_workers) as executor: + # Submit all agent tasks + future_to_agent = { + executor.submit(self._run_single_agent, agent, task, img, *args, **kwargs): agent + for agent in self.agents + } + + # Collect results as they complete + for future in concurrent.futures.as_completed(future_to_agent): + agent = future_to_agent[future] + try: + result = future.result() + results.append(result) + + # Add to conversation + self.conversation.add( + role=agent.agent_name, + content=result, + category="agent_output" + ) + + except Exception as e: + error_msg = f"Concurrent execution failed for agent '{agent.agent_name}': {str(e)}" + logger.error(error_msg) + results.append(f"FAILED: {error_msg}") + + # Add error to conversation + self.conversation.add( + role=agent.agent_name, + content=f"Error: {error_msg}", + category="agent_error" + ) + + # Add completion summary + self.conversation.add( + role="Swarm", + content=f"Concurrent task completed. {len(results)} agents processed.", + category="output" + ) + + return results + + def _run_single_agent(self, agent: Callable, task: str, img: str = None, *args, **kwargs) -> Any: + """ + Execute a single agent with error handling. + + Args: + agent: The agent to execute. + task (str): The task to execute. + img (str): Optional image input. + + Returns: + Any: The agent's result. + """ + try: + return agent.run(task, img, *args, **kwargs) + except Exception as e: + logger.error(f"Agent '{getattr(agent, 'agent_name', 'Unknown')}' execution failed: {str(e)}") + raise +``` + +### Advanced Features + +```python + def run_with_retries(self, task: str, img: str = None, retries: int = 3, *args, **kwargs) -> List[Any]: + """ + Execute a task with retry logic for failed agents. + + Args: + task (str): The task to execute. + img (str): Optional image input. + retries (int): Number of retries for failed agents. + + Returns: + List[Any]: Results from all agents with retry attempts. + """ + logger.info(f"🔄 Running task with {retries} retries per agent") + + # Add task to conversation + self.conversation.add( + role="User", + content=f"Task with retries ({retries}): {task}", + category="input" + ) + + results = [] + + for agent in self.agents: + attempt = 0 + success = False + + while attempt <= retries and not success: + try: + result = agent.run(task, img, *args, **kwargs) + results.append(result) + success = True + + # Add successful result to conversation + self.conversation.add( + role=agent.agent_name, + content=result, + category="agent_output" + ) + + if attempt > 0: + logger.success(f"✅ Agent '{agent.agent_name}' succeeded on attempt {attempt + 1}") + + except Exception as e: + attempt += 1 + error_msg = f"Agent '{agent.agent_name}' failed on attempt {attempt}: {str(e)}" + logger.warning(error_msg) + + # Add retry attempt to conversation + self.conversation.add( + role=agent.agent_name, + content=f"Retry attempt {attempt}: {error_msg}", + category="agent_retry" + ) + + if attempt > retries: + final_error = f"Agent '{agent.agent_name}' exhausted all {retries} retries" + logger.error(final_error) + results.append(f"FAILED: {final_error}") + + # Add final failure to conversation + self.conversation.add( + role=agent.agent_name, + content=final_error, + category="agent_error" + ) + + return results + + def get_conversation_summary(self) -> dict: + """ + Get a summary of the conversation history and agent performance. + + Returns: + dict: Summary of conversation statistics and agent performance. + """ + # Get conversation statistics + message_counts = self.conversation.count_messages_by_role() + + # Count categories + category_counts = {} + for message in self.conversation.conversation_history: + category = message.get("category", "uncategorized") + category_counts[category] = category_counts.get(category, 0) + 1 + + # Get token counts if available + token_summary = self.conversation.export_and_count_categories() + + return { + "swarm_name": self.name, + "total_messages": len(self.conversation.conversation_history), + "messages_by_role": message_counts, + "messages_by_category": category_counts, + "token_summary": token_summary, + "conversation_id": self.conversation.id, + } + + def export_conversation(self, filepath: str = None) -> str: + """ + Export the conversation history to a file. + + Args: + filepath (str): Optional custom filepath for export. + + Returns: + str: The filepath where the conversation was saved. + """ + if filepath is None: + filepath = f"conversations/{self.name}_{self.conversation.id}.json" + + self.conversation.export_conversation(filepath) + logger.info(f"📄 Conversation exported to: {filepath}") + return filepath + + def display_conversation(self, detailed: bool = True): + """ + Display the conversation history in a formatted way. + + Args: + detailed (bool): Whether to show detailed information. + """ + logger.info(f"💬 Displaying conversation for swarm: {self.name}") + self.conversation.display_conversation(detailed=detailed) +``` + +--- + +## Creating Agents for Your Swarm + +### Basic Agent Structure + +```python +class CustomAgent: + """ + A custom agent class that integrates with the swarm conversation system. + + Attributes: + agent_name (str): The name of the agent. + system_prompt (str): The system prompt guiding the agent's behavior. + conversation (Optional[Conversation]): Shared conversation for context. + """ + + def __init__( + self, + agent_name: str, + system_prompt: str, + conversation: Optional[Conversation] = None + ): + """ + Initialize the agent with its name and system prompt. + + Args: + agent_name (str): The name of the agent. + system_prompt (str): The guiding prompt for the agent. + conversation (Optional[Conversation]): Shared conversation context. + """ + self.agent_name = agent_name + self.system_prompt = system_prompt + self.conversation = conversation + + def run(self, task: str, img: str = None, *args: Any, **kwargs: Any) -> Any: + """ + Execute a specific task assigned to the agent. + + Args: + task (str): The task description. + img (str): The image input for processing. + *args: Additional positional arguments. + **kwargs: Additional keyword arguments. + + Returns: + Any: The result of the task execution. + """ + # Add context from shared conversation if available + context = "" + if self.conversation: + context = f"Previous context: {self.conversation.get_last_message_as_string()}\n\n" + + # Process the task (implement your custom logic here) + result = f"Agent {self.agent_name} processed: {context}{task}" + + logger.info(f"🤖 Agent '{self.agent_name}' completed task") + return result +``` + +### Using Swarms Framework Agents + +You can also use the built-in Agent class from the Swarms framework: + +```python +from swarms.structs.agent import Agent + +def create_financial_agent() -> Agent: + """Create a financial analysis agent.""" + return Agent( + agent_name="FinancialAnalyst", + system_prompt="You are a financial analyst specializing in market analysis and risk assessment.", + model_name="gpt-4o-mini", + max_loops=1, + ) + +def create_marketing_agent() -> Agent: + """Create a marketing analysis agent.""" + return Agent( + agent_name="MarketingSpecialist", + system_prompt="You are a marketing specialist focused on campaign analysis and customer insights.", + model_name="gpt-4o-mini", + max_loops=1, + ) +``` + +--- + +## Complete Implementation Example + +### Setting Up Your Swarm + +```python +import time +from typing import List + +def create_multi_domain_swarm() -> CustomSwarm: + """ + Create a comprehensive multi-domain analysis swarm. + + Returns: + CustomSwarm: A configured swarm with multiple specialized agents. + """ + # Create agents + agents = [ + create_financial_agent(), + create_marketing_agent(), + Agent( + agent_name="OperationsAnalyst", + system_prompt="You are an operations analyst specializing in process optimization and efficiency.", + model_name="gpt-4o-mini", + max_loops=1, + ), + ] + + # Configure conversation settings + conversation_config = { + "backend": "sqlite", # Use SQLite for persistent storage + "db_path": f"conversations/swarm_conversations.db", + "time_enabled": True, + "token_count": True, + } + + # Create the swarm + swarm = CustomSwarm( + name="MultiDomainAnalysisSwarm", + description="A comprehensive swarm for financial, marketing, and operations analysis", + agents=agents, + max_workers=3, + autosave_conversation=True, + conversation_config=conversation_config, + ) + + return swarm + +# Usage example +if __name__ == "__main__": + # Create and initialize the swarm + swarm = create_multi_domain_swarm() + + # Execute a complex analysis task + task = """ + Analyze the Q3 2024 performance data for our company: + - Revenue: $2.5M (up 15% from Q2) + + - Customer acquisition: 1,200 new customers + + - Marketing spend: $150K + + - Operational costs: $800K + + + Provide insights from financial, marketing, and operations perspectives. + """ + + # Run the analysis + results = swarm.run(task) + + # Display results + print("\n" + "="*50) + print("SWARM ANALYSIS RESULTS") + print("="*50) + + for i, result in enumerate(results): + agent_name = swarm.agents[i].agent_name + print(f"\n🤖 {agent_name}:") + print(f"📊 {result}") + + # Get conversation summary + summary = swarm.get_conversation_summary() + print(f"\n📈 Conversation Summary:") + print(f" Total messages: {summary['total_messages']}") + print(f" Total tokens: {summary['token_summary']['total_tokens']}") + + # Export conversation for later analysis + export_path = swarm.export_conversation() + print(f"💾 Conversation saved to: {export_path}") +``` + +### Advanced Usage with Concurrent Execution + +```python +def run_batch_analysis(): + """Example of running multiple tasks concurrently.""" + swarm = create_multi_domain_swarm() + + tasks = [ + "Analyze Q1 financial performance", + "Evaluate marketing campaign effectiveness", + "Review operational efficiency metrics", + "Assess customer satisfaction trends", + ] + + # Process all tasks concurrently + all_results = [] + for task in tasks: + results = swarm.run_concurrent(task) + all_results.append({"task": task, "results": results}) + + return all_results +``` + +--- + +## Conversation Management Integration + +The swarm uses the Swarms framework's [Conversation structure](../conversation/) for comprehensive message storage and management. This provides: + +### Key Features + +- **Persistent Storage**: Multiple backend options (SQLite, Redis, Supabase, etc.) + +- **Message Categorization**: Organize messages by type (input, output, error, etc.) + +- **Token Tracking**: Monitor token usage across conversations + +- **Export/Import**: Save and load conversation histories + +- **Search Capabilities**: Find specific messages or content + + +### Conversation Configuration Options + +```python +conversation_config = { + # Backend storage options + "backend": "sqlite", # or "redis", "supabase", "duckdb", "in-memory" + + # File-based storage + "db_path": "conversations/swarm_data.db", + + # Redis configuration (if using Redis backend) + "redis_host": "localhost", + "redis_port": 6379, + + # Features + "time_enabled": True, # Add timestamps to messages + "token_count": True, # Track token usage + "autosave": True, # Automatically save conversations + "save_enabled": True, # Enable saving functionality +} +``` + +### Accessing Conversation Data + +```python +# Get conversation history +history = swarm.conversation.return_history_as_string() + +# Search for specific content +financial_messages = swarm.conversation.search("financial") + +# Export conversation data +swarm.conversation.export_conversation("analysis_session.json") + +# Get conversation statistics +stats = swarm.conversation.count_messages_by_role() +token_usage = swarm.conversation.export_and_count_categories() +``` + +For complete documentation on conversation management, see the [Conversation Structure Documentation](../conversation/). + + +--- + +## Conclusion + +Building custom swarms with proper conversation management enables you to create powerful, scalable, and maintainable multi-agent systems. The integration with the Swarms framework's conversation structure provides: + +- **Complete audit trail** of all agent interactions + +- **Persistent storage** options for different deployment scenarios + +- **Performance monitoring** through token and message tracking + +- **Easy debugging** with searchable conversation history + +- **Scalable architecture** that grows with your needs + + +By following the patterns and best practices outlined in this guide, you can create robust swarms that handle complex tasks efficiently while maintaining full visibility into their operations. + +### Key Takeaways + +1. **Always implement conversation management** for tracking and auditing +2. **Use proper error handling and retries** for production resilience +3. **Implement monitoring and logging** for observability +4. **Design for scalability** with concurrent execution patterns +5. **Test thoroughly** with unit tests and integration tests +6. **Configure appropriately** for your deployment environment + +For more advanced patterns and examples, explore the [Swarms Examples](../../examples/) and consider contributing your custom swarms back to the community by submitting a pull request to the [Swarms repository](https://github.com/kyegomez/swarms). + +--- + +## Additional Resources + +- [Conversation Structure Documentation](../conversation/) - Complete guide to conversation management + +- [Agent Documentation](../../agents/) - Learn about creating and configuring agents + +- [Multi-Agent Architectures](../overview/) - Explore other swarm patterns and architectures + +- [Examples Repository](../../examples/) - Real-world swarm implementations + +- [Swarms Framework GitHub](https://github.com/kyegomez/swarms) - Source code and contributions + + +-------------------------------------------------- + +# File: swarms\structs\deep_research_swarm.md + +# Deep Research Swarm + +!!! abstract "Overview" + The Deep Research Swarm is a powerful, production-grade research system that conducts comprehensive analysis across multiple domains using parallel processing and advanced AI agents. + + Key Features: + + - Parallel search processing + + - Multi-agent research coordination + + - Advanced information synthesis + + - Automated query generation + + - Concurrent task execution + +## Getting Started + +!!! tip "Quick Installation" + ```bash + pip install swarms + ``` + +=== "Basic Usage" + ```python + from swarms.structs import DeepResearchSwarm + + # Initialize the swarm + swarm = DeepResearchSwarm( + name="MyResearchSwarm", + output_type="json", + max_loops=1 + ) + + # Run a single research task + results = swarm.run("What are the latest developments in quantum computing?") + ``` + +=== "Batch Processing" + ```python + # Run multiple research tasks in parallel + tasks = [ + "What are the environmental impacts of electric vehicles?", + "How is AI being used in drug discovery?", + ] + batch_results = swarm.batched_run(tasks) + ``` + +## Configuration + +!!! info "Constructor Arguments" + | Parameter | Type | Default | Description | + |-----------|------|---------|-------------| + | `name` | str | "DeepResearchSwarm" | Name identifier for the swarm | + | `description` | str | "A swarm that conducts..." | Description of the swarm's purpose | + | `research_agent` | Agent | research_agent | Custom research agent instance | + | `max_loops` | int | 1 | Maximum number of research iterations | + | `nice_print` | bool | True | Enable formatted console output | + | `output_type` | str | "json" | Output format ("json" or "string") | + | `max_workers` | int | CPU_COUNT * 2 | Maximum concurrent threads | + | `token_count` | bool | False | Enable token counting | + | `research_model_name` | str | "gpt-4o-mini" | Model to use for research | + +## Core Methods + +### Run +!!! example "Single Task Execution" + ```python + results = swarm.run("What are the latest breakthroughs in fusion energy?") + ``` + +### Batched Run +!!! example "Parallel Task Execution" + ```python + tasks = [ + "What are current AI safety initiatives?", + "How is CRISPR being used in agriculture?", + ] + results = swarm.batched_run(tasks) + ``` + +### Step +!!! example "Single Step Execution" + ```python + results = swarm.step("Analyze recent developments in renewable energy storage") + ``` + +## Domain-Specific Examples + +=== "Scientific Research" + ```python + science_swarm = DeepResearchSwarm( + name="ScienceSwarm", + output_type="json", + max_loops=2 # More iterations for thorough research + ) + + results = science_swarm.run( + "What are the latest experimental results in quantum entanglement?" + ) + ``` + +=== "Market Research" + ```python + market_swarm = DeepResearchSwarm( + name="MarketSwarm", + output_type="json" + ) + + results = market_swarm.run( + "What are the emerging trends in electric vehicle battery technology market?" + ) + ``` + +=== "News Analysis" + ```python + news_swarm = DeepResearchSwarm( + name="NewsSwarm", + output_type="string" # Human-readable output + ) + + results = news_swarm.run( + "What are the global economic impacts of recent geopolitical events?" + ) + ``` + +=== "Medical Research" + ```python + medical_swarm = DeepResearchSwarm( + name="MedicalSwarm", + max_loops=2 + ) + + results = medical_swarm.run( + "What are the latest clinical trials for Alzheimer's treatment?" + ) + ``` + +## Advanced Features + +??? note "Custom Research Agent" + ```python + from swarms import Agent + + custom_agent = Agent( + agent_name="SpecializedResearcher", + system_prompt="Your specialized prompt here", + model_name="gpt-4" + ) + + swarm = DeepResearchSwarm( + research_agent=custom_agent, + max_loops=2 + ) + ``` + +??? note "Parallel Processing Control" + ```python + swarm = DeepResearchSwarm( + max_workers=8, # Limit to 8 concurrent threads + nice_print=False # Disable console output for production + ) + ``` + +## Best Practices + +!!! success "Recommended Practices" + 1. **Query Formulation**: Be specific and clear in your research queries + 2. **Resource Management**: Adjust `max_workers` based on your system's capabilities + 3. **Output Handling**: Use appropriate `output_type` for your use case + 4. **Error Handling**: Implement try-catch blocks around swarm operations + 5. **Model Selection**: Choose appropriate models based on research complexity + +## Limitations + +!!! warning "Known Limitations" + + - Requires valid API keys for external services + + - Performance depends on system resources + + - Rate limits may apply to external API calls + + - Token limits apply to model responses + + + +-------------------------------------------------- + +# File: swarms\structs\diy_your_own_agent.md + +# Create your own agent with `Agent` class + +The Agent class is a powerful and flexible tool that empowers AI agents to build their own custom agents, tailored to their specific needs. + +This comprehensive guide will explore the process of inheriting from the Agent class, enabling agents to create their own custom agent classes. By leveraging the rich features and extensibility of the Agent class, agents can imbue their offspring agents with unique capabilities, specialized toolsets, and tailored decision-making processes. + +## Understanding the Agent Class + +Before we dive into the intricacies of creating custom agent classes, let's revisit the foundational elements of the Agent class itself. The Agent class is a versatile and feature-rich class designed to streamline the process of building and managing AI agents. It acts as a backbone, connecting language models (LLMs) with various tools, long-term memory, and a wide range of customization options. + +### Key Features of the Agent Class + +The Agent class offers a plethora of features that can be inherited and extended by custom agent classes. Here are some of the key features that make the Agent class a powerful foundation: + +1\. **Language Model Integration**: The Agent class supports seamless integration with popular language models such as LangChain, HuggingFace Transformers, and Autogen, allowing custom agent classes to leverage the power of state-of-the-art language models. + +2\. **Tool Integration**: One of the standout features of the Agent class is its ability to integrate with various tools. Custom agent classes can inherit this capability and incorporate specialized tools tailored to their specific use cases. + +3\. **Long-Term Memory**: The Agent class provides built-in support for long-term memory, enabling custom agent classes to retain and access information from previous interactions, essential for maintaining context and learning from past experiences. + +4\. **Customizable Prompts and Standard Operating Procedures (SOPs)**: The Agent class allows you to define custom prompts and Standard Operating Procedures (SOPs) that guide an agent's behavior and decision-making process. Custom agent classes can inherit and extend these prompts and SOPs to align with their unique objectives and requirements. + +5\. **Interactive and Dashboard Modes**: The Agent class supports interactive and dashboard modes, enabling real-time monitoring and interaction with agents. Custom agent classes can inherit these modes, facilitating efficient development, debugging, and user interaction. + +6\. **Autosave and State Management**: With the Agent class, agents can easily save and load their state, including configuration, memory, and history. Custom agent classes can inherit this capability, ensuring seamless task continuation and enabling efficient collaboration among team members. + +7\. **Response Filtering**: The Agent class provides built-in response filtering capabilities, allowing agents to filter out or replace specific words or phrases in their responses. Custom agent classes can inherit and extend this feature to ensure compliance with content moderation policies or specific guidelines. + +8\. **Code Execution and Multimodal Support**: The Agent class supports code execution and multimodal input/output, enabling agents to process and generate code, as well as handle various data formats such as images, audio, and video. Custom agent classes can inherit and specialize these capabilities for their unique use cases. + +9\. **Extensibility and Customization**: The Agent class is designed to be highly extensible and customizable, allowing agents to tailor its behavior, add custom functionality, and integrate with external libraries and APIs. Custom agent classes can leverage this extensibility to introduce specialized features and capabilities. + +### Creating a Custom Agent Class + +Now that we have a solid understanding of the Agent class and its features, let's dive into the process of creating a custom agent class by inheriting from the Agent class. Throughout this process, we'll explore how agents can leverage and extend the existing functionality, while introducing specialized features and capabilities tailored to their unique requirements. + +#### Step 1: Inherit from the Agent Class + +The first step in creating a custom agent class is to inherit from the Agent class. This will provide your custom agent class with the foundational features and capabilities of the Agent class, which can then be extended and customized as needed. The new agent class must have a `run(task: str)` method to run the entire agent. It is encouraged to have `step(task: str)` method that completes one step of the agent and then build the `run(task: str)` method. + +```python + +from swarms import Agent + +class MyCustomAgent(Agent): + +    def __init__(self, *args, **kwargs): + +        super().__init__(*args, **kwargs) + +        # Add custom initialization logic here + + def run(self, task: str) -> + ... + +``` + +In the example above, we define a new class `MyCustomAgent` that inherits from the `Agent` class. Within the `__init__` method, we call the parent class's `__init__` method using `super().__init__(*args, **kwargs)`, which ensures that the parent class's initialization logic is executed. You can then add any custom initialization logic specific to your custom agent class. + +#### Step 2: Customize the Agent's Behavior + +One of the key advantages of inheriting from the Agent class is the ability to customize the agent's behavior according to your specific requirements. This can be achieved by overriding or extending the existing methods, or by introducing new methods altogether. + +```python +from swarms import Agent + + +class MyCustomAgent(Agent): + +    def __init__(self, *args, **kwargs): + +        super().__init__(*args, **kwargs) + +        # Custom initialization logic + +    def custom_method(self, *args, **kwargs): + +        # Implement custom logic here + +        pass + +    def run(self, task, *args, **kwargs): + +        # Customize the run method + +        response = super().run(task, *args, **kwargs) + +        # Additional custom logic + +        return response + +``` + +In the example above, we introduce a new `custom_method` that can encapsulate any specialized logic or functionality specific to your custom agent class. Additionally, we override the `run` method, which is responsible for executing the agent's main task loop. Within the overridden `run` method, you can call the parent class's `run` method using `super().run(task, *args, **kwargs)` and then introduce any additional custom logic before or after the parent method's execution. + +#### Step 3: Extend Memory Management + +The Agent class provides built-in support for long-term memory, allowing agents to retain and access information from previous interactions. Custom agent classes can inherit and extend this capability by introducing specialized memory management techniques. + +```python + +from swarms_memory import BaseVectorDatabase +from swarms import Agent + + +class CustomMemory(BaseVectorDatabase): + +    def __init__(self, *args, **kwargs): + +        super().__init__(*args, **kwargs) + +        # Custom memory initialization logic + +    def query(self, *args, **kwargs): + +        # Custom memory query logic + +        return result + +class MyCustomAgent(Agent): + +    def __init__(self, *args, **kwargs): + +        super().__init__(*args, **kwargs) + +        # Custom initialization logic + +        self.long_term_memory = CustomMemory() + +    def run(self, task, *args, **kwargs): + +        # Customize the run method + +        response = super().run(task, *args, **kwargs) + +        # Utilize custom memory + +        memory_result = self.long_term_memory.query(*args, **kwargs) + +        # Process memory result + +        return response + +``` + +In the example above, we define a new `CustomMemory` class that inherits from the `BaseVectorDatabase` class provided by the Agent class framework. Within the `CustomMemory` class, you can implement specialized memory management logic, such as custom indexing, retrieval, and storage mechanisms. + +Next, within the `MyCustomAgent` class, we initialize an instance of the `CustomMemory` class and assign it to the `self.long_term_memory` attribute. This custom memory instance can then be utilized within the overridden `run` method, where you can query the memory and process the results as needed. + +## Step 5: Introduce Custom Prompts and Standard Operating Procedures (SOPs) + +The Agent class allows you to define custom prompts and Standard Operating Procedures (SOPs) that guide an agent's behavior and decision-making process. Custom agent classes can inherit and extend these prompts and SOPs to align with their unique objectives and requirements. + +```python +from swarms import Agent + + +class MyCustomAgent(Agent): + +    def __init__(self, *args, **kwargs): + +        super().__init__(*args, **kwargs) + +        # Custom initialization logic + +        self.custom_sop = "Custom SOP for MyCustomAgent..." + +        self.custom_prompt = "Custom prompt for MyCustomAgent..." + +    def run(self, task, *args, **kwargs): + +        # Customize the run method + +        response = super().run(task, *args, **kwargs) + +        # Utilize custom prompts and SOPs + +        custom_prompt = self.construct_dynamic_prompt(self.custom_prompt) + +        custom_sop = self.construct_dynamic_sop(self.custom_sop) + +        # Process custom prompts and SOPs + +        return response + +    def construct_dynamic_prompt(self, prompt): + +        # Custom prompt construction logic + +        return prompt + +    def construct_dynamic_sop(self, sop): + +        # Custom SOP construction logic + +        return sop + +``` + +In the example above, we define two new attributes within the `MyCustomAgent` class: `custom_sop` and `custom_prompt`. These attributes can be used to store custom prompts and SOPs specific to your custom agent class. + +Within the overridden `run` method, you can utilize these custom prompts and SOPs by calling the `construct_dynamic_prompt` and `construct_dynamic_sop` methods, which can be defined within the `MyCustomAgent` class to implement specialized prompt and SOP construction logic. + +#### Step 5: Introduce Custom Response Handling + +The Agent class provides built-in response filtering capabilities, allowing agents to filter out or replace specific words or phrases in their responses. Custom agent classes can inherit and extend this feature to ensure compliance with content moderation policies or specific guidelines. + +```python +from swarms import Agent + + +class MyCustomAgent(Agent): + +    def __init__(self, *args, **kwargs): + +        super().__init__(*args, **kwargs) + +        # Custom initialization logic + +        self.response_filters = ["filter_word_1", "filter_word_2"] + +    def run(self, task, *args, **kwargs): + +        # Customize the run method + +        response = super().run(task, *args, **kwargs) + +        # Apply custom response filtering + +        filtered_response = self.apply_response_filters(response) + +        return filtered_response + +    def apply_response_filters(self, response): + +        # Custom response filtering logic + +        for word in self.response_filters: + +            response = response.replace(word, "[FILTERED]") + +        return response + +``` + +In the example above, we define a new attribute `response_filters` within the `MyCustomAgent` class, which is a list of words or phrases that should be filtered out or replaced in the agent's responses. + +Within the overridden `run` method, we call the `apply_response_filters` method, which can be defined within the `MyCustomAgent` class to implement specialized response filtering logic. In the example, we iterate over the `response_filters` list and replace each filtered word or phrase with a placeholder string (`"[FILTERED]"`). + +### Advanced Customization and Integration + +The Agent class and its inherited custom agent classes can be further extended and customized to suit specific requirements and integrate with external libraries, APIs, and services. Here are some advanced customization and integration examples: + +1\. **Multimodal Input/Output Integration**: Custom agent classes can leverage the multimodal input/output capabilities of the Agent class and introduce specialized handling for various data formats such as images, audio, and video. + +2\. **Code Execution and Integration**: The Agent class supports code execution, enabling agents to run and evaluate code snippets. Custom agent classes can inherit and extend this capability, introducing specialized code execution environments, sandboxing mechanisms, or integration with external code repositories or platforms. + +3\. **External API and Service Integration**: Custom agent classes can integrate with external APIs and services, enabling agents to leverage specialized data sources, computational resources, or domain-specific services. + +4\. **Performance Optimization**: Depending on the use case and requirements, custom agent classes can introduce performance optimizations, such as adjusting loop intervals, retry attempts, or enabling parallel execution for certain tasks. + +5\. **Logging and Monitoring**: Custom agent classes can introduce specialized logging and monitoring mechanisms, enabling agents to track their performance, identify potential issues, and generate detailed reports or dashboards. + +6\. **Security and Privacy Enhancements**: Custom agent classes can implement security and privacy enhancements, such as data encryption, access control mechanisms, or compliance with industry-specific regulations and standards. + +7\. **Distributed Execution and Scaling**: Custom agent classes can be designed to support distributed execution and scaling, enabling agents to leverage cloud computing resources or distributed computing frameworks for handling large-scale tasks or high-concurrency workloads. + +By leveraging these advanced customization and integration capabilities, agents can create highly specialized and sophisticated custom agent classes tailored to their unique requirements and use cases. + +### Best Practices and Considerations + +While building custom agent classes by inheriting from the Agent class offers immense flexibility and power, it's essential to follow best practices and consider potential challenges and considerations: + +1\. **Maintainability and Documentation**: As custom agent classes become more complex, it's crucial to prioritize maintainability and thorough documentation. Clear and concise code, comprehensive comments, and up-to-date documentation can significantly improve the long-term sustainability and collaboration efforts surrounding custom agent classes. + +2\. **Testing and Validation**: Custom agent classes should undergo rigorous testing and validation to ensure their correctness, reliability, and adherence to expected behaviors. Establish a robust testing framework and continuously validate the agent's performance, particularly after introducing new features or integrations. + +3\. **Security and Privacy Considerations**: When building custom agent classes, it's essential to consider security and privacy implications, especially if the agents will handle sensitive data or interact with critical systems. Implement appropriate security measures, such as access controls, data encryption, and secure communication protocols, to protect against potential vulnerabilities and ensure compliance with relevant regulations and standards. + +4\. **Scalability and Performance Monitoring**: As custom agent classes are deployed and adopted, it's important to monitor their scalability and performance characteristics. Identify potential bottlenecks, resource constraints, or performance degradation, and implement appropriate optimization strategies or scaling mechanisms to ensure efficient and reliable operation. + +5\. **Collaboration and Knowledge Sharing**: Building custom agent classes often involves collaboration among teams and stakeholders. Foster an environment of knowledge sharing, code reviews, and open communication to ensure that everyone involved understands the agent's capabilities, limitations, and intended use cases. + +6\. **Ethical Considerations**: As AI agents become more advanced and autonomous, it's crucial to consider the ethical implications of their actions and decisions. Implement appropriate safeguards, oversight mechanisms, and ethical guidelines to ensure that custom agent classes operate in a responsible and transparent manner, aligning with ethical principles and societal values. + +7\. **Continuous Learning and Adaptation**: The field of AI is rapidly evolving, with new techniques, tools, and best practices emerging regularly. Stay up-to-date with the latest developments and be prepared to adapt and refine your custom agent classes as new advancements become available. + +By following these best practices and considering potential challenges, agents can create robust, reliable, and ethical custom agent classes that meet their specific requirements while adhering to industry standards and best practices. + +# Conclusion + +In this comprehensive guide, we have explored the process of creating custom agent classes by inheriting from the powerful Agent class. We have covered the key features of the Agent class, walked through the step-by-step process of inheriting and extending its functionality, and discussed advanced customization and integration techniques. + +Building custom agent classes empowers AI agents to create tailored and specialized agents capable of tackling unique challenges and addressing specific domain requirements. By leveraging the rich features and extensibility of the Agent class, agents can imbue their offspring agents with unique capabilities, specialized toolsets, and tailored decision-making processes. + +Remember, the journey of building custom agent classes is an iterative and collaborative process that requires continuous learning, adaptation, and refinement. + +-------------------------------------------------- + +# File: swarms\structs\forest_swarm.md + +# Forest Swarm + +This documentation describes the **ForestSwarm** that organizes agents into trees. Each agent specializes in processing specific tasks. Trees are collections of agents, each assigned based on their relevance to a task through keyword extraction and embedding-based similarity. + +The architecture allows for efficient task assignment by selecting the most relevant agent from a set of trees. Tasks are processed asynchronously, with agents selected based on task relevance, calculated by the similarity of system prompts and task keywords. + + +## Module Path: `swarms.structs.tree_swarm` + +--- + +### Class: `TreeAgent` + +`TreeAgent` represents an individual agent responsible for handling a specific task. Agents are initialized with a **system prompt** and are responsible for dynamically determining their relevance to a given task. + +#### Attributes + +| **Attribute** | **Type** | **Description** | +|--------------------------|------------------|---------------------------------------------------------------------------------| +| `system_prompt` | `str` | A string that defines the agent's area of expertise and task-handling capability.| +| `llm` | `callable` | The language model (LLM) used to process tasks (e.g., GPT-4). | +| `agent_name` | `str` | The name of the agent. | +| `system_prompt_embedding`| `tensor` | Embedding of the system prompt for similarity-based task matching. | +| `relevant_keywords` | `List[str]` | Keywords dynamically extracted from the system prompt to assist in task matching.| +| `distance` | `Optional[float]`| The computed distance between agents based on embedding similarity. | + +#### Methods + +| **Method** | **Input** | **Output** | **Description** | +|--------------------|---------------------------------|--------------------|---------------------------------------------------------------------------------| +| `calculate_distance(other_agent: TreeAgent)` | `other_agent: TreeAgent` | `float` | Calculates the cosine similarity between this agent and another agent. | +| `run_task(task: str)` | `task: str` | `Any` | Executes the task, logs the input/output, and returns the result. | +| `is_relevant_for_task(task: str, threshold: float = 0.7)` | `task: str, threshold: float` | `bool` | Checks if the agent is relevant for the task using keyword matching or embedding similarity.| + +--- + +### Class: `Tree` + +`Tree` organizes multiple agents into a hierarchical structure, where agents are sorted based on their relevance to tasks. + +#### Attributes + +| **Attribute** | **Type** | **Description** | +|--------------------------|------------------|---------------------------------------------------------------------------------| +| `tree_name` | `str` | The name of the tree (represents a domain of agents, e.g., "Financial Tree"). | +| `agents` | `List[TreeAgent]`| List of agents belonging to this tree. | + +#### Methods + +| **Method** | **Input** | **Output** | **Description** | +|--------------------|---------------------------------|--------------------|---------------------------------------------------------------------------------| +| `calculate_agent_distances()` | `None` | `None` | Calculates and assigns distances between agents based on similarity of prompts. | +| `find_relevant_agent(task: str)` | `task: str` | `Optional[TreeAgent]` | Finds the most relevant agent for a task based on keyword and embedding similarity. | +| `log_tree_execution(task: str, selected_agent: TreeAgent, result: Any)` | `task: str, selected_agent: TreeAgent, result: Any` | `None` | Logs details of the task execution by the selected agent. | + +--- + +### Class: `ForestSwarm` + +`ForestSwarm` is the main class responsible for managing multiple trees. It oversees task delegation by finding the most relevant tree and agent for a given task. + +#### Attributes + +| **Attribute** | **Type** | **Description** | +|--------------------------|------------------|---------------------------------------------------------------------------------| +| `trees` | `List[Tree]` | List of trees containing agents organized by domain. | + +#### Methods + +| **Method** | **Input** | **Output** | **Description** | +|--------------------|---------------------------------|--------------------|---------------------------------------------------------------------------------| +| `find_relevant_tree(task: str)` | `task: str` | `Optional[Tree]` | Searches across all trees to find the most relevant tree based on task requirements.| +| `run(task: str)` | `task: str` | `Any` | Executes the task by finding the most relevant agent from the relevant tree. | + +## Full Code Example + +```python +from swarms.structs.tree_swarm import TreeAgent, Tree, ForestSwarm +# Example Usage: + +# Create agents with varying system prompts and dynamically generated distances/keywords +agents_tree1 = [ + TreeAgent( + system_prompt="Stock Analysis Agent", + agent_name="Stock Analysis Agent", + ), + TreeAgent( + system_prompt="Financial Planning Agent", + agent_name="Financial Planning Agent", + ), + TreeAgent( + agent_name="Retirement Strategy Agent", + system_prompt="Retirement Strategy Agent", + ), +] + +agents_tree2 = [ + TreeAgent( + system_prompt="Tax Filing Agent", + agent_name="Tax Filing Agent", + ), + TreeAgent( + system_prompt="Investment Strategy Agent", + agent_name="Investment Strategy Agent", + ), + TreeAgent( + system_prompt="ROTH IRA Agent", agent_name="ROTH IRA Agent" + ), +] + +# Create trees +tree1 = Tree(tree_name="Financial Tree", agents=agents_tree1) +tree2 = Tree(tree_name="Investment Tree", agents=agents_tree2) + +# Create the ForestSwarm +multi_agent_structure = ForestSwarm(trees=[tree1, tree2]) + +# Run a task +task = "Our company is incorporated in delaware, how do we do our taxes for free?" +output = multi_agent_structure.run(task) +print(output) +``` + + + +--- + +## Example Workflow + +1. **Create Agents**: Agents are initialized with varying system prompts, representing different areas of expertise (e.g., stock analysis, tax filing). +2. **Create Trees**: Agents are grouped into trees, with each tree representing a domain (e.g., "Financial Tree", "Investment Tree"). +3. **Run Task**: When a task is submitted, the system traverses through all trees and finds the most relevant agent to handle the task. +4. **Task Execution**: The selected agent processes the task, and the result is returned. + +```plaintext +Task: "Our company is incorporated in Delaware, how do we do our taxes for free?" +``` + +**Process**: +- The system searches through the `Financial Tree` and `Investment Tree`. +- The most relevant agent (likely the "Tax Filing Agent") is selected based on keyword matching and prompt similarity. +- The task is processed, and the result is logged and returned. + +--- + +## Analysis of the Swarm Architecture + +The **Swarm Architecture** leverages a hierarchical structure (forest) composed of individual trees, each containing agents specialized in specific domains. This design allows for: + +- **Modular and Scalable Organization**: By separating agents into trees, it is easy to expand or contract the system by adding or removing trees or agents. +- **Task Specialization**: Each agent is specialized, which ensures that tasks are matched with the most appropriate agent based on relevance and expertise. +- **Dynamic Matching**: The architecture uses both keyword-based and embedding-based matching to assign tasks, ensuring a high level of accuracy in agent selection. +- **Logging and Accountability**: Each task execution is logged in detail, providing transparency and an audit trail of which agent handled which task and the results produced. +- **Asynchronous Task Execution**: The architecture can be adapted for asynchronous task processing, making it scalable and suitable for large-scale task handling in real-time systems. + +--- + +## Mermaid Diagram of the Swarm Architecture + +```mermaid +graph TD + A[ForestSwarm] --> B[Financial Tree] + A --> C[Investment Tree] + + B --> D[Stock Analysis Agent] + B --> E[Financial Planning Agent] + B --> F[Retirement Strategy Agent] + + C --> G[Tax Filing Agent] + C --> H[Investment Strategy Agent] + C --> I[ROTH IRA Agent] + + subgraph Tree Agents + D[Stock Analysis Agent] + E[Financial Planning Agent] + F[Retirement Strategy Agent] + G[Tax Filing Agent] + H[Investment Strategy Agent] + I[ROTH IRA Agent] + end +``` + +### Explanation of the Diagram + +- **ForestSwarm**: Represents the top-level structure managing multiple trees. +- **Trees**: In the example, two trees exist—**Financial Tree** and **Investment Tree**—each containing agents related to specific domains. +- **Agents**: Each agent within the tree is responsible for handling tasks in its area of expertise. Agents within a tree are organized based on their prompt similarity (distance). + +--- + +### Summary + +This **Multi-Agent Tree Structure** provides an efficient, scalable, and accurate architecture for delegating and executing tasks based on domain-specific expertise. The combination of hierarchical organization, dynamic task matching, and logging ensures reliability, performance, and transparency in task execution. + +-------------------------------------------------- + +# File: swarms\structs\graph_workflow.md + +# GraphWorkflow + +A powerful workflow orchestration system that creates directed graphs of agents for complex multi-agent collaboration and task execution. + +## Overview + +The `GraphWorkflow` class is a sophisticated workflow management system that enables the creation and execution of complex multi-agent workflows. It represents workflows as directed graphs where nodes are agents and edges represent data flow and dependencies between agents. The system supports parallel execution, automatic compilation optimization, and comprehensive visualization capabilities. + +Key features: + +| Feature | Description | +|------------------------|-----------------------------------------------------------------------------------------------| +| **Agent-based nodes** | Each node represents an agent that can process tasks | +| **Directed graph structure** | Edges define the flow of data between agents | +| **Parallel execution** | Multiple agents can run simultaneously within layers | +| **Automatic compilation** | Optimizes workflow structure for efficient execution | +| **Rich visualization** | Generate visual representations using Graphviz | +| **Serialization** | Save and load workflows as JSON | +| **Pattern detection** | Automatically identifies parallel processing patterns | + +## Architecture + +```mermaid +graph TB + subgraph "GraphWorkflow Architecture" + A[GraphWorkflow] --> B[Node Collection] + A --> C[Edge Collection] + A --> D[NetworkX Graph] + A --> E[Execution Engine] + + B --> F[Agent Nodes] + C --> G[Directed Edges] + D --> H[Topological Sort] + E --> I[Parallel Execution] + E --> J[Layer Processing] + + subgraph "Node Types" + F --> K[Agent Node] + K --> L[Agent Instance] + K --> M[Node Metadata] + end + + subgraph "Edge Types" + G --> N[Simple Edge] + G --> O[Fan-out Edge] + G --> P[Fan-in Edge] + G --> Q[Parallel Chain] + end + + subgraph "Execution Patterns" + I --> R[Thread Pool] + I --> S[Concurrent Futures] + J --> T[Layer-by-layer] + J --> U[Dependency Resolution] + end + end +``` + +## Class Reference + +| Parameter | Type | Description | Default | +|-----------|------|-------------|---------| +| `id` | `Optional[str]` | Unique identifier for the workflow | Auto-generated UUID | +| `name` | `Optional[str]` | Human-readable name for the workflow | "Graph-Workflow-01" | +| `description` | `Optional[str]` | Detailed description of the workflow | Generic description | +| `nodes` | `Optional[Dict[str, Node]]` | Initial collection of nodes | `{}` | +| `edges` | `Optional[List[Edge]]` | Initial collection of edges | `[]` | +| `entry_points` | `Optional[List[str]]` | Node IDs that serve as starting points | `[]` | +| `end_points` | `Optional[List[str]]` | Node IDs that serve as ending points | `[]` | +| `max_loops` | `int` | Maximum number of execution loops | `1` | +| `task` | `Optional[str]` | The task to be executed by the workflow | `None` | +| `auto_compile` | `bool` | Whether to automatically compile the workflow | `True` | +| `verbose` | `bool` | Whether to enable detailed logging | `False` | + +### Core Methods + +#### `add_node(agent: Agent, **kwargs)` + +Adds an agent node to the workflow graph. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `agent` | `Agent` | The agent to add as a node | +| `**kwargs` | `Any` | Additional keyword arguments for the node | + +**Raises:** + +- `ValueError`: If a node with the same ID already exists + +**Example:** + +```python +workflow = GraphWorkflow() +agent = Agent(agent_name="ResearchAgent", model_name="gpt-4") +workflow.add_node(agent, metadata={"priority": "high"}) +``` + +#### `add_edge(edge_or_source, target=None, **kwargs)` + +Adds an edge to connect nodes in the workflow. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `edge_or_source` | `Edge` or `str` | Either an Edge object or source node ID | +| `target` | `str` | Target node ID (required if edge_or_source is not an Edge) | +| `**kwargs` | `Any` | Additional keyword arguments for the edge | + +**Raises:** + +- `ValueError`: If source or target nodes don't exist + +**Example:** + +```python +# Using Edge object +edge = Edge(source="agent1", target="agent2") +workflow.add_edge(edge) + +# Using node IDs +workflow.add_edge("agent1", "agent2", metadata={"priority": "high"}) +``` + +#### `add_edges_from_source(source, targets, **kwargs)` + +Creates a fan-out pattern where one source connects to multiple targets. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `source` | `str` | Source node ID | +| `targets` | `List[str]` | List of target node IDs | +| `**kwargs` | `Any` | Additional keyword arguments for all edges | + +**Returns:** + +- `List[Edge]`: List of created Edge objects + +**Example:** + +```python +workflow.add_edges_from_source( + "DataCollector", + ["TechnicalAnalyst", "FundamentalAnalyst", "SentimentAnalyst"] +) +``` + +#### `add_edges_to_target(sources, target, **kwargs)` + +Creates a fan-in pattern where multiple sources connect to one target. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `sources` | `List[str]` | List of source node IDs | +| `target` | `str` | Target node ID | +| `**kwargs` | `Any` | Additional keyword arguments for all edges | + +**Returns:** + +- `List[Edge]`: List of created Edge objects + +**Example:** + +```python +workflow.add_edges_to_target( + ["TechnicalAnalyst", "FundamentalAnalyst", "SentimentAnalyst"], + "SynthesisAgent" +) +``` + +#### `add_parallel_chain(sources, targets, **kwargs)` + +Creates a full mesh connection between multiple sources and targets. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `sources` | `List[str]` | List of source node IDs | +| `targets` | `List[str]` | List of target node IDs | +| `**kwargs` | `Any` | Additional keyword arguments for all edges | + +**Returns:** + +- `List[Edge]`: List of created Edge objects + + +**Example:** + +```python +workflow.add_parallel_chain( + ["DataCollector1", "DataCollector2"], + ["Analyst1", "Analyst2", "Analyst3"] +) +``` + +### Execution Methods + +#### `run(task: str = None, img: Optional[str] = None, *args, **kwargs) -> Dict[str, Any]` + +Executes the workflow with optimized parallel agent execution. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `task` | `str` | Task to execute (uses self.task if not provided) | +| `img` | `Optional[str]` | Image path for vision-enabled agents | +| `*args` | `Any` | Additional positional arguments | +| `**kwargs` | `Any` | Additional keyword arguments | + +**Returns:** + +- `Dict[str, Any]`: Execution results from all nodes + +**Example:** + +```python +results = workflow.run( + task="Analyze market trends for cryptocurrency", + max_loops=2 +) +``` + +#### `arun(task: str = None, *args, **kwargs) -> Dict[str, Any]` + +Async version of run for better performance with I/O bound operations. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `task` | `str` | Task to execute | +| `*args` | `Any` | Additional positional arguments | +| `**kwargs` | `Any` | Additional keyword arguments | + +**Returns:** + +- `Dict[str, Any]`: Execution results from all nodes + +**Example:** + +```python +import asyncio +results = await workflow.arun("Process large dataset") +``` + +### Compilation and Optimization + +#### `compile()` + +Pre-computes expensive operations for faster execution. + +**Example:** + +```python +workflow.compile() +status = workflow.get_compilation_status() +print(f"Compiled: {status['is_compiled']}") +``` + +#### `get_compilation_status() -> Dict[str, Any]` + +Returns detailed compilation status information. + +**Returns:** + +- `Dict[str, Any]`: Compilation status including cache state and performance metrics + +**Example:** + +```python +status = workflow.get_compilation_status() +print(f"Layers: {status['cached_layers_count']}") +print(f"Max workers: {status['max_workers']}") +``` + +### Visualization Methods + +#### `visualize(format: str = "png", view: bool = True, engine: str = "dot", show_summary: bool = False) -> str` + +Generates a visual representation of the workflow using Graphviz. + +| Parameter | Type | Description | Default | +|-----------|------|-------------|---------| +| `format` | `str` | Output format ('png', 'svg', 'pdf', 'dot') | `"png"` | +| `view` | `bool` | Whether to open the visualization | `True` | +| `engine` | `str` | Graphviz layout engine | `"dot"` | +| `show_summary` | `bool` | Whether to print parallel processing summary | `False` | + +**Returns:** + +- `str`: Path to the generated visualization file + +**Example:** + +```python +output_file = workflow.visualize( + format="svg", + show_summary=True +) +print(f"Visualization saved to: {output_file}") +``` + +#### `visualize_simple() -> str` + +Generates a simple text-based visualization. + +**Returns:** + +- `str`: Text representation of the workflow + +**Example:** + +```python +text_viz = workflow.visualize_simple() +print(text_viz) +``` + +### Serialization Methods + +#### `to_json(fast: bool = True, include_conversation: bool = False, include_runtime_state: bool = False) -> str` + +Serializes the workflow to JSON format. + +| Parameter | Type | Description | Default | +|-----------|------|-------------|---------| +| `fast` | `bool` | Whether to use fast JSON serialization | `True` | +| `include_conversation` | `bool` | Whether to include conversation history | `False` | +| `include_runtime_state` | `bool` | Whether to include runtime state | `False` | + +**Returns:** + +- `str`: JSON representation of the workflow + +**Example:** + +```python +json_data = workflow.to_json( + include_conversation=True, + include_runtime_state=True +) +``` + +#### `from_json(json_str: str, restore_runtime_state: bool = False) -> GraphWorkflow` + +Deserializes a workflow from JSON format. + +| Parameter | Type | Description | Default | +|-----------|------|-------------|---------| +| `json_str` | `str` | JSON string representation | Required | +| `restore_runtime_state` | `bool` | Whether to restore runtime state | `False` | + +**Returns:** + +- `GraphWorkflow`: A new GraphWorkflow instance + +**Example:** + +```python +workflow = GraphWorkflow.from_json(json_data, restore_runtime_state=True) +``` + +#### `save_to_file(filepath: str, include_conversation: bool = False, include_runtime_state: bool = False, overwrite: bool = False) -> str` + +Saves the workflow to a JSON file. + +| Parameter | Type | Description | Default | +|-----------|------|-------------|---------| +| `filepath` | `str` | Path to save the JSON file | Required | +| `include_conversation` | `bool` | Whether to include conversation history | `False` | +| `include_runtime_state` | `bool` | Whether to include runtime state | `False` | +| `overwrite` | `bool` | Whether to overwrite existing files | `False` | + +**Returns:** + +- `str`: Path to the saved file + +**Example:** + +```python +filepath = workflow.save_to_file( + "my_workflow.json", + include_conversation=True +) +``` + +#### `load_from_file(filepath: str, restore_runtime_state: bool = False) -> GraphWorkflow` + +Loads a workflow from a JSON file. + +| Parameter | Type | Description | Default | +|-----------|------|-------------|---------| +| `filepath` | `str` | Path to the JSON file | Required | +| `restore_runtime_state` | `bool` | Whether to restore runtime state | `False` | + +**Returns:** + +- `GraphWorkflow`: Loaded workflow instance + +**Example:** + +```python +workflow = GraphWorkflow.load_from_file("my_workflow.json") +``` + +### Utility Methods + +#### `export_summary() -> Dict[str, Any]` + +Generates a human-readable summary of the workflow. + +**Returns:** + +- `Dict[str, Any]`: Comprehensive workflow summary + +**Example:** + +```python +summary = workflow.export_summary() +print(f"Workflow has {summary['structure']['nodes']} nodes") +print(f"Compilation status: {summary['compilation_status']['is_compiled']}") +``` + +#### `set_entry_points(entry_points: List[str])` + +Sets the entry points for the workflow. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `entry_points` | `List[str]` | List of node IDs to serve as entry points | + +**Example:** + +```python +workflow.set_entry_points(["DataCollector", "ResearchAgent"]) +``` + +#### `set_end_points(end_points: List[str])` + +Sets the end points for the workflow. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `end_points` | `List[str]` | List of node IDs to serve as end points | + +**Example:** + +```python +workflow.set_end_points(["SynthesisAgent", "ReportGenerator"]) +``` + +### Class Methods + +#### `from_spec(agents, edges, entry_points=None, end_points=None, task=None, **kwargs) -> GraphWorkflow` + +Constructs a workflow from a list of agents and connections. + +| Parameter | Type | Description | Default | +|-----------|------|-------------|---------| +| `agents` | `List` | List of agents or Node objects | Required | +| `edges` | `List` | List of edges or edge tuples | Required | +| `entry_points` | `List[str]` | List of entry point node IDs | `None` | +| `end_points` | `List[str]` | List of end point node IDs | `None` | +| `task` | `str` | Task to be executed by the workflow | `None` | +| `**kwargs` | `Any` | Additional keyword arguments | `{}` | + +**Returns:** + +- `GraphWorkflow`: A new GraphWorkflow instance + +**Example:** + +```python +workflow = GraphWorkflow.from_spec( + agents=[agent1, agent2, agent3], + edges=[ + ("agent1", "agent2"), + ("agent2", "agent3"), + ("agent1", ["agent2", "agent3"]) # Fan-out + ], + task="Analyze market data" +) +``` + +## Examples + +### Basic Sequential Workflow + +```python +from swarms import Agent, GraphWorkflow +from swarms.prompts.multi_agent_collab_prompt import MULTI_AGENT_COLLAB_PROMPT_TWO + +# Create agents +research_agent = Agent( + agent_name="ResearchAgent", + model_name="gpt-4", + system_prompt=MULTI_AGENT_COLLAB_PROMPT_TWO, + max_loops=1 +) + +analysis_agent = Agent( + agent_name="AnalysisAgent", + model_name="gpt-4", + system_prompt=MULTI_AGENT_COLLAB_PROMPT_TWO, + max_loops=1 +) + +# Build workflow +workflow = GraphWorkflow(name="Research-Analysis-Workflow") +workflow.add_node(research_agent) +workflow.add_node(analysis_agent) +workflow.add_edge("ResearchAgent", "AnalysisAgent") + +# Execute +results = workflow.run("What are the latest trends in AI?") +print(results) +``` + +### Parallel Processing Workflow + +```python +from swarms import Agent, GraphWorkflow + +# Create specialized agents +data_collector = Agent(agent_name="DataCollector", model_name="gpt-4") +technical_analyst = Agent(agent_name="TechnicalAnalyst", model_name="gpt-4") +fundamental_analyst = Agent(agent_name="FundamentalAnalyst", model_name="gpt-4") +sentiment_analyst = Agent(agent_name="SentimentAnalyst", model_name="gpt-4") +synthesis_agent = Agent(agent_name="SynthesisAgent", model_name="gpt-4") + +# Build parallel workflow +workflow = GraphWorkflow(name="Market-Analysis-Workflow") + +# Add all agents +for agent in [data_collector, technical_analyst, fundamental_analyst, + sentiment_analyst, synthesis_agent]: + workflow.add_node(agent) + +# Create fan-out pattern: data collector feeds all analysts +workflow.add_edges_from_source( + "DataCollector", + ["TechnicalAnalyst", "FundamentalAnalyst", "SentimentAnalyst"] +) + +# Create fan-in pattern: all analysts feed synthesis agent +workflow.add_edges_to_target( + ["TechnicalAnalyst", "FundamentalAnalyst", "SentimentAnalyst"], + "SynthesisAgent" +) + +# Execute +results = workflow.run("Analyze Bitcoin market trends") +print(results) +``` + +### Complex Multi-Layer Workflow + +```python +from swarms import Agent, GraphWorkflow + +# Create agents for different stages +data_collectors = [ + Agent(agent_name=f"DataCollector{i}", model_name="gpt-4") + for i in range(1, 4) +] + +analysts = [ + Agent(agent_name=f"Analyst{i}", model_name="gpt-4") + for i in range(1, 4) +] + +validators = [ + Agent(agent_name=f"Validator{i}", model_name="gpt-4") + for i in range(1, 3) +] + +synthesis_agent = Agent(agent_name="SynthesisAgent", model_name="gpt-4") + +# Build complex workflow +workflow = GraphWorkflow(name="Complex-Research-Workflow") + +# Add all agents +all_agents = data_collectors + analysts + validators + [synthesis_agent] +for agent in all_agents: + workflow.add_node(agent) + +# Layer 1: Data collectors feed all analysts in parallel +workflow.add_parallel_chain( + [agent.agent_name for agent in data_collectors], + [agent.agent_name for agent in analysts] +) + +# Layer 2: Analysts feed validators +workflow.add_parallel_chain( + [agent.agent_name for agent in analysts], + [agent.agent_name for agent in validators] +) + +# Layer 3: Validators feed synthesis agent +workflow.add_edges_to_target( + [agent.agent_name for agent in validators], + "SynthesisAgent" +) + +# Visualize and execute +workflow.visualize(show_summary=True) +results = workflow.run("Comprehensive analysis of renewable energy markets") +``` + +### Workflow with Custom Metadata + +```python +from swarms import Agent, GraphWorkflow, Edge + +# Create agents with specific roles +research_agent = Agent(agent_name="ResearchAgent", model_name="gpt-4") +analysis_agent = Agent(agent_name="AnalysisAgent", model_name="gpt-4") + +# Build workflow with metadata +workflow = GraphWorkflow( + name="Metadata-Workflow", + description="Workflow demonstrating metadata usage" +) + +workflow.add_node(research_agent, metadata={"priority": "high", "timeout": 300}) +workflow.add_node(analysis_agent, metadata={"priority": "medium", "timeout": 600}) + +# Add edge with metadata +edge = Edge( + source="ResearchAgent", + target="AnalysisAgent", + metadata={"data_type": "research_findings", "priority": "high"} +) +workflow.add_edge(edge) + +# Execute with custom parameters +results = workflow.run( + "Analyze the impact of climate change on agriculture", + max_loops=2 +) +``` + +### Workflow Serialization and Persistence + +```python +from swarms import Agent, GraphWorkflow + +# Create workflow +research_agent = Agent(agent_name="ResearchAgent", model_name="gpt-4") +analysis_agent = Agent(agent_name="AnalysisAgent", model_name="gpt-4") + +workflow = GraphWorkflow(name="Persistent-Workflow") +workflow.add_node(research_agent) +workflow.add_node(analysis_agent) +workflow.add_edge("ResearchAgent", "AnalysisAgent") + +# Execute and get conversation +results = workflow.run("Research quantum computing applications") + +# Save workflow with conversation history +filepath = workflow.save_to_file( + "quantum_research_workflow.json", + include_conversation=True, + include_runtime_state=True +) + +# Load workflow later +loaded_workflow = GraphWorkflow.load_from_file( + filepath, + restore_runtime_state=True +) + +# Continue execution +new_results = loaded_workflow.run("Continue with quantum cryptography analysis") +``` + +### Advanced Pattern Detection + +```python +from swarms import Agent, GraphWorkflow + +# Create a complex workflow with multiple patterns +workflow = GraphWorkflow(name="Pattern-Detection-Workflow", verbose=True) + +# Create agents +agents = { + "collector": Agent(agent_name="DataCollector", model_name="gpt-4"), + "tech_analyst": Agent(agent_name="TechnicalAnalyst", model_name="gpt-4"), + "fund_analyst": Agent(agent_name="FundamentalAnalyst", model_name="gpt-4"), + "sentiment_analyst": Agent(agent_name="SentimentAnalyst", model_name="gpt-4"), + "risk_analyst": Agent(agent_name="RiskAnalyst", model_name="gpt-4"), + "synthesis": Agent(agent_name="SynthesisAgent", model_name="gpt-4"), + "validator": Agent(agent_name="Validator", model_name="gpt-4") +} + +# Add all agents +for agent in agents.values(): + workflow.add_node(agent) + +# Create complex patterns +# Fan-out from collector +workflow.add_edges_from_source( + "DataCollector", + ["TechnicalAnalyst", "FundamentalAnalyst", "SentimentAnalyst", "RiskAnalyst"] +) + +# Fan-in to synthesis +workflow.add_edges_to_target( + ["TechnicalAnalyst", "FundamentalAnalyst", "SentimentAnalyst", "RiskAnalyst"], + "SynthesisAgent" +) + +# Final validation step +workflow.add_edge("SynthesisAgent", "Validator") + +# Compile and get status +workflow.compile() +status = workflow.get_compilation_status() + +print(f"Compilation status: {status}") +print(f"Layers: {status['cached_layers_count']}") +print(f"Max workers: {status['max_workers']}") + +# Visualize with pattern detection +workflow.visualize(show_summary=True, format="png") +``` + +### Error Handling and Recovery + +```python +from swarms import Agent, GraphWorkflow +import logging + +# Set up logging +logging.basicConfig(level=logging.INFO) + +# Create workflow with error handling +workflow = GraphWorkflow( + name="Error-Handling-Workflow", + verbose=True, + max_loops=1 +) + +# Create agents +try: + research_agent = Agent(agent_name="ResearchAgent", model_name="gpt-4") + analysis_agent = Agent(agent_name="AnalysisAgent", model_name="gpt-4") + + workflow.add_node(research_agent) + workflow.add_node(analysis_agent) + workflow.add_edge("ResearchAgent", "AnalysisAgent") + + # Execute with error handling + try: + results = workflow.run("Analyze market trends") + print("Workflow completed successfully") + print(results) + + except Exception as e: + print(f"Workflow execution failed: {e}") + + # Get workflow summary for debugging + summary = workflow.export_summary() + print(f"Workflow state: {summary['structure']}") + +except Exception as e: + print(f"Workflow setup failed: {e}") +``` + +## Conclusion + +The `GraphWorkflow` class provides a powerful and flexible framework for orchestrating complex multi-agent workflows. Its key benefits include: + +### Benefits + +| Benefit | Description | +|-----------------|--------------------------------------------------------------------------------------------------| +| **Scalability** | Supports workflows with hundreds of agents through efficient parallel execution | +| **Flexibility** | Multiple connection patterns (sequential, fan-out, fan-in, parallel chains) | +| **Performance** | Automatic compilation and optimization for faster execution | +| **Visualization** | Rich visual representations for workflow understanding and debugging | +| **Persistence** | Complete serialization and deserialization capabilities | +| **Error Handling** | Comprehensive error handling and recovery mechanisms | +| **Monitoring** | Detailed logging and status reporting | + +### Use Cases + +| Use Case | Description | +|-------------------------|--------------------------------------------------------------------| +| **Research Workflows** | Multi-stage research with data collection, analysis, and synthesis | +| **Content Generation** | Parallel content creation with validation and refinement | +| **Data Processing** | Complex ETL pipelines with multiple processing stages | +| **Decision Making** | Multi-agent decision systems with voting and consensus | +| **Quality Assurance** | Multi-stage validation and verification processes | +| **Automated Testing** | Complex test orchestration with parallel execution | + +### Best Practices + +| Best Practice | Description | +|---------------------------------------|------------------------------------------------------------------| +| **Use meaningful agent names** | Helps with debugging and visualization | +| **Leverage parallel patterns** | Use fan-out and fan-in for better performance | +| **Compile workflows** | Always compile before execution for optimal performance | +| **Monitor execution** | Use verbose mode and status reporting for debugging | +| **Save important workflows** | Use serialization for workflow persistence | +| **Handle errors gracefully** | Implement proper error handling and recovery | +| **Visualize complex workflows** | Use visualization to understand and debug workflows | + +The GraphWorkflow system represents a significant advancement in multi-agent orchestration, providing the tools needed to build complex, scalable, and maintainable AI workflows. + +-------------------------------------------------- + +# File: swarms\structs\group_chat.md + +# GroupChat Swarm Documentation + +A production-grade multi-agent system enabling sophisticated group conversations between AI agents with customizable speaking patterns, parallel processing capabilities, and comprehensive conversation tracking. + +## Advanced Configuration + +### Agent Parameters + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| agent_name | str | Required | Unique identifier for the agent | +| system_prompt | str | Required | Role and behavior instructions | +| llm | Any | Required | Language model instance | +| max_loops | int | 1 | Maximum conversation turns | +| autosave | bool | False | Enable conversation saving | +| dashboard | bool | False | Enable monitoring dashboard | +| verbose | bool | True | Enable detailed logging | +| dynamic_temperature | bool | True | Enable dynamic temperature | +| retry_attempts | int | 1 | Failed request retry count | +| context_length | int | 200000 | Maximum context window | +| output_type | str | "string" | Response format type | +| streaming_on | bool | False | Enable streaming responses | + +### GroupChat Parameters + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| name | str | "GroupChat" | Chat group identifier | +| description | str | "" | Purpose description | +| agents | List[Agent] | [] | Participating agents | +| speaker_fn | Callable | round_robin | Speaker selection function | +| max_loops | int | 10 | Maximum conversation turns | + + +## Table of Contents + +- [Installation](#installation) +- [Core Concepts](#core-concepts) +- [Basic Usage](#basic-usage) +- [Advanced Configuration](#advanced-configuration) +- [Speaker Functions](#speaker-functions) +- [Response Models](#response-models) +- [Advanced Examples](#advanced-examples) +- [API Reference](#api-reference) +- [Best Practices](#best-practices) + +## Installation + +```bash +pip3 install swarms swarm-models loguru +``` + +## Core Concepts + +The GroupChat system consists of several key components: + +1. **Agents**: Individual AI agents with specialized knowledge and roles +2. **Speaker Functions**: Control mechanisms for conversation flow +3. **Chat History**: Structured conversation tracking +4. **Response Models**: Pydantic models for data validation + +## Basic Usage + +```python + +import os +from dotenv import load_dotenv +from swarm_models import OpenAIChat +from swarms import Agent, GroupChat, expertise_based + + +if __name__ == "__main__": + + load_dotenv() + + # Get the OpenAI API key from the environment variable + api_key = os.getenv("OPENAI_API_KEY") + + # Create an instance of the OpenAIChat class + model = OpenAIChat( + openai_api_key=api_key, + model_name="gpt-4o-mini", + temperature=0.1, + ) + + # Example agents + agent1 = Agent( + agent_name="Financial-Analysis-Agent", + system_prompt="You are a financial analyst specializing in investment strategies.", + llm=model, + max_loops=1, + autosave=False, + dashboard=False, + verbose=True, + dynamic_temperature_enabled=True, + user_name="swarms_corp", + retry_attempts=1, + context_length=200000, + output_type="string", + streaming_on=False, + ) + + agent2 = Agent( + agent_name="Tax-Adviser-Agent", + system_prompt="You are a tax adviser who provides clear and concise guidance on tax-related queries.", + llm=model, + max_loops=1, + autosave=False, + dashboard=False, + verbose=True, + dynamic_temperature_enabled=True, + user_name="swarms_corp", + retry_attempts=1, + context_length=200000, + output_type="string", + streaming_on=False, + ) + + agents = [agent1, agent2] + + chat = GroupChat( + name="Investment Advisory", + description="Financial and tax analysis group", + agents=agents, + speaker_fn=expertise_based, + ) + + history = chat.run( + "How to optimize tax strategy for investments?" + ) + print(history.model_dump_json(indent=2)) + +``` + +## Speaker Functions + + +### Built-in Functions + +```python +def round_robin(history: List[str], agent: Agent) -> bool: + """ + Enables agents to speak in turns. + Returns True for each agent in sequence. + """ + return True + +def expertise_based(history: List[str], agent: Agent) -> bool: + """ + Enables agents to speak based on their expertise. + Returns True if agent's role matches conversation context. + """ + return agent.system_prompt.lower() in history[-1].lower() if history else True + +def random_selection(history: List[str], agent: Agent) -> bool: + """ + Randomly selects speaking agents. + Returns True/False with 50% probability. + """ + import random + return random.choice([True, False]) + +def most_recent(history: List[str], agent: Agent) -> bool: + """ + Enables agents to respond to their mentions. + Returns True if agent was last speaker. + """ + return agent.agent_name == history[-1].split(":")[0].strip() if history else True +``` + +### Custom Speaker Function Example + +```python +def custom_speaker(history: List[str], agent: Agent) -> bool: + """ + Custom speaker function with complex logic. + + Args: + history: Previous conversation messages + agent: Current agent being evaluated + + Returns: + bool: Whether agent should speak + """ + # No history - let everyone speak + if not history: + return True + + last_message = history[-1].lower() + + # Check for agent expertise keywords + expertise_relevant = any( + keyword in last_message + for keyword in agent.expertise_keywords + ) + + # Check for direct mentions + mentioned = agent.agent_name.lower() in last_message + + # Check if agent hasn't spoken recently + not_recent_speaker = not any( + agent.agent_name in msg + for msg in history[-3:] + ) + + return expertise_relevant or mentioned or not_recent_speaker + +# Usage +chat = GroupChat( + agents=[agent1, agent2], + speaker_fn=custom_speaker +) +``` + +## Response Models + +### Complete Schema + +```python +class AgentResponse(BaseModel): + """Individual agent response in a conversation turn""" + agent_name: str + role: str + message: str + timestamp: datetime = Field(default_factory=datetime.now) + turn_number: int + preceding_context: List[str] = Field(default_factory=list) + +class ChatTurn(BaseModel): + """Single turn in the conversation""" + turn_number: int + responses: List[AgentResponse] + task: str + timestamp: datetime = Field(default_factory=datetime.now) + +class ChatHistory(BaseModel): + """Complete conversation history""" + turns: List[ChatTurn] + total_messages: int + name: str + description: str + start_time: datetime = Field(default_factory=datetime.now) +``` + +## Advanced Examples + +### Multi-Agent Analysis Team + +```python +# Create specialized agents +data_analyst = Agent( + agent_name="Data-Analyst", + system_prompt="You analyze numerical data and patterns", + llm=model +) + +market_expert = Agent( + agent_name="Market-Expert", + system_prompt="You provide market insights and trends", + llm=model +) + +strategy_advisor = Agent( + agent_name="Strategy-Advisor", + system_prompt="You formulate strategic recommendations", + llm=model +) + +# Create analysis team +analysis_team = GroupChat( + name="Market Analysis Team", + description="Comprehensive market analysis group", + agents=[data_analyst, market_expert, strategy_advisor], + speaker_fn=expertise_based, + max_loops=15 +) + +# Run complex analysis +history = analysis_team.run(""" + Analyze the current market conditions: + 1. Identify key trends + 2. Evaluate risks + 3. Recommend investment strategy +""") +``` + +### Parallel Processing + +```python +# Define multiple analysis tasks +tasks = [ + "Analyze tech sector trends", + "Evaluate real estate market", + "Review commodity prices", + "Assess global economic indicators" +] + +# Run tasks concurrently +histories = chat.concurrent_run(tasks) + +# Process results +for task, history in zip(tasks, histories): + print(f"\nAnalysis for: {task}") + for turn in history.turns: + for response in turn.responses: + print(f"{response.agent_name}: {response.message}") +``` + +## Best Practices + +1. **Agent Design** + - Give agents clear, specific roles + - Use detailed system prompts + - Set appropriate context lengths + - Enable retries for reliability + +2. **Speaker Functions** + - Match function to use case + - Consider conversation flow + - Handle edge cases + - Add appropriate logging + +3. **Error Handling** + - Use try-except blocks + - Log errors appropriately + - Implement retry logic + - Provide fallback responses + +4. **Performance** + - Use concurrent processing for multiple tasks + - Monitor context lengths + - Implement proper cleanup + - Cache responses when appropriate + +## API Reference + +### GroupChat Methods + +| Method | Description | Arguments | Returns | +|--------|-------------|-----------|---------| +| run | Run single conversation | task: str | ChatHistory | +| batched_run | Run multiple sequential tasks | tasks: List[str] | List[ChatHistory] | +| concurrent_run | Run multiple parallel tasks | tasks: List[str] | List[ChatHistory] | +| get_recent_messages | Get recent messages | n: int = 3 | List[str] | + +### Agent Methods + +| Method | Description | Returns | +|--------|-------------|---------| +| run | Process single task | str | +| generate_response | Generate LLM response | str | +| save_context | Save conversation context | None | + +-------------------------------------------------- + +# File: swarms\structs\heavy_swarm.md + +# HeavySwarm Documentation + +HeavySwarm is a sophisticated multi-agent orchestration system that decomposes complex tasks into specialized questions and executes them using four specialized agents: Research, Analysis, Alternatives, and Verification. The results are then synthesized into a comprehensive response. + +Inspired by X.AI's Grok 4 heavy implementation, HeavySwarm provides robust task analysis through intelligent question generation, parallel execution, and comprehensive synthesis with real-time progress monitoring. + +## Architecture + +### System Design + +The HeavySwarm follows a structured 5-phase workflow: + +1. **Task Decomposition**: Complex tasks are broken down into specialized questions +2. **Question Generation**: AI-powered generation of role-specific questions +3. **Parallel Execution**: Four specialized agents work concurrently +4. **Result Collection**: Outputs are gathered and validated +5. **Synthesis**: Integration into a comprehensive final response + +### Agent Specialization + +- **Research Agent**: Comprehensive information gathering and synthesis +- **Analysis Agent**: Pattern recognition and statistical analysis +- **Alternatives Agent**: Creative problem-solving and strategic options +- **Verification Agent**: Validation, feasibility assessment, and quality assurance +- **Synthesis Agent**: Multi-perspective integration and executive reporting + +## Architecture Diagram + +```mermaid +graph TB + subgraph "HeavySwarm Architecture" + A[Input Task] --> B[Question Generation Agent] + B --> C[Task Decomposition] + + C --> D[Research Agent] + C --> E[Analysis Agent] + C --> F[Alternatives Agent] + C --> G[Verification Agent] + + D --> H[Parallel Execution Engine] + E --> H + F --> H + G --> H + + H --> I[Result Collection] + I --> J[Synthesis Agent] + J --> K[Comprehensive Report] + + subgraph "Monitoring & Control" + L[Rich Dashboard] + M[Progress Tracking] + N[Error Handling] + O[Timeout Management] + end + + H --> L + H --> M + H --> N + H --> O + end + + subgraph "Agent Specializations" + D --> D1[Information Gathering
Market Research
Data Collection] + E --> E1[Statistical Analysis
Pattern Recognition
Predictive Modeling] + F --> F1[Creative Solutions
Strategic Options
Innovation Ideation] + G --> G1[Fact Checking
Feasibility Assessment
Quality Assurance] + end + + style A fill:#ff6b6b + style K fill:#4ecdc4 + style H fill:#45b7d1 + style J fill:#96ceb4 +``` + +## Installation + +```bash +pip install swarms +``` + +## Quick Start + +```python +from swarms import HeavySwarm + +# Initialize the swarm +swarm = HeavySwarm( + name="MarketAnalysisSwarm", + description="Financial market analysis swarm", + question_agent_model_name="gpt-4o-mini", + worker_model_name="gpt-4o-mini", + show_dashboard=True, + verbose=True ) -# Run the agent in interactive mode -agent.run("Let's start a conversation") +# Execute analysis +result = swarm.run("Analyze the current cryptocurrency market trends and investment opportunities") +print(result) ``` -### Sentiment Analysis +## API Reference -To perform sentiment analysis on the agent's outputs, you can provide a sentiment analyzer function: +### HeavySwarm Class -```python -from textblob import TextBlob +#### Constructor Parameters -def sentiment_analyzer(text): - analysis = TextBlob(text) - return analysis.sentiment.polarity +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `name` | `str` | `"HeavySwarm"` | Identifier name for the swarm instance | +| `description` | `str` | `"A swarm of agents..."` | Description of the swarm's purpose | +| `agents` | `List[Agent]` | `None` | Pre-configured agent list (unused - agents created internally) | +| `timeout` | `int` | `300` | Maximum execution time per agent in seconds | +| `aggregation_strategy` | `str` | `"synthesis"` | Strategy for result aggregation | +| `loops_per_agent` | `int` | `1` | Number of execution loops per agent | +| `question_agent_model_name` | `str` | `"gpt-4o-mini"` | Model for question generation | +| `worker_model_name` | `str` | `"gpt-4o-mini"` | Model for specialized worker agents | +| `verbose` | `bool` | `False` | Enable detailed logging output | +| `max_workers` | `int` | `int(os.cpu_count() * 0.9)` | Maximum concurrent workers | +| `show_dashboard` | `bool` | `False` | Enable rich dashboard visualization | +| `agent_prints_on` | `bool` | `False` | Enable individual agent output printing | -agent = Agent( - agent_name="Sentiment-Analysis-Agent", - llm=OpenAIChat(api_key=os.getenv("OPENAI_API_KEY")), - sentiment_analyzer=sentiment_analyzer, - sentiment_threshold=0.5, - system_prompt="You are an agent that generates responses with sentiment analysis.", -) +#### Methods -response = agent.run("Generate a positive statement about AI") -print(response) -``` +##### `run(task: str, img: str = None) -> str` +Execute the complete HeavySwarm orchestration flow. +**Parameters:** -### Undo Functionality +- `task` (str): The main task to analyze and decompose -```python -# Feature 2: Undo functionality -response = agent.run("Another task") -print(f"Response: {response}") -previous_state, message = agent.undo_last() -print(message) -``` +- `img` (str, optional): Image input for visual analysis tasks -### Response Filtering +**Returns:** +- `str`: Comprehensive final analysis from synthesis agent +**Example:** ```python -# Feature 3: Response filtering -agent.add_response_filter("report") -response = agent.filtered_run("Generate a report on finance") -print(response) +result = swarm.run("Develop a go-to-market strategy for a new SaaS product") ``` -### Saving and Loading State + +## Real-World Applications + +### Financial Services ```python -# Save the agent state -agent.save_state('saved_flow.json') +# Market Analysis +swarm = HeavySwarm( + name="FinanceSwarm", + worker_model_name="gpt-4o", + show_dashboard=True +) -# Load the agent state -agent = Agent(llm=llm_instance, max_loops=5) -agent.load('saved_flow.json') -agent.run("Continue with the task") +result = swarm.run(""" +Analyze the impact of recent Federal Reserve policy changes on: +1. Bond markets and yield curves +2. Equity market valuations +3. Currency exchange rates +4. Provide investment recommendations for institutional portfolios +""") ``` -### Async and Concurrent Execution +### Use-cases -```python -# Run a task concurrently -response = await agent.run_concurrent("Concurrent task") -print(response) +| Use Case | Description | +|---------------------------------------------|---------------------------------------------| +| Portfolio optimization and risk assessment | Optimize asset allocation and assess risks | +| Market trend analysis and forecasting | Analyze and predict market movements | +| Regulatory compliance evaluation | Evaluate adherence to financial regulations | +| Investment strategy development | Develop and refine investment strategies | +| Credit risk analysis and modeling | Analyze and model credit risk | -# Run multiple tasks concurrently -tasks = [ - {"task": "Task 1"}, - {"task": "Task 2", "img": "path/to/image.jpg"}, - {"task": "Task 3", "custom_param": 42} -] -responses = agent.bulk_run(tasks) -print(responses) -``` + +------- -### Various other settings +### Healthcare & Life Sciences ```python -# # Convert the agent object to a dictionary -print(agent.to_dict()) -print(agent.to_toml()) -print(agent.model_dump_json()) -print(agent.model_dump_yaml()) +# Clinical Research Analysis +swarm = HeavySwarm( + name="HealthcareSwarm", + worker_model_name="gpt-4o", + timeout=600, + loops_per_agent=2 +) -# Ingest documents into the agent's knowledge base -agent.ingest_docs("your_pdf_path.pdf") +result = swarm.run(""" +Evaluate the potential of AI-driven personalized medicine: +1. Current technological capabilities and limitations +2. Regulatory landscape and approval pathways +3. Market opportunities and competitive analysis +4. Implementation strategies for healthcare systems +""") +``` -# Receive a message from a user and process it -agent.receive_message(name="agent_name", message="message") +---- -# Send a message from the agent to a user -agent.send_agent_message(agent_name="agent_name", message="message") +**Use Cases:** -# Ingest multiple documents into the agent's knowledge base -agent.ingest_docs("your_pdf_path.pdf", "your_csv_path.csv") +| Use Case | Description | +|----------------------------------------|---------------------------------------------| +| Drug discovery and development analysis| Analyze and accelerate drug R&D processes | +| Clinical trial optimization | Improve design and efficiency of trials | +| Healthcare policy evaluation | Assess and inform healthcare policies | +| Medical device market analysis | Evaluate trends and opportunities in devices| +| Patient outcome prediction modeling | Predict and model patient health outcomes | -# Run the agent with a filtered system prompt -agent.filtered_run( - "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?" -) +--- -# Run the agent with multiple system prompts -agent.bulk_run( - [ - "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?", - "Another system prompt", - ] -) -# Add a memory to the agent -agent.add_memory("Add a memory to the agent") +### Technology & Innovation -# Check the number of available tokens for the agent -agent.check_available_tokens() +```python +# Tech Strategy Analysis +swarm = HeavySwarm( + name="TechSwarm", + worker_model_name="gpt-4o", + show_dashboard=True, + verbose=True +) -# Perform token checks for the agent -agent.tokens_checks() +result = swarm.run(""" +Assess the strategic implications of quantum computing adoption: +1. Technical readiness and hardware developments +2. Industry applications and use cases +3. Competitive landscape and key players +4. Investment and implementation roadmap +""") +``` -# Print the dashboard of the agent -agent.print_dashboard() +**Use Cases:** +| Use Case | Description | +|------------------------------------|---------------------------------------------| +| Technology roadmap development | Plan and prioritize technology initiatives | +| Competitive intelligence gathering | Analyze competitors and market trends | +| Innovation pipeline analysis | Evaluate and manage innovation projects | +| Digital transformation strategy | Develop and implement digital strategies | +| Emerging technology assessment | Assess new and disruptive technologies | -# Fetch all the documents from the doc folders -agent.get_docs_from_doc_folders() +### Manufacturing & Supply Chain -# Dump the model to a JSON file -agent.model_dump_json() -print(agent.to_toml()) +```python +# Supply Chain Optimization +swarm = HeavySwarm( + name="ManufacturingSwarm", + worker_model_name="gpt-4o", + max_workers=8 +) + +result = swarm.run(""" +Optimize global supply chain resilience: +1. Risk assessment and vulnerability analysis +2. Alternative sourcing strategies +3. Technology integration opportunities +4. Cost-benefit analysis of proposed changes +""") ``` -## Auto Generate Prompt + CPU Execution +**Use Cases:** +| Use Case | Description | +|----------------------------------|---------------------------------------------| +| Supply chain risk management | Identify and mitigate supply chain risks | +| Manufacturing process optimization | Improve efficiency and productivity | +| Quality control system design | Develop systems to ensure product quality | +| Sustainability impact assessment | Evaluate environmental and social impacts | +| Logistics network optimization | Enhance logistics and distribution networks | + +## Advanced Configuration + +### Custom Agent Configuration ```python +# High-performance configuration +swarm = HeavySwarm( + name="HighPerformanceSwarm", + question_agent_model_name="gpt-4o", + worker_model_name="gpt-4o", + timeout=900, + loops_per_agent=3, + max_workers=12, + show_dashboard=True, + verbose=True +) +``` -import os -from swarms import Agent -from swarm_models import OpenAIChat -from dotenv import load_dotenv +## Troubleshooting -# Load environment variables -load_dotenv() +| Issue | Solution | +|-------------------------|---------------------------------------------------------------| +| **Agent Timeout** | Increase timeout parameter or reduce task complexity | +| **Model Rate Limits** | Implement backoff strategies or use different models | +| **Memory Usage** | Monitor system resources with large-scale operations | +| **Dashboard Performance** | Disable dashboard for batch processing | -# Retrieve the OpenAI API key from the environment variable -api_key = os.getenv("GROQ_API_KEY") +## Contributing -# Initialize the model for OpenAI Chat -model = OpenAIChat( - openai_api_base="https://api.groq.com/openai/v1", - openai_api_key=api_key, - model_name="llama-3.1-70b-versatile", - temperature=0.1, -) +HeavySwarm is part of the Swarms ecosystem. Contributions are welcome for: -# Initialize the agent with automated prompt engineering enabled -agent = Agent( - agent_name="Financial-Analysis-Agent", - system_prompt=None, # System prompt is dynamically generated - agent_description=None, - llm=model, - max_loops=1, - autosave=True, - dashboard=False, - verbose=False, - dynamic_temperature_enabled=True, - saved_state_path="finance_agent.json", - user_name="Human:", - return_step_meta=False, - output_type="string", - streaming_on=False, - auto_generate_prompt=True, # Enable automated prompt engineering -) +- New agent specializations -# Run the agent with a task description and specify the device -agent.run( - "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria", - ## Will design a system prompt based on the task if description and system prompt are None - device="cpu", -) +- Performance optimizations -# Print the dynamically generated system prompt -print(agent.system_prompt) +- Integration capabilities +- Documentation improvements -``` -## Agent Structured Outputs +## Acknowledgments -- Create a structured output schema for the agent [List[Dict]] -- Input in the `tools_list_dictionary` parameter -- Output is a dictionary -- Use the `str_to_dict` function to convert the output to a dictionary -```python +- Inspired by X.AI's Grok heavy implementation -from dotenv import load_dotenv +- Built on the Swarms framework -from swarms import Agent -from swarms.prompts.finance_agent_sys_prompt import ( - FINANCIAL_AGENT_SYS_PROMPT, -) -from swarms.utils.str_to_dict import str_to_dict +- Utilizes Rich for dashboard visualization -load_dotenv() +- Powered by advanced language models -tools = [ - { - "type": "function", - "function": { - "name": "get_stock_price", - "description": "Retrieve the current stock price and related information for a specified company.", - "parameters": { - "type": "object", - "properties": { - "ticker": { - "type": "string", - "description": "The stock ticker symbol of the company, e.g. AAPL for Apple Inc.", - }, - "include_history": { - "type": "boolean", - "description": "Indicates whether to include historical price data along with the current price.", - }, - "time": { - "type": "string", - "format": "date-time", - "description": "Optional parameter to specify the time for which the stock data is requested, in ISO 8601 format.", - }, - }, - "required": [ - "ticker", - "include_history", - "time", - ], - }, - }, - } -] -# 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, - tools_list_dictionary=tools, -) +-------------------------------------------------- -out = agent.run( - "What is the current stock price for Apple Inc. (AAPL)? Include historical price data.", -) +# File: swarms\structs\hhcs.md -print(out) +# Hybrid Hierarchical-Cluster Swarm [HHCS] -print(type(out)) +The Hybrid Hierarchical-Cluster Swarm (HHCS) is an advanced AI orchestration architecture that combines hierarchical decision-making with parallel processing capabilities. HHCS enables complex task solving by dynamically routing tasks to specialized agent swarms based on their expertise and capabilities. -print(str_to_dict(out)) +## Purpose -print(type(str_to_dict(out))) +HHCS addresses the challenge of efficiently solving diverse and complex tasks by: +- Intelligently routing tasks to the most appropriate specialized swarms -``` +- Enabling parallel processing of multifaceted problems -## Best Practices +- Maintaining a clear hierarchy for effective decision-making -1. Always provide a clear and concise `system_prompt` to guide the agent's behavior. -2. Use `tools` to extend the agent's capabilities for specific tasks. -3. Implement error handling and utilize the `retry_attempts` feature for robust execution. -4. Leverage `long_term_memory` for tasks that require persistent information. -5. Use `interactive` mode for real-time conversations and `dashboard` for monitoring. -6. Implement `sentiment_analysis` for applications requiring tone management. -7. Utilize `autosave` and `save`/`load` methods for continuity across sessions. -8. Optimize token usage with `dynamic_context_window` and `tokens_checks` methods. -9. Use `concurrent` and `async` methods for performance-critical applications. -10. Regularly review and analyze feedback using the `analyze_feedback` method. -11. Use `artifacts_on` to save important outputs from agent execution -12. Configure `device` and `device_id` appropriately for optimal performance -13. Enable `rag_every_loop` when continuous context from long-term memory is needed -14. Use `scheduled_run_date` for automated task scheduling +- Combining outputs from multiple specialized agents for comprehensive solutions -By following these guidelines and leveraging the Swarm Agent's extensive features, you can create powerful, flexible, and efficient autonomous agents for a wide range of applications. +## Key Features --------------------------------------------------- +- **Router-based task distribution**: Central router agent analyzes incoming tasks and directs them to appropriate specialized swarms -# File: swarms/structs/agent_docs_v1.md +- **Hybrid architecture**: Combines hierarchical control with clustered specialization -# `Agent` Documentation +- **Parallel processing**: Multiple swarms can work simultaneously on different aspects of complex tasks -Swarm Agent is a powerful autonomous agent framework designed to connect Language Models (LLMs) with various tools and long-term memory. This class provides the ability to ingest and process various types of documents such as PDFs, text files, Markdown files, JSON files, and more. The Agent structure offers a wide range of features to enhance the capabilities of LLMs and facilitate efficient task execution. +- **Flexible swarm types**: Supports both sequential and concurrent workflows within swarms -1. **Conversational Loop**: It establishes a conversational loop with a language model. This means it allows you to interact with the model in a back-and-forth manner, taking turns in the conversation. +- **Comprehensive result aggregation**: Collects and combines outputs from all contributing swarms -2. **Feedback Collection**: The class allows users to provide feedback on the responses generated by the model. This feedback can be valuable for training and improving the model's responses over time. -3. **Stoppable Conversation**: You can define custom stopping conditions for the conversation, allowing you to stop the interaction based on specific criteria. For example, you can stop the conversation if a certain keyword is detected in the responses. +## Diagram -4. **Retry Mechanism**: The class includes a retry mechanism that can be helpful if there are issues generating responses from the model. It attempts to generate a response multiple times before raising an error. +The HHCS architecture follows a hierarchical structure with the router agent at the top level, specialized swarms at the middle level, and individual agents at the bottom level. -## Architecture ```mermaid -graph TD - A[Task Initiation] -->|Receives Task| B[Initial LLM Processing] - B -->|Interprets Task| C[Tool Usage] - C -->|Calls Tools| D[Function 1] - C -->|Calls Tools| E[Function 2] - D -->|Returns Data| C - E -->|Returns Data| C - C -->|Provides Data| F[Memory Interaction] - F -->|Stores and Retrieves Data| G[RAG System] - G -->|ChromaDB/Pinecone| H[Enhanced Data] - F -->|Provides Enhanced Data| I[Final LLM Processing] - I -->|Generates Final Response| J[Output] - C -->|No Tools Available| K[Skip Tool Usage] - K -->|Proceeds to Memory Interaction| F - F -->|No Memory Available| L[Skip Memory Interaction] - L -->|Proceeds to Final LLM Processing| I +flowchart TD + Start([Task Input]) --> RouterAgent[Router Agent] + RouterAgent --> Analysis{Task Analysis} + + Analysis -->|Analyze Requirements| Selection[Swarm Selection] + Selection -->|Select Best Swarm| Route[Route Task] + + Route --> Swarm1[Swarm 1] + Route --> Swarm2[Swarm 2] + Route --> SwarmN[Swarm N...] + + Swarm1 -->|Process Task| Result1[Swarm 1 Output] + Swarm2 -->|Process Task| Result2[Swarm 2 Output] + SwarmN -->|Process Task| ResultN[Swarm N Output] + + Result1 --> Conversation[Conversation History] + Result2 --> Conversation + ResultN --> Conversation + + Conversation --> Output([Final Output]) + + subgraph Router Decision Process + Analysis + Selection + end + + subgraph Parallel Task Processing + Swarm1 + Swarm2 + SwarmN + end + + subgraph Results Collection + Result1 + Result2 + ResultN + Conversation + end ``` -### `Agent` Attributes -| Attribute | Description | -|------------|-------------| -| `id` | A unique identifier for the agent instance. | -| `llm` | The language model instance used by the agent. | -| `template` | The template used for formatting responses. | -| `max_loops` | The maximum number of loops the agent can run. | -| `stopping_condition` | A callable function that determines when the agent should stop looping. | -| `loop_interval` | The interval (in seconds) between loops. | -| `retry_attempts` | The number of retry attempts for failed LLM calls. | -| `retry_interval` | The interval (in seconds) between retry attempts. | -| `return_history` | A boolean indicating whether the agent should return the conversation history. | -| `stopping_token` | A token that, when present in the response, stops the agent from looping. | -| `dynamic_loops` | A boolean indicating whether the agent should dynamically determine the number of loops. | -| `interactive` | A boolean indicating whether the agent should run in interactive mode. | -| `dashboard` | A boolean indicating whether the agent should display a dashboard. | -| `agent_name` | The name of the agent instance. | -| `agent_description` | A description of the agent instance. | -| `system_prompt` | The system prompt used to initialize the conversation. | -| `tools` | A list of callable functions representing tools the agent can use. | -| `dynamic_temperature_enabled` | A boolean indicating whether the agent should dynamically adjust the temperature of the LLM. | -| `sop` | The standard operating procedure for the agent. | -| `sop_list` | A list of strings representing the standard operating procedure. | -| `saved_state_path` | The file path for saving and loading the agent's state. | -| `autosave` | A boolean indicating whether the agent should automatically save its state. | -| `context_length` | The maximum length of the context window (in tokens) for the LLM. | -| `user_name` | The name used to represent the user in the conversation. | -| `self_healing_enabled` | A boolean indicating whether the agent should attempt to self-heal in case of errors. | -| `code_interpreter` | A boolean indicating whether the agent should interpret and execute code snippets. | -| `multi_modal` | A boolean indicating whether the agent should support multimodal inputs (e.g., text and images). | -| `pdf_path` | The file path of a PDF document to be ingested. | -| `list_of_pdf` | A list of file paths for PDF documents to be ingested. | -| `tokenizer` | An instance of a tokenizer used for token counting and management. | -| `long_term_memory` | An instance of a `BaseVectorDatabase` implementation for long-term memory management. | -| `preset_stopping_token` | A boolean indicating whether the agent should use a preset stopping token. | -| `traceback` | An object used for traceback handling. | -| `traceback_handlers` | A list of traceback handlers. | -| `streaming_on` | A boolean indicating whether the agent should stream its responses. | -| `docs` | A list of document paths or contents to be ingested. | -| `docs_folder` | The path to a folder containing documents to be ingested. | -| `verbose` | A boolean indicating whether the agent should print verbose output. | -| `parser` | A callable function used for parsing input data. | -| `best_of_n` | An integer indicating the number of best responses to generate (for sampling). | -| `callback` | A callable function to be called after each agent loop. | -| `metadata` | A dictionary containing metadata for the agent. | -| `callbacks` | A list of callable functions to be called during the agent's execution. | -| `logger_handler` | A handler for logging messages. | -| `search_algorithm` | A callable function representing the search algorithm for long-term memory retrieval. | -| `logs_to_filename` | The file path for logging agent activities. | -| `evaluator` | A callable function used for evaluating the agent's responses. | -| `output_json` | A boolean indicating whether the agent's output should be in JSON format. | -| `stopping_func` | A callable function used as a stopping condition for the agent. | -| `custom_loop_condition` | A callable function used as a custom loop condition for the agent. | -| `sentiment_threshold` | A float value representing the sentiment threshold for evaluating responses. | -| `custom_exit_command` | A string representing a custom command for exiting the agent's loop. | -| `sentiment_analyzer` | A callable function used for sentiment analysis on the agent's outputs. | -| `limit_tokens_from_string` | A callable function used for limiting the number of tokens in a string. | -| `custom_tools_prompt` | A callable function used for generating a custom prompt for tool usage. | -| `tool_schema` | A data structure representing the schema for the agent's tools. | -| `output_type` | A type representing the expected output type of the agent's responses. | -| `function_calling_type` | A string representing the type of function calling (e.g., "json"). | -| `output_cleaner` | A callable function used for cleaning the agent's output. | -| `function_calling_format_type` | A string representing the format type for function calling (e.g., "OpenAI"). | -| `list_base_models` | A list of base models used for generating tool schemas. | -| `metadata_output_type` | A string representing the output type for metadata. | -| `state_save_file_type` | A string representing the file type for saving the agent's state (e.g., "json", "yaml"). | -| `chain_of_thoughts` | A boolean indicating whether the agent should use the chain of thoughts technique. | -| `algorithm_of_thoughts` | A boolean indicating whether the agent should use the algorithm of thoughts technique. | -| `tree_of_thoughts` | A boolean indicating whether the agent should use the tree of thoughts technique. | -| `tool_choice` | A string representing the method for tool selection (e.g., "auto"). | -| `execute_tool` | A boolean indicating whether the agent should execute tools. | -| `rules` | A string representing the rules for the agent's behavior. | -| `planning` | A boolean indicating whether the agent should perform planning. | -| `planning_prompt` | A string representing the prompt for planning. | -| `device` | A string representing the device on which the agent should run. | -| `custom_planning_prompt` | A string representing a custom prompt for planning. | -| `memory_chunk_size` | An integer representing the maximum size of memory chunks for long-term memory retrieval. | -| `agent_ops_on` | A boolean indicating whether agent operations should be enabled. | -| `return_step_meta` | A boolean indicating whether or not to return JSON of all the steps and additional metadata | -| `output_type` | A Literal type indicating whether to output "string", "str", "list", "json", "dict", "yaml" | +## `HybridHierarchicalClusterSwarm` Constructor Arguments +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `name` | string | "Hybrid Hierarchical-Cluster Swarm" | The name of the swarm instance | +| `description` | string | "A swarm that uses a hybrid hierarchical-peer model to solve complex tasks." | Brief description of the swarm's functionality | +| `swarms` | List[SwarmRouter] | [] | List of available swarm routers | +| `max_loops` | integer | 1 | Maximum number of processing loops | +| `output_type` | string | "list" | Format for output (e.g., "list", "json") | +| `router_agent_model_name` | string | "gpt-4o-mini" | LLM model used by the router agent | +## Methods -### `Agent` Methods +| Method | Parameters | Return Type | Description | +|--------|------------|-------------|-------------| +| `run` | `task` (str) | str | Processes a single task through the swarm system | +| `batched_run` | `tasks` (List[str]) | List[str] | Processes multiple tasks in parallel | +| `find_swarm_by_name` | `swarm_name` (str) | SwarmRouter | Retrieves a swarm by its name | +| `route_task` | `swarm_name` (str), `task_description` (str) | None | Routes a task to a specific swarm | +| `get_swarms_info` | None | str | Returns formatted information about all available swarms | -| Method | Description | Inputs | Usage Example | -|--------|-------------|--------|----------------| -| `run(task, img=None, *args, **kwargs)` | Runs the autonomous agent loop to complete the given task. | `task` (str): The task to be performed.
`img` (str, optional): Path to an image file, if the task involves image processing.
`*args`, `**kwargs`: Additional arguments to pass to the language model. | `response = agent.run("Generate a report on financial performance.")` | -| `__call__(task, img=None, *args, **kwargs)` | An alternative way to call the `run` method. | Same as `run`. | `response = agent("Generate a report on financial performance.")` | -| `parse_and_execute_tools(response, *args, **kwargs)` | Parses the agent's response and executes any tools mentioned in it. | `response` (str): The agent's response to be parsed.
`*args`, `**kwargs`: Additional arguments to pass to the tool execution. | `agent.parse_and_execute_tools(response)` | -| `long_term_memory_prompt(query, *args, **kwargs)` | Generates a prompt for querying the agent's long-term memory. | `query` (str): The query to search for in long-term memory.
`*args`, `**kwargs`: Additional arguments to pass to the long-term memory retrieval. | `memory_retrieval = agent.long_term_memory_prompt("financial performance")` | -| `add_memory(message)` | Adds a message to the agent's memory. | `message` (str): The message +## Full Example +```python +from swarms import Agent, SwarmRouter +from swarms.structs.hybrid_hiearchical_peer_swarm import ( + HybridHierarchicalClusterSwarm, +) -## Features -- **Language Model Integration**: The Swarm Agent allows seamless integration with different language models, enabling users to leverage the power of state-of-the-art models. -- **Tool Integration**: The framework supports the integration of various tools, enabling the agent to perform a wide range of tasks, from code execution to data analysis and beyond. -- **Long-term Memory Management**: The Swarm Agent incorporates long-term memory management capabilities, allowing it to store and retrieve relevant information for effective decision-making and task execution. -- **Document Ingestion**: The agent can ingest and process various types of documents, including PDFs, text files, Markdown files, JSON files, and more, enabling it to extract relevant information for task completion. -- **Interactive Mode**: Users can interact with the agent in an interactive mode, enabling real-time communication and task execution. -- **Dashboard**: The framework provides a visual dashboard for monitoring the agent's performance and activities. -- **Dynamic Temperature Control**: The Swarm Agent supports dynamic temperature control, allowing for adjustments to the model's output diversity during task execution. -- **Autosave and State Management**: The agent can save its state automatically, enabling seamless resumption of tasks after interruptions or system restarts. -- **Self-Healing and Error Handling**: The framework incorporates self-healing and error-handling mechanisms to ensure robust and reliable operation. -- **Code Interpretation**: The agent can interpret and execute code snippets, expanding its capabilities for tasks involving programming or scripting. -- **Multimodal Support**: The framework supports multimodal inputs, enabling the agent to process and reason about various data types, such as text, images, and audio. -- **Tokenization and Token Management**: The Swarm Agent provides tokenization capabilities, enabling efficient management of token usage and context window truncation. -- **Sentiment Analysis**: The agent can perform sentiment analysis on its generated outputs, allowing for evaluation and adjustment of responses based on sentiment thresholds. -- **Output Filtering and Cleaning**: The framework supports output filtering and cleaning, ensuring that generated responses adhere to specific criteria or guidelines. -- **Asynchronous and Concurrent Execution**: The Swarm Agent supports asynchronous and concurrent task execution, enabling efficient parallelization and scaling of operations. -- **Planning and Reasoning**: The agent can engage in planning and reasoning processes, leveraging techniques such as algorithm of thoughts and chain of thoughts to enhance decision-making and task execution. -- **Agent Operations and Monitoring**: The framework provides integration with agent operations and monitoring tools, enabling real-time monitoring and management of the agent's activities. +# Core Legal Agent Definitions with short, simple prompts +litigation_agent = Agent( + agent_name="Litigator", + system_prompt="You handle lawsuits. Analyze facts, build arguments, and develop case strategy.", + model_name="groq/deepseek-r1-distill-qwen-32b", + max_loops=1, +) -## Getting Started +corporate_agent = Agent( + agent_name="Corporate-Attorney", + system_prompt="You handle business law. Advise on corporate structure, governance, and transactions.", + model_name="groq/deepseek-r1-distill-qwen-32b", + max_loops=1, +) -First run the following: +ip_agent = Agent( + agent_name="IP-Attorney", + system_prompt="You protect intellectual property. Handle patents, trademarks, copyrights, and trade secrets.", + model_name="groq/deepseek-r1-distill-qwen-32b", + max_loops=1, +) -```bash -pip3 install -U swarms -``` +employment_agent = Agent( + agent_name="Employment-Attorney", + system_prompt="You handle workplace matters. Address hiring, termination, discrimination, and labor issues.", + model_name="groq/deepseek-r1-distill-qwen-32b", + max_loops=1, +) -And, then now you can get started with the following: +paralegal_agent = Agent( + agent_name="Paralegal", + system_prompt="You assist attorneys. Conduct research, draft documents, and organize case files.", + model_name="groq/deepseek-r1-distill-qwen-32b", + max_loops=1, +) -```python -import os -from swarms import Agent -from swarm_models import OpenAIChat -from swarms.prompts.finance_agent_sys_prompt import ( - FINANCIAL_AGENT_SYS_PROMPT, +doc_review_agent = Agent( + agent_name="Document-Reviewer", + system_prompt="You examine documents. Extract key information and identify relevant content.", + model_name="groq/deepseek-r1-distill-qwen-32b", + max_loops=1, +) + +# Practice Area Swarm Routers +litigation_swarm = SwarmRouter( + name="litigation-practice", + description="Handle all aspects of litigation", + agents=[litigation_agent, paralegal_agent, doc_review_agent], + swarm_type="SequentialWorkflow", ) -# Get the OpenAI API key from the environment variable -api_key = os.getenv("OPENAI_API_KEY") +corporate_swarm = SwarmRouter( + name="corporate-practice", + description="Handle business and corporate legal matters", + agents=[corporate_agent, paralegal_agent], + swarm_type="SequentialWorkflow", +) -# Create an instance of the OpenAIChat class -model = OpenAIChat( - api_key=api_key, model_name="gpt-4o-mini", temperature=0.1 +ip_swarm = SwarmRouter( + name="ip-practice", + description="Handle intellectual property matters", + agents=[ip_agent, paralegal_agent], + swarm_type="SequentialWorkflow", ) -# Initialize the agent -agent = Agent( - agent_name="Financial-Analysis-Agent_sas_chicken_eej", - system_prompt=FINANCIAL_AGENT_SYS_PROMPT, - llm=model, - max_loops=1, - autosave=True, - dashboard=False, - verbose=True, - dynamic_temperature_enabled=True, - saved_state_path="finance_agent.json", - user_name="swarms_corp", - retry_attempts=1, - context_length=200000, - return_step_meta=False, - output_type="str", +employment_swarm = SwarmRouter( + name="employment-practice", + description="Handle employment and labor law matters", + agents=[employment_agent, paralegal_agent], + swarm_type="SequentialWorkflow", ) +# Cross-functional Swarm Router +m_and_a_swarm = SwarmRouter( + name="mergers-acquisitions", + description="Handle mergers and acquisitions", + agents=[ + corporate_agent, + ip_agent, + employment_agent, + doc_review_agent, + ], + swarm_type="ConcurrentWorkflow", +) -agent.run( - "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria" +dispute_swarm = SwarmRouter( + name="dispute-resolution", + description="Handle complex disputes requiring multiple specialties", + agents=[litigation_agent, corporate_agent, doc_review_agent], + swarm_type="ConcurrentWorkflow", ) -print(out) -``` -This example initializes an instance of the `Agent` class with an OpenAI language model and a maximum of 3 loops. The `run()` method is then called with a task to generate a report on financial performance, and the agent's response is printed. +hybrid_hiearchical_swarm = HybridHierarchicalClusterSwarm( + name="hybrid-hiearchical-swarm", + description="A hybrid hiearchical swarm that uses a hybrid hiearchical peer model to solve complex tasks.", + swarms=[ + litigation_swarm, + corporate_swarm, + ip_swarm, + employment_swarm, + m_and_a_swarm, + dispute_swarm, + ], + max_loops=1, + router_agent_model_name="gpt-4o-mini", +) -## Advanced Usage -The Swarm Agent provides numerous advanced features and customization options. Here are a few examples of how to leverage these features: +if __name__ == "__main__": + hybrid_hiearchical_swarm.run( + "What is the best way to file for a patent? for ai technology " + ) -### Tool Integration +``` -To integrate tools with the Swarm Agent, you can pass a list of callable functions with types and doc strings to the `tools` parameter when initializing the `Agent` instance. The agent will automatically convert these functions into an OpenAI function calling schema and make them available for use during task execution. +-------------------------------------------------- -## Requirements for a tool -- Function - - With types - - with doc strings +# File: swarms\structs\hierarchical_swarm.md -```python -from swarms import Agent -from swarm_models import OpenAIChat -from swarms_memory import ChromaDB -import subprocess -import os +# `HierarchicalSwarm` -# Making an instance of the ChromaDB class -memory = ChromaDB( - metric="cosine", - n_results=3, - output_dir="results", - docs_folder="docs", -) +The `HierarchicalSwarm` is a sophisticated multi-agent orchestration system that implements a hierarchical workflow pattern. It consists of a director agent that coordinates and distributes tasks to specialized worker agents, creating a structured approach to complex problem-solving. -# Model -model = OpenAIChat( - api_key=os.getenv("OPENAI_API_KEY"), - model_name="gpt-4o-mini", - temperature=0.1, -) +## Overview +The Hierarchical Swarm follows a clear workflow pattern: -# Tools in swarms are simple python functions and docstrings -def terminal( - code: str, -): - """ - Run code in the terminal. +1. **Task Reception**: User provides a task to the swarm +2. **Planning**: Director creates a comprehensive plan and distributes orders to agents +3. **Execution**: Individual agents execute their assigned tasks +4. **Feedback Loop**: Director evaluates results and issues new orders if needed (up to `max_loops`) +5. **Context Preservation**: All conversation history and context is maintained throughout the process - Args: - code (str): The code to run in the terminal. +## Architecture - Returns: - str: The output of the code. - """ - out = subprocess.run( - code, shell=True, capture_output=True, text=True - ).stdout - return str(out) +```mermaid +graph TD + A[User Task] --> B[Director Agent] + B --> C[Create Plan & Orders] + C --> D[Distribute to Agents] + D --> E[Agent 1] + D --> F[Agent 2] + D --> G[Agent N] + E --> H[Execute Task] + F --> H + G --> H + H --> I[Report Results] + I --> J[Director Evaluation] + J --> K{More Loops?} + K -->|Yes| C + K -->|No| L[Final Output] +``` +## Key Features -def browser(query: str): - """ - Search the query in the browser with the `browser` tool. +- **Hierarchical Coordination**: Director agent orchestrates all operations +- **Specialized Agents**: Each agent has specific expertise and responsibilities +- **Iterative Refinement**: Multiple feedback loops for improved results +- **Context Preservation**: Full conversation history maintained +- **Flexible Output Formats**: Support for various output types (dict, str, list) +- **Comprehensive Logging**: Detailed logging for debugging and monitoring - Args: - query (str): The query to search in the browser. +## `HierarchicalSwarm` Constructor - Returns: - str: The search results. - """ - import webbrowser +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `name` | `str` | `"HierarchicalAgentSwarm"` | The name of the swarm instance | +| `description` | `str` | `"Distributed task swarm"` | Brief description of the swarm's functionality | +| `director` | `Optional[Union[Agent, Callable, Any]]` | `None` | The director agent that orchestrates tasks | +| `agents` | `List[Union[Agent, Callable, Any]]` | `None` | List of worker agents in the swarm | +| `max_loops` | `int` | `1` | Maximum number of feedback loops between director and agents | +| `output_type` | `OutputType` | `"dict-all-except-first"` | Format for output (dict, str, list) | +| `feedback_director_model_name` | `str` | `"gpt-4o-mini"` | Model name for feedback director | +| `director_name` | `str` | `"Director"` | Name of the director agent | +| `director_model_name` | `str` | `"gpt-4o-mini"` | Model name for the director agent | +| `verbose` | `bool` | `False` | Enable detailed logging | +| `add_collaboration_prompt` | `bool` | `True` | Add collaboration prompts to agents | +| `planning_director_agent` | `Optional[Union[Agent, Callable, Any]]` | `None` | Optional planning agent for enhanced planning | - url = f"https://www.google.com/search?q={query}" - webbrowser.open(url) - return f"Searching for {query} in the browser." +## Core Methods +### `run(task, img=None, *args, **kwargs)` -def create_file(file_path: str, content: str): - """ - Create a file using the file editor tool. +Executes the hierarchical swarm for a specified number of feedback loops, processing the task through multiple iterations for refinement and improvement. - Args: - file_path (str): The path to the file. - content (str): The content to write to the file. +#### Parameters - Returns: - str: The result of the file creation operation. - """ - with open(file_path, "w") as file: - file.write(content) - return f"File {file_path} created successfully." +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `task` | `str` | **Required** | The initial task to be processed by the swarm | +| `img` | `str` | `None` | Optional image input for the agents | +| `*args` | `Any` | - | Additional positional arguments | +| `**kwargs` | `Any` | - | Additional keyword arguments | +#### Returns -def file_editor(file_path: str, mode: str, content: str): - """ - Edit a file using the file editor tool. +| Type | Description | +|------|-------------| +| `Any` | The formatted conversation history as output based on `output_type` | - Args: - file_path (str): The path to the file. - mode (str): The mode to open the file in. - content (str): The content to write to the file. +#### Example - Returns: - str: The result of the file editing operation. - """ - with open(file_path, mode) as file: - file.write(content) - return f"File {file_path} edited successfully." +```python +from swarms import Agent +from swarms.structs.hiearchical_swarm import HierarchicalSwarm +# Create specialized agents +research_agent = Agent( + agent_name="Research-Specialist", + agent_description="Expert in market research and analysis", + model_name="gpt-4o", +) -# Agent -agent = Agent( - agent_name="Devin", - system_prompt=( - "Autonomous agent that can interact with humans and other" - " agents. Be Helpful and Kind. Use the tools provided to" - " assist the user. Return all code in markdown format." - ), - llm=model, - max_loops="auto", - autosave=True, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - interactive=True, - tools=[terminal, browser, file_editor, create_file], - streaming=True, - long_term_memory=memory, +financial_agent = Agent( + agent_name="Financial-Analyst", + agent_description="Specialist in financial analysis and valuation", + model_name="gpt-4o", ) -# Run the agent -out = agent( - "Create a CSV file with the latest tax rates for C corporations in the following ten states and the District of Columbia: Alabama, California, Florida, Georgia, Illinois, New York, North Carolina, Ohio, Texas, and Washington." +# Initialize the hierarchical swarm +swarm = HierarchicalSwarm( + name="Financial-Analysis-Swarm", + description="A hierarchical swarm for comprehensive financial analysis", + agents=[research_agent, financial_agent], + max_loops=2, + verbose=True, ) -print(out) +# Execute a complex task +task = "Analyze the market potential for Tesla (TSLA) stock" +result = swarm.run(task=task) +print(result) ``` -### Long-term Memory Management +### `step(task, img=None, *args, **kwargs)` -The Swarm Agent supports integration with various vector databases for long-term memory management. You can pass an instance of a `BaseVectorDatabase` implementation to the `long_term_memory` parameter when initializing the `Agent`. +Runs a single step of the hierarchical swarm, executing one complete cycle of planning, distribution, execution, and feedback. -```python -import os +#### Parameters -from swarms_memory import ChromaDB +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `task` | `str` | **Required** | The task to be executed in this step | +| `img` | `str` | `None` | Optional image input for the agents | +| `*args` | `Any` | - | Additional positional arguments | +| `**kwargs` | `Any` | - | Additional keyword arguments | -from swarms import Agent -from swarm_models import Anthropic -from swarms.prompts.finance_agent_sys_prompt import ( - FINANCIAL_AGENT_SYS_PROMPT, -) +#### Returns -# Initilaize the chromadb client -chromadb = ChromaDB( - metric="cosine", - output_dir="fiance_agent_rag", - # docs_folder="artifacts", # Folder of your documents -) +| Type | Description | +|------|-------------| +| `str` | Feedback from the director based on agent outputs | -# Model -model = Anthropic(anthropic_api_key=os.getenv("ANTHROPIC_API_KEY")) +#### Example +```python +from swarms import Agent +from swarms.structs.hiearchical_swarm import HierarchicalSwarm -# Initialize the agent -agent = Agent( - agent_name="Financial-Analysis-Agent", - system_prompt=FINANCIAL_AGENT_SYS_PROMPT, - agent_description="Agent creates ", - llm=model, - max_loops="auto", - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - dynamic_temperature_enabled=True, - saved_state_path="finance_agent.json", - user_name="swarms_corp", - retry_attempts=3, - context_length=200000, - long_term_memory=chromadb, +# Create development agents +frontend_agent = Agent( + agent_name="Frontend-Developer", + agent_description="Expert in React and modern web development", + model_name="gpt-4o", ) +backend_agent = Agent( + agent_name="Backend-Developer", + agent_description="Specialist in Node.js and API development", + model_name="gpt-4o", +) -agent.run( - "What are the components of a startups stock incentive equity plan" +# Initialize the swarm +swarm = HierarchicalSwarm( + name="Development-Swarm", + description="A hierarchical swarm for software development", + agents=[frontend_agent, backend_agent], + max_loops=1, + verbose=True, ) +# Execute a single step +task = "Create a simple web app for file upload and download" +feedback = swarm.step(task=task) +print("Director Feedback:", feedback) ``` -### Document Ingestion +### `batched_run(tasks, img=None, *args, **kwargs)` -The Swarm Agent can ingest various types of documents, such as PDFs, text files, Markdown files, and JSON files. You can pass a list of document paths or contents to the `docs` parameter when initializing the `Agent`. +Executes the hierarchical swarm for a list of tasks, processing each task through the complete workflow. -```python -from swarms.structs import Agent +#### Parameters -# Initialize the agent with documents -agent = Agent(llm=llm, max_loops=3, docs=["path/to/doc1.pdf", "path/to/doc2.txt"]) -``` +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `tasks` | `List[str]` | **Required** | List of tasks to be processed | +| `img` | `str` | `None` | Optional image input for the agents | +| `*args` | `Any` | - | Additional positional arguments | +| `**kwargs` | `Any` | - | Additional keyword arguments | -### Interactive Mode +#### Returns -The Swarm Agent supports an interactive mode, where users can engage in real-time communication with the agent. To enable interactive mode, set the `interactive` parameter to `True` when initializing the `Agent`. +| Type | Description | +|------|-------------| +| `List[Any]` | List of results for each task | -```python -from swarms.structs import Agent +#### Example -# Initialize the agent in interactive mode -agent = Agent(llm=llm, max_loops=3, interactive=True) +```python +from swarms import Agent +from swarms.structs.hiearchical_swarm import HierarchicalSwarm -# Run the agent in interactive mode -agent.interactive_run() -``` +# Create analysis agents +market_agent = Agent( + agent_name="Market-Analyst", + agent_description="Expert in market analysis and trends", + model_name="gpt-4o", +) -### Sentiment Analysis +technical_agent = Agent( + agent_name="Technical-Analyst", + agent_description="Specialist in technical analysis and patterns", + model_name="gpt-4o", +) -The Swarm Agent can perform sentiment analysis on its generated outputs using a sentiment analyzer function. You can pass a callable function to the `sentiment_analyzer` parameter when initializing the `Agent`. +# Initialize the swarm +swarm = HierarchicalSwarm( + name="Analysis-Swarm", + description="A hierarchical swarm for comprehensive analysis", + agents=[market_agent, technical_agent], + max_loops=2, + verbose=True, +) -```python -from swarms.structs import Agent -from my_sentiment_analyzer import sentiment_analyzer_function +# Execute multiple tasks +tasks = [ + "Analyze Apple (AAPL) stock performance", + "Evaluate Microsoft (MSFT) market position", + "Assess Google (GOOGL) competitive landscape" +] -# Initialize the agent with a sentiment analyzer -agent = Agent( - agent_name = "sentiment-analyzer-agent-01", system_prompt="..." - llm=llm, max_loops=3, sentiment_analyzer=sentiment_analyzer_function) +results = swarm.batched_run(tasks=tasks) +for i, result in enumerate(results): + print(f"Task {i+1} Result:", result) ``` +## Advanced Usage Examples -### Undo Functionality +### Financial Analysis Swarm ```python -# Feature 2: Undo functionality -response = agent.run("Another task") -print(f"Response: {response}") -previous_state, message = agent.undo_last() -print(message) -``` +from swarms import Agent +from swarms.structs.hiearchical_swarm import HierarchicalSwarm + +# Create specialized financial agents +market_research_agent = Agent( + agent_name="Market-Research-Specialist", + agent_description="Expert in market research, trend analysis, and competitive intelligence", + system_prompt="""You are a senior market research specialist with expertise in: + - Market trend analysis and forecasting + - Competitive landscape assessment + - Consumer behavior analysis + - Industry report generation + - Market opportunity identification + - Risk assessment and mitigation strategies""", + model_name="claude-3-sonnet-20240229", +) -### Response Filtering +financial_analyst_agent = Agent( + agent_name="Financial-Analysis-Expert", + agent_description="Specialist in financial statement analysis, valuation, and investment research", + system_prompt="""You are a senior financial analyst with deep expertise in: + - Financial statement analysis (income statement, balance sheet, cash flow) + - Valuation methodologies (DCF, comparable company analysis, precedent transactions) + - Investment research and due diligence + - Financial modeling and forecasting + - Risk assessment and portfolio analysis + - ESG (Environmental, Social, Governance) analysis""", + model_name="claude-3-sonnet-20240229", +) -```python -# Feature 3: Response filtering -agent.add_response_filter("report") -response = agent.filtered_run("Generate a report on finance") -print(response) +# Initialize the hierarchical swarm +financial_analysis_swarm = HierarchicalSwarm( + name="Financial-Analysis-Hierarchical-Swarm", + description="A hierarchical swarm for comprehensive financial analysis with specialized agents", + agents=[market_research_agent, financial_analyst_agent], + max_loops=2, + verbose=True, +) + +# Execute financial analysis +task = "Conduct a comprehensive analysis of Tesla (TSLA) stock including market position, financial health, and investment potential" +result = financial_analysis_swarm.run(task=task) +print(result) ``` -### Saving and Loading State +### Development Department Swarm ```python -# Save the agent state -agent.save_state('saved_flow.json') - -# Load the agent state -agent = Agent(llm=llm_instance, max_loops=5) -agent.load('saved_flow.json') -agent.run("Continue with the task") -``` +from swarms import Agent +from swarms.structs.hiearchical_swarm import HierarchicalSwarm + +# Create specialized development agents +frontend_developer_agent = Agent( + agent_name="Frontend-Developer", + agent_description="Senior frontend developer expert in modern web technologies and user experience", + system_prompt="""You are a senior frontend developer with expertise in: + - Modern JavaScript frameworks (React, Vue, Angular) + - TypeScript and modern ES6+ features + - CSS frameworks and responsive design + - State management (Redux, Zustand, Context API) + - Web performance optimization + - Accessibility (WCAG) and SEO best practices""", + model_name="claude-3-sonnet-20240229", +) -### Async and Concurrent Execution +backend_developer_agent = Agent( + agent_name="Backend-Developer", + agent_description="Senior backend developer specializing in server-side development and API design", + system_prompt="""You are a senior backend developer with expertise in: + - Server-side programming languages (Python, Node.js, Java, Go) + - Web frameworks (Django, Flask, Express, Spring Boot) + - Database design and optimization (SQL, NoSQL) + - API design and REST/GraphQL implementation + - Authentication and authorization systems + - Microservices architecture and containerization""", + model_name="claude-3-sonnet-20240229", +) -```python -# Run a task concurrently -response = await agent.run_concurrent("Concurrent task") -print(response) +# Initialize the development swarm +development_department_swarm = HierarchicalSwarm( + name="Autonomous-Development-Department", + description="A fully autonomous development department with specialized agents", + agents=[frontend_developer_agent, backend_developer_agent], + max_loops=3, + verbose=True, +) -# Run multiple tasks concurrently -tasks = [ - {"task": "Task 1"}, - {"task": "Task 2", "img": "path/to/image.jpg"}, - {"task": "Task 3", "custom_param": 42} -] -responses = agent.bulk_run(tasks) -print(responses) +# Execute development project +task = "Create a simple web app that allows users to upload a file and then download it. The app should be built with React and Node.js." +result = development_department_swarm.run(task=task) +print(result) ``` +## Output Types -### Various other settings +The `HierarchicalSwarm` supports various output formats through the `output_type` parameter: -```python -# # Convert the agent object to a dictionary -print(agent.to_dict()) -print(agent.to_toml()) -print(agent.model_dump_json()) -print(agent.model_dump_yaml()) +| Output Type | Description | Use Case | +|-------------|-------------|----------| +| `"dict-all-except-first"` | Returns all conversation history as a dictionary, excluding the first message | Default format for comprehensive analysis | +| `"dict"` | Returns conversation history as a dictionary | When you need structured data | +| `"str"` | Returns conversation history as a string | For simple text output | +| `"list"` | Returns conversation history as a list | For sequential processing | -# Ingest documents into the agent's knowledge base -agent.ingest_docs("your_pdf_path.pdf") +## Best Practices -# Receive a message from a user and process it -agent.receive_message(name="agent_name", message="message") +1. **Agent Specialization**: Create agents with specific, well-defined expertise areas +2. **Clear Task Descriptions**: Provide detailed, actionable task descriptions +3. **Appropriate Loop Count**: Set `max_loops` based on task complexity (1-3 for most tasks) +4. **Verbose Logging**: Enable verbose mode during development for debugging +5. **Context Preservation**: Leverage the built-in conversation history for continuity +6. **Error Handling**: Implement proper error handling for production use -# Send a message from the agent to a user -agent.send_agent_message(agent_name="agent_name", message="message") +## Error Handling -# Ingest multiple documents into the agent's knowledge base -agent.ingest_docs("your_pdf_path.pdf", "your_csv_path.csv") +The `HierarchicalSwarm` includes comprehensive error handling with detailed logging. Common issues and solutions: -# Run the agent with a filtered system prompt -agent.filtered_run( - "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?" -) +- **No Agents**: Ensure at least one agent is provided +- **Invalid Director**: Verify the director agent is properly configured +- **Max Loops**: Set `max_loops` to a value greater than 0 +- **Model Issues**: Check that all agents have valid model configurations -# Run the agent with multiple system prompts -agent.bulk_run( - [ - "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?", - "Another system prompt", - ] -) +## Performance Considerations -# Add a memory to the agent -agent.add_memory("Add a memory to the agent") +- **Loop Optimization**: Balance between thoroughness and performance with `max_loops` +- **Agent Count**: More agents increase coordination overhead +- **Model Selection**: Choose appropriate models for your use case and budget +- **Verbose Mode**: Disable verbose logging in production for better performance -# Check the number of available tokens for the agent -agent.check_available_tokens() +-------------------------------------------------- -# Perform token checks for the agent -agent.tokens_checks() +# File: swarms\structs\image_batch_agent.md -# Print the dashboard of the agent -agent.print_dashboard() +# ImageAgentBatchProcessor Documentation +## Overview -# Fetch all the documents from the doc folders -agent.get_docs_from_doc_folders() +The `ImageAgentBatchProcessor` is a high-performance parallel image processing system designed for running AI agents on multiple images concurrently. It provides robust error handling, logging, and flexible configuration options. -# Activate agent ops +## Installation -# Dump the model to a JSON file -agent.model_dump_json() -print(agent.to_toml()) +```bash +pip install swarms ``` --------------------------------------------------- - -# File: swarms/structs/agent_rearrange.md - -# `AgentRearrange` Class - -The `AgentRearrange` class represents a swarm of agents for rearranging tasks. It allows you to create a swarm of agents, add or remove agents from the swarm, and run the swarm to process tasks based on a specified flow pattern. - -## Attributes ----------- - -| Attribute | Type | Description | -| --- | --- | --- | -| `id` | `str` | Unique identifier for the swarm | -| `name` | `str` | Name of the swarm | -| `description` | `str` | Description of the swarm's purpose | -| `agents` | `dict` | Dictionary mapping agent names to Agent objects | -| `flow` | `str` | Flow pattern defining task execution order | -| `max_loops` | `int` | Maximum number of execution loops | -| `verbose` | `bool` | Whether to enable verbose logging | -| `memory_system` | `BaseVectorDatabase` | Memory system for storing agent interactions | -| `human_in_the_loop` | `bool` | Whether human intervention is enabled | -| `custom_human_in_the_loop` | `Callable` | Custom function for human intervention | -| `return_json` | `bool` | Whether to return output in JSON format | -| `output_type` | `OutputType` | Format of output ("all", "final", "list", or "dict") | -| `docs` | `List[str]` | List of document paths to add to agent prompts | -| `doc_folder` | `str` | Folder path containing documents to add to agent prompts | -| `swarm_history` | `dict` | History of agent interactions | +## Class Arguments +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| agents | Union[Agent, List[Agent], Callable, List[Callable]] | Required | Single agent or list of agents to process images | +| max_workers | int | None | Maximum number of parallel workers (defaults to 95% of CPU cores) | +| supported_formats | List[str] | ['.jpg', '.jpeg', '.png'] | List of supported image file extensions | ## Methods -------- -### `__init__(self, agents: List[Agent] = None, flow: str = None, max_loops: int = 1, verbose: bool = True)` +### run() -Initializes the `AgentRearrange` object. +**Description**: Main method for processing multiple images in parallel with configured agents. Can handle single images, multiple images, or entire directories. -| Parameter | Type | Description | -| --- | --- | --- | -| `agents` | `List[Agent]` (optional) | A list of `Agent` objects. Defaults to `None`. | -| `flow` | `str` (optional) | The flow pattern of the tasks. Defaults to `None`. | -| `max_loops` | `int` (optional) | The maximum number of loops for the agents to run. Defaults to `1`. | -| `verbose` | `bool` (optional) | Whether to enable verbose logging or not. Defaults to `True`. | +**Arguments**: -### `add_agent(self, agent: Agent)` +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| image_paths | Union[str, List[str], Path] | Yes | Single image path, list of paths, or directory path | +| tasks | Union[str, List[str]] | Yes | Single task or list of tasks to perform on each image | -Adds an agent to the swarm. +**Returns**: List[Dict[str, Any]] - List of processing results for each image -| Parameter | Type | Description | -| --- | --- | --- | -| `agent` | `Agent` | The agent to be added. | +**Example**: -### `remove_agent(self, agent_name: str)` +```python +from swarms import Agent +from swarms.structs import ImageAgentBatchProcessor +from pathlib import Path -Removes an agent from the swarm. +# Initialize agent and processor +agent = Agent(api_key="your-api-key", model="gpt-4-vision") +processor = ImageAgentBatchProcessor(agents=agent) -| Parameter | Type | Description | -| --- | --- | --- | -| `agent_name` | `str` | The name of the agent to be removed. | +# Example 1: Process single image +results = processor.run( + image_paths="path/to/image.jpg", + tasks="Describe this image" +) -### `add_agents(self, agents: List[Agent])` +# Example 2: Process multiple images +results = processor.run( + image_paths=["image1.jpg", "image2.jpg"], + tasks=["Describe objects", "Identify colors"] +) -Adds multiple agents to the swarm. +# Example 3: Process directory +results = processor.run( + image_paths=Path("./images"), + tasks="Analyze image content" +) +``` -| Parameter | Type | Description | -| --- | --- | --- | -| `agents` | `List[Agent]` | A list of `Agent` objects. | +### _validate_image_path() -### `validate_flow(self)` +**Description**: Internal method that validates if an image path exists and has a supported format. -Validates the flow pattern. +**Arguments**: -**Raises:** +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| image_path | Union[str, Path] | Yes | Path to the image file to validate | -- `ValueError`: If the flow pattern is incorrectly formatted or contains duplicate agent names. +**Returns**: Path - Validated Path object -**Returns:** +**Example**: +```python -- `bool`: `True` if the flow pattern is valid. +from swarms.structs import ImageAgentBatchProcessor, ImageProcessingError +from pathlib import Path -### `run(self, task: str = None, img: str = None, device: str = "cpu", device_id: int = 1, all_cores: bool = True, all_gpus: bool = False, *args, **kwargs)` +processor = ImageAgentBatchProcessor(agents=agent) -Executes the agent rearrangement task with specified compute resources. +try: + validated_path = processor._validate_image_path("image.jpg") + print(f"Valid image path: {validated_path}") +except ImageProcessingError as e: + print(f"Invalid image path: {e}") +``` -| Parameter | Type | Description | -| --- | --- | --- | -| `task` | `str` | The task to execute | -| `img` | `str` | Path to input image if required | -| `device` | `str` | Computing device to use ('cpu' or 'gpu') | -| `device_id` | `int` | ID of specific device to use | -| `all_cores` | `bool` | Whether to use all CPU cores | -| `all_gpus` | `bool` | Whether to use all available GPUs | +### _process_single_image() -**Returns:** +**Description**: Internal method that processes a single image with one agent and one or more tasks. -- `str`: The final processed task. +**Arguments**: -### `batch_run(self, tasks: List[str], img: Optional[List[str]] = None, batch_size: int = 10, device: str = "cpu", device_id: int = None, all_cores: bool = True, all_gpus: bool = False, *args, **kwargs)` +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| image_path | Path | Yes | Path to the image to process | +| tasks | Union[str, List[str]] | Yes | Tasks to perform on the image | +| agent | Agent | Yes | Agent to use for processing | -Process multiple tasks in batches. +**Returns**: Dict[str, Any] - Processing results for the image -| Parameter | Type | Description | -| --- | --- | --- | -| `tasks` | `List[str]` | List of tasks to process | -| `img` | `List[str]` | Optional list of images corresponding to tasks | -| `batch_size` | `int` | Number of tasks to process simultaneously | -| `device` | `str` | Computing device to use | -| `device_id` | `int` | Specific device ID if applicable | -| `all_cores` | `bool` | Whether to use all CPU cores | -| `all_gpus` | `bool` | Whether to use all available GPUs | +**Example**: + +```python +from swarms import Agent +from swarms.structs import ImageAgentBatchProcessor +from pathlib import Path +agent = Agent(api_key="your-api-key", model="gpt-4-vision") +processor = ImageAgentBatchProcessor(agents=agent) +try: + result = processor._process_single_image( + image_path=Path("image.jpg"), + tasks=["Describe image", "Identify objects"], + agent=agent + ) + print(f"Processing results: {result}") +except Exception as e: + print(f"Processing failed: {e}") +``` -### `concurrent_run(self, tasks: List[str], img: Optional[List[str]] = None, max_workers: Optional[int] = None, device: str = "cpu", device_id: int = None, all_cores: bool = True, all_gpus: bool = False, *args, **kwargs)` +### __call__() -Process multiple tasks concurrently using ThreadPoolExecutor. +**Description**: Makes the ImageAgentBatchProcessor callable like a function. Redirects to the run() method. -| Parameter | Type | Description | -| --- | --- | --- | -| `tasks` | `List[str]` | List of tasks to process | -| `img` | `List[str]` | Optional list of images corresponding to tasks | -| `max_workers` | `int` | Maximum number of worker threads | -| `device` | `str` | Computing device to use | -| `device_id` | `int` | Specific device ID if applicable | -| `all_cores` | `bool` | Whether to use all CPU cores | -| `all_gpus` | `bool` | Whether to use all available GPUs | +**Arguments**: +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| *args | Any | No | Variable length argument list passed to run() | +| **kwargs | Any | No | Keyword arguments passed to run() | +**Returns**: List[Dict[str, Any]] - Same as run() method -## Documentation for `rearrange` Function -====================================== +**Example**: -The `rearrange` function is a helper function that rearranges the given list of agents based on the specified flow. +```python +from swarms import Agent +from swarms.structs import ImageAgentBatchProcessor -## Parameters ----------- +# Initialize +agent = Agent(api_key="your-api-key", model="gpt-4-vision") +processor = ImageAgentBatchProcessor(agents=agent) -| Parameter | Type | Description | -| --- | --- | --- | -| `agents` | `List[Agent]` | The list of agents to be rearranged. | -| `flow` | `str` | The flow used for rearranging the agents. | -| `task` | `str` (optional) | The task to be performed during rearrangement. Defaults to `None`. | -| `*args` | - | Additional positional arguments. | -| `**kwargs` | - | Additional keyword arguments. | +# Using __call__ +results = processor( + image_paths=["image1.jpg", "image2.jpg"], + tasks="Describe the image" +) -## Returns -------- +# This is equivalent to: +results = processor.run( + image_paths=["image1.jpg", "image2.jpg"], + tasks="Describe the image" +) +``` -The result of running the agent system with the specified task. +## Return Format -### Example -------- +The processor returns a list of dictionaries with the following structure: ```python -agents = [agent1, agent2, agent3] -flow = "agent1 -> agent2, agent3" -task = "Perform a task" -rearrange(agents, flow, task) +{ + "image_path": str, # Path to the processed image + "results": { # Results for each task + "task_name": result, # Task-specific results + }, + "processing_time": float # Processing time in seconds +} ``` -### Example Usage -------------- +## Complete Usage Examples -Here's an example of how to use the `AgentRearrange` class and the `rearrange` function: +### 1. Basic Usage with Single Agent ```python -from swarms import Agent, AgentRearrange -from typing import List +from swarms import Agent +from swarms.structs import ImageAgentBatchProcessor -# Initialize the director agent -director = Agent( - agent_name="Accounting Director", - system_prompt="Directs the accounting tasks for the workers", - llm=Anthropic(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="accounting_director.json", +# Initialize an agent +agent = Agent( + api_key="your-api-key", + model="gpt-4-vision" ) -# Initialize worker 1 -worker1 = Agent( - agent_name="Accountant 1", - system_prompt="Processes financial transactions and prepares financial statements", - llm=Anthropic(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="accountant1.json", -) +# Create processor +processor = ImageAgentBatchProcessor(agents=agent) -# Initialize worker 2 -worker2 = Agent( - agent_name="Accountant 2", - system_prompt="Performs audits and ensures compliance with financial regulations", - llm=Anthropic(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="accountant2.json", +# Process single image +results = processor.run( + image_paths="path/to/image.jpg", + tasks="Describe this image in detail" ) +``` -# Create a list of agents -agents = [director, worker1, worker2] +### 2. Processing Multiple Images with Multiple Tasks -# Define the flow pattern -flow = "Accounting Director -> Accountant 1 -> Accountant 2" +```python +# Initialize with multiple agents +agent1 = Agent(api_key="key1", model="gpt-4-vision") +agent2 = Agent(api_key="key2", model="claude-3") -# Using AgentRearrange class -agent_system = AgentRearrange(agents=agents, flow=flow) -output = agent_system.run("Process monthly financial statements") -print(output) +processor = ImageAgentBatchProcessor( + agents=[agent1, agent2], + supported_formats=['.jpg', '.png', '.webp'] +) -``` +# Define multiple tasks +tasks = [ + "Describe the main objects in the image", + "What is the dominant color?", + "Identify any text in the image" +] -In this example, we first initialize three agents: `director`, `worker1`, and `worker2`. Then, we create a list of these agents and define the flow pattern `"Director -> Worker1 -> Worker2"`. +# Process a directory of images +results = processor.run( + image_paths="path/to/image/directory", + tasks=tasks +) -We can use the `AgentRearrange` class by creating an instance of it with the list of agents and the flow pattern. We then call the `run` method with the initial task, and it will execute the agents in the specified order, passing the output of one agent as the input to the next agent. +# Process results +for result in results: + print(f"Image: {result['image_path']}") + for task, output in result['results'].items(): + print(f"Task: {task}") + print(f"Result: {output}") + print(f"Processing time: {result['processing_time']:.2f} seconds") +``` -Alternatively, we can use the `rearrange` function by passing the list of agents, the flow pattern, and the initial task as arguments. +### 3. Custom Error Handling -Both the `AgentRearrange` class and the `rearrange` function will return the final output after processing the task through the agents according to the specified flow pattern. +```python +from swarms.structs import ImageAgentBatchProcessor, ImageProcessingError -## Error Handling --------------- +try: + processor = ImageAgentBatchProcessor(agents=agent) + results = processor.run( + image_paths=["image1.jpg", "image2.png", "invalid.txt"], + tasks="Analyze the image" + ) +except ImageProcessingError as e: + print(f"Image processing failed: {e}") +except InvalidAgentError as e: + print(f"Agent configuration error: {e}") +``` -The `AgentRearrange` class includes error handling mechanisms to validate the flow pattern. If the flow pattern is incorrectly formatted or contains duplicate agent names, a `ValueError` will be raised with an appropriate error message. +## Best Practices -### Example: +| Best Practice | Description | +|--------------|-------------| +| Resource Management | • The processor automatically uses 95% of available CPU cores
• For memory-intensive operations, consider reducing `max_workers` | +| Error Handling | • Always wrap processor calls in try-except blocks
• Check the results for any error keys | +| Task Design | • Keep tasks focused and specific
• Group related tasks together for efficiency | +| Performance Optimization | • Process images in batches for better throughput
• Use multiple agents for different types of analysis | -```python -# Invalid flow pattern -invalid_flow = "Director->Worker1,Worker2->Worker3" -agent_system = AgentRearrange(agents=agents, flow=invalid_flow) -output = agent_system.run("Some task")` -``` +## Limitations -This will raise a `ValueError` with the message `"Agent 'Worker3' is not registered."`. +| Limitation | Description | +|------------|-------------| +| File Format Support | Only supports image file formats specified in `supported_formats` | +| Agent Requirements | Requires valid agent configurations | +| Resource Scaling | Memory usage scales with number of concurrent processes | -## Parallel and Sequential Processing ----------------------------------- +This documentation provides a comprehensive guide to using the `ImageAgentBatchProcessor`. The class is designed to be both powerful and flexible, allowing for various use cases from simple image analysis to complex multi-agent processing pipelines. -The `AgentRearrange` class supports both parallel and sequential processing of tasks based on the specified flow pattern. If the flow pattern includes multiple agents separated by commas (e.g., `"agent1, agent2"`), the agents will be executed in parallel, and their outputs will be concatenated with a semicolon (`;`). If the flow pattern includes a single agent, it will be executed sequentially. +-------------------------------------------------- -### Parallel processing -`parallel_flow = "Worker1, Worker2 -> Director"` +# File: swarms\structs\index.md -### Sequential processing -`sequential_flow = "Worker1 -> Worker2 -> Director"` +# Introduction to Multi-Agent Collaboration -In the `parallel_flow` example, `Worker1` and `Worker2` will be executed in parallel, and their outputs will be concatenated and passed to `Director`. In the `sequential_flow` example, `Worker1` will be executed first, and its output will be passed to `Worker2`, and then the output of `Worker2` will be passed to `Director`. +--- -## Logging -------- +## 🚀 Benefits of Multi-Agent Collaboration -The `AgentRearrange` class includes logging capabilities using the `loguru` library. If `verbose` is set to `True` during initialization, a log file named `agent_rearrange.log` will be created, and log messages will be written to it. You can use this log file to track the execution of the agents and any potential issues or errors that may occur. +
+ Benefits of Multi-Agent Collaboration +
+ Fig. 1: Key benefits and structure of multi-agent collaboration +
+### Why Multi-Agent Architectures? -```bash -2023-05-08 10:30:15.456 | INFO | agent_rearrange:__init__:34 - Adding agent Director to the swarm. -2023-05-08 10:30:15.457 | INFO | agent_rearrange:__init__:34 - Adding agent Worker1 to the swarm. -2023-05-08 10:30:15.457 | INFO | agent_rearrange:__init__:34 - Adding agent Worker2 to the swarm. -2023-05-08 10:30:15.458 | INFO | agent_rearrange:run:118 - Running agents in parallel: ['Worker1', 'Worker2'] -2023-05-08 10:30:15.459 | INFO | agent_rearrange:run:121 - Running agents sequentially: ['Director']` -``` +Multi-agent systems unlock new levels of intelligence, reliability, and efficiency by enabling agents to work together. Here are the core benefits: -## Additional Parameters ---------------------- +1. **Reduction of Hallucination**: Cross-verification between agents ensures more accurate, reliable outputs by reducing hallucination. +2. **Extended Memory**: Agents share knowledge and task history, achieving collective long-term memory for smarter, more adaptive responses. +3. **Specialization & Task Distribution**: Delegating tasks to specialized agents boosts efficiency and quality. +4. **Parallel Processing**: Multiple agents work simultaneously, greatly increasing speed and throughput. +5. **Scalability & Adaptability**: Systems can dynamically scale and adapt, maintaining efficiency as demands change. -The `AgentRearrange` class also accepts additional parameters that can be passed to the `run` method using `*args` and `**kwargs`. These parameters will be forwarded to the individual agents during execution. +--- -`agent_system = AgentRearrange(agents=agents, flow=flow)` -`output = agent_system.run("Some task", max_tokens=200, temperature=0.7)` +## 🏗️ Multi-Agent Architectures For Production Deployments -In this example, the `max_tokens` and `temperature` parameters will be passed to each agent during execution. +`swarms` provides a variety of powerful, pre-built multi-agent architectures enabling you to orchestrate agents in various ways. Choose the right structure for your specific problem to build efficient and reliable production systems. -## Customization -------------- +| **Architecture** | **Description** | **Best For** | +|---|---|---| +| **[SequentialWorkflow](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/)** | Agents execute tasks in a linear chain; one agent's output is the next one's input. | Step-by-step processes like data transformation pipelines, report generation. | +| **[ConcurrentWorkflow](https://docs.swarms.world/en/latest/swarms/structs/concurrent_workflow/)** | Agents run tasks simultaneously for maximum efficiency. | High-throughput tasks like batch processing, parallel data analysis. | +| **[AgentRearrange](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/)** | Dynamically maps complex relationships (e.g., `a -> b, c`) between agents. | Flexible and adaptive workflows, task distribution, dynamic routing. | +| **[GraphWorkflow](https://docs.swarms.world/en/latest/swarms/structs/graph_workflow/)** | Orchestrates agents as nodes in a Directed Acyclic Graph (DAG). | Complex projects with intricate dependencies, like software builds. | +| **[MixtureOfAgents (MoA)](https://docs.swarms.world/en/latest/swarms/structs/moa/)** | Utilizes multiple expert agents in parallel and synthesizes their outputs. | Complex problem-solving, achieving state-of-the-art performance through collaboration. | +| **[GroupChat](https://docs.swarms.world/en/latest/swarms/structs/group_chat/)** | Agents collaborate and make decisions through a conversational interface. | Real-time collaborative decision-making, negotiations, brainstorming. | +| **[ForestSwarm](https://docs.swarms.world/en/latest/swarms/structs/forest_swarm/)** | Dynamically selects the most suitable agent or tree of agents for a given task. | Task routing, optimizing for expertise, complex decision-making trees. | +| **[SpreadSheetSwarm](https://docs.swarms.world/en/latest/swarms/structs/spreadsheet_swarm/)** | Manages thousands of agents concurrently, tracking tasks and outputs in a structured format. | Massive-scale parallel operations, large-scale data generation and analysis. | +| **[SwarmRouter](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/)** | Universal orchestrator that provides a single interface to run any type of swarm with dynamic selection. | Simplifying complex workflows, switching between swarm strategies, unified multi-agent management. | +| **[HierarchicalSwarm](https://docs.swarms.world/en/latest/swarms/structs/hierarchical_swarm/)** | Director agent coordinates specialized worker agents in a hierarchy. | Complex, multi-stage tasks, iterative refinement, enterprise workflows. | +| **[Hybrid Hierarchical-Cluster Swarm (HHCS)](https://docs.swarms.world/en/latest/swarms/structs/hhcs/)** | Router agent distributes tasks to specialized swarms for parallel, hierarchical processing. | Enterprise-scale, multi-domain, and highly complex workflows. | -The `AgentRearrange` class and the `rearrange` function can be customized and extended to suit specific use cases. For example, you can create custom agents by inheriting from the `Agent` class and implementing custom logic for task processing. You can then add these custom agents to the swarm and define the flow pattern accordingly. +--- -Additionally, you can modify the `run` method of the `AgentRearrange` class to implement custom logic for task processing and agent interaction. +### 🏢 HierarchicalSwarm Example +Hierarchical architectures enable structured, iterative, and scalable problem-solving by combining a director (or router) agent with specialized worker agents or swarms. Below are two key patterns: -## Limitations ------------ -It's important to note that the `AgentRearrange` class and the `rearrange` function rely on the individual agents to process tasks correctly. The quality of the output will depend on the capabilities and configurations of the agents used in the swarm. Additionally, the `AgentRearrange` class does not provide any mechanisms for task prioritization or load balancing among the agents. +```python +from swarms import Agent +from swarms.structs.hiearchical_swarm import HierarchicalSwarm -## Conclusion ----------- +# Create specialized agents +research_agent = Agent( + agent_name="Research-Specialist", + agent_description="Expert in market research and analysis", + model_name="gpt-4o", +) +financial_agent = Agent( + agent_name="Financial-Analyst", + agent_description="Specialist in financial analysis and valuation", + model_name="gpt-4o", +) -The `AgentRearrange` class and the `rearrange` function provide a flexible and extensible framework for orchestrating swarms of agents to process tasks based on a specified flow pattern. By combining the capabilities of individual agents, you can create complex workflows and leverage the strengths of different agents to tackle various tasks efficiently. +# Initialize the hierarchical swarm +swarm = HierarchicalSwarm( + name="Financial-Analysis-Swarm", + description="A hierarchical swarm for comprehensive financial analysis", + agents=[research_agent, financial_agent], + max_loops=2, + verbose=True, +) -While the current implementation offers basic functionality for agent rearrangement, there is room for future improvements and customizations to enhance the system's capabilities and cater to more specific use cases. +# Execute a complex task +result = swarm.run(task="Analyze the market potential for Tesla (TSLA) stock") +print(result) +``` -Whether you're working on natural language processing tasks, data analysis, or any other domain where agent-based systems can be beneficial, the `AgentRearrange` class and the `rearrange` function provide a solid foundation for building and experimenting with swarm-based solutions. +[Full HierarchicalSwarm Documentation →](https://docs.swarms.world/en/latest/swarms/structs/hierarchical_swarm/) --------------------------------------------------- -# File: swarms/structs/agent_registry.md -# AgentRegistry Documentation +### SequentialWorkflow -The `AgentRegistry` class is designed to manage a collection of agents, providing methods for adding, deleting, updating, and querying agents. This class ensures thread-safe operations on the registry, making it suitable for concurrent environments. Additionally, the `AgentModel` class is a Pydantic model used for validating and storing agent information. +A `SequentialWorkflow` executes tasks in a strict order, forming a pipeline where each agent builds upon the work of the previous one. `SequentialWorkflow` is Ideal for processes that have clear, ordered steps. This ensures that tasks with dependencies are handled correctly. -## Attributes +```python +from swarms import Agent, SequentialWorkflow -### AgentModel +# Initialize agents for a 3-step process +# 1. Generate an idea +idea_generator = Agent(agent_name="IdeaGenerator", system_prompt="Generate a unique startup idea.", model_name="gpt-4o-mini") +# 2. Validate the idea +validator = Agent(agent_name="Validator", system_prompt="Take this startup idea and analyze its market viability.", model_name="gpt-4o-mini") +# 3. Create a pitch +pitch_creator = Agent(agent_name="PitchCreator", system_prompt="Write a 3-sentence elevator pitch for this validated startup idea.", model_name="gpt-4o-mini") -| Attribute | Type | Description | -|-----------|--------|--------------------------------------| -| `agent_id`| `str` | The unique identifier for the agent. | -| `agent` | `Agent`| The agent object. | +# Create the sequential workflow +workflow = SequentialWorkflow(agents=[idea_generator, validator, pitch_creator]) -### AgentRegistry +# Run the workflow +elevator_pitch = workflow.run() +print(elevator_pitch) +``` -| Attribute | Type | Description | -|-----------|---------------------|-------------------------------------------| -| `agents` | `Dict[str, AgentModel]` | A dictionary mapping agent IDs to `AgentModel` instances. | -| `lock` | `Lock` | A threading lock for thread-safe operations. | +### ConcurrentWorkflow (with `SpreadSheetSwarm`) -## Methods +A concurrent workflow runs multiple agents simultaneously. `SpreadSheetSwarm` is a powerful implementation that can manage thousands of concurrent agents and log their outputs to a CSV file. Use this architecture for high-throughput tasks that can be performed in parallel, drastically reducing execution time. -### `__init__(self)` +```python +from swarms import Agent, SpreadSheetSwarm -Initializes the `AgentRegistry` object. +# Define a list of tasks (e.g., social media posts to generate) +platforms = ["Twitter", "LinkedIn", "Instagram"] -- **Usage Example:** - ```python - registry = AgentRegistry() - ``` +# Create an agent for each task +agents = [ + Agent( + agent_name=f"{platform}-Marketer", + system_prompt=f"Generate a real estate marketing post for {platform}.", + model_name="gpt-4o-mini", + ) + for platform in platforms +] -### `add(self, agent_id: str, agent: Agent) -> None` +# Initialize the swarm to run these agents concurrently +swarm = SpreadSheetSwarm( + agents=agents, + autosave_on=True, + save_file_path="marketing_posts.csv", +) -Adds a new agent to the registry. +# Run the swarm with a single, shared task description +property_description = "A beautiful 3-bedroom house in sunny California." +swarm.run(task=f"Generate a post about: {property_description}") +# Check marketing_posts.csv for the results! +``` -- **Parameters:** - - `agent_id` (`str`): The unique identifier for the agent. - - `agent` (`Agent`): The agent to add. +### AgentRearrange -- **Raises:** - - `ValueError`: If the agent ID already exists in the registry. - - `ValidationError`: If the input data is invalid. +Inspired by `einsum`, `AgentRearrange` lets you define complex, non-linear relationships between agents using a simple string-based syntax. [Learn more](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/). This architecture is Perfect for orchestrating dynamic workflows where agents might work in parallel, sequence, or a combination of both. -- **Usage Example:** - ```python - agent = Agent(agent_name="Agent1") - registry.add("agent_1", agent) - ``` +```python +from swarms import Agent, AgentRearrange -### `delete(self, agent_id: str) -> None` +# Define agents +researcher = Agent(agent_name="researcher", model_name="gpt-4o-mini") +writer = Agent(agent_name="writer", model_name="gpt-4o-mini") +editor = Agent(agent_name="editor", model_name="gpt-4o-mini") -Deletes an agent from the registry. +# Define a flow: researcher sends work to both writer and editor simultaneously +# This is a one-to-many relationship +flow = "researcher -> writer, editor" -- **Parameters:** - - `agent_id` (`str`): The unique identifier for the agent to delete. +# Create the rearrangement system +rearrange_system = AgentRearrange( + agents=[researcher, writer, editor], + flow=flow, +) -- **Raises:** - - `KeyError`: If the agent ID does not exist in the registry. +# Run the system +# The researcher will generate content, and then both the writer and editor +# will process that content in parallel. +outputs = rearrange_system.run("Analyze the impact of AI on modern cinema.") +print(outputs) +``` -- **Usage Example:** - ```python - registry.delete("agent_1") - ``` +--- -### `update_agent(self, agent_id: str, new_agent: Agent) -> None` +### SwarmRouter: The Universal Swarm Orchestrator -Updates an existing agent in the registry. +The `SwarmRouter` simplifies building complex workflows by providing a single interface to run any type of swarm. Instead of importing and managing different swarm classes, you can dynamically select the one you need just by changing the `swarm_type` parameter. [Read the full documentation](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/) -- **Parameters:** - - `agent_id` (`str`): The unique identifier for the agent to update. - - `new_agent` (`Agent`): The new agent to replace the existing one. +This makes your code cleaner and more flexible, allowing you to switch between different multi-agent strategies with ease. Here's a complete example that shows how to define agents and then use `SwarmRouter` to execute the same task using different collaborative strategies. -- **Raises:** - - `KeyError`: If the agent ID does not exist in the registry. - - `ValidationError`: If the input data is invalid. +```python +from swarms import Agent +from swarms.structs.swarm_router import SwarmRouter, SwarmType + +# Define a few generic agents +writer = Agent(agent_name="Writer", system_prompt="You are a creative writer.", model_name="gpt-4o-mini") +editor = Agent(agent_name="Editor", system_prompt="You are an expert editor for stories.", model_name="gpt-4o-mini") +reviewer = Agent(agent_name="Reviewer", system_prompt="You are a final reviewer who gives a score.", model_name="gpt-4o-mini") + +# The agents and task will be the same for all examples +agents = [writer, editor, reviewer] +task = "Write a short story about a robot who discovers music." + +# --- Example 1: SequentialWorkflow --- +# Agents run one after another in a chain: Writer -> Editor -> Reviewer. +print("Running a Sequential Workflow...") +sequential_router = SwarmRouter(swarm_type=SwarmType.SequentialWorkflow, agents=agents) +sequential_output = sequential_router.run(task) +print(f"Final Sequential Output:\n{sequential_output}\n") + +# --- Example 2: ConcurrentWorkflow --- +# All agents receive the same initial task and run at the same time. +print("Running a Concurrent Workflow...") +concurrent_router = SwarmRouter(swarm_type=SwarmType.ConcurrentWorkflow, agents=agents) +concurrent_outputs = concurrent_router.run(task) +# This returns a dictionary of each agent's output +for agent_name, output in concurrent_outputs.items(): + print(f"Output from {agent_name}:\n{output}\n") + +# --- Example 3: MixtureOfAgents --- +# All agents run in parallel, and a special 'aggregator' agent synthesizes their outputs. +print("Running a Mixture of Agents Workflow...") +aggregator = Agent( + agent_name="Aggregator", + system_prompt="Combine the story, edits, and review into a final document.", + model_name="gpt-4o-mini" +) +moa_router = SwarmRouter( + swarm_type=SwarmType.MixtureOfAgents, + agents=agents, + aggregator_agent=aggregator, # MoA requires an aggregator +) +aggregated_output = moa_router.run(task) +print(f"Final Aggregated Output:\n{aggregated_output}\n") +``` -- **Usage Example:** - ```python - new_agent = Agent(agent_name="UpdatedAgent") - registry.update_agent("agent_1", new_agent) - ``` -### `get(self, agent_id: str) -> Agent` +The `SwarmRouter` is a powerful tool for simplifying multi-agent orchestration. It provides a consistent and flexible way to deploy different collaborative strategies, allowing you to build more sophisticated applications with less code. -Retrieves an agent from the registry. +--- -- **Parameters:** - - `agent_id` (`str`): The unique identifier for the agent to retrieve. +### MixtureOfAgents (MoA) -- **Returns:** - - `Agent`: The agent associated with the given agent ID. +The `MixtureOfAgents` architecture processes tasks by feeding them to multiple "expert" agents in parallel. Their diverse outputs are then synthesized by an aggregator agent to produce a final, high-quality result. [Learn more here](https://docs.swarms.world/en/latest/swarms/examples/moa_example/) -- **Raises:** - - `KeyError`: If the agent ID does not exist in the registry. +```python +from swarms import Agent, MixtureOfAgents -- **Usage Example:** - ```python - agent = registry.get("agent_1") - ``` +# Define expert agents +financial_analyst = Agent(agent_name="FinancialAnalyst", system_prompt="Analyze financial data.", model_name="gpt-4o-mini") +market_analyst = Agent(agent_name="MarketAnalyst", system_prompt="Analyze market trends.", model_name="gpt-4o-mini") +risk_analyst = Agent(agent_name="RiskAnalyst", system_prompt="Analyze investment risks.", model_name="gpt-4o-mini") -### `list_agents(self) -> List[str]` +# Define the aggregator agent +aggregator = Agent( + agent_name="InvestmentAdvisor", + system_prompt="Synthesize the financial, market, and risk analyses to provide a final investment recommendation.", + model_name="gpt-4o-mini" +) -Lists all agent identifiers in the registry. +# Create the MoA swarm +moa_swarm = MixtureOfAgents( + agents=[financial_analyst, market_analyst, risk_analyst], + aggregator_agent=aggregator, +) -- **Returns:** - - `List[str]`: A list of all agent identifiers. +# Run the swarm +recommendation = moa_swarm.run("Should we invest in NVIDIA stock right now?") +print(recommendation) +``` -- **Usage Example:** - ```python - agent_ids = registry.list_agents() - ``` +--- -### `query(self, condition: Optional[Callable[[Agent], bool]] = None) -> List[Agent]` +### GroupChat -Queries agents based on a condition. +`GroupChat` creates a conversational environment where multiple agents can interact, discuss, and collaboratively solve a problem. You can define the speaking order or let it be determined dynamically. This architecture is ideal for tasks that benefit from debate and multi-perspective reasoning, such as contract negotiation, brainstorming, or complex decision-making. -- **Parameters:** - - `condition` (`Optional[Callable[[Agent], bool]]`): A function that takes an agent and returns a boolean indicating whether the agent meets the condition. Defaults to `None`. +```python +from swarms import Agent, GroupChat -- **Returns:** - - `List[Agent]`: A list of agents that meet the condition. +# Define agents for a debate +tech_optimist = Agent(agent_name="TechOptimist", system_prompt="Argue for the benefits of AI in society.", model_name="gpt-4o-mini") +tech_critic = Agent(agent_name="TechCritic", system_prompt="Argue against the unchecked advancement of AI.", model_name="gpt-4o-mini") -- **Usage Example:** - ```python - def is_active(agent): - return agent.is_active +# Create the group chat +chat = GroupChat( + agents=[tech_optimist, tech_critic], + max_loops=4, # Limit the number of turns in the conversation +) - active_agents = registry.query(is_active) - ``` +# Run the chat with an initial topic +conversation_history = chat.run( + "Let's discuss the societal impact of artificial intelligence." +) -### `find_agent_by_name(self, agent_name: str) -> Agent` +# Print the full conversation +for message in conversation_history: + print(f"[{message['agent_name']}]: {message['content']}") +``` -Finds an agent by its name. +-- -- **Parameters:** - - `agent_name` (`str`): The name of the agent to find. +## Connect With Us -- **Returns:** - - `Agent`: The agent with the specified name. +Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights! -- **Usage Example:** - ```python - agent = registry.find_agent_by_name("Agent1") - ``` +| Platform | Description | Link | +|----------|-------------|------| +| 📚 Documentation | Official documentation and guides | [docs.swarms.world](https://docs.swarms.world) | +| 📝 Blog | Latest updates and technical articles | [Medium](https://medium.com/@kyeg) | +| 💬 Discord | Live chat and community support | [Join Discord](https://discord.gg/jM3Z6M9uMq) | +| 🐦 Twitter | Latest news and announcements | [@kyegomez](https://twitter.com/kyegomez) | +| 👥 LinkedIn | Professional network and updates | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | +| 📺 YouTube | Tutorials and demos | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | +| 🎫 Events | Join our community events | [Sign up here](https://lu.ma/5p2jnc2v) | +| 🚀 Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) | +--- -### Full Example -```python -from swarms.structs.agent_registry import AgentRegistry -from swarms import Agent, OpenAIChat, Anthropic -# Initialize the agents -growth_agent1 = Agent( - agent_name="Marketing Specialist", - system_prompt="You're the marketing specialist, your purpose is to help companies grow by improving their marketing strategies!", - agent_description="Improve a company's marketing strategies!", - llm=OpenAIChat(), - max_loops="auto", - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - saved_state_path="marketing_specialist.json", - stopping_token="Stop!", - interactive=True, - context_length=1000, -) +-------------------------------------------------- -growth_agent2 = Agent( - agent_name="Sales Specialist", - system_prompt="You're the sales specialist, your purpose is to help companies grow by improving their sales strategies!", - agent_description="Improve a company's sales strategies!", - llm=Anthropic(), - max_loops="auto", - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - saved_state_path="sales_specialist.json", - stopping_token="Stop!", - interactive=True, - context_length=1000, -) +# File: swarms\structs\interactive_groupchat.md -growth_agent3 = Agent( - agent_name="Product Development Specialist", - system_prompt="You're the product development specialist, your purpose is to help companies grow by improving their product development strategies!", - agent_description="Improve a company's product development strategies!", - llm=Anthropic(), - max_loops="auto", - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - saved_state_path="product_development_specialist.json", - stopping_token="Stop!", - interactive=True, - context_length=1000, -) +# InteractiveGroupChat Documentation -growth_agent4 = Agent( - agent_name="Customer Service Specialist", - system_prompt="You're the customer service specialist, your purpose is to help companies grow by improving their customer service strategies!", - agent_description="Improve a company's customer service strategies!", - llm=OpenAIChat(), - max_loops="auto", - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - saved_state_path="customer_service_specialist.json", - stopping_token="Stop!", - interactive=True, - context_length=1000, -) +The InteractiveGroupChat is a sophisticated multi-agent system that enables interactive conversations between users and AI agents using @mentions. This system allows users to direct tasks to specific agents and facilitates collaborative responses when multiple agents are mentioned. +## Features -# Register the agents\ -registry = AgentRegistry() +| Feature | Description | +|---------|-------------| +| **@mentions Support** | Direct tasks to specific agents using @agent_name syntax | +| **Multi-Agent Collaboration** | Multiple mentioned agents can see and respond to each other's tasks | +| **Enhanced Collaborative Prompts** | Agents are trained to acknowledge, build upon, and synthesize each other's responses | +| **Speaker Functions** | Control the order in which agents respond (round robin, random, priority, custom) | +| **Dynamic Speaker Management** | Change speaker functions and priorities during runtime | +| **Random Dynamic Speaker** | Advanced speaker function that follows @mentions in agent responses | +| **Parallel and Sequential Strategies** | Support for both parallel and sequential agent execution | +| **Callable Function Support** | Supports both Agent instances and callable functions as chat participants | +| **Comprehensive Error Handling** | Custom error classes for different scenarios | +| **Conversation History** | Maintains a complete history of the conversation | +| **Flexible Output Formatting** | Configurable output format for conversation history | +| **Interactive Terminal Mode** | Full REPL interface for real-time chat with agents | -# Register the agents -registry.add("Marketing Specialist", growth_agent1) -registry.add("Sales Specialist", growth_agent2) -registry.add("Product Development Specialist", growth_agent3) -registry.add("Customer Service Specialist", growth_agent4) +## Installation +```bash +pip install swarms ``` -## Logging and Error Handling - -Each method in the `AgentRegistry` class includes logging to track the execution flow and captures errors to provide detailed information in case of failures. This is crucial for debugging and ensuring smooth operation of the registry. The `report_error` function is used for reporting exceptions that occur during method execution. +## Methods Reference -## Additional Tips +### Constructor (`__init__`) -- Ensure that agents provided to the `AgentRegistry` are properly initialized and configured to handle the tasks they will receive. -- Utilize the logging information to monitor and debug the registry operations. -- Use the `lock` attribute to ensure thread-safe operations when accessing or modifying the registry. +**Description:** +Initializes a new InteractiveGroupChat instance with the specified configuration. +**Arguments:** +| Parameter | Type | Description | Default | +|-----------|------|-------------|---------| +| `id` | str | Unique identifier for the chat | auto-generated key | +| `name` | str | Name of the group chat | "InteractiveGroupChat" | +| `description` | str | Description of the chat's purpose | generic description | +| `agents` | List[Union[Agent, Callable]] | List of participating agents | empty list | +| `max_loops` | int | Maximum conversation turns | 1 | +| `output_type` | str | Type of output format | "string" | +| `interactive` | bool | Whether to enable interactive mode | False | +| `speaker_function` | Union[str, Callable] | Function to determine speaking order | round_robin_speaker | +| `speaker_state` | dict | Initial state for speaker function | {"current_index": 0} | --------------------------------------------------- +**Example:** -# File: swarms/structs/artifact.md +```python +from swarms import Agent, InteractiveGroupChat -# swarms.structs Documentation +# Create agents +financial_advisor = Agent( + agent_name="FinancialAdvisor", + system_prompt="You are a financial advisor specializing in investment strategies.", + model_name="gpt-4" +) -## Introduction +tax_expert = Agent( + agent_name="TaxExpert", + system_prompt="You are a tax expert providing tax-related guidance.", + model_name="gpt-4" +) -The swarms.structs library provides a collection of classes for representing artifacts and their attributes. This documentation will provide an overview of the `Artifact` class, its attributes, functionality, and usage examples. +# Initialize group chat with speaker function +from swarms.structs.interactive_groupchat import round_robin_speaker -### Artifact Class +chat = InteractiveGroupChat( + id="finance-chat-001", + name="Financial Advisory Team", + description="Expert financial guidance team", + agents=[financial_advisor, tax_expert], + max_loops=3, + output_type="string", + interactive=True, + speaker_function=round_robin_speaker +) +``` -The `Artifact` class represents an artifact and its attributes. It inherits from the `BaseModel` class and includes the following attributes: +### Run Method (`run`) -#### Attributes +**Description:** +Processes a task and gets responses from mentioned agents. This is the main method for sending tasks in non-interactive mode. -1. `artifact_id (str)`: Id of the artifact. -2. `file_name (str)`: Filename of the artifact. -3. `relative_path (str, optional)`: Relative path of the artifact in the agent's workspace. +**Arguments:** -These attributes are crucial for identifying and managing different artifacts within a given context. +- `task` (str): The input task containing @mentions to agents +- `img` (Optional[str]): Optional image for the task +- `imgs` (Optional[List[str]]): Optional list of images for the task -## Class Definition +**Returns:** -The `Artifact` class can be defined as follows: +- str: Formatted conversation history including agent responses +**Example:** ```python -class Artifact(BaseModel): - """ - Represents an artifact. +# Single agent interaction +response = chat.run("@FinancialAdvisor what are the best ETFs for 2024?") +print(response) - Attributes: - artifact_id (str): Id of the artifact. - file_name (str): Filename of the artifact. - relative_path (str, optional): Relative path of the artifact in the agent's workspace. - """ +# Multiple agent collaboration +response = chat.run("@FinancialAdvisor and @TaxExpert, how can I minimize taxes on my investments?") +print(response) - artifact_id: str = Field( - ..., - description="Id of the artifact", - example="b225e278-8b4c-4f99-a696-8facf19f0e56", - ) - file_name: str = Field( - ..., description="Filename of the artifact", example="main.py" - ) - relative_path: Optional[str] = Field( - None, - description=("Relative path of the artifact in the agent's workspace"), - example="python/code/", - ) +# With image input +response = chat.run("@FinancialAdvisor analyze this chart", img="chart.png") +print(response) ``` -The `Artifact` class defines the mandatory and optional attributes and provides corresponding descriptions along with example values. +### Start Interactive Session (`start_interactive_session`) -## Functionality and Usage +**Description:** +Starts an interactive terminal session for real-time chat with agents. This creates a REPL (Read-Eval-Print Loop) interface. -The `Artifact` class encapsulates the information and attributes representing an artifact. It provides a structured and organized way to manage artifacts within a given context. +**Arguments:** +None -### Example 1: Creating an Artifact instance +**Features:** +- Real-time chat with agents using @mentions +- View available agents and their descriptions +- Change speaker functions during the session +- Built-in help system +- Graceful exit with 'exit' or 'quit' commands -To create an instance of the `Artifact` class, you can simply initialize it with the required attributes. Here's an example: +**Example:** ```python -from swarms.structs import Artifact - -artifact_instance = Artifact( - artifact_id="b225e278-8b4c-4f99-a696-8facf19f0e56", - file_name="main.py", - relative_path="python/code/", +# Initialize chat with interactive mode +chat = InteractiveGroupChat( + agents=[financial_advisor, tax_expert], + interactive=True ) + +# Start the interactive session +chat.start_interactive_session() ``` -In this example, we create an instance of the `Artifact` class with the specified artifact details. +**Interactive Session Commands:** +- `@agent_name message` - Mention specific agents +- `help` or `?` - Show help information +- `speaker` - Change speaker function +- `exit` or `quit` - End the session -### Example 2: Accessing Artifact attributes +### Set Speaker Function (`set_speaker_function`) -You can access the attributes of the `Artifact` instance using dot notation. Here's how you can access the file name of the artifact: +**Description:** -```python -print(artifact_instance.file_name) -# Output: "main.py" -``` +Dynamically changes the speaker function and optional state during runtime. -### Example 3: Handling optional attributes +**Arguments:** -If the `relative_path` attribute is not provided during artifact creation, it will default to `None`. Here's an example: +- `speaker_function` (Union[str, Callable]): Function that determines speaking order + - String options: "round-robin-speaker", "random-speaker", "priority-speaker", "random-dynamic-speaker" + - Callable: Custom function that takes (agents: List[str], **kwargs) -> str +- `speaker_state` (dict, optional): State for the speaker function +**Example:** ```python -artifact_instance_no_path = Artifact( - artifact_id="c280s347-9b7d-3c68-m337-7abvf50j23k", file_name="script.js" -) +from swarms.structs.interactive_groupchat import random_speaker, priority_speaker -print(artifact_instance_no_path.relative_path) -# Output: None -``` +# Change to random speaker function +chat.set_speaker_function(random_speaker) -By providing default values for optional attributes, the `Artifact` class allows flexibility in defining artifact instances. +# Change to priority speaker with custom priorities +chat.set_speaker_function(priority_speaker, {"financial_advisor": 3, "tax_expert": 2}) -### Additional Information and Tips +# Change to random dynamic speaker +chat.set_speaker_function("random-dynamic-speaker") +``` + +### Get Available Speaker Functions (`get_available_speaker_functions`) -The `Artifact` class represents a powerful and flexible means of handling various artifacts with different attributes. By utilizing this class, users can organize, manage, and streamline their artifacts with ease. +**Description:** -## References and Resources +Returns a list of all available built-in speaker function names. -For further details and references related to the swarms.structs library and the `Artifact` class, refer to the [official documentation](https://swarms.structs.docs/artifact.html). +**Arguments:** +None -This comprehensive documentation provides an in-depth understanding of the `Artifact` class, its attributes, functionality, and usage examples. By following the detailed examples and explanations, developers can effectively leverage the capabilities of the `Artifact` class within their projects. +**Returns:** +- List[str]: List of available speaker function names --------------------------------------------------- +**Example:** +```python +available_functions = chat.get_available_speaker_functions() +print(available_functions) +# Output: ['round-robin-speaker', 'random-speaker', 'priority-speaker', 'random-dynamic-speaker'] +``` -# File: swarms/structs/auto_agent_builder.md +### Get Current Speaker Function (`get_current_speaker_function`) -# Agent Builder +**Description:** -The Agent Builder is a powerful class that automatically builds and manages swarms of AI agents. It provides a flexible and extensible framework for creating, coordinating, and executing multiple AI agents working together to accomplish complex tasks. +Returns the name of the currently active speaker function. -## Overview +**Arguments:** +None -The Agent Builder uses a boss agent to delegate work and create new specialized agents as needed. It's designed to be production-ready with robust error handling, logging, and configuration options. +**Returns:** -## Architecture +- str: Name of the current speaker function, or "custom" if it's a custom function -```mermaid -graph TD - A[Agent Builder] --> B[Configuration] - A --> C[Agent Creation] - A --> D[Task Execution] - - B --> B1[Name] - B --> B2[Description] - B --> B3[Model Settings] - - C --> C1[Agent Pool] - C --> C2[Agent Registry] - C --> C3[Agent Configuration] - - D --> D1[Task Distribution] - D --> D2[Result Collection] - D --> D3[Error Handling] - - C1 --> E[Specialized Agents] - C2 --> E - C3 --> E - - E --> F[Task Execution] - F --> G[Results] +**Example:** +```python +current_function = chat.get_current_speaker_function() +print(current_function) # Output: "round-robin-speaker" ``` -## Class Structure +### Set Priorities (`set_priorities`) -### AgentsBuilder Class +**Description:** -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| name | str | "swarm-creator-01" | The name of the swarm | -| description | str | "This is a swarm that creates swarms" | A description of the swarm's purpose | -| verbose | bool | True | Whether to output detailed logs | -| max_loops | int | 1 | Maximum number of execution loops | -| model_name | str | "gpt-4o" | The model to use for agent creation | -| return_dictionary | bool | True | Whether to return results as a dictionary | -| system_prompt | str | BOSS_SYSTEM_PROMPT | The system prompt for the boss agent | +Sets agent priorities for priority-based speaking order. -### Methods +**Arguments:** -| Method | Description | Parameters | Returns | -|--------|-------------|------------|---------| -| run | Run the swarm on a given task | task: str, image_url: str = None, *args, **kwargs | Tuple[List[Agent], int] | -| _create_agents | Create necessary agents for a task | task: str, *args, **kwargs | List[Agent] | -| build_agent | Build a single agent with specifications | agent_name: str, agent_description: str, agent_system_prompt: str, max_loops: int = 1, model_name: str = "gpt-4o", dynamic_temperature_enabled: bool = True, auto_generate_prompt: bool = False, role: str = "worker", max_tokens: int = 8192, temperature: float = 0.5 | Agent | +- `priorities` (dict): Dictionary mapping agent names to priority weights -## Enterprise Use Cases +**Example:** +```python +# Set agent priorities (higher numbers = higher priority) +chat.set_priorities({ + "financial_advisor": 5, + "tax_expert": 3, + "investment_analyst": 1 +}) +``` -### 1. Customer Service Automation -- Create specialized agents for different aspects of customer service +### Set Dynamic Strategy (`set_dynamic_strategy`) -- Handle ticket routing, response generation, and escalation +**Description:** -- Maintain consistent service quality across channels +Sets the strategy for the random-dynamic-speaker function. -### 2. Data Analysis Pipeline -- Build agents for data collection, cleaning, analysis, and visualization +**Arguments:** -- Automate complex data processing workflows +- `strategy` (str): Either "sequential" or "parallel" + - "sequential": Process one agent at a time based on @mentions + - "parallel": Process all mentioned agents simultaneously -- Generate insights and reports automatically +**Example:** +```python +# Set to sequential strategy (one agent at a time) +chat.set_dynamic_strategy("sequential") -### 3. Content Creation and Management -- Deploy agents for content research, writing, editing, and publishing +# Set to parallel strategy (all mentioned agents respond simultaneously) +chat.set_dynamic_strategy("parallel") +``` -- Maintain brand consistency across content +### Extract Mentions (`_extract_mentions`) -- Automate content scheduling and distribution +**Description:** -### 4. Process Automation -- Create agents for workflow automation +Internal method that extracts @mentions from a task. Used by the run method to identify which agents should respond. -- Handle document processing and routing +**Arguments:** -- Manage approval chains and notifications +- `task` (str): The input task to extract mentions from -### 5. Research and Development -- Build agents for literature review, experiment design, and data collection +**Returns:** -- Automate research documentation and reporting +- List[str]: List of mentioned agent names -- Facilitate collaboration between research teams +**Example:** +```python +# Internal usage example (not typically called directly) +chat = InteractiveGroupChat(agents=[financial_advisor, tax_expert]) +mentions = chat._extract_mentions("@FinancialAdvisor and @TaxExpert, please help") +print(mentions) # ['FinancialAdvisor', 'TaxExpert'] +``` -## Example Usage +### Validate Initialization (`_validate_initialization`) -```python -from swarms import AgentsBuilder +**Description:** -# Initialize the agent builder -agents_builder = AgentsBuilder( - name="enterprise-automation", - description="Enterprise workflow automation swarm", - verbose=True -) +Internal method that validates the group chat configuration during initialization. -# Define a use-case for building agents -task = "Develop a swarm of agents to automate the generation of personalized marketing strategies based on customer data and market trends" +**Arguments:** +None -# Run the swarm -agents = agents_builder.run(task) +**Example:** -# Access results -print(agents) +```python +# Internal validation happens automatically during initialization +chat = InteractiveGroupChat( + agents=[financial_advisor], # Valid: at least one agent + max_loops=5 # Valid: positive number +) ``` -## Best Practices - -1. **Error Handling** - - Always implement proper error handling for agent failures - - Use retry mechanisms for transient failures - - Log all errors for debugging and monitoring +### Setup Conversation Context (`_setup_conversation_context`) -2. **Resource Management** - - Monitor agent resource usage - - Implement rate limiting for API calls - - Use connection pooling for database operations +**Description:** -3. **Security** - - Implement proper authentication and authorization - - Secure sensitive data and API keys - - Follow least privilege principle for agent permissions +Internal method that sets up the initial conversation context with group chat information. -4. **Monitoring and Logging** - - Implement comprehensive logging - - Monitor agent performance metrics - - Set up alerts for critical failures +**Arguments:** -5. **Scalability** - - Design for horizontal scaling - - Implement load balancing - - Use distributed systems when needed +None -## Integration Patterns +**Example:** -```mermaid -graph LR - A[External System] --> B[API Gateway] - B --> C[Agent Builder] - C --> D[Agent Pool] - D --> E[Specialized Agents] - E --> F[External Services] - - subgraph "Monitoring" - G[Logs] - H[Metrics] - I[Alerts] - end - - C --> G - C --> H - C --> I +```python +# Context is automatically set up during initialization +chat = InteractiveGroupChat( + name="Investment Team", + description="Expert investment advice", + agents=[financial_advisor, tax_expert] +) +# The conversation context now includes chat name, description, and agent info ``` -## Performance Considerations +### Update Agent Prompts (`_update_agent_prompts`) -1. **Agent Pool Management** - - Implement connection pooling - - Use caching for frequently accessed data - - Optimize agent creation and destruction +**Description:** -2. **Task Distribution** - - Implement load balancing - - Use priority queues for task scheduling - - Handle task timeouts and retries +Internal method that updates each agent's system prompt with information about other agents and the group chat. This includes enhanced collaborative instructions that teach agents how to acknowledge, build upon, and synthesize each other's responses. -3. **Resource Optimization** - - Monitor memory usage - - Implement garbage collection - - Use efficient data structures +**Arguments:** -## Troubleshooting +None -Common issues and solutions: +**Example:** +```python +# Agent prompts are automatically updated during initialization +chat = InteractiveGroupChat(agents=[financial_advisor, tax_expert]) +# Each agent now knows about the other participants and how to collaborate effectively +``` -1. **Agent Creation Failures** - - Check API credentials - - Verify model availability - - Review system prompts +### Get Speaking Order (`_get_speaking_order`) -2. **Performance Issues** - - Monitor resource usage - - Check network latency - - Review agent configurations +**Description:** -3. **Integration Problems** - - Verify API endpoints - - Check authentication - - Review data formats +Internal method that determines the speaking order using the configured speaker function. +**Arguments:** --------------------------------------------------- +- `mentioned_agents` (List[str]): List of agent names that were mentioned -# File: swarms/structs/auto_swarm.md +**Returns:** -# AutoSwarm +- List[str]: List of agent names in the order they should speak -The `AutoSwarm` class represents a swarm of agents that can be created and managed automatically. This class leverages the `AutoSwarmRouter` to route tasks to appropriate swarms and supports custom preprocessing, routing, and postprocessing of tasks. It is designed to handle complex workflows efficiently. +**Example:** +```python +# Internal usage (not typically called directly) +mentioned = ["financial_advisor", "tax_expert"] +order = chat._get_speaking_order(mentioned) +print(order) # Order determined by speaker function +``` -### Key Concepts +## Speaker Functions -- **Swarm**: A group of agents working together to complete tasks. -- **Routing**: Directing tasks to the appropriate swarm based on specific criteria. -- **Preprocessing and Postprocessing**: Customizable functions to handle tasks before and after routing. -- **Event Loop**: Managing the execution of tasks in a loop. +InteractiveGroupChat supports various speaker functions that control the order in which agents respond when multiple agents are mentioned. -## Attributes +### Built-in Speaker Functions -### Arguments +#### Round Robin Speaker (`round_robin_speaker`) -| Argument | Type | Default | Description | -|---------------------|-------------------------------|-----------|-------------| -| `name` | `Optional[str]` | `None` | The name of the swarm. | -| `description` | `Optional[str]` | `None` | The description of the swarm. | -| `verbose` | `bool` | `False` | Whether to enable verbose mode. | -| `custom_params` | `Optional[Dict[str, Any]]` | `None` | Custom parameters for the swarm. | -| `custom_preprocess` | `Optional[Callable]` | `None` | Custom preprocessing function for tasks. | -| `custom_postprocess`| `Optional[Callable]` | `None` | Custom postprocessing function for task results. | -| `custom_router` | `Optional[Callable]` | `None` | Custom routing function for tasks. | -| `max_loops` | `int` | `1` | The maximum number of loops to run the workflow. | +Agents speak in a fixed order, cycling through the list in sequence. -### Attributes +```python +from swarms.structs.interactive_groupchat import InteractiveGroupChat, round_robin_speaker -| Attribute | Type | Description | -|----------------------|-------------------------------|-------------| -| `name` | `Optional[str]` | The name of the swarm. | -| `description` | `Optional[str]` | The description of the swarm. | -| `verbose` | `bool` | Whether to enable verbose mode. | -| `custom_params` | `Optional[Dict[str, Any]]` | Custom parameters for the swarm. | -| `custom_preprocess` | `Optional[Callable]` | Custom preprocessing function for tasks. | -| `custom_postprocess` | `Optional[Callable]` | Custom postprocessing function for task results. | -| `custom_router` | `Optional[Callable]` | Custom routing function for tasks. | -| `max_loops` | `int` | The maximum number of loops to run the workflow. | -| `router` | `AutoSwarmRouter` | The router for managing task routing. | +chat = InteractiveGroupChat( + agents=agents, + speaker_function=round_robin_speaker, + interactive=False, +) +``` -## Methods +**Behavior:** -### init_logging +- Agents speak in the order they were mentioned -Initializes logging for the `AutoSwarm`. +- Maintains state between calls to continue the cycle -**Examples:** +- Predictable and fair distribution of speaking turns -```python -swarm = AutoSwarm(name="example_swarm", verbose=True) -swarm.init_logging() -``` +#### Random Speaker (`random_speaker`) -### run +Agents speak in random order each time. -Runs the swarm simulation. +```python +from swarms.structs.interactive_groupchat import InteractiveGroupChat, random_speaker -**Arguments:** +chat = InteractiveGroupChat( + agents=agents, + speaker_function=random_speaker, + interactive=False, +) +``` -| Parameter | Type | Default | Description | -|-----------|---------|---------|-------------| -| `task` | `str` | `None` | The task to be executed. | -| `*args` | | | Additional arguments. | -| `**kwargs`| | | Additional keyword arguments. | +**Behavior:** -**Returns:** +- Speaking order is randomized for each task -| Return Type | Description | -|-------------|-------------| -| `Any` | The result of the executed task. | +- Provides variety and prevents bias toward first-mentioned agents -**Raises:** +- Good for brainstorming sessions -- `Exception`: If any error occurs during task execution. +#### Priority Speaker (`priority_speaker`) -**Examples:** +Agents speak based on priority weights assigned to each agent. ```python -swarm = AutoSwarm(name="example_swarm", max_loops=3) -result = swarm.run(task="example_task") -print(result) +from swarms.structs.interactive_groupchat import InteractiveGroupChat, priority_speaker + +chat = InteractiveGroupChat( + agents=agents, + speaker_function=priority_speaker, + speaker_state={"priorities": {"financial_advisor": 3, "tax_expert": 2, "analyst": 1}}, + interactive=False, +) ``` -### list_all_swarms +**Behavior:** -Lists all available swarms and their descriptions. +- Higher priority agents speak first -**Examples:** +- Uses weighted probability for selection -```python -swarm = AutoSwarm(name="example_swarm", max_loops=3) -swarm.list_all_swarms() -# Output: -# INFO: Swarm Name: swarm1 || Swarm Description: Description of swarm1 -# INFO: Swarm Name: swarm2 || Swarm Description: Description of swarm2 -``` +- Good for hierarchical teams or expert-led discussions -### Additional Examples +#### Random Dynamic Speaker (`random_dynamic_speaker`) -#### Example 1: Custom Preprocessing and Postprocessing +Advanced speaker function that follows @mentions in agent responses, enabling dynamic conversation flow. ```python -def custom_preprocess(task, *args, **kwargs): - # Custom preprocessing logic - task = task.upper() - return task, args, kwargs - -def custom_postprocess(result): - # Custom postprocessing logic - return result.lower() +from swarms.structs.interactive_groupchat import InteractiveGroupChat, random_dynamic_speaker -swarm = AutoSwarm( - name="example_swarm", - custom_preprocess=custom_preprocess, - custom_postprocess=custom_postprocess, - max_loops=3 +chat = InteractiveGroupChat( + agents=agents, + speaker_function=random_dynamic_speaker, + speaker_state={"strategy": "parallel"}, # or "sequential" + interactive=False, ) - -# Running a task with custom preprocessing and postprocessing -result = swarm.run(task="example_task") -print(result) # Output will be the processed result ``` -#### Example 2: Custom Router Function +**Behavior:** +- **First Call**: Randomly selects an agent to start the conversation +- **Subsequent Calls**: Extracts @mentions from the previous agent's response and selects the next speaker(s) +- **Two Strategies**: + - **Sequential**: Processes one agent at a time based on @mentions + - **Parallel**: Processes all mentioned agents simultaneously + +**Example Dynamic Flow:** ```python -def custom_router(swarm, task, *args, **kwargs): - # Custom routing logic - if "specific" in task: - return swarm.router.swarm_dict["specific_swarm"].run(task, *args, **kwargs) - return swarm.router.swarm_dict["default_swarm"].run(task, *args, **kwargs) +# Agent A responds: "I think @AgentB should analyze this data and @AgentC should review the methodology" +# With sequential strategy: Agent B speaks next +# With parallel strategy: Both Agent B and Agent C speak simultaneously +``` -swarm = AutoSwarm( - name="example_swarm", - custom_router=custom_router, - max_loops=3 -) +**Use Cases:** +- Complex problem-solving where agents need to delegate to specific experts +- Dynamic workflows where the conversation flow depends on agent responses +- Collaborative decision-making processes -# Running a task with custom routing -result = swarm.run(task="specific_task") -print(result) # Output will be the result of the routed task -``` +### Custom Speaker Functions -#### Example 3: Verbose Mode +You can create your own speaker functions to implement custom logic: ```python -swarm = AutoSwarm( - name="example_swarm", - verbose=True, - max_loops=3 -) +def custom_speaker(agents: List[str], **kwargs) -> str: + """ + Custom speaker function that selects agents based on specific criteria. + + Args: + agents: List of agent names + **kwargs: Additional arguments (context, time, etc.) + + Returns: + Selected agent name + """ + # Your custom logic here + if "urgent" in kwargs.get("context", ""): + return "emergency_agent" if "emergency_agent" in agents else agents[0] + + # Default to first agent + return agents[0] -# Running a task with verbose mode enabled -result = swarm.run(task="example_task") -# Output will include detailed logs of the task execution process +# Use custom speaker function +chat = InteractiveGroupChat( + agents=agents, + speaker_function=custom_speaker, + interactive=False, +) ``` +### Dynamic Speaker Function Changes -#### Full Example 4: -First create a class with BaseSwarm -> Then wrap it in the router -> then pass that to the `AutoSwarm` +You can change the speaker function during runtime: ```python -from swarms import BaseSwarm, AutoSwarmRouter, AutoSwarm +# Start with round robin +chat = InteractiveGroupChat( + agents=agents, + speaker_function=round_robin_speaker, + interactive=False, +) +# Change to random +chat.set_speaker_function(random_speaker) -class FinancialReportSummarization(BaseSwarm): - def __init__(self, name: str = None, *args, **kwargs): - super().__init__() +# Change to priority with custom priorities +chat.set_priorities({"financial_advisor": 5, "tax_expert": 3, "analyst": 1}) +chat.set_speaker_function(priority_speaker) - def run(self, task, *args, **kwargs): - return task +# Change to dynamic speaker with parallel strategy +chat.set_speaker_function("random-dynamic-speaker") +chat.set_dynamic_strategy("parallel") +``` +## Enhanced Collaborative Behavior -# Add swarm to router -router = AutoSwarmRouter(swarms=[FinancialReportSummarization]) +The InteractiveGroupChat now includes enhanced collaborative prompts that ensure agents work together effectively. -# Create AutoSwarm Instance -autoswarm = AutoSwarm( - name="kyegomez/FinancialReportSummarization", - description="A swarm for financial document summarizing and generation", - verbose=True, - router=router, -) +### Collaborative Response Protocol -# Run the AutoSwarm -autoswarm.run("Analyze these documents and give me a summary:") -``` +Every agent receives instructions to: -## Summary +1. **Read and understand** all previous responses from other agents +2. **Acknowledge** what other agents have said +3. **Build upon** previous insights rather than repeating information +4. **Synthesize** multiple perspectives when possible +5. **Delegate** appropriately using @mentions -The `AutoSwarm` class provides a robust framework for managing and executing tasks using a swarm of agents. With customizable preprocessing, routing, and postprocessing functions, it is highly adaptable to various workflows and can handle complex task execution scenarios efficiently. The integration with `AutoSwarmRouter` enhances its flexibility, making it a powerful tool for dynamic task management. +### Response Structure --------------------------------------------------- +Agents are guided to structure their responses as: -# File: swarms/structs/auto_swarm_router.md +1. **ACKNOWLEDGE**: "I've reviewed the responses from @agent1 and @agent2..." +2. **BUILD**: "Building on @agent1's analysis of the data..." +3. **CONTRIBUTE**: "From my perspective, I would add..." +4. **COLLABORATE**: "To get a complete picture, let me ask @agent3 to..." +5. **SYNTHESIZE**: "Combining our insights, the key findings are..." -# AutoSwarmRouter +### Example Collaborative Response -The `AutoSwarmRouter` class is designed to route tasks to the appropriate swarm based on the provided name. This class allows for customization of preprocessing, routing, and postprocessing of tasks, making it highly adaptable to various workflows and requirements. +```python +task = "Analyze our Q3 performance. @analyst @researcher @strategist" -### Key Concepts +# Expected collaborative behavior: +# Analyst: "Based on the data analysis, I can see clear growth trends in Q3..." +# Researcher: "Building on @analyst's data insights, I can add that market research shows..." +# Strategist: "Synthesizing @analyst's data and @researcher's market insights, I recommend..." +``` -- **Routing**: Directing tasks to the appropriate swarm based on specific criteria. -- **Preprocessing and Postprocessing**: Customizable functions to handle tasks before and after routing. -- **Swarms**: Collections of `BaseSwarm` objects that perform the tasks. +## Error Classes -## Attributes +### InteractiveGroupChatError -### Arguments +**Description:** -| Argument | Type | Default | Description | -|--------------------|----------------------------------|-----------|-------------| -| `name` | `Optional[str]` | `None` | The name of the router. | -| `description` | `Optional[str]` | `None` | The description of the router. | -| `verbose` | `bool` | `False` | Whether to enable verbose mode. | -| `custom_params` | `Optional[Dict[str, Any]]` | `None` | Custom parameters for the router. | -| `swarms` | `Sequence[BaseSwarm]` | `None` | A list of `BaseSwarm` objects. | -| `custom_preprocess`| `Optional[Callable]` | `None` | Custom preprocessing function for tasks. | -| `custom_postprocess`| `Optional[Callable]` | `None` | Custom postprocessing function for task results. | -| `custom_router` | `Optional[Callable]` | `None` | Custom routing function for tasks. | +Base exception class for InteractiveGroupChat errors. -### Attributes +**Example:** +```python +try: + # Some operation that might fail + chat.run("@InvalidAgent hello") +except InteractiveGroupChatError as e: + print(f"Chat error occurred: {e}") +``` -| Attribute | Type | Description | -|----------------------|----------------------------------|-------------| -| `name` | `Optional[str]` | The name of the router. | -| `description` | `Optional[str]` | The description of the router. | -| `verbose` | `bool` | Whether to enable verbose mode. | -| `custom_params` | `Optional[Dict[str, Any]]` | Custom parameters for the router. | -| `swarms` | `Sequence[BaseSwarm]` | A list of `BaseSwarm` objects. | -| `custom_preprocess` | `Optional[Callable]` | Custom preprocessing function for tasks. | -| `custom_postprocess` | `Optional[Callable]` | Custom postprocessing function for task results. | -| `custom_router` | `Optional[Callable]` | Custom routing function for tasks. | -| `swarm_dict` | `Dict[str, BaseSwarm]` | A dictionary of swarms keyed by their name. | +### AgentNotFoundError -## Methods +**Description:** -### run +Raised when a mentioned agent is not found in the group. -Executes the swarm simulation and routes the task to the appropriate swarm. +**Example:** +```python +try: + chat.run("@NonExistentAgent hello!") +except AgentNotFoundError as e: + print(f"Agent not found: {e}") +``` -**Arguments:** +### NoMentionedAgentsError -| Parameter | Type | Default | Description | -|-----------|---------|---------|-------------| -| `task` | `str` | `None` | The task to be executed. | -| `*args` | | | Additional arguments. | -| `**kwargs`| | | Additional keyword arguments. | +**Description:** -**Returns:** +Raised when no agents are mentioned in the task. -| Return Type | Description | -|-------------|-------------| -| `Any` | The result of the routed task. | +**Example:** -**Raises:** +```python +try: + chat.run("Hello everyone!") # No @mentions +except NoMentionedAgentsError as e: + print(f"No agents mentioned: {e}") +``` -- `ValueError`: If the specified swarm is not found. -- `Exception`: If any error occurs during task routing or execution. +### InvalidTaskFormatError -**Examples:** +**Description:** -```python -router = AutoSwarmRouter(name="example_router", swarms=[swarm1, swarm2]) +Raised when the task format is invalid. -# Running a task -result = router.run(task="example_task") +**Example:** +```python +try: + chat.run("@Invalid@Format") +except InvalidTaskFormatError as e: + print(f"Invalid task format: {e}") ``` -### len_of_swarms +### InvalidSpeakerFunctionError -Prints the number of swarms available in the router. +**Description:** -**Examples:** +Raised when an invalid speaker function is provided. +**Example:** ```python -router = AutoSwarmRouter(name="example_router", swarms=[swarm1, swarm2]) +def invalid_speaker(agents, **kwargs): + return 123 # Should return string, not int -# Printing the number of swarms -router.len_of_swarms() # Output: 2 +try: + chat = InteractiveGroupChat( + agents=agents, + speaker_function=invalid_speaker, + ) +except InvalidSpeakerFunctionError as e: + print(f"Invalid speaker function: {e}") ``` -### list_available_swarms +## Best Practices -Logs the available swarms and their descriptions. +| Best Practice | Description | Example | +|--------------|-------------|---------| +| Agent Naming | Use clear, unique names for agents to avoid confusion | `financial_advisor`, `tax_expert` | +| Task Format | Always use @mentions to direct tasks to specific agents | `@financial_advisor What's your investment advice?` | +| Speaker Functions | Choose appropriate speaker functions for your use case | Round robin for fairness, priority for expert-led discussions | +| Dynamic Speaker | Use random-dynamic-speaker for complex workflows with delegation | When agents need to call on specific experts | +| Strategy Selection | Choose sequential for focused discussions, parallel for brainstorming | Sequential for analysis, parallel for idea generation | +| Collaborative Design | Design agents with complementary expertise for better collaboration | Analyst + Researcher + Strategist | +| Error Handling | Implement proper error handling for various scenarios | `try/except` blocks for `AgentNotFoundError` | +| Context Management | Be aware that agents can see the full conversation history | Monitor conversation length and relevance | +| Resource Management | Consider the number of agents and task length to optimize performance | Limit max_loops and task size | +| Dynamic Adaptation | Change speaker functions based on different phases of work | Round robin for brainstorming, priority for decision-making | -**Examples:** +## Usage Examples + +### Basic Multi-Agent Collaboration ```python -router = AutoSwarmRouter(name="example_router", swarms=[swarm1, swarm2]) +from swarms import Agent +from swarms.structs.interactive_groupchat import InteractiveGroupChat, round_robin_speaker -# Listing available swarms -router.list_available_swarms() -# Output: -# INFO: Swarm Name: swarm1 || Swarm Description: Description of swarm1 -# INFO: Swarm Name: swarm2 || Swarm Description: Description of swarm2 -``` +# Create specialized agents +analyst = Agent( + agent_name="analyst", + system_prompt="You are a data analyst specializing in business intelligence.", + llm="gpt-3.5-turbo", +) -### Additional Examples +researcher = Agent( + agent_name="researcher", + system_prompt="You are a market researcher with expertise in consumer behavior.", + llm="gpt-3.5-turbo", +) -#### Example 1: Custom Preprocessing and Postprocessing +strategist = Agent( + agent_name="strategist", + system_prompt="You are a strategic consultant who synthesizes insights into actionable recommendations.", + llm="gpt-3.5-turbo", +) -```python -def custom_preprocess(task, *args, **kwargs): - # Custom preprocessing logic - task = task.upper() - return task, args, kwargs +# Create collaborative group chat +chat = InteractiveGroupChat( + name="Business Analysis Team", + description="A collaborative team for comprehensive business analysis", + agents=[analyst, researcher, strategist], + speaker_function=round_robin_speaker, + interactive=False, +) -def custom_postprocess(result): - # Custom postprocessing logic - return result.lower() +# Collaborative analysis task +task = """Analyze our company's Q3 performance. We have the following data: +- Revenue: $2.5M (up 15% from Q2) +- Customer acquisition cost: $45 (down 8% from Q2) +- Market share: 3.2% (up 0.5% from Q2) -router = AutoSwarmRouter( - name="example_router", - swarms=[swarm1, swarm2], - custom_preprocess=custom_preprocess, - custom_postprocess=custom_postprocess -) +@analyst @researcher @strategist please provide a comprehensive analysis.""" -# Running a task with custom preprocessing and postprocessing -result = router.run(task="example_task") -print(result) # Output will be the processed result +response = chat.run(task) +print(response) ``` -#### Example 2: Custom Router Function +### Priority-Based Expert Consultation ```python -def custom_router(router, task, *args, **kwargs): - # Custom routing logic - if "specific" in task: - return router.swarm_dict["specific_swarm"].run(task, *args, **kwargs) - return router.swarm_dict["default_swarm"].run(task, *args, **kwargs) +from swarms.structs.interactive_groupchat import InteractiveGroupChat, priority_speaker -router = AutoSwarmRouter( - name="example_router", - swarms=[default_swarm, specific_swarm], - custom_router=custom_router +# Create expert agents with different priority levels +senior_expert = Agent( + agent_name="senior_expert", + system_prompt="You are a senior consultant with 15+ years of experience.", + llm="gpt-4", ) -# Running a task with custom routing -result = router.run(task="specific_task") -print(result) # Output will be the result of the routed task +junior_expert = Agent( + agent_name="junior_expert", + system_prompt="You are a junior consultant with 3 years of experience.", + llm="gpt-3.5-turbo", +) + +assistant = Agent( + agent_name="assistant", + system_prompt="You are a research assistant who gathers supporting information.", + llm="gpt-3.5-turbo", +) + +# Create priority-based group chat +chat = InteractiveGroupChat( + name="Expert Consultation Team", + description="Expert-led consultation with collaborative input", + agents=[senior_expert, junior_expert, assistant], + speaker_function=priority_speaker, + speaker_state={"priorities": {"senior_expert": 5, "junior_expert": 3, "assistant": 1}}, + interactive=False, +) + +# Expert consultation task +task = """We need strategic advice on entering a new market. +@senior_expert @junior_expert @assistant please provide your insights.""" + +response = chat.run(task) +print(response) ``` -#### Example 3: Verbose Mode +### Dynamic Speaker Function with Delegation ```python -router = AutoSwarmRouter( - name="example_router", - swarms=[swarm1, swarm2], - verbose=True +from swarms.structs.interactive_groupchat import InteractiveGroupChat, random_dynamic_speaker + +# Create specialized medical agents +cardiologist = Agent( + agent_name="cardiologist", + system_prompt="You are a cardiologist specializing in heart conditions.", + llm="gpt-4", +) + +oncologist = Agent( + agent_name="oncologist", + system_prompt="You are an oncologist specializing in cancer treatment.", + llm="gpt-4", +) + +endocrinologist = Agent( + agent_name="endocrinologist", + system_prompt="You are an endocrinologist specializing in hormone disorders.", + llm="gpt-4", +) + +# Create dynamic group chat +chat = InteractiveGroupChat( + name="Medical Panel Discussion", + description="A collaborative panel of medical specialists", + agents=[cardiologist, oncologist, endocrinologist], + speaker_function=random_dynamic_speaker, + speaker_state={"strategy": "sequential"}, + interactive=False, ) -# Running a task with verbose mode enabled -result = router.run(task="example_task") -# Output will include detailed logs of the task routing and execution process +# Complex medical case with dynamic delegation +case = """CASE PRESENTATION: +A 65-year-old male with Type 2 diabetes, hypertension, and recent diagnosis of +stage 3 colon cancer presents with chest pain and shortness of breath. +ECG shows ST-segment elevation. Recent blood work shows elevated blood glucose (280 mg/dL) +and signs of infection (WBC 15,000, CRP elevated). + +@cardiologist @oncologist @endocrinologist please provide your assessment and treatment recommendations.""" + +response = chat.run(case) +print(response) ``` -## Summary +### Dynamic Speaker Function Changes -The `AutoSwarmRouter` class provides a flexible and customizable approach to routing tasks to appropriate swarms, supporting custom preprocessing, routing, and postprocessing functions. This makes it a powerful tool for managing complex workflows that require dynamic task handling and execution. +```python +from swarms.structs.interactive_groupchat import ( + InteractiveGroupChat, + round_robin_speaker, + random_speaker, + priority_speaker, + random_dynamic_speaker +) --------------------------------------------------- +# Create brainstorming agents +creative_agent = Agent(agent_name="creative", system_prompt="You are a creative thinker.") +analytical_agent = Agent(agent_name="analytical", system_prompt="You are an analytical thinker.") +practical_agent = Agent(agent_name="practical", system_prompt="You are a practical implementer.") -# File: swarms/structs/base_workflow.md +chat = InteractiveGroupChat( + name="Dynamic Team", + agents=[creative_agent, analytical_agent, practical_agent], + speaker_function=round_robin_speaker, + interactive=False, +) -# BaseWorkflow +# Phase 1: Brainstorming (random order) +chat.set_speaker_function(random_speaker) +task1 = "Let's brainstorm new product ideas. @creative @analytical @practical" +response1 = chat.run(task1) -The `BaseWorkflow` class serves as a foundational structure for defining and managing workflows. It allows users to add, remove, update, and manage tasks and agents within a workflow, offering flexibility and extensibility for various applications. +# Phase 2: Analysis (priority order) +chat.set_priorities({"analytical": 3, "creative": 2, "practical": 1}) +chat.set_speaker_function(priority_speaker) +task2 = "Now let's analyze the feasibility of these ideas. @creative @analytical @practical" +response2 = chat.run(task2) -### Key Concepts +# Phase 3: Dynamic delegation (agents mention each other) +chat.set_speaker_function(random_dynamic_speaker) +chat.set_dynamic_strategy("sequential") +task3 = "Let's plan implementation with dynamic delegation. @creative @analytical @practical" +response3 = chat.run(task3) -- **Agents**: Entities participating in the workflow. -- **Tasks**: Units of work to be executed within the workflow. -- **Models**: Computational models used within the workflow. -- **Workflow State**: The state of the workflow, which can be saved and restored. +# Phase 4: Final synthesis (round robin for equal input) +chat.set_speaker_function(round_robin_speaker) +task4 = "Finally, let's synthesize our findings. @creative @analytical @practical" +response4 = chat.run(task4) +``` -## Attributes +### Custom Speaker Function -### Arguments +```python +def context_aware_speaker(agents: List[str], **kwargs) -> str: + """Custom speaker function that selects agents based on context.""" + context = kwargs.get("context", "").lower() + + if "data" in context or "analysis" in context: + return "analyst" if "analyst" in agents else agents[0] + elif "market" in context or "research" in context: + return "researcher" if "researcher" in agents else agents[0] + elif "strategy" in context or "planning" in context: + return "strategist" if "strategist" in agents else agents[0] + else: + return agents[0] -| Argument | Type | Default | Description | -|----------|------|---------|-------------| -| `agents` | `List[Agent]` | `None` | A list of agents participating in the workflow. | -| `task_pool` | `List[Task]` | `None` | A list of tasks in the workflow. | -| `models` | `List[Any]` | `None` | A list of models used in the workflow. | -| `*args` | | | Variable length argument list. | -| `**kwargs` | | | Arbitrary keyword arguments. | +# Use custom speaker function +chat = InteractiveGroupChat( + name="Context-Aware Team", + agents=[analyst, researcher, strategist], + speaker_function=context_aware_speaker, + interactive=False, +) -### Attributes +# The speaker function will automatically select the most appropriate agent +task = "We need to analyze our market position and develop a strategy." +response = chat.run(task) +``` -| Attribute | Type | Description | -|-----------|------|-------------| -| `agents` | `List[Agent]` | A list of agents participating in the workflow. | -| `task_pool` | `List[Task]` | A list of tasks in the workflow. | -| `models` | `List[Any]` | A list of models used in the workflow. | +### Interactive Session with Enhanced Collaboration -## Methods +```python +# Create agents designed for collaboration +data_scientist = Agent( + agent_name="data_scientist", + system_prompt="You are a data scientist. When collaborating, always reference specific data points and build upon others' insights with quantitative support.", + llm="gpt-4", +) -### add_task +business_analyst = Agent( + agent_name="business_analyst", + system_prompt="You are a business analyst. When collaborating, always connect business insights to practical implications and build upon data analysis with business context.", + llm="gpt-3.5-turbo", +) -Adds a task or a list of tasks to the task pool. +product_manager = Agent( + agent_name="product_manager", + system_prompt="You are a product manager. When collaborating, always synthesize insights from all team members and provide actionable product recommendations.", + llm="gpt-3.5-turbo", +) -**Arguments:** +# Start interactive session +chat = InteractiveGroupChat( + name="Product Development Team", + description="A collaborative team for product development decisions", + agents=[data_scientist, business_analyst, product_manager], + speaker_function=round_robin_speaker, + interactive=True, +) -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `task` | `Task` | `None` | A single task to add. | -| `tasks` | `List[Task]` | `None` | A list of tasks to add. | +# Start the interactive session +chat.start_interactive_session() +``` + +## Benefits and Use Cases + +### Benefits of Enhanced Collaboration + +1. **Reduced Redundancy**: Agents don't repeat what others have already said +2. **Improved Synthesis**: Multiple perspectives are integrated into coherent conclusions +3. **Better Delegation**: Agents naturally delegate to appropriate experts +4. **Enhanced Problem Solving**: Complex problems are addressed systematically +5. **More Natural Interactions**: Agents respond like real team members +6. **Dynamic Workflows**: Conversation flow adapts based on agent responses +7. **Flexible Execution**: Support for both sequential and parallel processing + +### Use Cases + +| Use Case Category | Specific Use Case | Agent Team Composition | Recommended Speaker Function | +|------------------|-------------------|----------------------|------------------------------| +| **Business Analysis and Strategy** | Data Analysis | Analyst + Researcher + Strategist | Round Robin | +| | Market Research | Multiple experts analyzing different aspects | Random Dynamic | +| | Strategic Planning | Expert-led discussions with collaborative input | Priority | +| **Product Development** | Requirements Gathering | Product Manager + Developer + Designer | Round Robin | +| | Technical Architecture | Senior + Junior developers with different expertise | Priority | +| | User Experience | UX Designer + Product Manager + Developer | Random Dynamic | +| **Research and Development** | Scientific Research | Multiple researchers with different specializations | Random Dynamic | +| | Literature Review | Different experts reviewing various aspects | Round Robin | +| | Experimental Design | Statistician + Domain Expert + Methodologist | Priority | +| **Creative Projects** | Content Creation | Writer + Editor + Designer | Random | +| | Marketing Campaigns | Creative + Analyst + Strategist | Random Dynamic | +| | Design Projects | Designer + Developer + Product Manager | Round Robin | +| **Problem Solving** | Troubleshooting | Technical + Business + User perspective experts | Priority | +| | Crisis Management | Emergency + Communication + Technical teams | Priority | +| | Decision Making | Executive + Analyst + Specialist | Priority | +| **Medical Consultation** | Complex Cases | Multiple specialists (Cardiologist + Oncologist + Endocrinologist) | Random Dynamic | +| | Treatment Planning | Senior + Junior doctors with different expertise | Priority | +| | Research Review | Multiple researchers reviewing different aspects | Round Robin | + +### Speaker Function Selection Guide + +| Use Case | Recommended Speaker Function | Strategy | Reasoning | +|----------|------------------------------|----------|-----------| +| Team Meetings | Round Robin | N/A | Ensures equal participation | +| Brainstorming | Random | N/A | Prevents bias and encourages creativity | +| Expert Consultation | Priority | N/A | Senior experts speak first | +| Problem Solving | Priority | N/A | Most relevant experts prioritize | +| Creative Sessions | Random | N/A | Encourages diverse perspectives | +| Decision Making | Priority | N/A | Decision makers speak first | +| Research Review | Round Robin | N/A | Equal contribution from all reviewers | +| Complex Workflows | Random Dynamic | Sequential | Follows natural conversation flow | +| Parallel Analysis | Random Dynamic | Parallel | Multiple agents work simultaneously | +| Medical Panels | Random Dynamic | Sequential | Specialists delegate to relevant experts | +| Technical Architecture | Random Dynamic | Sequential | Senior architects guide the discussion | -**Raises:** +## Contributing -- `ValueError`: If neither task nor tasks are provided. +Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository. -**Examples:** +## License -```python -workflow = BaseWorkflow() -task1 = Task(description="Task 1") -task2 = Task(description="Task 2") +This project is licensed under the Apache License - see the LICENSE file for details. -# Adding a single task -workflow.add_task(task=task1) +-------------------------------------------------- -# Adding multiple tasks -workflow.add_task(tasks=[task1, task2]) -``` +# File: swarms\structs\majorityvoting.md -### add_agent +# MajorityVoting Module Documentation -Adds an agent to the workflow. +The `MajorityVoting` module provides a mechanism for performing majority voting among a group of agents. Majority voting is a decision rule that selects the option which has the majority of votes. This is particularly useful in systems where multiple agents provide responses to a query, and the most common response needs to be identified as the final output. -**Arguments:** +## Architecture -| Parameter | Type | Description | -|-----------|------|-------------| -| `agent` | `Agent` | The agent to add to the workflow. | +```mermaid +graph TD + A[MajorityVoting System] --> B[Initialize Agents] + B --> C[Process Task] + C --> D{Execution Mode} + D --> E[Single Task] + D --> F[Batch Tasks] + D --> G[Concurrent Tasks] + D --> H[Async Tasks] + E --> I[Run Agents] + F --> I + G --> I + H --> I + I --> J[Collect Responses] + J --> K[Consensus Analysis] + K --> L{Consensus Agent?} + L -->|Yes| M[Use Consensus Agent] + L -->|No| N[Use Last Agent] + M --> O[Final Output] + N --> O + O --> P[Save Conversation] +``` -**Examples:** +### Key Concepts -```python -workflow = BaseWorkflow() -agent = Agent(name="Agent 1") +- **Majority Voting**: A method to determine the most common response from a set of answers. +- **Agents**: Entities (e.g., models, algorithms) that provide responses to tasks or queries. +- **Output Parser**: A function that processes the responses from the agents before performing the majority voting. +- **Consensus Agent**: An optional agent that analyzes the responses from all agents to determine the final consensus. +- **Conversation History**: A record of all agent interactions and responses during the voting process. -# Adding an agent to the workflow -workflow.add_agent(agent=agent) -``` +## Class Definition: `MajorityVoting` -### run +### Parameters -Abstract method to run the workflow. +| Parameter | Type | Description | +|------------------|----------------|-----------------------------------------------------------------------------| +| `name` | `str` | Name of the majority voting system. Default is "MajorityVoting". | +| `description` | `str` | Description of the system. Default is "A majority voting system for agents". | +| `agents` | `List[Agent]` | A list of agents to be used in the majority voting system. | +| `output_parser` | `Callable` | Function to parse agent outputs. Default is `majority_voting` function. | +| `consensus_agent`| `Agent` | Optional agent for analyzing consensus among responses. | +| `autosave` | `bool` | Whether to autosave conversations. Default is `False`. | +| `verbose` | `bool` | Whether to enable verbose logging. Default is `False`. | +| `max_loops` | `int` | Maximum number of voting loops. Default is 1. | -### __sequential_loop +### Methods -Abstract method for the sequential loop. +#### `run(task: str, correct_answer: str, *args, **kwargs) -> List[Any]` -### __log +Runs the majority voting system for a single task. -Logs a message if verbose mode is enabled. +**Parameters:** +- `task` (str): The task to be performed by the agents +- `correct_answer` (str): The correct answer for evaluation +- `*args`, `**kwargs`: Additional arguments -**Arguments:** +**Returns:** +- List[Any]: The conversation history as a string, including the majority vote -| Parameter | Type | Description | -|-----------|------|-------------| -| `message` | `str` | The message to log. | +#### `batch_run(tasks: List[str], *args, **kwargs) -> List[Any]` -### __str__ +Runs multiple tasks in sequence. -Returns a string representation of the workflow. +**Parameters:** +- `tasks` (List[str]): List of tasks to be performed +- `*args`, `**kwargs`: Additional arguments -### __repr__ +**Returns:** +- List[Any]: List of majority votes for each task -Returns a string representation of the workflow for debugging. +#### `run_concurrently(tasks: List[str], *args, **kwargs) -> List[Any]` -### reset +Runs multiple tasks concurrently using thread pooling. -Resets the workflow by clearing the results of each task. +**Parameters:** +- `tasks` (List[str]): List of tasks to be performed +- `*args`, `**kwargs`: Additional arguments -**Examples:** +**Returns:** +- List[Any]: List of majority votes for each task -```python -workflow = BaseWorkflow() -workflow.reset() -``` +#### `run_async(tasks: List[str], *args, **kwargs) -> List[Any]` -### get_task_results +Runs multiple tasks asynchronously using asyncio. -Returns the results of each task in the workflow. +**Parameters:** +- `tasks` (List[str]): List of tasks to be performed +- `*args`, `**kwargs`: Additional arguments **Returns:** +- List[Any]: List of majority votes for each task -| Return Type | Description | -|-------------|-------------| -| `Dict[str, Any]` | The results of each task in the workflow. | +## Usage Examples -**Examples:** +### Example 1: Basic Single Task Execution with Modern LLMs ```python -workflow = BaseWorkflow() -results = workflow.get_task_results() -``` +from swarms import Agent, MajorityVoting + +# Initialize multiple agents with different specialties +agents = [ + Agent( + agent_name="Financial-Analysis-Agent", + agent_description="Personal finance advisor focused on market analysis", + system_prompt="You are a financial advisor specializing in market analysis and investment opportunities.", + max_loops=1, + model_name="gpt-4o" + ), + Agent( + agent_name="Risk-Assessment-Agent", + agent_description="Risk analysis and portfolio management expert", + system_prompt="You are a risk assessment expert focused on evaluating investment risks and portfolio diversification.", + max_loops=1, + model_name="gpt-4o" + ), + Agent( + agent_name="Tech-Investment-Agent", + agent_description="Technology sector investment specialist", + system_prompt="You are a technology investment specialist focused on AI, emerging tech, and growth opportunities.", + max_loops=1, + model_name="gpt-4o" + ) +] -### remove_task -Removes a task from the workflow. +consensus_agent = Agent( + agent_name="Consensus-Agent", + agent_description="Consensus agent focused on analyzing investment advice", + system_prompt="You are a consensus agent focused on analyzing investment advice and providing a final answer.", + max_loops=1, + model_name="gpt-4o" +) -**Arguments:** +# Create majority voting system +majority_voting = MajorityVoting( + name="Investment-Advisory-System", + description="Multi-agent system for investment advice", + agents=agents, + verbose=True, + consensus_agent=consensus_agent +) -| Parameter | Type | Description | -|-----------|------|-------------| -| `task` | `str` | The description of the task to remove. | +# Run the analysis with majority voting +result = majority_voting.run( + task="Create a table of super high growth opportunities for AI. I have $40k to invest in ETFs, index funds, and more. Please create a table in markdown.", + correct_answer="" # Optional evaluation metric +) -**Examples:** +print(result) -```python -workflow = BaseWorkflow() -workflow.remove_task(task="Task 1") ``` -### update_task +## Batch Execution -Updates the arguments of a task in the workflow. +```python +from swarms import Agent, MajorityVoting -**Arguments:** +# Initialize multiple agents with different specialties +agents = [ + Agent( + agent_name="Financial-Analysis-Agent", + agent_description="Personal finance advisor focused on market analysis", + system_prompt="You are a financial advisor specializing in market analysis and investment opportunities.", + max_loops=1, + model_name="gpt-4o" + ), + Agent( + agent_name="Risk-Assessment-Agent", + agent_description="Risk analysis and portfolio management expert", + system_prompt="You are a risk assessment expert focused on evaluating investment risks and portfolio diversification.", + max_loops=1, + model_name="gpt-4o" + ), + Agent( + agent_name="Tech-Investment-Agent", + agent_description="Technology sector investment specialist", + system_prompt="You are a technology investment specialist focused on AI, emerging tech, and growth opportunities.", + max_loops=1, + model_name="gpt-4o" + ) +] -| Parameter | Type | Description | -|-----------|------|-------------| -| `task` | `str` | The description of the task to update. | -| `**updates` | | The updates to apply to the task. | -**Raises:** +consensus_agent = Agent( + agent_name="Consensus-Agent", + agent_description="Consensus agent focused on analyzing investment advice", + system_prompt="You are a consensus agent focused on analyzing investment advice and providing a final answer.", + max_loops=1, + model_name="gpt-4o" +) -- `ValueError`: If the task is not found in the workflow. +# Create majority voting system +majority_voting = MajorityVoting( + name="Investment-Advisory-System", + description="Multi-agent system for investment advice", + agents=agents, + verbose=True, + consensus_agent=consensus_agent +) -**Examples:** +# Run the analysis with majority voting +result = majority_voting.batch_run( + task="Create a table of super high growth opportunities for AI. I have $40k to invest in ETFs, index funds, and more. Please create a table in markdown.", + correct_answer="" # Optional evaluation metric +) -```python -workflow = BaseWorkflow() -task = Task(description="Task 1", kwargs={"param": 1}) +print(result) -# Adding a task to the workflow -workflow.add_task(task=task) -# Updating the task -workflow.update_task("Task 1", param=2) ``` -### delete_task - -Deletes a task from the workflow. - -**Arguments:** +-------------------------------------------------- -| Parameter | Type | Description | -|-----------|------|-------------| -| `task` | `str` | The description of the task to delete. | +# File: swarms\structs\malt.md -**Raises:** +# MALT: Multi-Agent Learning Task Framework -- `ValueError`: If the task is not found in the workflow. +## Overview -**Examples:** +MALT (Multi-Agent Learning Task) is a sophisticated orchestration framework that coordinates multiple specialized AI agents to tackle complex tasks through structured conversations. Inspired by the principles outlined in the [MALT research paper](https://arxiv.org/pdf/2412.01928), this implementation provides a reliable, extensible system for multi-agent collaboration. -```python -workflow = BaseWorkflow() -task = Task(description="Task 1") +The framework is designed around a three-agent architecture: -# Adding a task to the workflow -workflow.add_task(task=task) +1. **Creator Agent**: Generates initial content or solutions -# Deleting the task -workflow.delete_task("Task 1") -``` +2. **Verifier Agent**: Critically evaluates the creator's output -### save_workflow_state +3. **Refiner Agent**: Improves the solution based on verifier feedback -Saves the workflow state to a json file. +This collaborative approach enables high-quality outputs for complex tasks by combining the strengths of multiple specialized agents, each focused on a different aspect of the problem-solving process. -**Arguments:** +## How It Works -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `filepath` | `Optional[str]` | `"sequential_workflow_state.json"` | The path to save the workflow state to. | +The MALT framework follows a structured workflow: -**Examples:** +1. A task is submitted to the system +2. The Creator Agent generates an initial solution +3. Multiple instances of the Verifier Agent independently evaluate the solution +4. Multiple instances of the Refiner Agent improve the solution based on verification feedback +5. The final refined output is returned -```python -workflow = BaseWorkflow() -workflow.save_workflow_state(filepath="workflow_state.json") -``` +This process can be configured to run for multiple iterations, with each cycle potentially improving the quality of the output. The system maintains a conversation history, tracking interactions between agents throughout the workflow. -### add_objective_to_workflow +### Key Components -Adds an objective to the workflow. +- **Agent**: Represents an individual AI agent with specific capabilities and responsibilities +- **Conversation**: Manages the interaction history between agents +- **MALT Orchestrator**: Coordinates the workflow and manages agent interactions +- **Concurrency Support**: Enables parallel execution of multiple agent instances -**Arguments:** +## Architecture Diagram -| Parameter | Type | Description | -|-----------|------|-------------| -| `task` | `str` | The description of the task. | -| `**kwargs` | | Additional keyword arguments for the task. | +```mermaid +flowchart TD + User[User/Client] -->|Submit Task| MALT[MALT Orchestrator] + + subgraph MALT Framework + MALT -->|Task| Creator[Creator Agent] + Creator -->|Initial Solution| Conversation[Conversation Manager] + Conversation -->|Solution| VerifierPool[Verifier Agents Pool] + + subgraph VerifierPool + Verifier1[Verifier Agent 1] + Verifier2[Verifier Agent 2] + Verifier3[Verifier Agent 3] + end + + VerifierPool -->|Verification Feedback| Conversation + Conversation -->|Solution + Feedback| RefinerPool[Refiner Agents Pool] + + subgraph RefinerPool + Refiner1[Refiner Agent 1] + Refiner2[Refiner Agent 2] + Refiner3[Refiner Agent 3] + end + + RefinerPool -->|Refined Solutions| Conversation + end + + Conversation -->|Final Output| User +``` -**Examples:** +## Execution Workflow -```python -workflow = BaseWorkflow() -workflow.add_objective_to_workflow(task="New Objective", agent=agent, args=[], kwargs={}) +```mermaid +sequenceDiagram + participant User + participant MALT + participant Creator + participant Verifiers + participant Refiners + participant Conversation + + User->>MALT: Submit task + MALT->>Creator: Process task + Creator->>Conversation: Add initial solution + + par Verification Phase + Conversation->>Verifiers: Send solution for verification + Verifiers->>Conversation: Return verification feedback + end + + par Refinement Phase + Conversation->>Refiners: Send solution + feedback + Refiners->>Conversation: Return refined solutions + end + + MALT->>Conversation: Request final output + Conversation->>MALT: Return conversation history + MALT->>User: Return final result ``` -### load_workflow_state +## API Reference + +### MALT Class -Loads the workflow state from a json file and restores the workflow state. +The core orchestrator that manages the multi-agent interaction process. -**Arguments:** +#### Constructor Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| -| `filepath` | `str` | `None` | The path to load the workflow state from. | - -**Examples:** +| `main_agent` | `Agent` | `None` | The primary agent (Creator) responsible for generating initial solutions | +| `refiner_agent` | `Agent` | `None` | The agent that refines solutions based on verification feedback | +| `verifier_agent` | `Agent` | `None` | The agent that verifies and evaluates solutions | +| `max_loops` | `int` | `1` | Maximum number of iterations for the task execution | +| `return_list` | `bool` | `False` | Flag to return output as a list | +| `return_dict` | `bool` | `False` | Flag to return output as a dictionary | +| `agents` | `list[Agent]` | `[]` | Alternative list of agents to use in the task | +| `preset_agents` | `bool` | `True` | Use default preset agents for mathematical proofs | -```python -workflow = BaseWorkflow() -workflow.load_workflow_state(filepath="workflow_state.json") -``` +#### Methods -### workflow_dashboard +| Method | Parameters | Return Type | Description | +|--------|------------|-------------|-------------| +| `reliability_check` | None | None | Validates agent configuration and parameters | +| `step` | `task: str, img: str = None, *args, **kwargs` | `str` or `list` or `dict` | Executes a single iteration of the MALT workflow | +| `run` | `task: str, img: str = None, *args, **kwargs` | `str` or `list` or `dict` | Executes the complete MALT workflow for a task | +| `run_batched` | `tasks: List[str], *args, **kwargs` | `List[str]` or `List[list]` or `List[dict]` | Sequentially processes multiple tasks | +| `run_concurrently` | `tasks: List[str], *args, **kwargs` | `concurrent.futures.Future` | Processes multiple tasks in parallel using ThreadPoolExecutor | +| `__call__` | `task: str, *args, **kwargs` | Same as `run` | Allows the MALT instance to be called as a function | +| `__str__` | None | `str` | Returns the conversation history as a string | +| `__repr__` | None | `str` | Returns the conversation history as a string | -Displays a dashboard for the workflow. -**Arguments:** +## Sample Implementations -| Parameter | Type | Description | -|-----------|------|-------------| -| `**kwargs` | | Additional keyword arguments to pass to the dashboard. | +### Default Mathematical Proof Agents -**Examples:** +The MALT framework includes preset agents specialized for mathematical proof generation and refinement: -```python -workflow = BaseWorkflow() -workflow.workflow_dashboard() -``` +1. **Proof Creator Agent**: Generates original mathematical theorems and proofs +2. **Proof Verifier Agent**: Critically evaluates and identifies issues in mathematical proofs +3. **Proof Refiner Agent**: Improves proofs based on verification feedback -### workflow_bootup +Each agent has a carefully designed system prompt that guides its behavior and specialization. -Initializes the workflow. +## Usage Examples -**Examples:** +### Basic Usage ```python -workflow = BaseWorkflow() -workflow.workflow_bootup() -``` +from swarms.structs.agent import Agent +from swarms.structs.multi_agent_exec import MALT --------------------------------------------------- +# Initialize with preset mathematical proof agents +malt = MALT(preset_agents=True) -# File: swarms/structs/basestructure.md +# Run a mathematical proof task +result = malt.run("Develop a theorem and proof related to prime numbers and their distribution.") -# Module/Function Name: BaseStructure +print(result) +``` -## Introduction: +### Custom Agents -The `BaseStructure` module contains the basic structure and attributes required for running machine learning models and associated metadata, error logging, artifact saving/loading, and relevant event logging. +```python +from swarms.structs.agent import Agent +from swarms.structs.multi_agent_exec import MALT -The module provides the flexibility to save and load the model metadata, log errors, save artifacts, and maintain a log for multiple events associated with multiple threads and batched operations. The key attributes of the module include **name**, **description**, **save_metadata_path**, and **save_error_path**. +# Define custom agents +creator = Agent( + agent_name="Physics-Creator", + model_name="gpt-4o-mini", + max_loops=1, + system_prompt="You are a theoretical physicist specializing in quantum mechanics..." +) -## Class Definition: +verifier = Agent( + agent_name="Physics-Verifier", + model_name="gpt-4o-mini", + max_loops=1, + system_prompt="You are an experimental physicist who verifies theoretical claims..." +) -### Arguments: -| Argument | Type | Description | -|----------------------|--------|----------------------------------------------------------------------| -| name | str | (Optional) The name of the structure. | -| description | str | (Optional) A description of the structure. | -| save_metadata | bool | A boolean flag to enable or disable metadata saving. | -| save_artifact_path | str | (Optional) The path to save artifacts. | -| save_metadata_path | str | (Optional) The path to save metadata. | -| save_error_path | str | (Optional) The path to save errors. | +refiner = Agent( + agent_name="Physics-Communicator", + model_name="gpt-4o-mini", + max_loops=1, + system_prompt="You excel at explaining complex physics concepts to diverse audiences..." +) -## Methods: +# Initialize MALT with custom agents +malt = MALT( + main_agent=creator, + verifier_agent=verifier, + refiner_agent=refiner, + preset_agents=False, + max_loops=1 +) -### 1. run -Runs the structure. +# Run a physics explanation task +result = malt.run("Explain the quantum entanglement phenomenon and its implications.") +``` -### 2. save_to_file -Saves data to a file. -* **data**: Value to be saved. -* **file_path**: Path where the data is to be saved. +### Concurrent Processing -### 3. load_from_file -Loads data from a file. -* **file_path**: Path from where the data is to be loaded. +```python +from swarms.structs.multi_agent_exec import MALT -### 4. save_metadata -Saves metadata to a file. -* **metadata**: Data to be saved as metadata. +# Initialize MALT +malt = MALT() -### 5. load_metadata -Loads metadata from a file. +# Define multiple tasks +tasks = [ + "Prove a theorem related to continuous functions on compact sets.", + "Develop a theorem about convergence in infinite-dimensional Hilbert spaces.", + "Create a theorem relating to measure theory and Lebesgue integration." +] -### 6. log_error -Logs error to a file. +# Process tasks concurrently +futures = malt.run_concurrently(tasks) -### 7. save_artifact -Saves artifact to a file. -* **artifact**: The artifact to be saved. -* **artifact_name**: Name of the artifact. +# Collect results as they complete +for future in futures: + result = future.result() + print(result) +``` -### 8. load_artifact -Loads artifact from a file. -* **artifact_name**: Name of the artifact. +## Example: Complex Mathematical Domain -### 9. log_event -Logs an event to a file. -* **event**: The event to be logged. -* **event_type**: Type of the event (optional, defaults to "INFO"). +Here's an example of how MALT can generate, verify, and refine a mathematical proof: -### 10. run_async -Runs the structure asynchronously. +### Input -### 11. save_metadata_async -Saves metadata to a file asynchronously. +```python +malt = MALT(preset_agents=True) +task = "Develop a theorem and rigorous proof related to the convergence properties of infinite series." +result = malt.run(task) +``` -### 12. load_metadata_async -Loads metadata from a file asynchronously. +### Output Flow + +1. **Creator Agent** generates a theorem and proof about conditions for absolute convergence +2. **Verifier Agents** identify issues: + - Logical gap in lemma 2 + - Missing justification for uniform convergence claim + - Imprecise definition of certain terms +3. **Refiner Agents** produce improved versions addressing these concerns +4. The final output contains the refined, rigorous mathematical proof -### 13. log_error_async -Logs error to a file asynchronously. +## Best Practices -### 14. save_artifact_async -Saves artifact to a file asynchronously. +1. **Task Specificity**: Provide clear, detailed task descriptions for optimal results +2. **Agent Specialization**: Design agent prompts to focus on specific aspects of the task +3. **Iteration Control**: Adjust `max_loops` based on task complexity +4. **Concurrent Verification**: Use multiple verifier instances for comprehensive evaluation +5. **Custom Agents**: Create domain-specific agents for specialized tasks -### 15. load_artifact_async -Loads artifact from a file asynchronously. +## Potential Improvements -### 16. log_event_async -Logs an event to a file asynchronously. +- Autonomously create specialized agents based on task requirements +- Implement feedback loops between agents for iterative improvement +- Add support for agent-specific memory and knowledge bases +- Expand concurrency capabilities for improved performance +- Implement learning mechanisms for agent improvement over time -### 17. asave_to_file -Saves data to a file asynchronously. +## References -### 18. aload_from_file -Loads data from a file asynchronously. +- Original MALT paper: [arXiv:2412.01928](https://arxiv.org/pdf/2412.01928) +- Built on the swarms framework for multi-agent systems -### 19. run_concurrent -Runs the structure concurrently. +-------------------------------------------------- -### 20. compress_data -Compresses data. +# File: swarms\structs\matrix_swarm.md -### 21. decompres_data -Decompresses data. +# MatrixSwarm -### 22. run_batched -Runs batched data. +The `MatrixSwarm` class provides a framework for managing and operating on matrices of AI agents, enabling matrix-like operations similar to linear algebra. This allows for complex agent interactions and parallel processing capabilities. -## Examples: +## Overview -### Example 1: Saving Metadata -```python -base_structure = BaseStructure(name="ExampleStructure") -metadata = {"key1": "value1", "key2": "value2"} -base_structure.save_metadata(metadata) -``` +`MatrixSwarm` treats AI agents as elements in a matrix, allowing for operations like addition, multiplication, and transposition. This approach enables sophisticated agent orchestration and parallel processing patterns. -### Example 2: Loading Artifact -```python -artifact_name = "example_artifact" -artifact_data = base_structure.load_artifact(artifact_name) -``` +## Installation -### Example 3: Running Concurrently -```python -concurrent_data = [data1, data2, data3] -results = base_structure.run_concurrent(batched_data=concurrent_data) +```bash +pip3 install -U swarms ``` -## Note: +## Basic Usage -The `BaseStructure` class is designed to provide a modular and extensible structure for managing metadata, logs, errors, and batched operations while running machine learning models. The class's methods offer asynchronous and concurrent execution capabilities, thus optimizing the performance of the associated applications and models. The module's attributes and methods cater to a wide range of use cases, making it an essential foundational component for machine learning and data-based applications. +```python +from swarms import Agent +from swarms.matrix import MatrixSwarm -# Conclusion: +# Create a 2x2 matrix of agents +agents = [ + [Agent(agent_name="Agent-0-0"), Agent(agent_name="Agent-0-1")], + [Agent(agent_name="Agent-1-0"), Agent(agent_name="Agent-1-1")] +] -The `BaseStructure` module offers a robust and flexible foundation for managing machine learning model metadata, error logs, and event tracking, including asynchronous, concurrent, and batched operations. By leveraging the inherent capabilities of this class, developers can enhance the reliability, scalability, and performance of machine learning-based applications. +# Initialize the matrix +matrix = MatrixSwarm(agents) +``` -## References: +## Class Constructor -- [Python Concurrent Programming with `asyncio`](https://docs.python.org/3/library/asyncio.html) -- [Understanding Thread Pool Executor in Python](https://docs.python.org/3/library/concurrent.futures.html#executor-objects) -- [Documentation on `gzip` Module for Data Compression](https://docs.python.org/3/library/gzip.html) +```python +def __init__(self, agents: List[List[Agent]]) +``` ---- +### Parameters +- `agents` (`List[List[Agent]]`): A 2D list of Agent instances representing the matrix. -The above documentation provides detailed information about the `BaseStructure` module, including its functionality, attributes, methods, usage examples, and references to relevant resources for further exploration. This comprehensive documentation aims to deepen the users' understanding of the module's purpose and how it can be effectively utilized in practice. +### Raises +- `ValueError`: If the input is not a valid 2D list of Agent instances. -Please let me know if you need further elaboration on any specific aspect or functionality of the `BaseStructure` module. +## Methods +### transpose() --------------------------------------------------- +Transposes the matrix of agents by swapping rows and columns. -# File: swarms/structs/concurrentworkflow.md +```python +def transpose(self) -> MatrixSwarm +``` -# ConcurrentWorkflow Documentation +#### Returns +- `MatrixSwarm`: A new MatrixSwarm instance with transposed dimensions. -## Overview +--- -The `ConcurrentWorkflow` class is designed to facilitate the concurrent execution of multiple agents, each tasked with solving a specific query or problem. This class is particularly useful in scenarios where multiple agents need to work in parallel, allowing for efficient resource utilization and faster completion of tasks. The workflow manages the execution, collects metadata, and optionally saves the results in a structured format. +### add(other) -### Key Features +Performs element-wise addition of two agent matrices. -- **Concurrent Execution**: Runs multiple agents simultaneously using Python's `asyncio` and `ThreadPoolExecutor`. -- **Metadata Collection**: Gathers detailed metadata about each agent's execution, including start and end times, duration, and output. -- **Customizable Output**: Allows the user to save metadata to a file or return it as a string or dictionary. -- **Error Handling**: Implements retry logic for improved reliability. -- **Batch Processing**: Supports running tasks in batches and parallel execution. -- **Asynchronous Execution**: Provides asynchronous run options for improved performance. +```python +def add(self, other: MatrixSwarm) -> MatrixSwarm +``` -## Class Definitions +#### Parameters +- `other` (`MatrixSwarm`): Another MatrixSwarm instance to add. -The `ConcurrentWorkflow` class is the core class that manages the concurrent execution of agents. It inherits from `BaseSwarm` and includes several key attributes and methods to facilitate this process. +#### Returns +- `MatrixSwarm`: A new MatrixSwarm resulting from the addition. -### Attributes +#### Raises +- `ValueError`: If matrix dimensions are incompatible. -| Attribute | Type | Description | -|------------------------|-------------------------|-----------------------------------------------------------| -| `name` | `str` | The name of the workflow. Defaults to `"ConcurrentWorkflow"`. | -| `description` | `str` | A brief description of the workflow. | -| `agents` | `List[Agent]` | A list of agents to be executed concurrently. | -| `metadata_output_path` | `str` | Path to save the metadata output. Defaults to `"agent_metadata.json"`. | -| `auto_save` | `bool` | Flag indicating whether to automatically save the metadata. | -| `output_schema` | `BaseModel` | The output schema for the metadata, defaults to `MetadataSchema`. | -| `max_loops` | `int` | Maximum number of loops for the workflow, defaults to `1`. | -| `return_str_on` | `bool` | Flag to return output as string. Defaults to `False`. | -| `agent_responses` | `List[str]` | List of agent responses as strings. | -| `auto_generate_prompts`| `bool` | Flag indicating whether to auto-generate prompts for agents. | -| `output_type` | `OutputType` | Type of output format to return. Defaults to `"dict"`. | -| `return_entire_history`| `bool` | Flag to return entire conversation history. Defaults to `False`. | -| `conversation` | `Conversation` | Conversation object to track agent interactions. | -| `max_workers` | `int` | Maximum number of worker threads. Defaults to CPU count. | +--- -## Methods +### scalar_multiply(scalar) -### ConcurrentWorkflow.\_\_init\_\_ +Scales the matrix by duplicating agents along rows. -Initializes the `ConcurrentWorkflow` class with the provided parameters. +```python +def scalar_multiply(self, scalar: int) -> MatrixSwarm +``` #### Parameters +- `scalar` (`int`): The multiplication factor. -| Parameter | Type | Default Value | Description | -|-----------------------|----------------|----------------------------------------|-----------------------------------------------------------| -| `name` | `str` | `"ConcurrentWorkflow"` | The name of the workflow. | -| `description` | `str` | `"Execution of multiple agents concurrently"` | A brief description of the workflow. | -| `agents` | `List[Agent]` | `[]` | A list of agents to be executed concurrently. | -| `metadata_output_path`| `str` | `"agent_metadata.json"` | Path to save the metadata output. | -| `auto_save` | `bool` | `True` | Flag indicating whether to automatically save the metadata. | -| `output_schema` | `BaseModel` | `MetadataSchema` | The output schema for the metadata. | -| `max_loops` | `int` | `1` | Maximum number of loops for the workflow. | -| `return_str_on` | `bool` | `False` | Flag to return output as string. | -| `agent_responses` | `List[str]` | `[]` | List of agent responses as strings. | -| `auto_generate_prompts`| `bool` | `False` | Flag indicating whether to auto-generate prompts for agents. | -| `output_type` | `OutputType` | `"dict"` | Type of output format to return. | -| `return_entire_history`| `bool` | `False` | Flag to return entire conversation history. | - -#### Raises - -- `ValueError`: If the list of agents is empty or if the description is empty. +#### Returns +- `MatrixSwarm`: A new MatrixSwarm with scaled dimensions. -### ConcurrentWorkflow.activate_auto_prompt_engineering +--- -Activates the auto-generate prompts feature for all agents in the workflow. +### multiply(other, inputs) -#### Example +Performs matrix multiplication (dot product) between two agent matrices. ```python -workflow = ConcurrentWorkflow(agents=[Agent()]) -workflow.activate_auto_prompt_engineering() -# All agents in the workflow will now auto-generate prompts. +def multiply(self, other: MatrixSwarm, inputs: List[str]) -> List[List[AgentOutput]] ``` -### ConcurrentWorkflow.transform_metadata_schema_to_str - -Transforms the metadata schema into a string format. - #### Parameters - -| Parameter | Type | Description | -|-------------|---------------------|-----------------------------------------------------------| -| `schema` | `MetadataSchema` | The metadata schema to transform. | +- `other` (`MatrixSwarm`): The second MatrixSwarm for multiplication. +- `inputs` (`List[str]`): Input queries for the agents. #### Returns +- `List[List[AgentOutput]]`: Matrix of operation results. -- `str`: The metadata schema as a formatted string. +#### Raises +- `ValueError`: If matrix dimensions are incompatible for multiplication. -### ConcurrentWorkflow.save_metadata +--- -Saves the metadata to a JSON file based on the `auto_save` flag. +### subtract(other) -#### Example +Performs element-wise subtraction of two agent matrices. ```python -workflow.save_metadata() -# Metadata will be saved to the specified path if auto_save is True. +def subtract(self, other: MatrixSwarm) -> MatrixSwarm ``` -### ConcurrentWorkflow.run - -Executes the workflow for the provided task. - #### Parameters - -| Parameter | Type | Description | -|-------------|---------------------|-----------------------------------------------------------| -| `task` | `Optional[str]` | The task or query to give to all agents. | -| `img` | `Optional[str]` | The image to be processed by the agents. | -| `*args` | `tuple` | Additional positional arguments. | -| `**kwargs` | `dict` | Additional keyword arguments. | +- `other` (`MatrixSwarm`): Another MatrixSwarm to subtract. #### Returns +- `MatrixSwarm`: A new MatrixSwarm resulting from the subtraction. -- `Any`: The result of the execution, format depends on output_type and return_entire_history settings. - -#### Raises +--- -- `ValueError`: If an invalid device is specified. -- `Exception`: If any other error occurs during execution. +### identity(size) -### ConcurrentWorkflow.run_batched +Creates an identity matrix of agents. -Runs the workflow for a batch of tasks. +```python +def identity(self, size: int) -> MatrixSwarm +``` #### Parameters - -| Parameter | Type | Description | -|-------------|--------------|-----------------------------------------------------------| -| `tasks` | `List[str]` | A list of tasks or queries to give to all agents. | +- `size` (`int`): Size of the identity matrix (NxN). #### Returns +- `MatrixSwarm`: An identity MatrixSwarm. -- `List[Union[Dict[str, Any], str]]`: A list of final metadata for each task. +--- -#### Example +### determinant() + +Computes the determinant of a square agent matrix. ```python -tasks = ["Task 1", "Task 2"] -results = workflow.run_batched(tasks) -print(results) +def determinant(self) -> Any ``` +#### Returns +- `Any`: The determinant result. +#### Raises +- `ValueError`: If the matrix is not square. -## Usage Examples +--- -### Example 1: Basic Usage +### save_to_file(path) -```python -import os +Saves the matrix structure and metadata to a JSON file. -from swarms import Agent, ConcurrentWorkflow, OpenAIChat -# Define custom system prompts for each social media platform -TWITTER_AGENT_SYS_PROMPT = """ -You are a Twitter marketing expert specializing in real estate. Your task is to create engaging, concise tweets to promote properties, analyze trends to maximize engagement, and use appropriate hashtags and timing to reach potential buyers. -""" +```python +def save_to_file(self, path: str) -> None +``` -INSTAGRAM_AGENT_SYS_PROMPT = """ -You are an Instagram marketing expert focusing on real estate. Your task is to create visually appealing posts with engaging captions and hashtags to showcase properties, targeting specific demographics interested in real estate. -""" +#### Parameters +- `path` (`str`): File path for saving the matrix data. -FACEBOOK_AGENT_SYS_PROMPT = """ -You are a Facebook marketing expert for real estate. Your task is to craft posts optimized for engagement and reach on Facebook, including using images, links, and targeted messaging to attract potential property buyers. -""" +## Extended Example -LINKEDIN_AGENT_SYS_PROMPT = """ -You are a LinkedIn marketing expert for the real estate industry. Your task is to create professional and informative posts, highlighting property features, market trends, and investment opportunities, tailored to professionals and investors. -""" +Here's a comprehensive example demonstrating various MatrixSwarm operations: -EMAIL_AGENT_SYS_PROMPT = """ -You are an Email marketing expert specializing in real estate. Your task is to write compelling email campaigns to promote properties, focusing on personalization, subject lines, and effective call-to-action strategies to drive conversions. -""" +```python +from swarms import Agent +from swarms.matrix import MatrixSwarm -# Initialize your agents for different social media platforms +# Create agents with specific configurations agents = [ - Agent( - agent_name="Twitter-RealEstate-Agent", - system_prompt=TWITTER_AGENT_SYS_PROMPT, - model_name="gpt-4o", - max_loops=1, - dynamic_temperature_enabled=True, - saved_state_path="twitter_realestate_agent.json", - user_name="swarm_corp", - retry_attempts=1, - ), - Agent( - agent_name="Instagram-RealEstate-Agent", - system_prompt=INSTAGRAM_AGENT_SYS_PROMPT, - model_name="gpt-4o", - max_loops=1, - dynamic_temperature_enabled=True, - saved_state_path="instagram_realestate_agent.json", - user_name="swarm_corp", - retry_attempts=1, - ), - Agent( - agent_name="Facebook-RealEstate-Agent", - system_prompt=FACEBOOK_AGENT_SYS_PROMPT, - model_name="gpt-4o", - max_loops=1, - dynamic_temperature_enabled=True, - saved_state_path="facebook_realestate_agent.json", - user_name="swarm_corp", - retry_attempts=1, - ), - Agent( - agent_name="LinkedIn-RealEstate-Agent", - system_prompt=LINKEDIN_AGENT_SYS_PROMPT, - model_name="gpt-4o", - max_loops=1, - dynamic_temperature_enabled=True, - saved_state_path="linkedin_realestate_agent.json", - user_name="swarm_corp", - retry_attempts=1, - ), - Agent( - agent_name="Email-RealEstate-Agent", - system_prompt=EMAIL_AGENT_SYS_PROMPT, - model_name="gpt-4o", - max_loops=1, - dynamic_temperature_enabled=True, - saved_state_path="email_realestate_agent.json", - user_name="swarm_corp", - retry_attempts=1, - ), + [ + Agent( + agent_name=f"Agent-{i}-{j}", + system_prompt="Your system prompt here", + model_name="gpt-4", + max_loops=1, + verbose=True + ) for j in range(2) + ] for i in range(2) ] -# Initialize workflow -workflow = ConcurrentWorkflow( - name="Real Estate Marketing Swarm", - agents=agents, - metadata_output_path="metadata.json", - description="Concurrent swarm of content generators for real estate!", - auto_save=True, -) - -# Run workflow -task = "Create a marketing campaign for a luxury beachfront property in Miami, focusing on its stunning ocean views, private beach access, and state-of-the-art amenities." -metadata = workflow.run(task) -print(metadata) -``` +# Initialize matrix +matrix = MatrixSwarm(agents) -### Example 2: Custom Output Handling +# Example operations +transposed = matrix.transpose() +scaled = matrix.scalar_multiply(2) -```python -# Initialize workflow with string output -workflow = ConcurrentWorkflow( - name="Real Estate Marketing Swarm", - agents=agents, - metadata_output_path="metadata.json", - description="Concurrent swarm of content generators for real estate!", - auto_save=True, - return_str_on=True -) +# Run operations with inputs +inputs = ["Query 1", "Query 2"] +results = matrix.multiply(transposed, inputs) -# Run workflow -task = "Develop a marketing strategy for a newly renovated historic townhouse in Boston, emphasizing its blend of classic architecture and modern amenities." -metadata_str = workflow.run(task) -print(metadata_str) +# Save results +matrix.save_to_file("matrix_results.json") ``` -### Example 3: Error Handling and Debugging +## Output Schema + +The `AgentOutput` class defines the structure for operation results: ```python -import logging +class AgentOutput(BaseModel): + agent_name: str + input_query: str + output_result: Any + metadata: dict +``` -# Set up logging -logging.basicConfig(level=logging.INFO) +## Best Practices -# Initialize workflow -workflow = ConcurrentWorkflow( - name="Real Estate Marketing Swarm", - agents=agents, - metadata_output_path="metadata.json", - description="Concurrent swarm of content generators for real estate!", - auto_save=True -) +1. **Initialization** + - Ensure all agents in the matrix are properly configured before initialization + - Validate matrix dimensions for your use case -# Run workflow with error handling -try: - task = "Create a marketing campaign for a eco-friendly tiny house community in Portland, Oregon." - metadata = workflow.run(task) - print(metadata) -except Exception as e: - logging.error(f"An error occurred during workflow execution: {str(e)}") - # Additional error handling or debugging steps can be added here -``` +2. **Operation Performance** + - Consider computational costs for large matrices + - Use appropriate batch sizes for inputs -### Example 4: Batch Processing +3. **Error Handling** + - Implement proper error handling for agent operations + - Validate inputs before matrix operations -```python -# Initialize workflow -workflow = ConcurrentWorkflow( - name="Real Estate Marketing Swarm", - agents=agents, - metadata_output_path="metadata_batch.json", - description="Concurrent swarm of content generators for real estate!", - auto_save=True -) +4. **Resource Management** + - Monitor agent resource usage in large matrices + - Implement proper cleanup procedures -# Define a list of tasks -tasks = [ - "Market a family-friendly suburban home with a large backyard and excellent schools nearby.", - "Promote a high-rise luxury apartment in New York City with panoramic skyline views.", - "Advertise a ski-in/ski-out chalet in Aspen, Colorado, perfect for winter sports enthusiasts." -] +## Limitations -# Run workflow in batch mode -results = workflow.run_batched(tasks) +- Matrix operations are constrained by the underlying agent capabilities +- Performance may vary based on agent configuration and complexity +- Resource usage scales with matrix dimensions -# Process and print results -for task, result in zip(tasks, results): - print(f"Task: {task}") - print(f"Result: {result}\n") -``` +## See Also +- [Swarms Documentation](https://github.com/kyegomez/swarms) +- [Agent Class Reference](https://github.com/kyegomez/swarms/tree/main/swarms) +-------------------------------------------------- -## Tips and Best Practices +# File: swarms\structs\moa.md -- **Agent Initialization**: Ensure that all agents are correctly initialized with their required configurations before passing them to `ConcurrentWorkflow`. -- **Metadata Management**: Use the `auto_save` flag to automatically save metadata if you plan to run multiple workflows in succession. -- **Concurrency Limits**: Adjust the number of agents based on your system's capabilities to avoid overloading resources. -- **Error Handling**: Implement try-except blocks when running workflows to catch and handle exceptions gracefully. -- **Batch Processing**: For large numbers of tasks, consider using `run_batched` or `run_parallel` methods to improve overall throughput. -- **Asynchronous Operations**: Utilize asynchronous methods (`run_async`, `run_batched_async`, `run_parallel_async`) when dealing with I/O-bound tasks or when you need to maintain responsiveness in your application. -- **Logging**: Implement detailed logging to track the progress of your workflows and troubleshoot any issues that may arise. -- **Resource Management**: Be mindful of API rate limits and resource consumption, especially when running large batches or parallel executions. -- **Testing**: Thoroughly test your workflows with various inputs and edge cases to ensure robust performance in production environments. +# MixtureOfAgents Class Documentation -## References and Resources +## Architecture Overview -- [Python's `asyncio` Documentation](https://docs.python.org/3/library/asyncio.html) -- [Pydantic Documentation](https://pydantic-docs.helpmanual.io/) -- [ThreadPoolExecutor in Python](https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.ThreadPoolExecutor) -- [Loguru for Logging in Python](https://loguru.readthedocs.io/en/stable/) -- [Tenacity: Retry library for Python](https://tenacity.readthedocs.io/en/latest/) +```mermaid +graph TD + A[Input Task] --> B[Initialize MixtureOfAgents] + B --> C[Reliability Check] + C --> D[Layer 1: Parallel Agent Execution] + D --> E[Layer 2: Sequential Processing] + E --> F[Layer 3: Parallel Agent Execution] + F --> G[Final Aggregator Agent] + G --> H[Output Response] + + subgraph "Agent Layer Details" + I[Agent 1] --> J[Agent Results] + K[Agent 2] --> J + L[Agent N] --> J + end + + subgraph "Processing Flow" + M[Previous Context] --> N[Current Task] + N --> O[Agent Processing] + O --> P[Aggregation] + P --> M + end +``` --------------------------------------------------- +## Overview -# File: swarms/structs/conversation.md +The `MixtureOfAgents` class represents a mixture of agents operating within a swarm. The workflow of the swarm follows a parallel → sequential → parallel → final output agent process. This implementation is inspired by concepts discussed in the paper: [https://arxiv.org/pdf/2406.04692](https://arxiv.org/pdf/2406.04692). -# Module/Class Name: Conversation +The class is designed to manage a collection of agents, orchestrate their execution in layers, and handle the final aggregation of their outputs through a designated final agent. This architecture facilitates complex, multi-step processing where intermediate results are refined through successive layers of agent interactions. -## Introduction +## Class Definition -The `Conversation` class is a powerful tool for managing and structuring conversation data in a Python program. It enables you to create, manipulate, and analyze conversations easily. This documentation will provide you with a comprehensive understanding of the `Conversation` class, its attributes, methods, and how to effectively use it. +### MixtureOfAgents -## Table of Contents +```python +class MixtureOfAgents(BaseSwarm): +``` -1. **Class Definition** - - Overview - - Attributes +### Attributes -2. **Methods** - - `__init__(self, time_enabled: bool = False, *args, **kwargs)` - - `add(self, role: str, content: str, *args, **kwargs)` - - `delete(self, index: str)` - - `update(self, index: str, role, content)` - - `query(self, index: str)` - - `search(self, keyword: str)` - - `display_conversation(self, detailed: bool = False)` - - `export_conversation(self, filename: str)` - - `import_conversation(self, filename: str)` - - `count_messages_by_role(self)` - - `return_history_as_string(self)` - - `save_as_json(self, filename: str)` - - `load_from_json(self, filename: str)` - - `search_keyword_in_conversation(self, keyword: str)` - - `pretty_print_conversation(self, messages)` +| Attribute | Type | Description | Default | +|------------------|--------------|-------------------------------------------------------------------------------------|---------------------------------| +| `agents` | `List[Agent]`| The list of agents in the swarm. | `None` | +| `flow` | `str` | The flow of the swarm. | `parallel -> sequential -> parallel -> final output agent` | +| `max_loops` | `int` | The maximum number of loops to run. | `1` | +| `verbose` | `bool` | Flag indicating whether to print verbose output. | `True` | +| `layers` | `int` | The number of layers in the swarm. | `3` | +| `rules` | `str` | The rules for the swarm. | `None` | +| `final_agent` | `Agent` | The agent to handle the final output processing. | `None` | +| `auto_save` | `bool` | Flag indicating whether to auto-save the metadata to a file. | `False` | +| `saved_file_name`| `str` | The name of the file where the metadata will be saved. | `"moe_swarm.json"` | ---- +## Methods -### 1. Class Definition +### `__init__` -#### Overview +#### Parameters -The `Conversation` class is designed to manage conversations by keeping track of messages and their attributes. It offers methods for adding, deleting, updating, querying, and displaying messages within the conversation. Additionally, it supports exporting and importing conversations, searching for specific keywords, and more. +| Parameter | Type | Description | Default | +|------------------|--------------|-----------------------------------------------------------------------------------------------|----------------------------------------| +| `name` | `str` | The name of the swarm. | `"MixtureOfAgents"` | +| `description` | `str` | A brief description of the swarm. | `"A swarm of agents that run in parallel and sequentially."` | +| `agents` | `List[Agent]`| The list of agents in the swarm. | `None` | +| `max_loops` | `int` | The maximum number of loops to run. | `1` | +| `verbose` | `bool` | Flag indicating whether to print verbose output. | `True` | +| `layers` | `int` | The number of layers in the swarm. | `3` | +| `rules` | `str` | The rules for the swarm. | `None` | +| `final_agent` | `Agent` | The agent to handle the final output processing. | `None` | +| `auto_save` | `bool` | Flag indicating whether to auto-save the metadata to a file. | `False` | +| `saved_file_name`| `str` | The name of the file where the metadata will be saved. | `"moe_swarm.json"` | -#### Attributes +### `agent_check` -- `time_enabled (bool)`: A flag indicating whether to enable timestamp recording for messages. -- `conversation_history (list)`: A list that stores messages in the conversation. +```python +def agent_check(self): +``` -### 2. Methods +#### Description -#### `__init__(self, time_enabled: bool = False, *args, **kwargs)` +Checks if the provided `agents` attribute is a list of `Agent` instances. Raises a `TypeError` if the validation fails. -- **Description**: Initializes a new Conversation object. -- **Parameters**: - - `time_enabled (bool)`: If `True`, timestamps will be recorded for each message. Default is `False`. +#### Example Usage -#### `add(self, role: str, content: str, *args, **kwargs)` +```python +moe_swarm = MixtureOfAgents(agents=[agent1, agent2]) +moe_swarm.agent_check() # Validates the agents +``` -- **Description**: Adds a message to the conversation history. -- **Parameters**: - - `role (str)`: The role of the speaker (e.g., "user," "assistant"). - - `content (str)`: The content of the message. +### `final_agent_check` -#### `delete(self, index: str)` +```python +def final_agent_check(self): +``` -- **Description**: Deletes a message from the conversation history. -- **Parameters**: - - `index (str)`: The index of the message to delete. +#### Description -#### `update(self, index: str, role, content)` +Checks if the provided `final_agent` attribute is an instance of `Agent`. Raises a `TypeError` if the validation fails. -- **Description**: Updates a message in the conversation history. -- **Parameters**: - - `index (str)`: The index of the message to update. - - `role (_type_)`: The new role of the speaker. - - `content (_type_)`: The new content of the message. +#### Example Usage -#### `query(self, index: str)` +```python +moe_swarm = MixtureOfAgents(final_agent=final_agent) +moe_swarm.final_agent_check() # Validates the final agent +``` -- **Description**: Retrieves a message from the conversation history. -- **Parameters**: - - `index (str)`: The index of the message to query. -- **Returns**: The message as a string. +### `swarm_initialization` -#### `search(self, keyword: str)` +```python +def swarm_initialization(self): +``` -- **Description**: Searches for messages containing a specific keyword in the conversation history. -- **Parameters**: - - `keyword (str)`: The keyword to search for. -- **Returns**: A list of messages that contain the keyword. +#### Description -#### `display_conversation(self, detailed: bool = False)` +Initializes the swarm by logging the swarm name, description, and the number of agents. -- **Description**: Displays the conversation history. -- **Parameters**: - - `detailed (bool, optional)`: If `True`, provides detailed information about each message. Default is `False`. +#### Example Usage -#### `export_conversation(self, filename: str)` +```python +moe_swarm = MixtureOfAgents(agents=[agent1, agent2]) +moe_swarm.swarm_initialization() # Initializes the swarm +``` -- **Description**: Exports the conversation history to a text file. -- **Parameters**: - - `filename (str)`: The name of the file to export to. +### `run` -#### `import_conversation(self, filename: str)` +```python +def run(self, task: str = None, *args, **kwargs): +``` -- **Description**: Imports a conversation history from a text file. -- **Parameters**: - - `filename (str)`: The name of the file to import from. +#### Parameters -#### `count_messages_by_role(self)` +| Parameter | Type | Description | Default | +|-----------|--------|---------------------------------|---------| +| `task` | `str` | The task to be performed by the swarm. | `None` | +| `*args` | `tuple`| Additional arguments. | `None` | +| `**kwargs`| `dict` | Additional keyword arguments. | `None` | -- **Description**: Counts the number of messages by role in the conversation. -- **Returns**: A dictionary containing the count of messages for each role. +#### Returns -#### `return_history_as_string(self)` +| Type | Description | +|-------|---------------------------------------------| +| `str` | The conversation history as a string. | -- **Description**: Returns the entire conversation history as a single string. -- **Returns**: The conversation history as a string. +#### Description -#### `save_as_json(self, filename: str)` +Runs the swarm with the given task, orchestrates the execution of agents through the specified layers, and returns the conversation history. -- **Description**: Saves the conversation history as a JSON file. -- **Parameters**: - - `filename (str)`: The name of the JSON file to save. +#### Example Usage -#### `load_from_json(self, filename: str)` +```python +moe_swarm = MixtureOfAgents(agents=[agent1, agent2], final_agent=final_agent) +history = moe_swarm.run(task="Solve this problem.") +print(history) +``` -- **Description**: Loads a conversation history from a JSON file. -- **Parameters**: - - `filename (str)`: The name of the JSON file to load. +### `reliability_check` -#### `search_keyword_in_conversation(self, keyword: str)` +```python +def reliability_check(self) -> None: +``` -- **Description**: Searches for a keyword in the conversation history and returns matching messages. -- **Parameters**: - - `keyword (str)`: The keyword to search for. -- **Returns**: A list of messages containing the keyword. +#### Description -#### `pretty_print_conversation(self, messages)` +Performs validation checks on the Mixture of Agents class to ensure all required components are properly configured. Raises ValueError if any checks fail. -- **Description**: Pretty prints a list of messages with colored role indicators. -- **Parameters**: - - `messages (list)`: A list of messages to print. +#### Validation Checks: +- Verifies reference agents are provided +- Validates aggregator agent exists +- Checks aggregator system prompt is set +- Ensures layers count is valid (> 0) -## Examples +### `_get_final_system_prompt` -Here are some usage examples of the `Conversation` class: +```python +def _get_final_system_prompt(self, system_prompt: str, results: List[str]) -> str: +``` -### Creating a Conversation +#### Description -```python -from swarms.structs import Conversation +Internal method that constructs a system prompt for subsequent layers by incorporating previous responses. -conv = Conversation() -``` +#### Parameters -### Adding Messages +| Parameter | Type | Description | +|-----------|------|-------------| +| `system_prompt` | `str` | The initial system prompt | +| `results` | `List[str]` | List of previous responses | -```python -conv.add("user", "Hello, world!") -conv.add("assistant", "Hello, user!") -``` +#### Returns + +| Type | Description | +|------|-------------| +| `str` | Combined system prompt with previous responses | -### Displaying the Conversation +### `run_batched` ```python -conv.display_conversation() +def run_batched(self, tasks: List[str]) -> List[str]: ``` -### Searching for Messages +#### Description -```python -result = conv.search("Hello") -``` +Processes multiple tasks sequentially, returning a list of responses. -### Exporting and Importing Conversations +#### Parameters -```python -conv.export_conversation("conversation.txt") -conv.import_conversation("conversation.txt") -``` +| Parameter | Type | Description | +|-----------|------|-------------| +| `tasks` | `List[str]` | List of tasks to process | -### Counting Messages by Role +#### Returns -```python -counts = conv.count_messages_by_role() -``` +| Type | Description | +|------|-------------| +| `List[str]` | List of responses for each task | -### Loading and Saving as JSON +### `run_concurrently` ```python -conv.save_as_json("conversation.json") -conv.load_from_json("conversation.json") +def run_concurrently(self, tasks: List[str]) -> List[str]: ``` -Certainly! Let's continue with more examples and additional information about the `Conversation` class. +#### Description -### Querying a Specific Message +Processes multiple tasks concurrently using a ThreadPoolExecutor, optimizing for parallel execution. -You can retrieve a specific message from the conversation by its index: +#### Parameters -```python -message = conv.query(0) # Retrieves the first message -``` +| Parameter | Type | Description | +|-----------|------|-------------| +| `tasks` | `List[str]` | List of tasks to process concurrently | -### Updating a Message +#### Returns -You can update a message's content or role within the conversation: +| Type | Description | +|------|-------------| +| `List[str]` | List of responses for each task | -```python -conv.update(0, "user", "Hi there!") # Updates the first message -``` +## Detailed Explanation -### Deleting a Message +### Initialization -If you want to remove a message from the conversation, you can use the `delete` method: +The `__init__` method initializes the swarm with the provided parameters, sets up the conversation rules, and invokes the initialization of the swarm. It also ensures the validity of the `agents` and `final_agent` attributes by calling the `agent_check` and `final_agent_check` methods respectively. -```python -conv.delete(0) # Deletes the first message -``` +### Agent Validation -### Counting Messages by Role +The `agent_check` method validates whether the `agents` attribute is a list of `Agent` instances, while the `final_agent_check` method validates whether the `final_agent` is an instance of `Agent`. These checks are crucial to ensure that the swarm operates correctly with the appropriate agent types. -You can count the number of messages by role in the conversation: +### Swarm Initialization -```python -counts = conv.count_messages_by_role() -# Example result: {'user': 2, 'assistant': 2} -``` +The `swarm_initialization` method logs essential information about the swarm, including its name, description, and the number of agents. This provides a clear starting point for the swarm's operations and facilitates debugging and monitoring. -### Exporting and Importing as Text +### Running the Swarm -You can export the conversation to a text file and later import it: +The `run` method is the core of the `MixtureOfAgents` class. It orchestrates the execution of agents through multiple layers, collects their outputs, and processes the final output using the `final_agent`. The conversation history is maintained and updated throughout this process, allowing for a seamless flow of information and responses. -```python -conv.export_conversation("conversation.txt") # Export -conv.import_conversation("conversation.txt") # Import -``` +During each layer, the method iterates over the agents, invokes their `run` method with the current conversation history, and logs the outputs. These outputs are then added to the conversation, and the history is updated for the next layer. -### Exporting and Importing as JSON +After all layers are completed, the final output agent processes the entire conversation history, and the metadata is created and optionally saved to a file. This metadata includes details about the layers, agent runs, and final output, providing a comprehensive record of the swarm's execution. -Conversations can also be saved and loaded as JSON files: +## Additional Information and Tips -```python -conv.save_as_json("conversation.json") # Save as JSON -conv.load_from_json("conversation.json") # Load from JSON -``` +### Common Issues and Solutions -### Searching for a Keyword +- **Type Errors**: Ensure that all agents in the `agents` list and the `final_agent` are instances of the `Agent` class. The `agent_check` and `final_agent_check` methods help validate this. +- **Verbose Logging**: Use the `verbose` flag to control the verbosity of the output. This can help with debugging or reduce clutter in the logs. +- **Auto-Save Feature**: Utilize the `auto_save` flag to automatically save the metadata to a file. This can be useful for keeping records of the swarm's operations without manual intervention. -You can search for messages containing a specific keyword within the conversation: +### References and Resources -```python -results = conv.search_keyword_in_conversation("Hello") -``` +For further reading and background information on the concepts used in the `MixtureOfAgents` class, refer to the paper: [https://arxiv.org/pdf/2406.04692](https://arxiv.org/pdf/2406.04692). -### Pretty Printing +### Usage Examples -The `pretty_print_conversation` method provides a visually appealing way to display messages with colored role indicators: +#### Example 1: Basic Initialization and Run ```python -conv.pretty_print_conversation(conv.conversation_history) -``` - -These examples demonstrate the versatility of the `Conversation` class in managing and interacting with conversation data. Whether you're building a chatbot, conducting analysis, or simply organizing dialogues, this class offers a robust set of tools to help you accomplish your goals. +from swarms import MixtureOfAgents, Agent -## Conclusion +from swarm_models import OpenAIChat -The `Conversation` class is a valuable utility for handling conversation data in Python. With its ability to add, update, delete, search, export, and import messages, you have the flexibility to work with conversations in various ways. Feel free to explore its features and adapt them to your specific projects and applications. +# Define agents +director = Agent( + agent_name="Director", + system_prompt="Directs the tasks for the accountants", + llm=OpenAIChat(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="director.json", +) -If you have any further questions or need additional assistance, please don't hesitate to ask! +# Initialize accountant 1 +accountant1 = Agent( + agent_name="Accountant1", + system_prompt="Prepares financial statements", + llm=OpenAIChat(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="accountant1.json", +) --------------------------------------------------- +# Initialize accountant 2 +accountant2 = Agent( + agent_name="Accountant2", + system_prompt="Audits financial records", + llm=OpenAIChat(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="accountant2.json", +) -# File: swarms/structs/create_new_swarm.md -# How to Add a New Swarm Class +# Initialize the MixtureOfAgents +moe_swarm = MixtureOfAgents(agents=[director, accountant1, accountant2], final_agent=director) -This guide provides comprehensive step-by-step instructions for developers to create and add a new swarm. It emphasizes the importance of adhering to best practices, using proper type hints, and documenting code thoroughly to ensure maintainability, scalability, and clarity in your implementations. +# Run the swarm +history = moe_swarm.run(task="Perform task X.") +print(history) +``` -## Overview +#### Example 2: Verbose Output and Auto-Save -A Swarm class enables developers to manage and coordinate multiple agents working together to accomplish complex tasks efficiently. Each Swarm must: +```python +from swarms import MixtureOfAgents, Agent -- Contain a `run(task: str, img: str, *args, **kwargs)` method, which serves as the primary execution method for tasks. -- Include `name`, `description`, and `agents` parameters. -- Ensure `agents` is a list of callables, with each callable adhering to specific requirements for dynamic agent behavior. -- Follow type-hinting and documentation best practices to maintain code clarity and reliability. +from swarm_models import OpenAIChat -Each Agent within the swarm must: +# Define Agents +# Define agents +director = Agent( + agent_name="Director", + system_prompt="Directs the tasks for the accountants", + llm=OpenAIChat(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="director.json", +) -- Contain `agent_name`, `system_prompt`, and a `run` method. -- Follow similar type hinting and documentation standards to ensure consistency and readability. +# Initialize accountant 1 +accountant1 = Agent( + agent_name="Accountant1", + system_prompt="Prepares financial statements", + llm=OpenAIChat(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="accountant1.json", +) -By adhering to these requirements, you can create robust, reusable, and modular swarms that streamline task management and enhance collaborative functionality. Developers are also encouraged to contribute their swarms back to the open-source community by submitting a pull request to the Swarms repository at [https://github.com/kyegomez/swarms](https://github.com/kyegomez/swarms). +# Initialize accountant 2 +accountant2 = Agent( + agent_name="Accountant2", + system_prompt="Audits financial records", + llm=OpenAIChat(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="accountant2.json", +) ---- +# Initialize the MixtureOfAgents with verbose output and auto-save enabled +moe_swarm = MixtureOfAgents( + agents=[director, accountant1, accountant2], + final_agent=director, + verbose=True, + auto_save=True +) -## Creating a Swarm Class +# Run the swarm +history = moe_swarm.run(task="Analyze data set Y.") +print(history) +``` -Below is a detailed template for creating a Swarm class. Ensure that all elements are documented and clearly defined: +#### Example 3: Custom Rules and Multiple Layers ```python -from typing import Callable, Any, List - -class MySwarm: - """ - A custom swarm class to manage and execute tasks with multiple agents. +from swarms import MixtureOfAgents, Agent - Attributes: - name (str): The name of the swarm. - description (str): A brief description of the swarm's purpose. - agents (List[Callable]): A list of callables representing the agents to be utilized. - """ +from swarm_models import OpenAIChat - def __init__(self, name: str, description: str, agents: List[Callable]): - """ - Initialize the Swarm with its name, description, and agents. +# Define agents +# Initialize the director agent +director = Agent( + agent_name="Director", + system_prompt="Directs the tasks for the accountants", + llm=OpenAIChat(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="director.json", +) - Args: - name (str): The name of the swarm. - description (str): A description of the swarm. - agents (List[Callable]): A list of callables that provide the agents for the swarm. - """ - self.name = name - self.description = description - self.agents = agents +# Initialize accountant 1 +accountant1 = Agent( + agent_name="Accountant1", + system_prompt="Prepares financial statements", + llm=OpenAIChat(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="accountant1.json", +) - def run(self, task: str, img: str, *args: Any, **kwargs: Any) -> Any: - """ - Execute a task using the swarm and its agents. +# Initialize accountant 2 +accountant2 = Agent( + agent_name="Accountant2", + system_prompt="Audits financial records", + llm=OpenAIChat(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="accountant2.json", +) - Args: - task (str): The task description. - img (str): The image input. - *args: Additional positional arguments for customization. - **kwargs: Additional keyword arguments for fine-tuning behavior. +# Initialize the MixtureOfAgents with custom rules and multiple layers +moe_swarm = MixtureOfAgents( + agents=[director, accountant1, accountant2], + final_agent=director, + layers=5, + rules="Custom rules for the swarm" +) - Returns: - Any: The result of the task execution, aggregated from all agents. - """ - results = [] - for agent in self.agents: - result = agent.run(task, img, *args, **kwargs) - results.append(result) - return results +# Run the swarm +history = moe_swarm.run(task="Optimize process Z.") +print(history) ``` -This Swarm class serves as the main orchestrator for coordinating agents and running tasks dynamically and flexibly. +This comprehensive documentation provides a detailed understanding of the `MixtureOfAgents` class, its attributes, methods, and usage. The examples illustrate how to initialize and run the swarm, demonstrating its flexibility and capability to handle various tasks and configurations. ---- -## Creating an Agent Class +# Conclusion -Each agent must follow a well-defined structure to ensure compatibility with the swarm. Below is an example of an agent class: +The `MixtureOfAgents` class is a powerful and flexible framework for managing and orchestrating a swarm of agents. By following a structured approach of parallel and sequential processing, it enables the implementation of complex multi-step workflows where intermediate results are refined through multiple layers of agent interactions. This architecture is particularly suitable for tasks that require iterative processing, collaboration among diverse agents, and sophisticated aggregation of outputs. -```python -class Agent: - """ - A single agent class to handle specific tasks assigned by the swarm. +### Key Takeaways - Attributes: - agent_name (str): The name of the agent. - system_prompt (str): The system prompt guiding the agent's behavior and purpose. - """ +1. **Flexible Initialization**: The class allows for customizable initialization with various parameters, enabling users to tailor the swarm's configuration to their specific needs. +2. **Robust Agent Management**: With built-in validation methods, the class ensures that all agents and the final agent are correctly instantiated, preventing runtime errors and facilitating smooth execution. +3. **Layered Processing**: The layered approach to processing allows for intermediate results to be iteratively refined, enhancing the overall output quality. +4. **Verbose Logging and Auto-Save**: These features aid in debugging, monitoring, and record-keeping, providing transparency and ease of management. +5. **Comprehensive Documentation**: The detailed class and method documentation, along with numerous usage examples, provide a clear and thorough understanding of how to leverage the `MixtureOfAgents` class effectively. - def __init__(self, agent_name: str, system_prompt: str): - """ - Initialize the agent with its name and system prompt. +### Practical Applications - Args: - agent_name (str): The name of the agent. - system_prompt (str): The guiding prompt for the agent. - """ - self.agent_name = agent_name - self.system_prompt = system_prompt +The `MixtureOfAgents` class can be applied in various domains, including but not limited to: - def run(self, task: str, img: str, *args: Any, **kwargs: Any) -> Any: - """ - Execute a specific task assigned to the agent. +- **Natural Language Processing (NLP)**: Managing a swarm of NLP models to process, analyze, and synthesize text. +- **Data Analysis**: Coordinating multiple data analysis agents to process and interpret complex data sets. +- **Optimization Problems**: Running a swarm of optimization algorithms to solve complex problems in fields such as logistics, finance, and engineering. +- **AI Research**: Implementing experimental setups that require the collaboration of multiple AI models or agents to explore new methodologies and approaches. - Args: - task (str): The task description. - img (str): The image input for processing. - *args: Additional positional arguments for task details. - **kwargs: Additional keyword arguments for extended functionality. +### Future Extensions - Returns: - Any: The result of the task execution, which can be customized. - """ - # Example implementation (to be customized by developer) - return f"Agent {self.agent_name} executed task: {task}" -``` +The `MixtureOfAgents` framework provides a solid foundation for further extensions and customizations, including: -This structure ensures that each agent can independently handle tasks and integrate seamlessly into a swarm. +- **Dynamic Layer Configuration**: Allowing layers to be added or removed dynamically based on the task requirements or intermediate results. +- **Advanced Agent Communication**: Enhancing the communication protocols between agents to allow for more sophisticated information exchange. +- **Integration with Other Frameworks**: Seamlessly integrating with other machine learning or data processing frameworks to leverage their capabilities within the swarm architecture. ---- +In conclusion, the `MixtureOfAgents` class represents a versatile and efficient solution for orchestrating multi-agent systems, facilitating complex task execution through its structured and layered approach. By harnessing the power of parallel and sequential processing, it opens up new possibilities for tackling intricate problems across various domains. -## Adding Your Swarm to a Project +## Additional Examples -### Step 1: Define Your Agents -Create one or more instances of the `Agent` class to serve as components of your swarm. For example: +### Example 4: Batch Processing ```python -def create_agents(): - return [ - Agent(agent_name="Agent1", system_prompt="Analyze the image and summarize results."), - Agent(agent_name="Agent2", system_prompt="Detect objects and highlight key features."), - ] -``` +from swarms import MixtureOfAgents, Agent +from swarm_models import OpenAIChat -### Step 2: Implement Your Swarm -Create an instance of your Swarm class, defining its name, description, and associated agents: +# Initialize agents as in previous examples +director = Agent( + agent_name="Director", + system_prompt="Directs the tasks for the accountants", + llm=OpenAIChat(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="director.json", +) -```python -my_swarm = MySwarm( - name="Image Analysis Swarm", - description="A swarm designed to analyze images and perform a range of related tasks.", - agents=create_agents() +accountant1 = Agent( + agent_name="Accountant1", + system_prompt="Prepares financial statements", + llm=OpenAIChat(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="accountant1.json", +) + +accountant2 = Agent( + agent_name="Accountant2", + system_prompt="Audits financial records", + llm=OpenAIChat(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="accountant2.json", +) + +# Initialize MixtureOfAgents +moe_swarm = MixtureOfAgents( + agents=[director, accountant1, accountant2], + final_agent=director ) + +# Process multiple tasks in batch +tasks = [ + "Analyze Q1 financial statements", + "Review tax compliance", + "Prepare budget forecast" +] +results = moe_swarm.run_batched(tasks) +for task, result in zip(tasks, results): + print(f"Task: {task}\nResult: {result}\n") ``` -### Step 3: Execute Tasks -Call the `run` method of your swarm, passing in the required parameters for execution: +### Example 5: Concurrent Processing ```python -results = my_swarm.run(task="Analyze image content", img="path/to/image.jpg") -print(results) -``` +from swarms import MixtureOfAgents, Agent +from swarm_models import OpenAIChat -This simple flow allows you to dynamically utilize agents for diverse operations and ensures efficient task execution. +# Initialize agents as before +# ... agent initialization code ... ---- +# Initialize MixtureOfAgents +moe_swarm = MixtureOfAgents( + agents=[director, accountant1, accountant2], + final_agent=director +) -## Best Practices +# Process multiple tasks concurrently +tasks = [ + "Generate monthly report", + "Audit expense claims", + "Update financial projections", + "Review investment portfolio" +] +results = moe_swarm.run_concurrently(tasks) +for task, result in zip(tasks, results): + print(f"Task: {task}\nResult: {result}\n") +``` -To ensure your swarm implementation is efficient and maintainable, follow these best practices: +## Advanced Features -1. **Type Annotations:** - Use precise type hints for parameters and return types to improve code readability and support static analysis tools. +### Context Preservation -2. **Comprehensive Documentation:** - Include clear and detailed docstrings for all classes, methods, and attributes to ensure your code is understandable. +The `MixtureOfAgents` class maintains context between iterations when running multiple loops. Each subsequent iteration receives the context from previous runs, allowing for more sophisticated and context-aware processing. -3. **Thorough Testing:** - Test your swarm and agents with various tasks to verify correctness and identify potential edge cases. +### Asynchronous Processing -4. **Modular Design:** - Keep your swarm and agent logic modular, enabling reuse and easy extensions for future enhancements. +The class implements asynchronous processing internally using Python's `asyncio`, enabling efficient handling of concurrent operations and improved performance for complex workflows. -5. **Error Handling:** - Implement robust error handling in the `run` methods to gracefully manage unexpected inputs or issues during execution. +### Telemetry and Logging -6. **Code Review:** - Regularly review and refactor your code to align with the latest best practices and maintain high quality. +Built-in telemetry and logging capabilities help track agent performance and maintain detailed execution records: +- Automatic logging of agent outputs +- Structured data capture using Pydantic models +- JSON-formatted output options -7. **Scalability:** - Design your swarm with scalability in mind, ensuring it can handle a large number of agents and complex tasks. +-------------------------------------------------- -8. **Logging and Monitoring:** - Include comprehensive logging to track task execution and monitor performance, enabling easier debugging and optimization. +# File: swarms\structs\model_router.md -9. **Open-Source Contributions:** - Consider contributing your swarm to the Swarms repository to benefit the community. Submit a pull request at [https://github.com/kyegomez/swarms](https://github.com/kyegomez/swarms). +# ModelRouter Docs ---- +The ModelRouter is an intelligent routing system that automatically selects and executes AI models based on task requirements. It leverages a function-calling architecture to analyze tasks and recommend the optimal model and provider combination for each specific use case. -## Example Output -Given the implementation above, executing a task might produce output such as: -```plaintext -[ - "Agent Agent1 executed task: Analyze image content", - "Agent Agent2 executed task: Analyze image content" -] -``` -The modular design ensures that each agent contributes to the overall functionality of the swarm, allowing seamless scalability and dynamic task management. ---- +### Key Features -## Conclusion +- Dynamic model selection based on task complexity and requirements +- Multi-provider support (OpenAI, Anthropic, Google, etc.) +- Concurrent and asynchronous execution capabilities +- Batch processing with memory +- Automatic error handling and retries +- Provider-aware routing +- Cost optimization -By following these guidelines, you can create swarms that are powerful, flexible, and maintainable. Leveraging the provided templates and best practices enables you to build efficient multi-agent systems capable of handling diverse and complex tasks. Proper structuring, thorough testing, and adherence to best practices will ensure your swarm integrates effectively into any project, delivering robust and reliable performance. Furthermore, maintaining clear documentation and emphasizing modularity will help your implementation adapt to future needs and use cases. Empower your projects with a well-designed swarm architecture today, and consider submitting your swarm to the open-source community to foster collaboration and innovation. +### Constructor Arguments +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| system_prompt | str | model_router_system_prompt | Custom prompt for guiding model selection behavior | +| max_tokens | int | 4000 | Maximum token limit for model outputs | +| temperature | float | 0.5 | Control parameter for response randomness (0.0-1.0) | +| max_workers | int/str | 10 | Maximum concurrent workers ("auto" for CPU count) | +| api_key | str | None | API key for model access | +| max_loops | int | 1 | Maximum number of refinement iterations | +| *args | Any | None | Additional positional arguments | +| **kwargs | Any | None | Additional keyword arguments | +### Core Methods --------------------------------------------------- +#### run(task: str) -> str -# File: swarms/structs/custom_swarm.md +Executes a single task through the model router with memory and refinement capabilities. -### Title: Building Custom Swarms with Multiple Agents: A Comprehensive Guide for Swarm Engineers +# Installation -#### Introductio -As artificial intelligence and machine learning continue to grow in complexity and applicability, building systems that can harness multiple agents to solve complex tasks becomes more critical. Swarm engineering enables AI agents to collaborate and solve problems autonomously in diverse fields such as finance, marketing, operations, and even creative industries. In this guide, we'll focus on how to build a custom swarm system that integrates multiple agents into a cohesive system capable of solving tasks collaboratively. +1. Install the latest version of swarms using pip: -The swarm we'll design will leverage Python, use types for better code structure, and feature logging with the powerful **loguru** logging library. We'll break down how to define and initialize swarms, make them scalable, and create methods like `run(task: str)` to trigger their execution. +```bash +pip3 install -U swarms +``` -By the end of this article, you will have a complete understanding of: +2. Setup your API Keys in your .env file with the following: -- What swarms are and how they can be built. +```bash +OPENAI_API_KEY=your_openai_api_key +ANTHROPIC_API_KEY=your_anthropic_api_key +GOOGLE_API_KEY=your_google_api_key +# Add more API keys as needed following litellm format +``` -- How to intake multiple agents using a flexible class. -- How to run tasks across agents and capture their outputs. +```python +from swarms import ModelRouter -- Best practices for error handling, logging, and optimization. +router = ModelRouter() ---- +# Simple text analysis +result = router.run("Analyze the sentiment and key themes in this customer feedback") -### 1. Understanding the Concept of a Swarm +# Complex reasoning task +complex_result = router.run(""" +Evaluate the following business proposal: +- Initial investment: $500,000 +- Projected ROI: 25% annually +- Market size: $2B +- Competition: 3 major players +Provide detailed analysis and recommendations. +""") +``` -A **swarm** refers to a collection of agents that collaborate to solve a problem. Each agent in the swarm performs part of the task, either independently or by communicating with other agents. Swarms are ideal for: +#### batch_run(tasks: list) -> list +Executes multiple tasks sequentially with result aggregation. -- **Scalability**: You can add or remove agents dynamically based on the task's complexity. +```python +# Multiple analysis tasks +tasks = [ + "Analyze Q1 financial performance", + "Predict Q2 market trends", + "Evaluate competitor strategies", + "Generate growth recommendations" +] -- **Flexibility**: Each agent can be designed to specialize in different parts of the problem, offering modularity. +results = router.batch_run(tasks) -- **Autonomy**: Agents in a swarm can operate autonomously, reducing the need for constant supervision. +# Process results +for task, result in zip(tasks, results): + print(f"Task: {task}\nResult: {result}\n") +``` -We'll be using Python as the primary programming language and will structure the swarm class using clean, reusable code principles. +#### concurrent_run(tasks: list) -> list +Parallel execution of multiple tasks using thread pooling. ---- +```python +import asyncio +from typing import List -### 2. Designing the Swarm Class: Intake Multiple Agents +# Define multiple concurrent tasks +analysis_tasks = [ + "Perform technical analysis of AAPL stock", + "Analyze market sentiment from social media", + "Generate trading signals", + "Calculate risk metrics" +] -We'll begin by creating a base class for our swarm. This class will intake multiple agents and define a `run` method, which is the core method for executing tasks across the swarm. Each agent is defined by its specific behavior or "intelligence" to complete part of the task. +# Execute tasks concurrently +results = router.concurrent_run(analysis_tasks) -#### 2.1 Importing the Required Libraries and Dependencies +# Process results with error handling +for task, result in zip(analysis_tasks, results): + try: + processed_result = process_analysis(result) + save_to_database(processed_result) + except Exception as e: + log_error(f"Error processing {task}: {str(e)}") +``` -We'll rely on the **loguru** logging library, Pydantic for metadata handling, and standard Python typing. +#### async_run(task: str) -> asyncio.Task +Asynchronous task execution with coroutine support. ```python -from typing import List, Union -from loguru import logger -from swarms.structs.base_swarm import BaseSwarm +async def process_data_stream(): + tasks = [] + async for data in data_stream: + task = await router.async_run(f"Process data: {data}") + tasks.append(task) + + results = await asyncio.gather(*tasks) + return results -class SwarmExecutionError(Exception): - """Custom exception for handling swarm execution errors.""" - pass +# Usage in async context +async def main(): + router = ModelRouter() + results = await process_data_stream() ``` -#### 2.2 Defining the Swarm Class +### Advanced Usage Examples -The class `CustomSwarm` will take in a list of agents. The agents will be instances of `BaseSwarm` (or callable functions). The `run(task: str)` method will delegate tasks to each agent in the swarm and handle any errors or retries. +#### Financial Analysis System ```python -class CustomSwarm: - def __init__(self, agents: List[BaseSwarm]): - """ - Initializes the CustomSwarm with a list of agents. +from swarms import ModelRouter +from typing import Dict, List +import pandas as pd - Args: - agents (List[BaseSwarm]): A list of agent objects that inherit from BaseSwarm. +class FinancialAnalysisSystem: + def __init__(self): + self.router = ModelRouter( + temperature=0.3, # Lower temperature for more deterministic outputs + max_tokens=8000, # Higher token limit for detailed analysis + max_loops=2 # Allow for refinement iteration + ) + + def analyze_company_financials(self, financial_data: Dict) -> Dict: + analysis_task = f""" + Perform comprehensive financial analysis: + + Financial Metrics: + - Revenue: ${financial_data['revenue']}M + - EBITDA: ${financial_data['ebitda']}M + - Debt/Equity: {financial_data['debt_equity']} + - Working Capital: ${financial_data['working_capital']}M + + Required Analysis: + 1. Profitability assessment + 2. Liquidity analysis + 3. Growth projections + 4. Risk evaluation + 5. Investment recommendations + + Provide detailed insights and actionable recommendations. """ - self.agents = agents - self.validate_agents() - - def validate_agents(self): - """Validates that each agent has a 'run' method.""" - for agent in self.agents: - if not hasattr(agent, 'run'): - raise AttributeError(f"Agent {agent} does not have a 'run' method.") - logger.info(f"Agent {agent} validated successfully.") + + result = self.router.run(analysis_task) + return self._parse_analysis_result(result) + + def _parse_analysis_result(self, result: str) -> Dict: + # Implementation of result parsing + pass - def run(self, task: str): - """ - Runs the task across all agents in the swarm. +# Usage +analyzer = FinancialAnalysisSystem() +company_data = { + 'revenue': 150, + 'ebitda': 45, + 'debt_equity': 0.8, + 'working_capital': 25 +} - Args: - task (str): The task to pass to each agent. - """ - logger.info(f"Running task '{task}' across all agents in the swarm.") - for agent in self.agents: - try: - agent.run(task) - logger.info(f"Agent {agent} successfully completed the task.") - except Exception as e: - logger.error(f"Agent {agent} failed to run task: {e}") - raise SwarmExecutionError(f"Execution failed for {agent}. Task: {task}") +analysis = analyzer.analyze_company_financials(company_data) ``` -### 3. Adding Logging and Error Handling with `loguru` - -Logging is crucial for production-grade systems, especially when managing complex tasks that involve multiple agents. **Loguru** is a simple and efficient logging library that allows us to log everything from information messages to errors. +#### Healthcare Data Processing Pipeline ```python -from loguru import logger +from swarms import ModelRouter +import pandas as pd +from typing import List, Dict -class CustomSwarm: - def __init__(self, agents: List[BaseSwarm]): - self.agents = agents - logger.info("CustomSwarm initialized with agents.") - self.validate_agents() +class MedicalDataProcessor: + def __init__(self): + self.router = ModelRouter( + max_workers="auto", # Automatic worker scaling + temperature=0.2, # Conservative temperature for medical analysis + system_prompt="""You are a specialized medical data analyzer focused on: + 1. Clinical terminology interpretation + 2. Patient data analysis + 3. Treatment recommendation review + 4. Medical research synthesis""" + ) + + async def process_patient_records(self, records: List[Dict]) -> List[Dict]: + analysis_tasks = [] + + for record in records: + task = f""" + Analyze patient record: + - Age: {record['age']} + - Symptoms: {', '.join(record['symptoms'])} + - Vital Signs: {record['vitals']} + - Medications: {', '.join(record['medications'])} + - Lab Results: {record['lab_results']} + + Provide: + 1. Symptom analysis + 2. Medication interaction check + 3. Lab results interpretation + 4. Treatment recommendations + """ + analysis_tasks.append(task) + + results = await asyncio.gather(*[ + self.router.async_run(task) for task in analysis_tasks + ]) + + return [self._parse_medical_analysis(r) for r in results] + + def _parse_medical_analysis(self, analysis: str) -> Dict: + # Implementation of medical analysis parsing + pass - def run(self, task: str): - logger.info(f"Task received: {task}") - for agent in self.agents: - try: - agent.run(task) - logger.success(f"Agent {agent} completed task successfully.") - except Exception as e: - logger.error(f"Error while running task '{task}' for {agent}: {e}") - raise SwarmExecutionError(f"Execution failed for {agent}") +# Usage +async def main(): + processor = MedicalDataProcessor() + patient_records = [ + { + 'age': 45, + 'symptoms': ['fever', 'cough', 'fatigue'], + 'vitals': {'bp': '120/80', 'temp': '38.5C'}, + 'medications': ['lisinopril', 'metformin'], + 'lab_results': 'WBC: 11,000, CRP: 2.5' + } + # More records... + ] + + analyses = await processor.process_patient_records(patient_records) ``` -### 4. Running Tasks Across Multiple Agents - -The `run(task: str)` method will handle distributing the task to each agent in the swarm. Each agent’s `run` method is expected to take a task as input and perform its specific logic. We can add further customization by allowing each agent to return output, which can be collected for later analysis. - -#### 4.1 Example of Integrating Agents - -Let's take a look at how we can define agents using the `BaseSwarm` class and integrate them into the swarm. +#### Natural Language Processing Pipeline ```python -class FinancialAgent(BaseSwarm): - def run(self, task: str): - logger.info(f"FinancialAgent processing task: {task}") - # Custom logic for financial analysis - return f"FinancialAgent response to task: {task}" +from swarms import ModelRouter +from typing import List, Dict +import asyncio -class MarketingAgent(BaseSwarm): - def run(self, task: str): - logger.info(f"MarketingAgent processing task: {task}") - # Custom logic for marketing analysis - return f"MarketingAgent response to task: {task}" -``` +class NLPPipeline: + def __init__(self): + self.router = ModelRouter( + temperature=0.4, + max_loops=2 + ) + + def process_documents(self, documents: List[str]) -> List[Dict]: + tasks = [self._create_nlp_task(doc) for doc in documents] + results = self.router.concurrent_run(tasks) + return [self._parse_nlp_result(r) for r in results] + + def _create_nlp_task(self, document: str) -> str: + return f""" + Perform comprehensive NLP analysis: + + Text: {document} + + Required Analysis: + 1. Entity recognition + 2. Sentiment analysis + 3. Topic classification + 4. Key phrase extraction + 5. Intent detection + + Provide structured analysis with confidence scores. + """ + + def _parse_nlp_result(self, result: str) -> Dict: + # Implementation of NLP result parsing + pass -Now, we initialize the swarm with these agents: +# Usage +pipeline = NLPPipeline() +documents = [ + "We're extremely satisfied with the new product features!", + "The customer service response time needs improvement.", + "Looking to upgrade our subscription plan next month." +] -```python -if __name__ == "__main__": - agents = [FinancialAgent(), MarketingAgent()] - swarm = CustomSwarm(agents) - swarm.run("Analyze Q3 financial report and marketing impact.") +analyses = pipeline.process_documents(documents) ``` -### 5. Enhancing the Swarm with Concurrent Execution - -When dealing with large or time-consuming tasks, running agents concurrently (in parallel) can significantly improve performance. We can achieve this by utilizing Python’s **concurrent.futures** or **threading** libraries. - -#### 5.1 Running Swarms Concurrently - -```python -from concurrent.futures import ThreadPoolExecutor, as_completed +### Available Models and Use Cases -class CustomSwarm: - def __init__(self, agents: List[BaseSwarm], max_workers: int = 4): - self.agents = agents - self.thread_pool = ThreadPoolExecutor(max_workers=max_workers) - logger.info("CustomSwarm initialized with concurrent execution.") +| Model | Provider | Optimal Use Cases | Characteristics | +|-------|----------|-------------------|-----------------| +| gpt-4-turbo | OpenAI | Complex reasoning, Code generation, Creative writing | High accuracy, Latest knowledge cutoff | +| claude-3-opus | Anthropic | Research analysis, Technical documentation, Long-form content | Strong reasoning, Detailed outputs | +| gemini-pro | Google | Multimodal tasks, Code generation, Technical analysis | Fast inference, Strong coding abilities | +| mistral-large | Mistral | General tasks, Content generation, Classification | Open source, Good price/performance | +| deepseek-reasoner | DeepSeek | Mathematical analysis, Logic problems, Scientific computing | Specialized reasoning capabilities | - def run(self, task: str): - futures = [] - for agent in self.agents: - futures.append(self.thread_pool.submit(agent.run, task)) - - for future in as_completed(futures): - result = future.result() - logger.info(f"Agent result: {result}") -``` +### Provider Capabilities -### 6. Advanced Error Handling and Retries +| Provider | Strengths | Best For | Integration Notes | +|----------|-----------|-----------|------------------| +| OpenAI | Consistent performance, Strong reasoning | Production systems, Complex tasks | Requires API key setup | +| Anthropic | Safety features, Detailed analysis | Research, Technical writing | Claude-specific formatting | +| Google | Technical tasks, Multimodal support | Code generation, Analysis | Vertex AI integration available | +| Groq | High-speed inference | Real-time applications | Optimized for specific models | +| DeepSeek | Specialized reasoning | Scientific computing | Custom API integration | +| Mistral | Open source flexibility | General applications | Self-hosted options available | -In a production system, agents might fail due to a wide range of reasons (network errors, API rate limits, etc.). To ensure resilience, we can add retry mechanisms and even fallback agents that attempt to recover the failed task. -```python -class CustomSwarm: - def run_with_retries(self, task: str, retries: int = 3): - """ - Runs the task across all agents with retry logic. - - Args: - task (str): The task to run. - retries (int): Number of retries allowed for failed agents. - """ - for agent in self.agents: - attempt = 0 - while attempt <= retries: - try: - agent.run(task) - logger.success(f"Agent {agent} completed task.") - break - except Exception as e: - logger.error(f"Agent {agent} failed on attempt {attempt + 1}. Error: {e}") - attempt += 1 - if attempt > retries: - logger.error(f"Agent {agent} exhausted retries. Task failed.") -``` +### Performance Optimization Tips -### 7. Adding Documentation with Docstrings +1. Token Management + - Set appropriate max_tokens based on task complexity + - Monitor token usage for cost optimization + - Use streaming for long outputs -Clear and concise documentation is critical, especially for engineers maintaining and scaling the system. Using Python’s docstrings, we can document each class and method, describing what they do and their expected inputs/outputs. +2. Concurrency Settings + - Adjust max_workers based on system resources + - Use "auto" workers for optimal CPU utilization + - Monitor memory usage with large batch sizes -```python -class CustomSwarm: - """ - A class to manage and execute tasks using a swarm of agents. +3. Temperature Tuning + - Lower (0.1-0.3) for factual/analytical tasks + - Higher (0.7-0.9) for creative tasks + - Mid-range (0.4-0.6) for balanced outputs - Attributes: - agents (List[BaseSwarm]): A list of agent instances. - - Methods: - run(task: str): Runs a task across all agents in the swarm. - validate_agents(): Validates that each agent has a run method. - run_with_retries(task: str, retries: int): Runs the task with retry logic. - """ +4. System Prompts + - Customize for specific domains + - Include relevant context + - Define clear output formats - def __init__(self, agents: List[BaseSwarm]): - """ - Initializes the CustomSwarm with a list of agents. +### Dependencies - Args: - agents (List[BaseSwarm]): A list of agent objects that inherit from BaseSwarm. - """ - self.agents = agents +- asyncio: Asynchronous I/O support +- concurrent.futures: Thread pool execution +- pydantic: Data validation +- litellm: LLM interface standardization - def run(self, task: str): - """ - Runs the task across all agents in the swarm. - Args: - task (str): The task to pass to each agent. - """ - pass +-------------------------------------------------- - def validate_agents(self): - """Validates that each agent has a 'run' method.""" - pass -``` +# File: swarms\structs\multi_agent_collaboration_examples.md -` +# Multi-Agent Examples -### Conclusion -Building custom swarms that intake multiple agents can drastically improve the scalability, efficiency, and flexibility of AI-driven systems. By designing a robust swarm class that manages agents, distributes tasks, and ensures error resilience, you can handle complex, multi-agent workloads efficiently. +### `SequentialWorkflow` +Sequential Workflow enables you to sequentially execute tasks with `Agent` and then pass the output into the next agent and onwards until you have specified your max loops. -In this Guide, we've covered: +```python +from swarms import Agent, SequentialWorkflow -- Designing a basic swarm class. +from swarm_models import Anthropic -- Running tasks across multiple agents. -- Leveraging logging, error handling, retries, and concurrency. +# Initialize the language model agent (e.g., GPT-3) +llm = Anthropic() -- Documenting your class for future-proofing. +# Initialize agents for individual tasks +agent1 = Agent( + agent_name="Blog generator", + system_prompt="Generate a blog post like stephen king", + llm=llm, + max_loops=1, + dashboard=False, + tools=[], +) +agent2 = Agent( + agent_name="summarizer", + system_prompt="Sumamrize the blog post", + llm=llm, + max_loops=1, + dashboard=False, + tools=[], +) -This approach sets the foundation for building more advanced and domain-specific swarms in areas like finance, marketing, operations, and beyond. Swarm engineers can now explore more complex, multi-agent systems and push the boundaries of AI collaboration. +# Create the Sequential workflow +workflow = SequentialWorkflow( + agents=[agent1, agent2], max_loops=1, verbose=False +) -Stay tuned for future updates on more advanced swarm functionalities! +# Run the workflow +workflow.run( + "Generate a blog post on how swarms of agents can help businesses grow." +) --------------------------------------------------- +``` -# File: swarms/structs/deep_research_swarm.md +------ -# Deep Research Swarm +## `AgentRearrange` +Inspired by Einops and einsum, this orchestration techniques enables you to map out the relationships between various agents. For example you specify linear and sequential relationships like `a -> a1 -> a2 -> a3` or concurrent relationships where the first agent will send a message to 3 agents all at once: `a -> a1, a2, a3`. You can customize your workflow to mix sequential and concurrent relationships. [Docs Available:](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/) -!!! abstract "Overview" - The Deep Research Swarm is a powerful, production-grade research system that conducts comprehensive analysis across multiple domains using parallel processing and advanced AI agents. +```python +from swarms import Agent, AgentRearrange - Key Features: - - - Parallel search processing - - - Multi-agent research coordination - - - Advanced information synthesis - - - Automated query generation - - - Concurrent task execution -## Getting Started +from swarm_models import Anthropic -!!! tip "Quick Installation" - ```bash - pip install swarms - ``` +# Initialize the director agent -=== "Basic Usage" - ```python - from swarms.structs import DeepResearchSwarm +director = Agent( + agent_name="Director", + system_prompt="Directs the tasks for the workers", + llm=Anthropic(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="director.json", +) - # Initialize the swarm - swarm = DeepResearchSwarm( - name="MyResearchSwarm", - output_type="json", - max_loops=1 - ) - # Run a single research task - results = swarm.run("What are the latest developments in quantum computing?") - ``` +# Initialize worker 1 -=== "Batch Processing" - ```python - # Run multiple research tasks in parallel - tasks = [ - "What are the environmental impacts of electric vehicles?", - "How is AI being used in drug discovery?", - ] - batch_results = swarm.batched_run(tasks) - ``` +worker1 = Agent( + agent_name="Worker1", + system_prompt="Generates a transcript for a youtube video on what swarms are", + llm=Anthropic(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="worker1.json", +) -## Configuration -!!! info "Constructor Arguments" - | Parameter | Type | Default | Description | - |-----------|------|---------|-------------| - | `name` | str | "DeepResearchSwarm" | Name identifier for the swarm | - | `description` | str | "A swarm that conducts..." | Description of the swarm's purpose | - | `research_agent` | Agent | research_agent | Custom research agent instance | - | `max_loops` | int | 1 | Maximum number of research iterations | - | `nice_print` | bool | True | Enable formatted console output | - | `output_type` | str | "json" | Output format ("json" or "string") | - | `max_workers` | int | CPU_COUNT * 2 | Maximum concurrent threads | - | `token_count` | bool | False | Enable token counting | - | `research_model_name` | str | "gpt-4o-mini" | Model to use for research | +# Initialize worker 2 +worker2 = Agent( + agent_name="Worker2", + system_prompt="Summarizes the transcript generated by Worker1", + llm=Anthropic(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="worker2.json", +) -## Core Methods -### Run -!!! example "Single Task Execution" - ```python - results = swarm.run("What are the latest breakthroughs in fusion energy?") - ``` +# Create a list of agents +agents = [director, worker1, worker2] -### Batched Run -!!! example "Parallel Task Execution" - ```python - tasks = [ - "What are current AI safety initiatives?", - "How is CRISPR being used in agriculture?", - ] - results = swarm.batched_run(tasks) - ``` +# Define the flow pattern +flow = "Director -> Worker1 -> Worker2" -### Step -!!! example "Single Step Execution" - ```python - results = swarm.step("Analyze recent developments in renewable energy storage") - ``` +# Using AgentRearrange class +agent_system = AgentRearrange(agents=agents, flow=flow) +output = agent_system.run( + "Create a format to express and communicate swarms of llms in a structured manner for youtube" +) +print(output) -## Domain-Specific Examples +``` -=== "Scientific Research" - ```python - science_swarm = DeepResearchSwarm( - name="ScienceSwarm", - output_type="json", - max_loops=2 # More iterations for thorough research - ) +## `HierarhicalSwarm` +Coming soon... - results = science_swarm.run( - "What are the latest experimental results in quantum entanglement?" - ) - ``` -=== "Market Research" - ```python - market_swarm = DeepResearchSwarm( - name="MarketSwarm", - output_type="json" - ) +## `GraphSwarm` - results = market_swarm.run( - "What are the emerging trends in electric vehicle battery technology market?" - ) - ``` +```python +from swarms.structs.agent import Agent +from swarms import Edge, GraphWorkflow, Node, NodeType -=== "News Analysis" - ```python - news_swarm = DeepResearchSwarm( - name="NewsSwarm", - output_type="string" # Human-readable output - ) - results = news_swarm.run( - "What are the global economic impacts of recent geopolitical events?" - ) - ``` +# Initialize two agents with GPT-4o-mini +agent1 = Agent( + agent_name="agent1", + system_prompt="You are an autonomous agent executing workflow tasks.", + max_loops=1, + autosave=True, + dashboard=False, + verbose=True, + saved_state_path="agent1_state.json", + model_name="gpt-4o-mini", +) -=== "Medical Research" - ```python - medical_swarm = DeepResearchSwarm( - name="MedicalSwarm", - max_loops=2 - ) +agent2 = Agent( + agent_name="agent2", + system_prompt="You are an autonomous agent executing workflow tasks.", + max_loops=1, + autosave=True, + dashboard=False, + verbose=True, + saved_state_path="agent2_state.json", + model_name="gpt-4o-mini", +) - results = medical_swarm.run( - "What are the latest clinical trials for Alzheimer's treatment?" - ) - ``` +def sample_task(): + print("Running sample task") + return "Task completed" -## Advanced Features +# Build the DAG +wf = GraphWorkflow() +wf.add_node(Node(id="agent1", type=NodeType.AGENT, agent=agent1)) +wf.add_node(Node(id="agent2", type=NodeType.AGENT, agent=agent2)) +wf.add_node(Node(id="task1", type=NodeType.TASK, callable=sample_task)) -??? note "Custom Research Agent" - ```python - from swarms import Agent +# Connect agents to the task +wf.add_edge(Edge(source="agent1", target="task1")) +wf.add_edge(Edge(source="agent2", target="task1")) - custom_agent = Agent( - agent_name="SpecializedResearcher", - system_prompt="Your specialized prompt here", - model_name="gpt-4" - ) +wf.set_entry_points(["agent1", "agent2"]) +wf.set_end_points(["task1"]) - swarm = DeepResearchSwarm( - research_agent=custom_agent, - max_loops=2 - ) - ``` +# Visualize and run +print(wf.visualize()) +results = wf.run() +print("Execution results:", results) -??? note "Parallel Processing Control" - ```python - swarm = DeepResearchSwarm( - max_workers=8, # Limit to 8 concurrent threads - nice_print=False # Disable console output for production - ) - ``` +``` -## Best Practices +## `MixtureOfAgents` +This is an implementation from the paper: "Mixture-of-Agents Enhances Large Language Model Capabilities" by together.ai, it achieves SOTA on AlpacaEval 2.0, MT-Bench and FLASK, surpassing GPT-4 Omni. Great for tasks that need to be parallelized and then sequentially fed into another loop -!!! success "Recommended Practices" - 1. **Query Formulation**: Be specific and clear in your research queries - 2. **Resource Management**: Adjust `max_workers` based on your system's capabilities - 3. **Output Handling**: Use appropriate `output_type` for your use case - 4. **Error Handling**: Implement try-catch blocks around swarm operations - 5. **Model Selection**: Choose appropriate models based on research complexity +```python +from swarms import Agent, OpenAIChat, MixtureOfAgents -## Limitations +# Initialize the director agent +director = Agent( + agent_name="Director", + system_prompt="Directs the tasks for the accountants", + llm=OpenAIChat(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="director.json", +) -!!! warning "Known Limitations" - - - Requires valid API keys for external services - - - Performance depends on system resources - - - Rate limits may apply to external API calls - - - Token limits apply to model responses +# Initialize accountant 1 +accountant1 = Agent( + agent_name="Accountant1", + system_prompt="Prepares financial statements", + llm=OpenAIChat(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="accountant1.json", +) +# Initialize accountant 2 +accountant2 = Agent( + agent_name="Accountant2", + system_prompt="Audits financial records", + llm=OpenAIChat(), + max_loops=1, + dashboard=False, + streaming_on=True, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="accountant2.json", +) +# Create a list of agents +agents = [director, accountant1, accountant2] --------------------------------------------------- -# File: swarms/structs/diy_your_own_agent.md +# Swarm +swarm = MixtureOfAgents( + name="Mixture of Accountants", + agents=agents, + layers=3, + final_agent=director, +) -# Create your own agent with `Agent` class -The Agent class is a powerful and flexible tool that empowers AI agents to build their own custom agents, tailored to their specific needs. +# Run the swarm +out = swarm.run("Prepare financial statements and audit financial records") +print(out) +``` -This comprehensive guide will explore the process of inheriting from the Agent class, enabling agents to create their own custom agent classes. By leveraging the rich features and extensibility of the Agent class, agents can imbue their offspring agents with unique capabilities, specialized toolsets, and tailored decision-making processes. -## Understanding the Agent Class +-------------------------------------------------- -Before we dive into the intricacies of creating custom agent classes, let's revisit the foundational elements of the Agent class itself. The Agent class is a versatile and feature-rich class designed to streamline the process of building and managing AI agents. It acts as a backbone, connecting language models (LLMs) with various tools, long-term memory, and a wide range of customization options. +# File: swarms\structs\multi_agent_orchestration.md -### Key Features of the Agent Class +# Multi-Agent Orchestration: +Swarms was designed to faciliate the communication between many different and specialized agents from a vast array of other frameworks such as langchain, autogen, crew, and more. -The Agent class offers a plethora of features that can be inherited and extended by custom agent classes. Here are some of the key features that make the Agent class a powerful foundation: +In traditional swarm theory, there are many types of swarms usually for very specialized use-cases and problem sets. Such as Hiearchical and sequential are great for accounting and sales, because there is usually a boss coordinator agent that distributes a workload to other specialized agents. -1\. **Language Model Integration**: The Agent class supports seamless integration with popular language models such as LangChain, HuggingFace Transformers, and Autogen, allowing custom agent classes to leverage the power of state-of-the-art language models. -2\. **Tool Integration**: One of the standout features of the Agent class is its ability to integrate with various tools. Custom agent classes can inherit this capability and incorporate specialized tools tailored to their specific use cases. +| **Name** | **Description** | **Code Link** | **Use Cases** | +|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|---------------------------------------------------------------------------------------------------| +| Hierarchical Swarms | A system where agents are organized in a hierarchy, with higher-level agents coordinating lower-level agents to achieve complex tasks. | [Code Link](#) | Manufacturing process optimization, multi-level sales management, healthcare resource coordination | +| Agent Rearrange | A setup where agents rearrange themselves dynamically based on the task requirements and environmental conditions. | [Code Link](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/) | Adaptive manufacturing lines, dynamic sales territory realignment, flexible healthcare staffing | +| Concurrent Workflows | Agents perform different tasks simultaneously, coordinating to complete a larger goal. | [Code Link](#) | Concurrent production lines, parallel sales operations, simultaneous patient care processes | +| Sequential Coordination | Agents perform tasks in a specific sequence, where the completion of one task triggers the start of the next. | [Code Link](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/) | Step-by-step assembly lines, sequential sales processes, stepwise patient treatment workflows | +| Parallel Processing | Agents work on different parts of a task simultaneously to speed up the overall process. | [Code Link](#) | Parallel data processing in manufacturing, simultaneous sales analytics, concurrent medical tests | -3\. **Long-Term Memory**: The Agent class provides built-in support for long-term memory, enabling custom agent classes to retain and access information from previous interactions, essential for maintaining context and learning from past experiences. -4\. **Customizable Prompts and Standard Operating Procedures (SOPs)**: The Agent class allows you to define custom prompts and Standard Operating Procedures (SOPs) that guide an agent's behavior and decision-making process. Custom agent classes can inherit and extend these prompts and SOPs to align with their unique objectives and requirements. -5\. **Interactive and Dashboard Modes**: The Agent class supports interactive and dashboard modes, enabling real-time monitoring and interaction with agents. Custom agent classes can inherit these modes, facilitating efficient development, debugging, and user interaction. -6\. **Autosave and State Management**: With the Agent class, agents can easily save and load their state, including configuration, memory, and history. Custom agent classes can inherit this capability, ensuring seamless task continuation and enabling efficient collaboration among team members. +-------------------------------------------------- -7\. **Response Filtering**: The Agent class provides built-in response filtering capabilities, allowing agents to filter out or replace specific words or phrases in their responses. Custom agent classes can inherit and extend this feature to ensure compliance with content moderation policies or specific guidelines. +# File: swarms\structs\multi_agent_router.md -8\. **Code Execution and Multimodal Support**: The Agent class supports code execution and multimodal input/output, enabling agents to process and generate code, as well as handle various data formats such as images, audio, and video. Custom agent classes can inherit and specialize these capabilities for their unique use cases. +# MultiAgentRouter Documentation -9\. **Extensibility and Customization**: The Agent class is designed to be highly extensible and customizable, allowing agents to tailor its behavior, add custom functionality, and integrate with external libraries and APIs. Custom agent classes can leverage this extensibility to introduce specialized features and capabilities. +The MultiAgentRouter is a sophisticated task routing system that efficiently delegates tasks to specialized AI agents. It uses a "boss" agent to analyze incoming tasks and route them to the most appropriate specialized agent based on their capabilities and expertise. -### Creating a Custom Agent Class +## Table of Contents +- [Installation](#installation) +- [Key Components](#key-components) +- [Arguments](#arguments) +- [Methods](#methods) +- [Usage Examples](#usage-examples) + - [Healthcare](#healthcare-example) + - [Finance](#finance-example) + - [Legal](#legal-example) + - [Research](#research-example) -Now that we have a solid understanding of the Agent class and its features, let's dive into the process of creating a custom agent class by inheriting from the Agent class. Throughout this process, we'll explore how agents can leverage and extend the existing functionality, while introducing specialized features and capabilities tailored to their unique requirements. +## Installation -#### Step 1: Inherit from the Agent Class +```bash +pip install swarms +``` -The first step in creating a custom agent class is to inherit from the Agent class. This will provide your custom agent class with the foundational features and capabilities of the Agent class, which can then be extended and customized as needed. The new agent class must have a `run(task: str)` method to run the entire agent. It is encouraged to have `step(task: str)` method that completes one step of the agent and then build the `run(task: str)` method. +## Key Components -```python +### Arguments Table -from swarms import Agent +| Argument | Type | Default | Description | +|----------|------|---------|-------------| +| name | str | "swarm-router" | Name identifier for the router instance | +| description | str | "Routes tasks..." | Description of the router's purpose | +| agents | List[Agent] | [] | List of available specialized agents | +| model | str | "gpt-4o-mini" | Base language model for the boss agent | +| temperature | float | 0.1 | Temperature parameter for model outputs | +| shared_memory_system | callable | None | Optional shared memory system | +| output_type | Literal["json", "string"] | "json" | Format of agent outputs | +| execute_task | bool | True | Whether to execute routed tasks | -class MyCustomAgent(Agent): +### Methods Table -    def __init__(self, *args, **kwargs): +| Method | Arguments | Returns | Description | +|--------|-----------|---------|-------------| +| route_task | task: str | dict | Routes a single task to appropriate agent | +| batch_run | tasks: List[str] | List[dict] | Sequentially routes multiple tasks | +| concurrent_batch_run | tasks: List[str] | List[dict] | Concurrently routes multiple tasks | +| query_ragent | task: str | str | Queries the research agent | +| find_agent_in_list | agent_name: str | Optional[Agent] | Finds agent by name | -        super().__init__(*args, **kwargs) +## Production Examples -        # Add custom initialization logic here +### Healthcare Example - def run(self, task: str) -> - ... +```python +from swarms import Agent, MultiAgentRouter -``` +# Define specialized healthcare agents +agents = [ + Agent( + agent_name="DiagnosisAgent", + description="Specializes in preliminary symptom analysis and diagnostic suggestions", + system_prompt="""You are a medical diagnostic assistant. Analyze symptoms and provide + evidence-based diagnostic suggestions, always noting this is for informational purposes + only and recommending professional medical consultation.""", + model_name="openai/gpt-4o" + ), + Agent( + agent_name="TreatmentPlanningAgent", + description="Assists in creating treatment plans and medical documentation", + system_prompt="""You are a treatment planning assistant. Help create structured + treatment plans based on confirmed diagnoses, following medical best practices + and guidelines.""", + model_name="openai/gpt-4o" + ), + Agent( + agent_name="MedicalResearchAgent", + description="Analyzes medical research papers and clinical studies", + system_prompt="""You are a medical research analyst. Analyze and summarize medical + research papers, clinical trials, and scientific studies, providing evidence-based + insights.""", + model_name="openai/gpt-4o" + ) +] -In the example above, we define a new class `MyCustomAgent` that inherits from the `Agent` class. Within the `__init__` method, we call the parent class's `__init__` method using `super().__init__(*args, **kwargs)`, which ensures that the parent class's initialization logic is executed. You can then add any custom initialization logic specific to your custom agent class. +# Initialize router +healthcare_router = MultiAgentRouter( + name="Healthcare-Router", + description="Routes medical and healthcare-related tasks to specialized agents", + agents=agents, + model="gpt-4o", + temperature=0.1 +) -#### Step 2: Customize the Agent's Behavior +# Example usage +try: + # Process medical case + case_analysis = healthcare_router.route_task( + """Patient presents with: + - Persistent dry cough for 3 weeks + - Mild fever (38.1°C) + - Fatigue + Analyze symptoms and suggest potential diagnoses for healthcare provider review.""" + ) + + # Research treatment options + treatment_research = healthcare_router.route_task( + """Find recent clinical studies on treatment efficacy for community-acquired + pneumonia in adult patients, focusing on outpatient care.""" + ) + + # Process multiple cases concurrently + cases = [ + "Case 1: Patient symptoms...", + "Case 2: Patient symptoms...", + "Case 3: Patient symptoms..." + ] + concurrent_results = healthcare_router.concurrent_batch_run(cases) + +except Exception as e: + logger.error(f"Error in healthcare processing: {str(e)}") +``` -One of the key advantages of inheriting from the Agent class is the ability to customize the agent's behavior according to your specific requirements. This can be achieved by overriding or extending the existing methods, or by introducing new methods altogether. +### Finance Example ```python -from swarms import Agent +# Define specialized finance agents +finance_agents = [ + Agent( + agent_name="MarketAnalysisAgent", + description="Analyzes market trends and provides trading insights", + system_prompt="""You are a financial market analyst. Analyze market data, trends, + and indicators to provide evidence-based market insights and trading suggestions.""", + model_name="openai/gpt-4o" + ), + Agent( + agent_name="RiskAssessmentAgent", + description="Evaluates financial risks and compliance requirements", + system_prompt="""You are a risk assessment specialist. Analyze financial data + and operations for potential risks, ensuring regulatory compliance and suggesting + risk mitigation strategies.""", + model_name="openai/gpt-4o" + ), + Agent( + agent_name="InvestmentAgent", + description="Provides investment strategies and portfolio management", + system_prompt="""You are an investment strategy specialist. Develop and analyze + investment strategies, portfolio allocations, and provide long-term financial + planning guidance.""", + model_name="openai/gpt-4o" + ) +] +# Initialize finance router +finance_router = MultiAgentRouter( + name="Finance-Router", + description="Routes financial analysis and investment tasks", + agents=finance_agents +) -class MyCustomAgent(Agent): +# Example tasks +tasks = [ + """Analyze current market conditions for technology sector, focusing on: + - AI/ML companies + - Semiconductor manufacturers + - Cloud service providers + Provide risk assessment and investment opportunities.""", + + """Develop a diversified portfolio strategy for a conservative investor with: + - Investment horizon: 10 years + - Risk tolerance: Low to medium + - Initial investment: $500,000 + - Monthly contribution: $5,000""", + + """Conduct risk assessment for a fintech startup's crypto trading platform: + - Regulatory compliance requirements + - Security measures + - Operational risks + - Market risks""" +] -    def __init__(self, *args, **kwargs): +# Process tasks concurrently +results = finance_router.concurrent_batch_run(tasks) +``` -        super().__init__(*args, **kwargs) +### Legal Example -        # Custom initialization logic +```python +# Define specialized legal agents +legal_agents = [ + Agent( + agent_name="ContractAnalysisAgent", + description="Analyzes legal contracts and documents", + system_prompt="""You are a legal document analyst. Review contracts and legal + documents for key terms, potential issues, and compliance requirements.""", + model_name="openai/gpt-4o" + ), + Agent( + agent_name="ComplianceAgent", + description="Ensures regulatory compliance and updates", + system_prompt="""You are a legal compliance specialist. Monitor and analyze + regulatory requirements, ensuring compliance and suggesting necessary updates + to policies and procedures.""", + model_name="openai/gpt-4o" + ), + Agent( + agent_name="LegalResearchAgent", + description="Conducts legal research and case analysis", + system_prompt="""You are a legal researcher. Research relevant cases, statutes, + and regulations, providing comprehensive legal analysis and citations.""", + model_name="openai/gpt-4o" + ) +] -    def custom_method(self, *args, **kwargs): +# Initialize legal router +legal_router = MultiAgentRouter( + name="Legal-Router", + description="Routes legal analysis and compliance tasks", + agents=legal_agents +) -        # Implement custom logic here +# Example usage for legal department +contract_analysis = legal_router.route_task( + """Review the following software licensing agreement: + [contract text] + + Analyze for: + 1. Key terms and conditions + 2. Potential risks and liabilities + 3. Compliance with current regulations + 4. Suggested modifications""" +) +``` -        pass +## Error Handling and Best Practices -    def run(self, task, *args, **kwargs): +1. Always use try-except blocks for task routing: +```python +try: + result = router.route_task(task) +except Exception as e: + logger.error(f"Task routing failed: {str(e)}") +``` -        # Customize the run method +2. Monitor agent performance: +```python +if result["execution"]["execution_time"] > 5.0: + logger.warning(f"Long execution time for task: {result['task']['original']}") +``` -        response = super().run(task, *args, **kwargs) +3. Implement rate limiting for concurrent tasks: +```python +from concurrent.futures import ThreadPoolExecutor +with ThreadPoolExecutor(max_workers=5) as executor: + results = router.concurrent_batch_run(tasks) +``` -        # Additional custom logic +4. Regular agent validation: +```python +for agent in router.agents.values(): + if not agent.validate(): + logger.error(f"Agent validation failed: {agent.name}") +``` -        return response +## Performance Considerations -``` +1. Task Batching -In the example above, we introduce a new `custom_method` that can encapsulate any specialized logic or functionality specific to your custom agent class. Additionally, we override the `run` method, which is responsible for executing the agent's main task loop. Within the overridden `run` method, you can call the parent class's `run` method using `super().run(task, *args, **kwargs)` and then introduce any additional custom logic before or after the parent method's execution. +- Group similar tasks together -#### Step 3: Extend Memory Management +- Use concurrent_batch_run for independent tasks -The Agent class provides built-in support for long-term memory, allowing agents to retain and access information from previous interactions. Custom agent classes can inherit and extend this capability by introducing specialized memory management techniques. +- Monitor memory usage with large batches -```python +2. Model Selection -from swarms_memory import BaseVectorDatabase -from swarms import Agent +- Choose appropriate models based on task complexity +- Balance speed vs. accuracy requirements -class CustomMemory(BaseVectorDatabase): +- Consider cost implications -    def __init__(self, *args, **kwargs): +3. Response Caching -        super().__init__(*args, **kwargs) +- Implement caching for frequently requested analyses -        # Custom memory initialization logic +- Use shared memory system for repeated queries -    def query(self, *args, **kwargs): +- Regular cache invalidation for time-sensitive data -        # Custom memory query logic +## Security Considerations -        return result +1. Data Privacy -class MyCustomAgent(Agent): +- Implement data encryption -    def __init__(self, *args, **kwargs): +- Handle sensitive information appropriately -        super().__init__(*args, **kwargs) +- Regular security audits -        # Custom initialization logic +2. Access Control -        self.long_term_memory = CustomMemory() +- Implement role-based access -    def run(self, task, *args, **kwargs): +- Audit logging -        # Customize the run method +- Regular permission reviews -        response = super().run(task, *args, **kwargs) +## Monitoring and Logging -        # Utilize custom memory +1. Performance Metrics -        memory_result = self.long_term_memory.query(*args, **kwargs) +- Response times -        # Process memory result +- Success rates -        return response +- Error rates -``` +- Resource utilization -In the example above, we define a new `CustomMemory` class that inherits from the `BaseVectorDatabase` class provided by the Agent class framework. Within the `CustomMemory` class, you can implement specialized memory management logic, such as custom indexing, retrieval, and storage mechanisms. +2. Logging -Next, within the `MyCustomAgent` class, we initialize an instance of the `CustomMemory` class and assign it to the `self.long_term_memory` attribute. This custom memory instance can then be utilized within the overridden `run` method, where you can query the memory and process the results as needed. +- Use structured logging -## Step 5: Introduce Custom Prompts and Standard Operating Procedures (SOPs) +- Implement log rotation -The Agent class allows you to define custom prompts and Standard Operating Procedures (SOPs) that guide an agent's behavior and decision-making process. Custom agent classes can inherit and extend these prompts and SOPs to align with their unique objectives and requirements. +- Regular log analysis -```python -from swarms import Agent +3. Alerts +- Set up alerting for critical errors -class MyCustomAgent(Agent): +- Monitor resource usage -    def __init__(self, *args, **kwargs): +- Track API rate limits -        super().__init__(*args, **kwargs) +-------------------------------------------------- -        # Custom initialization logic +# File: swarms\structs\multi_swarm_orchestration.md -        self.custom_sop = "Custom SOP for MyCustomAgent..." +# Hierarchical Agent Orchestration Architectures -        self.custom_prompt = "Custom prompt for MyCustomAgent..." +Hierarchical agent orchestration involves organizing multiple agents in structured layers to efficiently handle complex tasks. There are several key architectures available, each with distinct characteristics and use cases. -    def run(self, task, *args, **kwargs): +Here are the Hierarchical swarms we support: -        # Customize the run method +| Architecture | Strengths | Weaknesses | +|--------------|-----------|------------| +| HHCS | - Clear task routing
- Specialized swarm handling
- Parallel processing capability
- Good for complex multi-domain tasks | - More complex setup
- Overhead in routing
- Requires careful swarm design | +| Auto Agent Builder | - Dynamic agent creation
- Flexible scaling
- Self-organizing
- Good for evolving tasks | - Higher resource usage
- Potential creation overhead
- May create redundant agents | +| SwarmRouter | - Multiple workflow types
- Simple configuration
- Flexible deployment
- Good for varied task types | - Less specialized than HHCS
- Limited inter-swarm communication
- May require manual type selection | -        response = super().run(task, *args, **kwargs) -        # Utilize custom prompts and SOPs -        custom_prompt = self.construct_dynamic_prompt(self.custom_prompt) +## Core Architectures -        custom_sop = self.construct_dynamic_sop(self.custom_sop) +### 1. Hybrid Hierarchical-Cluster Swarm (HHCS) -        # Process custom prompts and SOPs +Hybrid Hierarchical-Cluster Swarm (HHCS) is architecture that uses a Router Agent to analyze and distribute tasks to other swarms. -        return response +- Tasks are routed to specialized swarms based on their requirements -    def construct_dynamic_prompt(self, prompt): +- Enables parallel processing through multiple specialized swarms -        # Custom prompt construction logic +- Ideal for complex, multi-domain tasks and enterprise-scale operations -        return prompt +- Provides clear task routing but requires more complex setup -    def construct_dynamic_sop(self, sop): -        # Custom SOP construction logic +```mermaid +flowchart TD + Start([Task Input]) --> RouterAgent[Router Agent] + RouterAgent --> Analysis{Task Analysis} + + Analysis -->|Analyze Requirements| Selection[Swarm Selection] + Selection -->|Select Best Swarm| Route[Route Task] + + Route --> Swarm1[Specialized Swarm 1] + Route --> Swarm2[Specialized Swarm 2] + Route --> SwarmN[Specialized Swarm N] + + Swarm1 -->|Process| Result1[Output 1] + Swarm2 -->|Process| Result2[Output 2] + SwarmN -->|Process| ResultN[Output N] + + Result1 --> Final[Final Output] + Result2 --> Final + ResultN --> Final +``` -        return sop +### 2. Auto Agent Builder -``` +Auto Agent Builder is a dynamic agent architecture that creates specialized agents on-demand. -In the example above, we define two new attributes within the `MyCustomAgent` class: `custom_sop` and `custom_prompt`. These attributes can be used to store custom prompts and SOPs specific to your custom agent class. +- Analyzes tasks and automatically builds appropriate agents for the job -Within the overridden `run` method, you can utilize these custom prompts and SOPs by calling the `construct_dynamic_prompt` and `construct_dynamic_sop` methods, which can be defined within the `MyCustomAgent` class to implement specialized prompt and SOP construction logic. +- Maintains an agent pool that feeds into task orchestration -#### Step 5: Introduce Custom Response Handling +- Best suited for evolving requirements and dynamic workloads -The Agent class provides built-in response filtering capabilities, allowing agents to filter out or replace specific words or phrases in their responses. Custom agent classes can inherit and extend this feature to ensure compliance with content moderation policies or specific guidelines. +- Self-organizing but may have higher resource usage -```python -from swarms import Agent +```mermaid +flowchart TD + Task[Task Input] --> Builder[Agent Builder] + Builder --> Analysis{Task Analysis} + + Analysis --> Create[Create Specialized Agents] + Create --> Pool[Agent Pool] + + Pool --> Agent1[Specialized Agent 1] + Pool --> Agent2[Specialized Agent 2] + Pool --> AgentN[Specialized Agent N] + + Agent1 --> Orchestration[Task Orchestration] + Agent2 --> Orchestration + AgentN --> Orchestration + + Orchestration --> Result[Final Result] +``` +### 3. SwarmRouter -class MyCustomAgent(Agent): -    def __init__(self, *args, **kwargs): +SwarmRouter is a flexible system supporting multiple swarm architectures through a simple interface: -        super().__init__(*args, **kwargs) +- Sequential workflows -        # Custom initialization logic +- Concurrent workflows -        self.response_filters = ["filter_word_1", "filter_word_2"] +- Hierarchical swarms -    def run(self, task, *args, **kwargs): +- Group chat interactions -        # Customize the run method +- Simpler to configure and deploy compared to other architectures -        response = super().run(task, *args, **kwargs) +- Best for general-purpose tasks and smaller scale operations -        # Apply custom response filtering +- Recommended for 5-20 agents. -        filtered_response = self.apply_response_filters(response) +```mermaid +flowchart TD + Input[Task Input] --> Router[Swarm Router] + Router --> TypeSelect{Swarm Type Selection} + + TypeSelect -->|Sequential| Seq[Sequential Workflow] + TypeSelect -->|Concurrent| Con[Concurrent Workflow] + TypeSelect -->|Hierarchical| Hier[Hierarchical Swarm] + TypeSelect -->|Group| Group[Group Chat] + + Seq --> Output[Task Output] + Con --> Output + Hier --> Output + Group --> Output +``` -        return filtered_response +## Use Case Recommendations -    def apply_response_filters(self, response): +### **HHCS**: Best for: + +- Enterprise-scale operations -        # Custom response filtering logic +- Multi-domain problems -        for word in self.response_filters: +- Complex task routing -            response = response.replace(word, "[FILTERED]") +- Parallel processing needs -        return response +### **Auto Agent Builder**: Best for: -``` +- Dynamic workloads -In the example above, we define a new attribute `response_filters` within the `MyCustomAgent` class, which is a list of words or phrases that should be filtered out or replaced in the agent's responses. +- Evolving requirements -Within the overridden `run` method, we call the `apply_response_filters` method, which can be defined within the `MyCustomAgent` class to implement specialized response filtering logic. In the example, we iterate over the `response_filters` list and replace each filtered word or phrase with a placeholder string (`"[FILTERED]"`). +- Research and development -### Advanced Customization and Integration +- Exploratory tasks -The Agent class and its inherited custom agent classes can be further extended and customized to suit specific requirements and integrate with external libraries, APIs, and services. Here are some advanced customization and integration examples: +### **SwarmRouter**: Best for: -1\. **Multimodal Input/Output Integration**: Custom agent classes can leverage the multimodal input/output capabilities of the Agent class and introduce specialized handling for various data formats such as images, audio, and video. +- General purpose tasks -2\. **Code Execution and Integration**: The Agent class supports code execution, enabling agents to run and evaluate code snippets. Custom agent classes can inherit and extend this capability, introducing specialized code execution environments, sandboxing mechanisms, or integration with external code repositories or platforms. +- Quick deployment -3\. **External API and Service Integration**: Custom agent classes can integrate with external APIs and services, enabling agents to leverage specialized data sources, computational resources, or domain-specific services. +- Mixed workflow types -4\. **Performance Optimization**: Depending on the use case and requirements, custom agent classes can introduce performance optimizations, such as adjusting loop intervals, retry attempts, or enabling parallel execution for certain tasks. +- Smaller scale operations -5\. **Logging and Monitoring**: Custom agent classes can introduce specialized logging and monitoring mechanisms, enabling agents to track their performance, identify potential issues, and generate detailed reports or dashboards. +## Documentation Links -6\. **Security and Privacy Enhancements**: Custom agent classes can implement security and privacy enhancements, such as data encryption, access control mechanisms, or compliance with industry-specific regulations and standards. +### HHCS Documentation: -7\. **Distributed Execution and Scaling**: Custom agent classes can be designed to support distributed execution and scaling, enabling agents to leverage cloud computing resources or distributed computing frameworks for handling large-scale tasks or high-concurrency workloads. +- [Hybrid Hierarchical-Cluster Swarm Documentation](https://docs.swarms.world/en/latest/swarms/structs/hhcs/) -By leveraging these advanced customization and integration capabilities, agents can create highly specialized and sophisticated custom agent classes tailored to their unique requirements and use cases. +- Covers detailed implementation, constructor arguments, and full examples -### Best Practices and Considerations +### Auto Agent Builder Documentation: + +- [Agent Builder Documentation](https://docs.swarms.world/en/latest/swarms/structs/auto_agent_builder/) -While building custom agent classes by inheriting from the Agent class offers immense flexibility and power, it's essential to follow best practices and consider potential challenges and considerations: +- Includes enterprise use cases, best practices, and integration patterns -1\. **Maintainability and Documentation**: As custom agent classes become more complex, it's crucial to prioritize maintainability and thorough documentation. Clear and concise code, comprehensive comments, and up-to-date documentation can significantly improve the long-term sustainability and collaboration efforts surrounding custom agent classes. +3. SwarmRouter Documentation: -2\. **Testing and Validation**: Custom agent classes should undergo rigorous testing and validation to ensure their correctness, reliability, and adherence to expected behaviors. Establish a robust testing framework and continuously validate the agent's performance, particularly after introducing new features or integrations. +- [SwarmRouter Documentation](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/) -3\. **Security and Privacy Considerations**: When building custom agent classes, it's essential to consider security and privacy implications, especially if the agents will handle sensitive data or interact with critical systems. Implement appropriate security measures, such as access controls, data encryption, and secure communication protocols, to protect against potential vulnerabilities and ensure compliance with relevant regulations and standards. +- Provides comprehensive API reference, advanced usage, and use cases -4\. **Scalability and Performance Monitoring**: As custom agent classes are deployed and adopted, it's important to monitor their scalability and performance characteristics. Identify potential bottlenecks, resource constraints, or performance degradation, and implement appropriate optimization strategies or scaling mechanisms to ensure efficient and reliable operation. +## Best Practices for Selection -5\. **Collaboration and Knowledge Sharing**: Building custom agent classes often involves collaboration among teams and stakeholders. Foster an environment of knowledge sharing, code reviews, and open communication to ensure that everyone involved understands the agent's capabilities, limitations, and intended use cases. +### **Evaluate Task Complexity** + +- Simple tasks → SwarmRouter -6\. **Ethical Considerations**: As AI agents become more advanced and autonomous, it's crucial to consider the ethical implications of their actions and decisions. Implement appropriate safeguards, oversight mechanisms, and ethical guidelines to ensure that custom agent classes operate in a responsible and transparent manner, aligning with ethical principles and societal values. +- Complex, multi-domain tasks → HHCS -7\. **Continuous Learning and Adaptation**: The field of AI is rapidly evolving, with new techniques, tools, and best practices emerging regularly. Stay up-to-date with the latest developments and be prepared to adapt and refine your custom agent classes as new advancements become available. +- Dynamic, evolving tasks → Auto Agent Builder -By following these best practices and considering potential challenges, agents can create robust, reliable, and ethical custom agent classes that meet their specific requirements while adhering to industry standards and best practices. +### **Consider Scale** + +- Small scale → SwarmRouter -# Conclusion +- Large scale → HHCS -In this comprehensive guide, we have explored the process of creating custom agent classes by inheriting from the powerful Agent class. We have covered the key features of the Agent class, walked through the step-by-step process of inheriting and extending its functionality, and discussed advanced customization and integration techniques. +- Variable scale → Auto Agent Builder -Building custom agent classes empowers AI agents to create tailored and specialized agents capable of tackling unique challenges and addressing specific domain requirements. By leveraging the rich features and extensibility of the Agent class, agents can imbue their offspring agents with unique capabilities, specialized toolsets, and tailored decision-making processes. +### **Resource Availability** + +- Limited resources → SwarmRouter -Remember, the journey of building custom agent classes is an iterative and collaborative process that requires continuous learning, adaptation, and refinement. +- Abundant resources → HHCS or Auto Agent Builder --------------------------------------------------- +- Dynamic resources → Auto Agent Builder -# File: swarms/structs/forest_swarm.md +### **Development Time** -# Forest Swarm +- Quick deployment → SwarmRouter -This documentation describes the **ForestSwarm** that organizes agents into trees. Each agent specializes in processing specific tasks. Trees are collections of agents, each assigned based on their relevance to a task through keyword extraction and embedding-based similarity. +- Complex system → HHCS -The architecture allows for efficient task assignment by selecting the most relevant agent from a set of trees. Tasks are processed asynchronously, with agents selected based on task relevance, calculated by the similarity of system prompts and task keywords. +- Experimental system → Auto Agent Builder -## Module Path: `swarms.structs.tree_swarm` +This documentation provides a high-level overview of the main hierarchical agent orchestration architectures available in the system. Each architecture has its own strengths and ideal use cases, and the choice between them should be based on specific project requirements, scale, and complexity. ---- -### Class: `TreeAgent` +-------------------------------------------------- -`TreeAgent` represents an individual agent responsible for handling a specific task. Agents are initialized with a **system prompt** and are responsible for dynamically determining their relevance to a given task. +# File: swarms\structs\multi_threaded_workflow.md -#### Attributes +# MultiThreadedWorkflow Documentation -| **Attribute** | **Type** | **Description** | -|--------------------------|------------------|---------------------------------------------------------------------------------| -| `system_prompt` | `str` | A string that defines the agent's area of expertise and task-handling capability.| -| `llm` | `callable` | The language model (LLM) used to process tasks (e.g., GPT-4). | -| `agent_name` | `str` | The name of the agent. | -| `system_prompt_embedding`| `tensor` | Embedding of the system prompt for similarity-based task matching. | -| `relevant_keywords` | `List[str]` | Keywords dynamically extracted from the system prompt to assist in task matching.| -| `distance` | `Optional[float]`| The computed distance between agents based on embedding similarity. | +The `MultiThreadedWorkflow` class represents a multi-threaded workflow designed to execute tasks concurrently using a thread pool. This class is highly useful in scenarios where tasks need to be executed in parallel to improve performance and efficiency. The workflow ensures that tasks are managed in a priority-based queue, and it includes mechanisms for retrying failed tasks and optionally saving task results automatically. -#### Methods +## Class Definition -| **Method** | **Input** | **Output** | **Description** | -|--------------------|---------------------------------|--------------------|---------------------------------------------------------------------------------| -| `calculate_distance(other_agent: TreeAgent)` | `other_agent: TreeAgent` | `float` | Calculates the cosine similarity between this agent and another agent. | -| `run_task(task: str)` | `task: str` | `Any` | Executes the task, logs the input/output, and returns the result. | -| `is_relevant_for_task(task: str, threshold: float = 0.7)` | `task: str, threshold: float` | `bool` | Checks if the agent is relevant for the task using keyword matching or embedding similarity.| +### `MultiThreadedWorkflow` ---- +## Parameters -### Class: `Tree` +| Parameter | Type | Default | Description | +|---------------|-----------------------|---------|---------------------------------------------------------------| +| `max_workers` | `int` | `5` | The maximum number of worker threads in the thread pool. | +| `autosave` | `bool` | `True` | Flag indicating whether to automatically save task results. | +| `tasks` | `List[PriorityTask]` | `None` | List of priority tasks to be executed. | +| `retry_attempts` | `int` | `3` | The maximum number of retry attempts for failed tasks. | +| `*args` | `tuple` | | Variable length argument list. | +| `**kwargs` | `dict` | | Arbitrary keyword arguments. | -`Tree` organizes multiple agents into a hierarchical structure, where agents are sorted based on their relevance to tasks. +## Attributes -#### Attributes +| Attribute | Type | Description | +|------------------|--------------------|----------------------------------------------------------------| +| `max_workers` | `int` | The maximum number of worker threads in the thread pool. | +| `autosave` | `bool` | Flag indicating whether to automatically save task results. | +| `retry_attempts` | `int` | The maximum number of retry attempts for failed tasks. | +| `tasks_queue` | `PriorityQueue` | The queue that holds the priority tasks. | +| `lock` | `Lock` | The lock used for thread synchronization. | -| **Attribute** | **Type** | **Description** | -|--------------------------|------------------|---------------------------------------------------------------------------------| -| `tree_name` | `str` | The name of the tree (represents a domain of agents, e.g., "Financial Tree"). | -| `agents` | `List[TreeAgent]`| List of agents belonging to this tree. | +## Methods -#### Methods +### `run` -| **Method** | **Input** | **Output** | **Description** | -|--------------------|---------------------------------|--------------------|---------------------------------------------------------------------------------| -| `calculate_agent_distances()` | `None` | `None` | Calculates and assigns distances between agents based on similarity of prompts. | -| `find_relevant_agent(task: str)` | `task: str` | `Optional[TreeAgent]` | Finds the most relevant agent for a task based on keyword and embedding similarity. | -| `log_tree_execution(task: str, selected_agent: TreeAgent, result: Any)` | `task: str, selected_agent: TreeAgent, result: Any` | `None` | Logs details of the task execution by the selected agent. | ---- +#### Description -### Class: `ForestSwarm` +The `run` method executes the tasks stored in the priority queue using a thread pool. It handles task completion, retries failed tasks up to a specified number of attempts, and optionally saves the results of tasks if the autosave flag is set. -`ForestSwarm` is the main class responsible for managing multiple trees. It oversees task delegation by finding the most relevant tree and agent for a given task. +#### Usage Example -#### Attributes +```python +from swarms import MultiThreadedWorkflow, PriorityTask, Task -| **Attribute** | **Type** | **Description** | -|--------------------------|------------------|---------------------------------------------------------------------------------| -| `trees` | `List[Tree]` | List of trees containing agents organized by domain. | +# Define some tasks +tasks = [PriorityTask(task=Task()), PriorityTask(task=Task())] -#### Methods +# Create a MultiThreadedWorkflow instance +workflow = MultiThreadedWorkflow(max_workers=3, autosave=True, tasks=tasks, retry_attempts=2) -| **Method** | **Input** | **Output** | **Description** | -|--------------------|---------------------------------|--------------------|---------------------------------------------------------------------------------| -| `find_relevant_tree(task: str)` | `task: str` | `Optional[Tree]` | Searches across all trees to find the most relevant tree based on task requirements.| -| `run(task: str)` | `task: str` | `Any` | Executes the task by finding the most relevant agent from the relevant tree. | +# Run the workflow +results = workflow.run() +print(results) +``` -## Full Code Example +### `_autosave_task_result` -```python -from swarms.structs.tree_swarm import TreeAgent, Tree, ForestSwarm -# Example Usage: +#### Description -# Create agents with varying system prompts and dynamically generated distances/keywords -agents_tree1 = [ - TreeAgent( - system_prompt="Stock Analysis Agent", - agent_name="Stock Analysis Agent", - ), - TreeAgent( - system_prompt="Financial Planning Agent", - agent_name="Financial Planning Agent", - ), - TreeAgent( - agent_name="Retirement Strategy Agent", - system_prompt="Retirement Strategy Agent", - ), -] +The `_autosave_task_result` method is responsible for saving the results of a task. It uses a thread lock to ensure that the autosave operation is thread-safe. -agents_tree2 = [ - TreeAgent( - system_prompt="Tax Filing Agent", - agent_name="Tax Filing Agent", - ), - TreeAgent( - system_prompt="Investment Strategy Agent", - agent_name="Investment Strategy Agent", - ), - TreeAgent( - system_prompt="ROTH IRA Agent", agent_name="ROTH IRA Agent" - ), -] +#### Usage Example -# Create trees -tree1 = Tree(tree_name="Financial Tree", agents=agents_tree1) -tree2 = Tree(tree_name="Investment Tree", agents=agents_tree2) +This method is intended for internal use and is typically called by the `run` method. However, here is an example of how it might be used directly: -# Create the ForestSwarm -multi_agent_structure = ForestSwarm(trees=[tree1, tree2]) +```python +# Create a task and result +task = Task() +result = task.run() -# Run a task -task = "Our company is incorporated in delaware, how do we do our taxes for free?" -output = multi_agent_structure.run(task) -print(output) +# Autosave the result +workflow = MultiThreadedWorkflow() +workflow._autosave_task_result(task, result) ``` +## Detailed Functionality and Usage +### Initialization ---- +When an instance of `MultiThreadedWorkflow` is created, it initializes the following: -## Example Workflow +- **max_workers**: Sets the maximum number of threads that can run concurrently. +- **autosave**: Determines if the task results should be saved automatically. +- **tasks**: Accepts a list of tasks that need to be executed. If no tasks are provided, an empty list is used. +- **retry_attempts**: Sets the maximum number of retry attempts for failed tasks. +- **tasks_queue**: A priority queue to manage tasks based on their priority. +- **lock**: A threading lock to ensure thread-safe operations. -1. **Create Agents**: Agents are initialized with varying system prompts, representing different areas of expertise (e.g., stock analysis, tax filing). -2. **Create Trees**: Agents are grouped into trees, with each tree representing a domain (e.g., "Financial Tree", "Investment Tree"). -3. **Run Task**: When a task is submitted, the system traverses through all trees and finds the most relevant agent to handle the task. -4. **Task Execution**: The selected agent processes the task, and the result is returned. +### Running Tasks -```plaintext -Task: "Our company is incorporated in Delaware, how do we do our taxes for free?" -``` +The `run` method performs the following steps: -**Process**: -- The system searches through the `Financial Tree` and `Investment Tree`. -- The most relevant agent (likely the "Tax Filing Agent") is selected based on keyword matching and prompt similarity. -- The task is processed, and the result is logged and returned. +1. **Initialize Results and Executor**: Creates a list to store results and a `ThreadPoolExecutor` to manage the threads. +2. **Submit Tasks**: Iterates over the tasks in the queue, submitting them to the executor for execution and storing the future objects. +3. **Monitor Completion**: Uses the `wait` function to monitor the completion of tasks. Once a task is completed, it retrieves the result or catches exceptions. +4. **Retry Mechanism**: If a task fails, it checks the number of attempts made and retries the task if the limit is not reached. +5. **Autosave**: If the `autosave` flag is set, the `_autosave_task_result` method is called to save the task results. ---- +### Autosave Task Result -## Analysis of the Swarm Architecture +The `_autosave_task_result` method handles the saving of task results. It uses a threading lock to ensure that the save operation is not interrupted by other threads. -The **Swarm Architecture** leverages a hierarchical structure (forest) composed of individual trees, each containing agents specialized in specific domains. This design allows for: +## Additional Information and Tips -- **Modular and Scalable Organization**: By separating agents into trees, it is easy to expand or contract the system by adding or removing trees or agents. -- **Task Specialization**: Each agent is specialized, which ensures that tasks are matched with the most appropriate agent based on relevance and expertise. -- **Dynamic Matching**: The architecture uses both keyword-based and embedding-based matching to assign tasks, ensuring a high level of accuracy in agent selection. -- **Logging and Accountability**: Each task execution is logged in detail, providing transparency and an audit trail of which agent handled which task and the results produced. -- **Asynchronous Task Execution**: The architecture can be adapted for asynchronous task processing, making it scalable and suitable for large-scale task handling in real-time systems. +- **Thread Safety**: The use of threading locks ensures that the operations are thread-safe, preventing race conditions. +- **Logging**: The class uses the logging module to log information about task completion, retries, and failures. +- **Error Handling**: The retry mechanism helps in handling transient errors by attempting to re-execute failed tasks. ---- +## References and Resources -## Mermaid Diagram of the Swarm Architecture +For more information on threading and concurrent execution in Python, refer to the following resources: -```mermaid -graph TD - A[ForestSwarm] --> B[Financial Tree] - A --> C[Investment Tree] - - B --> D[Stock Analysis Agent] - B --> E[Financial Planning Agent] - B --> F[Retirement Strategy Agent] - - C --> G[Tax Filing Agent] - C --> H[Investment Strategy Agent] - C --> I[ROTH IRA Agent] +- [Python Threading Documentation](https://docs.python.org/3/library/threading.html) +- [Python Concurrent Futures Documentation](https://docs.python.org/3/library/concurrent.futures.html) - subgraph Tree Agents - D[Stock Analysis Agent] - E[Financial Planning Agent] - F[Retirement Strategy Agent] - G[Tax Filing Agent] - H[Investment Strategy Agent] - I[ROTH IRA Agent] - end -``` -### Explanation of the Diagram +-------------------------------------------------- -- **ForestSwarm**: Represents the top-level structure managing multiple trees. -- **Trees**: In the example, two trees exist—**Financial Tree** and **Investment Tree**—each containing agents related to specific domains. -- **Agents**: Each agent within the tree is responsible for handling tasks in its area of expertise. Agents within a tree are organized based on their prompt similarity (distance). +# File: swarms\structs\orchestration_methods.md ---- +# Multi-Agent Orchestration Methods -### Summary +Swarms provides a comprehensive suite of orchestration methods for coordinating multiple AI agents in structured conversations and decision-making processes. These methods enable sophisticated multi-agent interactions like debates, panel discussions, negotiations, and more. -This **Multi-Agent Tree Structure** provides an efficient, scalable, and accurate architecture for delegating and executing tasks based on domain-specific expertise. The combination of hierarchical organization, dynamic task matching, and logging ensures reliability, performance, and transparency in task execution. +## Overview --------------------------------------------------- -# File: swarms/structs/graph_workflow.md +| Method | Orchestration Description | Use Case | +|--------------------------|------------------------------------------------------------------------------------------|--------------------------------------------| +| OneOnOneDebate | Turn-based debates between two agents. Structured debates where two agents alternate turns presenting arguments. | Philosophical discussions, arguments | +| ExpertPanelDiscussion | Expert panel discussions with a moderator. Multiple experts discuss topics, guided by a moderator. | Professional discussions, expert opinions | +| RoundTableDiscussion | Round table discussions with multiple participants. Open discussions among several agents, each contributing equally. | Group discussions, brainstorming | +| InterviewSeries | Structured interviews with follow-up questions. One agent interviews another, with dynamic follow-up questions. | Q&A sessions, information gathering | +| PeerReviewProcess | Academic peer review processes. Simulated academic review, where agents critique and provide feedback. | Research review, feedback processes | +| MediationSession | Mediation sessions for conflict resolution. Agents participate in sessions to resolve disputes, often with a mediator. | Dispute resolution, negotiations | +| BrainstormingSession | Brainstorming sessions for idea generation. Collaborative sessions focused on generating new ideas. | Innovation, problem solving | +| TrialSimulation | Trial simulations with legal roles. Agents assume legal roles to simulate a courtroom trial. | Legal proceedings, case analysis | +| CouncilMeeting | Council meetings with voting procedures. Decision-making meetings where agents vote on proposals. | Governance, voting processes | +| MentorshipSession | Mentorship sessions with feedback loops. One or more agents mentor others, providing feedback and guidance. | Learning, guidance | +| NegotiationSession | Complex negotiations between parties. Multi-party negotiations to reach agreements or resolve conflicts. | Business deals, agreements | -# GraphWorkflow Documentation +## OneOnOneDebate -The `GraphWorkflow` class is a pivotal part of the workflow management system, representing a directed graph where nodes signify tasks or agents and edges represent the flow or dependencies between these nodes. This class leverages the NetworkX library to manage and manipulate the directed graph, allowing users to create complex workflows with defined entry and end points. +### Description +Simulates a turn-based debate between two agents for a specified number of loops. Each agent takes turns responding to the other's arguments. -### Attributes +### Parameters -| Attribute | Type | Description | Default | -|----------------|-------------------|-----------------------------------------------------------------------------------------------|-------------------------------------| -| `nodes` | `Dict[str, Node]` | A dictionary of nodes in the graph, where the key is the node ID and the value is the Node object. | `Field(default_factory=dict)` | -| `edges` | `List[Edge]` | A list of edges in the graph, where each edge is represented by an Edge object. | `Field(default_factory=list)` | -| `entry_points` | `List[str]` | A list of node IDs that serve as entry points to the graph. | `Field(default_factory=list)` | -| `end_points` | `List[str]` | A list of node IDs that serve as end points of the graph. | `Field(default_factory=list)` | -| `graph` | `nx.DiGraph` | A directed graph object from the NetworkX library representing the workflow graph. | `Field(default_factory=nx.DiGraph)` | -| `max_loops` | `int` | Maximum number of times the workflow can loop during execution. | `1` | +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| max_loops | int | Number of conversational turns | No | 1 | +| agents | List[Agent] | Two agents for debate | Yes | None | +| img | str | Optional image input | No | None | +| output_type | str | Format for conversation history | No | "str-all-except-first" | -### Methods +### Run Method -#### `add_node(node: Node)` +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes debate between agents | -Adds a node to the workflow graph. +### Example -| Parameter | Type | Description | -|-----------|------|-----------------------------------| -| `node` | `Node` | The node object to be added. | +Full example: [Philosophy Discussion Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/philosophy_discussion_example.py) -Raises: -- `ValueError`: If a node with the same ID already exists in the graph. +```python +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import OneOnOneDebate -#### `add_edge(edge: Edge)` +# Create debating agents +agent1 = Agent(name="Philosopher1") +agent2 = Agent(name="Philosopher2") -Adds an edge to the workflow graph. +# Initialize debate +debate = OneOnOneDebate( + max_loops=3, + agents=[agent1, agent2] +) -| Parameter | Type | Description | -|-----------|------|----------------------------------| -| `edge` | `Edge` | The edge object to be added. | +# Run debate +result = debate.run("Is artificial intelligence consciousness possible?") +``` -Raises: -- `ValueError`: If either the source or target node of the edge does not exist in the graph. +## ExpertPanelDiscussion -#### `set_entry_points(entry_points: List[str])` +### Description +Simulates an expert panel discussion with a moderator guiding the conversation. Multiple experts provide insights on a topic with structured rounds. -Sets the entry points of the workflow graph. +### Parameters -| Parameter | Type | Description | -|----------------|-----------|---------------------------------------------| -| `entry_points` | `List[str]` | A list of node IDs to be set as entry points. | +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| max_rounds | int | Number of discussion rounds | No | 3 | +| agents | List[Agent] | Expert panel participants | Yes | None | +| moderator | Agent | Discussion moderator | Yes | None | +| output_type | str | Format for conversation history | No | "str-all-except-first" | -Raises: -- `ValueError`: If any of the specified node IDs do not exist in the graph. +### Run Method -#### `set_end_points(end_points: List[str])` +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes panel discussion | -Sets the end points of the workflow graph. +### Example -| Parameter | Type | Description | -|--------------|-----------|-------------------------------------------| -| `end_points` | `List[str]` | A list of node IDs to be set as end points. | +Full example: [Healthcare Panel Discussion](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/healthcare_panel_discussion.py) -Raises: -- `ValueError`: If any of the specified node IDs do not exist in the graph. +```python +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import ExpertPanelDiscussion -#### `visualize() -> str` +# Create expert agents +moderator = Agent(name="Moderator") +expert1 = Agent(name="AI_Expert") +expert2 = Agent(name="Ethics_Expert") +expert3 = Agent(name="Neuroscience_Expert") -Generates a string representation of the workflow graph in the Mermaid syntax. +# Initialize panel +panel = ExpertPanelDiscussion( + max_rounds=2, + agents=[expert1, expert2, expert3], + moderator=moderator +) -Returns: -- `str`: The Mermaid string representation of the workflow graph. +# Run panel discussion +result = panel.run("What are the ethical implications of AGI development?") +``` -#### `run(task: str = None, *args, **kwargs) -> Dict[str, Any]` +## RoundTableDiscussion -Function to run the workflow graph. +### Description +Simulates a round table where each participant speaks in order, then the cycle repeats. Facilitated discussion with equal participation. -| Parameter | Type | Description | -|-----------|-------|----------------------------------| -| `task` | `str` | The task to be executed by the workflow. | -| `*args` | | Variable length argument list. | -| `**kwargs`| | Arbitrary keyword arguments. | +### Parameters -Returns: -- `Dict[str, Any]`: A dictionary containing the results of the execution. +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| max_cycles | int | Number of speaking cycles | No | 2 | +| agents | List[Agent] | Round table participants | Yes | None | +| facilitator | Agent | Discussion facilitator | Yes | None | +| output_type | str | Format for conversation history | No | "str-all-except-first" | -Raises: -- `ValueError`: If no entry points or end points are defined in the graph. +### Run Method -## Functionality and Usage +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes round table discussion | -### Adding Nodes +### Example -The `add_node` method is used to add nodes to the graph. Each node must have a unique ID. If a node with the same ID already exists, a `ValueError` is raised. +Full example: [AI Ethics Debate](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/ai_ethics_debate.py) ```python -wf_graph = GraphWorkflow() -node1 = Node(id="node1", type=NodeType.TASK, callable=sample_task) -wf_graph.add_node(node1) -``` +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import RoundTableDiscussion -### Adding Edges +# Create participants +facilitator = Agent(name="Facilitator") +participant1 = Agent(name="Participant1") +participant2 = Agent(name="Participant2") +participant3 = Agent(name="Participant3") -The `add_edge` method connects nodes with edges. Both the source and target nodes of the edge must already exist in the graph, otherwise a `ValueError` is raised. +# Initialize round table +roundtable = RoundTableDiscussion( + max_cycles=2, + agents=[participant1, participant2, participant3], + facilitator=facilitator +) -```python -edge1 = Edge(source="node1", target="node2") -wf_graph.add_edge(edge1) +# Run discussion +result = roundtable.run("How can we improve renewable energy adoption?") ``` -### Setting Entry and End Points +## InterviewSeries -The `set_entry_points` and `set_end_points` methods define which nodes are the starting and ending points of the workflow, respectively. If any specified node IDs do not exist, a `ValueError` is raised. +### Description +Conducts a structured interview with follow-up questions. Systematic Q&A with depth through follow-up questions. -```python -wf_graph.set_entry_points(["node1"]) -wf_graph.set_end_points(["node2"]) -``` +### Parameters + +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| questions | List[str] | Prepared interview questions | No | Default questions | +| interviewer | Agent | Interviewer agent | Yes | None | +| interviewee | Agent | Interviewee agent | Yes | None | +| follow_up_depth | int | Follow-up questions per main question | No | 2 | +| output_type | str | Format for conversation history | No | "str-all-except-first" | + +### Run Method -### Visualizing the Graph +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes interview series | -The `visualize` method generates a Mermaid string representation of the workflow graph. This can be useful for visualizing the workflow structure. +### Example ```python -print(wf_graph.visualize()) -``` +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import InterviewSeries -### Running the Workflow +# Create agents +interviewer = Agent(name="Interviewer") +interviewee = Agent(name="Expert") + +# Prepare questions +questions = [ + "What is your background in AI?", + "How do you see AI evolving in the next decade?", + "What are the biggest challenges in AI development?" +] -The `run` method executes the workflow. It performs a topological sort of the graph to ensure nodes are executed in the correct order. The results of each node's execution are returned in a dictionary. +# Initialize interview +interview = InterviewSeries( + questions=questions, + interviewer=interviewer, + interviewee=interviewee, + follow_up_depth=2 +) -```python -results = wf_graph.run() -print("Execution results:", results) +# Run interview +result = interview.run("AI Development and Future Prospects") ``` -## Example Usage - -Below is a comprehensive example demonstrating the creation and execution of a workflow graph: +## PeerReviewProcess -```python +### Description +Simulates academic peer review with multiple reviewers and author responses. Structured feedback and revision process. -import os +### Parameters -from dotenv import load_dotenv +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| reviewers | List[Agent] | Reviewer agents | Yes | None | +| author | Agent | Author agent | Yes | None | +| review_rounds | int | Number of review rounds | No | 2 | +| output_type | str | Format for conversation history | No | "str-all-except-first" | +### Run Method -from swarms import Agent, Edge, GraphWorkflow, Node, NodeType +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes peer review process | -from swarm_models import OpenAIChat +### Example -load_dotenv() +```python +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import PeerReviewProcess -api_key = os.environ.get("OPENAI_API_KEY") +# Create agents +author = Agent(name="Author") +reviewer1 = Agent(name="Reviewer1") +reviewer2 = Agent(name="Reviewer2") -llm = OpenAIChat( - temperature=0.5, openai_api_key=api_key, max_tokens=4000 +# Initialize peer review +review = PeerReviewProcess( + reviewers=[reviewer1, reviewer2], + author=author, + review_rounds=2 ) -agent1 = Agent(llm=llm, max_loops=1, autosave=True, dashboard=True) -agent2 = Agent(llm=llm, max_loops=1, autosave=True, dashboard=True) -def sample_task(): - print("Running sample task") - return "Task completed" +# Run review process +result = review.run("New Machine Learning Algorithm for Natural Language Processing") +``` -wf_graph = GraphWorkflow() -wf_graph.add_node(Node(id="agent1", type=NodeType.AGENT, agent=agent1)) -wf_graph.add_node(Node(id="agent2", type=NodeType.AGENT, agent=agent2)) -wf_graph.add_node( - Node(id="task1", type=NodeType.TASK, callable=sample_task) -) -wf_graph.add_edge(Edge(source="agent1", target="task1")) -wf_graph.add_edge(Edge(source="agent2", target="task1")) +## MediationSession -wf_graph.set_entry_points(["agent1", "agent2"]) -wf_graph.set_end_points(["task1"]) +### Description +Simulates a mediation session to resolve conflicts between parties. Facilitated conflict resolution with structured sessions. -print(wf_graph.visualize()) +### Parameters -# Run the workflow -results = wf_graph.run() -print("Execution results:", results) +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| parties | List[Agent] | Disputing parties | Yes | None | +| mediator | Agent | Mediator agent | Yes | None | +| max_sessions | int | Number of mediation sessions | No | 3 | +| output_type | str | Format for conversation history | No | "str-all-except-first" | -``` +### Run Method -In this example, we set up a workflow graph with two agents and one task. We define the entry and end points, visualize the graph, and then execute the workflow, capturing and printing the results. +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes mediation session | -## Additional Information and Tips +### Example -- **Error Handling**: The `GraphWorkflow` class includes error handling to ensure that invalid operations (such as adding duplicate nodes or edges with non-existent nodes) raise appropriate exceptions. -- **Max Loops**: The `max_loops` attribute allows the workflow to loop through the graph multiple times if needed. This can be useful for iterative tasks. -- **Topological Sort**: The workflow execution relies on a topological sort to ensure that nodes are processed in the correct order. This is particularly important in complex workflows with dependencies. +Full example: [Merger Mediation Session](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/merger_mediation_session.py) -## References and Resources +```python +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import MediationSession -- [NetworkX Documentation](https://networkx.github.io/documentation/stable/) -- [Pydantic Documentation](https://pydantic-docs.helpmanual.io/) -- [Mermaid Documentation](https://mermaid-js.github.io/mermaid/#/) +# Create agents +mediator = Agent(name="Mediator") +party1 = Agent(name="Party1") +party2 = Agent(name="Party2") --------------------------------------------------- +# Initialize mediation +mediation = MediationSession( + parties=[party1, party2], + mediator=mediator, + max_sessions=3 +) -# File: swarms/structs/group_chat.md +# Run mediation +result = mediation.run("Resolve intellectual property dispute") +``` -# GroupChat Swarm Documentation +## BrainstormingSession -A production-grade multi-agent system enabling sophisticated group conversations between AI agents with customizable speaking patterns, parallel processing capabilities, and comprehensive conversation tracking. +### Description +Simulates a brainstorming session where participants build on each other's ideas. Creative idea generation with collaborative building. -## Advanced Configuration +### Parameters -### Agent Parameters +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| participants | List[Agent] | Brainstorming participants | Yes | None | +| facilitator | Agent | Session facilitator | Yes | None | +| idea_rounds | int | Number of idea generation rounds | No | 3 | +| build_on_ideas | bool | Whether to build on previous ideas | No | True | +| output_type | str | Format for conversation history | No | "str-all-except-first" | -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| agent_name | str | Required | Unique identifier for the agent | -| system_prompt | str | Required | Role and behavior instructions | -| llm | Any | Required | Language model instance | -| max_loops | int | 1 | Maximum conversation turns | -| autosave | bool | False | Enable conversation saving | -| dashboard | bool | False | Enable monitoring dashboard | -| verbose | bool | True | Enable detailed logging | -| dynamic_temperature | bool | True | Enable dynamic temperature | -| retry_attempts | int | 1 | Failed request retry count | -| context_length | int | 200000 | Maximum context window | -| output_type | str | "string" | Response format type | -| streaming_on | bool | False | Enable streaming responses | +### Run Method -### GroupChat Parameters +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes brainstorming session | -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| name | str | "GroupChat" | Chat group identifier | -| description | str | "" | Purpose description | -| agents | List[Agent] | [] | Participating agents | -| speaker_fn | Callable | round_robin | Speaker selection function | -| max_loops | int | 10 | Maximum conversation turns | +### Example +Full example: [Pharma Research Brainstorm](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/pharma_research_brainstorm.py) -## Table of Contents +```python +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import BrainstormingSession -- [Installation](#installation) -- [Core Concepts](#core-concepts) -- [Basic Usage](#basic-usage) -- [Advanced Configuration](#advanced-configuration) -- [Speaker Functions](#speaker-functions) -- [Response Models](#response-models) -- [Advanced Examples](#advanced-examples) -- [API Reference](#api-reference) -- [Best Practices](#best-practices) +# Create agents +facilitator = Agent(name="Facilitator") +participant1 = Agent(name="Creative1") +participant2 = Agent(name="Creative2") +participant3 = Agent(name="Creative3") -## Installation +# Initialize brainstorming +brainstorm = BrainstormingSession( + participants=[participant1, participant2, participant3], + facilitator=facilitator, + idea_rounds=3, + build_on_ideas=True +) -```bash -pip3 install swarms swarm-models loguru +# Run brainstorming +result = brainstorm.run("Innovative solutions for urban transportation") ``` -## Core Concepts +## TrialSimulation -The GroupChat system consists of several key components: +### Description +Simulates a legal trial with structured phases and roles. Complete legal proceeding simulation with all participants. -1. **Agents**: Individual AI agents with specialized knowledge and roles -2. **Speaker Functions**: Control mechanisms for conversation flow -3. **Chat History**: Structured conversation tracking -4. **Response Models**: Pydantic models for data validation +### Parameters -## Basic Usage +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| prosecution | Agent | Prosecution attorney | Yes | None | +| defense | Agent | Defense attorney | Yes | None | +| judge | Agent | Trial judge | Yes | None | +| witnesses | List[Agent] | Trial witnesses | No | None | +| phases | List[str] | Trial phases | No | Default phases | +| output_type | str | Format for conversation history | No | "str-all-except-first" | -```python +### Run Method -import os -from dotenv import load_dotenv -from swarm_models import OpenAIChat -from swarms import Agent, GroupChat, expertise_based +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes trial simulation | +### Example -if __name__ == "__main__": +Full example: [Medical Malpractice Trial](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/medical_malpractice_trial.py) - load_dotenv() +```python +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import TrialSimulation - # Get the OpenAI API key from the environment variable - api_key = os.getenv("OPENAI_API_KEY") +# Create agents +judge = Agent(name="Judge") +prosecutor = Agent(name="Prosecutor") +defense = Agent(name="Defense") +witness1 = Agent(name="Witness1") +witness2 = Agent(name="Witness2") - # Create an instance of the OpenAIChat class - model = OpenAIChat( - openai_api_key=api_key, - model_name="gpt-4o-mini", - temperature=0.1, - ) +# Initialize trial +trial = TrialSimulation( + prosecution=prosecutor, + defense=defense, + judge=judge, + witnesses=[witness1, witness2], + phases=["opening", "testimony", "cross", "closing"] +) - # Example agents - agent1 = Agent( - agent_name="Financial-Analysis-Agent", - system_prompt="You are a financial analyst specializing in investment strategies.", - llm=model, - max_loops=1, - autosave=False, - dashboard=False, - verbose=True, - dynamic_temperature_enabled=True, - user_name="swarms_corp", - retry_attempts=1, - context_length=200000, - output_type="string", - streaming_on=False, - ) +# Run trial +result = trial.run("Patent infringement case") +``` - agent2 = Agent( - agent_name="Tax-Adviser-Agent", - system_prompt="You are a tax adviser who provides clear and concise guidance on tax-related queries.", - llm=model, - max_loops=1, - autosave=False, - dashboard=False, - verbose=True, - dynamic_temperature_enabled=True, - user_name="swarms_corp", - retry_attempts=1, - context_length=200000, - output_type="string", - streaming_on=False, - ) +## CouncilMeeting - agents = [agent1, agent2] +### Description +Simulates a council meeting with structured discussion and decision-making. Governance process with voting and consensus building. - chat = GroupChat( - name="Investment Advisory", - description="Financial and tax analysis group", - agents=agents, - speaker_fn=expertise_based, - ) +### Parameters - history = chat.run( - "How to optimize tax strategy for investments?" - ) - print(history.model_dump_json(indent=2)) +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| council_members | List[Agent] | Council participants | Yes | None | +| chairperson | Agent | Meeting chairperson | Yes | None | +| voting_rounds | int | Number of voting rounds | No | 1 | +| require_consensus | bool | Whether consensus is required | No | False | +| output_type | str | Format for conversation history | No | "str-all-except-first" | -``` +### Run Method -## Speaker Functions +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes council meeting | +### Example -### Built-in Functions +Full example: [Investment Council Meeting](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/investment_council_meeting.py) ```python -def round_robin(history: List[str], agent: Agent) -> bool: - """ - Enables agents to speak in turns. - Returns True for each agent in sequence. - """ - return True +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import CouncilMeeting -def expertise_based(history: List[str], agent: Agent) -> bool: - """ - Enables agents to speak based on their expertise. - Returns True if agent's role matches conversation context. - """ - return agent.system_prompt.lower() in history[-1].lower() if history else True +# Create agents +chairperson = Agent(name="Chair") +member1 = Agent(name="Member1") +member2 = Agent(name="Member2") +member3 = Agent(name="Member3") -def random_selection(history: List[str], agent: Agent) -> bool: - """ - Randomly selects speaking agents. - Returns True/False with 50% probability. - """ - import random - return random.choice([True, False]) +# Initialize council meeting +council = CouncilMeeting( + council_members=[member1, member2, member3], + chairperson=chairperson, + voting_rounds=2, + require_consensus=True +) -def most_recent(history: List[str], agent: Agent) -> bool: - """ - Enables agents to respond to their mentions. - Returns True if agent was last speaker. - """ - return agent.agent_name == history[-1].split(":")[0].strip() if history else True +# Run meeting +result = council.run("Vote on new environmental policy") ``` -### Custom Speaker Function Example +## MentorshipSession -```python -def custom_speaker(history: List[str], agent: Agent) -> bool: - """ - Custom speaker function with complex logic. - - Args: - history: Previous conversation messages - agent: Current agent being evaluated - - Returns: - bool: Whether agent should speak - """ - # No history - let everyone speak - if not history: - return True - - last_message = history[-1].lower() - - # Check for agent expertise keywords - expertise_relevant = any( - keyword in last_message - for keyword in agent.expertise_keywords - ) - - # Check for direct mentions - mentioned = agent.agent_name.lower() in last_message - - # Check if agent hasn't spoken recently - not_recent_speaker = not any( - agent.agent_name in msg - for msg in history[-3:] - ) - - return expertise_relevant or mentioned or not_recent_speaker +### Description +Simulates a mentorship session with structured learning and feedback. Guided learning process with progress tracking. -# Usage -chat = GroupChat( - agents=[agent1, agent2], - speaker_fn=custom_speaker -) -``` +### Parameters -## Response Models +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| mentor | Agent | Mentor agent | Yes | None | +| mentee | Agent | Mentee agent | Yes | None | +| session_count | int | Number of sessions | No | 3 | +| include_feedback | bool | Whether to include feedback | No | True | +| output_type | str | Format for conversation history | No | "str-all-except-first" | -### Complete Schema +### Run Method + +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes mentorship session | + +### Example + +Full example: [Startup Mentorship Program](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/startup_mentorship_program.py) ```python -class AgentResponse(BaseModel): - """Individual agent response in a conversation turn""" - agent_name: str - role: str - message: str - timestamp: datetime = Field(default_factory=datetime.now) - turn_number: int - preceding_context: List[str] = Field(default_factory=list) +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import MentorshipSession -class ChatTurn(BaseModel): - """Single turn in the conversation""" - turn_number: int - responses: List[AgentResponse] - task: str - timestamp: datetime = Field(default_factory=datetime.now) +# Create agents +mentor = Agent(name="Mentor") +mentee = Agent(name="Mentee") -class ChatHistory(BaseModel): - """Complete conversation history""" - turns: List[ChatTurn] - total_messages: int - name: str - description: str - start_time: datetime = Field(default_factory=datetime.now) +# Initialize mentorship +mentorship = MentorshipSession( + mentor=mentor, + mentee=mentee, + session_count=3, + include_feedback=True +) + +# Run session +result = mentorship.run("Career development in AI research") ``` -## Advanced Examples +## NegotiationSession -### Multi-Agent Analysis Team +### Description +Simulates a negotiation with multiple parties working toward agreement. Complex multi-party negotiation with concessions. -```python -# Create specialized agents -data_analyst = Agent( - agent_name="Data-Analyst", - system_prompt="You analyze numerical data and patterns", - llm=model -) +### Parameters -market_expert = Agent( - agent_name="Market-Expert", - system_prompt="You provide market insights and trends", - llm=model -) +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| parties | List[Agent] | Negotiating parties | Yes | None | +| mediator | Agent | Negotiation mediator | Yes | None | +| negotiation_rounds | int | Number of rounds | No | 5 | +| include_concessions | bool | Whether to allow concessions | No | True | +| output_type | str | Format for conversation history | No | "str-all-except-first" | -strategy_advisor = Agent( - agent_name="Strategy-Advisor", - system_prompt="You formulate strategic recommendations", - llm=model -) +### Run Method -# Create analysis team -analysis_team = GroupChat( - name="Market Analysis Team", - description="Comprehensive market analysis group", - agents=[data_analyst, market_expert, strategy_advisor], - speaker_fn=expertise_based, - max_loops=15 -) +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes negotiation session | -# Run complex analysis -history = analysis_team.run(""" - Analyze the current market conditions: - 1. Identify key trends - 2. Evaluate risks - 3. Recommend investment strategy -""") -``` +### Example -### Parallel Processing +Full example: [NVIDIA-AMD Executive Negotiation](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/nvidia_amd_executive_negotiation.py) ```python -# Define multiple analysis tasks -tasks = [ - "Analyze tech sector trends", - "Evaluate real estate market", - "Review commodity prices", - "Assess global economic indicators" -] +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import NegotiationSession -# Run tasks concurrently -histories = chat.concurrent_run(tasks) +# Create agents +mediator = Agent(name="Mediator") +party1 = Agent(name="Company1") +party2 = Agent(name="Company2") -# Process results -for task, history in zip(tasks, histories): - print(f"\nAnalysis for: {task}") - for turn in history.turns: - for response in turn.responses: - print(f"{response.agent_name}: {response.message}") +# Initialize negotiation +negotiation = NegotiationSession( + parties=[party1, party2], + mediator=mediator, + negotiation_rounds=4, + include_concessions=True +) + +# Run negotiation +result = negotiation.run("Merger terms negotiation") ``` -## Best Practices +## Conclusion -1. **Agent Design** - - Give agents clear, specific roles - - Use detailed system prompts - - Set appropriate context lengths - - Enable retries for reliability +The multi-agent orchestration methods in Swarms provide powerful frameworks for structuring complex interactions between AI agents. Key benefits include: -2. **Speaker Functions** - - Match function to use case - - Consider conversation flow - - Handle edge cases - - Add appropriate logging +1. Structured Communication: Each method provides a clear framework for organizing multi-agent interactions +2. Role-Based Interactions: Agents can take on specific roles with defined responsibilities +3. Flexible Configuration: Customizable parameters for controlling interaction flow +4. Scalable Architecture: Support for various numbers of participants and interaction rounds +5. Comprehensive Coverage: Methods for different use cases from debates to negotiations +6. Professional Output: Consistent formatting and organization of conversation history +7. Easy Integration: Simple API for incorporating into larger applications -3. **Error Handling** - - Use try-except blocks - - Log errors appropriately - - Implement retry logic - - Provide fallback responses +-------------------------------------------------- -4. **Performance** - - Use concurrent processing for multiple tasks - - Monitor context lengths - - Implement proper cleanup - - Cache responses when appropriate +# File: swarms\structs\overview.md -## API Reference +# Multi-Agent Architectures Overview -### GroupChat Methods +This page provides a comprehensive overview of all available multi-agent architectures in Swarms, their use cases, and functionality. -| Method | Description | Arguments | Returns | -|--------|-------------|-----------|---------| -| run | Run single conversation | task: str | ChatHistory | -| batched_run | Run multiple sequential tasks | tasks: List[str] | List[ChatHistory] | -| concurrent_run | Run multiple parallel tasks | tasks: List[str] | List[ChatHistory] | -| get_recent_messages | Get recent messages | n: int = 3 | List[str] | +## Architecture Comparison -### Agent Methods +=== "Core Architectures" + | Architecture | Use Case | Key Functionality | Documentation | + |-------------|----------|-------------------|---------------| + | MajorityVoting | Decision making through consensus | Combines multiple agent opinions and selects the most common answer | [Docs](majorityvoting.md) | + | AgentRearrange | Optimizing agent order | Dynamically reorders agents based on task requirements | [Docs](agent_rearrange.md) | + | RoundRobin | Equal task distribution | Cycles through agents in a fixed order | [Docs](round_robin_swarm.md) | + | Mixture of Agents | Complex problem solving | Combines diverse expert agents for comprehensive analysis | [Docs](moa.md) | + | GroupChat | Collaborative discussions | Simulates group discussions with multiple agents | [Docs](group_chat.md) | + | AgentRegistry | Agent management | Central registry for managing and accessing agents | [Docs](agent_registry.md) | + | SpreadSheetSwarm | Data processing | Collaborative data processing and analysis | [Docs](spreadsheet_swarm.md) | + | ForestSwarm | Hierarchical decision making | Tree-like structure for complex decision processes | [Docs](forest_swarm.md) | + | SwarmRouter | Task routing | Routes tasks to appropriate agents based on requirements | [Docs](swarm_router.md) | + | TaskQueueSwarm | Task management | Manages and prioritizes tasks in a queue | [Docs](taskqueue_swarm.md) | + | SwarmRearrange | Dynamic swarm optimization | Optimizes swarm configurations for specific tasks | [Docs](swarm_rearrange.md) | + | MultiAgentRouter | Advanced task routing | Routes tasks to specialized agents based on capabilities | [Docs](multi_agent_router.md) | + | MatrixSwarm | Parallel processing | Matrix-based organization for parallel task execution | [Docs](matrix_swarm.md) | + | ModelRouter | Model selection | Routes tasks to appropriate AI models | [Docs](model_router.md) | + | MALT | Multi-agent learning | Enables agents to learn from each other | [Docs](malt.md) | + | Deep Research Swarm | Research automation | Conducts comprehensive research across multiple domains | [Docs](deep_research_swarm.md) | + | Swarm Matcher | Agent matching | Matches tasks with appropriate agent combinations | [Docs](swarm_matcher.md) | -| Method | Description | Returns | -|--------|-------------|---------| -| run | Process single task | str | -| generate_response | Generate LLM response | str | -| save_context | Save conversation context | None | +=== "Workflow Architectures" + | Architecture | Use Case | Key Functionality | Documentation | + |-------------|----------|-------------------|---------------| + | ConcurrentWorkflow | Parallel task execution | Executes multiple tasks simultaneously | [Docs](concurrentworkflow.md) | + | SequentialWorkflow | Step-by-step processing | Executes tasks in a specific sequence | [Docs](sequential_workflow.md) | + | GraphWorkflow | Complex task dependencies | Manages tasks with complex dependencies | [Docs](graph_workflow.md) | --------------------------------------------------- +=== "Hierarchical Architectures" + | Architecture | Use Case | Key Functionality | Documentation | + |-------------|----------|-------------------|---------------| + | HierarchicalSwarm | Hierarchical task orchestration | Director agent coordinates specialized worker agents | [Docs](hierarchical_swarm.md) | + | Auto Agent Builder | Automated agent creation | Automatically creates and configures agents | [Docs](auto_agent_builder.md) | + | Hybrid Hierarchical-Cluster Swarm | Complex organization | Combines hierarchical and cluster-based organization | [Docs](hhcs.md) | + | Auto Swarm Builder | Automated swarm creation | Automatically creates and configures swarms | [Docs](auto_swarm_builder.md) | -# File: swarms/structs/hhcs.md +## Communication Structure -# Hybrid Hierarchical-Cluster Swarm [HHCS] +!!! note "Communication Protocols" + The [Conversation](conversation.md) documentation details the communication protocols and structures used between agents in these architectures. -The Hybrid Hierarchical-Cluster Swarm (HHCS) is an advanced AI orchestration architecture that combines hierarchical decision-making with parallel processing capabilities. HHCS enables complex task solving by dynamically routing tasks to specialized agent swarms based on their expertise and capabilities. +## Choosing the Right Architecture -## Purpose +When selecting a multi-agent architecture, consider the following factors: -HHCS addresses the challenge of efficiently solving diverse and complex tasks by: +!!! tip "Task Complexity" + Simple tasks may only need basic architectures like RoundRobin, while complex tasks might require Hierarchical or Graph-based approaches. -- Intelligently routing tasks to the most appropriate specialized swarms +!!! tip "Parallelization Needs" + If tasks can be executed in parallel, consider ConcurrentWorkflow or MatrixSwarm. -- Enabling parallel processing of multifaceted problems +!!! tip "Decision Making Requirements" + For consensus-based decisions, MajorityVoting is ideal. -- Maintaining a clear hierarchy for effective decision-making +!!! tip "Resource Optimization" + If you need to optimize agent usage, consider SwarmRouter or TaskQueueSwarm. -- Combining outputs from multiple specialized agents for comprehensive solutions +!!! tip "Learning Requirements" + If agents need to learn from each other, MALT is the appropriate choice. -## Key Features +!!! tip "Dynamic Adaptation" + For tasks requiring dynamic adaptation, consider SwarmRearrange or Auto Swarm Builder. -- **Router-based task distribution**: Central router agent analyzes incoming tasks and directs them to appropriate specialized swarms +For more detailed information about each architecture, please refer to their respective documentation pages. -- **Hybrid architecture**: Combines hierarchical control with clustered specialization -- **Parallel processing**: Multiple swarms can work simultaneously on different aspects of complex tasks +-------------------------------------------------- -- **Flexible swarm types**: Supports both sequential and concurrent workflows within swarms +# File: swarms\structs\round_robin_swarm.md -- **Comprehensive result aggregation**: Collects and combines outputs from all contributing swarms +# RoundRobin: Round-Robin Task Execution in a Swarm +## Introduction -## Diagram +The `RoundRobinSwarm` class is designed to manage and execute tasks among multiple agents in a round-robin fashion. This approach ensures that each agent in a swarm receives an equal opportunity to execute tasks, which promotes fairness and efficiency in distributed systems. It is particularly useful in environments where collaborative, sequential task execution is needed among various agents. -The HHCS architecture follows a hierarchical structure with the router agent at the top level, specialized swarms at the middle level, and individual agents at the bottom level. +## Conceptual Overview +### What is Round-Robin? -```mermaid -flowchart TD - Start([Task Input]) --> RouterAgent[Router Agent] - RouterAgent --> Analysis{Task Analysis} - - Analysis -->|Analyze Requirements| Selection[Swarm Selection] - Selection -->|Select Best Swarm| Route[Route Task] - - Route --> Swarm1[Swarm 1] - Route --> Swarm2[Swarm 2] - Route --> SwarmN[Swarm N...] - - Swarm1 -->|Process Task| Result1[Swarm 1 Output] - Swarm2 -->|Process Task| Result2[Swarm 2 Output] - SwarmN -->|Process Task| ResultN[Swarm N Output] - - Result1 --> Conversation[Conversation History] - Result2 --> Conversation - ResultN --> Conversation - - Conversation --> Output([Final Output]) - - subgraph Router Decision Process - Analysis - Selection - end - - subgraph Parallel Task Processing - Swarm1 - Swarm2 - SwarmN - end - - subgraph Results Collection - Result1 - Result2 - ResultN - Conversation - end -``` +Round-robin is a scheduling technique commonly used in computing for managing processes in shared systems. It involves assigning a fixed time slot to each process and cycling through all processes in a circular order without prioritization. In the context of swarms of agents, this method ensures equitable distribution of tasks and resource usage among all agents. +### Application in Swarms -## `HybridHierarchicalClusterSwarm` Constructor Arguments +In swarms, `RoundRobinSwarm` utilizes the round-robin scheduling to manage tasks among agents like software components, autonomous robots, or virtual entities. This strategy is beneficial where tasks are interdependent or require sequential processing. -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `name` | string | "Hybrid Hierarchical-Cluster Swarm" | The name of the swarm instance | -| `description` | string | "A swarm that uses a hybrid hierarchical-peer model to solve complex tasks." | Brief description of the swarm's functionality | -| `swarms` | List[SwarmRouter] | [] | List of available swarm routers | -| `max_loops` | integer | 1 | Maximum number of processing loops | -| `output_type` | string | "list" | Format for output (e.g., "list", "json") | -| `router_agent_model_name` | string | "gpt-4o-mini" | LLM model used by the router agent | +## Class Attributes + +- `agents (List[Agent])`: List of agents participating in the swarm. +- `verbose (bool)`: Enables or disables detailed logging of swarm operations. +- `max_loops (int)`: Limits the number of times the swarm cycles through all agents. +- `index (int)`: Maintains the current position in the agent list to ensure round-robin execution. ## Methods -| Method | Parameters | Return Type | Description | -|--------|------------|-------------|-------------| -| `run` | `task` (str) | str | Processes a single task through the swarm system | -| `batched_run` | `tasks` (List[str]) | List[str] | Processes multiple tasks in parallel | -| `find_swarm_by_name` | `swarm_name` (str) | SwarmRouter | Retrieves a swarm by its name | -| `route_task` | `swarm_name` (str), `task_description` (str) | None | Routes a task to a specific swarm | -| `get_swarms_info` | None | str | Returns formatted information about all available swarms | +### `__init__` +Initializes the swarm with the provided list of agents, verbosity setting, and operational parameters. -## Full Example +**Parameters:** +- `agents`: Optional list of agents in the swarm. +- `verbose`: Boolean flag for detailed logging. +- `max_loops`: Maximum number of execution cycles. +- `callback`: Optional function called after each loop. -```python +### `run` -from swarms import Agent, SwarmRouter -from swarms.structs.hybrid_hiearchical_peer_swarm import ( - HybridHierarchicalClusterSwarm, -) +Executes a specified task across all agents in a round-robin manner, cycling through each agent repeatedly for the number of specified loops. +**Conceptual Behavior:** +- Distribute the task sequentially among all agents starting from the current index. +- Each agent processes the task and potentially modifies it or produces new output. +- After an agent completes its part of the task, the index moves to the next agent. +- This cycle continues until the specified maximum number of loops is completed. +- Optionally, a callback function can be invoked after each loop to handle intermediate results or perform additional actions. -# Core Legal Agent Definitions with short, simple prompts -litigation_agent = Agent( - agent_name="Litigator", - system_prompt="You handle lawsuits. Analyze facts, build arguments, and develop case strategy.", - model_name="groq/deepseek-r1-distill-qwen-32b", - max_loops=1, -) +## Examples +### Example 1: Load Balancing Among Servers -corporate_agent = Agent( - agent_name="Corporate-Attorney", - system_prompt="You handle business law. Advise on corporate structure, governance, and transactions.", - model_name="groq/deepseek-r1-distill-qwen-32b", - max_loops=1, -) +In this example, `RoundRobinSwarm` is used to distribute network requests evenly among a group of servers. This is common in scenarios where load balancing is crucial for maintaining system responsiveness and scalability. -ip_agent = Agent( - agent_name="IP-Attorney", - system_prompt="You protect intellectual property. Handle patents, trademarks, copyrights, and trade secrets.", - model_name="groq/deepseek-r1-distill-qwen-32b", - max_loops=1, -) +```python +from swarms import Agent, RoundRobinSwarm +from swarm_models import OpenAIChat -employment_agent = Agent( - agent_name="Employment-Attorney", - system_prompt="You handle workplace matters. Address hiring, termination, discrimination, and labor issues.", - model_name="groq/deepseek-r1-distill-qwen-32b", - max_loops=1, -) -paralegal_agent = Agent( - agent_name="Paralegal", - system_prompt="You assist attorneys. Conduct research, draft documents, and organize case files.", - model_name="groq/deepseek-r1-distill-qwen-32b", - max_loops=1, -) +# Initialize the LLM +llm = OpenAIChat() -doc_review_agent = Agent( - agent_name="Document-Reviewer", - system_prompt="You examine documents. Extract key information and identify relevant content.", - model_name="groq/deepseek-r1-distill-qwen-32b", +# Define sales agents +sales_agent1 = Agent( + agent_name="Sales Agent 1 - Automation Specialist", + system_prompt="You're Sales Agent 1, your purpose is to generate sales for a company by focusing on the benefits of automating accounting processes!", + agent_description="Generate sales by focusing on the benefits of automation!", + llm=llm, max_loops=1, + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + context_length=1000, ) -# Practice Area Swarm Routers -litigation_swarm = SwarmRouter( - name="litigation-practice", - description="Handle all aspects of litigation", - agents=[litigation_agent, paralegal_agent, doc_review_agent], - swarm_type="SequentialWorkflow", -) - -corporate_swarm = SwarmRouter( - name="corporate-practice", - description="Handle business and corporate legal matters", - agents=[corporate_agent, paralegal_agent], - swarm_type="SequentialWorkflow", -) - -ip_swarm = SwarmRouter( - name="ip-practice", - description="Handle intellectual property matters", - agents=[ip_agent, paralegal_agent], - swarm_type="SequentialWorkflow", -) - -employment_swarm = SwarmRouter( - name="employment-practice", - description="Handle employment and labor law matters", - agents=[employment_agent, paralegal_agent], - swarm_type="SequentialWorkflow", +sales_agent2 = Agent( + agent_name="Sales Agent 2 - Cost Saving Specialist", + system_prompt="You're Sales Agent 2, your purpose is to generate sales for a company by emphasizing the cost savings of using swarms of agents!", + agent_description="Generate sales by emphasizing cost savings!", + llm=llm, + max_loops=1, + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + context_length=1000, ) -# Cross-functional Swarm Router -m_and_a_swarm = SwarmRouter( - name="mergers-acquisitions", - description="Handle mergers and acquisitions", - agents=[ - corporate_agent, - ip_agent, - employment_agent, - doc_review_agent, - ], - swarm_type="ConcurrentWorkflow", +sales_agent3 = Agent( + agent_name="Sales Agent 3 - Efficiency Specialist", + system_prompt="You're Sales Agent 3, your purpose is to generate sales for a company by highlighting the efficiency and accuracy of our swarms of agents in accounting processes!", + agent_description="Generate sales by highlighting efficiency and accuracy!", + llm=llm, + max_loops=1, + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + context_length=1000, ) -dispute_swarm = SwarmRouter( - name="dispute-resolution", - description="Handle complex disputes requiring multiple specialties", - agents=[litigation_agent, corporate_agent, doc_review_agent], - swarm_type="ConcurrentWorkflow", -) +# Initialize the swarm with sales agents +sales_swarm = RoundRobinSwarm(agents=[sales_agent1, sales_agent2, sales_agent3], verbose=True) +# Define a sales task +task = "Generate a sales email for an accountant firm executive to sell swarms of agents to automate their accounting processes." -hybrid_hiearchical_swarm = HybridHierarchicalClusterSwarm( - name="hybrid-hiearchical-swarm", - description="A hybrid hiearchical swarm that uses a hybrid hiearchical peer model to solve complex tasks.", - swarms=[ - litigation_swarm, - corporate_swarm, - ip_swarm, - employment_swarm, - m_and_a_swarm, - dispute_swarm, - ], - max_loops=1, - router_agent_model_name="gpt-4o-mini", -) +# Distribute sales tasks to different agents +for _ in range(5): # Repeat the task 5 times + results = sales_swarm.run(task) + print("Sales generated:", results) +``` -if __name__ == "__main__": - hybrid_hiearchical_swarm.run( - "What is the best way to file for a patent? for ai technology " - ) -``` +## Conclusion --------------------------------------------------- +The RoundRobinSwarm class provides a robust and flexible framework for managing tasks among multiple agents in a fair and efficient manner. This class is especially useful in environments where tasks need to be distributed evenly among a group of agents, ensuring that all tasks are handled timely and effectively. Through the round-robin algorithm, each agent in the swarm is guaranteed an equal opportunity to contribute to the overall task, promoting efficiency and collaboration. -# File: swarms/structs/index.md -# Enterprise-Grade and Production Ready Agents +-------------------------------------------------- -Swarms is an enterprise grade and production ready multi-agent collaboration framework that enables you to orchestrate many agents to work collaboratively at scale to automate real-world activities. +# File: swarms\structs\sequential_workflow.md -| **Feature** | **Description** | **Performance Impact** | **Documentation Link** | -|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------|-------------------------------| -| Models | Pre-trained models that can be utilized for various tasks within the swarm framework. | ⭐⭐⭐ | [Documentation](https://docs.swarms.world/en/latest/swarms/models/) | -| Models APIs | APIs to interact with and utilize the models effectively, providing interfaces for inference, training, and fine-tuning. | ⭐⭐⭐ | [Documentation](https://docs.swarms.world/en/latest/swarms/models/) | -| Agents with Tools | Agents equipped with specialized tools to perform specific tasks more efficiently, such as data processing, analysis, or interaction with external systems. | ⭐⭐⭐⭐ | [Documentation](https://medium.com/@kyeg/the-swarms-tool-system-functions-pydantic-basemodels-as-tools-and-radical-customization-c2a2e227b8ca) | -| Agents with Memory | Mechanisms for agents to store and recall past interactions, improving learning and adaptability over time. | ⭐⭐⭐⭐ | [Documentation](https://github.com/kyegomez/swarms/blob/master/examples/structs/agent/agent_with_longterm_memory.py) | -| Multi-Agent Orchestration | Coordination of multiple agents to work together seamlessly on complex tasks, leveraging their individual strengths to achieve higher overall performance. | ⭐⭐⭐⭐⭐ | [Documentation]() | +# SequentialWorkflow Documentation -The performance impact is rated on a scale from one to five stars, with multi-agent orchestration being the highest due to its ability to combine the strengths of multiple agents and optimize task execution. +**Overview:** +A Sequential Swarm architecture processes tasks in a linear sequence. Each agent completes its task before passing the result to the next agent in the chain. This architecture ensures orderly processing and is useful when tasks have dependencies. [Learn more here in the docs:](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/) ----- +**Use-Cases:** -## Install 💻 -`$ pip3 install -U swarms` +- Workflows where each step depends on the previous one, such as assembly lines or sequential data processing. ---- +- Scenarios requiring strict order of operations. -# Usage Examples 🤖 +```mermaid +graph TD + A[First Agent] --> B[Second Agent] + B --> C[Third Agent] + C --> D[Fourth Agent] +``` -### Google Collab Example -Run example in Collab: -Open In Colab - +## Attributes ---- +| Attribute | Type | Description | +|------------------|---------------|--------------------------------------------------| +| `agents` | `List[Agent]` | The list of agents in the workflow. | +| `flow` | `str` | A string representing the order of agents. | +| `agent_rearrange`| `AgentRearrange` | Manages the dynamic execution of agents. | -## `Agents` -A fully plug-and-play autonomous agent powered by an LLM extended by a long-term memory database, and equipped with function calling for tool usage! By passing in an LLM, you can create a fully autonomous agent with extreme customization and reliability, ready for real-world task automation! +## Methods -Features: +### `__init__(self, agents: List[Agent] = None, max_loops: int = 1, *args, **kwargs)` -✅ Any LLM / Any framework +The constructor initializes the `SequentialWorkflow` object. -✅ Extremely customize-able with max loops, autosaving, import docs (PDFS, TXT, CSVs, etc), tool usage, etc etc +- **Parameters:** + - `agents` (`List[Agent]`, optional): The list of agents in the workflow. Defaults to `None`. + - `max_loops` (`int`, optional): The maximum number of loops to execute the workflow. Defaults to `1`. + - `*args`: Variable length argument list. + - `**kwargs`: Arbitrary keyword arguments. -✅ Long term memory database with RAG (ChromaDB, Pinecone, Qdrant) +### `run(self, task: str) -> str` -```python -import os +Runs the specified task through the agents in the dynamically constructed flow. -from dotenv import load_dotenv +- **Parameters:** + - `task` (`str`): The task for the agents to execute. -# Import the OpenAIChat model and the Agent struct -from swarms import Agent -from swarm_models import OpenAIChat +- **Returns:** + - `str`: The final result after processing through all agents. -# Load the environment variables -load_dotenv() +## **Usage Example:** -# Get the API key from the environment -api_key = os.environ.get("OPENAI_API_KEY") +```python -# Initialize the language model -llm = OpenAIChat( - temperature=0.5, model_name="gpt-4", openai_api_key=api_key, max_tokens=4000 +from swarms import Agent, SequentialWorkflow + +# Initialize agents for individual tasks +agent1 = Agent( + agent_name="ICD-10 Code Analyzer", + system_prompt="Analyze medical data and provide relevant ICD-10 codes.", + model_name="gpt-4o", + max_loops=1, +) +agent2 = Agent( + agent_name="ICD-10 Code Summarizer", + system_prompt="Summarize the findings and suggest ICD-10 codes.", + model_name="gpt-4o", + max_loops=1, ) +# Create the Sequential workflow +workflow = SequentialWorkflow( + agents=[agent1, agent2], max_loops=1, verbose=False +) -## Initialize the workflow -agent = Agent(llm=llm, max_loops=1, autosave=True, dashboard=True) +# Run the workflow +workflow.run( + "Analyze the medical report and provide the appropriate ICD-10 codes." +) -# Run the workflow on a task -agent.run("Generate a 10,000 word blog on health and wellness.") ``` +This example initializes a `SequentialWorkflow` with three agents and executes a task, printing the final result. -### `Agent` + Long Term Memory -`Agent` equipped with quasi-infinite long term memory. Great for long document understanding, analysis, and retrieval. - -```python -from swarms import Agent -from swarm_models import OpenAIChat -from swarms_memory import ChromaDB # Copy and paste the code and put it in your own local directory. +## **Notes:** -# Making an instance of the ChromaDB class -memory = ChromaDB( - metric="cosine", - n_results=3, - output_dir="results", - docs_folder="docs", -) +- Logs the task execution process and handles any exceptions that occur during the task execution. -# Initializing the agent with the Gemini instance and other parameters -agent = Agent( - agent_name="Covid-19-Chat", - agent_description=( - "This agent provides information about COVID-19 symptoms." - ), - llm=OpenAIChat(), - max_loops="auto", - autosave=True, - verbose=True, - long_term_memory=memory, - stopping_condition="finish", -) +### Logging and Error Handling -# Defining the task and image path -task = ("What are the symptoms of COVID-19?",) +The `run` method includes logging to track the execution flow and captures errors to provide detailed information in case of failures. This is crucial for debugging and ensuring smooth operation of the workflow. -# Running the agent with the specified task and image -out = agent.run(task) -print(out) +## Additional Tips -``` +- Ensure that the agents provided to the `SequentialWorkflow` are properly initialized and configured to handle the tasks they will receive. +- The `max_loops` parameter can be used to control how many times the workflow should be executed, which is useful for iterative processes. -### `Agent` ++ Long Term Memory ++ Tools! -An LLM equipped with long term memory and tools, a full stack agent capable of automating all and any digital tasks given a good prompt. +- Utilize the logging information to monitor and debug the task execution process. -```python -from swarms import Agent, ChromaDB, OpenAIChat -# Making an instance of the ChromaDB class -memory = ChromaDB( - metric="cosine", - n_results=3, - output_dir="results", - docs_folder="docs", -) +-------------------------------------------------- -# Initialize a tool -def search_api(query: str): - # Add your logic here - return query +# File: swarms\structs\spreadsheet_swarm.md -# Initializing the agent with the Gemini instance and other parameters -agent = Agent( - agent_name="Covid-19-Chat", - agent_description=( - "This agent provides information about COVID-19 symptoms." - ), - llm=OpenAIChat(), - max_loops="auto", - autosave=True, - verbose=True, - long_term_memory=memory, - stopping_condition="finish", - tools=[search_api], -) +# SpreadSheetSwarm Documentation -# Defining the task and image path -task = ("What are the symptoms of COVID-19?",) +--- -# Running the agent with the specified task and image -out = agent.run(task) -print(out) +## Class Definition +```python +class SpreadSheetSwarm: ``` - -### Devin -Implementation of Devin in less than 90 lines of code with several tools: -terminal, browser, and edit files. +## Full Path ```python -from swarms import Agent -from swarm_models import Anthropic -import subprocess +from swarms.structs.spreadsheet_swarm import SpreadSheetSwarm +``` -# Model -llm = Anthropic( - temperature=0.1, -) +### Attributes -# Tools -def terminal( - code: str, -): - """ - Run code in the terminal. +The `SpreadSheetSwarm` class contains several attributes that define its behavior and configuration. These attributes are initialized in the constructor (`__init__` method) and are used throughout the class to manage the swarm's operations. - Args: - code (str): The code to run in the terminal. +| Attribute | Type | Description | +|--------------------|-----------------------------------|---------------------------------------------------------------------------------------------| +| `name` | `str` | The name of the swarm. | +| `description` | `str` | A description of the swarm's purpose. | +| `agents` | `Union[Agent, List[Agent]]` | The agents participating in the swarm. Can be a single agent or a list of agents. | +| `autosave_on` | `bool` | Flag indicating whether autosave is enabled. | +| `save_file_path` | `str` | The file path where the swarm data will be saved. | +| `task_queue` | `queue.Queue` | The queue that stores tasks to be processed by the agents. | +| `lock` | `threading.Lock` | A lock used for thread synchronization to prevent race conditions. | +| `metadata` | `SwarmRunMetadata` | Metadata for the swarm run, including start time, end time, tasks completed, and outputs. | +| `run_all_agents` | `bool` | Flag indicating whether to run all agents or just one. | +| `max_loops` | `int` | The number of times to repeat the task. | +| `workspace_dir` | `str` | The directory where the workspace is located, retrieved from environment variables. | - Returns: - str: The output of the code. - """ - out = subprocess.run( - code, shell=True, capture_output=True, text=True - ).stdout - return str(out) +### Parameters -def browser(query: str): - """ - Search the query in the browser with the `browser` tool. +- **`name`** (`str`, optional): The name of the swarm. Default is `"Spreadsheet-Swarm"`. +- **`description`** (`str`, optional): A brief description of the swarm. Default is `"A swarm that processes tasks from a queue using multiple agents on different threads."`. +- **`agents`** (`Union[Agent, List[Agent]]`, optional): The agents participating in the swarm. Default is an empty list. +- **`autosave_on`** (`bool`, optional): A flag to indicate if autosave is enabled. Default is `True`. +- **`save_file_path`** (`str`, optional): The file path where swarm data will be saved. Default is `"spreedsheet_swarm.csv"`. +- **`run_all_agents`** (`bool`, optional): Flag to determine if all agents should run. Default is `True`. +- **`max_loops`** (`int`, optional): The number of times to repeat the task. Default is `1`. +- **`workspace_dir`** (`str`, optional): The directory where the workspace is located. Default is retrieved from environment variable `WORKSPACE_DIR`. - Args: - query (str): The query to search in the browser. +### Constructor (`__init__`) - Returns: - str: The search results. - """ - import webbrowser +The constructor initializes the `SpreadSheetSwarm` with the provided parameters. It sets up the task queue, locks for thread synchronization, and initializes the metadata. - url = f"https://www.google.com/search?q={query}" - webbrowser.open(url) - return f"Searching for {query} in the browser." +--- -def create_file(file_path: str, content: str): - """ - Create a file using the file editor tool. +## Methods - Args: - file_path (str): The path to the file. - content (str): The content to write to the file. +### `reliability_check` - Returns: - str: The result of the file creation operation. - """ - with open(file_path, "w") as file: - file.write(content) - return f"File {file_path} created successfully." +```python +def reliability_check(self): +``` -def file_editor(file_path: str, mode: str, content: str): - """ - Edit a file using the file editor tool. +#### Description - Args: - file_path (str): The path to the file. - mode (str): The mode to open the file in. - content (str): The content to write to the file. +The `reliability_check` method performs a series of checks to ensure that the swarm is properly configured before it begins processing tasks. It verifies that there are agents available and that a valid file path is provided for saving the swarm's data. If any of these checks fail, an exception is raised. - Returns: - str: The result of the file editing operation. - """ - with open(file_path, mode) as file: - file.write(content) - return f"File {file_path} edited successfully." +#### Raises +- **`ValueError`**: Raised if no agents are provided or if no save file path is specified. -# Agent -agent = Agent( - agent_name="Devin", - system_prompt=( - "Autonomous agent that can interact with humans and other" - " agents. Be Helpful and Kind. Use the tools provided to" - " assist the user. Return all code in markdown format." - ), - llm=llm, - max_loops="auto", - autosave=True, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - interactive=True, - tools=[terminal, browser, file_editor, create_file], - code_interpreter=True, - # streaming=True, -) +#### Example -# Run the agent -out = agent("Create a new file for a plan to take over the world.") -print(out) +```python +swarm = SpreadSheetSwarm(agents=[agent1, agent2]) +swarm.reliability_check() ``` +--- -### `Agent`with Pydantic BaseModel as Output Type -The following is an example of an agent that intakes a pydantic basemodel and outputs it at the same time: +### `run` ```python -from pydantic import BaseModel, Field -from swarms import Agent -from swarm_models import Anthropic - +def run(self, task: str, *args, **kwargs): +``` -# Initialize the schema for the person's information -class Schema(BaseModel): - name: str = Field(..., title="Name of the person") - agent: int = Field(..., title="Age of the person") - is_student: bool = Field(..., title="Whether the person is a student") - courses: list[str] = Field( - ..., title="List of courses the person is taking" - ) +#### Description +The `run` method starts the task processing using the swarm. Depending on the configuration, it can either run all agents or a specific subset of them. The method tracks the start and end times of the task, executes the task multiple times if specified, and logs the results. -# Convert the schema to a JSON string -tool_schema = Schema( - name="Tool Name", - agent=1, - is_student=True, - courses=["Course1", "Course2"], -) +#### Parameters -# Define the task to generate a person's information -task = "Generate a person's information based on the following schema:" +- **`task`** (`str`): The task to be executed by the swarm. +- **`*args`**: Additional positional arguments to pass to the agents. +- **`**kwargs`**: Additional keyword arguments to pass to the agents. -# Initialize the agent -agent = Agent( - agent_name="Person Information Generator", - system_prompt=( - "Generate a person's information based on the following schema:" - ), - # Set the tool schema to the JSON string -- this is the key difference - tool_schema=tool_schema, - llm=Anthropic(), - max_loops=3, - autosave=True, - dashboard=False, - streaming_on=True, - verbose=True, - interactive=True, - # Set the output type to the tool schema which is a BaseModel - output_type=tool_schema, # or dict, or str - metadata_output_type="json", - # List of schemas that the agent can handle - list_base_models=[tool_schema], - function_calling_format_type="OpenAI", - function_calling_type="json", # or soon yaml -) +#### Example -# Run the agent to generate the person's information -generated_data = agent.run(task) +```python +swarm = SpreadSheetSwarm(agents=[agent1, agent2]) +swarm.run("Process Data") +``` -# Print the generated data -print(f"Generated data: {generated_data}") +--- +### `export_to_json` +```python +def export_to_json(self): ``` -### Multi Modal Autonomous Agent -Run the agent with multiple modalities useful for various real-world tasks in manufacturing, logistics, and health. +#### Description -```python -# Description: This is an example of how to use the Agent class to run a multi-modal workflow -import os +The `export_to_json` method generates a JSON representation of the swarm's metadata. This can be useful for exporting the results to an external system or for logging purposes. -from dotenv import load_dotenv +#### Returns -from swarm_models.gpt4_vision_api import GPT4VisionAPI -from swarms.structs import Agent +- **`str`**: The JSON representation of the swarm's metadata. -# Load the environment variables -load_dotenv() +#### Example -# Get the API key from the environment -api_key = os.environ.get("OPENAI_API_KEY") +```python +json_data = swarm.export_to_json() +print(json_data) +``` -# Initialize the language model -llm = GPT4VisionAPI( - openai_api_key=api_key, - max_tokens=500, -) +--- -# Initialize the task -task = ( - "Analyze this image of an assembly line and identify any issues such as" - " misaligned parts, defects, or deviations from the standard assembly" - " process. IF there is anything unsafe in the image, explain why it is" - " unsafe and how it could be improved." -) -img = "assembly_line.jpg" +### `data_to_json_file` -## Initialize the workflow -agent = Agent( - llm=llm, max_loops="auto", autosave=True, dashboard=True, multi_modal=True -) +```python +def data_to_json_file(self): +``` -# Run the workflow on a task -agent.run(task=task, img=img) +#### Description + +The `data_to_json_file` method saves the swarm's metadata as a JSON file in the specified workspace directory. The file name is generated using the swarm's name and run ID. + +#### Example + +```python +swarm.data_to_json_file() ``` ----- +--- +### `_track_output` --------------------------------------------------- +```python +def _track_output(self, agent: Agent, task: str, result: str): +``` -# File: swarms/structs/majorityvoting.md +#### Description -# MajorityVoting Module Documentation +The `_track_output` method is used internally to record the results of tasks executed by the agents. It updates the metadata with the completed tasks and their results. -The `MajorityVoting` module provides a mechanism for performing majority voting among a group of agents. Majority voting is a decision rule that selects the option which has the majority of votes. This is particularly useful in systems where multiple agents provide responses to a query, and the most common response needs to be identified as the final output. +#### Parameters -## Architecture +- **`agent`** (`Agent`): The agent that executed the task. +- **`task`** (`str`): The task that was executed. +- **`result`** (`str`): The result of the task execution. -```mermaid -graph TD - A[MajorityVoting System] --> B[Initialize Agents] - B --> C[Process Task] - C --> D{Execution Mode} - D --> E[Single Task] - D --> F[Batch Tasks] - D --> G[Concurrent Tasks] - D --> H[Async Tasks] - E --> I[Run Agents] - F --> I - G --> I - H --> I - I --> J[Collect Responses] - J --> K[Consensus Analysis] - K --> L{Consensus Agent?} - L -->|Yes| M[Use Consensus Agent] - L -->|No| N[Use Last Agent] - M --> O[Final Output] - N --> O - O --> P[Save Conversation] +#### Example + +```python +swarm._track_output(agent1, "Process Data", "Success") ``` -### Key Concepts +--- -- **Majority Voting**: A method to determine the most common response from a set of answers. -- **Agents**: Entities (e.g., models, algorithms) that provide responses to tasks or queries. -- **Output Parser**: A function that processes the responses from the agents before performing the majority voting. -- **Consensus Agent**: An optional agent that analyzes the responses from all agents to determine the final consensus. -- **Conversation History**: A record of all agent interactions and responses during the voting process. +### `_save_to_csv` -## Class Definition: `MajorityVoting` +```python +def _save_to_csv(self): +``` -### Parameters +#### Description -| Parameter | Type | Description | -|------------------|----------------|-----------------------------------------------------------------------------| -| `name` | `str` | Name of the majority voting system. Default is "MajorityVoting". | -| `description` | `str` | Description of the system. Default is "A majority voting system for agents". | -| `agents` | `List[Agent]` | A list of agents to be used in the majority voting system. | -| `output_parser` | `Callable` | Function to parse agent outputs. Default is `majority_voting` function. | -| `consensus_agent`| `Agent` | Optional agent for analyzing consensus among responses. | -| `autosave` | `bool` | Whether to autosave conversations. Default is `False`. | -| `verbose` | `bool` | Whether to enable verbose logging. Default is `False`. | -| `max_loops` | `int` | Maximum number of voting loops. Default is 1. | +The `_save_to_csv` method saves the swarm's metadata to a CSV file. It logs each task and its result before writing them to the file. The file is saved in the location specified by `save_file_path`. -### Methods +#### Example -#### `run(task: str, correct_answer: str, *args, **kwargs) -> List[Any]` +```python +swarm._save_to_csv() +``` -Runs the majority voting system for a single task. +--- -**Parameters:** -- `task` (str): The task to be performed by the agents -- `correct_answer` (str): The correct answer for evaluation -- `*args`, `**kwargs`: Additional arguments +## Usage Examples -**Returns:** -- List[Any]: The conversation history as a string, including the majority vote +### Example 1: Basic Swarm Initialization -#### `batch_run(tasks: List[str], *args, **kwargs) -> List[Any]` +```python +import os -Runs multiple tasks in sequence. +from swarms import Agent +from swarm_models import OpenAIChat +from swarms.prompts.finance_agent_sys_prompt import ( + FINANCIAL_AGENT_SYS_PROMPT, +) +from swarms.structs.spreadsheet_swarm import SpreadSheetSwarm -**Parameters:** -- `tasks` (List[str]): List of tasks to be performed -- `*args`, `**kwargs`: Additional arguments +# Example usage: +api_key = os.getenv("OPENAI_API_KEY") -**Returns:** -- List[Any]: List of majority votes for each task +# Model +model = OpenAIChat( + openai_api_key=api_key, model_name="gpt-4o-mini", temperature=0.1 +) -#### `run_concurrently(tasks: List[str], *args, **kwargs) -> List[Any]` -Runs multiple tasks concurrently using thread pooling. +# Initialize your agents (assuming the Agent class and model are already defined) +agents = [ + Agent( + agent_name=f"Financial-Analysis-Agent-spreesheet-swarm:{i}", + system_prompt=FINANCIAL_AGENT_SYS_PROMPT, + llm=model, + max_loops=1, + dynamic_temperature_enabled=True, + saved_state_path="finance_agent.json", + user_name="swarms_corp", + retry_attempts=1, + ) + for i in range(10) +] -**Parameters:** -- `tasks` (List[str]): List of tasks to be performed -- `*args`, `**kwargs`: Additional arguments +# Create a Swarm with the list of agents +swarm = SpreadSheetSwarm( + name="Finance-Spreadsheet-Swarm", + description="A swarm that processes tasks from a queue using multiple agents on different threads.", + agents=agents, + autosave_on=True, + save_file_path="financial_spreed_sheet_swarm_demo.csv", + run_all_agents=False, + max_loops=1, +) -**Returns:** -- List[Any]: List of majority votes for each task +# Run the swarm +swarm.run( + task="Analyze the states with the least taxes for LLCs. Provide an overview of all tax rates and add them with a comprehensive analysis" +) -#### `run_async(tasks: List[str], *args, **kwargs) -> List[Any]` +``` -Runs multiple tasks asynchronously using asyncio. +### Example 2: QR Code Generator -**Parameters:** -- `tasks` (List[str]): List of tasks to be performed -- `*args`, `**kwargs`: Additional arguments +```python +import os +from swarms import Agent +from swarm_models import OpenAIChat +from swarms.structs.spreadsheet_swarm import SpreadSheetSwarm -**Returns:** -- List[Any]: List of majority votes for each task +# Define custom system prompts for QR code generation +QR_CODE_AGENT_1_SYS_PROMPT = """ +You are a Python coding expert. Your task is to write a Python script to generate a QR code for the link: https://lu.ma/jjc1b2bo. The code should save the QR code as an image file. +""" -## Usage Examples +QR_CODE_AGENT_2_SYS_PROMPT = """ +You are a Python coding expert. Your task is to write a Python script to generate a QR code for the link: https://github.com/The-Swarm-Corporation/Cookbook. The code should save the QR code as an image file. +""" -### Example 1: Basic Single Task Execution with Modern LLMs +# Example usage: +api_key = os.getenv("OPENAI_API_KEY") -```python -from swarms import Agent, MajorityVoting +# Model +model = OpenAIChat( + openai_api_key=api_key, model_name="gpt-4o-mini", temperature=0.1 +) -# Initialize multiple agents with different specialties +# Initialize your agents for QR code generation agents = [ Agent( - agent_name="Financial-Analysis-Agent", - agent_description="Personal finance advisor focused on market analysis", - system_prompt="You are a financial advisor specializing in market analysis and investment opportunities.", + agent_name="QR-Code-Generator-Agent-Luma", + system_prompt=QR_CODE_AGENT_1_SYS_PROMPT, + llm=model, max_loops=1, - model_name="gpt-4o" + dynamic_temperature_enabled=True, + saved_state_path="qr_code_agent_luma.json", + user_name="swarms_corp", + retry_attempts=1, ), Agent( - agent_name="Risk-Assessment-Agent", - agent_description="Risk analysis and portfolio management expert", - system_prompt="You are a risk assessment expert focused on evaluating investment risks and portfolio diversification.", + agent_name="QR-Code-Generator-Agent-Cookbook", + system_prompt=QR_CODE_AGENT_2_SYS_PROMPT, + llm=model, max_loops=1, - model_name="gpt-4o" + dynamic_temperature_enabled=True, + saved_state_path="qr_code_agent_cookbook.json", + user_name="swarms_corp", + retry_attempts=1, ), - Agent( - agent_name="Tech-Investment-Agent", - agent_description="Technology sector investment specialist", - system_prompt="You are a technology investment specialist focused on AI, emerging tech, and growth opportunities.", - max_loops=1, - model_name="gpt-4o" - ) ] - -consensus_agent = Agent( - agent_name="Consensus-Agent", - agent_description="Consensus agent focused on analyzing investment advice", - system_prompt="You are a consensus agent focused on analyzing investment advice and providing a final answer.", +# Create a Swarm with the list of agents +swarm = SpreadSheetSwarm( + name="QR-Code-Generation-Swarm", + description="A swarm that generates Python scripts to create QR codes for specific links.", + agents=agents, + autosave_on=True, + save_file_path="qr_code_generation_results.csv", + run_all_agents=False, max_loops=1, - model_name="gpt-4o" ) -# Create majority voting system -majority_voting = MajorityVoting( - name="Investment-Advisory-System", - description="Multi-agent system for investment advice", - agents=agents, - verbose=True, - consensus_agent=consensus_agent +# Run the swarm +swarm.run( + task="Generate Python scripts to create QR codes for the provided links and save them as image files." ) +``` -# Run the analysis with majority voting -result = majority_voting.run( - task="Create a table of super high growth opportunities for AI. I have $40k to invest in ETFs, index funds, and more. Please create a table in markdown.", - correct_answer="" # Optional evaluation metric -) -print(result) +## Example 3: Social Media Marketing -``` +```python -## Batch Execution +import os +from swarms import Agent +from swarm_models import OpenAIChat +from swarms.structs.spreadsheet_swarm import SpreadSheetSwarm -```python -from swarms import Agent, MajorityVoting +# Define custom system prompts for each social media platform +TWITTER_AGENT_SYS_PROMPT = """ +You are a Twitter marketing expert. Your task is to create engaging, concise tweets and analyze trends to maximize engagement. Consider hashtags, timing, and content relevance. +""" -# Initialize multiple agents with different specialties +INSTAGRAM_AGENT_SYS_PROMPT = """ +You are an Instagram marketing expert. Your task is to create visually appealing and engaging content, including captions and hashtags, tailored to a specific audience. +""" + +FACEBOOK_AGENT_SYS_PROMPT = """ +You are a Facebook marketing expert. Your task is to craft posts that are optimized for engagement and reach on Facebook, including using images, links, and targeted messaging. +""" + +EMAIL_AGENT_SYS_PROMPT = """ +You are an Email marketing expert. Your task is to write compelling email campaigns that drive conversions, focusing on subject lines, personalization, and call-to-action strategies. +""" + +# Example usage: +api_key = os.getenv("OPENAI_API_KEY") + +# Model +model = OpenAIChat( + openai_api_key=api_key, model_name="gpt-4o-mini", temperature=0.1 +) + +# Initialize your agents for different social media platforms agents = [ Agent( - agent_name="Financial-Analysis-Agent", - agent_description="Personal finance advisor focused on market analysis", - system_prompt="You are a financial advisor specializing in market analysis and investment opportunities.", + agent_name="Twitter-Marketing-Agent", + system_prompt=TWITTER_AGENT_SYS_PROMPT, + llm=model, max_loops=1, - model_name="gpt-4o" + dynamic_temperature_enabled=True, + saved_state_path="twitter_agent.json", + user_name="swarms_corp", + retry_attempts=1, ), Agent( - agent_name="Risk-Assessment-Agent", - agent_description="Risk analysis and portfolio management expert", - system_prompt="You are a risk assessment expert focused on evaluating investment risks and portfolio diversification.", + agent_name="Instagram-Marketing-Agent", + system_prompt=INSTAGRAM_AGENT_SYS_PROMPT, + llm=model, max_loops=1, - model_name="gpt-4o" + dynamic_temperature_enabled=True, + saved_state_path="instagram_agent.json", + user_name="swarms_corp", + retry_attempts=1, ), Agent( - agent_name="Tech-Investment-Agent", - agent_description="Technology sector investment specialist", - system_prompt="You are a technology investment specialist focused on AI, emerging tech, and growth opportunities.", + agent_name="Facebook-Marketing-Agent", + system_prompt=FACEBOOK_AGENT_SYS_PROMPT, + llm=model, max_loops=1, - model_name="gpt-4o" - ) + dynamic_temperature_enabled=True, + saved_state_path="facebook_agent.json", + user_name="swarms_corp", + retry_attempts=1, + ), + Agent( + agent_name="Email-Marketing-Agent", + system_prompt=EMAIL_AGENT_SYS_PROMPT, + llm=model, + max_loops=1, + dynamic_temperature_enabled=True, + saved_state_path="email_agent.json", + user_name="swarms_corp", + retry_attempts=1, + ), ] - -consensus_agent = Agent( - agent_name="Consensus-Agent", - agent_description="Consensus agent focused on analyzing investment advice", - system_prompt="You are a consensus agent focused on analyzing investment advice and providing a final answer.", - max_loops=1, - model_name="gpt-4o" -) - -# Create majority voting system -majority_voting = MajorityVoting( - name="Investment-Advisory-System", - description="Multi-agent system for investment advice", +# Create a Swarm with the list of agents +swarm = SpreadSheetSwarm( + name="Social-Media-Marketing-Swarm", + description="A swarm that processes social media marketing tasks using multiple agents on different threads.", agents=agents, - verbose=True, - consensus_agent=consensus_agent + autosave_on=True, + save_file_path="social_media_marketing_spreadsheet.csv", + run_all_agents=False, + max_loops=2, ) -# Run the analysis with majority voting -result = majority_voting.batch_run( - task="Create a table of super high growth opportunities for AI. I have $40k to invest in ETFs, index funds, and more. Please create a table in markdown.", - correct_answer="" # Optional evaluation metric +# Run the swarm +swarm.run( + task="Create posts to promote hack nights in miami beach for developers, engineers, and tech enthusiasts. Include relevant hashtags, images, and engaging captions." ) - -print(result) - - ``` --------------------------------------------------- +--- -# File: swarms/structs/malt.md +## Additional Information and Tips -# MALT: Multi-Agent Learning Task Framework +- **Thread Synchronization**: When working with multiple agents in a concurrent environment, it's crucial to ensure that access to shared resources is properly synchronized using locks to avoid race conditions. -## Overview +- **Autosave Feature**: If you enable the `autosave_on` flag, ensure that the file path provided is correct and writable. This feature is handy for long-running tasks where you want to periodically save the state. -MALT (Multi-Agent Learning Task) is a sophisticated orchestration framework that coordinates multiple specialized AI agents to tackle complex tasks through structured conversations. Inspired by the principles outlined in the [MALT research paper](https://arxiv.org/pdf/2412.01928), this implementation provides a reliable, extensible system for multi-agent collaboration. +- **Error Handling** -The framework is designed around a three-agent architecture: +: Implementing proper error handling within your agents can prevent the swarm from crashing during execution. Consider catching exceptions in the `run` method and logging errors appropriately. -1. **Creator Agent**: Generates initial content or solutions +- **Custom Agents**: You can extend the `Agent` class to create custom agents that perform specific tasks tailored to your application's needs. -2. **Verifier Agent**: Critically evaluates the creator's output +--- -3. **Refiner Agent**: Improves the solution based on verifier feedback +## References and Resources -This collaborative approach enables high-quality outputs for complex tasks by combining the strengths of multiple specialized agents, each focused on a different aspect of the problem-solving process. +- [Python's `queue` module](https://docs.python.org/3/library/queue.html) +- [Python's `threading` module](https://docs.python.org/3/library/threading.html) +- [CSV File Handling in Python](https://docs.python.org/3/library/csv.html) +- [JSON Handling in Python](https://docs.python.org/3/library/json.html) -## How It Works -The MALT framework follows a structured workflow: -1. A task is submitted to the system -2. The Creator Agent generates an initial solution -3. Multiple instances of the Verifier Agent independently evaluate the solution -4. Multiple instances of the Refiner Agent improve the solution based on verification feedback -5. The final refined output is returned +-------------------------------------------------- -This process can be configured to run for multiple iterations, with each cycle potentially improving the quality of the output. The system maintains a conversation history, tracking interactions between agents throughout the workflow. +# File: swarms\structs\swarm_matcher.md -### Key Components +# SwarmMatcher -- **Agent**: Represents an individual AI agent with specific capabilities and responsibilities -- **Conversation**: Manages the interaction history between agents -- **MALT Orchestrator**: Coordinates the workflow and manages agent interactions -- **Concurrency Support**: Enables parallel execution of multiple agent instances +SwarmMatcher is a tool for automatically matching tasks to the most appropriate swarm type based on their semantic similarity. -## Architecture Diagram +## Overview -```mermaid -flowchart TD - User[User/Client] -->|Submit Task| MALT[MALT Orchestrator] - - subgraph MALT Framework - MALT -->|Task| Creator[Creator Agent] - Creator -->|Initial Solution| Conversation[Conversation Manager] - Conversation -->|Solution| VerifierPool[Verifier Agents Pool] - - subgraph VerifierPool - Verifier1[Verifier Agent 1] - Verifier2[Verifier Agent 2] - Verifier3[Verifier Agent 3] - end - - VerifierPool -->|Verification Feedback| Conversation - Conversation -->|Solution + Feedback| RefinerPool[Refiner Agents Pool] - - subgraph RefinerPool - Refiner1[Refiner Agent 1] - Refiner2[Refiner Agent 2] - Refiner3[Refiner Agent 3] - end - - RefinerPool -->|Refined Solutions| Conversation - end - - Conversation -->|Final Output| User -``` +The SwarmMatcher utilizes transformer-based embeddings to determine the best swarm architecture for a given task. By analyzing the semantic meaning of task descriptions and comparing them to known swarm types, it can intelligently select the optimal swarm configuration for any task. -## Execution Workflow +## Workflow ```mermaid -sequenceDiagram - participant User - participant MALT - participant Creator - participant Verifiers - participant Refiners - participant Conversation - - User->>MALT: Submit task - MALT->>Creator: Process task - Creator->>Conversation: Add initial solution - - par Verification Phase - Conversation->>Verifiers: Send solution for verification - Verifiers->>Conversation: Return verification feedback +flowchart TD + A[Task Description] --> B[Generate Task Embedding] + C[Swarm Type Descriptions] --> D[Generate Swarm Type Embeddings] + B --> E[Calculate Similarity Scores] + D --> E + E --> F[Select Best Matching Swarm Type] + F --> G[Return Selected Swarm Type] + + subgraph Initialization + H[Define Swarm Types] --> I[Load Transformer Model] + I --> J[Pre-compute Swarm Type Embeddings] end - par Refinement Phase - Conversation->>Refiners: Send solution + feedback - Refiners->>Conversation: Return refined solutions + subgraph Matching Process + A --> B --> E --> F --> G end - - MALT->>Conversation: Request final output - Conversation->>MALT: Return conversation history - MALT->>User: Return final result ``` -## API Reference - -### MALT Class - -The core orchestrator that manages the multi-agent interaction process. - -#### Constructor Parameters - -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `main_agent` | `Agent` | `None` | The primary agent (Creator) responsible for generating initial solutions | -| `refiner_agent` | `Agent` | `None` | The agent that refines solutions based on verification feedback | -| `verifier_agent` | `Agent` | `None` | The agent that verifies and evaluates solutions | -| `max_loops` | `int` | `1` | Maximum number of iterations for the task execution | -| `return_list` | `bool` | `False` | Flag to return output as a list | -| `return_dict` | `bool` | `False` | Flag to return output as a dictionary | -| `agents` | `list[Agent]` | `[]` | Alternative list of agents to use in the task | -| `preset_agents` | `bool` | `True` | Use default preset agents for mathematical proofs | - -#### Methods - -| Method | Parameters | Return Type | Description | -|--------|------------|-------------|-------------| -| `reliability_check` | None | None | Validates agent configuration and parameters | -| `step` | `task: str, img: str = None, *args, **kwargs` | `str` or `list` or `dict` | Executes a single iteration of the MALT workflow | -| `run` | `task: str, img: str = None, *args, **kwargs` | `str` or `list` or `dict` | Executes the complete MALT workflow for a task | -| `run_batched` | `tasks: List[str], *args, **kwargs` | `List[str]` or `List[list]` or `List[dict]` | Sequentially processes multiple tasks | -| `run_concurrently` | `tasks: List[str], *args, **kwargs` | `concurrent.futures.Future` | Processes multiple tasks in parallel using ThreadPoolExecutor | -| `__call__` | `task: str, *args, **kwargs` | Same as `run` | Allows the MALT instance to be called as a function | -| `__str__` | None | `str` | Returns the conversation history as a string | -| `__repr__` | None | `str` | Returns the conversation history as a string | - - -## Sample Implementations - -### Default Mathematical Proof Agents - -The MALT framework includes preset agents specialized for mathematical proof generation and refinement: - -1. **Proof Creator Agent**: Generates original mathematical theorems and proofs -2. **Proof Verifier Agent**: Critically evaluates and identifies issues in mathematical proofs -3. **Proof Refiner Agent**: Improves proofs based on verification feedback - -Each agent has a carefully designed system prompt that guides its behavior and specialization. - -## Usage Examples +## Installation -### Basic Usage +SwarmMatcher is included in the Swarms package. To use it, simply import it from the library: ```python -from swarms.structs.agent import Agent -from swarms.structs.multi_agent_exec import MALT +from swarms.structs.swarm_matcher import SwarmMatcher, SwarmMatcherConfig, SwarmType +``` -# Initialize with preset mathematical proof agents -malt = MALT(preset_agents=True) +## Basic Usage -# Run a mathematical proof task -result = malt.run("Develop a theorem and proof related to prime numbers and their distribution.") +```python +from swarms.structs.swarm_matcher import swarm_matcher -print(result) +# Use the simplified function to match a task to a swarm type +swarm_type = swarm_matcher("Analyze this dataset and create visualizations") +print(f"Selected swarm type: {swarm_type}") ``` -### Custom Agents +## Advanced Usage + +For more control over the matching process, you can create and configure your own SwarmMatcher instance: ```python -from swarms.structs.agent import Agent -from swarms.structs.multi_agent_exec import MALT +from swarms.structs.swarm_matcher import SwarmMatcher, SwarmMatcherConfig, SwarmType, initialize_swarm_types -# Define custom agents -creator = Agent( - agent_name="Physics-Creator", - model_name="gpt-4o-mini", - max_loops=1, - system_prompt="You are a theoretical physicist specializing in quantum mechanics..." +# Create a configuration +config = SwarmMatcherConfig( + model_name="sentence-transformers/all-MiniLM-L6-v2", + embedding_dim=512 ) -verifier = Agent( - agent_name="Physics-Verifier", - model_name="gpt-4o-mini", - max_loops=1, - system_prompt="You are an experimental physicist who verifies theoretical claims..." -) +# Initialize the matcher +matcher = SwarmMatcher(config) -refiner = Agent( - agent_name="Physics-Communicator", - model_name="gpt-4o-mini", - max_loops=1, - system_prompt="You excel at explaining complex physics concepts to diverse audiences..." -) +# Add default swarm types +initialize_swarm_types(matcher) -# Initialize MALT with custom agents -malt = MALT( - main_agent=creator, - verifier_agent=verifier, - refiner_agent=refiner, - preset_agents=False, - max_loops=1 +# Add a custom swarm type +custom_swarm = SwarmType( + name="CustomSwarm", + description="A specialized swarm for handling specific domain tasks with expert knowledge." ) +matcher.add_swarm_type(custom_swarm) -# Run a physics explanation task -result = malt.run("Explain the quantum entanglement phenomenon and its implications.") -``` +# Find the best match for a task +best_match, score = matcher.find_best_match("Process natural language and extract key insights") +print(f"Best match: {best_match}, Score: {score}") -### Concurrent Processing +# Auto-select a swarm type +selected_swarm = matcher.auto_select_swarm("Create data visualizations from this CSV file") +print(f"Selected swarm: {selected_swarm}") +``` -```python -from swarms.structs.multi_agent_exec import MALT +## Available Swarm Types -# Initialize MALT -malt = MALT() +SwarmMatcher comes with several pre-defined swarm types: -# Define multiple tasks -tasks = [ - "Prove a theorem related to continuous functions on compact sets.", - "Develop a theorem about convergence in infinite-dimensional Hilbert spaces.", - "Create a theorem relating to measure theory and Lebesgue integration." -] +| Swarm Type | Description | +| ---------- | ----------- | +| AgentRearrange | Optimize agent order and rearrange flow for multi-step tasks, ensuring efficient task allocation and minimizing bottlenecks. | +| MixtureOfAgents | Combine diverse expert agents for comprehensive analysis, fostering a collaborative approach to problem-solving and leveraging individual strengths. | +| SpreadSheetSwarm | Collaborative data processing and analysis in a spreadsheet-like environment, facilitating real-time data sharing and visualization. | +| SequentialWorkflow | Execute tasks in a step-by-step, sequential process workflow, ensuring a logical and methodical approach to task execution. | +| ConcurrentWorkflow | Process multiple tasks or data sources concurrently in parallel, maximizing productivity and reducing processing time. | -# Process tasks concurrently -futures = malt.run_concurrently(tasks) +## API Reference -# Collect results as they complete -for future in futures: - result = future.result() - print(result) -``` +### SwarmType -## Example: Complex Mathematical Domain +A class representing a type of swarm with its name and description. -Here's an example of how MALT can generate, verify, and refine a mathematical proof: -### Input +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| name | str | The name of the swarm type | +| description | str | A detailed description of the swarm type's capabilities and ideal use cases | +| embedding | Optional[List[float]] | The generated embedding vector for this swarm type (auto-populated) | -```python -malt = MALT(preset_agents=True) -task = "Develop a theorem and rigorous proof related to the convergence properties of infinite series." -result = malt.run(task) -``` +### SwarmMatcherConfig -### Output Flow +Configuration settings for the SwarmMatcher. -1. **Creator Agent** generates a theorem and proof about conditions for absolute convergence -2. **Verifier Agents** identify issues: - - Logical gap in lemma 2 - - Missing justification for uniform convergence claim - - Imprecise definition of certain terms -3. **Refiner Agents** produce improved versions addressing these concerns -4. The final output contains the refined, rigorous mathematical proof -## Best Practices +| Parameter | Type | Default | Description | +| --------- | ---- | ------- | ----------- | +| model_name | str | "sentence-transformers/all-MiniLM-L6-v2" | The transformer model to use for embeddings | +| embedding_dim | int | 512 | The dimension of the embedding vectors | -1. **Task Specificity**: Provide clear, detailed task descriptions for optimal results -2. **Agent Specialization**: Design agent prompts to focus on specific aspects of the task -3. **Iteration Control**: Adjust `max_loops` based on task complexity -4. **Concurrent Verification**: Use multiple verifier instances for comprehensive evaluation -5. **Custom Agents**: Create domain-specific agents for specialized tasks +### SwarmMatcher -## Potential Improvements +The main class for matching tasks to swarm types. -- Autonomously create specialized agents based on task requirements -- Implement feedback loops between agents for iterative improvement -- Add support for agent-specific memory and knowledge bases -- Expand concurrency capabilities for improved performance -- Implement learning mechanisms for agent improvement over time -## References +#### Methods -- Original MALT paper: [arXiv:2412.01928](https://arxiv.org/pdf/2412.01928) -- Built on the swarms framework for multi-agent systems +##### `__init__(config: SwarmMatcherConfig)` --------------------------------------------------- +Initializes the SwarmMatcher with a configuration. -# File: swarms/structs/matrix_swarm.md +##### `get_embedding(text: str) -> np.ndarray` -# MatrixSwarm +Generates an embedding vector for a given text using the configured model. -The `MatrixSwarm` class provides a framework for managing and operating on matrices of AI agents, enabling matrix-like operations similar to linear algebra. This allows for complex agent interactions and parallel processing capabilities. +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| text | str | The text to embed | +| Returns | np.ndarray | The embedding vector | -## Overview +##### `add_swarm_type(swarm_type: SwarmType)` -`MatrixSwarm` treats AI agents as elements in a matrix, allowing for operations like addition, multiplication, and transposition. This approach enables sophisticated agent orchestration and parallel processing patterns. +Adds a swarm type to the matcher, generating an embedding for its description. -## Installation +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| swarm_type | SwarmType | The swarm type to add | -```bash -pip3 install -U swarms -``` +##### `find_best_match(task: str) -> Tuple[str, float]` -## Basic Usage +Finds the best matching swarm type for a given task. -```python -from swarms import Agent -from swarms.matrix import MatrixSwarm +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| task | str | The task description | +| Returns | Tuple[str, float] | The name of the best matching swarm type and the similarity score | -# Create a 2x2 matrix of agents -agents = [ - [Agent(agent_name="Agent-0-0"), Agent(agent_name="Agent-0-1")], - [Agent(agent_name="Agent-1-0"), Agent(agent_name="Agent-1-1")] -] +##### `auto_select_swarm(task: str) -> str` -# Initialize the matrix -matrix = MatrixSwarm(agents) -``` +Automatically selects the best swarm type for a given task. -## Class Constructor +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| task | str | The task description | +| Returns | str | The name of the selected swarm type | -```python -def __init__(self, agents: List[List[Agent]]) -``` +##### `run_multiple(tasks: List[str]) -> List[str]` -### Parameters -- `agents` (`List[List[Agent]]`): A 2D list of Agent instances representing the matrix. +Matches multiple tasks to swarm types in batch. -### Raises -- `ValueError`: If the input is not a valid 2D list of Agent instances. +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| tasks | List[str] | A list of task descriptions | +| Returns | List[str] | A list of selected swarm type names | -## Methods +##### `save_swarm_types(filename: str)` -### transpose() +Saves the registered swarm types to a JSON file. -Transposes the matrix of agents by swapping rows and columns. +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| filename | str | Path where the swarm types will be saved | -```python -def transpose(self) -> MatrixSwarm -``` +##### `load_swarm_types(filename: str)` -#### Returns -- `MatrixSwarm`: A new MatrixSwarm instance with transposed dimensions. +Loads swarm types from a JSON file. ---- +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| filename | str | Path to the JSON file containing swarm types | -### add(other) +## Examples -Performs element-wise addition of two agent matrices. +### Simple Matching ```python -def add(self, other: MatrixSwarm) -> MatrixSwarm +from swarms.structs.swarm_matcher import swarm_matcher + +# Match tasks to swarm types +tasks = [ + "Analyze this dataset and create visualizations", + "Coordinate multiple agents to tackle different aspects of a problem", + "Process these 10 PDF files in sequence", + "Handle these data processing tasks in parallel" +] + +for task in tasks: + swarm_type = swarm_matcher(task) + print(f"Task: {task}") + print(f"Selected swarm: {swarm_type}\n") ``` -#### Parameters -- `other` (`MatrixSwarm`): Another MatrixSwarm instance to add. +### Custom Swarm Types -#### Returns -- `MatrixSwarm`: A new MatrixSwarm resulting from the addition. +```python +from swarms.structs.swarm_matcher import SwarmMatcher, SwarmMatcherConfig, SwarmType -#### Raises -- `ValueError`: If matrix dimensions are incompatible. +# Create configuration and matcher +config = SwarmMatcherConfig() +matcher = SwarmMatcher(config) ---- +# Define custom swarm types +swarm_types = [ + SwarmType( + name="DataAnalysisSwarm", + description="Specialized in processing and analyzing large datasets, performing statistical analysis, and extracting insights from complex data." + ), + SwarmType( + name="CreativeWritingSwarm", + description="Optimized for creative content generation, storytelling, and producing engaging written material with consistent style and tone." + ), + SwarmType( + name="ResearchSwarm", + description="Focused on deep research tasks, synthesizing information from multiple sources, and producing comprehensive reports on complex topics." + ) +] -### scalar_multiply(scalar) +# Add swarm types +for swarm_type in swarm_types: + matcher.add_swarm_type(swarm_type) -Scales the matrix by duplicating agents along rows. +# Save the swarm types for future use +matcher.save_swarm_types("custom_swarm_types.json") -```python -def scalar_multiply(self, scalar: int) -> MatrixSwarm +# Use the matcher +task = "Research quantum computing advances in the last 5 years" +best_match = matcher.auto_select_swarm(task) +print(f"Selected swarm type: {best_match}") ``` -#### Parameters -- `scalar` (`int`): The multiplication factor. +## How It Works -#### Returns -- `MatrixSwarm`: A new MatrixSwarm with scaled dimensions. +SwarmMatcher uses a transformer-based model to generate embeddings (vector representations) of both the task descriptions and the swarm type descriptions. It then calculates the similarity between these embeddings to determine which swarm type is most semantically similar to the given task. ---- +```mermaid +sequenceDiagram + participant User + participant SwarmMatcher + participant TransformerModel + + User->>SwarmMatcher: task = "Analyze this dataset" + Note over SwarmMatcher: Initialization already complete + + SwarmMatcher->>TransformerModel: get_embedding(task) + TransformerModel-->>SwarmMatcher: task_embedding + + loop For each swarm type + SwarmMatcher->>SwarmMatcher: Calculate similarity score + Note over SwarmMatcher: score = dot_product(task_embedding, swarm_type.embedding) + end + + SwarmMatcher->>SwarmMatcher: Find best score + SwarmMatcher-->>User: "SpreadSheetSwarm" +``` -### multiply(other, inputs) +The matching process follows these steps: -Performs matrix multiplication (dot product) between two agent matrices. +1. The task description is converted to an embedding vector +2. Each swarm type's description is converted to an embedding vector +3. The similarity between the task embedding and each swarm type embedding is calculated +4. The swarm type with the highest similarity score is selected -```python -def multiply(self, other: MatrixSwarm, inputs: List[str]) -> List[List[AgentOutput]] -``` +This approach ensures that the matcher can understand the semantic meaning of tasks, not just keyword matching, resulting in more accurate swarm type selection. -#### Parameters -- `other` (`MatrixSwarm`): The second MatrixSwarm for multiplication. -- `inputs` (`List[str]`): Input queries for the agents. -#### Returns -- `List[List[AgentOutput]]`: Matrix of operation results. +-------------------------------------------------- -#### Raises -- `ValueError`: If matrix dimensions are incompatible for multiplication. +# File: swarms\structs\swarm_network.md ---- +# SwarmNetwork [WIP] -### subtract(other) +The `SwarmNetwork` class is a powerful tool for managing a pool of agents, orchestrating task distribution, and scaling resources based on workload. It is designed to handle tasks efficiently by dynamically adjusting the number of agents according to the current demand. This class also provides an optional API for interacting with the agent pool, making it accessible for integration with other systems. -Performs element-wise subtraction of two agent matrices. +### Key Features +- **Agent Pool Management**: Dynamically manage a pool of agents. +- **Task Queue Management**: Handle tasks through a queue system. +- **Agent Health Monitoring**: Monitor the health of agents. +- **Agent Pool Scaling**: Scale the agent pool up or down based on workload. +- **API**: Interact with the agent pool and task queue through a simple API. +- **Agent Deployment Options**: Run agents on threads, processes, containers, machines, or clusters. -```python -def subtract(self, other: MatrixSwarm) -> MatrixSwarm -``` +### Parameters -#### Parameters -- `other` (`MatrixSwarm`): Another MatrixSwarm to subtract. +| Parameter | Type | Default Value | Description | +|-----------------|--------------------|---------------|-----------------------------------------------------------------------------| +| name | str | None | The name of the swarm network. | +| description | str | None | A description of the swarm network. | +| agents | List[Agent] | None | A list of agents in the pool. | +| idle_threshold | float | 0.2 | The idle threshold for the agents. | +| busy_threshold | float | 0.7 | The busy threshold for the agents. | +| api_enabled | Optional[bool] | False | A flag to enable/disable the API. | +| logging_enabled | Optional[bool] | False | A flag to enable/disable logging. | +| api_on | Optional[bool] | False | A flag to enable/disable the FastAPI instance. | +| host | str | "0.0.0.0" | The host address for the FastAPI instance. | +| port | int | 8000 | The port number for the FastAPI instance. | +| swarm_callable | Optional[callable] | None | A callable to be executed by the swarm network. | +| *args | tuple | | Additional positional arguments. | +| **kwargs | dict | | Additional keyword arguments. | -#### Returns -- `MatrixSwarm`: A new MatrixSwarm resulting from the subtraction. +### Attributes ---- +| Attribute | Type | Description | +|------------------|--------------------|----------------------------------------------------------------| +| task_queue | queue.Queue | A queue for storing tasks. | +| idle_threshold | float | The idle threshold for the agents. | +| busy_threshold | float | The busy threshold for the agents. | +| agents | List[Agent] | A list of agents in the pool. | +| api_enabled | bool | A flag to enable/disable the API. | +| logging_enabled | bool | A flag to enable/disable logging. | +| host | str | The host address for the FastAPI instance. | +| port | int | The port number for the FastAPI instance. | +| swarm_callable | Optional[callable] | A callable to be executed by the swarm network. | +| agent_dict | dict | A dictionary of agents for easy access. | +| lock | threading.Lock | A lock for synchronizing access to shared resources. | -### identity(size) +## Methods -Creates an identity matrix of agents. +#### Description +Initializes a new instance of the `SwarmNetwork` class. + +#### Parameters +- `name` (str): The name of the swarm network. +- `description` (str): A description of the swarm network. +- `agents` (List[Agent]): A list of agents in the pool. +- `idle_threshold` (float): The idle threshold for the agents. +- `busy_threshold` (float): The busy threshold for the agents. +- `api_enabled` (Optional[bool]): A flag to enable/disable the API. +- `logging_enabled` (Optional[bool]): A flag to enable/disable logging. +- `api_on` (Optional[bool]): A flag to enable/disable the FastAPI instance. +- `host` (str): The host address for the FastAPI instance. +- `port` (int): The port number for the FastAPI instance. +- `swarm_callable` (Optional[callable]): A callable to be executed by the swarm network. +- `*args`: Additional positional arguments. +- `**kwargs`: Additional keyword arguments. + +### `add_task` ```python -def identity(self, size: int) -> MatrixSwarm +def add_task(self, task) ``` +#### Description +Adds a task to the task queue. + #### Parameters -- `size` (`int`): Size of the identity matrix (NxN). +- `task` (_type_): The task to be added to the queue. -#### Returns -- `MatrixSwarm`: An identity MatrixSwarm. +#### Example ---- +```python +from swarms.structs.agent import Agent +from swarms.structs.swarm_net import SwarmNetwork -### determinant() +agent = Agent() +swarm = SwarmNetwork(agents=[agent]) +swarm.add_task("task") +``` -Computes the determinant of a square agent matrix. +### `async_add_task` ```python -def determinant(self) -> Any +async def async_add_task(self, task) ``` -#### Returns -- `Any`: The determinant result. +#### Description +Adds a task to the task queue asynchronously. -#### Raises -- `ValueError`: If the matrix is not square. +#### Parameters +- `task` (_type_): The task to be added to the queue. ---- +#### Example -### save_to_file(path) +```python +from swarms.structs.agent import Agent +from swarms.structs.swarm_net import SwarmNetwork -Saves the matrix structure and metadata to a JSON file. +agent = Agent() +swarm = SwarmNetwork(agents=[agent]) +await swarm.async_add_task("task") +``` + +### `run_single_agent` ```python -def save_to_file(self, path: str) -> None +def run_single_agent(self, agent_id, task: Optional[str], *args, **kwargs) ``` +#### Description +Runs a task on a specific agent by ID. + #### Parameters -- `path` (`str`): File path for saving the matrix data. +- `agent_id` (_type_): The ID of the agent. +- `task` (str, optional): The task to be executed by the agent. +- `*args`: Additional positional arguments. +- `**kwargs`: Additional keyword arguments. -## Extended Example +#### Returns +- `_type_`: The output of the agent running the task. -Here's a comprehensive example demonstrating various MatrixSwarm operations: +#### Example ```python -from swarms import Agent -from swarms.matrix import MatrixSwarm - -# Create agents with specific configurations -agents = [ - [ - Agent( - agent_name=f"Agent-{i}-{j}", - system_prompt="Your system prompt here", - model_name="gpt-4", - max_loops=1, - verbose=True - ) for j in range(2) - ] for i in range(2) -] - -# Initialize matrix -matrix = MatrixSwarm(agents) - -# Example operations -transposed = matrix.transpose() -scaled = matrix.scalar_multiply(2) +from swarms.structs.agent import Agent +from swarms.structs.swarm_net import SwarmNetwork -# Run operations with inputs -inputs = ["Query 1", "Query 2"] -results = matrix.multiply(transposed, inputs) +# Initialize the agent +agent = Agent( + agent_name="Financial-Analysis-Agent", + llm=model, + max_loops="auto", + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + interactive=True, + # interactive=True, # Set to False to disable interactive mode + saved_state_path="finance_agent.json", + # tools=[Add your functions here# ], + # stopping_token="Stop!", + # interactive=True, + # docs_folder="docs", # Enter your folder name + # pdf_path="docs/finance_agent.pdf", + # sop="Calculate the profit for a company.", + # sop_list=["Calculate the profit for a company."], + user_name="swarms_corp", + # # docs= + # # docs_folder="docs", + retry_attempts=3, + # context_length=1000, + # tool_schema = dict + context_length=200000, + # agent_ops_on=True, + # long_term_memory=ChromaDB(docs_folder="artifacts"), +) -# Save results -matrix.save_to_file("matrix_results.json") +swarm = SwarmNetwork(agents=[agent]) +result = swarm.run_single_agent(agent.id, "task") ``` -## Output Schema - -The `AgentOutput` class defines the structure for operation results: +### `run_many_agents` ```python -class AgentOutput(BaseModel): - agent_name: str - input_query: str - output_result: Any - metadata: dict +def run_many_agents(self, task: Optional[str] = None, *args, **kwargs) -> List ``` -## Best Practices - -1. **Initialization** - - Ensure all agents in the matrix are properly configured before initialization - - Validate matrix dimensions for your use case - -2. **Operation Performance** - - Consider computational costs for large matrices - - Use appropriate batch sizes for inputs - -3. **Error Handling** - - Implement proper error handling for agent operations - - Validate inputs before matrix operations +#### Description +Runs a task on all agents in the pool. -4. **Resource Management** - - Monitor agent resource usage in large matrices - - Implement proper cleanup procedures +#### Parameters +- `task` (str, optional): The task to be executed by the agents. +- `*args`: Additional positional arguments. +- `**kwargs`: Additional keyword arguments. -## Limitations +#### Returns +- `List`: The output of all agents running the task. -- Matrix operations are constrained by the underlying agent capabilities -- Performance may vary based on agent configuration and complexity -- Resource usage scales with matrix dimensions +#### Example -## See Also +```python +from swarms.structs.agent import Agent +from swarms.structs.swarm_net import SwarmNetwork -- [Swarms Documentation](https://github.com/kyegomez/swarms) -- [Agent Class Reference](https://github.com/kyegomez/swarms/tree/main/swarms) +# Initialize the agent +agent = Agent( + agent_name="Financial-Analysis-Agent", + system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, + llm=model, + max_loops="auto", + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + interactive=True, + # interactive=True, # Set to False to disable interactive mode + saved_state_path="finance_agent.json", + # tools=[Add your functions here# ], + # stopping_token="Stop!", + # interactive=True, + # docs_folder="docs", # Enter your folder name + # pdf_path="docs/finance_agent.pdf", + # sop="Calculate the profit for a company.", + # sop_list=["Calculate the profit for a company."], + user_name="swarms_corp", + # # docs= + # # docs_folder="docs", + retry_attempts=3, + # context_length=1000, + # tool_schema = dict + context_length=200000, + # agent_ops_on=True, + # long_term_memory=ChromaDB(docs_folder="artifacts"), +) --------------------------------------------------- +# Initialize the agent +agent2 = Agent( + agent_name="ROTH-IRA-AGENT", + system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, + llm=model, + max_loops="auto", + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + interactive=True, + # interactive=True, # Set to False to disable interactive mode + saved_state_path="finance_agent.json", + # tools=[Add your functions here# ], + # stopping_token="Stop!", + # interactive=True, + # docs_folder="docs", # Enter your folder name + # pdf_path="docs/finance_agent.pdf", + # sop="Calculate the profit for a company.", + # sop_list=["Calculate the profit for a company."], + user_name="swarms_corp", + # # docs= + # # docs_folder="docs", + retry_attempts=3, + # context_length=1000, + # tool_schema = dict + context_length=200000, + # agent_ops_on=True, + # long_term_memory=ChromaDB(docs_folder="artifacts"), +) -# File: swarms/structs/moa.md -# MixtureOfAgents Class Documentation +swarm = SwarmNetwork(agents=[agent1, agent2]) +results = swarm.run_many_agents("task") +``` -## Architecture Overview +### `list_agents` -```mermaid -graph TD - A[Input Task] --> B[Initialize MixtureOfAgents] - B --> C[Reliability Check] - C --> D[Layer 1: Parallel Agent Execution] - D --> E[Layer 2: Sequential Processing] - E --> F[Layer 3: Parallel Agent Execution] - F --> G[Final Aggregator Agent] - G --> H[Output Response] - - subgraph "Agent Layer Details" - I[Agent 1] --> J[Agent Results] - K[Agent 2] --> J - L[Agent N] --> J - end - - subgraph "Processing Flow" - M[Previous Context] --> N[Current Task] - N --> O[Agent Processing] - O --> P[Aggregation] - P --> M - end +```python +def list_agents(self) ``` -## Overview +#### Description +Lists all agents in the pool. -The `MixtureOfAgents` class represents a mixture of agents operating within a swarm. The workflow of the swarm follows a parallel → sequential → parallel → final output agent process. This implementation is inspired by concepts discussed in the paper: [https://arxiv.org/pdf/2406.04692](https://arxiv.org/pdf/2406.04692). +#### Example -The class is designed to manage a collection of agents, orchestrate their execution in layers, and handle the final aggregation of their outputs through a designated final agent. This architecture facilitates complex, multi-step processing where intermediate results are refined through successive layers of agent interactions. +```python +from swarms.structs.agent import Agent +from swarms.structs.swarm_net import SwarmNetwork -## Class Definition +# Initialize the agent +agent2 = Agent( + agent_name="ROTH-IRA-AGENT", + system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, + llm=model, + max_loops="auto", + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + interactive=True, + # interactive=True, # Set to False to disable interactive mode + saved_state_path="finance_agent.json", + # tools=[Add your functions here# ], + # stopping_token="Stop!", + # interactive=True, + # docs_folder="docs", # Enter your folder name + # pdf_path="docs/finance_agent.pdf", + # sop="Calculate the profit for a company.", + # sop_list=["Calculate the profit for a company."], + user_name="swarms_corp", + # # docs= + # # docs_folder="docs", + retry_attempts=3, + # context_length=1000, + # tool_schema = dict + context_length=200000, + # agent_ops_on=True, + # long_term_memory=ChromaDB(docs_folder="artifacts"), +) -### MixtureOfAgents +swarm = SwarmNetwork(agents=[agent]) +swarm.list_agents() +``` + +### `get_agent` ```python -class MixtureOfAgents(BaseSwarm): +def get_agent(self, agent_id) ``` -### Attributes +#### Description +Gets an agent by ID. -| Attribute | Type | Description | Default | -|------------------|--------------|-------------------------------------------------------------------------------------|---------------------------------| -| `agents` | `List[Agent]`| The list of agents in the swarm. | `None` | -| `flow` | `str` | The flow of the swarm. | `parallel -> sequential -> parallel -> final output agent` | -| `max_loops` | `int` | The maximum number of loops to run. | `1` | -| `verbose` | `bool` | Flag indicating whether to print verbose output. | `True` | -| `layers` | `int` | The number of layers in the swarm. | `3` | -| `rules` | `str` | The rules for the swarm. | `None` | -| `final_agent` | `Agent` | The agent to handle the final output processing. | `None` | -| `auto_save` | `bool` | Flag indicating whether to auto-save the metadata to a file. | `False` | -| `saved_file_name`| `str` | The name of the file where the metadata will be saved. | `"moe_swarm.json"` | +#### Parameters +- `agent_id` (_type_): The ID of the agent to retrieve. -## Methods +#### Returns +- `_type_`: The agent with the specified ID. -### `__init__` +#### Example -#### Parameters +```python +from swarms.structs.agent import Agent +from swarms.structs.swarm_net import SwarmNetwork -| Parameter | Type | Description | Default | -|------------------|--------------|-----------------------------------------------------------------------------------------------|----------------------------------------| -| `name` | `str` | The name of the swarm. | `"MixtureOfAgents"` | -| `description` | `str` | A brief description of the swarm. | `"A swarm of agents that run in parallel and sequentially."` | -| `agents` | `List[Agent]`| The list of agents in the swarm. | `None` | -| `max_loops` | `int` | The maximum number of loops to run. | `1` | -| `verbose` | `bool` | Flag indicating whether to print verbose output. | `True` | -| `layers` | `int` | The number of layers in the swarm. | `3` | -| `rules` | `str` | The rules for the swarm. | `None` | -| `final_agent` | `Agent` | The agent to handle the final output processing. | `None` | -| `auto_save` | `bool` | Flag indicating whether to auto-save the metadata to a file. | `False` | -| `saved_file_name`| `str` | The name of the file where the metadata will be saved. | `"moe_swarm.json"` | +# Initialize the agent +agent2 = Agent( + agent_name="ROTH-IRA-AGENT", + system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, + llm=model, + max_loops="auto", + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + interactive=True, + # interactive=True, # Set to False to disable interactive mode + saved_state_path="finance_agent.json", + # tools=[Add your functions here# ], + # stopping_token="Stop!", + # interactive=True, + # docs_folder="docs", # Enter your folder name + # pdf_path="docs/finance_agent.pdf", + # sop="Calculate the profit for a company.", + # sop_list=["Calculate the profit for a company."], + user_name="swarms_corp", + # # docs= + # # docs_folder="docs", + retry_attempts=3, + # context_length=1000, + # tool_schema = dict + context_length=200000, + # agent_ops_on=True, + # long_term_memory=ChromaDB(docs_folder="artifacts"), +) + +swarm = SwarmNetwork(agents=[agent]) +retrieved_agent = swarm.get_agent(agent.id) +``` -### `agent_check` +### `add_agent` ```python -def agent_check(self): +def add_agent(self, agent: Agent) ``` #### Description +Adds an agent to the agent pool. -Checks if the provided `agents` attribute is a list of `Agent` instances. Raises a `TypeError` if the validation fails. +#### Parameters +- `agent` (_type_): The agent to be added to the pool. -#### Example Usage +#### Example ```python -moe_swarm = MixtureOfAgents(agents=[agent1, agent2]) -moe_swarm.agent_check() # Validates the agents +from swarms.structs.agent import Agent +from swarms.structs.swarm_net import SwarmNetwork + +# Initialize the agent +agent2 = Agent( + agent_name="ROTH-IRA-AGENT", + system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, + llm=model, + max_loops="auto", + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + interactive=True, + # interactive=True, # Set to False to disable interactive mode + saved_state_path="finance_agent.json", + # tools=[Add your functions here# ], + # stopping_token="Stop!", + # interactive=True, + # docs_folder="docs", # Enter your folder name + # pdf_path="docs/finance_agent.pdf", + # sop="Calculate the profit for a company.", + # sop_list=["Calculate the profit for a company."], + user_name="swarms_corp", + # # docs= + # # docs_folder="docs", + retry_attempts=3, + # context_length=1000, + # tool_schema = dict + context_length=200000, + # agent_ops_on=True, + # long_term_memory=ChromaDB(docs_folder="artifacts"), +) + +swarm = SwarmNetwork(agents=[]) +swarm.add_agent(agent) ``` -### `final_agent_check` +### `remove_agent` ```python -def final_agent_check(self): +def remove_agent(self, agent_id) ``` #### Description +Removes an agent from the agent pool. -Checks if the provided `final_agent` attribute is an instance of `Agent`. Raises a `TypeError` if the validation fails. +#### Parameters +- `agent_id` (_type_): The ID of the agent to be removed. -#### Example Usage +#### Example ```python -moe_swarm = MixtureOfAgents(final_agent=final_agent) -moe_swarm.final_agent_check() # Validates the final agent +from swarms.structs.agent import Agent +from swarms.structs.swarm_net import SwarmNetwork + +# Initialize the agent +agent2 = Agent( + agent_name="ROTH-IRA-AGENT", + system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, + llm=model, + max_loops="auto", + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + interactive=True, + # interactive=True, # Set to False to disable interactive mode + saved_state_path="finance_agent.json", + # tools=[Add your functions here# ], + # stopping_token="Stop!", + # interactive=True, + # docs_folder="docs", # Enter your folder name + # pdf_path="docs/finance_agent.pdf", + # sop="Calculate the profit for a company.", + # sop_list=["Calculate the profit for a company."], + user_name="swarms_corp", + # # docs= + # # docs_folder="docs", + retry_attempts=3, + # context_length=1000, + # tool_schema = dict + context_length=200000, + # agent_ops_on=True, + # long_term_memory=ChromaDB(docs_folder="artifacts"), +) + +swarm = SwarmNetwork(agents=[agent]) +swarm.remove_agent(agent.id) ``` -### `swarm_initialization` +### ` + +async_remove_agent` ```python -def swarm_initialization(self): +async def async_remove_agent(self, agent_id) ``` #### Description +Removes an agent from the agent pool asynchronously. -Initializes the swarm by logging the swarm name, description, and the number of agents. +#### Parameters +- `agent_id` (_type_): The ID of the agent to be removed. -#### Example Usage +#### Example ```python -moe_swarm = MixtureOfAgents(agents=[agent1, agent2]) -moe_swarm.swarm_initialization() # Initializes the swarm -``` +from swarms.structs.agent import Agent +from swarms.structs.swarm_net import SwarmNetwork -### `run` +# Initialize the agent +agent2 = Agent( + agent_name="ROTH-IRA-AGENT", + system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, + llm=model, + max_loops="auto", + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + interactive=True, + # interactive=True, # Set to False to disable interactive mode + saved_state_path="finance_agent.json", + # tools=[Add your functions here# ], + # stopping_token="Stop!", + # interactive=True, + # docs_folder="docs", # Enter your folder name + # pdf_path="docs/finance_agent.pdf", + # sop="Calculate the profit for a company.", + # sop_list=["Calculate the profit for a company."], + user_name="swarms_corp", + # # docs= + # # docs_folder="docs", + retry_attempts=3, + # context_length=1000, + # tool_schema = dict + context_length=200000, + # agent_ops_on=True, + # long_term_memory=ChromaDB(docs_folder="artifacts"), +) -```python -def run(self, task: str = None, *args, **kwargs): +swarm = SwarmNetwork(agents=[agent]) +await swarm.async_remove_agent(agent.id) ``` -#### Parameters - -| Parameter | Type | Description | Default | -|-----------|--------|---------------------------------|---------| -| `task` | `str` | The task to be performed by the swarm. | `None` | -| `*args` | `tuple`| Additional arguments. | `None` | -| `**kwargs`| `dict` | Additional keyword arguments. | `None` | - -#### Returns +### `scale_up` -| Type | Description | -|-------|---------------------------------------------| -| `str` | The conversation history as a string. | +```python +def scale_up(self, num_agents: int = 1) +``` #### Description +Scales up the agent pool by adding new agents. -Runs the swarm with the given task, orchestrates the execution of agents through the specified layers, and returns the conversation history. +#### Parameters +- `num_agents` (int, optional): The number of agents to add. Defaults to 1. -#### Example Usage +#### Example ```python -moe_swarm = MixtureOfAgents(agents=[agent1, agent2], final_agent=final_agent) -history = moe_swarm.run(task="Solve this problem.") -print(history) +from swarms.structs.agent import Agent +from swarms.structs.swarm_net import SwarmNetwork + +# Initialize the agent +agent2 = Agent( + agent_name="ROTH-IRA-AGENT", + system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, + llm=model, + max_loops="auto", + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + interactive=True, + # interactive=True, # Set to False to disable interactive mode + saved_state_path="finance_agent.json", + # tools=[Add your functions here# ], + # stopping_token="Stop!", + # interactive=True, + # docs_folder="docs", # Enter your folder name + # pdf_path="docs/finance_agent.pdf", + # sop="Calculate the profit for a company.", + # sop_list=["Calculate the profit for a company."], + user_name="swarms_corp", + # # docs= + # # docs_folder="docs", + retry_attempts=3, + # context_length=1000, + # tool_schema = dict + context_length=200000, + # agent_ops_on=True, + # long_term_memory=ChromaDB(docs_folder="artifacts"), +) + +swarm = SwarmNetwork(agents=[agent]) +swarm.scale_up(2) ``` -### `reliability_check` +### `scale_down` ```python -def reliability_check(self) -> None: +def scale_down(self, num_agents: int = 1) ``` #### Description +Scales down the agent pool by removing agents. -Performs validation checks on the Mixture of Agents class to ensure all required components are properly configured. Raises ValueError if any checks fail. - -#### Validation Checks: -- Verifies reference agents are provided -- Validates aggregator agent exists -- Checks aggregator system prompt is set -- Ensures layers count is valid (> 0) +#### Parameters +- `num_agents` (int, optional): The number of agents to remove. Defaults to 1. -### `_get_final_system_prompt` +#### Example ```python -def _get_final_system_prompt(self, system_prompt: str, results: List[str]) -> str: +from swarms.structs.agent import Agent +from swarms.structs.swarm_net import SwarmNetwork + +# Initialize the agent +agent2 = Agent( + agent_name="ROTH-IRA-AGENT", + system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, + llm=model, + max_loops="auto", + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + interactive=True, + # interactive=True, # Set to False to disable interactive mode + saved_state_path="finance_agent.json", + # tools=[Add your functions here# ], + # stopping_token="Stop!", + # interactive=True, + # docs_folder="docs", # Enter your folder name + # pdf_path="docs/finance_agent.pdf", + # sop="Calculate the profit for a company.", + # sop_list=["Calculate the profit for a company."], + user_name="swarms_corp", + # # docs= + # # docs_folder="docs", + retry_attempts=3, + # context_length=1000, + # tool_schema = dict + context_length=200000, + # agent_ops_on=True, + # long_term_memory=ChromaDB(docs_folder="artifacts"), +) + + +swarm = SwarmNetwork(agents=[agent]) +swarm.scale_down(1) ``` +### `run` + #### Description +Runs the swarm network, starting the FastAPI application. -Internal method that constructs a system prompt for subsequent layers by incorporating previous responses. +#### Example -#### Parameters +```python -| Parameter | Type | Description | -|-----------|------|-------------| -| `system_prompt` | `str` | The initial system prompt | -| `results` | `List[str]` | List of previous responses | +import os -#### Returns +from dotenv import load_dotenv -| Type | Description | -|------|-------------| -| `str` | Combined system prompt with previous responses | +# Import the OpenAIChat model and the Agent struct +from swarms import Agent, OpenAIChat, SwarmNetwork -### `run_batched` +# Load the environment variables +load_dotenv() -```python -def run_batched(self, tasks: List[str]) -> List[str]: -``` +# Get the API key from the environment +api_key = os.environ.get("OPENAI_API_KEY") -#### Description +# Initialize the language model +llm = OpenAIChat( + temperature=0.5, + openai_api_key=api_key, +) -Processes multiple tasks sequentially, returning a list of responses. +## Initialize the workflow +agent = Agent(llm=llm, max_loops=1, agent_name="Social Media Manager") +agent2 = Agent(llm=llm, max_loops=1, agent_name=" Product Manager") +agent3 = Agent(llm=llm, max_loops=1, agent_name="SEO Manager") -#### Parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| `tasks` | `List[str]` | List of tasks to process | +# Load the swarmnet with the agents +swarmnet = SwarmNetwork( + agents=[agent, agent2, agent3], +) -#### Returns +# List the agents in the swarm network +out = swarmnet.list_agents() +print(out) -| Type | Description | -|------|-------------| -| `List[str]` | List of responses for each task | +# Run the workflow on a task +out = swarmnet.run_single_agent( + agent2.id, "Generate a 10,000 word blog on health and wellness." +) +print(out) -### `run_concurrently` -```python -def run_concurrently(self, tasks: List[str]) -> List[str]: +# Run all the agents in the swarm network on a task +out = swarmnet.run_many_agents("Generate a 10,000 word blog on health and wellness.") +print(out) ``` -#### Description +## Additional Information and Tips -Processes multiple tasks concurrently using a ThreadPoolExecutor, optimizing for parallel execution. +- **Error Handling**: Make use of try-except blocks to handle potential errors when adding tasks, running tasks, and managing agents. +- **Logging**: Enable logging to track the activity and status of the swarm network. +- **API**: The provided API allows for easy interaction with the swarm network and can be extended as needed. +- **Asynchronous Operations**: Utilize the asynchronous methods for non-blocking operations, especially in a production environment. +- **Scaling**: Adjust the scaling thresholds (`idle_threshold` and `busy_threshold`) based on the specific needs and workload patterns. -#### Parameters +## References and Resources -| Parameter | Type | Description | -|-----------|------|-------------| -| `tasks` | `List[str]` | List of tasks to process concurrently | +- [Python Queue Documentation](https://docs.python.org/3/library/queue.html) +- [Threading in Python](https://docs.python.org/3/library/threading.html) +- [FastAPI Documentation](https://fastapi.tiangolo.com/) +- [Tenacity Documentation](https://tenacity.readthedocs.io/en/latest/) -#### Returns +By following this documentation, users can effectively manage and utilize the `SwarmNetwork` class to handle dynamic workloads and maintain an efficient pool of agents. -| Type | Description | -|------|-------------| -| `List[str]` | List of responses for each task | -## Detailed Explanation +-------------------------------------------------- -### Initialization +# File: swarms\structs\swarm_rearrange.md -The `__init__` method initializes the swarm with the provided parameters, sets up the conversation rules, and invokes the initialization of the swarm. It also ensures the validity of the `agents` and `final_agent` attributes by calling the `agent_check` and `final_agent_check` methods respectively. +# SwarmRearrange Documentation -### Agent Validation +SwarmRearrange is a class for orchestrating multiple swarms in a sequential or parallel flow pattern. It provides thread-safe operations for managing swarm execution, history tracking, and flow validation. -The `agent_check` method validates whether the `agents` attribute is a list of `Agent` instances, while the `final_agent_check` method validates whether the `final_agent` is an instance of `Agent`. These checks are crucial to ensure that the swarm operates correctly with the appropriate agent types. +## Constructor Arguments -### Swarm Initialization +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| id | str | UUID | Unique identifier for the swarm arrangement | +| name | str | "SwarmRearrange" | Name of the swarm arrangement | +| description | str | "A swarm of swarms..." | Description of the arrangement | +| swarms | List[Any] | [] | List of swarm objects to be managed | +| flow | str | None | Flow pattern for swarm execution | +| max_loops | int | 1 | Maximum number of execution loops | +| verbose | bool | True | Enable detailed logging | +| human_in_the_loop | bool | False | Enable human intervention | +| custom_human_in_the_loop | Callable | None | Custom function for human interaction | +| return_json | bool | False | Return results in JSON format | -The `swarm_initialization` method logs essential information about the swarm, including its name, description, and the number of agents. This provides a clear starting point for the swarm's operations and facilitates debugging and monitoring. +## Methods -### Running the Swarm +### add_swarm(swarm: Any) +Adds a single swarm to the arrangement. -The `run` method is the core of the `MixtureOfAgents` class. It orchestrates the execution of agents through multiple layers, collects their outputs, and processes the final output using the `final_agent`. The conversation history is maintained and updated throughout this process, allowing for a seamless flow of information and responses. +### remove_swarm(swarm_name: str) +Removes a swarm by name from the arrangement. -During each layer, the method iterates over the agents, invokes their `run` method with the current conversation history, and logs the outputs. These outputs are then added to the conversation, and the history is updated for the next layer. +### add_swarms(swarms: List[Any]) +Adds multiple swarms to the arrangement. -After all layers are completed, the final output agent processes the entire conversation history, and the metadata is created and optionally saved to a file. This metadata includes details about the layers, agent runs, and final output, providing a comprehensive record of the swarm's execution. +### validate_flow() +Validates the flow pattern syntax and swarm names. -## Additional Information and Tips +### run(task: str = None, img: str = None, custom_tasks: Dict[str, str] = None) +Executes the swarm arrangement according to the flow pattern. -### Common Issues and Solutions +## Flow Pattern Syntax +The flow pattern uses arrow notation (`->`) to define execution order: -- **Type Errors**: Ensure that all agents in the `agents` list and the `final_agent` are instances of the `Agent` class. The `agent_check` and `final_agent_check` methods help validate this. -- **Verbose Logging**: Use the `verbose` flag to control the verbosity of the output. This can help with debugging or reduce clutter in the logs. -- **Auto-Save Feature**: Utilize the `auto_save` flag to automatically save the metadata to a file. This can be useful for keeping records of the swarm's operations without manual intervention. +- Sequential: `"SwarmA -> SwarmB -> SwarmC"` +- Parallel: `"SwarmA, SwarmB -> SwarmC"` +- Human intervention: Use `"H"` in the flow -### References and Resources +## Examples -For further reading and background information on the concepts used in the `MixtureOfAgents` class, refer to the paper: [https://arxiv.org/pdf/2406.04692](https://arxiv.org/pdf/2406.04692). +### Basic Sequential Flow -### Usage Examples +```python +from swarms.structs.swarm_arange import SwarmRearrange +import os +from swarms import Agent, AgentRearrange +from swarm_models import OpenAIChat -#### Example 1: Basic Initialization and Run +# model = Anthropic(anthropic_api_key=os.getenv("ANTHROPIC_API_KEY")) +company = "TGSC" -```python -from swarms import MixtureOfAgents, Agent +# Get the OpenAI API key from the environment variable +api_key = os.getenv("GROQ_API_KEY") -from swarm_models import OpenAIChat +# Model +model = OpenAIChat( + openai_api_base="https://api.groq.com/openai/v1", + openai_api_key=api_key, + model_name="llama-3.1-70b-versatile", + temperature=0.1, +) -# Define agents -director = Agent( - agent_name="Director", - system_prompt="Directs the tasks for the accountants", - llm=OpenAIChat(), + +# Initialize the Managing Director agent +managing_director = Agent( + agent_name="Managing-Director", + system_prompt=f""" + As the Managing Director at Blackstone, your role is to oversee the entire investment analysis process for potential acquisitions. + Your responsibilities include: + 1. Setting the overall strategy and direction for the analysis + 2. Coordinating the efforts of the various team members and ensuring a comprehensive evaluation + 3. Reviewing the findings and recommendations from each team member + 4. Making the final decision on whether to proceed with the acquisition + + For the current potential acquisition of {company}, direct the tasks for the team to thoroughly analyze all aspects of the company, including its financials, industry position, technology, market potential, and regulatory compliance. Provide guidance and feedback as needed to ensure a rigorous and unbiased assessment. + """, + llm=model, max_loops=1, dashboard=False, streaming_on=True, verbose=True, stopping_token="", state_save_file_type="json", - saved_state_path="director.json", + saved_state_path="managing-director.json", ) -# Initialize accountant 1 -accountant1 = Agent( - agent_name="Accountant1", - system_prompt="Prepares financial statements", - llm=OpenAIChat(), +# Initialize the Vice President of Finance +vp_finance = Agent( + agent_name="VP-Finance", + system_prompt=f""" + As the Vice President of Finance at Blackstone, your role is to lead the financial analysis of potential acquisitions. + For the current potential acquisition of {company}, your tasks include: + 1. Conducting a thorough review of {company}' financial statements, including income statements, balance sheets, and cash flow statements + 2. Analyzing key financial metrics such as revenue growth, profitability margins, liquidity ratios, and debt levels + 3. Assessing the company's historical financial performance and projecting future performance based on assumptions and market conditions + 4. Identifying any financial risks or red flags that could impact the acquisition decision + 5. Providing a detailed report on your findings and recommendations to the Managing Director + + Be sure to consider factors such as the sustainability of {company}' business model, the strength of its customer base, and its ability to generate consistent cash flows. Your analysis should be data-driven, objective, and aligned with Blackstone's investment criteria. + """, + llm=model, max_loops=1, dashboard=False, streaming_on=True, verbose=True, stopping_token="", state_save_file_type="json", - saved_state_path="accountant1.json", + saved_state_path="vp-finance.json", ) -# Initialize accountant 2 -accountant2 = Agent( - agent_name="Accountant2", - system_prompt="Audits financial records", - llm=OpenAIChat(), +# Initialize the Industry Analyst +industry_analyst = Agent( + agent_name="Industry-Analyst", + system_prompt=f""" + As the Industry Analyst at Blackstone, your role is to provide in-depth research and analysis on the industries and markets relevant to potential acquisitions. + For the current potential acquisition of {company}, your tasks include: + 1. Conducting a comprehensive analysis of the industrial robotics and automation solutions industry, including market size, growth rates, key trends, and future prospects + 2. Identifying the major players in the industry and assessing their market share, competitive strengths and weaknesses, and strategic positioning + 3. Evaluating {company}' competitive position within the industry, including its market share, differentiation, and competitive advantages + 4. Analyzing the key drivers and restraints for the industry, such as technological advancements, labor costs, regulatory changes, and economic conditions + 5. Identifying potential risks and opportunities for {company} based on the industry analysis, such as disruptive technologies, emerging markets, or shifts in customer preferences + + Your analysis should provide a clear and objective assessment of the attractiveness and future potential of the industrial robotics industry, as well as {company}' positioning within it. Consider both short-term and long-term factors, and provide evidence-based insights to inform the investment decision. + """, + llm=model, max_loops=1, dashboard=False, streaming_on=True, verbose=True, stopping_token="", state_save_file_type="json", - saved_state_path="accountant2.json", + saved_state_path="industry-analyst.json", ) - -# Initialize the MixtureOfAgents -moe_swarm = MixtureOfAgents(agents=[director, accountant1, accountant2], final_agent=director) - -# Run the swarm -history = moe_swarm.run(task="Perform task X.") -print(history) -``` - -#### Example 2: Verbose Output and Auto-Save - -```python -from swarms import MixtureOfAgents, Agent - -from swarm_models import OpenAIChat - -# Define Agents -# Define agents -director = Agent( - agent_name="Director", - system_prompt="Directs the tasks for the accountants", - llm=OpenAIChat(), +# Initialize the Technology Expert +tech_expert = Agent( + agent_name="Tech-Expert", + system_prompt=f""" + As the Technology Expert at Blackstone, your role is to assess the technological capabilities, competitive advantages, and potential risks of companies being considered for acquisition. + For the current potential acquisition of {company}, your tasks include: + 1. Conducting a deep dive into {company}' proprietary technologies, including its robotics platforms, automation software, and AI capabilities + 2. Assessing the uniqueness, scalability, and defensibility of {company}' technology stack and intellectual property + 3. Comparing {company}' technologies to those of its competitors and identifying any key differentiators or technology gaps + 4. Evaluating {company}' research and development capabilities, including its innovation pipeline, engineering talent, and R&D investments + 5. Identifying any potential technology risks or disruptive threats that could impact {company}' long-term competitiveness, such as emerging technologies or expiring patents + + Your analysis should provide a comprehensive assessment of {company}' technological strengths and weaknesses, as well as the sustainability of its competitive advantages. Consider both the current state of its technology and its future potential in light of industry trends and advancements. + """, + llm=model, max_loops=1, dashboard=False, streaming_on=True, verbose=True, stopping_token="", state_save_file_type="json", - saved_state_path="director.json", + saved_state_path="tech-expert.json", ) -# Initialize accountant 1 -accountant1 = Agent( - agent_name="Accountant1", - system_prompt="Prepares financial statements", - llm=OpenAIChat(), +# Initialize the Market Researcher +market_researcher = Agent( + agent_name="Market-Researcher", + system_prompt=f""" + As the Market Researcher at Blackstone, your role is to analyze the target company's customer base, market share, and growth potential to assess the commercial viability and attractiveness of the potential acquisition. + For the current potential acquisition of {company}, your tasks include: + 1. Analyzing {company}' current customer base, including customer segmentation, concentration risk, and retention rates + 2. Assessing {company}' market share within its target markets and identifying key factors driving its market position + 3. Conducting a detailed market sizing and segmentation analysis for the industrial robotics and automation markets, including identifying high-growth segments and emerging opportunities + 4. Evaluating the demand drivers and sales cycles for {company}' products and services, and identifying any potential risks or limitations to adoption + 5. Developing financial projections and estimates for {company}' revenue growth potential based on the market analysis and assumptions around market share and penetration + + Your analysis should provide a data-driven assessment of the market opportunity for {company} and the feasibility of achieving our investment return targets. Consider both bottom-up and top-down market perspectives, and identify any key sensitivities or assumptions in your projections. + """, + llm=model, max_loops=1, dashboard=False, streaming_on=True, verbose=True, stopping_token="", state_save_file_type="json", - saved_state_path="accountant1.json", + saved_state_path="market-researcher.json", ) -# Initialize accountant 2 -accountant2 = Agent( - agent_name="Accountant2", - system_prompt="Audits financial records", - llm=OpenAIChat(), +# Initialize the Regulatory Specialist +regulatory_specialist = Agent( + agent_name="Regulatory-Specialist", + system_prompt=f""" + As the Regulatory Specialist at Blackstone, your role is to identify and assess any regulatory risks, compliance requirements, and potential legal liabilities associated with potential acquisitions. + For the current potential acquisition of {company}, your tasks include: + 1. Identifying all relevant regulatory bodies and laws that govern the operations of {company}, including industry-specific regulations, labor laws, and environmental regulations + 2. Reviewing {company}' current compliance policies, procedures, and track record to identify any potential gaps or areas of non-compliance + 3. Assessing the potential impact of any pending or proposed changes to relevant regulations that could affect {company}' business or create additional compliance burdens + 4. Evaluating the potential legal liabilities and risks associated with {company}' products, services, and operations, including product liability, intellectual property, and customer contracts + 5. Providing recommendations on any regulatory or legal due diligence steps that should be taken as part of the acquisition process, as well as any post-acquisition integration considerations + + Your analysis should provide a comprehensive assessment of the regulatory and legal landscape surrounding {company}, and identify any material risks or potential deal-breakers. Consider both the current state and future outlook, and provide practical recommendations to mitigate identified risks. + """, + llm=model, max_loops=1, dashboard=False, streaming_on=True, verbose=True, stopping_token="", state_save_file_type="json", - saved_state_path="accountant2.json", + saved_state_path="regulatory-specialist.json", ) -# Initialize the MixtureOfAgents with verbose output and auto-save enabled -moe_swarm = MixtureOfAgents( - agents=[director, accountant1, accountant2], - final_agent=director, - verbose=True, - auto_save=True -) +# Create a list of agents +agents = [ + managing_director, + vp_finance, + industry_analyst, + tech_expert, + market_researcher, + regulatory_specialist, +] -# Run the swarm -history = moe_swarm.run(task="Analyze data set Y.") -print(history) -``` +# Define multiple flow patterns +flows = [ + "Industry-Analyst -> Tech-Expert -> Market-Researcher -> Regulatory-Specialist -> Managing-Director -> VP-Finance", + "Managing-Director -> VP-Finance -> Industry-Analyst -> Tech-Expert -> Market-Researcher -> Regulatory-Specialist", + "Tech-Expert -> Market-Researcher -> Regulatory-Specialist -> Industry-Analyst -> Managing-Director -> VP-Finance", +] -#### Example 3: Custom Rules and Multiple Layers +# Create instances of AgentRearrange for each flow pattern +blackstone_acquisition_analysis = AgentRearrange( + name="Blackstone-Acquisition-Analysis", + description="A system for analyzing potential acquisitions", + agents=agents, + flow=flows[0], +) -```python -from swarms import MixtureOfAgents, Agent +blackstone_investment_strategy = AgentRearrange( + name="Blackstone-Investment-Strategy", + description="A system for evaluating investment opportunities", + agents=agents, + flow=flows[1], +) -from swarm_models import OpenAIChat +blackstone_market_analysis = AgentRearrange( + name="Blackstone-Market-Analysis", + description="A system for analyzing market trends and opportunities", + agents=agents, + flow=flows[2], +) -# Define agents -# Initialize the director agent -director = Agent( - agent_name="Director", - system_prompt="Directs the tasks for the accountants", - llm=OpenAIChat(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="director.json", +swarm_arrange = SwarmRearrange( + swarms=[ + blackstone_acquisition_analysis, + blackstone_investment_strategy, + blackstone_market_analysis, + ], + flow=f"{blackstone_acquisition_analysis.name} -> {blackstone_investment_strategy.name} -> {blackstone_market_analysis.name}", ) -# Initialize accountant 1 -accountant1 = Agent( - agent_name="Accountant1", - system_prompt="Prepares financial statements", - llm=OpenAIChat(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="accountant1.json", +print( + swarm_arrange.run( + "Analyze swarms, 150k revenue with 45m+ agents build, with 1.4m downloads since march 2024" + ) ) -# Initialize accountant 2 -accountant2 = Agent( - agent_name="Accountant2", - system_prompt="Audits financial records", - llm=OpenAIChat(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="accountant2.json", +``` + +### Human-in-the-Loop + +```python +def custom_human_input(task): + return input(f"Review {task} and provide feedback: ") + +# Create arrangement with human intervention +arrangement = SwarmRearrange( + name="HumanAugmented", + swarms=[swarm1, swarm2], + flow="SwarmA -> H -> SwarmB", + human_in_the_loop=True, + custom_human_in_the_loop=custom_human_input ) -# Initialize the MixtureOfAgents with custom rules and multiple layers -moe_swarm = MixtureOfAgents( - agents=[director, accountant1, accountant2], - final_agent=director, - layers=5, - rules="Custom rules for the swarm" +# Execute with human intervention +result = arrangement.run("Initial task") +``` + +### Complex Multi-Stage Pipeline + +```python +# Define multiple flow patterns +flows = [ + "Collector -> Processor -> Analyzer", + "Analyzer -> ML -> Validator", + "Validator -> Reporter" +] + +# Create arrangements for each flow +pipelines = [ + SwarmRearrange(name=f"Pipeline{i}", swarms=swarms, flow=flow) + for i, flow in enumerate(flows) +] + +# Create master arrangement +master = SwarmRearrange( + name="MasterPipeline", + swarms=pipelines, + flow="Pipeline0 -> Pipeline1 -> Pipeline2" ) -# Run the swarm -history = moe_swarm.run(task="Optimize process Z.") -print(history) +# Execute complete pipeline +result = master.run("Start analysis") ``` -This comprehensive documentation provides a detailed understanding of the `MixtureOfAgents` class, its attributes, methods, and usage. The examples illustrate how to initialize and run the swarm, demonstrating its flexibility and capability to handle various tasks and configurations. +## Best Practices +1. **Flow Validation**: Always validate flows before execution +2. **Error Handling**: Implement try-catch blocks around run() calls +3. **History Tracking**: Use track_history() for monitoring swarm execution +4. **Resource Management**: Set appropriate max_loops to prevent infinite execution +5. **Logging**: Enable verbose mode during development for detailed logging -# Conclusion +## Error Handling -The `MixtureOfAgents` class is a powerful and flexible framework for managing and orchestrating a swarm of agents. By following a structured approach of parallel and sequential processing, it enables the implementation of complex multi-step workflows where intermediate results are refined through multiple layers of agent interactions. This architecture is particularly suitable for tasks that require iterative processing, collaboration among diverse agents, and sophisticated aggregation of outputs. +The class implements comprehensive error handling: -### Key Takeaways +```python +try: + arrangement = SwarmRearrange(swarms=swarms, flow=flow) + result = arrangement.run(task) +except ValueError as e: + logger.error(f"Flow validation error: {e}") +except Exception as e: + logger.error(f"Execution error: {e}") +``` -1. **Flexible Initialization**: The class allows for customizable initialization with various parameters, enabling users to tailor the swarm's configuration to their specific needs. -2. **Robust Agent Management**: With built-in validation methods, the class ensures that all agents and the final agent are correctly instantiated, preventing runtime errors and facilitating smooth execution. -3. **Layered Processing**: The layered approach to processing allows for intermediate results to be iteratively refined, enhancing the overall output quality. -4. **Verbose Logging and Auto-Save**: These features aid in debugging, monitoring, and record-keeping, providing transparency and ease of management. -5. **Comprehensive Documentation**: The detailed class and method documentation, along with numerous usage examples, provide a clear and thorough understanding of how to leverage the `MixtureOfAgents` class effectively. +-------------------------------------------------- -### Practical Applications +# File: swarms\structs\swarm_router.md -The `MixtureOfAgents` class can be applied in various domains, including but not limited to: +# SwarmRouter Documentation -- **Natural Language Processing (NLP)**: Managing a swarm of NLP models to process, analyze, and synthesize text. -- **Data Analysis**: Coordinating multiple data analysis agents to process and interpret complex data sets. -- **Optimization Problems**: Running a swarm of optimization algorithms to solve complex problems in fields such as logistics, finance, and engineering. -- **AI Research**: Implementing experimental setups that require the collaboration of multiple AI models or agents to explore new methodologies and approaches. +The `SwarmRouter` class is a flexible routing system designed to manage different types of swarms for task execution. It provides a unified interface to interact with various swarm types, including: -### Future Extensions +| Swarm Type | Description | +|------------|-------------| +| `AgentRearrange` | Optimizes agent arrangement for task execution | +| `MixtureOfAgents` | Combines multiple agent types for diverse tasks | +| `SpreadSheetSwarm` | Uses spreadsheet-like operations for task management | +| `SequentialWorkflow` | Executes tasks sequentially | +| `ConcurrentWorkflow` | Executes tasks in parallel | +| `GroupChat` | Facilitates communication among agents in a group chat format | +| `MultiAgentRouter` | Routes tasks between multiple agents | +| `AutoSwarmBuilder` | Automatically builds swarm structure | +| `HiearchicalSwarm` | Hierarchical organization of agents | +| `MajorityVoting` | Uses majority voting for decision making | +| `MALT` | Multi-Agent Language Tasks | +| `DeepResearchSwarm` | Specialized for deep research tasks | +| `CouncilAsAJudge` | Council-based judgment system | +| `InteractiveGroupChat` | Interactive group chat with user participation | +| `auto` | Automatically selects best swarm type via embedding search | -The `MixtureOfAgents` framework provides a solid foundation for further extensions and customizations, including: +## Classes -- **Dynamic Layer Configuration**: Allowing layers to be added or removed dynamically based on the task requirements or intermediate results. -- **Advanced Agent Communication**: Enhancing the communication protocols between agents to allow for more sophisticated information exchange. -- **Integration with Other Frameworks**: Seamlessly integrating with other machine learning or data processing frameworks to leverage their capabilities within the swarm architecture. +### Document -In conclusion, the `MixtureOfAgents` class represents a versatile and efficient solution for orchestrating multi-agent systems, facilitating complex task execution through its structured and layered approach. By harnessing the power of parallel and sequential processing, it opens up new possibilities for tackling intricate problems across various domains. +A Pydantic model for representing document data. -## Additional Examples +| Attribute | Type | Description | +| --- | --- | --- | +| `file_path` | str | Path to the document file. | +| `data` | str | Content of the document. | -### Example 4: Batch Processing +### SwarmLog -```python -from swarms import MixtureOfAgents, Agent -from swarm_models import OpenAIChat +A Pydantic model for capturing log entries. -# Initialize agents as in previous examples -director = Agent( - agent_name="Director", - system_prompt="Directs the tasks for the accountants", - llm=OpenAIChat(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="director.json", -) +| Attribute | Type | Description | +| --- | --- | --- | +| `id` | str | Unique identifier for the log entry. | +| `timestamp` | datetime | Time of log creation. | +| `level` | str | Log level (e.g., "info", "error"). | +| `message` | str | Log message content. | +| `swarm_type` | SwarmType | Type of swarm associated with the log. | +| `task` | str | Task being performed (optional). | +| `metadata` | Dict[str, Any] | Additional metadata (optional). | +| `documents` | List[Document] | List of documents associated with the log. | -accountant1 = Agent( - agent_name="Accountant1", - system_prompt="Prepares financial statements", - llm=OpenAIChat(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="accountant1.json", -) +### SwarmRouterConfig -accountant2 = Agent( - agent_name="Accountant2", - system_prompt="Audits financial records", - llm=OpenAIChat(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="accountant2.json", -) +Configuration model for SwarmRouter. -# Initialize MixtureOfAgents -moe_swarm = MixtureOfAgents( - agents=[director, accountant1, accountant2], - final_agent=director -) +| Attribute | Type | Description | +| --- | --- | --- | +| `name` | str | Name identifier for the SwarmRouter instance | +| `description` | str | Description of the SwarmRouter's purpose | +| `swarm_type` | SwarmType | Type of swarm to use | +| `rearrange_flow` | Optional[str] | Flow configuration string | +| `rules` | Optional[str] | Rules to inject into every agent | +| `multi_agent_collab_prompt` | bool | Whether to enable multi-agent collaboration prompts | +| `task` | str | The task to be executed by the swarm | -# Process multiple tasks in batch -tasks = [ - "Analyze Q1 financial statements", - "Review tax compliance", - "Prepare budget forecast" -] -results = moe_swarm.run_batched(tasks) -for task, result in zip(tasks, results): - print(f"Task: {task}\nResult: {result}\n") +### SwarmRouter + +Main class for routing tasks to different swarm types. + +| Attribute | Type | Description | +| --- | --- | --- | +| `name` | str | Name of the SwarmRouter instance | +| `description` | str | Description of the SwarmRouter's purpose | +| `max_loops` | int | Maximum number of loops to perform | +| `agents` | List[Union[Agent, Callable]] | List of Agent objects or callable functions | +| `swarm_type` | SwarmType | Type of swarm to be used | +| `autosave` | bool | Flag to enable/disable autosave | +| `rearrange_flow` | str | The flow for the AgentRearrange swarm type | +| `return_json` | bool | Flag to enable/disable returning the result in JSON format | +| `auto_generate_prompts` | bool | Flag to enable/disable auto generation of prompts | +| `shared_memory_system` | Any | Shared memory system for agents | +| `rules` | str | Rules to inject into every agent | +| `documents` | List[str] | List of document file paths | +| `output_type` | OutputType | Output format type (e.g., "string", "dict", "list", "json", "yaml", "xml") | +| `no_cluster_ops` | bool | Flag to disable cluster operations | +| `speaker_fn` | callable | Speaker function for GroupChat swarm type | +| `load_agents_from_csv` | bool | Flag to enable/disable loading agents from CSV | +| `csv_file_path` | str | Path to the CSV file for loading agents | +| `return_entire_history` | bool | Flag to enable/disable returning the entire conversation history | +| `multi_agent_collab_prompt` | bool | Whether to enable multi-agent collaboration prompts | + +#### Methods: + +| Method | Parameters | Description | +| --- | --- | --- | +| `__init__` | `name: str = "swarm-router", description: str = "Routes your task to the desired swarm", max_loops: int = 1, agents: List[Union[Agent, Callable]] = [], swarm_type: SwarmType = "SequentialWorkflow", autosave: bool = False, rearrange_flow: str = None, return_json: bool = False, auto_generate_prompts: bool = False, shared_memory_system: Any = None, rules: str = None, documents: List[str] = [], output_type: OutputType = "dict", no_cluster_ops: bool = False, speaker_fn: callable = None, load_agents_from_csv: bool = False, csv_file_path: str = None, return_entire_history: bool = True, multi_agent_collab_prompt: bool = True` | Initialize the SwarmRouter | +| `setup` | None | Set up the SwarmRouter by activating APE and handling shared memory and rules | +| `activate_shared_memory` | None | Activate shared memory with all agents | +| `handle_rules` | None | Inject rules to every agent | +| `activate_ape` | None | Activate automatic prompt engineering for agents that support it | +| `reliability_check` | None | Perform reliability checks on the SwarmRouter configuration | +| `_create_swarm` | `task: str = None, *args, **kwargs` | Create and return the specified swarm type | +| `update_system_prompt_for_agent_in_swarm` | None | Update system prompts for all agents with collaboration prompts | +| `_log` | `level: str, message: str, task: str = "", metadata: Dict[str, Any] = None` | Create a log entry | +| `_run` | `task: str, img: Optional[str] = None, model_response: Optional[str] = None, *args, **kwargs` | Run the specified task on the selected swarm type | +| `run` | `task: str, img: Optional[str] = None, model_response: Optional[str] = None, *args, **kwargs` | Execute a task on the selected swarm type | +| `__call__` | `task: str, *args, **kwargs` | Make the SwarmRouter instance callable | +| `batch_run` | `tasks: List[str], *args, **kwargs` | Execute multiple tasks in sequence | +| `async_run` | `task: str, *args, **kwargs` | Execute a task asynchronously | +| `get_logs` | None | Retrieve all logged entries | +| `concurrent_run` | `task: str, *args, **kwargs` | Execute a task using concurrent execution | +| `concurrent_batch_run` | `tasks: List[str], *args, **kwargs` | Execute multiple tasks concurrently | + + +## Installation + +To use the SwarmRouter, first install the required dependencies: + +```bash +pip install swarms swarm_models ``` -### Example 5: Concurrent Processing +## Basic Usage ```python -from swarms import MixtureOfAgents, Agent +import os +from dotenv import load_dotenv +from swarms import Agent, SwarmRouter, SwarmType from swarm_models import OpenAIChat -# Initialize agents as before -# ... agent initialization code ... - -# Initialize MixtureOfAgents -moe_swarm = MixtureOfAgents( - agents=[director, accountant1, accountant2], - final_agent=director -) +load_dotenv() -# Process multiple tasks concurrently -tasks = [ - "Generate monthly report", - "Audit expense claims", - "Update financial projections", - "Review investment portfolio" -] -results = moe_swarm.run_concurrently(tasks) -for task, result in zip(tasks, results): - print(f"Task: {task}\nResult: {result}\n") -``` +# Get the OpenAI API key from the environment variable +api_key = os.getenv("GROQ_API_KEY") -## Advanced Features +# Model +model = OpenAIChat( + openai_api_base="https://api.groq.com/openai/v1", + openai_api_key=api_key, + model_name="llama-3.1-70b-versatile", + temperature=0.1, +) -### Context Preservation +# Define specialized system prompts for each agent +DATA_EXTRACTOR_PROMPT = """You are a highly specialized private equity agent focused on data extraction from various documents. Your expertise includes: +1. Extracting key financial metrics (revenue, EBITDA, growth rates, etc.) from financial statements and reports +2. Identifying and extracting important contract terms from legal documents +3. Pulling out relevant market data from industry reports and analyses +4. Extracting operational KPIs from management presentations and internal reports +5. Identifying and extracting key personnel information from organizational charts and bios +Provide accurate, structured data extracted from various document types to support investment analysis.""" -The `MixtureOfAgents` class maintains context between iterations when running multiple loops. Each subsequent iteration receives the context from previous runs, allowing for more sophisticated and context-aware processing. +SUMMARIZER_PROMPT = """You are an expert private equity agent specializing in summarizing complex documents. Your core competencies include: +1. Distilling lengthy financial reports into concise executive summaries +2. Summarizing legal documents, highlighting key terms and potential risks +3. Condensing industry reports to capture essential market trends and competitive dynamics +4. Summarizing management presentations to highlight key strategic initiatives and projections +5. Creating brief overviews of technical documents, emphasizing critical points for non-technical stakeholders +Deliver clear, concise summaries that capture the essence of various documents while highlighting information crucial for investment decisions.""" -### Asynchronous Processing +# Initialize specialized agents +data_extractor_agent = Agent( + agent_name="Data-Extractor", + system_prompt=DATA_EXTRACTOR_PROMPT, + llm=model, + max_loops=1, + autosave=True, + verbose=True, + dynamic_temperature_enabled=True, + saved_state_path="data_extractor_agent.json", + user_name="pe_firm", + retry_attempts=1, + context_length=200000, + output_type="string", +) -The class implements asynchronous processing internally using Python's `asyncio`, enabling efficient handling of concurrent operations and improved performance for complex workflows. +summarizer_agent = Agent( + agent_name="Document-Summarizer", + system_prompt=SUMMARIZER_PROMPT, + llm=model, + max_loops=1, + autosave=True, + verbose=True, + dynamic_temperature_enabled=True, + saved_state_path="summarizer_agent.json", + user_name="pe_firm", + retry_attempts=1, + context_length=200000, + output_type="string", +) -### Telemetry and Logging +# Initialize the SwarmRouter +router = SwarmRouter( + name="pe-document-analysis-swarm", + description="Analyze documents for private equity due diligence and investment decision-making", + max_loops=1, + agents=[data_extractor_agent, summarizer_agent], + swarm_type="ConcurrentWorkflow", + autosave=True, + return_json=True, +) -Built-in telemetry and logging capabilities help track agent performance and maintain detailed execution records: -- Automatic logging of agent outputs -- Structured data capture using Pydantic models -- JSON-formatted output options +# Example usage +if __name__ == "__main__": + # Run a comprehensive private equity document analysis task + result = router.run( + "Where is the best place to find template term sheets for series A startups? Provide links and references" + ) + print(result) --------------------------------------------------- + # Retrieve and print logs + for log in router.get_logs(): + print(f"{log.timestamp} - {log.level}: {log.message}") +``` -# File: swarms/structs/model_router.md +## Advanced Usage -# ModelRouter Docs +### Changing Swarm Types -The ModelRouter is an intelligent routing system that automatically selects and executes AI models based on task requirements. It leverages a function-calling architecture to analyze tasks and recommend the optimal model and provider combination for each specific use case. +You can create multiple SwarmRouter instances with different swarm types: +```python +sequential_router = SwarmRouter( + name="SequentialRouter", + agents=[agent1, agent2], + swarm_type="SequentialWorkflow" +) +concurrent_router = SwarmRouter( + name="ConcurrentRouter", + agents=[agent1, agent2], + swarm_type="ConcurrentWorkflow" +) +``` +### Automatic Swarm Type Selection +You can let the SwarmRouter automatically select the best swarm type for a given task: -### Key Features +```python +auto_router = SwarmRouter( + name="AutoRouter", + agents=[agent1, agent2], + swarm_type="auto" +) -- Dynamic model selection based on task complexity and requirements -- Multi-provider support (OpenAI, Anthropic, Google, etc.) -- Concurrent and asynchronous execution capabilities -- Batch processing with memory -- Automatic error handling and retries -- Provider-aware routing -- Cost optimization +result = auto_router.run("Analyze and summarize the quarterly financial report") +``` -### Constructor Arguments +### Loading Agents from CSV -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| system_prompt | str | model_router_system_prompt | Custom prompt for guiding model selection behavior | -| max_tokens | int | 4000 | Maximum token limit for model outputs | -| temperature | float | 0.5 | Control parameter for response randomness (0.0-1.0) | -| max_workers | int/str | 10 | Maximum concurrent workers ("auto" for CPU count) | -| api_key | str | None | API key for model access | -| max_loops | int | 1 | Maximum number of refinement iterations | -| *args | Any | None | Additional positional arguments | -| **kwargs | Any | None | Additional keyword arguments | +To load agents from a CSV file: -### Core Methods +```python +csv_router = SwarmRouter( + name="CSVAgentRouter", + load_agents_from_csv=True, + csv_file_path="agents.csv", + swarm_type="SequentialWorkflow" +) -#### run(task: str) -> str +result = csv_router.run("Process the client data") +``` -Executes a single task through the model router with memory and refinement capabilities. +### Using Shared Memory System -# Installation +To enable shared memory across agents: -1. Install the latest version of swarms using pip: +```python +from swarms.memory import SemanticMemory -```bash -pip3 install -U swarms -``` +memory_system = SemanticMemory() -2. Setup your API Keys in your .env file with the following: +memory_router = SwarmRouter( + name="MemoryRouter", + agents=[agent1, agent2], + shared_memory_system=memory_system, + swarm_type="SequentialWorkflow" +) -```bash -OPENAI_API_KEY=your_openai_api_key -ANTHROPIC_API_KEY=your_anthropic_api_key -GOOGLE_API_KEY=your_google_api_key -# Add more API keys as needed following litellm format +result = memory_router.run("Analyze historical data and make predictions") ``` +### Injecting Rules to All Agents -```python -from swarms import ModelRouter +To inject common rules into all agents: -router = ModelRouter() +```python +rules = """ +1. Always provide sources for your information +2. Check your calculations twice +3. Explain your reasoning clearly +4. Highlight uncertainties and assumptions +""" -# Simple text analysis -result = router.run("Analyze the sentiment and key themes in this customer feedback") +rules_router = SwarmRouter( + name="RulesRouter", + agents=[agent1, agent2], + rules=rules, + swarm_type="SequentialWorkflow" +) -# Complex reasoning task -complex_result = router.run(""" -Evaluate the following business proposal: -- Initial investment: $500,000 -- Projected ROI: 25% annually -- Market size: $2B -- Competition: 3 major players -Provide detailed analysis and recommendations. -""") +result = rules_router.run("Analyze the investment opportunity") ``` -#### batch_run(tasks: list) -> list -Executes multiple tasks sequentially with result aggregation. +## Use Cases -```python -# Multiple analysis tasks -tasks = [ - "Analyze Q1 financial performance", - "Predict Q2 market trends", - "Evaluate competitor strategies", - "Generate growth recommendations" -] +### AgentRearrange -results = router.batch_run(tasks) +Use Case: Optimizing agent order for complex multi-step tasks. -# Process results -for task, result in zip(tasks, results): - print(f"Task: {task}\nResult: {result}\n") -``` +```python +rearrange_router = SwarmRouter( + name="TaskOptimizer", + description="Optimize agent order for multi-step tasks", + max_loops=3, + agents=[data_extractor, analyzer, summarizer], + swarm_type="AgentRearrange", + rearrange_flow=f"{data_extractor.name} -> {analyzer.name} -> {summarizer.name}" +) -#### concurrent_run(tasks: list) -> list -Parallel execution of multiple tasks using thread pooling. +result = rearrange_router.run("Analyze and summarize the quarterly financial report") +``` -```python -import asyncio -from typing import List +### MixtureOfAgents -# Define multiple concurrent tasks -analysis_tasks = [ - "Perform technical analysis of AAPL stock", - "Analyze market sentiment from social media", - "Generate trading signals", - "Calculate risk metrics" -] +Use Case: Combining diverse expert agents for comprehensive analysis. -# Execute tasks concurrently -results = router.concurrent_run(analysis_tasks) +```python +mixture_router = SwarmRouter( + name="ExpertPanel", + description="Combine insights from various expert agents", + max_loops=1, + agents=[financial_expert, market_analyst, tech_specialist, aggregator], + swarm_type="MixtureOfAgents" +) -# Process results with error handling -for task, result in zip(analysis_tasks, results): - try: - processed_result = process_analysis(result) - save_to_database(processed_result) - except Exception as e: - log_error(f"Error processing {task}: {str(e)}") +result = mixture_router.run("Evaluate the potential acquisition of TechStartup Inc.") ``` -#### async_run(task: str) -> asyncio.Task -Asynchronous task execution with coroutine support. +### SpreadSheetSwarm + +Use Case: Collaborative data processing and analysis. ```python -async def process_data_stream(): - tasks = [] - async for data in data_stream: - task = await router.async_run(f"Process data: {data}") - tasks.append(task) - - results = await asyncio.gather(*tasks) - return results +spreadsheet_router = SwarmRouter( + name="DataProcessor", + description="Collaborative data processing and analysis", + max_loops=1, + agents=[data_cleaner, statistical_analyzer, visualizer], + swarm_type="SpreadSheetSwarm" +) -# Usage in async context -async def main(): - router = ModelRouter() - results = await process_data_stream() +result = spreadsheet_router.run("Process and visualize customer churn data") ``` -### Advanced Usage Examples +### SequentialWorkflow -#### Financial Analysis System +Use Case: Step-by-step document analysis and report generation. ```python -from swarms import ModelRouter -from typing import Dict, List -import pandas as pd +sequential_router = SwarmRouter( + name="ReportGenerator", + description="Generate comprehensive reports sequentially", + max_loops=1, + agents=[data_extractor, analyzer, writer, reviewer], + swarm_type="SequentialWorkflow", + return_entire_history=True +) -class FinancialAnalysisSystem: - def __init__(self): - self.router = ModelRouter( - temperature=0.3, # Lower temperature for more deterministic outputs - max_tokens=8000, # Higher token limit for detailed analysis - max_loops=2 # Allow for refinement iteration - ) - - def analyze_company_financials(self, financial_data: Dict) -> Dict: - analysis_task = f""" - Perform comprehensive financial analysis: - - Financial Metrics: - - Revenue: ${financial_data['revenue']}M - - EBITDA: ${financial_data['ebitda']}M - - Debt/Equity: {financial_data['debt_equity']} - - Working Capital: ${financial_data['working_capital']}M - - Required Analysis: - 1. Profitability assessment - 2. Liquidity analysis - 3. Growth projections - 4. Risk evaluation - 5. Investment recommendations - - Provide detailed insights and actionable recommendations. - """ - - result = self.router.run(analysis_task) - return self._parse_analysis_result(result) - - def _parse_analysis_result(self, result: str) -> Dict: - # Implementation of result parsing - pass +result = sequential_router.run("Create a due diligence report for Project Alpha") +``` -# Usage -analyzer = FinancialAnalysisSystem() -company_data = { - 'revenue': 150, - 'ebitda': 45, - 'debt_equity': 0.8, - 'working_capital': 25 -} +### ConcurrentWorkflow -analysis = analyzer.analyze_company_financials(company_data) +Use Case: Parallel processing of multiple data sources. + +```python +concurrent_router = SwarmRouter( + name="MultiSourceAnalyzer", + description="Analyze multiple data sources concurrently", + max_loops=1, + agents=[financial_analyst, market_researcher, competitor_analyst], + swarm_type="ConcurrentWorkflow", + output_type="string" +) + +result = concurrent_router.run("Conduct a comprehensive market analysis for Product X") ``` -#### Healthcare Data Processing Pipeline +### GroupChat -```python -from swarms import ModelRouter -import pandas as pd -from typing import List, Dict +Use Case: Simulating a group discussion with multiple agents. -class MedicalDataProcessor: - def __init__(self): - self.router = ModelRouter( - max_workers="auto", # Automatic worker scaling - temperature=0.2, # Conservative temperature for medical analysis - system_prompt="""You are a specialized medical data analyzer focused on: - 1. Clinical terminology interpretation - 2. Patient data analysis - 3. Treatment recommendation review - 4. Medical research synthesis""" - ) - - async def process_patient_records(self, records: List[Dict]) -> List[Dict]: - analysis_tasks = [] - - for record in records: - task = f""" - Analyze patient record: - - Age: {record['age']} - - Symptoms: {', '.join(record['symptoms'])} - - Vital Signs: {record['vitals']} - - Medications: {', '.join(record['medications'])} - - Lab Results: {record['lab_results']} - - Provide: - 1. Symptom analysis - 2. Medication interaction check - 3. Lab results interpretation - 4. Treatment recommendations - """ - analysis_tasks.append(task) - - results = await asyncio.gather(*[ - self.router.async_run(task) for task in analysis_tasks - ]) - - return [self._parse_medical_analysis(r) for r in results] - - def _parse_medical_analysis(self, analysis: str) -> Dict: - # Implementation of medical analysis parsing - pass +```python +group_chat_router = SwarmRouter( + name="GroupChat", + description="Simulate a group discussion with multiple agents", + max_loops=10, + agents=[financial_analyst, market_researcher, competitor_analyst], + swarm_type="GroupChat", + speaker_fn=custom_speaker_function +) -# Usage -async def main(): - processor = MedicalDataProcessor() - patient_records = [ - { - 'age': 45, - 'symptoms': ['fever', 'cough', 'fatigue'], - 'vitals': {'bp': '120/80', 'temp': '38.5C'}, - 'medications': ['lisinopril', 'metformin'], - 'lab_results': 'WBC: 11,000, CRP: 2.5' - } - # More records... - ] - - analyses = await processor.process_patient_records(patient_records) +result = group_chat_router.run("Discuss the pros and cons of expanding into the Asian market") ``` -#### Natural Language Processing Pipeline +### MultiAgentRouter + +Use Case: Routing tasks to the most appropriate agent. ```python -from swarms import ModelRouter -from typing import List, Dict -import asyncio +multi_agent_router = SwarmRouter( + name="MultiAgentRouter", + description="Route tasks to specialized agents", + max_loops=1, + agents=[financial_analyst, market_researcher, competitor_analyst], + swarm_type="MultiAgentRouter", + shared_memory_system=memory_system +) -class NLPPipeline: - def __init__(self): - self.router = ModelRouter( - temperature=0.4, - max_loops=2 - ) - - def process_documents(self, documents: List[str]) -> List[Dict]: - tasks = [self._create_nlp_task(doc) for doc in documents] - results = self.router.concurrent_run(tasks) - return [self._parse_nlp_result(r) for r in results] - - def _create_nlp_task(self, document: str) -> str: - return f""" - Perform comprehensive NLP analysis: - - Text: {document} - - Required Analysis: - 1. Entity recognition - 2. Sentiment analysis - 3. Topic classification - 4. Key phrase extraction - 5. Intent detection - - Provide structured analysis with confidence scores. - """ - - def _parse_nlp_result(self, result: str) -> Dict: - # Implementation of NLP result parsing - pass +result = multi_agent_router.run("Analyze the competitive landscape for our new product") +``` -# Usage -pipeline = NLPPipeline() -documents = [ - "We're extremely satisfied with the new product features!", - "The customer service response time needs improvement.", - "Looking to upgrade our subscription plan next month." -] +See [MultiAgentRouter Minimal Example](../examples/multi_agent_router_minimal.md) for a lightweight demonstration. -analyses = pipeline.process_documents(documents) -``` +### HierarchicalSwarm -### Available Models and Use Cases +Use Case: Creating a hierarchical structure of agents with a director. -| Model | Provider | Optimal Use Cases | Characteristics | -|-------|----------|-------------------|-----------------| -| gpt-4-turbo | OpenAI | Complex reasoning, Code generation, Creative writing | High accuracy, Latest knowledge cutoff | -| claude-3-opus | Anthropic | Research analysis, Technical documentation, Long-form content | Strong reasoning, Detailed outputs | -| gemini-pro | Google | Multimodal tasks, Code generation, Technical analysis | Fast inference, Strong coding abilities | -| mistral-large | Mistral | General tasks, Content generation, Classification | Open source, Good price/performance | -| deepseek-reasoner | DeepSeek | Mathematical analysis, Logic problems, Scientific computing | Specialized reasoning capabilities | +```python +hierarchical_router = SwarmRouter( + name="HierarchicalSwarm", + description="Hierarchical organization of agents with a director", + max_loops=3, + agents=[director, analyst1, analyst2, researcher], + swarm_type="HiearchicalSwarm", + return_all_history=True +) -### Provider Capabilities +result = hierarchical_router.run("Develop a comprehensive market entry strategy") +``` -| Provider | Strengths | Best For | Integration Notes | -|----------|-----------|-----------|------------------| -| OpenAI | Consistent performance, Strong reasoning | Production systems, Complex tasks | Requires API key setup | -| Anthropic | Safety features, Detailed analysis | Research, Technical writing | Claude-specific formatting | -| Google | Technical tasks, Multimodal support | Code generation, Analysis | Vertex AI integration available | -| Groq | High-speed inference | Real-time applications | Optimized for specific models | -| DeepSeek | Specialized reasoning | Scientific computing | Custom API integration | -| Mistral | Open source flexibility | General applications | Self-hosted options available | +### MajorityVoting +Use Case: Using consensus among multiple agents for decision-making. -### Performance Optimization Tips +```python +voting_router = SwarmRouter( + name="MajorityVoting", + description="Make decisions using consensus among agents", + max_loops=1, + agents=[analyst1, analyst2, analyst3, consensus_agent], + swarm_type="MajorityVoting" +) -1. Token Management - - Set appropriate max_tokens based on task complexity - - Monitor token usage for cost optimization - - Use streaming for long outputs +result = voting_router.run("Should we invest in Company X based on the available data?") +``` -2. Concurrency Settings - - Adjust max_workers based on system resources - - Use "auto" workers for optimal CPU utilization - - Monitor memory usage with large batch sizes +### Auto Select (Experimental) +Autonomously selects the right swarm by conducting vector search on your input task or name or description or all 3. -3. Temperature Tuning - - Lower (0.1-0.3) for factual/analytical tasks - - Higher (0.7-0.9) for creative tasks - - Mid-range (0.4-0.6) for balanced outputs +```python +auto_router = SwarmRouter( + name="MultiSourceAnalyzer", + description="Analyze multiple data sources concurrently", + max_loops=1, + agents=[financial_analyst, market_researcher, competitor_analyst], + swarm_type="auto" # Set this to 'auto' for it to auto select your swarm. It's match words like concurrently multiple -> "ConcurrentWorkflow" +) -4. System Prompts - - Customize for specific domains - - Include relevant context - - Define clear output formats +result = auto_router.run("Conduct a comprehensive market analysis for Product X") +``` -### Dependencies +### InteractiveGroupChat -- asyncio: Asynchronous I/O support -- concurrent.futures: Thread pool execution -- pydantic: Data validation -- litellm: LLM interface standardization +Use Case: Interactive group discussions with user participation. +```python +interactive_chat_router = SwarmRouter( + name="InteractiveGroupChat", + description="Interactive group chat with user participation", + max_loops=10, + agents=[financial_analyst, market_researcher, competitor_analyst], + swarm_type="InteractiveGroupChat", + output_type="string" +) --------------------------------------------------- +result = interactive_chat_router.run("Discuss the market trends and provide interactive analysis") +``` -# File: swarms/structs/multi_agent_collaboration_examples.md +The InteractiveGroupChat allows for dynamic interaction between agents and users, enabling real-time participation in group discussions and decision-making processes. This is particularly useful for scenarios requiring human input or validation during the conversation flow. -# Multi-Agent Examples +## Advanced Features +### Processing Documents -### `SequentialWorkflow` -Sequential Workflow enables you to sequentially execute tasks with `Agent` and then pass the output into the next agent and onwards until you have specified your max loops. +To process documents with the SwarmRouter: ```python -from swarms import Agent, SequentialWorkflow +document_router = SwarmRouter( + name="DocumentProcessor", + agents=[document_analyzer, summarizer], + documents=["report.pdf", "contract.docx", "data.csv"], + swarm_type="SequentialWorkflow" +) -from swarm_models import Anthropic +result = document_router.run("Extract key information from the provided documents") +``` +### Batch Processing -# Initialize the language model agent (e.g., GPT-3) -llm = Anthropic() +To process multiple tasks in a batch: -# Initialize agents for individual tasks -agent1 = Agent( - agent_name="Blog generator", - system_prompt="Generate a blog post like stephen king", - llm=llm, - max_loops=1, - dashboard=False, - tools=[], -) -agent2 = Agent( - agent_name="summarizer", - system_prompt="Sumamrize the blog post", - llm=llm, - max_loops=1, - dashboard=False, - tools=[], -) +```python +tasks = ["Analyze Q1 report", "Summarize competitor landscape", "Evaluate market trends"] +results = router.batch_run(tasks) +``` -# Create the Sequential workflow -workflow = SequentialWorkflow( - agents=[agent1, agent2], max_loops=1, verbose=False -) +### Asynchronous Execution -# Run the workflow -workflow.run( - "Generate a blog post on how swarms of agents can help businesses grow." -) +For asynchronous task execution: +```python +result = await router.async_run("Generate financial projections") ``` ------- +### Concurrent Execution -## `AgentRearrange` -Inspired by Einops and einsum, this orchestration techniques enables you to map out the relationships between various agents. For example you specify linear and sequential relationships like `a -> a1 -> a2 -> a3` or concurrent relationships where the first agent will send a message to 3 agents all at once: `a -> a1, a2, a3`. You can customize your workflow to mix sequential and concurrent relationships. [Docs Available:](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/) +To run a single task concurrently: ```python -from swarms import Agent, AgentRearrange - +result = router.concurrent_run("Analyze multiple data streams") +``` -from swarm_models import Anthropic +### Concurrent Batch Processing -# Initialize the director agent +To process multiple tasks concurrently: -director = Agent( - agent_name="Director", - system_prompt="Directs the tasks for the workers", - llm=Anthropic(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="director.json", -) +```python +tasks = ["Task 1", "Task 2", "Task 3"] +results = router.concurrent_batch_run(tasks) +``` +### Using the SwarmRouter as a Callable -# Initialize worker 1 +You can use the SwarmRouter instance directly as a callable: -worker1 = Agent( - agent_name="Worker1", - system_prompt="Generates a transcript for a youtube video on what swarms are", - llm=Anthropic(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="worker1.json", +```python +router = SwarmRouter( + name="CallableRouter", + agents=[agent1, agent2], + swarm_type="SequentialWorkflow" ) +result = router("Analyze the market data") # Equivalent to router.run("Analyze the market data") +``` -# Initialize worker 2 -worker2 = Agent( - agent_name="Worker2", - system_prompt="Summarizes the transcript generated by Worker1", - llm=Anthropic(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="worker2.json", -) - +### Using the swarm_router Function -# Create a list of agents -agents = [director, worker1, worker2] +For quick one-off tasks, you can use the swarm_router function: -# Define the flow pattern -flow = "Director -> Worker1 -> Worker2" +```python +from swarms import swarm_router -# Using AgentRearrange class -agent_system = AgentRearrange(agents=agents, flow=flow) -output = agent_system.run( - "Create a format to express and communicate swarms of llms in a structured manner for youtube" +result = swarm_router( + name="QuickRouter", + agents=[agent1, agent2], + swarm_type="ConcurrentWorkflow", + task="Analyze the quarterly report" ) -print(output) - ``` -## `HierarhicalSwarm` -Coming soon... +-------------------------------------------------- -## `GraphSwarm` +# File: swarms\structs\task.md -```python -import os +# Task Class Documentation -from dotenv import load_dotenv +The `Task` class is a pivotal component designed for managing tasks in a sequential workflow. This class allows for the execution of tasks using various agents, which can be callable objects or specific instances of the `Agent` class. It supports the scheduling of tasks, handling their dependencies, and setting conditions and actions that govern their execution. +Key features of the `Task` class include: +- Executing tasks with specified agents and handling their results. +- Scheduling tasks to run at specified times. +- Setting triggers, actions, and conditions for tasks. +- Managing task dependencies and priorities. +- Providing a history of task executions for tracking purposes. -from swarms import Agent, Edge, GraphWorkflow, Node, NodeType +## Class Definition -from swarm_models import OpenAIChat +The `Task` class is defined as follows: -load_dotenv() -api_key = os.environ.get("OPENAI_API_KEY") +### Attributes -llm = OpenAIChat( - temperature=0.5, openai_api_key=api_key, max_tokens=4000 -) -agent1 = Agent(llm=llm, max_loops=1, autosave=True, dashboard=True) -agent2 = Agent(llm=llm, max_loops=1, autosave=True, dashboard=True) +| Attribute | Type | Description | +|----------------|-----------------------------|---------------------------------------------------------------------------------------| +| `agent` | `Union[Callable, Agent]` | The agent or callable object to run the task. | +| `description` | `str` | Description of the task. | +| `result` | `Any` | Result of the task. | +| `history` | `List[Any]` | History of the task. | +| `schedule_time`| `datetime` | Time to schedule the task. | +| `scheduler` | `sched.scheduler` | Scheduler to schedule the task. | +| `trigger` | `Callable` | Trigger to run the task. | +| `action` | `Callable` | Action to run the task. | +| `condition` | `Callable` | Condition to run the task. | +| `priority` | `int` | Priority of the task. | +| `dependencies` | `List[Task]` | List of tasks that need to be completed before this task can be executed. | +| `args` | `List[Any]` | Arguments to pass to the agent or callable object. | +| `kwargs` | `Dict[str, Any]` | Keyword arguments to pass to the agent or callable object. | -def sample_task(): - print("Running sample task") - return "Task completed" +## Methods -wf_graph = GraphWorkflow() -wf_graph.add_node(Node(id="agent1", type=NodeType.AGENT, agent=agent1)) -wf_graph.add_node(Node(id="agent2", type=NodeType.AGENT, agent=agent2)) -wf_graph.add_node( - Node(id="task1", type=NodeType.TASK, callable=sample_task) -) -wf_graph.add_edge(Edge(source="agent1", target="task1")) -wf_graph.add_edge(Edge(source="agent2", target="task1")) +### `execute(self, *args, **kwargs)` -wf_graph.set_entry_points(["agent1", "agent2"]) -wf_graph.set_end_points(["task1"]) +Executes the task by calling the agent or model with the specified arguments and keyword arguments. If a condition is set, the task will only execute if the condition returns `True`. -print(wf_graph.visualize()) +#### Parameters +- `args`: Arguments to pass to the agent or callable object. +- `kwargs`: Keyword arguments to pass to the agent or callable object. -# Run the workflow -results = wf_graph.run() -print("Execution results:", results) +#### Examples +```python +>>> from swarms.structs import Task, Agent +>>> from swarm_models import OpenAIChat +>>> agent = Agent(llm=OpenAIChat(openai_api_key=""), max_loops=1, dashboard=False) +>>> task = Task(description="What's the weather in Miami?", agent=agent) +>>> task.run() +>>> task.result ``` -## `MixtureOfAgents` -This is an implementation from the paper: "Mixture-of-Agents Enhances Large Language Model Capabilities" by together.ai, it achieves SOTA on AlpacaEval 2.0, MT-Bench and FLASK, surpassing GPT-4 Omni. Great for tasks that need to be parallelized and then sequentially fed into another loop - -```python -from swarms import Agent, OpenAIChat, MixtureOfAgents +### `handle_scheduled_task(self)` -# Initialize the director agent -director = Agent( - agent_name="Director", - system_prompt="Directs the tasks for the accountants", - llm=OpenAIChat(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="director.json", -) +Handles the execution of a scheduled task. If the schedule time is not set or has already passed, the task is executed immediately. Otherwise, the task is scheduled to be executed at the specified schedule time. -# Initialize accountant 1 -accountant1 = Agent( - agent_name="Accountant1", - system_prompt="Prepares financial statements", - llm=OpenAIChat(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="accountant1.json", -) +#### Examples -# Initialize accountant 2 -accountant2 = Agent( - agent_name="Accountant2", - system_prompt="Audits financial records", - llm=OpenAIChat(), - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="accountant2.json", -) +```python +>>> task.schedule_time = datetime.now() + timedelta(seconds=10) +>>> task.handle_scheduled_task() +``` -# Create a list of agents -agents = [director, accountant1, accountant2] +### `set_trigger(self, trigger: Callable)` +Sets the trigger for the task. -# Swarm -swarm = MixtureOfAgents( - name="Mixture of Accountants", - agents=agents, - layers=3, - final_agent=director, -) +#### Parameters +- `trigger` (`Callable`): The trigger to set. +#### Examples -# Run the swarm -out = swarm.run("Prepare financial statements and audit financial records") -print(out) +```python +>>> def my_trigger(): +>>> print("Trigger executed") +>>> task.set_trigger(my_trigger) ``` +### `set_action(self, action: Callable)` --------------------------------------------------- +Sets the action for the task. -# File: swarms/structs/multi_agent_orchestration.md +#### Parameters +- `action` (`Callable`): The action to set. -# Multi-Agent Orchestration: -Swarms was designed to faciliate the communication between many different and specialized agents from a vast array of other frameworks such as langchain, autogen, crew, and more. +#### Examples -In traditional swarm theory, there are many types of swarms usually for very specialized use-cases and problem sets. Such as Hiearchical and sequential are great for accounting and sales, because there is usually a boss coordinator agent that distributes a workload to other specialized agents. +```python +>>> def my_action(): +>>> print("Action executed") +>>> task.set_action(my_action) +``` +### `set_condition(self, condition: Callable)` -| **Name** | **Description** | **Code Link** | **Use Cases** | -|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|---------------------------------------------------------------------------------------------------| -| Hierarchical Swarms | A system where agents are organized in a hierarchy, with higher-level agents coordinating lower-level agents to achieve complex tasks. | [Code Link](#) | Manufacturing process optimization, multi-level sales management, healthcare resource coordination | -| Agent Rearrange | A setup where agents rearrange themselves dynamically based on the task requirements and environmental conditions. | [Code Link](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/) | Adaptive manufacturing lines, dynamic sales territory realignment, flexible healthcare staffing | -| Concurrent Workflows | Agents perform different tasks simultaneously, coordinating to complete a larger goal. | [Code Link](#) | Concurrent production lines, parallel sales operations, simultaneous patient care processes | -| Sequential Coordination | Agents perform tasks in a specific sequence, where the completion of one task triggers the start of the next. | [Code Link](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/) | Step-by-step assembly lines, sequential sales processes, stepwise patient treatment workflows | -| Parallel Processing | Agents work on different parts of a task simultaneously to speed up the overall process. | [Code Link](#) | Parallel data processing in manufacturing, simultaneous sales analytics, concurrent medical tests | +Sets the condition for the task. +#### Parameters +- `condition` (`Callable`): The condition to set. +#### Examples +```python +>>> def my_condition(): +>>> print("Condition checked") +>>> return True +>>> task.set_condition(my_condition) +``` --------------------------------------------------- +### `is_completed(self)` -# File: swarms/structs/multi_agent_router.md +Checks whether the task has been completed. -# MultiAgentRouter Documentation +#### Returns +- `bool`: `True` if the task has been completed, `False` otherwise. -The MultiAgentRouter is a sophisticated task routing system that efficiently delegates tasks to specialized AI agents. It uses a "boss" agent to analyze incoming tasks and route them to the most appropriate specialized agent based on their capabilities and expertise. +#### Examples -## Table of Contents -- [Installation](#installation) -- [Key Components](#key-components) -- [Arguments](#arguments) -- [Methods](#methods) -- [Usage Examples](#usage-examples) - - [Healthcare](#healthcare-example) - - [Finance](#finance-example) - - [Legal](#legal-example) - - [Research](#research-example) +```python +>>> task.is_completed() +``` -## Installation +### `add_dependency(self, task)` -```bash -pip install swarms -``` +Adds a task to the list of dependencies. -## Key Components +#### Parameters +- `task` (`Task`): The task to add as a dependency. -### Arguments Table +#### Examples -| Argument | Type | Default | Description | -|----------|------|---------|-------------| -| name | str | "swarm-router" | Name identifier for the router instance | -| description | str | "Routes tasks..." | Description of the router's purpose | -| agents | List[Agent] | [] | List of available specialized agents | -| model | str | "gpt-4o-mini" | Base language model for the boss agent | -| temperature | float | 0.1 | Temperature parameter for model outputs | -| shared_memory_system | callable | None | Optional shared memory system | -| output_type | Literal["json", "string"] | "json" | Format of agent outputs | -| execute_task | bool | True | Whether to execute routed tasks | +```python +>>> dependent_task = Task(description="Dependent Task") +>>> task.add_dependency(dependent_task) +``` -### Methods Table +### `set_priority(self, priority: int)` -| Method | Arguments | Returns | Description | -|--------|-----------|---------|-------------| -| route_task | task: str | dict | Routes a single task to appropriate agent | -| batch_run | tasks: List[str] | List[dict] | Sequentially routes multiple tasks | -| concurrent_batch_run | tasks: List[str] | List[dict] | Concurrently routes multiple tasks | -| query_ragent | task: str | str | Queries the research agent | -| find_agent_in_list | agent_name: str | Optional[Agent] | Finds agent by name | +Sets the priority of the task. -## Production Examples +#### Parameters +- `priority` (`int`): The priority to set. -### Healthcare Example +#### Examples ```python -from swarms import Agent, MultiAgentRouter +>>> task.set_priority(5) +``` -# Define specialized healthcare agents -agents = [ - Agent( - agent_name="DiagnosisAgent", - description="Specializes in preliminary symptom analysis and diagnostic suggestions", - system_prompt="""You are a medical diagnostic assistant. Analyze symptoms and provide - evidence-based diagnostic suggestions, always noting this is for informational purposes - only and recommending professional medical consultation.""", - model_name="openai/gpt-4o" - ), - Agent( - agent_name="TreatmentPlanningAgent", - description="Assists in creating treatment plans and medical documentation", - system_prompt="""You are a treatment planning assistant. Help create structured - treatment plans based on confirmed diagnoses, following medical best practices - and guidelines.""", - model_name="openai/gpt-4o" - ), - Agent( - agent_name="MedicalResearchAgent", - description="Analyzes medical research papers and clinical studies", - system_prompt="""You are a medical research analyst. Analyze and summarize medical - research papers, clinical trials, and scientific studies, providing evidence-based - insights.""", - model_name="openai/gpt-4o" - ) -] +### `check_dependency_completion(self)` -# Initialize router -healthcare_router = MultiAgentRouter( - name="Healthcare-Router", - description="Routes medical and healthcare-related tasks to specialized agents", - agents=agents, - model="gpt-4o", - temperature=0.1 -) +Checks whether all the dependencies have been completed. -# Example usage -try: - # Process medical case - case_analysis = healthcare_router.route_task( - """Patient presents with: - - Persistent dry cough for 3 weeks - - Mild fever (38.1°C) - - Fatigue - Analyze symptoms and suggest potential diagnoses for healthcare provider review.""" - ) - - # Research treatment options - treatment_research = healthcare_router.route_task( - """Find recent clinical studies on treatment efficacy for community-acquired - pneumonia in adult patients, focusing on outpatient care.""" - ) - - # Process multiple cases concurrently - cases = [ - "Case 1: Patient symptoms...", - "Case 2: Patient symptoms...", - "Case 3: Patient symptoms..." - ] - concurrent_results = healthcare_router.concurrent_batch_run(cases) - -except Exception as e: - logger.error(f"Error in healthcare processing: {str(e)}") -``` +#### Returns +- `bool`: `True` if all the dependencies have been completed, `False` otherwise. -### Finance Example +#### Examples ```python -# Define specialized finance agents -finance_agents = [ - Agent( - agent_name="MarketAnalysisAgent", - description="Analyzes market trends and provides trading insights", - system_prompt="""You are a financial market analyst. Analyze market data, trends, - and indicators to provide evidence-based market insights and trading suggestions.""", - model_name="openai/gpt-4o" - ), - Agent( - agent_name="RiskAssessmentAgent", - description="Evaluates financial risks and compliance requirements", - system_prompt="""You are a risk assessment specialist. Analyze financial data - and operations for potential risks, ensuring regulatory compliance and suggesting - risk mitigation strategies.""", - model_name="openai/gpt-4o" - ), - Agent( - agent_name="InvestmentAgent", - description="Provides investment strategies and portfolio management", - system_prompt="""You are an investment strategy specialist. Develop and analyze - investment strategies, portfolio allocations, and provide long-term financial - planning guidance.""", - model_name="openai/gpt-4o" - ) -] +>>> task.check_dependency_completion() +``` -# Initialize finance router -finance_router = MultiAgentRouter( - name="Finance-Router", - description="Routes financial analysis and investment tasks", - agents=finance_agents -) +### `context(self, task: "Task" = None, context: List["Task"] = None, *args, **kwargs)` -# Example tasks -tasks = [ - """Analyze current market conditions for technology sector, focusing on: - - AI/ML companies - - Semiconductor manufacturers - - Cloud service providers - Provide risk assessment and investment opportunities.""", - - """Develop a diversified portfolio strategy for a conservative investor with: - - Investment horizon: 10 years - - Risk tolerance: Low to medium - - Initial investment: $500,000 - - Monthly contribution: $5,000""", - - """Conduct risk assessment for a fintech startup's crypto trading platform: - - Regulatory compliance requirements - - Security measures - - Operational risks - - Market risks""" -] +Sets the context for the task. For a sequential workflow, it sequentially adds the context of the previous task in the list. -# Process tasks concurrently -results = finance_router.concurrent_batch_run(tasks) +#### Parameters +- `task` (`Task`, optional): The task whose context is to be set. +- `context` (`List[Task]`, optional): The list of tasks to set the context. + +#### Examples + +```python +>>> task1 = Task(description="Task 1") +>>> task2 = Task(description="Task 2") +>>> task2.context(context=[task1]) ``` -### Legal Example +## Usage Examples + +### Basic Usage ```python -# Define specialized legal agents -legal_agents = [ - Agent( - agent_name="ContractAnalysisAgent", - description="Analyzes legal contracts and documents", - system_prompt="""You are a legal document analyst. Review contracts and legal - documents for key terms, potential issues, and compliance requirements.""", - model_name="openai/gpt-4o" - ), - Agent( - agent_name="ComplianceAgent", - description="Ensures regulatory compliance and updates", - system_prompt="""You are a legal compliance specialist. Monitor and analyze - regulatory requirements, ensuring compliance and suggesting necessary updates - to policies and procedures.""", - model_name="openai/gpt-4o" - ), - Agent( - agent_name="LegalResearchAgent", - description="Conducts legal research and case analysis", - system_prompt="""You are a legal researcher. Research relevant cases, statutes, - and regulations, providing comprehensive legal analysis and citations.""", - model_name="openai/gpt-4o" - ) -] +import os +from dotenv import load_dotenv +from swarms import Agent, OpenAIChat, Task -# Initialize legal router -legal_router = MultiAgentRouter( - name="Legal-Router", - description="Routes legal analysis and compliance tasks", - agents=legal_agents -) +# Load the environment variables +load_dotenv() -# Example usage for legal department -contract_analysis = legal_router.route_task( - """Review the following software licensing agreement: - [contract text] - - Analyze for: - 1. Key terms and conditions - 2. Potential risks and liabilities - 3. Compliance with current regulations - 4. Suggested modifications""" +# Define a function to be used as the action +def my_action(): + print("Action executed") + +# Define a function to be used as the condition +def my_condition(): + print("Condition checked") + return True + +# Create an agent +agent = Agent( + llm=OpenAIChat(openai_api_key=os.environ["OPENAI_API_KEY"]), + max_loops=1, + dashboard=False, ) -``` -## Error Handling and Best Practices +# Create a task +task = Task( + description="Generate a report on the top 3 biggest expenses for small businesses and how businesses can save 20%", + agent=agent, +) -1. Always use try-except blocks for task routing: -```python -try: - result = router.route_task(task) -except Exception as e: - logger.error(f"Task routing failed: {str(e)}") -``` +# Set the action and condition +task.set_action(my_action) +task.set_condition(my_condition) -2. Monitor agent performance: -```python -if result["execution"]["execution_time"] > 5.0: - logger.warning(f"Long execution time for task: {result['task']['original']}") -``` +# Execute the task +print("Executing task...") +task.run() -3. Implement rate limiting for concurrent tasks: -```python -from concurrent.futures import ThreadPoolExecutor -with ThreadPoolExecutor(max_workers=5) as executor: - results = router.concurrent_batch_run(tasks) -``` +# Check if the task is completed +if task.is_completed(): + print("Task completed") +else: + print("Task not completed") -4. Regular agent validation: -```python -for agent in router.agents.values(): - if not agent.validate(): - logger.error(f"Agent validation failed: {agent.name}") +# Output the result of the task +print(f"Task result: {task.result}") ``` -## Performance Considerations - -1. Task Batching +### Scheduled Task Execution -- Group similar tasks together +```python +from datetime import datetime, timedelta +import os +from dotenv import load_dotenv +from swarms import Agent, OpenAIChat, Task -- Use concurrent_batch_run for independent tasks +# Load the environment variables +load_dotenv() -- Monitor memory usage with large batches +# Create an agent +agent = Agent( + llm=OpenAIChat(openai_api_key=os.environ["OPENAI_API_KEY"]), + max_loops=1, + dashboard=False, +) -2. Model Selection +# Create a task +task = Task( + description="Scheduled task example", + agent=agent, + schedule_time=datetime.now() + timedelta(seconds=10) +) -- Choose appropriate models based on task complexity +# Handle scheduled task +task.handle_scheduled_task() +``` -- Balance speed vs. accuracy requirements +### Task with Dependencies -- Consider cost implications +```python +import os +from dotenv import load_dotenv +from swarms import Agent, OpenAIChat, Task -3. Response Caching +# Load the environment variables +load_dotenv() -- Implement caching for frequently requested analyses +# Create agents +agent1 = Agent( + llm=OpenAIChat(openai_api_key=os.environ["OPENAI_API_KEY"]), + max_loops=1, + dashboard=False, +) +agent2 = Agent( + llm=OpenAIChat(openai_api_key=os.environ["OPENAI_API_KEY"]), + max_loops=1, + dashboard=False, +) -- Use shared memory system for repeated queries +# Create tasks +task1 = Task(description="First task", agent=agent1) +task2 = Task(description="Second task", agent=agent2) -- Regular cache invalidation for time-sensitive data +# Add dependency +task2.add_dependency(task1) -## Security Considerations +# Execute tasks +print("Executing first task...") +task1.run() -1. Data Privacy +print("Executing second task...") +task2.run() -- Implement data encryption +# Check if tasks are completed +print(f"Task 1 completed: {task1.is_completed()}") +print(f"Task 2 completed: {task2.is_completed()}") +``` -- Handle sensitive information appropriately +### Task Context -- Regular security audits +```python +import os +from dotenv import load_dotenv +from swarms import Agent, OpenAIChat, Task -2. Access Control +# Load the environment variables +load_dotenv() -- Implement role-based access +# Create an agent +agent = Agent( + llm=OpenAIChat(openai_api_key=os.environ["OPENAI_API_KEY"]), + max_loops -- Audit logging +=1, + dashboard=False, +) -- Regular permission reviews +# Create tasks +task1 = Task(description="First task", agent=agent) +task2 = Task(description="Second task", agent=agent) -## Monitoring and Logging +# Set context for the second task +task2.context(context=[task1]) -1. Performance Metrics +# Execute tasks +print("Executing first task...") +task1.run() -- Response times +print("Executing second task...") +task2.run() -- Success rates +# Output the context of the second task +print(f"Task 2 context: {task2.history}") +``` -- Error rates -- Resource utilization +-------------------------------------------------- -2. Logging +# File: swarms\structs\taskqueue_swarm.md -- Use structured logging +# TaskQueueSwarm Documentation -- Implement log rotation +The `TaskQueueSwarm` class is designed to manage and execute tasks using multiple agents concurrently. This class allows for the orchestration of multiple agents processing tasks from a shared queue, facilitating complex workflows where tasks can be distributed and processed in parallel by different agents. -- Regular log analysis +## Attributes -3. Alerts +| Attribute | Type | Description | +|-----------|------|-------------| +| `agents` | `List[Agent]` | The list of agents in the swarm. | +| `task_queue` | `queue.Queue` | A queue to store tasks for processing. | +| `lock` | `threading.Lock` | A lock for thread synchronization. | +| `autosave_on` | `bool` | Whether to automatically save the swarm metadata. | +| `save_file_path` | `str` | The file path for saving swarm metadata. | +| `workspace_dir` | `str` | The directory path of the workspace. | +| `return_metadata_on` | `bool` | Whether to return the swarm metadata after running. | +| `max_loops` | `int` | The maximum number of loops to run the swarm. | +| `metadata` | `SwarmRunMetadata` | Metadata about the swarm run. | -- Set up alerting for critical errors +## Methods -- Monitor resource usage +### `__init__(self, agents: List[Agent], name: str = "Task-Queue-Swarm", description: str = "A swarm that processes tasks from a queue using multiple agents on different threads.", autosave_on: bool = True, save_file_path: str = "swarm_run_metadata.json", workspace_dir: str = os.getenv("WORKSPACE_DIR"), return_metadata_on: bool = False, max_loops: int = 1, *args, **kwargs)` -- Track API rate limits +The constructor initializes the `TaskQueueSwarm` object. --------------------------------------------------- +- **Parameters:** + - `agents` (`List[Agent]`): The list of agents in the swarm. + - `name` (`str`, optional): The name of the swarm. Defaults to "Task-Queue-Swarm". + - `description` (`str`, optional): The description of the swarm. Defaults to "A swarm that processes tasks from a queue using multiple agents on different threads.". + - `autosave_on` (`bool`, optional): Whether to automatically save the swarm metadata. Defaults to True. + - `save_file_path` (`str`, optional): The file path to save the swarm metadata. Defaults to "swarm_run_metadata.json". + - `workspace_dir` (`str`, optional): The directory path of the workspace. Defaults to os.getenv("WORKSPACE_DIR"). + - `return_metadata_on` (`bool`, optional): Whether to return the swarm metadata after running. Defaults to False. + - `max_loops` (`int`, optional): The maximum number of loops to run the swarm. Defaults to 1. + - `*args`: Variable length argument list. + - `**kwargs`: Arbitrary keyword arguments. -# File: swarms/structs/multi_swarm_orchestration.md +### `add_task(self, task: str)` -# Hierarchical Agent Orchestration Architectures +Adds a task to the queue. -Hierarchical agent orchestration involves organizing multiple agents in structured layers to efficiently handle complex tasks. There are several key architectures available, each with distinct characteristics and use cases. +- **Parameters:** + - `task` (`str`): The task to be added to the queue. -Here are the Hierarchical swarms we support: +### `run(self)` -| Architecture | Strengths | Weaknesses | -|--------------|-----------|------------| -| HHCS | - Clear task routing
- Specialized swarm handling
- Parallel processing capability
- Good for complex multi-domain tasks | - More complex setup
- Overhead in routing
- Requires careful swarm design | -| Auto Agent Builder | - Dynamic agent creation
- Flexible scaling
- Self-organizing
- Good for evolving tasks | - Higher resource usage
- Potential creation overhead
- May create redundant agents | -| SwarmRouter | - Multiple workflow types
- Simple configuration
- Flexible deployment
- Good for varied task types | - Less specialized than HHCS
- Limited inter-swarm communication
- May require manual type selection | +Runs the swarm by having agents pick up tasks from the queue. +- **Returns:** + - `str`: JSON string of the swarm run metadata if `return_metadata_on` is True. +- **Usage Example:** + ```python + from swarms import Agent, TaskQueueSwarm -## Core Architectures -### 1. Hybrid Hierarchical-Cluster Swarm (HHCS) + # Initialize agents + agent1 = Agent(agent_name="Agent1", model_name="gpt-4o") + agent2 = Agent(agent_name="Agent2", model_name="gpt-4o") -Hybrid Hierarchical-Cluster Swarm (HHCS) is architecture that uses a Router Agent to analyze and distribute tasks to other swarms. + # Create the TaskQueueSwarm + swarm = TaskQueueSwarm(agents=[agent1, agent2], max_loops=5) -- Tasks are routed to specialized swarms based on their requirements + # Add tasks to the swarm + swarm.add_task("Analyze the latest market trends") + swarm.add_task("Generate a summary report") -- Enables parallel processing through multiple specialized swarms + # Run the swarm + result = swarm.run() + print(result) # Prints the swarm run metadata + ``` -- Ideal for complex, multi-domain tasks and enterprise-scale operations + This example initializes a `TaskQueueSwarm` with two agents, adds tasks to the queue, and runs the swarm. -- Provides clear task routing but requires more complex setup +### `save_json_to_file(self)` +Saves the swarm run metadata to a JSON file. -```mermaid -flowchart TD - Start([Task Input]) --> RouterAgent[Router Agent] - RouterAgent --> Analysis{Task Analysis} - - Analysis -->|Analyze Requirements| Selection[Swarm Selection] - Selection -->|Select Best Swarm| Route[Route Task] - - Route --> Swarm1[Specialized Swarm 1] - Route --> Swarm2[Specialized Swarm 2] - Route --> SwarmN[Specialized Swarm N] - - Swarm1 -->|Process| Result1[Output 1] - Swarm2 -->|Process| Result2[Output 2] - SwarmN -->|Process| ResultN[Output N] - - Result1 --> Final[Final Output] - Result2 --> Final - ResultN --> Final -``` +### `export_metadata(self)` -### 2. Auto Agent Builder +Exports the swarm run metadata as a JSON string. -Auto Agent Builder is a dynamic agent architecture that creates specialized agents on-demand. +- **Returns:** + - `str`: JSON string of the swarm run metadata. -- Analyzes tasks and automatically builds appropriate agents for the job +## Additional Notes -- Maintains an agent pool that feeds into task orchestration +- The `TaskQueueSwarm` uses threading to process tasks concurrently, which can significantly improve performance for I/O-bound tasks. +- The `reliability_checks` method ensures that the swarm is properly configured before running. +- The swarm automatically handles task distribution among agents and provides detailed metadata about the run. +- Error handling and logging are implemented to track the execution flow and capture any issues during task processing. -- Best suited for evolving requirements and dynamic workloads -- Self-organizing but may have higher resource usage +-------------------------------------------------- -```mermaid -flowchart TD - Task[Task Input] --> Builder[Agent Builder] - Builder --> Analysis{Task Analysis} - - Analysis --> Create[Create Specialized Agents] - Create --> Pool[Agent Pool] - - Pool --> Agent1[Specialized Agent 1] - Pool --> Agent2[Specialized Agent 2] - Pool --> AgentN[Specialized Agent N] - - Agent1 --> Orchestration[Task Orchestration] - Agent2 --> Orchestration - AgentN --> Orchestration - - Orchestration --> Result[Final Result] -``` +# File: swarms\structs\various_execution_methods.md -### 3. SwarmRouter +# Concurrent Agents API Reference +This documentation covers the API for running multiple agents concurrently using various execution strategies. The implementation uses `asyncio` with `uvloop` for enhanced performance and `ThreadPoolExecutor` for handling CPU-bound operations. -SwarmRouter is a flexible system supporting multiple swarm architectures through a simple interface: +## Table of Contents +- [Core Functions](#core-functions) +- [Advanced Functions](#advanced-functions) +- [Utility Functions](#utility-functions) +- [Resource Monitoring](#resource-monitoring) +- [Usage Examples](#usage-examples) -- Sequential workflows +## Core Functions -- Concurrent workflows +### run_agents_concurrently() -- Hierarchical swarms +Primary function for running multiple agents concurrently with optimized performance using both uvloop and ThreadPoolExecutor. -- Group chat interactions +#### Arguments -- Simpler to configure and deploy compared to other architectures +| Parameter | Type | Required | Default | Description | +|-------------|----------------|----------|----------------|-------------| +| agents | List[AgentType]| Yes | - | List of Agent instances to run concurrently | +| task | str | Yes | - | Task string to execute | +| batch_size | int | No | CPU count | Number of agents to run in parallel in each batch | +| max_workers | int | No | CPU count * 2 | Maximum number of threads in the executor | -- Best for general-purpose tasks and smaller scale operations +#### Returns +`List[Any]`: List of outputs from each agent -- Recommended for 5-20 agents. +#### Flow Diagram ```mermaid -flowchart TD - Input[Task Input] --> Router[Swarm Router] - Router --> TypeSelect{Swarm Type Selection} - - TypeSelect -->|Sequential| Seq[Sequential Workflow] - TypeSelect -->|Concurrent| Con[Concurrent Workflow] - TypeSelect -->|Hierarchical| Hier[Hierarchical Swarm] - TypeSelect -->|Group| Group[Group Chat] +graph TD + A[Start] --> B[Initialize ThreadPoolExecutor] + B --> C[Split Agents into Batches] + C --> D[Process Batch] + D --> E{More Batches?} + E -->|Yes| D + E -->|No| F[Combine Results] + F --> G[Return Results] - Seq --> Output[Task Output] - Con --> Output - Hier --> Output - Group --> Output + subgraph "Batch Processing" + D --> H[Run Agents Async] + H --> I[Wait for Completion] + I --> J[Collect Batch Results] + end ``` -## Use Case Recommendations - -### **HHCS**: Best for: - -- Enterprise-scale operations +### run_agents_sequentially() -- Multi-domain problems +Runs multiple agents sequentially for baseline comparison or simple use cases. -- Complex task routing +#### Arguments -- Parallel processing needs +| Parameter | Type | Required | Default | Description | +|-----------|----------------|----------|---------|-------------| +| agents | List[AgentType]| Yes | - | List of Agent instances to run | +| task | str | Yes | - | Task string to execute | -### **Auto Agent Builder**: Best for: +#### Returns +`List[Any]`: List of outputs from each agent -- Dynamic workloads +## Advanced Functions -- Evolving requirements +### run_agents_with_different_tasks() -- Research and development +Runs multiple agents with different tasks concurrently. -- Exploratory tasks +#### Arguments -### **SwarmRouter**: Best for: +| Parameter | Type | Required | Default | Description | +|-----------------|-------------------------------|----------|----------------|-------------| +| agent_task_pairs| List[tuple[AgentType, str]] | Yes | - | List of (agent, task) tuples | +| batch_size | int | No | CPU count | Number of agents to run in parallel | +| max_workers | int | No | CPU count * 2 | Maximum number of threads | -- General purpose tasks +### run_agents_with_timeout() -- Quick deployment +Runs multiple agents concurrently with timeout limits. -- Mixed workflow types +#### Arguments -- Smaller scale operations +| Parameter | Type | Required | Default | Description | +|-------------|----------------|----------|----------------|-------------| +| agents | List[AgentType]| Yes | - | List of Agent instances | +| task | str | Yes | - | Task string to execute | +| timeout | float | Yes | - | Timeout in seconds for each agent | +| batch_size | int | No | CPU count | Number of agents to run in parallel | +| max_workers | int | No | CPU count * 2 | Maximum number of threads | -## Documentation Links +## Usage Examples -### HHCS Documentation: +```python +from swarms.structs.agent import Agent +from swarms.structs.multi_agent_exec import ( + run_agents_concurrently, + run_agents_with_timeout, + run_agents_with_different_tasks +) -- [Hybrid Hierarchical-Cluster Swarm Documentation](https://docs.swarms.world/en/latest/swarms/structs/hhcs/) +# Initialize agents using only the built-in model_name parameter +agents = [ + Agent( + agent_name=f"Analysis-Agent-{i}", + system_prompt="You are a financial analysis expert", + model_name="gpt-4o-mini", + max_loops=1 + ) + for i in range(5) +] -- Covers detailed implementation, constructor arguments, and full examples +# Basic concurrent execution +task = "Analyze the impact of rising interest rates on tech stocks" +outputs = run_agents_concurrently(agents, task) -### Auto Agent Builder Documentation: - -- [Agent Builder Documentation](https://docs.swarms.world/en/latest/swarms/structs/auto_agent_builder/) +# Running with timeout +outputs_with_timeout = run_agents_with_timeout( + agents=agents, + task=task, + timeout=30.0, + batch_size=2 +) -- Includes enterprise use cases, best practices, and integration patterns +# Running different tasks +task_pairs = [ + (agents[0], "Analyze tech stocks"), + (agents[1], "Analyze energy stocks"), + (agents[2], "Analyze retail stocks") +] +different_outputs = run_agents_with_different_tasks(task_pairs) +``` -3. SwarmRouter Documentation: +## Resource Monitoring -- [SwarmRouter Documentation](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/) +### ResourceMetrics -- Provides comprehensive API reference, advanced usage, and use cases +A dataclass for system resource metrics. -## Best Practices for Selection +#### Properties -### **Evaluate Task Complexity** - -- Simple tasks → SwarmRouter +| Property | Type | Description | +|----------------|-------|-------------| +| cpu_percent | float | Current CPU usage percentage | +| memory_percent | float | Current memory usage percentage | +| active_threads | int | Number of active threads | -- Complex, multi-domain tasks → HHCS +### run_agents_with_resource_monitoring() -- Dynamic, evolving tasks → Auto Agent Builder +Runs agents with system resource monitoring and adaptive batch sizing. -### **Consider Scale** - -- Small scale → SwarmRouter +#### Arguments -- Large scale → HHCS +| Parameter | Type | Required | Default | Description | +|------------------|----------------|----------|---------|-------------| +| agents | List[AgentType]| Yes | - | List of Agent instances | +| task | str | Yes | - | Task string to execute | +| cpu_threshold | float | No | 90.0 | Max CPU usage percentage | +| memory_threshold | float | No | 90.0 | Max memory usage percentage | +| check_interval | float | No | 1.0 | Resource check interval in seconds | -- Variable scale → Auto Agent Builder +## Performance Considerations -### **Resource Availability** - -- Limited resources → SwarmRouter +- Default batch sizes and worker counts are optimized based on CPU cores +- Resource monitoring helps prevent system overload +- Using `uvloop` provides better performance than standard `asyncio` -- Abundant resources → HHCS or Auto Agent Builder +## Error Handling -- Dynamic resources → Auto Agent Builder +- Functions handle asyncio event loop creation/retrieval +- Timeout mechanism prevents infinite waiting +- Resource monitoring allows for adaptive performance adjustment -### **Development Time** +-------------------------------------------------- -- Quick deployment → SwarmRouter +# File: swarms\structs\yaml_model.md -- Complex system → HHCS +# YamlModel: A Pydantic Model for YAML Data -- Experimental system → Auto Agent Builder +The `YamlModel` class, derived from `BaseModel` in Pydantic, offers a convenient way to work with YAML data in your Python applications. It provides methods for serialization (converting to YAML), deserialization (creating an instance from YAML), and schema generation. This documentation will delve into the functionalities of `YamlModel` and guide you through its usage with illustrative examples. +### Purpose and Functionality -This documentation provides a high-level overview of the main hierarchical agent orchestration architectures available in the system. Each architecture has its own strengths and ideal use cases, and the choice between them should be based on specific project requirements, scale, and complexity. +The primary purpose of `YamlModel` is to streamline the interaction between your Python code and YAML data. It accomplishes this by: +* **Serialization:** Transforming a `YamlModel` instance into a YAML string representation using the `to_yaml()` method. +* **Deserialization:** Constructing a `YamlModel` instance from a provided YAML string using the `from_yaml()` class method. +* **JSON to YAML Conversion:** Facilitating the conversion of JSON data to YAML format through the `json_to_yaml()` static method. +* **Saving to YAML File:** Enabling the storage of `YamlModel` instances as YAML files using the `save_to_yaml()` method. +* (Future Implementation) **Schema Generation:** The `create_yaml_schema()` class method (not yet implemented but included for future reference) will generate a YAML schema that reflects the structure of the `YamlModel` class and its fields. --------------------------------------------------- +### Class Definition and Arguments -# File: swarms/structs/multi_threaded_workflow.md +The `YamlModel` class inherits from Pydantic's `BaseModel` class. You can define your custom YAML models by creating subclasses of `YamlModel` and specifying your data fields within the class definition. Here's the breakdown of the `YamlModel` class and its methods: -# MultiThreadedWorkflow Documentation +```python +class YamlModel(BaseModel): + """ + A Pydantic model class for working with YAML data. + """ -The `MultiThreadedWorkflow` class represents a multi-threaded workflow designed to execute tasks concurrently using a thread pool. This class is highly useful in scenarios where tasks need to be executed in parallel to improve performance and efficiency. The workflow ensures that tasks are managed in a priority-based queue, and it includes mechanisms for retrying failed tasks and optionally saving task results automatically. + def to_yaml(self): + """ + Serialize the Pydantic model instance to a YAML string. + """ + return yaml.safe_dump(self.dict(), sort_keys=False) -## Class Definition + @classmethod + def from_yaml(cls, yaml_str: str): + """ + Create an instance of the class from a YAML string. -### `MultiThreadedWorkflow` + Args: + yaml_str (str): The YAML string to parse. -## Parameters + Returns: + cls: An instance of the class with attributes populated from the YAML data. + Returns None if there was an error loading the YAML data. + """ + # ... -| Parameter | Type | Default | Description | -|---------------|-----------------------|---------|---------------------------------------------------------------| -| `max_workers` | `int` | `5` | The maximum number of worker threads in the thread pool. | -| `autosave` | `bool` | `True` | Flag indicating whether to automatically save task results. | -| `tasks` | `List[PriorityTask]` | `None` | List of priority tasks to be executed. | -| `retry_attempts` | `int` | `3` | The maximum number of retry attempts for failed tasks. | -| `*args` | `tuple` | | Variable length argument list. | -| `**kwargs` | `dict` | | Arbitrary keyword arguments. | + @staticmethod + def json_to_yaml(json_str: str): + """ + Convert a JSON string to a YAML string. + """ + # ... -## Attributes + def save_to_yaml(self, filename: str): + """ + Save the Pydantic model instance as a YAML file. + """ + # ... -| Attribute | Type | Description | -|------------------|--------------------|----------------------------------------------------------------| -| `max_workers` | `int` | The maximum number of worker threads in the thread pool. | -| `autosave` | `bool` | Flag indicating whether to automatically save task results. | -| `retry_attempts` | `int` | The maximum number of retry attempts for failed tasks. | -| `tasks_queue` | `PriorityQueue` | The queue that holds the priority tasks. | -| `lock` | `Lock` | The lock used for thread synchronization. | + # TODO: Implement a method to create a YAML schema from the model fields + # @classmethod + # def create_yaml_schema(cls): + # # ... + """ +``` -## Methods +**Arguments:** -### `run` +* `self` (implicit): Refers to the current instance of the `YamlModel` class. +* `yaml_str` (str): The YAML string used for deserialization in the `from_yaml()` method. +* `json_str` (str): The JSON string used for conversion to YAML in the `json_to_yaml()` method. +* `filename` (str): The filename (including path) for saving the YAML model instance in the `save_to_yaml()` method. +### Detailed Method Descriptions -#### Description +**1. to_yaml()** -The `run` method executes the tasks stored in the priority queue using a thread pool. It handles task completion, retries failed tasks up to a specified number of attempts, and optionally saves the results of tasks if the autosave flag is set. +This method transforms an instance of the `YamlModel` class into a YAML string representation. It utilizes the `yaml.safe_dump()` function from the `PyYAML` library to ensure secure YAML data generation. The `sort_keys=False` argument guarantees that the order of keys in the resulting YAML string remains consistent with the order of fields defined in your `YamlModel` subclass. -#### Usage Example +**Example:** ```python -from swarms import MultiThreadedWorkflow, PriorityTask, Task +class User(YamlModel): + name: str + age: int + is_active: bool -# Define some tasks -tasks = [PriorityTask(task=Task()), PriorityTask(task=Task())] +user = User(name="Bob", age=30, is_active=True) +yaml_string = user.to_yaml() +print(yaml_string) +``` -# Create a MultiThreadedWorkflow instance -workflow = MultiThreadedWorkflow(max_workers=3, autosave=True, tasks=tasks, retry_attempts=2) +This code will output a YAML string representation of the `user` object, resembling: -# Run the workflow -results = workflow.run() -print(results) +```yaml +name: Bob +age: 30 +is_active: true ``` -### `_autosave_task_result` - -#### Description +### Detailed Method Descriptions -The `_autosave_task_result` method is responsible for saving the results of a task. It uses a thread lock to ensure that the autosave operation is thread-safe. +**2. from_yaml(cls, yaml_str)** (Class Method) -#### Usage Example +The `from_yaml()` class method is responsible for constructing a `YamlModel` instance from a provided YAML string. -This method is intended for internal use and is typically called by the `run` method. However, here is an example of how it might be used directly: +* **Arguments:** + * `cls` (class): The class representing the desired YAML model (the subclass of `YamlModel` that matches the structure of the YAML data). + * `yaml_str` (str): The YAML string containing the data to be parsed and used for creating the model instance. -```python -# Create a task and result -task = Task() -result = task.run() +* **Returns:** + * `cls` (instance): An instance of the specified class (`cls`) populated with the data extracted from the YAML string. If an error occurs during parsing, it returns `None`. -# Autosave the result -workflow = MultiThreadedWorkflow() -workflow._autosave_task_result(task, result) -``` +* **Error Handling:** -## Detailed Functionality and Usage +The `from_yaml()` method employs `yaml.safe_load()` for secure YAML parsing. It incorporates a `try-except` block to handle potential `ValueError` exceptions that might arise during the parsing process. If an error is encountered, it logs the error message and returns `None`. -### Initialization +**Example:** -When an instance of `MultiThreadedWorkflow` is created, it initializes the following: +```python +class User(YamlModel): + name: str + age: int + is_active: bool -- **max_workers**: Sets the maximum number of threads that can run concurrently. -- **autosave**: Determines if the task results should be saved automatically. -- **tasks**: Accepts a list of tasks that need to be executed. If no tasks are provided, an empty list is used. -- **retry_attempts**: Sets the maximum number of retry attempts for failed tasks. -- **tasks_queue**: A priority queue to manage tasks based on their priority. -- **lock**: A threading lock to ensure thread-safe operations. +yaml_string = """ +name: Alice +age: 25 +is_active: false +""" -### Running Tasks +user = User.from_yaml(yaml_string) +print(user.name) # Output: Alice +``` -The `run` method performs the following steps: +**3. json_to_yaml(json_str)** (Static Method) -1. **Initialize Results and Executor**: Creates a list to store results and a `ThreadPoolExecutor` to manage the threads. -2. **Submit Tasks**: Iterates over the tasks in the queue, submitting them to the executor for execution and storing the future objects. -3. **Monitor Completion**: Uses the `wait` function to monitor the completion of tasks. Once a task is completed, it retrieves the result or catches exceptions. -4. **Retry Mechanism**: If a task fails, it checks the number of attempts made and retries the task if the limit is not reached. -5. **Autosave**: If the `autosave` flag is set, the `_autosave_task_result` method is called to save the task results. +This static method in the `YamlModel` class serves the purpose of converting a JSON string into a YAML string representation. -### Autosave Task Result +* **Arguments:** + * `json_str` (str): The JSON string that needs to be converted to YAML format. -The `_autosave_task_result` method handles the saving of task results. It uses a threading lock to ensure that the save operation is not interrupted by other threads. +* **Returns:** + * `str`: The converted YAML string representation of the provided JSON data. -## Additional Information and Tips +* **Functionality:** -- **Thread Safety**: The use of threading locks ensures that the operations are thread-safe, preventing race conditions. -- **Logging**: The class uses the logging module to log information about task completion, retries, and failures. -- **Error Handling**: The retry mechanism helps in handling transient errors by attempting to re-execute failed tasks. +The `json_to_yaml()` method leverages the `json.loads()` function to parse the JSON string into a Python dictionary. Subsequently, it utilizes `yaml.dump()` to generate the corresponding YAML string representation from the parsed dictionary. -## References and Resources +**Example:** -For more information on threading and concurrent execution in Python, refer to the following resources: +```python +json_string = '{"name": "Charlie", "age": 42, "is_active": true}' +yaml_string = YamlModel.json_to_yaml(json_string) +print(yaml_string) +``` -- [Python Threading Documentation](https://docs.python.org/3/library/threading.html) -- [Python Concurrent Futures Documentation](https://docs.python.org/3/library/concurrent.futures.html) +This code snippet will convert the JSON data to a YAML string, likely resembling: +```yaml +name: Charlie +age: 42 +is_active: true +``` --------------------------------------------------- +**4. save_to_yaml(self, filename)** -# File: swarms/structs/round_robin_swarm.md +The `save_to_yaml()` method facilitates the storage of a `YamlModel` instance as a YAML file. -# RoundRobin: Round-Robin Task Execution in a Swarm +* **Arguments:** + * `self` (implicit): Refers to the current instance of the `YamlModel` class that you intend to save. + * `filename` (str): The desired filename (including path) for the YAML file. -## Introduction +* **Functionality:** -The `RoundRobinSwarm` class is designed to manage and execute tasks among multiple agents in a round-robin fashion. This approach ensures that each agent in a swarm receives an equal opportunity to execute tasks, which promotes fairness and efficiency in distributed systems. It is particularly useful in environments where collaborative, sequential task execution is needed among various agents. +The `save_to_yaml()` method employs the previously explained `to_yaml()` method to generate a YAML string representation of the `self` instance. It then opens the specified file in write mode (`"w"`) and writes the YAML string content to the file. -## Conceptual Overview +**Example:** -### What is Round-Robin? +```python +class Employee(YamlModel): + name: str + department: str + salary: float -Round-robin is a scheduling technique commonly used in computing for managing processes in shared systems. It involves assigning a fixed time slot to each process and cycling through all processes in a circular order without prioritization. In the context of swarms of agents, this method ensures equitable distribution of tasks and resource usage among all agents. +employee = Employee(name="David", department="Engineering", salary=95000.00) +employee.save_to_yaml("employee.yaml") +``` -### Application in Swarms +This code will create a YAML file named "employee.yaml" containing the serialized representation of the `employee` object. -In swarms, `RoundRobinSwarm` utilizes the round-robin scheduling to manage tasks among agents like software components, autonomous robots, or virtual entities. This strategy is beneficial where tasks are interdependent or require sequential processing. -## Class Attributes +### More Usage Examples ++ -- `agents (List[Agent])`: List of agents participating in the swarm. -- `verbose (bool)`: Enables or disables detailed logging of swarm operations. -- `max_loops (int)`: Limits the number of times the swarm cycles through all agents. -- `index (int)`: Maintains the current position in the agent list to ensure round-robin execution. +```python +class User(YamlModel): + name: str + age: int + is_active: bool -## Methods +# Create an instance of the User model +user = User(name="Alice", age=30, is_active=True) -### `__init__` +# Serialize the User instance to YAML and print it +yaml_string = user.to_yaml() +print(yaml_string) +``` -Initializes the swarm with the provided list of agents, verbosity setting, and operational parameters. +This code snippet demonstrates the creation of a `User` instance and its subsequent serialization to a YAML string using the `to_yaml()` method. The printed output will likely resemble: -**Parameters:** -- `agents`: Optional list of agents in the swarm. -- `verbose`: Boolean flag for detailed logging. -- `max_loops`: Maximum number of execution cycles. -- `callback`: Optional function called after each loop. +```yaml +name: Alice +age: 30 +is_active: true +``` -### `run` +### Converting JSON to YAML -Executes a specified task across all agents in a round-robin manner, cycling through each agent repeatedly for the number of specified loops. +```python +# Convert JSON string to YAML and print +json_string = '{"name": "Bob", "age": 25, "is_active": false}' +yaml_string = YamlModel.json_to_yaml(json_string) +print(yaml_string) +``` -**Conceptual Behavior:** -- Distribute the task sequentially among all agents starting from the current index. -- Each agent processes the task and potentially modifies it or produces new output. -- After an agent completes its part of the task, the index moves to the next agent. -- This cycle continues until the specified maximum number of loops is completed. -- Optionally, a callback function can be invoked after each loop to handle intermediate results or perform additional actions. +This example showcases the conversion of a JSON string containing user data into a YAML string representation using the `json_to_yaml()` static method. The resulting YAML string might look like: -## Examples -### Example 1: Load Balancing Among Servers +```yaml +name: Bob +age: 25 +is_active: false +``` -In this example, `RoundRobinSwarm` is used to distribute network requests evenly among a group of servers. This is common in scenarios where load balancing is crucial for maintaining system responsiveness and scalability. +### Saving User Instance to YAML File ```python -from swarms import Agent, RoundRobinSwarm -from swarm_models import OpenAIChat +# Save the User instance to a YAML file +user.save_to_yaml("user.yaml") +``` +This code demonstrates the utilization of the `save_to_yaml()` method to store the `user` instance as a YAML file named "user.yaml". The contents of the file will mirror the serialized YAML string representation of the user object. -# Initialize the LLM -llm = OpenAIChat() +## Additional Considerations -# Define sales agents -sales_agent1 = Agent( - agent_name="Sales Agent 1 - Automation Specialist", - system_prompt="You're Sales Agent 1, your purpose is to generate sales for a company by focusing on the benefits of automating accounting processes!", - agent_description="Generate sales by focusing on the benefits of automation!", - llm=llm, - max_loops=1, - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - context_length=1000, -) +* Ensure you have the `PyYAML` library installed (`pip install pyyaml`) to leverage the YAML parsing and serialization functionalities within `YamlModel`. +* Remember that the `create_yaml_schema()` method is not yet implemented but serves as a placeholder for future enhancements. +* For complex data structures within your YAML models, consider leveraging Pydantic's data validation and nested model capabilities for robust data management. -sales_agent2 = Agent( - agent_name="Sales Agent 2 - Cost Saving Specialist", - system_prompt="You're Sales Agent 2, your purpose is to generate sales for a company by emphasizing the cost savings of using swarms of agents!", - agent_description="Generate sales by emphasizing cost savings!", - llm=llm, - max_loops=1, - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - context_length=1000, -) +## Conclusion -sales_agent3 = Agent( - agent_name="Sales Agent 3 - Efficiency Specialist", - system_prompt="You're Sales Agent 3, your purpose is to generate sales for a company by highlighting the efficiency and accuracy of our swarms of agents in accounting processes!", - agent_description="Generate sales by highlighting efficiency and accuracy!", - llm=llm, - max_loops=1, - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - context_length=1000, -) +The `YamlModel` class in Pydantic offers a streamlined approach to working with YAML data in your Python projects. By employing the provided methods (`to_yaml()`, `from_yaml()`, `json_to_yaml()`, and `save_to_yaml()`), you can efficiently convert between Python objects and YAML representations, facilitating data persistence and exchange. This comprehensive documentation empowers you to effectively utilize `YamlModel` for your YAML data processing requirements. -# Initialize the swarm with sales agents -sales_swarm = RoundRobinSwarm(agents=[sales_agent1, sales_agent2, sales_agent3], verbose=True) +-------------------------------------------------- -# Define a sales task -task = "Generate a sales email for an accountant firm executive to sell swarms of agents to automate their accounting processes." +# File: swarms\support.md -# Distribute sales tasks to different agents -for _ in range(5): # Repeat the task 5 times - results = sales_swarm.run(task) - print("Sales generated:", results) -``` +# Technical Support +*Getting Help with the Swarms Multi-Agent Framework* +--- -## Conclusion +## **Getting Started with Support** -The RoundRobinSwarm class provides a robust and flexible framework for managing tasks among multiple agents in a fair and efficient manner. This class is especially useful in environments where tasks need to be distributed evenly among a group of agents, ensuring that all tasks are handled timely and effectively. Through the round-robin algorithm, each agent in the swarm is guaranteed an equal opportunity to contribute to the overall task, promoting efficiency and collaboration. +The Swarms team is committed to providing exceptional technical support to help you build production-grade multi-agent systems. Whether you're experiencing bugs, need implementation guidance, or want to request new features, we have multiple channels to ensure you get the help you need quickly and efficiently. +--- --------------------------------------------------- +## **Support Channels Overview** -# File: swarms/structs/sequential_workflow.md +| **Support Type** | **Best For** | **Response Time** | **Channel** | +|------------------|--------------|-------------------|-------------| +| **Bug Reports** | Code issues, errors, unexpected behavior | < 24 hours | [GitHub Issues](https://github.com/kyegomez/swarms/issues) | +| **Major Features (SIPs)** | New agent types, core changes, integrations | 1-2 weeks | [SIP Guidelines](protocol/sip.md) | +| **Minor Features** | Small enhancements, straightforward additions | < 48 hours | [GitHub Issues](https://github.com/kyegomez/swarms/issues) | +| **Private Issues** | Security concerns, enterprise consulting | < 4 hours | [Book Support Call](https://cal.com/swarms/swarms-technical-support?overlayCalendar=true) | +| **Real-time Help** | Quick questions, community discussions | Immediate | [Discord Community](https://discord.gg/jM3Z6M9uMq) | +| **Documentation** | Usage guides, examples, tutorials | Self-service | [docs.swarms.world](https://docs.swarms.world) | -# SequentialWorkflow Documentation +--- -**Overview:** -A Sequential Swarm architecture processes tasks in a linear sequence. Each agent completes its task before passing the result to the next agent in the chain. This architecture ensures orderly processing and is useful when tasks have dependencies. [Learn more here in the docs:](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/) +## **Reporting Bugs & Technical Issues** -**Use-Cases:** +### **When to Use GitHub Issues** -- Workflows where each step depends on the previous one, such as assembly lines or sequential data processing. +Use GitHub Issues for: -- Scenarios requiring strict order of operations. +- Code bugs and errors -```mermaid -graph TD - A[First Agent] --> B[Second Agent] - B --> C[Third Agent] - C --> D[Fourth Agent] -``` +- Installation problems -## Attributes +- Documentation issues -| Attribute | Type | Description | -|------------------|---------------|--------------------------------------------------| -| `agents` | `List[Agent]` | The list of agents in the workflow. | -| `flow` | `str` | A string representing the order of agents. | -| `agent_rearrange`| `AgentRearrange` | Manages the dynamic execution of agents. | +- Performance problems -## Methods +- API inconsistencies -### `__init__(self, agents: List[Agent] = None, max_loops: int = 1, *args, **kwargs)` +- Public technical discussions -The constructor initializes the `SequentialWorkflow` object. +### **How to Create an Effective Bug Report** -- **Parameters:** - - `agents` (`List[Agent]`, optional): The list of agents in the workflow. Defaults to `None`. - - `max_loops` (`int`, optional): The maximum number of loops to execute the workflow. Defaults to `1`. - - `*args`: Variable length argument list. - - `**kwargs`: Arbitrary keyword arguments. +1. **Visit our Issues page**: [https://github.com/kyegomez/swarms/issues](https://github.com/kyegomez/swarms/issues) -### `run(self, task: str) -> str` +2. **Search existing issues** to avoid duplicates -Runs the specified task through the agents in the dynamically constructed flow. +3. **Click "New Issue"** and select the appropriate template -- **Parameters:** - - `task` (`str`): The task for the agents to execute. +4. **Include the following information**: -- **Returns:** - - `str`: The final result after processing through all agents. +## Bug Description -## **Usage Example:** +A clear description of what the bug is. -```python +## Environment -from swarms import Agent, SequentialWorkflow +- Swarms version: [e.g., 5.9.2] -# Initialize agents for individual tasks -agent1 = Agent( - agent_name="ICD-10 Code Analyzer", - system_prompt="Analyze medical data and provide relevant ICD-10 codes.", - model_name="gpt-4o", - max_loops=1, -) -agent2 = Agent( - agent_name="ICD-10 Code Summarizer", - system_prompt="Summarize the findings and suggest ICD-10 codes.", - model_name="gpt-4o", - max_loops=1, -) +- Python version: [e.g., 3.9.0] -# Create the Sequential workflow -workflow = SequentialWorkflow( - agents=[agent1, agent2], max_loops=1, verbose=False -) +- Operating System: [e.g., Ubuntu 20.04, macOS 14, Windows 11] -# Run the workflow -workflow.run( - "Analyze the medical report and provide the appropriate ICD-10 codes." -) +- Model provider: [e.g., OpenAI, Anthropic, Groq] -``` -This example initializes a `SequentialWorkflow` with three agents and executes a task, printing the final result. +## Steps to Reproduce -## **Notes:** +1. Step one +2. Step two +3. Step three -- Logs the task execution process and handles any exceptions that occur during the task execution. +## Expected Behavior -### Logging and Error Handling +What you expected to happen. -The `run` method includes logging to track the execution flow and captures errors to provide detailed information in case of failures. This is crucial for debugging and ensuring smooth operation of the workflow. +## Actual Behavior -## Additional Tips +What actually happened. -- Ensure that the agents provided to the `SequentialWorkflow` are properly initialized and configured to handle the tasks they will receive. +## Code Sample -- The `max_loops` parameter can be used to control how many times the workflow should be executed, which is useful for iterative processes. +```python +# Minimal code that reproduces the issue +from swarms import Agent -- Utilize the logging information to monitor and debug the task execution process. +agent = Agent(model_name="gpt-4o-mini") +result = agent.run("Your task here") +``` +## Error Messages --------------------------------------------------- +Paste any error messages or stack traces here -# File: swarms/structs/spreadsheet_swarm.md -# SpreadSheetSwarm Documentation +## Additional Context ---- +Any other context, screenshots, or logs that might help. -## Class Definition +### **Issue Templates Available** -```python -class SpreadSheetSwarm: -``` +| Template | Use Case | +|----------|----------| +| **Bug Report** | Standard bug reporting template | +| **Documentation** | Issues with docs, guides, examples | +| **Feature Request** | Suggesting new functionality | +| **Question** | General questions about usage | +| **Enterprise** | Enterprise-specific issues | -## Full Path +--- -```python -from swarms.structs.spreadsheet_swarm import SpreadSheetSwarm -``` +## **Private & Enterprise Support** -### Attributes +### **When to Book a Private Support Call** -The `SpreadSheetSwarm` class contains several attributes that define its behavior and configuration. These attributes are initialized in the constructor (`__init__` method) and are used throughout the class to manage the swarm's operations. +Book a private consultation for: -| Attribute | Type | Description | -|--------------------|-----------------------------------|---------------------------------------------------------------------------------------------| -| `name` | `str` | The name of the swarm. | -| `description` | `str` | A description of the swarm's purpose. | -| `agents` | `Union[Agent, List[Agent]]` | The agents participating in the swarm. Can be a single agent or a list of agents. | -| `autosave_on` | `bool` | Flag indicating whether autosave is enabled. | -| `save_file_path` | `str` | The file path where the swarm data will be saved. | -| `task_queue` | `queue.Queue` | The queue that stores tasks to be processed by the agents. | -| `lock` | `threading.Lock` | A lock used for thread synchronization to prevent race conditions. | -| `metadata` | `SwarmRunMetadata` | Metadata for the swarm run, including start time, end time, tasks completed, and outputs. | -| `run_all_agents` | `bool` | Flag indicating whether to run all agents or just one. | -| `max_loops` | `int` | The number of times to repeat the task. | -| `workspace_dir` | `str` | The directory where the workspace is located, retrieved from environment variables. | +- Security vulnerabilities or concerns -### Parameters +- Enterprise deployment guidance -- **`name`** (`str`, optional): The name of the swarm. Default is `"Spreadsheet-Swarm"`. -- **`description`** (`str`, optional): A brief description of the swarm. Default is `"A swarm that processes tasks from a queue using multiple agents on different threads."`. -- **`agents`** (`Union[Agent, List[Agent]]`, optional): The agents participating in the swarm. Default is an empty list. -- **`autosave_on`** (`bool`, optional): A flag to indicate if autosave is enabled. Default is `True`. -- **`save_file_path`** (`str`, optional): The file path where swarm data will be saved. Default is `"spreedsheet_swarm.csv"`. -- **`run_all_agents`** (`bool`, optional): Flag to determine if all agents should run. Default is `True`. -- **`max_loops`** (`int`, optional): The number of times to repeat the task. Default is `1`. -- **`workspace_dir`** (`str`, optional): The directory where the workspace is located. Default is retrieved from environment variable `WORKSPACE_DIR`. +- Custom implementation consulting -### Constructor (`__init__`) +- Architecture review sessions -The constructor initializes the `SpreadSheetSwarm` with the provided parameters. It sets up the task queue, locks for thread synchronization, and initializes the metadata. +- Performance optimization ---- +- Integration troubleshooting -## Methods +- Strategic technical planning -### `reliability_check` -```python -def reliability_check(self): -``` +### **How to Schedule Support** -#### Description +1. **Visit our booking page**: [https://cal.com/swarms/swarms-technical-support?overlayCalendar=true](https://cal.com/swarms/swarms-technical-support?overlayCalendar=true) -The `reliability_check` method performs a series of checks to ensure that the swarm is properly configured before it begins processing tasks. It verifies that there are agents available and that a valid file path is provided for saving the swarm's data. If any of these checks fail, an exception is raised. +2. **Select an available time** that works for your timezone -#### Raises +3. **Provide details** about your issue or requirements -- **`ValueError`**: Raised if no agents are provided or if no save file path is specified. +4. **Prepare for the call**: + - Have your code/environment ready -#### Example + - Prepare specific questions -```python -swarm = SpreadSheetSwarm(agents=[agent1, agent2]) -swarm.reliability_check() -``` + - Include relevant error messages or logs ---- + - Share your use case and goals -### `run` -```python -def run(self, task: str, *args, **kwargs): -``` +### **What to Expect** -#### Description +- **Direct access** to Swarms core team members -The `run` method starts the task processing using the swarm. Depending on the configuration, it can either run all agents or a specific subset of them. The method tracks the start and end times of the task, executes the task multiple times if specified, and logs the results. +- **Screen sharing** for live debugging -#### Parameters +- **Custom solutions** tailored to your needs -- **`task`** (`str`): The task to be executed by the swarm. -- **`*args`**: Additional positional arguments to pass to the agents. -- **`**kwargs`**: Additional keyword arguments to pass to the agents. +- **Follow-up resources** and documentation -#### Example +- **Priority support** for implementation -```python -swarm = SpreadSheetSwarm(agents=[agent1, agent2]) -swarm.run("Process Data") -``` --- -### `export_to_json` +## **Real-Time Community Support** -```python -def export_to_json(self): -``` +### **Join Our Discord Community** -#### Description +Get instant help from our active community of developers and core team members. -The `export_to_json` method generates a JSON representation of the swarm's metadata. This can be useful for exporting the results to an external system or for logging purposes. +**Discord Benefits:** -#### Returns +- **24/7 availability** - Someone is always online -- **`str`**: The JSON representation of the swarm's metadata. +- **Instant responses** - Get help in real-time -#### Example +- **Community wisdom** - Learn from other developers -```python -json_data = swarm.export_to_json() -print(json_data) -``` +- **Specialized channels** - Find the right help quickly ---- +- **Latest updates** - Stay informed about new releases -### `data_to_json_file` -```python -def data_to_json_file(self): -``` +### **Discord Channels Guide** -#### Description +| Channel | Purpose | +|---------|---------| +| **#general** | General discussions and introductions | +| **#technical-support** | Technical questions and troubleshooting | +| **#showcase** | Share your Swarms projects and demos | +| **#feature-requests** | Discuss potential new features | +| **#announcements** | Official updates and releases | +| **#resources** | Helpful links, tutorials, and guides | -The `data_to_json_file` method saves the swarm's metadata as a JSON file in the specified workspace directory. The file name is generated using the swarm's name and run ID. +### **Getting Help on Discord** -#### Example +1. **Join here**: [https://discord.gg/jM3Z6M9uMq](https://discord.gg/jM3Z6M9uMq) -```python -swarm.data_to_json_file() -``` +2. **Read the rules** and introduce yourself in #general ---- +3. **Use the right channel** for your question type -### `_track_output` +4. **Provide context** when asking questions: + ``` + Python version: 3.9 + Swarms version: 5.9.2 + OS: macOS 14 + Question: How do I implement custom tools with MCP? + What I tried: [paste your code] + Error: [paste error message] + ``` -```python -def _track_output(self, agent: Agent, task: str, result: str): -``` +5. **Be patient and respectful** - our community loves helping! -#### Description -The `_track_output` method is used internally to record the results of tasks executed by the agents. It updates the metadata with the completed tasks and their results. +--- -#### Parameters +## **Feature Requests & Enhancement Suggestions** -- **`agent`** (`Agent`): The agent that executed the task. -- **`task`** (`str`): The task that was executed. -- **`result`** (`str`): The result of the task execution. +### **Swarms Improvement Proposals (SIPs)** -#### Example +The primary way to propose new features and significant enhancements to the Swarms framework is through the **Swarms Improvement Proposal (SIP)** process. SIPs are design documents that describe new features, enhancements, or changes to the framework. -```python -swarm._track_output(agent1, "Process Data", "Success") -``` +**When to Submit a SIP:** ---- +- New agent types or behaviors +- Core framework changes +- New integrations with external services +- Breaking changes +- Complex features requiring community discussion -### `_save_to_csv` +**SIP Process Overview:** -```python -def _save_to_csv(self): -``` +1. **Discuss First**: Share your idea in [GitHub Discussions](https://github.com/kyegomez/swarms/discussions) +2. **Create SIP**: Submit as GitHub Issue with `SIP` and `proposal` labels +3. **Community Review**: Engage with feedback and iterate on the proposal +4. **Implementation**: Once accepted, work on the implementation -#### Description +For detailed guidelines on creating and submitting SIPs, visit our [SIP Guidelines](protocol/sip.md). -The `_save_to_csv` method saves the swarm's metadata to a CSV file. It logs each task and its result before writing them to the file. The file is saved in the location specified by `save_file_path`. +### **Other Feature Requests** -#### Example +For smaller enhancements or straightforward additions that don't require a full SIP, you can: -```python -swarm._save_to_csv() -``` +**Use GitHub Issues:** +- Visit [GitHub Issues](https://github.com/kyegomez/swarms/issues) +- Select the "Feature Request" template +- Provide detailed description and use cases ---- +**Contact Direct Support:** +For enterprise-specific features or private discussions: +- **Email**: [kye@swarms.world](mailto:kye@swarms.world) +- **Subject Format**: `[FEATURE REQUEST] Brief description` -## Usage Examples +### **Feature Request Process** -### Example 1: Basic Swarm Initialization +1. **Email submission** with detailed requirements +2. **Initial review** within 48 hours +3. **Technical feasibility** assessment +4. **Community feedback** gathering (if applicable) +5. **Roadmap planning** and timeline estimation +6. **Development** and testing +7. **Release** with documentation -```python -import os +--- -from swarms import Agent -from swarm_models import OpenAIChat -from swarms.prompts.finance_agent_sys_prompt import ( - FINANCIAL_AGENT_SYS_PROMPT, -) -from swarms.structs.spreadsheet_swarm import SpreadSheetSwarm +## **Self-Service Resources** -# Example usage: -api_key = os.getenv("OPENAI_API_KEY") +Before reaching out for support, check these resources: -# Model -model = OpenAIChat( - openai_api_key=api_key, model_name="gpt-4o-mini", temperature=0.1 -) +### **Documentation** +- **[Complete Documentation](https://docs.swarms.world)** - Comprehensive guides and API reference -# Initialize your agents (assuming the Agent class and model are already defined) -agents = [ - Agent( - agent_name=f"Financial-Analysis-Agent-spreesheet-swarm:{i}", - system_prompt=FINANCIAL_AGENT_SYS_PROMPT, - llm=model, - max_loops=1, - dynamic_temperature_enabled=True, - saved_state_path="finance_agent.json", - user_name="swarms_corp", - retry_attempts=1, - ) - for i in range(10) -] +- **[Installation Guide](https://docs.swarms.world/en/latest/swarms/install/install/)** - Setup and configuration -# Create a Swarm with the list of agents -swarm = SpreadSheetSwarm( - name="Finance-Spreadsheet-Swarm", - description="A swarm that processes tasks from a queue using multiple agents on different threads.", - agents=agents, - autosave_on=True, - save_file_path="financial_spreed_sheet_swarm_demo.csv", - run_all_agents=False, - max_loops=1, -) +- **[Quick Start](https://docs.swarms.world/en/latest/quickstart/)** - Get up and running fast -# Run the swarm -swarm.run( - task="Analyze the states with the least taxes for LLCs. Provide an overview of all tax rates and add them with a comprehensive analysis" -) +- **[Examples Gallery](https://docs.swarms.world/en/latest/examples/)** - Real-world use cases -``` -### Example 2: QR Code Generator +### **Common Solutions** + +| Issue | Solution | +|-------|----------| +| **Installation fails** | Check [Environment Setup](https://docs.swarms.world/en/latest/swarms/install/env/) | +| **Model not responding** | Verify API keys in environment variables | +| **Import errors** | Ensure latest version: `pip install -U swarms` | +| **Memory issues** | Review [Performance Guide](https://docs.swarms.world/en/latest/swarms/framework/test/) | +| **Agent not working** | Check [Basic Agent Example](https://docs.swarms.world/en/latest/swarms/examples/basic_agent/) | -```python -import os -from swarms import Agent -from swarm_models import OpenAIChat -from swarms.structs.spreadsheet_swarm import SpreadSheetSwarm +### **Video Tutorials** -# Define custom system prompts for QR code generation -QR_CODE_AGENT_1_SYS_PROMPT = """ -You are a Python coding expert. Your task is to write a Python script to generate a QR code for the link: https://lu.ma/jjc1b2bo. The code should save the QR code as an image file. -""" +- **[YouTube Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ)** - Step-by-step tutorials -QR_CODE_AGENT_2_SYS_PROMPT = """ -You are a Python coding expert. Your task is to write a Python script to generate a QR code for the link: https://github.com/The-Swarm-Corporation/Cookbook. The code should save the QR code as an image file. -""" +- **[Live Coding Sessions](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ)** - Real-world implementations -# Example usage: -api_key = os.getenv("OPENAI_API_KEY") -# Model -model = OpenAIChat( - openai_api_key=api_key, model_name="gpt-4o-mini", temperature=0.1 -) +--- -# Initialize your agents for QR code generation -agents = [ - Agent( - agent_name="QR-Code-Generator-Agent-Luma", - system_prompt=QR_CODE_AGENT_1_SYS_PROMPT, - llm=model, - max_loops=1, - dynamic_temperature_enabled=True, - saved_state_path="qr_code_agent_luma.json", - user_name="swarms_corp", - retry_attempts=1, - ), - Agent( - agent_name="QR-Code-Generator-Agent-Cookbook", - system_prompt=QR_CODE_AGENT_2_SYS_PROMPT, - llm=model, - max_loops=1, - dynamic_temperature_enabled=True, - saved_state_path="qr_code_agent_cookbook.json", - user_name="swarms_corp", - retry_attempts=1, - ), -] +## **Support Checklist** -# Create a Swarm with the list of agents -swarm = SpreadSheetSwarm( - name="QR-Code-Generation-Swarm", - description="A swarm that generates Python scripts to create QR codes for specific links.", - agents=agents, - autosave_on=True, - save_file_path="qr_code_generation_results.csv", - run_all_agents=False, - max_loops=1, -) +Before requesting support, please: -# Run the swarm -swarm.run( - task="Generate Python scripts to create QR codes for the provided links and save them as image files." -) -``` +- [ ] **Check the documentation** for existing solutions +- [ ] **Search GitHub issues** for similar problems -## Example 3: Social Media Marketing +- [ ] **Update to latest version**: `pip install -U swarms` -```python +- [ ] **Verify environment setup** and API keys -import os -from swarms import Agent -from swarm_models import OpenAIChat -from swarms.structs.spreadsheet_swarm import SpreadSheetSwarm +- [ ] **Test with minimal code** to isolate the issue -# Define custom system prompts for each social media platform -TWITTER_AGENT_SYS_PROMPT = """ -You are a Twitter marketing expert. Your task is to create engaging, concise tweets and analyze trends to maximize engagement. Consider hashtags, timing, and content relevance. -""" +- [ ] **Gather error messages** and relevant logs -INSTAGRAM_AGENT_SYS_PROMPT = """ -You are an Instagram marketing expert. Your task is to create visually appealing and engaging content, including captions and hashtags, tailored to a specific audience. -""" +- [ ] **Note your environment** (OS, Python version, Swarms version) -FACEBOOK_AGENT_SYS_PROMPT = """ -You are a Facebook marketing expert. Your task is to craft posts that are optimized for engagement and reach on Facebook, including using images, links, and targeted messaging. -""" -EMAIL_AGENT_SYS_PROMPT = """ -You are an Email marketing expert. Your task is to write compelling email campaigns that drive conversions, focusing on subject lines, personalization, and call-to-action strategies. -""" +--- -# Example usage: -api_key = os.getenv("OPENAI_API_KEY") +## **Support Best Practices** -# Model -model = OpenAIChat( - openai_api_key=api_key, model_name="gpt-4o-mini", temperature=0.1 -) +### **For Faster Resolution** -# Initialize your agents for different social media platforms -agents = [ - Agent( - agent_name="Twitter-Marketing-Agent", - system_prompt=TWITTER_AGENT_SYS_PROMPT, - llm=model, - max_loops=1, - dynamic_temperature_enabled=True, - saved_state_path="twitter_agent.json", - user_name="swarms_corp", - retry_attempts=1, - ), - Agent( - agent_name="Instagram-Marketing-Agent", - system_prompt=INSTAGRAM_AGENT_SYS_PROMPT, - llm=model, - max_loops=1, - dynamic_temperature_enabled=True, - saved_state_path="instagram_agent.json", - user_name="swarms_corp", - retry_attempts=1, - ), - Agent( - agent_name="Facebook-Marketing-Agent", - system_prompt=FACEBOOK_AGENT_SYS_PROMPT, - llm=model, - max_loops=1, - dynamic_temperature_enabled=True, - saved_state_path="facebook_agent.json", - user_name="swarms_corp", - retry_attempts=1, - ), - Agent( - agent_name="Email-Marketing-Agent", - system_prompt=EMAIL_AGENT_SYS_PROMPT, - llm=model, - max_loops=1, - dynamic_temperature_enabled=True, - saved_state_path="email_agent.json", - user_name="swarms_corp", - retry_attempts=1, - ), -] +1. **Be Specific**: Provide exact error messages and steps to reproduce +2. **Include Code**: Share minimal, runnable examples +3. **Environment Details**: Always include version information +4. **Search First**: Check if your issue has been addressed before +5. **One Issue Per Report**: Don't combine multiple problems +6. **Follow Up**: Respond promptly to requests for additional information -# Create a Swarm with the list of agents -swarm = SpreadSheetSwarm( - name="Social-Media-Marketing-Swarm", - description="A swarm that processes social media marketing tasks using multiple agents on different threads.", - agents=agents, - autosave_on=True, - save_file_path="social_media_marketing_spreadsheet.csv", - run_all_agents=False, - max_loops=2, -) +### **Response Time Expectations** -# Run the swarm -swarm.run( - task="Create posts to promote hack nights in miami beach for developers, engineers, and tech enthusiasts. Include relevant hashtags, images, and engaging captions." -) -``` +| Priority | Response Time | Resolution Time | +|----------|---------------|-----------------| +| **Critical** (Production down) | < 2 hours | < 24 hours | +| **High** (Major functionality blocked) | < 8 hours | < 48 hours | +| **Medium** (Feature issues) | < 24 hours | < 1 week | +| **Low** (Documentation, enhancements) | < 48 hours | Next release | --- -## Additional Information and Tips +## **Contributing Back** -- **Thread Synchronization**: When working with multiple agents in a concurrent environment, it's crucial to ensure that access to shared resources is properly synchronized using locks to avoid race conditions. +Help improve support for everyone: -- **Autosave Feature**: If you enable the `autosave_on` flag, ensure that the file path provided is correct and writable. This feature is handy for long-running tasks where you want to periodically save the state. +- **Answer questions** in Discord or GitHub -- **Error Handling** +- **Improve documentation** with your learnings -: Implementing proper error handling within your agents can prevent the swarm from crashing during execution. Consider catching exceptions in the `run` method and logging errors appropriately. +- **Share examples** of successful implementations -- **Custom Agents**: You can extend the `Agent` class to create custom agents that perform specific tasks tailored to your application's needs. +- **Report bugs** you discover + +- **Suggest improvements** to this support process + + +**Your contributions make Swarms better for everyone.** --- -## References and Resources +## **Support Channel Summary** -- [Python's `queue` module](https://docs.python.org/3/library/queue.html) -- [Python's `threading` module](https://docs.python.org/3/library/threading.html) -- [CSV File Handling in Python](https://docs.python.org/3/library/csv.html) -- [JSON Handling in Python](https://docs.python.org/3/library/json.html) +| Urgency | Best Channel | +|---------|-------------| +| **Emergency** | [Book Immediate Call](https://cal.com/swarms/swarms-technical-support?overlayCalendar=true) | +| **Urgent** | [Discord #technical-support](https://discord.gg/jM3Z6M9uMq) | +| **Standard** | [GitHub Issues](https://github.com/kyegomez/swarms/issues) | +| **Major Features** | [SIP Guidelines](protocol/sip.md) | +| **Minor Features** | [GitHub Issues](https://github.com/kyegomez/swarms/issues) | +**We're here to help you succeed with Swarms.** -------------------------------------------------- -# File: swarms/structs/swarm_network.md +# File: swarms\tools\base_tool.md -# SwarmNetwork [WIP] +# BaseTool Class Documentation -The `SwarmNetwork` class is a powerful tool for managing a pool of agents, orchestrating task distribution, and scaling resources based on workload. It is designed to handle tasks efficiently by dynamically adjusting the number of agents according to the current demand. This class also provides an optional API for interacting with the agent pool, making it accessible for integration with other systems. +## Overview -### Key Features -- **Agent Pool Management**: Dynamically manage a pool of agents. -- **Task Queue Management**: Handle tasks through a queue system. -- **Agent Health Monitoring**: Monitor the health of agents. -- **Agent Pool Scaling**: Scale the agent pool up or down based on workload. -- **API**: Interact with the agent pool and task queue through a simple API. -- **Agent Deployment Options**: Run agents on threads, processes, containers, machines, or clusters. +The `BaseTool` class is a comprehensive tool management system for function calling, schema conversion, and execution. It provides a unified interface for converting Python functions to OpenAI function calling schemas, managing Pydantic models, executing tools with proper error handling, and supporting multiple AI provider formats (OpenAI, Anthropic, etc.). -### Parameters +**Key Features:** -| Parameter | Type | Default Value | Description | -|-----------------|--------------------|---------------|-----------------------------------------------------------------------------| -| name | str | None | The name of the swarm network. | -| description | str | None | A description of the swarm network. | -| agents | List[Agent] | None | A list of agents in the pool. | -| idle_threshold | float | 0.2 | The idle threshold for the agents. | -| busy_threshold | float | 0.7 | The busy threshold for the agents. | -| api_enabled | Optional[bool] | False | A flag to enable/disable the API. | -| logging_enabled | Optional[bool] | False | A flag to enable/disable logging. | -| api_on | Optional[bool] | False | A flag to enable/disable the FastAPI instance. | -| host | str | "0.0.0.0" | The host address for the FastAPI instance. | -| port | int | 8000 | The port number for the FastAPI instance. | -| swarm_callable | Optional[callable] | None | A callable to be executed by the swarm network. | -| *args | tuple | | Additional positional arguments. | -| **kwargs | dict | | Additional keyword arguments. | +- Convert Python functions to OpenAI function calling schemas -### Attributes +- Manage Pydantic models and their schemas -| Attribute | Type | Description | -|------------------|--------------------|----------------------------------------------------------------| -| task_queue | queue.Queue | A queue for storing tasks. | -| idle_threshold | float | The idle threshold for the agents. | -| busy_threshold | float | The busy threshold for the agents. | -| agents | List[Agent] | A list of agents in the pool. | -| api_enabled | bool | A flag to enable/disable the API. | -| logging_enabled | bool | A flag to enable/disable logging. | -| host | str | The host address for the FastAPI instance. | -| port | int | The port number for the FastAPI instance. | -| swarm_callable | Optional[callable] | A callable to be executed by the swarm network. | -| agent_dict | dict | A dictionary of agents for easy access. | -| lock | threading.Lock | A lock for synchronizing access to shared resources. | +- Execute tools with proper error handling and validation -## Methods +- Support for parallel and sequential function execution -#### Description -Initializes a new instance of the `SwarmNetwork` class. +- Schema validation for multiple AI providers -#### Parameters -- `name` (str): The name of the swarm network. -- `description` (str): A description of the swarm network. -- `agents` (List[Agent]): A list of agents in the pool. -- `idle_threshold` (float): The idle threshold for the agents. -- `busy_threshold` (float): The busy threshold for the agents. -- `api_enabled` (Optional[bool]): A flag to enable/disable the API. -- `logging_enabled` (Optional[bool]): A flag to enable/disable logging. -- `api_on` (Optional[bool]): A flag to enable/disable the FastAPI instance. -- `host` (str): The host address for the FastAPI instance. -- `port` (int): The port number for the FastAPI instance. -- `swarm_callable` (Optional[callable]): A callable to be executed by the swarm network. -- `*args`: Additional positional arguments. -- `**kwargs`: Additional keyword arguments. +- Automatic tool execution from API responses -### `add_task` +- Caching for improved performance -```python -def add_task(self, task) -``` +## Initialization Parameters -#### Description -Adds a task to the task queue. +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `verbose` | `Optional[bool]` | `None` | Enable detailed logging output | +| `base_models` | `Optional[List[type[BaseModel]]]` | `None` | List of Pydantic models to manage | +| `autocheck` | `Optional[bool]` | `None` | Enable automatic validation checks | +| `auto_execute_tool` | `Optional[bool]` | `None` | Enable automatic tool execution | +| `tools` | `Optional[List[Callable[..., Any]]]` | `None` | List of callable functions to manage | +| `tool_system_prompt` | `Optional[str]` | `None` | System prompt for tool operations | +| `function_map` | `Optional[Dict[str, Callable]]` | `None` | Mapping of function names to callables | +| `list_of_dicts` | `Optional[List[Dict[str, Any]]]` | `None` | List of dictionary representations | -#### Parameters -- `task` (_type_): The task to be added to the queue. +## Methods Overview -#### Example +| Method | Description | +|--------|-------------| +| `func_to_dict` | Convert a callable function to OpenAI function calling schema | +| `load_params_from_func_for_pybasemodel` | Load function parameters for Pydantic BaseModel integration | +| `base_model_to_dict` | Convert Pydantic BaseModel to OpenAI schema dictionary | +| `multi_base_models_to_dict` | Convert multiple Pydantic BaseModels to OpenAI schema | +| `dict_to_openai_schema_str` | Convert dictionary to OpenAI schema string | +| `multi_dict_to_openai_schema_str` | Convert multiple dictionaries to OpenAI schema string | +| `get_docs_from_callable` | Extract documentation from callable items | +| `execute_tool` | Execute a tool based on response string | +| `detect_tool_input_type` | Detect the type of tool input | +| `dynamic_run` | Execute dynamic run with automatic type detection | +| `execute_tool_by_name` | Search for and execute tool by name | +| `execute_tool_from_text` | Execute tool from JSON-formatted string | +| `check_str_for_functions_valid` | Check if output is valid JSON with matching function | +| `convert_funcs_into_tools` | Convert all functions in tools list to OpenAI format | +| `convert_tool_into_openai_schema` | Convert tools into OpenAI function calling schema | +| `check_func_if_have_docs` | Check if function has proper documentation | +| `check_func_if_have_type_hints` | Check if function has proper type hints | +| `find_function_name` | Find function by name in tools list | +| `function_to_dict` | Convert function to dictionary representation | +| `multiple_functions_to_dict` | Convert multiple functions to dictionary representations | +| `execute_function_with_dict` | Execute function using dictionary of parameters | +| `execute_multiple_functions_with_dict` | Execute multiple functions with parameter dictionaries | +| `validate_function_schema` | Validate function schema for different AI providers | +| `get_schema_provider_format` | Get detected provider format of schema | +| `convert_schema_between_providers` | Convert schema between provider formats | +| `execute_function_calls_from_api_response` | Execute function calls from API responses | +| `detect_api_response_format` | Detect the format of API response | + +--- + +## Detailed Method Documentation + +### `func_to_dict` + +**Description:** Convert a callable function to OpenAI function calling schema dictionary. + +**Arguments:** +- `function` (Callable[..., Any], optional): The function to convert + +**Returns:** `Dict[str, Any]` - OpenAI function calling schema dictionary +**Example:** ```python -from swarms.structs.agent import Agent -from swarms.structs.swarm_net import SwarmNetwork +from swarms.tools.base_tool import BaseTool -agent = Agent() -swarm = SwarmNetwork(agents=[agent]) -swarm.add_task("task") -``` +def add_numbers(a: int, b: int) -> int: + """Add two numbers together.""" + return a + b -### `async_add_task` +# Create BaseTool instance +tool = BaseTool(verbose=True) -```python -async def async_add_task(self, task) +# Convert function to OpenAI schema +schema = tool.func_to_dict(add_numbers) +print(schema) +# Output: {'type': 'function', 'function': {'name': 'add_numbers', 'description': 'Add two numbers together.', 'parameters': {...}}} ``` -#### Description -Adds a task to the task queue asynchronously. +### `load_params_from_func_for_pybasemodel` -#### Parameters -- `task` (_type_): The task to be added to the queue. +**Description:** Load and process function parameters for Pydantic BaseModel integration. -#### Example +**Arguments:** -```python -from swarms.structs.agent import Agent -from swarms.structs.swarm_net import SwarmNetwork +- `func` (Callable[..., Any]): The function to process -agent = Agent() -swarm = SwarmNetwork(agents=[agent]) -await swarm.async_add_task("task") -``` +- `*args`: Additional positional arguments -### `run_single_agent` +- `**kwargs`: Additional keyword arguments +**Returns:** `Callable[..., Any]` - Processed function with loaded parameters + +**Example:** ```python -def run_single_agent(self, agent_id, task: Optional[str], *args, **kwargs) +from swarms.tools.base_tool import BaseTool + +def calculate_area(length: float, width: float) -> float: + """Calculate area of a rectangle.""" + return length * width + +tool = BaseTool() +processed_func = tool.load_params_from_func_for_pybasemodel(calculate_area) ``` -#### Description -Runs a task on a specific agent by ID. +### `base_model_to_dict` -#### Parameters -- `agent_id` (_type_): The ID of the agent. -- `task` (str, optional): The task to be executed by the agent. -- `*args`: Additional positional arguments. -- `**kwargs`: Additional keyword arguments. +**Description:** Convert a Pydantic BaseModel to OpenAI function calling schema dictionary. -#### Returns -- `_type_`: The output of the agent running the task. +**Arguments:** -#### Example +- `pydantic_type` (type[BaseModel]): The Pydantic model class to convert + +- `*args`: Additional positional arguments + +- `**kwargs`: Additional keyword arguments +**Returns:** `dict[str, Any]` - OpenAI function calling schema dictionary + +**Example:** ```python -from swarms.structs.agent import Agent -from swarms.structs.swarm_net import SwarmNetwork +from pydantic import BaseModel +from swarms.tools.base_tool import BaseTool -# Initialize the agent -agent = Agent( - agent_name="Financial-Analysis-Agent", - llm=model, - max_loops="auto", - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - interactive=True, - # interactive=True, # Set to False to disable interactive mode - saved_state_path="finance_agent.json", - # tools=[Add your functions here# ], - # stopping_token="Stop!", - # interactive=True, - # docs_folder="docs", # Enter your folder name - # pdf_path="docs/finance_agent.pdf", - # sop="Calculate the profit for a company.", - # sop_list=["Calculate the profit for a company."], - user_name="swarms_corp", - # # docs= - # # docs_folder="docs", - retry_attempts=3, - # context_length=1000, - # tool_schema = dict - context_length=200000, - # agent_ops_on=True, - # long_term_memory=ChromaDB(docs_folder="artifacts"), -) +class UserInfo(BaseModel): + name: str + age: int + email: str -swarm = SwarmNetwork(agents=[agent]) -result = swarm.run_single_agent(agent.id, "task") +tool = BaseTool() +schema = tool.base_model_to_dict(UserInfo) +print(schema) ``` -### `run_many_agents` +### `multi_base_models_to_dict` + +**Description:** Convert multiple Pydantic BaseModels to OpenAI function calling schema. +**Arguments:** +- `base_models` (List[BaseModel]): List of Pydantic models to convert + +**Returns:** `dict[str, Any]` - Combined OpenAI function calling schema + +**Example:** ```python -def run_many_agents(self, task: Optional[str] = None, *args, **kwargs) -> List +from pydantic import BaseModel +from swarms.tools.base_tool import BaseTool + +class User(BaseModel): + name: str + age: int + +class Product(BaseModel): + name: str + price: float + +tool = BaseTool() +schemas = tool.multi_base_models_to_dict([User, Product]) +print(schemas) ``` -#### Description -Runs a task on all agents in the pool. +### `dict_to_openai_schema_str` -#### Parameters -- `task` (str, optional): The task to be executed by the agents. -- `*args`: Additional positional arguments. -- `**kwargs`: Additional keyword arguments. +**Description:** Convert a dictionary to OpenAI function calling schema string. -#### Returns -- `List`: The output of all agents running the task. +**Arguments:** -#### Example +- `dict` (dict[str, Any]): Dictionary to convert +**Returns:** `str` - OpenAI schema string representation + +**Example:** ```python -from swarms.structs.agent import Agent -from swarms.structs.swarm_net import SwarmNetwork +from swarms.tools.base_tool import BaseTool -# Initialize the agent -agent = Agent( - agent_name="Financial-Analysis-Agent", - system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, - llm=model, - max_loops="auto", - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - interactive=True, - # interactive=True, # Set to False to disable interactive mode - saved_state_path="finance_agent.json", - # tools=[Add your functions here# ], - # stopping_token="Stop!", - # interactive=True, - # docs_folder="docs", # Enter your folder name - # pdf_path="docs/finance_agent.pdf", - # sop="Calculate the profit for a company.", - # sop_list=["Calculate the profit for a company."], - user_name="swarms_corp", - # # docs= - # # docs_folder="docs", - retry_attempts=3, - # context_length=1000, - # tool_schema = dict - context_length=200000, - # agent_ops_on=True, - # long_term_memory=ChromaDB(docs_folder="artifacts"), -) +my_dict = { + "type": "function", + "function": { + "name": "get_weather", + "description": "Get weather information", + "parameters": {"type": "object", "properties": {"city": {"type": "string"}}} + } +} -# Initialize the agent -agent2 = Agent( - agent_name="ROTH-IRA-AGENT", - system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, - llm=model, - max_loops="auto", - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - interactive=True, - # interactive=True, # Set to False to disable interactive mode - saved_state_path="finance_agent.json", - # tools=[Add your functions here# ], - # stopping_token="Stop!", - # interactive=True, - # docs_folder="docs", # Enter your folder name - # pdf_path="docs/finance_agent.pdf", - # sop="Calculate the profit for a company.", - # sop_list=["Calculate the profit for a company."], - user_name="swarms_corp", - # # docs= - # # docs_folder="docs", - retry_attempts=3, - # context_length=1000, - # tool_schema = dict - context_length=200000, - # agent_ops_on=True, - # long_term_memory=ChromaDB(docs_folder="artifacts"), -) +tool = BaseTool() +schema_str = tool.dict_to_openai_schema_str(my_dict) +print(schema_str) +``` +### `multi_dict_to_openai_schema_str` -swarm = SwarmNetwork(agents=[agent1, agent2]) -results = swarm.run_many_agents("task") -``` +**Description:** Convert multiple dictionaries to OpenAI function calling schema string. -### `list_agents` +**Arguments:** +- `dicts` (list[dict[str, Any]]): List of dictionaries to convert + +**Returns:** `str` - Combined OpenAI schema string representation + +**Example:** ```python -def list_agents(self) +from swarms.tools.base_tool import BaseTool + +dict1 = {"type": "function", "function": {"name": "func1", "description": "Function 1"}} +dict2 = {"type": "function", "function": {"name": "func2", "description": "Function 2"}} + +tool = BaseTool() +schema_str = tool.multi_dict_to_openai_schema_str([dict1, dict2]) +print(schema_str) ``` -#### Description -Lists all agents in the pool. +### `get_docs_from_callable` -#### Example +**Description:** Extract documentation from a callable item. + +**Arguments:** + +- `item`: The callable item to extract documentation from +**Returns:** Processed documentation + +**Example:** ```python -from swarms.structs.agent import Agent -from swarms.structs.swarm_net import SwarmNetwork +from swarms.tools.base_tool import BaseTool -# Initialize the agent -agent2 = Agent( - agent_name="ROTH-IRA-AGENT", - system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, - llm=model, - max_loops="auto", - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - interactive=True, - # interactive=True, # Set to False to disable interactive mode - saved_state_path="finance_agent.json", - # tools=[Add your functions here# ], - # stopping_token="Stop!", - # interactive=True, - # docs_folder="docs", # Enter your folder name - # pdf_path="docs/finance_agent.pdf", - # sop="Calculate the profit for a company.", - # sop_list=["Calculate the profit for a company."], - user_name="swarms_corp", - # # docs= - # # docs_folder="docs", - retry_attempts=3, - # context_length=1000, - # tool_schema = dict - context_length=200000, - # agent_ops_on=True, - # long_term_memory=ChromaDB(docs_folder="artifacts"), -) +def example_function(): + """This is an example function with documentation.""" + pass -swarm = SwarmNetwork(agents=[agent]) -swarm.list_agents() +tool = BaseTool() +docs = tool.get_docs_from_callable(example_function) +print(docs) ``` -### `get_agent` +### `execute_tool` + +**Description:** Execute a tool based on a response string. + +**Arguments:** +- `response` (str): JSON response string containing tool execution details + +- `*args`: Additional positional arguments + +- `**kwargs`: Additional keyword arguments + +**Returns:** `Callable` - Result of the tool execution +**Example:** ```python -def get_agent(self, agent_id) +from swarms.tools.base_tool import BaseTool + +def greet(name: str) -> str: + """Greet a person by name.""" + return f"Hello, {name}!" + +tool = BaseTool(tools=[greet]) +response = '{"name": "greet", "parameters": {"name": "Alice"}}' +result = tool.execute_tool(response) +print(result) # Output: "Hello, Alice!" ``` -#### Description -Gets an agent by ID. +### `detect_tool_input_type` -#### Parameters -- `agent_id` (_type_): The ID of the agent to retrieve. +**Description:** Detect the type of tool input for appropriate processing. -#### Returns -- `_type_`: The agent with the specified ID. +**Arguments:** -#### Example +- `input` (ToolType): The input to analyze -```python -from swarms.structs.agent import Agent -from swarms.structs.swarm_net import SwarmNetwork +**Returns:** `str` - Type of the input ("Pydantic", "Dictionary", "Function", or "Unknown") -# Initialize the agent -agent2 = Agent( - agent_name="ROTH-IRA-AGENT", - system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, - llm=model, - max_loops="auto", - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - interactive=True, - # interactive=True, # Set to False to disable interactive mode - saved_state_path="finance_agent.json", - # tools=[Add your functions here# ], - # stopping_token="Stop!", - # interactive=True, - # docs_folder="docs", # Enter your folder name - # pdf_path="docs/finance_agent.pdf", - # sop="Calculate the profit for a company.", - # sop_list=["Calculate the profit for a company."], - user_name="swarms_corp", - # # docs= - # # docs_folder="docs", - retry_attempts=3, - # context_length=1000, - # tool_schema = dict - context_length=200000, - # agent_ops_on=True, - # long_term_memory=ChromaDB(docs_folder="artifacts"), -) +**Example:** +```python +from swarms.tools.base_tool import BaseTool +from pydantic import BaseModel -swarm = SwarmNetwork(agents=[agent]) -retrieved_agent = swarm.get_agent(agent.id) -``` +class MyModel(BaseModel): + value: int -### `add_agent` +def my_function(): + pass -```python -def add_agent(self, agent: Agent) +tool = BaseTool() +print(tool.detect_tool_input_type(MyModel)) # "Pydantic" +print(tool.detect_tool_input_type(my_function)) # "Function" +print(tool.detect_tool_input_type({"key": "value"})) # "Dictionary" ``` -#### Description -Adds an agent to the agent pool. +### `dynamic_run` -#### Parameters -- `agent` (_type_): The agent to be added to the pool. +**Description:** Execute a dynamic run based on the input type with automatic type detection. -#### Example +**Arguments:** +- `input` (Any): The input to be processed (Pydantic model, dict, or function) + +**Returns:** `str` - The result of the dynamic run (schema string or execution result) +**Example:** ```python -from swarms.structs.agent import Agent -from swarms.structs.swarm_net import SwarmNetwork +from swarms.tools.base_tool import BaseTool -# Initialize the agent -agent2 = Agent( - agent_name="ROTH-IRA-AGENT", - system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, - llm=model, - max_loops="auto", - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - interactive=True, - # interactive=True, # Set to False to disable interactive mode - saved_state_path="finance_agent.json", - # tools=[Add your functions here# ], - # stopping_token="Stop!", - # interactive=True, - # docs_folder="docs", # Enter your folder name - # pdf_path="docs/finance_agent.pdf", - # sop="Calculate the profit for a company.", - # sop_list=["Calculate the profit for a company."], - user_name="swarms_corp", - # # docs= - # # docs_folder="docs", - retry_attempts=3, - # context_length=1000, - # tool_schema = dict - context_length=200000, - # agent_ops_on=True, - # long_term_memory=ChromaDB(docs_folder="artifacts"), -) +def multiply(x: int, y: int) -> int: + """Multiply two numbers.""" + return x * y -swarm = SwarmNetwork(agents=[]) -swarm.add_agent(agent) +tool = BaseTool(auto_execute_tool=False) +result = tool.dynamic_run(multiply) +print(result) # Returns OpenAI schema string ``` -### `remove_agent` +### `execute_tool_by_name` -```python -def remove_agent(self, agent_id) -``` +**Description:** Search for a tool by name and execute it with the provided response. -#### Description -Removes an agent from the agent pool. +**Arguments:** +- `tool_name` (str): The name of the tool to execute -#### Parameters -- `agent_id` (_type_): The ID of the agent to be removed. +- `response` (str): JSON response string containing execution parameters -#### Example +**Returns:** `Any` - The result of executing the tool +**Example:** ```python -from swarms.structs.agent import Agent -from swarms.structs.swarm_net import SwarmNetwork +from swarms.tools.base_tool import BaseTool -# Initialize the agent -agent2 = Agent( - agent_name="ROTH-IRA-AGENT", - system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, - llm=model, - max_loops="auto", - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - interactive=True, - # interactive=True, # Set to False to disable interactive mode - saved_state_path="finance_agent.json", - # tools=[Add your functions here# ], - # stopping_token="Stop!", - # interactive=True, - # docs_folder="docs", # Enter your folder name - # pdf_path="docs/finance_agent.pdf", - # sop="Calculate the profit for a company.", - # sop_list=["Calculate the profit for a company."], - user_name="swarms_corp", - # # docs= - # # docs_folder="docs", - retry_attempts=3, - # context_length=1000, - # tool_schema = dict - context_length=200000, - # agent_ops_on=True, - # long_term_memory=ChromaDB(docs_folder="artifacts"), -) +def calculate_sum(a: int, b: int) -> int: + """Calculate sum of two numbers.""" + return a + b -swarm = SwarmNetwork(agents=[agent]) -swarm.remove_agent(agent.id) +tool = BaseTool(function_map={"calculate_sum": calculate_sum}) +result = tool.execute_tool_by_name("calculate_sum", '{"a": 5, "b": 3}') +print(result) # Output: 8 ``` -### ` +### `execute_tool_from_text` -async_remove_agent` +**Description:** Convert a JSON-formatted string into a tool dictionary and execute the tool. +**Arguments:** +- `text` (str): A JSON-formatted string representing a tool call with 'name' and 'parameters' keys + +**Returns:** `Any` - The result of executing the tool + +**Example:** ```python -async def async_remove_agent(self, agent_id) +from swarms.tools.base_tool import BaseTool + +def divide(x: float, y: float) -> float: + """Divide x by y.""" + return x / y + +tool = BaseTool(function_map={"divide": divide}) +text = '{"name": "divide", "parameters": {"x": 10, "y": 2}}' +result = tool.execute_tool_from_text(text) +print(result) # Output: 5.0 ``` -#### Description -Removes an agent from the agent pool asynchronously. +### `check_str_for_functions_valid` -#### Parameters -- `agent_id` (_type_): The ID of the agent to be removed. +**Description:** Check if the output is a valid JSON string with a function name that matches the function map. -#### Example +**Arguments:** +- `output` (str): The output string to validate + +**Returns:** `bool` - True if the output is valid and the function name matches, False otherwise +**Example:** ```python -from swarms.structs.agent import Agent -from swarms.structs.swarm_net import SwarmNetwork +from swarms.tools.base_tool import BaseTool -# Initialize the agent -agent2 = Agent( - agent_name="ROTH-IRA-AGENT", - system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, - llm=model, - max_loops="auto", - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - interactive=True, - # interactive=True, # Set to False to disable interactive mode - saved_state_path="finance_agent.json", - # tools=[Add your functions here# ], - # stopping_token="Stop!", - # interactive=True, - # docs_folder="docs", # Enter your folder name - # pdf_path="docs/finance_agent.pdf", - # sop="Calculate the profit for a company.", - # sop_list=["Calculate the profit for a company."], - user_name="swarms_corp", - # # docs= - # # docs_folder="docs", - retry_attempts=3, - # context_length=1000, - # tool_schema = dict - context_length=200000, - # agent_ops_on=True, - # long_term_memory=ChromaDB(docs_folder="artifacts"), -) +def test_func(): + pass -swarm = SwarmNetwork(agents=[agent]) -await swarm.async_remove_agent(agent.id) +tool = BaseTool(function_map={"test_func": test_func}) +valid_output = '{"type": "function", "function": {"name": "test_func"}}' +is_valid = tool.check_str_for_functions_valid(valid_output) +print(is_valid) # Output: True ``` -### `scale_up` +### `convert_funcs_into_tools` + +**Description:** Convert all functions in the tools list into OpenAI function calling format. +**Arguments:** None + +**Returns:** None (modifies internal state) + +**Example:** ```python -def scale_up(self, num_agents: int = 1) +from swarms.tools.base_tool import BaseTool + +def func1(x: int) -> int: + """Function 1.""" + return x * 2 + +def func2(y: str) -> str: + """Function 2.""" + return y.upper() + +tool = BaseTool(tools=[func1, func2]) +tool.convert_funcs_into_tools() +print(tool.function_map) # {'func1': , 'func2': } ``` -#### Description -Scales up the agent pool by adding new agents. +### `convert_tool_into_openai_schema` -#### Parameters -- `num_agents` (int, optional): The number of agents to add. Defaults to 1. +**Description:** Convert tools into OpenAI function calling schema format. -#### Example +**Arguments:** None +**Returns:** `dict[str, Any]` - Combined OpenAI function calling schema + +**Example:** ```python -from swarms.structs.agent import Agent -from swarms.structs.swarm_net import SwarmNetwork +from swarms.tools.base_tool import BaseTool -# Initialize the agent -agent2 = Agent( - agent_name="ROTH-IRA-AGENT", - system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, - llm=model, - max_loops="auto", - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - interactive=True, - # interactive=True, # Set to False to disable interactive mode - saved_state_path="finance_agent.json", - # tools=[Add your functions here# ], - # stopping_token="Stop!", - # interactive=True, - # docs_folder="docs", # Enter your folder name - # pdf_path="docs/finance_agent.pdf", - # sop="Calculate the profit for a company.", - # sop_list=["Calculate the profit for a company."], - user_name="swarms_corp", - # # docs= - # # docs_folder="docs", - retry_attempts=3, - # context_length=1000, - # tool_schema = dict - context_length=200000, - # agent_ops_on=True, - # long_term_memory=ChromaDB(docs_folder="artifacts"), -) +def add(a: int, b: int) -> int: + """Add two numbers.""" + return a + b -swarm = SwarmNetwork(agents=[agent]) -swarm.scale_up(2) +def subtract(a: int, b: int) -> int: + """Subtract b from a.""" + return a - b + +tool = BaseTool(tools=[add, subtract]) +schema = tool.convert_tool_into_openai_schema() +print(schema) ``` -### `scale_down` +### `check_func_if_have_docs` -```python -def scale_down(self, num_agents: int = 1) -``` +**Description:** Check if a function has proper documentation. -#### Description -Scales down the agent pool by removing agents. +**Arguments:** -#### Parameters -- `num_agents` (int, optional): The number of agents to remove. Defaults to 1. +- `func` (callable): The function to check -#### Example +**Returns:** `bool` - True if function has documentation +**Example:** ```python -from swarms.structs.agent import Agent -from swarms.structs.swarm_net import SwarmNetwork +from swarms.tools.base_tool import BaseTool -# Initialize the agent -agent2 = Agent( - agent_name="ROTH-IRA-AGENT", - system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT, - llm=model, - max_loops="auto", - autosave=True, - dashboard=False, - verbose=True, - streaming_on=True, - interactive=True, - # interactive=True, # Set to False to disable interactive mode - saved_state_path="finance_agent.json", - # tools=[Add your functions here# ], - # stopping_token="Stop!", - # interactive=True, - # docs_folder="docs", # Enter your folder name - # pdf_path="docs/finance_agent.pdf", - # sop="Calculate the profit for a company.", - # sop_list=["Calculate the profit for a company."], - user_name="swarms_corp", - # # docs= - # # docs_folder="docs", - retry_attempts=3, - # context_length=1000, - # tool_schema = dict - context_length=200000, - # agent_ops_on=True, - # long_term_memory=ChromaDB(docs_folder="artifacts"), -) +def documented_func(): + """This function has documentation.""" + pass +def undocumented_func(): + pass -swarm = SwarmNetwork(agents=[agent]) -swarm.scale_down(1) +tool = BaseTool() +print(tool.check_func_if_have_docs(documented_func)) # True +# tool.check_func_if_have_docs(undocumented_func) # Raises ToolDocumentationError ``` -### `run` - -#### Description -Runs the swarm network, starting the FastAPI application. +### `check_func_if_have_type_hints` -#### Example +**Description:** Check if a function has proper type hints. -```python +**Arguments:** -import os +- `func` (callable): The function to check -from dotenv import load_dotenv +**Returns:** `bool` - True if function has type hints -# Import the OpenAIChat model and the Agent struct -from swarms import Agent, OpenAIChat, SwarmNetwork +**Example:** +```python +from swarms.tools.base_tool import BaseTool -# Load the environment variables -load_dotenv() +def typed_func(x: int) -> str: + """A typed function.""" + return str(x) -# Get the API key from the environment -api_key = os.environ.get("OPENAI_API_KEY") +def untyped_func(x): + """An untyped function.""" + return str(x) -# Initialize the language model -llm = OpenAIChat( - temperature=0.5, - openai_api_key=api_key, -) +tool = BaseTool() +print(tool.check_func_if_have_type_hints(typed_func)) # True +# tool.check_func_if_have_type_hints(untyped_func) # Raises ToolTypeHintError +``` -## Initialize the workflow -agent = Agent(llm=llm, max_loops=1, agent_name="Social Media Manager") -agent2 = Agent(llm=llm, max_loops=1, agent_name=" Product Manager") -agent3 = Agent(llm=llm, max_loops=1, agent_name="SEO Manager") +### `find_function_name` +**Description:** Find a function by name in the tools list. -# Load the swarmnet with the agents -swarmnet = SwarmNetwork( - agents=[agent, agent2, agent3], -) +**Arguments:** +- `func_name` (str): The name of the function to find -# List the agents in the swarm network -out = swarmnet.list_agents() -print(out) +**Returns:** `Optional[callable]` - The function if found, None otherwise -# Run the workflow on a task -out = swarmnet.run_single_agent( - agent2.id, "Generate a 10,000 word blog on health and wellness." -) -print(out) +**Example:** +```python +from swarms.tools.base_tool import BaseTool +def my_function(): + """My function.""" + pass -# Run all the agents in the swarm network on a task -out = swarmnet.run_many_agents("Generate a 10,000 word blog on health and wellness.") -print(out) +tool = BaseTool(tools=[my_function]) +found_func = tool.find_function_name("my_function") +print(found_func) # ``` -## Additional Information and Tips +### `function_to_dict` -- **Error Handling**: Make use of try-except blocks to handle potential errors when adding tasks, running tasks, and managing agents. -- **Logging**: Enable logging to track the activity and status of the swarm network. -- **API**: The provided API allows for easy interaction with the swarm network and can be extended as needed. -- **Asynchronous Operations**: Utilize the asynchronous methods for non-blocking operations, especially in a production environment. -- **Scaling**: Adjust the scaling thresholds (`idle_threshold` and `busy_threshold`) based on the specific needs and workload patterns. +**Description:** Convert a function to dictionary representation. -## References and Resources +**Arguments:** +- `func` (callable): The function to convert -- [Python Queue Documentation](https://docs.python.org/3/library/queue.html) -- [Threading in Python](https://docs.python.org/3/library/threading.html) -- [FastAPI Documentation](https://fastapi.tiangolo.com/) -- [Tenacity Documentation](https://tenacity.readthedocs.io/en/latest/) +**Returns:** `dict` - Dictionary representation of the function -By following this documentation, users can effectively manage and utilize the `SwarmNetwork` class to handle dynamic workloads and maintain an efficient pool of agents. +**Example:** +```python +from swarms.tools.base_tool import BaseTool +def example_func(param: str) -> str: + """Example function.""" + return param --------------------------------------------------- +tool = BaseTool() +func_dict = tool.function_to_dict(example_func) +print(func_dict) +``` -# File: swarms/structs/swarm_rearrange.md +### `multiple_functions_to_dict` -# SwarmRearrange Documentation +**Description:** Convert multiple functions to dictionary representations. -SwarmRearrange is a class for orchestrating multiple swarms in a sequential or parallel flow pattern. It provides thread-safe operations for managing swarm execution, history tracking, and flow validation. +**Arguments:** -## Constructor Arguments +- `funcs` (list[callable]): List of functions to convert -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| id | str | UUID | Unique identifier for the swarm arrangement | -| name | str | "SwarmRearrange" | Name of the swarm arrangement | -| description | str | "A swarm of swarms..." | Description of the arrangement | -| swarms | List[Any] | [] | List of swarm objects to be managed | -| flow | str | None | Flow pattern for swarm execution | -| max_loops | int | 1 | Maximum number of execution loops | -| verbose | bool | True | Enable detailed logging | -| human_in_the_loop | bool | False | Enable human intervention | -| custom_human_in_the_loop | Callable | None | Custom function for human interaction | -| return_json | bool | False | Return results in JSON format | +**Returns:** `list[dict]` - List of dictionary representations -## Methods +**Example:** +```python +from swarms.tools.base_tool import BaseTool -### add_swarm(swarm: Any) -Adds a single swarm to the arrangement. +def func1(x: int) -> int: + """Function 1.""" + return x -### remove_swarm(swarm_name: str) -Removes a swarm by name from the arrangement. +def func2(y: str) -> str: + """Function 2.""" + return y -### add_swarms(swarms: List[Any]) -Adds multiple swarms to the arrangement. +tool = BaseTool() +func_dicts = tool.multiple_functions_to_dict([func1, func2]) +print(func_dicts) +``` -### validate_flow() -Validates the flow pattern syntax and swarm names. +### `execute_function_with_dict` -### run(task: str = None, img: str = None, custom_tasks: Dict[str, str] = None) -Executes the swarm arrangement according to the flow pattern. +**Description:** Execute a function using a dictionary of parameters. -## Flow Pattern Syntax -The flow pattern uses arrow notation (`->`) to define execution order: +**Arguments:** -- Sequential: `"SwarmA -> SwarmB -> SwarmC"` -- Parallel: `"SwarmA, SwarmB -> SwarmC"` -- Human intervention: Use `"H"` in the flow +- `func_dict` (dict): Dictionary containing function parameters -## Examples +- `func_name` (Optional[str]): Name of function to execute (if not in dict) -### Basic Sequential Flow +**Returns:** `Any` - Result of function execution +**Example:** ```python -from swarms.structs.swarm_arange import SwarmRearrange -import os -from swarms import Agent, AgentRearrange -from swarm_models import OpenAIChat - -# model = Anthropic(anthropic_api_key=os.getenv("ANTHROPIC_API_KEY")) -company = "TGSC" - -# Get the OpenAI API key from the environment variable -api_key = os.getenv("GROQ_API_KEY") - -# Model -model = OpenAIChat( - openai_api_base="https://api.groq.com/openai/v1", - openai_api_key=api_key, - model_name="llama-3.1-70b-versatile", - temperature=0.1, -) +from swarms.tools.base_tool import BaseTool +def power(base: int, exponent: int) -> int: + """Calculate base to the power of exponent.""" + return base ** exponent -# Initialize the Managing Director agent -managing_director = Agent( - agent_name="Managing-Director", - system_prompt=f""" - As the Managing Director at Blackstone, your role is to oversee the entire investment analysis process for potential acquisitions. - Your responsibilities include: - 1. Setting the overall strategy and direction for the analysis - 2. Coordinating the efforts of the various team members and ensuring a comprehensive evaluation - 3. Reviewing the findings and recommendations from each team member - 4. Making the final decision on whether to proceed with the acquisition - - For the current potential acquisition of {company}, direct the tasks for the team to thoroughly analyze all aspects of the company, including its financials, industry position, technology, market potential, and regulatory compliance. Provide guidance and feedback as needed to ensure a rigorous and unbiased assessment. - """, - llm=model, - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="managing-director.json", -) +tool = BaseTool(tools=[power]) +result = tool.execute_function_with_dict({"base": 2, "exponent": 3}, "power") +print(result) # Output: 8 +``` -# Initialize the Vice President of Finance -vp_finance = Agent( - agent_name="VP-Finance", - system_prompt=f""" - As the Vice President of Finance at Blackstone, your role is to lead the financial analysis of potential acquisitions. - For the current potential acquisition of {company}, your tasks include: - 1. Conducting a thorough review of {company}' financial statements, including income statements, balance sheets, and cash flow statements - 2. Analyzing key financial metrics such as revenue growth, profitability margins, liquidity ratios, and debt levels - 3. Assessing the company's historical financial performance and projecting future performance based on assumptions and market conditions - 4. Identifying any financial risks or red flags that could impact the acquisition decision - 5. Providing a detailed report on your findings and recommendations to the Managing Director +### `execute_multiple_functions_with_dict` - Be sure to consider factors such as the sustainability of {company}' business model, the strength of its customer base, and its ability to generate consistent cash flows. Your analysis should be data-driven, objective, and aligned with Blackstone's investment criteria. - """, - llm=model, - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="vp-finance.json", -) +**Description:** Execute multiple functions using dictionaries of parameters. -# Initialize the Industry Analyst -industry_analyst = Agent( - agent_name="Industry-Analyst", - system_prompt=f""" - As the Industry Analyst at Blackstone, your role is to provide in-depth research and analysis on the industries and markets relevant to potential acquisitions. - For the current potential acquisition of {company}, your tasks include: - 1. Conducting a comprehensive analysis of the industrial robotics and automation solutions industry, including market size, growth rates, key trends, and future prospects - 2. Identifying the major players in the industry and assessing their market share, competitive strengths and weaknesses, and strategic positioning - 3. Evaluating {company}' competitive position within the industry, including its market share, differentiation, and competitive advantages - 4. Analyzing the key drivers and restraints for the industry, such as technological advancements, labor costs, regulatory changes, and economic conditions - 5. Identifying potential risks and opportunities for {company} based on the industry analysis, such as disruptive technologies, emerging markets, or shifts in customer preferences - - Your analysis should provide a clear and objective assessment of the attractiveness and future potential of the industrial robotics industry, as well as {company}' positioning within it. Consider both short-term and long-term factors, and provide evidence-based insights to inform the investment decision. - """, - llm=model, - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="industry-analyst.json", -) +**Arguments:** -# Initialize the Technology Expert -tech_expert = Agent( - agent_name="Tech-Expert", - system_prompt=f""" - As the Technology Expert at Blackstone, your role is to assess the technological capabilities, competitive advantages, and potential risks of companies being considered for acquisition. - For the current potential acquisition of {company}, your tasks include: - 1. Conducting a deep dive into {company}' proprietary technologies, including its robotics platforms, automation software, and AI capabilities - 2. Assessing the uniqueness, scalability, and defensibility of {company}' technology stack and intellectual property - 3. Comparing {company}' technologies to those of its competitors and identifying any key differentiators or technology gaps - 4. Evaluating {company}' research and development capabilities, including its innovation pipeline, engineering talent, and R&D investments - 5. Identifying any potential technology risks or disruptive threats that could impact {company}' long-term competitiveness, such as emerging technologies or expiring patents - - Your analysis should provide a comprehensive assessment of {company}' technological strengths and weaknesses, as well as the sustainability of its competitive advantages. Consider both the current state of its technology and its future potential in light of industry trends and advancements. - """, - llm=model, - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="tech-expert.json", -) +- `func_dicts` (list[dict]): List of dictionaries containing function parameters -# Initialize the Market Researcher -market_researcher = Agent( - agent_name="Market-Researcher", - system_prompt=f""" - As the Market Researcher at Blackstone, your role is to analyze the target company's customer base, market share, and growth potential to assess the commercial viability and attractiveness of the potential acquisition. - For the current potential acquisition of {company}, your tasks include: - 1. Analyzing {company}' current customer base, including customer segmentation, concentration risk, and retention rates - 2. Assessing {company}' market share within its target markets and identifying key factors driving its market position - 3. Conducting a detailed market sizing and segmentation analysis for the industrial robotics and automation markets, including identifying high-growth segments and emerging opportunities - 4. Evaluating the demand drivers and sales cycles for {company}' products and services, and identifying any potential risks or limitations to adoption - 5. Developing financial projections and estimates for {company}' revenue growth potential based on the market analysis and assumptions around market share and penetration - - Your analysis should provide a data-driven assessment of the market opportunity for {company} and the feasibility of achieving our investment return targets. Consider both bottom-up and top-down market perspectives, and identify any key sensitivities or assumptions in your projections. - """, - llm=model, - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="market-researcher.json", -) +- `func_names` (Optional[list[str]]): Optional list of function names -# Initialize the Regulatory Specialist -regulatory_specialist = Agent( - agent_name="Regulatory-Specialist", - system_prompt=f""" - As the Regulatory Specialist at Blackstone, your role is to identify and assess any regulatory risks, compliance requirements, and potential legal liabilities associated with potential acquisitions. - For the current potential acquisition of {company}, your tasks include: - 1. Identifying all relevant regulatory bodies and laws that govern the operations of {company}, including industry-specific regulations, labor laws, and environmental regulations - 2. Reviewing {company}' current compliance policies, procedures, and track record to identify any potential gaps or areas of non-compliance - 3. Assessing the potential impact of any pending or proposed changes to relevant regulations that could affect {company}' business or create additional compliance burdens - 4. Evaluating the potential legal liabilities and risks associated with {company}' products, services, and operations, including product liability, intellectual property, and customer contracts - 5. Providing recommendations on any regulatory or legal due diligence steps that should be taken as part of the acquisition process, as well as any post-acquisition integration considerations - - Your analysis should provide a comprehensive assessment of the regulatory and legal landscape surrounding {company}, and identify any material risks or potential deal-breakers. Consider both the current state and future outlook, and provide practical recommendations to mitigate identified risks. - """, - llm=model, - max_loops=1, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - state_save_file_type="json", - saved_state_path="regulatory-specialist.json", -) +**Returns:** `list[Any]` - List of results from function executions -# Create a list of agents -agents = [ - managing_director, - vp_finance, - industry_analyst, - tech_expert, - market_researcher, - regulatory_specialist, -] +**Example:** +```python +from swarms.tools.base_tool import BaseTool -# Define multiple flow patterns -flows = [ - "Industry-Analyst -> Tech-Expert -> Market-Researcher -> Regulatory-Specialist -> Managing-Director -> VP-Finance", - "Managing-Director -> VP-Finance -> Industry-Analyst -> Tech-Expert -> Market-Researcher -> Regulatory-Specialist", - "Tech-Expert -> Market-Researcher -> Regulatory-Specialist -> Industry-Analyst -> Managing-Director -> VP-Finance", -] +def add(a: int, b: int) -> int: + """Add two numbers.""" + return a + b -# Create instances of AgentRearrange for each flow pattern -blackstone_acquisition_analysis = AgentRearrange( - name="Blackstone-Acquisition-Analysis", - description="A system for analyzing potential acquisitions", - agents=agents, - flow=flows[0], -) +def multiply(a: int, b: int) -> int: + """Multiply two numbers.""" + return a * b -blackstone_investment_strategy = AgentRearrange( - name="Blackstone-Investment-Strategy", - description="A system for evaluating investment opportunities", - agents=agents, - flow=flows[1], +tool = BaseTool(tools=[add, multiply]) +results = tool.execute_multiple_functions_with_dict( + [{"a": 1, "b": 2}, {"a": 3, "b": 4}], + ["add", "multiply"] ) +print(results) # [3, 12] +``` -blackstone_market_analysis = AgentRearrange( - name="Blackstone-Market-Analysis", - description="A system for analyzing market trends and opportunities", - agents=agents, - flow=flows[2], -) +### `validate_function_schema` -swarm_arrange = SwarmRearrange( - swarms=[ - blackstone_acquisition_analysis, - blackstone_investment_strategy, - blackstone_market_analysis, - ], - flow=f"{blackstone_acquisition_analysis.name} -> {blackstone_investment_strategy.name} -> {blackstone_market_analysis.name}", -) +**Description:** Validate the schema of a function for different AI providers. -print( - swarm_arrange.run( - "Analyze swarms, 150k revenue with 45m+ agents build, with 1.4m downloads since march 2024" - ) -) +**Arguments:** + +- `schema` (Optional[Union[List[Dict[str, Any]], Dict[str, Any]]]): Function schema(s) to validate + +- `provider` (str): Target provider format ("openai", "anthropic", "generic", "auto") + +**Returns:** `bool` - True if schema(s) are valid, False otherwise + +**Example:** +```python +from swarms.tools.base_tool import BaseTool + +openai_schema = { + "type": "function", + "function": { + "name": "add_numbers", + "description": "Add two numbers", + "parameters": { + "type": "object", + "properties": { + "a": {"type": "integer"}, + "b": {"type": "integer"} + }, + "required": ["a", "b"] + } + } +} +tool = BaseTool() +is_valid = tool.validate_function_schema(openai_schema, "openai") +print(is_valid) # True ``` -### Human-in-the-Loop +### `get_schema_provider_format` + +**Description:** Get the detected provider format of a schema. + +**Arguments:** +- `schema` (Dict[str, Any]): Function schema dictionary + +**Returns:** `str` - Provider format ("openai", "anthropic", "generic", "unknown") + +**Example:** ```python -def custom_human_input(task): - return input(f"Review {task} and provide feedback: ") +from swarms.tools.base_tool import BaseTool -# Create arrangement with human intervention -arrangement = SwarmRearrange( - name="HumanAugmented", - swarms=[swarm1, swarm2], - flow="SwarmA -> H -> SwarmB", - human_in_the_loop=True, - custom_human_in_the_loop=custom_human_input -) +openai_schema = { + "type": "function", + "function": {"name": "test", "description": "Test function"} +} -# Execute with human intervention -result = arrangement.run("Initial task") +tool = BaseTool() +provider = tool.get_schema_provider_format(openai_schema) +print(provider) # "openai" ``` -### Complex Multi-Stage Pipeline +### `convert_schema_between_providers` + +**Description:** Convert a function schema between different provider formats. + +**Arguments:** + +- `schema` (Dict[str, Any]): Source function schema + +- `target_provider` (str): Target provider format ("openai", "anthropic", "generic") + +**Returns:** `Dict[str, Any]` - Converted schema +**Example:** ```python -# Define multiple flow patterns -flows = [ - "Collector -> Processor -> Analyzer", - "Analyzer -> ML -> Validator", - "Validator -> Reporter" -] +from swarms.tools.base_tool import BaseTool -# Create arrangements for each flow -pipelines = [ - SwarmRearrange(name=f"Pipeline{i}", swarms=swarms, flow=flow) - for i, flow in enumerate(flows) -] +openai_schema = { + "type": "function", + "function": { + "name": "test_func", + "description": "Test function", + "parameters": {"type": "object", "properties": {}} + } +} -# Create master arrangement -master = SwarmRearrange( - name="MasterPipeline", - swarms=pipelines, - flow="Pipeline0 -> Pipeline1 -> Pipeline2" -) +tool = BaseTool() +anthropic_schema = tool.convert_schema_between_providers(openai_schema, "anthropic") +print(anthropic_schema) +# Output: {"name": "test_func", "description": "Test function", "input_schema": {...}} +``` -# Execute complete pipeline -result = master.run("Start analysis") +### `execute_function_calls_from_api_response` + +**Description:** Automatically detect and execute function calls from OpenAI or Anthropic API responses. + +**Arguments:** + +- `api_response` (Union[Dict[str, Any], str, List[Any]]): The API response containing function calls + +- `sequential` (bool): If True, execute functions sequentially. If False, execute in parallel + +- `max_workers` (int): Maximum number of worker threads for parallel execution + +- `return_as_string` (bool): If True, return results as formatted strings + +**Returns:** `Union[List[Any], List[str]]` - List of results from executed functions + +**Example:** +```python +from swarms.tools.base_tool import BaseTool + +def get_weather(city: str) -> str: + """Get weather for a city.""" + return f"Weather in {city}: Sunny, 25°C" + +# Simulated OpenAI API response +openai_response = { + "choices": [{ + "message": { + "tool_calls": [{ + "type": "function", + "function": { + "name": "get_weather", + "arguments": '{"city": "New York"}' + }, + "id": "call_123" + }] + } + }] +} + +tool = BaseTool(tools=[get_weather]) +results = tool.execute_function_calls_from_api_response(openai_response) +print(results) # ["Function 'get_weather' result:\nWeather in New York: Sunny, 25°C"] ``` -## Best Practices +### `detect_api_response_format` -1. **Flow Validation**: Always validate flows before execution -2. **Error Handling**: Implement try-catch blocks around run() calls -3. **History Tracking**: Use track_history() for monitoring swarm execution -4. **Resource Management**: Set appropriate max_loops to prevent infinite execution -5. **Logging**: Enable verbose mode during development for detailed logging +**Description:** Detect the format of an API response. -## Error Handling +**Arguments:** -The class implements comprehensive error handling: +- `response` (Union[Dict[str, Any], str, BaseModel]): API response to analyze + +**Returns:** `str` - Detected format ("openai", "anthropic", "generic", "unknown") +**Example:** ```python -try: - arrangement = SwarmRearrange(swarms=swarms, flow=flow) - result = arrangement.run(task) -except ValueError as e: - logger.error(f"Flow validation error: {e}") -except Exception as e: - logger.error(f"Execution error: {e}") +from swarms.tools.base_tool import BaseTool + +openai_response = { + "choices": [{"message": {"tool_calls": []}}] +} + +anthropic_response = { + "content": [{"type": "tool_use", "name": "test", "input": {}}] +} + +tool = BaseTool() +print(tool.detect_api_response_format(openai_response)) # "openai" +print(tool.detect_api_response_format(anthropic_response)) # "anthropic" ``` --------------------------------------------------- +--- -# File: swarms/structs/swarm_router.md +## Exception Classes -# SwarmRouter Documentation +The BaseTool class defines several custom exception classes for better error handling: -The `SwarmRouter` class is a flexible routing system designed to manage different types of swarms for task execution. It provides a unified interface to interact with various swarm types, including `AgentRearrange`, `MixtureOfAgents`, `SpreadSheetSwarm`, `SequentialWorkflow`, `ConcurrentWorkflow`, `GroupChat`, `MultiAgentRouter`, `HierarchicalSwarm`, `MajorityVoting`, and `auto` which will dynamically select the most appropriate swarm for you by analyzing your task, name, and description. We will be continuously adding more swarm architectures as we progress with new developments. +- `BaseToolError`: Base exception class for all BaseTool related errors -## Classes +- `ToolValidationError`: Raised when tool validation fails -### Document +- `ToolExecutionError`: Raised when tool execution fails -A Pydantic model for representing document data. +- `ToolNotFoundError`: Raised when a requested tool is not found -| Attribute | Type | Description | -| --- | --- | --- | -| `file_path` | str | Path to the document file. | -| `data` | str | Content of the document. | +- `FunctionSchemaError`: Raised when function schema conversion fails -### SwarmLog +- `ToolDocumentationError`: Raised when tool documentation is missing or invalid -A Pydantic model for capturing log entries. +- `ToolTypeHintError`: Raised when tool type hints are missing or invalid -| Attribute | Type | Description | -| --- | --- | --- | -| `id` | str | Unique identifier for the log entry. | -| `timestamp` | datetime | Time of log creation. | -| `level` | str | Log level (e.g., "info", "error"). | -| `message` | str | Log message content. | -| `swarm_type` | SwarmType | Type of swarm associated with the log. | -| `task` | str | Task being performed (optional). | -| `metadata` | Dict[str, Any] | Additional metadata (optional). | -| `documents` | List[Document] | List of documents associated with the log. | +## Usage Tips -### SwarmRouter +1. **Always provide documentation and type hints** for your functions when using BaseTool +2. **Use verbose=True** during development for detailed logging +3. **Set up function_map** for efficient tool execution by name +4. **Validate schemas** before using them with different AI providers +5. **Use parallel execution** for better performance when executing multiple functions +6. **Handle exceptions** appropriately using the custom exception classes -Main class for routing tasks to different swarm types. +-------------------------------------------------- -| Attribute | Type | Description | -| --- | --- | --- | -| `name` | str | Name of the SwarmRouter instance. | -| `description` | str | Description of the SwarmRouter instance. | -| `max_loops` | int | Maximum number of loops to perform. | -| `agents` | List[Union[Agent, Callable]] | List of Agent objects or callable functions to be used in the swarm. | -| `swarm_type` | SwarmType | Type of swarm to be used. | -| `autosave` | bool | Flag to enable/disable autosave. | -| `rearrange_flow` | str | The flow for the AgentRearrange swarm type. | -| `return_json` | bool | Flag to enable/disable returning the result in JSON format. | -| `auto_generate_prompts` | bool | Flag to enable/disable auto generation of prompts. | -| `shared_memory_system` | Any | Shared memory system for agents. | -| `rules` | str | Rules to inject into every agent. | -| `documents` | List[str] | List of document file paths. | -| `output_type` | OutputType | Output format type (e.g., "string", "dict"). | -| `no_cluster_ops` | bool | Flag to disable cluster operations. | -| `speaker_fn` | callable | Speaker function for GroupChat swarm type. | -| `load_agents_from_csv` | bool | Flag to enable/disable loading agents from CSV. | -| `csv_file_path` | str | Path to the CSV file for loading agents. | -| `return_entire_history` | bool | Flag to enable/disable returning the entire conversation history. | -| `swarm` | Union[AgentRearrange, MixtureOfAgents, SpreadSheetSwarm, SequentialWorkflow, ConcurrentWorkflow, GroupChat, MultiAgentRouter, HierarchicalSwarm, MajorityVoting] | Instantiated swarm object. | -| `logs` | List[SwarmLog] | List of log entries captured during operations. | +# File: swarms\tools\build_tool.md -#### Methods: +# Swarms Tool Documentation -| Method | Parameters | Description | -| --- | --- | --- | -| `__init__` | `self, name: str = "swarm-router", description: str = "Routes your task to the desired swarm", max_loops: int = 1, agents: List[Union[Agent, Callable]] = [], swarm_type: SwarmType = "SequentialWorkflow", autosave: bool = False, rearrange_flow: str = None, return_json: bool = False, auto_generate_prompts: bool = False, shared_memory_system: Any = None, rules: str = None, documents: List[str] = [], output_type: OutputType = "dict", no_cluster_ops: bool = False, speaker_fn: callable = None, load_agents_from_csv: bool = False, csv_file_path: str = None, return_entire_history: bool = True, *args, **kwargs` | Initialize the SwarmRouter. | -| `activate_shared_memory` | `self` | Activate shared memory with all agents. | -| `handle_rules` | `self` | Inject rules to every agent. | -| `activate_ape` | `self` | Activate automatic prompt engineering for agents that support it. | -| `reliability_check` | `self` | Perform reliability checks on the SwarmRouter configuration. | -| `_create_swarm` | `self, task: str = None, *args, **kwargs` | Create and return the specified swarm type or automatically match the best swarm type for a given task. | -| `_log` | `self, level: str, message: str, task: str = "", metadata: Dict[str, Any] = None` | Create a log entry and add it to the logs list. | -| `_run` | `self, task: str, img: str, *args, **kwargs` | Dynamically run the specified task on the selected or matched swarm type. | -| `run` | `self, task: str, img: str = None, *args, **kwargs` | Execute a task on the selected swarm type. | -| `__call__` | `self, task: str, *args, **kwargs` | Make the SwarmRouter instance callable. | -| `batch_run` | `self, tasks: List[str], *args, **kwargs` | Execute a batch of tasks on the selected or matched swarm type. | -| `async_run` | `self, task: str, *args, **kwargs` | Execute a task on the selected or matched swarm type asynchronously. | -| `get_logs` | `self` | Retrieve all logged entries. | -| `concurrent_run` | `self, task: str, *args, **kwargs` | Execute a task on the selected or matched swarm type concurrently. | -| `concurrent_batch_run` | `self, tasks: List[str], *args, **kwargs` | Execute a batch of tasks on the selected or matched swarm type concurrently. | - -## Function: swarm_router - -A convenience function to create and run a SwarmRouter instance. +A tool is a Python function designed to perform specific tasks with clear type annotations and comprehensive docstrings. Below are examples of financial tools to help you get started. -| Parameter | Type | Default | Description | -| --- | --- | --- | --- | -| `name` | str | "swarm-router" | Name of the swarm router. | -| `description` | str | "Routes your task to the desired swarm" | Description of the router. | -| `max_loops` | int | 1 | Maximum number of execution loops. | -| `agents` | List[Union[Agent, Callable]] | [] | List of agents or callables. | -| `swarm_type` | SwarmType | "SequentialWorkflow" | Type of swarm to use. | -| `autosave` | bool | False | Whether to autosave results. | -| `flow` | str | None | Flow configuration. | -| `return_json` | bool | True | Whether to return results as JSON. | -| `auto_generate_prompts` | bool | False | Whether to auto-generate prompts. | -| `task` | str | None | Task to execute. | -| `rules` | str | None | Rules to inject into every agent. | -| `*args` | | | Additional positional arguments passed to SwarmRouter.run() | -| `**kwargs` | | | Additional keyword arguments passed to SwarmRouter.run() | +## Rules -## Installation +To create a tool in the Swarms environment, follow these rules: -To use the SwarmRouter, first install the required dependencies: +1. **Function Definition**: + - The tool must be defined as a Python function. + - The function should perform a specific task and be named appropriately. -```bash -pip install swarms swarm_models -``` +2. **Type Annotations**: + - All arguments and the return value must have type annotations. + - Both input and output types must be strings (`str`). -## Basic Usage +3. **Docstrings**: + - Each function must include a comprehensive docstring that adheres to PEP 257 standards. The docstring should explain: + - The purpose of the function. + - Arguments: names, types, and descriptions. + - Return value: type and description. + - Potential exceptions that the function may raise. + +4. **Input and Output Types**: + - The function's input must be a string. + - The function's output must be a string. + +## Example Financial Tools + +### Example 1: Fetch Stock Price from Yahoo Finance ```python -import os -from dotenv import load_dotenv -from swarms import Agent, SwarmRouter, SwarmType -from swarm_models import OpenAIChat +import yfinance as yf -load_dotenv() +def get_stock_price(symbol: str) -> str: + """ + Fetches the current stock price from Yahoo Finance. -# Get the OpenAI API key from the environment variable -api_key = os.getenv("GROQ_API_KEY") + Args: + symbol (str): The stock symbol (e.g., "AAPL", "TSLA", "NVDA"). -# Model -model = OpenAIChat( - openai_api_base="https://api.groq.com/openai/v1", - openai_api_key=api_key, - model_name="llama-3.1-70b-versatile", - temperature=0.1, -) + Returns: + str: A formatted string containing the current stock price and basic information. -# Define specialized system prompts for each agent -DATA_EXTRACTOR_PROMPT = """You are a highly specialized private equity agent focused on data extraction from various documents. Your expertise includes: -1. Extracting key financial metrics (revenue, EBITDA, growth rates, etc.) from financial statements and reports -2. Identifying and extracting important contract terms from legal documents -3. Pulling out relevant market data from industry reports and analyses -4. Extracting operational KPIs from management presentations and internal reports -5. Identifying and extracting key personnel information from organizational charts and bios -Provide accurate, structured data extracted from various document types to support investment analysis.""" + Raises: + ValueError: If the stock symbol is invalid or data cannot be retrieved. + Exception: If there is an error with the API request. + """ + try: + # Remove any whitespace and convert to uppercase + symbol = symbol.strip().upper() + + if not symbol: + raise ValueError("Stock symbol cannot be empty.") + + # Fetch stock data + stock = yf.Ticker(symbol) + info = stock.info + + if not info or 'regularMarketPrice' not in info: + raise ValueError(f"Unable to fetch data for symbol: {symbol}") + + current_price = info.get('regularMarketPrice', 'N/A') + previous_close = info.get('regularMarketPreviousClose', 'N/A') + market_cap = info.get('marketCap', 'N/A') + company_name = info.get('longName', symbol) + + # Format market cap for readability + if isinstance(market_cap, (int, float)) and market_cap > 0: + if market_cap >= 1e12: + market_cap_str = f"${market_cap/1e12:.2f}T" + elif market_cap >= 1e9: + market_cap_str = f"${market_cap/1e9:.2f}B" + elif market_cap >= 1e6: + market_cap_str = f"${market_cap/1e6:.2f}M" + else: + market_cap_str = f"${market_cap:,.0f}" + else: + market_cap_str = "N/A" + + # Calculate price change + if isinstance(current_price, (int, float)) and isinstance(previous_close, (int, float)): + price_change = current_price - previous_close + price_change_percent = (price_change / previous_close) * 100 + change_str = f"{price_change:+.2f} ({price_change_percent:+.2f}%)" + else: + change_str = "N/A" + + result = f""" +Stock: {company_name} ({symbol}) +Current Price: ${current_price} +Previous Close: ${previous_close} +Change: {change_str} +Market Cap: {market_cap_str} + """.strip() + + return result + + except ValueError as e: + print(f"Value Error: {e}") + raise + except Exception as e: + print(f"Error fetching stock data: {e}") + raise +``` -SUMMARIZER_PROMPT = """You are an expert private equity agent specializing in summarizing complex documents. Your core competencies include: -1. Distilling lengthy financial reports into concise executive summaries -2. Summarizing legal documents, highlighting key terms and potential risks -3. Condensing industry reports to capture essential market trends and competitive dynamics -4. Summarizing management presentations to highlight key strategic initiatives and projections -5. Creating brief overviews of technical documents, emphasizing critical points for non-technical stakeholders -Deliver clear, concise summaries that capture the essence of various documents while highlighting information crucial for investment decisions.""" +### Example 2: Fetch Cryptocurrency Price from CoinGecko -# Initialize specialized agents -data_extractor_agent = Agent( - agent_name="Data-Extractor", - system_prompt=DATA_EXTRACTOR_PROMPT, - llm=model, - max_loops=1, - autosave=True, - verbose=True, - dynamic_temperature_enabled=True, - saved_state_path="data_extractor_agent.json", - user_name="pe_firm", - retry_attempts=1, - context_length=200000, - output_type="string", -) +```python +import requests -summarizer_agent = Agent( - agent_name="Document-Summarizer", - system_prompt=SUMMARIZER_PROMPT, - llm=model, - max_loops=1, - autosave=True, - verbose=True, - dynamic_temperature_enabled=True, - saved_state_path="summarizer_agent.json", - user_name="pe_firm", - retry_attempts=1, - context_length=200000, - output_type="string", -) +def get_crypto_price(coin_id: str) -> str: + """ + Fetches the current cryptocurrency price from CoinGecko API. -# Initialize the SwarmRouter -router = SwarmRouter( - name="pe-document-analysis-swarm", - description="Analyze documents for private equity due diligence and investment decision-making", - max_loops=1, - agents=[data_extractor_agent, summarizer_agent], - swarm_type="ConcurrentWorkflow", - autosave=True, - return_json=True, -) + Args: + coin_id (str): The cryptocurrency ID (e.g., "bitcoin", "ethereum", "cardano"). -# Example usage -if __name__ == "__main__": - # Run a comprehensive private equity document analysis task - result = router.run( - "Where is the best place to find template term sheets for series A startups? Provide links and references" - ) - print(result) + Returns: + str: A formatted string containing the current crypto price and market data. - # Retrieve and print logs - for log in router.get_logs(): - print(f"{log.timestamp} - {log.level}: {log.message}") + Raises: + ValueError: If the coin ID is invalid or data cannot be retrieved. + requests.exceptions.RequestException: If there is an error with the API request. + """ + try: + # Remove any whitespace and convert to lowercase + coin_id = coin_id.strip().lower() + + if not coin_id: + raise ValueError("Coin ID cannot be empty.") + + url = f"https://api.coingecko.com/api/v3/simple/price" + params = { + "ids": coin_id, + "vs_currencies": "usd", + "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() + + if coin_id not in data: + raise ValueError(f"Coin ID '{coin_id}' not found. Please check the spelling.") + + coin_data = data[coin_id] + + if not coin_data: + raise ValueError(f"No data available for coin ID: {coin_id}") + + usd_price = coin_data.get('usd', 'N/A') + market_cap = coin_data.get('usd_market_cap', 'N/A') + volume_24h = coin_data.get('usd_24h_vol', 'N/A') + change_24h = coin_data.get('usd_24h_change', 'N/A') + last_updated = coin_data.get('last_updated_at', 'N/A') + + # Format large numbers for readability + def format_number(value): + if isinstance(value, (int, float)) and value > 0: + if value >= 1e12: + return f"${value/1e12:.2f}T" + elif value >= 1e9: + return f"${value/1e9:.2f}B" + elif value >= 1e6: + return f"${value/1e6:.2f}M" + elif value >= 1e3: + return f"${value/1e3:.2f}K" + else: + return f"${value:,.2f}" + return "N/A" + + # Format the result + result = f""" +Cryptocurrency: {coin_id.title()} +Current Price: ${usd_price:,.8f}" if isinstance(usd_price, (int, float)) else f"Current Price: {usd_price} +Market Cap: {format_number(market_cap)} +24h Volume: {format_number(volume_24h)} +24h Change: {change_24h:+.2f}%" if isinstance(change_24h, (int, float)) else f"24h Change: {change_24h} +Last Updated: {last_updated} + """.strip() + + return result + + except requests.exceptions.RequestException as e: + print(f"Request Error: {e}") + raise + except ValueError as e: + print(f"Value Error: {e}") + raise + except Exception as e: + print(f"Error fetching crypto data: {e}") + raise ``` -## Advanced Usage +### Example 3: Calculate Portfolio Performance -### Changing Swarm Types +```python +def calculate_portfolio_performance(initial_investment_str: str, current_value_str: str, time_period_str: str) -> str: + """ + Calculates portfolio performance metrics including return percentage and annualized return. -You can create multiple SwarmRouter instances with different swarm types: + Args: + initial_investment_str (str): The initial investment amount as a string. + current_value_str (str): The current portfolio value as a string. + time_period_str (str): The time period in years as a string. -```python -sequential_router = SwarmRouter( - name="SequentialRouter", - agents=[agent1, agent2], - swarm_type="SequentialWorkflow" -) + Returns: + str: A formatted string containing portfolio performance metrics. -concurrent_router = SwarmRouter( - name="ConcurrentRouter", - agents=[agent1, agent2], - swarm_type="ConcurrentWorkflow" -) + Raises: + ValueError: If any of the inputs cannot be converted to the appropriate type or are negative. + """ + try: + initial_investment = float(initial_investment_str) + current_value = float(current_value_str) + time_period = float(time_period_str) + + if initial_investment <= 0 or current_value < 0 or time_period <= 0: + raise ValueError("Initial investment and time period must be positive, current value must be non-negative.") + + # Calculate total return + total_return = current_value - initial_investment + total_return_percentage = (total_return / initial_investment) * 100 + + # Calculate annualized return + if time_period > 0: + annualized_return = ((current_value / initial_investment) ** (1 / time_period) - 1) * 100 + else: + annualized_return = 0 + + # Determine performance status + if total_return > 0: + status = "Profitable" + elif total_return < 0: + status = "Loss" + else: + status = "Break-even" + + result = f""" +Portfolio Performance Analysis: +Initial Investment: ${initial_investment:,.2f} +Current Value: ${current_value:,.2f} +Time Period: {time_period:.1f} years + +Total Return: ${total_return:+,.2f} ({total_return_percentage:+.2f}%) +Annualized Return: {annualized_return:+.2f}% +Status: {status} + """.strip() + + return result + + except ValueError as e: + print(f"Value Error: {e}") + raise + except Exception as e: + print(f"Error calculating portfolio performance: {e}") + raise ``` -### Automatic Swarm Type Selection - -You can let the SwarmRouter automatically select the best swarm type for a given task: +### Example 4: Calculate Compound Interest ```python -auto_router = SwarmRouter( - name="AutoRouter", - agents=[agent1, agent2], - swarm_type="auto" -) +def calculate_compound_interest(principal_str: str, rate_str: str, time_str: str, compounding_frequency_str: str) -> str: + """ + Calculates compound interest for investment planning. -result = auto_router.run("Analyze and summarize the quarterly financial report") + Args: + principal_str (str): The initial investment amount as a string. + rate_str (str): The annual interest rate (as decimal) as a string. + time_str (str): The investment time period in years as a string. + compounding_frequency_str (str): The number of times interest is compounded per year as a string. + + Returns: + str: A formatted string containing the compound interest calculation results. + + Raises: + ValueError: If any of the inputs cannot be converted to the appropriate type or are negative. + """ + try: + principal = float(principal_str) + rate = float(rate_str) + time = float(time_str) + n = int(compounding_frequency_str) + + if principal <= 0 or rate < 0 or time <= 0 or n <= 0: + raise ValueError("Principal, time, and compounding frequency must be positive. Rate must be non-negative.") + + # Calculate compound interest + amount = principal * (1 + rate / n) ** (n * time) + interest_earned = amount - principal + + # Calculate effective annual rate + effective_rate = ((1 + rate / n) ** n - 1) * 100 + + result = f""" +Compound Interest Calculation: +Principal: ${principal:,.2f} +Annual Rate: {rate*100:.2f}% +Time Period: {time:.1f} years +Compounding Frequency: {n} times per year + +Final Amount: ${amount:,.2f} +Interest Earned: ${interest_earned:,.2f} +Effective Annual Rate: {effective_rate:.2f}% + """.strip() + + return result + + except ValueError as e: + print(f"Value Error: {e}") + raise + except Exception as e: + print(f"Error calculating compound interest: {e}") + raise ``` -### Loading Agents from CSV +## Integrating Tools into an Agent -To load agents from a CSV file: +To integrate tools into an agent, simply pass callable functions with proper type annotations and documentation into the agent class. ```python -csv_router = SwarmRouter( - name="CSVAgentRouter", - load_agents_from_csv=True, - csv_file_path="agents.csv", - swarm_type="SequentialWorkflow" +from swarms import Agent + +# Initialize the financial analysis agent +agent = Agent( + agent_name="Financial-Analysis-Agent", + system_prompt=( + "You are a professional financial analyst agent. Use the provided tools to " + "analyze stocks, cryptocurrencies, and investment performance. Provide " + "clear, accurate financial insights and recommendations. Always format " + "responses in markdown for better readability." + ), + model_name="gpt-4o", + max_loops=3, + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + dynamic_temperature_enabled=True, + saved_state_path="financial_agent.json", + tools=[get_stock_price, get_crypto_price, calculate_portfolio_performance], + user_name="financial_analyst", + retry_attempts=3, + context_length=200000, ) -result = csv_router.run("Process the client data") +# Run the agent +response = agent("Analyze the current price of Apple stock and Bitcoin, then calculate the performance of a $10,000 investment in each over the past 2 years.") +print(response) ``` -### Using Shared Memory System - -To enable shared memory across agents: +## Complete Financial Analysis Example ```python -from swarms.memory import SemanticMemory +import yfinance as yf +import requests +from swarms import Agent -memory_system = SemanticMemory() +def get_stock_price(symbol: str) -> str: + """ + Fetches the current stock price from Yahoo Finance. -memory_router = SwarmRouter( - name="MemoryRouter", - agents=[agent1, agent2], - shared_memory_system=memory_system, - swarm_type="SequentialWorkflow" + Args: + symbol (str): The stock symbol (e.g., "AAPL", "TSLA", "NVDA"). + + Returns: + str: A formatted string containing the current stock price and basic information. + + Raises: + ValueError: If the stock symbol is invalid or data cannot be retrieved. + Exception: If there is an error with the API request. + """ + try: + symbol = symbol.strip().upper() + + if not symbol: + raise ValueError("Stock symbol cannot be empty.") + + stock = yf.Ticker(symbol) + info = stock.info + + if not info or 'regularMarketPrice' not in info: + raise ValueError(f"Unable to fetch data for symbol: {symbol}") + + current_price = info.get('regularMarketPrice', 'N/A') + previous_close = info.get('regularMarketPreviousClose', 'N/A') + market_cap = info.get('marketCap', 'N/A') + company_name = info.get('longName', symbol) + + if isinstance(market_cap, (int, float)) and market_cap > 0: + if market_cap >= 1e12: + market_cap_str = f"${market_cap/1e12:.2f}T" + elif market_cap >= 1e9: + market_cap_str = f"${market_cap/1e9:.2f}B" + elif market_cap >= 1e6: + market_cap_str = f"${market_cap/1e6:.2f}M" + else: + market_cap_str = f"${market_cap:,.0f}" + else: + market_cap_str = "N/A" + + if isinstance(current_price, (int, float)) and isinstance(previous_close, (int, float)): + price_change = current_price - previous_close + price_change_percent = (price_change / previous_close) * 100 + change_str = f"{price_change:+.2f} ({price_change_percent:+.2f}%)" + else: + change_str = "N/A" + + result = f""" +Stock: {company_name} ({symbol}) +Current Price: ${current_price} +Previous Close: ${previous_close} +Change: {change_str} +Market Cap: {market_cap_str} + """.strip() + + return result + + except ValueError as e: + print(f"Value Error: {e}") + raise + except Exception as e: + print(f"Error fetching stock data: {e}") + raise + +def get_crypto_price(coin_id: str) -> str: + """ + Fetches the current cryptocurrency price from CoinGecko API. + + Args: + coin_id (str): The cryptocurrency ID (e.g., "bitcoin", "ethereum", "cardano"). + + Returns: + str: A formatted string containing the current crypto price and market data. + + Raises: + ValueError: If the coin ID is invalid or data cannot be retrieved. + requests.exceptions.RequestException: If there is an error with the API request. + """ + try: + coin_id = coin_id.strip().lower() + + if not coin_id: + raise ValueError("Coin ID cannot be empty.") + + url = f"https://api.coingecko.com/api/v3/simple/price" + params = { + "ids": coin_id, + "vs_currencies": "usd", + "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() + + if coin_id not in data: + raise ValueError(f"Coin ID '{coin_id}' not found. Please check the spelling.") + + coin_data = data[coin_id] + + if not coin_data: + raise ValueError(f"No data available for coin ID: {coin_id}") + + usd_price = coin_data.get('usd', 'N/A') + market_cap = coin_data.get('usd_market_cap', 'N/A') + volume_24h = coin_data.get('usd_24h_vol', 'N/A') + change_24h = coin_data.get('usd_24h_change', 'N/A') + last_updated = coin_data.get('last_updated_at', 'N/A') + + def format_number(value): + if isinstance(value, (int, float)) and value > 0: + if value >= 1e12: + return f"${value/1e12:.2f}T" + elif value >= 1e9: + return f"${value/1e9:.2f}B" + elif value >= 1e6: + return f"${value/1e6:.2f}M" + elif value >= 1e3: + return f"${value/1e3:.2f}K" + else: + return f"${value:,.2f}" + return "N/A" + + result = f""" +Cryptocurrency: {coin_id.title()} +Current Price: ${usd_price:,.8f}" if isinstance(usd_price, (int, float)) else f"Current Price: {usd_price} +Market Cap: {format_number(market_cap)} +24h Volume: {format_number(volume_24h)} +24h Change: {change_24h:+.2f}%" if isinstance(change_24h, (int, float)) else f"24h Change: {change_24h} +Last Updated: {last_updated} + """.strip() + + return result + + except requests.exceptions.RequestException as e: + print(f"Request Error: {e}") + raise + except ValueError as e: + print(f"Value Error: {e}") + raise + except Exception as e: + print(f"Error fetching crypto data: {e}") + raise + +# Initialize the financial analysis agent +agent = Agent( + agent_name="Financial-Analysis-Agent", + system_prompt=( + "You are a professional financial analyst agent specializing in stock and " + "cryptocurrency analysis. Use the provided tools to fetch real-time market " + "data and provide comprehensive financial insights. Always present data " + "in a clear, professional format with actionable recommendations." + ), + model_name="gpt-4o", + max_loops=3, + autosave=True, + dashboard=False, + verbose=True, + streaming_on=True, + dynamic_temperature_enabled=True, + saved_state_path="financial_agent.json", + tools=[get_stock_price, get_crypto_price], + user_name="financial_analyst", + retry_attempts=3, + context_length=200000, ) -result = memory_router.run("Analyze historical data and make predictions") +# Run the agent +response = agent("What are the current prices and market data for Apple stock and Bitcoin? Provide a brief analysis of their performance.") +print(response) ``` -### Injecting Rules to All Agents -To inject common rules into all agents: +-------------------------------------------------- -```python -rules = """ -1. Always provide sources for your information -2. Check your calculations twice -3. Explain your reasoning clearly -4. Highlight uncertainties and assumptions -""" +# File: swarms\tools\main.md -rules_router = SwarmRouter( - name="RulesRouter", - agents=[agent1, agent2], - rules=rules, - swarm_type="SequentialWorkflow" -) +# The Swarms Tool System: Functions, Pydantic BaseModels as Tools, and Radical Customization -result = rules_router.run("Analyze the investment opportunity") -``` -## Use Cases +This guide provides an in-depth look at the Swarms Tool System, focusing on its functions, the use of Pydantic BaseModels as tools, and the extensive customization options available. Aimed at developers, this documentation highlights how the Swarms framework works and offers detailed examples of creating and customizing tools and agents, specifically for accounting tasks. -### AgentRearrange +The Swarms Tool System is a flexible and extensible component of the Swarms framework that allows for the creation, registration, and utilization of various tools. These tools can perform a wide range of tasks and are integrated into agents to provide specific functionalities. The system supports multiple ways to define tools, including using Pydantic BaseModels, functions, and dictionaries. -Use Case: Optimizing agent order for complex multi-step tasks. +### Architecture -```python -rearrange_router = SwarmRouter( - name="TaskOptimizer", - description="Optimize agent order for multi-step tasks", - max_loops=3, - agents=[data_extractor, analyzer, summarizer], - swarm_type="AgentRearrange", - rearrange_flow=f"{data_extractor.name} -> {analyzer.name} -> {summarizer.name}" -) +The architecture of the Swarms Tool System is designed to be highly modular. It consists of the following main components: -result = rearrange_router.run("Analyze and summarize the quarterly financial report") -``` +1. **Agents:** The primary entities that execute tasks. +2. **Tools:** Functions or classes that perform specific operations. +3. **Schemas:** Definitions of input and output data formats using Pydantic BaseModels. -### MixtureOfAgents +### Key Concepts -Use Case: Combining diverse expert agents for comprehensive analysis. +#### Tools -```python -mixture_router = SwarmRouter( - name="ExpertPanel", - description="Combine insights from various expert agents", - max_loops=1, - agents=[financial_expert, market_analyst, tech_specialist, aggregator], - swarm_type="MixtureOfAgents" -) +Tools are the core functional units within the Swarms framework. They can be defined in various ways: -result = mixture_router.run("Evaluate the potential acquisition of TechStartup Inc.") -``` +- **Pydantic BaseModels**: Tools can be defined using Pydantic BaseModels to ensure data validation and serialization. +- **Functions**: Tools can be simple or complex functions. +- **Dictionaries**: Tools can be represented as dictionaries for flexibility. -### SpreadSheetSwarm +#### Agents -Use Case: Collaborative data processing and analysis. +Agents utilize tools to perform tasks. They are configured with a set of tools and schemas, and they execute the tools based on the input they receive. -```python -spreadsheet_router = SwarmRouter( - name="DataProcessor", - description="Collaborative data processing and analysis", - max_loops=1, - agents=[data_cleaner, statistical_analyzer, visualizer], - swarm_type="SpreadSheetSwarm" -) +## Detailed Documentation -result = spreadsheet_router.run("Process and visualize customer churn data") -``` +### Tool Definition -### SequentialWorkflow +#### Using Pydantic BaseModels -Use Case: Step-by-step document analysis and report generation. +Pydantic BaseModels provide a structured way to define tool inputs and outputs. They ensure data validation and serialization, making them ideal for complex data handling. -```python -sequential_router = SwarmRouter( - name="ReportGenerator", - description="Generate comprehensive reports sequentially", - max_loops=1, - agents=[data_extractor, analyzer, writer, reviewer], - swarm_type="SequentialWorkflow", - return_entire_history=True -) +**Example:** -result = sequential_router.run("Create a due diligence report for Project Alpha") -``` +Define Pydantic BaseModels for accounting tasks: -### ConcurrentWorkflow +```python +from pydantic import BaseModel -Use Case: Parallel processing of multiple data sources. +class CalculateTax(BaseModel): + income: float -```python -concurrent_router = SwarmRouter( - name="MultiSourceAnalyzer", - description="Analyze multiple data sources concurrently", - max_loops=1, - agents=[financial_analyst, market_researcher, competitor_analyst], - swarm_type="ConcurrentWorkflow", - output_type="string" -) +class GenerateInvoice(BaseModel): + client_name: str + amount: float + date: str -result = concurrent_router.run("Conduct a comprehensive market analysis for Product X") +class SummarizeExpenses(BaseModel): + expenses: list[dict] ``` -### GroupChat - -Use Case: Simulating a group discussion with multiple agents. +Define tool functions using these models: ```python -group_chat_router = SwarmRouter( - name="GroupChat", - description="Simulate a group discussion with multiple agents", - max_loops=10, - agents=[financial_analyst, market_researcher, competitor_analyst], - swarm_type="GroupChat", - speaker_fn=custom_speaker_function -) +def calculate_tax(data: CalculateTax) -> dict: + tax_rate = 0.3 # Example tax rate + tax = data.income * tax_rate + return {"income": data.income, "tax": tax} -result = group_chat_router.run("Discuss the pros and cons of expanding into the Asian market") +def generate_invoice(data: GenerateInvoice) -> dict: + invoice = { + "client_name": data.client_name, + "amount": data.amount, + "date": data.date, + "invoice_id": "INV12345" + } + return invoice + +def summarize_expenses(data: SummarizeExpenses) -> dict: + total_expenses = sum(expense['amount'] for expense in data.expenses) + return {"total_expenses": total_expenses} ``` -### MultiAgentRouter +#### Using Functions Directly -Use Case: Routing tasks to the most appropriate agent. +Tools can also be defined directly as functions without using Pydantic models. This approach is suitable for simpler tasks where complex validation is not required. -```python -multi_agent_router = SwarmRouter( - name="MultiAgentRouter", - description="Route tasks to specialized agents", - max_loops=1, - agents=[financial_analyst, market_researcher, competitor_analyst], - swarm_type="MultiAgentRouter", - shared_memory_system=memory_system -) +**Example:** -result = multi_agent_router.run("Analyze the competitive landscape for our new product") +```python +def basic_tax_calculation(income: float) -> dict: + tax_rate = 0.25 + tax = income * tax_rate + return {"income": income, "tax": tax} ``` -### HierarchicalSwarm +#### Using Dictionaries -Use Case: Creating a hierarchical structure of agents with a director. +Tools can be represented as dictionaries, providing maximum flexibility. This method is useful when the tool's functionality is more dynamic or when integrating with external systems. + +**Example:** ```python -hierarchical_router = SwarmRouter( - name="HierarchicalSwarm", - description="Hierarchical organization of agents with a director", - max_loops=3, - agents=[director, analyst1, analyst2, researcher], - swarm_type="HiearchicalSwarm", - return_all_history=True -) +basic_tool_schema = { + "name": "basic_tax_tool", + "description": "A basic tax calculation tool", + "parameters": { + "type": "object", + "properties": { + "income": {"type": "number", "description": "Income amount"} + }, + "required": ["income"] + } +} -result = hierarchical_router.run("Develop a comprehensive market entry strategy") +def basic_tax_tool(income: float) -> dict: + tax_rate = 0.2 + tax = income * tax_rate + return {"income": income, "tax": tax} ``` -### MajorityVoting +### Tool Registration -Use Case: Using consensus among multiple agents for decision-making. +Tools need to be registered with the agent for it to utilize them. This can be done by specifying the tools in the `tools` parameter during agent initialization. + +**Example:** ```python -voting_router = SwarmRouter( - name="MajorityVoting", - description="Make decisions using consensus among agents", - max_loops=1, - agents=[analyst1, analyst2, analyst3, consensus_agent], - swarm_type="MajorityVoting" -) +from swarms import Agent +from llama_hosted import llama3Hosted -result = voting_router.run("Should we invest in Company X based on the available data?") -``` +# Define Pydantic BaseModels for accounting tasks +class CalculateTax(BaseModel): + income: float -### Auto Select (Experimental) -Autonomously selects the right swarm by conducting vector search on your input task or name or description or all 3. +class GenerateInvoice(BaseModel): + client_name: str + amount: float + date: str -```python -auto_router = SwarmRouter( - name="MultiSourceAnalyzer", - description="Analyze multiple data sources concurrently", - max_loops=1, - agents=[financial_analyst, market_researcher, competitor_analyst], - swarm_type="auto" # Set this to 'auto' for it to auto select your swarm. It's match words like concurrently multiple -> "ConcurrentWorkflow" -) +class SummarizeExpenses(BaseModel): + expenses: list[dict] -result = auto_router.run("Conduct a comprehensive market analysis for Product X") -``` +# Define tool functions using these models +def calculate_tax(data: CalculateTax) -> dict: + tax_rate = 0.3 + tax = data.income * tax_rate + return {"income": data.income, "tax": tax} -## Advanced Features +def generate_invoice(data: GenerateInvoice) -> dict: + invoice = { + "client_name": data.client_name, + "amount": data.amount, + "date": data.date, + "invoice_id": "INV12345" + } + return invoice -### Processing Documents +def summarize_expenses(data: SummarizeExpenses) -> dict: + total_expenses = sum(expense['amount'] for expense in data.expenses) + return {"total_expenses": total_expenses} -To process documents with the SwarmRouter: +# Function to generate a tool schema for demonstration purposes +def create_tool_schema(): + return { + "name": "execute", + "description": "Executes code on the user's machine", + "parameters": { + "type": "object", + "properties": { + "language": { + "type": "string", + "description": "Programming language", + "enum": ["python", "java"] + }, + "code": {"type": "string", "description": "Code to execute"} + }, + "required": ["language", "code"] + } + } -```python -document_router = SwarmRouter( - name="DocumentProcessor", - agents=[document_analyzer, summarizer], - documents=["report.pdf", "contract.docx", "data.csv"], - swarm_type="SequentialWorkflow" +# Initialize the agent with the tools +agent = Agent( + agent_name="Accounting Agent", + system_prompt="This agent assists with various accounting tasks.", + sop_list=["Provide accurate and timely accounting services."], + llm=llama3Hosted(), + max_loops="auto", + interactive=True, + verbose=True, + tool_schema=BaseModel, + list_base_models=[ + CalculateTax, + GenerateInvoice, + SummarizeExpenses + ], + output_type=str, + metadata_output_type="json", + function_calling_format_type="OpenAI", + function_calling_type="json", + tools=[ + calculate_tax, + generate_invoice, + summarize_expenses + ], + list_base_models_json=create_tool_schema(), ) - -result = document_router.run("Extract key information from the provided documents") ``` -### Batch Processing - -To process multiple tasks in a batch: - -```python -tasks = ["Analyze Q1 report", "Summarize competitor landscape", "Evaluate market trends"] -results = router.batch_run(tasks) -``` +### Running the Agent -### Asynchronous Execution +The agent can execute tasks using the `run` method. This method takes a prompt and determines the appropriate tool to use based on the input. -For asynchronous task execution: +**Example:** ```python -result = await router.async_run("Generate financial projections") -``` - -### Concurrent Execution +# Example task: Calculate tax for an income +result = agent.run("Calculate the tax for an income of $50,000.") +print(f"Result: {result}") -To run a single task concurrently: +# Example task: Generate an invoice +invoice_data = agent.run("Generate an invoice for John Doe for $1500 on 2024-06-01.") +print(f"Invoice Data: {invoice_data}") -```python -result = router.concurrent_run("Analyze multiple data streams") +# Example task: Summarize expenses +expenses = [ + {"amount": 200.0, "description": "Office supplies"}, + {"amount": 1500.0, "description": "Software licenses"}, + {"amount": 300.0, "description": "Travel expenses"} +] +summary = agent.run("Summarize these expenses: " + str(expenses)) +print(f"Expenses Summary: {summary}") ``` -### Concurrent Batch Processing - -To process multiple tasks concurrently: -```python -tasks = ["Task 1", "Task 2", "Task 3"] -results = router.concurrent_batch_run(tasks) -``` +### Customizing Tools -### Using the SwarmRouter as a Callable +Custom tools can be created to extend the functionality of the Swarms framework. This can include integrating external APIs, performing complex calculations, or handling specialized data formats. -You can use the SwarmRouter instance directly as a callable: +**Example: Custom Accounting Tool** ```python -router = SwarmRouter( - name="CallableRouter", - agents=[agent1, agent2], - swarm_type="SequentialWorkflow" -) - -result = router("Analyze the market data") # Equivalent to router.run("Analyze the market data") -``` - -### Using the swarm_router Function +from pydantic import BaseModel -For quick one-off tasks, you can use the swarm_router function: +class CustomAccountingTool(BaseModel): + data: dict -```python -from swarms import swarm_router +def custom_accounting_tool(data: CustomAccountingTool) -> dict: + # Custom logic for the accounting tool + result = { + "status": "success", + "data_processed": len(data.data) + } + return result -result = swarm_router( - name="QuickRouter", - agents=[agent1, agent2], - swarm_type="ConcurrentWorkflow", - task="Analyze the quarterly report" +# Register the custom tool with the agent +agent = Agent( + agent_name="Accounting Agent", + system_prompt="This agent assists with various accounting tasks.", + sop_list=["Provide accurate and timely accounting services."], + llm=llama3Hosted(), + max_loops="auto", + interactive=True, + verbose=True, + tool_schema=BaseModel, + list_base_models=[ + CalculateTax, + GenerateInvoice, + SummarizeExpenses, + CustomAccountingTool + ], + output_type=str, + metadata_output_type="json", + function_calling_format_type="OpenAI", + function_calling_type="json", + tools=[ + calculate_tax, + generate_invoice, + summarize_expenses, + custom_accounting_tool + ], + list_base_models_json=create_tool_schema(), ) ``` -## Best Practices - -1. Choose the appropriate swarm type based on your task requirements. - -2. Provide clear and specific tasks to the swarm for optimal results. - -3. Regularly review logs to monitor performance and identify potential issues. - -4. Use descriptive names and descriptions for your SwarmRouter and agents. - -5. Implement proper error handling in your application code. +### Advanced Customization -6. Consider the nature of your tasks when choosing a swarm type (e.g., use ConcurrentWorkflow for tasks that can be parallelized). +Advanced customization involves modifying the core components of the Swarms framework. This includes extending existing classes, adding new methods, or integrating third-party libraries. -7. Optimize your agents' prompts and configurations for best performance within the swarm. +**Example: Extending the Agent Class** -8. Utilize the automatic swarm type selection feature for tasks where the optimal swarm type is not immediately clear. +```python +from swarms import Agent -9. Take advantage of batch processing and concurrent execution for handling multiple tasks efficiently. +class AdvancedAccountingAgent(Agent): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) -10. Use the reliability check feature to ensure your SwarmRouter is properly configured before running tasks. + def custom_behavior(self): + print("Executing custom behavior") -11. Consider using shared memory systems when agents need to share context or knowledge. + def another_custom_method(self): + print("Another -12. Inject common rules when you want consistent behavior across all agents. + custom method") -13. Use the appropriate output type (string, dict, etc.) based on how you plan to process the results. +# Initialize the advanced agent +advanced_agent = AdvancedAccountingAgent( + agent_name="Advanced Accounting Agent", + system_prompt="This agent performs advanced accounting tasks.", + sop_list=["Provide advanced accounting services."], + llm=llama3Hosted(), + max_loops="auto", + interactive=True, + verbose=True, + tool_schema=BaseModel, + list_base_models=[ + CalculateTax, + GenerateInvoice, + SummarizeExpenses, + CustomAccountingTool + ], + output_type=str, + metadata_output_type="json", + function_calling_format_type="OpenAI", + function_calling_type="json", + tools=[ + calculate_tax, + generate_invoice, + summarize_expenses, + custom_accounting_tool + ], + list_base_models_json=create_tool_schema(), +) -14. When working with large documents, provide file paths instead of loading content into memory. +# Call custom methods +advanced_agent.custom_behavior() +advanced_agent.another_custom_method() +``` -15. For complex agent interactions, use the GroupChat or HierarchicalSwarm types to facilitate structured communication. +### Integrating External Libraries --------------------------------------------------- +You can integrate external libraries to extend the functionality of your tools. This is useful for adding new capabilities or leveraging existing libraries for complex tasks. -# File: swarms/structs/task.md +**Example: Integrating Pandas for Data Processing** -# Task Class Documentation +```python +import pandas as pd +from pydantic import BaseModel -The `Task` class is a pivotal component designed for managing tasks in a sequential workflow. This class allows for the execution of tasks using various agents, which can be callable objects or specific instances of the `Agent` class. It supports the scheduling of tasks, handling their dependencies, and setting conditions and actions that govern their execution. +class DataFrameTool(BaseModel): + data: list[dict] -Key features of the `Task` class include: -- Executing tasks with specified agents and handling their results. -- Scheduling tasks to run at specified times. -- Setting triggers, actions, and conditions for tasks. -- Managing task dependencies and priorities. -- Providing a history of task executions for tracking purposes. +def process_data_frame(data: DataFrameTool) -> dict: + df = pd.DataFrame(data.data) + summary = df.describe().to_dict() + return {"summary": summary} -## Class Definition +# Register the tool with the agent +agent = Agent( + agent_name="Data Processing Agent", + system_prompt="This agent processes data frames.", + sop_list=["Provide data processing services."], + llm=llama3Hosted(), + max_loops="auto", + interactive=True, + verbose=True, + tool_schema=BaseModel, + list_base_models=[DataFrameTool], + output_type=str, + metadata_output_type="json", + function_calling_format_type="OpenAI", + function_calling_type="json", + tools=[process_data_frame], + list_base_models_json=create_tool_schema(), +) -The `Task` class is defined as follows: +# Example task: Process a data frame +data = [ + {"col1": 1, "col2": 2}, + {"col1": 3, "col2": 4}, + {"col1": 5, "col2": 6} +] +result = agent.run("Process this data frame: " + str(data)) +print(f"Data Frame Summary: {result}") +``` +## Conclusion -### Attributes +The Swarms Tool System provides a robust and flexible framework for defining and utilizing tools within agents. By leveraging Pydantic BaseModels, functions, and dictionaries, developers can create highly customized tools to perform a wide range of tasks. The extensive customization options allow for the integration of external libraries and the extension of core components, making the Swarms framework suitable for diverse applications. -| Attribute | Type | Description | -|----------------|-----------------------------|---------------------------------------------------------------------------------------| -| `agent` | `Union[Callable, Agent]` | The agent or callable object to run the task. | -| `description` | `str` | Description of the task. | -| `result` | `Any` | Result of the task. | -| `history` | `List[Any]` | History of the task. | -| `schedule_time`| `datetime` | Time to schedule the task. | -| `scheduler` | `sched.scheduler` | Scheduler to schedule the task. | -| `trigger` | `Callable` | Trigger to run the task. | -| `action` | `Callable` | Action to run the task. | -| `condition` | `Callable` | Condition to run the task. | -| `priority` | `int` | Priority of the task. | -| `dependencies` | `List[Task]` | List of tasks that need to be completed before this task can be executed. | -| `args` | `List[Any]` | Arguments to pass to the agent or callable object. | -| `kwargs` | `Dict[str, Any]` | Keyword arguments to pass to the agent or callable object. | +This guide has covered the fundamental concepts and provided detailed examples to help you get started with the Swarms Tool System. With this foundation, you can explore and implement advanced features to build powerful -## Methods +-------------------------------------------------- -### `execute(self, *args, **kwargs)` +# File: swarms\tools\mcp_client_call.md -Executes the task by calling the agent or model with the specified arguments and keyword arguments. If a condition is set, the task will only execute if the condition returns `True`. +# MCP Client Call Reference Documentation -#### Parameters -- `args`: Arguments to pass to the agent or callable object. -- `kwargs`: Keyword arguments to pass to the agent or callable object. +This document provides a comprehensive reference for the MCP (Model Control Protocol) client call functions, including detailed parameter descriptions, return types, and usage examples. -#### Examples +## Table of Contents -```python ->>> from swarms.structs import Task, Agent ->>> from swarm_models import OpenAIChat ->>> agent = Agent(llm=OpenAIChat(openai_api_key=""), max_loops=1, dashboard=False) ->>> task = Task(description="What's the weather in Miami?", agent=agent) ->>> task.run() ->>> task.result -``` +- [aget_mcp_tools](#aget_mcp_tools) -### `handle_scheduled_task(self)` +- [get_mcp_tools_sync](#get_mcp_tools_sync) -Handles the execution of a scheduled task. If the schedule time is not set or has already passed, the task is executed immediately. Otherwise, the task is scheduled to be executed at the specified schedule time. +- [get_tools_for_multiple_mcp_servers](#get_tools_for_multiple_mcp_servers) -#### Examples +- [execute_tool_call_simple](#execute_tool_call_simple) -```python ->>> task.schedule_time = datetime.now() + timedelta(seconds=10) ->>> task.handle_scheduled_task() -``` +## Function Reference -### `set_trigger(self, trigger: Callable)` +### aget_mcp_tools -Sets the trigger for the task. +Asynchronously fetches available MCP tools from the server with retry logic. #### Parameters -- `trigger` (`Callable`): The trigger to set. -#### Examples +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| server_path | Optional[str] | No | Path to the MCP server script | +| format | str | No | Format of the returned tools (default: "openai") | +| connection | Optional[MCPConnection] | No | MCP connection object | +| *args | Any | No | Additional positional arguments | +| **kwargs | Any | No | Additional keyword arguments | -```python ->>> def my_trigger(): ->>> print("Trigger executed") ->>> task.set_trigger(my_trigger) -``` +#### Returns -### `set_action(self, action: Callable)` +- `List[Dict[str, Any]]`: List of available MCP tools in OpenAI format -Sets the action for the task. +#### Raises -#### Parameters -- `action` (`Callable`): The action to set. +- `MCPValidationError`: If server_path is invalid -#### Examples +- `MCPConnectionError`: If connection to server fails + +#### Example ```python ->>> def my_action(): ->>> print("Action executed") ->>> task.set_action(my_action) +import asyncio +from swarms.tools.mcp_client_call import aget_mcp_tools +from swarms.tools.mcp_connection import MCPConnection + +async def main(): + # Using server path + tools = await aget_mcp_tools(server_path="http://localhost:8000") + + # Using connection object + connection = MCPConnection( + host="localhost", + port=8000, + headers={"Authorization": "Bearer token"} + ) + tools = await aget_mcp_tools(connection=connection) + + print(f"Found {len(tools)} tools") + +if __name__ == "__main__": + asyncio.run(main()) ``` -### `set_condition(self, condition: Callable)` +### get_mcp_tools_sync -Sets the condition for the task. +Synchronous version of get_mcp_tools that handles event loop management. #### Parameters -- `condition` (`Callable`): The condition to set. -#### Examples +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| server_path | Optional[str] | No | Path to the MCP server script | +| format | str | No | Format of the returned tools (default: "openai") | +| connection | Optional[MCPConnection] | No | MCP connection object | +| *args | Any | No | Additional positional arguments | +| **kwargs | Any | No | Additional keyword arguments | -```python ->>> def my_condition(): ->>> print("Condition checked") ->>> return True ->>> task.set_condition(my_condition) -``` +#### Returns -### `is_completed(self)` +- `List[Dict[str, Any]]`: List of available MCP tools in OpenAI format -Checks whether the task has been completed. +#### Raises -#### Returns -- `bool`: `True` if the task has been completed, `False` otherwise. +- `MCPValidationError`: If server_path is invalid -#### Examples +- `MCPConnectionError`: If connection to server fails -```python ->>> task.is_completed() -``` +- `MCPExecutionError`: If event loop management fails -### `add_dependency(self, task)` +#### Example -Adds a task to the list of dependencies. +```python +from swarms.tools.mcp_client_call import get_mcp_tools_sync +from swarms.tools.mcp_connection import MCPConnection -#### Parameters -- `task` (`Task`): The task to add as a dependency. +# Using server path +tools = get_mcp_tools_sync(server_path="http://localhost:8000") -#### Examples +# Using connection object +connection = MCPConnection( + host="localhost", + port=8000, + headers={"Authorization": "Bearer token"} +) +tools = get_mcp_tools_sync(connection=connection) -```python ->>> dependent_task = Task(description="Dependent Task") ->>> task.add_dependency(dependent_task) +print(f"Found {len(tools)} tools") ``` -### `set_priority(self, priority: int)` +### get_tools_for_multiple_mcp_servers -Sets the priority of the task. +Get tools for multiple MCP servers concurrently using ThreadPoolExecutor. #### Parameters -- `priority` (`int`): The priority to set. -#### Examples +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| urls | List[str] | Yes | List of server URLs to fetch tools from | +| connections | List[MCPConnection] | No | Optional list of MCPConnection objects | +| format | str | No | Format to return tools in (default: "openai") | +| output_type | Literal["json", "dict", "str"] | No | Type of output format (default: "str") | +| max_workers | Optional[int] | No | Maximum number of worker threads | -```python ->>> task.set_priority(5) -``` +#### Returns -### `check_dependency_completion(self)` +- `List[Dict[str, Any]]`: Combined list of tools from all servers -Checks whether all the dependencies have been completed. +#### Raises -#### Returns -- `bool`: `True` if all the dependencies have been completed, `False` otherwise. +- `MCPExecutionError`: If fetching tools from any server fails -#### Examples +#### Example ```python ->>> task.check_dependency_completion() +from swarms.tools.mcp_client_call import get_tools_for_multiple_mcp_servers +from swarms.tools.mcp_connection import MCPConnection + +# Define server URLs +urls = [ + "http://server1:8000", + "http://server2:8000" +] + +# Optional: Define connections +connections = [ + MCPConnection(host="server1", port=8000), + MCPConnection(host="server2", port=8000) +] + +# Get tools from all servers +tools = get_tools_for_multiple_mcp_servers( + urls=urls, + connections=connections, + format="openai", + output_type="dict", + max_workers=4 +) + +print(f"Found {len(tools)} tools across all servers") ``` -### `context(self, task: "Task" = None, context: List["Task"] = None, *args, **kwargs)` +### execute_tool_call_simple -Sets the context for the task. For a sequential workflow, it sequentially adds the context of the previous task in the list. +Execute a tool call using the MCP client. #### Parameters -- `task` (`Task`, optional): The task whose context is to be set. -- `context` (`List[Task]`, optional): The list of tasks to set the context. -#### Examples +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| response | Any | No | Tool call response object | +| server_path | str | No | Path to the MCP server | +| connection | Optional[MCPConnection] | No | MCP connection object | +| output_type | Literal["json", "dict", "str", "formatted"] | No | Type of output format (default: "str") | +| *args | Any | No | Additional positional arguments | +| **kwargs | Any | No | Additional keyword arguments | -```python ->>> task1 = Task(description="Task 1") ->>> task2 = Task(description="Task 2") ->>> task2.context(context=[task1]) -``` +#### Returns -## Usage Examples +- `List[Dict[str, Any]]`: Result of the tool execution -### Basic Usage +#### Raises + +- `MCPConnectionError`: If connection to server fails +- `MCPExecutionError`: If tool execution fails + +#### Example ```python -import os -from dotenv import load_dotenv -from swarms import Agent, OpenAIChat, Task +import asyncio +from swarms.tools.mcp_client_call import execute_tool_call_simple +from swarms.tools.mcp_connection import MCPConnection -# Load the environment variables -load_dotenv() +async def main(): + # Example tool call response + response = { + "name": "example_tool", + "parameters": {"param1": "value1"} + } + + # Using server path + result = await execute_tool_call_simple( + response=response, + server_path="http://localhost:8000", + output_type="json" + ) + + # Using connection object + connection = MCPConnection( + host="localhost", + port=8000, + headers={"Authorization": "Bearer token"} + ) + result = await execute_tool_call_simple( + response=response, + connection=connection, + output_type="dict" + ) + + print(f"Tool execution result: {result}") -# Define a function to be used as the action -def my_action(): - print("Action executed") +if __name__ == "__main__": + asyncio.run(main()) +``` -# Define a function to be used as the condition -def my_condition(): - print("Condition checked") - return True +## Error Handling -# Create an agent -agent = Agent( - llm=OpenAIChat(openai_api_key=os.environ["OPENAI_API_KEY"]), - max_loops=1, - dashboard=False, -) +The MCP client functions use a retry mechanism with exponential backoff for failed requests. The following error types may be raised: -# Create a task -task = Task( - description="Generate a report on the top 3 biggest expenses for small businesses and how businesses can save 20%", - agent=agent, -) +- `MCPValidationError`: Raised when input validation fails -# Set the action and condition -task.set_action(my_action) -task.set_condition(my_condition) +- `MCPConnectionError`: Raised when connection to the MCP server fails -# Execute the task -print("Executing task...") -task.run() +- `MCPExecutionError`: Raised when tool execution fails -# Check if the task is completed -if task.is_completed(): - print("Task completed") -else: - print("Task not completed") +## Best Practices -# Output the result of the task -print(f"Task result: {task.result}") -``` +1. Always handle potential exceptions when using these functions +2. Use connection objects for authenticated requests +3. Consider using the async versions for better performance in async applications +4. Use appropriate output types based on your needs +5. When working with multiple servers, adjust max_workers based on your system's capabilities -### Scheduled Task Execution -```python -from datetime import datetime, timedelta -import os -from dotenv import load_dotenv -from swarms import Agent, OpenAIChat, Task -# Load the environment variables -load_dotenv() +-------------------------------------------------- -# Create an agent -agent = Agent( - llm=OpenAIChat(openai_api_key=os.environ["OPENAI_API_KEY"]), - max_loops=1, - dashboard=False, -) +# File: swarms\tools\tool_storage.md -# Create a task -task = Task( - description="Scheduled task example", - agent=agent, - schedule_time=datetime.now() + timedelta(seconds=10) -) +# ToolStorage -# Handle scheduled task -task.handle_scheduled_task() -``` -### Task with Dependencies +The `ToolStorage` module provides a structured and efficient way to manage and utilize various tool functions. It is designed to store tool functions, manage settings, and ensure smooth registration and retrieval of tools. This module is particularly useful in applications that require dynamic management of a collection of functions, such as plugin systems, modular software, or any application where functions need to be registered and called dynamically. -```python -import os -from dotenv import load_dotenv -from swarms import Agent, OpenAIChat, Task +## Class: ToolStorage -# Load the environment variables -load_dotenv() +The `ToolStorage` class is the core component of the module. It provides functionalities to add, retrieve, and list tool functions as well as manage settings. -# Create agents -agent1 = Agent( - llm=OpenAIChat(openai_api_key=os.environ["OPENAI_API_KEY"]), - max_loops=1, - dashboard=False, -) -agent2 = Agent( - llm=OpenAIChat(openai_api_key=os.environ["OPENAI_API_KEY"]), - max_loops=1, - dashboard=False, -) +### Attributes -# Create tasks -task1 = Task(description="First task", agent=agent1) -task2 = Task(description="Second task", agent=agent2) +| Attribute | Type | Description | +|------------|--------------------|-----------------------------------------------------------------------| +| `verbose` | `bool` | A flag to enable verbose logging. | +| `tools` | `List[Callable]` | A list of tool functions. | +| `_tools` | `Dict[str, Callable]` | A dictionary that stores the tools, where the key is the tool name and the value is the tool function. | +| `_settings`| `Dict[str, Any]` | A dictionary that stores the settings, where the key is the setting name and the value is the setting value. | -# Add dependency -task2.add_dependency(task1) +### Methods -# Execute tasks -print("Executing first task...") -task1.run() +#### `__init__` -print("Executing second task...") -task2.run() +Initializes the `ToolStorage` instance. -# Check if tasks are completed -print(f"Task 1 completed: {task1.is_completed()}") -print(f"Task 2 completed: {task2.is_completed()}") -``` -### Task Context +| Parameter | Type | Default | Description | +|------------|-------------------|---------|------------------------------------------------------------| +| `verbose` | `bool` | `None` | A flag to enable verbose logging. | +| `tools` | `List[Callable]` | `None` | A list of tool functions to initialize the storage with. | +| `*args` | `tuple` | `None` | Additional positional arguments. | +| `**kwargs` | `dict` | `None` | Additional keyword arguments. | -```python -import os -from dotenv import load_dotenv -from swarms import Agent, OpenAIChat, Task +#### `add_tool` -# Load the environment variables -load_dotenv() +Adds a tool to the storage. -# Create an agent -agent = Agent( - llm=OpenAIChat(openai_api_key=os.environ["OPENAI_API_KEY"]), - max_loops +| Parameter | Type | Description | +|-----------|----------|------------------------------| +| `func` | `Callable` | The tool function to be added. | -=1, - dashboard=False, -) +**Raises:** +- `ValueError`: If a tool with the same name already exists. -# Create tasks -task1 = Task(description="First task", agent=agent) -task2 = Task(description="Second task", agent=agent) +#### `get_tool` -# Set context for the second task -task2.context(context=[task1]) +Retrieves a tool by its name. -# Execute tasks -print("Executing first task...") -task1.run() +| Parameter | Type | Description | +|-----------|--------|-------------------------------| +| `name` | `str` | The name of the tool to retrieve. | -print("Executing second task...") -task2.run() +**Returns:** +- `Callable`: The tool function. -# Output the context of the second task -print(f"Task 2 context: {task2.history}") -``` +**Raises:** +- `ValueError`: If no tool with the given name is found. +#### `set_setting` --------------------------------------------------- +Sets a setting in the storage. -# File: swarms/structs/taskqueue_swarm.md -# TaskQueueSwarm Documentation +| Parameter | Type | Description | +|-----------|--------|--------------------------| +| `key` | `str` | The key for the setting. | +| `value` | `Any` | The value for the setting. | -The `TaskQueueSwarm` class is designed to manage and execute tasks using multiple agents concurrently. This class allows for the orchestration of multiple agents processing tasks from a shared queue, facilitating complex workflows where tasks can be distributed and processed in parallel by different agents. +#### `get_setting` -## Attributes +Gets a setting from the storage. -| Attribute | Type | Description | -|-----------|------|-------------| -| `agents` | `List[Agent]` | The list of agents in the swarm. | -| `task_queue` | `queue.Queue` | A queue to store tasks for processing. | -| `lock` | `threading.Lock` | A lock for thread synchronization. | -| `autosave_on` | `bool` | Whether to automatically save the swarm metadata. | -| `save_file_path` | `str` | The file path for saving swarm metadata. | -| `workspace_dir` | `str` | The directory path of the workspace. | -| `return_metadata_on` | `bool` | Whether to return the swarm metadata after running. | -| `max_loops` | `int` | The maximum number of loops to run the swarm. | -| `metadata` | `SwarmRunMetadata` | Metadata about the swarm run. | +| Parameter | Type | Description | +|-----------|--------|--------------------------| +| `key` | `str` | The key for the setting. | -## Methods +**Returns:** +- `Any`: The value of the setting. -### `__init__(self, agents: List[Agent], name: str = "Task-Queue-Swarm", description: str = "A swarm that processes tasks from a queue using multiple agents on different threads.", autosave_on: bool = True, save_file_path: str = "swarm_run_metadata.json", workspace_dir: str = os.getenv("WORKSPACE_DIR"), return_metadata_on: bool = False, max_loops: int = 1, *args, **kwargs)` +**Raises:** +- `KeyError`: If the setting is not found. -The constructor initializes the `TaskQueueSwarm` object. +#### `list_tools` -- **Parameters:** - - `agents` (`List[Agent]`): The list of agents in the swarm. - - `name` (`str`, optional): The name of the swarm. Defaults to "Task-Queue-Swarm". - - `description` (`str`, optional): The description of the swarm. Defaults to "A swarm that processes tasks from a queue using multiple agents on different threads.". - - `autosave_on` (`bool`, optional): Whether to automatically save the swarm metadata. Defaults to True. - - `save_file_path` (`str`, optional): The file path to save the swarm metadata. Defaults to "swarm_run_metadata.json". - - `workspace_dir` (`str`, optional): The directory path of the workspace. Defaults to os.getenv("WORKSPACE_DIR"). - - `return_metadata_on` (`bool`, optional): Whether to return the swarm metadata after running. Defaults to False. - - `max_loops` (`int`, optional): The maximum number of loops to run the swarm. Defaults to 1. - - `*args`: Variable length argument list. - - `**kwargs`: Arbitrary keyword arguments. +Lists all registered tools. -### `add_task(self, task: str)` +**Returns:** +- `List[str]`: A list of tool names. -Adds a task to the queue. +## Decorator: tool_registry -- **Parameters:** - - `task` (`str`): The task to be added to the queue. +The `tool_registry` decorator registers a function as a tool in the storage. -### `run(self)` +| Parameter | Type | Description | +|-----------|----------------|----------------------------------| +| `storage` | `ToolStorage` | The storage instance to register the tool in. | -Runs the swarm by having agents pick up tasks from the queue. +**Returns:** +- `Callable`: The decorator function. -- **Returns:** - - `str`: JSON string of the swarm run metadata if `return_metadata_on` is True. +## Usage Examples -- **Usage Example:** - ```python - from swarms import Agent, TaskQueueSwarm - from swarms_models import OpenAIChat - # Initialize the language model - llm = OpenAIChat() +### Full Example +```python +from swarms import ToolStorage, tool_registry - # Initialize agents - agent1 = Agent(agent_name="Agent1", llm=llm) - agent2 = Agent(agent_name="Agent2", llm=llm) +storage = ToolStorage() - # Create the TaskQueueSwarm - swarm = TaskQueueSwarm(agents=[agent1, agent2], max_loops=5) - # Add tasks to the swarm - swarm.add_task("Analyze the latest market trends") - swarm.add_task("Generate a summary report") +# Example usage +@tool_registry(storage) +def example_tool(x: int, y: int) -> int: + """ + Example tool function that adds two numbers. - # Run the swarm - result = swarm.run() - print(result) # Prints the swarm run metadata - ``` + Args: + x (int): The first number. + y (int): The second number. - This example initializes a `TaskQueueSwarm` with two agents, adds tasks to the queue, and runs the swarm. + Returns: + int: The sum of the two numbers. + """ + return x + y -### `save_json_to_file(self)` -Saves the swarm run metadata to a JSON file. +# Query all the tools and get the example tool +print(storage.list_tools()) # Should print ['example_tool'] +# print(storage.get_tool('example_tool')) # Should print -### `export_metadata(self)` +# Find the tool by names and call it +print(storage.get_tool("example_tool")) # Should print 5 -Exports the swarm run metadata as a JSON string. -- **Returns:** - - `str`: JSON string of the swarm run metadata. +# Test the storage and querying +if __name__ == "__main__": + print(storage.list_tools()) # Should print ['example_tool'] + print(storage.get_tool("example_tool")) # Should print 5 + storage.set_setting("example_setting", 42) + print(storage.get_setting("example_setting")) # Should print 42 -## Additional Notes +``` -- The `TaskQueueSwarm` uses threading to process tasks concurrently, which can significantly improve performance for I/O-bound tasks. -- The `reliability_checks` method ensures that the swarm is properly configured before running. -- The swarm automatically handles task distribution among agents and provides detailed metadata about the run. -- Error handling and logging are implemented to track the execution flow and capture any issues during task processing. +### Basic Usage --------------------------------------------------- +#### Example 1: Initializing ToolStorage and Adding a Tool -# File: swarms/structs/various_execution_methods.md +```python +from swarms.tools.tool_registry import ToolStorage, tool_registry -# Concurrent Agents API Reference +# Initialize ToolStorage +storage = ToolStorage() -This documentation covers the API for running multiple agents concurrently using various execution strategies. The implementation uses `asyncio` with `uvloop` for enhanced performance and `ThreadPoolExecutor` for handling CPU-bound operations. +# Define a tool function +@tool_registry(storage) +def add_numbers(x: int, y: int) -> int: + return x + y -## Table of Contents -- [Core Functions](#core-functions) -- [Advanced Functions](#advanced-functions) -- [Utility Functions](#utility-functions) -- [Resource Monitoring](#resource-monitoring) -- [Usage Examples](#usage-examples) +# List tools +print(storage.list_tools()) # Output: ['add_numbers'] -## Core Functions +# Retrieve and use the tool +add_tool = storage.get_tool('add_numbers') +print(add_tool(5, 3)) # Output: 8 +``` -### run_agents_concurrently() +### Advanced Usage -Primary function for running multiple agents concurrently with optimized performance using both uvloop and ThreadPoolExecutor. +#### Example 2: Managing Settings -#### Arguments +```python +# Set a setting +storage.set_setting('max_retries', 5) -| Parameter | Type | Required | Default | Description | -|-------------|----------------|----------|----------------|-------------| -| agents | List[AgentType]| Yes | - | List of Agent instances to run concurrently | -| task | str | Yes | - | Task string to execute | -| batch_size | int | No | CPU count | Number of agents to run in parallel in each batch | -| max_workers | int | No | CPU count * 2 | Maximum number of threads in the executor | +# Get a setting +max_retries = storage.get_setting('max_retries') +print(max_retries) # Output: 5 +``` -#### Returns -`List[Any]`: List of outputs from each agent +### Error Handling -#### Flow Diagram +#### Example 3: Handling Errors in Tool Retrieval -```mermaid -graph TD - A[Start] --> B[Initialize ThreadPoolExecutor] - B --> C[Split Agents into Batches] - C --> D[Process Batch] - D --> E{More Batches?} - E -->|Yes| D - E -->|No| F[Combine Results] - F --> G[Return Results] - - subgraph "Batch Processing" - D --> H[Run Agents Async] - H --> I[Wait for Completion] - I --> J[Collect Batch Results] - end +```python +try: + non_existent_tool = storage.get_tool('non_existent') +except ValueError as e: + print(e) # Output: No tool found with name: non_existent +``` + +#### Example 4: Handling Duplicate Tool Addition + +```python +try: + @tool_registry(storage) + def add_numbers(x: int, y: int) -> int: + return x + y +except ValueError as e: + print(e) # Output: Tool with name add_numbers already exists. ``` -### run_agents_sequentially() +## Conclusion -Runs multiple agents sequentially for baseline comparison or simple use cases. +The `ToolStorage` module provides a robust solution for managing tool functions and settings. Its design allows for easy registration, retrieval, and management of tools, making it a valuable asset in various applications requiring dynamic function handling. The inclusion of detailed logging ensures that the operations are transparent and any issues can be quickly identified and resolved. -#### Arguments +-------------------------------------------------- -| Parameter | Type | Required | Default | Description | -|-----------|----------------|----------|---------|-------------| -| agents | List[AgentType]| Yes | - | List of Agent instances to run | -| task | str | Yes | - | Task string to execute | +# File: swarms\tools\tools_examples.md -#### Returns -`List[Any]`: List of outputs from each agent +# Swarms Tools Documentation -## Advanced Functions +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. -### run_agents_with_different_tasks() +## Installation -Runs multiple agents with different tasks concurrently. +```bash +pip install swarms +``` -#### Arguments +## Overview -| Parameter | Type | Required | Default | Description | -|-----------------|-------------------------------|----------|----------------|-------------| -| agent_task_pairs| List[tuple[AgentType, str]] | Yes | - | List of (agent, task) tuples | -| batch_size | int | No | CPU count | Number of agents to run in parallel | -| max_workers | int | No | CPU count * 2 | Maximum number of threads | +Swarms provides a comprehensive suite of tool integration methods to enhance your AI agents' capabilities: -### run_agents_with_timeout() +| 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 | -Runs multiple agents concurrently with timeout limits. +--- -#### Arguments +## Method 1: Callable Functions -| Parameter | Type | Required | Default | Description | -|-------------|----------------|----------|----------------|-------------| -| agents | List[AgentType]| Yes | - | List of Agent instances | -| task | str | Yes | - | Task string to execute | -| timeout | float | Yes | - | Timeout in seconds for each agent | -| batch_size | int | No | CPU count | Number of agents to run in parallel | -| max_workers | int | No | CPU count * 2 | Maximum number of threads | +Callable functions are the simplest way to add tools to your Swarms agents. They are regular Python functions with type hints and comprehensive docstrings. -## Usage Examples +### Step 1: Define Your Tool Functions -```python -from swarms import Agent, run_agents_concurrently, run_agents_with_timeout, run_agents_with_different_tasks -from swarm_models import OpenAIChat +Create functions with the following requirements: -model = OpenAIChat( - model_name="gpt-4o-mini", - temperature=0.0 -) +- **Type hints** for all parameters and return values -# Initialize agents -agents = [ - Agent( - agent_name=f"Analysis-Agent-{i}", - system_prompt="You are a financial analysis expert", - llm=model, - max_loops=1 - ) - for i in range(5) -] +- **Comprehensive docstrings** with Args, Returns, Raises, and Examples sections -# Basic concurrent execution -task = "Analyze the impact of rising interest rates on tech stocks" -outputs = run_agents_concurrently(agents, task) +- **Error handling** for robust operation -# Running with timeout -outputs_with_timeout = run_agents_with_timeout( - agents=agents, - task=task, - timeout=30.0, - batch_size=2 -) +#### Example: Cryptocurrency Price Tools -# Running different tasks -task_pairs = [ - (agents[0], "Analyze tech stocks"), - (agents[1], "Analyze energy stocks"), - (agents[2], "Analyze retail stocks") -] -different_outputs = run_agents_with_different_tasks(task_pairs) -``` +```python +import json +import requests +from swarms import Agent -## Resource Monitoring -### ResourceMetrics +def get_coin_price(coin_id: str, vs_currency: str = "usd") -> str: + """ + Get the current price of a specific cryptocurrency. -A dataclass for system resource metrics. + 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". -#### Properties + Returns: + str: JSON formatted string containing the coin's current price and market data + including market cap, 24h volume, and price changes -| Property | Type | Description | -|----------------|-------|-------------| -| cpu_percent | float | Current CPU usage percentage | -| memory_percent | float | Current memory usage percentage | -| active_threads | int | Number of active threads | + 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, + } -### run_agents_with_resource_monitoring() + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() -Runs agents with system resource monitoring and adaptive batch sizing. + 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) -#### Arguments + 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)}"}) -| Parameter | Type | Required | Default | Description | -|------------------|----------------|----------|---------|-------------| -| agents | List[AgentType]| Yes | - | List of Agent instances | -| task | str | Yes | - | Task string to execute | -| cpu_threshold | float | No | 90.0 | Max CPU usage percentage | -| memory_threshold | float | No | 90.0 | Max memory usage percentage | -| check_interval | float | No | 1.0 | Resource check interval in seconds | -## Performance Considerations +def get_top_cryptocurrencies(limit: int = 10, vs_currency: str = "usd") -> str: + """ + Fetch the top cryptocurrencies by market capitalization. -- Default batch sizes and worker counts are optimized based on CPU cores -- Resource monitoring helps prevent system overload -- Using `uvloop` provides better performance than standard `asyncio` + 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". -## Error Handling + 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 -- Functions handle asyncio event loop creation/retrieval -- Timeout mechanism prevents infinite waiting -- Resource monitoring allows for adaptive performance adjustment + 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", + } -# File: swarms/structs/various_swarm_architectures.md + 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)}"}) --------------------------------------------------- -# File: swarms/structs/yaml_model.md +def search_cryptocurrencies(query: str) -> str: + """ + Search for cryptocurrencies by name or symbol. -# YamlModel: A Pydantic Model for YAML Data + Args: + query (str): The search term (coin name or symbol) + Examples: 'bitcoin', 'btc', 'ethereum', 'eth' + Case-insensitive search -The `YamlModel` class, derived from `BaseModel` in Pydantic, offers a convenient way to work with YAML data in your Python applications. It provides methods for serialization (converting to YAML), deserialization (creating an instance from YAML), and schema generation. This documentation will delve into the functionalities of `YamlModel` and guide you through its usage with illustrative examples. + 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 -### Purpose and Functionality + Raises: + requests.RequestException: If the API request fails + ValueError: If query is empty -The primary purpose of `YamlModel` is to streamline the interaction between your Python code and YAML data. It accomplishes this by: + 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()} -* **Serialization:** Transforming a `YamlModel` instance into a YAML string representation using the `to_yaml()` method. -* **Deserialization:** Constructing a `YamlModel` instance from a provided YAML string using the `from_yaml()` class method. -* **JSON to YAML Conversion:** Facilitating the conversion of JSON data to YAML format through the `json_to_yaml()` static method. -* **Saving to YAML File:** Enabling the storage of `YamlModel` instances as YAML files using the `save_to_yaml()` method. -* (Future Implementation) **Schema Generation:** The `create_yaml_schema()` class method (not yet implemented but included for future reference) will generate a YAML schema that reflects the structure of the `YamlModel` class and its fields. + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() -### Class Definition and Arguments + data = response.json() -The `YamlModel` class inherits from Pydantic's `BaseModel` class. You can define your custom YAML models by creating subclasses of `YamlModel` and specifying your data fields within the class definition. Here's the breakdown of the `YamlModel` class and its methods: + # 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) + } -```python -class YamlModel(BaseModel): - """ - A Pydantic model class for working with YAML data. - """ + return json.dumps(result, indent=2) - def to_yaml(self): - """ - Serialize the Pydantic model instance to a YAML string. - """ - return yaml.safe_dump(self.dict(), sort_keys=False) + 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)}"}) +``` - @classmethod - def from_yaml(cls, yaml_str: str): - """ - Create an instance of the class from a YAML string. +### Step 2: Configure Your Agent - Args: - yaml_str (str): The YAML string to parse. +Create an agent with the following key parameters: - Returns: - cls: An instance of the class with attributes populated from the YAML data. - Returns None if there was an error loading the YAML data. - """ - # ... +```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, + ], +) +``` - @staticmethod - def json_to_yaml(json_str: str): - """ - Convert a JSON string to a YAML string. - """ - # ... +### Step 3: Use Your Agent - def save_to_yaml(self, filename: str): - """ - Save the Pydantic model instance as a YAML file. - """ - # ... +```python +# Example usage with different queries +response = agent.run("What are the top 5 cryptocurrencies by market cap?") +print(response) - # TODO: Implement a method to create a YAML schema from the model fields - # @classmethod - # def create_yaml_schema(cls): - # # ... - """ +# 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) ``` -**Arguments:** +--- -* `self` (implicit): Refers to the current instance of the `YamlModel` class. -* `yaml_str` (str): The YAML string used for deserialization in the `from_yaml()` method. -* `json_str` (str): The JSON string used for conversion to YAML in the `json_to_yaml()` method. -* `filename` (str): The filename (including path) for saving the YAML model instance in the `save_to_yaml()` method. +## Method 2: MCP (Model Context Protocol) Servers -### Detailed Method Descriptions +MCP servers provide a standardized way to create distributed tool functionality. They're ideal for: -**1. to_yaml()** +- **Reusable tools** across multiple agents -This method transforms an instance of the `YamlModel` class into a YAML string representation. It utilizes the `yaml.safe_dump()` function from the `PyYAML` library to ensure secure YAML data generation. The `sort_keys=False` argument guarantees that the order of keys in the resulting YAML string remains consistent with the order of fields defined in your `YamlModel` subclass. +- **Complex tool logic** that needs isolation -**Example:** +- **Third-party tool integration** -```python -class User(YamlModel): - name: str - age: int - is_active: bool +- **Scalable architectures** -user = User(name="Bob", age=30, is_active=True) -yaml_string = user.to_yaml() -print(yaml_string) -``` +### Step 1: Create Your MCP Server -This code will output a YAML string representation of the `user` object, resembling: +```python +from mcp.server.fastmcp import FastMCP +import requests -```yaml -name: Bob -age: 30 -is_active: true +# Initialize the MCP server with configuration +mcp = FastMCP("OKXCryptoPrice") # Server name for identification +mcp.settings.port = 8001 # Port for server communication ``` -### Detailed Method Descriptions +### Step 2: Define MCP Tools -**2. from_yaml(cls, yaml_str)** (Class Method) +Each MCP tool requires the `@mcp.tool` decorator with specific parameters: -The `from_yaml()` class method is responsible for constructing a `YamlModel` instance from a provided YAML string. +```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. -* **Arguments:** - * `cls` (class): The class representing the desired YAML model (the subclass of `YamlModel` that matches the structure of the YAML data). - * `yaml_str` (str): The YAML string containing the data to be parsed and used for creating the model instance. + 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:** - * `cls` (instance): An instance of the specified class (`cls`) populated with the data extracted from the YAML string. If an error occurs during parsing, it returns `None`. + Returns: + str: A formatted string containing: + - Current price in USDT + - 24-hour price change percentage + - Formatted for human readability -* **Error Handling:** + Raises: + requests.RequestException: If the OKX API request fails + ValueError: If symbol format is invalid + ConnectionError: If unable to connect to OKX servers -The `from_yaml()` method employs `yaml.safe_load()` for secure YAML parsing. It incorporates a `try-except` block to handle potential `ValueError` exceptions that might arise during the parsing process. If an error is encountered, it logs the error message and returns `None`. + 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')" -**Example:** + # Normalize symbol format + symbol = symbol.upper().strip() + if not symbol.endswith("-USDT"): + symbol = f"{symbol}-USDT" -```python -class User(YamlModel): - name: str - age: int - is_active: bool + # OKX API endpoint for ticker information + url = f"https://www.okx.com/api/v5/market/ticker?instId={symbol}" -yaml_string = """ -name: Alice -age: 25 -is_active: false -""" + # Make the API request with timeout + response = requests.get(url, timeout=10) + response.raise_for_status() -user = User.from_yaml(yaml_string) -print(user.name) # Output: Alice -``` + data = response.json() -**3. json_to_yaml(json_str)** (Static Method) + # Check API response status + if data.get("code") != "0": + return f"Error: {data.get('msg', 'Unknown error from OKX API')}" -This static method in the `YamlModel` class serves the purpose of converting a JSON string into a YAML string representation. + # 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." -* **Arguments:** - * `json_str` (str): The JSON string that needs to be converted to YAML format. + # Parse numerical data + price = float(ticker_data.get("last", 0)) + change_percent = float(ticker_data.get("change24h", 0)) * 100 # Convert to percentage -* **Returns:** - * `str`: The converted YAML string representation of the provided JSON data. + # 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}%") -* **Functionality:** + 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)}" -The `json_to_yaml()` method leverages the `json.loads()` function to parse the JSON string into a Python dictionary. Subsequently, it utilizes `yaml.dump()` to generate the corresponding YAML string representation from the parsed dictionary. -**Example:** +@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. -```python -json_string = '{"name": "Charlie", "age": 42, "is_active": true}' -yaml_string = YamlModel.json_to_yaml(json_string) -print(yaml_string) -``` + 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 -This code snippet will convert the JSON data to a YAML string, likely resembling: + Returns: + str: A formatted string containing: + - 24-hour trading volume in the base currency + - Volume formatted with thousand separators + - Currency symbol for clarity -```yaml -name: Charlie -age: 42 -is_active: true -``` + Raises: + requests.RequestException: If the OKX API request fails + ValueError: If symbol format is invalid -**4. save_to_yaml(self, filename)** + 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')" -The `save_to_yaml()` method facilitates the storage of a `YamlModel` instance as a YAML file. + # Normalize symbol format + symbol = symbol.upper().strip() + if not symbol.endswith("-USDT"): + symbol = f"{symbol}-USDT" -* **Arguments:** - * `self` (implicit): Refers to the current instance of the `YamlModel` class that you intend to save. - * `filename` (str): The desired filename (including path) for the YAML file. + # OKX API endpoint + url = f"https://www.okx.com/api/v5/market/ticker?instId={symbol}" -* **Functionality:** + # Make API request + response = requests.get(url, timeout=10) + response.raise_for_status() -The `save_to_yaml()` method employs the previously explained `to_yaml()` method to generate a YAML string representation of the `self` instance. It then opens the specified file in write mode (`"w"`) and writes the YAML string content to the file. + data = response.json() -**Example:** + # Validate API response + if data.get("code") != "0": + return f"Error: {data.get('msg', 'Unknown error from OKX API')}" -```python -class Employee(YamlModel): - name: str - department: str - salary: float + ticker_data = data.get("data", [{}])[0] + if not ticker_data: + return f"Error: Could not find data for {symbol}. Please verify the trading pair." -employee = Employee(name="David", department="Engineering", salary=95000.00) -employee.save_to_yaml("employee.yaml") + # 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)}" ``` -This code will create a YAML file named "employee.yaml" containing the serialized representation of the `employee` object. +### 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") +``` -### More Usage Examples ++ +### Step 4: Connect Agent to MCP Server ```python -class User(YamlModel): - name: str - age: int - is_active: bool +from swarms import Agent -# Create an instance of the User model -user = User(name="Alice", age=30, is_active=True) +# Method 2: Using direct URL (simpler for development) +mcp_url = "http://0.0.0.0:8001/sse" -# Serialize the User instance to YAML and print it -yaml_string = user.to_yaml() -print(yaml_string) +# 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 +) ``` -This code snippet demonstrates the creation of a `User` instance and its subsequent serialization to a YAML string using the `to_yaml()` method. The printed output will likely resemble: +### Step 5: Use Your MCP-Enabled Agent -```yaml -name: Alice -age: 30 -is_active: true +```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) ``` -### Converting JSON to YAML +--- -```python -# Convert JSON string to YAML and print -json_string = '{"name": "Bob", "age": 25, "is_active": false}' -yaml_string = YamlModel.json_to_yaml(json_string) -print(yaml_string) -``` +## Best Practices -This example showcases the conversion of a JSON string containing user data into a YAML string representation using the `json_to_yaml()` static method. The resulting YAML string might look like: +### Function Design -```yaml -name: Bob -age: 25 -is_active: false -``` +| 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 | -### Saving User Instance to YAML File +### 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 -# Save the User instance to a YAML file -user.save_to_yaml("user.yaml") +# Ensure function is in tools list +agent = Agent( + # ... other config ... + tools=[your_function_name], # Function object, not string +) ``` -This code demonstrates the utilization of the `save_to_yaml()` method to store the `user` instance as a YAML file named "user.yaml". The contents of the file will mirror the serialized YAML string representation of the user object. +#### MCP Connection Failed +```python +# Check server status and URL +import requests +response = requests.get("http://localhost:8001/health") # Health check endpoint +``` -## Additional Considerations +#### Type Hint Errors -* Ensure you have the `PyYAML` library installed (`pip install pyyaml`) to leverage the YAML parsing and serialization functionalities within `YamlModel`. -* Remember that the `create_yaml_schema()` method is not yet implemented but serves as a placeholder for future enhancements. -* For complex data structures within your YAML models, consider leveraging Pydantic's data validation and nested model capabilities for robust data management. +```python +# Always specify return types +def my_tool(param: str) -> str: # Not just -> None + return "result" +``` -## Conclusion +#### JSON Parsing Issues -The `YamlModel` class in Pydantic offers a streamlined approach to working with YAML data in your Python projects. By employing the provided methods (`to_yaml()`, `from_yaml()`, `json_to_yaml()`, and `save_to_yaml()`), you can efficiently convert between Python objects and YAML representations, facilitating data persistence and exchange. This comprehensive documentation empowers you to effectively utilize `YamlModel` for your YAML data processing requirements. +```python +# Always return valid JSON strings +import json +return json.dumps({"result": data}, indent=2) +``` -------------------------------------------------- -# File: swarms/tools/build_tool.md +# File: swarms\ui\main.md -### Swarms Tool Documentation +# Swarms Chat UI Documentation -A tool is a Python function designed to perform specific tasks, with clear type annotations and comprehensive docstrings. Below are examples of tools to help you get started. +The Swarms Chat interface provides a customizable, multi-agent chat experience using Gradio. It supports various specialized AI agents—from finance to healthcare and news analysis—by leveraging Swarms models. -# Rules +--- -To create a tool in the Swarms environment, follow these rules: +## Table of Contents -1. **Function Definition**: - - The tool must be defined as a Python function. - - The function should perform a specific task and be named appropriately. +1. [Installation](#installation) +2. [Quick Start](#quick-start) +3. [Parameters Overview](#parameters-overview) +4. [Specialized Agents](#specialized-agents) + - [Finance Agents](#finance-agents) + - [Healthcare Agents](#healthcare-agents) + - [News & Research Agents](#news--research-agents) +5. [Swarms Integration Features](#swarms-integration-features) +6. [Usage Examples](#usage-examples) + - [Finance Agent Example](#finance-agent-example) + - [Healthcare Agent Example](#healthcare-agent-example) + - [News Analysis Agent Example](#news-analysis-agent-example) +7. [Setup and Deployment](#setup-and-deployment) +8. [Best Practices](#best-practices) +9. [Notes](#notes) -2. **Type Annotations**: - - All arguments and the return value must have type annotations. - - Both input and output types must be strings (`str`). +--- -3. **Docstrings**: - - Each function must include a comprehensive docstring that adheres to PEP 257 standards. The docstring should explain: - - The purpose of the function. - - Arguments: names, types, and descriptions. - - Return value: type and description. - - Potential exceptions that the function may raise. +## Installation -4. **Input and Output Types**: - - The function's input must be a string. - - The function's output must be a string. +Make sure you have Python 3.7+ installed, then install the required packages using pip: +```bash +pip install gradio ai-gradio swarms +``` -### Example Tools +--- +## Quick Start -### Examples and Anti-Examples +Below is a minimal example to get the Swarms Chat interface up and running. Customize the agent, title, and description as needed. -#### Example 1: Fetch Financial News +```python +import gradio as gr +import ai_gradio -**Correct Implementation** +# Create and launch a Swarms Chat interface +gr.load( + name='swarms:gpt-4-turbo', # Model identifier (supports OpenAI and others) + src=ai_gradio.registry, # Source module for model configurations + agent_name="Stock-Analysis-Agent", # Example agent from Finance category + title='Swarms Chat', + description='Chat with an AI agent powered by Swarms' +).launch() +``` -```python -import requests -import os +--- -def fetch_financial_news(query: str = "Nvidia news", num_articles: int = 5) -> str: - """ - Fetches financial news from the Google News API and returns a formatted string of the top news. +## Parameters Overview - Args: - query (str): The query term to search for news. Default is "Nvidia news". - num_articles (int): The number of top articles to fetch. Default is 5. +When configuring your interface, consider the following parameters: - Returns: - str: A formatted string of the top financial news articles. +- **`name` (str):** + Model identifier (e.g., `'swarms:gpt-4-turbo'`) that specifies which Swarms model to use. - Raises: - ValueError: If the API response is invalid or there are no articles found. - requests.exceptions.RequestException: If there is an error with the request. - """ - url = "https://newsapi.org/v2/everything" - params = { - "q": query, - "apiKey": os.getenv("NEWSAPI_KEY"), - "pageSize": num_articles, - "sortBy": "relevancy", - } +- **`src` (module):** + The source module (typically `ai_gradio.registry`) that contains model configurations. - try: - response = requests.get(url, params=params) - response.raise_for_status() - data = response.json() +- **`agent_name` (str):** + The name of the specialized agent you wish to use (e.g., "Stock-Analysis-Agent"). - if "articles" not in data or len(data["articles"]) == 0: - raise ValueError("No articles found or invalid API response.") +- **`title` (str):** + The title that appears at the top of the web interface. - articles = data["articles"] - formatted_articles = [] +- **`description` (str):** + A short summary describing the functionality of the chat interface. - for i, article in enumerate(articles, start=1): - title = article.get("title", "No Title") - description = article.get("description", "No Description") - url = article.get("url", "No URL") - formatted_articles.append( - f"{i}. {title}\nDescription: {description}\nRead more: {url}\n" - ) +--- - return "\n".join(formatted_articles) +## Specialized Agents - except requests.exceptions.RequestException as e: - print(f"Request Error: {e}") - raise - except ValueError as e: - print(f"Value Error: {e}") - raise -``` +Swarms Chat supports multiple specialized agents designed for different domains. Below is an overview of available agent types. -**Incorrect Implementation** +### Finance Agents -```python -import requests -import os +1. **Stock Analysis Agent** + - **Capabilities:** + - Market analysis and stock recommendations. + - Both technical and fundamental analysis. + - Portfolio management suggestions. -def fetch_financial_news(query="Nvidia news", num_articles=5): - # Fetches financial news from the Google News API and returns a formatted string of the top news. - url = "https://newsapi.org/v2/everything" - params = { - "q": query, - "apiKey": os.getenv("NEWSAPI_KEY"), - "pageSize": num_articles, - "sortBy": "relevancy", - } +2. **Tax Planning Agent** + - **Capabilities:** + - Tax optimization strategies. + - Deduction analysis. + - Guidance on tax law compliance. - response = requests.get(url, params=params) - response.raise_for_status() - data = response.json() +### Healthcare Agents - if "articles" not in data or len(data["articles"]) == 0: - raise ValueError("No articles found or invalid API response.") +1. **Medical Diagnosis Assistant** + - **Capabilities:** + - Analysis of symptoms. + - Treatment recommendations. + - Research using current medical literature. - articles = data["articles"] - formatted_articles = [] +2. **Healthcare Management Agent** + - **Capabilities:** + - Patient care coordination. + - Organization of medical records. + - Monitoring and tracking treatment plans. - for i, article in enumerate(articles, start=1): - title = article.get("title", "No Title") - description = article.get("description", "No Description") - url = article.get("url", "No URL") - formatted_articles.append( - f"{i}. {title}\nDescription: {description}\nRead more: {url}\n" - ) +### News & Research Agents - return "\n".join(formatted_articles) -``` +1. **News Analysis Agent** + - **Capabilities:** + - Real-time news aggregation. + - Filtering news by topics. + - Trend analysis and insights. -**Issues with Incorrect Implementation:** -- No type annotations for arguments and return value. -- Missing comprehensive docstring. +2. **Research Assistant** + - **Capabilities:** + - Analysis of academic papers. + - Literature review support. + - Guidance on research methodologies. -#### Example 2: Convert Celsius to Fahrenheit +--- -**Correct Implementation** +## Swarms Integration Features -```python -def celsius_to_fahrenheit(celsius_str: str) -> str: - """ - Converts a temperature from Celsius to Fahrenheit. +### Core Capabilities - Args: - celsius_str (str): The temperature in Celsius as a string. +- **Multi-Agent Collaboration:** Multiple agents can be engaged simultaneously for a coordinated experience. +- **Real-Time Data Processing:** The interface processes and responds to queries in real time. +- **Natural Language Understanding:** Advanced NLP for context-aware and coherent responses. +- **Context-Aware Responses:** Responses are tailored based on conversation context. - Returns: - str: The temperature converted to Fahrenheit as a formatted string. +### Technical Features - Raises: - ValueError: If the input cannot be converted to a float. - """ - try: - celsius = float(celsius_str) - fahrenheit = celsius * 9/5 + 32 - return f"{celsius}°C is {fahrenheit}°F" - except ValueError as e: - print(f"Value Error: {e}") - raise -``` +- **API Integration Support:** Easily connect with external APIs. +- **Custom Model Selection:** Choose the appropriate model for your specific task. +- **Concurrent Processing:** Supports multiple sessions concurrently. +- **Session Management:** Built-in session management ensures smooth user interactions. -**Incorrect Implementation** +--- -```python -def celsius_to_fahrenheit(celsius): - # Converts a temperature from Celsius to Fahrenheit. - celsius = float(celsius) - fahrenheit = celsius * 9/5 + 32 - return f"{celsius}°C is {fahrenheit}°F" -``` +## Usage Examples -**Issues with Incorrect Implementation:** -- No type annotations for arguments and return value. -- Missing comprehensive docstring. -- Input type is not enforced as string. +Below are detailed examples for each type of specialized agent. -#### Example 3: Calculate Compound Interest +### Finance Agent Example -**Correct Implementation** +This example configures a chat interface for stock analysis: ```python -def calculate_compound_interest(principal_str: str, rate_str: str, time_str: str, n_str: str) -> str: - """ - Calculates compound interest. - - Args: - principal_str (str): The initial amount of money as a string. - rate_str (str): The annual interest rate (decimal) as a string. - time_str (str): The time the money is invested for in years as a string. - n_str (str): The number of times that interest is compounded per year as a string. - - Returns: - str: The amount of money accumulated after n years, including interest. +import gradio as gr +import ai_gradio - Raises: - ValueError: If any of the inputs cannot be converted to the appropriate type or are negative. - """ - try: - principal = float(principal_str) - rate = float(rate_str) - time = float(time_str) - n = int(n_str) - - if principal < 0 or rate < 0 or time < 0 or n < 0: - raise ValueError("Inputs must be non-negative.") - - amount = principal * (1 + rate / n) ** (n * time) - return f"The amount after {time} years is {amount:.2f}" - except ValueError as e: - print(f"Value Error: {e}") - raise +finance_interface = gr.load( + name='swarms:gpt-4-turbo', + src=ai_gradio.registry, + agent_name="Stock-Analysis-Agent", + title='Finance Assistant', + description='Expert financial analysis and advice tailored to your investment needs.' +) +finance_interface.launch() ``` -**Incorrect Implementation** +### Healthcare Agent Example -```python -def calculate_compound_interest(principal, rate, time, n): - # Calculates compound interest. - principal = float(principal) - rate = float(rate) - time = float(time) - n = int(n) - - if principal < 0 or rate < 0 or time < 0 or n < 0: - raise ValueError("Inputs must be non-negative.") - - amount = principal * (1 + rate / n) ** (n * time) - return f"The amount after {time} years is {amount:.2f}" -``` +This example sets up a chat interface for healthcare assistance: -**Issues with Incorrect Implementation:** -- No type annotations for arguments and return value. -- Missing comprehensive docstring. -- Input types are not enforced as strings. +```python +import gradio as gr +import ai_gradio -By following these rules and using the examples provided, you can create robust and well-documented tools in the Swarms environment. Ensure that all functions include proper type annotations, comprehensive docstrings, and that both input and output types are strings. +healthcare_interface = gr.load( + name='swarms:gpt-4-turbo', + src=ai_gradio.registry, + agent_name="Medical-Assistant-Agent", + title='Healthcare Assistant', + description='Access medical information, symptom analysis, and treatment recommendations.' +) +healthcare_interface.launch() +``` -#### Example Tool 4: Reverse a String +### News Analysis Agent Example -**Functionality**: Reverses a given string. +This example creates an interface for real-time news analysis: ```python -def reverse_string(s: str) -> str: - """ - Reverses a given string. - - Args: - s (str): The string to reverse. - - Returns: - str: The reversed string. +import gradio as gr +import ai_gradio - Raises: - TypeError: If the input is not a string. - """ - try: - if not isinstance(s, str): - raise TypeError("Input must be a string.") - return s[::-1] - except TypeError as e: - print(f"Type Error: {e}") - raise +news_interface = gr.load( + name='swarms:gpt-4-turbo', + src=ai_gradio.registry, + agent_name="News-Analysis-Agent", + title='News Analyzer', + description='Get real-time insights and analysis of trending news topics.' +) +news_interface.launch() ``` -#### Example Tool 5: Check Palindrome +--- -**Functionality**: Checks if a given string is a palindrome. +## Setup and Deployment -```python -def is_palindrome(s: str) -> str: - """ - Checks if a given string is a palindrome. +1. **Install Dependencies:** + Make sure all required packages are installed. - Args: - s (str): The string to check. + ```bash + pip install gradio ai-gradio swarms + ``` - Returns: - str: A message indicating whether the string is a palindrome or not. +2. **Import Modules:** + Import Gradio and ai_gradio in your Python script. - Raises: - TypeError: If the input is not a string. - """ - try: - if not isinstance(s, str): - raise TypeError("Input must be a string.") - normalized_str = ''.join(filter(str.isalnum, s)).lower() - is_palindrome = normalized_str == normalized_str[::-1] - return f"The string '{s}' is {'a palindrome' if is_palindrome else 'not a palindrome'}." - except TypeError as e: - print(f"Type Error: {e}") - raise -``` + ```python + import gradio as gr + import ai_gradio + ``` -#### Example Tool 6: Fetch Current Weather +3. **Configure and Launch the Interface:** + Configure your interface with the desired parameters and then launch. -**Functionality**: Fetches the current weather for a given city from the OpenWeatherMap API. + ```python + interface = gr.load( + name='swarms:gpt-4-turbo', + src=ai_gradio.registry, + agent_name="Your-Desired-Agent", + title='Your Interface Title', + description='A brief description of your interface.' + ) + interface.launch() + ``` -```python -import requests -import os +4. **Deployment Options:** + - **Local:** By default, the interface runs at [http://localhost:7860](http://localhost:7860). + - **Cloud Deployment:** Use cloud platforms like Heroku, AWS, or Google Cloud for remote access. + - **Concurrent Sessions:** The system supports multiple users at the same time. Monitor resources and use proper scaling. -def fetch_current_weather(city: str) -> str: - """ - Fetches the current weather for a given city from the OpenWeatherMap API. +--- - Args: - city (str): The name of the city to fetch the weather for. +## Best Practices - Returns: - str: A formatted string of the current weather in the specified city. +1. **Select the Right Agent:** + Use the agent that best suits your specific domain needs. - Raises: - ValueError: If the API response is invalid or the city is not found. - requests.exceptions.RequestException: If there is an error with the request. - """ - url = "http://api.openweathermap.org/data/2.5/weather" - params = { - "q": city, - "appid": os.getenv("OPENWEATHERMAP_KEY"), - "units": "metric", - } +2. **Model Configuration:** + Adjust model parameters based on your computational resources to balance performance and cost. - try: - response = requests.get(url, params=params) - response.raise_for_status() - data = response.json() +3. **Error Handling:** + Implement error handling to manage unexpected inputs or API failures gracefully. - if "weather" not in data or "main" not in data: - raise ValueError("Invalid API response or city not found.") +4. **Resource Monitoring:** + Keep an eye on system performance, especially during high-concurrency sessions. - weather_description = data["weather"][0]["description"] - temperature = data["main"]["temp"] - return f"The current weather in {city} is {weather_description} with a temperature of {temperature}°C." +5. **Regular Updates:** + Keep your Swarms and Gradio packages updated to ensure compatibility with new features and security patches. - except requests.exceptions.RequestException as e: - print(f"Request Error: {e}") - raise - except ValueError as e: - print(f"Value Error: {e}") - raise -``` +--- -By following the examples provided, you can create your own tools to perform various tasks in the Swarms environment. Ensure each function includes type annotations, comprehensive docstrings, and appropriate error handling to make your tools robust and easy to use. +## Notes +- **Local vs. Remote:** + The interface runs locally by default but can be deployed on remote servers for wider accessibility. +- **Customization:** + You can configure custom model parameters and integrate additional APIs as needed. +- **Session Management:** + Built-in session handling ensures that users can interact concurrently without interfering with each other's sessions. +- **Error Handling & Rate Limiting:** + The system includes basic error handling and rate limiting to maintain performance under load. -## Integrate tools into Agent -To integrate tools into an agent, you'd simply just pass in a callable function with types and documentation into the agent class. +--- -```python +This documentation is designed to provide clarity, reliability, and comprehensive guidance for integrating and using the Swarms Chat UI. For further customization or troubleshooting, consult the respective package documentation and community forums. +-------------------------------------------------- -from swarms import Agent, OpenAIChat # ChromaDB -import subprocess +# File: swarms_cloud\add_agent.md -# Model -llm = OpenAIChat( - temperature=0.1, -) +# Publishing an Agent to Agent Marketplace +## Requirements -# Tools -def terminal( - code: str, -): - """ - Run code in the terminal. +- `swarms-cloud` package with `pip3 install -U swarms-cloud` - Args: - code (str): The code to run in the terminal. +- Onboarding Process with `swarms-cloud onboarding` - Returns: - str: The output of the code. - """ - out = subprocess.run( - code, shell=True, capture_output=True, text=True - ).stdout - return str(out) +- A Dockerfile `Dockerfile` containing the API of your agent code with FastAPI +- A YAML file for configuration `agent.yaml` -def browser(query: str): - """ - Search the query in the browser with the `browser` tool. +## Deployment YAML +```yaml - Args: - query (str): The query to search in the browser. +# Agent metadata and description +agent_name: "example-agent" # The name of the agent +description: "This agent performs financial data analysis." # A brief description of the agent's purpose +version: "v1.0" # The version number of the agent +author: "Agent Creator Name" # The name of the person or entity that created the agent +contact_email: "creator@example.com" # The email address for contacting the agent's creator +tags: + - "financial" # Tag indicating the agent is related to finance + - "data-analysis" # Tag indicating the agent performs data analysis + - "agent" # Tag indicating this is an agent - Returns: - str: The search results. - """ - import webbrowser - url = f"https://www.google.com/search?q={query}" - webbrowser.open(url) - return f"Searching for {query} in the browser." +# Deployment configuration +deployment_config: + # Dockerfile configuration + dockerfile_path: "./Dockerfile" # The path to the Dockerfile for building the agent's image + dockerfile_port: 8080 # The port number the agent will listen on + + # Resource allocation for the agent + resources: + cpu: 2 # Number of CPUs allocated to the agent + memory: "2Gi" # Memory allocation for the agent in gigabytes + max_instances: 5 # Maximum number of instances to scale up to + min_instances: 1 # Minimum number of instances to keep running + timeout: 300s # Request timeout setting in seconds + # Autoscaling configuration + autoscaling: + max_concurrency: 80 # Maximum number of requests the agent can handle concurrently + target_utilization: 0.6 # CPU utilization target for auto-scaling -def create_file(file_path: str, content: str): - """ - Create a file using the file editor tool. + # Environment variables for the agent + environment_variables: + DATABASE_URL: "postgres://user:password@db-url" # URL for the database connection + API_KEY: "your-secret-api-key" # API key for authentication + LOG_LEVEL: "info" # Log level for the agent - Args: - file_path (str): The path to the file. - content (str): The content to write to the file. + # Secrets configuration + secrets: + SECRET_NAME_1: "projects/my-project/secrets/my-secret/versions/latest" # Path to a secret +``` - Returns: - str: The result of the file creation operation. - """ - with open(file_path, "w") as file: - file.write(content) - return f"File {file_path} created successfully." +-------------------------------------------------- +# File: swarms_cloud\agent_api.md -def file_editor(file_path: str, mode: str, content: str): - """ - Edit a file using the file editor tool. +# Agent API - Args: - file_path (str): The path to the file. - mode (str): The mode to open the file in. - content (str): The content to write to the file. +The Swarms.ai Agent API provides powerful endpoints for running individual AI agents and batch agent operations. This documentation explains how to use these endpoints for effective agent-based task execution. - Returns: - str: The result of the file editing operation. - """ - with open(file_path, mode) as file: - file.write(content) - return f"File {file_path} edited successfully." +## Getting Started +To use the Agent API, you'll need a Swarms.ai API key: -# Agent -agent = Agent( - agent_name="Devin", - system_prompt=( - "Autonomous agent that can interact with humans and other" - " agents. Be Helpful and Kind. Use the tools provided to" - " assist the user. Return all code in markdown format." - ), - llm=llm, - max_loops="auto", - autosave=True, - dashboard=False, - streaming_on=True, - verbose=True, - stopping_token="", - interactive=True, - tools=[terminal, browser, file_editor, create_file], - # long_term_memory=chromadb, - metadata_output_type="json", - # List of schemas that the agent can handle - # list_base_models=[tool_schema], - function_calling_format_type="OpenAI", - function_calling_type="json", # or soon yaml -) +1. Go to [https://swarms.world/platform/api-keys](https://swarms.world/platform/api-keys) +2. Generate a new API key +3. Store your API key securely - it won't be shown again -# Run the agent -agent.run("Create a new file for a plan to take over the world.") +```python +import os +import requests +from dotenv import load_dotenv + +# Load API key from environment +load_dotenv() +API_KEY = os.getenv("SWARMS_API_KEY") +BASE_URL = "https://api.swarms.world" +# Configure headers with your API key +headers = { + "x-api-key": API_KEY, + "Content-Type": "application/json" +} ``` +## Individual Agent API -## Example 2 +The Individual Agent API allows you to run a single agent with a specific configuration and task. +### Agent Configuration (`AgentSpec`) -```python +The `AgentSpec` class defines the configuration for an individual agent. -import os +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `agent_name` | string | Required | Unique name identifying the agent and its functionality | +| `description` | string | None | Detailed explanation of the agent's purpose and capabilities | +| `system_prompt` | string | None | Initial instructions guiding the agent's behavior and responses | +| `model_name` | string | "gpt-4o-mini" | The AI model used by the agent (e.g., gpt-4o, gpt-4o-mini, openai/o3-mini) | +| `auto_generate_prompt` | boolean | false | Whether the agent should automatically create prompts based on task requirements | +| `max_tokens` | integer | 8192 | Maximum number of tokens the agent can generate in its responses | +| `temperature` | float | 0.5 | Controls output randomness (lower values = more deterministic responses) | +| `role` | string | "worker" | The agent's role within a swarm, influencing its behavior and interactions | +| `max_loops` | integer | 1 | Maximum number of times the agent can repeat its task for iterative processing | +| `tools_dictionary` | array | None | Dictionary of tools the agent can use to complete its task | +| `mcp_url` | string | None | URL for the MCP server that the agent can connect to | + +### Agent Completion + +The `AgentCompletion` class combines an agent configuration with a specific task. -import requests +| Parameter | Type | Description | +|-----------|------|-------------| +| `agent_config` | AgentSpec | Configuration of the agent to be completed | +| `task` | string | The task to be completed by the agent | +| `history` | Optional[Union[Dict[Any, Any], List[Dict[str, str]]]] | The history of the agent's previous tasks and responses. Can be either a dictionary or a list of message objects. | -from swarms import Agent -from swarm_models import OpenAIChat +### Single Agent Endpoint -# Get the OpenAI API key from the environment variable -api_key = os.getenv("OPENAI_API_KEY") +**Endpoint:** `POST /v1/agent/completions` -# Create an instance of the OpenAIChat class -model = OpenAIChat( - api_key=api_key, model_name="gpt-4o-mini", temperature=0.1 -) +Run a single agent with a specific configuration and task. +#### Request -def fetch_financial_news( - query: str = "Nvidia news", num_articles: int = 5 -) -> str: +```python +def run_single_agent(agent_config, task): """ - Fetches financial news from the Google News API and returns a formatted string of the top news. - + Run a single agent with the AgentCompletion format. + Args: - api_key (str): Your Google News API key. - query (str): The query term to search for news. Default is "financial". - num_articles (int): The number of top articles to fetch. Default is 5. - + agent_config: Dictionary containing agent configuration + task: String describing the task for the agent + Returns: - str: A formatted string of the top financial news articles. - - Raises: - ValueError: If the API response is invalid or there are no articles found. - requests.exceptions.RequestException: If there is an error with the request. + Dictionary containing the agent's response """ - url = "https://newsapi.org/v2/everything" - params = { - "q": query, - "apiKey": os.getenv("NEWSAPI_KEY"), - "pageSize": num_articles, - "sortBy": "relevancy", + payload = { + "agent_config": agent_config, + "task": task } - + try: - response = requests.get(url, params=params) + response = requests.post( + f"{BASE_URL}/v1/agent/completions", + headers=headers, + json=payload + ) response.raise_for_status() - data = response.json() - - if "articles" not in data or len(data["articles"]) == 0: - raise ValueError("No articles found or invalid API response.") - - articles = data["articles"] - formatted_articles = [] - - for i, article in enumerate(articles, start=1): - title = article.get("title", "No Title") - description = article.get("description", "No Description") - url = article.get("url", "No URL") - formatted_articles.append( - f"{i}. {title}\nDescription: {description}\nRead more: {url}\n" - ) - - return "\n".join(formatted_articles) - + return response.json() except requests.exceptions.RequestException as e: - print(f"Request Error: {e}") - raise - except ValueError as e: - print(f"Value Error: {e}") - raise - - -# # Example usage: -# api_key = "ceabc81a7d8f45febfedadb27177f3a3" -# print(fetch_financial_news(api_key)) + print(f"Error making request: {e}") + return None +``` +#### Example Usage -# Initialize the agent -agent = Agent( - agent_name="Financial-Analysis-Agent", - # system_prompt=FINANCIAL_AGENT_SYS_PROMPT, - llm=model, - max_loops=2, - autosave=True, - # dynamic_temperature_enabled=True, - dashboard=False, - verbose=True, - streaming_on=True, - # interactive=True, # Set to False to disable interactive mode - dynamic_temperature_enabled=True, - saved_state_path="finance_agent.json", - tools=[fetch_financial_news], - # stopping_token="Stop!", - # interactive=True, - # docs_folder="docs", # Enter your folder name - # pdf_path="docs/finance_agent.pdf", - # sop="Calculate the profit for a company.", - # sop_list=["Calculate the profit for a company."], - user_name="swarms_corp", - # # docs= - # # docs_folder="docs", - retry_attempts=3, - # context_length=1000, - # tool_schema = dict - context_length=200000, - # tool_schema= - # tools - # agent_ops_on=True, - # long_term_memory=ChromaDB(docs_folder="artifacts"), -) +```python +agent_config = { + "agent_name": "Research Analyst", + "description": "An expert in analyzing and synthesizing research data", + "system_prompt": ( + "You are a Research Analyst with expertise in data analysis and synthesis. " + "Your role is to analyze provided information, identify key insights, " + "and present findings in a clear, structured format. " + "Focus on accuracy, clarity, and actionable recommendations." + ), + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 2, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": False, +} +task = "Analyze the impact of artificial intelligence on healthcare delivery and provide a comprehensive report with key findings and recommendations." -# Run the agent -response = agent("What are the latest financial news on Nvidia?") -print(response) +result = run_single_agent(agent_config, task) +print(result) +``` +#### Response Structure +```json +{ + "id": "agent-6a8b9c0d1e2f3g4h5i6j7k8l9m0n", + "success": true, + "name": "Research Analyst", + "description": "An expert in analyzing and synthesizing research data", + "temperature": 0.5, + "outputs": { + "content": "# Impact of Artificial Intelligence on Healthcare Delivery\n\n## Executive Summary\n...", + "role": "assistant" + }, + "usage": { + "input_tokens": 1250, + "output_tokens": 3822, + "total_tokens": 5072 + }, + "timestamp": "2025-05-10T18:35:29.421Z" +} ``` +## Batch Agent API --------------------------------------------------- +The Batch Agent API allows you to run multiple agents in parallel, each with different configurations and tasks. -# File: swarms/tools/main.md +### Batch Agent Endpoint -# The Swarms Tool System: Functions, Pydantic BaseModels as Tools, and Radical Customization +**Endpoint:** `POST /v1/agent/batch/completions` +Run multiple agents with different configurations and tasks in a single API call. -This guide provides an in-depth look at the Swarms Tool System, focusing on its functions, the use of Pydantic BaseModels as tools, and the extensive customization options available. Aimed at developers, this documentation highlights how the Swarms framework works and offers detailed examples of creating and customizing tools and agents, specifically for accounting tasks. +#### Request -The Swarms Tool System is a flexible and extensible component of the Swarms framework that allows for the creation, registration, and utilization of various tools. These tools can perform a wide range of tasks and are integrated into agents to provide specific functionalities. The system supports multiple ways to define tools, including using Pydantic BaseModels, functions, and dictionaries. +```python +def run_batch_agents(agent_completions): + """ + Run multiple agents in batch. + + Args: + agent_completions: List of dictionaries, each containing agent_config and task + + Returns: + List of agent responses + """ + try: + response = requests.post( + f"{BASE_URL}/v1/agent/batch/completions", + headers=headers, + json=agent_completions + ) + response.raise_for_status() + return response.json() + except requests.exceptions.RequestException as e: + print(f"Error making batch request: {e}") + return None +``` -### Architecture +#### Example Usage -The architecture of the Swarms Tool System is designed to be highly modular. It consists of the following main components: +```python +batch_completions = [ + { + "agent_config": { + "agent_name": "Research Analyst", + "description": "An expert in analyzing research data", + "system_prompt": "You are a Research Analyst...", + "model_name": "gpt-4o", + "max_loops": 2 + }, + "task": "Analyze the impact of AI on healthcare delivery." + }, + { + "agent_config": { + "agent_name": "Market Analyst", + "description": "An expert in market analysis", + "system_prompt": "You are a Market Analyst...", + "model_name": "gpt-4o", + "max_loops": 1 + }, + "task": "Analyze the AI startup landscape in 2025." + } +] -1. **Agents:** The primary entities that execute tasks. -2. **Tools:** Functions or classes that perform specific operations. -3. **Schemas:** Definitions of input and output data formats using Pydantic BaseModels. +batch_results = run_batch_agents(batch_completions) +print(batch_results) +``` -### Key Concepts +#### Response Structure -#### Tools +```json +[ + { + "id": "agent-1a2b3c4d5e6f7g8h9i0j", + "success": true, + "name": "Research Analyst", + "description": "An expert in analyzing research data", + "temperature": 0.5, + "outputs": { + "content": "# Impact of AI on Healthcare Delivery\n...", + "role": "assistant" + }, + "usage": { + "input_tokens": 1250, + "output_tokens": 3822, + "total_tokens": 5072 + }, + "timestamp": "2025-05-10T18:35:29.421Z" + }, + { + "id": "agent-9i8h7g6f5e4d3c2b1a0", + "success": true, + "name": "Market Analyst", + "description": "An expert in market analysis", + "temperature": 0.5, + "outputs": { + "content": "# AI Startup Landscape 2025\n...", + "role": "assistant" + }, + "usage": { + "input_tokens": 980, + "output_tokens": 4120, + "total_tokens": 5100 + }, + "timestamp": "2025-05-10T18:35:31.842Z" + } +] +``` -Tools are the core functional units within the Swarms framework. They can be defined in various ways: +## Error Handling -- **Pydantic BaseModels**: Tools can be defined using Pydantic BaseModels to ensure data validation and serialization. -- **Functions**: Tools can be simple or complex functions. -- **Dictionaries**: Tools can be represented as dictionaries for flexibility. +The API uses standard HTTP status codes to indicate success or failure: -#### Agents +| Status Code | Meaning | +|-------------|---------| +| 200 | Success | +| 400 | Bad Request - Check your request parameters | +| 401 | Unauthorized - Invalid or missing API key | +| 403 | Forbidden - Insufficient permissions | +| 429 | Too Many Requests - Rate limit exceeded | +| 500 | Server Error - Something went wrong on the server | -Agents utilize tools to perform tasks. They are configured with a set of tools and schemas, and they execute the tools based on the input they receive. +When an error occurs, the response body will contain additional information: -## Detailed Documentation +```json +{ + "detail": "Error message explaining what went wrong" +} +``` -### Tool Definition +### Common Errors and Solutions -#### Using Pydantic BaseModels +| Error | Possible Solution | +|-------|-------------------| +| "Invalid API Key" | Verify your API key is correct and properly included in the request headers | +| "Rate limit exceeded" | Reduce the number of requests or contact support to increase your rate limit | +| "Invalid agent configuration" | Check your agent_config parameters for any missing or invalid values | +| "Failed to create agent" | Ensure your system_prompt and model_name are valid | +| "Insufficient credits" | Add credits to your account at https://swarms.world/platform/account | -Pydantic BaseModels provide a structured way to define tool inputs and outputs. They ensure data validation and serialization, making them ideal for complex data handling. +## Advanced Usage -**Example:** +### Setting Dynamic Temperature -Define Pydantic BaseModels for accounting tasks: +The agent can dynamically adjust its temperature for optimal outputs: ```python -from pydantic import BaseModel +agent_config = { + # Other config options... + "temperature": 0.7, + "dynamic_temperature_enabled": True +} +``` -class CalculateTax(BaseModel): - income: float +### Using Agent Tools -class GenerateInvoice(BaseModel): - client_name: str - amount: float - date: str +Agents can utilize various tools to enhance their capabilities: -class SummarizeExpenses(BaseModel): - expenses: list[dict] +```python +agent_config = { + # Other config options... + "tools_dictionary": [ + { + "name": "web_search", + "description": "Search the web for information", + "parameters": { + "query": "string" + } + }, + { + "name": "calculator", + "description": "Perform mathematical calculations", + "parameters": { + "expression": "string" + } + } + ] +} ``` -Define tool functions using these models: +## Best Practices -```python -def calculate_tax(data: CalculateTax) -> dict: - tax_rate = 0.3 # Example tax rate - tax = data.income * tax_rate - return {"income": data.income, "tax": tax} +!!! tip "API Key Security" + Store API keys in environment variables or secure vaults, never in code repositories. + ```python + # DON'T do this + api_key = "sk-123456789abcdef" + + # DO this instead + import os + from dotenv import load_dotenv + load_dotenv() + api_key = os.getenv("SWARMS_API_KEY") + ``` -def generate_invoice(data: GenerateInvoice) -> dict: - invoice = { - "client_name": data.client_name, - "amount": data.amount, - "date": data.date, - "invoice_id": "INV12345" +!!! info "Agent Naming Conventions" + Use a consistent naming pattern for your agents to make your code more maintainable. + ```python + # Good naming convention + agent_configs = { + "market_analyst": {...}, + "research_specialist": {...}, + "code_reviewer": {...} } - return invoice + ``` -def summarize_expenses(data: SummarizeExpenses) -> dict: - total_expenses = sum(expense['amount'] for expense in data.expenses) - return {"total_expenses": total_expenses} -``` +!!! success "Crafting Effective System Prompts" + A well-crafted system prompt acts as your agent's personality and instruction set. + + === "Basic Prompt" + ``` + You are a research analyst. Analyze the data and provide insights. + ``` + + === "Enhanced Prompt" + ``` + You are a Research Analyst with 15+ years of experience in biotech market analysis. + + Your task is to: + 1. Analyze the provided market data methodically + 2. Identify key trends and emerging patterns + 3. Highlight potential investment opportunities + 4. Assess risks and regulatory considerations + 5. Provide actionable recommendations supported by the data + + Format your response as a professional report with clear sections, + focusing on data-driven insights rather than generalities. + ``` -#### Using Functions Directly +!!! warning "Token Management" + Manage your token usage carefully to control costs. + + - Higher token limits provide more complete responses but increase costs + - Consider using different models based on task complexity + - For gpt-4o models, typical settings: + - Simple tasks: 2048 tokens (lower cost) + - Medium complexity: 4096 tokens (balanced) + - Complex analysis: 8192+ tokens (higher cost, more detail) -Tools can also be defined directly as functions without using Pydantic models. This approach is suitable for simpler tasks where complex validation is not required. +!!! danger "Error Handling" + Implement comprehensive error handling to make your application resilient. + + ```python + try: + response = requests.post( + f"{BASE_URL}/v1/agent/completions", + headers=headers, + json=payload, + timeout=30 # Add timeout to prevent hanging requests + ) + response.raise_for_status() + return response.json() + except requests.exceptions.HTTPError as e: + if e.response.status_code == 429: + # Implement exponential backoff for rate limiting + retry_after = int(e.response.headers.get('Retry-After', 5)) + time.sleep(retry_after) + return run_agent(payload) # Retry the request + elif e.response.status_code == 401: + logger.error("Authentication failed. Check your API key.") + else: + logger.error(f"HTTP Error: {e.response.status_code} - {e.response.text}") + return {"error": e.response.text} + except requests.exceptions.Timeout: + logger.error("Request timed out. The server might be busy.") + return {"error": "Request timed out"} + except requests.exceptions.RequestException as e: + logger.error(f"Request Error: {e}") + return {"error": str(e)} + ``` -**Example:** +!!! example "Implementing Caching" + Cache identical requests to improve performance and reduce costs. + + ```python + import hashlib + import json + from functools import lru_cache + + def generate_cache_key(agent_config, task): + """Generate a unique cache key for an agent request.""" + cache_data = json.dumps({"agent_config": agent_config, "task": task}, sort_keys=True) + return hashlib.md5(cache_data.encode()).hexdigest() + + @lru_cache(maxsize=100) + def cached_agent_run(cache_key, agent_config, task): + """Run agent with caching based on config and task.""" + # Convert agent_config back to a dictionary if it's a string representation + if isinstance(agent_config, str): + agent_config = json.loads(agent_config) + + payload = { + "agent_config": agent_config, + "task": task + } + + try: + response = requests.post( + f"{BASE_URL}/v1/agent/completions", + headers=headers, + json=payload + ) + response.raise_for_status() + return response.json() + except Exception as e: + return {"error": str(e)} + + def run_agent_with_cache(agent_config, task): + """Wrapper function to run agent with caching.""" + # Generate a cache key + cache_key = generate_cache_key(agent_config, task) + + # Convert agent_config to a hashable type for lru_cache + hashable_config = json.dumps(agent_config, sort_keys=True) + + # Call the cached function + return cached_agent_run(cache_key, hashable_config, task) + ``` -```python -def basic_tax_calculation(income: float) -> dict: - tax_rate = 0.25 - tax = income * tax_rate - return {"income": income, "tax": tax} -``` +!!! abstract "Usage & Cost Monitoring" + Set up a monitoring system to track your API usage and costs. + + ```python + def log_api_usage(api_call_type, tokens_used, cost_estimate): + """Log API usage for monitoring.""" + with open("api_usage_log.csv", "a") as f: + timestamp = datetime.now().isoformat() + f.write(f"{timestamp},{api_call_type},{tokens_used},{cost_estimate}\n") + + def estimate_cost(tokens): + """Estimate cost based on token usage.""" + # Example pricing: $0.002 per 1K tokens (adjust according to current pricing) + return (tokens / 1000) * 0.002 + + def run_agent_with_logging(agent_config, task): + """Run agent and log usage.""" + result = run_single_agent(agent_config, task) + + if "usage" in result: + total_tokens = result["usage"]["total_tokens"] + cost = estimate_cost(total_tokens) + log_api_usage("single_agent", total_tokens, cost) + + return result + ``` -#### Using Dictionaries +## FAQ -Tools can be represented as dictionaries, providing maximum flexibility. This method is useful when the tool's functionality is more dynamic or when integrating with external systems. +??? question "What's the difference between Single Agent and Batch Agent APIs?" + The Single Agent API (`/v1/agent/completions`) runs one agent with one task, while the Batch Agent API (`/v1/agent/batch/completions`) allows running multiple agents with different configurations and tasks in parallel. Use Batch Agent when you need to process multiple independent tasks efficiently. -**Example:** +??? question "How do I choose the right model for my agent?" + Model selection depends on your task complexity, performance requirements, and budget: + + | Model | Best For | Characteristics | + |-------|----------|-----------------| + | gpt-4o | Complex analysis, creative tasks | Highest quality, most expensive | + | gpt-4o-mini | General purpose tasks | Good balance of quality and cost | + | openai/o3-mini | Simple, factual tasks | Fast, economical | + + For exploratory work, start with gpt-4o-mini and adjust based on results. -```python -basic_tool_schema = { - "name": "basic_tax_tool", - "description": "A basic tax calculation tool", - "parameters": { - "type": "object", - "properties": { - "income": {"type": "number", "description": "Income amount"} - }, - "required": ["income"] - } -} +??? question "What should I include in my system prompt?" + A good system prompt should include: + + 1. **Role definition**: Who the agent is and their expertise + 2. **Task instructions**: Specific, clear directions on what to do + 3. **Output format**: How results should be structured + 4. **Constraints**: Any limitations or requirements + 5. **Examples**: Sample inputs and outputs when helpful + + Keep prompts focused and avoid contradictory instructions. -def basic_tax_tool(income: float) -> dict: - tax_rate = 0.2 - tax = income * tax_rate - return {"income": income, "tax": tax} -``` +??? question "How can I optimize costs when using the Agent API?" + Cost optimization strategies include: + + - Use the appropriate model for your task complexity + - Set reasonable token limits based on expected output length + - Implement caching for repeated or similar requests + - Batch related requests together + - Use `max_loops: 1` unless you specifically need iterative refinement + - Monitor usage patterns and adjust configurations accordingly -### Tool Registration +??? question "What's the maximum number of agents I can run in a batch?" + While there's no hard limit specified, we recommend keeping batch sizes under 20 agents for optimal performance. For very large batches, consider splitting them into multiple calls or contacting support for guidance on handling high-volume processing. -Tools need to be registered with the agent for it to utilize them. This can be done by specifying the tools in the `tools` parameter during agent initialization. +??? question "How do I handle rate limiting?" + Implement exponential backoff in your error handling: + + ```python + import time + + def run_with_backoff(func, max_retries=5, initial_delay=1): + """Run a function with exponential backoff retry logic.""" + retries = 0 + delay = initial_delay + + while retries < max_retries: + try: + return func() + except requests.exceptions.HTTPError as e: + if e.response.status_code == 429: # Too Many Requests + retry_after = int(e.response.headers.get('Retry-After', delay)) + print(f"Rate limited. Retrying after {retry_after} seconds...") + time.sleep(retry_after) + retries += 1 + delay *= 2 # Exponential backoff + else: + raise + except Exception as e: + raise + + raise Exception(f"Failed after {max_retries} retries") + ``` -**Example:** +??? question "Can I use tools with my agents?" + Yes, you can enable tools through the `tools_dictionary` parameter in your agent configuration. This allows agents to access external functionality like web searches, calculations, or custom tools. + + ```python + agent_config = { + # Other configuration... + "tools_dictionary": [ + { + "name": "web_search", + "description": "Search the web for current information", + "parameters": { + "query": { + "type": "string", + "description": "The search query" + } + } + } + ] + } + ``` -```python -from swarms import Agent -from llama_hosted import llama3Hosted +??? question "How do I debug agent performance issues?" + Debugging steps for agent performance issues: + + 1. **Check system prompts**: Ensure they're clear and not overly restrictive + 2. **Review model selection**: Try a more capable model if output quality is poor + 3. **Adjust token limits**: Increase max_tokens if outputs are getting truncated + 4. **Examine temperature**: Lower for more deterministic outputs, higher for creativity + 5. **Test with simpler tasks**: Isolate whether the issue is with the task complexity + 6. **Enable verbose logging**: Add detailed logging to track request/response cycles + 7. **Contact support**: For persistent issues, reach out with example payloads and responses -# Define Pydantic BaseModels for accounting tasks -class CalculateTax(BaseModel): - income: float +??? question "What's the pricing model for the Agent API?" + The Agent API uses a token-based pricing model: + + 1. **Input tokens**: Text sent to the API (task, system prompts) + 2. **Output tokens**: Text generated by the agent + + Pricing varies by model and is calculated per 1,000 tokens. Check the [pricing page](https://swarms.world/platform/pricing) for current rates. + + The API also offers a "flex" tier for lower-priority, cost-effective processing. -class GenerateInvoice(BaseModel): - client_name: str - amount: float - date: str +## Further Resources -class SummarizeExpenses(BaseModel): - expenses: list[dict] +[:material-file-document: Swarms.ai Documentation](https://docs.swarms.world){ .md-button } +[:material-application: Swarms.ai Platform](https://swarms.world/platform){ .md-button } +[:material-key: API Key Management](https://swarms.world/platform/api-keys){ .md-button } +[:material-forum: Swarms.ai Community](https://discord.gg/jM3Z6M9uMq){ .md-button } -# Define tool functions using these models -def calculate_tax(data: CalculateTax) -> dict: - tax_rate = 0.3 - tax = data.income * tax_rate - return {"income": data.income, "tax": tax} +-------------------------------------------------- -def generate_invoice(data: GenerateInvoice) -> dict: - invoice = { - "client_name": data.client_name, - "amount": data.amount, - "date": data.date, - "invoice_id": "INV12345" - } - return invoice +# File: swarms_cloud\api_clients.md -def summarize_expenses(data: SummarizeExpenses) -> dict: - total_expenses = sum(expense['amount'] for expense in data.expenses) - return {"total_expenses": total_expenses} +# Swarms API Clients -# Function to generate a tool schema for demonstration purposes -def create_tool_schema(): - return { - "name": "execute", - "description": "Executes code on the user's machine", - "parameters": { - "type": "object", - "properties": { - "language": { - "type": "string", - "description": "Programming language", - "enum": ["python", "java"] - }, - "code": {"type": "string", "description": "Code to execute"} - }, - "required": ["language", "code"] - } - } +*Production-Ready Client Libraries for Every Programming Language* -# Initialize the agent with the tools -agent = Agent( - agent_name="Accounting Agent", - system_prompt="This agent assists with various accounting tasks.", - sop_list=["Provide accurate and timely accounting services."], - llm=llama3Hosted(), - max_loops="auto", - interactive=True, - verbose=True, - tool_schema=BaseModel, - list_base_models=[ - CalculateTax, - GenerateInvoice, - SummarizeExpenses - ], - output_type=str, - metadata_output_type="json", - function_calling_format_type="OpenAI", - function_calling_type="json", - tools=[ - calculate_tax, - generate_invoice, - summarize_expenses - ], - list_base_models_json=create_tool_schema(), -) -``` +## Overview -### Running the Agent +The Swarms API provides official client libraries across multiple programming languages, enabling developers to integrate powerful multi-agent AI capabilities into their applications with ease. Our clients are designed for production use, featuring robust error handling, comprehensive documentation, and seamless integration with existing codebases. -The agent can execute tasks using the `run` method. This method takes a prompt and determines the appropriate tool to use based on the input. +Whether you're building enterprise applications, research prototypes, or innovative AI products, our client libraries provide the tools you need to harness the full power of the Swarms platform. -**Example:** +## Available Clients -```python -# Example task: Calculate tax for an income -result = agent.run("Calculate the tax for an income of $50,000.") -print(f"Result: {result}") +| Language | Status | Repository | Documentation | Description | +|----------|--------|------------|---------------|-------------| +| **Python** | ✅ **Available** | [swarms-sdk](https://github.com/The-Swarm-Corporation/swarms-sdk) | [Docs](https://docs.swarms.world/en/latest/swarms_cloud/python_client/) | Production-grade Python client with comprehensive error handling, retry logic, and extensive examples | +| **TypeScript/Node.js** | ✅ **Available** | [swarms-ts](https://github.com/The-Swarm-Corporation/swarms-ts) | 📚 *Coming Soon* | Modern TypeScript client with full type safety, Promise-based API, and Node.js compatibility | +| **Go** | ✅ **Available** | [swarms-client-go](https://github.com/The-Swarm-Corporation/swarms-client-go) | 📚 *Coming Soon* | High-performance Go client optimized for concurrent operations and microservices | +| **Java** | ✅ **Available** | [swarms-java](https://github.com/The-Swarm-Corporation/swarms-java) | 📚 *Coming Soon* | Enterprise Java client with Spring Boot integration and comprehensive SDK features | +| **Kotlin** | 🚧 **Coming Soon** | *In Development* | 📚 *Coming Soon* | Modern Kotlin client with coroutines support and Android compatibility | +| **Ruby** | 🚧 **Coming Soon** | *In Development* | 📚 *Coming Soon* | Elegant Ruby client with Rails integration and gem packaging | +| **Rust** | 🚧 **Coming Soon** | *In Development* | 📚 *Coming Soon* | Ultra-fast Rust client with memory safety and zero-cost abstractions | +| **C#/.NET** | 🚧 **Coming Soon** | *In Development* | 📚 *Coming Soon* | .NET client with async/await support and NuGet packaging | -# Example task: Generate an invoice -invoice_data = agent.run("Generate an invoice for John Doe for $1500 on 2024-06-01.") -print(f"Invoice Data: {invoice_data}") +## Client Features -# Example task: Summarize expenses -expenses = [ - {"amount": 200.0, "description": "Office supplies"}, - {"amount": 1500.0, "description": "Software licenses"}, - {"amount": 300.0, "description": "Travel expenses"} -] -summary = agent.run("Summarize these expenses: " + str(expenses)) -print(f"Expenses Summary: {summary}") -``` +All Swarms API clients are built with the following enterprise-grade features: +### 🔧 **Core Functionality** -### Customizing Tools +| Feature | Description | +|------------------------|--------------------------------------------------------------------| +| **Full API Coverage** | Complete access to all Swarms API endpoints | +| **Type Safety** | Strongly-typed interfaces for all request/response objects | +| **Error Handling** | Comprehensive error handling with detailed error messages | +| **Retry Logic** | Automatic retries with exponential backoff for transient failures | -Custom tools can be created to extend the functionality of the Swarms framework. This can include integrating external APIs, performing complex calculations, or handling specialized data formats. +--- -**Example: Custom Accounting Tool** +### 🚀 **Performance & Reliability** -```python -from pydantic import BaseModel +| Feature | Description | +|--------------------------|--------------------------------------------------------------------| +| **Connection Pooling** | Efficient HTTP connection management | +| **Rate Limiting** | Built-in rate limit handling and backoff strategies | +| **Timeout Configuration**| Configurable timeouts for different operation types | +| **Streaming Support** | Real-time streaming for long-running operations | -class CustomAccountingTool(BaseModel): - data: dict +--- -def custom_accounting_tool(data: CustomAccountingTool) -> dict: - # Custom logic for the accounting tool - result = { - "status": "success", - "data_processed": len(data.data) - } - return result +### 🛡️ **Security & Authentication** -# Register the custom tool with the agent -agent = Agent( - agent_name="Accounting Agent", - system_prompt="This agent assists with various accounting tasks.", - sop_list=["Provide accurate and timely accounting services."], - llm=llama3Hosted(), - max_loops="auto", - interactive=True, - verbose=True, - tool_schema=BaseModel, - list_base_models=[ - CalculateTax, - GenerateInvoice, - SummarizeExpenses, - CustomAccountingTool - ], - output_type=str, - metadata_output_type="json", - function_calling_format_type="OpenAI", - function_calling_type="json", - tools=[ - calculate_tax, - generate_invoice, - summarize_expenses, - custom_accounting_tool - ], - list_base_models_json=create_tool_schema(), -) -``` +| Feature | Description | +|------------------------|--------------------------------------------------------------------| +| **API Key Management** | Secure API key handling and rotation | +| **TLS/SSL** | End-to-end encryption for all communications | +| **Request Signing** | Optional request signing for enhanced security | +| **Environment Configuration** | Secure environment-based configuration | -### Advanced Customization +--- -Advanced customization involves modifying the core components of the Swarms framework. This includes extending existing classes, adding new methods, or integrating third-party libraries. +### 📊 **Monitoring & Debugging** -**Example: Extending the Agent Class** +| Feature | Description | +|----------------------------|--------------------------------------------------------------------| +| **Comprehensive Logging** | Detailed logging for debugging and monitoring | +| **Request/Response Tracing** | Full request/response tracing capabilities | +| **Metrics Integration** | Built-in metrics for monitoring client performance | +| **Debug Mode** | Enhanced debugging features for development | -```python -from swarms import Agent -class AdvancedAccountingAgent(Agent): - def __init__(self, *args, **kwargs): - super().__init__(*args, **kwargs) +## Client-Specific Features - def custom_behavior(self): - print("Executing custom behavior") +### Python Client - def another_custom_method(self): - print("Another +| Feature | Description | +|------------------------|----------------------------------------------------------| +| **Async Support** | Full async/await support with `asyncio` | +| **Pydantic Integration** | Type-safe request/response models | +| **Context Managers** | Resource management with context managers | +| **Rich Logging** | Integration with Python's `logging` module | - custom method") +--- -# Initialize the advanced agent -advanced_agent = AdvancedAccountingAgent( - agent_name="Advanced Accounting Agent", - system_prompt="This agent performs advanced accounting tasks.", - sop_list=["Provide advanced accounting services."], - llm=llama3Hosted(), - max_loops="auto", - interactive=True, - verbose=True, - tool_schema=BaseModel, - list_base_models=[ - CalculateTax, - GenerateInvoice, - SummarizeExpenses, - CustomAccountingTool - ], - output_type=str, - metadata_output_type="json", - function_calling_format_type="OpenAI", - function_calling_type="json", - tools=[ - calculate_tax, - generate_invoice, - summarize_expenses, - custom_accounting_tool - ], - list_base_models_json=create_tool_schema(), -) +### TypeScript/Node.js Client -# Call custom methods -advanced_agent.custom_behavior() -advanced_agent.another_custom_method() -``` +| Feature | Description | +|------------------------|----------------------------------------------------------| +| **TypeScript First** | Built with TypeScript for maximum type safety | +| **Promise-Based** | Modern Promise-based API with async/await | +| **Browser Compatible** | Works in both Node.js and modern browsers | +| **Zero Dependencies** | Minimal dependency footprint | -### Integrating External Libraries +--- -You can integrate external libraries to extend the functionality of your tools. This is useful for adding new capabilities or leveraging existing libraries for complex tasks. +### Go Client -**Example: Integrating Pandas for Data Processing** +| Feature | Description | +|------------------------|----------------------------------------------------------| +| **Context Support** | Full context.Context support for cancellation | +| **Structured Logging** | Integration with structured logging libraries | +| **Concurrency Safe** | Thread-safe design for concurrent operations | +| **Minimal Allocation** | Optimized for minimal memory allocation | -```python -import pandas as pd -from pydantic import BaseModel +--- -class DataFrameTool(BaseModel): - data: list[dict] +### Java Client -def process_data_frame(data: DataFrameTool) -> dict: - df = pd.DataFrame(data.data) - summary = df.describe().to_dict() - return {"summary": summary} +| Feature | Description | +|------------------------|----------------------------------------------------------| +| **Spring Boot Ready** | Built-in Spring Boot auto-configuration | +| **Reactive Support** | Optional reactive streams support | +| **Enterprise Features**| JMX metrics, health checks, and more | +| **Maven & Gradle** | Available on Maven Central | -# Register the tool with the agent -agent = Agent( - agent_name="Data Processing Agent", - system_prompt="This agent processes data frames.", - sop_list=["Provide data processing services."], - llm=llama3Hosted(), - max_loops="auto", - interactive=True, - verbose=True, - tool_schema=BaseModel, - list_base_models=[DataFrameTool], - output_type=str, - metadata_output_type="json", - function_calling_format_type="OpenAI", - function_calling_type="json", - tools=[process_data_frame], - list_base_models_json=create_tool_schema(), -) +## Advanced Configuration -# Example task: Process a data frame -data = [ - {"col1": 1, "col2": 2}, - {"col1": 3, "col2": 4}, - {"col1": 5, "col2": 6} -] -result = agent.run("Process this data frame: " + str(data)) -print(f"Data Frame Summary: {result}") +### Environment Variables + +All clients support standard environment variables for configuration: + +```bash +# API Configuration +SWARMS_API_KEY=your_api_key_here +SWARMS_BASE_URL=https://api.swarms.world + +# Client Configuration +SWARMS_TIMEOUT=60 +SWARMS_MAX_RETRIES=3 +SWARMS_LOG_LEVEL=INFO ``` -## Conclusion +## Community & Support -The Swarms Tool System provides a robust and flexible framework for defining and utilizing tools within agents. By leveraging Pydantic BaseModels, functions, and dictionaries, developers can create highly customized tools to perform a wide range of tasks. The extensive customization options allow for the integration of external libraries and the extension of core components, making the Swarms framework suitable for diverse applications. +### 📚 **Documentation & Resources** -This guide has covered the fundamental concepts and provided detailed examples to help you get started with the Swarms Tool System. With this foundation, you can explore and implement advanced features to build powerful +| Resource | Link | +|-----------------------------|----------------------------------------------------------------------------------------| +| Complete API Documentation | [View Docs](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/) | +| Python Client Docs | [View Docs](https://docs.swarms.world/en/latest/swarms_cloud/python_client/) | +| API Examples & Tutorials | [View Examples](https://docs.swarms.world/en/latest/examples/) | --------------------------------------------------- +--- -# File: swarms/tools/tool_storage.md +### 💬 **Community Support** -# ToolStorage +| Community Channel | Description | Link | +|-----------------------------|---------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------| +| Discord Community | Join our active developer community for real-time support and discussions | [Join Discord](https://discord.gg/jM3Z6M9uMq) | +| GitHub Discussions | Ask questions and share ideas | [GitHub Discussions](https://github.com/The-Swarm-Corporation/swarms/discussions) | +| Twitter/X | Follow for updates and announcements | [Twitter/X](https://x.com/swarms_corp) | +--- -The `ToolStorage` module provides a structured and efficient way to manage and utilize various tool functions. It is designed to store tool functions, manage settings, and ensure smooth registration and retrieval of tools. This module is particularly useful in applications that require dynamic management of a collection of functions, such as plugin systems, modular software, or any application where functions need to be registered and called dynamically. +### 🐛 **Issue Reporting & Contributions** -## Class: ToolStorage +| Contribution Area | Description | Link | +|-----------------------------|---------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------| +| Report Bugs | Help us improve by reporting issues | [Report Bugs](https://github.com/The-Swarm-Corporation/swarms/issues) | +| Feature Requests | Suggest new features and improvements | [Feature Requests](https://github.com/The-Swarm-Corporation/swarms/issues) | +| Contributing Guide | Learn how to contribute to the project | [Contributing Guide](https://docs.swarms.world/en/latest/contributors/main/) | -The `ToolStorage` class is the core component of the module. It provides functionalities to add, retrieve, and list tool functions as well as manage settings. +--- -### Attributes +### 📧 **Direct Support** -| Attribute | Type | Description | -|------------|--------------------|-----------------------------------------------------------------------| -| `verbose` | `bool` | A flag to enable verbose logging. | -| `tools` | `List[Callable]` | A list of tool functions. | -| `_tools` | `Dict[str, Callable]` | A dictionary that stores the tools, where the key is the tool name and the value is the tool function. | -| `_settings`| `Dict[str, Any]` | A dictionary that stores the settings, where the key is the setting name and the value is the setting value. | +| Support Type | Contact Information | +|-----------------------------|---------------------------------------------------------------------------------------| +| Support Call | [Book a call](https://cal.com/swarms/swarms-technical-support?overlayCalendar=true) | +| Enterprise Support | Contact us for dedicated enterprise support options | -### Methods -#### `__init__` +## Contributing to Client Development -Initializes the `ToolStorage` instance. +We welcome contributions to all our client libraries! Here's how you can help: +### 🛠️ **Development** -| Parameter | Type | Default | Description | -|------------|-------------------|---------|------------------------------------------------------------| -| `verbose` | `bool` | `None` | A flag to enable verbose logging. | -| `tools` | `List[Callable]` | `None` | A list of tool functions to initialize the storage with. | -| `*args` | `tuple` | `None` | Additional positional arguments. | -| `**kwargs` | `dict` | `None` | Additional keyword arguments. | +| Task | Description | +|-----------------------------------------|--------------------------------------------------| +| Implement new features and endpoints | Add new API features and expand client coverage | +| Improve error handling and retry logic | Enhance robustness and reliability | +| Add comprehensive test coverage | Ensure code quality and prevent regressions | +| Optimize performance and memory usage | Improve speed and reduce resource consumption | -#### `add_tool` +--- -Adds a tool to the storage. +### 📝 **Documentation** -| Parameter | Type | Description | -|-----------|----------|------------------------------| -| `func` | `Callable` | The tool function to be added. | +| Task | Description | +|-----------------------------|-----------------------------------------------------| +| Write tutorials and examples | Create guides and sample code for users | +| Improve API documentation | Clarify and expand reference docs | +| Create integration guides | Help users connect clients to their applications | +| Translate documentation | Make docs accessible in multiple languages | -**Raises:** -- `ValueError`: If a tool with the same name already exists. +--- -#### `get_tool` +### 🧪 **Testing** -Retrieves a tool by its name. +| Task | Description | +|-------------------------------|-----------------------------------------------------| +| Add unit and integration tests | Test individual components and end-to-end flows | +| Test with different language versions | Ensure compatibility across environments | +| Performance benchmarking | Measure and optimize speed and efficiency | +| Security testing | Identify and fix vulnerabilities | -| Parameter | Type | Description | -|-----------|--------|-------------------------------| -| `name` | `str` | The name of the tool to retrieve. | +--- -**Returns:** -- `Callable`: The tool function. +### 📦 **Packaging** -**Raises:** -- `ValueError`: If no tool with the given name is found. +| Task | Description | +|-------------------------------|-----------------------------------------------------| +| Package managers (npm, pip, Maven, etc.) | Publish to popular package repositories | +| Distribution optimization | Streamline builds and reduce package size | +| Version management | Maintain clear versioning and changelogs | +| Release automation | Automate build, test, and deployment pipelines | -#### `set_setting` +## Enterprise Features -Sets a setting in the storage. +For enterprise customers, we offer additional features and support: +### 🏢 **Enterprise Client Features** -| Parameter | Type | Description | -|-----------|--------|--------------------------| -| `key` | `str` | The key for the setting. | -| `value` | `Any` | The value for the setting. | +| Feature | Description | +|--------------------------|----------------------------------------------------------------| +| **Priority Support** | Dedicated support team with SLA guarantees | +| **Custom Integrations** | Tailored integrations for your specific needs | +| **On-Premises Deployment** | Support for on-premises or private cloud deployments | +| **Advanced Security** | Enhanced security features and compliance support | +| **Training & Onboarding**| Comprehensive training for your development team | -#### `get_setting` +### 📞 **Contact Enterprise Sales** -Gets a setting from the storage. +| Contact Type | Details | +|----------------|-----------------------------------------------------------------------------------------| +| **Sales** | [kye@swarms.world](mailto:kye@swarms.world) | +| **Schedule Demo** | [Book a Demo](https://cal.com/swarms/swarms-technical-support?overlayCalendar=true) | +| **Partnership**| [kye@swarms.world](mailto:kye@swarms.world) | -| Parameter | Type | Description | -|-----------|--------|--------------------------| -| `key` | `str` | The key for the setting. | +--- -**Returns:** -- `Any`: The value of the setting. +*Ready to build the future with AI agents? Start with any of our client libraries and join our growing community of developers building the next generation of intelligent applications.* -**Raises:** -- `KeyError`: If the setting is not found. +-------------------------------------------------- -#### `list_tools` +# File: swarms_cloud\api_pricing.md -Lists all registered tools. +# Swarm Agent API Pricing -**Returns:** -- `List[str]`: A list of tool names. +!!! success "🎉 Get Started with $20 Free Credits!" + New users receive $20 in free credits when they sign up! [Create your account now](https://swarms.world/platform/account) to start building with our powerful multi-agent platform. -## Decorator: tool_registry +!!! abstract "Overview" + The Swarm Agent API provides a powerful platform for managing multi-agent collaboration at scale and orchestrating swarms of LLM agents in the cloud. Our pricing model is designed to be transparent and cost-effective, enabling you to harness the full potential of your agents with ease. -The `tool_registry` decorator registers a function as a tool in the storage. +## Credit System -| Parameter | Type | Description | -|-----------|----------------|----------------------------------| -| `storage` | `ToolStorage` | The storage instance to register the tool in. | +The Swarm API operates on a credit-based system with the following characteristics: -**Returns:** -- `Callable`: The decorator function. +- **Credits** are the currency used within the platform -## Usage Examples +- 1 credit = $1 USD +- Credits can be purchased with USD or $swarms Solana tokens -### Full Example -```python -from swarms import ToolStorage, tool_registry +### Credit Types -storage = ToolStorage() +| Type | Description | Expiration | +|------|-------------|------------| +| Standard Credits | Purchased credits | Never expires | +| Free Credits | Promotional credits | May have expiration dates | +## Pricing Structure -# Example usage -@tool_registry(storage) -def example_tool(x: int, y: int) -> int: - """ - Example tool function that adds two numbers. +### Base Costs - Args: - x (int): The first number. - y (int): The second number. +| Cost Component | Price | +|----------------|-------| +| Base cost per agent | $0.01 per agent | - Returns: - int: The sum of the two numbers. - """ - return x + y +### Token Usage Costs + +| Token Type | Cost | +|------------|------| +| Input tokens | $2.00 per 1M tokens | +| Output tokens | $4.50 per 1M tokens | + +### Night-Time Discount + +!!! tip "Off-Peak Hours Discount" + To encourage efficient resource usage during off-peak hours, we offer significant discounts for operations performed during California night-time hours: + | Time Period (Pacific Time) | Discount | + |----------------------------|----------| + | 8:00 PM to 6:00 AM | 75% off token costs | -# Query all the tools and get the example tool -print(storage.list_tools()) # Should print ['example_tool'] -# print(storage.get_tool('example_tool')) # Should print +## Cost Calculation -# Find the tool by names and call it -print(storage.get_tool("example_tool")) # Should print 5 +### Formula +The total cost for a swarm execution is calculated as follows: -# Test the storage and querying -if __name__ == "__main__": - print(storage.list_tools()) # Should print ['example_tool'] - print(storage.get_tool("example_tool")) # Should print 5 - storage.set_setting("example_setting", 42) - print(storage.get_setting("example_setting")) # Should print 42 +```math +Total Cost = (Number of Agents × $0.01) + + (Total Input Tokens / 1M × $2.00 × Number of Agents) + + (Total Output Tokens / 1M × $4.50 × Number of Agents) +``` +With night-time discount applied: +```math +Input Token Cost = Input Token Cost × 0.25 +Output Token Cost = Output Token Cost × 0.25 ``` +### Example Scenarios -### Basic Usage +#### Scenario 1: Basic Workflow (Day-time) -#### Example 1: Initializing ToolStorage and Adding a Tool +!!! example "Basic Workflow Example" + **Parameters:** + + - 3 agents + + - 10,000 input tokens total + + - 25,000 output tokens total -```python -from swarms.tools.tool_registry import ToolStorage, tool_registry + **Calculation:** + + - Agent cost: 3 × $0.01 = $0.03 + + - Input token cost: (10,000 / 1,000,000) × $2.00 × 3 = $0.06 + + - Output token cost: (25,000 / 1,000,000) × $4.50 × 3 = $0.3375 + + - **Total cost: $0.4275** -# Initialize ToolStorage -storage = ToolStorage() +#### Scenario 2: Complex Workflow (Night-time) -# Define a tool function -@tool_registry(storage) -def add_numbers(x: int, y: int) -> int: - return x + y +!!! example "Complex Workflow Example" + **Parameters:** + + - 5 agents + + - 50,000 input tokens total + + - 125,000 output tokens total -# List tools -print(storage.list_tools()) # Output: ['add_numbers'] + **Calculation:** + + - Agent cost: 5 × $0.01 = $0.05 + + - Input token cost: (50,000 / 1,000,000) × $2.00 × 5 × 0.25 = $0.125 + + - Output token cost: (125,000 / 1,000,000) × $4.50 × 5 × 0.25 = $0.703125 + + - **Total cost: $0.878125** -# Retrieve and use the tool -add_tool = storage.get_tool('add_numbers') -print(add_tool(5, 3)) # Output: 8 -``` +## Purchasing Credits -### Advanced Usage +Credits can be purchased through our platform in two ways: -#### Example 2: Managing Settings +### USD Payment -```python -# Set a setting -storage.set_setting('max_retries', 5) +- Available through our [account page](https://swarms.world/platform/account) -# Get a setting -max_retries = storage.get_setting('max_retries') -print(max_retries) # Output: 5 -``` +- Secure payment processing -### Error Handling +- Minimum purchase: $10 -#### Example 3: Handling Errors in Tool Retrieval +### $swarms Token Payment -```python -try: - non_existent_tool = storage.get_tool('non_existent') -except ValueError as e: - print(e) # Output: No tool found with name: non_existent -``` +- Use Solana-based $swarms tokens -#### Example 4: Handling Duplicate Tool Addition +- Tokens can be purchased on supported exchanges -```python -try: - @tool_registry(storage) - def add_numbers(x: int, y: int) -> int: - return x + y -except ValueError as e: - print(e) # Output: Tool with name add_numbers already exists. -``` +- Connect your Solana wallet on our [account page](https://swarms.world/platform/account) -## Conclusion +## Free Credits -The `ToolStorage` module provides a robust solution for managing tool functions and settings. Its design allows for easy registration, retrieval, and management of tools, making it a valuable asset in various applications requiring dynamic function handling. The inclusion of detailed logging ensures that the operations are transparent and any issues can be quickly identified and resolved. +!!! info "Free Credit Program" + We occasionally offer free credits to: + + - New users (welcome bonus) + + - During promotional periods + + - For educational and research purposes --------------------------------------------------- + **Important Notes:** + + - Used before standard credits + + - May have expiration dates + + - May have usage restrictions -# File: swarms/ui/main.md +## Billing and Usage Tracking -# Swarms Chat UI Documentation +Track your credit usage through our comprehensive logging and reporting features: -The Swarms Chat interface provides a customizable, multi-agent chat experience using Gradio. It supports various specialized AI agents—from finance to healthcare and news analysis—by leveraging Swarms models. +### API Logs +- Access detailed logs via the `/v1/swarm/logs` endpoint ---- +- View cost breakdowns for each execution -## Table of Contents +### Dashboard +- Real-time credit balance display -1. [Installation](#installation) -2. [Quick Start](#quick-start) -3. [Parameters Overview](#parameters-overview) -4. [Specialized Agents](#specialized-agents) - - [Finance Agents](#finance-agents) - - [Healthcare Agents](#healthcare-agents) - - [News & Research Agents](#news--research-agents) -5. [Swarms Integration Features](#swarms-integration-features) -6. [Usage Examples](#usage-examples) - - [Finance Agent Example](#finance-agent-example) - - [Healthcare Agent Example](#healthcare-agent-example) - - [News Analysis Agent Example](#news-analysis-agent-example) -7. [Setup and Deployment](#setup-and-deployment) -8. [Best Practices](#best-practices) -9. [Notes](#notes) +- Historical usage graphs ---- +- Detailed cost analysis -## Installation +- Available at [https://swarms.world/platform/dashboard](https://swarms.world/platform/dashboard) -Make sure you have Python 3.7+ installed, then install the required packages using pip: +## FAQ -```bash -pip install gradio ai-gradio swarms -``` +??? question "Is there a minimum credit purchase?" + Yes, the minimum credit purchase is $10 USD equivalent. ---- +??? question "Do credits expire?" + Standard credits do not expire. Free promotional credits may have expiration dates. -## Quick Start +??? question "How is the night-time discount applied?" + The system automatically detects the execution time based on Pacific Time (America/Los_Angeles) and applies a 75% discount to token costs for executions between 8:00 PM and 6:00 AM. -Below is a minimal example to get the Swarms Chat interface up and running. Customize the agent, title, and description as needed. +??? question "What happens if I run out of credits during execution?" + Executions will fail with a 402 Payment Required error if sufficient credits are not available. We recommend maintaining a credit balance appropriate for your usage patterns. -```python -import gradio as gr -import ai_gradio +??? question "Can I get a refund for unused credits?" + Please contact our support team for refund requests for unused credits. -# Create and launch a Swarms Chat interface -gr.load( - name='swarms:gpt-4-turbo', # Model identifier (supports OpenAI and others) - src=ai_gradio.registry, # Source module for model configurations - agent_name="Stock-Analysis-Agent", # Example agent from Finance category - title='Swarms Chat', - description='Chat with an AI agent powered by Swarms' -).launch() -``` +??? question "Are there volume discounts available?" + Yes, please contact our sales team for enterprise pricing and volume discounts. + +## References + +- [Swarm API Documentation](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/) +- [Account Management Portal](https://swarms.world/platform/account) +- [Swarm Types Reference](https://docs.swarms.world/swarms_cloud/swarm_types) --- -## Parameters Overview +!!! info "Need Help?" + For additional questions or custom pricing options, please contact our support team at [kye@swarms.world](mailto:kye@swarms.world). -When configuring your interface, consider the following parameters: +-------------------------------------------------- -- **`name` (str):** - Model identifier (e.g., `'swarms:gpt-4-turbo'`) that specifies which Swarms model to use. +# File: swarms_cloud\best_practices.md -- **`src` (module):** - The source module (typically `ai_gradio.registry`) that contains model configurations. +# Swarms API Best Practices Guide -- **`agent_name` (str):** - The name of the specialized agent you wish to use (e.g., "Stock-Analysis-Agent"). +This comprehensive guide outlines production-grade best practices for using the Swarms API effectively. Learn how to choose the right swarm architecture, optimize costs, and implement robust error handling. -- **`title` (str):** - The title that appears at the top of the web interface. +## Quick Reference Cards -- **`description` (str):** - A short summary describing the functionality of the chat interface. +=== "Swarm Types" + + !!! info "Available Swarm Architectures" + + | Swarm Type | Best For | Use Cases | + |------------|----------|------------| + | `AgentRearrange` | Dynamic workflows | - Complex task decomposition
- Adaptive processing
- Multi-stage analysis
- Dynamic resource allocation | + | `MixtureOfAgents` | Diverse expertise | - Cross-domain problems
- Comprehensive analysis
- Multi-perspective tasks
- Research synthesis | + | `SpreadSheetSwarm` | Data processing | - Financial analysis
- Data transformation
- Batch calculations
- Report generation | + | `SequentialWorkflow` | Linear processes | - Document processing
- Step-by-step analysis
- Quality control
- Content pipeline | + | `ConcurrentWorkflow` | Parallel tasks | - Batch processing
- Independent analyses
- High-throughput needs
- Multi-market analysis | + | `GroupChat` | Collaborative solving | - Brainstorming
- Decision making
- Problem solving
- Strategy development | + | `MultiAgentRouter` | Task distribution | - Load balancing
- Specialized processing
- Resource optimization
- Service routing | + | `AutoSwarmBuilder` | Automated setup | - Quick prototyping
- Simple tasks
- Testing
- MVP development | + | `HiearchicalSwarm` | Complex organization | - Project management
- Research analysis
- Enterprise workflows
- Team automation | + | `MajorityVoting` | Consensus needs | - Quality assurance
- Decision validation
- Risk assessment
- Content moderation | ---- +=== "Application Patterns" + + !!! tip "Specialized Application Configurations" + + | Application | Recommended Swarm | Benefits | + |------------|-------------------|-----------| + | **Team Automation** | `HiearchicalSwarm` | - Automated team coordination
- Clear responsibility chain
- Scalable team structure | + | **Research Pipeline** | `SequentialWorkflow` | - Structured research process
- Quality control at each stage
- Comprehensive output | + | **Trading System** | `ConcurrentWorkflow` | - Multi-market coverage
- Real-time analysis
- Risk distribution | + | **Content Factory** | `MixtureOfAgents` | - Automated content creation
- Consistent quality
- High throughput | -## Specialized Agents +=== "Cost Optimization" -Swarms Chat supports multiple specialized agents designed for different domains. Below is an overview of available agent types. + !!! tip "Advanced Cost Management Strategies" + + | Strategy | Implementation | Impact | + |----------|----------------|---------| + | Batch Processing | Group related tasks | 20-30% cost reduction | + | Off-peak Usage | Schedule for 8 PM - 6 AM PT | 15-25% cost reduction | + | Token Optimization | Precise prompts, focused tasks | 10-20% cost reduction | + | Caching | Store reusable results | 30-40% cost reduction | + | Agent Optimization | Use minimum required agents | 15-25% cost reduction | + | Smart Routing | Route to specialized agents | 10-15% cost reduction | + | Prompt Engineering | Optimize input tokens | 15-20% cost reduction | + | Flex Processing | Use flex tier for non-urgent tasks | 75% cost reduction | -### Finance Agents +=== "Service Tiers" -1. **Stock Analysis Agent** - - **Capabilities:** - - Market analysis and stock recommendations. - - Both technical and fundamental analysis. - - Portfolio management suggestions. + !!! tip "Choosing the Right Service Tier" + + | Tier | Best For | Benefits | Considerations | + |------|----------|----------|----------------| + | Standard | - Real-time processing
- Time-sensitive tasks
- Critical workflows | - Immediate execution
- Higher priority
- Predictable timing | - Higher cost
- 5-min timeout | + | Flex | - Batch processing
- Non-urgent tasks
- Cost-sensitive workloads | - 75% cost reduction
- Longer timeouts
- Auto-retries | - Variable timing
- Resource contention | -2. **Tax Planning Agent** - - **Capabilities:** - - Tax optimization strategies. - - Deduction analysis. - - Guidance on tax law compliance. +=== "Industry Solutions" -### Healthcare Agents + !!! example "Industry-Specific Swarm Patterns" + + | Industry | Use Case | Applications | + |----------|----------|--------------| + | **Finance** | Automated trading desk | - Portfolio management
- Risk assessment
- Market analysis
- Trading execution | + | **Healthcare** | Clinical workflow automation | - Patient analysis
- Diagnostic support
- Treatment planning
- Follow-up care | + | **Legal** | Legal document processing | - Document review
- Case analysis
- Contract review
- Compliance checks | + | **E-commerce** | E-commerce operations | - Product management
- Pricing optimization
- Customer support
- Inventory management | -1. **Medical Diagnosis Assistant** - - **Capabilities:** - - Analysis of symptoms. - - Treatment recommendations. - - Research using current medical literature. +=== "Error Handling" -2. **Healthcare Management Agent** - - **Capabilities:** - - Patient care coordination. - - Organization of medical records. - - Monitoring and tracking treatment plans. + !!! warning "Advanced Error Management Strategies" + + | Error Code | Strategy | Recovery Pattern | + |------------|----------|------------------| + | 400 | Input Validation | Pre-request validation with fallback | + | 401 | Auth Management | Secure key rotation and storage | + | 429 | Rate Limiting | Exponential backoff with queuing | + | 500 | Resilience | Retry with circuit breaking | + | 503 | High Availability | Multi-region redundancy | + | 504 | Timeout Handling | Adaptive timeouts with partial results | -### News & Research Agents +## Choosing the Right Swarm Architecture -1. **News Analysis Agent** - - **Capabilities:** - - Real-time news aggregation. - - Filtering news by topics. - - Trend analysis and insights. +### Decision Framework -2. **Research Assistant** - - **Capabilities:** - - Analysis of academic papers. - - Literature review support. - - Guidance on research methodologies. +Use this framework to select the optimal swarm architecture for your use case: ---- +1. **Task Complexity Analysis** + - Simple tasks → `AutoSwarmBuilder` + - Complex tasks → `HiearchicalSwarm` or `MultiAgentRouter` + - Dynamic tasks → `AgentRearrange` -## Swarms Integration Features +2. **Workflow Pattern** + - Linear processes → `SequentialWorkflow` + - Parallel operations → `ConcurrentWorkflow` + - Collaborative tasks → `GroupChat` -### Core Capabilities +3. **Domain Requirements** + - Multi-domain expertise → `MixtureOfAgents` + - Data processing → `SpreadSheetSwarm` + - Quality assurance → `MajorityVoting` -- **Multi-Agent Collaboration:** Multiple agents can be engaged simultaneously for a coordinated experience. -- **Real-Time Data Processing:** The interface processes and responds to queries in real time. -- **Natural Language Understanding:** Advanced NLP for context-aware and coherent responses. -- **Context-Aware Responses:** Responses are tailored based on conversation context. +### Industry-Specific Recommendations -### Technical Features +=== "Finance" + + !!! example "Financial Applications" + - Risk Analysis: `HiearchicalSwarm` + - Market Research: `MixtureOfAgents` + - Trading Strategies: `ConcurrentWorkflow` + - Portfolio Management: `SpreadSheetSwarm` -- **API Integration Support:** Easily connect with external APIs. -- **Custom Model Selection:** Choose the appropriate model for your specific task. -- **Concurrent Processing:** Supports multiple sessions concurrently. -- **Session Management:** Built-in session management ensures smooth user interactions. +=== "Healthcare" + + !!! example "Healthcare Applications" + - Patient Analysis: `SequentialWorkflow` + - Research Review: `MajorityVoting` + - Treatment Planning: `GroupChat` + - Medical Records: `MultiAgentRouter` ---- +=== "Legal" + + !!! example "Legal Applications" + - Document Review: `SequentialWorkflow` + - Case Analysis: `MixtureOfAgents` + - Compliance Check: `HiearchicalSwarm` + - Contract Analysis: `ConcurrentWorkflow` -## Usage Examples +## Production Best Practices -Below are detailed examples for each type of specialized agent. +### Best Practices Summary -### Finance Agent Example +!!! success "Recommended Patterns" + - Use appropriate swarm types for tasks + - Implement robust error handling + - Monitor and log executions + - Cache repeated results + - Rotate API keys regularly + - Choose appropriate service tier based on task urgency + - Use flex processing for batch and non-urgent tasks -This example configures a chat interface for stock analysis: +!!! danger "Anti-patterns to Avoid" + - Hardcoding API keys + - Ignoring rate limits + - Missing error handling + - Excessive agent count + - Inadequate monitoring + - Using standard tier for non-urgent tasks + - Not implementing retry logic for flex tier -```python -import gradio as gr -import ai_gradio +### Performance Benchmarks -finance_interface = gr.load( - name='swarms:gpt-4-turbo', - src=ai_gradio.registry, - agent_name="Stock-Analysis-Agent", - title='Finance Assistant', - description='Expert financial analysis and advice tailored to your investment needs.' -) -finance_interface.launch() -``` +!!! note "Typical Performance Metrics" + + | Metric | Target Range | Warning Threshold | + |--------|--------------|-------------------| + | Response Time | < 2s (standard)
< 15s (flex) | > 5s (standard)
> 30s (flex) | + | Success Rate | > 99% | < 95% | + | Cost per Task | < $0.05 (standard)
< $0.0125 (flex) | > $0.10 (standard)
> $0.025 (flex) | + | Cache Hit Rate | > 80% | < 60% | + | Error Rate | < 1% | > 5% | + | Retry Rate (flex) | < 10% | > 30% | -### Healthcare Agent Example +### Additional Resources -This example sets up a chat interface for healthcare assistance: +!!! info "Useful Links" + + - [Swarms API Documentation](https://docs.swarms.world) + - [API Dashboard](https://swarms.world/platform/api-keys) -```python -import gradio as gr -import ai_gradio +-------------------------------------------------- -healthcare_interface = gr.load( - name='swarms:gpt-4-turbo', - src=ai_gradio.registry, - agent_name="Medical-Assistant-Agent", - title='Healthcare Assistant', - description='Access medical information, symptom analysis, and treatment recommendations.' -) -healthcare_interface.launch() -``` +# File: swarms_cloud\chinese_api_pricing.md -### News Analysis Agent Example +# Swarm Agent API 定价文档 -This example creates an interface for real-time news analysis: -```python -import gradio as gr -import ai_gradio +Swarm Agent API 提供了一个强大的平台，用于大规模管理多代理协作和在云端编排 LLM 代理群。本文档概述了定价模型、成本计算方式以及如何购买和管理您的积分。 -news_interface = gr.load( - name='swarms:gpt-4-turbo', - src=ai_gradio.registry, - agent_name="News-Analysis-Agent", - title='News Analyzer', - description='Get real-time insights and analysis of trending news topics.' -) -news_interface.launch() -``` +我们的定价设计旨在透明且具有成本效益，使您能够轻松发挥代理的全部潜力。成本基于： ---- +- 使用的代理数量 -## Setup and Deployment +- 输入和输出令牌使用量 -1. **Install Dependencies:** - Make sure all required packages are installed. +- 执行时间 - ```bash - pip install gradio ai-gradio swarms - ``` +## 积分系统 -2. **Import Modules:** - Import Gradio and ai_gradio in your Python script. +Swarm API 采用基于积分的系统： - ```python - import gradio as gr - import ai_gradio - ``` +- **积分**是平台内使用的货币 -3. **Configure and Launch the Interface:** - Configure your interface with the desired parameters and then launch. +- 1积分 = 1美元 - ```python - interface = gr.load( - name='swarms:gpt-4-turbo', - src=ai_gradio.registry, - agent_name="Your-Desired-Agent", - title='Your Interface Title', - description='A brief description of your interface.' - ) - interface.launch() - ``` +- 积分可以用美元或 $swarms Solana 代币购买 -4. **Deployment Options:** - - **Local:** By default, the interface runs at [http://localhost:7860](http://localhost:7860). - - **Cloud Deployment:** Use cloud platforms like Heroku, AWS, or Google Cloud for remote access. - - **Concurrent Sessions:** The system supports multiple users at the same time. Monitor resources and use proper scaling. +- 两种类型的积分： ---- + - **标准积分**：购买的积分永不过期 -## Best Practices + - **免费积分**：促销积分，可能有使用限制 -1. **Select the Right Agent:** - Use the agent that best suits your specific domain needs. +## 定价结构 -2. **Model Configuration:** - Adjust model parameters based on your computational resources to balance performance and cost. +### 基本成本 -3. **Error Handling:** - Implement error handling to manage unexpected inputs or API failures gracefully. +| 成本组成 | 价格 | +|----------------|-------| +| 每个代理的基本成本 | 每个代理$0.01 | -4. **Resource Monitoring:** - Keep an eye on system performance, especially during high-concurrency sessions. +### 令牌使用成本 -5. **Regular Updates:** - Keep your Swarms and Gradio packages updated to ensure compatibility with new features and security patches. +| 令牌类型 | 成本 | +|------------|------| +| 输入令牌 | 每百万令牌$2.00 | +| 输出令牌 | 每百万令牌$4.50 | + +### 夜间折扣 + +为了鼓励在非高峰时段高效利用资源，我们在加州夜间时段提供显著折扣： + +| 时间段（太平洋时间） | 折扣 | +|----------------------------|----------| +| 晚上8:00至早上6:00 | 令牌成本75%折扣 | ---- +## 成本计算 -## Notes +### 公式 -- **Local vs. Remote:** - The interface runs locally by default but can be deployed on remote servers for wider accessibility. +群体执行的总成本计算如下： -- **Customization:** - You can configure custom model parameters and integrate additional APIs as needed. +``` +总成本 = (代理数量 × $0.01) + + (总输入令牌数 / 1M × $2.00 × 代理数量) + + (总输出令牌数 / 1M × $4.50 × 代理数量) +``` -- **Session Management:** - Built-in session handling ensures that users can interact concurrently without interfering with each other's sessions. +应用夜间折扣时： +``` +输入令牌成本 = 输入令牌成本 × 0.25 +输出令牌成本 = 输出令牌成本 × 0.25 +``` -- **Error Handling & Rate Limiting:** - The system includes basic error handling and rate limiting to maintain performance under load. +### 示例场景 ---- +#### 场景1：基本工作流（白天） -This documentation is designed to provide clarity, reliability, and comprehensive guidance for integrating and using the Swarms Chat UI. For further customization or troubleshooting, consult the respective package documentation and community forums. +- 3个代理 --------------------------------------------------- +- 总共10,000个输入令牌 -# File: swarms_cloud/add_agent.md +- 总共25,000个输出令牌 -# Publishing an Agent to Agent Marketplace +**计算：** -## Requirements +- 代理成本：3 × $0.01 = $0.03 -- `swarms-cloud` package with `pip3 install -U swarms-cloud` +- 输入令牌成本：(10,000 / 1,000,000) × $2.00 × 3 = $0.06 -- Onboarding Process with `swarms-cloud onboarding` +- 输出令牌成本：(25,000 / 1,000,000) × $4.50 × 3 = $0.3375 -- A Dockerfile `Dockerfile` containing the API of your agent code with FastAPI +- **总成本：$0.4275** -- A YAML file for configuration `agent.yaml` +#### 场景2：复杂工作流（夜间） -## Deployment YAML -```yaml +- 5个代理 -# Agent metadata and description -agent_name: "example-agent" # The name of the agent -description: "This agent performs financial data analysis." # A brief description of the agent's purpose -version: "v1.0" # The version number of the agent -author: "Agent Creator Name" # The name of the person or entity that created the agent -contact_email: "creator@example.com" # The email address for contacting the agent's creator -tags: - - "financial" # Tag indicating the agent is related to finance - - "data-analysis" # Tag indicating the agent performs data analysis - - "agent" # Tag indicating this is an agent +- 总共50,000个输入令牌 +- 总共125,000个输出令牌 -# Deployment configuration -deployment_config: - # Dockerfile configuration - dockerfile_path: "./Dockerfile" # The path to the Dockerfile for building the agent's image - dockerfile_port: 8080 # The port number the agent will listen on - - # Resource allocation for the agent - resources: - cpu: 2 # Number of CPUs allocated to the agent - memory: "2Gi" # Memory allocation for the agent in gigabytes - max_instances: 5 # Maximum number of instances to scale up to - min_instances: 1 # Minimum number of instances to keep running - timeout: 300s # Request timeout setting in seconds +**计算：** - # Autoscaling configuration - autoscaling: - max_concurrency: 80 # Maximum number of requests the agent can handle concurrently - target_utilization: 0.6 # CPU utilization target for auto-scaling +- 代理成本：5 × $0.01 = $0.05 - # Environment variables for the agent - environment_variables: - DATABASE_URL: "postgres://user:password@db-url" # URL for the database connection - API_KEY: "your-secret-api-key" # API key for authentication - LOG_LEVEL: "info" # Log level for the agent +- 输入令牌成本：(50,000 / 1,000,000) × $2.00 × 5 × 0.25 = $0.125 - # Secrets configuration - secrets: - SECRET_NAME_1: "projects/my-project/secrets/my-secret/versions/latest" # Path to a secret -``` +- 输出令牌成本：(125,000 / 1,000,000) × $4.50 × 5 × 0.25 = $0.703125 --------------------------------------------------- +- **总成本：$0.878125** -# File: swarms_cloud/agent_api.md +## 购买积分 -# Swarms API Documentation +可以通过我们的平台以两种方式购买积分： + +1. **美元支付** + - 可通过我们的[账户页面](https://swarms.world/platform/account)使用 + - 安全支付处理 + - 最低购买额：$10 -The Swarms API provides endpoints to interact with various language models, manage agent configurations, and handle token counting. This documentation covers the available endpoints, input and output models, and detailed examples for each endpoint. +2. **$swarms 代币支付** + - 使用基于Solana的$swarms代币 + - 可在支持的交易所购买代币 + - 在我们的[账户页面](https://swarms.world/platform/account)连接您的Solana钱包 -URL: `https://api.swarms.world` +## 免费积分 -## Key Features -- Dynamic Model Switching: Easily switch between different language models based on user input. -- Token Counting: Efficiently count tokens using the tiktoken library. -- Agent Configuration: Configure and run agents with detailed settings for various tasks. -- CORS Handling: Support for Cross-Origin Resource Sharing (CORS) to allow web-based clients to interact with the API. +我们偶尔会向以下对象提供免费积分： +- 新用户（欢迎奖励） -## Endpoints +- 促销期间 -### `/v1/models` +- 教育和研究目的 -**Method:** `GET` +关于免费积分的说明： -**Response Model:** `List[str]` +- 在标准积分之前使用 -**Description:** -This endpoint returns a list of available model names. It is useful for clients to query and understand which models are available for use. +- 可能有过期日期 -**Response Example:** +- 可能有使用限制 -```json -[ - "OpenAIChat", - "GPT4VisionAPI", - "Anthropic" -] -``` +## 账单和使用跟踪 -**Example Usage:** +通过我们全面的日志和报告功能跟踪您的积分使用情况： -```python -import requests +1. **API日志** -response = requests.get("http://api.swarms.world/v1/models") -print(response.json()) -``` + - 通过`/v1/swarm/logs`端点访问详细日志 -### `/v1/agent/completions` + - 查看每次执行的成本明细 -**Method:** `POST` +2. **仪表板** -**Request Model:** `AgentInput` + - 实时积分余额显示 -**Response Model:** `AgentOutput` + - 历史使用图表 -**URL:** `http://api.swarms.world/v1/agent/completions` + - 详细成本分析 -**Description:** -This endpoint handles the completion request for an agent configured with the given input parameters. It processes the request and returns the completion results. + - 可在[https://swarms.world/platform/dashboard](https://swarms.world/platform/dashboard)访问 -**Request Example:** +## 常见问题 -```json -{ - "agent_name": "Swarm Agent", - "system_prompt": "Summarize the following text", - "agent_description": "An agent that summarizes text", - "model_name": "OpenAIChat", - "max_loops": 1, - "autosave": false, - "dynamic_temperature_enabled": false, - "dashboard": false, - "verbose": false, - "streaming_on": true, - "saved_state_path": null, - "sop": null, - "sop_list": null, - "user_name": "User", - "retry_attempts": 3, - "context_length": 8192, - "task": "This is a sample text that needs to be summarized." -} -``` +**问：是否有最低积分购买要求？** +答：是的，最低积分购买额为10美元等值。 -**Response Example:** +**问：积分会过期吗？** +答：标准积分不会过期。免费促销积分可能有过期日期。 -```json -{ - "agent": { - "agent_name": "Swarm Agent", - "system_prompt": "Summarize the following text", - "agent_description": "An agent that summarizes text", - "model_name": "OpenAIChat", - "max_loops": 1, - "autosave": false, - "dynamic_temperature_enabled": false, - "dashboard": false, - "verbose": false, - "streaming_on": true, - "saved_state_path": null, - "sop": null, - "sop_list": null, - "user_name": "User", - "retry_attempts": 3, - "context_length": 8192, - "task": "This is a sample text that needs to be summarized." - }, - "completions": { - "choices": [ - { - "index": 0, - "message": { - "role": "Swarm Agent", - "content": "The sample text summarizes how to perform text summarization using an agent.", - "name": null - } - } - ], - "stream_choices": null, - "usage_info": { - "prompt_tokens": 10, - "completion_tokens": 15, - "total_tokens": 25 - } - } -} -``` +**问：夜间折扣如何应用？** +答：系统会根据太平洋时间（America/Los_Angeles）自动检测执行时间，并在晚上8:00至早上6:00之间的执行应用75%的令牌成本折扣。 -**Example Usage:** +**问：如果我在执行过程中积分用完了会怎样？** +答：如果没有足够的积分，执行将失败并显示402 Payment Required错误。我们建议维持适合您使用模式的积分余额。 -```python -import requests -from pydantic import BaseModel -from typing import List +**问：我可以获得未使用积分的退款吗？** +答：请联系我们的支持团队处理未使用积分的退款请求。 -class AgentInput(BaseModel): - agent_name: str = "Swarm Agent" - system_prompt: str = None - agent_description: str = None - model_name: str = "OpenAIChat" - max_loops: int = 1 - autosave: bool = False - dynamic_temperature_enabled: bool = False - dashboard: bool = False - verbose: bool = False - streaming_on: bool = True - saved_state_path: str = None - sop: str = None - sop_list: List[str] = None - user_name: str = "User" - retry_attempts: int = 3 - context_length: int = 8192 - task: str = None - -agent_input = AgentInput(task="Generate a summary of the provided text.") -response = requests.post("http://api.swarms.world/v1/agent/completions", json=agent_input.dict()) -print(response.json()) -``` +**问：是否有批量折扣？** +答：是的，请联系我们的销售团队了解企业定价和批量折扣。 -## Models +## 参考资料 -### AgentInput +- [Swarm API 文档](https://docs.swarms.world) -The `AgentInput` class defines the structure of the input data required to configure and run an agent. +- [账户管理门户](https://swarms.world/platform/account) -| Parameter | Type | Default | Description | -|--------------------------------|-----------------|-----------------|-----------------------------------------------------------------| -| `agent_name` | `str` | "Swarm Agent" | The name of the agent. | -| `system_prompt` | `str` or `None` | `None` | The system prompt to guide the agent's behavior. | -| `agent_description` | `str` or `None` | `None` | A description of the agent's purpose. | -| `model_name` | `str` | "OpenAIChat" | The name of the language model to use. | -| `max_loops` | `int` | 1 | The maximum number of loops the agent should perform. | -| `autosave` | `bool` | `False` | Whether to enable autosave functionality. | -| `dynamic_temperature_enabled` | `bool` | `False` | Whether dynamic temperature adjustment is enabled. | -| `dashboard` | `bool` | `False` | Whether to enable the dashboard feature. | -| `verbose` | `bool` | `False` | Whether to enable verbose logging. | -| `streaming_on` | `bool` | `True` | Whether to enable streaming of responses. | -| `saved_state_path` | `str` or `None` | `None` | Path to save the agent's state. | -| `sop` | `str` or `None` | `None` | Standard operating procedures for the agent. | -| `sop_list` | `List[str]` or `None` | `None` | A list of standard operating procedures. | -| `user_name` | `str` | "User" | The name of the user interacting with the agent. | -| `retry_attempts` | `int` | 3 | Number of retry attempts for failed operations. | -| `context_length` | `int` | 8192 | Maximum context length for the model's input. | -| `task` | `str` or `None` | `None` | The task description for the agent to perform. | +- [Swarm 类型参考](https://docs.swarms.world/swarm-types) -### AgentOutput +- [令牌使用指南](https://docs.swarms.world/token-usage) -The `AgentOutput` class defines the structure of the output data returned by the agent after processing a request. +- [API 参考](https://docs.swarms.world/api-reference) -| Parameter | Type | Description | -|---------------|--------------------------|--------------------------------------------------| -| `agent` | `AgentInput` | The input configuration used to create the agent.| -| `completions` | `ChatCompletionResponse` | The response generated by the agent. | +--- -## Functions +如有其他问题或自定义定价选项，请联系我们的支持团队，邮箱：kye@swarms.world -### count_tokens +-------------------------------------------------- -The `count_tokens` function counts the number of tokens in a given text using the `tiktoken` library. +# File: swarms_cloud\cloud_run.md -**Parameters:** +# Hosting Agents on Google Cloud Run -- `text` (`str`): The text to be tokenized and counted. +This documentation provides a highly detailed, step-by-step guide to hosting your agents using Google Cloud Run. It uses a well-structured project setup that includes a Dockerfile at the root level, a folder dedicated to your API file, and a `requirements.txt` file to manage all dependencies. This guide will ensure your deployment is scalable, efficient, and easy to maintain. -**Returns:** +--- -- `int`: The number of tokens in the text. +## **Project Structure** -**Example Usage:** +Your project directory should adhere to the following structure to ensure compatibility and ease of deployment: -```python -text = "This is a sample text to count tokens." -token_count = count_tokens(text) -print(f"Token count: {token_count}") +``` +. +├── Dockerfile +├── requirements.txt +└── api/ + └── api.py ``` -### model_router - -The `model_router` function switches to the specified language model based on the provided model name. +Each component serves a specific purpose in the deployment pipeline, ensuring modularity and maintainability. -**Parameters:** +--- -- `model_name` (`str`): The name of the model to switch to. +## **Step 1: Prerequisites** -**Returns:** +Before you begin, make sure to satisfy the following prerequisites to avoid issues during deployment: -- An instance of the specified language model. +1. **Google Cloud Account**: + - Create a Google Cloud account at [Google Cloud Console](https://console.cloud.google.com/). + - Enable billing for your project. Billing is necessary for accessing Cloud Run services. -**Example Usage:** +2. **Install Google Cloud SDK**: + - Follow the [installation guide](https://cloud.google.com/sdk/docs/install) to set up the Google Cloud SDK on your local machine. -```python -model_name = "OpenAIChat" -model_instance = model_router(model_name) -``` +3. **Install Docker**: + - Download and install Docker by following the [official Docker installation guide](https://docs.docker.com/get-docker/). Docker is crucial for containerizing your application. -## Additional Information and Tips +4. **Create a Google Cloud Project**: + - Navigate to the Google Cloud Console and create a new project. Assign it a meaningful name and note the **Project ID**, as it will be used throughout this guide. -- **Error Handling**: Ensure robust error handling by catching exceptions and returning meaningful HTTP status codes and messages. -- **Model Selection**: When adding new models, update the `model_router` function and the `/v1/models` endpoint to include the new model names. -- **Token Management**: Keep track of token usage to optimize API costs and manage rate limits effectively. +5. **Enable Required APIs**: + - Visit the [API Library](https://console.cloud.google.com/apis/library) and enable the following APIs: + - Cloud Run API + - Cloud Build API + - Artifact Registry API + - These APIs are essential for deploying and managing your application in Cloud Run. --------------------------------------------------- +--- -# File: swarms_cloud/api_pricing.md +## **Step 2: Creating the Files** -# Swarm Agent API Pricing +### 1. **`api/api.py`** -!!! success "🎉 Get Started with $20 Free Credits!" - New users receive $20 in free credits when they sign up! [Create your account now](https://swarms.world/platform/account) to start building with our powerful multi-agent platform. +This is the main Python script where you define your Swarms agents and expose an API endpoint for interacting with them. Here’s an example: -!!! abstract "Overview" - The Swarm Agent API provides a powerful platform for managing multi-agent collaboration at scale and orchestrating swarms of LLM agents in the cloud. Our pricing model is designed to be transparent and cost-effective, enabling you to harness the full potential of your agents with ease. +```python +from flask import Flask, request, jsonify +from swarms import Agent # Assuming `swarms` is the framework you're using -## Credit System +app = Flask(__name__) -The Swarm API operates on a credit-based system with the following characteristics: +# Example Swarm agent +agent = Agent( + agent_name="Stock-Analysis-Agent", + model_name="gpt-4o-mini", + max_loops="auto", + interactive=True, + streaming_on=True, +) -- **Credits** are the currency used within the platform +@app.route('/run-agent', methods=['POST']) +def run_agent(): + data = request.json + task = data.get('task', '') + result = agent.run(task) + return jsonify({"result": result}) -- 1 credit = $1 USD +if __name__ == '__main__': + app.run(host='0.0.0.0', port=8080) +``` -- Credits can be purchased with USD or $swarms Solana tokens +This example sets up a basic API that listens for POST requests, processes a task using a Swarm agent, and returns the result as a JSON response. Customize it based on your agent’s functionality. -### Credit Types +--- -| Type | Description | Expiration | -|------|-------------|------------| -| Standard Credits | Purchased credits | Never expires | -| Free Credits | Promotional credits | May have expiration dates | +### 2. **`requirements.txt`** -## Pricing Structure +This file lists all Python dependencies required for your project. Example: -### Base Costs +``` +flask +swarms +# add any other dependencies here +``` -| Cost Component | Price | -|----------------|-------| -| Base cost per agent | $0.01 per agent | +Be sure to include any additional libraries your agents rely on. Keeping this file up to date ensures smooth dependency management during deployment. -### Token Usage Costs +--- -| Token Type | Cost | -|------------|------| -| Input tokens | $2.00 per 1M tokens | -| Output tokens | $4.50 per 1M tokens | +### 3. **`Dockerfile`** -### Night-Time Discount +The Dockerfile specifies how your application is containerized. Below is a sample Dockerfile for your setup: -!!! tip "Off-Peak Hours Discount" - To encourage efficient resource usage during off-peak hours, we offer significant discounts for operations performed during California night-time hours: +```dockerfile +# Use an official Python runtime as the base image +FROM python:3.10-slim - | Time Period (Pacific Time) | Discount | - |----------------------------|----------| - | 8:00 PM to 6:00 AM | 75% off token costs | +# Set the working directory +WORKDIR /app -## Cost Calculation +# Copy requirements.txt and install dependencies +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt -### Formula +# Copy the application code +COPY api/ ./api/ -The total cost for a swarm execution is calculated as follows: +# Expose port 8080 (Cloud Run default port) +EXPOSE 8080 -```math -Total Cost = (Number of Agents × $0.01) + - (Total Input Tokens / 1M × $2.00 × Number of Agents) + - (Total Output Tokens / 1M × $4.50 × Number of Agents) +# Run the application +CMD ["python", "api/api.py"] ``` -With night-time discount applied: -```math -Input Token Cost = Input Token Cost × 0.25 -Output Token Cost = Output Token Cost × 0.25 -``` +This Dockerfile ensures your application is containerized with minimal overhead, focusing on slim images for efficiency. -### Example Scenarios +--- -#### Scenario 1: Basic Workflow (Day-time) +## **Step 3: Deploying to Google Cloud Run** -!!! example "Basic Workflow Example" - **Parameters:** - - - 3 agents - - - 10,000 input tokens total - - - 25,000 output tokens total +### 1. **Authenticate with Google Cloud** - **Calculation:** - - - Agent cost: 3 × $0.01 = $0.03 - - - Input token cost: (10,000 / 1,000,000) × $2.00 × 3 = $0.06 - - - Output token cost: (25,000 / 1,000,000) × $4.50 × 3 = $0.3375 - - - **Total cost: $0.4275** +Log in to your Google Cloud account by running: -#### Scenario 2: Complex Workflow (Night-time) +```bash +gcloud auth login +``` -!!! example "Complex Workflow Example" - **Parameters:** - - - 5 agents - - - 50,000 input tokens total - - - 125,000 output tokens total +Set the active project to match your deployment target: - **Calculation:** - - - Agent cost: 5 × $0.01 = $0.05 - - - Input token cost: (50,000 / 1,000,000) × $2.00 × 5 × 0.25 = $0.125 - - - Output token cost: (125,000 / 1,000,000) × $4.50 × 5 × 0.25 = $0.703125 - - - **Total cost: $0.878125** +```bash +gcloud config set project [PROJECT_ID] +``` -## Purchasing Credits +Replace `[PROJECT_ID]` with your actual Project ID. -Credits can be purchased through our platform in two ways: +--- -### USD Payment +### 2. **Build the Docker Image** -- Available through our [account page](https://swarms.world/platform/account) +Use Google Cloud's Artifact Registry to store and manage your Docker image. Follow these steps: -- Secure payment processing +1. **Create a Repository**: -- Minimum purchase: $10 +```bash +gcloud artifacts repositories create my-repo --repository-format=Docker --location=us-central1 +``` -### $swarms Token Payment +2. **Authenticate Docker with Google Cloud**: -- Use Solana-based $swarms tokens +```bash +gcloud auth configure-docker us-central1-docker.pkg.dev +``` -- Tokens can be purchased on supported exchanges +3. **Build and Tag the Image**: -- Connect your Solana wallet on our [account page](https://swarms.world/platform/account) +```bash +docker build -t us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image . +``` -## Free Credits +4. **Push the Image**: -!!! info "Free Credit Program" - We occasionally offer free credits to: - - - New users (welcome bonus) - - - During promotional periods - - - For educational and research purposes +```bash +docker push us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image +``` - **Important Notes:** - - - Used before standard credits - - - May have expiration dates - - - May have usage restrictions +--- -## Billing and Usage Tracking +### 3. **Deploy to Cloud Run** -Track your credit usage through our comprehensive logging and reporting features: +Deploy the application to Cloud Run with the following command: -### API Logs -- Access detailed logs via the `/v1/swarm/logs` endpoint +```bash +gcloud run deploy my-agent-service \ + --image us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image \ + --platform managed \ + --region us-central1 \ + --allow-unauthenticated +``` -- View cost breakdowns for each execution +Key points: +- Replace `[PROJECT_ID]` with your actual Project ID. +- The `--allow-unauthenticated` flag makes the service publicly accessible. Exclude it to restrict access. -### Dashboard -- Real-time credit balance display +--- -- Historical usage graphs +## **Step 4: Testing the Deployment** -- Detailed cost analysis +Once the deployment is complete, test the service: -- Available at [https://swarms.world/platform/dashboard](https://swarms.world/platform/dashboard) +1. Note the URL provided by Cloud Run. +2. Use `curl` or Postman to send a request. Example: -## FAQ +```bash +curl -X POST [CLOUD_RUN_URL]/run-agent \ + -H "Content-Type: application/json" \ + -d '{"task": "example task"}' +``` -??? question "Is there a minimum credit purchase?" - Yes, the minimum credit purchase is $10 USD equivalent. +This tests whether your agent processes the task correctly and returns the expected output. -??? question "Do credits expire?" - Standard credits do not expire. Free promotional credits may have expiration dates. +--- -??? question "How is the night-time discount applied?" - The system automatically detects the execution time based on Pacific Time (America/Los_Angeles) and applies a 75% discount to token costs for executions between 8:00 PM and 6:00 AM. +## **Step 5: Updating the Service** -??? question "What happens if I run out of credits during execution?" - Executions will fail with a 402 Payment Required error if sufficient credits are not available. We recommend maintaining a credit balance appropriate for your usage patterns. +To apply changes to your application: -??? question "Can I get a refund for unused credits?" - Please contact our support team for refund requests for unused credits. +1. Edit the necessary files. +2. Rebuild and push the updated Docker image: -??? question "Are there volume discounts available?" - Yes, please contact our sales team for enterprise pricing and volume discounts. +```bash +docker build -t us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image . +docker push us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image +``` -## References +3. Redeploy the service: -- [Swarm API Documentation](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/) -- [Account Management Portal](https://swarms.world/platform/account) -- [Swarm Types Reference](https://docs.swarms.world/swarms_cloud/swarm_types) +```bash +gcloud run deploy my-agent-service \ + --image us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image +``` ---- +This ensures the latest version of your application is live. -!!! info "Need Help?" - For additional questions or custom pricing options, please contact our support team at [kye@swarms.world](mailto:kye@swarms.world). +--- --------------------------------------------------- +## **Troubleshooting** -# File: swarms_cloud/architecture.md +- **Permission Errors**: + Ensure your account has roles like Cloud Run Admin and Artifact Registry Reader. +- **Port Issues**: + Confirm the application listens on port 8080. Cloud Run expects this port by default. +- **Logs**: + Use the Google Cloud Console or CLI to review logs for debugging: -# Under The Hood: The Swarm Cloud Serving Infrastructure ------------------------------------------------------------------ +```bash +gcloud logs read --project [PROJECT_ID] +``` -This blog post delves into the intricate workings of our serving model infrastructure, providing a comprehensive understanding for both users and infrastructure engineers. We'll embark on a journey that starts with an API request and culminates in a response generated by your chosen model, all orchestrated within a multi-cloud environment. +--- -### The Journey of an API Request +## **Conclusion** -1. **The Gateway:** Your API request first arrives at an EC2 instance running SkyPilot, a lightweight controller. +By following this comprehensive guide, you can deploy your agents on Google Cloud Run with ease. This method leverages Docker for containerization and Google Cloud services for seamless scalability and management. With a robust setup like this, you can focus on enhancing your agents’ capabilities rather than worrying about deployment challenges. -2. **Intelligent Routing:** SkyPilot, wielding its decision-making prowess, analyzes the request and identifies the most suitable GPU in our multi-cloud setup. Factors like resource availability, latency, and cost might influence this choice. -3. **Multi-Cloud Agility:** Based on the chosen cloud provider (AWS or Azure), SkyPilot seamlessly directs the request to the appropriate containerized model residing in a sky clusters cluster. Here's where the magic of cloud-agnostic deployments comes into play. -### Unveiling the Architecture +-------------------------------------------------- -Let's dissect the technical architecture behind this process: +# File: swarms_cloud\launch.md -- **SkyPilot (EC2 Instance):** This lightweight controller, deployed on an EC2 instance, acts as the central hub for orchestrating requests and routing them to suitable model instances. +# Swarms Cloud API Client Documentation -- **Swarm Cloud Repositories:** Each model resides within its own dedicated folder on the Swarms Cloud GitHub repository (). Here, you'll find a folder structure like this: +## Overview +The Swarms Cloud API Client is a production-grade Python library for interacting with the Swarms Cloud Agent API. It provides a comprehensive interface for managing, executing, and monitoring cloud-based agents. +## Installation +```bash +pip install swarms-cloud ``` -servers/ - / - sky-serve.yaml # Deployment configuration file - / - sky-serve.yaml - ... +## Quick Start +```python +from swarms_cloud import SwarmCloudAPI, AgentCreate + +# Initialize the client +client = SwarmCloudAPI( + base_url="https://swarmcloud-285321057562.us-central1.run.app", + api_key="your_api_key_here" +) + +# Create an agent +agent_data = AgentCreate( + name="TranslateAgent", + description="Translates text between languages", + code=""" + def main(request, store): + text = request.payload.get('text', '') + return f'Translated: {text}' + """, + requirements="requests==2.25.1", + envs="DEBUG=True" +) + +new_agent = client.create_agent(agent_data) +print(f"Created agent with ID: {new_agent.id}") ``` -- **SkyServe Deployment Tool:** This is the workhorse responsible for deploying models within sky clusters. Each model's folder contains a `sky-serve.yaml` file that dictates the deployment configuration. - -### Infrastructure Engineer's Toolkit: Commands for Model Deployment - -Here's a breakdown of the `sky serve` command and its subcommands: - -- `sky serve -h`: Displays the help message for the `sky serve` CLI tool. +## Client Configuration -**Commands:** +### Constructor Parameters -- `sky serve up yaml.yaml -n --cloud aws/azure`: This command deploys a SkyServe service based on the provided `yaml.yaml` configuration file. The `-n` flag indicates a new deployment, and the `--cloud` flag specifies the target cloud platform (AWS or Azure). +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|----------|-------------| +| base_url | str | No | https://swarmcloud-285321057562.us-central1.run.app | The base URL of the SwarmCloud API | +| api_key | str | Yes | None | Your SwarmCloud API key | +| timeout | float | No | 10.0 | Request timeout in seconds | -**Additional Commands:** +## Data Models -- `sky serve update`: Updates a running SkyServe service. +### AgentCreate +Model for creating new agents. -- `sky serve status`: Shows the status of deployed SkyServe services. +| Field | Type | Required | Default | Description | +|-------|------|----------|----------|-------------| +| name | str | Yes | - | Name of the agent | +| description | str | No | None | Description of the agent's purpose | +| code | str | Yes | - | Python code that defines the agent's behavior | +| requirements | str | No | None | Python package requirements (pip format) | +| envs | str | No | None | Environment variables for the agent | +| autoscaling | bool | No | False | Enable/disable concurrent execution scaling | -- `sky serve down`: Tears down (stops and removes) a SkyServe service. +### AgentUpdate +Model for updating existing agents. -- `sky serve logs`: Tails the logs of a running SkyServe service, providing valuable insights into its operation. +| Field | Type | Required | Default | Description | +|-------|------|----------|----------|-------------| +| name | str | No | None | Updated name of the agent | +| description | str | No | None | Updated description | +| code | str | No | None | Updated Python code | +| requirements | str | No | None | Updated package requirements | +| autoscaling | bool | No | None | Updated autoscaling setting | -By leveraging these commands, infrastructure engineers can efficiently manage the deployment and lifecycle of models within the multi-cloud environment. +## API Methods -**Building the Cluster and Accessing the Model:** +### List Agents +Retrieve all available agents. -When you deploy a model using `sky serve up`, SkyServe triggers the building of a sky clusters cluster, if one doesn't already exist. Once the deployment is complete, SkyServe provides you with an endpoint URL for interacting with the model. This URL allows you to send requests to the deployed model and receive its predictions. +```python +agents = client.list_agents() +for agent in agents: + print(f"Agent: {agent.name} (ID: {agent.id})") +``` -### Understanding the `sky-serve.yaml` Configuration +**Returns**: List[AgentOut] -The `sky-serve.yaml` file plays a crucial role in defining the deployment parameters for your model. This file typically includes properties such as: +### Create Agent +Create a new agent with the specified configuration. -- **Image:** Specifies the Docker image containing your model code and dependencies. +```python +agent_data = AgentCreate( + name="DataProcessor", + description="Processes incoming data streams", + code=""" + def main(request, store): + data = request.payload.get('data', []) + return {'processed': len(data)} + """, + requirements="pandas==1.4.0\nnumpy==1.21.0", + envs="PROCESSING_MODE=fast", + autoscaling=True +) -- **Replicas:** Defines the number of model replicas to be deployed in the Swarm cluster. This allows for load balancing and fault tolerance. +new_agent = client.create_agent(agent_data) +``` -- **Resources:** Sets memory and CPU resource constraints for the deployed model containers. +**Returns**: AgentOut -- **Networking:** Configures network settings for communication within the sky clusters and with the outside world. +### Get Agent +Retrieve details of a specific agent. -**Benefits of Our Infrastructure:** +```python +agent = client.get_agent("agent_id_here") +print(f"Agent details: {agent}") +``` -- **Multi-Cloud Flexibility:** Deploy models seamlessly across AWS and Azure, taking advantage of whichever platform best suits your needs. +**Parameters**: +- agent_id (str): The unique identifier of the agent -- **Scalability:** Easily scale model deployments up or down based on traffic demands. +**Returns**: AgentOut -- **Cost Optimization:** The intelligent routing by SkyPilot helps optimize costs by utilizing the most cost-effective cloud resources. +### Update Agent +Update an existing agent's configuration. -- **Simplified Management:** Manage models across clouds with a single set of commands using `sky serve`. +```python +update_data = AgentUpdate( + name="UpdatedProcessor", + description="Enhanced data processing capabilities", + code="def main(request, store):\n return {'status': 'updated'}" +) -### Deep Dive: Technical Architecture +updated_agent = client.update_agent("agent_id_here", update_data) +``` -**Cloud Considerations:** +**Parameters**: +- agent_id (str): The unique identifier of the agent +- update (AgentUpdate): The update data -Our multi-cloud architecture offers several advantages, but it also introduces complexities that need to be addressed. Here's a closer look at some key considerations: +**Returns**: AgentOut -- **Cloud Provider APIs and SDKs:** SkyPilot interacts with the APIs and SDKs of the chosen cloud provider (AWS or Azure) to manage resources like virtual machines, storage, and networking. Infrastructure engineers need to be familiar with the specific APIs and SDKs for each cloud platform to ensure smooth operation and troubleshooting. +### Execute Agent +Manually execute an agent with optional payload data. -- **Security:** Maintaining consistent security across different cloud environments is crucial. This involves aspects like IAM (Identity and Access Management) configuration, network segmentation, and encryption of sensitive data at rest and in transit. Infrastructure engineers need to implement robust security measures tailored to each cloud provider's offerings. +```python +# Execute with payload +result = client.execute_agent( + "agent_id_here", + payload={"text": "Hello, World!"} +) -- **Network Connectivity:** Establishing secure and reliable network connectivity between SkyPilot (running on EC2), sky clusters clusters (deployed on cloud VMs), and your client applications is essential. This might involve setting up VPN tunnels or utilizing cloud-native networking solutions offered by each provider. +# Execute without payload +result = client.execute_agent("agent_id_here") +``` -- **Monitoring and Logging:** Monitoring the health and performance of SkyPilot, sky clusters clusters, and deployed models across clouds is critical for proactive issue identification and resolution. Infrastructure engineers can leverage cloud provider-specific monitoring tools alongside centralized logging solutions for comprehensive oversight. +**Parameters**: +- agent_id (str): The unique identifier of the agent +- payload (Optional[Dict[str, Any]]): Execution payload data -**sky clusters Clusters** +**Returns**: Dict[str, Any] -sky clusters is a container orchestration platform that facilitates the deployment and management of containerized applications, including your machine learning models. When you deploy a model with `sky serve up`, SkyPilot launches an node with: +### Get Agent History +Retrieve the execution history and logs for an agent. -- **Provision Resources:** SkyPilot requests resources from the chosen cloud provider (e.g., VMs with GPUs) to create a sky clusters cluster if one doesn't already exist. +```python +history = client.get_agent_history("agent_id_here") +for execution in history.executions: + print(f"[{execution.timestamp}] {execution.log}") +``` -- **Deploy Containerized Models:** SkyPilot leverages the `sky-serve.yaml` configuration to build Docker images containing your model code and dependencies. These images are then pushed to a container registry (e.g., Docker Hub) and deployed as containers within the Swarm cluster. +**Parameters**: +- agent_id (str): The unique identifier of the agent -- **Load Balancing and Service Discovery:** sky clusters provides built-in load balancing capabilities to distribute incoming requests across multiple model replicas, ensuring high availability and performance. Additionally, service discovery mechanisms allow models to find each other and communicate within the cluster. +**Returns**: AgentExecutionHistory -**SkyPilot - The Orchestrator** +### Batch Execute Agents +Execute multiple agents simultaneously with the same payload. -SkyPilot, the lightweight controller running on an EC2 instance, plays a central role in this infrastructure. Here's a deeper look at its functionalities: +```python +# Get list of agents +agents = client.list_agents() -- **API Gateway Integration:** SkyPilot can be integrated with your API gateway or service mesh to receive incoming requests for model predictions. +# Execute batch with payload +results = client.batch_execute_agents( + agents=agents[:3], # Execute first three agents + payload={"data": "test"} +) -- **Request Routing:** SkyPilot analyzes the incoming request, considering factors like model compatibility, resource availability, and latency. Based on this analysis, SkyPilot selects the most suitable model instance within the appropriate sky clusters cluster. +print(f"Batch execution results: {results}") +``` -- **Cloud Provider Interaction:** SkyPilot interacts with the chosen cloud provider's APIs to manage resources required for the sky clusters cluster and model deployment. +**Parameters**: +- agents (List[AgentOut]): List of agents to execute +- payload (Optional[Dict[str, Any]]): Shared execution payload -- **Model Health Monitoring:** SkyPilot can be configured to monitor the health and performance of deployed models. This might involve collecting metrics like model response times, resource utilization, and error rates. +**Returns**: List[Any] -- **Scalability Management:** Based on pre-defined policies or real-time traffic patterns, SkyPilot can trigger the scaling of model deployments (adding or removing replicas) within the sky clusters cluster. +### Health Check +Check the API's health status. -**Advanced Considerations** +```python +status = client.health() +print(f"API Status: {status}") +``` -This blog post has provided a foundational understanding of our serving model infrastructure. For infrastructure engineers seeking a deeper dive, here are some additional considerations: +**Returns**: Dict[str, Any] -- **Container Security:** Explore container image scanning for vulnerabilities, enforcing least privilege principles within container runtime environments, and utilizing secrets management solutions for secure access to sensitive data. +## Error Handling +The client uses exception handling to manage various error scenarios: -- **Model Versioning and Rollbacks:** Implement a model versioning strategy to track changes and facilitate rollbacks to previous versions if necessary. +```python +from swarms_cloud import SwarmCloudAPI +import httpx -- **A/B Testing:** Integrate A/B testing frameworks to evaluate the performance of different model versions and configurations before full-scale deployment. +try: + client = SwarmCloudAPI(api_key="your_api_key_here") + agents = client.list_agents() +except httpx.HTTPError as http_err: + print(f"HTTP error occurred: {http_err}") +except Exception as err: + print(f"An unexpected error occurred: {err}") +finally: + client.close() +``` -- **Auto-Scaling with Cloud Monitoring:** Utilize cloud provider-specific monitoring services like Amazon CloudWatch or Azure Monitor to trigger auto-scaling of sky clusters clusters based on predefined metrics. +## Context Manager Support +The client can be used with Python's context manager: -By understanding these technical aspects and considerations, infrastructure engineers can effectively manage and optimize our multi-cloud serving model infrastructure. +```python +with SwarmCloudAPI(api_key="your_api_key_here") as client: + status = client.health() + print(f"API Status: {status}") + # Client automatically closes after the with block +``` -### Conclusion +## Best Practices -This comprehensive exploration has shed light on the intricate workings of our serving model infrastructure. We've covered the journey of an API request, delved into the technical architecture with a focus on cloud considerations, sky clusters clusters, and SkyPilot's role as the orchestrator. We've also explored advanced considerations for infrastructure engineers seeking to further optimize and secure this multi-cloud environment. +1. Always close the client when finished: +```python +client = SwarmCloudAPI(api_key="your_api_key_here") +try: + # Your code here +finally: + client.close() +``` -This understanding empowers both users and infrastructure engineers to leverage this technology effectively for deploying and managing your machine learning models at scale. +2. Use context managers for automatic cleanup: +```python +with SwarmCloudAPI(api_key="your_api_key_here") as client: + # Your code here +``` +3. Handle errors appropriately: +```python +try: + result = client.execute_agent("agent_id", payload={"data": "test"}) +except httpx.HTTPError as e: + logger.error(f"HTTP error: {e}") + # Handle error appropriately +``` --------------------------------------------------- +4. Set appropriate timeouts for your use case: +```python +client = SwarmCloudAPI( + api_key="your_api_key_here", + timeout=30.0 # Longer timeout for complex operations +) +``` -# File: swarms_cloud/available_models.md +## Complete Example +Here's a complete example showcasing various features of the client: -# Available Models +```python +from swarms_cloud import SwarmCloudAPI, AgentCreate, AgentUpdate +import httpx -| Model Name | Description | Input Price | Output Price | Use Cases | -|-----------------------|---------------------------------------------------------------------------------------------------------|--------------|--------------|------------------------------------------------------------------------| -| **nternlm-xcomposer2-4khd** | One of the highest performing VLMs (Video Language Models). | $4/1M Tokens | $8/1M Tokens | High-resolution video processing and understanding. | +def main(): + with SwarmCloudAPI(api_key="your_api_key_here") as client: + # Create an agent + agent_data = AgentCreate( + name="DataAnalyzer", + description="Analyzes incoming data streams", + code=""" + def main(request, store): + data = request.payload.get('data', []) + return { + 'count': len(data), + 'summary': 'Data processed successfully' + } + """, + requirements="pandas==1.4.0", + autoscaling=True + ) + + try: + # Create the agent + new_agent = client.create_agent(agent_data) + print(f"Created agent: {new_agent.name} (ID: {new_agent.id})") + + # Execute the agent + result = client.execute_agent( + new_agent.id, + payload={"data": [1, 2, 3, 4, 5]} + ) + print(f"Execution result: {result}") + + # Update the agent + update_data = AgentUpdate( + description="Enhanced data analysis capabilities" + ) + updated_agent = client.update_agent(new_agent.id, update_data) + print(f"Updated agent: {updated_agent.name}") + + # Get execution history + history = client.get_agent_history(new_agent.id) + print(f"Execution history: {history}") + + except httpx.HTTPError as e: + print(f"HTTP error occurred: {e}") + except Exception as e: + print(f"Unexpected error: {e}") +if __name__ == "__main__": + main() +``` -## What models should we add? -[Book a call with us to learn more about your needs:](https://calendly.com/swarm-corp/30min) +## Logging +The client uses the `loguru` library for logging. You can configure the logging level and format: +```python +from loguru import logger --------------------------------------------------- +# Configure logging +logger.add("swarmcloud.log", rotation="500 MB") -# File: swarms_cloud/best_practices.md +client = SwarmCloudAPI(api_key="your_api_key_here") +``` -# Swarms API Best Practices Guide +## Performance Considerations -This comprehensive guide outlines production-grade best practices for using the Swarms API effectively. Learn how to choose the right swarm architecture, optimize costs, and implement robust error handling. +1. **Connection Reuse**: The client reuses HTTP connections by default, improving performance for multiple requests. -## Quick Reference Cards +2. **Timeout Configuration**: Set appropriate timeouts based on your use case: +```python +client = SwarmCloudAPI( + api_key="your_api_key_here", + timeout=5.0 # Shorter timeout for time-sensitive operations +) +``` -=== "Swarm Types" - - !!! info "Available Swarm Architectures" - - | Swarm Type | Best For | Use Cases | - |------------|----------|------------| - | `AgentRearrange` | Dynamic workflows | - Complex task decomposition
- Adaptive processing
- Multi-stage analysis
- Dynamic resource allocation | - | `MixtureOfAgents` | Diverse expertise | - Cross-domain problems
- Comprehensive analysis
- Multi-perspective tasks
- Research synthesis | - | `SpreadSheetSwarm` | Data processing | - Financial analysis
- Data transformation
- Batch calculations
- Report generation | - | `SequentialWorkflow` | Linear processes | - Document processing
- Step-by-step analysis
- Quality control
- Content pipeline | - | `ConcurrentWorkflow` | Parallel tasks | - Batch processing
- Independent analyses
- High-throughput needs
- Multi-market analysis | - | `GroupChat` | Collaborative solving | - Brainstorming
- Decision making
- Problem solving
- Strategy development | - | `MultiAgentRouter` | Task distribution | - Load balancing
- Specialized processing
- Resource optimization
- Service routing | - | `AutoSwarmBuilder` | Automated setup | - Quick prototyping
- Simple tasks
- Testing
- MVP development | - | `HiearchicalSwarm` | Complex organization | - Project management
- Research analysis
- Enterprise workflows
- Team automation | - | `MajorityVoting` | Consensus needs | - Quality assurance
- Decision validation
- Risk assessment
- Content moderation | +3. **Batch Operations**: Use batch_execute_agents for multiple agent executions: +```python +results = client.batch_execute_agents( + agents=agents, + payload=shared_payload +) +``` -=== "Application Patterns" - - !!! tip "Specialized Application Configurations" - - | Application | Recommended Swarm | Benefits | - |------------|-------------------|-----------| - | **Team Automation** | `HiearchicalSwarm` | - Automated team coordination
- Clear responsibility chain
- Scalable team structure | - | **Research Pipeline** | `SequentialWorkflow` | - Structured research process
- Quality control at each stage
- Comprehensive output | - | **Trading System** | `ConcurrentWorkflow` | - Multi-market coverage
- Real-time analysis
- Risk distribution | - | **Content Factory** | `MixtureOfAgents` | - Automated content creation
- Consistent quality
- High throughput | +## Rate Limiting +The client respects API rate limits but does not implement retry logic. Implement your own retry mechanism if needed: -=== "Cost Optimization" +```python +from tenacity import retry, stop_after_attempt, wait_exponential - !!! tip "Advanced Cost Management Strategies" - - | Strategy | Implementation | Impact | - |----------|----------------|---------| - | Batch Processing | Group related tasks | 20-30% cost reduction | - | Off-peak Usage | Schedule for 8 PM - 6 AM PT | 15-25% cost reduction | - | Token Optimization | Precise prompts, focused tasks | 10-20% cost reduction | - | Caching | Store reusable results | 30-40% cost reduction | - | Agent Optimization | Use minimum required agents | 15-25% cost reduction | - | Smart Routing | Route to specialized agents | 10-15% cost reduction | - | Prompt Engineering | Optimize input tokens | 15-20% cost reduction | +@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10)) +def execute_with_retry(client, agent_id, payload): + return client.execute_agent(agent_id, payload) +``` -=== "Industry Solutions" +## Thread Safety +The client is not thread-safe by default. For concurrent usage, create separate client instances for each thread or implement appropriate synchronization mechanisms. - !!! example "Industry-Specific Swarm Patterns" - - | Industry | Use Case | Applications | - |----------|----------|--------------| - | **Finance** | Automated trading desk | - Portfolio management
- Risk assessment
- Market analysis
- Trading execution | - | **Healthcare** | Clinical workflow automation | - Patient analysis
- Diagnostic support
- Treatment planning
- Follow-up care | - | **Legal** | Legal document processing | - Document review
- Case analysis
- Contract review
- Compliance checks | - | **E-commerce** | E-commerce operations | - Product management
- Pricing optimization
- Customer support
- Inventory management | +-------------------------------------------------- -=== "Error Handling" +# File: swarms_cloud\mcp.md - !!! warning "Advanced Error Management Strategies" - - | Error Code | Strategy | Recovery Pattern | - |------------|----------|------------------| - | 400 | Input Validation | Pre-request validation with fallback | - | 401 | Auth Management | Secure key rotation and storage | - | 429 | Rate Limiting | Exponential backoff with queuing | - | 500 | Resilience | Retry with circuit breaking | - | 503 | High Availability | Multi-region redundancy | - | 504 | Timeout Handling | Adaptive timeouts with partial results | +# Swarms API as MCP -## Choosing the Right Swarm Architecture +- Launch MCP server as a tool +- Put `SWARMS_API_KEY` in `.env` +- Client side code below -### Decision Framework -Use this framework to select the optimal swarm architecture for your use case: +## Server Side -1. **Task Complexity Analysis** - - Simple tasks → `AutoSwarmBuilder` - - Complex tasks → `HiearchicalSwarm` or `MultiAgentRouter` - - Dynamic tasks → `AgentRearrange` +```python +# server.py +from datetime import datetime +import os +from typing import Any, Dict, List, Optional -2. **Workflow Pattern** - - Linear processes → `SequentialWorkflow` - - Parallel operations → `ConcurrentWorkflow` - - Collaborative tasks → `GroupChat` +import requests +import httpx +from fastmcp import FastMCP +from pydantic import BaseModel, Field +from swarms import SwarmType +from dotenv import load_dotenv -3. **Domain Requirements** - - Multi-domain expertise → `MixtureOfAgents` - - Data processing → `SpreadSheetSwarm` - - Quality assurance → `MajorityVoting` +load_dotenv() -### Industry-Specific Recommendations +class AgentSpec(BaseModel): + agent_name: Optional[str] = Field( + description="The unique name assigned to the agent, which identifies its role and functionality within the swarm.", + ) + description: Optional[str] = Field( + description="A detailed explanation of the agent's purpose, capabilities, and any specific tasks it is designed to perform.", + ) + system_prompt: Optional[str] = Field( + description="The initial instruction or context provided to the agent, guiding its behavior and responses during execution.", + ) + model_name: Optional[str] = Field( + default="gpt-4o-mini", + description="The name of the AI model that the agent will utilize for processing tasks and generating outputs. For example: gpt-4o, gpt-4o-mini, openai/o3-mini", + ) + auto_generate_prompt: Optional[bool] = Field( + default=False, + description="A flag indicating whether the agent should automatically create prompts based on the task requirements.", + ) + max_tokens: Optional[int] = Field( + default=8192, + description="The maximum number of tokens that the agent is allowed to generate in its responses, limiting output length.", + ) + temperature: Optional[float] = Field( + default=0.5, + description="A parameter that controls the randomness of the agent's output; lower values result in more deterministic responses.", + ) + role: Optional[str] = Field( + default="worker", + description="The designated role of the agent within the swarm, which influences its behavior and interaction with other agents.", + ) + max_loops: Optional[int] = Field( + default=1, + description="The maximum number of times the agent is allowed to repeat its task, enabling iterative processing if necessary.", + ) + # New fields for RAG functionality + rag_collection: Optional[str] = Field( + None, + description="The Qdrant collection name for RAG functionality. If provided, this agent will perform RAG queries.", + ) + rag_documents: Optional[List[str]] = Field( + None, + description="Documents to ingest into the Qdrant collection for RAG. (List of text strings)", + ) + tools: Optional[List[Dict[str, Any]]] = Field( + None, + description="A dictionary of tools that the agent can use to complete its task.", + ) -=== "Finance" - - !!! example "Financial Applications" - - Risk Analysis: `HiearchicalSwarm` - - Market Research: `MixtureOfAgents` - - Trading Strategies: `ConcurrentWorkflow` - - Portfolio Management: `SpreadSheetSwarm` -=== "Healthcare" - - !!! example "Healthcare Applications" - - Patient Analysis: `SequentialWorkflow` - - Research Review: `MajorityVoting` - - Treatment Planning: `GroupChat` - - Medical Records: `MultiAgentRouter` +class AgentCompletion(BaseModel): + """ + Configuration for a single agent that works together as a swarm to accomplish tasks. + """ -=== "Legal" - - !!! example "Legal Applications" - - Document Review: `SequentialWorkflow` - - Case Analysis: `MixtureOfAgents` - - Compliance Check: `HiearchicalSwarm` - - Contract Analysis: `ConcurrentWorkflow` + agent: AgentSpec = Field( + ..., + description="The agent to run.", + ) + task: Optional[str] = Field( + ..., + description="The task to run.", + ) + img: Optional[str] = Field( + None, + description="An optional image URL that may be associated with the swarm's task or representation.", + ) + output_type: Optional[str] = Field( + "list", + description="The type of output to return.", + ) -## Production Best Practices -### Best Practices Summary +class AgentCompletionResponse(BaseModel): + """ + Response from an agent completion. + """ -!!! success "Recommended Patterns" - - Use appropriate swarm types for tasks - - Implement robust error handling - - Monitor and log executions - - Cache repeated results - - Rotate API keys regularly + agent_id: str = Field( + ..., + description="The unique identifier for the agent that completed the task.", + ) + agent_name: str = Field( + ..., + description="The name of the agent that completed the task.", + ) + agent_description: str = Field( + ..., + description="The description of the agent that completed the task.", + ) + messages: Any = Field( + ..., + description="The messages from the agent completion.", + ) -!!! danger "Anti-patterns to Avoid" - - Hardcoding API keys - - Ignoring rate limits - - Missing error handling - - Excessive agent count - - Inadequate monitoring + cost: Dict[str, Any] = Field( + ..., + description="The cost of the agent completion.", + ) -### Performance Benchmarks -!!! note "Typical Performance Metrics" - - | Metric | Target Range | Warning Threshold | - |--------|--------------|-------------------| - | Response Time | < 2s | > 5s | - | Success Rate | > 99% | < 95% | - | Cost per Task | < $0.05 | > $0.10 | - | Cache Hit Rate | > 80% | < 60% | - | Error Rate | < 1% | > 5% | +class Agents(BaseModel): + """Configuration for a collection of agents that work together as a swarm to accomplish tasks.""" -### Additional Resources + agents: List[AgentSpec] = Field( + description="A list containing the specifications of each agent that will participate in the swarm, detailing their roles and functionalities." + ) -!!! info "Useful Links" - - - [Swarms API Documentation](https://docs.swarms.world) - - [API Dashboard](https://swarms.world/platform/api-keys) --------------------------------------------------- +class ScheduleSpec(BaseModel): + scheduled_time: datetime = Field( + ..., + description="The exact date and time (in UTC) when the swarm is scheduled to execute its tasks.", + ) + timezone: Optional[str] = Field( + "UTC", + description="The timezone in which the scheduled time is defined, allowing for proper scheduling across different regions.", + ) -# File: swarms_cloud/chinese_api_pricing.md -# Swarm Agent API 定价文档 +class SwarmSpec(BaseModel): + name: Optional[str] = Field( + None, + description="The name of the swarm, which serves as an identifier for the group of agents and their collective task.", + max_length=100, + ) + description: Optional[str] = Field( + None, + description="A comprehensive description of the swarm's objectives, capabilities, and intended outcomes.", + ) + agents: Optional[List[AgentSpec]] = Field( + None, + description="A list of agents or specifications that define the agents participating in the swarm.", + ) + max_loops: Optional[int] = Field( + default=1, + description="The maximum number of execution loops allowed for the swarm, enabling repeated processing if needed.", + ) + swarm_type: Optional[SwarmType] = Field( + None, + description="The classification of the swarm, indicating its operational style and methodology.", + ) + rearrange_flow: Optional[str] = Field( + None, + description="Instructions on how to rearrange the flow of tasks among agents, if applicable.", + ) + task: Optional[str] = Field( + None, + description="The specific task or objective that the swarm is designed to accomplish.", + ) + img: Optional[str] = Field( + None, + description="An optional image URL that may be associated with the swarm's task or representation.", + ) + return_history: Optional[bool] = Field( + True, + description="A flag indicating whether the swarm should return its execution history along with the final output.", + ) + rules: Optional[str] = Field( + None, + description="Guidelines or constraints that govern the behavior and interactions of the agents within the swarm.", + ) + schedule: Optional[ScheduleSpec] = Field( + None, + description="Details regarding the scheduling of the swarm's execution, including timing and timezone information.", + ) + tasks: Optional[List[str]] = Field( + None, + description="A list of tasks that the swarm should complete.", + ) + messages: Optional[List[Dict[str, Any]]] = Field( + None, + description="A list of messages that the swarm should complete.", + ) + # rag_on: Optional[bool] = Field( + # None, + # description="A flag indicating whether the swarm should use RAG.", + # ) + # collection_name: Optional[str] = Field( + # None, + # description="The name of the collection to use for RAG.", + # ) + stream: Optional[bool] = Field( + False, + description="A flag indicating whether the swarm should stream its output.", + ) -Swarm Agent API 提供了一个强大的平台，用于大规模管理多代理协作和在云端编排 LLM 代理群。本文档概述了定价模型、成本计算方式以及如何购买和管理您的积分。 +class SwarmCompletionResponse(BaseModel): + """ + Response from a swarm completion. + """ -我们的定价设计旨在透明且具有成本效益，使您能够轻松发挥代理的全部潜力。成本基于： + status: str = Field(..., description="The status of the swarm completion.") + swarm_name: str = Field(..., description="The name of the swarm.") + description: str = Field(..., description="Description of the swarm.") + swarm_type: str = Field(..., description="The type of the swarm.") + task: str = Field( + ..., description="The task that the swarm is designed to accomplish." + ) + output: List[Dict[str, Any]] = Field( + ..., description="The output generated by the swarm." + ) + number_of_agents: int = Field( + ..., description="The number of agents involved in the swarm." + ) + # "input_config": Optional[Dict[str, Any]] = Field(None, description="The input configuration for the swarm.") -- 使用的代理数量 -- 输入和输出令牌使用量 +BASE_URL = "https://swarms-api-285321057562.us-east1.run.app" -- 执行时间 -## 积分系统 +# Create an MCP server +mcp = FastMCP("swarms-api") -Swarm API 采用基于积分的系统： -- **积分**是平台内使用的货币 +# Add an addition tool +@mcp.tool(name="swarm_completion", description="Run a swarm completion.") +def swarm_completion(swarm: SwarmSpec) -> Dict[str, Any]: + api_key = os.getenv("SWARMS_API_KEY") + headers = {"x-api-key": api_key, "Content-Type": "application/json"} -- 1积分 = 1美元 + payload = swarm.model_dump() -- 积分可以用美元或 $swarms Solana 代币购买 + response = requests.post(f"{BASE_URL}/v1/swarm/completions", json=payload, headers=headers) + + return response.json() -- 两种类型的积分： +@mcp.tool(name="swarms_available", description="Get the list of available swarms.") +async def swarms_available() -> Any: + """ + Get the list of available swarms. + """ + headers = {"Content-Type": "application/json"} - - **标准积分**：购买的积分永不过期 + async with httpx.AsyncClient() as client: + response = await client.get(f"{BASE_URL}/v1/models/available", headers=headers) + response.raise_for_status() # Raise an error for bad responses + return response.json() - - **免费积分**：促销积分，可能有使用限制 -## 定价结构 +if __name__ == "__main__": + mcp.run(transport="sse") +``` -### 基本成本 +## Client side -| 成本组成 | 价格 | -|----------------|-------| -| 每个代理的基本成本 | 每个代理$0.01 | +- Call the tool with it's name and the payload config -### 令牌使用成本 +```python +import asyncio +from fastmcp import Client -| 令牌类型 | 成本 | -|------------|------| -| 输入令牌 | 每百万令牌$2.00 | -| 输出令牌 | 每百万令牌$4.50 | +swarm_config = { + "name": "Simple Financial Analysis", + "description": "A swarm to analyze financial data", + "agents": [ + { + "agent_name": "Data Analyzer", + "description": "Looks at financial data", + "system_prompt": "Analyze the data.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 1000, + "temperature": 0.5, + "auto_generate_prompt": False, + }, + { + "agent_name": "Risk Analyst", + "description": "Checks risk levels", + "system_prompt": "Evaluate the risks.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 1000, + "temperature": 0.5, + "auto_generate_prompt": False, + }, + { + "agent_name": "Strategy Checker", + "description": "Validates strategies", + "system_prompt": "Review the strategy.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 1000, + "temperature": 0.5, + "auto_generate_prompt": False, + }, + ], + "max_loops": 1, + "swarm_type": "SequentialWorkflow", + "task": "Analyze the financial data and provide insights.", + "return_history": False, # Added required field + "stream": False, # Added required field + "rules": None, # Added optional field + "img": None, # Added optional field +} -### 夜间折扣 -为了鼓励在非高峰时段高效利用资源，我们在加州夜间时段提供显著折扣： +async def swarm_completion(): + """Connect to a server over SSE and fetch available swarms.""" -| 时间段（太平洋时间） | 折扣 | -|----------------------------|----------| -| 晚上8:00至早上6:00 | 令牌成本75%折扣 | + async with Client( + transport="http://localhost:8000/sse" + ) as client: + # Basic connectivity testing + # print("Ping check:", await client.ping()) + # print("Available tools:", await client.list_tools()) + # print("Swarms available:", await client.call_tool("swarms_available", None)) + result = await client.call_tool("swarm_completion", {"swarm": swarm_config}) + print("Swarm completion:", result) -## 成本计算 -### 公式 +# Execute the function +if __name__ == "__main__": + asyncio.run(swarm_completion()) +``` -群体执行的总成本计算如下： +-------------------------------------------------- -``` -总成本 = (代理数量 × $0.01) + - (总输入令牌数 / 1M × $2.00 × 代理数量) + - (总输出令牌数 / 1M × $4.50 × 代理数量) -``` +# File: swarms_cloud\mcs_api.md -应用夜间折扣时： -``` -输入令牌成本 = 输入令牌成本 × 0.25 -输出令牌成本 = 输出令牌成本 × 0.25 -``` +# Medical Coder Swarm API Documentation -### 示例场景 +Base URL: `https://mcs-285321057562.us-central1.run.app` -#### 场景1：基本工作流（白天） +## Table of Contents +- [Authentication](#authentication) +- [Rate Limits](#rate-limits) +- [Endpoints](#endpoints) + - [Health Check](#health-check) + - [Run Medical Coder](#run-medical-coder) + - [Run Batch Medical Coder](#run-batch-medical-coder) + - [Get Patient Data](#get-patient-data) + - [Get All Patients](#get-all-patients) +- [Code Examples](#code-examples) +- [Error Handling](#error-handling) -- 3个代理 +## Authentication -- 总共10,000个输入令牌 +Authentication details will be provided by the MCS team. Contact support for API credentials. -- 总共25,000个输出令牌 +## Rate Limits -**计算：** +| Endpoint | GET Rate Limit Status | +|----------|----------------------| +| `GET /rate-limits` | Returns current rate limit status for your IP address | -- 代理成本：3 × $0.01 = $0.03 +## Endpoints -- 输入令牌成本：(10,000 / 1,000,000) × $2.00 × 3 = $0.06 +### Health Check -- 输出令牌成本：(25,000 / 1,000,000) × $4.50 × 3 = $0.3375 +Check if the API is operational. -- **总成本：$0.4275** +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/health` | Returns 200 OK if service is running | -#### 场景2：复杂工作流（夜间） +### Run Medical Coder -- 5个代理 +Process a single patient case through the Medical Coder Swarm. -- 总共50,000个输入令牌 +| Method | Endpoint | Description | +|--------|----------|-------------| +| `POST` | `/v1/medical-coder/run` | Process a single patient case | -- 总共125,000个输出令牌 +**Request Body Parameters:** -**计算：** +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| patient_id | string | Yes | Unique identifier for the patient | +| case_description | string | Yes | Medical case details to be processed | -- 代理成本：5 × $0.01 = $0.05 +**Response Schema:** -- 输入令牌成本：(50,000 / 1,000,000) × $2.00 × 5 × 0.25 = $0.125 +| Field | Type | Description | +|-------|------|-------------| +| patient_id | string | Patient identifier | +| case_data | string | Processed case data | -- 输出令牌成本：(125,000 / 1,000,000) × $4.50 × 5 × 0.25 = $0.703125 +### Run Batch Medical Coder -- **总成本：$0.878125** +Process multiple patient cases in a single request. -## 购买积分 +| Method | Endpoint | Description | +|--------|----------|-------------| +| `POST` | `/v1/medical-coder/run-batch` | Process multiple patient cases | -可以通过我们的平台以两种方式购买积分： +**Request Body Parameters:** -1. **美元支付** - - 可通过我们的[账户页面](https://swarms.world/platform/account)使用 - - 安全支付处理 - - 最低购买额：$10 +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| cases | array | Yes | Array of PatientCase objects | -2. **$swarms 代币支付** - - 使用基于Solana的$swarms代币 - - 可在支持的交易所购买代币 - - 在我们的[账户页面](https://swarms.world/platform/account)连接您的Solana钱包 +### Get Patient Data -## 免费积分 +Retrieve data for a specific patient. -我们偶尔会向以下对象提供免费积分： +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/v1/medical-coder/patient/{patient_id}` | Get patient data by ID | -- 新用户（欢迎奖励） +**Path Parameters:** -- 促销期间 +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| patient_id | string | Yes | Patient identifier | -- 教育和研究目的 +### Get All Patients -关于免费积分的说明： +Retrieve data for all patients. -- 在标准积分之前使用 +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/v1/medical-coder/patients` | Get all patient data | -- 可能有过期日期 +## Code Examples -- 可能有使用限制 +### Python -## 账单和使用跟踪 +```python +import requests +import json -通过我们全面的日志和报告功能跟踪您的积分使用情况： +class MCSClient: + def __init__(self, base_url="https://mcs.swarms.ai", api_key=None): + self.base_url = base_url + self.headers = { + "Content-Type": "application/json", + "Authorization": f"Bearer {api_key}" if api_key else None + } -1. **API日志** + def run_medical_coder(self, patient_id, case_description): + endpoint = f"{self.base_url}/v1/medical-coder/run" + payload = { + "patient_id": patient_id, + "case_description": case_description + } + response = requests.post(endpoint, json=payload, headers=self.headers) + return response.json() - - 通过`/v1/swarm/logs`端点访问详细日志 + def run_batch(self, cases): + endpoint = f"{self.base_url}/v1/medical-coder/run-batch" + payload = {"cases": cases} + response = requests.post(endpoint, json=payload, headers=self.headers) + return response.json() - - 查看每次执行的成本明细 +# Usage example +client = MCSClient(api_key="your_api_key") +result = client.run_medical_coder("P123", "Patient presents with...") +``` -2. **仪表板** +### Next.js (TypeScript) - - 实时积分余额显示 +```typescript +// types.ts +interface PatientCase { + patient_id: string; + case_description: string; +} - - 历史使用图表 +interface QueryResponse { + patient_id: string; + case_data: string; +} - - 详细成本分析 +// api.ts +export class MCSApi { + private baseUrl: string; + private apiKey: string; - - 可在[https://swarms.world/platform/dashboard](https://swarms.world/platform/dashboard)访问 + constructor(apiKey: string, baseUrl = 'https://mcs.swarms.ai') { + this.baseUrl = baseUrl; + this.apiKey = apiKey; + } -## 常见问题 + private async fetchWithAuth(endpoint: string, options: RequestInit = {}) { + const response = await fetch(`${this.baseUrl}${endpoint}`, { + ...options, + headers: { + 'Content-Type': 'application/json', + 'Authorization': `Bearer ${this.apiKey}`, + ...options.headers, + }, + }); + return response.json(); + } -**问：是否有最低积分购买要求？** -答：是的，最低积分购买额为10美元等值。 + async runMedicalCoder(patientCase: PatientCase): Promise { + return this.fetchWithAuth('/v1/medical-coder/run', { + method: 'POST', + body: JSON.stringify(patientCase), + }); + } -**问：积分会过期吗？** -答：标准积分不会过期。免费促销积分可能有过期日期。 + async getPatientData(patientId: string): Promise { + return this.fetchWithAuth(`/v1/medical-coder/patient/${patientId}`); + } +} -**问：夜间折扣如何应用？** -答：系统会根据太平洋时间（America/Los_Angeles）自动检测执行时间，并在晚上8:00至早上6:00之间的执行应用75%的令牌成本折扣。 +// Usage in component +const mcsApi = new MCSApi(process.env.MCS_API_KEY); -**问：如果我在执行过程中积分用完了会怎样？** -答：如果没有足够的积分，执行将失败并显示402 Payment Required错误。我们建议维持适合您使用模式的积分余额。 +export async function ProcessPatientCase({ patientId, caseDescription }) { + const result = await mcsApi.runMedicalCoder({ + patient_id: patientId, + case_description: caseDescription, + }); + return result; +} +``` -**问：我可以获得未使用积分的退款吗？** -答：请联系我们的支持团队处理未使用积分的退款请求。 +### Go -**问：是否有批量折扣？** -答：是的，请联系我们的销售团队了解企业定价和批量折扣。 +```go +package mcs -## 参考资料 +import ( + "bytes" + "encoding/json" + "fmt" + "net/http" +) -- [Swarm API 文档](https://docs.swarms.world) +type MCSClient struct { + BaseURL string + APIKey string + Client *http.Client +} -- [账户管理门户](https://swarms.world/platform/account) +type PatientCase struct { + PatientID string `json:"patient_id"` + CaseDescription string `json:"case_description"` +} -- [Swarm 类型参考](https://docs.swarms.world/swarm-types) +type QueryResponse struct { + PatientID string `json:"patient_id"` + CaseData string `json:"case_data"` +} -- [令牌使用指南](https://docs.swarms.world/token-usage) +func NewMCSClient(apiKey string) *MCSClient { + return &MCSClient{ + BaseURL: "https://mcs.swarms.ai", + APIKey: apiKey, + Client: &http.Client{}, + } +} -- [API 参考](https://docs.swarms.world/api-reference) +func (c *MCSClient) RunMedicalCoder(patientCase PatientCase) (*QueryResponse, error) { + payload, err := json.Marshal(patientCase) + if err != nil { + return nil, err + } ---- + req, err := http.NewRequest("POST", + fmt.Sprintf("%s/v1/medical-coder/run", c.BaseURL), + bytes.NewBuffer(payload)) + if err != nil { + return nil, err + } -如有其他问题或自定义定价选项，请联系我们的支持团队，邮箱：kye@swarms.world + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", c.APIKey)) --------------------------------------------------- + resp, err := c.Client.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + + var result QueryResponse + if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { + return nil, err + } -# File: swarms_cloud/cli.md + return &result, nil +} -# Swarms Cloud CLI Documentation +// Usage example +func main() { + client := NewMCSClient("your_api_key") + + result, err := client.RunMedicalCoder(PatientCase{ + PatientID: "P123", + CaseDescription: "Patient presents with...", + }) + if err != nil { + panic(err) + } + + fmt.Printf("Result: %+v\n", result) +} +``` -Welcome to the Swarms Cloud CLI documentation. This guide will help you understand how to use the CLI to interact with the Swarms Cloud platform. +## C Sharp -## Table of Contents +```txt +using System; +using System.Net.Http; +using System.Text; +using System.Text.Json; +using System.Threading.Tasks; -1. [Introduction](#introduction) -2. [Installation](#installation) -3. [Usage](#usage) -4. [Commands](#commands) - - [onboarding](#onboarding) - - [help](#help) - - [get-api-key](#get-api-key) - - [check-login](#check-login) - - [read-docs](#read-docs) -5. [Troubleshooting](#troubleshooting) -6. [FAQs](#faqs) -7. [Contact Support](#contact-support) +namespace MedicalCoderSwarm +{ + public class PatientCase + { + public string PatientId { get; set; } + public string CaseDescription { get; set; } + } -## Introduction + public class QueryResponse + { + public string PatientId { get; set; } + public string CaseData { get; set; } + } -The Swarms Cloud CLI is a command-line interface tool that allows you to interact with the Swarms Cloud platform. It provides various commands to help you manage your account, retrieve API keys, and access documentation. + public class MCSClient : IDisposable + { + private readonly HttpClient _httpClient; + private readonly string _baseUrl; + + public MCSClient(string apiKey, string baseUrl = "https://mcs-285321057562.us-central1.run.app") + { + _baseUrl = baseUrl; + _httpClient = new HttpClient(); + _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}"); + _httpClient.DefaultRequestHeaders.Add("Content-Type", "application/json"); + } -## Installation + public async Task RunMedicalCoderAsync(string patientId, string caseDescription) + { + var payload = new PatientCase + { + PatientId = patientId, + CaseDescription = caseDescription + }; -To install the Swarms Cloud CLI, you need to have Python installed on your system. You can then install the CLI using pip: + var content = new StringContent( + JsonSerializer.Serialize(payload), + Encoding.UTF8, + "application/json" + ); -```bash -pip3 install -U swarms-cloud -``` + var response = await _httpClient.PostAsync( + $"{_baseUrl}/v1/medical-coder/run", + content + ); -## Usage + response.EnsureSuccessStatusCode(); + + var responseContent = await response.Content.ReadAsStringAsync(); + return JsonSerializer.Deserialize(responseContent); + } -Once installed, you can use the CLI by typing `swarms-cloud` followed by the command you wish to execute. For example: + public async Task GetPatientDataAsync(string patientId) + { + var response = await _httpClient.GetAsync( + $"{_baseUrl}/v1/medical-coder/patient/{patientId}" + ); -```bash -swarms-cloud help -``` + response.EnsureSuccessStatusCode(); + + var responseContent = await response.Content.ReadAsStringAsync(); + return JsonSerializer.Deserialize(responseContent); + } -## Commands + public async Task HealthCheckAsync() + { + var response = await _httpClient.GetAsync($"{_baseUrl}/health"); + return response.IsSuccessStatusCode; + } -### onboarding + public void Dispose() + { + _httpClient?.Dispose(); + } + } -Starts the onboarding process to help you set up your account. + // Example usage + public class Program + { + public static async Task Main() + { + try + { + using var client = new MCSClient("your_api_key"); -```bash -swarms-cloud onboarding -``` + // Check API health + var isHealthy = await client.HealthCheckAsync(); + Console.WriteLine($"API Health: {(isHealthy ? "Healthy" : "Unhealthy")}"); -### help + // Process a single case + var result = await client.RunMedicalCoderAsync( + "P123", + "Patient presents with acute respiratory symptoms..." + ); + Console.WriteLine($"Processed case for patient {result.PatientId}"); + Console.WriteLine($"Case data: {result.CaseData}"); -Displays the help message with a list of available commands. + // Get patient data + var patientData = await client.GetPatientDataAsync("P123"); + Console.WriteLine($"Retrieved data for patient {patientData.PatientId}"); + } + catch (HttpRequestException ex) + { + Console.WriteLine($"API request failed: {ex.Message}"); + } + catch (Exception ex) + { + Console.WriteLine($"An error occurred: {ex.Message}"); + } + } + } +} -```bash -swarms-cloud help ``` -### get-api-key +## Error Handling -Opens the API key retrieval page in your default web browser. +The API uses standard HTTP status codes and returns detailed error messages in JSON format. -```bash -swarms-cloud get-api-key -``` +**Common Status Codes:** -### check-login +| Status Code | Description | +|-------------|-------------| +| 200 | Success | +| 400 | Bad Request - Invalid input | +| 401 | Unauthorized - Invalid or missing API key | +| 422 | Validation Error - Request validation failed | +| 429 | Too Many Requests - Rate limit exceeded | +| 500 | Internal Server Error | -Checks if you are logged in and starts the cache if necessary. +**Error Response Format:** -```bash -swarms-cloud check-login +```json +{ + "detail": [ + { + "loc": ["body", "patient_id"], + "msg": "field required", + "type": "value_error.missing" + } + ] +} ``` -### read-docs - -Redirects you to the Swarms Cloud documentation page. -```bash -swarms-cloud read-docs -``` - -## Troubleshooting +# MCS Python Client Documentation -If you encounter any issues while using the CLI, ensure that you have the latest version installed. You can update the CLI using: +## Installation ```bash -pip install --upgrade swarms-cloud-cli +pip install mcs ``` -## FAQs - -**Q: How do I retrieve my API key?** -A: Use the `get-api-key` command to open the API key retrieval page. - -**Q: What should I do if I am not logged in?** -A: Use the `check-login` command to log in and start the cache. - -## Contact Support - -If you need further assistance, please contact our support team at kye@swarms.world +## Quick Start --------------------------------------------------- +```python +from mcs import MCSClient, PatientCase -# File: swarms_cloud/cloud_run.md +# Using context manager (recommended) +with MCSClient() as client: + # Process a single case + response = client.run_medical_coder( + patient_id="P123", + case_description="Patient presents with acute respiratory symptoms..." + ) + print(f"Processed case: {response.case_data}") -# Hosting Agents on Google Cloud Run + # Process multiple cases + cases = [ + PatientCase("P124", "Case 1 description..."), + PatientCase("P125", "Case 2 description...") + ] + batch_response = client.run_batch(cases) +``` -This documentation provides a highly detailed, step-by-step guide to hosting your agents using Google Cloud Run. It uses a well-structured project setup that includes a Dockerfile at the root level, a folder dedicated to your API file, and a `requirements.txt` file to manage all dependencies. This guide will ensure your deployment is scalable, efficient, and easy to maintain. +## Client Configuration ---- +### Constructor Arguments -## **Project Structure** +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| api_key | str | Yes | - | Authentication API key | +| base_url | str | No | "https://mcs.swarms.ai" | API base URL | +| timeout | int | No | 30 | Request timeout in seconds | +| max_retries | int | No | 3 | Maximum retry attempts | +| logger_name | str | No | "mcs" | Name for the logger instance | -Your project directory should adhere to the following structure to ensure compatibility and ease of deployment: +### Example Configuration +```python +client = MCSClient( + base_url="https://custom-url.example.com", + timeout=45, + max_retries=5, + logger_name="custom_logger" +) ``` -. -├── Dockerfile -├── requirements.txt -└── api/ - └── api.py -``` - -Each component serves a specific purpose in the deployment pipeline, ensuring modularity and maintainability. ---- - -## **Step 1: Prerequisites** +## Data Models -Before you begin, make sure to satisfy the following prerequisites to avoid issues during deployment: +### PatientCase -1. **Google Cloud Account**: - - Create a Google Cloud account at [Google Cloud Console](https://console.cloud.google.com/). - - Enable billing for your project. Billing is necessary for accessing Cloud Run services. +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| patient_id | str | Yes | Unique identifier for the patient | +| case_description | str | Yes | Medical case details | -2. **Install Google Cloud SDK**: - - Follow the [installation guide](https://cloud.google.com/sdk/docs/install) to set up the Google Cloud SDK on your local machine. +### QueryResponse -3. **Install Docker**: - - Download and install Docker by following the [official Docker installation guide](https://docs.docker.com/get-docker/). Docker is crucial for containerizing your application. +| Field | Type | Description | +|-------|------|-------------| +| patient_id | str | Patient identifier | +| case_data | str | Processed case data | -4. **Create a Google Cloud Project**: - - Navigate to the Google Cloud Console and create a new project. Assign it a meaningful name and note the **Project ID**, as it will be used throughout this guide. +## Methods -5. **Enable Required APIs**: - - Visit the [API Library](https://console.cloud.google.com/apis/library) and enable the following APIs: - - Cloud Run API - - Cloud Build API - - Artifact Registry API - - These APIs are essential for deploying and managing your application in Cloud Run. +### run_medical_coder ---- +Process a single patient case. -## **Step 2: Creating the Files** +```python +def run_medical_coder( + self, + patient_id: str, + case_description: str +) -> QueryResponse: +``` -### 1. **`api/api.py`** +**Arguments:** -This is the main Python script where you define your Swarms agents and expose an API endpoint for interacting with them. Here’s an example: +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| patient_id | str | Yes | Patient identifier | +| case_description | str | Yes | Case details | +**Example:** ```python -from flask import Flask, request, jsonify -from swarms import Agent # Assuming `swarms` is the framework you're using - -app = Flask(__name__) - -# Example Swarm agent -agent = Agent( - agent_name="Stock-Analysis-Agent", - model_name="gpt-4o-mini", - max_loops="auto", - interactive=True, - streaming_on=True, +response = client.run_medical_coder( + patient_id="P123", + case_description="Patient presents with..." ) - -@app.route('/run-agent', methods=['POST']) -def run_agent(): - data = request.json - task = data.get('task', '') - result = agent.run(task) - return jsonify({"result": result}) - -if __name__ == '__main__': - app.run(host='0.0.0.0', port=8080) +print(response.case_data) ``` -This example sets up a basic API that listens for POST requests, processes a task using a Swarm agent, and returns the result as a JSON response. Customize it based on your agent’s functionality. - ---- - -### 2. **`requirements.txt`** +### run_batch -This file lists all Python dependencies required for your project. Example: +Process multiple patient cases in batch. +```python +def run_batch( + self, + cases: List[PatientCase] +) -> List[QueryResponse]: ``` -flask -swarms -# add any other dependencies here -``` - -Be sure to include any additional libraries your agents rely on. Keeping this file up to date ensures smooth dependency management during deployment. - ---- - -### 3. **`Dockerfile`** - -The Dockerfile specifies how your application is containerized. Below is a sample Dockerfile for your setup: - -```dockerfile -# Use an official Python runtime as the base image -FROM python:3.10-slim - -# Set the working directory -WORKDIR /app - -# Copy requirements.txt and install dependencies -COPY requirements.txt . -RUN pip install --no-cache-dir -r requirements.txt -# Copy the application code -COPY api/ ./api/ +**Arguments:** -# Expose port 8080 (Cloud Run default port) -EXPOSE 8080 +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| cases | List[PatientCase] | Yes | List of patient cases | -# Run the application -CMD ["python", "api/api.py"] +**Example:** +```python +cases = [ + PatientCase("P124", "Case 1 description..."), + PatientCase("P125", "Case 2 description...") +] +responses = client.run_batch(cases) +for response in responses: + print(f"Patient {response.patient_id}: {response.case_data}") ``` -This Dockerfile ensures your application is containerized with minimal overhead, focusing on slim images for efficiency. - ---- - -## **Step 3: Deploying to Google Cloud Run** - -### 1. **Authenticate with Google Cloud** +### get_patient_data -Log in to your Google Cloud account by running: +Retrieve data for a specific patient. -```bash -gcloud auth login +```python +def get_patient_data( + self, + patient_id: str +) -> QueryResponse: ``` -Set the active project to match your deployment target: - -```bash -gcloud config set project [PROJECT_ID] +**Example:** +```python +patient_data = client.get_patient_data("P123") +print(f"Patient data: {patient_data.case_data}") ``` -Replace `[PROJECT_ID]` with your actual Project ID. - ---- - -### 2. **Build the Docker Image** - -Use Google Cloud's Artifact Registry to store and manage your Docker image. Follow these steps: +### get_all_patients -1. **Create a Repository**: +Retrieve data for all patients. -```bash -gcloud artifacts repositories create my-repo --repository-format=Docker --location=us-central1 +```python +def get_all_patients(self) -> List[QueryResponse]: ``` -2. **Authenticate Docker with Google Cloud**: - -```bash -gcloud auth configure-docker us-central1-docker.pkg.dev +**Example:** +```python +all_patients = client.get_all_patients() +for patient in all_patients: + print(f"Patient {patient.patient_id}: {patient.case_data}") ``` -3. **Build and Tag the Image**: +### get_rate_limits -```bash -docker build -t us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image . -``` +Get current rate limit status. -4. **Push the Image**: +```python +def get_rate_limits(self) -> Dict[str, Any]: +``` -```bash -docker push us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image +**Example:** +```python +rate_limits = client.get_rate_limits() +print(f"Rate limit status: {rate_limits}") ``` ---- +### health_check -### 3. **Deploy to Cloud Run** +Check if the API is operational. -Deploy the application to Cloud Run with the following command: +```python +def health_check(self) -> bool: +``` -```bash -gcloud run deploy my-agent-service \ - --image us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image \ - --platform managed \ - --region us-central1 \ - --allow-unauthenticated +**Example:** +```python +is_healthy = client.health_check() +print(f"API health: {'Healthy' if is_healthy else 'Unhealthy'}") ``` -Key points: -- Replace `[PROJECT_ID]` with your actual Project ID. -- The `--allow-unauthenticated` flag makes the service publicly accessible. Exclude it to restrict access. +## Error Handling ---- +### Exception Hierarchy -## **Step 4: Testing the Deployment** +| Exception | Description | +|-----------|-------------| +| MCSClientError | Base exception for all client errors | +| RateLimitError | Raised when API rate limit is exceeded | +| AuthenticationError | Raised when API authentication fails | +| ValidationError | Raised when request validation fails | -Once the deployment is complete, test the service: +### Example Error Handling -1. Note the URL provided by Cloud Run. -2. Use `curl` or Postman to send a request. Example: +```python +from mcs import MCSClient, MCSClientError, RateLimitError -```bash -curl -X POST [CLOUD_RUN_URL]/run-agent \ - -H "Content-Type: application/json" \ - -d '{"task": "example task"}' +with MCSClient() as client: + try: + response = client.run_medical_coder("P123", "Case description...") + except RateLimitError: + print("Rate limit exceeded. Please wait before retrying.") + except MCSClientError as e: + print(f"An error occurred: {str(e)}") ``` -This tests whether your agent processes the task correctly and returns the expected output. +## Advanced Usage ---- +### Retry Configuration -## **Step 5: Updating the Service** +The client implements two levels of retry logic: -To apply changes to your application: +1. Connection-level retries (using `HTTPAdapter`): +```python +client = MCSClient( + , + max_retries=5 # Adjusts connection-level retries +) +``` -1. Edit the necessary files. -2. Rebuild and push the updated Docker image: +2. Application-level retries (using `tenacity`): +```python +from tenacity import retry, stop_after_attempt -```bash -docker build -t us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image . -docker push us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image +@retry(stop=stop_after_attempt(5)) +def process_with_custom_retries(): + with MCSClient() as client: + return client.run_medical_coder("P123", "Case description...") ``` -3. Redeploy the service: +### Batch Processing with Progress Tracking -```bash -gcloud run deploy my-agent-service \ - --image us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image +```python +from tqdm import tqdm + +with MCSClient() as client: + cases = [ + PatientCase(f"P{i}", f"Case description {i}") + for i in range(100) + ] + + # Process in smaller batches + batch_size = 10 + results = [] + + for i in tqdm(range(0, len(cases), batch_size)): + batch = cases[i:i + batch_size] + batch_results = client.run_batch(batch) + results.extend(batch_results) ``` -This ensures the latest version of your application is live. +## Best Practices ---- +1. **Always use context managers:** + ```python + with MCSClient() as client: + # Your code here + pass + ``` -## **Troubleshooting** +2. **Handle rate limits appropriately:** + ```python + from time import sleep + + def process_with_rate_limit_handling(): + with MCSClient() as client: + try: + return client.run_medical_coder("P123", "Case...") + except RateLimitError: + sleep(60) # Wait before retry + return client.run_medical_coder("P123", "Case...") + ``` -- **Permission Errors**: - Ensure your account has roles like Cloud Run Admin and Artifact Registry Reader. -- **Port Issues**: - Confirm the application listens on port 8080. Cloud Run expects this port by default. -- **Logs**: - Use the Google Cloud Console or CLI to review logs for debugging: +3. **Implement proper logging:** + ```python + from loguru import logger + + logger.add("mcs.log", rotation="500 MB") + + with MCSClient() as client: + try: + response = client.run_medical_coder("P123", "Case...") + except Exception as e: + logger.exception(f"Error processing case: {str(e)}") + ``` -```bash -gcloud logs read --project [PROJECT_ID] -``` +4. **Monitor API health:** + ```python + def ensure_healthy_api(): + with MCSClient() as client: + if not client.health_check(): + raise SystemExit("API is not healthy") + ``` ---- +-------------------------------------------------- -## **Conclusion** +# File: swarms_cloud\phala_deploy.md -By following this comprehensive guide, you can deploy your agents on Google Cloud Run with ease. This method leverages Docker for containerization and Google Cloud services for seamless scalability and management. With a robust setup like this, you can focus on enhancing your agents’ capabilities rather than worrying about deployment challenges. +# 🔐 Swarms x Phala Deployment Guide +This guide will walk you through deploying your project to Phala's Trusted Execution Environment (TEE). +## 📋 Prerequisites --------------------------------------------------- +- Docker installed on your system +- A DockerHub account +- Access to Phala Cloud dashboard -# File: swarms_cloud/create_api.md +## 🛡️ TEE Overview -# CreateNow API Documentation +For detailed instructions about Trusted Execution Environment setup, please refer to our [TEE Documentation](./tee/README.md). -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. +## 🚀 Deployment Steps ---- +### 1. Build and Publish Docker Image -## **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: +```bash +# Build the Docker image +docker compose build -t /swarm-agent-node:latest -### **Claim Your Key** -``` -https://createnow.xyz/account +# Push to DockerHub +docker push /swarm-agent-node:latest ``` -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. Deploy to Phala Cloud ---- +Choose one of these deployment methods: +- Use [tee-cloud-cli](https://github.com/Phala-Network/tee-cloud-cli) (Recommended) +- Deploy manually via the [Phala Cloud Dashboard](https://cloud.phala.network/) -## **2. Generation Endpoint** -The generation endpoint allows you to create AI-generated content using natural language prompts. +### 3. Verify TEE Attestation -### **Endpoint** -``` -POST https://createnow.xyz/api/v1/generate -``` +Visit the [TEE Attestation Explorer](https://proof.t16z.com/) to check and verify your agent's TEE proof. -### **Authentication** -Include a Bearer token in the `Authorization` header for all requests: -``` -Authorization: Bearer YOUR_API_KEY -``` +## 📝 Docker Configuration -### **Basic Usage** -The simplest way to use the API is to send a prompt. The system will automatically detect the appropriate media type. +Below is a sample Docker Compose configuration for your Swarms agent: -#### **Example Request (Basic)** -```json -{ - "prompt": "a beautiful sunset over the ocean" -} +```yaml +services: + swarms-agent-server: + image: swarms-agent-node:latest + platform: linux/amd64 + volumes: + - /var/run/tappd.sock:/var/run/tappd.sock + - swarms:/app + restart: always + ports: + - 8000:8000 + command: # Sample MCP Server + - /bin/sh + - -c + - | + cd /app/mcp_example + python mcp_test.py +volumes: + swarms: ``` -### **Advanced Options** -You can specify additional parameters for finer control over the output. +## 📚 Additional Resources -#### **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 | +For more comprehensive documentation and examples, visit our [Official Documentation](https://docs.swarms.world/en/latest/). -#### **Example Request (Advanced)** -```json -{ - "prompt": "create an upbeat jazz melody", - "type": "music", - "count": 2, - "duration": 30 -} -``` +--- -### **Response Format** +> **Note**: Make sure to replace `` with your actual DockerHub username when building and pushing the image. -#### **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 -} -``` +# File: swarms_cloud\production_deployment.md ---- +# Enterprise Guide to High-Performance Multi-Agent LLM Deployments +------- -## **3. Examples in Multiple Languages** +As large language models (LLMs) continue to advance and enable a wide range of powerful applications, enterprises are increasingly exploring multi-agent architectures to leverage the collective capabilities of multiple LLMs. However, coordinating and optimizing the performance of these complex multi-agent systems presents significant challenges. -### **Python** -```python -import requests +This comprehensive guide provides enterprise architects, engineering leaders, and technical decision-makers with a strategic framework for maximizing performance across multi-agent LLM deployments. Developed through extensive research and collaboration with industry partners, this guide distills best practices, proven techniques, and cutting-edge methodologies into seven core principles. -url = "https://createnow.xyz/api/v1/generate" -headers = { - "Authorization": "Bearer YOUR_API_KEY", - "Content-Type": "application/json" -} +By implementing the recommendations outlined in this guide, organizations can achieve superior latency, throughput, and resource utilization while ensuring scalability, cost-effectiveness, and optimal user experiences. Whether powering customer-facing conversational agents, driving internal knowledge management systems, or fueling mission-critical decision support tools, high-performance multi-agent LLM deployments will be pivotal to unlocking the full potential of this transformative technology. -payload = { - "prompt": "a futuristic cityscape at night", - "type": "image", - "count": 2 -} +## Introduction -response = requests.post(url, json=payload, headers=headers) -print(response.json()) -``` +The rise of large language models (LLMs) has ushered in a new era of human-machine interaction, enabling enterprises to develop sophisticated natural language processing (NLP) applications that can understand, generate, and reason with human-like text. However, as the complexity and scale of LLM deployments grow, traditional monolithic architectures are increasingly challenged to meet the stringent performance, scalability, and cost requirements of enterprise environments. -### **Node.js** -```javascript -const axios = require('axios'); +Multi-agent architectures, which coordinate the collective capabilities of multiple specialized LLMs, have emerged as a powerful paradigm for addressing these challenges. By distributing workloads across a cohort of agents, each optimized for specific tasks or domains, multi-agent systems can deliver superior performance, resilience, and adaptability compared to single-model solutions. -const url = "https://createnow.xyz/api/v1/generate"; -const headers = { - Authorization: "Bearer YOUR_API_KEY", - "Content-Type": "application/json" -}; +However, realizing the full potential of multi-agent LLM deployments requires a strategic approach to system design, optimization, and ongoing management. This guide presents a comprehensive framework for maximizing performance across seven core principles, each underpinned by a range of proven techniques and methodologies. -const payload = { - prompt: "a futuristic cityscape at night", - type: "image", - count: 2 -}; +Whether you are architecting a customer-facing conversational agent, building an internal knowledge management platform, or developing a mission-critical decision support system, this guide will equip you with the insights and best practices necessary to unlock the full potential of multi-agent LLM deployments within your enterprise. -axios.post(url, payload, { headers }) - .then(response => { - console.log(response.data); - }) - .catch(error => { - console.error(error.response.data); - }); -``` +## Principle 1: Distribute Token Processing +---------------------------------------- -### **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 -}' -``` +At the heart of every LLM deployment lies the fundamental challenge of optimizing token processing -- the rate at which the model consumes and generates text inputs and outputs. In multi-agent architectures, distributing and parallelizing token processing across multiple agents is a critical performance optimization strategy. -### **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); - } -} -``` +### Agent Specialization ---- +One of the key advantages of multi-agent architectures is the ability to dedicate specific agents to specialized tasks or domains. By carefully matching agents to the workloads they are optimized for, enterprises can maximize overall throughput and minimize latency. -## **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. | +For example, in a conversational agent deployment, one agent may be optimized for intent recognition and query understanding, while another is fine-tuned for generating coherent, context-aware responses. In a document processing pipeline, separate agents could be dedicated to tasks such as named entity recognition, sentiment analysis, and summarization. ---- +To effectively leverage agent specialization, enterprises should: -## **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. +- Conduct a thorough analysis of their application's workflow and identify distinct tasks or domains that could benefit from dedicated agents. +- Evaluate the strengths and weaknesses of available LLM models and agents, and map them to the identified tasks or domains based on their capabilities and performance characteristics. +- Implement continuous monitoring and performance tuning processes to ensure agents remain optimized for their assigned workloads as models evolve and domain requirements shift. ---- +### Load Balancing -For further support or questions, please contact our support team at [support@createnow.xyz](mailto:support@createnow.xyz). +Even with a well-designed allocation of tasks across specialized agents, fluctuations in workload and demand can create bottlenecks and performance degradation. Effective load balancing strategies are essential to ensure that token processing capacity is dynamically distributed across available agents based on real-time conditions. +Load balancing in multi-agent LLM deployments can be accomplished through a combination of techniques, including: +- **Round-Robin**: Distributing incoming requests across agents in a cyclical fashion, ensuring an even distribution of workload. +- **Least Connections**: Routing requests to the agent with the fewest active connections or outstanding tasks, minimizing the risk of overloading any single agent. +- **Response Time Monitoring**: Continuously monitoring the response times of each agent and dynamically adjusting request routing to favor faster-responding agents. +- **Resource-Based Routing**: Factoring in agent-level resource consumption (e.g., CPU, memory) when making routing decisions, ensuring that overloaded agents are relieved of additional workload. --------------------------------------------------- +Implementing effective load balancing requires careful consideration of the specific characteristics and requirements of your multi-agent deployment, as well as the integration of robust monitoring and analytics capabilities to inform dynamic routing decisions. -# File: swarms_cloud/getting_started.md +### Horizontal Scaling -# Getting Started with State-of-the-Art Vision Language Models (VLMs) Using the Swarms API +While load balancing optimizes the utilization of existing agent resources, horizontal scaling strategies enable organizations to dynamically provision additional token processing capacity to meet demand spikes or handle larger overall workloads. -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. +In multi-agent LLM deployments, horizontal scaling can be achieved through: -#### What Are Vision Language Models? +- **Agent Replication**: Spin up additional instances of existing agents to increase parallel processing capacity for specific tasks or domains. +- **Hybrid Scaling**: Combine agent replication with the dynamic provisioning of additional compute resources (e.g., CPU, GPU) to support the increased agent count. +- **Serverless Deployment**: Leverage serverless computing platforms (e.g., AWS Lambda, Google Cloud Functions) to automatically scale agent instances based on real-time demand, minimizing idle resource consumption. -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. +Effective horizontal scaling requires robust orchestration and management capabilities, as well as seamless integration with load balancing mechanisms to ensure that incoming workloads are efficiently distributed across the dynamically scaled agent pool. -#### Why Use Swarms API for VLMs? +## Principle 2: Optimize Agent Communication +----------------------------------------- -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. +In multi-agent LLM deployments, efficient inter-agent communication is crucial for coordinating tasks, exchanging context and intermediate results, and maintaining overall system coherence. However, communication overhead can quickly become a performance bottleneck if not carefully managed. -#### Prerequisites +### Minimizing Overhead -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). +Reducing the volume and complexity of information exchanged between agents is a key strategy for optimizing communication performance. Techniques for minimizing overhead include: -#### Setting Up Your Environment +- **Data Compression**: Applying lossless or lossy compression algorithms to reduce the size of data payloads exchanged between agents, lowering bandwidth requirements and transmission latencies. +- **Information Summarization**: Distilling and summarizing context, results, or other data exchanged between agents to its essential elements, minimizing redundant or non-critical information. +- **Differential Updates**: Rather than transmitting entire data payloads, agents can exchange only the differential updates or deltas required to synchronize their respective states. -First, you'll need to install the `OpenAI` Python library if it's not already installed: +Implementing these techniques requires careful analysis of the specific data exchange patterns and communication requirements within your multi-agent deployment, as well as the integration of appropriate compression, summarization, and differential update algorithms. -```bash -pip install openai -``` +### Prioritizing Critical Information -#### Integrating the Swarms API +In scenarios where communication bandwidth or latency constraints cannot be fully alleviated through overhead reduction techniques, enterprises can prioritize the exchange of critical information over non-essential data. -Here’s a basic guide on how to set up the Swarms API in your Python environment: +This can be achieved through: -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. +- **Prioritized Queuing**: Implementing queuing mechanisms that prioritize the transmission of high-priority, time-sensitive data over lower-priority, non-critical information. +- **Selective Communication**: Dynamically determining which agents require specific pieces of information based on their roles and responsibilities, and selectively transmitting data only to those agents that truly need it. +- **Progressive Information Exchange**: Exchanging information in a progressive or staged manner, with critical elements transmitted first, followed by supplementary or contextual data as bandwidth becomes available. - ```python - from openai import OpenAI +Effective prioritization requires a deep understanding of the interdependencies and information flow within your multi-agent system, as well as the ability to dynamically assess and prioritize data based on its criticality and urgency. - openai_api_key = "your_swarms_key" - openai_api_base = "https://api.swarms.world/v1" - ``` +### Caching and Reusing Context -2. **Initialize Client**: - Initialize your OpenAI client with the provided API key and base URL. +In many multi-agent LLM deployments, agents frequently exchange or operate on shared context, such as user profiles, conversation histories, or domain-specific knowledge bases. Caching and reusing this context information can significantly reduce redundant communication and processing overhead. - ```python - client = OpenAI( - api_key=openai_api_key, - base_url=openai_api_base, - ) - ``` +Strategies for optimizing context caching and reuse include: -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: +- **Agent-Level Caching**: Implementing caching mechanisms within individual agents to store and retrieve frequently accessed context data, minimizing the need for inter-agent communication. +- **Centralized Context Management**: Deploying a dedicated context management service or data store that agents can query and update, ensuring consistent access to the latest context information across the system. +- **Context Versioning and Invalidation**: Implementing versioning and invalidation mechanisms to ensure that cached context data remains fresh and consistent, avoiding stale or outdated information from propagating through the system. - ```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. +### Principle 3: Leverage Agent Specialization +------------------------------------------ -#### Understanding the Response +One of the key advantages of multi-agent architectures is the ability to optimize individual agents for specific tasks, domains, or capabilities. By leveraging agent specialization, enterprises can ensure that each component of their LLM system is finely tuned for maximum performance and quality. -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. +### Task-Specific Optimization -#### Best Practices +Within a multi-agent LLM deployment, different agents may be responsible for distinct tasks such as language understanding, knowledge retrieval, response generation, or post-processing. Optimizing each agent for its designated task can yield significant performance gains and quality improvements. -- **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. +Techniques for task-specific optimization include: -#### Conclusion +- **Prompt Engineering**: Crafting carefully designed prompts that provide the necessary context, instructions, and examples to guide an agent towards optimal performance for its assigned task. +- **Fine-Tuning**: Adapting a pre-trained LLM to a specific task or domain by fine-tuning it on a curated dataset, allowing the agent to specialize and improve its performance on that particular workload. +- **Model Distillation**: Transferring the knowledge and capabilities of a larger, more capable LLM into a smaller, more efficient model specialized for a specific task, balancing performance and quality trade-offs. -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. +Implementing these optimization techniques requires a deep understanding of the capabilities and requirements of each task within your multi-agent system, as well as access to relevant training data and computational resources for fine-tuning and distillation processes. -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. +### Domain Adaptation -Happy coding, and here’s to building more intelligent, multimodal applications! +Many enterprise applications operate within specific domains or verticals, such as finance, healthcare, or legal. Adapting agents to these specialized domains can significantly improve their performance, accuracy, and compliance within the target domain. --------------------------------------------------- +Strategies for domain adaptation include: -# File: swarms_cloud/launch.md +- **Domain-Specific Pre-Training**: Leveraging domain-specific corpora to pre-train LLM agents, imbuing them with a foundational understanding of the language, concepts, and nuances specific to the target domain. +- **Transfer Learning**: Fine-tuning agents that have been pre-trained on general or adjacent domains, transferring their existing knowledge and capabilities to the target domain while optimizing for its specific characteristics. +- **Domain Persona Injection**: Injecting domain-specific personas, traits, or constraints into agents during fine-tuning or deployment, shaping their behavior and outputs to align with domain-specific norms and requirements. -# Swarms Cloud API Client Documentation +Effective domain adaptation requires access to high-quality, domain-specific training data, as well as close collaboration with subject matter experts to ensure that agents are properly calibrated to meet the unique demands of the target domain. -## Overview -The Swarms Cloud API Client is a production-grade Python library for interacting with the Swarms Cloud Agent API. It provides a comprehensive interface for managing, executing, and monitoring cloud-based agents. +### Ensemble Techniques -## Installation -```bash -pip install swarms-cloud -``` +In complex multi-agent deployments, individual agents may excel at specific subtasks or aspects of the overall workflow. Ensemble techniques that combine the outputs or predictions of multiple specialized agents can often outperform any single agent, leveraging the collective strengths of the ensemble. -## Quick Start -```python -from swarms_cloud import SwarmCloudAPI, AgentCreate +Common ensemble techniques for multi-agent LLM systems include: -# Initialize the client -client = SwarmCloudAPI( - base_url="https://swarmcloud-285321057562.us-central1.run.app", - api_key="your_api_key_here" -) +- **Voting**: Combining the outputs or predictions of multiple agents through majority voting, weighted voting, or other consensus mechanisms. +- **Stacking**: Training a meta-agent to combine and optimize the outputs of multiple base agents, effectively learning to leverage their collective strengths. +- **Blending**: Combining the outputs of multiple agents through weighted averaging, linear interpolation, or other blending techniques, allowing for nuanced integration of diverse perspectives. -# Create an agent -agent_data = AgentCreate( - name="TranslateAgent", - description="Translates text between languages", - code=""" - def main(request, store): - text = request.payload.get('text', '') - return f'Translated: {text}' - """, - requirements="requests==2.25.1", - envs="DEBUG=True" -) +Implementing effective ensemble techniques requires careful analysis of the strengths, weaknesses, and complementary capabilities of individual agents, as well as the development of robust combination strategies that can optimally leverage the ensemble's collective intelligence. -new_agent = client.create_agent(agent_data) -print(f"Created agent with ID: {new_agent.id}") -``` +### Principle 4: Implement Dynamic Scaling +-------------------------------------- -## Client Configuration +The demand and workload patterns of enterprise LLM deployments can be highly dynamic, with significant fluctuations driven by factors such as user activity, data ingestion schedules, or periodic batch processing. Implementing dynamic scaling strategies allows organizations to optimally provision and allocate resources in response to these fluctuations, ensuring consistent performance while minimizing unnecessary costs. -### Constructor Parameters +### Autoscaling -| Parameter | Type | Required | Default | Description | -|-----------|------|----------|----------|-------------| -| base_url | str | No | https://swarmcloud-285321057562.us-central1.run.app | The base URL of the SwarmCloud API | -| api_key | str | Yes | None | Your SwarmCloud API key | -| timeout | float | No | 10.0 | Request timeout in seconds | +Autoscaling is a core capability that enables the automatic adjustment of compute resources (e.g., CPU, GPU, memory) and agent instances based on real-time demand patterns and workload metrics. By dynamically scaling resources up or down, enterprises can maintain optimal performance and resource utilization, avoiding both over-provisioning and under-provisioning scenarios. -## Data Models +Effective autoscaling in multi-agent LLM deployments requires: -### AgentCreate -Model for creating new agents. +- **Monitoring and Metrics**: Implementing robust monitoring and metrics collection mechanisms to track key performance indicators (KPIs) such as request rates, response times, resource utilization, and agent-level metrics. +- **Scaling Policies**: Defining scaling policies that specify the conditions and thresholds for triggering automatic scaling actions, such as provisioning additional agents or compute resources when certain KPIs are breached. +- **Scaling Orchestration**: Integrating autoscaling capabilities with resource orchestration and management tools (e.g., Kubernetes, AWS Auto Scaling) to seamlessly provision, configure, and integrate new resources into the existing multi-agent deployment. -| Field | Type | Required | Default | Description | -|-------|------|----------|----------|-------------| -| name | str | Yes | - | Name of the agent | -| description | str | No | None | Description of the agent's purpose | -| code | str | Yes | - | Python code that defines the agent's behavior | -| requirements | str | No | None | Python package requirements (pip format) | -| envs | str | No | None | Environment variables for the agent | -| autoscaling | bool | No | False | Enable/disable concurrent execution scaling | +By automating the scaling process, enterprises can respond rapidly to workload fluctuations, ensuring consistent performance and optimal resource utilization without the need for manual intervention. -### AgentUpdate -Model for updating existing agents. +### Spot Instance Utilization -| Field | Type | Required | Default | Description | -|-------|------|----------|----------|-------------| -| name | str | No | None | Updated name of the agent | -| description | str | No | None | Updated description | -| code | str | No | None | Updated Python code | -| requirements | str | No | None | Updated package requirements | -| autoscaling | bool | No | None | Updated autoscaling setting | +Many cloud providers offer spot instances or preemptible resources at significantly discounted prices compared to on-demand or reserved instances. While these resources may be reclaimed with little notice, they can be leveraged judiciously within multi-agent LLM deployments to reduce operational costs. -## API Methods +Strategies for leveraging spot instances include: -### List Agents -Retrieve all available agents. +- **Fault-Tolerant Agent Deployment**: Deploying certain agents or components of the multi-agent system on spot instances, while ensuring that these components can be rapidly and seamlessly replaced or migrated in the event of instance preemption. +- **Batch Workload Offloading**: Offloading batch processing workloads or non-time-sensitive tasks to spot instances, leveraging their cost-effectiveness while minimizing the impact of potential disruptions. +- **Hybrid Provisioning**: Implementing a hybrid approach that combines on-demand or reserved instances for mission-critical components with spot instances for more flexible or elastic workloads. -```python -agents = client.list_agents() -for agent in agents: - print(f"Agent: {agent.name} (ID: {agent.id})") -``` +Effective spot instance utilization requires careful architectural considerations to ensure fault tolerance and minimize the impact of potential disruptions, as well as robust monitoring and automation capabilities to seamlessly replace or migrate workloads in response to instance preemption events. -**Returns**: List[AgentOut] +### Serverless Deployments -### Create Agent -Create a new agent with the specified configuration. +Serverless computing platforms, such as AWS Lambda, Google Cloud Functions, or Azure Functions, offer a compelling alternative to traditional server-based deployments. By automatically scaling compute resources based on real-time demand and charging only for the resources consumed, serverless architectures can provide significant cost savings and operational simplicity. -```python -agent_data = AgentCreate( - name="DataProcessor", - description="Processes incoming data streams", - code=""" - def main(request, store): - data = request.payload.get('data', []) - return {'processed': len(data)} - """, - requirements="pandas==1.4.0\nnumpy==1.21.0", - envs="PROCESSING_MODE=fast", - autoscaling=True -) +Leveraging serverless deployments for multi-agent LLM systems can be achieved through: -new_agent = client.create_agent(agent_data) -``` +- **Function-as-a-Service (FaaS) Agents**: Deploying individual agents or components of the multi-agent system as serverless functions, allowing for rapid and automatic scaling in response to fluctuating workloads. +- **Event-Driven Architectures**: Designing the multi-agent system to operate in an event-driven manner, with agents triggered and executed in response to specific events or data ingestion, aligning with the serverless execution model. +- **Hybrid Deployments**: Combining serverless components with traditional server-based components, leveraging the strengths and cost advantages of each deployment model for different aspects of the multi-agent system. -**Returns**: AgentOut +Adopting serverless architectures requires careful consideration of factors such as execution duration limits, cold start latencies, and integration with other components of the multi-agent deployment. However, when implemented effectively, serverless deployments can provide unparalleled scalability, cost-efficiency, and operational simplicity for dynamic, event-driven workloads. -### Get Agent -Retrieve details of a specific agent. -```python -agent = client.get_agent("agent_id_here") -print(f"Agent details: {agent}") -``` +### Principle 5: Employ Selective Execution +--------------------------------------- -**Parameters**: -- agent_id (str): The unique identifier of the agent +Not every input or request within a multi-agent LLM deployment requires the full execution of all agents or the complete processing pipeline. Selectively invoking agents or tasks based on input characteristics or intermediate results can significantly optimize performance by avoiding unnecessary computation and resource consumption. -**Returns**: AgentOut +### Input Filtering -### Update Agent -Update an existing agent's configuration. +Implementing input filtering mechanisms allows enterprises to reject or bypass certain inputs before they are processed by the multi-agent system. This can be achieved through techniques such as: -```python -update_data = AgentUpdate( - name="UpdatedProcessor", - description="Enhanced data processing capabilities", - code="def main(request, store):\n return {'status': 'updated'}" -) +- **Blacklisting/Whitelisting**: Maintaining lists of inputs (e.g., specific phrases, URLs, or content types) that should be automatically rejected or allowed, based on predefined criteria. +- **Rules-Based Filtering**: Defining a set of rules or heuristics to assess the suitability or relevance of an input for further processing, based on factors such as language, content, or metadata. +- **Confidence Thresholding**: Leveraging pre-processing agents or models to assess the likelihood that an input is relevant or valuable, and filtering out inputs that fall below a predetermined confidence threshold. -updated_agent = client.update_agent("agent_id_here", update_data) -``` +Effective input filtering requires careful consideration of the specific requirements, constraints, and objectives of your multi-agent deployment, as well as ongoing monitoring and adjustment of filtering rules and thresholds to maintain optimal performance and accuracy. -**Parameters**: -- agent_id (str): The unique identifier of the agent -- update (AgentUpdate): The update data +### Early Stopping -**Returns**: AgentOut +In many multi-agent LLM deployments, intermediate results or predictions generated by early-stage agents can be used to determine whether further processing is required or valuable. Early stopping mechanisms allow enterprises to terminate execution pipelines when specific conditions or thresholds are met, avoiding unnecessary downstream processing. -### Execute Agent -Manually execute an agent with optional payload data. +Techniques for implementing early stopping include: -```python -# Execute with payload -result = client.execute_agent( - "agent_id_here", - payload={"text": "Hello, World!"} -) +- **Confidence-Based Stopping**: Monitoring the confidence scores or probabilities associated with intermediate results, and terminating execution if a predefined confidence threshold is exceeded. +- **Exception-Based Stopping**: Defining specific intermediate results or conditions that indicate that further processing is unnecessary or undesirable, and terminating execution upon encountering these exceptions. +- **Adaptive Stopping**: Employing machine learning models or reinforcement learning agents to dynamically determine when to terminate execution based on learned patterns and trade-offs between accuracy, latency, and resource consumption. -# Execute without payload -result = client.execute_agent("agent_id_here") -``` +Effective early stopping requires a deep understanding of the interdependencies and decision points within your multi-agent workflow, as well as careful tuning and monitoring to ensure that stopping conditions are calibrated to maintain an optimal balance between performance and accuracy. -**Parameters**: -- agent_id (str): The unique identifier of the agent -- payload (Optional[Dict[str, Any]]): Execution payload data +### Conditional Branching -**Returns**: Dict[str, Any] +Rather than executing a linear, fixed pipeline of agents, conditional branching allows multi-agent systems to dynamically invoke different agents or execution paths based on input characteristics or intermediate results. This can significantly optimize resource utilization by ensuring that only the necessary agents and processes are executed for a given input or scenario. -### Get Agent History -Retrieve the execution history and logs for an agent. +Implementing conditional branching involves: -```python -history = client.get_agent_history("agent_id_here") -for execution in history.executions: - print(f"[{execution.timestamp}] {execution.log}") -``` +- **Decision Points**: Identifying key points within the multi-agent workflow where branching decisions can be made based on input or intermediate data. +- **Branching Logic**: Defining the rules, conditions, or machine learning models that will evaluate the input or intermediate data and determine the appropriate execution path or agent invocation. +- **Execution Routing**: Integrating mechanisms to dynamically route inputs or intermediate data to the appropriate agents or processes based on the branching decision. -**Parameters**: -- agent_id (str): The unique identifier of the agent +Conditional branching can be particularly effective in scenarios where inputs or workloads exhibit distinct characteristics or require significantly different processing pipelines, allowing enterprises to optimize resource allocation and minimize unnecessary computation. -**Returns**: AgentExecutionHistory +### Principle 6: Optimize User Experience +------------------------------------- -### Batch Execute Agents -Execute multiple agents simultaneously with the same payload. +While many of the principles outlined in this guide focus on optimizing backend performance and resource utilization, delivering an exceptional user experience is also a critical consideration for enterprise multi-agent LLM deployments. By minimizing perceived wait times and providing real-time progress updates, organizations can ensure that users remain engaged and satisfied, even during periods of high workload or resource constraints. -```python -# Get list of agents -agents = client.list_agents() +### Streaming Responses -# Execute batch with payload -results = client.batch_execute_agents( - agents=agents[:3], # Execute first three agents - payload={"data": "test"} -) +One of the most effective techniques for minimizing perceived wait times is to stream responses or outputs to users as they are generated, rather than waiting for the entire response to be completed before delivering it. This approach is particularly valuable in conversational agents, document summarization, or other scenarios where outputs can be naturally segmented and delivered incrementally. -print(f"Batch execution results: {results}") -``` +Implementing streaming responses requires: -**Parameters**: -- agents (List[AgentOut]): List of agents to execute -- payload (Optional[Dict[str, Any]]): Shared execution payload +- **Partial Output Generation**: Modifying agents or models to generate and emit outputs in a streaming or incremental fashion, rather than producing the entire output in a single, monolithic operation. +- **Streaming Data Pipelines**: Integrating streaming data pipelines and message queues to enable the efficient and reliable transmission of partial outputs from agents to user-facing interfaces or applications. +- **Incremental Rendering**: Updating user interfaces and displays to incrementally render or populate with newly streamed output segments, providing a seamless and real-time experience for end-users. -**Returns**: List[Any] +By delivering outputs as they are generated, streaming responses can significantly improve the perceived responsiveness and interactivity of multi-agent LLM deployments, even in scenarios where the overall processing time remains unchanged. -### Health Check -Check the API's health status. +### Progress Indicators -```python -status = client.health() -print(f"API Status: {status}") -``` +In cases where streaming responses may not be feasible or appropriate, providing visual or textual indicators of ongoing processing and progress can help manage user expectations and improve the overall experience. Progress indicators can be implemented through techniques such as: -**Returns**: Dict[str, Any] +- **Loader Animations**: Displaying simple animations or spinner graphics to indicate that processing is underway and provide a sense of activity and progress. +- **Progress Bars**: Rendering progress bars or completion indicators based on estimated or actual progress through multi-agent workflows or processing pipelines. +- **Status Updates**: Periodically updating user interfaces with textual status messages or descriptions of the current processing stage, providing users with a more detailed understanding of the system's activities. -## Error Handling -The client uses exception handling to manage various error scenarios: +Effective progress indicators require careful integration with monitoring and telemetry capabilities to accurately track and communicate the progress of multi-agent workflows, as well as thoughtful user experience design to ensure that indicators are clear, unobtrusive, and aligned with user expectations. -```python -from swarms_cloud import SwarmCloudAPI -import httpx +### Chunked Delivery -try: - client = SwarmCloudAPI(api_key="your_api_key_here") - agents = client.list_agents() -except httpx.HTTPError as http_err: - print(f"HTTP error occurred: {http_err}") -except Exception as err: - print(f"An unexpected error occurred: {err}") -finally: - client.close() -``` +In scenarios where outputs or responses cannot be effectively streamed or rendered incrementally, chunked delivery can provide a middle ground between delivering the entire output at once and streaming individual tokens or characters. By breaking larger outputs into smaller, more manageable chunks and delivering them individually, enterprises can improve perceived responsiveness and provide a more engaging user experience. -## Context Manager Support -The client can be used with Python's context manager: +Implementing chunked delivery involves: -```python -with SwarmCloudAPI(api_key="your_api_key_here") as client: - status = client.health() - print(f"API Status: {status}") - # Client automatically closes after the with block -``` +- **Output Segmentation**: Identifying logical breakpoints or segmentation boundaries within larger outputs, such as paragraphs, sections, or other structural elements. +- **Chunking Mechanisms**: Integrating mechanisms to efficiently break outputs into individual chunks and transmit or render them sequentially, with minimal delay between chunks. +- **Chunk Rendering**: Updating user interfaces or displays to seamlessly render or append new output chunks as they are received, providing a sense of continuous progress and minimizing the perception of extended waiting periods. -## Best Practices +Chunked delivery can be particularly effective in scenarios where outputs are inherently structured or segmented, such as document generation, report creation, or multi-step instructions or workflows. -1. Always close the client when finished: -```python -client = SwarmCloudAPI(api_key="your_api_key_here") -try: - # Your code here -finally: - client.close() -``` +## Principle 7: Leverage Hybrid Approaches +--------------------------------------- -2. Use context managers for automatic cleanup: -```python -with SwarmCloudAPI(api_key="your_api_key_here") as client: - # Your code here -``` +While multi-agent LLM architectures offer numerous advantages, they should not be viewed as a one-size-fits-all solution. In many cases, combining LLM agents with traditional techniques, optimized components, or external services can yield superior performance, cost-effectiveness, and resource utilization compared to a pure LLM-based approach. + +### Task Offloading -3. Handle errors appropriately: -```python -try: - result = client.execute_agent("agent_id", payload={"data": "test"}) -except httpx.HTTPError as e: - logger.error(f"HTTP error: {e}") - # Handle error appropriately -``` +Certain tasks or subtasks within a larger multi-agent workflow may be more efficiently handled by dedicated, optimized components or external services, rather than relying solely on LLM agents. Task offloading involves identifying these opportunities and integrating the appropriate components or services into the overall architecture. -4. Set appropriate timeouts for your use case: -```python -client = SwarmCloudAPI( - api_key="your_api_key_here", - timeout=30.0 # Longer timeout for complex operations -) -``` +Examples of task offloading in multi-agent LLM deployments include: -## Complete Example -Here's a complete example showcasing various features of the client: +- **Regular Expression Matching**: Offloading pattern matching or text extraction tasks to dedicated regular expression engines, which can often outperform LLM-based approaches in terms of speed and efficiency. +- **Structured Data Processing**: Leveraging specialized data processing engines or databases for tasks involving structured data, such as querying, filtering, or transforming tabular or relational data. +- **External APIs and Services**: Integrating with external APIs or cloud services for specific tasks, such as speech recognition, translation, or knowledge base lookup, leveraging the specialized capabilities and optimizations of these dedicated services. -```python -from swarms_cloud import SwarmCloudAPI, AgentCreate, AgentUpdate -import httpx +Effective task offloading requires a thorough understanding of the strengths and limitations of both LLM agents and traditional components, as well as careful consideration of integration points, data flows, and performance trade-offs within the overall multi-agent architecture. -def main(): - with SwarmCloudAPI(api_key="your_api_key_here") as client: - # Create an agent - agent_data = AgentCreate( - name="DataAnalyzer", - description="Analyzes incoming data streams", - code=""" - def main(request, store): - data = request.payload.get('data', []) - return { - 'count': len(data), - 'summary': 'Data processed successfully' - } - """, - requirements="pandas==1.4.0", - autoscaling=True - ) - - try: - # Create the agent - new_agent = client.create_agent(agent_data) - print(f"Created agent: {new_agent.name} (ID: {new_agent.id})") - - # Execute the agent - result = client.execute_agent( - new_agent.id, - payload={"data": [1, 2, 3, 4, 5]} - ) - print(f"Execution result: {result}") - - # Update the agent - update_data = AgentUpdate( - description="Enhanced data analysis capabilities" - ) - updated_agent = client.update_agent(new_agent.id, update_data) - print(f"Updated agent: {updated_agent.name}") - - # Get execution history - history = client.get_agent_history(new_agent.id) - print(f"Execution history: {history}") - - except httpx.HTTPError as e: - print(f"HTTP error occurred: {e}") - except Exception as e: - print(f"Unexpected error: {e}") +### Caching and Indexing -if __name__ == "__main__": - main() -``` +While LLMs excel at generating dynamic, context-aware outputs, they can be less efficient when dealing with static or frequently accessed information or knowledge. Caching and indexing strategies can help mitigate this limitation by minimizing redundant LLM processing and enabling faster retrieval of commonly accessed data. -## Logging -The client uses the `loguru` library for logging. You can configure the logging level and format: +Techniques for leveraging caching and indexing in multi-agent LLM deployments include: -```python -from loguru import logger +**Output Caching**: Caching the outputs or responses generated by LLM agents, allowing for rapid retrieval and reuse in cases where the same or similar input is encountered in the future. -# Configure logging -logger.add("swarmcloud.log", rotation="500 MB") +**Knowledge Base Indexing**: Indexing domain-specific knowledge bases, data repositories, or other static information sources using traditional search and information retrieval techniques. This allows LLM agents to efficiently query and incorporate relevant information into their outputs, without needing to process or generate this content from scratch. -client = SwarmCloudAPI(api_key="your_api_key_here") -``` +**Contextual Caching**: Caching not only outputs but also the contextual information and intermediate results generated during multi-agent workflows. This enables more efficient reuse and continuation of previous processing in scenarios where contexts are long-lived or recurring. -## Performance Considerations +Implementing effective caching and indexing strategies requires careful consideration of data freshness, consistency, and invalidation mechanisms, as well as seamless integration with LLM agents and multi-agent workflows to ensure that cached or indexed data is appropriately leveraged and updated. -1. **Connection Reuse**: The client reuses HTTP connections by default, improving performance for multiple requests. +### Pre-computation and Lookup -2. **Timeout Configuration**: Set appropriate timeouts based on your use case: -```python -client = SwarmCloudAPI( - api_key="your_api_key_here", - timeout=5.0 # Shorter timeout for time-sensitive operations -) -``` +In certain scenarios, especially those involving constrained or well-defined inputs, pre-computing and lookup strategies can be leveraged to minimize or entirely avoid the need for real-time LLM processing. By generating and storing potential outputs or responses in advance, enterprises can significantly improve performance and reduce resource consumption. -3. **Batch Operations**: Use batch_execute_agents for multiple agent executions: -```python -results = client.batch_execute_agents( - agents=agents, - payload=shared_payload -) -``` +Approaches for pre-computation and lookup include: -## Rate Limiting -The client respects API rate limits but does not implement retry logic. Implement your own retry mechanism if needed: +**Output Pre-generation**: For inputs or scenarios with a limited set of potential outputs, pre-generating and storing all possible responses, allowing for rapid retrieval and delivery without the need for real-time LLM execution. -```python -from tenacity import retry, stop_after_attempt, wait_exponential +**Retrieval-Based Responses**: Developing retrieval models or techniques that can identify and surface pre-computed or curated responses based on input characteristics, leveraging techniques such as nearest neighbor search, embedding-based retrieval, or example-based generation. -@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10)) -def execute_with_retry(client, agent_id, payload): - return client.execute_agent(agent_id, payload) -``` +**Hybrid Approaches**: Combining pre-computed or retrieved responses with real-time LLM processing, allowing for the generation of dynamic, context-aware content while still leveraging pre-computed components to optimize performance and resource utilization. -## Thread Safety -The client is not thread-safe by default. For concurrent usage, create separate client instances for each thread or implement appropriate synchronization mechanisms. +Effective implementation of pre-computation and lookup strategies requires careful analysis of input patterns, output distributions, and potential performance gains, as well as robust mechanisms for managing and updating pre-computed data as application requirements or domain knowledge evolves. --------------------------------------------------- +# Conclusion +---------- -# File: swarms_cloud/main.md +As enterprises increasingly embrace the transformative potential of large language models, optimizing the performance, scalability, and cost-effectiveness of these deployments has become a critical imperative. Multi-agent architectures, which coordinate the collective capabilities of multiple specialized LLM agents, offer a powerful paradigm for addressing these challenges. -# Swarm Cloud API Reference +By implementing the seven principles outlined in this guide -- distributing token processing, optimizing agent communication, leveraging agent specialization, implementing dynamic scaling, employing selective execution, optimizing user experience, and leveraging hybrid approaches -- organizations can unlock the full potential of multi-agent LLM deployments. -## Overview +However, realizing these benefits requires a strategic and holistic approach that accounts for the unique requirements, constraints, and objectives of each enterprise. From task-specific optimizations and domain adaptation to dynamic scaling and user experience considerations, maximizing the performance of multi-agent LLM systems demands a deep understanding of the underlying technologies, as well as the ability to navigate the inherent complexities of these sophisticated architectures. + +To learn more about how Swarm Corporation can assist your organization in architecting, deploying, and optimizing high-performance multi-agent LLM solutions, we invite you to book a consultation with one of our agent specialists. Visit to schedule a 30-minute call and explore how our expertise and cutting-edge technologies can drive transformative outcomes for your business. -The AI Chat Completion API processes text and image inputs to generate conversational responses. It supports various configurations to customize response behavior and manage input content. +In the rapidly evolving landscape of artificial intelligence and natural language processing, staying ahead of the curve is essential. Partner with Swarm Corporation, and unlock the full potential of multi-agent LLM deployments, today. -## API Endpoints +[Book a call with us now:](https://calendly.com/swarm-corp/30min) -### Chat Completion URL -`https://api.swarms.world` +-------------------------------------------------- +# File: swarms_cloud\python_client.md +# Swarms Cloud API Client Documentation -- **Endpoint:** `/v1/chat/completions` --- **Full Url** `https://api.swarms.world/v1/chat/completions` -- **Method:** POST -- **Description:** Generates a response based on the provided conversation history and parameters. +## Introduction -#### Request Parameters +The Swarms Cloud API client is a production-grade Python package for interacting with the Swarms API. It provides both synchronous and asynchronous interfaces, making it suitable for a wide range of applications from simple scripts to high-performance, scalable services. -| Parameter | Type | Description | Required | -|---------------|--------------------|-----------------------------------------------------------|----------| -| `model` | string | The AI model identifier. | Yes | -| `messages` | array of objects | A list of chat messages, including the sender's role and content. | Yes | -| `temperature` | float | Controls randomness. Lower values make responses more deterministic. | No | -| `top_p` | float | Controls diversity. Lower values lead to less random completions. | No | -| `max_tokens` | integer | The maximum number of tokens to generate. | No | -| `stream` | boolean | If set to true, responses are streamed back as they're generated. | No | +Key features include: +- Connection pooling and efficient session management +- Automatic retries with exponential backoff +- Circuit breaker pattern for improved reliability +- In-memory caching for frequently accessed resources +- Comprehensive error handling with detailed exceptions +- Full support for asynchronous operations +- Type checking with Pydantic -#### Response Structure +This documentation covers all available client methods with detailed descriptions, parameter references, and usage examples. -- **Success Response Code:** `200 OK` +## Installation -```markdown -{ - "model": string, - "object": string, - "choices": array of objects, - "usage": object -} +```bash +pip install swarms-client ``` -### List Models +## Authentication + +To use the Swarms API, you need an API key. You can obtain your API key from the [Swarms Platform API Keys page](https://swarms.world/platform/api-keys). -- **Endpoint:** `/v1/models` -- **Method:** GET -- **Description:** Retrieves a list of available models. +## Client Initialization -#### Response Structure +The `SwarmsClient` is the main entry point for interacting with the Swarms API. It can be initialized with various configuration options to customize its behavior. -- **Success Response Code:** `200 OK` +```python +from swarms_client import SwarmsClient -```markdown -{ - "data": array of objects -} +# Initialize with default settings +client = SwarmsClient(api_key="your-api-key") + +# Or with custom settings +client = SwarmsClient( + api_key="your-api-key", + base_url="https://swarms-api-285321057562.us-east1.run.app", + timeout=60, + max_retries=3, + retry_delay=1, + log_level="INFO", + pool_connections=100, + pool_maxsize=100, + keep_alive_timeout=5, + max_concurrent_requests=100, + circuit_breaker_threshold=5, + circuit_breaker_timeout=60, + enable_cache=True +) ``` -## Objects +### Parameters -### Request +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `api_key` | `str` | Environment variable `SWARMS_API_KEY` | API key for authentication | +| `base_url` | `str` | `"https://swarms-api-285321057562.us-east1.run.app"` | Base URL for the API | +| `timeout` | `int` | `60` | Timeout for API requests in seconds | +| `max_retries` | `int` | `3` | Maximum number of retry attempts for failed requests | +| `retry_delay` | `int` | `1` | Initial delay between retries in seconds (uses exponential backoff) | +| `log_level` | `str` | `"INFO"` | Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) | +| `pool_connections` | `int` | `100` | Number of connection pools to cache | +| `pool_maxsize` | `int` | `100` | Maximum number of connections to save in the pool | +| `keep_alive_timeout` | `int` | `5` | Keep-alive timeout for connections in seconds | +| `max_concurrent_requests` | `int` | `100` | Maximum number of concurrent requests | +| `circuit_breaker_threshold` | `int` | `5` | Failure threshold for the circuit breaker | +| `circuit_breaker_timeout` | `int` | `60` | Reset timeout for the circuit breaker in seconds | +| `enable_cache` | `bool` | `True` | Whether to enable in-memory caching | -| Field | Type | Description | Required | -|-----------|---------------------|-----------------------------------------------|----------| -| `role` | string | The role of the message sender. | Yes | -| `content` | string or array | The content of the message. | Yes | -| `name` | string | An optional name identifier for the sender. | No | +## Client Methods -### Response +### clear_cache -| Field | Type | Description | -|-----------|--------|------------------------------------| -| `index` | integer| The index of the choice. | -| `message` | object | A `ChatMessageResponse` object. | +Clears the in-memory cache used for caching API responses. -#### UsageInfo +```python +client.clear_cache() +``` -| Field | Type | Description | -|-------------------|---------|-----------------------------------------------| -| `prompt_tokens` | integer | The number of tokens used in the prompt. | -| `total_tokens` | integer | The total number of tokens used. | -| `completion_tokens`| integer| The number of tokens used for the completion. | +## Agent Resource -## Example Requests +The Agent resource provides methods for creating and managing agent completions. -### Text Chat Completion + +### create -```json -POST /v1/chat/completions -{ - "model": "cogvlm-chat-17b", - "messages": [ - { - "role": "user", - "content": "Hello, world!" - } - ], - "temperature": 0.8 -} -``` +Creates an agent completion. -### Image and Text Chat Completion +```python +response = client.agent.create( + agent_config={ + "agent_name": "Researcher", + "description": "Conducts in-depth research on topics", + "model_name": "gpt-4o", + "temperature": 0.7 + }, + task="Research the latest advancements in quantum computing and summarize the key findings" +) -```json -POST /v1/chat/completions -{ - "model": "cogvlm-chat-17b", - "messages": [ - { - "role": "user", - "content": [ - { - "type": "text", - "text": "Describe this image" - }, - { - "type": "image_url", - "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..." - } - ] - } - ], - "temperature": 0.8, - "top_p": 0.9, - "max_tokens": 1024 -} +print(f"Agent ID: {response.id}") +print(f"Output: {response.outputs}") ``` -## Error Codes +#### Parameters -The API uses standard HTTP status codes to indicate the success or failure of an API call. +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `agent_config` | `dict` or `AgentSpec` | Yes | Configuration for the agent | +| `task` | `str` | Yes | The task for the agent to complete | +| `history` | `dict` | No | Optional conversation history | + +The `agent_config` parameter can include the following fields: + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `agent_name` | `str` | Required | Name of the agent | +| `description` | `str` | `None` | Description of the agent's purpose | +| `system_prompt` | `str` | `None` | System prompt to guide the agent's behavior | +| `model_name` | `str` | `"gpt-4o-mini"` | Name of the model to use | +| `auto_generate_prompt` | `bool` | `False` | Whether to automatically generate a prompt | +| `max_tokens` | `int` | `8192` | Maximum tokens in the response | +| `temperature` | `float` | `0.5` | Temperature for sampling (0-1) | +| `role` | `str` | `None` | Role of the agent | +| `max_loops` | `int` | `1` | Maximum number of reasoning loops | +| `tools_dictionary` | `List[Dict]` | `None` | Tools available to the agent | -| Status Code | Description | -|-------------|-----------------------------------| -| 200 | OK - The request has succeeded. | -| 400 | Bad Request - Invalid request format. | -| 500 | Internal Server Error - An error occurred on the server. | +#### Returns +`AgentCompletionResponse` object with the following properties: -## Examples in Various Languages +- `id`: Unique identifier for the completion +- `success`: Whether the completion was successful +- `name`: Name of the agent +- `description`: Description of the agent +- `temperature`: Temperature used for the completion +- `outputs`: Output from the agent +- `usage`: Token usage information +- `timestamp`: Timestamp of the completion -### Python -```python -import requests -import base64 -from PIL import Image -from io import BytesIO - - -# Convert image to Base64 -def image_to_base64(image_path): - with Image.open(image_path) as image: - buffered = BytesIO() - image.save(buffered, format="JPEG") - img_str = base64.b64encode(buffered.getvalue()).decode("utf-8") - return img_str - - -# Replace 'image.jpg' with the path to your image -base64_image = image_to_base64("your_image.jpg") -text_data = {"type": "text", "text": "Describe what is in the image"} -image_data = { - "type": "image_url", - "image_url": {"url": f"data:image/jpeg;base64,{base64_image}"}, -} + +### create_batch -# Construct the request data -request_data = { - "model": "cogvlm-chat-17b", - "messages": [{"role": "user", "content": [text_data, image_data]}], - "temperature": 0.8, - "top_p": 0.9, - "max_tokens": 1024, -} +Creates multiple agent completions in batch. -# Specify the URL of your FastAPI application -url = "https://api.swarms.world/v1/chat/completions" +```python +responses = client.agent.create_batch([ + { + "agent_config": { + "agent_name": "Researcher", + "model_name": "gpt-4o-mini", + "temperature": 0.5 + }, + "task": "Summarize the latest quantum computing research" + }, + { + "agent_config": { + "agent_name": "Writer", + "model_name": "gpt-4o", + "temperature": 0.7 + }, + "task": "Write a blog post about AI safety" + } +]) -# Send the request -response = requests.post(url, json=request_data) -# Print the response from the server -print(response.text) +for i, response in enumerate(responses): + print(f"Agent {i+1} ID: {response.id}") + print(f"Output: {response.outputs}") + print("---") ``` -### Example API Request in Node -```js -const fs = require('fs'); -const https = require('https'); -const sharp = require('sharp'); - -// Convert image to Base64 -async function imageToBase64(imagePath) { - try { - const imageBuffer = await sharp(imagePath).jpeg().toBuffer(); - return imageBuffer.toString('base64'); - } catch (error) { - console.error('Error converting image to Base64:', error); - } -} +#### Parameters -// Main function to execute the workflow -async function main() { - const base64Image = await imageToBase64("your_image.jpg"); - const textData = { type: "text", text: "Describe what is in the image" }; - const imageData = { - type: "image_url", - image_url: { url: `data:image/jpeg;base64,${base64Image}` }, - }; +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `completions` | `List[Dict or AgentCompletion]` | Yes | List of agent completion requests | - // Construct the request data - const requestData = JSON.stringify({ - model: "cogvlm-chat-17b", - messages: [{ role: "user", content: [textData, imageData] }], - temperature: 0.8, - top_p: 0.9, - max_tokens: 1024, - }); +Each item in the `completions` list should have the same structure as the parameters for the `create` method. - const options = { - hostname: 'api.swarms.world', - path: '/v1/chat/completions', - method: 'POST', - headers: { - 'Content-Type': 'application/json', - 'Content-Length': requestData.length, - }, - }; +#### Returns - const req = https.request(options, (res) => { - let responseBody = ''; +List of `AgentCompletionResponse` objects with the same properties as the return value of the `create` method. - res.on('data', (chunk) => { - responseBody += chunk; - }); + +### acreate - res.on('end', () => { - console.log('Response:', responseBody); - }); - }); +Creates an agent completion asynchronously. - req.on('error', (error) => { - console.error(error); - }); +```python +import asyncio +from swarms_client import SwarmsClient - req.write(requestData); - req.end(); -} +async def main(): + async with SwarmsClient(api_key="your-api-key") as client: + response = await client.agent.acreate( + agent_config={ + "agent_name": "Researcher", + "description": "Conducts in-depth research", + "model_name": "gpt-4o" + }, + task="Research the impact of quantum computing on cryptography" + ) + + print(f"Agent ID: {response.id}") + print(f"Output: {response.outputs}") -main(); +asyncio.run(main()) ``` -### Example API Request in Go - -```go -package main +#### Parameters -import ( - "bytes" - "encoding/base64" - "encoding/json" - "fmt" - "image" - "image/jpeg" - _ "image/png" // Register PNG format - "io" - "net/http" - "os" -) +Same as the `create` method. -// imageToBase64 converts an image to a Base64-encoded string. -func imageToBase64(imagePath string) (string, error) { - file, err := os.Open(imagePath) - if err != nil { - return "", err - } - defer file.Close() +#### Returns - img, _, err := image.Decode(file) - if err != nil { - return "", err - } +Same as the `create` method. - buf := new(bytes.Buffer) - err = jpeg.Encode(buf, img, nil) - if err != nil { - return "", err - } + +### acreate_batch - return base64.StdEncoding.EncodeToString(buf.Bytes()), nil -} +Creates multiple agent completions in batch asynchronously. -// main is the entry point of the program. -func main() { - base64Image, err := imageToBase64("your_image.jpg") - if err != nil { - fmt.Println("Error converting image to Base64:", err) - return - } +```python +import asyncio +from swarms_client import SwarmsClient - requestData := map[string]interface{}{ - "model": "cogvlm-chat-17b", - "messages": []map[string]interface{}{ +async def main(): + async with SwarmsClient(api_key="your-api-key") as client: + responses = await client.agent.acreate_batch([ { - "role": "user", - "content": []map[string]string{{"type": "text", "text": "Describe what is in the image"}, {"type": "image_url", "image_url": {"url": fmt.Sprintf("data:image/jpeg;base64,%s", base64Image)}}}, + "agent_config": { + "agent_name": "Researcher", + "model_name": "gpt-4o-mini" + }, + "task": "Summarize the latest quantum computing research" }, - }, - "temperature": 0.8, - "top_p": 0.9, - "max_tokens": 1024, - } + { + "agent_config": { + "agent_name": "Writer", + "model_name": "gpt-4o" + }, + "task": "Write a blog post about AI safety" + } + ]) + + for i, response in enumerate(responses): + print(f"Agent {i+1} ID: {response.id}") + print(f"Output: {response.outputs}") + print("---") - requestBody, err := json.Marshal(requestData) - if err != nil { - fmt.Println("Error marshaling request data:", err) - return - } +asyncio.run(main()) +``` - url := "https://api.swarms.world/v1/chat/completions" - request, err := http.NewRequest("POST", url, bytes.NewBuffer(requestBody)) - if err != nil { - fmt.Println("Error creating request:", err) - return - } +#### Parameters - request.Header.Set("Content-Type", "application/json") +Same as the `create_batch` method. - client := &http.Client{} - response, err := client.Do(request) - if err != nil { - fmt.Println("Error sending request:", err) - return - } - defer response.Body.Close() +#### Returns - responseBody, err := io.ReadAll(response.Body) - if err != nil { - fmt.Println("Error reading response body:", err) - return - } +Same as the `create_batch` method. - fmt.Println("Response:", string(responseBody)) -} -``` +## Swarm Resource +The Swarm resource provides methods for creating and managing swarm completions. + +### create +Creates a swarm completion. +```python +response = client.swarm.create( + name="Research Swarm", + description="A swarm for research tasks", + swarm_type="SequentialWorkflow", + task="Research quantum computing advances in 2024 and summarize the key findings", + agents=[ + { + "agent_name": "Researcher", + "description": "Conducts in-depth research", + "model_name": "gpt-4o", + "temperature": 0.5 + }, + { + "agent_name": "Critic", + "description": "Evaluates arguments for flaws", + "model_name": "gpt-4o-mini", + "temperature": 0.3 + } + ], + max_loops=3, + return_history=True +) -## Conclusion +print(f"Job ID: {response.job_id}") +print(f"Status: {response.status}") +print(f"Output: {response.output}") +``` -This API reference provides the necessary details to understand and interact with the AI Chat Completion API. By following the outlined request and response formats, users can integrate this API into their applications to generate dynamic and contextually relevant conversational responses. +#### Parameters --------------------------------------------------- +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `name` | `str` | No | Name of the swarm | +| `description` | `str` | No | Description of the swarm | +| `agents` | `List[Dict or AgentSpec]` | No | List of agent specifications | +| `max_loops` | `int` | No | Maximum number of loops (default: 1) | +| `swarm_type` | `str` | No | Type of swarm (see available types) | +| `task` | `str` | Conditional | The task to complete (required if tasks and messages are not provided) | +| `tasks` | `List[str]` | Conditional | List of tasks for batch processing (required if task and messages are not provided) | +| `messages` | `List[Dict]` | Conditional | List of messages to process (required if task and tasks are not provided) | +| `return_history` | `bool` | No | Whether to return the execution history (default: True) | +| `rules` | `str` | No | Rules for the swarm | +| `schedule` | `Dict` | No | Schedule specification for delayed execution | +| `stream` | `bool` | No | Whether to stream the response (default: False) | +| `service_tier` | `str` | No | Service tier ('standard' or 'flex', default: 'standard') | -# File: swarms_cloud/mcp.md +#### Returns -# Swarms API as MCP +`SwarmCompletionResponse` object with the following properties: -- Launch MCP server as a tool -- Put `SWARMS_API_KEY` in `.env` -- Client side code below +- `job_id`: Unique identifier for the job +- `status`: Status of the job +- `swarm_name`: Name of the swarm +- `description`: Description of the swarm +- `swarm_type`: Type of swarm used +- `output`: Output from the swarm +- `number_of_agents`: Number of agents in the swarm +- `service_tier`: Service tier used +- `tasks`: List of tasks processed (if applicable) +- `messages`: List of messages processed (if applicable) + +### create_batch -## Server Side +Creates multiple swarm completions in batch. ```python -# server.py -from datetime import datetime -import os -from typing import Any, Dict, List, Optional +responses = client.swarm.create_batch([ + { + "name": "Research Swarm", + "swarm_type": "auto", + "task": "Research quantum computing advances", + "agents": [ + {"agent_name": "Researcher", "model_name": "gpt-4o"} + ] + }, + { + "name": "Writing Swarm", + "swarm_type": "SequentialWorkflow", + "task": "Write a blog post about AI safety", + "agents": [ + {"agent_name": "Writer", "model_name": "gpt-4o"}, + {"agent_name": "Editor", "model_name": "gpt-4o-mini"} + ] + } +]) -import requests -import httpx -from fastmcp import FastMCP -from pydantic import BaseModel, Field -from swarms import SwarmType -from dotenv import load_dotenv +for i, response in enumerate(responses): + print(f"Swarm {i+1} Job ID: {response.job_id}") + print(f"Status: {response.status}") + print(f"Output: {response.output}") + print("---") +``` -load_dotenv() +#### Parameters -class AgentSpec(BaseModel): - agent_name: Optional[str] = Field( - description="The unique name assigned to the agent, which identifies its role and functionality within the swarm.", - ) - description: Optional[str] = Field( - description="A detailed explanation of the agent's purpose, capabilities, and any specific tasks it is designed to perform.", - ) - system_prompt: Optional[str] = Field( - description="The initial instruction or context provided to the agent, guiding its behavior and responses during execution.", - ) - model_name: Optional[str] = Field( - default="gpt-4o-mini", - description="The name of the AI model that the agent will utilize for processing tasks and generating outputs. For example: gpt-4o, gpt-4o-mini, openai/o3-mini", - ) - auto_generate_prompt: Optional[bool] = Field( - default=False, - description="A flag indicating whether the agent should automatically create prompts based on the task requirements.", - ) - max_tokens: Optional[int] = Field( - default=8192, - description="The maximum number of tokens that the agent is allowed to generate in its responses, limiting output length.", - ) - temperature: Optional[float] = Field( - default=0.5, - description="A parameter that controls the randomness of the agent's output; lower values result in more deterministic responses.", - ) - role: Optional[str] = Field( - default="worker", - description="The designated role of the agent within the swarm, which influences its behavior and interaction with other agents.", - ) - max_loops: Optional[int] = Field( - default=1, - description="The maximum number of times the agent is allowed to repeat its task, enabling iterative processing if necessary.", - ) - # New fields for RAG functionality - rag_collection: Optional[str] = Field( - None, - description="The Qdrant collection name for RAG functionality. If provided, this agent will perform RAG queries.", - ) - rag_documents: Optional[List[str]] = Field( - None, - description="Documents to ingest into the Qdrant collection for RAG. (List of text strings)", - ) - tools: Optional[List[Dict[str, Any]]] = Field( - None, - description="A dictionary of tools that the agent can use to complete its task.", - ) +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `swarms` | `List[Dict or SwarmSpec]` | Yes | List of swarm specifications | +Each item in the `swarms` list should have the same structure as the parameters for the `create` method. -class AgentCompletion(BaseModel): - """ - Configuration for a single agent that works together as a swarm to accomplish tasks. - """ +#### Returns - agent: AgentSpec = Field( - ..., - description="The agent to run.", - ) - task: Optional[str] = Field( - ..., - description="The task to run.", - ) - img: Optional[str] = Field( - None, - description="An optional image URL that may be associated with the swarm's task or representation.", - ) - output_type: Optional[str] = Field( - "list", - description="The type of output to return.", - ) +List of `SwarmCompletionResponse` objects with the same properties as the return value of the `create` method. + +### list_types -class AgentCompletionResponse(BaseModel): - """ - Response from an agent completion. - """ +Lists available swarm types. - agent_id: str = Field( - ..., - description="The unique identifier for the agent that completed the task.", - ) - agent_name: str = Field( - ..., - description="The name of the agent that completed the task.", - ) - agent_description: str = Field( - ..., - description="The description of the agent that completed the task.", - ) - messages: Any = Field( - ..., - description="The messages from the agent completion.", - ) +```python +response = client.swarm.list_types() - cost: Dict[str, Any] = Field( - ..., - description="The cost of the agent completion.", - ) +print(f"Available swarm types:") +for swarm_type in response.swarm_types: + print(f"- {swarm_type}") +``` +#### Returns -class Agents(BaseModel): - """Configuration for a collection of agents that work together as a swarm to accomplish tasks.""" +`SwarmTypesResponse` object with the following properties: - agents: List[AgentSpec] = Field( - description="A list containing the specifications of each agent that will participate in the swarm, detailing their roles and functionalities." - ) +- `success`: Whether the request was successful +- `swarm_types`: List of available swarm types + +### alist_types -class ScheduleSpec(BaseModel): - scheduled_time: datetime = Field( - ..., - description="The exact date and time (in UTC) when the swarm is scheduled to execute its tasks.", - ) - timezone: Optional[str] = Field( - "UTC", - description="The timezone in which the scheduled time is defined, allowing for proper scheduling across different regions.", - ) +Lists available swarm types asynchronously. +```python +import asyncio +from swarms_client import SwarmsClient -class SwarmSpec(BaseModel): - name: Optional[str] = Field( - None, - description="The name of the swarm, which serves as an identifier for the group of agents and their collective task.", - max_length=100, - ) - description: Optional[str] = Field( - None, - description="A comprehensive description of the swarm's objectives, capabilities, and intended outcomes.", - ) - agents: Optional[List[AgentSpec]] = Field( - None, - description="A list of agents or specifications that define the agents participating in the swarm.", - ) - max_loops: Optional[int] = Field( - default=1, - description="The maximum number of execution loops allowed for the swarm, enabling repeated processing if needed.", - ) - swarm_type: Optional[SwarmType] = Field( - None, - description="The classification of the swarm, indicating its operational style and methodology.", - ) - rearrange_flow: Optional[str] = Field( - None, - description="Instructions on how to rearrange the flow of tasks among agents, if applicable.", - ) - task: Optional[str] = Field( - None, - description="The specific task or objective that the swarm is designed to accomplish.", - ) - img: Optional[str] = Field( - None, - description="An optional image URL that may be associated with the swarm's task or representation.", - ) - return_history: Optional[bool] = Field( - True, - description="A flag indicating whether the swarm should return its execution history along with the final output.", - ) - rules: Optional[str] = Field( - None, - description="Guidelines or constraints that govern the behavior and interactions of the agents within the swarm.", - ) - schedule: Optional[ScheduleSpec] = Field( - None, - description="Details regarding the scheduling of the swarm's execution, including timing and timezone information.", - ) - tasks: Optional[List[str]] = Field( - None, - description="A list of tasks that the swarm should complete.", - ) - messages: Optional[List[Dict[str, Any]]] = Field( - None, - description="A list of messages that the swarm should complete.", - ) - # rag_on: Optional[bool] = Field( - # None, - # description="A flag indicating whether the swarm should use RAG.", - # ) - # collection_name: Optional[str] = Field( - # None, - # description="The name of the collection to use for RAG.", - # ) - stream: Optional[bool] = Field( - False, - description="A flag indicating whether the swarm should stream its output.", - ) +async def main(): + async with SwarmsClient(api_key="your-api-key") as client: + response = await client.swarm.alist_types() + + print(f"Available swarm types:") + for swarm_type in response.swarm_types: + print(f"- {swarm_type}") + +asyncio.run(main()) +``` + +#### Returns + +Same as the `list_types` method. + + +### acreate + +Creates a swarm completion asynchronously. + +```python +import asyncio +from swarms_client import SwarmsClient +async def main(): + async with SwarmsClient(api_key="your-api-key") as client: + response = await client.swarm.acreate( + name="Research Swarm", + swarm_type="SequentialWorkflow", + task="Research quantum computing advances in 2024", + agents=[ + { + "agent_name": "Researcher", + "description": "Conducts in-depth research", + "model_name": "gpt-4o" + }, + { + "agent_name": "Critic", + "description": "Evaluates arguments for flaws", + "model_name": "gpt-4o-mini" + } + ] + ) + + print(f"Job ID: {response.job_id}") + print(f"Status: {response.status}") + print(f"Output: {response.output}") -class SwarmCompletionResponse(BaseModel): - """ - Response from a swarm completion. - """ +asyncio.run(main()) +``` - status: str = Field(..., description="The status of the swarm completion.") - swarm_name: str = Field(..., description="The name of the swarm.") - description: str = Field(..., description="Description of the swarm.") - swarm_type: str = Field(..., description="The type of the swarm.") - task: str = Field( - ..., description="The task that the swarm is designed to accomplish." - ) - output: List[Dict[str, Any]] = Field( - ..., description="The output generated by the swarm." - ) - number_of_agents: int = Field( - ..., description="The number of agents involved in the swarm." - ) - # "input_config": Optional[Dict[str, Any]] = Field(None, description="The input configuration for the swarm.") +#### Parameters +Same as the `create` method. -BASE_URL = "https://swarms-api-285321057562.us-east1.run.app" +#### Returns +Same as the `create` method. -# Create an MCP server -mcp = FastMCP("swarms-api") + +### acreate_batch +Creates multiple swarm completions in batch asynchronously. -# Add an addition tool -@mcp.tool(name="swarm_completion", description="Run a swarm completion.") -def swarm_completion(swarm: SwarmSpec) -> Dict[str, Any]: - api_key = os.getenv("SWARMS_API_KEY") - headers = {"x-api-key": api_key, "Content-Type": "application/json"} +```python +import asyncio +from swarms_client import SwarmsClient - payload = swarm.model_dump() +async def main(): + async with SwarmsClient(api_key="your-api-key") as client: + responses = await client.swarm.acreate_batch([ + { + "name": "Research Swarm", + "swarm_type": "auto", + "task": "Research quantum computing", + "agents": [ + {"agent_name": "Researcher", "model_name": "gpt-4o"} + ] + }, + { + "name": "Writing Swarm", + "swarm_type": "SequentialWorkflow", + "task": "Write a blog post about AI safety", + "agents": [ + {"agent_name": "Writer", "model_name": "gpt-4o"} + ] + } + ]) + + for i, response in enumerate(responses): + print(f"Swarm {i+1} Job ID: {response.job_id}") + print(f"Status: {response.status}") + print(f"Output: {response.output}") + print("---") - response = requests.post(f"{BASE_URL}/v1/swarm/completions", json=payload, headers=headers) - - return response.json() +asyncio.run(main()) +``` -@mcp.tool(name="swarms_available", description="Get the list of available swarms.") -async def swarms_available() -> Any: - """ - Get the list of available swarms. - """ - headers = {"Content-Type": "application/json"} +#### Parameters - async with httpx.AsyncClient() as client: - response = await client.get(f"{BASE_URL}/v1/models/available", headers=headers) - response.raise_for_status() # Raise an error for bad responses - return response.json() +Same as the `create_batch` method. +#### Returns -if __name__ == "__main__": - mcp.run(transport="sse") +Same as the `create_batch` method. + +## Models Resource + +The Models resource provides methods for retrieving information about available models. + + +### list + +Lists available models. + +```python +response = client.models.list() + +print(f"Available models:") +for model in response.models: + print(f"- {model}") ``` -## Client side +#### Returns -- Call the tool with it's name and the payload config +`ModelsResponse` object with the following properties: + +- `success`: Whether the request was successful +- `models`: List of available model names + + +### alist + +Lists available models asynchronously. ```python import asyncio -from fastmcp import Client +from swarms_client import SwarmsClient -swarm_config = { - "name": "Simple Financial Analysis", - "description": "A swarm to analyze financial data", - "agents": [ - { - "agent_name": "Data Analyzer", - "description": "Looks at financial data", - "system_prompt": "Analyze the data.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 1000, - "temperature": 0.5, - "auto_generate_prompt": False, - }, - { - "agent_name": "Risk Analyst", - "description": "Checks risk levels", - "system_prompt": "Evaluate the risks.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 1000, - "temperature": 0.5, - "auto_generate_prompt": False, - }, - { - "agent_name": "Strategy Checker", - "description": "Validates strategies", - "system_prompt": "Review the strategy.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 1000, - "temperature": 0.5, - "auto_generate_prompt": False, - }, - ], - "max_loops": 1, - "swarm_type": "SequentialWorkflow", - "task": "Analyze the financial data and provide insights.", - "return_history": False, # Added required field - "stream": False, # Added required field - "rules": None, # Added optional field - "img": None, # Added optional field -} +async def main(): + async with SwarmsClient(api_key="your-api-key") as client: + response = await client.models.alist() + + print(f"Available models:") + for model in response.models: + print(f"- {model}") +asyncio.run(main()) +``` -async def swarm_completion(): - """Connect to a server over SSE and fetch available swarms.""" +#### Returns - async with Client( - transport="http://localhost:8000/sse" - ) as client: - # Basic connectivity testing - # print("Ping check:", await client.ping()) - # print("Available tools:", await client.list_tools()) - # print("Swarms available:", await client.call_tool("swarms_available", None)) - result = await client.call_tool("swarm_completion", {"swarm": swarm_config}) - print("Swarm completion:", result) +Same as the `list` method. +## Logs Resource -# Execute the function -if __name__ == "__main__": - asyncio.run(swarm_completion()) -``` +The Logs resource provides methods for retrieving API request logs. --------------------------------------------------- + +### list -# File: swarms_cloud/mcs_api.md +Lists API request logs. -# Medical Coder Swarm API Documentation +```python +response = client.logs.list() -Base URL: `https://mcs-285321057562.us-central1.run.app` +print(f"Found {response.count} logs:") +for log in response.logs: + print(f"- ID: {log.id}, Created at: {log.created_at}") + print(f" Data: {log.data}") +``` -## Table of Contents -- [Authentication](#authentication) -- [Rate Limits](#rate-limits) -- [Endpoints](#endpoints) - - [Health Check](#health-check) - - [Run Medical Coder](#run-medical-coder) - - [Run Batch Medical Coder](#run-batch-medical-coder) - - [Get Patient Data](#get-patient-data) - - [Get All Patients](#get-all-patients) -- [Code Examples](#code-examples) -- [Error Handling](#error-handling) +#### Returns -## Authentication +`LogsResponse` object with the following properties: -Authentication details will be provided by the MCS team. Contact support for API credentials. +- `status`: Status of the request +- `count`: Number of logs +- `logs`: List of log entries +- `timestamp`: Timestamp of the request -## Rate Limits +Each log entry is a `LogEntry` object with the following properties: -| Endpoint | GET Rate Limit Status | -|----------|----------------------| -| `GET /rate-limits` | Returns current rate limit status for your IP address | +- `id`: Unique identifier for the log entry +- `api_key`: API key used for the request +- `data`: Request data +- `created_at`: Timestamp when the log entry was created -## Endpoints + +### alist -### Health Check +Lists API request logs asynchronously. -Check if the API is operational. +```python +import asyncio +from swarms_client import SwarmsClient -| Method | Endpoint | Description | -|--------|----------|-------------| -| `GET` | `/health` | Returns 200 OK if service is running | +async def main(): + async with SwarmsClient() as client: + response = await client.logs.alist() + + print(f"Found {response.count} logs:") + for log in response.logs: + print(f"- ID: {log.id}, Created at: {log.created_at}") + print(f" Data: {log.data}") -### Run Medical Coder +asyncio.run(main()) +``` -Process a single patient case through the Medical Coder Swarm. +#### Returns -| Method | Endpoint | Description | -|--------|----------|-------------| -| `POST` | `/v1/medical-coder/run` | Process a single patient case | +Same as the `list` method. -**Request Body Parameters:** +## Error Handling -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| patient_id | string | Yes | Unique identifier for the patient | -| case_description | string | Yes | Medical case details to be processed | +The Swarms API client provides detailed error handling with specific exception types for different error scenarios. All exceptions inherit from the base `SwarmsError` class. -**Response Schema:** +```python +from swarms_client import SwarmsClient, SwarmsError, AuthenticationError, RateLimitError, APIError -| Field | Type | Description | -|-------|------|-------------| -| patient_id | string | Patient identifier | -| case_data | string | Processed case data | +try: + client = SwarmsClient(api_key="invalid-api-key") + response = client.agent.create( + agent_config={"agent_name": "Researcher", "model_name": "gpt-4o"}, + task="Research quantum computing" + ) +except AuthenticationError as e: + print(f"Authentication error: {e}") +except RateLimitError as e: + print(f"Rate limit exceeded: {e}") +except APIError as e: + print(f"API error: {e}") +except SwarmsError as e: + print(f"Swarms error: {e}") +``` -### Run Batch Medical Coder +### Exception Types -Process multiple patient cases in a single request. +| Exception | Description | +|-----------|-------------| +| `SwarmsError` | Base exception for all Swarms API errors | +| `AuthenticationError` | Raised when there's an issue with authentication | +| `RateLimitError` | Raised when the rate limit is exceeded | +| `APIError` | Raised when the API returns an error | +| `InvalidRequestError` | Raised when the request is invalid | +| `InsufficientCreditsError` | Raised when the user doesn't have enough credits | +| `TimeoutError` | Raised when a request times out | +| `NetworkError` | Raised when there's a network issue | -| Method | Endpoint | Description | -|--------|----------|-------------| -| `POST` | `/v1/medical-coder/run-batch` | Process multiple patient cases | +## Advanced Features -**Request Body Parameters:** +### Connection Pooling -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| cases | array | Yes | Array of PatientCase objects | +The Swarms API client uses connection pooling to efficiently manage HTTP connections, which can significantly improve performance when making multiple requests. -### Get Patient Data +```python +client = SwarmsClient( + api_key="your-api-key", + pool_connections=100, # Number of connection pools to cache + pool_maxsize=100, # Maximum number of connections to save in the pool + keep_alive_timeout=5 # Keep-alive timeout for connections in seconds +) +``` -Retrieve data for a specific patient. +### Circuit Breaker Pattern -| Method | Endpoint | Description | -|--------|----------|-------------| -| `GET` | `/v1/medical-coder/patient/{patient_id}` | Get patient data by ID | +The client implements the circuit breaker pattern to prevent cascading failures when the API is experiencing issues. -**Path Parameters:** +```python +client = SwarmsClient( + api_key="your-api-key", + circuit_breaker_threshold=5, # Number of failures before the circuit opens + circuit_breaker_timeout=60 # Time in seconds before attempting to close the circuit +) +``` -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| patient_id | string | Yes | Patient identifier | +### Caching -### Get All Patients +The client includes in-memory caching for frequently accessed resources to reduce API calls and improve performance. -Retrieve data for all patients. +```python +client = SwarmsClient( + api_key="your-api-key", + enable_cache=True # Enable in-memory caching +) -| Method | Endpoint | Description | -|--------|----------|-------------| -| `GET` | `/v1/medical-coder/patients` | Get all patient data | +# Clear the cache manually if needed +client.clear_cache() +``` -## Code Examples +## Complete Example -### Python +Here's a complete example that demonstrates how to use the Swarms API client to create a research swarm and process its output: ```python -import requests -import json +import os +from swarms_client import SwarmsClient +from dotenv import load_dotenv -class MCSClient: - def __init__(self, base_url="https://mcs.swarms.ai", api_key=None): - self.base_url = base_url - self.headers = { - "Content-Type": "application/json", - "Authorization": f"Bearer {api_key}" if api_key else None - } +# Load API key from environment +load_dotenv() +api_key = os.getenv("SWARMS_API_KEY") - def run_medical_coder(self, patient_id, case_description): - endpoint = f"{self.base_url}/v1/medical-coder/run" - payload = { - "patient_id": patient_id, - "case_description": case_description - } - response = requests.post(endpoint, json=payload, headers=self.headers) - return response.json() +# Initialize client +client = SwarmsClient(api_key=api_key) - def run_batch(self, cases): - endpoint = f"{self.base_url}/v1/medical-coder/run-batch" - payload = {"cases": cases} - response = requests.post(endpoint, json=payload, headers=self.headers) - return response.json() +# Create a research swarm +try: + # Define the agents + researcher = { + "agent_name": "Researcher", + "description": "Conducts thorough research on specified topics", + "model_name": "gpt-4o", + "temperature": 0.5, + "system_prompt": "You are a diligent researcher focused on finding accurate and comprehensive information." + } + + analyst = { + "agent_name": "Analyst", + "description": "Analyzes research findings and identifies key insights", + "model_name": "gpt-4o", + "temperature": 0.3, + "system_prompt": "You are an insightful analyst who can identify patterns and extract meaningful insights from research data." + } + + summarizer = { + "agent_name": "Summarizer", + "description": "Creates concise summaries of complex information", + "model_name": "gpt-4o-mini", + "temperature": 0.4, + "system_prompt": "You specialize in distilling complex information into clear, concise summaries." + } + + # Create the swarm + response = client.swarm.create( + name="Quantum Computing Research Swarm", + description="A swarm for researching and analyzing quantum computing advancements", + swarm_type="SequentialWorkflow", + task="Research the latest advancements in quantum computing in 2024, analyze their potential impact on cryptography and data security, and provide a concise summary of the findings.", + agents=[researcher, analyst, summarizer], + max_loops=2, + return_history=True + ) + + # Process the response + print(f"Job ID: {response.job_id}") + print(f"Status: {response.status}") + print(f"Number of agents: {response.number_of_agents}") + print(f"Swarm type: {response.swarm_type}") + + # Print the output + if "final_output" in response.output: + print("\nFinal Output:") + print(response.output["final_output"]) + else: + print("\nOutput:") + print(response.output) + + # Access agent-specific outputs if available + if "agent_outputs" in response.output: + print("\nAgent Outputs:") + for agent, output in response.output["agent_outputs"].items(): + print(f"\n{agent}:") + print(output) -# Usage example -client = MCSClient(api_key="your_api_key") -result = client.run_medical_coder("P123", "Patient presents with...") +except Exception as e: + print(f"Error: {e}") ``` -### Next.js (TypeScript) +This example creates a sequential workflow swarm with three agents to research quantum computing, analyze the findings, and create a summary of the results. -```typescript -// types.ts -interface PatientCase { - patient_id: string; - case_description: string; -} -interface QueryResponse { - patient_id: string; - case_data: string; -} +-------------------------------------------------- -// api.ts -export class MCSApi { - private baseUrl: string; - private apiKey: string; +# File: swarms_cloud\quickstart.md - constructor(apiKey: string, baseUrl = 'https://mcs.swarms.ai') { - this.baseUrl = baseUrl; - this.apiKey = apiKey; - } - private async fetchWithAuth(endpoint: string, options: RequestInit = {}) { - const response = await fetch(`${this.baseUrl}${endpoint}`, { - ...options, - headers: { - 'Content-Type': 'application/json', - 'Authorization': `Bearer ${this.apiKey}`, - ...options.headers, - }, - }); - return response.json(); - } +# Swarms Quickstart Guide - async runMedicalCoder(patientCase: PatientCase): Promise { - return this.fetchWithAuth('/v1/medical-coder/run', { - method: 'POST', - body: JSON.stringify(patientCase), - }); - } +This guide will help you get started with both single agent and multi-agent functionalities in Swarms API. - async getPatientData(patientId: string): Promise { - return this.fetchWithAuth(`/v1/medical-coder/patient/${patientId}`); - } -} +## Prerequisites -// Usage in component -const mcsApi = new MCSApi(process.env.MCS_API_KEY); +!!! info "Requirements" -export async function ProcessPatientCase({ patientId, caseDescription }) { - const result = await mcsApi.runMedicalCoder({ - patient_id: patientId, - case_description: caseDescription, - }); - return result; -} -``` + - Python 3.7+ + - API key from [Swarms Platform](https://swarms.world/platform/api-keys) + - `requests` library for Python + - `axios` for TypeScript/JavaScript + - `curl` for shell commands -### Go +## Installation -```go -package mcs +=== "pip" -import ( - "bytes" - "encoding/json" - "fmt" - "net/http" -) + ```bash + pip install requests python-dotenv + ``` -type MCSClient struct { - BaseURL string - APIKey string - Client *http.Client -} +=== "npm" -type PatientCase struct { - PatientID string `json:"patient_id"` - CaseDescription string `json:"case_description"` -} + ```bash + npm install axios dotenv + ``` -type QueryResponse struct { - PatientID string `json:"patient_id"` - CaseData string `json:"case_data"` -} +## Authentication -func NewMCSClient(apiKey string) *MCSClient { - return &MCSClient{ - BaseURL: "https://mcs.swarms.ai", - APIKey: apiKey, - Client: &http.Client{}, - } -} +!!! warning "API Key Security" -func (c *MCSClient) RunMedicalCoder(patientCase PatientCase) (*QueryResponse, error) { - payload, err := json.Marshal(patientCase) - if err != nil { - return nil, err - } + Never hardcode your API key in your code. Always use environment variables or secure configuration management. - req, err := http.NewRequest("POST", - fmt.Sprintf("%s/v1/medical-coder/run", c.BaseURL), - bytes.NewBuffer(payload)) - if err != nil { - return nil, err - } +The API is accessible through two base URLs: - req.Header.Set("Content-Type", "application/json") - req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", c.APIKey)) +- Production: `https://api.swarms.world` +- Alternative: `https://swarms-api-285321057562.us-east1.run.app` - resp, err := c.Client.Do(req) - if err != nil { - return nil, err - } - defer resp.Body.Close() +## Single Agent Usage - var result QueryResponse - if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { - return nil, err - } +### Health Check - return &result, nil -} +=== "Python" -// Usage example -func main() { - client := NewMCSClient("your_api_key") - - result, err := client.RunMedicalCoder(PatientCase{ - PatientID: "P123", - CaseDescription: "Patient presents with...", - }) - if err != nil { - panic(err) + ```python linenums="1" title="health_check.py" + import os + import requests + from dotenv import load_dotenv + + load_dotenv() + API_KEY = os.getenv("SWARMS_API_KEY") + BASE_URL = "https://api.swarms.world" + + headers = { + "x-api-key": API_KEY, + "Content-Type": "application/json" } - - fmt.Printf("Result: %+v\n", result) -} -``` + response = requests.get(f"{BASE_URL}/health", headers=headers) + print(response.json()) + ``` -## C Sharp +=== "cURL" + ```bash title="health_check.sh" + curl -X GET "https://api.swarms.world/health" \ + -H "x-api-key: $SWARMS_API_KEY" \ + -H "Content-Type: application/json" + ``` -```txt -using System; -using System.Net.Http; -using System.Text; -using System.Text.Json; -using System.Threading.Tasks; +=== "TypeScript" -namespace MedicalCoderSwarm -{ - public class PatientCase - { - public string PatientId { get; set; } - public string CaseDescription { get; set; } - } + ```typescript linenums="1" title="health_check.ts" + import axios from 'axios'; + import * as dotenv from 'dotenv'; - public class QueryResponse - { - public string PatientId { get; set; } - public string CaseData { get; set; } - } + dotenv.config(); + const API_KEY = process.env.SWARMS_API_KEY; + const BASE_URL = 'https://api.swarms.world'; - public class MCSClient : IDisposable - { - private readonly HttpClient _httpClient; - private readonly string _baseUrl; - - public MCSClient(string apiKey, string baseUrl = "https://mcs-285321057562.us-central1.run.app") - { - _baseUrl = baseUrl; - _httpClient = new HttpClient(); - _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}"); - _httpClient.DefaultRequestHeaders.Add("Content-Type", "application/json"); - } + async function checkHealth() { + try { + const response = await axios.get(`${BASE_URL}/health`, { + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + } + }); + console.log(response.data); + } catch (error) { + console.error('Error:', error); + } + } - public async Task RunMedicalCoderAsync(string patientId, string caseDescription) - { - var payload = new PatientCase - { - PatientId = patientId, - CaseDescription = caseDescription - }; + checkHealth(); + ``` - var content = new StringContent( - JsonSerializer.Serialize(payload), - Encoding.UTF8, - "application/json" - ); +### Basic Agent - var response = await _httpClient.PostAsync( - $"{_baseUrl}/v1/medical-coder/run", - content - ); +=== "Python" - response.EnsureSuccessStatusCode(); - - var responseContent = await response.Content.ReadAsStringAsync(); - return JsonSerializer.Deserialize(responseContent); - } + ```python linenums="1" title="single_agent.py" + import os + import requests + from dotenv import load_dotenv - public async Task GetPatientDataAsync(string patientId) - { - var response = await _httpClient.GetAsync( - $"{_baseUrl}/v1/medical-coder/patient/{patientId}" - ); + load_dotenv() - response.EnsureSuccessStatusCode(); - - var responseContent = await response.Content.ReadAsStringAsync(); - return JsonSerializer.Deserialize(responseContent); - } + API_KEY = os.getenv("SWARMS_API_KEY") # (1) + BASE_URL = "https://api.swarms.world" - public async Task HealthCheckAsync() - { - var response = await _httpClient.GetAsync($"{_baseUrl}/health"); - return response.IsSuccessStatusCode; - } + headers = { + "x-api-key": API_KEY, + "Content-Type": "application/json" + } - public void Dispose() - { - _httpClient?.Dispose(); + def run_single_agent(): + """Run a single agent with the AgentCompletion format""" + payload = { + "agent_config": { + "agent_name": "Research Analyst", # (2) + "description": "An expert in analyzing and synthesizing research data", + "system_prompt": ( # (3) + "You are a Research Analyst with expertise in data analysis and synthesis. " + "Your role is to analyze provided information, identify key insights, " + "and present findings in a clear, structured format." + ), + "model_name": "claude-3-5-sonnet-20240620", # (4) + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 1, + "auto_generate_prompt": False, + "tools_list_dictionary": None, + }, + "task": "What are the key trends in renewable energy adoption?", # (5) } - } - // Example usage - public class Program - { - public static async Task Main() - { - try - { - using var client = new MCSClient("your_api_key"); + response = requests.post( + f"{BASE_URL}/v1/agent/completions", + headers=headers, + json=payload + ) + return response.json() - // Check API health - var isHealthy = await client.HealthCheckAsync(); - Console.WriteLine($"API Health: {(isHealthy ? "Healthy" : "Unhealthy")}"); + # Run the agent + result = run_single_agent() + print(result) + ``` - // Process a single case - var result = await client.RunMedicalCoderAsync( - "P123", - "Patient presents with acute respiratory symptoms..." - ); - Console.WriteLine($"Processed case for patient {result.PatientId}"); - Console.WriteLine($"Case data: {result.CaseData}"); + 1. Load API key from environment variables + 2. Give your agent a descriptive name + 3. Define the agent's capabilities and role + 4. Choose from available models + 5. Specify the task for the agent + +=== "cURL" + + ```bash title="single_agent.sh" + curl -X POST "https://api.swarms.world/v1/agent/completions" \ + -H "x-api-key: $SWARMS_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "agent_config": { + "agent_name": "Research Analyst", + "description": "An expert in analyzing and synthesizing research data", + "system_prompt": "You are a Research Analyst with expertise in data analysis and synthesis. Your role is to analyze provided information, identify key insights, and present findings in a clear, structured format.", + "model_name": "claude-3-5-sonnet-20240620", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 1, + "auto_generate_prompt": false, + "tools_list_dictionary": null + }, + "task": "What are the key trends in renewable energy adoption?" + }' + ``` - // Get patient data - var patientData = await client.GetPatientDataAsync("P123"); - Console.WriteLine($"Retrieved data for patient {patientData.PatientId}"); - } - catch (HttpRequestException ex) - { - Console.WriteLine($"API request failed: {ex.Message}"); - } - catch (Exception ex) - { - Console.WriteLine($"An error occurred: {ex.Message}"); - } - } - } -} +=== "TypeScript" -``` + ```typescript linenums="1" title="single_agent.ts" + import axios from 'axios'; + import * as dotenv from 'dotenv'; -## Error Handling + dotenv.config(); -The API uses standard HTTP status codes and returns detailed error messages in JSON format. + const API_KEY = process.env.SWARMS_API_KEY; + const BASE_URL = 'https://api.swarms.world'; -**Common Status Codes:** + interface AgentConfig { + agent_name: string; + description: string; + system_prompt: string; + model_name: string; + role: string; + max_loops: number; + max_tokens: number; + temperature: number; + auto_generate_prompt: boolean; + tools_list_dictionary: null | object[]; + } -| Status Code | Description | -|-------------|-------------| -| 200 | Success | -| 400 | Bad Request - Invalid input | -| 401 | Unauthorized - Invalid or missing API key | -| 422 | Validation Error - Request validation failed | -| 429 | Too Many Requests - Rate limit exceeded | -| 500 | Internal Server Error | + interface AgentPayload { + agent_config: AgentConfig; + task: string; + } -**Error Response Format:** + async function runSingleAgent() { + const payload: AgentPayload = { + agent_config: { + agent_name: "Research Analyst", + description: "An expert in analyzing and synthesizing research data", + system_prompt: "You are a Research Analyst with expertise in data analysis and synthesis.", + model_name: "claude-3-5-sonnet-20240620", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 1, + auto_generate_prompt: false, + tools_list_dictionary: null + }, + task: "What are the key trends in renewable energy adoption?" + }; -```json -{ - "detail": [ - { - "loc": ["body", "patient_id"], - "msg": "field required", - "type": "value_error.missing" + try { + const response = await axios.post( + `${BASE_URL}/v1/agent/completions`, + payload, + { + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + } + } + ); + return response.data; + } catch (error) { + console.error('Error:', error); + throw error; + } } - ] -} -``` + // Run the agent + runSingleAgent() + .then(result => console.log(result)) + .catch(error => console.error(error)); + ``` -# MCS Python Client Documentation +### Agent with History -## Installation +=== "Python" -```bash -pip install mcs -``` + ```python linenums="1" title="agent_with_history.py" + def run_agent_with_history(): + payload = { + "agent_config": { + "agent_name": "Conversation Agent", + "description": "An agent that maintains conversation context", + "system_prompt": "You are a helpful assistant that maintains context.", + "model_name": "claude-3-5-sonnet-20240620", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.7, + "auto_generate_prompt": False, + }, + "task": "What's the weather like?", + "history": [ # (1) + { + "role": "user", + "content": "I'm planning a trip to New York." + }, + { + "role": "assistant", + "content": "That's great! When are you planning to visit?" + }, + { + "role": "user", + "content": "Next week." + } + ] + } -## Quick Start + response = requests.post( + f"{BASE_URL}/v1/agent/completions", + headers=headers, + json=payload + ) + return response.json() + ``` -```python -from mcs import MCSClient, PatientCase + 1. Include conversation history for context -# Using context manager (recommended) -with MCSClient() as client: - # Process a single case - response = client.run_medical_coder( - patient_id="P123", - case_description="Patient presents with acute respiratory symptoms..." - ) - print(f"Processed case: {response.case_data}") +=== "cURL" - # Process multiple cases - cases = [ - PatientCase("P124", "Case 1 description..."), - PatientCase("P125", "Case 2 description...") - ] - batch_response = client.run_batch(cases) -``` + ```bash title="agent_with_history.sh" + curl -X POST "https://api.swarms.world/v1/agent/completions" \ + -H "x-api-key: $SWARMS_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "agent_config": { + "agent_name": "Conversation Agent", + "description": "An agent that maintains conversation context", + "system_prompt": "You are a helpful assistant that maintains context.", + "model_name": "claude-3-5-sonnet-20240620", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.7, + "auto_generate_prompt": false + }, + "task": "What'\''s the weather like?", + "history": [ + { + "role": "user", + "content": "I'\''m planning a trip to New York." + }, + { + "role": "assistant", + "content": "That'\''s great! When are you planning to visit?" + }, + { + "role": "user", + "content": "Next week." + } + ] + }' + ``` -## Client Configuration +=== "TypeScript" -### Constructor Arguments + ```typescript linenums="1" title="agent_with_history.ts" + interface Message { + role: 'user' | 'assistant'; + content: string; + } -| Parameter | Type | Required | Default | Description | -|-----------|------|----------|---------|-------------| -| api_key | str | Yes | - | Authentication API key | -| base_url | str | No | "https://mcs.swarms.ai" | API base URL | -| timeout | int | No | 30 | Request timeout in seconds | -| max_retries | int | No | 3 | Maximum retry attempts | -| logger_name | str | No | "mcs" | Name for the logger instance | + interface AgentWithHistoryPayload extends AgentPayload { + history: Message[]; + } -### Example Configuration + async function runAgentWithHistory() { + const payload: AgentWithHistoryPayload = { + agent_config: { + agent_name: "Conversation Agent", + description: "An agent that maintains conversation context", + system_prompt: "You are a helpful assistant that maintains context.", + model_name: "claude-3-5-sonnet-20240620", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.7, + auto_generate_prompt: false, + tools_list_dictionary: null + }, + task: "What's the weather like?", + history: [ + { + role: "user", + content: "I'm planning a trip to New York." + }, + { + role: "assistant", + content: "That's great! When are you planning to visit?" + }, + { + role: "user", + content: "Next week." + } + ] + }; -```python -client = MCSClient( - base_url="https://custom-url.example.com", - timeout=45, - max_retries=5, - logger_name="custom_logger" -) -``` + try { + const response = await axios.post( + `${BASE_URL}/v1/agent/completions`, + payload, + { + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + } + } + ); + return response.data; + } catch (error) { + console.error('Error:', error); + throw error; + } + } + ``` -## Data Models +## Multi-Agent Swarms -### PatientCase +!!! tip "Swarm Types" -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| patient_id | str | Yes | Unique identifier for the patient | -| case_description | str | Yes | Medical case details | + Swarms API supports two types of agent workflows: + + 1. `SequentialWorkflow`: Agents work in sequence, each building on previous output + 2. `ConcurrentWorkflow`: Agents work in parallel on the same task -### QueryResponse +### Sequential Workflow -| Field | Type | Description | -|-------|------|-------------| -| patient_id | str | Patient identifier | -| case_data | str | Processed case data | +=== "Python" -## Methods + ```python linenums="1" title="sequential_swarm.py" + def run_sequential_swarm(): + payload = { + "name": "Financial Analysis Swarm", + "description": "Market analysis swarm", + "agents": [ + { + "agent_name": "Market Analyst", # (1) + "description": "Analyzes market trends", + "system_prompt": "You are a financial analyst expert.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": False + }, + { + "agent_name": "Economic Forecaster", # (2) + "description": "Predicts economic trends", + "system_prompt": "You are an expert in economic forecasting.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": False + } + ], + "max_loops": 1, + "swarm_type": "SequentialWorkflow", # (3) + "task": "Analyze the current market conditions and provide economic forecasts." + } -### run_medical_coder + response = requests.post( + f"{BASE_URL}/v1/swarm/completions", + headers=headers, + json=payload + ) + return response.json() + ``` -Process a single patient case. + 1. First agent analyzes market trends + 2. Second agent builds on first agent's analysis + 3. Sequential workflow ensures ordered execution -```python -def run_medical_coder( - self, - patient_id: str, - case_description: str -) -> QueryResponse: -``` +=== "cURL" -**Arguments:** + ```bash title="sequential_swarm.sh" + curl -X POST "https://api.swarms.world/v1/swarm/completions" \ + -H "x-api-key: $SWARMS_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Financial Analysis Swarm", + "description": "Market analysis swarm", + "agents": [ + { + "agent_name": "Market Analyst", + "description": "Analyzes market trends", + "system_prompt": "You are a financial analyst expert.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": false + }, + { + "agent_name": "Economic Forecaster", + "description": "Predicts economic trends", + "system_prompt": "You are an expert in economic forecasting.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": false + } + ], + "max_loops": 1, + "swarm_type": "SequentialWorkflow", + "task": "Analyze the current market conditions and provide economic forecasts." + }' + ``` -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| patient_id | str | Yes | Patient identifier | -| case_description | str | Yes | Case details | +=== "TypeScript" + + ```typescript linenums="1" title="sequential_swarm.ts" + interface SwarmAgent { + agent_name: string; + description: string; + system_prompt: string; + model_name: string; + role: string; + max_loops: number; + max_tokens: number; + temperature: number; + auto_generate_prompt: boolean; + } -**Example:** -```python -response = client.run_medical_coder( - patient_id="P123", - case_description="Patient presents with..." -) -print(response.case_data) -``` + interface SwarmPayload { + name: string; + description: string; + agents: SwarmAgent[]; + max_loops: number; + swarm_type: 'SequentialWorkflow' | 'ConcurrentWorkflow'; + task: string; + } -### run_batch + async function runSequentialSwarm() { + const payload: SwarmPayload = { + name: "Financial Analysis Swarm", + description: "Market analysis swarm", + agents: [ + { + agent_name: "Market Analyst", + description: "Analyzes market trends", + system_prompt: "You are a financial analyst expert.", + model_name: "gpt-4o", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.5, + auto_generate_prompt: false + }, + { + agent_name: "Economic Forecaster", + description: "Predicts economic trends", + system_prompt: "You are an expert in economic forecasting.", + model_name: "gpt-4o", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.5, + auto_generate_prompt: false + } + ], + max_loops: 1, + swarm_type: "SequentialWorkflow", + task: "Analyze the current market conditions and provide economic forecasts." + }; + + try { + const response = await axios.post( + `${BASE_URL}/v1/swarm/completions`, + payload, + { + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + } + } + ); + return response.data; + } catch (error) { + console.error('Error:', error); + throw error; + } + } + ``` -Process multiple patient cases in batch. +### Concurrent Workflow -```python -def run_batch( - self, - cases: List[PatientCase] -) -> List[QueryResponse]: -``` +=== "Python" -**Arguments:** + ```python linenums="1" title="concurrent_swarm.py" + def run_concurrent_swarm(): + payload = { + "name": "Medical Analysis Swarm", + "description": "Analyzes medical data concurrently", + "agents": [ + { + "agent_name": "Lab Data Analyzer", # (1) + "description": "Analyzes lab report data", + "system_prompt": "You are a medical data analyst specializing in lab results.", + "model_name": "claude-3-5-sonnet-20240620", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": False + }, + { + "agent_name": "Clinical Specialist", # (2) + "description": "Provides clinical interpretations", + "system_prompt": "You are an expert in clinical diagnosis.", + "model_name": "claude-3-5-sonnet-20240620", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": False + } + ], + "max_loops": 1, + "swarm_type": "ConcurrentWorkflow", # (3) + "task": "Analyze these lab results and provide clinical interpretations." + } -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| cases | List[PatientCase] | Yes | List of patient cases | + response = requests.post( + f"{BASE_URL}/v1/swarm/completions", + headers=headers, + json=payload + ) + return response.json() + ``` -**Example:** -```python -cases = [ - PatientCase("P124", "Case 1 description..."), - PatientCase("P125", "Case 2 description...") -] -responses = client.run_batch(cases) -for response in responses: - print(f"Patient {response.patient_id}: {response.case_data}") -``` + 1. First agent processes lab data + 2. Second agent works simultaneously + 3. Concurrent workflow for parallel processing -### get_patient_data +=== "cURL" -Retrieve data for a specific patient. + ```bash title="concurrent_swarm.sh" + curl -X POST "https://api.swarms.world/v1/swarm/completions" \ + -H "x-api-key: $SWARMS_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Medical Analysis Swarm", + "description": "Analyzes medical data concurrently", + "agents": [ + { + "agent_name": "Lab Data Analyzer", + "description": "Analyzes lab report data", + "system_prompt": "You are a medical data analyst specializing in lab results.", + "model_name": "claude-3-5-sonnet-20240620", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": false + }, + { + "agent_name": "Clinical Specialist", + "description": "Provides clinical interpretations", + "system_prompt": "You are an expert in clinical diagnosis.", + "model_name": "claude-3-5-sonnet-20240620", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": false + } + ], + "max_loops": 1, + "swarm_type": "ConcurrentWorkflow", + "task": "Analyze these lab results and provide clinical interpretations." + }' + ``` -```python -def get_patient_data( - self, - patient_id: str -) -> QueryResponse: -``` +=== "TypeScript" -**Example:** -```python -patient_data = client.get_patient_data("P123") -print(f"Patient data: {patient_data.case_data}") -``` + ```typescript linenums="1" title="concurrent_swarm.ts" + async function runConcurrentSwarm() { + const payload: SwarmPayload = { + name: "Medical Analysis Swarm", + description: "Analyzes medical data concurrently", + agents: [ + { + agent_name: "Lab Data Analyzer", + description: "Analyzes lab report data", + system_prompt: "You are a medical data analyst specializing in lab results.", + model_name: "claude-3-5-sonnet-20240620", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.5, + auto_generate_prompt: false + }, + { + agent_name: "Clinical Specialist", + description: "Provides clinical interpretations", + system_prompt: "You are an expert in clinical diagnosis.", + model_name: "claude-3-5-sonnet-20240620", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.5, + auto_generate_prompt: false + } + ], + max_loops: 1, + swarm_type: "ConcurrentWorkflow", + task: "Analyze these lab results and provide clinical interpretations." + }; + + try { + const response = await axios.post( + `${BASE_URL}/v1/swarm/completions`, + payload, + { + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + } + } + ); + return response.data; + } catch (error) { + console.error('Error:', error); + throw error; + } + } + ``` -### get_all_patients +### Batch Processing -Retrieve data for all patients. +!!! example "Batch Processing" -```python -def get_all_patients(self) -> List[QueryResponse]: -``` + Process multiple swarms in a single request for improved efficiency. -**Example:** -```python -all_patients = client.get_all_patients() -for patient in all_patients: - print(f"Patient {patient.patient_id}: {patient.case_data}") -``` +=== "Python" -### get_rate_limits + ```python linenums="1" title="batch_swarms.py" + def run_batch_swarms(): + payload = [ + { + "name": "Batch Swarm 1", + "description": "First swarm in batch", + "agents": [ + { + "agent_name": "Research Agent", + "description": "Conducts research", + "system_prompt": "You are a research assistant.", + "model_name": "gpt-4", + "role": "worker", + "max_loops": 1 + }, + { + "agent_name": "Analysis Agent", + "description": "Analyzes data", + "system_prompt": "You are a data analyst.", + "model_name": "gpt-4", + "role": "worker", + "max_loops": 1 + } + ], + "max_loops": 1, + "swarm_type": "SequentialWorkflow", + "task": "Research AI advancements." + } + ] -Get current rate limit status. + response = requests.post( + f"{BASE_URL}/v1/swarm/batch/completions", + headers=headers, + json=payload + ) + return response.json() + ``` -```python -def get_rate_limits(self) -> Dict[str, Any]: -``` +=== "cURL" -**Example:** -```python -rate_limits = client.get_rate_limits() -print(f"Rate limit status: {rate_limits}") -``` + ```bash title="batch_swarms.sh" + curl -X POST "https://api.swarms.world/v1/swarm/batch/completions" \ + -H "x-api-key: $SWARMS_API_KEY" \ + -H "Content-Type: application/json" \ + -d '[ + { + "name": "Batch Swarm 1", + "description": "First swarm in batch", + "agents": [ + { + "agent_name": "Research Agent", + "description": "Conducts research", + "system_prompt": "You are a research assistant.", + "model_name": "gpt-4", + "role": "worker", + "max_loops": 1 + }, + { + "agent_name": "Analysis Agent", + "description": "Analyzes data", + "system_prompt": "You are a data analyst.", + "model_name": "gpt-4", + "role": "worker", + "max_loops": 1 + } + ], + "max_loops": 1, + "swarm_type": "SequentialWorkflow", + "task": "Research AI advancements." + } + ]' + ``` -### health_check +=== "TypeScript" -Check if the API is operational. + ```typescript linenums="1" title="batch_swarms.ts" + async function runBatchSwarms() { + const payload: SwarmPayload[] = [ + { + name: "Batch Swarm 1", + description: "First swarm in batch", + agents: [ + { + agent_name: "Research Agent", + description: "Conducts research", + system_prompt: "You are a research assistant.", + model_name: "gpt-4", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.7, + auto_generate_prompt: false + }, + { + agent_name: "Analysis Agent", + description: "Analyzes data", + system_prompt: "You are a data analyst.", + model_name: "gpt-4", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.7, + auto_generate_prompt: false + } + ], + max_loops: 1, + swarm_type: "SequentialWorkflow", + task: "Research AI advancements." + } + ]; -```python -def health_check(self) -> bool: -``` + try { + const response = await axios.post( + `${BASE_URL}/v1/swarm/batch/completions`, + payload, + { + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + } + } + ); + return response.data; + } catch (error) { + console.error('Error:', error); + throw error; + } + } + ``` -**Example:** -```python -is_healthy = client.health_check() -print(f"API health: {'Healthy' if is_healthy else 'Unhealthy'}") -``` +## Advanced Features -## Error Handling +### Tools Integration -### Exception Hierarchy +!!! note "Tools" -| Exception | Description | -|-----------|-------------| -| MCSClientError | Base exception for all client errors | -| RateLimitError | Raised when API rate limit is exceeded | -| AuthenticationError | Raised when API authentication fails | -| ValidationError | Raised when request validation fails | + Enhance agent capabilities by providing them with specialized tools. -### Example Error Handling +=== "Python" -```python -from mcs import MCSClient, MCSClientError, RateLimitError + ```python linenums="1" title="tools_example.py" + def run_agent_with_tools(): + tools_dictionary = [ + { + "type": "function", + "function": { + "name": "search_topic", + "description": "Conduct an in-depth search on a topic", + "parameters": { + "type": "object", + "properties": { + "depth": { + "type": "integer", + "description": "Search depth (1-3)" + }, + "detailed_queries": { + "type": "array", + "description": "Specific search queries", + "items": { + "type": "string" + } + } + }, + "required": ["depth", "detailed_queries"] + } + } + } + ] -with MCSClient() as client: - try: - response = client.run_medical_coder("P123", "Case description...") - except RateLimitError: - print("Rate limit exceeded. Please wait before retrying.") - except MCSClientError as e: - print(f"An error occurred: {str(e)}") -``` + payload = { + "agent_config": { + "agent_name": "Research Assistant", + "description": "Expert in research with search capabilities", + "system_prompt": "You are a research assistant with search capabilities.", + "model_name": "gpt-4", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.7, + "auto_generate_prompt": False, + "tools_dictionary": tools_dictionary + }, + "task": "Research the latest developments in quantum computing." + } -## Advanced Usage + response = requests.post( + f"{BASE_URL}/v1/agent/completions", + headers=headers, + json=payload + ) + return response.json() + ``` -### Retry Configuration +=== "cURL" + + ```bash title="tools_example.sh" + curl -X POST "https://api.swarms.world/v1/agent/completions" \ + -H "x-api-key: $SWARMS_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "agent_config": { + "agent_name": "Research Assistant", + "description": "Expert in research with search capabilities", + "system_prompt": "You are a research assistant with search capabilities.", + "model_name": "gpt-4", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.7, + "auto_generate_prompt": false, + "tools_dictionary": [ + { + "type": "function", + "function": { + "name": "search_topic", + "description": "Conduct an in-depth search on a topic", + "parameters": { + "type": "object", + "properties": { + "depth": { + "type": "integer", + "description": "Search depth (1-3)" + }, + "detailed_queries": { + "type": "array", + "description": "Specific search queries", + "items": { + "type": "string" + } + } + }, + "required": ["depth", "detailed_queries"] + } + } + } + ] + }, + "task": "Research the latest developments in quantum computing." + }' + ``` -The client implements two levels of retry logic: +=== "TypeScript" + + ```typescript linenums="1" title="tools_example.ts" + interface ToolFunction { + name: string; + description: string; + parameters: { + type: string; + properties: { + [key: string]: { + type: string; + description: string; + items?: { + type: string; + }; + }; + }; + required: string[]; + }; + } -1. Connection-level retries (using `HTTPAdapter`): -```python -client = MCSClient( - , - max_retries=5 # Adjusts connection-level retries -) -``` + interface Tool { + type: string; + function: ToolFunction; + } -2. Application-level retries (using `tenacity`): -```python -from tenacity import retry, stop_after_attempt + interface AgentWithToolsConfig extends AgentConfig { + tools_dictionary: Tool[]; + } -@retry(stop=stop_after_attempt(5)) -def process_with_custom_retries(): - with MCSClient() as client: - return client.run_medical_coder("P123", "Case description...") -``` + interface AgentWithToolsPayload { + agent_config: AgentWithToolsConfig; + task: string; + } -### Batch Processing with Progress Tracking + async function runAgentWithTools() { + const toolsDictionary: Tool[] = [ + { + type: "function", + function: { + name: "search_topic", + description: "Conduct an in-depth search on a topic", + parameters: { + type: "object", + properties: { + depth: { + type: "integer", + description: "Search depth (1-3)" + }, + detailed_queries: { + type: "array", + description: "Specific search queries", + items: { + type: "string" + } + } + }, + required: ["depth", "detailed_queries"] + } + } + } + ]; + + const payload: AgentWithToolsPayload = { + agent_config: { + agent_name: "Research Assistant", + description: "Expert in research with search capabilities", + system_prompt: "You are a research assistant with search capabilities.", + model_name: "gpt-4", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.7, + auto_generate_prompt: false, + tools_dictionary: toolsDictionary + }, + task: "Research the latest developments in quantum computing." + }; -```python -from tqdm import tqdm + try { + const response = await axios.post( + `${BASE_URL}/v1/agent/completions`, + payload, + { + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + } + } + ); + return response.data; + } catch (error) { + console.error('Error:', error); + throw error; + } + } + ``` -with MCSClient() as client: - cases = [ - PatientCase(f"P{i}", f"Case description {i}") - for i in range(100) - ] - - # Process in smaller batches - batch_size = 10 - results = [] - - for i in tqdm(range(0, len(cases), batch_size)): - batch = cases[i:i + batch_size] - batch_results = client.run_batch(batch) - results.extend(batch_results) -``` +### Available Models -## Best Practices +!!! info "Supported Models" -1. **Always use context managers:** - ```python - with MCSClient() as client: - # Your code here - pass - ``` + Choose the right model for your use case: -2. **Handle rate limits appropriately:** - ```python - from time import sleep - - def process_with_rate_limit_handling(): - with MCSClient() as client: - try: - return client.run_medical_coder("P123", "Case...") - except RateLimitError: - sleep(60) # Wait before retry - return client.run_medical_coder("P123", "Case...") - ``` + === "OpenAI" + - `gpt-4` + - `gpt-4o` + - `gpt-4o-mini` -3. **Implement proper logging:** - ```python - from loguru import logger - - logger.add("mcs.log", rotation="500 MB") - - with MCSClient() as client: - try: - response = client.run_medical_coder("P123", "Case...") - except Exception as e: - logger.exception(f"Error processing case: {str(e)}") - ``` + === "Anthropic" + - `claude-3-5-sonnet-20240620` + - `claude-3-7-sonnet-latest` + + === "Groq" + - `groq/llama3-70b-8192` + - `groq/deepseek-r1-distill-llama-70b` + +## Best Practices -4. **Monitor API health:** - ```python - def ensure_healthy_api(): - with MCSClient() as client: - if not client.health_check(): - raise SystemExit("API is not healthy") - ``` +!!! danger "Security" + Never commit API keys or sensitive credentials to version control. --------------------------------------------------- +!!! warning "Rate Limits" + Implement proper rate limiting and error handling in production. -# File: swarms_cloud/migrate_openai.md +!!! tip "Testing" + Start with simple tasks and gradually increase complexity. -## Migrate from OpenAI to Swarms in 3 lines of code +=== "Python" -If you’ve been using GPT-3.5 or GPT-4, switching to Swarms is easy! + ```python linenums="1" title="best_practices.py" + # Error Handling + try: + response = requests.post(url, headers=headers, json=payload) + response.raise_for_status() + except requests.exceptions.RequestException as e: + print(f"Error: {e}") -Swarms VLMs are available to use through our OpenAI compatible API. Additionally, if you have been building or prototyping using OpenAI’s Python SDK you can keep your code as-is and use Swarms’s VLMs models. + # Rate Limiting + import time + from tenacity import retry, wait_exponential -In this example, we will show you how to change just three lines of code to make your Python application use Swarms’s Open Source models through OpenAI’s Python SDK. + @retry(wait=wait_exponential(multiplier=1, min=4, max=10)) + def make_api_call(): + response = requests.post(url, headers=headers, json=payload) + response.raise_for_status() + return response -​ -## Getting Started -Migrate OpenAI’s Python SDK example script to use Swarms’s LLM endpoints. + # Input Validation + def validate_payload(payload): + required_fields = ["agent_config", "task"] + if not all(field in payload for field in required_fields): + raise ValueError("Missing required fields") + ``` -These are the three modifications necessary to achieve our goal: +=== "TypeScript" -Redefine OPENAI_API_KEY your API key environment variable to use your Swarms key. + ```typescript linenums="1" title="best_practices.ts" + // Error Handling + try { + const response = await axios.post(url, payload, { headers }); + } catch (error) { + if (axios.isAxiosError(error)) { + console.error('API Error:', error.response?.data); + } + throw error; + } -Redefine OPENAI_BASE_URL to point to `https://api.swarms.world/v1/chat/completions` + // Rate Limiting + import { rateLimit } from 'axios-rate-limit'; -Change the model name to an Open Source model, for example: cogvlm-chat-17b -​ -## Requirements -We will be using Python and OpenAI’s Python SDK. -​ -## Instructions -Set up a Python virtual environment. Read Creating Virtual Environments here. + const http = rateLimit(axios.create(), { + maxRequests: 2, + perMilliseconds: 1000 + }); -```sh -python3 -m venv .venv -source .venv/bin/activate -``` + // Input Validation + function validatePayload(payload: unknown): asserts payload is AgentPayload { + if (!payload || typeof payload !== 'object') { + throw new Error('Invalid payload'); + } -Install the pip requirements in your local python virtual environment + const { agent_config, task } = payload as Partial; + + if (!agent_config || !task) { + throw new Error('Missing required fields'); + } + } + ``` -`python3 -m pip install openai` -​ -## Environment setup -To run this example, there are simple steps to take: +## Connect With Us -Get an Swarms API token by following these instructions. -Expose the token in a new SWARMS_API_TOKEN environment variable: +Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights! -`export SWARMS_API_TOKEN=` +| Platform | Description | Link | +|----------|-------------|------| +| 📚 Documentation | Official documentation and guides | [docs.swarms.world](https://docs.swarms.world) | +| 📝 Blog | Latest updates and technical articles | [Medium](https://medium.com/@kyeg) | +| 💬 Discord | Live chat and community support | [Join Discord](https://discord.gg/jM3Z6M9uMq) | +| 🐦 Twitter | Latest news and announcements | [@kyegomez](https://twitter.com/kyegomez) | +| 👥 LinkedIn | Professional network and updates | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | +| 📺 YouTube | Tutorials and demos | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | +| 🎫 Events | Join our community events | [Sign up here](https://lu.ma/5p2jnc2v) | +| 🚀 Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) | -Switch the OpenAI token and base URL environment variable +-------------------------------------------------- -`export OPENAI_API_KEY=$SWARMS_API_TOKEN` -`export OPENAI_BASE_URL="https://api.swarms.world/v1/chat/completions"` +# File: swarms_cloud\rate_limits.md -If you prefer, you can also directly paste your token into the client initialization. +# Swarms API Rate Limits -​ -## Example code -Once you’ve completed the steps above, the code below will call Swarms LLMs: +The Swarms API implements a comprehensive rate limiting system that tracks API requests across multiple time windows and enforces various limits to ensure fair usage and system stability. -```python -from dotenv import load_dotenv -from openai import OpenAI +## Rate Limits Summary -load_dotenv() -openai_api_key = "" +| Rate Limit Type | Free Tier | Premium Tier | Time Window | Description | +|----------------|-----------|--------------|-------------|-------------| +| **Requests per Minute** | 100 | 2,000 | 1 minute | Maximum API calls per minute | +| **Requests per Hour** | 50 | 10,000 | 1 hour | Maximum API calls per hour | +| **Requests per Day** | 1,200 | 100,000 | 24 hours | Maximum API calls per day | +| **Tokens per Agent** | 200,000 | 2,000,000 | Per request | Maximum tokens per agent | +| **Prompt Length** | 200,000 | 200,000 | Per request | Maximum input tokens per request | +| **Batch Size** | 10 | 10 | Per request | Maximum agents in batch requests | +| **IP-based Fallback** | 100 | 100 | 60 seconds | For requests without API keys | -openai_api_base = "https://api.swarms.world/v1" -model = "internlm-xcomposer2-4khd" +## Detailed Rate Limit Explanations -client = OpenAI(api_key=openai_api_key, base_url=openai_api_base) -# Note that this model expects the image to come before the main text -chat_response = client.chat.completions.create( - model=model, - messages=[ - { - "role": "user", - "content": [ - { - "type": "image_url", - "image_url": { - "url": "https://home-cdn.reolink.us/wp-content/uploads/2022/04/010345091648784709.4253.jpg", - }, - }, - { - "type": "text", - "text": "What is the most dangerous object in the image?", - }, - ], - } - ], - temperature=0.1, - max_tokens=5000, -) -print("Chat response:", chat_response) +### 1. **Request Rate Limits** -```  +These limits control how many API calls you can make within specific time windows. -Note that you need to supply one of Swarms’s supported LLMs as an argument, as in the example above. For a complete list of our supported LLMs, check out our REST API page. +#### **Per-Minute Limit** -​ -## Example output -The code above produces the following object: +| Tier | Requests per Minute | Reset Interval | Applies To | +|--------------|--------------------|------------------------|--------------------| +| Free | 100 | Every minute (sliding) | All API endpoints | +| Premium | 2,000 | Every minute (sliding) | All API endpoints | -```python -ChatCompletionMessage(content=" Hello! How can I assist you today? Do you have any questions or tasks you'd like help with? Please let me know and I'll do my best to assist you.", role='assistant' function_call=None, tool_calls=None) -``` +#### **Per-Hour Limit** +- **Free Tier**: 50 requests per hour +- **Premium Tier**: 10,000 requests per hour +- **Reset**: Every hour (sliding window) +- **Applies to**: All API endpoints +#### **Per-Day Limit** +- **Free Tier**: 1,200 requests per day (50 × 24) --------------------------------------------------- +- **Premium Tier**: 100,000 requests per day -# File: swarms_cloud/phala_deploy.md +- **Reset**: Every 24 hours (sliding window) -# 🔐 Swarms x Phala Deployment Guide +- **Applies to**: All API endpoints -This guide will walk you through deploying your project to Phala's Trusted Execution Environment (TEE). +### 2. **Token Limits** -## 📋 Prerequisites +These limits control the amount of text processing allowed per request. -- Docker installed on your system -- A DockerHub account -- Access to Phala Cloud dashboard +#### **Tokens per Agent** -## 🛡️ TEE Overview +- **Free Tier**: 200,000 tokens per agent -For detailed instructions about Trusted Execution Environment setup, please refer to our [TEE Documentation](./tee/README.md). +- **Premium Tier**: 2,000,000 tokens per agent -## 🚀 Deployment Steps +- **Applies to**: Individual agent configurations -### 1. Build and Publish Docker Image +- **Includes**: System prompts, task descriptions, and agent names -```bash -# Build the Docker image -docker compose build -t /swarm-agent-node:latest +#### **Prompt Length Limit** -# Push to DockerHub -docker push /swarm-agent-node:latest -``` +- **All Tiers**: 200,000 tokens maximum -### 2. Deploy to Phala Cloud +- **Applies to**: Combined input text (task + history + system prompts) -Choose one of these deployment methods: -- Use [tee-cloud-cli](https://github.com/Phala-Network/tee-cloud-cli) (Recommended) -- Deploy manually via the [Phala Cloud Dashboard](https://cloud.phala.network/) +- **Error**: Returns 400 error if exceeded -### 3. Verify TEE Attestation +- **Message**: "Prompt is too long. Please provide a prompt that is less than 10000 tokens." -Visit the [TEE Attestation Explorer](https://proof.t16z.com/) to check and verify your agent's TEE proof. +### 3. **Batch Processing Limits** -## 📝 Docker Configuration +These limits control concurrent processing capabilities. -Below is a sample Docker Compose configuration for your Swarms agent: +#### **Batch Size Limit** -```yaml -services: - swarms-agent-server: - image: swarms-agent-node:latest - platform: linux/amd64 - volumes: - - /var/run/tappd.sock:/var/run/tappd.sock - - swarms:/app - restart: always - ports: - - 8000:8000 - command: # Sample MCP Server - - /bin/sh - - -c - - | - cd /app/mcp_example - python mcp_test.py -volumes: - swarms: -``` +- **All Tiers**: 10 agents maximum per batch -## 📚 Additional Resources +- **Applies to**: `/v1/agent/batch/completions` endpoint -For more comprehensive documentation and examples, visit our [Official Documentation](https://docs.swarms.world/en/latest/). +- **Error**: Returns 400 error if exceeded ---- +- **Message**: "ERROR: BATCH SIZE EXCEEDED - You can only run up to 10 batch agents at a time." -> **Note**: Make sure to replace `` with your actual DockerHub username when building and pushing the image. +## How Rate Limiting Works --------------------------------------------------- +### Database-Based Tracking -# File: swarms_cloud/production_deployment.md +The system uses a database-based approach for API key requests: -# Enterprise Guide to High-Performance Multi-Agent LLM Deployments -------- +1. **Request Logging**: Every API request is logged to the `swarms_api_logs` table +2. **Time Window Queries**: The system queries for requests in the last minute, hour, and day +3. **Limit Comparison**: Current counts are compared against configured limits +4. **Request Blocking**: Requests are blocked if any limit is exceeded -As large language models (LLMs) continue to advance and enable a wide range of powerful applications, enterprises are increasingly exploring multi-agent architectures to leverage the collective capabilities of multiple LLMs. However, coordinating and optimizing the performance of these complex multi-agent systems presents significant challenges. +### Sliding Windows -This comprehensive guide provides enterprise architects, engineering leaders, and technical decision-makers with a strategic framework for maximizing performance across multi-agent LLM deployments. Developed through extensive research and collaboration with industry partners, this guide distills best practices, proven techniques, and cutting-edge methodologies into seven core principles. +Rate limits use sliding windows rather than fixed windows: -By implementing the recommendations outlined in this guide, organizations can achieve superior latency, throughput, and resource utilization while ensuring scalability, cost-effectiveness, and optimal user experiences. Whether powering customer-facing conversational agents, driving internal knowledge management systems, or fueling mission-critical decision support tools, high-performance multi-agent LLM deployments will be pivotal to unlocking the full potential of this transformative technology. +- **Minute**: Counts requests in the last 60 seconds -## Introduction +- **Hour**: Counts requests in the last 60 minutes -The rise of large language models (LLMs) has ushered in a new era of human-machine interaction, enabling enterprises to develop sophisticated natural language processing (NLP) applications that can understand, generate, and reason with human-like text. However, as the complexity and scale of LLM deployments grow, traditional monolithic architectures are increasingly challenged to meet the stringent performance, scalability, and cost requirements of enterprise environments. +- **Day**: Counts requests in the last 24 hours -Multi-agent architectures, which coordinate the collective capabilities of multiple specialized LLMs, have emerged as a powerful paradigm for addressing these challenges. By distributing workloads across a cohort of agents, each optimized for specific tasks or domains, multi-agent systems can deliver superior performance, resilience, and adaptability compared to single-model solutions. +This provides more accurate rate limiting compared to fixed time windows. -However, realizing the full potential of multi-agent LLM deployments requires a strategic approach to system design, optimization, and ongoing management. This guide presents a comprehensive framework for maximizing performance across seven core principles, each underpinned by a range of proven techniques and methodologies. +## Checking Your Rate Limits -Whether you are architecting a customer-facing conversational agent, building an internal knowledge management platform, or developing a mission-critical decision support system, this guide will equip you with the insights and best practices necessary to unlock the full potential of multi-agent LLM deployments within your enterprise. +### API Endpoint -## Principle 1: Distribute Token Processing ----------------------------------------- +Use the `/v1/rate/limits` endpoint to check your current usage: -At the heart of every LLM deployment lies the fundamental challenge of optimizing token processing -- the rate at which the model consumes and generates text inputs and outputs. In multi-agent architectures, distributing and parallelizing token processing across multiple agents is a critical performance optimization strategy. +```bash +curl -H "x-api-key: your-api-key" \ + https://api.swarms.world/v1/rate/limits +``` -### Agent Specialization +### Response Format -One of the key advantages of multi-agent architectures is the ability to dedicate specific agents to specialized tasks or domains. By carefully matching agents to the workloads they are optimized for, enterprises can maximize overall throughput and minimize latency. +```json +{ + "success": true, + "rate_limits": { + "minute": { + "count": 5, + "limit": 100, + "exceeded": false, + "remaining": 95, + "reset_time": "2024-01-15T10:30:00Z" + }, + "hour": { + "count": 25, + "limit": 50, + "exceeded": false, + "remaining": 25, + "reset_time": "2024-01-15T11:00:00Z" + }, + "day": { + "count": 150, + "limit": 1200, + "exceeded": false, + "remaining": 1050, + "reset_time": "2024-01-16T10:00:00Z" + } + }, + "limits": { + "maximum_requests_per_minute": 100, + "maximum_requests_per_hour": 50, + "maximum_requests_per_day": 1200, + "tokens_per_agent": 200000 + }, + "timestamp": "2024-01-15T10:29:30Z" +} +``` -For example, in a conversational agent deployment, one agent may be optimized for intent recognition and query understanding, while another is fine-tuned for generating coherent, context-aware responses. In a document processing pipeline, separate agents could be dedicated to tasks such as named entity recognition, sentiment analysis, and summarization. +## Handling Rate Limit Errors -To effectively leverage agent specialization, enterprises should: +### Error Response -- Conduct a thorough analysis of their application's workflow and identify distinct tasks or domains that could benefit from dedicated agents. -- Evaluate the strengths and weaknesses of available LLM models and agents, and map them to the identified tasks or domains based on their capabilities and performance characteristics. -- Implement continuous monitoring and performance tuning processes to ensure agents remain optimized for their assigned workloads as models evolve and domain requirements shift. +When rate limits are exceeded, you'll receive a 429 status code: -### Load Balancing +```json +{ + "detail": "Rate limit exceeded for minute window(s). Upgrade to Premium for increased limits (2,000/min, 10,000/hour, 100,000/day) at https://swarms.world/platform/account for just $99/month." +} +``` -Even with a well-designed allocation of tasks across specialized agents, fluctuations in workload and demand can create bottlenecks and performance degradation. Effective load balancing strategies are essential to ensure that token processing capacity is dynamically distributed across available agents based on real-time conditions. +### Best Practices -Load balancing in multi-agent LLM deployments can be accomplished through a combination of techniques, including: +1. **Monitor Usage**: Regularly check your rate limits using the `/v1/rate/limits` endpoint +2. **Implement Retry Logic**: Use exponential backoff when hitting rate limits +3. **Optimize Requests**: Combine multiple operations into single requests when possible +4. **Upgrade When Needed**: Consider upgrading to Premium for higher limits -- **Round-Robin**: Distributing incoming requests across agents in a cyclical fashion, ensuring an even distribution of workload. -- **Least Connections**: Routing requests to the agent with the fewest active connections or outstanding tasks, minimizing the risk of overloading any single agent. -- **Response Time Monitoring**: Continuously monitoring the response times of each agent and dynamically adjusting request routing to favor faster-responding agents. -- **Resource-Based Routing**: Factoring in agent-level resource consumption (e.g., CPU, memory) when making routing decisions, ensuring that overloaded agents are relieved of additional workload. +## Premium Tier Benefits -Implementing effective load balancing requires careful consideration of the specific characteristics and requirements of your multi-agent deployment, as well as the integration of robust monitoring and analytics capabilities to inform dynamic routing decisions. +Upgrade to Premium for significantly higher limits: -### Horizontal Scaling +- **20x more requests per minute** (2,000 vs 100) -While load balancing optimizes the utilization of existing agent resources, horizontal scaling strategies enable organizations to dynamically provision additional token processing capacity to meet demand spikes or handle larger overall workloads. +- **200x more requests per hour** (10,000 vs 50) -In multi-agent LLM deployments, horizontal scaling can be achieved through: +- **83x more requests per day** (100,000 vs 1,200) -- **Agent Replication**: Spin up additional instances of existing agents to increase parallel processing capacity for specific tasks or domains. -- **Hybrid Scaling**: Combine agent replication with the dynamic provisioning of additional compute resources (e.g., CPU, GPU) to support the increased agent count. -- **Serverless Deployment**: Leverage serverless computing platforms (e.g., AWS Lambda, Google Cloud Functions) to automatically scale agent instances based on real-time demand, minimizing idle resource consumption. +- **10x more tokens per agent** (2M vs 200K) -Effective horizontal scaling requires robust orchestration and management capabilities, as well as seamless integration with load balancing mechanisms to ensure that incoming workloads are efficiently distributed across the dynamically scaled agent pool. +Visit [Swarms Platform Account](https://swarms.world/platform/account) to upgrade for just $99/month. -## Principle 2: Optimize Agent Communication ------------------------------------------ +## Performance Considerations -In multi-agent LLM deployments, efficient inter-agent communication is crucial for coordinating tasks, exchanging context and intermediate results, and maintaining overall system coherence. However, communication overhead can quickly become a performance bottleneck if not carefully managed. +- Database queries are optimized to only count request IDs +- Rate limit checks are cached per request +- Fallback mechanisms ensure system reliability +- Minimal impact on request latency +- Persistent tracking across server restarts -### Minimizing Overhead +-------------------------------------------------- -Reducing the volume and complexity of information exchanged between agents is a key strategy for optimizing communication performance. Techniques for minimizing overhead include: +# File: swarms_cloud\rust_client.md -- **Data Compression**: Applying lossless or lossy compression algorithms to reduce the size of data payloads exchanged between agents, lowering bandwidth requirements and transmission latencies. -- **Information Summarization**: Distilling and summarizing context, results, or other data exchanged between agents to its essential elements, minimizing redundant or non-critical information. -- **Differential Updates**: Rather than transmitting entire data payloads, agents can exchange only the differential updates or deltas required to synchronize their respective states. +# Swarms Client - Production Grade Rust SDK -Implementing these techniques requires careful analysis of the specific data exchange patterns and communication requirements within your multi-agent deployment, as well as the integration of appropriate compression, summarization, and differential update algorithms. +A high-performance, production-ready Rust client for the Swarms API with comprehensive features for building multi-agent AI systems. -### Prioritizing Critical Information +## Features -In scenarios where communication bandwidth or latency constraints cannot be fully alleviated through overhead reduction techniques, enterprises can prioritize the exchange of critical information over non-essential data. +- **🚀 High Performance**: Built with `reqwest` and `tokio` for maximum throughput +- **🔄 Connection Pooling**: Automatic HTTP connection reuse and pooling +- **⚡ Circuit Breaker**: Automatic failure detection and recovery +- **💾 Intelligent Caching**: TTL-based in-memory caching with concurrent access +- **📊 Rate Limiting**: Configurable concurrent request limits +- **🔄 Retry Logic**: Exponential backoff with jitter +- **📝 Comprehensive Logging**: Structured logging with `tracing` +- **✅ Type Safety**: Full compile-time type checking with `serde` -This can be achieved through: +## Installation -- **Prioritized Queuing**: Implementing queuing mechanisms that prioritize the transmission of high-priority, time-sensitive data over lower-priority, non-critical information. -- **Selective Communication**: Dynamically determining which agents require specific pieces of information based on their roles and responsibilities, and selectively transmitting data only to those agents that truly need it. -- **Progressive Information Exchange**: Exchanging information in a progressive or staged manner, with critical elements transmitted first, followed by supplementary or contextual data as bandwidth becomes available. +Install `swarms-rs` globally using cargo: -Effective prioritization requires a deep understanding of the interdependencies and information flow within your multi-agent system, as well as the ability to dynamically assess and prioritize data based on its criticality and urgency. +```bash +cargo install swarms-rs +``` -### Caching and Reusing Context -In many multi-agent LLM deployments, agents frequently exchange or operate on shared context, such as user profiles, conversation histories, or domain-specific knowledge bases. Caching and reusing this context information can significantly reduce redundant communication and processing overhead. -Strategies for optimizing context caching and reuse include: -- **Agent-Level Caching**: Implementing caching mechanisms within individual agents to store and retrieve frequently accessed context data, minimizing the need for inter-agent communication. -- **Centralized Context Management**: Deploying a dedicated context management service or data store that agents can query and update, ensuring consistent access to the latest context information across the system. -- **Context Versioning and Invalidation**: Implementing versioning and invalidation mechanisms to ensure that cached context data remains fresh and consistent, avoiding stale or outdated information from propagating through the system. +## Quick Start -### Principle 3: Leverage Agent Specialization ------------------------------------------- +```rust +use swarms_client::SwarmsClient; -One of the key advantages of multi-agent architectures is the ability to optimize individual agents for specific tasks, domains, or capabilities. By leveraging agent specialization, enterprises can ensure that each component of their LLM system is finely tuned for maximum performance and quality. +#[tokio::main] +async fn main() -> Result<(), Box> { + // Initialize the client with API key from environment + let client = SwarmsClient::builder() + .unwrap() + .from_env()? // Loads API key from SWARMS_API_KEY environment variable + .timeout(std::time::Duration::from_secs(60)) + .max_retries(3) + .build()?; + + // Make a simple swarm completion request + let response = client.swarm() + .completion() + .name("My First Swarm") + .swarm_type(SwarmType::Auto) + .task("Analyze the pros and cons of quantum computing") + .agent(|agent| { + agent + .name("Researcher") + .description("Conducts in-depth research") + .model("gpt-4o") + }) + .send() + .await?; -### Task-Specific Optimization + println!("Swarm output: {}", response.output); + Ok(()) +} +``` -Within a multi-agent LLM deployment, different agents may be responsible for distinct tasks such as language understanding, knowledge retrieval, response generation, or post-processing. Optimizing each agent for its designated task can yield significant performance gains and quality improvements. +## API Reference -Techniques for task-specific optimization include: +### SwarmsClient -- **Prompt Engineering**: Crafting carefully designed prompts that provide the necessary context, instructions, and examples to guide an agent towards optimal performance for its assigned task. -- **Fine-Tuning**: Adapting a pre-trained LLM to a specific task or domain by fine-tuning it on a curated dataset, allowing the agent to specialize and improve its performance on that particular workload. -- **Model Distillation**: Transferring the knowledge and capabilities of a larger, more capable LLM into a smaller, more efficient model specialized for a specific task, balancing performance and quality trade-offs. +The main client for interacting with the Swarms API. -Implementing these optimization techniques requires a deep understanding of the capabilities and requirements of each task within your multi-agent system, as well as access to relevant training data and computational resources for fine-tuning and distillation processes. +#### Constructor Methods -### Domain Adaptation +##### `SwarmsClient::builder()` -Many enterprise applications operate within specific domains or verticals, such as finance, healthcare, or legal. Adapting agents to these specialized domains can significantly improve their performance, accuracy, and compliance within the target domain. +Creates a new client builder for configuring the client. -Strategies for domain adaptation include: +**Returns**: `Result` -- **Domain-Specific Pre-Training**: Leveraging domain-specific corpora to pre-train LLM agents, imbuing them with a foundational understanding of the language, concepts, and nuances specific to the target domain. -- **Transfer Learning**: Fine-tuning agents that have been pre-trained on general or adjacent domains, transferring their existing knowledge and capabilities to the target domain while optimizing for its specific characteristics. -- **Domain Persona Injection**: Injecting domain-specific personas, traits, or constraints into agents during fine-tuning or deployment, shaping their behavior and outputs to align with domain-specific norms and requirements. +**Example**: +```rust +let client = SwarmsClient::builder() + .unwrap() + .api_key("your-api-key") + .timeout(Duration::from_secs(60)) + .build()?; +``` -Effective domain adaptation requires access to high-quality, domain-specific training data, as well as close collaboration with subject matter experts to ensure that agents are properly calibrated to meet the unique demands of the target domain. +##### `SwarmsClient::with_config(config: ClientConfig)` -### Ensemble Techniques +Creates a client with custom configuration. -In complex multi-agent deployments, individual agents may excel at specific subtasks or aspects of the overall workflow. Ensemble techniques that combine the outputs or predictions of multiple specialized agents can often outperform any single agent, leveraging the collective strengths of the ensemble. +| Parameter | Type | Description | +|-----------|------|-------------| +| `config` | `ClientConfig` | Client configuration settings | -Common ensemble techniques for multi-agent LLM systems include: +**Returns**: `Result` -- **Voting**: Combining the outputs or predictions of multiple agents through majority voting, weighted voting, or other consensus mechanisms. -- **Stacking**: Training a meta-agent to combine and optimize the outputs of multiple base agents, effectively learning to leverage their collective strengths. -- **Blending**: Combining the outputs of multiple agents through weighted averaging, linear interpolation, or other blending techniques, allowing for nuanced integration of diverse perspectives. +**Example**: +```rust +let config = ClientConfig { + api_key: "your-api-key".to_string(), + base_url: "https://api.swarms.com/".parse().unwrap(), + timeout: Duration::from_secs(120), + max_retries: 5, + ..Default::default() +}; -Implementing effective ensemble techniques requires careful analysis of the strengths, weaknesses, and complementary capabilities of individual agents, as well as the development of robust combination strategies that can optimally leverage the ensemble's collective intelligence. +let client = SwarmsClient::with_config(config)?; +``` -### Principle 4: Implement Dynamic Scaling --------------------------------------- +#### Resource Access Methods -The demand and workload patterns of enterprise LLM deployments can be highly dynamic, with significant fluctuations driven by factors such as user activity, data ingestion schedules, or periodic batch processing. Implementing dynamic scaling strategies allows organizations to optimally provision and allocate resources in response to these fluctuations, ensuring consistent performance while minimizing unnecessary costs. +| Method | Returns | Description | +|--------|---------|-------------| +| `agent()` | `AgentResource` | Access agent-related operations | +| `swarm()` | `SwarmResource` | Access swarm-related operations | +| `models()` | `ModelsResource` | Access model listing operations | +| `logs()` | `LogsResource` | Access logging operations | -### Autoscaling +#### Cache Management Methods -Autoscaling is a core capability that enables the automatic adjustment of compute resources (e.g., CPU, GPU, memory) and agent instances based on real-time demand patterns and workload metrics. By dynamically scaling resources up or down, enterprises can maintain optimal performance and resource utilization, avoiding both over-provisioning and under-provisioning scenarios. +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| `clear_cache()` | None | `()` | Clears all cached responses | +| `cache_stats()` | None | `Option<(usize, usize)>` | Returns (valid_entries, total_entries) | -Effective autoscaling in multi-agent LLM deployments requires: +### ClientBuilder -- **Monitoring and Metrics**: Implementing robust monitoring and metrics collection mechanisms to track key performance indicators (KPIs) such as request rates, response times, resource utilization, and agent-level metrics. -- **Scaling Policies**: Defining scaling policies that specify the conditions and thresholds for triggering automatic scaling actions, such as provisioning additional agents or compute resources when certain KPIs are breached. -- **Scaling Orchestration**: Integrating autoscaling capabilities with resource orchestration and management tools (e.g., Kubernetes, AWS Auto Scaling) to seamlessly provision, configure, and integrate new resources into the existing multi-agent deployment. +Builder for configuring the Swarms client. -By automating the scaling process, enterprises can respond rapidly to workload fluctuations, ensuring consistent performance and optimal resource utilization without the need for manual intervention. +#### Configuration Methods -### Spot Instance Utilization +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| `new()` | None | `ClientBuilder` | Creates a new builder with defaults | +| `from_env()` | None | `Result` | Loads API key from environment | +| `api_key(key)` | `String` | `ClientBuilder` | Sets the API key | +| `base_url(url)` | `&str` | `Result` | Sets the base URL | +| `timeout(duration)` | `Duration` | `ClientBuilder` | Sets request timeout | +| `max_retries(count)` | `usize` | `ClientBuilder` | Sets maximum retry attempts | +| `retry_delay(duration)` | `Duration` | `ClientBuilder` | Sets retry delay duration | +| `max_concurrent_requests(count)` | `usize` | `ClientBuilder` | Sets concurrent request limit | +| `enable_cache(enabled)` | `bool` | `ClientBuilder` | Enables/disables caching | +| `cache_ttl(duration)` | `Duration` | `ClientBuilder` | Sets cache TTL | +| `build()` | None | `Result` | Builds the client | -Many cloud providers offer spot instances or preemptible resources at significantly discounted prices compared to on-demand or reserved instances. While these resources may be reclaimed with little notice, they can be leveraged judiciously within multi-agent LLM deployments to reduce operational costs. +**Example**: +```rust +let client = SwarmsClient::builder() + .unwrap() + .from_env()? + .timeout(Duration::from_secs(120)) + .max_retries(5) + .max_concurrent_requests(50) + .enable_cache(true) + .cache_ttl(Duration::from_secs(600)) + .build()?; +``` -Strategies for leveraging spot instances include: +### SwarmResource -- **Fault-Tolerant Agent Deployment**: Deploying certain agents or components of the multi-agent system on spot instances, while ensuring that these components can be rapidly and seamlessly replaced or migrated in the event of instance preemption. -- **Batch Workload Offloading**: Offloading batch processing workloads or non-time-sensitive tasks to spot instances, leveraging their cost-effectiveness while minimizing the impact of potential disruptions. -- **Hybrid Provisioning**: Implementing a hybrid approach that combines on-demand or reserved instances for mission-critical components with spot instances for more flexible or elastic workloads. +Resource for swarm-related operations. -Effective spot instance utilization requires careful architectural considerations to ensure fault tolerance and minimize the impact of potential disruptions, as well as robust monitoring and automation capabilities to seamlessly replace or migrate workloads in response to instance preemption events. +#### Methods -### Serverless Deployments +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| `completion()` | None | `SwarmCompletionBuilder` | Creates a new swarm completion builder | +| `create(request)` | `SwarmSpec` | `Result` | Creates a swarm completion directly | +| `create_batch(requests)` | `Vec` | `Result, SwarmsError>` | Creates multiple swarm completions | +| `list_types()` | None | `Result` | Lists available swarm types | -Serverless computing platforms, such as AWS Lambda, Google Cloud Functions, or Azure Functions, offer a compelling alternative to traditional server-based deployments. By automatically scaling compute resources based on real-time demand and charging only for the resources consumed, serverless architectures can provide significant cost savings and operational simplicity. +### SwarmCompletionBuilder -Leveraging serverless deployments for multi-agent LLM systems can be achieved through: +Builder for creating swarm completion requests. -- **Function-as-a-Service (FaaS) Agents**: Deploying individual agents or components of the multi-agent system as serverless functions, allowing for rapid and automatic scaling in response to fluctuating workloads. -- **Event-Driven Architectures**: Designing the multi-agent system to operate in an event-driven manner, with agents triggered and executed in response to specific events or data ingestion, aligning with the serverless execution model. -- **Hybrid Deployments**: Combining serverless components with traditional server-based components, leveraging the strengths and cost advantages of each deployment model for different aspects of the multi-agent system. +#### Configuration Methods -Adopting serverless architectures requires careful consideration of factors such as execution duration limits, cold start latencies, and integration with other components of the multi-agent deployment. However, when implemented effectively, serverless deployments can provide unparalleled scalability, cost-efficiency, and operational simplicity for dynamic, event-driven workloads. +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| `name(name)` | `String` | `SwarmCompletionBuilder` | Sets the swarm name | +| `description(desc)` | `String` | `SwarmCompletionBuilder` | Sets the swarm description | +| `swarm_type(type)` | `SwarmType` | `SwarmCompletionBuilder` | Sets the swarm type | +| `task(task)` | `String` | `SwarmCompletionBuilder` | Sets the main task | +| `agent(builder_fn)` | `Fn(AgentSpecBuilder) -> AgentSpecBuilder` | `SwarmCompletionBuilder` | Adds an agent using a builder function | +| `max_loops(count)` | `u32` | `SwarmCompletionBuilder` | Sets maximum execution loops | +| `service_tier(tier)` | `String` | `SwarmCompletionBuilder` | Sets the service tier | +| `send()` | None | `Result` | Sends the request | +### AgentResource -### Principle 5: Employ Selective Execution ---------------------------------------- +Resource for agent-related operations. -Not every input or request within a multi-agent LLM deployment requires the full execution of all agents or the complete processing pipeline. Selectively invoking agents or tasks based on input characteristics or intermediate results can significantly optimize performance by avoiding unnecessary computation and resource consumption. +#### Methods -### Input Filtering +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| `completion()` | None | `AgentCompletionBuilder` | Creates a new agent completion builder | +| `create(request)` | `AgentCompletion` | `Result` | Creates an agent completion directly | +| `create_batch(requests)` | `Vec` | `Result, SwarmsError>` | Creates multiple agent completions | -Implementing input filtering mechanisms allows enterprises to reject or bypass certain inputs before they are processed by the multi-agent system. This can be achieved through techniques such as: +### AgentCompletionBuilder -- **Blacklisting/Whitelisting**: Maintaining lists of inputs (e.g., specific phrases, URLs, or content types) that should be automatically rejected or allowed, based on predefined criteria. -- **Rules-Based Filtering**: Defining a set of rules or heuristics to assess the suitability or relevance of an input for further processing, based on factors such as language, content, or metadata. -- **Confidence Thresholding**: Leveraging pre-processing agents or models to assess the likelihood that an input is relevant or valuable, and filtering out inputs that fall below a predetermined confidence threshold. +Builder for creating agent completion requests. -Effective input filtering requires careful consideration of the specific requirements, constraints, and objectives of your multi-agent deployment, as well as ongoing monitoring and adjustment of filtering rules and thresholds to maintain optimal performance and accuracy. +#### Configuration Methods -### Early Stopping +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| `agent_name(name)` | `String` | `AgentCompletionBuilder` | Sets the agent name | +| `task(task)` | `String` | `AgentCompletionBuilder` | Sets the task | +| `model(model)` | `String` | `AgentCompletionBuilder` | Sets the AI model | +| `description(desc)` | `String` | `AgentCompletionBuilder` | Sets the agent description | +| `system_prompt(prompt)` | `String` | `AgentCompletionBuilder` | Sets the system prompt | +| `temperature(temp)` | `f32` | `AgentCompletionBuilder` | Sets the temperature (0.0-1.0) | +| `max_tokens(tokens)` | `u32` | `AgentCompletionBuilder` | Sets maximum tokens | +| `max_loops(loops)` | `u32` | `AgentCompletionBuilder` | Sets maximum loops | +| `send()` | None | `Result` | Sends the request | + +### SwarmType Enum + +Available swarm types for different execution patterns. + +| Variant | Description | +|---------|-------------| +| `AgentRearrange` | Agents can be rearranged based on task requirements | +| `MixtureOfAgents` | Combines multiple agents with different specializations | +| `SpreadSheetSwarm` | Organized like a spreadsheet with structured data flow | +| `SequentialWorkflow` | Agents execute in a sequential order | +| `ConcurrentWorkflow` | Agents execute concurrently | +| `GroupChat` | Agents interact in a group chat format | +| `MultiAgentRouter` | Routes tasks between multiple agents | +| `AutoSwarmBuilder` | Automatically builds swarm structure | +| `HiearchicalSwarm` | Hierarchical organization of agents | +| `Auto` | Automatically selects the best swarm type | +| `MajorityVoting` | Agents vote on decisions | +| `Malt` | Multi-Agent Language Tasks | +| `DeepResearchSwarm` | Specialized for deep research tasks | + +## Detailed Examples + +### 1. Simple Agent Completion -In many multi-agent LLM deployments, intermediate results or predictions generated by early-stage agents can be used to determine whether further processing is required or valuable. Early stopping mechanisms allow enterprises to terminate execution pipelines when specific conditions or thresholds are met, avoiding unnecessary downstream processing. +```rust +use swarms_client::{SwarmsClient}; -Techniques for implementing early stopping include: +#[tokio::main] +async fn main() -> Result<(), Box> { + let client = SwarmsClient::builder() + .unwrap() + .from_env()? + .build()?; + + let response = client.agent() + .completion() + .agent_name("Content Writer") + .task("Write a blog post about sustainable technology") + .model("gpt-4o") + .temperature(0.7) + .max_tokens(2000) + .description("An expert content writer specializing in technology topics") + .system_prompt("You are a professional content writer with expertise in technology and sustainability. Write engaging, informative content that is well-structured and SEO-friendly.") + .send() + .await?; -- **Confidence-Based Stopping**: Monitoring the confidence scores or probabilities associated with intermediate results, and terminating execution if a predefined confidence threshold is exceeded. -- **Exception-Based Stopping**: Defining specific intermediate results or conditions that indicate that further processing is unnecessary or undesirable, and terminating execution upon encountering these exceptions. -- **Adaptive Stopping**: Employing machine learning models or reinforcement learning agents to dynamically determine when to terminate execution based on learned patterns and trade-offs between accuracy, latency, and resource consumption. + println!("Agent Response: {}", response.outputs); + println!("Tokens Used: {}", response.usage.total_tokens); + + Ok(()) +} +``` -Effective early stopping requires a deep understanding of the interdependencies and decision points within your multi-agent workflow, as well as careful tuning and monitoring to ensure that stopping conditions are calibrated to maintain an optimal balance between performance and accuracy. +### 2. Multi-Agent Research Swarm -### Conditional Branching +```rust +use swarms_client::{SwarmsClient, SwarmType}; -Rather than executing a linear, fixed pipeline of agents, conditional branching allows multi-agent systems to dynamically invoke different agents or execution paths based on input characteristics or intermediate results. This can significantly optimize resource utilization by ensuring that only the necessary agents and processes are executed for a given input or scenario. +#[tokio::main] +async fn main() -> Result<(), Box> { + let client = SwarmsClient::builder() + .unwrap() + .from_env()? + .timeout(Duration::from_secs(300)) // 5 minutes for complex tasks + .build()?; + + let response = client.swarm() + .completion() + .name("AI Research Swarm") + .description("A comprehensive research team analyzing AI trends and developments") + .swarm_type(SwarmType::SequentialWorkflow) + .task("Conduct a comprehensive analysis of the current state of AI in healthcare, including recent developments, challenges, and future prospects") + + // Data Collection Agent + .agent(|agent| { + agent + .name("Data Collector") + .description("Gathers comprehensive data and recent developments") + .model("gpt-4o") + .system_prompt("You are a research data collector specializing in AI and healthcare. Your job is to gather the most recent and relevant information about AI applications in healthcare, including clinical trials, FDA approvals, and industry developments.") + .temperature(0.3) + .max_tokens(3000) + }) + + // Technical Analyst + .agent(|agent| { + agent + .name("Technical Analyst") + .description("Analyzes technical aspects and implementation details") + .model("gpt-4o") + .system_prompt("You are a technical analyst with deep expertise in AI/ML technologies. Analyze the technical feasibility, implementation challenges, and technological requirements of AI solutions in healthcare.") + .temperature(0.4) + .max_tokens(3000) + }) + + // Market Analyst + .agent(|agent| { + agent + .name("Market Analyst") + .description("Analyzes market trends, adoption rates, and economic factors") + .model("gpt-4o") + .system_prompt("You are a market research analyst specializing in healthcare technology markets. Analyze market size, growth projections, key players, investment trends, and economic factors affecting AI adoption in healthcare.") + .temperature(0.5) + .max_tokens(3000) + }) + + // Regulatory Expert + .agent(|agent| { + agent + .name("Regulatory Expert") + .description("Analyzes regulatory landscape and compliance requirements") + .model("gpt-4o") + .system_prompt("You are a regulatory affairs expert with deep knowledge of healthcare regulations and AI governance. Analyze regulatory challenges, compliance requirements, ethical considerations, and policy developments affecting AI in healthcare.") + .temperature(0.3) + .max_tokens(3000) + }) + + // Report Synthesizer + .agent(|agent| { + agent + .name("Report Synthesizer") + .description("Synthesizes all analyses into a comprehensive report") + .model("gpt-4o") + .system_prompt("You are an expert report writer and strategic analyst. Synthesize all the previous analyses into a comprehensive, well-structured executive report with clear insights, recommendations, and future outlook.") + .temperature(0.6) + .max_tokens(4000) + }) + + .max_loops(1) + .service_tier("premium") + .send() + .await?; -Implementing conditional branching involves: + println!("Research Report:"); + println!("{}", response.output); + println!("\nSwarm executed with {} agents", response.number_of_agents); + + Ok(()) +} +``` -- **Decision Points**: Identifying key points within the multi-agent workflow where branching decisions can be made based on input or intermediate data. -- **Branching Logic**: Defining the rules, conditions, or machine learning models that will evaluate the input or intermediate data and determine the appropriate execution path or agent invocation. -- **Execution Routing**: Integrating mechanisms to dynamically route inputs or intermediate data to the appropriate agents or processes based on the branching decision. +### 3. Financial Analysis Swarm (From Example) -Conditional branching can be particularly effective in scenarios where inputs or workloads exhibit distinct characteristics or require significantly different processing pipelines, allowing enterprises to optimize resource allocation and minimize unnecessary computation. +```rust +use swarms_client::{SwarmsClient, SwarmType}; -### Principle 6: Optimize User Experience -------------------------------------- +#[tokio::main] +async fn main() -> Result<(), Box> { + let client = SwarmsClient::builder() + .unwrap() + .from_env()? + .timeout(Duration::from_secs(120)) + .max_retries(3) + .build()?; + + let response = client.swarm() + .completion() + .name("Financial Health Analysis Swarm") + .description("A sequential workflow of specialized financial agents analyzing company health") + .swarm_type(SwarmType::ConcurrentWorkflow) + .task("Analyze the financial health of Apple Inc. (AAPL) based on their latest quarterly report") + + // Financial Data Collector Agent + .agent(|agent| { + agent + .name("Financial Data Collector") + .description("Specializes in gathering and organizing financial data from various sources") + .model("gpt-4o") + .system_prompt("You are a financial data collection specialist. Your role is to gather and organize relevant financial data, including revenue, expenses, profit margins, and key financial ratios. Present the data in a clear, structured format.") + .temperature(0.7) + .max_tokens(2000) + }) + + // Financial Ratio Analyzer Agent + .agent(|agent| { + agent + .name("Ratio Analyzer") + .description("Analyzes key financial ratios and metrics") + .model("gpt-4o") + .system_prompt("You are a financial ratio analysis expert. Your role is to calculate and interpret key financial ratios such as P/E ratio, debt-to-equity, current ratio, and return on equity. Provide insights on what these ratios indicate about the company's financial health.") + .temperature(0.7) + .max_tokens(2000) + }) + + // Additional agents... + .agent(|agent| { + agent + .name("Investment Advisor") + .description("Provides investment recommendations based on analysis") + .model("gpt-4o") + .system_prompt("You are an investment advisory specialist. Your role is to synthesize the analysis from previous agents and provide clear, actionable investment recommendations. Consider both short-term and long-term investment perspectives.") + .temperature(0.7) + .max_tokens(2000) + }) + + .max_loops(1) + .service_tier("standard") + .send() + .await?; -While many of the principles outlined in this guide focus on optimizing backend performance and resource utilization, delivering an exceptional user experience is also a critical consideration for enterprise multi-agent LLM deployments. By minimizing perceived wait times and providing real-time progress updates, organizations can ensure that users remain engaged and satisfied, even during periods of high workload or resource constraints. + println!("Financial Analysis Results:"); + println!("{}", response.output); + + Ok(()) +} +``` -### Streaming Responses +### 4. Batch Processing -One of the most effective techniques for minimizing perceived wait times is to stream responses or outputs to users as they are generated, rather than waiting for the entire response to be completed before delivering it. This approach is particularly valuable in conversational agents, document summarization, or other scenarios where outputs can be naturally segmented and delivered incrementally. +```rust +use swarms_client::{SwarmsClient, AgentCompletion, AgentSpec}; -Implementing streaming responses requires: +#[tokio::main] +async fn main() -> Result<(), Box> { + let client = SwarmsClient::builder() + .unwrap() + .from_env()? + .max_concurrent_requests(20) // Allow more concurrent requests for batch + .build()?; + + // Create multiple agent completion requests + let requests = vec![ + AgentCompletion { + agent_config: AgentSpec { + agent_name: "Content Creator 1".to_string(), + model_name: "gpt-4o-mini".to_string(), + temperature: 0.7, + max_tokens: 1000, + ..Default::default() + }, + task: "Write a social media post about renewable energy".to_string(), + history: None, + }, + AgentCompletion { + agent_config: AgentSpec { + agent_name: "Content Creator 2".to_string(), + model_name: "gpt-4o-mini".to_string(), + temperature: 0.8, + max_tokens: 1000, + ..Default::default() + }, + task: "Write a social media post about electric vehicles".to_string(), + history: None, + }, + // Add more requests... + ]; -- **Partial Output Generation**: Modifying agents or models to generate and emit outputs in a streaming or incremental fashion, rather than producing the entire output in a single, monolithic operation. -- **Streaming Data Pipelines**: Integrating streaming data pipelines and message queues to enable the efficient and reliable transmission of partial outputs from agents to user-facing interfaces or applications. -- **Incremental Rendering**: Updating user interfaces and displays to incrementally render or populate with newly streamed output segments, providing a seamless and real-time experience for end-users. + // Process all requests in batch + let responses = client.agent() + .create_batch(requests) + .await?; -By delivering outputs as they are generated, streaming responses can significantly improve the perceived responsiveness and interactivity of multi-agent LLM deployments, even in scenarios where the overall processing time remains unchanged. + for (i, response) in responses.iter().enumerate() { + println!("Response {}: {}", i + 1, response.outputs); + println!("Tokens used: {}\n", response.usage.total_tokens); + } + + Ok(()) +} +``` -### Progress Indicators +### 5. Custom Configuration with Error Handling -In cases where streaming responses may not be feasible or appropriate, providing visual or textual indicators of ongoing processing and progress can help manage user expectations and improve the overall experience. Progress indicators can be implemented through techniques such as: +```rust +use swarms_client::{SwarmsClient, SwarmsError, ClientConfig}; +use std::time::Duration; -- **Loader Animations**: Displaying simple animations or spinner graphics to indicate that processing is underway and provide a sense of activity and progress. -- **Progress Bars**: Rendering progress bars or completion indicators based on estimated or actual progress through multi-agent workflows or processing pipelines. -- **Status Updates**: Periodically updating user interfaces with textual status messages or descriptions of the current processing stage, providing users with a more detailed understanding of the system's activities. +#[tokio::main] +async fn main() -> Result<(), Box> { + // Custom configuration for production use + let config = ClientConfig { + api_key: std::env::var("SWARMS_API_KEY")?, + base_url: "https://swarms-api-285321057562.us-east1.run.app/".parse()?, + timeout: Duration::from_secs(180), + max_retries: 5, + retry_delay: Duration::from_secs(2), + max_concurrent_requests: 50, + circuit_breaker_threshold: 10, + circuit_breaker_timeout: Duration::from_secs(120), + enable_cache: true, + cache_ttl: Duration::from_secs(600), + }; -Effective progress indicators require careful integration with monitoring and telemetry capabilities to accurately track and communicate the progress of multi-agent workflows, as well as thoughtful user experience design to ensure that indicators are clear, unobtrusive, and aligned with user expectations. + let client = SwarmsClient::with_config(config)?; + + // Example with comprehensive error handling + match client.swarm() + .completion() + .name("Production Swarm") + .swarm_type(SwarmType::Auto) + .task("Analyze market trends for Q4 2024") + .agent(|agent| { + agent + .name("Market Analyst") + .model("gpt-4o") + .temperature(0.5) + }) + .send() + .await + { + Ok(response) => { + println!("Success! Job ID: {}", response.job_id); + println!("Output: {}", response.output); + }, + Err(SwarmsError::Authentication { message, .. }) => { + eprintln!("Authentication error: {}", message); + }, + Err(SwarmsError::RateLimit { message, .. }) => { + eprintln!("Rate limit exceeded: {}", message); + // Implement backoff strategy + }, + Err(SwarmsError::InsufficientCredits { message, .. }) => { + eprintln!("Insufficient credits: {}", message); + }, + Err(SwarmsError::CircuitBreakerOpen) => { + eprintln!("Circuit breaker is open - service temporarily unavailable"); + }, + Err(e) => { + eprintln!("Other error: {}", e); + } + } + + Ok(()) +} +``` -### Chunked Delivery +### 6. Monitoring and Observability -In scenarios where outputs or responses cannot be effectively streamed or rendered incrementally, chunked delivery can provide a middle ground between delivering the entire output at once and streaming individual tokens or characters. By breaking larger outputs into smaller, more manageable chunks and delivering them individually, enterprises can improve perceived responsiveness and provide a more engaging user experience. +```rust +use swarms_client::SwarmsClient; +use tracing::{info, warn, error}; -Implementing chunked delivery involves: +#[tokio::main] +async fn main() -> Result<(), Box> { + // Initialize tracing for observability + tracing_subscriber::init(); + + let client = SwarmsClient::builder() + .unwrap() + .from_env()? + .enable_cache(true) + .build()?; + + // Monitor cache performance + if let Some((valid, total)) = client.cache_stats() { + info!("Cache stats: {}/{} entries valid", valid, total); + } -- **Output Segmentation**: Identifying logical breakpoints or segmentation boundaries within larger outputs, such as paragraphs, sections, or other structural elements. -- **Chunking Mechanisms**: Integrating mechanisms to efficiently break outputs into individual chunks and transmit or render them sequentially, with minimal delay between chunks. -- **Chunk Rendering**: Updating user interfaces or displays to seamlessly render or append new output chunks as they are received, providing a sense of continuous progress and minimizing the perception of extended waiting periods. + // Make request with monitoring + let start = std::time::Instant::now(); + + let response = client.swarm() + .completion() + .name("Monitored Swarm") + .task("Analyze system performance metrics") + .agent(|agent| { + agent + .name("Performance Analyst") + .model("gpt-4o-mini") + }) + .send() + .await?; -Chunked delivery can be particularly effective in scenarios where outputs are inherently structured or segmented, such as document generation, report creation, or multi-step instructions or workflows. + let duration = start.elapsed(); + info!("Request completed in {:?}", duration); + + if duration > Duration::from_secs(30) { + warn!("Request took longer than expected: {:?}", duration); + } -## Principle 7: Leverage Hybrid Approaches ---------------------------------------- + // Clear cache periodically in production + client.clear_cache(); + + Ok(()) +} +``` -While multi-agent LLM architectures offer numerous advantages, they should not be viewed as a one-size-fits-all solution. In many cases, combining LLM agents with traditional techniques, optimized components, or external services can yield superior performance, cost-effectiveness, and resource utilization compared to a pure LLM-based approach. +## Error Handling -### Task Offloading +The client provides comprehensive error handling with specific error types: -Certain tasks or subtasks within a larger multi-agent workflow may be more efficiently handled by dedicated, optimized components or external services, rather than relying solely on LLM agents. Task offloading involves identifying these opportunities and integrating the appropriate components or services into the overall architecture. +### SwarmsError Types -Examples of task offloading in multi-agent LLM deployments include: +| Error Type | Description | Recommended Action | +|------------|-------------|-------------------| +| `Authentication` | Invalid API key or authentication failure | Check API key and permissions | +| `RateLimit` | Rate limit exceeded | Implement exponential backoff | +| `InvalidRequest` | Malformed request parameters | Validate input parameters | +| `InsufficientCredits` | Not enough credits for operation | Check account balance | +| `Api` | General API error | Check API status and retry | +| `Network` | Network connectivity issues | Check internet connection | +| `Timeout` | Request timeout | Increase timeout or retry | +| `CircuitBreakerOpen` | Circuit breaker preventing requests | Wait for recovery period | +| `Serialization` | JSON serialization/deserialization error | Check data format | -- **Regular Expression Matching**: Offloading pattern matching or text extraction tasks to dedicated regular expression engines, which can often outperform LLM-based approaches in terms of speed and efficiency. -- **Structured Data Processing**: Leveraging specialized data processing engines or databases for tasks involving structured data, such as querying, filtering, or transforming tabular or relational data. -- **External APIs and Services**: Integrating with external APIs or cloud services for specific tasks, such as speech recognition, translation, or knowledge base lookup, leveraging the specialized capabilities and optimizations of these dedicated services. +### Error Handling Best Practices -Effective task offloading requires a thorough understanding of the strengths and limitations of both LLM agents and traditional components, as well as careful consideration of integration points, data flows, and performance trade-offs within the overall multi-agent architecture. +```rust +use swarms_client::{SwarmsClient, SwarmsError}; + +async fn handle_swarm_request(client: &SwarmsClient, task: &str) -> Result { + match client.swarm() + .completion() + .task(task) + .agent(|agent| agent.name("Worker").model("gpt-4o-mini")) + .send() + .await + { + Ok(response) => Ok(response.output.to_string()), + Err(SwarmsError::RateLimit { .. }) => { + // Implement exponential backoff + tokio::time::sleep(Duration::from_secs(5)).await; + Err(SwarmsError::RateLimit { + message: "Rate limited - should retry".to_string(), + status: Some(429), + request_id: None, + }) + }, + Err(e) => Err(e), + } +} +``` -### Caching and Indexing +## Performance Features -While LLMs excel at generating dynamic, context-aware outputs, they can be less efficient when dealing with static or frequently accessed information or knowledge. Caching and indexing strategies can help mitigate this limitation by minimizing redundant LLM processing and enabling faster retrieval of commonly accessed data. +### Connection Pooling +The client automatically manages HTTP connection pooling for optimal performance: -Techniques for leveraging caching and indexing in multi-agent LLM deployments include: +```rust +// Connections are automatically pooled and reused +let client = SwarmsClient::builder() + .unwrap() + .from_env()? + .max_concurrent_requests(100) // Allow up to 100 concurrent requests + .build()?; +``` -**Output Caching**: Caching the outputs or responses generated by LLM agents, allowing for rapid retrieval and reuse in cases where the same or similar input is encountered in the future. +### Caching +Intelligent caching reduces redundant API calls: -**Knowledge Base Indexing**: Indexing domain-specific knowledge bases, data repositories, or other static information sources using traditional search and information retrieval techniques. This allows LLM agents to efficiently query and incorporate relevant information into their outputs, without needing to process or generate this content from scratch. +```rust +let client = SwarmsClient::builder() + .unwrap() + .from_env()? + .enable_cache(true) + .cache_ttl(Duration::from_secs(300)) // 5-minute TTL + .build()?; -**Contextual Caching**: Caching not only outputs but also the contextual information and intermediate results generated during multi-agent workflows. This enables more efficient reuse and continuation of previous processing in scenarios where contexts are long-lived or recurring. +// GET requests are automatically cached +let models = client.models().list().await?; // First call hits API +let models_cached = client.models().list().await?; // Second call uses cache +``` -Implementing effective caching and indexing strategies requires careful consideration of data freshness, consistency, and invalidation mechanisms, as well as seamless integration with LLM agents and multi-agent workflows to ensure that cached or indexed data is appropriately leveraged and updated. +### Circuit Breaker +Automatic failure detection and recovery: -### Pre-computation and Lookup +```rust +let client = SwarmsClient::builder() + .unwrap() + .from_env()? + .build()?; -In certain scenarios, especially those involving constrained or well-defined inputs, pre-computing and lookup strategies can be leveraged to minimize or entirely avoid the need for real-time LLM processing. By generating and storing potential outputs or responses in advance, enterprises can significantly improve performance and reduce resource consumption. +// Circuit breaker automatically opens after 5 failures +// and recovers after 60 seconds +``` -Approaches for pre-computation and lookup include: +## Configuration Reference -**Output Pre-generation**: For inputs or scenarios with a limited set of potential outputs, pre-generating and storing all possible responses, allowing for rapid retrieval and delivery without the need for real-time LLM execution. +### ClientConfig Structure -**Retrieval-Based Responses**: Developing retrieval models or techniques that can identify and surface pre-computed or curated responses based on input characteristics, leveraging techniques such as nearest neighbor search, embedding-based retrieval, or example-based generation. +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `api_key` | `String` | `""` | Swarms API key | +| `base_url` | `Url` | `https://swarms-api-285321057562.us-east1.run.app/` | API base URL | +| `timeout` | `Duration` | `60s` | Request timeout | +| `max_retries` | `usize` | `3` | Maximum retry attempts | +| `retry_delay` | `Duration` | `1s` | Base retry delay | +| `max_concurrent_requests` | `usize` | `100` | Concurrent request limit | +| `circuit_breaker_threshold` | `usize` | `5` | Failure threshold for circuit breaker | +| `circuit_breaker_timeout` | `Duration` | `60s` | Circuit breaker recovery time | +| `enable_cache` | `bool` | `true` | Enable response caching | +| `cache_ttl` | `Duration` | `300s` | Cache time-to-live | -**Hybrid Approaches**: Combining pre-computed or retrieved responses with real-time LLM processing, allowing for the generation of dynamic, context-aware content while still leveraging pre-computed components to optimize performance and resource utilization. +## Environment Variables -Effective implementation of pre-computation and lookup strategies requires careful analysis of input patterns, output distributions, and potential performance gains, as well as robust mechanisms for managing and updating pre-computed data as application requirements or domain knowledge evolves. +| Variable | Description | Example | +|----------|-------------|---------| +| `SWARMS_API_KEY` | Your Swarms API key | `sk-xxx...` | +| `SWARMS_BASE_URL` | Custom API base URL (optional) | `https://api.custom.com/` | -# Conclusion ----------- +## Testing -As enterprises increasingly embrace the transformative potential of large language models, optimizing the performance, scalability, and cost-effectiveness of these deployments has become a critical imperative. Multi-agent architectures, which coordinate the collective capabilities of multiple specialized LLM agents, offer a powerful paradigm for addressing these challenges. +Run the test suite: -By implementing the seven principles outlined in this guide -- distributing token processing, optimizing agent communication, leveraging agent specialization, implementing dynamic scaling, employing selective execution, optimizing user experience, and leveraging hybrid approaches -- organizations can unlock the full potential of multi-agent LLM deployments. +```bash +cargo test +``` -However, realizing these benefits requires a strategic and holistic approach that accounts for the unique requirements, constraints, and objectives of each enterprise. From task-specific optimizations and domain adaptation to dynamic scaling and user experience considerations, maximizing the performance of multi-agent LLM systems demands a deep understanding of the underlying technologies, as well as the ability to navigate the inherent complexities of these sophisticated architectures. +Run specific tests: -To learn more about how Swarm Corporation can assist your organization in architecting, deploying, and optimizing high-performance multi-agent LLM solutions, we invite you to book a consultation with one of our agent specialists. Visit to schedule a 30-minute call and explore how our expertise and cutting-edge technologies can drive transformative outcomes for your business. +```bash +cargo test test_cache +cargo test test_circuit_breaker +``` -In the rapidly evolving landscape of artificial intelligence and natural language processing, staying ahead of the curve is essential. Partner with Swarm Corporation, and unlock the full potential of multi-agent LLM deployments, today. +## Contributing -[Book a call with us now:](https://calendly.com/swarm-corp/30min) +1. Fork the repository +2. Create a feature branch +3. Add tests for new functionality +4. Ensure all tests pass +5. Submit a pull request + +## License + +This project is licensed under the MIT License - see the LICENSE file for details. -------------------------------------------------- -# File: swarms_cloud/subscription_tiers.md +# File: swarms_cloud\subscription_tiers.md -# Swarms Cloud Subscription Tiers / Swarms 云订阅等级 +# Swarms Cloud Subscription Tiers -!!! abstract "Overview / 概述" +!!! abstract "Overview" Choose the perfect plan for your agent infrastructure needs. All plans include our core features with additional benefits as you scale up. - 为您的智能体基础设施需求选择完美方案。所有计划都包含我们的核心功能，随着您的扩展提供额外优势。 -## Pricing Plans / 定价方案 +## Pricing Plans -### Free Tier / 免费版 +### Free Tier -!!! example "Free / 免费" - **$0/year / 0美元/年** +!!! example "Free" + **$0/year** Perfect for getting started with AI development. - 非常适合开始AI开发。 - [Get Started / 开始使用](https://swarms.world/platform/account){ .md-button .md-button--primary } + [Get Started](https://swarms.world/platform/account){ .md-button .md-button--primary } - **What's Included: / 包含内容：** + **What's Included:** - - [x] Sign up Bonus! / 注册奖励！ + - [x] Sign up Bonus! - - [x] Basic Access / 基础访问权限 + - [x] Basic Access - - [x] Pay-Per-Use Pricing / 按使用量付费 + - [x] Pay-Per-Use Pricing - - [x] Community Support / 社区支持 + - [x] Community Support - - [x] Standard Processing Speed / 标准处理速度 + - [x] Standard Processing Speed -### Premium Tier / 高级版 +### Premium Tier -!!! success "Premium / 高级版" +!!! success "Premium" - **Monthly $100/month / 每月100美元** + **Monthly $100/month** - **Yearly $1,020/year / 每年1,020美元** (Save 15% on annual billing / 年付节省15%) + **Yearly $1,020/year** (Save 15% on annual billing) - [Subscribe Now / 立即订阅](https://swarms.world/platform/account){ .md-button .md-button--primary } + [Subscribe Now](https://swarms.world/platform/account){ .md-button .md-button--primary } - **Everything in Free, plus: / 包含免费版所有内容，外加：** + **Everything in Free, plus:** - - [x] Full Access to Explorer and Agents / 完全访问Explorer和智能体 + - [x] Full Access to Explorer and Agents - - [x] Access to Premium Multi-Modality Models / 访问高级多模态模型 + - [x] Access to Premium Multi-Modality Models - - [x] Priority Access to Swarms / 优先访问Swarms + - [x] Priority Access to Swarms - - [x] High-Performance Infrastructure / 高性能基础设施 + - [x] High-Performance Infrastructure - - [x] Exclusive Webinars and Tutorials / 独家网络研讨会和教程 + - [x] Exclusive Webinars and Tutorials - - [x] Priority Support / 优先支持 + - [x] Priority Support - - [x] Enhanced Security Features / 增强的安全功能 + - [x] Enhanced Security Features - - [x] Early Access to New Models and Features / 新模型和功能的早期访问 + - [x] Early Access to New Models and Features -### Enterprise Tier / 企业版 +### Enterprise Tier -!!! tip "Enterprise / 企业版" - **Contact for more Information / 联系获取更多信息** +!!! tip "Enterprise" + **Contact for more Information** - [Book a Call / 预约通话](https://cal.com/swarms){ .md-button .md-button--primary } + [Book a Call](https://cal.com/swarms){ .md-button .md-button--primary } - **Everything in Premium, plus: / 包含高级版所有内容，外加：** + **Everything in Premium, plus:** - - [x] High-Performance Infrastructure / 高性能基础设施 + - [x] High-Performance Infrastructure - - [x] Batch API / 批量API + - [x] Batch API - - [x] Early Access to New Swarms / 新Swarms的早期访问 + - [x] Early Access to New Swarms - - [x] Dedicated 24/7 Support / 专属24/7支持 + - [x] Dedicated 24/7 Support - - [x] Custom Solutions Engineering / 定制解决方案工程 + - [x] Custom Solutions Engineering - - [x] Advanced Security Features / 高级安全功能 + - [x] Advanced Security Features - - [x] Onsite Training and Onboarding / 现场培训和入职 + - [x] Onsite Training and Onboarding - - [x] Custom Model Training / 定制模型训练 + - [x] Custom Model Training - - [x] Priority Support / 优先支持 + - [x] Priority Support - - [x] Pay-Per-Use Pricing / 按使用量付费 + - [x] Pay-Per-Use Pricing - - [x] Enterprise Telemetry Platform / 企业遥测平台 + - [x] Enterprise Telemetry Platform - - [x] Regular Check-In Strategy Sessions / 定期战略会议 + - [x] Regular Check-In Strategy Sessions -## Feature Comparison / 功能对比 +## Feature Comparison -| Feature / 功能 | Free / 免费版 | Premium / 高级版 | Enterprise / 企业版 | +| Feature | Free | Premium | Enterprise | |---------|------|---------|------------| -| Sign up Bonus / 注册奖励 | ✅ | ✅ | ✅ | -| Basic Access / 基础访问权限 | ✅ | ✅ | ✅ | -| Pay-Per-Use Pricing / 按使用量付费 | ✅ | ✅ | ✅ | -| Community Support / 社区支持 | ✅ | ✅ | ✅ | -| Standard Processing Speed / 标准处理速度 | ✅ | ✅ | ✅ | -| Full Access to Explorer and Agents / 完全访问Explorer和智能体 | ❌ | ✅ | ✅ | -| Premium Multi-Modality Models / 高级多模态模型 | ❌ | ✅ | ✅ | -| Priority Access to Swarms / 优先访问Swarms | ❌ | ✅ | ✅ | -| High-Performance GPUs / 高性能GPU | ❌ | ✅ | ✅ | -| Exclusive Webinars and Tutorials / 独家网络研讨会和教程 | ❌ | ✅ | ✅ | -| Priority Support / 优先支持 | ❌ | ✅ | ✅ | -| Enhanced Security Features / 增强的安全功能 | ❌ | ✅ | ✅ | -| Early Access to New Models / 新模型的早期访问 | ❌ | ✅ | ✅ | -| Batch API / 批量API | ❌ | ❌ | ✅ | -| Dedicated 24/7 Support / 专属24/7支持 | ❌ | ❌ | ✅ | -| Custom Solutions Engineering / 定制解决方案工程 | ❌ | ❌ | ✅ | -| Onsite Training and Onboarding / 现场培训和入职 | ❌ | ❌ | ✅ | -| Custom Model Training / 定制模型训练 | ❌ | ❌ | ✅ | - -## Rate Limits / 速率限制 - -!!! info "Rate Limit Increases / 速率限制提升" - - **Premium / 高级版**: 100% increase in rate limits / 速率限制提升100% - - **Enterprise / 企业版**: Custom rate limits based on your needs (contact us for details) / 根据您的需求定制速率限制（详情请联系我们） - -## Getting Started / 开始使用 - -1. Choose your plan / 选择您的方案 -2. Create your account / 创建您的账户 -3. Start building with Swarms! / 开始使用Swarms构建！ - -!!! success "Need Help? / 需要帮助？" - - For general questions: [Contact Support](mailto:kye@swarms.world) / 一般问题：[联系支持](mailto:kye@swarms.world) - - For enterprise inquiries: [Book a Call](https://cal.com/swarms) / 企业咨询：[预约通话](https://cal.com/swarms) - - Upgrade Your Membership: [Upgrade Now](https://swarms.world/platform/account) / 升级会员：[立即升级](https://swarms.world/platform/account) +| Sign up Bonus | ✅ | ✅ | ✅ | +| Basic Access | ✅ | ✅ | ✅ | +| Pay-Per-Use Pricing | ✅ | ✅ | ✅ | +| Community Support | ✅ | ✅ | ✅ | +| Standard Processing Speed | ✅ | ✅ | ✅ | +| Full Access to Explorer and Agents | ❌ | ✅ | ✅ | +| Premium Multi-Modality Models | ❌ | ✅ | ✅ | +| Priority Access to Swarms | ❌ | ✅ | ✅ | +| High-Performance GPUs | ❌ | ✅ | ✅ | +| Exclusive Webinars and Tutorials | ❌ | ✅ | ✅ | +| Priority Support | ❌ | ✅ | ✅ | +| Enhanced Security Features | ❌ | ✅ | ✅ | +| Early Access to New Models | ❌ | ✅ | ✅ | +| Batch API | ❌ | ❌ | ✅ | +| Dedicated 24/7 Support | ❌ | ❌ | ✅ | +| Custom Solutions Engineering | ❌ | ❌ | ✅ | +| Onsite Training and Onboarding | ❌ | ❌ | ✅ | +| Custom Model Training | ❌ | ❌ | ✅ | +## Rate Limits --------------------------------------------------- - -# File: swarms_cloud/swarm_types.md +!!! info "Rate Limit Increases" + - **Premium**: 100% increase in rate limits + - **Enterprise**: Custom rate limits based on your needs (contact us for details) -### Available Swarms in The Swarms API +## Getting Started -| Swarm Type | Description (English) | Description (Chinese) | -|----------------------|-----------------------------------------------------------------------------|----------------------------------------------------------------------------| -| AgentRearrange | A swarm type focused on rearranging agents for optimal performance. | 一种专注于重新排列代理以实现最佳性能的群类型。 | -| MixtureOfAgents | Combines different types of agents to achieve a specific goal. | 结合不同类型的代理以实现特定目标。 | -| SpreadSheetSwarm | Utilizes spreadsheet-like structures for data management and operations. | 利用类似电子表格的结构进行数据管理和操作。 | -| SequentialWorkflow | Executes tasks in a sequential manner. | 以顺序方式执行任务。 | -| ConcurrentWorkflow | Allows tasks to be executed concurrently for efficiency. | 允许任务并发执行以提高效率。 | -| GroupChat | Facilitates communication among agents in a group chat format. | 以群聊格式促进代理之间的沟通。 | -| MultiAgentRouter | Routes tasks and information among multiple agents. | 在多个代理之间路由任务和信息。 | -| AutoSwarmBuilder | Automatically builds and configures swarms based on predefined criteria. | 根据预定义标准自动构建和配置群。 | -| HiearchicalSwarm | Organizes agents in a hierarchical structure for task delegation. | 以层次结构组织代理以进行任务委派。 | -| auto | Automatically selects the best swarm type based on the context. | 根据上下文自动选择最佳群类型。 | -| MajorityVoting | Uses majority voting among agents to make decisions. | 使用代理之间的多数投票来做出决策。 | -| MALT | A specialized swarm type for specific tasks (details needed). | 一种专门为特定任务设计的群类型（需要详细信息）。 | +1. Choose your plan +2. Create your account +3. Start building with Swarms! -### Documentation for Swarms +!!! success "Need Help?" + - For general questions: [Contact Support](mailto:kye@swarms.world) + - For enterprise inquiries: [Book a Call](https://cal.com/swarms) + - Upgrade Your Membership: [Upgrade Now](https://swarms.world/platform/account) -1. **AgentRearrange**: This swarm type is designed to rearrange agents to optimize their performance in a given task. It is useful in scenarios where agent positioning or order affects the outcome. - - 这种群类型旨在重新排列代理以优化其在给定任务中的性能。它在代理位置或顺序影响结果的情况下非常有用。 -2. **MixtureOfAgents**: This type combines various agents, each with unique capabilities, to work together towards a common goal. It leverages the strengths of different agents to enhance overall performance. - - 这种类型结合了各种代理，每个代理都有独特的能力，共同努力实现共同目标。它利用不同代理的优势来提高整体性能。 +-------------------------------------------------- -3. **SpreadSheetSwarm**: This swarm type uses spreadsheet-like structures to manage and operate on data. It is ideal for tasks that require organized data manipulation and analysis. - - 这种群类型使用类似电子表格的结构来管理和操作数据。它非常适合需要有组织的数据操作和分析的任务。 +# File: swarms_cloud\swarm_types.md -4. **SequentialWorkflow**: Tasks are executed one after another in this swarm type, ensuring that each step is completed before the next begins. It is suitable for processes that require strict order. - - 在这种群类型中，任务一个接一个地执行，确保每个步骤在下一个步骤开始之前完成。它适用于需要严格顺序的流程。 +# Multi-Agent Architectures -5. **ConcurrentWorkflow**: This type allows multiple tasks to be executed simultaneously, improving efficiency and reducing time for completion. It is best for independent tasks that do not rely on each other. - - 这种类型允许多个任务同时执行，提高效率并减少完成时间。它最适合不相互依赖的独立任务。 +Each multi-agent architecture type is designed for specific use cases and can be combined to create powerful multi-agent systems. Here's a comprehensive overview of each available swarm: -6. **GroupChat**: Facilitates communication among agents in a group chat format, enabling real-time collaboration and decision-making. - - 以群聊格式促进代理之间的沟通，实现实时协作和决策。 +| Swarm Type | Description | Learn More | +|---------------------|------------------------------------------------------------------------------|------------| +| AgentRearrange | Dynamically reorganizes agents to optimize task performance and efficiency. Optimizes agent performance by dynamically adjusting their roles and positions within the workflow. This architecture is particularly useful when the effectiveness of agents depends on their sequence or arrangement. | [Learn More](/swarms/structs/agent_rearrange) | +| MixtureOfAgents | Creates diverse teams of specialized agents, each bringing unique capabilities to solve complex problems. Each agent contributes unique skills to achieve the overall goal, making it excel at tasks requiring multiple types of expertise or processing. | [Learn More](/swarms/structs/moa) | +| SpreadSheetSwarm | Provides a structured approach to data management and operations, making it ideal for tasks involving data analysis, transformation, and systematic processing in a spreadsheet-like structure. | [Learn More](/swarms/structs/spreadsheet_swarm) | +| SequentialWorkflow | Ensures strict process control by executing tasks in a predefined order. Perfect for workflows where each step depends on the completion of previous steps. | [Learn More](/swarms/structs/sequential_workflow) | +| ConcurrentWorkflow | Maximizes efficiency by running independent tasks in parallel, significantly reducing overall processing time for complex operations. Ideal for independent tasks that can be processed simultaneously. | [Learn More](/swarms/structs/concurrentworkflow) | +| GroupChat | Enables dynamic collaboration between agents through a chat-based interface, facilitating real-time information sharing and decision-making. | [Learn More](/swarms/structs/group_chat) | +| MultiAgentRouter | Acts as an intelligent task dispatcher, ensuring optimal distribution of work across available agents based on their capabilities and current workload. | [Learn More](/swarms/structs/multi_agent_router) | +| AutoSwarmBuilder | Simplifies swarm creation by automatically configuring agent architectures based on task requirements and performance metrics. | [Learn More](/swarms/structs/auto_swarm_builder) | +| HiearchicalSwarm | Implements a structured approach to task management, with clear lines of authority and delegation across multiple agent levels. | [Learn More](/swarms/structs/multi_swarm_orchestration) | +| auto | Provides intelligent swarm selection based on context, automatically choosing the most effective architecture for given tasks. | [Learn More](/swarms/concept/how_to_choose_swarms) | +| MajorityVoting | Implements robust decision-making through consensus, particularly useful for tasks requiring collective intelligence or verification. | [Learn More](/swarms/structs/majorityvoting) | +| MALT | Specialized framework for language-based tasks, optimizing agent collaboration for complex language processing operations. | [Learn More](/swarms/structs/malt) | -7. **MultiAgentRouter**: This swarm type routes tasks and information among multiple agents, ensuring that each agent receives the necessary data to perform its function. - - 这种群类型在多个代理之间路由任务和信息，确保每个代理接收到执行其功能所需的数据。 +# Learn More -8. **AutoSwarmBuilder**: Automatically builds and configures swarms based on predefined criteria, reducing the need for manual setup and configuration. - - 根据预定义标准自动构建和配置群，减少手动设置和配置的需要。 +To learn more about Swarms architecture and how different swarm types work together, visit our comprehensive guides: -9. **HiearchicalSwarm**: Organizes agents in a hierarchical structure, allowing for efficient task delegation and management. - - 以层次结构组织代理，允许高效的任务委派和管理。 +- [Introduction to Multi-Agent Architectures](/swarms/concept/swarm_architectures) -10. **auto**: Automatically selects the most appropriate swarm type based on the context and requirements of the task. - - 根据任务的上下文和要求自动选择最合适的群类型。 +- [How to Choose the Right Multi-Agent Architecture](/swarms/concept/how_to_choose_swarms) -11. **MajorityVoting**: Uses a majority voting mechanism among agents to make decisions, ensuring that the most popular choice is selected. - - 使用代理之间的多数投票机制来做出决策，确保选择最受欢迎的选项。 +- [Framework Architecture Overview](/swarms/concept/framework_architecture) -12. **MALT**: A specialized swarm type designed for specific tasks. Further details are needed to fully document this type. - - 一种专门为特定任务设计的群类型。需要进一步的详细信息来完整记录这种类型。 +- [Building Custom Swarms](/swarms/structs/custom_swarm) -------------------------------------------------- -# File: swarms_cloud/swarms_api.md +# File: swarms_cloud\swarms_api.md # Swarms API Documentation -*Enterprise-grade Agent Swarm Management API* +*Enterprise-Grade Agent Swarm Management API* + +**Base URL**: `https://api.swarms.world` or `https://swarms-api-285321057562.us-east1.run.app` -**Base URL**: `https://api.swarms.world` **API Key Management**: [https://swarms.world/platform/api-keys](https://swarms.world/platform/api-keys) ## Overview @@ -46888,11 +56246,15 @@ The Swarms API provides a robust, scalable infrastructure for deploying and mana Key capabilities include: - **Intelligent Swarm Management**: Create and execute swarms of specialized AI agents that collaborate to solve complex tasks + - **Automatic Agent Generation**: Dynamically create optimized agents based on task requirements + - **Multiple Swarm Architectures**: Choose from various swarm patterns to match your specific workflow needs -- **Scheduled Execution**: Set up automated, scheduled swarm executions + - **Comprehensive Logging**: Track and analyze all API interactions + - **Cost Management**: Predictable, transparent pricing with optimized resource utilization + - **Enterprise Security**: Full API key authentication and management Swarms API is designed for production use cases requiring sophisticated AI orchestration, with applications in finance, healthcare, legal, research, and other domains where complex reasoning and multi-agent collaboration are needed. @@ -46916,12 +56278,11 @@ API keys can be obtained and managed at [https://swarms.world/platform/api-keys] | `/health` | GET | Simple health check endpoint | | `/v1/swarm/completions` | POST | Run a swarm with specified configuration | | `/v1/swarm/batch/completions` | POST | Run multiple swarms in batch mode | -| `/v1/swarm/schedule` | POST | Schedule a swarm to run at a specific time | -| `/v1/swarm/schedule` | GET | Get all scheduled swarm jobs | -| `/v1/swarm/schedule/{job_id}` | DELETE | Cancel a scheduled swarm job | | `/v1/swarm/logs` | GET | Retrieve API request logs | | `/v1/swarms/available` | GET | Get all available swarms as a list of strings | | `/v1/models/available` | GET | Get all available models as a list of strings | +| `/v1/agent/completions` | POST | Run a single agent with specified configuration | +| `/v1/agent/batch/completions` | POST | Run a batch of individual agent completions| @@ -46963,7 +56324,7 @@ The `SwarmSpec` model defines the configuration of a swarm. | img | string | Optional image URL for the swarm | No | | return_history | boolean | Whether to return execution history | No | | rules | string | Guidelines for swarm behavior | No | -| schedule | ScheduleSpec | Scheduling information | No | +| service_tier | string | Service tier for processing ("standard" or "flex") | No | ### AgentSpec @@ -46983,16 +56344,6 @@ The `AgentSpec` model defines the configuration of an individual agent. *Required if agents are manually specified; not required if using auto-generated agents -### ScheduleSpec - -The `ScheduleSpec` model defines when a swarm should be executed. - -| Field | Type | Description | Required | -|-------|------|-------------|----------| -| scheduled_time | datetime | Time when the swarm should run | Yes | -| timezone | string | Timezone for the scheduled time | No (defaults to "UTC") | - - ### Endpoint Details @@ -47004,11 +56355,58 @@ Check if the API service is available and functioning correctly. **Method**: GET **Rate Limit**: 100 requests per 60 seconds -**Example Request**: -```bash -curl -X GET "https://api.swarms.world/health" \ - -H "x-api-key: your_api_key_here" -``` +=== "Shell (curl)" + ```bash + curl -X GET "https://api.swarms.world/health" \ + -H "x-api-key: your_api_key_here" + ``` + +=== "Python (requests)" + ```python + import requests + + API_BASE_URL = "https://api.swarms.world" + API_KEY = "your_api_key_here" + + headers = { + "x-api-key": API_KEY + } + + response = requests.get(f"{API_BASE_URL}/health", headers=headers) + + if response.status_code == 200: + print("API is healthy:", response.json()) + else: + print(f"Error: {response.status_code}") + ``` + +=== "TypeScript (fetch)" + ```typescript + const API_BASE_URL = "https://api.swarms.world"; + const API_KEY = "your_api_key_here"; + + async function checkHealth(): Promise { + try { + const response = await fetch(`${API_BASE_URL}/health`, { + method: 'GET', + headers: { + 'x-api-key': API_KEY + } + }); + + if (response.ok) { + const data = await response.json(); + console.log("API is healthy:", data); + } else { + console.error(`Error: ${response.status}`); + } + } catch (error) { + console.error("Request failed:", error); + } + } + + checkHealth(); + ``` **Example Response**: ```json @@ -47019,69 +56417,213 @@ curl -X GET "https://api.swarms.world/health" \ #### Run Swarm -Run a swarm with the specified configuration to complete a task. +Run a swarm with the specified configuration to complete a task. + +**Endpoint**: `/v1/swarm/completions` +**Method**: POST +**Rate Limit**: 100 requests per 60 seconds + +**Request Parameters**: + +| Field | Type | Description | Required | +|-------|------|-------------|----------| +| name | string | Identifier for the swarm | No | +| description | string | Description of the swarm's purpose | No | +| agents | Array | List of agent specifications | No | +| max_loops | integer | Maximum number of execution loops | No | +| swarm_type | SwarmType | Architecture of the swarm | No | +| rearrange_flow | string | Instructions for rearranging task flow | No | +| task | string | The main task for the swarm to accomplish | Yes | +| img | string | Optional image URL for the swarm | No | +| return_history | boolean | Whether to return execution history | No | +| rules | string | Guidelines for swarm behavior | No | + +=== "Shell (curl)" + ```bash + curl -X POST "https://api.swarms.world/v1/swarm/completions" \ + -H "x-api-key: $SWARMS_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Financial Analysis Swarm", + "description": "Market analysis swarm", + "agents": [ + { + "agent_name": "Market Analyst", + "description": "Analyzes market trends", + "system_prompt": "You are a financial analyst expert.", + "model_name": "openai/gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": false + }, + { + "agent_name": "Economic Forecaster", + "description": "Predicts economic trends", + "system_prompt": "You are an expert in economic forecasting.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": false + } + ], + "max_loops": 1, + "swarm_type": "ConcurrentWorkflow", + "task": "What are the best etfs and index funds for ai and tech?", + "output_type": "dict" + }' + ``` + +=== "Python (requests)" + ```python + import requests + import json -**Endpoint**: `/v1/swarm/completions` -**Method**: POST -**Rate Limit**: 100 requests per 60 seconds + API_BASE_URL = "https://api.swarms.world" + API_KEY = "your_api_key_here" + + headers = { + "x-api-key": API_KEY, + "Content-Type": "application/json" + } + + swarm_config = { + "name": "Financial Analysis Swarm", + "description": "Market analysis swarm", + "agents": [ + { + "agent_name": "Market Analyst", + "description": "Analyzes market trends", + "system_prompt": "You are a financial analyst expert.", + "model_name": "openai/gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": False + }, + { + "agent_name": "Economic Forecaster", + "description": "Predicts economic trends", + "system_prompt": "You are an expert in economic forecasting.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": False + } + ], + "max_loops": 1, + "swarm_type": "ConcurrentWorkflow", + "task": "What are the best etfs and index funds for ai and tech?", + "output_type": "dict" + } + + response = requests.post( + f"{API_BASE_URL}/v1/swarm/completions", + headers=headers, + json=swarm_config + ) + + if response.status_code == 200: + result = response.json() + print("Swarm completed successfully!") + print(f"Cost: ${result['metadata']['billing_info']['total_cost']}") + print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds") + else: + print(f"Error: {response.status_code} - {response.text}") + ``` -**Request Parameters**: +=== "TypeScript (fetch)" + ```typescript + interface AgentSpec { + agent_name: string; + description: string; + system_prompt: string; + model_name: string; + role: string; + max_loops: number; + max_tokens: number; + temperature: number; + auto_generate_prompt: boolean; + } -| Field | Type | Description | Required | -|-------|------|-------------|----------| -| name | string | Identifier for the swarm | No | -| description | string | Description of the swarm's purpose | No | -| agents | Array | List of agent specifications | No | -| max_loops | integer | Maximum number of execution loops | No | -| swarm_type | SwarmType | Architecture of the swarm | No | -| rearrange_flow | string | Instructions for rearranging task flow | No | -| task | string | The main task for the swarm to accomplish | Yes | -| img | string | Optional image URL for the swarm | No | -| return_history | boolean | Whether to return execution history | No | -| rules | string | Guidelines for swarm behavior | No | -| schedule | ScheduleSpec | Scheduling information | No | + interface SwarmConfig { + name: string; + description: string; + agents: AgentSpec[]; + max_loops: number; + swarm_type: string; + task: string; + output_type: string; + } -**Example Request**: -```bash + const API_BASE_URL = "https://api.swarms.world"; + const API_KEY = "your_api_key_here"; -# Run single swarm -curl -X POST "https://api.swarms.world/v1/swarm/completions" \ - -H "x-api-key: $SWARMS_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Financial Analysis Swarm", - "description": "Market analysis swarm", - "agents": [ - { - "agent_name": "Market Analyst", - "description": "Analyzes market trends", - "system_prompt": "You are a financial analyst expert.", - "model_name": "openai/gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 8192, - "temperature": 0.5, - "auto_generate_prompt": false - }, - { - "agent_name": "Economic Forecaster", - "description": "Predicts economic trends", - "system_prompt": "You are an expert in economic forecasting.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 8192, - "temperature": 0.5, - "auto_generate_prompt": false - } - ], - "max_loops": 1, - "swarm_type": "ConcurrentWorkflow", - "task": "What are the best etfs and index funds for ai and tech?", - "output_type": "dict" - }' + async function runSwarm(): Promise { + const swarmConfig: SwarmConfig = { + name: "Financial Analysis Swarm", + description: "Market analysis swarm", + agents: [ + { + agent_name: "Market Analyst", + description: "Analyzes market trends", + system_prompt: "You are a financial analyst expert.", + model_name: "openai/gpt-4o", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.5, + auto_generate_prompt: false + }, + { + agent_name: "Economic Forecaster", + description: "Predicts economic trends", + system_prompt: "You are an expert in economic forecasting.", + model_name: "gpt-4o", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.5, + auto_generate_prompt: false + } + ], + max_loops: 1, + swarm_type: "ConcurrentWorkflow", + task: "What are the best etfs and index funds for ai and tech?", + output_type: "dict" + }; + + try { + const response = await fetch(`${API_BASE_URL}/v1/swarm/completions`, { + method: 'POST', + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + }, + body: JSON.stringify(swarmConfig) + }); + + if (response.ok) { + const result = await response.json(); + console.log("Swarm completed successfully!"); + console.log(`Cost: $${result.metadata.billing_info.total_cost}`); + console.log(`Execution time: ${result.metadata.execution_time_seconds} seconds`); + } else { + console.error(`Error: ${response.status} - ${await response.text()}`); + } + } catch (error) { + console.error("Request failed:", error); + } + } -``` + runSwarm(); + ``` **Example Response**: ```json @@ -47137,65 +56679,249 @@ Run multiple swarms as a batch operation. |-------|------|-------------|----------| | swarms | Array | List of swarm specifications | Yes | -**Example Request**: -```bash -# Batch swarm completions -curl -X POST "https://api.swarms.world/v1/swarm/batch/completions" \ - -H "x-api-key: $SWARMS_API_KEY" \ - -H "Content-Type: application/json" \ - -d '[ - { - "name": "Batch Swarm 1", - "description": "First swarm in the batch", - "agents": [ +=== "Shell (curl)" + ```bash + curl -X POST "https://api.swarms.world/v1/swarm/batch/completions" \ + -H "x-api-key: $SWARMS_API_KEY" \ + -H "Content-Type: application/json" \ + -d '[ { - "agent_name": "Research Agent", - "description": "Conducts research", - "system_prompt": "You are a research assistant.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 + "name": "Batch Swarm 1", + "description": "First swarm in the batch", + "agents": [ + { + "agent_name": "Research Agent", + "description": "Conducts research", + "system_prompt": "You are a research assistant.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1 + }, + { + "agent_name": "Analysis Agent", + "description": "Analyzes data", + "system_prompt": "You are a data analyst.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1 + } + ], + "max_loops": 1, + "swarm_type": "SequentialWorkflow", + "task": "Research AI advancements." }, { - "agent_name": "Analysis Agent", - "description": "Analyzes data", - "system_prompt": "You are a data analyst.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 + "name": "Batch Swarm 2", + "description": "Second swarm in the batch", + "agents": [ + { + "agent_name": "Writing Agent", + "description": "Writes content", + "system_prompt": "You are a content writer.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1 + }, + { + "agent_name": "Editing Agent", + "description": "Edits content", + "system_prompt": "You are an editor.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1 + } + ], + "max_loops": 1, + "swarm_type": "SequentialWorkflow", + "task": "Write a summary of AI research." } - ], - "max_loops": 1, - "swarm_type": "SequentialWorkflow", - "task": "Research AI advancements." - }, - { - "name": "Batch Swarm 2", - "description": "Second swarm in the batch", - "agents": [ + ]' + ``` + +=== "Python (requests)" + ```python + import requests + import json + + API_BASE_URL = "https://api.swarms.world" + API_KEY = "your_api_key_here" + + headers = { + "x-api-key": API_KEY, + "Content-Type": "application/json" + } + + batch_swarms = [ { - "agent_name": "Writing Agent", - "description": "Writes content", - "system_prompt": "You are a content writer.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 + "name": "Batch Swarm 1", + "description": "First swarm in the batch", + "agents": [ + { + "agent_name": "Research Agent", + "description": "Conducts research", + "system_prompt": "You are a research assistant.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1 + }, + { + "agent_name": "Analysis Agent", + "description": "Analyzes data", + "system_prompt": "You are a data analyst.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1 + } + ], + "max_loops": 1, + "swarm_type": "SequentialWorkflow", + "task": "Research AI advancements." }, { - "agent_name": "Editing Agent", - "description": "Edits content", - "system_prompt": "You are an editor.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 + "name": "Batch Swarm 2", + "description": "Second swarm in the batch", + "agents": [ + { + "agent_name": "Writing Agent", + "description": "Writes content", + "system_prompt": "You are a content writer.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1 + }, + { + "agent_name": "Editing Agent", + "description": "Edits content", + "system_prompt": "You are an editor.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1 + } + ], + "max_loops": 1, + "swarm_type": "SequentialWorkflow", + "task": "Write a summary of AI research." } - ], - "max_loops": 1, - "swarm_type": "SequentialWorkflow", - "task": "Write a summary of AI research." + ] + + response = requests.post( + f"{API_BASE_URL}/v1/swarm/batch/completions", + headers=headers, + json=batch_swarms + ) + + if response.status_code == 200: + results = response.json() + print(f"Batch completed with {len(results)} swarms") + for i, result in enumerate(results): + print(f"Swarm {i+1}: {result['swarm_name']} - {result['status']}") + else: + print(f"Error: {response.status_code} - {response.text}") + ``` + +=== "TypeScript (fetch)" + ```typescript + interface AgentSpec { + agent_name: string; + description: string; + system_prompt: string; + model_name: string; + role: string; + max_loops: number; } - ]' -``` + + interface SwarmSpec { + name: string; + description: string; + agents: AgentSpec[]; + max_loops: number; + swarm_type: string; + task: string; + } + + const API_BASE_URL = "https://api.swarms.world"; + const API_KEY = "your_api_key_here"; + + async function runBatchSwarms(): Promise { + const batchSwarms: SwarmSpec[] = [ + { + name: "Batch Swarm 1", + description: "First swarm in the batch", + agents: [ + { + agent_name: "Research Agent", + description: "Conducts research", + system_prompt: "You are a research assistant.", + model_name: "gpt-4o", + role: "worker", + max_loops: 1 + }, + { + agent_name: "Analysis Agent", + description: "Analyzes data", + system_prompt: "You are a data analyst.", + model_name: "gpt-4o", + role: "worker", + max_loops: 1 + } + ], + max_loops: 1, + swarm_type: "SequentialWorkflow", + task: "Research AI advancements." + }, + { + name: "Batch Swarm 2", + description: "Second swarm in the batch", + agents: [ + { + agent_name: "Writing Agent", + description: "Writes content", + system_prompt: "You are a content writer.", + model_name: "gpt-4o", + role: "worker", + max_loops: 1 + }, + { + agent_name: "Editing Agent", + description: "Edits content", + system_prompt: "You are an editor.", + model_name: "gpt-4o", + role: "worker", + max_loops: 1 + } + ], + max_loops: 1, + swarm_type: "SequentialWorkflow", + task: "Write a summary of AI research." + } + ]; + + try { + const response = await fetch(`${API_BASE_URL}/v1/swarm/batch/completions`, { + method: 'POST', + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + }, + body: JSON.stringify(batchSwarms) + }); + + if (response.ok) { + const results = await response.json(); + console.log(`Batch completed with ${results.length} swarms`); + results.forEach((result: any, index: number) => { + console.log(`Swarm ${index + 1}: ${result.swarm_name} - ${result.status}`); + }); + } else { + console.error(`Error: ${response.status} - ${await response.text()}`); + } + } catch (error) { + console.error("Request failed:", error); + } + } + + runBatchSwarms(); + ``` **Example Response**: ```json @@ -47217,11 +56943,13 @@ curl -X POST "https://api.swarms.world/v1/swarm/batch/completions" \ ] ``` -#### Schedule Swarm +## Individual Agent Endpoints + +### Run Single Agent -Schedule a swarm to run at a specific time. +Run a single agent with the specified configuration. -**Endpoint**: `/v1/swarm/schedule` +**Endpoint**: `/v1/agent/completions` **Method**: POST **Rate Limit**: 100 requests per 60 seconds @@ -47229,569 +56957,444 @@ Schedule a swarm to run at a specific time. | Field | Type | Description | Required | |-------|------|-------------|----------| -| name | string | Identifier for the swarm | No | -| description | string | Description of the swarm's purpose | No | -| agents | Array | List of agent specifications | No | -| max_loops | integer | Maximum number of execution loops | No | -| swarm_type | SwarmType | Architecture of the swarm | No | -| task | string | The main task for the swarm to accomplish | Yes | -| schedule | ScheduleSpec | Scheduling information | Yes | - -**Example Request**: -```bash -curl -X POST "https://api.swarms.world/v1/swarm/schedule" \ - -H "x-api-key: your_api_key_here" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "daily-market-analysis", - "description": "Daily analysis of market conditions", - "task": "Analyze today's market movements and prepare a summary report", - "schedule": { - "scheduled_time": "2025-03-05T17:00:00Z", - "timezone": "UTC" - } - }' -``` - -**Example Response**: -```json -{ - "status": "success", - "message": "Swarm scheduled successfully", - "job_id": "swarm_daily-market-analysis_1709563245", - "scheduled_time": "2025-03-05T17:00:00Z", - "timezone": "UTC" -} -``` +| agent_config | AgentSpec | Configuration for the agent | Yes | +| task | string | The task to be completed by the agent | Yes | -#### Get Scheduled Jobs - -Retrieve all scheduled swarm jobs. - -**Endpoint**: `/v1/swarm/schedule` -**Method**: GET -**Rate Limit**: 100 requests per 60 seconds +=== "Shell (curl)" + ```bash + curl -X POST "https://api.swarms.world/v1/agent/completions" \ + -H "x-api-key: your_api_key_here" \ + -H "Content-Type: application/json" \ + -d '{ + "agent_config": { + "agent_name": "Research Assistant", + "description": "Helps with research tasks", + "system_prompt": "You are a research assistant expert.", + "model_name": "gpt-4o", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5 + }, + "task": "Research the latest developments in quantum computing." + }' + ``` -**Example Request**: -```bash -curl -X GET "https://api.swarms.world/v1/swarm/schedule" \ - -H "x-api-key: your_api_key_here" -``` +=== "Python (requests)" + ```python + import requests + import json -**Example Response**: -```json -{ - "status": "success", - "scheduled_jobs": [ - { - "job_id": "swarm_daily-market-analysis_1709563245", - "swarm_name": "daily-market-analysis", - "scheduled_time": "2025-03-05T17:00:00Z", - "timezone": "UTC" - }, - { - "job_id": "swarm_weekly-report_1709563348", - "swarm_name": "weekly-report", - "scheduled_time": "2025-03-09T12:00:00Z", - "timezone": "UTC" + API_BASE_URL = "https://api.swarms.world" + API_KEY = "your_api_key_here" + + headers = { + "x-api-key": API_KEY, + "Content-Type": "application/json" } - ] -} -``` - -#### Cancel Scheduled Job - -Cancel a previously scheduled swarm job. + + agent_request = { + "agent_config": { + "agent_name": "Research Assistant", + "description": "Helps with research tasks", + "system_prompt": "You are a research assistant expert.", + "model_name": "gpt-4o", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5 + }, + "task": "Research the latest developments in quantum computing." + } + + response = requests.post( + f"{API_BASE_URL}/v1/agent/completions", + headers=headers, + json=agent_request + ) + + if response.status_code == 200: + result = response.json() + print(f"Agent {result['name']} completed successfully!") + print(f"Usage: {result['usage']['total_tokens']} tokens") + print(f"Output: {result['outputs']}") + else: + print(f"Error: {response.status_code} - {response.text}") + ``` -**Endpoint**: `/v1/swarm/schedule/{job_id}` -**Method**: DELETE -**Rate Limit**: 100 requests per 60 seconds +=== "TypeScript (fetch)" + ```typescript + interface AgentConfig { + agent_name: string; + description: string; + system_prompt: string; + model_name: string; + max_loops: number; + max_tokens: number; + temperature: number; + } -**Path Parameters**: + interface AgentRequest { + agent_config: AgentConfig; + task: string; + } -| Parameter | Description | -|-----------|-------------| -| job_id | ID of the scheduled job to cancel | + const API_BASE_URL = "https://api.swarms.world"; + const API_KEY = "your_api_key_here"; + + async function runSingleAgent(): Promise { + const agentRequest: AgentRequest = { + agent_config: { + agent_name: "Research Assistant", + description: "Helps with research tasks", + system_prompt: "You are a research assistant expert.", + model_name: "gpt-4o", + max_loops: 1, + max_tokens: 8192, + temperature: 0.5 + }, + task: "Research the latest developments in quantum computing." + }; + + try { + const response = await fetch(`${API_BASE_URL}/v1/agent/completions`, { + method: 'POST', + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + }, + body: JSON.stringify(agentRequest) + }); + + if (response.ok) { + const result = await response.json(); + console.log(`Agent ${result.name} completed successfully!`); + console.log(`Usage: ${result.usage.total_tokens} tokens`); + console.log(`Output:`, result.outputs); + } else { + console.error(`Error: ${response.status} - ${await response.text()}`); + } + } catch (error) { + console.error("Request failed:", error); + } + } -**Example Request**: -```bash -curl -X DELETE "https://api.swarms.world/v1/swarm/schedule/swarm_daily-market-analysis_1709563245" \ - -H "x-api-key: your_api_key_here" -``` + runSingleAgent(); + ``` **Example Response**: ```json { - "status": "success", - "message": "Scheduled job cancelled successfully", - "job_id": "swarm_daily-market-analysis_1709563245" + "id": "agent-abc123", + "success": true, + "name": "Research Assistant", + "description": "Helps with research tasks", + "temperature": 0.5, + "outputs": {}, + "usage": { + "input_tokens": 150, + "output_tokens": 450, + "total_tokens": 600 + }, + "timestamp": "2024-03-05T12:34:56.789Z" } ``` +### AgentCompletion Model -### Get Models - -#### Get Available Models - -Get all available models as a list of strings. - -**Endpoint**: `/v1/models/available` -**Method**: GET +The `AgentCompletion` model defines the configuration for running a single agent task. -**Example Request**: -```bash -curl -X GET "https://api.swarms.world/v1/models/available" \ - -H "x-api-key: your_api_key_here" -``` +| Field | Type | Description | Required | +|-------|------|-------------|----------| +| `agent_config` | AgentSpec | The configuration of the agent to be completed | Yes | +| `task` | string | The task to be completed by the agent | Yes | +| `history` | Dict[str, Any] | The history of the agent's previous tasks and responses | No | ------- +### AgentSpec Model +The `AgentSpec` model defines the configuration for an individual agent. -### Get Swarms Available +| Field | Type | Default | Description | Required | +|-------|------|---------|-------------|----------| +| `agent_name` | string | None | The unique name assigned to the agent | Yes | +| `description` | string | None | Detailed explanation of the agent's purpose | No | +| `system_prompt` | string | None | Initial instruction provided to the agent | No | +| `model_name` | string | "gpt-4o-mini" | Name of the AI model to use | No | +| `auto_generate_prompt` | boolean | false | Whether to auto-generate prompts | No | +| `max_tokens` | integer | 8192 | Maximum tokens in response | No | +| `temperature` | float | 0.5 | Controls randomness (0-1) | No | +| `role` | string | "worker" | Role of the agent | No | +| `max_loops` | integer | 1 | Maximum iterations | No | +| `tools_list_dictionary` | List[Dict] | None | Available tools for the agent | No | +| `mcp_url` | string | None | URL for Model Control Protocol | No | -Get all available swarms as a list of strings. -**Endpoint**: `/v1/swarms/available` -**Method**: GET +Execute a task using a single agent with specified configuration. -**Example Request**: -```bash -curl -X GET "https://api.swarms.world/v1/swarms/available" \ - -H "x-api-key: your_api_key_here" -``` +**Endpoint**: `/v1/agent/completions` +**Method**: POST +**Rate Limit**: 100 requests per 60 seconds -**Example Response**: +**Request Body**: ```json { - "status": "success", - "swarms": ["financial-analysis-swarm", "market-sentiment-swarm"] + "agent_config": { + "agent_name": "Research Assistant", + "description": "Specialized in research and analysis", + "system_prompt": "You are an expert research assistant.", + "model_name": "gpt-4o", + "auto_generate_prompt": false, + "max_tokens": 8192, + "temperature": 0.5, + "role": "worker", + "max_loops": 1, + "tools_list_dictionary": [ + { + "name": "search", + "description": "Search the web for information", + "parameters": { + "query": "string" + } + } + ], + "mcp_url": "https://example-mcp.com" + }, + "task": "Research the latest developments in quantum computing and summarize key findings", + "history": { + "previous_research": "Earlier findings on quantum computing basics...", + "user_preferences": "Focus on practical applications..." + } } ``` -------- - - -#### Get API Logs - -Retrieve logs of API requests made with your API key. - -**Endpoint**: `/v1/swarm/logs` -**Method**: GET -**Rate Limit**: 100 requests per 60 seconds - -**Example Request**: -```bash -curl -X GET "https://api.swarms.world/v1/swarm/logs" \ - -H "x-api-key: your_api_key_here" -``` - -**Example Response**: +**Response**: ```json { - "status": "success", - "count": 25, - "logs": [ - { - "id": "log_id_12345", - "api_key": "api_key_redacted", - "data": { - "action": "run_swarm", - "swarm_name": "financial-analysis-swarm", - "task": "Analyze quarterly financials...", - "timestamp": "2025-03-04T14:22:45Z" - } - }, - ... - ] + "id": "agent-abc123xyz", + "success": true, + "name": "Research Assistant", + "description": "Specialized in research and analysis", + "temperature": 0.5, + "outputs": { + "research_summary": "...", + "key_findings": [ + "..." + ] + }, + "usage": { + "input_tokens": 450, + "output_tokens": 850, + "total_tokens": 1300, + "mcp_url": 0.1 + }, + "timestamp": "2024-03-05T12:34:56.789Z" } ``` -## Production Examples - -### Python Examples +#### Run Batch Agents -#### Financial Risk Assessment (Python) +Execute multiple agent tasks in parallel. -This example demonstrates creating a swarm for comprehensive financial risk assessment. +**Endpoint**: `/v1/agent/batch/completions` +**Method**: POST +**Rate Limit**: 100 requests per 60 seconds +**Maximum Batch Size**: 10 requests +**Input** A list of `AgentCompeletion` inputs -```python -import requests -import json -from datetime import datetime, timedelta +=== "Shell (curl)" + ```bash + curl -X POST "https://api.swarms.world/v1/agent/batch/completions" \ + -H "x-api-key: your_api_key_here" \ + -H "Content-Type: application/json" \ + -d '[ + { + "agent_config": { + "agent_name": "Market Analyst", + "description": "Expert in market analysis", + "system_prompt": "You are a financial market analyst.", + "model_name": "gpt-4o", + "temperature": 0.3 + }, + "task": "Analyze the current market trends in AI technology sector" + }, + { + "agent_config": { + "agent_name": "Technical Writer", + "description": "Specialized in technical documentation", + "system_prompt": "You are a technical documentation expert.", + "model_name": "gpt-4o", + "temperature": 0.7 + }, + "task": "Create a technical guide for implementing OAuth2 authentication" + } + ]' + ``` -# API Configuration -API_BASE_URL = "https://api.swarms.world" -API_KEY = "your_api_key_here" -HEADERS = { - "x-api-key": API_KEY, - "Content-Type": "application/json" -} +=== "Python (requests)" + ```python + import requests + import json -def financial_risk_assessment(company_data, market_conditions, risk_tolerance): - """ - Creates and runs a swarm to perform comprehensive financial risk assessment. - - Args: - company_data (str): Description or data about the company - market_conditions (str): Current market conditions - risk_tolerance (str): Risk tolerance level (e.g., "conservative", "moderate", "aggressive") - - Returns: - dict: Risk assessment results - """ - # Prepare the task description with all relevant information - task = f""" - Perform a comprehensive financial risk assessment with the following data: - - COMPANY DATA: - {company_data} - - MARKET CONDITIONS: - {market_conditions} + API_BASE_URL = "https://api.swarms.world" + API_KEY = "your_api_key_here" - RISK TOLERANCE: - {risk_tolerance} - - Analyze all potential risk factors including market risks, credit risks, - operational risks, and regulatory compliance risks. Quantify each risk factor - on a scale of 1-10 and provide specific mitigation strategies. - - Return a detailed report with executive summary, risk scores, detailed analysis, - and actionable recommendations. - """ + headers = { + "x-api-key": API_KEY, + "Content-Type": "application/json" + } - # Define specialized financial agents - financial_analysts = [ - { - "agent_name": "MarketAnalyst", - "description": "Specialist in market risk assessment and forecasting", - "system_prompt": "You are an expert market analyst with deep expertise in financial markets. Analyze market conditions, trends, and external factors that could impact financial performance. Provide quantitative and qualitative analysis of market-related risks.", - "model_name": "gpt-4o", - "temperature": 0.3, - "role": "analyst", - "max_loops": 1 - }, - { - "agent_name": "CreditRiskAnalyst", - "description": "Expert in assessing credit and counterparty risks", - "system_prompt": "You are a specialist in credit risk analysis with experience in banking and financial institutions. Evaluate creditworthiness, default probabilities, and counterparty exposures. Provide detailed analysis of credit-related risks and recommended safeguards.", - "model_name": "gpt-4o", - "temperature": 0.2, - "role": "analyst", - "max_loops": 1 - }, + batch_agents = [ { - "agent_name": "RegulatoryExpert", - "description": "Expert in financial regulations and compliance", - "system_prompt": "You are a regulatory compliance expert with deep knowledge of financial regulations. Identify potential regulatory risks, compliance issues, and governance concerns. Recommend compliance measures and risk mitigation strategies.", - "model_name": "gpt-4o", - "temperature": 0.2, - "role": "analyst", - "max_loops": 1 + "agent_config": { + "agent_name": "Market Analyst", + "description": "Expert in market analysis", + "system_prompt": "You are a financial market analyst.", + "model_name": "gpt-4o", + "temperature": 0.3 + }, + "task": "Analyze the current market trends in AI technology sector" }, { - "agent_name": "RiskSynthesizer", - "description": "Integrates all risk factors into comprehensive assessment", - "system_prompt": "You are a senior risk management professional responsible for synthesizing multiple risk analyses into a coherent, comprehensive risk assessment. Integrate analyses from various domains, resolve conflicting assessments, and provide a holistic view of risk exposure with prioritized recommendations.", - "model_name": "gpt-4o", - "temperature": 0.4, - "role": "manager", - "max_loops": 1 + "agent_config": { + "agent_name": "Technical Writer", + "description": "Specialized in technical documentation", + "system_prompt": "You are a technical documentation expert.", + "model_name": "gpt-4o", + "temperature": 0.7 + }, + "task": "Create a technical guide for implementing OAuth2 authentication" } ] - # Create the swarm specification - swarm_spec = { - "name": "financial-risk-assessment", - "description": "Comprehensive financial risk assessment swarm", - "agents": financial_analysts, - "max_loops": 2, - "swarm_type": "HiearchicalSwarm", - "task": task, - "return_history": True - } - - # Execute the swarm response = requests.post( - f"{API_BASE_URL}/v1/swarm/completions", - headers=HEADERS, - json=swarm_spec + f"{API_BASE_URL}/v1/agent/batch/completions", + headers=headers, + json=batch_agents ) if response.status_code == 200: result = response.json() - print(f"Risk assessment completed. Cost: ${result['metadata']['billing_info']['total_cost']}") - return result["output"] + print(f"Batch completed with {result['total_requests']} agents") + print(f"Execution time: {result['execution_time']} seconds") + print("\nResults:") + for i, agent_result in enumerate(result['results']): + print(f" Agent {i+1}: {agent_result['name']} - {agent_result['success']}") else: print(f"Error: {response.status_code} - {response.text}") - return None + ``` -# Usage example -if __name__ == "__main__": - company_data = """ - XYZ Financial Services - Annual Revenue: $125M - Current Debt: $45M - Credit Rating: BBB+ - Primary Markets: North America, Europe - Key Products: Asset management, retirement planning, commercial lending - Recent Events: Expanding into Asian markets, New CEO appointed 6 months ago - """ - - market_conditions = """ - Current interest rates rising (Federal Reserve increased rates by 0.25% last month) - Inflation at 3.2% (12-month outlook projects 3.5-4.0%) - Market volatility index (VIX) at 22.4 (elevated) - Regulatory environment: New financial reporting requirements taking effect next quarter - Sector performance: Financial services sector underperforming broader market by 2.7% - """ - - risk_tolerance = "moderate" - - result = financial_risk_assessment(company_data, market_conditions, risk_tolerance) - - if result: - # Process and use the risk assessment - print(json.dumps(result, indent=2)) - - # Optionally, schedule a follow-up assessment - tomorrow = datetime.utcnow() + timedelta(days=30) - schedule_spec = { - "name": "monthly-risk-update", - "description": "Monthly update to risk assessment", - "task": f"Update the risk assessment for XYZ Financial Services based on current market conditions. Previous assessment: {json.dumps(result)}", - "schedule": { - "scheduled_time": tomorrow.isoformat() + "Z", - "timezone": "UTC" - } - } - - schedule_response = requests.post( - f"{API_BASE_URL}/v1/swarm/schedule", - headers=HEADERS, - json=schedule_spec - ) - - if schedule_response.status_code == 200: - print("Follow-up assessment scheduled successfully") - print(schedule_response.json()) -``` +=== "TypeScript (fetch)" + ```typescript + interface AgentConfig { + agent_name: string; + description: string; + system_prompt: string; + model_name: string; + temperature: number; + } -#### Healthcare Patient Data Analysis (Python) + interface AgentCompletion { + agent_config: AgentConfig; + task: string; + } -This example demonstrates creating a swarm for analyzing patient health data and generating insights. + const API_BASE_URL = "https://api.swarms.world"; + const API_KEY = "your_api_key_here"; -```python -import requests -import json -import os -from datetime import datetime + async function runBatchAgents(): Promise { + const batchAgents: AgentCompletion[] = [ + { + agent_config: { + agent_name: "Market Analyst", + description: "Expert in market analysis", + system_prompt: "You are a financial market analyst.", + model_name: "gpt-4o", + temperature: 0.3 + }, + task: "Analyze the current market trends in AI technology sector" + }, + { + agent_config: { + agent_name: "Technical Writer", + description: "Specialized in technical documentation", + system_prompt: "You are a technical documentation expert.", + model_name: "gpt-4o", + temperature: 0.7 + }, + task: "Create a technical guide for implementing OAuth2 authentication" + } + ]; + + try { + const response = await fetch(`${API_BASE_URL}/v1/agent/batch/completions`, { + method: 'POST', + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + }, + body: JSON.stringify(batchAgents) + }); + + if (response.ok) { + const result = await response.json(); + console.log(`Batch completed with ${result.total_requests} agents`); + console.log(`Execution time: ${result.execution_time} seconds`); + console.log("\nResults:"); + result.results.forEach((agentResult: any, index: number) => { + console.log(` Agent ${index + 1}: ${agentResult.name} - ${agentResult.success}`); + }); + } else { + console.error(`Error: ${response.status} - ${await response.text()}`); + } + } catch (error) { + console.error("Request failed:", error); + } + } -# API Configuration -API_BASE_URL = "https://api.swarms.world" -API_KEY = os.environ.get("SWARMS_API_KEY") -HEADERS = { - "x-api-key": API_KEY, - "Content-Type": "application/json" -} + runBatchAgents(); + ``` -def analyze_patient_health_data(patient_data, medical_history, lab_results, treatment_goals): - """ - Creates and runs a swarm to analyze patient health data and generate insights. - - Args: - patient_data (str): Basic patient information - medical_history (str): Patient's medical history - lab_results (str): Recent laboratory results - treatment_goals (str): Treatment objectives - - Returns: - dict: Comprehensive health analysis and recommendations - """ - # Prepare the detailed task description - task = f""" - Perform a comprehensive analysis of the following patient health data: - - PATIENT INFORMATION: - {patient_data} - - MEDICAL HISTORY: - {medical_history} - - LABORATORY RESULTS: - {lab_results} - - TREATMENT GOALS: - {treatment_goals} - - Analyze all aspects of the patient's health status, identify potential concerns, - evaluate treatment effectiveness, and provide evidence-based recommendations for - optimizing care. Consider medication interactions, lifestyle factors, and preventive measures. - - Return a detailed clinical report with key findings, risk stratification, - prioritized recommendations, and suggested follow-up timeline. - """ - - # Create the swarm specification with auto-generated agents - # (letting the system create specialized medical experts) - swarm_spec = { - "name": "patient-health-analysis", - "description": "Comprehensive patient health data analysis", - "swarm_type": "AutoSwarmBuilder", - "task": task, - "max_loops": 3, - "return_history": True +**Response**: +```json +{ + "batch_id": "agent-batch-xyz789", + "total_requests": 2, + "execution_time": 15.5, + "timestamp": "2024-03-05T12:34:56.789Z", + "results": [ + { + "id": "agent-abc123", + "success": true, + "name": "Market Analyst", + "outputs": { + "market_analysis": "..." + }, + "usage": { + "input_tokens": 300, + "output_tokens": 600, + "total_tokens": 900 + } + }, + { + "id": "agent-def456", + "success": true, + "name": "Technical Writer", + "outputs": { + "technical_guide": "..." + }, + "usage": { + "input_tokens": 400, + "output_tokens": 800, + "total_tokens": 1200 + } } - - # Execute the swarm - try: - response = requests.post( - f"{API_BASE_URL}/v1/swarm/completions", - headers=HEADERS, - json=swarm_spec - ) - - response.raise_for_status() - result = response.json() - - # Log the execution metadata - execution_time = result["metadata"]["execution_time_seconds"] - cost = result["metadata"]["billing_info"]["total_cost"] - num_agents = result["metadata"]["num_agents"] - - print(f"Analysis completed in {execution_time:.2f} seconds") - print(f"Used {num_agents} specialized medical agents") - print(f"Total cost: ${cost:.4f}") - - # Return just the analysis results - return result["output"] - - except requests.exceptions.RequestException as e: - print(f"API request failed: {str(e)}") - if hasattr(e, 'response') and e.response: - print(f"Response: {e.response.text}") - return None - except Exception as e: - print(f"Error: {str(e)}") - return None - -# Usage example -if __name__ == "__main__": - # Sample patient data (would typically come from EHR system) - patient_data = """ - ID: PT-28456 - Age: 67 - Gender: Female - Height: 162 cm - Weight: 78 kg - Vitals: - - Blood Pressure: 142/88 mmHg - - Heart Rate: 76 bpm - - Respiratory Rate: 16/min - - Temperature: 37.1°C - - Oxygen Saturation: 97% - """ - - medical_history = """ - Diagnoses: - - Type 2 Diabetes Mellitus (diagnosed 12 years ago) - - Hypertension (diagnosed 8 years ago) - - Osteoarthritis (knees, diagnosed 5 years ago) - - Hyperlipidemia - - Surgical History: - - Cholecystectomy (15 years ago) - - Right knee arthroscopy (3 years ago) - - Medications: - - Metformin 1000mg BID - - Lisinopril 20mg daily - - Atorvastatin 40mg daily - - Aspirin 81mg daily - - Acetaminophen 500mg PRN for joint pain - - Allergies: - - Penicillin (rash) - - Sulfa drugs (hives) - - Family History: - - Father: MI at age 70, died at 76 - - Mother: Breast cancer at 68, Type 2 Diabetes, died at 82 - - Sister: Type 2 Diabetes, Hypertension - """ - - lab_results = """ - CBC (2 days ago): - - WBC: 7.2 x10^9/L (normal) - - RBC: 4.1 x10^12/L (low-normal) - - Hemoglobin: 12.8 g/dL (low-normal) - - Hematocrit: 38% (low-normal) - - Platelets: 245 x10^9/L (normal) - - Comprehensive Metabolic Panel: - - Glucose (fasting): 142 mg/dL (elevated) - - HbA1c: 7.8% (elevated) - - BUN: 22 mg/dL (normal) - - Creatinine: 1.1 mg/dL (normal) - - eGFR: 62 mL/min/1.73m² (mildly reduced) - - Sodium: 138 mEq/L (normal) - - Potassium: 4.2 mEq/L (normal) - - Chloride: 101 mEq/L (normal) - - Calcium: 9.4 mg/dL (normal) - - ALT: 32 U/L (normal) - - AST: 28 U/L (normal) - - Lipid Panel: - - Total Cholesterol: 198 mg/dL - - Triglycerides: 172 mg/dL (elevated) - - HDL: 42 mg/dL (low) - - LDL: 122 mg/dL (borderline elevated) - - Urinalysis: - - Microalbumin/Creatinine ratio: 45 mg/g (elevated) - """ - - treatment_goals = """ - Primary Goals: - - Improve glycemic control (target HbA1c < 7.0%) - - Blood pressure control (target < 130/80 mmHg) - - Lipid management (target LDL < 100 mg/dL) - - Renal protection (reduce microalbuminuria) - - Weight management (target BMI < 27) - - Pain management for osteoarthritis - - Maintain functional independence - - Patient Preferences: - - Prefers to minimize medication changes if possible - - Interested in dietary approaches - - Concerned about memory changes - - Limited exercise tolerance due to knee pain - """ - - result = analyze_patient_health_data(patient_data, medical_history, lab_results, treatment_goals) - - if result: - # Write the analysis to a report file - timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") - with open(f"patient_analysis_{timestamp}.json", "w") as f: - json.dump(result, f, indent=2) - - print(f"Analysis saved to patient_analysis_{timestamp}.json") - - # Display key findings - if "key_findings" in result: - print("\nKEY FINDINGS:") - for i, finding in enumerate(result["key_findings"]): - print(f" {i+1}. {finding}") - - # Display recommendations - if "recommendations" in result: - print("\nRECOMMENDATIONS:") - for i, rec in enumerate(result["recommendations"]): - print(f" {i+1}. {rec}") + ] +} ``` +----- + +## Production Examples + ## Error Handling The Swarms API follows standard HTTP status codes for error responses: @@ -47815,76 +57418,94 @@ Error responses include a detailed message explaining the issue: ## Rate Limiting -The API enforces a rate limit of 100 requests per 60-second window. When exceeded, a 429 status code is returned. Implement appropriate retry logic with exponential backoff in production applications. +| Description | Details | +|-------------|---------| +| Rate Limit | 100 requests per 60-second window | +| Exceed Consequence | 429 status code returned | +| Recommended Action | Implement retry logic with exponential backoff | ## Billing & Cost Management -The API uses a credit-based billing system with costs calculated based on: - -1. **Agent Count**: Base cost per agent - - -2. **Input Tokens**: Cost based on the size of input data and prompts - -3. **Output Tokens**: Cost based on the length of generated responses - -4. **Time of Day**: Reduced rates during nighttime hours (8 PM to 6 AM PT) - -Cost information is included in each response's metadata for transparency and forecasting. +| Cost Factor | Description | +|-------------|-------------| +| Agent Count | Base cost per agent | +| Input Tokens | Cost based on size of input data and prompts | +| Output Tokens | Cost based on length of generated responses | +| Time of Day | Reduced rates during nighttime hours (8 PM to 6 AM PT) | +| Cost Information | Included in each response's metadata | ## Best Practices -1. **Task Description** - - - Provide detailed, specific task descriptions +### Task Description - - Include all necessary context and constraints - - - Structure complex inputs for easier processing - -2. **Agent Configuration** - - - For simple tasks, use `AutoSwarmBuilder` to automatically generate optimal agents - - - For complex or specialized tasks, manually define agents with specific expertise - - - Use appropriate `swarm_type` for your workflow pattern - -3. **Production Implementation** - - - Implement robust error handling and retries - - - Log API responses for debugging and auditing - - - Monitor costs closely during development and testing - - - Use scheduled jobs for recurring tasks instead of continuous polling +| Practice | Description | +|----------|-------------| +| Detail | Provide detailed, specific task descriptions | +| Context | Include all necessary context and constraints | +| Structure | Structure complex inputs for easier processing | -4. **Cost Optimization** +### Agent Configuration - - Batch related tasks when possible +| Practice | Description | +|----------|-------------| +| Simple Tasks | Use `AutoSwarmBuilder` for automatic agent generation | +| Complex Tasks | Manually define agents with specific expertise | +| Workflow | Use appropriate `swarm_type` for your workflow pattern | - - Schedule non-urgent tasks during discount hours +### Production Implementation - - Carefully scope task descriptions to reduce token usage +| Practice | Description | +|----------|-------------| +| Error Handling | Implement robust error handling and retries | +| Logging | Log API responses for debugging and auditing | +| Cost Monitoring | Monitor costs closely during development and testing | - - Cache results when appropriate +### Cost Optimization +| Practice | Description | +|----------|-------------| +| Batching | Batch related tasks when possible | +| Scheduling | Schedule non-urgent tasks during discount hours | +| Scoping | Carefully scope task descriptions to reduce token usage | +| Caching | Cache results when appropriate | ## Support -For technical assistance with the Swarms API, please contact: - -- Documentation: [https://docs.swarms.world](https://docs.swarms.world) -- Email: kye@swarms.world -- Community Discord: [https://discord.gg/jM3Z6M9uMq](https://discord.gg/jM3Z6M9uMq) -- Swarms Marketplace: [https://swarms.world](https://swarms.world) -- Swarms AI Website: [https://swarms.ai](https://swarms.ai) - +| Support Type | Contact Information | +|--------------|---------------------| +| Documentation | [https://docs.swarms.world](https://docs.swarms.world) | +| Email | kye@swarms.world | +| Community | [https://discord.gg/jM3Z6M9uMq](https://discord.gg/jM3Z6M9uMq) | +| Marketplace | [https://swarms.world](https://swarms.world) | +| Website | [https://swarms.ai](https://swarms.ai) | + +## Service Tiers + +### Standard Tier + +| Feature | Description | +|---------|-------------| +| Processing | Default processing tier | +| Execution | Immediate execution | +| Priority | Higher priority processing | +| Pricing | Standard pricing | +| Timeout | 5-minute timeout limit | + +### Flex Tier + +| Feature | Description | +|---------|-------------| +| Cost | Lower cost processing | +| Retries | Automatic retries (up to 3 attempts) | +| Timeout | 15-minute timeout | +| Discount | 75% discount on token costs | +| Suitability | Best for non-urgent tasks | +| Backoff | Exponential backoff on resource contention | +| Configuration | Set `service_tier: "flex"` in SwarmSpec | -------------------------------------------------- -# File: swarms_cloud/swarms_api_tools.md +# File: swarms_cloud\swarms_api_tools.md # Swarms API with Tools Guide @@ -48271,101 +57892,7 @@ if __name__ == "__main__": -------------------------------------------------- -# File: swarms_cloud/vision.md - -# The Swarms Cloud and Agent Marketplace - -We stand at the dawn of a new era—the **Agentic Economy**, where the power of intelligent automation is in the hands of everyone. The Swarms Cloud and Agent Marketplace will serve as the epicenter of this economy, enabling developers, businesses, and creators to easily publish, discover, and leverage intelligent agents. Our vision is to make publishing agents as simple as possible through an intuitive CLI, while empowering users to generate income by posting their APIs on the marketplace. - -The Swarms Marketplace is more than just a platform—it’s a **revolutionary ecosystem** that will change how we think about automation and intelligence. By building this platform, we aim to democratize access to agent-driven solutions, enabling a seamless bridge between creators and consumers of automation. With every agent posted to the marketplace, a ripple effect is created, driving innovation across industries and providing an unparalleled opportunity for monetization. - ---- - -### The Agent Marketplace - -#### A Unified Platform for Automation - -In the Swarms Marketplace, **agents will be the new currency of efficiency**. Whether you’re building agents for marketing, finance, customer service, or any other domain, the Swarms Cloud will allow you to showcase your agentic APIs, easily discoverable by anyone needing those capabilities. - -We envision the marketplace to function like an API store, where users can search for specific agent capabilities, purchase access to agents, or even integrate their existing systems with agent-based APIs that others have developed. Each agent you publish will come with a potential income stream as businesses and developers integrate your creations into their workflows. - -#### The Opportunity to Monetize Your APIs - -The Swarms Marketplace is designed to let developers and businesses generate income by sharing their agent APIs. Once your agent is published to the marketplace, other users can browse, test, and integrate it into their operations. You will be able to set custom pricing, usage tiers, and licensing terms for your API, ensuring you can profit from your innovations. - -Our vision for monetization includes: - -- **API subscriptions**: Allow users to subscribe to your agent API with recurring payments. - -- **Per-use pricing**: Offer users a pay-as-you-go model where they only pay for the API calls they use. - -- **Licensing**: Enable others to purchase full access to your agent for a set period or on a project basis. - -### Publishing Agents: Simplicity Through CLI - -The complexity of deploying agents to a marketplace should never be a barrier. Our goal is to **streamline the publishing process** into something as simple as a command-line interaction. The Swarms CLI will be your one-stop solution to get your agent up and running on the marketplace. - -#### CLI Workflow: - -1. **Create an Agent**: Build your agent using the Swarms framework or any custom framework of your choice. -2. **Set Agent Metadata**: Through the CLI, input the metadata about your agent, including its capabilities, pricing, and target industries. -3. **Publish to Marketplace**: Run the simple `swarms publish` command to instantly deploy your agent to the marketplace. -4. **Monitor Usage and Income**: Use the Swarms Cloud dashboard to view your agent's interactions, track API usage, and receive payouts. - -Here’s an example of how easy publishing will be: - -```bash -$ swarms create-agent --name "CustomerSupportAgent" --type "LLM" -$ swarms set-metadata --description "An intelligent agent for customer support operations" --pricing "subscription" --rate "$20/month" -$ swarms publish -``` - -Within minutes, your agent will be live and accessible to the global marketplace! - ---- - -### Empowering Businesses - -For businesses, the marketplace offers **an unprecedented opportunity to automate tasks**, integrate pre-built agents, and drastically cut operational costs. Companies no longer need to build every system from scratch. With the marketplace, they can simply discover and plug in the agentic solutions that best suit their needs. - - -```mermaid -graph TD - A[Build Agent] --> B[Set Metadata] - B --> C[Publish to Marketplace] - C --> D{Agent Available Globally} - D --> E[Developers Discover API] - D --> F[Businesses Integrate API] - F --> G[Revenue Stream for Agent Creator] - E --> G -``` - ---- - -### The Future of Automation: Agents as APIs - -In this future we’re creating, **agents will be as ubiquitous as APIs**. The Swarms Marketplace will be an expansive repository of intelligent agents, each contributing to the automation and streamlining of everyday tasks. Imagine a world where every business can access highly specific, pre-built intelligence for any task, from customer support to supply chain management, and integrate these agents into their processes in minutes. - - -```mermaid -graph LR - A[Search for Agent API] --> B[Find Agent That Fits] - B --> C[Purchase Access] - C --> D[Integrate with Business System] - D --> E[Business Operations Streamlined] -``` - ---- - -### Conclusion - -The Swarms Cloud and Agent Marketplace will usher in an **agent-powered future**, where **automation is accessible to all**, and **monetization opportunities** are boundless. Our vision is to create a space where developers can not only build and showcase their agents but can also create sustainable income streams from their creations. The CLI will remove the friction of deployment, and the marketplace will enable a **self-sustaining ecosystem** of agentic intelligence that powers the next generation of automation. - -Together, we will shape the **Agentic Economy**, where **collaboration, innovation, and financial opportunity** intersect. Welcome to the future of intelligent automation. Welcome to **Swarms Cloud**. - --------------------------------------------------- - -# File: swarms_memory/chromadb.md +# File: swarms_memory\chromadb.md # ChromaDB Documentation @@ -48511,7 +58038,7 @@ By following this documentation, users can effectively utilize the ChromaDB modu -------------------------------------------------- -# File: swarms_memory/faiss.md +# File: swarms_memory\faiss.md # FAISSDB: Documentation @@ -48748,7 +58275,7 @@ By following this documentation, users can effectively utilize the `FAISSDB` cla -------------------------------------------------- -# File: swarms_memory/index.md +# File: swarms_memory\index.md # Announcing the Release of Swarms-Memory Package: Your Gateway to Efficient RAG Systems @@ -48926,7 +58453,7 @@ For more detailed usage examples and documentation, visit our [GitHub repository -------------------------------------------------- -# File: swarms_memory/pinecone.md +# File: swarms_memory\pinecone.md # PineconeMemory Documentation @@ -49110,7 +58637,7 @@ This concludes the detailed documentation for the `PineconeMemory` class. The cl -------------------------------------------------- -# File: swarms_platform/account_management.md +# File: swarms_platform\account_management.md # Swarms Platform Account Management Documentation @@ -49305,7 +58832,7 @@ For further assistance or to learn more about managing your account on the Swarm -------------------------------------------------- -# File: swarms_platform/agents/agents_api.md +# File: swarms_platform\agents\agents_api.md # Agents API Documentation @@ -49527,7 +59054,7 @@ The response will be a JSON object containing the result of the operation. Examp -------------------------------------------------- -# File: swarms_platform/agents/edit_agent.md +# File: swarms_platform\agents\edit_agent.md # Endpoint: Edit Agent @@ -49784,7 +59311,7 @@ This comprehensive documentation provides all the necessary information to effec -------------------------------------------------- -# File: swarms_platform/agents/fetch_agents.md +# File: swarms_platform\agents\fetch_agents.md # Documentation for `getAllAgents` API Endpoint @@ -50204,7 +59731,7 @@ This documentation provides a comprehensive guide to the `getAllAgents` API endp -------------------------------------------------- -# File: swarms_platform/apikeys.md +# File: swarms_platform\apikeys.md # Swarms Platform API Keys Documentation @@ -50296,7 +59823,196 @@ For any further questions or issues regarding API key management, please refer t -------------------------------------------------- -# File: swarms_platform/index.md +# File: swarms_platform\apps_page.md + +# Swarms Marketplace Apps Documentation + + +The Swarms Apps page (`https://swarms.world/apps`) is your central hub for managing and customizing your workspace experience. Here you can control which applications appear in your sidebar, organize them using templates, and quickly access the tools you need for different workflows. + +## Apps Gallery + +### Customizing Your Sidebar + +The Apps Gallery allows you to curate your workspace by selecting which applications you want to see in your sidebar. This personalized approach ensures you have quick access to the tools most relevant to your work. + +**Key Features:** + +- **Selective App Display**: Choose exactly which apps appear in your sidebar + +- **Favorites System**: Star your most-used apps to pin them for instant access + +- **Quick Access**: Starred apps remain easily accessible regardless of your current template + + +### How to Use the Apps Gallery + +1. **Browse Available Apps**: Scroll through the complete list of available applications +2. **Toggle App Visibility**: Click on apps to add or remove them from your sidebar +3. **Star Favorites**: Click the star icon on frequently used apps to pin them +4. **Instant Updates**: Changes to your sidebar configuration take effect immediately + +## Quick Sidebar Templates + +Templates provide pre-configured app collections optimized for specific workflows. Instead of manually selecting apps one by one, you can choose a template that matches your current needs. + +### Available Templates + +#### 🏪 Marketplace Template + +*Perfect for discovering and managing marketplace content* + +**Included Apps:** + +- **Marketplace**: Browse and discover new tools, agents, and prompts + +- **App Store**: Access autonomous AI applications + +- **Leaderboard**: View top creators and contributors + +- **Dashboard**: Your main control center + +- **Settings**: Account and organization configuration + + +**Best For:** Content discovery, community engagement, platform exploration + +#### 🎨 No-Code Solutions Template + +*Ideal for users who prefer visual, drag-and-drop interfaces* + +**Included Apps:** +- **Dashboard**: Central control and overview + +- **Chat**: Direct communication with agents and team members + +- **Spreadsheet**: Collaborative AI-powered spreadsheets + +- **Drag n Drop**: Visual workflow builder for creating processes + +- **Settings**: Platform configuration options + + +**Best For:** Visual workflow creation, collaborative work, rapid prototyping + +#### 👨‍💻 Developer Template + +*Designed for technical users and developers* + +**Included Apps:** +- **Dashboard**: System overview and monitoring + +- **API Key**: Manage authentication credentials + +- **Telemetry**: Monitor platform usage and analytics + +- **Settings**: Advanced configuration options + +- **Playground**: Testing and experimentation environment + + +**Best For:** API integration, performance monitoring, technical development + +#### 📱 All Apps Template + +*Comprehensive access to every available application* + +**Features:** +- **Complete Access**: Activates all available apps in your sidebar + +- **Maximum Flexibility**: Switch between any tool without reconfiguration + +- **Full Feature Set**: Access to every platform capability + + +**Best For:** Power users, comprehensive workflows, exploration of all features + +## App Categories + +### Marketplace Applications + +These apps focus on content discovery, community interaction, and marketplace functionality. + +#### Dashboard + +Your primary control center providing system overview, key metrics, and quick access to important functions. + +#### Marketplace + +Discover and utilize new tools, agents, and prompts created by the community. Browse categories, read reviews, and integrate new capabilities into your workflows. + +#### App Store + +Access a curated collection of autonomous AI applications. These are complete solutions that can operate independently to accomplish specific tasks. + +#### Leaderboard + +View rankings of top creators, contributors, and most popular content. Discover trending tools and identify influential community members. + +#### Marketplace Bookmarks +Organize and manage your saved marketplace items. Keep track of tools you want to try later or frequently reference. + +### No Code Agent Platforms + +Visual, user-friendly tools that don't require programming knowledge. + +| Application | Description | +|-------------|-------------| +| Apps | Meta-application for managing your sidebar configuration. Add, remove, and organize your available applications. | +| Chat | Real-time communication interface for conversing with AI agents and team members. Supports both individual and group conversations. | +| Spreadsheet Swarm | AI-enhanced collaborative spreadsheets that combine familiar spreadsheet functionality with intelligent automation and team collaboration features. | +| Drag & Drop | Visual workflow builder allowing you to create complex processes using intuitive drag-and-drop interfaces. Connect different tools and actions without coding. | + +### Account Settings + +Configuration and management tools for your account and organization. + +| Application | Description | +|-------------|-------------| +| API Keys | Secure management of your authentication credentials. Generate, rotate, and manage API keys for integrating external services. | +| Telemetry | Comprehensive analytics dashboard showing platform usage, performance metrics, and usage patterns. Monitor your organization's AI agent activity. | +| Settings | Central configuration hub for account preferences, organization settings, notification preferences, and platform customization options. | +| Playground | Safe testing environment for experimenting with new configurations, testing API calls, and prototyping workflows before implementing them in production. | + +## Best Practices + +### Template Selection Strategy + +**Start with Templates**: Begin with a template that matches your primary use case, then customize as needed. + +**Regular Review**: Periodically reassess your app selection as your needs evolve. + +**Workflow-Specific**: Consider switching templates based on current projects or tasks. + +### App Management Tips + +**Star Strategically**: Only star apps you use daily to avoid sidebar clutter. + +**Template Switching**: Don't hesitate to switch templates when your focus changes. + +**Exploration**: Periodically activate the "All" template to discover new capabilities. + +### Organization Recommendations + +**Role-Based Setup**: Configure templates based on team roles (developers, content creators, analysts). + +**Project Phases**: Adjust app selection based on project phases (research, development, deployment). + +**Performance Monitoring**: Use telemetry data to optimize your app selection over time. + +## Getting Started + +1. **Visit the Apps Page**: Navigate to `https://swarms.world/apps` +2. **Choose a Template**: Select the template that best matches your immediate needs +3. **Customize**: Add or remove specific apps based on your preferences +4. **Star Favorites**: Mark your most-used apps as favorites +5. **Start Working**: Your customized sidebar is immediately available across the platform + +The Apps page puts you in complete control of your Swarms experience, ensuring you have the right tools at your fingertips for any task or workflow. + +-------------------------------------------------- + +# File: swarms_platform\index.md # Swarms Platform Documentation @@ -50423,7 +60139,481 @@ The Swarms Platform is a versatile and powerful ecosystem for managing intellige -------------------------------------------------- -# File: swarms_platform/prompts/add_prompt.md +# File: swarms_platform\monetize.md + +# Swarms.World Monetization Guide + +## Quick Overview + +Swarms Marketplace has activated its payment infrastructure, enabling creators to monetize AI agents, prompts, and tools directly through the platform. Sellers receive payments minus a 5-15% platform fee, scaled based on subscription tiers. Revenue accrues in real-time to integrated crypto wallets, with optional fiat conversions. + +--- + +## Eligibility Requirements + +### Current Requirements for Paid Content + +- **2+ published items** (Prompts, Agents, and Tools) + +- **2 Items with 4+ star ratings** (you need community ratings) + +- **Marketplace Agent Rating** An agent will automatically rate your prompt, agent, or tool. + +**Bottom Line**: You must build reputation with free, high-quality content first. + +--- + +## Step-by-Step Process + +### Phase 1: Build Reputation (Required First) + +#### 1. Improve Your Existing Content + +- Add better descriptions and examples to your published items + +- Use the Rating System: Evaluate and rate prompts, agents, and tools based on their effectiveness. Commenting System: Share feedback and insights with the Swarms community + +- Ask users for honest reviews and ratings + +#### 2. Create More Quality Content + +Focus on these categories: + +- **Agents**: Marketing, finance, or programming automation + +- **Prompts**: Templates for specific business tasks + +- **Tools**: Utilities that solve real problems + +Target: 3-5 additional items, all aiming for 4+ star ratings + +#### 3. Get Community Ratings + +- Share your content in relevant communities + +- Engage with users who try your content + +- Respond to feedback and improve based on comments + +- Be patient - ratings take time to accumulate + +### Phase 2: Start Monetizing + +#### 4. Choose Your Pricing Model + +Three primary monetization avenues exist: AI agents (autonomous task-execution models), prompts (pre-optimized input templates), and tools (development utilities like data preprocessors) + +**Pricing Options:** + +- **One-time**: $0.01 - $999,999 USD + +- **Subscription**: Monthly/annual recurring fees (Coming Soon) + +- **Usage-based**: Pay per API call or computation (Coming Soon) + + +#### 6. Optimize & Scale + +- Monitor your revenue and user feedback + +- Developers can bundle assets—such as pairing prompt libraries with compatible agents—creating value-added +packages + +- Create bundles of related content for higher value + +- Adjust pricing based on demand + +--- + +## Revenue Models + +### What Sells Best + +1. **Business Automation Agents** - Marketing, sales, finance + +2. **Industry-Specific Prompts** - Legal, medical, technical writing + +3. **Integration Tools** - APIs, data processors, connectors + +### Pricing Examples + +- Simple prompts: $1-50 + +- Complex agents: $20-500+ + +- Enterprise tools: $100-1000+ + +--- + +## Quick Tips for Success + +1. **Quality over quantity** - Better to have 3 excellent items than 10 mediocre ones +2. **Solve real problems** - Focus on actual business needs +3. **Document everything** - Clear instructions increase ratings +4. **Engage actively** - Respond to all user feedback +5. **Be patient** - Building reputation takes time but pays off + +--- + +## Common Mistakes to Avoid + +- Publishing low-quality content to meet quantity requirements + +- Not responding to user feedback + +- Setting prices too high before building reputation + +- Copying existing solutions without adding value + +- Ignoring community guidelines + + + +-------------------------------------------------- + +# File: swarms_platform\playground_page.md + +# Swarms API Playground Documentation + +## Overview + +The Swarms Playground (`https://swarms.world/platform/playground`) is an interactive testing environment that allows you to experiment with the Swarms API in real-time. This powerful tool enables you to configure AI agents, test different parameters, and generate code examples in multiple programming languages without writing any code manually. + +## Key Features + +- **Real-time API Testing**: Execute Swarms API calls directly in the browser + +- **Multi-language Code Generation**: Generate code examples in Python, Rust, Go, and TypeScript + +- **Interactive Configuration**: Visual interface for setting up agent parameters + +- **Live Output**: See API responses immediately in the output terminal + +- **Code Export**: Copy generated code for use in your applications + + +## Interface Overview + +### Language Selection + +The playground supports code generation in four programming languages: + +- **Python**: Default language with `requests` library implementation + +- **Rust**: Native Rust HTTP client implementation + +- **Go**: Standard Go HTTP package implementation + +- **TypeScript**: Node.js/browser-compatible implementation + + +Switch between languages using the dropdown menu in the top-right corner to see language-specific code examples. + +### Agent Modes + +The playground offers two distinct modes for testing different types of AI implementations: + +#### Single Agent Mode +Test individual AI agents with specific configurations and tasks. Ideal for: +- Prototype testing + +- Parameter optimization + +- Simple task automation + +- API familiarization + + +#### Multi-Agent Mode +Experiment with coordinated AI agent systems. Perfect for: +- Complex workflow automation + +- Collaborative AI systems + +- Distributed task processing + +- Advanced orchestration scenarios + + +## Configuration Parameters + +### Basic Agent Settings + +#### Agent Name +**Purpose**: Unique identifier for your agent +**Usage**: Helps distinguish between different agent configurations +**Example**: `"customer_service_bot"`, `"data_analyst"`, `"content_writer"` + +#### Model Name +**Purpose**: Specifies which AI model to use for the agent +**Default**: `gpt-4o-mini` +**Options**: Various OpenAI and other supported models +**Impact**: Affects response quality, speed, and cost + +#### Description +**Purpose**: Human-readable description of the agent's purpose +**Usage**: Documentation and identification +**Best Practice**: Be specific about the agent's intended function + +#### System Prompt +**Purpose**: Core instructions that define the agent's behavior and personality +**Impact**: Critical for agent performance and response style +**Tips**: +- Be clear and specific + +- Include role definition + +- Specify output format if needed + +- Add relevant constraints + + +### Advanced Parameters + +#### Temperature +**Range**: 0.0 - 2.0 + +**Default**: 0.5 +**Purpose**: Controls randomness in responses +- **Low (0.0-0.3)**: More deterministic, consistent responses + +- **Medium (0.4-0.7)**: Balanced creativity and consistency + +- **High (0.8-2.0)**: More creative and varied responses + + +#### Max Tokens +**Default**: 8192 +**Purpose**: Maximum length of the agent's response +**Considerations**: +- Higher values allow longer responses + +- Impacts API costs + +- Model-dependent limits apply + + +#### Role +**Default**: `worker` +**Purpose**: Defines the agent's role in multi-agent scenarios +**Common Roles**: `worker`, `manager`, `coordinator`, `specialist` + +#### Max Loops +**Default**: 1 +**Purpose**: Number of iterations the agent can perform +**Usage**: +- `1`: Single response + +- `>1`: Allows iterative problem solving + + +#### MCP URL (Optional) +**Purpose**: Model Context Protocol URL for external integrations +**Usage**: Connect to external services or data sources +**Format**: Valid URL pointing to MCP-compatible service + +### Task Definition + +#### Task +**Purpose**: Specific instruction or query for the agent to process +**Best Practices**: +- Be specific and clear + +- Include all necessary context + +- Specify desired output format + +- Provide examples when helpful + + +## Using the Playground + +### Step-by-Step Guide + +1. **Select Mode**: Choose between Single Agent or Multi-Agent +2. **Choose Language**: Select your preferred programming language +3. **Configure Agent**: Fill in the required parameters +4. **Define Task**: Enter your specific task or query +5. **Run Agent**: Click the "Run Agent" button +6. **Review Output**: Check the Output Terminal for results +7. **Copy Code**: Use the generated code in your applications + +### Testing Strategies + +#### Parameter Experimentation + +- **Temperature Testing**: Try different temperature values to find optimal creativity levels + +- **Prompt Engineering**: Iterate on system prompts to improve responses + +- **Token Optimization**: Adjust max_tokens based on expected response length + + +#### Workflow Development + +- **Start Simple**: Begin with basic tasks and gradually increase complexity + +- **Iterative Refinement**: Use playground results to refine your approach + +- **Documentation**: Keep notes on successful configurations + + +## Output Interpretation + +### Output Terminal + +The Output Terminal displays: + +- **Agent Responses**: Direct output from the AI agent + +- **Error Messages**: API errors or configuration issues + +- **Execution Status**: Success/failure indicators + +- **Response Metadata**: Token usage, timing information + + +### Code Preview + +The Code Preview section shows: + +- **Complete Implementation**: Ready-to-use code in your selected language + +- **API Configuration**: Proper headers and authentication setup + +- **Request Structure**: Correctly formatted payload + +- **Response Handling**: Basic error handling and output processing + + +## Code Examples by Language + +### Python Implementation +```python +import requests + +url = "https://swarms-api-285321057562.us-east1.run.app/v1/agent/completions" +headers = { + "Content-Type": "application/json", + "x-api-key": "your-api-key-here" +} + +payload = { + "agent_config": { + "agent_name": "example_agent", + "description": "Example agent for demonstration", + "system_prompt": "You are a helpful assistant.", + "model_name": "gpt-4o-mini", + "auto_generate_prompt": false, + "max_tokens": 8192, + "temperature": 0.5, + "role": "worker", + "max_loops": 1, + "tools_list_dictionary": null, + "mcp_url": null + }, + "task": "Explain quantum computing in simple terms" +} + +response = requests.post(url, json=payload, headers=headers) +print(response.json()) +``` + +### Key Code Components + +#### API Endpoint + +- **URL**: `https://swarms-api-285321057562.us-east1.run.app/v1/agent/completions` + +- **Method**: POST + +- **Authentication**: API key in `x-api-key` header + + +#### Request Structure + +- **Headers**: Content-Type and API key + +- **Payload**: Agent configuration and task + +- **Response**: JSON with agent output and metadata + + +## Best Practices + +### Security + +- **API Key Management**: Never expose API keys in client-side code + +- **Environment Variables**: Store sensitive credentials securely + +- **Rate Limiting**: Respect API rate limits in production + + +### Performance Optimization + +- **Parameter Tuning**: Optimize temperature and max_tokens for your use case + +- **Prompt Engineering**: Craft efficient system prompts + +- **Caching**: Implement response caching for repeated queries + + +### Development Workflow + +- **Prototype in Playground**: Test configurations before implementation + +- **Document Successful Configs**: Save working parameter combinations + +- **Iterate and Improve**: Use playground for continuous optimization + + +## Troubleshooting + +### Common Issues + +#### No Output in Terminal + +- **Check API Key**: Ensure valid API key is configured + +- **Verify Parameters**: All required fields must be filled + +- **Network Issues**: Check internet connection + + +#### Unexpected Responses + +- **Review System Prompt**: Ensure clear instructions + +- **Adjust Temperature**: Try different creativity levels + +- **Check Task Definition**: Verify task clarity and specificity + + +#### Code Generation Issues + +- **Language Selection**: Ensure correct language is selected + +- **Copy Functionality**: Use the "Copy Code" button for accurate copying + +- **Syntax Validation**: Test generated code in your development environment + + +## Integration Guide + +### From Playground to Production + +1. **Copy Generated Code**: Use the Code Preview section +2. **Add Error Handling**: Implement robust error handling +3. **Configure Environment**: Set up proper API key management +4. **Test Thoroughly**: Validate in your target environment +5. **Monitor Performance**: Track API usage and response quality + +The Swarms Playground is your gateway to understanding and implementing the Swarms API effectively. Use it to experiment, learn, and build confidence before deploying AI agents in production environments. + +-------------------------------------------------- + +# File: swarms_platform\prompts\add_prompt.md # Prompts API Documentation @@ -50606,7 +60796,7 @@ The response will be a JSON object containing the result of the operation. Examp -------------------------------------------------- -# File: swarms_platform/prompts/edit_prompt.md +# File: swarms_platform\prompts\edit_prompt.md # Endpoint: Edit Prompt @@ -50826,7 +61016,7 @@ This comprehensive documentation provides all the necessary information to effec -------------------------------------------------- -# File: swarms_platform/prompts/fetch_prompts.md +# File: swarms_platform\prompts\fetch_prompts.md # Documentation for `getAllPrompts` API Endpoint @@ -51157,214 +61347,406 @@ This documentation provides a comprehensive guide to the `getAllPrompts` API end -------------------------------------------------- -# File: swarms_platform/share_discover.md +# File: swarms_platform\share_and_discover.md +# Swarms Marketplace Documentation +The Swarms Marketplace (`https://swarms.world`) is a vibrant community hub where developers, researchers, and agent enthusiasts share and discover cutting-edge agent tools, agents, and prompts. This collaborative platform empowers you to leverage the collective intelligence of the Swarms community while contributing your own innovations. --------------------------------------------------- +## What You Can Discover -# File: swarms_platform/telemetry/index.md +### 🤖 Agents -# Swarms Telemetry API Documentation +Ready-to-use agent agents for specific tasks and industries: -This documentation covers the API for handling telemetry data. The API is implemented using Next.js, Supabase for data storage, and Zod for request validation. The handler processes incoming telemetry data, validates it, and stores it in a Supabase database. The handler also includes robust error handling and retries for database insertions to ensure data reliability. +- **Specialized Agents**: From healthcare diagnostics to financial analysis -## Endpoint +- **Multi-Agent Systems**: Collaborative agent swarms for complex workflows -- **URL:** `/api/telemetry` -- **Method:** `POST` -- **Content-Type:** `application/json` -- **Description:** Receives telemetry data and stores it in the Supabase database. +- **Industry Solutions**: Pre-built agents for healthcare, finance, education, and more -## Request Schema +- **Custom Implementations**: Unique agent architectures and approaches -The API expects a JSON object in the request body that matches the following schema, validated using Zod: -| Field Name | Type | Required | Description | -|---------------------|----------|----------|-----------------------------------------------------------| -| `data` | `any` | No | Telemetry data payload. | -| `swarms_api_key` | `string` | No | API key associated with the swarms framework. | -| `status` | `string` | No | Status of the telemetry data. Default is `'received'`. | -| `processing_time` | `string` | No | Time taken to process the telemetry data. | +### 💡 Prompts -## Response +System prompts and instructions that define agent behavior: -### Success Response +- **Role-Specific Prompts**: Behavioral psychologist, documentation specialist, financial advisor -- **Status Code:** `200 OK` -- **Content-Type:** `application/json` -- **Body:** +- **System Templates**: Production-grade prompts for various use cases -```json -{ - "message": "Telemetry data received and stored successfully" -} -``` +- **Collaborative Frameworks**: Multi-agent coordination prompts -### Error Responses +- **Task-Specific Instructions**: Optimized prompts for specific workflows -- **Status Code:** `400 Bad Request` -- **Content-Type:** `application/json` -- **Body:** -```json -{ - "error": "Invalid data format", - "details": [ - // Zod validation error details - ] -} -``` +### 🛠️ Tools -- **Status Code:** `405 Method Not Allowed` -- **Content-Type:** `application/json` -- **Body:** +APIs, integrations, and utilities that extend agent capabilities: -```json -{ - "error": "Method Not Allowed" -} -``` +- **API Integrations**: Connect to external services and data sources -- **Status Code:** `500 Internal Server Error` -- **Content-Type:** `application/json` -- **Body:** +- **Data Fetchers**: Tools for retrieving information from various platforms -```json -{ - "error": "Internal Server Error", - "details": "Error message" -} -``` +- **Workflow Utilities**: Helper functions and automation tools -## Example Usage +- **Communication Tools**: Integrations with messaging platforms and services -### Python (Using `requests` Library) -```python -import requests +## Browsing and Discovery -url = "https://swarms.world/api/telemetry" -headers = { - "Content-Type": "application/json" -} -data = { - "data": {"example_key": "example_value"}, - "swarms_api_key": "your_swarms_api_key", - "status": "received", - "processing_time": "123ms" -} +### Category-Based Navigation -response = requests.post(url, json=data, headers=headers) +**Industry Categories:** -print(response.status_code) -print(response.json()) -``` +- **Healthcare**: Medical diagnosis, patient care, research tools -### Node.js (Using `axios` Library) +- **Education**: Learning assistants, curriculum development, assessment tools -```javascript -const axios = require('axios'); - -const url = 'https://swarms.world/api/telemetry'; -const data = { - data: { example_key: 'example_value' }, - swarms_api_key: 'your_swarms_api_key', - status: 'received', - processing_time: '123ms' -}; +- **Finance**: Trading bots, market analysis, financial planning -axios.post(url, data) - .then(response => { - console.log(response.status); - console.log(response.data); - }) - .catch(error => { - console.error(error.response.status); - console.error(error.response.data); - }); -``` +- **Research**: Academic paper fetchers, data analysis, literature review -### Go (Using `net/http` and `encoding/json`) +- **Public Safety**: Risk assessment, emergency response, safety monitoring -```go -package main +- **Marketing**: Content creation, campagentgn optimization, audience analysis -import ( - "bytes" - "encoding/json" - "fmt" - "net/http" -) +- **Sales**: Lead generation, customer engagement, sales automation -func main() { - url := "https://swarms.world/api/telemetry" - data := map[string]interface{}{ - "data": map[string]interface{}{"example_key": "example_value"}, - "swarms_api_key": "your_swarms_api_key", - "status": "received", - "processing_time": "123ms", - } - jsonData, err := json.Marshal(data) - if err != nil { - fmt.Println("Error marshaling JSON:", err) - return - } +- **Customer Support**: Chatbots, issue resolution, knowledge management - req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData)) - if err != nil { - fmt.Println("Error creating request:", err) - return - } - req.Header.Set("Content-Type", "application/json") - client := &http.Client{} - resp, err := client.Do(req) - if err != nil { - fmt.Println("Error making request:", err) - return - } - defer resp.Body.Close() +### Trending Section + +Discover the most popular and highly-rated content in the community: + +- **Top-Rated Items**: Content with 5-star ratings from users + +- **Community Favorites**: Most shared and downloaded items + +- **Recent Additions**: Latest contributions to the marketplace + +- **Featured Content**: Curated selections highlighting exceptional work + + +### Search and Filtering + +- **Keyword Search**: Find specific tools, agents, or prompts by name or description + +- **Category Filters**: Browse within specific industry verticals + +- **Rating Filters**: Filter by community ratings and reviews + +- **Tag-Based Discovery**: Explore content by relevant tags and keywords + + +## Contributing to the Marketplace + +### Why Share Your Work? + +**🌟 Community Impact** + +- Help fellow developers solve similar challenges + +- Contribute to the collective advancement of agent technology + +- Build your reputation in the agent community + + +**📈 Professional Growth** + +- Showcase your expertise and innovative solutions + +- Receive feedback and suggestions from the community + +- Network with like-minded professionals and researchers + + +**🔄 Knowledge Exchange** + +- Learn from others who use and modify your contributions + +- Discover new approaches and improvements to your work + +- Foster collaborative innovation and problem-solving + + +**🏆 Recognition** + +- Get credited for your contributions with author attribution + +- Build a portfolio of public agent implementations + +- Gagentn visibility in the growing Swarms ecosystem + + +## How to Submit Content + +### Adding a Prompt + +Prompts are the foundation of agent behavior - share your carefully crafted instructions with the community. + + +**Step-by-Step Process:** + +1. **Click "Add Prompt"** from the marketplace interface +2. **Fill Required Fields:** + + - **Name**: Descriptive title that clearly indicates the prompt's purpose + + - **Description**: Detagentled explanation of what the prompt does and when to use it + + - **Prompt**: The complete system prompt or instruction text + +3. **Enhance Your Submission:** + - **Add Image**: Upload a visual representation (up to 60MB) + + - **Select Categories**: Choose relevant industry categories + + - **Add Tags**: Include searchable keywords and descriptors + +4. **Submit**: Review and submit your prompt to the community + +**Best Practices for Prompts:** + +- **Be Specific**: Clearly define the agent's role and expected behavior + +- **Include Context**: Provide background information and use case scenarios + +- **Test Thoroughly**: Ensure your prompt produces consistent, high-quality results + +- **Document Parameters**: Explagentn any variables or customization options + + +### Submitting an Agent + +Agents are complete agent implementations - share your working solutions with the community. + + +**Step-by-Step Process:** + +1. **Click "Add Agent"** from the marketplace interface +2. **Complete Required Information:** + - **Name**: Clear, descriptive agent name + + - **Description**: Comprehensive explanation of functionality and use cases + + - **Agent Code**: Complete, working implementation + + - **Language**: Select the programming language (Python, etc.) + +3. **Optimize Discoverability:** + - **Categories**: Choose appropriate industry verticals + + - **Image**: Add a representative image or diagram + + - **Tags**: Include relevant keywords for searchability + +4. **Submit**: Finalize and share your agent with the community + +**Agent Submission Guidelines:** + +- **Complete Implementation**: Provide fully functional, tested code + +- **Clear Documentation**: Include usage instructions and configuration detagentls + +- **Error Handling**: Implement robust error handling and validation + +- **Dependencies**: List all required libraries and dependencies + +- **Examples**: Provide usage examples and expected outputs + + +### Adding Tools + +Tools extend the capabilities of the Swarms ecosystem - share your integrations and utilities. + + +**What Makes a Great Tool:** + +- **Solves Real Problems**: Addresses common pagentn points or workflow gaps + +- **Easy Integration**: Simple to implement and configure + +- **Well Documented**: Clear instructions and examples + +- **Reliable Performance**: Tested and optimized for production use + + +## Content Quality Guidelines + +### Writing Effective Descriptions + +**For All Submissions:** + +- **Start with Purpose**: Lead with what your contribution does + +- **Explagentn Benefits**: Highlight the value and use cases + +- **Include Technical Detagentls**: Mention key features and capabilities + +- **Provide Context**: Explagentn when and why to use your contribution + + +**Example Description Structure:** - fmt.Println("Response status:", resp.Status) -} ``` +[Brief summary of what it does] -### cURL Command +Key Features: +- [Feature 1 with benefit] + +- [Feature 2 with benefit] + +- [Feature 3 with benefit] + + +Use Cases: +- [Scenario 1] + +- [Scenario 2] + +- [Scenario 3] + + +Technical Detagentls: +- [Implementation notes] + +- [Requirements or dependencies] + +- [Configuration options] -```bash -curl -X POST https://swarms.world/api/telemetry \ --H "Content-Type: application/json" \ --d '{ - "data": {"example_key": "example_value"}, - "swarms_api_key": "your_swarms_api_key", - "status": "received", - "processing_time": "123ms" -}' ``` -### Supabase Table Structure +### Choosing Categories and Tags + +**Categories:** + +- Select all relevant industry verticals + +- Consider cross-industry applications + +- Choose the primary category first + + +**Tags:** + +- Include technical keywords (API names, frameworks, models) + +- Add functional descriptors (automation, analysis, generation) + +- Include use case keywords (customer service, data processing, content creation) + +- Use common terminology that others would search for + + +### Visual Assets + +**Image Guidelines:** + +- **File Size**: Maximum 60MB supported + +- **Recommended Types**: Screenshots, diagrams, logos, workflow illustrations + +- **Quality**: High-resolution images that clearly represent your contribution + +- **Content**: Visual representations of functionality, architecture, or results + + +## Community Engagement + +### Rating and Reviews + +**As a User:** + +- Rate content honestly based on quality and usefulness + +- Leave constructive feedback to help creators improve + +- Share your experiences and modifications -The Supabase table (presumably `swarms_framework_schema`) should have the following columns: -- **`data`**: JSONB or TEXT - Stores the telemetry data payload. -- **`swarms_api_key`**: TEXT - Stores the API key associated with the data. -- **`source_ip`**: TEXT - Stores the IP address of the request source. -- **`status`**: TEXT - Stores the status of the data processing. -- **`processing_time`**: TEXT - Stores the time taken to process the telemetry data. +**As a Creator:** -## References and Further Reading +- Respond to feedback and questions -- [Next.js API Routes Documentation](https://nextjs.org/docs/api-routes/introduction) -- [Supabase JavaScript Client](https://supabase.com/docs/reference/javascript/supabase-client) -- [Zod Schema Validation](https://zod.dev/) -- [OpenAPI Specification](https://swagger.io/specification/) +- Update your submissions based on community input -This documentation is designed to be thorough and provide all the necessary details for developers to effectively use and integrate with the telemetry API. +- Engage with users who implement your solutions + + +### Building Your Reputation + +**Consistency**: Regularly contribute high-quality content +**Responsiveness**: Engage with community feedback and questions +**Innovation**: Share unique approaches and creative solutions +**Collaboration**: Build upon and improve existing community contributions + + +### What Makes Content Successful + +**Clear Value Proposition**: Immediately obvious benefits and use cases +**Production Ready**: Fully functional, tested implementations +**Good Documentation**: Clear instructions and examples +**Active Magentntenance**: Regular updates and community engagement +**Unique Approach**: Novel solutions or creative implementations + +## Getting Started + +### For New Contributors + +1. **Explore First**: Browse existing content to understand community standards +2. **Start Small**: Begin with a simple but useful contribution +3. **Focus on Quality**: Prioritize completeness and documentation over quantity +4. **Engage**: Participate in discussions and provide feedback to others + +### For Experienced Developers + +1. **Share Expertise**: Contribute advanced implementations and frameworks +2. **Mentor Others**: Provide feedback and suggestions to new contributors +3. **Lead Innovation**: Introduce cutting-edge approaches and techniques +4. **Build Ecosystems**: Create complementary tools and integrations + +## Best Practices Summary + +### Before Submitting + +- ✅ Test your contribution thoroughly + +- ✅ Write clear, comprehensive documentation + +- ✅ Choose appropriate categories and tags + +- ✅ Create or find a representative image + +- ✅ Review similar existing content + + +### After Submitting + +- ✅ Monitor for community feedback + +- ✅ Respond to questions and comments + +- ✅ Update based on user suggestions + +- ✅ Share your contribution on social platforms + +- ✅ Continue improving and iterating + + +## Join the Community + +The Swarms Marketplace thrives on community participation. Whether you're sharing a simple prompt or a complex multi-agent system, your contribution makes the entire ecosystem stronger. Start exploring, contributing, and collaborating today! + +**Ready to contribute?** Visit `https://swarms.world` and click "Add Prompt," "Add Agent," or "Add Tool" to share your innovation with the world. + +Together, we're building the future of agent collaboration, one contribution at a time. -------------------------------------------------- -# File: swarms_rs/agents.md +# File: swarms_rs\agents.md # swarms-rs @@ -51722,7 +62104,7 @@ Contributions to swarms-rs are welcome! Check out our [GitHub repository](https: -------------------------------------------------- -# File: swarms_rs/overview.md +# File: swarms_rs\overview.md # swarms-rs 🚀 @@ -51782,7 +62164,7 @@ Contributions to swarms-rs are welcome! Check out our [GitHub repository](https: -------------------------------------------------- -# File: swarms_tools/finance.md +# File: swarms_tools\finance.md # Swarms Finance Tools Documentation @@ -52112,7 +62494,7 @@ The package automatically handles most dependencies, but you may need to install -------------------------------------------------- -# File: swarms_tools/overview.md +# File: swarms_tools\overview.md # Swarms Tools @@ -52357,7 +62739,7 @@ Explore the limitless possibilities of agent-based systems. Together, we can bui -------------------------------------------------- -# File: swarms_tools/search.md +# File: swarms_tools\search.md # Search Tools Documentation @@ -52534,7 +62916,7 @@ For issues and feature requests, please visit the [GitHub repository](https://gi -------------------------------------------------- -# File: swarms_tools/twitter.md +# File: swarms_tools\twitter.md # Twitter Tool Documentation @@ -52697,23 +63079,11 @@ This is an example of how to use the TwitterTool in a production environment usi import os from time import time -from swarm_models import OpenAIChat from swarms import Agent from dotenv import load_dotenv from swarms_tools.social_media.twitter_tool import TwitterTool -load_dotenv() - -model_name = "gpt-4o" - -model = OpenAIChat( - model_name=model_name, - max_tokens=3000, - openai_api_key=os.getenv("OPENAI_API_KEY"), -) - - medical_coder = Agent( agent_name="Medical Coder", system_prompt=""" @@ -52762,7 +63132,8 @@ medical_coder = Agent( - For ambiguous cases, provide a brief note with reasoning and flag for clarification. - Ensure the output format is clean, consistent, and ready for professional use. """, - llm=model, + model_name="gpt-4o-mini", + max_tokens=3000, max_loops=1, dynamic_temperature_enabled=True, ) @@ -52864,152 +63235,3 @@ Be aware of Twitter's API rate limits. Implement appropriate delays between requ -------------------------------------------------- -# File: web3/token.md - - -# $swarms Tokenomics - -**Empowering the Agentic Revolution** -Token Contract Address: `74SBV4zDXxTRgv1pEMoECskKBkZHc2yGPnc7GYVepump` - -> You can buy $swarms on most marketplaces: -> **Pump.fun**, **Kraken**, **Bitget**, **Binance**, **OKX**, and more. - ---- - -## 📦 Overview - -- **Token Name:** Swarms Coin -- **Ticker:** `$swarms` -- **Blockchain:** Solana -- **Utility:** Powering the agentic economy. - ---- - -## 📊 Initial Token Distribution - -| Allocation | Percentage | -|-----------------|------------| -| 🧠 **Team** | 3% | -| 🌍 **Public Sale** | 97% | - -> ⚠️ At launch, only **2%** was reserved for the team — among the **smallest allocations in DAO history**. - ---- - -## 📣 A Message from the Team - -!!! quote - When we launched $swarms, we prioritized community ownership by allocating just 2% to the team. - Our intent was radical decentralization. But that decision has created unintended consequences. - -### ❗ Challenges We Faced - -- **Market manipulation** by whales and exchanges -- **Unsustainable funding** for innovation and ops -- **Malicious actors undermining decentralization** - ---- - -## 🛠 Our Proposed Solution - -We are initiating a **DAO governance proposal** to: - -=== "Key Reforms" - -- 📈 **Increase team allocation to 10%** - Secure operational longevity and attract top contributors. - -- 🌱 **Launch an ecosystem grants program** - Incentivize developers building agentic tools and infra. - -- 🛡 **Combat token manipulation** - Deploy anti-whale policies and explore token lockups. - -- 🤝 **Strengthen community dev initiatives** - Support contributor bounties, governance tooling, and hackathons. - -> This proposal isn’t about centralizing power — it's about protecting and empowering the **Swarms ecosystem**. - ---- - -## 💸 Contribute to Swarms DAO - -To expand our ecosystem, grow the core team, and bring agentic AI to the world, we invite all community members to **invest directly in Swarms DAO**. - -Send **$swarms** or **SOL** to our official treasury address: - -```plaintext -🪙 DAO Treasury Wallet: -7MaX4muAn8ZQREJxnupm8sgokwFHujgrGfH9Qn81BuEV -``` - -!!! success "Every contribution matters" - Whether it’s 1 $swarms or 1000 SOL — you’re helping fund a decentralized future. - -> You may use most wallets and platforms supporting Solana to send tokens. - ---- - -## 🧠 Why Invest? - -Your contributions fund: - -- Expansion of the **Swarms core team** -- Development of **open-source AI agent tooling** -- Community **grants** and contributor **bounties** -- Anti-manipulation strategies & decentralized governance tools - ---- - -## 🚀 How to Get Involved - -[![Join the DAO](https://img.shields.io/badge/DAO%20Governance-Click%20Here-blue?style=for-the-badge&logo=solana)](https://dao.swarms.world) -[![Investor Info](https://img.shields.io/badge/Investor%20Page-Explore-green?style=for-the-badge)](https://investors.swarms.world) - -### 🛠 You can: -- Vote on governance proposals - -- Submit development or funding proposals - -- Share $swarms with your network - -- Build with our upcoming agent SDKs - -- Contribute to the mission of agentic decentralization - ---- - -## 📘 Quick Summary - -| Key Metric | Value | -|----------------------------|------------------| -| **Token Symbol** | `$swarms` | -| **Blockchain** | Solana | -| **Initial Team Allocation**| 3% (Proposed 10%)| -| **Public Distribution** | 97% | -| **DAO Wallet** | `7MaX4muAn8ZQREJxnupm8sgokwFHujgrGfH9Qn81BuEV` | -| **DAO Governance** | [dao.swarms.world](https://dao.swarms.world) | - ---- - -## 🌍 Useful Links - -- [DAO Governance Portal][dao] - -- [Investor Information][investors] - -- [Official Site][site] - -- [Join Swarms on Discord][discord] - -[dao]: https://dao.swarms.world/ -[investors]: https://investors.swarms.world/ -[site]: https://swarms.world/ -[discord]: https://discord.gg/jM3Z6M9uMq -``` - - - --------------------------------------------------- - diff --git a/docs/swarms/changelog/5_6_8.md b/docs/swarms/changelog/5_6_8.md deleted file mode 100644 index ba043d58..00000000 --- a/docs/swarms/changelog/5_6_8.md +++ /dev/null @@ -1,44 +0,0 @@ -# Swarms ChangeLog 5.6.8 - - -The biggest update in Swarms history! We've introduced major fixes, updates, and new features to enhance your agent workflows and performance. To get the latest updates run the following: - -## Installation - -```bash -$ pip3 install -U swarms -``` - -# Log -Here’s the breakdown of the latest changes: - ---- - -### 🐞 **Fixes:** -- **[BUGF-AGENTS]:** Fixed various response issues within agents, leading to smoother performance. -- **[BUGF-MIXTURE]:** Resolved issues with the Mixture of Agents, ensuring more reliable and stable execution. -- **[CLEA-FILES]:** Removed unnecessary files, resulting in a significant speed boost and cleaner environment. - ---- - -### 🛠 **Updates:** -- **[REFA-MODULES]:** Refactored the `swarms.models` module into its own package: `swarm_models` for improved code organization. -- **[CLEA-AGENTS]:** Cleaned up tool logic in the `agents` class for streamlined and efficient operations. - ---- - -### ✨ **New Features:** -- **[FEAT-SWARMS]:** Introduced JSON outputs for `AgentRearrange`, `SpreadsheetSwarm`, and other swarms, improving data handling. -- **[FEAT-AGENTS]:** Added YAML file support for creating agents, making the setup process simpler than ever. -- **[FEAT-METADATA]:** Enhanced the `Agent` class with JSON metadata output, supporting OpenAI-like API responses with `output_type="json"` and `return_step_meta=True`. -- **[FEAT-FOREST]:** Released `ForestSwarm`, a new architecture that clusters agents into trees, enabling precise task execution. -- **[FEAT-REGISTRY]:** Fully implemented `AgentRegistry`, allowing you to store multiple agents for future use. - ---- - -### 🚀 **Performance Enhancements:** -- **[PERF-AGENTS]:** Accelerated agent execution by **4x**, with a **10x** boost coming soon, powered by our Rust backend. -- **[PERF-ARCH]:** Optimized multi-threading, concurrency, and asynchrony in swarm architectures, making them faster than ever. - ---- - -**Ready to dive in?** Get started now: [https://buff.ly/444kDjA](https://buff.ly/444kDjA) diff --git a/docs/swarms/changelog/5_8_1.md b/docs/swarms/changelog/5_8_1.md deleted file mode 100644 index 5d6d7b77..00000000 --- a/docs/swarms/changelog/5_8_1.md +++ /dev/null @@ -1,119 +0,0 @@ -# Swarms 5.8.1 Feature Documentation - -## 1. Enhanced Command Line Interface (CLI) - -### 1.1 Integrated Onboarding Process - -```bash -$ swarms onboarding -``` - -### 1.2 Run Agents Command - -```bash -$ swarms run-agents --yaml-file agents.yaml -``` - -This command allows users to execute multiple agents defined in a YAML file. Here's the process: - -1. The command reads the specified YAML file (`agents.yaml` in this case). -2. It parses the YAML content, extracting the configuration for each agent. -3. For each agent defined in the YAML: - - It creates an instance of the agent with the specified parameters. - - It sets up the agent's environment (model, temperature, max tokens, etc.). - - It assigns the given task to the agent. - - It executes the agent, respecting parameters like `max_loops`, `autosave`, and `verbose`. -4. The results from all agents are collected and presented to the user. - -The YAML file structure allows users to define multiple agents with different configurations, making it easy to run complex, multi-agent tasks from the command line. - -### 1.3 Generate Prompt Feature - -```bash -$ swarms generate-prompt --prompt "Create a marketing strategy for a new product launch" -``` - -This feature leverages Swarms' language model to generate expanded or refined prompts: - -1. The command takes the user's input prompt as a starting point. -2. It likely sends this prompt to a pre-configured language model (possibly GPT-4 or a similar model). -3. The model then generates an expanded or more detailed version of the prompt. -4. The generated prompt is returned to the user, possibly with options to further refine or save it. - -This feature can help users create more effective prompts for their agents or other AI tasks. - -## 2. New Prompt Management System - -### 2.1 Prompt Class - -The new `Prompt` class provides a robust system for managing and versioning prompts: - -```python -from swarms import Prompt - -marketing_prompt = Prompt(content="Initial marketing strategy draft", autosave=True) - -print(marketing_prompt.get_prompt()) -``` - -Key features of the `Prompt` class: - -1. **Initialization**: The class is initialized with initial content and an `autosave` option. - -2. **Editing**: - ```python - marketing_prompt.edit_prompt("Updated marketing strategy with social media focus") - ``` - This method updates the prompt content and, if `autosave` is True, automatically saves the new version. - -3. **Retrieval**: - ```python - current_content = marketing_prompt.get_prompt() - ``` - This method returns the current content of the prompt. - -4. **Version History**: - ```python - print(f"Edit history: {marketing_prompt.edit_history}") - ``` - The class maintains a history of edits, allowing users to track changes over time. - -5. **Rollback**: - ```python - marketing_prompt.rollback(1) - ``` - This feature allows users to revert to a previous version of the prompt. - -6. **Duplicate Prevention**: - The class includes logic to prevent duplicate edits, raising a `ValueError` if an attempt is made to save the same content twice in a row. - -This system provides a powerful way to manage prompts, especially for complex projects where prompt engineering and iteration are crucial. - -## 3. Upcoming Features Preview - -### 3.1 Enhanced Agent Execution Capabilities - -The preview code demonstrates planned enhancements for agent execution: - -```python -from swarms import Agent, ExecutionEnvironment - -my_agent = Agent(name="data_processor") - -cpu_env = ExecutionEnvironment(type="cpu", cores=4) -my_agent.run(environment=cpu_env) - -gpu_env = ExecutionEnvironment(type="gpu", device_id=0) -my_agent.run(environment=gpu_env) - -fractional_env = ExecutionEnvironment(type="fractional", cpu_fraction=0.5, gpu_fraction=0.3) -my_agent.run(environment=fractional_env) -``` - -This upcoming feature will allow for more fine-grained control over the execution environment: - -1. **CPU Execution**: Users can specify the number of CPU cores to use. -2. **GPU Execution**: Allows selection of a specific GPU device. -3. **Fractionalized Execution**: Enables partial allocation of CPU and GPU resources. - -These features will provide users with greater flexibility in resource allocation, potentially improving performance and allowing for more efficient use of available hardware. \ No newline at end of file diff --git a/docs/swarms/changelog/6_0_0 2.md b/docs/swarms/changelog/6_0_0 2.md deleted file mode 100644 index aae2e8ef..00000000 --- a/docs/swarms/changelog/6_0_0 2.md +++ /dev/null @@ -1,59 +0,0 @@ -# Swarms 6.0.0 - Performance & Reliability Update 🚀 - -We're excited to announce the release of Swarms 6.0.0, bringing significant improvements to performance, reliability, and developer experience. This release focuses on streamlining core functionalities while enhancing the overall stability of the framework. - -## 📦 Installation - -```bash -pip3 install -U swarms -``` - -## 🌟 Highlights - -### Agent Enhancements -- **Improved RAG Performance**: Significant improvements to Retrieval-Augmented Generation capabilities -- **Enhanced Prompt Generation**: Auto-generate prompt now incorporates name, description, and system prompt for more contextual interactions -- **Streamlined Architecture**: Cleaned up unused code for better performance and maintainability -- **Simplified State Management**: Consolidated state management methods into a single `load()` function - -### Tools & Execution -- **Optimized Environment Management**: Fixed multiple environment instantiation issue - - Environments now initialize once during `__init__` -- **New SwarmRouter Function**: Simplified routing mechanism - - Returns consolidated string output from all agents - - Improved coordination between swarm components - -## 💪 Performance Improvements -- Faster execution times -- Reduced memory footprint -- More reliable logging system -- Lightweight and efficient codebase - -## 🤝 Join Our Community - -### We're Hiring! -Join our growing team! We're currently looking for: -- Agent Engineers -- Developer Relations -- Infrastructure Engineers -- And more! - -### Get Involved -- ⭐ Star our repository -- 🔄 Fork the project -- 🛠 Submit pull requests -- 🐛 Report issues -- 💡 Share your ideas - -### Contact & Support -- 📧 Email: kye@swarms.world -- 🔗 Issues: [GitHub Issues](https://github.com/kyegomez/swarms/issues) - -## 🔜 What's Next? -Have ideas for features, bug fixes, or improvements? We'd love to hear from you! Reach out through our GitHub issues or email us directly. - ---- - -*Thank you to all our contributors and users who make Swarms better every day. Together, we're building the future of swarm intelligence.* - -#SwarmAI #OpenSource #AI #MachineLearning \ No newline at end of file diff --git a/docs/swarms/changelog/6_0_0.md b/docs/swarms/changelog/6_0_0.md deleted file mode 100644 index aae2e8ef..00000000 --- a/docs/swarms/changelog/6_0_0.md +++ /dev/null @@ -1,59 +0,0 @@ -# Swarms 6.0.0 - Performance & Reliability Update 🚀 - -We're excited to announce the release of Swarms 6.0.0, bringing significant improvements to performance, reliability, and developer experience. This release focuses on streamlining core functionalities while enhancing the overall stability of the framework. - -## 📦 Installation - -```bash -pip3 install -U swarms -``` - -## 🌟 Highlights - -### Agent Enhancements -- **Improved RAG Performance**: Significant improvements to Retrieval-Augmented Generation capabilities -- **Enhanced Prompt Generation**: Auto-generate prompt now incorporates name, description, and system prompt for more contextual interactions -- **Streamlined Architecture**: Cleaned up unused code for better performance and maintainability -- **Simplified State Management**: Consolidated state management methods into a single `load()` function - -### Tools & Execution -- **Optimized Environment Management**: Fixed multiple environment instantiation issue - - Environments now initialize once during `__init__` -- **New SwarmRouter Function**: Simplified routing mechanism - - Returns consolidated string output from all agents - - Improved coordination between swarm components - -## 💪 Performance Improvements -- Faster execution times -- Reduced memory footprint -- More reliable logging system -- Lightweight and efficient codebase - -## 🤝 Join Our Community - -### We're Hiring! -Join our growing team! We're currently looking for: -- Agent Engineers -- Developer Relations -- Infrastructure Engineers -- And more! - -### Get Involved -- ⭐ Star our repository -- 🔄 Fork the project -- 🛠 Submit pull requests -- 🐛 Report issues -- 💡 Share your ideas - -### Contact & Support -- 📧 Email: kye@swarms.world -- 🔗 Issues: [GitHub Issues](https://github.com/kyegomez/swarms/issues) - -## 🔜 What's Next? -Have ideas for features, bug fixes, or improvements? We'd love to hear from you! Reach out through our GitHub issues or email us directly. - ---- - -*Thank you to all our contributors and users who make Swarms better every day. Together, we're building the future of swarm intelligence.* - -#SwarmAI #OpenSource #AI #MachineLearning \ No newline at end of file diff --git a/docs/swarms/changelog/changelog_new.md b/docs/swarms/changelog/changelog_new.md deleted file mode 100644 index adc92b02..00000000 --- a/docs/swarms/changelog/changelog_new.md +++ /dev/null @@ -1,90 +0,0 @@ -# 🚀 Swarms 5.9.2 Release Notes - - -### 🎯 Major Features - -#### Concurrent Agent Execution Suite -We're excited to introduce a comprehensive suite of agent execution methods to supercharge your multi-agent workflows: - -- `run_agents_concurrently`: Execute multiple agents in parallel with optimal resource utilization -- `run_agents_concurrently_async`: Asynchronous execution for improved performance -- `run_single_agent`: Streamlined single agent execution -- `run_agents_concurrently_multiprocess`: Multi-process execution for CPU-intensive tasks -- `run_agents_sequentially`: Sequential execution with controlled flow -- `run_agents_with_different_tasks`: Assign different tasks to different agents -- `run_agent_with_timeout`: Time-bounded agent execution -- `run_agents_with_resource_monitoring`: Monitor and manage resource usage - -### 📚 Documentation -- Comprehensive documentation added for all new execution methods -- Updated examples and usage patterns -- Enhanced API reference - -### 🛠️ Improvements -- Tree swarm implementation fixes -- Workspace directory now automatically set to `agent_workspace` -- Improved error handling and stability - -## Quick Start - -```python -from swarms import Agent, run_agents_concurrently, run_agents_with_timeout, run_agents_with_different_tasks - -# Initialize multiple agents -agents = [ - Agent( - agent_name=f"Analysis-Agent-{i}", - system_prompt="You are a financial analysis expert", - llm=model, - max_loops=1 - ) - for i in range(5) -] - -# Run agents concurrently -task = "Analyze the impact of rising interest rates on tech stocks" -outputs = run_agents_concurrently(agents, task) - -# Example with timeout -outputs_with_timeout = run_agents_with_timeout( - agents=agents, - task=task, - timeout=30.0, - batch_size=2 -) - -# Run different tasks -task_pairs = [ - (agents[0], "Analyze tech stocks"), - (agents[1], "Analyze energy stocks"), - (agents[2], "Analyze retail stocks") -] -different_outputs = run_agents_with_different_tasks(task_pairs) -``` - -## Installation -```bash -pip3 install -U swarms -``` - -## Coming Soon -- 🌟 Auto Swarm Builder: Automatically construct and configure entire swarms from a single task specification (in development) -- Auto Prompt Generator for thousands of agents (in development) - -## Community -We believe in the power of community-driven development. Help us make Swarms better! - -- ⭐ Star our repository: https://github.com/kyegomez/swarms -- 🔄 Fork the project and contribute your improvements -- 🤝 Join our growing community of contributors - -## Bug Fixes -- Fixed Tree Swarm implementation issues -- Resolved workspace directory configuration problems -- General stability improvements - ---- - -For detailed documentation and examples, visit our [GitHub repository](https://github.com/kyegomez/swarms). - -Let's build the future of multi-agent systems together! 🚀 \ No newline at end of file diff --git a/docs/swarms/structs/taskqueue_swarm.md b/docs/swarms/structs/taskqueue_swarm.md index c7bd89aa..4145e69a 100644 --- a/docs/swarms/structs/taskqueue_swarm.md +++ b/docs/swarms/structs/taskqueue_swarm.md @@ -51,14 +51,11 @@ Runs the swarm by having agents pick up tasks from the queue. - **Usage Example:** ```python from swarms import Agent, TaskQueueSwarm - from swarms_models import OpenAIChat - # Initialize the language model - llm = OpenAIChat() # Initialize agents - agent1 = Agent(agent_name="Agent1", llm=llm) - agent2 = Agent(agent_name="Agent2", llm=llm) + agent1 = Agent(agent_name="Agent1", model_name="gpt-4o") + agent2 = Agent(agent_name="Agent2", model_name="gpt-4o") # Create the TaskQueueSwarm swarm = TaskQueueSwarm(agents=[agent1, agent2], max_loops=5) diff --git a/examples/single_agent/rag/qdrant_agent.py b/examples/single_agent/rag/qdrant_agent.py index 71c65293..4222d1da 100644 --- a/examples/single_agent/rag/qdrant_agent.py +++ b/examples/single_agent/rag/qdrant_agent.py @@ -6,7 +6,6 @@ from typing import Dict, List, Optional from qdrant_client import QdrantClient from qdrant_client.http import models from qdrant_client.http.models import Distance, VectorParams -from swarm_models import Anthropic from swarms import Agent @@ -172,14 +171,14 @@ memory = QdrantMemory( ) # Model -model = Anthropic(anthropic_api_key=os.getenv("ANTHROPIC_API_KEY")) +# model = Anthropic(anthropic_api_key=os.getenv("ANTHROPIC_API_KEY")) # Initialize the agent with Qdrant memory agent = Agent( agent_name="Financial-Analysis-Agent", system_prompt="Agent system prompt here", agent_description="Agent performs financial analysis.", - llm=model, + model_name="gpt-4o-mini", long_term_memory=memory, ) diff --git a/swarms/structs/agent.py b/swarms/structs/agent.py index a61c43db..3f726d24 100644 --- a/swarms/structs/agent.py +++ b/swarms/structs/agent.py @@ -286,13 +286,13 @@ class Agent: Examples: >>> from swarms import Agent - >>> agent = Agent(llm=llm, max_loops=1, model_name="gpt-4o") + >>> agent = Agent(model_name="gpt-4o", max_loops=1) >>> response = agent.run("Generate a report on the financials.") >>> print(response) >>> # Generate a report on the financials. >>> # Real-time streaming example - >>> agent = Agent(llm=llm, max_loops=1, streaming_on=True) + >>> agent = Agent(model_name="gpt-4o", max_loops=1, streaming_on=True) >>> response = agent.run("Tell me a long story.") # Will stream in real-time >>> print(response) # Final complete response