ix-embeddings 0.1.0

Shared embedding infrastructure for Ixchel with pluggable providers
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# 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

```rust
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:

| Provider      | Feature               | GPU Support | Notes                                 |
| ------------- | --------------------- | ----------- | ------------------------------------- |
| **fastembed** | `fastembed` (default) | CPU only    | ONNX Runtime, fast startup            |
| **candle**    | `candle`              | Metal/CUDA  | Hugging Face models, GPU acceleration |

### Feature Flags

```toml
# 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`:

```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](https://docs.rs/fastembed) for full model list.

### Candle

Any BERT-based model from Hugging Face Hub:

| Model                                    | Params | Dims | Notes                                   |
| ---------------------------------------- | ------ | ---- | --------------------------------------- |
| `sentence-transformers/all-MiniLM-L6-v2` | 22M    | 384  | Fastest, good quality                   |
| `BAAI/bge-small-en-v1.5`                 | 33M    | 384  | Better retrieval                        |
| `BAAI/bge-base-en-v1.5`                  | 109M   | 768  | Higher quality                          |
| `BAAI/bge-large-en-v1.5`                 | 335M   | 1024 | **Best quality** (recommended with GPU) |

For highest quality with Metal GPU acceleration:

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

## Consumers

| Tool     | Use Case                       |
| -------- | ------------------------------ |
| Ixchel   | Semantic search over knowledge |
| demo-got | Example usage + benchmarking   |

## License

MIT

## Kiro Specs

- [Requirements][requirements]
- [Design][design]
- [Tasks][tasks]

<!-- Links -->

[requirements]: specs/requirements.md
[design]: specs/design.md
[tasks]: specs/tasks.md