Metadata-Version: 2.4
Name: llama-index-vector-stores-shannonbase
Version: 0.1.0
Summary: LlamaIndex VectorStore for MySQL 9's native VECTOR type — works with ShannonBase, self-hosted MySQL, and MySQL HeatWave.
Project-URL: Homepage, https://github.com/apoorva-01/llama-index-vector-stores-shannonbase
Project-URL: Issues, https://github.com/apoorva-01/llama-index-vector-stores-shannonbase/issues
Author: Apoorva Verma
License: MIT
License-File: LICENSE
Keywords: heatwave,llama-index,llamaindex,mysql,rag,shannonbase,vector-search,vectorstore
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database
Requires-Python: >=3.9
Requires-Dist: llama-index-core>=0.11
Provides-Extra: dev
Requires-Dist: llama-index-core>=0.11; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: mysql-connector-python>=8.3; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: mysql
Requires-Dist: mysql-connector-python>=8.3; extra == 'mysql'
Description-Content-Type: text/markdown

# llama-index-vector-stores-shannonbase

A [LlamaIndex](https://docs.llamaindex.ai) `VectorStore` backed by MySQL 9's native
`VECTOR` type. If your data already lives in MySQL, you can do retrieval without
standing up a separate vector database.

It works against the three things that share the same `VECTOR` / `STRING_TO_VECTOR`
/ `DISTANCE` surface: [ShannonBase](https://github.com/Shannon-Data/ShannonBase)
(open-source "MySQL for AI"), self-hosted MySQL 9, and MySQL HeatWave.

This is the LlamaIndex sibling of
[langchain-shannonbase](https://pypi.org/project/langchain-shannonbase/). Same
storage engine underneath, wired to LlamaIndex's node and query model so it drops
into a LlamaIndex pipeline instead of a LangChain one.

## Install

```bash
pip install "llama-index-vector-stores-shannonbase[mysql]"
```

Leave off `[mysql]` if you only want the offline in-memory backend for tests.

## Usage

```python
from llama_index.core import VectorStoreIndex, StorageContext
from llama_index.core.schema import TextNode
from llama_index.vector_stores.shannonbase import ShannonBaseVectorStore

store = ShannonBaseVectorStore(
    table="documents",
    host="127.0.0.1", port=3306, user="root", password="", database="rag",
)

# with an index and your embed model of choice
storage = StorageContext.from_defaults(vector_store=store)
index = VectorStoreIndex.from_documents(documents, storage_context=storage)
retriever = index.as_retriever(similarity_top_k=3)
retriever.retrieve("what's the return policy?")
```

The table is created on the first write, with an `embedding VECTOR(n)` column sized
to your embedding model, and a `FULLTEXT` index on the text column for hybrid search.

## What's supported

- `add`, `delete(ref_doc_id)`, and `query`
- Query modes: `DEFAULT` (vector), `MMR` (diverse results), and `HYBRID`
  (vector + MySQL `FULLTEXT` keyword matching, fused by reciprocal rank)
- Metadata filters: `EQ`, `NE`, `GT`, `GTE`, `LT`, `LTE`, `IN`, `NIN`
  (combined with `AND`; `OR` and nested filters aren't supported yet)
- cosine (default), dot, and euclidean metrics via `metric=...`

For very large tables there's the same approximate IVF index as the LangChain
package, reachable through the underlying store (`store.client`).

## Notes on scale

By default search is an exact `DISTANCE` scan (100% recall), which is fine into the
low millions of vectors. On MySQL HeatWave you get its automatic HNSW vector index
for free on these queries. On ShannonBase or self-hosted MySQL, build the app-side
IVF index for approximate search at scale.

## Backend is shared with langchain-shannonbase

The `_sql`, `_store`, `_filter`, and `_ivf` modules are copied verbatim from
langchain-shannonbase so both packages behave identically at the storage layer.
`scripts/check_backend_sync.py` fails if they drift.

## License

MIT
