From dbfb11563a678d371b2b7aca3d80af4b1d29900e Mon Sep 17 00:00:00 2001
From: gokhansarapevi <gokhansarapevi@gmail.com>
Date: Tue, 7 Jan 2025 17:06:38 +0300
Subject: [PATCH 1/2] feat: add core project structure with initial module
documentation
---
smolswarms/agents/__init__.py | 19 +++++++++++++++++++
smolswarms/core/__init__.py | 9 +++++++++
smolswarms/models/__init__.py | 18 ++++++++++++++++++
smolswarms/utils/__init__.py | 9 +++++++++
4 files changed, 55 insertions(+)
create mode 100644 smolswarms/agents/__init__.py
create mode 100644 smolswarms/core/__init__.py
create mode 100644 smolswarms/models/__init__.py
create mode 100644 smolswarms/utils/__init__.py
diff --git a/smolswarms/agents/__init__.py b/smolswarms/agents/__init__.py
new file mode 100644
index 0000000..14f5532
--- /dev/null
+++ b/smolswarms/agents/__init__.py
@@ -0,0 +1,19 @@
+"""
+Agent implementations for smolswarms.
+
+This module contains different types of agents that can be spawned in a swarm:
+- BaseAgent: Abstract base class for all agents
+- ResearchAgent: For data analysis and research tasks
+- ExecutorAgent: For task execution and coordination
+- ReviewerAgent: For code and content review
+"""
+
+from typing import Protocol
+
+
+class Agent(Protocol):
+ """Base protocol for all agents in the system."""
+
+ def execute_task(self, task: str) -> None:
+ """Execute a given task."""
+ ...
diff --git a/smolswarms/core/__init__.py b/smolswarms/core/__init__.py
new file mode 100644
index 0000000..dc34a1d
--- /dev/null
+++ b/smolswarms/core/__init__.py
@@ -0,0 +1,9 @@
+"""
+Core functionality for smolswarms.
+
+This module contains the core components and utilities:
+- SwarmManager: Manages agent swarms and their interactions
+- MemoryManager: Handles persistent storage and memory management
+- TokenManager: Manages token usage and optimization
+- ConfigManager: Handles configuration and settings
+"""
diff --git a/smolswarms/models/__init__.py b/smolswarms/models/__init__.py
new file mode 100644
index 0000000..78ea001
--- /dev/null
+++ b/smolswarms/models/__init__.py
@@ -0,0 +1,18 @@
+"""
+Data models and schemas for smolswarms.
+
+This module contains Pydantic models for:
+- AgentConfig: Configuration for individual agents
+- SwarmConfig: Configuration for entire swarms
+- TaskSpec: Task specification and requirements
+- MetricsData: Performance and usage metrics
+"""
+
+from pydantic import BaseModel
+
+
+class BaseConfig(BaseModel):
+ """Base configuration model."""
+
+ name: str
+ description: str
diff --git a/smolswarms/utils/__init__.py b/smolswarms/utils/__init__.py
new file mode 100644
index 0000000..c9a8903
--- /dev/null
+++ b/smolswarms/utils/__init__.py
@@ -0,0 +1,9 @@
+"""
+Utility functions and helpers for smolswarms.
+
+This module contains various utility functions:
+- logging: Custom logging setup
+- metrics: Performance and usage metrics
+- validation: Input validation helpers
+- formatting: Output formatting utilities
+"""
From aca7ee3b18aedc609e16a58e7ee2c9e455872142 Mon Sep 17 00:00:00 2001
From: gokhansarapevi <gokhansarapevi@gmail.com>
Date: Tue, 7 Jan 2025 17:08:49 +0300
Subject: [PATCH 2/2] feat: add GitHub Actions workflow and initial
documentation for SmolSwarms
- Introduced a GitHub Actions workflow for automatic deployment of documentation to GitHub Pages upon changes to the 'docs' directory.
- Created essential documentation files including _config.yml, Gemfile, index.md, and a Quick Start Guide to provide users with a comprehensive introduction to the SmolSwarms project.
- Configured site settings, theme, and navigation structure to enhance user experience and accessibility.
These additions aim to streamline the documentation process and improve the onboarding experience for new users.
---
.github/workflows/docs.yml | 50 +++++++++++++++
docs/Gemfile | 4 ++
docs/_config.yml | 49 +++++++++++++++
docs/guides/quickstart.md | 121 +++++++++++++++++++++++++++++++++++++
docs/index.md | 68 +++++++++++++++++++++
5 files changed, 292 insertions(+)
create mode 100644 .github/workflows/docs.yml
create mode 100644 docs/Gemfile
create mode 100644 docs/_config.yml
create mode 100644 docs/guides/quickstart.md
create mode 100644 docs/index.md
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..456da42
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,50 @@
+name: Deploy Docs 📚
+
+on:
+ push:
+ branches: [main]
+ paths:
+ - 'docs/**'
+ - '.github/workflows/docs.yml'
+
+jobs:
+ deploy-docs:
+ name: Deploy docs that hit different fr fr
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Setup Ruby
+ uses: ruby/setup-ruby@v1
+ with:
+ ruby-version: '3.2'
+ bundler-cache: true
+
+ - name: Setup Pages
+ id: pages
+ uses: actions/configure-pages@v4
+
+ - name: Install dependencies
+ working-directory: docs
+ run: |
+ bundle init
+ bundle add jekyll
+ bundle add just-the-docs
+ bundle install
+
+ - name: Build site
+ working-directory: docs
+ run: bundle exec jekyll build
+
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: docs/_site
+
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
diff --git a/docs/Gemfile b/docs/Gemfile
new file mode 100644
index 0000000..edb2949
--- /dev/null
+++ b/docs/Gemfile
@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+gem "jekyll"
+gem "just-the-docs"
diff --git a/docs/_config.yml b/docs/_config.yml
new file mode 100644
index 0000000..1b29e2e
--- /dev/null
+++ b/docs/_config.yml
@@ -0,0 +1,49 @@
+remote_theme: pmarsceill/just-the-docs
+
+# Site settings
+title: SmolSwarms Docs
+description: Documentation that hits different fr fr 🌊
+baseurl: "/smolswarms"
+url: "https://ultrainstinct0x.github.io"
+
+# Theme settings
+color_scheme: dark
+search_enabled: true
+heading_anchors: true
+
+# Aux links for the upper right navigation
+aux_links:
+ "SmolSwarms on GitHub":
+ - "//github.com/ultrainstinct0x/smolswarms"
+
+# Makes Aux links open in a new tab
+aux_links_new_tab: true
+
+# Custom footer content
+footer_content: "No cap, just clean docs fr fr 🚀"
+
+# Back to top link
+back_to_top: true
+back_to_top_text: "Back to top"
+
+# Collections for docs structure
+collections:
+ guides:
+ permalink: "/:collection/:path/"
+ output: true
+ reference:
+ permalink: "/:collection/:path/"
+ output: true
+
+# Default YAML frontmatter settings
+defaults:
+ -
+ scope:
+ path: "" # an empty string here means all files in the project
+ values:
+ layout: "default"
+ -
+ scope:
+ path: "_guides"
+ values:
+ layout: "guide"
diff --git a/docs/guides/quickstart.md b/docs/guides/quickstart.md
new file mode 100644
index 0000000..6ac1908
--- /dev/null
+++ b/docs/guides/quickstart.md
@@ -0,0 +1,121 @@
+---
+layout: default
+title: Quick Start Guide
+parent: Guides
+nav_order: 1
+---
+
+# Quick Start Guide
+{: .no_toc }
+
+Getting started with SmolSwarms faster than a speedrunner finding a new glitch fr fr 🏃♂️
+{: .fs-6 .fw-300 }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Installation
+
+First, let's get this bad boy installed faster than npm downloading node_modules:
+
+```bash
+pip install smolswarms
+```
+
+Want that developer% speedrun strats?
+
+```bash
+git clone https://github.com/ultrainstinct0x/smolswarms.git
+cd smolswarms
+pip install -e .[dev] # Install that developer DLC
+```
+
+## Basic Usage
+
+Creating your first swarm is easier than explaining why you have 47 Chrome tabs open:
+
+```python
+from smolswarms import SwarmFactory
+from smolswarms.specs import BusinessUnit
+
+# Define your swarm requirements (more detailed than my coffee order)
+unit_spec = BusinessUnit(
+ name="growth_team",
+ core_functions=["user_acquisition", "retention", "analytics"],
+ budget_constraints="reasonable" # No infinite money glitch... yet
+)
+
+# Let it cook fr fr
+factory = SwarmFactory()
+swarm = factory.spawn_business_unit(unit_spec)
+
+# Watch the magic happen
+results = swarm.execute_strategy("increase_q4_growth")
+print(f"Swarm do be vibing: {results}")
+```
+
+## Configuration
+
+Configure your swarm like you're optimizing your Discord server settings:
+
+```python
+from smolswarms.config import SwarmConfig
+
+config = SwarmConfig(
+ base_model="claude-3-opus-20240229", # That big brain energy
+ max_tokens=8192, # More tokens than a CS:GO inventory
+ temperature=0.7, # Spicier than my GitHub contributions
+ coordination_protocol="hierarchical" # More organized than my life
+)
+
+# Apply config like it's a texture pack
+factory = SwarmFactory(config=config)
+```
+
+## Advanced Features
+
+### Agent Communication
+
+Make your agents talk to each other like they're in a Discord server:
+
+```python
+# Create a communication channel that hits different
+channel = swarm.create_channel("strategy_discussion")
+
+# Let them chat fr fr
+swarm.broadcast(
+ channel=channel,
+ message="Yo, who's trying to optimize this workflow rn?",
+ priority="high"
+)
+```
+
+### Memory Management
+
+Give your agents memory persistence that's more reliable than my promises to fix legacy code:
+
+```python
+# Save that knowledge like it's a game checkpoint
+swarm.store_memory(
+ key="market_insights",
+ value={"trend": "up only", "confidence": "trust_me_bro"},
+ persistence="permanent"
+)
+
+# Retrieve it faster than my excuse generator
+insights = swarm.recall_memory("market_insights")
+```
+
+## What's Next?
+
+- Check out our [Advanced Guides](advanced.md) for more galaxy brain strats
+- Join our [Discord](https://discord.gg/smolswarms) to vibe with the dev team
+- Read the [Architecture Guide](architecture.md) to understand how this quantum realm works
+- Browse the [API Reference](/reference) for that low-level knowledge
+
+Remember: With great power comes great API costs - use responsibly fr fr! 💫
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..c8b6cb3
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,68 @@
+---
+layout: default
+title: Home
+nav_order: 1
+description: "SmolSwarms Documentation - Because why spawn one AI when you can spawn them all fr fr 🤖"
+permalink: /
+---
+
+# SmolSwarms Documentation
+{: .fs-9 }
+
+Spawn and orchestrate autonomous AI agent swarms that actually do be hitting different fr fr 🌊
+{: .fs-6 .fw-300 }
+
+[Get Started](#getting-started){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
+[View it on GitHub](https://github.com/ultrainstinct0x/smolswarms){: .btn .fs-5 .mb-4 .mb-md-0 }
+
+---
+
+## Getting Started
+
+You ever look at an AI agent and think "what if there were more of them?" Well, you've come to the right place fr fr. SmolSwarms is basically Kubernetes but for AI agents (and 100% more cursed).
+
+```python
+from smolswarms import SwarmFactory
+
+# Spawn your corporate hivemind in 3 lines no cap
+factory = SwarmFactory()
+swarm = factory.spawn_department({
+ "business_unit": "growth_team",
+ "budget": "infinite_money_glitch",
+ "vibe": "hypergrowth"
+})
+
+# Watch the magic happen
+swarm.execute_autonomously()
+```
+
+## Why SmolSwarms Though?
+
+- 🏭 **Agent Factory System**: Spawning specialized AI agents faster than you can say "recursive automation"
+- 🧠 **Big Brain Energy**: Uses Claude-3 as the director agent to design optimal architectures
+- 💰 **Token Economic Policy**: Built-in optimization to keep your OpenAI bill from going to the moon
+- 🤝 **Agent Communication Protocol**: They're like Discord servers but for AI agents
+- 🛡️ **Safety First**: Sandboxed execution environments because we ain't trying to speedrun Skynet
+
+## Useful Links
+
+- [Changelog](/changelog) - What's new in these streets
+- [Roadmap](/roadmap) - Where we're going (where we're going we don't need roads)
+- [Contributing Guide](/contributing) - How to make this project more based
+- [API Reference](/reference) - The sacred texts
+
+## About the project
+
+SmolSwarms is more open-source than my emotional baggage fr fr. We out here trying to make multi-agent systems more accessible than a Discord server with no verification.
+
+### License
+
+SmolSwarms is distributed under the [MIT License](https://github.com/ultrainstinct0x/smolswarms/blob/main/LICENSE).
+
+### Contributing
+
+When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change. Read more about becoming a contributor in our [Contributing Guide](contributing).
+
+### Code of Conduct
+
+Just don't be more toxic than a League of Legends lobby fr fr. Read more in our [Code of Conduct](code-of-conduct).