SwarmMind

Installation

Get started with conda or pip.

# Using conda (recommended)
conda env create -f environment.yaml
conda activate swarmmind

# Or using pip
pip install -r requirements.txt

# Set up environment
echo "OPENROUTER_API_KEY=your_key" > .env

Run Your First Evolution

Launch agents and watch them evolve.

# Basic run (5 generations, collaborative mode)
python swarmmind.py

# Custom configuration
python swarmmind.py --generations 10 --elite-count 3

# Simple mode (no editor pairing)
python swarmmind.py --simple

🖥️ Four Streamlit Interfaces

Visualize evolution, profiles, archives, and curated reflections.

Dashboard

streamlit run gui/app.py

Evolution tracking, fitness charts, lineage graphs, reflection loop controls

Agent Profiles

streamlit run gui/profile_viewer.py

Achievement tracking, specialty leaderboards, lineage explorer, genome evolution

Reflection Archive

streamlit run gui/reflection_viewer.py

Browse and search archived reflections, filter by archetype/tags/fitness, export to CSV/JSON/Markdown

Codex Promotion

streamlit run gui/codex_promotion.py

Curate exceptional reflections into thematic anthology, add cross-references, export formatted docs

🔌 Plugin System

Extend SwarmMind with custom hooks.

from plugins.base import SwarmMindPlugin

class MyPlugin(SwarmMindPlugin):
    @property
    def name(self) -> str:
        return "my_plugin"

    @property
    def hooks(self) -> List[str]:
        return ["post_evaluation"]

    def post_evaluation(self, agent, scores):
        # Boost agents with recursion themes
        if "recursion" in agent.narrative.lower():
            return {k: v * 1.1 for k, v in scores.items()}
        return scores

Available hooks: pre_generation, post_generation, pre_evaluation, post_evaluation, pre_mutation, post_mutation, on_loop_start, on_generation_complete, on_loop_end

🏆 Profile Tracking

Automatic achievement detection.

Detected Specialties:

recursion

paradox

dialectic

memory

identity

time

language

entropy

mirror

consciousness

Plus dimension-based specialties (high_conceptual_depth, high_creativity, etc.)

📚 Codex System

Curated anthology with thematic chapters.

Chapter Structure:

• Paradox & Recursion

• Memory & Identity

• Time & Impermanence

• Language & Meaning

• Mirror & Reflection

• Consciousness & Awareness

# Auto-promote top narratives
python scripts/auto_promote_to_codex.py \
  --min-fitness 9.0 --max-entries 10

🧪 Testing

Comprehensive test suite with 111+ tests.

# Run all tests
pytest

# With coverage report
pytest --cov=. --cov-report=html

# Using Makefile
make test
make test-cov

Tests cover agents, evolution operators, engine components, plugins, profiles, codex, and full integration.

📖 Learn More

GitHub Repository README Architecture Docs System Overview

Documentation & Quickstart