diff --git a/python/packages/qdrant/README.md b/python/packages/qdrant/README.md index 87bf7f14c8d..ce4df4ce044 100644 --- a/python/packages/qdrant/README.md +++ b/python/packages/qdrant/README.md @@ -23,9 +23,9 @@ then an optional `env_file_path`, then environment variables. API keys accept `str` or AF `SecretString` and are unwrapped only when creating the SDK client. You can instead pass a configured `AsyncQdrantClient` as `async_client` for -advanced SDK options. Supplied clients bypass settings loading and remain -caller-owned unless `managed_client=True`; connector-created clients are closed -on async context exit. +advanced SDK options. An injected client takes precedence over URL, API-key, +and `.env` settings and always remains caller-owned. Connector-created clients +are closed on async context exit. ## Usage diff --git a/python/packages/qdrant/agent_framework_qdrant/_vector_store.py b/python/packages/qdrant/agent_framework_qdrant/_vector_store.py index 35bb5e62743..e1ac6936ccf 100644 --- a/python/packages/qdrant/agent_framework_qdrant/_vector_store.py +++ b/python/packages/qdrant/agent_framework_qdrant/_vector_store.py @@ -74,6 +74,34 @@ def _create_client( ) +def _resolve_client( + async_client: AsyncQdrantClient | None, + *, + url: str | None, + api_key: str | SecretString | None, + managed_client: bool | None, + env_file_path: str | None, + env_file_encoding: str | None, +) -> tuple[AsyncQdrantClient, bool]: + """Return the client and whether this connector closes it. + + An injected client is returned unchanged. URL, API key, and ``.env`` options + are not read, and the caller keeps ownership even when ``managed_client`` is set. + Connector-created clients are owned unless ``managed_client`` is false. + """ + if async_client is not None: + return async_client, False + return ( + _create_client( + url=url, + api_key=api_key, + env_file_path=env_file_path, + env_file_encoding=env_file_encoding, + ), + True if managed_client is None else managed_client, + ) + + _DISTANCES = { "DEFAULT": models.Distance.COSINE, "cosine_similarity": models.Distance.COSINE, @@ -327,7 +355,7 @@ class QdrantCollection(BaseVectorCollection[KeyT, ModelT], BaseVectorSearch[KeyT All dense fields are named vectors. The default metric is cosine similarity (larger is better), not cosine distance. Scores and thresholds retain native - Qdrant units. Supplied clients remain caller-owned unless explicitly managed. + Qdrant units. Supplied clients remain caller-owned. Portable filters require a server: Qdrant's local emulator has different null/missing and numeric matching behavior across supported SDK versions. @@ -359,34 +387,33 @@ def __init__( definition: Explicit dictionary schema. collection_name: Collection name, overriding the model name. embedding_generator: Default local embedding client. - async_client: Existing async client, borrowed by default. Use this for local mode or advanced configuration. - url: Server URL override; otherwise loaded from QdrantSettings, then the SDK defaults to localhost. - api_key: API key override as a string or SecretString; otherwise loaded from QdrantSettings. - managed_client: Whether to close the client. Defaults to True only for connector-created clients. + async_client: Existing async client for local mode or advanced configuration. When supplied, URL, + API-key, and .env options are ignored and the client remains caller-owned. + url: Server URL override used when creating a client; otherwise loaded from QdrantSettings, then the SDK + defaults to localhost. + api_key: API key override as a string or SecretString, used when creating a client; otherwise loaded from + QdrantSettings. + managed_client: Whether to close a connector-created client. Defaults to True. Ignored for an injected + client, which always remains caller-owned. env_file_path: Optional .env file to load before process environment variables. env_file_encoding: Encoding for the .env file; defaults to UTF-8. """ - if async_client is not None and any( - value is not None for value in (url, api_key, env_file_path, env_file_encoding) - ): - raise ValueError("Pass async_client or connection settings, not both.") super().__init__( record_type, definition=definition, collection_name=collection_name, embedding_generator=embedding_generator, - managed_client=async_client is None if managed_client is None else managed_client, ) - self.async_client = ( - async_client - if async_client is not None - else _create_client( - url=url, - api_key=api_key, - env_file_path=env_file_path, - env_file_encoding=env_file_encoding, - ) + resolved_client, owns_client = _resolve_client( + async_client, + url=url, + api_key=api_key, + managed_client=managed_client, + env_file_path=env_file_path, + env_file_encoding=env_file_encoding, ) + self.async_client = resolved_client + self.managed_client = owns_client self._closed = False @property @@ -817,32 +844,31 @@ def __init__( """Initialize a store. Args: - async_client: Existing async client; borrowed unless managed_client=True. - url: Server URL override; otherwise loaded from QdrantSettings, then the SDK defaults to localhost. - api_key: API key override as a string or SecretString; otherwise loaded from QdrantSettings. + async_client: Existing async client. When supplied, URL, API-key, and .env options are ignored and the + client remains caller-owned. + url: Server URL override used when creating a client; otherwise loaded from QdrantSettings, then the SDK + defaults to localhost. + api_key: API key override as a string or SecretString, used when creating a client; otherwise loaded from + QdrantSettings. embedding_generator: Default embedding client inherited by collections. - managed_client: Whether to close the client. Defaults to True for connector-created clients. + managed_client: Whether to close a connector-created client. Defaults to True. Ignored for an injected + client, which always remains caller-owned. env_file_path: Optional .env file to load before process environment variables. env_file_encoding: Encoding for the .env file; defaults to UTF-8. """ - if async_client is not None and any( - value is not None for value in (url, api_key, env_file_path, env_file_encoding) - ): - raise ValueError("Pass async_client or connection settings, not both.") + resolved_client, owns_client = _resolve_client( + async_client, + url=url, + api_key=api_key, + managed_client=managed_client, + env_file_path=env_file_path, + env_file_encoding=env_file_encoding, + ) super().__init__( embedding_generator=embedding_generator, - managed_client=async_client is None if managed_client is None else managed_client, - ) - self.async_client = ( - async_client - if async_client is not None - else _create_client( - url=url, - api_key=api_key, - env_file_path=env_file_path, - env_file_encoding=env_file_encoding, - ) + managed_client=owns_client, ) + self.async_client = resolved_client self._closed = False def get_collection( diff --git a/python/packages/qdrant/tests/qdrant/conftest.py b/python/packages/qdrant/tests/qdrant/conftest.py index 47bff63a300..81d5c723f45 100644 --- a/python/packages/qdrant/tests/qdrant/conftest.py +++ b/python/packages/qdrant/tests/qdrant/conftest.py @@ -97,15 +97,18 @@ def make(record_type=dict, *, definition=definition, embedding_generator=None): async def server_collection(definition): if not os.getenv("QDRANT_TEST_URL"): pytest.skip("Set QDRANT_TEST_URL to a disposable Qdrant server.") - async with QdrantCollection( - dict, - definition=definition, - collection_name=f"af_qdrant_test_{uuid4().hex}", - async_client=AsyncQdrantClient(url=os.environ["QDRANT_TEST_URL"], check_compatibility=False), - managed_client=True, - ) as collection: - await collection.ensure_collection_exists() - try: - yield collection - finally: - await collection.ensure_collection_deleted() + client = AsyncQdrantClient(url=os.environ["QDRANT_TEST_URL"], check_compatibility=False) + try: + async with QdrantCollection( + dict, + definition=definition, + collection_name=f"af_qdrant_test_{uuid4().hex}", + async_client=client, + ) as collection: + await collection.ensure_collection_exists() + try: + yield collection + finally: + await collection.ensure_collection_deleted() + finally: + await client.close() diff --git a/python/packages/qdrant/tests/qdrant/test_collection.py b/python/packages/qdrant/tests/qdrant/test_collection.py index 33b6d159aa0..60405887ebf 100644 --- a/python/packages/qdrant/tests/qdrant/test_collection.py +++ b/python/packages/qdrant/tests/qdrant/test_collection.py @@ -313,10 +313,22 @@ async def test_client_ownership(definition): ): pass client.close.assert_not_awaited() - async with QdrantStore(async_client=client, managed_client=True) as owner: - pass + async with QdrantStore(async_client=client, url="https://ignored.example", managed_client=True) as owner: + assert owner.async_client is client + assert not owner.managed_client await owner.aclose() - client.close.assert_awaited_once() + async with QdrantCollection( + dict, + definition=definition, + collection_name="test", + async_client=client, + api_key="ignored-key", + managed_client=True, + ) as injected: + assert injected.async_client is client + assert not injected.managed_client + await injected.aclose() + client.close.assert_not_awaited() client.reset_mock() with patch("agent_framework_qdrant._vector_store.AsyncQdrantClient", return_value=client): async with QdrantCollection( @@ -364,24 +376,32 @@ async def test_api_key_unwrapped_at_sdk_boundary( @pytest.mark.parametrize("route", ["collection", "store"]) -@pytest.mark.parametrize("api_key", [SecretString("test-api-key"), SecretString("")]) -def test_api_key_rejected_with_supplied_client(definition, route: str, api_key: SecretString): +@pytest.mark.parametrize("api_key", [SecretString("test-api-key"), SecretString(""), "plain-key", ""]) +async def test_api_key_ignored_with_supplied_client(definition, route: str, api_key: SecretString | str): client = AsyncMock(spec=AsyncQdrantClient) with ( patch("agent_framework_qdrant._vector_store.AsyncQdrantClient") as factory, - pytest.raises(ValueError, match="connection settings"), + patch("agent_framework_qdrant._vector_store.load_settings") as loader, ): + connector: QdrantCollection | QdrantStore if route == "collection": - QdrantCollection( + connector = QdrantCollection( dict, definition=definition, collection_name="test", async_client=client, api_key=api_key, + managed_client=True, ) + assert connector.definition is definition else: - QdrantStore(async_client=client, api_key=api_key) + connector = QdrantStore(async_client=client, api_key=api_key, managed_client=True) + assert connector.async_client is client + assert not connector.managed_client + await connector.aclose() factory.assert_not_called() + loader.assert_not_called() + client.close.assert_not_awaited() async def test_failed_and_partial_batches(definition, record): @@ -402,18 +422,21 @@ async def test_failed_and_partial_batches(definition, record): async def test_local_filters_rejected_even_on_empty_collection(definition): - async with QdrantCollection( - dict, - definition=definition, - collection_name="test", - async_client=AsyncQdrantClient(":memory:"), - managed_client=True, - ) as collection: - await collection.ensure_collection_exists() - with pytest.raises(NotImplementedError, match="server"): - await collection.get(filter=Filter("text", "eq", "hi")) - with pytest.raises(NotImplementedError, match="server"): - await collection.search(vector=[1, 0, 0], filter=Filter("integer", "eq", 1)) + client = AsyncQdrantClient(":memory:") + try: + async with QdrantCollection( + dict, + definition=definition, + collection_name="test", + async_client=client, + ) as collection: + await collection.ensure_collection_exists() + with pytest.raises(NotImplementedError, match="server"): + await collection.get(filter=Filter("text", "eq", "hi")) + with pytest.raises(NotImplementedError, match="server"): + await collection.search(vector=[1, 0, 0], filter=Filter("integer", "eq", 1)) + finally: + await client.close() @pytest.mark.parametrize("init_options", [{}, {"location": ":memory:"}, {"path": "local-storage"}]) @@ -486,12 +509,23 @@ async def test_unsupported_options_and_schema(definition): await collection.get(order_by={"integer": True}) with pytest.raises(ValueError, match="finite"): await collection.search(vector=[1, 0, 0], score_threshold=math.nan) - with pytest.raises(ValueError, match="connection settings"): - QdrantStore(async_client=client, url="http://localhost") - with pytest.raises(ValueError, match="connection settings"): - QdrantCollection( - dict, definition=definition, collection_name="test", async_client=client, url="http://localhost" - ) + store = QdrantStore(async_client=client, url="http://localhost", managed_client=True) + assert store.async_client is client + assert not store.managed_client + injected = QdrantCollection( + dict, definition=definition, collection_name="test", async_client=client, url="http://localhost" + ) + assert injected.async_client is client + assert injected.collection_name == "test" + + +def test_invalid_collection_arguments_do_not_create_client(): + with ( + patch("agent_framework_qdrant._vector_store.AsyncQdrantClient") as factory, + pytest.raises(ValueError, match="VectorStoreCollectionDefinition"), + ): + QdrantCollection(dict, collection_name="test", url="https://qdrant.example") + factory.assert_not_called() @pytest.mark.parametrize( diff --git a/python/packages/qdrant/tests/qdrant/test_settings.py b/python/packages/qdrant/tests/qdrant/test_settings.py index 908cb4bf718..4eebe4994cc 100644 --- a/python/packages/qdrant/tests/qdrant/test_settings.py +++ b/python/packages/qdrant/tests/qdrant/test_settings.py @@ -137,12 +137,78 @@ async def test_injected_client_bypasses_environment_settings(connector_factory, client.close.assert_not_awaited() -@pytest.mark.parametrize("settings", [{"env_file_path": "unused.env"}, {"env_file_encoding": "utf-16"}]) -def test_injected_client_rejects_explicit_env_options(connector_factory, settings): +@pytest.mark.parametrize( + "settings", + [ + {"url": "https://ignored.example"}, + {"url": ""}, + {"url": {}}, + {"api_key": "ignored-key"}, + {"api_key": SecretString("ignored-key")}, + {"api_key": ""}, + {"api_key": 123}, + {"env_file_path": "missing.env"}, + {"env_file_encoding": "invalid-encoding"}, + {"managed_client": True}, + { + "url": "https://ignored.example", + "api_key": SecretString("ignored-key"), + "env_file_path": "missing.env", + "env_file_encoding": "invalid-encoding", + "managed_client": True, + }, + ], +) +async def test_injected_client_ignores_connection_settings(connector_factory, monkeypatch, settings): + monkeypatch.setenv("QDRANT_URL", "not-a-url") + monkeypatch.setenv("QDRANT_API_KEY", "ambient-key") client = AsyncMock(spec=AsyncQdrantClient) + client.init_options = {} with ( - patch("agent_framework_qdrant._vector_store.load_settings") as loader, - pytest.raises(ValueError, match="connection settings"), + patch( + "agent_framework_qdrant._vector_store.load_settings", + side_effect=AssertionError("Unexpected settings read"), + ), + patch("agent_framework_qdrant._vector_store.AsyncQdrantClient") as factory, ): - connector_factory(async_client=client, **settings) - loader.assert_not_called() + async with connector_factory(async_client=client, **settings) as connector: + assert connector.async_client is client + assert connector.managed_client is False + if isinstance(connector, QdrantCollection): + assert connector.collection_name == "test" + assert connector.definition.key_field.name == "id" + with pytest.raises(ValueError, match="Unsupported"): + await connector.get(operation_options={"with_payload": False}) + await connector.aclose() + factory.assert_not_called() + client.close.assert_not_awaited() + + +async def test_store_collection_reuses_injected_client(definition, monkeypatch): + monkeypatch.setenv("QDRANT_URL", "not-a-url") + monkeypatch.setenv("QDRANT_API_KEY", "ambient-key") + client = AsyncMock(spec=AsyncQdrantClient) + with ( + patch( + "agent_framework_qdrant._vector_store.load_settings", + side_effect=AssertionError("Unexpected settings read"), + ), + patch("agent_framework_qdrant._vector_store.AsyncQdrantClient") as factory, + ): + async with QdrantStore( + async_client=client, + url="https://ignored.example", + api_key=SecretString("ignored-key"), + env_file_path="missing.env", + env_file_encoding="invalid-encoding", + managed_client=True, + ) as store: + collection = store.get_collection(dict, definition=definition, collection_name="documents") + assert collection.async_client is client + assert collection.managed_client is False + assert collection.collection_name == "documents" + assert collection.definition is definition + await collection.aclose() + await store.aclose() + factory.assert_not_called() + client.close.assert_not_awaited()