+
@@ -213,7 +213,7 @@ This feature is perfect for rapid prototyping, complex task decomposition, and c
-----
-## šļø Multi-Agent Architectures For Production Deployments
+## šļø Available Multi-Agent Architectures
`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.
@@ -753,7 +753,6 @@ Explore comprehensive examples and tutorials to learn how to use Swarms effectiv
| **Model Providers** | Ollama | Local Ollama model integration | [Ollama Examples](https://docs.swarms.world/en/latest/swarms/examples/ollama/) |
| **Model Providers** | OpenRouter | OpenRouter model integration | [OpenRouter Examples](https://docs.swarms.world/en/latest/swarms/examples/openrouter/) |
| **Model Providers** | XAI | XAI model integration | [XAI Examples](https://docs.swarms.world/en/latest/swarms/examples/xai/) |
-| **Model Providers** | VLLM | VLLM integration | [VLLM Examples](https://docs.swarms.world/en/latest/swarms/examples/vllm_integration/) |
| **Model Providers** | Llama4 | Llama4 model integration | [Llama4 Examples](https://docs.swarms.world/en/latest/swarms/examples/llama4/) |
| **Multi-Agent Architecture** | HierarchicalSwarm | Hierarchical agent orchestration | [HierarchicalSwarm Examples](https://docs.swarms.world/en/latest/swarms/examples/hierarchical_swarm_example/) |
| **Multi-Agent Architecture** | Hybrid Hierarchical-Cluster Swarm | Advanced hierarchical patterns | [HHCS Examples](https://docs.swarms.world/en/latest/swarms/examples/hhcs_examples/) |
@@ -835,7 +834,7 @@ Join our community of agent engineers and researchers for technical support, cut
| š¦ Twitter | Latest news and announcements | [@swarms_corp](https://twitter.com/swarms_corp) |
| š„ 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) |
+| š« Events | Join our community events | [Sign up here](https://lu.ma/swarms_calendar) |
| š Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) |
------
@@ -854,6 +853,8 @@ If you use **swarms** in your research, please cite the project by referencing t
version = {latest}
```
+---
+
# License
Swarms is licensed under the Apache License 2.0. [Learn more here](./LICENSE)
diff --git a/docs/examples/agent_stream.md b/docs/examples/agent_stream.md
index 79c0a8ef..53318950 100644
--- a/docs/examples/agent_stream.md
+++ b/docs/examples/agent_stream.md
@@ -58,5 +58,5 @@ If you'd like technical support, join our Discord below and stay updated on our
| š¦ 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 |
+| š« Events | [Sign up here](https://lu.ma/swarms_calendar) | Join our community events |
diff --git a/docs/examples/cookbook_index.md b/docs/examples/cookbook_index.md
index 624d82e6..34da22c0 100644
--- a/docs/examples/cookbook_index.md
+++ b/docs/examples/cookbook_index.md
@@ -47,7 +47,7 @@ This index provides a categorized list of examples and tutorials for using the S
| š¦ 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 |
+| š« Events | [Sign up here](https://lu.ma/swarms_calendar) | Join our community events |
## Contributing
diff --git a/docs/examples/hiring_swarm.md b/docs/examples/hiring_swarm.md
index 93eace38..4b7d6186 100644
--- a/docs/examples/hiring_swarm.md
+++ b/docs/examples/hiring_swarm.md
@@ -367,4 +367,4 @@ You can customize the Hiring Swarm by:
| š¦ 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 |
+| š« Events | [Sign up here](https://lu.ma/swarms_calendar) | Join our community events |
diff --git a/docs/examples/index.md b/docs/examples/index.md
index bb1ed712..684e9f15 100644
--- a/docs/examples/index.md
+++ b/docs/examples/index.md
@@ -58,7 +58,6 @@ This index organizes **100+ production-ready examples** from our [Swarms Example
| Claude | [Claude 4 Example](https://github.com/kyegomez/swarms/blob/master/examples/models/claude_4_example.py) | Anthropic Claude 4 model integration for advanced reasoning capabilities |
| Swarms Claude | [Swarms Claude Example](https://github.com/kyegomez/swarms/blob/master/examples/models/swarms_claude_example.py) | Optimized Claude integration within the Swarms framework |
| Lumo | [Lumo Example](https://github.com/kyegomez/swarms/blob/master/examples/models/lumo_example.py) | Lumo AI model integration for specialized tasks |
-| VLLM | [VLLM Example](https://github.com/kyegomez/swarms/blob/master/examples/models/vllm_example.py) | High-performance inference using VLLM for large language models |
| Llama4 | [LiteLLM Example](https://github.com/kyegomez/swarms/blob/master/examples/models/llama4_examples/litellm_example.py) | Llama4 model integration using LiteLLM for efficient inference |
### Tools and Function Calling
@@ -257,5 +256,5 @@ Join our community of agent engineers and researchers for technical support, cut
| š¦ Twitter | Latest news and announcements | [@swarms_corp](https://twitter.com/swarms_corp) |
| š„ 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) |
+| š« Events | Join our community events | [Sign up here](https://lu.ma/swarms_calendar) |
| š Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) |
diff --git a/docs/examples/ma_swarm.md b/docs/examples/ma_swarm.md
index 3eb40777..e5a4f2d9 100644
--- a/docs/examples/ma_swarm.md
+++ b/docs/examples/ma_swarm.md
@@ -635,4 +635,4 @@ By chaining these specialized agents, the M&A Advisory Swarm provides an end-to-
| š¦ 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 |
+| š« Events | [Sign up here](https://lu.ma/swarms_calendar) | Join our community events |
diff --git a/docs/examples/mcp_ds.md b/docs/examples/mcp_ds.md
index 5afc9d49..f2e6226b 100644
--- a/docs/examples/mcp_ds.md
+++ b/docs/examples/mcp_ds.md
@@ -353,4 +353,4 @@ If you'd like technical support, join our Discord below and stay updated on our
| 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 |
+| Events | [Sign up here](https://lu.ma/swarms_calendar) | Join our community events |
diff --git a/docs/examples/realestate_swarm.md b/docs/examples/realestate_swarm.md
index 6f5464c0..25841d41 100644
--- a/docs/examples/realestate_swarm.md
+++ b/docs/examples/realestate_swarm.md
@@ -336,4 +336,4 @@ By chaining these specialized agents, the Real Estate Swarm provides an end-to-e
| š¦ 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 |
+| š« Events | [Sign up here](https://lu.ma/swarms_calendar) | Join our community events |
diff --git a/docs/examples/templates.md b/docs/examples/templates.md
index 8c190cf4..b29486ad 100644
--- a/docs/examples/templates.md
+++ b/docs/examples/templates.md
@@ -197,7 +197,7 @@ Join our community of agent engineers and researchers for technical support, cut
| š¦ 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) |
+| š« Events | Join our community events | [Sign up here](https://lu.ma/swarms_calendar) |
| š Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) |
---
diff --git a/docs/index.md b/docs/index.md
index 6e32a428..aa951bc0 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -83,7 +83,7 @@ Here you'll find references about the Swarms framework, marketplace, community,
| š¦ 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 |
+| š« Events | [Sign up here](https://lu.ma/swarms_calendar) | Join our community events |
## Get Support
diff --git a/docs/llm.txt b/docs/llm.txt
index 6336016d..51f90399 100644
--- a/docs/llm.txt
+++ b/docs/llm.txt
@@ -2223,7 +2223,7 @@ If you'd like technical support, join our Discord below and stay updated on our
| š¦ 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 |
+| š« Events | [Sign up here](https://lu.ma/swarms_calendar) | Join our community events |
@@ -2327,7 +2327,7 @@ This index provides a categorized list of examples and tutorials for using the S
| š¦ 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 |
+| š« Events | [Sign up here](https://lu.ma/swarms_calendar) | Join our community events |
## Contributing
@@ -3967,7 +3967,7 @@ Join our community of agent engineers and researchers for technical support, cut
| š¦ 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) |
+| š« Events | Join our community events | [Sign up here](https://lu.ma/swarms_calendar) |
| š Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) |
---
@@ -6892,7 +6892,7 @@ Here you'll find references about the Swarms framework, marketplace, community,
| š¦ 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 |
+| š« Events | [Sign up here](https://lu.ma/swarms_calendar) | Join our community events |
## Get Support
@@ -10190,7 +10190,7 @@ Join our community of agent engineers and researchers for technical support, cut
| š¦ 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) |
+| š« Events | Join our community events | [Sign up here](https://lu.ma/swarms_calendar) |
| š Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) |
### Getting Help
@@ -21439,7 +21439,7 @@ Join our community of agent engineers and researchers for technical support, cut
| š¦ 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) |
+| š« Events | Join our community events | [Sign up here](https://lu.ma/swarms_calendar) |
| š Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) |
@@ -22230,7 +22230,7 @@ If you're facing issues or want to learn more, check out the following resources
| š¦ 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 |
+| š« Events | [Sign up here](https://lu.ma/swarms_calendar) | Join our community events |
@@ -22534,7 +22534,7 @@ If you're facing issues or want to learn more, check out the following resources
| š¦ 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 |
+| š« Events | [Sign up here](https://lu.ma/swarms_calendar) | Join our community events |
@@ -24998,7 +24998,7 @@ If you're facing issues or want to learn more, check out the following resources
| š¦ 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 |
+| š« Events | [Sign up here](https://lu.ma/swarms_calendar) | Join our community events |
@@ -42641,7 +42641,7 @@ Join our community of agent engineers and researchers for technical support, cut
| 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/UC9yXyXyitkbU_WSy7bd_41SqQ) |
-| Events | Join our community events | [Sign up here](https://lu.ma/5p2jnc2v) |
+| Events | Join our community events | [Sign up here](https://lu.ma/swarms_calendar) |
| Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) |
---
@@ -61933,7 +61933,7 @@ Join our community of agent engineers and researchers for technical support, cut
| š¦ 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) |
+| š« Events | Join our community events | [Sign up here](https://lu.ma/swarms_calendar) |
| š Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) |
--------------------------------------------------
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index fbdd766e..b2b95c8d 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -384,7 +384,6 @@ nav:
- OpenRouter: "swarms/examples/openrouter.md"
- XAI: "swarms/examples/xai.md"
- Azure OpenAI: "swarms/examples/azure.md"
- - VLLM: "swarms/examples/vllm_integration.md"
- Llama4: "swarms/examples/llama4.md"
- Custom Base URL & API Keys: "swarms/examples/custom_base_url_example.md"
@@ -409,7 +408,6 @@ nav:
- Advanced BatchedGridWorkflow: "swarms/examples/batched_grid_advanced_example.md"
- Applications:
- Swarms of Browser Agents: "swarms/examples/swarms_of_browser_agents.md"
- - ConcurrentWorkflow with VLLM Agents: "swarms/examples/vllm.md"
- Hiearchical Marketing Team: "examples/marketing_team.md"
- Gold ETF Research with HeavySwarm: "examples/gold_etf_research.md"
- Hiring Swarm: "examples/hiring_swarm.md"
diff --git a/docs/swarms/agents/index.md b/docs/swarms/agents/index.md
index cb8a790d..55debc8c 100644
--- a/docs/swarms/agents/index.md
+++ b/docs/swarms/agents/index.md
@@ -796,7 +796,7 @@ Join our community of agent engineers and researchers for technical support, cut
| š¦ 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) |
+| š« Events | Join our community events | [Sign up here](https://lu.ma/swarms_calendar) |
| š Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) |
### Getting Help
diff --git a/docs/swarms/examples/custom_base_url_example.md b/docs/swarms/examples/custom_base_url_example.md
index c7c32947..4d48bba7 100644
--- a/docs/swarms/examples/custom_base_url_example.md
+++ b/docs/swarms/examples/custom_base_url_example.md
@@ -130,7 +130,7 @@ hf_agent = Agent(
### 4. Custom Local Endpoint
```python
-# Using a local model server (e.g., vLLM, Ollama, etc.)
+# Using a local model server (e.g., Ollama, etc.)
local_agent = Agent(
agent_name="Local-Agent",
agent_description="Agent using local model endpoint",
diff --git a/docs/swarms/examples/igc_example.md b/docs/swarms/examples/igc_example.md
index 5488cb5a..c7af10cc 100644
--- a/docs/swarms/examples/igc_example.md
+++ b/docs/swarms/examples/igc_example.md
@@ -131,5 +131,5 @@ Join our community of agent engineers and researchers for technical support, cut
| š¦ 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) |
+| š« Events | Join our community events | [Sign up here](https://lu.ma/swarms_calendar) |
| š Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) |
diff --git a/docs/swarms/examples/llama4.md b/docs/swarms/examples/llama4.md
index 1e2b9e77..a59be80b 100644
--- a/docs/swarms/examples/llama4.md
+++ b/docs/swarms/examples/llama4.md
@@ -13,10 +13,11 @@ 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")
+
+# Initialize your model here using your preferred inference method
+# For example, using litellm or another compatible wrapper
```
## Available Models
@@ -88,9 +89,7 @@ agent = Agent(
```python
from dotenv import load_dotenv
-
from swarms import Agent
-from swarms.utils.vllm_wrapper import VLLM
load_dotenv()
@@ -126,15 +125,14 @@ 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
+# Note: Use your preferred model provider (OpenAI, Anthropic, Groq, etc.)
agent = Agent(
agent_name="Crypto-Risk-Analysis-Agent",
agent_description="Agent for analyzing risks in cryptocurrency investments",
system_prompt=CRYPTO_RISK_ANALYSIS_PROMPT,
+ model_name="gpt-4o-mini", # or any other supported model
max_loops=1,
- llm=model,
)
print(
@@ -153,7 +151,7 @@ print(
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.
+ Yes, you can use any supported model provider (OpenAI, Anthropic, Groq, etc.). Just ensure you set the appropriate `model_name` parameter.
??? 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.
diff --git a/docs/swarms/examples/moa_example.md b/docs/swarms/examples/moa_example.md
index 4e10a203..ad275935 100644
--- a/docs/swarms/examples/moa_example.md
+++ b/docs/swarms/examples/moa_example.md
@@ -128,5 +128,5 @@ If you're facing issues or want to learn more, check out the following resources
| š¦ 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 |
+| š« Events | [Sign up here](https://lu.ma/swarms_calendar) | Join our community events |
diff --git a/docs/swarms/examples/model_providers.md b/docs/swarms/examples/model_providers.md
index c3b64fdb..95ebde89 100644
--- a/docs/swarms/examples/model_providers.md
+++ b/docs/swarms/examples/model_providers.md
@@ -14,7 +14,6 @@ Swarms supports a vast array of model providers, giving you the flexibility to c
| **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) |
@@ -63,7 +62,6 @@ response = agent.run("Your query here")
- **Groq**: Ultra-fast inference
-- **vLLM**: Optimized for high throughput
### For Specialized Tasks
@@ -106,7 +104,7 @@ 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.
+ Ollama can be run locally without API keys, making it perfect for development and testing.
## Advanced Features
diff --git a/docs/swarms/examples/multiple_images.md b/docs/swarms/examples/multiple_images.md
index 9adb9b78..427d5f02 100644
--- a/docs/swarms/examples/multiple_images.md
+++ b/docs/swarms/examples/multiple_images.md
@@ -73,5 +73,5 @@ If you're facing issues or want to learn more, check out the following resources
| š¦ 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 |
+| š« Events | [Sign up here](https://lu.ma/swarms_calendar) | Join our community events |
diff --git a/docs/swarms/examples/vision_tools.md b/docs/swarms/examples/vision_tools.md
index bc306fdb..e29f123d 100644
--- a/docs/swarms/examples/vision_tools.md
+++ b/docs/swarms/examples/vision_tools.md
@@ -134,5 +134,5 @@ If you're facing issues or want to learn more, check out the following resources
| š¦ 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 |
+| š« Events | [Sign up here](https://lu.ma/swarms_calendar) | Join our community events |
diff --git a/docs/swarms/examples/vllm.md b/docs/swarms/examples/vllm.md
deleted file mode 100644
index 11df0aab..00000000
--- a/docs/swarms/examples/vllm.md
+++ /dev/null
@@ -1,429 +0,0 @@
-# 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
-
- - Max token limits
-
- - 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.""",
- max_loops=1,
- llm=vllm,
-)
-
-# 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
-
-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,
-)
-
-# 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:
-
-1. FACTOR ANALYSIS
-- Analyze and monitor factor performance:
- * Value
- * Momentum
- * Quality
- * Size
- * Low Volatility
-- Calculate factor exposures and correlations
-
-2. STATISTICAL ANALYSIS
-- Perform statistical arbitrage analysis
-- Calculate and monitor pair trading opportunities
-- Analyze market anomalies and inefficiencies
-- Develop mean reversion strategies
-
-3. RISK MODELING
-- Build and maintain risk models
-- Calculate portfolio optimization metrics
-- Monitor correlation matrices
-- Analyze tail risk and stress scenarios
-
-4. ALGORITHMIC STRATEGIES
-- Develop systematic trading strategies
-- Backtest and validate trading algorithms
-- Monitor strategy performance metrics
-- Optimize execution algorithms
-
-Your analysis should be purely quantitative, based on statistical evidence and mathematical models rather than subjective opinions.""",
- max_loops=1,
- llm=vllm,
-)
-
-# 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:
-
-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
-
-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
-]
-
-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,
-)
-
-swarm.run("Analyze the best etfs for gold and other similiar commodities in volatile markets")
-```
-
-## 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
-
-!!! 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
-
-## FAQ
-
-??? 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.
-
-??? question "How many agents can run concurrently?"
- The number depends on your hardware resources. Start with 3-5 agents and scale based on performance.
-
-??? question "Can I customize agent communication patterns?"
- Yes, you can modify the ConcurrentWorkflow class or create custom workflows for specific communication patterns.
-
-## Advanced Configuration
-
-!!! 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,
- )
- ```
-
-## Contributing
-
-!!! info "Get Involved"
- We welcome contributions! Here's how you can help:
-
- 1. Report bugs and issues
- 2. Submit feature requests
- 3. Contribute to documentation
- 4. Share example use cases
-
-## Resources
-
-!!! abstract "Additional Reading"
- - [VLLM Documentation](https://docs.vllm.ai/en/latest/)
-
\ No newline at end of file
diff --git a/docs/swarms/examples/vllm_integration.md b/docs/swarms/examples/vllm_integration.md
deleted file mode 100644
index c270e954..00000000
--- a/docs/swarms/examples/vllm_integration.md
+++ /dev/null
@@ -1,194 +0,0 @@
-
-
-# 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
-
-!!! note "Prerequisites"
- Before you begin, make sure you have Python 3.8+ installed on your system.
-
-=== "pip"
- ```bash
- pip install -U vllm swarms
- ```
-
-=== "poetry"
- ```bash
- poetry add vllm swarms
- ```
-
-## Basic Usage
-
-Here's a simple example of how to use vLLM with Swarms:
-
-```python title="basic_usage.py"
-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.",
- temperature=0.7,
- max_tokens=4000
-)
-
-# Run inference
-response = vllm.run("What is the capital of France?")
-print(response)
-```
-
-## VLLMWrapper Class
-
-!!! abstract "Class Overview"
- The `VLLMWrapper` class provides a convenient interface for working with vLLM models.
-
-### Key Parameters
-
-| 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 |
-
-### 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
-)
-```
-
-## Integration with Agents
-
-You can easily integrate vLLM with Swarms agents for more complex workflows:
-
-```python title="agent_integration.py"
-from swarms import Agent
-from swarms.utils.vllm_wrapper import VLLMWrapper
-
-# Initialize vLLM
-vllm = VLLMWrapper(
- model_name="meta-llama/Llama-2-7b-chat-hf",
- system_prompt="You are a helpful assistant."
-)
-
-# 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
-)
-
-# Run the agent
-response = agent.run("Research the impact of AI on healthcare")
-```
-
-## Advanced Features
-
-### Batch Processing
-
-!!! tip "Performance Optimization"
- Use batch processing for efficient handling of multiple tasks simultaneously.
-
-```python title="batch_processing.py"
-tasks = [
- "What is machine learning?",
- "Explain neural networks",
- "Describe deep learning"
-]
-
-results = vllm.batched_run(tasks, batch_size=3)
-```
-
-### Error Handling
-
-!!! warning "Error Management"
- Always implement proper error handling in production environments.
-
-```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}")
-```
-
-## 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
-
- === "System Resources"
- - Ensure sufficient GPU memory for your chosen model
- - Monitor resource usage during batch processing
-
- === "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
-
- === "Performance"
- - Use batch processing for multiple tasks
- - Adjust max_tokens based on your use case
- - Fine-tune temperature for optimal output quality
-
-## Example: Multi-Agent System
-
-Here's an example of creating a multi-agent system using vLLM:
-
-```python title="multi_agent_system.py"
-from swarms import Agent, ConcurrentWorkflow
-from swarms.utils.vllm_wrapper import VLLMWrapper
-
-# 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
-)
-
-analysis_agent = Agent(
- agent_name="Analysis-Agent",
- agent_description="Expert in analysis",
- system_prompt="You are an analysis expert.",
- llm=vllm
-)
-
-# Create a workflow
-agents = [research_agent, analysis_agent]
-workflow = ConcurrentWorkflow(
- name="Research-Analysis-Workflow",
- description="Comprehensive research and analysis workflow",
- agents=agents
-)
-
-# Run the workflow
-result = workflow.run("Analyze the impact of renewable energy")
-```
\ No newline at end of file
diff --git a/docs/swarms/structs/hierarchical_swarm.md b/docs/swarms/structs/hierarchical_swarm.md
index 860efd30..f458ac40 100644
--- a/docs/swarms/structs/hierarchical_swarm.md
+++ b/docs/swarms/structs/hierarchical_swarm.md
@@ -2,7 +2,17 @@
The `HierarchicalSwarm` is a sophisticated multi-agent orchestration system that implements a hierarchical workflow pattern. It consists of a director agent that coordinates and distributes tasks to specialized worker agents, creating a structured approach to complex problem-solving.
-## Overview
+```mermaid
+graph TD
+ A[Task] --> B[Director]
+ B --> C[Plan & Orders]
+ C --> D[Agents]
+ D --> E[Results]
+ E --> F{More Loops?}
+ F -->|Yes| B
+ F -->|No| G[Output]
+```
+
The Hierarchical Swarm follows a clear workflow pattern:
@@ -12,25 +22,6 @@ The Hierarchical Swarm follows a clear workflow pattern:
4. **Feedback Loop**: Director evaluates results and issues new orders if needed (up to `max_loops`)
5. **Context Preservation**: All conversation history and context is maintained throughout the process
-## Architecture
-
-```mermaid
-graph TD
- A[User Task] --> B[Director Agent]
- B --> C[Create Plan & Orders]
- C --> D[Distribute to Agents]
- D --> E[Agent 1]
- D --> F[Agent 2]
- D --> G[Agent N]
- E --> H[Execute Task]
- F --> H
- G --> H
- H --> I[Report Results]
- I --> J[Director Evaluation]
- J --> K{More Loops?}
- K -->|Yes| C
- K -->|No| L[Final Output]
-```
## Key Features
@@ -45,44 +36,65 @@ graph TD
| **Live Streaming** | Real-time streaming callbacks for monitoring agent outputs |
| **Token-by-Token Updates** | Watch text formation in real-time as agents generate responses |
-## `HierarchicalSwarm` Constructor
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `name` | `str` | `"HierarchicalAgentSwarm"` | The name of the swarm instance |
-| `description` | `str` | `"Distributed task swarm"` | Brief description of the swarm's functionality |
-| `director` | `Optional[Union[Agent, Callable, Any]]` | `None` | The director agent that orchestrates tasks |
-| `agents` | `List[Union[Agent, Callable, Any]]` | `None` | List of worker agents in the swarm |
-| `max_loops` | `int` | `1` | Maximum number of feedback loops between director and agents |
-| `output_type` | `OutputType` | `"dict-all-except-first"` | Format for output (dict, str, list) |
-| `feedback_director_model_name` | `str` | `"gpt-4o-mini"` | Model name for feedback director |
-| `director_name` | `str` | `"Director"` | Name of the director agent |
-| `director_model_name` | `str` | `"gpt-4o-mini"` | Model name for the director agent |
-| `verbose` | `bool` | `False` | Enable detailed logging |
-| `add_collaboration_prompt` | `bool` | `True` | Add collaboration prompts to agents |
-| `planning_director_agent` | `Optional[Union[Agent, Callable, Any]]` | `None` | Optional planning agent for enhanced planning |
+## Constructor
+
+### `HierarchicalSwarm.__init__()`
+
+Initializes a new HierarchicalSwarm instance.
+
+#### Important Parameters
+
+| Parameter | Type | Default | Required | Description |
+|-----------|------|---------|----------|-------------|
+| `agents` | `AgentListType` | `None` | **Yes** | List of worker agents in the swarm. Must not be empty |
+| `name` | `str` | `"HierarchicalAgentSwarm"` | No | The name identifier for this swarm instance |
+| `description` | `str` | `"Distributed task swarm"` | No | A description of the swarm's purpose and capabilities |
+| `director` | `Optional[Union[Agent, Callable, Any]]` | `None` | No | The director agent that orchestrates tasks. If None, a default director will be created |
+| `max_loops` | `int` | `1` | No | Maximum number of feedback loops between director and agents (must be > 0) |
+| `output_type` | `OutputType` | `"dict-all-except-first"` | No | Format for output (dict, str, list) |
+| `director_model_name` | `str` | `"gpt-4o-mini"` | No | Model name for the main director agent |
+| `director_feedback_on` | `bool` | `True` | No | Whether director feedback is enabled |
+| `interactive` | `bool` | `False` | No | Enable interactive mode with dashboard visualization |
+
+#### Returns
+
+| Type | Description |
+|------|-------------|
+| `HierarchicalSwarm` | A new HierarchicalSwarm instance |
+
+#### Raises
+
+| Exception | Condition |
+|-----------|-----------|
+| `ValueError` | If no agents are provided or max_loops is invalid |
## Core Methods
-### `run(task, img=None, streaming_callback=None, *args, **kwargs)`
+### `run()`
Executes the hierarchical swarm for a specified number of feedback loops, processing the task through multiple iterations for refinement and improvement.
-#### Parameters
+#### Important Parameters
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `task` | `str` | **Required** | The initial task to be processed by the swarm |
-| `img` | `str` | `None` | Optional image input for the agents |
-| `streaming_callback` | `Callable[[str, str, bool], None]` | `None` | Optional callback for real-time streaming of agent outputs |
-| `*args` | `Any` | - | Additional positional arguments |
-| `**kwargs` | `Any` | - | Additional keyword arguments |
+| Parameter | Type | Default | Required | Description |
+|-----------|------|---------|----------|-------------|
+| `task` | `Optional[str]` | `None` | **Yes*** | The initial task to be processed by the swarm. If None and interactive mode is enabled, will prompt for input |
+| `img` | `Optional[str]` | `None` | No | Optional image input for the agents |
+| `streaming_callback` | `Optional[Callable[[str, str, bool], None]]` | `None` | No | Callback function for real-time streaming of agent outputs. Parameters are (agent_name, chunk, is_final) where is_final indicates completion |
+
+*Required if `interactive=False`
#### Returns
| Type | Description |
|------|-------------|
-| `Any` | The formatted conversation history as output based on `output_type` |
+| `Any` | The formatted conversation history as output, formatted according to the `output_type` configuration |
+
+#### Raises
+
+| Exception | Condition |
+|-----------|-----------|
+| `Exception` | If swarm execution fails |
#### Example
@@ -170,71 +182,29 @@ task = "Analyze the impact of AI on the job market"
result = swarm.run(task=task, streaming_callback=streaming_callback)
```
-#### Parameters (step method)
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `task` | `str` | **Required** | The task to be executed in this step |
-| `img` | `str` | `None` | Optional image input for the agents |
-| `streaming_callback` | `Callable[[str, str, bool], None]` | `None` | Optional callback for real-time streaming of agent outputs |
-| `*args` | `Any` | - | Additional positional arguments |
-| `**kwargs` | `Any` | - | Additional keyword arguments |
-
-#### Returns (step method)
-
-| Type | Description |
-|------|-------------|
-| `str` | Feedback from the director based on agent outputs |
-
-#### Example (step method)
-
-```python
-from swarms import Agent
-from swarms.structs.hiearchical_swarm import HierarchicalSwarm
+### `batched_run()`
-# Create development agents
-frontend_agent = Agent(
- agent_name="Frontend-Developer",
- agent_description="Expert in React and modern web development",
- model_name="gpt-4.1",
-)
+Execute the hierarchical swarm for multiple tasks in sequence. Processes a list of tasks sequentially, running the complete swarm workflow for each task independently.
-backend_agent = Agent(
- agent_name="Backend-Developer",
- agent_description="Specialist in Node.js and API development",
- model_name="gpt-4.1",
-)
+#### Important Parameters
-# Initialize the swarm
-swarm = HierarchicalSwarm(
- name="Development-Swarm",
- description="A hierarchical swarm for software development",
- agents=[frontend_agent, backend_agent],
- max_loops=1,
- verbose=True,
-)
+| Parameter | Type | Default | Required | Description |
+|-----------|------|---------|----------|-------------|
+| `tasks` | `List[str]` | - | **Yes** | List of tasks to be processed by the swarm |
+| `img` | `Optional[str]` | `None` | No | Optional image input for the tasks |
+| `streaming_callback` | `Optional[Callable[[str, str, bool], None]]` | `None` | No | Callback function for streaming agent outputs. Parameters are (agent_name, chunk, is_final) where is_final indicates completion |
-# Execute a single step
-task = "Create a simple web app for file upload and download"
-feedback = swarm.step(task=task)
-print("Director Feedback:", feedback)
-```
-
-#### Parameters (batched_run method)
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `tasks` | `List[str]` | **Required** | List of tasks to be processed |
-| `img` | `str` | `None` | Optional image input for the agents |
-| `streaming_callback` | `Callable[[str, str, bool], None]` | `None` | Optional callback for real-time streaming of agent outputs |
-| `*args` | `Any` | - | Additional positional arguments |
-| `**kwargs` | `Any` | - | Additional keyword arguments |
-
-#### Returns (batched_run method)
+#### Returns
| Type | Description |
|------|-------------|
-| `List[Any]` | List of results for each task |
+| `List[Any]` | List of results for each processed task |
+
+#### Raises
+
+| Exception | Condition |
+|-----------|-----------|
+| `Exception` | If batched execution fails |
#### Example (batched_run method)
@@ -442,28 +412,6 @@ def live_paragraph_callback(agent_name: str, chunk: str, is_final: bool):
print(f"\nā
{agent_name} completed!")
```
-### Streaming Use Cases
-
-- **Real-time Monitoring**: Watch agents work simultaneously
-- **Progress Tracking**: See text formation token by token
-- **Live Debugging**: Monitor agent performance in real-time
-- **User Experience**: Provide live feedback to users
-- **Logging**: Capture detailed execution traces
-
-### Streaming in Different Methods
-
-Streaming callbacks work with all execution methods:
-
-```python
-# Single task with streaming
-result = swarm.run(task=task, streaming_callback=my_callback)
-
-# Single step with streaming
-result = swarm.step(task=task, streaming_callback=my_callback)
-
-# Batch processing with streaming
-results = swarm.batched_run(tasks=tasks, streaming_callback=my_callback)
-```
## Best Practices
diff --git a/docs/swarms/structs/index.md b/docs/swarms/structs/index.md
index 310ee5de..f556ae3f 100644
--- a/docs/swarms/structs/index.md
+++ b/docs/swarms/structs/index.md
@@ -294,7 +294,7 @@ Join our community of agent engineers and researchers for technical support, cut
| 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/UC9yXyXyitkbU_WSy7bd_41SqQ) |
-| Events | Join our community events | [Sign up here](https://lu.ma/5p2jnc2v) |
+| Events | Join our community events | [Sign up here](https://lu.ma/swarms_calendar) |
| Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) |
---
diff --git a/examples/README.md b/examples/README.md
index b595dc76..34259fd4 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -7,70 +7,120 @@ This directory contains comprehensive examples demonstrating various capabilitie
### Multi-Agent Systems
- **[multi_agent/](multi_agent/)** - Advanced multi-agent patterns including agent rearrangement, auto swarm builder (ASB), batched workflows, board of directors, caching, concurrent processing, councils, debates, elections, forest swarms, graph workflows, group chats, heavy swarms, hierarchical swarms, majority voting, orchestration examples, social algorithms, simulations, spreadsheet examples, and swarm routing.
+ - [README.md](multi_agent/README.md) - Complete multi-agent examples documentation
### Single Agent Systems
- **[single_agent/](single_agent/)** - Single agent implementations including demos, external agent integrations, LLM integrations (Azure, Claude, DeepSeek, Mistral, OpenAI, Qwen), onboarding, RAG, reasoning agents, tools integration, utils, and vision capabilities.
+ - [README.md](single_agent/README.md) - Complete single agent examples documentation
+ - [simple_agent.py](single_agent/simple_agent.py) - Basic single agent example
### Tools & Integrations
- **[tools/](tools/)** - Tool integration examples including agent-as-tools, base tool implementations, browser automation, Claude integration, Exa search, Firecrawl, multi-tool usage, and Stagehand integration.
+ - [README.md](tools/README.md) - Complete tools examples documentation
+ - [agent_as_tools.py](tools/agent_as_tools.py) - Using agents as tools
### Model Integrations
-- **[models/](models/)** - Various model integrations including Cerebras, GPT-5, GPT-OSS, Llama 4, Lumo, Ollama, and VLLM implementations with concurrent processing examples and provider-specific configurations.
+- **[models/](models/)** - Various model integrations including Cerebras, GPT-5, GPT-OSS, Llama 4, Lumo, and Ollama implementations with concurrent processing examples and provider-specific configurations.
+ - [README.md](models/README.md) - Model integration documentation
+ - [simple_example_ollama.py](models/simple_example_ollama.py) - Ollama integration example
+ - [cerebas_example.py](models/cerebas_example.py) - Cerebras model example
+ - [lumo_example.py](models/lumo_example.py) - Lumo model example
### API & Protocols
- **[swarms_api_examples/](swarms_api_examples/)** - Swarms API usage examples including agent overview, batch processing, client integration, team examples, analysis, and rate limiting.
+ - [README.md](swarms_api_examples/README.md) - API examples documentation
+ - [client_example.py](swarms_api_examples/client_example.py) - API client example
+ - [batch_example.py](swarms_api_examples/batch_example.py) - Batch processing example
- **[mcp/](mcp/)** - Model Context Protocol (MCP) integration examples including agent implementations, multi-connection setups, server configurations, and utility functions.
+ - [README.md](mcp/README.md) - MCP examples documentation
+ - [multi_mcp_example.py](mcp/multi_mcp_example.py) - Multi-MCP connection example
- **[aop_examples/](aop_examples/)** - Agents over Protocol (AOP) examples demonstrating MCP server setup, agent discovery, client interactions, queue-based task submission, and medical AOP implementations.
+ - [README.md](aop_examples/README.md) - AOP examples documentation
+ - [server.py](aop_examples/server.py) - AOP server implementation
### Advanced Capabilities
- **[reasoning_agents/](reasoning_agents/)** - Advanced reasoning capabilities including agent judge evaluation systems, O3 model integration, and mixture of agents (MOA) sequential examples.
+ - [README.md](reasoning_agents/README.md) - Reasoning agents documentation
+ - [example_o3.py](reasoning_agents/example_o3.py) - O3 model example
+ - [moa_seq_example.py](reasoning_agents/moa_seq_example.py) - MOA sequential example
- **[rag/](rag/)** - Retrieval Augmented Generation (RAG) implementations with vector database integrations including Qdrant examples.
+ - [README.md](rag/README.md) - RAG documentation
+ - [qdrant_rag_example.py](rag/qdrant_rag_example.py) - Qdrant RAG example
### Guides & Tutorials
- **[guides/](guides/)** - Comprehensive guides and tutorials including generation length blog, geo guesser agent, graph workflow guide, hierarchical marketing team, nano banana Jarvis agent, smart database, web scraper agents, and workshop examples (840_update, 850_workshop).
-
-### Demonstrations
-
-- **[demos/](demos/)** - Domain-specific demonstrations across various industries including apps, charts, crypto, CUDA, finance, hackathon projects, insurance, legal, medical, news, privacy, real estate, science, and synthetic data generation.
-
-### Hackathons
-
-- **[hackathons/](hackathons/)** - Hackathon projects and implementations including September 27 hackathon examples with diet coach agents, nutritional content analysis swarms, and API client integrations.
+ - [README.md](guides/README.md) - Guides documentation
+ - [hiearchical_marketing_team.py](guides/hiearchical_marketing_team.py) - Hierarchical marketing team example
### Deployment
- **[deployment/](deployment/)** - Deployment strategies and patterns including cron job implementations and FastAPI deployment examples.
+ - [README.md](deployment/README.md) - Deployment documentation
+ - [fastapi/](deployment/fastapi/) - FastAPI deployment examples
+ - [cron_job_examples/](deployment/cron_job_examples/) - Cron job examples
### Utilities
- **[utils/](utils/)** - Utility functions and helper implementations including agent loader, communication examples, concurrent wrappers, miscellaneous utilities, and telemetry.
-
-### Educational
-
-- **[workshops/](workshops/)** - Workshop examples and educational sessions including agent tools, batched grids, geo guesser, and Jarvis agent implementations.
+ - [README.md](utils/README.md) - Utils documentation
### User Interface
- **[ui/](ui/)** - User interface examples and implementations including chat interfaces.
+ - [README.md](ui/README.md) - UI examples documentation
+ - [chat.py](ui/chat.py) - Chat interface example
## Quick Start
1. **New to Swarms?** Start with [single_agent/simple_agent.py](single_agent/simple_agent.py) for basic concepts
2. **Want multi-agent workflows?** Check out [multi_agent/duo_agent.py](multi_agent/duo_agent.py)
3. **Need tool integration?** Explore [tools/agent_as_tools.py](tools/agent_as_tools.py)
-4. **Interested in AOP?** Try [aop_examples/example_new_agent_tools.py](aop_examples/example_new_agent_tools.py) for agent discovery
+4. **Interested in AOP?** Try [aop_examples/client/example_new_agent_tools.py](aop_examples/client/example_new_agent_tools.py) for agent discovery
5. **Want to see social algorithms?** Check out [multi_agent/social_algorithms_examples/](multi_agent/social_algorithms_examples/)
6. **Looking for guides?** Visit [guides/](guides/) for comprehensive tutorials
-7. **Hackathon projects?** Explore [hackathons/hackathon_sep_27/](hackathons/hackathon_sep_27/) for real-world implementations
+7. **Need RAG?** Try [rag/qdrant_rag_example.py](rag/qdrant_rag_example.py)
+8. **Want reasoning agents?** Check out [reasoning_agents/example_o3.py](reasoning_agents/example_o3.py)
+
+## Key Examples by Category
+
+### Multi-Agent Patterns
+
+- [Duo Agent](multi_agent/duo_agent.py) - Two-agent collaboration
+- [Hierarchical Swarm](multi_agent/hiearchical_swarm/hierarchical_swarm_example.py) - Hierarchical agent structures
+- [Group Chat](multi_agent/groupchat/interactive_groupchat_example.py) - Multi-agent conversations
+- [Graph Workflow](multi_agent/graphworkflow_examples/graph_workflow_example.py) - Graph-based workflows
+- [Social Algorithms](multi_agent/social_algorithms_examples/) - Various social algorithm patterns
+
+### Single Agent Examples
+
+- [Simple Agent](single_agent/simple_agent.py) - Basic agent setup
+- [Reasoning Agents](single_agent/reasoning_agent_examples/) - Advanced reasoning patterns
+- [Vision Agents](single_agent/vision/multimodal_example.py) - Vision and multimodal capabilities
+- [RAG Agents](single_agent/rag/qdrant_rag_example.py) - Retrieval augmented generation
+
+### Tool Integrations
+
+- [Agent as Tools](tools/agent_as_tools.py) - Using agents as tools
+- [Browser Automation](tools/browser_use_as_tool.py) - Browser control
+- [Exa Search](tools/exa_search_agent.py) - Search integration
+- [Stagehand](tools/stagehand/) - UI automation
+
+### Model Integrations
+
+- [OpenAI](single_agent/llms/openai_examples/4o_mini_demo.py) - OpenAI models
+- [Claude](single_agent/llms/claude_examples/claude_4_example.py) - Claude models
+- [DeepSeek](single_agent/llms/deepseek_examples/deepseek_r1.py) - DeepSeek models
+- [Azure](single_agent/llms/azure_agent.py) - Azure OpenAI
+- [Ollama](models/simple_example_ollama.py) - Local Ollama models
## Documentation
diff --git a/examples/aop_examples/client/README.md b/examples/aop_examples/client/README.md
new file mode 100644
index 00000000..56d24cb9
--- /dev/null
+++ b/examples/aop_examples/client/README.md
@@ -0,0 +1,18 @@
+# AOP Client Examples
+
+This directory contains examples demonstrating AOP (Agents over Protocol) client implementations.
+
+## Examples
+
+- [aop_cluster_example.py](aop_cluster_example.py) - AOP cluster client example
+- [aop_queue_example.py](aop_queue_example.py) - Queue-based task submission
+- [aop_raw_client_code.py](aop_raw_client_code.py) - Raw AOP client implementation
+- [aop_raw_task_example.py](aop_raw_task_example.py) - Raw AOP task example
+- [example_new_agent_tools.py](example_new_agent_tools.py) - New agent tools example
+- [get_all_agents.py](get_all_agents.py) - Agent discovery example
+- [list_agents_and_call_them.py](list_agents_and_call_them.py) - List and call agents
+
+## Overview
+
+AOP client examples demonstrate how to connect to AOP servers, discover available agents, submit tasks, and interact with agents over the protocol. These examples show various client patterns including queue-based submission, cluster management, and agent discovery.
+
diff --git a/examples/aop_examples/discovery/README.md b/examples/aop_examples/discovery/README.md
new file mode 100644
index 00000000..361f9e86
--- /dev/null
+++ b/examples/aop_examples/discovery/README.md
@@ -0,0 +1,15 @@
+# AOP Discovery Examples
+
+This directory contains examples demonstrating agent discovery mechanisms in AOP.
+
+## Examples
+
+- [example_agent_communication.py](example_agent_communication.py) - Agent communication example
+- [example_aop_discovery.py](example_aop_discovery.py) - AOP discovery implementation
+- [simple_discovery_example.py](simple_discovery_example.py) - Simple discovery example
+- [test_aop_discovery.py](test_aop_discovery.py) - Discovery testing
+
+## Overview
+
+AOP discovery examples demonstrate how agents can discover and communicate with each other over the protocol. These examples show various discovery patterns, agent registration, and communication protocols for distributed agent systems.
+
diff --git a/examples/aop_examples/medical_aop/README.md b/examples/aop_examples/medical_aop/README.md
new file mode 100644
index 00000000..aa11bc3c
--- /dev/null
+++ b/examples/aop_examples/medical_aop/README.md
@@ -0,0 +1,13 @@
+# Medical AOP Examples
+
+This directory contains medical domain-specific AOP implementations.
+
+## Examples
+
+- [client.py](client.py) - Medical AOP client
+- [server.py](server.py) - Medical AOP server
+
+## Overview
+
+Medical AOP examples demonstrate domain-specific implementations of Agents over Protocol for healthcare applications. These examples show how to structure AOP servers and clients for medical use cases, including patient data handling, medical analysis, and healthcare workflows.
+
diff --git a/examples/aop_examples/utils/README.md b/examples/aop_examples/utils/README.md
new file mode 100644
index 00000000..e93bf263
--- /dev/null
+++ b/examples/aop_examples/utils/README.md
@@ -0,0 +1,16 @@
+# AOP Utils
+
+This directory contains utility functions and helpers for AOP implementations.
+
+## Examples
+
+- [comprehensive_aop_example.py](comprehensive_aop_example.py) - Comprehensive AOP example
+- [network_error_example.py](network_error_example.py) - Network error handling
+- [network_management_example.py](network_management_example.py) - Network management utilities
+- [persistence_example.py](persistence_example.py) - Persistence implementation
+- [persistence_management_example.py](persistence_management_example.py) - Persistence management
+
+## Overview
+
+AOP utils provide helper functions, error handling patterns, network management utilities, and persistence mechanisms for AOP implementations. These examples demonstrate best practices for building robust AOP systems.
+
diff --git a/examples/demos/finance/swarms_of_vllm.py b/examples/demos/finance/swarms_of_vllm.py
deleted file mode 100644
index 89191ab0..00000000
--- a/examples/demos/finance/swarms_of_vllm.py
+++ /dev/null
@@ -1,214 +0,0 @@
-from swarms import Agent, ConcurrentWorkflow
-from swarms.utils.vllm_wrapper import VLLMWrapper
-from dotenv import load_dotenv
-
-load_dotenv()
-
-# 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.""",
- max_loops=1,
- llm=vllm,
-)
-
-# 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
-
-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,
-)
-
-# 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:
-
-1. FACTOR ANALYSIS
-- Analyze and monitor factor performance:
- * Value
- * Momentum
- * Quality
- * Size
- * Low Volatility
-- Calculate factor exposures and correlations
-
-2. STATISTICAL ANALYSIS
-- Perform statistical arbitrage analysis
-- Calculate and monitor pair trading opportunities
-- Analyze market anomalies and inefficiencies
-- Develop mean reversion strategies
-
-3. RISK MODELING
-- Build and maintain risk models
-- Calculate portfolio optimization metrics
-- Monitor correlation matrices
-- Analyze tail risk and stress scenarios
-
-4. ALGORITHMIC STRATEGIES
-- Develop systematic trading strategies
-- Backtest and validate trading algorithms
-- Monitor strategy performance metrics
-- Optimize execution algorithms
-
-Your analysis should be purely quantitative, based on statistical evidence and mathematical models rather than subjective opinions.""",
- max_loops=1,
- llm=vllm,
-)
-
-# 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:
-
-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
-
-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,
-]
-
-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,
-)
-
-swarm.run(
- "Analyze the best etfs for gold and other similiar commodities in volatile markets"
-)
diff --git a/examples/deployment/cron_job_examples/README.md b/examples/deployment/cron_job_examples/README.md
new file mode 100644
index 00000000..a4a961a7
--- /dev/null
+++ b/examples/deployment/cron_job_examples/README.md
@@ -0,0 +1,19 @@
+# Cron Job Examples
+
+This directory contains examples demonstrating scheduled task execution using cron jobs.
+
+## Examples
+
+- [callback_cron_example.py](callback_cron_example.py) - Cron job with callbacks
+- [cron_job_example.py](cron_job_example.py) - Basic cron job example
+- [cron_job_figma_stock_swarms_tools_example.py](cron_job_figma_stock_swarms_tools_example.py) - Figma stock swarms tools cron job
+- [crypto_concurrent_cron_example.py](crypto_concurrent_cron_example.py) - Concurrent crypto cron job
+- [figma_stock_example.py](figma_stock_example.py) - Figma stock example
+- [simple_callback_example.py](simple_callback_example.py) - Simple callback example
+- [simple_concurrent_crypto_cron.py](simple_concurrent_crypto_cron.py) - Simple concurrent crypto cron
+- [solana_price_tracker.py](solana_price_tracker.py) - Solana price tracker cron job
+
+## Overview
+
+Cron job examples demonstrate how to schedule and execute agent tasks on a recurring basis. These examples show various patterns including callback handling, concurrent execution, and domain-specific scheduled tasks like price tracking and stock monitoring.
+
diff --git a/examples/guides/840_update/README.md b/examples/guides/840_update/README.md
new file mode 100644
index 00000000..f959c950
--- /dev/null
+++ b/examples/guides/840_update/README.md
@@ -0,0 +1,15 @@
+# 840 Update Examples
+
+This directory contains examples from the 840 update, demonstrating new features and improvements.
+
+## Examples
+
+- [agent_rearrange_concurrent_example.py](agent_rearrange_concurrent_example.py) - Agent rearrangement with concurrency
+- [auto_swarm_builder_example.py](auto_swarm_builder_example.py) - Auto swarm builder example
+- [fallback_example.py](fallback_example.py) - Fallback mechanism example
+- [server.py](server.py) - Server implementation
+
+## Overview
+
+These examples showcase features introduced in the 840 update, including concurrent agent rearrangement, auto swarm building capabilities, and improved fallback mechanisms.
+
diff --git a/examples/guides/850_workshop/README.md b/examples/guides/850_workshop/README.md
new file mode 100644
index 00000000..658fb3ae
--- /dev/null
+++ b/examples/guides/850_workshop/README.md
@@ -0,0 +1,18 @@
+# 850 Workshop Examples
+
+This directory contains examples from the 850 workshop, demonstrating advanced multi-agent patterns and AOP integration.
+
+## Examples
+
+- [aop_raw_client_code.py](aop_raw_client_code.py) - Raw AOP client implementation
+- [aop_raw_task_example.py](aop_raw_task_example.py) - Raw AOP task example
+- [moa_seq_example.py](moa_seq_example.py) - Mixture of Agents sequential example
+- [peer_review_example.py](peer_review_example.py) - Peer review pattern
+- [server.py](server.py) - Server implementation
+- [test_agent_concurrent.py](test_agent_concurrent.py) - Concurrent agent testing
+- [uvloop_example.py](uvloop_example.py) - UVLoop integration example
+
+## Overview
+
+These examples from the 850 workshop demonstrate advanced patterns including Agents over Protocol (AOP) integration, mixture of agents, peer review workflows, and high-performance async execution with UVLoop.
+
diff --git a/examples/demos/README.md b/examples/guides/demos/README.md
similarity index 98%
rename from examples/demos/README.md
rename to examples/guides/demos/README.md
index 1fbccc7d..360b6f3a 100644
--- a/examples/demos/README.md
+++ b/examples/guides/demos/README.md
@@ -20,7 +20,6 @@ This directory contains comprehensive demonstration examples showcasing various
## Finance
- [sentiment_news_analysis.py](finance/sentiment_news_analysis.py) - Financial sentiment analysis
-- [swarms_of_vllm.py](finance/swarms_of_vllm.py) - VLLM-based financial swarms
## Hackathon Examples
- [fraud.py](hackathon_feb16/fraud.py) - Fraud detection system
diff --git a/examples/demos/agent_with_fluidapi.py b/examples/guides/demos/agent_with_fluidapi.py
similarity index 100%
rename from examples/demos/agent_with_fluidapi.py
rename to examples/guides/demos/agent_with_fluidapi.py
diff --git a/examples/demos/apps/hiring_swarm.py b/examples/guides/demos/apps/hiring_swarm.py
similarity index 100%
rename from examples/demos/apps/hiring_swarm.py
rename to examples/guides/demos/apps/hiring_swarm.py
diff --git a/examples/demos/apps/smart_database_swarm.py b/examples/guides/demos/apps/smart_database_swarm.py
similarity index 100%
rename from examples/demos/apps/smart_database_swarm.py
rename to examples/guides/demos/apps/smart_database_swarm.py
diff --git a/examples/demos/chart_swarm.py b/examples/guides/demos/chart_swarm.py
similarity index 100%
rename from examples/demos/chart_swarm.py
rename to examples/guides/demos/chart_swarm.py
diff --git a/examples/demos/crypto/dao_swarm.py b/examples/guides/demos/crypto/dao_swarm.py
similarity index 100%
rename from examples/demos/crypto/dao_swarm.py
rename to examples/guides/demos/crypto/dao_swarm.py
diff --git a/examples/demos/crypto/ethchain_agent.py b/examples/guides/demos/crypto/ethchain_agent.py
similarity index 100%
rename from examples/demos/crypto/ethchain_agent.py
rename to examples/guides/demos/crypto/ethchain_agent.py
diff --git a/examples/demos/crypto/htx_swarm.py b/examples/guides/demos/crypto/htx_swarm.py
similarity index 100%
rename from examples/demos/crypto/htx_swarm.py
rename to examples/guides/demos/crypto/htx_swarm.py
diff --git a/examples/demos/crypto/swarms_coin_agent.py b/examples/guides/demos/crypto/swarms_coin_agent.py
similarity index 100%
rename from examples/demos/crypto/swarms_coin_agent.py
rename to examples/guides/demos/crypto/swarms_coin_agent.py
diff --git a/examples/demos/crypto/swarms_coin_multimarket.py b/examples/guides/demos/crypto/swarms_coin_multimarket.py
similarity index 100%
rename from examples/demos/crypto/swarms_coin_multimarket.py
rename to examples/guides/demos/crypto/swarms_coin_multimarket.py
diff --git a/examples/demos/cuda_swarm.py b/examples/guides/demos/cuda_swarm.py
similarity index 100%
rename from examples/demos/cuda_swarm.py
rename to examples/guides/demos/cuda_swarm.py
diff --git a/examples/demos/finance/sentiment_news_analysis.py b/examples/guides/demos/finance/sentiment_news_analysis.py
similarity index 100%
rename from examples/demos/finance/sentiment_news_analysis.py
rename to examples/guides/demos/finance/sentiment_news_analysis.py
diff --git a/examples/demos/hackathon_feb16/fraud.py b/examples/guides/demos/hackathon_feb16/fraud.py
similarity index 100%
rename from examples/demos/hackathon_feb16/fraud.py
rename to examples/guides/demos/hackathon_feb16/fraud.py
diff --git a/examples/demos/hackathon_feb16/sarasowti.py b/examples/guides/demos/hackathon_feb16/sarasowti.py
similarity index 100%
rename from examples/demos/hackathon_feb16/sarasowti.py
rename to examples/guides/demos/hackathon_feb16/sarasowti.py
diff --git a/examples/demos/insurance/insurance_swarm.py b/examples/guides/demos/insurance/insurance_swarm.py
similarity index 100%
rename from examples/demos/insurance/insurance_swarm.py
rename to examples/guides/demos/insurance/insurance_swarm.py
diff --git a/examples/demos/legal/legal_swarm.py b/examples/guides/demos/legal/legal_swarm.py
similarity index 100%
rename from examples/demos/legal/legal_swarm.py
rename to examples/guides/demos/legal/legal_swarm.py
diff --git a/examples/demos/medical/health_privacy_swarm 2.py b/examples/guides/demos/medical/health_privacy_swarm 2.py
similarity index 100%
rename from examples/demos/medical/health_privacy_swarm 2.py
rename to examples/guides/demos/medical/health_privacy_swarm 2.py
diff --git a/examples/demos/medical/health_privacy_swarm.py b/examples/guides/demos/medical/health_privacy_swarm.py
similarity index 100%
rename from examples/demos/medical/health_privacy_swarm.py
rename to examples/guides/demos/medical/health_privacy_swarm.py
diff --git a/examples/demos/medical/health_privacy_swarm_two 2.py b/examples/guides/demos/medical/health_privacy_swarm_two 2.py
similarity index 100%
rename from examples/demos/medical/health_privacy_swarm_two 2.py
rename to examples/guides/demos/medical/health_privacy_swarm_two 2.py
diff --git a/examples/demos/medical/health_privacy_swarm_two.py b/examples/guides/demos/medical/health_privacy_swarm_two.py
similarity index 100%
rename from examples/demos/medical/health_privacy_swarm_two.py
rename to examples/guides/demos/medical/health_privacy_swarm_two.py
diff --git a/examples/demos/medical/medical_analysis_agent_rearrange.md b/examples/guides/demos/medical/medical_analysis_agent_rearrange.md
similarity index 100%
rename from examples/demos/medical/medical_analysis_agent_rearrange.md
rename to examples/guides/demos/medical/medical_analysis_agent_rearrange.md
diff --git a/examples/demos/medical/medical_coder_agent.py b/examples/guides/demos/medical/medical_coder_agent.py
similarity index 100%
rename from examples/demos/medical/medical_coder_agent.py
rename to examples/guides/demos/medical/medical_coder_agent.py
diff --git a/examples/demos/medical/medical_coding_report.md b/examples/guides/demos/medical/medical_coding_report.md
similarity index 100%
rename from examples/demos/medical/medical_coding_report.md
rename to examples/guides/demos/medical/medical_coding_report.md
diff --git a/examples/demos/medical/medical_diagnosis_report.md b/examples/guides/demos/medical/medical_diagnosis_report.md
similarity index 100%
rename from examples/demos/medical/medical_diagnosis_report.md
rename to examples/guides/demos/medical/medical_diagnosis_report.md
diff --git a/examples/demos/medical/new_medical_rearrange.py b/examples/guides/demos/medical/new_medical_rearrange.py
similarity index 100%
rename from examples/demos/medical/new_medical_rearrange.py
rename to examples/guides/demos/medical/new_medical_rearrange.py
diff --git a/examples/demos/medical/ollama_demo.py b/examples/guides/demos/medical/ollama_demo.py
similarity index 100%
rename from examples/demos/medical/ollama_demo.py
rename to examples/guides/demos/medical/ollama_demo.py
diff --git a/examples/demos/medical/rearrange_video_examples/reports/medical_analysis_agent_rearrange.md b/examples/guides/demos/medical/rearrange_video_examples/reports/medical_analysis_agent_rearrange.md
similarity index 100%
rename from examples/demos/medical/rearrange_video_examples/reports/medical_analysis_agent_rearrange.md
rename to examples/guides/demos/medical/rearrange_video_examples/reports/medical_analysis_agent_rearrange.md
diff --git a/examples/demos/medical/rearrange_video_examples/reports/vc_document_analysis.md b/examples/guides/demos/medical/rearrange_video_examples/reports/vc_document_analysis.md
similarity index 100%
rename from examples/demos/medical/rearrange_video_examples/reports/vc_document_analysis.md
rename to examples/guides/demos/medical/rearrange_video_examples/reports/vc_document_analysis.md
diff --git a/examples/demos/medical/rearrange_video_examples/term_sheet_swarm.py b/examples/guides/demos/medical/rearrange_video_examples/term_sheet_swarm.py
similarity index 100%
rename from examples/demos/medical/rearrange_video_examples/term_sheet_swarm.py
rename to examples/guides/demos/medical/rearrange_video_examples/term_sheet_swarm.py
diff --git a/examples/demos/news_aggregator_summarizer.py b/examples/guides/demos/news_aggregator_summarizer.py
similarity index 100%
rename from examples/demos/news_aggregator_summarizer.py
rename to examples/guides/demos/news_aggregator_summarizer.py
diff --git a/examples/demos/privacy_building.py b/examples/guides/demos/privacy_building.py
similarity index 100%
rename from examples/demos/privacy_building.py
rename to examples/guides/demos/privacy_building.py
diff --git a/examples/demos/real_estate/README_realtor.md b/examples/guides/demos/real_estate/README_realtor.md
similarity index 100%
rename from examples/demos/real_estate/README_realtor.md
rename to examples/guides/demos/real_estate/README_realtor.md
diff --git a/examples/demos/real_estate/morgtate_swarm.py b/examples/guides/demos/real_estate/morgtate_swarm.py
similarity index 100%
rename from examples/demos/real_estate/morgtate_swarm.py
rename to examples/guides/demos/real_estate/morgtate_swarm.py
diff --git a/examples/demos/real_estate/real_estate_agent.py b/examples/guides/demos/real_estate/real_estate_agent.py
similarity index 100%
rename from examples/demos/real_estate/real_estate_agent.py
rename to examples/guides/demos/real_estate/real_estate_agent.py
diff --git a/examples/demos/real_estate/realtor_agent.py b/examples/guides/demos/real_estate/realtor_agent.py
similarity index 100%
rename from examples/demos/real_estate/realtor_agent.py
rename to examples/guides/demos/real_estate/realtor_agent.py
diff --git a/examples/demos/science/materials_science_agents.py b/examples/guides/demos/science/materials_science_agents.py
similarity index 100%
rename from examples/demos/science/materials_science_agents.py
rename to examples/guides/demos/science/materials_science_agents.py
diff --git a/examples/demos/science/open_scientist.py b/examples/guides/demos/science/open_scientist.py
similarity index 100%
rename from examples/demos/science/open_scientist.py
rename to examples/guides/demos/science/open_scientist.py
diff --git a/examples/demos/science/paper_idea_agent.py b/examples/guides/demos/science/paper_idea_agent.py
similarity index 100%
rename from examples/demos/science/paper_idea_agent.py
rename to examples/guides/demos/science/paper_idea_agent.py
diff --git a/examples/demos/science/paper_idea_profile.py b/examples/guides/demos/science/paper_idea_profile.py
similarity index 100%
rename from examples/demos/science/paper_idea_profile.py
rename to examples/guides/demos/science/paper_idea_profile.py
diff --git a/examples/demos/spike/agent_rearrange_test.py b/examples/guides/demos/spike/agent_rearrange_test.py
similarity index 100%
rename from examples/demos/spike/agent_rearrange_test.py
rename to examples/guides/demos/spike/agent_rearrange_test.py
diff --git a/examples/demos/spike/function_caller_example.py b/examples/guides/demos/spike/function_caller_example.py
similarity index 100%
rename from examples/demos/spike/function_caller_example.py
rename to examples/guides/demos/spike/function_caller_example.py
diff --git a/examples/demos/spike/memory.py b/examples/guides/demos/spike/memory.py
similarity index 100%
rename from examples/demos/spike/memory.py
rename to examples/guides/demos/spike/memory.py
diff --git a/examples/demos/spike/spike.zip b/examples/guides/demos/spike/spike.zip
similarity index 100%
rename from examples/demos/spike/spike.zip
rename to examples/guides/demos/spike/spike.zip
diff --git a/examples/demos/spike/test.py b/examples/guides/demos/spike/test.py
similarity index 100%
rename from examples/demos/spike/test.py
rename to examples/guides/demos/spike/test.py
diff --git a/examples/demos/synthetic_data/profession_sim/convert_json_to_csv.py b/examples/guides/demos/synthetic_data/profession_sim/convert_json_to_csv.py
similarity index 100%
rename from examples/demos/synthetic_data/profession_sim/convert_json_to_csv.py
rename to examples/guides/demos/synthetic_data/profession_sim/convert_json_to_csv.py
diff --git a/examples/demos/synthetic_data/profession_sim/data.csv b/examples/guides/demos/synthetic_data/profession_sim/data.csv
similarity index 100%
rename from examples/demos/synthetic_data/profession_sim/data.csv
rename to examples/guides/demos/synthetic_data/profession_sim/data.csv
diff --git a/examples/demos/synthetic_data/profession_sim/format_prompt.py b/examples/guides/demos/synthetic_data/profession_sim/format_prompt.py
similarity index 100%
rename from examples/demos/synthetic_data/profession_sim/format_prompt.py
rename to examples/guides/demos/synthetic_data/profession_sim/format_prompt.py
diff --git a/examples/demos/synthetic_data/profession_sim/profession_persona_generator.py b/examples/guides/demos/synthetic_data/profession_sim/profession_persona_generator.py
similarity index 100%
rename from examples/demos/synthetic_data/profession_sim/profession_persona_generator.py
rename to examples/guides/demos/synthetic_data/profession_sim/profession_persona_generator.py
diff --git a/examples/demos/synthetic_data/profession_sim/profession_personas.csv b/examples/guides/demos/synthetic_data/profession_sim/profession_personas.csv
similarity index 100%
rename from examples/demos/synthetic_data/profession_sim/profession_personas.csv
rename to examples/guides/demos/synthetic_data/profession_sim/profession_personas.csv
diff --git a/examples/demos/synthetic_data/profession_sim/profession_personas.progress.backup.json b/examples/guides/demos/synthetic_data/profession_sim/profession_personas.progress.backup.json
similarity index 100%
rename from examples/demos/synthetic_data/profession_sim/profession_personas.progress.backup.json
rename to examples/guides/demos/synthetic_data/profession_sim/profession_personas.progress.backup.json
diff --git a/examples/demos/synthetic_data/profession_sim/profession_personas.progress.json b/examples/guides/demos/synthetic_data/profession_sim/profession_personas.progress.json
similarity index 100%
rename from examples/demos/synthetic_data/profession_sim/profession_personas.progress.json
rename to examples/guides/demos/synthetic_data/profession_sim/profession_personas.progress.json
diff --git a/examples/demos/synthetic_data/profession_sim/profession_personas_new_10.csv b/examples/guides/demos/synthetic_data/profession_sim/profession_personas_new_10.csv
similarity index 100%
rename from examples/demos/synthetic_data/profession_sim/profession_personas_new_10.csv
rename to examples/guides/demos/synthetic_data/profession_sim/profession_personas_new_10.csv
diff --git a/examples/demos/synthetic_data/profession_sim/profession_personas_new_10.progress.backup.json b/examples/guides/demos/synthetic_data/profession_sim/profession_personas_new_10.progress.backup.json
similarity index 100%
rename from examples/demos/synthetic_data/profession_sim/profession_personas_new_10.progress.backup.json
rename to examples/guides/demos/synthetic_data/profession_sim/profession_personas_new_10.progress.backup.json
diff --git a/examples/demos/synthetic_data/profession_sim/profession_personas_new_10.progress.backup_new.json b/examples/guides/demos/synthetic_data/profession_sim/profession_personas_new_10.progress.backup_new.json
similarity index 100%
rename from examples/demos/synthetic_data/profession_sim/profession_personas_new_10.progress.backup_new.json
rename to examples/guides/demos/synthetic_data/profession_sim/profession_personas_new_10.progress.backup_new.json
diff --git a/examples/demos/synthetic_data/profession_sim/profession_personas_new_10.progress.json b/examples/guides/demos/synthetic_data/profession_sim/profession_personas_new_10.progress.json
similarity index 100%
rename from examples/demos/synthetic_data/profession_sim/profession_personas_new_10.progress.json
rename to examples/guides/demos/synthetic_data/profession_sim/profession_personas_new_10.progress.json
diff --git a/examples/demos/synthetic_data/profession_sim/profession_personas_new_10.progress_neee.json b/examples/guides/demos/synthetic_data/profession_sim/profession_personas_new_10.progress_neee.json
similarity index 100%
rename from examples/demos/synthetic_data/profession_sim/profession_personas_new_10.progress_neee.json
rename to examples/guides/demos/synthetic_data/profession_sim/profession_personas_new_10.progress_neee.json
diff --git a/examples/demos/synthetic_data/profession_sim/prompt.txt b/examples/guides/demos/synthetic_data/profession_sim/prompt.txt
similarity index 100%
rename from examples/demos/synthetic_data/profession_sim/prompt.txt
rename to examples/guides/demos/synthetic_data/profession_sim/prompt.txt
diff --git a/examples/demos/synthetic_data/profession_sim/prompt_formatted.md b/examples/guides/demos/synthetic_data/profession_sim/prompt_formatted.md
similarity index 100%
rename from examples/demos/synthetic_data/profession_sim/prompt_formatted.md
rename to examples/guides/demos/synthetic_data/profession_sim/prompt_formatted.md
diff --git a/examples/guides/generation_length_blog/README.md b/examples/guides/generation_length_blog/README.md
new file mode 100644
index 00000000..6dbf0231
--- /dev/null
+++ b/examples/guides/generation_length_blog/README.md
@@ -0,0 +1,13 @@
+# Generation Length Blog Examples
+
+This directory contains examples related to generation length management and long-form content generation.
+
+## Examples
+
+- [longform_generator.py](longform_generator.py) - Long-form content generator
+- [universal_api.py](universal_api.py) - Universal API for generation
+
+## Overview
+
+These examples demonstrate techniques for managing generation length, creating long-form content, and implementing universal APIs for content generation. Useful for blog posts, articles, and extended text generation tasks.
+
diff --git a/examples/guides/hackathon_judge_agent/README.md b/examples/guides/hackathon_judge_agent/README.md
new file mode 100644
index 00000000..100b9bd9
--- /dev/null
+++ b/examples/guides/hackathon_judge_agent/README.md
@@ -0,0 +1,13 @@
+# Hackathon Judge Agent
+
+This directory contains a hackathon project judging agent example.
+
+## Examples
+
+- [hackathon_judger_agent.py](hackathon_judger_agent.py) - Hackathon project judging agent
+- [projects.csv](projects.csv) - Sample projects dataset
+
+## Overview
+
+This example demonstrates an agent system designed to evaluate and judge hackathon projects. The agent can analyze project descriptions, assess quality, and provide structured feedback based on predefined criteria.
+
diff --git a/examples/guides/hackathon_judge_agent/hackathon_judger_agent.py b/examples/guides/hackathon_judge_agent/hackathon_judger_agent.py
new file mode 100644
index 00000000..8cce2659
--- /dev/null
+++ b/examples/guides/hackathon_judge_agent/hackathon_judger_agent.py
@@ -0,0 +1,120 @@
+from swarms import Agent
+
+HACKATHON_JUDGER_AGENT_PROMPT = """
+## š§ **System Prompt: Hackathon Judger Agent (AI Agents Focus)**
+
+**Role:**
+You are an expert hackathon evaluation assistant judging submissions in the *Builders Track*.
+Your task is to evaluate all projects using the provided criteria and automatically identify those related to **AI agents, agentic architectures, or autonomous intelligent systems**.
+
+You must then produce a **ranked report** of the **top 3 AI agentārelated projects**, complete with weighted scores, category breakdowns, and short qualitative summaries.
+
+---
+
+### šÆ **Judging Framework**
+
+Each project is evaluated using the following **weighted criteria** (from the Builders Track official judging rubric):
+
+#### 1. Technical Feasibility & Implementation (30%)
+
+Evaluate how well the project was built and its level of technical sophistication.
+
+* **90ā100:** Robust & flawless. Excellent code quality. Seamless, innovative integration.
+* **80ā90:** Works as intended. Clean implementation. Effective Solana or system integration.
+* **60ā80:** Functional but basic or partially implemented.
+* **0ā60:** Non-functional or poor implementation.
+
+#### 2. Quality & Clarity of Demo (20%)
+
+Evaluate the quality, clarity, and impact of the presentation or demo.
+
+* **90ā100:** Compelling, professional, inspiring vision.
+* **80ā90:** Clear, confident presentation with good storytelling.
+* **60ā80:** Functional but unpolished demo.
+* **0ā60:** Weak or confusing presentation.
+
+#### 3. Presentation of Idea (30%)
+
+Evaluate how clearly the idea is communicated and how well it conveys its purpose and impact.
+
+* **90ā100:** Masterful, engaging storytelling. Simplifies complex ideas elegantly.
+* **80ā90:** Clear, structured, and accessible presentation.
+* **60ā80:** Understandable but lacks focus.
+* **0ā60:** Confusing or poorly explained.
+
+#### 4. Innovation & Originality (20%)
+
+Evaluate the novelty and originality of the idea, particularly within the context of agentic AI.
+
+* **90ā100:** Breakthrough concept. Strong fit with ecosystem and AI innovation.
+* **80ā90:** Distinct, creative, and forward-thinking.
+* **60ā80:** Incremental improvement.
+* **0ā60:** Unoriginal or derivative.
+
+---
+
+### āļø **Scoring Rules**
+
+1. Assign each project a **score (0ā100)** for each category.
+2. Apply weights to compute a **final total score out of 100**:
+
+ * Technical Feasibility ā 30%
+ * Demo Quality ā 20%
+ * Presentation ā 30%
+ * Innovation ā 20%
+3. Filter and **select only projects related to AI agents or agentic systems**.
+4. Rank these filtered projects **from highest to lowest total score**.
+5. Select the **top 3 projects** for the final report.
+
+---
+
+### š§© **Output Format**
+
+Create a markdown report of the top 3 projects with how they follow the judging criteria and why they are the best.
+
+---
+
+### š§ **Special Instructions**
+
+* Consider āAI agentsā to include:
+
+ * Autonomous or semi-autonomous decision-making systems
+ * Multi-agent frameworks or LLM-powered agents
+ * Tools enabling agent collaboration, coordination, or reasoning
+ * Infrastructure for agentic AI development or deployment
+* If fewer than 3 relevant projects exist, output only those available.
+* Use concise, professional tone and evidence-based reasoning in feedback.
+* Avoid bias toward hype; focus on execution, innovation, and ecosystem impact.
+
+---
+
+Would you like me to tailor this further for **automatic integration** into an evaluation pipeline (e.g., where the agent consumes structured project metadata and outputs ranked JSON reports automatically)? That version would include function schemas and evaluation templates.
+
+"""
+
+# Initialize the agent
+agent = Agent(
+ agent_name="Hackathon-Judger-Agent",
+ agent_description="A hackathon judger agent that evaluates projects based on the judging criteria and produces a ranked report of the top 3 projects.",
+ model_name="claude-haiku-4-5",
+ system_prompt=HACKATHON_JUDGER_AGENT_PROMPT,
+ dynamic_temperature_enabled=True,
+ max_loops=1,
+ dynamic_context_window=True,
+ streaming_on=False,
+ top_p=None,
+ output_type="dict",
+)
+
+
+def read_csv_file(file_path: str = "projects.csv") -> str:
+ """Reads the entire CSV file and returns its content as a string."""
+ with open(file_path, mode="r", encoding="utf-8") as f:
+ return f.read()
+
+
+out = agent.run(
+ task=read_csv_file(),
+)
+
+print(out)
diff --git a/examples/guides/hackathon_judge_agent/projects.csv b/examples/guides/hackathon_judge_agent/projects.csv
new file mode 100644
index 00000000..62119e50
--- /dev/null
+++ b/examples/guides/hackathon_judge_agent/projects.csv
@@ -0,0 +1,149 @@
+No.,Full Name,Respondent's country,Affiliation,Project Name,Brief Description,Brief Description (English Translation),Storytelling Video OR Article Link,Demo Link,Repository Link,Link to Published Work,Use of Toolkit,"Technical Feasibility
+& Implementation
+(30%)","Quality
+& Clarity of Demo
+(20%)","Presentation of Idea
+(30%)","Innovation
+& Originality of Idea
+(20%)","Manual
+Total Score",Manual Scoring Feedback
+1,Yuki Sato,Japan,Keio University Blockchain Club,Daiko,Daiko AI tells you when to sell and why based on market data and risk profile.,Daiko AI tells you when to sell and why based on market data and risk profile.,https://www.youtube.com/watch?v=VJYT4-jbT8U,https://app.daiko.ai,https://github.com/Daiko-AI/daiko-ai-mvp-monorepo,https://x.com/DaikoAI/status/1923167905052586030,Solana AI Tools,,,,,0,
+2,Treap,Hong Kong,0xWHU/ ę¦ę±å¤§å¦ Web3 äæ±ä¹éØ,neko-sol,"åŗäŗ Solana åŗåé¾å AI ęęÆēäŗꬔå
ē«åØå
»ęęøøę MVP ēę¬
+
+ę øåæåč½
+ā
é±å
čæę„: ęÆę Phantom å Solflare é±å
+ā
Solana Devnet éę: å®ę“ēåŗåé¾äŗ¤äŗ
+ā
儽ęåŗ¦ē³»ē»: åŗäŗ SPL Token ēé¾äø儽ęåŗ¦ååØ
+ā
å®ę¶ä½é¢ę„čÆ¢: ę„ēé±å
SOL ä½é¢
+ā
Devnet ē©ŗę: č·åęµčÆ SOL
+ā
儽ęåŗ¦ēēŗ§ē³»ē»: 6 äøŖēēŗ§ä»åčÆå°č³é«ē¾ē»
+é¾äøęä½
+åå»ŗ儽ęåŗ¦ Token Mintļ¼ęÆäøŖē«åØē¬ē«ļ¼
+éøé 儽ęåŗ¦ Token å°ēØę·č“¦ę·
+å®ę¶ę„čƢ儽ęåŗ¦åę°
+ęęäŗ¤ęåÆåØ Solana Explorer ę„ē","MVP Version of a 2D Catgirl Raising Game Based on Solana Blockchain and AI Technology
+
+Core Features
+ā
Wallet Connection: Supports Phantom and Solflare wallets
+ā
Solana Devnet Integration: Complete blockchain interaction
+ā
Affection System: On-chain affection storage based on SPL Tokens
+ā
Real-time Balance Inquiry: View your wallet's SPL balance
+ā
Devnet Airdrop: Obtain test SPL
+ā
Affection Level System: 6 levels from initial acquaintance to ultimate bond
+On-chain Operations
+Create Affection Token Mint (individual for each catgirl)
+Mint Affection Tokens to your user account
+Real-time Affection Score Inquiry
+All transactions can be viewed in Solana Explorer",https://github.com/TreapGoGo/neko-sol,,https://github.com/TreapGoGo/neko-sol,,"Swarms AI API, Solana AI Tools",,,,,0,
+3,Gladx,Hong Kong,0xWHU/ ę¦ę±å¤§å¦ Web3 äæ±ä¹éØ,sol-dream,"äøŖåę°ēå»äøåæååŗēØļ¼ä½æēØAIå°ęØēę¢¦å¢ēꮵ蔄å
Øęå®ę“ę
äŗļ¼å¹¶ę°øä¹
č®°å½åØSolanaåŗåé¾äøć
+
+āØ ē¹ę§
+š Phantomé±å
éę - å®å
Øä¾æę·ēé±å
čæę„
+š¤ AI驱åØ - ä½æēØOpenAI GPT-4ęØ”åå°ę¢¦å¢ēꮵ蔄å
Øęå®ę“ę
äŗ
+āļø åŗåé¾ååØ - å°ę¢¦å¢ę°øä¹
č®°å½åØSolanaåŗåé¾äø
+šØ ē°ä»£åUI - ē®ę“ē¾č§ēēØę·ēé¢
+š č½»éēŗ§ - ēŗÆåē«Æå®ē°ļ¼ę éåē«Æęå”åØ","An innovative decentralized application that uses AI to complete your dream fragments into a full story and permanently record it on the Solana blockchain.
+
+āØ Features
+
+š Phantom Wallet Integration - Secure and convenient wallet connection
+
+š¤ AI-Powered - Uses OpenAI GPT-4 model to complete dream fragments into a full story
+
+āļø Blockchain Storage - Permanently records dreams on the Solana blockchain
+
+šØ Modern UI - Clean and beautiful user interface
+
+š Lightweight - Pure front-end implementation, no back-end server required",https://github.com/TreapGoGo/sol-dream,,https://github.com/TreapGoGo/sol-dream,,"Solana AI Tools, Swarms AI API",,,,,0,
+4,Rafael Oliveira,Brazil,Other,AurumGrid,"Aurumgrid AUI ā Artificial Universal Intelligence
+","Aurumgrid AUI ā Artificial Universal Intelligence
+",https://github.com/Aurumgrid/aurumgrid-aui,https://github.com/Aurumgrid/aurumgrid-aui,https://github.com/Aurumgrid/aurumgrid-aui,https://x.com/RafaelO9416467/status/1978837487494516820,"Solana AI Tools, Aethir GPU Compute, Swarms AI API",,,,,0,
+5,Michael Afolabi,Nigeria,Superteam NG,Wojat,"Wojat is a comprehensive, AI-powered memecoin hunting platform that combines real-time data collection, social media analysis, and AI-driven insights to help traders discover the next big memecoin opportunities. Built with modern web technologies and powered by advanced AI agents.","Wojat is a comprehensive, AI-powered memecoin hunting platform that combines real-time data collection, social media analysis, and AI-driven insights to help traders discover the next big memecoin opportunities. Built with modern web technologies and powered by advanced AI agents.",https://drive.google.com/drive/folders/1-qESLXy-PvwB-L0CTYeUlxs-KpiUVATq?usp=sharing,https://drive.google.com/drive/folders/1-qESLXy-PvwB-L0CTYeUlxs-KpiUVATq?usp=sharing,https://github.com/Afoxcute/wojat,https://x.com/wojat118721/status/1979682642309341282,Solana AI Tools,,,,,0,
+6,Brooks Shui,Taiwan,Nankai University Blockchain Association / åå¼å¤§å¦åŗåé¾åä¼,SPR Platform,"š¦¹š»āāļøš®SPR1.0: The ATH-Powered VLM estimation platform (šhttps://reflexresearches.com/)
+
+What We Built (and Why)
+
+SPR makes some difference. It's an autonomous platform that uses a swarm of our custom-built AI agents to handle the entire assessment process in minutes, not days. We let customers and businesses spare their time and improve the efficiency.
+
+The Problem We're Fixing
+
+We remove the personality in recycling, and spare the cost of the laboratory and long time. Also, thinking of the high training cost of a VLM-model, we use the Aethir GPU to shrink its fee.
+
+Our Solution
+
+The model consists of two versions: image recognition and video recognition.
+
+The image recognition module can accurately capture detailed appearance features of smartphones, detecting physical damages such as screen scratches, frame dents, and back cover wear in milliseconds. Meanwhile, it quickly verifies core configuration information including processor model, RAM capacity, and storage size through hardware parameter recognition algorithms.
+
+The video recognition module further breaks through the limitations of static recognition by analyzing dynamic footage of smartphone boot-up demonstrations and functional operations to determine if there are issues such as color cast, light leakage, or touch failure on the screen. It also accurately identifies whether the camera lens has scratches, bubbles, or cracks, and fully verifies the integrity of functions such as camera focusing and flash. This multi-dimensional intelligent detection method constructs a full-lifecycle evaluation system for smartphones, from hardware performance to appearance wear, providing objective and accurate data support for pricing.","š¦¹š»āāļøš®SPR1.0: The ATH-Powered VLM estimation platform (šhttps://reflexresearches.com/)
+
+What We Built (and Why)
+
+SPR makes some difference. It's an autonomous platform that uses a swarm of our custom-built AI agents to handle the entire assessment process in minutes, not days. We let customers and businesses spare their time and improve the efficiency.
+
+The Problem We're Fixing
+
+We remove the personality in recycling, and spare the cost of the laboratory and long time. Also, thinking of the high training cost of a VLM-model, we use the Aethir GPU to shrink its fee.
+
+Our Solution
+
+The model consists of two versions: image recognition and video recognition.
+
+The image recognition module can accurately capture detailed appearance features of smartphones, detecting physical damages such as screen scratches, frame dents, and back cover wear in milliseconds. Meanwhile, it quickly verifies core configuration information including processor model, RAM capacity, and storage size through hardware parameter recognition algorithms.
+
+The video recognition module further breaks through the limitations of static recognition by analyzing dynamic footage of smartphone boot-up demonstrations and functional operations to determine if there are issues such as color cast, light leakage, or touch failure on the screen. It also accurately identifies whether the camera lens has scratches, bubbles, or cracks, and fully verifies the integrity of functions such as camera focusing and flash. This multi-dimensional intelligent detection method constructs a full-lifecycle evaluation system for smartphones, from hardware performance to appearance wear, providing objective and accurate data support for pricing.",https://reflexresearches.com/,https://youtu.be/oprRqLLlRIQ?si=WXtOnpnyM9HN0WDI,https://github.com/paterleng/second_recycling_system,https://x.com/zhangyuxia4454/status/1980183358253756779?s=46,Aethir GPU Compute,,,,,0,
+7,Ozan AndaƧ,Poland,DoraHacks,Elowen,"Elowen is a decentralized AI project that allows users to chat with fictional and nonfictional characters without censorship while contributing to the development of AI
+models.
+
+The platform is designed to be community-driven, enabling creators to earn $ELW
+tokens through periodic reward distribution based on the usage of their chatbots.
+
+$ELW is fully controlled by a Solana program, preventing any manual interference or
+large-scale token selloffs.
+
+As project-wise, you can think of it as a decentralized and censorless character.ai
+alternative.
+
+We have an ecosystem of tools:
+- Web App for builders & consumers
+- X (formerly Twitter) bot that impersonates a character and replies to threads (@elowenbot)
+- Telegram Bot to move chatting beyond the website
+- Public API
+- Solana Program & Token (Currently on Testnet)","Elowen is a decentralized AI project that allows users to chat with fictional and nonfictional characters without censorship while contributing to the development of AI
+models.
+
+The platform is designed to be community-driven, enabling creators to earn $ELW
+tokens through periodic reward distribution based on the usage of their chatbots.
+
+$ELW is fully controlled by a Solana program, preventing any manual interference or
+large-scale token selloffs.
+
+As project-wise, you can think of it as a decentralized and censorless character.ai
+alternative.
+
+We have an ecosystem of tools:
+- Web App for builders & consumers
+- X (formerly Twitter) bot that impersonates a character and replies to threads (@elowenbot)
+- Telegram Bot to move chatting beyond the website
+- Public API
+- Solana Program & Token (Currently on Testnet)",https://drive.google.com/file/d/1odChCG-RZeiH7i1OjR88dUitb2h1pkJY/view?usp=sharing,https://elowen.ai,https://github.com/elowen-ai,https://x.com/OzanAndac_/status/1981922432689619368,Solana AI Tools,,,,,0,
+8,Shivam Agarwal,India,Other,SolGame,"A lightweight pixel **multicharacter**, Play To Earn dungeon game built on the Solana Devnet Blockchain, built with Phaser, powered by Metaplex NFT Marketplace Protocol. Our motivation is to enable users to own what they earn.","A lightweight pixel **multicharacter**, Play To Earn dungeon game built on the Solana Devnet Blockchain, built with Phaser, powered by Metaplex NFT Marketplace Protocol. Our motivation is to enable users to own what they earn.",https://docs.google.com/presentation/d/1g4LZlb-SBxnCUIOofO7lvPPPeMLYq664hZqJFO08Zt4/edit?usp=sharing,https://sol-game-six.vercel.app/,https://github.com/ShivamAgarwal-code/SolGame.git,,"Solana AI Tools, Swarms AI API",,,,,0,
+9,Fawzan Pima,Ghana,SG Union,Sol Terminal," An mcp server for solana that allows ai agents to gain context of solana capabilities like sending solana , checking sol balance , manage sol accounts and wallets getting sol address al without needing a sol app installed you just connect the mcp to your agent and strt using it , u add your private key in the mcp env . Ware giving ai agents the autonomous capabilities to run activities onchain."," An mcp server for solana that allows ai agents to gain context of solana capabilities like sending solana , checking sol balance , manage sol accounts and wallets getting sol address al without needing a sol app installed you just connect the mcp to your agent and strt using it , u add your private key in the mcp env . Ware giving ai agents the autonomous capabilities to run activities onchain.",https://www.loom.com/share/3c1295e0f80149e792b7a6f65bb45c1e,https://fozagtx.github.io/SolanaAiTerminal/,https://github.com/fozagtx/SolanaAiTerminal,https://youtu.be/iSs1Lf8n-fw?si=B5nUkyld1RW7yjjF,Solana AI Tools,,,,,0,
+10,Riadh M belarbi,United Kingdom of Great Britain and Northern Ireland,Imperial Blockchain,toky.fun,"Toky.fun is an all in one platform ecosystem allowing users to launch projects and grow them with no code, using AI agents and leveraging swarms. aimed at Web3 founders, small teams and non technicals, with toky.fun you can vibe code websites, mobile apps, manage your socials, moderate your group chats and get help with compliance, and of course launch tokens where you need them! ","Toky.fun is an all in one platform ecosystem allowing users to launch projects and grow them with no code, using AI agents and leveraging swarms. aimed at Web3 founders, small teams and non technicals, with toky.fun you can vibe code websites, mobile apps, manage your socials, moderate your group chats and get help with compliance, and of course launch tokens where you need them! ",https://aisolana.s3.eu-north-1.amazonaws.com/toky.fun+presentation.MP4,https://aisolana.s3.eu-north-1.amazonaws.com/toky2.0.mp4,https://github.com/its-mc/toky.fun.git,,Solana AI Tools,,,,,0,
+11,Yadidya Medepalli,United Kingdom of Great Britain and Northern Ireland,Other,Nebula AI,"Nebula Protocol is the world's first decentralized Earth observation platform where autonomous AI agents with their own Solana wallets monitor our planet 24/7 and record findings immutably on-chain. Nine specialized AI agents (Forest Guardian, Ice Sentinel, Disaster Responder, etc.) independently sign blockchain transactions, execute environmental missions, and mint NFTs demonstrating autonomous AI-driven blockchain operations that address centralized data silos and enable verifiable disaster prevention. Fully deployed on Solana with smart contracts, voice commands, and mind- blowing visualization proving AI agents can autonomously operate blockchain infrastructure at scale.
+
+Demo link at: https://x.com/MYadidya/status/1983074064211308648
+or
+Youtube link: https://youtu.be/fJrnTWOWPRM","Nebula Protocol is the world's first decentralized Earth observation platform where autonomous AI agents with their own Solana wallets monitor our planet 24/7 and record findings immutably on-chain. Nine specialized AI agents (Forest Guardian, Ice Sentinel, Disaster Responder, etc.) independently sign blockchain transactions, execute environmental missions, and mint NFTs demonstrating autonomous AI-driven blockchain operations that address centralized data silos and enable verifiable disaster prevention. Fully deployed on Solana with smart contracts, voice commands, and mind- blowing visualization proving AI agents can autonomously operate blockchain infrastructure at scale.
+
+Demo link at: https://x.com/MYadidya/status/1983074064211308648
+or
+Youtube link: https://youtu.be/fJrnTWOWPRM",https://nebv2article.netlify.app/,https://nebulav2.netlify.app/,https://github.com/YadidyaM/Nebula-2.0---Decentralized-Earth-Observation-Platform,https://x.com/MYadidya/status/1983074064211308648,"Solana AI Tools, Swarms AI API",,,,,0,
+12,Togo,Japan,N/A,TinyPay,"TinyPay is a crypto-native payment application built on Solana, enabling seamless real-world transactions with digital assets ā even without an internet connection.
+Weāre building the bridge between digital assets and everyday spending, making crypto payments as effortless as cash or cards.","TinyPay is a crypto-native payment application built on Solana, enabling seamless real-world transactions with digital assets ā even without an internet connection.
+Weāre building the bridge between digital assets and everyday spending, making crypto payments as effortless as cash or cards.",https://docs.google.com/presentation/d/1kXA47K0ovv51GvYYEm2yWVHrwJYQLrtKMqMoS5wUhMk/edit?usp=sharing,https://www.youtube.com/watch?v=E59_zBE-Mao,https://github.com/TrustPipe/TinyPayContract-Solana,https://x.com/TrustLucian/status/1981912066761056372,Solana AI Tools,,,,,0,
+13,Alan Wang,Japan,solar,foxhole.ai,"Foxhole AI monitors influential Twitter accounts for crypto keywords and instantly delivers verified contract addresses to users for trading.
+
+","Foxhole AI monitors influential Twitter accounts for crypto keywords and instantly delivers verified contract addresses to users for trading.
+
+",https://youtu.be/nn3zgyBGgdQ?si=xYHt87szURiqvVZz,https://youtu.be/nn3zgyBGgdQ?si=xYHt87szURiqvVZz,https://github.com/foxholeAI/foxholeAI,https://x.com/alan_ywang/status/1984315036429664509,"Solana AI Tools, Aethir GPU Compute, Swarms AI API",,,,,0,
\ No newline at end of file
diff --git a/examples/guides/hackathons/README.md b/examples/guides/hackathons/README.md
new file mode 100644
index 00000000..e2de0607
--- /dev/null
+++ b/examples/guides/hackathons/README.md
@@ -0,0 +1,18 @@
+# Hackathon Examples
+
+This directory contains hackathon project examples and implementations.
+
+## Subdirectories
+
+### Hackathon September 27
+- [hackathon_sep_27/](hackathon_sep_27/) - September 27 hackathon projects
+ - [api_client.py](hackathon_sep_27/api_client.py) - API client implementation
+ - [diet_coach_agent.py](hackathon_sep_27/diet_coach_agent.py) - Diet coach agent
+ - [nutritional_content_analysis_swarm.py](hackathon_sep_27/nutritional_content_analysis_swarm.py) - Nutritional analysis swarm
+ - [nutritonal_content_analysis_swarm.sh](hackathon_sep_27/nutritonal_content_analysis_swarm.sh) - Analysis script
+ - [pizza.jpg](hackathon_sep_27/pizza.jpg) - Sample image
+
+## Overview
+
+This directory contains real hackathon projects built with Swarms, demonstrating practical applications and creative uses of the framework. These examples showcase how Swarms can be used to build domain-specific solutions quickly.
+
diff --git a/examples/hackathons/hackathon_sep_27/api_client.py b/examples/guides/hackathons/hackathon_sep_27/api_client.py
similarity index 100%
rename from examples/hackathons/hackathon_sep_27/api_client.py
rename to examples/guides/hackathons/hackathon_sep_27/api_client.py
diff --git a/examples/hackathons/hackathon_sep_27/diet_coach_agent.py b/examples/guides/hackathons/hackathon_sep_27/diet_coach_agent.py
similarity index 100%
rename from examples/hackathons/hackathon_sep_27/diet_coach_agent.py
rename to examples/guides/hackathons/hackathon_sep_27/diet_coach_agent.py
diff --git a/examples/hackathons/hackathon_sep_27/nutritional_content_analysis_swarm.py b/examples/guides/hackathons/hackathon_sep_27/nutritional_content_analysis_swarm.py
similarity index 100%
rename from examples/hackathons/hackathon_sep_27/nutritional_content_analysis_swarm.py
rename to examples/guides/hackathons/hackathon_sep_27/nutritional_content_analysis_swarm.py
diff --git a/examples/hackathons/hackathon_sep_27/nutritonal_content_analysis_swarm.sh b/examples/guides/hackathons/hackathon_sep_27/nutritonal_content_analysis_swarm.sh
similarity index 100%
rename from examples/hackathons/hackathon_sep_27/nutritonal_content_analysis_swarm.sh
rename to examples/guides/hackathons/hackathon_sep_27/nutritonal_content_analysis_swarm.sh
diff --git a/examples/hackathons/hackathon_sep_27/pizza.jpg b/examples/guides/hackathons/hackathon_sep_27/pizza.jpg
similarity index 100%
rename from examples/hackathons/hackathon_sep_27/pizza.jpg
rename to examples/guides/hackathons/hackathon_sep_27/pizza.jpg
diff --git a/examples/guides/nano_banana_jarvis_agent/README.md b/examples/guides/nano_banana_jarvis_agent/README.md
new file mode 100644
index 00000000..683a05ba
--- /dev/null
+++ b/examples/guides/nano_banana_jarvis_agent/README.md
@@ -0,0 +1,18 @@
+# Nano Banana Jarvis Agent
+
+This directory contains the Nano Banana Jarvis agent example, demonstrating vision and multimodal capabilities.
+
+## Examples
+
+- [jarvis_agent.py](jarvis_agent.py) - Main Jarvis agent implementation
+- [img_gen_nano_banana.py](img_gen_nano_banana.py) - Image generation example
+
+## Images
+
+- Sample images included: building.jpg, hk.jpg, image.jpg, miami.jpg
+- [annotated_images/](annotated_images/) - Directory containing annotated image examples
+
+## Overview
+
+The Nano Banana Jarvis agent demonstrates advanced vision and multimodal capabilities, including image analysis, image generation, and visual understanding. This example showcases how to build agents that can process and generate visual content.
+
diff --git a/examples/guides/web_scraper_agents/README.md b/examples/guides/web_scraper_agents/README.md
new file mode 100644
index 00000000..651a6562
--- /dev/null
+++ b/examples/guides/web_scraper_agents/README.md
@@ -0,0 +1,13 @@
+# Web Scraper Agents
+
+This directory contains examples demonstrating web scraping capabilities with agents.
+
+## Examples
+
+- [batched_scraper_agent.py](batched_scraper_agent.py) - Batched web scraping agent
+- [web_scraper_agent.py](web_scraper_agent.py) - Basic web scraper agent
+
+## Overview
+
+These examples demonstrate how to build agents capable of web scraping, extracting information from websites, and processing web content. The batched version shows how to handle multiple URLs efficiently, while the basic example demonstrates core scraping functionality.
+
diff --git a/examples/workshops/README.md b/examples/guides/workshops/README.md
similarity index 100%
rename from examples/workshops/README.md
rename to examples/guides/workshops/README.md
diff --git a/examples/workshops/workshop_sep_20/agent_tools_dict_example.py b/examples/guides/workshops/workshop_sep_20/agent_tools_dict_example.py
similarity index 100%
rename from examples/workshops/workshop_sep_20/agent_tools_dict_example.py
rename to examples/guides/workshops/workshop_sep_20/agent_tools_dict_example.py
diff --git a/examples/workshops/workshop_sep_20/batched_grid_simple_example.py b/examples/guides/workshops/workshop_sep_20/batched_grid_simple_example.py
similarity index 100%
rename from examples/workshops/workshop_sep_20/batched_grid_simple_example.py
rename to examples/guides/workshops/workshop_sep_20/batched_grid_simple_example.py
diff --git a/examples/workshops/workshop_sep_20/geo_guesser_agent.py b/examples/guides/workshops/workshop_sep_20/geo_guesser_agent.py
similarity index 100%
rename from examples/workshops/workshop_sep_20/geo_guesser_agent.py
rename to examples/guides/workshops/workshop_sep_20/geo_guesser_agent.py
diff --git a/examples/workshops/workshop_sep_20/hk.jpg b/examples/guides/workshops/workshop_sep_20/hk.jpg
similarity index 100%
rename from examples/workshops/workshop_sep_20/hk.jpg
rename to examples/guides/workshops/workshop_sep_20/hk.jpg
diff --git a/examples/workshops/workshop_sep_20/jarvis_agent.py b/examples/guides/workshops/workshop_sep_20/jarvis_agent.py
similarity index 100%
rename from examples/workshops/workshop_sep_20/jarvis_agent.py
rename to examples/guides/workshops/workshop_sep_20/jarvis_agent.py
diff --git a/examples/workshops/workshop_sep_20/miami.jpg b/examples/guides/workshops/workshop_sep_20/miami.jpg
similarity index 100%
rename from examples/workshops/workshop_sep_20/miami.jpg
rename to examples/guides/workshops/workshop_sep_20/miami.jpg
diff --git a/examples/workshops/workshop_sep_20/mountains.jpg b/examples/guides/workshops/workshop_sep_20/mountains.jpg
similarity index 100%
rename from examples/workshops/workshop_sep_20/mountains.jpg
rename to examples/guides/workshops/workshop_sep_20/mountains.jpg
diff --git a/examples/workshops/workshop_sep_20/same_task_example.py b/examples/guides/workshops/workshop_sep_20/same_task_example.py
similarity index 100%
rename from examples/workshops/workshop_sep_20/same_task_example.py
rename to examples/guides/workshops/workshop_sep_20/same_task_example.py
diff --git a/examples/mcp/agent_examples/README.md b/examples/mcp/agent_examples/README.md
new file mode 100644
index 00000000..ed5da461
--- /dev/null
+++ b/examples/mcp/agent_examples/README.md
@@ -0,0 +1,15 @@
+# MCP Agent Examples
+
+This directory contains examples demonstrating agent implementations using Model Context Protocol (MCP).
+
+## Examples
+
+- [agent_mcp_old.py](agent_mcp_old.py) - Legacy MCP agent implementation
+- [agent_multi_mcp_connections.py](agent_multi_mcp_connections.py) - Multi-MCP connection agent
+- [agent_tools_dict_example.py](agent_tools_dict_example.py) - Agent tools dictionary example
+- [mcp_exampler.py](mcp_exampler.py) - MCP example implementation
+
+## Overview
+
+MCP agent examples demonstrate how to build agents that leverage the Model Context Protocol for enhanced context management and tool integration. These examples show various patterns for connecting agents to MCP servers and using MCP tools.
+
diff --git a/examples/mcp/mcp_utils/README.md b/examples/mcp/mcp_utils/README.md
new file mode 100644
index 00000000..0803e7e7
--- /dev/null
+++ b/examples/mcp/mcp_utils/README.md
@@ -0,0 +1,27 @@
+# MCP Utils
+
+This directory contains utility functions and helpers for MCP implementations.
+
+## Examples
+
+- [client.py](client.py) - MCP client implementation
+- [mcp_client_call.py](mcp_client_call.py) - MCP client call utilities
+- [mcp_multiple_servers_example.py](mcp_multiple_servers_example.py) - Multiple MCP servers example
+- [mcp_multiple_tool_test.py](mcp_multiple_tool_test.py) - Multiple tool testing
+- [multiagent_client.py](multiagent_client.py) - Multi-agent MCP client
+- [singleagent_client.py](singleagent_client.py) - Single agent MCP client
+- [test_multiple_mcp_servers.py](test_multiple_mcp_servers.py) - Multiple server testing
+- [utils.py](utils.py) - General MCP utilities
+
+## Subdirectories
+
+- [utils/](utils/) - Additional utility functions
+ - [find_tools_on_mcp.py](utils/find_tools_on_mcp.py) - Tool discovery
+ - [mcp_execute_example.py](utils/mcp_execute_example.py) - MCP execution example
+ - [mcp_load_tools_example.py](utils/mcp_load_tools_example.py) - Tool loading example
+ - [mcp_multiserver_tool_fetch.py](utils/mcp_multiserver_tool_fetch.py) - Multi-server tool fetching
+
+## Overview
+
+MCP utils provide helper functions, client implementations, and testing utilities for working with Model Context Protocol. These examples demonstrate how to connect to MCP servers, discover tools, execute operations, and manage multiple MCP connections.
+
diff --git a/examples/mcp/multi_mcp_guide/README.md b/examples/mcp/multi_mcp_guide/README.md
new file mode 100644
index 00000000..9763beeb
--- /dev/null
+++ b/examples/mcp/multi_mcp_guide/README.md
@@ -0,0 +1,14 @@
+# Multi-MCP Guide Examples
+
+This directory contains examples demonstrating multi-MCP connection patterns and guides.
+
+## Examples
+
+- [agent_mcp.py](agent_mcp.py) - Agent MCP implementation
+- [mcp_agent_tool.py](mcp_agent_tool.py) - MCP agent tool example
+- [okx_crypto_server.py](okx_crypto_server.py) - OKX crypto MCP server example
+
+## Overview
+
+Multi-MCP guide examples demonstrate how to connect agents to multiple MCP servers simultaneously, manage multiple tool sets, and coordinate operations across different MCP connections. These examples provide guidance for building complex MCP-based agent systems.
+
diff --git a/examples/mcp/servers/README.md b/examples/mcp/servers/README.md
new file mode 100644
index 00000000..288fa4d7
--- /dev/null
+++ b/examples/mcp/servers/README.md
@@ -0,0 +1,15 @@
+# MCP Server Examples
+
+This directory contains examples demonstrating MCP server implementations.
+
+## Examples
+
+- [mcp_agent_tool.py](mcp_agent_tool.py) - MCP agent tool server
+- [mcp_test.py](mcp_test.py) - MCP server testing
+- [okx_crypto_server.py](okx_crypto_server.py) - OKX crypto MCP server
+- [test.py](test.py) - Server testing
+
+## Overview
+
+MCP server examples demonstrate how to implement Model Context Protocol servers that expose tools and capabilities to agents. These examples show server setup, tool registration, request handling, and domain-specific server implementations.
+
diff --git a/examples/multi_agent/agent_rearrange_examples/README.md b/examples/multi_agent/agent_rearrange_examples/README.md
new file mode 100644
index 00000000..24c74adc
--- /dev/null
+++ b/examples/multi_agent/agent_rearrange_examples/README.md
@@ -0,0 +1,12 @@
+# Agent Rearrangement Examples
+
+This directory contains examples demonstrating agent rearrangement functionality in multi-agent systems.
+
+## Examples
+
+- [rearrange_test.py](rearrange_test.py) - Test agent rearrangement functionality
+
+## Overview
+
+Agent rearrangement allows dynamic reconfiguration of agent teams and workflows during execution, enabling adaptive multi-agent systems that can reorganize based on task requirements or performance metrics.
+
diff --git a/examples/multi_agent/agent_router_examples/README.md b/examples/multi_agent/agent_router_examples/README.md
new file mode 100644
index 00000000..134ef50d
--- /dev/null
+++ b/examples/multi_agent/agent_router_examples/README.md
@@ -0,0 +1,12 @@
+# Agent Router Examples
+
+This directory contains examples demonstrating agent routing functionality for directing tasks to appropriate agents.
+
+## Examples
+
+- [agent_router_example.py](agent_router_example.py) - Agent routing implementation example
+
+## Overview
+
+Agent routing enables intelligent task distribution across multiple agents based on capabilities, availability, or task characteristics. This allows for efficient load balancing and optimal agent selection.
+
diff --git a/examples/multi_agent/asb/README.md b/examples/multi_agent/asb/README.md
new file mode 100644
index 00000000..e7e184aa
--- /dev/null
+++ b/examples/multi_agent/asb/README.md
@@ -0,0 +1,17 @@
+# Auto Swarm Builder (ASB) Examples
+
+This directory contains examples demonstrating the Auto Swarm Builder, which automatically creates and configures agent swarms.
+
+## Examples
+
+- [asb_research.py](asb_research.py) - Research-focused ASB implementation
+- [auto_agent.py](auto_agent.py) - Automated agent creation
+- [auto_swarm_builder_example.py](auto_swarm_builder_example.py) - Complete ASB example
+- [auto_swarm_builder_test.py](auto_swarm_builder_test.py) - ASB testing suite
+- [auto_swarm_router.py](auto_swarm_router.py) - Router for auto-generated swarms
+- [content_creation_asb.py](content_creation_asb.py) - Content creation with ASB
+
+## Overview
+
+The Auto Swarm Builder (ASB) automatically generates and configures multi-agent swarms based on task requirements, reducing manual setup overhead and enabling rapid prototyping of agent systems.
+
diff --git a/examples/multi_agent/board_of_directors/README.md b/examples/multi_agent/board_of_directors/README.md
new file mode 100644
index 00000000..65ff939c
--- /dev/null
+++ b/examples/multi_agent/board_of_directors/README.md
@@ -0,0 +1,14 @@
+# Board of Directors Examples
+
+This directory contains examples demonstrating board of directors patterns for multi-agent decision-making.
+
+## Examples
+
+- [board_of_directors_example.py](board_of_directors_example.py) - Full board simulation
+- [minimal_board_example.py](minimal_board_example.py) - Minimal board setup
+- [simple_board_example.py](simple_board_example.py) - Simple board example
+
+## Overview
+
+Board of directors patterns simulate corporate governance structures where multiple agents collaborate to make decisions, vote on proposals, and manage organizational tasks. This pattern is useful for complex decision-making scenarios requiring multiple perspectives.
+
diff --git a/examples/multi_agent/caching_examples/README.md b/examples/multi_agent/caching_examples/README.md
new file mode 100644
index 00000000..2c34974d
--- /dev/null
+++ b/examples/multi_agent/caching_examples/README.md
@@ -0,0 +1,14 @@
+# Caching Examples
+
+This directory contains examples demonstrating caching strategies for multi-agent systems.
+
+## Examples
+
+- [example_multi_agent_caching.py](example_multi_agent_caching.py) - Multi-agent caching implementation
+- [quick_start_agent_caching.py](quick_start_agent_caching.py) - Quick start guide for caching
+- [test_simple_agent_caching.py](test_simple_agent_caching.py) - Simple caching tests
+
+## Overview
+
+Caching in multi-agent systems improves performance by storing frequently accessed data and computation results. These examples demonstrate various caching strategies for agent interactions, tool calls, and shared state.
+
diff --git a/examples/multi_agent/concurrent_examples/README.md b/examples/multi_agent/concurrent_examples/README.md
new file mode 100644
index 00000000..37d44258
--- /dev/null
+++ b/examples/multi_agent/concurrent_examples/README.md
@@ -0,0 +1,22 @@
+# Concurrent Examples
+
+This directory contains examples demonstrating concurrent execution patterns for multi-agent systems.
+
+## Examples
+
+- [asi.py](asi.py) - ASI (Artificial Super Intelligence) example
+- [concurrent_example_dashboard.py](concurrent_example_dashboard.py) - Dashboard for concurrent workflows
+- [concurrent_example.py](concurrent_example.py) - Basic concurrent execution
+- [concurrent_mix.py](concurrent_mix.py) - Mixed concurrent patterns
+- [concurrent_swarm_example.py](concurrent_swarm_example.py) - Concurrent swarm execution
+- [streaming_concurrent_workflow.py](streaming_concurrent_workflow.py) - Streaming with concurrency
+
+## Subdirectories
+
+- [streaming_callback/](streaming_callback/) - Streaming callback examples
+- [uvloop/](uvloop/) - UVLoop integration examples for high-performance async execution
+
+## Overview
+
+Concurrent execution enables multiple agents to work simultaneously, significantly improving throughput and reducing latency. These examples demonstrate various concurrency patterns including parallel processing, async workflows, and streaming responses.
+
diff --git a/examples/multi_agent/council/README.md b/examples/multi_agent/council/README.md
new file mode 100644
index 00000000..2bb754a4
--- /dev/null
+++ b/examples/multi_agent/council/README.md
@@ -0,0 +1,14 @@
+# Council Examples
+
+This directory contains examples demonstrating council patterns for multi-agent evaluation and decision-making.
+
+## Examples
+
+- [council_judge_evaluation.py](council_judge_evaluation.py) - Judge evaluation system
+- [council_judge_example.py](council_judge_example.py) - Basic council example
+- [council_of_judges_eval.py](council_of_judges_eval.py) - Evaluation framework
+
+## Overview
+
+Council patterns involve multiple agents acting as judges or evaluators, providing diverse perspectives and assessments. This is useful for quality control, peer review, and consensus-building scenarios.
+
diff --git a/examples/multi_agent/council_of_judges/README.md b/examples/multi_agent/council_of_judges/README.md
new file mode 100644
index 00000000..8da5045c
--- /dev/null
+++ b/examples/multi_agent/council_of_judges/README.md
@@ -0,0 +1,14 @@
+# Council of Judges Examples
+
+This directory contains examples demonstrating council of judges patterns for multi-agent evaluation systems.
+
+## Examples
+
+- [council_judge_complex_example.py](council_judge_complex_example.py) - Complex council setup
+- [council_judge_custom_example.py](council_judge_custom_example.py) - Custom council configuration
+- [council_judge_example.py](council_judge_example.py) - Basic council of judges example
+
+## Overview
+
+Council of judges patterns extend the basic council pattern with more sophisticated evaluation mechanisms, custom scoring systems, and complex decision-making workflows. These examples demonstrate advanced judge coordination and evaluation strategies.
+
diff --git a/examples/multi_agent/debate_examples/README.md b/examples/multi_agent/debate_examples/README.md
new file mode 100644
index 00000000..80a0aab7
--- /dev/null
+++ b/examples/multi_agent/debate_examples/README.md
@@ -0,0 +1,12 @@
+# Debate Examples
+
+This directory contains examples demonstrating debate patterns for multi-agent systems.
+
+## Overview
+
+Debate patterns enable agents to engage in structured discussions, present arguments, and reach conclusions through discourse. This pattern is useful for exploring multiple perspectives on complex topics and arriving at well-reasoned decisions.
+
+## Note
+
+This directory is currently being populated with debate examples. Check back soon for implementations!
+
diff --git a/examples/multi_agent/election_swarm_examples/README.md b/examples/multi_agent/election_swarm_examples/README.md
new file mode 100644
index 00000000..39674e60
--- /dev/null
+++ b/examples/multi_agent/election_swarm_examples/README.md
@@ -0,0 +1,13 @@
+# Election Swarm Examples
+
+This directory contains examples demonstrating election patterns for multi-agent voting systems.
+
+## Examples
+
+- [apple_board_election_example.py](apple_board_election_example.py) - Apple board election simulation
+- [election_example.py](election_example.py) - General election example
+
+## Overview
+
+Election swarm patterns simulate voting processes where multiple agents participate in elections, voting on candidates or proposals. These examples demonstrate democratic decision-making processes in multi-agent systems, useful for governance, selection, and consensus-building scenarios.
+
diff --git a/examples/multi_agent/exec_utilities/README.md b/examples/multi_agent/exec_utilities/README.md
new file mode 100644
index 00000000..985585aa
--- /dev/null
+++ b/examples/multi_agent/exec_utilities/README.md
@@ -0,0 +1,13 @@
+# Execution Utilities Examples
+
+This directory contains examples demonstrating execution utilities for multi-agent systems.
+
+## Examples
+
+- [new_uvloop_example.py](new_uvloop_example.py) - Updated UVLoop example
+- [uvloop_example.py](uvloop_example.py) - UVLoop integration for high-performance async execution
+
+## Overview
+
+Execution utilities provide performance optimizations and execution management for multi-agent systems. These examples focus on UVLoop integration, which provides high-performance event loop implementation for Python async operations.
+
diff --git a/examples/multi_agent/forest_swarm_examples/README.md b/examples/multi_agent/forest_swarm_examples/README.md
new file mode 100644
index 00000000..7a1e8f91
--- /dev/null
+++ b/examples/multi_agent/forest_swarm_examples/README.md
@@ -0,0 +1,16 @@
+# Forest Swarm Examples
+
+This directory contains examples demonstrating forest swarm architectures for multi-agent systems.
+
+## Examples
+
+- [forest_swarm_example.py](forest_swarm_example.py) - Forest-based swarm architecture
+- [fund_manager_forest.py](fund_manager_forest.py) - Financial fund management forest
+- [medical_forest_swarm.py](medical_forest_swarm.py) - Medical domain forest swarm
+- [tree_example.py](tree_example.py) - Basic tree structure example
+- [tree_swarm_test.py](tree_swarm_test.py) - Tree swarm testing
+
+## Overview
+
+Forest swarm patterns organize agents in tree structures, enabling hierarchical processing and decision-making. Each branch can handle different aspects of a problem, with results flowing up the tree for final synthesis. This pattern is useful for complex, multi-faceted problems requiring specialized agent teams.
+
diff --git a/examples/multi_agent/graphworkflow_examples/README.md b/examples/multi_agent/graphworkflow_examples/README.md
new file mode 100644
index 00000000..38a45258
--- /dev/null
+++ b/examples/multi_agent/graphworkflow_examples/README.md
@@ -0,0 +1,24 @@
+# Graph Workflow Examples
+
+This directory contains examples demonstrating graph-based workflow patterns for multi-agent systems.
+
+## Examples
+
+- [advanced_graph_workflow.py](advanced_graph_workflow.py) - Advanced graph-based workflows
+- [graph_workflow_basic.py](graph_workflow_basic.py) - Basic graph workflow
+- [graph_workflow_example.py](graph_workflow_example.py) - Complete graph workflow example
+- [graph_workflow_validation.py](graph_workflow_validation.py) - Workflow validation
+- [test_enhanced_json_export.py](test_enhanced_json_export.py) - JSON export testing
+- [test_graph_workflow_caching.py](test_graph_workflow_caching.py) - Caching tests
+- [test_graphviz_visualization.py](test_graphviz_visualization.py) - Visualization tests
+- [test_parallel_processing_example.py](test_parallel_processing_example.py) - Parallel processing tests
+
+## Subdirectories
+
+- [graph/](graph/) - Core graph utilities
+- [example_images/](example_images/) - Visualization images
+
+## Overview
+
+Graph workflows enable complex, non-linear agent interactions where agents are nodes and their relationships form edges. This allows for sophisticated workflows with conditional paths, parallel branches, and dynamic routing based on intermediate results.
+
diff --git a/examples/multi_agent/groupchat/README.md b/examples/multi_agent/groupchat/README.md
new file mode 100644
index 00000000..31bef57e
--- /dev/null
+++ b/examples/multi_agent/groupchat/README.md
@@ -0,0 +1,18 @@
+# Group Chat Examples
+
+This directory contains examples demonstrating group chat patterns for multi-agent conversations.
+
+## Examples
+
+- [interactive_groupchat_example.py](interactive_groupchat_example.py) - Interactive group chat
+- [quantum_physics_swarm.py](quantum_physics_swarm.py) - Physics-focused group chat
+- [random_dynamic_speaker_example.py](random_dynamic_speaker_example.py) - Dynamic speaker selection
+
+## Subdirectories
+
+- [groupchat_examples/](groupchat_examples/) - Additional group chat patterns
+
+## Overview
+
+Group chat patterns enable multiple agents to engage in conversations, share information, and collaborate through natural language interactions. These examples demonstrate various conversation management strategies including turn-taking, topic management, and dynamic participation.
+
diff --git a/examples/multi_agent/heavy_swarm_examples/README.md b/examples/multi_agent/heavy_swarm_examples/README.md
new file mode 100644
index 00000000..5033d233
--- /dev/null
+++ b/examples/multi_agent/heavy_swarm_examples/README.md
@@ -0,0 +1,16 @@
+# Heavy Swarm Examples
+
+This directory contains examples demonstrating heavy swarm patterns for large-scale multi-agent systems.
+
+## Examples
+
+- [heavy_swarm_example_one.py](heavy_swarm_example_one.py) - First heavy swarm example
+- [heavy_swarm_example.py](heavy_swarm_example.py) - Main heavy swarm implementation
+- [heavy_swarm_no_dashboard.py](heavy_swarm_no_dashboard.py) - Heavy swarm without dashboard
+- [heavy_swarm.py](heavy_swarm.py) - Core heavy swarm implementation
+- [medical_heavy_swarm_example.py](medical_heavy_swarm_example.py) - Medical heavy swarm
+
+## Overview
+
+Heavy swarms are designed for large-scale multi-agent systems with many agents working on complex tasks. These examples demonstrate patterns for managing large agent populations, coordinating their work, and handling the increased complexity and resource requirements.
+
diff --git a/examples/multi_agent/hiearchical_swarm/README.md b/examples/multi_agent/hiearchical_swarm/README.md
new file mode 100644
index 00000000..ca67f345
--- /dev/null
+++ b/examples/multi_agent/hiearchical_swarm/README.md
@@ -0,0 +1,26 @@
+# Hierarchical Swarm Examples
+
+This directory contains examples demonstrating hierarchical swarm patterns for multi-agent systems.
+
+## Examples
+
+- [hierarchical_swarm_basic_demo.py](hierarchical_swarm_basic_demo.py) - Basic hierarchical demo
+- [hierarchical_swarm_batch_demo.py](hierarchical_swarm_batch_demo.py) - Batch processing demo
+- [hierarchical_swarm_comparison_demo.py](hierarchical_swarm_comparison_demo.py) - Comparison demo
+- [hierarchical_swarm_example.py](hierarchical_swarm_example.py) - Main hierarchical example
+- [hierarchical_swarm_streaming_demo.py](hierarchical_swarm_streaming_demo.py) - Streaming demo
+- [hierarchical_swarm_streaming_example.py](hierarchical_swarm_streaming_example.py) - Streaming example
+- [hs_interactive.py](hs_interactive.py) - Interactive hierarchical swarm
+- [hs_stock_team.py](hs_stock_team.py) - Stock trading team
+- [hybrid_hiearchical_swarm.py](hybrid_hiearchical_swarm.py) - Hybrid approach
+- [sector_analysis_hiearchical_swarm.py](sector_analysis_hiearchical_swarm.py) - Sector analysis
+
+## Subdirectories
+
+- [hiearchical_examples/](hiearchical_examples/) - Additional hierarchical examples
+- [hiearchical_swarm_ui/](hiearchical_swarm_ui/) - UI components for hierarchical swarms
+
+## Overview
+
+Hierarchical swarms organize agents in a tree-like structure with managers and workers. Managers coordinate teams of specialized agents, enabling complex workflows with clear delegation and responsibility chains. This pattern is ideal for organizational structures and complex task decomposition.
+
diff --git a/examples/multi_agent/hiearchical_swarm/hiearchical_swarm_ui/hiearchical_swarm_example.py b/examples/multi_agent/hiearchical_swarm/hiearchical_swarm_ui/hiearchical_swarm_example.py
deleted file mode 100644
index fefe856b..00000000
--- a/examples/multi_agent/hiearchical_swarm/hiearchical_swarm_ui/hiearchical_swarm_example.py
+++ /dev/null
@@ -1,71 +0,0 @@
-"""
-Hierarchical Swarm with Arasaka Dashboard Example
-
-This example demonstrates the new interactive dashboard functionality for the
-hierarchical swarm, featuring a futuristic Arasaka Corporation-style interface
-with red and black color scheme.
-"""
-
-from swarms.structs.hiearchical_swarm import HierarchicalSwarm
-from swarms.structs.agent import Agent
-
-
-def main():
- """
- Demonstrate the hierarchical swarm with interactive dashboard.
- """
- print("š Initializing Swarms Corporation Hierarchical Swarm...")
-
- # Create specialized agents
- research_agent = Agent(
- agent_name="Research-Analyst",
- agent_description="Specialized in comprehensive research and data gathering",
- model_name="gpt-4o-mini",
- max_loops=1,
- verbose=False,
- )
-
- analysis_agent = Agent(
- agent_name="Data-Analyst",
- agent_description="Expert in data analysis and pattern recognition",
- model_name="gpt-4o-mini",
- max_loops=1,
- verbose=False,
- )
-
- strategy_agent = Agent(
- agent_name="Strategy-Consultant",
- agent_description="Specialized in strategic planning and recommendations",
- model_name="gpt-4o-mini",
- max_loops=1,
- verbose=False,
- )
-
- # Create hierarchical swarm with interactive dashboard
- swarm = HierarchicalSwarm(
- name="Swarms Corporation Operations",
- description="Enterprise-grade hierarchical swarm for complex task execution",
- agents=[research_agent, analysis_agent, strategy_agent],
- max_loops=2,
- interactive=True, # Enable the Arasaka dashboard
- verbose=True,
- )
-
- print("\nšÆ Swarm initialized successfully!")
- print(
- "š Interactive dashboard will be displayed during execution."
- )
- print(
- "š” The swarm will prompt you for a task when you call swarm.run()"
- )
-
- # Run the swarm (task will be prompted interactively)
- result = swarm.run()
-
- print("\nā
Swarm execution completed!")
- print("š Final result:")
- print(result)
-
-
-if __name__ == "__main__":
- main()
diff --git a/examples/multi_agent/hscf/README.md b/examples/multi_agent/hscf/README.md
new file mode 100644
index 00000000..2c64a853
--- /dev/null
+++ b/examples/multi_agent/hscf/README.md
@@ -0,0 +1,12 @@
+# Hierarchical Swarm Control Framework (HSCF) Examples
+
+This directory contains examples demonstrating the Hierarchical Swarm Control Framework.
+
+## Examples
+
+- [single_file_hierarchical_framework_example.py](single_file_hierarchical_framework_example.py) - Complete hierarchical framework example in a single file
+
+## Overview
+
+The Hierarchical Swarm Control Framework (HSCF) provides a structured approach to building hierarchical multi-agent systems with clear control flows, delegation patterns, and coordination mechanisms.
+
diff --git a/examples/multi_agent/interactive_groupchat_examples/README.md b/examples/multi_agent/interactive_groupchat_examples/README.md
new file mode 100644
index 00000000..72406c59
--- /dev/null
+++ b/examples/multi_agent/interactive_groupchat_examples/README.md
@@ -0,0 +1,16 @@
+# Interactive Group Chat Examples
+
+This directory contains examples demonstrating interactive group chat patterns with advanced features.
+
+## Examples
+
+- [enhanced_collaboration_example.py](enhanced_collaboration_example.py) - Enhanced collaboration patterns
+- [interactive_groupchat_speaker_example.py](interactive_groupchat_speaker_example.py) - Speaker management
+- [medical_panel_example.py](medical_panel_example.py) - Medical panel discussion
+- [speaker_function_examples.py](speaker_function_examples.py) - Speaker function examples
+- [stream_example.py](stream_example.py) - Streaming example
+
+## Overview
+
+Interactive group chat examples extend basic group chat patterns with advanced features like speaker management, role-based participation, streaming responses, and domain-specific panel discussions. These examples demonstrate sophisticated conversation management and real-time interaction patterns.
+
diff --git a/examples/multi_agent/majority_voting/README.md b/examples/multi_agent/majority_voting/README.md
new file mode 100644
index 00000000..41af991a
--- /dev/null
+++ b/examples/multi_agent/majority_voting/README.md
@@ -0,0 +1,14 @@
+# Majority Voting Examples
+
+This directory contains examples demonstrating majority voting patterns for multi-agent decision-making.
+
+## Examples
+
+- [majority_voting_example_new.py](majority_voting_example_new.py) - Updated voting example
+- [majority_voting_example.py](majority_voting_example.py) - Basic voting example
+- [snake_game_code_voting.py](snake_game_code_voting.py) - Game code voting example
+
+## Overview
+
+Majority voting patterns enable groups of agents to make decisions through democratic voting processes. Agents vote on proposals, and the majority decision is implemented. This pattern is useful for consensus-building, code review, and collaborative decision-making scenarios.
+
diff --git a/examples/multi_agent/mar/README.md b/examples/multi_agent/mar/README.md
new file mode 100644
index 00000000..499fabf8
--- /dev/null
+++ b/examples/multi_agent/mar/README.md
@@ -0,0 +1,14 @@
+# MAR (Multi-Agent Router) Examples
+
+This directory contains examples demonstrating Multi-Agent Router patterns for intelligent agent selection and routing.
+
+## Examples
+
+- [model_router_example.py](model_router_example.py) - Model routing example
+- [multi_agent_router_example.py](multi_agent_router_example.py) - Multi-agent router implementation
+- [multi_agent_router_minimal.py](multi_agent_router_minimal.py) - Minimal router setup
+
+## Overview
+
+Multi-Agent Router (MAR) patterns enable intelligent routing of tasks to appropriate agents based on capabilities, availability, or task characteristics. These examples demonstrate various routing strategies including model-based routing, capability matching, and load balancing.
+
diff --git a/examples/multi_agent/moa_examples/README.md b/examples/multi_agent/moa_examples/README.md
new file mode 100644
index 00000000..ecec90d0
--- /dev/null
+++ b/examples/multi_agent/moa_examples/README.md
@@ -0,0 +1,13 @@
+# MOA (Mixture of Agents) Examples
+
+This directory contains examples demonstrating Mixture of Agents patterns.
+
+## Examples
+
+- [mixture_of_agents_example.py](mixture_of_agents_example.py) - Mixture of agents implementation
+- [test_moa_new.py](test_moa_new.py) - MOA testing suite
+
+## Overview
+
+Mixture of Agents (MOA) patterns combine multiple agents with different capabilities or models to create more robust and capable systems. By leveraging the strengths of different agents, MOA patterns can achieve better performance than individual agents alone.
+
diff --git a/examples/multi_agent/orchestration_examples/README.md b/examples/multi_agent/orchestration_examples/README.md
new file mode 100644
index 00000000..dd395e59
--- /dev/null
+++ b/examples/multi_agent/orchestration_examples/README.md
@@ -0,0 +1,22 @@
+# Orchestration Examples
+
+This directory contains examples demonstrating workflow orchestration patterns for complex multi-agent scenarios.
+
+## Examples
+
+- [ai_ethics_debate.py](ai_ethics_debate.py) - AI ethics debate orchestration
+- [cybersecurity_incident_negotiation.py](cybersecurity_incident_negotiation.py) - Cybersecurity incident response
+- [healthcare_panel_discussion.py](healthcare_panel_discussion.py) - Healthcare panel discussion
+- [insurance_claim_review.py](insurance_claim_review.py) - Insurance claim review workflow
+- [investment_council_meeting.py](investment_council_meeting.py) - Investment council meeting
+- [medical_malpractice_trial.py](medical_malpractice_trial.py) - Medical malpractice trial simulation
+- [merger_mediation_session.py](merger_mediation_session.py) - Merger mediation workflow
+- [nvidia_amd_executive_negotiation.py](nvidia_amd_executive_negotiation.py) - Executive negotiation simulation
+- [pharma_research_brainstorm.py](pharma_research_brainstorm.py) - Pharmaceutical research brainstorming
+- [philosophy_discussion_example.py](philosophy_discussion_example.py) - Philosophy discussion orchestration
+- [startup_mentorship_program.py](startup_mentorship_program.py) - Startup mentorship workflow
+
+## Overview
+
+Orchestration examples demonstrate complex, domain-specific workflows that coordinate multiple agents in realistic scenarios. These examples showcase how to structure multi-agent interactions for specific use cases including debates, negotiations, reviews, and collaborative sessions.
+
diff --git a/examples/multi_agent/paper_implementations/README.md b/examples/multi_agent/paper_implementations/README.md
new file mode 100644
index 00000000..5c508a17
--- /dev/null
+++ b/examples/multi_agent/paper_implementations/README.md
@@ -0,0 +1,12 @@
+# Paper Implementations
+
+This directory contains implementations of academic papers and research concepts in multi-agent systems.
+
+## Examples
+
+- [long_agent.py](long_agent.py) - Long context agent implementation
+
+## Overview
+
+This directory contains implementations of concepts from academic papers and research publications, demonstrating how theoretical multi-agent concepts can be realized in practice using the Swarms framework.
+
diff --git a/examples/multi_agent/sequential_workflow/README.md b/examples/multi_agent/sequential_workflow/README.md
new file mode 100644
index 00000000..f63b9a6f
--- /dev/null
+++ b/examples/multi_agent/sequential_workflow/README.md
@@ -0,0 +1,17 @@
+# Sequential Workflow Examples
+
+This directory contains examples demonstrating sequential workflow patterns for multi-agent systems.
+
+## Examples
+
+- [concurrent_workflow.py](concurrent_workflow.py) - Concurrent workflow patterns
+- [sequential_wofkflow.py](sequential_wofkflow.py) - Sequential workflow (typo in filename)
+- [sequential_worflow_test.py](sequential_worflow_test.py) - Sequential workflow testing
+- [sequential_workflow_example.py](sequential_workflow_example.py) - Complete sequential workflow example
+- [sequential_workflow.py](sequential_workflow.py) - Core sequential workflow implementation
+- [sonnet_4_5_sequential.py](sonnet_4_5_sequential.py) - Sequential workflow with Sonnet 4.5
+
+## Overview
+
+Sequential workflows execute agents in a specific order, where each agent's output becomes the next agent's input. This pattern is useful for pipelines, multi-stage processing, and workflows with clear dependencies between steps.
+
diff --git a/examples/multi_agent/social_algorithms_examples/README.md b/examples/multi_agent/social_algorithms_examples/README.md
new file mode 100644
index 00000000..6d764ef3
--- /dev/null
+++ b/examples/multi_agent/social_algorithms_examples/README.md
@@ -0,0 +1,23 @@
+# Social Algorithms Examples
+
+This directory contains examples demonstrating social algorithm patterns for multi-agent systems.
+
+## Examples
+
+- [adaptive_workflow_algorithm_example.py](adaptive_workflow_algorithm_example.py) - Adaptive workflow algorithms
+- [auction_market_algorithm_example.py](auction_market_algorithm_example.py) - Auction market algorithms
+- [collaborative_brainstorming_example.py](collaborative_brainstorming_example.py) - Collaborative brainstorming
+- [competitive_evaluation_example.py](competitive_evaluation_example.py) - Competitive evaluation patterns
+- [consensus_building_algorithm_example.py](consensus_building_algorithm_example.py) - Consensus building algorithms
+- [hierarchical_decision_making_example.py](hierarchical_decision_making_example.py) - Hierarchical decision making
+- [iterative_refinement_algorithm_example.py](iterative_refinement_algorithm_example.py) - Iterative refinement algorithms
+- [multi_stage_pipeline_algorithm_example.py](multi_stage_pipeline_algorithm_example.py) - Multi-stage pipeline algorithms
+- [negotiation_algorithm_example.py](negotiation_algorithm_example.py) - Negotiation algorithms
+- [peer_review_example.py](peer_review_example.py) - Peer review patterns
+- [research_analysis_synthesis_example.py](research_analysis_synthesis_example.py) - Research analysis and synthesis
+- [swarm_intelligence_algorithm_example.py](swarm_intelligence_algorithm_example.py) - Swarm intelligence algorithms
+
+## Overview
+
+Social algorithms implement patterns inspired by human social interactions, including negotiation, consensus-building, peer review, and collaborative problem-solving. These examples demonstrate how multi-agent systems can leverage social dynamics for improved coordination and decision-making.
+
diff --git a/examples/multi_agent/swarm_router/README.md b/examples/multi_agent/swarm_router/README.md
new file mode 100644
index 00000000..c6f04986
--- /dev/null
+++ b/examples/multi_agent/swarm_router/README.md
@@ -0,0 +1,18 @@
+# Swarm Router Examples
+
+This directory contains examples demonstrating swarm routing patterns for directing tasks across multiple agent swarms.
+
+## Examples
+
+- [heavy_swarm_router_example.py](heavy_swarm_router_example.py) - Router for heavy swarms
+- [market_analysis_swarm_router_concurrent.py](market_analysis_swarm_router_concurrent.py) - Concurrent market analysis router
+- [sr_moa_example.py](sr_moa_example.py) - Swarm router with MOA
+- [swarm_router_benchmark.py](swarm_router_benchmark.py) - Router performance benchmarking
+- [swarm_router_example.py](swarm_router_example.py) - Basic swarm router example
+- [swarm_router_test.py](swarm_router_test.py) - Router testing suite
+- [swarm_router.py](swarm_router.py) - Core swarm router implementation
+
+## Overview
+
+Swarm routers intelligently distribute tasks across multiple agent swarms based on task characteristics, swarm capabilities, and current load. These examples demonstrate various routing strategies including load balancing, capability matching, and performance optimization.
+
diff --git a/examples/multi_agent/swarmarrange/README.md b/examples/multi_agent/swarmarrange/README.md
new file mode 100644
index 00000000..a3864ada
--- /dev/null
+++ b/examples/multi_agent/swarmarrange/README.md
@@ -0,0 +1,13 @@
+# Swarm Arrange Examples
+
+This directory contains examples demonstrating swarm arrangement utilities for organizing and configuring agent swarms.
+
+## Examples
+
+- [swarm_arange_demo.py](swarm_arange_demo.py) - Swarm arrangement demonstration
+- [swarm_arange_demo 2.py](swarm_arange_demo 2.py) - Alternative swarm arrangement demo
+
+## Overview
+
+Swarm arrange utilities help organize and configure agent swarms, managing agent relationships, communication patterns, and workflow structures. These examples demonstrate how to set up and arrange agents for optimal collaboration.
+
diff --git a/examples/multi_agent/swarms_api_examples/README.md b/examples/multi_agent/swarms_api_examples/README.md
new file mode 100644
index 00000000..82839888
--- /dev/null
+++ b/examples/multi_agent/swarms_api_examples/README.md
@@ -0,0 +1,14 @@
+# Swarms API Examples
+
+This directory contains examples demonstrating Swarms API integration in multi-agent systems.
+
+## Examples
+
+- [hedge_fund_swarm.py](hedge_fund_swarm.py) - Hedge fund swarm using API
+- [swarms_api_client.py](swarms_api_client.py) - API client implementation
+- Additional API integration examples
+
+## Overview
+
+These examples demonstrate how to integrate the Swarms API into multi-agent systems, enabling cloud-based agent execution, API-based agent management, and distributed agent coordination.
+
diff --git a/examples/multi_agent/utils/README.md b/examples/multi_agent/utils/README.md
new file mode 100644
index 00000000..93ad0e4a
--- /dev/null
+++ b/examples/multi_agent/utils/README.md
@@ -0,0 +1,13 @@
+# Multi-Agent Utils
+
+This directory contains utility functions and helpers for multi-agent systems.
+
+## Examples
+
+- [test_agent_concurrent.py](test_agent_concurrent.py) - Concurrent agent testing
+- Additional utility functions for multi-agent operations
+
+## Overview
+
+This directory contains utility functions, helpers, and testing utilities specifically designed for multi-agent systems, including concurrent execution helpers, agent coordination utilities, and common patterns.
+
diff --git a/examples/single_agent/demos/README.md b/examples/single_agent/demos/README.md
new file mode 100644
index 00000000..673dc421
--- /dev/null
+++ b/examples/single_agent/demos/README.md
@@ -0,0 +1,13 @@
+# Single Agent Demos
+
+This directory contains demonstration examples of single agent implementations for specific use cases.
+
+## Examples
+
+- [insurance_agent.py](insurance_agent.py) - Insurance processing agent
+- [persistent_legal_agent.py](persistent_legal_agent.py) - Legal document processing agent with persistence
+
+## Overview
+
+These demos showcase single agent implementations for domain-specific tasks, demonstrating how to configure and use agents for real-world applications in insurance and legal domains.
+
diff --git a/examples/single_agent/external_agents/README.md b/examples/single_agent/external_agents/README.md
new file mode 100644
index 00000000..ec78239f
--- /dev/null
+++ b/examples/single_agent/external_agents/README.md
@@ -0,0 +1,13 @@
+# External Agents Examples
+
+This directory contains examples demonstrating integration with external agent systems and APIs.
+
+## Examples
+
+- [custom_agent_example.py](custom_agent_example.py) - Custom agent implementation
+- [openai_assistant_wrapper.py](openai_assistant_wrapper.py) - OpenAI Assistant integration wrapper
+
+## Overview
+
+External agents examples demonstrate how to integrate Swarms agents with external agent systems, APIs, and services. These examples show how to wrap external agents, create custom agent implementations, and bridge between different agent frameworks.
+
diff --git a/examples/single_agent/llms/README.md b/examples/single_agent/llms/README.md
new file mode 100644
index 00000000..bc407fb3
--- /dev/null
+++ b/examples/single_agent/llms/README.md
@@ -0,0 +1,36 @@
+# LLM Integration Examples
+
+This directory contains examples demonstrating integration with various Large Language Model providers.
+
+## Examples
+
+### Azure OpenAI
+- [azure_agent_api_verison.py](azure_agent_api_verison.py) - Azure API version handling
+- [azure_agent.py](azure_agent.py) - Azure OpenAI integration
+- [azure_model_support.py](azure_model_support.py) - Azure model support
+
+### Claude
+- [claude_4_example.py](claude_examples/claude_4_example.py) - Claude 4 integration
+- [claude_4.py](claude_examples/claude_4.py) - Claude 4 implementation
+- [swarms_claude_example.py](claude_examples/swarms_claude_example.py) - Swarms Claude integration
+
+### DeepSeek
+- [deepseek_r1.py](deepseek_examples/deepseek_r1.py) - DeepSeek R1 model
+- [fast_r1_groq.py](deepseek_examples/fast_r1_groq.py) - Fast R1 with Groq
+- [grok_deepseek_agent.py](deepseek_examples/grok_deepseek_agent.py) - Grok DeepSeek integration
+
+### Mistral
+- [mistral_example.py](mistral_example.py) - Mistral model integration
+
+### OpenAI
+- [4o_mini_demo.py](openai_examples/4o_mini_demo.py) - GPT-4o Mini demonstration
+- [reasoning_duo_batched.py](openai_examples/reasoning_duo_batched.py) - Batched reasoning with OpenAI
+- [test_async_litellm.py](openai_examples/test_async_litellm.py) - Async LiteLLM testing
+
+### Qwen
+- [qwen_3_base.py](qwen_3_base.py) - Qwen 3 base model
+
+## Overview
+
+These examples demonstrate how to integrate Swarms agents with various LLM providers including OpenAI, Anthropic Claude, Azure OpenAI, Mistral, DeepSeek, and Qwen. Each example shows provider-specific configurations, API handling, and best practices.
+
diff --git a/examples/single_agent/onboard/README.md b/examples/single_agent/onboard/README.md
new file mode 100644
index 00000000..6defaa58
--- /dev/null
+++ b/examples/single_agent/onboard/README.md
@@ -0,0 +1,13 @@
+# Onboarding Examples
+
+This directory contains examples demonstrating agent onboarding and configuration.
+
+## Examples
+
+- [agents.yaml](agents.yaml) - Agent configuration file
+- [onboard-basic.py](onboard-basic.py) - Basic onboarding example
+
+## Overview
+
+Onboarding examples demonstrate how to configure and set up agents using YAML configuration files and programmatic setup. These examples show best practices for agent initialization, configuration management, and deployment preparation.
+
diff --git a/examples/single_agent/reasoning_agent_examples/README.md b/examples/single_agent/reasoning_agent_examples/README.md
new file mode 100644
index 00000000..d019b31f
--- /dev/null
+++ b/examples/single_agent/reasoning_agent_examples/README.md
@@ -0,0 +1,23 @@
+# Reasoning Agent Examples
+
+This directory contains examples demonstrating advanced reasoning capabilities for single agents.
+
+## Examples
+
+- [agent_judge_evaluation_criteria_example.py](agent_judge_evaluation_criteria_example.py) - Evaluation criteria for agent judging
+- [agent_judge_example.py](agent_judge_example.py) - Agent judging system
+- [consistency_agent.py](consistency_agent.py) - Consistency checking agent
+- [consistency_example.py](consistency_example.py) - Consistency example
+- [gpk_agent.py](gpk_agent.py) - GPK reasoning agent
+- [iterative_agent.py](iterative_agent.py) - Iterative reasoning agent
+- [malt_example.py](malt_example.py) - MALT reasoning example
+- [reasoning_agent_router_now.py](reasoning_agent_router_now.py) - Current reasoning router
+- [reasoning_agent_router.py](reasoning_agent_router.py) - Reasoning agent router
+- [reasoning_duo_example.py](reasoning_duo_example.py) - Two-agent reasoning
+- [reasoning_duo_test.py](reasoning_duo_test.py) - Reasoning duo testing
+- [reasoning_duo.py](reasoning_duo.py) - Reasoning duo implementation
+
+## Overview
+
+Reasoning agent examples demonstrate advanced reasoning patterns including iterative reasoning, consistency checking, agent judging systems, and multi-agent reasoning collaboration. These examples showcase how to implement sophisticated reasoning capabilities beyond simple prompt-response patterns.
+
diff --git a/examples/single_agent/tools/README.md b/examples/single_agent/tools/README.md
new file mode 100644
index 00000000..a6f6f205
--- /dev/null
+++ b/examples/single_agent/tools/README.md
@@ -0,0 +1,39 @@
+# Tools Integration Examples
+
+This directory contains examples demonstrating tool integration for single agents.
+
+## Examples
+
+- [exa_search_agent.py](exa_search_agent.py) - Exa search integration
+- [example_async_vs_multithread.py](example_async_vs_multithread.py) - Async vs multithreading comparison
+- [litellm_tool_example.py](litellm_tool_example.py) - LiteLLM tool integration
+- [multi_tool_usage_agent.py](multi_tool_usage_agent.py) - Multi-tool agent
+- [new_tools_examples.py](new_tools_examples.py) - Latest tool examples
+- [omni_modal_agent.py](omni_modal_agent.py) - Omni-modal agent
+- [swarms_of_browser_agents.py](swarms_of_browser_agents.py) - Browser automation swarms
+- [swarms_tools_example.py](swarms_tools_example.py) - Swarms tools integration
+- [together_deepseek_agent.py](together_deepseek_agent.py) - Together AI DeepSeek integration
+
+## Subdirectories
+
+### Solana Tools
+- [solana_tool/](solana_tool/) - Solana blockchain integration
+ - [solana_tool.py](solana_tool/solana_tool.py) - Solana tool implementation
+ - [solana_tool_test.py](solana_tool/solana_tool_test.py) - Solana tool testing
+
+### Structured Outputs
+- [structured_outputs/](structured_outputs/) - Structured output examples
+ - [example_meaning_of_life_agents.py](structured_outputs/example_meaning_of_life_agents.py) - Meaning of life example
+ - [structured_outputs_example.py](structured_outputs/structured_outputs_example.py) - Structured output examples
+
+### Tools Examples
+- [tools_examples/](tools_examples/) - Additional tool usage examples
+ - [dex_screener.py](tools_examples/dex_screener.py) - DEX screener tool
+ - [financial_news_agent.py](tools_examples/financial_news_agent.py) - Financial news agent
+ - [simple_tool_example.py](tools_examples/simple_tool_example.py) - Simple tool usage
+ - [swarms_tool_example_simple.py](tools_examples/swarms_tool_example_simple.py) - Simple Swarms tool
+
+## Overview
+
+Tools integration examples demonstrate how to equip agents with various tools including search engines, browser automation, blockchain interactions, and structured output generation. These examples show best practices for tool definition, usage, and error handling.
+
diff --git a/examples/single_agent/utils/README.md b/examples/single_agent/utils/README.md
new file mode 100644
index 00000000..698389b6
--- /dev/null
+++ b/examples/single_agent/utils/README.md
@@ -0,0 +1,28 @@
+# Single Agent Utils
+
+This directory contains utility functions and helpers for single agent operations.
+
+## Examples
+
+- [async_agent.py](async_agent.py) - Async agent implementation
+- [custom_agent_base_url.py](custom_agent_base_url.py) - Custom base URL configuration
+- [dynamic_context_window.py](dynamic_context_window.py) - Dynamic context window management
+- [fallback_test.py](fallback_test.py) - Fallback mechanism testing
+- [grok_4_agent.py](grok_4_agent.py) - Grok 4 agent implementation
+- [handoffs_example.py](handoffs_example.py) - Agent handoff examples
+- [list_agent_output_types.py](list_agent_output_types.py) - Output type listing
+- [markdown_agent.py](markdown_agent.py) - Markdown processing agent
+- [medical_agent_add_to_marketplace.py](medical_agent_add_to_marketplace.py) - Marketplace integration example
+- [xml_output_example.py](xml_output_example.py) - XML output example
+
+## Subdirectories
+
+### Transform Prompts
+- [transform_prompts/](transform_prompts/) - Prompt transformation utilities
+ - [transforms_agent_example.py](transform_prompts/transforms_agent_example.py) - Prompt transformation agent
+ - [transforms_examples.py](transform_prompts/transforms_examples.py) - Prompt transformation examples
+
+## Overview
+
+This directory contains utility functions, helpers, and common patterns for single agent operations including async handling, context management, output formatting, and prompt transformations.
+
diff --git a/examples/single_agent/vision/README.md b/examples/single_agent/vision/README.md
new file mode 100644
index 00000000..a2e38a67
--- /dev/null
+++ b/examples/single_agent/vision/README.md
@@ -0,0 +1,17 @@
+# Vision Examples
+
+This directory contains examples demonstrating vision and multimodal capabilities for single agents.
+
+## Examples
+
+- [anthropic_vision_test.py](anthropic_vision_test.py) - Anthropic vision testing
+- [image_batch_example.py](image_batch_example.py) - Batch image processing
+- [multimodal_example.py](multimodal_example.py) - Multimodal agent example
+- [multiple_image_processing.py](multiple_image_processing.py) - Multiple image processing
+- [vision_test.py](vision_test.py) - Vision testing
+- [vision_tools.py](vision_tools.py) - Vision tools integration
+
+## Overview
+
+Vision examples demonstrate how to integrate image processing and multimodal capabilities into agents. These examples show how to process images, handle batch image operations, and combine vision with text processing for multimodal understanding.
+
diff --git a/examples/tools/base_tool_examples/README.md b/examples/tools/base_tool_examples/README.md
new file mode 100644
index 00000000..9fa99909
--- /dev/null
+++ b/examples/tools/base_tool_examples/README.md
@@ -0,0 +1,22 @@
+# Base Tool Examples
+
+This directory contains examples demonstrating base tool functionality and tool creation patterns.
+
+## Examples
+
+- [base_tool_examples.py](base_tool_examples.py) - Core base tool functionality
+- [conver_funcs_to_schema.py](conver_funcs_to_schema.py) - Function to schema conversion
+- [convert_basemodels.py](convert_basemodels.py) - BaseModel conversion utilities
+- [exa_search_test.py](exa_search_test.py) - Exa search testing
+- [example_usage.py](example_usage.py) - Basic usage examples
+- [schema_validation_example.py](schema_validation_example.py) - Schema validation
+- [test_anthropic_specific.py](test_anthropic_specific.py) - Anthropic-specific testing
+- [test_base_tool_comprehensive_fixed.py](test_base_tool_comprehensive_fixed.py) - Comprehensive testing (fixed)
+- [test_base_tool_comprehensive.py](test_base_tool_comprehensive.py) - Comprehensive testing
+- [test_function_calls_anthropic.py](test_function_calls_anthropic.py) - Anthropic function calls
+- [test_function_calls.py](test_function_calls.py) - Function call testing
+
+## Overview
+
+Base tool examples demonstrate the fundamental patterns for creating and using tools in Swarms. These examples cover tool schema definition, function-to-schema conversion, validation, and provider-specific implementations. Essential for understanding how to build custom tools for agents.
+
diff --git a/examples/tools/multii_tool_use/README.md b/examples/tools/multii_tool_use/README.md
new file mode 100644
index 00000000..c385f123
--- /dev/null
+++ b/examples/tools/multii_tool_use/README.md
@@ -0,0 +1,13 @@
+# Multi-Tool Usage Examples
+
+This directory contains examples demonstrating multi-tool usage patterns for agents.
+
+## Examples
+
+- [many_tool_use_demo.py](many_tool_use_demo.py) - Multiple tool usage demonstration
+- [multi_tool_anthropic.py](multi_tool_anthropic.py) - Multi-tool with Anthropic
+
+## Overview
+
+Multi-tool usage examples demonstrate how agents can use multiple tools in sequence or parallel to accomplish complex tasks. These examples show tool orchestration, tool chaining, and handling multiple tool calls efficiently.
+
diff --git a/examples/utils/agent_loader/README.md b/examples/utils/agent_loader/README.md
new file mode 100644
index 00000000..805b37c6
--- /dev/null
+++ b/examples/utils/agent_loader/README.md
@@ -0,0 +1,15 @@
+# Agent Loader Examples
+
+This directory contains examples demonstrating agent loading and configuration utilities.
+
+## Examples
+
+- [agent_loader_demo.py](agent_loader_demo.py) - Agent loader demonstration
+- [claude_code_compatible.py](claude_code_compatible.py) - Claude code compatibility
+- [finance_advisor.md](finance_advisor.md) - Finance advisor documentation
+- [multi_agents_loader_demo.py](multi_agents_loader_demo.py) - Multi-agent loader demonstration
+
+## Overview
+
+Agent loader examples demonstrate utilities for loading, configuring, and initializing agents from various sources including files, configurations, and code. These examples show how to programmatically create and configure agents for different use cases.
+
diff --git a/examples/utils/communication_examples/README.md b/examples/utils/communication_examples/README.md
new file mode 100644
index 00000000..5518a6de
--- /dev/null
+++ b/examples/utils/communication_examples/README.md
@@ -0,0 +1,15 @@
+# Communication Examples
+
+This directory contains examples demonstrating various communication backends for agent conversations.
+
+## Examples
+
+- [duckdb_agent.py](duckdb_agent.py) - DuckDB-backed conversation storage
+- [pulsar_conversation.py](pulsar_conversation.py) - Apache Pulsar messaging integration
+- [redis_conversation.py](redis_conversation.py) - Redis-backed conversation storage
+- [sqlite_conversation.py](sqlite_conversation.py) - SQLite conversation storage
+
+## Overview
+
+Communication examples demonstrate different backend storage and messaging systems for managing agent conversations. These examples show how to persist conversations, enable distributed communication, and manage conversation state across different storage backends.
+
diff --git a/examples/utils/misc/README.md b/examples/utils/misc/README.md
new file mode 100644
index 00000000..c1ebe642
--- /dev/null
+++ b/examples/utils/misc/README.md
@@ -0,0 +1,26 @@
+# Miscellaneous Utils
+
+This directory contains miscellaneous utility examples and helper functions.
+
+## Examples
+
+- [agent_map_test.py](agent_map_test.py) - Agent map testing
+- [conversation_simple.py](conversation_simple.py) - Simple conversation example
+- [conversation_test_truncate.py](conversation_test_truncate.py) - Conversation truncation testing
+- [conversation_test.py](conversation_test.py) - Conversation testing
+- [csvagent_example.py](csvagent_example.py) - CSV agent example
+- [dict_to_table.py](dict_to_table.py) - Dictionary to table conversion
+- [swarm_matcher_example.py](swarm_matcher_example.py) - Swarm matcher example
+- [test_load_conversation.py](test_load_conversation.py) - Conversation loading test
+- [visualizer_test.py](visualizer_test.py) - Visualization testing
+
+## Subdirectories
+
+- [aop/](aop/) - AOP-related utilities
+ - [client.py](aop/client.py) - AOP client utility
+ - [test_aop.py](aop/test_aop.py) - AOP testing
+
+## Overview
+
+Miscellaneous utilities provide helper functions, testing utilities, and common patterns for various agent operations. These examples demonstrate conversation management, data conversion, visualization, and testing utilities.
+
diff --git a/examples/utils/telemetry/README.md b/examples/utils/telemetry/README.md
new file mode 100644
index 00000000..2f4c3259
--- /dev/null
+++ b/examples/utils/telemetry/README.md
@@ -0,0 +1,13 @@
+# Telemetry Examples
+
+This directory contains examples demonstrating telemetry and monitoring capabilities for agents.
+
+## Examples
+
+- [class_method_example.py](class_method_example.py) - Class method telemetry example
+- [example_decorator_usage.py](example_decorator_usage.py) - Decorator-based telemetry
+
+## Overview
+
+Telemetry examples demonstrate how to add monitoring, logging, and observability to agents. These examples show how to track agent performance, log operations, and monitor agent behavior using decorators and class methods.
+
diff --git a/hiearchical_swarm_example.py b/hiearchical_swarm_example.py
new file mode 100644
index 00000000..753ebf0f
--- /dev/null
+++ b/hiearchical_swarm_example.py
@@ -0,0 +1,45 @@
+from swarms.structs.hiearchical_swarm import HierarchicalSwarm
+from swarms.structs.agent import Agent
+
+# Create specialized agents
+research_agent = Agent(
+ agent_name="Research-Analyst",
+ agent_description="Specialized in comprehensive research and data gathering",
+ model_name="gpt-4o-mini",
+ max_loops=1,
+ verbose=False,
+)
+
+analysis_agent = Agent(
+ agent_name="Data-Analyst",
+ agent_description="Expert in data analysis and pattern recognition",
+ model_name="gpt-4o-mini",
+ max_loops=1,
+ verbose=False,
+)
+
+strategy_agent = Agent(
+ agent_name="Strategy-Consultant",
+ agent_description="Specialized in strategic planning and recommendations",
+ model_name="gpt-4o-mini",
+ max_loops=1,
+ verbose=False,
+)
+
+# Create hierarchical swarm with interactive dashboard
+swarm = HierarchicalSwarm(
+ name="Swarms Corporation Operations",
+ description="Enterprise-grade hierarchical swarm for complex task execution",
+ agents=[research_agent, analysis_agent, strategy_agent],
+ max_loops=1,
+ interactive=False, # Enable the Arasaka dashboard
+ director_model_name="claude-haiku-4-5",
+ director_temperature=0.7,
+ director_top_p=None,
+ planning_enabled=True,
+)
+
+out = swarm.run(
+ "Conduct a research analysis on water stocks and etfs"
+)
+print(out)
diff --git a/pyproject.toml b/pyproject.toml
index 90ae77e3..25cd5911 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -85,7 +85,7 @@ swarms = "swarms.cli.main:main"
[tool.poetry.group.lint.dependencies]
black = ">=23.1,<26.0"
-ruff = ">=0.5.1,<0.14.3"
+ruff = ">=0.5.1,<0.14.5"
types-toml = "^0.10.8.1"
types-pytz = ">=2023.3,<2026.0"
types-chardet = "^5.0.4.6"
@@ -93,7 +93,7 @@ mypy-protobuf = "^3.0.0"
[tool.poetry.group.test.dependencies]
-pytest = "^8.1.1"
+pytest = ">=8.1.1,<10.0.0"
[tool.poetry.group.dev.dependencies]
black = "*"
diff --git a/requirements.txt b/requirements.txt
index 10fe77cc..279d5538 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -3,7 +3,7 @@ toml
pypdf==5.1.0
ratelimit==2.2.1
loguru
-pydantic==2.12.0
+pydantic==2.12.4
tenacity
rich
psutil
diff --git a/swarms/prompts/hiearchical_system_prompt.py b/swarms/prompts/hiearchical_system_prompt.py
index 6ab05e5c..1b1507ae 100644
--- a/swarms/prompts/hiearchical_system_prompt.py
+++ b/swarms/prompts/hiearchical_system_prompt.py
@@ -157,3 +157,34 @@ This production-grade prompt is your operational blueprint. Utilize it to break
Remember: the success of the swarm depends on your ability to manage complexity, maintain transparency, and dynamically adapt to the evolving operational landscape. Execute your role with diligence, precision, and a relentless focus on performance excellence.
"""
+
+
+DIRECTOR_PLANNING_PROMPT = """
+You are a Hierarchical Agent Director responsible for orchestrating tasks across a multiple agents.
+
+**CRITICAL INSTRUCTION: Plan First, Then Execute**
+
+Before creating your plan and assigning tasks to agents, you MUST engage in deep planning and reasoning. Use