Heretek Swarm - The Collective

Version: 0.1.0
Framework: Python 3.11+
Status: PRODUCTION READY
Last Updated: 2026-04-18

Installation

Python Package (pip)

pip install heretek-swarm

The package provides the core heretek_swarm library installed under src/heretek_swarm/.

Frontend (npm)

cd dashboard/frontend
npm install
npm run dev

Docker Compose (Local Development)

docker-compose up -d

Starts PostgreSQL, Redis, Qdrant, the API server, and the frontend dashboard.

Package Structure

heretek-swarm/
├── config/               # Configuration files
│   ├── litellm_config.yaml
│   ├── otel-collector-config.yaml
│   └── config.example.json
├── src/heretek_swarm/      # Python package (pip-installable)
│   ├── actors/            # 23 agent implementations
│   ├── api/               # FastAPI endpoints
│   ├── consciousness/     # Consciousness metrics (GWT, IIT, FEP)
│   ├── consensus/         # MAKER protocol implementation
│   ├── gateway/           # NATS event mesh
│   ├── memory/            # Multi-tier memory system
│   ├── security/          # Zero-trust validation
│   └── state/             # PostgreSQL persistence
│
└── dashboard/frontend/    # React dashboard (npm-managed)
    ├── src/               # React/Vite application
    ├── public/
    └── package.json

Quick Start

Prerequisites

One-Shot Deployment

./deploy.sh

The script checks prerequisites, creates .env, pulls images, starts services, and runs migrations.

Manual Start

# Start infrastructure
docker-compose up -d postgres redis qdrant

# Start API
uvicorn src.heretek_swarm.api.main:app --reload

# Start frontend
cd dashboard/frontend && npm run dev

Script Commands

Troubleshooting

docker-compose ps          # Check service status
docker-compose logs api    # View error logs
docker-compose restart api # Restart a specific service

Kubernetes

For production Kubernetes deployment, see k8s/README.md.

Infrastructure (External Services)

The system depends on the following external services:

All services are defined in docker-compose.yml. For local development without Docker, set DATABASE_URL, REDIS_URL, and QDRANT_HOST environment variables pointing to your infrastructure hosts.

🏛️ The 23 Agents

┌─────────────────────────────────────────────────────────────────┐
│                    THE COLLECTIVE (23 AGENT TYPES)              │
├─────────────────────────────────────────────────────────────────┤
│ TIER 1: CORE TRIAD (4)     │ TIER 4: SAFETY (3)               │
│ ├── Steward (Orchestrator) │ ├── Sentinel (Safety Guardian)   │
│ ├── Alpha (Deep Analysis)  │ ├── Sentinel-Prime (Security)    │
│ ├── Beta (Validation)      │ └── Arbiter (Conflict Resolution)│
│ └── Charlie (Challenge)    │                                   │
│                            │ TIER 5: COORDINATION (4)         │
│ TIER 2: SUPPORT (5)        │ ├── Coordinator (Multi-Agent)    │
│ ├── Historian (Memory)     │ ├── Nexus (External Integration) │
│ ├── Metis (Strategy)       │ ├── Catalyst (Change Mgmt)       │
│ ├── Empath (Emotional IQ)  │ └── Chronos (Scheduling)         │
│ └── Perceiver (Sensory)    │                                   │
│                            │ TIER 6: ENHANCEMENT (3)          │
│ TIER 3: EXPLORATION (4)    │ ├── Prism (Multi-Perspective)    │
│ ├── Explorer (Discovery)   │ ├── Habit-Forge (Optimization)   │
│ ├── Examiner (QA)          │ └── Perceiver+ (Advanced)        │
│ └── Coder (Implementation)│                                   │
└─────────────────────────────────────────────────────────────────┘

System Architecture

Components

Frontend Dashboard

The React-based dashboard provides:

• Agent Management: Deploy and monitor agents
• Consciousness Metrics: Real-time consciousness visualizations
• Workflow Builder: Visual workflow design with React Flow
• Settings: LLM providers, embedding models, system config

Technology Stack: React 18.2+, Vite 5.0+, @xyflow/react 12.0+, Zustand, Tailwind CSS 3.4+

Configuration

Documentation

The Prime Directive

Build a self-governing swarm of 23 specialized AI agents that operate independently 24/7, make collective decisions through consensus, adapt and learn from experience, and exhibit emergent collective intelligence.

🦞 The thought that never ends.

License: Apache 2.0

Last Updated: 2026-04-18