dreambeesai-artbot

# 🐝 DreamBees Orchestration Engine

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Node](https://img.shields.io/badge/Node-v20+-green.svg)](https://nodejs.org/)
[![Discord](https://img.shields.io/badge/Discord-Hive-blue.svg?logo=discord&logoColor=white)](https://discord.com/invite/curMHRAN8y)
[![Inference Status](https://img.shields.io/badge/Inference-Modal_GPU-purple.svg)](https://modal.com)

---

### **Abstract**
DreamBees is a high-performance, distributed orchestration engine designed to bridge the gap between large-scale Discord communities and state-of-the-art Generative AI inference. Built on a cloud-native architecture of **Node.js**, **Google Firestore**, and **Modal**, DreamBees provides a deterministic environment for multi-modal image generation, surgical creative edits (Remixing), and a resilient financial economy—all while maintaining enterprise-grade safety through its multi-layered "Queen's Guard" moderation protocol.

---

## 🏛️ System Architecture

DreamBees operates as a centralized state-machine, delegating compute-heavy inference to serverless GPU clusters and preserving environmental state through atomic database transitions.

### Infrastructure Topology
```mermaid
graph TD
    User((👤 Discord User))
    DC[🐝 Discord API Gateway]
    Bot[🚀 DreamBees Orchestrator]
    FS[(🔥 Firestore State)]
    S3[(📦 Backblaze B2/S3)]
    Modal[🧠 Modal GPU Cluster]
    Hive[🛡️ Queen's Guard Security]

    User <--> DC
    DC <--> Bot
    Bot <--> FS
    Bot <--> Hive
    Bot --> Modal
    Modal --> Bot
    Bot --> S3
    S3 --> User
```

### Generation Lifecycle (Request Sequence)
The following sequence diagram illustrates the lifecycle of a high-fidelity generation request, emphasizing the synchronous validation and asynchronous asset persistence.

```mermaid
sequenceDiagram
    participant User as 👤 User
    participant DC as 🐝 DreamBees (Node.js)
    participant FB as 🔥 Firestore (State)
    participant Hive as 🛡️ Hive (Security)
    participant Modal as 🧠 Modal (Inference)
    participant B2 as 📦 B2/S3 (Storage)

    User->>DC: /dream {prompt}
    DC->>FB: Check Distributed Lock & Cooldown
    FB-->>DC: Permission Granted
    DC->>Hive: Queen's Guard Entropy Scan
    Hive-->>DC: Validation Success (Nectar Refined)
    DC->>FB: Wallet.debit(zaps, transactionID)
    FB-->>DC: Atomic Success
    
    DC->>Modal: Parallel Inference Request (Batch x4)
    Modal-->>DC: Image Buffer Stream
    DC->>B2: Asynchronous Asset Persistence
    B2-->>DC: Secure S3 Object URLs
    
    DC->>DC: Composition & Stitching (Sharp)
    DC->>B2: Final Grid Persistence
    B2-->>DC: Public Asset URL
    
    DC->>FB: commitHistory(meta_data)
    DC->>User: Render Interactive Embed + Evolution Controls
    
    DC->>FB: Release Mutex & Enforce Cooldown
```

---

## 🧪 Technical Pillars

### 1. Tiered Inference Orchestration
Integration with **Modal** allows for dynamic, serverless scaling of GPU-accelerated inference. DreamBees supports multiple latent diffusion models (SDXL, Flux, Illustrious) through unified API endpoints, ensuring rapid response times even during high-concurrency periods.

### 2. Deterministic "Zap" Economy
All financial transactions are governed by the **Zap Protocol**, which leverages Google Firestore's multi-document atomic transactions. This ensuring absolute financial integrity and prevents race conditions during high-volume generation cycles (e.g., simultaneous claims or multi-batch generations).

### 3. The Queen's Guard (Hive Security)
A multi-layered safety framework that performs:
- **Lexical Analysis**: Filtering sensitive tokens at the ingress layer.
- **Latent Safety**: Post-inference visual auditing.
- **Automated Abuse Backoff**: Dynamic restriction of malicious actors based on interaction frequency.

---

## 🚀 Deployment & Operations (Industrial Grade)

DreamBees is deployed as a hardened, immutable "Hive Node" on **Google Compute Engine (GCE)** using a professional-grade Unified CI/CD Pipeline.

### 📋 Prerequisites Checklist
Before deploying, ensure you have:
- [ ] A Google Cloud Project with Billing enabled.
- [ ] Required APIs enabled (`Compute`, `Cloud Build`, `Artifact Registry`).
- [ ] A service account with `Cloud Build Editor` and `Compute Admin` roles.
- [ ] A populated `.env` file based on `.env.example`.

### 🏁 Quick Start
1. **Initialize Cloud Resources**:
   See the **[Infrastructure Setup Guide](./docs/deployment.md#️-prerequisites-day-0-setup)**.
2. **Trigger Unified Pipeline**:
   ```bash
   ./scripts/deploy-gce.sh
   ```

### 🛰️ The "Vault" Architecture
- **Immutable OS**: The container runs with a **Read-Only Root Filesystem** for maximum runtime security.
- **Unified Pipeline (v3.0)**: A fully automated **Build-Scan-Deploy** manifest (`cloudbuild.yaml`) that handles everything from parallel linting to automated vulnerability gating.
- **Kaniko Acceleration**: High-performance layer caching cuts build times by up to 10x.

---

For a deep dive into the orchestration engineering, see the **[🚢 Detailed Deployment Guide](./docs/deployment.md)**.

---

---

---

## ⚡ Mathematical Foundations (Zap Economy)

DreamBees implements a deterministic resource management system where user interactions are governed by formal distribution and consumption functions, ensuring long-term economic stability and incentive alignment.

### 1. Resource Distribution (Daily Claims)
The reward function $R(\tau)$ for a user with streak $\tau$ is defined as follows:

$$ R(\tau) = B + \min((\tau - 1) \cdot \beta, M) $$

| Variable | Definition | Production Value |
| :--- | :--- | :--- |
| $B$ | **Base Reward**: The initial Zaps granted per claim. | 100 ⚡ |
| $\beta$ | **Streak Bonus**: Incremental reward per contiguous day. | 10 ⚡ |
| $M$ | **Maximum Cap**: The upper boundary for cumulative bonuses. | 100 ⚡ |
| $\tau$ | **Streak Interval**: The number of contiguous successful claims. | $1, n \dots$ |

#### 🕒 Temporal Constraint (The 48h Window)
The streak state $\tau$ at interval $n+1$ is modeled as a discrete state transition governed by the **Theorem of Continuity ($\Theta$)**. This theorem defines the valid temporal boundaries $\Delta t = t_{n+1} - t_n$ for which a streak remains monotonic.

$$ \Theta = \{ (t_{n}, t_{n+1}) \mid \Delta t \in [24\text{h}, 48\text{h}] \} $$

**Transition Function ($F$):**
The system's state machine mapping $F(s_{n}, t_{n+1})$ defines the behavioral outcomes for each interaction:

$$
F(s_{n}, t_{n+1}) = \begin{cases} 
\text{Continuous}(\tau_{n} + 1) & \text{if } \Delta t \in \Theta \\
\text{Reset}(1) & \text{if } \Delta t > 48\text{h} \\
\text{Blocked} & \text{if } \Delta t < 24\text{h}
\end{cases}
$$

---

- **Grace Period (Incentive Physics)**: The **48-hour upper bound** is a deliberate "Grace Period" designed as a psychological buffer for user retention. It provides flexibility for real-world user availability while maintaining the 24-hour periodic engagement target.
- **Monotonicity & Architectural Integrity**: To ensure state integrity, $\Delta t$ is calculated using the **Firestore `serverTimestamp()`**. This provides a monotonic, server-side source of truth that is immune to local machine clock manipulation and timezone exploits.
- **Stratified Time Segments**: The 24-hour lower bound is enforced by a deterministic UTC identifier (`claim-YYYY-MM-DD`), ensuring only one state increment $\tau \to \tau+1$ is possible per universal day.

```mermaid
stateDiagram-v2
    [*] --> Idle: Initial State
    Idle --> PendingSelection: /claim Interaction
    
    state PendingSelection {
        [*] --> CheckInterval: Δt calculation
        CheckInterval --> WithinWindow: Δt ∈ [24h, 48h]
        CheckInterval --> WindowExpired: Δt > 48h
        CheckInterval --> Blocked: Δt < 24h
    }

    WithinWindow --> ActiveStreak: Update τ+1 (Commit)
    WindowExpired --> TerminalReset: Reset τ=1 (Commit)
    Blocked --> Idle: Excepti

[truncated…]