singlestore-langchain-core 0.1.0__tar.gz

singlestore_langchain_core-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: singlestore-langchain-core
+Version: 0.1.0
+Summary: Shared SingleStore helpers for langchain-singlestore and langgraph-singlestore
+License: MIT
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.14
+Requires-Dist: singlestoredb (>=1.16.9,<2.0.0)
+Requires-Dist: sqlalchemy (>=2.0.40,<3.0.0)
+Project-URL: Repository, https://github.com/singlestore-labs/langchain-singlestore
+Project-URL: Release Notes, https://github.com/singlestore-labs/langchain-singlestore/releases
+Project-URL: Source Code, https://github.com/singlestore-labs/langchain-singlestore/tree/main/libs/singlestore-langchain-core
+Description-Content-Type: text/markdown
+
+# singlestore-langchain-core
+
+Shared, internal helpers used by the SingleStore integrations for LangChain
+and LangGraph:
+
+- Connection attribute helpers (`set_connector_attributes`,
+  `compute_connector_version`).
+- SingleStore capability enums (`DistanceStrategy`, `FullTextIndexVersion`,
+  `FullTextScoringMode`).
+- Metadata filter DSL (`FilterTypedDict`, `_parse_filter`) shared by vector
+  stores and stores.
+
+This package is not intended to be depended on directly by application code.
+Install one of the higher-level packages instead:
+
+- [`langchain-singlestore`](../langchain-singlestore)
+- [`langgraph-singlestore`](../langgraph-singlestore)
+

singlestore_langchain_core-0.1.0/README.md

@@ -0,0 +1,17 @@
+# singlestore-langchain-core
+
+Shared, internal helpers used by the SingleStore integrations for LangChain
+and LangGraph:
+
+- Connection attribute helpers (`set_connector_attributes`,
+  `compute_connector_version`).
+- SingleStore capability enums (`DistanceStrategy`, `FullTextIndexVersion`,
+  `FullTextScoringMode`).
+- Metadata filter DSL (`FilterTypedDict`, `_parse_filter`) shared by vector
+  stores and stores.
+
+This package is not intended to be depended on directly by application code.
+Install one of the higher-level packages instead:
+
+- [`langchain-singlestore`](../langchain-singlestore)
+- [`langgraph-singlestore`](../langgraph-singlestore)

singlestore_langchain_core-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "singlestore-langchain-core"
+version = "0.1.0"
+description = "Shared SingleStore helpers for langchain-singlestore and langgraph-singlestore"
+authors = []
+readme = "README.md"
+repository = "https://github.com/singlestore-labs/langchain-singlestore"
+license = "MIT"
+packages = [{ include = "singlestore_langchain_core" }]
+
+[tool.poetry.urls]
+"Source Code" = "https://github.com/singlestore-labs/langchain-singlestore/tree/main/libs/singlestore-langchain-core"
+"Release Notes" = "https://github.com/singlestore-labs/langchain-singlestore/releases"
+
+[tool.poetry.dependencies]
+python = ">=3.10,<4.0"
+singlestoredb = "^1.16.9"
+sqlalchemy = "^2.0.40"
+
+[tool.mypy]
+disallow_untyped_defs = "True"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "T201"]
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers --strict-config --durations=5"
+asyncio_mode = "auto"
+
+[tool.poetry.group.test]
+optional = true
+
+[tool.poetry.group.test_integration]
+optional = true
+
+[tool.poetry.group.lint]
+optional = true
+
+[tool.poetry.group.typing]
+optional = true
+
+[tool.poetry.group.test.dependencies]
+pytest = ">=7.4.3,<10.0.0"
+pytest-asyncio = ">=0.23.2,<2.0.0"
+pytest-socket = "^0.7.0"
+
+[tool.poetry.group.test_integration.dependencies]
+docker = "^7.1.0"
+
+[tool.poetry.group.lint.dependencies]
+ruff = "^0.5"
+
+[tool.poetry.group.typing.dependencies]
+mypy = "^1.10"

singlestore_langchain_core-0.1.0/singlestore_langchain_core/__init__.py

@@ -0,0 +1,48 @@
+"""Shared SingleStore helpers used by ``langchain-singlestore`` and
+``langgraph-singlestore``.
+
+This package contains only SingleStore/SQL primitives with no dependency on
+``langchain-core`` or ``langgraph``.  It is intended to be an internal
+implementation detail; direct use by application code is not supported.
+"""
+
+from importlib import metadata
+
+from singlestore_langchain_core._connection import (
+    create_connection_pool,
+)
+from singlestore_langchain_core._filter import (
+    FilterTypedDict,
+    _get_match_param_function,
+    _parse_filter,
+)
+from singlestore_langchain_core._utils import (
+    DEFAULT_CONNECTOR_NAME,
+    DistanceStrategy,
+    FullTextIndexVersion,
+    FullTextScoringMode,
+    compute_connector_version,
+    hash,
+    set_connector_attributes,
+)
+
+try:
+    __version__ = metadata.version(__package__)
+except metadata.PackageNotFoundError:
+    __version__ = ""
+del metadata
+
+__all__ = [
+    "DEFAULT_CONNECTOR_NAME",
+    "DistanceStrategy",
+    "FilterTypedDict",
+    "FullTextIndexVersion",
+    "FullTextScoringMode",
+    "_get_match_param_function",
+    "_parse_filter",
+    "compute_connector_version",
+    "hash",
+    "set_connector_attributes",
+    "create_connection_pool",
+    "__version__",
+]

singlestore_langchain_core-0.1.0/singlestore_langchain_core/_connection.py

@@ -0,0 +1,154 @@
+"""Connection-pool utilities for SingleStore integrations.
+
+Two SQLAlchemy ``Pool`` implementations are provided:
+
+* :class:`SingleConnectionPool` — always hands out the same, caller-owned
+  connection. Useful when the caller manages the connection lifecycle itself
+  (tests, notebooks, a shared long-lived connection).
+* :class:`QueueConnectionPool` — a thin wrapper around
+  :class:`sqlalchemy.pool.QueuePool` that lazily opens
+  :func:`singlestoredb.connect` connections using a stored kwargs mapping.
+
+Use :func:`create_connection_pool` as the single entry point; it picks the
+right implementation based on the arguments the caller supplied.
+"""
+
+from typing import Any, Optional
+
+from singlestoredb.connection import Connection, connect
+from sqlalchemy.pool import Pool, QueuePool
+
+
+class _CallerOwnedConnection:
+    """DBAPI-like proxy over a caller-owned :class:`Connection`.
+
+    Consumers of a pool follow the ``connect()``/``close()`` idiom, but for
+    :class:`SingleConnectionPool` the underlying connection is owned by the
+    caller and must outlive the checkout. This proxy forwards every attribute
+    to the wrapped connection while making ``close()`` a no-op so subsequent
+    checkouts keep working.
+    """
+
+    __slots__ = ("_connection",)
+
+    def __init__(self, connection: Connection) -> None:
+        object.__setattr__(self, "_connection", connection)
+
+    def close(self) -> None:
+        return None
+
+    def __getattr__(self, name: str) -> Any:
+        if name == "_connection":
+            raise AttributeError(name)
+        return getattr(self._connection, name)
+
+    def __enter__(self) -> Connection:
+        return self._connection
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        return None
+
+
+class SingleConnectionPool(Pool):
+    """Pool that returns the same pre-established connection on every call.
+
+    The connection is owned by the caller; this class does not open or close
+    it. Intended for scenarios where a single, long-lived connection is
+    reused across operations. Each :meth:`connect` returns a lightweight
+    proxy so callers may follow the standard ``connect()``/``close()``
+    idiom without tearing down the shared connection.
+    """
+
+    def __init__(self, connection: Connection) -> None:
+        self._connection = connection
+
+    def connect(self) -> Any:  # type: ignore[override]
+        return _CallerOwnedConnection(self._connection)
+
+    def dispose(self) -> None:  # type: ignore[override]
+        # Caller owns the underlying connection; nothing to release here.
+        return None
+
+
+class QueueConnectionPool(Pool):
+    """Lazy, size-bounded pool backed by :class:`sqlalchemy.pool.QueuePool`.
+
+    Connections are opened on demand via :func:`singlestoredb.connect` using
+    ``connection_kwargs``. See the ``singlestoredb.connect`` documentation for
+    the full list of accepted keyword arguments (``host``, ``user``,
+    ``password``, ``port``, ``database``, TLS options, etc.).
+
+    Args:
+        pool_size: Number of persistent connections kept in the pool.
+        max_overflow: Additional connections that may be opened beyond
+            ``pool_size`` under load.
+        timeout: Seconds to wait for a free connection before raising.
+        connection_kwargs: Keyword arguments forwarded to
+            :func:`singlestoredb.connect` when a new connection is opened.
+    """
+
+    def __init__(
+        self,
+        pool_size: int = 5,
+        max_overflow: int = 10,
+        timeout: float = 30,
+        connection_kwargs: Optional[dict] = None,
+    ) -> None:
+        self._pool_size = pool_size
+        self._max_overflow = max_overflow
+        self._timeout = timeout
+        self._connection_kwargs: dict = dict(connection_kwargs or {})
+        self._pool = QueuePool(
+            self._open_connection,
+            pool_size=self._pool_size,
+            max_overflow=self._max_overflow,
+            timeout=self._timeout,
+        )
+
+    def _open_connection(self) -> Any:
+        return connect(**self._connection_kwargs)
+
+    def connect(self) -> Any:  # type: ignore[override]
+        return self._pool.connect()
+
+    def dispose(self) -> None:  # type: ignore[override]
+        self._pool.dispose()
+
+
+def create_connection_pool(
+    connection: Optional[Connection] = None,
+    connection_pool: Optional[Pool] = None,
+    pool_size: int = 5,
+    max_overflow: int = 10,
+    timeout: float = 30,
+    connection_kwargs: Optional[dict] = None,
+) -> Pool:
+    """Return the connection pool that matches the supplied arguments.
+
+    Dispatch rules (checked in order):
+
+    1. If both ``connection`` and ``connection_pool`` are given, raise
+       :class:`ValueError` — the caller must pick one.
+    2. If ``connection`` is given, wrap it in a :class:`SingleConnectionPool`.
+    3. If ``connection_pool`` is given, return it unchanged.
+    4. Otherwise build a :class:`QueueConnectionPool` from ``pool_size``,
+       ``max_overflow``, ``timeout`` and ``connection_kwargs``.
+
+    See :class:`QueueConnectionPool` and :func:`singlestoredb.connect` for the
+    meaning of the remaining arguments.
+    """
+    if connection is not None and connection_pool is not None:
+        raise ValueError("Cannot specify both a connection and a connection pool.")
+
+    if connection is not None:
+        return SingleConnectionPool(connection)
+
+    if connection_pool is not None:
+        return connection_pool
+
+    return QueueConnectionPool(
+        pool_size=pool_size,
+        max_overflow=max_overflow,
+        timeout=timeout,
+        connection_kwargs=connection_kwargs,
+    )

singlestore_langchain_core-0.1.0/singlestore_langchain_core/_filter.py

@@ -0,0 +1,247 @@
+"""
+Filter module for VectorStore.
+
+This module provides typed filter definitions and utilities to convert
+filter dictionaries into SQL query fragments for metadata filtering.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Literal, Tuple, Union, cast
+
+# Type definitions for filter values
+FieldValue = Union[str, int, float, bool]
+NumericFieldValue = Union[int, float]
+
+# Simple filter types
+ExactMatchFilter = Dict[str, FieldValue]
+
+# Comparison operators
+EqFilter = Dict[Literal["$eq"], FieldValue]
+NeFilter = Dict[Literal["$ne"], FieldValue]
+GtFilter = Dict[Literal["$gt"], NumericFieldValue]
+GteFilter = Dict[Literal["$gte"], NumericFieldValue]
+LtFilter = Dict[Literal["$lt"], NumericFieldValue]
+LteFilter = Dict[Literal["$lte"], NumericFieldValue]
+
+# Collection operators
+InFilter = Dict[Literal["$in"], List[FieldValue]]
+NinFilter = Dict[Literal["$nin"], List[FieldValue]]
+
+# Existence operator
+ExistsFilter = Dict[Literal["$exists"], bool]
+
+# Combined filter types
+FieldFilter = Union[
+    EqFilter,
+    NeFilter,
+    GtFilter,
+    GteFilter,
+    LtFilter,
+    LteFilter,
+    InFilter,
+    NinFilter,
+    ExistsFilter,
+]
+
+SimpleFilter = Union[
+    ExactMatchFilter,
+    Dict[str, FieldFilter],
+]
+
+# Logical operators
+AndFilter = Dict[Literal["$and"], List["FilterTypedDict"]]
+OrFilter = Dict[Literal["$or"], List["FilterTypedDict"]]
+
+# Overall filter type
+FilterTypedDict = Union[SimpleFilter, AndFilter, OrFilter]
+
+
+def _get_match_param_function(value: Any) -> str:
+    """
+    Determine the appropriate match parameter function based on value type.
+
+    Args:
+        value: The value to match against
+
+    Returns:
+        String representing the SQL match function to use
+
+    Raises:
+        ValueError: If the value type is not supported
+    """
+    # Check bool first since bool is a subclass of int
+    if isinstance(value, bool):
+        return "MATCH_PARAM_BOOL_STRICT()"
+    elif isinstance(value, str):
+        return "MATCH_PARAM_STRING_STRICT()"
+    elif isinstance(value, (int, float)):
+        return "MATCH_PARAM_DOUBLE_STRICT()"
+    else:
+        raise ValueError(f"Unsupported value type: {type(value)}")
+
+
+def _parse_filter(
+    filter_dict: FilterTypedDict, metadata_field: str
+) -> tuple[str, list[Any]]:
+    """
+    Parse a filter dictionary into an SQL query fragment and parameters.
+
+    Args:
+        filter_dict: Filter specification following the FilterTypedDict schema
+
+    Returns:
+        Tuple containing:
+          - SQL query fragment string
+          - List of parameter values to be substituted into the query
+
+    Raises:
+        ValueError: If the filter format is invalid
+    """
+    if not isinstance(filter_dict, dict):
+        raise ValueError("Filter must be a dictionary")
+
+    if len(filter_dict) != 1:
+        raise ValueError("Filter must contain exactly one key")
+
+    # Handle logical operators
+    if "$and" in filter_dict:
+        return _handle_and_filter(  # type: ignore[arg-type]
+            cast(AndFilter, filter_dict), metadata_field
+        )
+    elif "$or" in filter_dict:
+        return _handle_or_filter(  # type: ignore[arg-type]
+            cast(OrFilter, filter_dict), metadata_field
+        )
+    else:
+        # Handle field filters
+        field_name = next(iter(filter_dict))
+        field_value = filter_dict[field_name]  # type: ignore[index]
+
+        if isinstance(field_value, dict):
+            # Handle operator-based field filter
+            return _handle_operator_filter(field_name, field_value, metadata_field)
+        else:
+            # Handle exact match filter
+            match_func = _get_match_param_function(field_value)
+            return (
+                f"JSON_MATCH_ANY({match_func} = %s, {metadata_field}, %s)",
+                [field_value, field_name],
+            )
+
+
+def _handle_and_filter(
+    filter_dict: AndFilter, metadata_field: str
+) -> tuple[str, list[Any]]:
+    """Handle $and operator filter."""
+    sub_filters = filter_dict["$and"]  # type: ignore[index]
+    if not isinstance(sub_filters, list):
+        raise ValueError("$and must be a list of filters")
+
+    # Process each sub-filter
+    parsed_filters = [
+        _parse_filter(sub_filter, metadata_field) for sub_filter in sub_filters
+    ]
+
+    # Join conditions with AND
+    query = " AND ".join(item[0] for item in parsed_filters)
+
+    # Flatten parameter lists
+    params = [param for parsed_filter in parsed_filters for param in parsed_filter[1]]
+
+    return query, params
+
+
+def _handle_or_filter(
+    filter_dict: OrFilter, metadata_field: str
+) -> tuple[str, list[Any]]:
+    """Handle $or operator filter."""
+    sub_filters = filter_dict["$or"]  # type: ignore[index]
+    if not isinstance(sub_filters, list):
+        raise ValueError("$or must be a list of filters")
+
+    # Process each sub-filter
+    parsed_filters = [
+        _parse_filter(sub_filter, metadata_field) for sub_filter in sub_filters
+    ]
+
+    # Join conditions with OR and wrap in parentheses
+    query = "(" + " OR ".join(item[0] for item in parsed_filters) + ")"
+
+    # Flatten parameter lists
+    params = [param for parsed_filter in parsed_filters for param in parsed_filter[1]]
+
+    return query, params
+
+
+def _handle_operator_filter(
+    field_name: str, field_filter: Dict, metadata_field: str
+) -> Tuple[str, List[Any]]:
+    """Handle operator-based field filters like $eq, $gt, etc."""
+    if len(field_filter) != 1:
+        raise ValueError("Field filter must contain exactly one key")
+
+    operator = next(iter(field_filter))
+    field_value = field_filter[operator]
+
+    # Equal operator
+    if operator == "$eq":
+        match_func = _get_match_param_function(field_value)
+        return (
+            f"JSON_MATCH_ANY({match_func} = %s, {metadata_field}, %s)",
+            [field_value, field_name],
+        )
+
+    # Not equal operator
+    elif operator == "$ne":
+        match_func = _get_match_param_function(field_value)
+        return (
+            f"NOT JSON_MATCH_ANY({match_func} = %s, {metadata_field}, %s) AND "
+            f"JSON_MATCH_ANY_EXISTS({metadata_field}, %s)",
+            [field_value, field_name, field_name],
+        )
+
+    # Numeric comparison operators
+    elif operator in ("$gt", "$gte", "$lt", "$lte"):
+        if not isinstance(field_value, (int, float)):
+            raise ValueError(f"{operator} must be a numeric value")
+
+        comparison_op = {"$gt": ">", "$gte": ">=", "$lt": "<", "$lte": "<="}[operator]
+
+        return (
+            f"JSON_EXTRACT_DOUBLE({metadata_field}, %s) {comparison_op} %s",
+            [field_name, field_value],
+        )
+
+    # Collection operators
+    elif operator in ("$in", "$nin"):
+        if not isinstance(field_value, list):
+            raise ValueError(f"{operator} must be a list")
+
+        if operator == "$in":
+            return (
+                f"JSON_MATCH_ANY(JSON_ARRAY_CONTAINS_JSON(%s, MATCH_PARAM_JSON()), "
+                f"{metadata_field}, %s)",
+                [json.dumps(field_value), field_name],
+            )
+        else:  # $nin
+            return (
+                f"NOT JSON_MATCH_ANY(JSON_ARRAY_CONTAINS_JSON(%s, MATCH_PARAM_JSON()), "
+                f"{metadata_field}, %s) AND "
+                f"JSON_MATCH_ANY_EXISTS({metadata_field}, %s)",
+                [json.dumps(field_value), field_name, field_name],
+            )
+
+    # Existence operator
+    elif operator == "$exists":
+        if not isinstance(field_value, bool):
+            raise ValueError("$exists must be a boolean")
+
+        if field_value:
+            return f"JSON_MATCH_ANY_EXISTS({metadata_field}, %s)", [field_name]
+        else:
+            return f"NOT JSON_MATCH_ANY_EXISTS({metadata_field}, %s)", [field_name]
+
+    else:
+        raise ValueError(f"Unsupported operator: {operator}")

singlestore_langchain_core-0.1.0/singlestore_langchain_core/_utils.py

@@ -0,0 +1,103 @@
+"""SingleStore connection helpers and shared enums.
+
+No LangChain / LangGraph imports live in this module so it can be shared by
+every SingleStore integration package.
+"""
+
+import hashlib
+from enum import Enum
+from importlib.metadata import PackageNotFoundError, version
+from typing import Optional
+
+DEFAULT_CONNECTOR_NAME = "langchain python sdk"
+
+
+def compute_connector_version(package_name: str, *, fallback: str = "3.0.0") -> str:
+    """Return the connector version to advertise to SingleStore.
+
+    Historically the connector version is the package version with ``2`` added
+    to the major component (``1.5.0`` -> ``3.5.0``).  This preserves the wire
+    contract that pre-monorepo releases used.
+    """
+    try:
+        pkg_version = version(package_name)
+        version_parts = pkg_version.split(".")
+        major_version = int(version_parts[0]) + 2
+        version_parts[0] = str(major_version)
+        return ".".join(version_parts)
+    except (PackageNotFoundError, ValueError):
+        return fallback
+
+
+def set_connector_attributes(
+    connection_kwargs: dict,
+    *,
+    connector_name: str = DEFAULT_CONNECTOR_NAME,
+    connector_version: Optional[str] = None,
+) -> None:
+    """Stamp connector identity onto ``connection_kwargs['conn_attrs']``.
+
+    ``connector_version`` may be ``None`` when the caller has no versioned
+    package to report; the attribute is simply omitted in that case.
+    """
+    if "conn_attrs" not in connection_kwargs:
+        connection_kwargs["conn_attrs"] = {}
+
+    connection_kwargs["conn_attrs"]["_connector_name"] = connector_name
+    if connector_version is not None:
+        connection_kwargs["conn_attrs"]["_connector_version"] = connector_version
+
+
+class DistanceStrategy(str, Enum):
+    """Distance strategies for calculating similarity between vectors.
+
+    Attributes:
+        EUCLIDEAN_DISTANCE: Computes the Euclidean (L2) distance between vectors.
+            Lower scores indicate more similar vectors. Not compatible with
+            WEIGHTED_SUM search strategy.
+        DOT_PRODUCT: Computes the dot product (inner product) between vectors.
+            Higher scores indicate more similar vectors. This is the default
+            and recommended strategy for most embedding models.
+    """
+
+    EUCLIDEAN_DISTANCE = "EUCLIDEAN_DISTANCE"
+    DOT_PRODUCT = "DOT_PRODUCT"
+
+
+class FullTextIndexVersion(str, Enum):
+    """Full-text index versions supported by SingleStore.
+
+    Attributes:
+        V1: Original full-text index implementation. Compatible with all
+            SingleStore versions that support full-text search. Only supports
+            MATCH scoring mode.
+        V2: New full-text index implementation available in SingleStore 8.7+.
+            Offers improved performance and supports additional scoring modes
+            (BM25, BM25_GLOBAL).
+    """
+
+    V1 = "V1"
+    V2 = "V2"
+
+
+class FullTextScoringMode(str, Enum):
+    """Scoring algorithms for full-text search ranking.
+
+    Attributes:
+        MATCH: Uses SingleStore's native MATCH() AGAINST() function.
+            Compatible with both V1 and V2 full-text indexes.
+        BM25: Best Matching 25 algorithm with TF-IDF scoring and document
+            length normalization. Requires V2 full-text index.
+        BM25_GLOBAL: BM25 with global IDF statistics across all partitions.
+            Provides consistent scoring in distributed environments.
+            Requires V2 full-text index.
+    """
+
+    MATCH = "MATCH"
+    BM25 = "BM25"
+    BM25_GLOBAL = "BM25_GLOBAL"
+
+
+def hash(_input: str) -> str:
+    """Use a deterministic hashing approach."""
+    return hashlib.md5(_input.encode()).hexdigest()