Skip to content

AGENT_PLAYBOOK.md

Latest commit

 

History

History
64 lines (47 loc) · 4.23 KB

AGENT_PLAYBOOK.md

File metadata and controls

64 lines (47 loc) · 4.23 KB
Raw

Agent Playbook — DreamBees MLX Studio

What is this? A high-velocity, current-state operating brief for autonomous agents interacting with DreamBees MLX Studio. When do I use it? At task start to understand the active developer landscape, model cards, substrate connections, and validation paths. Source of Truth: Active workspace files, package manifests, and runtime execution logs.

Last audited: 2026-08-08

Current System Architecture

Area Component Location / Evidence
Interface ChatGPT-style Chat UI src/components/DreamBeesStudio.tsx, DreamBeesStudio.css
Prompt LLM Onboard Gemma 4 Prompt Rewriter src/core/gemmaPromptEngine.ts, electron/mlx/mlx_image_daemon.py
Image Engine MLX Native Diffusion Engine electron/mlx/mlx_image_daemon.py (mflux, mlx, ZImageTurbo)
Substrate BroccoliDB Substrate broccolidb/ (@noorm/broccolidb), electron/database.ts
Main Process Electron Main & Sidecar Supervisor electron/main.ts, electron/sidecar_supervisor.ts
Preload Bridge ContextBridge IPC electron/preload.ts, src/electron-api.d.ts

⚡ Agent Operational Rules & Hardening Protocols

  1. Direct Agent Prompt Injection & Dual-Stage Pipeline:

    • Autonomous Agent Execution (Gemma 4 Bypass): Autonomous AI agents craft pre-optimized, model-card-tailored prompts directly, bypassing Stage 1 (Gemma 4 LLM) to save ~2 GB text model VRAM and 15s LLM latency, submitting directly to Stage 2.
    • Human Intent Translation (Stage 1 Gemma 4): Evaluates raw human intent against the target model card (FLUX.2 Klein, Z-Image Turbo 6B, Sana 2.0, Wan 2.1, Lumina 2.0, SD 3.5), generating model-card-rewritten prompts (15s ceiling timeout).
    • Stage 2 (MLX Metal GPU Engine): Executes native Metal GPU diffusion, streaming real-time TAESD latent previews and VRAM telemetry into the ChatGPT message bubble.

  2. Output Hardening & Anti-Corruption Invariants:

    • Prompt Clause Deduplication: All rewritten prompts run through sanitizeAndDeduplicatePrompt() to eliminate duplicate suffixes, code fences, and unclosed XML tags.
    • TAESD NCHW/NHWC Transpose Safety: Latent preview decoding verifies shape order ([C, H, W] vs [H, W, C]) to prevent dimension flipping and corrupted previews.
    • 64-Pixel Spatial Grid Alignment: Width/height dimensions snap to multiples of 64 ((dim // 64) * 64) to align with DiT / Rectified Flow positional embeddings.
    • Atomic Disk Writes: Final image files are saved to .tmp.png before os.replace atomic replacement to prevent reading partial image frames.

  3. BroccoliDB Governance:

    • Database operations use BroccoliDB's Connection, Workspace, and AgentContext.
    • SQLite connections operate under WAL journal mode with busy_timeout = 5000 and automatic disk quota enforcement (2GB max image cache).

  4. Mechanical Sympathy Performance Principles:

    • Monomorphic Shapes: Preserve constant property keys across records to prevent V8 TurboFan deoptimizations.
    • Pre-filtering: Use quick string searches before multi-pass regex evaluations.
    • Reference Caching: Cache immutably structured message projections using WeakMap.

🛠️ Validation Command Menu

Scope Command
Production Build npm run build
TypeScript Type Check npx tsc -p tsconfig.json --noEmit
Python Daemon Verification python3 -m py_compile electron/mlx/mlx_image_daemon.py
12-Test Metal Benchmark Suite python3 tests/benchmarks/run_benchmarks.py --model <model_id>

📊 Empirical Performance Findings

  • Pass Rate: 100.0% (12 / 12 Passed across FLUX.2 Klein 4B & Z-Image Turbo 6B)
  • Multi-Model GPU Throughput: 45.2s (Z-Image Turbo 6B) / 77.6s (FLUX.2 Klein 4B) per 512x512 image
  • Live Visualizer Stream: < 1.0 ms sub-millisecond neural TAESD preview
  • VRAM Cache & Memory Limits: 64 MB – 256 MB cache ceiling (25%–30% RAM for 4B models, 30%–40% RAM for 6B/9B models like Z-Image Turbo / FLUX 9B, 75% system VRAM circuit breaker, reserves 60%–75% RAM for macOS)
  • Published Benchmark Document: docs/INDUSTRY_BENCHMARKS.md