agent-framework-mongodb 1.0.0a260918__tar.gz

agent_framework_mongodb-1.0.0a260918/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.

agent_framework_mongodb-1.0.0a260918/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: agent-framework-mongodb
+Version: 1.0.0a260918
+Summary: MongoDB vector stores for Microsoft Agent Framework.
+Author-email: Microsoft <af-support@microsoft.com>
+Requires-Python: >=3.10
+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: pymongo>=4.13.2,<5
+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
+
+# MongoDB vector stores
+
+An alpha MongoDB integration for [Microsoft Agent Framework](https://learn.microsoft.com/agent-framework/).
+`MongoDBCollection` provides async BSON CRUD and dense-vector search,
+`MongoDBStore` shares an official async PyMongo client across collections, and
+`MongoDBSettings` defines connection configuration.
+
+## Installation
+
+```bash
+pip install agent-framework-mongodb --pre
+```
+
+Requires Python 3.10+, PyMongo 4.13.2+, and a MongoDB deployment with
+[MongoDB Vector Search](https://www.mongodb.com/docs/vector-search/). Search-index
+creation requires the corresponding database permissions.
+
+## Connection
+
+Set `MONGODB_URI` and `MONGODB_DATABASE_NAME`; `MONGODB_APP_NAME` is optional.
+Constructors resolve explicit arguments first, then an explicitly selected
+`.env` file, then process environment variables. URIs accept `str` or AF
+`SecretString` and are unwrapped only for PyMongo.
+
+You can instead inject an `AsyncMongoClient` and pass `database_name`. An
+injected client bypasses URI, app-name, and `.env` loading and always remains
+caller-owned. Connector-created clients are closed by `close()` or async context
+exit. Collections created by a store borrow its already-resolved client.
+
+## Example
+
+```python
+import asyncio
+from dataclasses import dataclass
+from typing import Annotated
+
+from agent_framework import Filter, VectorStoreField, vectorstoremodel
+from agent_framework_mongodb import MongoDBStore
+
+
+@vectorstoremodel(collection_name="articles")
+@dataclass
+class Article:
+    id: Annotated[str, VectorStoreField("key")]
+    topic: Annotated[str, VectorStoreField("data", is_indexed=True)]
+    text: Annotated[str, VectorStoreField("data")]
+    embedding: Annotated[list[float] | None, VectorStoreField("vector", dimensions=3)] = None
+
+
+async def main() -> None:
+    async with MongoDBStore() as store:
+        collection = store.get_collection(Article)
+        await collection.ensure_collection_exists()
+        await collection.upsert(
+            [Article("1", "database", "MongoDB stores BSON documents", [1, 0, 0])],
+            generate_vectors=False,
+        )
+        results = await collection.search(
+            vector=[1, 0, 0],
+            filter=Filter("topic", "eq", "database"),
+        )
+        async for result in results:
+            print(result["record"].text, result["score"])
+
+
+asyncio.run(main())
+```
+
+## Capabilities and limits
+
+- String, signed 64-bit integer, and BSON `ObjectId` `_id` values retain native
+  identity. Only `ObjectId` keys can be generated. Typed `ObjectId` models must
+  register an encoder and decoder that preserve `ObjectId`; IDs are never stringified
+  or copied to hidden fields in storage. Agent-facing CRUD tool JSON represents
+  `ObjectId` keys as validated 24-character hexadecimal strings and converts them
+  back to native values at the collection boundary.
+- Multiple top-level dense-vector fields are supported through one vector-search
+  index per field. Use `provider_annotations={"mongodb.index_name": "..."}` to
+  select an existing index name. Dimensions must be 1-8192. Metrics are cosine,
+  dot product, and Euclidean; returned `vectorSearchScore` values are native
+  normalized relevance scores where larger is better.
+- `ensure_collection_exists()` creates missing indexes, waits for readiness, and
+  validates existing semantic definitions. It never updates or migrates an
+  incompatible collection or index. Newly written documents become searchable
+  asynchronously, even after an index is queryable.
+- Retrieval filters preserve whole-value equality, missing/null, direct array
+  membership, boolean/number, and literal text semantics with server-side
+  expressions. Collection filters require fields declared as `list` and reject
+  mapping and non-list collection operands whose identity BSON cannot preserve.
+  Vector prefilters are intentionally narrower: indexed scalar equality, range,
+  membership, AND, and OR only. Nested paths, NOT, null/missing, list membership,
+  and literal/analyzed text are rejected for vector search.
+- Keyword-hybrid search, sparse/binary vectors, provider-side embedding
+  generation, and automatic schema migration are not supported.
+- ANN defaults `numCandidates` to the MongoDB recommendation of 20 times
+  `skip + top`, capped at MongoDB's maximum of 10,000. Explicit values must be
+  1-10,000 and at least `skip + top`; larger result windows require exact search.
+  The vector stage selects its result window before score thresholding, skip,
+  and limit, so selective thresholds can underfill a page. Deep offsets increase
+  server cost; result prefixes are never materialized by the connector.
+- Every record is fully validated against BSON's signed 64-bit integer and 16 MiB
+  document limits before any batch write. PyMongo then chunks bulk writes using
+  negotiated server limits. A server error can leave a successful prefix
+  (`ordered=True`) or subset (`ordered=False`) persisted.
+
+## Documentation
+
+- [Microsoft Agent Framework documentation](https://learn.microsoft.com/agent-framework/)
+- [MongoDB Vector Search documentation](https://www.mongodb.com/docs/vector-search/)
+- [PyMongo async documentation](https://pymongo.readthedocs.io/en/stable/api/pymongo/asynchronous/)
+- [MongoDB limits and thresholds](https://www.mongodb.com/docs/manual/reference/limits/)
+

agent_framework_mongodb-1.0.0a260918/README.md

@@ -0,0 +1,111 @@
+# MongoDB vector stores
+
+An alpha MongoDB integration for [Microsoft Agent Framework](https://learn.microsoft.com/agent-framework/).
+`MongoDBCollection` provides async BSON CRUD and dense-vector search,
+`MongoDBStore` shares an official async PyMongo client across collections, and
+`MongoDBSettings` defines connection configuration.
+
+## Installation
+
+```bash
+pip install agent-framework-mongodb --pre
+```
+
+Requires Python 3.10+, PyMongo 4.13.2+, and a MongoDB deployment with
+[MongoDB Vector Search](https://www.mongodb.com/docs/vector-search/). Search-index
+creation requires the corresponding database permissions.
+
+## Connection
+
+Set `MONGODB_URI` and `MONGODB_DATABASE_NAME`; `MONGODB_APP_NAME` is optional.
+Constructors resolve explicit arguments first, then an explicitly selected
+`.env` file, then process environment variables. URIs accept `str` or AF
+`SecretString` and are unwrapped only for PyMongo.
+
+You can instead inject an `AsyncMongoClient` and pass `database_name`. An
+injected client bypasses URI, app-name, and `.env` loading and always remains
+caller-owned. Connector-created clients are closed by `close()` or async context
+exit. Collections created by a store borrow its already-resolved client.
+
+## Example
+
+```python
+import asyncio
+from dataclasses import dataclass
+from typing import Annotated
+
+from agent_framework import Filter, VectorStoreField, vectorstoremodel
+from agent_framework_mongodb import MongoDBStore
+
+
+@vectorstoremodel(collection_name="articles")
+@dataclass
+class Article:
+    id: Annotated[str, VectorStoreField("key")]
+    topic: Annotated[str, VectorStoreField("data", is_indexed=True)]
+    text: Annotated[str, VectorStoreField("data")]
+    embedding: Annotated[list[float] | None, VectorStoreField("vector", dimensions=3)] = None
+
+
+async def main() -> None:
+    async with MongoDBStore() as store:
+        collection = store.get_collection(Article)
+        await collection.ensure_collection_exists()
+        await collection.upsert(
+            [Article("1", "database", "MongoDB stores BSON documents", [1, 0, 0])],
+            generate_vectors=False,
+        )
+        results = await collection.search(
+            vector=[1, 0, 0],
+            filter=Filter("topic", "eq", "database"),
+        )
+        async for result in results:
+            print(result["record"].text, result["score"])
+
+
+asyncio.run(main())
+```
+
+## Capabilities and limits
+
+- String, signed 64-bit integer, and BSON `ObjectId` `_id` values retain native
+  identity. Only `ObjectId` keys can be generated. Typed `ObjectId` models must
+  register an encoder and decoder that preserve `ObjectId`; IDs are never stringified
+  or copied to hidden fields in storage. Agent-facing CRUD tool JSON represents
+  `ObjectId` keys as validated 24-character hexadecimal strings and converts them
+  back to native values at the collection boundary.
+- Multiple top-level dense-vector fields are supported through one vector-search
+  index per field. Use `provider_annotations={"mongodb.index_name": "..."}` to
+  select an existing index name. Dimensions must be 1-8192. Metrics are cosine,
+  dot product, and Euclidean; returned `vectorSearchScore` values are native
+  normalized relevance scores where larger is better.
+- `ensure_collection_exists()` creates missing indexes, waits for readiness, and
+  validates existing semantic definitions. It never updates or migrates an
+  incompatible collection or index. Newly written documents become searchable
+  asynchronously, even after an index is queryable.
+- Retrieval filters preserve whole-value equality, missing/null, direct array
+  membership, boolean/number, and literal text semantics with server-side
+  expressions. Collection filters require fields declared as `list` and reject
+  mapping and non-list collection operands whose identity BSON cannot preserve.
+  Vector prefilters are intentionally narrower: indexed scalar equality, range,
+  membership, AND, and OR only. Nested paths, NOT, null/missing, list membership,
+  and literal/analyzed text are rejected for vector search.
+- Keyword-hybrid search, sparse/binary vectors, provider-side embedding
+  generation, and automatic schema migration are not supported.
+- ANN defaults `numCandidates` to the MongoDB recommendation of 20 times
+  `skip + top`, capped at MongoDB's maximum of 10,000. Explicit values must be
+  1-10,000 and at least `skip + top`; larger result windows require exact search.
+  The vector stage selects its result window before score thresholding, skip,
+  and limit, so selective thresholds can underfill a page. Deep offsets increase
+  server cost; result prefixes are never materialized by the connector.
+- Every record is fully validated against BSON's signed 64-bit integer and 16 MiB
+  document limits before any batch write. PyMongo then chunks bulk writes using
+  negotiated server limits. A server error can leave a successful prefix
+  (`ordered=True`) or subset (`ordered=False`) persisted.
+
+## Documentation
+
+- [Microsoft Agent Framework documentation](https://learn.microsoft.com/agent-framework/)
+- [MongoDB Vector Search documentation](https://www.mongodb.com/docs/vector-search/)
+- [PyMongo async documentation](https://pymongo.readthedocs.io/en/stable/api/pymongo/asynchronous/)
+- [MongoDB limits and thresholds](https://www.mongodb.com/docs/manual/reference/limits/)

agent_framework_mongodb-1.0.0a260918/agent_framework_mongodb/__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Async MongoDB vector collections and stores."""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+from ._vector_store import MongoDBCollection, MongoDBSettings, MongoDBStore
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["MongoDBCollection", "MongoDBSettings", "MongoDBStore", "__version__"]