Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions python/packages/qdrant/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
102 changes: 64 additions & 38 deletions python/packages/qdrant/agent_framework_qdrant/_vector_store.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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(
Comment thread
Copilot marked this conversation as resolved.
Resolved
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
Expand Down Expand Up @@ -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(
Expand Down
27 changes: 15 additions & 12 deletions python/packages/qdrant/tests/qdrant/conftest.py
Original file line number Diff line number Diff line change
Expand Up @@ -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()
86 changes: 60 additions & 26 deletions python/packages/qdrant/tests/qdrant/test_collection.py
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down Expand Up @@ -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):
Expand All @@ -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"}])
Expand Down Expand Up @@ -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(
Expand Down
Loading
Loading