agent-framework-sql-server 1.0.0a261002__py3-none-any.whl

agent_framework_sql_server/__init__.py

@@ -0,0 +1,22 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""SQL Server native vector collections and stores for Agent Framework."""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+from ._vector_store import SqlServerCollection, SqlServerCommittedCleanupException, SqlServerSettings, SqlServerStore
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "SqlServerCollection",
+    "SqlServerCommittedCleanupException",
+    "SqlServerSettings",
+    "SqlServerStore",
+    "__version__",
+]

agent_framework_sql_server/_sql.py

@@ -0,0 +1,344 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""SQL Server identifiers, values, and portable filter translation."""
+
+# pyright: reportUnusedFunction=false, reportUnusedClass=false
+# Package-private helpers are consumed by the sibling vector-store module.
+
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Sequence
+from datetime import date, datetime, timezone
+from typing import Any, cast
+from uuid import UUID
+
+from agent_framework import FilterGroup, VectorStoreCollectionDefinition, VectorStoreField
+from agent_framework._vector_filters import FilterExpression
+from agent_framework.exceptions import IntegrationInvalidResponseException
+
+MAX_PARAMETERS = 2000  # SQL Server's limit is 2100; leave room for paging and search arguments.
+_FLOAT32_MAX = 3.4028234663852886e38
+_COLLATION = "Latin1_General_100_BIN2"
+_ORDER_OPERATORS = {"gt": ">", "gte": ">=", "lt": "<", "lte": "<="}
+_METRICS = {
+    "DEFAULT": ("cosine", "distance"),
+    "cosine_distance": ("cosine", "distance"),
+    "cosine_similarity": ("cosine", "similarity"),
+    "euclidean_distance": ("euclidean", "distance"),
+    "dot_prod": ("dot", "negative"),
+    "negative_dot_prod": ("dot", "distance"),
+}
+
+
+def _quote_identifier(name: str) -> str:
+    """Quote one SQL identifier; data values must be passed as bound parameters."""
+    if not isinstance(name, str) or not name or "\0" in name or len(name.encode("utf-16-le")) // 2 > 128:
+        raise ValueError("SQL Server identifiers must contain 1-128 UTF-16 code units and no NUL.")
+    return f"[{name.replace(']', ']]')}]"
+
+
+def _metric_for(field: VectorStoreField) -> tuple[str, str]:
+    try:
+        return _METRICS[field.distance_function or "DEFAULT"]
+    except KeyError:
+        raise NotImplementedError(f"Unsupported SQL Server distance function '{field.distance_function}'.") from None
+
+
+def _column_type(field: VectorStoreField) -> str:
+    if field.field_type == "vector":
+        dimensions = field.dimensions
+        if type(dimensions) is not int or not 1 <= dimensions <= 1998:
+            raise ValueError("SQL Server vector dimensions must be an integer between 1 and 1998.")
+        if field.type_ not in (None, "float", "float32"):
+            raise NotImplementedError("SQL Server VECTOR columns support float32 vectors only.")
+        return f"VECTOR({dimensions})"
+    types = {
+        "int": "BIGINT",
+        "float": "FLOAT(53)",
+        "bool": "BIT",
+        "UUID": "UNIQUEIDENTIFIER",
+        "bytes": "VARBINARY(MAX)",
+        "date": "DATE",
+        "datetime": "DATETIME2(7)",
+        "list": "NVARCHAR(MAX)",
+        "dict": "NVARCHAR(MAX)",
+    }
+    if field.type_ == "str":
+        width = "450" if field.field_type == "key" or field.is_indexed else "MAX"
+        return f"NVARCHAR({width}) COLLATE {_COLLATION}"
+    if field.type_ not in types:
+        raise NotImplementedError(f"Field '{field.name}' needs a supported explicit type; got '{field.type_}'.")
+    return types[field.type_]
+
+
+def _validate_json(value: Any) -> None:
+    if value is None or type(value) in (str, bool, int):
+        return
+    if type(value) is float:
+        if not math.isfinite(value):
+            raise ValueError("JSON values must be finite.")
+        return
+    if isinstance(value, list):
+        for item in cast(list[Any], value):
+            _validate_json(item)
+        return
+    if isinstance(value, dict):
+        for key, item in cast(dict[Any, Any], value).items():
+            if not isinstance(key, str):
+                raise TypeError("JSON object keys must be strings.")
+            _validate_json(item)
+        return
+    raise TypeError("JSON fields support only JSON scalars, lists, and string-keyed dictionaries.")
+
+
+def _prepare_vector(field: VectorStoreField, value: Any) -> str:
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes, bytearray)):
+        raise TypeError(f"Vector field '{field.name}' requires a dense numeric sequence.")
+    vector = cast(Sequence[float | int], value)
+    if len(vector) != field.dimensions:
+        raise ValueError(f"Vector field '{field.name}' requires {field.dimensions} dimensions.")
+    components: list[float] = []
+    for element in vector:
+        if type(element) not in (float, int):
+            raise TypeError(f"Vector field '{field.name}' requires numeric elements, not booleans or strings.")
+        try:
+            component = float(element)
+        except OverflowError as exc:
+            raise ValueError(f"Vector field '{field.name}' has an element outside the float32 range.") from exc
+        if not math.isfinite(component) or abs(component) > _FLOAT32_MAX:
+            raise ValueError(f"Vector field '{field.name}' requires finite float32 elements.")
+        components.append(component)
+    return json.dumps(components, separators=(",", ":"), allow_nan=False)
+
+
+def _prepare_value(field: VectorStoreField, value: Any) -> Any:
+    if value is None:
+        return None
+    if field.field_type == "vector":
+        return _prepare_vector(field, value)
+    kind = field.type_
+    if kind == "UUID" and isinstance(value, (str, UUID)):
+        return str(UUID(str(value)))
+    if kind == "int" and type(value) is int:
+        if not -(2**63) <= value < 2**63:
+            raise ValueError(f"Field '{field.name}' exceeds the SQL Server bigint range.")
+        return value
+    if kind == "float" and type(value) in (float, int):
+        try:
+            number = float(value)
+        except OverflowError as exc:
+            raise ValueError(f"Field '{field.name}' requires a finite number.") from exc
+        if not math.isfinite(number):
+            raise ValueError(f"Field '{field.name}' requires a finite number.")
+        return number
+    if kind == "bool" and type(value) is bool:
+        return value
+    if kind == "str" and isinstance(value, str):
+        if (field.field_type == "key" or field.is_indexed) and len(value.encode("utf-16-le")) // 2 > 450:
+            raise ValueError(f"Field '{field.name}' exceeds the indexed NVARCHAR(450) limit.")
+        if field.field_type == "key" and value.endswith(" "):
+            raise ValueError(
+                "SQL Server string keys cannot end in a space; SQL Server ignores trailing spaces in keys."
+            )
+        return value
+    if kind == "bytes" and isinstance(value, bytes):
+        return value
+    if kind == "date" and (type(value) is date or isinstance(value, str)):
+        return date.fromisoformat(value) if isinstance(value, str) else value
+    if kind == "datetime" and isinstance(value, (datetime, str)):
+        resolved = datetime.fromisoformat(value.replace("Z", "+00:00")) if isinstance(value, str) else value
+        if resolved.tzinfo is None or resolved.utcoffset() is None:
+            raise ValueError(f"Datetime field '{field.name}' requires a timezone.")
+        return resolved.astimezone(timezone.utc).replace(tzinfo=None)
+    if (kind == "list" and isinstance(value, list)) or (kind == "dict" and isinstance(value, dict)):
+        _validate_json(value)
+        return json.dumps(value, separators=(",", ":"), ensure_ascii=False, allow_nan=False)
+    raise TypeError(f"Field '{field.name}' requires a value of type '{kind}'.")
+
+
+def _parse_value(field: VectorStoreField, value: Any) -> Any:
+    if value is None:
+        return None
+    kind = field.type_
+    if field.field_type == "vector" or kind in ("list", "dict"):
+        if not isinstance(value, str):
+            raise IntegrationInvalidResponseException(f"SQL Server returned a non-JSON value for '{field.name}'.")
+        try:
+            parsed: Any = json.loads(value)
+        except json.JSONDecodeError as exc:
+            raise IntegrationInvalidResponseException(f"SQL Server returned invalid JSON for '{field.name}'.") from exc
+        if field.field_type == "vector":
+            if not isinstance(parsed, list):
+                raise IntegrationInvalidResponseException(f"SQL Server returned an invalid vector for '{field.name}'.")
+            vector_values = cast(list[Any], parsed)
+            if len(vector_values) != field.dimensions:
+                raise IntegrationInvalidResponseException(f"SQL Server returned an invalid vector for '{field.name}'.")
+            components: list[float] = []
+            for item in vector_values:
+                if type(item) not in (int, float):
+                    raise IntegrationInvalidResponseException(
+                        f"SQL Server returned invalid vector elements for '{field.name}'."
+                    )
+                try:
+                    number = float(item)
+                except OverflowError as exc:
+                    raise IntegrationInvalidResponseException(
+                        f"SQL Server returned invalid vector elements for '{field.name}'."
+                    ) from exc
+                if not math.isfinite(number) or abs(number) > _FLOAT32_MAX:
+                    raise IntegrationInvalidResponseException(
+                        f"SQL Server returned invalid vector elements for '{field.name}'."
+                    )
+                components.append(number)
+            return components
+        if not isinstance(parsed, list if kind == "list" else dict):
+            raise IntegrationInvalidResponseException(f"SQL Server returned the wrong JSON type for '{field.name}'.")
+        return cast(list[Any] | dict[str, Any], parsed)
+    if kind == "UUID":
+        try:
+            return UUID(str(value))
+        except ValueError as exc:
+            raise IntegrationInvalidResponseException(
+                f"SQL Server returned an invalid UUID for '{field.name}'."
+            ) from exc
+    if kind == "datetime":
+        if not isinstance(value, datetime):
+            raise IntegrationInvalidResponseException(f"SQL Server returned an invalid datetime for '{field.name}'.")
+        return value.replace(tzinfo=timezone.utc) if value.tzinfo is None else value.astimezone(timezone.utc)
+    if kind == "bool" and type(value) is int and value in (0, 1):
+        return bool(value)
+    return value
+
+
+def _filter_field(definition: VectorStoreCollectionDefinition, name: str) -> VectorStoreField:
+    if "." in name:
+        raise NotImplementedError("SQL Server filters and ordering do not support nested field paths.")
+    field = definition.try_get_field(name)
+    if field is None:
+        raise ValueError(f"Unknown SQL Server field '{name}'.")
+    if field.field_type == "vector":
+        raise NotImplementedError("Filtering and ordering vector columns is not supported.")
+    return field
+
+
+def _numeric_filter_value(value: int | float) -> int | float:
+    try:
+        if not math.isfinite(value):
+            raise ValueError("Numeric filter values must be finite.")
+    except OverflowError as exc:
+        raise ValueError("Numeric filter values must fit in the SQL Server numeric range.") from exc
+    if type(value) is int and not -(2**63) <= value < 2**63:
+        raise ValueError("Integer filter values must fit in the SQL Server bigint range.")
+    return value
+
+
+def _prepare_numeric_filter_value(field: VectorStoreField, value: int | float) -> int | float:
+    return _numeric_filter_value(value) if field.type_ == "int" else _prepare_value(field, value)
+
+
+class _FilterCompiler:
+    """Compile bounded data-only filter expressions into parameterized two-valued T-SQL."""
+
+    def __init__(self, definition: VectorStoreCollectionDefinition, *, alias: str = "") -> None:
+        self.definition = definition
+        self.alias = alias
+        self.parameters: list[Any] = []
+
+    def compile(self, expression: FilterExpression) -> tuple[str, list[Any]]:
+        """Compile one filter with its parameters in placeholder order."""
+        self.parameters = []
+        return self._condition(expression), self.parameters
+
+    def _bind(self, value: Any) -> str:
+        if len(self.parameters) >= MAX_PARAMETERS:
+            raise ValueError(f"SQL Server queries support at most {MAX_PARAMETERS} bound parameters.")
+        self.parameters.append(value)
+        return "?"
+
+    def _equality(self, field: VectorStoreField, column: str, value: Any) -> str:
+        if value is None:
+            return f"{column} IS NULL"
+        kind = field.type_
+        if kind in ("list", "dict"):
+            raise NotImplementedError("Equality filtering JSON fields is not supported.")
+        if kind == "bool" and type(value) is not bool:
+            return "1 = 0"
+        if kind != "bool" and isinstance(value, bool):
+            return "1 = 0"
+        if kind in ("int", "float") and type(value) in (int, float):
+            adapted = _prepare_numeric_filter_value(field, value)
+        elif (
+            (kind == "str" and isinstance(value, str))
+            or (kind == "bytes" and isinstance(value, bytes))
+            or (kind == "UUID" and isinstance(value, (UUID, str)))
+            or (kind == "date" and (type(value) is date or isinstance(value, str)))
+            or (kind == "datetime" and isinstance(value, (datetime, str)))
+            or (kind == "bool" and type(value) is bool)
+        ):
+            adapted = _prepare_value(field, value)
+        else:
+            return "1 = 0"
+        if kind == "str":
+            # SQL Server pads trailing spaces even with binary collations; compare bytes instead.
+            return (
+                f"({column} IS NOT NULL AND CONVERT(VARBINARY(MAX), {column}) = "
+                f"CONVERT(VARBINARY(MAX), CONVERT(NVARCHAR(MAX), {self._bind(adapted)})))"
+            )
+        return f"({column} IS NOT NULL AND {column} = {self._bind(adapted)})"
+
+    def _condition(self, expression: FilterExpression) -> str:
+        if isinstance(expression, FilterGroup):
+            conditions = [self._condition(child) for child in expression.filters]
+            if expression.operator == "not":
+                return f"(NOT ({conditions[0]}))"
+            joiner = " AND " if expression.operator == "and" else " OR "
+            return f"({joiner.join(conditions)})"
+        field = _filter_field(self.definition, expression.field_name)
+        column = f"{self.alias}{_quote_identifier(field.storage_name or field.name)}"
+        op, value = expression.operator, expression.value
+        if op == "exists":
+            return "1 = 1"  # SQL columns exist even when their values are NULL.
+        if op == "is_null":
+            return f"{column} IS NULL"
+        if op == "is_not_null":
+            return f"{column} IS NOT NULL"
+        if op in ("eq", "ne"):
+            equality = self._equality(field, column, value)
+            return equality if op == "eq" else f"(NOT ({equality}))"
+        if op in ("in", "not_in"):
+            choices = " OR ".join(self._equality(field, column, item) for item in value) or "1 = 0"
+            membership = f"({choices})" if op == "in" else f"(NOT ({choices}))"
+            return f"({column} IS NOT NULL AND {membership})"
+        if op in _ORDER_OPERATORS or op == "between":
+            if field.type_ not in ("int", "float", "date", "datetime"):
+                raise NotImplementedError(f"Ordered SQL Server filtering is not supported for '{field.type_}'.")
+            values: Sequence[Any] = value if op == "between" else [value]
+            if any(item is None or isinstance(item, bool) for item in values):
+                raise TypeError("Ordered filter operands must be non-null scalars of the column's type.")
+            adapted = [
+                _prepare_numeric_filter_value(field, item)
+                if field.type_ in ("int", "float") and type(item) in (int, float)
+                else _prepare_value(field, item)
+                for item in values
+            ]
+            comparison = (
+                f"{column} BETWEEN {self._bind(adapted[0])} AND {self._bind(adapted[1])}"
+                if op == "between"
+                else f"{column} {_ORDER_OPERATORS[op]} {self._bind(adapted[0])}"
+            )
+            return f"({column} IS NOT NULL AND {comparison})"
+        if op in ("contains_text", "starts_with", "ends_with"):
+            if field.type_ != "str":
+                raise TypeError("Text filtering requires a string column.")
+            if not isinstance(value, str):
+                raise TypeError("Text filtering requires a string operand.")
+            if "\0" in value:
+                raise ValueError("SQL Server LIKE does not support NUL characters.")
+            escaped = value.replace("!", "!!").replace("%", "!%").replace("_", "!_").replace("[", "[[]")
+            pattern = ("%" if op != "starts_with" else "") + escaped + ("%" if op != "ends_with" else "")
+            if len(pattern.encode("utf-16-le")) > 8000:
+                raise ValueError("SQL Server LIKE patterns cannot exceed 8000 bytes.")
+            return f"({column} IS NOT NULL AND {column} COLLATE {_COLLATION} LIKE {self._bind(pattern)} ESCAPE '!')"
+        raise NotImplementedError(f"Unsupported SQL Server filter operator '{op}'.")

agent_framework_sql_server/_vector_store.py

@@ -0,0 +1,705 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Asynchronous Agent Framework collections backed by SQL Server VECTOR columns."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import logging
+import math
+from collections.abc import Callable, Mapping, Sequence
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import replace
+from typing import Any, ClassVar, Generic, cast
+
+import mssql_python
+from agent_framework import (
+    BaseVectorCollection,
+    BaseVectorSearch,
+    BaseVectorStore,
+    SearchResults,
+    SecretString,
+    VectorStoreCollectionDefinition,
+    load_settings,
+)
+from agent_framework._vector_filters import FilterExpression
+from agent_framework._vectors import EmbeddingClient, SearchType, Vector
+from agent_framework.exceptions import IntegrationException, IntegrationInvalidResponseException
+from typing_extensions import Self, TypedDict, TypeVar
+
+from ._sql import (
+    MAX_PARAMETERS,
+    _column_type,  # pyright: ignore[reportPrivateUsage]
+    _filter_field,  # pyright: ignore[reportPrivateUsage]
+    _FilterCompiler,  # pyright: ignore[reportPrivateUsage]
+    _metric_for,  # pyright: ignore[reportPrivateUsage]
+    _parse_value,  # pyright: ignore[reportPrivateUsage]
+    _prepare_value,  # pyright: ignore[reportPrivateUsage]
+    _quote_identifier,  # pyright: ignore[reportPrivateUsage]
+)
+
+KeyT = TypeVar("KeyT", default=Any)
+ModelT = TypeVar("ModelT", default=Any)
+ResultT = TypeVar("ResultT")
+_KEY_BATCH_SIZE = 1000
+logger = logging.getLogger(__name__)
+
+
+class SqlServerCommittedCleanupException(IntegrationException):
+    """The SQL Server transaction committed, but closing its connection failed."""
+
+
+class SqlServerSettings(TypedDict, total=False):
+    """Connection settings resolved from explicit values, a selected .env file, or ``SQL_SERVER_`` variables."""
+
+    connection_string: SecretString | None
+    """Driver connection string, resolved from ``SQL_SERVER_CONNECTION_STRING`` and kept masked."""
+
+
+def _validate_options(options: Mapping[str, Any] | None) -> None:
+    if options:
+        raise NotImplementedError(f"Unsupported SQL Server operation option(s): {', '.join(sorted(options))}.")
+
+
+def _execute(cursor: mssql_python.Cursor, statement: str, parameters: Sequence[Any] = ()) -> None:
+    if parameters:
+        cursor.execute(statement, tuple(parameters))  # pyright: ignore[reportUnknownMemberType]
+    else:
+        cursor.execute(statement)  # pyright: ignore[reportUnknownMemberType]
+
+
+def _rows(cursor: mssql_python.Cursor, count: int) -> list[Sequence[Any]]:
+    result: list[Sequence[Any]] = [tuple(row) for row in cursor.fetchall()]
+    for row in result:
+        if len(row) != count:
+            raise IntegrationInvalidResponseException("SQL Server returned a row with an unexpected column count.")
+    return result
+
+
+def _check_parameter_count(parameters: Sequence[Any]) -> None:
+    if len(parameters) > MAX_PARAMETERS:
+        raise ValueError(f"SQL Server queries support at most {MAX_PARAMETERS} bound parameters.")
+
+
+class _Client:
+    """Own one worker; every operation creates and releases a connection on that worker."""
+
+    def __init__(self, connection_string: SecretString | None, *, query_timeout: int | None = None) -> None:
+        if connection_string is None:
+            raise ValueError("SQL_SERVER_CONNECTION_STRING or an explicit connection_string is required.")
+        if not connection_string.get_secret_value().strip():
+            raise ValueError("connection_string must not be empty.")
+        if query_timeout is not None and (type(query_timeout) is not int or query_timeout < 0):
+            raise ValueError("query_timeout must be a non-negative integer number of seconds.")
+        self.connection_string = connection_string
+        self.query_timeout = query_timeout
+        self.closed = False
+        self._executor: ThreadPoolExecutor | None = None
+        self._close_lock = asyncio.Lock()
+
+    def ensure_open(self) -> None:
+        if self.closed:
+            raise RuntimeError("The SQL Server client is closed.")
+
+    def _run_sync(self, operation: Callable[[mssql_python.Cursor], ResultT]) -> ResultT:
+        try:
+            connection = mssql_python.connect(self.connection_string.get_secret_value(), autocommit=False)
+            committed = False
+            failed = False
+            try:
+                try:
+                    if self.query_timeout is not None:
+                        connection.timeout = self.query_timeout
+                    cursor = connection.cursor()
+                    try:
+                        result = operation(cursor)
+                    finally:
+                        cursor.close()
+                    connection.commit()
+                    committed = True
+                    return result
+                except BaseException:
+                    failed = True
+                    connection.rollback()
+                    raise
+            finally:
+                try:
+                    connection.close()
+                except Exception as exc:
+                    if committed:
+                        raise SqlServerCommittedCleanupException(
+                            "SQL Server transaction committed, but connection cleanup failed; "
+                            "do not retry this operation automatically."
+                        ) from exc
+                    if failed:
+                        logger.warning(
+                            "SQL Server connection cleanup also failed after an operation error.", exc_info=exc
+                        )
+                    else:
+                        raise
+        except mssql_python.Error as exc:
+            raise IntegrationException("SQL Server operation failed; inspect the chained driver exception.") from exc
+
+    async def run(self, operation: Callable[[mssql_python.Cursor], ResultT]) -> ResultT:
+        """Offload a whole transaction and wait for worker cleanup on cancellation."""
+        self.ensure_open()
+        if self._executor is None:
+            self._executor = ThreadPoolExecutor(max_workers=1, thread_name_prefix="af-sql-server")
+        future = asyncio.get_running_loop().run_in_executor(self._executor, self._run_sync, operation)
+        try:
+            return await asyncio.shield(future)
+        except asyncio.CancelledError:
+            while not future.done():
+                try:
+                    await asyncio.shield(future)
+                except asyncio.CancelledError:
+                    continue
+                except Exception:
+                    break
+            if not future.cancelled() and (error := future.exception()) is not None:
+                logger.warning("SQL Server worker failed after caller cancellation.", exc_info=error)
+            raise
+
+    async def close(self) -> None:
+        """Wait for queued operations and shut down the owned worker."""
+        async with self._close_lock:
+            if self.closed:
+                return
+            self.closed = True
+            if self._executor is not None:
+                await asyncio.to_thread(self._executor.shutdown, wait=True)
+
+
+def _create_client(
+    connection_string: str | SecretString | None,
+    *,
+    query_timeout: int | None,
+    env_file_path: str | None,
+    env_file_encoding: str | None,
+) -> _Client:
+    settings = load_settings(
+        SqlServerSettings,
+        env_prefix="SQL_SERVER_",
+        connection_string=connection_string,
+        env_file_path=env_file_path,
+        env_file_encoding=env_file_encoding,
+    )
+    resolved = settings.get("connection_string")
+    if resolved is not None and not isinstance(resolved, SecretString):
+        raise TypeError("connection_string must be a string or SecretString.")
+    return _Client(resolved, query_timeout=query_timeout)
+
+
+class SqlServerCollection(
+    BaseVectorCollection[KeyT, ModelT],
+    BaseVectorSearch[KeyT, ModelT],
+    Generic[KeyT, ModelT],
+):
+    """Store typed rows and perform exact searches on SQL Server native VECTOR columns.
+
+    Tables are created in an existing schema and are never migrated. Connections
+    are owned by the collection, or by its store when created from a store.
+    """
+
+    supported_key_types: ClassVar[set[str] | None] = {"str", "int", "UUID"}
+    supported_vector_types: ClassVar[set[str] | None] = {"float", "float32"}
+    supported_search_types: ClassVar[set[SearchType]] = {"vector"}
+
+    def __init__(
+        self,
+        record_type: type[ModelT],
+        *,
+        connection_string: str | SecretString | None = None,
+        query_timeout: int | None = None,
+        schema: str = "dbo",
+        definition: VectorStoreCollectionDefinition | None = None,
+        collection_name: str | None = None,
+        embedding_generator: EmbeddingClient | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+    ) -> None:
+        """Initialize a collection without connecting to the database.
+
+        Args:
+            record_type: Decorated/registered model type, or ``dict``.
+            connection_string: Driver connection string, or ``SQL_SERVER_CONNECTION_STRING``.
+            query_timeout: Optional per-statement timeout in seconds; ``0`` disables the timeout.
+            schema: Existing database schema containing the table.
+            definition: Explicit field definition for dictionary records.
+            collection_name: Table name overriding the model definition.
+            embedding_generator: Default local embedding generator.
+            env_file_path: Optional .env file.
+            env_file_encoding: Encoding of the selected .env file.
+        """
+        super().__init__(
+            record_type,
+            definition=definition,
+            collection_name=collection_name,
+            embedding_generator=embedding_generator,
+            managed_client=True,
+        )
+        self.schema = schema
+        self._table = f"{_quote_identifier(schema)}.{_quote_identifier(self.collection_name)}"
+        self._fields = tuple(
+            replace(field, provider_annotations=field.provider_annotations) for field in self.definition.fields
+        )
+        for field in self._fields:
+            _quote_identifier(field.storage_name or field.name)
+            _column_type(field)
+            if field.is_full_text_indexed:
+                raise NotImplementedError("SQL Server full-text and keyword-hybrid search are not supported.")
+            if any(name.startswith("sql_server.") for name in field.provider_annotations):
+                raise NotImplementedError("SQL Server provider annotations are not supported.")
+            if field.field_type == "vector":
+                _metric_for(field)
+                if field.index_kind not in ("default", "flat"):
+                    raise NotImplementedError("SQL Server approximate vector indexes are not supported.")
+            elif field.is_indexed and field.field_type == "data" and field.type_ in ("bytes", "list", "dict"):
+                raise NotImplementedError(f"SQL Server cannot index data fields of type '{field.type_}'.")
+        self._client = _create_client(
+            connection_string,
+            query_timeout=query_timeout,
+            env_file_path=env_file_path,
+            env_file_encoding=env_file_encoding,
+        )
+
+    async def __aenter__(self) -> Self:
+        """Enter the collection context."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None:
+        """Release collection-owned resources."""
+        await self.close()
+
+    async def close(self) -> None:
+        """Close a collection-owned worker, never its store's worker."""
+        if self.managed_client:
+            await self._client.close()
+
+    def _column_names(self, include_vectors: bool) -> list[str]:
+        return [
+            field.storage_name or field.name
+            for field in self._fields
+            if include_vectors or field.field_type != "vector"
+        ]
+
+    def _column_definitions(self) -> str:
+        definitions: list[str] = []
+        for field in self._fields:
+            column = _quote_identifier(field.storage_name or field.name)
+            data_type = _column_type(field)
+            if field.field_type == "key":
+                generated = ""
+                if field.is_auto_generated:
+                    generated = {
+                        "int": " IDENTITY(1,1)",
+                        "UUID": " DEFAULT NEWID()",
+                        "str": " DEFAULT CONVERT(NVARCHAR(36), NEWID())",
+                    }[field.type_ or ""]
+                definitions.append(f"{column} {data_type}{generated} NOT NULL PRIMARY KEY")
+            else:
+                definitions.append(f"{column} {data_type} NULL")
+        return ", ".join(definitions)
+
+    @staticmethod
+    def _index_name(schema: str, table: str, column: str) -> str:
+        digest = hashlib.sha256(f"{schema}\0{table}\0{column}".encode()).hexdigest()[:32]
+        return f"af_sql_{digest}"
+
+    async def ensure_collection_exists(self, *, operation_options: Mapping[str, Any] | None = None) -> None:
+        """Create a table and requested scalar indexes, without modifying existing tables."""
+        _validate_options(operation_options)
+        self._client.ensure_open()
+        statement = (
+            "IF NOT EXISTS (SELECT 1 FROM sys.tables AS t "  # nosec B608
+            "JOIN sys.schemas AS s ON s.schema_id = t.schema_id "
+            "WHERE s.name = ? AND t.name = ?) "
+            f"BEGIN CREATE TABLE {self._table} ({self._column_definitions()}) END"
+        )
+
+        def create(cursor: mssql_python.Cursor) -> None:
+            _execute(cursor, statement, [self.schema, self.collection_name])
+            for field in self._fields:
+                if field.field_type != "data" or not field.is_indexed:
+                    continue
+                name = field.storage_name or field.name
+                index_name = self._index_name(self.schema, self.collection_name, name)
+                index_statement = (
+                    "IF NOT EXISTS (SELECT 1 FROM sys.indexes AS i "  # nosec B608
+                    "JOIN sys.tables AS t ON t.object_id = i.object_id "
+                    "JOIN sys.schemas AS s ON s.schema_id = t.schema_id "
+                    "WHERE s.name = ? AND t.name = ? AND i.name = ?) "
+                    f"CREATE INDEX {_quote_identifier(index_name)} ON {self._table} ({_quote_identifier(name)})"
+                )
+                _execute(cursor, index_statement, [self.schema, self.collection_name, index_name])
+
+        await self._client.run(create)
+
+    async def collection_exists(self, *, operation_options: Mapping[str, Any] | None = None) -> bool:
+        """Return whether a base table exists in the configured schema."""
+        _validate_options(operation_options)
+
+        def exists(cursor: mssql_python.Cursor) -> bool:
+            _execute(
+                cursor,
+                "SELECT 1 FROM sys.tables AS t JOIN sys.schemas AS s ON s.schema_id = t.schema_id "
+                "WHERE s.name = ? AND t.name = ?",
+                [self.schema, self.collection_name],
+            )
+            return cursor.fetchone() is not None
+
+        return await self._client.run(exists)
+
+    async def ensure_collection_deleted(self, *, operation_options: Mapping[str, Any] | None = None) -> None:
+        """Drop only the table in this schema; never drop the schema or other tables."""
+        _validate_options(operation_options)
+        await self._client.run(lambda cursor: _execute(cursor, f"DROP TABLE IF EXISTS {self._table}"))
+
+    def _deserialize_store_models_to_dicts(
+        self, records: Sequence[Any], *, context: Mapping[str, Any] | None = None
+    ) -> Sequence[dict[str, Any]]:
+        result = super()._deserialize_store_models_to_dicts(records, context=context)
+        for record in result:
+            for field in self._fields:
+                name = field.storage_name or field.name
+                if name in record:
+                    record[name] = _parse_value(field, record[name])
+        return result
+
+    def _prepare_key(self, key: Any) -> Any:
+        if key is None:
+            raise ValueError("SQL Server keys cannot be null.")
+        return _prepare_value(self.definition.key_field, key)
+
+    def _parsed_key(self, key: Any) -> Any:
+        return _parse_value(self.definition.key_field, key)
+
+    async def _inner_upsert(
+        self, records: Sequence[Any], *, operation_options: Mapping[str, Any] | None = None
+    ) -> Sequence[KeyT]:
+        _validate_options(operation_options)
+        self._client.ensure_open()
+        prepared: list[dict[str, Any]] = []
+        for record in records:
+            row: dict[str, Any] = {}
+            for field in self._fields:
+                name = field.storage_name or field.name
+                if name not in record and field.field_type == "key" and field.is_auto_generated:
+                    continue
+                row[name] = (
+                    self._prepare_key(record[name])
+                    if field.field_type == "key"
+                    else _prepare_value(field, record[name])
+                )
+            prepared.append(row)
+        if not prepared:
+            return []
+        key_name = self.definition.key_field_storage_name
+        key_column = _quote_identifier(key_name)
+
+        def upsert(cursor: mssql_python.Cursor) -> list[KeyT]:
+            keys: list[KeyT] = []
+            for row in prepared:
+                names = tuple(row)
+                if key_name in row:
+                    _execute(
+                        cursor,
+                        f"SELECT {key_column} FROM {self._table} WITH (UPDLOCK, HOLDLOCK) WHERE {key_column} = ?",  # nosec B608
+                        [row[key_name]],
+                    )
+                    if cursor.fetchone() is not None:
+                        updates = [name for name in names if name != key_name]
+                        assignments = ", ".join(f"{_quote_identifier(name)} = ?" for name in updates)
+                        if not assignments:
+                            assignments = f"{key_column} = {key_column}"
+                        parameters = [*(row[name] for name in updates), row[key_name]]
+                        _check_parameter_count(parameters)
+                        _execute(
+                            cursor,
+                            f"UPDATE {self._table} SET {assignments} OUTPUT INSERTED.{key_column} "  # nosec B608
+                            f"WHERE {key_column} = ?",
+                            parameters,
+                        )
+                        result = cursor.fetchone()
+                        if result is None:
+                            raise IntegrationInvalidResponseException("SQL Server did not return an updated key.")
+                        keys.append(cast(KeyT, self._parsed_key(result[0])))
+                        continue
+                    if self.definition.key_field.is_auto_generated and self.definition.key_field.type_ == "int":
+                        raise NotImplementedError(
+                            "SQL Server IDENTITY columns cannot insert an explicit new key; omit it to generate a key."
+                        )
+                if names:
+                    columns = ", ".join(_quote_identifier(name) for name in names)
+                    markers = ", ".join("?" for _ in names)
+                    statement = f"INSERT INTO {self._table} ({columns}) OUTPUT INSERTED.{key_column} VALUES ({markers})"  # nosec B608
+                    parameters = [row[name] for name in names]
+                    _check_parameter_count(parameters)
+                    _execute(cursor, statement, parameters)
+                else:
+                    _execute(cursor, f"INSERT INTO {self._table} OUTPUT INSERTED.{key_column} DEFAULT VALUES")
+                result = cursor.fetchone()
+                if result is None:
+                    raise IntegrationInvalidResponseException("SQL Server did not return an inserted key.")
+                keys.append(cast(KeyT, self._parsed_key(result[0])))
+            return keys
+
+        return await self._client.run(upsert)
+
+    def _order_by(self, order_by: Mapping[str, bool] | None) -> str:
+        parts: list[str] = []
+        for name, ascending in (order_by or {}).items():
+            if type(ascending) is not bool:
+                raise TypeError("Order directions must be booleans.")
+            field = _filter_field(self.definition, name)
+            if field.type_ in ("list", "dict", "bytes"):
+                raise NotImplementedError(f"SQL Server ordering is not supported for '{field.type_}'.")
+            column = _quote_identifier(field.storage_name or field.name)
+            parts.append(f"CASE WHEN {column} IS NULL THEN 1 ELSE 0 END")
+            parts.append(f"{column} {'ASC' if ascending else 'DESC'}")
+        if self.definition.key_field.name not in (order_by or {}):
+            parts.append(f"{_quote_identifier(self.definition.key_field_storage_name)} ASC")
+        return ", ".join(parts)
+
+    async def _inner_get(
+        self,
+        *,
+        keys: Sequence[KeyT] | None = None,
+        filter: FilterExpression | None = None,
+        top: int = 10,
+        skip: int = 0,
+        order_by: Mapping[str, bool] | None = None,
+        include_vectors: bool = False,
+        operation_options: Mapping[str, Any] | None = None,
+    ) -> Sequence[Any]:
+        _validate_options(operation_options)
+        self._client.ensure_open()
+        columns = self._column_names(include_vectors)
+        select = f"SELECT {', '.join(_quote_identifier(name) for name in columns)} FROM {self._table}"  # nosec B608
+        if keys is not None:
+            if order_by:
+                raise ValueError("order_by applies only to filtered retrieval, not key lookup.")
+            prepared_keys = [self._prepare_key(key) for key in keys]
+            if not prepared_keys:
+                return []
+
+            def get_keys(cursor: mssql_python.Cursor) -> list[dict[str, Any]]:
+                found: dict[Any, dict[str, Any]] = {}
+                key_column = _quote_identifier(self.definition.key_field_storage_name)
+                for offset in range(0, len(prepared_keys), _KEY_BATCH_SIZE):
+                    batch = prepared_keys[offset : offset + _KEY_BATCH_SIZE]
+                    markers = ", ".join("?" for _ in batch)
+                    _execute(cursor, f"{select} WHERE {key_column} IN ({markers})", batch)
+                    for row in _rows(cursor, len(columns)):
+                        record = dict(zip(columns, row, strict=True))
+                        found[self._parsed_key(record[self.definition.key_field_storage_name])] = record
+                return [found[key] for raw in prepared_keys if (key := self._parsed_key(raw)) in found]
+
+            return await self._client.run(get_keys)
+        where, parameters = ("1 = 1", []) if filter is None else _FilterCompiler(self.definition).compile(filter)
+        parameters.extend((skip, top))
+        _check_parameter_count(parameters)
+        statement = f"{select} WHERE {where} ORDER BY {self._order_by(order_by)} OFFSET ? ROWS FETCH NEXT ? ROWS ONLY"
+
+        def get_page(cursor: mssql_python.Cursor) -> list[dict[str, Any]]:
+            _execute(cursor, statement, parameters)
+            return [dict(zip(columns, row, strict=True)) for row in _rows(cursor, len(columns))]
+
+        return await self._client.run(get_page)
+
+    async def _inner_delete(self, keys: Sequence[KeyT], *, operation_options: Mapping[str, Any] | None = None) -> None:
+        _validate_options(operation_options)
+        self._client.ensure_open()
+        prepared = [self._prepare_key(key) for key in keys]
+        if not prepared:
+            return
+        key_column = _quote_identifier(self.definition.key_field_storage_name)
+
+        def delete(cursor: mssql_python.Cursor) -> None:
+            for offset in range(0, len(prepared), _KEY_BATCH_SIZE):
+                batch = prepared[offset : offset + _KEY_BATCH_SIZE]
+                markers = ", ".join("?" for _ in batch)
+                _execute(cursor, f"DELETE FROM {self._table} WHERE {key_column} IN ({markers})", batch)  # nosec B608
+
+        await self._client.run(delete)
+
+    async def _inner_search(
+        self,
+        *,
+        search_type: SearchType,
+        filter: FilterExpression | None = None,
+        values: Any | None = None,
+        vector: Vector | None = None,
+        top: int = 3,
+        skip: int = 0,
+        include_vectors: bool = False,
+        vector_property_name: str | None = None,
+        additional_property_name: str | None = None,
+        score_threshold: float | None = None,
+        operation_options: Mapping[str, Any] | None = None,
+    ) -> SearchResults[Any]:
+        _validate_options(operation_options)
+        if search_type != "vector" or additional_property_name is not None:
+            raise NotImplementedError("SQL Server supports dense vector search only, not keyword-hybrid search.")
+        if vector is None:
+            raise NotImplementedError("SQL Server requires a vector or a local embedding generator.")
+        self._client.ensure_open()
+        resolved = self.definition.try_get_vector_field(vector_property_name)
+        if resolved is None:
+            raise ValueError("Select a vector_property_name from the collection definition.")
+        field = next(item for item in self._fields if item.name == resolved.name)
+        metric, result_kind = _metric_for(field)
+        where, filter_params = (
+            ("1 = 1", []) if filter is None else _FilterCompiler(self.definition, alias="t.").compile(filter)
+        )
+        column_names = self._column_names(include_vectors)
+        projections = ", ".join(f"t.{_quote_identifier(name)}" for name in column_names)
+        vector_column = f"t.{_quote_identifier(field.storage_name or field.name)}"
+        key_column = f"t.{_quote_identifier(self.definition.key_field_storage_name)}"
+        dimensions = field.dimensions
+        statement = (
+            f"SELECT {projections}, d.[distance] FROM {self._table} AS t "  # nosec B608
+            f"CROSS APPLY (VALUES (VECTOR_DISTANCE('{metric}', CAST(? AS VECTOR({dimensions})), "
+            f"{vector_column}))) AS d([distance]) "
+            f"WHERE {vector_column} IS NOT NULL AND ({where}) AND d.[distance] IS NOT NULL"
+        )
+        parameters: list[Any] = [_prepare_value(field, vector), *filter_params]
+        if score_threshold is not None:
+            if type(score_threshold) not in (int, float):
+                raise ValueError("score_threshold must be a finite number.")
+            try:
+                threshold = float(score_threshold)
+            except OverflowError as exc:
+                raise ValueError("score_threshold must be a finite number.") from exc
+            if not math.isfinite(threshold):
+                raise ValueError("score_threshold must be a finite number.")
+            cutoff = (
+                1 - threshold
+                if result_kind == "similarity"
+                else (-threshold if result_kind == "negative" else threshold)
+            )
+            statement += " AND d.[distance] <= ?"
+            parameters.append(cutoff)
+        statement += f" ORDER BY d.[distance] ASC, {key_column} ASC OFFSET ? ROWS FETCH NEXT ? ROWS ONLY"
+        parameters.extend((skip, top))
+        _check_parameter_count(parameters)
+
+        def search(cursor: mssql_python.Cursor) -> list[dict[str, Any]]:
+            _execute(cursor, statement, parameters)
+            results: list[dict[str, Any]] = []
+            for row in _rows(cursor, len(column_names) + 1):
+                distance = row[-1]
+                if type(distance) not in (float, int) or not math.isfinite(distance):
+                    raise IntegrationInvalidResponseException("SQL Server returned a non-finite vector distance.")
+                score = (
+                    1 - distance
+                    if result_kind == "similarity"
+                    else -distance
+                    if result_kind == "negative"
+                    else distance
+                )
+                results.append({"record": dict(zip(column_names, row[:-1], strict=True)), "score": float(score)})
+            return results
+
+        rows = await self._client.run(search)
+        return SearchResults(
+            rows,
+            metadata={"distance_function": field.distance_function or "DEFAULT", "approximate": False},
+        )
+
+    def _get_record_from_result(self, result: Any) -> Any:
+        return result["record"]
+
+    def _get_score_from_result(self, result: Any) -> float | None:
+        return cast(float, result["score"])
+
+
+class SqlServerStore(BaseVectorStore):
+    """Create SQL Server collections sharing one store-owned worker."""
+
+    def __init__(
+        self,
+        *,
+        connection_string: str | SecretString | None = None,
+        query_timeout: int | None = None,
+        schema: str = "dbo",
+        embedding_generator: EmbeddingClient | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+    ) -> None:
+        """Initialize a store without connecting to SQL Server.
+
+        Args:
+            connection_string: Driver connection string, or ``SQL_SERVER_CONNECTION_STRING``.
+            query_timeout: Optional per-statement timeout in seconds; ``0`` disables the timeout.
+            schema: Existing database schema used by all collections.
+            embedding_generator: Default local embedding generator.
+            env_file_path: Optional .env file.
+            env_file_encoding: Encoding of the selected .env file.
+        """
+        super().__init__(embedding_generator=embedding_generator, managed_client=True)
+        _quote_identifier(schema)
+        self.schema = schema
+        self._client = _create_client(
+            connection_string,
+            query_timeout=query_timeout,
+            env_file_path=env_file_path,
+            env_file_encoding=env_file_encoding,
+        )
+
+    def get_collection(
+        self,
+        record_type: type[ModelT],
+        *,
+        definition: VectorStoreCollectionDefinition | None = None,
+        collection_name: str | None = None,
+        embedding_generator: EmbeddingClient | None = None,
+    ) -> SqlServerCollection[Any, ModelT]:
+        """Create a collection sharing this store's owned worker and lifecycle."""
+        collection = SqlServerCollection(
+            record_type,
+            connection_string=self._client.connection_string,
+            query_timeout=self._client.query_timeout,
+            schema=self.schema,
+            definition=definition,
+            collection_name=collection_name,
+            embedding_generator=embedding_generator if embedding_generator is not None else self.embedding_generator,
+        )
+        # Collection construction does no I/O; reuse the store's lazy worker.
+        collection._client = self._client  # pyright: ignore[reportPrivateUsage]
+        collection.managed_client = False
+        return collection
+
+    async def list_collection_names(self, *, operation_options: Mapping[str, Any] | None = None) -> Sequence[str]:
+        """List base tables in the configured schema."""
+        _validate_options(operation_options)
+
+        def list_names(cursor: mssql_python.Cursor) -> list[str]:
+            _execute(
+                cursor,
+                "SELECT t.name FROM sys.tables AS t JOIN sys.schemas AS s ON s.schema_id = t.schema_id "
+                "WHERE s.name = ? ORDER BY t.name",
+                [self.schema],
+            )
+            names = _rows(cursor, 1)
+            if any(not isinstance(row[0], str) for row in names):
+                raise IntegrationInvalidResponseException("SQL Server returned a non-string table name.")
+            return [cast(str, row[0]) for row in names]
+
+        return await self._client.run(list_names)
+
+    async def _inner_ensure_collection_deleted(
+        self, collection_name: str, *, operation_options: Mapping[str, Any] | None = None
+    ) -> None:
+        _validate_options(operation_options)
+        table = f"{_quote_identifier(self.schema)}.{_quote_identifier(collection_name)}"
+        await self._client.run(lambda cursor: _execute(cursor, f"DROP TABLE IF EXISTS {table}"))
+
+    async def __aexit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None:
+        """Release store-owned resources."""
+        await self.close()
+
+    async def close(self) -> None:
+        """Wait for in-flight operations and shut down the store-owned worker."""
+        await self._client.close()

agent_framework_sql_server-1.0.0a261002.dist-info/METADATA

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: agent-framework-sql-server
+Version: 1.0.0a261002
+Summary: SQL Server native vector integration for Microsoft Agent Framework.
+Author-email: Microsoft <af-support@microsoft.com>
+Requires-Python: >=3.10,<3.15
+Description-Content-Type: text/markdown
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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
+Classifier: Typing :: Typed
+License-File: LICENSE
+Requires-Dist: agent-framework-core>=1.19.0,<2
+Requires-Dist: mssql-python>=1.15.0,<2
+Project-URL: homepage, https://aka.ms/agent-framework
+Project-URL: issues, https://github.com/microsoft/agent-framework/issues
+Project-URL: source, https://github.com/microsoft/agent-framework/tree/main/python
+
+# Agent Framework SQL Server vector store
+
+Store typed Agent Framework records in SQL Server and Azure SQL native `VECTOR`
+columns, with exact, database-side similarity search. This alpha package exports
+`SqlServerCollection`, `SqlServerStore`, `SqlServerSettings`, and
+`SqlServerCommittedCleanupException` directly from `agent_framework_sql_server`.
+
+## Install and provision
+
+```bash
+pip install agent-framework-sql-server --pre
+```
+
+Requires Python 3.10–3.14 and a vector-enabled database: SQL Server 2025
+(17.x), Azure SQL Database, Azure SQL Managed Instance on the SQL Server 2025
+or Always-up-to-date update policy, or SQL database in Microsoft Fabric.
+Older SQL Server releases do not support `VECTOR`/`VECTOR_DISTANCE`.
+
+The package uses Microsoft's [`mssql-python` 1.15+ driver](https://pypi.org/project/mssql-python/).
+It installs its `mssql-python-odbc` binary companion automatically; no external
+ODBC Driver 18 or driver manager is required. Published wheels cover CPython
+3.10–3.14 on Windows x64, Linux x64/ARM64, and **macOS 15+**
+Intel/Apple Silicon; Windows ARM64 wheels start at Python 3.11. macOS 14 is
+listed in the driver's support documentation, but the published macOS wheels
+are tagged `macosx_15_0_universal2` and there is no source distribution.
+Python 3.15 has no published wheel yet: this package caps `requires-python`
+below 3.15, and the repository's non-blocking 3.15 CI lane excludes it.
+The workspace lockfile likewise limits Python below 3.15 while this package
+remains a member; the experimental 3.15 lane excludes it before resolving.
+Follow the [driver's installation instructions](https://learn.microsoft.com/sql/connect/python/mssql-python/installation)
+for system libraries on Linux and OpenSSL on macOS.
+
+The database administrator must provide an existing schema (default `dbo`).
+`ensure_collection_exists()` creates the requested table and scalar indexes
+there but never creates a schema, alters an existing table, or changes database
+settings. `ensure_collection_deleted()` drops only that table.
+
+## Connection settings and ownership
+
+For local Azure SQL development with passwordless Microsoft Entra authentication,
+sign in with Azure CLI, then set the environment variable used by the
+[sample](samples/sql_server_vectors.py):
+
+```bash
+az login
+export SQL_SERVER_CONNECTION_STRING='Server=<host>;Database=<db>;Authentication=ActiveDirectoryDefault;Encrypt=yes;'
+```
+
+Replace `<host>` with the Azure SQL server hostname (for example,
+`my-server.database.windows.net`) and `<db>` with your existing database.
+`ActiveDirectoryDefault` uses the driver's credential chain, which can use
+your Azure CLI sign-in. The identity must be granted access to the database
+and permission to create a table and index in the configured schema and
+read/write its records. On an Azure-hosted app, use
+`Authentication=ActiveDirectoryMSI` for managed identity; add
+`UID=<client-id>` for a user-assigned identity. See
+[Microsoft's Entra authentication guide](https://learn.microsoft.com/sql/connect/python/mssql-python/entra-authentication)
+for setup, permissions, and other supported modes. This connector accepts
+connection strings, not the driver's `token_provider=` credential argument.
+
+Do not commit connection strings containing credentials. Alternatively, pass
+`connection_string` as a string or Agent Framework `SecretString` to
+`SqlServerStore` or `SqlServerCollection`. Settings precedence is **explicit
+argument > selected `.env` file > process environment**. To read a `.env` file
+in the run directory, pass `env_file_path=".env"` to `SqlServerStore` or
+`SqlServerCollection`; `env_file_encoding` is optional. Missing or empty
+connection strings are rejected.
+
+The connector owns all connections. Each whole operation opens, uses, commits
+or rolls back, and closes a `mssql-python` connection on a dedicated worker
+thread, keeping Agent Framework's async calls nonblocking. The driver's
+built-in pooling can reuse the underlying physical connection. A store and
+its collections share one worker; a standalone collection owns its own.
+Call `close()` or use an async context manager to release the worker. There is
+no `client=` or connection-factory constructor argument: arbitrary caller-owned
+`mssql-python` connections cannot safely cross threads (`threadsafety=1`).
+This is intentionally narrower than connectors that support borrowed async
+clients.
+
+Batch writes commit or roll back together on one connection. Cancelling an
+async operation waits for its worker to finish cleanup; it cannot interrupt an
+already-running synchronous SQL statement, and the transaction may already
+have committed. Set `query_timeout=30` (seconds, for example) on the store or
+collection when bounding database calls; leaving it unset uses the driver's
+default, and `0` disables the timeout. Prefer stable application-provided
+keys when retrying writes.
+If closing the connection fails after a successful commit,
+`SqlServerCommittedCleanupException` explicitly signals that the transaction
+**already committed**; do not automatically retry, especially with generated
+keys. Cancellation remains `CancelledError` even if the worker fails while
+finishing; that worker error is logged after cleanup.
+
+## Example
+
+With `SQL_SERVER_CONNECTION_STRING` configured, run the
+[typed sample](samples/sql_server_vectors.py) from the `python/` directory:
+
+```bash
+uv run --package agent-framework-sql-server \
+    python packages/sql-server/samples/sql_server_vectors.py
+```
+
+The sample creates a uniquely named table, upserts precomputed embeddings,
+filters/ranks in SQL Server, retrieves an optional vector, and drops its own
+table. Pass `generate_vectors=False` to preserve precomputed vectors; to
+generate them locally, configure an `embedding_generator`.
+
+## Capabilities and limits
+
+The connector supports typed decorated models and dictionary definitions;
+string/integer/UUID keys (including generated keys); multiple nullable float32
+vector columns with **1–1998 dimensions**; field storage aliases; batch
+upsert/get/delete; paged and ordered retrieval; scalar data indexes; and
+parameterized top-level `Filter`/`FilterGroup` expressions. String keys cannot
+end with a space because SQL Server ignores trailing spaces in key comparisons.
+Indexed strings use `NVARCHAR(450)`; other strings use `NVARCHAR(MAX)`. List and
+dictionary fields are stored as JSON, and timezone-aware `datetime` values are
+normalized to UTC in `DATETIME2(7)` columns.
+For an auto-generated integer (`IDENTITY`) key, omit the key on insert;
+explicit keys can update existing rows but cannot create new identity rows.
+
+Supported filters: scalar `eq`, `ne`, `in`, `not_in`, `is_null`, `is_not_null`,
+`exists`; numeric/date/datetime `gt`, `gte`, `lt`, `lte`, `between`; and string
+`starts_with`, `ends_with`, `contains_text`. `AND`/`OR`/`NOT` groups preserve
+two-valued null semantics; string equality is byte-exact and text patterns
+escape SQL Server wildcards. JSON fields support `is_null`, `is_not_null`, and
+`exists`, **not** equality or collection-membership filters. Nested paths,
+full-text filtering, and unknown operation options fail explicitly. The SQL
+Server 2100-parameter limit is respected by batching key reads/deletes and
+limiting other statements to 2000 bound parameters.
+
+Search uses SQL Server's exact `VECTOR_DISTANCE` on native `VECTOR` columns,
+with filters and score thresholds applied **before** offset/limit. The default
+metric is cosine **distance** (lower is better). Euclidean and negative dot
+product also return distances (maximum thresholds); `cosine_similarity` and
+`dot_prod` return similarity/positive-dot scores (minimum thresholds).
+Scores are raw metric units, not probabilities. Retrieval excludes vectors by
+default; use `include_vectors=True` to return them. Approximate DiskANN
+indexes/search, preview-only float16 vectors, keyword-hybrid search, sparse or
+binary vectors, server-side embedding generation, and schema migration are
+not supported.
+
+The server stores native `VECTOR` columns, but `mssql-python` 1.15 does not
+expose a native Python vector type. The connector binds JSON-encoded vectors
+as parameters and parses JSON on retrieval; SQL Server converts to/from the
+native type. It does not enable native driver vector bindings.
+
+## Service tests
+
+Unit tests need no database. Integration tests are opt-in: set
+`SQL_SERVER_TEST_CONNECTION_STRING` to a deliberately designated test database
+with table creation permissions and run:
+
+```bash
+uv run --package agent-framework-sql-server pytest \
+    packages/sql-server/tests/sql_server/test_integration.py -m integration
+```
+
+The tests create uniquely named tables and remove only those tables. They
+skip when the variable is absent or empty (including an unconfigured CI
+secret), and fail rather than silently skipping when an explicitly
+designated server lacks vector support.
+
+## References
+
+- [SQL Server vector type and database availability](https://learn.microsoft.com/sql/t-sql/data-types/vector-data-type)
+- [Exact vector distance metrics](https://learn.microsoft.com/sql/t-sql/functions/vector-distance-transact-sql)
+- [Microsoft's Python vector JSON example](https://learn.microsoft.com/sql/t-sql/data-types/vector-data-type#python)
+- [mssql-python asynchronous integration patterns](https://learn.microsoft.com/sql/connect/python/mssql-python/asynchronous-patterns)
+- [Microsoft Agent Framework](https://learn.microsoft.com/agent-framework/)
+

agent_framework_sql_server-1.0.0a261002.dist-info/RECORD

@@ -0,0 +1,8 @@
+agent_framework_sql_server/__init__.py,sha256=FU0pnNvCvhVvurpIk5Hw8_okV76LbuNhbPSdkeduJ4U,591
+agent_framework_sql_server/_sql.py,sha256=19Lidl8195aeBgXuJa-88s293uh2lLoBDVR7bp3Hrmc,16911
+agent_framework_sql_server/_vector_store.py,sha256=Wvz_akkjiy3Y93eprkGzeoOTQ87OUdbsZEGY6vNXYSg,32658
+agent_framework_sql_server/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_framework_sql_server-1.0.0a261002.dist-info/licenses/LICENSE,sha256=ws_MuBL-SCEBqPBFl9_FqZkaaydIJmxHrJG2parhU4M,1141
+agent_framework_sql_server-1.0.0a261002.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+agent_framework_sql_server-1.0.0a261002.dist-info/METADATA,sha256=kunrA6pFHYxmG5yR3YsHsOiF0vKRGCOzd02B0EkcccE,10514
+agent_framework_sql_server-1.0.0a261002.dist-info/RECORD,,

agent_framework_sql_server-1.0.0a261002.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: flit 3.12.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_framework_sql_server-1.0.0a261002.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    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