langchain-shannonbase 0.1.0__tar.gz

langchain_shannonbase-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

langchain_shannonbase-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,17 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

langchain_shannonbase-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+src/*.egg-info/
+.pytest_cache/
+.env
+.env.*
+
+# internal planning docs — never track
+TODO.md
+docs/DEVELOPMENT.md

langchain_shannonbase-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+- Initial release.
+- `ShannonBaseVectorStore` implementing LangChain's VectorStore interface on
+  MySQL 9's native VECTOR type (ShannonBase / MySQL 9 / HeatWave).
+- add_texts, similarity_search(_with_score / _by_vector), get_by_ids, delete, from_texts.
+- cosine / dot / euclidean metrics.
+- Offline InMemoryStore for deterministic tests; gated live integration test.
+- Passes LangChain's standard VectorStore integration suite (langchain-tests),
+  run offline against the in-memory backend.

langchain_shannonbase-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apoorva Verma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langchain_shannonbase-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: langchain-shannonbase
+Version: 0.1.0
+Summary: LangChain 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/langchain-shannonbase
+Project-URL: Issues, https://github.com/apoorva-01/langchain-shannonbase/issues
+Author: Apoorva Verma
+License: MIT
+License-File: LICENSE
+Keywords: embeddings,heatwave,langchain,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: langchain-core>=0.3
+Provides-Extra: dev
+Requires-Dist: langchain-tests>=0.3; extra == 'dev'
+Requires-Dist: mysql-connector-python>=8.3; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; 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
+
+# langchain-shannonbase
+
+A [LangChain](https://python.langchain.com) `VectorStore` for **MySQL 9's native
+`VECTOR` type** — so you can do RAG on a database you already run.
+
+Works with **[ShannonBase](https://github.com/Shannon-Data/ShannonBase)** (the
+open-source MySQL-for-AI), **self-hosted MySQL 9**, and **MySQL HeatWave** — they
+all share the same `VECTOR` / `STRING_TO_VECTOR` / `DISTANCE` surface.
+
+## Why this exists
+
+If your data already lives in MySQL, your options for LangChain vector search were
+thin: the only MySQL `VectorStore` is locked to Google Cloud SQL, and ShannonBase's
+LangChain integration was on its wishlist but unbuilt. This fills that gap — a
+plain, self-hostable adapter that plugs MySQL 9 into the LangChain ecosystem, no
+separate vector database required.
+
+## Install
+
+```bash
+pip install "langchain-shannonbase[mysql]"
+```
+
+## Use
+
+```python
+from langchain_openai import OpenAIEmbeddings
+from langchain_shannonbase import ShannonBaseVectorStore
+
+store = ShannonBaseVectorStore(
+    embedding=OpenAIEmbeddings(model="text-embedding-3-small"),
+    table="documents",
+    host="127.0.0.1", port=3306, user="root", password="", database="rag",
+)
+
+store.add_texts(
+    ["Refunds are accepted within 30 days.", "Free shipping over $50."],
+    metadatas=[{"topic": "refunds"}, {"topic": "shipping"}],
+)
+
+# It's a normal LangChain vector store — use it directly or as a retriever:
+docs = store.similarity_search("return policy?", k=2)
+retriever = store.as_retriever(search_kwargs={"k": 3})
+```
+
+Because it implements LangChain's `VectorStore` interface, it drops into any
+LangChain chain, retriever, or RAG pipeline unchanged.
+
+## How it works
+
+Under the hood it uses MySQL 9's native vector features — no extensions:
+
+```sql
+CREATE TABLE documents (
+  id VARCHAR(36) PRIMARY KEY,
+  content TEXT, metadata JSON,
+  embedding VECTOR(1536)
+);
+-- inserts go through STRING_TO_VECTOR('[...]')
+-- search: ORDER BY DISTANCE(embedding, STRING_TO_VECTOR('[...]'), 'COSINE')
+```
+
+Similarity search reads back the nearest rows by cosine distance and returns them
+as LangChain `Document`s with a score (`1 - distance`).
+
+## API
+
+| Method | Does |
+|--------|------|
+| `add_texts(texts, metadatas, ids)` | embed + upsert, returns ids |
+| `similarity_search(query, k)` | top-k `Document`s |
+| `similarity_search_with_score(query, k)` | with cosine similarity scores |
+| `similarity_search_by_vector(embedding, k)` | search with a raw vector |
+| `delete(ids)` | remove by id |
+| `from_texts(texts, embedding, ...)` | build a store in one call |
+| `metric=` | `"cosine"` (default), `"dot"`, `"euclidean"` |
+
+## Testing
+
+The core logic is unit-tested offline via an in-memory backend (no database
+needed — `pytest`). A live round-trip test runs against a real instance when you
+set the connection env vars:
+
+```bash
+export SB_HOST=127.0.0.1 SB_USER=root SB_PASSWORD=... SB_DATABASE=test
+pytest tests/test_integration.py
+```
+
+> Local dev tip: run [ShannonBase](https://github.com/Shannon-Data/ShannonBase) to
+> get MySQL-9 vector features without a HeatWave subscription.
+
+## Requirements
+
+- Python 3.9+
+- A MySQL-9-compatible database with the `VECTOR` type (ShannonBase, MySQL 9, or
+  HeatWave)
+- `mysql-connector-python` (installed via the `[mysql]` extra)
+
+## License
+
+MIT © Apoorva Verma

langchain_shannonbase-0.1.0/README.md

@@ -0,0 +1,101 @@
+# langchain-shannonbase
+
+A [LangChain](https://python.langchain.com) `VectorStore` for **MySQL 9's native
+`VECTOR` type** — so you can do RAG on a database you already run.
+
+Works with **[ShannonBase](https://github.com/Shannon-Data/ShannonBase)** (the
+open-source MySQL-for-AI), **self-hosted MySQL 9**, and **MySQL HeatWave** — they
+all share the same `VECTOR` / `STRING_TO_VECTOR` / `DISTANCE` surface.
+
+## Why this exists
+
+If your data already lives in MySQL, your options for LangChain vector search were
+thin: the only MySQL `VectorStore` is locked to Google Cloud SQL, and ShannonBase's
+LangChain integration was on its wishlist but unbuilt. This fills that gap — a
+plain, self-hostable adapter that plugs MySQL 9 into the LangChain ecosystem, no
+separate vector database required.
+
+## Install
+
+```bash
+pip install "langchain-shannonbase[mysql]"
+```
+
+## Use
+
+```python
+from langchain_openai import OpenAIEmbeddings
+from langchain_shannonbase import ShannonBaseVectorStore
+
+store = ShannonBaseVectorStore(
+    embedding=OpenAIEmbeddings(model="text-embedding-3-small"),
+    table="documents",
+    host="127.0.0.1", port=3306, user="root", password="", database="rag",
+)
+
+store.add_texts(
+    ["Refunds are accepted within 30 days.", "Free shipping over $50."],
+    metadatas=[{"topic": "refunds"}, {"topic": "shipping"}],
+)
+
+# It's a normal LangChain vector store — use it directly or as a retriever:
+docs = store.similarity_search("return policy?", k=2)
+retriever = store.as_retriever(search_kwargs={"k": 3})
+```
+
+Because it implements LangChain's `VectorStore` interface, it drops into any
+LangChain chain, retriever, or RAG pipeline unchanged.
+
+## How it works
+
+Under the hood it uses MySQL 9's native vector features — no extensions:
+
+```sql
+CREATE TABLE documents (
+  id VARCHAR(36) PRIMARY KEY,
+  content TEXT, metadata JSON,
+  embedding VECTOR(1536)
+);
+-- inserts go through STRING_TO_VECTOR('[...]')
+-- search: ORDER BY DISTANCE(embedding, STRING_TO_VECTOR('[...]'), 'COSINE')
+```
+
+Similarity search reads back the nearest rows by cosine distance and returns them
+as LangChain `Document`s with a score (`1 - distance`).
+
+## API
+
+| Method | Does |
+|--------|------|
+| `add_texts(texts, metadatas, ids)` | embed + upsert, returns ids |
+| `similarity_search(query, k)` | top-k `Document`s |
+| `similarity_search_with_score(query, k)` | with cosine similarity scores |
+| `similarity_search_by_vector(embedding, k)` | search with a raw vector |
+| `delete(ids)` | remove by id |
+| `from_texts(texts, embedding, ...)` | build a store in one call |
+| `metric=` | `"cosine"` (default), `"dot"`, `"euclidean"` |
+
+## Testing
+
+The core logic is unit-tested offline via an in-memory backend (no database
+needed — `pytest`). A live round-trip test runs against a real instance when you
+set the connection env vars:
+
+```bash
+export SB_HOST=127.0.0.1 SB_USER=root SB_PASSWORD=... SB_DATABASE=test
+pytest tests/test_integration.py
+```
+
+> Local dev tip: run [ShannonBase](https://github.com/Shannon-Data/ShannonBase) to
+> get MySQL-9 vector features without a HeatWave subscription.
+
+## Requirements
+
+- Python 3.9+
+- A MySQL-9-compatible database with the `VECTOR` type (ShannonBase, MySQL 9, or
+  HeatWave)
+- `mysql-connector-python` (installed via the `[mysql]` extra)
+
+## License
+
+MIT © Apoorva Verma

langchain_shannonbase-0.1.0/examples/basic.py

@@ -0,0 +1,34 @@
+"""Minimal RAG-style usage against a real ShannonBase / MySQL 9 / HeatWave DB.
+
+    pip install 'langchain-shannonbase[mysql]' langchain-openai
+    export OPENAI_API_KEY=...
+    python examples/basic.py
+"""
+
+from langchain_openai import OpenAIEmbeddings
+
+from langchain_shannonbase import ShannonBaseVectorStore
+
+store = ShannonBaseVectorStore(
+    embedding=OpenAIEmbeddings(model="text-embedding-3-small"),
+    table="documents",
+    host="127.0.0.1",
+    port=3306,
+    user="root",
+    password="",
+    database="rag",
+)
+
+store.add_texts(
+    [
+        "Our refund policy allows returns within 30 days of purchase.",
+        "Support is available Monday to Friday, 9am to 6pm.",
+        "Free shipping on orders over $50.",
+    ],
+    metadatas=[{"topic": "refunds"}, {"topic": "support"}, {"topic": "shipping"}],
+)
+
+# Use it like any LangChain vector store:
+retriever = store.as_retriever(search_kwargs={"k": 2})
+for doc in retriever.invoke("how long do I have to return something?"):
+    print(f"- {doc.page_content}  ({doc.metadata})")

langchain_shannonbase-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-shannonbase"
+version = "0.1.0"
+description = "LangChain VectorStore for MySQL 9's native VECTOR type — works with ShannonBase, self-hosted MySQL, and MySQL HeatWave."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Apoorva Verma" }]
+keywords = ["langchain", "vectorstore", "mysql", "shannonbase", "heatwave", "rag", "vector-search", "embeddings"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Database",
+]
+dependencies = [
+    "langchain-core>=0.3",
+]
+
+[project.optional-dependencies]
+mysql = ["mysql-connector-python>=8.3"]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.23", "mysql-connector-python>=8.3", "langchain-tests>=0.3"]
+
+[project.urls]
+Homepage = "https://github.com/apoorva-01/langchain-shannonbase"
+Issues = "https://github.com/apoorva-01/langchain-shannonbase/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_shannonbase"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

langchain_shannonbase-0.1.0/src/langchain_shannonbase/__init__.py

@@ -0,0 +1,8 @@
+"""langchain-shannonbase — a LangChain VectorStore for MySQL 9's VECTOR type."""
+
+__version__ = "0.1.0"
+
+from ._store import InMemoryStore, MySQLStore
+from .vectorstores import ShannonBaseVectorStore
+
+__all__ = ["ShannonBaseVectorStore", "MySQLStore", "InMemoryStore", "__version__"]

langchain_shannonbase-0.1.0/src/langchain_shannonbase/_sql.py

@@ -0,0 +1,67 @@
+"""SQL for MySQL 9's native VECTOR type (ShannonBase / MySQL / HeatWave).
+
+Kept as pure string builders so they can be unit-tested without a database.
+Embeddings are passed to MySQL as a JSON array string via STRING_TO_VECTOR(),
+and cosine distance comes from the native DISTANCE(a, b, 'COSINE') function.
+similarity = 1 - distance.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import List
+
+# Distance metric -> MySQL DISTANCE() metric name.
+_METRICS = {"cosine": "COSINE", "dot": "DOT", "euclidean": "EUCLIDEAN"}
+
+
+def vector_literal(embedding: List[float]) -> str:
+    """Serialize a vector to the JSON-array string STRING_TO_VECTOR expects."""
+    return json.dumps([float(x) for x in embedding])
+
+
+def create_table_sql(table: str, dim: int) -> str:
+    return (
+        f"CREATE TABLE IF NOT EXISTS `{table}` ("
+        "  id VARCHAR(36) PRIMARY KEY,"
+        "  content TEXT,"
+        "  metadata JSON,"
+        f"  embedding VECTOR({dim})"
+        ")"
+    )
+
+
+def insert_sql(table: str) -> str:
+    """Upsert one row. Embedding bind param is wrapped in STRING_TO_VECTOR()."""
+    return (
+        f"INSERT INTO `{table}` (id, content, metadata, embedding) "
+        "VALUES (%s, %s, %s, STRING_TO_VECTOR(%s)) "
+        "AS new ON DUPLICATE KEY UPDATE "
+        "content = new.content, metadata = new.metadata, embedding = new.embedding"
+    )
+
+
+def search_sql(table: str, metric: str = "cosine") -> str:
+    m = _METRICS.get(metric)
+    if m is None:
+        raise ValueError(f"unknown metric {metric!r}; use one of {list(_METRICS)}")
+    return (
+        "SELECT id, content, metadata, "
+        f"DISTANCE(embedding, STRING_TO_VECTOR(%s), '{m}') AS dist "
+        f"FROM `{table}` ORDER BY dist ASC LIMIT %s"
+    )
+
+
+def delete_sql(table: str, n_ids: int) -> str:
+    placeholders = ", ".join(["%s"] * n_ids)
+    return f"DELETE FROM `{table}` WHERE id IN ({placeholders})"
+
+
+def select_by_ids_sql(table: str, n_ids: int) -> str:
+    placeholders = ", ".join(["%s"] * n_ids)
+    return f"SELECT id, content, metadata FROM `{table}` WHERE id IN ({placeholders})"
+
+
+def distance_to_score(distance: float) -> float:
+    """Convert a cosine distance to a [0, 1]-ish similarity score."""
+    return 1.0 - float(distance)

langchain_shannonbase-0.1.0/src/langchain_shannonbase/_store.py

@@ -0,0 +1,150 @@
+"""Storage backends behind the vector store.
+
+MySQLStore talks to a real ShannonBase / MySQL 9 / HeatWave instance. InMemoryStore
+emulates the same behavior in pure Python (cosine over stored vectors) so the
+vector store can be fully unit-tested offline — same pattern that keeps the tests
+deterministic and CI-friendly without provisioning a database.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass
+from typing import List, Optional, Protocol, Tuple
+
+from . import _sql
+
+
+@dataclass
+class Row:
+    id: str
+    content: str
+    metadata: dict
+    distance: float
+
+
+class Store(Protocol):
+    def ensure_table(self, dim: int) -> None: ...
+    def upsert(self, rows: List[Tuple[str, str, dict, List[float]]]) -> None: ...
+    def search(self, embedding: List[float], k: int, metric: str) -> List[Row]: ...
+    def get(self, ids: List[str]) -> List[Row]: ...
+    def delete(self, ids: List[str]) -> None: ...
+
+
+class MySQLStore:
+    """Real backend. Requires: pip install 'langchain-shannonbase[mysql]'."""
+
+    def __init__(self, table: str, **connection_kwargs):
+        import mysql.connector  # noqa: F401  (lazy; validates the extra is installed)
+        self.table = table
+        self._conn_kwargs = connection_kwargs
+
+    def _connect(self):
+        import mysql.connector
+        return mysql.connector.connect(**self._conn_kwargs)
+
+    def ensure_table(self, dim: int) -> None:
+        conn = self._connect()
+        try:
+            conn.cursor().execute(_sql.create_table_sql(self.table, dim))
+            conn.commit()
+        finally:
+            conn.close()
+
+    def upsert(self, rows):
+        conn = self._connect()
+        try:
+            cur = conn.cursor()
+            stmt = _sql.insert_sql(self.table)
+            cur.executemany(
+                stmt,
+                [(rid, content, json.dumps(meta), _sql.vector_literal(emb))
+                 for rid, content, meta, emb in rows],
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def search(self, embedding, k, metric):
+        conn = self._connect()
+        try:
+            cur = conn.cursor()
+            cur.execute(_sql.search_sql(self.table, metric),
+                        (_sql.vector_literal(embedding), k))
+            out = []
+            for rid, content, meta, dist in cur.fetchall():
+                md = meta if isinstance(meta, dict) else json.loads(meta or "{}")
+                out.append(Row(rid, content, md, float(dist)))
+            return out
+        finally:
+            conn.close()
+
+    def get(self, ids):
+        if not ids:
+            return []
+        conn = self._connect()
+        try:
+            cur = conn.cursor()
+            cur.execute(_sql.select_by_ids_sql(self.table, len(ids)), tuple(ids))
+            out = []
+            for rid, content, meta in cur.fetchall():
+                md = meta if isinstance(meta, dict) else json.loads(meta or "{}")
+                out.append(Row(rid, content, md, 0.0))
+            return out
+        finally:
+            conn.close()
+
+    def delete(self, ids):
+        if not ids:
+            return
+        conn = self._connect()
+        try:
+            cur = conn.cursor()
+            cur.execute(_sql.delete_sql(self.table, len(ids)), tuple(ids))
+            conn.commit()
+        finally:
+            conn.close()
+
+
+class InMemoryStore:
+    """Deterministic offline backend that mirrors MySQLStore's cosine behavior."""
+
+    def __init__(self):
+        self._rows: dict[str, Tuple[str, dict, List[float]]] = {}
+
+    def ensure_table(self, dim: int) -> None:
+        pass
+
+    def upsert(self, rows):
+        for rid, content, meta, emb in rows:
+            self._rows[rid] = (content, dict(meta or {}), list(emb))
+
+    def search(self, embedding, k, metric):
+        scored = []
+        for rid, (content, meta, emb) in self._rows.items():
+            scored.append(Row(rid, content, meta, _cosine_distance(embedding, emb)))
+        scored.sort(key=lambda r: r.distance)
+        return scored[:k]
+
+    def get(self, ids):
+        out = []
+        for i in ids:
+            row = self._rows.get(i)
+            if row is not None:
+                content, meta, _ = row
+                out.append(Row(i, content, dict(meta), 0.0))
+        return out
+
+    def delete(self, ids):
+        for i in ids:
+            self._rows.pop(i, None)
+
+
+def _cosine_distance(a: List[float], b: List[float]) -> float:
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    if na == 0 or nb == 0:
+        return 1.0
+    return 1.0 - dot / (na * nb)

langchain_shannonbase-0.1.0/src/langchain_shannonbase/vectorstores.py

@@ -0,0 +1,132 @@
+"""ShannonBaseVectorStore — a LangChain VectorStore backed by MySQL 9's native
+VECTOR type. Works with ShannonBase, self-hosted MySQL 9, and MySQL HeatWave,
+which all share the same VECTOR / STRING_TO_VECTOR / DISTANCE surface.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, Iterable, List, Optional, Tuple
+
+from langchain_core.documents import Document
+from langchain_core.embeddings import Embeddings
+from langchain_core.vectorstores import VectorStore
+
+from ._store import InMemoryStore, MySQLStore, Store
+
+
+class ShannonBaseVectorStore(VectorStore):
+    """Store and query embeddings in a MySQL-9-compatible database.
+
+    Typical use points it at a real database:
+
+        from langchain_shannonbase import ShannonBaseVectorStore
+        store = ShannonBaseVectorStore(
+            embedding=my_embeddings,
+            table="documents",
+            host="127.0.0.1", user="root", password="...", database="rag",
+        )
+        store.add_texts(["hello world"], metadatas=[{"src": "demo"}])
+        docs = store.similarity_search("greeting", k=3)
+
+    Pass `store=InMemoryStore()` instead of connection kwargs for offline tests.
+    """
+
+    def __init__(
+        self,
+        embedding: Embeddings,
+        table: str = "langchain_vectors",
+        metric: str = "cosine",
+        store: Optional[Store] = None,
+        **connection_kwargs: Any,
+    ):
+        self._embedding = embedding
+        self.table = table
+        self.metric = metric
+        self._store: Store = store if store is not None else MySQLStore(table, **connection_kwargs)
+        self._dim: Optional[int] = None
+
+    @property
+    def embeddings(self) -> Embeddings:
+        return self._embedding
+
+    def _ensure_dim(self, dim: int) -> None:
+        if self._dim is None:
+            self._dim = dim
+            self._store.ensure_table(dim)
+
+    def add_texts(
+        self,
+        texts: Iterable[str],
+        metadatas: Optional[List[dict]] = None,
+        ids: Optional[List[str]] = None,
+        **kwargs: Any,
+    ) -> List[str]:
+        texts = list(texts)
+        if not texts:
+            return []
+        vectors = self._embedding.embed_documents(texts)
+        self._ensure_dim(len(vectors[0]))
+        metadatas = metadatas or [{} for _ in texts]
+        ids = ids or [str(uuid.uuid4()) for _ in texts]
+        rows: List[Tuple[str, str, dict, List[float]]] = [
+            (ids[i], texts[i], metadatas[i], vectors[i]) for i in range(len(texts))
+        ]
+        self._store.upsert(rows)
+        return ids
+
+    def similarity_search(self, query: str, k: int = 4, **kwargs: Any) -> List[Document]:
+        return [doc for doc, _ in self.similarity_search_with_score(query, k, **kwargs)]
+
+    def similarity_search_with_score(
+        self, query: str, k: int = 4, **kwargs: Any
+    ) -> List[Tuple[Document, float]]:
+        vector = self._embedding.embed_query(query)
+        return self.similarity_search_by_vector_with_score(vector, k, **kwargs)
+
+    def similarity_search_by_vector(
+        self, embedding: List[float], k: int = 4, **kwargs: Any
+    ) -> List[Document]:
+        return [doc for doc, _ in self.similarity_search_by_vector_with_score(embedding, k)]
+
+    def similarity_search_by_vector_with_score(
+        self, embedding: List[float], k: int = 4, **kwargs: Any
+    ) -> List[Tuple[Document, float]]:
+        rows = self._store.search(embedding, k, self.metric)
+        # DISTANCE is smaller-is-closer; expose it as a score (1 - distance).
+        return [
+            (Document(id=r.id, page_content=r.content, metadata=dict(r.metadata)),
+             1.0 - r.distance)
+            for r in rows
+        ]
+
+    def get_by_ids(self, ids: Iterable[str]) -> List[Document]:
+        ids = list(ids)
+        found = {r.id: r for r in self._store.get(ids)}
+        return [
+            Document(id=i, page_content=found[i].content, metadata=dict(found[i].metadata))
+            for i in ids
+            if i in found
+        ]
+
+    def delete(self, ids: Optional[List[str]] = None, **kwargs: Any) -> Optional[bool]:
+        if not ids:
+            return False
+        self._store.delete(ids)
+        return True
+
+    @classmethod
+    def from_texts(
+        cls,
+        texts: List[str],
+        embedding: Embeddings,
+        metadatas: Optional[List[dict]] = None,
+        table: str = "langchain_vectors",
+        metric: str = "cosine",
+        store: Optional[Store] = None,
+        ids: Optional[List[str]] = None,
+        **connection_kwargs: Any,
+    ) -> "ShannonBaseVectorStore":
+        vs = cls(embedding=embedding, table=table, metric=metric, store=store, **connection_kwargs)
+        vs.add_texts(texts, metadatas=metadatas, ids=ids)
+        return vs

langchain_shannonbase-0.1.0/tests/test_integration.py

@@ -0,0 +1,57 @@
+"""Live integration test against a real MySQL 9 / ShannonBase / HeatWave instance.
+
+Skipped unless SHANNONBASE_TEST_DSN-style env vars are set, so CI stays green
+without provisioning a database. To run locally against a ShannonBase or MySQL 9:
+
+    export SB_HOST=127.0.0.1 SB_PORT=3306 SB_USER=root SB_PASSWORD=... SB_DATABASE=test
+    pytest tests/test_integration.py -v
+"""
+
+import os
+
+import pytest
+
+pytestmark = pytest.mark.skipif(
+    not os.environ.get("SB_HOST"),
+    reason="set SB_HOST/SB_USER/SB_PASSWORD/SB_DATABASE to run live DB tests",
+)
+
+
+def _conn_kwargs():
+    return dict(
+        host=os.environ["SB_HOST"],
+        port=int(os.environ.get("SB_PORT", 3306)),
+        user=os.environ["SB_USER"],
+        password=os.environ.get("SB_PASSWORD", ""),
+        database=os.environ["SB_DATABASE"],
+    )
+
+
+def test_roundtrip_against_real_db():
+    import hashlib
+    import re
+
+    from langchain_core.embeddings import Embeddings
+
+    from langchain_shannonbase import ShannonBaseVectorStore
+
+    tok = re.compile(r"[a-z0-9]+")
+
+    class E(Embeddings):
+        def _e(self, t):
+            v = [0.0] * 64
+            for w in tok.findall(t.lower()):
+                v[int(hashlib.md5(w.encode()).hexdigest(), 16) % 64] += 1.0
+            return v
+
+        def embed_documents(self, x):
+            return [self._e(t) for t in x]
+
+        def embed_query(self, t):
+            return self._e(t)
+
+    vs = ShannonBaseVectorStore(embedding=E(), table="lc_sb_itest", **_conn_kwargs())
+    vs.add_texts(["reset my password", "cancel my subscription"], ids=["a", "b"])
+    docs = vs.similarity_search("how do I reset my password", k=1)
+    assert docs[0].page_content == "reset my password"
+    vs.delete(["a", "b"])

langchain_shannonbase-0.1.0/tests/test_sql.py

@@ -0,0 +1,40 @@
+import json
+
+import pytest
+
+from langchain_shannonbase import _sql
+
+
+def test_vector_literal_is_json_array():
+    assert json.loads(_sql.vector_literal([1, 2.5, 3])) == [1.0, 2.5, 3.0]
+
+
+def test_create_table_has_vector_dim():
+    sql = _sql.create_table_sql("docs", 384)
+    assert "VECTOR(384)" in sql
+    assert "`docs`" in sql
+
+
+def test_insert_wraps_embedding_in_string_to_vector():
+    assert "STRING_TO_VECTOR(%s)" in _sql.insert_sql("docs")
+    assert "ON DUPLICATE KEY UPDATE" in _sql.insert_sql("docs")
+
+
+def test_search_uses_distance_and_metric():
+    sql = _sql.search_sql("docs", "cosine")
+    assert "DISTANCE(embedding, STRING_TO_VECTOR(%s), 'COSINE')" in sql
+    assert "ORDER BY dist ASC LIMIT %s" in sql
+
+
+def test_search_rejects_unknown_metric():
+    with pytest.raises(ValueError):
+        _sql.search_sql("docs", "nope")
+
+
+def test_delete_has_one_placeholder_per_id():
+    assert _sql.delete_sql("docs", 3).count("%s") == 3
+
+
+def test_distance_to_score():
+    assert _sql.distance_to_score(0.0) == 1.0
+    assert _sql.distance_to_score(0.25) == 0.75

langchain_shannonbase-0.1.0/tests/test_standard.py

@@ -0,0 +1,18 @@
+"""LangChain's standard VectorStore integration suite, run offline.
+
+The suite exercises add/get_by_ids/delete/search against a real store. We point it
+at InMemoryStore so it runs in CI without provisioning a database — same behavior
+as the MySQL backend, just in-process.
+"""
+
+import pytest
+from langchain_core.vectorstores import VectorStore
+from langchain_tests.integration_tests import VectorStoreIntegrationTests
+
+from langchain_shannonbase import InMemoryStore, ShannonBaseVectorStore
+
+
+class TestShannonBaseVectorStore(VectorStoreIntegrationTests):
+    @pytest.fixture()
+    def vectorstore(self) -> VectorStore:
+        return ShannonBaseVectorStore(embedding=self.get_embeddings(), store=InMemoryStore())

langchain_shannonbase-0.1.0/tests/test_vectorstore.py

@@ -0,0 +1,81 @@
+"""End-to-end tests of ShannonBaseVectorStore against the offline InMemoryStore.
+
+A deterministic bag-of-words embedder stands in for a real embedding model so the
+semantics (paraphrases rank closer than unrelated text) are reproducible offline.
+"""
+
+import hashlib
+import re
+
+from langchain_core.embeddings import Embeddings
+
+from langchain_shannonbase import InMemoryStore, ShannonBaseVectorStore
+
+_TOKEN = re.compile(r"[a-z0-9]+")
+
+
+class HashEmbeddings(Embeddings):
+    dim = 64
+
+    def _embed(self, text: str):
+        vec = [0.0] * self.dim
+        for tok in _TOKEN.findall(text.lower()):
+            vec[int(hashlib.md5(tok.encode()).hexdigest(), 16) % self.dim] += 1.0
+        return vec
+
+    def embed_documents(self, texts):
+        return [self._embed(t) for t in texts]
+
+    def embed_query(self, text):
+        return self._embed(text)
+
+
+def _store():
+    return ShannonBaseVectorStore(embedding=HashEmbeddings(), store=InMemoryStore())
+
+
+def test_add_and_search_returns_relevant_doc():
+    vs = _store()
+    vs.add_texts(
+        ["the cat sat on the mat", "quarterly financial report", "a dog in the park"],
+        metadatas=[{"src": "a"}, {"src": "b"}, {"src": "c"}],
+    )
+    docs = vs.similarity_search("cat on a mat", k=1)
+    assert len(docs) == 1
+    assert "cat" in docs[0].page_content
+    assert docs[0].metadata["src"] == "a"
+
+
+def test_add_texts_returns_ids_and_respects_custom_ids():
+    vs = _store()
+    ids = vs.add_texts(["hello"], ids=["fixed-id"])
+    assert ids == ["fixed-id"]
+
+
+def test_similarity_search_with_score_orders_by_similarity():
+    vs = _store()
+    vs.add_texts(["reset my password", "cancel my subscription"])
+    results = vs.similarity_search_with_score("how do I reset my password", k=2)
+    assert results[0][0].page_content == "reset my password"
+    assert results[0][1] >= results[1][1]  # higher score first
+
+
+def test_k_limits_results():
+    vs = _store()
+    vs.add_texts([f"doc number {i}" for i in range(10)])
+    assert len(vs.similarity_search("doc", k=3)) == 3
+
+
+def test_delete_removes_document():
+    vs = _store()
+    vs.add_texts(["keep me", "delete me"], ids=["keep", "del"])
+    assert vs.delete(["del"]) is True
+    remaining = vs.similarity_search("me", k=10)
+    assert all(d.id != "del" for d in remaining)
+
+
+def test_from_texts_classmethod():
+    vs = ShannonBaseVectorStore.from_texts(
+        ["alpha", "beta"], embedding=HashEmbeddings(), store=InMemoryStore()
+    )
+    assert len(vs.similarity_search("alpha", k=2)) == 2