Python: Add Azure DocumentDB vector store connector

[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

Agent Framework needs a first-class Azure DocumentDB vector-store connector so Python applications can keep embeddings and source documents together while using the service's Mongo-compatible transport and DocumentDB-specific vector-search dialect. This contributes typed CRUD, metadata filtering, and dense retrieval for RAG and agent-memory scenarios without treating Azure DocumentDB as MongoDB Atlas or Azure Cosmos DB for NoSQL.

Description & Review Guide

• What are the major changes? Adds the alpha agent-framework-azure-documentdb package with direct imports, PyMongo's stable AsyncMongoClient transport, createIndexes/cosmosSearchOptions lifecycle support for IVF, HNSW, and DiskANN, and $search.cosmosSearch query pipelines. The collection supports explicit BSON string/integer keys, multiple vector paths, storage aliases, type-aware BSON metadata filters, native score thresholds before server-side paging, bounded/chunked batch operations, settings precedence, and caller-owned client/database/collection injection. The package also includes a concise consumer README, a package-local sample, workspace/package-status/lock registration, unit and command-capture coverage, and a credential-gated managed integration scenario.
• What is the impact of these changes? Python users can opt into Azure DocumentDB vector storage without changing the stable core install surface; the alpha package is intentionally excluded from core[all] and lazy namespaces. Existing applications are unaffected. The connector rejects unsupported key coercion, hybrid/full-text search, nested filter paths, compressed vectors, and incompatible existing indexes rather than silently changing semantics. It uses the existing Python package syntax, unit, typing, and build CI paths; no fake-green managed-service job is added.
• What do you want reviewers to focus on? Please focus on the DocumentDB-specific index reconciliation and $search.cosmosSearch pipeline, portable filter missing/null/bool-number semantics, native threshold/paging behavior, batch preflight/partial-write reporting, and created-versus-injected client ownership. Managed ARM provisioning was exercised successfully on disposable M10/server-8.0 resources, but the restricted data-plane TLS handshake could not be established; all resources were deleted, and this PR does not claim managed query execution validation.

Related Issue

Related to #4168 and #1188.

This is the Azure DocumentDB-only partial contribution and intentionally does not close either umbrella because other Phase 6 connectors remain. The open #8184 covers the separate MongoDB connector and does not overlap this package or service contract. The issue-exclusivity checklist item remains unchecked because these umbrella issues intentionally have parallel independent connector PRs.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above). This is intentionally unchecked because Python: Phase 6: Vector Store Connectors — Tier 2 (MongoDB, Cosmos DB, Pinecone, Chroma, Weaviate) #4168 and Python SDK : Add native vector database connectors and retrieval patterns #1188 are umbrella issues with parallel connector contributions.
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): fb8faddc5a41
Model: gpt-5.6-sol-fast

Overview

The PR adds a carefully validated Azure DocumentDB vector-store package with strong BSON/type preflight, explicit client ownership, bounded batch calls, index reconciliation, and broad unit coverage. One compatibility gap remains: the connector reuses Mongo query operators inside DocumentDB's distinct cosmosSearch filter dialect, causing negative filtered vector searches to fail.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
1 verified finding remained after source verification (1 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/azure-documentdb/agent_framework_azure_documentdb/_vector_store.py

[Copilot]

🟡 Changes recommended

The vector prefilter emits the wrong inequality dialect, and the sample command bypasses the local workspace package.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds an alpha Azure DocumentDB vector-store connector for Python, supporting typed CRUD, metadata filtering, index management, and vector search.

Changes:

• Implements the DocumentDB collection/store and configuration APIs.
• Adds documentation, packaging, and a runnable sample.
• Adds unit and credential-gated integration coverage.

File summaries

File	Description
python/uv.lock	Locks the connector and PyMongo.
python/pyproject.toml	Registers the workspace package.
python/PACKAGE_STATUS.md	Marks the package alpha.
python/packages/azure-documentdb/pyproject.toml	Defines package metadata and tooling.
python/packages/azure-documentdb/LICENSE	Adds the MIT license.
python/packages/azure-documentdb/README.md	Documents setup, usage, and limits.
python/packages/azure-documentdb/agent_framework_azure_documentdb/__init__.py	Exposes the public API.
python/packages/azure-documentdb/agent_framework_azure_documentdb/_vector_store.py	Implements connector behavior.
python/packages/azure-documentdb/agent_framework_azure_documentdb/py.typed	Marks the package typed.
python/packages/azure-documentdb/samples/README.md	Documents sample execution.
python/packages/azure-documentdb/samples/azure_documentdb_vectors.py	Demonstrates vector operations.
python/packages/azure-documentdb/tests/azure_documentdb/conftest.py	Provides test fixtures.
python/packages/azure-documentdb/tests/azure_documentdb/test_vector_store.py	Covers CRUD, filters, indexes, and search.
python/packages/azure-documentdb/tests/azure_documentdb/test_settings.py	Covers settings and ownership.
python/packages/azure-documentdb/tests/azure_documentdb/test_integration.py	Adds managed-service integration coverage.

Review details

• Files reviewed: 13/15 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.