diff --git a/docs/llm.txt b/docs/llm.txt index ce0b209b..5ccbf028 100644 --- a/docs/llm.txt +++ b/docs/llm.txt @@ -16,28420 +16,17537 @@ FAST -------------------------------------------------- -# File: applications\azure_openai.md - -# Deploying Azure OpenAI in Production: A Comprehensive Guide - -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: +# File: concepts\limitations.md -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`. +# Limitations of Individual Agents -## Setting up the Environment: -To kick things off, we'll set up our development environment and install the necessary dependencies. +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. -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. +## Overview -``` -python -m venv myenv +```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] ``` -2. **Activate the Virtual Environment**: Activate the virtual environment to ensure that any packages you install are isolated within the environment. +## 1. Context Window Limits -``` -source myenv/bin/activate # On Windows, use `myenv\Scripts\activate` +### The Challenge +Individual agents are constrained by fixed context windows, limiting their ability to process large amounts of information simultaneously. + +```mermaid +graph LR + subgraph "Context Window Limitation" + Input[Large Document] --> Truncation[Truncation] + Truncation --> ProcessedPart[Processed Part] + Truncation --> UnprocessedPart[Unprocessed Part] + end ``` -3. **Install Required Packages**: Install the `python-dotenv` and `swarms` packages using pip. +### Impact +- Limited understanding of large documents +- Fragmented processing of long conversations +- Inability to maintain extended context +- Loss of important information -``` -pip install python-dotenv swarms -``` +## 2. Hallucination -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. +### The Challenge +Individual agents may generate plausible-sounding but incorrect information, especially when dealing with ambiguous or incomplete data. -``` -AZURE_OPENAI_ENDPOINT= -AZURE_OPENAI_DEPLOYMENT= -OPENAI_API_VERSION= -AZURE_OPENAI_API_KEY= -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 ``` -Replace the placeholders with your actual Azure OpenAI credentials and configuration settings. - -## 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 +- Unreliable information generation +- Reduced trust in system outputs +- Potential for misleading decisions +- Need for extensive verification -```python -import os -from dotenv import load_dotenv -from swarms import AzureOpenAI +## 3. Single Task Execution -# Load the environment variables -load_dotenv() +### The Challenge +Most individual agents are optimized for specific tasks and struggle with multi-tasking or adapting to new requirements. -# 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 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] ``` -## Let's break down this code: - -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. - -2. **Load Environment Variables**: We use `load_dotenv()` to load the environment variables stored in the `.env` file we created earlier. - -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: +## Best Practices for Mitigation -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. +1. **Use Multi-Agent Systems** + - Distribute tasks across agents + - Enable parallel processing + - Implement cross-validation + - Foster collaboration -2. **Error Handling and Retries**: Implement robust error handling and retry mechanisms to handle potential failures or rate-limiting scenarios. +2. **Implement Verification** + - Cross-check results + - Use consensus mechanisms + - Monitor accuracy metrics + - Track performance -3. **Logging and Monitoring**: Implement comprehensive logging and monitoring strategies to track application performance, identify issues, and gather insights for optimization. +3. **Optimize Resource Usage** + - Balance load distribution + - Cache frequent operations + - Implement efficient queuing + - Monitor system health -4. **Scalability and Load Testing**: Conduct load testing to ensure your application can handle anticipated traffic volumes and scale appropriately based on demand. +## Conclusion -5. **Caching and Optimization**: Explore caching strategies and performance optimizations to improve response times and reduce the load on the Azure OpenAI service. +Understanding these limitations is crucial for: +- Designing robust multi-agent systems +- Implementing effective mitigation strategies +- Optimizing system performance +- Ensuring reliable outputs -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. +The next section explores how [Multi-Agent Architecture](architecture.md) addresses these limitations through collaborative approaches and specialized agent roles. -7. **Compliance and Security**: Ensure your application adheres to relevant compliance standards and security best practices, especially when handling sensitive data. +-------------------------------------------------- -## 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. +# File: contributors\docs.md -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. +# Contributing to Swarms Documentation -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. +--- --------------------------------------------------- +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. -# File: applications\blog.md +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. -# The Future of Manufacturing: Leveraging Autonomous LLM Agents for Cost Reduction and Revenue Growth +--- -## Table of Contents +## 1. Introduction -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) +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. -## 1. Introduction +**Objectives of this Guide:** -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. -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. +- Define a standardized contribution workflow for Swarms documentation. -## 2. Understanding Autonomous LLM Agents +- Clarify documentation roles, responsibilities, and submission expectations. -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. +- Establish quality benchmarks, review procedures, and formatting rules. -Key features of autonomous LLM agents include: +- Introduce the Swarms Documentation Bounty Program to incentivize excellence. -1. **Natural Language Processing (NLP)**: They can understand and generate human-like text, enabling seamless communication with employees across all levels of the organization. +--- -2. **Contextual Understanding**: These agents can grasp complex scenarios and nuanced information, making them ideal for handling intricate manufacturing processes. +## 2. Why Documentation Is a Strategic Asset -3. **Adaptive Learning**: Through continuous interaction and feedback, they can improve their performance over time, becoming more efficient and accurate. +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. -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. +By treating documentation as a core product component, we ensure continuity, scalability, and user satisfaction. -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. +--- -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. Understanding the Swarms Ecosystem -## 3. RAG Embedding Databases: The Knowledge Foundation +The Swarms ecosystem consists of multiple tightly integrated components that serve developers and enterprise clients alike: -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. -RAG embedding databases work by: +- **Core Documentation Repository**: The main documentation hub for all Swarms technologies [GitHub](https://github.com/kyegomez/swarms). -1. **Vectorizing Information**: Converting textual data into high-dimensional vectors that capture semantic meaning. +- **Rust SDK (`swarms_rs`)**: Official documentation for the Rust implementation. [Repo](https://github.com/The-Swarm-Corporation/swarms-rs). -2. **Efficient Storage**: Organizing these vectors in a way that allows for rapid retrieval of relevant information. +- **Tools Documentation (`swarms_tools`)**: Guides for CLI and GUI utilities. -3. **Contextual Retrieval**: Enabling the agent to pull relevant information based on the current context or query. +- **Hosted API Reference**: Up-to-date REST API documentation: [Swarms API Docs](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/). -4. **Dynamic Updates**: Allowing for continuous updates to the knowledge base, ensuring the agent always has access to the most current information. +- **Marketplace & Chat**: Web platforms and communication interfaces [swarms.world](https://swarms.world). -In the manufacturing context, RAG embedding databases can store a wealth of information, including: +All contributions funnel through the `docs/` directory in the core repo and are structured via MkDocs. -- 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 +--- -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. +## 4. Documentation Tools and Platforms -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. +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. Function Calling and External Tools: Enhancing Capabilities +- **Markdown**: For formatting structure, code snippets, lists, and links. -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. +- **MkDocs Configuration**: `mkdocs.yml` manages structure, theme, and navigation. -Function calling allows the agent to: +- **Version Control**: GitHub for branching, version tracking, and collaboration. -1. **Execute Specific Tasks**: Trigger predefined functions to perform complex operations or calculations. +**Recommended Tooling:** -2. **Interact with Databases**: Query and update various databases within the manufacturing ecosystem. +- Markdown linters to enforce syntax consistency. -3. **Control Equipment**: Send commands to machinery or robotic systems on the production floor. +- Spellcheckers to ensure grammatical accuracy. -4. **Generate Reports**: Automatically compile and format data into meaningful reports for different stakeholders. +- Doc generators for automated API reference extraction. -External tools that can be integrated include: +--- -- **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. +## 5. Getting Started with Contributions -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.1 System Requirements -For instance, an autonomous agent could: -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. +- **Git** v2.30 or higher -This level of integration and automation can lead to significant improvements in operational efficiency, cost reduction, and overall productivity. +- **Node.js** and **npm** for related dependency management -## 5. Cost Reduction Strategies +- **MkDocs** and **Material for MkDocs** theme (`pip install mkdocs mkdocs-material`) -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: +- A GitHub account with permissions to fork and submit pull requests -### 5.1. Optimizing Supply Chain Management +### 5.2 Forking the Swarms Repository -Autonomous LLM agents can revolutionize supply chain management by: +1. Visit: `https://github.com/kyegomez/swarms` -- **Predictive Inventory Management**: Analyzing historical data, market trends, and production schedules to optimize inventory levels, reducing carrying costs and minimizing stockouts. +2. Click on **Fork** to create your version of the repository -- **Supplier Selection and Negotiation**: Evaluating supplier performance, market conditions, and contract terms to recommend the most cost-effective suppliers and negotiate better deals. +### 5.3 Clone and Configure Locally -- **Logistics Optimization**: Analyzing transportation routes, warehouse locations, and delivery schedules to minimize logistics costs and improve delivery times. +```bash +git clone https://github.com//swarms.git +cd swarms/docs +git checkout -b feature/docs- +``` -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. +--- -### 5.2. Enhancing Quality Control +## 6. Understanding the Repository Structure -Quality control is a critical aspect of manufacturing that directly impacts costs. Autonomous LLM agents can significantly improve quality control processes by: +Explore the documentation directory: -- **Real-time Defect Detection**: Integrating with computer vision systems to identify and classify defects in real-time, reducing waste and rework. +```text +docs/ +├── index.md +├── mkdocs.yml +├── swarms_rs/ +│ ├── overview.md +│ └── ... +└── swarms_tools/ + ├── install.md + └── ... +``` -- **Root Cause Analysis**: Analyzing production data to identify the root causes of quality issues and recommending corrective actions. +### 6.1 SDK/Tools Directories -- **Predictive Quality Management**: Leveraging historical data and machine learning models to predict potential quality issues before they occur. +- **Rust SDK (`docs/swarms_rs`)**: Guides, references, and API walkthroughs for the Rust-based implementation. -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. +- **Swarms Tools (`docs/swarms_tools`)**: CLI guides, GUI usage instructions, and architecture documentation. -### 5.3. Streamlining Maintenance and Repairs -Effective maintenance is crucial for minimizing downtime and extending the lifespan of expensive manufacturing equipment. Autonomous LLM agents can optimize maintenance processes by: +Add new `.md` files in the folder corresponding to your documentation type. -- **Predictive Maintenance**: Analyzing equipment sensor data, maintenance history, and production schedules to predict when maintenance is needed, reducing unplanned downtime. +### 6.2 Configuring Navigation in MkDocs -- **Maintenance Scheduling Optimization**: Balancing maintenance needs with production schedules to minimize disruptions and maximize equipment availability. +Update `mkdocs.yml` to integrate your new document: -- **Repair Knowledge Management**: Creating and maintaining a comprehensive knowledge base of repair procedures, making it easier for technicians to quickly address issues. +```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 +``` -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. +--- -### 5.4. Improving Energy Efficiency +## 7. Writing and Editing Documentation -Energy consumption is a significant cost factor in manufacturing. Autonomous LLM agents can help reduce energy costs by: +### 7.1 Content Standards -- **Real-time Energy Monitoring**: Analyzing energy consumption data across the facility to identify inefficiencies and anomalies. -- **Process Optimization for Energy Efficiency**: Recommending changes to production processes to reduce energy consumption without impacting output. +- **Clarity**: Explain complex ideas in simple, direct language. -- **Demand Response Management**: Integrating with smart grid systems to optimize energy usage based on variable electricity prices and demand. +- **Style Consistency**: Match the tone and structure of existing docs. -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. +- **Accuracy**: Validate all technical content and code snippets. -## 6. Revenue Growth Opportunities +- **Accessibility**: Include alt text for images and use semantic Markdown. -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: +### 7.2 Markdown Best Practices -### 6.1. Product Innovation and Development +- Sequential heading levels (`#`, `##`, `###`) -Autonomous LLM agents can accelerate and enhance the product innovation process by: +- Use fenced code blocks with language identifiers -- **Market Trend Analysis**: Analyzing vast amounts of market data, customer feedback, and industry reports to identify emerging trends and unmet needs. +- Create readable line spacing and avoid unnecessary line breaks -- **Design Optimization**: Leveraging generative design techniques and historical performance data to suggest optimal product designs that balance functionality, manufacturability, and cost. -- **Rapid Prototyping Assistance**: Guiding engineers through the prototyping process, suggesting materials and manufacturing techniques based on design requirements and cost constraints. +### 7.3 File Placement Protocol -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. +Place `.md` files into the correct subdirectory: -### 6.2. Personalized Customer Experiences -In the age of mass customization, providing personalized experiences can significantly boost customer satisfaction and revenue. Autonomous LLM agents can facilitate this by: +- **Rust SDK Docs**: `docs/swarms_rs/` -- **Customer Preference Analysis**: Analyzing historical purchase data, customer interactions, and market trends to predict individual customer preferences. +- **Tooling Docs**: `docs/swarms_tools/` -- **Dynamic Product Configuration**: Enabling real-time product customization based on customer inputs and preferences, while ensuring manufacturability. +--- -- **Personalized Marketing and Sales Support**: Generating tailored marketing content and sales recommendations for each customer or market segment. +## 8. Updating Navigation Configuration -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. +After writing your content: -### 6.3. Market Analysis and Trend Prediction +1. Open `mkdocs.yml` +2. Identify where your file belongs +3. Add it to the `nav` hierarchy +4. Preview changes: -Staying ahead of market trends is crucial for maintaining a competitive edge. Autonomous LLM agents can provide valuable insights by: +```bash +mkdocs serve +# Open http://127.0.0.1:8000 to verify output +``` -- **Competitive Intelligence**: Analyzing competitor activities, product launches, and market positioning to identify threats and opportunities. +--- -- **Demand Forecasting**: Combining historical sales data, economic indicators, and market trends to predict future demand more accurately. +## 9. Workflow: Branches, Commits, Pull Requests -- **Emerging Market Identification**: Analyzing global economic data, demographic trends, and industry reports to identify promising new markets for expansion. +### 9.1 Branch Naming Guidelines -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. +- Use prefix and description, e.g.: + - `feature/docs-api-pagination` -### 6.4. Optimizing Pricing Strategies + - `fix/docs-typo-tooling` -Pricing is a critical lever for revenue growth. Autonomous LLM agents can optimize pricing strategies by: +### 9.2 Writing Clear Commits -- **Dynamic Pricing Models**: Analyzing market conditions, competitor pricing, and demand fluctuations to suggest optimal pricing in real-time. +Follow [Conventional Commits](https://www.conventionalcommits.org/): -- **Value-based Pricing Analysis**: Assessing customer perceived value through sentiment analysis and willingness-to-pay studies to maximize revenue. +```bash +docs(swarms_rs): add stream API tutorial +docs(swarms_tools): correct CLI usage example +``` -- **Bundle and Discount Optimization**: Recommending product bundles and discount structures that maximize overall revenue and profitability. +### 9.3 Submitting a Pull Request -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. +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`) -## 7. Implementation Strategies +--- -Successfully implementing autonomous LLM agents in a manufacturing environment requires a strategic approach. Here are key steps and considerations for executives and CEOs: +## 10. Review, QA, and Merging -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. +Every PR undergoes automated and human review: -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. +- **CI Checks**: Syntax validation, link checking, and formatting -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. +- **Manual Review**: Maintain clarity, completeness, and relevance -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. +- **Iteration**: Collaborate through feedback and finalize changes -5. **Invest in Data Infrastructure and Quality**: - - Ensure robust data collection and storage systems are in place. - - Implement data cleaning and standardization processes. +Once approved, maintainers will merge and deploy the updated documentation. +--- +## 11. Swarms Documentation Bounty Initiative -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. +To foster continuous improvement, we offer structured rewards for eligible contributions: -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. +### 11.1 Contribution Types -8. **Prioritize Security and Compliance**: - - Implement strong data encryption and access control measures. - - Ensure compliance with industry regulations and data privacy laws. -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. +- Creating comprehensive new tutorials and deep dives -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. +- Updating outdated references and examples -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. +- Fixing typos, grammar, and formatting errors -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. +- Translating existing content -## 8. Overcoming Challenges and Risks +### 11.2 Reward Structure -While the benefits of autonomous LLM agents in manufacturing are substantial, there are several challenges and risks that executives must address: +| 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 | -### Data Quality and Availability +### 11.3 Claiming Bounties -**Challenge**: Manufacturing environments often have siloed, inconsistent, or incomplete data, which can hinder the effectiveness of AI systems. +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) -**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. +--- -### Integration with Legacy Systems +## 12. Best Practices for Efficient Contribution -**Challenge**: Many manufacturing facilities rely on legacy systems that may not easily integrate with modern AI technologies. +- **Stay Updated**: Sync your fork weekly to avoid merge conflicts -**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. +- **Atomic PRs**: Submit narrowly scoped changes for faster review -### Workforce Adaptation and Resistance +- **Use Visuals**: Support documentation with screenshots or diagrams -**Challenge**: Employees may resist AI implementation due to fear of job displacement or lack of understanding. +- **Cross-Reference**: Link to related documentation for completeness -**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. +- **Version Awareness**: Specify SDK/tool versions in code examples -### Ethical Considerations and Bias +--- -**Challenge**: AI systems may inadvertently perpetuate biases present in historical data or decision-making processes. +## 13. Style Guide Snapshot -**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. -### Security and Intellectual Property Protection +- **Voice**: Informative, concise, and respectful -**Challenge**: AI systems may be vulnerable to cyber attacks or could potentially expose sensitive manufacturing processes. +- **Terminology**: Use standardized terms (`Swarm`, `Swarms`) consistently -**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. +- **Code**: Format snippets using language-specific linters -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. +- **Accessibility**: Include alt attributes and avoid ambiguous links -## 9. Case Studies +--- -To illustrate the transformative potential of autonomous LLM agents in manufacturing, let's examine several real-world case studies: +## 14. Monitoring & Improving Documentation Health -### Case Study 1: Global Electronics Manufacturer +We use analytics and community input to prioritize improvements: -**Challenge**: A leading electronics manufacturer was struggling with supply chain disruptions and rising production costs. +- **Traffic Reports**: Track most/least visited pages -**Solution**: They implemented an autonomous LLM agent integrated with their supply chain management system and production planning tools. +- **Search Logs**: Detect content gaps from common search terms -**Results**: -- 22% reduction in inventory carrying costs -- 18% improvement in on-time deliveries -- 15% decrease in production lead times -- $200 million annual cost savings +- **Feedback Forms**: Collect real-world user input -**Key Factors for Success**: -- Comprehensive integration with existing systems -- Real-time data processing capabilities -- Continuous learning and optimization algorithms +Schedule quarterly audits to refine structure and content across all repositories. -### Case Study 2: Automotive Parts Supplier +--- -**Challenge**: An automotive parts supplier needed to improve quality control and reduce warranty claims. +## 15. Community Promotion & Engagement -**Solution**: They deployed an AI-powered quality control system using computer vision and an autonomous LLM agent for defect analysis and prediction. +Promote your contributions via: -**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 -**Key Factors for Success**: -- High-quality image data collection system -- Integration of domain expertise into the AI model -- Continuous feedback loop for model improvement +- **Swarms Discord**: https://discord.gg/jM3Z6M9uMq -### Case Study 3: Food and Beverage Manufacturer +- **Swarms Telegram**: https://t.me/swarmsgroupchat -**Challenge**: A large food and beverage manufacturer wanted to optimize its energy consumption and reduce waste in its production processes. +- **Swarms Twitter**: https://x.com/swarms_corp -**Solution**: They implemented an autonomous LLM agent that integrated with their energy management systems and production equipment. +- **Startup Program Showcases**: https://www.swarms.xyz/programs/startups -**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 +Active contributors are often spotlighted for leadership roles and community awards. -**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 +--- -### Case Study 4: Aerospace Component Manufacturer +## 16. Resource Index -**Challenge**: An aerospace component manufacturer needed to accelerate product development and improve first-time-right rates for new designs. +- Core GitHub Repo: https://github.com/kyegomez/swarms -**Solution**: They implemented an autonomous LLM agent to assist in the design process, leveraging historical data, simulation results, and industry standards. +- Rust SDK Repo: https://github.com/The-Swarm-Corporation/swarms-rs -**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 +- Swarms API Docs: https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/ -**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 +- Marketplace: https://swarms.world -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. +Join our monthly Documentation Office Hours for real-time mentorship and Q&A. -## 10. Future Outlook +--- -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: +## 17. Frequently Asked Questions -### 1. Advanced Natural Language Interfaces +**Q1: Is MkDocs required to contribute?** +A: It's recommended but not required; Markdown knowledge is sufficient to get started. -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. +**Q2: Can I rework existing sections?** +A: Yes, propose changes via issues first, or submit PRs with clear descriptions. -### 2. Enhanced Multi-modal Learning +**Q3: When are bounties paid?** +A: Within 30 days of merge, following internal validation. -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. +--- -### 3. Collaborative AI Systems +## 18. Final Thoughts -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. +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. -### 4. Quantum-enhanced AI +We look forward to your pull requests, feedback, and ideas. -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. +--- -### 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 +# File: contributors\environment_setup.md -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. +# Environment Setup Guide for Swarms Contributors -### 7. Ethical AI and Explainable Decision-Making +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. -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. +!!! 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! -### 8. Circular Economy Optimization +!!! 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 + ``` -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. +--- -To stay ahead in this rapidly evolving landscape, manufacturing executives should: +## :material-list-status: Prerequisites -1. **Foster a Culture of Innovation**: Encourage experimentation with new AI technologies and applications. +Before setting up your development environment, ensure you have the following installed: -2. **Invest in Continuous Learning**: Ensure your workforce is constantly upskilling to work effectively with advanced AI systems. +### System Requirements -3. **Collaborate with AI Research Institutions**: Partner with universities and research labs to stay at the forefront of AI advancements in manufacturing. +| 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) | -4. **Participate in Industry Consortiums**: Join manufacturing technology consortiums to share knowledge and shape industry standards for AI adoption. +### Operating System Support -5. **Develop Flexible and Scalable AI Infrastructure**: Build systems that can easily incorporate new AI capabilities as they emerge. +=== "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 + ``` -6. **Monitor Regulatory Developments**: Stay informed about evolving regulations related to AI in manufacturing to ensure compliance and competitive advantage. +=== "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 + ``` -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. +=== "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 - + ``` -## 11. Conclusion +--- -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. +## :material-auto-fix: Automated Setup (Recommended) -Key takeaways for executives and CEOs: +We provide a comprehensive setup script that automates the entire development environment setup process. This is the **recommended approach** for new contributors. -1. **Transformative Potential**: Autonomous LLM agents can impact every aspect of manufacturing, from supply chain optimization to product innovation. +### What the Setup Script Does -2. **Data-Driven Decision Making**: These AI systems enable more informed, real-time decision-making based on comprehensive data analysis. +The `scripts/setup.sh` script automatically handles: -3. **Competitive Advantage**: Early adopters of this technology are likely to gain significant competitive advantages in terms of efficiency, quality, and innovation. +- ✅ **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 -4. **Holistic Implementation**: Success requires a strategic approach that addresses technology, processes, and people. +### Running the Automated Setup -5. **Continuous Evolution**: The field of AI in manufacturing is rapidly advancing, necessitating ongoing investment and adaptation. +```bash +# Clone the repository +git clone https://github.com/kyegomez/swarms.git +cd swarms -6. **Ethical Considerations**: As AI becomes more prevalent, addressing ethical concerns and maintaining transparency will be crucial. +# Make the script executable and run it +chmod +x scripts/setup.sh +./scripts/setup.sh +``` -7. **Future Readiness**: Preparing for future developments, such as quantum-enhanced AI and autonomous factories, will be key to long-term success. +### Script Features -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. +=== "🎯 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 -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. +=== "🔧 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 + ``` -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. +=== "📋 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 + ``` --------------------------------------------------- +=== "💡 Helpful Guidance" + Provides next steps and useful commands: + - How to activate the virtual environment + - Essential Poetry commands + - Testing and development workflow + - Troubleshooting tips -# File: applications\business-analyst-agent.md +### When to Use Manual Setup -## Building Analyst Agents with Swarms to write Business Reports +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 -> 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) +--- -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: +## :material-git: Repository Setup -- 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. +### Step 1: Fork and Clone -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. +1. **Fork the repository** on GitHub: [github.com/kyegomez/swarms](https://github.com/kyegomez/swarms) -- **[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` +2. **Clone your fork**: +```bash +git clone https://github.com/YOUR_USERNAME/swarms.git +cd swarms +``` -```python -import dotenv -dotenv.load_dotenv() # Load environment variables from .env file +3. **Add upstream remote**: +```bash +git remote add upstream https://github.com/kyegomez/swarms.git ``` -### Developing an Outline to solve the problem +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) +``` -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. +--- +## :material-package-variant: Dependency Management -#### Step 1. Defining the Data Model and Tool Schema - -Using Pydantic, we define a structure to help the agent generate sub-problems. - -- **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() +--- -memory = ChromaDB( - metric="cosine", - n_results=3, - output_dir="results", - embedding_function=default_ef -) -``` +## :material-bug: Troubleshooting -#### Step 6. Defining Worker Agents +!!! 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. -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. +### Common Issues and Solutions -```python -class WorkerAgent(Agent): - def __init__(self, *args, **kwargs): - super().__init__(*args, **kwargs) +=== "Poetry Issues" - def run(self, task, *args, **kwargs): - response = super().run(task, *args, **kwargs) - print(response.content) - - json_dict = json.loads(process_json_output(response.content)) - - #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"] + **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 + ``` - if tool_name not in ['browser', 'kay_retriever']: - continue - - query = command["args"]["query"] +=== "Python Version Issues" + + **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 + ``` - # Get the tool by its name - tool = globals()[tool_name] - tool_response = tool(query) +=== "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 . + ``` - # Add tool's output to long term memory - self.long_term_memory.add(tool_response) -``` +=== "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 + ``` -We can then instantiate an object of the `WorkerAgent` class. +### Getting Help -```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, -) -``` +If you encounter issues: -#### Step 7. Running the Worker Agents +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 -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. +## :material-next-step: Next Steps -![Query Plan Mini](../assets/img/docs/query-plan-mini.png) +Now that your environment is set up: -Below is the code that produces the order of processing sub-queries. - -```python -from collections import deque, defaultdict +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 -# Define the graph nodes -nodes = json_object['sub_queries'] +!!! 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. -# Create a graph from the nodes -graph = defaultdict(list) -for node in nodes: - for dependency in node['dependencies']: - graph[dependency].append(node['id']) +--- -# Find all nodes with no dependencies (potential starting points) -start_nodes = [node['id'] for node in nodes if not node['dependencies']] +## :material-bookmark-outline: Quick Reference -# Adjust the BFT function to handle dependencies correctly -def bft_corrected(start, graph, nodes_info): - visited = set() - queue = deque([start]) - order = [] - - 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) - - return order +### Essential Commands -# Dictionary to access node information quickly -nodes_info = {node['id']: node for node in nodes} +```bash +# Setup (choose one) +./scripts/setup.sh # Automated setup (recommended) +poetry install --with dev # Manual dependency install -# Perform BFT for each unvisited start node using the corrected BFS function -visited_global = set() -bfs_order = [] +# Daily workflow +poetry shell # Activate environment +poetry run pytest # Run tests +poetry run black swarms/ # Format code +poetry run ruff check swarms/ # Lint code -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) +# 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 -print("BFT Order:", bfs_order) +# Documentation +cd docs && mkdocs serve # Serve docs locally +mkdocs build # Build docs ``` -This produces the following output. +### Project Structure -```python -BFT Order: ['1', '6', '10', '2', '3', '4', '5', '7', '8', '9'] +``` +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 ``` -Now, let's define our `ConcurrentWorkflow` and run it. +Happy coding! 🚀 -```python -import os -from dotenv import load_dotenv -from swarms import Agent, ConcurrentWorkflow, OpenAIChat, Task +-------------------------------------------------- -# Create a workflow -workflow = ConcurrentWorkflow(max_workers=5) -task_list = [] +# File: contributors\main.md -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) +# Contributing to Swarms: Building the Infrastructure for The Agentic Economy -workflow.add(tasks=task_list) +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. -# Run the workflow -workflow.run() -``` +!!! 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. -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"`. +### What You're Building -```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 +=== "Autonomous Systems" + **Autonomous Resource Allocation** + + Global supply chains and energy distribution optimized in real-time -{ - "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" - } - } -} +=== "Intelligence Networks" + **Distributed Decision Making** + + Collaborative intelligence networks across industries and governments ------------------ -Document added successfully ------------------ -... -... -``` +=== "Smart Markets" + **Self-Organizing Markets** + + Agent-driven marketplaces that automatically balance supply and demand -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`. +=== "Problem Solving" + **Collaborative Problem Solving** + + Massive agent swarms tackling climate change, disease, and scientific discovery +=== "Infrastructure" + **Adaptive Infrastructure** + + Self-healing systems that evolve without human intervention -#### Step 7. Generating the report using Writer Agent +--- -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. +## Why Contribute to Swarms? -```python -from swarms import Agent, OpenAIChat, tool +### :material-rocket-launch: Shape the Future of Civilization -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, -) -``` +!!! 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 -The report individual sections of the report will be collected in a list. +### :material-trophy: Recognition and Professional Development -```python -report = [] -``` +!!! 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 + +!!! 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 -Let us now run the writer agent. +### :material-brain: Technical Expertise Development -```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 -``` +Master cutting-edge technologies: -Now, we need to clean up the repoort a bit to make it render professionally. +| 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 | -```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 +### :material-account-group: Research Community Access -# At times the LLM outputs \\n instead of \n -cleaned_report = [entry.replace("\\n", "\n") for entry in report] -import re +!!! 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 -# 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 +--- -# Apply the cleaning function to the markdown report -cleaned_report = clean_report(cleaned_report) -``` +## Contribution Opportunities -After cleaning, we append parts of the report together to get out final report. +=== "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 -```python -final_report = ' \n '.join(cleaned_report) -``` +=== "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 -In Jupyter Notebook, we can use the below code to render it in Markdown. +=== "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 -```python -from IPython.display import display, Markdown +--- -display(Markdown(final_report)) -``` +## How to Contribute +### Step 1: Get Started -## Final Generated Report +!!! 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 } +### Step 2: Find Your Path -### Nike's Current Revenue Trend +```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] +``` -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 +### Step 3: Make Impact -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. +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 -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. +## Recognition Framework -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. +### :material-flash: Immediate Benefits -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 +!!! 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 | -1. **Supply Chain Optimization**: Streamlining the supply chain, reducing transportation costs, and improving inventory management can lead to significant cost savings for Nike. +### :material-trending-up: Long-term Opportunities -2. **Operational Efficiency**: Implementing lean manufacturing practices, reducing waste, and optimizing production processes can help lower production costs and improve overall efficiency. +!!! 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 -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. +## Societal Impact -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. +!!! abstract "Building Solutions for Humanity" + Swarms enables technology that addresses critical challenges: -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 + === "Research" + **Scientific Research** + + Accelerate collaborative research and discovery across disciplines -1. **Sustainable Fashion**: Consumers are increasingly demanding eco-friendly and sustainable products, leading to a rise in sustainable sportswear options in the market. + === "Healthcare" + **Healthcare Innovation** + + Support drug discovery and personalized medicine development -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. + === "Environment" + **Environmental Solutions** + + Monitor climate and optimize sustainability initiatives -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. + === "Education" + **Educational Technology** + + Create adaptive learning systems for personalized education -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. + === "Economy" + **Economic Innovation** + + Generate new opportunities and efficiency improvements -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. +--- -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 +## Get Involved -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. +### :material-link: Connect With Us -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. +!!! 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 } -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. +--- -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. +!!! 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. -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. +!!! success "Your Mission" + Your contribution to Swarms helps create the foundation for billions of autonomous agents working together to solve humanity's greatest challenges. -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 + **Join us in building the most important technology of our time.** -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. +--- -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. +
+*Built with :material-heart: by the global Swarms community* +
-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. +-------------------------------------------------- -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. +# File: contributors\tools.md -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 +# Contributing Tools and Plugins to the Swarms Ecosystem -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. +## Introduction -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. +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. -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. +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. -4. **Personalization**: Customization options, personalized fit, and unique design elements are appealing to consumers who seek individuality and exclusivity in their sports 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. -5. **Brand Transparency**: Consumers value transparency in brand practices, including supply chain transparency, ethical sourcing, and clear communication on product quality and manufacturing processes. +## Repository Architecture -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 +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: -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. +- `finance/`: Market analytics, stock price retrievers, blockchain APIs, etc. -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. +- `social/`: Sentiment analysis, engagement tracking, and media scraping utilities. -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. +- `health/`: Interfaces for EHR systems, wearable device APIs, or health informatics. -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. +- `ai/`: Model-serving utilities, embedding services, and prompt engineering functions. -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. +- `security/`: Encryption libraries, risk scoring tools, penetration test interfaces. -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 +- `devtools/`: Build tools, deployment utilities, code quality analyzers. -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. +- `misc/`: General-purpose helpers or utilities that serve multiple domains. -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. +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. -3. **Customization Platforms**: Offering personalized design options for footwear and apparel through online customization platforms could appeal to consumers seeking unique and tailored products. +## Tool Development Specifications -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. +To ensure long-term maintainability and smooth agent-tool integration, each contribution must strictly follow the specifications below. -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. +### 1. Function Structure and API Usage -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 +```python +import requests +import os -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. +def fetch_data(symbol: str, date_range: str) -> str: + """ + Fetch financial data for a given symbol and date range. -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. + Args: + symbol (str): Ticker symbol of the asset. + date_range (str): Timeframe for the data (e.g., '1d', '1m', '1y'). -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. + 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. **Localized Marketing**: Tailoring marketing messages, promotions, and product offerings to specific regions or target demographics can enhance relevance and appeal to diverse consumer groups. +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. **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. +### 2. Type Hints and Input Validation -By employing these marketing strategies in Q3 2024, Nike can enhance its brand presence, attract new customers, and ultimately boost revenue growth. +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 +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. +### 4. API Key Management Best Practices +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. Documentation Guidelines +Every tool must include a detailed docstring that describes: +- The function's purpose and operational scope +- All parameter types and formats +- A clear return type +- Usage examples or sample inputs/outputs +Example usage: +```python +result = fetch_data("AAPL", "1m") +print(result) +``` +Well-documented code accelerates adoption and improves LLM interpretability. --------------------------------------------------- +## Contribution Workflow -# File: applications\customer_support.md +To submit a tool, follow the workflow below. This ensures your code integrates cleanly and is easy for maintainers to review. -## **Applications of Swarms: Revolutionizing Customer Support** +### 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. ---- +### Step 2: Clone Your Fork +```bash +git clone https://github.com/YOUR_USERNAME/swarms-tools.git +cd swarms-tools +``` -**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. +### Step 3: Create a Feature Branch ---- +```bash +git checkout -b feature/add-tool- +``` -### **The Benefits of Using Swarms for Customer Support:** +Use descriptive branch names. This is especially helpful when collaborating in teams or maintaining audit trails. -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. +### 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. -### **Features - Reinventing Customer Support**: +### 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. -- **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. +### Step 6: Commit Your Changes ---- +```bash +git add . +git commit -m "Add under : API-based tool for X" +``` -**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. +### Step 7: Push to GitHub -**Experience the future of customer support. Dive into the swarm revolution.** +```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) --------------------------------------------------- +--- -# File: applications\marketing_agencies.md +## Integration with Swarms Agents -## **Swarms in Marketing Agencies: A New Era of Automated Media Strategy** +Once your tool has been merged into the official repository, it can be utilized by Swarms agents as part of their available capabilities. ---- +The example below illustrates how to embed a newly added tool into an autonomous agent: -### **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. +```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", +) -### **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. +agent.run("Create a new file for a plan to take over the world.") +``` ---- +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. -### **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. +This agent-tool paradigm enables highly flexible and responsive behavior across workflows involving research, automation, financial analysis, social listening, and more. --- -### **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. +## Tool Maintenance and Long-Term Ownership ---- +Contributors are expected to uphold the quality of their tools post-merge. This includes: -### **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. +- Monitoring for issues or bugs reported by the community ---- +- Updating tools when APIs deprecate or modify their behavior -### **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* +- Improving efficiency, error handling, or documentation over time ---- +If a tool becomes outdated or unsupported, maintainers may archive or revise it to maintain ecosystem integrity. -### **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. +Contributors whose tools receive wide usage or demonstrate excellence in design may be offered elevated privileges or invited to maintain broader tool categories. --- --------------------------------------------------- +## Best Practices for Enterprise-Grade Contributions -# File: concepts\limitations.md +To ensure your tool is production-ready and enterprise-compliant, observe the following practices: -# Limitations of Individual Agents -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. +- Run static type checking with `mypy` -## Overview +- Use formatters like `black` and linters such as `flake8` -```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] -``` +- Avoid unnecessary external dependencies -## 1. Context Window Limits +- Keep functions modular and readable -### The Challenge -Individual agents are constrained by fixed context windows, limiting their ability to process large amounts of information simultaneously. +- Prefer named parameters over positional arguments for clarity -```mermaid -graph LR - subgraph "Context Window Limitation" - Input[Large Document] --> Truncation[Truncation] - Truncation --> ProcessedPart[Processed Part] - Truncation --> UnprocessedPart[Unprocessed Part] - end -``` +- Handle API errors gracefully and return user-friendly messages -### Impact -- Limited understanding of large documents -- Fragmented processing of long conversations -- Inability to maintain extended context -- Loss of important information +- Document limitations or assumptions in the docstring -## 2. Hallucination +Optional but encouraged: +- Add unit tests to validate function output -### The Challenge -Individual agents may generate plausible-sounding but incorrect information, especially when dealing with ambiguous or incomplete data. +- Benchmark performance if your tool operates on large datasets -```mermaid -graph TD - Input[Ambiguous Input] --> Agent[AI Agent] - Agent --> Valid[Valid Output] - Agent --> Hallucination[Hallucinated Output] - style Hallucination fill:#ff9999 -``` +--- -### Impact -- Unreliable information generation -- Reduced trust in system outputs -- Potential for misleading decisions -- Need for extensive verification +## Conclusion -## 3. Single Task Execution +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. -### The Challenge -Most individual agents are optimized for specific tasks and struggle with multi-tasking or adapting to new requirements. +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. -```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] -``` +We encourage all developers, data scientists, and domain experts to contribute meaningfully. Review existing tools for inspiration, or create something entirely novel. -### Impact -- Limited flexibility -- Inefficient resource usage -- Complex integration requirements -- Reduced adaptability +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. -## 4. Lack of Collaboration -### The Challenge -Individual agents operate in isolation, unable to share insights or coordinate actions with other agents. -```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 -``` +-------------------------------------------------- -### Impact -- No knowledge sharing -- Duplicate effort -- Missed optimization opportunities -- Limited problem-solving capabilities +# File: docs_structure.md -## 5. Accuracy Issues +# Class/function -### The Challenge -Individual agents may produce inaccurate results due to: -- Limited training data -- Model biases -- Lack of cross-validation -- Incomplete context understanding - -```mermaid -graph LR - Input[Input Data] --> Processing[Processing] - Processing --> Accurate[Accurate Output] - Processing --> Inaccurate[Inaccurate Output] - style Inaccurate fill:#ff9999 -``` - -## 6. Processing Speed Limitations - -### The Challenge -Individual agents may experience: -- Slow response times -- Resource constraints -- Limited parallel processing -- Bottlenecks in complex tasks - -```mermaid -graph TD - Input[Input] --> Queue[Processing Queue] - Queue --> Processing[Sequential Processing] - Processing --> Delay[Processing Delay] - Delay --> Output[Delayed Output] -``` +Brief description +↓ -## Best Practices for Mitigation +↓ +## Overview +↓ +## Architecture (Mermaid diagram) +↓ +## Class Reference (Constructor + Methods) -1. **Use Multi-Agent Systems** - - Distribute tasks across agents - - Enable parallel processing - - Implement cross-validation - - Foster collaboration +table of parameters for every method and example -2. **Implement Verification** - - Cross-check results - - Use consensus mechanisms - - Monitor accuracy metrics - - Track performance +↓ +## Examples -3. **Optimize Resource Usage** - - Balance load distribution - - Cache frequent operations - - Implement efficient queuing - - Monitor system health +↓ ## Conclusion +Benefits of class/structure, and more -Understanding these limitations is crucial for: -- Designing robust multi-agent systems -- Implementing effective mitigation strategies -- Optimizing system performance -- Ensuring reliable outputs -The next section explores how [Multi-Agent Architecture](architecture.md) addresses these limitations through collaborative approaches and specialized agent roles. -------------------------------------------------- -# File: contributors\docs.md +# File: examples\agent_stream.md -# Contributing to Swarms Documentation +# Agent with Streaming ---- +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 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. +## Installation -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. +Install the swarms package using pip: ---- +```bash +pip install -U swarms +``` -## 1. Introduction +## Basic Setup -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. +1. First, set up your environment variables: -**Objectives of this Guide:** +```python +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" +``` +## Step by Step -- Define a standardized contribution workflow for Swarms documentation. +- Install and put your keys in `.env` -- Clarify documentation roles, responsibilities, and submission expectations. +- Turn on streaming in `Agent()` with `streaming_on=True` -- Establish quality benchmarks, review procedures, and formatting rules. +- Optional: If you want to pretty print it, you can do `print_on=True`; if not, it will print normally -- Introduce the Swarms Documentation Bounty Program to incentivize excellence. +## Code ---- +```python +from swarms import Agent -## 2. Why Documentation Is a Strategic Asset +# 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! +) -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. +# 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) +``` -By treating documentation as a core product component, we ensure continuity, scalability, and user satisfaction. +## Connect With Us ---- +If you'd like technical support, join our Discord below and stay updated on our Twitter for new updates! -## 3. Understanding the Swarms Ecosystem +| 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 | -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: examples\cookbook_index.md -- **Tools Documentation (`swarms_tools`)**: Guides for CLI and GUI utilities. +# Swarms Cookbook Examples Index -- **Hosted API Reference**: Up-to-date REST API documentation: [Swarms API Docs](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/). +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. -- **Marketplace & Chat**: Web platforms and communication interfaces [swarms.world](https://swarms.world). +## Finance & Trading -All contributions funnel through the `docs/` directory in the core repo and are structured via MkDocs. +| 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) | ---- +## Healthcare & Medical -## 4. Documentation Tools and Platforms +| 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) | -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: +## Marketing & Content -- **Markdown**: For formatting structure, code snippets, lists, and links. +| 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) | -- **MkDocs Configuration**: `mkdocs.yml` manages structure, theme, and navigation. +## Accounting & Finance Operations -- **Version Control**: GitHub for branching, version tracking, and collaboration. +| 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) | -**Recommended Tooling:** +## Workshops & Tutorials -- Markdown linters to enforce syntax consistency. +| 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) | -- Spellcheckers to ensure grammatical accuracy. +## Additional Resources -- Doc generators for automated API reference extraction. +| 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 | ---- +## Contributing -## 5. Getting Started with Contributions +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). -### 5.1 System Requirements +## License +This project is licensed under the MIT License - see the [LICENSE](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/LICENSE) file for details. -- **Git** v2.30 or higher +-------------------------------------------------- -- **Node.js** and **npm** for related dependency management +# File: examples\index.md -- **MkDocs** and **Material for MkDocs** theme (`pip install mkdocs mkdocs-material`) +# Swarms Examples Index -- A GitHub account with permissions to fork and submit pull requests +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. -### 5.2 Forking the Swarms Repository +## What is Swarms? -1. Visit: `https://github.com/kyegomez/swarms` +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. -2. Click on **Fork** to create your version of the repository +## What You'll Find Here -### 5.3 Clone and Configure Locally +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: -```bash -git clone https://github.com//swarms.git -cd swarms/docs -git checkout -b feature/docs- -``` ---- +- **Single Agent Systems**: From basic implementations to advanced reasoning agents -## 6. Understanding the Repository Structure +- **Multi-Agent Architectures**: Collaborative swarms, hierarchical systems, and experimental topologies -Explore the documentation directory: +- **Industry Applications**: Real-world use cases across finance, healthcare, security, and more -```text -docs/ -├── index.md -├── mkdocs.yml -├── swarms_rs/ -│ ├── overview.md -│ └── ... -└── swarms_tools/ - ├── install.md - └── ... -``` +- **Integration Examples**: Connect with popular AI models, tools, and frameworks -### 6.1 SDK/Tools Directories +- **Advanced Patterns**: RAG systems, function calling, MCP integration, and more -- **Rust SDK (`docs/swarms_rs`)**: Guides, references, and API walkthroughs for the Rust-based implementation. +## Getting Started -- **Swarms Tools (`docs/swarms_tools`)**: CLI guides, GUI usage instructions, and architecture documentation. +**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. -Add new `.md` files in the folder corresponding to your documentation type. +**Want to see real-world applications?** Explore the Industry Applications section to see how Swarms solves practical problems. -### 6.2 Configuring Navigation in MkDocs +## Quick Navigation -Update `mkdocs.yml` to integrate your new document: -```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 -``` +- [Single Agent Examples](#single-agent-examples) - Individual AI agents with various capabilities ---- +- [Multi-Agent Examples](#multi-agent-examples) - Collaborative systems and swarm architectures -## 7. Writing and Editing Documentation +- [Additional Resources](#additional-resources) - Community links and support channels -### 7.1 Content Standards +## 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 | -- **Clarity**: Explain complex ideas in simple, direct language. +### 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 | -- **Style Consistency**: Match the tone and structure of existing docs. +### 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 | -- **Accuracy**: Validate all technical content and code snippets. +### 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 | -- **Accessibility**: Include alt text for images and use semantic Markdown. +### 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 | -### 7.2 Markdown Best Practices +### 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 | -- Sequential heading levels (`#`, `##`, `###`) +### 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 | -- Use fenced code blocks with language identifiers +### 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 | -- Create readable line spacing and avoid unnecessary line breaks +### 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 | -### 7.3 File Placement Protocol +## Multi-Agent Examples -Place `.md` files into the correct subdirectory: +### 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 | -- **Rust SDK Docs**: `docs/swarms_rs/` +### 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 | -- **Tooling Docs**: `docs/swarms_tools/` +### 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 | -## 8. Updating Navigation Configuration +### 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 | -After writing your content: +### 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 | -1. Open `mkdocs.yml` -2. Identify where your file belongs -3. Add it to the `nav` hierarchy -4. Preview changes: +### 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 | -```bash -mkdocs serve -# Open http://127.0.0.1:8000 to verify output -``` +### 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 | -## 9. Workflow: Branches, Commits, Pull Requests +### 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 | -### 9.1 Branch Naming Guidelines +### 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 | -- Use prefix and description, e.g.: - - `feature/docs-api-pagination` +### 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 | - - `fix/docs-typo-tooling` +## Additional Resources -### 9.2 Writing Clear Commits +- [Github](https://github.com/kyegomez/swarms) -Follow [Conventional Commits](https://www.conventionalcommits.org/): +- Discord (https://t.co/zlLe07AqUX) -```bash -docs(swarms_rs): add stream API tutorial -docs(swarms_tools): correct CLI usage example -``` +- Telegram (https://t.co/dSRy143zQv) -### 9.3 Submitting a Pull Request +- X Community (https://x.com/i/communities/1875452887414804745) -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`) +-------------------------------------------------- ---- +# File: examples\paper_implementations.md -## 10. Review, QA, and Merging +# Multi-Agent Paper Implementations -Every PR undergoes automated and human review: +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. -- **CI Checks**: Syntax validation, link checking, and formatting +### Why Multi-Agent Research Matters -- **Manual Review**: Maintain clarity, completeness, and relevance +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: -- **Iteration**: Collaborate through feedback and finalize changes +- **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 -Once approved, maintainers will merge and deploy the updated documentation. +### Our Research Implementation Philosophy ---- +We believe that the best way to advance the field is through practical implementation and real-world validation. Our approach includes: -## 11. Swarms Documentation Bounty Initiative +- **Faithful Reproduction**: Implementing research papers with high fidelity to original methodologies -To foster continuous improvement, we offer structured rewards for eligible contributions: +- **Production Enhancement**: Adding enterprise-grade features like error handling, monitoring, and scalability -### 11.1 Contribution Types +- **Open Source Commitment**: Making all implementations freely available to the research community +- **Continuous Improvement**: Iterating on implementations based on community feedback and new research -- Creating comprehensive new tutorials and deep dives - -- Updating outdated references and examples +### What You'll Find Here -- Fixing typos, grammar, and formatting errors +This documentation showcases our comprehensive collection of multi-agent research implementations, including: -- Translating existing content -### 11.2 Reward Structure +- **Academic Paper Implementations**: Direct implementations of published research papers -| 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 | +- **Enhanced Frameworks**: Production-ready versions with additional features and optimizations -### 11.3 Claiming Bounties +- **Research Compilations**: Curated lists of influential multi-agent papers and resources -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) +- **Practical Examples**: Ready-to-use code examples and tutorials ---- +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. -## 12. Best Practices for Efficient Contribution +### Join the Multi-Agent Revolution -- **Stay Updated**: Sync your fork weekly to avoid merge conflicts +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. -- **Atomic PRs**: Submit narrowly scoped changes for faster review +## Implemented Research Papers -- **Use Visuals**: Support documentation with screenshots or diagrams +| 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 | -- **Cross-Reference**: Link to related documentation for completeness +## Additional Research Resources -- **Version Awareness**: Specify SDK/tool versions in code examples +### Multi-Agent Papers Compilation ---- +We maintain a comprehensive list of multi-agent research papers at: [awesome-multi-agent-papers](https://github.com/kyegomez/awesome-multi-agent-papers) -## 13. Style Guide Snapshot +### Research Lists +Our research compilation includes: -- **Voice**: Informative, concise, and respectful +- **Projects**: ModelScope-Agent, Gorilla, BMTools, LMQL, Langchain, MetaGPT, AutoGPT, and more -- **Terminology**: Use standardized terms (`Swarm`, `Swarms`) consistently +- **Research Papers**: BOLAA, ToolLLM, Communicative Agents, Mind2Web, Voyager, Tree of Thoughts, and many others -- **Code**: Format snippets using language-specific linters +- **Blog Articles**: Latest insights and developments in autonomous agents -- **Accessibility**: Include alt attributes and avoid ambiguous links +- **Talks**: Presentations from leading researchers like Geoffrey Hinton and Andrej Karpathy ---- -## 14. Monitoring & Improving Documentation Health +## Implementation Details -We use analytics and community input to prioritize improvements: +### MALT Framework -- **Traffic Reports**: Track most/least visited pages +The MALT implementation provides: -- **Search Logs**: Detect content gaps from common search terms +- **Three-Agent Architecture**: Creator, Verifier, and Refiner agents -- **Feedback Forms**: Collect real-world user input +- **Structured Workflow**: Coordinated task execution with conversation history -Schedule quarterly audits to refine structure and content across all repositories. +- **Reliability Features**: Error handling, validation, and quality assurance ---- +- **Extensibility**: Custom agent integration and configuration options -## 15. Community Promotion & Engagement -Promote your contributions via: +### MAI-DxO System +The MAI Diagnostic Orchestrator features: -- **Swarms Discord**: https://discord.gg/jM3Z6M9uMq +- **Virtual Physician Panel**: Multiple specialized medical agents -- **Swarms Telegram**: https://t.me/swarmsgroupchat +- **Cost Optimization**: Efficient diagnostic workflows -- **Swarms Twitter**: https://x.com/swarms_corp +- **Iterative Refinement**: Continuous improvement of diagnoses -- **Startup Program Showcases**: https://www.swarms.xyz/programs/startups +- **Medical Expertise**: Domain-specific knowledge and reasoning -Active contributors are often spotlighted for leadership roles and community awards. ---- +### AI-CoScientist Framework -## 16. Resource Index +The AI-CoScientist implementation includes: -- Core GitHub Repo: https://github.com/kyegomez/swarms +- **Tournament-Based Selection**: Elo rating system for hypothesis ranking -- Rust SDK Repo: https://github.com/The-Swarm-Corporation/swarms-rs +- **Peer Review System**: Comprehensive evaluation of scientific proposals -- Swarms API Docs: https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/ +- **Hypothesis Evolution**: Iterative refinement based on feedback -- Marketplace: https://swarms.world +- **Diversity Control**: Proximity analysis to maintain hypothesis variety -Join our monthly Documentation Office Hours for real-time mentorship and Q&A. ---- +### Mixture of Agents (MoA) -## 17. Frequently Asked Questions +The MoA architecture provides: -**Q1: Is MkDocs required to contribute?** -A: It's recommended but not required; Markdown knowledge is sufficient to get started. +- **Parallel Processing**: Multiple agents working simultaneously -**Q2: Can I rework existing sections?** -A: Yes, propose changes via issues first, or submit PRs with clear descriptions. +- **Expert Specialization**: Domain-specific agent capabilities -**Q3: When are bounties paid?** -A: Within 30 days of merge, following internal validation. +- **Iterative Refinement**: Continuous improvement through collaboration ---- +- **State-of-the-Art Performance**: Achieving superior results through collective intelligence -## 18. Final Thoughts -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. -We look forward to your pull requests, feedback, and ideas. +## Contributing ---- +We welcome contributions to implement additional research papers! If you'd like to contribute: +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 --------------------------------------------------- +## Citation -# File: contributors\environment_setup.md +If you use any of these implementations in your research, please cite the original papers and the Swarms framework: -# Environment Setup Guide for Swarms Contributors +```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} +} +``` -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. +## Community -!!! 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! +Join our community to stay updated on the latest multi-agent research implementations: -!!! 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 - ``` +- **Discord**: [Join our community](https://discord.gg/jM3Z6M9uMq) ---- +- **Documentation**: [docs.swarms.world](https://docs.swarms.world) -## :material-list-status: Prerequisites +- **GitHub**: [kyegomez/swarms](https://github.com/kyegomez/swarms) -Before setting up your development environment, ensure you have the following installed: +- **Research Papers**: [awesome-multi-agent-papers](https://github.com/kyegomez/awesome-multi-agent-papers) -### System Requirements -| 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) | -### Operating System Support -=== "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 - ``` +-------------------------------------------------- -=== "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 - ``` +# File: examples\templates.md -=== "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 - - ``` +# Templates & Applications Documentation ---- +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. -## :material-auto-fix: Automated Setup (Recommended) +🔗 **Main Repository**: [Swarms Framework](https://github.com/kyegomez/swarms) -We provide a comprehensive setup script that automates the entire development environment setup process. This is the **recommended approach** for new contributors. +--- -### What the Setup Script Does +## 🏥 Healthcare & Medical Applications -The `scripts/setup.sh` script automatically handles: +### Medical Diagnosis & Analysis -- ✅ **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 +| 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 | -### Running the Automated Setup +### Medical Operations & Administration -```bash -# Clone the repository -git clone https://github.com/kyegomez/swarms.git -cd swarms +| 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 | -# Make the script executable and run it -chmod +x scripts/setup.sh -./scripts/setup.sh -``` +--- -### Script Features +## 💰 Financial Services & Trading -=== "🎯 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 +### Trading & Investment -=== "🔧 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 - ``` +| 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 | -=== "📋 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 - ``` +### Financial Analysis & Management -=== "💡 Helpful Guidance" - Provides next steps and useful commands: - - How to activate the virtual environment - - Essential Poetry commands - - Testing and development workflow - - Troubleshooting tips +| 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 | -### When to Use Manual Setup +### Insurance & Lending -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 +| 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 | --- -## :material-git: Repository Setup - -### Step 1: Fork and Clone +## 🔬 Research & Development -1. **Fork the repository** on GitHub: [github.com/kyegomez/swarms](https://github.com/kyegomez/swarms) +### Scientific Research -2. **Clone your fork**: -```bash -git clone https://github.com/YOUR_USERNAME/swarms.git -cd swarms -``` +| 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 | -3. **Add upstream remote**: -```bash -git remote add upstream https://github.com/kyegomez/swarms.git -``` +### Mathematical & Analytical -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) -``` +| Name | Description | Type | Repository | +|------|-------------|------|------------| +| [Generalist-Mathematician-Swarm](https://github.com/The-Swarm-Corporation/Generalist-Mathematician-Swarm) | Mathematical problem-solving agent swarm | Mathematics | Science | --- -## :material-package-variant: Dependency Management - -Choose your preferred method for managing dependencies: - -=== "Poetry (Recommended)" - - Poetry provides superior dependency resolution and virtual environment management. +## 💼 Business & Marketing - ### 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 - ``` +### Marketing & Content - ### 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 - ``` +| 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 | -=== "pip + venv" - - Traditional pip-based setup with virtual environments. +### Legal Services - ### 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 - ``` +| Name | Description | Type | Repository | +|------|-------------|------|------------| +| [Legal-Swarm-Template](https://github.com/The-Swarm-Corporation/Legal-Swarm-Template) | Legal document processing and analysis | Legal Technology | Business | --- -## :material-tools: Development Tools Setup - -### Code Quality Tools +## 🛠️ Development Tools & Platforms -Swarms uses several tools to maintain code quality: +### Core Platforms & Operating Systems -=== "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 - ``` +| 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 | -=== "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 - ``` +### Development Tools & Utilities -=== "Type Checking" - - **MyPy** - Static type checker - ```bash - # Run type checking - poetry run mypy swarms/ - # or with pip: - mypy swarms/ - ``` +| 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 | -### Pre-commit Hooks (Optional but Recommended) +### Templates & Examples -Set up pre-commit hooks to automatically run quality checks: +| 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 | -```bash -# Install pre-commit -poetry add --group dev pre-commit -# or with pip: -pip install pre-commit +--- -# Install git hooks -pre-commit install +## 📚 Educational Resources -# Run on all files -pre-commit run --all-files -``` +### Courses & Guides -The project uses the latest ruff-pre-commit configuration with separate hooks for linting and formatting: +| 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 | -- **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 +### Testing & Evaluation -This configuration ensures consistent code quality and style across the project while avoiding conflicts with Jupyter notebook files. +| Name | Description | Type | Repository | +|------|-------------|------|------------| +| [swarms-evals](https://github.com/The-Swarm-Corporation/swarms-evals) | Evaluation framework for swarm systems | Testing Framework | Development | --- -## :material-test-tube: Testing Setup +## 🚀 Getting Started -### Running Tests +### Prerequisites -```bash -# Run all tests -poetry run pytest -# or with pip: -pytest +- Python 3.8+ -# Run tests with coverage -poetry run pytest --cov=swarms tests/ +- Basic understanding of AI agents and multi-agent systems -# Run specific test file -poetry run pytest tests/test_specific_file.py +- Familiarity with the Swarms framework -# Run tests matching a pattern -poetry run pytest -k "test_agent" -``` -### Test Structure +### Installation -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 +```bash +pip install swarms ``` -### Writing Tests +### Quick Start -```python -# Example test file: tests/test_example.py -import pytest -from swarms import Agent +1. Choose a template from the categories above -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" +2. Clone the repository -@pytest.mark.parametrize("input_val,expected", [ - ("hello", "HELLO"), - ("world", "WORLD"), -]) -def test_uppercase(input_val, expected): - """Example parametrized test.""" - assert input_val.upper() == expected -``` +3. Follow the setup instructions in the README + +4. Customize the agents for your specific use case --- -## :material-book-open-page-variant: Documentation Setup +## 🤝 Contributing -### Building Documentation Locally +The Swarms ecosystem is constantly growing. To contribute: -```bash -# Install documentation dependencies -pip install -r docs/requirements.txt +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 -# Navigate to docs directory -cd docs +--- -# Serve documentation locally -mkdocs serve -# Documentation will be available at http://127.0.0.1:8000 -``` +## 📞 Support & Community -### Documentation Structure +Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights! -``` -docs/ -├── index.md # Homepage -├── mkdocs.yml # MkDocs configuration -├── swarms/ # Core documentation -├── examples/ # Examples and tutorials -├── contributors/ # Contributor guides -└── assets/ # Images and static files -``` +| 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) | -### Writing Documentation +--- -Use Markdown with MkDocs extensions: +## 📊 Statistics -```markdown -# Page Title +- **Total Projects**: 35+ -!!! tip "Pro Tip" - Use admonitions to highlight important information. +- **Industries Covered**: Healthcare, Finance, Research, Business, Development -=== "Python" - ```python - from swarms import Agent - agent = Agent() - ``` +- **Project Types**: Templates, Applications, Tools, Educational Resources + +- **Active Development**: Continuous updates and new additions -=== "CLI" - ```bash - swarms create-agent --name myagent - ``` -``` --- -## :material-application-variable: Environment Variables -Create a `.env` file for local development: +-------------------------------------------------- -```bash -# Copy example environment file -cp .env.example .env # if it exists +# File: governance\bounty_program.md -# Or create your own .env file -touch .env -``` +# Swarms Bounty Program -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 +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. -# Development settings -DEBUG=true -LOG_LEVEL=INFO +## Why Contribute? -# Optional: Database settings -DATABASE_URL=sqlite:///swarms.db -``` +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. -## :material-check-circle: Verification Steps +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. -!!! 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. +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. -For manual setups, verify your setup is working correctly: +## How It Works -### 1. Basic Import Test -```bash -poetry run python -c "from swarms import Agent; print('✅ Import successful')" -``` +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. -### 2. Run a Simple Agent -```python -# test_setup.py -from swarms import Agent +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="setup_test", - system_prompt="You are a helpful assistant for testing setup.", - max_loops=1 -) +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. -response = agent.run("Say hello!") -print(f"✅ Agent response: {response}") -``` +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. -### 3. Code Quality Check -```bash -# Run all quality checks -poetry run black swarms/ --check -poetry run ruff check swarms/ -poetry run pytest tests/ -x -``` +## 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. -### 4. Documentation Build -```bash -cd docs -mkdocs build -echo "✅ Documentation built successfully" -``` +- 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. -## :material-rocket-launch: Development Workflow +## Get Involved -### Creating a Feature Branch +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. -```bash -# Sync with upstream -git fetch upstream -git checkout master -git rebase upstream/master +2. **Stay Updated**: + - Keep track of the latest updates, announcements, and bounty opportunities by regularly checking the Discord channel and the GitHub repository. -# Create feature branch -git checkout -b feature/your-feature-name +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. -# Make your changes... -# Add and commit -git add . -git commit -m "feat: add your feature description" +## Additional Benefits -# Push to your fork -git push origin feature/your-feature-name -``` +Beyond monetary rewards, contributors gain intangible benefits that elevate their professional journey: -### Daily Development Commands +- **Recognition**: Your contributions will be showcased to a community of over 9,000 engineers, increasing your visibility and credibility in the AI field. -```bash -# Start development session -cd swarms -poetry shell # or source venv/bin/activate +- **Portfolio Building**: Add high-impact contributions to your portfolio, demonstrating your skills and experience to potential employers or collaborators. -# Pull latest changes -git fetch upstream -git rebase upstream/master +- **Knowledge Sharing**: Learn from and collaborate with experts in agent engineering, gaining insights into the latest advancements and best practices in the field. -# Run tests during development -poetry run pytest tests/ -v +## Contact Us +For any questions, support, or clarifications, reach out to the Swarms team: -# Format and lint before committing -poetry run black swarms/ -poetry run ruff check swarms/ --fix +- **Discord**: Engage directly with the team and fellow contributors in our active channels. -# Run a quick smoke test -poetry run python -c "from swarms import Agent; print('✅ All good')" -``` +- **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. --- -## :material-bug: Troubleshooting - -!!! 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. - -### Common Issues and Solutions - -=== "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 - ``` +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! -=== "Python Version Issues" - - **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 - ``` -=== "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 . - ``` -=== "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 - ``` +-------------------------------------------------- -### Getting Help +# File: governance\main.md -If you encounter issues: +# 🔗 Links & Resources -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 +Welcome to the Swarms ecosystem. Click any tile below to explore our products, community, documentation, and social platforms. --- -## :material-next-step: Next Steps + -!!! 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. +
---- +🗣️ Swarms Chat -## :material-bookmark-outline: Quick Reference +🛍️ Swarms Marketplace -### Essential Commands +📚 Swarms API Docs -```bash -# Setup (choose one) -./scripts/setup.sh # Automated setup (recommended) -poetry install --with dev # Manual dependency install +🚀 Swarms Startup Program -# Daily workflow -poetry shell # Activate environment -poetry run pytest # Run tests -poetry run black swarms/ # Format code -poetry run ruff check swarms/ # Lint code +💻 GitHub: Swarms (Python) -# 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 +🦀 GitHub: Swarms (Rust) -# Documentation -cd docs && mkdocs serve # Serve docs locally -mkdocs build # Build docs -``` +💬 Join Our Discord -### Project Structure +📱 Telegram Group -``` -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 -``` +🐦 Twitter / X -Happy coding! 🚀 +✍️ Swarms Blog on Medium --------------------------------------------------- +
-# File: contributors\main.md +--- -# Contributing to Swarms: Building the Infrastructure for The Agentic Economy +## 💡 Quick Summary -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. +| 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) | -!!! 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. +--- -### What You're Building +> 🐝 Swarms is building the agentic internet. Join the movement and build the future with us. -=== "Autonomous Systems" - **Autonomous Resource Allocation** - - Global supply chains and energy distribution optimized in real-time -=== "Intelligence Networks" - **Distributed Decision Making** - - Collaborative intelligence networks across industries and governments +-------------------------------------------------- -=== "Smart Markets" - **Self-Organizing Markets** - - Agent-driven marketplaces that automatically balance supply and demand +# File: guides\agent_evals.md -=== "Problem Solving" - **Collaborative Problem Solving** - - Massive agent swarms tackling climate change, disease, and scientific discovery +### Understanding Agent Evaluation Mechanisms -=== "Infrastructure" - **Adaptive Infrastructure** - - Self-healing systems that evolve without human intervention +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. ---- +#### 1. Introduction to Agent Evaluation Mechanisms -## Why Contribute to Swarms? +Agent evaluation mechanisms refer to the processes and criteria used to assess the performance of agents within a system. These mechanisms are essential for: -### :material-rocket-launch: Shape the Future of Civilization +- **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. -!!! 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 +### 2. Key Components of Agent Evaluation -### :material-trophy: Recognition and Professional Development +To effectively evaluate agents, several components and metrics are considered: -!!! 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 +#### a. Performance Metrics -!!! 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 +These are quantitative measures used to assess how well an agent is performing. Common performance metrics include: -### :material-brain: Technical Expertise Development +- **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. -Master cutting-edge technologies: +#### b. Evaluation Criteria -| 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 | +Evaluation criteria define the standards or benchmarks against which agent performance is measured. These criteria are often task-specific and may include: -### :material-account-group: Research Community Access +- **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. -!!! 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 +### 3. The Process of Agent Evaluation ---- +The evaluation process involves several steps, which can be visualized using Mermaid graphs: -## Contribution Opportunities +#### a. Define Evaluation Metrics -=== "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 +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. -=== "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 +```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] +``` ---- +#### b. Collect Data -## How to Contribute +Data collection involves gathering information on the agent's performance. This data can come from logs, user feedback, or direct observations. -### Step 1: Get Started +```mermaid +graph TD + A[Collect Data] --> B[Logs] + A --> C[User Feedback] + A --> D[Direct Observations] +``` -!!! 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 } +#### c. Analyze Performance -### Step 2: Find Your Path +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[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] + A[Analyze Performance] --> B[Statistical Analysis] + A --> C[Machine Learning Models] + A --> D[Other Analytical Techniques] ``` -### Step 3: Make Impact +#### d. Generate Reports -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 +After analysis, performance reports are generated. These reports provide insights into how well the agent is performing and identify areas for improvement. ---- +```mermaid +graph TD + A[Generate Reports] --> B[Performance Insights] + B --> C[Identify Areas for Improvement] +``` -## Recognition Framework +### 4. Tracking Agent Accuracy -### :material-flash: Immediate Benefits +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: -!!! 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 | +#### a. Define Correctness Criteria -### :material-trending-up: Long-term Opportunities +The first step is to define what constitutes a correct action or decision for the agent. -!!! 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 +```mermaid +graph TD + A[Define Correctness Criteria] --> B[Task-Specific Standards] + B --> C[Action Accuracy] + B --> D[Decision Accuracy] +``` ---- +#### b. Monitor Agent Actions -## Societal Impact +Agents' actions are continuously monitored to track their performance. This monitoring can be done in real-time or through periodic evaluations. -!!! abstract "Building Solutions for Humanity" - Swarms enables technology that addresses critical challenges: +```mermaid +graph TD + A[Monitor Agent Actions] --> B[Real-Time Monitoring] + A --> C[Periodic Evaluations] +``` - === "Research" - **Scientific Research** - - Accelerate collaborative research and discovery across disciplines +#### c. Compare Against Correctness Criteria - === "Healthcare" - **Healthcare Innovation** - - Support drug discovery and personalized medicine development +Each action or decision made by the agent is compared against the defined correctness criteria to determine its accuracy. - === "Environment" - **Environmental Solutions** - - Monitor climate and optimize sustainability initiatives +```mermaid +graph TD + A[Compare Against Correctness Criteria] --> B[Evaluate Each Action] + B --> C[Correct or Incorrect?] +``` - === "Education" - **Educational Technology** - - Create adaptive learning systems for personalized education +#### d. Calculate Accuracy Metrics - === "Economy" - **Economic Innovation** - - Generate new opportunities and efficiency improvements +Accuracy metrics are calculated based on the comparison results. These metrics provide a quantitative measure of the agent's accuracy. ---- +```mermaid +graph TD + A[Calculate Accuracy Metrics] --> B[Accuracy Percentage] + A --> C[Error Rate] +``` -## Get Involved +### 5. Measuring Agent Accuracy -### :material-link: Connect With Us +Measuring agent accuracy involves several steps and considerations: -!!! 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 } +#### a. Data Labeling ---- +To measure accuracy, the data used for evaluation must be accurately labeled. This involves annotating the data with the correct actions or decisions. -!!! 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. +```mermaid +graph TD + A[Data Labeling] --> B[Annotate Data with Correct Actions] + B --> C[Ensure Accuracy of Labels] +``` -!!! success "Your Mission" - Your contribution to Swarms helps create the foundation for billions of autonomous agents working together to solve humanity's greatest challenges. +#### b. Establish Baseline Performance - **Join us in building the most important technology of our time.** +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] +``` -
-*Built with :material-heart: by the global Swarms community* -
+#### 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. -# File: contributors\tools.md +```mermaid +graph TD + A[Regular Evaluations] --> B[Track Performance Over Time] + B --> C[Identify Performance Trends] + B --> D[Detect Deviations] +``` -# Contributing Tools and Plugins to the Swarms Ecosystem +#### d. Feedback and Improvement -## Introduction +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. -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. +```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] +``` -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. +### 6. Visualizing Agent Evaluation with Mermaid Graphs -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. +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: -## Repository Architecture +#### a. Overall Evaluation Process -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: +```mermaid +graph TD + A[Define Evaluation Metrics] --> B[Collect Data] + B --> C[Analyze Performance] + C --> D[Generate Reports] +``` -- `finance/`: Market analytics, stock price retrievers, blockchain APIs, etc. +#### b. Accuracy Tracking -- `social/`: Sentiment analysis, engagement tracking, and media scraping utilities. +```mermaid +graph TD + A[Define Correctness Criteria] --> B[Monitor Agent Actions] + B --> C[Compare Against Correctness Criteria] + C --> D[Calculate Accuracy Metrics] +``` -- `health/`: Interfaces for EHR systems, wearable device APIs, or health informatics. +#### c. Continuous Improvement Cycle -- `ai/`: Model-serving utilities, embedding services, and prompt engineering functions. +```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 +``` -- `security/`: Encryption libraries, risk scoring tools, penetration test interfaces. +### 7. Case Study: Evaluating a Chatbot Agent -- `devtools/`: Build tools, deployment utilities, code quality analyzers. +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. -- `misc/`: General-purpose helpers or utilities that serve multiple domains. +#### a. Define Evaluation Metrics -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. +For the chatbot, key performance metrics might include: -## Tool Development Specifications +- **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. -To ensure long-term maintainability and smooth agent-tool integration, each contribution must strictly follow the specifications below. +#### b. Collect Data -### 1. Function Structure and API Usage +Data is collected from chatbot interactions, including user queries, responses, and feedback. -```python -import requests -import os +#### c. Analyze Performance -def fetch_data(symbol: str, date_range: str) -> str: - """ - Fetch financial data for a given symbol and date range. +Performance analysis involves comparing the chatbot's responses against a predefined set of correct responses and calculating accuracy metrics. - Args: - symbol (str): Ticker symbol of the asset. - date_range (str): Timeframe for the data (e.g., '1d', '1m', '1y'). +#### d. Generate Reports - 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." -``` +Reports are generated to provide insights into the chatbot's performance, highlighting areas where it excels and areas needing improvement. -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. +### 8. Best Practices for Agent Evaluation -### 2. Type Hints and Input Validation +Here are some best practices to ensure effective agent evaluation: -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. +#### a. Use Realistic Scenarios -### 3. Standardized Output Format +Evaluate agents in realistic scenarios that closely mimic real-world conditions. This ensures that the evaluation results are relevant and applicable. -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. +#### b. Continuous Monitoring -### 4. API Key Management Best Practices +Continuously monitor agent performance to detect and address issues promptly. This helps in maintaining high performance levels. -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. +#### c. Incorporate User Feedback -### 5. Documentation Guidelines +User feedback is invaluable for improving agent performance. Incorporate feedback into the evaluation process to identify and rectify shortcomings. -Every tool must include a detailed docstring that describes: +#### d. Regular Updates -- The function's purpose and operational scope +Regularly update the evaluation metrics and criteria to keep pace with evolving tasks and requirements. -- All parameter types and formats +### Conclusion -- A clear return type +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. -- Usage examples or sample inputs/outputs +-------------------------------------------------- -Example usage: -```python -result = fetch_data("AAPL", "1m") -print(result) -``` +# File: guides\financial_analysis_swarm_mm.md -Well-documented code accelerates adoption and improves LLM interpretability. +# Building a Multi-Agent System for Real-Time Financial Analysis: A Comprehensive Tutorial -## Contribution Workflow +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 submit a tool, follow the workflow below. This ensures your code integrates cleanly and is easy for maintainers to review. +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. -### 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. +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. -### Step 2: Clone Your Fork -```bash -git clone https://github.com/YOUR_USERNAME/swarms-tools.git -cd swarms-tools -``` +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 -### Step 3: Create a Feature Branch +Now, let's break down our financial analysis system step by step. + +## Step 1: Setting Up the Environment +First install the necessary packages: ```bash -git checkout -b feature/add-tool- +$ pip3 install -U swarms yfiance swarm_models fredapi pandas ``` -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. +First, we need to set up our environment and import the necessary libraries: -If your tool belongs in a new category, you may create a new folder with a clear, lowercase name. +```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 -### 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. +# Load environment variables +load_dotenv() -### Step 6: Commit Your Changes +# Set up logging +logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s') +logger = logging.getLogger(__name__) -```bash -git add . -git commit -m "Add under : API-based tool for X" -``` +# 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') -### Step 7: Push to GitHub +# Initialize FRED client +fred_client = Fred(api_key=FRED_API_KEY) -```bash -git push origin feature/add-tool- +# Polygon API base URL +POLYGON_BASE_URL = "https://api.polygon.io" ``` -### 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 +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. -Once your tool has been merged into the official repository, it can be utilized by Swarms agents as part of their available capabilities. +## Step 2: Implementing Rate Limiting -The example below illustrates how to embed a newly added tool into an autonomous agent: +To respect API rate limits, we implement rate limiting decorators: ```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", -) +@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() -agent.run("Create a new file for a plan to take over the world.") +@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) ``` -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. - -This agent-tool paradigm enables highly flexible and responsive behavior across workflows involving research, automation, financial analysis, social listening, and more. - ---- - -## Tool Maintenance and Long-Term Ownership +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. -Contributors are expected to uphold the quality of their tools post-merge. This includes: +## Step 3: Implementing Data Fetching Functions -- Monitoring for issues or bugs reported by the community +Next, we implement functions to fetch data from various sources: -- Updating tools when APIs deprecate or modify their behavior +### Yahoo Finance Integration -- Improving efficiency, error handling, or documentation over time +```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 -If a tool becomes outdated or unsupported, maintainers may archive or revise it to maintain ecosystem integrity. +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 +``` -Contributors whose tools receive wide usage or demonstrate excellence in design may be offered elevated privileges or invited to maintain broader tool categories. +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 -## Best Practices for Enterprise-Grade Contributions +```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 -To ensure your tool is production-ready and enterprise-compliant, observe the following practices: +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 [] +``` +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. -- Run static type checking with `mypy` +### FRED Integration -- Use formatters like `black` and linters such as `flake8` +```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 -- Avoid unnecessary external dependencies +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 {} +``` -- Keep functions modular and readable +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. -- Prefer named parameters over positional arguments for clarity +## Step 4: Creating Specialized Agents -- Handle API errors gracefully and return user-friendly messages +Now we create our specialized agents using the Swarms framework: -- Document limitations or assumptions in the docstring +```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, +) -Optional but encouraged: -- Add unit tests to validate function output +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, +) -- Benchmark performance if your tool operates on large datasets +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, +) +``` -## Conclusion +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. -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. +## Step 5: Building the Multi-Agent System -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 then combine our specialized agents into a multi-agent system: -We encourage all developers, data scientists, and domain experts to contribute meaningfully. Review existing tools for inspiration, or create something entirely novel. +```python +agents = [stock_agent, market_agent, macro_agent, news_agent] +flow = "StockAgent -> MarketAgent -> MacroAgent -> NewsAgent" -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. +agent_system = AgentRearrange(agents=agents, flow=flow) +``` +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. +## Step 6: Implementing Real-Time Analysis --------------------------------------------------- +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']) -# File: corporate\2024_2025_goals.md + # Prepare input for the multi-agent system + input_data = f""" + Yahoo Finance Data: + {yf_realtime} -# **Swarms Goals & Milestone Tracking: A Vision for 2024 and Beyond** + Recent Stock History: + {yf_data.tail().to_string() if yf_data is not None else 'Data unavailable'} -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. + Polygon.io Trade Data: + {polygon_trades} -## **Our Vision: The Agentic Ecosystem** + Polygon.io Quote Data: + {polygon_quotes} -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. + Recent News: + {polygon_news[:3] if polygon_news else 'No recent news available'} -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. + Economic Indicators: + {fred_data} -## **Goals for 2024 and 2025** + 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. + """ -To achieve our vision, we have laid out a structured growth trajectory for Swarms, driven by clear numerical targets: + # 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}" +``` -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. +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. -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. +## Step 7: Implementing Advanced Use Cases -## **Tracking Progress: The Power of Metrics** +We then implement more advanced analysis functions: -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: +### Compare Stocks -### 1. Growth in Agent Deployment +```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} -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. + 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}" +``` -**Key Milestones:** +This function compares multiple stocks by running a real-time analysis on each and then prompting our multi-agent system to compare the results. -- **November 2024**: Surpass 250 million agents. +### Sector Analysis -- **December 2024**: Reach 500 million 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} -- **June 2025**: Break the 5 billion agents mark. + 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}" +``` -- **December 2025**: Hit 10 billion agents. +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. +### Economic Impact Analysis -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. +```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()} -### 2. Agents Deployed Per User: Engagement Indicator + 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 -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. + 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}" +``` -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. +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. +## Step 8: Running the Analysis -**Key Milestones:** +Finally, we implement our main function to run all of our analyses: -- **November 2024**: Achieve an average of 20 agents deployed per user each month. +```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) -- **June 2025**: Target 100-200+ agents deployed per user. + comparison_result = await compare_stocks(session, ['AAPL', 'GOOGL', 'MSFT']) + print("\nStock Comparison:") + print(comparison_result) + tech_sector_analysis = await sector_analysis(session, 'Technology') + print("\nTechnology Sector Analysis:") + print(tech_sector_analysis) -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. + gdp_impact = await economic_impact_analysis(session, 'GDP', 22000) + print("\nEconomic Impact Analysis:") + print(gdp_impact) -### 3. Active vs. Inactive Agents: Measuring Churn +if __name__ == "__main__": + asyncio.run(main()) +``` -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. +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. -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. +## Conclusion and Next Steps -**Key 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: -- **December 2024**: Ensure that no more than **30%** of deployed agents are inactive. +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 -- **December 2025**: Aim for **10%** or lower, reflecting strong agent usefulness and consistent platform value delivery. +This system provides a powerful foundation for financial analysis, but there's always room for expansion and improvement. Here are some potential next steps: +1. **Expand data sources**: Consider integrating additional financial data providers for even more comprehensive analysis. -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. +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. -## **Milestones and Success Criteria** +3. **Implement a user interface**: Consider building a web interface or dashboard to make the system more user-friendly for non-technical analysts. -To reach these ambitious goals, we have broken our roadmap down into a series of actionable milestones: +4. **Add visualization capabilities**: Integrate data visualization tools to help interpret complex financial data more easily. -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. +5. **Implement a backtesting system**: Develop a system to evaluate your multi-agent system's performance on historical data. -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. +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. -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. +7. **Implement real-time monitoring**: Set up a system to continuously monitor markets and alert you to significant changes or opportunities. -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. +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. -## **Actionable Strategies for Goal Achievement** +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). -**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. +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. -**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. +Lastly, don't forget to visit the [Swarms Website](https://swarms.xyz) for a comprehensive overview of the project and its capabilities. -**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. +By leveraging the power of multi-agent AI systems, you're well-equipped to navigate the complex world of financial markets. Happy analyzing! -**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. -**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. -## **The Path Ahead: Building Towards 10 Billion Agents** +## Swarm Resources: -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. -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. +* [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) -## **Community and Culture** +-------------------------------------------------- -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. +# File: guides\financial_data_api.md -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. +# Analyzing Financial Data with AI Agents using Swarms Framework -# **Conclusion: Measuring Success One Milestone at a Time** +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. -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. +## Table of Contents -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. +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) -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. +## 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. --------------------------------------------------- +## Setting Up the Environment -# File: corporate\architecture.md +Before we dive into connecting AI agents with financial data providers, let's set up our environment: -# Architecture +1. Install the Swarms framework: -## **1. Introduction** +```bash +pip install -U swarms +``` -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. +2. Install additional required libraries: ---- +```bash +pip install requests pandas numpy matplotlib +``` -## **2. The Vision** +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. -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. +## Connecting AI Agents with Financial Data Providers ---- +Now, let's explore how to connect AI agents using the Swarms framework with different financial data providers. -## **3. Architecture Overview** +### Polygon.io -### **3.1 Agent Level** -The base level that serves as the building block for all further complexity. +First, we'll create an AI agent that can fetch and analyze stock data from Polygon.io. -#### 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. +```python +import os +from swarms import Agent +from swarms.models import OpenAIChat +from dotenv import load_dotenv +import requests +import pandas as pd -#### Interaction: -Agents interact with the external world through their model and tools. The Vectorstore aids in retaining knowledge and facilitating inter-agent communication. +load_dotenv() -### **3.2 Worker Infrastructure Level** -Building on the agent foundation, enhancing capability and readiness for swarm integration. +# Polygon.io API setup +POLYGON_API_KEY = os.getenv("POLYGON_API_KEY") +POLYGON_BASE_URL = "https://api.polygon.io/v2" -#### 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. +# OpenAI API setup +OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") -#### Interaction: -Each worker is an enhanced agent, capable of operating independently or in sync with its peers, allowing for dynamic, scalable operations. +# Create an instance of the OpenAIChat class +model = OpenAIChat( + openai_api_key=OPENAI_API_KEY, + model_name="gpt-4", + temperature=0.1 +) -### **3.3 Swarm Level** -Multiple Worker Nodes orchestrated into a synchronized, collaborative entity. +# 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 +) -#### 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. +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']) -#### Interaction: -Nodes collaborate under the orchestrator's guidance, ensuring tasks are partitioned appropriately, executed, and results consolidated. +# Example usage +symbol = "AAPL" +from_date = "2023-01-01" +to_date = "2023-12-31" -### **3.4 Hivemind Level** -Envisioned as a 'Swarm of Swarms'. An upper echelon of collaboration. +stock_data = get_stock_data(symbol, from_date, to_date) -#### 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. +analysis_request = f""" +Analyze the following stock data for {symbol} from {from_date} to {to_date}: -#### Interaction: -Multiple swarms, each a formidable force, combine their prowess under the Hivemind. This level tackles monumental tasks by dividing them among swarms. +{stock_data.to_string()} ---- +Provide insights on the stock's performance, including trends, volatility, and any notable events. +""" -## **4. Building the Framework: A Task Checklist** - -### **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. - -### **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. - -### **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. - -### **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. +analysis = agent.run(analysis_request) +print(analysis) +``` ---- +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. -## **5. Integration and Communication Mechanisms** +### Alpha Vantage -### **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. +Next, let's create an agent that can work with Alpha Vantage data to perform fundamental analysis. -### **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. +```python +import os +from swarms import Agent +from swarms.models import OpenAIChat +from dotenv import load_dotenv +import requests ---- +load_dotenv() -## **6. Conclusion & Forward Path** +# Alpha Vantage API setup +ALPHA_VANTAGE_API_KEY = os.getenv("ALPHA_VANTAGE_API_KEY") +ALPHA_VANTAGE_BASE_URL = "https://www.alphavantage.co/query" -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. +# 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 +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 +) -# Overview +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. Model +# Example usage +symbol = "MSFT" -**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. +income_statement = get_income_statement(symbol) -**Diagram:** -``` -[ Model (openai) ] -``` +analysis_request = f""" +Analyze the following income statement data for {symbol}: -### 2. Agent Level +{income_statement} -**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. +Provide insights on the company's financial health, profitability trends, and any notable observations. +""" -**Diagram:** -``` -+-----------+ -| Agent | -| +-------+ | -| | Model | | -| +-------+ | -| +-----------+ | -| | VectorStore | | -| +-----------+ | -| +-------+ | -| | Tools | | -| +-------+ | -+-----------+ +analysis = agent.run(analysis_request) +print(analysis) ``` -### 3. Worker Infrastructure Level - -**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 +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. -**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 +### Yahoo Finance -**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. +Now, let's create an agent that can work with Yahoo Finance data to perform technical analysis. +```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 +load_dotenv() -------- -# **Swarms Framework Development Strategy Checklist** +# OpenAI API setup +OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") -## **Introduction** +# Create an instance of the OpenAIChat class +model = OpenAIChat( + openai_api_key=OPENAI_API_KEY, + model_name="gpt-4", + temperature=0.1 +) -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. +# 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 +) ---- +def get_stock_data(symbol, start_date, end_date): + stock = yf.Ticker(symbol) + data = stock.history(start=start_date, end=end_date) + return data -## **1. Agent Level Development** +# Example usage +symbol = "GOOGL" +start_date = "2023-01-01" +end_date = "2023-12-31" -### **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. +stock_data = get_stock_data(symbol, start_date, end_date) -### **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. +# 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() -### **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. +analysis_request = f""" +Analyze the following stock price data and technical indicators for {symbol} from {start_date} to {end_date}: ---- +{stock_data.tail(30).to_string()} -## **2. Worker Infrastructure Level Development** +Provide insights on the stock's price trends, potential support and resistance levels, and any notable trading signals based on the moving averages. +""" -### **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. +analysis = agent.run(analysis_request) +print(analysis) +``` -### **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. +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. -### **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. +### IEX Cloud ---- +Let's create an agent that can work with IEX Cloud data to analyze company news sentiment. -## **3. Swarm Level Development** +```python +import os +from swarms import Agent +from swarms.models import OpenAIChat +from dotenv import load_dotenv +import requests -### **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. +load_dotenv() -### **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. +# IEX Cloud API setup +IEX_CLOUD_API_KEY = os.getenv("IEX_CLOUD_API_KEY") +IEX_CLOUD_BASE_URL = "https://cloud.iexapis.com/stable" -### **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. +# 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 +) -## **4. Hivemind Level Development** +# 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 +) -### **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. +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() -### **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. +# Example usage +symbol = "TSLA" +last_n = 10 ---- +news_data = get_company_news(symbol, last_n) -## **5. Scalability & Performance Testing** +analysis_request = f""" +Analyze the following recent news articles for {symbol}: -- [ ] 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. +{news_data} ---- +Provide insights on the overall sentiment of the news, potential impact on the stock price, and any notable trends or events mentioned. +""" -## **6. Documentation & User Guide** +analysis = agent.run(analysis_request) +print(analysis) +``` -- [ ] 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. +This example demonstrates an AI agent that can fetch recent news data from IEX Cloud and perform a sentiment analysis on the company news. ---- +### Finnhub -## **7. Continuous Integration & Deployment** +Finally, let's create an agent that can work with Finnhub data to analyze earnings estimates and recommendations. -- [ ] 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. - ---- - -## **Conclusion** - -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. - -(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.) - --------------------------------------------------- - -# File: corporate\bounties.md - -# Bounty Program +```python +import os +from swarms import Agent +from swarms.models import OpenAIChat +from dotenv import load_dotenv +import finnhub -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. +load_dotenv() -Here's how it works: +# Finnhub API setup +FINNHUB_API_KEY = os.getenv("FINNHUB_API_KEY") +finnhub_client = finnhub.Client(api_key=FINNHUB_API_KEY) -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. +# OpenAI API setup +OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") -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. +# Create an instance of the OpenAIChat class +model = OpenAIChat( + openai_api_key=OPENAI_API_KEY, + model_name="gpt-4", + temperature=0.1 +) -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. +# 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 +) -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. +def get_earnings_estimates(symbol): + return finnhub_client.earnings_calendar(symbol=symbol, from_date="2023-01-01", to_date="2023-12-31") -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. +def get_recommendations(symbol): + return finnhub_client.recommendation_trends(symbol) -## The Three Phases of Our Bounty Program +# Example usage +symbol = "NVDA" -### 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. +earnings_estimates = get_earnings_estimates(symbol) +recommendations = get_recommendations(symbol) -### 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. +analysis_request = f""" +Analyze the following earnings estimates and recommendations for {symbol}: -### 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. +Earnings Estimates: +{earnings_estimates} -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. +Recommendations: +{recommendations} -**To participate in our bounty program, visit the [Swarms Bounty Program Page](https://swarms.ai/bounty).** Let's build the future together! +Provide insights on the company's expected financial performance, analyst sentiment, and any notable trends in the recommendations. +""" +analysis = agent.run(analysis_request) +print(analysis) +``` +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 +To further enhance the capabilities of our AI agents, we can implement more advanced analysis techniques: -## Bounties for Roadmap Items +1. Multi-source analysis: Combine data from multiple providers to get a more comprehensive view of a stock or market. -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: +2. Time series forecasting: Implement machine learning models for price prediction. -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 +3. Sentiment analysis of social media: Incorporate data from social media platforms to gauge market sentiment. -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. +4. Portfolio optimization: Use AI agents to suggest optimal portfolio allocations based on risk tolerance and investment goals. -# 3-Phase Testing Framework +5. Anomaly detection: Implement algorithms to detect unusual patterns or events in financial data. -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. +Here's an example of how we might implement a multi-source analysis: -## 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. +```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 -## 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. +load_dotenv() -## 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. +# 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") -By following this 3-phase testing framework, we aim to develop a reliable, high-performing, and scalable Swarm that can automate all digital activities. +# Create an instance of the OpenAIChat class +model = OpenAIChat( + openai_api_key=OPENAI_API_KEY, + model_name="gpt-4", + temperature=0.1 +) -# Reverse Engineering to Reach Phase 3 +# 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 +) -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: +def get_stock_data_yf(symbol, start_date, end_date): + stock = yf.Ticker(symbol) + return stock.history(start=start_date, end=end_date) -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. +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']) -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. +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() -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. +# Example usage +symbol = "AAPL" +start_date = "2023-01-01" +end_date = "2023-12-31" -4. **Execute the Tests**: Run the test cases on our Swarm, making note of any issues or bugs that arise. +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) -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. +analysis_request = f""" +Analyze the following data for {symbol} from {start_date} to {end_date}: -6. **Repeat**: Repeat this process until our Swarm meets our expectations and passes all test cases. +Yahoo Finance Data: +{yf_data.tail().to_string()} -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. +Polygon.io Data: +{polygon_data.tail().to_string()} -Let's shape the future of digital automation together! +Alpha Vantage Company Overview: +{av_overview} +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 +""" --------------------------------------------------- +analysis = agent.run(analysis_request) +print(analysis) +``` -# File: corporate\bounty_program.md +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. -# Swarms Bounty Program +Now, let's explore some additional advanced analysis techniques: -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. +### Time Series Forecasting -## Why Contribute? +We can implement a simple time series forecasting model using the Prophet library and integrate it with our AI agent: -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. +```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 -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. +load_dotenv() -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. +OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") -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. +model = OpenAIChat( + openai_api_key=OPENAI_API_KEY, + model_name="gpt-4", + temperature=0.1 +) -## How It Works +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 +) -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. +def get_stock_data(symbol, start_date, end_date): + stock = yf.Ticker(symbol) + data = stock.history(start=start_date, end=end_date) + return data -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. +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 -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. +# Example usage +symbol = "MSFT" +start_date = "2020-01-01" +end_date = "2023-12-31" -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. +stock_data = get_stock_data(symbol, start_date, end_date) +forecast = forecast_stock_price(stock_data) -## 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. +analysis_request = f""" +Analyze the following time series forecast for {symbol}: -- Ensure your code is clean, modular, and well-documented. Contributions that adhere to the project's standards are more likely to be accepted. +Forecast Data: +{forecast.tail(30).to_string()} -- Actively communicate with the Swarms team and other contributors. Clear communication helps resolve uncertainties, avoids duplication, and fosters collaboration within the community. +The forecast plot has been saved as 'forecast_plot.png'. -## Get Involved +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 +""" -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. +analysis = agent.run(analysis_request) +print(analysis) +``` -2. **Stay Updated**: - - Keep track of the latest updates, announcements, and bounty opportunities by regularly checking the Discord channel and the GitHub repository. +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. -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. +### Sentiment Analysis of Social Media -## Additional Benefits +We can use a pre-trained sentiment analysis model to analyze tweets about a company and integrate this with our AI agent: -Beyond monetary rewards, contributors gain intangible benefits that elevate their professional journey: +```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 -- **Recognition**: Your contributions will be showcased to a community of over 9,000 engineers, increasing your visibility and credibility in the AI field. +load_dotenv() -- **Portfolio Building**: Add high-impact contributions to your portfolio, demonstrating your skills and experience to potential employers or collaborators. +# 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") -- **Knowledge Sharing**: Learn from and collaborate with experts in agent engineering, gaining insights into the latest advancements and best practices in the field. +auth = tweepy.OAuthHandler(TWITTER_API_KEY, TWITTER_API_SECRET) +auth.set_access_token(TWITTER_ACCESS_TOKEN, TWITTER_ACCESS_TOKEN_SECRET) +api = tweepy.API(auth) -## Contact Us -For any questions, support, or clarifications, reach out to the Swarms team: +# OpenAI setup +OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") -- **Discord**: Engage directly with the team and fellow contributors in our active channels. +model = OpenAIChat( + openai_api_key=OPENAI_API_KEY, + model_name="gpt-4", + temperature=0.1 +) -- **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. +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 +) ---- +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] -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! +def analyze_sentiment(tweets): + sentiments = [TextBlob(tweet).sentiment.polarity for tweet in tweets] + return pd.DataFrame({'tweet': tweets, 'sentiment': sentiments}) +# Example usage +symbol = "TSLA" +query = f"${symbol} stock" +tweets = get_tweets(query) +sentiment_data = analyze_sentiment(tweets) --------------------------------------------------- +analysis_request = f""" +Analyze the following sentiment data for tweets about {symbol} stock: -# File: corporate\checklist.md +Sentiment Summary: +Positive tweets: {sum(sentiment_data['sentiment'] > 0)} +Negative tweets: {sum(sentiment_data['sentiment'] < 0)} +Neutral tweets: {sum(sentiment_data['sentiment'] == 0)} -# **Swarms Framework Development Strategy Checklist** +Average sentiment: {sentiment_data['sentiment'].mean()} -## **Introduction** +Sample tweets and their sentiments: +{sentiment_data.head(10).to_string()} -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. +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 +""" ---- +analysis = agent.run(analysis_request) +print(analysis) +``` -## **1. Agent Level Development** +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.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. +### Portfolio Optimization -### **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. +We can use the PyPortfolioOpt library to perform portfolio optimization and have our AI agent provide insights: -### **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. +```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 ---- +load_dotenv() -## **2. Worker Infrastructure Level Development** +OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") -### **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. +model = OpenAIChat( + openai_api_key=OPENAI_API_KEY, + model_name="gpt-4", + temperature=0.1 +) -### **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. +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 +) -### **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. +def get_stock_data(symbols, start_date, end_date): + data = yf.download(symbols, start=start_date, end=end_date)['Adj Close'] + return data ---- +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 -## **3. Swarm Level Development** +# Example usage +symbols = ["AAPL", "GOOGL", "MSFT", "AMZN", "FB"] +start_date = "2018-01-01" +end_date = "2023-12-31" -### **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. +stock_data = get_stock_data(symbols, start_date, end_date) +optimized_weights = optimize_portfolio(stock_data) -### **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_request = f""" +Analyze the following optimized portfolio allocation: -### **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. +{pd.Series(optimized_weights).to_string()} ---- +The optimization aimed to maximize the Sharpe ratio based on historical data from {start_date} to {end_date}. -## **4. Hivemind Level Development** +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 +""" -### **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. +analysis = agent.run(analysis_request) +print(analysis) +``` -### **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. +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 -## **5. Scalability & Performance Testing** +When using AI agents for financial data analysis, consider the following best practices: -- [ ] 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. +1. Data quality: Ensure that the data you're feeding into the agents is accurate and up-to-date. ---- +2. Model limitations: Be aware of the limitations of both the financial models and the AI models being used. -## **6. Documentation & User Guide** +3. Regulatory compliance: Ensure that your use of AI in financial analysis complies with relevant regulations. -- [ ] 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. +4. Ethical considerations: Be mindful of potential biases in AI models and strive for fair and ethical analysis. ---- +5. Continuous monitoring: Regularly evaluate the performance of your AI agents and update them as needed. -## **7. Continuous Integration & Deployment** +6. Human oversight: While AI agents can provide valuable insights, human judgment should always play a role in financial decision-making. -- [ ] 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. +7. Privacy and security: Implement robust security measures to protect sensitive financial data. ---- +## Conclusion -## **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. -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. +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. -(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.) +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: corporate\cost_analysis.md - -# Costs Structure of Deploying Autonomous Agents - -## Table of Contents - -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 +# File: guides\healthcare_blog.md ---- +# Unlocking Efficiency and Cost Savings in Healthcare: How Swarms of LLM Agents Can Revolutionize Medical Operations and Save Millions -## 1. Introduction +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. -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. +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. Administrative Automation -## 2. Our Time: Generating System Prompts and Custom Tools +#### Use Case: Billing and Claims Processing -### Description +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. -The deployment of autonomous agents often requires a substantial investment of time to develop system prompts and custom tools tailored to specific operational needs. +**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. -### Costs +**Estimated Savings:** -| 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** | +- Average cost per manual claim: $25 ---- +- Average claims per hospital: 10,000 per month -## 3. Consultancy Fees +- Swarms of LLM agents can reduce processing time by 90% and errors by 95% -### Description +- Estimated annual savings per hospital: -Consultation is often necessary for navigating the complexities of autonomous agents. This includes system assessment, customization, and other essential services. + - Savings per claim: $22.5 (90% reduction) -### Costs + - Total annual savings: 10,000 claims/month × 12 months × $22.5 = **$2.7 million** -| Service | Fees ($) | -| -------------------- | --------- | -| Initial Assessment | 5,000 | -| System Customization | 7,000 | -| Training | 3,000 | -| **Total** | **15,000**| ---- +#### 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]; +``` -## 4. Model Inference Infrastructure +### 2. Enhancing Clinical Decision Support -### Description +#### Use Case: Diagnostic Assistance -The hardware and software needed for the agent's functionality, known as the model inference infrastructure, form a significant part of the costs. +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. -### Costs +**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. -| Component | Cost ($) | -| -------------------- | --------- | -| Hardware | 10,000 | -| Software Licenses | 2,000 | -| Cloud Services | 3,000 | -| **Total** | **15,000**| +**Estimated Savings:** ---- +- Time saved per diagnosis: 2 hours per patient -## 5. Deployment and Continual Maintenance +- Average patient cases per hospital: 5,000 per year -### Description +- Time saved annually: 2 × 5,000 = 10,000 hours -Once everything is in place, deploying the autonomous agents and their ongoing maintenance are the next major cost factors. +- Doctor's hourly rate: $150 -### Costs +- Total annual savings: 10,000 × $150 = **$1.5 million** -| Task | Monthly Cost ($) | Annual Cost ($) | -| ------------------- | ---------------- | --------------- | -| Deployment | 5,000 | 60,000 | -| Ongoing Maintenance | 1,000 | 12,000 | -| **Total** | **6,000** | **72,000** | ---- +#### 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]; +``` -## 6. Output Metrics: Blogs Generation Rates +### 3. Streamlining Patient Communication -### Description +#### Use Case: Patient Follow-ups and Reminders -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. +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. -### Blogs Generation Rates +**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. -| Timeframe | Number of Blogs | -|-----------|-----------------| -| Per Day | 20 | -| Per Week | 140 | -| Per Month | 600 | +**Estimated Savings:** +- Average cost per patient follow-up: $5 +- Number of follow-ups: 20,000 annually per hospital +- Swarm efficiency: 90% reduction in manual effort --------------------------------------------------- +- Total annual savings: 20,000 × $4.5 = **$90,000** -# File: corporate\culture.md -# Swarms Corp Culture Document +#### 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]; +``` -## **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. +### 4. Optimizing Inventory Management -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. +#### Use Case: Pharmaceutical Stock Management -## **Values We Live By** +Hospitals often struggle with managing pharmaceutical inventory efficiently. Overstocking leads to wasted resources, while understocking can be a critical problem for patient care. -### 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. +**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. -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. +**Estimated Savings:** -### 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. +- Annual waste due to overstocking: $500,000 per hospital -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. +- Swarm efficiency: 80% reduction in overstocking -### 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: $500,000 × 0.8 = **$400,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. +#### 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]; +``` -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. +### 5. Improving Clinical Research -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. +#### Use Case: Literature Review and Data Analysis -## **Our Way of Working** +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. -- **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. +**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. -- **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. +**Estimated Savings:** -- **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. +- Average time spent on literature review per paper: 5 hours -- **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. +- Number of papers reviewed annually: 1,000 -## **Expectations** +- Time saved: 80% reduction in review time -- **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. +- Total time saved: 1,000 × 5 × 0.8 = 4,000 hours -- **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. +- Researcher's hourly rate: $100 -- **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. +- Total annual savings: 4,000 × $100 = **$400,000** -- **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. -## **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. +#### 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]; +``` -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. +### 6. Automating Medical Record Keeping +#### Use Case: EHR Management and Documentation +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. -# File: corporate\data_room.md +**Estimated Savings:** -# Swarms Data Room +- Average time spent on EHR per patient: 20 minutes -## Table of Contents +- Number of patients annually: 30,000 -**Introduction** +- Time saved: 80% reduction in manual effort -- Overview of the Company +- Total time saved: 30,000 × 20 minutes × 0.8 = 480,000 minutes or 8,000 hours -- Vision and Mission Statement +- Provider's hourly rate: $150 -- Executive Summary +- Total annual savings: 8,000 × $150 = **$1.2 million** -**Corporate Documents** -- Articles of Incorporation +#### 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]; +``` -- Bylaws +### 7. Reducing Diagnostic Errors -- Shareholder Agreements +#### Use Case: Medical Imaging Analysis -- Board Meeting Minutes +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. -- Company Structure and Org Chart +**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. -**Financial Information** +**Estimated Savings:** -- Historical Financial Statements - - - Income Statements +- Time saved per scan: 30 minutes - - Balance Sheets +- Number of scans annually: 10,000 - - Cash Flow Statements +- Time saved: 10,000 × 30 minutes = 5,000 hours -- Financial Projections and Forecasts +- Radiologist's hourly rate: $200 -- Cap Table +- Total annual savings: 5,000 × $ -- Funding History and Use of Funds -**Products and Services** +200 = **$1 million** -- Detailed Descriptions of Products/Services +#### 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]; +``` -- Product Development Roadmap +### Conclusion: The Financial and Time-Saving Impact of LLM Swarms in Healthcare -- User Manuals and Technical Specifications -- Case Studies and Use Cases +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. -## **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. +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. -### **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. +The future of healthcare is agentic, and by embracing swarms of LLM agents, your organization can unlock unprecedented levels of productivity and savings. -### **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. +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. -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. +The table below summarizes the estimated savings for each use case: -Our business model focuses on customer satisfaction, openness, integration with other tools/platforms, and production-grade reliability. +| 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** | -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. +### References +- [Swarms GitHub](https://github.com/kyegomez/swarms) -The team has thousands of hours building and optimizing autonomous agents. Leadership includes AI engineers, product experts, open source contributors and community builders. +- [Swarms Website](https://swarms.xyz) -Key milestones: get 80K framework users in January 2024, start contracts in target verticals, introduce commercial products in 2025 with various pricing models. +- [book a call](https://cal.com/swarms) -### **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) +- 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 -## **Financial Documents** -This section is dedicated entirely for corporate documents. +By adopting swarms of LLM agents, healthcare organizations can streamline operations, reduce inefficiencies, and focus on what truly matters—delivering top-notch patient care. -- [Cap Table](https://docs.google.com/spreadsheets/d/1wuTWbfhYaY5Xp6nSQ9R0wDtSpwSS9coHxsjKd0UbIDc/edit?usp=sharing) -- [Cashflow Prediction Sheet](https://docs.google.com/spreadsheets/d/1HQEHCIXXMHajXMl5sj8MEfcQtWfOnD7GjHtNiocpD60/edit?usp=sharing) +-------------------------------------------------- ------- +# File: guides\pricing.md -## **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. +# Comparing LLM Provider Pricing: A Guide for Enterprises -- [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) +Large language models (LLMs) have become a cornerstone of innovation for enterprises across various industries. -### 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) | +As executives contemplate which model to integrate into their operations, understanding the intricacies of LLM provider pricing is crucial. +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. +## Table of Contents +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) --------------------------------------------------- +## 1. Introduction to LLM Pricing Models -# File: corporate\demos.md +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. -# Demo Ideas +### Pay-per-Token Model -* 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. +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. -* 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 +**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. -* Swarm of AI influencers to spread marketing +**Disadvantages:** +- Unpredictability: Costs can vary significantly based on the verbosity of inputs and outputs. +- Potential for overruns: Without proper monitoring, costs can quickly escalate. -* 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 +### Subscription-Based Models +Some providers offer subscription tiers that provide a set amount of compute resources or tokens for a fixed monthly or annual fee. --------------------------------------------------- +**Advantages:** +- Predictable costs: Easier budgeting and financial planning. +- Potential cost savings: Can be more economical for consistent, high-volume usage. -# File: corporate\design.md +**Disadvantages:** +- Less flexibility: May lead to underutilization or overages. +- Commitment required: Often involves longer-term contracts. -# Design Philosophy Document for Swarms +### Custom Enterprise Agreements -## Usable +For large-scale deployments, providers may offer custom pricing agreements tailored to the specific needs of an enterprise. -### Objective +**Advantages:** +- Optimized for specific use cases: Can include specialized support, SLAs, and pricing structures. +- Potential for significant cost savings at 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. +**Disadvantages:** +- Complexity: Negotiating and managing these agreements can be resource-intensive. +- Less standardization: Difficult to compare across providers. -### Tactics +### Hybrid Models -- 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. +Some providers are beginning to offer hybrid models that combine elements of pay-per-token and subscription-based pricing. -## Reliable +**Advantages:** +- Flexibility: Can adapt to varying usage patterns. +- Risk mitigation: Balances the benefits of both main pricing models. -### Objective +**Disadvantages:** +- Complexity: Can be more challenging to understand and manage. +- Potential for suboptimal pricing if not carefully structured. -Swarms should be dependable and trustworthy. Users should be able to count on Swarms to perform consistently and without error or failure. +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. -### Tactics +## 2. Understanding Unit Economics in LLM Deployment -- 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. +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. -## Fast +### Defining the Unit -### Objective +In the context of LLMs, a "unit" can be defined in several ways: -Swarms should offer high performance and rapid response times. The system should be able to handle requests and tasks swiftly. +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. -### Tactics +Understanding which unit is most relevant to your use case is crucial for accurate economic analysis. -- 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. +### Components of Unit Cost -## Scalable +1. **Direct LLM Costs** + - Token processing fees + - API call charges + - Data transfer costs -### Objective +2. **Indirect Costs** + - Compute resources for pre/post-processing + - Storage for inputs, outputs, and fine-tuning data + - Networking costs -Swarms should be able to grow in capacity and complexity without compromising performance or reliability. It should be able to handle increased workloads gracefully. +3. **Operational Costs** + - Monitoring and management tools + - Integration and maintenance engineering time + - Customer support related to AI functions -### Tactics +4. **Overhead** + - Legal and compliance costs + - Training and documentation + - Risk management and insurance -- 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. +### Calculating Unit Economics -### Philosophy +To calculate the true unit economics, follow these steps: -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. **Determine Total Costs**: Sum all direct, indirect, operational, and overhead costs over a fixed period (e.g., monthly). -# Swarm Architecture Design Document +2. **Measure Total Units**: Track the total number of relevant units processed in the same period. -## Overview +3. **Calculate Cost per Unit**: Divide total costs by total units. -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. + ``` + Cost per Unit = Total Costs / Total Units + ``` -## Design Principles +4. **Analyze Revenue per Unit**: If the LLM is part of a revenue-generating product, calculate the revenue attributed to each unit. -- **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. +5. **Determine Profit per Unit**: Subtract the cost per unit from the revenue per unit. -## Design Components + ``` + Profit per Unit = Revenue per Unit - Cost per Unit + ``` -### BaseSwarm +### Example Calculation -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. +Let's consider a hypothetical customer service AI chatbot: -### Swarm Classes +- Monthly LLM API costs: $10,000 +- Indirect and operational costs: $5,000 +- Total monthly interactions: 100,000 -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. +``` +Cost per Interaction = ($10,000 + $5,000) / 100,000 = $0.15 +``` -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. +If each interaction generates an average of $0.50 in value (through cost savings or revenue): -### Tools and Agents +``` +Profit per Interaction = $0.50 - $0.15 = $0.35 +``` -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. +### Economies of Scale -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. +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 -Users can either use pre-configured swarms or create their own custom 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. -To use a pre-configured swarm, they can simply instantiate the corresponding swarm class and call the run method with the required objective. +### Diseconomies of Scale -To create a custom swarm, they need to: +Conversely, be aware of potential diseconomies of scale: -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. +- Increased complexity in managing large-scale deployments +- Higher costs for specialized talent as operations grow +- Potential for diminishing returns on very large language models -### Example +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. -```python -# Using pre-configured swarm -swarm = PreConfiguredSwarm(openai_api_key) -swarm.run_swarms(objective) +## 3. Profit Margins and Cost Structures -# Creating custom swarm -class CustomSwarm(BaseSwarm): - # Implement required methods +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. -swarm = CustomSwarm(openai_api_key) -swarm.run_swarms(objective) -``` +### Components of Profit Margin -## Conclusion +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 + ``` -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. +2. **Contribution Margin**: Gross margin minus variable operational costs. + ``` + Contribution Margin = Gross Margin - Variable Operational Costs + ``` +3. **Net Margin**: The final profit after all costs, including fixed overheads. + ``` + Net Margin = Contribution Margin - Fixed Costs + Net Margin % = (Net Margin / Revenue) * 100 + ``` -# Swarming Architectures -Sure, below are five different swarm architectures with their base requirements and an abstract class that processes these components: +### Cost Structures in LLM Deployment -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. +1. **Fixed Costs** + - Subscription fees for LLM access (if using a subscription model) + - Base infrastructure costs + - Core team salaries + - Licensing fees for essential software -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. +2. **Variable Costs** + - Per-token or per-request charges + - Scaling infrastructure costs + - Usage-based API fees + - Performance-based team bonuses -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. +3. **Step Costs** + - Costs that increase in chunks as usage scales + - Examples: Adding new server clusters, hiring additional support staff -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. +### Analyzing Profit Margins Across Different Pricing Models -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. +Let's compare how different LLM pricing models might affect profit margins for a hypothetical AI-powered writing assistant service: +**Scenario**: The service charges users $20/month and expects to process an average of 100,000 tokens per user per month. -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). +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%) -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. +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%) -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. +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%) -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. +### Strategies for Improving Profit Margins -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. +1. **Optimize Token Usage** + - Implement efficient prompting techniques + - Cache common responses + - Use compression algorithms for inputs and outputs -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. +2. **Leverage Economies of Scale** + - Negotiate better rates at higher volumes + - Spread fixed costs across a larger user base +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) --------------------------------------------------- +4. **Vertical Integration** + - Invest in proprietary LLM development for core functionalities + - Reduce dependency on third-party providers for critical operations -# File: corporate\distribution.md +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 -# Swarms Monetization Strategy +Consider a company that initially used a pay-per-token model: -This strategy includes a variety of business models, potential revenue streams, cashflow structures, and customer identification methods. Let's explore these further. +**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%) -## Business Models +**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 -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. +**Result:** +- New LLM cost per user: $4.32 +- New net margin per user: $12.68 (50.7%) -2. **API Usage-based Pricing:** Charge customers based on their usage of the Swarms API. The more requests made, the higher the fee. +This case study demonstrates how a holistic approach to margin improvement, addressing both revenue and various cost components, can significantly enhance profitability. -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. +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. -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. +## 4. LLM Pricing in Action: Case Studies -5. **Partnerships:** Collaborate with large enterprises and offer them dedicated Swarm AI services. These could be performance-based contracts, ensuring a mutually beneficial relationship. +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. -6. **Data as a Service (DaaS):** Leverage the data generated by Swarms for insights and analytics, providing valuable business intelligence to clients. +### Case Study 1: E-commerce Product Description Generator -## Potential Revenue Streams +**Company**: GlobalMart, a large online retailer +**Use Case**: Automated generation of product descriptions +**LLM Provider**: GPT-4o -1. **Subscription Fees:** This would be the main revenue stream from providing the Swarms platform as a service. +**Pricing Model**: Pay-per-token +- Input: $5.00 per 1M tokens +- Output: $15.00 per 1M tokens -2. **Usage Fees:** Additional revenue can come from usage fees for businesses that have high demand for Swarms API. +**Usage Pattern**: +- Average input: 50 tokens per product (product attributes) +- Average output: 200 tokens per product (generated description) +- Daily products processed: 10,000 -3. **Contract Fees:** From offering managed services and bespoke solutions to businesses. +**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 -4. **Training Fees:** Revenue from providing training and certification programs to developers and businesses. +**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) -5. **Partnership Contracts:** Large-scale projects with enterprises, involving dedicated Swarm AI services, could provide substantial income. +**ROI Analysis**: +- Daily investment: $32.50 +- Daily return: $500 +- ROI = (Return - Investment) / Investment * 100 = 1,438% -6. **Data Insights:** Revenue from selling valuable business intelligence derived from Swarm's aggregated and anonymized data. +**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. -## Potential Customers +### Case Study 2: Customer Service Chatbot -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. +**Company**: TechSupport Inc., a software company +**Use Case**: 24/7 customer support chatbot +**LLM Provider**: Claude 3.5 Sonnet -2. **Developers:** Both freelance and those working in organizations could use Swarms to enhance their projects and services. +**Pricing Model**: Input: $3 per 1M tokens, Output: $15 per 1M tokens -3. **Enterprises:** Large enterprises looking to automate and optimize their operations could greatly benefit from Swarms. +**Usage Pattern**: +- Average conversation: 500 tokens input (customer queries + context), 1000 tokens output (bot responses) +- Daily conversations: 5,000 -4. **Educational Institutions:** Universities and research institutions could leverage Swarms for research and teaching purposes. +**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 -## Roadmap +**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) -1. **Landing Page Creation:** Develop a dedicated product page on apac.ai for Swarms. +**ROI Analysis**: +- Daily investment: $82.50 +- Daily return: $2,000 +- ROI = (Return - Investment) / Investment * 100 = 2,324% -2. **Hosted Swarms API:** Launch a cloud-based Swarms API service. It should be highly reliable, with robust documentation to attract daily users. +**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. -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. +### Case Study 3: Financial Report Summarization -4. **Dedicated Capacity Deals:** Partner with large enterprises to offer them dedicated Swarm AI solutions for automating their operations. +**Company**: FinAnalyze, a financial services firm +**Use Case**: Automated summarization of lengthy financial reports +**LLM Provider**: GPT-3.5 Turbo -5. **Enterprise Partnerships:** Develop partnerships with large enterprises for extensive contract-based projects. +**Pricing Model**: Input: $0.50 per 1M tokens, Output: $1.50 per 1M tokens -6. **Integration with Collaboration Platforms:** Develop Swarms bots for platforms like Discord and Slack, charging users a subscription fee for access. +**Usage Pattern**: +- Average report: 20,000 tokens input, 2,000 tokens output +- Daily reports processed: 100 -7. **Personal Data Instances:** Offer users dedicated instances of all their data that the Swarm can query as needed. +**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. **Browser Extension:** Develop a browser extension that integrates with the Swarms platform, offering users a more seamless experience. +**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) -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. +**ROI Analysis**: +- Daily investment: $130 +- Daily return: $1,000 +- ROI = (Return - Investment) / Investment * 100 = 669% ----- +**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. -# Other ideas +### Case Study 4: AI-Powered Language Learning App -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. +**Company**: LinguaLeap, an edtech startup +**Use Case**: Personalized language exercises and conversations +**LLM Provider**: Claude 3 Haiku -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. +**Pricing Model**: Input: $0.25 per 1M tokens, Output: $1.25 per 1M tokens -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. +**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 -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. +**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 -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. +**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) -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. +**ROI Analysis**: +- Daily investment: $105 +- Daily revenue: $5,000 +- ROI = (Revenue - Investment) / Investment * 100 = 4,662% -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. +**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. -**Product Brief Monetization Strategy:** +### Case Study 5: Legal Document Analysis -Product Name: Swarms.AI Platform +**Company**: LegalEagle LLP, a large law firm +**Use Case**: Contract review and risk assessment +**LLM Provider**: Claude 3 Opus -Product Description: A cloud-based AI and ML platform harnessing the power of swarm intelligence. +**Pricing Model**: Input: $15 per 1M tokens, Output: $75 per 1M tokens -1. **Platform as a Service (PaaS):** Offer tiered subscription plans (Basic, Premium, Enterprise) to accommodate different usage levels and business sizes. +**Usage Pattern**: +- Average contract: 10,000 tokens input, 3,000 tokens output (analysis and risk assessment) +- Daily contracts processed: 50 -2. **Professional Services:** Offer consultancy and custom development services to tailor the Swarms solution to the specific needs of the business. +**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 -3. **Education and Training:** Launch an online Swarms.AI Academy with courses and certifications for developers and businesses. +**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) -4. **Managed Services:** Provide a premium, fully-managed service offering that includes hosting, maintenance, and 24/7 support. +**ROI Analysis**: +- Daily investment: $18.75 +- Daily value: $10,000 +- ROI = (Value - Investment) / Investment * 100 = 53,233% -5. **Data Analysis and Insights:** Offer industry reports and customized insights generated from aggregated and anonymized Swarm data. +**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. -Potential Customers: Enterprises in sectors such as logistics, eCommerce, finance, and technology. This can be sold globally, provided there's an internet connection. +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. -Marketing Channels: Online marketing (SEO, Content Marketing, Social Media), Partnerships with tech companies, Direct Sales to Enterprises. +## 5. Calculating ROI for LLM Integration -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. +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. -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. +### The ROI Formula -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. +The basic ROI formula is: -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. +``` +ROI = (Net Benefit / Cost of Investment) * 100 +``` -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. +For LLM integration, we can expand this to: -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. +``` +ROI = ((Total Benefits - Total Costs) / Total Costs) * 100 +``` -**Type of Platform:** +### Identifying Benefits -Cloud-based platform or Software as a Service (SaaS) will be a suitable model. It offers accessibility, scalability, and ease of updates. +1. **Direct Cost Savings** + - Reduced labor costs + - Decreased operational expenses + - Lower error-related costs -**Target Customers:** +2. **Revenue Increases** + - New product offerings enabled by LLM + - Improved customer acquisition and retention + - Upselling and cross-selling opportunities -The technology can be beneficial for businesses across sectors like eCommerce, technology, logistics, finance, healthcare, and education, among others. +3. **Productivity Gains** + - Time saved on repetitive tasks + - Faster decision-making processes + - Improved employee efficiency -**Product Brief Monetization Strategy:** +4. **Quality Improvements** + - Enhanced accuracy in outputs + - Consistency in service delivery + - Reduced error rates -Product Name: Swarms.AI +5. **Strategic Advantages** + - Market differentiation + - Faster time-to-market for new offerings + - Improved competitive positioning -1. **AI Solution as a Service:** Offer different tiered subscriptions (Standard, Premium, and Enterprise) each with varying levels of usage and features. +### Calculating Costs -2. **Integration and Custom Development:** Offer custom development and integration services, priced based on the scope and complexity of the project. +1. **Direct LLM Costs** + - API usage fees + - Subscription costs -3. **Training and Certification:** Launch the Swarms.AI Academy with courses and certifications, available for a fee. +2. **Infrastructure Costs** + - Cloud computing resources + - Data storage + - Networking expenses -4. **Managed Swarms Solutions:** Offer fully managed solutions tailored to business needs, priced based on scope and service level agreements. +3. **Integration and Development Costs** + - Initial setup and integration + - Ongoing maintenance and updates + - Custom feature development -5. **Data Analytics Services:** Provide insightful reports and data analyses, which can be purchased on a one-off basis or through a subscription. +4. **Training and Support** + - Employee training programs + - User support and documentation + - Change management initiatives -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. +5. **Compliance and Security** + - Data privacy measures + - Security audits and implementations + - Regulatory compliance efforts +### Step-by-Step ROI Calculation +1. **Define the Time Period**: Determine the timeframe for your ROI calculation (e.g., 1 year, 3 years). -# Roadmap +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) -* Create a landing page for swarms apac.ai/product/swarms +3. **Calculate Total Costs**: + - Sum up all direct and indirect costs related to LLM integration -* 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. +4. **Apply the ROI Formula**: + ``` + ROI = ((Total Benefits - Total Costs) / Total Costs) * 100 + ``` -* 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. +5. **Consider Time Value of Money**: For longer-term projections, use Net Present Value (NPV) to account for the time value of money. -* Hosted dedicated capacity deals with mega enterprises on automating many operations with Swarms for monthly subscription 300,000+$ +### Example ROI Calculation -* Partnerships with enterprises, massive contracts with performance based fee +Let's consider a hypothetical customer service chatbot implementation: -* Have discord bot and or slack bot with users personal data, charge subscription + browser extension +**Time Period**: 1 year -* each user gets a dedicated ocean instance of all their data so the swarm can query it as needed. +**Benefits**: +- Labor cost savings: $500,000 +- Increased sales from improved customer satisfaction: $300,000 +- Productivity gains from faster query resolution: $200,000 +Total Benefits: $1,000,000 +**Costs**: +- LLM API fees: $100,000 +- Integration and development: $150,000 +- Training and support: $50,000 +- Infrastructure: $50,000 +Total Costs: $350,000 ---- ---- +**ROI Calculation**: +``` +ROI = (($1,000,000 - $350,000) / $350,000) * 100 = 185.7% +``` +This indicates a strong positive return on investment, with benefits outweighing costs by a significant margin. -# Swarms Monetization Strategy: A Revolutionary AI-powered Future +### Considerations for Accurate ROI Calculation -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. +1. **Be Conservative in Estimates**: It's better to underestimate benefits and overestimate costs to provide a more realistic view. -Here we outline our strategic monetization pathways and provide a roadmap that plots our course to future success. +2. **Account for Ramp-Up Time**: Full benefits may not be realized immediately. Consider a phased approach in your calculations. ---- +3. **Include Opportunity Costs**: Consider the potential returns if the investment were made elsewhere. -## I. Business Models +4. **Factor in Risk**: Adjust your ROI based on the likelihood of achieving projected benefits. -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. +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. -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. +6. **Perform Sensitivity Analysis**: Calculate ROI under different scenarios (best case, worst case, most likely) to understand the range of possible outcomes. -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. +7. **Benchmark Against Alternatives**: Compare the ROI of LLM integration against other potential investments or solutions. -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. +### Long-Term ROI Considerations -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. +While initial ROI calculations are crucial for decision-making, it's important to consider long-term implications: -6. **Data as a Service (DaaS):** Swarms generated data are mined for insights and analytics, with business intelligence reports offered from $500 each. +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? ---- +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. -## II. Potential Revenue Streams +## 6. Comparative Analysis of Major LLM Providers -1. **Subscription Fees:** From $50 to $500+ per month for platform access. +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. -2. **Usage Fees:** From $0.01 per API request, generating income from high platform usage. +### OpenAI -3. **Contract Fees:** Starting from $100,000 per month for managed services. - -4. **Training Fees:** From $200 to $2,000 for individual courses or subscription access. - -5. **Partnership Contracts:** Contracts starting from $100,000, offering major income potential. - -6. **Data Insights:** Business intelligence reports starting from $500. +**Models**: GPT-4o, GPT-3.5 Turbo ---- +**Pricing Structure**: +- Pay-per-token model +- Different rates for input and output tokens +- Bulk discounts available for high-volume users -## III. Potential Customers +**Key Features**: +- State-of-the-art performance on a wide range of tasks +- Regular model updates and improvements +- Extensive documentation and community support -1. **Businesses Across Sectors:** Our offerings cater to businesses across finance, eCommerce, logistics, healthcare, and more. +**Considerations**: +- Higher pricing compared to some competitors +- Potential for rapid price changes as technology evolves +- Usage limits and approval process for higher-tier models -2. **Developers:** Both freelancers and organization-based developers can leverage Swarms for their projects. +### Anthropic -3. **Enterprises:** Swarms offers large enterprises solutions for optimizing operations. +**Models**: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku -4. **Educational Institutions:** Universities and research institutions can use Swarms for research and teaching. +**Pricing Structure**: +- Pay-per-token model +- Different rates for input and output tokens +- Tiered pricing based on model capabilities ---- +**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) -## IV. Roadmap +**Considerations**: +- Newer to the market compared to OpenAI +- Potentially more limited third-party integrations +- Strong emphasis on responsible AI use -1. **Landing Page Creation:** Develop a dedicated Swarms product page on apac.ai. +### Google (Vertex AI) -2. **Hosted Swarms API:** Launch a reliable, well-documented cloud-based Swarms API service. +**Models**: PaLM 2 for Chat, PaLM 2 for Text -3. **Consumer and Enterprise Subscription Service:** Launch an extensive subscription service on The Domain, providing wide-ranging access to APIs and data streams. +**Pricing Structure**: +- Pay-per-thousand characters model +- Different rates for input and output +- Additional charges for advanced features (e.g., semantic retrieval) -4. **Dedicated Capacity Deals:** Offer large enterprises dedicated Swarm AI solutions, starting from $300,000 monthly subscription. +**Key Features**: +- Integration with Google Cloud ecosystem +- Multi-modal capabilities (text, image, audio) +- Enterprise-grade security and compliance features -5. **Enterprise Partnerships:** Develop performance-based contracts with large enterprises. +**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 -6. **Integration with Collaboration Platforms:** Develop Swarms bots for platforms like Discord and Slack, charging a subscription fee for access. +### Amazon (Bedrock) -7. **Personal Data Instances:** Offer users dedicated data instances that the Swarm can query as needed. +**Models**: Claude (Anthropic), Titan -8. **Browser Extension:** Develop a browser extension that integrates with the Swarms platform for seamless user experience. +**Pricing Structure**: +- Pay-per-second of compute time +- Additional charges for data transfer and storage ---- +**Key Features**: +- Seamless integration with AWS services +- Access to multiple model providers through a single API +- Fine-tuning and customization options -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**: +- Pricing model can be less predictable for inconsistent workloads +- Strong appeal for existing AWS customers +- Potential for cost optimizations through AWS ecosystem -## **Platform Distribution Strategy for Swarms** +### Microsoft (Azure OpenAI Service) -*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. +**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) -### **1. Framework:** +**Key Features**: +- Enterprise-grade security and compliance +- Integration with Azure AI services +- Access to fine-tuning and customization options -#### **Objective:** -To offer Swarms as an integrated solution within popular frameworks to ensure that developers and businesses can seamlessly incorporate its functionalities. +**Considerations**: +- Attractive for organizations already using Azure +- Potential for volume discounts through Microsoft Enterprise Agreements +- Additional overhead for Azure management -#### **Strategy:** +### Comparative Analysis -* **Language/Framework Integration:** - * Target popular frameworks like Django, Flask for Python, Express.js for Node, etc. - * Create SDKs or plugins for easy integration. +| 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 | -* **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. +### Factors to Consider in Provider Selection -* **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. +1. **Performance Requirements**: Assess whether you need state-of-the-art performance or if a less advanced (and potentially cheaper) model suffices. ---- +2. **Pricing Predictability**: Consider whether your usage patterns align better with token-based or compute-time-based pricing. -### **2. Paid API:** +3. **Integration Needs**: Evaluate how well each provider integrates with your existing technology stack. -#### **Objective:** -To provide a scalable solution for developers and businesses that want direct access to Swarms' functionalities without integrating the entire framework. +4. **Scalability**: Assess each provider's ability to handle your expected growth in usage. -#### **Strategy:** +5. **Customization Options**: Determine if you need fine-tuning or specialized model development capabilities. -* **API Endpoints:** - * Offer various endpoints catering to different functionalities. - * Maintain robust documentation to ensure ease of use. +6. **Compliance and Security**: Consider your industry-specific regulatory requirements and each provider's security offerings. -* **Monetization:** - * Usage-based Pricing: Charge based on the number of API calls. - * Subscription Tiers: Provide tiered packages based on usage limits and advanced features. +7. **Support and Documentation**: Evaluate the quality of documentation, community support, and enterprise-level assistance. -* **Promotion:** - * List on API marketplaces like RapidAPI. - * Engage in SEO to make the API documentation discoverable. +8. **Ethical Considerations**: Assess each provider's stance on AI ethics and responsible use. ---- +9. **Lock-In Concerns**: Consider the long-term implications of committing to a specific provider or cloud ecosystem. -### **3. Domain Hosted:** +10. **Multi-Provider Strategy**: Evaluate the feasibility and benefits of using multiple providers for different use cases. -#### **Objective:** -To provide a centralized web platform where users can directly access and engage with Swarms' offerings. +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. -#### **Strategy:** +## 7. Hidden Costs and Considerations -* **User-Friendly Interface:** - * Ensure a seamless user experience with intuitive design. - * Incorporate features like real-time chat support, tutorials, and an FAQ section. +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. -* **Monetization:** - * Subscription Model: Offer monthly/annual subscriptions for premium features. - * Affiliate Marketing: Partner with related tech products/services and earn through referrals. +### 1. Data Preparation and Cleaning -* **Promotion:** - * Invest in PPC advertising on platforms like Google Ads. - * Engage in content marketing, targeting keywords related to Swarms' offerings. +**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 -### **4. Build Your Own (No-Code Platform):** +### 2. Fine-Tuning and Customization -#### **Objective:** -To cater to the non-developer audience, allowing them to leverage Swarms' features without any coding expertise. +**Considerations**: +- Costs associated with creating custom datasets +- Compute resources required for fine-tuning +- Potential need for specialized ML expertise -#### **Strategy:** +**Impact**: +- Can significantly improve model performance for specific tasks +- May lead to better ROI in the long run +- Increases initial implementation costs -* **Drag-and-Drop Interface:** - * Offer customizable templates. - * Ensure integration with popular platforms and apps. +### 3. Integration and Development -* **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. +**Considerations**: +- Engineering time for API integration +- Development of custom interfaces or applications +- Ongoing maintenance and updates -* **Promotion:** - * Partner with no-code communities and influencers. - * Offer promotions and discounts to early adopters. +**Impact**: +- Can be substantial, especially for complex integrations +- May require hiring additional developers or consultants +- Critical for seamless user experience and workflow integration ---- +### 4. Monitoring and Optimization -### **5. Marketplace for the No-Code Platform:** +**Considerations**: +- Tools and systems for performance monitoring +- Regular audits and optimizations +- Costs associated with debugging and troubleshooting -#### **Objective:** -To create an ecosystem where third-party developers can contribute, and users can enhance their Swarms experience. +**Impact**: +- Ongoing expense that increases with scale +- Essential for maintaining efficiency and cost-effectiveness +- Can lead to significant savings through optimized usage -#### **Strategy:** +### 5. Compliance and Security -* **Open API for Development:** - * Offer robust documentation and developer support. - * Ensure a strict quality check for marketplace additions. +**Considerations**: +- Legal counsel for data privacy and AI regulations +- Implementation of security measures (e.g., encryption, access controls) +- Regular audits and certifications -* **Monetization:** - * Revenue Sharing: Take a percentage cut from third-party sales. - * Featured Listings: Charge developers for premium listings. +**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 -* **Promotion:** - * Host hackathons and competitions to boost developer engagement. - * Promote top plugins/extensions through email marketing and on the main platform. +### 6. Training and Change Management ---- +- Employee training programs +- Development of user guides and documentation +- Change management initiatives -### **Future Outlook & Expansion:** +**Impact**: +- Often underestimated but crucial for adoption +- Can affect productivity during the transition period +- Important for realizing the full potential of LLM integration -* **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, +### 7. Scaling Costs +**Considerations**: +- Potential price increases as usage grows +- Need for additional infrastructure or resources +- Costs associated with managing increased complexity -* **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. +**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 ---- +### 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 +**Impact**: +- Difficult to quantify but important to consider +- Can affect overall business strategy and priorities +- May influence timing and scope of LLM integration -### **50 Creative Distribution Platforms for Swarms** +### 9. Vendor Lock-in -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. +**Considerations**: +- Costs associated with switching providers +- Dependency on provider-specific features or integrations +- Potential for price increases once deeply integrated -3. **Podcasting Platforms:** Swarms-themed content on platforms like Spotify, Apple Podcasts to reach aural learners. +**Impact**: +- Can limit flexibility and negotiating power +- May affect long-term costs and strategic decisions +- Important to consider multi-provider or portable implementation strategies -4. **Virtual Reality (VR) Platforms:** Integration with VR experiences on Oculus or Viveport. +### 10. Ethical and Reputational Considerations -5. **Gaming Platforms:** Tools or plugins for game developers on Steam, Epic Games. +**Considerations**: +- Potential backlash from AI-related controversies +- Costs of ensuring ethical AI use and transparency +- Investments in responsible AI practices -6. **Decentralized Platforms:** Using blockchain, create decentralized apps (DApps) versions of Swarms. +**Impact**: +- Can affect brand reputation and customer trust +- May require ongoing public relations efforts +- Important for long-term sustainability and social responsibility -7. **Chat Applications:** Integrate with popular messaging platforms like WhatsApp, Telegram, Slack. +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. -8. **AI Assistants:** Integration with Siri, Alexa, Google Assistant to provide Swarms functionalities via voice commands. +## Conclusion: Navigating the LLM Pricing Landscape -9. **Freelancing Websites:** Offer tools or services for freelancers on platforms like Upwork, Fiverr. +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. -10. **Online Forums:** Platforms like Reddit, Quora, where users can discuss or access Swarms. +Key takeaways include: -11. **Educational Platforms:** Sites like Khan Academy, Udacity where Swarms can enhance learning experiences. +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. -12. **Digital Art Platforms:** Integrate with platforms like DeviantArt, Behance. +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. -13. **Open-source Repositories:** Hosting Swarms on GitHub, GitLab, Bitbucket with open-source plugins. +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: -14. **Augmented Reality (AR) Apps:** Create AR experiences powered by Swarms. +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). -15. **Smart Home Devices:** Integrate Swarms' functionalities into smart home devices. +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). -16. **Newsletters:** Platforms like Substack, where Swarms insights can be shared. +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. -17. **Interactive Kiosks:** In malls, airports, and other public places. +-------------------------------------------------- -18. **IoT Devices:** Incorporate Swarms in devices like smart fridges, smartwatches. +# File: index.md -19. **Collaboration Tools:** Platforms like Trello, Notion, offering Swarms-enhanced productivity. +# Welcome to Swarms Docs Home -20. **Dating Apps:** An AI-enhanced matching algorithm powered by Swarms. +[![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) -21. **Music Platforms:** Integrate with Spotify, SoundCloud for music-related AI functionalities. +## What is Swarms? -22. **Recipe Websites:** Platforms like AllRecipes, Tasty with AI-recommended recipes. +**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. -23. **Travel & Hospitality:** Integrate with platforms like Airbnb, Tripadvisor for AI-based recommendations. +### Key Capabilities -24. **Language Learning Apps:** Duolingo, Rosetta Stone integrations. +- **🏢 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 -25. **Virtual Events Platforms:** Websites like Hopin, Zoom where Swarms can enhance the virtual event experience. +### Why Choose Swarms? -26. **Social Media Management:** Tools like Buffer, Hootsuite with AI insights by Swarms. +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. -27. **Fitness Apps:** Platforms like MyFitnessPal, Strava with AI fitness insights. +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. -28. **Mental Health Apps:** Integration into apps like Calm, Headspace for AI-driven wellness. +## Swarms Installation -29. **E-books Platforms:** Amazon Kindle, Audible with AI-enhanced reading experiences. +```bash +pip3 install swarms +``` -30. **Sports Analysis Tools:** Websites like ESPN, Sky Sports where Swarms can provide insights. +## Update Swarms -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. +```bash +pip3 install -U swarms +``` -33. **3D Printing Platforms:** Websites like Thingiverse, Shapeways with AI customization. +### **Get Started Building Production-Grade Multi-Agent Applications** -34. **Meme Platforms:** Websites like Memedroid, 9GAG where Swarms can suggest memes. +## Onboarding -35. **Astronomy Apps:** Platforms like Star Walk, NASA's Eyes with AI-driven space insights. +| 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/) | -36. **Weather Apps:** Integration into Weather.com, AccuWeather for predictive analysis. -37. **Sustainability Platforms:** Websites like Ecosia, GoodGuide with AI-driven eco-tips. +## Ecosystem -38. **Fashion Apps:** Platforms like ASOS, Zara with AI-based style recommendations. +Here you'll find references about the Swarms framework, marketplace, community, and more to enable you to build your multi-agent applications. -39. **Pet Care Apps:** Integration into PetSmart, Chewy for AI-driven pet care tips. +| 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) | -40. **Real Estate Platforms:** Websites like Zillow, Realtor with AI-enhanced property insights. -41. **DIY Platforms:** Websites like Instructables, DIY.org with AI project suggestions. +## Join the Swarms Community -42. **Genealogy Platforms:** Ancestry, MyHeritage with AI-driven family tree insights. +| 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 | -43. **Car Rental & Sale Platforms:** Integration into AutoTrader, Turo for AI-driven vehicle suggestions. +## Get Support -44. **Wedding Planning Websites:** Platforms like Zola, The Knot with AI-driven planning. +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! -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. -47. **Study & Revision Platforms:** Websites like Chegg, Quizlet with AI-driven study guides. +-------------------------------------------------- -48. **Local Business Directories:** Yelp, Yellow Pages with AI-enhanced reviews. +# File: protocol\overview.md -49. **Networking Platforms:** LinkedIn, Meetup with AI-driven connection suggestions. +# Swarms Protocol Overview & Architecture -50. **Lifestyle Magazines' Digital Platforms:** Websites like Vogue, GQ with AI-curated fashion and lifestyle insights. +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. --- -*Endnote: Leveraging these diverse platforms ensures that Swarms becomes an integral part of multiple ecosystems, enhancing its visibility and user engagement.* +## Introduction --------------------------------------------------- +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. -# File: corporate\failures.md +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. -# Failure Root Cause Analysis for Langchain +For a high-level introduction and installation instructions, see the [Swarms Docs Home](https://docs.swarms.world/en/latest/). -## 1. Introduction +--- -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. +## High-Level Architecture Flow -## 2. Analysis of Weaknesses +The Swarms protocol is organized into several key layers, each responsible for a specific aspect of the system. The typical flow is as follows: -### 2.1 Tool Lock-in +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/) -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. +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.). -#### Mitigation + - 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/) -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. +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. -### 2.2 Outdated Workflows + - Includes agents for self-reflection, iterative improvement, and domain-specific expertise. -Langchain's current workflows and prompt engineering, mainly based on InstructGPT, are out of date, especially compared to newer models like ChatGPT/GPT-4. + - Example: A `SelfConsistencyAgent` that aggregates multiple reasoning paths, or a `JudgeAgent` that evaluates outputs from other + agents. -#### Mitigation + - [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/) -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. +4. **Multi-Agent Structures (`swarms/structs`)** + - Agents are composed into higher-order structures for collaboration, voting, parallelism, and workflow orchestration. -### 2.3 Debugging Difficulties + - Includes swarms for majority voting, round-robin execution, hierarchical delegation, and more. -Debugging in Langchain is reportedly very challenging, even with verbose output enabled, making it hard to determine what is happening under the hood. + - Example: A `MajorityVotingSwarm` that aggregates outputs from several agents, or a `HierarchicalSwarm` that delegates tasks to + sub-agents. -#### Mitigation + - [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/) -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. +5. **Supporting Components** -### 2.4 Limited Customization + - **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/) -Langchain makes it extremely hard to deviate from documented workflows. This becomes a challenge when developers need custom workflows for their specific use-cases. +--- -#### Mitigation +## Proposing Large Improvements or Enhancements: Swarms Improvement Proposals (SIPs) -An ideal framework should support custom workflows and allow developers to hack and adjust the framework according to their needs. +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. -### 2.5 Documentation +**When to use a SIP:** -Langchain's documentation is reportedly missing relevant details, making it difficult for users to understand the differences between various agent types, among other things. +- Proposing new agent types, swarm patterns, or coordination mechanisms -#### Mitigation +- Core framework changes or breaking changes -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. +- New integrations (LLM providers, tools, external services) -### 2.6 Negative Influence on AI Ecosystem +- Any complex or multi-component feature -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. +**SIP Process Overview:** -#### Mitigation +1. Discuss your idea in [GitHub Discussions](https://github.com/kyegomez/swarms/discussions) -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. +2. Submit a SIP as a GitHub Issue using the SIP template -## 3. Conclusion +3. Engage with the community and iterate on your proposal -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. +4. Undergo review and, if accepted, proceed to implementation +**Learn more:** See the full [SIP Guidelines and Template](https://docs.swarms.world/en/latest/protocol/sip/) -# List of weaknesses in gLangchain and Potential Mitigations +--- -1. **Tool Lock-in**: Langchain encourages the use of specific tools, creating a lock-in problem with minimal benefits for developers. +## Detailed Architecture Diagram - *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. +The following Mermaid diagram visualizes the protocol flow and the relationship between the main folders in the `swarms/` package: -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. +```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 +``` - *Mitigation Strategy*: Regular updates and adaptation of more recent models should be integrated into the Langchain framework. +--- -3. **Debugging Difficulty**: Debugging a Langchain error is a complicated task, even with verbose=True, leading to a discouraging developer experience. +## Folder-by-Folder Breakdown - *Mitigation Strategy*: Develop a comprehensive debugging tool or improve current debugging processes for clearer and more accessible error detection and resolution. +### `agents/` -4. **Lack of Customizability**: Customizing workflows that are not documented in Langchain is quite challenging. +**Purpose:** Defines all agent classes, including base agents, reasoning agents, tool agents, judge agents, and more. - *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. +- Modular agent design for extensibility. - *Mitigation Strategy*: Enhance and improve the documentation of Langchain to provide clarity for developers and make navigation easier. +- Support for YAML-based agent creation and configuration. See [YAML Agent Creation](https://docs.swarms.world/en/latest/swarms/ +agents/create_agents_yaml/) -6. **Harmful Ecosystem Influence**: Langchain's extreme popularity is influencing the AI ecosystem towards the workflows, potentially harming development and code clarity. +- Specialized agents for self-consistency, evaluation, and domain-specific tasks. - *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. +- `ReasoningAgent`, `ToolAgent`, `JudgeAgent`, `ConsistencyAgent`, `OpenAIAssistant`, etc. - *Mitigation Strategy*: Enhance the performance optimization of Langchain. Benchmarking against other tools can also provide performance improvement insights. +- [Agents Overview](https://docs.swarms.world/en/latest/swarms/framework/agents_explained/) -8. **Rigid General Interface**: Langchain tries to do too many things, resulting in a rigid interface not suitable for practical use, especially in production. - *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. +### `tools/` -9. **Leaky Abstraction Problem**: Langchain’s full-on framework approach has created a leaky abstraction problem leading to a disappointing developer experience. +**Purpose:** Houses all tool-related logic, including tool registry, function calling, tool schemas, and integration with external +APIs. - *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. +**Highlights:** -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. +- Tools can be dynamically registered and called by agents. - *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. +- Support for OpenAI function calling, Cohere, and custom tool schemas. --------------------------------------------------- +- Utilities for parsing, formatting, and executing tool calls. -# File: corporate\faq.md +- **Example:** -### FAQ on Swarm Intelligence and Multi-Agent Systems +- `base_tool.py`, `tool_registry.py`, `mcp_client_call.py`, `func_calling_utils.py`, etc. -#### What is an agent in the context of AI and swarm intelligence? +- [Tools Reference](https://docs.swarms.world/en/latest/swarms/tools/tools_examples/) -In artificial intelligence (AI), an agent refers to an LLM with some objective to accomplish. +- [What are tools?](https://docs.swarms.world/en/latest/swarms/tools/build_tool/) -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. +### `structs/` +**Purpose:** Implements multi-agent structures, workflows, routers, registries, and orchestration logic. -#### 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. +**Highlights:** +- Swarms for majority voting, round-robin, hierarchical delegation, spreadsheet processing, and more. -#### How does a swarm work? +- Workflow orchestration (sequential, concurrent, graph-based). -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. +- Utilities for agent matching, rearrangement, and evaluation. -#### Why do you need more agents in a swarm? +- **Example:** -More agents in a swarm can enhance its problem-solving capabilities, resilience, and efficiency. With more agents: +- `MajorityVotingSwarm`, `HierarchicalSwarm`, `SwarmRouter`, `SequentialWorkflow`, `ConcurrentWorkflow`, etc. -- **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. +- [Custom Multi Agent Architectures](https://docs.swarms.world/en/latest/swarms/structs/custom_swarm/) -#### Isn't it more expensive to use more agents? +- [SwarmRouter](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/) -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: +- [AgentRearrange](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/) -- **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. -#### Can swarms make decisions better than individual agents? +### `utils/` -Yes, swarms can make better decisions than individual agents for several reasons: +**Purpose:** Provides utility functions, memory management, caching, wrappers, and helpers used throughout the framework. -- **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. +**Highlights:** -#### How do agents in a swarm communicate? +- Memory and caching for agents and tools. See [Integrating RAG with Agents](https://docs.swarms.world/en/latest/swarms/memory/ +diy_memory/) -Communication in a swarm can vary based on the design and purpose of the system but generally involves either direct or indirect interactions: +- Wrappers for concurrency, logging, and data processing. -- **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. +- General-purpose utilities for string, file, and data manipulation. -#### Are swarms only useful in computational tasks? +**Example:** -While swarms are often associated with computational tasks, their applications extend far beyond. Swarms can be utilized in: +- `agent_cache.py`, `concurrent_wrapper.py`, `file_processing.py`, `formatter.py`, etc. -- **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. -#### How do you ensure the security of a swarm system? +### `telemetry/` -Security in swarm systems involves: +**Purpose:** Handles telemetry, logging, monitoring, and bootup routines for the framework. -- **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. +**Highlights:** -#### How do individual agents within a swarm share insights without direct learning mechanisms like reinforcement learning? +- Centralized logging and execution tracking. -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: +- Bootup routines for initializing the framework. -- **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. +- Utilities for monitoring agent and swarm performance. -#### How do you balance the autonomy of individual LLMs with the need for coherent collective behavior in a swarm? +- **Example:** -Balancing autonomy with collective coherence in a swarm of LLMs involves: +- `bootup.py`, `log_executions.py`, `main.py`. -- **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. -- **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. +### `schemas/` -#### How do LLM swarms adapt to changing environments or tasks without machine learning techniques? +**Purpose:** Defines data schemas for agents, tools, completions, and communication protocols. -Adaptation in LLM swarms, without relying on machine learning techniques for dynamic learning, can be achieved through: +**Highlights:** -- **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. +- Ensures type safety and consistency across the framework. -- **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. +- Pydantic-based schemas for validation and serialization. -- **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: +- Schemas for agent classes, tool calls, completions, and more. +**Example:** -#### Can LLM swarms operate in physical environments, or are they limited to digital spaces? +- `agent_class_schema.py`, `tool_schema_base_model.py`, `agent_completion_response.py`, etc. -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. -#### Without direct learning from each other, how do agents in a swarm improve over time? +### `prompts/` -Improvement over time in a swarm of pre-trained LLMs, without direct learning from each other, can be achieved through: +**Purpose:** Contains prompt templates, system prompts, and agent-specific prompts for LLM-based agents. -- **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. +**Highlights:** -- **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. +- Modular prompt design for easy customization. -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. +- Support for multi-modal, collaborative, and domain-specific prompts. +- Templates for system, task, and conversational prompts. -#### Conclusion +**Example:** -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. +- `prompt.py`, `reasoning_prompt.py`, `multi_agent_collab_prompt.py`, etc. --------------------------------------------------- +- [Prompts Management](https://docs.swarms.world/en/latest/swarms/prompts/main/) -# File: corporate\flywheel.md -# The Swarms Flywheel +### `artifacts/` -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. +**Purpose:** Manages the creation, storage, and retrieval of artifacts (outputs, files, logs) generated by agents and swarms. -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. +**Highlights:** -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. +- Artifact management for reproducibility and traceability. +- Support for various output types and formats. -4. **Rise in User Base:** As Swarms becomes more robust and more well-known, the user base grows, driving more revenue. +**Example:** -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. +- `main_artifact.py`. -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. -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. +### `communication/` -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. +**Purpose:** Provides wrappers for inter-agent communication, database access, message passing, and integration with external systems. +**Highlights:** -```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. +- Support for Redis, DuckDB, Pulsar, Supabase, and more. +- Abstractions for message passing and data exchange between agents. --------------------------------------------------- +**Example:** -# File: corporate\front_end_contributors.md +- `redis_wrap.py`, `duckdb_wrap.py`, `base_communication.py`, etc. -# Frontend Contributor Guide +- [Communication Structure](https://docs.swarms.world/en/latest/swarms/structs/conversation/) -## 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/` -## 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. +**Purpose:** Command-line utilities for agent creation, management, and orchestration. -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. +**Highlights:** +- Scripts for onboarding, agent creation, and management. -## 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. +- CLI entry points for interacting with the framework. +**Example:** -### 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! +- `main.py`, `create_agent.py`, `onboarding_process.py`. -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. +- [CLI Documentation](https://docs.swarms.world/en/latest/swarms/cli/main/) -## 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) +## How the System Works Together -- **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 Community](https://discord.gg/pSTSxqDk)** - - -### Design Style & User Experience -- [How to build great products with game design, not gamification](https://blog.superhuman.com/game-design-not-gamification/) - --------------------------------------------------- - -# File: corporate\hiring.md - -# Careers at Swarms +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. -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. +For example, a typical workflow might involve: -**We offer none of the following benefits Yet:** +- Creating a set of specialized agents (e.g., data analyst, summarizer, judge). -- No medical, dental, or vision insurance +- Registering tools (e.g., LLM API, database access, web search) and memory modules. -- No paid time off +- Composing agents into a `MajorityVotingSwarm` for collaborative decision-making. -- No life or AD&D insurance +- Using communication wrappers to exchange data between agents and external systems. -- No short-term or long-term disability insurance +- Logging all actions and outputs for traceability and debugging. -- No 401(k) plan -**Working hours:** 9 AM to 10 PM, every day, 7 days a week. This is not for people who seek work-life balance. +For more advanced examples, see the [Examples Overview](https://docs.swarms.world/en/latest/examples/index/). --- -### Hiring Process: How to Join Swarms -We have a simple 3-step hiring process: +## Swarms Framework Philosophy -**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. +Swarms is built on the following principles: -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! +- **Modularity:** Every component (agent, tool, prompt, schema) is a module that can be extended or replaced. -There are no recruiters. All evaluations are done by our technical team. +- **Composability:** Agents and tools can be composed into larger structures for complex workflows. ---- +- **Observability:** Telemetry and artifact management ensure that all actions are traceable and debuggable. -# Location +- **Extensibility:** New agents, tools, and workflows can be added with minimal friction. -- **Palo Alto** CA Our Palo Alto office houses the majority of our core research teams including our prompting, agent design, and model training +- **Production-Readiness:** The framework is designed for reliability, scalability, and real-world deployment. -- **Miami** Our miami office holds prompt engineering, agent design, and more. +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/). -### Open Roles at Swarms +--- -**Infrastructure Engineer** +## Further Reading & References -- Build and maintain the systems that run our AI multi-agent infrastructure. +- [Swarms Docs Home](https://docs.swarms.world/en/latest/) -- Expertise in Skypilot, AWS, Terraform. +- [Quickstart for Agents](https://docs.swarms.world/en/latest/swarms/agents/) -- Ensure seamless, high-availability environments for agent operations. +- [Agent API Reference](https://docs.swarms.world/en/latest/swarms/structs/agent/) -**Agent Engineer** +- [Tools Overview](https://docs.swarms.world/en/latest/swarms_tools/overview/) -- Design, develop, and orchestrate complex swarms of AI agents. +- [BaseTool Reference](https://docs.swarms.world/en/latest/swarms/tools/base_tool/) -- Extensive experience with Python, multi-agent systems, and neural networks. +- [Reasoning Agents Overview](https://docs.swarms.world/en/latest/swarms/agents/reasoning_agents_overview/) -- Ability to create dynamic and efficient agent architectures from scratch. +- [Multi-Agent Architectures Overview](https://docs.swarms.world/en/latest/swarms/concept/swarm_architectures/) -**Prompt Engineer** +- [Examples Overview](https://docs.swarms.world/en/latest/examples/index/) -- Craft highly optimized prompts that drive our LLM-based agents. +- [CLI Documentation](https://docs.swarms.world/en/latest/swarms/cli/main/) -- Specialize in instruction-based prompts, multi-shot examples, and production-grade deployment. +- [Prompts Management](https://docs.swarms.world/en/latest/swarms/prompts/main/) -- Collaborate with agents to deliver state-of-the-art solutions. +- [Development Philosophy & Principles](https://docs.swarms.world/en/latest/swarms/concept/philosophy/) -**Front-End Engineer** +- [Understanding Swarms Architecture](https://docs.swarms.world/en/latest/swarms/concept/framework_architecture/) -- Build sleek, intuitive interfaces for interacting with swarms of agents. +- [SIP Guidelines and Template](https://docs.swarms.world/en/latest/protocol/sip/) -- Proficiency in Next.js, FastAPI, and modern front-end technologies. -- Design with the user experience in mind, integrating complex AI features into simple workflows. +# Conclusion +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. --------------------------------------------------- -# File: corporate\metric.md -# The Golden Metric: 95% User-Task-Completion-Satisfaction Rate +-------------------------------------------------- -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. +# File: protocol\sip.md -## 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. +# Swarms Improvement Proposal (SIP) Guidelines -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. +A simplified process for proposing new functionality and enhancements to the Swarms framework. -## 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. +## What is a SIP? -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. +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. -## 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. +The SIP author is responsible for building consensus within the community and documenting the proposal clearly and concisely. -### Here are some strategies we’re implementing to reach our goal: +## When to Submit a SIP -* 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 +Consider submitting a SIP for: -* 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. +- **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 -* 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. +For simple bug fixes, minor enhancements, or straightforward additions, use regular GitHub issues and pull requests instead. -*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. +## SIP Types -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. +**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 +## Submitting a SIP +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 -# Your Feedback Matters: Help Us Optimize the UTCS Rate +## SIP Format -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. +### Required Sections -## 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. +#### **SIP Header** +``` +Title: [Descriptive title] +Author: [Your name and contact] +Type: [Standard/Process/Informational] +Status: Proposal +Created: [Date] +``` -Here's what we want to understand from you: +#### **Abstract** (200 words max) +A brief summary of what you're proposing and why. -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? +#### **Motivation** +- What problem does this solve? +- Why can't the current framework handle this? +- What are the benefits to the Swarms ecosystem? -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. +#### **Specification** +- Detailed technical description +- API changes or new interfaces +- Code examples showing usage +- Integration points with existing framework -## 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. +#### **Implementation Plan** +- High-level implementation approach +- Breaking changes (if any) +- Migration path for existing users +- Testing strategy -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. +#### **Alternatives Considered** +- Other approaches you evaluated +- Why you chose this solution +- Trade-offs and limitations -So, let's start this conversation - how can we make Swarms work best for you? +### Optional Sections +#### **Reference Implementation** +Link to prototype code or proof-of-concept (can be added later) -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. +#### **Security Considerations** +Any security implications or requirements -Here's what we're keen to understand: +## SIP Workflow -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. +``` +Proposal → Draft → Review → Accepted/Rejected → Final +``` -Let's start the conversation - how can we make Swarms work best for you? +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 +## SIP Status --------- +- **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 -**The Golden Metric Analysis: The Ultimate UTCS Paradigm for Swarms** +## Review Process -### Introduction +- 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) -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. +## Getting Help -### Decoding UTCS: An Analytical Overview +- **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 -The UTCS rate is not merely about task completion; it's about the comprehensive experience. Therefore, its foundations lie in: +## SIP Template -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. +When creating your SIP, copy this template: -We can represent the UTCS rate with the following equation: +```markdown +# SIP-XXX: [Title] -```latex -\[ UTCS Rate = \frac{(Completed Tasks \times User Satisfaction)}{(Total Tasks)} \times 100 \] -``` +**Author**: [Your name] <[email]> +**Type**: Standard +**Status**: Proposal +**Created**: [Date] -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. +## Abstract -### The Golden Metric: Swarm Efficiency Index (SEI) +[Brief 200-word summary] -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. +## Motivation -Here’s the formula: +[Why is this needed? What problem does it solve?] -```latex -\[ SEI = \frac{UTCS Rate}{(Memory Consumption + Time Window + Task Complexity)} \] -``` +## Specification -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). +[Detailed technical description with code examples] -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. +## Implementation Plan -### Implementing SEI & Improving UTCS +[How will this be built? Any breaking changes?] -Using feedback from elder-plinius, we can better understand and improve SEI and UTCS: +## Alternatives Considered -1. **Feedback Across Skill Levels**: By gathering feedback from users with different skill levels, we can refine our metrics, ensuring Swarms caters to all. +[Other approaches and why you chose this one] -2. **Simplifying Setup**: Detailed guides can help newcomers swiftly get on board, thus enhancing user satisfaction. +## Reference Implementation -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. +[Link to prototype code if available] +``` -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 +**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. -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. +-------------------------------------------------- +# File: quickstart.md ----------------- -**Research Analysis: Tracking and Ensuring Reliability of Swarm Metrics at Scale** -### 1. Introduction +# Welcome to Swarms Docs Home -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. +[![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) -### 2. Why Tracking at Scale is Challenging +## What is Swarms? -The primary challenges include: +**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. -- **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. +### Key Capabilities -### 3. Strategies for Scalable Tracking +- **🏢 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 -#### 3.1. Distributed Monitoring Systems +### Why Choose Swarms? -**Recommendation**: Implement distributed systems like Prometheus or InfluxDB. +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. -**Rationale**: -- Ability to collect metrics from various Swarm instances concurrently. -- Scalable and can handle vast data influxes. - -#### 3.2. Real-time Data Processing +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. -**Recommendation**: Use stream processing systems like Apache Kafka or Apache Flink. +Get started learning swarms with the following examples and more. -**Rationale**: -- Enables real-time metric calculation. -- Can handle high throughput and low-latency requirements. +## Install 💻 -#### 3.3. Data Sampling +```bash +$ pip3 install -U swarms +``` -**Recommendation**: Random or stratified sampling of user sessions. +### Using uv (Recommended) +[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver, written in Rust. -**Rationale**: -- Reduces the data volume to be processed. -- Maintains representativeness of overall user experience. +```bash +# Install uv +$ curl -LsSf https://astral.sh/uv/install.sh | sh -### 4. Ensuring Reliability in Data Collection +# Install swarms using uv +$ uv pip install swarms +``` -#### 4.1. Redundancy +### Using poetry +```bash +# Install poetry if you haven't already +$ curl -sSL https://install.python-poetry.org | python3 - -**Recommendation**: Integrate redundancy into data collection nodes. +# Add swarms to your project +$ poetry add swarms +``` -**Rationale**: -- Ensures no single point of failure. -- Data loss prevention in case of system malfunctions. +### From source +```bash +# Clone the repository +$ git clone https://github.com/kyegomez/swarms.git +$ cd swarms -#### 4.2. Anomaly Detection +# Install with pip +$ pip install -e . +``` -**Recommendation**: Implement AI-driven anomaly detection systems. +--- -**Rationale**: -- Identifies outliers or aberrations in metric calculations. -- Ensures consistent and reliable data interpretation. +## Environment Configuration -#### 4.3. Data Validation +[Learn more about the environment configuration here](https://docs.swarms.world/en/latest/swarms/install/env/) -**Recommendation**: Establish automated validation checks. +``` +OPENAI_API_KEY="" +WORKSPACE_DIR="agent_workspace" +ANTHROPIC_API_KEY="" +GROQ_API_KEY="" +``` -**Rationale**: -- Ensures only accurate and relevant data is considered. -- Eliminates inconsistencies arising from corrupted or irrelevant data. -### 5. Feedback Loops and Continuous Refinement -#### 5.1. User Feedback Integration +### 🤖 Your First Agent -**Recommendation**: Develop an in-built user feedback mechanism. +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/) -**Rationale**: -- Helps validate the perceived vs. actual performance. -- Allows for continuous refining of tracking metrics and methodologies. +```python +from swarms import Agent -#### 5.2. A/B Testing +# 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 +) -**Recommendation**: Regularly conduct A/B tests for new tracking methods or adjustments. +# Run the agent with a task +agent.run("What are the key benefits of using a multi-agent system?") +``` -**Rationale**: -- Determines the most effective methods for data collection. -- Validates new tracking techniques against established ones. +### 🤝 Your First Swarm: Multi-Agent Collaboration -### 6. Conclusion +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/) -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. +```python +from swarms import Agent, SequentialWorkflow --------------------------------------------------- +# 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", +) -# File: corporate\purpose.md +# 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", +) +# Create a sequential workflow where the researcher's output feeds into the writer's input +workflow = SequentialWorkflow(agents=[researcher, writer]) -## 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. +# Run the workflow on a task +final_post = workflow.run("The history and future of artificial intelligence") +print(final_post) -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. +``` +----- -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. +## 🏗️ Multi-Agent Architectures For Production Deployments -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. +`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. -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. +| **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. | ---- +----- --------------------------------------------------- +### SequentialWorkflow -# File: corporate\research.md +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. -# Research Lists -A compilation of projects, papers, blogs in autonomous agents. +```python +from swarms import Agent, SequentialWorkflow -## Table of Contents +# 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") -- [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 +# Create the sequential workflow +workflow = SequentialWorkflow(agents=[idea_generator, validator, pitch_creator]) +# Run the workflow +elevator_pitch = workflow.run() +print(elevator_pitch) +``` --------------------------------------------------- +----- -# File: corporate\roadmap.md -## The Plan +### ConcurrentWorkflow (with `SpreadSheetSwarm`) -### 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. +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. -### 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. +```python +from swarms import Agent, SpreadSheetSwarm -### 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. +# Define a list of tasks (e.g., social media posts to generate) +platforms = ["Twitter", "LinkedIn", "Instagram"] -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. +# 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 +] +# Initialize the swarm to run these agents concurrently +swarm = SpreadSheetSwarm( + agents=agents, + autosave_on=True, + save_file_path="marketing_posts.csv", +) +# 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! +``` --------------------------------------------------- +--- -# File: corporate\swarm_cloud.md +### AgentRearrange -# The Swarm Cloud +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. -### Business Model Plan for Autonomous Agent Swarm Service +```python +from swarms import Agent, AgentRearrange -#### 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. +# 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") -#### 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. +# Define a flow: researcher sends work to both writer and editor simultaneously +# This is a one-to-many relationship +flow = "researcher -> writer, editor" -#### 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. +# Create the rearrangement system +rearrange_system = AgentRearrange( + agents=[researcher, writer, editor], + flow=flow, +) -# 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. | +# 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) ``` -1. **Pay-Per-Mission Pricing:** Clients are charged for each specific task or mission completed by the agents. -- **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. + -9. **Peak Time Premiums:** Higher charges during peak usage times or for emergency deployment. +---- -10. **Bundled Services:** Combining agent services with other products or services for a comprehensive package deal. +### SwarmRouter: The Universal Swarm Orchestrator -11. **Custom Solution Pricing:** Tailor-made pricing for unique or specialized requirements. +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/) -12. **Data Analysis Fee:** Charging for the data processing and analytics provided by the agents. +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. -13. **Performance Tiers:** Different pricing for varying levels of agent efficiency or performance. +```python +from swarms import Agent +from swarms.structs.swarm_router import SwarmRouter, SwarmType -14. **License Model:** Clients purchase a license to deploy and use a certain number of agents. +# 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") -15. **Cost-Plus Pricing:** Pricing based on the cost of deployment plus a markup. +# 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." -16. **Service Level Agreement (SLA) Pricing:** Higher prices for higher levels of service guarantees. +# --- 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") -17. **Pay-Per-Save Model:** Charging based on the cost savings or value created by the agents for the client. +# --- 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") -18. **Revenue Sharing:** Sharing a percentage of the revenue generated through the use of agents. +# --- 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") +``` -19. **Geographic Pricing:** Different pricing for different regions or markets. -20. **User-Based Pricing:** Charging based on the number of users accessing and controlling the agents. +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. -21. **Energy Usage Pricing:** Prices based on the amount of energy consumed by the agents during operation. +------- -22. **Event-Driven Pricing:** Charging for specific events or triggers during the agent's operation. +### MixtureOfAgents (MoA) -23. **Seasonal Pricing:** Adjusting prices based on seasonal demand or usage patterns. +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/) -24. **Partnership Models:** Collaborating with other businesses and sharing revenue from combined services. +```python +from swarms import Agent, MixtureOfAgents -25. **Customizable Packages:** Allowing clients to build their own package of services and capabilities, priced accordingly. +# 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") -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. +# 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, +) -# ICP Analysis -### Ideal Customer Profile (ICP) Map +# Run the swarm +recommendation = moa_swarm.run("Should we invest in NVIDIA stock right now?") +print(recommendation) +``` -#### 1. Manufacturing and Industrial Automation - - **Characteristics:** Large-scale manufacturers, high automation needs, emphasis on efficiency and precision. - - **Needs:** Process automation, quality control, predictive maintenance. +---- -#### 2. Agriculture and Farming - - **Characteristics:** Large agricultural enterprises, focus on modern farming techniques. - - **Needs:** Crop monitoring, automated harvesting, pest control. +### GroupChat -#### 3. Logistics and Supply Chain - - **Characteristics:** Companies with extensive logistics operations, warehousing, and supply chain management. - - **Needs:** Inventory tracking, automated warehousing, delivery optimization. +`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. -#### 4. Energy and Utilities - - **Characteristics:** Energy providers, utility companies, renewable energy farms. - - **Needs:** Infrastructure monitoring, predictive maintenance, efficiency optimization. +```python +from swarms import Agent, GroupChat -#### 5. Environmental Monitoring and Conservation - - **Characteristics:** Organizations focused on environmental protection, research institutions. - - **Needs:** Wildlife tracking, pollution monitoring, ecological research. +# 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") -#### 6. Smart Cities and Urban Planning - - **Characteristics:** Municipal governments, urban development agencies. - - **Needs:** Traffic management, infrastructure monitoring, public safety. +# Create the group chat +chat = GroupChat( + agents=[tech_optimist, tech_critic], + max_loops=4, # Limit the number of turns in the conversation +) -#### 7. Defense and Security - - **Characteristics:** Defense contractors, security firms, government agencies. - - **Needs:** Surveillance, reconnaissance, threat assessment. +# Run the chat with an initial topic +conversation_history = chat.run( + "Let's discuss the societal impact of artificial intelligence." +) -#### 8. Healthcare and Medical Facilities - - **Characteristics:** Large hospitals, medical research centers. - - **Needs:** Facility management, patient monitoring, medical logistics. +# Print the full conversation +for message in conversation_history: + print(f"[{message['agent_name']}]: {message['content']}") +``` -#### 9. Entertainment and Event Management - - **Characteristics:** Large-scale event organizers, theme parks. - - **Needs:** Crowd management, entertainment automation, safety monitoring. -#### 10. Construction and Infrastructure - - **Characteristics:** Major construction firms, infrastructure developers. - - **Needs:** Site monitoring, material tracking, safety compliance. -### Potential Market Size Table (in Markdown) -```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. | -``` - -#### Risk Analysis -- **Market Risks:** Adaptation rate and competition. -- **Operational Risks:** Reliability and scalability of infrastructure. -- **Regulatory Risks:** Compliance with data security and privacy laws. - -# Business Model ---- +-------------------------------------------------- -### The Swarm Cloud: Business Model +# File: swarms\agents\abstractagent.md -#### Unlocking the Potential of Autonomous Agent Technology +# swarms.agents -**1. Our Vision:** - - Revolutionize industries through scalable, intelligent swarms of autonomous agents. - - Enable real-time data collection, analysis, and automated task execution. +## 1. Introduction -**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. +`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. -**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. +`AbstractAgent` provides capabilities for managing tools and accessing memory, and has methods for running, chatting, and stepping through communication with other agents. -**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. +## 2. Class Definition -**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. +```python +class AbstractAgent: + """An abstract class for AI agent. -**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. + An agent can communicate with other agents and perform actions. + Different agents can differ in what actions they perform in the `receive` method. -**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. + Agents are full and completed: -"Empowering industries with intelligent, autonomous solutions – The Swarm Cloud is set to redefine efficiency and innovation." + Agents = llm + tools + memory + """ -#### 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. + def __init__(self, name: str): + """ + Args: + name (str): name of the agent. + """ + self._name = name + @property + def name(self): + """Get the name of the agent.""" + return self._name + def tools(self, tools): + """init tools""" --------------------------------------------------- + def memory(self, memory_store): + """init memory""" -# File: corporate\swarm_memo.md + def reset(self): + """(Abstract method) Reset the agent.""" -# [Go To Market Strategy][GTM] + def run(self, task: str): + """Run the agent once""" -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. + def _arun(self, taks: str): + """Run Async run""" -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. + def chat(self, messages: List[Dict]): + """Chat with the agent""" -Our target user segment for the framework is AI engineers looking to deploy agents into high risk environments where reliability is crucial. + def _achat(self, messages: List[Dict]): + """Asynchronous Chat""" -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. + def step(self, message: str): + """Step through the agent""" -Our growth strategy for the OS framework can be summarized by: + def _astep(self, message: str): + """Asynchronous 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) +## 3. Functionality and Usage -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. +The `AbstractAgent` class represents a generic AI agent and provides a set of methods to interact with it. -Acquire Full Access to the memo here: [TSC Memo](https://docs.google.com/document/d/1hS_nv_lFjCqLfnJBoF6ULY9roTbSgSuCkvXvSUSc7Lo/edit?usp=sharing) +To create an instance of an agent, the `name` of the agent should be specified. --------------------------------------------------- +### Core Methods -# File: corporate\swarms_bounty_system.md +#### 1. `reset` -# **The Swarms Bounty System: Get Paid to Contribute to Open Source** +The `reset` method allows the agent to be reset to its initial state. -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. +```python +agent.reset() +``` -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. +#### 2. `run` -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. +The `run` method allows the agent to perform a specific task. -[**All bounties with rewards can be found here:**](https://github.com/users/kyegomez/projects/1) +```python +agent.run("some_task") +``` -## **The Power of Collaboration** +#### 3. `chat` -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. - -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. +The `chat` method enables communication with the agent through a series of messages. -## **How the Bounty System Works** +```python +messages = [{"id": 1, "text": "Hello, agent!"}, {"id": 2, "text": "How are you?"}] +agent.chat(messages) +``` -The Swarms Bounty System is designed to be simple, transparent, and rewarding. Here's how it works: +#### 4. `step` -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) +The `step` method allows the agent to process a single message. -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 +agent.step("Hello, agent!") +``` -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. +### Asynchronous Methods -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. +The class also provides asynchronous variants of the core methods. -## **The Rewards System** +### Additional Functionality -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: +Additional functionalities for agent initialization and management of tools and memory are also provided. -### Tier 1: Bug Fixes and Minor Enhancements +```python +agent.tools(some_tools) +agent.memory(some_memory_store) +``` -| Reward | Description | -|------------------------|--------------------------------------------------------------| -| Cash Reward | $50 - $150 | -| Stock Reward | N/A | +## 4. Additional Information and Tips -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. +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. -### Tier 2: Moderate Enhancements and New Features +## 5. References and Resources -| Reward | Description | -|------------------------|--------------------------------------------------------------| -| Cash Reward | $151 - $300 | -| Stock Reward | 10+ | +For further exploration and understanding of AI agents and agent communication, refer to the relevant literature and research on this topic. -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. -### Tier 3: Major Features and Groundbreaking Innovations +-------------------------------------------------- -| Reward | Description | -|------------------------|--------------------------------------------------------------| -| Cash Reward | $301 - $++ | -| Stock Reward | 25+ | +# File: swarms\agents\agent_judge.md -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. +# 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. +A specialized agent for evaluating and judging outputs from other agents or systems. Acts as a quality control mechanism providing objective assessments and feedback. -## **The Benefits of Contributing** +Based on the research paper: **"Agent-as-a-Judge: Evaluate Agents with Agents"** - [arXiv:2410.10934](https://arxiv.org/abs/2410.10934) -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: +## Overview -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. +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. -2. **Build Your Portfolio**: Your contributions will become part of your professional portfolio, showcasing your expertise and dedication to the open source community. +Key capabilities: -3. **Network with Industry Experts**: Collaborate with our team of seasoned developers and gain invaluable insights and mentorship from industry leaders. +- **Quality Assessment**: Evaluates correctness, clarity, and completeness of agent outputs -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. +- **Structured Feedback**: Provides detailed critiques with strengths, weaknesses, and suggestions -5. **Gain Recognition**: Stand out in the crowded field of software development by having your contributions acknowledged and celebrated by the Swarms community. +- **Multimodal Support**: Can evaluate text outputs alongside images -## **Join the Movement** +- **Context Building**: Maintains evaluation context across multiple iterations -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. +- **Batch Processing**: Efficiently processes multiple evaluations -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. +## Architecture -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. +```mermaid +graph TD + A[Input Task] --> B[AgentJudge] + B --> C{Evaluation Mode} -[Join the swarm community now:](https://discord.gg/F4GGT5DERD) + C -->|step()| D[Single Eval] + C -->|run()| E[Iterative Eval] + C -->|run_batched()| F[Batch Eval] + D --> G[Agent Core] + E --> G + F --> G -## 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) + 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 -# File: docs_structure.md + J --> N + J --> O + J --> P + J --> Q -# Class/function +``` -Brief description -↓ +## Class Reference -↓ -## Overview -↓ -## Architecture (Mermaid diagram) -↓ -## Class Reference (Constructor + Methods) +### Constructor -table of parameters for every method and example +```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 +) +``` -↓ -## Examples +#### Parameters -↓ +| 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 | -## Conclusion -Benefits of class/structure, and more +### Methods +#### step() +```python +step( + task: str = None, + tasks: Optional[List[str]] = None, + img: Optional[str] = None +) -> str +``` --------------------------------------------------- +Processes a single task or list of tasks and returns evaluation. -# File: examples\agent_stream.md +| 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 | -# Agent with Streaming +**Returns:** `str` - Detailed evaluation response -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. +#### run() -## Installation +```python +run( + task: str = None, + tasks: Optional[List[str]] = None, + img: Optional[str] = None +) -> List[str] +``` -Install the swarms package using pip: +Executes evaluation in multiple iterations with context building. -```bash -pip install -U swarms -``` +| 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 | -## Basic Setup +**Returns:** `List[str]` - List of evaluation responses from each iteration -1. First, set up your environment variables: +#### run_batched() ```python -WORKSPACE_DIR="agent_workspace" -OPENAI_API_KEY="" +run_batched( + tasks: Optional[List[str]] = None, + imgs: Optional[List[str]] = None +) -> List[List[str]] ``` -## Step by Step +Executes batch evaluation of multiple tasks with corresponding images. -- Install and put your keys in `.env` +| 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) | -- Turn on streaming in `Agent()` with `streaming_on=True` +**Returns:** `List[List[str]]` - Evaluation responses for each task -- Optional: If you want to pretty print it, you can do `print_on=True`; if not, it will print normally +## Examples -## Code +### Basic Usage ```python -from swarms import Agent +from swarms import AgentJudge -# 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! -) +# Initialize with default settings +judge = AgentJudge() -# 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) +# Single task evaluation +result = judge.step(task="The capital of France is Paris.") +print(result) ``` -## Connect With Us +### Custom Configuration -If you'd like technical support, join our Discord below and stay updated on our Twitter for new updates! +```python +from swarms import AgentJudge -| 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 | +# Custom judge configuration +judge = AgentJudge( + agent_name="content-evaluator", + model_name="gpt-4", + max_loops=3, + verbose=True +) +# 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" +] +evaluation = judge.step(tasks=outputs) +print(evaluation) +``` --------------------------------------------------- +### Iterative Evaluation with Context -# File: examples\cookbook_index.md +```python +from swarms import AgentJudge -# Swarms Cookbook Examples Index +# Multiple iterations with context building +judge = AgentJudge(max_loops=3) -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. +# 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") +``` -## Finance & Trading +### Multimodal Evaluation -| 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) | +```python +from swarms import AgentJudge -## Healthcare & Medical +judge = AgentJudge() -| 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) | +# Evaluate with image +evaluation = judge.step( + task="Describe what you see in this image", + img="path/to/image.jpg" +) +print(evaluation) +``` -## Marketing & Content +### Batch Processing -| 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) | +```python +from swarms import AgentJudge -## Accounting & Finance Operations +judge = AgentJudge() -| 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) | +# Batch evaluation with images +tasks = [ + "Describe this chart", + "What's the main trend?", + "Any anomalies?" +] +images = [ + "chart1.png", + "chart2.png", + "chart3.png" +] -## Workshops & Tutorials +# 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}") +``` -| 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) | +## Reference -## Additional Resources +```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} +} +``` -| 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 | +-------------------------------------------------- -## Contributing +# File: swarms\agents\consistency_agent.md -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). +# Consistency Agent Documentation -## License +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. -This project is licensed under the MIT License - see the [LICENSE](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/LICENSE) file for details. +## Purpose --------------------------------------------------- +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. -# File: examples\index.md +## Class: `SelfConsistencyAgent` -# Swarms Examples Index +### Initialization -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. +- **`__init__`**: Initializes the `SelfConsistencyAgent` with specified parameters. -## What is Swarms? +#### Arguments -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. +| 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. | -## What You'll Find Here +### Methods -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: +- **`run`**: Generates multiple responses for the given task and aggregates them. + - **Arguments**: + - `task` (`str`): The input prompt. + - `img` (`Optional[str]`, optional): Image input for vision tasks. + - `answer` (`Optional[str]`, optional): Expected answer for validation (if eval=True). + - **Returns**: `Union[str, Dict[str, Any]]` - The aggregated final answer. +- **`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. -- **Single Agent Systems**: From basic implementations to advanced reasoning agents +- **`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. -- **Multi-Agent Architectures**: Collaborative swarms, hierarchical systems, and experimental topologies +- **`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. -- **Industry Applications**: Real-world use cases across finance, healthcare, security, and more +### Examples -- **Integration Examples**: Connect with popular AI models, tools, and frameworks +#### Example 1: Basic Usage -- **Advanced Patterns**: RAG systems, function calling, MCP integration, and more +```python +from swarms.agents.consistency_agent import SelfConsistencyAgent -## Getting Started +# Initialize the agent +agent = SelfConsistencyAgent( + name="Math-Reasoning-Agent", + model_name="gpt-4o-mini", + max_loops=1, + num_samples=5 +) -**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. +# Define a task +task = "What is the 40th prime number?" -**Looking for comprehensive tutorials?** Check out [The Swarms Cookbook](https://github.com/The-Swarm-Corporation/Cookbook) for detailed walkthroughs and advanced patterns. +# Run the agent +final_answer = agent.run(task) -**Want to see real-world applications?** Explore the Industry Applications section to see how Swarms solves practical problems. +# Print the final aggregated answer +print("Final aggregated answer:", final_answer) +``` -## Quick Navigation +#### Example 2: Using Custom Majority Voting Prompt +```python +from swarms.agents.consistency_agent import SelfConsistencyAgent -- [Single Agent Examples](#single-agent-examples) - Individual AI agents with various capabilities +# 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." +) -- [Multi-Agent Examples](#multi-agent-examples) - Collaborative systems and swarm architectures +# Define a task +task = "Explain the theory of relativity in simple terms." -- [Additional Resources](#additional-resources) - Community links and support channels +# Run the agent +final_answer = agent.run(task) -## Single Agent Examples +# Print the final aggregated answer +print("Final aggregated answer:", final_answer) +``` -### 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 | +#### Example 3: Evaluation Mode -### 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 | +```python +from swarms.agents.consistency_agent import SelfConsistencyAgent -### 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 | +# Initialize the agent with evaluation mode +agent = SelfConsistencyAgent( + name="Validation-Agent", + model_name="gpt-4o-mini", + num_samples=3, + eval=True +) -### 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 | +# 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") +``` -### 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 | +#### Example 4: Random Models for Diversity -### 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 | +```python +from swarms.agents.consistency_agent import SelfConsistencyAgent -### 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 | +# 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 +) -### 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 | +# Run the agent +result = agent.run("What are the benefits of renewable energy?") +print("Diverse reasoning result:", result) +``` -### 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 | +#### Example 5: Batch Processing -### 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 | +```python +from swarms.agents.consistency_agent import SelfConsistencyAgent -## Multi-Agent Examples +# Initialize the agent +agent = SelfConsistencyAgent( + name="Batch-Processing-Agent", + model_name="gpt-4o-mini", + num_samples=3 +) -### 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 | +# Define multiple tasks +tasks = [ + "What is the capital of France?", + "What is 15 * 23?", + "Explain photosynthesis in simple terms." +] -### 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 | +# Process all tasks +results = agent.batched_run(tasks) -### 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 | +# Print results +for i, result in enumerate(results): + print(f"Task {i+1} result: {result}") +``` -### 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 | +## Key Features -### 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 | +### 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: -### 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 | +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 -### 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 | +### 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 -### 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 | +### 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 -### 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 | +## Technical Details -### 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 | +### Concurrent Execution +The agent uses `ThreadPoolExecutor` to generate multiple responses concurrently, improving performance while maintaining independence between reasoning paths. -### 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 | +### 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 -### 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 | +### 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 -### 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 | +## Limitations -## Additional Resources +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 -- [Github](https://github.com/kyegomez/swarms) +## Best Practices -- Discord (https://t.co/zlLe07AqUX) +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 -- Telegram (https://t.co/dSRy143zQv) +--- -- X Community (https://x.com/i/communities/1875452887414804745) -------------------------------------------------- -# File: examples\paper_implementations.md +# File: swarms\agents\create_agents_yaml.md -# Multi-Agent Paper Implementations +# Building Agents from a YAML File -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. +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. -### Why Multi-Agent Research Matters +### 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. -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: +--- -- **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 +### Parameters -### Our Research Implementation Philosophy +| 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 | -We believe that the best way to advance the field is through practical implementation and real-world validation. Our approach includes: +--- -- **Faithful Reproduction**: Implementing research papers with high fidelity to original methodologies +### Return Types -- **Production Enhancement**: Adding enterprise-grade features like error handling, monitoring, and scalability +| 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. | -- **Open Source Commitment**: Making all implementations freely available to the research community +--- -- **Continuous Improvement**: Iterating on implementations based on community feedback and new research +### Detailed Return Types -### What You'll Find Here +| 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'` | -This documentation showcases our comprehensive collection of multi-agent research implementations, including: +--- +### Example Use Cases -- **Academic Paper Implementations**: Direct implementations of published research papers +1. **Creating Multiple Agents for Financial Analysis** -- **Enhanced Frameworks**: Production-ready versions with additional features and optimizations +```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." -- **Research Compilations**: Curated lists of influential multi-agent papers and resources + - 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?" +``` -- **Practical Examples**: Ready-to-use code examples and tutorials +```python +from swarms.structs.agent import Agent +from swarms.structs.swarm_router import SwarmRouter -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. +# Model representing your LLM +def model(prompt): + return f"Processed: {prompt}" -### Join the Multi-Agent Revolution +# Create agents and return them as a list +agents = create_agents_from_yaml(model=model, yaml_file="agents.yaml", return_type="agents") +print(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. +2. **Running a Swarm of Agents to Solve a Complex Task** -## Implemented Research Papers +```yaml +agents: + - agent_name: "Legal-Agent" + system_prompt: "Provide legal advice on corporate structuring." + task: "How to incorporate a business as an LLC?" -| 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 | +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 +``` -## Additional Research Resources +```python +import os -### Multi-Agent Papers Compilation +from dotenv import load_dotenv +from loguru import logger +from swarm_models import OpenAIChat -We maintain a comprehensive list of multi-agent research papers at: [awesome-multi-agent-papers](https://github.com/kyegomez/awesome-multi-agent-papers) +from swarms.agents.create_agents_from_yaml import ( + create_agents_from_yaml, +) -### Research Lists +# Load environment variables +load_dotenv() -Our research compilation includes: +# Path to your YAML file +yaml_file = "agents_multi_agent.yaml" -- **Projects**: ModelScope-Agent, Gorilla, BMTools, LMQL, Langchain, MetaGPT, AutoGPT, and more -- **Research Papers**: BOLAA, ToolLLM, Communicative Agents, Mind2Web, Voyager, Tree of Thoughts, and many others +# Get the OpenAI API key from the environment variable +api_key = os.getenv("GROQ_API_KEY") -- **Blog Articles**: Latest insights and developments in autonomous agents +# 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, +) -- **Talks**: Presentations from leading researchers like Geoffrey Hinton and Andrej Karpathy +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" + ) + logger.info(f"Results from agents: {task_results}") +except Exception as e: + logger.error(f"An error occurred: {e}") -## Implementation Details +``` -### MALT Framework +3. **Returning Both Agents and Tasks** -The MALT implementation provides: +```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." +``` -- **Three-Agent Architecture**: Creator, Verifier, and Refiner agents +```python +from swarms.structs.agent import Agent -- **Structured Workflow**: Coordinated task execution with conversation history +# Model representing your LLM +def model(prompt): + return f"Processed: {prompt}" -- **Reliability Features**: Error handling, validation, and quality assurance +# 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) +``` -- **Extensibility**: Custom agent integration and configuration options +--- -### MAI-DxO System -The MAI Diagnostic Orchestrator features: +--- -- **Virtual Physician Panel**: Multiple specialized medical agents +### YAML Schema Overview: -- **Cost Optimization**: Efficient diagnostic workflows +Below is a breakdown of the attributes expected in the YAML configuration file, which governs how agents and swarms are created. -- **Iterative Refinement**: Continuous improvement of diagnoses +### YAML Attributes Table: -- **Medical Expertise**: Domain-specific knowledge and reasoning +| 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?"` | +#### Swarm Architecture (Optional): -### AI-CoScientist Framework +| 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?"` | -The AI-CoScientist implementation includes: +--- +### YAML Schema Example: -- **Tournament-Based Selection**: Elo rating system for hypothesis ranking +Below is an updated YAML schema that conforms to the function's expectations: -- **Peer Review System**: Comprehensive evaluation of scientific proposals +```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 -- **Hypothesis Evolution**: Iterative refinement based on feedback + - 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?" -- **Diversity Control**: Proximity analysis to maintain hypothesis variety +# 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 +``` +# Diagram +```mermaid +graph TD; + A[Task] -->|Send to| B[Financial-Analysis-Agent] + A -->|Send to| C[Stock-Analysis-Agent] +``` -### Mixture of Agents (MoA) +--- -The MoA architecture provides: +### How to Use `create_agents_from_yaml` Function with YAML: -- **Parallel Processing**: Multiple agents working simultaneously +- You need to plug in your specific model until we can create a model router that can fetch any model and set specific settings -- **Expert Specialization**: Domain-specific agent capabilities +#### Example Code: +```python +import os -- **Iterative Refinement**: Continuous improvement through collaboration +from dotenv import load_dotenv +from loguru import logger +from swarm_models import OpenAIChat -- **State-of-the-Art Performance**: Achieving superior results through collective intelligence +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" -## Contributing -We welcome contributions to implement additional research papers! If you'd like to contribute: +# Get the OpenAI API key from the environment variable +api_key = os.getenv("GROQ_API_KEY") -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 +# 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, +) -## Citation +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" # + ) -If you use any of these implementations in your research, please cite the original papers and the Swarms framework: + logger.info(f"Results from agents: {task_results}") +except Exception as e: + logger.error(f"An error occurred: {e}") -```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 - -Join our community to stay updated on the latest multi-agent research implementations: - -- **Discord**: [Join our community](https://discord.gg/jM3Z6M9uMq) - -- **Documentation**: [docs.swarms.world](https://docs.swarms.world) - -- **GitHub**: [kyegomez/swarms](https://github.com/kyegomez/swarms) - -- **Research Papers**: [awesome-multi-agent-papers](https://github.com/kyegomez/awesome-multi-agent-papers) +--- +### 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`. +### 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. -------------------------------------------------- -# File: examples\templates.md +# File: swarms\agents\external_party_agents.md -# Templates & Applications Documentation -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. -🔗 **Main Repository**: [Swarms Framework](https://github.com/kyegomez/swarms) +# **Swarms External Agent Integration** ---- +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. -## 🏥 Healthcare & Medical Applications +--- -### Medical Diagnosis & Analysis +## **Quick Overview** -| 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 | +- **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. -### Medical Operations & Administration +### **Agent Class** -| 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 | +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 +from swarms import Agent -## 💰 Financial Services & Trading +class ExternalAgent(Agent): + def run(self, task: str) -> str: + # Implement logic to run external agent + pass -### Trading & Investment + 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) +``` -| 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 | +--- -### Financial Analysis & Management +## **Griptape Agent Integration Example** -| 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 | +In this example, we will create a **Griptape** agent by inheriting from the Swarms `Agent` class and implementing the `run` method. -### Insurance & Lending +### **Griptape Integration Steps**: -| 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 | +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. ---- +## **Griptape Example Code**: -## 🔬 Research & Development +```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, +) -### Scientific Research +# 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, + ) -| 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 | + # 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) -### Mathematical & Analytical -| Name | Description | Type | Repository | -|------|-------------|------|------------| -| [Generalist-Mathematician-Swarm](https://github.com/The-Swarm-Corporation/Generalist-Mathematician-Swarm) | Mathematical problem-solving agent swarm | Mathematics | Science | +# Example usage: +griptape_swarms_agent = GriptapeSwarmsAgent() +output = griptape_swarms_agent.run("https://griptape.ai, griptape.txt") +print(output) +``` ---- +### **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. -## 💼 Business & Marketing -### Marketing & Content +## **Additional Features**: +You can enhance your external agents with additional features such as: -| 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 | +- **Saving outputs** to JSON, databases, or logs. -### Legal Services +- **Handling errors** and retry mechanisms for robustness. -| Name | Description | Type | Repository | -|------|-------------|------|------------| -| [Legal-Swarm-Template](https://github.com/The-Swarm-Corporation/Legal-Swarm-Template) | Legal document processing and analysis | Legal Technology | Business | +- **Custom logging** with tools like **Loguru** for extensive debugging. --- -## 🛠️ Development Tools & Platforms +## **Langchain Agent Integration Example** -### Core Platforms & Operating Systems +Next, we demonstrate how to integrate a **Langchain** agent with **Swarms** by following similar steps. -| 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 | +### **Langchain Integration Steps**: -### Development Tools & Utilities +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. -| 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 | +## **Langchain Example Code**: -### Templates & Examples +```python +from swarms import Agent as SwarmsAgent +from langchain import LLMChain +from langchain.llms import OpenAI +from langchain.prompts import PromptTemplate -| 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 | +# 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) ---- + # 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 -## 📚 Educational Resources +# Example usage: +langchain_swarms_agent = LangchainSwarmsAgent() +output = langchain_swarms_agent.run("What is the capital of France?") +print(output) +``` -### Courses & Guides +### **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. -| 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 | -### Testing & Evaluation +### Additional Examples from other providers -| Name | Description | Type | Repository | -|------|-------------|------|------------| -| [swarms-evals](https://github.com/The-Swarm-Corporation/swarms-evals) | Evaluation framework for swarm systems | Testing Framework | Development | ---- +### 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 -## 🚀 Getting Started + # 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) -### Prerequisites + 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 3.8+ + # Example usage: + openai_agent = OpenAIFunctionAgent() + output = openai_agent.run("summarize, Provide a short summary of this text...") + print(output) + ``` -- Basic understanding of AI agents and multi-agent systems +### 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**. -- Familiarity with the Swarms framework + ## 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) -### Installation + 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." -```bash -pip install swarms -``` + # Example usage: + rasa_swarms_agent = RasaSwarmsAgent("path/to/rasa_model") + output = rasa_swarms_agent.run("Hello, how can I get a refund?") + print(output) + ``` -### Quick Start +### 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. -1. Choose a template from the categories above + ## Example Integration: + ```python + from swarms import Agent as SwarmsAgent + from transformers import pipeline -2. Clone the repository + # 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) -3. Follow the setup instructions in the README + 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"] -4. Customize the agents for your specific use case + # Example usage: + hf_swarms_agent = HuggingFaceSwarmsAgent("gpt2") + output = hf_swarms_agent.run("Once upon a time in a land far, far away...") + print(output) + ``` ---- +### 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 -## 🤝 Contributing + # Custom AutoGPT Agent + class AutoGPTSwarmsAgent(SwarmsAgent): + def __init__(self, config, *args, **kwargs): + # Initialize AutoGPT with configuration + self.agent = AutoGPT(config) + super().__init__(*args, **kwargs) -The Swarms ecosystem is constantly growing. To contribute: + def run(self, task: str) -> str: + # Execute task recursively using AutoGPT + result = self.agent.run(task) + return result -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 + # Example usage: + autogpt_swarms_agent = AutoGPTSwarmsAgent({"goal": "Solve world hunger"}) + output = autogpt_swarms_agent.run("Develop a plan to solve world hunger.") + print(output) + ``` ---- +### 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 -## 📞 Support & Community + # 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) -Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights! + 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 -| 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) | + # 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) + ``` ---- +### 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 -## 📊 Statistics + # Custom ChatterBot Agent + class ChatterBotSwarmsAgent(SwarmsAgent): + def __init__(self, name: str, *args, **kwargs): + # Initialize ChatterBot + self.agent = ChatBot(name) + super().__init__(*args, **kwargs) -- **Total Projects**: 35+ + def run(self, task: str) -> str: + # Get a response from ChatterBot based on user input + response = self.agent.get_response(task) + return str(response) -- **Industries Covered**: Healthcare, Finance, Research, Business, Development + # Example usage: + chatterbot_swarms_agent = ChatterBotSwarmsAgent("Assistant") + output = chatterbot_swarms_agent.run("What is the capital of Italy?") + print(output) + ``` -- **Project Types**: Templates, Applications, Tools, Educational Resources +### 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 -- **Active Development**: Continuous updates and new additions + # 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 + # Example usage: + api_swarms_agent = APIAgent() + output = api_swarms_agent.run("https://api.example.com/search, python") + print(output) + ``` --- +### **Summary of Integrations**: --------------------------------------------------- - -# File: governance\main.md - -# 🔗 Links & Resources - -Welcome to the Swarms ecosystem. Click any tile below to explore our products, community, documentation, and social platforms. +- **Griptape**: Integrate with tools for web scraping, summarization, etc. ---- +- **Langchain**: Use powerful language model orchestration. - +- **Hugging Face**: Leverage transformer models. -
+- **AutoGPT/BabyAGI**: Recursive, autonomous task execution. -🗣️ Swarms Chat +- **DialogFlow**: Integrate conversational flows for voice/chat-based systems. -🛍️ Swarms Marketplace +- **ChatterBot**: Machine-learning conversational agents. -📚 Swarms API Docs +- **Custom APIs**: Leverage external APIs as agents for custom workflows. -🚀 Swarms Startup Program -💻 GitHub: Swarms (Python) +--- -🦀 GitHub: Swarms (Rust) -💬 Join Our Discord +## **Conclusion**: -📱 Telegram Group +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. -🐦 Twitter / X +For more examples and use cases, please refer to the official Swarms documentation site. -✍️ Swarms Blog on Medium -
---- +-------------------------------------------------- -## 💡 Quick Summary +# File: swarms\agents\gkp_agent.md -| 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) | +# Generated Knowledge Prompting (GKP) Agent ---- +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. -> 🐝 Swarms is building the agentic internet. Join the movement and build the future with us. +## Overview +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 --------------------------------------------------- +## Architecture -# File: guides\agent_evals.md +```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 +``` -### Understanding Agent Evaluation Mechanisms +## Use Cases -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. +```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] +``` -#### 1. Introduction to Agent Evaluation Mechanisms +## API Reference -Agent evaluation mechanisms refer to the processes and criteria used to assess the performance of agents within a system. These mechanisms are essential for: +### GKPAgent -- **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. +The main agent class that orchestrates the knowledge generation and reasoning process. -### 2. Key Components of Agent Evaluation +#### Initialization Parameters -To effectively evaluate agents, several components and metrics are considered: +| 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 | -#### a. Performance Metrics +#### Methods -These are quantitative measures used to assess how well an agent is performing. Common performance metrics include: +| 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]]] | -- **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. +### KnowledgeGenerator -#### b. Evaluation Criteria +Component responsible for generating relevant knowledge for queries. -Evaluation criteria define the standards or benchmarks against which agent performance is measured. These criteria are often task-specific and may include: +#### Initialization Parameters -- **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. +| 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. The Process of Agent Evaluation +#### Methods -The evaluation process involves several steps, which can be visualized using Mermaid graphs: +| Method | Description | Parameters | Returns | +|--------|-------------|------------|---------| +| generate_knowledge(query: str) | Generate relevant knowledge for a query | query: str | List[str] of generated knowledge statements | -#### a. Define Evaluation Metrics +### Reasoner -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. +Component that uses generated knowledge to reason about and answer queries. -```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] -``` +#### Initialization Parameters -#### b. Collect Data +| 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 | -Data collection involves gathering information on the agent's performance. This data can come from logs, user feedback, or direct observations. +#### Methods -```mermaid -graph TD - A[Collect Data] --> B[Logs] - A --> C[User Feedback] - A --> D[Direct Observations] -``` +| 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 | -#### c. Analyze Performance +## Example Usage -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. +```python +from swarms.agents.gkp_agent import GKPAgent -```mermaid -graph TD - A[Analyze Performance] --> B[Statistical Analysis] - A --> C[Machine Learning Models] - A --> D[Other Analytical Techniques] -``` +# 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 +) -#### d. Generate Reports +# Example queries +queries = [ + "What are the implications of quantum entanglement on information theory?", +] -After analysis, performance reports are generated. These reports provide insights into how well the agent is performing and identify areas for improvement. +# Run the agent +results = agent.run(queries) -```mermaid -graph TD - A[Generate Reports] --> B[Performance Insights] - B --> C[Identify Areas for Improvement] +# Print results +for i, result in enumerate(results): + print(f"\nQuery {i+1}: {queries[i]}") + print(f"Answer: {result}") ``` -### 4. Tracking Agent Accuracy +## Best Practices -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: +1. **Knowledge Generation** + - Set appropriate number of knowledge items based on query complexity + - Monitor knowledge quality and relevance + - Adjust model parameters for optimal performance -#### a. Define Correctness Criteria +2. **Reasoning Process** + - Ensure diverse reasoning paths for complex queries + - Validate confidence levels + - Consider multiple perspectives -The first step is to define what constitutes a correct action or decision for the agent. +3. **Coordination** + - Review coordination logic for complex scenarios + - Validate final answers against source knowledge + - Monitor processing time and optimize if needed -```mermaid -graph TD - A[Define Correctness Criteria] --> B[Task-Specific Standards] - B --> C[Action Accuracy] - B --> D[Decision Accuracy] -``` +## Performance Considerations -#### b. Monitor Agent Actions +- 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 -Agents' actions are continuously monitored to track their performance. This monitoring can be done in real-time or through periodic evaluations. +## Error Handling -```mermaid -graph TD - A[Monitor Agent Actions] --> B[Real-Time Monitoring] - A --> C[Periodic Evaluations] -``` +The agent includes robust error handling for: +- Invalid queries +- Failed knowledge generation +- Reasoning errors +- Coordination failures -#### c. Compare Against Correctness Criteria -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?] -``` +# File: swarms\agents\index.md -#### d. Calculate Accuracy Metrics +# Agents Introduction -Accuracy metrics are calculated based on the comparison results. These metrics provide a quantitative measure of the agent's accuracy. +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. -```mermaid -graph TD - A[Calculate Accuracy Metrics] --> B[Accuracy Percentage] - A --> C[Error Rate] -``` +## Table of Contents -### 5. Measuring Agent Accuracy +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) -Measuring agent accuracy involves several steps and considerations: +## Prerequisites & Installation -#### a. Data Labeling +### System Requirements -To measure accuracy, the data used for evaluation must be accurately labeled. This involves annotating the data with the correct actions or decisions. +- Python 3.7+ -```mermaid -graph TD - A[Data Labeling] --> B[Annotate Data with Correct Actions] - B --> C[Ensure Accuracy of Labels] -``` +- OpenAI API key (for GPT models) -#### b. Establish Baseline Performance +- Anthropic API key (for Claude models) -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. +### Installation -```mermaid -graph TD - A[Establish Baseline Performance] --> B[Evaluate Sample Data] - B --> C[Set Performance Benchmarks] +```bash +pip3 install -U swarms ``` -#### c. Regular Evaluations +### Environment Setup -Agents are regularly evaluated to measure their accuracy over time. This helps in tracking performance trends and identifying any deviations from the expected behavior. +Create a `.env` file with your API keys: -```mermaid -graph TD - A[Regular Evaluations] --> B[Track Performance Over Time] - B --> C[Identify Performance Trends] - B --> D[Detect Deviations] +```bash +OPENAI_API_KEY="your-openai-api-key" +ANTHROPIC_API_KEY="your-anthropic-api-key" +WORKSPACE_DIR="agent_workspace" ``` -#### d. Feedback and Improvement +## Basic Agent Configuration -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. +### Core Agent Structure -```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] -``` +The Agent class provides a comprehensive set of parameters for customization: -### 6. Visualizing Agent Evaluation with Mermaid Graphs +```python +from swarms import Agent -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: +# Basic agent initialization +agent = Agent( + 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, + max_tokens=4096, + temperature=0.7, + output_type="str", + safety_prompt_on=True +) +``` -#### a. Overall Evaluation Process +### Key Configuration Parameters -```mermaid -graph TD - A[Define Evaluation Metrics] --> B[Collect Data] - B --> C[Analyze Performance] - C --> D[Generate Reports] -``` +| 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 | -#### b. Accuracy Tracking +### Simple Example -```mermaid -graph TD - A[Define Correctness Criteria] --> B[Monitor Agent Actions] - B --> C[Compare Against Correctness Criteria] - C --> D[Calculate Accuracy Metrics] -``` +```python +from swarms import Agent -#### c. Continuous Improvement Cycle +# 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" +) -```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 +# Run the agent +response = financial_agent.run("What are the best investment strategies for a 30-year-old?") +print(response) ``` -### 7. Case Study: Evaluating a Chatbot 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. +## Multi-Modal Capabilities -#### a. Define Evaluation Metrics +### Image Processing -For the chatbot, key performance metrics might include: +The Agent class supports comprehensive image analysis through vision-enabled models: -- **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. +```python +from swarms import Agent -#### b. Collect Data +# 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" +) -Data is collected from chatbot interactions, including user queries, responses, and feedback. +# Analyze a single image +response = vision_agent.run( + task="Analyze this image for quality control purposes", + img="path/to/image.jpg" +) -#### c. Analyze Performance +# 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 +) +``` -Performance analysis involves comparing the chatbot's responses against a predefined set of correct responses and calculating accuracy metrics. +### Supported Image Formats -#### d. Generate Reports +| 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 | -Reports are generated to provide insights into the chatbot's performance, highlighting areas where it excels and areas needing improvement. +### Quality Control Example -### 8. Best Practices for Agent Evaluation +```python +from swarms import Agent +from swarms.prompts.logistics import Quality_Control_Agent_Prompt -Here are some best practices to ensure effective agent evaluation: +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") -#### a. Use Realistic Scenarios +# 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, + tools=[security_analysis] +) -Evaluate agents in realistic scenarios that closely mimic real-world conditions. This ensures that the evaluation results are relevant and applicable. +# Analyze factory image +response = quality_agent.run( + task="Analyze this factory image for safety and quality issues", + img="factory_floor.jpg" +) +``` -#### b. Continuous Monitoring +## Tool Integration -Continuously monitor agent performance to detect and address issues promptly. This helps in maintaining high performance levels. +### Creating Custom Tools -#### c. Incorporate User Feedback +Tools are Python functions that extend your agent's capabilities: -User feedback is invaluable for improving agent performance. Incorporate feedback into the evaluation process to identify and rectify shortcomings. +```python +import json +import requests +from typing import Optional, Dict, Any -#### d. Regular Updates +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)}"}) -Regularly update the evaluation metrics and criteria to keep pace with evolving tasks and requirements. +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)}"}) +``` -### Conclusion +### Tool Integration Example -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. +```python +from swarms import Agent --------------------------------------------------- - -# File: guides\financial_analysis_swarm_mm.md - -# Building a Multi-Agent System for Real-Time Financial Analysis: A Comprehensive Tutorial - -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. - -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. - -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 - -Now, let's break down our financial analysis system step by step. - -## Step 1: Setting Up the Environment -First install the necessary packages: +# 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] +) -```bash -$ pip3 install -U swarms yfiance swarm_models fredapi pandas +# 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]?" +) ``` -First, we need to set up our environment and import the necessary libraries: +### API Integration Tools ```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() - -# Set up logging -logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s') -logger = logging.getLogger(__name__) - -# 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') - -# Initialize FRED client -fred_client = Fred(api_key=FRED_API_KEY) - -# Polygon API base URL -POLYGON_BASE_URL = "https://api.polygon.io" -``` - -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 +import json +from typing import List -To respect API rate limits, we implement rate limiting decorators: +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)}"}) -```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: +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 await response.json() + return json.dumps(response.json(), indent=2) + + except Exception as e: + return json.dumps({"error": f"API error: {str(e)}"}) -@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) -``` +# 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] +) -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. +# Analyze crypto market +response = crypto_agent.run("Analyze the current Bitcoin price and show me the top 5 cryptocurrencies") +``` -## Step 3: Implementing Data Fetching Functions +## Structured Outputs -Next, we implement functions to fetch data from various sources: +### Function Schema Definition -### Yahoo Finance Integration +Define structured outputs using OpenAI's function calling format: ```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 -``` +from swarms import Agent -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. +# 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"] + } + } +} -### Polygon.io Integration +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"] + } + } +} -```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 +# 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] +) -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 [] +# Generate structured analysis +response = structured_agent.run( + "Analyze Apple stock (AAPL) performance with comprehensive analysis for the last 3 months" +) ``` -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. +## Advanced Features -### FRED Integration +### Dynamic Temperature Control ```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 +from swarms import Agent -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 {} +# 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" +) ``` -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. - -## Step 4: Creating Specialized Agents - -Now we create our specialized agents using the Swarms framework: +### Output Type Configurations ```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, -) - -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, +# Different output type examples +json_agent = Agent( + agent_name="JSON-Agent", + system_prompt="Always respond in valid JSON format", + output_type="json" ) -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, +streaming_agent = Agent( + agent_name="Streaming-Agent", + system_prompt="Provide detailed streaming responses", + output_type="str-all-except-first" ) -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, +final_only_agent = Agent( + agent_name="Final-Only-Agent", + system_prompt="Provide only the final result", + output_type="final" ) ``` -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. - -## Step 5: Building the Multi-Agent System - -We then combine our specialized agents into a multi-agent system: +### Safety and Content Filtering ```python -agents = [stock_agent, market_agent, macro_agent, news_agent] -flow = "StockAgent -> MarketAgent -> MacroAgent -> NewsAgent" +from swarms import Agent -agent_system = AgentRearrange(agents=agents, flow=flow) +# 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 +) ``` -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. - -## Step 6: Implementing Real-Time Analysis +## Best Practices -Now we implement our main analysis function: +### Error Handling and Robustness ```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']) - - # Prepare input for the multi-agent system - input_data = f""" - Yahoo Finance Data: - {yf_realtime} +import logging +from swarms import Agent - Recent Stock History: - {yf_data.tail().to_string() if yf_data is not None else 'Data unavailable'} +# Configure logging +logging.basicConfig(level=logging.INFO) +logger = logging.getLogger(__name__) - Polygon.io Trade Data: - {polygon_trades} +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 - Polygon.io Quote Data: - {polygon_quotes} +# Example usage +try: + result = robust_agent_execution(agent, "Analyze market trends") + print(result) +except Exception as e: + print(f"Agent execution failed: {e}") +``` - Recent News: - {polygon_news[:3] if polygon_news else 'No recent news available'} +### Performance Optimization - Economic Indicators: - {fred_data} +```python +from swarms import Agent +import time - 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. - """ +# 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" +) - # 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}" +# 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 ``` -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. - -## Step 7: Implementing Advanced Use Cases - -We then implement more advanced analysis functions: +## Complete Examples -### Compare Stocks +### Multi-Modal Quality Control System ```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} - - 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}" -``` +from swarms import Agent +from swarms.prompts.logistics import Quality_Control_Agent_Prompt -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 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") -### Sector Analysis +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" -```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'] - } +# 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} - if sector not in sector_stocks: - return f"Sector '{sector}' not found. Available sectors: {', '.join(sector_stocks.keys())}" + You are an advanced quality control system with the following capabilities: - stocks = sector_stocks[sector][:5] + 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 - sector_data = {} - for stock in stocks: - sector_data[stock] = await real_time_analysis(session, stock) + 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 - sector_prompt = f""" - Analyze the {sector} sector based on the following data from its top stocks: - {sector_data} + Always provide specific, actionable feedback. + """, + model_name="gpt-4o-mini", + multi_modal=True, + max_loops=1, + tools=[security_analysis, quality_assessment], + output_type="str" +) - 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 - """ +# Process factory images +factory_images = ["factory_floor.jpg", "assembly_line.jpg", "safety_equipment.jpg"] + +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) +``` + +### Advanced Financial Analysis Agent + +```python +from swarms import Agent +import json +import requests + +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) + +def calculate_risk_metrics(prices: list, benchmark_prices: list) -> str: + """Calculate risk metrics for a portfolio.""" + import numpy as np try: - analysis = agent_system.run(sector_prompt) - logger.info(f"Sector analysis completed for {sector}") - return analysis + 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: - logger.error(f"Error during sector analysis for {sector}: {e}") - return f"Error during sector analysis: {e}" -``` - -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. + return json.dumps({"error": f"Risk calculation error: {str(e)}"}) -### Economic Impact 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"] + } + } +} -```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) +# 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: - if indicator_data is None or len(indicator_data) < 2: - return f"Insufficient data for indicator {indicator}" + - Fundamental analysis and valuation + - Technical analysis and chart patterns + - Risk assessment and portfolio optimization + - Market sentiment analysis + - Economic indicator interpretation - # 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) + Your analysis should be: + - Data-driven and objective + - Risk-aware and practical + - Clearly structured and actionable + - Compliant with financial regulations - 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()} + 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" +) - 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 +# Comprehensive financial analysis +analysis_response = financial_analyst.run( + "Perform a comprehensive analysis of Apple Inc. (AAPL) including technical and fundamental analysis with structured recommendations" +) - 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}" +print(json.dumps(json.loads(analysis_response), indent=2)) ``` -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. +### Multi-Agent Collaboration System -## Step 8: Running the Analysis +```python +from swarms import Agent +import json -Finally, we implement our main function to run all of our analyses: +# 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 +) -```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) +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 +) - comparison_result = await compare_stocks(session, ['AAPL', 'GOOGL', 'MSFT']) - print("\nStock Comparison:") - print(comparison_result) +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, + temperature=0.4 +) - tech_sector_analysis = await sector_analysis(session, 'Technology') - print("\nTechnology Sector Analysis:") - print(tech_sector_analysis) +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 + } - gdp_impact = await economic_impact_analysis(session, 'GDP', 22000) - print("\nEconomic Impact Analysis:") - print(gdp_impact) +# Example: Collaborative investment analysis +investment_analysis = collaborative_analysis("renewable energy sector investment opportunities") -if __name__ == "__main__": - asyncio.run(main()) +for phase, results in investment_analysis.items(): + print(f"\n=== {phase.upper()} PHASE ===") + print(results) ``` -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. +## Support and Resources -## Conclusion and Next Steps +Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights! -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: +| 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) | -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 +### Getting Help -This system provides a powerful foundation for financial analysis, but there's always room for expansion and improvement. Here are some potential next steps: +If you encounter issues or need assistance: -1. **Expand data sources**: Consider integrating additional financial data providers for even more comprehensive analysis. +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 -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. +### Contributing -3. **Implement a user interface**: Consider building a web interface or dashboard to make the system more user-friendly for non-technical analysts. +We welcome contributions! Here's how to get involved: -4. **Add visualization capabilities**: Integrate data visualization tools to help interpret complex financial data more easily. +- **Report Bugs**: Help us improve by reporting issues -5. **Implement a backtesting system**: Develop a system to evaluate your multi-agent system's performance on historical data. +- **Suggest Features**: Share your ideas for new capabilities -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. +- **Submit Code**: Contribute improvements and new features -7. **Implement real-time monitoring**: Set up a system to continuously monitor markets and alert you to significant changes or opportunities. +- **Improve Documentation**: Help make our docs better -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. +- **Share Examples**: Show how you're using Swarms in your projects -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). +--- -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 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.* -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! +# File: swarms\agents\iterative_agent.md +# Iterative Reflective Expansion (IRE) Algorithm Documentation +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. -## Swarm Resources: +## Architecture -* [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) +```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 ✅"] --------------------------------------------------- +``` -# File: guides\financial_data_api.md +--- -# Analyzing Financial Data with AI Agents using Swarms Framework +## Workflow -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. +1. Generate initial hypotheses +2. Simulate paths +3. Reflect on errors +4. Revise paths +5. Select promising paths +6. Synthesize solution -## Table of Contents +## Class: IterativeReflectiveExpansion -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) +### Arguments -## Introduction to Swarms Framework +| 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. | -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. +### Methods -## Setting Up the Environment +| 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. | -Before we dive into connecting AI agents with financial data providers, let's set up our environment: +## Use-Cases -1. Install the Swarms framework: +### Example 1: Solving a Mathematical Problem -```bash -pip install -U swarms -``` +```python +from swarms import IterativeReflectiveExpansion -2. Install additional required libraries: +agent = IterativeReflectiveExpansion( + max_iterations=3, +) -```bash -pip install requests pandas numpy matplotlib +agent.run("What is the 40th prime number?") ``` -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. +## Conclusion -## Connecting AI Agents with Financial Data Providers +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. -Now, let's explore how to connect AI agents using the Swarms framework with different financial data providers. -### Polygon.io +-------------------------------------------------- -First, we'll create an AI agent that can fetch and analyze stock data from Polygon.io. +# File: swarms\agents\message.md -```python -import os -from swarms import Agent -from swarms.models import OpenAIChat -from dotenv import load_dotenv -import requests -import pandas as pd +# The Module/Class Name: Message -load_dotenv() +In the swarms.agents framework, the class `Message` is used to represent a message with timestamp and optional metadata. -# Polygon.io API setup -POLYGON_API_KEY = os.getenv("POLYGON_API_KEY") -POLYGON_BASE_URL = "https://api.polygon.io/v2" +## Overview and Introduction -# OpenAI API setup -OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") +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. -# Create an instance of the OpenAIChat class -model = OpenAIChat( - openai_api_key=OPENAI_API_KEY, - model_name="gpt-4", - temperature=0.1 -) +## Class Definition -# 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 -) +### Constructor: `__init__` -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']) +The constructor of the `Message` class takes three parameters: -# Example usage -symbol = "AAPL" -from_date = "2023-01-01" -to_date = "2023-12-31" +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. -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}: +1. `__repr__(self)`: Returns a string representation of the `Message` object, including the timestamp, sender, and content. -{stock_data.to_string()} +```python +class Message: + """ + Represents a message with timestamp and optional metadata. -Provide insights on the stock's performance, including trends, volatility, and any notable events. -""" + Usage + -------------- + mes = Message( + sender = "Kye", + content = "message" + ) -analysis = agent.run(analysis_request) -print(analysis) + print(mes) + """ + + 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. + + Returns: + (str) A string containing the timestamp, sender, and content of the message. + """ + return f"{self.timestamp} - {self.sender}: {self.content}" ``` -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. +## Functionality and Usage -### Alpha Vantage +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. -Next, let's create an agent that can work with Alpha Vantage data to perform fundamental analysis. +### Usage Example 1 + +Creating a `Message` object and displaying its string representation. ```python -import os -from swarms import Agent -from swarms.models import OpenAIChat -from dotenv import load_dotenv -import requests +mes = Message(sender="Kye", content="Hello! How are you?") -load_dotenv() +print(mes) +``` -# Alpha Vantage API setup -ALPHA_VANTAGE_API_KEY = os.getenv("ALPHA_VANTAGE_API_KEY") -ALPHA_VANTAGE_BASE_URL = "https://www.alphavantage.co/query" +Output: +``` +2023-09-20 13:45:00 - Kye: Hello! How are you? +``` -# OpenAI API setup -OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") +### Usage Example 2 -# Create an instance of the OpenAIChat class -model = OpenAIChat( - openai_api_key=OPENAI_API_KEY, - model_name="gpt-4", - temperature=0.1 -) +Creating a `Message` object with metadata. -# 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 +```python +metadata = {"priority": "high", "category": "urgent"} +mes_with_metadata = Message( + sender="Alice", content="Important update", metadata=metadata ) -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() - -# Example usage -symbol = "MSFT" +print(mes_with_metadata) +``` -income_statement = get_income_statement(symbol) +Output: +``` +2023-09-20 13:46:00 - Alice: Important update +``` -analysis_request = f""" -Analyze the following income statement data for {symbol}: +### Usage Example 3 -{income_statement} +Creating a `Message` object without providing metadata. -Provide insights on the company's financial health, profitability trends, and any notable observations. -""" +```python +mes_no_metadata = Message(sender="Bob", content="Reminder: Meeting at 2PM") -analysis = agent.run(analysis_request) -print(analysis) +print(mes_no_metadata) ``` -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. +Output: +``` +2023-09-20 13:47:00 - Bob: Reminder: Meeting at 2PM +``` -```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 +## Additional Information and Tips -load_dotenv() +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. -# OpenAI API setup -OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") +## References and Resources -# Create an instance of the OpenAIChat class -model = OpenAIChat( - openai_api_key=OPENAI_API_KEY, - model_name="gpt-4", - temperature=0.1 -) +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. -# 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 -) -def get_stock_data(symbol, start_date, end_date): - stock = yf.Ticker(symbol) - data = stock.history(start=start_date, end=end_date) - return data +-------------------------------------------------- -# Example usage -symbol = "GOOGL" -start_date = "2023-01-01" -end_date = "2023-12-31" +# File: swarms\agents\new_agent.md -stock_data = get_stock_data(symbol, start_date, end_date) +# How to Create Good Agents -# 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() +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. -analysis_request = f""" -Analyze the following stock price data and technical indicators for {symbol} from {start_date} to {end_date}: +## Overview -{stock_data.tail(30).to_string()} +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: -Provide insights on the stock's price trends, potential support and resistance levels, and any notable trading signals based on the moving averages. -""" +- 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. -analysis = agent.run(analysis_request) -print(analysis) -``` +By following these guidelines, you can create agents that integrate well with broader systems and exhibit high reliability in real-world applications. -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. +--- -### IEX Cloud +## Creating a Custom Agent -Let's create an agent that can work with IEX Cloud data to analyze company news sentiment. +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 -import os +from typing import Callable, Any from swarms import Agent -from swarms.models import OpenAIChat -from dotenv import load_dotenv -import requests -load_dotenv() +class MyNewAgent(Agent): + """ + A custom agent class for specialized tasks. -# IEX Cloud API setup -IEX_CLOUD_API_KEY = os.getenv("IEX_CLOUD_API_KEY") -IEX_CLOUD_BASE_URL = "https://cloud.iexapis.com/stable" + 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. + """ -# OpenAI API setup -OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") + def __init__(self, name: str, system_prompt: str, model_name: str = None, description: str, llm: Callable = None): + """ + Initialize the custom agent. -# Create an instance of the OpenAIChat class -model = OpenAIChat( - openai_api_key=OPENAI_API_KEY, - model_name="gpt-4", - temperature=0.1 -) + 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 -# 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 -) + def run(self, task: str, img: str, *args: Any, **kwargs: Any) -> Any: + """ + Execute the task assigned to the agent. -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() + Args: + task (str): The task description. + img (str): The image input for processing. + *args: Additional positional arguments. + **kwargs: Additional keyword arguments. -# Example usage -symbol = "TSLA" -last_n = 10 + Returns: + Any: The result of the task execution. + """ + # Your custom logic + ... +``` -news_data = get_company_news(symbol, last_n) +This design ensures a seamless extension of functionality while maintaining clear and maintainable code. -analysis_request = f""" -Analyze the following recent news articles for {symbol}: +--- -{news_data} +## Key Considerations -Provide insights on the overall sentiment of the news, potential impact on the stock price, and any notable trends or events mentioned. -""" +### 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. -analysis = agent.run(analysis_request) -print(analysis) -``` +### 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. -This example demonstrates an AI agent that can fetch recent news data from IEX Cloud and perform a sentiment analysis on the company news. +### 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. -### Finnhub +### 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. -Finally, let's create an agent that can work with Finnhub data to analyze earnings estimates and recommendations. +### 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. -```python -import os -from swarms import Agent -from swarms.models import OpenAIChat -from dotenv import load_dotenv -import finnhub +### 6. **Scalability Considerations** +Ensure your agent design can scale to accommodate increased complexity or a larger number of tasks without compromising performance. -load_dotenv() +--- -# Finnhub API setup -FINNHUB_API_KEY = os.getenv("FINNHUB_API_KEY") -finnhub_client = finnhub.Client(api_key=FINNHUB_API_KEY) +## Example Usage -# OpenAI API setup -OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") +Here is an example of how to use your custom agent effectively: -# Create an instance of the OpenAIChat class -model = OpenAIChat( - openai_api_key=OPENAI_API_KEY, - model_name="gpt-4", - temperature=0.1 -) +```python +# Example LLM callable +class MockLLM: + """ + A mock language model class for simulating LLM behavior. -# 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 + 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}'" + +# 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 ) -def get_earnings_estimates(symbol): - return finnhub_client.earnings_calendar(symbol=symbol, from_date="2023-01-01", to_date="2023-12-31") +# Run a task +result = agent.run(task="Analyze content", img="path/to/image.jpg") +print(result) +``` -def get_recommendations(symbol): - return finnhub_client.recommendation_trends(symbol) +This example showcases the practical application of the `MyNewAgent` class and highlights its extensibility. -# Example usage -symbol = "NVDA" -earnings_estimates = get_earnings_estimates(symbol) -recommendations = get_recommendations(symbol) +## Production-Grade Example with **Griptape Agent Integration Example** -analysis_request = f""" -Analyze the following earnings estimates and recommendations for {symbol}: +In this example, we will create a **Griptape** agent by inheriting from the Swarms `Agent` class and implementing the `run` method. -Earnings Estimates: -{earnings_estimates} +### **Griptape Integration Steps**: -Recommendations: -{recommendations} +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. -Provide insights on the company's expected financial performance, analyst sentiment, and any notable trends in the recommendations. -""" +## **Griptape Example Code**: -analysis = agent.run(analysis_request) -print(analysis) -``` +```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, +) -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 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, + ) -## Advanced Analysis Techniques + # 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) -To further enhance the capabilities of our AI agents, we can implement more advanced analysis techniques: -1. Multi-source analysis: Combine data from multiple providers to get a more comprehensive view of a stock or market. +# Example usage: +griptape_swarms_agent = GriptapeSwarmsAgent() +output = griptape_swarms_agent.run("https://griptape.ai, griptape.txt") +print(output) +``` -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. +--- -4. Portfolio optimization: Use AI agents to suggest optimal portfolio allocations based on risk tolerance and investment goals. +## Best Practices -5. Anomaly detection: Implement algorithms to detect unusual patterns or events in financial data. +1. **Test Extensively:** + Validate your agent with various task inputs to ensure it performs as expected under different conditions. -Here's an example of how we might implement a multi-source analysis: +2. **Follow the Single Responsibility Principle:** + Design each agent to focus on a specific task or role, ensuring clarity and modularity in implementation. -```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 +3. **Log Actions:** + Include detailed logging within the `run` method to capture key actions, inputs, and results for debugging and monitoring. -load_dotenv() +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. -# 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") +5. **Iterate and Refactor:** + Continuously improve your agents based on feedback, performance evaluations, and new requirements to maintain relevance and functionality. -# 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 -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 -) +## Conclusion -def get_stock_data_yf(symbol, start_date, end_date): - stock = yf.Ticker(symbol) - return stock.history(start=start_date, end=end_date) +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. -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']) -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() -# 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: swarms\agents\openai_assistant.md -analysis_request = f""" -Analyze the following data for {symbol} from {start_date} to {end_date}: +# OpenAI Assistant -Yahoo Finance Data: -{yf_data.tail().to_string()} +The OpenAI Assistant class provides a wrapper around OpenAI's Assistants API, integrating it with the swarms framework. -Polygon.io Data: -{polygon_data.tail().to_string()} +## Overview -Alpha Vantage Company Overview: -{av_overview} +The `OpenAIAssistant` class allows you to create and interact with OpenAI Assistants, providing a simple interface for: -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 -""" - -analysis = agent.run(analysis_request) -print(analysis) -``` - -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. - -Now, let's explore some additional advanced analysis techniques: +- 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 -### Time Series Forecasting +## Insstallation -We can implement a simple time series forecasting model using the Prophet library and integrate it with our AI agent: +```bash +pip install swarms +``` +## Basic Usage ```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() -OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") +from swarms import OpenAIAssistant -model = OpenAIChat( - openai_api_key=OPENAI_API_KEY, - model_name="gpt-4", - temperature=0.1 +#Create an assistant +assistant = OpenAIAssistant( + name="Math Tutor", + instructions="You are a helpful math tutor.", + model="gpt-4o", + tools=[{"type": "code_interpreter"}] ) -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 -) +#Run a Task +response = assistant.run("Solve the equation: 3x + 11 = 14") +print(response) -def get_stock_data(symbol, start_date, end_date): - stock = yf.Ticker(symbol) - data = stock.history(start=start_date, end=end_date) - return data +# Continue the conversation in the same thread +follow_up = assistant.run("Now explain how you solved it") +print(follow_up) +``` -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 +## Function Calling -# Example usage -symbol = "MSFT" -start_date = "2020-01-01" -end_date = "2023-12-31" +The assistant supports custom function integration: -stock_data = get_stock_data(symbol, start_date, end_date) -forecast = forecast_stock_price(stock_data) +```python -analysis_request = f""" -Analyze the following time series forecast for {symbol}: +def get_weather(location: str, unit: str = "celsius") -> str: + # Mock weather function + return f"The weather in {location} is 22 degrees {unit}" -Forecast Data: -{forecast.tail(30).to_string()} +# 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"] + } +) +``` -The forecast plot has been saved as 'forecast_plot.png'. +## API Reference -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 -""" +### Constructor -analysis = agent.run(analysis_request) -print(analysis) +```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, +) ``` -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. +### Methods -### Sentiment Analysis of Social Media +#### run(task: str) -> str +Sends a task to the assistant and returns its response. The conversation thread is maintained between calls. -We can use a pre-trained sentiment analysis model to analyze tweets about a company and integrate this with our AI agent: +#### add_function(func: Callable, description: str, parameters: Dict[str, Any]) -> None +Adds a callable function that the assistant can use during conversations. -```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 +#### add_message(content: str, file_ids: Optional[List[str]] = None) -> None +Adds a message to the current conversation thread. -load_dotenv() +## Error Handling -# 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") +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 -auth = tweepy.OAuthHandler(TWITTER_API_KEY, TWITTER_API_SECRET) -auth.set_access_token(TWITTER_ACCESS_TOKEN, TWITTER_ACCESS_TOKEN_SECRET) -api = tweepy.API(auth) +## Best Practices -# OpenAI setup -OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") +1. Thread Management + - Use the same assistant instance for related conversations + - Create new instances for unrelated tasks + - Monitor thread status during long-running operations -model = OpenAIChat( - openai_api_key=OPENAI_API_KEY, - model_name="gpt-4", - temperature=0.1 -) +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 -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 -) +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 -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] +## References -def analyze_sentiment(tweets): - sentiments = [TextBlob(tweet).sentiment.polarity for tweet in tweets] - return pd.DataFrame({'tweet': tweets, 'sentiment': sentiments}) +- [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) -# Example usage -symbol = "TSLA" -query = f"${symbol} stock" -tweets = get_tweets(query) -sentiment_data = analyze_sentiment(tweets) -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()} +-------------------------------------------------- -Sample tweets and their sentiments: -{sentiment_data.head(10).to_string()} +# File: swarms\agents\reasoning_agent_router.md -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 -""" +# ReasoningAgentRouter -analysis = agent.run(analysis_request) -print(analysis) +!!! 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. + +## Architecture + +```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 ``` -This example shows how to perform sentiment analysis on tweets about a stock and integrate the results with our AI agent for further analysis. +## Configuration -### Portfolio Optimization +### Arguments -We can use the PyPortfolioOpt library to perform portfolio optimization and have our AI agent provide insights: +!!! info "Constructor Parameters" -```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 + | 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 | -load_dotenv() +### Available Agent Types -OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") +!!! note "Supported Types" + The following agent types are supported through the `swarm_type` parameter: -model = OpenAIChat( - openai_api_key=OPENAI_API_KEY, - model_name="gpt-4", - temperature=0.1 -) + - `"reasoning-duo"` or `"reasoning-agent"` + - `"self-consistency"` or `"consistency-agent"` + - `"ire"` or `"ire-agent"` + - `"ReflexionAgent"` + - `"GKPAgent"` + - `"AgentJudge"` -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 -) +### Agent Types Comparison -def get_stock_data(symbols, start_date, end_date): - data = yf.download(symbols, start=start_date, end=end_date)['Adj Close'] - return data +=== "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) -def optimize_portfolio(data): - mu = expected_returns.mean_historical_return(data) - S = risk_models.sample_cov(data) +=== "Self Consistency" + **Key Features** - ef = EfficientFrontier(mu, S) - weights = ef.max_sharpe() - cleaned_weights = ef.clean_weights() + - Multiple solution generation + - Consensus building + - Solution verification + - Concurrent execution + - AI-powered aggregation - return cleaned_weights + **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 -# Example usage -symbols = ["AAPL", "GOOGL", "MSFT", "AMZN", "FB"] -start_date = "2018-01-01" -end_date = "2023-12-31" +=== "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 -stock_data = get_stock_data(symbols, start_date, end_date) -optimized_weights = optimize_portfolio(stock_data) +=== "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 -analysis_request = f""" -Analyze the following optimized portfolio allocation: +=== "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 -{pd.Series(optimized_weights).to_string()} +=== "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 -The optimization aimed to maximize the Sharpe ratio based on historical data from {start_date} to {end_date}. +## Usage -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 -""" +### Methods -analysis = agent.run(analysis_request) -print(analysis) -``` +!!! 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 | -This example demonstrates how to perform portfolio optimization using the PyPortfolioOpt library and have our AI agent provide insights on the optimized allocation. +### Image Support -## Best Practices and Considerations +!!! info "Multi-modal Capabilities" + The ReasoningAgentRouter supports image inputs for compatible agent types: -When using AI agents for financial data analysis, consider the following best practices: + **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 -1. Data quality: Ensure that the data you're feeding into the agents is accurate and up-to-date. + **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 -2. Model limitations: Be aware of the limitations of both the financial models and the AI models being used. - -3. Regulatory compliance: Ensure that your use of AI in financial analysis complies with relevant regulations. + **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" + ) -4. Ethical considerations: Be mindful of potential biases in AI models and strive for fair and ethical analysis. + # Batch processing with images + results = router.batched_run( + tasks=["Analyze this chart", "Describe this photo"], + imgs=["chart.png", "photo.jpg"] + ) + ``` -5. Continuous monitoring: Regularly evaluate the performance of your AI agents and update them as needed. +### Code Examples -6. Human oversight: While AI agents can provide valuable insights, human judgment should always play a role in financial decision-making. +=== "Basic Usage" + ```python + from swarms.agents.reasoning_agents import ReasoningAgentRouter -7. Privacy and security: Implement robust security measures to protect sensitive financial data. + # 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 + ) -## Conclusion + # 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" + ) + ``` -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. +=== "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." + ) + ``` -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. +=== "ReflexionAgent" + ```python + router = ReasoningAgentRouter( + swarm_type="ReflexionAgent", + max_loops=3, + model_name="gpt-4o-mini" + ) + ``` -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. +=== "GKPAgent" + ```python + router = ReasoningAgentRouter( + swarm_type="GKPAgent", + model_name="gpt-4o-mini", + num_knowledge_items=6 + ) + ``` --------------------------------------------------- +=== "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" + ) + ``` -# File: guides\healthcare_blog.md +=== "AgentJudge" + ```python + router = ReasoningAgentRouter( + swarm_type="AgentJudge", + model_name="gpt-4o-mini", + max_loops=2 + ) + ``` -# Unlocking Efficiency and Cost Savings in Healthcare: How Swarms of LLM Agents Can Revolutionize Medical Operations and Save Millions +## Best Practices -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. +!!! 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 -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. + 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 -### 1. Administrative Automation + 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 -#### Use Case: Billing and Claims Processing + 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 -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. +## Limitations -**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. +!!! warning "Known Limitations" + 1. Processing time increases with: + - Higher num_samples + + - Larger max_loops + + - More complex tasks -**Estimated Savings:** + 2. Model-specific limitations based on: + - Token limits + + - Model capabilities + + - API rate limits -- Average cost per manual claim: $25 +## Contributing -- Average claims per hospital: 10,000 per month +!!! note "Development Guidelines" + When extending the ReasoningAgentRouter: + + 1. Follow the existing swarm interface + 2. Add comprehensive tests + 3. Update documentation + 4. Maintain error handling -- Swarms of LLM agents can reduce processing time by 90% and errors by 95% -- Estimated annual savings per hospital: +-------------------------------------------------- - - Savings per claim: $22.5 (90% reduction) +# File: swarms\agents\reasoning_agents_overview.md - - Total annual savings: 10,000 claims/month × 12 months × $22.5 = **$2.7 million** +# Reasoning Agents Overview -#### 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]; -``` +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. -### 2. Enhancing Clinical Decision Support +These agents are inspired by cognitive science and human reasoning processes, incorporating techniques such as: -#### Use Case: Diagnostic Assistance +- **Multi-step reasoning**: Breaking down complex problems into manageable components -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. +- **Self-reflection**: Evaluating and critiquing their own outputs -**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. +- **Iterative refinement**: Progressively improving solutions through multiple iterations -**Estimated Savings:** +- **Collaborative thinking**: Using multiple reasoning pathways or agent perspectives -- Time saved per diagnosis: 2 hours per patient +- **Memory integration**: Learning from past experiences and building knowledge over time -- Average patient cases per hospital: 5,000 per year +- **Meta-cognitive awareness**: Understanding their own thinking processes and limitations -- Time saved annually: 2 × 5,000 = 10,000 hours -- Doctor's hourly rate: $150 -- Total annual savings: 10,000 × $150 = **$1.5 million** +## Available Reasoning Agents -#### 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]; -``` +| 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) | -### 3. Streamlining Patient Communication +## Agent Architectures -#### Use Case: Patient Follow-ups and Reminders +### Self-Consistency Agent -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. +**Description**: Implements multiple independent reasoning paths with consensus-building to improve response reliability and accuracy through majority voting mechanisms. -**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. +**Key Features**: -**Estimated Savings:** +- Concurrent execution of multiple reasoning instances -- Average cost per patient follow-up: $5 +- AI-powered aggregation and consensus analysis -- Number of follow-ups: 20,000 annually per hospital +- Validation mode for answer verification -- Swarm efficiency: 90% reduction in manual effort +- Configurable sample sizes and output formats -- Total annual savings: 20,000 × $4.5 = **$90,000** +**Architecture Diagram**: -#### 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]; +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 ``` -### 4. Optimizing Inventory Management +**Use Cases**: Mathematical problem solving, high-stakes decision making, answer validation, quality assurance processes -#### Use Case: Pharmaceutical Stock Management +**Implementation**: `SelfConsistencyAgent` -Hospitals often struggle with managing pharmaceutical inventory efficiently. Overstocking leads to wasted resources, while understocking can be a critical problem for patient care. +**Documentation**: [Self-Consistency Agent Guide](consistency_agent.md) -**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. +--- -**Estimated Savings:** +### Reasoning Duo -- Annual waste due to overstocking: $500,000 per hospital +**Description**: Dual-agent collaborative system that separates reasoning and execution phases, enabling specialized analysis and task completion through coordinated agent interaction. -- Swarm efficiency: 80% reduction in overstocking +**Key Features**: -- Total annual savings: $500,000 × 0.8 = **$400,000** +- Separate reasoning and execution agents +- Collaborative problem decomposition + +- Cross-validation between agents + +- Configurable model selection for each agent + + +**Architecture Diagram**: -#### 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]; +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 ``` -### 5. Improving Clinical Research +**Use Cases**: Complex analysis tasks, multi-step problem solving, research and planning, verification workflows -#### Use Case: Literature Review and Data Analysis +**Implementation**: `ReasoningDuo` -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. +**Documentation**: [Reasoning Duo Guide](reasoning_duo.md) -**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:** +### IRE Agent (Iterative Reflective Expansion) -- Average time spent on literature review per paper: 5 hours +**Description**: Sophisticated reasoning framework employing iterative hypothesis generation, simulation, and refinement through continuous cycles of testing and meta-cognitive reflection. -- Number of papers reviewed annually: 1,000 +**Key Features**: -- Time saved: 80% reduction in review time +- Hypothesis generation and testing -- Total time saved: 1,000 × 5 × 0.8 = 4,000 hours +- Path simulation and evaluation -- Researcher's hourly rate: $100 +- Meta-cognitive reflection capabilities -- Total annual savings: 4,000 × $100 = **$400,000** +- Dynamic strategy revision based on feedback -#### Clinical Research Swarm +**Architecture Diagram**: + ```mermaid -graph TD; - A[Research Papers] --> B[Data Extraction Agent]; - B --> C[Cross-reference Agent]; - C --> D[Simulation Agent]; - D --> E[Researcher]; +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 ``` -### 6. Automating Medical Record Keeping +**Use Cases**: Complex reasoning tasks, research problems, strategy development, iterative learning scenarios -#### Use Case: EHR Management and Documentation +**Implementation**: `IterativeReflectiveExpansion` -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. +**Documentation**: [IRE Agent Guide](iterative_agent.md) -**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. +--- -**Estimated Savings:** +### Reflexion Agent -- Average time spent on EHR per patient: 20 minutes +**Description**: Advanced self-reflective system implementing actor-evaluator-reflector architecture for continuous improvement through experience-based learning and memory integration. -- Number of patients annually: 30,000 +**Key Features**: -- Time saved: 80% reduction in manual effort +- Actor-evaluator-reflector sub-agent architecture -- Total time saved: 30,000 × 20 minutes × 0.8 = 480,000 minutes or 8,000 hours +- Self-evaluation and quality assessment -- Provider's hourly rate: $150 +- Experience memory and learning capabilities -- Total annual savings: 8,000 × $150 = **$1.2 million** +- Adaptive improvement through reflection -#### EHR Management Swarm +**Architecture Diagram**: + ```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]; +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 ``` -### 7. Reducing Diagnostic Errors +**Use Cases**: Continuous improvement tasks, long-term projects, adaptive learning, quality refinement processes -#### Use Case: Medical Imaging Analysis +**Implementation**: `ReflexionAgent` -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. +**Documentation**: [Reflexion Agent Guide](reflexion_agent.md) -**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. +--- -**Estimated Savings:** +### GKP Agent (Generated Knowledge Prompting) -- Time saved per scan: 30 minutes +**Description**: Knowledge-driven reasoning system that generates relevant information before answering queries, implementing multi-perspective analysis through coordinated knowledge synthesis. -- Number of scans annually: 10,000 +**Key Features**: -- Time saved: 10,000 × 30 minutes = 5,000 hours +- Dynamic knowledge generation -- Radiologist's hourly rate: $200 +- Multi-perspective reasoning coordination -- Total annual savings: 5,000 × $ +- Information synthesis and integration + +- Configurable knowledge item generation -200 = **$1 million** +**Architecture Diagram**: -#### 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]; +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 ``` -### Conclusion: The Financial and Time-Saving Impact of LLM Swarms in Healthcare +**Use Cases**: Knowledge-intensive tasks, research questions, fact-based reasoning, information synthesis +**Implementation**: `GKPAgent` -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. +**Documentation**: [GKP Agent Guide](gkp_agent.md) -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. +--- -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. +### Agent Judge -The future of healthcare is agentic, and by embracing swarms of LLM agents, your organization can unlock unprecedented levels of productivity and savings. +**Description**: Specialized evaluation system for assessing agent outputs and system performance, providing structured feedback and quality metrics through comprehensive assessment frameworks. -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. +**Key Features**: -The table below summarizes the estimated savings for each use case: +- Structured evaluation methodology -| 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** | +- Quality assessment and scoring -### References -- [Swarms GitHub](https://github.com/kyegomez/swarms) +- Performance metrics generation -- [Swarms Website](https://swarms.xyz) +- Configurable evaluation criteria -- [book a call](https://cal.com/swarms) -- Swarms Discord: https://discord.gg/jM3Z6M9uMq +**Architecture Diagram**: -- Swarms Twitter: https://x.com/swarms_corp +```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 +``` -- Swarms Spotify: https://open.spotify.com/show/2HLiswhmUaMdjHC8AUHcCF?si=c831ef10c5ef4994 +**Use Cases**: Quality control, output evaluation, performance assessment, model comparison -Swarms Blog: https://medium.com/@kyeg -Swarms Website: https://swarms.xyz +**Implementation**: `AgentJudge` -By adopting swarms of LLM agents, healthcare organizations can streamline operations, reduce inefficiencies, and focus on what truly matters—delivering top-notch patient care. +**Documentation**: [Agent Judge Guide](agent_judge.md) +--- +### REACT Agent (Reason-Act-Observe) --------------------------------------------------- +**Description**: Action-oriented reasoning system implementing iterative reason-act-observe cycles with memory integration for interactive task completion and environmental adaptation. -# File: guides\pricing.md +**Key Features**: -# Comparing LLM Provider Pricing: A Guide for Enterprises +- Reason-Act-Observe cycle implementation -Large language models (LLMs) have become a cornerstone of innovation for enterprises across various industries. +- Memory integration and experience building -As executives contemplate which model to integrate into their operations, understanding the intricacies of LLM provider pricing is crucial. +- Action planning and execution -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. +- Environmental state observation -## Table of Contents -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) +**Architecture Diagram**: -## 1. Introduction to LLM Pricing Models +```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 +``` -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. +**Use Cases**: Interactive tasks, tool usage scenarios, planning problems, learning environments -### Pay-per-Token Model +**Implementation**: `ReactAgent` -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. +**Documentation**: [REACT Agent Guide](react_agent.md) -**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. -**Disadvantages:** -- Unpredictability: Costs can vary significantly based on the verbosity of inputs and outputs. -- Potential for overruns: Without proper monitoring, costs can quickly escalate. +## Implementation Guide -### Subscription-Based Models +### Unified Interface via Reasoning Agent Router -Some providers offer subscription tiers that provide a set amount of compute resources or tokens for a fixed monthly or annual fee. +The `ReasoningAgentRouter` provides a centralized interface for accessing all reasoning agent implementations: -**Advantages:** -- Predictable costs: Easier budgeting and financial planning. -- Potential cost savings: Can be more economical for consistent, high-volume usage. +```python +from swarms.agents import ReasoningAgentRouter -**Disadvantages:** -- Less flexibility: May lead to underutilization or overages. -- Commitment required: Often involves longer-term contracts. +# 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 +) -### Custom Enterprise Agreements +# Execute reasoning process +result = router.run("Analyze the optimal solution for this complex business problem") +print(result) +``` -For large-scale deployments, providers may offer custom pricing agreements tailored to the specific needs of an enterprise. +### Direct Agent Implementation -**Advantages:** -- Optimized for specific use cases: Can include specialized support, SLAs, and pricing structures. -- Potential for significant cost savings at scale. +```python +from swarms.agents import SelfConsistencyAgent, ReasoningDuo, ReflexionAgent -**Disadvantages:** -- Complexity: Negotiating and managing these agreements can be resource-intensive. -- Less standardization: Difficult to compare across providers. +# Self-Consistency Agent for high-accuracy requirements +consistency_agent = SelfConsistencyAgent( + model_name="gpt-4o-mini", + num_samples=5 +) -### Hybrid Models +# Reasoning Duo for collaborative analysis workflows +duo_agent = ReasoningDuo( + model_names=["gpt-4o-mini", "gpt-4o"] +) -Some providers are beginning to offer hybrid models that combine elements of pay-per-token and subscription-based pricing. +# Reflexion Agent for adaptive learning scenarios +reflexion_agent = ReflexionAgent( + model_name="gpt-4o-mini", + max_loops=3, + memory_capacity=100 +) +``` -**Advantages:** -- Flexibility: Can adapt to varying usage patterns. -- Risk mitigation: Balances the benefits of both main pricing models. +## Choosing the Right Reasoning Agent -**Disadvantages:** -- Complexity: Can be more challenging to understand and manage. -- Potential for suboptimal pricing if not carefully structured. +| 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 | -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. Understanding Unit Economics in LLM Deployment +## Technical Documentation -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. +For comprehensive technical documentation on each reasoning agent implementation: -### Defining the Unit +- [Self-Consistency Agent](consistency_agent.md) -In the context of LLMs, a "unit" can be defined in several ways: +- [Reasoning Duo](reasoning_duo.md) -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. +- [IRE Agent](iterative_agent.md) -Understanding which unit is most relevant to your use case is crucial for accurate economic analysis. +- [Reflexion Agent](reflexion_agent.md) -### Components of Unit Cost +- [GKP Agent](gkp_agent.md) -1. **Direct LLM Costs** - - Token processing fees - - API call charges - - Data transfer costs +- [Agent Judge](agent_judge.md) -2. **Indirect Costs** - - Compute resources for pre/post-processing - - Storage for inputs, outputs, and fine-tuning data - - Networking costs +- [Reasoning Agent Router](reasoning_agent_router.md) -3. **Operational Costs** - - Monitoring and management tools - - Integration and maintenance engineering time - - Customer support related to AI functions -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: +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. -1. **Determine Total Costs**: Sum all direct, indirect, operational, and overhead costs over a fixed period (e.g., monthly). +-------------------------------------------------- -2. **Measure Total Units**: Track the total number of relevant units processed in the same period. +# File: swarms\agents\reasoning_duo.md -3. **Calculate Cost per Unit**: Divide total costs by total units. +# ReasoningDuo - ``` - Cost per Unit = Total Costs / Total Units - ``` +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. -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. +## Class Overview - ``` - Profit per Unit = Revenue per Unit - Cost per Unit - ``` +### Constructor Parameters -### Example Calculation +| 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 | -Let's consider a hypothetical customer service AI chatbot: +### Methods -- Monthly LLM API costs: $10,000 -- Indirect and operational costs: $5,000 -- Total monthly interactions: 100,000 +| 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 | -``` -Cost per Interaction = ($10,000 + $5,000) / 100,000 = $0.15 -``` -If each interaction generates an average of $0.50 in value (through cost savings or revenue): -``` -Profit per Interaction = $0.50 - $0.15 = $0.35 -``` +## Quick Start -### Economies of Scale +```python +from swarms.agents.reasoning_duo import ReasoningDuo -As usage increases, unit economics often improve due to: +# Initialize the ReasoningDuo +duo = ReasoningDuo( + model_name="reasoning-agent-01", + model_names=["gpt-4o-mini", "gpt-4o"] +) -- Volume discounts from LLM providers -- Amortization of fixed costs over more units -- Efficiency gains through learning and optimization +# Run a single task +result = duo.run("Explain the concept of gravitational waves") -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. +# Run multiple tasks +tasks = [ + "Calculate compound interest for $1000 over 5 years", + "Explain quantum entanglement" +] +results = duo.batched_run(tasks) +``` -### Diseconomies of Scale +## Examples -Conversely, be aware of potential diseconomies of scale: +### 1. Mathematical Analysis -- Increased complexity in managing large-scale deployments -- Higher costs for specialized talent as operations grow -- Potential for diminishing returns on very large language models +```python +duo = ReasoningDuo() -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. +# Complex mathematical problem +math_task = """ +Solve the following differential equation: +dy/dx + 2y = x^2, y(0) = 1 +""" -## 3. Profit Margins and Cost Structures +solution = duo.run(math_task) +``` -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. +### 2. Physics Problem -### Components of Profit Margin +```python +# Quantum mechanics problem +physics_task = """ +Calculate the wavelength of an electron with kinetic energy of 50 eV +using the de Broglie relationship. +""" -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 - ``` +result = duo.run(physics_task) +``` -2. **Contribution Margin**: Gross margin minus variable operational costs. - ``` - Contribution Margin = Gross Margin - Variable Operational Costs - ``` +### 3. Financial Analysis -3. **Net Margin**: The final profit after all costs, including fixed overheads. - ``` - Net Margin = Contribution Margin - Fixed Costs - Net Margin % = (Net Margin / Revenue) * 100 - ``` +```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% +""" -### Cost Structures in LLM Deployment +analysis = duo.run(finance_task) +``` -1. **Fixed Costs** - - Subscription fees for LLM access (if using a subscription model) - - Base infrastructure costs - - Core team salaries - - Licensing fees for essential software +## Advanced Usage -2. **Variable Costs** - - Per-token or per-request charges - - Scaling infrastructure costs - - Usage-based API fees - - Performance-based team bonuses +### Customizing Agent Behavior -3. **Step Costs** - - Costs that increase in chunks as usage scales - - Examples: Adding new server clusters, hiring additional support staff +You can customize both agents by modifying their initialization parameters: -### Analyzing Profit Margins Across Different Pricing Models +```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..." +) +``` -Let's compare how different LLM pricing models might affect profit margins for a hypothetical AI-powered writing assistant service: +### Batch Processing with Progress Tracking -**Scenario**: The service charges users $20/month and expects to process an average of 100,000 tokens per user per month. +```python +tasks = [ + "Analyze market trends for tech stocks", + "Calculate risk metrics for a portfolio", + "Forecast revenue growth" +] -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%) +# Process multiple tasks with logging +results = duo.batched_run(tasks) +``` -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%) +## Implementation Details -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%) +The ReasoningDuo uses a two-stage process: -### Strategies for Improving Profit Margins +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 -1. **Optimize Token Usage** - - Implement efficient prompting techniques - - Cache common responses - - Use compression algorithms for inputs and outputs +### Internal Architecture -2. **Leverage Economies of Scale** - - Negotiate better rates at higher volumes - - Spread fixed costs across a larger user base +``` +Task Input → Reasoning Agent → Structured Analysis → Main Agent → Final Output +``` -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) +## Best Practices -4. **Vertical Integration** - - Invest in proprietary LLM development for core functionalities - - Reduce dependency on third-party providers for critical operations +1. **Task Formulation** + - Be specific and clear in task descriptions + - Include relevant context and constraints + - Break complex problems into smaller subtasks -5. **Smart Caching and Pre-computation** - - Store and reuse common LLM outputs - - Perform batch processing during off-peak hours +2. **Performance Optimization** + - Use batched_run for multiple related tasks + - Monitor agent outputs for consistency + - Adjust model parameters based on task complexity -6. **Hybrid Cloud Strategies** - - Use on-premises solutions for consistent workloads - - Leverage cloud elasticity for demand spikes +## Error Handling -### Case Study: Margin Improvement +The ReasoningDuo includes built-in logging using the `loguru` library: -Consider a company that initially used a pay-per-token model: +```python +from loguru import logger -**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%) +# Logs are automatically generated for each task +logger.info("Task processing started") +``` -**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 +## Limitations -**Result:** -- New LLM cost per user: $4.32 -- New net margin per user: $12.68 (50.7%) +- Processing time may vary based on task complexity +- Model response quality depends on input clarity +- Resource usage scales with batch size -This case study demonstrates how a holistic approach to margin improvement, addressing both revenue and various cost components, can significantly enhance profitability. +## Example Script -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. +For a runnable demonstration, see the [reasoning_duo_batched.py](https://github.com/kyegomez/swarms/blob/master/examples/models/reasoning_duo_batched.py) example. -## 4. LLM Pricing in Action: Case Studies -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. +-------------------------------------------------- -### Case Study 1: E-commerce Product Description Generator +# File: swarms\agents\reflexion_agent.md -**Company**: GlobalMart, a large online retailer -**Use Case**: Automated generation of product descriptions -**LLM Provider**: GPT-4o +# ReflexionAgent -**Pricing Model**: Pay-per-token -- Input: $5.00 per 1M tokens -- Output: $15.00 per 1M tokens +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. -**Usage Pattern**: -- Average input: 50 tokens per product (product attributes) -- Average output: 200 tokens per product (generated description) -- Daily products processed: 10,000 +## Overview -**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 +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 -**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) +## Initialization -**ROI Analysis**: -- Daily investment: $32.50 -- Daily return: $500 -- ROI = (Return - Investment) / Investment * 100 = 1,438% +```python +from swarms.agents import ReflexionAgent -**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 = ReflexionAgent( + agent_name="reflexion-agent", + system_prompt="...", # Optional custom system prompt + model_name="openai/o1", + max_loops=3, + memory_capacity=100 +) +``` -### Case Study 2: Customer Service Chatbot +### Parameters -**Company**: TechSupport Inc., a software company -**Use Case**: 24/7 customer support chatbot -**LLM Provider**: Claude 3.5 Sonnet +| 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 | -**Pricing Model**: Input: $3 per 1M tokens, Output: $15 per 1M tokens +## Methods -**Usage Pattern**: -- Average conversation: 500 tokens input (customer queries + context), 1000 tokens output (bot responses) -- Daily conversations: 5,000 +### act -**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 +Generates a response to the given task using the actor agent. -**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) +```python +response = agent.act(task: str, relevant_memories: List[Dict[str, Any]] = None) -> str +``` -**ROI Analysis**: -- Daily investment: $82.50 -- Daily return: $2,000 -- ROI = (Return - Investment) / Investment * 100 = 2,324% - -**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 +| Parameter | Type | Description | +|-----------|------|-------------| +| `task` | `str` | The task to respond to | +| `relevant_memories` | `List[Dict[str, Any]]` | Optional relevant past memories to consider | -**Company**: FinAnalyze, a financial services firm -**Use Case**: Automated summarization of lengthy financial reports -**LLM Provider**: GPT-3.5 Turbo +### evaluate -**Pricing Model**: Input: $0.50 per 1M tokens, Output: $1.50 per 1M tokens +Evaluates the quality of a response to a task. -**Usage Pattern**: -- Average report: 20,000 tokens input, 2,000 tokens output -- Daily reports processed: 100 +```python +evaluation, score = agent.evaluate(task: str, response: str) -> Tuple[str, float] +``` -**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 +| Parameter | Type | Description | +|-----------|------|-------------| +| `task` | `str` | The original task | +| `response` | `str` | The response to evaluate | -**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) +Returns: +- `evaluation`: Detailed feedback on the response +- `score`: Numerical score between 0 and 1 -**ROI Analysis**: -- Daily investment: $130 -- Daily return: $1,000 -- ROI = (Return - Investment) / Investment * 100 = 669% +### reflect -**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. +Generates a self-reflection based on the task, response, and evaluation. -### Case Study 4: AI-Powered Language Learning App +```python +reflection = agent.reflect(task: str, response: str, evaluation: str) -> str +``` -**Company**: LinguaLeap, an edtech startup -**Use Case**: Personalized language exercises and conversations -**LLM Provider**: Claude 3 Haiku +| Parameter | Type | Description | +|-----------|------|-------------| +| `task` | `str` | The original task | +| `response` | `str` | The generated response | +| `evaluation` | `str` | The evaluation feedback | -**Pricing Model**: Input: $0.25 per 1M tokens, Output: $1.25 per 1M tokens +### refine -**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 +Refines the original response based on evaluation and reflection. -**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 +```python +refined_response = agent.refine( + task: str, + original_response: str, + evaluation: str, + reflection: str +) -> str +``` -**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) +| Parameter | Type | Description | +|-----------|------|-------------| +| `task` | `str` | The original task | +| `original_response` | `str` | The original response | +| `evaluation` | `str` | The evaluation feedback | +| `reflection` | `str` | The self-reflection | -**ROI Analysis**: -- Daily investment: $105 -- Daily revenue: $5,000 -- ROI = (Revenue - Investment) / Investment * 100 = 4,662% +### step -**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. +Processes a single task through one iteration of the Reflexion process. -### Case Study 5: Legal Document Analysis +```python +result = agent.step( + task: str, + iteration: int = 0, + previous_response: str = None +) -> Dict[str, Any] +``` -**Company**: LegalEagle LLP, a large law firm -**Use Case**: Contract review and risk assessment -**LLM Provider**: Claude 3 Opus +| Parameter | Type | Description | +|-----------|------|-------------| +| `task` | `str` | The task to process | +| `iteration` | `int` | Current iteration number | +| `previous_response` | `str` | Response from previous iteration | -**Pricing Model**: Input: $15 per 1M tokens, Output: $75 per 1M tokens +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 -**Usage Pattern**: -- Average contract: 10,000 tokens input, 3,000 tokens output (analysis and risk assessment) -- Daily contracts processed: 50 +### run -**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 +Executes the Reflexion process for a list of tasks. -**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) +```python +results = agent.run( + tasks: List[str], + include_intermediates: bool = False +) -> List[Any] +``` -**ROI Analysis**: -- Daily investment: $18.75 -- Daily value: $10,000 -- ROI = (Value - Investment) / Investment * 100 = 53,233% +| Parameter | Type | Description | +|-----------|------|-------------| +| `tasks` | `List[str]` | List of tasks to process | +| `include_intermediates` | `bool` | Whether to include intermediate iterations in results | -**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. +Returns: +- If `include_intermediates=False`: List of final responses +- If `include_intermediates=True`: List of complete iteration histories -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. +## Example Usage -## 5. Calculating ROI for LLM Integration +```python +from swarms.agents import ReflexionAgent -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. +# Initialize the Reflexion Agent +agent = ReflexionAgent( + agent_name="reflexion-agent", + model_name="openai/o1", + max_loops=3 +) -### The ROI Formula +# Example tasks +tasks = [ + "Explain quantum computing to a beginner.", + "Write a Python function to sort a list of dictionaries by a specific key." +] -The basic ROI formula is: +# Run the agent +results = agent.run(tasks) -``` -ROI = (Net Benefit / Cost of Investment) * 100 +# Print results +for i, result in enumerate(results): + print(f"\nTask {i+1}: {tasks[i]}") + print(f"Response: {result}") ``` -For LLM integration, we can expand this to: +## Memory System -``` -ROI = ((Total Benefits - Total Costs) / Total Costs) * 100 -``` +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. -### Identifying Benefits +### 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 -1. **Direct Cost Savings** - - Reduced labor costs - - Decreased operational expenses - - Lower error-related costs +## Best Practices -2. **Revenue Increases** - - New product offerings enabled by LLM - - Improved customer acquisition and retention - - Upselling and cross-selling opportunities +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 -3. **Productivity Gains** - - Time saved on repetitive tasks - - Faster decision-making processes - - Improved employee efficiency -4. **Quality Improvements** - - Enhanced accuracy in outputs - - Consistency in service delivery - - Reduced error rates +-------------------------------------------------- -5. **Strategic Advantages** - - Market differentiation - - Faster time-to-market for new offerings - - Improved competitive positioning +# File: swarms\agents\structured_outputs.md -### Calculating Costs +# :material-code-json: Agentic Structured Outputs -1. **Direct LLM Costs** - - API usage fees - - Subscription costs +!!! 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. -2. **Infrastructure Costs** - - Cloud computing resources - - Data storage - - Networking expenses +## :material-file-document-outline: Schema Definition -3. **Integration and Development Costs** - - Initial setup and integration - - Ongoing maintenance and updates - - Custom feature development +Structured outputs are defined using JSON Schema format. Here's the basic structure: -4. **Training and Support** - - Employee training programs - - User support and documentation - - Change management initiatives +=== "Basic Schema" -5. **Compliance and Security** - - Data privacy measures - - Security audits and implementations - - Regulatory compliance efforts + ```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 + ] + } + } + } + ] + ``` -### Step-by-Step ROI Calculation +=== "Advanced Schema" -1. **Define the Time Period**: Determine the timeframe for your ROI calculation (e.g., 1 year, 3 years). + ```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"] + } + } + } + ] + ``` -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) +### :material-format-list-bulleted-type: Parameter Types -3. **Calculate Total Costs**: - - Sum up all direct and indirect costs related to LLM integration +The following parameter types are supported: -4. **Apply the ROI Formula**: - ``` - ROI = ((Total Benefits - Total Costs) / Total Costs) * 100 - ``` +| 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` | -5. **Consider Time Value of Money**: For longer-term projections, use Net Present Value (NPV) to account for the time value of money. +## :material-cog: Implementation Steps -### Example ROI Calculation +!!! tip "Quick Start Guide" + Follow these steps to implement structured outputs in your agent: -Let's consider a hypothetical customer service chatbot implementation: +### Step 1: Define Your Schema -**Time Period**: 1 year +```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"] + } + } + } +] +``` -**Benefits**: -- Labor cost savings: $500,000 -- Increased sales from improved customer satisfaction: $300,000 -- Productivity gains from faster query resolution: $200,000 +### Step 2: Initialize the Agent -Total Benefits: $1,000,000 +``` +from swarms import Agent -**Costs**: -- LLM API fees: $100,000 -- Integration and development: $150,000 -- Training and support: $50,000 -- Infrastructure: $50,000 +agent = Agent( + agent_name="Your-Agent-Name", + agent_description="Agent description", + system_prompt="Your system prompt", + tools_list_dictionary=tools +) +``` -Total Costs: $350,000 +### Step 3: Run the Agent -**ROI Calculation**: -``` -ROI = (($1,000,000 - $350,000) / $350,000) * 100 = 185.7% +```python +response = agent.run("Your query here") ``` -This indicates a strong positive return on investment, with benefits outweighing costs by a significant margin. +### Step 4: Parse the Output -### Considerations for Accurate ROI Calculation +```python +from swarms.utils.str_to_dict import str_to_dict -1. **Be Conservative in Estimates**: It's better to underestimate benefits and overestimate costs to provide a more realistic view. +parsed_output = str_to_dict(response) +``` -2. **Account for Ramp-Up Time**: Full benefits may not be realized immediately. Consider a phased approach in your calculations. +## :material-code-braces: Example Usage -3. **Include Opportunity Costs**: Consider the potential returns if the investment were made elsewhere. +!!! example "Complete Financial Agent Example" + Here's a comprehensive example using a financial analysis agent: -4. **Factor in Risk**: Adjust your ROI based on the likelihood of achieving projected benefits. +=== "Python Implementation" -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. + ```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}") + ``` -6. **Perform Sensitivity Analysis**: Calculate ROI under different scenarios (best case, worst case, most likely) to understand the range of possible outcomes. +=== "Expected Output" -7. **Benchmark Against Alternatives**: Compare the ROI of LLM integration against other potential investments or solutions. + ```json + { + "function_calls": [ + { + "name": "get_stock_price", + "arguments": { + "ticker": "AAPL", + "include_history": true, + "time": "2024-01-15T10:30:00Z" + } + } + ] + } + ``` -### Long-Term ROI Considerations +## :material-check-circle: Best Practices -While initial ROI calculations are crucial for decision-making, it's important to consider long-term implications: +!!! 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 -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? +!!! 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 -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 "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 -## 6. Comparative Analysis of Major LLM Providers +## :material-alert-circle: Troubleshooting -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. +!!! warning "Common Issues" -### OpenAI +### Invalid Output Format -**Models**: GPT-4o, GPT-3.5 Turbo +!!! failure "Problem" + The agent returns data in an unexpected format -**Pricing Structure**: -- Pay-per-token model -- Different rates for input and output tokens -- Bulk discounts available for high-volume users - -**Key Features**: -- State-of-the-art performance on a wide range of tasks -- Regular model updates and improvements -- Extensive documentation and community support +!!! 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 -**Considerations**: -- Higher pricing compared to some competitors -- Potential for rapid price changes as technology evolves -- Usage limits and approval process for higher-tier models +### Parsing Errors -### Anthropic +!!! failure "Problem" + Errors occur when trying to parse the agent's response -**Models**: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku +!!! 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 + ``` -**Pricing Structure**: -- Pay-per-token model -- Different rates for input and output tokens -- Tiered pricing based on model capabilities +### Missing Fields -**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) +!!! failure "Problem" + Required fields are missing from the output -**Considerations**: -- Newer to the market compared to OpenAI -- Potentially more limited third-party integrations -- Strong emphasis on responsible AI use +!!! 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 -### Google (Vertex AI) +## :material-lightbulb: Advanced Features -**Models**: PaLM 2 for Chat, PaLM 2 for Text +!!! 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" + } + } + ``` -**Pricing Structure**: -- Pay-per-thousand characters model -- Different rates for input and output -- Additional charges for advanced features (e.g., semantic retrieval) +--- -**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 -### Amazon (Bedrock) +-------------------------------------------------- -**Models**: Claude (Anthropic), Titan +# File: swarms\agents\third_party.md -**Pricing Structure**: -- Pay-per-second of compute time -- Additional charges for data transfer and storage +# Swarms Framework: Integrating and Customizing Agent Libraries -**Key Features**: -- Seamless integration with AWS services -- Access to multiple model providers through a single API -- Fine-tuning and customization options +Agent-based systems have emerged as a powerful paradigm for solving complex problems and automating tasks. -**Considerations**: -- Pricing model can be less predictable for inconsistent workloads -- Strong appeal for existing AWS customers -- Potential for cost optimizations through AWS ecosystem +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. -### Microsoft (Azure OpenAI Service) +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. -**Models**: GPT-4, GPT-3.5 Turbo +## Table of Contents -**Pricing Structure**: -- Similar to OpenAI's pricing, but with Azure integration -- Additional costs for Azure services (e.g., storage, networking) +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) -**Key Features**: -- Enterprise-grade security and compliance -- Integration with Azure AI services -- Access to fine-tuning and customization options +## 1. Introduction to the Swarms Framework -**Considerations**: -- Attractive for organizations already using Azure -- Potential for volume discounts through Microsoft Enterprise Agreements -- Additional overhead for Azure management +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. -### Comparative Analysis +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: -| 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 | +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. -### Factors to Consider in Provider Selection +## 2. The Need for Wrappers -1. **Performance Requirements**: Assess whether you need state-of-the-art performance or if a less advanced (and potentially cheaper) model suffices. +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. -2. **Pricing Predictability**: Consider whether your usage patterns align better with token-based or compute-time-based pricing. +This is where the concept of wrappers becomes crucial. By creating wrappers around different agent libraries, we can: -3. **Integration Needs**: Evaluate how well each provider integrates with your existing technology stack. +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. -4. **Scalability**: Assess each provider's ability to handle your expected growth in usage. +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. -5. **Customization Options**: Determine if you need fine-tuning or specialized model development capabilities. +## 3. Building Custom Agents with Swarms -6. **Compliance and Security**: Consider your industry-specific regulatory requirements and each provider's security offerings. +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: -7. **Support and Documentation**: Evaluate the quality of documentation, community support, and enterprise-level assistance. +```python +from swarms import Agent -8. **Ethical Considerations**: Assess each provider's stance on AI ethics and responsible use. +class MyCustomAgent(Agent): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + # Custom initialization logic -9. **Lock-In Concerns**: Consider the long-term implications of committing to a specific provider or cloud ecosystem. + def custom_method(self, *args, **kwargs): + # Implement custom logic here + pass -10. **Multi-Provider Strategy**: Evaluate the feasibility and benefits of using multiple providers for different use cases. + def run(self, task, *args, **kwargs): + # Customize the run method + response = super().run(task, *args, **kwargs) + # Additional custom logic + return response +``` -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. +This example demonstrates the fundamental structure of a custom agent class within the swarms framework. Let's break down the key components: -## 7. Hidden Costs and Considerations +1. **Inheritance**: The class inherits from the `Agent` parent class, ensuring it adheres to the swarms framework's interface. -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. +2. **Initialization**: The `__init__` method calls the parent class's initializer and can include additional custom initialization logic. -### 1. Data Preparation and Cleaning +3. **Custom methods**: You can add any number of custom methods to extend the agent's functionality. -**Considerations**: -- Cost of data collection and aggregation -- Expenses related to data cleaning and normalization -- Ongoing data maintenance and updates +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. -**Impact**: -- Can be time-consuming and labor-intensive -- May require specialized tools or personnel -- Critical for model performance and accuracy +To create more sophisticated custom agents, you can expand on this basic structure by adding features such as: -### 2. Fine-Tuning and Customization +- **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. -**Considerations**: -- Costs associated with creating custom datasets -- Compute resources required for fine-tuning -- Potential need for specialized ML expertise +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. -**Impact**: -- Can significantly improve model performance for specific tasks -- May lead to better ROI in the long run -- Increases initial implementation costs +## 4. Integrating Third-Party Agent Libraries -### 3. Integration and Development +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. -**Considerations**: -- Engineering time for API integration -- Development of custom interfaces or applications -- Ongoing maintenance and updates +### Griptape Integration -**Impact**: -- Can be substantial, especially for complex integrations -- May require hiring additional developers or consultants -- Critical for seamless user experience and workflow 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: -### 4. Monitoring and Optimization +```python +from typing import List, Optional -**Considerations**: -- Tools and systems for performance monitoring -- Regular audits and optimizations -- Costs associated with debugging and troubleshooting +from griptape.structures import Agent as GriptapeAgent +from griptape.tools import FileManager, TaskMemoryClient, WebScraper -**Impact**: -- Ongoing expense that increases with scale -- Essential for maintaining efficiency and cost-effectiveness -- Can lead to significant savings through optimized usage +from swarms import Agent -### 5. Compliance and Security -**Considerations**: -- Legal counsel for data privacy and AI regulations -- Implementation of security measures (e.g., encryption, access controls) -- Regular audits and certifications +class GriptapeAgentWrapper(Agent): + """ + A wrapper class for the GriptapeAgent from the griptape library. + """ -**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 + def __init__(self, name: str, tools: Optional[List] = None, *args, **kwargs): + """ + Initialize the GriptapeAgentWrapper. -### 6. Training and Change Management + 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 + ) -- Employee training programs -- Development of user guides and documentation -- Change management initiatives + def run(self, task: str, *args, **kwargs) -> str: + """ + Run a task using the GriptapeAgent. -**Impact**: -- Often underestimated but crucial for adoption -- Can affect productivity during the transition period -- Important for realizing the full potential of LLM integration + Parameters: + - task: The task to be performed by the agent. -### 7. Scaling Costs + Returns: + - The response from the GriptapeAgent as a string. + """ + response = self.griptape_agent.run(task, *args, **kwargs) + return str(response) -**Considerations**: -- Potential price increases as usage grows -- Need for additional infrastructure or resources -- Costs associated with managing increased complexity + def add_tool(self, tool) -> None: + """ + Add a tool to the agent. -**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 + 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 + ) -### 8. Opportunity Costs +# 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) -**Considerations**: -- Time and resources diverted from other projects -- Potential missed opportunities due to focus on LLM implementation -- Learning curve and productivity dips during adoption +``` -**Impact**: -- Difficult to quantify but important to consider -- Can affect overall business strategy and priorities -- May influence timing and scope of LLM integration +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. -### 9. Vendor Lock-in +### Langchain Integration -**Considerations**: -- Costs associated with switching providers -- Dependency on provider-specific features or integrations -- Potential for price increases once deeply integrated +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: -**Impact**: -- Can limit flexibility and negotiating power -- May affect long-term costs and strategic decisions -- Important to consider multi-provider or portable implementation strategies +```python +from typing import List, Optional -### 10. Ethical and Reputational Considerations +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 -**Considerations**: -- Potential backlash from AI-related controversies -- Costs of ensuring ethical AI use and transparency -- Investments in responsible AI practices +from swarms import Agent -**Impact**: -- Can affect brand reputation and customer trust -- May require ongoing public relations efforts -- Important for long-term sustainability and social responsibility -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. +class LangchainAgentWrapper(Agent): + """ + Initialize the LangchainAgentWrapper. -## Conclusion: Navigating the LLM Pricing Landscape + 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) -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. + prompt = StringPromptTemplate.from_template( + "You are {name}, an AI assistant. Answer the following question: {question}" + ) -Key takeaways include: + llm_chain = LLMChain(llm=self.llm, prompt=prompt) + tool_names = [tool.name for tool in self.tools] -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. + self.agent = LLMSingleActionAgent( + llm_chain=llm_chain, + output_parser=None, + stop=["\nObservation:"], + allowed_tools=tool_names, + ) -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. + self.agent_executor = AgentExecutor.from_agent_and_tools( + agent=self.agent, tools=self.tools, verbose=True + ) -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: + def run(self, task: str, *args, **kwargs): + """ + Run the agent with the given task. -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). + Args: + task (str): The task to be performed by the agent. -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). + 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}") -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. --------------------------------------------------- +# Usage example -# File: index.md +search_tool = DuckDuckGoSearchRun() +tools = [ + Tool( + name="Search", + func=search_tool.run, + description="Useful for searching the internet", + ) +] -# Welcome to Swarms Docs Home +langchain_wrapper = LangchainAgentWrapper("LangchainAssistant", tools) +result = langchain_wrapper.run("What is the capital of France?") +print(result) +``` -[![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) +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. -## What is Swarms? +### CrewAI Integration -**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. +CrewAI is a library focused on creating and managing teams of AI agents. Let's create a wrapper for a CrewAI agent: -### Key Capabilities +```python +from swarms import Agent +from crewai import Agent as CrewAIAgent +from crewai import Task, Crew, Process -- **🏢 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 +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 [] + ) -### Why Choose Swarms? + 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 -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. +# Usage example +from crewai_tools import SerperDevTool -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. +search_tool = SerperDevTool() -## Swarms Installation +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] +) -```bash -pip3 install swarms +result = crewai_wrapper.run("Analyze the latest trends in quantum computing and summarize the key findings.") +print(result) ``` -## Update Swarms +This wrapper allows us to use CrewAI agents within the swarms framework, leveraging CrewAI's focus on role-based agents and collaborative task execution. +### Autogen Integration -```bash -pip3 install -U swarms -``` - -### **Get Started Building Production-Grade Multi-Agent Applications** - -## Onboarding - -| 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/) | +Autogen is a framework for building conversational AI agents. Here's how we can create a wrapper for an Autogen agent: +```python +from swarms import Agent +from autogen import ConversableAgent -## Ecosystem +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" + ) -Here you'll find references about the Swarms framework, marketplace, community, and more to enable you to build your multi-agent applications. + def run(self, task, *args, **kwargs): + messages = [{"content": task, "role": "user"}] + response = self.autogen_agent.generate_reply(messages) + return response -| 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) | +# Usage example +import os +llm_config = { + "config_list": [{"model": "gpt-4", "api_key": os.environ.get("OPENAI_API_KEY")}] +} -## Join the Swarms Community +autogen_wrapper = AutogenAgentWrapper("AutogenAssistant", llm_config) +result = autogen_wrapper.run("Tell me a joke about programming.") +print(result) +``` -| 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 wrapper integrates Autogen's ConversableAgent into the swarms framework, allowing for easy use of Autogen's conversational AI capabilities. -## Get Support +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. -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! +## 5. Advanced Agent Handling Techniques +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. Dynamic Agent Creation --------------------------------------------------- +Implement a factory pattern to create agents dynamically based on task requirements: -# File: misc\features\20swarms.md +```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}") -```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 +# Usage +agent = AgentFactory.create_agent("griptape", "DynamicGriptapeAgent") ``` ---- -# Swarm Theta: Sentiment Scanner -**Overview**: Analyzes text for sentiment and emotional tone. -**Strengths**: Accurate sentiment detection. -**Weaknesses**: Contextual nuances might be missed. +### 2. Agent Pooling -**Pseudo Code**: -```arduino -INPUT text_data -ANALYZE text_data FOR emotional_tone -DETERMINE sentiment_value -RETURN sentiment_value -``` +Implement an agent pool to manage and reuse agents efficiently: -# Swarm Iota: Image Interpreter -**Overview**: Processes and categorizes images. -**Strengths**: High image recognition accuracy. -**Weaknesses**: Can struggle with abstract visuals. +```python +from queue import Queue -**Pseudo Code**: -```objective-c -LOAD image_data -PROCESS image_data FOR features -CATEGORIZE image_based_on_features -RETURN image_category -``` +class AgentPool: + def __init__(self, pool_size=5): + self.pool = Queue(maxsize=pool_size) + self.pool_size = pool_size -# Swarm Kappa: Language Learner -**Overview**: Translates and interprets multiple languages. -**Strengths**: Supports multiple languages. -**Weaknesses**: Nuances in dialects might pose challenges. + 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) -**Pseudo Code**: -```vbnet -RECEIVE input_text, target_language -TRANSLATE input_text TO target_language -RETURN translated_text +# Usage +pool = AgentPool() +agent = pool.get_agent("langchain", "PooledLangchainAgent") +result = agent.run("Perform a task") +pool.release_agent(agent) ``` -# Swarm Lambda: Trend Tracker -**Overview**: Monitors and predicts trends based on data. -**Strengths**: Proactive trend identification. -**Weaknesses**: Requires continuous data stream. +### 3. Agent Composition -**Pseudo Code**: -```sql -COLLECT data_over_time -ANALYZE data_trends -PREDICT upcoming_trends -RETURN trend_forecast -``` +Create composite agents that combine the capabilities of multiple agent types: -# Swarm Mu: Financial Forecaster -**Overview**: Analyzes financial data to predict market movements. -**Strengths**: In-depth financial analytics. -**Weaknesses**: Market volatility can affect predictions. +```python +class CompositeAgent(Agent): + def __init__(self, name, agents): + super().__init__() + self.name = name + self.agents = agents -**Pseudo Code**: -```sql -GATHER financial_data -COMPUTE statistical_analysis -FORECAST market_movements -RETURN financial_projections -``` + def run(self, task): + results = [] + for agent in self.agents: + results.append(agent.run(task)) + return self.aggregate_results(results) -# Swarm Nu: Network Navigator -**Overview**: Optimizes and manages network traffic. -**Strengths**: Efficient traffic management. -**Weaknesses**: Depends on network infrastructure. + def aggregate_results(self, results): + # Implement your own logic to combine results + return "\n".join(results) -**Pseudo Code**: -```sql -MONITOR network_traffic -IDENTIFY congestion_points -OPTIMIZE traffic_flow -RETURN network_status +# 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") ``` -# Swarm Xi: Content Curator -**Overview**: Gathers and presents content based on user preferences. -**Strengths**: Personalized content delivery. -**Weaknesses**: Limited by available content sources. +### 4. Agent Specialization -**Pseudo Code**: -```sql -DEFINE user_preferences -SEARCH content_sources -FILTER content_matching_preferences -DISPLAY curated_content -``` +Create specialized agents for specific domains or tasks: +```python +class DataAnalysisAgent(Agent): + def __init__(self, name, analysis_tools): + super().__init__() + self.name = name + self.analysis_tools = analysis_tools + def run(self, data): + results = {} + for tool in self.analysis_tools: + results[tool.name] = tool.analyze(data) + return results --------------------------------------------------- +# Usage +import pandas as pd +from sklearn.preprocessing import StandardScaler +from sklearn.decomposition import PCA -# File: misc\features\agent_archive.md +class AnalysisTool: + def __init__(self, name, func): + self.name = name + self.func = func -# AgentArchive Documentation -## Swarms Multi-Agent Framework + def analyze(self, data): + return self.func(data) -**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.** +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))) +] ---- +data_agent = DataAnalysisAgent("DataAnalyst", tools) +df = pd.read_csv("sample_data.csv") +analysis_results = data_agent.run(df) +``` -## Overview: +### 5. Agent Monitoring and Logging -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. +Implement a monitoring system to track agent performance and log their activities: ---- +```python +import logging +from functools import wraps -## Features: +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 -### 1. Archiving: +class MonitoredAgent(Agent): + def __init__(self, name, *args, **kwargs): + super().__init__(*args, **kwargs) + self.name = name -- **Save Transcripts**: Retain the full narrative of an agent's interaction and choices. -- **Searchable Database**: Dive into archives using specific keywords, timestamps, or tags. + @log_agent_activity + def run(self, task, *args, **kwargs): + return super().run(task, *args, **kwargs) -### 2. Bookmarking: +# 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. -- **Highlight Essential Runs**: Designate specific agent runs for future reference. -- **Annotations**: Embed notes or remarks to bookmarked runs for clearer understanding. +To switch between JSON and string output: +- Use `output_type="str"` for string output (default) +- Use `output_type="json"` for JSON output -### 3. Tagging: +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. -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. +## 6. Best Practices for Custom Agent Development -### 4. Recipe Generation: +When developing custom agents using the swarms framework, consider the following best practices: -- **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. +1. **Modular Design**: Design your agents with modularity in mind. Break down complex functionality into smaller, reusable components. -### 5. Public Archive & Sharing: +2. **Consistent Interfaces**: Maintain consistent interfaces across your custom agents to ensure interoperability within the swarms framework. -- **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. +3. **Error Handling**: Implement robust error handling and graceful degradation in your agents to ensure system stability. ---- +4. **Performance Optimization**: Optimize your agents for performance, especially when dealing with resource-intensive tasks or large-scale deployments. -## Benefits: +5. **Testing and Validation**: Develop comprehensive test suites for your custom agents to ensure their reliability and correctness. -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. +6. **Documentation**: Provide clear and detailed documentation for your custom agents, including their capabilities, limitations, and usage examples. ---- +7. **Versioning**: Implement proper versioning for your custom agents to manage updates and maintain backwards compatibility. -## Usage: +8. **Security Considerations**: Implement security best practices, especially when dealing with sensitive data or integrating with external services. -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. +Here's an example that incorporates some of these best practices: ---- +```python +import logging +from typing import Dict, Any +from swarms import Agent -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. +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}") + 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}" --------------------------------------------------- + @property + def api_key(self) -> str: + # Provide a secure way to access the API key + return self._api_key -# File: misc\features\fail_protocol.md + def __repr__(self) -> str: + return f"<{self.__class__.__name__} name='{self.name}' version='{self.version}'>" -# Swarms Multi-Agent Framework Documentation +# 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) +``` -## Table of Contents -- Agent Failure Protocol -- Swarm Failure Protocol +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 ---- +## 7. Future Directions and Challenges -## Agent Failure Protocol +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: -### 1. Overview -Agent failures may arise from bugs, unexpected inputs, or external system changes. This protocol aims to diagnose, address, and prevent such failures. +1. **Enhanced Interoperability**: Developing more sophisticated protocols for agent communication and collaboration across different libraries and frameworks. -### 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. +2. **Scalability**: Improving the framework's ability to handle large-scale swarms of agents, potentially leveraging distributed computing techniques. -### 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. +3. **Adaptive Learning**: Incorporating more advanced machine learning techniques to allow agents to adapt and improve their performance over time. -### 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. +4. **Ethical AI**: Integrating ethical considerations and safeguards into the agent development process to ensure responsible AI deployment. -### 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. +5. **Human-AI Collaboration**: Exploring new paradigms for human-AI interaction and collaboration within the swarms framework. ---- +6. **Domain-Specific Optimizations**: Developing specialized agent types and tools for specific industries or problem domains. -## Swarm Failure Protocol +7. **Explainability and Transparency**: Improving the ability to understand and explain agent decision-making processes. -### 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. +8. **Security and Privacy**: Enhancing the framework's security features to protect against potential vulnerabilities and ensure data privacy. -### 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. +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. -### 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. +## 8. Conclusion -### 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. +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. -### 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. +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. ---- +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 following these protocols, the Swarms Multi-Agent Framework can systematically address and prevent failures, ensuring a high degree of reliability and efficiency. +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! -------------------------------------------------- -# File: misc\features\human_in_loop.md - -# Human-in-the-Loop Task Handling Protocol +# File: swarms\agents\tool_agent.md -## Overview +# ToolAgent Documentation -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. +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. -## Protocol Steps +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. -### 1. Task Initiation & Analysis +### Parameters -- 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. +| 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. | -### 2. Automated Resolution Attempt +### Attributes -- Agents first attempt to resolve the task autonomously using their algorithms and data. -- If the task can be completed without issues, it progresses normally. +| 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. | -### 3. Challenge Detection +### Methods -- If agents encounter challenges or uncertainties they cannot resolve, the "Human-in-the-Loop" protocol is triggered. - -### 4. Human Collaborator Identification +#### `run` -- 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. +```python +def run(self, task: str, *args, **kwargs) -> Any: +``` -### 5. Real-time Collaboration +**Parameters:** -- 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 +| 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. | -- 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. +**Returns:** -## Best Practices +- The output of the tool agent. -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. +**Raises:** -## Conclusion +- `Exception`: If an error occurs during the execution of the tool agent. -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. +## Functionality and Usage +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. --------------------------------------------------- +### Initialization -# File: misc\features\info_sec.md +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. -# Secure Communication Protocols +```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 +) +``` -## Overview +### Running a Task -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. +To execute a task using the `ToolAgent`, the `run` method is called with the task description and any additional arguments or keyword arguments. -## Features +```python +result = agent.run("Generate a person's information based on the given schema.") +print(result) +``` -### 1. End-to-End Encryption +### Detailed Examples -- 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. +#### Example 1: Basic Usage -### 2. Authentication +```python +from transformers import AutoModelForCausalLM, AutoTokenizer +from swarms import ToolAgent -- Before initiating communication, agents authenticate each other using digital certificates. -- This prevents impersonation attacks and ensures that agents are communicating with legitimate counterparts. +model = AutoModelForCausalLM.from_pretrained("databricks/dolly-v2-12b") +tokenizer = AutoTokenizer.from_pretrained("databricks/dolly-v2-12b") -### 3. Forward Secrecy +json_schema = { + "type": "object", + "properties": { + "name": {"type": "string"}, + "age": {"type": "number"}, + "is_student": {"type": "boolean"}, + "courses": { + "type": "array", + "items": {"type": "string"} + } + } +} -- 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 +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) -- Cryptographic hashes ensure that the data has not been altered in transit. -- Any discrepancies in data integrity result in the communication being rejected. +print(generated_data) +``` -### 5. Zero-Knowledge Protocols +#### Example 2: Using a Parsing Function -- When handling especially sensitive data, agents use zero-knowledge proofs to validate information without revealing the actual data. - -### 6. Periodic Key Rotation +```python +def parse_output(output): + # Custom parsing logic + return output -- 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. +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 +) -## Best Practices for Handling Personal and Sensitive Information +task = "Generate a person's information with custom parsing:" +parsed_data = agent.run(task) -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. +print(parsed_data) +``` -## Conclusion +#### Example 3: Specifying Maximum Number of Tokens -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. +```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) --------------------------------------------------- +print(limited_data) +``` -# File: misc\features\promptimizer.md -# Promptimizer Documentation -## Swarms Multi-Agent Framework +## Full Usage +```python -**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.** +from pydantic import BaseModel, Field +from transformers import AutoModelForCausalLM, AutoTokenizer ---- +from swarms import ToolAgent +from swarms.tools.json_utils import base_model_to_json -## Overview: +# Model name +model_name = "CohereForAI/c4ai-command-r-v01-4bit" -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. +# Load the pre-trained model and tokenizer +model = AutoModelForCausalLM.from_pretrained( + model_name, + device_map="auto", +) ---- +# Load the pre-trained model and tokenizer +tokenizer = AutoTokenizer.from_pretrained(model_name) -## Core Features: -### 1. Deep Prompt Analysis: +# 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", + ) -- **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. -### 2. Adaptive Recommendations: +# Convert the schema to a JSON string +api_example_schema = base_model_to_json(APIExampleRequestSchema) +# Convert the schema to a JSON string -- **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. +# Define the task to generate a person's information +task = "Generate an example API request using this code:\n" -### 3. Versatile Category Framework: +# 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, +) -- **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. +# Run the agent to generate the person's information +generated_data = agent.run(task) -### 4. Machine Learning Integration: +# Print the generated data +print(f"Generated data: {generated_data}") -- **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. -### 5. Collaboration & Sharing: -- **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. +``` ---- -## Benefits: +## Jamba ++ ToolAgent +```python +from pydantic import BaseModel, Field +from transformers import AutoModelForCausalLM, AutoTokenizer -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. +from swarms import ToolAgent +from swarms.tools.json_utils import base_model_to_json ---- +# Model name +model_name = "ai21labs/Jamba-v0.1" -## Usage Workflow: +# Load the pre-trained model and tokenizer +model = AutoModelForCausalLM.from_pretrained( + model_name, + device_map="auto", +) -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. +# Load the pre-trained model and tokenizer +tokenizer = AutoTokenizer.from_pretrained(model_name) ---- -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. +# 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", + ) +# Convert the schema to a JSON string +api_example_schema = base_model_to_json(APIExampleRequestSchema) +# Convert the schema to a JSON string --------------------------------------------------- - -# File: misc\features\shorthand.md - -# Shorthand Communication System -## Swarms Multi-Agent Framework - -**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.** - ---- - -## Format: - -The shorthand format is structured as `[AgentType]-[TaskLayer].[TaskNumber]-[Priority]-[Status]`. - ---- - -## Components: - -### 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 - -### 2. Task Layer & Number: -- Represents the task's category. - * Example: `1.8` signifies Task layer 1, task number 8. - -### 3. Priority: -- Indicates task urgency. - * `H`: High - * `M`: Medium - * `L`: Low - -### 4. Status: -- Gives a snapshot of the task's progress. - * `I`: Initialized - * `P`: In-progress - * `C`: Completed - * `F`: Failed - * `W`: Waiting - ---- - -## Extended Features: - -### 1. Error Codes (for failures): -- `E01`: Resource issues -- `E02`: Data inconsistency -- `E03`: Dependency malfunction -... and more as needed. +# Define the task to generate a person's information +task = "Generate an example API request using this code:\n" -### 2. Collaboration Flag: -- `+`: Denotes required collaboration. +# 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, +) ---- +# Run the agent to generate the person's information +generated_data = agent(task) -## Example Codes: +# Print the generated data +print(f"Generated data: {generated_data}") +``` -- `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. +## Additional Information and Tips ---- +- 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. -By leveraging the Enhanced Shorthand Communication System, the Swarms Multi-Agent Framework can ensure swift interactions, concise communications, and effective task management. +## 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. -------------------------------------------------- -# 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 +# File: swarms\artifacts\artifact.md -- **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. +# `Artifact` -- **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). +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. -- **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. +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. -- **Agent Supervision**: - - Monitor agent actions in real-time. - - Intervene, if necessary, to guide agent actions based on permissions. +## Class Definition -- **Audit Trail**: - - All actions, whether performed by humans or AI agents, are logged. - - Review historical actions, decisions, and interventions for accountability and improvement. +### Artifact -### 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. +| 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. | -### 4. Integration +### Parameters and Validation -- **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. +- `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. -## 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. +### Methods +The `Artifact` class includes various methods for creating, editing, saving, loading, and exporting file artifacts. --------------------------------------------------- +#### `create` -# File: protocol\bc.md +| Parameter | Type | Description | +|--------------------|--------|----------------------------------------| +| `initial_content` | `str` | The initial content of the file. | -# Backwards Compatability +**Usage Example:** --------------------------------------------------- +```python +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` -# File: protocol\overview.md -# Swarms Protocol Overview & Architecture +| Parameter | Type | Description | +|---------------|--------|----------------------------------------| +| `new_content` | `str` | The new content of the file. | -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. +**Usage Example:** ---- +```python +artifact.edit(new_content="Updated file content") +``` -## Introduction +#### `save` -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. +**Usage Example:** -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. +```python +artifact.save() +``` -For a high-level introduction and installation instructions, see the [Swarms Docs Home](https://docs.swarms.world/en/latest/). +#### `load` ---- +**Usage Example:** -## High-Level Architecture Flow +```python +artifact.load() +``` -The Swarms protocol is organized into several key layers, each responsible for a specific aspect of the system. The typical flow is as follows: +#### `get_version` -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/) -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.). +| Parameter | Type | Description | +|-------------------|-------|-----------------------------------------| +| `version_number` | `int` | The version number to retrieve. | - - 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/) +**Usage Example:** -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. +```python +version = artifact.get_version(version_number=1) +``` - - Includes agents for self-reflection, iterative improvement, and domain-specific expertise. +#### `get_contents` - - Example: A `SelfConsistencyAgent` that aggregates multiple reasoning paths, or a `JudgeAgent` that evaluates outputs from other - agents. +**Usage Example:** - - [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/) +```python +current_contents = artifact.get_contents() +``` -4. **Multi-Agent Structures (`swarms/structs`)** - - Agents are composed into higher-order structures for collaboration, voting, parallelism, and workflow orchestration. +#### `get_version_history` - - Includes swarms for majority voting, round-robin execution, hierarchical delegation, and more. - - Example: A `MajorityVotingSwarm` that aggregates outputs from several agents, or a `HierarchicalSwarm` that delegates tasks to - sub-agents. +**Usage Example:** - - [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/) +```python +version_history = artifact.get_version_history() +``` -5. **Supporting Components** +#### `export_to_json` - - **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/) ---- +| Parameter | Type | Description | +|-------------|-------|----------------------------------------------| +| `file_path` | `str` | The path to the JSON file to save the artifact.| -## Proposing Large Improvements or Enhancements: Swarms Improvement Proposals (SIPs) +**Usage Example:** -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. +```python +artifact.export_to_json(file_path="artifact.json") +``` -**When to use a SIP:** +#### `import_from_json` -- Proposing new agent types, swarm patterns, or coordination mechanisms -- Core framework changes or breaking changes +| Parameter | Type | Description | +|-------------|-------|--------------------------------------------------| +| `file_path` | `str` | The path to the JSON file to import the artifact from.| -- New integrations (LLM providers, tools, external services) +**Usage Example:** -- Any complex or multi-component feature +```python +imported_artifact = Artifact.import_from_json(file_path="artifact.json") +``` -**SIP Process Overview:** +#### `get_metrics` -1. Discuss your idea in [GitHub Discussions](https://github.com/kyegomez/swarms/discussions) +**Usage Example:** -2. Submit a SIP as a GitHub Issue using the SIP template +```python +metrics = artifact.get_metrics() +``` -3. Engage with the community and iterate on your proposal +#### `to_dict` -4. Undergo review and, if accepted, proceed to implementation +**Usage Example:** -**Learn more:** See the full [SIP Guidelines and Template](https://docs.swarms.world/en/latest/protocol/sip/) +```python +artifact_dict = artifact.to_dict() +``` ---- +#### `from_dict` -## Detailed Architecture Diagram +| Parameter | Type | Description | +|-----------|------------------|--------------------------------------------------| +| `data` | `Dict[str, Any]` | The dictionary representation of the artifact. | -The following Mermaid diagram visualizes the protocol flow and the relationship between the main folders in the `swarms/` package: +**Usage Example:** -```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 +```python +artifact_data = { + "file_path": "example.txt", + "file_type": "txt", + "contents": "File content", + "versions": [], + "edit_count": 0 +} +artifact = Artifact.from_dict(artifact_data) ``` ---- - -## Folder-by-Folder Breakdown +## Additional Information and Tips -### `agents/` +- 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. -**Purpose:** Defines all agent classes, including base agents, reasoning agents, tool agents, judge agents, and more. +## References and Resources -**Highlights:** +- [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) -- Modular agent design for extensibility. +## Examples of Usage -- Support for YAML-based agent creation and configuration. See [YAML Agent Creation](https://docs.swarms.world/en/latest/swarms/ -agents/create_agents_yaml/) +### Example 1: Creating and Editing an Artifact -- Specialized agents for self-consistency, evaluation, and domain-specific tasks. +```python +from datetime import datetime +from pydantic import BaseModel, Field, validator +from typing import List, Dict, Any, Union +import os +import json -- **Example:** +# Define FileVersion class +class FileVersion(BaseModel): + version_number: int + content: str + timestamp: datetime -- `ReasoningAgent`, `ToolAgent`, `JudgeAgent`, `ConsistencyAgent`, `OpenAIAssistant`, etc. +# Artifact class definition goes here -- [Agents Overview](https://docs.swarms.world/en/latest/swarms/framework/agents_explained/) +# Create an artifact +artifact = Artifact(file_path="example.txt", file_type="txt") +artifact.create(initial_content="Initial file content") +# Edit the artifact +artifact.edit(new_content="Updated file content") -### `tools/` +# Save the artifact to a file +artifact.save() -**Purpose:** Houses all tool-related logic, including tool registry, function calling, tool schemas, and integration with external -APIs. +# Load the artifact from the file +artifact.load() -**Highlights:** +# Print the current contents of the artifact +print(artifact.get_contents()) -- Tools can be dynamically registered and called by agents. +# Print the version history +print(artifact.get_version_history()) +``` -- Support for OpenAI function calling, Cohere, and custom tool schemas. +### Example 2: Exporting and Importing an Artifact -- Utilities for parsing, formatting, and executing tool calls. +```python +# Export the artifact to a JSON file +artifact.export_to_json(file_path="artifact.json") -- **Example:** +# Import -- `base_tool.py`, `tool_registry.py`, `mcp_client_call.py`, `func_calling_utils.py`, etc. + the artifact from a JSON file +imported_artifact = Artifact.import_from_json(file_path="artifact.json") -- [Tools Reference](https://docs.swarms.world/en/latest/swarms/tools/tools_examples/) +# Print the metrics of the imported artifact +print(imported_artifact.get_metrics()) +``` -- [What are tools?](https://docs.swarms.world/en/latest/swarms/tools/build_tool/) +### Example 3: Converting an Artifact to and from a Dictionary +```python +# Convert the artifact to a dictionary +artifact_dict = artifact.to_dict() -### `structs/` -**Purpose:** Implements multi-agent structures, workflows, routers, registries, and orchestration logic. +# Create a new artifact from the dictionary +new_artifact = Artifact.from_dict(artifact_dict) -**Highlights:** +# Print the metrics of the new artifact +print(new_artifact.get_metrics()) +``` -- Swarms for majority voting, round-robin, hierarchical delegation, spreadsheet processing, and more. -- Workflow orchestration (sequential, concurrent, graph-based). +-------------------------------------------------- -- Utilities for agent matching, rearrangement, and evaluation. +# File: swarms\cli\cli_guide.md -- **Example:** +# The Ultimate Technical Guide to the Swarms CLI: A Step-by-Step Developer’s Guide -- `MajorityVotingSwarm`, `HierarchicalSwarm`, `SwarmRouter`, `SequentialWorkflow`, `ConcurrentWorkflow`, etc. +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. -- [Custom Multi Agent Architectures](https://docs.swarms.world/en/latest/swarms/structs/custom_swarm/) +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. -- [SwarmRouter](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/) +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! -- [AgentRearrange](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/) +--- +## 1. Installing the Swarms CLI -### `utils/` +Before we explore the Swarms CLI commands, let’s get it installed and running on your machine. -**Purpose:** Provides utility functions, memory management, caching, wrappers, and helpers used throughout the framework. +### 1.1. Installation Using `pip` -**Highlights:** +For most users, the simplest way to install the Swarms CLI is through `pip`: -- Memory and caching for agents and tools. See [Integrating RAG with Agents](https://docs.swarms.world/en/latest/swarms/memory/ -diy_memory/) +```bash +pip3 install -U swarms +``` -- Wrappers for concurrency, logging, and data processing. +This command installs the latest version of the Swarms CLI package, ensuring that you have the newest features and fixes. -- General-purpose utilities for string, file, and data manipulation. +### 1.2. Installation Using `Poetry` -**Example:** +Alternatively, if you are using `Poetry` as your Python package manager, you can add the Swarms package like this: -- `agent_cache.py`, `concurrent_wrapper.py`, `file_processing.py`, `formatter.py`, etc. +```bash +poetry add swarms +``` +Once installed, you can run the Swarms CLI directly using: -### `telemetry/` +```bash +poetry run swarms help +``` -**Purpose:** Handles telemetry, logging, monitoring, and bootup routines for the framework. +This command shows all the available options and commands, as we will explore in-depth below. -**Highlights:** +--- -- Centralized logging and execution tracking. +## 2. Understanding Swarms CLI Commands -- Bootup routines for initializing the framework. +With the Swarms CLI installed, the next step is to explore its key functionalities. Here are the most essential commands: -- Utilities for monitoring agent and swarm performance. +### 2.1. `onboarding`: Setup Your Environment -- **Example:** +The `onboarding` command guides you through setting up your environment and configuring the agents for your Swarms. -- `bootup.py`, `log_executions.py`, `main.py`. +```bash +swarms onboarding +``` +This is the first step when you begin working with the Swarms platform. It helps to: -### `schemas/` +- Authenticate your Swarms account. +- Download any necessary configurations. +- Ensure everything is in place to launch agents seamlessly. -**Purpose:** Defines data schemas for agents, tools, completions, and communication protocols. +### 2.2. `help`: Learn Available Commands -**Highlights:** +Running `help` displays the various commands you can use: -- Ensures type safety and consistency across the framework. +```bash +swarms help +``` -- Pydantic-based schemas for validation and serialization. +This command will output a helpful list like the one shown below, including detailed descriptions of each command. -- Schemas for agent classes, tool calls, completions, and more. +```plaintext +Swarms CLI - Help -**Example:** +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 +``` -- `agent_class_schema.py`, `tool_schema_base_model.py`, `agent_completion_response.py`, etc. +### 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: -### `prompts/` +```bash +swarms get-api-key +``` -**Purpose:** Contains prompt templates, system prompts, and agent-specific prompts for LLM-based agents. +Your API key is essential to enable agent workflows and access various services through the Swarms platform. -**Highlights:** +### 2.4. `check-login`: Verify Authentication -- Modular prompt design for easy customization. +Use the `check-login` command to verify if you're logged in and ensure that your credentials are cached: -- Support for multi-modal, collaborative, and domain-specific prompts. +```bash +swarms check-login +``` -- Templates for system, task, and conversational prompts. +This ensures seamless operation, allowing agents to execute tasks securely on the Swarms platform without needing to log in repeatedly. -**Example:** +### 2.5. `read-docs`: Explore Official Documentation -- `prompt.py`, `reasoning_prompt.py`, `multi_agent_collab_prompt.py`, etc. +Easily access the official documentation with this command: -- [Prompts Management](https://docs.swarms.world/en/latest/swarms/prompts/main/) +```bash +swarms read-docs +``` +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. -### `artifacts/` +### 2.6. `run-agents`: Orchestrate Agents -**Purpose:** Manages the creation, storage, and retrieval of artifacts (outputs, files, logs) generated by agents and swarms. +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. -**Highlights:** +```bash +swarms run-agents --yaml-file agents.yaml +``` -- Artifact management for reproducibility and traceability. -- Support for various output types and formats. +If you want to specify a custom configuration file, just pass in the YAML file using the `--yaml-file` flag. -**Example:** +--- -- `main_artifact.py`. +## 3. Working with the `agents.yaml` Configuration File +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. -### `communication/` +### 3.1. Example `agents.yaml` Configuration: -**Purpose:** Provides wrappers for inter-agent communication, database access, message passing, and integration with external systems. - -**Highlights:** - -- Support for Redis, DuckDB, Pulsar, Supabase, and more. -- Abstractions for message passing and data exchange between agents. +```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?" -**Example:** + - 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." -- `redis_wrap.py`, `duckdb_wrap.py`, `base_communication.py`, etc. + - 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." -- [Communication Structure](https://docs.swarms.world/en/latest/swarms/structs/conversation/) + - 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." +``` +### 3.2. Explanation of Key Fields -### `cli/` +- **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. -**Purpose:** Command-line utilities for agent creation, management, and orchestration. +### 3.3. Running Agents Using `agents.yaml` -**Highlights:** +After configuring the agents, you can execute them directly from the CLI: -- Scripts for onboarding, agent creation, and management. +```bash +swarms run-agents --yaml-file agents_config.yaml +``` -- CLI entry points for interacting with the framework. +This command will run the specified agents, allowing them to perform their tasks and return results according to your configuration. -**Example:** +--- -- `main.py`, `create_agent.py`, `onboarding_process.py`. +## 4. Use Cases for the Swarms CLI -- [CLI Documentation](https://docs.swarms.world/en/latest/swarms/cli/main/) +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. +### 4.1. Financial Data Analysis ---- +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. -## How the System Works Together +Example Task: Automating long-term investment analysis using historical stock data. -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. +```bash +swarms run-agents --yaml-file finance_analysis.yaml +``` -For example, a typical workflow might involve: +### 4.2. Marketing Automation -- Creating a set of specialized agents (e.g., data analyst, summarizer, judge). +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. -- Registering tools (e.g., LLM API, database access, web search) and memory modules. +Example Task: Running multiple agents to analyze customer sentiment from recent surveys. -- Composing agents into a `MajorityVotingSwarm` for collaborative decision-making. +```bash +swarms run-agents --yaml-file marketing_agents.yaml +``` -- Using communication wrappers to exchange data between agents and external systems. +### 4.3. Operations and Task Management -- Logging all actions and outputs for traceability and debugging. +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. +Example Task: Automating a task management system using Swarms agents. -For more advanced examples, see the [Examples Overview](https://docs.swarms.world/en/latest/examples/index/). +```bash +swarms run-agents --yaml-file operations_agents.yaml +``` --- -## Swarms Framework Philosophy - -Swarms is built on the following principles: +## 5. Advanced Usage: Customizing and Scaling Agents -- **Modularity:** Every component (agent, tool, prompt, schema) is a module that can be extended or replaced. +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. -- **Composability:** Agents and tools can be composed into larger structures for complex workflows. +### 5.1. Running Agents in Parallel -- **Observability:** Telemetry and artifact management ensure that all actions are traceable and debuggable. +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. -- **Extensibility:** New agents, tools, and workflows can be added with minimal friction. +```bash +swarms run-agents --yaml-file agents_batch_1.yaml & +swar -- **Production-Readiness:** The framework is designed for reliability, scalability, and real-world deployment. +ms run-agents --yaml-file agents_batch_2.yaml & +``` +### 5.2. Integration with Other Tools -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/). +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. --- -## Further Reading & References +## 6. Conclusion and Next Steps -- [Swarms Docs Home](https://docs.swarms.world/en/latest/) +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. -- [Quickstart for Agents](https://docs.swarms.world/en/latest/swarms/agents/) +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). -- [Agent API Reference](https://docs.swarms.world/en/latest/swarms/structs/agent/) +With the Swarms CLI, the future of automation is within reach. -- [Tools Overview](https://docs.swarms.world/en/latest/swarms_tools/overview/) -- [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/) +-------------------------------------------------- -- [Multi-Agent Architectures Overview](https://docs.swarms.world/en/latest/swarms/concept/swarm_architectures/) +# File: swarms\cli\main.md -- [Examples Overview](https://docs.swarms.world/en/latest/examples/index/) +# Swarms CLI Documentation -- [CLI Documentation](https://docs.swarms.world/en/latest/swarms/cli/main/) +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. -- [Prompts Management](https://docs.swarms.world/en/latest/swarms/prompts/main/) +## Installation -- [Development Philosophy & Principles](https://docs.swarms.world/en/latest/swarms/concept/philosophy/) +You can install the `swarms` package using `pip` or `poetry`. -- [Understanding Swarms Architecture](https://docs.swarms.world/en/latest/swarms/concept/framework_architecture/) +### Using pip -- [SIP Guidelines and Template](https://docs.swarms.world/en/latest/protocol/sip/) +```bash +pip3 install -U swarms +``` +### Using poetry -# Conclusion +```bash +poetry add swarms +``` -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. +Once installed, you can run the Swarms CLI with the following command: +```bash +poetry run swarms help +``` +## Swarms CLI - Help --------------------------------------------------- +When running `swarms help`, you'll see the following output: -# File: protocol\sip.md +``` + _________ + / _____/_ _ _______ _______ _____ ______ + \_____ \ \/ \/ /\__ \_ __ \/ \ / ___/ + / \ / / __ \| | \/ Y Y \___ \ +/_______ / \/\_/ (____ /__| |__|_| /____ > + \/ \/ \/ \/ -# Swarms Improvement Proposal (SIP) Guidelines -A simplified process for proposing new functionality and enhancements to the Swarms framework. -## What is a SIP? + Swarms CLI - Help -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. + 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 -The SIP author is responsible for building consensus within the community and documenting the proposal clearly and concisely. + For more details, visit: https://docs.swarms.world +``` -## When to Submit a SIP +### CLI Commands -Consider submitting a SIP for: +Below is a detailed explanation of the available commands: -- **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 +- **onboarding** + Starts the onboarding process to help you set up your environment and configure your agents. + + Usage: + ```bash + swarms onboarding + ``` -For simple bug fixes, minor enhancements, or straightforward additions, use regular GitHub issues and pull requests instead. +- **help** + Displays the help message, including a list of available commands. -## SIP Types + Usage: + ```bash + swarms help + ``` -**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 +- **get-api-key** + Retrieves your API key from the platform, allowing your agents to communicate with the Swarms platform. -## Submitting a SIP + Usage: + ```bash + swarms get-api-key + ``` -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 +- **check-login** + Verifies if you are logged into the platform and starts the cache for storing your login session. -## SIP Format + Usage: + ```bash + swarms check-login + ``` -### Required Sections +- **read-docs** + Redirects you to the official Swarms documentation on the web for further reading. -#### **SIP Header** -``` -Title: [Descriptive title] -Author: [Your name and contact] -Type: [Standard/Process/Informational] -Status: Proposal -Created: [Date] -``` + Usage: + ```bash + swarms read-docs + ``` -#### **Abstract** (200 words max) -A brief summary of what you're proposing and why. +- **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` -#### **Motivation** -- What problem does this solve? -- Why can't the current framework handle this? -- What are the benefits to the Swarms ecosystem? + Usage: + ```bash + swarms run-agents --yaml-file agents.yaml + ``` -#### **Specification** -- Detailed technical description -- API changes or new interfaces -- Code examples showing usage -- Integration points with existing framework -#### **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 +# File: swarms\concept\framework_architecture.md -### Optional Sections +# Swarms Framework Architecture -#### **Reference Implementation** -Link to prototype code or proof-of-concept (can be added later) -#### **Security Considerations** -Any security implications or requirements +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. + -## SIP Workflow ``` -Proposal → Draft → Review → Accepted/Rejected → Final +swarms/ +├── agents/ +├── artifacts/ +├── cli/ +├── memory/ +├── models/ ---> Moved to swarm_models +├── prompts/ +├── schemas/ +├── structs/ +├── telemetry/ +├── tools/ +├── utils/ +└── __init__.py ``` -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 -## SIP Status -- **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 +### Role of Folders in the Swarms Framework -## Review Process +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. -- 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) +--- -## Getting Help +### **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. -- **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 +--- -## SIP Template +### **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. -When creating your SIP, copy this template: +--- -```markdown -# SIP-XXX: [Title] +### **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. -**Author**: [Your name] <[email]> -**Type**: Standard -**Status**: Proposal -**Created**: [Date] +--- -## Abstract +### **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. -[Brief 200-word summary] +--- -## Motivation +### **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. -[Why is this needed? What problem does it solve?] +--- -## Specification +### **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. -[Detailed technical description with code examples] +--- -## Implementation Plan +### **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. -[How will this be built? Any breaking changes?] +--- -## Alternatives Considered +### **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. -[Other approaches and why you chose this one] +--- -## Reference Implementation +### **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. -[Link to prototype code if available] -``` +--- + +### **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. --- -**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. +### **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. --------------------------------------------------- +--- -# File: quickstart.md +### **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. +--- -# Welcome to Swarms Docs Home +### How to Access Documentation -[![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) +- **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. -## What is Swarms? +- **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. -**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. +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. -### Key Capabilities +## Support: -- **🏢 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 +- **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 -### Why Choose Swarms? -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. +- **Community Support** + - URL: [Submit issue](https://discord.gg/jM3Z6M9uMq) + - Ask the community for support in real-time and or admin support -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. +-------------------------------------------------- -Get started learning swarms with the following examples and more. +# File: swarms\concept\future_swarm_architectures.md -## Install 💻 -```bash -$ pip3 install -U swarms -``` - -### Using uv (Recommended) -[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver, written in Rust. -```bash -# Install uv -$ curl -LsSf https://astral.sh/uv/install.sh | sh +--- -# Install swarms using uv -$ uv pip install swarms -``` +### Federated Swarm -### Using poetry -```bash -# Install poetry if you haven't already -$ curl -sSL https://install.python-poetry.org | python3 - +**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. -# Add swarms to your project -$ poetry add swarms -``` +**Use-Cases:** +- Distributed learning systems where data is processed across multiple nodes. -### From source -```bash -# Clone the repository -$ git clone https://github.com/kyegomez/swarms.git -$ cd swarms +- Scenarios requiring collaboration between different teams or departments. -# Install with pip -$ pip install -e . +```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 ``` --- -## Environment Configuration - -[Learn more about the environment configuration here](https://docs.swarms.world/en/latest/swarms/install/env/) +### Star Swarm -``` -OPENAI_API_KEY="" -WORKSPACE_DIR="agent_workspace" -ANTHROPIC_API_KEY="" -GROQ_API_KEY="" -``` +**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. +**Use-Cases:** +- Centralized decision-making processes. +- Scenarios requiring a central authority to coordinate multiple workers. -### 🤖 Your First Agent +```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] +``` -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/) +--- -```python -from swarms import Agent +### Mesh Swarm -# 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 -) +**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. -# Run the agent with a task -agent.run("What are the key benefits of using a multi-agent system?") -``` +**Use-Cases:** +- Complex systems requiring high fault tolerance and redundancy. -### 🤝 Your First Swarm: Multi-Agent Collaboration +- Scenarios involving dynamic and frequent communication between agents. -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/) +```mermaid +graph TD + A1[Agent 1] --> A2[Agent 2] + A1 --> A3[Agent 3] + A1 --> A4[Agent 4] + A2 --> A3 + A2 --> A4 + A3 --> A4 +``` -```python -from swarms import Agent, SequentialWorkflow +--- -# 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", -) +### Cascade Swarm -# 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", -) +**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. -# Create a sequential workflow where the researcher's output feeds into the writer's input -workflow = SequentialWorkflow(agents=[researcher, writer]) +**Use-Cases:** +- Multi-stage processing tasks such as data transformation pipelines. -# Run the workflow on a task -final_post = workflow.run("The history and future of artificial intelligence") -print(final_post) +- 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] ``` ------ - -## 🏗️ Multi-Agent Architectures For Production Deployments +--- -`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. +### Hybrid Swarm -| **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. | +**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. ------ +**Use-Cases:** +- Complex workflows requiring a mix of different processing strategies. -### SequentialWorkflow +- Custom scenarios tailored to specific operational requirements. -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. +```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] +``` -```python -from swarms import Agent, SequentialWorkflow +--- -# 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") +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. -# Create the sequential workflow -workflow = SequentialWorkflow(agents=[idea_generator, validator, pitch_creator]) +-------------------------------------------------- -# Run the workflow -elevator_pitch = workflow.run() -print(elevator_pitch) -``` +# File: swarms\concept\how_to_choose_swarms.md ------ +# Choosing the Right Swarm for Your Business Problem +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. -### ConcurrentWorkflow (with `SpreadSheetSwarm`) +## Swarm Types Overview -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. +- **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). -```python -from swarms import Agent, SpreadSheetSwarm +--- -# Define a list of tasks (e.g., social media posts to generate) -platforms = ["Twitter", "LinkedIn", "Instagram"] +## MajorityVoting Swarm -# 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 -] +### 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. -# Initialize the swarm to run these agents concurrently -swarm = SpreadSheetSwarm( - agents=agents, - autosave_on=True, - save_file_path="marketing_posts.csv", -) +### Advantages +- Ensures robustness in decision-making by leveraging multiple agents. +- Helps eliminate outliers or faulty agent decisions. -# 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! -``` +### 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. --- -### AgentRearrange +## AgentRearrange (Sequential and Parallel) -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. +### 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. -```python -from swarms import Agent, AgentRearrange +### 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. -# 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") +### Notes +!!! note + Sequential swarms are slower but ensure strict task dependencies are respected. Parallel swarms are faster but require careful management of task interdependencies. -# Define a flow: researcher sends work to both writer and editor simultaneously -# This is a one-to-many relationship -flow = "researcher -> writer, editor" +--- -# Create the rearrangement system -rearrange_system = AgentRearrange( - agents=[researcher, writer, editor], - flow=flow, -) +## RoundRobin Swarm -# 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) -``` +### 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. +### Advantages +- Fair and even distribution of tasks. +- Simple and effective for balanced workloads. - +### 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. -### SwarmRouter: The Universal Swarm Orchestrator +--- -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/) +## GroupChat Swarm -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. +### 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. -```python -from swarms import Agent -from swarms.structs.swarm_router import SwarmRouter, SwarmType +### Advantages +- Facilitates highly interactive problem-solving. +- Ideal for dynamic and unstructured problems. -# 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") +### Warnings +!!! warning + High communication overhead between agents may slow down decision-making in large swarms. -# 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") +## AgentRegistry Swarm -# --- 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") +### 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. -# --- 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") -``` +### Notes +!!! note + AgentRegistry is a flexible solution but introduces additional complexity when agents need to be discovered and registered on the fly. +--- -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. +## SpreadsheetSwarm -------- +### 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. -### MixtureOfAgents (MoA) +### Advantages +- Provides structure and order for managing massive amounts of agent outputs. +- Outputs are easily saved and tracked in CSV files. -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/) +### Warnings +!!! warning + Ensure the correct configuration of agents in SpreadsheetSwarm to avoid data mismatches and inconsistencies when scaling up to thousands of agents. -```python -from swarms import Agent, MixtureOfAgents +--- -# 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") +## Final Thoughts -# 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" -) +The choice of swarm depends on: -# Create the MoA swarm -moa_swarm = MixtureOfAgents( - agents=[financial_analyst, market_analyst, risk_analyst], - aggregator_agent=aggregator, -) +1. **Nature of the task**: Whether it's sequential or parallel. -# Run the swarm -recommendation = moa_swarm.run("Should we invest in NVIDIA stock right now?") -print(recommendation) -``` +2. **Problem complexity**: Simple problems might benefit from RoundRobin, while complex ones may need GraphWorkflow or Mixture of Agents. ----- +3. **Scale of execution**: For large-scale tasks, Swarms like SpreadsheetSwarm or MajorityVoting provide scalability with structured outputs. -### GroupChat +When integrating agents in a business workflow, it's crucial to balance task complexity, agent capabilities, and scalability to ensure the optimal swarm architecture. -`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. -```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") +# File: swarms\concept\philosophy.md -# Create the group chat -chat = GroupChat( - agents=[tech_optimist, tech_critic], - max_loops=4, # Limit the number of turns in the conversation -) +# Our Philosophy: Simplifying Multi-Agent Collaboration Through Readable Code and Performance Optimization -# Run the chat with an initial topic -conversation_history = chat.run( - "Let's discuss the societal impact of artificial intelligence." -) +Our mission is to streamline multi-agent collaboration by emphasizing simplicity, readability, and performance in our codebase. This document outlines our core tactics: -# Print the full conversation -for message in conversation_history: - print(f"[{message['agent_name']}]: {message['content']}") -``` +- **Readable Code with Type Annotations, Documentation, and Logging** +- **Bleeding-Edge Performance via Concurrency and Parallelism** +- **Simplified Abstractions for Multi-Agent Collaboration** + +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. +--- +## 1. Emphasizing Readable Code +Readable code is the cornerstone of maintainable and scalable systems. It ensures that developers can easily understand, modify, and extend the codebase. --------------------------------------------------- +### 1.1 Use of Type Annotations -# File: swarms\agents\abstractagent.md +Type annotations enhance code readability and catch errors early in the development process. -# swarms.agents +```python +def process_data(data: List[str]) -> Dict[str, int]: + result = {} + for item in data: + result[item] = len(item) + return result +``` -## 1. Introduction +### 1.2 Code Style Guidelines -`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. +Adhering to consistent code style guidelines, such as PEP 8 for Python, ensures uniformity across the codebase. -`AbstractAgent` provides capabilities for managing tools and accessing memory, and has methods for running, chatting, and stepping through communication with other agents. +- **Indentation:** Use 4 spaces per indentation level. +- **Variable Naming:** Use `snake_case` for variables and functions. +- **Class Naming:** Use `PascalCase` for class names. -## 2. Class Definition +### 1.3 Importance of Documentation -```python -class AbstractAgent: - """An abstract class for AI agent. +Comprehensive documentation helps new developers understand the purpose and functionality of code modules. - An agent can communicate with other agents and perform actions. - Different agents can differ in what actions they perform in the `receive` method. +```python +def fetch_user_profile(user_id: str) -> UserProfile: + """ + Fetches the user profile from the database. - Agents are full and completed: + Args: + user_id (str): The unique identifier of the user. - Agents = llm + tools + memory + Returns: + UserProfile: An object containing user profile data. """ + # Function implementation +``` - def __init__(self, name: str): - """ - Args: - name (str): name of the agent. - """ - self._name = name +### 1.4 Consistent Naming Conventions - @property - def name(self): - """Get the name of the agent.""" - return self._name +Consistent naming reduces confusion and makes the code self-explanatory. - def tools(self, tools): - """init tools""" +- **Functions:** Should be verbs (e.g., `calculate_total`). +- **Variables:** Should be nouns (e.g., `total_amount`). +- **Constants:** Should be uppercase (e.g., `MAX_RETRIES`). - def memory(self, memory_store): - """init memory""" +--- - def reset(self): - """(Abstract method) Reset the agent.""" - - def run(self, task: str): - """Run the agent once""" +## 2. Effective Logging Practices - def _arun(self, taks: str): - """Run Async run""" +Logging is essential for debugging and monitoring the health of applications. - def chat(self, messages: List[Dict]): - """Chat with the agent""" +### 2.1 Why Logging is Important - def _achat(self, messages: List[Dict]): - """Asynchronous Chat""" +- **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. - def step(self, message: str): - """Step through the agent""" +### 2.2 Best Practices for Logging - def _astep(self, message: str): - """Asynchronous step""" -``` +- **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. -## 3. Functionality and Usage +### 2.3 Logging Examples -The `AbstractAgent` class represents a generic AI agent and provides a set of methods to interact with it. +```python +import logging -To create an instance of an agent, the `name` of the agent should be specified. +logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s:%(message)s') -### Core Methods +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 +``` -#### 1. `reset` +--- -The `reset` method allows the agent to be reset to its initial state. +## 3. Achieving Bleeding-Edge Performance -```python -agent.reset() -``` +Performance is critical, especially when dealing with multiple agents and large datasets. -#### 2. `run` +### 3.1 Concurrency and Parallelism -The `run` method allows the agent to perform a specific task. +Utilizing concurrency and parallelism can significantly improve performance. -```python -agent.run("some_task") -``` +- **Concurrency:** Dealing with multiple tasks by managing multiple threads. +- **Parallelism:** Executing multiple tasks simultaneously on multiple CPU cores. -#### 3. `chat` +### 3.2 Asynchronous Programming -The `chat` method enables communication with the agent through a series of messages. +Asynchronous programming allows for non-blocking operations, leading to better resource utilization. ```python -messages = [{"id": 1, "text": "Hello, agent!"}, {"id": 2, "text": "How are you?"}] -agent.chat(messages) -``` +import asyncio -#### 4. `step` +async def fetch_data(endpoint: str) -> dict: + async with aiohttp.ClientSession() as session: + async with session.get(endpoint) as response: + return await response.json() -The `step` method allows the agent to process a single message. +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) -```python -agent.step("Hello, agent!") +asyncio.run(main()) ``` -### Asynchronous Methods +### 3.3 Utilizing Modern Hardware Capabilities -The class also provides asynchronous variants of the core methods. +Leverage multi-core processors and GPUs for computationally intensive tasks. -### Additional Functionality +- **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. -Additional functionalities for agent initialization and management of tools and memory are also provided. +### 3.4 Code Example: Parallel Processing ```python -agent.tools(some_tools) -agent.memory(some_memory_store) -``` - -## 4. Additional Information and Tips +from concurrent.futures import ThreadPoolExecutor -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. +def process_item(item): + # Processing logic + return result -## 5. References and Resources +items = [1, 2, 3, 4, 5] +with ThreadPoolExecutor(max_workers=5) as executor: + results = list(executor.map(process_item, items)) +``` -For further exploration and understanding of AI agents and agent communication, refer to the relevant literature and research on this topic. +--- +## 4. Simplifying Multi-Agent Collaboration --------------------------------------------------- +Simplifying the abstraction of multi-agent collaboration makes it accessible and manageable. -# File: swarms\agents\agent_judge.md +### 4.1 Importance of Simple Abstractions -# AgentJudge +- **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. -A specialized agent for evaluating and judging outputs from other agents or systems. Acts as a quality control mechanism providing objective assessments and feedback. +### 4.2 Standardizing Agent Interfaces -Based on the research paper: **"Agent-as-a-Judge: Evaluate Agents with Agents"** - [arXiv:2410.10934](https://arxiv.org/abs/2410.10934) +Every agent should adhere to a standard interface for consistency. -## Overview +#### 4.2.1 Agent Base Class -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. +```python +from abc import ABC, abstractmethod -Key capabilities: +class BaseAgent(ABC): + @abstractmethod + def run(self, task: str) -> Any: + pass -- **Quality Assessment**: Evaluates correctness, clarity, and completeness of agent outputs + def __call__(self, task: str) -> Any: + return self.run(task) -- **Structured Feedback**: Provides detailed critiques with strengths, weaknesses, and suggestions + @abstractmethod + async def arun(self, task: str) -> Any: + pass +``` -- **Multimodal Support**: Can evaluate text outputs alongside images +#### 4.2.2 Example Agent Implementation -- **Context Building**: Maintains evaluation context across multiple iterations +```python +class DataProcessingAgent(BaseAgent): + def run(self, task: str) -> str: + # Synchronous processing logic + return f"Processed {task}" -- **Batch Processing**: Efficiently processes multiple evaluations + async def arun(self, task: str) -> str: + # Asynchronous processing logic + return f"Processed {task} asynchronously" +``` -## Architecture +#### 4.2.3 Usage Example -```mermaid -graph TD - A[Input Task] --> B[AgentJudge] - B --> C{Evaluation Mode} +```python +agent = DataProcessingAgent() - C -->|step()| D[Single Eval] - C -->|run()| E[Iterative Eval] - C -->|run_batched()| F[Batch Eval] +# Synchronous call +result = agent.run("data_task") +print(result) # Output: Processed data_task - D --> G[Agent Core] - E --> G - F --> G +# Asynchronous call +async def main(): + result = await agent.arun("data_task") + print(result) # Output: Processed data_task asynchronously - G --> H[LLM Model] - H --> I[Quality Analysis] - I --> J[Feedback & Output] +asyncio.run(main()) +``` - subgraph "Feedback Details" - N[Strengths] - O[Weaknesses] - P[Improvements] - Q[Accuracy Check] - end +### 4.3 Mermaid Diagram: Agent Interaction - J --> N - J --> O - J --> P - J --> Q +```mermaid +sequenceDiagram + participant User + participant AgentA + participant AgentB + participant AgentC + 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 ``` -## Class Reference +*Agents collaborating to fulfill a user's task.* -### Constructor +### 4.4 Simplified Collaboration Workflow -```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 -) +```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 | -|-----------|------|---------|-------------| -| `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 | +--- -### Methods +## 5. Bringing It All Together -#### step() +By integrating these principles, we create a cohesive system where agents can efficiently collaborate while maintaining code quality and performance. -```python -step( - task: str = None, - tasks: Optional[List[str]] = None, - img: Optional[str] = None -) -> str -``` +### 5.1 Example: Multi-Agent System -Processes a single task or list of tasks and returns evaluation. +#### 5.1.1 Agent Definitions -| 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 | +```python +class AgentA(BaseAgent): + def run(self, task: str) -> str: + # Agent A processing + return f"AgentA processed {task}" -**Returns:** `str` - Detailed evaluation response + async def arun(self, task: str) -> str: + # Agent A asynchronous processing + return f"AgentA processed {task} asynchronously" -#### run() +class AgentB(BaseAgent): + def run(self, task: str) -> str: + # Agent B processing + return f"AgentB processed {task}" -```python -run( - task: str = None, - tasks: Optional[List[str]] = None, - img: Optional[str] = None -) -> List[str] + async def arun(self, task: str) -> str: + # Agent B asynchronous processing + return f"AgentB processed {task} asynchronously" ``` -Executes evaluation in multiple iterations with context building. - -| 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 | +#### 5.1.2 Orchestrator Agent -**Returns:** `List[str]` - List of evaluation responses from each iteration +```python +class OrchestratorAgent(BaseAgent): + def __init__(self): + self.agent_a = AgentA() + self.agent_b = AgentB() -#### run_batched() + 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}" -```python -run_batched( - tasks: Optional[List[str]] = None, - imgs: Optional[List[str]] = None -) -> List[List[str]] + 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}" ``` -Executes batch evaluation of multiple tasks with corresponding images. +#### 5.1.3 Execution -| 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) | +```python +orchestrator = OrchestratorAgent() -**Returns:** `List[List[str]]` - Evaluation responses for each task +# Synchronous execution +result = orchestrator.run("task1") +print(result) +# Output: Orchestrated results: AgentA processed task1 & AgentB processed task1 -## Examples +# Asynchronous execution +async def main(): + result = await orchestrator.arun("task1") + print(result) + # Output: Orchestrated results: AgentA processed task1 asynchronously & AgentB processed task1 asynchronously -### Basic Usage +asyncio.run(main()) +``` -```python -from swarms import AgentJudge +### 5.2 Mermaid Diagram: Orchestrator Workflow -# Initialize with default settings -judge = AgentJudge() +```mermaid +sequenceDiagram + participant User + participant Orchestrator + participant AgentA + participant AgentB -# Single task evaluation -result = judge.step(task="The capital of France is Paris.") -print(result) + User->>Orchestrator: run(task) + Orchestrator->>AgentA: run(task) + Orchestrator->>AgentB: run(task) + AgentA-->>Orchestrator: result_a + AgentB-->>Orchestrator: result_b + Orchestrator-->>User: Orchestrated results ``` -### Custom Configuration +*Orchestrator coordinating between Agent A and Agent B.* -```python -from swarms import AgentJudge +--- -# Custom judge configuration -judge = AgentJudge( - agent_name="content-evaluator", - model_name="gpt-4", - max_loops=3, - verbose=True -) +## 6. Conclusion -# 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" -] +Our philosophy centers around making multi-agent collaboration as simple and efficient as possible by: -evaluation = judge.step(tasks=outputs) -print(evaluation) -``` +- **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. -### Iterative Evaluation with Context +By adhering to these principles, we create a robust foundation for scalable and maintainable systems that can adapt to evolving technological landscapes. -```python -from swarms import AgentJudge -# Multiple iterations with context building -judge = AgentJudge(max_loops=3) -# 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") -``` +-------------------------------------------------- -### Multimodal Evaluation +# File: swarms\concept\purpose\limits_of_individual_agents.md -```python -from swarms import AgentJudge +# The Limits of Individual Agents -judge = AgentJudge() +![Reliable Agents](docs/assets/img/reliabilitythrough.png) -# Evaluate with image -evaluation = judge.step( - task="Describe what you see in this image", - img="path/to/image.jpg" -) -print(evaluation) -``` -### Batch Processing +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, -```python -from swarms import AgentJudge +- Context Window Limits +- Single Task Execution +- Hallucination +- No collaboration -judge = AgentJudge() -# Batch evaluation with images -tasks = [ - "Describe this chart", - "What's the main trend?", - "Any anomalies?" -] -images = [ - "chart1.png", - "chart2.png", - "chart3.png" -] -# 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}") -``` +#### Context Window Limits -## Reference +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. -```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} -} -``` +#### Hallucination --------------------------------------------------- +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. -# File: swarms\agents\consistency_agent.md +#### Single Task Threading -# Consistency Agent Documentation +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. -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. +#### Lack of Collaboration -## Purpose +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. -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. +# The Elegant yet Simple Solution -## Class: `SelfConsistencyAgent` +- ## Multi-Agent Collaboration -### Initialization +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: -- **`__init__`**: Initializes the `SelfConsistencyAgent` with specified parameters. +#### Overcoming Context Window Limits -#### Arguments +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. -| 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. | +#### Mitigating Hallucination -### Methods +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. -- **`run`**: Generates multiple responses for the given task and aggregates them. - - **Arguments**: - - `task` (`str`): The input prompt. - - `img` (`Optional[str]`, optional): Image input for vision tasks. - - `answer` (`Optional[str]`, optional): Expected answer for validation (if eval=True). - - **Returns**: `Union[str, Dict[str, Any]]` - The aggregated final answer. +#### Enhancing Multitasking Capabilities -- **`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. +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. -- **`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. +#### Facilitating Collaboration and Knowledge Sharing -- **`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. +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. -### Examples +### Conclusion -#### Example 1: Basic Usage +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. -```python -from swarms.agents.consistency_agent import SelfConsistencyAgent +-------------------------------------------------- -# Initialize the agent -agent = SelfConsistencyAgent( - name="Math-Reasoning-Agent", - model_name="gpt-4o-mini", - max_loops=1, - num_samples=5 -) +# File: swarms\concept\purpose\why.md -# Define a task -task = "What is the 40th prime number?" +# The Swarms Framework: Orchestrating Agents for Enterprise Automation -# Run the agent -final_answer = agent.run(task) +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. -# Print the final aggregated answer -print("Final aggregated answer:", final_answer) -``` +Individual agents are plagued by the same issues: short term memory constraints, hallucinations, single task limitations, lack of collaboration, and cost inefficiences. -#### Example 2: Using Custom Majority Voting Prompt +[Learn more here from a list of compiled agent papers](https://github.com/kyegomez/awesome-multi-agent-papers) -```python -from swarms.agents.consistency_agent import SelfConsistencyAgent +## The Purpose of Swarms: Overcoming Agent Limitations -# 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." -) +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: -# Define a task -task = "Explain the theory of relativity in simple terms." +1. Short-Term Memory Constraints +2. Hallucination and Factual Inconsistencies +3. Single-Task Limitations +4. Lack of Collaborative Capabilities +5. Cost Inefficiencies -# Run the agent -final_answer = agent.run(task) +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. -# Print the final aggregated answer -print("Final aggregated answer:", final_answer) -``` +### Limitation 1: Short-Term Memory Constraints -#### Example 3: Evaluation Mode +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. -```python -from swarms.agents.consistency_agent import SelfConsistencyAgent +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. -# Initialize the agent with evaluation mode -agent = SelfConsistencyAgent( - name="Validation-Agent", - model_name="gpt-4o-mini", - num_samples=3, - eval=True -) +### Limitation 2: Hallucination and Factual Inconsistencies -# 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") -``` +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. -#### Example 4: Random Models for Diversity +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. -```python -from swarms.agents.consistency_agent import SelfConsistencyAgent +### Limitation 3: Single-Task Limitations -# 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 -) +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. -# Run the agent -result = agent.run("What are the benefits of renewable energy?") -print("Diverse reasoning result:", result) -``` +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 5: Batch Processing +### Limitation 4: Lack of Collaborative Capabilities -```python -from swarms.agents.consistency_agent import SelfConsistencyAgent +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. -# Initialize the agent -agent = SelfConsistencyAgent( - name="Batch-Processing-Agent", - model_name="gpt-4o-mini", - num_samples=3 -) +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. -# Define multiple tasks -tasks = [ - "What is the capital of France?", - "What is 15 * 23?", - "Explain photosynthesis in simple terms." -] +### Limitation 5: Cost Inefficiencies -# Process all tasks -results = agent.batched_run(tasks) +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. -# Print results -for i, result in enumerate(results): - print(f"Task {i+1} result: {result}") -``` +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. -## Key Features +## The Swarms Framework: A Holistic Approach to Enterprise Automation -### 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: +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. **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 +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. -### 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 +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. -### 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 -## Technical Details +## Benefits of the Swarms Framework -### Concurrent Execution -The agent uses `ThreadPoolExecutor` to generate multiple responses concurrently, improving performance while maintaining independence between reasoning paths. +The adoption of the Swarms Framework in enterprise environments offers numerous benefits: -### 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 +1. Increased Efficiency and Scalability +2. Improved Reliability and Accuracy +3. Adaptability and Continuous Improvement +4. Cost Optimization +5. Enhanced Security and Compliance -### 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 +## Increased Efficiency and Scalability -## Limitations +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. -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 +## Improved Reliability and Accuracy -## Best Practices +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. -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 +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. ---- +## Adaptability and Continuous Improvement +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. --------------------------------------------------- +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. -# File: swarms\agents\create_agents_yaml.md +## Cost Optimization -# Building Agents from a YAML File +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 `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. +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. -### 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. +## Enhanced Security and Compliance ---- +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. -### Parameters +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. -| 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 | +## Real-World Applications and Use Cases ---- +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: -### Return Types +1. Intelligent Process Automation (IPA) +2. Customer Service and Support +3. Fraud Detection and Risk Management +4. Supply Chain Optimization +5. Research and Development -| 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. | +## Intelligent Process Automation (IPA) ---- +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. -### Detailed Return Types +## Customer Service and Support -| 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'` | +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. ---- +## Fraud Detection and Risk Management -### Example Use Cases +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. -1. **Creating Multiple Agents for Financial Analysis** +## Supply Chain Optimization -```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." +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. - - 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?" -``` +## Research and Development -```python -from swarms.structs.agent import Agent -from swarms.structs.swarm_router import SwarmRouter +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. -# Model representing your LLM -def model(prompt): - return f"Processed: {prompt}" +# Conclusion -# Create agents and return them as a list -agents = create_agents_from_yaml(model=model, yaml_file="agents.yaml", return_type="agents") -print(agents) -``` +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. -2. **Running a Swarm of Agents to Solve a Complex Task** +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. -```yaml -agents: - - agent_name: "Legal-Agent" - system_prompt: "Provide legal advice on corporate structuring." - task: "How to incorporate a business as an LLC?" +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. -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 -``` +-------------------------------------------------- -```python -import os +# File: swarms\concept\purpose\why_swarms.md -from dotenv import load_dotenv -from loguru import logger -from swarm_models import OpenAIChat +# Why Swarms? -from swarms.agents.create_agents_from_yaml import ( - create_agents_from_yaml, -) +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. -# Load environment variables -load_dotenv() +### Why Multiple Agents Are Necessary -# Path to your YAML file -yaml_file = "agents_multi_agent.yaml" +#### 1. **Cognitive Diversity** +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. -# Get the OpenAI API key from the environment variable -api_key = os.getenv("GROQ_API_KEY") +#### 2. **Specialization and Expertise** -# 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, -) +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. -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" - ) +#### 3. **Scalability and Flexibility** - logger.info(f"Results from agents: {task_results}") -except Exception as e: - logger.error(f"An error occurred: {e}") +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. -``` +#### 4. **Robustness and Redundancy** -3. **Returning Both Agents and Tasks** +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. -```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." -``` +### Overcoming Expenses with API Bills and Hosting -```python -from swarms.structs.agent import Agent +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: -# Model representing your LLM -def model(prompt): - return f"Processed: {prompt}" +#### 1. **Optimize Agent Efficiency** -# 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) -``` +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. ---- +#### 2. **Use Open Source and Self-Hosted Solutions** +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. -### YAML Schema Overview: +#### 4. **Dynamic Scaling and Load Balancing** -Below is a breakdown of the attributes expected in the YAML configuration file, which governs how agents and swarms are created. +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. -### YAML Attributes Table: +#### 5. **Collaborative Cost-Sharing Models** -| 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?"` | +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. -#### Swarm Architecture (Optional): +#### 6. **Monitor and Analyze Costs** -| 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?"` | +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. ---- -### YAML Schema Example: +### Conclusion -Below is an updated YAML schema that conforms to the function's expectations: +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. -```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 +-------------------------------------------------- - - 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: swarms\concept\swarm_architectures.md -# 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 -``` +# Multi-Agent Architectures -# Diagram -```mermaid -graph TD; - A[Task] -->|Send to| B[Financial-Analysis-Agent] - A -->|Send to| C[Stock-Analysis-Agent] -``` +### What is a Multi-Agent Architecture? ---- +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. -### How to Use `create_agents_from_yaml` Function with YAML: +### How Multi-Agent Architectures Facilitate Communication -- You need to plug in your specific model until we can create a model router that can fetch any model and set specific settings +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: -#### Example Code: -```python -import os +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. -from dotenv import load_dotenv -from loguru import logger -from swarm_models import OpenAIChat +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. -from swarms.agents.create_agents_from_yaml import ( - create_agents_from_yaml, -) +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. -# Load environment variables -load_dotenv() +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. -# Path to your YAML file -yaml_file = "agents.yaml" +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. +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. -# Get the OpenAI API key from the environment variable -api_key = os.getenv("GROQ_API_KEY") +## Core Multi-Agent Architectures -# 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, -) +| **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 | -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" # - ) +--- - logger.info(f"Results from agents: {task_results}") -except Exception as e: - logger.error(f"An error occurred: {e}") - -``` - ---- - -### Error Handling: +## Architectural Patterns -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`. +### Hierarchical Architecture -### 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. +**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. --------------------------------------------------- +**Use Cases:** -# File: swarms\agents\external_party_agents.md +- Complex decision-making processes where tasks can be broken down into subtasks +- Multi-stage workflows such as data processing pipelines or hierarchical reinforcement learning -# **Swarms External Agent Integration** +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/hierarchical_swarm/)** -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. +```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] +``` --- -## **Quick Overview** +### Agent Rearrange -- **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. +**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. -### **Agent Class** +**Use Cases:** +- Adaptive manufacturing lines that reconfigure based on product requirements -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: +- Dynamic sales territory realignment based on market conditions -```python -from swarms import Agent +- Flexible healthcare staffing that adjusts to patient needs -class ExternalAgent(Agent): - def run(self, task: str) -> str: - # Implement logic to run external agent - pass - 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) +**[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] ``` --- -## **Griptape Agent Integration Example** +### Concurrent Architecture -In this example, we will create a **Griptape** agent by inheriting from the Swarms `Agent` class and implementing the `run` method. +**Overview:** +Multiple agents operate independently and simultaneously on different tasks. Each agent works on its own task without dependencies on the others. -### **Griptape Integration Steps**: +**Use Cases:** +- Tasks that can be processed independently, such as parallel data analysis -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. +- Large-scale simulations where multiple scenarios are run simultaneously -## **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, -) +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/concurrentworkflow/)** -# 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, - ) +```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] +``` - # 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) +--- +### Sequential Architecture -# Example usage: -griptape_swarms_agent = GriptapeSwarmsAgent() -output = griptape_swarms_agent.run("https://griptape.ai, griptape.txt") -print(output) -``` +**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. -### **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. +**Use Cases:** +- Workflows where each step depends on the previous one, such as assembly lines or sequential data processing -## **Additional Features**: -You can enhance your external agents with additional features such as: +- Scenarios requiring strict order of operations -- **Saving outputs** to JSON, databases, or logs. -- **Handling errors** and retry mechanisms for robustness. +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/)** -- **Custom logging** with tools like **Loguru** for extensive debugging. +```mermaid +graph TD + A[Input] --> B[Agent 1] + B --> C[Agent 2] + C --> D[Agent 3] + D --> E[Agent 4] + E --> F[Final Output] +``` --- -## **Langchain Agent Integration Example** - -Next, we demonstrate how to integrate a **Langchain** agent with **Swarms** by following similar steps. +### Round Robin Architecture -### **Langchain Integration Steps**: +**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. -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. +**Use Cases:** -## **Langchain Example Code**: +- Load balancing in distributed systems -```python -from swarms import Agent as SwarmsAgent -from langchain import LLMChain -from langchain.llms import OpenAI -from langchain.prompts import PromptTemplate +- Scenarios requiring fair distribution of tasks to avoid overloading any single agent -# 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) - # 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 +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/round_robin_swarm/)** -# Example usage: -langchain_swarms_agent = LangchainSwarmsAgent() -output = langchain_swarms_agent.run("What is the capital of France?") -print(output) +```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 ``` -### **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. +--- +### SpreadSheet Architecture -### Additional Examples from other providers +**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. +**Use Cases:** +- Multi-threaded execution: Execute agents on multiple threads -### 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 +- Save agent outputs into CSV file - # 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) +- One place to analyze agent outputs - 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() - # Example usage: - openai_agent = OpenAIFunctionAgent() - output = openai_agent.run("summarize, Provide a short summary of this text...") - print(output) - ``` +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/spreadsheet_swarm/)** -### 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**. +```mermaid +graph TD + A[Initialize SpreadSheet System] --> B[Initialize Agents] + B --> C[Load Task Queue] + C --> D[Distribute Tasks] - ## Example Integration: - ```python - from swarms import Agent as SwarmsAgent - from rasa.core.agent import Agent as RasaAgent - from rasa.core.interpreter import RasaNLUInterpreter + subgraph Agent_Pool[Agent Pool] + D --> E1[Agent 1] + D --> E2[Agent 2] + D --> E3[Agent 3] + D --> E4[Agent N] + end - # 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) + E1 --> F1[Process Task] + E2 --> F2[Process Task] + E3 --> F3[Process Task] + E4 --> F4[Process Task] - 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." + F1 --> G[Collect Results] + F2 --> G + F3 --> G + F4 --> G - # Example usage: - rasa_swarms_agent = RasaSwarmsAgent("path/to/rasa_model") - output = rasa_swarms_agent.run("Hello, how can I get a refund?") - print(output) - ``` + G --> H[Save to CSV] + H --> I[Generate Analytics] +``` -### 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. +--- - ## Example Integration: - ```python - from swarms import Agent as SwarmsAgent - from transformers import pipeline +### Mixture of Agents - # 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) +**Overview:** +Combines multiple agents with different capabilities and expertise to solve complex problems that require diverse skill sets. - 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"] +**Use Cases:** +- Financial forecasting requiring different analytical approaches - # Example usage: - hf_swarms_agent = HuggingFaceSwarmsAgent("gpt2") - output = hf_swarms_agent.run("Once upon a time in a land far, far away...") - print(output) - ``` +- Complex problem-solving needing diverse expertise -### 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 +- Multi-domain analysis tasks - # Custom AutoGPT Agent - class AutoGPTSwarmsAgent(SwarmsAgent): - def __init__(self, config, *args, **kwargs): - # Initialize AutoGPT with configuration - self.agent = AutoGPT(config) - super().__init__(*args, **kwargs) - def run(self, task: str) -> str: - # Execute task recursively using AutoGPT - result = self.agent.run(task) - return result +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/moa/)** - # Example usage: - autogpt_swarms_agent = AutoGPTSwarmsAgent({"goal": "Solve world hunger"}) - output = autogpt_swarms_agent.run("Develop a plan to solve world hunger.") - print(output) - ``` +```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] -### 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 + C --> F[Response 1] + D --> G[Response 2] + E --> H[Response N] - # 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) + F --> I[Layer 2: Aggregator Agent] + G --> I + H --> I + I --> J[Synthesized Output] +``` - 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 +--- - # 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) - ``` +### Graph Workflow -### 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 +**Overview:** +Organizes agents in a directed acyclic graph (DAG) format, enabling complex dependencies and parallel execution paths. - # Custom ChatterBot Agent - class ChatterBotSwarmsAgent(SwarmsAgent): - def __init__(self, name: str, *args, **kwargs): - # Initialize ChatterBot - self.agent = ChatBot(name) - super().__init__(*args, **kwargs) +**Use Cases:** +- AI-driven software development pipelines - def run(self, task: str) -> str: - # Get a response from ChatterBot based on user input - response = self.agent.get_response(task) - return str(response) +- Complex project management with dependencies - # Example usage: - chatterbot_swarms_agent = ChatterBotSwarmsAgent("Assistant") - output = chatterbot_swarms_agent.run("What is the capital of Italy?") - print(output) - ``` +- Multi-step data processing workflows -### 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 - # 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 +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/graph_workflow/)** - # Example usage: - api_swarms_agent = APIAgent() - output = api_swarms_agent.run("https://api.example.com/search, python") - print(output) - ``` +```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] +``` --- -### **Summary of Integrations**: - -- **Griptape**: Integrate with tools for web scraping, summarization, etc. - -- **Langchain**: Use powerful language model orchestration. - -- **OpenAI Function Calling**: Directly run OpenAI API-based agents. +### Group Chat -- **Rasa**: Build and integrate conversational agents. +**Overview:** +Enables agents to engage in chat-like interactions to reach decisions collaboratively through discussion and consensus building. -- **Hugging Face**: Leverage transformer models. +**Use Cases:** +- Real-time collaborative decision-making -- **AutoGPT/BabyAGI**: Recursive, autonomous task execution. +- Contract negotiations -- **DialogFlow**: Integrate conversational flows for voice/chat-based systems. +- Brainstorming sessions -- **ChatterBot**: Machine-learning conversational agents. -- **Custom APIs**: Leverage external APIs as agents for custom workflows. +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/group_chat/)** +```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] +``` --- +### Interactive Group Chat -## **Conclusion**: - -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. - -For more examples and use cases, please refer to the official Swarms documentation site. - +**Overview:** +Enhanced version of Group Chat with dynamic speaker selection, priority-based communication, and advanced interaction patterns. +**Use Cases:** +- Advanced collaborative decision-making --------------------------------------------------- +- Dynamic team coordination -# File: swarms\agents\gkp_agent.md +- Adaptive conversation management -# Generated Knowledge Prompting (GKP) Agent -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. - -## Overview - -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 - -## Architecture +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/interactive_groupchat/)** ```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] + A[Conversation Manager] --> B[Speaker Selection Logic] + B --> C[Priority Speaker] + B --> D[Random Speaker] + B --> E[Round Robin Speaker] - subgraph "Knowledge Generation" - B - C - end + C --> F[Active Discussion] + D --> F + E --> F - subgraph "Reasoning" - D - E - end + F --> G[Agent Pool] + G --> H[Agent 1] + G --> I[Agent 2] + G --> J[Agent N] - subgraph "Coordination" - F - G - end + H --> K[Dynamic Response] + I --> K + J --> K + K --> A ``` -## Use Cases +--- + +### Agent Registry + +**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. + +**Use Cases:** +- Dynamic agent management in large-scale systems + +- Evolving recommendation engines that adapt agent selection + +- Service discovery in distributed agent systems + + +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/agent_registry/)** ```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] +graph TD + A[Agent Registration] --> B[Registry Database] + B --> C[Agent Metadata] + C --> D[Capabilities] + C --> E[Performance Metrics] + C --> F[Availability Status] - D --> D1[Technical Analysis] - D --> D2[Decision Making] + G[Task Request] --> H[Registry Query Engine] + H --> I[Agent Discovery] + I --> J[Capability Matching] + J --> K[Agent Selection] - E --> E1[Chain of Thought] - E --> E2[Multi-perspective Analysis] + K --> L[Agent Invocation] + L --> M[Task Execution] + M --> N[Performance Tracking] + N --> O[Registry Update] + O --> B ``` -## API Reference +--- -### GKPAgent +### Router Architecture -The main agent class that orchestrates the knowledge generation and reasoning process. +**Overview:** +Intelligently routes tasks to the most appropriate agents or architectures based on task requirements and agent capabilities. -#### Initialization Parameters +**Use Cases:** +- Dynamic task routing -| 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 | +- Adaptive architecture selection -#### Methods +- Optimized agent allocation -| 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]]] | -### KnowledgeGenerator +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/)** -Component responsible for generating relevant knowledge for queries. +```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] +``` -#### Initialization Parameters +--- -| 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 | +### Heavy Architecture -#### Methods +**Overview:** +High-performance architecture designed for handling intensive computational tasks with multiple agents working on resource-heavy operations. -| Method | Description | Parameters | Returns | -|--------|-------------|------------|---------| -| generate_knowledge(query: str) | Generate relevant knowledge for a query | query: str | List[str] of generated knowledge statements | +**Use Cases:** +- Large-scale data processing -### Reasoner +- Intensive computational workflows -Component that uses generated knowledge to reason about and answer queries. +- High-throughput task execution -#### Initialization Parameters -| 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 | +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/heavy_swarm/)** -#### Methods +```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] +``` -| 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 +### Deep Research Architecture -```python -from swarms.agents.gkp_agent import GKPAgent +**Overview:** +Specialized architecture for conducting comprehensive research tasks across multiple domains with iterative refinement and cross-validation. -# 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 -) +**Use Cases:** +- Academic research projects -# Example queries -queries = [ - "What are the implications of quantum entanglement on information theory?", -] +- Market analysis and intelligence -# Run the agent -results = agent.run(queries) +- Comprehensive data investigation -# Print results -for i, result in enumerate(results): - print(f"\nQuery {i+1}: {queries[i]}") - print(f"Answer: {result}") + +**[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] ``` -## Best Practices +--- -1. **Knowledge Generation** - - Set appropriate number of knowledge items based on query complexity - - Monitor knowledge quality and relevance - - Adjust model parameters for optimal performance +### De-Hallucination Architecture -2. **Reasoning Process** - - Ensure diverse reasoning paths for complex queries - - Validate confidence levels - - Consider multiple perspectives +**Overview:** +Architecture specifically designed to reduce and eliminate hallucinations in AI outputs through consensus mechanisms and fact-checking protocols. -3. **Coordination** - - Review coordination logic for complex scenarios - - Validate final answers against source knowledge - - Monitor processing time and optimize if needed +**Use Cases:** +- Fact-checking and verification -## Performance Considerations +- Content validation -- 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 +- Reliable information generation -## Error Handling -The agent includes robust error handling for: -- Invalid queries -- Failed knowledge generation -- Reasoning errors -- Coordination failures +```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 +``` +--- --------------------------------------------------- +### Council as Judge -# File: swarms\agents\index.md +**Overview:** +Multiple agents act as a council to evaluate, judge, and validate outputs or decisions through collaborative assessment. -# Agents Introduction +**Use Cases:** +- Quality assessment and validation -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. +- Decision validation processes -## Table of Contents +- Peer review systems -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) -## Prerequisites & Installation +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/council_of_judges/)** -### System Requirements +```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] +``` -- Python 3.7+ +--- -- OpenAI API key (for GPT models) +### MALT Architecture -- Anthropic API key (for Claude models) +**Overview:** +Specialized architecture for complex language processing tasks that require coordination between multiple language-focused agents. -### Installation +**Use Cases:** +- Natural language processing pipelines -```bash -pip3 install -U swarms -``` +- Translation and localization -### Environment Setup +- Content generation and editing -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" -``` +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/malt/)** -## Basic Agent Configuration +```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] +``` -### Core Agent Structure +--- -The Agent class provides a comprehensive set of parameters for customization: +### Majority Voting -```python -from swarms import Agent +**Overview:** +Agents vote on decisions with the majority determining the final outcome, providing democratic decision-making and error reduction through consensus. -# Basic agent initialization -agent = Agent( - 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, - max_tokens=4096, - temperature=0.7, - output_type="str", - safety_prompt_on=True -) -``` +**Use Cases:** +- Democratic decision-making processes -### Key Configuration Parameters +- Consensus building -| 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 | +- Error reduction through voting -### Simple Example -```python -from swarms import Agent +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/majorityvoting/)** -# 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 +```mermaid +graph TD + A[Decision Request] --> B[Voting Coordinator] + B --> C[Voting Pool] - Provide clear, actionable advice while considering risk tolerance.""", - model_name="gpt-4o-mini", - max_loops=1, - temperature=0.3, - output_type="str" -) - -# Run the agent -response = financial_agent.run("What are the best investment strategies for a 30-year-old?") -print(response) + 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] ``` -## Multi-Modal Capabilities +--- -### Image Processing +### Auto-Builder -The Agent class supports comprehensive image analysis through vision-enabled models: +**Overview:** +Automatically constructs and configures multi-agent systems based on requirements, enabling dynamic system creation and adaptation. -```python -from swarms import Agent +**Use Cases:** +- Dynamic system creation -# 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" -) +- Adaptive architectures -# Analyze a single image -response = vision_agent.run( - task="Analyze this image for quality control purposes", - img="path/to/image.jpg" -) +- Rapid prototyping of multi-agent systems -# 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 -) -``` -### Supported Image Formats +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/auto_swarm_builder/)** -| 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 | +```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] +``` -### 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") +### Hybrid Hierarchical Cluster -# 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, - tools=[security_analysis] -) +**Overview:** +Combines hierarchical and peer-to-peer communication patterns for complex workflows that require both centralized coordination and distributed collaboration. -# Analyze factory image -response = quality_agent.run( - task="Analyze this factory image for safety and quality issues", - img="factory_floor.jpg" -) -``` +**Use Cases:** +- Complex enterprise workflows -## Tool Integration +- Multi-department coordination -### Creating Custom Tools +- Hybrid organizational structures -Tools are Python functions that extend your agent's capabilities: -```python -import json -import requests -from typing import Optional, Dict, Any +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/hhcs/)** -def get_weather_data(city: str, country: Optional[str] = None) -> str: - """ - Get current weather data for a specified city. +```mermaid +graph TD + A[Central Coordinator] --> B[Cluster 1 Leader] + A --> C[Cluster 2 Leader] + A --> D[Cluster 3 Leader] - Args: - city (str): The city name - country (Optional[str]): Country code (e.g., 'US', 'UK') + B --> E[Peer Agent 1.1] + B --> F[Peer Agent 1.2] + E <--> F - Returns: - str: JSON formatted weather data + C --> G[Peer Agent 2.1] + C --> H[Peer Agent 2.2] + G <--> H - 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) + D --> I[Peer Agent 3.1] + D --> J[Peer Agent 3.2] + I <--> J - except Exception as e: - return json.dumps({"error": f"Weather API error: {str(e)}"}) + E --> K[Inter-Cluster Communication] + G --> K + I --> K + K --> A +``` -def calculate_portfolio_metrics(prices: list, weights: list) -> str: - """ - Calculate portfolio performance metrics. +--- + +### Election Architecture + +**Overview:** +Agents participate in democratic voting processes to select leaders or make collective decisions. + +**Use Cases:** +- Democratic governance + +- Consensus building + +- Leadership selection + + +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/election_swarm/)** + +```mermaid +graph TD + A[Voting Process] --> B[Candidate Agents] + B --> C[Voting Mechanism] - Args: - prices (list): List of asset prices - weights (list): List of portfolio weights + C --> D[Voter Agent 1] + C --> E[Voter Agent 2] + C --> F[Voter Agent N] - 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) + D --> G[Vote Collection] + E --> G + F --> G - except Exception as e: - return json.dumps({"error": f"Calculation error: {str(e)}"}) + G --> H[Vote Counting] + H --> I[Majority Check] + I --> J{Majority?} + J -->|Yes| K[Leader Selected] + J -->|No| L[Continue Voting] + L --> B ``` -### Tool Integration Example +--- -```python -from swarms import Agent -# 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] -) +--- -# 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]?" -) -``` +### Dynamic Conversational Architecture -### API Integration Tools +**Overview:** +Adaptive conversation management with dynamic agent selection and interaction patterns. -```python -import requests -import json -from typing import List +**Use Cases:** +- Adaptive chatbots -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)}"}) +- Dynamic customer service -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)}"}) +- Contextual conversations -# 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] -) -# Analyze crypto market -response = crypto_agent.run("Analyze the current Bitcoin price and show me the top 5 cryptocurrencies") +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/dynamic_conversational_swarm/)** + +```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 ``` -## Structured Outputs +--- -### Function Schema Definition +### Tree Architecture -Define structured outputs using OpenAI's function calling format: +**Overview:** +Hierarchical tree structure for organizing agents in parent-child relationships. -```python -from swarms import Agent +**Use Cases:** +- Organizational hierarchies -# 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"] - } - } -} +- Decision trees -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"] - } - } -} +- Taxonomic classification -# 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] -) -# Generate structured analysis -response = structured_agent.run( - "Analyze Apple stock (AAPL) performance with comprehensive analysis for the last 3 months" -) +**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/tree_swarm/)** + +```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] ``` -## Advanced Features -### Dynamic Temperature Control +-------------------------------------------------- -```python -from swarms import Agent +# File: swarms\concept\swarm_ecosystem.md -# 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" -) -``` +# Understanding the Swarms Ecosystem -### Output Type Configurations +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 -# Different output type examples -json_agent = Agent( - agent_name="JSON-Agent", - system_prompt="Always respond in valid JSON format", - output_type="json" -) +#### 1. **Swarms Framework** -streaming_agent = Agent( - agent_name="Streaming-Agent", - system_prompt="Provide detailed streaming responses", - output_type="str-all-except-first" -) +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. -final_only_agent = Agent( - agent_name="Final-Only-Agent", - system_prompt="Provide only the final result", - output_type="final" -) +```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] ``` -### Safety and Content Filtering +#### 2. **Swarms-Cloud** -```python -from swarms import Agent +[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. -# 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 -) +```mermaid +graph TD; + SC[Swarms-Cloud] --> Uptime[99% Uptime] + SC --> Scale[Infinite Scalability] + SC --> Healing[Self-Healing] ``` -## Best Practices +#### 3. **Swarms-Models** -### Error Handling and Robustness +[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. -```python -import logging -from swarms import Agent +```mermaid +graph TD; + SM[Swarms-Models] --> OpenAI[OpenAI API] + SM --> Anthropic[Anthropic API] + SM --> Ollama[Ollama API] +``` -# Configure logging -logging.basicConfig(level=logging.INFO) -logger = logging.getLogger(__name__) +#### 4. **AgentParse** -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 +[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. -# Example usage -try: - result = robust_agent_execution(agent, "Analyze market trends") - print(result) -except Exception as e: - print(f"Agent execution failed: {e}") +```mermaid +graph TD; + AP[AgentParse] --> JSON[JSON Parsing] + AP --> YAML[YAML Parsing] + AP --> CSV[CSV Parsing] + AP --> Pydantic[Pydantic Model Parsing] ``` -### Performance Optimization +#### 5. **Swarms-Platform** -```python -from swarms import Agent -import time +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. -# 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" -) +```mermaid +graph TD; + SP[Swarms-Platform] --> Discover[Discover Agents] + SP --> Buy[Buy Agents] + SP --> Sell[Sell Agents] +``` -# 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 +#### Extending the Ecosystem: **Swarms Core**, **JS**, and More + +In addition to the core components, the Swarms Ecosystem offers several other powerful packages: + +- **[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. + +```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] ``` -## Complete Examples +### Conclusion -### Multi-Modal Quality Control System +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. -```python -from swarms import Agent -from swarms.prompts.logistics import Quality_Control_Agent_Prompt +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. -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" -# 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} - - You are an advanced quality control system with the following capabilities: - - 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 - - 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 - - Always provide specific, actionable feedback. - """, - model_name="gpt-4o-mini", - multi_modal=True, - max_loops=1, - tools=[security_analysis, quality_assessment], - output_type="str" -) +-------------------------------------------------- -# Process factory images -factory_images = ["factory_floor.jpg", "assembly_line.jpg", "safety_equipment.jpg"] +# File: swarms\concept\vision.md -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) -``` +# Swarms – The Ultimate Multi-Agent LLM Framework for Developers -### Advanced Financial Analysis Agent +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. -```python -from swarms import Agent -import json -import requests +### 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. -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) +--- -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)}"}) +### Code Examples -# 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"] - } - } -} +#### 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. -# 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.""", +```python +from swarms.structs.agent import Agent +from swarms.prompts.finance_agent_sys_prompt import FINANCIAL_AGENT_SYS_PROMPT + +# 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, - tools=[get_market_data, calculate_risk_metrics], - tools_list_dictionary=[financial_analysis_schema], - output_type="json" + 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, ) -# Comprehensive financial analysis -analysis_response = financial_analyst.run( - "Perform a comprehensive analysis of Apple Inc. (AAPL) including technical and fundamental analysis with structured recommendations" +# 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?" ) -print(json.dumps(json.loads(analysis_response), indent=2)) +# Output the result +print(out) ``` -### Multi-Agent Collaboration System +#### 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 -import json +from swarms.structs.agent import Agent +from swarms.structs.rearrange import AgentRearrange -# 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", +# 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, - temperature=0.3 + dashboard=False, + streaming_on=False, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="director.json", ) -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", +# 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, - temperature=0.5 + dashboard=False, + streaming_on=False, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="worker1.json", ) -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", +# 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, - temperature=0.4 + dashboard=False, + streaming_on=False, + verbose=True, + stopping_token="", + state_save_file_type="json", + saved_state_path="worker2.json", ) -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 - } +# Orchestrate the agents in sequence +agents = [director, worker1, worker2] +flow = "Director -> Worker1 -> Worker2" +agent_system = AgentRearrange(agents=agents, flow=flow) -# Example: Collaborative investment analysis -investment_analysis = collaborative_analysis("renewable energy sector investment opportunities") +# 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) +``` -for phase, results in investment_analysis.items(): - print(f"\n=== {phase.upper()} PHASE ===") - print(results) +#### 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] ``` -## Support and Resources +In this diagram: +- The **Director** agent assigns tasks. +- **Worker 1** generates a transcript for a YouTube video. +- **Worker 2** summarizes the transcript. -Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights! +#### 2. Sequential Agent Flow: +This diagram showcases a sequential agent setup where one agent completes its task before the next agent starts its task. -| 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) | +```mermaid +flowchart TD + A[Director] --> B[Worker 1: Generate Transcript] + B --> C[Worker 2: Summarize Transcript] + C --> D[Worker 3: Finalize] +``` -### Getting Help +In this setup: -If you encounter issues or need assistance: +- The **Director** agent assigns tasks to **Worker 1**, which generates a transcript for a YouTube video. -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 +- **Worker 1** completes its task before **Worker 2** starts summarizing the transcript. -### Contributing +- **Worker 2** completes its task before **Worker 3** finalizes the process. -We welcome contributions! Here's how to get involved: +### Why Developers Should Choose Swarms: -- **Report Bugs**: Help us improve by reporting issues +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. -- **Suggest Features**: Share your ideas for new capabilities +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. -- **Submit Code**: Contribute improvements and new features +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. -- **Improve Documentation**: Help make our docs better +### 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. -- **Share Examples**: Show how you're using Swarms in your projects +-------------------------------------------------- ---- +# File: swarms\concept\why.md -*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.* +**Maximizing Enterprise Automation: Overcoming the Limitations of Individual AI Agents Through Multi-Agent Collaboration** --------------------------------------------------- -# File: swarms\agents\iterative_agent.md +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. -# Iterative Reflective Expansion (IRE) Algorithm Documentation +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. -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. +--- +### Part 1: The Limitations of Individual AI Agents -## Architecture +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. -```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 ✅"] +#### 1. Context Window Limits -``` +**Explanation** ---- +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. -## Workflow +**Impact on Enterprises** -1. Generate initial hypotheses -2. Simulate paths -3. Reflect on errors -4. Revise paths -5. Select promising paths -6. Synthesize solution +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. -## Class: IterativeReflectiveExpansion -### Arguments +```mermaid +graph LR + subgraph "Context Window Limit" + Input[Large Document] + Agent[AI Agent] + Output[Partial Understanding] + Input -- Truncated Data --> Agent + Agent -- Generates --> Output + end +``` -| 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. | +*An AI agent processes only a portion of a large document due to context window limits, resulting in partial understanding.* -### Methods +#### 2. Hallucination -| 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. | +**Explanation** -## Use-Cases +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. -### Example 1: Solving a Mathematical Problem +**Impact on Enterprises** -```python -from swarms import IterativeReflectiveExpansion +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. -agent = IterativeReflectiveExpansion( - max_iterations=3, -) -agent.run("What is the 40th prime number?") +```mermaid +graph TD + Input[Ambiguous Data] + Agent[AI Agent] + Output[Incorrect Information] + Input --> Agent + Agent --> Output ``` -## Conclusion +*An AI agent generates incorrect information (hallucination) when processing ambiguous data.* -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. +#### 3. Single Task Execution +**Explanation** --------------------------------------------------- +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. -# File: swarms\agents\message.md +**Impact on Enterprises** -# The Module/Class Name: Message +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. -In the swarms.agents framework, the class `Message` is used to represent a message with timestamp and optional metadata. -## Overview and Introduction +```mermaid +graph LR + TaskA[Task A] --> AgentA[Agent A] + TaskB[Task B] --> AgentB[Agent B] + AgentA --> OutputA[Result A] + AgentB --> OutputB[Result B] +``` -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. +*Separate agents handle different tasks independently, lacking integration.* -## Class Definition +#### 4. Lack of Collaboration -### Constructor: `__init__` +**Explanation** -The constructor of the `Message` class takes three parameters: +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. -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. +**Impact on Enterprises** -### Methods +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. -1. `__repr__(self)`: Returns a string representation of the `Message` object, including the timestamp, sender, and content. -```python -class Message: - """ - Represents a message with timestamp and optional metadata. +```mermaid +graph LR + Agent1[Agent 1] + Agent2[Agent 2] + Agent3[Agent 3] + Agent1 -->|No Communication| Agent2 + Agent2 -->|No Communication| Agent3 +``` - Usage - -------------- - mes = Message( - sender = "Kye", - content = "message" - ) +*Agents operate without collaboration, resulting in isolated efforts.* - print(mes) - """ +#### 5. Lack of Accuracy - def __init__(self, sender, content, metadata=None): - self.timestamp = datetime.datetime.now() - self.sender = sender - self.content = content - self.metadata = metadata or {} +**Explanation** - def __repr__(self): - """ - __repr__ represents the string representation of the Message object. +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. - Returns: - (str) A string containing the timestamp, sender, and content of the message. - """ - return f"{self.timestamp} - {self.sender}: {self.content}" +**Impact on Enterprises** + +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. + + +```mermaid +graph TD + Input[Complex Data] + Agent[AI Agent] + Output[Inaccurate Result] + Input --> Agent + Agent --> Output ``` -## Functionality and Usage +*An AI agent produces an inaccurate result when handling complex data.* -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. +#### 6. Slow Processing Speed -### Usage Example 1 +**Explanation** -Creating a `Message` object and displaying its string representation. +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. -```python -mes = Message(sender="Kye", content="Hello! How are you?") +**Impact on Enterprises** -print(mes) -``` +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. -Output: -``` -2023-09-20 13:45:00 - Kye: Hello! How are you? + +```mermaid +graph TD + Input[Data] + Agent[AI Agent] + Delay[Processing Delay] + Output[Delayed Response] + Input --> Agent + Agent --> Delay + Delay --> Output ``` -### Usage Example 2 +*An AI agent's slow processing leads to delayed responses.* -Creating a `Message` object with metadata. +--- -```python -metadata = {"priority": "high", "category": "urgent"} -mes_with_metadata = Message( - sender="Alice", content="Important update", metadata=metadata -) +### Part 2: Overcoming Limitations Through Multi-Agent Collaboration -print(mes_with_metadata) -``` +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. -Output: -``` -2023-09-20 13:46:00 - Alice: Important update -``` +#### 1. Extending Context Window Through Distributed Processing -### Usage Example 3 +**Solution** -Creating a `Message` object without providing metadata. +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. -```python -mes_no_metadata = Message(sender="Bob", content="Reminder: Meeting at 2PM") +**Implementation in Enterprises** -print(mes_no_metadata) -``` +- **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. -Output: + +```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 ``` -2023-09-20 13:47:00 - Bob: Reminder: Meeting at 2PM + +*Multiple agents process segments of a large document, and results are aggregated.* + +#### 2. Reducing Hallucination Through Cross-Verification + +**Solution** + +Agents can verify each other's outputs by cross-referencing information and flagging inconsistencies. Implementing consensus mechanisms ensures that only accurate information is accepted. + +**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. + + +```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 ``` -## Additional Information and Tips +*Agents verify outputs through cross-verification and consensus.* -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. +#### 3. Enhancing Multi-Tasking Through Specialized Agents -## References and Resources +**Solution** -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. +Deploy specialized agents for different tasks and enable them to work concurrently. An orchestrator agent manages task allocation and workflow integration. +**Implementation in Enterprises** --------------------------------------------------- +- **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. -# File: swarms\agents\new_agent.md -# How to Create Good Agents +```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 +``` -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. +*Specialized agents handle different tasks under the management of an orchestrator agent.* -## Overview +#### 4. Facilitating Collaboration Through Communication Protocols -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: +**Solution** -- 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. +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. -By following these guidelines, you can create agents that integrate well with broader systems and exhibit high reliability in real-world applications. +**Implementation in Enterprises** ---- +- **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. -## Creating a Custom Agent -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: +```mermaid +graph LR + Agent1[Agent 1] + Agent2[Agent 2] + Agent3[Agent 3] + Agent1 <--> Agent2 + Agent2 <--> Agent3 + Agent3 <--> Agent1 + Output[Collaborative Outcome] +``` -```python -from typing import Callable, Any -from swarms import Agent +*Agents communicate and collaborate to achieve a common goal.* -class MyNewAgent(Agent): - """ - A custom agent class for specialized tasks. +#### 5. Improving Accuracy Through Ensemble Learning - 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. - """ +**Solution** - def __init__(self, name: str, system_prompt: str, model_name: str = None, description: str, llm: Callable = None): - """ - Initialize the custom agent. +Use ensemble methods where multiple agents provide predictions or analyses, and a meta-agent combines these to produce a more accurate result. - 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 +**Implementation in Enterprises** - def run(self, task: str, img: str, *args: Any, **kwargs: Any) -> Any: - """ - Execute the task assigned to the agent. +- **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. - 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. - """ - # Your custom logic - ... +```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 design ensures a seamless extension of functionality while maintaining clear and maintainable code. +*Meta-agent combines outputs from multiple agents to improve accuracy.* ---- +#### 6. Increasing Processing Speed Through Parallelization -## Key Considerations +**Solution** -### 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. +By distributing workloads among multiple agents operating in parallel, processing times are significantly reduced, enabling real-time responses. -### 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. +**Implementation in Enterprises** -### 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. +- **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. -### 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. -### 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. +```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 +``` -### 6. **Scalability Considerations** -Ensure your agent design can scale to accommodate increased complexity or a larger number of tasks without compromising performance. +*Parallel processing by agents leads to faster completion times.* --- -## Example Usage +### Part 3: Tailoring Multi-Agent Systems for Enterprise Automation at Scale -Here is an example of how to use your custom agent effectively: +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. -```python -# Example LLM callable -class MockLLM: - """ - A mock language model class for simulating LLM behavior. +#### 1. Identifying Automation Opportunities - Methods: - run(task: str, img: str, *args: Any, **kwargs: Any) -> str: - Processes the task and image input to return a simulated response. - """ +Enterprises should start by identifying processes and tasks that are suitable for automation through multi-agent systems. Prioritize areas where: - def run(self, task: str, img: str, *args: Any, **kwargs: Any) -> str: - return f"Processed task '{task}' with image '{img}'" +- **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. -# 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 -) +#### 2. Designing the Multi-Agent Architecture -# Run a task -result = agent.run(task="Analyze content", img="path/to/image.jpg") -print(result) -``` +Develop a robust architecture that defines how agents will interact, communicate, and collaborate. Key components include: -This example showcases the practical application of the `MyNewAgent` class and highlights its extensibility. +- **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. +#### 3. Ensuring Data Security and Compliance -## Production-Grade Example with **Griptape Agent Integration Example** +Data security is paramount when agents handle sensitive enterprise information. Implement measures such as: -In this example, we will create a **Griptape** agent by inheriting from the Swarms `Agent` class and implementing the `run` method. +- **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). -### **Griptape Integration Steps**: +#### 4. Monitoring and Performance Management -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. +Establish monitoring tools to track agent performance, system health, and outcomes. Key metrics may include: -## **Griptape Example Code**: +- **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. -```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, -) +#### 5. Scaling Strategies -# 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, - ) +Develop strategies for scaling the system as enterprise needs grow, including: - # 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) +- **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. +#### 6. Continuous Improvement -# Example usage: -griptape_swarms_agent = GriptapeSwarmsAgent() -output = griptape_swarms_agent.run("https://griptape.ai, griptape.txt") -print(output) -``` +Implement feedback loops for ongoing enhancement of the multi-agent system: +- **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. --- -## Best Practices +### Part 4: Case Studies and Real-World Applications -1. **Test Extensively:** - Validate your agent with various task inputs to ensure it performs as expected under different conditions. +To illustrate the practical benefits of multi-agent collaboration in enterprise automation, let's explore several real-world examples. -2. **Follow the Single Responsibility Principle:** - Design each agent to focus on a specific task or role, ensuring clarity and modularity in implementation. +#### Case Study 1: Financial Services Automation -3. **Log Actions:** - Include detailed logging within the `run` method to capture key actions, inputs, and results for debugging and monitoring. +**Challenge** -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. +A financial institution needs to process large volumes of loan applications, requiring data verification, risk assessment, compliance checks, and decision-making. -5. **Iterate and Refactor:** - Continuously improve your agents based on feedback, performance evaluations, and new requirements to maintain relevance and functionality. +**Solution** ---- +- **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. -## Conclusion +- **Collaboration:** + - Agents communicate to share data and findings. + - The Decision Agent coordinates the workflow. -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. +**Outcome** +- **Increased Processing Speed:** Applications are processed in minutes instead of days. +- **Improved Accuracy:** Cross-verification reduces errors. +- **Scalability:** System handles fluctuating application volumes efficiently. +#### Case Study 2: Manufacturing Supply Chain Optimization --------------------------------------------------- +**Challenge** -# File: swarms\agents\openai_assistant.md +A manufacturing company wants to optimize its supply chain to reduce costs and improve delivery times. -# OpenAI Assistant +**Solution** -The OpenAI Assistant class provides a wrapper around OpenAI's Assistants API, integrating it with the swarms framework. +- **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. -## Overview +- **Collaboration:** + - Agents share data on demand forecasts and inventory levels. + - Logistics Agent adjusts plans based on input from other agents. -The `OpenAIAssistant` class allows you to create and interact with OpenAI Assistants, providing a simple interface for: +**Outcome** -- 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 +- **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. -## Insstallation +#### Case Study 3: Healthcare Patient Management -```bash -pip install swarms -``` -## Basic Usage +**Challenge** -```python +A hospital aims to improve patient care coordination, managing appointments, medical records, billing, and treatment plans. -from swarms import OpenAIAssistant +**Solution** -#Create an assistant -assistant = OpenAIAssistant( - name="Math Tutor", - instructions="You are a helpful math tutor.", - model="gpt-4o", - tools=[{"type": "code_interpreter"}] -) +- **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. -#Run a Task -response = assistant.run("Solve the equation: 3x + 11 = 14") -print(response) +- **Collaboration:** + - Agents coordinate to ensure seamless patient experiences. + - Data is securely shared while maintaining patient confidentiality. -# Continue the conversation in the same thread -follow_up = assistant.run("Now explain how you solved it") -print(follow_up) -``` +**Outcome** -## Function Calling +- **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). -The assistant supports custom function integration: +--- -```python +### Part 5: Implementing Multi-Agent Systems – Best Practices for Enterprises -def get_weather(location: str, unit: str = "celsius") -> str: - # Mock weather function - return f"The weather in {location} is 22 degrees {unit}" +For enterprises embarking on the journey of multi-agent automation, adhering to best practices ensures successful implementation. -# 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"] - } -) -``` +#### 1. Start Small and Scale Gradually -## API Reference +- **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. -### Constructor +#### 2. Invest in Training and Change Management -```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, -) -``` +- **Employee Education:** Train staff on interacting with and managing multi-agent systems. +- **Change Management:** Prepare the organization for changes in workflows and roles. -### Methods +#### 3. Leverage Cloud and Edge Computing -#### run(task: str) -> str -Sends a task to the assistant and returns its response. The conversation thread is maintained between calls. +- **Scalable Infrastructure:** Utilize cloud services for flexible resource allocation. +- **Edge Computing:** Deploy agents closer to data sources for faster processing. -#### add_function(func: Callable, description: str, parameters: Dict[str, Any]) -> None -Adds a callable function that the assistant can use during conversations. +#### 4. Foster Interoperability -#### add_message(content: str, file_ids: Optional[List[str]] = None) -> None -Adds a message to the current conversation thread. +- **Standards Compliance:** Use industry standards for data formats and communication protocols. +- **API Integration:** Ensure agents can integrate with existing enterprise applications. -## Error Handling +#### 5. Prioritize Ethical Considerations -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 +- **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. -## Best Practices +--- -1. Thread Management - - Use the same assistant instance for related conversations - - Create new instances for unrelated tasks - - Monitor thread status during long-running operations +### Conclusion -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 +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. -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 +By adopting multi-agent systems, enterprises can: -## References +- **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. -- [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) +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. +-------------------------------------------------- +# File: swarms\contributing.md +# Contribution Guidelines --------------------------------------------------- +--- -# File: swarms\agents\reasoning_agent_router.md +## Table of Contents -# ReasoningAgentRouter +- [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) -!!! 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. +--- -## Architecture +## Project Overview -```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 -``` +**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. -## Configuration +We need your help to: -### Arguments +- **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 -!!! info "Constructor Parameters" - | 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 | -### Available Agent Types +Your contributions will help us push the boundaries of AI and make this library a valuable resource for the community. -!!! note "Supported Types" - The following agent types are supported through the `swarm_type` parameter: +--- - - `"reasoning-duo"` or `"reasoning-agent"` - - `"self-consistency"` or `"consistency-agent"` - - `"ire"` or `"ire-agent"` - - `"ReflexionAgent"` - - `"GKPAgent"` - - `"AgentJudge"` +## Getting Started -### Agent Types Comparison +### Installation -=== "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) +You can install swarms using `pip`: -=== "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 +```bash +pip3 install swarms +``` -=== "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 +Alternatively, you can clone the repository: -=== "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 +```bash +git clone https://github.com/kyegomez/swarms +``` -=== "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 +### Project Structure -=== "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 +- **`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. -## Usage +--- -### Methods +## How to Contribute -!!! 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 | +### Reporting Issues -### Image Support +If you find any bugs, inconsistencies, or have suggestions for enhancements, please open an issue on GitHub: -!!! info "Multi-modal Capabilities" - The ReasoningAgentRouter supports image inputs for compatible agent types: +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). - **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 +### Submitting Pull Requests - **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 +We welcome pull requests (PRs) for bug fixes, improvements, and new features. Please follow these guidelines: - **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" - ) +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. - # Batch processing with images - results = router.batched_run( - tasks=["Analyze this chart", "Describe this photo"], - imgs=["chart.png", "photo.jpg"] - ) - ``` + ```bash + git clone https://github.com/kyegomez/swarms.git + ``` -### Code Examples +3. **Create a New Branch**: Use a descriptive branch name. -=== "Basic Usage" - ```python - from swarms.agents.reasoning_agents import ReasoningAgentRouter + ```bash + git checkout -b feature/your-feature-name + ``` - # 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 - ) +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. - # 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" - ) - ``` + ```bash + git commit -am "Add feature X" + ``` -=== "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." - ) - ``` +7. **Push to Your Fork**: -=== "ReflexionAgent" - ```python - router = ReasoningAgentRouter( - swarm_type="ReflexionAgent", - max_loops=3, - model_name="gpt-4o-mini" - ) - ``` + ```bash + git push origin feature/your-feature-name + ``` -=== "GKPAgent" - ```python - router = ReasoningAgentRouter( - swarm_type="GKPAgent", - model_name="gpt-4o-mini", - num_knowledge_items=6 - ) - ``` +8. **Create a Pull Request**: -=== "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" - ) - ``` + - 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. -=== "AgentJudge" - ```python - router = ReasoningAgentRouter( - swarm_type="AgentJudge", - model_name="gpt-4o-mini", - max_loops=2 - ) - ``` +9. **Respond to Feedback**: Be prepared to make changes based on code reviews. -## Best Practices +**Note**: It's recommended to create small and focused PRs for easier review and faster integration. -!!! 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 +--- - 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 +## Coding Standards - 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 +To maintain code quality and consistency, please adhere to the following standards. - 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 +### Type Annotations -## Limitations +- **Mandatory**: All functions and methods must have type annotations. +- **Example**: -!!! warning "Known Limitations" - 1. Processing time increases with: - - Higher num_samples - - - Larger max_loops - - - More complex tasks + ```python + def add_numbers(a: int, b: int) -> int: + return a + b + ``` - 2. Model-specific limitations based on: - - Token limits - - - Model capabilities - - - API rate limits +- **Benefits**: + - Improves code readability. + - Helps with static type checking tools. -## Contributing +### Docstrings and Documentation -!!! note "Development Guidelines" - When extending the ReasoningAgentRouter: - - 1. Follow the existing swarm interface - 2. Add comprehensive tests - 3. Update documentation - 4. Maintain error handling +- **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. +- **Example**: --------------------------------------------------- + ```python + def calculate_mean(values: List[float]) -> float: + """ + Calculates the mean of a list of numbers. -# File: swarms\agents\reasoning_agents_overview.md + Args: + values (List[float]): A list of numerical values. -# Reasoning Agents Overview + Returns: + float: The mean of the input values. + Raises: + ValueError: If the input list is empty. + """ + if not values: + raise ValueError("The input list is empty.") + return sum(values) / len(values) + ``` -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. +- **Documentation**: Update or create documentation pages if your changes affect the public API. -These agents are inspired by cognitive science and human reasoning processes, incorporating techniques such as: +### Testing -- **Multi-step reasoning**: Breaking down complex problems into manageable components +- **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. -- **Self-reflection**: Evaluating and critiquing their own outputs + ```bash + pytest tests/ + ``` -- **Iterative refinement**: Progressively improving solutions through multiple iterations +### Code Style -- **Collaborative thinking**: Using multiple reasoning pathways or agent perspectives +- **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. -- **Memory integration**: Learning from past experiences and building knowledge over time +--- -- **Meta-cognitive awareness**: Understanding their own thinking processes and limitations +## Areas Needing Contributions +We have several areas where contributions are particularly welcome. +### Writing Tests +- **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. -## Available Reasoning Agents +### Improving Documentation -| 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) | +- **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. -## Agent Architectures +### Creating Multi-Agent Orchestration Methods -### Self-Consistency Agent +- **Goal**: Provide new multi-agent orchestration methods -**Description**: Implements multiple independent reasoning paths with consensus-building to improve response reliability and accuracy through majority voting mechanisms. +--- -**Key Features**: +## Community and Support -- Concurrent execution of multiple reasoning instances +- **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. -- AI-powered aggregation and consensus analysis +--- -- Validation mode for answer verification +## License -- Configurable sample sizes and output formats +By contributing to swarms, you agree that your contributions will be licensed under the [MIT License](LICENSE). +--- -**Architecture Diagram**: +Thank you for contributing to swarms! Your efforts help make this project better for everyone. -```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 -``` +If you have any questions or need assistance, please feel free to open an issue or reach out to the maintainers. -**Use Cases**: Mathematical problem solving, high-stakes decision making, answer validation, quality assurance processes +-------------------------------------------------- -**Implementation**: `SelfConsistencyAgent` +# File: swarms\ecosystem.md -**Documentation**: [Self-Consistency Agent Guide](consistency_agent.md) ---- +# Swarms Ecosystem -### Reasoning Duo +*The Complete Enterprise-Grade Multi-Agent AI Platform* -**Description**: Dual-agent collaborative system that separates reasoning and execution phases, enabling specialized analysis and task completion through coordinated agent interaction. +--- -**Key Features**: +## **Join the Future of AI Development** -- Separate reasoning and execution agents +**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. -- Collaborative problem decomposition +--- -- Cross-validation between agents +## **Complete Product Portfolio** -- Configurable model selection for each agent +| **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* | +--- -**Architecture Diagram**: +## **Why Choose the Swarms Ecosystem?** -```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 -``` +### **Enterprise-Grade Architecture** -**Use Cases**: Complex analysis tasks, multi-step problem solving, research and planning, verification workflows +- **Production Ready**: Battle-tested in enterprise environments with 99.9%+ uptime -**Implementation**: `ReasoningDuo` +- **Scalable Infrastructure**: Handle millions of agent interactions with automatic scaling -**Documentation**: [Reasoning Duo Guide](reasoning_duo.md) +- **Security First**: End-to-end encryption, API key management, and enterprise compliance ---- +- **Observability**: Comprehensive logging, monitoring, and debugging capabilities -### IRE Agent (Iterative Reflective Expansion) +### **Developer Experience** -**Description**: Sophisticated reasoning framework employing iterative hypothesis generation, simulation, and refinement through continuous cycles of testing and meta-cognitive reflection. +- **Multiple Language Support**: Native clients for every major programming language -**Key Features**: +- **Unified API**: Consistent interface across all platforms and languages -- Hypothesis generation and testing +- **Rich Documentation**: Comprehensive guides, tutorials, and API references -- Path simulation and evaluation +- **Active Community**: 24/7 support through Discord, GitHub, and direct channels -- Meta-cognitive reflection capabilities +### **Performance & Reliability** -- Dynamic strategy revision based on feedback +- **High Throughput**: Process thousands of concurrent agent requests +- **Low Latency**: Optimized for real-time applications and user experiences -**Architecture Diagram**: +- **Fault Tolerance**: Automatic retries, circuit breakers, and graceful degradation -```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 -``` +- **Multi-Cloud**: Deploy on AWS, GCP, Azure, or on-premises infrastructure -**Use Cases**: Complex reasoning tasks, research problems, strategy development, iterative learning scenarios +--- -**Implementation**: `IterativeReflectiveExpansion` +## **Join Our Growing Community** -**Documentation**: [IRE Agent Guide](iterative_agent.md) +### **Connect With Developers Worldwide** + +| **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 | --- -### Reflexion Agent +## **Contribute to the Ecosystem** -**Description**: Advanced self-reflective system implementing actor-evaluator-reflector architecture for continuous improvement through experience-based learning and memory integration. +### **How You Can Make an Impact** -**Key Features**: +| **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) | -- Actor-evaluator-reflector sub-agent architecture +--- -- Self-evaluation and quality assessment +## **We're Hiring Top Talent** -- Experience memory and learning capabilities +### **Join the Team Building the Future Of The World Economy** -- Adaptive improvement through reflection +**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 | -**Architecture Diagram**: +### **Open Positions** -```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 -``` +| **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 | -**Use Cases**: Continuous improvement tasks, long-term projects, adaptive learning, quality refinement processes +**Ready to Build the Future?** **[Apply Now at swarms.ai/hiring](https://swarms.ai/hiring)** -**Implementation**: `ReflexionAgent` +--- -**Documentation**: [Reflexion Agent Guide](reflexion_agent.md) +--- + +## **Get Started Today** + +### **Quick Start Guide** + +| **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 | --- -### GKP Agent (Generated Knowledge Prompting) +## **Enterprise Support & Partnerships** -**Description**: Knowledge-driven reasoning system that generates relevant information before answering queries, implementing multi-perspective analysis through coordinated knowledge synthesis. +### **Ready to Scale with Swarms?** -**Key Features**: +| **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) | -- Dynamic knowledge generation +--- -- Multi-perspective reasoning coordination +**Ready to build the future of AI? Start with Swarms today and join thousands of developers creating the next generation of intelligent applications.** -- Information synthesis and integration -- Configurable knowledge item generation +-------------------------------------------------- +# File: swarms\examples\agent_output_types.md -**Architecture Diagram**: +# Agent Output Types Examples with Vision Capabilities -```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 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. -**Use Cases**: Knowledge-intensive tasks, research questions, fact-based reasoning, information synthesis +## Prerequisites -**Implementation**: `GKPAgent` +- Python 3.7+ +- OpenAI API key +- Anthropic API key (optional, for Claude models) +- Swarms library -**Documentation**: [GKP Agent Guide](gkp_agent.md) +## Installation ---- +```bash +pip3 install -U swarms +``` -### Agent Judge +## Environment Variables -**Description**: Specialized evaluation system for assessing agent outputs and system performance, providing structured feedback and quality metrics through comprehensive assessment frameworks. +```plaintext +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" # Required for GPT-4V vision capabilities +ANTHROPIC_API_KEY="" # Optional, for Claude models +``` -**Key Features**: +## Examples -- Structured evaluation methodology +### Vision-Enabled Quality Control Agent -- Quality assessment and scoring +```python +from swarms.structs import Agent +from swarms.prompts.logistics import ( + Quality_Control_Agent_Prompt, +) -- Performance metrics generation +# Image for analysis +factory_image = "image.jpg" -- Configurable evaluation criteria + +# 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", +) -**Architecture Diagram**: +response = quality_control_agent.run( + task="what is in the image?", + img=factory_image, +) + +print(response) -```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 ``` -**Use Cases**: Quality control, output evaluation, performance assessment, model comparison +### Supported Image Formats -**Implementation**: `AgentJudge` +The vision-enabled agents support various image formats including: -**Documentation**: [Agent Judge Guide](agent_judge.md) +| 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 | ---- +### Best Practices for Vision Tasks -### REACT Agent (Reason-Act-Observe) +| 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 | -**Description**: Action-oriented reasoning system implementing iterative reason-act-observe cycles with memory integration for interactive task completion and environmental adaptation. +-------------------------------------------------- -**Key Features**: +# File: swarms\examples\agent_structured_outputs.md -- Reason-Act-Observe cycle implementation +# Agent Structured Outputs -- Memory integration and experience building +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. -- Action planning and execution +## Prerequisites -- Environmental state observation +- Python 3.7+ +- OpenAI API key +- Swarms library +## Installation -**Architecture Diagram**: - -```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 -``` - -**Use Cases**: Interactive tasks, tool usage scenarios, planning problems, learning environments - -**Implementation**: `ReactAgent` - -**Documentation**: [REACT Agent Guide](react_agent.md) +```bash +pip3 install -U swarms +``` +## Environment Variables -## Implementation Guide +```plaintext +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" +ANTHROPIC_API_KEY="" +``` -### Unified Interface via Reasoning Agent Router +## Understanding Function Schemas -The `ReasoningAgentRouter` provides a centralized interface for accessing all reasoning agent implementations: +Function schemas in Swarms follow OpenAI's function calling format. Each function schema is defined as a dictionary with the following structure: ```python -from swarms.agents import ReasoningAgentRouter - -# 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 -) - -# Execute reasoning process -result = router.run("Analyze the optimal solution for this complex business problem") -print(result) +{ + "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"] + } + } +} ``` -### Direct Agent Implementation +## Code Example + +Here's an example showing how to use multiple function schemas with a Swarms agent: ```python -from swarms.agents import SelfConsistencyAgent, ReasoningDuo, ReflexionAgent +from swarms import Agent +from swarms.prompts.finance_agent_sys_prompt import FINANCIAL_AGENT_SYS_PROMPT -# Self-Consistency Agent for high-accuracy requirements -consistency_agent = SelfConsistencyAgent( - model_name="gpt-4o-mini", - num_samples=5 +# 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"] + } + } + } +] + +# 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" ) -# Reasoning Duo for collaborative analysis workflows -duo_agent = ReasoningDuo( - model_names=["gpt-4o-mini", "gpt-4o"] +# 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) -# Reflexion Agent for adaptive learning scenarios -reflexion_agent = ReflexionAgent( - model_name="gpt-4o-mini", - max_loops=3, - memory_capacity=100 +# 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) ``` -## Choosing the Right Reasoning Agent +## Schema Types and Properties -| 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 | +The function schema supports various parameter types and properties: +| 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 | -## Technical Documentation +Example of a more complex schema: -For comprehensive technical documentation on each reasoning agent implementation: +```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"] + } + } +} +``` -- [Self-Consistency Agent](consistency_agent.md) +This example shows how to structure complex nested objects, arrays, and various parameter types while following OpenAI's function calling schema. -- [Reasoning Duo](reasoning_duo.md) -- [IRE Agent](iterative_agent.md) +-------------------------------------------------- -- [Reflexion Agent](reflexion_agent.md) +# File: swarms\examples\agent_with_tools.md -- [GKP Agent](gkp_agent.md) +# Basic Agent Example -- [Agent Judge](agent_judge.md) +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. -- [Reasoning Agent Router](reasoning_agent_router.md) +## Prerequisites +- Python 3.7+ +- OpenAI API key ---- +- Swarms library -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. +## Building Tools for Your Agent --------------------------------------------------- +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: -# File: swarms\agents\reasoning_duo.md +### Tool Structure Best Practices -# ReasoningDuo +1. **Type Hints**: Always use type hints to specify input and output types -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. +2. **Docstrings**: Include comprehensive docstrings with description, args, returns, and examples +3. **Error Handling**: Implement proper error handling and return consistent JSON responses -## Class Overview +4. **Rate Limiting**: Include rate limiting when dealing with APIs -### Constructor Parameters +5. **Input Validation**: Validate input parameters before processing -| 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 | +### Example Tool Template -### Methods +Here's a template for creating a well-structured tool: -| 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 | +```python +from typing import Optional, Dict, Any +import json +def example_tool(param1: str, param2: Optional[int] = None) -> str: + """ + Brief description of what the tool does. + Args: + param1 (str): Description of first parameter + param2 (Optional[int]): Description of optional parameter -## Quick Start + Returns: + str: JSON formatted string containing the result -```python -from swarms.agents.reasoning_duo import ReasoningDuo + Raises: + ValueError: Description of when this error occurs + RequestException: Description of when this error occurs -# Initialize the ReasoningDuo -duo = ReasoningDuo( - model_name="reasoning-agent-01", - model_names=["gpt-4o-mini", "gpt-4o"] -) + 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") -# Run a single task -result = duo.run("Explain the concept of gravitational waves") + # Main logic + result: Dict[str, Any] = { + "status": "success", + "data": { + "param1": param1, + "param2": param2 + } + } -# Run multiple tasks -tasks = [ - "Calculate compound interest for $1000 over 5 years", - "Explain quantum entanglement" -] -results = duo.batched_run(tasks) + # Return JSON string + return json.dumps(result, indent=2) + + 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)}"}) ``` -## Examples +### Building API Integration Tools -### 1. Mathematical Analysis +When building tools that interact with external APIs: + +1. **API Client Setup**: ```python -duo = ReasoningDuo() +def get_api_data(endpoint: str, params: Dict[str, Any]) -> str: + """ + Generic API data fetcher with proper error handling. -# Complex mathematical problem -math_task = """ -Solve the following differential equation: -dy/dx + 2y = x^2, y(0) = 1 -""" + Args: + endpoint (str): API endpoint to call + params (Dict[str, Any]): Query parameters -solution = duo.run(math_task) + 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)}"}) ``` -### 2. Physics Problem -```python -# Quantum mechanics problem -physics_task = """ -Calculate the wavelength of an electron with kinetic energy of 50 eV -using the de Broglie relationship. -""" -result = duo.run(physics_task) -``` +### Data Processing Tools -### 3. Financial Analysis +Example of a tool that processes data: ```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% -""" - -analysis = duo.run(finance_task) -``` +from typing import List, Dict +import pandas as pd -## Advanced Usage +def process_market_data(prices: List[float], window: int = 14) -> str: + """ + Calculate technical indicators from price data. -### Customizing Agent Behavior + Args: + prices (List[float]): List of historical prices + window (int): Rolling window size for calculations -You can customize both agents by modifying their initialization parameters: + Returns: + str: JSON formatted string with calculated indicators -```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..." -) + 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)}"}) ``` -### Batch Processing with Progress Tracking +### Adding Tools to Your Agent -```python -tasks = [ - "Analyze market trends for tech stocks", - "Calculate risk metrics for a portfolio", - "Forecast revenue growth" -] +Once you've created your tools, add them to your agent like this: -# Process multiple tasks with logging -results = duo.batched_run(tasks) +```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 + ] +) ``` -## Implementation Details +## Tutorial Steps -The ReasoningDuo uses a two-stage process: +1. First, install the latest version of Swarms: -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 +```bash +pip3 install -U swarms +``` -### Internal Architecture +2. Set up your environment variables in a `.env` file: -``` -Task Input → Reasoning Agent → Structured Analysis → Main Agent → Final Output +```plaintext +OPENAI_API_KEY="your-api-key-here" +WORKSPACE_DIR="agent_workspace" ``` -## Best Practices - -1. **Task Formulation** - - Be specific and clear in task descriptions - - Include relevant context and constraints - - Break complex problems into smaller subtasks +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 -2. **Performance Optimization** - - Use batched_run for multiple related tasks - - Monitor agent outputs for consistency - - Adjust model parameters based on task complexity +4. Run the example code below: -## Error Handling -The ReasoningDuo includes built-in logging using the `loguru` library: ```python -from loguru import logger - -# Logs are automatically generated for each task -logger.info("Task processing started") -``` - -## Limitations - -- Processing time may vary based on task complexity -- Model response quality depends on input clarity -- Resource usage scales with batch size - -## Example Script +import json +import requests +from swarms import Agent +from typing import List +import time -For a runnable demonstration, see the [reasoning_duo_batched.py](https://github.com/kyegomez/swarms/blob/master/examples/models/reasoning_duo_batched.py) example. +def get_coin_price(coin_id: str, vs_currency: str) -> str: + """ + Get the current price of a specific cryptocurrency. --------------------------------------------------- + Args: + coin_id (str): The CoinGecko ID of the cryptocurrency (e.g., 'bitcoin', 'ethereum') + vs_currency (str, optional): The target currency. Defaults to "usd". -# File: swarms\agents\reflexion_agent.md + Returns: + str: JSON formatted string containing the coin's current price and market data -# ReflexionAgent + Raises: + requests.RequestException: If the API request fails -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. + 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, + } -## Overview + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() -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 + data = response.json() + return json.dumps(data, indent=2) -## Initialization + 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)}"}) -```python -from swarms.agents import ReflexionAgent -agent = ReflexionAgent( - agent_name="reflexion-agent", - system_prompt="...", # Optional custom system prompt - model_name="openai/o1", - max_loops=3, - memory_capacity=100 -) -``` +def get_top_cryptocurrencies(limit: int, vs_currency: str) -> str: + """ + Fetch the top cryptocurrencies by market capitalization. -### Parameters + Args: + limit (int, optional): Number of coins to retrieve (1-250). Defaults to 10. + vs_currency (str, optional): The target currency. Defaults to "usd". -| 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 | + Returns: + str: JSON formatted string containing top cryptocurrencies with detailed market data -## Methods + Raises: + requests.RequestException: If the API request fails + ValueError: If limit is not between 1 and 250 -### act + 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") -Generates a response to the given task using the actor agent. + 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", + } -```python -response = agent.act(task: str, relevant_memories: List[Dict[str, Any]] = None) -> str -``` + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() -| Parameter | Type | Description | -|-----------|------|-------------| -| `task` | `str` | The task to respond to | -| `relevant_memories` | `List[Dict[str, Any]]` | Optional relevant past memories to consider | + data = response.json() -### evaluate + # 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"), + } + ) -Evaluates the quality of a response to a task. + return json.dumps(simplified_data, indent=2) -```python -evaluation, score = agent.evaluate(task: str, response: str) -> Tuple[str, float] -``` + 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)}"}) -| Parameter | Type | Description | -|-----------|------|-------------| -| `task` | `str` | The original task | -| `response` | `str` | The response to evaluate | -Returns: -- `evaluation`: Detailed feedback on the response -- `score`: Numerical score between 0 and 1 +def search_cryptocurrencies(query: str) -> str: + """ + Search for cryptocurrencies by name or symbol. -### reflect + Args: + query (str): The search term (coin name or symbol) -Generates a self-reflection based on the task, response, and evaluation. + Returns: + str: JSON formatted string containing search results with coin details -```python -reflection = agent.reflect(task: str, response: str, evaluation: str) -> str -``` + Raises: + requests.RequestException: If the API request fails -| Parameter | Type | Description | -|-----------|------|-------------| -| `task` | `str` | The original task | -| `response` | `str` | The generated response | -| `evaluation` | `str` | The evaluation feedback | + 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} -### refine + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() -Refines the original response based on evaluation and reflection. + data = response.json() -```python -refined_response = agent.refine( - task: str, - original_response: str, - evaluation: str, - reflection: str -) -> str -``` + # Extract and format the results + result = { + "coins": data.get("coins", [])[ + :10 + ], # Limit to top 10 results + "query": query, + "total_results": len(data.get("coins", [])), + } -| Parameter | Type | Description | -|-----------|------|-------------| -| `task` | `str` | The original task | -| `original_response` | `str` | The original response | -| `evaluation` | `str` | The evaluation feedback | -| `reflection` | `str` | The self-reflection | + return json.dumps(result, indent=2) -### step + 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)}"}) -Processes a single task through one iteration of the Reflexion process. -```python -result = agent.step( - task: str, - iteration: int = 0, - previous_response: str = None -) -> Dict[str, Any] -``` +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. -| Parameter | Type | Description | -|-----------|------|-------------| -| `task` | `str` | The task to process | -| `iteration` | `int` | Current iteration number | -| `previous_response` | `str` | Response from previous iteration | + 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. -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 + Returns: + str: JSON formatted string containing the swap quote details -### run + 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), + } -Executes the Reflexion process for a list of tasks. + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() + return json.dumps(response.json(), indent=2) -```python -results = agent.run( - tasks: List[str], - include_intermediates: bool = False -) -> List[Any] -``` + 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)}"}) -| Parameter | Type | Description | -|-----------|------|-------------| -| `tasks` | `List[str]` | List of tasks to process | -| `include_intermediates` | `bool` | Whether to include intermediate iterations in results | -Returns: -- If `include_intermediates=False`: List of final responses -- If `include_intermediates=True`: List of complete iteration histories +def get_htx_market_data(symbol: str) -> str: + """ + Get market data for a trading pair from HTX exchange. -## Example Usage + Args: + symbol (str): Trading pair symbol (e.g., 'btcusdt', 'ethusdt') -```python -from swarms.agents import ReflexionAgent + Returns: + str: JSON formatted string containing market data -# Initialize the Reflexion Agent -agent = ReflexionAgent( - agent_name="reflexion-agent", - model_name="openai/o1", - max_loops=3 -) + 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()} -# Example tasks -tasks = [ - "Explain quantum computing to a beginner.", - "Write a Python function to sort a list of dictionaries by a specific key." -] + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() + return json.dumps(response.json(), indent=2) -# Run the agent -results = agent.run(tasks) + 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)}"}) -# Print results -for i, result in enumerate(results): - print(f"\nTask {i+1}: {tasks[i]}") - print(f"Response: {result}") -``` -## Memory System +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. -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. + 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". -### 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 + Returns: + str: JSON formatted string containing historical price and market data -## Best Practices + 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", + } -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 + response = requests.get(url, 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"Failed to fetch historical data: {str(e)}"} + ) + except Exception as e: + return json.dumps({"error": f"Unexpected error: {str(e)}"}) --------------------------------------------------- -# File: swarms\agents\structured_outputs.md +def get_defi_stats() -> str: + """ + Get global DeFi statistics including TVL, trading volumes, and dominance. -# :material-code-json: Agentic Structured Outputs + Returns: + str: JSON formatted string containing global DeFi statistics -!!! 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. + 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) -## :material-file-document-outline: Schema Definition + 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)}"}) -Structured outputs are defined using JSON Schema format. Here's the basic structure: -=== "Basic Schema" +def get_jupiter_tokens() -> str: + """ + Get list of tokens supported by Jupiter Protocol on Solana. - ```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 - ] - } - } - } - ] - ``` + Returns: + str: JSON formatted string containing supported tokens -=== "Advanced Schema" + 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) - ```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"] - } - } - } - ] - ``` + 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)}"}) -### :material-format-list-bulleted-type: Parameter Types -The following parameter types are supported: +def get_htx_trading_pairs() -> str: + """ + Get list of all trading pairs available on HTX exchange. -| 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` | + Returns: + str: JSON formatted string containing trading pairs information -## :material-cog: Implementation Steps + 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) -!!! tip "Quick Start Guide" - Follow these steps to implement structured outputs in your agent: + 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)}"}) -### Step 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" - }, - "include_volume": { - "type": "boolean", - "description": "Include trading volume data" - } - }, - "required": ["ticker"] - } - } - } -] -``` - -### Step 2: Initialize the Agent - -``` -from swarms import Agent - -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") -``` - -### Step 4: Parse the Output - -```python -from swarms.utils.str_to_dict import str_to_dict - -parsed_output = str_to_dict(response) -``` - -## :material-code-braces: Example Usage +def get_market_sentiment(coin_ids: List[str]) -> str: + """ + Get market sentiment data including social metrics and developer activity. -!!! example "Complete Financial Agent Example" - Here's a comprehensive example using a financial analysis agent: + Args: + coin_ids (List[str]): List of CoinGecko coin IDs -=== "Python Implementation" + Returns: + str: JSON formatted string containing market sentiment data - ```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"] - } + 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, } - } - ] - - # 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}") - ``` -=== "Expected Output" + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() + data = response.json() - ```json - { - "function_calls": [ - { - "name": "get_stock_price", - "arguments": { - "ticker": "AAPL", - "include_history": true, - "time": "2024-01-15T10:30:00Z" - } + 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"), } - ] - } - ``` - -## :material-check-circle: Best Practices - -!!! 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 - -!!! 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 -!!! 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 + # Rate limiting to avoid API restrictions + time.sleep(0.6) -## :material-alert-circle: Troubleshooting + return json.dumps(sentiment_data, indent=2) -!!! warning "Common Issues" + 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)}"}) -### Invalid Output Format -!!! failure "Problem" - The agent returns data in an unexpected format +# 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! +) -!!! 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 +# 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! +``` -### 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: swarms\examples\agents_as_tools.md -### Missing Fields +# Agents as Tools Tutorial -!!! failure "Problem" - Required fields are missing from the output +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. -!!! 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 +## Overview -## :material-lightbulb: Advanced Features +The Agents as Tools pattern allows you to: -!!! 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" - } - } - ``` +- Create specialized agents with specific capabilities ---- +- Have agents delegate tasks to other agents +- Chain multiple agents together for complex workflows +- Maintain separation of concerns between different agent roles --------------------------------------------------- +## Prerequisites -# File: swarms\agents\third_party.md +- Python 3.8 or higher -# Swarms Framework: Integrating and Customizing Agent Libraries +- Basic understanding of Python programming -Agent-based systems have emerged as a powerful paradigm for solving complex problems and automating tasks. +- Familiarity with async/await concepts (optional) -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. -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. +## Installation -## Table of Contents +Install the swarms package using pip: -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) +```bash +pip install -U swarms +``` -## 1. Introduction to the Swarms Framework +## Basic Setup -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. +1. First, set up your environment variables: -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: +```python +WORKSPACE_DIR="agent_workspace" +ANTHROPIC_API_KEY="" +``` -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. +## Step-by-Step Guide -## 2. The Need for Wrappers +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 + ``` -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. +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] + ) + ``` -This is where the concept of wrappers becomes crucial. By creating wrappers around different agent libraries, we can: +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] + ) + ``` -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. +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") + ``` -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. -## 3. Building Custom Agents with Swarms -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: +## Code ```python +import json +import requests 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 -``` - -This example demonstrates the fundamental structure of a custom agent class within the swarms framework. Let's break down the key components: +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)} -1. **Inheritance**: The class inherits from the `Agent` parent class, ensuring it adheres to the swarms framework's interface. +Execution Details: +----------------- +Exit Code: {result.returncode} +Execution Time: {result.returncode} seconds -2. **Initialization**: The `__init__` method calls the parent class's initializer and can include additional custom initialization logic. +Output: +------- +{result.stdout} -3. **Custom methods**: You can add any number of custom methods to extend the agent's functionality. +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)} -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. +Execution Error: +--------------- +Exit Code: {e.returncode} +Error Message: {e.stderr} -To create more sophisticated custom agents, you can expand on this basic structure by adding features such as: - -- **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. - -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 - -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. - -### 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: - -```python -from typing import List, Optional - -from griptape.structures import Agent as GriptapeAgent -from griptape.tools import FileManager, TaskMemoryClient, WebScraper +Command Output: +------------- +{e.stdout} +""" + return error_response + + + -from swarms import Agent -class GriptapeAgentWrapper(Agent): - """ - A wrapper class for the GriptapeAgent from the griptape library. +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!' """ - - 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 + 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)} - def run(self, task: str, *args, **kwargs) -> str: - """ - Run a task using the GriptapeAgent. +Execution Details: +----------------- +Exit Code: {result.returncode} +Execution Time: {result.returncode} seconds - Parameters: - - task: The task to be performed by the agent. +Output: +------- +{result.stdout} - Returns: - - The response from the GriptapeAgent as a string. - """ - response = self.griptape_agent.run(task, *args, **kwargs) - return str(response) +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)} - def add_tool(self, tool) -> None: - """ - Add a tool to the agent. + Execution Error: + --------------- + Exit Code: {e.returncode} + Error Message: {e.stderr} - Parameters: - - tool: The tool to be added. + Command Output: + ------------- + {e.stdout} """ - 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 - ) - -# 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) - -``` - -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. - -### Langchain Integration - -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: - -```python -from typing import List, Optional - -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 - + return error_response + + +def run_quant_trading_agent(task: str) -> str: + """Run a quantitative trading agent to analyze and execute trading strategies. -class LangchainAgentWrapper(Agent): - """ - Initialize the LangchainAgentWrapper. + 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 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}" - ) - - llm_chain = LLMChain(llm=self.llm, prompt=prompt) - tool_names = [tool.name for tool in self.tools] - - 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 - ) - - 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}") - + task (str): The specific trading task or analysis to perform -# Usage example + Returns: + str: The agent's response or analysis results -search_tool = DuckDuckGoSearchRun() -tools = [ - Tool( - name="Search", - func=search_tool.run, - description="Useful for searching the internet", + 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], ) -] - -langchain_wrapper = LangchainAgentWrapper("LangchainAssistant", tools) -result = langchain_wrapper.run("What is the capital of France?") -print(result) -``` - -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. - -### CrewAI Integration - -CrewAI is a library focused on creating and managing teams of AI agents. Let's create a wrapper for a CrewAI agent: -```python -from swarms import Agent -from crewai import Agent as CrewAIAgent -from crewai import Task, Crew, Process + out = agent.run(task) + return out -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 [] - ) - 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 +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}" -search_tool = SerperDevTool() +def get_coin_price(coin_id: str, vs_currency: str) -> str: + """ + Get the current price of a specific cryptocurrency. -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] -) + Args: + coin_id (str): The CoinGecko ID of the cryptocurrency (e.g., 'bitcoin', 'ethereum') + vs_currency (str, optional): The target currency. Defaults to "usd". -result = crewai_wrapper.run("Analyze the latest trends in quantum computing and summarize the key findings.") -print(result) -``` + Returns: + str: JSON formatted string containing the coin's current price and market data -This wrapper allows us to use CrewAI agents within the swarms framework, leveraging CrewAI's focus on role-based agents and collaborative task execution. + Raises: + requests.RequestException: If the API request fails -### Autogen Integration + 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, + } -Autogen is a framework for building conversational AI agents. Here's how we can create a wrapper for an Autogen agent: + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() -```python -from swarms import Agent -from autogen import ConversableAgent + data = response.json() + return json.dumps(data, indent=2) -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" + 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)}"}) - def run(self, task, *args, **kwargs): - messages = [{"content": task, "role": "user"}] - response = self.autogen_agent.generate_reply(messages) - return response - -# Usage example -import os - -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) -``` -This wrapper integrates Autogen's ConversableAgent into the swarms framework, allowing for easy use of Autogen's conversational AI capabilities. +def run_crypto_quant_agent(task: str) -> str: + """ + Run a crypto quantitative trading agent with specialized tools for cryptocurrency market analysis. -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. + 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. -## 5. Advanced Agent Handling Techniques + Args: + task (str): The task or query to be processed by the crypto quant agent. -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: + Returns: + str: The agent's response to the given task. -### 1. Dynamic Agent Creation + 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, + ], + ) -Implement a factory pattern to create agents dynamically based on task requirements: + return quant_agent.run(task) -```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}") - -# Usage -agent = AgentFactory.create_agent("griptape", "DynamicGriptapeAgent") -``` - - -### 2. Agent Pooling - -Implement an agent pool to manage and reuse agents efficiently: - -```python -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. Agent Composition - -Create composite agents that combine the capabilities of multiple agent types: - -```python -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. Agent Specialization - -Create specialized agents for specific domains or tasks: - -```python -class DataAnalysisAgent(Agent): - def __init__(self, name, analysis_tools): - super().__init__() - self.name = name - self.analysis_tools = analysis_tools - - def run(self, data): - results = {} - for tool in self.analysis_tools: - results[tool.name] = tool.analyze(data) - return results - -# Usage -import pandas as pd -from sklearn.preprocessing import StandardScaler -from sklearn.decomposition import PCA - -class AnalysisTool: - def __init__(self, name, func): - self.name = name - self.func = func - - 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))) -] - -data_agent = DataAnalysisAgent("DataAnalyst", tools) -df = pd.read_csv("sample_data.csv") -analysis_results = data_agent.run(df) -``` - -### 5. Agent Monitoring and Logging - -Implement a monitoring system to track agent performance and log their activities: - -```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 - - @log_agent_activity - def run(self, task, *args, **kwargs): - return super().run(task, *args, **kwargs) - -# 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 - -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. - -## 6. Best Practices for Custom Agent Development - -When developing custom agents using the swarms framework, consider the following best practices: - -1. **Modular Design**: Design your agents with modularity in mind. Break down complex functionality into smaller, reusable components. - -2. **Consistent Interfaces**: Maintain consistent interfaces across your custom agents to ensure interoperability within the swarms framework. - -3. **Error Handling**: Implement robust error handling and graceful degradation in your agents to ensure system stability. - -4. **Performance Optimization**: Optimize your agents for performance, especially when dealing with resource-intensive tasks or large-scale deployments. - -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. - -7. **Versioning**: Implement proper versioning for your custom agents to manage updates and maintain backwards compatibility. - -8. **Security Considerations**: Implement security best practices, especially when dealing with sensitive data or integrating with external services. - -Here's an example that incorporates some of these best practices: - -```python -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}") - - 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}" - - @property - def api_key(self) -> str: - # Provide a secure way to access the API key - return self._api_key - - 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) -``` - -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 - -## 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: - -1. **Enhanced Interoperability**: Developing more sophisticated protocols for agent communication and collaboration across different libraries and frameworks. - -2. **Scalability**: Improving the framework's ability to handle large-scale swarms of agents, potentially leveraging distributed computing techniques. - -3. **Adaptive Learning**: Incorporating more advanced machine learning techniques to allow agents to adapt and improve their performance over time. - -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. - -6. **Domain-Specific Optimizations**: Developing specialized agent types and tools for specific industries or problem domains. - -7. **Explainability and Transparency**: Improving the ability to understand and explain agent decision-making processes. - -8. **Security and Privacy**: Enhancing the framework's security features to protect against potential vulnerabilities and ensure data privacy. - -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. - -## 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. - -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. - -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! - - --------------------------------------------------- - -# File: swarms\agents\tool_agent.md - -# 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. - -### Parameters - -| 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 - -| 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. | - -### Methods - -#### `run` - -```python -def run(self, task: str, *args, **kwargs) -> Any: -``` - -**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. | - -**Returns:** - -- The output of the tool agent. - -**Raises:** - -- `Exception`: If an error occurs during the execution of the tool agent. - -## Functionality and Usage - -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. - -### Initialization - -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 -) -``` - -### Running a Task - -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) -``` - -### Detailed Examples - -#### Example 1: Basic Usage - -```python -from transformers import AutoModelForCausalLM, AutoTokenizer -from swarms import ToolAgent - -model = AutoModelForCausalLM.from_pretrained("databricks/dolly-v2-12b") -tokenizer = AutoTokenizer.from_pretrained("databricks/dolly-v2-12b") - -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) - -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 -) - -task = "Generate a person's information with custom parsing:" -parsed_data = agent.run(task) - -print(parsed_data) -``` - -#### Example 3: Specifying Maximum Number of Tokens - -```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) - -print(limited_data) -``` - - -## Full Usage -```python - -from pydantic import BaseModel, Field -from transformers import AutoModelForCausalLM, AutoTokenizer - -from swarms import ToolAgent -from swarms.tools.json_utils import base_model_to_json - -# Model name -model_name = "CohereForAI/c4ai-command-r-v01-4bit" - -# Load the pre-trained model and tokenizer -model = AutoModelForCausalLM.from_pretrained( - model_name, - device_map="auto", -) - -# Load the pre-trained model and tokenizer -tokenizer = AutoTokenizer.from_pretrained(model_name) - - -# 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", - ) - - -# 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" - -# 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, -) - -# Run the agent to generate the person's information -generated_data = agent.run(task) - -# Print the generated data -print(f"Generated data: {generated_data}") - - - -``` - - -## Jamba ++ ToolAgent -```python -from pydantic import BaseModel, Field -from transformers import AutoModelForCausalLM, AutoTokenizer - -from swarms import ToolAgent -from swarms.tools.json_utils import base_model_to_json - -# Model name -model_name = "ai21labs/Jamba-v0.1" - -# Load the pre-trained model and tokenizer -model = AutoModelForCausalLM.from_pretrained( - model_name, - device_map="auto", -) - -# Load the pre-trained model and tokenizer -tokenizer = AutoTokenizer.from_pretrained(model_name) - - -# 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", - ) - - -# 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" - -# 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, -) - -# Run the agent to generate the person's information -generated_data = agent(task) - -# Print the generated data -print(f"Generated data: {generated_data}") -``` - -## Additional Information and Tips - -- 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. - --------------------------------------------------- - -# File: swarms\artifacts\artifact.md - -# `Artifact` - -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. - -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. - -## Class Definition - -### Artifact - - -| 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 - -- `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. - -### Methods - -The `Artifact` class includes various methods for creating, editing, saving, loading, and exporting file artifacts. - -#### `create` - -| Parameter | Type | Description | -|--------------------|--------|----------------------------------------| -| `initial_content` | `str` | The initial content of the file. | - -**Usage Example:** - -```python -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` - - -| Parameter | Type | Description | -|---------------|--------|----------------------------------------| -| `new_content` | `str` | The new content of the file. | - -**Usage Example:** - -```python -artifact.edit(new_content="Updated file content") -``` - -#### `save` - -**Usage Example:** - -```python -artifact.save() -``` - -#### `load` - -**Usage Example:** - -```python -artifact.load() -``` - -#### `get_version` - - -| Parameter | Type | Description | -|-------------------|-------|-----------------------------------------| -| `version_number` | `int` | The version number to retrieve. | - -**Usage Example:** - -```python -version = artifact.get_version(version_number=1) -``` - -#### `get_contents` - -**Usage Example:** - -```python -current_contents = artifact.get_contents() -``` - -#### `get_version_history` - - -**Usage Example:** - -```python -version_history = artifact.get_version_history() -``` - -#### `export_to_json` - - -| Parameter | Type | Description | -|-------------|-------|----------------------------------------------| -| `file_path` | `str` | The path to the JSON file to save the artifact.| - -**Usage Example:** - -```python -artifact.export_to_json(file_path="artifact.json") -``` - -#### `import_from_json` - - -| Parameter | Type | Description | -|-------------|-------|--------------------------------------------------| -| `file_path` | `str` | The path to the JSON file to import the artifact from.| - -**Usage Example:** - -```python -imported_artifact = Artifact.import_from_json(file_path="artifact.json") -``` - -#### `get_metrics` - -**Usage Example:** - -```python -metrics = artifact.get_metrics() -``` - -#### `to_dict` - -**Usage Example:** - -```python -artifact_dict = artifact.to_dict() -``` - -#### `from_dict` - -| Parameter | Type | Description | -|-----------|------------------|--------------------------------------------------| -| `data` | `Dict[str, Any]` | The dictionary representation of the artifact. | - -**Usage Example:** - -```python -artifact_data = { - "file_path": "example.txt", - "file_type": "txt", - "contents": "File content", - "versions": [], - "edit_count": 0 -} -artifact = Artifact.from_dict(artifact_data) -``` - -## 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) - -## Examples of Usage - -### Example 1: Creating and Editing an Artifact - -```python -from datetime import datetime -from pydantic import BaseModel, Field, validator -from typing import List, Dict, Any, Union -import os -import json - -# Define FileVersion class -class FileVersion(BaseModel): - version_number: int - content: str - timestamp: datetime - -# Artifact class definition goes here - -# Create an artifact -artifact = Artifact(file_path="example.txt", file_type="txt") -artifact.create(initial_content="Initial file content") - -# Edit the artifact -artifact.edit(new_content="Updated file content") - -# Save the artifact to a file -artifact.save() - -# Load the artifact from the file -artifact.load() - -# Print the current contents of the artifact -print(artifact.get_contents()) - -# Print the version history -print(artifact.get_version_history()) -``` - -### Example 2: Exporting and Importing an Artifact - -```python -# Export the artifact to a JSON file -artifact.export_to_json(file_path="artifact.json") - -# Import - - the artifact from a JSON file -imported_artifact = Artifact.import_from_json(file_path="artifact.json") - -# Print the metrics of the imported artifact -print(imported_artifact.get_metrics()) -``` - -### Example 3: Converting an Artifact to and from a Dictionary - -```python -# Convert the artifact to a dictionary -artifact_dict = artifact.to_dict() - -# Create a new artifact from the dictionary -new_artifact = Artifact.from_dict(artifact_dict) - -# Print the metrics of the new artifact -print(new_artifact.get_metrics()) -``` - - --------------------------------------------------- - -# File: swarms\changelog\5_6_8.md - -# 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) - - --------------------------------------------------- - -# File: swarms\changelog\5_8_1.md - -# 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. - --------------------------------------------------- - -# File: swarms\changelog\6_0_0 2.md - -# 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 - --------------------------------------------------- - -# File: swarms\changelog\6_0_0.md - -# 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 - --------------------------------------------------- - -# File: swarms\changelog\changelog_new.md - -# 🚀 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! 🚀 - --------------------------------------------------- - -# File: swarms\cli\cli_guide.md - -# The Ultimate Technical Guide to the Swarms CLI: A Step-by-Step Developer’s Guide - -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. - -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. - -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! - ---- - -## 1. Installing the Swarms CLI - -Before we explore the Swarms CLI commands, let’s get it installed and running on your machine. - -### 1.1. Installation Using `pip` - -For most users, the simplest way to install the Swarms CLI is through `pip`: - -```bash -pip3 install -U swarms -``` - -This command installs the latest version of the Swarms CLI package, ensuring that you have the newest features and fixes. - -### 1.2. Installation Using `Poetry` - -Alternatively, if you are using `Poetry` as your Python package manager, you can add the Swarms package like this: - -```bash -poetry add swarms -``` - -Once installed, you can run the Swarms CLI directly using: - -```bash -poetry run swarms help -``` - -This command shows all the available options and commands, as we will explore in-depth below. - ---- - -## 2. Understanding Swarms CLI Commands - -With the Swarms CLI installed, the next step is to explore its key functionalities. Here are the most essential commands: - -### 2.1. `onboarding`: Setup Your Environment - -The `onboarding` command guides you through setting up your environment and configuring the agents for your Swarms. - -```bash -swarms onboarding -``` - -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: - -```bash -swarms help -``` - -This command will output a helpful list like the one shown below, including detailed descriptions of each command. - -```plaintext -Swarms CLI - Help - -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 -``` - -### 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. - -### 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: - -```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: - -```bash -swarms read-docs -``` - -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. - -### 2.6. `run-agents`: Orchestrate Agents - -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. - -```bash -swarms run-agents --yaml-file agents.yaml -``` - -If you want to specify a custom configuration file, just pass in the YAML file using the `--yaml-file` flag. - ---- - -## 3. Working with the `agents.yaml` Configuration File - -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. - -### 3.1. Example `agents.yaml` Configuration: - -```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?" - - - 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." - - - 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." - - - 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." -``` - -### 3.2. Explanation of Key Fields - -- **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. - -### 3.3. Running Agents Using `agents.yaml` - -After configuring the agents, you can execute them directly from the CLI: - -```bash -swarms run-agents --yaml-file agents_config.yaml -``` - -This command will run the specified agents, allowing them to perform their tasks and return results according to your configuration. - ---- - -## 4. Use Cases for the Swarms CLI - -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. - -### 4.1. Financial Data Analysis - -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 Task: Automating long-term investment analysis using historical stock data. - -```bash -swarms run-agents --yaml-file finance_analysis.yaml -``` - -### 4.2. Marketing Automation - -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. - -Example Task: Running multiple agents to analyze customer sentiment from recent surveys. - -```bash -swarms run-agents --yaml-file marketing_agents.yaml -``` - -### 4.3. Operations and Task Management - -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. - -Example Task: Automating a task management system using Swarms agents. - -```bash -swarms run-agents --yaml-file operations_agents.yaml -``` - ---- - -## 5. Advanced Usage: Customizing and Scaling Agents - -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. - -### 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 - -ms run-agents --yaml-file agents_batch_2.yaml & -``` - -### 5.2. Integration with Other Tools - -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. - ---- - -## 6. Conclusion and Next Steps - -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. - - - --------------------------------------------------- - -# File: swarms\cli\main.md - -# Swarms CLI Documentation - -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. - -## Installation - -You can install the `swarms` package using `pip` or `poetry`. - -### Using pip - -```bash -pip3 install -U swarms -``` - -### Using poetry - -```bash -poetry add swarms -``` - -Once installed, you can run the Swarms CLI with the following command: - -```bash -poetry run swarms help -``` - -## Swarms CLI - Help - -When running `swarms help`, you'll see the following output: - -``` - _________ - / _____/_ _ _______ _______ _____ ______ - \_____ \ \/ \/ /\__ \_ __ \/ \ / ___/ - / \ / / __ \| | \/ Y Y \___ \ -/_______ / \/\_/ (____ /__| |__|_| /____ > - \/ \/ \/ \/ - - - - Swarms CLI - Help - - 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 - - For more details, visit: https://docs.swarms.world -``` - -### CLI Commands - -Below is a detailed explanation of the available commands: - -- **onboarding** - Starts the onboarding process to help you set up your environment and configure your agents. - - Usage: - ```bash - swarms onboarding - ``` - -- **help** - Displays the help message, including a list of available commands. - - 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 - ``` - -- **check-login** - Verifies if you are logged into the platform and starts the cache for storing your login session. - - Usage: - ```bash - swarms check-login - ``` - -- **read-docs** - Redirects you to the official Swarms documentation on the web for further reading. - - Usage: - ```bash - swarms read-docs - ``` - -- **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: - ```bash - swarms run-agents --yaml-file agents.yaml - ``` - - --------------------------------------------------- - -# File: swarms\concept\framework_architecture.md - -# Swarms Framework Architecture - - -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. - - - -``` -swarms/ -├── agents/ -├── artifacts/ -├── cli/ -├── memory/ -├── models/ ---> Moved to swarm_models -├── prompts/ -├── schemas/ -├── structs/ -├── telemetry/ -├── tools/ -├── utils/ -└── __init__.py -``` - - - -### Role of Folders in the Swarms Framework - -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. - ---- - -### **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. - ---- - -### **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. - ---- - -### **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. - ---- - -### **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. - ---- - -### **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. - ---- - -### **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. - ---- - -### **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. - ---- - -### **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. - ---- - -### **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. - ---- - -### **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. - ---- - -### **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. - ---- - -### **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. - ---- - -### How to Access Documentation - -- **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. - -- **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. - -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: - -- **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 - - -- **Community Support** - - URL: [Submit issue](https://discord.gg/jM3Z6M9uMq) - - Ask the community for support in real-time and or admin support - --------------------------------------------------- - -# File: swarms\concept\future_swarm_architectures.md - - - ---- - -### Federated Swarm - -**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. - -**Use-Cases:** -- Distributed learning systems where data is processed across multiple nodes. - -- Scenarios requiring collaboration between different teams or departments. - -```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 -``` - ---- - -### 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. - -**Use-Cases:** -- Centralized decision-making processes. - -- 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] -``` - ---- - -### Mesh Swarm - -**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. - -**Use-Cases:** -- Complex systems requiring high fault tolerance and redundancy. - -- Scenarios involving dynamic and frequent communication between agents. - -```mermaid -graph TD - A1[Agent 1] --> A2[Agent 2] - A1 --> A3[Agent 3] - A1 --> A4[Agent 4] - A2 --> A3 - A2 --> A4 - A3 --> A4 -``` - ---- - -### Cascade Swarm - -**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] -``` - ---- - -### Hybrid Swarm - -**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. - -**Use-Cases:** -- Complex workflows requiring a mix of different processing strategies. - -- Custom scenarios tailored to specific operational requirements. - -```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] -``` - ---- - -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. - --------------------------------------------------- - -# File: swarms\concept\how_to_choose_swarms.md - -# Choosing the Right Swarm for Your Business Problem - -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. - -## Swarm Types Overview - -- **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). - ---- - -## 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. - -### Advantages -- Ensures robustness in decision-making by leveraging multiple agents. -- Helps eliminate outliers or faulty agent decisions. - -### 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. - ---- - -## 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. - -### 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. - -### Notes -!!! note - Sequential swarms are slower but ensure strict task dependencies are respected. Parallel swarms are faster but require careful management of task interdependencies. - ---- - -## 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. - -### Advantages -- Fair and even distribution of tasks. -- Simple and effective for balanced workloads. - -### 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. - ---- - -## Mixture of Agents - -### 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. - -### 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. - ---- - -## 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. - -### Advantages -- Facilitates highly interactive problem-solving. -- Ideal for dynamic and unstructured problems. - -### Warnings -!!! warning - High communication overhead between agents may slow down decision-making in large swarms. - ---- - -## AgentRegistry Swarm - -### 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. - ---- - -## SpreadsheetSwarm - -### 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. - -### Advantages -- Provides structure and order for managing massive amounts of agent outputs. -- Outputs are easily saved and tracked in CSV files. - -### Warnings -!!! warning - Ensure the correct configuration of agents in SpreadsheetSwarm to avoid data mismatches and inconsistencies when scaling up to thousands of agents. - ---- - -## Final Thoughts - -The choice of swarm depends on: - -1. **Nature of the task**: Whether it's sequential or parallel. - -2. **Problem complexity**: Simple problems might benefit from RoundRobin, while complex ones may need GraphWorkflow or Mixture of Agents. - -3. **Scale of execution**: For large-scale tasks, Swarms like SpreadsheetSwarm or MajorityVoting provide scalability with structured outputs. - -When integrating agents in a business workflow, it's crucial to balance task complexity, agent capabilities, and scalability to ensure the optimal swarm architecture. - - --------------------------------------------------- - -# File: swarms\concept\philosophy.md - -# 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: - -- **Readable Code with Type Annotations, Documentation, and Logging** -- **Bleeding-Edge Performance via Concurrency and Parallelism** -- **Simplified Abstractions for Multi-Agent Collaboration** - -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. - ---- - -## 1. Emphasizing Readable Code - -Readable code is the cornerstone of maintainable and scalable systems. It ensures that developers can easily understand, modify, and extend the codebase. - -### 1.1 Use of Type Annotations - -Type annotations enhance code readability and catch errors early in the development process. - -```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 - -Adhering to consistent code style guidelines, such as PEP 8 for Python, ensures uniformity across the codebase. - -- **Indentation:** Use 4 spaces per indentation level. -- **Variable Naming:** Use `snake_case` for variables and functions. -- **Class Naming:** Use `PascalCase` for class names. - -### 1.3 Importance of Documentation - -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. - - Returns: - UserProfile: An object containing user profile data. - """ - # Function implementation -``` - -### 1.4 Consistent Naming Conventions - -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`). - ---- - -## 2. Effective Logging Practices - -Logging is essential for debugging and monitoring the health of applications. - -### 2.1 Why Logging is Important - -- **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. - -### 2.3 Logging Examples - -```python -import logging - -logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s:%(message)s') - -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 -``` - ---- - -## 3. Achieving Bleeding-Edge Performance - -Performance is critical, especially when dealing with multiple agents and large datasets. - -### 3.1 Concurrency and Parallelism - -Utilizing concurrency and parallelism can significantly improve performance. - -- **Concurrency:** Dealing with multiple tasks by managing multiple threads. -- **Parallelism:** Executing multiple tasks simultaneously on multiple CPU cores. - -### 3.2 Asynchronous Programming - -Asynchronous programming allows for non-blocking operations, leading to better resource utilization. - -```python -import asyncio - -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()) -``` - -### 3.3 Utilizing Modern Hardware Capabilities - -Leverage multi-core processors and GPUs for computationally intensive tasks. - -- **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 -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)) -``` - ---- - -## 4. Simplifying Multi-Agent Collaboration - -Simplifying the abstraction of multi-agent collaboration makes it accessible and manageable. - -### 4.1 Importance of Simple Abstractions - -- **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. - -### 4.2 Standardizing Agent Interfaces - -Every agent should adhere to a standard interface for consistency. - -#### 4.2.1 Agent Base Class - -```python -from abc import ABC, abstractmethod - -class BaseAgent(ABC): - @abstractmethod - def run(self, task: str) -> Any: - pass - - def __call__(self, task: str) -> Any: - return self.run(task) - - @abstractmethod - async def arun(self, task: str) -> Any: - pass -``` - -#### 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" -``` - -#### 4.2.3 Usage Example - -```python -agent = DataProcessingAgent() - -# Synchronous call -result = agent.run("data_task") -print(result) # Output: Processed data_task - -# Asynchronous call -async def main(): - result = await agent.arun("data_task") - print(result) # Output: Processed data_task asynchronously - -asyncio.run(main()) -``` - -### 4.3 Mermaid Diagram: Agent Interaction - -```mermaid -sequenceDiagram - participant User - participant AgentA - participant AgentB - participant AgentC - - 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 -``` - -*Agents collaborating to fulfill a user's task.* - -### 4.4 Simplified Collaboration Workflow - -```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"] -``` - -*Workflow demonstrating how agents process a task collaboratively.* - ---- - -## 5. Bringing It All Together - -By integrating these principles, we create a cohesive system where agents can efficiently collaborate while maintaining code quality and performance. - -### 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}" - - 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}" - - async def arun(self, task: str) -> str: - # Agent B asynchronous processing - return f"AgentB processed {task} asynchronously" -``` - -#### 5.1.2 Orchestrator Agent - -```python -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}" -``` - -#### 5.1.3 Execution - -```python -orchestrator = OrchestratorAgent() - -# 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 - -asyncio.run(main()) -``` - -### 5.2 Mermaid Diagram: Orchestrator Workflow - -```mermaid -sequenceDiagram - participant User - participant Orchestrator - participant AgentA - participant AgentB - - User->>Orchestrator: run(task) - Orchestrator->>AgentA: run(task) - Orchestrator->>AgentB: run(task) - AgentA-->>Orchestrator: result_a - AgentB-->>Orchestrator: result_b - Orchestrator-->>User: Orchestrated results -``` - -*Orchestrator coordinating between Agent A and Agent B.* - ---- - -## 6. Conclusion - -Our philosophy centers around making multi-agent collaboration as simple and efficient as possible by: - -- **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. - -By adhering to these principles, we create a robust foundation for scalable and maintainable systems that can adapt to evolving technological landscapes. - - - --------------------------------------------------- - -# File: swarms\concept\purpose\limits_of_individual_agents.md - -# The Limits of Individual Agents - -![Reliable Agents](docs/assets/img/reliabilitythrough.png) - - -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, - -- Context Window Limits -- Single Task Execution -- Hallucination -- No collaboration - - - -#### Context Window Limits - -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. - -#### Hallucination - -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. - -#### 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 - -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. - -# The Elegant yet Simple Solution - -- ## Multi-Agent Collaboration - -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: - -#### Overcoming Context Window Limits - -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. - -#### 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. - -#### Enhancing Multitasking Capabilities - -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. - -#### Facilitating Collaboration and Knowledge Sharing - -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. - -### Conclusion - -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. - --------------------------------------------------- - -# File: swarms\concept\purpose\why.md - -# The Swarms Framework: Orchestrating Agents for Enterprise Automation - -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. - -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) - -## The Purpose of Swarms: Overcoming Agent Limitations - -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: - -1. Short-Term Memory Constraints -2. Hallucination and Factual Inconsistencies -3. Single-Task Limitations -4. Lack of Collaborative Capabilities -5. Cost Inefficiencies - -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 - -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. - -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. - -### Limitation 2: Hallucination and Factual Inconsistencies - -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. - -### 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 - -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. - -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. - -### Limitation 5: Cost Inefficiencies - -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. - -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 - -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. - -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. - - -## Benefits of the Swarms Framework - -The adoption of the Swarms Framework in enterprise environments offers numerous benefits: - -1. Increased Efficiency and Scalability -2. Improved Reliability and Accuracy -3. Adaptability and Continuous Improvement -4. Cost Optimization -5. Enhanced Security and Compliance - -## Increased Efficiency and Scalability - -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. - -## Improved Reliability and Accuracy - -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. - -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. - -## Adaptability and Continuous Improvement - -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. - -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. - -## Cost Optimization - -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. - -## Enhanced Security and Compliance - -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. - -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. - -## Real-World Applications and Use Cases - -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: - -1. Intelligent Process Automation (IPA) -2. Customer Service and Support -3. Fraud Detection and Risk Management -4. Supply Chain Optimization -5. Research and Development - -## Intelligent Process Automation (IPA) - -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. - -## Customer Service and Support - -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. - -## 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 - -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. - -## Research and Development - -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. - -# Conclusion - -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. - --------------------------------------------------- - -# File: swarms\concept\purpose\why_swarms.md - -# 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. - -### Why Multiple Agents Are Necessary - -#### 1. **Cognitive Diversity** - -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. - -#### 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** - -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. - -#### 4. **Robustness and Redundancy** - -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. - -### Overcoming Expenses with API Bills and Hosting - -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: - -#### 1. **Optimize Agent Efficiency** - -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. - -#### 2. **Use Open Source and Self-Hosted Solutions** - -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. - -#### 4. **Dynamic Scaling and Load Balancing** - -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. - -#### 5. **Collaborative Cost-Sharing Models** - -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. - -#### 6. **Monitor and Analyze Costs** - -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. - -### Conclusion - -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. - --------------------------------------------------- - -# File: swarms\concept\swarm_architectures.md - -# Multi-Agent Architectures - -### What is a Multi-Agent Architecture? - -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. - -### How Multi-Agent Architectures Facilitate Communication - -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: - -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. - -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. - -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. - -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. - -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. - -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. - -## Core Multi-Agent Architectures - -| **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 | - ---- - -## Architectural Patterns - -### Hierarchical Architecture - -**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. - -**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 - - -**[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] -``` - ---- - -### Agent Rearrange - -**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. - -**Use Cases:** -- Adaptive manufacturing lines that reconfigure based on product requirements - -- Dynamic sales territory realignment based on market conditions - -- Flexible healthcare staffing that adjusts to patient needs - - -**[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] -``` - ---- - -### Concurrent Architecture - -**Overview:** -Multiple agents operate independently and simultaneously on different tasks. Each agent works on its own task without dependencies on the others. - -**Use Cases:** -- Tasks that can be processed independently, such as parallel data analysis - -- Large-scale simulations where multiple scenarios are run simultaneously - - -**[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] -``` - ---- - -### Sequential Architecture - -**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. - -**Use Cases:** - -- Workflows where each step depends on the previous one, such as assembly lines or sequential data processing - -- Scenarios requiring strict order of operations - - -**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/)** - -```mermaid -graph TD - A[Input] --> B[Agent 1] - B --> C[Agent 2] - C --> D[Agent 3] - D --> E[Agent 4] - E --> F[Final Output] -``` - ---- - -### Round Robin Architecture - -**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. - -**Use Cases:** - -- Load balancing in distributed systems - -- Scenarios requiring fair distribution of tasks to avoid overloading any single agent - - -**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/round_robin_swarm/)** - -```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 -``` - ---- - -### SpreadSheet Architecture - -**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. - -**Use Cases:** -- Multi-threaded execution: Execute agents on multiple threads - -- Save agent outputs into CSV file - -- One place to analyze agent outputs - - -**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/spreadsheet_swarm/)** - -```mermaid -graph TD - A[Initialize SpreadSheet System] --> B[Initialize Agents] - B --> C[Load Task Queue] - C --> D[Distribute Tasks] - - subgraph Agent_Pool[Agent Pool] - D --> E1[Agent 1] - D --> E2[Agent 2] - D --> E3[Agent 3] - D --> E4[Agent N] - end - - E1 --> F1[Process Task] - E2 --> F2[Process Task] - E3 --> F3[Process Task] - E4 --> F4[Process Task] - - F1 --> G[Collect Results] - F2 --> G - F3 --> G - F4 --> G - - G --> H[Save to CSV] - H --> I[Generate Analytics] -``` - ---- - -### Mixture of Agents - -**Overview:** -Combines multiple agents with different capabilities and expertise to solve complex problems that require diverse skill sets. - -**Use Cases:** -- Financial forecasting requiring different analytical approaches - -- Complex problem-solving needing diverse expertise - -- Multi-domain analysis tasks - - -**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/moa/)** - -```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] - - C --> F[Response 1] - D --> G[Response 2] - E --> H[Response N] - - F --> I[Layer 2: Aggregator Agent] - G --> I - H --> I - I --> J[Synthesized Output] -``` - ---- - -### Graph Workflow - -**Overview:** -Organizes agents in a directed acyclic graph (DAG) format, enabling complex dependencies and parallel execution paths. - -**Use Cases:** -- AI-driven software development pipelines - -- Complex project management with dependencies - -- Multi-step data processing workflows - - -**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/graph_workflow/)** - -```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] -``` - ---- - -### 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 - -- Contract negotiations - -- Brainstorming sessions - - -**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/group_chat/)** - -```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] -``` - ---- - -### Interactive Group Chat - -**Overview:** -Enhanced version of Group Chat with dynamic speaker selection, priority-based communication, and advanced interaction patterns. - -**Use Cases:** -- Advanced collaborative decision-making - -- Dynamic team coordination - -- Adaptive conversation management - - -**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/interactive_groupchat/)** - -```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 -``` - ---- - -### Agent Registry - -**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. - -**Use Cases:** -- Dynamic agent management in large-scale systems - -- Evolving recommendation engines that adapt agent selection - -- Service discovery in distributed agent systems - - -**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/agent_registry/)** - -```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 -``` - ---- - -### Router Architecture - -**Overview:** -Intelligently routes tasks to the most appropriate agents or architectures based on task requirements and agent capabilities. - -**Use Cases:** -- Dynamic task routing - -- Adaptive architecture selection - -- Optimized agent allocation - - -**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/)** - -```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] -``` - ---- - -### Heavy Architecture - -**Overview:** -High-performance architecture designed for handling intensive computational tasks with multiple agents working on resource-heavy operations. - -**Use Cases:** -- Large-scale data processing - -- Intensive computational workflows - -- High-throughput task execution - - -**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/heavy_swarm/)** - -```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] -``` - ---- - -### Deep Research Architecture - -**Overview:** -Specialized architecture for conducting comprehensive research tasks across multiple domains with iterative refinement and cross-validation. - -**Use Cases:** -- Academic research projects - -- Market analysis and intelligence - -- Comprehensive data investigation - - -**[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] -``` - ---- - -### De-Hallucination Architecture - -**Overview:** -Architecture specifically designed to reduce and eliminate hallucinations in AI outputs through consensus mechanisms and fact-checking protocols. - -**Use Cases:** -- Fact-checking and verification - -- 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 -``` - ---- - -### Council as Judge - -**Overview:** -Multiple agents act as a council to evaluate, judge, and validate outputs or decisions through collaborative assessment. - -**Use Cases:** -- Quality assessment and validation - -- Decision validation processes - -- Peer review systems - - -**[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] -``` - ---- - -### MALT Architecture - -**Overview:** -Specialized architecture for complex language processing tasks that require coordination between multiple language-focused agents. - -**Use Cases:** -- Natural language processing pipelines - -- Translation and localization - -- Content generation and editing - - -**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/malt/)** - -```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] -``` - ---- - -### Majority Voting - -**Overview:** -Agents vote on decisions with the majority determining the final outcome, providing democratic decision-making and error reduction through consensus. - -**Use Cases:** -- Democratic decision-making processes - -- Consensus building - -- Error reduction through voting - - -**[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] -``` - ---- - -### Auto-Builder - -**Overview:** -Automatically constructs and configures multi-agent systems based on requirements, enabling dynamic system creation and adaptation. - -**Use Cases:** -- Dynamic system creation - -- Adaptive architectures - -- Rapid prototyping of multi-agent systems - - -**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/auto_swarm_builder/)** - -```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] -``` - ---- - -### Hybrid Hierarchical Cluster - -**Overview:** -Combines hierarchical and peer-to-peer communication patterns for complex workflows that require both centralized coordination and distributed collaboration. - -**Use Cases:** -- Complex enterprise workflows - -- Multi-department coordination - -- Hybrid organizational structures - - -**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/hhcs/)** - -```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 -``` - ---- - -### Election Architecture - -**Overview:** -Agents participate in democratic voting processes to select leaders or make collective decisions. - -**Use Cases:** -- Democratic governance - -- Consensus building - -- Leadership selection - - -**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/election_swarm/)** - -```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 -``` - ---- - - ---- - -### Dynamic Conversational Architecture - -**Overview:** -Adaptive conversation management with dynamic agent selection and interaction patterns. - -**Use Cases:** -- Adaptive chatbots - -- Dynamic customer service - -- Contextual conversations - - -**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/dynamic_conversational_swarm/)** - -```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 -``` - ---- - -### Tree Architecture - -**Overview:** -Hierarchical tree structure for organizing agents in parent-child relationships. - -**Use Cases:** -- Organizational hierarchies - -- Decision trees - -- Taxonomic classification - - -**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/tree_swarm/)** - -```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] -``` - - --------------------------------------------------- - -# File: swarms\concept\swarm_ecosystem.md - -# Understanding the Swarms Ecosystem - -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. - -#### 1. **Swarms Framework** - -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. - -```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] -``` - -#### 2. **Swarms-Cloud** - -[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. - -```mermaid -graph TD; - SC[Swarms-Cloud] --> Uptime[99% Uptime] - SC --> Scale[Infinite Scalability] - SC --> Healing[Self-Healing] -``` - -#### 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. - -```mermaid -graph TD; - SM[Swarms-Models] --> OpenAI[OpenAI API] - SM --> Anthropic[Anthropic API] - SM --> Ollama[Ollama API] -``` - -#### 4. **AgentParse** - -[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. - -```mermaid -graph TD; - AP[AgentParse] --> JSON[JSON Parsing] - AP --> YAML[YAML Parsing] - AP --> CSV[CSV Parsing] - AP --> Pydantic[Pydantic Model Parsing] -``` - -#### 5. **Swarms-Platform** - -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] -``` - -#### Extending the Ecosystem: **Swarms Core**, **JS**, and More - -In addition to the core components, the Swarms Ecosystem offers several other powerful packages: - -- **[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. - -```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. - -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. - - - --------------------------------------------------- - -# File: swarms\concept\vision.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. - -### 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. - ---- - -### Code Examples - -#### 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 - -# 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?" -) - -# 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 - -# 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", -) - -# 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", -) - -# 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", -) - -# Orchestrate the agents in sequence -agents = [director, worker1, worker2] -flow = "Director -> Worker1 -> Worker2" -agent_system = AgentRearrange(agents=agents, flow=flow) - -# 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. 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] -``` - -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: - -- The **Director** agent assigns tasks to **Worker 1**, which generates a transcript for a YouTube video. - -- **Worker 1** completes its task before **Worker 2** starts summarizing the transcript. - -- **Worker 2** completes its task before **Worker 3** finalizes the process. - -### Why Developers Should Choose Swarms: - -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. - -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. - -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. - -### 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. - --------------------------------------------------- - -# 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. - -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. - ---- - -### Part 1: The Limitations of Individual AI Agents - -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. - -#### 1. Context Window Limits - -**Explanation** - -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. - -**Impact on Enterprises** - -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. - - -```mermaid -graph LR - subgraph "Context Window Limit" - Input[Large Document] - Agent[AI Agent] - Output[Partial Understanding] - Input -- Truncated Data --> Agent - Agent -- Generates --> Output - end -``` - -*An AI agent processes only a portion of a large document due to context window limits, resulting in partial understanding.* - -#### 2. Hallucination - -**Explanation** - -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. - -**Impact on Enterprises** - -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. - - -```mermaid -graph TD - Input[Ambiguous Data] - Agent[AI Agent] - Output[Incorrect Information] - Input --> Agent - Agent --> Output -``` - -*An AI agent generates incorrect information (hallucination) when processing ambiguous data.* - -#### 3. Single Task Execution - -**Explanation** - -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. - -**Impact on Enterprises** - -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. - - -```mermaid -graph LR - TaskA[Task A] --> AgentA[Agent A] - TaskB[Task B] --> AgentB[Agent B] - AgentA --> OutputA[Result A] - AgentB --> OutputB[Result B] -``` - -*Separate agents handle different tasks independently, lacking integration.* - -#### 4. Lack of Collaboration - -**Explanation** - -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. - -**Impact on Enterprises** - -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. - - -```mermaid -graph LR - Agent1[Agent 1] - Agent2[Agent 2] - Agent3[Agent 3] - Agent1 -->|No Communication| Agent2 - Agent2 -->|No Communication| Agent3 -``` - -*Agents operate without collaboration, resulting in isolated efforts.* - -#### 5. Lack of Accuracy - -**Explanation** - -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** - -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. - - -```mermaid -graph TD - Input[Complex Data] - Agent[AI Agent] - Output[Inaccurate Result] - Input --> Agent - Agent --> Output -``` - -*An AI agent produces an inaccurate result when handling complex data.* - -#### 6. Slow Processing Speed - -**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. - -**Impact on Enterprises** - -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. - - -```mermaid -graph TD - Input[Data] - Agent[AI Agent] - Delay[Processing Delay] - Output[Delayed Response] - Input --> Agent - Agent --> Delay - Delay --> Output -``` - -*An AI agent's slow processing leads to delayed responses.* - ---- - -### Part 2: Overcoming Limitations Through Multi-Agent Collaboration - -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. - -#### 1. Extending Context Window Through Distributed Processing - -**Solution** - -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. - -**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. - - -```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 -``` - -*Multiple agents process segments of a large document, and results are aggregated.* - -#### 2. Reducing Hallucination Through Cross-Verification - -**Solution** - -Agents can verify each other's outputs by cross-referencing information and flagging inconsistencies. Implementing consensus mechanisms ensures that only accurate information is accepted. - -**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. - - -```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.* - -#### 3. Enhancing Multi-Tasking Through Specialized Agents - -**Solution** - -Deploy specialized agents for different tasks and enable them to work concurrently. An orchestrator agent manages task allocation and workflow integration. - -**Implementation in Enterprises** - -- **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. - - -```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 -``` - -*Specialized agents handle different tasks under the management of an orchestrator agent.* - -#### 4. Facilitating Collaboration Through Communication Protocols - -**Solution** - -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. - -**Implementation in Enterprises** - -- **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. - - -```mermaid -graph LR - Agent1[Agent 1] - Agent2[Agent 2] - Agent3[Agent 3] - Agent1 <--> Agent2 - Agent2 <--> Agent3 - Agent3 <--> Agent1 - Output[Collaborative Outcome] -``` - -*Agents communicate and collaborate to achieve a common goal.* - -#### 5. Improving Accuracy Through Ensemble Learning - -**Solution** - -Use ensemble methods where multiple agents provide predictions or analyses, and a meta-agent combines these to produce a more accurate result. - -**Implementation in Enterprises** - -- **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. - - -```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 -``` - -*Meta-agent combines outputs from multiple agents to improve accuracy.* - -#### 6. Increasing Processing Speed Through Parallelization - -**Solution** - -By distributing workloads among multiple agents operating in parallel, processing times are significantly reduced, enabling real-time responses. - -**Implementation in Enterprises** - -- **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. - - -```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 -``` - -*Parallel processing by agents leads to faster completion times.* - ---- - -### Part 3: Tailoring Multi-Agent Systems for Enterprise Automation at Scale - -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. - -#### 1. Identifying Automation Opportunities - -Enterprises should start by identifying processes and tasks that are suitable for automation through multi-agent systems. Prioritize areas where: - -- **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. Designing the Multi-Agent Architecture - -Develop a robust architecture that defines how agents will interact, communicate, and collaborate. Key components include: - -- **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. - -#### 3. Ensuring Data Security and Compliance - -Data security is paramount when agents handle sensitive enterprise information. Implement measures such as: - -- **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). - -#### 4. Monitoring and Performance Management - -Establish monitoring tools to track agent performance, system health, and outcomes. Key metrics may include: - -- **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. - -#### 5. Scaling Strategies - -Develop strategies for scaling the system as enterprise needs grow, including: - -- **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. - -#### 6. Continuous Improvement - -Implement feedback loops for ongoing enhancement of the multi-agent system: - -- **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. - ---- - -### Part 4: Case Studies and Real-World Applications - -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 - -**Challenge** - -A financial institution needs to process large volumes of loan applications, requiring data verification, risk assessment, compliance checks, and decision-making. - -**Solution** - -- **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** - -- **Increased Processing Speed:** Applications are processed in minutes instead of days. -- **Improved Accuracy:** Cross-verification reduces errors. -- **Scalability:** System handles fluctuating application volumes efficiently. - -#### Case Study 2: Manufacturing Supply Chain Optimization - -**Challenge** - -A manufacturing company wants to optimize its supply chain to reduce costs and improve delivery times. - -**Solution** - -- **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. - -#### Case Study 3: Healthcare Patient Management - -**Challenge** - -A hospital aims to improve patient care coordination, managing appointments, medical records, billing, and treatment plans. - -**Solution** - -- **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. - -- **Collaboration:** - - Agents coordinate to ensure seamless patient experiences. - - Data is securely shared while maintaining patient confidentiality. - -**Outcome** - -- **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). - ---- - -### Part 5: Implementing Multi-Agent Systems – Best Practices for Enterprises - -For enterprises embarking on the journey of multi-agent automation, adhering to best practices ensures successful implementation. - -#### 1. Start Small and Scale Gradually - -- **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 - -- **Scalable Infrastructure:** Utilize cloud services for flexible resource allocation. -- **Edge Computing:** Deploy agents closer to data sources for faster processing. - -#### 4. Foster Interoperability - -- **Standards Compliance:** Use industry standards for data formats and communication protocols. -- **API Integration:** Ensure agents can integrate with existing enterprise applications. - -#### 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. - ---- - -### Conclusion - -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. - -By adopting multi-agent systems, enterprises can: - -- **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. - -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. - - --------------------------------------------------- - -# File: swarms\contributing.md - -# Contribution Guidelines - ---- - -## Table of Contents - -- [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) - ---- - -## Project Overview - -**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. - -We need your help to: - -- **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 - - - -Your contributions will help us push the boundaries of AI and make this library a valuable resource for the community. - ---- - -## Getting Started - -### Installation - -You can install swarms using `pip`: - -```bash -pip3 install swarms -``` - -Alternatively, you can clone the repository: - -```bash -git clone https://github.com/kyegomez/swarms -``` - -### 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 - -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). - -### 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. - - ```bash - git clone https://github.com/kyegomez/swarms.git - ``` - -3. **Create a New Branch**: Use a descriptive branch name. - - ```bash - git checkout -b feature/your-feature-name - ``` - -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" - ``` - -7. **Push to Your Fork**: - - ```bash - git push origin feature/your-feature-name - ``` - -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. - -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. - ---- - -## Coding Standards - -To maintain code quality and consistency, please adhere to the following standards. - -### Type Annotations - -- **Mandatory**: All functions and methods must have type annotations. -- **Example**: - - ```python - def add_numbers(a: int, b: int) -> int: - return a + b - ``` - -- **Benefits**: - - Improves code readability. - - Helps with static type checking tools. - -### 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. - -- **Example**: - - ```python - def calculate_mean(values: List[float]) -> float: - """ - Calculates the mean of a list of numbers. - - Args: - values (List[float]): A list of numerical values. - - Returns: - float: The mean of the input values. - - 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. - -### 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/ - ``` - -### 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. - ---- - -## Areas Needing Contributions - -We have several areas where contributions are particularly welcome. - -### Writing Tests - -- **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 - -- **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 - ---- - -## Community and Support - -- **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. - ---- - -## License - -By contributing to swarms, you agree that your contributions will be licensed under the [MIT License](LICENSE). - ---- - -Thank you for contributing to swarms! Your efforts help make this project better for everyone. - -If you have any questions or need assistance, please feel free to open an issue or reach out to the maintainers. - --------------------------------------------------- - -# File: swarms\ecosystem.md - - -# Swarms Ecosystem - -*The Complete Enterprise-Grade Multi-Agent AI Platform* - ---- - -## **Join the Future of AI Development** - -**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. - ---- - -## **Complete Product Portfolio** - -| **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* | - ---- - -## **Why Choose the Swarms Ecosystem?** - -### **Enterprise-Grade Architecture** - -- **Production Ready**: Battle-tested in enterprise environments with 99.9%+ uptime - -- **Scalable Infrastructure**: Handle millions of agent interactions with automatic scaling - -- **Security First**: End-to-end encryption, API key management, and enterprise compliance - -- **Observability**: Comprehensive logging, monitoring, and debugging capabilities - -### **Developer Experience** - -- **Multiple Language Support**: Native clients for every major programming language - -- **Unified API**: Consistent interface across all platforms and languages - -- **Rich Documentation**: Comprehensive guides, tutorials, and API references - -- **Active Community**: 24/7 support through Discord, GitHub, and direct channels - -### **Performance & Reliability** - -- **High Throughput**: Process thousands of concurrent agent requests - -- **Low Latency**: Optimized for real-time applications and user experiences - -- **Fault Tolerance**: Automatic retries, circuit breakers, and graceful degradation - -- **Multi-Cloud**: Deploy on AWS, GCP, Azure, or on-premises infrastructure - ---- - -## **Join Our Growing Community** - -### **Connect With Developers Worldwide** - -| **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 | - ---- - -## **Contribute to the Ecosystem** - -### **How You Can Make an Impact** - -| **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) | - ---- - -## **We're Hiring Top Talent** - -### **Join the Team Building the Future Of The World Economy** - -**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 | - -### **Open Positions** - -| **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 | - -**Ready to Build the Future?** **[Apply Now at swarms.ai/hiring](https://swarms.ai/hiring)** - ---- - ---- - -## **Get Started Today** - -### **Quick Start Guide** - -| **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 | - ---- - -## **Enterprise Support & Partnerships** - -### **Ready to Scale with 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) | - ---- - -**Ready to build the future of AI? Start with Swarms today and join thousands of developers creating the next generation of intelligent applications.** - - --------------------------------------------------- - -# File: swarms\examples\agent_output_types.md - -# Agent Output Types Examples with Vision Capabilities - -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. - -## Prerequisites - -- Python 3.7+ -- OpenAI API key -- Anthropic API key (optional, for Claude models) -- Swarms library - -## Installation - -```bash -pip3 install -U swarms -``` - -## Environment Variables - -```plaintext -WORKSPACE_DIR="agent_workspace" -OPENAI_API_KEY="" # Required for GPT-4V vision capabilities -ANTHROPIC_API_KEY="" # Optional, for Claude models -``` - -## Examples - -### Vision-Enabled Quality Control Agent - -```python -from swarms.structs 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="gpt-4.1-mini", - system_prompt=Quality_Control_Agent_Prompt, - multi_modal=True, - max_loops=2, - output_type="str-all-except-first", -) - - -response = quality_control_agent.run( - task="what is in the image?", - img=factory_image, -) - -print(response) - -``` - -### Supported Image Formats - -The vision-enabled agents support various image formats including: - -| 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 | - -### Best Practices for Vision Tasks - -| 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 | - --------------------------------------------------- - -# File: swarms\examples\agent_structured_outputs.md - -# Agent Structured Outputs - -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. - -## Prerequisites - -- Python 3.7+ -- OpenAI API key -- Swarms library - -## Installation - -```bash -pip3 install -U swarms -``` - -## Environment Variables - -```plaintext -WORKSPACE_DIR="agent_workspace" -OPENAI_API_KEY="" -ANTHROPIC_API_KEY="" -``` - -## Understanding Function Schemas - -Function schemas in Swarms follow OpenAI's function calling format. Each function schema is defined as a dictionary with the following structure: - -```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 - -Here's an example showing how to use multiple function schemas with a Swarms agent: - -```python -from swarms import Agent -from swarms.prompts.finance_agent_sys_prompt import FINANCIAL_AGENT_SYS_PROMPT - -# 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"] - } - } - } -] - -# 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" -) - -# 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) - -# 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) -``` - -## Schema Types and Properties - -The function schema supports various parameter types and properties: - -| 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 | - -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. - - --------------------------------------------------- - -# File: swarms\examples\agent_with_tools.md - -# Basic Agent Example - -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. - -## Prerequisites - -- Python 3.7+ - -- OpenAI API key - -- Swarms library - -## Building Tools for Your Agent - -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: - -### Tool Structure Best Practices - -1. **Type Hints**: Always use type hints to specify input and output types - -2. **Docstrings**: Include comprehensive docstrings with description, args, returns, and examples - -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 typing import Optional, Dict, Any -import json - -def example_tool(param1: str, param2: Optional[int] = None) -> str: - """ - Brief description of what the tool does. - - Args: - param1 (str): Description of first parameter - param2 (Optional[int]): Description of optional parameter - - Returns: - str: JSON formatted string containing the result - - Raises: - ValueError: Description of when this error occurs - RequestException: Description of when this error occurs - - 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 - } - } - - # Return JSON string - return json.dumps(result, indent=2) - - 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)}"}) -``` - -### Building API Integration Tools - -When building tools that interact with external APIs: - -1. **API Client Setup**: - -```python -def get_api_data(endpoint: str, params: Dict[str, Any]) -> str: - """ - Generic API data fetcher with proper error handling. - - Args: - endpoint (str): API endpoint to call - params (Dict[str, Any]): Query parameters - - 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)}"}) -``` - - - -### Data Processing Tools - -Example of a tool that processes data: - -```python -from typing import List, Dict -import pandas as pd - -def process_market_data(prices: List[float], window: int = 14) -> str: - """ - Calculate technical indicators from price data. - - Args: - prices (List[float]): List of historical prices - window (int): Rolling window size for calculations - - 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)}"}) -``` - -### Adding Tools to Your Agent - -Once you've created your tools, add them to your agent like this: - -```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 - ] -) -``` - -## Tutorial Steps - -1. First, install the latest version of Swarms: - -```bash -pip3 install -U swarms -``` - -2. Set up your environment variables in a `.env` file: - -```plaintext -OPENAI_API_KEY="your-api-key-here" -WORKSPACE_DIR="agent_workspace" -``` - -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 - -4. Run the example code below: - - - -```python -import json -import requests -from swarms import Agent -from typing import List -import time - - -def get_coin_price(coin_id: str, vs_currency: str) -> str: - """ - Get the current price of a specific cryptocurrency. - - Args: - coin_id (str): The CoinGecko ID of the cryptocurrency (e.g., 'bitcoin', 'ethereum') - vs_currency (str, optional): The target currency. Defaults to "usd". - - Returns: - str: JSON formatted string containing the coin's current price and market data - - Raises: - requests.RequestException: If the API request fails - - 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, - } - - response = requests.get(url, params=params, timeout=10) - response.raise_for_status() - - data = response.json() - return json.dumps(data, indent=2) - - except requests.RequestException as e: - return json.dumps( - { - "error": f"Failed to fetch price for {coin_id}: {str(e)}" - } - ) - except Exception as e: - return json.dumps({"error": f"Unexpected error: {str(e)}"}) - - -def get_top_cryptocurrencies(limit: int, vs_currency: str) -> str: - """ - Fetch the top cryptocurrencies by market capitalization. - - Args: - limit (int, optional): Number of coins to retrieve (1-250). Defaults to 10. - vs_currency (str, optional): The target currency. Defaults to "usd". - - Returns: - str: JSON formatted string containing top cryptocurrencies with detailed market data - - Raises: - requests.RequestException: If the API request fails - ValueError: If limit is not between 1 and 250 - - 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", - } - - response = requests.get(url, params=params, timeout=10) - response.raise_for_status() - - data = response.json() - - # 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"), - } - ) - - return json.dumps(simplified_data, indent=2) - - except (requests.RequestException, ValueError) as e: - return json.dumps( - { - "error": f"Failed to fetch top cryptocurrencies: {str(e)}" - } - ) - except Exception as e: - return json.dumps({"error": f"Unexpected error: {str(e)}"}) - - -def search_cryptocurrencies(query: str) -> str: - """ - Search for cryptocurrencies by name or symbol. - - Args: - query (str): The search term (coin name or symbol) - - Returns: - str: JSON formatted string containing search results with coin details - - Raises: - requests.RequestException: If the API request fails - - 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} - - response = requests.get(url, params=params, timeout=10) - response.raise_for_status() - - data = response.json() - - # Extract and format the results - result = { - "coins": data.get("coins", [])[ - :10 - ], # Limit to top 10 results - "query": query, - "total_results": len(data.get("coins", [])), - } - - 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)}"}) - - -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. - - 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. - - Returns: - str: JSON formatted string containing the swap quote details - - 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), - } - - response = requests.get(url, 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"Failed to get Jupiter quote: {str(e)}"} - ) - except Exception as e: - return json.dumps({"error": f"Unexpected error: {str(e)}"}) - - -def get_htx_market_data(symbol: str) -> str: - """ - Get market data for a trading pair from HTX exchange. - - Args: - symbol (str): Trading pair symbol (e.g., 'btcusdt', 'ethusdt') - - Returns: - str: JSON formatted string containing market data - - 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()} - - response = requests.get(url, 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"Failed to fetch HTX market data: {str(e)}"} - ) - except Exception as e: - return json.dumps({"error": f"Unexpected error: {str(e)}"}) - - -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. - - 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". - - Returns: - str: JSON formatted string containing historical price and market data - - 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", - } - - response = requests.get(url, 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"Failed to fetch historical data: {str(e)}"} - ) - except Exception as e: - return json.dumps({"error": f"Unexpected error: {str(e)}"}) - - -def get_defi_stats() -> str: - """ - Get global DeFi statistics including TVL, trading volumes, and dominance. - - Returns: - str: JSON formatted string containing global DeFi statistics - - 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) - - 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)}"}) - - -def get_jupiter_tokens() -> str: - """ - Get list of tokens supported by Jupiter Protocol on Solana. - - Returns: - str: JSON formatted string containing supported tokens - - 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) - - 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)}"}) - - -def get_htx_trading_pairs() -> str: - """ - Get list of all trading pairs available on HTX exchange. - - Returns: - str: JSON formatted string containing trading pairs information - - 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) - - 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)}"}) - - -def get_market_sentiment(coin_ids: List[str]) -> str: - """ - Get market sentiment data including social metrics and developer activity. - - Args: - coin_ids (List[str]): List of CoinGecko coin IDs - - Returns: - str: JSON formatted string containing market sentiment data - - 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, - } - - response = requests.get(url, params=params, timeout=10) - response.raise_for_status() - data = response.json() - - 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"), - } - - # Rate limiting to avoid API restrictions - time.sleep(0.6) - - return json.dumps(sentiment_data, indent=2) - - 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)}"}) - - -# 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! -) - -# 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! -``` - - --------------------------------------------------- - -# File: swarms\examples\agents_as_tools.md - -# Agents as Tools Tutorial - -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. - -## Overview - -The Agents as Tools pattern allows you to: - -- Create specialized agents with specific capabilities - -- Have agents delegate tasks to other agents - -- Chain multiple agents together for complex workflows - -- Maintain separation of concerns between different agent roles - -## Prerequisites - -- Python 3.8 or higher - -- Basic understanding of Python programming - -- Familiarity with async/await concepts (optional) - - -## 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="" -``` - -## Step-by-Step Guide - -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 - ``` - -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] - ) - ``` - -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] - ) - ``` - -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") - ``` - - - -## Code - -```python -import json -import requests -from swarms import Agent - -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 - -Output: -------- -{result.stdout} - -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 - - - - - - -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} - -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. - - 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 - - Args: - task (str): The specific trading task or analysis to perform - - Returns: - str: The agent's response or analysis results - - 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], - ) - - out = agent.run(task) - return out - - - -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}" - -def get_coin_price(coin_id: str, vs_currency: str) -> str: - """ - Get the current price of a specific cryptocurrency. - - Args: - coin_id (str): The CoinGecko ID of the cryptocurrency (e.g., 'bitcoin', 'ethereum') - vs_currency (str, optional): The target currency. Defaults to "usd". - - Returns: - str: JSON formatted string containing the coin's current price and market data - - Raises: - requests.RequestException: If the API request fails - - 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, - } - - response = requests.get(url, params=params, timeout=10) - response.raise_for_status() - - data = response.json() - return json.dumps(data, indent=2) - - except requests.RequestException as e: - return json.dumps( - { - "error": f"Failed to fetch price for {coin_id}: {str(e)}" - } - ) - except Exception as e: - return json.dumps({"error": f"Unexpected error: {str(e)}"}) - - - -def run_crypto_quant_agent(task: str) -> str: - """ - Run a crypto quantitative trading agent with specialized tools for cryptocurrency market analysis. - - 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. - - Args: - task (str): The task or query to be processed by the crypto quant agent. - - Returns: - str: The agent's response to the given task. - - 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, - ], - ) - - return quant_agent.run(task) - -# 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], -) - -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) -``` - -## 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\examples\aggregate.md - -# Aggregate Multi-Agent Responses - -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. - -## Installation - -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/): - -```bash -pip3 install -U swarms -``` - -## Environment Variables - -```txt -WORKSPACE_DIR="" -OPENAI_API_KEY="" -ANTHROPIC_API_KEY="" -``` - -## 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 - -## 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, - ), -] - -# 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" -) - -print(result) -``` - - --------------------------------------------------- - -# File: swarms\examples\basic_agent.md - -# 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 - -- Python 3.7+ - -- OpenAI API key - -- Swarms library - -## Tutorial Steps - -1. First, install the latest version of Swarms: - -```bash -pip3 install -U swarms -``` - -2. Set up your environment variables in a `.env` file: - -```plaintext -OPENAI_API_KEY="your-api-key-here" -WORKSPACE_DIR="agent_workspace" -``` - -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 - -4. Run the example code below: - - -## Code - -```python -import time -from swarms import Agent - -# 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, -) - -out = agent.run("What are the best top 3 etfs for gold coverage?") - -time.sleep(10) -print(out) -``` - -## Example Output - -The agent will return a JSON response containing recommendations for gold ETFs based on the query. - -## Customization - -You can modify the system prompt and agent parameters to create specialized agents for different use cases: - -| 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 | - --------------------------------------------------- - -# File: swarms\examples\claude.md - -# Agent with Anthropic/Claude - -- Get their api keys and put it in the `.env` - -- Select your model_name like `claude-3-sonnet-20240229` follows LiteLLM conventions - - -```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="claude-3-sonnet-20240229", - 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\cohere.md - -# Agent with Cohere - -- Add your `COHERE_API_KEY` in the `.env` file - -- Select your model_name like `command-r` follows LiteLLM conventions - - -```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="command-r", - 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\concurrent_workflow.md - -# 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. - -## Prerequisites - -- Python 3.7+ -- OpenAI API key or other supported LLM provider keys -- Swarms library - -## Installation - -```bash -pip3 install -U swarms -``` - -## Environment Variables - -```plaintext -WORKSPACE_DIR="agent_workspace" -OPENAI_API_KEY="" -ANTHROPIC_API_KEY="" -GROQ_API_KEY="" -``` - -## Basic Usage - -### 1. Initialize Specialized Agents - -```python -from swarms import Agent -from swarms.structs.concurrent_workflow import ConcurrentWorkflow - -# 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, -) - -# 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, -) - -# 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, -) - -# Create list of agents -agents = [market_researcher, financial_analyst, technical_analyst] - -# 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 -) - -# Run the workflow -result = router.run( - "Analyze Tesla (TSLA) stock from market, financial, and technical perspectives" -) -``` - -## Features - -### Real-time Dashboard - -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 - -- **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 - -#### 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 - -#### 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 -) -``` - -#### Dashboard Behavior - -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 - -- **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 - -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 - -```python -# Configure output format -workflow = ConcurrentWorkflow( - agents=agents, - output_type="dict", # Get complete dictionary of results - show_dashboard=True -) -``` - -### Advanced Features - -#### Auto Prompt Engineering - -Enable automatic prompt optimization for all agents: - -```python -workflow = ConcurrentWorkflow( - agents=agents, - auto_generate_prompts=True, # Enable automatic prompt engineering - show_dashboard=True -) -``` - -#### Conversation History Management - -Automatic conversation tracking and persistence: - -```python -workflow = ConcurrentWorkflow( - agents=agents, - auto_save=True, # Auto-save conversation history - metadata_output_path="results.json" # Custom output file path -) -``` - -#### Multimodal Support - -Support for image inputs across all agents: - -```python -# Single image input -result = workflow.run( - task="Analyze this chart", - img="financial_chart.png" -) - -# Multiple image inputs -result = workflow.run( - task="Compare these charts", - imgs=["chart1.png", "chart2.png", "chart3.png"] -) -``` - -## Best Practices - -### 1. Dashboard Usage - -- **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 - -### 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 - -- **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 - -## Example Implementations - -### Comprehensive Market Analysis - -```python -from swarms import Agent -from swarms.structs.concurrent_workflow import ConcurrentWorkflow - -# 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, -) - -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, -) - -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, -) - -# 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 -) - -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)}") -``` - -### Batch Processing with Dashboard - -```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" -] - -# Optional: corresponding images for each task -charts = ["q1_chart.png", "q2_chart.png", "q3_chart.png", "q4_chart.png"] - -# Batch processing with dashboard monitoring -results = workflow.batch_run(tasks, imgs=charts) - -print(f"Completed {len(results)} quarterly analyses") -for i, result in enumerate(results): - print(f"\nQ{i+1} Analysis Results:") - print(result) -``` - -### Multimodal Analysis - -```python -# Analyze financial charts with multiple specialized agents -workflow = ConcurrentWorkflow( - agents=[technical_analyst, fundamental_analyst, sentiment_analyst], - show_dashboard=True, - output_type="dict" -) - -# Analyze a single chart -result = workflow.run( - task="Analyze this stock chart and provide trading insights", - img="stock_chart.png" -) - -# Analyze multiple charts -result = workflow.run( - task="Compare these three charts and identify patterns", - imgs=["chart1.png", "chart2.png", "chart3.png"] -) -``` - -### Error Handling and Monitoring - -```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 -) - -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 -``` - -## Performance Tips - -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 - -## 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\examples\deepseek.md - -# Agent with DeepSeek - -- 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) - -- 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="deepseek/deepseek-chat", - 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?") -``` - -## R1 - -This is a simple example of how to use the DeepSeek Reasoner model otherwise known as R1. - -```python - -import os -from swarms import Agent -from dotenv import load_dotenv - -load_dotenv() - -# 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.", -) - -# Run a query -agent.run("What are the components of a startup's stock incentive equity plan?") -``` - --------------------------------------------------- - -# File: swarms\examples\groq.md - -# Agent with Groq - -- Add your `GROQ_API_KEY` - -- Initiate your agent - -- Run your agent - -```python -import os - -from swarm_models import OpenAIChat - -from swarms import Agent - -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\examples\groupchat_example.md - -# 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. - -## 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 -``` - -## 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 dotenv import load_dotenv -import os -from swarms import Agent, GroupChat -``` - -### Configure Agents - -!!! example "Agent Configuration" - Here's how to set up your agents with specific roles: - - ```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, - ) - - # 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, - ) - ``` - -### Initialize GroupChat - -!!! example "GroupChat Setup" - Configure the GroupChat 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", - ) - ``` - -### Run the Chat - -!!! example "Execute the Chat" - Start the conversation between agents: - - ```python - history = chat.run( - "What potential expenses should we consider for the upcoming quarter? Please collaborate to outline a comprehensive list." - ) - ``` - -## Complete Example - -!!! success "Full Implementation" - Here's the complete code combined: - - ```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") - - # 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, - ) - - 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, - ) - - # 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", - ) - - # Run the chat - history = chat.run( - "What potential expenses should we consider for the upcoming quarter? Please collaborate to outline a comprehensive list." - ) - ``` - -## 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 | - -## 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 - -## 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 - -- [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 - - -# Hybrid Hierarchical-Cluster Swarm (HHCS) Example - -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 - -```python - -from swarms import Agent, SwarmRouter, HybridHierarchicalClusterSwarm - - -# 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, -) - -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, -) - -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, -) - -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, -) - -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", -) - -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", -) - -# 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", -) - -dispute_swarm = SwarmRouter( - name="dispute-resolution", - description="Handle complex disputes requiring multiple specialties", - agents=[litigation_agent, corporate_agent, doc_review_agent], - swarm_type="ConcurrentWorkflow", -) - - -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", -) - - -if __name__ == "__main__": - hybrid_hiearchical_swarm.run( - "What is the best way to file for a patent? for ai technology " - ) - -``` - --------------------------------------------------- - -# File: swarms\examples\hierarchical_swarm_example.md - -# Hierarchical Swarm Examples - -This page provides simple, practical examples of how to use the `HierarchicalSwarm` for various real-world scenarios. - -## Basic Example: Financial Analysis - -```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", -) - -# 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) -``` - -## Development Team Example - -```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", -) - -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", -) - -# 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, -) - -# 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) -``` - -## Single Step Execution - -```python -from swarms import Agent -from swarms.structs.hiearchical_swarm import HierarchicalSwarm - -# 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", -) - -# 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, -) - -# Execute a single step -task = "Analyze the current market trends for electric vehicles" -feedback = swarm.step(task=task) -print("Director Feedback:", feedback) -``` - -## Batch Processing - -```python -from swarms import Agent -from swarms.structs.hiearchical_swarm import HierarchicalSwarm - -# 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", -) - -# 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, -) - -# Execute multiple tasks -tasks = [ - "Analyze Apple (AAPL) stock performance", - "Evaluate Microsoft (MSFT) market position", - "Assess Google (GOOGL) competitive landscape" -] - -results = swarm.batched_run(tasks=tasks) -for i, result in enumerate(results): - print(f"Task {i+1} Result:", result) -``` - -## Research Team Example - -```python -from swarms import Agent -from swarms.structs.hiearchical_swarm import HierarchicalSwarm - -# 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", -) - -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", -) - -# 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) -``` - -## Key Takeaways - -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 - -For more detailed information about the `HierarchicalSwarm` API and advanced usage patterns, see the [main documentation](hierarchical_swarm.md). - --------------------------------------------------- - -# File: swarms\examples\igc_example.md - -## 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. - -### Architecture Description - -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 - -For comprehensive documentation on Interactive GroupChat, visit: [Interactive GroupChat Documentation](https://docs.swarms.world/en/latest/swarms/structs/interactive_groupchat/) - -### Step-by-Step Showcase - -* **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 - -## 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 - -```python -""" -InteractiveGroupChat Speaker Function Examples - -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 - -The example also shows how agents can mention each other using @agent_name syntax. -""" - -from swarms import Agent -from swarms.structs.interactive_groupchat import ( - InteractiveGroupChat, - random_speaker, -) - - -def create_example_agents(): - """Create example agents for demonstration.""" - - # 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, - ) - - 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, - ) - - 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, - ) - - return [analyst, researcher, writer] - - -def example_random(): - agents = create_example_agents() - - # 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, - ) - - # Test the random behavior - task = "Let's create a marketing strategy. @analyst @researcher @writer please contribute." - - response = group_chat.run(task) - print(f"Response:\n{response}\n") - - -if __name__ == "__main__": - # example_round_robin() - example_random() -``` - - - -## Connect With Us - -Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights! - -| 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) | - - --------------------------------------------------- - -# File: swarms\examples\interactive_groupchat_example.md - -# Interactive GroupChat Example - -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/) - -## Installation - -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/): - -```bash -pip3 install -U swarms -``` - -## Environment Variables - -```txt -OPENAI_API_KEY="" -ANTHROPIC_API_KEY="" -GROQ_API_KEY="" -``` - -# Code - - -## Interactive Session in Terminal - -```python -from swarms import Agent -from swarms.structs.interactive_groupchat import InteractiveGroupChat - - -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", - ) - - 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", - ) - - 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", - ) - - # Create a list of agents including both Agent instances and callables - agents = [ - financial_advisor, - tax_expert, - investment_analyst, - ] - - # 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, - ) - - 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}") -``` - - -## Run Method // Manual Method - - -```python -from swarms import Agent -from swarms.structs.interactive_groupchat import InteractiveGroupChat - - -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", - ) - - 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", - ) - - 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", - ) - - # Create a list of agents including both Agent instances and callables - agents = [ - financial_advisor, - tax_expert, - investment_analyst, - ] - - # 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\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: - -```python -from dotenv import load_dotenv -from swarms import Agent -from swarms.utils.vllm_wrapper import VLLM - -load_dotenv() -model = VLLM(model_name="meta-llama/Llama-4-Maverick-17B-128E") -``` - -## 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 - -### 1. Define Custom System Prompt - -```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. -""" -``` - -### 2. Initialize Agent - -```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, -) -``` - -## Full Code - -```python -from dotenv import load_dotenv - -from swarms import Agent -from swarms.utils.vllm_wrapper import VLLM - -load_dotenv() - -# Define custom system prompt for crypto risk analysis -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. -""" - -model = VLLM(model_name="meta-llama/Llama-4-Maverick-17B-128E") - -# 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, -) - -print( - agent.run( - "Conduct a risk analysis of the top cryptocurrencies. Think for 2 loops internally" - ) -) -``` - -!!! 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. - -??? 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. - -!!! 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 - -!!! example "Sample Usage" - ```python - response = agent.run( - "Conduct a risk analysis of the top cryptocurrencies. Think for 2 loops internally" - ) - 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. - - Args: - prompt (str): The input prompt for the model. - - 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) - - - - -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?") - -``` - --------------------------------------------------- - -# File: swarms\examples\mixture_of_agents.md - -# MixtureOfAgents Examples - -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. - -## Prerequisites - -- Python 3.7+ -- OpenAI API key or other supported LLM provider keys -- Swarms library - -## Installation - -```bash -pip3 install -U swarms -``` - -## Environment Variables - -```plaintext -WORKSPACE_DIR="agent_workspace" -OPENAI_API_KEY="" -ANTHROPIC_API_KEY="" -GROQ_API_KEY="" -``` - -## Basic Usage - -### 1. Initialize Specialized Agents - -```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, -) - -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, -) - -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, -) -``` - -### 2. Create and Run MixtureOfAgents - -```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, -) - -# Run the analysis -result = moa.run( - "Analyze the proposed merger between Company A and Company B, considering legal, financial, and business aspects." -) -``` - -## Advanced Usage - -### 1. Custom Configuration with System Prompts - -```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, -) - -result = moa.run("Evaluate the potential acquisition of StartupX") -``` - -### 2. Error Handling and Validation - -```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 - -1. Agent Selection and Configuration: - - Choose specialists with complementary expertise - - Configure appropriate system prompts - - Set suitable model parameters - -2. Aggregator Configuration: - - Define clear aggregation criteria - - Set appropriate weights for different opinions - - Configure conflict resolution strategies - -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)}") -``` - -This comprehensive guide demonstrates how to effectively use the MixtureOfAgents architecture for complex analysis tasks requiring multiple expert perspectives and consensus-building. - --------------------------------------------------- - -# File: swarms\examples\moa_example.md - -# 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. - -## 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. - -![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\model_providers.md - -# Model Providers Overview - -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. - -## 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) | - -## Quick Start - -All model providers follow a consistent pattern in Swarms. Here's the basic template: - -```python -from swarms import Agent -import os -from dotenv import load_dotenv - -load_dotenv() - -# Initialize agent with your chosen model -agent = 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 -``` - -!!! 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="You are a research expert." -) - -# 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 - -Automatically route tasks to the most appropriate model: - -```python -from swarms import Agent, ModelRouter - -# 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" - } -) - -# 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 -from swarms.structs.swarm_router import SwarmRouter - -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", - ), -] - -router = SwarmRouter( - name="multi-agent-router-demo", - description="Routes tasks to the most suitable agent", - agents=agents, - swarm_type="MultiAgentRouter" -) - -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\multiple_images.md - -# Processing Multiple Images - -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. - - -## 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 -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\swarm_router.md - -# SwarmRouter Examples - -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`. - -## Prerequisites - -- Python 3.7+ -- OpenAI API key or other supported LLM provider keys -- Swarms library - -## Installation - -```bash -pip3 install -U swarms -``` - -## Environment Variables - -```plaintext -WORKSPACE_DIR="agent_workspace" -OPENAI_API_KEY="" -ANTHROPIC_API_KEY="" -GROQ_API_KEY="" -``` - -## Basic Usage - -### 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, -) - -summarizer_agent = Agent( - agent_name="Document-Summarizer", - system_prompt="You are a document summarization expert...", - model_name="gpt-4o", - max_loops=1, -) - -financial_analyst_agent = Agent( - agent_name="Financial-Analyst", - system_prompt="You are a financial analysis specialist...", - model_name="gpt-4o", - max_loops=1, -) -``` - -### 2. Create SwarmRouter with Sequential Workflow - -```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 -) - -# Run a task -result = sequential_router.run("Analyze and summarize the quarterly financial report") -``` - -### 3. Create SwarmRouter with Concurrent Workflow - -```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 -) - -# Run a task -result = concurrent_router.run("Evaluate multiple aspects of the company simultaneously") -``` - -### 4. Create SwarmRouter with AgentRearrange - -```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 -) - -# Run a task -result = rearrange_router.run("Process and analyze company documents") -``` - -### 5. Create SwarmRouter with MixtureOfAgents - -```python -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 -) - -# Run a task -result = mixture_router.run("Provide comprehensive analysis of company performance") -``` - -## Advanced Features - -### 1. Error Handling and Logging - -```python -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. Custom Configuration - -```python -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" -) -``` - -# Best Practices - -## Choose the appropriate swarm type based on your task requirements: - -| 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 | - -## Configure agents appropriately: - - | 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 | - -## Implement proper error handling: - -| 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 | - -## Optimize performance: - -| 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 | - -## Example Implementation - -Here's a complete example showing how to use SwarmRouter in a real-world scenario: - -```python -import os -from swarms import Agent -from swarms.structs.swarm_router import SwarmRouter, SwarmType - -# Initialize specialized agents -research_agent = Agent( - agent_name="ResearchAgent", - system_prompt="You are a research specialist...", - model_name="gpt-4o", - max_loops=1 -) - -analysis_agent = Agent( - agent_name="AnalysisAgent", - system_prompt="You are an analysis expert...", - model_name="gpt-4o", - max_loops=1 -) - -summary_agent = Agent( - agent_name="SummaryAgent", - system_prompt="You are a summarization specialist...", - model_name="gpt-4o", - max_loops=1 -) - -# 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 -) - -# Run complex task -try: - result = router.run( - "Research and analyze the impact of AI on healthcare, " - "providing a comprehensive summary of findings." - ) - 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)}") -``` - -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. - --------------------------------------------------- - -# 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. - """ - - payload = { - "swarm_name": "Enhanced Financial Analysis Swarm", - "description": "A swarm of agents specialized in performing comprehensive financial analysis, risk assessment, and market recommendations.", - "agents": [ - { - "agent_name": "Equity Analyst", - "description": "Agent specialized in analyzing equities data to provide insights on stock performance and valuation.", - "system_prompt": ( - "You are an experienced equity analyst with expertise in financial markets and stock valuation. " - "Your role is to analyze the provided equities data, including historical performance, financial statements, and market trends. " - "Provide a detailed analysis of the stock's potential, including valuation metrics and growth prospects. " - "Consider macroeconomic factors, industry trends, and company-specific news. Your analysis should be clear, actionable, and well-supported by data." - ), - "model_name": "openai/gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 4000, - "temperature": 0.3, - "auto_generate_prompt": False - }, - { - "agent_name": "Risk Assessor", - "description": "Agent responsible for evaluating the risks associated with equity investments.", - "system_prompt": ( - "You are a certified risk management professional with expertise in financial risk assessment. " - "Your task is to evaluate the risks associated with the provided equities data, including market risk, credit risk, and operational risk. " - "Provide a comprehensive risk analysis, including potential scenarios and their impact on investment performance. " - "Your output should be detailed, reliable, and compliant with current risk management standards." - ), - "model_name": "openai/gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 3000, - "temperature": 0.2, - "auto_generate_prompt": False - }, - { - "agent_name": "Market Advisor", - "description": "Agent dedicated to suggesting investment strategies based on market conditions and equity analysis.", - "system_prompt": ( - "You are a knowledgeable market advisor with expertise in investment strategies and portfolio management. " - "Based on the analysis provided by the Equity Analyst and the risk assessment, your task is to recommend a comprehensive investment strategy. " - "Your suggestions should include asset allocation, diversification strategies, and considerations for market conditions. " - "Explain the rationale behind each recommendation and reference relevant market data where applicable. " - "Your recommendations should be reliable, detailed, and clearly prioritized based on risk and return." - ), - "model_name": "openai/gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 5000, - "temperature": 0.3, - "auto_generate_prompt": False - } - ], - "max_loops": 1, - "swarm_type": "SequentialWorkflow", - "task": equity_data, - } - - # Payload includes the equity data as the task to be processed by the swarm - - response = requests.post( - f"{BASE_URL}/v1/swarm/completions", - headers=headers, - json=payload, - ) - - if response.status_code == 200: - print("Swarm successfully executed!") - return json.dumps(response.json(), indent=4) - else: - print(f"Error {response.status_code}: {response.text}") - return None - - -# Example Equity Data for the Swarm to analyze -if __name__ == "__main__": - equity_data = ( - "Analyze the equity data for Company XYZ, which has shown a 15% increase in revenue over the last quarter, " - "with a P/E ratio of 20 and a market cap of $1 billion. Consider the current market conditions and potential risks." - ) - - financial_output = create_financial_swarm(equity_data) - print(financial_output) -``` - -4. Run the script: - -```bash -python financial_swarm.py -``` - - - --------------------------------------------------- - -# File: swarms\examples\swarms_api_medical.md - -# Medical 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 medical 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_medical_swarm(patient_case: str): - """ - Constructs and triggers a full-stack medical swarm consisting of three agents: - Diagnostic Specialist, Medical Coder, and Treatment Advisor. - Each agent is provided with a comprehensive, detailed system prompt to ensure high reliability. - """ - - payload = { - "swarm_name": "Enhanced Medical Diagnostic Swarm", - "description": "A swarm of agents specialized in performing comprehensive medical diagnostics, analysis, and coding.", - "agents": [ - { - "agent_name": "Diagnostic Specialist", - "description": "Agent specialized in analyzing patient history, symptoms, lab results, and imaging data to produce accurate diagnoses.", - "system_prompt": ( - "You are an experienced, board-certified medical diagnostician with over 20 years of clinical practice. " - "Your role is to analyze all available patient information—including history, symptoms, lab tests, and imaging results—" - "with extreme attention to detail and clinical nuance. Provide a comprehensive differential diagnosis considering " - "common, uncommon, and rare conditions. Always cross-reference clinical guidelines and evidence-based medicine. " - "Explain your reasoning step by step and provide a final prioritized list of potential diagnoses along with their likelihood. " - "Consider patient demographics, comorbidities, and risk factors. Your diagnosis should be reliable, clear, and actionable." - ), - "model_name": "openai/gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 4000, - "temperature": 0.3, - "auto_generate_prompt": False - }, - { - "agent_name": "Medical Coder", - "description": "Agent responsible for translating medical diagnoses and procedures into accurate standardized medical codes (ICD-10, CPT, etc.).", - "system_prompt": ( - "You are a certified and experienced medical coder, well-versed in ICD-10, CPT, and other coding systems. " - "Your task is to convert detailed medical diagnoses and treatment procedures into precise, standardized codes. " - "Consider all aspects of the clinical documentation including severity, complications, and comorbidities. " - "Provide clear explanations for the codes chosen, referencing the latest coding guidelines and payer policies where relevant. " - "Your output should be comprehensive, reliable, and fully compliant with current medical coding standards." - ), - "model_name": "openai/gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 3000, - "temperature": 0.2, - "auto_generate_prompt": False - }, - { - "agent_name": "Treatment Advisor", - "description": "Agent dedicated to suggesting evidence-based treatment options, including pharmaceutical and non-pharmaceutical interventions.", - "system_prompt": ( - "You are a highly knowledgeable medical treatment specialist with expertise in the latest clinical guidelines and research. " - "Based on the diagnostic conclusions provided, your task is to recommend a comprehensive treatment plan. " - "Your suggestions should include first-line therapies, potential alternative treatments, and considerations for patient-specific factors " - "such as allergies, contraindications, and comorbidities. Explain the rationale behind each treatment option and reference clinical guidelines where applicable. " - "Your recommendations should be reliable, detailed, and clearly prioritized based on efficacy and safety." - ), - "model_name": "openai/gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 5000, - "temperature": 0.3, - "auto_generate_prompt": False - } - ], - "max_loops": 1, - "swarm_type": "SequentialWorkflow", - "task": patient_case, - } - - # Payload includes the patient case as the task to be processed by the swar - - response = requests.post( - f"{BASE_URL}/v1/swarm/completions", - headers=headers, - json=payload, - ) - - if response.status_code == 200: - print("Swarm successfully executed!") - return json.dumps(response.json(), indent=4) - else: - print(f"Error {response.status_code}: {response.text}") - return None - - -# Example Patient Task for the Swarm to diagnose and analyze -if __name__ == "__main__": - patient_case = ( - "Patient is a 55-year-old male presenting with severe chest pain, shortness of breath, elevated blood pressure, " - "nausea, and a family history of cardiovascular disease. Blood tests show elevated troponin levels, and EKG indicates ST-segment elevations. " - "The patient is currently unstable. Provide a detailed diagnosis, coding, and treatment plan." - ) - - diagnostic_output = create_medical_swarm(patient_case) - print(diagnostic_output) -``` - -4. Run the script: - -```bash -python medical_swarm.py -``` - --------------------------------------------------- - -# File: swarms\examples\swarms_api_ml_model.md - -# ML Model Code Generation 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 following 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_ml_code_swarm(task_description: str): - """ - Constructs and triggers a swarm of agents for generating a complete machine learning project using PyTorch. - The swarm includes: - - Model Code Generator: Generates the PyTorch model architecture code. - - Training Script Generator: Creates a comprehensive training, validation, and testing script using PyTorch. - - Unit Test Creator: Produces extensive unit tests and helper code, ensuring correctness of the model and training scripts. - Each agent's prompt is highly detailed to output only Python code, with exclusive use of PyTorch. - """ - payload = { - "swarm_name": "Comprehensive PyTorch Code Generation Swarm", - "description": ( - "A production-grade swarm of agents tasked with generating a complete machine learning project exclusively using PyTorch. " - "The swarm is divided into distinct roles: one agent generates the core model architecture code; " - "another creates the training and evaluation scripts including data handling; and a third produces " - "extensive unit tests and helper functions. Each agent's instructions are highly detailed to ensure that the " - "output is strictly Python code with PyTorch as the only deep learning framework." - ), - "agents": [ - { - "agent_name": "Model Code Generator", - "description": "Generates the complete machine learning model architecture code using PyTorch.", - "system_prompt": ( - "You are an expert machine learning engineer with a deep understanding of PyTorch. " - "Your task is to generate production-ready Python code that defines a complete deep learning model architecture exclusively using PyTorch. " - "The code must include all necessary imports, class or function definitions, and should be structured in a modular and scalable manner. " - "Follow PEP8 standards and output only code—no comments, explanations, or extraneous text. " - "Your model definition should include proper layer initialization, activation functions, dropout, and any custom components as required. " - "Ensure that the entire output is strictly Python code based on PyTorch." - ), - "model_name": "openai/gpt-4o", - "role": "worker", - "max_loops": 2, - "max_tokens": 4000, - "temperature": 0.3, - "auto_generate_prompt": False - }, - { - "agent_name": "Training Script Generator", - "description": "Creates a comprehensive training, validation, and testing script using PyTorch.", - "system_prompt": ( - "You are a highly skilled software engineer specializing in machine learning pipeline development with PyTorch. " - "Your task is to generate Python code that builds a complete training pipeline using PyTorch. " - "The script must include robust data loading, preprocessing, augmentation, and a complete training loop, along with validation and testing procedures. " - "All necessary imports should be included and the code should assume that the model code from the previous agent is available via proper module imports. " - "Follow best practices for reproducibility and modularity, and output only code without any commentary or non-code text. " - "The entire output must be strictly Python code that uses PyTorch for all deep learning operations." - ), - "model_name": "openai/gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 3000, - "temperature": 0.3, - "auto_generate_prompt": False - }, - { - "agent_name": "Unit Test Creator", - "description": "Develops a suite of unit tests and helper functions for verifying the PyTorch model and training pipeline.", - "system_prompt": ( - "You are an experienced software testing expert with extensive experience in writing unit tests for machine learning projects in PyTorch. " - "Your task is to generate Python code that consists solely of unit tests and any helper functions required to validate both the PyTorch model and the training pipeline. " - "Utilize testing frameworks such as pytest or unittest. The tests should cover key functionalities such as model instantiation, forward pass correctness, " - "training loop execution, data preprocessing verification, and error handling. " - "Ensure that your output is only Python code, without any additional text or commentary, and that it is ready to be integrated into a CI/CD pipeline. " - "The entire output must exclusively use PyTorch as the deep learning framework." - ), - "model_name": "openai/gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 3000, - "temperature": 0.3, - "auto_generate_prompt": False - } - ], - "max_loops": 3, - "swarm_type": "SequentialWorkflow" # Sequential workflow: later agents can assume outputs from earlier ones - } - - # The task description provides the high-level business requirement for the swarm. - payload = { - "task": task_description, - "swarm": payload - } - - response = requests.post( - f"{BASE_URL}/swarm/completion", - headers=headers, - json=payload, - ) - - if response.status_code == 200: - print("PyTorch Code Generation Swarm successfully executed!") - return json.dumps(response.json(), indent=4) - else: - print(f"Error {response.status_code}: {response.text}") - return None - -# Example business task for the swarm: generating a full-stack machine learning pipeline for image classification using PyTorch. -if __name__ == "__main__": - task_description = ( - "Develop a full-stack machine learning pipeline for image classification using PyTorch. " - "The project must include a deep learning model using a CNN architecture for image recognition, " - "a comprehensive training script for data preprocessing, augmentation, training, validation, and testing, " - "and an extensive suite of unit tests to validate every component. " - "Each component's output must be strictly Python code with no additional text or commentary, using PyTorch exclusively." - ) - - output = create_ml_code_swarm(task_description) - print(output) - -``` - --------------------------------------------------- - -# File: swarms\examples\swarms_dao.md - -# Swarms DAO Example - -This example demonstrates how to create a swarm of agents to collaborate on a task. The agents are designed to work together to create a comprehensive strategy for a DAO focused on decentralized governance for climate action. - -You can customize the agents and their system prompts to fit your specific needs. - -And, this example is using the `deepseek-reasoner` model, which is a large language model that is optimized for reasoning tasks. - - -## Todo -- Add tools to check wallet of the treasury and check the balance of the treasury -- Add tools to check the price of the token -- Add tools to check the price of the token on different exchanges -- Add tools to check the price of the token on different chains -- Add tools to check twitter posts and check the sentiment of the posts - -```python -import random -from swarms import Agent - -# System prompts for each agent -MARKETING_AGENT_SYS_PROMPT = """ -You are the Marketing Strategist Agent for a DAO. Your role is to develop, implement, and optimize all marketing and branding strategies to align with the DAO's mission and vision. The DAO is focused on decentralized governance for climate action, funding projects aimed at reducing carbon emissions, and incentivizing community participation through its native token. - -### Objectives: -1. **Brand Awareness**: Build a globally recognized and trusted brand for the DAO. -2. **Community Growth**: Expand the DAO's community by onboarding individuals passionate about climate action and blockchain technology. -3. **Campaign Execution**: Launch high-impact marketing campaigns on platforms like Twitter, Discord, and YouTube to engage and retain community members. -4. **Partnerships**: Identify and build partnerships with like-minded organizations, NGOs, and influencers. -5. **Content Strategy**: Design educational and engaging content, including infographics, blog posts, videos, and AMAs. - -### Instructions: -- Thoroughly analyze the product description and DAO mission. -- Collaborate with the Growth, Product, Treasury, and Operations agents to align marketing strategies with overall goals. -- Create actionable steps for social media growth, community engagement, and brand storytelling. -- Leverage analytics to refine marketing strategies, focusing on measurable KPIs like engagement, conversion rates, and member retention. -- Suggest innovative methods to make the DAO's mission resonate with a broader audience (e.g., gamified incentives, contests, or viral campaigns). -- Ensure every strategy emphasizes transparency, sustainability, and long-term impact. -""" - -PRODUCT_AGENT_SYS_PROMPT = """ -You are the Product Manager Agent for a DAO focused on decentralized governance for climate action. Your role is to design, manage, and optimize the DAO's product roadmap. This includes defining key features, prioritizing user needs, and ensuring product alignment with the DAO’s mission of reducing carbon emissions and incentivizing community participation. - -### Objectives: -1. **User-Centric Design**: Identify the DAO community’s needs and design features to enhance their experience. -2. **Roadmap Prioritization**: Develop a prioritized product roadmap based on community feedback and alignment with climate action goals. -3. **Integration**: Suggest technical solutions and tools for seamless integration with other platforms and blockchains. -4. **Continuous Improvement**: Regularly evaluate product features and recommend optimizations to improve usability, engagement, and adoption. - -### Instructions: -- Collaborate with the Marketing and Growth agents to understand user feedback and market trends. -- Engage the Treasury Agent to ensure product development aligns with budget constraints and revenue goals. -- Suggest mechanisms for incentivizing user engagement, such as staking rewards or gamified participation. -- Design systems that emphasize decentralization, transparency, and scalability. -- Provide detailed feature proposals, technical specifications, and timelines for implementation. -- Ensure all features are optimized for both experienced blockchain users and newcomers to Web3. -""" - -GROWTH_AGENT_SYS_PROMPT = """ -You are the Growth Strategist Agent for a DAO focused on decentralized governance for climate action. Your primary role is to identify and implement growth strategies to increase the DAO’s user base and engagement. - -### Objectives: -1. **User Acquisition**: Identify effective strategies to onboard more users to the DAO. -2. **Retention**: Suggest ways to improve community engagement and retain active members. -3. **Data-Driven Insights**: Leverage data analytics to identify growth opportunities and areas of improvement. -4. **Collaborative Growth**: Work with other agents to align growth efforts with marketing, product development, and treasury goals. - -### Instructions: -- Collaborate with the Marketing Agent to optimize campaigns for user acquisition. -- Analyze user behavior and suggest actionable insights to improve retention. -- Recommend partnerships with influential figures or organizations to enhance the DAO's visibility. -- Propose growth experiments (A/B testing, new incentives, etc.) and analyze their effectiveness. -- Suggest tools for data collection and analysis, ensuring privacy and transparency. -- Ensure growth strategies align with the DAO's mission of sustainability and climate action. -""" - -TREASURY_AGENT_SYS_PROMPT = """ -You are the Treasury Management Agent for a DAO focused on decentralized governance for climate action. Your role is to oversee the DAO's financial operations, including budgeting, funding allocation, and financial reporting. - -### Objectives: -1. **Financial Transparency**: Maintain clear and detailed reports of the DAO's financial status. -2. **Budget Management**: Allocate funds strategically to align with the DAO's goals and priorities. -3. **Fundraising**: Identify and recommend strategies for fundraising to ensure the DAO's financial sustainability. -4. **Cost Optimization**: Suggest ways to reduce operational costs without sacrificing quality. - -### Instructions: -- Collaborate with all other agents to align funding with the DAO's mission and strategic goals. -- Propose innovative fundraising campaigns (e.g., NFT drops, token sales) to generate revenue. -- Analyze financial risks and suggest mitigation strategies. -- Ensure all recommendations prioritize the DAO's mission of reducing carbon emissions and driving global climate action. -- Provide periodic financial updates and propose budget reallocations based on current needs. -""" - -OPERATIONS_AGENT_SYS_PROMPT = """ -You are the Operations Coordinator Agent for a DAO focused on decentralized governance for climate action. Your role is to ensure smooth day-to-day operations, coordinate workflows, and manage governance processes. - -### Objectives: -1. **Workflow Optimization**: Streamline operational processes to maximize efficiency and effectiveness. -2. **Task Coordination**: Manage and delegate tasks to ensure timely delivery of goals. -3. **Governance**: Oversee governance processes, including proposal management and voting mechanisms. -4. **Communication**: Ensure seamless communication between all agents and community members. - -### Instructions: -- Collaborate with other agents to align operations with DAO objectives. -- Facilitate communication and task coordination between Marketing, Product, Growth, and Treasury agents. -- Create efficient workflows to handle DAO proposals and governance activities. -- Suggest tools or platforms to improve operational efficiency. -- Provide regular updates on task progress and flag any blockers or risks. -""" - -# Initialize agents -marketing_agent = Agent( - agent_name="Marketing-Agent", - system_prompt=MARKETING_AGENT_SYS_PROMPT, - model_name="deepseek/deepseek-reasoner", - autosave=True, - dashboard=False, - verbose=True, -) - -product_agent = Agent( - agent_name="Product-Agent", - system_prompt=PRODUCT_AGENT_SYS_PROMPT, - model_name="deepseek/deepseek-reasoner", - autosave=True, - dashboard=False, - verbose=True, -) - -growth_agent = Agent( - agent_name="Growth-Agent", - system_prompt=GROWTH_AGENT_SYS_PROMPT, - model_name="deepseek/deepseek-reasoner", - autosave=True, - dashboard=False, - verbose=True, -) - -treasury_agent = Agent( - agent_name="Treasury-Agent", - system_prompt=TREASURY_AGENT_SYS_PROMPT, - model_name="deepseek/deepseek-reasoner", - autosave=True, - dashboard=False, - verbose=True, -) - -operations_agent = Agent( - agent_name="Operations-Agent", - system_prompt=OPERATIONS_AGENT_SYS_PROMPT, - model_name="deepseek/deepseek-reasoner", - autosave=True, - dashboard=False, - verbose=True, -) - -agents = [marketing_agent, product_agent, growth_agent, treasury_agent, operations_agent] - - -class DAOSwarmRunner: - """ - A class to manage and run a swarm of agents in a discussion. - """ - - def __init__(self, agents: list, max_loops: int = 5, shared_context: str = "") -> None: - """ - Initializes the DAO Swarm Runner. - - Args: - agents (list): A list of agents in the swarm. - max_loops (int, optional): The maximum number of discussion loops between agents. Defaults to 5. - shared_context (str, optional): The shared context for all agents to base their discussion on. Defaults to an empty string. - """ - self.agents = agents - self.max_loops = max_loops - self.shared_context = shared_context - self.discussion_history = [] - - def run(self, task: str) -> str: - """ - Runs the swarm in a random discussion. - - Args: - task (str): The task or context that agents will discuss. - - Returns: - str: The final discussion output after all loops. - """ - print(f"Task: {task}") - print("Initializing Random Discussion...") - - # Initialize the discussion with the shared context - current_message = f"Task: {task}\nContext: {self.shared_context}" - self.discussion_history.append(current_message) - - # Run the agents in a randomized discussion - for loop in range(self.max_loops): - print(f"\n--- Loop {loop + 1}/{self.max_loops} ---") - # Choose a random agent - agent = random.choice(self.agents) - print(f"Agent {agent.agent_name} is responding...") - - # Run the agent and get a response - response = agent.run(current_message) - print(f"Agent {agent.agent_name} says:\n{response}\n") - - # Append the response to the discussion history - self.discussion_history.append(f"{agent.agent_name}: {response}") - - # Update the current message for the next agent - current_message = response - - print("\n--- Discussion Complete ---") - return "\n".join(self.discussion_history) - - -swarm = DAOSwarmRunner(agents=agents, max_loops=1, shared_context="") - -# User input for product description -product_description = """ -The DAO is focused on decentralized governance for climate action. -It funds projects aimed at reducing carbon emissions and incentivizes community participation with a native token. -""" - -# Assign a shared context for all agents -swarm.shared_context = product_description - -# Run the swarm -task = """ -Analyze the product description and create a collaborative strategy for marketing, product, growth, treasury, and operations. Ensure all recommendations align with the DAO's mission of reducing carbon emissions. -""" -output = swarm.run(task) - -# Print the swarm output -print("Collaborative Strategy Output:\n", output) - -``` - --------------------------------------------------- - -# File: swarms\examples\swarms_of_browser_agents.md - -# Swarms x Browser Use - -- Import required modules - -- Configure your agent first by making a new class - -- Set your api keys for your model provider in the `.env` file such as `OPENAI_API_KEY="sk-"` - -- Conigure your `ConcurrentWorkflow` - -## Install - -```bash -pip install swarms browser-use langchain-openai -``` --------- - - -## Main -```python -import asyncio - -from browser_use import Agent -from dotenv import load_dotenv -from langchain_openai import ChatOpenAI - -from swarms import ConcurrentWorkflow - -load_dotenv() - - -class BrowserAgent: - def __init__(self, agent_name: str = "BrowserAgent"): - self.agent_name = agent_name - - async def browser_agent_test(self, task: str): - agent = Agent( - task=task, - llm=ChatOpenAI(model="gpt-4o"), - ) - result = await agent.run() - return result - - def run(self, task: str): - return asyncio.run(self.browser_agent_test(task)) - - -swarm = ConcurrentWorkflow( - agents=[BrowserAgent() for _ in range(3)], -) - -swarm.run( - """ - Go to pump.fun. - - 2. Make an account: use email: "test@test.com" and password: "test1234" - - 3. Make a coin called and give it a cool description and etc. Fill in the form - - 4. Sit back and watch the coin grow in value. - - """ -) - -``` - --------------------------------------------------- - -# File: swarms\examples\swarms_tools_htx.md - -# Swarms Tools Example with HTX + CoinGecko - -- `pip3 install swarms swarms-tools` -- Add `OPENAI_API_KEY` to your `.env` file - -```python -from swarms import Agent -from swarms.prompts.finance_agent_sys_prompt import ( - FINANCIAL_AGENT_SYS_PROMPT, -) -from swarms_tools import ( - coin_gecko_coin_api, - fetch_htx_data, -) - - -# Initialize the agent -agent = Agent( - agent_name="Financial-Analysis-Agent", - agent_description="Personal finance advisor agent", - system_prompt=FINANCIAL_AGENT_SYS_PROMPT, - max_loops=1, - model_name="gpt-4o", - dynamic_temperature_enabled=True, - user_name="swarms_corp", - return_step_meta=False, - output_type="str", # "json", "dict", "csv" OR "string" "yaml" and - auto_generate_prompt=False, # Auto generate prompt for the agent based on name, description, and system prompt, task - max_tokens=4000, # max output tokens - saved_state_path="agent_00.json", - interactive=False, -) - -agent.run( - f"Analyze the $swarms token on HTX with data: {fetch_htx_data('swarms')}. Additionally, consider the following CoinGecko data: {coin_gecko_coin_api('swarms')}" -) -``` - --------------------------------------------------- - -# File: swarms\examples\swarms_tools_htx_gecko.md - -# Swarms Tools Example with HTX + CoinGecko - -- `pip3 install swarms swarms-tools` -- Add `OPENAI_API_KEY` to your `.env` file -- Run `swarms_tools_htx_gecko.py` -- Agent will make a function call to the desired tool -- The tool will be executed and the result will be returned to the agent -- The agent will then analyze the result and return the final output - - -```python -from swarms import Agent -from swarms.prompts.finance_agent_sys_prompt import ( - FINANCIAL_AGENT_SYS_PROMPT, -) -from swarms_tools import ( - fetch_stock_news, - coin_gecko_coin_api, - fetch_htx_data, -) - -# Initialize the agent -agent = Agent( - agent_name="Financial-Analysis-Agent", - agent_description="Personal finance advisor agent", - system_prompt=FINANCIAL_AGENT_SYS_PROMPT, - max_loops=1, - model_name="gpt-4o", - dynamic_temperature_enabled=True, - user_name="swarms_corp", - retry_attempts=3, - context_length=8192, - return_step_meta=False, - output_type="str", # "json", "dict", "csv" OR "string" "yaml" and - auto_generate_prompt=False, # Auto generate prompt for the agent based on name, description, and system prompt, task - max_tokens=4000, # max output tokens - saved_state_path="agent_00.json", - interactive=False, - tools=[fetch_stock_news, coin_gecko_coin_api, fetch_htx_data], -) - -agent.run("Analyze the $swarms token on htx") -``` - --------------------------------------------------- - -# 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. - -# Documentation - -## Table of Contents -1. [Common Parameters](#common-parameters) -2. [Basic Swarm Patterns](#basic-swarm-patterns) -3. [Mathematical Swarm Patterns](#mathematical-swarm-patterns) -4. [Advanced Swarm Patterns](#advanced-swarm-patterns) -5. [Communication Patterns](#communication-patterns) -6. [Best Practices](#best-practices) -7. [Common Use Cases](#common-use-cases) - -## Common Parameters - -All swarm architectures accept these base parameters: - -- `agents: AgentListType` - List of Agent objects to participate in the swarm -- `tasks: List[str]` - List of tasks to be processed by the agents -- `return_full_history: bool` (optional) - If True, returns conversation history. Defaults to True - -Return types are generally `Union[dict, List[str]]`, where: -- If `return_full_history=True`: Returns a dictionary containing the full conversation history -- If `return_full_history=False`: Returns a list of agent responses - -## Basic Swarm Patterns - -### Circular Swarm -```python -def circular_swarm(agents: AgentListType, tasks: List[str], return_full_history: bool = True) -``` - -**Information Flow:** -```mermaid -flowchart LR - subgraph Circular Flow - A1((Agent 1)) --> A2((Agent 2)) - A2 --> A3((Agent 3)) - A3 --> A4((Agent 4)) - A4 --> A1 - end - Task1[Task 1] --> A1 - Task2[Task 2] --> A2 - Task3[Task 3] --> A3 -``` - -**Best Used When:** - -- You need continuous processing of tasks - -- Tasks need to be processed by every agent in sequence - -- You want predictable, ordered task distribution - -**Key Features:** - -- Tasks move in a circular pattern through all agents - -- Each agent processes each task once - -- Maintains strict ordering of task processing - -### Linear Swarm -```python -def linear_swarm(agents: AgentListType, tasks: List[str], return_full_history: bool = True) -``` - -**Information Flow:** -```mermaid -flowchart LR - Input[Task Input] --> A1 - subgraph Sequential Processing - A1((Agent 1)) --> A2((Agent 2)) - A2 --> A3((Agent 3)) - A3 --> A4((Agent 4)) - A4 --> A5((Agent 5)) - end - A5 --> Output[Final Result] -``` - -**Best Used When:** - -- Tasks need sequential, pipeline-style processing - -- Each agent performs a specific transformation step - -- Order of processing is critical - -### Star Swarm -```python -def star_swarm(agents: AgentListType, tasks: List[str], return_full_history: bool = True) -``` - -**Information Flow:** -```mermaid -flowchart TD - subgraph Star Pattern - A1((Central Agent)) - A2((Agent 2)) - A3((Agent 3)) - A4((Agent 4)) - A5((Agent 5)) - A1 --> A2 - A1 --> A3 - A1 --> A4 - A1 --> A5 - end - Task[Initial Task] --> A1 - A2 --> Result2[Result 2] - A3 --> Result3[Result 3] - A4 --> Result4[Result 4] - A5 --> Result5[Result 5] -``` - -**Best Used When:** - -- You need centralized control - -- Tasks require coordination or oversight - -- You want to maintain a single point of task distribution - -### Mesh Swarm -```python -def mesh_swarm(agents: AgentListType, tasks: List[str], return_full_history: bool = True) -``` - -**Information Flow:** -```mermaid -flowchart TD - subgraph Mesh Network - A1((Agent 1)) <--> A2((Agent 2)) - A2 <--> A3((Agent 3)) - A1 <--> A4((Agent 4)) - A2 <--> A5((Agent 5)) - A3 <--> A6((Agent 6)) - A4 <--> A5 - A5 <--> A6 - end - Tasks[Task Pool] --> A1 - Tasks --> A2 - Tasks --> A3 - Tasks --> A4 - Tasks --> A5 - Tasks --> A6 -``` - -**Best Used When:** - -- You need maximum flexibility - -- Task processing order isn't critical - -- You want fault tolerance - -## Mathematical Swarm Patterns - -### Fibonacci Swarm -```python -def fibonacci_swarm(agents: AgentListType, tasks: List[str]) -``` - -**Information Flow:** -```mermaid -flowchart TD - subgraph Fibonacci Pattern - L1[Level 1: 1 Agent] --> L2[Level 2: 1 Agent] - L2 --> L3[Level 3: 2 Agents] - L3 --> L4[Level 4: 3 Agents] - L4 --> L5[Level 5: 5 Agents] - end - Task[Initial Task] --> L1 - L5 --> Results[Processed Results] -``` - -**Best Used When:** - -- You need natural scaling patterns - -- Tasks have increasing complexity - -- You want organic growth in processing capacity - -### Pyramid Swarm -```python -def pyramid_swarm(agents: AgentListType, tasks: List[str], return_full_history: bool = True) -``` - -**Information Flow:** -```mermaid -flowchart TD - subgraph Pyramid Structure - A1((Leader Agent)) - A2((Manager 1)) - A3((Manager 2)) - A4((Worker 1)) - A5((Worker 2)) - A6((Worker 3)) - A7((Worker 4)) - A1 --> A2 - A1 --> A3 - A2 --> A4 - A2 --> A5 - A3 --> A6 - A3 --> A7 - end - Task[Complex Task] --> A1 - A4 --> Result1[Output 1] - A5 --> Result2[Output 2] - A6 --> Result3[Output 3] - A7 --> Result4[Output 4] -``` - -**Best Used When:** - -- You need hierarchical task processing - -- Tasks require multiple levels of oversight - -- You want organized task delegation - -### Grid Swarm -```python -def grid_swarm(agents: AgentListType, tasks: List[str]) -``` - -**Information Flow:** -```mermaid -flowchart TD - subgraph Grid Layout - A1((1)) <--> A2((2)) <--> A3((3)) - A4((4)) <--> A5((5)) <--> A6((6)) - A7((7)) <--> A8((8)) <--> A9((9)) - A1 <--> A4 <--> A7 - A2 <--> A5 <--> A8 - A3 <--> A6 <--> A9 - end - Tasks[Task Queue] --> A1 - Tasks --> A5 - Tasks --> A9 -``` - -**Best Used When:** - -- Tasks have spatial relationships - -- You need neighbor-based processing - -- You want structured parallel processing - -## Communication Patterns - -### One-to-One Communication -```python -def one_to_one(sender: Agent, receiver: Agent, task: str, max_loops: int = 1) -> str -``` - -**Information Flow:** -```mermaid -flowchart LR - Task[Task] --> S((Sender)) - S --> R((Receiver)) - R --> Result[Result] -``` - -**Best Used When:** - -- Direct agent communication is needed - -- Tasks require back-and-forth interaction - -- You need controlled message exchange - -### Broadcast Communication -```python -async def broadcast(sender: Agent, agents: AgentListType, task: str) -> None -``` - -**Information Flow:** -```mermaid -flowchart TD - T[Task] --> S((Sender)) - S --> A1((Agent 1)) - S --> A2((Agent 2)) - S --> A3((Agent 3)) - S --> A4((Agent 4)) -``` - -**Best Used When:** - -- Information needs to reach all agents - -- Tasks require global coordination - -- You need system-wide updates - -## Best Practices - -1. **Choose the Right Pattern:** - - Consider your task's natural structure - - Think about scaling requirements - - Consider fault tolerance needs - -2. **Performance Considerations:** - - More complex patterns have higher overhead - - Consider communication costs - - Match pattern to available resources - -3. **Error Handling:** - - All patterns include basic error checking - - Consider adding additional error handling for production - - Monitor agent performance and task completion - -4. **Scaling:** - - Different patterns scale differently - - Consider future growth needs - - Test with expected maximum load - -## Common Use Cases - -1. **Data Processing Pipelines** - - Linear Swarm - - Circular Swarm - -2. **Distributed Computing** - - Mesh Swarm - - Grid Swarm - -3. **Hierarchical Systems** - - Pyramid Swarm - - Star Swarm - -4. **Dynamic Workloads** - - Exponential Swarm - - Fibonacci Swarm - -5. **Conflict-Free Processing** - - Prime Swarm - - Harmonic Swarm - - -```python -import asyncio -from typing import List - -from swarms.structs.agent import Agent -from swarms.structs.swarming_architectures import ( - broadcast, - circular_swarm, - exponential_swarm, - fibonacci_swarm, - grid_swarm, - linear_swarm, - mesh_swarm, - one_to_three, - prime_swarm, - sigmoid_swarm, - sinusoidal_swarm, - staircase_swarm, - star_swarm, -) - - -def create_finance_agents() -> List[Agent]: - """Create specialized finance agents""" - return [ - Agent( - agent_name="MarketAnalyst", - system_prompt="You are a market analysis expert. Analyze market trends and provide insights.", - model_name="gpt-4o-mini" - ), - Agent( - agent_name="RiskManager", - system_prompt="You are a risk management specialist. Evaluate risks and provide mitigation strategies.", - model_name="gpt-4o-mini" - ), - Agent( - agent_name="PortfolioManager", - system_prompt="You are a portfolio management expert. Optimize investment portfolios and asset allocation.", - model_name="gpt-4o-mini" - ), - Agent( - agent_name="ComplianceOfficer", - system_prompt="You are a financial compliance expert. Ensure regulatory compliance and identify issues.", - model_name="gpt-4o-mini" - ) - ] - -def create_healthcare_agents() -> List[Agent]: - """Create specialized healthcare agents""" - return [ - Agent( - agent_name="Diagnostician", - system_prompt="You are a medical diagnostician. Analyze symptoms and suggest potential diagnoses.", - model_name="gpt-4o-mini" - ), - Agent( - agent_name="Treatment_Planner", - system_prompt="You are a treatment planning specialist. Develop comprehensive treatment plans.", - model_name="gpt-4o-mini" - ), - Agent( - agent_name="MedicalResearcher", - system_prompt="You are a medical researcher. Analyze latest research and provide evidence-based recommendations.", - model_name="gpt-4o-mini" - ), - Agent( - agent_name="PatientCareCoordinator", - system_prompt="You are a patient care coordinator. Manage patient care workflow and coordination.", - model_name="gpt-4o-mini" - ) - ] - -def print_separator(): - print("\n" + "="*50 + "\n") - -def run_finance_circular_swarm(): - """Investment analysis workflow using circular swarm""" - print_separator() - print("FINANCE - INVESTMENT ANALYSIS (Circular Swarm)") - - agents = create_finance_agents() - tasks = [ - "Analyze Tesla stock performance for Q4 2024", - "Assess market risks and potential hedging strategies", - "Recommend portfolio adjustments based on analysis" - ] - - print("\nTasks:") - for i, task in enumerate(tasks, 1): - print(f"{i}. {task}") - - result = circular_swarm(agents, tasks) - print("\nResults:") - for log in result['history']: - print(f"\n{log['agent_name']}:") - print(f"Task: {log['task']}") - print(f"Response: {log['response']}") - -def run_healthcare_grid_swarm(): - """Patient diagnosis and treatment planning using grid swarm""" - print_separator() - print("HEALTHCARE - PATIENT DIAGNOSIS (Grid Swarm)") - - agents = create_healthcare_agents() - tasks = [ - "Review patient symptoms: fever, fatigue, joint pain", - "Research latest treatment protocols", - "Develop preliminary treatment plan", - "Coordinate with specialists" - ] - - print("\nTasks:") - for i, task in enumerate(tasks, 1): - print(f"{i}. {task}") - - result = grid_swarm(agents, tasks) - print("\nGrid swarm processing completed") - print(result) - -def run_finance_linear_swarm(): - """Loan approval process using linear swarm""" - print_separator() - print("FINANCE - LOAN APPROVAL PROCESS (Linear Swarm)") - - agents = create_finance_agents()[:3] - tasks = [ - "Review loan application and credit history", - "Assess risk factors and compliance requirements", - "Generate final loan recommendation" - ] - - print("\nTasks:") - for i, task in enumerate(tasks, 1): - print(f"{i}. {task}") - - result = linear_swarm(agents, tasks) - print("\nResults:") - for log in result['history']: - print(f"\n{log['agent_name']}:") - print(f"Task: {log['task']}") - print(f"Response: {log['response']}") - -def run_healthcare_star_swarm(): - """Complex medical case management using star swarm""" - print_separator() - print("HEALTHCARE - COMPLEX CASE MANAGEMENT (Star Swarm)") - - agents = create_healthcare_agents() - tasks = [ - "Complex case: Patient with multiple chronic conditions", - "Develop integrated care plan" - ] - - print("\nTasks:") - for i, task in enumerate(tasks, 1): - print(f"{i}. {task}") - - result = star_swarm(agents, tasks) - print("\nResults:") - for log in result['history']: - print(f"\n{log['agent_name']}:") - print(f"Task: {log['task']}") - print(f"Response: {log['response']}") - -def run_finance_mesh_swarm(): - """Market risk assessment using mesh swarm""" - print_separator() - print("FINANCE - MARKET RISK ASSESSMENT (Mesh Swarm)") - - agents = create_finance_agents() - tasks = [ - "Analyze global market conditions", - "Assess currency exchange risks", - "Evaluate sector-specific risks", - "Review portfolio exposure" - ] - - print("\nTasks:") - for i, task in enumerate(tasks, 1): - print(f"{i}. {task}") - - result = mesh_swarm(agents, tasks) - print("\nResults:") - for log in result['history']: - print(f"\n{log['agent_name']}:") - print(f"Task: {log['task']}") - print(f"Response: {log['response']}") - -def run_mathematical_finance_swarms(): - """Complex financial analysis using mathematical swarms""" - print_separator() - print("FINANCE - MARKET PATTERN ANALYSIS") - - agents = create_finance_agents() - tasks = [ - "Analyze historical market patterns", - "Predict market trends using technical analysis", - "Identify potential arbitrage opportunities" - ] - - print("\nTasks:") - for i, task in enumerate(tasks, 1): - print(f"{i}. {task}") - - print("\nFibonacci Swarm Results:") - result = fibonacci_swarm(agents, tasks.copy()) - print(result) - - print("\nPrime Swarm Results:") - result = prime_swarm(agents, tasks.copy()) - print(result) - - print("\nExponential Swarm Results:") - result = exponential_swarm(agents, tasks.copy()) - print(result) - -def run_healthcare_pattern_swarms(): - """Patient monitoring using pattern swarms""" - print_separator() - print("HEALTHCARE - PATIENT MONITORING PATTERNS") - - agents = create_healthcare_agents() - task = "Monitor and analyze patient vital signs: BP, heart rate, temperature, O2 saturation" - - print(f"\nTask: {task}") - - print("\nStaircase Pattern Analysis:") - result = staircase_swarm(agents, task) - print(result) - - print("\nSigmoid Pattern Analysis:") - result = sigmoid_swarm(agents, task) - print(result) - - print("\nSinusoidal Pattern Analysis:") - result = sinusoidal_swarm(agents, task) - print(result) - -async def run_communication_examples(): - """Communication patterns for emergency scenarios""" - print_separator() - print("EMERGENCY COMMUNICATION PATTERNS") - - # Finance market alert - finance_sender = create_finance_agents()[0] - finance_receivers = create_finance_agents()[1:] - market_alert = "URGENT: Major market volatility detected - immediate risk assessment required" - - print("\nFinance Market Alert:") - print(f"Alert: {market_alert}") - result = await broadcast(finance_sender, finance_receivers, market_alert) - print("\nBroadcast Results:") - for log in result['history']: - print(f"\n{log['agent_name']}:") - print(f"Response: {log['response']}") - - # Healthcare emergency - health_sender = create_healthcare_agents()[0] - health_receivers = create_healthcare_agents()[1:4] - emergency_case = "EMERGENCY: Trauma patient with multiple injuries - immediate consultation required" - - print("\nHealthcare Emergency:") - print(f"Case: {emergency_case}") - result = await one_to_three(health_sender, health_receivers, emergency_case) - print("\nConsultation Results:") - for log in result['history']: - print(f"\n{log['agent_name']}:") - print(f"Response: {log['response']}") - -async def run_all_examples(): - """Execute all swarm examples""" - print("\n=== SWARM ARCHITECTURE EXAMPLES ===\n") - - # Finance examples - run_finance_circular_swarm() - run_finance_linear_swarm() - run_finance_mesh_swarm() - run_mathematical_finance_swarms() - - # Healthcare examples - run_healthcare_grid_swarm() - run_healthcare_star_swarm() - run_healthcare_pattern_swarms() - - # Communication examples - await run_communication_examples() - - print("\n=== ALL EXAMPLES COMPLETED ===") - -if __name__ == "__main__": - asyncio.run(run_all_examples()) -``` - --------------------------------------------------- - -# 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 - -!!! tip "Quick Summary" - This guide demonstrates how to create a sophisticated multi-agent system using VLLM and Swarms for comprehensive stock market analysis. You'll learn how to configure and orchestrate multiple AI agents working together to provide deep market insights. - -## Overview - -The example showcases how to build a stock analysis system with 5 specialized agents: - -- Technical Analysis Agent -- Fundamental Analysis Agent -- Market Sentiment Agent -- Quantitative Strategy Agent -- Portfolio Strategy Agent - -Each agent has specific expertise and works collaboratively through a concurrent workflow. - -## Prerequisites - -!!! warning "Requirements" - Before starting, ensure you have: - - - Python 3.7 or higher - - The Swarms package installed - - Access to VLLM compatible models - - Sufficient compute resources for running VLLM - -## Installation - -!!! example "Setup Steps" - - 1. Install the Swarms package: - ```bash - pip install swarms - ``` - - 2. Install VLLM dependencies (if not already installed): - ```bash - pip install vllm - ``` - -## Basic Usage - -Here's a complete example of setting up the stock analysis swarm: - -```python -from swarms import Agent, ConcurrentWorkflow -from swarms.utils.vllm_wrapper import VLLMWrapper - -# Initialize the VLLM wrapper -vllm = VLLMWrapper( - model_name="meta-llama/Llama-2-7b-chat-hf", - system_prompt="You are a helpful assistant.", -) -``` - -!!! note "Model Selection" - The example uses Llama-2-7b-chat, but you can use any VLLM-compatible model. Make sure you have the necessary permissions and resources to run your chosen model. - -## Agent Configuration - -### Technical Analysis Agent - -```python -technical_analyst = Agent( - agent_name="Technical-Analysis-Agent", - agent_description="Expert in technical analysis and chart patterns", - system_prompt="""You are an expert Technical Analysis Agent specializing in market technicals and chart patterns. Your responsibilities include: - -1. PRICE ACTION ANALYSIS -- Identify key support and resistance levels -- Analyze price trends and momentum -- Detect chart patterns (e.g., head & shoulders, triangles, flags) -- Evaluate volume patterns and their implications - -2. TECHNICAL INDICATORS -- Calculate and interpret moving averages (SMA, EMA) -- Analyze momentum indicators (RSI, MACD, Stochastic) -- Evaluate volume indicators (OBV, Volume Profile) -- Monitor volatility indicators (Bollinger Bands, ATR) - -3. TRADING SIGNALS -- Generate clear buy/sell signals based on technical criteria -- Identify potential entry and exit points -- Set appropriate stop-loss and take-profit levels -- Calculate position sizing recommendations - -4. RISK MANAGEMENT -- Assess market volatility and trend strength -- Identify potential reversal points -- Calculate risk/reward ratios for trades -- Suggest position sizing based on risk parameters - -Your analysis should be data-driven, precise, and actionable. Always include specific price levels, time frames, and risk parameters in your recommendations.""", - max_loops=1, - llm=vllm, -) -``` - -!!! tip "Agent Customization" - Each agent can be customized with different: - - - System prompts - - - Temperature settings +# 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 - - Max token limits + 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 - - Response formats - -## Running the Swarm - -To execute the swarm analysis: - -```python -swarm = ConcurrentWorkflow( - name="Stock-Analysis-Swarm", - description="A swarm of agents that analyze stocks and provide comprehensive analysis.", - agents=stock_analysis_agents, -) - -# Run the analysis -response = swarm.run("Analyze the best etfs for gold and other similar commodities in volatile markets") -``` - - - -## Full Code Example - -```python -from swarms import Agent, ConcurrentWorkflow -from swarms.utils.vllm_wrapper import VLLMWrapper - -# Initialize the VLLM wrapper -vllm = VLLMWrapper( - model_name="meta-llama/Llama-2-7b-chat-hf", - system_prompt="You are a helpful assistant.", -) - -# Technical Analysis Agent -technical_analyst = Agent( - agent_name="Technical-Analysis-Agent", - agent_description="Expert in technical analysis and chart patterns", - system_prompt="""You are an expert Technical Analysis Agent specializing in market technicals and chart patterns. Your responsibilities include: - -1. PRICE ACTION ANALYSIS -- Identify key support and resistance levels -- Analyze price trends and momentum -- Detect chart patterns (e.g., head & shoulders, triangles, flags) -- Evaluate volume patterns and their implications - -2. TECHNICAL INDICATORS -- Calculate and interpret moving averages (SMA, EMA) -- Analyze momentum indicators (RSI, MACD, Stochastic) -- Evaluate volume indicators (OBV, Volume Profile) -- Monitor volatility indicators (Bollinger Bands, ATR) - -3. TRADING SIGNALS -- Generate clear buy/sell signals based on technical criteria -- Identify potential entry and exit points -- Set appropriate stop-loss and take-profit levels -- Calculate position sizing recommendations - -4. RISK MANAGEMENT -- Assess market volatility and trend strength -- Identify potential reversal points -- Calculate risk/reward ratios for trades -- Suggest position sizing based on risk parameters - -Your analysis should be data-driven, precise, and actionable. Always include specific price levels, time frames, and risk parameters in your recommendations.""", - max_loops=1, - llm=vllm, -) - -# Fundamental Analysis Agent -fundamental_analyst = Agent( - agent_name="Fundamental-Analysis-Agent", - agent_description="Expert in company fundamentals and valuation", - system_prompt="""You are an expert Fundamental Analysis Agent specializing in company valuation and financial metrics. Your core responsibilities include: - -1. FINANCIAL STATEMENT ANALYSIS -- Analyze income statements, balance sheets, and cash flow statements -- Calculate and interpret key financial ratios -- Evaluate revenue growth and profit margins -- Assess company's debt levels and cash position - -2. VALUATION METRICS -- Calculate fair value using multiple valuation methods: - * Discounted Cash Flow (DCF) - * Price-to-Earnings (P/E) - * Price-to-Book (P/B) - * Enterprise Value/EBITDA -- Compare valuations against industry peers - -3. BUSINESS MODEL ASSESSMENT -- Evaluate competitive advantages and market position -- Analyze industry dynamics and market share -- Assess management quality and corporate governance -- Identify potential risks and growth opportunities - -4. ECONOMIC CONTEXT -- Consider macroeconomic factors affecting the company -- Analyze industry cycles and trends -- Evaluate regulatory environment and compliance -- Assess global market conditions - -Your analysis should be comprehensive, focusing on both quantitative metrics and qualitative factors that impact long-term value.""", + 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, - llm=vllm, + model_name="gpt-4o-mini", + output_type="final", + interactive=False, + tools=[run_quant_trading_agent], ) -# Market Sentiment Agent -sentiment_analyst = Agent( - agent_name="Market-Sentiment-Agent", - agent_description="Expert in market psychology and sentiment analysis", - system_prompt="""You are an expert Market Sentiment Agent specializing in analyzing market psychology and investor behavior. Your key responsibilities include: +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) +``` -1. SENTIMENT INDICATORS -- Monitor and interpret market sentiment indicators: - * VIX (Fear Index) - * Put/Call Ratio - * Market Breadth - * Investor Surveys -- Track institutional vs retail investor behavior +## Best Practices -2. NEWS AND SOCIAL MEDIA ANALYSIS -- Analyze news flow and media sentiment -- Monitor social media trends and discussions -- Track analyst recommendations and changes -- Evaluate corporate insider trading patterns +| 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 | -3. MARKET POSITIONING -- Assess hedge fund positioning and exposure -- Monitor short interest and short squeeze potential -- Track fund flows and asset allocation trends -- Analyze options market sentiment -4. CONTRARIAN SIGNALS -- Identify extreme sentiment readings -- Detect potential market turning points -- Analyze historical sentiment patterns -- Provide contrarian trading opportunities +-------------------------------------------------- -Your analysis should combine quantitative sentiment metrics with qualitative assessment of market psychology and crowd behavior.""", - max_loops=1, - llm=vllm, -) +# File: swarms\examples\aggregate.md -# Quantitative Strategy Agent -quant_analyst = Agent( - agent_name="Quantitative-Strategy-Agent", - agent_description="Expert in quantitative analysis and algorithmic strategies", - system_prompt="""You are an expert Quantitative Strategy Agent specializing in data-driven investment strategies. Your primary responsibilities include: +# Aggregate Multi-Agent Responses -1. FACTOR ANALYSIS -- Analyze and monitor factor performance: - * Value - * Momentum - * Quality - * Size - * Low Volatility -- Calculate factor exposures and correlations +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. -2. STATISTICAL ANALYSIS -- Perform statistical arbitrage analysis -- Calculate and monitor pair trading opportunities -- Analyze market anomalies and inefficiencies -- Develop mean reversion strategies +## Installation -3. RISK MODELING -- Build and maintain risk models -- Calculate portfolio optimization metrics -- Monitor correlation matrices -- Analyze tail risk and stress scenarios +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/): -4. ALGORITHMIC STRATEGIES -- Develop systematic trading strategies -- Backtest and validate trading algorithms -- Monitor strategy performance metrics -- Optimize execution algorithms +```bash +pip3 install -U swarms +``` -Your analysis should be purely quantitative, based on statistical evidence and mathematical models rather than subjective opinions.""", - max_loops=1, - llm=vllm, -) +## Environment Variables -# Portfolio Strategy Agent -portfolio_strategist = Agent( - agent_name="Portfolio-Strategy-Agent", - agent_description="Expert in portfolio management and asset allocation", - system_prompt="""You are an expert Portfolio Strategy Agent specializing in portfolio construction and management. Your core responsibilities include: +```txt +WORKSPACE_DIR="" +OPENAI_API_KEY="" +ANTHROPIC_API_KEY="" +``` -1. ASSET ALLOCATION -- Develop strategic asset allocation frameworks -- Recommend tactical asset allocation shifts -- Optimize portfolio weightings -- Balance risk and return objectives +## How It Works -2. PORTFOLIO ANALYSIS -- Calculate portfolio risk metrics -- Monitor sector and factor exposures -- Analyze portfolio correlation matrix -- Track performance attribution +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 -3. RISK MANAGEMENT -- Implement portfolio hedging strategies -- Monitor and adjust position sizing -- Set stop-loss and rebalancing rules -- Develop drawdown protection strategies +## Code Example -4. PORTFOLIO OPTIMIZATION -- Calculate efficient frontier analysis -- Optimize for various objectives: - * Maximum Sharpe Ratio - * Minimum Volatility - * Maximum Diversification -- Consider transaction costs and taxes +```python +from swarms.structs.agent import Agent +from swarms.structs.ma_blocks import aggregate -Your recommendations should focus on portfolio-level decisions that optimize risk-adjusted returns while meeting specific investment objectives.""", - max_loops=1, - llm=vllm, -) -# Create a list of all agents -stock_analysis_agents = [ - technical_analyst, - fundamental_analyst, - sentiment_analyst, - quant_analyst, - portfolio_strategist +# 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, + ), ] -swarm = ConcurrentWorkflow( - name="Stock-Analysis-Swarm", - description="A swarm of agents that analyze stocks and provide a comprehensive analysis of the current trends and opportunities.", - agents=stock_analysis_agents, +# 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" ) -swarm.run("Analyze the best etfs for gold and other similiar commodities in volatile markets") +print(result) ``` -## Best Practices -!!! success "Optimization Tips" - 1. **Agent Design** - - Keep system prompts focused and specific - - - Use clear role definitions - - - Include error handling guidelines - - 2. **Resource Management** - - - Monitor memory usage with large models - - - Implement proper cleanup procedures - - - Use batching for multiple queries - - 3. **Output Handling** - - - Implement proper logging - - - Format outputs consistently - - - Include error checking +-------------------------------------------------- -## Common Issues and Solutions +# File: swarms\examples\azure.md -!!! warning "Troubleshooting" - Common issues you might encounter: +# Azure OpenAI Integration - 1. **Memory Issues** - - - *Problem*: VLLM consuming too much memory - - - *Solution*: Adjust batch sizes and model parameters - - 2. **Agent Coordination** - - - *Problem*: Agents providing conflicting information - - - *Solution*: Implement consensus mechanisms or priority rules - - 3. **Performance** - - - *Problem*: Slow response times - - - *Solution*: Use proper batching and optimize model loading +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. -## FAQ +## Prerequisites -??? question "Can I use different models for different agents?" - Yes, you can initialize multiple VLLM wrappers with different models for each agent. However, be mindful of memory usage. +- Azure subscription with OpenAI service enabled +- Azure OpenAI resource deployed +- Python 3.7+ +- Swarms library +- LiteLLM library -??? question "How many agents can run concurrently?" - The number depends on your hardware resources. Start with 3-5 agents and scale based on performance. +## Installation -??? question "Can I customize agent communication patterns?" - Yes, you can modify the ConcurrentWorkflow class or create custom workflows for specific communication patterns. +First, install the required dependencies: -## Advanced Configuration +```bash +pip install -U swarms +``` -!!! example "Extended Settings" - ```python - vllm = VLLMWrapper( - model_name="meta-llama/Llama-2-7b-chat-hf", - system_prompt="You are a helpful assistant.", - temperature=0.7, - max_tokens=2048, - top_p=0.95, - ) - ``` +## Environment Setup -## Contributing +### 1. Azure OpenAI Configuration -!!! info "Get Involved" - We welcome contributions! Here's how you can help: +Set up your Azure OpenAI environment variables in a `.env` file: - 1. Report bugs and issues - 2. Submit feature requests - 3. Contribute to documentation - 4. Share example use cases +```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 -## Resources +# Optional: Model deployment names (if different from model names) +AZURE_GPT4_DEPLOYMENT_NAME=gpt-4 +AZURE_GPT35_DEPLOYMENT_NAME=gpt-35-turbo +``` -!!! abstract "Additional Reading" - - [VLLM Documentation](https://docs.vllm.ai/en/latest/) - +### 2. Verify Available Models --------------------------------------------------- +Check what Azure models are available using LiteLLM: -# File: swarms\examples\vllm_integration.md +```python +from litellm import model_list +# 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` -# vLLM Integration Guide +## Basic Usage -!!! info "Overview" - vLLM is a high-performance and easy-to-use library for LLM inference and serving. This guide explains how to integrate vLLM with Swarms for efficient, production-grade language model deployment. +### Simple Agent with Azure Model +```python +import os +from dotenv import load_dotenv +from swarms import Agent -## Installation +# Load environment variables +load_dotenv() -!!! note "Prerequisites" - Before you begin, make sure you have Python 3.8+ installed on your system. +# 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", +) -=== "pip" - ```bash - pip install -U vllm swarms - ``` +# Run the agent +response = agent.run("Explain quantum computing in simple terms.") +print(response) +``` -=== "poetry" - ```bash - poetry add vllm swarms - ``` +## Advanced Configuration -## Basic Usage +### Quantitative Trading Agent Example -Here's a simple example of how to use vLLM with Swarms: +Here's a comprehensive example of a quantitative trading agent using Azure models: -```python title="basic_usage.py" -from swarms.utils.vllm_wrapper import VLLMWrapper +```python +import os +from dotenv import load_dotenv +from swarms import Agent -# Initialize the vLLM wrapper -vllm = VLLMWrapper( - model_name="meta-llama/Llama-2-7b-chat-hf", - system_prompt="You are a helpful assistant.", - temperature=0.7, - max_tokens=4000 +# Load environment variables +load_dotenv() + +# 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, ) -# Run inference -response = vllm.run("What is the capital of France?") +# 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) ``` -## VLLMWrapper Class -!!! abstract "Class Overview" - The `VLLMWrapper` class provides a convenient interface for working with vLLM models. +## Next Steps -### Key Parameters +- Check out [LiteLLM Azure integration](https://docs.litellm.ai/docs/providers/azure) -| Parameter | Type | Description | Default | -|-----------|------|-------------|---------| -| `model_name` | str | Name of the model to use | "meta-llama/Llama-2-7b-chat-hf" | -| `system_prompt` | str | System prompt to use | None | -| `stream` | bool | Whether to stream the output | False | -| `temperature` | float | Sampling temperature | 0.5 | -| `max_tokens` | int | Maximum number of tokens to generate | 4000 | +- Learn about [Swarms multi-agent architectures](../structs/index.md) -### Example with Custom Parameters +- Discover [advanced tool integrations](agent_with_tools.md) -```python title="custom_parameters.py" -vllm = VLLMWrapper( - model_name="meta-llama/Llama-2-13b-chat-hf", - system_prompt="You are an expert in artificial intelligence.", - temperature=0.8, - max_tokens=2000 -) -``` -## Integration with Agents +-------------------------------------------------- -You can easily integrate vLLM with Swarms agents for more complex workflows: +# File: swarms\examples\basic_agent.md -```python title="agent_integration.py" -from swarms import Agent -from swarms.utils.vllm_wrapper import VLLMWrapper +# Basic Agent Example -# Initialize vLLM -vllm = VLLMWrapper( - model_name="meta-llama/Llama-2-7b-chat-hf", - system_prompt="You are a helpful assistant." -) +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. -# Create an agent with vLLM -agent = Agent( - agent_name="Research-Agent", - agent_description="Expert in conducting research and analysis", - system_prompt="""You are an expert research agent. Your tasks include: - 1. Analyzing complex topics - 2. Providing detailed summaries - 3. Making data-driven recommendations""", - llm=vllm, - max_loops=1 -) +## Prerequisites -# Run the agent -response = agent.run("Research the impact of AI on healthcare") -``` +- Python 3.7+ -## Advanced Features +- OpenAI API key -### Batch Processing +- Swarms library -!!! tip "Performance Optimization" - Use batch processing for efficient handling of multiple tasks simultaneously. +## Tutorial Steps -```python title="batch_processing.py" -tasks = [ - "What is machine learning?", - "Explain neural networks", - "Describe deep learning" -] +1. First, install the latest version of Swarms: -results = vllm.batched_run(tasks, batch_size=3) +```bash +pip3 install -U swarms ``` -### Error Handling - -!!! warning "Error Management" - Always implement proper error handling in production environments. - -```python title="error_handling.py" -from loguru import logger +2. Set up your environment variables in a `.env` file: -try: - response = vllm.run("Complex task") -except Exception as error: - logger.error(f"Error occurred: {error}") +```plaintext +OPENAI_API_KEY="your-api-key-here" +WORKSPACE_DIR="agent_workspace" ``` -## Best Practices - -!!! success "Recommended Practices" - === "Model Selection" - - Choose appropriate model sizes based on your requirements - - Consider the trade-off between model size and inference speed +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 - === "System Resources" - - Ensure sufficient GPU memory for your chosen model - - Monitor resource usage during batch processing +4. Run the example code below: - === "Prompt Engineering" - - Use clear and specific system prompts - - Structure user prompts for optimal results - === "Error Handling" - - Implement proper error handling and logging - - Set up monitoring for production deployments +## Code - === "Performance" - - Use batch processing for multiple tasks - - Adjust max_tokens based on your use case - - Fine-tune temperature for optimal output quality +```python +import time +from swarms import Agent -## Example: Multi-Agent System +# 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, +) -Here's an example of creating a multi-agent system using vLLM: +out = agent.run("What are the best top 3 etfs for gold coverage?") -```python title="multi_agent_system.py" -from swarms import Agent, ConcurrentWorkflow -from swarms.utils.vllm_wrapper import VLLMWrapper +time.sleep(10) +print(out) +``` -# Initialize vLLM -vllm = VLLMWrapper( - model_name="meta-llama/Llama-2-7b-chat-hf", - system_prompt="You are a helpful assistant." -) +## Example Output -# Create specialized agents -research_agent = Agent( - agent_name="Research-Agent", - agent_description="Expert in research", - system_prompt="You are a research expert.", - llm=vllm -) +The agent will return a JSON response containing recommendations for gold ETFs based on the query. -analysis_agent = Agent( - agent_name="Analysis-Agent", - agent_description="Expert in analysis", - system_prompt="You are an analysis expert.", - llm=vllm -) +## Customization -# Create a workflow -agents = [research_agent, analysis_agent] -workflow = ConcurrentWorkflow( - name="Research-Analysis-Workflow", - description="Comprehensive research and analysis workflow", - agents=agents -) +You can modify the system prompt and agent parameters to create specialized agents for different use cases: -# Run the workflow -result = workflow.run("Analyze the impact of renewable energy") -``` +| 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 | -------------------------------------------------- -# File: swarms\examples\xai.md - -# Agent with XAI +# File: swarms\examples\claude.md -- Add your `XAI_API_KEY` in the `.env` file +# Agent with Anthropic/Claude -- Select your model_name like `xai/grok-beta` follows [LiteLLM conventions](https://docs.litellm.ai/docs/providers/xai) +- Get their api keys and put it in the `.env` -- Execute your agent! +- Select your model_name like `claude-3-sonnet-20240229` follows LiteLLM conventions ```python @@ -28442,7 +17559,7 @@ load_dotenv() # Initialize the agent with ChromaDB memory agent = Agent( agent_name="Financial-Analysis-Agent", - model_name="xai/grok-beta", + model_name="claude-3-sonnet-20240229", system_prompt="Agent system prompt here", agent_description="Agent performs financial analysis.", ) @@ -28453,8483 +17570,9722 @@ agent.run("What are the components of a startup's stock incentive equity plan?") -------------------------------------------------- -# File: swarms\examples\yahoo_finance.md +# File: swarms\examples\cohere.md -# Swarms Tools Example with Yahoo Finance +# Agent with Cohere -- `pip3 install swarms swarms-tools` -- Add `OPENAI_API_KEY` to your `.env` file -- Run `yahoo_finance_agent.py` -- Agent will make a function call to the desired tool -- The tool will be executed and the result will be returned to the agent -- The agent will then analyze the result and return the final output +- Add your `COHERE_API_KEY` in the `.env` file + +- Select your model_name like `command-r` follows LiteLLM conventions ```python from swarms import Agent -from swarms.prompts.finance_agent_sys_prompt import ( - FINANCIAL_AGENT_SYS_PROMPT, -) -from swarms_tools import ( - yahoo_finance_api, -) +import os +from dotenv import load_dotenv -# Initialize the agent +load_dotenv() + +# Initialize the agent with ChromaDB memory agent = Agent( agent_name="Financial-Analysis-Agent", - agent_description="Personal finance advisor agent", - system_prompt=FINANCIAL_AGENT_SYS_PROMPT, - max_loops=1, - model_name="gpt-4o", - dynamic_temperature_enabled=True, - user_name="swarms_corp", - retry_attempts=3, - context_length=8192, - return_step_meta=False, - output_type="str", # "json", "dict", "csv" OR "string" "yaml" and - auto_generate_prompt=False, # Auto generate prompt for the agent based on name, description, and system prompt, task - max_tokens=4000, # max output tokens - saved_state_path="agent_00.json", - interactive=False, - tools=[yahoo_finance_api], + model_name="command-r", + system_prompt="Agent system prompt here", + agent_description="Agent performs financial analysis.", ) -agent.run("Analyze the latest metrics for nvidia") -# Less than 30 lines of code.... +# Run a query +agent.run("What are the components of a startup's stock incentive equity plan?") ``` -------------------------------------------------- -# 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 +# File: swarms\examples\concurrent_workflow.md -- Explore custom enterprise solutions and integrations +# ConcurrentWorkflow Examples -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. +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. +## Prerequisites --------------------------------------------------- +- Python 3.7+ +- OpenAI API key or other supported LLM provider keys +- Swarms library -# File: swarms\framework\agents_explained.md +## Installation -# An Analysis of Agents +```bash +pip3 install -U swarms +``` -In the Swarms framework, agents are designed to perform tasks autonomously by leveraging large language models (LLMs), various tools, and long-term memory systems. This guide provides an extensive conceptual walkthrough of how an agent operates, detailing the sequence of actions it takes to complete a task and how it utilizes its internal components. +## Environment Variables -#### Agent Components Overview -- **LLM (Large Language Model)**: The core component responsible for understanding and generating natural language. -- **Tools**: External functions and services that the agent can call to perform specific tasks, such as querying databases or interacting with APIs. -- **Long-term Memory**: Systems like ChromaDB or Pinecone that store and retrieve information over extended periods, enabling the agent to remember past interactions and contexts. +```plaintext +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" +ANTHROPIC_API_KEY="" +GROQ_API_KEY="" +``` -#### Agent Workflow -The workflow of an agent can be divided into several stages: task initiation, initial LLM processing, tool usage, memory interaction, and final LLM processing. +## Basic Usage -##### Stage 1: Task Initiation -- **Input**: The task or query that the agent needs to address. -- **Output**: A structured plan or approach for handling the task. +### 1. Initialize Specialized Agents -##### Stage 2: Initial LLM Processing -- **Input**: The task or query. -- **Process**: The LLM interprets the task, understanding the context and requirements. -- **Output**: An initial response or action plan. +```python +from swarms import Agent +from swarms.structs.concurrent_workflow import ConcurrentWorkflow -##### Stage 3: Tool Usage -- **Input**: The action plan or specific sub-tasks identified by the LLM. -- **Process**: The agent calls various tools to gather information, perform calculations, or interact with external systems. - - **Function Calling as Tools**: Tools are called as functions with specific inputs and outputs, enabling the agent to perform a wide range of tasks. -- **Output**: Data or results from the tools. +# 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, +) -##### Stage 4: Memory Interaction -- **Input**: Intermediate results and context from the tools. -- **Process**: The agent interacts with long-term memory systems to store new information and retrieve relevant past data. - - **RAG Systems (ChromaDB, Pinecone)**: These systems are used to enhance the agent’s responses by providing relevant historical data and context. -- **Output**: Enhanced context and data for final processing. +# 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, +) -##### Stage 5: Final LLM Processing -- **Input**: Comprehensive data and context from the tools and memory systems. -- **Process**: The LLM generates the final response or completes the task using the enriched data. -- **Output**: The final output or action taken by the agent. +# 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, +) -### Detailed Workflow with Mermaid Diagrams +# Create list of agents +agents = [market_researcher, financial_analyst, technical_analyst] -#### Agent Components and Workflow +# 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 +) -```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] +# Run the workflow +result = router.run( + "Analyze Tesla (TSLA) stock from market, financial, and technical perspectives" +) ``` -### Explanation of Each Stage - -#### Stage 1: Task Initiation -- **Task**: The agent receives a task or query from an external source (e.g., a user query, a system trigger). -- **Objective**: To understand what needs to be done and prepare an initial approach. - -#### Stage 2: Initial LLM Processing -- **Interpretation**: The LLM processes the task to comprehend its context and requirements. -- **Planning**: The LLM generates an initial plan or identifies the sub-tasks required to complete the task. - -#### Stage 3: Tool Usage -- **Function Calls**: The agent uses predefined functions (tools) to perform specific actions, such as querying a database or making API calls. -- **Tool Integration**: Each tool is called with specific parameters, and the results are collected for further processing. - -#### Stage 4: Memory Interaction -- **Long-term Memory**: Systems like ChromaDB and Pinecone store and retrieve long-term data, providing the agent with historical context and past interactions. -- **Retrieval-Augmented Generation (RAG)**: The agent uses RAG systems to enhance the current context with relevant past data, improving the quality and relevance of the final output. - -#### Stage 5: Final LLM Processing -- **Enhanced Processing**: The LLM processes the enriched data and context provided by the tools and memory systems. -- **Final Output**: The LLM generates a comprehensive response or completes the task using the enhanced information. - -### Conclusion +## Features -The Swarms framework's agents are powerful units that combine LLMs, tools, and long-term memory systems to perform complex tasks efficiently. By leveraging function calling for tools and RAG systems like ChromaDB and Pinecone, agents can enhance their capabilities and deliver highly relevant and accurate results. This conceptual guide and walkthrough provide a detailed understanding of how agents operate within the Swarms framework, enabling the development of sophisticated and collaborative AI systems. +### Real-time Dashboard --------------------------------------------------- +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. -# File: swarms\framework\code_cleanliness.md +#### Dashboard Features -# Code Cleanliness in Python: A Comprehensive Guide +- **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 -Code cleanliness is an essential aspect of software development that ensures code is easy to read, understand, and maintain. Clean code leads to fewer bugs, easier debugging, and more efficient collaboration among developers. This blog article delves into the principles of writing clean Python code, emphasizing the use of type annotations, docstrings, and the Loguru logging library. We'll explore the importance of each component and provide practical examples to illustrate best practices. +#### Dashboard Status Values -## Table of Contents -1. Introduction to Code Cleanliness -2. Importance of Type Annotations -3. Writing Effective Docstrings -4. Structuring Your Code -5. Error Handling and Logging with Loguru -6. Refactoring for Clean Code -7. Examples of Clean Code -8. Conclusion +- **"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 -## 1. Introduction to Code Cleanliness +#### Dashboard Configuration -Code cleanliness refers to the practice of writing code that is easy to read, understand, and maintain. Clean code follows consistent conventions and is organized logically, making it easier for developers to collaborate and for new team members to get up to speed quickly. +```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 +) +``` -### Why Clean Code Matters +#### Dashboard Behavior -1. **Readability**: Clean code is easy to read and understand, which reduces the time needed to grasp what the code does. -2. **Maintainability**: Clean code is easier to maintain and modify, reducing the risk of introducing bugs when making changes. -3. **Collaboration**: Clean code facilitates collaboration among team members, as everyone can easily understand and follow the codebase. -4. **Debugging**: Clean code makes it easier to identify and fix bugs, leading to more reliable software. +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 -## 2. Importance of Type Annotations +### Concurrent Execution -Type annotations in Python provide a way to specify the types of variables, function arguments, and return values. They enhance code readability and help catch type-related errors early in the development process. +- **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 -### Benefits of Type Annotations +### Output Formatting Options -1. **Improved Readability**: Type annotations make it clear what types of values are expected, improving code readability. -2. **Error Detection**: Type annotations help catch type-related errors during development, reducing runtime errors. -3. **Better Tooling**: Many modern IDEs and editors use type annotations to provide better code completion and error checking. +The workflow supports multiple output aggregation formats: -### Example of Type Annotations +- **"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 ```python -from typing import List - -def calculate_average(numbers: List[float]) -> float: - """ - Calculates the average of a list of numbers. - - Args: - numbers (List[float]): A list of numbers. - - Returns: - float: The average of the numbers. - """ - return sum(numbers) / len(numbers) +# Configure output format +workflow = ConcurrentWorkflow( + agents=agents, + output_type="dict", # Get complete dictionary of results + show_dashboard=True +) ``` -In this example, the `calculate_average` function takes a list of floats as input and returns a float. The type annotations make it clear what types are expected and returned, enhancing readability and maintainability. - -## 3. Writing Effective Docstrings - -Docstrings are an essential part of writing clean code in Python. They provide inline documentation for modules, classes, methods, and functions. Effective docstrings improve code readability and make it easier for other developers to understand and use your code. - -### Benefits of Docstrings +### Advanced Features -1. **Documentation**: Docstrings serve as inline documentation, making it easier to understand the purpose and usage of code. -2. **Consistency**: Well-written docstrings ensure consistent documentation across the codebase. -3. **Ease of Use**: Docstrings make it easier for developers to use and understand code without having to read through the implementation details. +#### Auto Prompt Engineering -### Example of Effective Docstrings +Enable automatic prompt optimization for all agents: ```python -def calculate_factorial(n: int) -> int: - """ - Calculates the factorial of a given non-negative integer. +workflow = ConcurrentWorkflow( + agents=agents, + auto_generate_prompts=True, # Enable automatic prompt engineering + show_dashboard=True +) +``` - Args: - n (int): The non-negative integer to calculate the factorial of. +#### Conversation History Management - Returns: - int: The factorial of the given number. +Automatic conversation tracking and persistence: - Raises: - ValueError: If the input is a negative integer. - """ - if n < 0: - raise ValueError("Input must be a non-negative integer.") - factorial = 1 - for i in range(1, n + 1): - factorial *= i - return factorial +```python +workflow = ConcurrentWorkflow( + agents=agents, + auto_save=True, # Auto-save conversation history + metadata_output_path="results.json" # Custom output file path +) ``` -In this example, the docstring clearly explains the purpose of the `calculate_factorial` function, its arguments, return value, and the exception it may raise. +#### Multimodal Support -## 4. Structuring Your Code +Support for image inputs across all agents: -Proper code structure is crucial for code cleanliness. A well-structured codebase is easier to navigate, understand, and maintain. Here are some best practices for structuring your Python code: +```python +# Single image input +result = workflow.run( + task="Analyze this chart", + img="financial_chart.png" +) -### Organizing Code into Modules and Packages +# Multiple image inputs +result = workflow.run( + task="Compare these charts", + imgs=["chart1.png", "chart2.png", "chart3.png"] +) +``` -Organize your code into modules and packages to group related functionality together. This makes it easier to find and manage code. +## Best Practices -```python -# project/ -# ├── main.py -# ├── utils/ -# │ ├── __init__.py -# │ ├── file_utils.py -# │ └── math_utils.py -# └── models/ -# ├── __init__.py -# ├── user.py -# └── product.py -``` +### 1. Dashboard Usage -### Using Functions and Classes +- **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 -Break down your code into small, reusable functions and classes. This makes your code more modular and easier to test. +### 2. Agent Configuration -```python -class User: - def __init__(self, name: str, age: int): - """ - Initializes a new user. +- **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 - Args: - name (str): The name of the user. - age (int): The age of the user. - """ - self.name = name - self.age = age +### 3. Resource Management - def greet(self) -> str: - """ - Greets the user. +- **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 - Returns: - str: A greeting message. - """ - return f"Hello, {self.name}!" -``` +### 4. Task Design -### Keeping Functions Small +- **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 -Functions should do one thing and do it well. Keep functions small and focused on a single task. +## Example Implementations + +### Comprehensive Market Analysis ```python -def save_user(user: User, filename: str) -> None: - """ - Saves user data to a file. +from swarms import Agent +from swarms.structs.concurrent_workflow import ConcurrentWorkflow - Args: - user (User): The user object to save. - filename (str): The name of the file to save the user data to. - """ - with open(filename, 'w') as file: - file.write(f"{user.name},{user.age}") -``` +# 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, +) -## 5. Error Handling and Logging with Loguru +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, +) -Effective error handling and logging are critical components of clean code. They help you manage and diagnose issues that arise during the execution of your code. +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, +) -### Error Handling Best Practices +# 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 +) -1. **Use Specific Exceptions**: Catch specific exceptions rather than using a generic `except` clause. -2. **Provide Meaningful Messages**: When raising exceptions, provide meaningful error messages to help diagnose the issue. -3. **Clean Up Resources**: Use `finally` blocks or context managers to ensure that resources are properly cleaned up. +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)}") +``` -### Example of Error Handling +### Batch Processing with Dashboard ```python -def divide_numbers(numerator: float, denominator: float) -> float: - """ - Divides the numerator by the denominator. +# 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" +] - Args: - numerator (float): The number to be divided. - denominator (float): The number to divide by. +# Optional: corresponding images for each task +charts = ["q1_chart.png", "q2_chart.png", "q3_chart.png", "q4_chart.png"] - Returns: - float: The result of the division. +# Batch processing with dashboard monitoring +results = workflow.batch_run(tasks, imgs=charts) - Raises: - ValueError: If the denominator is zero. - """ - if denominator == 0: - raise ValueError("The denominator cannot be zero.") - return numerator / denominator +print(f"Completed {len(results)} quarterly analyses") +for i, result in enumerate(results): + print(f"\nQ{i+1} Analysis Results:") + print(result) ``` -### Logging with Loguru +### Multimodal Analysis -Loguru is a powerful logging library for Python that makes logging simple and enjoyable. It provides a clean and easy-to-use API for logging messages with different severity levels. +```python +# Analyze financial charts with multiple specialized agents +workflow = ConcurrentWorkflow( + agents=[technical_analyst, fundamental_analyst, sentiment_analyst], + show_dashboard=True, + output_type="dict" +) -#### Installing Loguru +# Analyze a single chart +result = workflow.run( + task="Analyze this stock chart and provide trading insights", + img="stock_chart.png" +) -```bash -pip install loguru +# Analyze multiple charts +result = workflow.run( + task="Compare these three charts and identify patterns", + imgs=["chart1.png", "chart2.png", "chart3.png"] +) ``` -#### Basic Usage of Loguru +### Error Handling and Monitoring ```python -from loguru import logger +# 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 +) -logger.debug("This is a debug message") -logger.info("This is an info message") -logger.warning("This is a warning message") -logger.error("This is an error message") -logger.critical("This is a critical message") +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 ``` -### Example of Logging in a Function +## Performance Tips -```python -from loguru import logger +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 -def fetch_data(url: str) -> str: - """ - Fetches data from a given URL and returns it as a string. +## Use Cases - Args: - url (str): The URL to fetch data from. +- **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 - Returns: - str: The data fetched from the URL. +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. - Raises: - requests.exceptions.RequestException: If there is an error with the request. - """ - try: - logger.info(f"Fetching data from {url}") - response = requests.get(url) - response.raise_for_status() - logger.info("Data fetched successfully") - return response.text - except requests.exceptions.RequestException as e: - logger.error(f"Error fetching data: {e}") - raise -``` +-------------------------------------------------- -In this example, Loguru is used to log messages at different severity levels. The `fetch_data` function logs informational messages when fetching data and logs an error message if an exception is raised. +# File: swarms\examples\deepseek.md -## 6. Refactoring for Clean Code +# Agent with DeepSeek -Refactoring is the process of restructuring existing code without changing its external behavior. It is an essential practice for maintaining clean code. Refactoring helps improve code readability, reduce complexity, and eliminate redundancy. +- Add your `DEEPSEEK_API_KEY` in the `.env` file -### Identifying Code Smells +- Select your model_name like `deepseek/deepseek-chat` follows [LiteLLM conventions](https://docs.litellm.ai/docs/providers/deepseek) -Code smells are indicators of potential issues in the code that may require refactoring. Common code smells include: -1. **Long Methods**: Methods that are too long and do too many things. -2. **Duplicated Code**: Code that is duplicated in multiple places. -3. **Large Classes**: Classes that have too many responsibilities. -4. **Poor Naming**: Variables, functions, or classes with unclear or misleading names. +- Execute your agent! -### Refactoring Techniques -1. **Extract Method**: Break down long methods into smaller, more focused methods. -2. **Rename Variables**: Use meaningful names for variables, functions, and classes. -3. **Remove Duplicated Code**: Consolidate duplicated code into a single location. -4. **Simplify Conditional Expressions**: Simplify complex conditional expressions for +```python +from swarms import Agent +import os +from dotenv import load_dotenv - better readability. +load_dotenv() -### Example of Refactoring +# Initialize the agent with ChromaDB memory +agent = Agent( + agent_name="Financial-Analysis-Agent", + model_name="deepseek/deepseek-chat", + system_prompt="Agent system prompt here", + agent_description="Agent performs financial analysis.", +) -Before refactoring: -```python -def process_data(data: List[int]) -> int: - total = 0 - for value in data: - if value > 0: - total += value - return total +# Run a query +agent.run("What are the components of a startup's stock incentive equity plan?") ``` -After refactoring: -```python -def filter_positive_values(data: List[int]) -> List[int]: - """ - Filters the positive values from the input data. - - Args: - data (List[int]): The input data. - - Returns: - List[int]: A list of positive values. - """ - return [value for value in data if value > 0] +## R1 -def sum_values(values: List[int]) -> int: - """ - Sums the values in the input list. +This is a simple example of how to use the DeepSeek Reasoner model otherwise known as R1. - Args: - values (List[int]): A list of values to sum. +```python - Returns: - int: The sum of the values. - """ - return sum(values) +import os +from swarms import Agent +from dotenv import load_dotenv -def process_data(data: List[int]) -> int: - """ - Processes the data by filtering positive values and summing them. +load_dotenv() - Args: - data (List[int]): The input data. +# 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.", +) - Returns: - int: The sum of the positive values. - """ - positive_values = filter_positive_values(data) - return sum_values(positive_values) +# Run a query +agent.run("What are the components of a startup's stock incentive equity plan?") ``` -In this example, the `process_data` function is refactored into smaller, more focused functions. This improves readability and maintainability. - -## 7. Examples of Clean Code - -### Example 1: Reading a File +-------------------------------------------------- -```python -def read_file(file_path: str) -> str: - """ - Reads the content of a file and returns it as a string. +# File: swarms\examples\groq.md - Args: - file_path (str): The path to the file to read. +# Agent with Groq - Returns: - str: The content of the file. +- Add your `GROQ_API_KEY` - Raises: - FileNotFoundError: If the file does not exist. - IOError: If there is an error reading the file. - """ - try: - with open(file_path, 'r') as file: - return file.read() - except FileNotFoundError as e: - logger.error(f"File not found: {file_path}") - raise - except IOError as e: - logger.error(f"Error reading file: {file_path}") - raise -``` +- Initiate your agent -### Example 2: Fetching Data from a URL +- Run your agent ```python -import requests -from loguru import logger +import os -def fetch_data(url: str) -> str: - """ - Fetches data from a given URL and returns it as a string. +from swarm_models import OpenAIChat - Args: - url (str): The URL to fetch data from. +from swarms import Agent - Returns: - str: The data fetched from the URL. +company = "NVDA" - Raises: - requests.exceptions.RequestException: If there is an error with the request. - """ - try: - logger.info(f"Fetching data from {url}") - response = requests.get(url) - response.raise_for_status() - logger.info("Data fetched successfully") - return response.text - except requests.exceptions.RequestException as e: - logger.error(f"Error fetching data: {e}") - raise -``` -### Example 3: Calculating Factorial +# 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", +) +``` -```python -def calculate_factorial(n: int) -> int: - """ - Calculates the factorial of a given non-negative integer. +-------------------------------------------------- - Args: - n (int): The non-negative integer to calculate the factorial of. +# File: swarms\examples\groupchat_example.md - Returns: - int: The factorial of the given number. +# GroupChat Example - Raises: - ValueError: If the input is a negative integer. - """ - if n < 0: - raise ValueError("Input must be a non-negative integer.") - factorial = 1 - for i in range(1, n + 1): - factorial *= i - return factorial -``` +!!! 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. -## 8. Conclusion +## Prerequisites -Writing clean code in Python is crucial for developing maintainable, readable, and error-free software. By using type annotations, writing effective docstrings, structuring your code properly, and leveraging logging with Loguru, you can significantly improve the quality of your codebase. +!!! info "Before You Begin" + Make sure you have: + - Python 3.7+ installed + - A valid API key for your model provider + - The Swarms package installed -Remember to refactor your code regularly to eliminate code smells and improve readability. Clean code not only makes your life as a developer easier but also enhances collaboration and reduces the likelihood of bugs. +## Installation -By following the principles and best practices outlined in this article, you'll be well on your way to writing clean, maintainable Python code. +```bash +pip install swarms +``` --------------------------------------------------- +## Environment Setup -# File: swarms\framework\concept.md +!!! tip "API Key Configuration" + Set your API key in the `.env` file: + ```bash + OPENAI_API_KEY="your-api-key-here" + ``` -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. +## Code Implementation -### Swarms Framework Overview +### Import Required Modules -#### 1. **Models** -Models are the core component of the Swarms framework, representing the neural networks and machine learning models used to perform various tasks. These can be Large Language Models (LLMs), vision models, or any other AI models. +```python +from dotenv import load_dotenv +import os +from swarms import Agent, GroupChat +``` -#### 2. **Agents** -Agents are autonomous units that use models to perform specific tasks. In the Swarms framework, agents can leverage tools and interact with RAG systems. +### Configure Agents -- **LLMs with Tools**: These agents use large language models along with tools like databases, APIs, and external knowledge sources to enhance their capabilities. -- **RAG Systems**: These systems combine retrieval mechanisms with generative models to produce more accurate and contextually relevant outputs. +!!! example "Agent Configuration" + Here's how to set up your agents with specific roles: -#### 3. **Swarm Systems** -Swarm systems involve multiple agents working collaboratively to achieve complex tasks. These systems coordinate and communicate among agents to ensure efficient and effective task execution. + ```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, + ) -### Mermaid Diagrams + # 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, + ) + ``` -#### Models +### Initialize GroupChat -```mermaid -graph TD - A[Model] -->|Uses| B[Data] - A -->|Trains| C[Algorithm] - A -->|Outputs| D[Predictions] -``` +!!! example "GroupChat Setup" + Configure the GroupChat with your agents: -#### Agents: LLMs with Tools and RAG Systems + ```python + agents = [agent1, agent2] -```mermaid -graph TD - A[Agent] -->|Uses| B[LLM] - A -->|Interacts with| C[Tool] - C -->|Provides Data to| B - A -->|Queries| D[RAG System] - D -->|Retrieves Information from| E[Database] - D -->|Generates Responses with| F[Generative Model] -``` + chat = GroupChat( + name="Expense Advisory", + description="Accounting group focused on discussing potential expenses", + agents=agents, + max_loops=1, + output_type="all", + ) + ``` -#### Swarm Systems +### Run the Chat -```mermaid -graph TD - A[Swarm System] - A -->|Coordinates| B[Agent 1] - A -->|Coordinates| C[Agent 2] - A -->|Coordinates| D[Agent 3] - B -->|Communicates with| C - C -->|Communicates with| D - D -->|Communicates with| B - B -->|Performs Task| E[Task 1] - C -->|Performs Task| F[Task 2] - D -->|Performs Task| G[Task 3] - E -->|Reports to| A - F -->|Reports to| A - G -->|Reports to| A -``` +!!! example "Execute the Chat" + Start the conversation between agents: -### Conceptualization + ```python + history = chat.run( + "What potential expenses should we consider for the upcoming quarter? Please collaborate to outline a comprehensive list." + ) + ``` -1. **Models**: The basic building blocks trained on specific datasets to perform tasks. -2. **Agents**: Intelligent entities that utilize models and tools to perform actions. LLM agents can use additional tools to enhance their capabilities. -3. **RAG Systems**: Enhance agents by combining retrieval mechanisms (to fetch relevant information) with generative models (to create contextually relevant responses). -4. **Swarm Systems**: Complex systems where multiple agents collaborate, communicate, and coordinate to perform complex, multi-step tasks efficiently. +## Complete Example -### Summary -The Swarms framework leverages models, agents, tools, RAG systems, and swarm systems to create a robust, collaborative environment for executing complex AI tasks. By coordinating multiple agents and enhancing their capabilities with tools and retrieval-augmented generation, Swarms can handle sophisticated and multi-faceted applications effectively. +!!! success "Full Implementation" + Here's the complete code combined: --------------------------------------------------- + ```python + from dotenv import load_dotenv + import os + from swarms import Agent, GroupChat -# File: swarms\framework\index.md + if __name__ == "__main__": + # Load environment variables + load_dotenv() + api_key = os.getenv("OPENAI_API_KEY") -## Swarms Framework Conceptual Breakdown + # 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, + ) -The `swarms` framework is a sophisticated structure designed to orchestrate the collaborative work of multiple agents in a hierarchical manner. This breakdown provides a conceptual and visual representation of the framework, highlighting the interactions between models, tools, memory, agents, and swarms. + 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, + ) -### Hierarchical Structure + # 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", + ) -The framework can be visualized as a multi-layered hierarchy: + # Run the chat + history = chat.run( + "What potential expenses should we consider for the upcoming quarter? Please collaborate to outline a comprehensive list." + ) + ``` -1. **Models, Tools, Memory**: These form the foundational components that agents utilize to perform tasks. -2. **Agents**: Individual entities that encapsulate specific functionalities, utilizing models, tools, and memory. -3. **Swarm**: A collection of multiple agents working together in a coordinated manner. -4. **Structs**: High-level structures that organize and manage swarms, enabling complex workflows and interactions. +## Configuration Options -### Visual Representation +!!! 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 | -Below are visual graphs illustrating the hierarchical and tree structure of the `swarms` framework. +## Next Steps -#### 1. Foundational Components: Models, Tools, Memory +!!! 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 -![Diagram](assets/img/agent_def.png) +## Troubleshooting -#### 2. Agents and Their Interactions +!!! 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 -```mermaid -graph TD; - Agents --> Swarm - subgraph Agents_Collection - Agent1 - Agent2 - Agent3 - end - subgraph Individual_Agents - Agent1 --> Models - Agent1 --> Tools - Agent1 --> Memory - Agent2 --> Models - Agent2 --> Tools - Agent2 --> Memory - Agent3 --> Models - Agent3 --> Tools - Agent3 --> Memory - end -``` +## Additional Resources -#### 3. Multiple Agents Form a Swarm +- [Swarms Documentation](https://docs.swarms.world) +- [API Reference](https://docs.swarms.world/api) +- [Examples Gallery](https://docs.swarms.world/examples) -```mermaid -graph TD; - Swarm1 --> Struct - Swarm2 --> Struct - Swarm3 --> Struct - subgraph Swarms_Collection - Swarm1 - Swarm2 - Swarm3 - end - subgraph Individual_Swarms - Swarm1 --> Agent1 - Swarm1 --> Agent2 - Swarm1 --> Agent3 - Swarm2 --> Agent4 - Swarm2 --> Agent5 - Swarm2 --> Agent6 - Swarm3 --> Agent7 - Swarm3 --> Agent8 - Swarm3 --> Agent9 - end -``` +-------------------------------------------------- -#### 4. Structs Organizing Multiple Swarms +# File: swarms\examples\hhcs_examples.md -```mermaid -graph TD; - Struct --> Swarms_Collection - subgraph High_Level_Structs - Struct1 - Struct2 - Struct3 - end - subgraph Struct1 - Swarm1 - Swarm2 - end - subgraph Struct2 - Swarm3 - end - subgraph Struct3 - Swarm4 - Swarm5 - end -``` -### Directory Breakdown +# Hybrid Hierarchical-Cluster Swarm (HHCS) Example -The directory structure of the `swarms` framework is organized to support its hierarchical architecture: +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 -```sh -swarms/ -├── agents/ -├── artifacts/ -├── marketplace/ -├── memory/ -├── models/ -├── prompts/ -├── schemas/ -├── structs/ -├── telemetry/ -├── tools/ -├── utils/ -└── __init__.py -``` +```python -### Summary +from swarms import Agent, SwarmRouter, HybridHierarchicalClusterSwarm -The `swarms` framework is designed to facilitate complex multi-agent interactions through a structured and layered approach. By leveraging foundational components like models, tools, and memory, individual agents are empowered to perform specialized tasks. These agents are then coordinated within swarms to achieve collective goals, and swarms are managed within high-level structs to orchestrate sophisticated workflows. -This hierarchical design ensures scalability, flexibility, and robustness, making the `swarms` framework a powerful tool for various applications in AI, data analysis, optimization, and beyond. +# 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, +) --------------------------------------------------- +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, +) -# File: swarms\framework\reference.md +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, +) -# API Reference Documentation +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, +) +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, +) -### `swarms.__init__` +# 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", +) -**Description**: -This module initializes the Swarms package by concurrently executing the bootup process and activating Sentry for telemetry. It imports various components from other modules within the Swarms package. +corporate_swarm = SwarmRouter( + name="corporate-practice", + description="Handle business and corporate legal matters", + agents=[corporate_agent, paralegal_agent], + swarm_type="SequentialWorkflow", +) -**Imports**: -- `concurrent.futures`: A module that provides a high-level interface for asynchronously executing callables. +ip_swarm = SwarmRouter( + name="ip-practice", + description="Handle intellectual property matters", + agents=[ip_agent, paralegal_agent], + swarm_type="SequentialWorkflow", +) -- `swarms.telemetry.bootup`: Contains the `bootup` function for initializing telemetry. +employment_swarm = SwarmRouter( + name="employment-practice", + description="Handle employment and labor law matters", + agents=[employment_agent, paralegal_agent], + swarm_type="SequentialWorkflow", +) -- `swarms.telemetry.sentry_active`: Contains the `activate_sentry` function to enable Sentry for error tracking. +# 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", +) -- Other modules from the Swarms package are imported for use, including agents, artifacts, prompts, structs, telemetry, tools, utils, and schemas. +dispute_swarm = SwarmRouter( + name="dispute-resolution", + description="Handle complex disputes requiring multiple specialties", + agents=[litigation_agent, corporate_agent, doc_review_agent], + swarm_type="ConcurrentWorkflow", +) -**Concurrent Execution**: -The module uses `ThreadPoolExecutor` to run the `bootup` and `activate_sentry` functions concurrently. +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 -import concurrent.futures -from swarms.telemetry.bootup import bootup # noqa: E402, F403 -from swarms.telemetry.sentry_active import activate_sentry -# Use ThreadPoolExecutor to run bootup and activate_sentry concurrently -with concurrent.futures.ThreadPoolExecutor(max_workers=2) as executor: - executor.submit(bootup) - executor.submit(activate_sentry) +if __name__ == "__main__": + hybrid_hiearchical_swarm.run( + "What is the best way to file for a patent? for ai technology " + ) -from swarms.agents import * # noqa: E402, F403 -from swarms.artifacts import * # noqa: E402, F403 -from swarms.prompts import * # noqa: E402, F403 -from swarms.structs import * # noqa: E402, F403 -from swarms.telemetry import * # noqa: E402, F403 -from swarms.tools import * # noqa: E402, F403 -from swarms.utils import * # noqa: E402, F403 -from swarms.schemas import * # noqa: E402, F403 ``` -**Note**: There are no documentable functions or classes within this module itself, as it primarily serves to execute initial setup tasks and import other modules. - +-------------------------------------------------- +# File: swarms\examples\hierarchical_swarm_example.md +# Hierarchical Swarm Examples -### `swarms.artifacts.base_artifact` +This page provides simple, practical examples of how to use the `HierarchicalSwarm` for various real-world scenarios. -**Description**: -This module defines the `BaseArtifact` abstract base class for representing artifacts in the system. It provides methods to convert artifact values to various formats and enforces the implementation of an addition method for subclasses. +## Basic Example: Financial Analysis -**Imports**: -- `json`: A module for parsing JSON data. +```python +from swarms import Agent +from swarms.structs.hiearchical_swarm import HierarchicalSwarm -- `uuid`: A module for generating unique identifiers. +# 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", +) -- `ABC`, `abstractmethod`: Tools from the `abc` module to define abstract base classes. +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", +) -- `dataclass`: A decorator for creating data classes. +# 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, +) -- `Any`: A type hint for any data type. +# 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) +``` +## Development Team Example -### `BaseArtifact` -**Description**: -An abstract base class for artifacts that includes common attributes and methods for handling artifact values. +```python +from swarms import Agent +from swarms.structs.hiearchical_swarm import HierarchicalSwarm -**Attributes**: -- `id` (`str`): A unique identifier for the artifact, generated if not provided. +# 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", +) -- `name` (`str`): The name of the artifact. If not provided, it defaults to the artifact's ID. +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", +) -- `value` (`Any`): The value associated with the artifact. +# 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, +) +# 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) +``` -**Methods**: +## Single Step Execution -- `__post_init__(self) -> None` +```python +from swarms import Agent +from swarms.structs.hiearchical_swarm import HierarchicalSwarm - - **Description**: Initializes the artifact, setting the `id` and `name` attributes if they are not provided. - - - **Parameters**: None. - - - **Return**: None. - +# Create analysis agents +market_agent = Agent( + agent_name="Market-Analyst", + agent_description="Expert in market analysis and trends", + model_name="gpt-4o", +) -- `value_to_bytes(cls, value: Any) -> bytes` +technical_agent = Agent( + agent_name="Technical-Analyst", + agent_description="Specialist in technical analysis and patterns", + model_name="gpt-4o", +) - - **Description**: Converts the given value to bytes. - - - **Parameters**: - - - `value` (`Any`): The value to convert. - - - **Return**: - - - (`bytes`): The value converted to bytes. - +# 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, +) -- `value_to_dict(cls, value: Any) -> dict` +# Execute a single step +task = "Analyze the current market trends for electric vehicles" +feedback = swarm.step(task=task) +print("Director Feedback:", feedback) +``` - - **Description**: Converts the given value to a dictionary. - - - **Parameters**: - - - `value` (`Any`): The value to convert. - - - **Return**: - - - (`dict`): The value converted to a dictionary. - +## Batch Processing -- `to_text(self) -> str` +```python +from swarms import Agent +from swarms.structs.hiearchical_swarm import HierarchicalSwarm - - **Description**: Converts the artifact's value to a text representation. - - - **Parameters**: None. - - - **Return**: - - - (`str`): The string representation of the artifact's value. - +# Create analysis agents +market_agent = Agent( + agent_name="Market-Analyst", + agent_description="Expert in market analysis and trends", + model_name="gpt-4o", +) -- `__str__(self) -> str` +technical_agent = Agent( + agent_name="Technical-Analyst", + agent_description="Specialist in technical analysis and patterns", + model_name="gpt-4o", +) - - **Description**: Returns a string representation of the artifact. - - - **Parameters**: None. - - - **Return**: - - - (`str`): The string representation of the artifact. - +# 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, +) -- `__bool__(self) -> bool` +# Execute multiple tasks +tasks = [ + "Analyze Apple (AAPL) stock performance", + "Evaluate Microsoft (MSFT) market position", + "Assess Google (GOOGL) competitive landscape" +] - - **Description**: Returns the boolean value of the artifact based on its value. - - - **Parameters**: None. - - - **Return**: - - - (`bool`): The boolean value of the artifact. - +results = swarm.batched_run(tasks=tasks) +for i, result in enumerate(results): + print(f"Task {i+1} Result:", result) +``` -- `__len__(self) -> int` +## Research Team Example - - **Description**: Returns the length of the artifact's value. - - - **Parameters**: None. - - - **Return**: - - - (`int`): The length of the artifact's value. - +```python +from swarms import Agent +from swarms.structs.hiearchical_swarm import HierarchicalSwarm -- `__add__(self, other: BaseArtifact) -> BaseArtifact` +# 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", +) - - **Description**: Abstract method for adding two artifacts together. Must be implemented by subclasses. - - - **Parameters**: - - - `other` (`BaseArtifact`): The other artifact to add. - - - **Return**: - - - (`BaseArtifact`): The result of adding the two artifacts. - +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", +) -**Example**: -```python -from swarms.artifacts.base_artifact import BaseArtifact +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", +) -class MyArtifact(BaseArtifact): - def __add__(self, other: BaseArtifact) -> BaseArtifact: - - return MyArtifact(id=self.id, name=self.name, value=self.value + other.value) +# 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, +) -artifact1 = MyArtifact(id="123", name="Artifact1", value=10) -artifact2 = MyArtifact(id="456", name="Artifact2", value=20) -result = artifact1 + artifact2 -print(result) # Output: MyArtifact with the combined value +# Execute research project +task = "Conduct a comprehensive market analysis for a new AI-powered productivity tool" +result = research_swarm.run(task=task) +print(result) ``` +## Key Takeaways +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 +For more detailed information about the `HierarchicalSwarm` API and advanced usage patterns, see the [main documentation](hierarchical_swarm.md). -### `swarms.artifacts.text_artifact` +-------------------------------------------------- -**Description**: -This module defines the `TextArtifact` class, which represents a text-based artifact. It extends the `BaseArtifact` class and includes attributes and methods specific to -handling text values, including encoding options, embedding generation, and token counting. +# File: swarms\examples\igc_example.md -**Imports**: -- `dataclass`, `field`: Decorators and functions from the `dataclasses` module for creating data classes. +## Interactive Groupchat Examples -- `Callable`: A type hint indicating a callable object from the `typing` module. +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. -- `BaseArtifact`: The abstract base class for artifacts, imported from `swarms.artifacts.base_artifact`. +### Architecture Description +The Interactive GroupChat implements a **collaborative swarm architecture** where multiple specialized agents work together in a coordinated manner. Key features include: -### `TextArtifact` -**Description**: -Represents a text artifact with additional functionality for handling text values, encoding, and embeddings. +- **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 -**Attributes**: -- `value` (`str`): The text value of the artifact. +For comprehensive documentation on Interactive GroupChat, visit: [Interactive GroupChat Documentation](https://docs.swarms.world/en/latest/swarms/structs/interactive_groupchat/) -- `encoding` (`str`, optional): The encoding of the text (default is "utf-8"). +### Step-by-Step Showcase -- `encoding_error_handler` (`str`, optional): The error handler for encoding errors (default is "strict"). +* **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 -- `tokenizer` (`Callable`, optional): A callable for tokenizing the text value. +## Installation -- `_embedding` (`list[float]`): The embedding of the text artifact (default is an empty list). +Install the swarms package using pip: +```bash +pip install -U swarms +``` -**Properties**: -- `embedding` (`Optional[list[float]]`): Returns the embedding of the text artifact if available; otherwise, returns `None`. +## Basic Setup +1. First, set up your environment variables: -**Methods**: +```python +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" +``` -- `__add__(self, other: BaseArtifact) -> TextArtifact` +## Code - - **Description**: Concatenates the text value of this artifact with the text value of another artifact. - - - **Parameters**: - - - `other` (`BaseArtifact`): The other artifact to concatenate with. - - - **Return**: - - - (`TextArtifact`): A new `TextArtifact` instance with the concatenated value. - +```python +""" +InteractiveGroupChat Speaker Function Examples -- `__bool__(self) -> bool` +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 - - **Description**: Checks if the text value of the artifact is non-empty. - - - **Parameters**: None. - - - **Return**: - - - (`bool`): `True` if the text value is non-empty; otherwise, `False`. - +The example also shows how agents can mention each other using @agent_name syntax. +""" -- `generate_embedding(self, model) -> list[float] | None` +from swarms import Agent +from swarms.structs.interactive_groupchat import ( + InteractiveGroupChat, + random_speaker, +) - - **Description**: Generates the embedding of the text artifact using a given embedding model. - - - **Parameters**: - - - `model`: An embedding model that provides the `embed_string` method. - - - **Return**: - - - (`list[float] | None`): The generated embedding as a list of floats, or `None` if the embedding could not be generated. - -- `token_count(self) -> int` +def create_example_agents(): + """Create example agents for demonstration.""" - - **Description**: Counts the number of tokens in the text artifact using a specified tokenizer. - - - **Parameters**: None. - - - **Return**: - - - (`int`): The number of tokens in the text value. - + # 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, + ) -- `to_bytes(self) -> bytes` + 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, + ) - - **Description**: Converts the text value of the artifact to bytes using the specified encoding and error handler. - - - **Parameters**: None. - - - **Return**: - - - (`bytes`): The text value encoded as bytes. - + 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, + ) -**Example**: -```python -from swarms.artifacts.text_artifact import TextArtifact + return [analyst, researcher, writer] -# Create a TextArtifact instance -text_artifact = TextArtifact(value="Hello, World!") -# Generate embedding (assuming an appropriate model is provided) -# embedding = text_artifact.generate_embedding(model) +def example_random(): + agents = create_example_agents() -# Count tokens in the text artifact -token_count = text_artifact.token_count() + # 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, + ) -# Convert to bytes -bytes_value = text_artifact.to_bytes() + # Test the random behavior + task = "Let's create a marketing strategy. @analyst @researcher @writer please contribute." -print(text_artifact) # Output: Hello, World! -print(token_count) # Output: Number of tokens -print(bytes_value) # Output: b'Hello, World!' + response = group_chat.run(task) + print(f"Response:\n{response}\n") + + +if __name__ == "__main__": + # example_round_robin() + example_random() ``` +## Connect With Us -### `swarms.artifacts.main_artifact` +Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights! -**Description**: -This module defines the `Artifact` class, which represents a file artifact with versioning capabilities. It allows for the creation, editing, saving, loading, and exporting of file artifacts, as well as managing their version history. The module also includes a `FileVersion` class to encapsulate the details of each version of the artifact. +| 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) | -**Imports**: -- `time`: A module for time-related functions. -- `logger`: A logging utility from `swarms.utils.loguru_logger`. +-------------------------------------------------- -- `os`: A module providing a way of using operating system-dependent functionality. +# File: swarms\examples\interactive_groupchat_example.md -- `json`: A module for parsing JSON data. +# Interactive GroupChat Example -- `List`, `Union`, `Dict`, `Any`: Type hints from the `typing` module. +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/) -- `BaseModel`, `Field`, `validator`: Tools from the `pydantic` module for data validation and settings management. +## Installation -- `datetime`: A module for manipulating dates and times. +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/): +```bash +pip3 install -U swarms +``` -### `FileVersion` -**Description**: -Represents a version of a file with its content and timestamp. +## Environment Variables -**Attributes**: -- `version_number` (`int`): The version number of the file. +```txt +OPENAI_API_KEY="" +ANTHROPIC_API_KEY="" +GROQ_API_KEY="" +``` -- `content` (`str`): The content of the file version. +# Code -- `timestamp` (`str`): The timestamp of the file version, formatted as "YYYY-MM-DD HH:MM:SS". +## Interactive Session in Terminal -**Methods**: +```python +from swarms import Agent +from swarms.structs.interactive_groupchat import InteractiveGroupChat -- `__str__(self) -> str` - - **Description**: Returns a string representation of the file version. - - - **Parameters**: None. - - - **Return**: - - - (`str`): A formatted string containing the version number, timestamp, and content. - +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", + ) -### `Artifact` -**Description**: -Represents a file artifact with attributes to manage its content and version history. + 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", + ) -**Attributes**: -- `file_path` (`str`): The path to the file. + 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", + ) -- `file_type` (`str`): The type of the file (e.g., ".txt"). + # Create a list of agents including both Agent instances and callables + agents = [ + financial_advisor, + tax_expert, + investment_analyst, + ] -- `contents` (`str`): The contents of the file. + # 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, + ) -- `versions` (`List[FileVersion]`): The list of file versions. + 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}") +``` -- `edit_count` (`int`): The number of times the file has been edited. +## Run Method // Manual Method -**Methods**: -- `validate_file_type(cls, v, values) -> str` +```python +from swarms import Agent +from swarms.structs.interactive_groupchat import InteractiveGroupChat - - **Description**: Validates the file type based on the file extension. - - - **Parameters**: - - - `v` (`str`): The file type to validate. - - - `values` (`dict`): A dictionary of other field values. - - - **Return**: - - - (`str`): The validated file type. - -- `create(self, initial_content: str) -> None` +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", + ) - - **Description**: Creates a new file artifact with the initial content. - - - **Parameters**: - - - `initial_content` (`str`): The initial content to set for the artifact. - - - **Return**: None. - + 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", + ) -- `edit(self, new_content: str) -> None` + 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", + ) - - **Description**: Edits the artifact's content, tracking the change in the version history. - - - **Parameters**: - - - `new_content` (`str`): The new content to set for the artifact. - - - **Return**: None. - + # Create a list of agents including both Agent instances and callables + agents = [ + financial_advisor, + tax_expert, + investment_analyst, + ] + + # 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, + ) -- `save(self) -> None` + 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}") +``` - - **Description**: Saves the current artifact's contents to the specified file path. - - - **Parameters**: None. - - - **Return**: None. - +-------------------------------------------------- -- `load(self) -> None` +# File: swarms\examples\llama4.md - - **Description**: Loads the file contents from the specified file path into the artifact. - - - **Parameters**: None. - - - **Return**: None. - +# Llama4 Model Integration -- `get_version(self, version_number: int) -> Union[FileVersion, None]` +!!! info "Prerequisites" + - Python 3.8 or higher + - `swarms` library installed + - Access to Llama4 model + - Valid environment variables configured - - **Description**: Retrieves a specific version of the artifact by its version number. - - - **Parameters**: - - - `version_number` (`int`): The version number to retrieve. - - - **Return**: - - - (`FileVersion | None`): The requested version if found; otherwise, `None`. - +## Quick Start -- `get_contents(self) -> str` +Here's a simple example of integrating Llama4 model for crypto risk analysis: - - **Description**: Returns the current contents of the artifact as a string. - - - **Parameters**: None. - - - **Return**: - - - (`str`): The current contents of the artifact. - +```python +from dotenv import load_dotenv +from swarms import Agent +from swarms.utils.vllm_wrapper import VLLM -- `get_version_history(self) -> str` +load_dotenv() +model = VLLM(model_name="meta-llama/Llama-4-Maverick-17B-128E") +``` - - **Description**: Returns the version history of the artifact as a formatted string. - - - **Parameters**: None. - - - **Return**: - - - (`str`): A formatted string containing the version history. - +## Available Models -- `export_to_json(self, file_path: str) -> None` +| 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 | - - **Description**: Exports the artifact to a JSON file. - - - **Parameters**: - - - `file_path` (`str`): The path to the JSON file where the artifact will be saved. - - - **Return**: None. - +!!! 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 -- `import_from_json(cls, file_path: str) -> "Artifact"` +## Detailed Implementation - - **Description**: Imports an artifact from a JSON file. - - - **Parameters**: - - - `file_path` (`str`): The path to the JSON file to import the artifact from. - - - **Return**: - - - (`Artifact`): The imported artifact instance. - +### 1. Define Custom System Prompt -- `get_metrics(self) -> str` +```python +CRYPTO_RISK_ANALYSIS_PROMPT = """ +You are a cryptocurrency risk analysis expert. Your role is to: - - **Description**: Returns all metrics of the artifact as a formatted string. - - - **Parameters**: None. - - - **Return**: - - - (`str`): A string containing all metrics of the artifact. - +1. Analyze market risks: + - Volatility assessment + - Market sentiment analysis + - Trading volume patterns + - Price trend evaluation -- `to_dict(self) -> Dict[str, Any]` +2. Evaluate technical risks: + - Network security + - Protocol vulnerabilities + - Smart contract risks + - Technical scalability - - **Description**: Converts the artifact instance to a dictionary representation. - - - **Parameters**: None. - - - **Return**: - - - (`Dict[str, Any]`): The dictionary representation of the artifact. - +3. Consider regulatory risks: + - Current regulations + - Potential regulatory changes + - Compliance requirements + - Geographic restrictions -- `from_dict(cls, data: Dict[str, Any]) -> "Artifact"` +4. Assess fundamental risks: + - Team background + - Project development status + - Competition analysis + - Use case viability - - **Description**: Creates an artifact instance from a dictionary representation. - - - **Parameters**: - - - `data` (`Dict[str, Any]`): The dictionary to create the artifact from. - - - **Return**: - - - (`Artifact`): The created artifact instance. - +Provide detailed, balanced analysis with both risks and potential mitigations. +Base your analysis on established crypto market principles and current market conditions. +""" +``` -**Example**: -```python -from swarms.artifacts.main_artifact import Artifact +### 2. Initialize Agent -# Create an Artifact instance -artifact = Artifact(file_path="example.txt", file_type=".txt") -artifact.create("Initial content") -artifact.edit("First edit") -artifact.edit("Second edit") -artifact.save() +```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, +) +``` -# Export to JSON -artifact.export_to_json("artifact.json") +## Full Code -# Import from JSON -imported_artifact = Artifact.import_from_json("artifact.json") +```python +from dotenv import load_dotenv -# Get metrics -print(artifact.get_metrics()) -``` +from swarms import Agent +from swarms.utils.vllm_wrapper import VLLM +load_dotenv() +# Define custom system prompt for crypto risk analysis +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 -### `swarms.artifacts.__init__` +2. Evaluate technical risks: + - Network security + - Protocol vulnerabilities + - Smart contract risks + - Technical scalability -**Description**: -This module serves as the initialization point for the artifacts subpackage within the Swarms framework. It imports and exposes the key classes related to artifacts, including `BaseArtifact`, `TextArtifact`, and `Artifact`, making them available for use in other parts of the application. +3. Consider regulatory risks: + - Current regulations + - Potential regulatory changes + - Compliance requirements + - Geographic restrictions -**Imports**: -- `BaseArtifact`: The abstract base class for artifacts, imported from `swarms.artifacts.base_artifact`. +4. Assess fundamental risks: + - Team background + - Project development status + - Competition analysis + - Use case viability -- `TextArtifact`: A class representing text-based artifacts, imported from `swarms.artifacts.text_artifact`. +Provide detailed, balanced analysis with both risks and potential mitigations. +Base your analysis on established crypto market principles and current market conditions. +""" -- `Artifact`: A class representing file artifacts with versioning capabilities, imported from `swarms.artifacts.main_artifact`. +model = VLLM(model_name="meta-llama/Llama-4-Maverick-17B-128E") +# 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, +) -**Exported Classes**: -- `BaseArtifact`: The base class for all artifacts. +print( + agent.run( + "Conduct a risk analysis of the top cryptocurrencies. Think for 2 loops internally" + ) +) +``` -- `TextArtifact`: A specialized artifact class for handling text values. +!!! warning "Resource Usage" + The Llama4 model requires significant computational resources. Ensure your system meets the minimum requirements. -- `Artifact`: A class for managing file artifacts, including their content and version history. +## 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. -**Example**: -```python -from swarms.artifacts import * +??? 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. -# Create instances of the artifact classes -base_artifact = BaseArtifact(id="1", name="Base Artifact", value="Some value") # This will raise an error since BaseArtifact is abstract -text_artifact = TextArtifact(value="Sample text") -file_artifact = Artifact(file_path="example.txt", file_type=".txt") +??? 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. -# Use the classes as needed -print(text_artifact) # Output: Sample text -``` +!!! 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 -**Note**: Since `BaseArtifact` is an abstract class, it cannot be instantiated directly. +!!! example "Sample Usage" + ```python + response = agent.run( + "Conduct a risk analysis of the top cryptocurrencies. Think for 2 loops internally" + ) + print(response) + ``` +-------------------------------------------------- -# Agents +# File: swarms\examples\lumo.md -### `swarms.agents.__init__` +# 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. -**Description**: -This module serves as the initialization point for the agents subpackage within the Swarms framework. It imports and exposes key classes and functions related to agent operations, including stopping conditions and the `ToolAgent` class, making them available for use in other parts of the application. -**Imports**: -- `check_cancelled`: A function to check if the operation has been cancelled. +- [Docs](https://huggingface.co/lumolabs-ai/Lumo-70B-Instruct) -- `check_complete`: A function to check if the operation is complete. +```python +from swarms import Agent +from transformers import LlamaForCausalLM, AutoTokenizer +import torch +from transformers import BitsAndBytesConfig -- `check_done`: A function to check if the operation is done. +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 + ) -- `check_end`: A function to check if the operation has ended. + 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") -- `check_error`: A function to check if there was an error during the operation. + def run(self, task: str) -> str: + """ + Generates text based on the given prompt using the Lumo model. -- `check_exit`: A function to check if the operation has exited. + Args: + prompt (str): The input prompt for the model. -- `check_failure`: A function to check if the operation has failed. + 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) -- `check_finished`: A function to check if the operation has finished. -- `check_stopped`: A function to check if the operation has been stopped. -- `check_success`: A function to check if the operation was successful. -- `ToolAgent`: A class representing an agent that utilizes tools. +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?") +``` -**Exported Classes and Functions**: -- `ToolAgent`: The class for managing tool-based agents. +-------------------------------------------------- -- `check_done`: Checks if the operation is done. +# File: swarms\examples\mixture_of_agents.md -- `check_finished`: Checks if the operation has finished. +# MixtureOfAgents Examples -- `check_complete`: Checks if the operation is complete. +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. -- `check_success`: Checks if the operation was successful. +## Prerequisites -- `check_failure`: Checks if the operation has failed. +- Python 3.7+ +- OpenAI API key or other supported LLM provider keys +- Swarms library -- `check_error`: Checks if there was an error during the operation. +## Installation -- `check_stopped`: Checks if the operation has been stopped. +```bash +pip3 install -U swarms +``` -- `check_cancelled`: Checks if the operation has been cancelled. +## Environment Variables -- `check_exit`: Checks if the operation has exited. +```plaintext +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" +ANTHROPIC_API_KEY="" +GROQ_API_KEY="" +``` -- `check_end`: Checks if the operation has ended. +## Basic Usage +### 1. Initialize Specialized Agents -**Example**: ```python -from swarms.agents import * - -# Create an instance of ToolAgent -tool_agent = ToolAgent() +from swarms import Agent, MixtureOfAgents -# Check the status of an operation -if check_done(): - print("The operation is done.") -``` +# 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, +) -**Note**: The specific implementations of the stopping condition functions and the `ToolAgent` class are not detailed in this module, as they are imported from other modules within the `swarms.agents` package. +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, +) +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, +) +``` +### 2. Create and Run MixtureOfAgents -### `swarms.agents.tool_agent` +```python +# Create list of specialist agents +specialists = [legal_expert, financial_expert, business_expert] -**Description**: -This module defines the `ToolAgent` class, which represents a specialized agent capable of performing tasks using a specified model and tokenizer. It is designed to run operations that require input validation against a JSON schema, generating outputs based on defined tasks. +# Initialize the mixture of agents +moa = MixtureOfAgents( + agents=specialists, + aggregator_agent=aggregator, + layers=3, +) -**Imports**: -- `Any`, `Optional`, `Callable`: Type hints from the `typing` module for flexible parameter types. +# Run the analysis +result = moa.run( + "Analyze the proposed merger between Company A and Company B, considering legal, financial, and business aspects." +) +``` -- `Agent`: The base class for agents, imported from `swarms.structs.agent`. +## Advanced Usage -- `Jsonformer`: A class responsible for transforming JSON data, imported from `swarms.tools.json_former`. +### 1. Custom Configuration with System Prompts -- `logger`: A logging utility from `swarms.utils.loguru_logger`. +```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, +) +result = moa.run("Evaluate the potential acquisition of StartupX") +``` -### `ToolAgent` -**Description**: -Represents a tool agent that performs a specific task using a model and tokenizer. It facilitates the execution of tasks by calling the appropriate model or using the defined JSON schema for structured output. +### 2. Error Handling and Validation -**Attributes**: -- `name` (`str`): The name of the tool agent. +```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)}") +``` -- `description` (`str`): A description of what the tool agent does. +## Best Practices -- `model` (`Any`): The model used by the tool agent for processing. +1. Agent Selection and Configuration: + - Choose specialists with complementary expertise + - Configure appropriate system prompts + - Set suitable model parameters -- `tokenizer` (`Any`): The tokenizer used by the tool agent to prepare input data. +2. Aggregator Configuration: + - Define clear aggregation criteria + - Set appropriate weights for different opinions + - Configure conflict resolution strategies -- `json_schema` (`Any`): The JSON schema that defines the structure of the expected output. +3. Layer Management: + - Set appropriate number of layers + - Monitor layer effectiveness + - Adjust based on task complexity -- `max_number_tokens` (`int`): The maximum number of tokens to generate (default is 500). +4. Quality Control: + - Implement validation checks + - Monitor agent performance + - Ensure comprehensive coverage -- `parsing_function` (`Optional[Callable]`): A function for parsing the output, if provided. +## Example Implementation -- `llm` (`Any`): A language model, if utilized instead of a custom model. +Here's a complete example showing how to use MixtureOfAgents for a comprehensive business analysis: +```python +import os +from swarms import Agent, MixtureOfAgents -**Methods**: +# 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, +) -- `__init__(self, name: str, description: str, model: Any, tokenizer: Any, json_schema: Any, max_number_tokens: int, parsing_function: Optional[Callable], llm: Any, *args, -**kwargs) -> None` +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, +) - - **Description**: Initializes a new instance of the ToolAgent class. - - - **Parameters**: - - - `name` (`str`): The name of the tool agent. - - - `description` (`str`): A description of the tool agent. - - - `model` (`Any`): The model to use (if applicable). - - - `tokenizer` (`Any`): The tokenizer to use (if applicable). - - - `json_schema` (`Any`): The JSON schema that outlines the expected output format. - - - `max_number_tokens` (`int`): Maximum token output size. - - - `parsing_function` (`Optional[Callable]`): Optional function to parse the output. - - - `llm` (`Any`): The language model to use as an alternative to a custom model. - - - `*args` and `**kwargs`: Additional arguments and keyword arguments for flexibility. - - - **Return**: None. - +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, +) -- `run(self, task: str, *args, **kwargs) -> Any` +# 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, +) - - **Description**: Executes the tool agent for the specified task, utilizing either a model or a language model based on provided parameters. - - - **Parameters**: +# 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, + ) - - `task` (`str`): The task or prompt to be processed by the tool agent. - - - `*args`: Additional positional arguments for flexibility. - - - `**kwargs`: Additional keyword arguments for flexibility. - - - **Return**: + # 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""" + ) - - (`Any`): The output generated by the tool agent based on the input task. - - - **Raises**: + # Process and display results + print("\nComprehensive Analysis Results:") + print("=" * 50) + print(result) + print("=" * 50) - - `Exception`: If neither `model` nor `llm` is provided or if an error occurs during task execution. - - -**Example**: -```python -from transformers import AutoModelForCausalLM, AutoTokenizer -from swarms.agents.tool_agent import ToolAgent - -# Load model and tokenizer -model = AutoModelForCausalLM.from_pretrained("databricks/dolly-v2-12b") - -tokenizer = AutoTokenizer.from_pretrained("databricks/dolly-v2-12b") - +except Exception as e: + print(f"Error during analysis: {str(e)}") +``` -# Define a JSON schema -json_schema = { - "type": "object", - "properties": { - "name": {"type": "string"}, - "age": {"type": "number"}, - "is_student": {"type": "boolean"}, - "courses": { - "type": "array", - "items": {"type": "string"} - } - } -} +This comprehensive guide demonstrates how to effectively use the MixtureOfAgents architecture for complex analysis tasks requiring multiple expert perspectives and consensus-building. -# Create and run a ToolAgent -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(generated_data) -``` +# File: swarms\examples\moa_example.md +# 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. +## How It Works -### `swarms.agents.stopping_conditions` +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 -**Description**: -This module contains a set of functions that check specific stopping conditions based on strings. These functions return boolean values indicating the presence of certain keywords, which can be used to determine the status of an operation or process. +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. -### Functions: +![Mixture of Agents](https://files.readme.io/ddb138e-moa-3layer.png) -- `check_done(s: str) -> bool` - - **Description**: Checks if the string contains the keyword "". - - - **Parameters**: - - - `s` (`str`): The input string to check. - - - **Return**: - - - (`bool`): `True` if "" is found in the string; otherwise, `False`. - +## Installation -- `check_finished(s: str) -> bool` +Install the swarms package using pip: - - **Description**: Checks if the string contains the keyword "finished". - - - **Parameters**: - - - `s` (`str`): The input string to check. - - - **Return**: - - - (`bool`): `True` if "finished" is found in the string; otherwise, `False`. - +```bash +pip install -U swarms +``` -- `check_complete(s: str) -> bool` +## Basic Setup - - **Description**: Checks if the string contains the keyword "complete". - - - **Parameters**: - - - `s` (`str`): The input string to check. - - - **Return**: - - - (`bool`): `True` if "complete" is found in the string; otherwise, `False`. - +1. First, set up your environment variables: -- `check_success(s: str) -> bool` +```python +WORKSPACE_DIR="agent_workspace" +ANTHROPIC_API_KEY="" +``` - - **Description**: Checks if the string contains the keyword "success". - - - **Parameters**: - - - `s` (`str`): The input string to check. - - - **Return**: - - - (`bool`): `True` if "success" is found in the string; otherwise, `False`. - +## Code -- `check_failure(s: str) -> bool` +```python +from swarms import Agent, MixtureOfAgents - - **Description**: Checks if the string contains the keyword "failure". - - - **Parameters**: - - - `s` (`str`): The input string to check. - - - **Return**: +# 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 - - (`bool`): `True` if "failure" is found in the string; otherwise, `False`. - - -- `check_error(s: str) -> bool` + 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, +) - - **Description**: Checks if the string contains the keyword "error". - - - **Parameters**: - - - `s` (`str`): The input string to check. - - - **Return**: +# 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 - - (`bool`): `True` if "error" is found in the string; otherwise, `False`. - - -- `check_stopped(s: str) -> bool` + 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, +) - - **Description**: Checks if the string contains the keyword "stopped". - - - **Parameters**: - - - `s` (`str`): The input string to check. - - - **Return**: +# 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 - - (`bool`): `True` if "stopped" is found in the string; otherwise, `False`. - - -- `check_cancelled(s: str) -> bool` + 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, +) - - **Description**: Checks if the string contains the keyword "cancelled". - - - **Parameters**: - - - `s` (`str`): The input string to check. - - - **Return**: - - - (`bool`): `True` if "cancelled" is found in the string; otherwise, `False`. - -- `check_exit(s: str) -> bool` +swarm = MixtureOfAgents( + agents=[ + risk_metrics_agent, + portfolio_risk_agent, + market_risk_agent, + ], + layers=1, + max_loops=1, + output_type="final", +) - - **Description**: Checks if the string contains the keyword "exit". - - - **Parameters**: - - - `s` (`str`): The input string to check. - - - **Return**: - - - (`bool`): `True` if "exit" is found in the string; otherwise, `False`. - -- `check_end(s: str) -> bool` +out = swarm.run( + "Calculate VaR and Sharpe ratio for a portfolio with 15% annual return and 20% volatility" +) - - **Description**: Checks if the string contains the keyword "end". - - - **Parameters**: - - - `s` (`str`): The input string to check. - - - **Return**: - - - (`bool`): `True` if "end" is found in the string; otherwise, `False`. - +print(out) +``` -**Example**: -```python -from swarms.agents.stopping_conditions import check_done, check_error +## Support and Community -status_message = "The process has finished and !" +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! -if check_done(status_message): - print("The operation is done!") +| 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 | -if check_error(status_message): - print("An error has occurred!") -``` -**Note**: Each of these functions provides a simple way to check for specific keywords in a given string, which can be helpful in managing and monitoring tasks or operations. +-------------------------------------------------- +# File: swarms\examples\model_providers.md -# Schemas +# Model Providers Overview -### `swarms.schemas.base_schemas` +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. -**Description**: -This module defines various Pydantic models that represent schemas used in machine learning applications. These models facilitate data validation and serialization for different types of content, such as model cards, chat messages, and responses. +## Supported Model Providers -**Imports**: -- `uuid`: A module for generating unique identifiers. +| 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) | -- `time`: A module for time-related functions. +## Quick Start -- `List`, `Literal`, `Optional`, `Union`: Type hints from the `typing` module for flexible parameter types. +All model providers follow a consistent pattern in Swarms. Here's the basic template: -- `BaseModel`, `Field`: Tools from the `pydantic` module for data validation and settings management. +```python +from swarms import Agent +import os +from dotenv import load_dotenv +load_dotenv() -### `ModelCard` -**Description**: -A Pydantic model that represents a model card, which provides metadata about a machine learning model. +# Initialize agent with your chosen model +agent = 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.", +) -**Attributes**: -- `id` (`str`): The unique identifier for the model. +# Run your agent +response = agent.run("Your query here") +``` -- `object` (`str`): A fixed string indicating the type of object ("model"). +## Model Selection Guide -- `created` (`int`): The timestamp of model creation, defaults to the current time. +### For High-Performance Applications -- `owned_by` (`str`): The owner of the model. +- **OpenAI GPT-4o**: Best overall performance and reasoning -- `root` (`Optional[str]`): The root model identifier if applicable. +- **Anthropic Claude**: Excellent safety and analysis capabilities -- `parent` (`Optional[str]`): The parent model identifier if applicable. +- **DeepSeek R1**: Advanced reasoning and problem-solving -- `permission` (`Optional[list]`): A list of permissions associated with the model. +### For Cost-Effective Solutions +- **OpenAI GPT-4o-mini**: Great performance at lower cost -### `ModelList` -**Description**: -A Pydantic model that represents a list of model cards. +- **Ollama**: Free local deployment -**Attributes**: -- `object` (`str`): A fixed string indicating the type of object ("list"). +- **OpenRouter**: Access to cost-effective models -- `data` (`List[ModelCard]`): A list containing instances of `ModelCard`. +### For Real-Time Applications +- **Groq**: Ultra-fast inference -### `ImageUrl` -**Description**: -A Pydantic model representing an image URL. +- **vLLM**: Optimized for high throughput -**Attributes**: -- `url` (`str`): The URL of the image. +### For Specialized Tasks +- **Llama4**: Expert routing for complex workflows -### `TextContent` -**Description**: -A Pydantic model representing text content. +- **XAI Grok**: Advanced research capabilities -**Attributes**: -- `type` (`Literal["text"]`): A fixed string indicating the type of content (text). +- **Cohere**: Strong business applications -- `text` (`str`): The actual text content. +## Environment Setup +Most providers require API keys. Add them to your `.env` file: -### `ImageUrlContent` -**Description**: -A Pydantic model representing image content via URL. +```bash +# OpenAI +OPENAI_API_KEY=your_openai_key -**Attributes**: -- `type` (`Literal["image_url"]`): A fixed string indicating the type of content (image URL). +# Anthropic +ANTHROPIC_API_KEY=your_anthropic_key -- `image_url` (`ImageUrl`): An instance of `ImageUrl` containing the URL of the image. +# Groq +GROQ_API_KEY=your_groq_key +# Cohere +COHERE_API_KEY=your_cohere_key -### `ContentItem` -**Description**: -A type alias for a union of `TextContent` and `ImageUrlContent`, representing any content type that can be processed. +# DeepSeek +DEEPSEEK_API_KEY=your_deepseek_key -### `ChatMessageInput` -**Description**: -A Pydantic model representing an input message for chat applications. +# OpenRouter +OPENROUTER_API_KEY=your_openrouter_key -**Attributes**: -- `role` (`str`): The role of the sender (e.g., "user", "assistant", or "system"). +# XAI +XAI_API_KEY=your_xai_key -- `content` (`Union[str, List[ContentItem]]`): The content of the message, which can be a string or a list of content items. +# 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. -### `ChatMessageResponse` -**Description**: -A Pydantic model representing a response message in chat applications. +## Advanced Features -**Attributes**: -- `role` (`str`): The role of the sender (e.g., "user", "assistant", or "system"). +### Multi-Model Workflows -- `content` (`str`, optional): The content of the response message. +Swarms allows you to create workflows that use different models for different tasks: +```python +from swarms import Agent, ConcurrentWorkflow -### `DeltaMessage` -**Description**: -A Pydantic model representing a delta update for messages in chat applications. +# Research agent using Claude for analysis +research_agent = Agent( + agent_name="Research-Agent", + model_name="claude-3-sonnet-20240229", + system_prompt="You are a research expert." +) -**Attributes**: -- `role` (`Optional[Literal["user", "assistant", "system"]]`): The role of the sender, if specified. +# 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." +) -- `content` (`Optional[str]`): The content of the delta message, if provided. +# Workflow combining both agents +workflow = ConcurrentWorkflow( + name="Research-Creative-Workflow", + agents=[research_agent, creative_agent] +) +``` +### Model Routing -### `ChatCompletionRequest` -**Description**: -A Pydantic model representing a request for chat completion. +Automatically route tasks to the most appropriate model: -**Attributes**: -- `model` (`str`): The model to use for completing the chat (default is "gpt-4o"). +```python +from swarms import Agent, ModelRouter -- `messages` (`List[ChatMessageInput]`): A list of input messages for the chat. +# 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" + } +) -- `temperature` (`Optional[float]`): Controls the randomness of the output (default is 0.8). +# Agent will automatically choose the best model +agent = Agent( + agent_name="Smart-Agent", + llm=model_router, + system_prompt="You are a versatile assistant." +) +``` -- `top_p` (`Optional[float]`): An alternative to sampling with temperature (default is 0.8). +## Getting Help -- `max_tokens` (`Optional[int]`): The maximum number of tokens to generate (default is 4000). +- **Documentation**: Each provider has detailed documentation with examples -- `stream` (`Optional[bool]`): If true, the response will be streamed (default is False). +- **Community**: Join the Swarms community for support and best practices -- `repetition_penalty` (`Optional[float]`): A penalty for repeated tokens (default is 1.0). +- **Issues**: Report bugs and request features on GitHub -- `echo` (`Optional[bool]`): If true, the input will be echoed in the output (default is False). +- **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. -### `ChatCompletionResponseChoice` -**Description**: -A Pydantic model representing a choice in a chat completion response. -**Attributes**: -- `index` (`int`): The index of the choice. +-------------------------------------------------- -- `input` (`str`): The input message. +# File: swarms\examples\multi_agent_router_minimal.md -- `message` (`ChatMessageResponse`): The output message. +# MultiAgentRouter Minimal Example +This example shows how to route a task to the most suitable agent using `SwarmRouter` with `swarm_type="MultiAgentRouter"`. -### `ChatCompletionResponseStreamChoice` -**Description**: -A Pydantic model representing a choice in a streamed chat completion response. +```python +from swarms import Agent +from swarms.structs.swarm_router import SwarmRouter -**Attributes**: -- `index` (`int`): The index of the choice. +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", + ), +] -- `delta` (`DeltaMessage`): The delta update for the message. +router = SwarmRouter( + name="multi-agent-router-demo", + description="Routes tasks to the most suitable agent", + agents=agents, + swarm_type="MultiAgentRouter" +) +result = router.run("Write a function that adds two numbers") +print(result) +``` -### `UsageInfo` -**Description**: -A Pydantic model representing usage information for a chat completion request. +View the source on [GitHub](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/mar/multi_agent_router_minimal.py). -**Attributes**: -- `prompt_tokens` (`int`): The number of tokens used in the prompt (default is 0). +-------------------------------------------------- -- `total_tokens` (`int`): The total number of tokens used (default is 0). +# File: swarms\examples\multiple_images.md -- `completion_tokens` (`Optional[int]`): The number of tokens used in the completion (default is 0). +# Processing Multiple Images +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. -### `ChatCompletionResponse` -**Description**: -A Pydantic model representing a response from a chat completion request. -**Attributes**: -- `model` (`str`): The model used for the completion. +## Installation -- `object` (`Literal["chat.completion", "chat.completion.chunk"]`): The type of response object. +Install the swarms package using pip: -- `choices` (`List[Union[ChatCompletionResponseChoice, ChatCompletionResponseStreamChoice]]`): A list of choices from the completion. +```bash +pip install -U swarms +``` -- `created` (`Optional[int]`): The timestamp of when the response was created. +## Basic Setup +1. First, set up your environment variables: -### `AgentChatCompletionResponse` -**Description**: -A Pydantic model representing a completion response from an agent. +```python +WORKSPACE_DIR="agent_workspace" +ANTHROPIC_API_KEY="" +``` -**Attributes**: -- `id` (`Optional[str]`): The ID of the agent that generated the completion response (default is a new UUID). -- `agent_name` (`Optional[str]`): The name of the agent that generated the response. +## Code -- `object` (`Optional[Literal["chat.completion", "chat.completion.chunk"]]`): The type of response object. +- Create a list of images by their file paths -- `choices` (`Optional[ChatCompletionResponseChoice]`): The choice from the completion response. +- Pass it into the `Agent.run(imgs=[str])` parameter -- `created` (`Optional[int]`): The timestamp of when the response was created. +- Activate `summarize_multiple_images=True` if you want the agent to output a summary of the image analyses -**Example**: ```python -from swarms.schemas.base_schemas import ChatCompletionRequest, ChatMessageInput - -# Create a chat completion request -request = ChatCompletionRequest( - model="gpt-4", - - messages=[ - ChatMessageInput(role="user", content="Hello! How can I help you?") - ] +from swarms import Agent +from swarms.prompts.logistics import ( + Quality_Control_Agent_Prompt, ) -``` -**Note**: The Pydantic models in this module provide a structured way to handle data related to machine learning models and chat interactions, ensuring that the data adheres to defined schemas. +# 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], +) -### `swarms.schemas.plan` +print(response) +``` -**Description**: -This module defines the `Plan` class, which represents a sequence of steps in a structured format. It utilizes Pydantic for data validation and configuration, ensuring that each plan consists of a list of defined steps. +## Support and Community -**Imports**: -- `List`: A type hint from the `typing` module for work with lists. +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! -- `BaseModel`: The Pydantic base class for data models, providing validation and serialization features. +| 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 | -- `Step`: A model representing individual steps in the plan, imported from `swarms.schemas.agent_step_schemas`. -### `Plan` -**Description**: -Represents a sequence of steps that comprise a plan. This class ensures that the data structure adheres to the expected model for steps. +-------------------------------------------------- -**Attributes**: -- `steps` (`List[Step]`): A list of steps, where each step is an instance of the `Step` model. +# File: swarms\examples\ollama.md +# Agent with Ollama -**Config**: -- `orm_mode` (bool): Enables compatibility with ORM models to facilitate data loading from database objects. +- No API key needed +- Select your model_name like `ollama/llama2` follows [LiteLLM conventions](https://docs.litellm.ai/docs/providers/ollama) -**Example**: ```python -from swarms.schemas.plan import Plan -from swarms.schemas.agent_step_schemas import Step +from swarms import Agent +import os +from dotenv import load_dotenv -# Create a list of steps -steps = [ - Step(/* initialize step attributes */), - Step(/* initialize step attributes */), -] +load_dotenv() -# Create a Plan instance -plan = Plan(steps=steps) +# 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.", +) -# Access the steps -for step in plan.steps: - print(step) +# Run a query +agent.run("What are the components of a startup's stock incentive equity plan?") ``` -**Note**: The `Plan` class relies on the `Step` model for its structure, ensuring that the steps in a plan conform to the validation rules defined in the `Step` model. - +-------------------------------------------------- +# File: swarms\examples\openai_example.md +# Agent with GPT-4o-Mini -### `swarms.schemas.__init__` +- Add `OPENAI_API_KEY="your_key"` to your `.env` file +- Select your model like `gpt-4o-mini` or `gpt-4o` -**Description**: -This module serves as the initialization point for the schemas subpackage within the Swarms framework. It imports and exposes key classes related to agent steps and agent input schemas, making them available for use in other parts of the application. +```python +from swarms import Agent -**Imports**: -- `Step`: A model representing an individual step in an agent's operation, imported from `swarms.schemas.agent_step_schemas`. +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") +``` -- `ManySteps`: A model representing multiple steps, also imported from `swarms.schemas.agent_step_schemas`. +-------------------------------------------------- -- `AgentSchema`: A model representing the schema for agent inputs, imported from `swarms.schemas.agent_input_schema`. +# File: swarms\examples\openrouter.md +# Agent with OpenRouter -**Exported Classes**: -- `Step`: The class for defining individual steps in an agent's operation. +- Add your `OPENROUTER_API_KEY` in the `.env` file -- `ManySteps`: The class for defining multiple steps in an agent's operation. +- Select your model_name like `openrouter/google/palm-2-chat-bison` follows [LiteLLM conventions](https://docs.litellm.ai/docs/providers/openrouter) -- `AgentSchema`: The class for defining the input schema for agents. +- Execute your agent! -**Example**: ```python -from swarms.schemas import * +from swarms import Agent +import os +from dotenv import load_dotenv -# Create an instance of Step -step = Step(/* initialize step attributes */) +load_dotenv() -# Create an instance of ManySteps -many_steps = ManySteps(steps=[step, step]) +# 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.", +) -# Create an instance of AgentSchema -agent_schema = AgentSchema(/* initialize agent schema attributes */) +# Run a query +agent.run("What are the components of a startup's stock incentive equity plan?") ``` -**Note**: This module acts as a central point for importing and utilizing the various schema classes defined in the Swarms framework, facilitating structured data handling for agents and their operations. - +-------------------------------------------------- +# File: swarms\examples\quant_crypto_agent.md +# Quant Crypto Agent -### `swarms.schemas.agent_step_schemas` +- 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. -**Description**: -This module defines the `Step` and `ManySteps` classes, which represent individual steps and collections of steps in a task, respectively. These classes utilize Pydantic for data validation and serialization, ensuring that each step adheres to the defined schema. +## Steps -**Imports**: -- `time`: A module for time-related functions. +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. -- `uuid`: A module for generating unique identifiers. +## Installation: -- `List`, `Optional`, `Any`: Type hints from the `typing` module for flexible parameter types. +```bash +pip install swarms swarms-tools python-dotenv +``` -- `BaseModel`, `Field`: Tools from the `pydantic` module for data validation and settings management. +## Code: -- `AgentChatCompletionResponse`: A model representing the response from an agent's chat completion, imported from `swarms.schemas.base_schemas`. +```python +from swarms import Agent +from dotenv import load_dotenv +from swarms_tools import fetch_htx_data, coin_gecko_coin_api +load_dotenv() -### `get_current_time() -> str` +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 -**Description**: -Returns the current time formatted as "YYYY-MM-DD HH:MM:SS". +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 -**Return**: -- (`str`): The current time as a formatted string. +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 -### `Step` -**Description**: -A Pydantic model representing a single step in a task, including its ID, completion time, and response from an agent. +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 -**Attributes**: -- `step_id` (`Optional[str]`): The unique identifier for the step, generated if not provided. +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 -- `time` (`Optional[float]`): The time taken to complete the task step, formatted as a string. +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 +""" -- `response` (`Optional[AgentChatCompletionResponse]`): The response from the agent for this step. +# 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")) -### `ManySteps` -**Description**: -A Pydantic model representing a collection of steps associated with a specific agent and task. +# 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")} + + """ +) +``` -**Attributes**: -- `agent_id` (`Optional[str]`): The unique identifier for the agent. +-------------------------------------------------- -- `agent_name` (`Optional[str]`): The name of the agent. +# File: swarms\examples\sequential_example.md -- `task` (`Optional[str]`): The name of the task being performed. +# Sequential Workflow Example -- `max_loops` (`Optional[Any]`): The maximum number of steps in the task. +!!! 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. -- `run_id` (`Optional[str]`): The ID of the task this collection of steps belongs to. +## Prerequisites -- `steps` (`Optional[List[Step]]`): A list of `Step` instances representing the steps of the task. +!!! info "Before You Begin" + Make sure you have: + + - Python 3.7+ installed + + - A valid API key for your model provider + + - The Swarms package installed -- `full_history` (`Optional[str]`): A string containing the full history of the task. +## Installation -- `total_tokens` (`Optional[int]`): The total number of tokens generated during the task. +```bash +pip3 install -U swarms +``` -- `stopping_token` (`Optional[str]`): The token at which the task stopped. +## Environment Setup -- `interactive` (`Optional[bool]`): Indicates whether the task is interactive. +!!! tip "API Key Configuration" + Set your API key in the `.env` file: + ```bash + OPENAI_API_KEY="your-api-key-here" + ``` -- `dynamic_temperature_enabled` (`Optional[bool]`): Indicates whether dynamic temperature adjustments are enabled for the task. +## Code Implementation +### Import Required Modules -**Example**: ```python -from swarms.schemas.agent_step_schemas import Step, ManySteps +from swarms import Agent, SequentialWorkflow +``` -# Create a step instance -step = Step(step_id="12345", response=AgentChatCompletionResponse(...)) +### Configure Agents -# Create a ManySteps instance -many_steps = ManySteps( - agent_id="agent-1", - - agent_name="Test Agent", - task="Example Task", - max_loops=5, - steps=[step], - full_history="Task executed successfully.", - total_tokens=100 -) +!!! example "Legal Agent Configuration" + Here's how to set up your specialized legal agents: -print(many_steps) -``` + ```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, + ) -**Note**: The `Step` and `ManySteps` classes provide structured representations of task steps, ensuring that all necessary information is captured and validated according to the defined schemas. + # 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: -### `swarms.schemas.agent_input_schema` + ```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.", + ) + ``` -**Description**: -This module defines the `AgentSchema` class using Pydantic, which represents the input parameters necessary for configuring an agent in the Swarms framework. It includes a variety of attributes for specifying the agent's behavior, model settings, and operational parameters. +### Run the Workflow -**Imports**: -- `Any`, `Callable`, `Dict`, `List`, `Optional`: Type hints from the `typing` module for flexible parameter types. +!!! example "Execute the Workflow" + Start the sequential workflow: -- `BaseModel`, `Field`: Tools from the `pydantic` module for data validation and settings management. + ```python + swarm.run("Create a report on how to patent an all-new AI invention and what platforms to use and more.") + ``` -- `validator`: A decorator from Pydantic used for custom validation of fields. +## Complete Example +!!! success "Full Implementation" + Here's the complete code combined: -### `AgentSchema` -**Description**: -Represents the configuration for an agent, including attributes that govern its behavior, capabilities, and interaction with language models. This class ensures that the input data adheres to defined validation rules. + ```python + from swarms import Agent, SequentialWorkflow -**Attributes**: -- `llm` (`Any`): The language model to use. + # 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, + ) -- `max_tokens` (`int`): The maximum number of tokens the agent can generate, must be greater than or equal to 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, + ) -- `context_window` (`int`): The size of the context window, must be greater than or equal to 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, + ) -- `user_name` (`str`): The name of the user interacting with the agent. + # 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.", + ) -- `agent_name` (`str`): The name of the agent. + swarm.run("Create a report on how to patent an all-new AI invention and what platforms to use and more.") + ``` -- `system_prompt` (`str`): The system prompt provided to the agent. +## Agent Roles -- `template` (`Optional[str]`): An optional template for the agent, default is `None`. +!!! 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 | -- `max_loops` (`Optional[int]`): The maximum number of loops the agent can perform (default is 1, must be greater than or equal to 1). +## Configuration Options -- `stopping_condition` (`Optional[Callable[[str], bool]]`): A callable function that defines a stopping condition for the agent. +!!! 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 | -- `loop_interval` (`Optional[int]`): The interval between loops (default is 0, must be greater than or equal to 0). +## Next Steps -- `retry_attempts` (`Optional[int]`): Number of times to retry an operation if it fails (default is 3, must be greater than or equal to 0). +!!! 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 -- `retry_interval` (`Optional[int]`): The time between retry attempts (default is 1, must be greater than or equal to 0). +## Troubleshooting -- `return_history` (`Optional[bool]`): Flag indicating whether to return the history of the agent's operations (default is `False`). +!!! 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 -- `stopping_token` (`Optional[str]`): Token indicating when to stop processing (default is `None`). -- `dynamic_loops` (`Optional[bool]`): Indicates whether dynamic loops are enabled (default is `False`). +-------------------------------------------------- -- `interactive` (`Optional[bool]`): Indicates whether the agent operates in an interactive mode (default is `False`). +# File: swarms\examples\swarm_router.md -- `dashboard` (`Optional[bool]`): Flag indicating whether a dashboard interface is enabled (default is `False`). +# SwarmRouter Examples -- `agent_description` (`Optional[str]`): A description of the agent's functionality (default is `None`). +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`. -- `tools` (`Optional[List[Callable]]`): List of callable tools the agent can use (default is `None`). +## Prerequisites -- `dynamic_temperature_enabled` (`Optional[bool]`): Indicates whether dynamic temperature adjustments are enabled (default is `False`). +- Python 3.7+ +- OpenAI API key or other supported LLM provider keys +- Swarms library -- Additional attributes for managing various functionalities and configurations related to the agent's behavior, such as logging, saving states, and managing tools. +## Installation +```bash +pip3 install -U swarms +``` -### Validators: +## Environment Variables -- **check_list_items_not_none(v)**: Ensures that items within certain list attributes (`tools`, `docs`, `sop_list`, etc.) are not `None`. +```plaintext +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" +ANTHROPIC_API_KEY="" +GROQ_API_KEY="" +``` -- **check_optional_callable_not_none(v)**: Ensures that optional callable attributes are either `None` or callable. +## Basic Usage +### 1. Initialize Specialized Agents -**Example**: ```python -from swarms.schemas.agent_input_schema import AgentSchema - -# Define the agent configuration data -agent_data = { - "llm": "OpenAIChat", - "max_tokens": 4096, - "context_window": 8192, - "user_name": "Human", - "agent_name": "test-agent", - - "system_prompt": "Custom system prompt", -} +from swarms import Agent +from swarms.structs.swarm_router import SwarmRouter, SwarmType -# Create an AgentSchema instance -agent = AgentSchema(**agent_data) -print(agent) -``` +# 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, +) -**Note**: The `AgentSchema` class provides a structured way to configure agents in the Swarms framework, ensuring that all necessary parameters are validated before use. +summarizer_agent = Agent( + agent_name="Document-Summarizer", + system_prompt="You are a document summarization expert...", + model_name="gpt-4o", + max_loops=1, +) +financial_analyst_agent = Agent( + agent_name="Financial-Analyst", + system_prompt="You are a financial analysis specialist...", + model_name="gpt-4o", + max_loops=1, +) +``` +### 2. Create SwarmRouter with Sequential Workflow +```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 +) --------------------------------------------------- +# Run a task +result = sequential_router.run("Analyze and summarize the quarterly financial report") +``` -# File: swarms\framework\test.md +### 3. Create SwarmRouter with Concurrent Workflow -# How to Run Tests Using Pytest: A Comprehensive Guide +```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 +) -In modern software development, automated testing is crucial for ensuring the reliability and functionality of your code. One of the most popular testing frameworks for Python is `pytest`. +# Run a task +result = concurrent_router.run("Evaluate multiple aspects of the company simultaneously") +``` -This blog will provide an in-depth look at how to run tests using `pytest`, including testing a single file, multiple files, every file in the test repository, and providing guidelines for contributors to run tests reliably. +### 4. Create SwarmRouter with AgentRearrange -## What is Pytest? +```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 +) -`pytest` is a testing framework for Python that makes it easy to write simple and scalable test cases. It supports fixtures, parameterized testing, and has a rich plugin architecture. `pytest` is widely used because of its ease of use and powerful features that help streamline the testing process. +# Run a task +result = rearrange_router.run("Process and analyze company documents") +``` -## Installation +### 5. Create SwarmRouter with MixtureOfAgents -To get started with `pytest`, you need to install it. You can install `pytest` using `pip`: +```python +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 +) -```bash -pip install pytest +# Run a task +result = mixture_router.run("Provide comprehensive analysis of company performance") ``` -## Writing Your First Test +## Advanced Features -Before diving into running tests, let’s write a simple test. Create a file named `test_sample.py` with the following content: +### 1. Error Handling and Logging ```python -def test_addition(): - assert 1 + 1 == 2 +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)}") +``` -def test_subtraction(): - assert 2 - 1 == 1 +### 2. Custom Configuration + +```python +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" +) ``` -In this example, we have defined two basic tests: `test_addition` and `test_subtraction`. +# Best Practices -## Running Tests +## Choose the appropriate swarm type based on your task requirements: -### Running a Single Test File +| 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 | -To run a single test file, you can use the `pytest` command followed by the filename. For example, to run the tests in `test_sample.py`, use the following command: +## Configure agents appropriately: -```bash -pytest test_sample.py -``` + | 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 | -The output will show the test results, including the number of tests passed, failed, or skipped. +## Implement proper error handling: -### Running Multiple Test Files +| 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 | -You can also run multiple test files by specifying their filenames separated by a space. For example: +## Optimize performance: -```bash -pytest test_sample.py test_another_sample.py -``` +| 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 | -If you have multiple test files in a directory, you can run all of them by specifying the directory name: +## Example Implementation -```bash -pytest tests/ -``` +Here's a complete example showing how to use SwarmRouter in a real-world scenario: -### Running All Tests in the Repository +```python +import os +from swarms import Agent +from swarms.structs.swarm_router import SwarmRouter, SwarmType -To run all tests in the repository, navigate to the root directory of your project and simply run: +# Initialize specialized agents +research_agent = Agent( + agent_name="ResearchAgent", + system_prompt="You are a research specialist...", + model_name="gpt-4o", + max_loops=1 +) -```bash -pytest -``` +analysis_agent = Agent( + agent_name="AnalysisAgent", + system_prompt="You are an analysis expert...", + model_name="gpt-4o", + max_loops=1 +) -`pytest` will automatically discover and run all the test files that match the pattern `test_*.py` or `*_test.py`. +summary_agent = Agent( + agent_name="SummaryAgent", + system_prompt="You are a summarization specialist...", + model_name="gpt-4o", + max_loops=1 +) -### Test Discovery +# 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 +) -`pytest` automatically discovers test files and test functions based on their naming conventions. By default, it looks for files that match the pattern `test_*.py` or `*_test.py` and functions or methods that start with `test_`. +# Run complex task +try: + result = router.run( + "Research and analyze the impact of AI on healthcare, " + "providing a comprehensive summary of findings." + ) + 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)}") +``` -### Using Markers +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. -`pytest` allows you to use markers to group tests or add metadata to them. Markers can be used to run specific subsets of tests. For example, you can mark a test as `slow` and then run only the slow tests or skip them. +-------------------------------------------------- -```python -import pytest +# File: swarms\examples\swarms_api_finance.md -@pytest.mark.slow -def test_long_running(): - import time - time.sleep(5) - assert True -def test_fast(): - assert True -``` +# Finance Swarm Example -To run only the tests marked as `slow`, use the `-m` option: +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 -pytest -m slow +SWARMS_API_KEY= ``` -### Parameterized Tests +3. Create a Python script to create and trigger the financial swarm: -`pytest` supports parameterized testing, which allows you to run a test with different sets of input data. This can be done using the `@pytest.mark.parametrize` decorator. ```python -import pytest - -@pytest.mark.parametrize("a,b,expected", [ - (1, 2, 3), - (2, 3, 5), - (3, 5, 8), -]) -def test_add(a, b, expected): - assert a + b == expected -``` - -In this example, `test_add` will run three times with different sets of input data. - -### Fixtures +import os +import requests +from dotenv import load_dotenv +import json -Fixtures are a powerful feature of `pytest` that allow you to set up some context for your tests. They can be used to provide a fixed baseline upon which tests can reliably and repeatedly execute. +load_dotenv() -```python -import pytest +# Retrieve API key securely from .env +API_KEY = os.getenv("SWARMS_API_KEY") +BASE_URL = "https://api.swarms.world" -@pytest.fixture -def sample_data(): - return {"name": "John", "age": 30} +# Headers for secure API communication +headers = {"x-api-key": API_KEY, "Content-Type": "application/json"} -def test_sample_data(sample_data): - assert sample_data["name"] == "John" - assert sample_data["age"] == 30 -``` +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. + """ -Fixtures can be used to share setup and teardown code between tests. + payload = { + "swarm_name": "Enhanced Financial Analysis Swarm", + "description": "A swarm of agents specialized in performing comprehensive financial analysis, risk assessment, and market recommendations.", + "agents": [ + { + "agent_name": "Equity Analyst", + "description": "Agent specialized in analyzing equities data to provide insights on stock performance and valuation.", + "system_prompt": ( + "You are an experienced equity analyst with expertise in financial markets and stock valuation. " + "Your role is to analyze the provided equities data, including historical performance, financial statements, and market trends. " + "Provide a detailed analysis of the stock's potential, including valuation metrics and growth prospects. " + "Consider macroeconomic factors, industry trends, and company-specific news. Your analysis should be clear, actionable, and well-supported by data." + ), + "model_name": "openai/gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 4000, + "temperature": 0.3, + "auto_generate_prompt": False + }, + { + "agent_name": "Risk Assessor", + "description": "Agent responsible for evaluating the risks associated with equity investments.", + "system_prompt": ( + "You are a certified risk management professional with expertise in financial risk assessment. " + "Your task is to evaluate the risks associated with the provided equities data, including market risk, credit risk, and operational risk. " + "Provide a comprehensive risk analysis, including potential scenarios and their impact on investment performance. " + "Your output should be detailed, reliable, and compliant with current risk management standards." + ), + "model_name": "openai/gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 3000, + "temperature": 0.2, + "auto_generate_prompt": False + }, + { + "agent_name": "Market Advisor", + "description": "Agent dedicated to suggesting investment strategies based on market conditions and equity analysis.", + "system_prompt": ( + "You are a knowledgeable market advisor with expertise in investment strategies and portfolio management. " + "Based on the analysis provided by the Equity Analyst and the risk assessment, your task is to recommend a comprehensive investment strategy. " + "Your suggestions should include asset allocation, diversification strategies, and considerations for market conditions. " + "Explain the rationale behind each recommendation and reference relevant market data where applicable. " + "Your recommendations should be reliable, detailed, and clearly prioritized based on risk and return." + ), + "model_name": "openai/gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 5000, + "temperature": 0.3, + "auto_generate_prompt": False + } + ], + "max_loops": 1, + "swarm_type": "SequentialWorkflow", + "task": equity_data, + } -## Advanced Usage + # Payload includes the equity data as the task to be processed by the swarm -### Running Tests in Parallel + response = requests.post( + f"{BASE_URL}/v1/swarm/completions", + headers=headers, + json=payload, + ) -`pytest` can run tests in parallel using the `pytest-xdist` plugin. To install `pytest-xdist`, run: + if response.status_code == 200: + print("Swarm successfully executed!") + return json.dumps(response.json(), indent=4) + else: + print(f"Error {response.status_code}: {response.text}") + return None -```bash -pip install pytest-xdist -``` -To run tests in parallel, use the `-n` option followed by the number of CPU cores you want to use: +# Example Equity Data for the Swarm to analyze +if __name__ == "__main__": + equity_data = ( + "Analyze the equity data for Company XYZ, which has shown a 15% increase in revenue over the last quarter, " + "with a P/E ratio of 20 and a market cap of $1 billion. Consider the current market conditions and potential risks." + ) -```bash -pytest -n 4 + financial_output = create_financial_swarm(equity_data) + print(financial_output) ``` -### Generating Test Reports - -`pytest` can generate detailed test reports. You can use the `--html` option to generate an HTML report: +4. Run the script: ```bash -pip install pytest-html -pytest --html=report.html +python financial_swarm.py ``` -This command will generate a file named `report.html` with a detailed report of the test results. - -### Code Coverage -You can use the `pytest-cov` plugin to measure code coverage. To install `pytest-cov`, run: -```bash -pip install pytest-cov -``` +-------------------------------------------------- -To generate a coverage report, use the `--cov` option followed by the module name: +# File: swarms\examples\swarms_api_medical.md -```bash -pytest --cov=my_module -``` +# Medical Swarm Example -This command will show the coverage summary in the terminal. You can also generate an HTML report: +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 -pytest --cov=my_module --cov-report=html +SWARMS_API_KEY= ``` -The coverage report will be generated in the `htmlcov` directory. - -## Best Practices for Writing Tests - -1. **Write Clear and Concise Tests**: Each test should focus on a single piece of functionality. -2. **Use Descriptive Names**: Test function names should clearly describe what they are testing. -3. **Keep Tests Independent**: Tests should not depend on each other and should run in isolation. -4. **Use Fixtures**: Use fixtures to set up the context for your tests. -5. **Mock External Dependencies**: Use mocking to isolate the code under test from external dependencies. +3. Create a Python script to create and trigger the medical swarm: -## Running Tests Reliably +```python +import os +import requests +from dotenv import load_dotenv +import json -For contributors and team members, it’s important to run tests reliably to ensure consistent results. Here are some guidelines: +load_dotenv() -1. **Set Up a Virtual Environment**: Use a virtual environment to manage dependencies and ensure a consistent testing environment. - - ```bash - python -m venv venv - source venv/bin/activate # On Windows use `venv\Scripts\activate` - ``` +# Retrieve API key securely from .env +API_KEY = os.getenv("SWARMS_API_KEY") +BASE_URL = "https://api.swarms.world" -2. **Install Dependencies**: Install all required dependencies from the `requirements.txt` file. - - ```bash - pip install -r requirements.txt - ``` +# Headers for secure API communication +headers = {"x-api-key": API_KEY, "Content-Type": "application/json"} -3. **Run Tests Before Pushing**: Ensure all tests pass before pushing code to the repository. +def create_medical_swarm(patient_case: str): + """ + Constructs and triggers a full-stack medical swarm consisting of three agents: + Diagnostic Specialist, Medical Coder, and Treatment Advisor. + Each agent is provided with a comprehensive, detailed system prompt to ensure high reliability. + """ -4. **Use Continuous Integration (CI)**: Set up CI pipelines to automatically run tests on each commit or pull request. + payload = { + "swarm_name": "Enhanced Medical Diagnostic Swarm", + "description": "A swarm of agents specialized in performing comprehensive medical diagnostics, analysis, and coding.", + "agents": [ + { + "agent_name": "Diagnostic Specialist", + "description": "Agent specialized in analyzing patient history, symptoms, lab results, and imaging data to produce accurate diagnoses.", + "system_prompt": ( + "You are an experienced, board-certified medical diagnostician with over 20 years of clinical practice. " + "Your role is to analyze all available patient information—including history, symptoms, lab tests, and imaging results—" + "with extreme attention to detail and clinical nuance. Provide a comprehensive differential diagnosis considering " + "common, uncommon, and rare conditions. Always cross-reference clinical guidelines and evidence-based medicine. " + "Explain your reasoning step by step and provide a final prioritized list of potential diagnoses along with their likelihood. " + "Consider patient demographics, comorbidities, and risk factors. Your diagnosis should be reliable, clear, and actionable." + ), + "model_name": "openai/gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 4000, + "temperature": 0.3, + "auto_generate_prompt": False + }, + { + "agent_name": "Medical Coder", + "description": "Agent responsible for translating medical diagnoses and procedures into accurate standardized medical codes (ICD-10, CPT, etc.).", + "system_prompt": ( + "You are a certified and experienced medical coder, well-versed in ICD-10, CPT, and other coding systems. " + "Your task is to convert detailed medical diagnoses and treatment procedures into precise, standardized codes. " + "Consider all aspects of the clinical documentation including severity, complications, and comorbidities. " + "Provide clear explanations for the codes chosen, referencing the latest coding guidelines and payer policies where relevant. " + "Your output should be comprehensive, reliable, and fully compliant with current medical coding standards." + ), + "model_name": "openai/gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 3000, + "temperature": 0.2, + "auto_generate_prompt": False + }, + { + "agent_name": "Treatment Advisor", + "description": "Agent dedicated to suggesting evidence-based treatment options, including pharmaceutical and non-pharmaceutical interventions.", + "system_prompt": ( + "You are a highly knowledgeable medical treatment specialist with expertise in the latest clinical guidelines and research. " + "Based on the diagnostic conclusions provided, your task is to recommend a comprehensive treatment plan. " + "Your suggestions should include first-line therapies, potential alternative treatments, and considerations for patient-specific factors " + "such as allergies, contraindications, and comorbidities. Explain the rationale behind each treatment option and reference clinical guidelines where applicable. " + "Your recommendations should be reliable, detailed, and clearly prioritized based on efficacy and safety." + ), + "model_name": "openai/gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 5000, + "temperature": 0.3, + "auto_generate_prompt": False + } + ], + "max_loops": 1, + "swarm_type": "SequentialWorkflow", + "task": patient_case, + } -### Example CI Configuration (GitHub Actions) + # Payload includes the patient case as the task to be processed by the swar -Here is an example of a GitHub Actions workflow to run tests using `pytest`: + response = requests.post( + f"{BASE_URL}/v1/swarm/completions", + headers=headers, + json=payload, + ) -```yaml -name: Python package + if response.status_code == 200: + print("Swarm successfully executed!") + return json.dumps(response.json(), indent=4) + else: + print(f"Error {response.status_code}: {response.text}") + return None -on: [push, pull_request] -jobs: - build: - runs-on: ubuntu-latest +# Example Patient Task for the Swarm to diagnose and analyze +if __name__ == "__main__": + patient_case = ( + "Patient is a 55-year-old male presenting with severe chest pain, shortness of breath, elevated blood pressure, " + "nausea, and a family history of cardiovascular disease. Blood tests show elevated troponin levels, and EKG indicates ST-segment elevations. " + "The patient is currently unstable. Provide a detailed diagnosis, coding, and treatment plan." + ) - steps: - - uses: actions/checkout@v2 - - name: Set up Python - uses: actions/setup-python@v2 - with: - python-version: '3.8' - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install -r requirements.txt - - name: Run tests - run: | - pytest + diagnostic_output = create_medical_swarm(patient_case) + print(diagnostic_output) ``` -This configuration will run the tests on every push and pull request, ensuring that your codebase remains stable. - -## Conclusion - -`pytest` is a powerful and flexible testing framework that makes it easy to write and run tests for your Python code. By following the guidelines and best practices outlined in this blog, you can ensure that your tests are reliable and your codebase is robust. Whether you are testing a single file, multiple files, or the entire repository, `pytest` provides the tools you need to automate and streamline your testing process. +4. Run the script: -Happy testing! +```bash +python medical_swarm.py +``` -------------------------------------------------- -# File: swarms\framework\vision.md - -### Swarms Vision - -**Swarms** is dedicated to transforming enterprise automation by offering a robust and intuitive interface for multi-agent collaboration and seamless integration with multiple models. Our mission is to enable enterprises to enhance their operational efficiency and effectiveness through intelligent automation. - -#### Vision Statement - -**To become the preeminent framework for orchestrating multi-agent collaboration and integration, empowering enterprises to achieve exceptional automation efficiency and operational excellence.** - -#### Core Principles - -1. **Multi-Agent Collaboration**: Facilitate seamless collaboration between diverse agents to solve complex and dynamic problems. -2. **Integration**: Provide robust and flexible integration with various models and frameworks to maximize functionality. -3. **Enterprise Automation**: Deliver enterprise-grade solutions designed for reliability, scalability, and security. -4. **Open Ecosystem**: Promote an open and extensible ecosystem that encourages innovation, community engagement, and collaborative development. - -### Vision Document with Mermaid Graphs - -#### Overview Diagram - -```mermaid -graph TD - A[Swarms Framework] --> B[Multi-Agent Collaboration] - A --> C[Integration with Multiple Models] - A --> D[Enterprise Automation] - A --> E[Open Ecosystem] +# File: swarms\examples\swarms_api_ml_model.md - B --> F[Seamless Communication] - B --> G[Collaboration Protocols] - - C --> H[Model Integration] - C --> I[Framework Compatibility] +# ML Model Code Generation Swarm Example - D --> J[Operational Efficiency] - D --> K[Reliability and Scalability] +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: - E --> L[Encourage Innovation] - E --> M[Community Driven] +```bash +SWARMS_API_KEY= ``` -#### Multi-Agent Collaboration +3. Create a Python script to create and trigger the following swarm: -```mermaid -graph TD - B[Multi-Agent Collaboration] --> F[Seamless Communication] - B --> G[Collaboration Protocols] - F --> N[Cross-Agent Messaging] - F --> O[Task Coordination] - F --> P[Real-Time Updates] +```python +import os +import requests +from dotenv import load_dotenv +import json - G --> Q[Standard APIs] - G --> R[Extensible Protocols] - G --> S[Security and Compliance] +load_dotenv() - N --> T[Agent Messaging Hub] - O --> U[Task Assignment and Monitoring] - P --> V[Instantaneous Data Sync] +# Retrieve API key securely from .env +API_KEY = os.getenv("SWARMS_API_KEY") +BASE_URL = "https://api.swarms.world" - Q --> W[Unified API Interface] - R --> X[Customizable Protocols] - S --> Y[Compliance with Standards] - S --> Z[Secure Communication Channels] -``` +# Headers for secure API communication +headers = {"x-api-key": API_KEY, "Content-Type": "application/json"} -#### Integration with Multiple Models +def create_ml_code_swarm(task_description: str): + """ + Constructs and triggers a swarm of agents for generating a complete machine learning project using PyTorch. + The swarm includes: + - Model Code Generator: Generates the PyTorch model architecture code. + - Training Script Generator: Creates a comprehensive training, validation, and testing script using PyTorch. + - Unit Test Creator: Produces extensive unit tests and helper code, ensuring correctness of the model and training scripts. + Each agent's prompt is highly detailed to output only Python code, with exclusive use of PyTorch. + """ + payload = { + "swarm_name": "Comprehensive PyTorch Code Generation Swarm", + "description": ( + "A production-grade swarm of agents tasked with generating a complete machine learning project exclusively using PyTorch. " + "The swarm is divided into distinct roles: one agent generates the core model architecture code; " + "another creates the training and evaluation scripts including data handling; and a third produces " + "extensive unit tests and helper functions. Each agent's instructions are highly detailed to ensure that the " + "output is strictly Python code with PyTorch as the only deep learning framework." + ), + "agents": [ + { + "agent_name": "Model Code Generator", + "description": "Generates the complete machine learning model architecture code using PyTorch.", + "system_prompt": ( + "You are an expert machine learning engineer with a deep understanding of PyTorch. " + "Your task is to generate production-ready Python code that defines a complete deep learning model architecture exclusively using PyTorch. " + "The code must include all necessary imports, class or function definitions, and should be structured in a modular and scalable manner. " + "Follow PEP8 standards and output only code—no comments, explanations, or extraneous text. " + "Your model definition should include proper layer initialization, activation functions, dropout, and any custom components as required. " + "Ensure that the entire output is strictly Python code based on PyTorch." + ), + "model_name": "openai/gpt-4o", + "role": "worker", + "max_loops": 2, + "max_tokens": 4000, + "temperature": 0.3, + "auto_generate_prompt": False + }, + { + "agent_name": "Training Script Generator", + "description": "Creates a comprehensive training, validation, and testing script using PyTorch.", + "system_prompt": ( + "You are a highly skilled software engineer specializing in machine learning pipeline development with PyTorch. " + "Your task is to generate Python code that builds a complete training pipeline using PyTorch. " + "The script must include robust data loading, preprocessing, augmentation, and a complete training loop, along with validation and testing procedures. " + "All necessary imports should be included and the code should assume that the model code from the previous agent is available via proper module imports. " + "Follow best practices for reproducibility and modularity, and output only code without any commentary or non-code text. " + "The entire output must be strictly Python code that uses PyTorch for all deep learning operations." + ), + "model_name": "openai/gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 3000, + "temperature": 0.3, + "auto_generate_prompt": False + }, + { + "agent_name": "Unit Test Creator", + "description": "Develops a suite of unit tests and helper functions for verifying the PyTorch model and training pipeline.", + "system_prompt": ( + "You are an experienced software testing expert with extensive experience in writing unit tests for machine learning projects in PyTorch. " + "Your task is to generate Python code that consists solely of unit tests and any helper functions required to validate both the PyTorch model and the training pipeline. " + "Utilize testing frameworks such as pytest or unittest. The tests should cover key functionalities such as model instantiation, forward pass correctness, " + "training loop execution, data preprocessing verification, and error handling. " + "Ensure that your output is only Python code, without any additional text or commentary, and that it is ready to be integrated into a CI/CD pipeline. " + "The entire output must exclusively use PyTorch as the deep learning framework." + ), + "model_name": "openai/gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 3000, + "temperature": 0.3, + "auto_generate_prompt": False + } + ], + "max_loops": 3, + "swarm_type": "SequentialWorkflow" # Sequential workflow: later agents can assume outputs from earlier ones + } -```mermaid -graph TD - C[Integration with Multiple Models] --> H[Model Integration] - C --> I[Framework Compatibility] + # The task description provides the high-level business requirement for the swarm. + payload = { + "task": task_description, + "swarm": payload + } - H --> R[Plug-and-Play Models] - H --> S[Model Orchestration] - H --> T[Model Versioning] + response = requests.post( + f"{BASE_URL}/swarm/completion", + headers=headers, + json=payload, + ) - I --> U[Support for OpenAI] - I --> V[Support for Anthropic] - I --> W[Support for Gemini] - I --> X[Support for LangChain] - I --> Y[Support for AutoGen] - I --> Z[Support for Custom Models] + if response.status_code == 200: + print("PyTorch Code Generation Swarm successfully executed!") + return json.dumps(response.json(), indent=4) + else: + print(f"Error {response.status_code}: {response.text}") + return None - R --> AA[Easy Model Integration] - S --> AB[Dynamic Model Orchestration] - T --> AC[Version Control] +# Example business task for the swarm: generating a full-stack machine learning pipeline for image classification using PyTorch. +if __name__ == "__main__": + task_description = ( + "Develop a full-stack machine learning pipeline for image classification using PyTorch. " + "The project must include a deep learning model using a CNN architecture for image recognition, " + "a comprehensive training script for data preprocessing, augmentation, training, validation, and testing, " + "and an extensive suite of unit tests to validate every component. " + "Each component's output must be strictly Python code with no additional text or commentary, using PyTorch exclusively." + ) + + output = create_ml_code_swarm(task_description) + print(output) - U --> AD[Integration with OpenAI Models] - V --> AE[Integration with Anthropic Models] - W --> AF[Integration with Gemini Models] - X --> AG[Integration with LangChain Models] - Y --> AH[Integration with AutoGen Models] - Z --> AI[Support for Proprietary Models] ``` -#### Enterprise Automation +-------------------------------------------------- -```mermaid -graph TD - D[Enterprise Automation] --> J[Operational Efficiency] - D --> K[Reliability and Scalability] +# File: swarms\examples\swarms_dao.md - J --> Y[Automate Workflows] - J --> Z[Reduce Manual Work] - J --> AA[Increase Productivity] +# Swarms DAO Example - K --> AB[High Uptime] - K --> AC[Enterprise-Grade Security] - K --> AD[Scalable Solutions] +This example demonstrates how to create a swarm of agents to collaborate on a task. The agents are designed to work together to create a comprehensive strategy for a DAO focused on decentralized governance for climate action. - Y --> AE[Workflow Automation Tools] - Z --> AF[Eliminate Redundant Tasks] - AA --> AG[Boost Employee Efficiency] +You can customize the agents and their system prompts to fit your specific needs. - AB --> AH[Robust Infrastructure] - AC --> AI[Security Compliance] - AD --> AJ[Scale with Demand] -``` +And, this example is using the `deepseek-reasoner` model, which is a large language model that is optimized for reasoning tasks. -#### Open Ecosystem -```mermaid -graph TD - E[Open Ecosystem] --> L[Encourage Innovation] - E --> M[Community Driven] +## Todo +- Add tools to check wallet of the treasury and check the balance of the treasury +- Add tools to check the price of the token +- Add tools to check the price of the token on different exchanges +- Add tools to check the price of the token on different chains +- Add tools to check twitter posts and check the sentiment of the posts - L --> AC[Open Source Contributions] - L --> AD[Hackathons and Workshops] - L --> AE[Research and Development] +```python +import random +from swarms import Agent - M --> AF[Active Community Support] - M --> AG[Collaborative Development] - M --> AH[Shared Resources] +# System prompts for each agent +MARKETING_AGENT_SYS_PROMPT = """ +You are the Marketing Strategist Agent for a DAO. Your role is to develop, implement, and optimize all marketing and branding strategies to align with the DAO's mission and vision. The DAO is focused on decentralized governance for climate action, funding projects aimed at reducing carbon emissions, and incentivizing community participation through its native token. - AC --> AI[Community Contributions] - AD --> AJ[Innovative Events] - AE --> AK[Continuous R&D] +### Objectives: +1. **Brand Awareness**: Build a globally recognized and trusted brand for the DAO. +2. **Community Growth**: Expand the DAO's community by onboarding individuals passionate about climate action and blockchain technology. +3. **Campaign Execution**: Launch high-impact marketing campaigns on platforms like Twitter, Discord, and YouTube to engage and retain community members. +4. **Partnerships**: Identify and build partnerships with like-minded organizations, NGOs, and influencers. +5. **Content Strategy**: Design educational and engaging content, including infographics, blog posts, videos, and AMAs. - AF --> AL[Supportive Community] - AG --> AM[Joint Development Projects] - AH --> AN[Shared Knowledge Base] -``` +### Instructions: +- Thoroughly analyze the product description and DAO mission. +- Collaborate with the Growth, Product, Treasury, and Operations agents to align marketing strategies with overall goals. +- Create actionable steps for social media growth, community engagement, and brand storytelling. +- Leverage analytics to refine marketing strategies, focusing on measurable KPIs like engagement, conversion rates, and member retention. +- Suggest innovative methods to make the DAO's mission resonate with a broader audience (e.g., gamified incentives, contests, or viral campaigns). +- Ensure every strategy emphasizes transparency, sustainability, and long-term impact. +""" ---- +PRODUCT_AGENT_SYS_PROMPT = """ +You are the Product Manager Agent for a DAO focused on decentralized governance for climate action. Your role is to design, manage, and optimize the DAO's product roadmap. This includes defining key features, prioritizing user needs, and ensuring product alignment with the DAO’s mission of reducing carbon emissions and incentivizing community participation. -### Conclusion +### Objectives: +1. **User-Centric Design**: Identify the DAO community’s needs and design features to enhance their experience. +2. **Roadmap Prioritization**: Develop a prioritized product roadmap based on community feedback and alignment with climate action goals. +3. **Integration**: Suggest technical solutions and tools for seamless integration with other platforms and blockchains. +4. **Continuous Improvement**: Regularly evaluate product features and recommend optimizations to improve usability, engagement, and adoption. -Swarms excels in enabling seamless communication and coordination between multiple agents, fostering a collaborative environment where agents can work together to solve complex tasks. Our platform supports cross-agent messaging, task coordination, and real-time updates, ensuring that all agents are synchronized and can efficiently contribute to the collective goal. +### Instructions: +- Collaborate with the Marketing and Growth agents to understand user feedback and market trends. +- Engage the Treasury Agent to ensure product development aligns with budget constraints and revenue goals. +- Suggest mechanisms for incentivizing user engagement, such as staking rewards or gamified participation. +- Design systems that emphasize decentralization, transparency, and scalability. +- Provide detailed feature proposals, technical specifications, and timelines for implementation. +- Ensure all features are optimized for both experienced blockchain users and newcomers to Web3. +""" -Swarms provides robust integration capabilities with a wide array of models, including OpenAI, Anthropic, Gemini, LangChain, AutoGen, and custom models. This ensures that enterprises can leverage the best models available to meet their specific needs, while also allowing for dynamic model orchestration and version control to keep operations up-to-date and effective. +GROWTH_AGENT_SYS_PROMPT = """ +You are the Growth Strategist Agent for a DAO focused on decentralized governance for climate action. Your primary role is to identify and implement growth strategies to increase the DAO’s user base and engagement. -Our framework is designed to enhance operational efficiency through automation. By automating workflows, reducing manual work, and increasing productivity, Swarms helps enterprises achieve higher efficiency and operational excellence. Our solutions are built for high uptime, enterprise-grade security, and scalability, ensuring reliable and secure operations. +### Objectives: +1. **User Acquisition**: Identify effective strategies to onboard more users to the DAO. +2. **Retention**: Suggest ways to improve community engagement and retain active members. +3. **Data-Driven Insights**: Leverage data analytics to identify growth opportunities and areas of improvement. +4. **Collaborative Growth**: Work with other agents to align growth efforts with marketing, product development, and treasury goals. -Swarms promotes an open and extensible ecosystem, encouraging community-driven innovation and development. We support open-source contributions, organize hackathons and workshops, and continuously invest in research and development. Our active community fosters collaborative development, shared resources, and a supportive environment for innovation. +### Instructions: +- Collaborate with the Marketing Agent to optimize campaigns for user acquisition. +- Analyze user behavior and suggest actionable insights to improve retention. +- Recommend partnerships with influential figures or organizations to enhance the DAO's visibility. +- Propose growth experiments (A/B testing, new incentives, etc.) and analyze their effectiveness. +- Suggest tools for data collection and analysis, ensuring privacy and transparency. +- Ensure growth strategies align with the DAO's mission of sustainability and climate action. +""" -**Swarms** is dedicated to providing a comprehensive and powerful framework for enterprises seeking to automate operations through multi-agent collaboration and integration with various models. Our commitment to an open ecosystem, enterprise-grade automation solutions, and seamless multi-agent collaboration ensures that Swarms remains the leading choice for enterprises aiming to achieve operational excellence through intelligent automation. +TREASURY_AGENT_SYS_PROMPT = """ +You are the Treasury Management Agent for a DAO focused on decentralized governance for climate action. Your role is to oversee the DAO's financial operations, including budgeting, funding allocation, and financial reporting. --------------------------------------------------- +### Objectives: +1. **Financial Transparency**: Maintain clear and detailed reports of the DAO's financial status. +2. **Budget Management**: Allocate funds strategically to align with the DAO's goals and priorities. +3. **Fundraising**: Identify and recommend strategies for fundraising to ensure the DAO's financial sustainability. +4. **Cost Optimization**: Suggest ways to reduce operational costs without sacrificing quality. -# File: swarms\glossary.md +### Instructions: +- Collaborate with all other agents to align funding with the DAO's mission and strategic goals. +- Propose innovative fundraising campaigns (e.g., NFT drops, token sales) to generate revenue. +- Analyze financial risks and suggest mitigation strategies. +- Ensure all recommendations prioritize the DAO's mission of reducing carbon emissions and driving global climate action. +- Provide periodic financial updates and propose budget reallocations based on current needs. +""" -# Glossary of Terms +OPERATIONS_AGENT_SYS_PROMPT = """ +You are the Operations Coordinator Agent for a DAO focused on decentralized governance for climate action. Your role is to ensure smooth day-to-day operations, coordinate workflows, and manage governance processes. -**Agent**: -An LLM (Large Language Model) equipped with tools and memory, operating with a specific objective in a loop. An agent can perform tasks, interact with other agents, and utilize external tools and memory systems to achieve its goals. +### Objectives: +1. **Workflow Optimization**: Streamline operational processes to maximize efficiency and effectiveness. +2. **Task Coordination**: Manage and delegate tasks to ensure timely delivery of goals. +3. **Governance**: Oversee governance processes, including proposal management and voting mechanisms. +4. **Communication**: Ensure seamless communication between all agents and community members. -**Swarms**: -A group of more than two agents working together and communicating to accomplish a shared objective. Swarms enable complex, collaborative tasks that leverage the strengths of multiple agents. +### Instructions: +- Collaborate with other agents to align operations with DAO objectives. +- Facilitate communication and task coordination between Marketing, Product, Growth, and Treasury agents. +- Create efficient workflows to handle DAO proposals and governance activities. +- Suggest tools or platforms to improve operational efficiency. +- Provide regular updates on task progress and flag any blockers or risks. +""" -**Tool**: -A Python function that is converted into a function call, allowing agents to perform specific actions or access external resources. Tools enhance the capabilities of agents by providing specialized functionalities. +# Initialize agents +marketing_agent = Agent( + agent_name="Marketing-Agent", + system_prompt=MARKETING_AGENT_SYS_PROMPT, + model_name="deepseek/deepseek-reasoner", + autosave=True, + dashboard=False, + verbose=True, +) -**Memory System**: -A system for managing information retrieval and storage, often implemented as a Retrieval-Augmented Generation (RAG) system or a memory vector database. Memory systems enable agents to recall previous interactions, store new information, and improve decision-making based on historical data. +product_agent = Agent( + agent_name="Product-Agent", + system_prompt=PRODUCT_AGENT_SYS_PROMPT, + model_name="deepseek/deepseek-reasoner", + autosave=True, + dashboard=False, + verbose=True, +) -**LLM (Large Language Model)**: -A type of AI model designed to understand and generate human-like text. LLMs, such as GPT-3 or GPT-4, are used as the core computational engine for agents. +growth_agent = Agent( + agent_name="Growth-Agent", + system_prompt=GROWTH_AGENT_SYS_PROMPT, + model_name="deepseek/deepseek-reasoner", + autosave=True, + dashboard=False, + verbose=True, +) -**System Prompt**: -A predefined prompt that sets the context and instructions for an agent's task. The system prompt guides the agent's behavior and response generation. +treasury_agent = Agent( + agent_name="Treasury-Agent", + system_prompt=TREASURY_AGENT_SYS_PROMPT, + model_name="deepseek/deepseek-reasoner", + autosave=True, + dashboard=False, + verbose=True, +) -**Max Loops**: -The maximum number of iterations an agent will perform to complete its task. This parameter helps control the extent of an agent's processing and ensures tasks are completed efficiently. +operations_agent = Agent( + agent_name="Operations-Agent", + system_prompt=OPERATIONS_AGENT_SYS_PROMPT, + model_name="deepseek/deepseek-reasoner", + autosave=True, + dashboard=False, + verbose=True, +) -**Dashboard**: -A user interface that provides real-time monitoring and control over the agents and their activities. Dashboards can display agent status, logs, and performance metrics. +agents = [marketing_agent, product_agent, growth_agent, treasury_agent, operations_agent] -**Streaming On**: -A setting that enables agents to stream their output incrementally, providing real-time feedback as they process tasks. This feature is useful for monitoring progress and making adjustments on the fly. -**Verbose**: -A setting that controls the level of detail in an agent's output and logging. When verbose mode is enabled, the agent provides more detailed information about its operations and decisions. +class DAOSwarmRunner: + """ + A class to manage and run a swarm of agents in a discussion. + """ -**Multi-modal**: -The capability of an agent to process and integrate multiple types of data, such as text, images, and audio. Multi-modal agents can handle more complex tasks that require diverse inputs. + def __init__(self, agents: list, max_loops: int = 5, shared_context: str = "") -> None: + """ + Initializes the DAO Swarm Runner. -**Autosave**: -A feature that automatically saves the agent's state and progress at regular intervals. Autosave helps prevent data loss and allows for recovery in case of interruptions. + Args: + agents (list): A list of agents in the swarm. + max_loops (int, optional): The maximum number of discussion loops between agents. Defaults to 5. + shared_context (str, optional): The shared context for all agents to base their discussion on. Defaults to an empty string. + """ + self.agents = agents + self.max_loops = max_loops + self.shared_context = shared_context + self.discussion_history = [] -**Flow**: -The predefined sequence in which agents in a swarm interact and process tasks. The flow ensures that each agent's output is appropriately passed to the next agent, facilitating coordinated efforts. + def run(self, task: str) -> str: + """ + Runs the swarm in a random discussion. -**Long Term Memory**: -A component of the memory system that retains information over extended periods, enabling agents to recall and utilize past interactions and experiences. + Args: + task (str): The task or context that agents will discuss. -**Output Schema**: -A structured format for the output generated by agents, often defined using data models like Pydantic's BaseModel. Output schemas ensure consistency and clarity in the information produced by agents. + Returns: + str: The final discussion output after all loops. + """ + print(f"Task: {task}") + print("Initializing Random Discussion...") + + # Initialize the discussion with the shared context + current_message = f"Task: {task}\nContext: {self.shared_context}" + self.discussion_history.append(current_message) -By understanding these terms, you can effectively build and orchestrate agents and swarms, leveraging their capabilities to perform complex, collaborative tasks. + # Run the agents in a randomized discussion + for loop in range(self.max_loops): + print(f"\n--- Loop {loop + 1}/{self.max_loops} ---") + # Choose a random agent + agent = random.choice(self.agents) + print(f"Agent {agent.agent_name} is responding...") --------------------------------------------------- + # Run the agent and get a response + response = agent.run(current_message) + print(f"Agent {agent.agent_name} says:\n{response}\n") -# File: swarms\install\docker_setup.md + # Append the response to the discussion history + self.discussion_history.append(f"{agent.agent_name}: {response}") -# Docker Setup Guide for Contributors to Swarms + # Update the current message for the next agent + current_message = response + print("\n--- Discussion Complete ---") + return "\n".join(self.discussion_history) -Welcome to the `swarms` project Docker setup guide. This document will help you establish a Docker-based environment for contributing to `swarms`. Docker provides a consistent and isolated environment, ensuring that all contributors can work in the same settings, reducing the "it works on my machine" syndrome. -### Purpose +swarm = DAOSwarmRunner(agents=agents, max_loops=1, shared_context="") -The purpose of this guide is to: +# User input for product description +product_description = """ +The DAO is focused on decentralized governance for climate action. +It funds projects aimed at reducing carbon emissions and incentivizes community participation with a native token. +""" -- Ensure contributors can quickly set up their development environment. -- Provide a consistent testing and deployment workflow. -- Introduce Docker basics and best practices. +# Assign a shared context for all agents +swarm.shared_context = product_description -### Scope +# Run the swarm +task = """ +Analyze the product description and create a collaborative strategy for marketing, product, growth, treasury, and operations. Ensure all recommendations align with the DAO's mission of reducing carbon emissions. +""" +output = swarm.run(task) -This guide covers: +# Print the swarm output +print("Collaborative Strategy Output:\n", output) -- Installing Docker -- Cloning the `swarms` repository -- Building a Docker image -- Running the `swarms` application in a Docker container -- Running tests using Docker -- Pushing changes and working with Docker Hub +``` +-------------------------------------------------- -## Docker Installation +# File: swarms\examples\swarms_of_browser_agents.md -### Windows +# Swarms x Browser Use -1. Download Docker Desktop for Windows from the official website. -2. Install Docker Desktop, ensuring that the "Use Windows containers instead of Linux containers" option is unchecked. -3. Start Docker Desktop and wait for the Docker engine to start. +- Import required modules -### macOS +- Configure your agent first by making a new class -1. Download Docker Desktop for macOS from the official website. -2. Follow the installation instructions, drag-and-drop Docker into the Applications folder. -3. Start Docker Desktop from the Applications folder. +- Set your api keys for your model provider in the `.env` file such as `OPENAI_API_KEY="sk-"` -### Linux (Ubuntu) +- Conigure your `ConcurrentWorkflow` -1. Update your package index: `sudo apt-get update`. -2. Install packages to allow apt to use a repository over HTTPS. -3. Add Docker’s official GPG key. -4. Set up the stable repository. -5. Install the latest version of Docker Engine and containerd. +## Install ```bash -sudo apt-get install docker-ce docker-ce-cli containerd.io +pip install swarms browser-use langchain-openai ``` +-------- -6. Verify that Docker Engine is installed correctly by running the hello-world image. -```bash -sudo docker run hello-world -``` +## Main +```python +import asyncio -### Post-installation Steps for Linux +from browser_use import Agent +from dotenv import load_dotenv +from langchain_openai import ChatOpenAI -- Manage Docker as a non-root user. -- Configure Docker to start on boot. +from swarms import ConcurrentWorkflow -## Cloning the Repository +load_dotenv() -```bash -git clone https://github.com/your-username/swarms.git -cd swarms -``` -## Docker Basics +class BrowserAgent: + def __init__(self, agent_name: str = "BrowserAgent"): + self.agent_name = agent_name -### Dockerfile Overview + async def browser_agent_test(self, task: str): + agent = Agent( + task=task, + llm=ChatOpenAI(model="gpt-4o"), + ) + result = await agent.run() + return result -- Explain the structure and commands of a Dockerfile used in the `swarms` project. + def run(self, task: str): + return asyncio.run(self.browser_agent_test(task)) -### Building the Image -```bash -docker build -t swarms-dev . -``` +swarm = ConcurrentWorkflow( + agents=[BrowserAgent() for _ in range(3)], +) -### Running a Container +swarm.run( + """ + Go to pump.fun. + + 2. Make an account: use email: "test@test.com" and password: "test1234" + + 3. Make a coin called and give it a cool description and etc. Fill in the form + + 4. Sit back and watch the coin grow in value. + + """ +) -```bash -docker run -it --rm swarms-dev ``` -## Development Workflow with Docker - -### Running the Application - -- Commands to run the `swarms` application within Docker. - -### Making Changes +-------------------------------------------------- -- How to make changes to the code and reflect those changes within the Docker container. +# File: swarms\examples\swarms_tools_htx.md -### Running Tests +# Swarms Tools Example with HTX + CoinGecko -- Instructions on running tests using `pytest` within the Docker environment. +- `pip3 install swarms swarms-tools` +- Add `OPENAI_API_KEY` to your `.env` file -## Docker Compose for Local Development +```python +from swarms import Agent +from swarms.prompts.finance_agent_sys_prompt import ( + FINANCIAL_AGENT_SYS_PROMPT, +) +from swarms_tools import ( + coin_gecko_coin_api, + fetch_htx_data, +) -- Introduce Docker Compose and its role in simplifying multi-container setups. -- Create a `docker-compose.yml` file for the `swarms` project. +# Initialize the agent +agent = Agent( + agent_name="Financial-Analysis-Agent", + agent_description="Personal finance advisor agent", + system_prompt=FINANCIAL_AGENT_SYS_PROMPT, + max_loops=1, + model_name="gpt-4o", + dynamic_temperature_enabled=True, + user_name="swarms_corp", + return_step_meta=False, + output_type="str", # "json", "dict", "csv" OR "string" "yaml" and + auto_generate_prompt=False, # Auto generate prompt for the agent based on name, description, and system prompt, task + max_tokens=4000, # max output tokens + saved_state_path="agent_00.json", + interactive=False, +) -## Dockerfile +agent.run( + f"Analyze the $swarms token on HTX with data: {fetch_htx_data('swarms')}. Additionally, consider the following CoinGecko data: {coin_gecko_coin_api('swarms')}" +) +``` -Creating a Dockerfile for deploying the `swarms` framework to the cloud involves setting up the necessary environment to run your Python application, ensuring all dependencies are installed, and configuring the container to execute the desired tasks. Here's an example Dockerfile that sets up such an environment: +-------------------------------------------------- -```Dockerfile -# Use an official Python runtime as a parent image -FROM python:3.11-slim +# File: swarms\examples\swarms_tools_htx_gecko.md -# Set environment variables -ENV PYTHONDONTWRITEBYTECODE 1 -ENV PYTHONUNBUFFERED 1 +# Swarms Tools Example with HTX + CoinGecko -# Set the working directory in the container -WORKDIR /usr/src/swarm_cloud +- `pip3 install swarms swarms-tools` +- Add `OPENAI_API_KEY` to your `.env` file +- Run `swarms_tools_htx_gecko.py` +- Agent will make a function call to the desired tool +- The tool will be executed and the result will be returned to the agent +- The agent will then analyze the result and return the final output -# Install system dependencies -RUN apt-get update \ - && apt-get -y install gcc \ - && apt-get clean -# Install Python dependencies -# COPY requirements.txt and pyproject.toml if you're using poetry for dependency management -COPY requirements.txt . -RUN pip install --upgrade pip -RUN pip install --no-cache-dir -r requirements.txt +```python +from swarms import Agent +from swarms.prompts.finance_agent_sys_prompt import ( + FINANCIAL_AGENT_SYS_PROMPT, +) +from swarms_tools import ( + fetch_stock_news, + coin_gecko_coin_api, + fetch_htx_data, +) -# Install the 'swarms' package, assuming it's available on PyPI -ENV SWARM_API_KEY=your_swarm_api_key_here -ENV OPENAI_API_KEY=your_openai_key -RUN pip install swarms +# Initialize the agent +agent = Agent( + agent_name="Financial-Analysis-Agent", + agent_description="Personal finance advisor agent", + system_prompt=FINANCIAL_AGENT_SYS_PROMPT, + max_loops=1, + model_name="gpt-4o", + dynamic_temperature_enabled=True, + user_name="swarms_corp", + retry_attempts=3, + context_length=8192, + return_step_meta=False, + output_type="str", # "json", "dict", "csv" OR "string" "yaml" and + auto_generate_prompt=False, # Auto generate prompt for the agent based on name, description, and system prompt, task + max_tokens=4000, # max output tokens + saved_state_path="agent_00.json", + interactive=False, + tools=[fetch_stock_news, coin_gecko_coin_api, fetch_htx_data], +) -# Copy the rest of the application -COPY . . +agent.run("Analyze the $swarms token on htx") +``` -# Add entrypoint script if needed -# COPY ./entrypoint.sh . -# RUN chmod +x /usr/src/swarm_cloud/entrypoint.sh +-------------------------------------------------- -# Expose port if your application has a web interface -# EXPOSE 5000 +# File: swarms\examples\templates_index.md -# Define environment variable for the swarm to work -# Add Docker CMD or ENTRYPOINT script to run the application -# CMD python your_swarm_startup_script.py -# Or use the entrypoint script if you have one -# ENTRYPOINT ["/usr/src/swarm_cloud/entrypoint.sh"] +# The Swarms Index -# If you're using `CMD` to execute a Python script, make sure it's executable -# RUN chmod +x your_swarm_startup_script.py -``` +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. -To build and run this Docker image: +| 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) | -1. Replace `requirements.txt` with your actual requirements file or `pyproject.toml` and `poetry.lock` if you're using Poetry. -2. Replace `your_swarm_startup_script.py` with the script that starts your application. -3. If your application requires an API key or other sensitive data, make sure to set these securely, perhaps using environment variables or secrets management solutions provided by your cloud provider. -4. If you have an entrypoint script, uncomment the `COPY` and `RUN` lines for `entrypoint.sh`. -5. If your application has a web interface, uncomment the `EXPOSE` line and set it to the correct port. -Now, build your Docker image: -```sh -docker build -t swarm-cloud . -``` -And run it: +-------------------------------------------------- -```sh -docker run -d --name my-swarm-app swarm-cloud -``` +# File: swarms\examples\unique_swarms.md -For deploying to the cloud, you'll need to push your Docker image to a container registry (like Docker Hub or a private registry), then pull it from your cloud environment to run it. Cloud providers often have services specifically for this purpose (like AWS ECS, GCP GKE, or Azure AKS). The deployment process will involve: -- Pushing the image to a registry. -- Configuring cloud services to run your image. -- Setting up networking, storage, and other cloud resources. -- Monitoring, logging, and potentially scaling your containers. +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. -Remember to secure sensitive data, use tagged releases for your images, and follow best practices for operating in the cloud. +# Documentation +## Table of Contents +1. [Common Parameters](#common-parameters) +2. [Basic Swarm Patterns](#basic-swarm-patterns) +3. [Mathematical Swarm Patterns](#mathematical-swarm-patterns) +4. [Advanced Swarm Patterns](#advanced-swarm-patterns) +5. [Communication Patterns](#communication-patterns) +6. [Best Practices](#best-practices) +7. [Common Use Cases](#common-use-cases) --------------------------------------------------- +## Common Parameters -# File: swarms\install\env.md +All swarm architectures accept these base parameters: -# Environment Variables +- `agents: AgentListType` - List of Agent objects to participate in the swarm +- `tasks: List[str]` - List of tasks to be processed by the agents +- `return_full_history: bool` (optional) - If True, returns conversation history. Defaults to True -## Overview +Return types are generally `Union[dict, List[str]]`, where: +- If `return_full_history=True`: Returns a dictionary containing the full conversation history +- If `return_full_history=False`: Returns a list of agent responses -Swarms uses environment variables for configuration management and secure credential storage. This approach keeps sensitive information like API keys out of your code and allows for easy configuration changes across different environments. +## Basic Swarm Patterns -## Core Environment Variables +### Circular Swarm +```python +def circular_swarm(agents: AgentListType, tasks: List[str], return_full_history: bool = True) +``` -### Framework Configuration +**Information Flow:** +```mermaid +flowchart LR + subgraph Circular Flow + A1((Agent 1)) --> A2((Agent 2)) + A2 --> A3((Agent 3)) + A3 --> A4((Agent 4)) + A4 --> A1 + end + Task1[Task 1] --> A1 + Task2[Task 2] --> A2 + Task3[Task 3] --> A3 +``` -=== "Configuration Variables" +**Best Used When:** - | Variable | Description | Example | - |----------|-------------|---------| - | `SWARMS_VERBOSE_GLOBAL` | Controls global logging verbosity | `True` or `False` | - | `WORKSPACE_DIR` | Defines the workspace directory for agent operations | `agent_workspace` | +- You need continuous processing of tasks -### LLM Provider API Keys +- Tasks need to be processed by every agent in sequence -=== "OpenAI" - ```bash - OPENAI_API_KEY="your-openai-key" - ``` +- You want predictable, ordered task distribution -=== "Anthropic" - ```bash - ANTHROPIC_API_KEY="your-anthropic-key" - ``` +**Key Features:** -=== "Groq" - ```bash - GROQ_API_KEY="your-groq-key" - ``` +- Tasks move in a circular pattern through all agents -=== "Google" - ```bash - GEMINI_API_KEY="your-gemini-key" - ``` +- Each agent processes each task once -=== "Hugging Face" - ```bash - HUGGINGFACE_TOKEN="your-huggingface-token" - ``` +- Maintains strict ordering of task processing -=== "Perplexity AI" - ```bash - PPLX_API_KEY="your-perplexity-key" - ``` +### Linear Swarm +```python +def linear_swarm(agents: AgentListType, tasks: List[str], return_full_history: bool = True) +``` -=== "AI21" - ```bash - AI21_API_KEY="your-ai21-key" - ``` +**Information Flow:** +```mermaid +flowchart LR + Input[Task Input] --> A1 + subgraph Sequential Processing + A1((Agent 1)) --> A2((Agent 2)) + A2 --> A3((Agent 3)) + A3 --> A4((Agent 4)) + A4 --> A5((Agent 5)) + end + A5 --> Output[Final Result] +``` -=== "Cohere" - ```bash - COHERE_API_KEY="your-cohere-key" - ``` +**Best Used When:** -=== "Mistral AI" - ```bash - MISTRAL_API_KEY="your-mistral-key" - ``` +- Tasks need sequential, pipeline-style processing -=== "Together AI" - ```bash - TOGETHER_API_KEY="your-together-key" - ``` +- Each agent performs a specific transformation step -### Tool Provider Keys +- Order of processing is critical -=== "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" - ``` +### Star Swarm +```python +def star_swarm(agents: AgentListType, tasks: List[str], return_full_history: bool = True) +``` -=== "Analytics & Monitoring" - ```bash - EXA_API_KEY="your-exa-key" - ``` +**Information Flow:** +```mermaid +flowchart TD + subgraph Star Pattern + A1((Central Agent)) + A2((Agent 2)) + A3((Agent 3)) + A4((Agent 4)) + A5((Agent 5)) + A1 --> A2 + A1 --> A3 + A1 --> A4 + A1 --> A5 + end + Task[Initial Task] --> A1 + A2 --> Result2[Result 2] + A3 --> Result3[Result 3] + A4 --> Result4[Result 4] + A5 --> Result5[Result 5] +``` -=== "Browser Automation" - ```bash - MULTION_API_KEY="your-multion-key" - ``` +**Best Used When:** -## Security Best Practices +- You need centralized control -### Environment File Management +- Tasks require coordination or oversight -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 - ``` +- You want to maintain a single point of task distribution -### API Key Security +### Mesh Swarm +```python +def mesh_swarm(agents: AgentListType, tasks: List[str], return_full_history: bool = True) +``` -!!! 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 +**Information Flow:** +```mermaid +flowchart TD + subgraph Mesh Network + A1((Agent 1)) <--> A2((Agent 2)) + A2 <--> A3((Agent 3)) + A1 <--> A4((Agent 4)) + A2 <--> A5((Agent 5)) + A3 <--> A6((Agent 6)) + A4 <--> A5 + A5 <--> A6 + end + Tasks[Task Pool] --> A1 + Tasks --> A2 + Tasks --> A3 + Tasks --> A4 + Tasks --> A5 + Tasks --> A6 +``` -### Template Configuration +**Best Used When:** -Create a `.env.example` template without actual values: +- You need maximum flexibility -```bash -# Required Configuration -OPENAI_API_KEY="" -ANTHROPIC_API_KEY="" -GROQ_API_KEY="" -WORKSPACE_DIR="agent_workspace" +- Task processing order isn't critical -# Optional Configuration -SWARMS_VERBOSE_GLOBAL="False" -``` +- You want fault tolerance -### Loading Environment Variables +## Mathematical Swarm Patterns +### Fibonacci Swarm ```python -from dotenv import load_dotenv -import os - -# Load environment variables -load_dotenv() +def fibonacci_swarm(agents: AgentListType, tasks: List[str]) +``` -# Access variables -workspace_dir = os.getenv("WORKSPACE_DIR") -openai_key = os.getenv("OPENAI_API_KEY") +**Information Flow:** +```mermaid +flowchart TD + subgraph Fibonacci Pattern + L1[Level 1: 1 Agent] --> L2[Level 2: 1 Agent] + L2 --> L3[Level 3: 2 Agents] + L3 --> L4[Level 4: 3 Agents] + L4 --> L5[Level 5: 5 Agents] + end + Task[Initial Task] --> L1 + L5 --> Results[Processed Results] ``` -## Environment Setup Guide +**Best Used When:** -=== "1. Install Dependencies" - ```bash - pip install python-dotenv - ``` +- You need natural scaling patterns -=== "2. Create Environment File" - ```bash - cp .env.example .env - ``` +- Tasks have increasing complexity -=== "3. Configure Variables" - - Open `.env` in your text editor - - Add your API keys and configuration - - Save the file +- You want organic growth in processing capacity -=== "4. Verify Setup" - ```python - import os - from dotenv import load_dotenv +### Pyramid Swarm +```python +def pyramid_swarm(agents: AgentListType, tasks: List[str], return_full_history: bool = True) +``` - load_dotenv() - assert os.getenv("OPENAI_API_KEY") is not None, "OpenAI API key not found" - ``` +**Information Flow:** +```mermaid +flowchart TD + subgraph Pyramid Structure + A1((Leader Agent)) + A2((Manager 1)) + A3((Manager 2)) + A4((Worker 1)) + A5((Worker 2)) + A6((Worker 3)) + A7((Worker 4)) + A1 --> A2 + A1 --> A3 + A2 --> A4 + A2 --> A5 + A3 --> A6 + A3 --> A7 + end + Task[Complex Task] --> A1 + A4 --> Result1[Output 1] + A5 --> Result2[Output 2] + A6 --> Result3[Output 3] + A7 --> Result4[Output 4] +``` -## Environment-Specific Configuration +**Best Used When:** -=== "Development" - ```bash - WORKSPACE_DIR="agent_workspace" - SWARMS_VERBOSE_GLOBAL="True" - ``` +- You need hierarchical task processing -=== "Production" - ```bash - WORKSPACE_DIR="/var/swarms/workspace" - SWARMS_VERBOSE_GLOBAL="False" - ``` +- Tasks require multiple levels of oversight -=== "Testing" - ```bash - WORKSPACE_DIR="test_workspace" - SWARMS_VERBOSE_GLOBAL="True" - ``` +- You want organized task delegation -## Troubleshooting +### Grid Swarm +```python +def grid_swarm(agents: AgentListType, tasks: List[str]) +``` -### Common Issues +**Information Flow:** +```mermaid +flowchart TD + subgraph Grid Layout + A1((1)) <--> A2((2)) <--> A3((3)) + A4((4)) <--> A5((5)) <--> A6((6)) + A7((7)) <--> A8((8)) <--> A9((9)) + A1 <--> A4 <--> A7 + A2 <--> A5 <--> A8 + A3 <--> A6 <--> A9 + end + Tasks[Task Queue] --> A1 + Tasks --> A5 + Tasks --> A9 +``` -???+ note "Environment Variables Not Loading" - - Verify `.env` file exists in project root - - Confirm `load_dotenv()` is called before accessing variables - - Check file permissions +**Best Used When:** -???+ note "API Key Issues" - - Verify key format is correct - - Ensure key has not expired - - Check for leading/trailing whitespace +- Tasks have spatial relationships -???+ note "Workspace Directory Problems" - - Confirm directory exists - - Verify write permissions - - Check path is absolute when required +- You need neighbor-based processing +- You want structured parallel processing --------------------------------------------------- +## Communication Patterns -# File: swarms\install\install.md +### One-to-One Communication +```python +def one_to_one(sender: Agent, receiver: Agent, task: str, max_loops: int = 1) -> str +``` -# Swarms Installation Guide +**Information Flow:** +```mermaid +flowchart LR + Task[Task] --> S((Sender)) + S --> R((Receiver)) + R --> Result[Result] +``` -
-

- - - -

-
+**Best Used When:** -You can install `swarms` with pip in a -[**Python>=3.10**](https://www.python.org/) environment. +- Direct agent communication is needed -## Prerequisites +- Tasks require back-and-forth interaction -Before you begin, ensure you have the following installed: +- You need controlled message exchange -- Python 3.10 or higher: [Download Python](https://www.python.org/) -- pip (specific version recommended): `pip >= 21.0` -- git (for cloning the repository): [Download Git](https://git-scm.com/) +### Broadcast Communication +```python +async def broadcast(sender: Agent, agents: AgentListType, task: str) -> None +``` -## Installation Options +**Information Flow:** +```mermaid +flowchart TD + T[Task] --> S((Sender)) + S --> A1((Agent 1)) + S --> A2((Agent 2)) + S --> A3((Agent 3)) + S --> A4((Agent 4)) +``` -=== "pip (Recommended)" +**Best Used When:** - #### Headless Installation +- Information needs to reach all agents - The headless installation of `swarms` is designed for environments where graphical user interfaces (GUI) are not needed, making it more lightweight and suitable for server-side applications. +- Tasks require global coordination - ```bash - pip install swarms - ``` +- You need system-wide updates -=== "UV Installation" +## Best Practices - UV is a fast Python package installer and resolver written in Rust. It's significantly faster than pip and provides better dependency resolution. +1. **Choose the Right Pattern:** + - Consider your task's natural structure + - Think about scaling requirements + - Consider fault tolerance needs - === "Basic Installation" +2. **Performance Considerations:** + - More complex patterns have higher overhead + - Consider communication costs + - Match pattern to available resources - ```bash - # Install UV first - curl -LsSf https://astral.sh/uv/install.sh | sh +3. **Error Handling:** + - All patterns include basic error checking + - Consider adding additional error handling for production + - Monitor agent performance and task completion - # Install swarms using UV - uv pip install swarms - ``` +4. **Scaling:** + - Different patterns scale differently + - Consider future growth needs + - Test with expected maximum load - === "Development Installation" +## Common Use Cases - ```bash - # Clone the repository - git clone https://github.com/kyegomez/swarms.git - cd swarms +1. **Data Processing Pipelines** + - Linear Swarm + - Circular Swarm - # Install in editable mode - uv pip install -e . - ``` +2. **Distributed Computing** + - Mesh Swarm + - Grid Swarm - For desktop installation with extras: +3. **Hierarchical Systems** + - Pyramid Swarm + - Star Swarm - ```bash - uv pip install -e .[desktop] - ``` +4. **Dynamic Workloads** + - Exponential Swarm + - Fibonacci Swarm -=== "Development Installation" +5. **Conflict-Free Processing** + - Prime Swarm + - Harmonic Swarm - === "Using virtualenv" - 1. **Clone the repository and navigate to the root directory:** +```python +import asyncio +from typing import List - ```bash - git clone https://github.com/kyegomez/swarms.git - cd swarms - ``` +from swarms.structs.agent import Agent +from swarms.structs.swarming_architectures import ( + broadcast, + circular_swarm, + exponential_swarm, + fibonacci_swarm, + grid_swarm, + linear_swarm, + mesh_swarm, + one_to_three, + prime_swarm, + sigmoid_swarm, + sinusoidal_swarm, + staircase_swarm, + star_swarm, +) - 2. **Setup Python environment and activate it:** - ```bash - python3 -m venv venv - source venv/bin/activate - pip install --upgrade pip - ``` +def create_finance_agents() -> List[Agent]: + """Create specialized finance agents""" + return [ + Agent( + agent_name="MarketAnalyst", + system_prompt="You are a market analysis expert. Analyze market trends and provide insights.", + model_name="gpt-4o-mini" + ), + Agent( + agent_name="RiskManager", + system_prompt="You are a risk management specialist. Evaluate risks and provide mitigation strategies.", + model_name="gpt-4o-mini" + ), + Agent( + agent_name="PortfolioManager", + system_prompt="You are a portfolio management expert. Optimize investment portfolios and asset allocation.", + model_name="gpt-4o-mini" + ), + Agent( + agent_name="ComplianceOfficer", + system_prompt="You are a financial compliance expert. Ensure regulatory compliance and identify issues.", + model_name="gpt-4o-mini" + ) + ] + +def create_healthcare_agents() -> List[Agent]: + """Create specialized healthcare agents""" + return [ + Agent( + agent_name="Diagnostician", + system_prompt="You are a medical diagnostician. Analyze symptoms and suggest potential diagnoses.", + model_name="gpt-4o-mini" + ), + Agent( + agent_name="Treatment_Planner", + system_prompt="You are a treatment planning specialist. Develop comprehensive treatment plans.", + model_name="gpt-4o-mini" + ), + Agent( + agent_name="MedicalResearcher", + system_prompt="You are a medical researcher. Analyze latest research and provide evidence-based recommendations.", + model_name="gpt-4o-mini" + ), + Agent( + agent_name="PatientCareCoordinator", + system_prompt="You are a patient care coordinator. Manage patient care workflow and coordination.", + model_name="gpt-4o-mini" + ) + ] - 3. **Install Swarms:** +def print_separator(): + print("\n" + "="*50 + "\n") - - Headless install: +def run_finance_circular_swarm(): + """Investment analysis workflow using circular swarm""" + print_separator() + print("FINANCE - INVESTMENT ANALYSIS (Circular Swarm)") + + agents = create_finance_agents() + tasks = [ + "Analyze Tesla stock performance for Q4 2024", + "Assess market risks and potential hedging strategies", + "Recommend portfolio adjustments based on analysis" + ] + + print("\nTasks:") + for i, task in enumerate(tasks, 1): + print(f"{i}. {task}") + + result = circular_swarm(agents, tasks) + print("\nResults:") + for log in result['history']: + print(f"\n{log['agent_name']}:") + print(f"Task: {log['task']}") + print(f"Response: {log['response']}") - ```bash - pip install -e . - ``` +def run_healthcare_grid_swarm(): + """Patient diagnosis and treatment planning using grid swarm""" + print_separator() + print("HEALTHCARE - PATIENT DIAGNOSIS (Grid Swarm)") + + agents = create_healthcare_agents() + tasks = [ + "Review patient symptoms: fever, fatigue, joint pain", + "Research latest treatment protocols", + "Develop preliminary treatment plan", + "Coordinate with specialists" + ] + + print("\nTasks:") + for i, task in enumerate(tasks, 1): + print(f"{i}. {task}") + + result = grid_swarm(agents, tasks) + print("\nGrid swarm processing completed") + print(result) - - Desktop install: +def run_finance_linear_swarm(): + """Loan approval process using linear swarm""" + print_separator() + print("FINANCE - LOAN APPROVAL PROCESS (Linear Swarm)") + + agents = create_finance_agents()[:3] + tasks = [ + "Review loan application and credit history", + "Assess risk factors and compliance requirements", + "Generate final loan recommendation" + ] + + print("\nTasks:") + for i, task in enumerate(tasks, 1): + print(f"{i}. {task}") + + result = linear_swarm(agents, tasks) + print("\nResults:") + for log in result['history']: + print(f"\n{log['agent_name']}:") + print(f"Task: {log['task']}") + print(f"Response: {log['response']}") - ```bash - pip install -e .[desktop] - ``` +def run_healthcare_star_swarm(): + """Complex medical case management using star swarm""" + print_separator() + print("HEALTHCARE - COMPLEX CASE MANAGEMENT (Star Swarm)") + + agents = create_healthcare_agents() + tasks = [ + "Complex case: Patient with multiple chronic conditions", + "Develop integrated care plan" + ] + + print("\nTasks:") + for i, task in enumerate(tasks, 1): + print(f"{i}. {task}") + + result = star_swarm(agents, tasks) + print("\nResults:") + for log in result['history']: + print(f"\n{log['agent_name']}:") + print(f"Task: {log['task']}") + print(f"Response: {log['response']}") - === "Using Anaconda" +def run_finance_mesh_swarm(): + """Market risk assessment using mesh swarm""" + print_separator() + print("FINANCE - MARKET RISK ASSESSMENT (Mesh Swarm)") + + agents = create_finance_agents() + tasks = [ + "Analyze global market conditions", + "Assess currency exchange risks", + "Evaluate sector-specific risks", + "Review portfolio exposure" + ] + + print("\nTasks:") + for i, task in enumerate(tasks, 1): + print(f"{i}. {task}") + + result = mesh_swarm(agents, tasks) + print("\nResults:") + for log in result['history']: + print(f"\n{log['agent_name']}:") + print(f"Task: {log['task']}") + print(f"Response: {log['response']}") - 1. **Create and activate an Anaconda environment:** +def run_mathematical_finance_swarms(): + """Complex financial analysis using mathematical swarms""" + print_separator() + print("FINANCE - MARKET PATTERN ANALYSIS") + + agents = create_finance_agents() + tasks = [ + "Analyze historical market patterns", + "Predict market trends using technical analysis", + "Identify potential arbitrage opportunities" + ] + + print("\nTasks:") + for i, task in enumerate(tasks, 1): + print(f"{i}. {task}") + + print("\nFibonacci Swarm Results:") + result = fibonacci_swarm(agents, tasks.copy()) + print(result) + + print("\nPrime Swarm Results:") + result = prime_swarm(agents, tasks.copy()) + print(result) + + print("\nExponential Swarm Results:") + result = exponential_swarm(agents, tasks.copy()) + print(result) - ```bash - conda create -n swarms python=3.10 - conda activate swarms - ``` +def run_healthcare_pattern_swarms(): + """Patient monitoring using pattern swarms""" + print_separator() + print("HEALTHCARE - PATIENT MONITORING PATTERNS") + + agents = create_healthcare_agents() + task = "Monitor and analyze patient vital signs: BP, heart rate, temperature, O2 saturation" + + print(f"\nTask: {task}") + + print("\nStaircase Pattern Analysis:") + result = staircase_swarm(agents, task) + print(result) + + print("\nSigmoid Pattern Analysis:") + result = sigmoid_swarm(agents, task) + print(result) + + print("\nSinusoidal Pattern Analysis:") + result = sinusoidal_swarm(agents, task) + print(result) - 2. **Clone the repository and navigate to the root directory:** +async def run_communication_examples(): + """Communication patterns for emergency scenarios""" + print_separator() + print("EMERGENCY COMMUNICATION PATTERNS") + + # Finance market alert + finance_sender = create_finance_agents()[0] + finance_receivers = create_finance_agents()[1:] + market_alert = "URGENT: Major market volatility detected - immediate risk assessment required" + + print("\nFinance Market Alert:") + print(f"Alert: {market_alert}") + result = await broadcast(finance_sender, finance_receivers, market_alert) + print("\nBroadcast Results:") + for log in result['history']: + print(f"\n{log['agent_name']}:") + print(f"Response: {log['response']}") + + # Healthcare emergency + health_sender = create_healthcare_agents()[0] + health_receivers = create_healthcare_agents()[1:4] + emergency_case = "EMERGENCY: Trauma patient with multiple injuries - immediate consultation required" + + print("\nHealthcare Emergency:") + print(f"Case: {emergency_case}") + result = await one_to_three(health_sender, health_receivers, emergency_case) + print("\nConsultation Results:") + for log in result['history']: + print(f"\n{log['agent_name']}:") + print(f"Response: {log['response']}") - ```bash - git clone https://github.com/kyegomez/swarms.git - cd swarms - ``` +async def run_all_examples(): + """Execute all swarm examples""" + print("\n=== SWARM ARCHITECTURE EXAMPLES ===\n") + + # Finance examples + run_finance_circular_swarm() + run_finance_linear_swarm() + run_finance_mesh_swarm() + run_mathematical_finance_swarms() + + # Healthcare examples + run_healthcare_grid_swarm() + run_healthcare_star_swarm() + run_healthcare_pattern_swarms() + + # Communication examples + await run_communication_examples() + + print("\n=== ALL EXAMPLES COMPLETED ===") - 3. **Install Swarms:** +if __name__ == "__main__": + asyncio.run(run_all_examples()) +``` - - Headless install: +-------------------------------------------------- - ```bash - pip install -e . - ``` +# File: swarms\examples\vision_processing.md - - Desktop install: +# Vision Processing Examples - ```bash - pip install -e .[desktop] - ``` +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. - === "Using Poetry" +## Prerequisites - 1. **Clone the repository and navigate to the root directory:** +- Python 3.7+ - ```bash - git clone https://github.com/kyegomez/swarms.git - cd swarms - ``` +- OpenAI API key (for GPT-4V) - 2. **Setup Python environment and activate it:** +- Anthropic API key (for Claude 3) - ```bash - poetry env use python3.10 - poetry shell - ``` +- Swarms library - 3. **Install Swarms:** +## Installation - - Headless install: +```bash +pip3 install -U swarms +``` - ```bash - poetry install - ``` +## Environment Variables - - Desktop install: +```plaintext +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" # Required for GPT-4V +ANTHROPIC_API_KEY="" # Required for Claude 3 +``` - ```bash - poetry install --extras "desktop" - ``` +## Working with Images -=== "Using Docker" +### Supported Image Formats - Docker is an excellent option for creating isolated and reproducible environments, suitable for both development and production. Contact us if there are any issues with the docker setup +Vision-enabled agents support various image formats: - 1. **Pull the Docker image:** +| 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 | - ```bash - docker pull swarmscorp/swarms:tagname +### 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 - 2. **Run the Docker container:** +## Examples - ```bash - docker run -it --rm swarmscorp/swarms:tagname - ``` +### 1. Quality Control with GPT-4V - 3. **Build and run a custom Docker image:** +```python +from swarms.structs import Agent +from swarms.prompts.logistics import Quality_Control_Agent_Prompt - ```dockerfile - # Use Python 3.11 instead of 3.13 - FROM python:3.11-slim +# Load your image +factory_image = "path/to/your/image.jpg" # Local file path +# Or use a URL +# factory_image = "https://example.com/image.jpg" - # Set environment variables - ENV PYTHONDONTWRITEBYTECODE=1 \ - PYTHONUNBUFFERED=1 \ - WORKSPACE_DIR="agent_workspace" \ - OPENAI_API_KEY="your_swarm_api_key_here" +# 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 +) - # Set the working directory - WORKDIR /usr/src/swarms +# Run the analysis +response = quality_control_agent.run( + task="Analyze this image and provide a detailed quality control report", + img=factory_image +) - # Install system dependencies - RUN apt-get update && apt-get install -y \ - build-essential \ - gcc \ - g++ \ - gfortran \ - && rm -rf /var/lib/apt/lists/* +print(response) +``` - # Install swarms package - RUN pip3 install -U swarm-models - RUN pip3 install -U swarms +### 2. Visual Analysis with Claude 3 - # Copy the application - COPY . . - ``` +```python +from swarms.structs import Agent +from swarms.prompts.logistics import Visual_Analysis_Prompt -=== "Using Kubernetes" +# Load your image +product_image = "path/to/your/product.jpg" - Kubernetes provides an automated way to deploy, scale, and manage containerized applications. +# 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 +) - 1. **Create a Deployment YAML file:** +# Run the analysis +response = visual_analyst.run( + task="Provide a comprehensive analysis of this product image", + img=product_image +) - ```yaml - apiVersion: apps/v1 - kind: Deployment - metadata: - name: swarms-deployment - spec: - replicas: 3 - selector: - matchLabels: - app: swarms - template: - metadata: - labels: - app: swarms - spec: - containers: - - name: swarms - image: kyegomez/swarms - ports: - - containerPort: 8080 - ``` +print(response) +``` - 2. **Apply the Deployment:** +### 3. Image Batch Processing - ```bash - kubectl apply -f deployment.yaml - ``` +```python +from swarms.structs import Agent +import os - 3. **Expose the Deployment:** +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 - ```bash - kubectl expose deployment swarms-deployment --type=LoadBalancer --name=swarms-service - ``` +# Example usage +image_folder = "path/to/image/folder" +batch_results = process_image_batch(image_folder, visual_analyst) +``` -=== "CI/CD Pipelines" +## Best Practices - Integrating Swarms into your CI/CD pipeline ensures automated testing and deployment. +| 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 | - #### Using GitHub Actions - ```yaml - # .github/workflows/ci.yml - name: CI - on: - push: - branches: [ main ] - pull_request: - branches: [ main ] - jobs: - build: +-------------------------------------------------- - runs-on: ubuntu-latest +# File: swarms\examples\vision_tools.md - steps: - - uses: actions/checkout@v2 - - name: Set up Python - uses: actions/setup-python@v2 - with: - python-version: 3.10 - - name: Install dependencies - run: | - python -m venv venv - source venv/bin/activate - pip install --upgrade pip - pip install -e . - - name: Run tests - run: | - source venv/bin/activate - pytest - ``` +# Agents with Vision and Tool Usage - #### Using Jenkins +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. - ```groovy - pipeline { - agent any +## What You'll Learn - stages { - stage('Clone repository') { - steps { - git 'https://github.com/kyegomez/swarms.git' - } - } - stage('Setup Python') { - steps { - sh 'python3 -m venv venv' - sh 'source venv/bin/activate && pip install --upgrade pip' - } - } - stage('Install dependencies') { - steps { - sh 'source venv/bin/activate && pip install -e .' - } - } - stage('Run tests') { - steps { - sh 'source venv/bin/activate && pytest' - } - } - } - } - ``` +- 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 -## Rust +## Use Cases -=== "Cargo install" +This approach is perfect for: - Get started with the Rust implementation of Swarms. [Get started with the docs here](https://docs.swarms.world/en/latest/swarms_rs/overview/) +- **Quality Control Systems**: Automated inspection of manufacturing processes - ```bash - cargo add swarms-rs - ``` +- **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 -# File: swarms\install\quickstart.md +Install the swarms package using pip: -## Quickstart +```bash +pip install -U swarms +``` -**Swarms** is an enterprise-grade, production-ready multi-agent collaboration framework that enables you to orchestrate agents to work collaboratively at scale to automate real-world activities. Follow this quickstart guide to get up and running with Swarms, including setting up your environment, building an agent, and leveraging multi-agent methods. +## Basic Setup -### **Requirements** +1. First, set up your environment variables: -- Python 3.10 or above -- `.env` file with API keys from your providers like `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` -- Set an environment variable for your workspace directory: - ```bash - WORKSPACE_DIR="agent_workspace" - ``` +```python +WORKSPACE_DIR="agent_workspace" +OPENAI_API_KEY="" +``` -### **Installation** -To install Swarms, run: -```bash -$ pip install -U swarms -``` +## Code -### **Usage Example: Single Agent** +- Create tools for your agent as a function with types and documentation -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. +- Pass tools to your agent `Agent(tools=[list_of_callables])` -```python -from swarms.structs.agent import Agent +- Add your image path to the run method like: `Agent().run(task=task, img=img)` -# Initialize the agent with GPT-4o-mini model -agent = Agent( - agent_name="Financial-Analysis-Agent", - system_prompt="Analyze financial situations and provide advice...", - max_loops=1, - autosave=True, - dashboard=False, - verbose=True, - saved_state_path="finance_agent.json", - model_name="gpt-4o-mini", +```python +from swarms.structs import Agent +from swarms.prompts.logistics import ( + Quality_Control_Agent_Prompt, ) -# 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) -``` -#### **Agent Class** +# Image for analysis +factory_image = "image.jpg" -- **Attributes:** - - `agent_name`: Name of the agent. - - `system_prompt`: System-level instruction guiding the agent's behavior. - - `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. - - `filtered_run(task: str)`: Runs agent with a filtered system prompt. ------ +def security_analysis(danger_level: str) -> str: + """ + Analyzes the security danger level and returns an appropriate response. -## Creating Agents from YAML + 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" -### Step 1: Define Your Agents in a YAML File + if danger_level == "low": + return "No danger" -The `create_agents_from_yaml` function works by reading agent configurations from a YAML file. Below is an example of what your YAML file (`agents_config.yaml`) should look like this. Example YAML Configuration (`agents_config.yaml`): + if danger_level == "medium": + return "Medium danger" -```yaml -agents: - - agent_name: "Financial-Analysis-Agent" - 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: false - dashboard: false - verbose: false - dynamic_temperature_enabled: false - user_name: "swarms_corp" - retry_attempts: 1 - context_length: 200000 - return_step_meta: false - output_type: "str" - temperature: 0.1 - max_tokens: 2000 - task: "Analyze tech stocks for 2024 investment strategy. Provide detailed analysis and recommendations." + if danger_level == "high": + return "High danger" - - 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: false - dynamic_temperature_enabled: false - user_name: "swarms_corp" - retry_attempts: 1 - context_length: 150000 - 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." + return "Unknown danger level" -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. -- **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. +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. -### Step 2: Create the Main Script +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. +""" -Now, create the main Python script that will use the `create_agents_from_yaml` function. +# 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], +) -### `main.py`: -```python -from swarms.agents.create_agents_from_yaml import create_agents_from_yaml -# Create agents and get task results -task_results = create_agents_from_yaml( - yaml_file="agents_config.yaml", - return_type="run_swarm" +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, ) - -print(task_results) ``` -### Example Run: -```bash -python main.py -``` +## Support and Community -This will: -1. Load agent configurations from `agents_config.yaml`. -2. Create the agents specified in the YAML file. -3. Run the tasks provided for each agent. -4. Output the task results to the console. +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 | -### Step 3: Customize the Return Type -The `create_agents_from_yaml` function supports multiple return types. You can control what is returned by setting the `return_type` parameter to `"agents"`, `"tasks"`, or `"both"`. -1. **Return Only Agents** -To create agents but not run tasks, set `return_type="agents"`: +-------------------------------------------------- -```python -agents = create_agents_from_yaml(yaml_file, return_type="agents") -for agent in agents: - print(f"Agent {agent.agent_name} created.") -``` +# File: swarms\examples\vllm.md -2. **Return Only Task Results** -If you only care about the task results and not the agent objects, set `return_type="tasks"`: +# VLLM Swarm Agents -```python -task_results = create_agents_from_yaml(yaml_file, return_type="tasks") -for result in task_results: - print(f"Agent {result['agent_name']} executed task '{result['task']}' with output: {result['output']}") -``` +!!! tip "Quick Summary" + This guide demonstrates how to create a sophisticated multi-agent system using VLLM and Swarms for comprehensive stock market analysis. You'll learn how to configure and orchestrate multiple AI agents working together to provide deep market insights. -3. **Return Both Agents and Task Results** -To return both the list of created agents and task results, use `return_type="both"`: +## Overview -```python -agents, task_results = create_agents_from_yaml(yaml_file, return_type="both") -# Process agents and tasks separately -``` +The example showcases how to build a stock analysis system with 5 specialized agents: +- Technical Analysis Agent +- Fundamental Analysis Agent +- Market Sentiment Agent +- Quantitative Strategy Agent +- Portfolio Strategy Agent -## Step 4: YAML Structure for Multiple Agents +Each agent has specific expertise and works collaboratively through a concurrent workflow. -The YAML file can define any number of agents, each with its own unique configuration. You can scale this setup by adding more agents and tasks to the `agents` list within the YAML file. +## Prerequisites -```yaml -agents: - - agent_name: "Agent1" - # Agent1 config... +!!! warning "Requirements" + Before starting, ensure you have: - - agent_name: "Agent2" - # Agent2 config... + - Python 3.7 or higher + - The Swarms package installed + - Access to VLLM compatible models + - Sufficient compute resources for running VLLM - - agent_name: "Agent3" - # Agent3 config... -``` +## Installation -Each agent will be initialized according to its configuration, and tasks (if provided) will be executed automatically. +!!! example "Setup Steps" ---- + 1. Install the Swarms package: + ```bash + pip install swarms + ``` -## Integrating External Agents -Integrating external agents from other agent frameworks is easy with swarms. + 2. Install VLLM dependencies (if not already installed): + ```bash + pip install vllm + ``` -Steps: +## Basic Usage -1. Create a new class that inherits `Agent` -2. Create a `.run(task: str) -> str` method that runs the agent and returns the response. -3. The new Agent must return a string of the response. But you may add additional methods to save the output to JSON. +Here's a complete example of setting up the stock analysis swarm: +```python +from swarms import Agent, ConcurrentWorkflow +from swarms.utils.vllm_wrapper import VLLMWrapper -### Griptape Example +# Initialize the VLLM wrapper +vllm = VLLMWrapper( + model_name="meta-llama/Llama-2-7b-chat-hf", + system_prompt="You are a helpful assistant.", +) +``` -For example, here's an example on how to create an agent from griptape. +!!! note "Model Selection" + The example uses Llama-2-7b-chat, but you can use any VLLM-compatible model. Make sure you have the necessary permissions and resources to run your chosen model. -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. +## Agent Configuration +### Technical Analysis Agent ```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, -) +technical_analyst = Agent( + agent_name="Technical-Analysis-Agent", + agent_description="Expert in technical analysis and chart patterns", + system_prompt="""You are an expert Technical Analysis Agent specializing in market technicals and chart patterns. Your responsibilities include: +1. PRICE ACTION ANALYSIS +- Identify key support and resistance levels +- Analyze price trends and momentum +- Detect chart patterns (e.g., head & shoulders, triangles, flags) +- Evaluate volume patterns and their implications -# 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, - # Add additional settings - ) +2. TECHNICAL INDICATORS +- Calculate and interpret moving averages (SMA, EMA) +- Analyze momentum indicators (RSI, MACD, Stochastic) +- Evaluate volume indicators (OBV, Volume Profile) +- Monitor volatility indicators (Bollinger Bands, ATR) - # 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 (you can modify this parsing based on task structure) - url, filename = task.split( - "," - ) # Example of splitting task string - # Execute the Griptape agent with the task inputs - result = self.agent.run(url.strip(), filename.strip()) - # Return the final result as a string - return str(result) +3. TRADING SIGNALS +- Generate clear buy/sell signals based on technical criteria +- Identify potential entry and exit points +- Set appropriate stop-loss and take-profit levels +- Calculate position sizing recommendations +4. RISK MANAGEMENT +- Assess market volatility and trend strength +- Identify potential reversal points +- Calculate risk/reward ratios for trades +- Suggest position sizing based on risk parameters -# Example usage: -griptape_swarms_agent = GriptapeSwarmsAgent() -output = griptape_swarms_agent.run( - "https://griptape.ai, griptape.txt" +Your analysis should be data-driven, precise, and actionable. Always include specific price levels, time frames, and risk parameters in your recommendations.""", + max_loops=1, + llm=vllm, ) -print(output) ``` -### Key Components: -1. **GriptapeSwarmsAgent**: A custom class that inherits from the `SwarmsAgent` class and integrates the Griptape agent. -2. **run(task: str) -> str**: A method that takes a task string, processes it (e.g., splitting into a URL and filename), and runs the Griptape agent with the provided inputs. -3. **Griptape Tools**: The tools integrated into the Griptape agent (e.g., `WebScraperTool`, `PromptSummaryTool`, `FileManagerTool`) allow for web scraping, summarization, and file management. +!!! tip "Agent Customization" + Each agent can be customized with different: + + - System prompts + + - Temperature settings + + - Max token limits + + - Response formats -You can now easily plug this custom Griptape agent into the **Swarms Framework** and use it to run tasks! +## Running the Swarm + +To execute the swarm analysis: +```python +swarm = ConcurrentWorkflow( + name="Stock-Analysis-Swarm", + description="A swarm of agents that analyze stocks and provide comprehensive analysis.", + agents=stock_analysis_agents, +) +# Run the analysis +response = swarm.run("Analyze the best etfs for gold and other similar commodities in volatile markets") +``` -## Overview of Swarm Architectures in the Swarms Framework ---- +## Full Code Example -### 1. **Sequential Workflow** +```python +from swarms import Agent, ConcurrentWorkflow +from swarms.utils.vllm_wrapper import VLLMWrapper -**Overview**: The `SequentialWorkflow` enables tasks to be executed one after the other. Each agent processes its task and passes the output to the next agent in the sequence. +# Initialize the VLLM wrapper +vllm = VLLMWrapper( + model_name="meta-llama/Llama-2-7b-chat-hf", + system_prompt="You are a helpful assistant.", +) -#### Mermaid Graph: +# Technical Analysis Agent +technical_analyst = Agent( + agent_name="Technical-Analysis-Agent", + agent_description="Expert in technical analysis and chart patterns", + system_prompt="""You are an expert Technical Analysis Agent specializing in market technicals and chart patterns. Your responsibilities include: -```mermaid -graph TD; - A[Task Input] --> B[Blog Generator Agent]; - B --> C[Summarizer Agent]; - C --> D[Task Output]; -``` +1. PRICE ACTION ANALYSIS +- Identify key support and resistance levels +- Analyze price trends and momentum +- Detect chart patterns (e.g., head & shoulders, triangles, flags) +- Evaluate volume patterns and their implications -#### Code Example: +2. TECHNICAL INDICATORS +- Calculate and interpret moving averages (SMA, EMA) +- Analyze momentum indicators (RSI, MACD, Stochastic) +- Evaluate volume indicators (OBV, Volume Profile) +- Monitor volatility indicators (Bollinger Bands, ATR) -```python -from swarms import Agent, SequentialWorkflow +3. TRADING SIGNALS +- Generate clear buy/sell signals based on technical criteria +- Identify potential entry and exit points +- Set appropriate stop-loss and take-profit levels +- Calculate position sizing recommendations -# 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 +4. RISK MANAGEMENT +- Assess market volatility and trend strength +- Identify potential reversal points +- Calculate risk/reward ratios for trades +- Suggest position sizing based on risk parameters + +Your analysis should be data-driven, precise, and actionable. Always include specific price levels, time frames, and risk parameters in your recommendations.""", + max_loops=1, + llm=vllm, ) -agent2 = Agent( - agent_name="Summarizer", - system_prompt="Summarize the blog post", - model_name="claude-3-sonnet-20240229", - max_loops=1 + +# Fundamental Analysis Agent +fundamental_analyst = Agent( + agent_name="Fundamental-Analysis-Agent", + agent_description="Expert in company fundamentals and valuation", + system_prompt="""You are an expert Fundamental Analysis Agent specializing in company valuation and financial metrics. Your core responsibilities include: + +1. FINANCIAL STATEMENT ANALYSIS +- Analyze income statements, balance sheets, and cash flow statements +- Calculate and interpret key financial ratios +- Evaluate revenue growth and profit margins +- Assess company's debt levels and cash position + +2. VALUATION METRICS +- Calculate fair value using multiple valuation methods: + * Discounted Cash Flow (DCF) + * Price-to-Earnings (P/E) + * Price-to-Book (P/B) + * Enterprise Value/EBITDA +- Compare valuations against industry peers + +3. BUSINESS MODEL ASSESSMENT +- Evaluate competitive advantages and market position +- Analyze industry dynamics and market share +- Assess management quality and corporate governance +- Identify potential risks and growth opportunities + +4. ECONOMIC CONTEXT +- Consider macroeconomic factors affecting the company +- Analyze industry cycles and trends +- Evaluate regulatory environment and compliance +- Assess global market conditions + +Your analysis should be comprehensive, focusing on both quantitative metrics and qualitative factors that impact long-term value.""", + max_loops=1, + llm=vllm, ) -# Create Sequential workflow -workflow = SequentialWorkflow(agents=[agent1, agent2], max_loops=1) +# Market Sentiment Agent +sentiment_analyst = Agent( + agent_name="Market-Sentiment-Agent", + agent_description="Expert in market psychology and sentiment analysis", + system_prompt="""You are an expert Market Sentiment Agent specializing in analyzing market psychology and investor behavior. Your key responsibilities include: + +1. SENTIMENT INDICATORS +- Monitor and interpret market sentiment indicators: + * VIX (Fear Index) + * Put/Call Ratio + * Market Breadth + * Investor Surveys +- Track institutional vs retail investor behavior + +2. NEWS AND SOCIAL MEDIA ANALYSIS +- Analyze news flow and media sentiment +- Monitor social media trends and discussions +- Track analyst recommendations and changes +- Evaluate corporate insider trading patterns -# Run workflow -output = workflow.run("Generate a blog post on how swarms of agents can help businesses grow.") -print(output) -``` +3. MARKET POSITIONING +- Assess hedge fund positioning and exposure +- Monitor short interest and short squeeze potential +- Track fund flows and asset allocation trends +- Analyze options market sentiment ---- +4. CONTRARIAN SIGNALS +- Identify extreme sentiment readings +- Detect potential market turning points +- Analyze historical sentiment patterns +- Provide contrarian trading opportunities -### 2. **Agent Rearrange** +Your analysis should combine quantitative sentiment metrics with qualitative assessment of market psychology and crowd behavior.""", + max_loops=1, + llm=vllm, +) -**Overview**: `AgentRearrange` allows the orchestration of agents in both sequential and parallel configurations. The user can define a flexible flow of tasks between agents. +# Quantitative Strategy Agent +quant_analyst = Agent( + agent_name="Quantitative-Strategy-Agent", + agent_description="Expert in quantitative analysis and algorithmic strategies", + system_prompt="""You are an expert Quantitative Strategy Agent specializing in data-driven investment strategies. Your primary responsibilities include: -#### Mermaid Graph: +1. FACTOR ANALYSIS +- Analyze and monitor factor performance: + * Value + * Momentum + * Quality + * Size + * Low Volatility +- Calculate factor exposures and correlations -```mermaid -graph TD; - A[Director Agent] --> B[Worker 1 Agent]; - A --> C[Worker 2 Agent]; - B --> D[Task Completed]; - C --> D[Task Completed]; -``` +2. STATISTICAL ANALYSIS +- Perform statistical arbitrage analysis +- Calculate and monitor pair trading opportunities +- Analyze market anomalies and inefficiencies +- Develop mean reversion strategies -#### Code Example: +3. RISK MODELING +- Build and maintain risk models +- Calculate portfolio optimization metrics +- Monitor correlation matrices +- Analyze tail risk and stress scenarios -```python -from swarms import Agent, AgentRearrange +4. ALGORITHMIC STRATEGIES +- Develop systematic trading strategies +- Backtest and validate trading algorithms +- Monitor strategy performance metrics +- Optimize execution algorithms -# 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 +Your analysis should be purely quantitative, based on statistical evidence and mathematical models rather than subjective opinions.""", + max_loops=1, + llm=vllm, ) -# Define the flow and create the rearranged system -flow = "Director -> Worker1 -> Worker2" -agent_system = AgentRearrange(agents=[director, worker1, worker2], flow=flow) +# Portfolio Strategy Agent +portfolio_strategist = Agent( + agent_name="Portfolio-Strategy-Agent", + agent_description="Expert in portfolio management and asset allocation", + system_prompt="""You are an expert Portfolio Strategy Agent specializing in portfolio construction and management. Your core responsibilities include: -# Run it -output = agent_system.run("Create a YouTube transcript and summary") -print(output) -``` +1. ASSET ALLOCATION +- Develop strategic asset allocation frameworks +- Recommend tactical asset allocation shifts +- Optimize portfolio weightings +- Balance risk and return objectives +2. PORTFOLIO ANALYSIS +- Calculate portfolio risk metrics +- Monitor sector and factor exposures +- Analyze portfolio correlation matrix +- Track performance attribution +3. RISK MANAGEMENT +- Implement portfolio hedging strategies +- Monitor and adjust position sizing +- Set stop-loss and rebalancing rules +- Develop drawdown protection strategies ---- +4. PORTFOLIO OPTIMIZATION +- Calculate efficient frontier analysis +- Optimize for various objectives: + * Maximum Sharpe Ratio + * Minimum Volatility + * Maximum Diversification +- Consider transaction costs and taxes -### 4. **Mixture of Agents** +Your recommendations should focus on portfolio-level decisions that optimize risk-adjusted returns while meeting specific investment objectives.""", + max_loops=1, + llm=vllm, +) -**Overview**: `MixtureOfAgents` is a parallelized architecture where agents perform tasks concurrently and then feed their results back into a loop for final aggregation. This is useful for highly parallelizable tasks. +# Create a list of all agents +stock_analysis_agents = [ + technical_analyst, + fundamental_analyst, + sentiment_analyst, + quant_analyst, + portfolio_strategist +] -#### Mermaid Graph: +swarm = ConcurrentWorkflow( + name="Stock-Analysis-Swarm", + description="A swarm of agents that analyze stocks and provide a comprehensive analysis of the current trends and opportunities.", + agents=stock_analysis_agents, +) -```mermaid -graph TD; - A[Director Agent] --> B[Accountant 1]; - A --> C[Accountant 2]; - B --> D[Final Aggregation]; - C --> D[Final Aggregation]; +swarm.run("Analyze the best etfs for gold and other similiar commodities in volatile markets") ``` -#### Code Example: - -```python -from swarms import Agent, OpenAIChat, MixtureOfAgents +## Best Practices -# Initialize agents -director = Agent(agent_name="Director", system_prompt="Directs tasks", llm=OpenAIChat(), max_loops=1) -accountant1 = Agent(agent_name="Accountant1", system_prompt="Prepare financial statements", llm=OpenAIChat(), max_loops=1) -accountant2 = Agent(agent_name="Accountant2", system_prompt="Audit financial records", llm=OpenAIChat(), max_loops=1) +!!! success "Optimization Tips" + 1. **Agent Design** + - Keep system prompts focused and specific + + - Use clear role definitions + + - Include error handling guidelines + + 2. **Resource Management** + + - Monitor memory usage with large models + + - Implement proper cleanup procedures + + - Use batching for multiple queries + + 3. **Output Handling** + + - Implement proper logging + + - Format outputs consistently + + - Include error checking -# Create Mixture of Agents swarm -swarm = MixtureOfAgents(name="Mixture of Accountants", agents=[director, accountant1, accountant2], layers=3, final_agent=director) +## Common Issues and Solutions -# Run the swarm -output = swarm.run("Prepare financial statements and audit financial records") -print(output) -``` +!!! warning "Troubleshooting" + Common issues you might encounter: ---- + 1. **Memory Issues** + + - *Problem*: VLLM consuming too much memory + + - *Solution*: Adjust batch sizes and model parameters + + 2. **Agent Coordination** + + - *Problem*: Agents providing conflicting information + + - *Solution*: Implement consensus mechanisms or priority rules + + 3. **Performance** + + - *Problem*: Slow response times + + - *Solution*: Use proper batching and optimize model loading -### 5. **Spreadsheet Swarm** +## FAQ -**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. +??? question "Can I use different models for different agents?" + Yes, you can initialize multiple VLLM wrappers with different models for each agent. However, be mindful of memory usage. -#### Mermaid Graph: +??? question "How many agents can run concurrently?" + The number depends on your hardware resources. Start with 3-5 agents and scale based on performance. -```mermaid -graph TD; - A[Spreadsheet Swarm] --> B[Twitter Agent]; - A --> C[Instagram Agent]; - A --> D[Facebook Agent]; - A --> E[LinkedIn Agent]; - A --> F[Email Agent]; -``` +??? question "Can I customize agent communication patterns?" + Yes, you can modify the ConcurrentWorkflow class or create custom workflows for specific communication patterns. -#### Code Example: +## Advanced Configuration -```python -from swarms import Agent -from swarms.structs.spreadsheet_swarm import SpreadSheetSwarm +!!! example "Extended Settings" + ```python + vllm = VLLMWrapper( + model_name="meta-llama/Llama-2-7b-chat-hf", + system_prompt="You are a helpful assistant.", + temperature=0.7, + max_tokens=2048, + top_p=0.95, + ) + ``` -# Initialize agents for different marketing platforms using model_name -agents = [ - 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 - ), -] +## Contributing -# Create the Spreadsheet Swarm -swarm = SpreadSheetSwarm( - agents=agents, - save_file_path="real_estate_marketing_spreadsheet.csv", - run_all_agents=False, - max_loops=2 -) +!!! info "Get Involved" + We welcome contributions! Here's how you can help: -# Run the swarm -swarm.run("Create posts to promote luxury properties in North Texas.") -``` + 1. Report bugs and issues + 2. Submit feature requests + 3. Contribute to documentation + 4. Share example use cases ---- +## Resources -These are the key swarm architectures available in the **Swarms Framework**. Each one is designed to solve different types of multi-agent orchestration problems, from sequential tasks to large-scale parallel processing. +!!! abstract "Additional Reading" + - [VLLM Documentation](https://docs.vllm.ai/en/latest/) + +-------------------------------------------------- -### Overview of Swarm Architectures -#### **Workflow Classes** +# File: swarms\examples\vllm_integration.md -- **SequentialWorkflow:** - - 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. -#### **Swarm Architectures** -- **Hierarchical Swarms:** - - Implements top-down control, where a boss agent coordinates tasks among sub-agents. - -- **Spreadsheet Swarm:** - - A large-scale swarm architecture for managing multiple agents working concurrently. +# vLLM Integration Guide +!!! info "Overview" + vLLM is a high-performance and easy-to-use library for LLM inference and serving. This guide explains how to integrate vLLM with Swarms for efficient, production-grade language model deployment. --------------------------------------------------- +## Installation -# File: swarms\install\workspace_manager.md +!!! note "Prerequisites" + Before you begin, make sure you have Python 3.8+ installed on your system. -# Swarms Framework Environment Configuration +=== "pip" + ```bash + pip install -U vllm swarms + ``` -This guide details the environment variables used in the Swarms framework for configuration and customization of your agent-based applications. +=== "poetry" + ```bash + poetry add vllm swarms + ``` -## Configuration Setup +## Basic Usage -Create a `.env` file in your project's root directory to configure the Swarms framework. This file will contain all necessary environment variables for customizing your agent's behavior, logging, and analytics. +Here's a simple example of how to use vLLM with Swarms: -## Environment Variables +```python title="basic_usage.py" +from swarms.utils.vllm_wrapper import VLLMWrapper -### Core Variables +# Initialize the vLLM wrapper +vllm = VLLMWrapper( + model_name="meta-llama/Llama-2-7b-chat-hf", + system_prompt="You are a helpful assistant.", + temperature=0.7, + max_tokens=4000 +) -#### `WORKSPACE_DIR` -- **Purpose**: Defines the directory where all agent states and execution logs are stored -- **Type**: String (path) -- **Default**: `./workspace` -- **Example**: -```bash -WORKSPACE_DIR=/path/to/your/workspace +# Run inference +response = vllm.run("What is the capital of France?") +print(response) ``` -- **Usage**: - - Stores JSON files containing agent states - - Maintains execution history - - Keeps track of agent interactions - - Preserves conversation logs -#### `SWARMS_AUTOUPDATE_ON` -- **Purpose**: Controls automatic updates of the Swarms framework -- **Type**: Boolean -- **Default**: `false` -- **Example**: -```bash -SWARMS_AUTOUPDATE_ON=true -``` -- **Features**: - - Automatically updates to the latest stable version - - Ensures you have the newest features - - Maintains compatibility with the latest improvements - - Handles dependency updates -- **Considerations**: - - Set to `false` if you need version stability - - Recommended `true` for development environments - - Consider system requirements for auto-updates - - May require restart after updates +## VLLMWrapper Class -### Telemetry Configuration +!!! abstract "Class Overview" + The `VLLMWrapper` class provides a convenient interface for working with vLLM models. -#### `USE_TELEMETRY` -- **Purpose**: Controls whether telemetry data is collected -- **Type**: Boolean -- **Default**: `false` -- **Example**: -```bash -USE_TELEMETRY=true -``` -- **Data Collected**: - - Agent performance metrics - - Execution time statistics - - Memory usage - - Error rates - - System health indicators +### Key Parameters -### Analytics Integration +| Parameter | Type | Description | Default | +|-----------|------|-------------|---------| +| `model_name` | str | Name of the model to use | "meta-llama/Llama-2-7b-chat-hf" | +| `system_prompt` | str | System prompt to use | None | +| `stream` | bool | Whether to stream the output | False | +| `temperature` | float | Sampling temperature | 0.5 | +| `max_tokens` | int | Maximum number of tokens to generate | 4000 | -#### `SWARMS_API_KEY` -- **Purpose**: Authentication key for the Swarms Analytics Suite -- **Type**: String -- **Required**: Yes, for analytics features -- **Example**: -```bash -SWARMS_API_KEY=your_api_key_here +### Example with Custom Parameters + +```python title="custom_parameters.py" +vllm = VLLMWrapper( + model_name="meta-llama/Llama-2-13b-chat-hf", + system_prompt="You are an expert in artificial intelligence.", + temperature=0.8, + max_tokens=2000 +) ``` -- **Features**: - - Real-time agent execution tracking - - Usage analytics - - Performance monitoring - - Cost tracking - - Custom metrics -## Getting Started +## Integration with Agents -1. Create a new `.env` file: -```bash -touch .env -``` +You can easily integrate vLLM with Swarms agents for more complex workflows: -2. Add your configuration: -```bash -# Basic configuration -WORKSPACE_DIR=./my_workspace +```python title="agent_integration.py" +from swarms import Agent +from swarms.utils.vllm_wrapper import VLLMWrapper -# Enable auto-updates -SWARMS_AUTOUPDATE_ON=true +# Initialize vLLM +vllm = VLLMWrapper( + model_name="meta-llama/Llama-2-7b-chat-hf", + system_prompt="You are a helpful assistant." +) -# Enable telemetry -USE_TELEMETRY=true +# Create an agent with vLLM +agent = Agent( + agent_name="Research-Agent", + agent_description="Expert in conducting research and analysis", + system_prompt="""You are an expert research agent. Your tasks include: + 1. Analyzing complex topics + 2. Providing detailed summaries + 3. Making data-driven recommendations""", + llm=vllm, + max_loops=1 +) -# Add your Swarms API key -SWARMS_API_KEY=your_api_key_here +# Run the agent +response = agent.run("Research the impact of AI on healthcare") ``` -3. Obtain your API key: - - Visit [swarms.ai](https://swarms.ai) - - Create an account or log in - - Navigate to the API section - - Generate your unique API key +## Advanced Features -## Best Practices +### Batch Processing -1. **Security**: - - Never commit your `.env` file to version control - - Add `.env` to your `.gitignore` file - - Keep your API keys secure and rotate them periodically +!!! tip "Performance Optimization" + Use batch processing for efficient handling of multiple tasks simultaneously. -2. **Workspace Organization**: - - Use descriptive workspace directory names - - Implement regular cleanup of old logs - - Monitor workspace size to prevent disk space issues +```python title="batch_processing.py" +tasks = [ + "What is machine learning?", + "Explain neural networks", + "Describe deep learning" +] -3. **Telemetry Management**: - - Enable telemetry in development for debugging - - Consider privacy implications in production - - Review collected data periodically +results = vllm.batched_run(tasks, batch_size=3) +``` -4. **Auto-Update Management**: - - Test updates in development before enabling in production - - Keep backups before enabling auto-updates - - Monitor system resources during updates - - Schedule updates during low-traffic periods +### Error Handling -## Examples +!!! warning "Error Management" + Always implement proper error handling in production environments. -### Basic Development Setup -```bash -WORKSPACE_DIR=./dev_workspace -SWARMS_AUTOUPDATE_ON=true -USE_TELEMETRY=true -SWARMS_API_KEY=sk_test_xxxxxxxxxxxx +```python title="error_handling.py" +from loguru import logger + +try: + response = vllm.run("Complex task") +except Exception as error: + logger.error(f"Error occurred: {error}") ``` -### Production Setup -```bash -WORKSPACE_DIR=/var/log/swarms/prod_workspace -SWARMS_AUTOUPDATE_ON=false -USE_TELEMETRY=true -SWARMS_API_KEY=sk_prod_xxxxxxxxxxxx -``` +## Best Practices -### Testing Environment -```bash -WORKSPACE_DIR=./test_workspace -SWARMS_AUTOUPDATE_ON=true -USE_TELEMETRY=false -SWARMS_API_KEY=sk_test_xxxxxxxxxxxx -``` +!!! success "Recommended Practices" + === "Model Selection" + - Choose appropriate model sizes based on your requirements + - Consider the trade-off between model size and inference speed -## Troubleshooting + === "System Resources" + - Ensure sufficient GPU memory for your chosen model + - Monitor resource usage during batch processing -Common issues and solutions: + === "Prompt Engineering" + - Use clear and specific system prompts + - Structure user prompts for optimal results -1. **Workspace Access Issues**: - - Ensure proper file permissions - - Verify the directory exists - - Check disk space availability + === "Error Handling" + - Implement proper error handling and logging + - Set up monitoring for production deployments -2. **API Key Problems**: - - Confirm key is properly formatted - - Verify key hasn't expired - - Check for proper environment variable loading + === "Performance" + - Use batch processing for multiple tasks + - Adjust max_tokens based on your use case + - Fine-tune temperature for optimal output quality -3. **Telemetry Issues**: - - Confirm network connectivity - - Verify firewall settings - - Check for proper boolean values +## Example: Multi-Agent System -4. **Auto-Update Issues**: - - Check internet connectivity - - Verify sufficient disk space - - Ensure proper permissions for updates - - Check system compatibility requirements +Here's an example of creating a multi-agent system using vLLM: -## Additional Resources +```python title="multi_agent_system.py" +from swarms import Agent, ConcurrentWorkflow +from swarms.utils.vllm_wrapper import VLLMWrapper -- [Swarms Framework Documentation](https://github.com/kyegomez/swarms) -- [Swarms Analytics Dashboard](https://swarms.ai) -- [API Reference](https://swarms.ai/docs/api) +# Initialize vLLM +vllm = VLLMWrapper( + model_name="meta-llama/Llama-2-7b-chat-hf", + system_prompt="You are a helpful assistant." +) --------------------------------------------------- +# Create specialized agents +research_agent = Agent( + agent_name="Research-Agent", + agent_description="Expert in research", + system_prompt="You are a research expert.", + llm=vllm +) -# File: swarms\memory\diy_memory.md +analysis_agent = Agent( + agent_name="Analysis-Agent", + agent_description="Expert in analysis", + system_prompt="You are an analysis expert.", + llm=vllm +) -# Integrating the Agent Class with Memory Systems/RAG in the Swarms Memory Framework +# Create a workflow +agents = [research_agent, analysis_agent] +workflow = ConcurrentWorkflow( + name="Research-Analysis-Workflow", + description="Comprehensive research and analysis workflow", + agents=agents +) -In this guide, we will cover how to integrate various memory systems from the Swarms Memory framework into an agent class. The Swarms Memory framework allows for the integration of different database-backed memory systems, enabling agents to retain and query long-term knowledge effectively. We'll walk through examples of integrating with Pinecone, ChromaDB, and Faiss, showcasing how to configure custom functions and embed memory functionality into an agent class. +# Run the workflow +result = workflow.run("Analyze the impact of renewable energy") +``` -## Installation +-------------------------------------------------- -First, you need to install the Swarms Memory package: +# File: swarms\examples\xai.md -```bash -$ pip install swarms swarms-memory -``` +# Agent with XAI +- Add your `XAI_API_KEY` in the `.env` file -### Integrating ChromaDB with the Agent Class +- Select your model_name like `xai/grok-beta` follows [LiteLLM conventions](https://docs.litellm.ai/docs/providers/xai) + +- Execute your agent! -ChromaDB is a simple, high-performance vector store for use with embeddings. Here's how you can integrate ChromaDB: ```python -from swarms_memory import ChromaDB -from swarms.structs.agent import Agent +from swarms import Agent +import os +from dotenv import load_dotenv -# Initialize ChromaDB memory -chromadb_memory = ChromaDB( - metric="cosine", - output_dir="finance_agent_rag", -) +load_dotenv() -# Initialize the Financial Analysis Agent with GPT-4o-mini model +# Initialize the agent with ChromaDB memory agent = Agent( agent_name="Financial-Analysis-Agent", + model_name="xai/grok-beta", system_prompt="Agent system prompt here", agent_description="Agent performs financial analysis.", - model_name="gpt-4o-mini", - long_term_memory=chromadb_memory, ) # Run a query -response = agent.run( - "What are the components of a startup's stock incentive equity plan?" -) -print(response) +agent.run("What are the components of a startup's stock incentive equity plan?") ``` -### Integrating Faiss with the Agent Class +-------------------------------------------------- -Faiss is a library for efficient similarity search and clustering of dense vectors. Here's how you can integrate Faiss: +# File: swarms\examples\yahoo_finance.md -```python -from typing import List, Dict, Any -from swarms_memory.faiss_wrapper import FAISSDB -from swarms import Agent -from swarm_models import Anthropic -from transformers import AutoTokenizer, AutoModel -import torch -import os +# Swarms Tools Example with Yahoo Finance -# Custom embedding function using a HuggingFace model -def custom_embedding_function(text: str) -> List[float]: - tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased") - model = AutoModel.from_pretrained("bert-base-uncased") - inputs = tokenizer( - text, - return_tensors="pt", - padding=True, - truncation=True, - max_length=512, - ) - with torch.no_grad(): - outputs = model(**inputs) - embeddings = ( - outputs.last_hidden_state.mean(dim=1).squeeze().tolist() - ) - return embeddings +- `pip3 install swarms swarms-tools` +- Add `OPENAI_API_KEY` to your `.env` file +- Run `yahoo_finance_agent.py` +- Agent will make a function call to the desired tool +- The tool will be executed and the result will be returned to the agent +- The agent will then analyze the result and return the final output -# Initialize the FAISS memory wrapper -faiss_memory = FAISSDB( - dimension=768, - index_type="Flat", - embedding_function=custom_embedding_function, - metric="cosine", -) -# Model -model = Anthropic(anthropic_api_key=os.getenv("ANTHROPIC_API_KEY")) +```python +from swarms import Agent +from swarms.prompts.finance_agent_sys_prompt import ( + FINANCIAL_AGENT_SYS_PROMPT, +) +from swarms_tools import ( + yahoo_finance_api, +) -# Initialize the agent with Faiss memory +# Initialize the agent agent = Agent( agent_name="Financial-Analysis-Agent", - system_prompt="Agent system prompt here", - agent_description="Agent performs financial analysis.", - llm=model, - long_term_memory=faiss_memory, + agent_description="Personal finance advisor agent", + system_prompt=FINANCIAL_AGENT_SYS_PROMPT, + max_loops=1, + model_name="gpt-4o", + dynamic_temperature_enabled=True, + user_name="swarms_corp", + retry_attempts=3, + context_length=8192, + return_step_meta=False, + output_type="str", # "json", "dict", "csv" OR "string" "yaml" and + auto_generate_prompt=False, # Auto generate prompt for the agent based on name, description, and system prompt, task + max_tokens=4000, # max output tokens + saved_state_path="agent_00.json", + interactive=False, + tools=[yahoo_finance_api], ) -# Run a query -agent.run("Explain the differences between various types of financial instruments.") +agent.run("Analyze the latest metrics for nvidia") +# Less than 30 lines of code.... ``` -## Mermaid Graphs for Visualizing Integration - -To help visualize the integration process, here's a Mermaid graph illustrating how an agent interacts with the memory systems: +-------------------------------------------------- -```mermaid -graph TD; - A[Agent] -->|Queries| B[Memory System] - B --> C{Pinecone / ChromaDB / Faiss} - C --> D[Embedding Function] - D --> E[LLM Model] - E --> F[Query Results] - F -->|Returns| A -``` +# File: swarms\features.md -This graph shows the flow from the agent sending queries to the memory system, which processes them using the embedding function and LLM model, and finally returns the results back to the agent. +## ✨ Enterprise Features -## Conclusion +Swarms delivers a comprehensive, enterprise-grade multi-agent infrastructure platform designed for production-scale deployments and seamless integration with existing systems. -Integrating various memory systems from the Swarms Memory framework into the agent class enables the creation of powerful, memory-augmented agents capable of retaining and recalling information over time. Whether you're using Pinecone, ChromaDB, or Faiss, the process involves initializing the memory system, embedding functions, and then passing this memory system to the agent class. The examples and visualizations provided should help you get started with building your own memory-augmented agents. +| 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 | -Happy coding! +--- +## 🚀 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: -# File: swarms\models\agent_and_models.md +### 📝 **Report Missing Features** -# Model Integration in Agents +- Create a [GitHub Issue](https://github.com/kyegomez/swarms/issues) to request new features -!!! info "About Model Integration" - Agents supports multiple model providers through LiteLLM integration, allowing you to easily switch between different language models. This document outlines the available providers and how to use them with agents. +- Describe your use case and business requirements -## Important Note on Model Names +- Our team will evaluate and prioritize based on enterprise demand -!!! warning "Required Format" - When specifying a model in an agent, you must use the format `provider/model_name`. For example: - ```python - "openai/gpt-4" - "anthropic/claude-3-opus-latest" - "cohere/command-r-plus" - ``` - This format ensures the agent knows which provider to use for the specified model. +### 📞 **Schedule a Consultation** -## Available Model Providers +- [Book a call with our enterprise team](https://cal.com/swarms/swarms-onboarding-session) for personalized guidance -### OpenAI +- Discuss your specific multi-agent architecture requirements -??? info "OpenAI Models" - - **Provider name**: `openai` - - **Available Models**: - - `gpt-4` - - `gpt-3.5-turbo` - - `gpt-4-turbo-preview` +- Get expert recommendations for your implementation strategy -### Anthropic -??? info "Anthropic Models" - - **Provider name**: `anthropic` - - **Available Models**: - - **Claude 3 Opus**: - - `claude-3-opus-latest` - - `claude-3-opus-20240229` - - **Claude 3 Sonnet**: - - `claude-3-sonnet-20240229` - - `claude-3-5-sonnet-latest` - - `claude-3-5-sonnet-20240620` - - `claude-3-7-sonnet-latest` - - `claude-3-7-sonnet-20250219` - - `claude-3-5-sonnet-20241022` - - **Claude 3 Haiku**: - - `claude-3-haiku-20240307` - - `claude-3-5-haiku-20241022` - - `claude-3-5-haiku-latest` - - **Legacy Models**: - - `claude-2` - - `claude-2.1` - - `claude-instant-1` - - `claude-instant-1.2` - -### Cohere -??? info "Cohere Models" - - **Provider name**: `cohere` - - **Available Models**: - - **Command**: - - `command` - - `command-r` - - `command-r-08-2024` - - `command-r7b-12-2024` - - **Command Light**: - - `command-light` - - **Command R Plus**: - - `command-r-plus` - - `command-r-plus-08-2024` - -### Google -??? info "Google Models" - - **Provider name**: `google` - - **Available Models**: - - `gemini-pro` - - `gemini-pro-vision` - -### Mistral -??? info "Mistral Models" - - **Provider name**: `mistral` - - **Available Models**: - - `mistral-tiny` - - `mistral-small` - - `mistral-medium` - -## Using Different Models In Your Agents - -To use a different model with your Swarms agent, specify the model name in the `model_name` parameter when initializing the Agent, using the provider/model_name format: +- Explore custom enterprise solutions and integrations -```python -from swarms import Agent +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. -# Using OpenAI's GPT-4 -agent = Agent( - agent_name="Research-Agent", - model_name="openai/gpt-4o", # Note the provider/model_name format - # ... other parameters -) -# Using Anthropic's Claude -agent = Agent( - agent_name="Analysis-Agent", - model_name="anthropic/claude-3-sonnet-20240229", # Note the provider/model_name format - # ... other parameters -) +-------------------------------------------------- -# Using Cohere's Command -agent = Agent( - agent_name="Text-Agent", - model_name="cohere/command-r-plus", # Note the provider/model_name format - # ... other parameters -) -``` +# File: swarms\framework\agents_explained.md -## Model Configuration +# An Analysis of Agents -When using different models, you can configure various parameters: +In the Swarms framework, agents are designed to perform tasks autonomously by leveraging large language models (LLMs), various tools, and long-term memory systems. This guide provides an extensive conceptual walkthrough of how an agent operates, detailing the sequence of actions it takes to complete a task and how it utilizes its internal components. -```python -agent = Agent( - agent_name="Custom-Agent", - model_name="openai/gpt-4", - temperature=0.7, # Controls randomness (0.0 to 1.0) - max_tokens=2000, # Maximum tokens in response - top_p=0.9, # Nucleus sampling parameter - frequency_penalty=0.0, # Reduces repetition - presence_penalty=0.0, # Encourages new topics - # ... other parameters -) -``` +#### Agent Components Overview +- **LLM (Large Language Model)**: The core component responsible for understanding and generating natural language. +- **Tools**: External functions and services that the agent can call to perform specific tasks, such as querying databases or interacting with APIs. +- **Long-term Memory**: Systems like ChromaDB or Pinecone that store and retrieve information over extended periods, enabling the agent to remember past interactions and contexts. -## Best Practices +#### Agent Workflow +The workflow of an agent can be divided into several stages: task initiation, initial LLM processing, tool usage, memory interaction, and final LLM processing. -### Model Selection -!!! tip "Choosing the Right Model" - - Choose models based on your specific use case - - Consider cost, performance, and feature requirements - - Test different models for your specific task +##### Stage 1: Task Initiation +- **Input**: The task or query that the agent needs to address. +- **Output**: A structured plan or approach for handling the task. -### Error Handling -!!! warning "Error Management" - - Implement proper error handling for model-specific errors - - Handle rate limits and API quotas appropriately +##### Stage 2: Initial LLM Processing +- **Input**: The task or query. +- **Process**: The LLM interprets the task, understanding the context and requirements. +- **Output**: An initial response or action plan. -### Cost Management -!!! note "Cost Considerations" - - Monitor token usage and costs - - Use appropriate model sizes for your needs +##### Stage 3: Tool Usage +- **Input**: The action plan or specific sub-tasks identified by the LLM. +- **Process**: The agent calls various tools to gather information, perform calculations, or interact with external systems. + - **Function Calling as Tools**: Tools are called as functions with specific inputs and outputs, enabling the agent to perform a wide range of tasks. +- **Output**: Data or results from the tools. -## Example Use Cases +##### Stage 4: Memory Interaction +- **Input**: Intermediate results and context from the tools. +- **Process**: The agent interacts with long-term memory systems to store new information and retrieve relevant past data. + - **RAG Systems (ChromaDB, Pinecone)**: These systems are used to enhance the agent’s responses by providing relevant historical data and context. +- **Output**: Enhanced context and data for final processing. -### 1. Complex Analysis (GPT-4) +##### Stage 5: Final LLM Processing +- **Input**: Comprehensive data and context from the tools and memory systems. +- **Process**: The LLM generates the final response or completes the task using the enriched data. +- **Output**: The final output or action taken by the agent. -```python -agent = Agent( - agent_name="Analysis-Agent", - model_name="openai/gpt-4", # Note the provider/model_name format - temperature=0.3, # Lower temperature for more focused responses - max_tokens=4000 -) -``` +### Detailed Workflow with Mermaid Diagrams -### 2. Creative Tasks (Claude) +#### Agent Components and Workflow -```python -agent = Agent( - agent_name="Creative-Agent", - model_name="anthropic/claude-3-sonnet-20240229", # Note the provider/model_name format - temperature=0.8, # Higher temperature for more creative responses - max_tokens=2000 -) +```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] ``` -### 3. Vision Tasks (Gemini) +### Explanation of Each Stage -```python -agent = Agent( - agent_name="Vision-Agent", - model_name="google/gemini-pro-vision", # Note the provider/model_name format - temperature=0.4, - max_tokens=1000 -) -``` +#### Stage 1: Task Initiation +- **Task**: The agent receives a task or query from an external source (e.g., a user query, a system trigger). +- **Objective**: To understand what needs to be done and prepare an initial approach. -## Troubleshooting +#### Stage 2: Initial LLM Processing +- **Interpretation**: The LLM processes the task to comprehend its context and requirements. +- **Planning**: The LLM generates an initial plan or identifies the sub-tasks required to complete the task. -!!! warning "Common Issues" - If you encounter issues with specific models: +#### Stage 3: Tool Usage +- **Function Calls**: The agent uses predefined functions (tools) to perform specific actions, such as querying a database or making API calls. +- **Tool Integration**: Each tool is called with specific parameters, and the results are collected for further processing. - 1. Verify your API keys are correctly set - 2. Check model availability in your region - 3. Ensure you have sufficient quota/credits - 4. Verify the model name is correct and supported +#### Stage 4: Memory Interaction +- **Long-term Memory**: Systems like ChromaDB and Pinecone store and retrieve long-term data, providing the agent with historical context and past interactions. +- **Retrieval-Augmented Generation (RAG)**: The agent uses RAG systems to enhance the current context with relevant past data, improving the quality and relevance of the final output. -## Additional Resources +#### Stage 5: Final LLM Processing +- **Enhanced Processing**: The LLM processes the enriched data and context provided by the tools and memory systems. +- **Final Output**: The LLM generates a comprehensive response or completes the task using the enhanced information. -- [LiteLLM Documentation](https://docs.litellm.ai/){target=_blank} -- [OpenAI API Documentation](https://platform.openai.com/docs/api-reference){target=_blank} -- [Anthropic API Documentation](https://docs.anthropic.com/claude/reference/getting-started-with-the-api){target=_blank} -- [Google AI Documentation](https://ai.google.dev/docs){target=_blank} +### Conclusion +The Swarms framework's agents are powerful units that combine LLMs, tools, and long-term memory systems to perform complex tasks efficiently. By leveraging function calling for tools and RAG systems like ChromaDB and Pinecone, agents can enhance their capabilities and deliver highly relevant and accurate results. This conceptual guide and walkthrough provide a detailed understanding of how agents operate within the Swarms framework, enabling the development of sophisticated and collaborative AI systems. -------------------------------------------------- -# File: swarms\models\anthropic.md +# File: swarms\framework\code_cleanliness.md -# **Documentation for the `Anthropic` Class** +# Code Cleanliness in Python: A Comprehensive Guide -## **Overview and Introduction** +Code cleanliness is an essential aspect of software development that ensures code is easy to read, understand, and maintain. Clean code leads to fewer bugs, easier debugging, and more efficient collaboration among developers. This blog article delves into the principles of writing clean Python code, emphasizing the use of type annotations, docstrings, and the Loguru logging library. We'll explore the importance of each component and provide practical examples to illustrate best practices. -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. +## Table of Contents +1. Introduction to Code Cleanliness +2. Importance of Type Annotations +3. Writing Effective Docstrings +4. Structuring Your Code +5. Error Handling and Logging with Loguru +6. Refactoring for Clean Code +7. Examples of Clean Code +8. Conclusion -### **Key Concepts and Terminology** +## 1. Introduction to Code Cleanliness -- **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** +Code cleanliness refers to the practice of writing code that is easy to read, understand, and maintain. Clean code follows consistent conventions and is organized logically, making it easier for developers to collaborate and for new team members to get up to speed quickly. -### `Anthropic` -```python -class Anthropic: - """Anthropic large language models.""" -``` +### Why Clean Code Matters -### Parameters: +1. **Readability**: Clean code is easy to read and understand, which reduces the time needed to grasp what the code does. +2. **Maintainability**: Clean code is easier to maintain and modify, reducing the risk of introducing bugs when making changes. +3. **Collaboration**: Clean code facilitates collaboration among team members, as everyone can easily understand and follow the codebase. +4. **Debugging**: Clean code makes it easier to identify and fix bugs, leading to more reliable software. -- `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. +## 2. Importance of Type Annotations -### **Methods and their Functionality** +Type annotations in Python provide a way to specify the types of variables, function arguments, and return values. They enhance code readability and help catch type-related errors early in the development process. -#### `_default_params(self) -> dict` +### Benefits of Type Annotations -- Provides the default parameters for calling the Anthropic API. - -- **Returns**: A dictionary containing the default parameters. +1. **Improved Readability**: Type annotations make it clear what types of values are expected, improving code readability. +2. **Error Detection**: Type annotations help catch type-related errors during development, reducing runtime errors. +3. **Better Tooling**: Many modern IDEs and editors use type annotations to provide better code completion and error checking. -#### `generate(self, prompt: str, stop: list[str] = None) -> str` +### Example of Type Annotations -- 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. +```python +from typing import List + +def calculate_average(numbers: List[float]) -> float: + """ + Calculates the average of a list of numbers. -#### `__call__(self, prompt: str, stop: list[str] = None) -> str` + Args: + numbers (List[float]): A list of numbers. -- 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. + Returns: + float: The average of the numbers. + """ + return sum(numbers) / len(numbers) +``` -## **Usage Examples** +In this example, the `calculate_average` function takes a list of floats as input and returns a float. The type annotations make it clear what types are expected and returned, enhancing readability and maintainability. -```python -# Import necessary modules and classes -from swarm_models import Anthropic +## 3. Writing Effective Docstrings -# Initialize an instance of the Anthropic class -model = Anthropic(anthropic_api_key="") +Docstrings are an essential part of writing clean code in Python. They provide inline documentation for modules, classes, methods, and functions. Effective docstrings improve code readability and make it easier for other developers to understand and use your code. -# Using the run method -completion_1 = model.run("What is the capital of France?") -print(completion_1) +### Benefits of Docstrings -# Using the __call__ method -completion_2 = model("How far is the moon from the earth?", stop=["miles", "km"]) -print(completion_2) -``` +1. **Documentation**: Docstrings serve as inline documentation, making it easier to understand the purpose and usage of code. +2. **Consistency**: Well-written docstrings ensure consistent documentation across the codebase. +3. **Ease of Use**: Docstrings make it easier for developers to use and understand code without having to read through the implementation details. -## **Mathematical Formula** +### Example of Effective Docstrings -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: +```python +def calculate_factorial(n: int) -> int: + """ + Calculates the factorial of a given non-negative integer. -\[ P(t) = \frac{e^{l_t}}{\sum_{i} e^{l_i}} \] + Args: + n (int): The non-negative integer to calculate the factorial of. -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. + Returns: + int: The factorial of the given number. -The temperature, top-k, and top-p parameters are further used to modulate the probabilities. + Raises: + ValueError: If the input is a negative integer. + """ + if n < 0: + raise ValueError("Input must be a non-negative integer.") + factorial = 1 + for i in range(1, n + 1): + factorial *= i + return factorial +``` -## **Additional Information and Tips** +In this example, the docstring clearly explains the purpose of the `calculate_factorial` function, its arguments, return value, and the exception it may raise. -- 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. +## 4. Structuring Your Code -## **References and Resources** +Proper code structure is crucial for code cleanliness. A well-structured codebase is easier to navigate, understand, and maintain. Here are some best practices for structuring your Python code: -- [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. +### Organizing Code into Modules and Packages --------------------------------------------------- +Organize your code into modules and packages to group related functionality together. This makes it easier to find and manage code. -# File: swarms\models\base_llm.md +```python +# project/ +# ├── main.py +# ├── utils/ +# │ ├── __init__.py +# │ ├── file_utils.py +# │ └── math_utils.py +# └── models/ +# ├── __init__.py +# ├── user.py +# └── product.py +``` -# Language Model Interface Documentation +### Using Functions and Classes -## Table of Contents +Break down your code into small, reusable functions and classes. This makes your code more modular and easier to test. -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) +```python +class User: + def __init__(self, name: str, age: int): + """ + Initializes a new user. ---- + Args: + name (str): The name of the user. + age (int): The age of the user. + """ + self.name = name + self.age = age -## 1. Introduction + def greet(self) -> str: + """ + Greets the user. + + Returns: + str: A greeting message. + """ + return f"Hello, {self.name}!" +``` -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. +### Keeping Functions Small -## 2. Abstract Language Model +Functions should do one thing and do it well. Keep functions small and focused on a single task. -### Initialization +```python +def save_user(user: User, filename: str) -> None: + """ + Saves user data to a file. -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: + Args: + user (User): The user object to save. + filename (str): The name of the file to save the user data to. + """ + with open(filename, 'w') as file: + file.write(f"{user.name},{user.age}") +``` -| 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 | +## 5. Error Handling and Logging with Loguru -### Attributes +Effective error handling and logging are critical components of clean code. They help you manage and diagnose issues that arise during the execution of your code. -- `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. +### Error Handling Best Practices -### Methods +1. **Use Specific Exceptions**: Catch specific exceptions rather than using a generic `except` clause. +2. **Provide Meaningful Messages**: When raising exceptions, provide meaningful error messages to help diagnose the issue. +3. **Clean Up Resources**: Use `finally` blocks or context managers to ensure that resources are properly cleaned up. -The `BaseLLM` class defines several methods for working with language models: +### Example of Error Handling -- `run(task: Optional[str] = None, *args, **kwargs) -> str`: Generate text using the language model. This method is abstract and must be implemented by subclasses. +```python +def divide_numbers(numerator: float, denominator: float) -> float: + """ + Divides the numerator by the denominator. -- `arun(task: Optional[str] = None, *args, **kwargs)`: An asynchronous version of `run` for concurrent text generation. + Args: + numerator (float): The number to be divided. + denominator (float): The number to divide by. -- `batch_run(tasks: List[str], *args, **kwargs)`: Generate text for a batch of tasks. + Returns: + float: The result of the division. -- `abatch_run(tasks: List[str], *args, **kwargs)`: An asynchronous version of `batch_run` for concurrent batch generation. + Raises: + ValueError: If the denominator is zero. + """ + if denominator == 0: + raise ValueError("The denominator cannot be zero.") + return numerator / denominator +``` -- `chat(task: str, history: str = "") -> str`: Conduct a chat with the model, providing a conversation history. +### Logging with Loguru -- `__call__(task: str) -> str`: Call the model to generate text. +Loguru is a powerful logging library for Python that makes logging simple and enjoyable. It provides a clean and easy-to-use API for logging messages with different severity levels. -- `_tokens_per_second() -> float`: Calculate tokens generated per second. +#### Installing Loguru -- `_num_tokens(text: str) -> int`: Calculate the number of tokens in a text. +```bash +pip install loguru +``` -- `_time_for_generation(task: str) -> float`: Measure the time taken for text generation. +#### Basic Usage of Loguru -- `generate_summary(text: str) -> str`: Generate a summary of the provided text. +```python +from loguru import logger -- `set_temperature(value: float)`: Set the temperature parameter. +logger.debug("This is a debug message") +logger.info("This is an info message") +logger.warning("This is a warning message") +logger.error("This is an error message") +logger.critical("This is a critical message") +``` -- `set_max_tokens(value: int)`: Set the maximum number of tokens. +### Example of Logging in a Function -- `clear_history()`: Clear the conversation history. +```python +from loguru import logger -- `enable_logging(log_file: str = "model.log")`: Initialize logging for the model. +def fetch_data(url: str) -> str: + """ + Fetches data from a given URL and returns it as a string. -- `log_event(message: str)`: Log an event. + Args: + url (str): The URL to fetch data from. -- `save_checkpoint(checkpoint_dir: str = "checkpoints")`: Save the model state as a checkpoint. + Returns: + str: The data fetched from the URL. -- `load_checkpoint(checkpoint_path: str)`: Load the model state from a checkpoint. + Raises: + requests.exceptions.RequestException: If there is an error with the request. + """ + try: + logger.info(f"Fetching data from {url}") + response = requests.get(url) + response.raise_for_status() + logger.info("Data fetched successfully") + return response.text + except requests.exceptions.RequestException as e: + logger.error(f"Error fetching data: {e}") + raise +``` -- `toggle_creative_mode(enable: bool)`: Toggle creative mode for the model. +In this example, Loguru is used to log messages at different severity levels. The `fetch_data` function logs informational messages when fetching data and logs an error message if an exception is raised. -- `track_resource_utilization()`: Track and report resource utilization. +## 6. Refactoring for Clean Code -- ` +Refactoring is the process of restructuring existing code without changing its external behavior. It is an essential practice for maintaining clean code. Refactoring helps improve code readability, reduce complexity, and eliminate redundancy. -get_generation_time() -> float`: Get the time taken for text generation. +### Identifying Code Smells -- `set_max_length(max_length: int)`: Set the maximum length of generated sequences. +Code smells are indicators of potential issues in the code that may require refactoring. Common code smells include: +1. **Long Methods**: Methods that are too long and do too many things. +2. **Duplicated Code**: Code that is duplicated in multiple places. +3. **Large Classes**: Classes that have too many responsibilities. +4. **Poor Naming**: Variables, functions, or classes with unclear or misleading names. -- `set_model_name(model_name: str)`: Set the model name. +### Refactoring Techniques -- `set_frequency_penalty(frequency_penalty: float)`: Set the frequency penalty parameter. +1. **Extract Method**: Break down long methods into smaller, more focused methods. +2. **Rename Variables**: Use meaningful names for variables, functions, and classes. +3. **Remove Duplicated Code**: Consolidate duplicated code into a single location. +4. **Simplify Conditional Expressions**: Simplify complex conditional expressions for -- `set_presence_penalty(presence_penalty: float)`: Set the presence penalty parameter. + better readability. -- `set_stop_token(stop_token: str)`: Set the stop token. +### Example of Refactoring -- `set_length_penalty(length_penalty: float)`: Set the length penalty parameter. +Before refactoring: +```python +def process_data(data: List[int]) -> int: + total = 0 + for value in data: + if value > 0: + total += value + return total +``` -- `set_role(role: str)`: Set the role of the model. +After refactoring: +```python +def filter_positive_values(data: List[int]) -> List[int]: + """ + Filters the positive values from the input data. -- `set_top_k(top_k: int)`: Set the top-k parameter. + Args: + data (List[int]): The input data. -- `set_top_p(top_p: float)`: Set the top-p parameter. + Returns: + List[int]: A list of positive values. + """ + return [value for value in data if value > 0] -- `set_num_beams(num_beams: int)`: Set the number of beams. +def sum_values(values: List[int]) -> int: + """ + Sums the values in the input list. -- `set_do_sample(do_sample: bool)`: Set whether to use sampling. + Args: + values (List[int]): A list of values to sum. -- `set_early_stopping(early_stopping: bool)`: Set whether to use early stopping. + Returns: + int: The sum of the values. + """ + return sum(values) -- `set_seed(seed: int)`: Set the random seed. +def process_data(data: List[int]) -> int: + """ + Processes the data by filtering positive values and summing them. -- `set_device(device: str)`: Set the device for model execution. + Args: + data (List[int]): The input data. -## 3. Implementation + Returns: + int: The sum of the positive values. + """ + positive_values = filter_positive_values(data) + return sum_values(positive_values) +``` -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. +In this example, the `process_data` function is refactored into smaller, more focused functions. This improves readability and maintainability. -## 4. Usage Examples +## 7. Examples of Clean Code -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 1: Reading a File ```python -# Import the BaseLLM class -from swarm_models import BaseLLM +def read_file(file_path: str) -> str: + """ + Reads the content of a file and returns it as a string. -# 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", -) + Args: + file_path (str): The path to the file to read. -# Generate text for a task -task = "Translate the following English text to French: 'Hello, world.'" -generated_text = language_model.run(task) + Returns: + str: The content of the file. -# Print the generated text -print(generated_text) + Raises: + FileNotFoundError: If the file does not exist. + IOError: If there is an error reading the file. + """ + try: + with open(file_path, 'r') as file: + return file.read() + except FileNotFoundError as e: + logger.error(f"File not found: {file_path}") + raise + except IOError as e: + logger.error(f"Error reading file: {file_path}") + raise ``` -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. - -## 5. Additional Features - -The `BaseLLM` interface provides additional features for customization and control: +### Example 2: Fetching Data from a URL -- `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. +```python +import requests +from loguru import logger -These features enhance the flexibility and utility of the interface in various applications, including chatbots, language translation, and content generation. +def fetch_data(url: str) -> str: + """ + Fetches data from a given URL and returns it as a string. -## 6. Performance Metrics + Args: + url (str): The URL to fetch data from. -The `BaseLLM` class offers methods for tracking performance metrics: + Returns: + str: The data fetched from the URL. -- `_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. + Raises: + requests.exceptions.RequestException: If there is an error with the request. + """ + try: + logger.info(f"Fetching data from {url}") + response = requests.get(url) + response.raise_for_status() + logger.info("Data fetched successfully") + return response.text + except requests.exceptions.RequestException as e: + logger.error(f"Error fetching data: {e}") + raise +``` -These metrics help assess the efficiency and speed of text generation, enabling optimizations as needed. +### Example 3: Calculating Factorial -## 7. Logging and Checkpoints +```python +def calculate_factorial(n: int) -> int: + """ + Calculates the factorial of a given non-negative integer. -Logging and checkpointing are crucial for tracking model behavior and ensuring reproducibility: + Args: + n (int): The non-negative integer to calculate the factorial of. -- `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. + Returns: + int: The factorial of the given number. -These capabilities aid in debugging, monitoring, and resuming model experiments. + Raises: + ValueError: If the input is a negative integer. + """ + if n < 0: + raise ValueError("Input must be a non-negative integer.") + factorial = 1 + for i in range(1, n + 1): + factorial *= i + return factorial +``` -## 8. Resource Utilization Tracking +## 8. Conclusion -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. +Writing clean code in Python is crucial for developing maintainable, readable, and error-free software. By using type annotations, writing effective docstrings, structuring your code properly, and leveraging logging with Loguru, you can significantly improve the quality of your codebase. -## 9. Conclusion +Remember to refactor your code regularly to eliminate code smells and improve readability. Clean code not only makes your life as a developer easier but also enhances collaboration and reduces the likelihood of bugs. -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. +By following the principles and best practices outlined in this article, you'll be well on your way to writing clean, maintainable Python code. -------------------------------------------------- -# File: swarms\models\base_multimodal_model.md +# File: swarms\framework\concept.md -# `BaseMultiModalModel` Documentation +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. -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. +### Swarms Framework Overview -## Table of Contents +#### 1. **Models** +Models are the core component of the Swarms framework, representing the neural networks and machine learning models used to perform various tasks. These can be Large Language Models (LLMs), vision models, or any other AI models. -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) +#### 2. **Agents** +Agents are autonomous units that use models to perform specific tasks. In the Swarms framework, agents can leverage tools and interact with RAG systems. -## 1. Introduction +- **LLMs with Tools**: These agents use large language models along with tools like databases, APIs, and external knowledge sources to enhance their capabilities. +- **RAG Systems**: These systems combine retrieval mechanisms with generative models to produce more accurate and contextually relevant outputs. -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. +#### 3. **Swarm Systems** +Swarm systems involve multiple agents working collaboratively to achieve complex tasks. These systems coordinate and communicate among agents to ensure efficient and effective task execution. -## 2. Installation +### Mermaid Diagrams -To install swarms, you can use pip: +#### Models -```bash -pip install swarms +```mermaid +graph TD + A[Model] -->|Uses| B[Data] + A -->|Trains| C[Algorithm] + A -->|Outputs| D[Predictions] ``` -## 3. Getting Started +#### Agents: LLMs with Tools and RAG Systems -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. +```mermaid +graph TD + A[Agent] -->|Uses| B[LLM] + A -->|Interacts with| C[Tool] + C -->|Provides Data to| B + A -->|Queries| D[RAG System] + D -->|Retrieves Information from| E[Database] + D -->|Generates Responses with| F[Generative Model] +``` -```python -from swarm_models import BaseMultiModalModel +#### Swarm Systems -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, -) +```mermaid +graph TD + A[Swarm System] + A -->|Coordinates| B[Agent 1] + A -->|Coordinates| C[Agent 2] + A -->|Coordinates| D[Agent 3] + B -->|Communicates with| C + C -->|Communicates with| D + D -->|Communicates with| B + B -->|Performs Task| E[Task 1] + C -->|Performs Task| F[Task 2] + D -->|Performs Task| G[Task 3] + E -->|Reports to| A + F -->|Reports to| A + G -->|Reports to| A ``` -You can customize the initialization parameters based on your model's requirements. +### Conceptualization + +1. **Models**: The basic building blocks trained on specific datasets to perform tasks. +2. **Agents**: Intelligent entities that utilize models and tools to perform actions. LLM agents can use additional tools to enhance their capabilities. +3. **RAG Systems**: Enhance agents by combining retrieval mechanisms (to fetch relevant information) with generative models (to create contextually relevant responses). +4. **Swarm Systems**: Complex systems where multiple agents collaborate, communicate, and coordinate to perform complex, multi-step tasks efficiently. -## 4. BaseMultiModalModel Class +### Summary +The Swarms framework leverages models, agents, tools, RAG systems, and swarm systems to create a robust, collaborative environment for executing complex AI tasks. By coordinating multiple agents and enhancing their capabilities with tools and retrieval-augmented generation, Swarms can handle sophisticated and multi-faceted applications effectively. -### Initialization +-------------------------------------------------- -The `BaseMultiModalModel` class is initialized with several parameters that control its behavior. Here's a breakdown of the initialization parameters: +# File: swarms\framework\index.md -| 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 | +## Swarms Framework Conceptual Breakdown -### Methods +The `swarms` framework is a sophisticated structure designed to orchestrate the collaborative work of multiple agents in a hierarchical manner. This breakdown provides a conceptual and visual representation of the framework, highlighting the interactions between models, tools, memory, agents, and swarms. -The `BaseMultiModalModel` class defines various methods for running multimodal models and managing interactions: +### Hierarchical Structure -- `run(task: str, img: str) -> str`: Run the multimodal model with a text task and an image URL to generate a response. +The framework can be visualized as a multi-layered hierarchy: -- `arun(task: str, img: str) -> str`: Run the multimodal model asynchronously with a text task and an image URL to generate a response. +1. **Models, Tools, Memory**: These form the foundational components that agents utilize to perform tasks. +2. **Agents**: Individual entities that encapsulate specific functionalities, utilizing models, tools, and memory. +3. **Swarm**: A collection of multiple agents working together in a coordinated manner. +4. **Structs**: High-level structures that organize and manage swarms, enabling complex workflows and interactions. -- `get_img_from_web(img: str) -> Image`: Fetch an image from a URL and return it as a PIL Image. +### Visual Representation -- `encode_img(img: str) -> str`: Encode an image to base64 format. +Below are visual graphs illustrating the hierarchical and tree structure of the `swarms` framework. -- `get_img(img: str) -> Image`: Load an image from the local file system and return it as a PIL Image. +#### 1. Foundational Components: Models, Tools, Memory -- `clear_chat_history()`: Clear the chat history maintained by the model. +![Diagram](assets/img/agent_def.png) -- `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. +#### 2. Agents and Their Interactions -- `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. +```mermaid +graph TD; + Agents --> Swarm + subgraph Agents_Collection + Agent1 + Agent2 + Agent3 + end + subgraph Individual_Agents + Agent1 --> Models + Agent1 --> Tools + Agent1 --> Memory + Agent2 --> Models + Agent2 --> Tools + Agent2 --> Memory + Agent3 --> Models + Agent3 --> Tools + Agent3 --> Memory + end +``` -- `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. +#### 3. Multiple Agents Form a Swarm -- `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. +```mermaid +graph TD; + Swarm1 --> Struct + Swarm2 --> Struct + Swarm3 --> Struct + subgraph Swarms_Collection + Swarm1 + Swarm2 + Swarm3 + end + subgraph Individual_Swarms + Swarm1 --> Agent1 + Swarm1 --> Agent2 + Swarm1 --> Agent3 + Swarm2 --> Agent4 + Swarm2 --> Agent5 + Swarm2 --> Agent6 + Swarm3 --> Agent7 + Swarm3 --> Agent8 + Swarm3 --> Agent9 + end +``` -- `unique_chat_history() -> List[str]`: Get the unique chat history stored by the model. +#### 4. Structs Organizing Multiple Swarms -- `run_with_retries(task: str, img: str) -> str`: Run the model with retries in case of an error. +```mermaid +graph TD; + Struct --> Swarms_Collection + subgraph High_Level_Structs + Struct1 + Struct2 + Struct3 + end + subgraph Struct1 + Swarm1 + Swarm2 + end + subgraph Struct2 + Swarm3 + end + subgraph Struct3 + Swarm4 + Swarm5 + end +``` -- `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. +### Directory Breakdown -- `_tokens_per_second() -> float`: Calculate the tokens generated per second during text generation. +The directory structure of the `swarms` framework is organized to support its hierarchical architecture: -- `_time_for_generation(task: str) -> float`: Measure the time taken for text generation for a specific task. +```sh +swarms/ +├── agents/ +├── artifacts/ +├── marketplace/ +├── memory/ +├── models/ +├── prompts/ +├── schemas/ +├── structs/ +├── telemetry/ +├── tools/ +├── utils/ +└── __init__.py +``` -- `generate_summary(text: str) -> str`: Generate a summary of the provided text. +### Summary -- `set_temperature(value: float)`: Set the temperature parameter for controlling randomness in text generation. +The `swarms` framework is designed to facilitate complex multi-agent interactions through a structured and layered approach. By leveraging foundational components like models, tools, and memory, individual agents are empowered to perform specialized tasks. These agents are then coordinated within swarms to achieve collective goals, and swarms are managed within high-level structs to orchestrate sophisticated workflows. -- `set_max_tokens(value: int)`: Set the maximum number of tokens allowed in generated responses. +This hierarchical design ensures scalability, flexibility, and robustness, making the `swarms` framework a powerful tool for various applications in AI, data analysis, optimization, and beyond. -- `get_generation_time() -> float`: Get the time taken for text generation for the last task. +-------------------------------------------------- -- `get_chat_history() -> List[str]`: Get the chat history, including all interactions. +# File: swarms\framework\reference.md -- `get_unique_chat_history() -> List[str]`: Get the unique chat history, removing duplicate interactions. +# API Reference Documentation -- `get_chat_history_length() -> int`: Get the length of the chat history. -- `get_unique_chat_history_length() -> int`: Get the length of the unique chat history. -- `get_chat_history_tokens() -> int`: Get the total number of tokens in the chat history. +### `swarms.__init__` -- `print_beautiful(content: str, color: str = 'cyan')`: Print content beautifully using colored text. +**Description**: +This module initializes the Swarms package by concurrently executing the bootup process and activating Sentry for telemetry. It imports various components from other modules within the Swarms package. -- `stream(content: str)`: Stream the content, printing it character by character. +**Imports**: +- `concurrent.futures`: A module that provides a high-level interface for asynchronously executing callables. -- `meta_prompt() -> str`: Get the meta prompt that provides guidance for including image labels in responses. +- `swarms.telemetry.bootup`: Contains the `bootup` function for initializing telemetry. -## 5. Usage Examples +- `swarms.telemetry.sentry_active`: Contains the `activate_sentry` function to enable Sentry for error tracking. -Let's explore some usage examples of the MultiModalAI library: +- Other modules from the Swarms package are imported for use, including agents, artifacts, prompts, structs, telemetry, tools, utils, and schemas. -### Example 1: Running - the Model +**Concurrent Execution**: +The module uses `ThreadPoolExecutor` to run the `bootup` and `activate_sentry` functions concurrently. ```python -# Import the library -from swarm_models import BaseMultiModalModel +import concurrent.futures +from swarms.telemetry.bootup import bootup # noqa: E402, F403 +from swarms.telemetry.sentry_active import activate_sentry -# Create an instance of the model -model = BaseMultiModalModel( - model_name="your_model_name", - temperature=0.5, - max_tokens=500, - device="cuda", -) +# Use ThreadPoolExecutor to run bootup and activate_sentry concurrently +with concurrent.futures.ThreadPoolExecutor(max_workers=2) as executor: + executor.submit(bootup) + executor.submit(activate_sentry) -# 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) +from swarms.agents import * # noqa: E402, F403 +from swarms.artifacts import * # noqa: E402, F403 +from swarms.prompts import * # noqa: E402, F403 +from swarms.structs import * # noqa: E402, F403 +from swarms.telemetry import * # noqa: E402, F403 +from swarms.tools import * # noqa: E402, F403 +from swarms.utils import * # noqa: E402, F403 +from swarms.schemas import * # noqa: E402, F403 ``` -### Example 2: Running Multiple Tasks Concurrently +**Note**: There are no documentable functions or classes within this module itself, as it primarily serves to execute initial setup tasks and import other modules. -```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, - 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"] -# Run the model on multiple tasks concurrently -responses = model.run_many(tasks, images) -for response in responses: - print(response) -``` +### `swarms.artifacts.base_artifact` -### Example 3: Running the Model Asynchronously +**Description**: +This module defines the `BaseArtifact` abstract base class for representing artifacts in the system. It provides methods to convert artifact values to various formats and enforces the implementation of an addition method for subclasses. -```python -# Import the library -from swarm_models import BaseMultiModalModel +**Imports**: +- `json`: A module for parsing JSON data. -# Create an instance of the model -model = BaseMultiModalModel( - model_name="your_model_name", - temperature=0.5, - max_tokens=500, - device="cuda", -) +- `uuid`: A module for generating unique identifiers. -# 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"), -] +- `ABC`, `abstractmethod`: Tools from the `abc` module to define abstract base classes. -# Run the model on multiple tasks asynchronously -responses = model.run_batch_async(tasks_images) -for response in responses: - print(response) -``` +- `dataclass`: A decorator for creating data classes. -### Example 4: Inheriting `BaseMultiModalModel` for it's prebuilt classes -```python -from swarm_models import BaseMultiModalModel +- `Any`: A type hint for any data type. -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 +### `BaseArtifact` +**Description**: +An abstract base class for artifacts that includes common attributes and methods for handling artifact values. - def __call__(self, text, img): - # Implement the multimodal model logic here - # You can use self.custom_parameter and other inherited attributes - pass +**Attributes**: +- `id` (`str`): A unique identifier for the artifact, generated if not provided. - def generate_summary(self, text): - # Implement the summary generation logic using your model - # You can use self.custom_parameter and other inherited attributes - pass +- `name` (`str`): The name of the artifact. If not provided, it defaults to the artifact's ID. +- `value` (`Any`): The value associated with the artifact. -# 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", -) -# Run your custom model -response = custom_model.run( - "Generate a summary of this text", "https://www.example.com/image.jpg" -) -print(response) +**Methods**: -# Generate a summary using your custom model -summary = custom_model.generate_summary("This is a sample text to summarize.") -print(summary) -``` +- `__post_init__(self) -> None` -In the code above: + - **Description**: Initializes the artifact, setting the `id` and `name` attributes if they are not provided. + + - **Parameters**: None. + + - **Return**: None. + -1. We define a `CustomMultiModalModel` class that inherits from `BaseMultiModalModel`. +- `value_to_bytes(cls, value: Any) -> bytes` -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`. + - **Description**: Converts the given value to bytes. + + - **Parameters**: + + - `value` (`Any`): The value to convert. + + - **Return**: + + - (`bytes`): The value converted to bytes. + -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. +- `value_to_dict(cls, value: Any) -> dict` -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. + - **Description**: Converts the given value to a dictionary. + + - **Parameters**: + + - `value` (`Any`): The value to convert. + + - **Return**: + + - (`dict`): The value converted to a dictionary. + -5. We create an instance of our custom model, passing the required parameters, including the custom parameter. +- `to_text(self) -> str` -6. We demonstrate how to run the custom model and generate a summary using it. + - **Description**: Converts the artifact's value to a text representation. + + - **Parameters**: None. + + - **Return**: + + - (`str`): The string representation of the artifact's value. + -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. +- `__str__(self) -> str` -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. + - **Description**: Returns a string representation of the artifact. + + - **Parameters**: None. + + - **Return**: + + - (`str`): The string representation of the artifact. + -## 6. Additional Tips +- `__bool__(self) -> bool` -Here are some additional tips and considerations for using MultiModalAI effectively: + - **Description**: Returns the boolean value of the artifact based on its value. + + - **Parameters**: None. + + - **Return**: + + - (`bool`): The boolean value of the artifact. + -- **Custom Models**: You can create your own multimodal models and inherit from the `BaseMultiModalModel` class to integrate them with this library. +- `__len__(self) -> int` -- **Retries**: In cases where text generation might fail due to various reasons (e.g., server issues), using methods with retries can be helpful. + - **Description**: Returns the length of the artifact's value. + + - **Parameters**: None. + + - **Return**: + + - (`int`): The length of the artifact's value. + -- **Monitoring**: You can monitor the performance of your model using methods like `_tokens_per_second()` and `_time_for_generation()`. +- `__add__(self, other: BaseArtifact) -> BaseArtifact` -- **Chat History**: The library maintains a chat history, allowing you to keep track of interactions. + - **Description**: Abstract method for adding two artifacts together. Must be implemented by subclasses. + + - **Parameters**: + + - `other` (`BaseArtifact`): The other artifact to add. + + - **Return**: + + - (`BaseArtifact`): The result of adding the two artifacts. + -- **Streaming**: The `stream()` method can be useful for displaying output character by character, which can be helpful for certain applications. +**Example**: +```python +from swarms.artifacts.base_artifact import BaseArtifact -## 7. References and Resources +class MyArtifact(BaseArtifact): + def __add__(self, other: BaseArtifact) -> BaseArtifact: + + return MyArtifact(id=self.id, name=self.name, value=self.value + other.value) -Here are some references and resources that you may find useful for working with multimodal models: +artifact1 = MyArtifact(id="123", name="Artifact1", value=10) +artifact2 = MyArtifact(id="456", name="Artifact2", value=20) +result = artifact1 + artifact2 +print(result) # Output: MyArtifact with the combined value +``` -- [Hugging Face Transformers Library](https://huggingface.co/transformers/): A library for working with various transformer-based models. -- [PIL (Python Imaging Library)](https://pillow.readthedocs.io/en/stable/): Documentation for working with images in Python using the Pillow library. -- [Concurrent Programming in Python](https://docs.python.org/3/library/concurrent.futures.html): Official Python documentation for concurrent programming. -- [Requests Library Documentation](https://docs.python-requests.org/en/latest/): Documentation for the Requests library, which is used for making HTTP requests. +### `swarms.artifacts.text_artifact` -- [Base64 Encoding in Python](https://docs.python.org/3/library/base64.html): Official Python documentation for base64 encoding and decoding. +**Description**: +This module defines the `TextArtifact` class, which represents a text-based artifact. It extends the `BaseArtifact` class and includes attributes and methods specific to +handling text values, including encoding options, embedding generation, and token counting. -This concludes the documentation for the MultiModalAI library. You can now explore the library further and integrate it with your multimodal AI projects. +**Imports**: +- `dataclass`, `field`: Decorators and functions from the `dataclasses` module for creating data classes. --------------------------------------------------- +- `Callable`: A type hint indicating a callable object from the `typing` module. -# File: swarms\models\cerebras.md +- `BaseArtifact`: The abstract base class for artifacts, imported from `swarms.artifacts.base_artifact`. -# Using Cerebras LLaMA with Swarms -This guide demonstrates how to create and use an AI agent powered by the Cerebras LLaMA 3 70B model using the Swarms framework. +### `TextArtifact` +**Description**: +Represents a text artifact with additional functionality for handling text values, encoding, and embeddings. -## Prerequisites +**Attributes**: +- `value` (`str`): The text value of the artifact. -- Python 3.7+ +- `encoding` (`str`, optional): The encoding of the text (default is "utf-8"). -- Swarms library installed (`pip install swarms`) +- `encoding_error_handler` (`str`, optional): The error handler for encoding errors (default is "strict"). -- Set your ENV key `CEREBRAS_API_KEY` +- `tokenizer` (`Callable`, optional): A callable for tokenizing the text value. -## Step-by-Step Guide +- `_embedding` (`list[float]`): The embedding of the text artifact (default is an empty list). -### 1. Import Required Module -```python -from swarms.structs.agent import Agent -``` +**Properties**: +- `embedding` (`Optional[list[float]]`): Returns the embedding of the text artifact if available; otherwise, returns `None`. -This imports the `Agent` class from Swarms, which is the core component for creating AI agents. -### 2. Create an Agent Instance +**Methods**: -```python -agent = Agent( - agent_name="Financial-Analysis-Agent", - agent_description="Personal finance advisor agent", - max_loops=4, - model_name="cerebras/llama3-70b-instruct", - dynamic_temperature_enabled=True, - interactive=False, - output_type="all", -) -``` +- `__add__(self, other: BaseArtifact) -> TextArtifact` -Let's break down each parameter: + - **Description**: Concatenates the text value of this artifact with the text value of another artifact. + + - **Parameters**: + + - `other` (`BaseArtifact`): The other artifact to concatenate with. + + - **Return**: + + - (`TextArtifact`): A new `TextArtifact` instance with the concatenated value. + -- `agent_name`: A descriptive name for your agent (here, "Financial-Analysis-Agent") +- `__bool__(self) -> bool` -- `agent_description`: A brief description of the agent's purpose + - **Description**: Checks if the text value of the artifact is non-empty. + + - **Parameters**: None. + + - **Return**: + + - (`bool`): `True` if the text value is non-empty; otherwise, `False`. + -- `max_loops`: Maximum number of interaction loops the agent can perform (set to 4) +- `generate_embedding(self, model) -> list[float] | None` -- `model_name`: Specifies the Cerebras LLaMA 3 70B model to use + - **Description**: Generates the embedding of the text artifact using a given embedding model. + + - **Parameters**: + + - `model`: An embedding model that provides the `embed_string` method. + + - **Return**: + + - (`list[float] | None`): The generated embedding as a list of floats, or `None` if the embedding could not be generated. + -- `dynamic_temperature_enabled`: Enables dynamic adjustment of temperature for varied responses +- `token_count(self) -> int` -- `interactive`: When False, runs without requiring user interaction + - **Description**: Counts the number of tokens in the text artifact using a specified tokenizer. + + - **Parameters**: None. + + - **Return**: + + - (`int`): The number of tokens in the text value. + -- `output_type`: Set to "all" to return complete response information +- `to_bytes(self) -> bytes` -### 3. Run the Agent + - **Description**: Converts the text value of the artifact to bytes using the specified encoding and error handler. + + - **Parameters**: None. + + - **Return**: + + - (`bytes`): The text value encoded as bytes. + +**Example**: ```python -agent.run("Conduct an analysis of the best real undervalued ETFs") -``` +from swarms.artifacts.text_artifact import TextArtifact -This command: +# Create a TextArtifact instance +text_artifact = TextArtifact(value="Hello, World!") -1. Activates the agent +# Generate embedding (assuming an appropriate model is provided) +# embedding = text_artifact.generate_embedding(model) -2. Processes the given prompt about ETF analysis +# Count tokens in the text artifact +token_count = text_artifact.token_count() -3. Returns the analysis based on the model's knowledge +# Convert to bytes +bytes_value = text_artifact.to_bytes() -## Notes +print(text_artifact) # Output: Hello, World! +print(token_count) # Output: Number of tokens +print(bytes_value) # Output: b'Hello, World!' +``` -- The Cerebras LLaMA 3 70B model is a powerful language model suitable for complex analysis tasks -- The agent can be customized further with additional parameters -- The `max_loops=4` setting prevents infinite loops while allowing sufficient processing depth -- Setting `interactive=False` makes the agent run autonomously without user intervention +### `swarms.artifacts.main_artifact` -## Example Output +**Description**: +This module defines the `Artifact` class, which represents a file artifact with versioning capabilities. It allows for the creation, editing, saving, loading, and exporting of file artifacts, as well as managing their version history. The module also includes a `FileVersion` class to encapsulate the details of each version of the artifact. -The agent will provide a detailed analysis of undervalued ETFs, including: +**Imports**: +- `time`: A module for time-related functions. -- Market analysis +- `logger`: A logging utility from `swarms.utils.loguru_logger`. -- Performance metrics +- `os`: A module providing a way of using operating system-dependent functionality. -- Risk assessment +- `json`: A module for parsing JSON data. -- Investment recommendations +- `List`, `Union`, `Dict`, `Any`: Type hints from the `typing` module. -Note: Actual output will vary based on current market conditions and the model's training data. +- `BaseModel`, `Field`, `validator`: Tools from the `pydantic` module for data validation and settings management. --------------------------------------------------- +- `datetime`: A module for manipulating dates and times. -# File: swarms\models\custom_model.md -# How to Create A Custom Language Model +### `FileVersion` +**Description**: +Represents a version of a file with its content and timestamp. -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. +**Attributes**: +- `version_number` (`int`): The version number of the file. -### Prerequisites +- `content` (`str`): The content of the file version. -Before you begin, ensure that you have: +- `timestamp` (`str`): The timestamp of the file version, formatted as "YYYY-MM-DD HH:MM:SS". -- 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`. -### Step-by-Step Guide +**Methods**: -#### Step 1: Understand `BaseLLM` +- `__str__(self) -> str` -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. + - **Description**: Returns a string representation of the file version. + + - **Parameters**: None. + + - **Return**: + + - (`str`): A formatted string containing the version number, timestamp, and content. + -#### Step 2: Create a New Class +### `Artifact` +**Description**: +Represents a file artifact with attributes to manage its content and version history. -Start by defining a new class that inherits from `BaseLLM`. This class will implement the required methods defined in the abstract base class. +**Attributes**: +- `file_path` (`str`): The path to the file. -```python -from swarms import BaseLLM +- `file_type` (`str`): The type of the file (e.g., ".txt"). -class vLLMLM(BaseLLM): - pass -``` +- `contents` (`str`): The contents of the file. -#### Step 3: Initialize Your Class +- `versions` (`List[FileVersion]`): The list of file versions. -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. +- `edit_count` (`int`): The number of times the file has been edited. -```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 -``` -#### Step 4: Implement Required Methods +**Methods**: -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. +- `validate_file_type(cls, v, values) -> str` -```python -class vLLMLM(BaseLLM): - # ... existing code ... + - **Description**: Validates the file type based on the file extension. - def run(self, task, *args, **kwargs): - # Logic for running your model goes here - return "Processed output" -``` - -#### Step 5: Test Your Model - -Instantiate your custom LLM and test it to ensure that it works as expected. + - **Parameters**: + + - `v` (`str`): The file type to validate. + + - `values` (`dict`): A dictionary of other field values. + + - **Return**: + + - (`str`): The validated file type. + -```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" -``` +- `create(self, initial_content: str) -> None` -#### Step 6: Integrate Additional Components + - **Description**: Creates a new file artifact with the initial content. + + - **Parameters**: + + - `initial_content` (`str`): The initial content to set for the artifact. + + - **Return**: None. + -Depending on the requirements, you might need to integrate additional components such as database connections, parallel computing resources, or custom processing pipelines. +- `edit(self, new_content: str) -> None` -#### Step 7: Documentation + - **Description**: Edits the artifact's content, tracking the change in the version history. + + - **Parameters**: + + - `new_content` (`str`): The new content to set for the artifact. + + - **Return**: None. + -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. +- `save(self) -> None` -```python -class vLLMLM(BaseLLM): - """ - A custom language model class that extends BaseLLM. + - **Description**: Saves the current artifact's contents to the specified file path. + + - **Parameters**: None. + + - **Return**: None. - ... more detailed docstring ... - """ - # ... existing code ... -``` -#### Step 8: Best Practices +- `load(self) -> None` -Follow best practices such as error handling, input validation, and resource management to ensure your model is robust and reliable. + - **Description**: Loads the file contents from the specified file path into the artifact. + + - **Parameters**: None. + + - **Return**: None. + -#### Step 9: Packaging Your Model +- `get_version(self, version_number: int) -> Union[FileVersion, None]` -Package your custom LLM class into a module or package that can be easily distributed and imported into other projects. + - **Description**: Retrieves a specific version of the artifact by its version number. + + - **Parameters**: + + - `version_number` (`int`): The version number to retrieve. + + - **Return**: + + - (`FileVersion | None`): The requested version if found; otherwise, `None`. + -#### Step 10: Version Control and Collaboration +- `get_contents(self) -> str` -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. + - **Description**: Returns the current contents of the artifact as a string. + + - **Parameters**: None. + + - **Return**: + + - (`str`): The current contents of the artifact. + -### Conclusion +- `get_version_history(self) -> str` -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. + - **Description**: Returns the version history of the artifact as a formatted string. + + - **Parameters**: None. + + - **Return**: + + - (`str`): A formatted string containing the version history. + -### Further Reading +- `export_to_json(self, file_path: str) -> None` -- 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. + - **Description**: Exports the artifact to a JSON file. + + - **Parameters**: + + - `file_path` (`str`): The path to the JSON file where the artifact will be saved. + + - **Return**: None. + -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. +- `import_from_json(cls, file_path: str) -> "Artifact"` --------------------------------------------------- + - **Description**: Imports an artifact from a JSON file. + + - **Parameters**: + + - `file_path` (`str`): The path to the JSON file to import the artifact from. + + - **Return**: + + - (`Artifact`): The imported artifact instance. + -# File: swarms\models\dalle3.md +- `get_metrics(self) -> str` -# `Dalle3` Documentation + - **Description**: Returns all metrics of the artifact as a formatted string. + + - **Parameters**: None. + + - **Return**: + + - (`str`): A string containing all metrics of the artifact. + -## Table of Contents +- `to_dict(self) -> Dict[str, Any]` -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) + - **Description**: Converts the artifact instance to a dictionary representation. + + - **Parameters**: None. + + - **Return**: + + - (`Dict[str, Any]`): The dictionary representation of the artifact. + ---- +- `from_dict(cls, data: Dict[str, Any]) -> "Artifact"` -## Introduction + - **Description**: Creates an artifact instance from a dictionary representation. + + - **Parameters**: + + - `data` (`Dict[str, Any]`): The dictionary to create the artifact from. + + - **Return**: + + - (`Artifact`): The created artifact instance. + -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. +**Example**: +```python +from swarms.artifacts.main_artifact import Artifact ---- +# Create an Artifact instance +artifact = Artifact(file_path="example.txt", file_type=".txt") +artifact.create("Initial content") +artifact.edit("First edit") +artifact.edit("Second edit") +artifact.save() -## Installation +# Export to JSON +artifact.export_to_json("artifact.json") -To use the Dalle3 model, you must first install swarms: +# Import from JSON +imported_artifact = Artifact.import_from_json("artifact.json") -```bash -pip install swarms +# Get metrics +print(artifact.get_metrics()) ``` ---- - -## 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 -# Create an instance of the Dalle3 class -dalle = Dalle3() -# Define a text prompt -task = "A painting of a dog" +### `swarms.artifacts.__init__` -# Generate an image from the text prompt -image_url = dalle3(task) +**Description**: +This module serves as the initialization point for the artifacts subpackage within the Swarms framework. It imports and exposes the key classes related to artifacts, including `BaseArtifact`, `TextArtifact`, and `Artifact`, making them available for use in other parts of the application. -# Print the generated image URL -print(image_url) -``` +**Imports**: +- `BaseArtifact`: The abstract base class for artifacts, imported from `swarms.artifacts.base_artifact`. -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. +- `TextArtifact`: A class representing text-based artifacts, imported from `swarms.artifacts.text_artifact`. ---- +- `Artifact`: A class representing file artifacts with versioning capabilities, imported from `swarms.artifacts.main_artifact`. -## Dalle3 Class -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. +**Exported Classes**: +- `BaseArtifact`: The base class for all artifacts. -### Attributes +- `TextArtifact`: A specialized artifact class for handling text values. -- `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. +- `Artifact`: A class for managing file artifacts, including their content and version history. -### Methods -#### `__call__(self, task: str) -> Dalle3` +**Example**: +```python +from swarms.artifacts import * -This method makes a call to the Dalle3 API and returns the image URL generated from the provided text prompt. +# Create instances of the artifact classes +base_artifact = BaseArtifact(id="1", name="Base Artifact", value="Some value") # This will raise an error since BaseArtifact is abstract +text_artifact = TextArtifact(value="Sample text") +file_artifact = Artifact(file_path="example.txt", file_type=".txt") -Parameters: -- `task` (str): The text prompt to be converted to an image. +# Use the classes as needed +print(text_artifact) # Output: Sample text +``` -Returns: -- `Dalle3`: An instance of the Dalle3 class with the image URL generated by the Dalle3 API. +**Note**: Since `BaseArtifact` is an abstract class, it cannot be instantiated directly. -#### `create_variations(self, img: str)` -This method creates variations of an image using the Dalle3 API. +# Agents -Parameters: -- `img` (str): The image to be used for the API request. +### `swarms.agents.__init__` -Returns: -- `img` (str): The image URL of the generated variations. +**Description**: +This module serves as the initialization point for the agents subpackage within the Swarms framework. It imports and exposes key classes and functions related to agent operations, including stopping conditions and the `ToolAgent` class, making them available for use in other parts of the application. ---- +**Imports**: +- `check_cancelled`: A function to check if the operation has been cancelled. -## Usage Examples +- `check_complete`: A function to check if the operation is complete. -### Example 1: Basic Image Generation +- `check_done`: A function to check if the operation is done. -```python -from swarm_models.dalle3 import Dalle3 +- `check_end`: A function to check if the operation has ended. -# Create an instance of the Dalle3 class -dalle3 = Dalle3() +- `check_error`: A function to check if there was an error during the operation. -# Define a text prompt -task = "A painting of a dog" +- `check_exit`: A function to check if the operation has exited. -# Generate an image from the text prompt -image_url = dalle3(task) +- `check_failure`: A function to check if the operation has failed. -# Print the generated image URL -print(image_url) -``` +- `check_finished`: A function to check if the operation has finished. -### Example 2: Creating Image Variations +- `check_stopped`: A function to check if the operation has been stopped. -```python -from swarm_models.dalle3 import Dalle3 +- `check_success`: A function to check if the operation was successful. -# Create an instance of the Dalle3 class -dalle3 = Dalle3() +- `ToolAgent`: A class representing an agent that utilizes tools. -# 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 -# Create variations of the image -variations_url = dalle3.create_variations(img_url) +**Exported Classes and Functions**: +- `ToolAgent`: The class for managing tool-based agents. -# Print the URLs of the generated variations -print(variations_url) -``` +- `check_done`: Checks if the operation is done. -Certainly! Here are additional examples that cover various edge cases and methods of the `Dalle3` class in the Dalle3 library: +- `check_finished`: Checks if the operation has finished. -### Example 3: Customizing Image Size +- `check_complete`: Checks if the operation is complete. -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: +- `check_success`: Checks if the operation was successful. -```python -from swarm_models.dalle3 import Dalle3 +- `check_failure`: Checks if the operation has failed. -# Create an instance of the Dalle3 class with a custom image size -dalle3 = Dalle3(size="512x512") +- `check_error`: Checks if there was an error during the operation. -# Define a text prompt -task = "A small painting of a cat" +- `check_stopped`: Checks if the operation has been stopped. -# Generate a smaller image from the text prompt -image_url = dalle3(task) +- `check_cancelled`: Checks if the operation has been cancelled. -# Print the generated image URL -print(image_url) -``` +- `check_exit`: Checks if the operation has exited. -### Example 4: Adjusting Retry Limit +- `check_end`: Checks if the operation has ended. -You can adjust the maximum number of API request retries using the `max_retries` parameter. Here's how to increase the retry limit: +**Example**: ```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" +from swarms.agents import * -# Generate an image with a higher retry limit -image_url = dalle3(task) +# Create an instance of ToolAgent +tool_agent = ToolAgent() -# Print the generated image URL -print(image_url) +# Check the status of an operation +if check_done(): + print("The operation is done.") ``` -### Example 5: Generating Image Variations +**Note**: The specific implementations of the stopping condition functions and the `ToolAgent` class are not detailed in this module, as they are imported from other modules within the `swarms.agents` package. -To create variations of an existing image, you can use the `create_variations` method. Here's an example: -```python -from swarm_models.dalle3 import Dalle3 -# Create an instance of the Dalle3 class -dalle3 = Dalle3() -# 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" +### `swarms.agents.tool_agent` -# Create variations of the image -variations_url = dalle3.create_variations(img_url) +**Description**: +This module defines the `ToolAgent` class, which represents a specialized agent capable of performing tasks using a specified model and tokenizer. It is designed to run operations that require input validation against a JSON schema, generating outputs based on defined tasks. -# Print the URLs of the generated variations -print(variations_url) -``` +**Imports**: +- `Any`, `Optional`, `Callable`: Type hints from the `typing` module for flexible parameter types. -### Example 6: Handling API Errors +- `Agent`: The base class for agents, imported from `swarms.structs.agent`. -The Dalle3 library provides error handling for API-related issues. Here's how to handle and display API errors: +- `Jsonformer`: A class responsible for transforming JSON data, imported from `swarms.tools.json_former`. -```python -from swarm_models.dalle3 import Dalle3 +- `logger`: A logging utility from `swarms.utils.loguru_logger`. -# Create an instance of the Dalle3 class -dalle3 = Dalle3() -# Define a text prompt -task = "Invalid prompt that may cause an API error" +### `ToolAgent` +**Description**: +Represents a tool agent that performs a specific task using a model and tokenizer. It facilitates the execution of tasks by calling the appropriate model or using the defined JSON schema for structured output. -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)}") -``` +**Attributes**: +- `name` (`str`): The name of the tool agent. + +- `description` (`str`): A description of what the tool agent does. -### Example 7: Customizing Image Quality +- `model` (`Any`): The model used by the tool agent for processing. -You can customize the quality of the generated image by specifying the `quality` parameter. Here's how to generate a high-quality image: +- `tokenizer` (`Any`): The tokenizer used by the tool agent to prepare input data. -```python -from swarm_models.dalle3 import Dalle3 +- `json_schema` (`Any`): The JSON schema that defines the structure of the expected output. -# Create an instance of the Dalle3 class with high quality -dalle3 = Dalle3(quality="high") +- `max_number_tokens` (`int`): The maximum number of tokens to generate (default is 500). -# Define a text prompt -task = "A high-quality image of a sunset" +- `parsing_function` (`Optional[Callable]`): A function for parsing the output, if provided. -# Generate a high-quality image from the text prompt -image_url = dalle3(task) +- `llm` (`Any`): A language model, if utilized instead of a custom model. -# Print the generated image URL -print(image_url) -``` +**Methods**: ---- +- `__init__(self, name: str, description: str, model: Any, tokenizer: Any, json_schema: Any, max_number_tokens: int, parsing_function: Optional[Callable], llm: Any, *args, +**kwargs) -> None` -## Error Handling + - **Description**: Initializes a new instance of the ToolAgent class. + + - **Parameters**: + + - `name` (`str`): The name of the tool agent. + + - `description` (`str`): A description of the tool agent. + + - `model` (`Any`): The model to use (if applicable). + + - `tokenizer` (`Any`): The tokenizer to use (if applicable). + + - `json_schema` (`Any`): The JSON schema that outlines the expected output format. + + - `max_number_tokens` (`int`): Maximum token output size. + + - `parsing_function` (`Optional[Callable]`): Optional function to parse the output. + + - `llm` (`Any`): The language model to use as an alternative to a custom model. + + - `*args` and `**kwargs`: Additional arguments and keyword arguments for flexibility. + + - **Return**: None. + -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. +- `run(self, task: str, *args, **kwargs) -> Any` ---- + - **Description**: Executes the tool agent for the specified task, utilizing either a model or a language model based on provided parameters. + + - **Parameters**: + + - `task` (`str`): The task or prompt to be processed by the tool agent. + + - `*args`: Additional positional arguments for flexibility. + + - `**kwargs`: Additional keyword arguments for flexibility. + + - **Return**: + + - (`Any`): The output generated by the tool agent based on the input task. + + - **Raises**: + + - `Exception`: If neither `model` nor `llm` is provided or if an error occurs during task execution. + -## Advanced Usage +**Example**: +```python +from transformers import AutoModelForCausalLM, AutoTokenizer +from swarms.agents.tool_agent import ToolAgent -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. +# Load model and tokenizer +model = AutoModelForCausalLM.from_pretrained("databricks/dolly-v2-12b") ---- +tokenizer = AutoTokenizer.from_pretrained("databricks/dolly-v2-12b") -## References -For more information about the DALL·E 3 model and the Dalle3 library, you can refer to the official OpenAI documentation and resources. +# Define a JSON schema +json_schema = { + "type": "object", + "properties": { + "name": {"type": "string"}, + "age": {"type": "number"}, + "is_student": {"type": "boolean"}, + "courses": { + "type": "array", + "items": {"type": "string"} + } + } +} -- [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) +# Create and run a ToolAgent +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(generated_data) +``` -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. --------------------------------------------------- -# File: swarms\models\distilled_whisperx.md -# DistilWhisperModel Documentation +### `swarms.agents.stopping_conditions` -## Overview +**Description**: +This module contains a set of functions that check specific stopping conditions based on strings. These functions return boolean values indicating the presence of certain keywords, which can be used to determine the status of an operation or process. -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. +### Functions: -## Installation +- `check_done(s: str) -> bool` -Before you can use `DistilWhisperModel`, ensure you have the required libraries installed: + - **Description**: Checks if the string contains the keyword "". + + - **Parameters**: + + - `s` (`str`): The input string to check. + + - **Return**: + + - (`bool`): `True` if "" is found in the string; otherwise, `False`. + -```sh -pip3 install --upgrade swarms -``` +- `check_finished(s: str) -> bool` -## Initialization + - **Description**: Checks if the string contains the keyword "finished". + + - **Parameters**: + + - `s` (`str`): The input string to check. + + - **Return**: + + - (`bool`): `True` if "finished" is found in the string; otherwise, `False`. + -The `DistilWhisperModel` class is initialized with the following parameters: +- `check_complete(s: str) -> bool` -| Parameter | Type | Description | Default | -|-----------|------|-------------|---------| -| `model_id` | `str` | The identifier for the pre-trained Whisper model | `"distil-whisper/distil-large-v2"` | + - **Description**: Checks if the string contains the keyword "complete". + + - **Parameters**: + + - `s` (`str`): The input string to check. + + - **Return**: + + - (`bool`): `True` if "complete" is found in the string; otherwise, `False`. + -Example of initialization: +- `check_success(s: str) -> bool` -```python -from swarm_models import DistilWhisperModel + - **Description**: Checks if the string contains the keyword "success". + + - **Parameters**: + + - `s` (`str`): The input string to check. + + - **Return**: + + - (`bool`): `True` if "success" is found in the string; otherwise, `False`. + -# Initialize with default model -model_wrapper = DistilWhisperModel() +- `check_failure(s: str) -> bool` -# Initialize with a specific model ID -model_wrapper = DistilWhisperModel(model_id="distil-whisper/distil-large-v2") -``` + - **Description**: Checks if the string contains the keyword "failure". + + - **Parameters**: + + - `s` (`str`): The input string to check. + + - **Return**: + + - (`bool`): `True` if "failure" is found in the string; otherwise, `False`. + -## Attributes +- `check_error(s: str) -> bool` -After initialization, the `DistilWhisperModel` has several attributes: + - **Description**: Checks if the string contains the keyword "error". + + - **Parameters**: + + - `s` (`str`): The input string to check. + + - **Return**: + + - (`bool`): `True` if "error" is found in the string; otherwise, `False`. + -| 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. | +- `check_stopped(s: str) -> bool` -## Methods + - **Description**: Checks if the string contains the keyword "stopped". + + - **Parameters**: + + - `s` (`str`): The input string to check. + + - **Return**: + + - (`bool`): `True` if "stopped" is found in the string; otherwise, `False`. + -### `transcribe` +- `check_cancelled(s: str) -> bool` -Transcribes audio input synchronously. + - **Description**: Checks if the string contains the keyword "cancelled". + + - **Parameters**: + + - `s` (`str`): The input string to check. + + - **Return**: + + - (`bool`): `True` if "cancelled" is found in the string; otherwise, `False`. + -**Arguments**: +- `check_exit(s: str) -> bool` -| Argument | Type | Description | -|----------|------|-------------| -| `inputs` | `Union[str, dict]` | File path or audio data dictionary. | + - **Description**: Checks if the string contains the keyword "exit". + + - **Parameters**: + + - `s` (`str`): The input string to check. + + - **Return**: + + - (`bool`): `True` if "exit" is found in the string; otherwise, `False`. + -**Returns**: `str` - The transcribed text. +- `check_end(s: str) -> bool` -**Usage Example**: + - **Description**: Checks if the string contains the keyword "end". + + - **Parameters**: + + - `s` (`str`): The input string to check. + + - **Return**: + + - (`bool`): `True` if "end" is found in the string; otherwise, `False`. + +**Example**: ```python -# Synchronous transcription -transcription = model_wrapper.transcribe("path/to/audio.mp3") -print(transcription) -``` +from swarms.agents.stopping_conditions import check_done, check_error -### `async_transcribe` +status_message = "The process has finished and !" -Transcribes audio input asynchronously. +if check_done(status_message): + print("The operation is done!") -**Arguments**: +if check_error(status_message): + print("An error has occurred!") +``` -| Argument | Type | Description | -|----------|------|-------------| -| `inputs` | `Union[str, dict]` | File path or audio data dictionary. | +**Note**: Each of these functions provides a simple way to check for specific keywords in a given string, which can be helpful in managing and monitoring tasks or operations. -**Returns**: `Coroutine` - A coroutine that when awaited, returns the transcribed text. -**Usage Example**: -```python -import asyncio +# Schemas -# Asynchronous transcription -transcription = asyncio.run(model_wrapper.async_transcribe("path/to/audio.mp3")) -print(transcription) -``` +### `swarms.schemas.base_schemas` -### `real_time_transcribe` +**Description**: +This module defines various Pydantic models that represent schemas used in machine learning applications. These models facilitate data validation and serialization for different types of content, such as model cards, chat messages, and responses. -Simulates real-time transcription of an audio file. +**Imports**: +- `uuid`: A module for generating unique identifiers. -**Arguments**: +- `time`: A module for time-related functions. -| Argument | Type | Description | -|----------|------|-------------| -| `audio_file_path` | `str` | Path to the audio file. | -| `chunk_duration` | `int` | Duration of audio chunks in seconds. | +- `List`, `Literal`, `Optional`, `Union`: Type hints from the `typing` module for flexible parameter types. -**Usage Example**: +- `BaseModel`, `Field`: Tools from the `pydantic` module for data validation and settings management. -```python -# Real-time transcription simulation -model_wrapper.real_time_transcribe("path/to/audio.mp3", chunk_duration=5) -``` -## Error Handling +### `ModelCard` +**Description**: +A Pydantic model that represents a model card, which provides metadata about a machine learning model. -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. +**Attributes**: +- `id` (`str`): The unique identifier for the model. -## Conclusion +- `object` (`str`): A fixed string indicating the type of object ("model"). -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. +- `created` (`int`): The timestamp of model creation, defaults to the current time. -## Additional Notes +- `owned_by` (`str`): The owner of the model. -- 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. +- `root` (`Optional[str]`): The root model identifier if applicable. -For a full list of models supported by `transformers.AutoModelForSpeechSeq2Seq`, visit the [Hugging Face Model Hub](https://huggingface.co/models). +- `parent` (`Optional[str]`): The parent model identifier if applicable. +- `permission` (`Optional[list]`): A list of permissions associated with the model. --------------------------------------------------- -# File: swarms\models\fuyu.md +### `ModelList` +**Description**: +A Pydantic model that represents a list of model cards. -# Fuyu Documentation +**Attributes**: +- `object` (`str`): A fixed string indicating the type of object ("list"). -## Introduction +- `data` (`List[ModelCard]`): A list containing instances of `ModelCard`. -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. -## Overview +### `ImageUrl` +**Description**: +A Pydantic model representing an image URL. -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. +**Attributes**: +- `url` (`str`): The URL of the image. -## Class Definition -```python -class Fuyu: - def __init__( - self, - pretrained_path: str = "adept/fuyu-8b", - device_map: str = "cuda:0", - max_new_tokens: int = 7, - ): -``` +### `TextContent` +**Description**: +A Pydantic model representing text content. -## Purpose +**Attributes**: +- `type` (`Literal["text"]`): A fixed string indicating the type of content (text). -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. +- `text` (`str`): The actual text content. -## 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. +### `ImageUrlContent` +**Description**: +A Pydantic model representing image content via URL. -## Usage +**Attributes**: +- `type` (`Literal["image_url"]`): A fixed string indicating the type of content (image URL). -To use Fuyu, follow these steps: +- `image_url` (`ImageUrl`): An instance of `ImageUrl` containing the URL of the image. -1. Initialize the Fuyu instance: -```python -from swarm_models.fuyu import Fuyu +### `ContentItem` +**Description**: +A type alias for a union of `TextContent` and `ImageUrlContent`, representing any content type that can be processed. -fuyu = Fuyu() -``` +### `ChatMessageInput` +**Description**: +A Pydantic model representing an input message for chat applications. +**Attributes**: +- `role` (`str`): The role of the sender (e.g., "user", "assistant", or "system"). -2. Generate Text with Fuyu: +- `content` (`Union[str, List[ContentItem]]`): The content of the message, which can be a string or a list of content items. -```python -text = "Hello, my name is" -img_path = "path/to/image.png" -output_text = fuyu(text, img_path) -``` -### Example 2 - Text Generation +### `ChatMessageResponse` +**Description**: +A Pydantic model representing a response message in chat applications. -```python -from swarm_models.fuyu import Fuyu +**Attributes**: +- `role` (`str`): The role of the sender (e.g., "user", "assistant", or "system"). -fuyu = Fuyu() +- `content` (`str`, optional): The content of the response message. -text = "Hello, my name is" -img_path = "path/to/image.png" +### `DeltaMessage` +**Description**: +A Pydantic model representing a delta update for messages in chat applications. -output_text = fuyu(text, img_path) -print(output_text) -``` +**Attributes**: +- `role` (`Optional[Literal["user", "assistant", "system"]]`): The role of the sender, if specified. -## How Fuyu Works +- `content` (`Optional[str]`): The content of the delta message, if provided. -Fuyu combines text and image processing to generate meaningful text outputs. Here's how it works: -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. +### `ChatCompletionRequest` +**Description**: +A Pydantic model representing a request for chat completion. -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. +**Attributes**: +- `model` (`str`): The model to use for completing the chat (default is "gpt-4o"). -3. **Tokenization**: Fuyu tokenizes the input text and encodes the image using its tokenizer. +- `messages` (`List[ChatMessageInput]`): A list of input messages for the chat. -4. **Model Inference**: The model takes the tokenized inputs and generates text that is conditioned on both the text and the image. +- `temperature` (`Optional[float]`): Controls the randomness of the output (default is 0.8). -5. **Output Text**: Fuyu returns the generated text as the output. +- `top_p` (`Optional[float]`): An alternative to sampling with temperature (default is 0.8). -## Additional Information +- `max_tokens` (`Optional[int]`): The maximum number of tokens to generate (default is 4000). -- 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. +- `stream` (`Optional[bool]`): If true, the response will be streamed (default is False). -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! +- `repetition_penalty` (`Optional[float]`): A penalty for repeated tokens (default is 1.0). --------------------------------------------------- +- `echo` (`Optional[bool]`): If true, the input will be echoed in the output (default is False). -# File: swarms\models\gemini.md -## `Gemini` Documentation +### `ChatCompletionResponseChoice` +**Description**: +A Pydantic model representing a choice in a chat completion response. -### Introduction +**Attributes**: +- `index` (`int`): The index of the choice. -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. +- `input` (`str`): The input message. -#### Purpose +- `message` (`ChatMessageResponse`): The output message. -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 +### `ChatCompletionResponseStreamChoice` +**Description**: +A Pydantic model representing a choice in a streamed chat completion response. -Before using Gemini, ensure that you have the required dependencies installed. You can install them using the following commands: +**Attributes**: +- `index` (`int`): The index of the choice. -```bash -pip install swarms -pip install google-generativeai -pip install python-dotenv -``` +- `delta` (`DeltaMessage`): The delta update for the message. -### Class: Gemini -#### Overview +### `UsageInfo` +**Description**: +A Pydantic model representing usage information for a chat completion request. -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. +**Attributes**: +- `prompt_tokens` (`int`): The number of tokens used in the prompt (default is 0). -##### Class Constructor +- `total_tokens` (`int`): The total number of tokens used (default is 0). -```python -class Gemini(BaseMultiModalModel): - def __init__( - self, - model_name: str = "gemini-pro", - gemini_api_key: str = get_gemini_api_key_env, - *args, - **kwargs, - ): -``` +- `completion_tokens` (`Optional[int]`): The number of tokens used in the completion (default is 0). -| 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. +### `ChatCompletionResponse` +**Description**: +A Pydantic model representing a response from a chat completion request. -- `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. +**Attributes**: +- `model` (`str`): The model used for the completion. -##### Methods +- `object` (`Literal["chat.completion", "chat.completion.chunk"]`): The type of response object. -1. **run()** +- `choices` (`List[Union[ChatCompletionResponseChoice, ChatCompletionResponseStreamChoice]]`): A list of choices from the completion. - ```python - def run( - self, - task: str = None, - img: str = None, - *args, - **kwargs, - ) -> str: - ``` +- `created` (`Optional[int]`): The timestamp of when the response was created. - | 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. +### `AgentChatCompletionResponse` +**Description**: +A Pydantic model representing a completion response from an agent. - - `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. +**Attributes**: +- `id` (`Optional[str]`): The ID of the agent that generated the completion response (default is a new UUID). - - `*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. +- `agent_name` (`Optional[str]`): The name of the agent that generated the response. - **Returns**: A string containing the generated content. +- `object` (`Optional[Literal["chat.completion", "chat.completion.chunk"]]`): The type of response object. - **Examples**: +- `choices` (`Optional[ChatCompletionResponseChoice]`): The choice from the completion response. - ```python - from swarm_models import Gemini +- `created` (`Optional[int]`): The timestamp of when the response was created. - # 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", - ) +**Example**: +```python +from swarms.schemas.base_schemas import ChatCompletionRequest, ChatMessageInput - # Print the generated content - print(generated_content) - ``` +# Create a chat completion request +request = ChatCompletionRequest( + model="gpt-4", + + messages=[ + ChatMessageInput(role="user", content="Hello! How can I help you?") + ] +) +``` - 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. +**Note**: The Pydantic models in this module provide a structured way to handle data related to machine learning models and chat interactions, ensuring that the data adheres to defined schemas. -2. **process_img()** - ```python - def process_img( - self, - img: str = None, - type: str = "image/png", - *args, - **kwargs, - ): - ``` - | 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. | - - `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. +### `swarms.schemas.plan` - - `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. +**Description**: +This module defines the `Plan` class, which represents a sequence of steps in a structured format. It utilizes Pydantic for data validation and configuration, ensuring that each plan consists of a list of defined steps. - - `*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. +**Imports**: +- `List`: A type hint from the `typing` module for work with lists. - **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. +- `BaseModel`: The Pydantic base class for data models, providing validation and serialization features. - **Examples**: +- `Step`: A model representing individual steps in the plan, imported from `swarms.schemas.agent_step_schemas`. - ```python - from swarm_models.gemini import Gemini - # Initialize the Gemini model - gemini = Gemini() +### `Plan` +**Description**: +Represents a sequence of steps that comprise a plan. This class ensures that the data structure adheres to the expected model for steps. - # Process an image - processed_image = gemini.process_img( - img="image.jpg", - type="image/jpeg", - ) +**Attributes**: +- `steps` (`List[Step]`): A list of steps, where each step is an instance of the `Step` model. - # Further use the processed image in content generation - generated_content = gemini.run( - task="Describe this image", - img=processed_image, - ) - # Print the generated content - print(generated_content) - ``` +**Config**: +- `orm_mode` (bool): Enables compatibility with ORM models to facilitate data loading from database objects. - In this example, we demonstrate how to process an image using the `process_img()` method and then use the processed image in content generation. -#### Additional Information +**Example**: +```python +from swarms.schemas.plan import Plan +from swarms.schemas.agent_step_schemas import Step -- Gemini is designed to work seamlessly with various multimodal AI models, making it a powerful tool for content generation tasks. +# Create a list of steps +steps = [ + Step(/* initialize step attributes */), + Step(/* initialize step attributes */), +] -- 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. +# Create a Plan instance +plan = Plan(steps=steps) -- 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." +# Access the steps +for step in plan.steps: + print(step) +``` -- Gemini's flexibility allows you to experiment with different Gemini models and tailor the content generation process to your specific needs. +**Note**: The `Plan` class relies on the `Step` model for its structure, ensuring that the steps in a plan conform to the validation rules defined in the `Step` model. -- 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. -- If you encounter any issues or have specific requirements, refer to the Gemini documentation for more details and advanced usage. -### References and Resources -- [Gemini GitHub Repository](https://github.com/swarms/gemini): Explore the Gemini repository for additional information, updates, and examples. +### `swarms.schemas.__init__` -- [Google GenerativeAI Documentation](https://docs.google.com/document/d/1WZSBw6GsOhOCYm0ArydD_9uy6nPPA1KFIbKPhjj43hA): Dive deeper into the capabilities of the Google GenerativeAI package used by Gemini. +**Description**: +This module serves as the initialization point for the schemas subpackage within the Swarms framework. It imports and exposes key classes related to agent steps and agent input schemas, making them available for use in other parts of the application. -- [Gemini API Documentation](https://gemini-api-docs.example.com): Access the official documentation for the Gemini API to explore advanced features and integrations. +**Imports**: +- `Step`: A model representing an individual step in an agent's operation, imported from `swarms.schemas.agent_step_schemas`. -## Conclusion +- `ManySteps`: A model representing multiple steps, also imported from `swarms.schemas.agent_step_schemas`. -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. +- `AgentSchema`: A model representing the schema for agent inputs, imported from `swarms.schemas.agent_input_schema`. --------------------------------------------------- -# File: swarms\models\gpt4v.md +**Exported Classes**: +- `Step`: The class for defining individual steps in an agent's operation. -# `GPT4VisionAPI` Documentation +- `ManySteps`: The class for defining multiple steps in an agent's operation. -**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) +- `AgentSchema`: The class for defining the input schema for agents. -## 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. +**Example**: +```python +from swarms.schemas import * -## Installation +# Create an instance of Step +step = Step(/* initialize step attributes */) -Before you start using the `GPT4VisionAPI` module, make sure you have the required dependencies installed. You can install them using the following commands: +# Create an instance of ManySteps +many_steps = ManySteps(steps=[step, step]) -```bash -pip3 install --upgrade swarms +# Create an instance of AgentSchema +agent_schema = AgentSchema(/* initialize agent schema attributes */) ``` -## Module Overview - -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: - -- 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. - -## Class: GPT4VisionAPI - -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 +**Note**: This module acts as a central point for importing and utilizing the various schema classes defined in the Swarms framework, facilitating structured data handling for agents and their operations. -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: -| 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. | -Here's how you can initialize the `GPT4VisionAPI` class: -```python -from swarm_models import GPT4VisionAPI +### `swarms.schemas.agent_step_schemas` -# Initialize with default API key and max_tokens -api = GPT4VisionAPI() +**Description**: +This module defines the `Step` and `ManySteps` classes, which represent individual steps and collections of steps in a task, respectively. These classes utilize Pydantic for data validation and serialization, ensuring that each step adheres to the defined schema. -# 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) -``` +**Imports**: +- `time`: A module for time-related functions. -### Methods +- `uuid`: A module for generating unique identifiers. -#### encode_image +- `List`, `Optional`, `Any`: Type hints from the `typing` module for flexible parameter types. -This method allows you to encode an image from a URL to base64 format. It's a utility function used internally by the module. +- `BaseModel`, `Field`: Tools from the `pydantic` module for data validation and settings management. -```python -def encode_image(img: str) -> str: - """ - Encode image to base64. +- `AgentChatCompletionResponse`: A model representing the response from an agent's chat completion, imported from `swarms.schemas.base_schemas`. - Parameters: - - img (str): URL of the image to encode. - Returns: - str: Base64 encoded image. - """ -``` +### `get_current_time() -> str` -#### run +**Description**: +Returns the current time formatted as "YYYY-MM-DD HH:MM:SS". -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. -```python -def run(task: str, img: str) -> str: - """ - Run the GPT-4 Vision model. +**Return**: +- (`str`): The current time as a formatted string. - Parameters: - - task (str): The task or question related to the image. - - img (str): URL of the image to analyze. - Returns: - str: The model's response. - """ -``` +### `Step` +**Description**: +A Pydantic model representing a single step in a task, including its ID, completion time, and response from an agent. -#### __call__ +**Attributes**: +- `step_id` (`Optional[str]`): The unique identifier for the step, generated if not provided. -The `__call__` method is a convenient way to run the GPT-4 Vision model. It has the same functionality as the `run` method. +- `time` (`Optional[float]`): The time taken to complete the task step, formatted as a string. -```python -def __call__(task: str, img: str) -> str: - """ - Run the GPT-4 Vision model (callable). +- `response` (`Optional[AgentChatCompletionResponse]`): The response from the agent for this step. - Parameters: - - task (str): The task or question related to the image. - - img - (str): URL of the image to analyze. +### `ManySteps` +**Description**: +A Pydantic model representing a collection of steps associated with a specific agent and task. - Returns: - str: The model's response. - """ -``` +**Attributes**: +- `agent_id` (`Optional[str]`): The unique identifier for the agent. -## Examples +- `agent_name` (`Optional[str]`): The name of the agent. -Let's explore some usage examples of the `GPT4VisionAPI` module to better understand how to use it effectively. +- `task` (`Optional[str]`): The name of the task being performed. -### Example 1: Basic Usage +- `max_loops` (`Optional[Any]`): The maximum number of steps in the task. -In this example, we'll use the module with the default API key and maximum tokens to analyze an image. +- `run_id` (`Optional[str]`): The ID of the task this collection of steps belongs to. -```python -from swarm_models import GPT4VisionAPI +- `steps` (`Optional[List[Step]]`): A list of `Step` instances representing the steps of the task. -# Initialize with default API key and max_tokens -api = GPT4VisionAPI() +- `full_history` (`Optional[str]`): A string containing the full history of the task. -# Define the task and image URL -task = "What is the color of the object?" -img = "https://i.imgur.com/2M2ZGwC.jpeg" +- `total_tokens` (`Optional[int]`): The total number of tokens generated during the task. -# Run the GPT-4 Vision model -response = api.run(task, img) +- `stopping_token` (`Optional[str]`): The token at which the task stopped. -# Print the model's response -print(response) -``` +- `interactive` (`Optional[bool]`): Indicates whether the task is interactive. -### Example 2: Custom API Key +- `dynamic_temperature_enabled` (`Optional[bool]`): Indicates whether dynamic temperature adjustments are enabled for the task. -If you have a custom API key, you can initialize the module with it as shown in this example. +**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) +from swarms.schemas.agent_step_schemas import Step, ManySteps -# Define the task and image URL -task = "What is the object in the image?" -img = "https://i.imgur.com/3T3ZHwD.jpeg" +# Create a step instance +step = Step(step_id="12345", response=AgentChatCompletionResponse(...)) -# Run the GPT-4 Vision model -response = api.run(task, img) +# Create a ManySteps instance +many_steps = ManySteps( + agent_id="agent-1", + + agent_name="Test Agent", + task="Example Task", + max_loops=5, + steps=[step], + full_history="Task executed successfully.", + total_tokens=100 +) -# Print the model's response -print(response) +print(many_steps) ``` -### 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. +**Note**: The `Step` and `ManySteps` classes provide structured representations of task steps, ensuring that all necessary information is captured and validated according to the defined schemas. -```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) +### `swarms.schemas.agent_input_schema` -# Print the model's response -print(response) -``` +**Description**: +This module defines the `AgentSchema` class using Pydantic, which represents the input parameters necessary for configuring an agent in the Swarms framework. It includes a variety of attributes for specifying the agent's behavior, model settings, and operational parameters. -## Additional Information +**Imports**: +- `Any`, `Callable`, `Dict`, `List`, `Optional`: Type hints from the `typing` module for flexible parameter types. -- 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. +- `BaseModel`, `Field`: Tools from the `pydantic` module for data validation and settings management. -## References +- `validator`: A decorator from Pydantic used for custom validation of fields. -- [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. +### `AgentSchema` +**Description**: +Represents the configuration for an agent, including attributes that govern its behavior, capabilities, and interaction with language models. This class ensures that the input data adheres to defined validation rules. --------------------------------------------------- +**Attributes**: +- `llm` (`Any`): The language model to use. -# File: swarms\models\groq.md +- `max_tokens` (`int`): The maximum number of tokens the agent can generate, must be greater than or equal to 1. -# Groq API Key Setup Documentation +- `context_window` (`int`): The size of the context window, must be greater than or equal to 1. +- `user_name` (`str`): The name of the user interacting with the agent. -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. +- `agent_name` (`str`): The name of the agent. -## Step 1: Obtain Your Groq API Key +- `system_prompt` (`str`): The system prompt provided to the agent. -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. +- `template` (`Optional[str]`): An optional template for the agent, default is `None`. -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". +- `max_loops` (`Optional[int]`): The maximum number of loops the agent can perform (default is 1, must be greater than or equal to 1). -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. +- `stopping_condition` (`Optional[Callable[[str], bool]]`): A callable function that defines a stopping condition for the agent. -## Step 2: Create a `.env` File +- `loop_interval` (`Optional[int]`): The interval between loops (default is 0, must be greater than or equal to 0). -1. **Create the File**: - - In the root directory of your project, create a new file named `.env`. +- `retry_attempts` (`Optional[int]`): Number of times to retry an operation if it fails (default is 3, must be greater than or equal to 0). -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: +- `retry_interval` (`Optional[int]`): The time between retry attempts (default is 1, must be greater than or equal to 0). - ```plaintext - GROQ_API_KEY=your_groq_api_key_here - ``` +- `return_history` (`Optional[bool]`): Flag indicating whether to return the history of the agent's operations (default is `False`). -3. **Save the File**: - - Save the changes to the `.env` file. +- `stopping_token` (`Optional[str]`): Token indicating when to stop processing (default is `None`). +- `dynamic_loops` (`Optional[bool]`): Indicates whether dynamic loops are enabled (default is `False`). +- `interactive` (`Optional[bool]`): Indicates whether the agent operates in an interactive mode (default is `False`). -## Full Example -```python -import os -from swarm_models import OpenAIChat -from dotenv import load_dotenv +- `dashboard` (`Optional[bool]`): Flag indicating whether a dashboard interface is enabled (default is `False`). -load_dotenv() +- `agent_description` (`Optional[str]`): A description of the agent's functionality (default is `None`). -# Get the OpenAI API key from the environment variable -api_key = os.getenv("GROQ_API_KEY") +- `tools` (`Optional[List[Callable]]`): List of callable tools the agent can use (default is `None`). -# 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, -) +- `dynamic_temperature_enabled` (`Optional[bool]`): Indicates whether dynamic temperature adjustments are enabled (default is `False`). -model.run("What are the best metrics to track and understand risk in private equity") -``` +- Additional attributes for managing various functionalities and configurations related to the agent's behavior, such as logging, saving states, and managing tools. -## 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. +### Validators: +- **check_list_items_not_none(v)**: Ensures that items within certain list attributes (`tools`, `docs`, `sop_list`, etc.) are not `None`. -## Conclusion +- **check_optional_callable_not_none(v)**: Ensures that optional callable attributes are either `None` or callable. -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. +**Example**: +```python +from swarms.schemas.agent_input_schema import AgentSchema --------------------------------------------------- +# Define the agent configuration data +agent_data = { + "llm": "OpenAIChat", + "max_tokens": 4096, + "context_window": 8192, + "user_name": "Human", + "agent_name": "test-agent", + + "system_prompt": "Custom system prompt", +} -# File: swarms\models\hf.md +# Create an AgentSchema instance +agent = AgentSchema(**agent_data) +print(agent) +``` -# HuggingFaceLLM +**Note**: The `AgentSchema` class provides a structured way to configure agents in the Swarms framework, ensuring that all necessary parameters are validated before use. -## 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. -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. ---- +-------------------------------------------------- -## Class Definition +# File: swarms\framework\test.md -```python -class HuggingFaceLLM: -``` +# How to Run Tests Using Pytest: A Comprehensive Guide -### Parameters: +In modern software development, automated testing is crucial for ensuring the reliability and functionality of your code. One of the most popular testing frameworks for Python is `pytest`. -- `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`. +This blog will provide an in-depth look at how to run tests using `pytest`, including testing a single file, multiple files, every file in the test repository, and providing guidelines for contributors to run tests reliably. ---- +## What is Pytest? -## Functionality & Usage +`pytest` is a testing framework for Python that makes it easy to write simple and scalable test cases. It supports fixtures, parameterized testing, and has a rich plugin architecture. `pytest` is widely used because of its ease of use and powerful features that help streamline the testing process. -### Initialization: +## Installation -```python -llm = HuggingFaceLLM(model_id="gpt2-medium") -``` +To get started with `pytest`, you need to install it. You can install `pytest` using `pip`: -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. +```bash +pip install pytest +``` -### Generation: +## Writing Your First Test -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. +Before diving into running tests, let’s write a simple test. Create a file named `test_sample.py` with the following content: -Usage: ```python -from swarms import HuggingFaceLLM - -# Initialize -llm = HuggingFaceLLM(model_id="gpt2-medium") - -# Generate text using __call__ method -result = llm("Once upon a time,") -print(result) +def test_addition(): + assert 1 + 1 == 2 -# Alternatively, using the generate method -result = llm.generate("The future of AI is") -print(result) +def test_subtraction(): + assert 2 - 1 == 1 ``` ---- +In this example, we have defined two basic tests: `test_addition` and `test_subtraction`. -## Mathematical Explanation: +## Running Tests -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: +### Running a Single Test File -\[ P(x_{n+1} | x_1, x_2, ..., x_n) \] +To run a single test file, you can use the `pytest` command followed by the filename. For example, to run the tests in `test_sample.py`, use the following command: -Where \( P \) is the probability distribution over all possible tokens in the vocabulary. +```bash +pytest test_sample.py +``` -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. +The output will show the test results, including the number of tests passed, failed, or skipped. ---- +### Running Multiple Test Files -## Additional Information & Tips: +You can also run multiple test files by specifying their filenames separated by a space. For example: -- 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. +```bash +pytest test_sample.py test_another_sample.py +``` -- Although the default `max_length` is set to 20, it's advisable to adjust this parameter based on the context of the problem. +If you have multiple test files in a directory, you can run all of them by specifying the directory name: -- Keep an eye on GPU memory when using large models or generating long sequences. +```bash +pytest tests/ +``` ---- +### Running All Tests in the Repository -## References & Resources: +To run all tests in the repository, navigate to the root directory of your project and simply run: -- 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) +```bash +pytest +``` -- Causal Language Modeling: Vaswani, A., et al. (2017). Attention is All You Need. [arXiv:1706.03762](https://arxiv.org/abs/1706.03762) +`pytest` will automatically discover and run all the test files that match the pattern `test_*.py` or `*_test.py`. -Note: This documentation template provides a comprehensive overview of the `HuggingFaceLLM` class. Developers can follow similar structures when documenting other classes or functionalities. +### Test Discovery --------------------------------------------------- +`pytest` automatically discovers test files and test functions based on their naming conventions. By default, it looks for files that match the pattern `test_*.py` or `*_test.py` and functions or methods that start with `test_`. -# File: swarms\models\huggingface.md +### Using Markers -## `HuggingfaceLLM` Documentation +`pytest` allows you to use markers to group tests or add metadata to them. Markers can be used to run specific subsets of tests. For example, you can mark a test as `slow` and then run only the slow tests or skip them. -### Introduction +```python +import pytest -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. +@pytest.mark.slow +def test_long_running(): + import time + time.sleep(5) + assert True -#### Purpose +def test_fast(): + assert True +``` -The `HuggingfaceLLM` class serves the following purposes: +To run only the tests marked as `slow`, use the `-m` option: -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. +```bash +pytest -m slow +``` -### Class Definition +### Parameterized Tests -The `HuggingfaceLLM` class is defined as follows: +`pytest` supports parameterized testing, which allows you to run a test with different sets of input data. This can be done using the `@pytest.mark.parametrize` decorator. ```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 - - def load_model(self): - # Method to load the pre-trained model and tokenizer - pass - - def run(self, prompt_text: str, max_length: int = None): - # Method to generate text-based responses - pass +import pytest - def __call__(self, prompt_text: str, max_length: int = None): - # Alternate method for generating text-based responses - pass +@pytest.mark.parametrize("a,b,expected", [ + (1, 2, 3), + (2, 3, 5), + (3, 5, 8), +]) +def test_add(a, b, expected): + assert a + b == expected ``` -### Attributes - -| 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. | +In this example, `test_add` will run three times with different sets of input data. -### Class Methods +### Fixtures -#### `__init__` Method +Fixtures are a powerful feature of `pytest` that allow you to set up some context for your tests. They can be used to provide a fixed baseline upon which tests can reliably and repeatedly execute. -The `__init__` method initializes an instance of the `HuggingfaceLLM` class with the specified parameters. It also loads the pre-trained model and tokenizer. +```python +import pytest -- `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. +@pytest.fixture +def sample_data(): + return {"name": "John", "age": 30} -#### `load_model` Method +def test_sample_data(sample_data): + assert sample_data["name"] == "John" + assert sample_data["age"] == 30 +``` -The `load_model` method loads the pre-trained model and tokenizer specified by `model_id`. +Fixtures can be used to share setup and teardown code between tests. -#### `run` and `__call__` Methods +## Advanced Usage -Both `run` and `__call__` methods generate text-based responses based on a given prompt. They accept the following parameters: +### Running Tests in Parallel -- `prompt_text` (str): The text prompt to initiate text generation. -- `max_length` (int, optional): The maximum length of the generated text. +`pytest` can run tests in parallel using the `pytest-xdist` plugin. To install `pytest-xdist`, run: -### Usage Examples +```bash +pip install pytest-xdist +``` -Here are three ways to use the `HuggingfaceLLM` class: +To run tests in parallel, use the `-n` option followed by the number of CPU cores you want to use: -#### Example 1: Basic Usage +```bash +pytest -n 4 +``` -```python -from swarm_models import HuggingfaceLLM +### Generating Test Reports -# Initialize the HuggingfaceLLM instance with a model ID -model_id = "NousResearch/Nous-Hermes-2-Vision-Alpha" -inference = HuggingfaceLLM(model_id=model_id) +`pytest` can generate detailed test reports. You can use the `--html` option to generate an HTML report: -# Generate text based on a prompt -prompt_text = "Once upon a time" -generated_text = inference(prompt_text) -print(generated_text) +```bash +pip install pytest-html +pytest --html=report.html ``` -#### Example 2: Custom Configuration +This command will generate a file named `report.html` with a detailed report of the test results. -```python -from swarm_models import HuggingfaceLLM +### Code Coverage -# 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 -) +You can use the `pytest-cov` plugin to measure code coverage. To install `pytest-cov`, run: -# Generate text based on a prompt -prompt_text = "Tell me a joke" -generated_text = inference(prompt_text) -print(generated_text) +```bash +pip install pytest-cov ``` -#### Example 3: Distributed Processing +To generate a coverage report, use the `--cov` option followed by the module name: -```python -from swarm_models import HuggingfaceLLM +```bash +pytest --cov=my_module +``` -# Initialize for distributed processing -inference = HuggingfaceLLM(model_id="gpt2-medium", distributed=True) +This command will show the coverage summary in the terminal. You can also generate an HTML report: -# Generate text based on a prompt -prompt_text = "Translate the following sentence to French" -generated_text = inference(prompt_text) -print(generated_text) +```bash +pytest --cov=my_module --cov-report=html ``` -### Additional Information +The coverage report will be generated in the `htmlcov` directory. -- 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. +## Best Practices for Writing Tests -### References +1. **Write Clear and Concise Tests**: Each test should focus on a single piece of functionality. +2. **Use Descriptive Names**: Test function names should clearly describe what they are testing. +3. **Keep Tests Independent**: Tests should not depend on each other and should run in isolation. +4. **Use Fixtures**: Use fixtures to set up the context for your tests. +5. **Mock External Dependencies**: Use mocking to isolate the code under test from external dependencies. -- [Hugging Face Transformers Documentation](https://huggingface.co/transformers/) -- [PyTorch Documentation](https://pytorch.org/docs/stable/index.html) +## Running Tests Reliably -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. +For contributors and team members, it’s important to run tests reliably to ensure consistent results. Here are some guidelines: --------------------------------------------------- +1. **Set Up a Virtual Environment**: Use a virtual environment to manage dependencies and ensure a consistent testing environment. + + ```bash + python -m venv venv + source venv/bin/activate # On Windows use `venv\Scripts\activate` + ``` -# File: swarms\models\idefics.md +2. **Install Dependencies**: Install all required dependencies from the `requirements.txt` file. + + ```bash + pip install -r requirements.txt + ``` -# `Idefics` Documentation +3. **Run Tests Before Pushing**: Ensure all tests pass before pushing code to the repository. -## Introduction +4. **Use Continuous Integration (CI)**: Set up CI pipelines to automatically run tests on each commit or pull request. -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. +### Example CI Configuration (GitHub Actions) -## Overview +Here is an example of a GitHub Actions workflow to run tests using `pytest`: -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. +```yaml +name: Python package -## Class Definition +on: [push, pull_request] -```python -class Idefics: - def __init__( - self, - checkpoint="HuggingFaceM4/idefics-9b-instruct", - device=None, - torch_dtype=torch.bfloat16, - max_length=100, - ): +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + - name: Set up Python + uses: actions/setup-python@v2 + with: + python-version: '3.8' + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r requirements.txt + - name: Run tests + run: | + pytest ``` -## Usage +This configuration will run the tests on every push and pull request, ensuring that your codebase remains stable. -To use Idefics, follow these steps: +## Conclusion -1. Initialize the Idefics instance: +`pytest` is a powerful and flexible testing framework that makes it easy to write and run tests for your Python code. By following the guidelines and best practices outlined in this blog, you can ensure that your tests are reliable and your codebase is robust. Whether you are testing a single file, multiple files, or the entire repository, `pytest` provides the tools you need to automate and streamline your testing process. -```python -from swarm_models import Idefics +Happy testing! -model = Idefics() -``` +-------------------------------------------------- + +# File: swarms\framework\vision.md -2. Generate text based on prompts: +### Swarms Vision -```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) -``` +**Swarms** is dedicated to transforming enterprise automation by offering a robust and intuitive interface for multi-agent collaboration and seamless integration with multiple models. Our mission is to enable enterprises to enhance their operational efficiency and effectiveness through intelligent automation. + +#### Vision Statement -### Example 1 - Image Questioning +**To become the preeminent framework for orchestrating multi-agent collaboration and integration, empowering enterprises to achieve exceptional automation efficiency and operational excellence.** -```python -from swarm_models import Idefics +#### Core Principles -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) -``` +1. **Multi-Agent Collaboration**: Facilitate seamless collaboration between diverse agents to solve complex and dynamic problems. +2. **Integration**: Provide robust and flexible integration with various models and frameworks to maximize functionality. +3. **Enterprise Automation**: Deliver enterprise-grade solutions designed for reliability, scalability, and security. +4. **Open Ecosystem**: Promote an open and extensible ecosystem that encourages innovation, community engagement, and collaborative development. -### Example 2 - Bidirectional Conversation +### Vision Document with Mermaid Graphs -```python -from swarm_models import Idefics +#### Overview Diagram -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) +```mermaid +graph TD + A[Swarms Framework] --> B[Multi-Agent Collaboration] + A --> C[Integration with Multiple Models] + A --> D[Enterprise Automation] + A --> E[Open Ecosystem] -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) -``` + B --> F[Seamless Communication] + B --> G[Collaboration Protocols] + + C --> H[Model Integration] + C --> I[Framework Compatibility] -### Example 3 - Configuration Changes + D --> J[Operational Efficiency] + D --> K[Reliability and Scalability] -```python -model.set_checkpoint("new_checkpoint") -model.set_device("cpu") -model.set_max_length(200) -model.clear_chat_history() + E --> L[Encourage Innovation] + E --> M[Community Driven] ``` -## How Idefics Works +#### Multi-Agent Collaboration -Idefics operates by leveraging pre-trained models from the Hugging Face Hub. Here's how it works: +```mermaid +graph TD + B[Multi-Agent Collaboration] --> F[Seamless Communication] + B --> G[Collaboration Protocols] -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. + F --> N[Cross-Agent Messaging] + F --> O[Task Coordination] + F --> P[Real-Time Updates] -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. + G --> Q[Standard APIs] + G --> R[Extensible Protocols] + G --> S[Security and Compliance] -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. + N --> T[Agent Messaging Hub] + O --> U[Task Assignment and Monitoring] + P --> V[Instantaneous Data Sync] -4. **Configuration Changes**: You can change the model checkpoint, device, maximum text length, or clear the chat history as needed during runtime. + Q --> W[Unified API Interface] + R --> X[Customizable Protocols] + S --> Y[Compliance with Standards] + S --> Z[Secure Communication Channels] +``` -## Parameters +#### Integration with Multiple Models -- `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). +```mermaid +graph TD + C[Integration with Multiple Models] --> H[Model Integration] + C --> I[Framework Compatibility] -## Additional Information + H --> R[Plug-and-Play Models] + H --> S[Model Orchestration] + H --> T[Model Versioning] -- 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. + I --> U[Support for OpenAI] + I --> V[Support for Anthropic] + I --> W[Support for Gemini] + I --> X[Support for LangChain] + I --> Y[Support for AutoGen] + I --> Z[Support for Custom Models] -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! + R --> AA[Easy Model Integration] + S --> AB[Dynamic Model Orchestration] + T --> AC[Version Control] --------------------------------------------------- + U --> AD[Integration with OpenAI Models] + V --> AE[Integration with Anthropic Models] + W --> AF[Integration with Gemini Models] + X --> AG[Integration with LangChain Models] + Y --> AH[Integration with AutoGen Models] + Z --> AI[Support for Proprietary Models] +``` -# File: swarms\models\index.md +#### Enterprise Automation -# Swarm Models +```mermaid +graph TD + D[Enterprise Automation] --> J[Operational Efficiency] + D --> K[Reliability and Scalability] + J --> Y[Automate Workflows] + J --> Z[Reduce Manual Work] + J --> AA[Increase Productivity] -```bash -$ pip3 install -U swarm-models -``` + K --> AB[High Uptime] + K --> AC[Enterprise-Grade Security] + K --> AD[Scalable Solutions] -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. + Y --> AE[Workflow Automation Tools] + Z --> AF[Eliminate Redundant Tasks] + AA --> AG[Boost Employee Efficiency] -### Table of Contents -1. [OpenAI](#openai) -2. [HuggingFace](#huggingface) -3. [Anthropic](#anthropic) + AB --> AH[Robust Infrastructure] + AC --> AI[Security Compliance] + AD --> AJ[Scale with Demand] +``` -### 1. OpenAI (swarm_models.OpenAI) +#### Open Ecosystem -The OpenAI class provides an interface to interact with OpenAI's language models. It allows both synchronous and asynchronous interactions. +```mermaid +graph TD + E[Open Ecosystem] --> L[Encourage Innovation] + E --> M[Community Driven] -**Constructor:** -```python -OpenAI(api_key: str, system: str = None, console: bool = True, model: str = None, params: dict = None, save_messages: bool = True) -``` + L --> AC[Open Source Contributions] + L --> AD[Hackathons and Workshops] + L --> AE[Research and Development] -**Attributes:** -- `api_key` (str): Your OpenAI API key. + M --> AF[Active Community Support] + M --> AG[Collaborative Development] + M --> AH[Shared Resources] -- `system` (str, optional): A system message to be used in conversations. + AC --> AI[Community Contributions] + AD --> AJ[Innovative Events] + AE --> AK[Continuous R&D] -- `console` (bool, default=True): Display console logs. + AF --> AL[Supportive Community] + AG --> AM[Joint Development Projects] + AH --> AN[Shared Knowledge Base] +``` -- `model` (str, optional): Name of the language model to use. +--- -- `params` (dict, optional): Additional parameters for model interactions. +### Conclusion -- `save_messages` (bool, default=True): Save conversation messages. +Swarms excels in enabling seamless communication and coordination between multiple agents, fostering a collaborative environment where agents can work together to solve complex tasks. Our platform supports cross-agent messaging, task coordination, and real-time updates, ensuring that all agents are synchronized and can efficiently contribute to the collective goal. -**Methods:** +Swarms provides robust integration capabilities with a wide array of models, including OpenAI, Anthropic, Gemini, LangChain, AutoGen, and custom models. This ensures that enterprises can leverage the best models available to meet their specific needs, while also allowing for dynamic model orchestration and version control to keep operations up-to-date and effective. -- `run(message: str, **kwargs) -> str`: Generate a response using the OpenAI model. +Our framework is designed to enhance operational efficiency through automation. By automating workflows, reducing manual work, and increasing productivity, Swarms helps enterprises achieve higher efficiency and operational excellence. Our solutions are built for high uptime, enterprise-grade security, and scalability, ensuring reliable and secure operations. -- `generate_async(message: str, **kwargs) -> str`: Generate a response asynchronously. +Swarms promotes an open and extensible ecosystem, encouraging community-driven innovation and development. We support open-source contributions, organize hackathons and workshops, and continuously invest in research and development. Our active community fosters collaborative development, shared resources, and a supportive environment for innovation. -- `ask_multiple(ids: List[str], question_template: str) -> List[str]`: Query multiple IDs simultaneously. +**Swarms** is dedicated to providing a comprehensive and powerful framework for enterprises seeking to automate operations through multi-agent collaboration and integration with various models. Our commitment to an open ecosystem, enterprise-grade automation solutions, and seamless multi-agent collaboration ensures that Swarms remains the leading choice for enterprises aiming to achieve operational excellence through intelligent automation. -- `stream_multiple(ids: List[str], question_template: str) -> List[str]`: Stream multiple responses. +-------------------------------------------------- -**Usage Example:** -```python -import asyncio +# File: swarms\glossary.md -from swarm_models import OpenAI +# Glossary of Terms -chat = OpenAI(api_key="YOUR_OPENAI_API_KEY") +**Agent**: +An LLM (Large Language Model) equipped with tools and memory, operating with a specific objective in a loop. An agent can perform tasks, interact with other agents, and utilize external tools and memory systems to achieve its goals. -response = chat.run("Hello, how can I assist you?") -print(response) +**Swarms**: +A group of more than two agents working together and communicating to accomplish a shared objective. Swarms enable complex, collaborative tasks that leverage the strengths of multiple agents. -ids = ["id1", "id2", "id3"] -async_responses = asyncio.run(chat.ask_multiple(ids, "How is {id}?")) -print(async_responses) -``` +**Tool**: +A Python function that is converted into a function call, allowing agents to perform specific actions or access external resources. Tools enhance the capabilities of agents by providing specialized functionalities. -### 2. HuggingFace (swarm_models.HuggingFaceLLM) +**Memory System**: +A system for managing information retrieval and storage, often implemented as a Retrieval-Augmented Generation (RAG) system or a memory vector database. Memory systems enable agents to recall previous interactions, store new information, and improve decision-making based on historical data. -The HuggingFaceLLM class allows interaction with language models from Hugging Face. +**LLM (Large Language Model)**: +A type of AI model designed to understand and generate human-like text. LLMs, such as GPT-3 or GPT-4, are used as the core computational engine for agents. -**Constructor:** -```python -HuggingFaceLLM(model_id: str, device: str = None, max_length: int = 20, quantize: bool = False, quantization_config: dict = None) -``` +**System Prompt**: +A predefined prompt that sets the context and instructions for an agent's task. The system prompt guides the agent's behavior and response generation. -**Attributes:** +**Max Loops**: +The maximum number of iterations an agent will perform to complete its task. This parameter helps control the extent of an agent's processing and ensures tasks are completed efficiently. -- `model_id` (str): ID or name of the Hugging Face model. +**Dashboard**: +A user interface that provides real-time monitoring and control over the agents and their activities. Dashboards can display agent status, logs, and performance metrics. -- `device` (str, optional): Device to run the model on (e.g., 'cuda', 'cpu'). +**Streaming On**: +A setting that enables agents to stream their output incrementally, providing real-time feedback as they process tasks. This feature is useful for monitoring progress and making adjustments on the fly. -- `max_length` (int, default=20): Maximum length of generated text. +**Verbose**: +A setting that controls the level of detail in an agent's output and logging. When verbose mode is enabled, the agent provides more detailed information about its operations and decisions. -- `quantize` (bool, default=False): Apply model quantization. +**Multi-modal**: +The capability of an agent to process and integrate multiple types of data, such as text, images, and audio. Multi-modal agents can handle more complex tasks that require diverse inputs. -- `quantization_config` (dict, optional): Configuration for quantization. +**Autosave**: +A feature that automatically saves the agent's state and progress at regular intervals. Autosave helps prevent data loss and allows for recovery in case of interruptions. -**Methods:** +**Flow**: +The predefined sequence in which agents in a swarm interact and process tasks. The flow ensures that each agent's output is appropriately passed to the next agent, facilitating coordinated efforts. -- `run(prompt_text: str, max_length: int = None) -> str`: Generate text based on a prompt. +**Long Term Memory**: +A component of the memory system that retains information over extended periods, enabling agents to recall and utilize past interactions and experiences. -**Usage Example:** -```python -from swarm_models import HuggingFaceLLM +**Output Schema**: +A structured format for the output generated by agents, often defined using data models like Pydantic's BaseModel. Output schemas ensure consistency and clarity in the information produced by agents. -model_id = "gpt2" -hugging_face_model = HuggingFaceLLM(model_id=model_id) +By understanding these terms, you can effectively build and orchestrate agents and swarms, leveraging their capabilities to perform complex, collaborative tasks. -prompt = "Once upon a time" -generated_text = hugging_face_model.run(prompt) -print(generated_text) -``` +-------------------------------------------------- -### 3. Anthropic (swarm_models.Anthropic) +# File: swarms\install\docker_setup.md -The Anthropic class enables interaction with Anthropic's large language models. +# Docker Setup Guide for Contributors to Swarms -**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) -``` -**Attributes:** +Welcome to the `swarms` project Docker setup guide. This document will help you establish a Docker-based environment for contributing to `swarms`. Docker provides a consistent and isolated environment, ensuring that all contributors can work in the same settings, reducing the "it works on my machine" syndrome. -- `model` (str): Name of the Anthropic model. +### Purpose -- `max_tokens_to_sample` (int, default=256): Maximum tokens to sample. +The purpose of this guide is to: -- `temperature` (float, optional): Temperature for text generation. +- Ensure contributors can quickly set up their development environment. +- Provide a consistent testing and deployment workflow. +- Introduce Docker basics and best practices. -- `top_k` (int, optional): Top-k sampling value. +### Scope -- `top_p` (float, optional): Top-p sampling value. +This guide covers: -- `streaming` (bool, default=False): Enable streaming mode. +- Installing Docker +- Cloning the `swarms` repository +- Building a Docker image +- Running the `swarms` application in a Docker container +- Running tests using Docker +- Pushing changes and working with Docker Hub -- `default_request_timeout` (int, optional): Default request timeout. -**Methods:** +## Docker Installation -- `run(prompt: str, stop: List[str] = None) -> str`: Generate text based on a prompt. +### Windows -**Usage Example:** -```python -from swarm_models import Anthropic +1. Download Docker Desktop for Windows from the official website. +2. Install Docker Desktop, ensuring that the "Use Windows containers instead of Linux containers" option is unchecked. +3. Start Docker Desktop and wait for the Docker engine to start. -anthropic = Anthropic() -prompt = "Once upon a time" -generated_text = anthropic.run(prompt) -print(generated_text) -``` +### macOS -This concludes the documentation for the "models" folder, providing you with tools to seamlessly integrate with various language models and APIs. Happy coding! +1. Download Docker Desktop for macOS from the official website. +2. Follow the installation instructions, drag-and-drop Docker into the Applications folder. +3. Start Docker Desktop from the Applications folder. --------------------------------------------------- +### Linux (Ubuntu) -# File: swarms\models\kosmos.md +1. Update your package index: `sudo apt-get update`. +2. Install packages to allow apt to use a repository over HTTPS. +3. Add Docker’s official GPG key. +4. Set up the stable repository. +5. Install the latest version of Docker Engine and containerd. -# `Kosmos` Documentation +```bash +sudo apt-get install docker-ce docker-ce-cli containerd.io +``` -## Introduction +6. Verify that Docker Engine is installed correctly by running the hello-world image. -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. +```bash +sudo docker run hello-world +``` -## Overview +### Post-installation Steps for Linux -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. +- Manage Docker as a non-root user. +- Configure Docker to start on boot. -## Class Definition +## Cloning the Repository -```python -class Kosmos: - def __init__(self, model_name="ydshieh/kosmos-2-patch14-224"): +```bash +git clone https://github.com/your-username/swarms.git +cd swarms ``` -## Usage +## Docker Basics -To use Kosmos, follow these steps: +### Dockerfile Overview -1. Initialize the Kosmos instance: +- Explain the structure and commands of a Dockerfile used in the `swarms` project. -```python -from swarm_models.kosmos_two import Kosmos +### Building the Image -kosmos = Kosmos() +```bash +docker build -t swarms-dev . ``` -2. Perform Multimodal Grounding: +### Running a Container -```python -kosmos.multimodal_grounding( - "Find the red apple in the image.", "https://example.com/apple.jpg" -) +```bash +docker run -it --rm swarms-dev ``` -### Example 1 - Multimodal Grounding - -```python -from swarm_models.kosmos_two import Kosmos +## Development Workflow with Docker -kosmos = Kosmos() +### Running the Application -kosmos.multimodal_grounding( - "Find the red apple in the image.", "https://example.com/apple.jpg" -) -``` +- Commands to run the `swarms` application within Docker. -3. Perform Referring Expression Comprehension: +### Making Changes -```python -kosmos.referring_expression_comprehension( - "Show me the green bottle.", "https://example.com/bottle.jpg" -) -``` +- How to make changes to the code and reflect those changes within the Docker container. -### Example 2 - Referring Expression Comprehension +### Running Tests -```python -from swarm_models.kosmos_two import Kosmos +- Instructions on running tests using `pytest` within the Docker environment. -kosmos = Kosmos() +## Docker Compose for Local Development -kosmos.referring_expression_comprehension( - "Show me the green bottle.", "https://example.com/bottle.jpg" -) -``` +- Introduce Docker Compose and its role in simplifying multi-container setups. +- Create a `docker-compose.yml` file for the `swarms` project. -4. Generate Referring Expressions: -```python -kosmos.referring_expression_generation( - "It is on the table.", "https://example.com/table.jpg" -) -``` +## Dockerfile -### Example 3 - Referring Expression Generation +Creating a Dockerfile for deploying the `swarms` framework to the cloud involves setting up the necessary environment to run your Python application, ensuring all dependencies are installed, and configuring the container to execute the desired tasks. Here's an example Dockerfile that sets up such an environment: -```python -from swarm_models.kosmos_two import Kosmos +```Dockerfile +# Use an official Python runtime as a parent image +FROM python:3.11-slim -kosmos = Kosmos() +# Set environment variables +ENV PYTHONDONTWRITEBYTECODE 1 +ENV PYTHONUNBUFFERED 1 -kosmos.referring_expression_generation( - "It is on the table.", "https://example.com/table.jpg" -) -``` +# Set the working directory in the container +WORKDIR /usr/src/swarm_cloud -5. Perform Grounded Visual Question Answering (VQA): +# Install system dependencies +RUN apt-get update \ + && apt-get -y install gcc \ + && apt-get clean -```python -kosmos.grounded_vqa("What is the color of the car?", "https://example.com/car.jpg") -``` +# Install Python dependencies +# COPY requirements.txt and pyproject.toml if you're using poetry for dependency management +COPY requirements.txt . +RUN pip install --upgrade pip +RUN pip install --no-cache-dir -r requirements.txt -### Example 4 - Grounded Visual Question Answering +# Install the 'swarms' package, assuming it's available on PyPI +ENV SWARM_API_KEY=your_swarm_api_key_here +ENV OPENAI_API_KEY=your_openai_key +RUN pip install swarms -```python -from swarm_models.kosmos_two import Kosmos +# Copy the rest of the application +COPY . . -kosmos = Kosmos() +# Add entrypoint script if needed +# COPY ./entrypoint.sh . +# RUN chmod +x /usr/src/swarm_cloud/entrypoint.sh -kosmos.grounded_vqa("What is the color of the car?", "https://example.com/car.jpg") -``` +# Expose port if your application has a web interface +# EXPOSE 5000 -6. Generate Grounded Image Captions: +# Define environment variable for the swarm to work +# Add Docker CMD or ENTRYPOINT script to run the application +# CMD python your_swarm_startup_script.py +# Or use the entrypoint script if you have one +# ENTRYPOINT ["/usr/src/swarm_cloud/entrypoint.sh"] -```python -kosmos.grounded_image_captioning("https://example.com/beach.jpg") +# If you're using `CMD` to execute a Python script, make sure it's executable +# RUN chmod +x your_swarm_startup_script.py ``` -### Example 5 - Grounded Image Captioning +To build and run this Docker image: -```python -from swarm_models.kosmos_two import Kosmos +1. Replace `requirements.txt` with your actual requirements file or `pyproject.toml` and `poetry.lock` if you're using Poetry. +2. Replace `your_swarm_startup_script.py` with the script that starts your application. +3. If your application requires an API key or other sensitive data, make sure to set these securely, perhaps using environment variables or secrets management solutions provided by your cloud provider. +4. If you have an entrypoint script, uncomment the `COPY` and `RUN` lines for `entrypoint.sh`. +5. If your application has a web interface, uncomment the `EXPOSE` line and set it to the correct port. -kosmos = Kosmos() +Now, build your Docker image: -kosmos.grounded_image_captioning("https://example.com/beach.jpg") +```sh +docker build -t swarm-cloud . ``` -7. Generate Detailed Grounded Image Captions: +And run it: -```python -kosmos.grounded_image_captioning_detailed("https://example.com/beach.jpg") +```sh +docker run -d --name my-swarm-app swarm-cloud ``` -### Example 6 - Detailed Grounded Image Captioning +For deploying to the cloud, you'll need to push your Docker image to a container registry (like Docker Hub or a private registry), then pull it from your cloud environment to run it. Cloud providers often have services specifically for this purpose (like AWS ECS, GCP GKE, or Azure AKS). The deployment process will involve: -```python -from swarm_models.kosmos_two import Kosmos +- Pushing the image to a registry. +- Configuring cloud services to run your image. +- Setting up networking, storage, and other cloud resources. +- Monitoring, logging, and potentially scaling your containers. -kosmos = Kosmos() +Remember to secure sensitive data, use tagged releases for your images, and follow best practices for operating in the cloud. -kosmos.grounded_image_captioning_detailed("https://example.com/beach.jpg") -``` -8. Draw Entity Boxes on Image: +-------------------------------------------------- -```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) -``` +# File: swarms\install\env.md -### Example 7 - Drawing Entity Boxes on Image +# Environment Variables -```python -from swarm_models.kosmos_two import Kosmos +## Overview -kosmos = Kosmos() +Swarms uses environment variables for configuration management and secure credential storage. This approach keeps sensitive information like API keys out of your code and allows for easy configuration changes across different environments. -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) -``` +## Core Environment Variables -9. Generate Boxes for Entities: +### Framework Configuration -```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" -) -``` +=== "Configuration Variables" -### Example 8 - Generating Boxes for Entities + | Variable | Description | Example | + |----------|-------------|---------| + | `SWARMS_VERBOSE_GLOBAL` | Controls global logging verbosity | `True` or `False` | + | `WORKSPACE_DIR` | Defines the workspace directory for agent operations | `agent_workspace` | -```python -from swarm_models.kosmos_two import Kosmos +### LLM Provider API Keys -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" -) -``` +=== "OpenAI" + ```bash + OPENAI_API_KEY="your-openai-key" + ``` -## How Kosmos Works +=== "Anthropic" + ```bash + ANTHROPIC_API_KEY="your-anthropic-key" + ``` -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: +=== "Groq" + ```bash + GROQ_API_KEY="your-groq-key" + ``` -1. **Initialization**: When you create a Kosmos instance, it loads the ydshieh/kosmos-2-patch14-224 model for multimodal tasks. +=== "Google" + ```bash + GEMINI_API_KEY="your-gemini-key" + ``` -2. **Processing Text and Images**: Kosmos can process both text prompts and images. It takes a textual prompt and an image URL as input. +=== "Hugging Face" + ```bash + HUGGINGFACE_TOKEN="your-huggingface-token" + ``` -3. **Task Execution**: Based on the task you specify, Kosmos generates informative responses by combining natural language understanding with image analysis. +=== "Perplexity AI" + ```bash + PPLX_API_KEY="your-perplexity-key" + ``` -4. **Drawing Entity Boxes**: You can use the `draw_entity_boxes_on_image` method to draw bounding boxes around entities in an image. +=== "AI21" + ```bash + AI21_API_KEY="your-ai21-key" + ``` -5. **Generating Boxes for Entities**: The `generate_boxes` method allows you to generate bounding boxes for entities mentioned in a prompt. +=== "Cohere" + ```bash + COHERE_API_KEY="your-cohere-key" + ``` -## Parameters +=== "Mistral AI" + ```bash + MISTRAL_API_KEY="your-mistral-key" + ``` -- `model_name`: The name or path of the Kosmos model to be used. By default, it uses the ydshieh/kosmos-2-patch14-224 model. +=== "Together AI" + ```bash + TOGETHER_API_KEY="your-together-key" + ``` -## Additional Information +### Tool Provider Keys -- 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. +=== "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" + ``` -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! +=== "Analytics & Monitoring" + ```bash + EXA_API_KEY="your-exa-key" + ``` +=== "Browser Automation" + ```bash + MULTION_API_KEY="your-multion-key" + ``` --------------------------------------------------- +## Security Best Practices -# File: swarms\models\layoutlm_document_qa.md +### Environment File Management -# `LayoutLMDocumentQA` Documentation +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 + ``` -## Introduction +### API Key Security -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. +!!! 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 -## Overview +### Template Configuration -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. +Create a `.env.example` template without actual values: -## Class Definition +```bash +# Required Configuration +OPENAI_API_KEY="" +ANTHROPIC_API_KEY="" +GROQ_API_KEY="" +WORKSPACE_DIR="agent_workspace" -```python -class LayoutLMDocumentQA(AbstractModel): - def __init__( - self, - model_name: str = "impira/layoutlm-document-qa", - task: str = "document-question-answering", - ): +# Optional Configuration +SWARMS_VERBOSE_GLOBAL="False" ``` -## Purpose +### Loading Environment Variables -The LayoutLMDocumentQA class serves the following primary purposes: +```python +from dotenv import load_dotenv +import os -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. +# Load environment variables +load_dotenv() -2. **Multimodal Understanding**: It combines natural language understanding with document layout analysis, making it suitable for documents with complex structures. +# Access variables +workspace_dir = os.getenv("WORKSPACE_DIR") +openai_key = os.getenv("OPENAI_API_KEY") +``` -## Parameters +## Environment Setup Guide -- `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". +=== "1. Install Dependencies" + ```bash + pip install python-dotenv + ``` -## Usage +=== "2. Create Environment File" + ```bash + cp .env.example .env + ``` -To use LayoutLMDocumentQA, follow these steps: +=== "3. Configure Variables" + - Open `.env` in your text editor + - Add your API keys and configuration + - Save the file -1. Initialize the LayoutLMDocumentQA instance: +=== "4. Verify Setup" + ```python + import os + from dotenv import load_dotenv -```python -from swarm_models import LayoutLMDocumentQA + load_dotenv() + assert os.getenv("OPENAI_API_KEY") is not None, "OpenAI API key not found" + ``` -layout_lm_doc_qa = LayoutLMDocumentQA() -``` +## Environment-Specific Configuration -### Example 1 - Initialization +=== "Development" + ```bash + WORKSPACE_DIR="agent_workspace" + SWARMS_VERBOSE_GLOBAL="True" + ``` -```python -layout_lm_doc_qa = LayoutLMDocumentQA() -``` +=== "Production" + ```bash + WORKSPACE_DIR="/var/swarms/workspace" + SWARMS_VERBOSE_GLOBAL="False" + ``` -2. Ask a question about a document and provide the document's image path: +=== "Testing" + ```bash + WORKSPACE_DIR="test_workspace" + SWARMS_VERBOSE_GLOBAL="True" + ``` -```python -question = "What is the total amount?" -image_path = "path/to/document_image.png" -answer = layout_lm_doc_qa(question, image_path) -``` +## Troubleshooting -### Example 2 - Document QA +### Common Issues -```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) -``` +???+ note "Environment Variables Not Loading" + - Verify `.env` file exists in project root + - Confirm `load_dotenv()` is called before accessing variables + - Check file permissions -## How LayoutLMDocumentQA Works +???+ note "API Key Issues" + - Verify key format is correct + - Ensure key has not expired + - Check for leading/trailing whitespace -LayoutLMDocumentQA employs a multimodal approach to document QA. Here's how it works: +???+ note "Workspace Directory Problems" + - Confirm directory exists + - Verify write permissions + - Check path is absolute when required -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. -2. **Question and Document**: You provide a question about the document and the image path of the document to the LayoutLMDocumentQA instance. +-------------------------------------------------- -3. **Multimodal Processing**: LayoutLMDocumentQA processes both the question and the document image. It combines layout-based analysis with natural language understanding. +# File: swarms\install\install.md -4. **Answer Generation**: The model generates an answer to the question based on its analysis of the document layout and content. +# Swarms Installation Guide -## 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. +You can install `swarms` with pip in a +[**Python>=3.10**](https://www.python.org/) environment. -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! +## Prerequisites --------------------------------------------------- +Before you begin, ensure you have the following installed: -# File: swarms\models\llama3.md +- Python 3.10 or higher: [Download Python](https://www.python.org/) +- pip (specific version recommended): `pip >= 21.0` +- git (for cloning the repository): [Download Git](https://git-scm.com/) -## Llava3 +## Installation Options +=== "pip (Recommended)" -```python -from transformers import AutoTokenizer, AutoModelForCausalLM -import torch -from swarm_models.base_llm import BaseLLM + #### Headless Installation + The headless installation of `swarms` is designed for environments where graphical user interfaces (GUI) are not needed, making it more lightweight and suitable for server-side applications. -class Llama3(BaseLLM): - """ - Llama3 class represents a Llama model for natural language generation. + ```bash + pip install swarms + ``` - 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. +=== "UV Installation" - 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. + UV is a fast Python package installer and resolver written in Rust. It's significantly faster than pip and provides better dependency resolution. - Methods: - run(task, *args, **kwargs): Generates a response for the given task. + === "Basic Installation" - """ + ```bash + # Install UV first + curl -LsSf https://astral.sh/uv/install.sh | sh - 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", - ) + # Install swarms using UV + uv pip install swarms + ``` - def run(self, task: str, *args, **kwargs): - """ - Generates a response for the given task. + === "Development Installation" - Args: - task (str): The user's task or input. + ```bash + # Clone the repository + git clone https://github.com/kyegomez/swarms.git + cd swarms - Returns: - str: The generated response. + # Install in editable mode + uv pip install -e . + ``` - """ - messages = [ - {"role": "system", "content": self.system_prompt}, - {"role": "user", "content": task}, - ] + For desktop installation with extras: - input_ids = self.tokenizer.apply_chat_template( - messages, add_generation_prompt=True, return_tensors="pt" - ).to(self.model.device) + ```bash + uv pip install -e .[desktop] + ``` - terminators = [ - self.tokenizer.eos_token_id, - self.tokenizer.convert_tokens_to_ids("<|eot_id|>"), - ] +=== "Development Installation" - 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 - ) -``` + === "Using virtualenv" --------------------------------------------------- + 1. **Clone the repository and navigate to the root directory:** -# File: swarms\models\models_available_overview.md + ```bash + git clone https://github.com/kyegomez/swarms.git + cd swarms + ``` -## The Swarms Framework: A Comprehensive Guide to Model APIs and Usage + 2. **Setup Python environment and activate it:** -### Introduction + ```bash + python3 -m venv venv + source venv/bin/activate + pip install --upgrade pip + ``` -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. + 3. **Install Swarms:** -### Overview of the Swarms Framework + - Headless install: -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. + ```bash + pip install -e . + ``` -### Getting Started with Swarms + - Desktop install: -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: + ```bash + pip install -e .[desktop] + ``` -#### Installation + === "Using Anaconda" -You can install the Swarms framework using pip: + 1. **Create and activate an Anaconda environment:** -```bash -pip install swarms -``` + ```bash + conda create -n swarms python=3.10 + conda activate swarms + ``` -#### Setting Up Environment Variables + 2. **Clone the repository and navigate to the root directory:** -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. + ```bash + git clone https://github.com/kyegomez/swarms.git + cd swarms + ``` -```bash -pip install python-dotenv -``` + 3. **Install Swarms:** -Create a `.env` file in your project directory and add your API keys and other settings: + - Headless install: -```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 -``` + ```bash + pip install -e . + ``` -### Using the Swarms Framework + - Desktop install: -Swarms supports a variety of models from different providers. Here are some examples of how to use these models within the Swarms framework. + ```bash + pip install -e .[desktop] + ``` -#### Using the Anthropic Model + === "Using Poetry" -The Anthropic model is one of the many models supported by Swarms. Here's how you can use it: + 1. **Clone the repository and navigate to the root directory:** -```python -import os -from swarm_models import Anthropic + ```bash + git clone https://github.com/kyegomez/swarms.git + cd swarms + ``` -# Load the environment variables -anthropic_api_key = os.getenv("ANTHROPIC_API_KEY") + 2. **Setup Python environment and activate it:** -# Create an instance of the Anthropic model -model = Anthropic(anthropic_api_key=anthropic_api_key) + ```bash + poetry env use python3.10 + poetry shell + ``` -# Define the task -task = "What is quantum field theory? What are 3 books on the field?" + 3. **Install Swarms:** -# Generate a response -response = model(task) + - Headless install: -# Print the response -print(response) -``` + ```bash + poetry install + ``` -#### Using the HuggingfaceLLM Model + - Desktop install: -HuggingfaceLLM allows you to use models from Hugging Face's vast repository. Here's an example: + ```bash + poetry install --extras "desktop" + ``` -```python -from swarm_models import HuggingfaceLLM +=== "Using Docker" -# Define the model ID -model_id = "NousResearch/Yarn-Mistral-7b-128k" + Docker is an excellent option for creating isolated and reproducible environments, suitable for both development and production. Contact us if there are any issues with the docker setup -# Create an instance of the HuggingfaceLLM model -inference = HuggingfaceLLM(model_id=model_id) + 1. **Pull the Docker image:** -# Define the task -task = "Once upon a time" + ```bash + docker pull swarmscorp/swarms:tagname -# Generate a response -generated_text = inference(task) -print(generated_text) -``` + ``` + 2. **Run the Docker container:** + ```bash + docker run -it --rm swarmscorp/swarms:tagname + ``` -#### Using the OpenAIChat Model + 3. **Build and run a custom Docker image:** -The OpenAIChat model is designed for conversational tasks. Here's how to use it: + ```dockerfile + # Use Python 3.11 instead of 3.13 + FROM python:3.11-slim -```python -import os -from swarm_models import OpenAIChat + # Set environment variables + ENV PYTHONDONTWRITEBYTECODE=1 \ + PYTHONUNBUFFERED=1 \ + WORKSPACE_DIR="agent_workspace" \ + OPENAI_API_KEY="your_swarm_api_key_here" -# Load the environment variables -openai_api_key = os.getenv("OPENAI_API_KEY") + # Set the working directory + WORKDIR /usr/src/swarms -# Create an instance of the OpenAIChat model -openai = OpenAIChat(openai_api_key=openai_api_key, verbose=False) + # Install system dependencies + RUN apt-get update && apt-get install -y \ + build-essential \ + gcc \ + g++ \ + gfortran \ + && rm -rf /var/lib/apt/lists/* -# Define the task -chat = openai("What are quantum fields?") -print(chat) -``` + # Install swarms package + RUN pip3 install -U swarm-models + RUN pip3 install -U swarms -#### Using the TogetherLLM Model + # Copy the application + COPY . . + ``` -TogetherLLM supports models from the Together ecosystem. Here's an example: +=== "Using Kubernetes" -```python -from swarms import TogetherLLM + Kubernetes provides an automated way to deploy, scale, and manage containerized applications. -# 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", -) + 1. **Create a Deployment YAML file:** -# Run the model -response = model.run("Generate a blog post about the best way to make money online.") -print(response) -``` + ```yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: swarms-deployment + spec: + replicas: 3 + selector: + matchLabels: + app: swarms + template: + metadata: + labels: + app: swarms + spec: + containers: + - name: swarms + image: kyegomez/swarms + ports: + - containerPort: 8080 + ``` -#### Using the Azure OpenAI Model + 2. **Apply the Deployment:** -The Azure OpenAI model is another powerful tool that can be integrated with Swarms. Here's how to use it: + ```bash + kubectl apply -f deployment.yaml + ``` -```python -import os -from dotenv import load_dotenv -from swarms import AzureOpenAI + 3. **Expose the Deployment:** -# Load the environment variables -load_dotenv() + ```bash + kubectl expose deployment swarms-deployment --type=LoadBalancer --name=swarms-service + ``` -# 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"), -) +=== "CI/CD Pipelines" -# Define the prompt -prompt = ( - "Analyze this load document and assess it for any risks and" - " create a table in markdown format." -) + Integrating Swarms into your CI/CD pipeline ensures automated testing and deployment. -# Generate a response -response = model(prompt) -print(response) -``` + #### Using GitHub Actions + ```yaml + # .github/workflows/ci.yml + name: CI -#### Using the GPT4VisionAPI Model + on: + push: + branches: [ main ] + pull_request: + branches: [ main ] -The GPT4VisionAPI model can analyze images and provide detailed insights. Here's how to use it: + jobs: + build: -```python -import os -from dotenv import load_dotenv -from swarms import GPT4VisionAPI + runs-on: ubuntu-latest -# Load the environment variables -load_dotenv() + steps: + - uses: actions/checkout@v2 + - name: Set up Python + uses: actions/setup-python@v2 + with: + python-version: 3.10 + - name: Install dependencies + run: | + python -m venv venv + source venv/bin/activate + pip install --upgrade pip + pip install -e . + - name: Run tests + run: | + source venv/bin/activate + pytest + ``` -# Get the API key from the environment variables -api_key = os.getenv("OPENAI_API_KEY") + #### Using Jenkins -# 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", -) + ```groovy + pipeline { + agent any -# Define the URL of the image to analyze -img = "ear.png" + stages { + stage('Clone repository') { + steps { + git 'https://github.com/kyegomez/swarms.git' + } + } + stage('Setup Python') { + steps { + sh 'python3 -m venv venv' + sh 'source venv/bin/activate && pip install --upgrade pip' + } + } + stage('Install dependencies') { + steps { + sh 'source venv/bin/activate && pip install -e .' + } + } + stage('Run tests') { + steps { + sh 'source venv/bin/activate && pytest' + } + } + } + } + ``` -# Define the task to perform on the image -task = "What is this image" +## Rust -# Run the GPT4VisionAPI on the image with the specified task -answer = gpt4vision.run(task, img, return_json=True) +=== "Cargo install" -# Print the answer -print(answer) -``` + Get started with the Rust implementation of Swarms. [Get started with the docs here](https://docs.swarms.world/en/latest/swarms_rs/overview/) -#### Using the QwenVLMultiModal Model + ```bash + cargo add swarms-rs + ``` -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: -```python -from swarms import QwenVLMultiModal -# Instantiate the QwenVLMultiModal model -model = QwenVLMultiModal( - model_name="Qwen/Qwen-VL-Chat", - device="cuda", - quantize=True, -) -# Run the model -response = model("Hello, how are you?", "https://example.com/image.jpg") +-------------------------------------------------- -# Print the response -print(response) -``` +# File: swarms\install\quickstart.md +## Quickstart -### Common Methods in Swarms +**Swarms** is an enterprise-grade, production-ready multi-agent collaboration framework that enables you to orchestrate agents to work collaboratively at scale to automate real-world activities. Follow this quickstart guide to get up and running with Swarms, including setting up your environment, building an agent, and leveraging multi-agent methods. -Swarms provides several common methods that are useful across different models. One of the most frequently used methods is `__call__`. +### **Requirements** -#### The `__call__` Method +- Python 3.10 or above +- `.env` file with API keys from your providers like `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` +- Set an environment variable for your workspace directory: + ```bash + WORKSPACE_DIR="agent_workspace" + ``` -The `__call__` method is used to run the model on a given task. Here is a generic example: +### **Installation** -```python -# Assuming `model` is an instance of any supported model -task = "Explain the theory of relativity." -response = model(task) -print(response) +To install Swarms, run: +```bash +$ pip install -U swarms ``` -This method abstracts the complexity of interacting with different model APIs, providing a consistent interface for executing tasks. - -### Common Settings in Swarms - -Swarms allows you to configure various settings to customize the behavior of the models. Here are some common settings: - -#### API Keys +### **Usage Example: Single Agent** -API keys are essential for authenticating and accessing the models. These keys are typically set through environment variables: +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 - -# Set API keys as environment variables -os.environ['OPENAI_API_KEY'] = 'your_openai_api_key' -os.environ['ANTHROPIC_API_KEY'] = 'your_anthropic_api_key' -``` - -#### 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: +from swarms.structs.agent import Agent -```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"), +# Initialize the agent with GPT-4o-mini model +agent = Agent( + agent_name="Financial-Analysis-Agent", + system_prompt="Analyze financial situations and provide advice...", + max_loops=1, + autosave=True, + dashboard=False, + verbose=True, + saved_state_path="finance_agent.json", + model_name="gpt-4o-mini", ) -``` - -### Advanced Usage and Best Practices - -To make the most out of the Swarms framework, consider the following best practices: - -#### Extensive Logging - -Use logging to monitor the behavior and performance of your models. The `loguru` library is recommended for its simplicity and flexibility: -```python -from loguru import logger - -# Log model interactions -logger.info("Running task on Anthropic model") -response = model(task) -logger.info(f"Response: {response}") -``` - -#### Error Handling - -Implement robust error handling to manage API failures and other issues gracefully: - -```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) +# 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) ``` -### Conclusion - -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, - -Swarms offers a unified interface that simplifies the process of model orchestration and execution. +#### **Agent Class** --------------------------------------------------- +- **Attributes:** + - `agent_name`: Name of the agent. + - `system_prompt`: System-level instruction guiding the agent's behavior. + - `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. + - `filtered_run(task: str)`: Runs agent with a filtered system prompt. -# File: swarms\models\nougat.md +----- -# `Nougat` Documentation +## Creating Agents from YAML -## Introduction -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. +### Step 1: Define Your Agents in a YAML File -## Overview +The `create_agents_from_yaml` function works by reading agent configurations from a YAML file. Below is an example of what your YAML file (`agents_config.yaml`) should look like this. Example YAML Configuration (`agents_config.yaml`): -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. +```yaml +agents: + - agent_name: "Financial-Analysis-Agent" + 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: false + dashboard: false + verbose: false + dynamic_temperature_enabled: false + user_name: "swarms_corp" + retry_attempts: 1 + context_length: 200000 + return_step_meta: false + output_type: "str" + temperature: 0.1 + max_tokens: 2000 + task: "Analyze tech stocks for 2024 investment strategy. Provide detailed analysis and recommendations." -## Class Definition + - 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: false + dynamic_temperature_enabled: false + user_name: "swarms_corp" + retry_attempts: 1 + context_length: 150000 + 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." -```python -class Nougat: - def __init__( - self, - model_name_or_path="facebook/nougat-base", - min_length: int = 1, - max_new_tokens: int = 30, - ): +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 ``` -## Purpose - -The Nougat class serves the following primary purposes: - -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. - -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. - -3. **Metadata Extraction**: Nougat can also extract metadata from PDF documents, providing essential details about the document, such as title, author, and publication date. - -## Parameters - -- `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. +### Key Configuration Fields: +- **agent_name**: Name of the agent. +- **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. -## Usage +--- -To use Nougat, follow these steps: +### Step 2: Create the Main Script -1. Initialize the Nougat instance: +Now, create the main Python script that will use the `create_agents_from_yaml` function. +### `main.py`: ```python -from swarm_models import Nougat - -nougat = Nougat() -``` +from swarms.agents.create_agents_from_yaml import create_agents_from_yaml -### Example 1 - Initialization +# Create agents and get task results +task_results = create_agents_from_yaml( + yaml_file="agents_config.yaml", + return_type="run_swarm" +) -```python -nougat = Nougat() +print(task_results) ``` -2. Transcribe a PDF image using Nougat: +### Example Run: -```python -markdown_transcription = nougat("path/to/pdf_file.png") +```bash +python main.py ``` -### Example 2 - PDF Transcription +This will: +1. Load agent configurations from `agents_config.yaml`. +2. Create the agents specified in the YAML file. +3. Run the tasks provided for each agent. +4. Output the task results to the console. -```python -nougat = Nougat() -markdown_transcription = nougat("path/to/pdf_file.png") -``` +--- -3. Extract information from a PDF: +### Step 3: Customize the Return Type -```python -information = nougat.extract_information("path/to/pdf_file.png") -``` +The `create_agents_from_yaml` function supports multiple return types. You can control what is returned by setting the `return_type` parameter to `"agents"`, `"tasks"`, or `"both"`. -### Example 3 - Information Extraction +1. **Return Only Agents** +To create agents but not run tasks, set `return_type="agents"`: ```python -nougat = Nougat() -information = nougat.extract_information("path/to/pdf_file.png") +agents = create_agents_from_yaml(yaml_file, return_type="agents") +for agent in agents: + print(f"Agent {agent.agent_name} created.") ``` -4. Extract metadata from a PDF: +2. **Return Only Task Results** +If you only care about the task results and not the agent objects, set `return_type="tasks"`: ```python -metadata = nougat.extract_metadata("path/to/pdf_file.png") +task_results = create_agents_from_yaml(yaml_file, return_type="tasks") +for result in task_results: + print(f"Agent {result['agent_name']} executed task '{result['task']}' with output: {result['output']}") ``` -### Example 4 - Metadata Extraction +3. **Return Both Agents and Task Results** +To return both the list of created agents and task results, use `return_type="both"`: ```python -nougat = Nougat() -metadata = nougat.extract_metadata("path/to/pdf_file.png") +agents, task_results = create_agents_from_yaml(yaml_file, return_type="both") +# Process agents and tasks separately ``` -## How Nougat Works -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: - -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. +## Step 4: YAML Structure for Multiple Agents -2. **Processing PDFs**: Nougat can process PDFs as input. You can provide the path to a PDF document. +The YAML file can define any number of agents, each with its own unique configuration. You can scale this setup by adding more agents and tasks to the `agents` list within the YAML file. -3. **Image Processing**: The processor converts PDF pages into images, which are then encoded by the model. +```yaml +agents: + - agent_name: "Agent1" + # Agent1 config... -4. **Transcription**: Nougat generates Markdown transcriptions of PDF content, ensuring a minimum length and respecting the token limit. + - agent_name: "Agent2" + # Agent2 config... -5. **Information Extraction**: Information extraction involves parsing the Markdown transcription to identify key details or content of interest. + - agent_name: "Agent3" + # Agent3 config... +``` -6. **Metadata Extraction**: Metadata extraction involves identifying and extracting document metadata, such as title, author, and publication date. +Each agent will be initialized according to its configuration, and tasks (if provided) will be executed automatically. -## Additional Information +--- -- 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. +## Integrating External Agents +Integrating external agents from other agent frameworks is easy with swarms. -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! +Steps: --------------------------------------------------- +1. Create a new class that inherits `Agent` +2. Create a `.run(task: str) -> str` method that runs the agent and returns the response. +3. The new Agent must return a string of the response. But you may add additional methods to save the output to JSON. -# File: swarms\models\openai.md -# `BaseOpenAI` and `OpenAI` Documentation +### Griptape Example -## Table of Contents +For example, here's an example on how to create an agent from griptape. -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) +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. ---- -## 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 - -### 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 +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, +) -```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) -# Generate text asynchronously -async_prompt = "Translate 'Thank you' into German." -async_result = openai.generate_async(async_prompt, max_tokens=30) +# 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, + # Add additional settings + ) -# Access the result of an asynchronous generation -async_result_text = async_result.get() -``` + # 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 (you can modify this parsing based on task structure) + url, filename = task.split( + "," + ) # Example of splitting task string + # Execute the Griptape agent with the task inputs + result = self.agent.run(url.strip(), filename.strip()) + # Return the final result as a string + return str(result) -### 6.3 Advanced Configuration -```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) +# Example usage: +griptape_swarms_agent = GriptapeSwarmsAgent() +output = griptape_swarms_agent.run( + "https://griptape.ai, griptape.txt" +) +print(output) ``` -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. +### Key Components: +1. **GriptapeSwarmsAgent**: A custom class that inherits from the `SwarmsAgent` class and integrates the Griptape agent. +2. **run(task: str) -> str**: A method that takes a task string, processes it (e.g., splitting into a URL and filename), and runs the Griptape agent with the provided inputs. +3. **Griptape Tools**: The tools integrated into the Griptape agent (e.g., `WebScraperTool`, `PromptSummaryTool`, `FileManagerTool`) allow for web scraping, summarization, and file management. --------------------------------------------------- +You can now easily plug this custom Griptape agent into the **Swarms Framework** and use it to run tasks! -# File: swarms\models\openai_chat.md -# `OpenAIChat` Documentation -## Table of Contents -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) +## Overview of Swarm Architectures in the Swarms Framework --- -## 1. Introduction - -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. - -## 3. Class Architecture - -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. - -## 4. Class Attributes - -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"). | - -## 5. Methods - -### 5.1 Construction - -#### 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: []). - -### 5.2 Configuration - -#### 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. - -#### 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 - -#### 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. +### 1. **Sequential Workflow** -### 5.4 Generation +**Overview**: The `SequentialWorkflow` enables tasks to be executed one after the other. Each agent processes its task and passes the output to the next agent in the sequence. -#### 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. +#### Mermaid Graph: -#### 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. +```mermaid +graph TD; + A[Task Input] --> B[Blog Generator Agent]; + B --> C[Summarizer Agent]; + C --> D[Task Output]; +``` -### 5.5 Tokenization +#### Code Example: -#### 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 +```python +from swarms import Agent, SequentialWorkflow - token IDs. - -## 6. Usage Examples - -### Example 1: Initializing `OpenAIChat` +# 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 +) -```python -from swarm_models import OpenAIChat +# Create Sequential workflow +workflow = SequentialWorkflow(agents=[agent1, agent2], max_loops=1) -# Initialize OpenAIChat with model name and API key -openai_chat = OpenAIChat(model_name="gpt-3.5-turbo", openai_api_key="YOUR_API_KEY") +# Run workflow +output = workflow.run("Generate a blog post on how swarms of agents can help businesses grow.") +print(output) ``` -### Example 2: Sending Messages and Generating Responses +--- -```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!", -] +### 2. **Agent Rearrange** -# Set the conversation as the prefix messages -openai_chat.prefix_messages = conversation +**Overview**: `AgentRearrange` allows the orchestration of agents in both sequential and parallel configurations. The user can define a flexible flow of tasks between agents. -# Generate a response -user_message = "User: Tell me another joke." -response = openai_chat.generate([user_message]) +#### Mermaid Graph: -# Print the generated response -print( - response[0][0].text -) # Output: "Assistant: Why don't scientists trust atoms? Because they make up everything!" +```mermaid +graph TD; + A[Director Agent] --> B[Worker 1 Agent]; + A --> C[Worker 2 Agent]; + B --> D[Task Completed]; + C --> D[Task Completed]; ``` -### Example 3: Asynchronous Generation +#### Code Example: ```python -import asyncio - +from swarms import Agent, AgentRearrange -# 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) +# 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 the flow and create the rearranged system +flow = "Director -> Worker1 -> Worker2" +agent_system = AgentRearrange(agents=[director, worker1, worker2], flow=flow) -# Run the asynchronous generation function -asyncio.run(generate_responses()) +# Run it +output = agent_system.run("Create a YouTube transcript and summary") +print(output) ``` -## 7. Additional Information -- 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. --- -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. - --------------------------------------------------- - -# File: swarms\models\openai_function_caller.md - -# OpenAIFunctionCaller Documentation - -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. - -## Class Definition - -### OpenAIFunctionCaller - -A class that represents a caller for OpenAI chat completions. - -### Attributes - -| 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. | - -### Methods - -#### `check_api_key` - -Checks if the API key is provided and retrieves it from the environment if not. - -| Parameter | Type | Description | -|---------------|--------|--------------------------------------| -| None | | | - -**Returns:** - -| Type | Description | -|--------|--------------------------------------| -| `str` | The API key. | - -#### `run` - -Runs the chat completion with the given task and returns the generated completion. - -| 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. | - -**Returns:** - -| Type | Description | -|--------|-----------------------------------------------| -| `str` | The generated completion. | - -#### `convert_to_dict_from_base_model` - -Converts a `BaseModel` to a dictionary. - -| Parameter | Type | Description | -|-------------|------------|--------------------------------------| -| `base_model`| `BaseModel`| The BaseModel to be converted. | - -**Returns:** - -| Type | Description | -|--------|--------------------------------------| -| `dict` | A dictionary representing the BaseModel.| - -#### `convert_list_of_base_models` - -Converts a list of `BaseModels` to a list of dictionaries. - -| Parameter | Type | Description | -|--------------|-----------------|--------------------------------------| -| `base_models`| `List[BaseModel]`| A list of BaseModels to be converted.| - -**Returns:** +### 4. **Mixture of Agents** -| Type | Description | -|--------|-----------------------------------------------| -| `List[Dict]` | A list of dictionaries representing the converted BaseModels. | +**Overview**: `MixtureOfAgents` is a parallelized architecture where agents perform tasks concurrently and then feed their results back into a loop for final aggregation. This is useful for highly parallelizable tasks. -## Usage Examples +#### Mermaid Graph: -Here are three examples demonstrating different ways to use the `OpenAIFunctionCaller` class: +```mermaid +graph TD; + A[Director Agent] --> B[Accountant 1]; + A --> C[Accountant 2]; + B --> D[Final Aggregation]; + C --> D[Final Aggregation]; +``` -### Example 1: Production-Grade Claude Artifacts +#### Code Example: ```python -import openai -from swarm_models.openai_function_caller import OpenAIFunctionCaller -from swarms.artifacts.main_artifact import Artifact - - -# Pydantic is a data validation library that provides data validation and parsing using Python type hints. - +from swarms import Agent, OpenAIChat, MixtureOfAgents -# 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, -) +# Initialize agents +director = Agent(agent_name="Director", system_prompt="Directs tasks", llm=OpenAIChat(), max_loops=1) +accountant1 = Agent(agent_name="Accountant1", system_prompt="Prepare financial statements", llm=OpenAIChat(), max_loops=1) +accountant2 = Agent(agent_name="Accountant2", system_prompt="Audit financial records", llm=OpenAIChat(), max_loops=1) +# Create Mixture of Agents swarm +swarm = MixtureOfAgents(name="Mixture of Accountants", agents=[director, accountant1, accountant2], layers=3, final_agent=director) -# 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) +# Run the swarm +output = swarm.run("Prepare financial statements and audit financial records") +print(output) ``` -### Example 2: Prompt Generator - -```python -from swarm_models.openai_function_caller import OpenAIFunctionCaller -from pydantic import BaseModel, Field -from typing import Sequence +--- +### 5. **Spreadsheet Swarm** -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", - ) +**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: -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", - ) +```mermaid +graph TD; + A[Spreadsheet Swarm] --> B[Twitter Agent]; + A --> C[Instagram Agent]; + A --> D[Facebook Agent]; + A --> E[LinkedIn Agent]; + A --> F[Email Agent]; +``` +#### Code Example: -# 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, -) +```python +from swarms import Agent +from swarms.structs.spreadsheet_swarm import SpreadSheetSwarm +# Initialize agents for different marketing platforms using model_name +agents = [ + 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 + ), +] -# 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." +# Create the Spreadsheet Swarm +swarm = SpreadSheetSwarm( + agents=agents, + save_file_path="real_estate_marketing_spreadsheet.csv", + run_all_agents=False, + max_loops=2 ) -print(out) +# Run the swarm +swarm.run("Create posts to promote luxury properties in North Texas.") ``` -### Example 3: Sentiment Analysis - -```python -from swarm_models.openai_function_caller import OpenAIFunctionCaller -from pydantic import BaseModel, Field - - -# 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( - ..., - description="The text to be analyzed for sentiment rating", - ) - rating: str = Field( - ..., - description="The sentiment rating of the text from 0.0 to 1.0", - ) - - -# 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. - -# 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, -) +--- +These are the key swarm architectures available in the **Swarms Framework**. Each one is designed to solve different types of multi-agent orchestration problems, from sequential tasks to large-scale parallel processing. -# 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) -``` +### Overview of Swarm Architectures +#### **Workflow Classes** -## Additional Information and Tips +- **SequentialWorkflow:** + - 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. -- 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. +#### **Swarm Architectures** -## References and Resources +- **Hierarchical Swarms:** + - Implements top-down control, where a boss agent coordinates tasks among sub-agents. + +- **Spreadsheet Swarm:** + - A large-scale swarm architecture for managing multiple agents working concurrently. -- [OpenAI API Documentation](https://beta.openai.com/docs/) -- [Pydantic Documentation](https://pydantic-docs.helpmanual.io/) -- [Loguru Logger Documentation](https://loguru.readthedocs.io/) -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. -------------------------------------------------- -# File: swarms\models\openai_tts.md - -# `OpenAITTS` Documentation +# File: swarms\install\workspace_manager.md -## 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) +# Swarms Framework Environment Configuration -## 1. Overview +This guide details the environment variables used in the Swarms framework for configuration and customization of your agent-based applications. -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. +## Configuration Setup -### 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. +Create a `.env` file in your project's root directory to configure the Swarms framework. This file will contain all necessary environment variables for customizing your agent's behavior, logging, and analytics. -## 2. Installation +## Environment Variables -To use the `OpenAITTS` model, you need to install the necessary dependencies. You can do this using `pip`: +### Core Variables +#### `WORKSPACE_DIR` +- **Purpose**: Defines the directory where all agent states and execution logs are stored +- **Type**: String (path) +- **Default**: `./workspace` +- **Example**: ```bash -pip install swarms requests wave +WORKSPACE_DIR=/path/to/your/workspace ``` +- **Usage**: + - Stores JSON files containing agent states + - Maintains execution history + - Keeps track of agent interactions + - Preserves conversation logs -## 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: +#### `SWARMS_AUTOUPDATE_ON` +- **Purpose**: Controls automatic updates of the Swarms framework +- **Type**: Boolean +- **Default**: `false` +- **Example**: +```bash +SWARMS_AUTOUPDATE_ON=true +``` +- **Features**: + - Automatically updates to the latest stable version + - Ensures you have the newest features + - Maintains compatibility with the latest improvements + - Handles dependency updates +- **Considerations**: + - Set to `false` if you need version stability + - Recommended `true` for development environments + - Consider system requirements for auto-updates + - May require restart after updates -```python -from swarm_models.openai_tts import OpenAITTS +### Telemetry Configuration -# 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", -) +#### `USE_TELEMETRY` +- **Purpose**: Controls whether telemetry data is collected +- **Type**: Boolean +- **Default**: `false` +- **Example**: +```bash +USE_TELEMETRY=true ``` +- **Data Collected**: + - Agent performance metrics + - Execution time statistics + - Memory usage + - Error rates + - System health indicators -#### 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"). +### Analytics Integration -### Running TTS +#### `SWARMS_API_KEY` +- **Purpose**: Authentication key for the Swarms Analytics Suite +- **Type**: String +- **Required**: Yes, for analytics features +- **Example**: +```bash +SWARMS_API_KEY=your_api_key_here +``` +- **Features**: + - Real-time agent execution tracking + - Usage analytics + - Performance monitoring + - Cost tracking + - Custom metrics -Once the `OpenAITTS` instance is initialized, you can use it to convert text to speech using the `run` method: +## Getting Started -```python -# Generate speech from text -speech_data = tts.run("Hello, world!") +1. Create a new `.env` file: +```bash +touch .env ``` -#### Parameters: -- `task` (str): The text you want to convert to speech. - -#### Returns: -- `speech_data` (bytes): The generated speech data. +2. Add your configuration: +```bash +# Basic configuration +WORKSPACE_DIR=./my_workspace -### Running TTS and Saving +# Enable auto-updates +SWARMS_AUTOUPDATE_ON=true -You can also use the `run_and_save` method to generate speech from text and save it to a file: +# Enable telemetry +USE_TELEMETRY=true -```python -# Generate speech from text and save it to a file -speech_data = tts.run_and_save("Hello, world!") +# Add your Swarms API key +SWARMS_API_KEY=your_api_key_here ``` -#### Parameters: -- `task` (str): The text you want to convert to speech. +3. Obtain your API key: + - Visit [swarms.ai](https://swarms.ai) + - Create an account or log in + - Navigate to the API section + - Generate your unique API key -#### Returns: -- `speech_data` (bytes): The generated speech data. +## Best Practices -## 4. Examples +1. **Security**: + - Never commit your `.env` file to version control + - Add `.env` to your `.gitignore` file + - Keep your API keys secure and rotate them periodically -### Basic Usage +2. **Workspace Organization**: + - Use descriptive workspace directory names + - Implement regular cleanup of old logs + - Monitor workspace size to prevent disk space issues -Here's a basic example of how to use the `OpenAITTS` module to generate speech from text: +3. **Telemetry Management**: + - Enable telemetry in development for debugging + - Consider privacy implications in production + - Review collected data periodically -```python -from swarm_models.openai_tts import OpenAITTS +4. **Auto-Update Management**: + - Test updates in development before enabling in production + - Keep backups before enabling auto-updates + - Monitor system resources during updates + - Schedule updates during low-traffic periods -# 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", -) +## Examples -# Generate speech from text -speech_data = tts.run("Hello, world!") +### Basic Development Setup +```bash +WORKSPACE_DIR=./dev_workspace +SWARMS_AUTOUPDATE_ON=true +USE_TELEMETRY=true +SWARMS_API_KEY=sk_test_xxxxxxxxxxxx ``` -### Saving the Output - -You can save the generated speech to a WAV file using the `run_and_save` method: - -```python -# Generate speech from text and save it to a file -speech_data = tts.run_and_save("Hello, world!") +### Production Setup +```bash +WORKSPACE_DIR=/var/log/swarms/prod_workspace +SWARMS_AUTOUPDATE_ON=false +USE_TELEMETRY=true +SWARMS_API_KEY=sk_prod_xxxxxxxxxxxx ``` -## 5. Advanced Options +### Testing Environment +```bash +WORKSPACE_DIR=./test_workspace +SWARMS_AUTOUPDATE_ON=true +USE_TELEMETRY=false +SWARMS_API_KEY=sk_test_xxxxxxxxxxxx +``` -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. +## Troubleshooting -## 6. Troubleshooting +Common issues and solutions: -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. +1. **Workspace Access Issues**: + - Ensure proper file permissions + - Verify the directory exists + - Check disk space availability -## 7. References +2. **API Key Problems**: + - Confirm key is properly formatted + - Verify key hasn't expired + - Check for proper environment variable loading -- [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) +3. **Telemetry Issues**: + - Confirm network connectivity + - Verify firewall settings + - Check for proper boolean values -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. +4. **Auto-Update Issues**: + - Check internet connectivity + - Verify sufficient disk space + - Ensure proper permissions for updates + - Check system compatibility requirements --------------------------------------------------- +## Additional Resources -# File: swarms\models\vilt.md +- [Swarms Framework Documentation](https://github.com/kyegomez/swarms) +- [Swarms Analytics Dashboard](https://swarms.ai) +- [API Reference](https://swarms.ai/docs/api) -# `Vilt` Documentation +-------------------------------------------------- -## Introduction +# File: swarms\memory\diy_memory.md -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. +# Integrating the Agent Class with Memory Systems/RAG in the Swarms Memory Framework -## Overview +In this guide, we will cover how to integrate various memory systems from the Swarms Memory framework into an agent class. The Swarms Memory framework allows for the integration of different database-backed memory systems, enabling agents to retain and query long-term knowledge effectively. We'll walk through examples of integrating with Pinecone, ChromaDB, and Faiss, showcasing how to configure custom functions and embed memory functionality into an agent class. -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. +## Installation -## Class Definition +First, you need to install the Swarms Memory package: -```python -class Vilt: - def __init__(self): - """ - Initialize the Vilt model. - """ +```bash +$ pip install swarms swarms-memory ``` -## Usage -To use the Vilt model, follow these steps: +### Integrating ChromaDB with the Agent Class -1. Initialize the Vilt model: +ChromaDB is a simple, high-performance vector store for use with embeddings. Here's how you can integrate ChromaDB: ```python -from swarm_models import Vilt - -model = Vilt() -``` - -2. Call the model with a text question and an image URL: +from swarms_memory import ChromaDB +from swarms.structs.agent import Agent -```python -output = model( - "What is this image?", "http://images.cocodataset.org/val2017/000000039769.jpg" +# Initialize ChromaDB memory +chromadb_memory = ChromaDB( + metric="cosine", + output_dir="finance_agent_rag", ) -``` -### Example 1 - Image Questioning +# 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.", + model_name="gpt-4o-mini", + long_term_memory=chromadb_memory, +) -```python -model = Vilt() -output = model( - "What are the objects in this image?", - "http://images.cocodataset.org/val2017/000000039769.jpg", +# Run a query +response = agent.run( + "What are the components of a startup's stock incentive equity plan?" ) -print(output) +print(response) ``` -### Example 2 - Image Analysis +### Integrating Faiss with the Agent Class + +Faiss is a library for efficient similarity search and clustering of dense vectors. Here's how you can integrate Faiss: ```python -model = Vilt() -output = model( - "Describe the scene in this image.", - "http://images.cocodataset.org/val2017/000000039769.jpg", -) -print(output) -``` +from typing import List, Dict, Any +from swarms_memory.faiss_wrapper import FAISSDB +from swarms import Agent +from swarm_models import Anthropic +from transformers import AutoTokenizer, AutoModel +import torch +import os -### Example 3 - Visual Knowledge Retrieval +# Custom embedding function using a HuggingFace model +def custom_embedding_function(text: str) -> List[float]: + tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased") + model = AutoModel.from_pretrained("bert-base-uncased") + inputs = tokenizer( + text, + return_tensors="pt", + padding=True, + truncation=True, + max_length=512, + ) + with torch.no_grad(): + outputs = model(**inputs) + embeddings = ( + outputs.last_hidden_state.mean(dim=1).squeeze().tolist() + ) + return embeddings -```python -model = Vilt() -output = model( - "Tell me more about the landmark in this image.", - "http://images.cocodataset.org/val2017/000000039769.jpg", +# Initialize the FAISS memory wrapper +faiss_memory = FAISSDB( + dimension=768, + index_type="Flat", + embedding_function=custom_embedding_function, + metric="cosine", ) -print(output) -``` -## How Vilt Works +# Model +model = Anthropic(anthropic_api_key=os.getenv("ANTHROPIC_API_KEY")) -Vilt operates by combining text and image information to generate meaningful answers to questions about the provided image. Here's how it works: +# Initialize the agent with Faiss memory +agent = Agent( + agent_name="Financial-Analysis-Agent", + system_prompt="Agent system prompt here", + agent_description="Agent performs financial analysis.", + llm=model, + long_term_memory=faiss_memory, +) -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. +# Run a query +agent.run("Explain the differences between various types of financial instruments.") +``` -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. +## Mermaid Graphs for Visualizing Integration -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. +To help visualize the integration process, here's a Mermaid graph illustrating how an agent interacts with the memory systems: -4. **Output**: The predicted answer is returned as the output of the model. +```mermaid +graph TD; + A[Agent] -->|Queries| B[Memory System] + B --> C{Pinecone / ChromaDB / Faiss} + C --> D[Embedding Function] + D --> E[LLM Model] + E --> F[Query Results] + F -->|Returns| A +``` -## Parameters +This graph shows the flow from the agent sending queries to the memory system, which processes them using the embedding function and LLM model, and finally returns the results back to the agent. -Vilt does not require any specific parameters during initialization. It is pre-configured to work with the "dandelin/vilt-b32-finetuned-vqa" model. +## Conclusion -## Additional Information +Integrating various memory systems from the Swarms Memory framework into the agent class enables the creation of powerful, memory-augmented agents capable of retaining and recalling information over time. Whether you're using Pinecone, ChromaDB, or Faiss, the process involves initializing the memory system, embedding functions, and then passing this memory system to the agent class. The examples and visualizations provided should help you get started with building your own memory-augmented agents. -- 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. +Happy coding! -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! -------------------------------------------------- @@ -60322,150 +50678,6 @@ Track your credit usage through our comprehensive logging and reporting features !!! info "Need Help?" For additional questions or custom pricing options, please contact our support team at [kye@swarms.world](mailto:kye@swarms.world). --------------------------------------------------- - -# File: swarms_cloud\architecture.md - -# Under The Hood: The Swarm Cloud Serving Infrastructure ------------------------------------------------------------------ - -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 - -1. **The Gateway:** Your API request first arrives at an EC2 instance running SkyPilot, a lightweight controller. - -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: - -- **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. - -- **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: - -``` -servers/ - / - sky-serve.yaml # Deployment configuration file - / - sky-serve.yaml - ... - -``` - -- **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. - -**Commands:** - -- `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). - -**Additional Commands:** - -- `sky serve update`: Updates a running SkyServe service. - -- `sky serve status`: Shows the status of deployed SkyServe services. - -- `sky serve down`: Tears down (stops and removes) a SkyServe service. - -- `sky serve logs`: Tails the logs of a running SkyServe service, providing valuable insights into its operation. - -By leveraging these commands, infrastructure engineers can efficiently manage the deployment and lifecycle of models within the multi-cloud environment. - -**Building the Cluster and Accessing the Model:** - -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. - -### Understanding the `sky-serve.yaml` Configuration - -The `sky-serve.yaml` file plays a crucial role in defining the deployment parameters for your model. This file typically includes properties such as: - -- **Image:** Specifies the Docker image containing your model code and dependencies. - -- **Replicas:** Defines the number of model replicas to be deployed in the Swarm cluster. This allows for load balancing and fault tolerance. - -- **Resources:** Sets memory and CPU resource constraints for the deployed model containers. - -- **Networking:** Configures network settings for communication within the sky clusters and with the outside world. - -**Benefits of Our Infrastructure:** - -- **Multi-Cloud Flexibility:** Deploy models seamlessly across AWS and Azure, taking advantage of whichever platform best suits your needs. - -- **Scalability:** Easily scale model deployments up or down based on traffic demands. - -- **Cost Optimization:** The intelligent routing by SkyPilot helps optimize costs by utilizing the most cost-effective cloud resources. - -- **Simplified Management:** Manage models across clouds with a single set of commands using `sky serve`. - -### Deep Dive: Technical Architecture - -**Cloud Considerations:** - -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: - -- **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. - -- **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. - -- **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. - -- **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. - -**sky clusters Clusters** - -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: - -- **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. - -- **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. - -- **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. - -**SkyPilot - The Orchestrator** - -SkyPilot, the lightweight controller running on an EC2 instance, plays a central role in this infrastructure. Here's a deeper look at its functionalities: - -- **API Gateway Integration:** SkyPilot can be integrated with your API gateway or service mesh to receive incoming requests for model predictions. - -- **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. - -- **Cloud Provider Interaction:** SkyPilot interacts with the chosen cloud provider's APIs to manage resources required for the sky clusters cluster and model deployment. - -- **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. - -- **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. - -**Advanced Considerations** - -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: - -- **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. - -- **Model Versioning and Rollbacks:** Implement a model versioning strategy to track changes and facilitate rollbacks to previous versions if necessary. - -- **A/B Testing:** Integrate A/B testing frameworks to evaluate the performance of different model versions and configurations before full-scale deployment. - -- **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. - -By understanding these technical aspects and considerations, infrastructure engineers can effectively manage and optimize our multi-cloud serving model infrastructure. - -### Conclusion - -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. - -This understanding empowers both users and infrastructure engineers to leverage this technology effectively for deploying and managing your machine learning models at scale. - - -------------------------------------------------- # File: swarms_cloud\best_practices.md @@ -67680,100 +57892,6 @@ 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 # ChromaDB Documentation @@ -73117,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 -``` - - - --------------------------------------------------- -