Python: Add Azure DocumentDB vector store connector

python/PACKAGE_STATUS.md

@@ -20,6 +20,7 @@ Status is grouped into these buckets:
 | `agent-framework-anthropic` | `python/packages/anthropic` | `beta` |
 | `agent-framework-azure-contentunderstanding` | `python/packages/azure-contentunderstanding` | `beta` |
 | `agent-framework-azure-ai-search` | `python/packages/azure-ai-search` | `beta` |
+| `agent-framework-azure-documentdb` | `python/packages/azure-documentdb` | `alpha` |
 | `agent-framework-azure-cosmos` | `python/packages/azure-cosmos` | `beta` |
 | `agent-framework-azure-cosmos-memory` | `python/packages/azure-cosmos-memory` | `alpha` |
 | `agent-framework-bedrock` | `python/packages/bedrock` | `beta` |

python/packages/azure-documentdb/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.

python/packages/azure-documentdb/README.md

@@ -0,0 +1,114 @@
+# Agent Framework Azure DocumentDB
+
+Store and search vector records in
+[Azure DocumentDB](https://learn.microsoft.com/azure/documentdb/) with this
+alpha integration for
+[Microsoft Agent Framework](https://learn.microsoft.com/agent-framework/).
+The package uses PyMongo's stable asynchronous API and Azure DocumentDB's
+Mongo-compatible `$search.cosmosSearch` dialect.
+
+- **`AzureDocumentDBCollection`** provides batch CRUD, metadata filters, index reconciliation, and vector search.
+- **`AzureDocumentDBStore`** creates collection clients sharing one resolved database.
+- **`AzureDocumentDBSettings`** defines the two Agent Framework-managed connection settings.
+
+## Installation
+
+```bash
+pip install agent-framework-azure-documentdb --pre
+```
+
+Requires Python 3.10+, PyMongo 4.13+, and an Azure DocumentDB cluster. IVF
+indexes are intended for smaller datasets and M10/M20 tiers. HNSW and DiskANN
+require M30 or higher; consult the current service documentation before choosing
+a production tier.
+
+## Authentication and setup
+
+Set `AZURE_DOCUMENTDB_CONNECTION_STRING` to the connection string from the
+Azure portal and `AZURE_DOCUMENTDB_DATABASE_NAME` to an existing or intended
+database. Settings precedence is explicit constructor value, selected `.env`
+file, then process environment. Connection strings are held in Agent Framework
+`SecretString` values.
+
+Connector-created clients enforce TLS, disable retryable writes, and set an
+application name. They are closed by `aclose()` or an async context manager.
+An injected PyMongo `AsyncMongoClient`, `AsyncDatabase`, or `AsyncCollection`
+remains caller-owned and bypasses settings loading.
+
+The identity running `ensure_collection_exists()` needs permission to create
+collections and indexes. Each filtered data field must declare
+`is_indexed=True`; the connector creates its ordinary ascending index alongside
+separate vector indexes.
+
+## Example
+
+```python
+import asyncio
+from dataclasses import dataclass
+from typing import Annotated
+
+from agent_framework import Filter, VectorStoreField, vectorstoremodel
+from agent_framework_azure_documentdb import AzureDocumentDBStore
+
+
+@vectorstoremodel(collection_name="articles")
+@dataclass
+class Article:
+    id: Annotated[str, VectorStoreField("key")]
+    category: Annotated[str, VectorStoreField("data", is_indexed=True)]
+    embedding: Annotated[
+        list[float] | None,
+        VectorStoreField("vector", dimensions=3, index_kind="ivf_flat"),
+    ] = None
+
+
+async def main() -> None:
+    async with AzureDocumentDBStore() as store:
+        collection = store.get_collection(Article)
+        await collection.ensure_collection_exists()
+        await collection.upsert(
+            [Article("one", "database", [1.0, 0.0, 0.0])],
+            generate_vectors=False,
+        )
+        results = await collection.search(
+            vector=[1.0, 0.0, 0.0],
+            filter=Filter("category", "eq", "database"),
+        )
+        async for result in results:
+            print(result["record"], result["score"])
+
+
+asyncio.run(main())
+```
+
+## Limits
+
+The connector supports explicit string and signed 64-bit integer `_id` keys,
+multiple top-level dense vector fields, storage aliases, IVF/HNSW/DiskANN
+indexes, native metadata filters, server-side paging, and native `searchScore`
+values. Generated ObjectIds, ordered retrieval, hybrid/full-text search,
+sparse/binary vectors, nested field paths, compressed vectors, and automatic
+schema/index migration are not supported.
+
+The core `default` index kind maps to IVF so it does not silently require an
+M30+ tier. Select `hnsw` or `disk_ann` explicitly when those service contracts
+and cluster requirements are appropriate.
+
+Vector dimensions are conservatively limited to the service's 2,000-dimension
+standard-vector contract. Azure DocumentDB also offers higher limits with
+half-precision or product quantization; those distinct index/storage options are
+outside this connector.
+
+`score_threshold` uses native metric units after `$search` selects its `k`
+candidates and before `$skip`/`$limit`. It is a minimum for cosine and inner
+product scores, where larger is better, and a maximum for Euclidean distance,
+where smaller is better. Set a larger `operation_options={"k": ...}` candidate
+window when needed. Thresholded ANN search can return fewer than `top`; the
+connector does not fetch or filter a client-side prefix. Algorithm tuning uses
+`n_probes`, `ef_search`, or `l_search` for IVF, HNSW, or DiskANN respectively.
+
+See the
+[Azure DocumentDB vector search guide](https://learn.microsoft.com/azure/documentdb/vector-search),
+[Azure DocumentDB limits](https://learn.microsoft.com/azure/documentdb/limitations),
+[PyMongo async API](https://pymongo.readthedocs.io/en/stable/api/pymongo/asynchronous/),
+and [Agent Framework documentation](https://learn.microsoft.com/agent-framework/).

python/packages/azure-documentdb/agent_framework_azure_documentdb/__init__.py

@@ -0,0 +1,21 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Azure DocumentDB vector collections and stores."""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+from ._vector_store import AzureDocumentDBCollection, AzureDocumentDBSettings, AzureDocumentDBStore
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "AzureDocumentDBCollection",
+    "AzureDocumentDBSettings",
+    "AzureDocumentDBStore",
+    "__version__",
+]