# Hyperbolic Embeddings Integration Plan

## Overview

Integrate hyperbolic geometry operations into PostgreSQL for hierarchical data representation, enabling embeddings in Poincaré ball and Lorentz (hyperboloid) models with native distance functions and indexing.

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                     PostgreSQL Extension                         │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                 Hyperbolic Type System                   │    │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │    │
│  │  │   Poincaré   │  │   Lorentz    │  │   Klein      │   │    │
│  │  │     Ball     │  │ Hyperboloid  │  │    Model     │   │    │
│  │  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘   │    │
│  └─────────┼─────────────────┼─────────────────┼───────────┘    │
│            └─────────────────┴─────────────────┘                │
│                              ▼                                   │
│              ┌───────────────────────────┐                       │
│              │   Riemannian Operations   │                       │
│              │   (Exponential, Log, PT)  │                       │
│              └───────────────────────────┘                       │
└─────────────────────────────────────────────────────────────────┘
```

## Module Structure

```
src/
├── hyperbolic/
│   ├── mod.rs              # Module exports
│   ├── types/
│   │   ├── poincare.rs     # Poincaré ball model
│   │   ├── lorentz.rs      # Lorentz/hyperboloid model
│   │   └── klein.rs        # Klein model (projective)
│   ├── manifold.rs         # Manifold operations
│   ├── distance.rs         # Distance functions
│   ├── index/
│   │   ├── htree.rs        # Hyperbolic tree index
│   │   └── hnsw_hyper.rs   # HNSW for hyperbolic space
│   └── operators.rs        # SQL operators
```

## SQL Interface

### Hyperbolic Types

```sql
-- Create hyperbolic embedding column
CREATE TABLE hierarchical_nodes (
    id SERIAL PRIMARY KEY,
    name TEXT,
    euclidean_embedding vector(128),
    poincare_embedding hyperbolic(128),      -- Poincaré ball
    lorentz_embedding hyperboloid(129),      -- Lorentz model (d+1 dims)
    curvature FLOAT DEFAULT -1.0
);

-- Insert with automatic projection
INSERT INTO hierarchical_nodes (name, euclidean_embedding)
VALUES ('root', '[0.1, 0.2, ...]');

-- Auto-project to hyperbolic space
UPDATE hierarchical_nodes
SET poincare_embedding = ruvector_to_poincare(euclidean_embedding, curvature);
```

### Distance Operations

```sql
-- Poincaré distance
SELECT id, name,
       ruvector_poincare_distance(poincare_embedding, query_point) AS dist
FROM hierarchical_nodes
ORDER BY dist
LIMIT 10;

-- Lorentz distance (often more numerically stable)
SELECT id, name,
       ruvector_lorentz_distance(lorentz_embedding, query_point) AS dist
FROM hierarchical_nodes
ORDER BY dist
LIMIT 10;

-- Custom curvature
SELECT ruvector_hyperbolic_distance(
    a := point_a,
    b := point_b,
    model := 'poincare',
    curvature := -0.5
);
```

### Hyperbolic Operations

```sql
-- Möbius addition (translation in Poincaré ball)
SELECT ruvector_mobius_add(point_a, point_b, curvature := -1.0);

-- Exponential map (tangent vector → manifold point)
SELECT ruvector_exp_map(base_point, tangent_vector, curvature := -1.0);

-- Logarithmic map (manifold point → tangent vector)
SELECT ruvector_log_map(base_point, target_point, curvature := -1.0);

-- Parallel transport (move vector along geodesic)
SELECT ruvector_parallel_transport(vector, from_point, to_point, curvature := -1.0);

-- Geodesic midpoint
SELECT ruvector_geodesic_midpoint(point_a, point_b);

-- Project Euclidean to hyperbolic
SELECT ruvector_project_to_hyperbolic(euclidean_vec, model := 'poincare');
```

### Hyperbolic Index

```sql
-- Create hyperbolic HNSW index
CREATE INDEX ON hierarchical_nodes USING ruvector_hyperbolic (
    poincare_embedding hyperbolic(128)
) WITH (
    model = 'poincare',
    curvature = -1.0,
    m = 16,
    ef_construction = 64
);

-- Hyperbolic k-NN search
SELECT * FROM hierarchical_nodes
ORDER BY poincare_embedding <~> query_point  -- <~> is hyperbolic distance
LIMIT 10;
```

## Implementation Phases

### Phase 1: Poincaré Ball Model (Week 1-3)

```rust
// src/hyperbolic/types/poincare.rs

use simsimd::SpatialSimilarity;

/// Poincaré ball model B^n_c = {x ∈ R^n : c||x||² < 1}
pub struct PoincareBall {
    dim: usize,
    curvature: f32,  // Negative curvature, typically -1.0
}

impl PoincareBall {
    pub fn new(dim: usize, curvature: f32) -> Self {
        assert!(curvature < 0.0, "Curvature must be negative");
        Self { dim, curvature }
    }

    /// Conformal factor λ_c(x) = 2 / (1 - c||x||²)
    #[inline]
    fn conformal_factor(&self, x: &[f32]) -> f32 {
        let c = -self.curvature;
        let norm_sq = self.norm_sq(x);
        2.0 / (1.0 - c * norm_sq)
    }

    /// Poincaré distance: d(x,y) = (2/√c) * arctanh(√c * ||−x ⊕_c y||)
    pub fn distance(&self, x: &[f32], y: &[f32]) -> f32 {
        let c = -self.curvature;
        let sqrt_c = c.sqrt();

        // Möbius addition: -x ⊕ y
        let neg_x: Vec<f32> = x.iter().map(|&xi| -xi).collect();
        let mobius_sum = self.mobius_add(&neg_x, y);
        let norm = self.norm(&mobius_sum);

        (2.0 / sqrt_c) * (sqrt_c * norm).atanh()
    }

    /// Möbius addition in Poincaré ball
    pub fn mobius_add(&self, x: &[f32], y: &[f32]) -> Vec<f32> {
        let c = -self.curvature;
        let x_norm_sq = self.norm_sq(x);
        let y_norm_sq = self.norm_sq(y);
        let xy_dot = self.dot(x, y);

        let num_coef = 1.0 + 2.0 * c * xy_dot + c * y_norm_sq;
        let y_coef = 1.0 - c * x_norm_sq;
        let denom = 1.0 + 2.0 * c * xy_dot + c * c * x_norm_sq * y_norm_sq;

        x.iter().zip(y.iter())
            .map(|(&xi, &yi)| (num_coef * xi + y_coef * yi) / denom)
            .collect()
    }

    /// Exponential map: tangent space → manifold
    pub fn exp_map(&self, base: &[f32], tangent: &[f32]) -> Vec<f32> {
        let c = -self.curvature;
        let sqrt_c = c.sqrt();

        let lambda = self.conformal_factor(base);
        let tangent_norm = self.norm(tangent);

        if tangent_norm < 1e-10 {
            return base.to_vec();
        }

        let coef = (sqrt_c * lambda * tangent_norm / 2.0).tanh() / (sqrt_c * tangent_norm);
        let direction: Vec<f32> = tangent.iter().map(|&t| t * coef).collect();

        self.mobius_add(base, &direction)
    }

    /// Logarithmic map: manifold → tangent space
    pub fn log_map(&self, base: &[f32], target: &[f32]) -> Vec<f32> {
        let c = -self.curvature;
        let sqrt_c = c.sqrt();

        // -base ⊕ target
        let neg_base: Vec<f32> = base.iter().map(|&b| -b).collect();
        let addition = self.mobius_add(&neg_base, target);
        let add_norm = self.norm(&addition);

        if add_norm < 1e-10 {
            return vec![0.0; self.dim];
        }

        let lambda = self.conformal_factor(base);
        let coef = (2.0 / (sqrt_c * lambda)) * (sqrt_c * add_norm).atanh() / add_norm;

        addition.iter().map(|&a| a * coef).collect()
    }

    /// Project point to ball (clamp norm)
    pub fn project(&self, x: &[f32]) -> Vec<f32> {
        let c = -self.curvature;
        let max_norm = (1.0 / c).sqrt() - 1e-5;
        let norm = self.norm(x);

        if norm <= max_norm {
            x.to_vec()
        } else {
            let scale = max_norm / norm;
            x.iter().map(|&xi| xi * scale).collect()
        }
    }

    #[inline]
    fn norm_sq(&self, x: &[f32]) -> f32 {
        f32::dot(x, x).unwrap_or_else(|| x.iter().map(|&xi| xi * xi).sum())
    }

    #[inline]
    fn norm(&self, x: &[f32]) -> f32 {
        self.norm_sq(x).sqrt()
    }

    #[inline]
    fn dot(&self, x: &[f32], y: &[f32]) -> f32 {
        f32::dot(x, y).unwrap_or_else(|| x.iter().zip(y.iter()).map(|(&a, &b)| a * b).sum())
    }
}

// PostgreSQL type
#[derive(PostgresType, Serialize, Deserialize)]
#[pgx(sql = "CREATE TYPE hyperbolic")]
pub struct Hyperbolic {
    data: Vec<f32>,
    curvature: f32,
}

// PostgreSQL functions
#[pg_extern(immutable, parallel_safe)]
fn ruvector_poincare_distance(a: Vec<f32>, b: Vec<f32>, curvature: default!(f32, -1.0)) -> f32 {
    let ball = PoincareBall::new(a.len(), curvature);
    ball.distance(&a, &b)
}

#[pg_extern(immutable, parallel_safe)]
fn ruvector_mobius_add(a: Vec<f32>, b: Vec<f32>, curvature: default!(f32, -1.0)) -> Vec<f32> {
    let ball = PoincareBall::new(a.len(), curvature);
    ball.mobius_add(&a, &b)
}

#[pg_extern(immutable, parallel_safe)]
fn ruvector_exp_map(base: Vec<f32>, tangent: Vec<f32>, curvature: default!(f32, -1.0)) -> Vec<f32> {
    let ball = PoincareBall::new(base.len(), curvature);
    ball.exp_map(&base, &tangent)
}

#[pg_extern(immutable, parallel_safe)]
fn ruvector_log_map(base: Vec<f32>, target: Vec<f32>, curvature: default!(f32, -1.0)) -> Vec<f32> {
    let ball = PoincareBall::new(base.len(), curvature);
    ball.log_map(&base, &target)
}
```

### Phase 2: Lorentz Model (Week 4-5)

```rust
// src/hyperbolic/types/lorentz.rs

/// Lorentz (hyperboloid) model: H^n = {x ∈ R^{n+1} : <x,x>_L = -1/c, x_0 > 0}
/// More numerically stable than Poincaré for high dimensions
pub struct LorentzModel {
    dim: usize,  // Ambient dimension (n+1)
    curvature: f32,
}

impl LorentzModel {
    /// Minkowski inner product: <x,y>_L = -x_0*y_0 + Σ x_i*y_i
    #[inline]
    pub fn minkowski_dot(&self, x: &[f32], y: &[f32]) -> f32 {
        -x[0] * y[0] + x[1..].iter().zip(y[1..].iter())
            .map(|(&a, &b)| a * b)
            .sum::<f32>()
    }

    /// Lorentz distance: d(x,y) = (1/√c) * arcosh(-c * <x,y>_L)
    pub fn distance(&self, x: &[f32], y: &[f32]) -> f32 {
        let c = -self.curvature;
        let sqrt_c = c.sqrt();
        let inner = self.minkowski_dot(x, y);

        (1.0 / sqrt_c) * (-c * inner).acosh()
    }

    /// Exponential map on hyperboloid
    pub fn exp_map(&self, base: &[f32], tangent: &[f32]) -> Vec<f32> {
        let c = -self.curvature;
        let sqrt_c = c.sqrt();

        let tangent_norm_sq = self.minkowski_dot(tangent, tangent);
        if tangent_norm_sq < 1e-10 {
            return base.to_vec();
        }
        let tangent_norm = tangent_norm_sq.sqrt();

        let coef1 = (sqrt_c * tangent_norm).cosh();
        let coef2 = (sqrt_c * tangent_norm).sinh() / tangent_norm;

        base.iter().zip(tangent.iter())
            .map(|(&b, &t)| coef1 * b + coef2 * t)
            .collect()
    }

    /// Logarithmic map on hyperboloid
    pub fn log_map(&self, base: &[f32], target: &[f32]) -> Vec<f32> {
        let c = -self.curvature;
        let sqrt_c = c.sqrt();

        let inner = self.minkowski_dot(base, target);
        let dist = self.distance(base, target);

        if dist < 1e-10 {
            return vec![0.0; self.dim];
        }

        let coef = dist / (dist * sqrt_c).sinh();

        target.iter().zip(base.iter())
            .map(|(&t, &b)| coef * (t - inner * b))
            .collect()
    }

    /// Project to hyperboloid (ensure constraint satisfied)
    pub fn project(&self, x: &[f32]) -> Vec<f32> {
        let c = -self.curvature;
        let space_norm_sq: f32 = x[1..].iter().map(|&xi| xi * xi).sum();
        let x0 = ((1.0 / c) + space_norm_sq).sqrt();

        let mut result = vec![x0];
        result.extend_from_slice(&x[1..]);
        result
    }

    /// Convert from Poincaré ball to Lorentz
    pub fn from_poincare(&self, poincare: &[f32], poincare_curvature: f32) -> Vec<f32> {
        let c = -poincare_curvature;
        let norm_sq: f32 = poincare.iter().map(|&x| x * x).sum();

        let x0 = (1.0 + c * norm_sq) / (1.0 - c * norm_sq);
        let coef = 2.0 / (1.0 - c * norm_sq);

        let mut result = vec![x0];
        result.extend(poincare.iter().map(|&p| coef * p));
        result
    }

    /// Convert from Lorentz to Poincaré ball
    pub fn to_poincare(&self, lorentz: &[f32]) -> Vec<f32> {
        let denom = 1.0 + lorentz[0];
        lorentz[1..].iter().map(|&x| x / denom).collect()
    }
}

#[pg_extern(immutable, parallel_safe)]
fn ruvector_lorentz_distance(a: Vec<f32>, b: Vec<f32>, curvature: default!(f32, -1.0)) -> f32 {
    let model = LorentzModel::new(a.len(), curvature);
    model.distance(&a, &b)
}

#[pg_extern(immutable, parallel_safe)]
fn ruvector_poincare_to_lorentz(poincare: Vec<f32>, curvature: default!(f32, -1.0)) -> Vec<f32> {
    let model = LorentzModel::new(poincare.len() + 1, curvature);
    model.from_poincare(&poincare, curvature)
}

#[pg_extern(immutable, parallel_safe)]
fn ruvector_lorentz_to_poincare(lorentz: Vec<f32>) -> Vec<f32> {
    let model = LorentzModel::new(lorentz.len(), -1.0);
    model.to_poincare(&lorentz)
}
```

### Phase 3: Hyperbolic HNSW Index (Week 6-8)

```rust
// src/hyperbolic/index/hnsw_hyper.rs

/// HNSW index adapted for hyperbolic space
pub struct HyperbolicHnsw {
    layers: Vec<HnswLayer>,
    manifold: HyperbolicManifold,
    m: usize,
    ef_construction: usize,
}

pub enum HyperbolicManifold {
    Poincare(PoincareBall),
    Lorentz(LorentzModel),
}

impl HyperbolicHnsw {
    /// Distance function based on manifold
    fn distance(&self, a: &[f32], b: &[f32]) -> f32 {
        match &self.manifold {
            HyperbolicManifold::Poincare(ball) => ball.distance(a, b),
            HyperbolicManifold::Lorentz(model) => model.distance(a, b),
        }
    }

    /// Insert with hyperbolic distance
    pub fn insert(&mut self, id: u64, vector: &[f32]) {
        // Project to manifold first
        let projected = match &self.manifold {
            HyperbolicManifold::Poincare(ball) => ball.project(vector),
            HyperbolicManifold::Lorentz(model) => model.project(vector),
        };

        // Standard HNSW insertion with hyperbolic distance
        let entry_point = self.entry_point();
        let level = self.random_level();

        for l in (0..=level).rev() {
            let candidates = self.search_layer(&projected, entry_point, self.ef_construction, l);
            let neighbors = self.select_neighbors(&projected, &candidates, self.m);
            self.connect(id, &neighbors, l);
        }

        self.vectors.insert(id, projected);
    }

    /// Search with hyperbolic distance
    pub fn search(&self, query: &[f32], k: usize, ef: usize) -> Vec<(u64, f32)> {
        let projected = match &self.manifold {
            HyperbolicManifold::Poincare(ball) => ball.project(query),
            HyperbolicManifold::Lorentz(model) => model.project(query),
        };

        let mut candidates = self.search_layer(&projected, self.entry_point(), ef, 0);
        candidates.truncate(k);
        candidates
    }
}

// PostgreSQL index access method
#[pg_extern]
fn ruvector_hyperbolic_hnsw_handler(internal: Internal) -> Internal {
    // Index AM handler
}
```

### Phase 4: Euclidean to Hyperbolic Projection (Week 9-10)

```rust
// src/hyperbolic/manifold.rs

/// Project Euclidean embeddings to hyperbolic space
pub struct HyperbolicProjection {
    model: HyperbolicModel,
    method: ProjectionMethod,
}

pub enum ProjectionMethod {
    /// Direct scaling to fit in ball
    Scale,
    /// Learned exponential map from origin
    ExponentialMap,
    /// Centroid-based projection
    Centroid { centroid: Vec<f32> },
}

impl HyperbolicProjection {
    /// Project batch of Euclidean vectors
    pub fn project_batch(&self, vectors: &[Vec<f32>]) -> Vec<Vec<f32>> {
        match &self.method {
            ProjectionMethod::Scale => {
                vectors.par_iter()
                    .map(|v| self.scale_project(v))
                    .collect()
            }
            ProjectionMethod::ExponentialMap => {
                let origin = vec![0.0; vectors[0].len()];
                vectors.par_iter()
                    .map(|v| self.model.exp_map(&origin, v))
                    .collect()
            }
            ProjectionMethod::Centroid { centroid } => {
                vectors.par_iter()
                    .map(|v| {
                        let tangent: Vec<f32> = v.iter()
                            .zip(centroid.iter())
                            .map(|(&vi, &ci)| vi - ci)
                            .collect();
                        self.model.exp_map(centroid, &tangent)
                    })
                    .collect()
            }
        }
    }

    fn scale_project(&self, v: &[f32]) -> Vec<f32> {
        let norm: f32 = v.iter().map(|&x| x * x).sum::<f32>().sqrt();
        let max_norm = 0.99;  // Stay within ball

        if norm <= max_norm {
            v.to_vec()
        } else {
            let scale = max_norm / norm;
            v.iter().map(|&x| x * scale).collect()
        }
    }
}

#[pg_extern]
fn ruvector_to_poincare(
    euclidean: Vec<f32>,
    curvature: default!(f32, -1.0),
    method: default!(&str, "'scale'"),
) -> Vec<f32> {
    let model = PoincareBall::new(euclidean.len(), curvature);
    let projection = HyperbolicProjection::new(model, method.into());
    projection.project(&euclidean)
}

#[pg_extern]
fn ruvector_batch_to_poincare(
    table_name: &str,
    euclidean_column: &str,
    output_column: &str,
    curvature: default!(f32, -1.0),
) -> i64 {
    // Batch projection using SPI
    Spi::connect(|client| {
        // ... batch update
    })
}
```

## Use Cases

### Hierarchical Data (Taxonomies, Org Charts)

```sql
-- Embed taxonomy with parent-child relationships preserved
-- Children naturally cluster closer to parents in hyperbolic space
CREATE TABLE taxonomy (
    id SERIAL PRIMARY KEY,
    name TEXT,
    parent_id INTEGER REFERENCES taxonomy(id),
    embedding hyperbolic(64)
);

-- Find all items in subtree (leveraging hyperbolic geometry)
SELECT * FROM taxonomy
WHERE ruvector_poincare_distance(embedding, root_embedding) < subtree_radius
ORDER BY ruvector_poincare_distance(embedding, root_embedding);
```

### Knowledge Graphs

```sql
-- Entities with hierarchical relationships
-- Hyperbolic space captures asymmetric relations naturally
SELECT entity_a.name, entity_b.name,
       ruvector_poincare_distance(entity_a.embedding, entity_b.embedding) AS distance
FROM entities entity_a, entities entity_b
WHERE entity_a.id != entity_b.id
ORDER BY distance
LIMIT 100;
```

## Benchmarks

| Operation | Dimension | Curvature | Time (μs) | vs Euclidean |
|-----------|-----------|-----------|-----------|--------------|
| Poincaré Distance | 128 | -1.0 | 2.1 | 1.8x slower |
| Lorentz Distance | 129 | -1.0 | 1.5 | 1.3x slower |
| Möbius Addition | 128 | -1.0 | 3.2 | N/A |
| Exp Map | 128 | -1.0 | 4.5 | N/A |
| HNSW Search (hyper) | 128 | -1.0 | 850 | 1.5x slower |

## Dependencies

```toml
[dependencies]
# SIMD for fast operations
simsimd = "5.9"

# Numerical stability
num-traits = "0.2"
```

## Feature Flags

```toml
[features]
hyperbolic = []
hyperbolic-poincare = ["hyperbolic"]
hyperbolic-lorentz = ["hyperbolic"]
hyperbolic-index = ["hyperbolic", "index-hnsw"]
hyperbolic-all = ["hyperbolic-poincare", "hyperbolic-lorentz", "hyperbolic-index"]
```