Metadata-Version: 2.4
Name: llama-index-vector-stores-ngt
Version: 0.1.0
Summary: LlamaIndex vector store integration for NGT (Neighborhood Graph and Tree)
Author-email: Masajiro Iwasaki <masajiro.iwasaki@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/NGT-labs/llama-index-vector-stores-ngt
Project-URL: Repository, https://github.com/NGT-labs/llama-index-vector-stores-ngt
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: llama-index-core>=0.10.0
Requires-Dist: ngt>=2.8.0
Requires-Dist: numpy>=1.20.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# llama-index-vector-stores-ngt

LlamaIndex vector store integration for [NGT](https://github.com/NGT-labs/NGT) (Neighborhood Graph and Tree).

## Installation

```bash
pip install llama-index-vector-stores-ngt
```

## Parameters

`NGTVectorStore` accepts the following parameters:

- `index_path`: Directory path where NGT persists its index.
- `dimension`: Dimensionality of the vectors to be stored.
- `distance_type`: Distance function. Default: `"L2"`.
  - Available values: `"L1"`, `"L2"`, `"Normalized L2"`, `"Angle"`, `"Normalized Angle"`, `"Cosine"`, `"Normalized Cosine"`, `"Hamming"`, `"Jaccard"`, `"Inner Product"`.
- `edge_size_for_creation`: Number of edges used when building the graph. Default: `10`.
- `edge_size_for_search`: Number of edges explored during search. Default: `40`.
- `epsilon`: Exploration range for approximate search. Larger values are more accurate but slower. Default: `0.1`.

## Usage

```python
from llama_index.core import VectorStoreIndex, StorageContext
from llama_index.core.schema import TextNode
from llama_index.vector_stores.ngt import NGTVectorStore

vector_store = NGTVectorStore(
    index_path="ngt_index",
    dimension=128,
    distance_type="L2",
)

storage_context = StorageContext.from_defaults(vector_store=vector_store)

nodes = [
    TextNode(text="apple is red and sweet"),
    TextNode(text="banana is yellow and sweet"),
]

index = VectorStoreIndex(nodes, storage_context=storage_context)
retriever = index.as_retriever(similarity_top_k=2)
results = retriever.retrieve("yellow fruit")

for node in results:
    print(node.score, node.text)
```

## Query options

- `similarity_top_k`: Number of nearest neighbors to retrieve. Pass it to `as_retriever()` or `as_query_engine()`.
- `epsilon`: Override the exploration range for a single query. Set `vector_store.epsilon` before querying, or pass `epsilon` directly to `vector_store.query()`.
- `edge_size`: Override the search graph exploration size. Set `vector_store.edge_size_for_search` before querying, or pass `edge_size` directly to `vector_store.query()`.

## Persistence

Call `persist()` before exiting to save both the NGT index and LlamaIndex metadata.

```python
vector_store.persist(persist_dir="ngt_index_persisted")
```

Later, or in another process, reopen the persisted index:

```python
vector_store = NGTVectorStore(
    index_path="ngt_index_persisted",
    dimension=128,
    distance_type="L2",
)

storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex([], storage_context=storage_context)

results = index.as_retriever(similarity_top_k=2).retrieve("yellow fruit")
```

Use `persist_dir=""` to save into the original `index_path` instead.

## Notes

- NGT stores only vectors and integer IDs. Text and metadata are kept by the wrapper and serialised alongside the NGT index.
- Metadata filtering is not supported by NGT itself. If you need it, pre-filter IDs on the Python side or combine with another metadata store.
