Metadata-Version: 2.4
Name: heretek-swarm
Version: 0.1.0
Summary: Heretek Swarm v2.0 - Next-generation multi-agent system built on Swarms framework
Author-email: Heretek AI <engineering@heretek.ai>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: swarms>=5.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: redis>=5.0.0
Requires-Dist: qdrant-client>=1.7.0
Requires-Dist: opentelemetry-api>=1.22.0
Requires-Dist: opentelemetry-sdk>=1.22.0
Requires-Dist: opentelemetry-exporter-otlp>=1.22.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: tenacity>=8.2.0
Requires-Dist: circuitbreaker>=2.0.0
Requires-Dist: starlette>=0.27.0
Requires-Dist: uvicorn>=0.25.0
Requires-Dist: websockets>=12.0
Requires-Dist: mem0ai>=1.0.0
Requires-Dist: fastapi>=0.109.0
Requires-Dist: click>=8.1.0
Requires-Dist: prometheus-client>=0.19.0
Requires-Dist: nats-py>=2.0.0
Provides-Extra: core
Requires-Dist: swarms>=5.0.0; extra == "core"
Requires-Dist: pydantic>=2.0.0; extra == "core"
Requires-Dist: structlog>=24.1.0; extra == "core"
Requires-Dist: tenacity>=8.2.0; extra == "core"
Requires-Dist: circuitbreaker>=2.0.0; extra == "core"
Provides-Extra: agents
Requires-Dist: heretek-swarm[core]; extra == "agents"
Requires-Dist: starlette>=0.27.0; extra == "agents"
Requires-Dist: uvicorn>=0.25.0; extra == "agents"
Requires-Dist: websockets>=12.0; extra == "agents"
Requires-Dist: fastapi>=0.109.0; extra == "agents"
Requires-Dist: click>=8.1.0; extra == "agents"
Requires-Dist: httpx>=0.25.0; extra == "agents"
Requires-Dist: mem0ai>=1.0.0; extra == "agents"
Requires-Dist: redis>=5.0.0; extra == "agents"
Requires-Dist: qdrant-client>=1.7.0; extra == "agents"
Requires-Dist: opentelemetry-api>=1.22.0; extra == "agents"
Requires-Dist: opentelemetry-sdk>=1.22.0; extra == "agents"
Requires-Dist: opentelemetry-exporter-otlp>=1.22.0; extra == "agents"
Provides-Extra: full
Requires-Dist: heretek-swarm[agents]; extra == "full"
Requires-Dist: nats-server>=3.0.0; extra == "full"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.53b0; extra == "full"
Requires-Dist: opentelemetry-instrumentation-httpx>=0.53b0; extra == "full"
Provides-Extra: dev
Requires-Dist: heretek-swarm[full]; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.3.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.5.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Requires-Dist: pytest-env>=1.1.0; extra == "dev"
Requires-Dist: hypothesis>=6.98.0; extra == "dev"
Requires-Dist: faker>=24.0.0; extra == "dev"
Requires-Dist: coverage[toml]>=7.4.0; extra == "dev"
Requires-Dist: ruff>=0.2.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"
Requires-Dist: locust>=2.23.0; extra == "dev"
Requires-Dist: locust-plugins>=4.0.0; extra == "dev"
Requires-Dist: testcontainers>=3.7.0; extra == "dev"
Dynamic: license-file

# Heretek Swarm - The Collective

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

---

## Installation

### Python Package (pip)

```bash
pip install heretek-swarm
```

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

### Frontend (npm)

```bash
cd dashboard/frontend
npm install
npm run dev
```

### Docker Compose (Local Development)

```bash
docker-compose up -d
```

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

---

## Package Structure

```
heretek-swarm/
├── 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

| Requirement | Minimum |
|-------------|---------|
| **Docker** | 20.10+ |
| **Docker Compose** | 2.0+ |
| **Python** | 3.11+ |

### One-Shot Deployment

```bash
./deploy.sh
```

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

### Manual Start

```bash
# 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

| Command | Description |
|---------|-------------|
| `./deploy.sh` | Deploy all services |
| `./deploy.sh stop` | Stop all services |
| `./deploy.sh restart` | Restart all services |
| `./deploy.sh status` | Show service status |
| `./deploy.sh logs` | View live logs |
| `./deploy.sh clean` | Remove all containers and volumes |

### Troubleshooting

```bash
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`](k8s/README.md).

---

## Infrastructure (External Services)

The system depends on the following external services:

| Service | Default Port | Purpose |
|---------|--------------|---------|
| PostgreSQL | 5432 | State persistence, mem0 episodic memory |
| Redis | 6379 | Working memory, caching |
| Qdrant | 6333 | Semantic/vector memory storage |
| NATS | 4222 | Event mesh (A2A agent communication) |

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

| Component | Port | Notes |
|-----------|------|-------|
| FastAPI Server | 8000 | Python 3.11+ |
| React Dashboard | 3000 → 80 | Vite/React |
| PostgreSQL | 5432 | pgvector enabled |
| Redis | 6379 | redis:7-alpine |
| Qdrant | 6333 | Vector storage |

### 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

| Variable | Required | Description |
|----------|----------|-------------|
| `DATABASE_URL` | Yes | PostgreSQL connection string |
| `REDIS_URL` | Yes | Redis connection string |
| `QDRANT_HOST` | Yes | Qdrant host |
| `MINIMAX_API_KEY` | Yes | MiniMax API key |

---

## Documentation

| Document | Description |
|----------|-------------|
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | System architecture details |
| [`docs/API_ENDPOINTS.md`](docs/API_ENDPOINTS.md) | API reference |
| [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) | Deployment guide |
| [`docs/CONSCIOUSNESS_PLUGINS.md`](docs/CONSCIOUSNESS_PLUGINS.md) | Consciousness frameworks |
| [`docs/AGENTS.md`](docs/AGENTS.md) | Complete agent reference |
| [`PRIME_DIRECTIVE.md`](PRIME_DIRECTIVE.md) | Project vision and philosophy |
| [`dashboard/frontend/README.md`](dashboard/frontend/README.md) | Frontend dashboard docs |

---

## 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*
