skeg-llamaindex

LlamaIndex VectorStore adapter for skeg. Compatible with llama-index-core >= 0.10.

Talks to skeg over RESP3 (skeg-resp3, port 6379). That is where the TurboQuant tiers live: the native binary protocol cannot name them, because its kind byte 3 means PQ.

Install

pip install skeg-llamaindex

Pulls in skeg (Python client) and llama-index-core automatically. Server install (skeg engine) is separate:

brew tap skegdb/tap
brew install skeg

Usage

from llama_index.core import VectorStoreIndex, StorageContext, Document
from llama_index.core.node_parser import SentenceSplitter
from skeg_llamaindex import SkegVectorStore

# 1. Start a skeg RESP3 server:
#    skeg-resp3 --data-dir ./data --addr 127.0.0.1:6379

# 2. Point the adapter at it. `dim` must match the embedding model.
store = SkegVectorStore.from_uri(
    "skeg://127.0.0.1:6379/notes",
    dim=1024,             # mxbai-embed-large-v1 dimension
    backend="flat",       # in-RAM flat index for <50K vectors
    # kind defaults to "tq2"; see the tier table below
)

# 3. Wire into LlamaIndex.
ctx = StorageContext.from_defaults(vector_store=store)
docs = [Document(text="hello world"), Document(text="goodbye world")]
index = VectorStoreIndex.from_documents(docs, storage_context=ctx)

# 4. Query as usual.
engine = index.as_query_engine()
print(engine.query("what does the first doc say?"))

Quantisation tier (kind)

The tier is fixed when the index is created. Changing it means creating a new index and re-ingesting.

Index backend choice

For the pre-build path, build offline once and start the server in serve mode; this adapter then queries it read-only:

# Build the index offline (one shell):
skeg-cli build --input embeddings.npy --output ./data --name notes

# Serve it read-only (another shell):
skeg-resp3 --mode serve --data-dir ./data --tier tq2

What this adapter handles

• add(nodes): VSET each embedding + KV-store the text + metadata
• query(VectorStoreQuery): VSEARCH top-k, returns node_ids + similarity
• delete(ref_doc_id): VDEL + drop KV keys
• Stable mapping node_id (str) → vec_id (u64) via xxh3

What this adapter does not do

• Metadata filter pushdown: LlamaIndex post-filters returned hits. (The server does support SKEG.VSEARCH ... FILTER; this adapter does not translate LlamaIndex filters onto it yet.)
• Batched VSET: one VSET per node on the synchronous path. For large corpora build the index offline with skeg-cli build and serve it read-only. (The server does support SKEG.VMSET; wiring it up here is open work.)
• Hybrid sparse+dense search: skeg's surface is dense-only.
• Async API: this adapter is synchronous.

Test-suite safety

The pytest suite spawns its own skeg-resp3 via the conftest fixture and tears it down at the end. Set SKEG_RESP3_BIN to the binary, or the tests skip. The tests create VINDEX entries with names like notes-<test_name> and drop them after each test. If you ever override the fixture to point at an external server, those VINDEX names may collide with yours. The fixture is the safe default.

License

Apache-2.0.