Metadata-Version: 2.4
Name: llama-index-vector-stores-zeusdb
Version: 0.1.1
Summary: LlamaIndex integration for ZeusDB vector database. Enterprise-grade RAG with high-performance vector search.
Project-URL: Homepage, https://github.com/zeusdb/llama-index-vector-stores-zeusdb
Project-URL: Repository, https://github.com/zeusdb/llama-index-vector-stores-zeusdb
Project-URL: Issues, https://github.com/zeusdb/llama-index-vector-stores-zeusdb/issues
Author-email: ZeusDB <contact@zeusdb.com>
License: MIT
License-File: LICENSE
Keywords: embeddings,hnsw,llama-index,rag,semantic-search,vector-database,zeusdb
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.10
Requires-Dist: llama-index-core>=0.14.4
Requires-Dist: zeusdb>=0.0.8
Provides-Extra: dev
Requires-Dist: black>=25.1; extra == 'dev'
Requires-Dist: codespell[toml]>=2.2.6; extra == 'dev'
Requires-Dist: ipython>=8.10.0; extra == 'dev'
Requires-Dist: jupyter>=1.0.0; extra == 'dev'
Requires-Dist: llama-index-embeddings-openai>=0.5.1; extra == 'dev'
Requires-Dist: llama-index-llms-openai>=0.6.4; extra == 'dev'
Requires-Dist: mypy>=1.17; extra == 'dev'
Requires-Dist: pre-commit>=4.3; extra == 'dev'
Requires-Dist: pylint>=3.3; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.2.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.15; extra == 'dev'
Requires-Dist: pytest>=8.4; extra == 'dev'
Requires-Dist: python-dotenv>=1.1.1; extra == 'dev'
Requires-Dist: ruff>=0.12; extra == 'dev'
Requires-Dist: types-requests>=2.32; extra == 'dev'
Description-Content-Type: text/markdown

# LlamaIndex ZeusDB Integration

ZeusDB vector database integration for LlamaIndex. Connect LlamaIndex's RAG framework with high-performance, enterprise-grade vector database.

## Features

- **Production Ready**: Built for enterprise-scale RAG applications
- **Persistence**: Complete save/load functionality with cross-platform compatibility
- **Advanced Filtering**: Comprehensive metadata filtering with complex operators
- **MMR Support**: Maximal Marginal Relevance for diverse, non-redundant results
- **Quantization**: Product Quantization (PQ) for memory-efficient vector storage
- **Async Support**: Async wrappers for non-blocking operations (`aadd`, `aquery`, `adelete_nodes`)

## Installation

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

## Quick Start

```python
from llama_index.core import VectorStoreIndex, Document, StorageContext
from llama_index.vector_stores.zeusdb import ZeusDBVectorStore
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.llms.openai import OpenAI
from llama_index.core import Settings

# Set up embedding model and LLM
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")
Settings.llm = OpenAI(model="gpt-5")

# Create ZeusDB vector store
vector_store = ZeusDBVectorStore(
    dim=1536,  # OpenAI embedding dimension
    distance="cosine",
    index_type="hnsw"
)

# Create storage context
storage_context = StorageContext.from_defaults(vector_store=vector_store)

# Create documents
documents = [
    Document(text="ZeusDB is a high-performance vector database."),
    Document(text="LlamaIndex provides RAG capabilities."),
    Document(text="Vector search enables semantic similarity.")
]

# Create index and store documents
index = VectorStoreIndex.from_documents(
    documents,
    storage_context=storage_context
)

# Query the index
query_engine = index.as_query_engine()
response = query_engine.query("What is ZeusDB?")
print(response)
```

## Advanced Features

### Persistence

Save and load indexes with complete state preservation:

```python
# Save index to disk
vector_store.save_index("my_index.zdb")

# Load index from disk
loaded_store = ZeusDBVectorStore.load_index("my_index.zdb")
```

### MMR Search

Balance relevance and diversity for comprehensive results:

```python
from llama_index.core.vector_stores.types import VectorStoreQuery

# Query with MMR for diverse results
query_embedding = embed_model.get_text_embedding("your query")
results = vector_store.query(
    VectorStoreQuery(query_embedding=query_embedding, similarity_top_k=5),
    mmr=True,
    fetch_k=20,
    mmr_lambda=0.7  # 0.0=max diversity, 1.0=pure relevance
)

# Note: MMR automatically enables return_vector=True for diversity calculation
# Results contain ids and similarities (nodes=None)
```

### Quantization

Reduce memory usage with Product Quantization:

```python
vector_store = ZeusDBVectorStore(
    dim=1536,
    distance="cosine",
    quantization_config={
        'type': 'pq',
        'subvectors': 8,
        'bits': 8,
        'training_size': 1000,
        'storage_mode': 'quantized_only'
    }
)
```

### Async Operations

Non-blocking operations for web servers and concurrent workflows:

```python
import asyncio

# Async add
node_ids = await vector_store.aadd(nodes)

# Async query
results = await vector_store.aquery(query_obj)

# Async delete
await vector_store.adelete_nodes(node_ids=["id1", "id2"])
```

### Metadata Filtering

Filter results by metadata:

```python
from llama_index.core.vector_stores.types import (
    MetadataFilters,
    FilterOperator,
    FilterCondition
)

# Create metadata filter
filters = MetadataFilters.from_dicts([
    {"key": "category", "value": "tech", "operator": FilterOperator.EQ},
    {"key": "year", "value": 2024, "operator": FilterOperator.GTE}
], condition=FilterCondition.AND)

# Query with filters
results = vector_store.query(
    VectorStoreQuery(
        query_embedding=query_embedding,
        similarity_top_k=5,
        filters=filters
    )
)
```

**Supported operators**: EQ, NE, GT, GTE, LT, LTE, IN, NIN, ANY, ALL, CONTAINS, TEXT_MATCH, TEXT_MATCH_INSENSITIVE

## Configuration

| Parameter | Description | Default |
|-----------|-------------|---------|
| `dim` | Vector dimension | Required |
| `distance` | Distance metric (`cosine`, `l2`, `l1`) | `cosine` |
| `index_type` | Index type (`hnsw`) | `hnsw` |
| `m` | HNSW connectivity parameter | 16 |
| `ef_construction` | HNSW build-time search depth | 200 |
| `expected_size` | Expected number of vectors | 10000 |
| `quantization_config` | PQ quantization settings | None |

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
