Python: [Bug]: Out-of-range Cosmos memory search parameters silently disable retrieval

Đọc python/packages/azure-cosmos-memory/agent_framework_azure_cosmos_memory/_context_provider.py, đặc biệt là hàm khởi tạo quanh dòng 159–160, cùng các bài kiểm thử hiện có trong python/packages/azure-cosmos-memory/tests/test_context_provider.py. Thêm kiểm tra trong hàm khởi tạo để top_k là số dương và min_confidence nằm trong khoảng 0.0–1.0, sau đó chạy các bài kiểm thử của trình cung cấp ngữ cảnh. Hoàn thành khi các giá trị không hợp lệ gây ra ValueError được chỉ định và các giá trị biên đã được tài liệu hóa được chấp nhận.

Observed Behavior

CosmosMemoryContextProvider forwards its two retrieval parameters, top_k and min_confidence, to the memory toolkit on every turn without validating either one (python/packages/azure-cosmos-memory/agent_framework_azure_cosmos_memory/_context_provider.py:159-160, main @ 726dcff8):

self.top_k = top_k
self.min_confidence = min_confidence

and then unconditionally into the search call (:393, :395, :400):

search_kwargs = {..., "top_k": self.top_k, ..., "min_confidence": self.min_confidence, ...}
results = await self.memory_client.search_cosmos(**search_kwargs)

Both out-of-range values are accepted at construction, and both fail silently at retrieval rather than at the call site that has the mistake:

1. top_k <= 0 — the toolkit refuses, and the provider turns that into "no memories".
azure-cosmos-agent-memory 0.3.0b2 validates the parameter deep inside the query builder (store/_search_helpers.py:32-38, reached from aio/store/memory_store.py:861):

if top <= 0:
    raise ValidationError(f"{name} must be a positive integer")

The provider's own except (:404) catches it and logs a single warning line, so the agent runs every turn with injected_memory_messages=0. Nothing propagates to the caller: memory retrieval is permanently off, with one warning per turn as the only trace.

2. min_confidence > 1.0 — an impossible predicate, so zero recall and not even a log.
Confidence scores are documented as 0.0-1.0 in this very package — _context_provider.py:130 ("Minimum confidence score (0.0-1.0) for retrieved memories") and README.md:325 / :347. The toolkit builds the filter verbatim (_utils.py:512-513):

if min_confidence is not None and min_confidence > 0:
    qb.add_gte("c.confidence", "@min_confidence", min_confidence)

Measured with min_confidence=1.5, the generated clause is WHERE c.type IN (@memory_type_0) AND c.confidence >= @min_confidence with bind value 1.5, which no memory can ever satisfy: every retrieval returns empty, with no error and no warning at all.

3. min_confidence < 0 — the filter the caller configured is silently dropped.
The same min_confidence > 0 guard skips the WHERE clause entirely (measured with -0.5: no confidence predicate in the generated query). So a negative threshold behaves exactly like "no filtering" and retrieval widens instead of tightening — the opposite of what README.md:347 recommends it for ("Use min_confidence to filter low-quality extractions").

Expected Behavior

Out-of-range retrieval parameters should be rejected at construction, where the caller can see them, instead of degrading retrieval later. The repo already does exactly this for the same class of parameter, e.g. core/agent_framework/_types.py:4863 ("temperature must be between 0.0 and 2.0"), :4868 ("top_p must be between 0.0 and 1.0"), :4872 ("max_tokens must be greater than 0"), plus azure-ai-search/_vector_store.py:789 and mongodb/_vector_store.py:1067 for the retrieval-shape knobs.

min_confidence already has a documented contract (0.0-1.0), so enforcing it is not a new rule but a missing check; top_k must be positive because the toolkit requires it on every search.

The impact is not a wrong answer but a permanently disabled memory feature that looks like it works: a typo, a config that lands on 0, or a threshold expressed as a percentage (90 instead of 0.9) gives an agent that silently stops recalling anything, and the operator has no error to catch.

Steps to Reproduce

1. Install from main (726dcff8): agent-framework-azure-cosmos-memory (source) with the toolkit it pins, azure-cosmos-agent-memory 0.3.0b2.
2. Construct the provider with an out-of-range value — no error is raised: CosmosMemoryContextProvider(memory_client=client, top_k=0) and CosmosMemoryContextProvider(memory_client=client, min_confidence=1.5).
3. Drive one turn through the provider's retrieval path against the real toolkit query builder.
4. Observe: case (1) raises ValidationError inside the toolkit and the provider swallows it into a warning with zero injected messages; case (2) returns zero memories and logs nothing.

Minimal Reproduction

No Azure resources or API keys are needed — the three checks below exercise the toolkit's real query builder and the provider constructor. As tests in python/packages/azure-cosmos-memory/tests/test_context_provider.py, the first two fail on main and the third pins the boundary so the fix cannot over-tighten it:

def test_init_rejects_non_positive_top_k(self, mock_memory_client: AsyncMock) -> None:
    for top_k in (0, -1):
        with pytest.raises(ValueError, match="top_k must be greater than 0"):
            CosmosMemoryContextProvider(memory_client=mock_memory_client, top_k=top_k)


def test_init_rejects_min_confidence_outside_documented_range(self, mock_memory_client: AsyncMock) -> None:
    for min_confidence in (-0.1, 1.01, float("nan"), float("inf")):
        with pytest.raises(ValueError, match="min_confidence must be between 0.0 and 1.0"):
            CosmosMemoryContextProvider(memory_client=mock_memory_client, min_confidence=min_confidence)


def test_init_accepts_boundary_search_params(self, mock_memory_client: AsyncMock) -> None:
    provider = CosmosMemoryContextProvider(memory_client=mock_memory_client, top_k=1, min_confidence=1.0)
    assert provider.top_k == 1
    assert provider.min_confidence == 1.0

The toolkit side, which is what makes these silent rather than merely inconvenient:

from azure.cosmos.agent_memory._utils import _build_memory_query_builder
from azure.cosmos.agent_memory.store._search_helpers import top_literal

top_literal(0, name="top_k")    # ValidationError: top_k must be a positive integer
top_literal(-1, name="top_k")   # ValidationError: top_k must be a positive integer

qb = _build_memory_query_builder(memory_types=["fact"], min_confidence=1.5)
print(qb.build_where(), qb.get_parameters())
# ' WHERE c.type IN (@memory_type_0) AND c.confidence >= @min_confidence'
# [{'name': '@memory_type_0', 'value': 'fact'}, {'name': '@min_confidence', 'value': 1.5}]

qb = _build_memory_query_builder(memory_types=["fact"], min_confidence=-0.5)
print(qb.build_where())
# ' WHERE c.type IN (@memory_type_0)'        <- no confidence predicate at all

Measured on the installed toolkit (0.3.0b2): min_confidence=1.5 keeps the predicate with an unsatisfiable bind, min_confidence=-0.5 drops it entirely, and the in-range 0.7 behaves as documented.

Error Messages and Stack Traces

Measured on main (726dcff8), the two rejection tests fail and nothing is raised:

    def test_init_rejects_non_positive_top_k(self, mock_memory_client: AsyncMock) -> None:
        for top_k in (0, -1):
>           with pytest.raises(ValueError, match="top_k must be greater than 0"):
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
E           Failed: DID NOT RAISE ValueError

tests\test_context_provider.py:138: Failed
tests\test_context_provider.py::TestInit::test_init_rejects_non_positive_top_k FAILED
tests\test_context_provider.py::TestInit::test_init_rejects_min_confidence_outside_documented_range FAILED

and the swallowed toolkit error, which is the only thing an operator ever sees for case (1) — the provider's except/logger.warning at :404 turns it into one log line per turn:

azure.cosmos.agent_memory.exceptions.ValidationError: top_k must be a positive integer
WARNING agent_framework_azure_cosmos_memory._context_provider: Failed to retrieve memories: top_k must be a positive integer

Package Versions

agent-framework-azure-cosmos-memory: source main @ 726dcff8; azure-cosmos-agent-memory: 0.3.0b2

Python Version

Python 3.12.11

Operating System

Windows