Metadata-Version: 2.4
Name: skeg-llamaindex
Version: 0.2.0
Summary: LlamaIndex VectorStore adapter for skeg.
Author: skeg contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/skegdb/skeg-llamaindex
Project-URL: Repository, https://github.com/skegdb/skeg-llamaindex
Keywords: llamaindex,vector-store,skeg,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: skeg<0.3,>=0.2
Requires-Dist: llama-index-core>=0.10
Requires-Dist: xxhash>=3.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-timeout>=2.0; extra == "test"
Requires-Dist: numpy>=1.24; extra == "test"
Requires-Dist: ruff<0.12,>=0.11; extra == "test"
Dynamic: license-file

# skeg-llamaindex

LlamaIndex `VectorStore` adapter for [skeg](https://github.com/skegdb/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

```sh
pip install skeg-llamaindex
```

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

```sh
brew tap skegdb/tap
brew install skeg
```

## Usage

```python
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`)

| `kind` | What it is | When |
| --- | --- | --- |
| `tq2` | TurboQuant, 2 bits/dim. **The default.** | Start here. Near-f32 recall at a fraction of the RAM |
| `tq1` | TurboQuant, 1 bit/dim | Tightest memory budget, some recall given up |
| `tq4` | TurboQuant, 4 bits/dim | When tq2 measurably loses recall on your data |
| `int8` | 8-bit integer | Previous default; kept for existing indexes |
| `f32` | No quantisation | Exact scores, largest footprint |
| `binary` | 1-bit sign | Hamming distance, specialised use |

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

## Index backend choice

| Use case | `backend` | Notes |
| --- | --- | --- |
| Personal AI, < 50K nodes | `flat` | Exhaustive scan; fast on M-series CPUs |
| RAG over a fixed corpus, > 50K nodes | `disk_vamana` (pre-build) | Use `skeg-cli build`, then serve read-only |
| Streaming insert with eventual large size | `disk_vamana` (RW) | Delta WAL handles streaming |

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

```sh
# 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.
