docs/SETUP_GUIDE.md

# 🚀 ChiasmBridge — Step-by-Step Setup & User Guide

Welcome to the **ChiasmBridge** setup guide. This document guides you through configuring `libchiasm.so` to bridge disparate feature vectors across ANY dimension boundary ($N \iff M$) and ANY modality (Vision, Audio/Speech, Haptics, and LLMs).

---

## 📋 Prerequisites & Installation

1. **System Requirements:** Linux OS with NVIDIA GPU (Ampere or newer recommended) and CUDA drivers installed.
2. **Installation via Pip:**
   ```bash
   git clone https://github.com/MongooseReborn/chiasm-bridge.git
   cd chiasm-bridge
   pip install .
   ```

---

## 🛠️ Step 1: Basic Universal Usage (`chiasm`)

ChiasmBridge provides a lightweight Python package (`chiasm`) that interfaces natively with compiled CUDA shared library `libchiasm.so`.

```python
import torch
from chiasm import ChiasmBridge, ChiasmConfig

# 1. Define dynamic N -> M configuration (e.g. 3584 Vision -> 5120 LLM, 1024 Audio -> 4096 LLM)
config = ChiasmConfig(source_dim=3584, target_dim=5120)
bridge = ChiasmBridge(config)

# 2. Forward Projection (N -> M): Sensory Perception -> LLM Space
raw_sensory_tokens = torch.randn(1, 64, 3584)       # [batch, seq_len, 3584]
translated_tokens = bridge.project_forward(raw_sensory_tokens)  # [batch, seq_len, 5120]

print("Forward Projected Shape:", translated_tokens.shape)  # torch.Size([1, 64, 5120])

# 3. Inverse Projection (M -> N): LLM Space -> Sensory Reconstruction
reconstructed_sensory = bridge.project_inverse(translated_tokens)
print("Inverse Reconstructed Shape:", reconstructed_sensory.shape)  # torch.Size([1, 64, 3584])
```

---

## 💾 Step 2: Directory Structure

```text
chiasm-bridge/
├── bin/
│   └── libchiasm.so          # Pre-compiled CUDA Binary Shared Library (Stripped)
├── chiasm/
│   ├── __init__.py           # Package Exports
│   └── sam_bridge.py         # Bi-Directional Modular Neural Adapter
├── docs/
│   ├── WHITE_PAPER.md        # Technical Architecture Overview
│   ├── SETUP_GUIDE.md        # Step-by-Step Setup Guide
│   ├── Whitepaper.html       # Web-formatted Whitepaper
│   └── test_modular_chiasm.py # Universal Modular Test Suite
├── README.md
└── setup.py                  # Pip Package Installer
```

---

*ChiasmBridge — Mongoose & Kalos Engine Architecture Team @ BlackForest Studio (2026).*