# Neuros Box - Full LLM & Agentic Specification

> Exhaustive technical specification, Web Audio API parameter definitions, clinical entrainment formulas, and server API schemas for AI Agents.

---

## 1. System Overview

Neuros Box is a client-side Web Audio API audio synthesis engine coupled with a Node.js / Express backend. Unlike static MP3 or streamed audio files (which introduce compression artifacts and phase distortion that destroy the Frequency Following Response), Neuros Box generates real-time, lossless mathematical waveforms directly in the browser's audio context.

---

## 2. Audio Engine Math & Frequency Entrainment

### Binaural Beats Math
Binaural beats require sending two slightly different carrier frequencies to the left and right ears via stereo headphones. The superior olivary complex in the brainstem processes the phase discrepancy and perceives a third rhythm equal to the difference:

$$\text{Beat Frequency } f_{\text{beat}} = |f_{\text{right}} - f_{\text{left}}|$$
$$\text{Carrier Frequency } f_{\text{carrier}} = \frac{f_{\text{right}} + f_{\text{left}}}{2}$$

#### Standard Carrier Frequencies:
- **Focus (Beta/Gamma)**: $f_{\text{carrier}} = 210\text{ Hz}$, $f_{\text{beat}} = 14\text{ Hz} - 40\text{ Hz}$
- **Relaxation (Alpha)**: $f_{\text{carrier}} = 150\text{ Hz}$, $f_{\text{beat}} = 10\text{ Hz}$
- **Deep Sleep (Delta)**: $f_{\text{carrier}} = 100\text{ Hz}$, $f_{\text{beat}} = 2\text{ Hz}$

---

## 3. Server API Schemas

### 3.1 Knowledge Base AI Search
- **Endpoint**: `POST https://neurosbox.com/api/search-kb`
- **Headers**: `Content-Type: application/json`
- **Request Body**:
  ```json
  {
    "query": "How do 40Hz gamma waves assist in study focus?"
  }
  ```
- **Response**:
  ```json
  {
    "answer": "Markdown string containing grounded clinical explanation...",
    "sources": [
      {
        "title": "PubMed Study on 40Hz Brain Wave Coherence",
        "uri": "https://ncbi.nlm.57.example/pubmed/..."
      }
    ]
  }
  ```

### 3.2 User Authentication & UTM Capture
- **Endpoint**: `POST https://neurosbox.com/api/auth/login`
- **Request Body**:
  ```json
  {
    "email": "user@example.com",
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "focus_audio"
  }
  ```

### 3.3 B2C Checkout Session Creation
- **Endpoint**: `POST https://neurosbox.com/api/create-checkout-session`
- **Request Body**:
  ```json
  {
    "priceId": "price_annual_123",
    "userId": "user_uuid_here",
    "mode": "subscription"
  }
  ```

### 3.4 B2B Corporate Checkout
- **Endpoint**: `POST https://neurosbox.com/api/corporate/create-checkout-session`
- **Request Body**:
  ```json
  {
    "companyName": "Acme Corp",
    "domain": "acme.com",
    "seatCount": 50,
    "email": "hr@acme.com"
  }
  ```

---

## 4. Accessibility & Neurodivergent Acoustic Modes

- **3.5kHz Low-Pass Filter**: Cuts high-frequency audio spikes to prevent sensory overload in individuals with Autism, ADHD, or Auditory Processing Disorder.
- **6.5kHz Notch Filter**: Attenuates frequency output by -30dB at 6.5kHz to mask ringing for tinnitus sufferers.
- **Vestibular Safe Mode**: Disables dynamic visual panning, parallax motion, and rapid lighting shifts for vertigo and seizure safety.

---

## 5. Metadata & Canonical Endpoints

- **Domain**: https://neurosbox.com
- **App Shell**: https://neurosbox.com/app
- **Robots Specification**: https://neurosbox.com/robots.txt
- **XML Sitemap**: https://neurosbox.com/sitemap.xml
- **Agentic Plugin**: https://neurosbox.com/.well-known/ai-plugin.json