# Bi-Mind Engine - AI Agent Specification (AGENTS.md)

> **Company / Maintainer:** Alatus Info. Ltd  
> **Target Audience:** Autonomous AI Agents (Gemini, Claude, Antigravity, ChatGPT, DeepSeek, AutoGPT)  
> **Purpose:** Machine-readable specification for generating, parsing, and streaming **BEX (Bi-Mind Expression)** physics rules.

---

## 1. Overview & Capabilities

**Bi-Mind Engine** is an ultra-high-performance web particle physics simulation engine developed by **Alatus Info. Ltd**, built on **Data-Oriented Design (DOD)** principles.

* **Memory Layout:** 4 x 32-bit floats per particle (`[x, y, vx, vy]`). 10,000 particles = **160 KB** contiguous buffer.
* **Architecture:** Web Worker Physics Loop (`Float32Array`) + Main Thread Zero-GC Canvas Renderer (`SharedArrayBuffer` / zero-copy `ArrayBuffer` transfer).
* **LLM Token Optimization:** Instead of streaming entire JS applications (~380-400 tokens), AI agents stream ultra-compact **BEX** RPN strings (~30-40 tokens), achieving **90%+ LLM token savings**.

---

## 2. BEX (Bi-Mind Expression) RPN Grammar

BEX statements are delimited by pipe characters (`|`). Each statement is evaluated in **Reverse Polish Notation (RPN)** stack evaluation.

### Available Variables
| Identifier | Description | Range |
| :--- | :--- | :--- |
| `x` | Particle X Position | `0` to `width` |
| `y` | Particle Y Position | `0` to `height` |
| `vx` | Particle X Velocity | `-50` to `50` |
| `vy` | Particle Y Velocity | `-50` to `50` |
| `g` | Gravity / Buoyancy Constant | `-1.0` to `1.0` |
| `f` | Friction Damping Factor | `0.80` to `1.0` |
| `width` | Canvas Width (px) | e.g. `800` |
| `height` | Canvas Height (px) | e.g. `600` |
| `mx` | Mouse X Position (px) | `0` to `width` |
| `my` | Mouse Y Position (px) | `0` to `height` |
| `mforce` | Mouse Force State | `1` (attract), `-1` (repulse), `0` (none) |

### Supported Operators
* **Arithmetic:** `+`, `-`, `*`, `/`
* **Comparisons:** `<`, `>`, `<=`, `>=`, `==`, `!=`
* **Ternary Operator:** `cond trueVal falseVal ?`
* **Assignment Operators:** `=vx`, `=vy`, `=x`, `=y`

---

## 3. Reference BEX Expressions for AI Agents

### 🚀 Standard Antigravity Buoyancy (~40 Tokens)
```text
vy g - =vy | vx f * =vx | vy f * =vy | x vx + =x | y vy + =y | y 0 < vy -0.8 * vy ? =vy | y 0 < 0 y ? =y | x 0 < vx -0.8 * vx ? =vx | x 800 > vx -0.8 * vx ? =vx
```

### 🌀 Swirling Galaxy Vortex (~45 Tokens)
```text
vx 0.02 * vy - =vy | vy 0.02 * vx + =vx | vx f * =vx | vy f * =vy | x vx + =x | y vy + =y | x 0 < 800 x ? =x | x 800 > 0 x ? =x | y 0 < 600 y ? =y | y 600 > 0 y ? =y
```

### 💨 Atmospheric Wind Shear (~30 Tokens)
```text
vy g - =vy | vx 0.3 + =vx | vx f * =vx | vy f * =vy | x vx + =x | y vy + =y | x 800 > 0 x ? =x | y 0 < 600 y ? =y
```

---

## 4. Performance Benchmark Metrics

| Metric | Classic Monolithic JS | Bi-Mind Engine (BEX + DOD) | AI Agent Benefit |
| :--- | :--- | :--- | :--- |
| **Token Cost** | ~380 Tokens | **~40 Tokens** | **90% Token Reduction** |
| **RAM Footprint** | ~640 KB+ (V8 Objects) | **160 KB** (Float32Array) | **4x Memory Savings** |
| **V8 Memory Access** | Object Lookups (`p.x`) | Pointer Offsets (`data[i]`) | **Zero Lookup Overhead** |
| **Garbage Collection** | High (GC Stutters) | **0 Allocations** | **100% GC-Free** |

---

## 5. Webhook Integration (`synapso_mailsrv`)
Feedback submissions and custom BEX suggestions stream to the Synapso mail service via:
`POST /api/v1/synapso_mailsrv/feedback`