eulix-embed
eulix-embed is the Python tool that turns the parser’s knowledge base into vectors, and answers “what vector is this question?” while you chat.
Crate / path:
eulix-embed/(entry pointmain.py, version0.4.2)
Language: Python 3.11
Status: beta
Last verified against:ad744e9
Overview
Keyword search finds code that shares words with your question. Embeddings find code that means something similar. An embedding model turns a piece of text into a list of numbers (a vector) such that texts with similar meaning get vectors that point in similar directions. eulix-embed does this for every function, method, class and file in a repository, and saves the vectors to disk so that the eulix program can search them later.
It has two jobs:
- Indexing (
embedcommand, run byeulix analyze): readkb.json, cut it into chunks, embed each chunk, and writeembeddings.binandvectors.bin. - Query embedding (
servercommand, started byeulix chatandeulix mcp): stay running with the model loaded, and turn each question into a vector in a few milliseconds.
Only the default retrieval engine, ETIYA, uses these files. The EHNAS engine does not (Engines).
This folder has five more pages:
| Page | Covers |
|---|---|
| Chunking | How the knowledge base becomes text “cards”, and what the cards contain. |
| Pipeline | Streaming, length bucketing, batching, disk checks. |
| Embedders | The ONNX and PyTorch backends, devices, models. |
| Binary Format | The layout of embeddings.bin and vectors.bin, and SQ8 quantization. |
| Server | The line-based protocol the eulix program speaks to the daemon. |
Why It Exists
Embedding models are Python libraries (ONNX Runtime, PyTorch, Hugging Face tokenizers). The rest of Eulix is Go and Rust. Keeping the model code in one small Python tool, driven over a pipe, lets the other programs stay free of Python and lets users swap models without rebuilding anything.
How It Works
kb.json ──stream──► chunker ──► token-length buckets ──► embedder (ONNX or torch) ──► embeddings.bin
(parser) (threads) (batches) (CPU / GPU) vectors.bin
- Stream.
kb.jsoncan be gigabytes, so it is read in a single pass withijson, one file entry at a time (Pipeline). - Chunk. Each file entry becomes chunks: one per function, class, method, and one summary per file (Chunking).
- Embed. Chunks are grouped by token length so batches need little padding, then run through the model (Embedders).
- Write. Vectors are written to disk as they are produced, so memory use is one batch, not the whole index (Binary Format).
Commands
Run as python main.py <command>; if the first argument is not a known command, embed is assumed.
| Command | What it does |
|---|---|
embed |
Build embeddings.bin and vectors.bin from a knowledge base. |
query -q "text" |
Embed one string and print it (json, or binary). |
server |
Long-running daemon for query embedding (Server). |
compare <emb> <vec> |
Check the two binary files for consistency: duplicate ids, norms, dimension. |
ijson-backend |
Report which JSON parsing backend is active. |
version |
Print the version. |
Main Components
| Folder or file | Responsibility |
|---|---|
main.py |
Argument parsing, dependency check, dispatch. |
cli/ |
Command implementations and compare. |
chunking/ |
Chunking and the text formatters. |
pipeline/ |
The shared driver and the ONNX/torch subclasses. |
embedders/ |
The two model backends. |
data_io/ |
Streaming JSON reader, binary reader and writer, quantization. |
server/ |
The daemon. |
utils/ |
Constants (binary magic and version, bucket sizes), shared types. |
Data In, Data Out
In: kb.json. Out: embeddings.bin (the vectors) and vectors.bin (the chunk ids, in the same order). eulix analyze calls it as embed -k .eulix/kb.json -o .eulix -m <model> --quantize -e <engine>.
Key Algorithms
The interesting ones are length bucketing (Pipeline), mean pooling and normalization (Embedders), and scalar quantization to bytes (Binary Format).
Configuration
eulix.toml sets [embeddings] model, engine, dimension and debug (Config). Flags of embed:
| Flag | Default | Meaning |
|---|---|---|
-k, --kb-path |
knowledge_base.json |
Input knowledge base. |
-o, --output |
./embeddings |
Output directory. |
-m, --model |
BAAI/bge-base-en-v1.5 |
Hugging Face model name. |
-e, --engine |
onnx |
onnx or torch. |
-d, --device |
auto | cuda, rocm, mps or cpu. |
-b, --batch-size |
auto | 64 on GPUs, 16 on CPU. |
--max-chunk |
2000 | Longest chunk, in characters. |
--quantize |
off | Store vectors as bytes (Binary Format). |
Recommended models: BAAI/bge-base-en-v1.5 (768 dimensions, the default), BAAI/bge-small-en-v1.5 and sentence-transformers/all-MiniLM-L6-v2 (384), and jinaai/jina-embeddings-v2-base-code (768, long inputs up to 8,192 tokens).
Install the Python packages with uv pip install -r requiremenents/<file>.txt (the folder name is spelled that way) where the file is onnx-nvidia, onnx-amd, torch-nvidia or torch-amd. eulix does this for you on first run.
Usage Examples
python main.py embed -k .eulix/kb.json -o .eulix -m BAAI/bge-base-en-v1.5 -e onnx --quantize
python main.py query -q "how does authentication middleware work" -e onnx
python main.py compare .eulix/embeddings.bin .eulix/vectors.bin
Expected result: a progress bar while embedding and a summary of chunks per second; compare ends with a pass or fail report.
Performance Notes
The pipeline is designed so that peak memory is about one batch of vectors, and so that GPUs see few padding tokens. I found no current benchmark: the older benchmark.md in the project history describes an earlier Rust implementation and was not carried over.
Limitations
| Limitation | Why it happens | Workaround |
|---|---|---|
| The chunk text is much thinner than documented. | See Chunking and EMB-6 and EMB-7. | None yet. |
| ROCm gives wrong vectors with ONNX. | See EMB-1. | Use engine = "ehnas". |
| Needs Python 3.11 and (first run) network access. | Model files are downloaded from Hugging Face. | Pre-download or point -m at a local model. |
Related Docs
- Chunking, Pipeline, Embedders, Binary Format, Server.
- Embeddings (eulix-cli): the Go side of the daemon.
- Embedding issues.