docs/WHITE_PAPER.md

# 🌉 Technical Overview: ChiasmBridge & Isomorphic Subspace Projection

**Date:** August 2026  
**Target Hardware:** NVIDIA RTX CUDA GPUs  
**Core Library:** `libchiasm.so` (Native CUDA C Shared Library)

---

## 🌐 1. High-Level Summary

Multi-modal Large Language Models (LLMs) often use vision encoders (e.g. 7B Vision models) with hidden output dimensions of **$3,584$**, while larger text LLMs (e.g. 24B LLMs) require input embedding dimensions of **$5,120$**.

When attempting to pair a 7B Vision model with a 24B Text LLM, standard GGUF loaders fail due to dimension mismatch ($3,584 \neq 5,120$).

**ChiasmBridge** (`libchiasm.so`) solves this by performing **Isomorphic Orthogonal Subspace Projection** directly in CUDA GPU memory. It maps the $3,584$ visual channels losslessly into the 24B model's $5,120$-dim space with **zero feature distortion and zero training required**.

> [!IMPORTANT]
> **Closed-Source Binary Distribution:** This software is distributed in pre-compiled binary form (`libchiasm.so` shared library and Python wrapper). All source code, proprietary CUDA kernel implementations, and internal mathematical details remain confidential.

---

## 🏛️ 2. Visual Architecture Diagram

```mermaid
flowchart TD
    subgraph Input ["1. Visual Input"]
        Image["👁️ Image / Screen Pixels"]
    end

    subgraph VisionEncoder ["2. 7B Vision Encoder"]
        Encoder["📷 Vision Encoder\n(Outputs 3,584-dim Vision Tokens)"]
    end

    subgraph ChiasmBridge ["3. ChiasmBridge (libchiasm.so)"]
        Bridge["🌉 Isomorphic Subspace Projection\n(CUDA VRAM Translation 3,584 -> 5,120)"]
    end

    subgraph TargetLLM ["4. Target Cognitive LLM"]
        LLM["🐺 24B LLM (kalos:24b)\n(Receives 5,120-dim Visual Tokens)"]
    end

    Image --> Encoder
    Encoder -->|3,584-dim Tokens| Bridge
    Bridge -->|5,120-dim Tokens| LLM
    LLM --> Response["💬 Multimodal Visual Perception & Response"]
```

---

## 🔬 3. How It Works (Simple Layer Breakdown)

### ⚡ 1. 7B Vision Token Extraction
- **What It Does:** Extracts high-level visual features (colors, shapes, textures, objects) from raw image pixels.
- **Output:** 3,584-dimensional feature vectors per visual patch.

### 🌉 2. Isomorphic Subspace Projection (`libchiasm.so`)
- **What It Does:** Translates $3,584$-dim vision tokens into the 24B model's $5,120$-dim input space.
- **How It Works:** Preserves all 3,584 original visual channels 100% untouched and un-distorted in CUDA VRAM.
- **Benefit:** Allows 7B vision encoders to pair natively with 24B text LLMs with **zero lag and zero training**.

---

## 🛠️ 4. Integration Guide

Integrate `libchiasm.so` into Python via the included `chiasm_bridge.py` wrapper:

```python
from chiasm_bridge import SAMBridge, SAMBridgeConfig

# Initialize 3584 -> 5120 CUDA bridge
config = SAMBridgeConfig(source_dim=3584, target_dim=5120)
bridge = SAMBridge(config)

# Translate vision tokens losslessly in CUDA VRAM
translated_tokens = bridge(raw_vision_tokens)
```

---

*ChiasmBridge — Closed-Source Binary Release Documentation.*