ix-embeddings

Shared embedding infrastructure for Ixchel with pluggable providers.

Why

Multiple Ixchel tools need semantic embeddings:

• ixchel — Embed knowledge artifacts for semantic search
• demo-got — Example usage for graph + vector pipelines This crate provides a unified Embedder so each tool doesn't reinvent embedding logic.

Usage

use ix_embeddings::Embedder;

// Create embedder (uses config from ~/.ixchel/config/config.toml and .ixchel/config.toml)
let embedder = Embedder::new()?;

// Embed single text
let embedding = embedder.embed("How to handle authentication?")?;
assert_eq!(embedding.len(), embedder.dimension());

// Embed batch (more efficient)
let embeddings = embedder.embed_batch(&[
    "First document",
    "Second document",
])?;

Providers

Enable providers via Cargo features:

Feature Flags

# Default (fastembed only)
ix-embeddings = { path = "..." }

# Candle with Metal (macOS)
ix-embeddings = { path = "...", features = ["candle", "metal"] }

# Candle with CUDA (Linux/Windows)
ix-embeddings = { path = "...", features = ["candle", "cuda"] }

# Both providers
ix-embeddings = { path = "...", features = ["fastembed", "candle"] }

Configuration

Configure via ~/.ixchel/config/config.toml:

[embedding]
provider = "fastembed"             # or "candle"
model = "BAAI/bge-small-en-v1.5"   # HuggingFace model ID
batch_size = 32                    # Batch size for embed_batch
dimension = 384                    # Optional (auto-detected)

Supported Models

FastEmbed (ONNX)

• BAAI/bge-small-en-v1.5 (default, 384 dimensions)
• BAAI/bge-base-en-v1.5 (768 dimensions)
• sentence-transformers/all-MiniLM-L6-v2 (384 dimensions)

See fastembed docs for full model list.

Candle

Any BERT-based model from Hugging Face Hub:

For highest quality with Metal GPU acceleration:

[embedding]
provider = "candle"
model = "BAAI/bge-large-en-v1.5"

Consumers

License

MIT

Kiro Specs

• Requirements
• Design
• Tasks