From 5bbe21180052321c62b1f7c283e5d5a8fc24ef61 Mon Sep 17 00:00:00 2001 From: Aayush Kataria Date: Tue, 17 Nov 2026 15:52:08 -0800 Subject: [PATCH 1/4] Partition memories by [tenant_id, user_id]; thread_id becomes a plain field Every record now lives in the logical partition [tenant_id, user_id] instead of [user_id, thread_id]. user_id is the owner of a memory (a user or an agent) and thread_id is a plain field, so everything one owner knows sits in one partition. - Clients take tenant_id (default "default") and stamp it on every record they write. A client reads and writes only inside its tenant, and the Function App follows the tenant of each changed turn. - Containers are created with the hierarchical key /tenant_id, /user_id (SDK and Bicep). create_memory_store(), validate_topology() and the Function App refuse an existing container with another key. - tenant_id and user_id are validated: non-empty, at most 256 UTF-8 bytes, and no / \ ? # or control characters. - thread_id is removed from update_cosmos, delete_memory, delete_turn, add_tags, remove_tags and get_memory_history, and from MemoryNotFoundError. Record ids are unique per owner across threads. - Function App orchestration instance ids are a fixed-length hash of tenant, owner and thread. - Tests guard that every owner filter names the tenant and that no partition key is built by hand. Breaking: recreate the containers, and leases with them. Existing data is not migrated. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CHANGELOG.md | 14 + Docs/README.md | 4 +- Docs/architecture/orchestrators.md | 2 + Docs/azure_testing.md | 4 +- Docs/concepts.md | 61 ++- Docs/design_patterns.md | 58 +- Docs/local_testing.md | 6 +- Docs/operations.md | 4 + Docs/public_api.md | 54 +- Docs/troubleshooting.md | 11 +- README.md | 11 +- Samples/Advanced/advanced_memory_lifecycle.py | 2 +- Samples/Notebooks/Demo.ipynb | 2 - Samples/Notebooks/Demo_async.ipynb | 2 - .../Processing/processing_episodic_memory.py | 1 - .../processing_procedural_memory.py | 1 - Samples/Quickstarts/quickstart_cosmos.py | 4 +- Samples/Scenarios/scenario_counter_tuning.py | 2 +- .../scenario_memory_reconciliation.py | 1 - Samples/Scenarios/scenario_rag_with_memory.py | 2 - .../cosmos/agent_memory/_base/base_client.py | 8 + .../cosmos/agent_memory/_container_routing.py | 3 +- azure/cosmos/agent_memory/_counters.py | 30 +- azure/cosmos/agent_memory/_partitioning.py | 115 ++++ azure/cosmos/agent_memory/_query_builder.py | 23 +- azure/cosmos/agent_memory/_utils.py | 8 +- azure/cosmos/agent_memory/aio/auto_trigger.py | 16 +- .../agent_memory/aio/cosmos_memory_client.py | 113 ++-- .../agent_memory/aio/processors/inprocess.py | 14 +- .../agent_memory/aio/services/pipeline.py | 181 ++++--- .../agent_memory/aio/store/memory_store.py | 201 +++---- azure/cosmos/agent_memory/auto_trigger.py | 18 +- .../agent_memory/cosmos_memory_client.py | 108 ++-- azure/cosmos/agent_memory/exceptions.py | 7 +- azure/cosmos/agent_memory/models.py | 2 + .../agent_memory/processors/inprocess.py | 10 +- .../cosmos/agent_memory/services/__init__.py | 5 +- .../cosmos/agent_memory/services/_absorbed.py | 33 +- .../agent_memory/services/_conflicts.py | 59 +- azure/cosmos/agent_memory/services/_dedup.py | 29 +- .../services/_extraction_context.py | 13 +- .../agent_memory/services/_procedures.py | 17 +- .../cosmos/agent_memory/services/pipeline.py | 188 +++---- .../agent_memory/store/_search_helpers.py | 16 +- .../cosmos/agent_memory/store/memory_store.py | 212 ++++---- .../orchestrators/extract_episodes.py | 9 +- .../orchestrators/extract_memories.py | 38 +- .../orchestrators/synthesize_procedural.py | 9 +- function_app/orchestrators/thread_summary.py | 17 +- function_app/orchestrators/user_summary.py | 19 +- function_app/shared/counters.py | 27 +- function_app/shared/instance_ids.py | 21 + function_app/shared/pipeline_factory.py | 43 +- function_app/triggers/change_feed.py | 111 ++-- infra/README.md | 26 +- infra/main.bicep | 8 +- infra/modules/cosmos.bicep | 16 +- infra/modules/functions.bicep | 8 +- tests/conftest.py | 6 + tests/integration/test_async_full_pipeline.py | 29 +- .../test_changefeed_integration.py | 22 +- tests/integration/test_episodic_pipeline.py | 21 +- tests/integration/test_full_pipeline.py | 46 +- tests/integration/test_procedural_pipeline.py | 21 +- tests/integration/test_ttl_lifecycle.py | 12 +- tests/unit/aio/processors/test_base.py | 14 + .../services/test_episodic_retrieval_async.py | 15 +- .../test_mark_turns_extracted_async.py | 7 +- .../test_procedural_retrieval_async.py | 19 +- ..._procedural_synthesis_and_context_async.py | 89 +++- .../services/test_tenant_isolation_async.py | 379 +++++++++++++ tests/unit/aio/store/test_delete_cascade.py | 87 +-- .../unit/aio/store/test_get_memory_history.py | 6 +- tests/unit/aio/store/test_memory_store.py | 67 +-- tests/unit/aio/store/test_search_routing.py | 30 +- tests/unit/aio/store/test_secret_redaction.py | 42 +- .../store/test_update_embedding_fallback.py | 15 +- tests/unit/aio/test_auto_trigger.py | 95 +++- tests/unit/aio/test_combine.py | 8 + tests/unit/aio/test_conflict_links.py | 27 +- tests/unit/aio/test_consolidate_memories.py | 21 +- tests/unit/aio/test_cosmos_memory_client.py | 346 ++++++++++-- tests/unit/aio/test_reconcile_passes.py | 10 +- tests/unit/aio/test_search_slots.py | 6 +- tests/unit/function_app/test_change_feed.py | 503 ++++++++++++++++-- tests/unit/function_app/test_counters.py | 69 ++- .../unit/function_app/test_error_redaction.py | 4 +- .../test_extract_episodes_orchestrator.py | 20 +- tests/unit/function_app/test_failure_logs.py | 12 +- tests/unit/function_app/test_instance_ids.py | 98 ++++ tests/unit/function_app/test_orchestrators.py | 212 ++++++-- .../function_app/test_pipeline_factory.py | 92 +++- ...test_synthesize_procedural_orchestrator.py | 25 +- tests/unit/processors/test_base.py | 14 + tests/unit/services/test_absorbed.py | 45 +- tests/unit/services/test_combine.py | 37 +- tests/unit/services/test_conflict_links.py | 114 +++- tests/unit/services/test_conflicts.py | 92 ++-- .../services/test_consolidate_memories.py | 23 +- tests/unit/services/test_dedup.py | 23 +- .../unit/services/test_episodic_retrieval.py | 8 +- tests/unit/services/test_extract_dry.py | 46 +- tests/unit/services/test_extract_episodes.py | 48 ++ .../unit/services/test_extraction_context.py | 89 +++- .../services/test_mark_turns_extracted.py | 15 +- tests/unit/services/test_persist_extracted.py | 79 +++ tests/unit/services/test_pipeline_service.py | 102 +++- .../test_procedural_synthesis_and_context.py | 135 ++++- tests/unit/services/test_procedures.py | 44 +- tests/unit/services/test_reconcile_passes.py | 3 + .../services/test_secret_redaction_writes.py | 49 +- .../unit/services/test_transcript_metadata.py | 4 + .../services/test_user_summary_topic_tags.py | 31 ++ tests/unit/store/test_delete_cascade.py | 79 +-- tests/unit/store/test_get_memory_history.py | 46 +- tests/unit/store/test_list_tags.py | 25 +- tests/unit/store/test_memory_store.py | 77 ++- tests/unit/store/test_search_routing.py | 48 +- tests/unit/store/test_secret_redaction.py | 42 +- tests/unit/store/test_tag_mutation.py | 8 +- tests/unit/store/test_tenant_isolation.py | 417 +++++++++++++++ .../store/test_update_embedding_fallback.py | 15 +- tests/unit/test_auto_trigger.py | 90 +++- tests/unit/test_cosmos_memory_client.py | 314 +++++++++-- tests/unit/test_counters.py | 166 +++++- tests/unit/test_dependency_failure_logs.py | 38 +- tests/unit/test_exceptions.py | 16 +- tests/unit/test_log_redaction.py | 2 + tests/unit/test_memory_type_multi.py | 29 +- tests/unit/test_min_confidence.py | 6 +- tests/unit/test_models.py | 32 ++ tests/unit/test_no_exception_text_in_logs.py | 10 +- tests/unit/test_partitioning.py | 175 ++++++ tests/unit/test_pipeline_confidence.py | 49 +- tests/unit/test_query_builder.py | 23 + tests/unit/test_reconcile.py | 5 + tests/unit/test_search_conflicts.py | 42 +- tests/unit/test_search_slots.py | 6 +- tests/unit/test_tenant_scope_guard.py | 69 +++ tests/unit/test_utils.py | 25 + 140 files changed, 5724 insertions(+), 1633 deletions(-) create mode 100644 azure/cosmos/agent_memory/_partitioning.py create mode 100644 function_app/shared/instance_ids.py create mode 100644 tests/unit/aio/services/test_tenant_isolation_async.py create mode 100644 tests/unit/function_app/test_instance_ids.py create mode 100644 tests/unit/store/test_tenant_isolation.py create mode 100644 tests/unit/test_partitioning.py create mode 100644 tests/unit/test_tenant_scope_guard.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 4b27765..53b40a1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,19 @@ ## Release History +## [Unreleased] + +#### Features Added +* **Memories are keyed by tenant and owner.** Every record lives in the partition `[tenant_id, user_id]`, where `user_id` is the owner of the memory, a user or an agent, and `thread_id` is a plain field. Everything one owner knows now sits in one partition. Pass `tenant_id` to the client (default `"default"`) to keep several apps or customers apart in the same containers; the Function App follows the tenant of each record. +* **A container with the wrong partition key is refused.** `create_memory_store()`, which the client constructor calls, now fails with a clear message when an existing container is not keyed `[/tenant_id, /user_id]`, and `validate_topology()` checks the key of `memories`, `memories_turns`, `memories_summaries` and `counter`. The Function App makes the same check on its first change-feed batch. A container keyed the earlier way takes writes but reads back empty. + +#### Breaking Changes +* **The containers use a new partition key.** `memories`, `memories_turns`, `memories_summaries` and `counter` are keyed `[/tenant_id, /user_id]` instead of `[/user_id, /thread_id]` (the Bicep template and `create_memory_store()`). A partition key can't change in place, so recreate those containers, and `leases` too so the change feed starts clean; existing data is not migrated. Record ids must now be unique per owner across threads, not per thread. +* **`user_id` is validated.** An owner id must be a non-empty string of at most 256 UTF-8 bytes without `/`, `\`, `?`, `#` or control characters, the rules a `tenant_id` already followed. Anything else raises `ValidationError`. +* **`thread_id` is no longer needed to find a record.** It is removed from `update_cosmos()`, `delete_memory()`, `delete_turn()`, `add_tags()`, `remove_tags()` and `get_memory_history()`, and `MemoryNotFoundError` no longer carries it. It still filters reads and names the thread for thread operations. + +#### Other Changes +* Orchestration instance ids in the Function App are now `:[:]`, where the digest is a fixed-length hash of the tenant, owner and thread. They stay within Durable Functions' 100-character limit and no longer contain user ids. + ## [0.4.0b1] (2026-11-16) #### Features Added diff --git a/Docs/README.md b/Docs/README.md index cfb7b35..190ad46 100644 --- a/Docs/README.md +++ b/Docs/README.md @@ -6,10 +6,10 @@ This folder contains the main project documentation for Agent Memory Toolkit. | Document | Purpose | |----------|---------| -| [concepts.md](concepts.md) | Explains the core memory model, including memory types (turn, summary, fact, episodic, procedural, user summary), threads, roles, embeddings and search (result slots, conflicting facts), the processing pipeline and fact extraction, secret redaction, reconciliation, automatic change feed processing, and shared Cosmos throughput configuration. | +| [concepts.md](concepts.md) | Explains the core memory model, including memory types (turn, summary, fact, episodic, procedural, user summary), tenants and owners (the `[tenant_id, user_id]` partition key), threads, roles, embeddings and search (result slots, conflicting facts), the processing pipeline and fact extraction, secret redaction, reconciliation, automatic change feed processing, and shared Cosmos throughput configuration. | | [local_testing.md](local_testing.md) | Covers local setup, environment configuration, RBAC, Cosmos provisioning, running the toolkit and Azure Functions locally, and testing change feed auto-processing with serverless or autoscale container provisioning. | | [azure_testing.md](azure_testing.md) | Covers Azure deployment, cloud configuration, required services, change feed settings, throughput mode configuration, and validation steps for running the toolkit in Azure. | -| [design_patterns.md](design_patterns.md) | Shows when and how to call CRUD operations, summarization, fact extraction, memory retrieval and search slots, procedures and standing instructions, reconciliation and conflicting facts, and secret handling and deletion in chat and multi-agent applications, including automatic processing via the change feed. | +| [design_patterns.md](design_patterns.md) | Shows when and how to call CRUD operations, summarization, fact extraction, memory retrieval and search slots, procedures and standing instructions, reconciliation and conflicting facts, secret handling and deletion, and tenants and agent-owned memory in chat and multi-agent applications, including automatic processing via the change feed. | | [public_api.md](public_api.md) | Documents the `CosmosMemoryClient` and `AsyncCosmosMemoryClient` methods (connection, CRUD, retrieval, processing, tagging), fact and procedure fields, secret redaction, topology validation, and extension points. | | [operations.md](operations.md) | Covers runtime settings for a deployment: memory TTLs, counter-based trigger thresholds, and reconcile, procedure, extraction prompt and Cosmos DB region settings. | | [architecture/orchestrators.md](architecture/orchestrators.md) | Describes the Function App's Durable orchestrators and their activity chains, the time-budgeted reconcile and procedure activities, and how failed activities are reported without exposing message text. | diff --git a/Docs/architecture/orchestrators.md b/Docs/architecture/orchestrators.md index fc3f2cd..a5ef580 100644 --- a/Docs/architecture/orchestrators.md +++ b/Docs/architecture/orchestrators.md @@ -27,6 +27,8 @@ SynthesizeProceduralOrchestrator A batch whose model call fails with a retryable error yields no facts and is counted in `deferred_turn_count`. `em_AdvanceExtractWatermark` still moves past its turns, so the Function App does not retry them (the in-process backend does). +Every orchestration input and activity payload carries `tenant_id`, which the change feed trigger reads from the changed turn, and each activity runs the pipeline of that tenant (one per tenant, sharing the Cosmos DB and model clients), so one Function App serves every tenant. An orchestration instance ID is `{kind}:{digest}:{count}`, where `kind` is `extract`, `episode`, `thread_summary`, `user_summary` or `procedural` and `digest` is a fixed-length digest of the tenant, owner and (where there is one) thread, so IDs stay within the 100-character limit and hold no user IDs. + Fact IDs are deterministic from user, thread, and normalized content, and episode IDs from user, thread, the segment's first and last turn and the episode's position in it. Thread and user summaries keep their deterministic summary IDs. Procedure IDs derive from the user, kind and name, and a combined fact's ID from the user and its source IDs, so a retried activity finds the record it already wrote (409) instead of writing a second one. `UserSummaryOrchestrator` can start before extraction has persisted anything for a new user. `us_Extract` then returns `no_memories_yet` instead of failing, and the orchestrator polls on a durable timer (App Settings `USER_SUMMARY_WAIT_SECONDS`, default `120`, every `USER_SUMMARY_WAIT_INTERVAL_SECONDS`, default `10`) before it skips that cadence; the next user-summary threshold tries again. `USER_SUMMARY_WAIT_SECONDS=0` makes it a single attempt. diff --git a/Docs/azure_testing.md b/Docs/azure_testing.md index 21909eb..835f22d 100644 --- a/Docs/azure_testing.md +++ b/Docs/azure_testing.md @@ -142,7 +142,7 @@ az functionapp config appsettings set \ USER_SUMMARY_EVERY_N="10" ``` -Set any threshold to `"0"` to disable that processing type. +Set any threshold to `"0"` to disable that processing type. There is no tenant setting: the Function App processes each turn in the tenant stored on it, which is the `tenant_id` of the client that wrote it (`"default"` unless set). The `leases` container is provisioned by `create_memory_store()` alongside the other containers, so the Function App should be configured to use that existing lease container. @@ -259,7 +259,7 @@ await memory.connect_cosmos() await memory.create_memory_store() ``` -This provisions the `memories`, `memories_turns`, `memories_summaries`, `counter`, and `leases` containers. `serverless` is the default throughput mode; if you set `COSMOS_DB_THROUGHPUT_MODE=autoscale`, the shared `COSMOS_DB_AUTOSCALE_MAX_RU` value is applied to all five containers. The Function App does not read either variable. +This provisions the `memories`, `memories_turns`, `memories_summaries`, `counter`, and `leases` containers. The first four get the hierarchical partition key `/tenant_id`, `/user_id` (`leases` uses `/id`); an existing container keeps its key, so recreate the containers that an earlier version created with `[/user_id, /thread_id]`, and `leases` with them so the change feed starts clean on the recreated turns container. `serverless` is the default throughput mode; if you set `COSMOS_DB_THROUGHPUT_MODE=autoscale`, the shared `COSMOS_DB_AUTOSCALE_MAX_RU` value is applied to all five containers. The Function App does not read either variable. --- diff --git a/Docs/concepts.md b/Docs/concepts.md index 985eaf1..59ec320 100644 --- a/Docs/concepts.md +++ b/Docs/concepts.md @@ -10,9 +10,10 @@ Every memory uses the same base shape: | Field | Description | |--------------|-------------------------------------------------------------------------------| -| `id` | Unique identifier | -| `user_id` | User the memory belongs to | -| `thread_id` | Conversation thread | +| `id` | Identifier, unique per owner across all of the owner's threads | +| `tenant_id` | Tenant the memory belongs to (`"default"` unless the client sets one) | +| `user_id` | Owner of the memory: a user or an agent | +| `thread_id` | Conversation thread; a plain field, not part of the partition key | | `role` | `user`, `agent`, `tool`, or `system` | | `type` | `turn`, `thread_summary`, `fact`, `episodic`, `procedural`, or `user_summary` | | `content` | Main text payload | @@ -22,6 +23,22 @@ Every memory uses the same base shape: --- +## Tenants and Owners + +Every record lives in the logical partition `[tenant_id, user_id]`: the `memories`, `memories_turns`, `memories_summaries` and `counter` containers use the hierarchical partition key `/tenant_id`, `/user_id`. + +- **`tenant_id`** is a name you choose for whose memories these are: an application, a customer or an environment. A client is bound to one tenant by its `tenant_id` constructor argument (default `"default"`), stamps it on every record it writes, and reads and writes only inside it. It is never a per-call argument and has no environment variable; the Function App uses the `tenant_id` stored on each record. +- **`user_id`** is the owner of the memory: a user or an agent. It is a plain string, so keep the ids distinct (for example `agent:support-bot`). The same `user_id` in two tenants is two owners. +- **`thread_id`** is a plain field, not part of the key. It filters reads and names the thread for thread operations, but everything one owner knows (turns, facts, episodes, procedures, summaries, counters) sits in one partition of its container. Sentinel thread ids such as `__user_summary__` and `__procedural__` are marker values on documents, not partitions. + +A record id is unique per owner across all of the owner's threads. A tenant id or an owner id is a non-empty string of at most 256 UTF-8 bytes without `/`, `\`, `?`, `#` or control characters, because ids appear in Cosmos DB document ids; anything else raises `ValidationError`. A query that names the owner reads one partition (a keyword search is the exception, see [Keyword search and partition scope](#keyword-search-and-partition-scope)); a read where `user_id` is optional and left out, such as `get_memories()`, covers every owner in the client's tenant, across partitions. + +Cosmos DB limits a logical partition to 20 GB of data and 10,000 RU/s, so the limits apply per owner. Keep any one owner, such as an agent shared by many users, well below them. + +A container's partition key cannot be changed in place. `create_memory_store()` creates the containers with this key, so a deployment whose containers have the earlier `[/user_id, /thread_id]` key must recreate `memories`, `memories_turns`, `memories_summaries` and `counter`, and `leases` with them so the change feed starts clean on the recreated turns container; existing data is not migrated. `create_memory_store()` refuses an existing container keyed otherwise with an error that names the container and its key, and `validate_topology()` makes the same check after `connect_cosmos()`: a container with the earlier key takes writes but reads back empty. + +--- + ## Memory Types ### Turn @@ -107,7 +124,7 @@ A procedure `applies` either `always` (nearly every interaction: response langua - When reviewing code for the user: Include a suggested fix with every review comment. ``` -**How procedures are learned.** `synthesize_procedural()` runs after each reconcile (when `PROCEDURAL_SYNTHESIS_AUTO` is true) or on demand with the in-process backend. It reads the user's active preference and requirement facts, facts with salience of at least 0.8, `directive` and `correction` facts, and episodes with lessons, written since its cursor (the `procedure_cursor` document under `[user_id, "__procedural__"]`). A run reads at most 50 facts and 50 episodes and shows them to the model 10 at a time, each batch with the user's nearest existing procedures, so the model adds a procedure, revises one in place or records new evidence for one instead of writing a paraphrase. The cursor moves after each batch, so a run that stops early resumes where it stopped, and a run with nothing new makes no model call. A retryable model error, or a transient embedding or Cosmos DB error while writing a procedure, ends the run without moving the cursor past that batch, so the next run retries it. A revision that drops a number or a negation is discarded unless it records the user's correction. +**How procedures are learned.** `synthesize_procedural()` runs after each reconcile (when `PROCEDURAL_SYNTHESIS_AUTO` is true) or on demand with the in-process backend. It reads the user's active preference and requirement facts, facts with salience of at least 0.8, `directive` and `correction` facts, and episodes with lessons, written since its cursor (the `procedure_cursor` document under the sentinel thread id `__procedural__`). A run reads at most 50 facts and 50 episodes and shows them to the model 10 at a time, each batch with the user's nearest existing procedures, so the model adds a procedure, revises one in place or records new evidence for one instead of writing a paraphrase. The cursor moves after each batch, so a run that stops early resumes where it stopped, and a run with nothing new makes no model call. A retryable model error, or a transient embedding or Cosmos DB error while writing a procedure, ends the run without moving the cursor past that batch, so the next run retries it. A revision that drops a number or a negation is discarded unless it records the user's correction. **Retiring taught facts.** When an active situational procedure cites a user's `directive` or `correction` fact, the fact is retired into the procedure (`supersede_reason="procedure"`), so the rule is stored and retrieved once. A standing rule leaves its facts searchable, because it reaches the agent through `build_procedural_context()`. Only facts extracted with an `assertion` are retired. @@ -186,7 +203,7 @@ Slots need `user_id` and are skipped when `memory_id` is set or when they would ### Keyword search and partition scope -A keyword (hybrid) query ranks with `FullTextScore`, which is ignored in a query the Python SDK sends with a partition key, because it skips query planning ([Azure/azure-sdk-for-python#42241](https://github.com/Azure/azure-sdk-for-python/issues/42241)), so every question would get the same fixed order. A search that has keywords therefore runs across partitions with `c.user_id` (and `c.thread_id`, when given) in the `WHERE` clause, which confines it to the same records, and sets `full_text_score_scope="Local"` so BM25 statistics come from the partition ranges the query targets. This applies to `search_cosmos`, `search_turns`, `search_summaries`, `search_episodic_memories` and `retrieve_procedures`; expect more RUs than a single-partition read on a large container. A query whose terms are all stopwords has no keywords and ranks by vector similarity alone; with both `user_id` and `thread_id` it still reads one partition, except a `search_cosmos` that searches episodic or procedural memories, which always runs across partitions (those memories match on the user alone, whatever the `thread_id`). `MemoryStore.query()` raises `ValidationError` for a `FullTextScore` query sent with a partition key. +A keyword (hybrid) query ranks with `FullTextScore`, which is ignored in a query the Python SDK sends with a partition key, because it skips query planning ([Azure/azure-sdk-for-python#42241](https://github.com/Azure/azure-sdk-for-python/issues/42241)), so every question would get the same fixed order. A search that has keywords therefore runs across partitions with `c.tenant_id`, `c.user_id` (and `c.thread_id`, when given) in the `WHERE` clause, which confines it to the client's tenant and the same owner, and sets `full_text_score_scope="Local"` so BM25 statistics come from the partition ranges the query targets. This applies to `search_cosmos`, `search_turns`, `search_summaries`, `search_episodic_memories` and `retrieve_procedures`; expect more RUs than a single-partition read on a large container. A query whose terms are all stopwords has no keywords and ranks by vector similarity alone; with a `user_id` it reads one partition, the owner's, whatever the `thread_id`. A search without a `user_id` covers every owner in the client's tenant and always runs across partitions. `MemoryStore.query()` raises `ValidationError` for a `FullTextScore` query sent with a partition key. --- @@ -299,7 +316,7 @@ Retired facts stay in the container with their `supersede_reason` (`duplicate`, ### Deleting a memory -`delete_memory()` removes one document. For a fact or procedure it first deletes the records retired into it (`supersede_reason` of `duplicate`, `combined` or `procedure`) and, transitively, anything retired into those, because they hold the same information as the memory they were folded into: what the user deleted is gone. The records are looked up across the user's partitions and deleted deepest first, each under its own `thread_id`, before the memory itself. The delete is sequential and best-effort: if one fails, the memory is kept and a retry resumes. Records retired for another reason (older records may carry `contradict` or `update`) are earlier versions, not copies, and stay. A conflict link holds only fact ids, no text, and is ignored once either fact is gone. Deleting a retired record deletes only that record, so to remove information delete the fact that is active now (the survivor or the combined fact). `delete_thread()` deletes only a thread's turns and summary. +`delete_memory()` removes one document. For a fact or procedure it first deletes the records retired into it (`supersede_reason` of `duplicate`, `combined` or `procedure`) and, transitively, anything retired into those, because they hold the same information as the memory they were folded into: what the user deleted is gone. The records are looked up in the owner's partition and deleted deepest first, before the memory itself. The delete is sequential and best-effort: if one fails, the memory is kept and a retry resumes. Records retired for another reason (older records may carry `contradict` or `update`) are earlier versions, not copies, and stay. A conflict link holds only fact ids, no text, and is ignored once either fact is gone. Deleting a retired record deletes only that record, so to remove information delete the fact that is active now (the survivor or the combined fact). `delete_thread()` deletes only a thread's turns and summary. ### Exact duplicates at write time @@ -339,29 +356,29 @@ memories_turns container ▼ on_memory_change trigger │ - ├── count turns per (user_id, thread_id) + ├── count turns per (tenant_id, user_id, thread_id) │ └── crosses threshold? ──► start thread_summary / extract_memories / extract_episodes │ - └── count turns per user_id + └── count turns per (tenant_id, user_id) └── crosses threshold? ──► start user_summary ``` ### How it works 1. The change feed trigger watches the `memories_turns` container for new documents. -2. Only documents with `type == "turn"` are counted. +2. Only documents with `type == "turn"` are counted. The trigger reads `tenant_id` from each changed turn, next to `user_id` and `thread_id`, and skips a turn without a valid `tenant_id` with a warning. 3. Documents in the dedicated `counter` container track how many turns have been seen per scope using ETag-based optimistic concurrency. -4. When a counter crosses a configured threshold, the corresponding Durable Functions orchestration is started automatically. +4. When a counter crosses a configured threshold, the corresponding Durable Functions orchestration is started automatically, in the tenant of the turns it counted. The Function App needs no tenant setting. ### Threshold settings -| Setting | Scope | Default | -|---------------------------|---------------------------------------------------------------------------------|---------| -| `THREAD_SUMMARY_EVERY_N` | Per `(user_id, thread_id)` | `10` | -| `FACT_EXTRACTION_EVERY_N` | Per `(user_id, thread_id)` | `2` | -| `DEDUP_EVERY_N` | Per `(user_id, thread_id)`; reconcile every `FACT_EXTRACTION_EVERY_N × N` turns | `5` | -| `EPISODE_EVAL_EVERY_N` | Per `(user_id, thread_id)`; checks for an episode boundary every N turns | `4` | -| `USER_SUMMARY_EVERY_N` | Per `user_id` (across all threads) | `20` | +| Setting | Scope | Default | +|---------------------------|--------------------------------------------------------------------------------------------|---------| +| `THREAD_SUMMARY_EVERY_N` | Per `(tenant_id, user_id, thread_id)` | `10` | +| `FACT_EXTRACTION_EVERY_N` | Per `(tenant_id, user_id, thread_id)` | `2` | +| `DEDUP_EVERY_N` | Per `(tenant_id, user_id, thread_id)`; reconcile every `FACT_EXTRACTION_EVERY_N × N` turns | `5` | +| `EPISODE_EVAL_EVERY_N` | Per `(tenant_id, user_id, thread_id)`; checks for an episode boundary every N turns | `4` | +| `USER_SUMMARY_EVERY_N` | Per `(tenant_id, user_id)` (across all threads) | `20` | These defaults are shared by both backends (`function_app/shared/config.py` imports the same constants from `azure.cosmos.agent_memory.thresholds`), so the InProcess and Durable processors fire on the same turn boundaries unless overridden. Set any value to `0` to disable that processing type. For example, setting `THREAD_SUMMARY_EVERY_N=5` generates a thread summary every 5 new turns in each thread. @@ -373,10 +390,10 @@ A failed activity reports only ` ()` to Durable Functions, never | Container | Partition Key | Purpose | |----------------------|-----------------------------------------|-------------------------------------------------------------------------------------------------| -| `memories` | `/user_id`, `/thread_id` (hierarchical) | Durable derived memories (`fact`, `episodic`, `procedural`) | -| `memories_turns` | `/user_id`, `/thread_id` (hierarchical) | Raw conversation turns (`turn`) - append-only, TTL-pruned | -| `memories_summaries` | `/user_id`, `/thread_id` (hierarchical) | Thread + user summaries (`thread_summary`, `user_summary`) | -| `counter` | `/user_id`, `/thread_id` (hierarchical) | Message count tracking for automatic processing; 90-day default TTL when the toolkit creates it | +| `memories` | `/tenant_id`, `/user_id` (hierarchical) | Durable derived memories (`fact`, `episodic`, `procedural`) | +| `memories_turns` | `/tenant_id`, `/user_id` (hierarchical) | Raw conversation turns (`turn`) - append-only, TTL-pruned | +| `memories_summaries` | `/tenant_id`, `/user_id` (hierarchical) | Thread + user summaries (`thread_summary`, `user_summary`) | +| `counter` | `/tenant_id`, `/user_id` (hierarchical) | Message count tracking for automatic processing; 90-day default TTL when the toolkit creates it | | `leases` | `/id` | Change feed checkpointing container created by `create_memory_store()` | The 90-day TTL is the `counter` container's default, so it applies to every document in it - thread counters, user counters and the extraction watermark kept on a thread counter - and each expires 90 days after its last update. An existing `counter` container keeps its current TTL setting: `create_container_if_not_exists` does not change it. The `memories` container also holds the cursor documents that resume reconcile (`dedup_cursor`, under `__dedup__`), procedure learning (`procedure_cursor`, under `__procedural__`) and episode extraction (`episode_cursor`, one per thread), and the conflict links (`conflict_link`, under `__conflicts__`); they are not memories and `get_memories()` does not return them. @@ -410,4 +427,4 @@ Both modes run the same pipeline code (`PipelineService`; the Function App's act Local storage is enough for CRUD testing. Cosmos DB is required for persistence, vector search, and the processing pipeline. -Cosmos DB uses a hierarchical partition key (`user_id`, `thread_id`) for efficient queries scoped to a user or thread. +Cosmos DB uses the hierarchical partition key (`tenant_id`, `user_id`), so a read that names the owner reads one partition ([Tenants and Owners](#tenants-and-owners)). diff --git a/Docs/design_patterns.md b/Docs/design_patterns.md index 73c9ff0..3b6d8d5 100644 --- a/Docs/design_patterns.md +++ b/Docs/design_patterns.md @@ -63,10 +63,10 @@ await mem.push_to_cosmos() ```python # Update content of an existing memory -await mem.update_cosmos(memory_id="", user_id="user-1", thread_id=THREAD_ID, memory_type="fact", content="Corrected message text") +await mem.update_cosmos(memory_id="", user_id="user-1", memory_type="fact", content="Corrected message text") -# Delete a memory (requires the partition keys and the memory_type) -await mem.delete_memory(memory_id="", user_id="user-1", thread_id=THREAD_ID, memory_type="fact") +# Delete a memory (needs the owner's user_id and the memory_type, not the thread) +await mem.delete_memory(memory_id="", user_id="user-1", memory_type="fact") ``` Deleting a fact or procedure also deletes the records that were retired into it (duplicates, the sources of a combined fact, and directives or corrections held by a procedure), so deleted information does not survive in history. See [Section 11](#11-secrets-and-deleting-memories). @@ -338,7 +338,7 @@ await mem.upsert_memory( ### Pattern: per-agent threads, cross-agent retrieval -Each agent writes to its own `thread_id`. Other agents discover relevant context through `search_cosmos` across all threads for the user. At the end, `generate_user_summary` produces a unified profile from all agent threads. +Each agent writes to its own `thread_id`. Other agents discover relevant context through `search_cosmos` across all threads for the user. At the end, `generate_user_summary` produces a unified profile from all agent threads. An agent can also own memories of its own (see [An agent as owner](#an-agent-as-owner)). ```python # After all agents finish @@ -359,15 +359,17 @@ When a new turn is written to the `memories_turns` container, the change feed tr 2. Checks whether the counter has crossed a configured threshold. 3. Starts the appropriate Durable Functions orchestration if the threshold is crossed. +The trigger reads `tenant_id` from each changed turn and processes it in that tenant, so one Function App serves every tenant that shares the database, with no tenant setting. A turn without a valid `tenant_id` is skipped with a warning. + ### Configuration Set these application settings (in `local.settings.json` locally or Function App settings in Azure): | Setting | Scope | Effect | |---------|-------|--------| -| `THREAD_SUMMARY_EVERY_N=5` | Per `(user_id, thread_id)` | Summarize the thread every 5 turns | -| `FACT_EXTRACTION_EVERY_N=3` | Per `(user_id, thread_id)` | Extract facts every 3 turns | -| `USER_SUMMARY_EVERY_N=10` | Per `user_id` | Update user profile every 10 turns across all threads | +| `THREAD_SUMMARY_EVERY_N=5` | Per `(tenant_id, user_id, thread_id)` | Summarize the thread every 5 turns | +| `FACT_EXTRACTION_EVERY_N=3` | Per `(tenant_id, user_id, thread_id)` | Extract facts every 3 turns | +| `USER_SUMMARY_EVERY_N=10` | Per `(tenant_id, user_id)` | Update user profile every 10 turns across all threads | Set any value to `0` to disable that processing type. The defaults are `10`, `2` and `20` (see [Threshold settings](concepts.md#threshold-settings)). Reconcile (`DEDUP_EVERY_N`) and procedure learning (`PROCEDURAL_SYNTHESIS_AUTO`) follow extraction automatically; see [Section 9](#9-procedures-and-standing-instructions) and [Section 10](#10-keeping-the-fact-pool-clean). The Function App also needs `MEMORY_PROCESSOR_OWNER=durable` (the Bicep template and `local.settings.json.template` set it); without it the trigger skips every batch. @@ -494,16 +496,53 @@ Credentials without a fixed format, such as `password: hunter2`, cannot be recog ### Deleting ```python -await mem.delete_memory(memory_id="", user_id="user-1", thread_id=THREAD_ID, memory_type="fact") +await mem.delete_memory(memory_id="", user_id="user-1", memory_type="fact") ``` -- Deleting a fact or procedure first deletes the records retired into it (`duplicate`, `combined` and `procedure`) and anything retired into those, each under its own `thread_id`, so what the user deleted is gone from history too. Records retired for any other reason (older records may carry `contradict` or `update`) stay, because they are earlier versions rather than copies. +- Deleting a fact or procedure first deletes the records retired into it (`duplicate`, `combined` and `procedure`) and anything retired into those, so what the user deleted is gone from history too. Records retired for any other reason (older records may carry `contradict` or `update`) stay, because they are earlier versions rather than copies. - To remove a piece of information, delete the fact that is active now. If it was folded into another fact, search returns the survivor; deleting a retired record removes only that record. - The cascade is sequential and best-effort: if deleting a folded record fails, the memory is kept and a retry resumes where it stopped. - `delete_thread` removes a thread's turns and summary only; the facts, episodes and procedures distilled from it are user-scoped and stay. --- +## 12. Tenants and Owners + +Every record is keyed by `[tenant_id, user_id]` (see [Tenants and Owners](concepts.md#tenants-and-owners)): `tenant_id` says whose memories these are, and `user_id` owns them, as a user or as an agent. + +### One client per tenant + +A client is bound to one tenant when you create it, and every read and write stays inside it. An app that serves several customers or environments from the same containers creates one client for each: + +```python +acme = AsyncCosmosMemoryClient(..., tenant_id="acme") +globex = AsyncCosmosMemoryClient(..., tenant_id="globex") + +await acme.upsert_memory(user_id="user-1", thread_id="t-1", role="user", content="I prefer dark mode.") +await globex.get_thread(thread_id="t-1", user_id="user-1") # [] - "user-1" at Globex is a different owner +``` + +The tenant is never a per-call argument and has no setting, so a call cannot reach into another tenant. The Function App follows the `tenant_id` stored on each turn. + +### An agent as owner + +`user_id` names whoever owns a memory, and that can be an agent. Use a distinct string such as `agent:support-bot` so it never collides with a user's id: + +```python +AGENT = "agent:support-bot" + +# What the agent itself has learned, apart from any user's memories +await mem.upsert_memory( + user_id=AGENT, thread_id="ops", role="system", memory_type="fact", + content="Refunds over $500 need a manager's approval.", +) +facts = await mem.search_cosmos("refund limits", user_id=AGENT, memory_types=["fact"], top_k=3) +``` + +Everything an owner knows sits in one partition, and Cosmos DB limits a logical partition to 20 GB of data and 10,000 RU/s. Keep each user's memories under that user's id and put only what belongs to the agent itself under the agent's, so that no single owner, such as an agent shared by many users, outgrows those limits. + +--- + ## Quick Reference | Operation | Method | When | @@ -523,3 +562,4 @@ await mem.delete_memory(memory_id="", user_id="user-1", thread_id=THREA | Clean up facts | `reconcile` | Fold duplicates, combine facts, link conflicts: automatic, or after a bulk import | | Summarize a user | `generate_user_summary` | Cross-session profiling, after thread summaries, or automatic via change feed | | Get user summary | `get_user_summary` | Start of a new session | +| Keep tenants apart | `tenant_id` (client argument) | One client per app, customer or environment that shares the containers | diff --git a/Docs/local_testing.md b/Docs/local_testing.md index 98c8ce3..e462336 100644 --- a/Docs/local_testing.md +++ b/Docs/local_testing.md @@ -109,7 +109,7 @@ In `function_app/local.settings.json`, add these to enable automatic processing: The Function App skips every change feed batch unless `MEMORY_PROCESSOR_OWNER` is `durable`. Set `MEMORY_PROCESSOR_OWNER=durable` in the SDK's `.env` as well, so the SDK does not also process the same turns in-process. -Set any threshold to `"0"` to disable that processing type. `USER_SUMMARY_WAIT_SECONDS` (default `120`) and `USER_SUMMARY_WAIT_INTERVAL_SECONDS` (default `10`) set how long a user-summary run waits, polling at that interval, for extraction to save a new user's first memories before it skips that cycle. See `function_app/local.settings.json.template` for the full template. +Set any threshold to `"0"` to disable that processing type. There is no tenant setting: the Function App processes each turn in the tenant stored on it, which is the `tenant_id` of the client that wrote it (`"default"` unless set). `USER_SUMMARY_WAIT_SECONDS` (default `120`) and `USER_SUMMARY_WAIT_INTERVAL_SECONDS` (default `10`) set how long a user-summary run waits, polling at that interval, for extraction to save a new user's first memories before it skips that cycle. See `function_app/local.settings.json.template` for the full template. --- @@ -235,7 +235,7 @@ for r in results: await memory.close() ``` -`create_memory_store()` creates the database and the `memories`, `memories_turns`, `memories_summaries`, `counter`, and `leases` containers. It configures the hierarchical partition key (`user_id`, `thread_id`) for the first four and `/id` for `leases`, gives a newly created `memories_turns` container a 30-day default TTL and a newly created `counter` container a 90-day one, and applies either serverless or autoscale throughput based on `cosmos_throughput_mode` (set from `COSMOS_DB_THROUGHPUT_MODE` above). +`create_memory_store()` creates the database and the `memories`, `memories_turns`, `memories_summaries`, `counter`, and `leases` containers. It configures the hierarchical partition key (`/tenant_id`, `/user_id`) for the first four and `/id` for `leases`, gives a newly created `memories_turns` container a 30-day default TTL and a newly created `counter` container a 90-day one, and applies either serverless or autoscale throughput based on `cosmos_throughput_mode` (set from `COSMOS_DB_THROUGHPUT_MODE` above). An existing container keeps its key, so recreate the containers that an earlier version created with `[/user_id, /thread_id]`, and `leases` with them so the change feed starts clean on the recreated turns container. --- @@ -335,7 +335,7 @@ If you have configured the change feed settings above, you can test automatic pr 1. Set a low threshold for testing, e.g. `THREAD_SUMMARY_EVERY_N=3` (restart the host after changing it). 2. Write turns to Cosmos with the SDK until the threshold is crossed. -3. Watch the Functions host logs - you should see the orchestrator being started automatically, for example `change-feed: starting ThreadSummaryOrchestrator instance=thread_summary:user-001::3`. +3. Watch the Functions host logs - you should see the orchestrator being started automatically, for example `change-feed: starting ThreadSummaryOrchestrator instance=thread_summary::3`. ```python import uuid diff --git a/Docs/operations.md b/Docs/operations.md index 3bb0c68..54795ac 100644 --- a/Docs/operations.md +++ b/Docs/operations.md @@ -31,6 +31,10 @@ Override the turns container default at provision time (it applies to documents Function-app threshold knobs (`THREAD_SUMMARY_EVERY_N`, `FACT_EXTRACTION_EVERY_N`, `DEDUP_EVERY_N`, `USER_SUMMARY_EVERY_N`, `MAX_BATCH_SIZE`, `DEDUP_POOL_SIZE`, `ACTIVITY_TIME_BUDGET_SECONDS`, `MEMORY_PROCESSOR_OWNER`) are Bicep parameters, documented in [`infra/README.md` → Counter-based trigger configuration](../infra/README.md#counter-based-trigger-configuration-function-app-only). Change them with `azd env set ...` then `azd up`. `MAX_BATCH_SIZE` must be at least 1; a lower value falls back to `20`. +## Tenants + +The tenant is not a setting. A client takes `tenant_id` as a constructor argument (default `"default"`), and the Function App processes each turn in the tenant stored on it, so one deployment serves every tenant of the database. See [Tenants and Owners](concepts.md#tenants-and-owners). + ## Reconcile, procedure and extraction knobs These settings are read from the environment: `.env` for the SDK, App Settings for the Function App. On the Function App, `DEDUP_POOL_SIZE` and `ACTIVITY_TIME_BUDGET_SECONDS` are Bicep parameters (`azd env set DEDUP_POOL_SIZE 100`, then `azd up`); the others below are not, so the code defaults apply unless you set them. Set one on the Function App with `az functionapp config appsettings set`, or add it to `infra/modules/functions.bicep` so `azd up` keeps it. diff --git a/Docs/public_api.md b/Docs/public_api.md index a348d60..6ff0614 100644 --- a/Docs/public_api.md +++ b/Docs/public_api.md @@ -13,14 +13,16 @@ ### Connection -- `__init__(cosmos_endpoint=None, cosmos_credential=None, cosmos_key=None, cosmos_database=None, cosmos_container=None, cosmos_turns_container='memories_turns', cosmos_summaries_container='memories_summaries', cosmos_counter_container=None, cosmos_lease_container=None, cosmos_throughput_mode=None, cosmos_autoscale_max_ru=None, ai_foundry_endpoint=None, ai_foundry_credential=None, ai_foundry_api_key=None, embedding_deployment_name='text-embedding-3-large', embedding_dimensions=None, chat_deployment_name='gpt-4o-mini', use_default_credential=True, enable_turn_embeddings=None, user_agent=None, embeddings_client=None, chat_client=None, processor=None, transcript_metadata_keys=None, cadence_thresholds=None, cosmos_preferred_locations=None) -> None` - configure local state, model clients, optional Cosmos auto-connect (with a `cosmos_endpoint` it calls `create_memory_store()`, which creates any missing database or container), and optional processing backend. The SDK uses a hard 3-container topology: turns in `memories_turns`, facts/episodic/procedural in `memories`, and summaries in `memories_summaries` (or the names you pass). `enable_turn_embeddings` (default `False`, env `ENABLE_TURN_EMBEDDINGS`) embeds raw turns on write so they can be vector-searched via `search_turns()`; the turns container is always provisioned with a vector index, so toggling this never requires recreating it. `cosmos_preferred_locations` (a list or a comma-separated string, env `COSMOS_DB_PREFERRED_REGIONS`) orders the Cosmos DB regions the client reads from, closest first; unset keeps the account's default order. +- `__init__(cosmos_endpoint=None, cosmos_credential=None, cosmos_key=None, cosmos_database=None, cosmos_container=None, cosmos_turns_container='memories_turns', cosmos_summaries_container='memories_summaries', cosmos_counter_container=None, cosmos_lease_container=None, cosmos_throughput_mode=None, cosmos_autoscale_max_ru=None, ai_foundry_endpoint=None, ai_foundry_credential=None, ai_foundry_api_key=None, embedding_deployment_name='text-embedding-3-large', embedding_dimensions=None, chat_deployment_name='gpt-4o-mini', use_default_credential=True, enable_turn_embeddings=None, user_agent=None, embeddings_client=None, chat_client=None, processor=None, transcript_metadata_keys=None, cadence_thresholds=None, cosmos_preferred_locations=None, tenant_id=None) -> None` - configure local state, model clients, optional Cosmos auto-connect (with a `cosmos_endpoint` it calls `create_memory_store()`, which creates any missing database or container), and optional processing backend. The SDK uses a hard 3-container topology: turns in `memories_turns`, facts/episodic/procedural in `memories`, and summaries in `memories_summaries` (or the names you pass). `enable_turn_embeddings` (default `False`, env `ENABLE_TURN_EMBEDDINGS`) embeds raw turns on write so they can be vector-searched via `search_turns()`; the turns container is always provisioned with a vector index, so toggling this never requires recreating it. `cosmos_preferred_locations` (a list or a comma-separated string, env `COSMOS_DB_PREFERRED_REGIONS`) orders the Cosmos DB regions the client reads from, closest first; unset keeps the account's default order. `tenant_id` (`None` selects `"default"`) binds the client to one tenant: every record it writes carries it, and every read and write stays inside it (see [Tenants and Owners](concepts.md#tenants-and-owners)). It is set once, here, never per call, and has no environment variable; an invalid value raises `ValidationError`, and the read-only `tenant_id` property returns it. - `close() -> None` - close Cosmos/model clients and owned credentials. - `connect_cosmos(endpoint=None, credential=None, key=None, database=None, container=None, turns_container=None, summaries_container=None) -> None` - connect to existing memory, turns, and summaries containers. -- `create_memory_store(database=None, container=None, turns_container=None, summaries_container=None, counter_container=None, lease_container=None, endpoint=None, credential=None, key=None, embedding_dimensions=None, embedding_data_type=None, distance_function=None, full_text_language=None, throughput_mode=None, autoscale_max_ru=None, vector_index_type=None) -> None` - create/connect the memory, turns, summaries, counter, and lease containers. `vector_index_type` (`quantizedFlat` by default, `diskANN` or `flat`) sets the memories container's vector index; the turns and summaries containers always use `quantizedFlat`. -- `validate_topology() -> None` - read metadata for all three memory containers and raise `RuntimeError` if any is missing or unreachable; call after connecting to catch infrastructure/config drift before writes. +- `create_memory_store(database=None, container=None, turns_container=None, summaries_container=None, counter_container=None, lease_container=None, endpoint=None, credential=None, key=None, embedding_dimensions=None, embedding_data_type=None, distance_function=None, full_text_language=None, throughput_mode=None, autoscale_max_ru=None, vector_index_type=None) -> None` - create/connect the memory, turns, summaries, counter, and lease containers. The memory, turns, summaries and counter containers get the hierarchical partition key `/tenant_id`, `/user_id` (`leases` uses `/id`); an existing container keeps its key, and `create_memory_store()` raises `CosmosOperationError` when one of them is keyed otherwise, so recreate the containers created with an earlier key, and `leases` with them so the change feed starts clean on the recreated turns container (see [Tenants and Owners](concepts.md#tenants-and-owners)). `vector_index_type` (`quantizedFlat` by default, `diskANN` or `flat`) sets the memories container's vector index; the turns and summaries containers always use `quantizedFlat`. +- `validate_topology() -> None` - read metadata for the memories, turns, summaries and counter containers and raise `RuntimeError` if any is missing, unreachable, or not keyed `[/tenant_id, /user_id]`; call after connecting to catch infrastructure/config drift before writes. ### Memory CRUD +`update_cosmos`, `delete_memory`, `delete_turn`, `add_tags`, `remove_tags` and `get_memory_history` find a record by its owner (`user_id`) and need no `thread_id`: `thread_id` is a plain field, not part of the partition key. + - `add_local(user_id, role, content, memory_type='turn', agent_id=None, metadata=None, thread_id=None, tags=None, ttl=None, salience=None) -> None` - append a memory to the local buffer. `thread_id` is required when `memory_type='turn'`. - `get_local(memory_id=None, user_id=None, role=None, memory_types=None) -> list[dict]` - filter local buffered memories. - `update_local(memory_id, content=None, role=None, memory_type=None, metadata=None) -> None` - update a local buffered memory. @@ -28,22 +30,22 @@ - `upsert_memory(user_id, role, content, memory_type='turn', metadata=None, thread_id=None, tags=None, ttl=None, salience=None, embedding=None, embed=None, created_at=None) -> str` - upsert one memory to Cosmos and return its id. `created_at` (an ISO 8601 string or `datetime`; a naive value is read as UTC) sets the record's creation time instead of now. `thread_id` is required when `memory_type='turn'`. - `push_to_cosmos(batch_size=25) -> None` - upload all local buffered memories to Cosmos. The buffer is not cleared, so a later call uploads them again. - `get_memories(memory_id=None, user_id=None, thread_id=None, role=None, memory_types=None, recent_k=None, tags_all=None, tags_any=None, exclude_tags=None, include_superseded=False, min_salience=None, min_confidence=None, created_after=None, created_before=None) -> list[dict]` - retrieve memories from the MEMORIES container. `memory_types` defaults to `["fact", "episodic", "procedural"]` and must be a subset of those three. -- `get_memory_history(memory_id, user_id, thread_id=None, *, max_depth=20) -> list[dict]` - the records a memory superseded, directly or through earlier replacements (up to `max_depth` levels), most recently superseded first, each with its `superseded_at` and `supersede_reason`; the memory itself is not included. -- `update_cosmos(memory_id, *, user_id, thread_id, memory_type, content=None, role=None, metadata=None) -> None` - point-update a memory in the container that holds `memory_type`. The `type` field itself is never mutated. `metadata`, when given, replaces the stored metadata wholesale. An existing vector is rebuilt when the text it encodes changes or the secret guard redacts it (one embedding call); if embedding fails or is not configured, the memory keeps its previous vector (stale until a later update changes the text) and the failure is logged. The vector is dropped only when the text it was built from held a credential. -- `delete_memory(memory_id, *, user_id, thread_id, memory_type) -> None` - delete a memory from the container that holds `memory_type`. Deleting a `fact` or `procedural` memory first deletes the records folded into it: duplicates retired into a fact (`supersede_reason="duplicate"`), the sources of a combined fact (`"combined"`), the directives and corrections retired into a procedure (`"procedure"`), and anything folded into those. They are found across the user's partitions and deleted one at a time, each under its own `thread_id`; if one delete fails the memory is kept and a retry resumes. Records retired for another reason (older records may carry `"update"` or `"contradict"`) are earlier versions and stay. -- `delete_turn(turn_id, *, user_id, thread_id) -> None` - delete one turn; raises `MemoryNotFoundError` if it does not exist. +- `get_memory_history(memory_id, user_id, *, max_depth=20) -> list[dict]` - the records a memory superseded, directly or through earlier replacements (up to `max_depth` levels), most recently superseded first, each with its `superseded_at` and `supersede_reason`; the memory itself is not included. +- `update_cosmos(memory_id, *, user_id, memory_type, content=None, role=None, metadata=None) -> None` - point-update a memory in the container that holds `memory_type`. The `type` field itself is never mutated. `metadata`, when given, replaces the stored metadata wholesale. An existing vector is rebuilt when the text it encodes changes or the secret guard redacts it (one embedding call); if embedding fails or is not configured, the memory keeps its previous vector (stale until a later update changes the text) and the failure is logged. The vector is dropped only when the text it was built from held a credential. +- `delete_memory(memory_id, *, user_id, memory_type) -> None` - delete a memory from the container that holds `memory_type`. Deleting a `fact` or `procedural` memory first deletes the records folded into it: duplicates retired into a fact (`supersede_reason="duplicate"`), the sources of a combined fact (`"combined"`), the directives and corrections retired into a procedure (`"procedure"`), and anything folded into those. They are found in the owner's partition and deleted one at a time; if one delete fails the memory is kept and a retry resumes. Records retired for another reason (older records may carry `"update"` or `"contradict"`) are earlier versions and stay. +- `delete_turn(turn_id, *, user_id) -> None` - delete one turn; raises `MemoryNotFoundError` if it does not exist. - `delete_thread_summary(user_id, thread_id) -> bool` - delete a thread's summary; `True` if one was deleted, `False` if there was none. - `delete_user_summary(user_id) -> bool` - delete the user's summary; `True` if one was deleted, `False` if there was none. - `delete_thread(user_id, thread_id, *, include_summary=True) -> int` - delete all of a thread's turns and, by default, its summary, and return how many documents were deleted. Facts, episodes and procedures learned from the thread belong to the user and are kept. - `get_thread(thread_id, user_id=None, recent_k=None, tags_all=None, tags_any=None, exclude_tags=None, include_superseded=False, created_after=None, created_before=None) -> list[dict]` - retrieve turns from the TURNS container oldest-first. -- `get_thread_summary(user_id, thread_id, recent_k=None) -> list[dict]` - retrieve thread summary documents from the SUMMARIES container for a single `(user_id, thread_id)` partition. +- `get_thread_summary(user_id, thread_id, recent_k=None) -> list[dict]` - retrieve thread summary documents from the SUMMARIES container for one thread of `user_id`. - `get_episodes(user_id, thread_id=None, recent_k=None) -> list[dict]` - retrieve the user's active episodic memories, newest first; `thread_id` narrows to one thread and `recent_k` keeps the newest. - `get_user_summary(user_id) -> Optional[dict]` - retrieve the active user-summary document. ### Retrieval - `search_cosmos(search_terms, memory_id=None, user_id=None, role=None, memory_types=None, thread_id=None, top_k=5, tags_all=None, tags_any=None, exclude_tags=None, include_superseded=False, min_salience=None, min_confidence=None, created_after=None, created_before=None, include_episodes=False, include_turns=False, turn_top_k=None, include_summaries=False, summary_top_k=None, preference_slot=False, procedure_slot=False) -> list[dict]` - hybrid vector/full-text search memories, falling back to vector-only for all-stopword queries. It searches facts unless `memory_types` says otherwise, and `include_episodes=True` adds episodes. `include_summaries` / `include_turns` append summaries / turns after the memories (capped by `summary_top_k` / `turn_top_k`, default `top_k`), deduped by content, and are ignored without `user_id`. `preference_slot` / `procedure_slot` reserve result slots within `top_k`. Procedures are returned only while `active` and not past `valid_until`. With `user_id`, a fact that conflicts with others carries `conflicts_with`. See [Search scoping, procedures and slots](#search-scoping-procedures-and-slots) and [Conflicts in search results](#conflicts-in-search-results). -- `search_turns(search_terms, user_id, thread_id=None, role=None, top_k=5, tags_all=None, tags_any=None, exclude_tags=None, created_after=None, created_before=None) -> list[dict]` - hybrid vector/full-text search the raw conversation log instead of facts/episodic/procedural (requires turn embeddings; see `enable_turn_embeddings`). `user_id` is required and always filters the results (`c.user_id`); a keyword query runs across partitions, a vector-only query with a `thread_id` reads one. +- `search_turns(search_terms, user_id, thread_id=None, role=None, top_k=5, tags_all=None, tags_any=None, exclude_tags=None, created_after=None, created_before=None) -> list[dict]` - hybrid vector/full-text search the raw conversation log instead of facts/episodic/procedural (requires turn embeddings; see `enable_turn_embeddings`). `user_id` is required and always filters the results (`c.user_id`); a keyword query runs across partitions, a vector-only query reads one. - `search_summaries(search_terms, user_id, thread_id=None, top_k=5, tags_all=None, tags_any=None, exclude_tags=None) -> list[dict]` - hybrid vector/full-text search the user's thread and user summaries; `thread_id` narrows it to one thread's summary. - `get_procedural_prompt(user_id) -> Optional[str]` - the user's standing instructions (the same text as `build_procedural_context(user_id)`), or `None` when there are none. - `get_procedural_history(user_id, limit=10) -> list[dict]` - list up to `limit` of the user's procedures: superseded ones last, otherwise highest `version` first. @@ -63,7 +65,7 @@ compete with facts in one ranked result set. #### Search scoping, procedures and slots -- **Partitions.** A keyword query ranks with `FullTextScore`, which is ignored in a query the Python SDK sends with a partition key, because it skips query planning ([Azure/azure-sdk-for-python#42241](https://github.com/Azure/azure-sdk-for-python/issues/42241)). `search_cosmos`, `search_turns`, `search_summaries`, `search_episodic_memories` and `retrieve_procedures` therefore run a keyword query across partitions, with `c.user_id` (and `c.thread_id`, when given) in the `WHERE` clause, and set `full_text_score_scope="Local"` so BM25 statistics come from the partition ranges the query targets. The filters still confine the results to the same user and thread (in `search_cosmos`, episodic and procedural memories match on the user alone); ranking now follows the question. Expect more RUs than a single-partition read on a large container. A vector-only query (all-stopword terms) with both `user_id` and `thread_id` still reads one partition, except a `search_cosmos` that searches episodic or procedural memories, which always runs across partitions. `MemoryStore.query()` and `AsyncMemoryStore.query()` raise `ValidationError` for a `FullTextScore` query sent with a partition key; filter on `c.user_id` and `c.thread_id` in the `WHERE` clause instead. +- **Partitions.** A keyword query ranks with `FullTextScore`, which is ignored in a query the Python SDK sends with a partition key, because it skips query planning ([Azure/azure-sdk-for-python#42241](https://github.com/Azure/azure-sdk-for-python/issues/42241)). `search_cosmos`, `search_turns`, `search_summaries`, `search_episodic_memories` and `retrieve_procedures` therefore run a keyword query across partitions, with `c.tenant_id`, `c.user_id` (and `c.thread_id`, when given) in the `WHERE` clause, and set `full_text_score_scope="Local"` so BM25 statistics come from the partition ranges the query targets. The filters still confine the results to the client's tenant and, with a `user_id`, to the same owner (in `search_cosmos`, episodic and procedural memories match on the owner alone, whatever the `thread_id`); ranking now follows the question. Expect more RUs than a single-partition read on a large container. A vector-only query (all-stopword terms) with a `user_id` reads one partition, the owner's, whatever the `thread_id`; a `search_cosmos` without a `user_id` covers every owner in the tenant and always runs across partitions. `MemoryStore.query()` and `AsyncMemoryStore.query()` raise `ValidationError` for a `FullTextScore` query sent with a partition key; filter on `c.tenant_id`, `c.user_id` and `c.thread_id` in the `WHERE` clause instead. - **Procedures.** `search_cosmos` hides procedures that are not `active` (a `candidate`, for one) or are past `valid_until` (an ISO date; no value means no end). `get_procedural_memories` lists them and `retrieve_procedures(..., status=None)` ranks candidates. - **Slots** (opt-in). `preference_slot=True` reserves one of the `top_k` results for the user's best-matching preference fact (`metadata.category="preference"`) that the ranked results do not already show. `procedure_slot=True` reserves one for the user's best-matching active situational procedure (`applies="when"`); procedures then leave the ranked results. Slot candidates are ranked by vector similarity alone and use the search's own filters, except that the procedure slot ignores `role`, `tags_all`, `tags_any`, `min_salience` and `min_confidence`, which no procedure can meet (a procedure has no salience or confidence, its role is `system` and its tags are the toolkit's own). A slot with no candidate takes the next ranked result, so `top_k` stays filled. A slotted result carries `retrieval={"rank": <1-based position>, "slot": "preference" | "procedure" | "backfill"}`; ranked results carry none. Slots need `user_id` and are skipped with `memory_id` or when `top_k` would leave no ranked result. The preference slot applies only when facts are searched, and `procedure_slot` has no effect when only procedural types are searched. Episodes never take a slot, and summaries and turns blended in with `include_summaries` / `include_turns` still follow the `top_k` results. @@ -86,8 +88,8 @@ The clients run each pass to completion. `PipelineService.reconcile_memories(use ### Tagging -- `add_tags(memory_id, user_id, thread_id, memory_type, tags) -> None` - add tags to a memory. `memory_type` must be one of `fact`, `episodic`, `procedural`. -- `remove_tags(memory_id, user_id, thread_id, memory_type, tags) -> None` - remove tags from a memory. `memory_type` must be one of `fact`, `episodic`, `procedural`. +- `add_tags(memory_id, user_id, memory_type, tags) -> None` - add tags to a memory. `memory_type` must be one of `fact`, `episodic`, `procedural`. +- `remove_tags(memory_id, user_id, memory_type, tags) -> None` - remove tags from a memory. `memory_type` must be one of `fact`, `episodic`, `procedural`. - `list_tags(user_id, *, thread_id=None, prefix=None, include_sys=False) -> list[str]` - list sorted, deduped tags for a user; omits `sys:*` by default. ## AsyncCosmosMemoryClient @@ -96,11 +98,11 @@ Local-buffer methods remain synchronous in-memory operations; Cosmos, retrieval, ### Connection -- `__init__(cosmos_endpoint=None, cosmos_credential=None, cosmos_key=None, cosmos_database=None, cosmos_container=None, cosmos_turns_container='memories_turns', cosmos_summaries_container='memories_summaries', cosmos_counter_container=None, cosmos_lease_container=None, cosmos_throughput_mode=None, cosmos_autoscale_max_ru=None, ai_foundry_endpoint=None, ai_foundry_credential=None, ai_foundry_api_key=None, embedding_deployment_name='text-embedding-3-large', embedding_dimensions=None, chat_deployment_name='gpt-4o-mini', use_default_credential=True, enable_turn_embeddings=None, user_agent=None, embeddings_client=None, chat_client=None, processor=None, transcript_metadata_keys=None, cadence_thresholds=None, cosmos_preferred_locations=None) -> None` - configure async local state, model clients, and optional processing backend; it does not connect to Cosmos, so await `connect_cosmos()` or `create_memory_store()`. The async SDK uses the same hard 3-container topology as the sync client. `enable_turn_embeddings` (default `False`, env `ENABLE_TURN_EMBEDDINGS`) embeds raw turns on write so they can be vector-searched via `search_turns()`. `cosmos_preferred_locations` (a list or a comma-separated string, env `COSMOS_DB_PREFERRED_REGIONS`) orders the Cosmos DB regions the client reads from, closest first; unset keeps the account's default order. +- `__init__(cosmos_endpoint=None, cosmos_credential=None, cosmos_key=None, cosmos_database=None, cosmos_container=None, cosmos_turns_container='memories_turns', cosmos_summaries_container='memories_summaries', cosmos_counter_container=None, cosmos_lease_container=None, cosmos_throughput_mode=None, cosmos_autoscale_max_ru=None, ai_foundry_endpoint=None, ai_foundry_credential=None, ai_foundry_api_key=None, embedding_deployment_name='text-embedding-3-large', embedding_dimensions=None, chat_deployment_name='gpt-4o-mini', use_default_credential=True, enable_turn_embeddings=None, user_agent=None, embeddings_client=None, chat_client=None, processor=None, transcript_metadata_keys=None, cadence_thresholds=None, cosmos_preferred_locations=None, tenant_id=None) -> None` - configure async local state, model clients, and optional processing backend; it does not connect to Cosmos, so await `connect_cosmos()` or `create_memory_store()`. The async SDK uses the same hard 3-container topology as the sync client. `enable_turn_embeddings` (default `False`, env `ENABLE_TURN_EMBEDDINGS`) embeds raw turns on write so they can be vector-searched via `search_turns()`. `cosmos_preferred_locations` (a list or a comma-separated string, env `COSMOS_DB_PREFERRED_REGIONS`) orders the Cosmos DB regions the client reads from, closest first; unset keeps the account's default order. `tenant_id` binds the client to one tenant and works as in the sync client. - `async close() -> None` - cancel any pending background processing tasks, then close async/sync resources and owned credentials. - `async connect_cosmos(endpoint=None, credential=None, key=None, database=None, container=None, turns_container=None, summaries_container=None) -> None` - connect to existing memory, turns, and summaries containers. -- `async create_memory_store(database=None, container=None, turns_container=None, summaries_container=None, counter_container=None, lease_container=None, endpoint=None, credential=None, key=None, embedding_dimensions=None, embedding_data_type=None, distance_function=None, full_text_language=None, throughput_mode=None, autoscale_max_ru=None, vector_index_type=None) -> None` - create/connect memory, turns, summaries, counter, and lease containers; `vector_index_type` works as in the sync method. -- `async validate_topology() -> None` - read metadata for all three memory containers and raise `RuntimeError` if any is missing or unreachable; call after connecting to catch infrastructure/config drift before writes. +- `async create_memory_store(database=None, container=None, turns_container=None, summaries_container=None, counter_container=None, lease_container=None, endpoint=None, credential=None, key=None, embedding_dimensions=None, embedding_data_type=None, distance_function=None, full_text_language=None, throughput_mode=None, autoscale_max_ru=None, vector_index_type=None) -> None` - create/connect memory, turns, summaries, counter, and lease containers; `vector_index_type` and the partition key work as in the sync method. +- `async validate_topology() -> None` - read metadata for the memories, turns, summaries and counter containers and raise `RuntimeError` if any is missing, unreachable, or not keyed `[/tenant_id, /user_id]`; call after connecting to catch infrastructure/config drift before writes. ### Memory CRUD @@ -111,22 +113,22 @@ Local-buffer methods remain synchronous in-memory operations; Cosmos, retrieval, - `async upsert_memory(user_id, role, content, memory_type='turn', metadata=None, thread_id=None, tags=None, ttl=None, salience=None, embedding=None, embed=None, created_at=None) -> str` - upsert one memory to Cosmos and return its id; `created_at` and `thread_id` work as in the sync method. - `async push_to_cosmos(batch_size=25) -> None` - upload all local buffered memories to Cosmos; the buffer is not cleared. - `async get_memories(memory_id=None, user_id=None, thread_id=None, role=None, memory_types=None, recent_k=None, tags_all=None, tags_any=None, exclude_tags=None, include_superseded=False, min_salience=None, min_confidence=None, created_after=None, created_before=None) -> list[dict]` - retrieve memories from the MEMORIES container. `memory_types` defaults to `["fact", "episodic", "procedural"]` and must be a subset of those three. -- `async get_memory_history(memory_id, user_id, thread_id=None, *, max_depth=20) -> list[dict]` - the records a memory superseded, most recently superseded first, as in the sync method. -- `async update_cosmos(memory_id, *, user_id, thread_id, memory_type, content=None, role=None, metadata=None) -> None` - point-update a memory in the container that holds `memory_type`. The `type` field itself is never mutated. `metadata`, when given, replaces the stored metadata wholesale. An existing vector is rebuilt when the text it encodes changes or the secret guard redacts it (one embedding call); if embedding fails or is not configured, the memory keeps its previous vector (stale until a later update changes the text) and the failure is logged. The vector is dropped only when the text it was built from held a credential. -- `async delete_memory(memory_id, *, user_id, thread_id, memory_type) -> None` - delete a memory from the container that holds `memory_type`. Cascades like the sync method: deleting a `fact` or `procedural` memory first deletes the records folded into it (`supersede_reason` `duplicate`, `combined` or `procedure`, and anything folded into those); earlier versions (older records may carry `update` or `contradict`) stay. -- `async delete_turn(turn_id, *, user_id, thread_id) -> None` - delete one turn; raises `MemoryNotFoundError` if it does not exist. +- `async get_memory_history(memory_id, user_id, *, max_depth=20) -> list[dict]` - the records a memory superseded, most recently superseded first, as in the sync method. +- `async update_cosmos(memory_id, *, user_id, memory_type, content=None, role=None, metadata=None) -> None` - point-update a memory in the container that holds `memory_type`. The `type` field itself is never mutated. `metadata`, when given, replaces the stored metadata wholesale. An existing vector is rebuilt when the text it encodes changes or the secret guard redacts it (one embedding call); if embedding fails or is not configured, the memory keeps its previous vector (stale until a later update changes the text) and the failure is logged. The vector is dropped only when the text it was built from held a credential. +- `async delete_memory(memory_id, *, user_id, memory_type) -> None` - delete a memory from the container that holds `memory_type`. Cascades like the sync method: deleting a `fact` or `procedural` memory first deletes the records folded into it (`supersede_reason` `duplicate`, `combined` or `procedure`, and anything folded into those); earlier versions (older records may carry `update` or `contradict`) stay. +- `async delete_turn(turn_id, *, user_id) -> None` - delete one turn; raises `MemoryNotFoundError` if it does not exist. - `async delete_thread_summary(user_id, thread_id) -> bool` - delete a thread's summary; `True` if one was deleted, `False` if there was none. - `async delete_user_summary(user_id) -> bool` - delete the user's summary; `True` if one was deleted, `False` if there was none. - `async delete_thread(user_id, thread_id, *, include_summary=True) -> int` - delete all of a thread's turns and, by default, its summary, and return how many documents were deleted. Facts, episodes and procedures learned from the thread belong to the user and are kept. - `async get_thread(thread_id, user_id=None, recent_k=None, tags_all=None, tags_any=None, exclude_tags=None, include_superseded=False, created_after=None, created_before=None) -> list[dict]` - retrieve turns from the TURNS container oldest-first. -- `async get_thread_summary(user_id, thread_id, recent_k=None) -> list[dict]` - retrieve thread summary documents from the SUMMARIES container for a single `(user_id, thread_id)` partition. +- `async get_thread_summary(user_id, thread_id, recent_k=None) -> list[dict]` - retrieve thread summary documents from the SUMMARIES container for one thread of `user_id`. - `async get_episodes(user_id, thread_id=None, recent_k=None) -> list[dict]` - retrieve the user's active episodic memories, newest first; `thread_id` narrows to one thread and `recent_k` keeps the newest. - `async get_user_summary(user_id) -> Optional[dict]` - retrieve the active user-summary document. ### Retrieval - `async search_cosmos(search_terms, memory_id=None, user_id=None, role=None, memory_types=None, thread_id=None, top_k=5, tags_all=None, tags_any=None, exclude_tags=None, include_superseded=False, min_salience=None, min_confidence=None, created_after=None, created_before=None, include_episodes=False, include_turns=False, turn_top_k=None, include_summaries=False, summary_top_k=None, preference_slot=False, procedure_slot=False) -> list[dict]` - hybrid vector/full-text search memories, falling back to vector-only for all-stopword queries. Searched types, blending, slots, procedure visibility, partition scoping and `conflicts_with` match the sync method (see [Search scoping, procedures and slots](#search-scoping-procedures-and-slots) and [Conflicts in search results](#conflicts-in-search-results)). -- `async search_turns(search_terms, user_id, thread_id=None, role=None, top_k=5, tags_all=None, tags_any=None, exclude_tags=None, created_after=None, created_before=None) -> list[dict]` - hybrid vector/full-text search the raw conversation log instead of facts/episodic/procedural (requires turn embeddings; see `enable_turn_embeddings`). `user_id` is required and always filters the results (`c.user_id`); a keyword query runs across partitions, a vector-only query with a `thread_id` reads one. +- `async search_turns(search_terms, user_id, thread_id=None, role=None, top_k=5, tags_all=None, tags_any=None, exclude_tags=None, created_after=None, created_before=None) -> list[dict]` - hybrid vector/full-text search the raw conversation log instead of facts/episodic/procedural (requires turn embeddings; see `enable_turn_embeddings`). `user_id` is required and always filters the results (`c.user_id`); a keyword query runs across partitions, a vector-only query reads one. - `async search_summaries(search_terms, user_id, thread_id=None, top_k=5, tags_all=None, tags_any=None, exclude_tags=None) -> list[dict]` - hybrid vector/full-text search the user's thread and user summaries; `thread_id` narrows it to one thread's summary. - `async get_procedural_prompt(user_id) -> Optional[str]` - the user's standing instructions (the same text as `build_procedural_context(user_id)`), or `None` when there are none. - `async get_procedural_history(user_id, limit=10) -> list[dict]` - list up to `limit` of the user's procedures: superseded ones last, otherwise highest `version` first. @@ -156,8 +158,8 @@ memory as user-scoped and may return episodes from other threads for that user. ### Tagging -- `async add_tags(memory_id, user_id, thread_id, memory_type, tags) -> None` - add tags to a memory. `memory_type` must be one of `fact`, `episodic`, `procedural`. -- `async remove_tags(memory_id, user_id, thread_id, memory_type, tags) -> None` - remove tags from a memory. `memory_type` must be one of `fact`, `episodic`, `procedural`. +- `async add_tags(memory_id, user_id, memory_type, tags) -> None` - add tags to a memory. `memory_type` must be one of `fact`, `episodic`, `procedural`. +- `async remove_tags(memory_id, user_id, memory_type, tags) -> None` - remove tags from a memory. `memory_type` must be one of `fact`, `episodic`, `procedural`. - `async list_tags(user_id, *, thread_id=None, prefix=None, include_sys=False) -> list[str]` - list sorted, deduped tags for a user; omits `sys:*` by default. ## Fact fields @@ -189,7 +191,7 @@ A procedural memory (type `procedural`, stored under the sentinel thread id `__p Anything else stays a `candidate`, which search, `retrieve_procedures` (default `status="active"`) and `build_procedural_context` do not show. Teaching evidence counts only from a fact the user stated that extraction recorded as a `directive` or `correction` (a fact extracted before assertions existed also counts), so a plain preference or a request about one task stays a candidate. `valid_until` (an ISO date) ends a procedure's validity, `version` rises with every revision, `source_kind` and `source_authority` are derived from the strongest evidence, and the ID derives from the user, kind and name, so a repeated lesson reinforces one record. -`synthesize_procedural` reads the user's active preference and requirement facts, facts with salience of at least 0.8, `directive` and `correction` facts, and episodes with lessons, written after the `procedure_cursor` document (under `[user_id, "__procedural__"]`): at most 50 facts and 50 episodes per run, shown to the model 10 at a time with the user's nearest existing procedures so it revises or reinforces one instead of writing a paraphrase. A revision that drops a number or a negation records nothing, unless it is the user's correction. When an active situational procedure holds a directive or correction fact it cites, that fact is retired into the procedure (`supersede_reason="procedure"`), so the rule is stored and retrieved once. A standing rule leaves its facts in place, because it reaches the agent through `build_procedural_context`. +`synthesize_procedural` reads the user's active preference and requirement facts, facts with salience of at least 0.8, `directive` and `correction` facts, and episodes with lessons, written after the `procedure_cursor` document (under the sentinel thread id `__procedural__`): at most 50 facts and 50 episodes per run, shown to the model 10 at a time with the user's nearest existing procedures so it revises or reinforces one instead of writing a paraphrase. A revision that drops a number or a negation records nothing, unless it is the user's correction. When an active situational procedure holds a directive or correction fact it cites, that fact is retired into the procedure (`supersede_reason="procedure"`), so the rule is stored and retrieved once. A standing rule leaves its facts in place, because it reaches the agent through `build_procedural_context`. ## Secret redaction @@ -199,7 +201,7 @@ Credentials without a fixed format, such as `password: hunter2` typed into a cha ## Topology validation -Use `validate_topology()` (sync) or `await validate_topology()` (async) after `connect_cosmos()` or `create_memory_store()` to verify that `memories`, `memories_turns`, and `memories_summaries` all exist and are readable. The method raises `RuntimeError` on the first container that is missing (the message says to redeploy) or unreadable. +Use `validate_topology()` (sync) or `await validate_topology()` (async) after `connect_cosmos()` or `create_memory_store()` to verify that `memories`, `memories_turns`, `memories_summaries` and `counter` all exist, are readable, and are keyed `[/tenant_id, /user_id]`. The method raises `RuntimeError` on the first container that is missing (the message says to redeploy), unreadable, or keyed otherwise (the message says to recreate it, because a partition key cannot change in place). `create_memory_store()` makes the same key check itself, so the client constructor fails at once on a container created with the earlier `[/user_id, /thread_id]` key; `connect_cosmos()` does not, so call `validate_topology()` after it. ## Extension Points @@ -211,3 +213,5 @@ Concrete service classes: - Sync: `PipelineService` from `azure.cosmos.agent_memory.services.pipeline`. - Async: `AsyncPipelineService` from `azure.cosmos.agent_memory.aio.services` (sub-module `pipeline`). The async pipeline is a fully-native asyncio implementation - not an `asyncio.to_thread` shim over the sync pipeline. - Threshold-driven auto-trigger: `maybe_trigger_steps` from `azure.cosmos.agent_memory.auto_trigger` (sync) and `azure.cosmos.agent_memory.aio.auto_trigger` (async). + +`MemoryStore`, `AsyncMemoryStore`, `PipelineService` and `AsyncPipelineService` take the same `tenant_id` argument as the clients (default `"default"`). A store stamps it on every record it writes and refuses a record that names another tenant; a pipeline keys its own reads and writes with it. Give a store and the pipeline that uses it the same value. diff --git a/Docs/troubleshooting.md b/Docs/troubleshooting.md index 5d5abcd..dab451f 100644 --- a/Docs/troubleshooting.md +++ b/Docs/troubleshooting.md @@ -13,6 +13,8 @@ Use this guide when local memory works but Cosmos DB, embeddings, Durable Functi | Cosmos 401 or 403 | Run `az login` and confirm Cosmos DB data-plane RBAC is assigned. | | Cosmos operations fail before connecting | Call `create_memory_store()` or `connect_cosmos()` before cloud operations. | | Search returns no vector results | Confirm embeddings are generated and `AI_FOUNDRY_EMBEDDING_DIMENSIONS` matches the container vector policy. | +| A client does not find memories another client wrote | A client reads and writes only its own tenant. Check that both use the same `tenant_id` (default `"default"`). See section 3. | +| Reads, updates and deletes find nothing after upgrading | The containers were created with the earlier `[/user_id, /thread_id]` key and must be recreated, `leases` included. See section 3. | | A fact, procedure or preference is missing from search results | It may be retired (`superseded_by` is set; pass `include_superseded=True`) or, for a procedure, still a `candidate` or past `valid_until`. See section 4. | | Conflicting facts show no `conflicts_with` | Search with `user_id` after a reconcile pass has run; only pairs that pass compared are linked. See section 4. | | A stored memory contains `[REDACTED-SECRET]` | The write guard replaced a credential it recognized and tagged the record `sys:secret`; the credential itself is not written to Cosmos DB. See [Secrets](design_patterns.md#11-secrets-and-deleting-memories). | @@ -99,10 +101,14 @@ Run `create_memory_store()` before relying on cloud operations. It creates the d The memories container is created with: -- hierarchical partition key on `user_id` and `thread_id` +- hierarchical partition key on `tenant_id` and `user_id` (`memories_turns`, `memories_summaries` and `counter` use the same key; `leases` uses `/id`) - vector index on `/embedding` - full-text index on `/content` +A client is bound to one tenant (`tenant_id`, default `"default"`) and reads and writes only inside it, so memories written under another tenant are not visible to it. `client.tenant_id` shows the value in use. + +A container's partition key is fixed when it is created, and `create_memory_store()` leaves an existing container as it is, but it refuses one that is not keyed `[/tenant_id, /user_id]` with `container 'memories' has partition key ['/user_id', '/thread_id'] but this SDK requires ['/tenant_id', '/user_id']`. Containers created by an earlier version are keyed `[/user_id, /thread_id]`: they take writes, but the current client's reads, updates and deletes by owner do not find the records. Delete and recreate `memories`, `memories_turns`, `memories_summaries`, `counter` and `leases`, so the change feed starts clean on the recreated turns container (`create_memory_store()` creates them, the first four with the new key); existing data is not migrated. After `connect_cosmos()`, which does not check, `validate_topology()` makes the same check. + If vector or full-text search fails after changing dimensions or indexing settings, create a fresh container with the desired configuration. Cosmos container vector policies are creation-time infrastructure choices. Pass `cosmos_throughput_mode="serverless"` (the default) when creating the client. Use `cosmos_throughput_mode="autoscale"` with `cosmos_autoscale_max_ru` when you need provisioned autoscale throughput. @@ -122,7 +128,7 @@ Search always uses hybrid vector/full-text ranking when keyword extraction finds If search returns documents but scores look poor, check that records have an `embedding` field and that the query uses similar language to the stored memory content. -Keyword searches read across partitions. The Python SDK skips query planning for a query sent with a partition key, so `FullTextScore` ranking is ignored ([Azure/azure-sdk-for-python#42241](https://github.com/Azure/azure-sdk-for-python/issues/42241)); a keyword query therefore filters on `c.user_id` (and `c.thread_id`, when given) in the `WHERE` clause instead and sets `full_text_score_scope="Local"`. Results stay confined to the same user and thread (in `search_cosmos`, episodic and procedural memories match on the user alone), but a large container costs more RUs than a single-partition read. A vector-only query with both `user_id` and `thread_id` still reads one partition, except a `search_cosmos` that searches episodic or procedural memories, which always runs across partitions. If a custom query sent with a partition key raises a `ValidationError` that mentions `FullTextScore`, drop the partition key and filter on the partition key fields in the `WHERE` clause. +Keyword searches read across partitions. The Python SDK skips query planning for a query sent with a partition key, so `FullTextScore` ranking is ignored ([Azure/azure-sdk-for-python#42241](https://github.com/Azure/azure-sdk-for-python/issues/42241)); a keyword query therefore filters on `c.tenant_id`, `c.user_id` (and `c.thread_id`, when given) in the `WHERE` clause instead and sets `full_text_score_scope="Local"`. Results stay confined to the client's tenant and the same owner (in `search_cosmos`, episodic and procedural memories match on the owner alone), but a large container costs more RUs than a single-partition read. A vector-only query with a `user_id` still reads one partition, whatever the `thread_id`. If a custom query sent with a partition key raises a `ValidationError` that mentions `FullTextScore`, drop the partition key and filter on `c.tenant_id` and `c.user_id` in the `WHERE` clause. Search hides some records on purpose: @@ -202,6 +208,7 @@ If nothing fires: - confirm the `memories`, `memories_turns` and `memories_summaries` containers exist; a missing one fails the batch with `Topology error: container '' does not exist` - confirm the `counter` container is writable - confirm `MEMORY_PROCESSOR_OWNER=durable` is set on the Function App +- check the Function App log for warnings about skipped turns: a turn needs a valid `tenant_id`, which the SDK stamps on every record it writes, and the trigger skips one without it - insert enough new turn documents to cross the configured threshold - check for generated documents where the Cosmos JSON field is `type="thread_summary"`, `type="fact"`, or `type="user_summary"` diff --git a/README.md b/README.md index 73bc571..f85e83e 100644 --- a/README.md +++ b/README.md @@ -139,7 +139,7 @@ See [`Samples/`](Samples/) for end-to-end scenarios (chat memory, RAG, multi-age | **Reconcile** | Fold duplicate facts, combine facts about one thing, link conflicting facts | `reconcile(...)` | | **Process now** | Run the full pipeline (summary → facts → reconcile → procedures → user profile) | `process_now(...)` | -AgentMemoryToolkit uses 3-container Cosmos topology, all partitioned by hierarchical `(user_id, thread_id)` keys: +AgentMemoryToolkit uses 3-container Cosmos topology, all partitioned by the hierarchical key `[tenant_id, user_id]`: | Container | Holds | Notes | |----------------------|--------------------------------------------|-----------------------------------------------------------------------| @@ -147,7 +147,9 @@ AgentMemoryToolkit uses 3-container Cosmos topology, all partitioned by hierarch | `memories` | `fact`, `episodic`, `procedural` documents | vector + full-text retrieval path | | `memories_summaries` | thread and user summaries | latest-summary point reads; vector + full-text for `search_summaries` | -`create_memory_store()` also creates a `counter` container (the turn counters behind the auto-trigger) and a `leases` container (change feed checkpoints). +`tenant_id` says whose memories these are (an app, a customer, an environment); a client is bound to one tenant through its `tenant_id` argument, `"default"` unless you set it. `user_id` is the owner of a memory, a user or an agent. `thread_id` is a plain field, so everything one owner knows sits in one partition. See [Tenants and Owners](Docs/concepts.md#tenants-and-owners). + +`create_memory_store()` also creates a `counter` container (the turn counters behind the auto-trigger, with the same key) and a `leases` container (change feed checkpoints, keyed `/id`). ### Memory Type Taxonomy @@ -351,8 +353,8 @@ Async equivalents (`AsyncInProcessProcessor`, `AsyncDurableFunctionProcessor`) l ## Documentation -- **[Docs/concepts.md](Docs/concepts.md)** - Memory types, threads, roles, embeddings, search slots, conflicting facts, processing pipeline, secret redaction, reconciliation, change feed processing -- **[Docs/design_patterns.md](Docs/design_patterns.md)** - Integration patterns for chat apps and multi-agent systems, including procedures, reconciliation and secrets +- **[Docs/concepts.md](Docs/concepts.md)** - Memory types, tenants and owners (the partition key), threads, roles, embeddings, search slots, conflicting facts, processing pipeline, secret redaction, reconciliation, change feed processing +- **[Docs/design_patterns.md](Docs/design_patterns.md)** - Integration patterns for chat apps and multi-agent systems, including procedures, reconciliation, secrets, tenants and agent-owned memory - **[Docs/public_api.md](Docs/public_api.md)** - Client methods and options, fact and procedure fields, secret redaction - **[Docs/operations.md](Docs/operations.md)** - TTLs and runtime settings (thresholds, reconcile, procedures, extraction prompt) - **[Docs/local_testing.md](Docs/local_testing.md)** - Prerequisites, environment setup, running locally, debugging @@ -381,6 +383,7 @@ tests/ Unit + integration tests (pytest) ## Migration notes +- **Memories are keyed `[tenant_id, user_id]`, with no migration.** `memories`, `memories_turns`, `memories_summaries` and `counter` were keyed `[user_id, thread_id]`. A partition key cannot change in place, so recreate those containers and `leases`, so the change feed starts clean on the recreated turns container (`create_memory_store()` creates them with the new key, and for `azd` deployments see [`infra/README.md`](infra/README.md)). Existing data is not migrated, and `create_memory_store()` refuses a container that still has the earlier key rather than let it take writes and read back empty. A `user_id` must now be a non-empty string of at most 256 UTF-8 bytes without `/`, `\`, `?`, `#` or control characters. `thread_id` is no longer an argument of `update_cosmos()`, `delete_memory()`, `delete_turn()`, `add_tags()`, `remove_tags()` and `get_memory_history()`, and `MemoryNotFoundError` no longer carries it. Clients take an optional `tenant_id` (default `"default"`). See [CHANGELOG.md](CHANGELOG.md). - **`azure.cosmos.agent_memory.processing.ProcessingClient` is removed.** Drop the import and call `client.process_now()` (or `client.process_now_and_wait()`) instead. Same for the async `AsyncProcessingClient`. - **New `processor=` kwarg.** Defaults to `InProcessProcessor()` - existing code keeps its current behavior with no edits. - **`adf_endpoint` / `adf_key` constructor kwargs are gone.** The SDK no longer makes HTTP calls to the Function app at runtime; the Function app reads from the Cosmos change feed. diff --git a/Samples/Advanced/advanced_memory_lifecycle.py b/Samples/Advanced/advanced_memory_lifecycle.py index 9fdedd2..5c976b0 100644 --- a/Samples/Advanced/advanced_memory_lifecycle.py +++ b/Samples/Advanced/advanced_memory_lifecycle.py @@ -93,7 +93,7 @@ def main() -> None: _header(5, "Archive: delete raw turns, keep derived memories") deleted = 0 for m in mem.get_thread(thread_id=thread_id, user_id=user_id): - mem.delete_memory(memory_id=m["id"], user_id=user_id, thread_id=thread_id, memory_type="turn") + mem.delete_memory(memory_id=m["id"], user_id=user_id, memory_type="turn") deleted += 1 print(f" deleted {deleted} raw turn(s)") diff --git a/Samples/Notebooks/Demo.ipynb b/Samples/Notebooks/Demo.ipynb index 9940edb..76ae258 100644 --- a/Samples/Notebooks/Demo.ipynb +++ b/Samples/Notebooks/Demo.ipynb @@ -627,7 +627,6 @@ "memory.update_cosmos(\n", " memory_id=target[\"id\"],\n", " user_id=target[\"user_id\"],\n", - " thread_id=target[\"thread_id\"],\n", " memory_type=target[\"type\"],\n", " content=\"Something near Pike Place Market would be great. Keep flights under $300 round trip and hotels under $200/night.\",\n", " metadata={\"edited\": True, \"reason\": \"user clarified hotel budget\"},\n", @@ -662,7 +661,6 @@ " memory.delete_memory(\n", " tool_mems[0][\"id\"],\n", " user_id=tool_mems[0][\"user_id\"],\n", - " thread_id=tool_mems[0][\"thread_id\"],\n", " memory_type=tool_mems[0][\"type\"],\n", " )\n", " print(f\"Deleted tool memory {tool_mems[0]['id'][:8]}...\")\n", diff --git a/Samples/Notebooks/Demo_async.ipynb b/Samples/Notebooks/Demo_async.ipynb index 5e7da94..d69c302 100644 --- a/Samples/Notebooks/Demo_async.ipynb +++ b/Samples/Notebooks/Demo_async.ipynb @@ -594,7 +594,6 @@ "await memory.update_cosmos(\n", " memory_id=target[\"id\"],\n", " user_id=target[\"user_id\"],\n", - " thread_id=target[\"thread_id\"],\n", " memory_type=target[\"type\"],\n", " content=\"Something near Pike Place Market would be great. Keep flights under $300 round trip and hotels under $200/night.\",\n", " metadata={\"edited\": True, \"reason\": \"user clarified hotel budget\"},\n", @@ -629,7 +628,6 @@ " await memory.delete_memory(\n", " tool_mems[0][\"id\"],\n", " user_id=tool_mems[0][\"user_id\"],\n", - " thread_id=tool_mems[0][\"thread_id\"],\n", " memory_type=tool_mems[0][\"type\"],\n", " )\n", " print(f\"Deleted tool memory {tool_mems[0]['id'][:8]}...\")\n", diff --git a/Samples/Processing/processing_episodic_memory.py b/Samples/Processing/processing_episodic_memory.py index 9314a07..5095bbd 100644 --- a/Samples/Processing/processing_episodic_memory.py +++ b/Samples/Processing/processing_episodic_memory.py @@ -231,7 +231,6 @@ def main() -> None: mem.delete_memory( memory_id=memory_id, user_id=user_id, - thread_id=record.get("thread_id", thread_id), memory_type=record["type"], ) deleted += 1 diff --git a/Samples/Processing/processing_procedural_memory.py b/Samples/Processing/processing_procedural_memory.py index fc054dd..781897b 100644 --- a/Samples/Processing/processing_procedural_memory.py +++ b/Samples/Processing/processing_procedural_memory.py @@ -327,7 +327,6 @@ def main() -> None: mem.delete_memory( memory_id=memory_id, user_id=user_id, - thread_id=record.get("thread_id") or debug_thread_id, memory_type=record_type, ) deleted += 1 diff --git a/Samples/Quickstarts/quickstart_cosmos.py b/Samples/Quickstarts/quickstart_cosmos.py index 3a26f0b..1fe59ee 100644 --- a/Samples/Quickstarts/quickstart_cosmos.py +++ b/Samples/Quickstarts/quickstart_cosmos.py @@ -29,6 +29,7 @@ def main() -> None: embedding_deployment_name=os.environ.get("AI_FOUNDRY_EMBEDDING_DEPLOYMENT_NAME", "text-embedding-3-large"), chat_deployment_name=os.environ.get("AI_FOUNDRY_CHAT_DEPLOYMENT_NAME", "gpt-4o-mini"), use_default_credential=True, + # tenant_id="acme", # optional: keeps apps or customers that share the containers apart (default "default") ) # Connect to an existing Cosmos DB container @@ -49,7 +50,6 @@ def main() -> None: mem.update_cosmos( memory_id=memory_id, user_id="u1", - thread_id="t1", memory_type="turn", content="Updated via quickstart", ) @@ -61,7 +61,7 @@ def main() -> None: print("Pushed local memories to Cosmos") # Clean up – delete the memory we updated - mem.delete_memory(memory_id=memory_id, user_id="u1", thread_id="t1", memory_type="turn") + mem.delete_memory(memory_id=memory_id, user_id="u1", memory_type="turn") print(f"Deleted memory {memory_id}") print("\nQuickstart complete!") diff --git a/Samples/Scenarios/scenario_counter_tuning.py b/Samples/Scenarios/scenario_counter_tuning.py index b99f715..b1f547a 100644 --- a/Samples/Scenarios/scenario_counter_tuning.py +++ b/Samples/Scenarios/scenario_counter_tuning.py @@ -3,7 +3,7 @@ This sample demonstrates the *operational* surface of the :class:`DurableFunctionProcessor` deployment: the SDK never invokes an LLM locally - instead, the sibling Azure Function app reads the Cosmos change -feed and decides which orchestrator(s) to fire based on per-(user,thread) +feed and decides which orchestrator(s) to fire based on per-(tenant,user,thread) counters. The orchestrators run independently, each gated on its own threshold: diff --git a/Samples/Scenarios/scenario_memory_reconciliation.py b/Samples/Scenarios/scenario_memory_reconciliation.py index 3461568..c767850 100644 --- a/Samples/Scenarios/scenario_memory_reconciliation.py +++ b/Samples/Scenarios/scenario_memory_reconciliation.py @@ -198,7 +198,6 @@ def main() -> None: mem.delete_memory( memory_id=rec["id"], user_id=unique_user_id, - thread_id=rec.get("thread_id", unique_thread_id), memory_type=rec["type"], ) deleted += 1 diff --git a/Samples/Scenarios/scenario_rag_with_memory.py b/Samples/Scenarios/scenario_rag_with_memory.py index 633454a..bf3ef7e 100644 --- a/Samples/Scenarios/scenario_rag_with_memory.py +++ b/Samples/Scenarios/scenario_rag_with_memory.py @@ -260,7 +260,6 @@ def run_demo() -> None: mem.delete_memory( memory_id=item["id"], user_id=user_id, - thread_id=item.get("thread_id", thread_id), memory_type="turn", ) stored = mem.get_memories(user_id=user_id, thread_id=thread_id) @@ -268,7 +267,6 @@ def run_demo() -> None: mem.delete_memory( memory_id=item["id"], user_id=user_id, - thread_id=item.get("thread_id", thread_id), memory_type=item["type"], ) print(f" Deleted {len(turns) + len(stored)} seeded memories.") diff --git a/azure/cosmos/agent_memory/_base/base_client.py b/azure/cosmos/agent_memory/_base/base_client.py index 7504a5b..c7a2123 100644 --- a/azure/cosmos/agent_memory/_base/base_client.py +++ b/azure/cosmos/agent_memory/_base/base_client.py @@ -8,6 +8,7 @@ from typing import Any, Optional from azure.cosmos.agent_memory._container_routing import ContainerKey +from azure.cosmos.agent_memory._partitioning import resolve_tenant_id from azure.cosmos.agent_memory._utils import ( VALID_ROLES, VALID_TYPES, @@ -54,9 +55,11 @@ def _init_base_config( user_agent: Optional[str] = None, default_credential_module: str = "azure.identity", cosmos_preferred_locations: Optional[str | Iterable[str]] = None, + tenant_id: Optional[str] = None, ) -> None: """Initialize shared local state, config values, and default credentials.""" configure_logging() + self._tenant_id = resolve_tenant_id(tenant_id) self.local_memory: list[dict[str, Any]] = [] self._unflushed_turn_counts: dict[tuple[str, str], int] = {} self._warned_owner_skip: bool = False @@ -117,6 +120,11 @@ def _init_base_config( self._counter_container_client: Any = None self._store: Any = None + @property + def tenant_id(self) -> str: + """The tenant this client is bound to: every record it reads or writes belongs to it.""" + return self._tenant_id + @property def _containers(self) -> dict[ContainerKey, Any]: return { diff --git a/azure/cosmos/agent_memory/_container_routing.py b/azure/cosmos/agent_memory/_container_routing.py index 80428e9..2118b71 100644 --- a/azure/cosmos/agent_memory/_container_routing.py +++ b/azure/cosmos/agent_memory/_container_routing.py @@ -2,7 +2,8 @@ Single source of truth for which Cosmos DB container holds which memory document type. ``Docs/concepts.md`` ("Required containers") describes the -layout. +layout. Every container is keyed ``[/tenant_id, /user_id]`` (see +``_partitioning``), so a thread is a field of a record, not a partition. Default container names (each can be changed on the client): diff --git a/azure/cosmos/agent_memory/_counters.py b/azure/cosmos/agent_memory/_counters.py index 22d5bd8..a4456a0 100644 --- a/azure/cosmos/agent_memory/_counters.py +++ b/azure/cosmos/agent_memory/_counters.py @@ -4,17 +4,17 @@ uses the same counter container and document shape, so InProcess and Durable backends can be swapped without losing per-thread / per-user counts. -Counter document shape:: +Counter documents live in the owner's partition, PK = [tenant_id, user_id]:: - # thread-scoped - id = "thread:{user_id}:{thread_id}", PK = [user_id, thread_id] - { "id": ..., "user_id": ..., "thread_id": ..., "count": int, + # thread-scoped - id = "thread:{user_id}:{thread_id}" + { "id": ..., "tenant_id": ..., "user_id": ..., "thread_id": ..., "count": int, "created_at": str, "updated_at": str, "last_batch_lsn": int|None, "last_batch_old_count": int, "last_extract_count": int, # only once the Function App has extracted "last_failure_at": str|None, "last_failure_reason": str|None, "last_owner": str|None } - # user-scoped - id = "user:{user_id}", PK = [user_id, "__counters__"] + # user-scoped - id = "user:{user_id}", thread_id = "__counters__" { ... same fields, without "last_extract_count" ... } The counter container's default TTL (``COUNTER_TTL_SECONDS``) expires a counter 90 days after its @@ -39,6 +39,7 @@ from azure.core import MatchConditions from azure.cosmos.exceptions import CosmosHttpResponseError, CosmosResourceNotFoundError +from azure.cosmos.agent_memory._partitioning import partition_key_for from azure.cosmos.agent_memory.logging import describe_exception, get_logger logger = get_logger(__name__) @@ -107,6 +108,7 @@ def _maybe_warn_owner_mismatch(counter_id: str, existing_owner: Optional[str], o def increment_counter_sync( container: Any, + tenant_id: str, counter_id: str, user_id: str, thread_id: str, @@ -116,6 +118,9 @@ def increment_counter_sync( ) -> tuple[int, int]: """Atomically increment ``counter_id`` by *count* and return ``(old, new)``. + The counter lives in the ``[tenant_id, user_id]`` partition; *thread_id* is a plain field of + the document (``"__counters__"`` for the user-scoped counter). + Uses ETag-based optimistic concurrency, retrying up to ``MAX_RETRIES`` times on HTTP 412. Uses ``create_item`` for the first-write path, retrying on HTTP 409 in case multiple SDK clients raced to seed the @@ -129,7 +134,7 @@ def increment_counter_sync( Returns ``(0, 0)`` and logs a warning if the increment fails (the container is unreachable, or every retry conflicted) - auto-trigger failures must never block the user's primary write path. """ - partition_key = [user_id, thread_id] + partition_key = partition_key_for(tenant_id, user_id) for attempt in range(MAX_RETRIES): old_count = 0 @@ -148,6 +153,7 @@ def increment_counter_sync( new_count = old_count + count new_doc = _build_counter_doc( counter_id=counter_id, + tenant_id=tenant_id, user_id=user_id, thread_id=thread_id, new_count=new_count, @@ -186,6 +192,7 @@ def increment_counter_sync( async def increment_counter_async( container: Any, + tenant_id: str, counter_id: str, user_id: str, thread_id: str, @@ -194,7 +201,7 @@ async def increment_counter_async( owner: Optional[str] = None, ) -> tuple[int, int]: """Async version of :func:`increment_counter_sync`.""" - partition_key = [user_id, thread_id] + partition_key = partition_key_for(tenant_id, user_id) for attempt in range(MAX_RETRIES): old_count = 0 @@ -213,6 +220,7 @@ async def increment_counter_async( new_count = old_count + count new_doc = _build_counter_doc( counter_id=counter_id, + tenant_id=tenant_id, user_id=user_id, thread_id=thread_id, new_count=new_count, @@ -252,6 +260,7 @@ async def increment_counter_async( def _build_counter_doc( *, counter_id: str, + tenant_id: str, user_id: str, thread_id: str, new_count: int, @@ -263,6 +272,7 @@ def _build_counter_doc( now = _utc_now_iso() doc: dict[str, Any] = { "id": counter_id, + "tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id, "count": new_count, @@ -305,9 +315,9 @@ def _build_counter_doc( def stamp_failure_sync( container: Any, + tenant_id: str, counter_id: str, user_id: str, - thread_id: str, reason: str, ) -> None: """Best-effort stamp ``last_failure_at`` / ``last_failure_reason`` on the counter doc. @@ -318,7 +328,7 @@ def stamp_failure_sync( the user's write path. ``reason`` is stored as given, so it must describe the failure (``describe_exception``), never quote an exception's text. """ - partition_key = [user_id, thread_id] + partition_key = partition_key_for(tenant_id, user_id) patch_ops = [ {"op": "add", "path": "/last_failure_at", "value": _utc_now_iso()}, {"op": "add", "path": "/last_failure_reason", "value": (reason or "")[:500]}, @@ -335,13 +345,13 @@ def stamp_failure_sync( async def stamp_failure_async( container: Any, + tenant_id: str, counter_id: str, user_id: str, - thread_id: str, reason: str, ) -> None: """Async version of :func:`stamp_failure_sync`.""" - partition_key = [user_id, thread_id] + partition_key = partition_key_for(tenant_id, user_id) patch_ops = [ {"op": "add", "path": "/last_failure_at", "value": _utc_now_iso()}, {"op": "add", "path": "/last_failure_reason", "value": (reason or "")[:500]}, diff --git a/azure/cosmos/agent_memory/_partitioning.py b/azure/cosmos/agent_memory/_partitioning.py new file mode 100644 index 0000000..0873546 --- /dev/null +++ b/azure/cosmos/agent_memory/_partitioning.py @@ -0,0 +1,115 @@ +"""How records are keyed in Cosmos DB. + +Every record lives in the logical partition ``[tenant_id, user_id]``. ``tenant_id`` says whose memories these are (an +application, a customer, an environment), and ``user_id`` is the owner of the memory: a user or an agent. ``thread_id`` +is a plain field of the record, not part of the key, so everything one owner knows (turns, facts, episodes, procedures, +summaries, counters) sits in one partition, and a query that names the owner reads that partition only. + +A client is bound to one tenant (its ``tenant_id`` argument, ``"default"`` when not given), and every read and write +it makes stays inside it. A filter on ``user_id`` alone would read the same id in every tenant, so every query also +filters on ``c.tenant_id``: build the filter with :data:`OWNER_FILTER` and :func:`owner_parameters`. + +A record id is unique within its partition, that is, per owner across all of the owner's threads. +""" + +from __future__ import annotations + +from typing import Any, Mapping, Optional + +from azure.cosmos.agent_memory.exceptions import ValidationError + +DEFAULT_TENANT_ID = "default" + +# The partition key every keyed container is created with, and the one :func:`partition_key_problem` expects. +PARTITION_KEY_PATHS = ["/tenant_id", "/user_id"] + +# Ids appear in Cosmos document ids and orchestration instance ids, which cannot hold these characters. +_UNSUPPORTED_CHARACTERS = "/\\?#" +MAX_TENANT_ID_BYTES = 256 +MAX_OWNER_ID_BYTES = 256 + +TENANT_FILTER = "c.tenant_id = @tenant_id" +OWNER_FILTER = "c.tenant_id = @tenant_id AND c.user_id = @user_id" + + +def _checked_identifier(value: Any, name: str, max_bytes: int) -> str: + if not isinstance(value, str) or not value.strip(): + raise ValidationError(f"{name} must be a non-empty string") + if any(character in value for character in _UNSUPPORTED_CHARACTERS) or any( + ord(character) < 32 for character in value + ): + raise ValidationError(f"{name} contains characters the memory store does not support: / \\ ? # or control") + if len(value.encode("utf-8")) > max_bytes: + raise ValidationError(f"{name} must not exceed {max_bytes} UTF-8 bytes") + return value + + +def resolve_tenant_id(tenant_id: Optional[str] = None) -> str: + """The tenant to use: ``DEFAULT_TENANT_ID`` when ``tenant_id`` is ``None``, else ``tenant_id`` if it is valid. + + A valid tenant id is a non-empty string of at most ``MAX_TENANT_ID_BYTES`` UTF-8 bytes without ``/``, ``\\``, ``?``, + ``#`` or control characters. Anything else raises :class:`ValidationError`. + """ + if tenant_id is None: + return DEFAULT_TENANT_ID + return _checked_identifier(tenant_id, "tenant_id", MAX_TENANT_ID_BYTES) + + +def validate_owner_id(user_id: Any) -> str: + """``user_id`` if it is a valid owner id, else :class:`ValidationError`. + + An owner id follows the rules of a tenant id: a non-empty string of at most ``MAX_OWNER_ID_BYTES`` UTF-8 bytes + without ``/``, ``\\``, ``?``, ``#`` or control characters. It is part of the partition key and of the ids of the + records the toolkit builds for the owner, so a value outside the rules would fail later or share a partition by + accident. + """ + return _checked_identifier(user_id, "user_id", MAX_OWNER_ID_BYTES) + + +def partition_key_for(tenant_id: str, user_id: str) -> list[str]: + """The full partition key of the records of ``user_id`` in ``tenant_id``.""" + return [tenant_id, validate_owner_id(user_id)] + + +def tenant_parameters(tenant_id: str) -> list[dict[str, Any]]: + """The query parameter for :data:`TENANT_FILTER`.""" + return [{"name": "@tenant_id", "value": tenant_id}] + + +def owner_parameters(tenant_id: str, user_id: str) -> list[dict[str, Any]]: + """The query parameters for :data:`OWNER_FILTER`.""" + return [{"name": "@tenant_id", "value": tenant_id}, {"name": "@user_id", "value": validate_owner_id(user_id)}] + + +def stamp_scope(doc: Mapping[str, Any], tenant_id: str) -> dict[str, Any]: + """A copy of ``doc`` that carries ``tenant_id``, refusing a record that has no valid owner or names another tenant. + + A client writes only into its own tenant. Cosmos stores a record in the partition its own ``tenant_id`` and + ``user_id`` name, so a record without a valid ``user_id`` would land where no owner-scoped read reaches it. + """ + validate_owner_id(doc.get("user_id")) + named = doc.get("tenant_id") + if named is not None and named != tenant_id: + raise ValidationError("record names a different tenant than the client it is written with") + stamped = dict(doc) + stamped["tenant_id"] = tenant_id + return stamped + + +def partition_key_problem(container_id: Any, properties: Any) -> Optional[str]: + """What is wrong with the partition key of a container, or ``None`` when it is :data:`PARTITION_KEY_PATHS`. + + ``properties`` is what ``ContainerProxy.read()`` returns. A partition key cannot change in place, and a container + keyed otherwise (for example ``[/user_id, /thread_id]``) accepts writes but is read back empty, so a mismatch is + reported up front. Anything that is not a mapping, such as a test double, is not checked. + """ + if not isinstance(properties, Mapping): + return None + actual = list((properties.get("partitionKey") or {}).get("paths") or []) + if actual == PARTITION_KEY_PATHS: + return None + return ( + f"container {container_id!r} has partition key {actual or 'none'} but this SDK requires {PARTITION_KEY_PATHS}. " + "A partition key cannot be changed in place: recreate the container, and the leases container with it, " + "because existing data is not migrated" + ) diff --git a/azure/cosmos/agent_memory/_query_builder.py b/azure/cosmos/agent_memory/_query_builder.py index 19da32d..e0e5741 100644 --- a/azure/cosmos/agent_memory/_query_builder.py +++ b/azure/cosmos/agent_memory/_query_builder.py @@ -8,23 +8,38 @@ from typing import Any +from azure.cosmos.agent_memory._partitioning import OWNER_FILTER, TENANT_FILTER, owner_parameters, tenant_parameters + class _QueryBuilder: """Accumulates optional WHERE conditions and their parameterized values. Usage:: - qb = _QueryBuilder() - qb.add_filter("c.user_id", "@user_id", some_user_id) + qb = _QueryBuilder.for_tenant(tenant_id, user_id) qb.add_filter("c.role", "@role", some_role) - where = qb.build_where() # " WHERE c.user_id = @user_id AND c.role = @role" - params = qb.get_parameters() # [{"name": "@user_id", "value": ...}, ...] + where = qb.build_where() # " WHERE c.tenant_id = @tenant_id AND c.user_id = @user_id AND c.role = @role" + params = qb.get_parameters() # [{"name": "@tenant_id", "value": ...}, ...] """ def __init__(self) -> None: self._conditions: list[str] = [] self._parameters: list[dict[str, Any]] = [] + @classmethod + def for_tenant(cls, tenant_id: str, user_id: str | None = None) -> _QueryBuilder: + """A builder that starts with the tenant filter, and the owner's when ``user_id`` is given. + + A filter on ``user_id`` alone would read the same id in every tenant, so every query that reads records starts + from here. + """ + qb = cls() + if user_id is None: + qb.add_condition(TENANT_FILTER, tenant_parameters(tenant_id)) + else: + qb.add_condition(OWNER_FILTER, owner_parameters(tenant_id, user_id)) + return qb + def add_condition(self, condition: str, parameters: list[dict[str, Any]] | None = None) -> None: """Add a pre-built parameterized condition.""" if not condition: diff --git a/azure/cosmos/agent_memory/_utils.py b/azure/cosmos/agent_memory/_utils.py index 2fa252f..716abf7 100644 --- a/azure/cosmos/agent_memory/_utils.py +++ b/azure/cosmos/agent_memory/_utils.py @@ -509,6 +509,7 @@ def _validate_connection( def _build_memory_query_builder( *, + tenant_id: str, memory_id: Optional[str] = None, user_id: Optional[str] = None, thread_id: Optional[str] = None, @@ -518,12 +519,11 @@ def _build_memory_query_builder( ) -> _QueryBuilder: """Return a :class:`_QueryBuilder` pre-loaded with the standard filters. - ``memory_types`` is a list of types (e.g. ``["fact", "procedural", - "episodic"]``); when ``None`` or empty no type filter is applied. + The query is confined to ``tenant_id``, and to the owner's records when ``user_id`` is given. ``memory_types`` is + a list of types (e.g. ``["fact", "procedural", "episodic"]``); when ``None`` or empty no type filter is applied. """ - qb = _QueryBuilder() + qb = _QueryBuilder.for_tenant(tenant_id, user_id) qb.add_filter("c.id", "@memory_id", memory_id) - qb.add_filter("c.user_id", "@user_id", user_id) in_scope_user_types = _resolve_user_scoped_types_in_query(memory_types) if thread_id is not None and in_scope_user_types: qb.add_thread_id_or_user_scoped(thread_id, "@thread_id", sorted(in_scope_user_types)) diff --git a/azure/cosmos/agent_memory/aio/auto_trigger.py b/azure/cosmos/agent_memory/aio/auto_trigger.py index 6a103aa..59ee848 100644 --- a/azure/cosmos/agent_memory/aio/auto_trigger.py +++ b/azure/cosmos/agent_memory/aio/auto_trigger.py @@ -46,6 +46,7 @@ def _should_trigger(processor: Any, thresholds: Any) -> bool: async def maybe_trigger_steps( processor: Any, counter_container: Any, + tenant_id: str, turn_counts: dict[tuple[str, str], int], *, thresholds: Any = default_thresholds, @@ -68,6 +69,7 @@ async def maybe_trigger_steps( user_batch_counts = await _trigger_thread_steps( processor, counter_container, + tenant_id, turn_counts, n_facts=n_facts, n_summary=n_summary, @@ -75,12 +77,13 @@ async def maybe_trigger_steps( n_dedup_turns=n_dedup_turns, thresholds=thresholds, ) - await _trigger_user_steps(processor, counter_container, user_batch_counts, n_user=n_user) + await _trigger_user_steps(processor, counter_container, tenant_id, user_batch_counts, n_user=n_user) async def _trigger_thread_steps( processor: AsyncInProcessProcessor, counter_container: Any, + tenant_id: str, turn_counts: dict[tuple[str, str], int], *, n_facts: int, @@ -98,6 +101,7 @@ async def _trigger_thread_steps( try: old_count, new_count = await _counters.increment_counter_async( counter_container, + tenant_id, counter_id, user_id, thread_id, @@ -110,6 +114,7 @@ async def _trigger_thread_steps( await _fire_thread_steps( processor, counter_container, + tenant_id, counter_id, user_id, thread_id, @@ -126,6 +131,7 @@ async def _trigger_thread_steps( async def _fire_thread_steps( processor: AsyncInProcessProcessor, counter_container: Any, + tenant_id: str, counter_id: str, user_id: str, thread_id: str, @@ -154,7 +160,7 @@ async def _fire_thread_steps( "Async auto-trigger process_extract_memories failed for %s/%s: %s", user_id, thread_id, error ) await _counters.stamp_failure_async( - counter_container, counter_id, user_id, thread_id, f"process_extract_memories: {error}" + counter_container, tenant_id, counter_id, user_id, f"process_extract_memories: {error}" ) calls = ( ( @@ -190,12 +196,13 @@ async def _fire_thread_steps( except Exception as exc: error = describe_exception(exc) logger.warning("Async auto-trigger %s failed for %s/%s: %s", label, user_id, thread_id, error) - await _counters.stamp_failure_async(counter_container, counter_id, user_id, thread_id, f"{label}: {error}") + await _counters.stamp_failure_async(counter_container, tenant_id, counter_id, user_id, f"{label}: {error}") async def _trigger_user_steps( processor: AsyncInProcessProcessor, counter_container: Any, + tenant_id: str, user_batch_counts: dict[str, int], *, n_user: int, @@ -207,6 +214,7 @@ async def _trigger_user_steps( try: old_count, new_count = await _counters.increment_counter_async( counter_container, + tenant_id, counter_id, user_id, _counters.USER_COUNTER_THREAD_ID, @@ -225,9 +233,9 @@ async def _trigger_user_steps( logger.warning("Async auto-trigger process_user_summary failed for %s: %s", user_id, error) await _counters.stamp_failure_async( counter_container, + tenant_id, counter_id, user_id, - _counters.USER_COUNTER_THREAD_ID, f"process_user_summary: {error}", ) diff --git a/azure/cosmos/agent_memory/aio/cosmos_memory_client.py b/azure/cosmos/agent_memory/aio/cosmos_memory_client.py index 769ac32..7ea6e9e 100644 --- a/azure/cosmos/agent_memory/aio/cosmos_memory_client.py +++ b/azure/cosmos/agent_memory/aio/cosmos_memory_client.py @@ -10,6 +10,7 @@ from azure.cosmos.agent_memory._base import _BaseMemoryClient from azure.cosmos.agent_memory._base.base_client import is_transient_tail_step_error from azure.cosmos.agent_memory._container_routing import ContainerKey, container_key_for_type +from azure.cosmos.agent_memory._partitioning import PARTITION_KEY_PATHS, partition_key_problem from azure.cosmos.agent_memory._utils import ( _build_container_kwargs, _container_policies, @@ -29,6 +30,7 @@ from azure.cosmos.agent_memory.aio.services.pipeline import AsyncPipelineService from azure.cosmos.agent_memory.aio.store import AsyncMemoryStore from azure.cosmos.agent_memory.exceptions import ( + ConfigurationError, CosmosNotConnectedError, CosmosOperationError, MemoryNotFoundError, @@ -55,7 +57,11 @@ def _log_auto_trigger_task_failure(task: "asyncio.Task[Any]") -> None: class AsyncCosmosMemoryClient(_BaseMemoryClient): - """Async variant of :class:`azure.cosmos.agent_memory.CosmosMemoryClient`.""" + """Async variant of :class:`azure.cosmos.agent_memory.CosmosMemoryClient`. + + Like it, a client is bound to one tenant (``tenant_id``, ``"default"`` when not given): every record + it reads or writes belongs to it. + """ def __init__( self, @@ -85,6 +91,7 @@ def __init__( transcript_metadata_keys: Optional[Iterable[str]] = None, cadence_thresholds: Optional[Mapping[str, int]] = None, cosmos_preferred_locations: Optional[str | Iterable[str]] = None, + tenant_id: Optional[str] = None, ) -> None: self._init_base_config( cosmos_endpoint=cosmos_endpoint, @@ -109,6 +116,7 @@ def __init__( user_agent=user_agent, default_credential_module="azure.identity.aio", cosmos_preferred_locations=cosmos_preferred_locations, + tenant_id=tenant_id, ) self._background_tasks: set[asyncio.Task[Any]] = set() self._pipeline_init_error: Exception | None = None @@ -327,8 +335,9 @@ async def create_memory_store( user_agent=self._cosmos_user_agent, preferred_locations=self._cosmos_preferred_locations, ) + self._cosmos_client = client db = await client.create_database_if_not_exists(id=self._cosmos_database) - partition_key = PartitionKey(path=["/user_id", "/thread_id"], kind="MultiHash") + partition_key = PartitionKey(path=list(PARTITION_KEY_PATHS), kind="MultiHash") offer = _cosmos_container_offer_throughput( throughput_mode=self._cosmos_throughput_mode, autoscale_max_ru=self._cosmos_autoscale_max_ru, @@ -374,6 +383,7 @@ async def create_memory_store( ) summaries_idx_policy["compositeIndexes"] = [ [ + {"path": "/tenant_id", "order": "ascending"}, {"path": "/user_id", "order": "ascending"}, {"path": "/thread_id", "order": "ascending"}, {"path": "/version", "order": "descending"}, @@ -395,7 +405,7 @@ async def create_memory_store( self._cosmos_database, self._cosmos_summaries_container, ) - await db.create_container_if_not_exists( + counter_container = await db.create_container_if_not_exists( **_build_container_kwargs( container_id=self._cosmos_counter_container, partition_key=partition_key, @@ -403,6 +413,15 @@ async def create_memory_store( default_ttl=COUNTER_TTL_SECONDS, ) ) + # An existing container keeps the key it was created with, and one keyed differently takes writes + # but is read back empty, so it is refused here rather than later. + for keyed_container in ( + self._memories_container_client, + self._turns_container_client, + self._summaries_container_client, + counter_container, + ): + await self._require_partition_key(keyed_container) await db.create_container_if_not_exists( **_build_container_kwargs( container_id=self._cosmos_lease_container, @@ -410,18 +429,25 @@ async def create_memory_store( offer_throughput=offer, ) ) - self._cosmos_client = client self._init_services() except Exception as exc: + # The store cannot be used: close the client just opened and forget its containers. + try: + await self._drain_cosmos_client() + except Exception as close_exc: # noqa: BLE001 + logger.warning( + "Failed to close the Cosmos client after create_memory_store failed: %s", + describe_exception(close_exc), + ) raise CosmosOperationError(f"Failed to create memory store (async): {exc}") from exc logger.info("Async created memory store %s/%s", self._cosmos_database, self._cosmos_container) async def validate_topology(self) -> None: - """Verify all three Cosmos containers exist and are reachable. + """Verify the Cosmos containers exist, are reachable, and are keyed ``[/tenant_id, /user_id]``. - Reads container metadata for memories / memories_turns / memories_summaries. - Raises ``RuntimeError`` on the first failure with a clear message - instructing the customer to redeploy the infrastructure. + Reads container metadata for memories / memories_turns / memories_summaries and the counter container. + Raises ``RuntimeError`` on the first failure with a clear message: to redeploy the infrastructure when a + container is missing, or to recreate it when its partition key is not the one this SDK requires. Call this after ``connect_cosmos`` or ``create_memory_store`` to diagnose topology mismatches before any data is written. @@ -430,12 +456,16 @@ async def validate_topology(self) -> None: if self._memories_container_client is None: raise RuntimeError("validate_topology: Cosmos client is not connected; call connect_cosmos() first") - for key, client in self._containers.items(): + checks: list[tuple[str, Any]] = [(key.value, client) for key, client in self._containers.items()] + counter_client = self._get_counter_container() + if counter_client is not None: + checks.append((self._cosmos_counter_container, counter_client)) + for label, client in checks: if client is None: - raise RuntimeError(f"validate_topology: container for {key.value!r} is not connected") - container_id = getattr(client, "id", key.value) + raise RuntimeError(f"validate_topology: container for {label!r} is not connected") + container_id = getattr(client, "id", label) try: - await client.read() + properties = await client.read() except CosmosResourceNotFoundError as exc: raise RuntimeError( f"validate_topology: container {container_id!r} does not exist; " @@ -445,12 +475,22 @@ async def validate_topology(self) -> None: raise RuntimeError( f"validate_topology: cannot read container {container_id!r}: {type(exc).__name__}: {exc}" ) from exc + problem = partition_key_problem(container_id, properties) + if problem: + raise RuntimeError(f"validate_topology: {problem}") + + @staticmethod + async def _require_partition_key(container: Any) -> None: + problem = partition_key_problem(getattr(container, "id", None), await container.read()) + if problem: + raise ConfigurationError(problem) def _build_store(self) -> AsyncMemoryStore: return AsyncMemoryStore( containers=self._containers, embeddings_client=self._embeddings_client, enable_turn_embeddings=self._enable_turn_embeddings, + tenant_id=self._tenant_id, ) def _build_pipeline(self, store: AsyncMemoryStore) -> AsyncPipelineService: @@ -460,6 +500,7 @@ def _build_pipeline(self, store: AsyncMemoryStore) -> AsyncPipelineService: self._embeddings_client, containers=self._containers, transcript_metadata_keys=self._transcript_metadata_keys, + tenant_id=self._tenant_id, ) def _store_uses_current_clients(self) -> bool: @@ -569,6 +610,7 @@ async def _maybe_auto_trigger(self, turn_counts: dict[tuple[str, str], int]) -> await maybe_trigger_steps( self._get_processor(), self._get_counter_container(), + self._tenant_id, turn_counts, thresholds=self._cadence_thresholds, ) @@ -694,13 +736,12 @@ async def update_cosmos( memory_id: str, *, user_id: str, - thread_id: str, memory_type: str, content: Optional[str] = None, role: Optional[str] = None, metadata: Optional[dict[str, Any]] = None, ) -> None: - """Update a memory in Cosmos DB. + """Update a memory of ``user_id`` in Cosmos DB. Replaces ``content``, ``role`` and ``metadata`` where given, on the memory in the container that holds ``memory_type``, which must be its stored type. Literal credentials are redacted @@ -711,7 +752,6 @@ async def update_cosmos( return await self._get_store().update( memory_id, user_id=user_id, - thread_id=thread_id, memory_type=memory_type, content=content, role=role, @@ -723,10 +763,9 @@ async def delete_memory( memory_id: str, *, user_id: str, - thread_id: str, memory_type: str, ) -> None: - """Delete a memory from Cosmos DB. + """Delete a memory of ``user_id`` from Cosmos DB. Raises ``MemoryNotFoundError`` if it does not exist and ``MemoryTypeMismatchError`` if its stored type is not ``memory_type``. Deleting a fact or procedure first deletes the records @@ -737,16 +776,14 @@ async def delete_memory( return await self._get_store().delete( memory_id, user_id=user_id, - thread_id=thread_id, memory_type=memory_type, ) - async def delete_turn(self, turn_id: str, *, user_id: str, thread_id: str) -> None: - """Delete a single turn document. Raises if it does not exist.""" + async def delete_turn(self, turn_id: str, *, user_id: str) -> None: + """Delete a single turn document of ``user_id``. Raises if it does not exist.""" return await self.delete_memory( turn_id, user_id=user_id, - thread_id=thread_id, memory_type="turn", ) @@ -760,7 +797,6 @@ async def delete_thread_summary(self, user_id: str, thread_id: str) -> bool: await self.delete_memory( f"summary_{user_id}_{thread_id}", user_id=user_id, - thread_id=thread_id, memory_type="thread_summary", ) return True @@ -776,7 +812,6 @@ async def delete_user_summary(self, user_id: str) -> bool: await self.delete_memory( f"user_summary_{user_id}", user_id=user_id, - thread_id="__user_summary__", memory_type="user_summary", ) return True @@ -804,7 +839,7 @@ async def delete_thread(self, user_id: str, thread_id: str, *, include_summary: if not turn_id: continue try: - await self.delete_memory(turn_id, user_id=user_id, thread_id=thread_id, memory_type="turn") + await self.delete_memory(turn_id, user_id=user_id, memory_type="turn") deleted += 1 except MemoryNotFoundError: continue @@ -851,10 +886,10 @@ async def search_cosmos( block, deduped by content (best-effort; a blend fetch failure never breaks the base result). Blending, like the slots, needs ``user_id``. - ``thread_id`` limits facts to that thread; episodes and procedures stay user-wide. A keyword - (hybrid) query runs across partitions with ``c.user_id`` (and ``c.thread_id``, when given) - in the ``WHERE`` clause, because a partition key breaks full-text ranking (Azure SDK issue - #42241). Only a vector-only query with both ids over facts reads one partition. + ``thread_id`` limits facts to that thread; episodes and procedures stay user-wide. With ``user_id``, a + vector-only query reads that user's partition only. A keyword (hybrid) query runs across partitions with + the tenant and user filters in the ``WHERE`` clause, because a partition key breaks full-text ranking + (Azure SDK issue #42241). ``preference_slot`` and ``procedure_slot`` reserve result slots within ``top_k`` (see ``azure.cosmos.agent_memory._slots``): the user's best-matching preference fact @@ -986,11 +1021,10 @@ def _extend(docs: list[dict[str, Any]]) -> None: turns = [] _extend(turns) - async def query_memories(sql: str, parameters: Any, *, cross_partition: bool = False, **kwargs: Any) -> Any: - # The async store reads across partitions whenever no partition key is given. + async def query_memories(sql: str, parameters: Any, **kwargs: Any) -> Any: return await store.query(sql, parameters, container_key=ContainerKey.MEMORIES, **kwargs) - return await awith_conflicts(results, query_memories) + return await awith_conflicts(results, query_memories, self._tenant_id) async def _slot_candidates(self, store: Any, search_kwargs: dict[str, Any]) -> list[dict[str, Any]]: """Candidates for a result slot; a failed slot search leaves the slot to the ranked results.""" @@ -1046,11 +1080,10 @@ async def search_turns( Searches the turns container directly. Only vector-searchable when ``enable_turn_embeddings`` was set when the turns were written. ``user_id`` is required and always filters the results. Passing - ``thread_id`` as well restricts the results to that thread: a vector-only - query targets the thread's partition, while a keyword (hybrid) query runs - across partitions with ``user_id`` and ``thread_id`` filters in the WHERE - clause (a partition key breaks full-text ranking, Azure SDK issue #42241). - Omitting it fans out across the user's partitions. + ``thread_id`` as well restricts the results to that thread. A vector-only + query reads the user's partition; a keyword (hybrid) query runs across + partitions with the tenant, user and thread filters in the WHERE clause + (a partition key breaks full-text ranking, Azure SDK issue #42241). """ return await self._get_store().search_turns( search_terms=search_terms, @@ -1069,7 +1102,6 @@ async def get_memory_history( self, memory_id: str, user_id: str, - thread_id: Optional[str] = None, *, max_depth: int = 20, ) -> list[dict[str, Any]]: @@ -1087,7 +1119,6 @@ async def get_memory_history( return await self._get_store().get_memory_history( memory_id, user_id, - thread_id, max_depth=max_depth, ) @@ -1166,7 +1197,6 @@ async def add_tags( self, memory_id: str, user_id: str, - thread_id: str, memory_type: str, tags: list[str], ) -> None: @@ -1175,18 +1205,17 @@ async def add_tags( Tags are lower-cased. A tag that holds a literal credential is dropped, and the memory is marked ``sys:secret``. """ - return await self._get_store().add_tags(memory_id, user_id, thread_id, memory_type, tags) + return await self._get_store().add_tags(memory_id, user_id, memory_type, tags) async def remove_tags( self, memory_id: str, user_id: str, - thread_id: str, memory_type: str, tags: list[str], ) -> None: """Remove tags from an existing fact, episodic or procedural memory.""" - return await self._get_store().remove_tags(memory_id, user_id, thread_id, memory_type, tags) + return await self._get_store().remove_tags(memory_id, user_id, memory_type, tags) async def get_procedural_prompt(self, user_id: str) -> Optional[str]: """Return the user's standing instructions as a prompt block, or None when there are none. diff --git a/azure/cosmos/agent_memory/aio/processors/inprocess.py b/azure/cosmos/agent_memory/aio/processors/inprocess.py index ad90970..2fc36c6 100644 --- a/azure/cosmos/agent_memory/aio/processors/inprocess.py +++ b/azure/cosmos/agent_memory/aio/processors/inprocess.py @@ -10,6 +10,7 @@ import time from typing import Any, Optional +from azure.cosmos.agent_memory._partitioning import DEFAULT_TENANT_ID from azure.cosmos.agent_memory.processors.base import ( ProcessThreadResult, UserSummaryResult, @@ -17,7 +18,11 @@ class AsyncInProcessProcessor: - """Async in-process orchestrator over :class:`AsyncPipelineService`.""" + """Async in-process orchestrator over :class:`AsyncPipelineService`. + + Wraps an existing pipeline, or builds one from the supplied container / LLM / embeddings clients, + bound to ``tenant_id`` (``"default"`` when not given). + """ def __init__( self, @@ -28,6 +33,7 @@ def __init__( summaries_container: Any = None, chat_client: Any = None, embeddings_client: Any = None, + tenant_id: str = DEFAULT_TENANT_ID, ) -> None: if pipeline is None: if ( @@ -51,8 +57,10 @@ def __init__( ContainerKey.MEMORIES: cosmos_container, ContainerKey.SUMMARIES: summaries_container, } - store = AsyncMemoryStore(containers=containers, embeddings_client=embeddings_client) - pipeline = AsyncPipelineService(store, chat_client, embeddings_client, containers=containers) + store = AsyncMemoryStore(containers=containers, embeddings_client=embeddings_client, tenant_id=tenant_id) + pipeline = AsyncPipelineService( + store, chat_client, embeddings_client, containers=containers, tenant_id=tenant_id + ) self._pipeline = pipeline diff --git a/azure/cosmos/agent_memory/aio/services/pipeline.py b/azure/cosmos/agent_memory/aio/services/pipeline.py index f716f4e..f89b8ae 100644 --- a/azure/cosmos/agent_memory/aio/services/pipeline.py +++ b/azure/cosmos/agent_memory/aio/services/pipeline.py @@ -29,6 +29,14 @@ from azure.cosmos.agent_memory._container_routing import ContainerKey from azure.cosmos.agent_memory._curation import mark_secret, sanitize_record, sanitize_text +from azure.cosmos.agent_memory._partitioning import ( + DEFAULT_TENANT_ID, + OWNER_FILTER, + owner_parameters, + partition_key_for, + resolve_tenant_id, + stamp_scope, +) from azure.cosmos.agent_memory._utils import ( DEFAULT_TTL_BY_TYPE, compute_content_hash, @@ -66,7 +74,6 @@ ) from azure.cosmos.agent_memory.services._conflicts import conflict_link_body, conflict_pairs from azure.cosmos.agent_memory.services._dedup import ( - DEDUP_CURSOR_THREAD_ID, DEDUP_CURSOR_TYPE, DEDUP_PROMPT, Verdict, @@ -309,7 +316,11 @@ async def replace_item(self, **kwargs: Any) -> Any: class AsyncPipelineService: - """Async LLM orchestration service over the injected containers, async memory store and model clients.""" + """Async LLM orchestration service over the injected containers, async memory store and model clients. + + The service is bound to one tenant (``tenant_id``): every record it reads or writes is in the partition + ``[tenant_id, user_id]`` of its owner, and every query it sends filters on the tenant. + """ def __init__( self, @@ -320,7 +331,9 @@ def __init__( *, containers: dict[ContainerKey, Any], transcript_metadata_keys: Optional[Iterable[str]] = None, + tenant_id: str = DEFAULT_TENANT_ID, ) -> None: + self._tenant_id = resolve_tenant_id(tenant_id) self._store = store self._containers = containers self._memories_container = containers[ContainerKey.MEMORIES] @@ -431,8 +444,11 @@ def _build_transcript( ) def _sanitized_body(self, doc: dict[str, Any]) -> dict[str, Any]: - """Copy ``doc`` with literal credentials redacted, ready for a direct container write.""" - body = dict(doc) + """Copy ``doc`` with literal credentials redacted and the tenant stamped, ready for a direct container write. + + A document that names another tenant is refused: the service writes only into its own. + """ + body = stamp_scope(doc, self._tenant_id) redacted = sanitize_record(body) if redacted: logger.warning("redacted literal secrets before write id=%s patterns=%s", body.get("id"), redacted) @@ -513,19 +529,19 @@ async def extract_memories_durable( if turns is None: query = ( - "SELECT * FROM c WHERE c.user_id = @user_id " + f"SELECT * FROM c WHERE {OWNER_FILTER} " "AND c.thread_id = @thread_id AND c.type = 'turn' " "AND (NOT IS_DEFINED(c.extracted_at) OR IS_NULL(c.extracted_at))" ) parameters: list[dict[str, Any]] = [ - {"name": "@user_id", "value": user_id}, + *owner_parameters(self._tenant_id, user_id), {"name": "@thread_id", "value": thread_id}, ] items = await self._query_items( self._turns_container, query=query, parameters=parameters, - partition_key=[user_id, thread_id], + partition_key=partition_key_for(self._tenant_id, user_id), ) else: items = list(turns) @@ -655,6 +671,7 @@ async def extract_memories_durable( source_turn_ids = ground_fact_sources(fact, turn_ids=batch_turn_ids, labels=batch_labels) doc: dict[str, Any] = { "id": det_id, + "tenant_id": self._tenant_id, "user_id": user_id, "thread_id": thread_id, "role": "system", @@ -747,10 +764,11 @@ async def _extraction_window_context( return [], NONE window_ts = window_write_second(items, window_start) prior: list[dict[str, Any]] = [] + partition_key = partition_key_for(self._tenant_id, user_id) try: - query, parameters = previous_turns_query(user_id, thread_id, window_start, window_ts) + query, parameters = previous_turns_query(self._tenant_id, user_id, thread_id, window_start, window_ts) rows = await self._query_items( - self._turns_container, query=query, parameters=parameters, partition_key=[user_id, thread_id] + self._turns_container, query=query, parameters=parameters, partition_key=partition_key ) prior = prior_turns(rows, items) except Exception as exc: # noqa: BLE001 @@ -765,7 +783,7 @@ async def _extraction_window_context( summary_doc = await self._read_item( self._summaries_container, item=f"summary_{user_id}_{thread_id}", - partition_key=[user_id, thread_id], + partition_key=partition_key, ) summary = summary_text(summary_doc, window_start, window_ts) except CosmosResourceNotFoundError: @@ -786,11 +804,14 @@ async def _known_memories(self, user_id: str, batch: list[dict[str, Any]]) -> st return NONE try: query, parameters = known_facts_query( - user_id, await self._embed_one(text), latest_created_at(batch), _ACTIVE_DOC_FILTER + self._tenant_id, user_id, await self._embed_one(text), latest_created_at(batch), _ACTIVE_DOC_FILTER + ) + rows = await self._query_items( + self._memories_container, + query=query, + parameters=parameters, + partition_key=partition_key_for(self._tenant_id, user_id), ) - # The async SDK queries across partitions when no partition key is given and rejects - # enable_cross_partition_query (the sync SDK takes it). - rows = await self._query_items(self._memories_container, query=query, parameters=parameters) except Exception as exc: # noqa: BLE001 logger.warning( "extract_memories: extracting without stored memories user_id=%s err=%s", @@ -812,8 +833,8 @@ async def persist_extracted_memories( raise ValidationError("extracted must be a dict") result = self._empty_extract_counts() - fact_docs = [dict(doc) for doc in extracted.get("facts", [])] - episodic_docs = [dict(doc) for doc in extracted.get("episodic", [])] + fact_docs = [stamp_scope(doc, self._tenant_id) for doc in extracted.get("facts", [])] + episodic_docs = [stamp_scope(doc, self._tenant_id) for doc in extracted.get("episodic", [])] update_ops = [dict(op) for op in extracted.get("updates", [])] docs_to_create = fact_docs + episodic_docs @@ -877,7 +898,7 @@ async def _mark_turns_extracted(self, turn_docs: list[dict[str, Any]]) -> int: try: await self._turns_container.patch_item( item=turn_id, - partition_key=[turn.get("user_id"), turn.get("thread_id")], + partition_key=partition_key_for(self._tenant_id, turn.get("user_id")), patch_operations=[{"op": "set", "path": "/extracted_at", "value": now_iso}], ) marked += 1 @@ -935,25 +956,6 @@ async def extract_memories( ) return counts - async def _load_turn_window( - self, - user_id: str, - thread_id: str, - recent_k: int | None = None, - ) -> list[dict[str, Any]]: - """Load the newest turns for a thread, returned in chronological order.""" - query = "SELECT * FROM c WHERE c.user_id = @user_id AND c.thread_id = @thread_id AND c.type = 'turn'" - items = await self._query_items( - self._turns_container, - query=query, - parameters=[ - {"name": "@user_id", "value": user_id}, - {"name": "@thread_id", "value": thread_id}, - ], - partition_key=[user_id, thread_id], - ) - return newest_window(items, recent_k) - @staticmethod def _ground_episode_events( events: Any, @@ -1086,6 +1088,7 @@ async def _build_episode_docs( EpisodicRecord, { "id": self._deterministic_episode_id(segment_key, index), + "tenant_id": self._tenant_id, "user_id": user_id, "thread_id": thread_id, "role": "system", @@ -1140,7 +1143,7 @@ async def _read_episode_cursor(self, user_id: str, thread_id: str) -> tuple[str, doc = await self._read_item( self._memories_container, item=self._episode_cursor_id(user_id, thread_id), - partition_key=[user_id, thread_id], + partition_key=partition_key_for(self._tenant_id, user_id), ) except CosmosResourceNotFoundError: return "", "" @@ -1161,7 +1164,7 @@ async def _advance_episode_cursor(self, user_id: str, thread_id: str, last_turn: if not last_at: return cursor_id = self._episode_cursor_id(user_id, thread_id) - partition_key = [user_id, thread_id] + partition_key = partition_key_for(self._tenant_id, user_id) for _ in range(3): etag: Optional[str] = None try: @@ -1179,6 +1182,7 @@ async def _advance_episode_cursor(self, user_id: str, thread_id: str, last_turn: body = { "id": cursor_id, "type": "episode_cursor", + "tenant_id": self._tenant_id, "user_id": user_id, "thread_id": thread_id, "last_episode_at": last_at, @@ -1211,18 +1215,18 @@ async def _load_open_episode_segment(self, user_id: str, thread_id: str) -> list items = await self._query_items( self._turns_container, query=( - "SELECT * FROM c WHERE c.user_id = @user_id " + f"SELECT * FROM c WHERE {OWNER_FILTER} " "AND c.thread_id = @thread_id AND c.type = 'turn' " "AND (c.created_at > @last_at " "OR (c.created_at = @last_at AND c.id > @last_id))" ), parameters=[ - {"name": "@user_id", "value": user_id}, + *owner_parameters(self._tenant_id, user_id), {"name": "@thread_id", "value": thread_id}, {"name": "@last_at", "value": last_at}, {"name": "@last_id", "value": last_id}, ], - partition_key=[user_id, thread_id], + partition_key=partition_key_for(self._tenant_id, user_id), ) items.sort(key=created_at_sort_key) return items @@ -1400,10 +1404,10 @@ async def synthesize_procedural( logger.info("synthesize_procedural extraction started user_id=%s", user_id) - scope = ProcedureScope(user_id) + scope = ProcedureScope(self._tenant_id, user_id) cursor = await self._read_procedure_cursor(scope) - facts_read = await self._query_user_memories(*behavioral_facts_query(scope, cursor)) - episodes_read = await self._query_user_memories(*lesson_episodes_query(scope, cursor)) + facts_read = await self._query_procedures(scope, *behavioral_facts_query(scope, cursor)) + episodes_read = await self._query_procedures(scope, *lesson_episodes_query(scope, cursor)) batches = source_batches(facts_read, episodes_read) if not any(sources for sources, _, _ in batches): await self._advance_procedure_cursor(scope, cursor, facts_read, episodes_read) @@ -1563,7 +1567,9 @@ async def _apply_procedure_answer( async def _create_procedure( self, user_id: str, answer: ProcedureAnswer, now: str ) -> tuple[str, Optional[dict[str, Any]]]: - created = with_support(new_procedure(answer, user_id=user_id, now=now), answer.sources, answer.evidence) + created = with_support( + new_procedure(answer, tenant_id=self._tenant_id, user_id=user_id, now=now), answer.sources, answer.evidence + ) if created is None: return "skipped", None created.update(self._prompt_lineage("extract_procedure.prompty")) @@ -1633,14 +1639,10 @@ async def _read_procedure(self, scope: ProcedureScope, doc_id: str) -> Optional[ return None return doc if doc.get("type") == "procedural" and not doc.get("superseded_by") else None - async def _query_user_memories(self, query: str, parameters: list[dict[str, Any]]) -> list[dict[str, Any]]: - """Run ``query`` over all of the user's memories, which span their threads' partitions.""" - return await self._query_items(self._memories_container, query=query, parameters=parameters) - async def _query_procedures( self, scope: ProcedureScope, query: str, parameters: list[dict[str, Any]] ) -> list[dict[str, Any]]: - """Run ``query`` over the user's procedures, which all share one partition.""" + """Run ``query`` in the owner's partition, where their memories, procedures and procedure cursor all live.""" return await self._query_items( self._memories_container, query=query, parameters=parameters, partition_key=scope.partition_key ) @@ -1726,19 +1728,20 @@ async def generate_thread_summary_durable( logger.info("generate_thread_summary_durable started user_id=%s thread_id=%s", user_id, thread_id) summary_id = f"summary_{user_id}_{thread_id}" + partition_key = partition_key_for(self._tenant_id, user_id) existing_summary: Optional[dict[str, Any]] = None try: existing_summary = await self._read_item( self._summaries_container, item=summary_id, - partition_key=[user_id, thread_id], + partition_key=partition_key, ) except CosmosResourceNotFoundError: pass - query = "SELECT * FROM c WHERE c.user_id = @user_id AND c.thread_id = @thread_id AND c.type = 'turn'" + query = f"SELECT * FROM c WHERE {OWNER_FILTER} AND c.thread_id = @thread_id AND c.type = 'turn'" parameters: list[dict[str, Any]] = [ - {"name": "@user_id", "value": user_id}, + *owner_parameters(self._tenant_id, user_id), {"name": "@thread_id", "value": thread_id}, ] if existing_summary: @@ -1750,7 +1753,7 @@ async def generate_thread_summary_durable( self._turns_container, query=query, parameters=parameters, - partition_key=[user_id, thread_id], + partition_key=partition_key, ) if existing_summary and not items: @@ -1787,6 +1790,7 @@ async def generate_thread_summary_durable( doc_timestamp = self._stable_source_timestamp(items) summary_doc: dict[str, Any] = { "id": summary_id, + "tenant_id": self._tenant_id, "user_id": user_id, "thread_id": thread_id, "role": "system", @@ -1820,7 +1824,7 @@ async def persist_thread_summary( if not isinstance(summary_doc, dict): raise ValidationError("summary_doc must be a dict") - doc = dict(summary_doc) + doc = stamp_scope(summary_doc, self._tenant_id) doc["id"] = doc.get("id") or f"summary_{user_id}_{thread_id}" doc["user_id"] = user_id doc["thread_id"] = thread_id @@ -1866,18 +1870,19 @@ async def generate_user_summary_durable( ) user_summary_id = f"user_summary_{user_id}" + partition_key = partition_key_for(self._tenant_id, user_id) existing_summary: Optional[dict[str, Any]] = None try: existing_summary = await self._read_item( self._summaries_container, item=user_summary_id, - partition_key=[user_id, "__user_summary__"], + partition_key=partition_key, ) except CosmosResourceNotFoundError: pass - query_predicate = "c.user_id = @user_id" - parameters: list[dict[str, Any]] = [{"name": "@user_id", "value": user_id}] + query_predicate = OWNER_FILTER + parameters: list[dict[str, Any]] = owner_parameters(self._tenant_id, user_id) if existing_summary: since = existing_summary["updated_at"] query_predicate += " AND c.created_at > @since" @@ -1890,12 +1895,14 @@ async def generate_user_summary_durable( self._memories_container, query=memories_query, parameters=parameters, + partition_key=partition_key, ) items.extend( await self._query_items( self._summaries_container, query=summaries_query, parameters=parameters, + partition_key=partition_key, ) ) @@ -1945,6 +1952,7 @@ async def generate_user_summary_durable( doc_timestamp = self._stable_source_timestamp(items) summary_doc: dict[str, Any] = { "id": user_summary_id, + "tenant_id": self._tenant_id, "user_id": user_id, "thread_id": "__user_summary__", "role": "system", @@ -1977,7 +1985,7 @@ async def persist_user_summary( if not isinstance(user_summary_doc, dict): raise ValidationError("user_summary_doc must be a dict") - doc = dict(user_summary_doc) + doc = stamp_scope(user_summary_doc, self._tenant_id) doc["id"] = doc.get("id") or f"user_summary_{user_id}" doc["user_id"] = user_id doc["thread_id"] = "__user_summary__" @@ -2037,29 +2045,6 @@ def _emit_reconcile_outcome( }, ) - async def _load_memories_by_ids( - self, - user_id: str, - memory_type: str, - ids: Iterable[str], - ) -> list[dict[str, Any]]: - id_list = [mid for mid in dict.fromkeys(ids) if mid] - if not id_list: - return [] - placeholders = ", ".join(f"@id{i}" for i in range(len(id_list))) - query = ( - "SELECT * FROM c WHERE c.user_id = @user_id " - "AND c.type = @memory_type " - f"AND c.id IN ({placeholders}) " - f"AND {_ACTIVE_DOC_FILTER}" - ) - parameters = [ - {"name": "@user_id", "value": user_id}, - {"name": "@memory_type", "value": memory_type}, - ] - parameters.extend({"name": f"@id{i}", "value": mid} for i, mid in enumerate(id_list)) - return await self._query_items(self._memories_container, query=query, parameters=parameters) - async def reconcile_memories( self, user_id: str, n: int = 50, *, memory_type: str = "fact", deadline: Optional[float] = None ) -> dict[str, int]: @@ -2150,9 +2135,14 @@ async def consolidate_memories( logger.info("consolidate_memories started user_id=%s n=%d memory_type=%s", user_id, n, memory_type) cursor = await self._read_dedup_cursor(user_id, memory_type) query, parameters = unchecked_memories_query( - user_id, memory_type, cursor, top_literal(n, name="consolidate_memories.n") + self._tenant_id, user_id, memory_type, cursor, top_literal(n, name="consolidate_memories.n") + ) + seeds = await self._query_items( + self._memories_container, + query=query, + parameters=parameters, + partition_key=partition_key_for(self._tenant_id, user_id), ) - seeds = await self._query_items(self._memories_container, query=query, parameters=parameters) checked: list[tuple[dict[str, Any], list[Verdict]]] = [] done: list[dict[str, Any]] = [] @@ -2235,8 +2225,13 @@ async def _dedup_candidates( ``COMBINE_SIMILARITY_FLOOR`` it could be combined with; none without an embedding.""" if not isinstance(seed.get("embedding"), list) or not seed["embedding"]: return [] - query, parameters = neighbor_query(user_id, memory_type, seed) - neighbors = await self._query_items(self._memories_container, query=query, parameters=parameters) + query, parameters = neighbor_query(self._tenant_id, user_id, memory_type, seed) + neighbors = await self._query_items( + self._memories_container, + query=query, + parameters=parameters, + partition_key=partition_key_for(self._tenant_id, user_id), + ) return comparable_candidates(seed, neighbors) if combine else close_candidates(seed, neighbors) async def _verify_duplicates( @@ -2275,7 +2270,7 @@ async def _read_dedup_cursor(self, user_id: str, memory_type: str) -> Optional[d doc = await self._read_item( self._memories_container, item=dedup_cursor_id(user_id, memory_type), - partition_key=[user_id, DEDUP_CURSOR_THREAD_ID], + partition_key=partition_key_for(self._tenant_id, user_id), ) except CosmosResourceNotFoundError: return None @@ -2297,7 +2292,9 @@ async def _link_conflicts( written = 0 for pair in conflict_pairs(checked, absorbed=absorbed): try: - await self._upsert_item(self._memories_container, body=conflict_link_body(user_id, pair)) + await self._upsert_item( + self._memories_container, body=conflict_link_body(self._tenant_id, user_id, pair) + ) written += 1 except Exception as exc: # noqa: BLE001 - a link is best effort logger.warning( @@ -2320,7 +2317,7 @@ async def _advance_dedup_cursor( position = next_dedup_cursor(existing, checked) if position is None: return - body = dedup_cursor_body(existing, user_id, memory_type, position) + body = dedup_cursor_body(self._tenant_id, existing, user_id, memory_type, position) try: if existing is None: await self._create_item(self._memories_container, body=body) @@ -2485,7 +2482,7 @@ async def _members_unchanged(self, members: list[dict[str, Any]]) -> bool: for doc in members: try: current = await self._memories_container.read_item( - item=doc["id"], partition_key=[doc["user_id"], doc["thread_id"]] + item=doc["id"], partition_key=partition_key_for(self._tenant_id, doc["user_id"]) ) except CosmosResourceNotFoundError: return False @@ -2509,7 +2506,7 @@ async def _commit_combine(self, record: dict[str, Any], members: list[dict[str, existing = await self._read_item( self._memories_container, item=record["id"], - partition_key=[record["user_id"], record["thread_id"]], + partition_key=partition_key_for(self._tenant_id, record["user_id"]), ) except CosmosResourceNotFoundError: return None @@ -2534,7 +2531,7 @@ async def build_procedural_context(self, user_id: str, task: Optional[str] = Non """ if not user_id: raise ValidationError("user_id is required") - scope = ProcedureScope(user_id) + scope = ProcedureScope(self._tenant_id, user_id) today = utc_today() standing, left_out = standing_rules( await self._query_procedures(scope, *standing_rules_query(scope, today)), today diff --git a/azure/cosmos/agent_memory/aio/store/memory_store.py b/azure/cosmos/agent_memory/aio/store/memory_store.py index 2bd1ce1..2276c27 100644 --- a/azure/cosmos/agent_memory/aio/store/memory_store.py +++ b/azure/cosmos/agent_memory/aio/store/memory_store.py @@ -9,7 +9,6 @@ from azure.cosmos.agent_memory._container_routing import ( _CONTAINER_FOR_TYPE, - USER_SCOPED_MEMORIES_TYPES, ContainerKey, container_key_for_type, ) @@ -21,6 +20,15 @@ sanitize_record, sanitize_text, ) +from azure.cosmos.agent_memory._partitioning import ( + DEFAULT_TENANT_ID, + OWNER_FILTER, + owner_parameters, + partition_key_for, + resolve_tenant_id, + stamp_scope, + validate_owner_id, +) from azure.cosmos.agent_memory._query_builder import _QueryBuilder from azure.cosmos.agent_memory._utils import ( _build_memory_query_builder, @@ -67,7 +75,11 @@ class AsyncMemoryStore: - """Typed CRUD and query primitives over the split async Cosmos DB containers.""" + """Typed CRUD and query primitives over the split async Cosmos DB containers. + + A store is bound to one tenant: every query it builds filters on it, every point operation addresses the + partition ``[tenant_id, user_id]``, and every document it writes carries it. + """ def __init__( self, @@ -75,6 +87,7 @@ def __init__( containers: dict[ContainerKey, Any], embeddings_client: Any = None, enable_turn_embeddings: bool = False, + tenant_id: str = DEFAULT_TENANT_ID, ) -> None: self._containers = containers self._turns_container = containers[ContainerKey.TURNS] @@ -82,6 +95,12 @@ def __init__( self._summaries_container = containers[ContainerKey.SUMMARIES] self._embeddings_client = embeddings_client self._enable_turn_embeddings = enable_turn_embeddings + self._tenant_id = resolve_tenant_id(tenant_id) + + @property + def tenant_id(self) -> str: + """The tenant this store reads and writes.""" + return self._tenant_id @property def container(self) -> Any: @@ -89,8 +108,11 @@ def container(self) -> Any: return self._memories_container def _prepare_doc(self, doc: dict[str, Any]) -> dict[str, Any]: - """Return a write-ready document: literal credentials redacted and type defaults applied.""" - body = dict(doc) + """Return a write-ready document: stamped with the tenant, literal credentials redacted, type defaults applied. + + A document that names another tenant raises :class:`ValidationError`. + """ + body = stamp_scope(doc, self._tenant_id) redacted = sanitize_record(body) if redacted: logger.warning("redacted literal secrets before write id=%s patterns=%s", body.get("id"), redacted) @@ -190,11 +212,12 @@ async def query( ) -> list[dict[str, Any]]: """Run a query against the explicitly selected split container. - ``partition_key`` reads one partition; without it the query runs across partitions. A query - that calls ``FullTextScore`` raises ``ValidationError`` when it is sent with a - ``partition_key``: the Python SDK skips query planning for such a query, so the ranking would - be ignored (Azure/azure-sdk-for-python#42241). Filter on the partition key fields in the - ``WHERE`` clause instead (see ``query_scope``). ``full_text_score_scope`` (``"Local"`` or + ``sql`` runs as given, so it must filter on the tenant (``TENANT_FILTER`` or ``OWNER_FILTER`` of + ``_partitioning``) unless it is sent with the owner's ``partition_key``. ``partition_key`` reads one + partition; without it the query runs across partitions. A query that calls ``FullTextScore`` raises + ``ValidationError`` when it is sent with a ``partition_key``: the Python SDK skips query planning for such a + query, so the ranking would be ignored (Azure/azure-sdk-for-python#42241). Filter on the partition key fields + in the ``WHERE`` clause instead (see ``query_scope``). ``full_text_score_scope`` (``"Local"`` or ``"Global"``) sets where the keyword ranking takes its BM25 statistics from. """ return await self._query_items( @@ -284,8 +307,10 @@ async def add( follow ``enable_turn_embeddings``. A supplied ``embedding`` is kept, unless it was built from text that held a credential. """ + validate_owner_id(user_id) content, secret_patterns = sanitize_text(content) kwargs: dict[str, Any] = { + "tenant_id": self._tenant_id, "user_id": user_id, "role": role, "content": content, @@ -431,7 +456,10 @@ async def get_memories( created_after: Optional[str | datetime] = None, created_before: Optional[str | datetime] = None, ) -> list[dict[str, Any]]: - """Retrieve memories from the MEMORIES container with optional filters.""" + """Retrieve memories from the MEMORIES container with optional filters. + + Reads the store's tenant: one owner's memories when ``user_id`` is given, else every owner's. + """ types = _validated_memories_types(memory_types) logger.debug( "get_memories filters: memory_id=%s user_id=%s thread_id=%s role=%s types=%s recent_k=%s", @@ -444,6 +472,7 @@ async def get_memories( ) qb = _build_memory_query_builder( + tenant_id=self._tenant_id, memory_id=memory_id, user_id=user_id, thread_id=thread_id, @@ -473,9 +502,11 @@ async def get_memories( query = f"SELECT * FROM c{where}" logger.debug("async get_memories query: %s", query) + partition_key, _ = query_scope(self._tenant_id, user_id) results = await self._query_items( query=query, parameters=parameters or None, + partition_key=partition_key, operation="async get_memories query", container=self._memories_container, ) @@ -493,7 +524,6 @@ async def update( memory_id: str, *, user_id: str, - thread_id: str, memory_type: str, content: Optional[str] = None, role: Optional[str] = None, @@ -515,14 +545,15 @@ async def update( ) container = self._container_for_type(memory_type) + partition_key = partition_key_for(self._tenant_id, user_id) max_attempts = 5 attempts = 0 vectors: dict[str, list[float]] = {} while True: try: - doc = await container.read_item(item=memory_id, partition_key=[user_id, thread_id]) + doc = await container.read_item(item=memory_id, partition_key=partition_key) except CosmosResourceNotFoundError as exc: - raise MemoryNotFoundError(memory_id=memory_id, user_id=user_id, thread_id=thread_id) from exc + raise MemoryNotFoundError(memory_id=memory_id, user_id=user_id) from exc except Exception as exc: raise _wrap_cosmos_exception(exc, message=f"async update read failed for {memory_id}: {exc}") from exc @@ -570,7 +601,6 @@ async def delete( memory_id: str, *, user_id: str, - thread_id: str, memory_type: str, ) -> None: """Delete a memory document from the container for ``memory_type``. @@ -591,10 +621,11 @@ async def delete( ) container = self._container_for_type(memory_type) + partition_key = partition_key_for(self._tenant_id, user_id) try: - doc = await container.read_item(item=memory_id, partition_key=[user_id, thread_id]) + doc = await container.read_item(item=memory_id, partition_key=partition_key) except CosmosResourceNotFoundError as exc: - raise MemoryNotFoundError(memory_id=memory_id, user_id=user_id, thread_id=thread_id) from exc + raise MemoryNotFoundError(memory_id=memory_id, user_id=user_id) from exc except Exception as exc: raise _wrap_cosmos_exception(exc, message=f"async delete read failed for {memory_id}: {exc}") from exc @@ -605,19 +636,19 @@ async def delete( absorbed: list[dict[str, Any]] = [] if memory_type in ABSORBING_TYPES: try: - absorbed = await adelete_absorbed(container, user_id, memory_id) + absorbed = await adelete_absorbed(container, self._tenant_id, user_id, memory_id) except Exception as exc: raise _wrap_cosmos_exception( exc, message=f"async delete of the records folded into {memory_id} failed: {exc}" ) from exc - kwargs: dict[str, Any] = {"item": memory_id, "partition_key": [user_id, thread_id]} + kwargs: dict[str, Any] = {"item": memory_id, "partition_key": partition_key} if etag := doc.get("_etag"): kwargs.update(match_condition=MatchConditions.IfNotModified, etag=etag) try: await container.delete_item(**kwargs) except CosmosResourceNotFoundError as exc: - raise MemoryNotFoundError(memory_id=memory_id, user_id=user_id, thread_id=thread_id) from exc + raise MemoryNotFoundError(memory_id=memory_id, user_id=user_id) from exc except CosmosAccessConditionFailedError as exc: raise MemoryConflictError( f"delete conflicted for memory_id={memory_id!r} - document was modified after the type check" @@ -640,9 +671,8 @@ async def get_thread( created_before: Optional[str | datetime] = None, ) -> list[dict[str, Any]]: """Retrieve an entire thread (turns) sorted oldest first.""" - qb = _QueryBuilder() + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.thread_id", "@thread_id", thread_id) - qb.add_filter("c.user_id", "@user_id", user_id) add_tag_filters(qb, tags_all=tags_all, tags_any=tags_any, exclude_tags=exclude_tags) qb.add_time_range( "c.created_at", @@ -656,9 +686,11 @@ async def get_thread( query = f"SELECT {_TURN_PROJECTION} FROM c{qb.build_where()} ORDER BY c.created_at DESC" logger.debug("async get_thread query: %s", query) + partition_key, _ = query_scope(self._tenant_id, user_id) items = await self._query_items( query=query, parameters=qb.get_parameters(), + partition_key=partition_key, operation="async get_thread query", container=self._turns_container, ) @@ -674,9 +706,8 @@ async def get_thread_summary( recent_k: Optional[int] = None, ) -> list[dict[str, Any]]: """Retrieve active thread summaries for ``(user_id, thread_id)``, newest first.""" - qb = _QueryBuilder() + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.type", "@type", "thread_summary") - qb.add_filter("c.user_id", "@user_id", user_id) qb.add_filter("c.thread_id", "@thread_id", thread_id) qb.add_is_null_or_undefined("c.superseded_by") parameters = qb.get_parameters() @@ -688,7 +719,7 @@ async def get_thread_summary( return await self._query_items( query=sql, parameters=parameters, - partition_key=[user_id, thread_id], + partition_key=partition_key_for(self._tenant_id, user_id), operation="async get_thread_summary query", container=self._summaries_container, ) @@ -700,7 +731,7 @@ async def get_user_summary(self, user_id: str) -> Optional[dict[str, Any]]: try: return await self._summaries_container.read_item( item=f"user_summary_{user_id}", - partition_key=[user_id, "__user_summary__"], + partition_key=partition_key_for(self._tenant_id, user_id), ) except CosmosResourceNotFoundError: return None @@ -717,8 +748,8 @@ async def list_tags( include_superseded: bool = False, ) -> list[str]: """Return sorted distinct tags for a user from the MEMORIES container.""" - query = "SELECT VALUE c.tags FROM c WHERE c.user_id = @user_id AND ARRAY_LENGTH(c.tags) > 0" - parameters = [{"name": "@user_id", "value": user_id}] + query = f"SELECT VALUE c.tags FROM c WHERE {OWNER_FILTER} AND ARRAY_LENGTH(c.tags) > 0" + parameters = owner_parameters(self._tenant_id, user_id) if thread_id is not None: query += " AND c.thread_id = @thread_id" parameters.append({"name": "@thread_id", "value": thread_id}) @@ -726,11 +757,10 @@ async def list_tags( query += " AND (NOT IS_DEFINED(c.superseded_by) OR IS_NULL(c.superseded_by))" prefix_norm = prefix.strip().lower() if prefix else None - partition_key, _ = query_scope(user_id, thread_id) rows = await self._query_items( query=query, parameters=parameters, - partition_key=partition_key, + partition_key=partition_key_for(self._tenant_id, user_id), operation="async list_tags query", container=self._memories_container, ) @@ -752,7 +782,6 @@ async def _mutate_tags( self, memory_id: str, user_id: str, - thread_id: str, memory_type: str, tags: list[str], *, @@ -769,6 +798,7 @@ async def _mutate_tags( _validate_taggable_type(memory_type) container = self._container_for_type(memory_type) + partition_key = partition_key_for(self._tenant_id, user_id) secret_patterns: list[str] = [] if add: tags, secret_patterns = drop_secret_tags(tags) @@ -779,9 +809,9 @@ async def _mutate_tags( attempts = 0 while True: try: - doc = await container.read_item(item=memory_id, partition_key=[user_id, thread_id]) + doc = await container.read_item(item=memory_id, partition_key=partition_key) except CosmosResourceNotFoundError as exc: - raise MemoryNotFoundError(memory_id=memory_id, user_id=user_id, thread_id=thread_id) from exc + raise MemoryNotFoundError(memory_id=memory_id, user_id=user_id) from exc mark_secret(doc, secret_patterns) existing_tags = set(doc.get("tags", [])) if add: @@ -810,7 +840,6 @@ async def add_tags( self, memory_id: str, user_id: str, - thread_id: str, memory_type: str, tags: list[str], ) -> None: @@ -819,18 +848,17 @@ async def add_tags( Tags are lower-cased. A tag that holds a literal credential is dropped, and the memory is marked ``sys:secret``. """ - await self._mutate_tags(memory_id, user_id, thread_id, memory_type, tags, add=True) + await self._mutate_tags(memory_id, user_id, memory_type, tags, add=True) async def remove_tags( self, memory_id: str, user_id: str, - thread_id: str, memory_type: str, tags: list[str], ) -> None: """Remove tags from an existing fact, episodic or procedural memory.""" - await self._mutate_tags(memory_id, user_id, thread_id, memory_type, tags, add=False) + await self._mutate_tags(memory_id, user_id, memory_type, tags, add=False) async def mark_superseded( self, @@ -839,7 +867,10 @@ async def mark_superseded( *, reason: str, ) -> bool: - """Set supersession audit fields using ETag protection when available.""" + """Set supersession audit fields using ETag protection when available. + + A document that names another tenant raises :class:`ValidationError`. + """ from azure.core import MatchConditions from azure.cosmos.exceptions import ( CosmosAccessConditionFailedError, @@ -847,12 +878,15 @@ async def mark_superseded( ) etag = old_doc.get("_etag") - new_doc = { - **old_doc, - "superseded_by": superseder_id, - "supersede_reason": reason, - "superseded_at": datetime.now(timezone.utc).isoformat(), - } + new_doc = stamp_scope( + { + **old_doc, + "superseded_by": superseder_id, + "supersede_reason": reason, + "superseded_at": datetime.now(timezone.utc).isoformat(), + }, + self._tenant_id, + ) target_container = self._container_for_type(old_doc.get("type")) try: if etag: @@ -891,8 +925,7 @@ async def get_procedural_prompt(self, user_id: str) -> Optional[str]: instructions: ``AsyncCosmosMemoryClient.get_procedural_prompt`` compiles those from the active standing rules. """ - qb = _QueryBuilder() - qb.add_filter("c.user_id", "@user_id", user_id) + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.thread_id", "@thread_id", "__procedural__") qb.add_filter("c.type", "@type", "procedural") qb.add_is_null_or_undefined("c.superseded_by") @@ -901,6 +934,7 @@ async def get_procedural_prompt(self, user_id: str) -> Optional[str]: items = await self._query_items( query=query, parameters=qb.get_parameters(), + partition_key=partition_key_for(self._tenant_id, user_id), operation="async get_procedural_prompt query", container=self._memories_container, ) @@ -918,8 +952,7 @@ async def get_procedural_history(self, user_id: str, limit: int = 10) -> list[di if limit <= 0: return [] - qb = _QueryBuilder() - qb.add_filter("c.user_id", "@user_id", user_id) + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.thread_id", "@thread_id", "__procedural__") qb.add_filter("c.type", "@type", "procedural") @@ -927,6 +960,7 @@ async def get_procedural_history(self, user_id: str, limit: int = 10) -> list[di items = await self._query_items( query=query, parameters=qb.get_parameters(), + partition_key=partition_key_for(self._tenant_id, user_id), operation="async get_procedural_history query", container=self._memories_container, ) @@ -959,8 +993,7 @@ async def get_procedural_memories( ``metadata.category`` and ``salience``, which procedures learned by ``synthesize_procedural`` do not carry, so setting one leaves them out. """ - qb = _QueryBuilder() - qb.add_filter("c.user_id", "@user_id", user_id) + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.thread_id", "@thread_id", "__procedural__") qb.add_filter("c.type", "@type", "procedural") if not include_superseded: @@ -970,6 +1003,7 @@ async def get_procedural_memories( items = await self._query_items( query=query, parameters=qb.get_parameters(), + partition_key=partition_key_for(self._tenant_id, user_id), operation="async get_procedural_memories query", container=self._memories_container, ) @@ -991,9 +1025,8 @@ async def get_episodes( """Retrieve active episodic memories for ``user_id``, newest first.""" if not user_id: raise ValidationError("user_id is required for get_episodes") - qb = _QueryBuilder() + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.type", "@type", "episodic") - qb.add_filter("c.user_id", "@user_id", user_id) qb.add_filter("c.thread_id", "@thread_id", thread_id) qb.add_is_null_or_undefined("c.superseded_by") parameters = qb.get_parameters() @@ -1003,13 +1036,12 @@ async def get_episodes( else: sql = f"SELECT * FROM c{qb.build_where()} ORDER BY c.created_at DESC" - partition_key, _ = query_scope(user_id, thread_id) logger.debug("AsyncMemoryStore.get_episodes query: %s", sql) return await self.query( sql, parameters, container_key=ContainerKey.MEMORIES, - partition_key=partition_key, + partition_key=partition_key_for(self._tenant_id, user_id), ) async def search( @@ -1049,10 +1081,9 @@ async def search( ``query_embedding`` is the query's embedding when the caller already has it. ``thread_id`` limits facts to that thread; episodic and procedural memories stay user-wide. - A keyword query, or a thread-scoped search that includes those user-wide types, runs across - partitions with ``user_id`` and ``thread_id`` filters in the WHERE clause (keyword queries - also set ``full_text_score_scope="Local"``); a vector-only query over facts with both ids - reads one partition (see ``query_scope``). + The search reads the store's tenant only. A vector-only query that names ``user_id`` reads that owner's + partition; a keyword query runs across partitions with the ``tenant_id`` and ``user_id`` filters in the + WHERE clause and sets ``full_text_score_scope="Local"`` (see ``query_scope``). """ terms = require_search_terms(search_terms, query) top = top_literal(top_k, name="top_k") @@ -1060,6 +1091,7 @@ async def search( keywords = [] if vector_only else extract_keywords(terms) qb = _build_memory_query_builder( + tenant_id=self._tenant_id, memory_id=memory_id, user_id=user_id, role=role, @@ -1095,9 +1127,7 @@ async def search( for i, kw in enumerate(keywords): parameters.append({"name": f"@kw{i}", "value": kw}) - partition_key, _ = query_scope(user_id, thread_id, len(keywords)) - if thread_id is not None and (not memory_types or set(memory_types) & USER_SCOPED_MEMORIES_TYPES): - partition_key = None + partition_key, _ = query_scope(self._tenant_id, user_id, len(keywords)) logger.debug("AsyncMemoryStore.search query: %s", sql) return await self.query( sql, @@ -1111,7 +1141,6 @@ async def get_memory_history( self, memory_id: str, user_id: str, - thread_id: Optional[str] = None, *, max_depth: int = 20, ) -> list[dict[str, Any]]: @@ -1128,25 +1157,21 @@ async def get_memory_history( value is everything it superseded, transitively, bounded by *max_depth* to guard against cycles. Each entry carries the ``superseded_at`` / ``supersede_reason`` audit fields so callers can order and explain the - transitions. + transitions. The walk stays in the owner's partition, whatever threads the records belong to. """ if not memory_id: raise ValidationError("memory_id is required") if not user_id: raise ValidationError("user_id is required") - partition_key, _ = query_scope(user_id, thread_id) + partition_key = partition_key_for(self._tenant_id, user_id) history: list[dict[str, Any]] = [] seen: set[str] = {memory_id} frontier: list[str] = [memory_id] for _ in range(max(1, max_depth)): id_params = [{"name": f"@sid{i}", "value": sid} for i, sid in enumerate(frontier)] placeholders = ", ".join(param["name"] for param in id_params) - parameters: list[dict[str, Any]] = [*id_params, {"name": "@user_id", "value": user_id}] - where = f"c.superseded_by IN ({placeholders}) AND c.user_id = @user_id" - if thread_id is not None: - where += " AND c.thread_id = @thread_id" - parameters.append({"name": "@thread_id", "value": thread_id}) - sql = f"SELECT {MEMORY_PROJECTION} FROM c WHERE {where}" + parameters: list[dict[str, Any]] = [*id_params, *owner_parameters(self._tenant_id, user_id)] + sql = f"SELECT {MEMORY_PROJECTION} FROM c WHERE c.superseded_by IN ({placeholders}) AND {OWNER_FILTER}" rows = await self.query( sql, parameters, @@ -1185,13 +1210,11 @@ async def search_turns( Only vector-searchable when turn embeddings were enabled at write time (see ``enable_turn_embeddings``). ``user_id`` is required and always - filters the results. When ``thread_id`` is also supplied the results are - restricted to that thread: a vector-only query targets the thread's - partition, while a keyword (hybrid) query runs across partitions with - ``user_id`` and ``thread_id`` filters in the WHERE clause (a partition key - breaks full-text ranking, Azure SDK issue #42241). When it is omitted the - query fans out across the user's partitions. - + filters the results, within the store's tenant. ``thread_id`` narrows the + results to one thread. A vector-only query reads the owner's partition, + while a keyword (hybrid) query runs across partitions with the ``tenant_id`` + and ``user_id`` filters in the WHERE clause (a partition key breaks + full-text ranking, Azure SDK issue #42241). """ if not user_id: raise ValidationError("user_id is required for search_turns") @@ -1200,8 +1223,7 @@ async def search_turns( query_vector = await self._embed(terms) keywords = extract_keywords(terms) - qb = _QueryBuilder() - qb.add_filter("c.user_id", "@user_id", user_id) + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.thread_id", "@thread_id", thread_id) qb.add_filter("c.role", "@role", role) add_tag_filters(qb, tags_all=tags_all, tags_any=tags_any, exclude_tags=exclude_tags) @@ -1219,7 +1241,7 @@ async def search_turns( for i, kw in enumerate(keywords): parameters.append({"name": f"@kw{i}", "value": kw}) - partition_key, _ = query_scope(user_id, thread_id, len(keywords)) + partition_key, _ = query_scope(self._tenant_id, user_id, len(keywords)) logger.debug("AsyncMemoryStore.search_turns query: %s", sql) return await self.query( sql, @@ -1249,9 +1271,9 @@ async def search_summaries( topic-scoped summary question all surface the right summary. Ranking is by vector similarity, with full-text relevance added when the query has keywords. ``user_id`` is required. Pass ``thread_id`` to narrow to one - thread's summary; as with :meth:`search_turns`, a keyword query then runs - across partitions with ``user_id`` and ``thread_id`` filters in the WHERE - clause, and a vector-only query targets the thread's partition. + thread's summary. As with :meth:`search_turns`, a vector-only query reads + the owner's partition and a keyword query runs across partitions with the + ``tenant_id`` and ``user_id`` filters in the WHERE clause. """ if not user_id: raise ValidationError("user_id is required for search_summaries") @@ -1260,8 +1282,7 @@ async def search_summaries( query_vector = await self._embed(terms) keywords = extract_keywords(terms) - qb = _QueryBuilder() - qb.add_filter("c.user_id", "@user_id", user_id) + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.thread_id", "@thread_id", thread_id) add_tag_filters(qb, tags_all=tags_all, tags_any=tags_any, exclude_tags=exclude_tags) @@ -1271,7 +1292,7 @@ async def search_summaries( for i, kw in enumerate(keywords): parameters.append({"name": f"@kw{i}", "value": kw}) - partition_key, _ = query_scope(user_id, thread_id, len(keywords)) + partition_key, _ = query_scope(self._tenant_id, user_id, len(keywords)) logger.debug("AsyncMemoryStore.search_summaries query: %s", sql) return await self.query( sql, @@ -1310,9 +1331,8 @@ async def search_episodic( query_vector = await self._embed(terms) keywords = extract_keywords(terms) - qb = _QueryBuilder() + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.type", "@type", "episodic") - qb.add_filter("c.user_id", "@user_id", user_id) qb.add_filter("c.thread_id", "@thread_id", thread_id) add_tag_filters(qb, tags_all=tags_all, tags_any=tags_any, exclude_tags=exclude_tags) qb.add_time_range( @@ -1349,7 +1369,7 @@ async def search_episodic( for i, kw in enumerate(keywords): parameters.append({"name": f"@kw{i}", "value": kw}) - partition_key, _ = query_scope(user_id, thread_id, len(keywords)) + partition_key, _ = query_scope(self._tenant_id, user_id, len(keywords)) logger.debug("AsyncMemoryStore.search_episodic query: %s", sql) return await self.query( sql, @@ -1389,9 +1409,8 @@ async def retrieve_procedures( query_vector = await self._embed(terms) keywords = extract_keywords(terms) - qb = _QueryBuilder() + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.type", "@type", "procedural") - qb.add_filter("c.user_id", "@user_id", user_id) qb.add_filter("c.procedure_kind", "@procedure_kind", procedure_kind) qb.add_filter("c.status", "@status", status) @@ -1406,7 +1425,7 @@ async def retrieve_procedures( for i, kw in enumerate(keywords): parameters.append({"name": f"@kw{i}", "value": kw}) - partition_key, _ = query_scope(user_id, None) + partition_key, _ = query_scope(self._tenant_id, user_id, len(keywords)) logger.debug("AsyncMemoryStore.retrieve_procedures query: %s", sql) return await self.query( sql, diff --git a/azure/cosmos/agent_memory/auto_trigger.py b/azure/cosmos/agent_memory/auto_trigger.py index bb5fb4f..5acea90 100644 --- a/azure/cosmos/agent_memory/auto_trigger.py +++ b/azure/cosmos/agent_memory/auto_trigger.py @@ -79,6 +79,7 @@ def _should_trigger(processor: Any, thresholds: Any) -> bool: def maybe_trigger_steps( processor: Any, counter_container: Any, + tenant_id: str, turn_counts: dict[tuple[str, str], int], *, thresholds: Any = default_thresholds, @@ -92,6 +93,8 @@ def maybe_trigger_steps( trigger is skipped for any other processor type (e.g. durable). counter_container: The Cosmos counter container. ``None`` disables the trigger. + tenant_id: + The tenant the counters belong to; they live in each owner's ``[tenant_id, user_id]`` partition. turn_counts: Map of ``(user_id, thread_id) -> turns_pushed_in_this_batch``. thresholds: @@ -116,6 +119,7 @@ def maybe_trigger_steps( user_batch_counts = _trigger_thread_steps( processor, counter_container, + tenant_id, turn_counts, n_facts=n_facts, n_summary=n_summary, @@ -123,12 +127,13 @@ def maybe_trigger_steps( n_dedup_turns=n_dedup_turns, thresholds=thresholds, ) - _trigger_user_steps(processor, counter_container, user_batch_counts, n_user=n_user) + _trigger_user_steps(processor, counter_container, tenant_id, user_batch_counts, n_user=n_user) def _trigger_thread_steps( processor: InProcessProcessor, counter_container: Any, + tenant_id: str, turn_counts: dict[tuple[str, str], int], *, n_facts: int, @@ -146,6 +151,7 @@ def _trigger_thread_steps( try: old_count, new_count = _counters.increment_counter_sync( counter_container, + tenant_id, counter_id, user_id, thread_id, @@ -158,6 +164,7 @@ def _trigger_thread_steps( _fire_thread_steps( processor, counter_container, + tenant_id, counter_id, user_id, thread_id, @@ -174,6 +181,7 @@ def _trigger_thread_steps( def _fire_thread_steps( processor: InProcessProcessor, counter_container: Any, + tenant_id: str, counter_id: str, user_id: str, thread_id: str, @@ -200,7 +208,7 @@ def _fire_thread_steps( error = describe_exception(exc) logger.warning("Auto-trigger process_extract_memories failed for %s/%s: %s", user_id, thread_id, error) _counters.stamp_failure_sync( - counter_container, counter_id, user_id, thread_id, f"process_extract_memories: {error}" + counter_container, tenant_id, counter_id, user_id, f"process_extract_memories: {error}" ) for enabled, label, call in ( ( @@ -231,12 +239,13 @@ def _fire_thread_steps( except Exception as exc: error = describe_exception(exc) logger.warning("Auto-trigger %s failed for %s/%s: %s", label, user_id, thread_id, error) - _counters.stamp_failure_sync(counter_container, counter_id, user_id, thread_id, f"{label}: {error}") + _counters.stamp_failure_sync(counter_container, tenant_id, counter_id, user_id, f"{label}: {error}") def _trigger_user_steps( processor: InProcessProcessor, counter_container: Any, + tenant_id: str, user_batch_counts: dict[str, int], *, n_user: int, @@ -248,6 +257,7 @@ def _trigger_user_steps( try: old_count, new_count = _counters.increment_counter_sync( counter_container, + tenant_id, counter_id, user_id, _counters.USER_COUNTER_THREAD_ID, @@ -266,9 +276,9 @@ def _trigger_user_steps( logger.warning("Auto-trigger process_user_summary failed for %s: %s", user_id, error) _counters.stamp_failure_sync( counter_container, + tenant_id, counter_id, user_id, - _counters.USER_COUNTER_THREAD_ID, f"process_user_summary: {error}", ) diff --git a/azure/cosmos/agent_memory/cosmos_memory_client.py b/azure/cosmos/agent_memory/cosmos_memory_client.py index 0080e68..c14ade4 100644 --- a/azure/cosmos/agent_memory/cosmos_memory_client.py +++ b/azure/cosmos/agent_memory/cosmos_memory_client.py @@ -11,6 +11,7 @@ from ._base import _BaseMemoryClient from ._base.base_client import is_transient_tail_step_error from ._container_routing import ContainerKey, container_key_for_type +from ._partitioning import PARTITION_KEY_PATHS, partition_key_problem from ._utils import ( _build_container_kwargs, _container_policies, @@ -26,7 +27,7 @@ from .auto_trigger import maybe_trigger_steps from .chat import ChatClient from .embeddings import EmbeddingsClient -from .exceptions import CosmosOperationError, MemoryNotFoundError, ValidationError +from .exceptions import ConfigurationError, CosmosOperationError, MemoryNotFoundError, ValidationError from .processors import InProcessProcessor, MemoryProcessor from .services._conflicts import with_conflicts from .services._pipeline_helpers import _normalize_cadence_thresholds, _normalize_metadata_keys @@ -42,7 +43,12 @@ class CosmosMemoryClient(_BaseMemoryClient): - """Manages local and Cosmos-backed memories via store and service layers.""" + """Manages local and Cosmos-backed memories via store and service layers. + + A client is bound to one tenant (``tenant_id``, ``"default"`` when not given): every record it reads + or writes belongs to it. Records are keyed by ``[tenant_id, user_id]``, where ``user_id`` is the owner + of the memory, a user or an agent, and ``thread_id`` is a plain field. + """ def __init__( self, @@ -72,6 +78,7 @@ def __init__( transcript_metadata_keys: Optional[Iterable[str]] = None, cadence_thresholds: Optional[Mapping[str, int]] = None, cosmos_preferred_locations: Optional[str | Iterable[str]] = None, + tenant_id: Optional[str] = None, ) -> None: self._init_base_config( cosmos_endpoint=cosmos_endpoint, @@ -95,6 +102,7 @@ def __init__( enable_turn_embeddings=enable_turn_embeddings, user_agent=user_agent, cosmos_preferred_locations=cosmos_preferred_locations, + tenant_id=tenant_id, ) # Embeddings/chat clients may be injected (e.g. an OpenAI-compatible backend, a # caller-configured client, or a deterministic fake for offline tests). When a client @@ -290,8 +298,9 @@ def create_memory_store( user_agent=self._cosmos_user_agent, preferred_locations=self._cosmos_preferred_locations, ) + self._cosmos_client = client db = client.create_database_if_not_exists(id=self._cosmos_database) - partition_key = PartitionKey(path=["/user_id", "/thread_id"], kind="MultiHash") + partition_key = PartitionKey(path=list(PARTITION_KEY_PATHS), kind="MultiHash") offer = _cosmos_container_offer_throughput( throughput_mode=self._cosmos_throughput_mode, autoscale_max_ru=self._cosmos_autoscale_max_ru, @@ -334,12 +343,13 @@ def create_memory_store( logger.info("Created turns container: %s/%s", self._cosmos_database, self._cosmos_turns_container) # Summaries carry the vector + full-text index too, so summaries are # semantically searchable (search_summaries). Keep the point-lookup - # composite (user_id, thread_id, version) get_*_summary relies on. + # composite (tenant_id, user_id, thread_id, version) get_*_summary relies on. summaries_vec_policy, summaries_idx_policy, summaries_ft_policy = _container_policies( **{**_policy_kwargs, "vector_index_type": "quantizedFlat"}, ) summaries_idx_policy["compositeIndexes"] = [ [ + {"path": "/tenant_id", "order": "ascending"}, {"path": "/user_id", "order": "ascending"}, {"path": "/thread_id", "order": "ascending"}, {"path": "/version", "order": "descending"}, @@ -361,7 +371,7 @@ def create_memory_store( self._cosmos_database, self._cosmos_summaries_container, ) - db.create_container_if_not_exists( + counter_container = db.create_container_if_not_exists( **_build_container_kwargs( container_id=self._cosmos_counter_container, partition_key=partition_key, @@ -369,6 +379,15 @@ def create_memory_store( default_ttl=COUNTER_TTL_SECONDS, ) ) + # An existing container keeps the key it was created with, and one keyed differently takes writes + # but is read back empty, so it is refused here rather than later. + for keyed_container in ( + self._memories_container_client, + self._turns_container_client, + self._summaries_container_client, + counter_container, + ): + self._require_partition_key(keyed_container) db.create_container_if_not_exists( **_build_container_kwargs( container_id=self._cosmos_lease_container, @@ -376,18 +395,19 @@ def create_memory_store( offer_throughput=offer, ) ) - self._cosmos_client = client self._init_services() except Exception as exc: + # The store cannot be used: close the client just opened and forget its containers. + self._drain_cosmos_client() raise CosmosOperationError(f"Failed to create memory store: {exc}") from exc logger.info("Created memory store %s/%s", self._cosmos_database, self._cosmos_container) def validate_topology(self) -> None: - """Verify all three Cosmos containers exist and are reachable. + """Verify the Cosmos containers exist, are reachable, and are keyed ``[/tenant_id, /user_id]``. - Reads container metadata for memories / memories_turns / memories_summaries. - Raises ``RuntimeError`` on the first failure with a clear message - instructing the customer to redeploy the infrastructure. + Reads container metadata for memories / memories_turns / memories_summaries and the counter container. + Raises ``RuntimeError`` on the first failure with a clear message: to redeploy the infrastructure when a + container is missing, or to recreate it when its partition key is not the one this SDK requires. Call this after ``connect_cosmos`` or ``create_memory_store`` to diagnose topology mismatches before any data is written. @@ -396,12 +416,16 @@ def validate_topology(self) -> None: if self._memories_container_client is None: raise RuntimeError("validate_topology: Cosmos client is not connected; call connect_cosmos() first") - for key, client in self._containers.items(): + checks: list[tuple[str, Any]] = [(key.value, client) for key, client in self._containers.items()] + counter_client = self._get_counter_container() + if counter_client is not None: + checks.append((self._cosmos_counter_container, counter_client)) + for label, client in checks: if client is None: - raise RuntimeError(f"validate_topology: container for {key.value!r} is not connected") - container_id = getattr(client, "id", key.value) + raise RuntimeError(f"validate_topology: container for {label!r} is not connected") + container_id = getattr(client, "id", label) try: - client.read() + properties = client.read() except CosmosResourceNotFoundError as exc: raise RuntimeError( f"validate_topology: container {container_id!r} does not exist; " @@ -411,12 +435,22 @@ def validate_topology(self) -> None: raise RuntimeError( f"validate_topology: cannot read container {container_id!r}: {type(exc).__name__}: {exc}" ) from exc + problem = partition_key_problem(container_id, properties) + if problem: + raise RuntimeError(f"validate_topology: {problem}") + + @staticmethod + def _require_partition_key(container: Any) -> None: + problem = partition_key_problem(getattr(container, "id", None), container.read()) + if problem: + raise ConfigurationError(problem) def _build_store(self) -> MemoryStore: return MemoryStore( containers=self._containers, embeddings_client=self._embeddings_client, enable_turn_embeddings=self._enable_turn_embeddings, + tenant_id=self._tenant_id, ) def _build_pipeline(self, store: MemoryStore) -> PipelineService: @@ -426,6 +460,7 @@ def _build_pipeline(self, store: MemoryStore) -> PipelineService: self._embeddings_client, containers=self._containers, transcript_metadata_keys=self._transcript_metadata_keys, + tenant_id=self._tenant_id, ) def _store_uses_current_clients(self) -> bool: @@ -524,6 +559,7 @@ def _maybe_auto_trigger(self, turn_counts: dict[tuple[str, str], int]) -> None: maybe_trigger_steps( self._get_processor(), self._get_counter_container(), + self._tenant_id, turn_counts, thresholds=self._cadence_thresholds, ) @@ -650,13 +686,12 @@ def update_cosmos( memory_id: str, *, user_id: str, - thread_id: str, memory_type: str, content: Optional[str] = None, role: Optional[str] = None, metadata: Optional[dict[str, Any]] = None, ) -> None: - """Update a memory in Cosmos DB. + """Update a memory of ``user_id`` in Cosmos DB. Replaces ``content``, ``role`` and ``metadata`` where given, on the memory in the container that holds ``memory_type``, which must be its stored type. Literal credentials are redacted @@ -667,7 +702,6 @@ def update_cosmos( return self._get_store().update( memory_id, user_id=user_id, - thread_id=thread_id, memory_type=memory_type, content=content, role=role, @@ -679,10 +713,9 @@ def delete_memory( memory_id: str, *, user_id: str, - thread_id: str, memory_type: str, ) -> None: - """Delete a memory from Cosmos DB. + """Delete a memory of ``user_id`` from Cosmos DB. Raises ``MemoryNotFoundError`` if it does not exist and ``MemoryTypeMismatchError`` if its stored type is not ``memory_type``. Deleting a fact or procedure first deletes the records @@ -693,16 +726,14 @@ def delete_memory( return self._get_store().delete( memory_id, user_id=user_id, - thread_id=thread_id, memory_type=memory_type, ) - def delete_turn(self, turn_id: str, *, user_id: str, thread_id: str) -> None: - """Delete a single turn document. Raises if it does not exist.""" + def delete_turn(self, turn_id: str, *, user_id: str) -> None: + """Delete a single turn document of ``user_id``. Raises if it does not exist.""" return self.delete_memory( turn_id, user_id=user_id, - thread_id=thread_id, memory_type="turn", ) @@ -716,7 +747,6 @@ def delete_thread_summary(self, user_id: str, thread_id: str) -> bool: self.delete_memory( f"summary_{user_id}_{thread_id}", user_id=user_id, - thread_id=thread_id, memory_type="thread_summary", ) return True @@ -732,7 +762,6 @@ def delete_user_summary(self, user_id: str) -> bool: self.delete_memory( f"user_summary_{user_id}", user_id=user_id, - thread_id="__user_summary__", memory_type="user_summary", ) return True @@ -760,7 +789,7 @@ def delete_thread(self, user_id: str, thread_id: str, *, include_summary: bool = if not turn_id: continue try: - self.delete_memory(turn_id, user_id=user_id, thread_id=thread_id, memory_type="turn") + self.delete_memory(turn_id, user_id=user_id, memory_type="turn") deleted += 1 except MemoryNotFoundError: continue @@ -807,10 +836,10 @@ def search_cosmos( block, deduped by content (best-effort; a blend fetch failure never breaks the base result). Blending, like the slots, needs ``user_id``. - ``thread_id`` limits facts to that thread; episodes and procedures stay user-wide. A keyword - (hybrid) query runs across partitions with ``c.user_id`` (and ``c.thread_id``, when given) - in the ``WHERE`` clause, because a partition key breaks full-text ranking (Azure SDK issue - #42241). Only a vector-only query with both ids over facts reads one partition. + ``thread_id`` limits facts to that thread; episodes and procedures stay user-wide. With ``user_id``, a + vector-only query reads that user's partition only. A keyword (hybrid) query runs across partitions with + the tenant and user filters in the ``WHERE`` clause, because a partition key breaks full-text ranking + (Azure SDK issue #42241). ``preference_slot`` and ``procedure_slot`` reserve result slots within ``top_k`` (see ``azure.cosmos.agent_memory._slots``): the user's best-matching preference fact @@ -945,7 +974,7 @@ def _extend(docs: list[dict[str, Any]]) -> None: def query_memories(sql: str, parameters: Any, **kwargs: Any) -> Any: return store.query(sql, parameters, container_key=ContainerKey.MEMORIES, **kwargs) - return with_conflicts(results, query_memories) + return with_conflicts(results, query_memories, self._tenant_id) def _slot_candidates(self, store: Any, search_kwargs: dict[str, Any]) -> list[dict[str, Any]]: """Candidates for a result slot; a failed slot search leaves the slot to the ranked results.""" @@ -1001,11 +1030,10 @@ def search_turns( Searches the turns container directly. Only vector-searchable when ``enable_turn_embeddings`` was set when the turns were written. ``user_id`` is required and always filters the results. Passing - ``thread_id`` as well restricts the results to that thread: a vector-only - query targets the thread's partition, while a keyword (hybrid) query runs - across partitions with ``user_id`` and ``thread_id`` filters in the WHERE - clause (a partition key breaks full-text ranking, Azure SDK issue #42241). - Omitting it fans out across the user's partitions. + ``thread_id`` as well restricts the results to that thread. A vector-only + query reads the user's partition; a keyword (hybrid) query runs across + partitions with the tenant, user and thread filters in the WHERE clause + (a partition key breaks full-text ranking, Azure SDK issue #42241). """ return self._get_store().search_turns( search_terms=search_terms, @@ -1024,7 +1052,6 @@ def get_memory_history( self, memory_id: str, user_id: str, - thread_id: Optional[str] = None, *, max_depth: int = 20, ) -> list[dict[str, Any]]: @@ -1042,7 +1069,6 @@ def get_memory_history( return self._get_store().get_memory_history( memory_id, user_id, - thread_id, max_depth=max_depth, ) @@ -1121,7 +1147,6 @@ def add_tags( self, memory_id: str, user_id: str, - thread_id: str, memory_type: str, tags: list[str], ) -> None: @@ -1130,18 +1155,17 @@ def add_tags( Tags are lower-cased. A tag that holds a literal credential is dropped, and the memory is marked ``sys:secret``. """ - return self._get_store().add_tags(memory_id, user_id, thread_id, memory_type, tags) + return self._get_store().add_tags(memory_id, user_id, memory_type, tags) def remove_tags( self, memory_id: str, user_id: str, - thread_id: str, memory_type: str, tags: list[str], ) -> None: """Remove tags from an existing fact, episodic or procedural memory.""" - return self._get_store().remove_tags(memory_id, user_id, thread_id, memory_type, tags) + return self._get_store().remove_tags(memory_id, user_id, memory_type, tags) def get_procedural_prompt(self, user_id: str) -> Optional[str]: """Return the user's standing instructions as a prompt block, or None when there are none. diff --git a/azure/cosmos/agent_memory/exceptions.py b/azure/cosmos/agent_memory/exceptions.py index 7d9979d..7484e40 100644 --- a/azure/cosmos/agent_memory/exceptions.py +++ b/azure/cosmos/agent_memory/exceptions.py @@ -83,8 +83,7 @@ class MemoryNotFoundError(AgentMemoryError): Attributes: memory_id: The ID of the memory that was not found. - user_id: The user ID used in the lookup. - thread_id: The thread ID used in the lookup. + user_id: The owner (``user_id``) used in the lookup. """ error_code = "memory_not_found" @@ -95,11 +94,9 @@ def __init__( *, memory_id: str | None = None, user_id: str | None = None, - thread_id: str | None = None, ): self.memory_id = memory_id self.user_id = user_id - self.thread_id = thread_id if message is None: message = self._build_message() super().__init__(message) @@ -110,8 +107,6 @@ def _build_message(self) -> str: parts.append(f"memory_id={self.memory_id!r}") if self.user_id: parts.append(f"user_id={self.user_id!r}") - if self.thread_id: - parts.append(f"thread_id={self.thread_id!r}") detail = ", ".join(parts) if detail: return f"Memory not found ({detail})" diff --git a/azure/cosmos/agent_memory/models.py b/azure/cosmos/agent_memory/models.py index 0ff3b1e..b4eab25 100644 --- a/azure/cosmos/agent_memory/models.py +++ b/azure/cosmos/agent_memory/models.py @@ -29,6 +29,7 @@ model_validator, ) +from azure.cosmos.agent_memory._partitioning import DEFAULT_TENANT_ID from azure.cosmos.agent_memory.logging import get_logger logger = get_logger(__name__) @@ -167,6 +168,7 @@ class MemoryRecordBase(BaseModel): ) id: str = Field(default_factory=_uuid4_str) + tenant_id: str = DEFAULT_TENANT_ID user_id: str thread_id: str = Field(default_factory=_uuid4_str) role: Optional[MemoryRole] = None diff --git a/azure/cosmos/agent_memory/processors/inprocess.py b/azure/cosmos/agent_memory/processors/inprocess.py index e395516..b26cfe5 100644 --- a/azure/cosmos/agent_memory/processors/inprocess.py +++ b/azure/cosmos/agent_memory/processors/inprocess.py @@ -5,6 +5,7 @@ import time from typing import Any, Optional +from .._partitioning import DEFAULT_TENANT_ID from .base import ProcessThreadResult, UserSummaryResult @@ -13,7 +14,8 @@ class InProcessProcessor: This is the default backend. Wraps an existing :class:`azure.cosmos.agent_memory.services.pipeline.PipelineService` instance, - or constructs one from the supplied container / LLM / embeddings clients. + or constructs one from the supplied container / LLM / embeddings clients, + bound to ``tenant_id`` (``"default"`` when not given). """ def __init__( @@ -25,6 +27,7 @@ def __init__( summaries_container: Any = None, chat_client: Any = None, embeddings_client: Any = None, + tenant_id: str = DEFAULT_TENANT_ID, ) -> None: if pipeline is None: if ( @@ -51,8 +54,11 @@ def __init__( store = MemoryStore( containers=containers, embeddings_client=embeddings_client, + tenant_id=tenant_id, + ) + pipeline = PipelineService( + store, chat_client, embeddings_client, containers=containers, tenant_id=tenant_id ) - pipeline = PipelineService(store, chat_client, embeddings_client, containers=containers) self._pipeline = pipeline diff --git a/azure/cosmos/agent_memory/services/__init__.py b/azure/cosmos/agent_memory/services/__init__.py index 4dbf393..2135988 100644 --- a/azure/cosmos/agent_memory/services/__init__.py +++ b/azure/cosmos/agent_memory/services/__init__.py @@ -6,7 +6,10 @@ class MemoryStoreProtocol(Protocol): - """Persistence primitives consumed by the pipeline service.""" + """Persistence primitives consumed by the pipeline service. + + A ``partition_key`` is the owner's ``[tenant_id, user_id]``. + """ def query( self, diff --git a/azure/cosmos/agent_memory/services/_absorbed.py b/azure/cosmos/agent_memory/services/_absorbed.py index 2eb7c95..9994f52 100644 --- a/azure/cosmos/agent_memory/services/_absorbed.py +++ b/azure/cosmos/agent_memory/services/_absorbed.py @@ -11,69 +11,72 @@ retired for another reason (``"update"`` or ``"contradict"``, which earlier versions wrote) are earlier versions, not copies, and stay. -A user's memories sit in one partition per thread, so the records are looked up across the user's partitions and each -is deleted under its own thread. +An owner's records all sit in one partition, so the records are looked up and deleted there. """ from __future__ import annotations from typing import Any +from azure.cosmos.agent_memory._partitioning import OWNER_FILTER, owner_parameters, partition_key_for + ABSORBED_REASONS = ("duplicate", "procedure", "combined") # The memory types records are folded into: dedup and combining fold facts into facts (episodes are left alone), # and a procedure absorbs the statements it cites. ABSORBING_TYPES = frozenset({"fact", "procedural"}) -def absorbed_query(user_id: str, memory_id: str) -> tuple[str, list[dict[str, Any]]]: - """The records folded directly into ``memory_id`` (run across the user's partitions).""" +def absorbed_query(tenant_id: str, user_id: str, memory_id: str) -> tuple[str, list[dict[str, Any]]]: + """The records folded directly into ``memory_id`` (run in the owner's partition).""" names = [f"@reason_{i}" for i in range(len(ABSORBED_REASONS))] query = ( - "SELECT c.id, c.type, c.thread_id FROM c WHERE c.user_id = @user_id AND c.superseded_by = @memory_id " + f"SELECT c.id, c.type FROM c WHERE {OWNER_FILTER} AND c.superseded_by = @memory_id " f"AND c.supersede_reason IN ({', '.join(names)})" ) reasons = [{"name": name, "value": reason} for name, reason in zip(names, ABSORBED_REASONS)] - return query, [{"name": "@user_id", "value": user_id}, {"name": "@memory_id", "value": memory_id}, *reasons] + return query, [*owner_parameters(tenant_id, user_id), {"name": "@memory_id", "value": memory_id}, *reasons] -def delete_absorbed(container: Any, user_id: str, memory_id: str) -> list[dict[str, Any]]: +def delete_absorbed(container: Any, tenant_id: str, user_id: str, memory_id: str) -> list[dict[str, Any]]: """Delete everything folded into ``memory_id``, directly or through another record, deepest first, and return - it (``id``, ``type`` and ``thread_id``). Any failure but a record already gone is raised.""" + it (``id`` and ``type``). Any failure but a record already gone is raised.""" from azure.cosmos.exceptions import CosmosResourceNotFoundError + partition_key = partition_key_for(tenant_id, user_id) found: list[dict[str, Any]] = [] seen, pending = {memory_id}, [memory_id] while pending: - query, parameters = absorbed_query(user_id, pending.pop()) - for row in container.query_items(query=query, parameters=parameters, enable_cross_partition_query=True): + query, parameters = absorbed_query(tenant_id, user_id, pending.pop()) + for row in container.query_items(query=query, parameters=parameters, partition_key=partition_key): if row["id"] not in seen: seen.add(row["id"]) pending.append(row["id"]) found.append(row) for row in reversed(found): try: - container.delete_item(item=row["id"], partition_key=[user_id, row["thread_id"]]) + container.delete_item(item=row["id"], partition_key=partition_key) except CosmosResourceNotFoundError: continue return found -async def adelete_absorbed(container: Any, user_id: str, memory_id: str) -> list[dict[str, Any]]: +async def adelete_absorbed(container: Any, tenant_id: str, user_id: str, memory_id: str) -> list[dict[str, Any]]: """Async mirror of ``delete_absorbed``.""" from azure.cosmos.exceptions import CosmosResourceNotFoundError + partition_key = partition_key_for(tenant_id, user_id) found: list[dict[str, Any]] = [] seen, pending = {memory_id}, [memory_id] while pending: - query, parameters = absorbed_query(user_id, pending.pop()) - async for row in container.query_items(query=query, parameters=parameters): + query, parameters = absorbed_query(tenant_id, user_id, pending.pop()) + async for row in container.query_items(query=query, parameters=parameters, partition_key=partition_key): if row["id"] not in seen: seen.add(row["id"]) pending.append(row["id"]) found.append(row) for row in reversed(found): try: - await container.delete_item(item=row["id"], partition_key=[user_id, row["thread_id"]]) + await container.delete_item(item=row["id"], partition_key=partition_key) except CosmosResourceNotFoundError: continue return found diff --git a/azure/cosmos/agent_memory/services/_conflicts.py b/azure/cosmos/agent_memory/services/_conflicts.py index cc85d3e..4dba66a 100644 --- a/azure/cosmos/agent_memory/services/_conflicts.py +++ b/azure/cosmos/agent_memory/services/_conflicts.py @@ -6,10 +6,10 @@ nothing is retired. The pass links the pair instead, and ``search_cosmos`` returns each fact with the active facts it conflicts with (``conflicts_with``), so the agent sees both sides and can ask the user which is right. -A link is one small document in the user's memories container, in the user's ``__conflicts__`` partition. It holds the -IDs of the two facts and the kind, and no text. Its ID derives from the pair, so judging a pair again rewrites the same -document. Facts written by the assistant (``sys:agent-fact``) are never linked: they record what the agent said or -recommended, not what the user holds true. +A link is one small document in the owner's memories container, in the owner's partition, marked with the thread id +``__conflicts__``. It holds the IDs of the two facts and the kind, and no text. Its ID derives from the pair, so judging +a pair again rewrites the same document. Facts written by the assistant (``sys:agent-fact``) are never linked: they +record what the agent said or recommended, not what the user holds true. A link names the two facts as they were when it was written, and a later pass can retire either into another fact (a fold or a combine). The conflict follows the fact. When the pass that retires one of a pair is the pass that links it, @@ -26,6 +26,7 @@ from datetime import datetime, timezone from typing import Any, Awaitable, Callable, Iterable, Mapping, Optional, Sequence +from azure.cosmos.agent_memory._partitioning import OWNER_FILTER, owner_parameters, partition_key_for from azure.cosmos.agent_memory.logging import describe_exception, get_logger from azure.cosmos.agent_memory.services._dedup import CONFLICT_RELATIONS, Verdict, is_agent_sourced from azure.cosmos.agent_memory.services._pipeline_helpers import ID_SEED_SEP @@ -103,11 +104,14 @@ def conflict_link_id(user_id: str, pair: ConflictPair) -> str: return f"conflict_{hashlib.sha256(seed.encode()).hexdigest()[:32]}" -def conflict_link_body(user_id: str, pair: ConflictPair, *, now: Optional[datetime] = None) -> dict[str, Any]: +def conflict_link_body( + tenant_id: str, user_id: str, pair: ConflictPair, *, now: Optional[datetime] = None +) -> dict[str, Any]: """The document that links ``pair`` (written to the memories container, not through the memory store).""" return { "id": conflict_link_id(user_id, pair), "type": CONFLICT_LINK_TYPE, + "tenant_id": tenant_id, "user_id": user_id, "thread_id": CONFLICT_LINK_THREAD_ID, "first": pair.first, @@ -117,28 +121,28 @@ def conflict_link_body(user_id: str, pair: ConflictPair, *, now: Optional[dateti } -def links_query(user_id: str, fact_ids: Sequence[str]) -> tuple[str, list[dict[str, Any]]]: - """The links that touch any of ``fact_ids``; run it in the partition ``[user_id, CONFLICT_LINK_THREAD_ID]``.""" +def links_query(tenant_id: str, user_id: str, fact_ids: Sequence[str]) -> tuple[str, list[dict[str, Any]]]: + """The links that touch any of ``fact_ids``; run it in the owner's partition.""" query = ( - "SELECT c.first, c.later, c.kind FROM c WHERE c.user_id = @user_id AND c.type = @type " + f"SELECT c.first, c.later, c.kind FROM c WHERE {OWNER_FILTER} AND c.type = @type " "AND (ARRAY_CONTAINS(@ids, c.first) OR ARRAY_CONTAINS(@ids, c.later))" ) parameters = [ - {"name": "@user_id", "value": user_id}, + *owner_parameters(tenant_id, user_id), {"name": "@type", "value": CONFLICT_LINK_TYPE}, {"name": "@ids", "value": list(fact_ids)}, ] return query, parameters -def facts_query(user_id: str, fact_ids: Sequence[str]) -> tuple[str, list[dict[str, Any]]]: +def facts_query(tenant_id: str, user_id: str, fact_ids: Sequence[str]) -> tuple[str, list[dict[str, Any]]]: """The facts among ``fact_ids``, active or not, with what a result shows of a conflicting fact and where a retired - one went (``superseded_by``); run it across the user's partitions.""" + one went (``superseded_by``); run it in the owner's partition.""" query = ( "SELECT c.id, c.content, c.created_at, c.superseded_by FROM c " - "WHERE c.user_id = @user_id AND c.type = 'fact' AND ARRAY_CONTAINS(@ids, c.id)" + f"WHERE {OWNER_FILTER} AND c.type = 'fact' AND ARRAY_CONTAINS(@ids, c.id)" ) - parameters = [{"name": "@user_id", "value": user_id}, {"name": "@ids", "value": list(fact_ids)}] + parameters = [*owner_parameters(tenant_id, user_id), {"name": "@ids", "value": list(fact_ids)}] return query, parameters @@ -273,13 +277,14 @@ def _lookup_ids_by_user(docs: Iterable[Mapping[str, Any]]) -> dict[str, list[str def with_conflicts( - docs: Sequence[dict[str, Any]], query: Callable[..., Iterable[Mapping[str, Any]]] + docs: Sequence[dict[str, Any]], query: Callable[..., Iterable[Mapping[str, Any]]], tenant_id: str ) -> list[dict[str, Any]]: """``docs`` (search results) with the conflicts of each fact attached (``conflicts_with``). - ``query(sql, parameters, *, partition_key=None, cross_partition=False)`` runs a query on the memories container and - returns its rows. A search with no conflicts costs one query per user; with links, one more reads the facts they - name, and one more for each step a linked fact has since been retired through. + ``query(sql, parameters, *, partition_key)`` runs a query on the memories container, in that partition, and returns + its rows; every query reads one owner's partition, ``[tenant_id, user_id]``. A search with no conflicts costs one + query per user; with links, one more reads the facts they name, and one more for each step a linked fact has since + been retired through. Conflicts are context: a failed lookup is logged and ``docs`` come back as they were. """ ids_by_user = _lookup_ids_by_user(docs) @@ -289,15 +294,16 @@ def with_conflicts( links: list[Mapping[str, Any]] = [] active: dict[str, Mapping[str, Any]] = {} for user_id, fact_ids in ids_by_user.items(): - sql, parameters = links_query(user_id, fact_ids) - found = list(query(sql, parameters, partition_key=[user_id, CONFLICT_LINK_THREAD_ID])) + partition_key = partition_key_for(tenant_id, user_id) + sql, parameters = links_query(tenant_id, user_id, fact_ids) + found = list(query(sql, parameters, partition_key=partition_key)) if not found: continue links.extend(found) resolver = EndpointResolver(link_endpoints(found)) while wanted := resolver.next_ids(): - sql, parameters = facts_query(user_id, wanted) - resolver.add(query(sql, parameters, cross_partition=True)) + sql, parameters = facts_query(tenant_id, user_id, wanted) + resolver.add(query(sql, parameters, partition_key=partition_key)) active.update(resolver.resolved()) return attach_conflicts(docs, links, active) except Exception as exc: # noqa: BLE001 - conflicts must never break a search @@ -308,7 +314,7 @@ def with_conflicts( async def awith_conflicts( - docs: Sequence[dict[str, Any]], query: Callable[..., Awaitable[Iterable[Mapping[str, Any]]]] + docs: Sequence[dict[str, Any]], query: Callable[..., Awaitable[Iterable[Mapping[str, Any]]]], tenant_id: str ) -> list[dict[str, Any]]: """:func:`with_conflicts` for an async ``query``.""" ids_by_user = _lookup_ids_by_user(docs) @@ -318,15 +324,16 @@ async def awith_conflicts( links: list[Mapping[str, Any]] = [] active: dict[str, Mapping[str, Any]] = {} for user_id, fact_ids in ids_by_user.items(): - sql, parameters = links_query(user_id, fact_ids) - found = list(await query(sql, parameters, partition_key=[user_id, CONFLICT_LINK_THREAD_ID])) + partition_key = partition_key_for(tenant_id, user_id) + sql, parameters = links_query(tenant_id, user_id, fact_ids) + found = list(await query(sql, parameters, partition_key=partition_key)) if not found: continue links.extend(found) resolver = EndpointResolver(link_endpoints(found)) while wanted := resolver.next_ids(): - sql, parameters = facts_query(user_id, wanted) - resolver.add(await query(sql, parameters, cross_partition=True)) + sql, parameters = facts_query(tenant_id, user_id, wanted) + resolver.add(await query(sql, parameters, partition_key=partition_key)) active.update(resolver.resolved()) return attach_conflicts(docs, links, active) except Exception as exc: # noqa: BLE001 - conflicts must never break a search diff --git a/azure/cosmos/agent_memory/services/_dedup.py b/azure/cosmos/agent_memory/services/_dedup.py index 6e8fd7b..b6ba88f 100644 --- a/azure/cosmos/agent_memory/services/_dedup.py +++ b/azure/cosmos/agent_memory/services/_dedup.py @@ -32,6 +32,7 @@ from datetime import datetime, timezone from typing import Any, Callable, Mapping, Optional, Sequence +from azure.cosmos.agent_memory._partitioning import OWNER_FILTER, owner_parameters from azure.cosmos.agent_memory._utils import cosine_similarity from azure.cosmos.agent_memory.exceptions import ValidationError from azure.cosmos.agent_memory.models import AGENT_FACT_TAG, MAX_TAGS_PER_RECORD, USER_ONLY_ASSERTIONS @@ -40,7 +41,7 @@ DEDUP_PROMPT = "dedup_verify.prompty" DEDUP_CURSOR_TYPE = "dedup_cursor" -# The cursor is user-wide, so it lives under a sentinel thread id like the user summary does. +# The cursor is user-wide, so it carries a marker thread id like the user summary does. DEDUP_CURSOR_THREAD_ID = "__dedup__" # A fold is one write per retired fact after its survivor's, and the survivor lists them all in # ``merged_from``: bound both for one pass. @@ -128,13 +129,18 @@ def dedup_cursor_id(user_id: str, memory_type: str) -> str: def dedup_cursor_body( - existing: Optional[Mapping[str, Any]], user_id: str, memory_type: str, position: Mapping[str, Any] + tenant_id: str, + existing: Optional[Mapping[str, Any]], + user_id: str, + memory_type: str, + position: Mapping[str, Any], ) -> dict[str, Any]: body = without_system_fields(existing) body.update( { "id": dedup_cursor_id(user_id, memory_type), "type": DEDUP_CURSOR_TYPE, + "tenant_id": tenant_id, "user_id": user_id, "thread_id": DEDUP_CURSOR_THREAD_ID, "last_ts": position["ts"], @@ -159,30 +165,31 @@ def position_parameters(position: Mapping[str, Any]) -> list[dict[str, Any]]: def unchecked_memories_query( - user_id: str, memory_type: str, existing_cursor: Optional[Mapping[str, Any]], top: int + tenant_id: str, user_id: str, memory_type: str, existing_cursor: Optional[Mapping[str, Any]], top: int ) -> tuple[str, list[dict[str, Any]]]: - """The user's active ``memory_type`` memories written after the cursor, oldest first.""" + """The owner's active ``memory_type`` memories written after the cursor, oldest first.""" query = ( - f"SELECT TOP {top} * FROM c WHERE c.user_id = @user_id AND c.type = @memory_type AND {ACTIVE_FILTER}" - + AFTER_POSITION + f"SELECT TOP {top} * FROM c WHERE {OWNER_FILTER} AND c.type = @memory_type AND {ACTIVE_FILTER}" + AFTER_POSITION ) parameters = [ - {"name": "@user_id", "value": user_id}, + *owner_parameters(tenant_id, user_id), {"name": "@memory_type", "value": memory_type}, *position_parameters(checkpoint_position(existing_cursor)), ] return query, parameters -def neighbor_query(user_id: str, memory_type: str, seed: Mapping[str, Any]) -> tuple[str, list[dict[str, Any]]]: - """The seed's nearest active memories of the same type for the same user.""" +def neighbor_query( + tenant_id: str, user_id: str, memory_type: str, seed: Mapping[str, Any] +) -> tuple[str, list[dict[str, Any]]]: + """The seed's nearest active memories of the same type for the same owner.""" query = ( - f"SELECT TOP {DEDUP_MAX_NEIGHBORS} * FROM c WHERE c.user_id = @user_id AND c.type = @memory_type " + f"SELECT TOP {DEDUP_MAX_NEIGHBORS} * FROM c WHERE {OWNER_FILTER} AND c.type = @memory_type " f"AND {ACTIVE_FILTER} AND c.id != @seed_id AND IS_DEFINED(c.embedding) " "ORDER BY VectorDistance(c.embedding, @embedding)" ) parameters = [ - {"name": "@user_id", "value": user_id}, + *owner_parameters(tenant_id, user_id), {"name": "@memory_type", "value": memory_type}, {"name": "@seed_id", "value": seed["id"]}, {"name": "@embedding", "value": seed["embedding"]}, diff --git a/azure/cosmos/agent_memory/services/_extraction_context.py b/azure/cosmos/agent_memory/services/_extraction_context.py index 1cf6683..1a0e5ca 100644 --- a/azure/cosmos/agent_memory/services/_extraction_context.py +++ b/azure/cosmos/agent_memory/services/_extraction_context.py @@ -15,6 +15,7 @@ from typing import AbstractSet, Any, Iterable, Mapping, Optional, Sequence from azure.cosmos.agent_memory._embedding_tokens import count_tokens +from azure.cosmos.agent_memory._partitioning import OWNER_FILTER, owner_parameters from azure.cosmos.agent_memory.models import FACT_ASSERTIONS, USER_ONLY_ASSERTIONS, FactAssertion from azure.cosmos.agent_memory.services._dedup import is_agent_sourced from azure.cosmos.agent_memory.services._pipeline_helpers import build_transcript @@ -96,6 +97,7 @@ def window_write_second(turns: Iterable[Mapping[str, Any]], start: Optional[str] def previous_turns_query( + tenant_id: str, user_id: str, thread_id: str, before: str, @@ -115,11 +117,11 @@ def previous_turns_query( earlier = f"({earlier} OR (c.created_at = @before AND c._ts < @before_ts))" query = ( f"SELECT TOP {EXTRACTION_CONTEXT_TURNS} c.id, c.role, c.content, c.created_at, c._ts FROM c " - f"WHERE c.user_id = @user_id AND c.thread_id = @thread_id AND c.type = 'turn' AND {earlier} " + f"WHERE {OWNER_FILTER} AND c.thread_id = @thread_id AND c.type = 'turn' AND {earlier} " "ORDER BY c.created_at DESC" ) parameters = [ - {"name": "@user_id", "value": user_id}, + *owner_parameters(tenant_id, user_id), {"name": "@thread_id", "value": thread_id}, {"name": "@before", "value": before}, ] @@ -193,21 +195,22 @@ def query_text(batch: Sequence[Mapping[str, Any]]) -> str: def known_facts_query( + tenant_id: str, user_id: str, vector: list[float], before: Optional[str], active_filter: str, ) -> tuple[str, list[dict[str, Any]]]: - """The user's active facts nearest ``vector``, written no later than ``before`` (an event time).""" + """The owner's active facts nearest ``vector``, written no later than ``before`` (an event time).""" window = " AND c.created_at <= @before" if before else "" query = ( f"SELECT TOP {EXTRACTION_KNOWN_FACTS} c.id, c.content, c.created_at, c.tags, c.metadata.source AS source, " "c.assertion, c.subject, c.attribute, c.entities FROM c " - f"WHERE c.user_id = @user_id AND c.type = @fact_type AND {active_filter} " + f"WHERE {OWNER_FILTER} AND c.type = @fact_type AND {active_filter} " f"AND IS_DEFINED(c.embedding){window} ORDER BY VectorDistance(c.embedding, @embedding)" ) parameters = [ - {"name": "@user_id", "value": user_id}, + *owner_parameters(tenant_id, user_id), {"name": "@fact_type", "value": "fact"}, {"name": "@embedding", "value": vector}, ] diff --git a/azure/cosmos/agent_memory/services/_procedures.py b/azure/cosmos/agent_memory/services/_procedures.py index 92f3b97..342fb33 100644 --- a/azure/cosmos/agent_memory/services/_procedures.py +++ b/azure/cosmos/agent_memory/services/_procedures.py @@ -32,6 +32,7 @@ from datetime import datetime, timezone from typing import Any, Iterable, Mapping, Optional, Sequence +from azure.cosmos.agent_memory._partitioning import OWNER_FILTER, owner_parameters, partition_key_for from azure.cosmos.agent_memory.models import FACT_ASSERTIONS, USER_ONLY_ASSERTIONS, ProcedureEvidence, ProcedureKind from azure.cosmos.agent_memory.services._dedup import ( ACTIVE_FILTER, @@ -85,26 +86,27 @@ def is_transient_write_failure(exc: BaseException) -> bool: @dataclass(frozen=True) class ProcedureScope: - """One user's procedure data: what selects their memories, and where their procedures live.""" + """One owner's procedure data: what selects their memories, and where their procedures live.""" + tenant_id: str user_id: str @property def predicate(self) -> str: - return "c.user_id = @uid" + return OWNER_FILTER @property def parameters(self) -> list[dict[str, Any]]: - return [{"name": "@uid", "value": self.user_id}] + return owner_parameters(self.tenant_id, self.user_id) @property def partition_key(self) -> list[str]: - """Where procedures and the procedure cursor are stored (a point read or write).""" - return [self.user_id, PROCEDURAL_THREAD_ID] + """The owner's partition: their memories, procedures and the procedure cursor are all stored in it.""" + return partition_key_for(self.tenant_id, self.user_id) @property def fields(self) -> dict[str, str]: - return {"user_id": self.user_id, "thread_id": PROCEDURAL_THREAD_ID} + return {"tenant_id": self.tenant_id, "user_id": self.user_id, "thread_id": PROCEDURAL_THREAD_ID} # ---------------------------------------------------------------- shared helpers @@ -557,10 +559,11 @@ def _content_fields(item: Mapping[str, Any], name: str) -> dict[str, Any]: return fields -def new_procedure(answer: ProcedureAnswer, *, user_id: str, now: str) -> dict[str, Any]: +def new_procedure(answer: ProcedureAnswer, *, tenant_id: str, user_id: str, now: str) -> dict[str, Any]: """A new candidate procedure from an ``add`` answer, with no support yet.""" return { "id": procedure_id(user_id, answer.kind, answer.name), + "tenant_id": tenant_id, "user_id": user_id, "thread_id": PROCEDURAL_THREAD_ID, "type": "procedural", diff --git a/azure/cosmos/agent_memory/services/pipeline.py b/azure/cosmos/agent_memory/services/pipeline.py index 8f9b020..64bf228 100644 --- a/azure/cosmos/agent_memory/services/pipeline.py +++ b/azure/cosmos/agent_memory/services/pipeline.py @@ -28,6 +28,14 @@ from azure.cosmos.agent_memory import thresholds as threshold_config from azure.cosmos.agent_memory._container_routing import ContainerKey from azure.cosmos.agent_memory._curation import mark_secret, sanitize_record, sanitize_text +from azure.cosmos.agent_memory._partitioning import ( + DEFAULT_TENANT_ID, + OWNER_FILTER, + owner_parameters, + partition_key_for, + resolve_tenant_id, + stamp_scope, +) from azure.cosmos.agent_memory._utils import ( DEFAULT_TTL_BY_TYPE, compute_content_hash, @@ -65,7 +73,6 @@ ) from azure.cosmos.agent_memory.services._conflicts import conflict_link_body, conflict_pairs from azure.cosmos.agent_memory.services._dedup import ( - DEDUP_CURSOR_THREAD_ID, DEDUP_CURSOR_TYPE, DEDUP_PROMPT, Verdict, @@ -277,7 +284,11 @@ def replace_item(self, **kwargs: Any) -> Any: class PipelineService: - """LLM orchestration service over the injected containers, memory store and model clients.""" + """LLM orchestration service over the injected containers, memory store and model clients. + + The service is bound to one tenant (``tenant_id``): every record it reads or writes is in the partition + ``[tenant_id, user_id]`` of its owner, and every query it sends filters on the tenant. + """ def __init__( self, @@ -288,7 +299,9 @@ def __init__( *, containers: dict[ContainerKey, Any], transcript_metadata_keys: Optional[Iterable[str]] = None, + tenant_id: str = DEFAULT_TENANT_ID, ) -> None: + self._tenant_id = resolve_tenant_id(tenant_id) self._store = store self._containers = containers self._memories_container = containers[ContainerKey.MEMORIES] @@ -366,64 +379,12 @@ def _build_transcript( include_timestamp=include_timestamp, ) - def _query_active_memories( - self, - user_id: str, - memory_type: str, - *, - limit: int | None = None, - tagged_only: bool = False, - ) -> list[dict[str, Any]]: - top_clause = f"TOP {top_literal(limit, name='_query_active_memories.limit')} " if limit else "" - tag_clause = "AND ARRAY_CONTAINS(c.tags, @tag) " if tagged_only else "" - query = ( - f"SELECT {top_clause}* FROM c WHERE c.user_id = @user_id " - "AND c.type = @memory_type " - f"AND {_ACTIVE_DOC_FILTER} " - f"{tag_clause}" - "ORDER BY c.created_at DESC" - ) - parameters = [ - {"name": "@user_id", "value": user_id}, - {"name": "@memory_type", "value": memory_type}, - ] - if tagged_only: - parameters.append({"name": "@tag", "value": "sys:dup-candidate"}) - return list( - self._memories_container.query_items( - query=query, - parameters=parameters, - enable_cross_partition_query=True, - ) - ) - - def _load_memories_by_ids(self, user_id: str, memory_type: str, ids: Iterable[str]) -> list[dict[str, Any]]: - ids = [mid for mid in dict.fromkeys(ids) if mid] - if not ids: - return [] - placeholders = ", ".join(f"@id{i}" for i in range(len(ids))) - parameters = [ - {"name": "@user_id", "value": user_id}, - {"name": "@memory_type", "value": memory_type}, - ] - parameters.extend({"name": f"@id{i}", "value": mid} for i, mid in enumerate(ids)) - query = ( - "SELECT * FROM c WHERE c.user_id = @user_id " - "AND c.type = @memory_type " - f"AND c.id IN ({placeholders}) " - f"AND {_ACTIVE_DOC_FILTER}" - ) - return list( - self._memories_container.query_items( - query=query, - parameters=parameters, - enable_cross_partition_query=True, - ) - ) - def _sanitized_body(self, doc: dict[str, Any]) -> dict[str, Any]: - """Copy ``doc`` with literal credentials redacted, ready for a direct container write.""" - body = dict(doc) + """Copy ``doc`` with literal credentials redacted and the tenant stamped, ready for a direct container write. + + A document that names another tenant is refused: the service writes only into its own. + """ + body = stamp_scope(doc, self._tenant_id) redacted = sanitize_record(body) if redacted: logger.warning("redacted literal secrets before write id=%s patterns=%s", body.get("id"), redacted) @@ -553,19 +514,19 @@ def extract_memories_durable( if turns is None: query = ( - "SELECT * FROM c WHERE c.user_id = @user_id " + f"SELECT * FROM c WHERE {OWNER_FILTER} " "AND c.thread_id = @thread_id AND c.type = 'turn' " "AND (NOT IS_DEFINED(c.extracted_at) OR IS_NULL(c.extracted_at))" ) parameters: list[dict[str, Any]] = [ - {"name": "@user_id", "value": user_id}, + *owner_parameters(self._tenant_id, user_id), {"name": "@thread_id", "value": thread_id}, ] items = list( self._turns_container.query_items( query=query, parameters=parameters, - partition_key=[user_id, thread_id], + partition_key=partition_key_for(self._tenant_id, user_id), ) ) else: @@ -694,6 +655,7 @@ def extract_memories_durable( source_turn_ids = ground_fact_sources(fact, turn_ids=batch_turn_ids, labels=batch_labels) doc: dict[str, Any] = { "id": det_id, + "tenant_id": self._tenant_id, "user_id": user_id, "thread_id": thread_id, "role": "system", @@ -785,11 +747,10 @@ def _extraction_window_context( return [], NONE window_ts = window_write_second(items, window_start) prior: list[dict[str, Any]] = [] + partition_key = partition_key_for(self._tenant_id, user_id) try: - query, parameters = previous_turns_query(user_id, thread_id, window_start, window_ts) - rows = self._turns_container.query_items( - query=query, parameters=parameters, partition_key=[user_id, thread_id] - ) + query, parameters = previous_turns_query(self._tenant_id, user_id, thread_id, window_start, window_ts) + rows = self._turns_container.query_items(query=query, parameters=parameters, partition_key=partition_key) prior = prior_turns(rows, items) except Exception as exc: # noqa: BLE001 logger.warning( @@ -801,7 +762,7 @@ def _extraction_window_context( summary = NONE try: summary_doc = self._summaries_container.read_item( - item=f"summary_{user_id}_{thread_id}", partition_key=[user_id, thread_id] + item=f"summary_{user_id}_{thread_id}", partition_key=partition_key ) summary = summary_text(summary_doc, window_start, window_ts) except CosmosResourceNotFoundError: @@ -822,11 +783,11 @@ def _known_memories(self, user_id: str, batch: list[dict[str, Any]]) -> str: return NONE try: query, parameters = known_facts_query( - user_id, self._embed_one(text), latest_created_at(batch), _ACTIVE_DOC_FILTER + self._tenant_id, user_id, self._embed_one(text), latest_created_at(batch), _ACTIVE_DOC_FILTER ) rows = list( self._memories_container.query_items( - query=query, parameters=parameters, enable_cross_partition_query=True + query=query, parameters=parameters, partition_key=partition_key_for(self._tenant_id, user_id) ) ) except Exception as exc: # noqa: BLE001 @@ -975,6 +936,7 @@ def _build_episode_docs( EpisodicRecord, { "id": self._deterministic_episode_id(segment_key, index), + "tenant_id": self._tenant_id, "user_id": user_id, "thread_id": thread_id, "role": "system", @@ -1033,7 +995,7 @@ def _read_episode_cursor(self, user_id: str, thread_id: str) -> tuple[str, str]: try: doc = self._memories_container.read_item( item=self._episode_cursor_id(user_id, thread_id), - partition_key=[user_id, thread_id], + partition_key=partition_key_for(self._tenant_id, user_id), ) except CosmosResourceNotFoundError: return "", "" @@ -1057,7 +1019,7 @@ def _advance_episode_cursor(self, user_id: str, thread_id: str, last_turn: dict[ if not last_at: return cursor_id = self._episode_cursor_id(user_id, thread_id) - partition_key = [user_id, thread_id] + partition_key = partition_key_for(self._tenant_id, user_id) for _ in range(3): etag: Optional[str] = None try: @@ -1075,6 +1037,7 @@ def _advance_episode_cursor(self, user_id: str, thread_id: str, last_turn: dict[ body = { "id": cursor_id, "type": "episode_cursor", + "tenant_id": self._tenant_id, "user_id": user_id, "thread_id": thread_id, "last_episode_at": last_at, @@ -1107,7 +1070,7 @@ def _load_open_episode_segment(self, user_id: str, thread_id: str) -> list[dict[ """ last_at, last_id = self._read_episode_cursor(user_id, thread_id) query = ( - "SELECT * FROM c WHERE c.user_id = @user_id " + f"SELECT * FROM c WHERE {OWNER_FILTER} " "AND c.thread_id = @thread_id AND c.type = 'turn' " "AND (c.created_at > @last_at " "OR (c.created_at = @last_at AND c.id > @last_id))" @@ -1115,14 +1078,14 @@ def _load_open_episode_segment(self, user_id: str, thread_id: str) -> list[dict[ parameters: list[dict[str, Any]] = [ {"name": "@last_at", "value": last_at}, {"name": "@last_id", "value": last_id}, - {"name": "@user_id", "value": user_id}, + *owner_parameters(self._tenant_id, user_id), {"name": "@thread_id", "value": thread_id}, ] items = list( self._turns_container.query_items( query=query, parameters=parameters, - partition_key=[user_id, thread_id], + partition_key=partition_key_for(self._tenant_id, user_id), ) ) items.sort(key=created_at_sort_key) @@ -1285,8 +1248,8 @@ def persist_extracted_memories( raise ValidationError("extracted must be a dict") result = self._empty_extract_counts() - fact_docs = [dict(doc) for doc in extracted.get("facts", [])] - episodic_docs = [dict(doc) for doc in extracted.get("episodic", [])] + fact_docs = [stamp_scope(doc, self._tenant_id) for doc in extracted.get("facts", [])] + episodic_docs = [stamp_scope(doc, self._tenant_id) for doc in extracted.get("episodic", [])] update_ops = [dict(op) for op in extracted.get("updates", [])] docs_to_create = fact_docs + episodic_docs @@ -1361,7 +1324,7 @@ def _mark_turns_extracted(self, turn_docs: list[dict[str, Any]]) -> int: try: self._turns_container.patch_item( item=turn_id, - partition_key=[turn.get("user_id"), turn.get("thread_id")], + partition_key=partition_key_for(self._tenant_id, turn.get("user_id")), patch_operations=[{"op": "set", "path": "/extracted_at", "value": now_iso}], ) marked += 1 @@ -1458,10 +1421,10 @@ def synthesize_procedural( logger.info("synthesize_procedural extraction started user_id=%s", user_id) - scope = ProcedureScope(user_id) + scope = ProcedureScope(self._tenant_id, user_id) cursor = self._read_procedure_cursor(scope) - facts_read = self._query_user_memories(*behavioral_facts_query(scope, cursor)) - episodes_read = self._query_user_memories(*lesson_episodes_query(scope, cursor)) + facts_read = self._query_procedures(scope, *behavioral_facts_query(scope, cursor)) + episodes_read = self._query_procedures(scope, *lesson_episodes_query(scope, cursor)) batches = source_batches(facts_read, episodes_read) if not any(sources for sources, _, _ in batches): self._advance_procedure_cursor(scope, cursor, facts_read, episodes_read) @@ -1621,7 +1584,9 @@ def _apply_procedure_answer( def _create_procedure( self, user_id: str, answer: ProcedureAnswer, now: str ) -> tuple[str, Optional[dict[str, Any]]]: - created = with_support(new_procedure(answer, user_id=user_id, now=now), answer.sources, answer.evidence) + created = with_support( + new_procedure(answer, tenant_id=self._tenant_id, user_id=user_id, now=now), answer.sources, answer.evidence + ) if created is None: return "skipped", None created.update(self._prompt_lineage("extract_procedure.prompty")) @@ -1691,16 +1656,10 @@ def _read_procedure(self, scope: ProcedureScope, doc_id: str) -> Optional[dict[s return None return doc if doc.get("type") == "procedural" and not doc.get("superseded_by") else None - def _query_user_memories(self, query: str, parameters: list[dict[str, Any]]) -> list[dict[str, Any]]: - """Run ``query`` over all of the user's memories, which span their threads' partitions.""" - return list( - self._memories_container.query_items(query=query, parameters=parameters, enable_cross_partition_query=True) - ) - def _query_procedures( self, scope: ProcedureScope, query: str, parameters: list[dict[str, Any]] ) -> list[dict[str, Any]]: - """Run ``query`` over the user's procedures, which all share one partition.""" + """Run ``query`` in the owner's partition, where their memories, procedures and procedure cursor all live.""" return list( self._memories_container.query_items(query=query, parameters=parameters, partition_key=scope.partition_key) ) @@ -1784,15 +1743,16 @@ def generate_thread_summary_durable( logger.info("generate_thread_summary_durable started user_id=%s thread_id=%s", user_id, thread_id) summary_id = f"summary_{user_id}_{thread_id}" + partition_key = partition_key_for(self._tenant_id, user_id) existing_summary: Optional[dict[str, Any]] = None try: - existing_summary = self._summaries_container.read_item(item=summary_id, partition_key=[user_id, thread_id]) + existing_summary = self._summaries_container.read_item(item=summary_id, partition_key=partition_key) except CosmosResourceNotFoundError: pass - query = "SELECT * FROM c WHERE c.user_id = @user_id AND c.thread_id = @thread_id AND c.type = 'turn'" + query = f"SELECT * FROM c WHERE {OWNER_FILTER} AND c.thread_id = @thread_id AND c.type = 'turn'" parameters: list[dict[str, Any]] = [ - {"name": "@user_id", "value": user_id}, + *owner_parameters(self._tenant_id, user_id), {"name": "@thread_id", "value": thread_id}, ] if existing_summary: @@ -1804,7 +1764,7 @@ def generate_thread_summary_durable( self._turns_container.query_items( query=query, parameters=parameters, - partition_key=[user_id, thread_id], + partition_key=partition_key, ) ) @@ -1842,6 +1802,7 @@ def generate_thread_summary_durable( doc_timestamp = self._stable_source_timestamp(items) summary_doc: dict[str, Any] = { "id": summary_id, + "tenant_id": self._tenant_id, "user_id": user_id, "thread_id": thread_id, "role": "system", @@ -1875,7 +1836,7 @@ def persist_thread_summary( if not isinstance(summary_doc, dict): raise ValidationError("summary_doc must be a dict") - doc = dict(summary_doc) + doc = stamp_scope(summary_doc, self._tenant_id) doc["id"] = doc.get("id") or f"summary_{user_id}_{thread_id}" doc["user_id"] = user_id doc["thread_id"] = thread_id @@ -1921,17 +1882,15 @@ def generate_user_summary_durable( ) user_summary_id = f"user_summary_{user_id}" + partition_key = partition_key_for(self._tenant_id, user_id) existing_summary: Optional[dict[str, Any]] = None try: - existing_summary = self._summaries_container.read_item( - item=user_summary_id, - partition_key=[user_id, "__user_summary__"], - ) + existing_summary = self._summaries_container.read_item(item=user_summary_id, partition_key=partition_key) except CosmosResourceNotFoundError: pass - query_predicate = "c.user_id = @user_id" - parameters: list[dict[str, Any]] = [{"name": "@user_id", "value": user_id}] + query_predicate = OWNER_FILTER + parameters: list[dict[str, Any]] = owner_parameters(self._tenant_id, user_id) if existing_summary: since = existing_summary["updated_at"] query_predicate += " AND c.created_at > @since" @@ -1944,14 +1903,14 @@ def generate_user_summary_durable( self._memories_container.query_items( query=memories_query, parameters=parameters, - enable_cross_partition_query=True, + partition_key=partition_key, ) ) items.extend( self._summaries_container.query_items( query=summaries_query, parameters=parameters, - enable_cross_partition_query=True, + partition_key=partition_key, ) ) @@ -2001,6 +1960,7 @@ def generate_user_summary_durable( doc_timestamp = self._stable_source_timestamp(items) summary_doc: dict[str, Any] = { "id": user_summary_id, + "tenant_id": self._tenant_id, "user_id": user_id, "thread_id": "__user_summary__", "role": "system", @@ -2033,7 +1993,7 @@ def persist_user_summary( if not isinstance(user_summary_doc, dict): raise ValidationError("user_summary_doc must be a dict") - doc = dict(user_summary_doc) + doc = stamp_scope(user_summary_doc, self._tenant_id) doc["id"] = doc.get("id") or f"user_summary_{user_id}" doc["user_id"] = user_id doc["thread_id"] = "__user_summary__" @@ -2180,10 +2140,12 @@ def consolidate_memories( logger.info("consolidate_memories started user_id=%s n=%d memory_type=%s", user_id, n, memory_type) cursor = self._read_dedup_cursor(user_id, memory_type) query, parameters = unchecked_memories_query( - user_id, memory_type, cursor, top_literal(n, name="consolidate_memories.n") + self._tenant_id, user_id, memory_type, cursor, top_literal(n, name="consolidate_memories.n") ) seeds = list( - self._memories_container.query_items(query=query, parameters=parameters, enable_cross_partition_query=True) + self._memories_container.query_items( + query=query, parameters=parameters, partition_key=partition_key_for(self._tenant_id, user_id) + ) ) checked: list[tuple[dict[str, Any], list[Verdict]]] = [] @@ -2265,9 +2227,11 @@ def _dedup_candidates( ``COMBINE_SIMILARITY_FLOOR`` it could be combined with; none without an embedding.""" if not isinstance(seed.get("embedding"), list) or not seed["embedding"]: return [] - query, parameters = neighbor_query(user_id, memory_type, seed) + query, parameters = neighbor_query(self._tenant_id, user_id, memory_type, seed) neighbors = list( - self._memories_container.query_items(query=query, parameters=parameters, enable_cross_partition_query=True) + self._memories_container.query_items( + query=query, parameters=parameters, partition_key=partition_key_for(self._tenant_id, user_id) + ) ) return comparable_candidates(seed, neighbors) if combine else close_candidates(seed, neighbors) @@ -2303,7 +2267,7 @@ def _verify_duplicates(self, seed: dict[str, Any], candidates: list[tuple[dict[s def _read_dedup_cursor(self, user_id: str, memory_type: str) -> Optional[dict[str, Any]]: try: doc = self._memories_container.read_item( - item=dedup_cursor_id(user_id, memory_type), partition_key=[user_id, DEDUP_CURSOR_THREAD_ID] + item=dedup_cursor_id(user_id, memory_type), partition_key=partition_key_for(self._tenant_id, user_id) ) except CosmosResourceNotFoundError: return None @@ -2325,7 +2289,7 @@ def _link_conflicts( written = 0 for pair in conflict_pairs(checked, absorbed=absorbed): try: - self._memories_container.upsert_item(body=conflict_link_body(user_id, pair)) + self._memories_container.upsert_item(body=conflict_link_body(self._tenant_id, user_id, pair)) written += 1 except Exception as exc: # noqa: BLE001 - a link is best effort logger.warning( @@ -2348,7 +2312,7 @@ def _advance_dedup_cursor( position = next_dedup_cursor(existing, checked) if position is None: return - body = dedup_cursor_body(existing, user_id, memory_type, position) + body = dedup_cursor_body(self._tenant_id, existing, user_id, memory_type, position) try: if existing is None: self._memories_container.create_item(body=body) @@ -2505,7 +2469,7 @@ def _members_unchanged(self, members: list[dict[str, Any]]) -> bool: for doc in members: try: current = self._memories_container.read_item( - item=doc["id"], partition_key=[doc["user_id"], doc["thread_id"]] + item=doc["id"], partition_key=partition_key_for(self._tenant_id, doc["user_id"]) ) except CosmosResourceNotFoundError: return False @@ -2527,7 +2491,7 @@ def _commit_combine(self, record: dict[str, Any], members: list[dict[str, Any]]) except CosmosResourceExistsError: try: existing = self._memories_container.read_item( - item=record["id"], partition_key=[record["user_id"], record["thread_id"]] + item=record["id"], partition_key=partition_key_for(self._tenant_id, record["user_id"]) ) except CosmosResourceNotFoundError: return None @@ -2552,7 +2516,7 @@ def build_procedural_context(self, user_id: str, task: Optional[str] = None) -> """ if not user_id: raise ValidationError("user_id is required") - scope = ProcedureScope(user_id) + scope = ProcedureScope(self._tenant_id, user_id) today = utc_today() standing, left_out = standing_rules(self._query_procedures(scope, *standing_rules_query(scope, today)), today) if left_out: diff --git a/azure/cosmos/agent_memory/store/_search_helpers.py b/azure/cosmos/agent_memory/store/_search_helpers.py index 4c7dc36..008b8e5 100644 --- a/azure/cosmos/agent_memory/store/_search_helpers.py +++ b/azure/cosmos/agent_memory/store/_search_helpers.py @@ -12,11 +12,12 @@ from datetime import datetime, timezone from typing import Any, Optional +from azure.cosmos.agent_memory._partitioning import partition_key_for from azure.cosmos.agent_memory._query_builder import _QueryBuilder from azure.cosmos.agent_memory.exceptions import ConfigurationError, ValidationError MEMORY_PROJECTION = ( - "c.id, c.user_id, c.thread_id, c.role, c.type, c.content, " + "c.id, c.tenant_id, c.user_id, c.thread_id, c.role, c.type, c.content, " "c.metadata, c.created_at, c.tags, c.salience, c.confidence, " "c.name, c.summary, c.procedure_kind, c.applies, c.status, c.valid_until, c.activation_conditions, c.steps, " "c.title, c.started_at, c.ended_at, c.participants, c.events, " @@ -115,17 +116,20 @@ def uses_full_text_score(query: str) -> bool: return _FULL_TEXT_SCORE_CALL.search(query) is not None -def query_scope(user_id: Optional[str], thread_id: Optional[str], keyword_count: int = 0) -> tuple[Any, bool]: +def query_scope(tenant_id: str, user_id: Optional[str], keyword_count: int = 0) -> tuple[Optional[list[str]], bool]: """Return ``(partition_key, needs_cross_partition)`` for a read. + A read that names the owner stays in the owner's partition ``[tenant_id, user_id]``, whatever thread it asks about. + A read that does not name the owner spans the owners of the tenant, so it runs cross-partition. + A search with keywords (``keyword_count`` > 0) ranks with ``FullTextScore``. The Python SDK runs a query sent with a partition key without planning it, and Cosmos DB then ignores the ranking: every question gets the same fixed order - (Azure/azure-sdk-for-python#42241). Such a search therefore runs cross-partition: the ``c.user_id`` and - ``c.thread_id`` filters in its ``WHERE`` clause confine it to the records the key would have read. A vector-only + (Azure/azure-sdk-for-python#42241). Such a search therefore runs cross-partition: the ``c.tenant_id`` and + ``c.user_id`` filters in its ``WHERE`` clause confine it to the records the key would have read. A vector-only search ranks correctly either way and keeps the key. """ - if user_id is not None and thread_id is not None and not keyword_count: - return [user_id, thread_id], False + if user_id is not None and not keyword_count: + return partition_key_for(tenant_id, user_id), False return None, True diff --git a/azure/cosmos/agent_memory/store/memory_store.py b/azure/cosmos/agent_memory/store/memory_store.py index 009f294..8fa078d 100644 --- a/azure/cosmos/agent_memory/store/memory_store.py +++ b/azure/cosmos/agent_memory/store/memory_store.py @@ -7,7 +7,6 @@ from azure.cosmos.agent_memory._container_routing import ( _CONTAINER_FOR_TYPE, - USER_SCOPED_MEMORIES_TYPES, ContainerKey, container_key_for_type, ) @@ -19,6 +18,15 @@ sanitize_record, sanitize_text, ) +from azure.cosmos.agent_memory._partitioning import ( + DEFAULT_TENANT_ID, + OWNER_FILTER, + owner_parameters, + partition_key_for, + resolve_tenant_id, + stamp_scope, + validate_owner_id, +) from azure.cosmos.agent_memory._query_builder import _QueryBuilder from azure.cosmos.agent_memory._utils import ( _build_memory_query_builder, @@ -65,6 +73,7 @@ # ``embedding`` to keep the vector off the wire and out of the result. _TURN_PROJECTION_FIELDS: tuple[str, ...] = ( "id", + "tenant_id", "user_id", "thread_id", "role", @@ -97,7 +106,11 @@ def _wrap_cosmos_exception(exc: BaseException, *, message: str) -> CosmosOperati class MemoryStore: - """Typed CRUD and query primitives over the Cosmos DB containers.""" + """Typed CRUD and query primitives over the Cosmos DB containers. + + A store is bound to one tenant: every query it builds filters on it, every point operation addresses the + partition ``[tenant_id, user_id]``, and every document it writes carries it. + """ def __init__( self, @@ -105,6 +118,7 @@ def __init__( containers: dict[ContainerKey, Any], embeddings_client: Any = None, enable_turn_embeddings: bool = False, + tenant_id: str = DEFAULT_TENANT_ID, ) -> None: self._containers = containers self._turns_container = containers[ContainerKey.TURNS] @@ -112,6 +126,12 @@ def __init__( self._summaries_container = containers[ContainerKey.SUMMARIES] self._embeddings_client = embeddings_client self._enable_turn_embeddings = enable_turn_embeddings + self._tenant_id = resolve_tenant_id(tenant_id) + + @property + def tenant_id(self) -> str: + """The tenant this store reads and writes.""" + return self._tenant_id @property def container(self) -> Any: @@ -119,8 +139,11 @@ def container(self) -> Any: return self._memories_container def _prepare_doc(self, doc: dict[str, Any]) -> dict[str, Any]: - """Return a write-ready document: literal credentials redacted and type defaults applied.""" - body = dict(doc) + """Return a write-ready document: stamped with the tenant, literal credentials redacted, type defaults applied. + + A document that names another tenant raises :class:`ValidationError`. + """ + body = stamp_scope(doc, self._tenant_id) redacted = sanitize_record(body) if redacted: logger.warning("redacted literal secrets before write id=%s patterns=%s", body.get("id"), redacted) @@ -221,11 +244,12 @@ def query( ) -> list[dict[str, Any]]: """Run a query against the explicitly selected split container. - ``partition_key`` reads one partition; ``cross_partition`` lets the query fan out across - partitions. A query that calls ``FullTextScore`` raises ``ValidationError`` when it is sent - with a ``partition_key``: the Python SDK skips query planning for such a query, so the - ranking would be ignored (Azure/azure-sdk-for-python#42241). Filter on the partition key - fields in the ``WHERE`` clause instead (see ``query_scope``). ``full_text_score_scope`` + ``sql`` runs as given, so it must filter on the tenant (``TENANT_FILTER`` or ``OWNER_FILTER`` of + ``_partitioning``) unless it is sent with the owner's ``partition_key``. ``partition_key`` reads one + partition; ``cross_partition`` lets the query fan out across partitions. A query that calls + ``FullTextScore`` raises ``ValidationError`` when it is sent with a ``partition_key``: the Python SDK skips + query planning for such a query, so the ranking would be ignored (Azure/azure-sdk-for-python#42241). Filter + on the partition key fields in the ``WHERE`` clause instead (see ``query_scope``). ``full_text_score_scope`` (``"Local"`` or ``"Global"``) sets where the keyword ranking takes its BM25 statistics from. """ return self._query_items( @@ -318,8 +342,10 @@ def add( follow ``enable_turn_embeddings``. A supplied ``embedding`` is kept, unless it was built from text that held a credential. """ + validate_owner_id(user_id) content, secret_patterns = sanitize_text(content) kwargs: dict[str, Any] = { + "tenant_id": self._tenant_id, "user_id": user_id, "role": role, "content": content, @@ -462,7 +488,10 @@ def get_memories( created_after: Optional[str | datetime] = None, created_before: Optional[str | datetime] = None, ) -> list[dict[str, Any]]: - """Retrieve memories from the MEMORIES container with optional filters.""" + """Retrieve memories from the MEMORIES container with optional filters. + + Reads the store's tenant: one owner's memories when ``user_id`` is given, else every owner's. + """ types = _validated_memories_types(memory_types) logger.debug( "get_memories filters: memory_id=%s user_id=%s thread_id=%s role=%s types=%s recent_k=%s", @@ -475,6 +504,7 @@ def get_memories( ) qb = _build_memory_query_builder( + tenant_id=self._tenant_id, memory_id=memory_id, user_id=user_id, thread_id=thread_id, @@ -504,10 +534,12 @@ def get_memories( query = f"SELECT * FROM c{where}" logger.debug("get_memories query: %s", query) + partition_key, cross_partition = query_scope(self._tenant_id, user_id) items = self._query_items( query=query, parameters=parameters or None, - cross_partition=True, + partition_key=partition_key, + cross_partition=cross_partition, operation="get_memories query", container=self._memories_container, ) @@ -525,7 +557,6 @@ def update( memory_id: str, *, user_id: str, - thread_id: str, memory_type: str, content: Optional[str] = None, role: Optional[str] = None, @@ -548,14 +579,15 @@ def update( ) container = self._container_for_type(memory_type) + partition_key = partition_key_for(self._tenant_id, user_id) max_attempts = 5 attempts = 0 vectors: dict[str, list[float]] = {} while True: try: - doc = container.read_item(item=memory_id, partition_key=[user_id, thread_id]) + doc = container.read_item(item=memory_id, partition_key=partition_key) except CosmosResourceNotFoundError as exc: - raise MemoryNotFoundError(memory_id=memory_id, user_id=user_id, thread_id=thread_id) from exc + raise MemoryNotFoundError(memory_id=memory_id, user_id=user_id) from exc except Exception as exc: raise _wrap_cosmos_exception(exc, message=f"update read failed for {memory_id}: {exc}") from exc @@ -601,7 +633,6 @@ def delete( memory_id: str, *, user_id: str, - thread_id: str, memory_type: str, ) -> None: """Delete a memory document from the container for ``memory_type``. @@ -622,10 +653,11 @@ def delete( ) container = self._container_for_type(memory_type) + partition_key = partition_key_for(self._tenant_id, user_id) try: - doc = container.read_item(item=memory_id, partition_key=[user_id, thread_id]) + doc = container.read_item(item=memory_id, partition_key=partition_key) except CosmosResourceNotFoundError as exc: - raise MemoryNotFoundError(memory_id=memory_id, user_id=user_id, thread_id=thread_id) from exc + raise MemoryNotFoundError(memory_id=memory_id, user_id=user_id) from exc except Exception as exc: raise _wrap_cosmos_exception(exc, message=f"delete read failed for {memory_id}: {exc}") from exc @@ -636,19 +668,19 @@ def delete( absorbed: list[dict[str, Any]] = [] if memory_type in ABSORBING_TYPES: try: - absorbed = delete_absorbed(container, user_id, memory_id) + absorbed = delete_absorbed(container, self._tenant_id, user_id, memory_id) except Exception as exc: raise _wrap_cosmos_exception( exc, message=f"delete of the records folded into {memory_id} failed: {exc}" ) from exc - kwargs: dict[str, Any] = {"item": memory_id, "partition_key": [user_id, thread_id]} + kwargs: dict[str, Any] = {"item": memory_id, "partition_key": partition_key} if etag := doc.get("_etag"): kwargs.update(match_condition=MatchConditions.IfNotModified, etag=etag) try: container.delete_item(**kwargs) except CosmosResourceNotFoundError as exc: - raise MemoryNotFoundError(memory_id=memory_id, user_id=user_id, thread_id=thread_id) from exc + raise MemoryNotFoundError(memory_id=memory_id, user_id=user_id) from exc except CosmosAccessConditionFailedError as exc: raise MemoryConflictError( f"delete conflicted for memory_id={memory_id!r} - document was modified after the type check" @@ -671,9 +703,8 @@ def get_thread( created_before: Optional[str | datetime] = None, ) -> list[dict[str, Any]]: """Retrieve an entire thread (turns) sorted oldest first.""" - qb = _QueryBuilder() + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.thread_id", "@thread_id", thread_id) - qb.add_filter("c.user_id", "@user_id", user_id) add_tag_filters(qb, tags_all=tags_all, tags_any=tags_any, exclude_tags=exclude_tags) qb.add_time_range( "c.created_at", @@ -687,10 +718,12 @@ def get_thread( query = f"SELECT {_TURN_PROJECTION} FROM c{qb.build_where()} ORDER BY c.created_at DESC" logger.debug("get_thread query: %s", query) + partition_key, cross_partition = query_scope(self._tenant_id, user_id) items = self._query_items( query=query, parameters=qb.get_parameters(), - cross_partition=True, + partition_key=partition_key, + cross_partition=cross_partition, operation="get_thread query", container=self._turns_container, ) @@ -706,9 +739,8 @@ def get_thread_summary( recent_k: Optional[int] = None, ) -> list[dict[str, Any]]: """Retrieve active thread summaries for ``(user_id, thread_id)``, newest first.""" - qb = _QueryBuilder() + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.type", "@type", "thread_summary") - qb.add_filter("c.user_id", "@user_id", user_id) qb.add_filter("c.thread_id", "@thread_id", thread_id) qb.add_is_null_or_undefined("c.superseded_by") parameters = qb.get_parameters() @@ -720,7 +752,7 @@ def get_thread_summary( return self._query_items( query=sql, parameters=parameters, - partition_key=[user_id, thread_id], + partition_key=partition_key_for(self._tenant_id, user_id), operation="get_thread_summary query", container=self._summaries_container, ) @@ -734,9 +766,8 @@ def get_episodes( """Retrieve active episodic memories for ``user_id``, newest first.""" if not user_id: raise ValidationError("user_id is required for get_episodes") - qb = _QueryBuilder() + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.type", "@type", "episodic") - qb.add_filter("c.user_id", "@user_id", user_id) qb.add_filter("c.thread_id", "@thread_id", thread_id) qb.add_is_null_or_undefined("c.superseded_by") parameters = qb.get_parameters() @@ -745,13 +776,11 @@ def get_episodes( sql = f"SELECT TOP @recent_k * FROM c{qb.build_where()} ORDER BY c.created_at DESC" else: sql = f"SELECT * FROM c{qb.build_where()} ORDER BY c.created_at DESC" - partition_key, cross_partition = query_scope(user_id, thread_id) return self.query( sql, parameters, container_key=ContainerKey.MEMORIES, - partition_key=partition_key, - cross_partition=cross_partition, + partition_key=partition_key_for(self._tenant_id, user_id), ) def get_user_summary(self, user_id: str) -> Optional[dict[str, Any]]: @@ -761,7 +790,7 @@ def get_user_summary(self, user_id: str) -> Optional[dict[str, Any]]: try: return self._summaries_container.read_item( item=f"user_summary_{user_id}", - partition_key=[user_id, "__user_summary__"], + partition_key=partition_key_for(self._tenant_id, user_id), ) except CosmosResourceNotFoundError: return None @@ -778,8 +807,8 @@ def list_tags( include_superseded: bool = False, ) -> list[str]: """Return sorted distinct tags for a user from the MEMORIES container.""" - query = "SELECT VALUE c.tags FROM c WHERE c.user_id = @user_id AND ARRAY_LENGTH(c.tags) > 0" - parameters = [{"name": "@user_id", "value": user_id}] + query = f"SELECT VALUE c.tags FROM c WHERE {OWNER_FILTER} AND ARRAY_LENGTH(c.tags) > 0" + parameters = owner_parameters(self._tenant_id, user_id) if thread_id is not None: query += " AND c.thread_id = @thread_id" parameters.append({"name": "@thread_id", "value": thread_id}) @@ -787,12 +816,10 @@ def list_tags( query += " AND (NOT IS_DEFINED(c.superseded_by) OR IS_NULL(c.superseded_by))" prefix_norm = prefix.strip().lower() if prefix else None - partition_key, cross_partition = query_scope(user_id, thread_id) rows = self._query_items( query=query, parameters=parameters, - partition_key=partition_key, - cross_partition=cross_partition, + partition_key=partition_key_for(self._tenant_id, user_id), operation="list_tags query", container=self._memories_container, ) @@ -814,7 +841,6 @@ def _mutate_tags( self, memory_id: str, user_id: str, - thread_id: str, memory_type: str, tags: list[str], *, @@ -831,6 +857,7 @@ def _mutate_tags( _validate_taggable_type(memory_type) container = self._container_for_type(memory_type) + partition_key = partition_key_for(self._tenant_id, user_id) secret_patterns: list[str] = [] if add: tags, secret_patterns = drop_secret_tags(tags) @@ -841,9 +868,9 @@ def _mutate_tags( attempts = 0 while True: try: - doc = container.read_item(item=memory_id, partition_key=[user_id, thread_id]) + doc = container.read_item(item=memory_id, partition_key=partition_key) except CosmosResourceNotFoundError as exc: - raise MemoryNotFoundError(memory_id=memory_id, user_id=user_id, thread_id=thread_id) from exc + raise MemoryNotFoundError(memory_id=memory_id, user_id=user_id) from exc mark_secret(doc, secret_patterns) existing_tags = set(doc.get("tags", [])) if add: @@ -872,7 +899,6 @@ def add_tags( self, memory_id: str, user_id: str, - thread_id: str, memory_type: str, tags: list[str], ) -> None: @@ -881,18 +907,17 @@ def add_tags( Tags are lower-cased. A tag that holds a literal credential is dropped, and the memory is marked ``sys:secret``. """ - self._mutate_tags(memory_id, user_id, thread_id, memory_type, tags, add=True) + self._mutate_tags(memory_id, user_id, memory_type, tags, add=True) def remove_tags( self, memory_id: str, user_id: str, - thread_id: str, memory_type: str, tags: list[str], ) -> None: """Remove tags from an existing fact, episodic or procedural memory.""" - self._mutate_tags(memory_id, user_id, thread_id, memory_type, tags, add=False) + self._mutate_tags(memory_id, user_id, memory_type, tags, add=False) def mark_superseded( self, @@ -901,7 +926,10 @@ def mark_superseded( *, reason: str, ) -> bool: - """Set supersession audit fields using ETag protection when available.""" + """Set supersession audit fields using ETag protection when available. + + A document that names another tenant raises :class:`ValidationError`. + """ from azure.core import MatchConditions from azure.cosmos.exceptions import ( CosmosAccessConditionFailedError, @@ -909,12 +937,15 @@ def mark_superseded( ) etag = old_doc.get("_etag") - new_doc = { - **old_doc, - "superseded_by": superseder_id, - "supersede_reason": reason, - "superseded_at": datetime.now(timezone.utc).isoformat(), - } + new_doc = stamp_scope( + { + **old_doc, + "superseded_by": superseder_id, + "supersede_reason": reason, + "superseded_at": datetime.now(timezone.utc).isoformat(), + }, + self._tenant_id, + ) target_container = self._container_for_type(old_doc.get("type")) try: if etag: @@ -953,8 +984,7 @@ def get_procedural_prompt(self, user_id: str) -> Optional[str]: instructions: ``CosmosMemoryClient.get_procedural_prompt`` compiles those from the active standing rules. """ - qb = _QueryBuilder() - qb.add_filter("c.user_id", "@user_id", user_id) + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.thread_id", "@thread_id", "__procedural__") qb.add_filter("c.type", "@type", "procedural") qb.add_is_null_or_undefined("c.superseded_by") @@ -963,7 +993,7 @@ def get_procedural_prompt(self, user_id: str) -> Optional[str]: items = self._query_items( query=query, parameters=qb.get_parameters(), - cross_partition=True, + partition_key=partition_key_for(self._tenant_id, user_id), operation="get_procedural_prompt query", container=self._memories_container, ) @@ -981,8 +1011,7 @@ def get_procedural_history(self, user_id: str, limit: int = 10) -> list[dict[str if limit <= 0: return [] - qb = _QueryBuilder() - qb.add_filter("c.user_id", "@user_id", user_id) + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.thread_id", "@thread_id", "__procedural__") qb.add_filter("c.type", "@type", "procedural") @@ -990,7 +1019,7 @@ def get_procedural_history(self, user_id: str, limit: int = 10) -> list[dict[str items = self._query_items( query=query, parameters=qb.get_parameters(), - cross_partition=True, + partition_key=partition_key_for(self._tenant_id, user_id), operation="get_procedural_history query", container=self._memories_container, ) @@ -1023,8 +1052,7 @@ def get_procedural_memories( ``metadata.category`` and ``salience``, which procedures learned by ``synthesize_procedural`` do not carry, so setting one leaves them out. """ - qb = _QueryBuilder() - qb.add_filter("c.user_id", "@user_id", user_id) + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.thread_id", "@thread_id", "__procedural__") qb.add_filter("c.type", "@type", "procedural") if not include_superseded: @@ -1034,7 +1062,7 @@ def get_procedural_memories( items = self._query_items( query=query, parameters=qb.get_parameters(), - cross_partition=True, + partition_key=partition_key_for(self._tenant_id, user_id), operation="get_procedural_memories query", container=self._memories_container, ) @@ -1084,10 +1112,9 @@ def search( ``query_embedding`` is the query's embedding when the caller already has it. ``thread_id`` limits facts to that thread; episodic and procedural memories stay user-wide. - A keyword query, or a thread-scoped search that includes those user-wide types, runs across - partitions with ``user_id`` and ``thread_id`` filters in the WHERE clause (keyword queries - also set ``full_text_score_scope="Local"``); a vector-only query over facts with both ids - reads one partition (see ``query_scope``). + The search reads the store's tenant only. A vector-only query that names ``user_id`` reads that owner's + partition; a keyword query runs across partitions with the ``tenant_id`` and ``user_id`` filters in the + WHERE clause and sets ``full_text_score_scope="Local"`` (see ``query_scope``). """ terms = require_search_terms(search_terms, query) top = top_literal(top_k, name="top_k") @@ -1095,6 +1122,7 @@ def search( keywords = [] if vector_only else extract_keywords(terms) qb = _build_memory_query_builder( + tenant_id=self._tenant_id, memory_id=memory_id, user_id=user_id, role=role, @@ -1130,9 +1158,7 @@ def search( for i, kw in enumerate(keywords): parameters.append({"name": f"@kw{i}", "value": kw}) - partition_key, cross_partition = query_scope(user_id, thread_id, len(keywords)) - if thread_id is not None and (not memory_types or set(memory_types) & USER_SCOPED_MEMORIES_TYPES): - partition_key, cross_partition = None, True + partition_key, cross_partition = query_scope(self._tenant_id, user_id, len(keywords)) logger.debug("MemoryStore.search query: %s", sql) return self.query( sql, @@ -1147,7 +1173,6 @@ def get_memory_history( self, memory_id: str, user_id: str, - thread_id: Optional[str] = None, *, max_depth: int = 20, ) -> list[dict[str, Any]]: @@ -1164,31 +1189,26 @@ def get_memory_history( value is everything it superseded, transitively, bounded by *max_depth* to guard against cycles. Each entry carries the ``superseded_at`` / ``supersede_reason`` audit fields so callers can order and explain the - transitions. + transitions. The walk stays in the owner's partition, whatever threads the records belong to. """ if not memory_id: raise ValidationError("memory_id is required") if not user_id: raise ValidationError("user_id is required") - partition_key, cross_partition = query_scope(user_id, thread_id) + partition_key = partition_key_for(self._tenant_id, user_id) history: list[dict[str, Any]] = [] seen: set[str] = {memory_id} frontier: list[str] = [memory_id] for _ in range(max(1, max_depth)): id_params = [{"name": f"@sid{i}", "value": sid} for i, sid in enumerate(frontier)] placeholders = ", ".join(param["name"] for param in id_params) - parameters: list[dict[str, Any]] = [*id_params, {"name": "@user_id", "value": user_id}] - where = f"c.superseded_by IN ({placeholders}) AND c.user_id = @user_id" - if thread_id is not None: - where += " AND c.thread_id = @thread_id" - parameters.append({"name": "@thread_id", "value": thread_id}) - sql = f"SELECT {MEMORY_PROJECTION} FROM c WHERE {where}" + parameters: list[dict[str, Any]] = [*id_params, *owner_parameters(self._tenant_id, user_id)] + sql = f"SELECT {MEMORY_PROJECTION} FROM c WHERE c.superseded_by IN ({placeholders}) AND {OWNER_FILTER}" rows = self.query( sql, parameters, container_key=ContainerKey.MEMORIES, partition_key=partition_key, - cross_partition=cross_partition, ) frontier = [] for doc in rows: @@ -1222,13 +1242,11 @@ def search_turns( Only vector-searchable when turn embeddings were enabled at write time (see ``enable_turn_embeddings``). ``user_id`` is required and always - filters the results. When ``thread_id`` is also supplied the results are - restricted to that thread: a vector-only query targets the thread's - partition, while a keyword (hybrid) query runs across partitions with - ``user_id`` and ``thread_id`` filters in the WHERE clause (a partition key - breaks full-text ranking, Azure SDK issue #42241). When it is omitted the - query fans out across the user's partitions. - + filters the results, within the store's tenant. ``thread_id`` narrows the + results to one thread. A vector-only query reads the owner's partition, + while a keyword (hybrid) query runs across partitions with the ``tenant_id`` + and ``user_id`` filters in the WHERE clause (a partition key breaks + full-text ranking, Azure SDK issue #42241). """ if not user_id: raise ValidationError("user_id is required for search_turns") @@ -1237,8 +1255,7 @@ def search_turns( query_vector = self._embed(terms) keywords = extract_keywords(terms) - qb = _QueryBuilder() - qb.add_filter("c.user_id", "@user_id", user_id) + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.thread_id", "@thread_id", thread_id) qb.add_filter("c.role", "@role", role) add_tag_filters(qb, tags_all=tags_all, tags_any=tags_any, exclude_tags=exclude_tags) @@ -1256,7 +1273,7 @@ def search_turns( for i, kw in enumerate(keywords): parameters.append({"name": f"@kw{i}", "value": kw}) - partition_key, cross_partition = query_scope(user_id, thread_id, len(keywords)) + partition_key, cross_partition = query_scope(self._tenant_id, user_id, len(keywords)) logger.debug("MemoryStore.search_turns query: %s", sql) return self.query( sql, @@ -1287,9 +1304,9 @@ def search_summaries( topic-scoped summary question all surface the right summary. Ranking is by vector similarity, with full-text relevance added when the query has keywords. ``user_id`` is required. Pass ``thread_id`` to narrow to one - thread's summary; as with :meth:`search_turns`, a keyword query then runs - across partitions with ``user_id`` and ``thread_id`` filters in the WHERE - clause, and a vector-only query targets the thread's partition. + thread's summary. As with :meth:`search_turns`, a vector-only query reads + the owner's partition and a keyword query runs across partitions with the + ``tenant_id`` and ``user_id`` filters in the WHERE clause. """ if not user_id: raise ValidationError("user_id is required for search_summaries") @@ -1298,8 +1315,7 @@ def search_summaries( query_vector = self._embed(terms) keywords = extract_keywords(terms) - qb = _QueryBuilder() - qb.add_filter("c.user_id", "@user_id", user_id) + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.thread_id", "@thread_id", thread_id) add_tag_filters(qb, tags_all=tags_all, tags_any=tags_any, exclude_tags=exclude_tags) @@ -1309,7 +1325,7 @@ def search_summaries( for i, kw in enumerate(keywords): parameters.append({"name": f"@kw{i}", "value": kw}) - partition_key, cross_partition = query_scope(user_id, thread_id, len(keywords)) + partition_key, cross_partition = query_scope(self._tenant_id, user_id, len(keywords)) logger.debug("MemoryStore.search_summaries query: %s", sql) return self.query( sql, @@ -1349,9 +1365,8 @@ def search_episodic( query_vector = self._embed(terms) keywords = extract_keywords(terms) - qb = _QueryBuilder() + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.type", "@type", "episodic") - qb.add_filter("c.user_id", "@user_id", user_id) qb.add_filter("c.thread_id", "@thread_id", thread_id) add_tag_filters(qb, tags_all=tags_all, tags_any=tags_any, exclude_tags=exclude_tags) qb.add_time_range( @@ -1388,7 +1403,7 @@ def search_episodic( for i, kw in enumerate(keywords): parameters.append({"name": f"@kw{i}", "value": kw}) - partition_key, cross_partition = query_scope(user_id, thread_id, len(keywords)) + partition_key, cross_partition = query_scope(self._tenant_id, user_id, len(keywords)) logger.debug("MemoryStore.search_episodic query: %s", sql) return self.query( sql, @@ -1429,9 +1444,8 @@ def retrieve_procedures( query_vector = self._embed(terms) keywords = extract_keywords(terms) - qb = _QueryBuilder() + qb = _QueryBuilder.for_tenant(self._tenant_id, user_id) qb.add_filter("c.type", "@type", "procedural") - qb.add_filter("c.user_id", "@user_id", user_id) qb.add_filter("c.procedure_kind", "@procedure_kind", procedure_kind) qb.add_filter("c.status", "@status", status) @@ -1446,7 +1460,7 @@ def retrieve_procedures( for i, kw in enumerate(keywords): parameters.append({"name": f"@kw{i}", "value": kw}) - partition_key, cross_partition = query_scope(user_id, None) + partition_key, cross_partition = query_scope(self._tenant_id, user_id, len(keywords)) logger.debug("MemoryStore.retrieve_procedures query: %s", sql) return self.query( sql, diff --git a/function_app/orchestrators/extract_episodes.py b/function_app/orchestrators/extract_episodes.py index 759eecc..0085b95 100644 --- a/function_app/orchestrators/extract_episodes.py +++ b/function_app/orchestrators/extract_episodes.py @@ -30,6 +30,7 @@ @bp.orchestration_trigger(context_name="context") def ExtractEpisodesOrchestrator(context: df.DurableOrchestrationContext): payload = context.get_input() or {} + tenant_id = payload["tenant_id"] user_id = payload["user_id"] thread_id = payload["thread_id"] @@ -38,7 +39,7 @@ def ExtractEpisodesOrchestrator(context: df.DurableOrchestrationContext): result = yield context.call_activity_with_retry( "ee_ExtractEpisodes", retry, - {"user_id": user_id, "thread_id": thread_id}, + {"tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id}, ) return result @@ -52,13 +53,15 @@ def ExtractEpisodesOrchestrator(context: df.DurableOrchestrationContext): @bp.activity_trigger(input_name="payload") @redact_errors def ee_ExtractEpisodes(payload: dict) -> dict: + tenant_id = payload["tenant_id"] user_id = payload["user_id"] thread_id = payload["thread_id"] - pipeline = get_pipeline() + pipeline = get_pipeline(tenant_id) result = pipeline.extract_episodes(user_id=user_id, thread_id=thread_id, flush=False) or {} slim = {"episodes": int(result.get("episodes", 0))} logger.info( - "ExtractEpisodes user=%s thread=%s episodes=%s", + "ExtractEpisodes tenant=%s user=%s thread=%s episodes=%s", + tenant_id, user_id, thread_id, slim["episodes"], diff --git a/function_app/orchestrators/extract_memories.py b/function_app/orchestrators/extract_memories.py index ed7dc28..c62be11 100644 --- a/function_app/orchestrators/extract_memories.py +++ b/function_app/orchestrators/extract_memories.py @@ -25,6 +25,7 @@ import azure.durable_functions as df from shared import config from shared.error_redaction import redact_errors +from shared.instance_ids import orchestration_instance_id from shared.pipeline_factory import get_pipeline from azure.cosmos.agent_memory.logging import describe_exception @@ -39,13 +40,14 @@ @bp.orchestration_trigger(context_name="context") def ExtractMemoriesOrchestrator(context: df.DurableOrchestrationContext): payload = context.get_input() or {} + tenant_id = payload["tenant_id"] user_id = payload["user_id"] thread_id = payload["thread_id"] should_reconcile = bool(payload.get("reconcile", False)) recent_k = payload.get("recent_k") retry = default_retry_options() - extract_payload = {"user_id": user_id, "thread_id": thread_id} + extract_payload = {"tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id} if recent_k is not None: extract_payload["recent_k"] = recent_k extracted = yield context.call_activity_with_retry( @@ -56,7 +58,7 @@ def ExtractMemoriesOrchestrator(context: df.DurableOrchestrationContext): persisted = yield context.call_activity_with_retry( "em_Persist", retry, - {"user_id": user_id, "extracted": extracted}, + {"tenant_id": tenant_id, "user_id": user_id, "extracted": extracted}, ) count = payload.get("count") @@ -64,7 +66,7 @@ def ExtractMemoriesOrchestrator(context: df.DurableOrchestrationContext): yield context.call_activity_with_retry( "em_AdvanceExtractWatermark", retry, - {"user_id": user_id, "thread_id": thread_id, "count": count}, + {"tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id, "count": count}, ) reconciled = None @@ -73,22 +75,27 @@ def ExtractMemoriesOrchestrator(context: df.DurableOrchestrationContext): reconciled = yield context.call_activity_with_retry( "em_ReconcileMemories", retry, - {"user_id": user_id}, + {"tenant_id": tenant_id, "user_id": user_id}, ) if config.get_procedural_synthesis_auto(): count = payload.get("count") - instance_id = f"procedural:{user_id}:{thread_id}:{count}" if count is not None else None + instance_id = ( + orchestration_instance_id("procedural", tenant_id, user_id, thread_id, count=count) + if count is not None + else None + ) try: procedural = yield context.call_sub_orchestrator_with_retry( "SynthesizeProceduralOrchestrator", retry, - {"user_id": user_id, "force": False}, + {"tenant_id": tenant_id, "user_id": user_id, "force": False}, instance_id=instance_id, ) except Exception as exc: if not context.is_replaying: logger.warning( - "SynthesizeProceduralOrchestrator failed user=%s thread=%s: %s", + "SynthesizeProceduralOrchestrator failed tenant=%s user=%s thread=%s: %s", + tenant_id, user_id, thread_id, describe_exception(exc), @@ -106,18 +113,20 @@ def ExtractMemoriesOrchestrator(context: df.DurableOrchestrationContext): @redact_errors def em_Extract(payload: dict) -> dict: """Load recent turns and run LLM extraction without embeddings or writes.""" + tenant_id = payload["tenant_id"] user_id = payload["user_id"] thread_id = payload["thread_id"] recent_k = payload.get("recent_k") if recent_k is None: recent_k = config.get_max_batch_size() - extracted = get_pipeline().extract_memories_durable( + extracted = get_pipeline(tenant_id).extract_memories_durable( user_id=user_id, thread_id=thread_id, recent_k=recent_k, ) logger.info( - "ExtractMemories extracted user=%s thread=%s facts=%d episodic=%d updates=%d", + "ExtractMemories extracted tenant=%s user=%s thread=%s facts=%d episodic=%d updates=%d", + tenant_id, user_id, thread_id, len(extracted.get("facts", [])), @@ -131,12 +140,13 @@ def em_Extract(payload: dict) -> dict: @redact_errors def em_Persist(payload: dict) -> dict: """Persist extracted docs with embeddings and deterministic create semantics.""" + tenant_id = payload["tenant_id"] user_id = payload["user_id"] - counts = get_pipeline().persist_extracted_memories( + counts = get_pipeline(tenant_id).persist_extracted_memories( user_id=user_id, extracted=payload["extracted"], ) - logger.info("ExtractMemories persisted user=%s counts=%s", user_id, counts) + logger.info("ExtractMemories persisted tenant=%s user=%s counts=%s", tenant_id, user_id, counts) return counts or {} @@ -154,11 +164,12 @@ async def em_AdvanceExtractWatermark(payload: dict) -> bool: from shared.cosmos_clients import get_counter_container_async from shared.counters import advance_extract_watermark, thread_counter_id + tenant_id = payload["tenant_id"] user_id = payload["user_id"] thread_id = payload["thread_id"] count = payload["count"] container = await get_counter_container_async() - await advance_extract_watermark(container, thread_counter_id(user_id, thread_id), user_id, thread_id, count) + await advance_extract_watermark(container, tenant_id, thread_counter_id(user_id, thread_id), user_id, count) return True @@ -171,8 +182,9 @@ def em_ReconcileMemories(payload: dict) -> dict: # starting model calls and keeps what it finished, and the next run continues from the # dedup cursor. # The episodic call is a no-op that returns zero counts. + tenant_id = payload["tenant_id"] user_id = payload["user_id"] - pipeline = get_pipeline() + pipeline = get_pipeline(tenant_id) from azure.cosmos.agent_memory.thresholds import get_dedup_pool_size n = get_dedup_pool_size() diff --git a/function_app/orchestrators/synthesize_procedural.py b/function_app/orchestrators/synthesize_procedural.py index a9f3649..434e6a9 100644 --- a/function_app/orchestrators/synthesize_procedural.py +++ b/function_app/orchestrators/synthesize_procedural.py @@ -35,6 +35,7 @@ @bp.orchestration_trigger(context_name="context") def SynthesizeProceduralOrchestrator(context: df.DurableOrchestrationContext): payload = context.get_input() or {} + tenant_id = payload["tenant_id"] user_id = payload["user_id"] force = bool(payload.get("force", False)) @@ -43,7 +44,7 @@ def SynthesizeProceduralOrchestrator(context: df.DurableOrchestrationContext): result = yield context.call_activity_with_retry( "sp_SynthesizeProcedural", retry, - {"user_id": user_id, "force": force}, + {"tenant_id": tenant_id, "user_id": user_id, "force": force}, ) return result @@ -60,9 +61,10 @@ def sp_SynthesizeProcedural(payload: dict) -> dict: # One activity: the pass moves its cursor after each batch of sources and stops # starting model calls at the deadline, so a long backlog spreads over later runs # instead of outrunning the function timeout. + tenant_id = payload["tenant_id"] user_id = payload["user_id"] force = bool(payload.get("force", False)) - pipeline = get_pipeline() + pipeline = get_pipeline(tenant_id) deadline = time.monotonic() + config.get_activity_time_budget_seconds() result = pipeline.synthesize_procedural(user_id=user_id, force=force, deadline=deadline) or {} slim = { @@ -71,7 +73,8 @@ def sp_SynthesizeProcedural(payload: dict) -> dict: "facts_retired": int(result.get("facts_retired") or 0), } logger.info( - "SynthesizeProcedural user=%s status=%s procedures_created=%s facts_retired=%s", + "SynthesizeProcedural tenant=%s user=%s status=%s procedures_created=%s facts_retired=%s", + tenant_id, user_id, slim["status"], slim["procedures_created"], diff --git a/function_app/orchestrators/thread_summary.py b/function_app/orchestrators/thread_summary.py index 08bb952..a0b02e1 100644 --- a/function_app/orchestrators/thread_summary.py +++ b/function_app/orchestrators/thread_summary.py @@ -23,6 +23,7 @@ @bp.orchestration_trigger(context_name="context") def ThreadSummaryOrchestrator(context: df.DurableOrchestrationContext): payload = context.get_input() or {} + tenant_id = payload["tenant_id"] user_id = payload["user_id"] thread_id = payload["thread_id"] retry = default_retry_options() @@ -30,13 +31,13 @@ def ThreadSummaryOrchestrator(context: df.DurableOrchestrationContext): summary = yield context.call_activity_with_retry( "ts_Extract", retry, - {"user_id": user_id, "thread_id": thread_id, "limit": config.get_max_batch_size()}, + {"tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id, "limit": config.get_max_batch_size()}, ) persisted = yield context.call_activity_with_retry( "ts_PersistSummary", retry, - {"user_id": user_id, "thread_id": thread_id, "summary": summary}, + {"tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id, "summary": summary}, ) return { @@ -49,14 +50,15 @@ def ThreadSummaryOrchestrator(context: df.DurableOrchestrationContext): @redact_errors def ts_Extract(payload: dict) -> dict: """Generate (or incrementally update) the thread summary body only.""" + tenant_id = payload["tenant_id"] user_id = payload["user_id"] thread_id = payload["thread_id"] - summary = get_pipeline().generate_thread_summary_durable( + summary = get_pipeline(tenant_id).generate_thread_summary_durable( user_id=user_id, thread_id=thread_id, recent_k=payload.get("limit"), ) - logger.info("ThreadSummary extracted user=%s thread=%s", user_id, thread_id) + logger.info("ThreadSummary extracted tenant=%s user=%s thread=%s", tenant_id, user_id, thread_id) return summary @@ -64,12 +66,15 @@ def ts_Extract(payload: dict) -> dict: @redact_errors def ts_PersistSummary(payload: dict) -> dict: """Compute the embedding and persist the thread summary.""" + tenant_id = payload["tenant_id"] user_id = payload["user_id"] thread_id = payload["thread_id"] - summary = get_pipeline().persist_thread_summary( + summary = get_pipeline(tenant_id).persist_thread_summary( user_id=user_id, thread_id=thread_id, summary_doc=payload["summary"], ) - logger.info("ThreadSummary persisted user=%s thread=%s id=%s", user_id, thread_id, summary.get("id")) + logger.info( + "ThreadSummary persisted tenant=%s user=%s thread=%s id=%s", tenant_id, user_id, thread_id, summary.get("id") + ) return summary diff --git a/function_app/orchestrators/user_summary.py b/function_app/orchestrators/user_summary.py index f000951..b926017 100644 --- a/function_app/orchestrators/user_summary.py +++ b/function_app/orchestrators/user_summary.py @@ -30,10 +30,12 @@ @bp.orchestration_trigger(context_name="context") def UserSummaryOrchestrator(context: df.DurableOrchestrationContext): payload = context.get_input() or {} + tenant_id = payload["tenant_id"] user_id = payload["user_id"] thread_ids = payload.get("thread_ids") or None retry = default_retry_options() extract_payload = { + "tenant_id": tenant_id, "user_id": user_id, "limit": config.get_max_batch_size(), "thread_ids": thread_ids, @@ -52,9 +54,10 @@ def UserSummaryOrchestrator(context: df.DurableOrchestrationContext): while isinstance(user_summary, dict) and user_summary.get("status") == _NO_MEMORIES_YET_STATUS: if context.current_utc_datetime >= deadline: logger.warning( - "UserSummary no memories persisted within %ss for user=%s; skipping this " + "UserSummary no memories persisted within %ss for tenant=%s user=%s; skipping this " "cadence (a later user-summary threshold will retry)", wait_budget, + tenant_id, user_id, ) return {"persisted": False, "user_summary_id": None, "skipped": _NO_MEMORIES_YET_STATUS} @@ -64,7 +67,7 @@ def UserSummaryOrchestrator(context: df.DurableOrchestrationContext): persisted = yield context.call_activity_with_retry( "us_PersistUserSummary", retry, - {"user_id": user_id, "user_summary": user_summary}, + {"tenant_id": tenant_id, "user_id": user_id, "user_summary": user_summary}, ) return { @@ -86,17 +89,18 @@ def us_Extract(payload: dict) -> dict: the user has no persisted memories yet, so the orchestrator can wait for extraction to land rather than exhausting its activity retries. """ + tenant_id = payload["tenant_id"] user_id = payload["user_id"] try: - summary = get_pipeline().generate_user_summary_durable( + summary = get_pipeline(tenant_id).generate_user_summary_durable( user_id=user_id, recent_k=payload.get("limit"), thread_ids=payload.get("thread_ids") or None, ) except NoSourceMemoriesError: - logger.info("UserSummary no source memories yet user=%s; will wait and retry", user_id) + logger.info("UserSummary no source memories yet tenant=%s user=%s; will wait and retry", tenant_id, user_id) return {"status": _NO_MEMORIES_YET_STATUS} - logger.info("UserSummary extracted user=%s", user_id) + logger.info("UserSummary extracted tenant=%s user=%s", tenant_id, user_id) return summary @@ -104,10 +108,11 @@ def us_Extract(payload: dict) -> dict: @redact_errors def us_PersistUserSummary(payload: dict) -> dict: """Compute the embedding and persist the user summary.""" + tenant_id = payload["tenant_id"] user_id = payload["user_id"] - summary = get_pipeline().persist_user_summary( + summary = get_pipeline(tenant_id).persist_user_summary( user_id=user_id, user_summary_doc=payload["user_summary"], ) - logger.info("UserSummary persisted user=%s id=%s", user_id, summary.get("id")) + logger.info("UserSummary persisted tenant=%s user=%s id=%s", tenant_id, user_id, summary.get("id")) return summary diff --git a/function_app/shared/counters.py b/function_app/shared/counters.py index 5623650..16dd494 100644 --- a/function_app/shared/counters.py +++ b/function_app/shared/counters.py @@ -5,17 +5,17 @@ Counter document shape:: - # thread-scoped - id = "thread:{user_id}:{thread_id}", PK = [user_id, thread_id] - { "id": ..., "user_id": ..., "thread_id": ..., "count": int, + # thread-scoped - id = "thread:{user_id}:{thread_id}" + { "id": ..., "tenant_id": ..., "user_id": ..., "thread_id": ..., "count": int, "last_batch_lsn": int|None, "last_batch_old_count": int } - # user-scoped - id = "user:{user_id}", PK = [user_id, "__counters__"] - { "id": ..., "user_id": ..., "thread_id": "__counters__", + # user-scoped - id = "user:{user_id}" + { "id": ..., "tenant_id": ..., "user_id": ..., "thread_id": "__counters__", "count": int, "last_batch_lsn": int|None, "last_batch_old_count": int } -Both also carry ``created_at``, ``updated_at`` and ``last_owner`` (advisory). A thread counter gains -``last_extract_count`` (the extraction watermark), and the SDK may add ``last_failure_at`` and -``last_failure_reason``; an increment keeps all three. +Both live in the owner's partition, PK = [tenant_id, user_id], and also carry ``created_at``, ``updated_at`` and +``last_owner`` (advisory). A thread counter gains ``last_extract_count`` (the extraction watermark), and the SDK may +add ``last_failure_at`` and ``last_failure_reason``; an increment keeps all three. """ from __future__ import annotations @@ -27,6 +27,7 @@ from azure.core import MatchConditions from azure.cosmos.exceptions import CosmosHttpResponseError, CosmosResourceNotFoundError +from azure.cosmos.agent_memory._partitioning import partition_key_for from azure.cosmos.agent_memory.logging import describe_exception logger = logging.getLogger(__name__) @@ -81,6 +82,7 @@ def user_counter_id(user_id: str) -> str: async def increment_counter_by( container: Any, + tenant_id: str, counter_id: str, user_id: str, thread_id: str, @@ -110,7 +112,7 @@ async def increment_counter_by( * Stamps ``last_owner=owner`` (advisory) so operators can detect double-write configurations across SDK and FA. """ - partition_key = [user_id, thread_id] + partition_key = partition_key_for(tenant_id, user_id) for attempt in range(MAX_RETRIES): # ---- Read current counter (or default to 0) ---- @@ -166,6 +168,7 @@ async def increment_counter_by( new_count = old_count + count new_doc = { "id": counter_id, + "tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id, "count": new_count, @@ -271,9 +274,9 @@ def crosses_threshold(old_count: int, new_count: int, n: int) -> bool: async def read_extract_watermark( container: Any, + tenant_id: str, counter_id: str, user_id: str, - thread_id: str, ) -> int | None: """Return the count value at the last successful extract, or ``None``. @@ -284,7 +287,7 @@ async def read_extract_watermark( trigger treats as no watermark yet, so it extracts every turn counted so far. """ try: - doc = await container.read_item(item=counter_id, partition_key=[user_id, thread_id]) + doc = await container.read_item(item=counter_id, partition_key=partition_key_for(tenant_id, user_id)) value = doc.get("last_extract_count") return int(value) if value is not None else None except Exception as exc: # pragma: no cover - best-effort @@ -294,9 +297,9 @@ async def read_extract_watermark( async def advance_extract_watermark( container: Any, + tenant_id: str, counter_id: str, user_id: str, - thread_id: str, count: int, ) -> None: """Advance ``last_extract_count`` to ``count`` after a successful extract. @@ -317,7 +320,7 @@ async def advance_extract_watermark( try: await container.patch_item( item=counter_id, - partition_key=[user_id, thread_id], + partition_key=partition_key_for(tenant_id, user_id), patch_operations=patch_ops, filter_predicate=(f"FROM c WHERE NOT IS_DEFINED(c.last_extract_count) OR c.last_extract_count < {count}"), ) diff --git a/function_app/shared/instance_ids.py b/function_app/shared/instance_ids.py new file mode 100644 index 0000000..2c4ef90 --- /dev/null +++ b/function_app/shared/instance_ids.py @@ -0,0 +1,21 @@ +"""Instance ids for the orchestrations the change feed and the extraction orchestrator start. + +Durable Functions takes an instance id of 1-100 characters without ``/``, ``\\``, ``#``, ``?`` or control characters, +and tenant, user and thread ids are free text, so an instance id never carries them: it is a readable ``kind``, a +fixed-length hash of the owner (and thread) and, for a counter threshold, the count. The same owner, thread and count +always give the same id, which is what makes a replayed change-feed batch start each orchestration once. +""" + +from __future__ import annotations + +from hashlib import sha256 + + +def orchestration_instance_id(kind: str, *parts: str, count: int | None = None) -> str: + """``{kind}:{digest}`` plus ``:{count}`` when a count is given. + + ``parts`` is ``(tenant_id, user_id)`` or ``(tenant_id, user_id, thread_id)``. They are joined with the unit + separator before hashing, so a ``:`` inside an id cannot make two different splits give the same digest. + """ + digest = sha256("\x1f".join(parts).encode("utf-8")).hexdigest()[:32] + return f"{kind}:{digest}" + (f":{count}" if count is not None else "") diff --git a/function_app/shared/pipeline_factory.py b/function_app/shared/pipeline_factory.py index 02d64fc..2f12967 100644 --- a/function_app/shared/pipeline_factory.py +++ b/function_app/shared/pipeline_factory.py @@ -1,7 +1,8 @@ """Lazy PipelineService factory (MI auth, sync clients). The activities reuse :class:`azure.cosmos.agent_memory.services.pipeline.PipelineService` -verbatim - no business logic is duplicated in the function app. +verbatim - no business logic is duplicated in the function app. A pipeline is bound to one tenant, so the +factory keeps one per tenant; they share the containers and the chat and embeddings clients. """ from __future__ import annotations @@ -9,6 +10,8 @@ import os from typing import Any +from azure.cosmos.agent_memory._partitioning import DEFAULT_TENANT_ID, resolve_tenant_id + from . import config from .cosmos_clients import ( get_memories_container, @@ -16,7 +19,9 @@ get_turns_container, ) -_pipeline: Any | None = None +_pipelines: dict[str, Any] = {} +# (chat client, embeddings client, containers), built once and shared by every tenant's pipeline. +_shared: tuple[Any, Any, dict] | None = None def _read_transcript_metadata_keys() -> tuple[str, ...] | None: @@ -33,11 +38,11 @@ def _read_transcript_metadata_keys() -> tuple[str, ...] | None: return keys or None -def get_pipeline(): - """Return the cached :class:`PipelineService` for this worker.""" - global _pipeline - if _pipeline is not None: - return _pipeline +def _shared_clients() -> tuple[Any, Any, dict]: + """Return the chat client, embeddings client and containers shared by every tenant's pipeline.""" + global _shared + if _shared is not None: + return _shared from azure.identity import DefaultAzureCredential @@ -45,8 +50,6 @@ def get_pipeline(): from azure.cosmos.agent_memory._utils import _resolve_embedding_dimensions from azure.cosmos.agent_memory.chat import ChatClient from azure.cosmos.agent_memory.embeddings import EmbeddingsClient - from azure.cosmos.agent_memory.services.pipeline import PipelineService - from azure.cosmos.agent_memory.store import MemoryStore credential = DefaultAzureCredential() memories_container = get_memories_container() @@ -73,15 +76,33 @@ def get_pipeline(): ContainerKey.MEMORIES: memories_container, ContainerKey.SUMMARIES: summaries_container, } + _shared = (chat, embeddings, containers) + return _shared + + +def get_pipeline(tenant_id: str = DEFAULT_TENANT_ID): + """Return the cached :class:`PipelineService` of ``tenant_id`` for this worker.""" + tenant_id = resolve_tenant_id(tenant_id) + pipeline = _pipelines.get(tenant_id) + if pipeline is not None: + return pipeline + + from azure.cosmos.agent_memory.services.pipeline import PipelineService + from azure.cosmos.agent_memory.store import MemoryStore + + chat, embeddings, containers = _shared_clients() store = MemoryStore( containers=containers, embeddings_client=embeddings, + tenant_id=tenant_id, ) - _pipeline = PipelineService( + pipeline = PipelineService( store, chat, embeddings, containers=containers, transcript_metadata_keys=_read_transcript_metadata_keys(), + tenant_id=tenant_id, ) - return _pipeline + _pipelines[tenant_id] = pipeline + return pipeline diff --git a/function_app/triggers/change_feed.py b/function_app/triggers/change_feed.py index c209e9b..56b4996 100644 --- a/function_app/triggers/change_feed.py +++ b/function_app/triggers/change_feed.py @@ -4,6 +4,11 @@ counters, then starts the matching orchestrator with a deterministic instance ID whenever a configured threshold is crossed. +Every turn names its tenant in ``tenant_id``; a turn without a valid one, or without a valid owner or thread, is +skipped. Counters, watermarks, +instance IDs (a hash of the owner, see :mod:`shared.instance_ids`) and orchestrator inputs are per +``(tenant_id, user_id[, thread_id])``, so one Function App serves every tenant that writes to the containers. + The trigger is registered as a :class:`df.Blueprint` and wired into the top-level :class:`df.DFApp` from ``function_app.py``. The pure-logic entry point :func:`process_changefeed_batch` accepts plain ``dict`` documents and a @@ -30,7 +35,10 @@ thread_counter_id, user_counter_id, ) +from shared.instance_ids import orchestration_instance_id +from azure.cosmos.agent_memory._partitioning import partition_key_problem, resolve_tenant_id, validate_owner_id +from azure.cosmos.agent_memory.exceptions import ValidationError from azure.cosmos.agent_memory.logging import describe_exception logger = logging.getLogger(__name__) @@ -47,7 +55,7 @@ async def _ensure_topology() -> None: - """Validate that all split-topology containers are reachable once per worker.""" + """Validate once per worker that the keyed containers are reachable and keyed ``[/tenant_id, /user_id]``.""" global _topology_validated if _topology_validated: return @@ -57,23 +65,47 @@ async def _ensure_topology() -> None: from shared.cosmos_clients import get_cosmos_database_async db = await get_cosmos_database_async() - for name in (config.TURNS_CONTAINER, config.MEMORIES_CONTAINER, config.SUMMARIES_CONTAINER): + for name in ( + config.TURNS_CONTAINER, + config.MEMORIES_CONTAINER, + config.SUMMARIES_CONTAINER, + config.COUNTERS_CONTAINER, + ): problem = None try: container = db.get_container_client(name) - await container.read() + properties = await container.read() except CosmosResourceNotFoundError: - problem = ( - f"container {name!r} does not exist. Run azd up to provision the 3-container split or fix env vars." - ) + problem = f"container {name!r} does not exist. Run azd up to provision the containers or fix env vars." except Exception as exc: problem = f"cannot read container {name!r}: {describe_exception(exc)}" + else: + problem = partition_key_problem(name, properties) if problem: # Raised after the handler, so the host's log of this error carries no SDK error or its text. raise RuntimeError(f"Topology error: {problem}") _topology_validated = True +def _tenant_of(doc: dict) -> str | None: + """The tenant a changed turn names, or ``None`` when it names none or one that is not valid.""" + tenant_id = doc.get("tenant_id") + if tenant_id is None: + return None + try: + return resolve_tenant_id(tenant_id) + except ValidationError: + return None + + +def _owner_of(doc: dict) -> str | None: + """The owner a changed turn names, or ``None`` when it names none or one that is not valid.""" + try: + return validate_owner_id(doc.get("user_id")) + except ValidationError: + return None + + # --------------------------------------------------------------------------- # Pure-logic entry point (exposed for unit tests) # --------------------------------------------------------------------------- @@ -138,16 +170,16 @@ async def process_changefeed_batch( return # all orchestrators disabled # ---- Step 1: Filter to turns + group by scope ---- - thread_counts: dict[tuple[str, str], int] = defaultdict(int) - user_counts: dict[str, int] = defaultdict(int) - thread_max_lsn: dict[tuple[str, str], int] = {} - user_max_lsn: dict[str, int] = {} + thread_counts: dict[tuple[str, str, str], int] = defaultdict(int) + user_counts: dict[tuple[str, str], int] = defaultdict(int) + thread_max_lsn: dict[tuple[str, str, str], int] = {} + user_max_lsn: dict[tuple[str, str], int] = {} # Track which threads contributed to each user counter. The user-summary orchestrator # passes them to the pipeline, which only logs how many (``observed_thread_ids``): it # does not filter by them, and its query reads every memory and thread summary the # user wrote since the last user summary. - user_thread_ids: dict[str, set[str]] = defaultdict(set) + user_thread_ids: dict[tuple[str, str], set[str]] = defaultdict(set) for doc in documents: if doc.get("type") != "turn": @@ -156,15 +188,18 @@ async def process_changefeed_batch( # backend never mutates a turn doc (episodic segmentation advances a # separate cursor doc; fact extraction is count-based), so each turn is # delivered - and counted - exactly once, at creation. - user_id = doc.get("user_id") + tenant_id = _tenant_of(doc) + user_id = _owner_of(doc) thread_id = doc.get("thread_id") - if not user_id or not thread_id: - logger.warning("change-feed: turn doc missing user_id/thread_id, skipping") + if not tenant_id or not user_id or not thread_id: + logger.warning("change-feed: turn doc missing a valid tenant_id, user_id or thread_id, skipping") continue - thread_counts[(user_id, thread_id)] += 1 - user_counts[user_id] += 1 - user_thread_ids[user_id].add(thread_id) + thread_key = (tenant_id, user_id, thread_id) + user_key = (tenant_id, user_id) + thread_counts[thread_key] += 1 + user_counts[user_key] += 1 + user_thread_ids[user_key].add(thread_id) lsn = doc.get("_lsn") if lsn is not None: @@ -172,9 +207,8 @@ async def process_changefeed_batch( lsn_int = int(lsn) except (TypeError, ValueError): continue - tkey = (user_id, thread_id) - thread_max_lsn[tkey] = max(thread_max_lsn.get(tkey, 0), lsn_int) - user_max_lsn[user_id] = max(user_max_lsn.get(user_id, 0), lsn_int) + thread_max_lsn[thread_key] = max(thread_max_lsn.get(thread_key, 0), lsn_int) + user_max_lsn[user_key] = max(user_max_lsn.get(user_key, 0), lsn_int) thread_enabled = n_thread > 0 or n_facts > 0 or n_episode > 0 user_enabled = n_user > 0 @@ -191,11 +225,13 @@ async def process_changefeed_batch( # ---- Step 2: Thread-scoped counters ---- if thread_enabled: - for (user_id, thread_id), batch_count in thread_counts.items(): + for thread_key, batch_count in thread_counts.items(): + tenant_id, user_id, thread_id = thread_key cid = thread_counter_id(user_id, thread_id) - lsn = thread_max_lsn.get((user_id, thread_id)) + lsn = thread_max_lsn.get(thread_key) old_count, new_count = await increment_counter_by( counter_container, + tenant_id, cid, user_id, thread_id, @@ -204,19 +240,21 @@ async def process_changefeed_batch( ) if n_thread > 0 and crosses_threshold(old_count, new_count, n_thread): - instance_id = f"thread_summary:{user_id}:{thread_id}:{new_count}" + instance_id = orchestration_instance_id( + "thread_summary", tenant_id, user_id, thread_id, count=new_count + ) await _safe_start( starter, "ThreadSummaryOrchestrator", instance_id, - {"user_id": user_id, "thread_id": thread_id, "count": new_count}, + {"tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id, "count": new_count}, orchestration_errors, ) if n_facts > 0 and crosses_threshold(old_count, new_count, n_facts): - instance_id = f"extract:{user_id}:{thread_id}:{new_count}" + instance_id = orchestration_instance_id("extract", tenant_id, user_id, thread_id, count=new_count) should_reconcile = bool(n_dedup_turns > 0 and crosses_threshold(old_count, new_count, n_dedup_turns)) - watermark = await read_extract_watermark(counter_container, cid, user_id, thread_id) + watermark = await read_extract_watermark(counter_container, tenant_id, cid, user_id) # Not capped: new_count - watermark is exactly the turns the watermark has # not covered, and the orchestrator advances the watermark to new_count, so # capping would strand the oldest turns (DEDUP_POOL_SIZE is the reconcile @@ -231,6 +269,7 @@ async def process_changefeed_batch( "ExtractMemoriesOrchestrator", instance_id, { + "tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id, "count": new_count, @@ -241,22 +280,24 @@ async def process_changefeed_batch( ) if n_episode > 0 and crosses_threshold(old_count, new_count, n_episode): - instance_id = f"episode:{user_id}:{thread_id}:{new_count}" + instance_id = orchestration_instance_id("episode", tenant_id, user_id, thread_id, count=new_count) await _safe_start( starter, "ExtractEpisodesOrchestrator", instance_id, - {"user_id": user_id, "thread_id": thread_id, "count": new_count}, + {"tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id, "count": new_count}, orchestration_errors, ) # ---- Step 3: User-scoped counters ---- if user_enabled: - for user_id, batch_count in user_counts.items(): + for user_key, batch_count in user_counts.items(): + tenant_id, user_id = user_key cid = user_counter_id(user_id) - lsn = user_max_lsn.get(user_id) + lsn = user_max_lsn.get(user_key) old_count, new_count = await increment_counter_by( counter_container, + tenant_id, cid, user_id, config.USER_COUNTER_THREAD_ID, @@ -264,15 +305,16 @@ async def process_changefeed_batch( batch_max_lsn=lsn, ) if crosses_threshold(old_count, new_count, n_user): - instance_id = f"user_summary:{user_id}:{new_count}" + instance_id = orchestration_instance_id("user_summary", tenant_id, user_id, count=new_count) await _safe_start( starter, "UserSummaryOrchestrator", instance_id, { + "tenant_id": tenant_id, "user_id": user_id, "count": new_count, - "thread_ids": sorted(user_thread_ids.get(user_id, set())), + "thread_ids": sorted(user_thread_ids.get(user_key, set())), }, orchestration_errors, ) @@ -294,9 +336,12 @@ async def _safe_start( errors: list[Exception], ) -> None: logger.info( - "change-feed: starting %s instance=%s", + "change-feed: starting %s instance=%s tenant=%s user=%s thread=%s", orchestration_name, instance_id, + client_input["tenant_id"], + client_input["user_id"], + client_input.get("thread_id"), ) try: await starter.start_new( diff --git a/infra/README.md b/infra/README.md index fb4797d..5ba5ba5 100644 --- a/infra/README.md +++ b/infra/README.md @@ -8,13 +8,15 @@ This folder provisions everything the Agent Memory Toolkit needs in a single Azu - **Cosmos DB for NoSQL** - serverless account (vector and full-text search enabled) with the `ai_memory` database and this container topology: - | Container | Purpose | - | --- | --- | - | `memories` | Facts, episodics, and procedural memories; vector + FTS index | - | `memories_turns` | Turns; vector + FTS index, 30-day default TTL (`MEMORIES_TURNS_DEFAULT_TTL`, in seconds), change-feed binding target | - | `memories_summaries` | Thread + user summaries; vector + FTS index (`search_summaries`), composite index for point reads | - | `leases` | Change-feed checkpoints | - | `counter` | Atomic counters; 90-day default TTL | + | Container | Partition key | Purpose | + | --- | --- | --- | + | `memories` | `/tenant_id`, `/user_id` | Facts, episodics, and procedural memories; vector + FTS index | + | `memories_turns` | `/tenant_id`, `/user_id` | Turns; vector + FTS index, 30-day default TTL (`MEMORIES_TURNS_DEFAULT_TTL`, in seconds), change-feed binding target | + | `memories_summaries` | `/tenant_id`, `/user_id` | Thread + user summaries; vector + FTS index (`search_summaries`), composite index for point reads | + | `leases` | `/id` | Change-feed checkpoints | + | `counter` | `/tenant_id`, `/user_id` | Atomic counters; 90-day default TTL | + + Everything one owner (a user or an agent) knows in one tenant is in one logical partition; `thread_id` is a plain field. A container's partition key cannot be changed, so a deployment created with the earlier `[user_id, thread_id]` key has to recreate its containers: delete `memories`, `memories_turns`, `memories_summaries`, `counter` and `leases` (their data is lost) and run `azd up`. A container left with the earlier key is refused by `create_memory_store()`, by `validate_topology()` and by the Function App on its first change-feed batch, so the mistake shows up at startup rather than as empty reads. - **AI Foundry** (`Microsoft.CognitiveServices/accounts` with `kind: AIServices`) - with `gpt-4o-mini` and `text-embedding-3-large` deployments - **User-assigned managed identity (UAMI)** - used by the Function app - **RBAC role assignments** - Cosmos DB Built-in Data Reader + Contributor, Cognitive Services OpenAI User, Storage Blob/Queue/Table data roles, granted to the UAMI and (except the Storage Queue/Table roles) the deploying user (full table in [Identity & RBAC](#identity--rbac)) @@ -126,15 +128,15 @@ To cut chat usage instead, see the cost knobs under [Counter-based trigger confi ## Counter-based trigger configuration (Function app only) -The Function app uses a counter document per `(user_id, thread_id)` to decide when to fire each orchestrator. Every knob is a Bicep parameter bound to an `azd env` variable - `azd up` re-renders them on every deploy, so changing a value is a one-line `azd env set ...` followed by `azd up`. +The Function app uses a counter document per `(tenant_id, user_id, thread_id)` to decide when to fire each orchestrator, and reads `tenant_id` from each changed turn, so one Function app serves every tenant (there is no tenant setting). Every knob is a Bicep parameter bound to an `azd env` variable - `azd up` re-renders them on every deploy, so changing a value is a one-line `azd env set ...` followed by `azd up`. | `azd env` variable | Bicep param | Default | Effect | |---|---|---|---| -| `THREAD_SUMMARY_EVERY_N` | `threadSummaryEveryN` | `10` | Run thread-summary orchestration every N turns within a `(user_id, thread_id)`. `0` disables it. | -| `FACT_EXTRACTION_EVERY_N` | `factExtractionEveryN` | `2` | Run fact extraction every N turns within a `(user_id, thread_id)`. Reconcile and procedure learning run on multiples of it (see `DEDUP_EVERY_N`). `0` disables all three. | +| `THREAD_SUMMARY_EVERY_N` | `threadSummaryEveryN` | `10` | Run thread-summary orchestration every N turns within a `(tenant_id, user_id, thread_id)`. `0` disables it. | +| `FACT_EXTRACTION_EVERY_N` | `factExtractionEveryN` | `2` | Run fact extraction every N turns within a `(tenant_id, user_id, thread_id)`. Reconcile and procedure learning run on multiples of it (see `DEDUP_EVERY_N`). `0` disables all three. | | `DEDUP_EVERY_N` | `dedupEveryN` | `5` | Run reconcile (fold duplicate facts, combine facts about one specific thing, link conflicting facts) every Nth fact-extraction, so it fires every `FACT_EXTRACTION_EVERY_N × DEDUP_EVERY_N` turns. Procedure learning is chained after it (unless `PROCEDURAL_SYNTHESIS_AUTO` is `false`). `0` disables both. | -| `USER_SUMMARY_EVERY_N` | `userSummaryEveryN` | `20` | Run user-summary orchestration every N turns from a given `user_id` across all threads. `0` disables it. | -| `EPISODE_EVAL_EVERY_N` | `episodeEvalEveryN` | `4` | Check a thread's open episode for a boundary every N turns within a `(user_id, thread_id)`. `0` disables episodic memory. | +| `USER_SUMMARY_EVERY_N` | `userSummaryEveryN` | `20` | Run user-summary orchestration every N turns from a given `(tenant_id, user_id)` across all threads. `0` disables it. | +| `EPISODE_EVAL_EVERY_N` | `episodeEvalEveryN` | `4` | Check a thread's open episode for a boundary every N turns within a `(tenant_id, user_id, thread_id)`. `0` disables episodic memory. | | `EPISODE_IDLE_GAP_SECONDS` | `episodeIdleGapSeconds` | `1800` | A gap longer than this between two consecutive turns closes the open episode. | | `EPISODE_TOPIC_DRIFT` | `episodeTopicDrift` | `0` | Cosine distance from the open episode's centroid past which a new turn closes it. `0` turns drift detection off, leaving the idle gap and the size cap. | | `EPISODE_MAX_TURNS` | `episodeMaxTurns` | `40` | An open episode is closed once it reaches this many turns. | diff --git a/infra/main.bicep b/infra/main.bicep index 42d8689..0f30e31 100644 --- a/infra/main.bicep +++ b/infra/main.bicep @@ -66,19 +66,19 @@ param azureOpenAiApiVersion string = '2024-12-01-preview' @description('Embedding output dimensions. Used for the vector policy of the memories, turns and summaries containers and set as AI_FOUNDRY_EMBEDDING_DIMENSIONS on the function app, so they always match; set the same value for the SDK. text-embedding-3-large natively returns 3072; 1536 (the SDK default) is requested instead. A container keeps the dimensions it was created with.') param embeddingDimensions int = 1536 -@description('Run thread-summary orchestration every N turns within a (user_id, thread_id). 0 = disabled.') +@description('Run thread-summary orchestration every N turns within a (tenant_id, user_id, thread_id). 0 = disabled.') param threadSummaryEveryN int = 10 -@description('Run fact extraction every N turns within a (user_id, thread_id); reconcile and procedure learning run on multiples of it (see dedupEveryN). Default 2 = every 2 turns (the SDK default). 0 = disabled, which disables all three. Bump for cost-sensitive production deployments.') +@description('Run fact extraction every N turns within a (tenant_id, user_id, thread_id); reconcile and procedure learning run on multiples of it (see dedupEveryN). Default 2 = every 2 turns (the SDK default). 0 = disabled, which disables all three. Bump for cost-sensitive production deployments.') param factExtractionEveryN int = 2 @description('Once per N fact extractions, run reconcile (fold duplicates, combine facts, link conflicting facts), then procedure learning unless PROCEDURAL_SYNTHESIS_AUTO is false. Effective cadence = factExtractionEveryN * dedupEveryN turns. 0 = disabled.') param dedupEveryN int = 5 -@description('Run user-summary orchestration every N turns from a given user_id across all threads. 0 = disabled.') +@description('Run user-summary orchestration every N turns from a given (tenant_id, user_id) across all threads. 0 = disabled.') param userSummaryEveryN int = 20 -@description('Evaluate an episode boundary every N turns within a (user_id, thread_id). 0 = disabled (no episodic memory).') +@description('Evaluate an episode boundary every N turns within a (tenant_id, user_id, thread_id). 0 = disabled (no episodic memory).') param episodeEvalEveryN int = 4 @description('Idle gap (seconds) between two consecutive turns that closes the open episode.') diff --git a/infra/modules/cosmos.bicep b/infra/modules/cosmos.bicep index 406247c..e03db5e 100644 --- a/infra/modules/cosmos.bicep +++ b/infra/modules/cosmos.bicep @@ -80,6 +80,10 @@ resource database 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-11-15 } // --- Containers ----------------------------------------------------------- +// +// memories, turns, summaries and counter share one hierarchical partition key, /tenant_id then /user_id (the SDK's +// create_memory_store() uses the same): all of one owner's records in a tenant, whether the owner is a user or an +// agent, live in one logical partition, and thread_id is a plain field. A container's key cannot be changed later. resource memoriesContainer 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2024-11-15' = { parent: database @@ -92,8 +96,8 @@ resource memoriesContainer 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/c kind: 'MultiHash' version: 2 paths: [ + '/tenant_id' '/user_id' - '/thread_id' ] } indexingPolicy: { @@ -161,8 +165,8 @@ resource memoriesTurnsContainer 'Microsoft.DocumentDB/databaseAccounts/sqlDataba kind: 'MultiHash' version: 2 paths: [ + '/tenant_id' '/user_id' - '/thread_id' ] } indexingPolicy: { @@ -233,8 +237,8 @@ resource memoriesSummariesContainer 'Microsoft.DocumentDB/databaseAccounts/sqlDa kind: 'MultiHash' version: 2 paths: [ + '/tenant_id' '/user_id' - '/thread_id' ] } indexingPolicy: { @@ -258,6 +262,10 @@ resource memoriesSummariesContainer 'Microsoft.DocumentDB/databaseAccounts/sqlDa ] compositeIndexes: [ [ + { + path: '/tenant_id' + order: 'ascending' + } { path: '/user_id' order: 'ascending' @@ -335,8 +343,8 @@ resource counterContainer 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/co kind: 'MultiHash' version: 2 paths: [ + '/tenant_id' '/user_id' - '/thread_id' ] } // 90 days: every counter document expires this long after its last update diff --git a/infra/modules/functions.bicep b/infra/modules/functions.bicep index 2bca9d1..a9b5989 100644 --- a/infra/modules/functions.bicep +++ b/infra/modules/functions.bicep @@ -70,19 +70,19 @@ param azureOpenAiApiVersion string // in main.bicep - these module params are declared without defaults so // main.bicep stays the single source of truth. -@description('Run thread-summary orchestration every N turns within a (user_id, thread_id). 0 = disabled.') +@description('Run thread-summary orchestration every N turns within a (tenant_id, user_id, thread_id). 0 = disabled.') param threadSummaryEveryN int -@description('Run fact extraction every N turns within a (user_id, thread_id); reconcile and procedure learning run on multiples of it. 0 = disabled (all three).') +@description('Run fact extraction every N turns within a (tenant_id, user_id, thread_id); reconcile and procedure learning run on multiples of it. 0 = disabled (all three).') param factExtractionEveryN int @description('Once per N fact extractions, run reconcile, then procedure learning. Effective cadence = factExtractionEveryN * dedupEveryN turns. 0 = disabled.') param dedupEveryN int -@description('Run user-summary orchestration every N turns from a given user_id across all threads. 0 = disabled.') +@description('Run user-summary orchestration every N turns from a given (tenant_id, user_id) across all threads. 0 = disabled.') param userSummaryEveryN int -@description('Evaluate an episode boundary every N turns within a (user_id, thread_id). 0 = disabled (no episodic memory).') +@description('Evaluate an episode boundary every N turns within a (tenant_id, user_id, thread_id). 0 = disabled (no episodic memory).') param episodeEvalEveryN int @description('Idle gap (seconds) between two consecutive turns that closes the open episode.') diff --git a/tests/conftest.py b/tests/conftest.py index d239fbb..277f194 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -154,6 +154,12 @@ def chat_deployment_name(): return os.environ.get("AI_FOUNDRY_CHAT_DEPLOYMENT_NAME", "gpt-4o-mini") +@pytest.fixture(scope="session") +def integration_tenant_id(): + """The tenant the integration tests run in: not the default one, so a hard-coded default tenant fails them.""" + return "integration-tests" + + @pytest.fixture def unique_user_id(): """Unique user ID to isolate integration test data.""" diff --git a/tests/integration/test_async_full_pipeline.py b/tests/integration/test_async_full_pipeline.py index 722d649..2bb8812 100644 --- a/tests/integration/test_async_full_pipeline.py +++ b/tests/integration/test_async_full_pipeline.py @@ -25,6 +25,7 @@ import pytest +from azure.cosmos.agent_memory._partitioning import OWNER_FILTER, owner_parameters, partition_key_for from azure.cosmos.agent_memory.aio.cosmos_memory_client import AsyncCosmosMemoryClient from tests.conftest import INTEGRATION_ENABLED @@ -68,6 +69,7 @@ async def async_agent_memory( embedding_deployment_name, embedding_dimensions, chat_deployment_name, + integration_tenant_id, ): """A live AsyncCosmosMemoryClient with its containers provisioned/connected.""" if not cosmos_endpoint or not ai_foundry_endpoint: @@ -83,6 +85,7 @@ async def async_agent_memory( embedding_deployment_name=embedding_deployment_name, embedding_dimensions=embedding_dimensions, chat_deployment_name=chat_deployment_name, + tenant_id=integration_tenant_id, ) # The async client cannot auto-connect in __init__; do it explicitly. await client.create_memory_store() @@ -110,8 +113,9 @@ async def _async_add_turns( async def _async_cleanup(mem: AsyncCosmosMemoryClient, user_id: str) -> None: """Best-effort delete of every document for *user_id* across all containers.""" - sql = "SELECT c.id, c.thread_id FROM c WHERE c.user_id = @uid" - params = [{"name": "@uid", "value": user_id}] + partition_key = partition_key_for(mem.tenant_id, user_id) + sql = f"SELECT c.id FROM c WHERE {OWNER_FILTER}" + params = owner_parameters(mem.tenant_id, user_id) for container in ( mem._turns_container_client, mem._memories_container_client, @@ -120,15 +124,14 @@ async def _async_cleanup(mem: AsyncCosmosMemoryClient, user_id: str) -> None: if container is None: continue try: - docs = [doc async for doc in container.query_items(query=sql, parameters=params)] + docs = [ + doc async for doc in container.query_items(query=sql, parameters=params, partition_key=partition_key) + ] except Exception: continue for doc in docs: try: - await container.delete_item( - item=doc["id"], - partition_key=[user_id, doc.get("thread_id", "")], - ) + await container.delete_item(item=doc["id"], partition_key=partition_key) except Exception: pass @@ -145,8 +148,9 @@ async def _async_seed_fact_with_embedding( sync helper). Retries through transient embedding-service blips so the extract-time vector floor always has a neighbour; skips honestly if the embedding service is genuinely unavailable.""" - check = "SELECT c.id FROM c WHERE c.user_id = @uid AND c.content = @content AND IS_DEFINED(c.embedding)" - params = [{"name": "@uid", "value": user_id}, {"name": "@content", "value": content}] + check = f"SELECT c.id FROM c WHERE {OWNER_FILTER} AND c.content = @content AND IS_DEFINED(c.embedding)" + params = [*owner_parameters(mem.tenant_id, user_id), {"name": "@content", "value": content}] + partition_key = partition_key_for(mem.tenant_id, user_id) for _ in range(retries): await mem.upsert_memory( user_id=user_id, @@ -156,7 +160,12 @@ async def _async_seed_fact_with_embedding( thread_id=thread_id, salience=0.7, ) - embedded = [doc async for doc in mem._memories_container_client.query_items(query=check, parameters=params)] + embedded = [ + doc + async for doc in mem._memories_container_client.query_items( + query=check, parameters=params, partition_key=partition_key + ) + ] if embedded: return await asyncio.sleep(1) diff --git a/tests/integration/test_changefeed_integration.py b/tests/integration/test_changefeed_integration.py index f6a702d..aad6447 100644 --- a/tests/integration/test_changefeed_integration.py +++ b/tests/integration/test_changefeed_integration.py @@ -13,7 +13,9 @@ change-feed trigger configured is required, along with the ``turns``, ``counter``, and ``leases`` containers. Post container-split, the change-feed trigger binds to the ``turns`` container - turn documents must be inserted -there, not into ``memories``. +there, not into ``memories``. The Function App reads ``tenant_id`` from each +changed turn, so the turns carry one, and a counter lives in the +``[tenant_id, user_id]`` partition of its owner. """ import os @@ -65,9 +67,10 @@ def cosmos_clients(): @pytest.fixture -def unique_ids(): - """Generate unique user_id and thread_id for test isolation.""" +def unique_ids(integration_tenant_id): + """Generate a unique user_id and thread_id for test isolation, in the integration tenant.""" return { + "tenant_id": integration_tenant_id, "user_id": f"test-user-{uuid.uuid4().hex[:8]}", "thread_id": f"test-thread-{uuid.uuid4().hex[:8]}", } @@ -76,10 +79,11 @@ def unique_ids(): class TestChangeFeedIntegration: """Integration tests for change feed trigger with live Cosmos DB.""" - def _insert_turn(self, turns_container, user_id, thread_id): + def _insert_turn(self, turns_container, tenant_id, user_id, thread_id): """Insert a single turn document into the turns container.""" doc = { "id": str(uuid.uuid4()), + "tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id, "role": "user", @@ -91,12 +95,12 @@ def _insert_turn(self, turns_container, user_id, thread_id): turns_container.upsert_item(body=doc) return doc - def _read_counter(self, counter_container, counter_id, user_id, thread_id): + def _read_counter(self, counter_container, counter_id, tenant_id, user_id): """Read a counter document, returning None if not found.""" from azure.cosmos.exceptions import CosmosResourceNotFoundError try: - return counter_container.read_item(item=counter_id, partition_key=[user_id, thread_id]) + return counter_container.read_item(item=counter_id, partition_key=[tenant_id, user_id]) except CosmosResourceNotFoundError: return None @@ -108,19 +112,20 @@ def test_counter_increments_on_turn_insert(self, cosmos_clients, unique_ids): waiting for the change feed to process them. """ turns, counters = cosmos_clients + tenant_id = unique_ids["tenant_id"] user_id = unique_ids["user_id"] thread_id = unique_ids["thread_id"] counter_id = f"thread:{user_id}:{thread_id}" # Insert 3 turn documents for _ in range(3): - self._insert_turn(turns, user_id, thread_id) + self._insert_turn(turns, tenant_id, user_id, thread_id) # Poll for counter to appear (change feed has latency) deadline = time.time() + 60 counter_doc = None while time.time() < deadline: - counter_doc = self._read_counter(counters, counter_id, user_id, thread_id) + counter_doc = self._read_counter(counters, counter_id, tenant_id, user_id) if counter_doc and counter_doc.get("count", 0) >= 3: break time.sleep(3) @@ -128,4 +133,5 @@ def test_counter_increments_on_turn_insert(self, cosmos_clients, unique_ids): assert counter_doc is not None, ( f"Counter {counter_id} was not created within 60s. Is the change feed trigger running?" ) + assert counter_doc["tenant_id"] == tenant_id assert counter_doc["count"] >= 3, f"Expected counter >= 3, got {counter_doc['count']}" diff --git a/tests/integration/test_episodic_pipeline.py b/tests/integration/test_episodic_pipeline.py index 7505c18..a989121 100644 --- a/tests/integration/test_episodic_pipeline.py +++ b/tests/integration/test_episodic_pipeline.py @@ -12,6 +12,7 @@ import pytest from azure.cosmos.agent_memory import CosmosMemoryClient +from azure.cosmos.agent_memory._partitioning import OWNER_FILTER, owner_parameters, partition_key_for from tests.conftest import INTEGRATION_ENABLED pytestmark = [ @@ -35,6 +36,7 @@ def episodic_memory( embedding_deployment_name, embedding_dimensions, chat_deployment_name, + integration_tenant_id, ): """Live client using AAD for Cosmos and existing containers only.""" if not cosmos_endpoint or not ai_foundry_endpoint: @@ -49,6 +51,7 @@ def episodic_memory( embedding_dimensions=embedding_dimensions, chat_deployment_name=chat_deployment_name, use_default_credential=True, + tenant_id=integration_tenant_id, cadence_thresholds={ "FACT_EXTRACTION_EVERY_N": 1_000_000, "EPISODE_EVAL_EVERY_N": 1_000_000, @@ -70,29 +73,21 @@ def episodic_memory( def _delete_user_records(mem: CosmosMemoryClient, user_id: str) -> None: - query = "SELECT c.id, c.thread_id FROM c WHERE c.user_id = @user_id" - params = [{"name": "@user_id", "value": user_id}] + partition_key = partition_key_for(mem.tenant_id, user_id) + query = f"SELECT c.id FROM c WHERE {OWNER_FILTER}" + params = owner_parameters(mem.tenant_id, user_id) for container in ( mem._turns_container_client, mem._memories_container_client, mem._summaries_container_client, ): try: - docs = list( - container.query_items( - query=query, - parameters=params, - enable_cross_partition_query=True, - ) - ) + docs = list(container.query_items(query=query, parameters=params, partition_key=partition_key)) except Exception: continue for doc in docs: try: - container.delete_item( - item=doc["id"], - partition_key=[user_id, doc.get("thread_id", "")], - ) + container.delete_item(item=doc["id"], partition_key=partition_key) except Exception: pass diff --git a/tests/integration/test_full_pipeline.py b/tests/integration/test_full_pipeline.py index e8a799f..3d8f64e 100644 --- a/tests/integration/test_full_pipeline.py +++ b/tests/integration/test_full_pipeline.py @@ -26,6 +26,7 @@ import pytest from azure.cosmos.agent_memory import CosmosMemoryClient +from azure.cosmos.agent_memory._partitioning import OWNER_FILTER, owner_parameters, partition_key_for from tests.conftest import INTEGRATION_ENABLED # What ``reconcile`` returns: the facts checked that stay active (``kept``), the duplicates folded (``merged``), @@ -68,6 +69,7 @@ def agent_memory( embedding_deployment_name, embedding_dimensions, chat_deployment_name, + integration_tenant_id, ): """A live CosmosMemoryClient shared by every test in this module.""" if not cosmos_endpoint or not ai_foundry_endpoint: @@ -83,6 +85,7 @@ def agent_memory( embedding_deployment_name=embedding_deployment_name, embedding_dimensions=embedding_dimensions, chat_deployment_name=chat_deployment_name, + tenant_id=integration_tenant_id, ) @@ -106,35 +109,23 @@ def _cleanup(mem: CosmosMemoryClient, user_id: str) -> None: """Best-effort delete of every memory belonging to *user_id* across all split containers (turns, memories, summaries) so consecutive runs on the same user_id do not accumulate residue.""" - - def _delete(container, doc: dict) -> None: - try: - container.delete_item( - item=doc["id"], - partition_key=[user_id, doc.get("thread_id", "")], - ) - except Exception: - pass - - sql = "SELECT c.id, c.thread_id FROM c WHERE c.user_id = @uid" - params = [{"name": "@uid", "value": user_id}] + partition_key = partition_key_for(mem.tenant_id, user_id) + sql = f"SELECT c.id FROM c WHERE {OWNER_FILTER}" + params = owner_parameters(mem.tenant_id, user_id) for container in ( mem._turns_container_client, mem._memories_container_client, mem._summaries_container_client, ): try: - docs = list( - container.query_items( - query=sql, - parameters=params, - enable_cross_partition_query=True, - ) - ) + docs = list(container.query_items(query=sql, parameters=params, partition_key=partition_key)) except Exception: continue for doc in docs: - _delete(container, doc) + try: + container.delete_item(item=doc["id"], partition_key=partition_key) + except Exception: + pass def _seed_fact_with_embedding( @@ -153,8 +144,8 @@ def _seed_fact_with_embedding( neighbour to match. Retry until an embedded copy exists (indexing is fast - the doc is vector-searchable within ~2s), and skip honestly if the embedding service is genuinely unavailable rather than reporting a false failure.""" - check = "SELECT c.id FROM c WHERE c.user_id = @uid AND c.content = @content AND IS_DEFINED(c.embedding)" - params = [{"name": "@uid", "value": user_id}, {"name": "@content", "value": content}] + check = f"SELECT c.id FROM c WHERE {OWNER_FILTER} AND c.content = @content AND IS_DEFINED(c.embedding)" + params = [*owner_parameters(mem.tenant_id, user_id), {"name": "@content", "value": content}] for _ in range(retries): mem.upsert_memory( user_id=user_id, @@ -166,7 +157,7 @@ def _seed_fact_with_embedding( ) embedded = list( mem._memories_container_client.query_items( - query=check, parameters=params, enable_cross_partition_query=True + query=check, parameters=params, partition_key=partition_key_for(mem.tenant_id, user_id) ) ) if embedded: @@ -375,14 +366,12 @@ def test_add_remove_tags_and_salience_filter(self, agent_memory, unique_user_id, agent_memory.add_tags( memory_id=mid, user_id=unique_user_id, - thread_id=unique_thread_id, memory_type="fact", tags=["ui"], ) agent_memory.remove_tags( memory_id=mid, user_id=unique_user_id, - thread_id=unique_thread_id, memory_type="fact", tags=["ide"], ) @@ -484,11 +473,12 @@ def test_reconcile_links_conflicting_facts_and_retires_neither( links = list( agent_memory._memories_container_client.query_items( - query="SELECT c.first, c.later, c.kind FROM c WHERE c.type = 'conflict_link'", - partition_key=[unique_user_id, "__conflicts__"], + query=f"SELECT c.first, c.later, c.kind FROM c WHERE {OWNER_FILTER} AND c.type = 'conflict_link'", + parameters=owner_parameters(agent_memory.tenant_id, unique_user_id), + partition_key=partition_key_for(agent_memory.tenant_id, unique_user_id), ) ) - assert links, "Expected a link document in the user's __conflicts__ partition" + assert links, "Expected a link document in the owner's partition" assert {fact_id for link in links for fact_id in (link["first"], link["later"])} <= { m["id"] for m in active } diff --git a/tests/integration/test_procedural_pipeline.py b/tests/integration/test_procedural_pipeline.py index 03573f7..e2856b0 100644 --- a/tests/integration/test_procedural_pipeline.py +++ b/tests/integration/test_procedural_pipeline.py @@ -13,6 +13,7 @@ import pytest from azure.cosmos.agent_memory import CosmosMemoryClient +from azure.cosmos.agent_memory._partitioning import OWNER_FILTER, owner_parameters, partition_key_for from azure.cosmos.agent_memory.services._procedures import procedure_status pytestmark = [ @@ -34,6 +35,7 @@ def procedural_memory( embedding_deployment_name, embedding_dimensions, chat_deployment_name, + integration_tenant_id, ): """Live client using AAD for Cosmos and existing containers only.""" if not cosmos_endpoint or not ai_foundry_endpoint: @@ -48,6 +50,7 @@ def procedural_memory( embedding_dimensions=embedding_dimensions, chat_deployment_name=chat_deployment_name, use_default_credential=True, + tenant_id=integration_tenant_id, cadence_thresholds={ "FACT_EXTRACTION_EVERY_N": 1_000_000, "EPISODE_EVAL_EVERY_N": 1_000_000, @@ -69,29 +72,21 @@ def procedural_memory( def _delete_user_records(mem: CosmosMemoryClient, user_id: str) -> None: - query = "SELECT c.id, c.thread_id FROM c WHERE c.user_id = @user_id" - params = [{"name": "@user_id", "value": user_id}] + partition_key = partition_key_for(mem.tenant_id, user_id) + query = f"SELECT c.id FROM c WHERE {OWNER_FILTER}" + params = owner_parameters(mem.tenant_id, user_id) for container in ( mem._turns_container_client, mem._memories_container_client, mem._summaries_container_client, ): try: - docs = list( - container.query_items( - query=query, - parameters=params, - enable_cross_partition_query=True, - ) - ) + docs = list(container.query_items(query=query, parameters=params, partition_key=partition_key)) except Exception: continue for doc in docs: try: - container.delete_item( - item=doc["id"], - partition_key=[user_id, doc.get("thread_id", "")], - ) + container.delete_item(item=doc["id"], partition_key=partition_key) except Exception: pass diff --git a/tests/integration/test_ttl_lifecycle.py b/tests/integration/test_ttl_lifecycle.py index e7d4a23..30264b2 100644 --- a/tests/integration/test_ttl_lifecycle.py +++ b/tests/integration/test_ttl_lifecycle.py @@ -39,6 +39,7 @@ def ttl_client( cosmos_key, cosmos_database, cosmos_container, + integration_tenant_id, ): if not cosmos_endpoint: pytest.skip("COSMOS_DB_ENDPOINT not set") @@ -48,6 +49,7 @@ def ttl_client( cosmos_database=cosmos_database, cosmos_container=cosmos_container, cosmos_turns_container=os.environ.get("COSMOS_DB_TURNS_CONTAINER") or None, + tenant_id=integration_tenant_id, ) @@ -76,11 +78,9 @@ def _find_memory( return None -def _delete_if_present( - client: CosmosMemoryClient, memory_id: str, user_id: str, thread_id: str, memory_type: str -) -> None: +def _delete_if_present(client: CosmosMemoryClient, memory_id: str, user_id: str, memory_type: str) -> None: try: - client.delete_memory(memory_id=memory_id, user_id=user_id, thread_id=thread_id, memory_type=memory_type) + client.delete_memory(memory_id=memory_id, user_id=user_id, memory_type=memory_type) except Exception: pass @@ -115,6 +115,6 @@ def test_turn_ttl_expires_while_episodic_persists(ttl_client: CosmosMemoryClient assert _find_memory(ttl_client, user_id, thread_id, episodic_id, ["episodic"]) is not None finally: if turn_id: - _delete_if_present(ttl_client, turn_id, user_id, thread_id, "turn") + _delete_if_present(ttl_client, turn_id, user_id, "turn") if episodic_id: - _delete_if_present(ttl_client, episodic_id, user_id, thread_id, "episodic") + _delete_if_present(ttl_client, episodic_id, user_id, "episodic") diff --git a/tests/unit/aio/processors/test_base.py b/tests/unit/aio/processors/test_base.py index 26dc70d..e8eea86 100644 --- a/tests/unit/aio/processors/test_base.py +++ b/tests/unit/aio/processors/test_base.py @@ -32,3 +32,17 @@ def test_async_inprocess_requires_pipeline_or_components(): with pytest.raises(ValueError): AsyncInProcessProcessor() + + +def test_async_inprocess_built_from_components_belongs_to_the_tenant_it_is_given(): + proc = AsyncInProcessProcessor( + cosmos_container=MagicMock(), + turns_container=MagicMock(), + summaries_container=MagicMock(), + chat_client=MagicMock(), + embeddings_client=MagicMock(), + tenant_id="acme", + ) + + assert proc._pipeline._store.tenant_id == "acme" + assert proc._pipeline._tenant_id == "acme" diff --git a/tests/unit/aio/services/test_episodic_retrieval_async.py b/tests/unit/aio/services/test_episodic_retrieval_async.py index beabc80..521c936 100644 --- a/tests/unit/aio/services/test_episodic_retrieval_async.py +++ b/tests/unit/aio/services/test_episodic_retrieval_async.py @@ -9,6 +9,7 @@ from azure.cosmos.agent_memory.aio.store import AsyncMemoryStore EPISODIC_OPT_IN_WARNING = "Episodic memories requested via memory_types are only returned when include_episodes=True" +TENANT = "acme" class AsyncIterator: @@ -26,7 +27,7 @@ async def __anext__(self): def _connected_client() -> tuple[AsyncCosmosMemoryClient, MagicMock]: - client = AsyncCosmosMemoryClient(use_default_credential=False) + client = AsyncCosmosMemoryClient(use_default_credential=False, tenant_id=TENANT) memories = MagicMock() turns = MagicMock() summaries = MagicMock() @@ -64,12 +65,12 @@ async def test_async_get_episodes_user_wide_newest_first(): assert [doc["id"] for doc in results] == ["ep-new", "ep-old"] call_kwargs = memories.query_items.call_args.kwargs assert "SELECT TOP @recent_k * FROM c" in call_kwargs["query"] - assert "c.user_id = @user_id" in call_kwargs["query"] + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in call_kwargs["query"] assert "c.type = @type" in call_kwargs["query"] assert "ORDER BY c.created_at DESC" in call_kwargs["query"] - assert "partition_key" not in call_kwargs + assert call_kwargs["partition_key"] == [TENANT, "u1"] params = _params_by_name(call_kwargs) - assert params["@user_id"] == "u1" + assert (params["@tenant_id"], params["@user_id"]) == (TENANT, "u1") assert params["@type"] == "episodic" assert params["@recent_k"] == 2 @@ -168,7 +169,7 @@ async def test_async_search_cosmos_include_episodes_combined_query_hits_real_sto memories.query_items = MagicMock(return_value=AsyncIterator([])) embeddings = MagicMock() embeddings.generate = AsyncMock(return_value=[0.1, 0.2]) - store = AsyncMemoryStore(containers=_containers(memories=memories), embeddings_client=embeddings) + store = AsyncMemoryStore(containers=_containers(memories=memories), embeddings_client=embeddings, tenant_id=TENANT) mem, _ = _connected_client() mem._get_store = MagicMock(return_value=store) @@ -188,7 +189,9 @@ async def test_async_search_cosmos_include_episodes_combined_query_hits_real_sto # caller's filters applied uniformly. assert memories.query_items.call_count == 1 call_kwargs = memories.query_items.call_args.kwargs + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in call_kwargs["query"] params = _params_by_name(call_kwargs) + assert (params["@tenant_id"], params["@user_id"]) == (TENANT, "u1") type_values = {v for k, v in params.items() if k.startswith("@memory_type")} assert type_values == {"fact", "episodic"} assert params["@min_salience"] == 0.5 @@ -200,7 +203,7 @@ async def test_async_search_episodic_temporal_filters_do_not_rank_by_time(): memories.query_items.return_value = AsyncIterator([]) embeddings = MagicMock() embeddings.generate = AsyncMock(return_value=[0.1, 0.2]) - store = AsyncMemoryStore(containers=_containers(memories=memories), embeddings_client=embeddings) + store = AsyncMemoryStore(containers=_containers(memories=memories), embeddings_client=embeddings, tenant_id=TENANT) created_after = datetime(2026, 1, 1, tzinfo=timezone.utc) await store.search_episodic( diff --git a/tests/unit/aio/services/test_mark_turns_extracted_async.py b/tests/unit/aio/services/test_mark_turns_extracted_async.py index 4369dfc..bdb669a 100644 --- a/tests/unit/aio/services/test_mark_turns_extracted_async.py +++ b/tests/unit/aio/services/test_mark_turns_extracted_async.py @@ -62,9 +62,13 @@ def __init__(self, container: Any): self._containers = {ContainerKey.TURNS: container} +TENANT = "acme" + + def _turn_doc(**overrides: Any) -> dict[str, Any]: doc = { "id": "turn-1", + "tenant_id": TENANT, "user_id": "u1", "thread_id": "t1", "type": "turn", @@ -88,6 +92,7 @@ def _service(turns_container: Any) -> AsyncPipelineService: ContainerKey.MEMORIES: _AsyncStoreContainerAdapter(memories_store, ContainerKey.MEMORIES), ContainerKey.SUMMARIES: _AsyncStoreContainerAdapter(summaries_store, ContainerKey.SUMMARIES), }, + tenant_id=TENANT, ) @@ -102,7 +107,7 @@ async def test_mark_turns_extracted_patches_extracted_at() -> None: assert turns_container.patch_calls == [ { "item": "turn-1", - "partition_key": ["u1", "t1"], + "partition_key": [TENANT, "u1"], "patch_operations": [ {"op": "set", "path": "/extracted_at", "value": turns_container.docs[0]["extracted_at"]} ], diff --git a/tests/unit/aio/services/test_procedural_retrieval_async.py b/tests/unit/aio/services/test_procedural_retrieval_async.py index 4e16d9a..ee2470d 100644 --- a/tests/unit/aio/services/test_procedural_retrieval_async.py +++ b/tests/unit/aio/services/test_procedural_retrieval_async.py @@ -6,6 +6,8 @@ from azure.cosmos.agent_memory._container_routing import ContainerKey from azure.cosmos.agent_memory.aio.store import AsyncMemoryStore +TENANT = "acme" + class AsyncIterator: def __init__(self, items: list[dict[str, Any]]) -> None: @@ -29,6 +31,10 @@ def _containers(*, memories: Any = None, turns: Any = None, summaries: Any = Non } +def _store(memories: Any, embeddings: Any) -> AsyncMemoryStore: + return AsyncMemoryStore(containers=_containers(memories=memories), embeddings_client=embeddings, tenant_id=TENANT) + + def _params_by_name(call_kwargs: dict[str, Any]) -> dict[str, Any]: return {param["name"]: param["value"] for param in call_kwargs["parameters"]} @@ -42,7 +48,7 @@ async def test_async_retrieve_procedures_filters_active_procedures_by_default() memories.query_items.return_value = AsyncIterator(ranked_docs) embeddings = MagicMock() embeddings.generate = AsyncMock(return_value=[0.1, 0.2]) - store = AsyncMemoryStore(containers=_containers(memories=memories), embeddings_client=embeddings) + store = _store(memories, embeddings) result = await store.retrieve_procedures("u1", "cosmos db retry", top_k=2) @@ -50,13 +56,14 @@ async def test_async_retrieve_procedures_filters_active_procedures_by_default() call_kwargs = memories.query_items.call_args.kwargs assert "TOP 2" in call_kwargs["query"] assert "c.type = @type" in call_kwargs["query"] - assert "c.user_id = @user_id" in call_kwargs["query"] + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in call_kwargs["query"] assert "c.status = @status" in call_kwargs["query"] assert "VectorDistance(c.embedding, @embedding)" in call_kwargs["query"] assert "(NOT IS_DEFINED(c.superseded_by) OR IS_NULL(c.superseded_by))" in call_kwargs["query"] + assert "partition_key" not in call_kwargs, "a keyword search is not sent with a partition key" params = _params_by_name(call_kwargs) assert params["@type"] == "procedural" - assert params["@user_id"] == "u1" + assert (params["@tenant_id"], params["@user_id"]) == (TENANT, "u1") assert params["@status"] == "active" assert params["@embedding"] == [0.1, 0.2] assert params["@kw0"] == "cosmos" @@ -68,7 +75,7 @@ async def test_async_retrieve_procedures_status_none_drops_status_filter() -> No memories.query_items.return_value = AsyncIterator(ranked_docs) embeddings = MagicMock() embeddings.generate = AsyncMock(return_value=[0.3, 0.4]) - store = AsyncMemoryStore(containers=_containers(memories=memories), embeddings_client=embeddings) + store = _store(memories, embeddings) result = await store.retrieve_procedures("u1", "partition key", status=None) @@ -78,7 +85,7 @@ async def test_async_retrieve_procedures_status_none_drops_status_filter() -> No assert "c.status = @status" not in call_kwargs["query"] params = _params_by_name(call_kwargs) assert params["@type"] == "procedural" - assert params["@user_id"] == "u1" + assert (params["@tenant_id"], params["@user_id"]) == (TENANT, "u1") assert "@status" not in params @@ -88,7 +95,7 @@ async def test_async_retrieve_procedures_filters_by_kind_and_can_include_superse memories.query_items.return_value = AsyncIterator(ranked_docs) embeddings = MagicMock() embeddings.generate = AsyncMock(return_value=[0.5, 0.6]) - store = AsyncMemoryStore(containers=_containers(memories=memories), embeddings_client=embeddings) + store = _store(memories, embeddings) result = await store.retrieve_procedures( "u1", diff --git a/tests/unit/aio/services/test_procedural_synthesis_and_context_async.py b/tests/unit/aio/services/test_procedural_synthesis_and_context_async.py index 253b473..dd32e25 100644 --- a/tests/unit/aio/services/test_procedural_synthesis_and_context_async.py +++ b/tests/unit/aio/services/test_procedural_synthesis_and_context_async.py @@ -22,8 +22,9 @@ procedure_id, ) from tests.unit.services.test_procedural_synthesis_and_context import ( - PROCEDURAL_PARTITION, + OWNER_PARTITION, STEPS, + TENANT, Chat, Embeddings, Memories, @@ -58,20 +59,13 @@ async def __anext__(self) -> dict[str, Any]: class AsyncMemories: - """The in-memory container behind awaitable methods, as the async Cosmos client exposes it. A query without a - partition reads every partition, which the async client does without being asked.""" + """The in-memory container behind awaitable methods, as the async Cosmos client exposes it.""" def __init__(self, inner: Memories) -> None: self.inner = inner def query_items(self, *, query: str, parameters: Any = None, partition_key: Any = None) -> AsyncRows: - rows = self.inner.query_items( - query=query, - parameters=parameters, - partition_key=partition_key, - enable_cross_partition_query=partition_key is None, - ) - return AsyncRows(rows) + return AsyncRows(self.inner.query_items(query=query, parameters=parameters, partition_key=partition_key)) async def read_item(self, *, item: str, partition_key: Any) -> dict[str, Any]: return self.inner.read_item(item=item, partition_key=partition_key) @@ -98,8 +92,8 @@ def _service( ) -> tuple[AsyncPipelineService, AsyncChat]: chat, embeddings = AsyncChat(responses), AsyncEmbeddings(vectors) containers = containers_for(AsyncMemories(memories)) - store = AsyncMemoryStore(containers=containers, embeddings_client=embeddings) - return AsyncPipelineService(store, chat, embeddings, containers=containers), chat + store = AsyncMemoryStore(containers=containers, embeddings_client=embeddings, tenant_id=TENANT) + return AsyncPipelineService(store, chat, embeddings, containers=containers, tenant_id=TENANT), chat # --------------------------------------------------------------------------- @@ -130,7 +124,12 @@ async def test_a_taught_instruction_is_active_with_its_support_recorded() -> Non ) assert (created["source_kind"], created["source_authority"]) == ("explicit_user_instruction", "high") assert created["id"] == procedure_id("u1", "instruction", "Run targeted tests") - assert (created["user_id"], created["thread_id"], created["embedding"]) == ("u1", "__procedural__", [1.0]) + assert (created["tenant_id"], created["user_id"], created["thread_id"], created["embedding"]) == ( + TENANT, + "u1", + "__procedural__", + [1.0], + ) assert (created["prompt_id"], created["prompt_version"]) == ("extract_procedure.prompty", "v6") assert "Never write a literal secret" in prompt_text(chat, 0) @@ -461,16 +460,51 @@ async def test_the_users_nearest_existing_procedures_are_shown_so_the_model_can_ assert "Far 1" not in prompt_text(chat, 0) -async def test_procedures_and_the_cursor_live_in_the_users_procedural_partition() -> None: +async def test_procedures_and_the_cursor_live_in_the_owners_partition() -> None: memories = Memories([fact(), fact("fact-theirs", "Their rule.", user_id="u2")]) service, _ = _service(memories, [{"procedures": [answer()]}]) await service.synthesize_procedural("u1") created = procedures_by_name(memories)["Run targeted tests"] - assert memories.read_item(item=created["id"], partition_key=PROCEDURAL_PARTITION)["name"] == created["name"] - cursor = memories.read_item(item="procedure_cursor", partition_key=PROCEDURAL_PARTITION) - assert (cursor["type"], cursor["user_id"], cursor["thread_id"]) == ("procedure_cursor", "u1", "__procedural__") + assert memories.read_item(item=created["id"], partition_key=OWNER_PARTITION)["name"] == created["name"] + cursor = memories.read_item(item="procedure_cursor", partition_key=OWNER_PARTITION) + assert (cursor["type"], cursor["tenant_id"], cursor["user_id"], cursor["thread_id"]) == ( + "procedure_cursor", + TENANT, + "u1", + "__procedural__", + ) + assert not any(doc["user_id"] == "u2" and doc.get("type") != "fact" for doc in memories.docs) + + +async def test_every_query_of_the_procedure_pass_filters_on_the_tenant_and_reads_the_owners_partition() -> None: + memories = Memories([fact(), episode(), procedure("Existing")]) + service, _ = _service(memories, [{"procedures": [answer()]}]) + + await service.synthesize_procedural("u1") + + assert len(memories.queries) >= 3 + for sql, params, partition in memories.queries: + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in sql + assert (params["@tenant_id"], params["@user_id"], partition) == (TENANT, "u1", OWNER_PARTITION) + + +async def test_the_procedure_pass_stays_inside_its_tenant() -> None: + theirs = [ + fact("fact-theirs", "Another tenant's rule for the same user id.", tenant_id="other"), + {**procedure("Theirs"), "tenant_id": "other"}, + ] + memories = Memories([fact(), *theirs]) + service, chat = _service(memories, [{"procedures": [answer()]}]) + + await service.synthesize_procedural("u1") + + assert "Another tenant" not in prompt_text(chat, 0) and "Theirs" not in prompt_text(chat, 0) + written = [doc for doc in memories.docs if doc["id"] not in {"fact-raw-1", "fact-theirs", theirs[1]["id"]}] + assert {doc["type"] for doc in written} == {"procedural", "procedure_cursor"} + assert {doc["tenant_id"] for doc in written} == {TENANT} + assert [doc for doc in memories.docs if doc["tenant_id"] == "other"] == theirs # --------------------------------------------------------------------------- @@ -830,6 +864,27 @@ async def test_build_procedural_context_lists_the_standing_rules_in_force() -> N assert await service.build_procedural_context("missing-user") == "" +async def test_build_procedural_context_reads_only_its_tenants_rules() -> None: + memories = Memories( + [rule("Mine"), rule("Reviews", applies="when", embedding=[0.0, 1.0]), {**rule("Theirs"), "tenant_id": "other"}] + ) + service, _ = _service(memories, [], vectors={"review": [0.0, 1.0]}) + + context = await service.build_procedural_context("u1", task="review") + + assert context.splitlines() == [ + STANDING_HEADER, + "- Mine rule.", + "", + SITUATIONAL_HEADER, + "- When working on Reviews: Reviews rule.", + ] + assert len(memories.queries) == 2 + for sql, params, partition in memories.queries: + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in sql + assert (params["@tenant_id"], params["@user_id"], partition) == (TENANT, "u1", OWNER_PARTITION) + + async def test_build_procedural_context_leaves_out_rules_written_before_procedures_were_learned_from_evidence() -> None: legacy = { key: value for key, value in rule("Legacy", procedure_kind="behavioral_policy").items() if key != "applies" diff --git a/tests/unit/aio/services/test_tenant_isolation_async.py b/tests/unit/aio/services/test_tenant_isolation_async.py new file mode 100644 index 0000000..dfb0661 --- /dev/null +++ b/tests/unit/aio/services/test_tenant_isolation_async.py @@ -0,0 +1,379 @@ +"""An async pipeline is bound to one tenant. + +Every query it sends filters on the tenant and names the owner's partition, ``[tenant_id, user_id]``; every point +operation names that partition; every document it writes carries the tenant. The containers here are in-memory doubles +that keep documents under ``[tenant_id, user_id]`` as a container with a hierarchical partition key does, answer a +query from the partition it names and from its ``@tenant_id``, ``@user_id``, ``@thread_id`` and type conditions, and +record every call. A second tenant holds records with the same user and thread ids, so a query, read or write that +forgot the tenant would find them, or miss its own. +""" + +from __future__ import annotations + +import copy +import json +import re +from typing import Any, Iterable, NamedTuple +from unittest.mock import AsyncMock, MagicMock + +import pytest +from azure.cosmos.exceptions import CosmosResourceExistsError, CosmosResourceNotFoundError + +from azure.cosmos.agent_memory._container_routing import ContainerKey +from azure.cosmos.agent_memory._utils import compute_content_hash +from azure.cosmos.agent_memory.aio.services.pipeline import AsyncPipelineService +from azure.cosmos.agent_memory.exceptions import ValidationError +from azure.cosmos.agent_memory.services._dedup import Verdict + +TENANT = "acme" +OTHER = "globex" +USER = "u1" +OWNER = [TENANT, USER] +OWNER_FILTER = "c.tenant_id = @tenant_id AND c.user_id = @user_id" + +_PARAMETER_FIELDS = { + "@tenant_id": "tenant_id", + "@user_id": "user_id", + "@thread_id": "thread_id", + "@memory_type": "type", + "@fact_type": "type", +} + + +class _Query(NamedTuple): + sql: str + params: dict[str, Any] + partition_key: Any + + +def _matches(doc: dict[str, Any], sql: str, params: dict[str, Any]) -> bool: + if any(name in params and doc.get(field) != params[name] for name, field in _PARAMETER_FIELDS.items()): + return False + if (found := re.search(r"c\.type = '(\w+)'", sql)) and doc.get("type") != found[1]: + return False + if (found := re.search(r"c\.type IN \(([^)]*)\)", sql)) and doc.get("type") not in re.findall(r"'(\w+)'", found[1]): + return False + if "NOT IS_DEFINED(c.extracted_at)" in sql and doc.get("extracted_at"): + return False + if "@last_at" in params and (doc["created_at"], doc["id"]) <= (params["@last_at"], params["@last_id"]): + return False + return True + + +class _Rows: + def __init__(self, rows: list[dict[str, Any]]) -> None: + self._rows = iter(rows) + + def __aiter__(self) -> _Rows: + return self + + async def __anext__(self) -> dict[str, Any]: + try: + return next(self._rows) + except StopIteration: + raise StopAsyncIteration + + +class _Container: + """Documents by ``(tenant_id, user_id, id)``; a point operation finds one only under the partition it names.""" + + def __init__(self, docs: Iterable[dict[str, Any]] = ()) -> None: + self.docs: dict[tuple[str, str, str], dict[str, Any]] = {} + self.queries: list[_Query] = [] + self.reads: list[tuple[str, list[str]]] = [] + for doc in docs: + self.put(doc) + + def put(self, doc: dict[str, Any]) -> dict[str, Any]: + self.docs[(doc["tenant_id"], doc["user_id"], doc["id"])] = copy.deepcopy(doc) + return doc + + def query_items(self, *, query: str, parameters: Any = None, partition_key: Any = None) -> _Rows: + params = {p["name"]: p["value"] for p in parameters or []} + self.queries.append(_Query(query, params, partition_key)) + rows = [ + copy.deepcopy(doc) + for (tenant, user, _), doc in self.docs.items() + if (partition_key is None or [tenant, user] == list(partition_key)) and _matches(doc, query, params) + ] + return _Rows(rows) + + async def read_item(self, *, item: str, partition_key: Any) -> dict[str, Any]: + self.reads.append((item, list(partition_key))) + found = self.docs.get((*partition_key, item)) + if found is None: + raise CosmosResourceNotFoundError(message=item) + return copy.deepcopy(found) + + async def create_item(self, *, body: dict[str, Any]) -> dict[str, Any]: + if (body["tenant_id"], body["user_id"], body["id"]) in self.docs: + raise CosmosResourceExistsError(message=body["id"]) + return self.put(body) + + async def upsert_item(self, *, body: dict[str, Any]) -> dict[str, Any]: + return self.put(body) + + async def replace_item(self, *, item: str, body: dict[str, Any], **kwargs: Any) -> dict[str, Any]: + del kwargs + if (body["tenant_id"], body["user_id"], item) not in self.docs: + raise CosmosResourceNotFoundError(message=item) + return self.put(body) + + async def patch_item(self, *, item: str, partition_key: Any, patch_operations: list[dict[str, Any]]) -> dict: + found = self.docs.get((*partition_key, item)) + if found is None: + raise CosmosResourceNotFoundError(message=item) + for operation in patch_operations: + found[operation["path"].removeprefix("/")] = operation["value"] + return copy.deepcopy(found) + + +class _Embeddings: + async def generate(self, text: str) -> list[float]: + del text + return [1.0, 0.0] + + async def generate_batch(self, texts: list[str]) -> list[list[float]]: + return [[1.0, 0.0] for _ in texts] + + +def _service( + tenant: str = TENANT, + *, + memories: _Container | None = None, + turns: _Container | None = None, + summaries: _Container | None = None, + replies: Iterable[dict[str, Any]] = (), +) -> AsyncPipelineService: + containers = { + ContainerKey.MEMORIES: memories if memories is not None else _Container(), + ContainerKey.TURNS: turns if turns is not None else _Container(), + ContainerKey.SUMMARIES: summaries if summaries is not None else _Container(), + } + store = MagicMock() + store.mark_superseded = AsyncMock(return_value=True) + service = AsyncPipelineService(store, MagicMock(), _Embeddings(), containers=containers, tenant_id=tenant) + service._run_prompty = AsyncMock(side_effect=[json.dumps(reply) for reply in replies]) + return service + + +def _turn(turn_id: str, tenant: str = TENANT, *, minute: int = 0) -> dict[str, Any]: + return { + "id": turn_id, + "tenant_id": tenant, + "user_id": USER, + "thread_id": "t1", + "type": "turn", + "role": "user", + "content": f"{tenant} turn {turn_id}: I like tea.", + "created_at": f"2025-01-01T00:{minute:02d}:00+00:00", + } + + +def _memory(memory_id: str, tenant: str = TENANT, kind: str = "fact", **fields: Any) -> dict[str, Any]: + return { + "id": memory_id, + "tenant_id": tenant, + "user_id": USER, + "thread_id": "t1", + "type": kind, + "role": "system", + "content": f"{tenant} {kind} {memory_id}", + "created_at": "2025-01-01T00:00:00+00:00", + **fields, + } + + +def _fact(fact_id: str, tenant: str = TENANT) -> dict[str, Any]: + """A fact as extraction builds it, ready to be persisted.""" + return _memory( + fact_id, + tenant, + content_hash=compute_content_hash(f"{tenant} fact {fact_id}"), + prompt_id="extract_memories-v3.prompty", + prompt_version="v3", + metadata={"category": "preference"}, + ) + + +def _assert_owner_scoped(queries: list[_Query]) -> None: + assert queries + for sql, params, partition_key in queries: + assert OWNER_FILTER in sql + assert (params["@tenant_id"], params["@user_id"], partition_key) == (TENANT, USER, OWNER) + + +@pytest.mark.parametrize("tenant", ["", " ", "acme/prod", "acme?", "a" * 300]) +def test_a_pipeline_refuses_a_tenant_that_cannot_key_a_record(tenant: str) -> None: + containers = {key: MagicMock() for key in ContainerKey} + + with pytest.raises(ValidationError): + AsyncPipelineService(MagicMock(), MagicMock(), _Embeddings(), containers=containers, tenant_id=tenant) + + +# --- extraction ----------------------------------------------------------------------------------------------- + + +async def test_extraction_reads_marks_and_writes_only_its_tenants_records(monkeypatch) -> None: + monkeypatch.delenv("AMT_EXTRACT_MEMORIES_PROMPT", raising=False) + turns = _Container([_turn("turn-a"), _turn("turn-g", OTHER)]) + memories, summaries = _Container(), _Container() + fact = {"text": "The user likes tea.", "category": "preference", "confidence": 0.9, "salience": 0.8, "tags": []} + service = _service(memories=memories, turns=turns, summaries=summaries, replies=[{"facts": [fact]}]) + + counts = await service.extract_memories(USER, "t1") + + assert counts["fact_count"] == 1 + [stored] = memories.docs.values() + assert (stored["tenant_id"], stored["user_id"], stored["thread_id"]) == (TENANT, USER, "t1") + assert turns.docs[(TENANT, USER, "turn-a")]["extracted_at"] + assert "extracted_at" not in turns.docs[(OTHER, USER, "turn-g")] + _assert_owner_scoped(turns.queries) + _assert_owner_scoped(memories.queries) + assert len(turns.queries) == 2, "the unextracted turns, then the turns before them" + assert summaries.reads == [("summary_u1_t1", OWNER)] + + +async def test_persisting_extracted_memories_stamps_the_tenant_and_refuses_another_tenants_records() -> None: + memories = _Container() + service = _service(memories=memories) + fact = {key: value for key, value in _fact("fact_1").items() if key != "tenant_id"} + + assert (await service.persist_extracted_memories(USER, {"facts": [fact]}))["fact_count"] == 1 + assert [doc["tenant_id"] for doc in memories.docs.values()] == [TENANT] + + with pytest.raises(ValidationError): + await service.persist_extracted_memories(USER, {"facts": [_fact("fact_2", OTHER)]}) + assert list(memories.docs) == [(TENANT, USER, "fact_1")] + + +async def test_a_document_written_straight_to_a_container_carries_the_tenant_or_is_refused() -> None: + memories = _Container() + service = _service(memories=memories) + bare = {"id": "episode-1", "user_id": USER, "thread_id": "t1", "type": "episodic", "content": "Tea."} + + await service._create_memory(bare) + + assert list(memories.docs) == [(TENANT, USER, "episode-1")] + with pytest.raises(ValidationError): + await service._create_memory({**bare, "id": "episode-2", "tenant_id": OTHER}) + assert list(memories.docs) == [(TENANT, USER, "episode-1")] + + +# --- episodes ------------------------------------------------------------------------------------------------- + + +async def test_episodes_and_their_cursor_live_in_the_owners_partition_of_each_tenant(monkeypatch) -> None: + monkeypatch.setenv("EPISODE_TOPIC_DRIFT", "0") + turns = _Container([_turn("turn-a", minute=1), _turn("turn-a2", minute=2), _turn("turn-g", OTHER, minute=3)]) + memories = _Container() + episode = {"title": "Tea", "summary": "The user talked about tea.", "events": [], "participants": ["user"]} + acme = _service(memories=memories, turns=turns, replies=[{"episodes": [episode]}]) + globex = _service(OTHER, memories=memories, turns=turns, replies=[{"episodes": [episode]}]) + + assert await acme.extract_episodes(USER, "t1", flush=True) == {"episodes": 1} + assert await acme.extract_episodes(USER, "t1", flush=True) == {"episodes": 0}, "its cursor is found again" + assert await globex.extract_episodes(USER, "t1", flush=True) == {"episodes": 1}, "and not shared with globex" + + cursors = [doc for doc in memories.docs.values() if doc["type"] == "episode_cursor"] + assert sorted((doc["tenant_id"], doc["last_episode_id"]) for doc in cursors) == [ + (TENANT, "turn-a2"), + (OTHER, "turn-g"), + ] + episodes = [doc for doc in memories.docs.values() if doc["type"] == "episodic"] + assert sorted(doc["tenant_id"] for doc in episodes) == [TENANT, OTHER] + assert all((doc["tenant_id"], doc["user_id"], doc["id"]) in memories.docs for doc in [*cursors, *episodes]) + acme_queries = [query for query in turns.queries if query.params["@tenant_id"] == TENANT] + _assert_owner_scoped(acme_queries) + assert ("episode_cursor_u1_t1", OWNER) in memories.reads + + +# --- summaries ------------------------------------------------------------------------------------------------ + + +async def test_a_thread_summary_is_read_and_written_in_the_owners_partition() -> None: + turns = _Container([_turn("turn-a"), _turn("turn-g", OTHER)]) + summaries = _Container() + reply = {"overview": "Tea.", "topics": []} + acme = _service(turns=turns, summaries=summaries, replies=[reply]) + globex = _service(OTHER, turns=turns, summaries=summaries, replies=[reply]) + + first = await acme.generate_thread_summary(USER, "t1") + second = await globex.generate_thread_summary(USER, "t1") + + assert (first["tenant_id"], second["tenant_id"]) == (TENANT, OTHER) + assert first["id"] == second["id"] == "summary_u1_t1" + assert set(summaries.docs) == {(TENANT, USER, "summary_u1_t1"), (OTHER, USER, "summary_u1_t1")} + assert summaries.reads == [("summary_u1_t1", OWNER), ("summary_u1_t1", [OTHER, USER])] + assert [(query.params["@tenant_id"], query.partition_key) for query in turns.queries] == [ + (TENANT, OWNER), + (OTHER, [OTHER, USER]), + ] + assert all(OWNER_FILTER in query.sql for query in turns.queries) + assert "acme turn" in acme._run_prompty.call_args.kwargs["inputs"]["transcript"] + assert "globex turn" not in acme._run_prompty.call_args.kwargs["inputs"]["transcript"] + + +async def test_a_user_summary_is_built_from_and_written_to_the_owners_partition() -> None: + memories = _Container([_memory("f-a"), _memory("f-g", OTHER)]) + summaries = _Container([_memory("summary_u1_t1", kind="thread_summary"), _memory("s-g", OTHER, "thread_summary")]) + service = _service(memories=memories, summaries=summaries, replies=[{"key_facts": ["Likes tea."], "topics": []}]) + + stored = await service.generate_user_summary(USER) + + assert (stored["tenant_id"], stored["user_id"], stored["thread_id"]) == (TENANT, USER, "__user_summary__") + assert (TENANT, USER, "user_summary_u1") in summaries.docs and len(summaries.docs) == 3 + assert summaries.reads == [("user_summary_u1", OWNER)] + _assert_owner_scoped(memories.queries) + _assert_owner_scoped(summaries.queries) + transcript = service._run_prompty.call_args.kwargs["inputs"]["transcript"] + assert "acme fact f-a" in transcript and "acme thread_summary summary_u1_t1" in transcript + assert "globex" not in transcript + + +@pytest.mark.parametrize( + ("persist", "summary_id", "kind"), + [ + pytest.param( + lambda service, doc: service.persist_thread_summary(USER, "t1", doc), + "summary_u1_t1", + "thread_summary", + id="thread-summary", + ), + pytest.param( + lambda service, doc: service.persist_user_summary(USER, doc), + "user_summary_u1", + "user_summary", + id="user-summary", + ), + ], +) +async def test_a_summary_naming_another_tenant_is_refused(persist, summary_id: str, kind: str) -> None: + summaries = _Container() + service = _service(summaries=summaries) + doc = _memory(summary_id, OTHER, kind, metadata={"thread_ids": ["t1"]}) + + with pytest.raises(ValidationError): + await persist(service, doc) + + assert summaries.docs == {} + stored = await persist(service, {key: value for key, value in doc.items() if key != "tenant_id"}) + assert stored["tenant_id"] == TENANT and list(summaries.docs) == [(TENANT, USER, summary_id)] + + +# --- reconcile ------------------------------------------------------------------------------------------------ + + +async def test_a_conflict_link_is_written_with_the_tenant_to_the_owners_partition() -> None: + memories = _Container() + service = _service(memories=memories) + older = _memory("f1", created_at="2026-01-01") + newer = _memory("f2", created_at="2026-02-01") + verdict = Verdict(candidate=older, similarity=0.9, relation="update", seed_missing=(), candidate_missing=()) + + assert await service._link_conflicts(USER, [(newer, [verdict])], {}) == 1 + + [(tenant, user, link_id)] = memories.docs + link = memories.docs[(tenant, user, link_id)] + assert (tenant, user) == (TENANT, USER) + assert (link["type"], link["tenant_id"], link["thread_id"]) == ("conflict_link", TENANT, "__conflicts__") diff --git a/tests/unit/aio/store/test_delete_cascade.py b/tests/unit/aio/store/test_delete_cascade.py index b8d2144..8914a45 100644 --- a/tests/unit/aio/store/test_delete_cascade.py +++ b/tests/unit/aio/store/test_delete_cascade.py @@ -11,17 +11,30 @@ from azure.cosmos.agent_memory.aio.store import AsyncMemoryStore from azure.cosmos.agent_memory.exceptions import CosmosOperationError, MemoryTypeMismatchError +TENANT = "acme" + def _containers(memories): return {ContainerKey.TURNS: MagicMock(), ContainerKey.MEMORIES: memories, ContainerKey.SUMMARIES: MagicMock()} +def _store(memories): + return AsyncMemoryStore(containers=_containers(memories), tenant_id=TENANT) + + def _memory(memory_type="fact", memory_id="m1"): - return {"id": memory_id, "type": memory_type, "user_id": "u1", "thread_id": "t1", "_etag": "e1"} + return { + "id": memory_id, + "type": memory_type, + "tenant_id": TENANT, + "user_id": "u1", + "thread_id": "t1", + "_etag": "e1", + } -def _row(row_id, thread_id="t1"): - return {"id": row_id, "type": "fact", "thread_id": thread_id} +def _row(row_id): + return {"id": row_id, "type": "fact"} def _memories(doc, absorbed=None, fail=False): @@ -50,31 +63,28 @@ def _deleted(memories): async def test_deleting_a_fact_first_deletes_the_duplicates_merged_into_it(): - memories = _memories(_memory(), absorbed={"m1": [_row("copy_1", "t2")]}) + memories = _memories(_memory(), absorbed={"m1": [_row("copy_1")]}) - await AsyncMemoryStore(containers=_containers(memories)).delete( - "m1", user_id="u1", thread_id="t1", memory_type="fact" - ) + await _store(memories).delete("m1", user_id="u1", memory_type="fact") assert _deleted(memories) == ["copy_1", "m1"] lookup = memories.query_items.call_args_list[0].kwargs params = {p["name"]: p["value"] for p in lookup["parameters"]} - assert params["@user_id"] == "u1" and params["@memory_id"] == "m1" + assert params["@tenant_id"] == TENANT and params["@user_id"] == "u1" and params["@memory_id"] == "m1" assert {v for k, v in params.items() if k.startswith("@reason_")} == {"combined", "duplicate", "procedure"} + assert lookup["partition_key"] == [TENANT, "u1"] copy_delete, memory_delete = memories.delete_item.call_args_list - assert copy_delete.kwargs["partition_key"] == ["u1", "t2"] - assert memory_delete.kwargs["partition_key"] == ["u1", "t1"] + assert copy_delete.kwargs["partition_key"] == [TENANT, "u1"] + assert memory_delete.kwargs["partition_key"] == [TENANT, "u1"] async def test_deleting_a_procedure_deletes_the_statements_it_absorbed_and_their_copies(): memories = _memories( _memory("procedural", "p1"), - absorbed={"p1": [_row("said_1", "t2")], "said_1": [_row("said_1_copy", "t3")]}, + absorbed={"p1": [_row("said_1")], "said_1": [_row("said_1_copy")]}, ) - await AsyncMemoryStore(containers=_containers(memories)).delete( - "p1", user_id="u1", thread_id="t1", memory_type="procedural" - ) + await _store(memories).delete("p1", user_id="u1", memory_type="procedural") assert _deleted(memories) == ["said_1_copy", "said_1", "p1"] @@ -84,7 +94,7 @@ async def test_other_memory_types_are_deleted_without_a_lookup(memory_type): target = _memories(_memory(memory_type)) containers = {ContainerKey.TURNS: target, ContainerKey.MEMORIES: target, ContainerKey.SUMMARIES: target} - await AsyncMemoryStore(containers=containers).delete("m1", user_id="u1", thread_id="t1", memory_type=memory_type) + await AsyncMemoryStore(containers=containers, tenant_id=TENANT).delete("m1", user_id="u1", memory_type=memory_type) assert _deleted(target) == ["m1"] target.query_items.assert_not_called() @@ -99,9 +109,7 @@ async def delete_item(*, item, **_kwargs): memories.delete_item.side_effect = delete_item - await AsyncMemoryStore(containers=_containers(memories)).delete( - "m1", user_id="u1", thread_id="t1", memory_type="fact" - ) + await _store(memories).delete("m1", user_id="u1", memory_type="fact") assert _deleted(memories) == ["copy_1", "m1"] @@ -110,9 +118,7 @@ async def test_a_failed_lookup_keeps_the_memory_for_a_retry(): memories = _memories(_memory(), fail=True) with pytest.raises(CosmosOperationError): - await AsyncMemoryStore(containers=_containers(memories)).delete( - "m1", user_id="u1", thread_id="t1", memory_type="fact" - ) + await _store(memories).delete("m1", user_id="u1", memory_type="fact") memories.delete_item.assert_not_called() @@ -122,9 +128,7 @@ async def test_a_failed_delete_of_a_folded_record_keeps_the_memory_for_a_retry() memories.delete_item.side_effect = RuntimeError("throttled") with pytest.raises(CosmosOperationError): - await AsyncMemoryStore(containers=_containers(memories)).delete( - "m1", user_id="u1", thread_id="t1", memory_type="fact" - ) + await _store(memories).delete("m1", user_id="u1", memory_type="fact") assert _deleted(memories) == ["copy_1"] @@ -133,20 +137,18 @@ async def test_a_type_mismatch_deletes_nothing(): memories = _memories(_memory("fact"), absorbed={"m1": [_row("copy_1")]}) with pytest.raises(MemoryTypeMismatchError): - await AsyncMemoryStore(containers=_containers(memories)).delete( - "m1", user_id="u1", thread_id="t1", memory_type="procedural" - ) + await _store(memories).delete("m1", user_id="u1", memory_type="procedural") memories.query_items.assert_not_called() memories.delete_item.assert_not_called() class _Memories: - """An in-memory memories container: point reads and deletes by ``[user_id, thread_id]``, and the folded-record + """An in-memory memories container: point reads and deletes by ``[tenant_id, user_id]``, and the folded-record lookup answered from the query parameters.""" def __init__(self, *docs): - self.docs = {(d["user_id"], d["thread_id"], d["id"]): d for d in docs} + self.docs = {(d["tenant_id"], d["user_id"], d["id"]): d for d in docs} self.failing_id = None async def read_item(self, *, item, partition_key): @@ -159,9 +161,10 @@ def query_items(self, *, parameters, **_kwargs): params = {p["name"]: p["value"] for p in parameters} reasons = {v for k, v in params.items() if k.startswith("@reason_")} rows = [ - {key: d[key] for key in ("id", "type", "thread_id")} + {key: d[key] for key in ("id", "type")} for d in self.docs.values() - if d["user_id"] == params["@user_id"] + if d["tenant_id"] == params["@tenant_id"] + and d["user_id"] == params["@user_id"] and d.get("superseded_by") == params["@memory_id"] and d.get("supersede_reason") in reasons ] @@ -181,8 +184,8 @@ async def delete_item(self, *, item, partition_key, **_kwargs): raise CosmosResourceNotFoundError(status_code=404, message="not found") from None -def _stored(doc_id, thread_id, user_id="u1", **fields): - return {"id": doc_id, "user_id": user_id, "thread_id": thread_id, "type": "fact", **fields} +def _stored(doc_id, thread_id, user_id="u1", tenant_id=TENANT, **fields): + return {"id": doc_id, "tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id, "type": "fact", **fields} async def test_only_what_was_folded_into_the_memory_is_deleted_and_a_retry_finishes_the_job(): @@ -193,15 +196,21 @@ async def test_only_what_was_folded_into_the_memory_is_deleted_and_a_retry_finis _stored("older", "t4", superseded_by="m1", supersede_reason="update"), _stored("lost", "t5", superseded_by="m1", supersede_reason="contradict"), _stored("theirs", "t2", user_id="u2", superseded_by="m1", supersede_reason="duplicate"), + _stored("elsewhere", "t2", tenant_id="globex", superseded_by="m1", supersede_reason="duplicate"), ) - store = AsyncMemoryStore(containers=_containers(memories)) + store = _store(memories) memories.failing_id = "dup" with pytest.raises(CosmosOperationError): - await store.delete("m1", user_id="u1", thread_id="t1", memory_type="fact") - assert ("u1", "t1", "m1") in memories.docs and ("u1", "t3", "src") not in memories.docs + await store.delete("m1", user_id="u1", memory_type="fact") + assert (TENANT, "u1", "m1") in memories.docs and (TENANT, "u1", "src") not in memories.docs memories.failing_id = None - await store.delete("m1", user_id="u1", thread_id="t1", memory_type="fact") - - assert set(memories.docs) == {("u1", "t4", "older"), ("u1", "t5", "lost"), ("u2", "t2", "theirs")} + await store.delete("m1", user_id="u1", memory_type="fact") + + assert set(memories.docs) == { + (TENANT, "u1", "older"), + (TENANT, "u1", "lost"), + (TENANT, "u2", "theirs"), + ("globex", "u1", "elsewhere"), + } diff --git a/tests/unit/aio/store/test_get_memory_history.py b/tests/unit/aio/store/test_get_memory_history.py index fe4527a..49078e4 100644 --- a/tests/unit/aio/store/test_get_memory_history.py +++ b/tests/unit/aio/store/test_get_memory_history.py @@ -36,6 +36,7 @@ def _containers(*, memories=None): def _fact(fact_id, *, superseded_at=None, reason=None): return { "id": fact_id, + "tenant_id": "default", "user_id": "u1", "thread_id": "t1", "type": "fact", @@ -56,9 +57,12 @@ async def test_async_multi_level_chain_newest_first(): ] store = AsyncMemoryStore(containers=_containers(memories=memories)) - history = await store.get_memory_history("current", user_id="u1", thread_id="t1") + history = await store.get_memory_history("current", user_id="u1") assert [d["id"] for d in history] == ["v2", "v1"] + for call in memories.query_items.call_args_list: + assert call.kwargs["partition_key"] == ["default", "u1"] + assert "c.thread_id" not in call.kwargs["query"].split(" WHERE ", 1)[1] async def test_async_missing_ids_raise(): diff --git a/tests/unit/aio/store/test_memory_store.py b/tests/unit/aio/store/test_memory_store.py index e4d65aa..6449c13 100644 --- a/tests/unit/aio/store/test_memory_store.py +++ b/tests/unit/aio/store/test_memory_store.py @@ -162,9 +162,9 @@ async def test_update_replaces_matching_doc(): memories.replace_item = AsyncMock() store = AsyncMemoryStore(containers=_containers(memories=memories)) - await store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content="updated") + await store.update("m1", user_id="u1", memory_type="fact", content="updated") - memories.read_item.assert_awaited_once_with(item="m1", partition_key=["u1", "t1"]) + memories.read_item.assert_awaited_once_with(item="m1", partition_key=["default", "u1"]) body = memories.replace_item.call_args.kwargs["body"] assert body["content"] == "updated" assert body["type"] == "fact" @@ -178,8 +178,10 @@ async def test_update_raises_when_missing(): memories.read_item = AsyncMock(side_effect=CosmosResourceNotFoundError(message="404")) store = AsyncMemoryStore(containers=_containers(memories=memories)) - with pytest.raises(MemoryNotFoundError): - await store.update("missing", user_id="u1", thread_id="t1", memory_type="fact") + with pytest.raises(MemoryNotFoundError) as excinfo: + await store.update("missing", user_id="u1", memory_type="fact") + + assert (excinfo.value.memory_id, excinfo.value.user_id) == ("missing", "u1") async def test_update_raises_on_type_mismatch(): @@ -189,7 +191,7 @@ async def test_update_raises_on_type_mismatch(): store = AsyncMemoryStore(containers=_containers(memories=memories)) with pytest.raises(MemoryTypeMismatchError): - await store.update("m1", user_id="u1", thread_id="t1", memory_type="episodic", content="x") + await store.update("m1", user_id="u1", memory_type="episodic", content="x") memories.replace_item.assert_not_awaited() @@ -200,9 +202,9 @@ async def test_delete_calls_delete_item_directly(): memories.delete_item = AsyncMock() store = AsyncMemoryStore(containers=_containers(memories=memories)) - await store.delete("m1", user_id="u1", thread_id="t1", memory_type="fact") + await store.delete("m1", user_id="u1", memory_type="fact") - memories.delete_item.assert_awaited_once_with(item="m1", partition_key=["u1", "t1"]) + memories.delete_item.assert_awaited_once_with(item="m1", partition_key=["default", "u1"]) async def test_delete_raises_when_missing(): @@ -214,7 +216,7 @@ async def test_delete_raises_when_missing(): store = AsyncMemoryStore(containers=_containers(memories=memories)) with pytest.raises(MemoryNotFoundError): - await store.delete("m1", user_id="u1", thread_id="t1", memory_type="fact") + await store.delete("m1", user_id="u1", memory_type="fact") memories.delete_item.assert_not_awaited() @@ -226,7 +228,7 @@ async def test_delete_raises_on_type_mismatch(): store = AsyncMemoryStore(containers=_containers(memories=memories)) with pytest.raises(MemoryTypeMismatchError): - await store.delete("m1", user_id="u1", thread_id="t1", memory_type="episodic") + await store.delete("m1", user_id="u1", memory_type="episodic") memories.delete_item.assert_not_awaited() @@ -237,11 +239,12 @@ async def test_read_and_tag_mutation_use_point_reads(): memories.replace_item = AsyncMock() store = AsyncMemoryStore(containers=_containers(memories=memories)) - assert (await store.read_item("m1", ["u1", "t1"], container_key=ContainerKey.MEMORIES))["id"] == "m1" - await store.add_tags("m1", "u1", "t1", "fact", ["New"]) - await store.remove_tags("m1", "u1", "t1", "fact", ["old"]) + assert (await store.read_item("m1", ["default", "u1"], container_key=ContainerKey.MEMORIES))["id"] == "m1" + await store.add_tags("m1", "u1", "fact", ["New"]) + await store.remove_tags("m1", "u1", "fact", ["old"]) - assert memories.read_item.call_args_list[0].kwargs == {"item": "m1", "partition_key": ["u1", "t1"]} + assert memories.read_item.call_args_list[0].kwargs == {"item": "m1", "partition_key": ["default", "u1"]} + assert [call.kwargs["partition_key"] for call in memories.read_item.call_args_list] == [["default", "u1"]] * 3 assert memories.replace_item.await_count == 2 @@ -250,7 +253,7 @@ async def test_tag_mutation_rejects_non_memories_types(): for bad in ("turn", "thread_summary", "user_summary", "unknown"): with pytest.raises(ValueError, match="memory_type for tag mutation"): - await store.add_tags("m1", "u1", "t1", bad, ["x"]) + await store.add_tags("m1", "u1", bad, ["x"]) async def test_single_doc_and_simple_query_helpers(): @@ -386,7 +389,7 @@ async def test_get_memories_rejects_non_memories_types(): await store.get_memories(memory_types=bad) -async def test_get_thread_summary_queries_summaries_with_partition_key(): +async def test_get_thread_summary_queries_summaries_with_the_owners_partition_key(): summaries = MagicMock() summaries.query_items.return_value = AsyncIterator([_doc(type="thread_summary", id="s1")]) store = AsyncMemoryStore(containers=_containers(summaries=summaries)) @@ -395,7 +398,7 @@ async def test_get_thread_summary_queries_summaries_with_partition_key(): assert [doc["id"] for doc in results] == ["s1"] call_kwargs = summaries.query_items.call_args.kwargs - assert call_kwargs["partition_key"] == ["u1", "t1"] + assert call_kwargs["partition_key"] == ["default", "u1"] assert "c.type = @type" in call_kwargs["query"] assert "TOP @recent_k" in call_kwargs["query"] params = _params_by_name(call_kwargs) @@ -457,7 +460,7 @@ async def test_get_memories_no_memory_types_with_thread_id_emits_or_clause(): assert "(c.thread_id = @thread_id OR c.type IN (@user_scoped_type_0, @user_scoped_type_1))" in call_kwargs["query"] -async def test_search_with_episodic_and_thread_id_omits_partition_key(): +async def test_search_with_episodic_and_thread_id_stays_in_the_owners_partition(): memories = MagicMock() memories.query_items.return_value = AsyncIterator([]) embeddings = MagicMock() @@ -465,17 +468,16 @@ async def test_search_with_episodic_and_thread_id_omits_partition_key(): store = AsyncMemoryStore(containers=_containers(memories=memories), embeddings_client=embeddings) await store.search( - search_terms="hotels", + search_terms="hello", user_id="u1", thread_id="t1", memory_types=["episodic"], ) call_kwargs = memories.query_items.call_args.kwargs - # When user-scoped types are in scope, async search must NOT confine - # the query to [u1, t1] (where no episodic ever lives). Async SDK - # treats absent partition_key as cross-partition by default. - assert "partition_key" not in call_kwargs + # The thread filter never forces a fan-out: every record of the owner is in one partition, and the OR clause keeps + # the user-wide types reachable. + assert call_kwargs["partition_key"] == ["default", "u1"] assert "(c.thread_id = @thread_id OR c.type IN (@user_scoped_type_0))" in call_kwargs["query"] @@ -572,7 +574,7 @@ async def test_search_turns_queries_turns_container(): assert "VectorDistance(c.embedding, @embedding)" in sql -async def test_vector_only_search_turns_scopes_to_single_partition_with_thread_id(): +async def test_vector_only_search_turns_reads_the_owners_partition_whatever_the_thread(): turns = MagicMock() turns.query_items.return_value = AsyncIterator([]) embeddings = MagicMock() @@ -586,7 +588,8 @@ async def test_vector_only_search_turns_scopes_to_single_partition_with_thread_i await store.search_turns(search_terms="hello", user_id="u1", thread_id="t1") kwargs = turns.query_items.call_args.kwargs - assert kwargs["partition_key"] == ["u1", "t1"] + assert kwargs["partition_key"] == ["default", "u1"] + assert "c.thread_id = @thread_id" in kwargs["query"] async def test_keyword_search_turns_with_thread_id_filters_instead_of_using_partition_key(): @@ -607,22 +610,6 @@ async def test_keyword_search_turns_with_thread_id_filters_instead_of_using_part assert "c.thread_id = @thread_id" in kwargs["query"] -async def test_search_turns_fans_out_across_partitions_without_thread_id(): - turns = MagicMock() - turns.query_items.return_value = AsyncIterator([]) - embeddings = MagicMock() - embeddings.generate = AsyncMock(return_value=[0.1, 0.2]) - store = AsyncMemoryStore( - containers=_containers(turns=turns), - embeddings_client=embeddings, - ) - - await store.search_turns(search_terms="hello", user_id="u1") - - kwargs = turns.query_items.call_args.kwargs - assert "partition_key" not in kwargs - - async def test_search_turns_requires_user_id(): turns = MagicMock() embeddings = MagicMock() diff --git a/tests/unit/aio/store/test_search_routing.py b/tests/unit/aio/store/test_search_routing.py index c6b0a58..da00769 100644 --- a/tests/unit/aio/store/test_search_routing.py +++ b/tests/unit/aio/store/test_search_routing.py @@ -1,6 +1,7 @@ """Async search routing. -See tests/unit/store/test_search_routing.py for why keyword searches run cross-partition. +See tests/unit/store/test_search_routing.py for why keyword searches run cross-partition and vector-only searches +read the owner's partition. """ from __future__ import annotations @@ -63,9 +64,10 @@ async def test_a_keyword_search_of_a_thread_runs_cross_partition_inside_it(metho (call,) = _calls(containers[container_key]) assert "partition_key" not in call, "the async SDK queries across partitions when no key is given" - assert "c.user_id = @user_id" in call["query"] + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in call["query"] assert "c.thread_id = @thread_id" in call["query"] params = _params(call) + assert ("@tenant_id", "default") in params assert ("@user_id", "u1") in params assert ("@thread_id", "t1") in params assert ( @@ -79,17 +81,29 @@ async def test_a_keyword_search_of_a_thread_runs_cross_partition_inside_it(metho @pytest.mark.parametrize(("method", "container_key", "options"), THREAD_SEARCHES) -async def test_a_vector_only_search_of_a_thread_keeps_the_partition_key(method, container_key, options): +async def test_a_vector_only_search_of_a_thread_keeps_the_owners_partition_key(method, container_key, options): store, containers = _store() await getattr(store, method)(user_id="u1", thread_id="t1", search_terms=NO_KEYWORDS, **options) (call,) = _calls(containers[container_key]) - assert call["partition_key"] == ["u1", "t1"] + assert call["partition_key"] == ["default", "u1"] + assert "c.thread_id = @thread_id" in call["query"] assert "FullTextScore" not in call["query"] assert "full_text_score_scope" not in call +@pytest.mark.parametrize(("method", "container_key", "options"), USER_SEARCHES) +async def test_a_vector_only_search_of_the_users_threads_keeps_the_owners_partition_key(method, container_key, options): + store, containers = _store() + + await getattr(store, method)(user_id="u1", search_terms=NO_KEYWORDS, **options) + + (call,) = _calls(containers[container_key]) + assert call["partition_key"] == ["default", "u1"] + assert "c.thread_id = @thread_id" not in call["query"] + + @pytest.mark.parametrize(("method", "container_key", "options"), USER_SEARCHES) async def test_a_keyword_search_of_the_users_threads_ranks_with_local_statistics(method, container_key, options): store, containers = _store() @@ -98,7 +112,7 @@ async def test_a_keyword_search_of_the_users_threads_ranks_with_local_statistics (call,) = _calls(containers[container_key]) assert "partition_key" not in call - assert "c.user_id = @user_id" in call["query"] + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in call["query"] assert "c.thread_id = @thread_id" not in call["query"] assert call["full_text_score_scope"] == "Local" @@ -137,7 +151,7 @@ async def test_a_full_text_query_sent_with_a_partition_key_is_rejected(call): f"SELECT TOP 1 c.id FROM c ORDER BY RANK {call}", [], container_key=ContainerKey.MEMORIES, - partition_key=["u1", "t1"], + partition_key=["default", "u1"], ) containers[ContainerKey.MEMORIES].query_items.assert_not_called() @@ -149,11 +163,11 @@ async def test_a_query_that_only_names_a_field_like_the_function_keeps_its_parti "SELECT TOP 1 c.id FROM c WHERE c.fulltextscore = 1", [], container_key=ContainerKey.MEMORIES, - partition_key=["u1", "t1"], + partition_key=["default", "u1"], ) (call,) = _calls(containers[ContainerKey.MEMORIES]) - assert call["partition_key"] == ["u1", "t1"] + assert call["partition_key"] == ["default", "u1"] async def test_a_callers_own_full_text_query_keeps_the_default_statistics(): diff --git a/tests/unit/aio/store/test_secret_redaction.py b/tests/unit/aio/store/test_secret_redaction.py index 19cf2b9..9cc1d66 100644 --- a/tests/unit/aio/store/test_secret_redaction.py +++ b/tests/unit/aio/store/test_secret_redaction.py @@ -262,9 +262,7 @@ async def test_async_update_without_an_embedder_redacts_new_content_and_metadata ) store = AsyncMemoryStore(containers=_containers(memories=memories)) - await store.update( - "m1", user_id="u1", thread_id="t1", memory_type="fact", content=f"Use {SECRET}", metadata={"note": SECRET} - ) + await store.update("m1", user_id="u1", memory_type="fact", content=f"Use {SECRET}", metadata={"note": SECRET}) body = memories.replace_item.call_args.kwargs["body"] assert TOKEN not in repr(body) @@ -288,7 +286,7 @@ def _failing_embedder(): async def test_async_update_without_an_embedder_keeps_the_previous_vector_when_the_content_changes(): store, memories = _update_store(_stored_doc(embedding=[9.9]), None) - await store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content="Prefers Ruff.") + await store.update("m1", user_id="u1", memory_type="fact", content="Prefers Ruff.") body = memories.replace_item.call_args.kwargs["body"] assert body["content"] == "Prefers Ruff." @@ -299,7 +297,7 @@ async def test_async_update_rebuilds_the_vector_from_the_redacted_content(): embeddings = _embeddings() store, memories = _update_store(_stored_doc(embedding=[9.9]), embeddings) - await store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content=f"Use {SECRET}") + await store.update("m1", user_id="u1", memory_type="fact", content=f"Use {SECRET}") body = memories.replace_item.call_args.kwargs["body"] embeddings.generate.assert_awaited_once_with(body["content"]) @@ -311,7 +309,7 @@ async def test_an_async_metadata_only_update_rebuilds_the_vector_of_a_record_tha embeddings = _embeddings() store, memories = _update_store(_stored_doc(content=f"Use {SECRET}", embedding=[9.9]), embeddings) - await store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", metadata={"note": "rotated"}) + await store.update("m1", user_id="u1", memory_type="fact", metadata={"note": "rotated"}) body = memories.replace_item.call_args.kwargs["body"] embeddings.generate.assert_awaited_once_with(body["content"]) @@ -323,7 +321,7 @@ async def test_async_update_rebuilds_the_vector_when_the_content_changes(): embeddings = _embeddings() store, memories = _update_store(_stored_doc(embedding=[9.9]), embeddings) - await store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content="Prefers Ruff.") + await store.update("m1", user_id="u1", memory_type="fact", content="Prefers Ruff.") embeddings.generate.assert_awaited_once_with("Prefers Ruff.") assert memories.replace_item.call_args.kwargs["body"]["embedding"] == [0.1, 0.2] @@ -338,7 +336,7 @@ async def test_async_update_keeps_the_vector_when_the_text_it_encodes_is_unchang embeddings = _embeddings() store, memories = _update_store(_stored_doc(embedding=[9.9]), embeddings) - await store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", **changes) + await store.update("m1", user_id="u1", memory_type="fact", **changes) embeddings.generate.assert_not_called() assert memories.replace_item.call_args.kwargs["body"]["embedding"] == [9.9] @@ -348,7 +346,7 @@ async def test_async_update_does_not_embed_a_record_that_has_no_vector(): embeddings = _embeddings() store, memories = _update_store(_stored_doc(), embeddings) - await store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content=f"Use {SECRET}") + await store.update("m1", user_id="u1", memory_type="fact", content=f"Use {SECRET}") embeddings.generate.assert_not_called() assert "embedding" not in memories.replace_item.call_args.kwargs["body"] @@ -358,7 +356,7 @@ async def test_async_update_drops_the_vector_of_a_record_whose_text_is_emptied_w embeddings = _embeddings() store, memories = _update_store(_stored_doc(embedding=[9.9]), embeddings) - await store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content="") + await store.update("m1", user_id="u1", memory_type="fact", content="") embeddings.generate.assert_not_called() assert "embedding" not in memories.replace_item.call_args.kwargs["body"] @@ -369,7 +367,7 @@ async def test_async_update_keeps_a_procedures_vector_when_only_its_content_chan stored = _stored_doc(type="procedural", retrieval_text="deploy the service", embedding=[9.9]) store, memories = _update_store(stored, embeddings) - await store.update("m1", user_id="u1", thread_id="t1", memory_type="procedural", content="Run the deploy script.") + await store.update("m1", user_id="u1", memory_type="procedural", content="Run the deploy script.") embeddings.generate.assert_not_called() assert memories.replace_item.call_args.kwargs["body"]["embedding"] == [9.9] @@ -380,7 +378,7 @@ async def test_async_update_rebuilds_a_procedures_vector_from_its_retrieval_text stored = _stored_doc(type="procedural", retrieval_text="deploy the service", embedding=[9.9]) store, memories = _update_store(stored, embeddings) - await store.update("m1", user_id="u1", thread_id="t1", memory_type="procedural", content=f"Use {SECRET}") + await store.update("m1", user_id="u1", memory_type="procedural", content=f"Use {SECRET}") embeddings.generate.assert_awaited_once_with("deploy the service") assert memories.replace_item.call_args.kwargs["body"]["embedding"] == [0.1, 0.2] @@ -395,7 +393,7 @@ async def test_async_update_keeps_the_previous_vector_when_embedding_fails(conte caplog.set_level(logging.DEBUG) store, memories = _update_store(_stored_doc(embedding=[9.9]), _failing_embedder()) - await store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content=content) + await store.update("m1", user_id="u1", memory_type="fact", content=content) body = memories.replace_item.call_args.kwargs["body"] assert body["embedding"] == [9.9] @@ -417,7 +415,7 @@ async def test_async_update_drops_a_vector_built_from_a_secret_when_it_cannot_be embeddings = _failing_embedder() if embedder == "fails" else None store, memories = _update_store(_stored_doc(content=f"Use {SECRET}", embedding=[9.9]), embeddings) - await store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", **changes) + await store.update("m1", user_id="u1", memory_type="fact", **changes) body = memories.replace_item.call_args.kwargs["body"] assert "embedding" not in body @@ -435,7 +433,7 @@ async def test_async_update_judges_a_procedures_vector_by_the_text_it_was_built_ stored = _stored_doc(type="procedural", retrieval_text=retrieval_text, content=f"Use {SECRET}", embedding=[9.9]) store, memories = _update_store(stored, _failing_embedder()) - await store.update("m1", user_id="u1", thread_id="t1", memory_type="procedural", metadata={"note": "rotated"}) + await store.update("m1", user_id="u1", memory_type="procedural", metadata={"note": "rotated"}) body = memories.replace_item.call_args.kwargs["body"] assert body.get("embedding") == expected @@ -456,7 +454,7 @@ async def _noop_sleep(*_a, **_kw): ) store = AsyncMemoryStore(containers=_containers(memories=memories), embeddings_client=_failing_embedder()) - await store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content="Prefers Ruff.") + await store.update("m1", user_id="u1", memory_type="fact", content="Prefers Ruff.") assert memories.replace_item.await_count == 2 assert memories.replace_item.call_args.kwargs["body"]["embedding"] == [7.7] @@ -473,7 +471,7 @@ async def _noop_sleep(*_a, **_kw): side_effect=[CosmosAccessConditionFailedError(message="412", response=None), None] ) - await store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content="Prefers Ruff.") + await store.update("m1", user_id="u1", memory_type="fact", content="Prefers Ruff.") assert memories.replace_item.await_count == 2 embeddings.generate.assert_awaited_once_with("Prefers Ruff.") @@ -489,7 +487,7 @@ def _tagged_store(tags=()): async def test_async_add_tags_drops_a_credential_tag_and_flags_the_record(): store, memories = _tagged_store(["topic:deploy"]) - await store.add_tags("m1", "u1", "t1", "fact", [TOKEN, "Release"]) + await store.add_tags("m1", "u1", "fact", [TOKEN, "Release"]) body = memories.replace_item.call_args.kwargs["body"] assert body["tags"] == ["release", "sys:secret", "topic:deploy"] @@ -501,7 +499,7 @@ async def test_async_add_tags_drops_a_credential_tag_and_flags_the_record(): async def test_async_add_tags_checks_a_tag_before_it_is_lowercased(): store, memories = _tagged_store() - await store.add_tags("m1", "u1", "t1", "fact", ["AKIA" + "IOSFODNN7EXAMPLE"]) + await store.add_tags("m1", "u1", "fact", ["AKIA" + "IOSFODNN7EXAMPLE"]) body = memories.replace_item.call_args.kwargs["body"] assert "akiaiosfodnn7example" not in repr(body).lower() @@ -512,11 +510,11 @@ async def test_async_add_tags_checks_a_tag_before_it_is_lowercased(): async def test_async_add_tags_leaves_a_clean_record_unflagged_and_remove_tags_never_flags(): store, memories = _tagged_store(["a", "b"]) - await store.add_tags("m1", "u1", "t1", "fact", ["c"]) + await store.add_tags("m1", "u1", "fact", ["c"]) assert memories.replace_item.call_args.kwargs["body"]["tags"] == ["a", "b", "c"] assert "classification" not in memories.replace_item.call_args.kwargs["body"]["metadata"] - await store.remove_tags("m1", "u1", "t1", "fact", [TOKEN, "a"]) + await store.remove_tags("m1", "u1", "fact", [TOKEN, "a"]) assert memories.replace_item.call_args.kwargs["body"]["tags"] == ["b"] assert "classification" not in memories.replace_item.call_args.kwargs["body"]["metadata"] @@ -525,7 +523,7 @@ async def test_async_add_tags_logs_the_formats_found_never_the_tag(caplog): caplog.set_level(logging.DEBUG) store, _memories = _tagged_store() - await store.add_tags("m1", "u1", "t1", "fact", [TOKEN]) + await store.add_tags("m1", "u1", "fact", [TOKEN]) assert "patterns=['github_token']" in caplog.text assert TOKEN not in caplog.text and TOKEN.lower() not in caplog.text diff --git a/tests/unit/aio/store/test_update_embedding_fallback.py b/tests/unit/aio/store/test_update_embedding_fallback.py index b700990..10c5181 100644 --- a/tests/unit/aio/store/test_update_embedding_fallback.py +++ b/tests/unit/aio/store/test_update_embedding_fallback.py @@ -38,7 +38,7 @@ def __init__(self, *docs: dict[str, Any]) -> None: def _save(self, body: dict[str, Any]) -> dict[str, Any]: saved = {**copy.deepcopy(body), "_etag": f"etag-{next(self._etags)}"} - self._docs[saved["id"], (saved["user_id"], saved["thread_id"])] = saved + self._docs[saved["id"], (saved["tenant_id"], saved["user_id"])] = saved return copy.deepcopy(saved) async def read_item(self, item: str, partition_key: list[str], **_kwargs: Any) -> dict[str, Any]: @@ -52,7 +52,7 @@ async def read_item(self, item: str, partition_key: list[str], **_kwargs: Any) - async def replace_item( self, item: str, body: dict[str, Any], *, match_condition: Any = None, etag: Any = None, **_kwargs: Any ) -> dict[str, Any]: - current = await self.read_item(item, [body["user_id"], body["thread_id"]]) + current = await self.read_item(item, [body["tenant_id"], body["user_id"]]) if match_condition == MatchConditions.IfNotModified and etag != current["_etag"]: raise CosmosAccessConditionFailedError(status_code=412, message="Precondition failed") return self._save(body) @@ -75,6 +75,7 @@ async def generate(self, text: str) -> list[float]: def _fact(content: str, embedding: list[float]) -> dict[str, Any]: return { "id": "fact_1", + "tenant_id": "default", "user_id": "u1", "thread_id": "t1", "type": "fact", @@ -103,16 +104,16 @@ async def test_a_failed_re_embed_keeps_the_record_in_vector_search_and_a_later_e store = _store(memories, embedder) embedder.available = False - await store.update("fact_1", user_id="u1", thread_id="t1", memory_type="fact", content="I like green tea") + await store.update("fact_1", user_id="u1", memory_type="fact", content="I like green tea") - stored = await memories.read_item("fact_1", ["u1", "t1"]) + stored = await memories.read_item("fact_1", ["default", "u1"]) assert stored["content"] == "I like green tea" assert stored["embedding"] == [10.0, 1.0], "the previous vector stays, so the record is still found" embedder.available = True - await store.update("fact_1", user_id="u1", thread_id="t1", memory_type="fact", content="I like oolong tea") + await store.update("fact_1", user_id="u1", memory_type="fact", content="I like oolong tea") - stored = await memories.read_item("fact_1", ["u1", "t1"]) + stored = await memories.read_item("fact_1", ["default", "u1"]) assert stored["embedding"] == [float(len("I like oolong tea")), 1.0] assert embedder.texts == ["I like green tea", "I like oolong tea"] @@ -140,7 +141,7 @@ async def _noop_sleep(*_a, **_kw): ) store = AsyncMemoryStore(containers=_containers(memories=memories), embeddings_client=_failing_embedder()) - await store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", metadata={"note": "rotated"}) + await store.update("m1", user_id="u1", memory_type="fact", metadata={"note": "rotated"}) body = memories.replace_item.call_args.kwargs["body"] assert memories.replace_item.await_count == 2 diff --git a/tests/unit/aio/test_auto_trigger.py b/tests/unit/aio/test_auto_trigger.py index f51eb92..686eed8 100644 --- a/tests/unit/aio/test_auto_trigger.py +++ b/tests/unit/aio/test_auto_trigger.py @@ -17,16 +17,22 @@ from azure.cosmos.agent_memory.aio.cosmos_memory_client import AsyncCosmosMemoryClient from azure.cosmos.agent_memory.aio.processors import AsyncInProcessProcessor +TENANT = "acme" + class _AsyncFakeCounterContainer: """Async in-memory counter container exercising the REAL increment / - watermark-read / watermark-advance helpers end-to-end (no constant mocks).""" + watermark-read / watermark-advance helpers end-to-end (no constant mocks). + It records the partition each read and patch asks for.""" def __init__(self) -> None: self.store: dict[str, dict] = {} + self.partitions_read: list[list[str]] = [] + self.partitions_patched: list[list[str]] = [] self._etag = 0 async def read_item(self, *, item, partition_key): + self.partitions_read.append(partition_key) if item not in self.store: raise CosmosResourceNotFoundError(message="404") return dict(self.store[item]) @@ -46,6 +52,7 @@ async def upsert_item(self, *, body, **_kwargs): return dict(body) async def patch_item(self, *, item, partition_key, patch_operations): + self.partitions_patched.append(partition_key) doc = self.store.setdefault(item, {"id": item}) for op in patch_operations: doc[op["path"].lstrip("/")] = op["value"] @@ -110,6 +117,7 @@ async def test_episode_zero_does_not_fire(self): await maybe_trigger_steps( processor, counter_container, + TENANT, {("u1", "t1"): 1}, thresholds={ "FACT_EXTRACTION_EVERY_N": 0, @@ -136,10 +144,10 @@ async def test_episode_fires_when_threshold_crossed(self): "MEMORY_PROCESSOR_OWNER": "inprocess", } - await maybe_trigger_steps(processor, counter_container, {("u1", "t1"): 2}, thresholds=thresholds) + await maybe_trigger_steps(processor, counter_container, TENANT, {("u1", "t1"): 2}, thresholds=thresholds) processor.process_extract_episodes.assert_not_awaited() - await maybe_trigger_steps(processor, counter_container, {("u1", "t1"): 1}, thresholds=thresholds) + await maybe_trigger_steps(processor, counter_container, TENANT, {("u1", "t1"): 1}, thresholds=thresholds) processor.process_extract_episodes.assert_awaited_once_with(user_id="u1", thread_id="t1") @@ -157,6 +165,7 @@ async def test_episode_failure_is_caught_and_other_steps_continue(self): await maybe_trigger_steps( processor, counter_container, + TENANT, {("u1", "t1"): 1}, thresholds={ "FACT_EXTRACTION_EVERY_N": 0, @@ -383,3 +392,83 @@ def test_non_int_value_rejected(self): def test_non_mapping_rejected(self): with pytest.raises(TypeError): AsyncCosmosMemoryClient(use_default_credential=False, cadence_thresholds=[("DEDUP_EVERY_N", 5)]) + + +_THREAD_AND_USER_STEPS = { + "FACT_EXTRACTION_EVERY_N": 1, + "THREAD_SUMMARY_EVERY_N": 0, + "EPISODE_EVAL_EVERY_N": 0, + "USER_SUMMARY_EVERY_N": 1, + "DEDUP_EVERY_N": 0, + "MEMORY_PROCESSOR_OWNER": "inprocess", +} + + +class TestCountersFollowTheTenant: + """Every counter the auto-trigger reads, writes or stamps is in the client's tenant, in the owner's partition.""" + + @pytest.mark.asyncio + async def test_thread_and_user_counters_live_in_the_tenant_and_owner_partition(self): + processor = AsyncInProcessProcessor(pipeline=MagicMock()) + processor.process_extract_memories = AsyncMock(return_value={}) + processor.process_user_summary = AsyncMock() + counters = _AsyncFakeCounterContainer() + + await maybe_trigger_steps(processor, counters, TENANT, {("u1", "t1"): 1}, thresholds=_THREAD_AND_USER_STEPS) + + assert {(doc["tenant_id"], doc["user_id"], doc["thread_id"]) for doc in counters.store.values()} == { + (TENANT, "u1", "t1"), + (TENANT, "u1", "__counters__"), + } + assert counters.partitions_read == [[TENANT, "u1"], [TENANT, "u1"]] + + @pytest.mark.asyncio + async def test_a_failed_step_is_stamped_in_the_tenant_and_owner_partition(self): + processor = AsyncInProcessProcessor(pipeline=MagicMock()) + processor.process_extract_memories = AsyncMock(side_effect=RuntimeError("boom")) + processor.process_user_summary = AsyncMock(side_effect=RuntimeError("boom")) + counters = _AsyncFakeCounterContainer() + + await maybe_trigger_steps(processor, counters, TENANT, {("u1", "t1"): 1}, thresholds=_THREAD_AND_USER_STEPS) + + assert counters.partitions_patched == [[TENANT, "u1"], [TENANT, "u1"]] + assert counters.store["thread:u1:t1"]["last_failure_reason"].startswith("process_extract_memories: ") + assert counters.store["user:u1"]["last_failure_reason"].startswith("process_user_summary: ") + + @pytest.mark.asyncio + async def test_a_client_counts_the_turns_it_pushes_in_its_own_tenant(self, monkeypatch): + monkeypatch.setenv("FACT_EXTRACTION_EVERY_N", "1") + monkeypatch.setenv("THREAD_SUMMARY_EVERY_N", "0") + monkeypatch.setenv("EPISODE_EVAL_EVERY_N", "0") + monkeypatch.setenv("USER_SUMMARY_EVERY_N", "0") + processor = AsyncInProcessProcessor(pipeline=MagicMock()) + processor.process_extract_memories = AsyncMock(return_value={}) + client = AsyncCosmosMemoryClient(use_default_credential=False, processor=processor, tenant_id=TENANT) + client._memories_container_client = MagicMock() + client._memories_container_client.upsert_item = AsyncMock(side_effect=lambda body: body) + client._turns_container_client = client._memories_container_client + client._summaries_container_client = client._memories_container_client + counters = client._counter_container_client = _AsyncFakeCounterContainer() + + client.add_local(user_id="u1", role="user", thread_id="t1", content="hi") + await client.push_to_cosmos() + await asyncio.gather(*list(client._background_tasks), return_exceptions=True) + + [counter] = counters.store.values() + assert (counter["tenant_id"], counter["user_id"], counter["thread_id"]) == (TENANT, "u1", "t1") + assert counters.partitions_read == [[TENANT, "u1"]] + + @pytest.mark.asyncio + async def test_a_client_hands_its_tenant_to_the_trigger(self): + client = AsyncCosmosMemoryClient(use_default_credential=False, tenant_id=TENANT) + processor, counters = MagicMock(), MagicMock() + client._get_processor = MagicMock(return_value=processor) + client._get_counter_container = MagicMock(return_value=counters) + + with patch( + "azure.cosmos.agent_memory.aio.cosmos_memory_client.maybe_trigger_steps", + new=AsyncMock(), + ) as trigger: + await client._maybe_auto_trigger({("u1", "t1"): 1}) + + assert trigger.await_args.args == (processor, counters, TENANT, {("u1", "t1"): 1}) diff --git a/tests/unit/aio/test_combine.py b/tests/unit/aio/test_combine.py index 6034105..cdf81c1 100644 --- a/tests/unit/aio/test_combine.py +++ b/tests/unit/aio/test_combine.py @@ -23,6 +23,7 @@ NEAR = [1.0, 0.0, 0.0] BAND = [0.75, math.sqrt(1 - 0.75**2), 0.0] # cosine 0.75: below the dedup floor, above the combine floor +TENANT = "acme" PLANS = "The user is planning a Christmas Eve dinner for 15 guests" START = "The user wants the Christmas Eve dinner to start at 6:30 PM" @@ -32,6 +33,7 @@ def _fact(fid: str, content: str, *, vector=NEAR, ts: int = 1, created_at: str = "2024-01-01T00:00:00+00:00", **extra): doc = { "id": fid, + "tenant_id": TENANT, "user_id": "u1", "thread_id": "t1", "role": "system", @@ -99,6 +101,7 @@ def writer_inputs(self) -> list[dict]: def _make_pipeline() -> AsyncPipelineService: p = AsyncPipelineService.__new__(AsyncPipelineService) + p._tenant_id = TENANT p._embeddings = MagicMock() p._embed_one = AsyncMock(return_value=[0.1, 0.2, 0.3]) p._commit_fold = AsyncMock(side_effect=lambda survivor, losers, **kwargs: [doc["id"] for doc in losers]) @@ -174,6 +177,8 @@ async def test_overlapping_facts_become_one_fact_and_retire_into_it(self): [record] = _created(p) assert (record["content"], record["merged_from"]) == (BOTH, ["f1", "f2"]) assert "sys:combined" in record["tags"] and record["embedding"] == [0.1, 0.2, 0.3] + assert record["tenant_id"] == TENANT + assert {tuple(c.kwargs["partition_key"]) for c in p._container.read_item.call_args_list} == {(TENANT, "u1")} assert (record["prompt_id"], record["prompt_version"]) == ("combine_memories.prompty", "v1") assert _retired(p) == [("f1", record["id"], "combined"), ("f2", record["id"], "combined")] assert (result["combined"], result["synthesized"], result["kept"], result["combine_groups"]) == (2, 1, 0, 1) @@ -370,6 +375,7 @@ class TestAsyncCommitCombine: @staticmethod def _build() -> AsyncPipelineService: p = AsyncPipelineService.__new__(AsyncPipelineService) + p._tenant_id = TENANT p._container = MagicMock() p._container.create_item = AsyncMock() p._memories_container = p._container @@ -401,6 +407,8 @@ async def test_a_fact_that_already_exists_is_not_created_again_and_its_members_a assert await p._commit_combine(record, members) == ["f1", "f2"] + p._container.read_item.assert_awaited_once_with(item=record["id"], partition_key=[TENANT, "u1"]) + @pytest.mark.parametrize( "existing", [ diff --git a/tests/unit/aio/test_conflict_links.py b/tests/unit/aio/test_conflict_links.py index 4ba765c..d4f4372 100644 --- a/tests/unit/aio/test_conflict_links.py +++ b/tests/unit/aio/test_conflict_links.py @@ -4,8 +4,8 @@ and one link document names the pair, a conflicting fact that is combined or folded is linked as the fact that took its place, and a link that cannot be written neither fails the pass nor holds the cursor back. The fake container, the scripted model and the scenarios are the sync tests'; here the container is behind awaitable methods as the async -Cosmos client exposes it and, like that client, it rejects ``enable_cross_partition_query`` (a query without a -partition reads every partition without being asked). +Cosmos client exposes it and, like that client, it takes no ``enable_cross_partition_query``: every query names the +partition of one owner. """ from __future__ import annotations @@ -33,6 +33,7 @@ RESULT_KEYS, RETIREMENT_FIELDS, SEATTLE, + TENANT, USER, V_A, V_B, @@ -71,21 +72,14 @@ async def __anext__(self) -> dict[str, Any]: class AsyncAccount: - """``Account`` behind awaitable methods. Passing ``enable_cross_partition_query`` is a ``TypeError``, as it is for - the async client.""" + """``Account`` behind awaitable methods, as the async client exposes a container (which rejects + ``enable_cross_partition_query``).""" def __init__(self, inner: Account) -> None: self.inner = inner def query_items(self, *, query: str, parameters: Any = None, partition_key: Any = None) -> AsyncRows: - return AsyncRows( - self.inner.query_items( - query=query, - parameters=parameters, - partition_key=partition_key, - enable_cross_partition_query=partition_key is None, - ) - ) + return AsyncRows(self.inner.query_items(query=query, parameters=parameters, partition_key=partition_key)) async def read_item(self, *, item: str, partition_key: Any) -> dict[str, Any]: return self.inner.read_item(item, partition_key) @@ -126,9 +120,9 @@ def service_over(account: Account, chat: Chat) -> tuple[AsyncPipelineService, As ContainerKey.TURNS: MagicMock(), ContainerKey.SUMMARIES: MagicMock(), } - store = AsyncMemoryStore(containers=containers, embeddings_client=embeddings) + store = AsyncMemoryStore(containers=containers, embeddings_client=embeddings, tenant_id=TENANT) scripted = AsyncChat(chat) - return AsyncPipelineService(store, scripted, embeddings, containers=containers), scripted + return AsyncPipelineService(store, scripted, embeddings, containers=containers, tenant_id=TENANT), scripted def a_conflict(kind: str) -> tuple[Account, AsyncChat, AsyncPipelineService]: @@ -152,6 +146,7 @@ async def test_both_facts_stay_active_and_one_link_names_the_pair(self, kind, en assert link_fields(link) == { "id": link["id"], "type": "conflict_link", + "tenant_id": TENANT, "user_id": USER, "thread_id": "__conflicts__", "first": "f1", @@ -159,9 +154,7 @@ async def test_both_facts_stay_active_and_one_link_names_the_pair(self, kind, en "kind": kind, } assert link["id"].startswith("conflict_") and link["created_at"] - assert account.read_item(link["id"], [USER, "__conflicts__"])["id"] == link["id"], ( - "it is in the user's partition" - ) + assert account.read_item(link["id"], [TENANT, USER])["id"] == link["id"], "it is in the owner's partition" assert not {"content", "text"} & set(link), "a link names the facts and holds none of their text" assert (result["conflicts"], result["checked"], result["compared"], result["kept"]) == (1, 2, 1, 2) assert (result["merged"], result["combined"], result["synthesized"]) == (0, 0, 0) diff --git a/tests/unit/aio/test_consolidate_memories.py b/tests/unit/aio/test_consolidate_memories.py index cf9492e..0d6f792 100644 --- a/tests/unit/aio/test_consolidate_memories.py +++ b/tests/unit/aio/test_consolidate_memories.py @@ -27,6 +27,7 @@ NEAR = [1.0, 0.0, 0.0] NEAR_ENOUGH = [0.9, 0.3, 0.0] # cosine 0.95 with NEAR TOO_FAR = [0.8, 0.6, 0.0] # cosine 0.80 with NEAR: below the 0.85 floor +TENANT = "acme" @pytest.fixture(autouse=True) @@ -36,6 +37,7 @@ def _dedup_only(monkeypatch): def _make_pipeline() -> AsyncPipelineService: p = AsyncPipelineService.__new__(AsyncPipelineService) + p._tenant_id = TENANT p._embeddings = MagicMock() p._commit_fold = AsyncMock(side_effect=lambda survivor, losers, **kwargs: [doc["id"] for doc in losers]) p._container = MagicMock() @@ -61,6 +63,7 @@ def _fact( ) -> dict: doc = { "id": fid, + "tenant_id": TENANT, "user_id": "u1", "thread_id": "t1", "type": "fact", @@ -156,7 +159,7 @@ async def test_a_fact_without_a_close_neighbour_is_checked_without_asking_the_mo p._run_prompty.assert_not_called() body = p._container.create_item.call_args.kwargs["body"] assert (body["id"], body["type"]) == ("dedup_cursor_u1_fact", "dedup_cursor") - assert (body["user_id"], body["thread_id"]) == ("u1", "__dedup__") + assert (body["tenant_id"], body["user_id"], body["thread_id"]) == (TENANT, "u1", "__dedup__") assert (body["last_ts"], body["ids_at_last_ts"]) == (3, ["f1"]) async def test_a_pass_reads_active_facts_after_its_cursor_and_replaces_it_if_unchanged(self): @@ -171,14 +174,18 @@ async def test_a_pass_reads_active_facts_after_its_cursor_and_replaces_it_if_unc _, queries = await _run(p, [_fact("f1", "User likes coffee", ts=6)], cursor=cursor, n=7) - sql, params, _ = queries[0] + sql, params, kwargs = queries[0] assert "TOP 7" in sql and "ORDER BY c._ts ASC" in sql and "IS_NULL(c.superseded_by)" in sql - assert (params["@user_id"], params["@after_ts"], params["@after_ids"]) == ("u1", 5, ["f0"]) - assert p._container.read_item.call_args.kwargs["partition_key"] == ["u1", "__dedup__"] + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in sql + assert (params["@tenant_id"], params["@user_id"]) == (TENANT, "u1") + assert (params["@after_ts"], params["@after_ids"]) == (5, ["f0"]) + assert kwargs["partition_key"] == [TENANT, "u1"] + assert p._container.read_item.call_args.kwargs["partition_key"] == [TENANT, "u1"] replaced = p._container.replace_item.call_args.kwargs assert (replaced["item"], replaced["etag"]) == ("dedup_cursor_u1_fact", "c1") assert replaced["match_condition"] == MatchConditions.IfNotModified assert (replaced["body"]["last_ts"], replaced["body"]["ids_at_last_ts"]) == (6, ["f1"]) + assert replaced["body"]["tenant_id"] == TENANT async def test_only_neighbours_at_or_above_the_similarity_floor_reach_the_model(self): p = _make_pipeline() @@ -188,7 +195,11 @@ async def test_only_neighbours_at_or_above_the_similarity_floor_reach_the_model( result, queries = await _run(p, [seed], {"f1": [far, close]}, [[_verdict("related")]]) - assert "ORDER BY VectorDistance(c.embedding, @embedding)" in queries[1][0] + sql, params, kwargs = queries[1] + assert "ORDER BY VectorDistance(c.embedding, @embedding)" in sql + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in sql + assert (params["@tenant_id"], params["@user_id"]) == (TENANT, "u1") + assert kwargs["partition_key"] == [TENANT, "u1"] assert p._run_prompty.call_args.args[0] == "dedup_verify.prompty" candidates = json.loads(p._run_prompty.call_args.kwargs["inputs"]["candidates"]) assert [c["text"] for c in candidates] == ["The user likes coffee"] diff --git a/tests/unit/aio/test_cosmos_memory_client.py b/tests/unit/aio/test_cosmos_memory_client.py index 8cebf28..3b22539 100644 --- a/tests/unit/aio/test_cosmos_memory_client.py +++ b/tests/unit/aio/test_cosmos_memory_client.py @@ -3,18 +3,22 @@ from __future__ import annotations import asyncio +import inspect import uuid from datetime import datetime, timezone +from types import SimpleNamespace from unittest.mock import AsyncMock, MagicMock, patch import pytest from azure.cosmos.agent_memory._container_routing import ContainerKey +from azure.cosmos.agent_memory._partitioning import DEFAULT_TENANT_ID, PARTITION_KEY_PATHS from azure.cosmos.agent_memory.aio.cosmos_memory_client import AsyncCosmosMemoryClient from azure.cosmos.agent_memory.aio.store import AsyncMemoryStore from azure.cosmos.agent_memory.exceptions import ( ConfigurationError, CosmosNotConnectedError, + CosmosOperationError, MemoryNotFoundError, ValidationError, ) @@ -23,6 +27,14 @@ # Helpers # --------------------------------------------------------------------------- +EARLIER_KEY = ["/user_id", "/thread_id"] + + +def _keyed_container(paths=PARTITION_KEY_PATHS, container_id="container") -> MagicMock: + """A container whose metadata names its partition key, as ``read()`` returns it.""" + properties = {"id": container_id, "partitionKey": {"paths": list(paths), "kind": "MultiHash", "version": 2}} + return MagicMock(id=container_id, read=AsyncMock(return_value=properties)) + class AsyncIterator: """Simple async iterator over a list of items.""" @@ -47,9 +59,9 @@ def _make_client(**overrides) -> AsyncCosmosMemoryClient: return AsyncCosmosMemoryClient(**defaults) -def _connected_client() -> tuple[AsyncCosmosMemoryClient, MagicMock]: +def _connected_client(**client_kwargs) -> tuple[AsyncCosmosMemoryClient, MagicMock]: """Return a client with mocked split containers already wired up.""" - client = _make_client() + client = _make_client(**client_kwargs) container = MagicMock() turns = MagicMock() summaries = MagicMock() @@ -105,6 +117,42 @@ def test_default_credential_enabled(self): assert mem._cosmos_credential is not None +# =================================================================== +# Tenant binding +# =================================================================== + + +class TestTenant: + def test_a_client_is_bound_to_the_default_tenant_unless_given_one(self): + assert _make_client().tenant_id == DEFAULT_TENANT_ID + + def test_the_tenant_is_the_constructor_argument(self): + assert _make_client(tenant_id="acme").tenant_id == "acme" + + @pytest.mark.parametrize("tenant_id", ["", "a/b", 7]) + def test_a_tenant_that_cannot_be_stored_is_refused(self, tenant_id): + with pytest.raises(ValidationError): + _make_client(tenant_id=tenant_id) + + def test_the_tenant_cannot_be_changed_after_construction(self): + mem = _make_client(tenant_id="acme") + + with pytest.raises(AttributeError): + mem.tenant_id = "globex" + + def test_the_store_and_the_pipeline_are_bound_to_the_clients_tenant(self): + mem, _ = _connected_client(tenant_id="acme") + + assert mem._get_store().tenant_id == "acme" + assert mem._get_pipeline()._tenant_id == "acme" + + @pytest.mark.parametrize( + "method", ["update_cosmos", "delete_memory", "delete_turn", "add_tags", "remove_tags", "get_memory_history"] + ) + def test_a_memory_is_addressed_by_its_owner_not_its_thread(self, method): + assert "thread_id" not in inspect.signature(getattr(AsyncCosmosMemoryClient, method)).parameters + + # =================================================================== # Injected embeddings / chat clients # =================================================================== @@ -219,7 +267,7 @@ def test_add_local_turn_requires_thread_id(self): with pytest.raises(ValidationError, match="thread_id is required"): mem.add_local(user_id="u1", role="user", content="hi") # Validation must run BEFORE append - otherwise an orphan turn - # with thread_id=None would persist and pollute pk on push. + # with no thread_id would be buffered and pushed. assert mem.local_memory == [] assert mem._unflushed_turn_counts == {} @@ -354,20 +402,59 @@ async def test_preferred_locations_read_from_environment(self, monkeypatch, entr class TestCreateMemoryStore: + @staticmethod + async def _created_containers() -> list[dict]: + """The arguments of the five ``create_container_if_not_exists`` calls ``create_memory_store`` makes.""" + mock_cosmos_cls = MagicMock() + mock_db = AsyncMock() + mock_cosmos_cls.return_value.create_database_if_not_exists = AsyncMock(return_value=mock_db) + partition_key = MagicMock(side_effect=lambda **kwargs: SimpleNamespace(**kwargs)) + with patch.dict( + "sys.modules", + { + "azure.cosmos.aio": MagicMock(CosmosClient=mock_cosmos_cls), + "azure.cosmos": MagicMock(PartitionKey=partition_key, ThroughputProperties=MagicMock()), + }, + ): + await _make_client().create_memory_store( + endpoint="https://fake.documents.azure.com:443/", credential="fake-key" + ) + return [call.kwargs for call in mock_db.create_container_if_not_exists.await_args_list] + + async def test_the_containers_are_partitioned_by_tenant_and_user(self): + memories, turns, summaries, counter, leases = await self._created_containers() + + for container in (memories, turns, summaries, counter): + assert container["partition_key"].path == ["/tenant_id", "/user_id"] + assert container["partition_key"].kind == "MultiHash" + assert leases["partition_key"].path == "/id" + + async def test_the_summaries_composite_index_starts_with_the_partition_key(self): + summaries = (await self._created_containers())[2] + + assert summaries["indexing_policy"]["compositeIndexes"] == [ + [ + {"path": "/tenant_id", "order": "ascending"}, + {"path": "/user_id", "order": "ascending"}, + {"path": "/thread_id", "order": "ascending"}, + {"path": "/version", "order": "descending"}, + ] + ] + async def test_create_memory_store_with_counter_container(self): mem = _make_client() mock_cosmos_cls = MagicMock() mock_client = MagicMock() mock_db = AsyncMock() - mock_memories_container = MagicMock() - mock_counter_container = MagicMock() + mock_memories_container = _keyed_container() + mock_counter_container = _keyed_container() mock_lease_container = MagicMock() mock_throughput_cls = MagicMock(side_effect=lambda **kwargs: type("Throughput", (), kwargs)()) mock_cosmos_cls.return_value = mock_client mock_client.create_database_if_not_exists = AsyncMock(return_value=mock_db) - mock_turns_container = MagicMock() - mock_summaries_container = MagicMock() + mock_turns_container = _keyed_container() + mock_summaries_container = _keyed_container() mock_db.create_container_if_not_exists = AsyncMock( side_effect=[ mock_memories_container, @@ -426,14 +513,14 @@ async def test_create_memory_store_turns_container_uses_30_day_ttl(self): mock_cosmos_cls = MagicMock() mock_client = MagicMock() mock_db = AsyncMock() - mock_memories_container = MagicMock() - mock_counter_container = MagicMock() + mock_memories_container = _keyed_container() + mock_counter_container = _keyed_container() mock_lease_container = MagicMock() - mock_turns_container = MagicMock() + mock_turns_container = _keyed_container() mock_cosmos_cls.return_value = mock_client mock_client.create_database_if_not_exists = AsyncMock(return_value=mock_db) - mock_summaries_container = MagicMock() + mock_summaries_container = _keyed_container() mock_db.create_container_if_not_exists = AsyncMock( side_effect=[ mock_memories_container, @@ -477,14 +564,14 @@ async def test_create_memory_store_defaults_to_serverless(self): mock_cosmos_cls = MagicMock() mock_client = MagicMock() mock_db = AsyncMock() - mock_memories_container = MagicMock() - mock_counter_container = MagicMock() + mock_memories_container = _keyed_container() + mock_counter_container = _keyed_container() mock_lease_container = MagicMock() mock_cosmos_cls.return_value = mock_client mock_client.create_database_if_not_exists = AsyncMock(return_value=mock_db) - mock_turns_container = MagicMock() - mock_summaries_container = MagicMock() + mock_turns_container = _keyed_container() + mock_summaries_container = _keyed_container() mock_db.create_container_if_not_exists = AsyncMock( side_effect=[ mock_memories_container, @@ -514,6 +601,39 @@ async def test_create_memory_store_defaults_to_serverless(self): for call in mock_db.create_container_if_not_exists.await_args_list: assert "offer_throughput" not in call.kwargs + @pytest.mark.parametrize("earlier", ["memories", "memories_turns", "memories_summaries", "counter"]) + async def test_an_existing_container_with_the_earlier_key_is_refused(self, earlier): + containers = { + name: _keyed_container(container_id=name) + for name in ("memories", "memories_turns", "memories_summaries", "counter") + } + containers[earlier] = _keyed_container(EARLIER_KEY, container_id=earlier) + mock_cosmos_cls = MagicMock() + mock_cosmos_cls.return_value.close = AsyncMock() + mock_db = AsyncMock() + mock_db.create_container_if_not_exists = AsyncMock(side_effect=[*containers.values(), MagicMock()]) + mock_cosmos_cls.return_value.create_database_if_not_exists = AsyncMock(return_value=mock_db) + mem = _make_client() + + with patch.dict( + "sys.modules", + { + "azure.cosmos.aio": MagicMock(CosmosClient=mock_cosmos_cls), + "azure.cosmos": MagicMock(PartitionKey=MagicMock(), ThroughputProperties=MagicMock()), + }, + ): + with pytest.raises( + CosmosOperationError, + match=rf"container '{earlier}' has partition key \['/user_id', '/thread_id'\].*recreate the container", + ): + await mem.create_memory_store(endpoint="https://fake.documents.azure.com:443/", credential="fake-key") + + mock_cosmos_cls.return_value.close.assert_awaited_once() + assert mem._cosmos_client is None + assert mem._memories_container_client is None + with pytest.raises(CosmosNotConnectedError): + await mem._require_cosmos() + def test_constructor_ignores_autoscale_in_serverless_mode(self): # Even an invalid autoscale value is ignored in serverless mode. mem = _make_client(cosmos_throughput_mode="serverless", cosmos_autoscale_max_ru="not-an-int") @@ -537,23 +657,37 @@ async def test_require_cosmos_after_connect(self): class TestValidateTopology: - async def test_validate_topology_succeeds_on_healthy_deploy(self): + CONTAINER_ATTRIBUTES = { + "memories": "_memories_container_client", + "memories_turns": "_turns_container_client", + "memories_summaries": "_summaries_container_client", + "counter": "_counter_container_client", + } + + def _connected(self, earlier=None): mem = _make_client() - memories = MagicMock(id="memories") - turns = MagicMock(id="memories_turns") - summaries = MagicMock(id="memories_summaries") - memories.read = AsyncMock() - turns.read = AsyncMock() - summaries.read = AsyncMock() - mem._memories_container_client = memories - mem._turns_container_client = turns - mem._summaries_container_client = summaries + containers = { + name: _keyed_container(EARLIER_KEY if name == earlier else PARTITION_KEY_PATHS, container_id=name) + for name in self.CONTAINER_ATTRIBUTES + } + for name, attribute in self.CONTAINER_ATTRIBUTES.items(): + setattr(mem, attribute, containers[name]) + return mem, containers + + async def test_validate_topology_succeeds_on_healthy_deploy(self): + mem, containers = self._connected() await mem.validate_topology() - memories.read.assert_awaited_once() - turns.read.assert_awaited_once() - summaries.read.assert_awaited_once() + for container in containers.values(): + container.read.assert_awaited_once() + + @pytest.mark.parametrize("earlier", ["memories", "memories_turns", "memories_summaries", "counter"]) + async def test_validate_topology_raises_on_a_container_with_the_earlier_key(self, earlier): + mem, _ = self._connected(earlier) + + with pytest.raises(RuntimeError, match=rf"validate_topology: container '{earlier}' has partition key"): + await mem.validate_topology() async def test_validate_topology_raises_on_missing_container(self): from azure.cosmos.exceptions import CosmosResourceNotFoundError @@ -714,18 +848,19 @@ async def test_with_recent_k(self): class TestUpdateCosmos: async def test_success(self): - mem, container = _connected_client() - doc = _make_doc(id="m1", type="fact") + mem, container = _connected_client(tenant_id="acme") + doc = _make_doc(id="m1", type="fact", tenant_id="acme") container.read_item = AsyncMock(return_value=doc) container.replace_item = AsyncMock() - await mem.update_cosmos(memory_id="m1", user_id="u1", thread_id="t1", memory_type="fact", content="updated") + await mem.update_cosmos(memory_id="m1", user_id="u1", memory_type="fact", content="updated") - container.read_item.assert_awaited_once_with(item="m1", partition_key=["u1", "t1"]) + container.read_item.assert_awaited_once_with(item="m1", partition_key=["acme", "u1"]) container.replace_item.assert_awaited_once() body = container.replace_item.call_args.kwargs["body"] assert body["content"] == "updated" assert body["type"] == "fact" + assert body["tenant_id"] == "acme" assert "updated_at" in body async def test_not_found(self): @@ -735,7 +870,7 @@ async def test_not_found(self): container.read_item = AsyncMock(side_effect=CosmosResourceNotFoundError(message="404")) with pytest.raises(MemoryNotFoundError): - await mem.update_cosmos(memory_id="missing", user_id="u1", thread_id="t1", memory_type="fact") + await mem.update_cosmos(memory_id="missing", user_id="u1", memory_type="fact") async def test_partial_fields(self): mem, container = _connected_client() @@ -743,9 +878,7 @@ async def test_partial_fields(self): container.read_item = AsyncMock(return_value=doc) container.replace_item = AsyncMock() - await mem.update_cosmos( - memory_id="m1", user_id="u1", thread_id="t1", memory_type="fact", role="agent", metadata={"key": "val"} - ) + await mem.update_cosmos(memory_id="m1", user_id="u1", memory_type="fact", role="agent", metadata={"key": "val"}) body = container.replace_item.call_args.kwargs["body"] assert body["role"] == "agent" assert body["metadata"] == {"key": "val"} @@ -755,13 +888,13 @@ async def test_partial_fields(self): class TestDeleteCosmos: async def test_success(self): - mem, container = _connected_client() - container.read_item = AsyncMock(return_value=_make_doc(id="m1", type="fact")) + mem, container = _connected_client(tenant_id="acme") + container.read_item = AsyncMock(return_value=_make_doc(id="m1", type="fact", tenant_id="acme")) container.delete_item = AsyncMock() - await mem.delete_memory(memory_id="m1", user_id="u1", thread_id="t1", memory_type="fact") + await mem.delete_memory(memory_id="m1", user_id="u1", memory_type="fact") - container.delete_item.assert_awaited_once_with(item="m1", partition_key=["u1", "t1"]) + container.delete_item.assert_awaited_once_with(item="m1", partition_key=["acme", "u1"]) async def test_not_found(self): from azure.cosmos.exceptions import CosmosResourceNotFoundError @@ -771,23 +904,23 @@ async def test_not_found(self): container.delete_item = AsyncMock() with pytest.raises(MemoryNotFoundError): - await mem.delete_memory(memory_id="x", user_id="u1", thread_id="t1", memory_type="fact") + await mem.delete_memory(memory_id="x", user_id="u1", memory_type="fact") container.delete_item.assert_not_awaited() class TestGetUserSummary: async def test_returns_doc_when_present(self): - mem, _ = _connected_client() + mem, _ = _connected_client(tenant_id="acme") summaries = mem._summaries_container_client - doc = _make_doc(type="user_summary", id="user_summary_u1") + doc = _make_doc(type="user_summary", id="user_summary_u1", tenant_id="acme") summaries.read_item = AsyncMock(return_value=doc) result = await mem.get_user_summary(user_id="u1") call_kwargs = summaries.read_item.call_args.kwargs assert call_kwargs["item"] == "user_summary_u1" - assert call_kwargs["partition_key"] == ["u1", "__user_summary__"] + assert call_kwargs["partition_key"] == ["acme", "u1"] assert result == doc async def test_returns_none_when_absent(self): @@ -815,9 +948,9 @@ async def test_cosmos_ops_without_connect(self): with pytest.raises(CosmosNotConnectedError): await mem.get_thread(thread_id="t1") with pytest.raises(CosmosNotConnectedError): - await mem.update_cosmos(memory_id="m1", user_id="u1", thread_id="t1", memory_type="fact") + await mem.update_cosmos(memory_id="m1", user_id="u1", memory_type="fact") with pytest.raises(CosmosNotConnectedError): - await mem.delete_memory(memory_id="m1", user_id="u1", thread_id="t1", memory_type="fact") + await mem.delete_memory(memory_id="m1", user_id="u1", memory_type="fact") # =================================================================== @@ -1011,14 +1144,16 @@ async def test_context_manager(self): async def test_list_tags_delegates_to_store(): - mem, container = _connected_client() + mem, container = _connected_client(tenant_id="acme") container.query_items = MagicMock(return_value=AsyncIterator([["topic:python", "sys:fact"]])) assert await mem.list_tags("u1") == ["topic:python"] kwargs = container.query_items.call_args.kwargs assert "SELECT VALUE c.tags" in kwargs["query"] - assert kwargs["parameters"] == [{"name": "@user_id", "value": "u1"}] + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in kwargs["query"] + assert kwargs["parameters"] == [{"name": "@tenant_id", "value": "acme"}, {"name": "@user_id", "value": "u1"}] + assert kwargs["partition_key"] == ["acme", "u1"] class TestAsyncSearchCosmosUnifiedRetrieval: @@ -1122,28 +1257,24 @@ class TestAsyncDeleteHelpers: async def test_delete_turn_delegates_with_turn_type(self): mem = _make_client() mem.delete_memory = AsyncMock() - await mem.delete_turn("turn-1", user_id="u1", thread_id="t1") - mem.delete_memory.assert_awaited_once_with("turn-1", user_id="u1", thread_id="t1", memory_type="turn") + await mem.delete_turn("turn-1", user_id="u1") + mem.delete_memory.assert_awaited_once_with("turn-1", user_id="u1", memory_type="turn") @pytest.mark.asyncio async def test_delete_thread_summary_returns_true_then_false(self): mem = _make_client() mem.delete_memory = AsyncMock() assert await mem.delete_thread_summary("u1", "t1") is True - mem.delete_memory.assert_awaited_once_with( - "summary_u1_t1", user_id="u1", thread_id="t1", memory_type="thread_summary" - ) - mem.delete_memory = AsyncMock(side_effect=MemoryNotFoundError(memory_id="x", user_id="u1", thread_id="t1")) + mem.delete_memory.assert_awaited_once_with("summary_u1_t1", user_id="u1", memory_type="thread_summary") + mem.delete_memory = AsyncMock(side_effect=MemoryNotFoundError(memory_id="x", user_id="u1")) assert await mem.delete_thread_summary("u1", "t1") is False @pytest.mark.asyncio - async def test_delete_user_summary_uses_deterministic_id_and_scope(self): + async def test_delete_user_summary_uses_deterministic_id(self): mem = _make_client() mem.delete_memory = AsyncMock() assert await mem.delete_user_summary("u1") is True - mem.delete_memory.assert_awaited_once_with( - "user_summary_u1", user_id="u1", thread_id="__user_summary__", memory_type="user_summary" - ) + mem.delete_memory.assert_awaited_once_with("user_summary_u1", user_id="u1", memory_type="user_summary") @pytest.mark.asyncio async def test_delete_thread_deletes_turns_and_summary_and_counts(self): @@ -1161,7 +1292,7 @@ async def test_delete_thread_skips_missing_turn(self): async def _delete(memory_id, **kwargs): if memory_id == "turn-1": - raise MemoryNotFoundError(memory_id="turn-1", user_id="u1", thread_id="t1") + raise MemoryNotFoundError(memory_id="turn-1", user_id="u1") mem.delete_memory = AsyncMock(side_effect=_delete) deleted = await mem.delete_thread("u1", "t1", include_summary=False) @@ -1172,3 +1303,100 @@ async def test_delete_thread_requires_ids(self): mem = _make_client() with pytest.raises(ValidationError): await mem.delete_thread("", "t1") + + +# =================================================================== +# Tenant isolation: a client bound to a tenant reads, writes and deletes only inside it +# =================================================================== + +_READS = { + "get_memories": lambda mem: mem.get_memories(user_id="u1", thread_id="t1"), + "get_memories_of_every_user": lambda mem: mem.get_memories(), + "get_thread": lambda mem: mem.get_thread(thread_id="t1", user_id="u1"), + "get_thread_of_every_user": lambda mem: mem.get_thread(thread_id="t1"), + "get_thread_summary": lambda mem: mem.get_thread_summary("u1", "t1"), + "get_episodes": lambda mem: mem.get_episodes("u1"), + "list_tags": lambda mem: mem.list_tags("u1"), + "get_procedural_memories": lambda mem: mem.get_procedural_memories("u1"), + "get_procedural_history": lambda mem: mem.get_procedural_history("u1"), + "get_memory_history": lambda mem: mem.get_memory_history("m1", "u1"), + "search_cosmos": lambda mem: mem.search_cosmos("weather", user_id="u1"), + "search_cosmos_by_keywords_of_every_user": lambda mem: mem.search_cosmos("weather Seattle"), + "search_turns": lambda mem: mem.search_turns("weather", user_id="u1", thread_id="t1"), + "search_summaries": lambda mem: mem.search_summaries("weather", user_id="u1"), + "search_episodic_memories": lambda mem: mem.search_episodic_memories("u1", "weather"), + "retrieve_procedures": lambda mem: mem.retrieve_procedures("u1", "weather"), +} + + +class TestTenantIsolation: + @pytest.mark.parametrize("read", _READS.values(), ids=_READS.keys()) + async def test_every_query_a_read_sends_is_confined_to_the_tenant(self, read): + mem, _ = _connected_client(tenant_id="acme") + mem._embeddings_client = AsyncMock() + mem._embeddings_client.generate = AsyncMock(return_value=[0.1, 0.2, 0.3]) + + await read(mem) + + sent = [ + call.kwargs + for container in ( + mem._memories_container_client, + mem._turns_container_client, + mem._summaries_container_client, + ) + for call in container.query_items.call_args_list + ] + assert sent + for query in sent: + assert "c.tenant_id = @tenant_id" in query["query"] + assert {"name": "@tenant_id", "value": "acme"} in query["parameters"] + assert query.get("partition_key") in (None, ["acme", "u1"]) + + async def test_a_written_turn_carries_the_tenant(self): + mem, _ = _connected_client(tenant_id="acme") + mem._maybe_auto_trigger = AsyncMock() + + await mem.upsert_memory(user_id="u1", role="user", content="hello", thread_id="t1") + await asyncio.gather(*list(mem._background_tasks), return_exceptions=True) + + body = mem._turns_container_client.upsert_item.call_args.kwargs["body"] + assert (body["tenant_id"], body["user_id"], body["thread_id"]) == ("acme", "u1", "t1") + + async def test_pushed_memories_carry_the_tenant(self): + mem, memories = _connected_client(tenant_id="acme") + mem._maybe_auto_trigger = AsyncMock() + mem.add_local(user_id="u1", role="user", content="prefers dark mode", memory_type="fact") + mem.add_local(user_id="u1", role="user", content="hello", thread_id="t1") + + await mem.push_to_cosmos() + await asyncio.gather(*list(mem._background_tasks), return_exceptions=True) + + written = [*memories.upsert_item.call_args_list, *mem._turns_container_client.upsert_item.call_args_list] + assert [call.kwargs["body"]["tenant_id"] for call in written] == ["acme", "acme"] + + async def test_a_record_that_names_another_tenant_is_refused(self): + mem, memories = _connected_client(tenant_id="acme") + mem.add_local(user_id="u1", role="user", content="prefers dark mode", memory_type="fact") + mem.local_memory[0]["tenant_id"] = "globex" + + with pytest.raises(ValidationError): + await mem.push_to_cosmos() + + memories.upsert_item.assert_not_awaited() + + async def test_a_thread_is_deleted_from_the_owners_partition_of_the_tenant(self): + mem, _ = _connected_client(tenant_id="acme") + turns, summaries = mem._turns_container_client, mem._summaries_container_client + turn = _make_doc(id="turn-1", tenant_id="acme") + turns.query_items = MagicMock(return_value=AsyncIterator([turn])) + turns.read_item = AsyncMock(return_value=turn) + summaries.read_item = AsyncMock( + return_value=_make_doc(id="summary_u1_t1", type="thread_summary", tenant_id="acme") + ) + + assert await mem.delete_thread("u1", "t1") == 2 + + for container in (turns, summaries): + container.delete_item.assert_awaited_once() + assert container.delete_item.call_args.kwargs["partition_key"] == ["acme", "u1"] diff --git a/tests/unit/aio/test_reconcile_passes.py b/tests/unit/aio/test_reconcile_passes.py index d0670b8..87b61d8 100644 --- a/tests/unit/aio/test_reconcile_passes.py +++ b/tests/unit/aio/test_reconcile_passes.py @@ -19,6 +19,7 @@ from azure.cosmos.agent_memory.services._dedup import dedup_result NEAR = [1.0, 0.0, 0.0] +TENANT = "acme" ASYNC_LOGGER_NAME = "azure.cosmos.agent_memory.pipeline.aio" RESULT_KEYS = { "kept", @@ -42,6 +43,7 @@ def _dedup_only(monkeypatch): def _fact(fid: str, content: str, *, vector=None, ts: int = 1, created_at: str = "2024-01-01T00:00:00+00:00") -> dict: doc = { "id": fid, + "tenant_id": TENANT, "user_id": "u1", "thread_id": "t1", "type": "fact", @@ -94,6 +96,7 @@ def _store() -> _Store: def _make_pipeline(store: _Store, replies: list[dict]) -> AsyncPipelineService: p = AsyncPipelineService.__new__(AsyncPipelineService) + p._tenant_id = TENANT p._container = MagicMock() p._container.query_items = AsyncMock(side_effect=store.query_items) p._container.read_item = AsyncMock(side_effect=CosmosResourceNotFoundError(message="no dedup cursor yet")) @@ -147,7 +150,12 @@ async def test_the_dedup_cursor_is_written_and_the_facts_are_not_read_again(self await p.reconcile_memories("u1") body = p._container.create_item.call_args.kwargs["body"] - assert (body["id"], body["thread_id"], body["last_ts"]) == ("dedup_cursor_u1_fact", "__dedup__", 4) + assert (body["id"], body["tenant_id"], body["thread_id"], body["last_ts"]) == ( + "dedup_cursor_u1_fact", + TENANT, + "__dedup__", + 4, + ) assert not [query for query in store.queries if "ORDER BY c.created_at DESC" in query] async def test_a_pass_with_nothing_to_fold_retires_nothing(self): diff --git a/tests/unit/aio/test_search_slots.py b/tests/unit/aio/test_search_slots.py index fb1cc5d..646cea0 100644 --- a/tests/unit/aio/test_search_slots.py +++ b/tests/unit/aio/test_search_slots.py @@ -19,6 +19,7 @@ PREFERENCE = {"id": "pref_a", "content": "The user prefers pnpm.", "metadata": {"category": "preference"}} PROCEDURE = {"id": "proc_a", "content": "Run targeted tests before reporting success.", "type": "procedural"} CLIENT_LOGGER = "azure.cosmos.agent_memory.aio.cosmos_memory_client" +TENANT = "acme" # A procedure has no salience or confidence, its role is "system" and its tags are the pipeline's own, so # these filters could never match one. FACT_ONLY_FILTERS = { @@ -62,6 +63,7 @@ def _store() -> tuple[AsyncMemoryStore, MagicMock, MagicMock]: store = AsyncMemoryStore( containers={key: memories for key in (ContainerKey.TURNS, ContainerKey.MEMORIES, ContainerKey.SUMMARIES)}, embeddings_client=embeddings, + tenant_id=TENANT, ) return store, memories, embeddings @@ -117,8 +119,8 @@ async def test_the_procedure_slot_search_is_a_vector_search_of_the_users_situati assert "ORDER BY VectorDistance" in call["query"] and "FullTextScore" not in call["query"] assert "c.applies = @applies" in call["query"] assert PROCEDURES_IN_FORCE in call["query"] - assert (params["@user_id"], params["@applies"]) == ("u1", "when") - assert "partition_key" not in call, "procedures live under a sentinel thread, so a thread cannot key the query" + assert (params["@tenant_id"], params["@user_id"], params["@applies"]) == (TENANT, "u1", "when") + assert call["partition_key"] == [TENANT, "u1"], "a thread does not key the query: the owner's partition does" async def test_the_procedure_slot_query_asks_for_nothing_a_procedure_lacks(): diff --git a/tests/unit/function_app/test_change_feed.py b/tests/unit/function_app/test_change_feed.py index 899babb..cebc6d2 100644 --- a/tests/unit/function_app/test_change_feed.py +++ b/tests/unit/function_app/test_change_feed.py @@ -3,19 +3,27 @@ Mocks the durable client's ``start_new`` and the counter container so the trigger's pure-logic entry point :func:`process_changefeed_batch` can be exercised without Azure Functions or Cosmos DB. + +Every turn names its tenant (``acme`` unless a test says otherwise): counters, instance ids and orchestrator +inputs are per ``(tenant_id, user_id[, thread_id])``. """ from __future__ import annotations import asyncio +import logging import os +import re from unittest.mock import AsyncMock, MagicMock, patch import pytest import triggers.change_feed as change_feed_module from azure.cosmos.exceptions import CosmosHttpResponseError, CosmosResourceNotFoundError +from shared.instance_ids import orchestration_instance_id from triggers.change_feed import process_changefeed_batch +TENANT = "acme" + @pytest.fixture(autouse=True) def _default_owner_durable(monkeypatch): @@ -34,8 +42,8 @@ def _default_owner_durable(monkeypatch): # --------------------------------------------------------------------------- -def _turn(user_id: str = "u1", thread_id: str = "t1", lsn: int | None = None) -> dict: - doc: dict = {"type": "turn", "user_id": user_id, "thread_id": thread_id} +def _turn(user_id: str = "u1", thread_id: str = "t1", lsn: int | None = None, tenant_id: str = TENANT) -> dict: + doc: dict = {"type": "turn", "tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id} if lsn is not None: doc["_lsn"] = lsn return doc @@ -48,33 +56,42 @@ def _make_starter() -> MagicMock: def _make_counter_container_starting_at(start_count: int = 0) -> MagicMock: - """Return a counter container whose ``read_item`` answers from an in-mem - dict and whose ``create_item``/``upsert_item`` mutate that same dict. + """Return a counter container that keeps its documents per logical partition. - Lets the test mimic a real Cosmos counter without needing the SDK. + ``read_item`` answers from an in-memory dict keyed by ``(tenant_id, user_id, id)``, that is, by the partition key + ``[tenant_id, user_id]`` plus the document id, and ``create_item``/``upsert_item`` mutate that same dict, taking + the partition from the document. A read in another partition than the write finds nothing, as in Cosmos. """ - state: dict[str, dict] = {} + state: dict[tuple[str, str, str], dict] = {} if start_count: # Seeded entries can be supplied by the test if needed; default empty. pass container = MagicMock() + def slot(partition_key, item): + tenant_id, user_id = partition_key + return (tenant_id, user_id, item) + async def read_item(*, item, partition_key): - if item not in state: + key = slot(partition_key, item) + if key not in state: raise CosmosResourceNotFoundError(message="404") - return dict(state[item]) + return dict(state[key]) async def create_item(*, body): - state[body["id"]] = dict(body) + state[slot([body["tenant_id"], body["user_id"]], body["id"])] = dict(body) return body async def upsert_item(*, body, **_kwargs): - state[body["id"]] = dict(body) + state[slot([body["tenant_id"], body["user_id"]], body["id"])] = dict(body) return body async def patch_item(*, item, partition_key, patch_operations, filter_predicate=None): - doc = state.setdefault(item, {"id": item}) + key = slot(partition_key, item) + if key not in state: + raise CosmosResourceNotFoundError(message="404") + doc = state[key] if filter_predicate is not None: # Honor the monotonic watermark guard: apply only when the new # last_extract_count exceeds the stored one (else Cosmos returns 412). @@ -97,18 +114,37 @@ async def patch_item(*, item, partition_key, patch_operations, filter_predicate= return container -def _make_topology_db(missing_name: str | None = None): +def _counter(container: MagicMock, counter_id: str, *, tenant_id: str = TENANT, user_id: str = "u1") -> dict: + """The counter document ``counter_id`` of ``user_id`` in ``tenant_id``.""" + return container._state[(tenant_id, user_id, counter_id)] + + +def _thread_instance_id( + kind: str, count: int, *, tenant_id: str = TENANT, user_id: str = "u1", thread_id: str = "t1" +) -> str: + """The instance id of a thread-scoped orchestration: a hash of the tenant, user and thread, and the count.""" + return orchestration_instance_id(kind, tenant_id, user_id, thread_id, count=count) + + +def _user_instance_id(count: int, *, tenant_id: str = TENANT, user_id: str = "u1") -> str: + """The instance id of a user summary: a hash of the tenant and user, and the count.""" + return orchestration_instance_id("user_summary", tenant_id, user_id, count=count) + + +def _make_topology_db(missing_name: str | None = None, earlier_key_name: str | None = None): containers: dict[str, MagicMock] = {} for name in ( change_feed_module.config.TURNS_CONTAINER, change_feed_module.config.MEMORIES_CONTAINER, change_feed_module.config.SUMMARIES_CONTAINER, + change_feed_module.config.COUNTERS_CONTAINER, ): container = MagicMock() if name == missing_name: container.read = AsyncMock(side_effect=CosmosResourceNotFoundError(message="missing")) else: - container.read = AsyncMock() + paths = ["/user_id", "/thread_id"] if name == earlier_key_name else ["/tenant_id", "/user_id"] + container.read = AsyncMock(return_value={"id": name, "partitionKey": {"paths": paths, "kind": "MultiHash"}}) containers[name] = container db = MagicMock() @@ -129,7 +165,7 @@ def test_ensure_topology_succeeds_when_all_containers_exist(): asyncio.run(change_feed_module._ensure_topology()) assert change_feed_module._topology_validated is True - assert db.get_container_client.call_count == 3 + assert db.get_container_client.call_count == 4 for container in containers.values(): container.read.assert_awaited_once() @@ -148,6 +184,28 @@ def test_ensure_topology_raises_on_missing_container(): assert change_feed_module._topology_validated is False +@pytest.mark.parametrize( + "earlier", + [ + change_feed_module.config.TURNS_CONTAINER, + change_feed_module.config.MEMORIES_CONTAINER, + change_feed_module.config.SUMMARIES_CONTAINER, + change_feed_module.config.COUNTERS_CONTAINER, + ], +) +def test_ensure_topology_raises_on_a_container_with_the_earlier_key(earlier): + change_feed_module._topology_validated = False + db, _containers = _make_topology_db(earlier_key_name=earlier) + + with patch("shared.cosmos_clients.get_cosmos_database_async", new=AsyncMock(return_value=db)): + with pytest.raises(RuntimeError, match=rf"Topology error: container '{earlier}' has partition key") as error: + asyncio.run(change_feed_module._ensure_topology()) + + assert "['/user_id', '/thread_id']" in str(error.value) + assert "recreate" in str(error.value) + assert change_feed_module._topology_validated is False + + def test_ensure_topology_is_idempotent(): change_feed_module._topology_validated = False db, containers = _make_topology_db() @@ -161,7 +219,7 @@ async def run_twice(): asyncio.run(run_twice()) assert get_db.await_count == 1 - assert sum(container.read.await_count for container in containers.values()) == 3 + assert sum(container.read.await_count for container in containers.values()) == 4 # --------------------------------------------------------------------------- @@ -249,9 +307,9 @@ def test_non_turn_documents_are_filtered_out(): container = _make_counter_container_starting_at() docs = [ - {"type": "thread_summary", "user_id": "u1", "thread_id": "t1"}, - {"type": "fact", "user_id": "u1", "thread_id": "t1"}, - {"type": "user_summary", "user_id": "u1", "thread_id": "__user_summary__"}, + {"type": "thread_summary", "tenant_id": TENANT, "user_id": "u1", "thread_id": "t1"}, + {"type": "fact", "tenant_id": TENANT, "user_id": "u1", "thread_id": "t1"}, + {"type": "user_summary", "tenant_id": TENANT, "user_id": "u1", "thread_id": "__user_summary__"}, ] asyncio.run(process_changefeed_batch(docs, starter, counter_container=container)) @@ -285,7 +343,7 @@ def test_sub_threshold_batch_does_not_start_orchestrator(): assert starter.start_new.await_count == 0 # We DID still increment the counter. assert container.create_item.await_count == 1 - assert container._state["thread:u1:t1"]["count"] == 3 + assert _counter(container, "thread:u1:t1")["count"] == 3 @patch.dict( @@ -301,14 +359,88 @@ def test_turn_doc_missing_ids_is_skipped(): starter = _make_starter() container = _make_counter_container_starting_at() docs = [ - {"type": "turn", "user_id": "u1"}, # missing thread_id - {"type": "turn", "thread_id": "t1"}, # missing user_id + {"type": "turn", "tenant_id": TENANT, "user_id": "u1"}, # missing thread_id + {"type": "turn", "tenant_id": TENANT, "thread_id": "t1"}, # missing user_id ] asyncio.run(process_changefeed_batch(docs, starter, counter_container=container)) assert starter.start_new.await_count == 0 assert container.read_item.await_count == 0 +_NO_TENANT = object() + + +@patch.dict( + os.environ, + { + "THREAD_SUMMARY_EVERY_N": "2", + "FACT_EXTRACTION_EVERY_N": "0", + "EPISODE_EVAL_EVERY_N": "0", + "USER_SUMMARY_EVERY_N": "0", + }, + clear=False, +) +@pytest.mark.parametrize( + "tenant_id", + [ + pytest.param(_NO_TENANT, id="missing"), + pytest.param(None, id="null"), + pytest.param("", id="empty"), + pytest.param(" ", id="blank"), + pytest.param(7, id="not-a-string"), + pytest.param("acme/eu", id="slash"), + pytest.param("acme#eu", id="hash"), + pytest.param("x" * 300, id="too-long"), + ], +) +def test_a_turn_without_a_valid_tenant_is_skipped_with_a_warning_that_quotes_nothing(tenant_id, caplog): + """The tenant is never guessed: a turn that names none, or an unusable one, is counted nowhere (not under the + default tenant either) and the valid turns of the same batch still are.""" + caplog.set_level(logging.WARNING) + starter = _make_starter() + container = _make_counter_container_starting_at() + unusable = {"type": "turn", "user_id": "u2", "thread_id": "t2", "content": "private text"} + if tenant_id is not _NO_TENANT: + unusable["tenant_id"] = tenant_id + + asyncio.run(process_changefeed_batch([unusable, unusable, _turn(), _turn()], starter, counter_container=container)) + + assert list(container._state) == [(TENANT, "u1", "thread:u1:t1")] + assert [(c.args[0], c.kwargs["instance_id"]) for c in starter.start_new.await_args_list] == [ + ("ThreadSummaryOrchestrator", _thread_instance_id("thread_summary", 2)) + ] + warnings = [r.getMessage() for r in caplog.records if r.levelno == logging.WARNING] + assert warnings == ["change-feed: turn doc missing a valid tenant_id, user_id or thread_id, skipping"] * 2 + + +@patch.dict( + os.environ, + { + "THREAD_SUMMARY_EVERY_N": "2", + "FACT_EXTRACTION_EVERY_N": "0", + "EPISODE_EVAL_EVERY_N": "0", + "USER_SUMMARY_EVERY_N": "0", + }, + clear=False, +) +@pytest.mark.parametrize("owner", ["", " ", 7, "a/b", "a#b", "o" * 300], ids=repr) +def test_a_turn_with_an_unsupported_owner_is_skipped_like_one_without_a_tenant(owner, caplog): + """An owner the SDK would refuse is never counted; the valid turns of the same batch still are.""" + caplog.set_level(logging.WARNING) + starter = _make_starter() + container = _make_counter_container_starting_at() + unusable = {"type": "turn", "tenant_id": TENANT, "user_id": owner, "thread_id": "t2", "content": "private text"} + + asyncio.run(process_changefeed_batch([unusable, _turn(), _turn()], starter, counter_container=container)) + + assert list(container._state) == [(TENANT, "u1", "thread:u1:t1")] + assert [(c.args[0], c.kwargs["instance_id"]) for c in starter.start_new.await_args_list] == [ + ("ThreadSummaryOrchestrator", _thread_instance_id("thread_summary", 2)) + ] + warnings = [r.getMessage() for r in caplog.records if r.levelno == logging.WARNING] + assert warnings == ["change-feed: turn doc missing a valid tenant_id, user_id or thread_id, skipping"] + + # --------------------------------------------------------------------------- # Threshold crossing → deterministic instance IDs # --------------------------------------------------------------------------- @@ -339,9 +471,9 @@ def test_thread_threshold_crossing_starts_summary_and_extract(): ) started = {(call.args[0], call.kwargs["instance_id"]) for call in starter.start_new.await_args_list} - assert ("ThreadSummaryOrchestrator", "thread_summary:u1:t1:4") in started - assert ("ExtractMemoriesOrchestrator", "extract:u1:t1:4") in started - assert ("ExtractEpisodesOrchestrator", "episode:u1:t1:4") in started + assert ("ThreadSummaryOrchestrator", _thread_instance_id("thread_summary", 4)) in started + assert ("ExtractMemoriesOrchestrator", _thread_instance_id("extract", 4)) in started + assert ("ExtractEpisodesOrchestrator", _thread_instance_id("episode", 4)) in started # User threshold 20 not crossed by 4 turns. assert not any(name == "UserSummaryOrchestrator" for name, _ in started) @@ -371,8 +503,8 @@ def test_episode_threshold_crossing_starts_extract_episodes(): episode_calls = [c for c in starter.start_new.await_args_list if c.args[0] == "ExtractEpisodesOrchestrator"] assert len(episode_calls) == 1 call = episode_calls[0] - assert call.kwargs["instance_id"] == "episode:u1:t1:4" - assert call.kwargs["client_input"] == {"user_id": "u1", "thread_id": "t1", "count": 4} + assert call.kwargs["instance_id"] == _thread_instance_id("episode", 4) + assert call.kwargs["client_input"] == {"tenant_id": TENANT, "user_id": "u1", "thread_id": "t1", "count": 4} @patch.dict( @@ -399,14 +531,14 @@ def test_user_threshold_crossing_starts_user_summary(): started = {(call.args[0], call.kwargs["instance_id"]) for call in starter.start_new.await_args_list} # Exactly one user-summary, deterministic instance id at count=20. - assert ("UserSummaryOrchestrator", "user_summary:u1:20") in started + assert ("UserSummaryOrchestrator", _user_instance_id(20)) in started user_summary_starts = [n for n, _ in started if n == "UserSummaryOrchestrator"] assert len(user_summary_starts) == 1 - # Payload must include the contributing thread_ids so the orchestrator - # can scope the user-summary query (avoids a full cross-partition scan). + # Payload carries the contributing thread_ids. us_call = next(c for c in starter.start_new.await_args_list if c.args[0] == "UserSummaryOrchestrator") payload = us_call.kwargs["client_input"] + assert payload["tenant_id"] == TENANT assert payload["user_id"] == "u1" assert sorted(payload["thread_ids"]) == ["t0", "t1", "t2", "t3"] @@ -470,6 +602,7 @@ def test_disabled_episode_does_not_start_extract_episodes(): { "THREAD_SUMMARY_EVERY_N": "4", "FACT_EXTRACTION_EVERY_N": "4", + "EPISODE_EVAL_EVERY_N": "4", "USER_SUMMARY_EVERY_N": "20", }, clear=False, @@ -492,11 +625,12 @@ def test_per_thread_grouping_is_correct(): asyncio.run(process_changefeed_batch(docs, starter, counter_container=container)) started = {(call.args[0], call.kwargs["instance_id"]) for call in starter.start_new.await_args_list} - # t1 crossed → summary + extract started for t1 only. - assert ("ThreadSummaryOrchestrator", "thread_summary:u1:t1:4") in started - assert ("ExtractMemoriesOrchestrator", "extract:u1:t1:4") in started - # t2 below threshold - no orchestrators for t2. - assert not any("t2" in iid for _, iid in started) + # t1 crossed → summary, extract and episode started for t1 only; t2 is below every threshold. + assert started == { + ("ThreadSummaryOrchestrator", _thread_instance_id("thread_summary", 4)), + ("ExtractMemoriesOrchestrator", _thread_instance_id("extract", 4)), + ("ExtractEpisodesOrchestrator", _thread_instance_id("episode", 4)), + } @patch.dict( @@ -522,11 +656,226 @@ def test_orchestrator_payload_includes_count_and_ids(): for call in starter.start_new.await_args_list: payload = call.kwargs["client_input"] + assert payload["tenant_id"] == TENANT assert payload["user_id"] == "u1" assert payload["thread_id"] == "t1" assert payload["count"] == 4 +# --------------------------------------------------------------------------- +# Tenants: every scope is per (tenant_id, user_id[, thread_id]) +# --------------------------------------------------------------------------- + + +@patch.dict( + os.environ, + { + "THREAD_SUMMARY_EVERY_N": "4", + "FACT_EXTRACTION_EVERY_N": "4", + "EPISODE_EVAL_EVERY_N": "4", + "USER_SUMMARY_EVERY_N": "4", + }, + clear=False, +) +def test_every_orchestration_is_started_with_a_hashed_instance_id_and_the_tenant_in_its_input(): + starter = _make_starter() + container = _make_counter_container_starting_at() + + asyncio.run( + process_changefeed_batch([_turn(tenant_id="globex") for _ in range(4)], starter, counter_container=container) + ) + + calls = starter.start_new.await_args_list + started = {c.args[0]: (c.kwargs["instance_id"], c.kwargs["client_input"]) for c in calls} + instance_ids = {name: instance_id for name, (instance_id, _) in started.items()} + assert instance_ids == { + "ThreadSummaryOrchestrator": _thread_instance_id("thread_summary", 4, tenant_id="globex"), + "ExtractMemoriesOrchestrator": _thread_instance_id("extract", 4, tenant_id="globex"), + "ExtractEpisodesOrchestrator": _thread_instance_id("episode", 4, tenant_id="globex"), + "UserSummaryOrchestrator": _user_instance_id(4, tenant_id="globex"), + } + # An id names the kind and the count and hashes the rest: no tenant, user or thread in it. + assert all(re.fullmatch(r"[a-z_]+:[0-9a-f]{32}:4", instance_id) for instance_id in instance_ids.values()) + assert all(client_input["tenant_id"] == "globex" for _, client_input in started.values()) + + +@patch.dict( + os.environ, + { + "THREAD_SUMMARY_EVERY_N": "4", + "FACT_EXTRACTION_EVERY_N": "4", + "EPISODE_EVAL_EVERY_N": "4", + "USER_SUMMARY_EVERY_N": "4", + }, + clear=False, +) +def test_owners_with_very_long_ids_still_get_instance_ids_within_the_durable_limit(): + """Durable Functions takes at most 100 characters; ids of 200 characters each used to overflow it.""" + starter = _make_starter() + container = _make_counter_container_starting_at() + docs = [_turn(user_id="u" * 200, thread_id="h" * 200, tenant_id="t" * 200) for _ in range(4)] + + asyncio.run(process_changefeed_batch(docs, starter, counter_container=container)) + + instance_ids = [c.kwargs["instance_id"] for c in starter.start_new.await_args_list] + assert len(instance_ids) == 4 + assert all(re.fullmatch(r"[a-z_]+:[0-9a-f]{32}:4", instance_id) for instance_id in instance_ids) + + +@patch.dict( + os.environ, + { + "THREAD_SUMMARY_EVERY_N": "2", + "FACT_EXTRACTION_EVERY_N": "0", + "EPISODE_EVAL_EVERY_N": "0", + "USER_SUMMARY_EVERY_N": "0", + }, + clear=False, +) +def test_the_log_of_a_start_names_the_owner_because_the_instance_id_does_not(caplog): + caplog.set_level(logging.INFO) + starter = _make_starter() + container = _make_counter_container_starting_at() + + asyncio.run(process_changefeed_batch([_turn(), _turn()], starter, counter_container=container)) + + instance_id = _thread_instance_id("thread_summary", 2) + assert [r.getMessage() for r in caplog.records if r.getMessage().startswith("change-feed: starting")] == [ + f"change-feed: starting ThreadSummaryOrchestrator instance={instance_id} tenant=acme user=u1 thread=t1" + ] + + +@patch.dict( + os.environ, + { + "THREAD_SUMMARY_EVERY_N": "4", + "FACT_EXTRACTION_EVERY_N": "0", + "EPISODE_EVAL_EVERY_N": "0", + "USER_SUMMARY_EVERY_N": "4", + }, + clear=False, +) +def test_the_same_user_and_thread_in_two_tenants_are_counted_separately(): + """Two turns per tenant never add up to the four that start an orchestration.""" + starter = _make_starter() + container = _make_counter_container_starting_at() + docs = [_turn(tenant_id="acme"), _turn(tenant_id="globex"), _turn(tenant_id="acme"), _turn(tenant_id="globex")] + + asyncio.run(process_changefeed_batch(docs, starter, counter_container=container)) + + assert starter.start_new.await_count == 0 + for tenant_id in ("acme", "globex"): + assert _counter(container, "thread:u1:t1", tenant_id=tenant_id)["count"] == 2 + assert _counter(container, "user:u1", tenant_id=tenant_id)["count"] == 2 + + +@patch.dict( + os.environ, + { + "THREAD_SUMMARY_EVERY_N": "4", + "FACT_EXTRACTION_EVERY_N": "0", + "EPISODE_EVAL_EVERY_N": "0", + "USER_SUMMARY_EVERY_N": "0", + }, + clear=False, +) +def test_each_tenant_that_crosses_a_threshold_starts_its_own_orchestration(): + starter = _make_starter() + container = _make_counter_container_starting_at() + docs = [_turn(tenant_id="acme") for _ in range(4)] + [_turn(tenant_id="globex") for _ in range(4)] + + asyncio.run(process_changefeed_batch(docs, starter, counter_container=container)) + + started = {c.kwargs["instance_id"]: c.kwargs["client_input"] for c in starter.start_new.await_args_list} + assert started == { + _thread_instance_id("thread_summary", 4, tenant_id="acme"): { + "tenant_id": "acme", + "user_id": "u1", + "thread_id": "t1", + "count": 4, + }, + _thread_instance_id("thread_summary", 4, tenant_id="globex"): { + "tenant_id": "globex", + "user_id": "u1", + "thread_id": "t1", + "count": 4, + }, + } + + +@patch.dict( + os.environ, + { + "THREAD_SUMMARY_EVERY_N": "0", + "FACT_EXTRACTION_EVERY_N": "0", + "EPISODE_EVAL_EVERY_N": "0", + "USER_SUMMARY_EVERY_N": "2", + }, + clear=False, +) +def test_user_summary_thread_ids_are_collected_per_tenant(): + starter = _make_starter() + container = _make_counter_container_starting_at() + docs = [ + _turn(tenant_id="acme", thread_id="t1"), + _turn(tenant_id="globex", thread_id="t9"), + _turn(tenant_id="acme", thread_id="t2"), + _turn(tenant_id="globex", thread_id="t9"), + ] + + asyncio.run(process_changefeed_batch(docs, starter, counter_container=container)) + + started = {c.kwargs["instance_id"]: c.kwargs["client_input"] for c in starter.start_new.await_args_list} + assert started == { + _user_instance_id(2, tenant_id="acme"): { + "tenant_id": "acme", + "user_id": "u1", + "count": 2, + "thread_ids": ["t1", "t2"], + }, + _user_instance_id(2, tenant_id="globex"): { + "tenant_id": "globex", + "user_id": "u1", + "count": 2, + "thread_ids": ["t9"], + }, + } + + +@patch.dict( + os.environ, + { + "THREAD_SUMMARY_EVERY_N": "100", + "FACT_EXTRACTION_EVERY_N": "0", + "EPISODE_EVAL_EVERY_N": "0", + "USER_SUMMARY_EVERY_N": "100", + }, + clear=False, +) +def test_counters_live_in_the_owner_partition_and_carry_the_tenant(): + starter = _make_starter() + container = _make_counter_container_starting_at() + + asyncio.run( + process_changefeed_batch([_turn(thread_id="t1"), _turn(thread_id="t2")], starter, counter_container=container) + ) + + assert {tuple(call.kwargs["partition_key"]) for call in container.read_item.await_args_list} == {(TENANT, "u1")} + thread_counter = _counter(container, "thread:u1:t1") + user_counter = _counter(container, "user:u1") + assert (thread_counter["tenant_id"], thread_counter["user_id"], thread_counter["thread_id"]) == (TENANT, "u1", "t1") + assert (user_counter["tenant_id"], user_counter["user_id"], user_counter["thread_id"]) == ( + TENANT, + "u1", + "__counters__", + ) + assert set(container._state) == { + (TENANT, "u1", "thread:u1:t1"), + (TENANT, "u1", "thread:u1:t2"), + (TENANT, "u1", "user:u1"), + } + + # --------------------------------------------------------------------------- # LSN replay protection # --------------------------------------------------------------------------- @@ -551,7 +900,7 @@ def test_lsn_replay_does_not_double_increment(): asyncio.run(process_changefeed_batch(docs, starter, counter_container=container)) # Layer 1 (LSN replay dedup): the counter must NOT double-increment. - assert container._state["thread:u1:t1"]["count"] == 4 + assert _counter(container, "thread:u1:t1")["count"] == 4 # Layer 2 (deterministic instance ID): on replay the counter helper still # reports the same ``(old, new)`` it returned the first time, so the @@ -560,7 +909,37 @@ def test_lsn_replay_does_not_double_increment(): # ``start_new`` server-side. We assert the determinism here. summary_starts = [c for c in starter.start_new.await_args_list if c.args[0] == "ThreadSummaryOrchestrator"] assert len(summary_starts) == 2 # same id sent twice - durable dedups - assert all(c.kwargs["instance_id"] == "thread_summary:u1:t1:4" for c in summary_starts) + assert all(c.kwargs["instance_id"] == _thread_instance_id("thread_summary", 4) for c in summary_starts) + + +@patch.dict( + os.environ, + { + "THREAD_SUMMARY_EVERY_N": "100", + "FACT_EXTRACTION_EVERY_N": "0", + "EPISODE_EVAL_EVERY_N": "0", + "USER_SUMMARY_EVERY_N": "100", + }, + clear=False, +) +def test_lsns_are_tracked_per_tenant_and_a_replay_counts_nothing_twice(): + """One batch can mix tenants; each tenant's counters record only the LSNs of its own turns.""" + starter = _make_starter() + container = _make_counter_container_starting_at() + docs = [ + _turn(tenant_id="acme", lsn=10), + _turn(tenant_id="globex", lsn=50), + _turn(tenant_id="acme", lsn=11), + ] + + asyncio.run(process_changefeed_batch(docs, starter, counter_container=container)) + asyncio.run(process_changefeed_batch(docs, starter, counter_container=container)) + + for counter_id in ("thread:u1:t1", "user:u1"): + acme = _counter(container, counter_id, tenant_id="acme") + globex = _counter(container, counter_id, tenant_id="globex") + assert (acme["count"], acme["last_batch_lsn"]) == (2, 11) + assert (globex["count"], globex["last_batch_lsn"]) == (1, 50) # --------------------------------------------------------------------------- @@ -622,7 +1001,7 @@ def test_runs_normally_when_owner_durable(): asyncio.run(process_changefeed_batch(docs, starter, counter_container=container)) # Counter was written. - assert container._state["thread:u1:t1"]["count"] == 2 + assert _counter(container, "thread:u1:t1")["count"] == 2 # Threshold (2) crossed - orchestrator started. summary_starts = [c for c in starter.start_new.await_args_list if c.args[0] == "ThreadSummaryOrchestrator"] assert len(summary_starts) == 1 @@ -704,7 +1083,7 @@ def test_reconcile_flag_set_only_when_n_facts_times_n_dedup_threshold_crosses(): # advancing the watermark to the processed count (4) after batch 1. from shared.counters import advance_extract_watermark, thread_counter_id - asyncio.run(advance_extract_watermark(container, thread_counter_id("u1", "t1"), "u1", "t1", 4)) + asyncio.run(advance_extract_watermark(container, TENANT, thread_counter_id("u1", "t1"), "u1", 4)) # Next batch: counter 4 -> 5. Reconcile threshold crossed, so the same # extract dispatch carries reconcile=True, and recent_k = 5 - watermark(4) = 1. @@ -714,6 +1093,7 @@ def test_reconcile_flag_set_only_when_n_facts_times_n_dedup_threshold_crosses(): assert len(extract_calls) == 1 payload = _extract_payload(extract_calls[0]) assert payload.get("reconcile") is True + assert payload.get("tenant_id") == TENANT assert payload.get("user_id") == "u1" assert payload.get("recent_k") == 1 @@ -721,21 +1101,54 @@ def test_reconcile_flag_set_only_when_n_facts_times_n_dedup_threshold_crosses(): def test_advance_extract_watermark_is_monotonic(): """A later, out-of-order run must not regress the extract watermark below a higher value a concurrent run already wrote (that would re-extract turns).""" - from shared.counters import advance_extract_watermark, thread_counter_id + from shared.counters import advance_extract_watermark, increment_counter_by, thread_counter_id container = _make_counter_container_starting_at() cid = thread_counter_id("u1", "t1") + asyncio.run(increment_counter_by(container, TENANT, cid, "u1", "t1", 12)) - asyncio.run(advance_extract_watermark(container, cid, "u1", "t1", 8)) - assert container._state[cid]["last_extract_count"] == 8 + asyncio.run(advance_extract_watermark(container, TENANT, cid, "u1", 8)) + assert _counter(container, cid)["last_extract_count"] == 8 # An out-of-order run with a lower count is a no-op (Cosmos 412, swallowed). - asyncio.run(advance_extract_watermark(container, cid, "u1", "t1", 4)) - assert container._state[cid]["last_extract_count"] == 8 + asyncio.run(advance_extract_watermark(container, TENANT, cid, "u1", 4)) + assert _counter(container, cid)["last_extract_count"] == 8 # A higher count still advances. - asyncio.run(advance_extract_watermark(container, cid, "u1", "t1", 12)) - assert container._state[cid]["last_extract_count"] == 12 + asyncio.run(advance_extract_watermark(container, TENANT, cid, "u1", 12)) + assert _counter(container, cid)["last_extract_count"] == 12 + + +@patch.dict( + os.environ, + { + "THREAD_SUMMARY_EVERY_N": "0", + "FACT_EXTRACTION_EVERY_N": "1", + "EPISODE_EVAL_EVERY_N": "0", + "USER_SUMMARY_EVERY_N": "0", + "DEDUP_EVERY_N": "0", + }, + clear=False, +) +def test_the_extract_watermark_is_read_from_the_tenant_of_the_turns(): + from shared.counters import advance_extract_watermark, thread_counter_id + + starter = _make_starter() + container = _make_counter_container_starting_at() + first = [_turn(tenant_id=tenant_id) for tenant_id in ("acme", "globex") for _ in range(4)] + asyncio.run(process_changefeed_batch(first, starter, counter_container=container)) + # Only acme's extraction has gone through its 4 turns. + asyncio.run(advance_extract_watermark(container, "acme", thread_counter_id("u1", "t1"), "u1", 4)) + + starter.start_new.reset_mock() + asyncio.run( + process_changefeed_batch( + [_turn(tenant_id="acme"), _turn(tenant_id="globex")], starter, counter_container=container + ) + ) + + payloads = [_extract_payload(c) for c in starter.start_new.await_args_list] + assert {payload["tenant_id"]: payload["recent_k"] for payload in payloads} == {"acme": 1, "globex": 5} @patch.dict( diff --git a/tests/unit/function_app/test_counters.py b/tests/unit/function_app/test_counters.py index 1efc96e..204e2bf 100644 --- a/tests/unit/function_app/test_counters.py +++ b/tests/unit/function_app/test_counters.py @@ -4,6 +4,7 @@ * ``crosses_threshold`` boundary semantics (the truth table from the spec). * ``increment_counter_by`` first-write path, happy path, ETag retry path, ETag exhaustion (skip), and LSN-based replay detection. +* The counter key: every counter lives in the owner's partition ``[tenant_id, user_id]`` and carries ``tenant_id``. The Cosmos container is mocked - no Azure dependency is required at test time. """ @@ -16,12 +17,16 @@ import pytest from azure.cosmos.exceptions import CosmosHttpResponseError, CosmosResourceNotFoundError from shared.counters import ( + advance_extract_watermark, crosses_threshold, increment_counter_by, + read_extract_watermark, thread_counter_id, user_counter_id, ) +TENANT = "acme" + # --------------------------------------------------------------------------- # crosses_threshold # --------------------------------------------------------------------------- @@ -109,7 +114,7 @@ def test_creates_doc_when_missing(self): container = _make_container() container.read_item.side_effect = CosmosResourceNotFoundError(message="404") - old, new = asyncio.run(increment_counter_by(container, "thread:u1:t1", "u1", "t1", 3)) + old, new = asyncio.run(increment_counter_by(container, TENANT, "thread:u1:t1", "u1", "t1", 3)) assert (old, new) == (0, 3) assert container.create_item.await_count == 1 @@ -130,7 +135,7 @@ def test_create_conflict_then_succeeds(self): ] container.create_item.side_effect = [_http_error(409)] - old, new = asyncio.run(increment_counter_by(container, "thread:u1:t1", "u1", "t1", 2)) + old, new = asyncio.run(increment_counter_by(container, TENANT, "thread:u1:t1", "u1", "t1", 2)) assert (old, new) == (3, 5) assert container.create_item.await_count == 1 @@ -154,6 +159,7 @@ def test_happy_path_upserts(self): old, new = asyncio.run( increment_counter_by( container, + TENANT, "thread:u1:t1", "u1", "t1", @@ -178,7 +184,7 @@ def test_etag_conflict_retries_then_succeeds(self): ] container.upsert_item.side_effect = [_http_error(412), None] - old, new = asyncio.run(increment_counter_by(container, "thread:u1:t1", "u1", "t1", 2)) + old, new = asyncio.run(increment_counter_by(container, TENANT, "thread:u1:t1", "u1", "t1", 2)) # We restart from the *latest* read - count went 7 → 9. assert (old, new) == (7, 9) @@ -202,7 +208,7 @@ def test_etag_conflict_exhausted_raises(self): container.upsert_item.side_effect = _http_error(412) with pytest.raises(CosmosHttpResponseError) as exc_info: - asyncio.run(increment_counter_by(container, "thread:u1:t1", "u1", "t1", 1)) + asyncio.run(increment_counter_by(container, TENANT, "thread:u1:t1", "u1", "t1", 1)) assert exc_info.value.status_code == 412 assert container.upsert_item.await_count == 3 # MAX_RETRIES @@ -223,6 +229,7 @@ def test_lsn_replay_returns_cached_without_writing(self): old, new = asyncio.run( increment_counter_by( container, + TENANT, "thread:u1:t1", "u1", "t1", @@ -249,6 +256,7 @@ def test_different_lsn_does_not_trigger_replay(self): old, new = asyncio.run( increment_counter_by( container, + TENANT, "thread:u1:t1", "u1", "t1", @@ -279,6 +287,7 @@ def test_out_of_order_replay_is_noop(self): old, new = asyncio.run( increment_counter_by( container, + TENANT, "thread:u1:t1", "u1", "t1", @@ -290,3 +299,55 @@ def test_out_of_order_replay_is_noop(self): assert (old, new) == (10, 10) assert container.upsert_item.await_count == 0 assert container.create_item.await_count == 0 + + +# --------------------------------------------------------------------------- +# The counter key: the owner's partition [tenant_id, user_id]; thread_id is a plain field +# --------------------------------------------------------------------------- + + +class TestCounterKey: + def test_a_thread_counter_is_read_and_created_in_the_owner_partition(self): + container = _make_container() + container.read_item.side_effect = CosmosResourceNotFoundError(message="404") + + asyncio.run(increment_counter_by(container, TENANT, "thread:u1:t1", "u1", "t1", 3)) + + assert container.read_item.await_args.kwargs == {"item": "thread:u1:t1", "partition_key": [TENANT, "u1"]} + body = container.create_item.await_args.kwargs["body"] + assert (body["tenant_id"], body["user_id"], body["thread_id"]) == (TENANT, "u1", "t1") + + def test_a_user_counter_shares_the_partition_and_keeps_its_marker_thread_id(self): + container = _make_container() + container.read_item.side_effect = CosmosResourceNotFoundError(message="404") + + asyncio.run(increment_counter_by(container, TENANT, user_counter_id("u1"), "u1", "__counters__", 3)) + + assert container.read_item.await_args.kwargs["partition_key"] == [TENANT, "u1"] + body = container.create_item.await_args.kwargs["body"] + assert (body["id"], body["tenant_id"], body["user_id"], body["thread_id"]) == ( + "user:u1", + TENANT, + "u1", + "__counters__", + ) + + def test_an_increment_keeps_the_tenant_on_the_upserted_counter(self): + container = _make_container() + container.read_item.return_value = {"id": "thread:u1:t1", "count": 5, "_etag": "etag-A"} + + asyncio.run(increment_counter_by(container, TENANT, "thread:u1:t1", "u1", "t1", 2)) + + assert container.read_item.await_args.kwargs["partition_key"] == [TENANT, "u1"] + assert container.upsert_item.await_args.kwargs["body"]["tenant_id"] == TENANT + + def test_the_extract_watermark_is_read_and_advanced_in_the_owner_partition(self): + container = _make_container() + container.read_item.return_value = {"id": "thread:u1:t1", "last_extract_count": 6} + container.patch_item = AsyncMock() + + assert asyncio.run(read_extract_watermark(container, TENANT, "thread:u1:t1", "u1")) == 6 + asyncio.run(advance_extract_watermark(container, TENANT, "thread:u1:t1", "u1", 8)) + + assert container.read_item.await_args.kwargs["partition_key"] == [TENANT, "u1"] + assert container.patch_item.await_args.kwargs["partition_key"] == [TENANT, "u1"] diff --git a/tests/unit/function_app/test_error_redaction.py b/tests/unit/function_app/test_error_redaction.py index b9c150d..60fe185 100644 --- a/tests/unit/function_app/test_error_redaction.py +++ b/tests/unit/function_app/test_error_redaction.py @@ -192,9 +192,9 @@ def _run(orchestrator, context, activities): def test_a_failed_summary_step_keeps_its_error_text_out_of_the_history_and_the_log(monkeypatch, caplog): pipeline = MagicMock() pipeline.generate_thread_summary_durable.side_effect = LLMError(f"LLM returned invalid JSON (preview={SECRET!r})") - monkeypatch.setattr(ts_mod, "get_pipeline", lambda: pipeline) + monkeypatch.setattr(ts_mod, "get_pipeline", lambda tenant_id: pipeline) monkeypatch.setattr(ts_mod, "default_retry_options", lambda: "retry") - context = _Context({"user_id": "alice", "thread_id": "t1"}) + context = _Context({"tenant_id": "acme", "user_id": "alice", "thread_id": "t1"}) activities = {"ts_Extract": ts_mod.ts_Extract, "ts_PersistSummary": ts_mod.ts_PersistSummary} with caplog.at_level(logging.DEBUG), pytest.raises(ActivityFailedError) as failure: diff --git a/tests/unit/function_app/test_extract_episodes_orchestrator.py b/tests/unit/function_app/test_extract_episodes_orchestrator.py index abcbc7e..579e063 100644 --- a/tests/unit/function_app/test_extract_episodes_orchestrator.py +++ b/tests/unit/function_app/test_extract_episodes_orchestrator.py @@ -4,6 +4,7 @@ from unittest.mock import MagicMock, patch +import pytest from orchestrators import extract_episodes as ee_mod @@ -46,25 +47,34 @@ def _orchestrator(self): return _user_function(ee_mod.ExtractEpisodesOrchestrator) @patch.object(ee_mod, "default_retry_options", return_value=MagicMock(name="retry")) - def test_calls_activity_once_with_user_and_thread_and_returns_result(self, _retry): - ctx = _make_context({"user_id": "u1", "thread_id": "t1"}) + def test_calls_activity_once_with_tenant_user_and_thread_and_returns_result(self, _retry): + ctx = _make_context({"tenant_id": "acme", "user_id": "u1", "thread_id": "t1"}) gen = self._orchestrator()(ctx) result, _ = _drive(gen, [{"episodes": 2}]) assert [call[0] for call in ctx._yielded_calls] == ["ee_ExtractEpisodes"] - assert ctx._yielded_calls[0][2] == {"user_id": "u1", "thread_id": "t1"} + assert ctx._yielded_calls[0][2] == {"tenant_id": "acme", "user_id": "u1", "thread_id": "t1"} assert result == {"episodes": 2} + @pytest.mark.parametrize("missing", ["tenant_id", "user_id", "thread_id"]) + def test_missing_tenant_user_or_thread_id_raises(self, missing): + payload = {"tenant_id": "acme", "user_id": "u1", "thread_id": "t1"} + del payload[missing] + with patch.object(ee_mod, "default_retry_options", return_value=MagicMock()): + with pytest.raises(KeyError): + next(self._orchestrator()(_make_context(payload))) + @patch.object(ee_mod, "get_pipeline") -def test_activity_calls_pipeline_and_returns_slim_payload(mock_get_pipeline): +def test_activity_calls_the_tenants_pipeline_and_returns_slim_payload(mock_get_pipeline): pipeline = MagicMock() pipeline.extract_episodes.return_value = {"episodes": 3} mock_get_pipeline.return_value = pipeline - result = ee_mod.ee_ExtractEpisodes({"user_id": "u1", "thread_id": "t1"}) + result = ee_mod.ee_ExtractEpisodes({"tenant_id": "acme", "user_id": "u1", "thread_id": "t1"}) + mock_get_pipeline.assert_called_once_with("acme") pipeline.extract_episodes.assert_called_once_with( user_id="u1", thread_id="t1", diff --git a/tests/unit/function_app/test_failure_logs.py b/tests/unit/function_app/test_failure_logs.py index 8f213a7..74dca75 100644 --- a/tests/unit/function_app/test_failure_logs.py +++ b/tests/unit/function_app/test_failure_logs.py @@ -46,9 +46,9 @@ async def test_watermark_failures_log_the_status_not_the_text(logs) -> None: side_effect=[_failure(503), CosmosHttpResponseError(status_code=500, message=MEMORY)] ) - assert await read_extract_watermark(container, "thread:u1:t1", "u1", "t1") is None - await advance_extract_watermark(container, "thread:u1:t1", "u1", "t1", 4) - await advance_extract_watermark(container, "thread:u1:t1", "u1", "t1", 4) + assert await read_extract_watermark(container, "acme", "thread:u1:t1", "u1") is None + await advance_extract_watermark(container, "acme", "thread:u1:t1", "u1", 4) + await advance_extract_watermark(container, "acme", "thread:u1:t1", "u1", 4) expected = ( "advance_extract_watermark failed counter_id=thread:u1:t1: azure.cosmos.CosmosHttpResponseError(status=500) at " @@ -84,7 +84,7 @@ def _user_function(builder): def test_a_failed_sub_orchestration_logs_its_type_not_its_text(logs) -> None: - context = _Context({"user_id": "u1", "thread_id": "t1", "reconcile": True}) + context = _Context({"tenant_id": "acme", "user_id": "u1", "thread_id": "t1", "reconcile": True}) with patch.object(em, "default_retry_options", return_value=MagicMock()): generator = _user_function(em.ExtractMemoriesOrchestrator)(context) @@ -99,7 +99,9 @@ def test_a_failed_sub_orchestration_logs_its_type_not_its_text(logs) -> None: record for record in logs.records if record.name == em.logger.name and record.levelno >= logging.WARNING ] assert record.exc_info is None - assert record.getMessage().startswith("SynthesizeProceduralOrchestrator failed user=u1 thread=t1: RuntimeError at ") + assert record.getMessage().startswith( + "SynthesizeProceduralOrchestrator failed tenant=acme user=u1 thread=t1: RuntimeError at " + ) _assert_no_text(logs) diff --git a/tests/unit/function_app/test_instance_ids.py b/tests/unit/function_app/test_instance_ids.py new file mode 100644 index 0000000..96cdb10 --- /dev/null +++ b/tests/unit/function_app/test_instance_ids.py @@ -0,0 +1,98 @@ +"""Unit tests for ``function_app/shared/instance_ids.py``. + +An orchestration instance id is ``{kind}:{digest}`` plus ``:{count}``. Durable Functions takes 1-100 characters without +``/``, ``\\``, ``#``, ``?`` or control characters, and tenant, user and thread ids are free text, so none of them +appears in the id. +""" + +from __future__ import annotations + +import re +import unicodedata + +import pytest +from shared.instance_ids import orchestration_instance_id + +KINDS = ("thread_summary", "extract", "episode", "user_summary", "procedural") + + +def _is_allowed_instance_id(instance_id: str) -> bool: + """Durable Functions' rules for an instance id.""" + return ( + 1 <= len(instance_id) <= 100 + and not instance_id.startswith("@") + and not any(character in "/\\#?" for character in instance_id) + and not any(unicodedata.category(character) == "Cc" for character in instance_id) + ) + + +def test_the_id_is_the_kind_a_hash_of_the_owner_and_the_count(): + """The digest is the first 32 hex digits of the SHA-256 of the parts joined with the unit separator.""" + assert ( + orchestration_instance_id("extract", "acme", "u1", "t1", count=4) + == "extract:bdddaa37089972c2babf1b5dda603e63:4" + ) + assert orchestration_instance_id("user_summary", "acme", "u1", count=20) == ( + "user_summary:16694a27e83b5de5685ed29bf499bc68:20" + ) + + +def test_the_count_is_an_optional_suffix_and_zero_is_a_count(): + without = orchestration_instance_id("episode", "acme", "u1", "t1") + assert re.fullmatch(r"episode:[0-9a-f]{32}", without) + assert orchestration_instance_id("episode", "acme", "u1", "t1", count=0) == f"{without}:0" + + +def test_the_same_inputs_give_the_same_id(): + first = orchestration_instance_id("thread_summary", "acme", "u1", "t1", count=4) + second = orchestration_instance_id("thread_summary", "".join(["ac", "me"]), "u1", "t" + "1", count=4) + + assert first == second + + +def test_a_different_kind_tenant_user_thread_or_count_gives_a_different_id(): + ids = { + orchestration_instance_id("thread_summary", "acme", "u1", "t1", count=4), + orchestration_instance_id("extract", "acme", "u1", "t1", count=4), + orchestration_instance_id("thread_summary", "globex", "u1", "t1", count=4), + orchestration_instance_id("thread_summary", "acme", "u2", "t1", count=4), + orchestration_instance_id("thread_summary", "acme", "u1", "t2", count=4), + orchestration_instance_id("thread_summary", "acme", "u1", "t1", count=5), + } + + assert len(ids) == 6 + + +@pytest.mark.parametrize( + ("first", "second"), + [ + pytest.param(("a:b", "c", "d"), ("a", "b:c", "d"), id="thread-level-colon-between-tenant-and-user"), + pytest.param(("a", "b:c", "d"), ("a", "b", "c:d"), id="thread-level-colon-between-user-and-thread"), + pytest.param(("a:b", "c"), ("a", "b:c"), id="user-level-colon-between-tenant-and-user"), + pytest.param(("ab", "c", "d"), ("a", "bc", "d"), id="thread-level-boundary-between-tenant-and-user"), + pytest.param(("acme", "u1"), ("acme", "u1", ""), id="user-level-and-an-empty-thread"), + ], +) +def test_a_colon_or_a_moved_boundary_cannot_make_two_owners_collide(first, second): + first_id = orchestration_instance_id("extract", *first, count=1) + second_id = orchestration_instance_id("extract", *second, count=1) + + assert first_id != second_id + + +@pytest.mark.parametrize("kind", KINDS) +def test_the_worst_case_stays_within_the_limit_and_the_allowed_characters(kind): + """Tenant, user and thread of 200 characters and a 10-digit count: the id is as long as for one-character ids.""" + longest = orchestration_instance_id(kind, "t" * 200, "u" * 200, "h" * 200, count=9_999_999_999) + shortest = orchestration_instance_id(kind, "t", "u", "h", count=1_000_000_000) + + assert len(longest) == len(shortest) == len(kind) + 1 + 32 + 1 + 10 + assert _is_allowed_instance_id(longest) + + +@pytest.mark.parametrize("user_id", ["a/b", "a\\b", "a#b", "a?b", "a\nb", "a\x1fb", "@user", "ünï©ødé", "a b"]) +def test_characters_a_user_id_may_hold_never_reach_the_id(user_id): + instance_id = orchestration_instance_id("episode", "acme", user_id, "t1", count=7) + + assert re.fullmatch(r"episode:[0-9a-f]{32}:7", instance_id) + assert _is_allowed_instance_id(instance_id) diff --git a/tests/unit/function_app/test_orchestrators.py b/tests/unit/function_app/test_orchestrators.py index 857baca..efabc39 100644 --- a/tests/unit/function_app/test_orchestrators.py +++ b/tests/unit/function_app/test_orchestrators.py @@ -13,12 +13,17 @@ from unittest.mock import AsyncMock, MagicMock, call, patch import pytest +from orchestrators import extract_episodes as ee_mod from orchestrators import extract_memories as em_mod +from orchestrators import synthesize_procedural as sp_mod from orchestrators import thread_summary as ts_mod from orchestrators import user_summary as us_mod +from shared.instance_ids import orchestration_instance_id from azure.cosmos.agent_memory.exceptions import NoSourceMemoriesError +TENANT = "acme" + # --------------------------------------------------------------------------- # Helpers # --------------------------------------------------------------------------- @@ -44,6 +49,7 @@ def _make_context(payload): yielded_calls: list[tuple] = [] yielded_sub_orchestrators: list[tuple] = [] + sub_instance_ids: list = [] def call_activity_with_retry(name, retry, activity_payload): yielded_calls.append((name, retry, activity_payload)) @@ -51,14 +57,16 @@ def call_activity_with_retry(name, retry, activity_payload): # this and feeds the next pre-canned activity result back in. return ("__call__", name, activity_payload) - def call_sub_orchestrator_with_retry(name, retry, sub_payload, *_args, **_kwargs): + def call_sub_orchestrator_with_retry(name, retry, sub_payload, *_args, **kwargs): yielded_sub_orchestrators.append((name, retry, sub_payload)) + sub_instance_ids.append(kwargs.get("instance_id")) return ("__sub__", name, sub_payload) ctx.call_activity_with_retry.side_effect = call_activity_with_retry ctx.call_sub_orchestrator_with_retry.side_effect = call_sub_orchestrator_with_retry ctx._yielded_calls = yielded_calls ctx._yielded_sub_orchestrators = yielded_sub_orchestrators + ctx._sub_instance_ids = sub_instance_ids return ctx @@ -138,7 +146,7 @@ def _orchestrator(self): @patch.object(ts_mod, "default_retry_options", return_value=MagicMock(name="retry")) def test_happy_path_calls_two_activities_in_order(self, _retry): - ctx = _make_context({"user_id": "u1", "thread_id": "t1"}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u1", "thread_id": "t1"}) gen = self._orchestrator()(ctx) result, _ = _drive( gen, @@ -155,19 +163,21 @@ def test_happy_path_calls_two_activities_in_order(self, _retry): assert result == {"persisted": True, "summary_id": "sum-123"} @patch.object(ts_mod, "default_retry_options", return_value=MagicMock()) - def test_passes_user_and_thread_ids_to_each_activity(self, _retry): - ctx = _make_context({"user_id": "alice", "thread_id": "T-9"}) + def test_passes_tenant_user_and_thread_ids_to_each_activity(self, _retry): + ctx = _make_context({"tenant_id": TENANT, "user_id": "alice", "thread_id": "T-9"}) gen = self._orchestrator()(ctx) _drive(gen, [{"id": "s"}, {}]) for _name, _retry_arg, payload in ctx._yielded_calls: + assert payload["tenant_id"] == TENANT assert payload["user_id"] == "alice" # Specific shape checks summarize_payload = ctx._yielded_calls[0][2] persist_payload = ctx._yielded_calls[1][2] - assert summarize_payload == {"user_id": "alice", "thread_id": "T-9", "limit": 20} + assert summarize_payload == {"tenant_id": TENANT, "user_id": "alice", "thread_id": "T-9", "limit": 20} assert persist_payload == { + "tenant_id": TENANT, "user_id": "alice", "thread_id": "T-9", "summary": {"id": "s"}, @@ -175,7 +185,7 @@ def test_passes_user_and_thread_ids_to_each_activity(self, _retry): @patch.object(ts_mod, "default_retry_options", return_value=MagicMock()) def test_summary_id_returned(self, _retry): - ctx = _make_context({"user_id": "u", "thread_id": "t"}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u", "thread_id": "t"}) gen = self._orchestrator()(ctx) result, _ = _drive(gen, [{"id": "s1"}, {"id": "s1"}]) @@ -184,23 +194,26 @@ def test_summary_id_returned(self, _retry): @patch.object(ts_mod, "default_retry_options", return_value=MagicMock()) def test_non_dict_summary_yields_none_summary_id(self, _retry): - ctx = _make_context({"user_id": "u", "thread_id": "t"}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u", "thread_id": "t"}) gen = self._orchestrator()(ctx) result, _ = _drive(gen, ["not-a-dict", {}]) assert result["summary_id"] is None @patch.object(ts_mod, "default_retry_options", return_value=MagicMock()) def test_activity_failure_propagates(self, _retry): - ctx = _make_context({"user_id": "u", "thread_id": "t"}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u", "thread_id": "t"}) gen = self._orchestrator()(ctx) # Yield first; throw exception into the generator at the next yield. next(gen) with pytest.raises(RuntimeError, match="boom"): gen.throw(RuntimeError("boom")) - def test_missing_user_id_raises(self): + @pytest.mark.parametrize("missing", ["tenant_id", "user_id"]) + def test_missing_tenant_or_user_id_raises(self, missing): with patch.object(ts_mod, "default_retry_options", return_value=MagicMock()): - ctx = _make_context({"thread_id": "t"}) + payload = {"tenant_id": TENANT, "user_id": "u", "thread_id": "t"} + del payload[missing] + ctx = _make_context(payload) gen = self._orchestrator()(ctx) with pytest.raises(KeyError): next(gen) @@ -208,7 +221,7 @@ def test_missing_user_id_raises(self): @patch.object(ts_mod, "default_retry_options", return_value=MagicMock()) def test_uses_max_batch_size_from_env(self, _retry, monkeypatch): monkeypatch.setenv("MAX_BATCH_SIZE", "7") - ctx = _make_context({"user_id": "u", "thread_id": "t"}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u", "thread_id": "t"}) gen = self._orchestrator()(ctx) _drive(gen, [{"id": "s"}, {}]) assert ctx._yielded_calls[0][2]["limit"] == 7 @@ -225,7 +238,7 @@ def _orchestrator(self): @patch.object(em_mod, "default_retry_options", return_value=MagicMock()) def test_extract_only_when_reconcile_flag_absent(self, _retry): - ctx = _make_context({"user_id": "u1", "thread_id": "t1"}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u1", "thread_id": "t1"}) gen = self._orchestrator()(ctx) result, _ = _drive( gen, @@ -241,6 +254,7 @@ def test_extract_only_when_reconcile_flag_absent(self, _retry): assert [c[0] for c in ctx._yielded_calls] == ["em_Extract", "em_Persist"] assert ctx._yielded_calls[1][2] == { + "tenant_id": TENANT, "user_id": "u1", "extracted": {"facts": [{"id": "f1"}], "episodic": [], "updates": []}, } @@ -250,7 +264,7 @@ def test_extract_only_when_reconcile_flag_absent(self, _retry): @patch.object(em_mod, "default_retry_options", return_value=MagicMock()) def test_chains_reconcile_when_flag_true(self, _retry): - ctx = _make_context({"user_id": "u1", "thread_id": "t1", "reconcile": True}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u1", "thread_id": "t1", "reconcile": True}) gen = self._orchestrator()(ctx) result, _ = _drive( gen, @@ -267,11 +281,11 @@ def test_chains_reconcile_when_flag_true(self, _retry): names = [c[0] for c in ctx._yielded_calls] assert names == ["em_Extract", "em_Persist", "em_ReconcileMemories"] - assert ctx._yielded_calls[2][2] == {"user_id": "u1"} + assert ctx._yielded_calls[2][2] == {"tenant_id": TENANT, "user_id": "u1"} assert [s[0] for s in ctx._yielded_sub_orchestrators] == [ "SynthesizeProceduralOrchestrator", ] - assert ctx._yielded_sub_orchestrators[0][2] == {"user_id": "u1", "force": False} + assert ctx._yielded_sub_orchestrators[0][2] == {"tenant_id": TENANT, "user_id": "u1", "force": False} assert result["reconciled"] == { "fact": {"kept": 0, "merged": 1, "conflicts": 0}, "episodic": {"kept": 1, "merged": 0, "conflicts": 0}, @@ -281,7 +295,7 @@ def test_chains_reconcile_when_flag_true(self, _retry): @patch.object(em_mod, "default_retry_options", return_value=MagicMock()) def test_procedural_failure_is_swallowed(self, _retry): """Procedural synthesis is best-effort; failure must not fail the orchestrator.""" - ctx = _make_context({"user_id": "u1", "thread_id": "t1", "reconcile": True}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u1", "thread_id": "t1", "reconcile": True}) def boom_after_sub(name, retry, sub_payload, *args, **kwargs): ctx._yielded_sub_orchestrators.append((name, retry, sub_payload)) @@ -320,7 +334,7 @@ def boom_after_sub(name, retry, sub_payload, *args, **kwargs): @patch.object(em_mod, "default_retry_options", return_value=MagicMock()) def test_procedural_not_called_when_reconcile_skipped(self, _retry): - ctx = _make_context({"user_id": "u1", "thread_id": "t1"}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u1", "thread_id": "t1"}) gen = self._orchestrator()(ctx) result, _ = _drive( gen, @@ -335,35 +349,35 @@ def test_procedural_not_called_when_reconcile_skipped(self, _retry): assert result["procedural"] is None @patch.object(em_mod, "default_retry_options", return_value=MagicMock()) - def test_extract_payload_carries_user_thread_without_recent_k_when_absent(self, _retry): - ctx = _make_context({"user_id": "u", "thread_id": "t"}) + def test_extract_payload_carries_tenant_user_thread_without_recent_k_when_absent(self, _retry): + ctx = _make_context({"tenant_id": TENANT, "user_id": "u", "thread_id": "t"}) gen = self._orchestrator()(ctx) _drive(gen, [{"facts": []}, {"fact_count": 0}]) extract_payload = ctx._yielded_calls[0][2] - assert extract_payload == {"user_id": "u", "thread_id": "t"} + assert extract_payload == {"tenant_id": TENANT, "user_id": "u", "thread_id": "t"} @patch.object(em_mod, "default_retry_options", return_value=MagicMock()) def test_extract_payload_carries_recent_k_when_provided(self, _retry): - ctx = _make_context({"user_id": "u", "thread_id": "t", "recent_k": 7}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u", "thread_id": "t", "recent_k": 7}) gen = self._orchestrator()(ctx) _drive(gen, [{"facts": []}, {"fact_count": 0}]) extract_payload = ctx._yielded_calls[0][2] - assert extract_payload == {"user_id": "u", "thread_id": "t", "recent_k": 7} + assert extract_payload == {"tenant_id": TENANT, "user_id": "u", "thread_id": "t", "recent_k": 7} @patch.object(em_mod, "default_retry_options", return_value=MagicMock()) def test_extract_output_flows_to_persist(self, _retry): extracted = {"facts": [{"id": "f1"}], "episodic": [], "updates": []} - ctx = _make_context({"user_id": "u", "thread_id": "t"}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u", "thread_id": "t"}) gen = self._orchestrator()(ctx) _drive(gen, [extracted, {"fact_count": 1}]) - assert ctx._yielded_calls[1][2] == {"user_id": "u", "extracted": extracted} + assert ctx._yielded_calls[1][2] == {"tenant_id": TENANT, "user_id": "u", "extracted": extracted} @patch.object(em_mod, "default_retry_options", return_value=MagicMock()) def test_activity_failure_propagates(self, _retry): - ctx = _make_context({"user_id": "u", "thread_id": "t"}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u", "thread_id": "t"}) gen = self._orchestrator()(ctx) next(gen) with pytest.raises(ValueError, match="kaboom"): @@ -371,25 +385,51 @@ def test_activity_failure_propagates(self, _retry): @patch.object(em_mod, "default_retry_options", return_value=MagicMock()) def test_advance_watermark_after_persist_when_count_present(self, _retry): - ctx = _make_context({"user_id": "u1", "thread_id": "t1", "count": 42}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u1", "thread_id": "t1", "count": 42}) gen = self._orchestrator()(ctx) _drive(gen, [{"facts": []}, {"fact_count": 0}, True]) names = [c[0] for c in ctx._yielded_calls] assert names == ["em_Extract", "em_Persist", "em_AdvanceExtractWatermark"] - assert ctx._yielded_calls[2][2] == {"user_id": "u1", "thread_id": "t1", "count": 42} + assert ctx._yielded_calls[2][2] == {"tenant_id": TENANT, "user_id": "u1", "thread_id": "t1", "count": 42} @patch.object(em_mod, "default_retry_options", return_value=MagicMock()) def test_no_watermark_advance_when_count_absent(self, _retry): - ctx = _make_context({"user_id": "u1", "thread_id": "t1"}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u1", "thread_id": "t1"}) gen = self._orchestrator()(ctx) _drive(gen, [{"facts": []}, {"fact_count": 0}]) names = [c[0] for c in ctx._yielded_calls] assert "em_AdvanceExtractWatermark" not in names - def test_missing_thread_id_raises(self): + @patch.object(em_mod, "default_retry_options", return_value=MagicMock()) + def test_the_procedural_sub_orchestration_id_hashes_the_tenant_user_and_thread_with_the_count(self, _retry): + """Two tenants can have the same user and thread, so the instance id hashes the tenant too.""" + instance_ids = [] + for tenant_id in ("acme", "globex"): + payload = {"tenant_id": tenant_id, "user_id": "u1", "thread_id": "t1", "count": 42, "reconcile": True} + ctx = _make_context(payload) + _drive(self._orchestrator()(ctx), [{"facts": []}, {"fact_count": 0}, True, {}, {"status": "unchanged"}]) + instance_ids += ctx._sub_instance_ids + + assert instance_ids == [ + orchestration_instance_id("procedural", "acme", "u1", "t1", count=42), + orchestration_instance_id("procedural", "globex", "u1", "t1", count=42), + ] + assert instance_ids[0] != instance_ids[1] + + @patch.object(em_mod, "default_retry_options", return_value=MagicMock()) + def test_the_procedural_sub_orchestration_gets_no_fixed_id_without_a_count(self, _retry): + ctx = _make_context({"tenant_id": TENANT, "user_id": "u1", "thread_id": "t1", "reconcile": True}) + _drive(self._orchestrator()(ctx), [{"facts": []}, {"fact_count": 0}, {}, {"status": "unchanged"}]) + + assert ctx._sub_instance_ids == [None] + + @pytest.mark.parametrize("missing", ["tenant_id", "user_id", "thread_id"]) + def test_missing_tenant_user_or_thread_id_raises(self, missing): with patch.object(em_mod, "default_retry_options", return_value=MagicMock()): - ctx = _make_context({"user_id": "u"}) + payload = {"tenant_id": TENANT, "user_id": "u", "thread_id": "t"} + del payload[missing] + ctx = _make_context(payload) gen = self._orchestrator()(ctx) with pytest.raises(KeyError): next(gen) @@ -406,7 +446,7 @@ def test_em_extract_uses_payload_recent_k(self): pipeline.extract_memories_durable.return_value = {"facts": [], "episodic": [], "updates": []} with patch.object(em_mod, "get_pipeline", return_value=pipeline): - result = em_mod.em_Extract({"user_id": "u1", "thread_id": "t1", "recent_k": 3}) + result = em_mod.em_Extract({"tenant_id": TENANT, "user_id": "u1", "thread_id": "t1", "recent_k": 3}) pipeline.extract_memories_durable.assert_called_once_with(user_id="u1", thread_id="t1", recent_k=3) assert result == {"facts": [], "episodic": [], "updates": []} @@ -416,7 +456,7 @@ def test_em_extract_falls_back_to_max_batch_size_when_recent_k_absent(self): pipeline.extract_memories_durable.return_value = {"facts": [], "episodic": [], "updates": []} with patch.object(em_mod, "get_pipeline", return_value=pipeline): - em_mod.em_Extract({"user_id": "u1", "thread_id": "t1"}) + em_mod.em_Extract({"tenant_id": TENANT, "user_id": "u1", "thread_id": "t1"}) pipeline.extract_memories_durable.assert_called_once_with(user_id="u1", thread_id="t1", recent_k=20) @@ -433,7 +473,7 @@ def test_em_reconcile_memories_reconciles_fact_and_episodic(self): patch.object(em_mod.config, "get_activity_time_budget_seconds", return_value=45), patch.object(em_mod.time, "monotonic", return_value=1000.0), ): - result = em_mod.em_ReconcileMemories({"user_id": "u1"}) + result = em_mod.em_ReconcileMemories({"tenant_id": TENANT, "user_id": "u1"}) # Both passes share one deadline: the activity's time budget from when it started. assert pipeline.reconcile_memories.call_args_list == [ @@ -454,7 +494,7 @@ def test_em_reconcile_memories_budget_comes_from_the_environment(self, monkeypat patch.object(em_mod, "get_pipeline", return_value=pipeline), patch.object(em_mod.time, "monotonic", return_value=10.0), ): - em_mod.em_ReconcileMemories({"user_id": "u1"}) + em_mod.em_ReconcileMemories({"tenant_id": TENANT, "user_id": "u1"}) assert {c.kwargs["deadline"] for c in pipeline.reconcile_memories.call_args_list} == {100.0} @@ -468,10 +508,12 @@ def test_em_advance_extract_watermark_stamps_counter(self): patch.object(cosmos_clients, "get_counter_container_async", new=AsyncMock(return_value=container)), patch.object(counters, "advance_extract_watermark", new=AsyncMock()) as advance, ): - result = asyncio.run(em_mod.em_AdvanceExtractWatermark({"user_id": "u1", "thread_id": "t1", "count": 9})) + result = asyncio.run( + em_mod.em_AdvanceExtractWatermark({"tenant_id": TENANT, "user_id": "u1", "thread_id": "t1", "count": 9}) + ) assert result is True - advance.assert_awaited_once_with(container, "thread:u1:t1", "u1", "t1", 9) + advance.assert_awaited_once_with(container, TENANT, "thread:u1:t1", "u1", 9) class TestUserSummaryOrchestrator: @@ -480,7 +522,7 @@ def _orchestrator(self): @patch.object(us_mod, "default_retry_options", return_value=MagicMock()) def test_happy_path_calls_two_activities_in_order(self, _retry): - ctx = _make_context({"user_id": "u1"}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u1"}) gen = self._orchestrator()(ctx) result, _ = _drive( gen, @@ -499,27 +541,28 @@ def test_happy_path_calls_two_activities_in_order(self, _retry): } @patch.object(us_mod, "default_retry_options", return_value=MagicMock()) - def test_payloads_only_carry_user_id_limit_and_thread_ids(self, _retry): - ctx = _make_context({"user_id": "alice"}) + def test_payloads_only_carry_tenant_user_id_limit_and_thread_ids(self, _retry): + ctx = _make_context({"tenant_id": TENANT, "user_id": "alice"}) gen = self._orchestrator()(ctx) _drive(gen, [{"id": "us"}, {}]) gen_payload = ctx._yielded_calls[0][2] persist_payload = ctx._yielded_calls[1][2] - assert gen_payload == {"user_id": "alice", "limit": 20, "thread_ids": None} - assert persist_payload == {"user_id": "alice", "user_summary": {"id": "us"}} + assert gen_payload == {"tenant_id": TENANT, "user_id": "alice", "limit": 20, "thread_ids": None} + assert persist_payload == {"tenant_id": TENANT, "user_id": "alice", "user_summary": {"id": "us"}} for payload in (gen_payload, persist_payload): assert "thread_id" not in payload @patch.object(us_mod, "default_retry_options", return_value=MagicMock()) def test_payload_passes_thread_ids_when_provided(self, _retry): - ctx = _make_context({"user_id": "alice", "thread_ids": ["t1", "t2"]}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "alice", "thread_ids": ["t1", "t2"]}) gen = self._orchestrator()(ctx) _drive(gen, [{"id": "us"}, {}]) gen_payload = ctx._yielded_calls[0][2] assert gen_payload == { + "tenant_id": TENANT, "user_id": "alice", "limit": 20, "thread_ids": ["t1", "t2"], @@ -527,7 +570,7 @@ def test_payload_passes_thread_ids_when_provided(self, _retry): @patch.object(us_mod, "default_retry_options", return_value=MagicMock()) def test_user_summary_id_returned(self, _retry): - ctx = _make_context({"user_id": "u"}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u"}) gen = self._orchestrator()(ctx) result, _ = _drive(gen, [{"id": "us"}, {"id": "us"}]) assert result["user_summary_id"] == "us" @@ -535,22 +578,23 @@ def test_user_summary_id_returned(self, _retry): @patch.object(us_mod, "default_retry_options", return_value=MagicMock()) def test_non_dict_user_summary_yields_none_id(self, _retry): - ctx = _make_context({"user_id": "u"}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u"}) gen = self._orchestrator()(ctx) result, _ = _drive(gen, [None, {}]) assert result["user_summary_id"] is None @patch.object(us_mod, "default_retry_options", return_value=MagicMock()) def test_activity_failure_propagates(self, _retry): - ctx = _make_context({"user_id": "u"}) + ctx = _make_context({"tenant_id": TENANT, "user_id": "u"}) gen = self._orchestrator()(ctx) next(gen) with pytest.raises(RuntimeError): gen.throw(RuntimeError("activity failed")) - def test_missing_user_id_raises(self): + @pytest.mark.parametrize("payload", [{"tenant_id": TENANT}, {"user_id": "u"}], ids=["no-user", "no-tenant"]) + def test_missing_tenant_or_user_id_raises(self, payload): with patch.object(us_mod, "default_retry_options", return_value=MagicMock()): - ctx = _make_context({}) + ctx = _make_context(payload) gen = self._orchestrator()(ctx) with pytest.raises(KeyError): next(gen) @@ -572,7 +616,7 @@ def test_waits_then_persists_when_memories_arrive_late(self, _retry, monkeypatch monkeypatch.setenv("USER_SUMMARY_WAIT_INTERVAL_SECONDS", "10") # Static clock: the budget never elapses, so the loop ends only when # memories finally land. - ctx = _TimerContext({"user_id": "u1"}, step_seconds=0) + ctx = _TimerContext({"tenant_id": TENANT, "user_id": "u1"}, step_seconds=0) gen = self._orchestrator()(ctx) result, _ = _drive( gen, @@ -599,7 +643,7 @@ def test_gives_up_after_budget_without_persisting(self, _retry, monkeypatch): monkeypatch.setenv("USER_SUMMARY_WAIT_SECONDS", "15") monkeypatch.setenv("USER_SUMMARY_WAIT_INTERVAL_SECONDS", "10") # Clock advances 10s per read, so the 15s budget elapses after one wait. - ctx = _TimerContext({"user_id": "u1"}, step_seconds=10) + ctx = _TimerContext({"tenant_id": TENANT, "user_id": "u1"}, step_seconds=10) gen = self._orchestrator()(ctx) result, _ = _drive( gen, @@ -615,7 +659,7 @@ def test_gives_up_after_budget_without_persisting(self, _retry, monkeypatch): @patch.object(us_mod, "default_retry_options", return_value=MagicMock()) def test_persists_immediately_when_memories_already_present(self, _retry, monkeypatch): monkeypatch.setenv("USER_SUMMARY_WAIT_SECONDS", "120") - ctx = _TimerContext({"user_id": "u1"}, step_seconds=0) + ctx = _TimerContext({"tenant_id": TENANT, "user_id": "u1"}, step_seconds=0) gen = self._orchestrator()(ctx) result, _ = _drive(gen, [{"id": "us"}, {"id": "us"}]) assert result == {"persisted": True, "user_summary_id": "us"} @@ -627,13 +671,77 @@ def test_returns_sentinel_when_no_source_memories(self): pipeline = MagicMock() pipeline.generate_user_summary_durable.side_effect = NoSourceMemoriesError("No memories found for user_id='u1'") with patch.object(us_mod, "get_pipeline", return_value=pipeline): - result = us_mod.us_Extract({"user_id": "u1", "limit": 20, "thread_ids": None}) + result = us_mod.us_Extract({"tenant_id": TENANT, "user_id": "u1", "limit": 20, "thread_ids": None}) assert result == {"status": "no_memories_yet"} def test_passes_through_summary_doc_when_memories_present(self): pipeline = MagicMock() pipeline.generate_user_summary_durable.return_value = {"id": "user_summary_u1", "type": "user_summary"} with patch.object(us_mod, "get_pipeline", return_value=pipeline): - result = us_mod.us_Extract({"user_id": "u1", "limit": 20, "thread_ids": ["t1"]}) + result = us_mod.us_Extract({"tenant_id": TENANT, "user_id": "u1", "limit": 20, "thread_ids": ["t1"]}) assert result == {"id": "user_summary_u1", "type": "user_summary"} pipeline.generate_user_summary_durable.assert_called_once_with(user_id="u1", recent_k=20, thread_ids=["t1"]) + + +# --------------------------------------------------------------------------- +# Tenants: every orchestration input and activity payload carries tenant_id +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + ("module", "orchestrator", "extra_input", "results", "payloads_sent"), + [ + pytest.param( + ts_mod, "ThreadSummaryOrchestrator", {"thread_id": "t1"}, [{"id": "s"}, {"id": "s"}], 2, id="thread-summary" + ), + pytest.param( + em_mod, + "ExtractMemoriesOrchestrator", + {"thread_id": "t1", "count": 4, "reconcile": True}, + [{"facts": []}, {"fact_count": 0}, True, {}, {"status": "unchanged"}], + 5, + id="extract-memories", + ), + pytest.param(ee_mod, "ExtractEpisodesOrchestrator", {"thread_id": "t1"}, [{"episodes": 1}], 1, id="episodes"), + pytest.param( + sp_mod, "SynthesizeProceduralOrchestrator", {}, [{"status": "unchanged"}], 1, id="synthesize-procedural" + ), + pytest.param(us_mod, "UserSummaryOrchestrator", {}, [{"id": "us"}, {"id": "us"}], 2, id="user-summary"), + ], +) +def test_every_activity_and_sub_orchestration_payload_carries_the_tenant( + module, orchestrator, extra_input, results, payloads_sent, monkeypatch +): + monkeypatch.setenv("PROCEDURAL_SYNTHESIS_AUTO", "true") + with patch.object(module, "default_retry_options", return_value=MagicMock()): + ctx = _make_context({"tenant_id": "globex", "user_id": "u1", **extra_input}) + _drive(_user_function(getattr(module, orchestrator))(ctx), results) + + sent = [payload for _, _, payload in ctx._yielded_calls + ctx._yielded_sub_orchestrators] + assert len(sent) == payloads_sent + assert all(payload["tenant_id"] == "globex" for payload in sent) + + +_PIPELINE_ACTIVITIES = [ + pytest.param(ts_mod.ts_Extract, ts_mod, {"thread_id": "t1", "limit": 5}, id="ts_Extract"), + pytest.param(ts_mod.ts_PersistSummary, ts_mod, {"thread_id": "t1", "summary": {"id": "s"}}, id="ts_PersistSummary"), + pytest.param(em_mod.em_Extract, em_mod, {"thread_id": "t1"}, id="em_Extract"), + pytest.param(em_mod.em_Persist, em_mod, {"extracted": {"facts": []}}, id="em_Persist"), + pytest.param(em_mod.em_ReconcileMemories, em_mod, {}, id="em_ReconcileMemories"), + pytest.param(ee_mod.ee_ExtractEpisodes, ee_mod, {"thread_id": "t1"}, id="ee_ExtractEpisodes"), + pytest.param(sp_mod.sp_SynthesizeProcedural, sp_mod, {}, id="sp_SynthesizeProcedural"), + pytest.param(us_mod.us_Extract, us_mod, {"limit": 5}, id="us_Extract"), + pytest.param(us_mod.us_PersistUserSummary, us_mod, {"user_summary": {"id": "us"}}, id="us_PersistUserSummary"), +] + + +@pytest.mark.parametrize(("activity", "module", "extra_payload"), _PIPELINE_ACTIVITIES) +def test_an_activity_runs_on_the_pipeline_of_the_tenant_in_its_payload(activity, module, extra_payload): + pipelines = {"acme": MagicMock(name="acme-pipeline"), "globex": MagicMock(name="globex-pipeline")} + + with patch.object(module, "get_pipeline", side_effect=lambda tenant_id: pipelines[tenant_id]) as get_pipeline: + activity({"tenant_id": "globex", "user_id": "u1", **extra_payload}) + + get_pipeline.assert_called_once_with("globex") + assert pipelines["globex"].method_calls + assert not pipelines["acme"].method_calls diff --git a/tests/unit/function_app/test_pipeline_factory.py b/tests/unit/function_app/test_pipeline_factory.py index 37b7cce..942f2cf 100644 --- a/tests/unit/function_app/test_pipeline_factory.py +++ b/tests/unit/function_app/test_pipeline_factory.py @@ -1,6 +1,6 @@ """Unit tests for ``function_app/shared/pipeline_factory.py``. -The factory lazily constructs a ``PipelineService`` from environment variables. +The factory lazily constructs one ``PipelineService`` per tenant from environment variables. We mock ``DefaultAzureCredential``, the Cosmos container helper, and the SDK clients so no Azure resource is touched. """ @@ -12,13 +12,17 @@ import pytest from shared import pipeline_factory +from azure.cosmos.agent_memory.exceptions import ValidationError + @pytest.fixture(autouse=True) def _reset_pipeline_cache(): """Each test must observe a fresh build.""" - pipeline_factory._pipeline = None + pipeline_factory._pipelines.clear() + pipeline_factory._shared = None yield - pipeline_factory._pipeline = None + pipeline_factory._pipelines.clear() + pipeline_factory._shared = None @pytest.fixture(autouse=True) @@ -88,7 +92,7 @@ def mocks(monkeypatch): def test_builds_pipeline_from_complete_env(mocks): - result = pipeline_factory.get_pipeline() + result = pipeline_factory.get_pipeline("acme") assert result is mocks.pipeline_instance from azure.cosmos.agent_memory._container_routing import ContainerKey @@ -101,6 +105,7 @@ def test_builds_pipeline_from_complete_env(mocks): mocks.store_ctor.assert_called_once_with( containers=expected_containers, embeddings_client=mocks.embed_instance, + tenant_id="acme", ) mocks.pipeline_ctor.assert_called_once_with( mocks.store_instance, @@ -108,9 +113,17 @@ def test_builds_pipeline_from_complete_env(mocks): mocks.embed_instance, containers=expected_containers, transcript_metadata_keys=None, + tenant_id="acme", ) +def test_the_tenant_defaults_to_the_default_tenant(mocks): + pipeline_factory.get_pipeline() + + assert mocks.store_ctor.call_args.kwargs["tenant_id"] == "default" + assert mocks.pipeline_ctor.call_args.kwargs["tenant_id"] == "default" + + def test_uses_chat_deployment_name_env_var(monkeypatch, mocks): monkeypatch.setenv("AI_FOUNDRY_CHAT_DEPLOYMENT_NAME", "gpt-4o-mega") pipeline_factory.get_pipeline() @@ -176,15 +189,82 @@ def test_transcript_metadata_keys_env_empty_string_yields_none(monkeypatch, mock def test_pipeline_is_cached_across_calls(mocks): - a = pipeline_factory.get_pipeline() - b = pipeline_factory.get_pipeline() + a = pipeline_factory.get_pipeline("acme") + b = pipeline_factory.get_pipeline("acme") assert a is b assert mocks.pipeline_ctor.call_count == 1 + assert mocks.store_ctor.call_count == 1 assert mocks.chat_ctor.call_count == 1 assert mocks.embed_ctor.call_count == 1 +def test_each_tenant_gets_its_own_cached_pipeline_bound_to_its_own_store(mocks): + stores: dict[str, MagicMock] = {} + pipelines: dict[str, MagicMock] = {} + + def new_store(**kwargs): + stores[kwargs["tenant_id"]] = MagicMock(name=f"store-{kwargs['tenant_id']}") + return stores[kwargs["tenant_id"]] + + def new_pipeline(store, *_args, **kwargs): + pipelines[kwargs["tenant_id"]] = MagicMock(name=f"pipeline-{kwargs['tenant_id']}", store=store) + return pipelines[kwargs["tenant_id"]] + + mocks.store_ctor.side_effect = new_store + mocks.pipeline_ctor.side_effect = new_pipeline + + acme = pipeline_factory.get_pipeline("acme") + globex = pipeline_factory.get_pipeline("globex") + + assert acme is pipelines["acme"] and globex is pipelines["globex"] and acme is not globex + assert acme.store is stores["acme"] and globex.store is stores["globex"] + assert pipeline_factory.get_pipeline("acme") is acme + assert pipeline_factory.get_pipeline("globex") is globex + assert mocks.pipeline_ctor.call_count == 2 and mocks.store_ctor.call_count == 2 + + +def test_tenants_share_the_containers_and_the_chat_and_embeddings_clients(mocks): + pipeline_factory.get_pipeline("acme") + pipeline_factory.get_pipeline("globex") + + assert mocks.credential_ctor.call_count == 1 + assert mocks.chat_ctor.call_count == 1 + assert mocks.embed_ctor.call_count == 1 + (acme_store, globex_store) = mocks.store_ctor.call_args_list + (acme, globex) = mocks.pipeline_ctor.call_args_list + assert acme_store.kwargs["containers"] is globex_store.kwargs["containers"] is acme.kwargs["containers"] + assert acme.kwargs["containers"] is globex.kwargs["containers"] + assert acme.args[1:] == globex.args[1:] == (mocks.chat_instance, mocks.embed_instance) + + +@pytest.mark.parametrize("tenant_id", ["", " ", "acme/eu", "acme?eu", "acme#eu", "acme\\eu", "x" * 300]) +def test_an_invalid_tenant_is_refused_before_anything_is_built(mocks, tenant_id): + with pytest.raises(ValidationError): + pipeline_factory.get_pipeline(tenant_id) + + mocks.credential_ctor.assert_not_called() + mocks.store_ctor.assert_not_called() + mocks.pipeline_ctor.assert_not_called() + assert pipeline_factory._pipelines == {} + + +def test_the_store_and_pipeline_it_builds_are_bound_to_the_tenant(monkeypatch): + """The real ``MemoryStore`` and ``PipelineService`` take the tenant the factory passes (only Azure is faked).""" + for getter in ("get_memories_container", "get_turns_container", "get_summaries_container"): + monkeypatch.setattr(pipeline_factory, getter, lambda: MagicMock()) + with ( + patch("azure.identity.DefaultAzureCredential"), + patch("azure.cosmos.agent_memory.chat.ChatClient"), + patch("azure.cosmos.agent_memory.embeddings.EmbeddingsClient"), + ): + acme = pipeline_factory.get_pipeline("acme") + globex = pipeline_factory.get_pipeline("globex") + + assert (acme._tenant_id, acme._store.tenant_id) == ("acme", "acme") + assert (globex._tenant_id, globex._store.tenant_id) == ("globex", "globex") + + # --------------------------------------------------------------------------- # Missing-env error paths (these run BEFORE any client is constructed, so # we don't need the heavy ``mocks`` fixture). diff --git a/tests/unit/function_app/test_synthesize_procedural_orchestrator.py b/tests/unit/function_app/test_synthesize_procedural_orchestrator.py index 2ecb7ce..a9163ec 100644 --- a/tests/unit/function_app/test_synthesize_procedural_orchestrator.py +++ b/tests/unit/function_app/test_synthesize_procedural_orchestrator.py @@ -47,27 +47,35 @@ def _orchestrator(self): return _user_function(sp_mod.SynthesizeProceduralOrchestrator) @patch.object(sp_mod, "default_retry_options", return_value=MagicMock(name="retry")) - def test_calls_activity_once_with_user_and_force_and_returns_result(self, _retry): - ctx = _make_context({"user_id": "u1", "force": True}) + def test_calls_activity_once_with_tenant_user_and_force_and_returns_result(self, _retry): + ctx = _make_context({"tenant_id": "acme", "user_id": "u1", "force": True}) gen = self._orchestrator()(ctx) result, _ = _drive(gen, [{"status": "synthesized", "procedures_created": 2}]) assert [call[0] for call in ctx._yielded_calls] == ["sp_SynthesizeProcedural"] - assert ctx._yielded_calls[0][2] == {"user_id": "u1", "force": True} + assert ctx._yielded_calls[0][2] == {"tenant_id": "acme", "user_id": "u1", "force": True} assert result == {"status": "synthesized", "procedures_created": 2} + @pytest.mark.parametrize("missing", ["tenant_id", "user_id"]) + def test_missing_tenant_or_user_id_raises(self, missing): + payload = {"tenant_id": "acme", "user_id": "u1"} + del payload[missing] + with patch.object(sp_mod, "default_retry_options", return_value=MagicMock()): + with pytest.raises(KeyError): + next(self._orchestrator()(_make_context(payload))) + @pytest.mark.parametrize( ("payload", "pipeline_result", "expected"), [ ( - {"user_id": "u1", "force": True}, + {"tenant_id": "acme", "user_id": "u1", "force": True}, {"status": "synthesized", "procedures_created": 2, "procedures_updated": 1, "facts_retired": 1}, {"status": "synthesized", "procedures_created": 2, "facts_retired": 1}, ), ( - {"user_id": "u2", "force": False}, + {"tenant_id": "acme", "user_id": "u2", "force": False}, {"status": "skipped", "procedures_created": None}, {"status": "skipped", "procedures_created": 0, "facts_retired": 0}, ), @@ -75,7 +83,9 @@ def test_calls_activity_once_with_user_and_force_and_returns_result(self, _retry ids=["extra-fields-dropped", "missing-count-is-zero"], ) @patch.object(sp_mod, "get_pipeline") -def test_activity_calls_pipeline_and_returns_slim_payload(mock_get_pipeline, payload, pipeline_result, expected): +def test_activity_calls_the_tenants_pipeline_and_returns_slim_payload( + mock_get_pipeline, payload, pipeline_result, expected +): """Durable records activity outputs in the job history, so only the status and counts may come back.""" pipeline = MagicMock() pipeline.synthesize_procedural.return_value = pipeline_result @@ -84,6 +94,7 @@ def test_activity_calls_pipeline_and_returns_slim_payload(mock_get_pipeline, pay with patch.object(sp_mod.time, "monotonic", return_value=100.0): result = sp_mod.sp_SynthesizeProcedural(payload) + mock_get_pipeline.assert_called_once_with("acme") # The pass stops starting model calls at the activity's time budget (240 s by default). pipeline.synthesize_procedural.assert_called_once_with( user_id=payload["user_id"], force=payload["force"], deadline=340.0 @@ -100,6 +111,6 @@ def test_activity_deadline_follows_the_configured_time_budget(mock_get_pipeline, mock_get_pipeline.return_value = pipeline with patch.object(sp_mod.time, "monotonic", return_value=100.0): - sp_mod.sp_SynthesizeProcedural({"user_id": "u1"}) + sp_mod.sp_SynthesizeProcedural({"tenant_id": "acme", "user_id": "u1"}) assert pipeline.synthesize_procedural.call_args.kwargs["deadline"] == 190.0 diff --git a/tests/unit/processors/test_base.py b/tests/unit/processors/test_base.py index b7e8f10..92a6f24 100644 --- a/tests/unit/processors/test_base.py +++ b/tests/unit/processors/test_base.py @@ -39,3 +39,17 @@ def test_inprocess_requires_pipeline_or_components(): with pytest.raises(ValueError): InProcessProcessor() + + +def test_inprocess_built_from_components_belongs_to_the_tenant_it_is_given(): + proc = InProcessProcessor( + cosmos_container=MagicMock(), + turns_container=MagicMock(), + summaries_container=MagicMock(), + chat_client=MagicMock(), + embeddings_client=MagicMock(), + tenant_id="acme", + ) + + assert proc._pipeline._store.tenant_id == "acme" + assert proc._pipeline._tenant_id == "acme" diff --git a/tests/unit/services/test_absorbed.py b/tests/unit/services/test_absorbed.py index 85a0083..11863dc 100644 --- a/tests/unit/services/test_absorbed.py +++ b/tests/unit/services/test_absorbed.py @@ -21,17 +21,19 @@ ) from azure.cosmos.agent_memory.services._combine import COMBINE_REASON -# m1 absorbed a and b; a absorbed c; a bad record points c back at a. The records live in different threads. +# m1 absorbed a and b; a absorbed c; a bad record points c back at a. The records come from different threads, which +# does not matter: they all sit in the owner's partition. FOLDED = { - "m1": [{"id": "a", "type": "fact", "thread_id": "t2"}, {"id": "b", "type": "fact", "thread_id": "t1"}], - "a": [{"id": "c", "type": "fact", "thread_id": "t3"}], - "c": [{"id": "a", "type": "fact", "thread_id": "t2"}], + "m1": [{"id": "a", "type": "fact"}, {"id": "b", "type": "fact"}], + "a": [{"id": "c", "type": "fact"}], + "c": [{"id": "a", "type": "fact"}], } +OWNER_PARTITION = ["acme", "u1"] def _rows(*, query, parameters, **_kwargs): params = {p["name"]: p["value"] for p in parameters} - assert params["@user_id"] == "u1" + assert (params["@tenant_id"], params["@user_id"]) == ("acme", "u1") return list(FOLDED.get(params["@memory_id"], [])) @@ -54,10 +56,11 @@ async def iterate(): def test_the_query_names_only_duplicate_combined_and_procedure_retirements(): - query, parameters = absorbed_query("u1", "m1") + query, parameters = absorbed_query("acme", "u1", "m1") params = {p["name"]: p["value"] for p in parameters} - assert "c.user_id = @user_id" in query and params["@user_id"] == "u1" + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in query + assert (params["@tenant_id"], params["@user_id"]) == ("acme", "u1") assert "c.superseded_by = @memory_id" in query and params["@memory_id"] == "m1" assert sorted(v for k, v in params.items() if k.startswith("@reason_")) == ["combined", "duplicate", "procedure"] @@ -66,21 +69,23 @@ def test_everything_folded_in_is_deleted_once_children_before_parents(): container = MagicMock() container.query_items.side_effect = _rows - found = delete_absorbed(container, "u1", "m1") + found = delete_absorbed(container, "acme", "u1", "m1") assert sorted(row["id"] for row in found) == ["a", "b", "c"] deleted = [call.kwargs["item"] for call in container.delete_item.call_args_list] assert sorted(deleted) == ["a", "b", "c"] and deleted.index("c") < deleted.index("a") -def test_each_record_is_looked_up_across_partitions_and_deleted_under_its_own_thread(): +def test_every_record_is_looked_up_and_deleted_in_the_owners_partition(): container = MagicMock() container.query_items.side_effect = _rows - delete_absorbed(container, "u1", "m1") + delete_absorbed(container, "acme", "u1", "m1") - assert all(call.kwargs["enable_cross_partition_query"] for call in container.query_items.call_args_list) - assert _deleted(container) == {"a": ["u1", "t2"], "b": ["u1", "t1"], "c": ["u1", "t3"]} + queried = [call.kwargs["partition_key"] for call in container.query_items.call_args_list] + assert queried and all(key == OWNER_PARTITION for key in queried) + assert not any("enable_cross_partition_query" in call.kwargs for call in container.query_items.call_args_list) + assert _deleted(container) == {"a": OWNER_PARTITION, "b": OWNER_PARTITION, "c": OWNER_PARTITION} def test_a_record_already_gone_is_skipped_and_other_failures_raise(): @@ -88,18 +93,18 @@ def test_a_record_already_gone_is_skipped_and_other_failures_raise(): container.query_items.side_effect = _rows container.delete_item.side_effect = CosmosResourceNotFoundError(status_code=404, message="not found") - assert len(delete_absorbed(container, "u1", "m1")) == 3 + assert len(delete_absorbed(container, "acme", "u1", "m1")) == 3 container.delete_item.side_effect = RuntimeError("throttled") with pytest.raises(RuntimeError): - delete_absorbed(container, "u1", "m1") + delete_absorbed(container, "acme", "u1", "m1") def test_nothing_folded_in_means_nothing_is_deleted(): container = MagicMock() container.query_items.return_value = [] - assert delete_absorbed(container, "u1", "m1") == [] + assert delete_absorbed(container, "acme", "u1", "m1") == [] container.delete_item.assert_not_called() @@ -133,20 +138,22 @@ def test_the_cascade_follows_exactly_the_retirements_that_leave_a_copy_behind(mo async def test_the_async_walk_matches_the_sync_one(): container = _async_container() - found = await adelete_absorbed(container, "u1", "m1") + found = await adelete_absorbed(container, "acme", "u1", "m1") assert sorted(row["id"] for row in found) == ["a", "b", "c"] deleted = [call.kwargs["item"] for call in container.delete_item.call_args_list] assert sorted(deleted) == ["a", "b", "c"] and deleted.index("c") < deleted.index("a") - assert _deleted(container) == {"a": ["u1", "t2"], "b": ["u1", "t1"], "c": ["u1", "t3"]} + queried = [call.kwargs["partition_key"] for call in container.query_items.call_args_list] + assert queried and all(key == OWNER_PARTITION for key in queried) + assert _deleted(container) == {"a": OWNER_PARTITION, "b": OWNER_PARTITION, "c": OWNER_PARTITION} async def test_the_async_walk_skips_a_record_already_gone_and_raises_other_failures(): container = _async_container() container.delete_item.side_effect = CosmosResourceNotFoundError(status_code=404, message="not found") - assert len(await adelete_absorbed(container, "u1", "m1")) == 3 + assert len(await adelete_absorbed(container, "acme", "u1", "m1")) == 3 container.delete_item.side_effect = RuntimeError("throttled") with pytest.raises(RuntimeError): - await adelete_absorbed(container, "u1", "m1") + await adelete_absorbed(container, "acme", "u1", "m1") diff --git a/tests/unit/services/test_combine.py b/tests/unit/services/test_combine.py index c282f6f..49dd2f6 100644 --- a/tests/unit/services/test_combine.py +++ b/tests/unit/services/test_combine.py @@ -50,6 +50,7 @@ PLANS = "The user is planning a Christmas Eve dinner for 15 guests" START = "The user wants the Christmas Eve dinner to start at 6:30 PM" BOTH = "For the user's Christmas Eve dinner, the user is planning for 15 guests and wants it to start at 6:30 PM." +TENANT = "acme" def _fact( @@ -64,6 +65,7 @@ def _fact( ) -> dict: doc = { "id": fid, + "tenant_id": TENANT, "user_id": "u1", "thread_id": "t1", "role": "system", @@ -152,6 +154,7 @@ def checked_texts(self) -> list[list[str]]: def _make_pipeline() -> PipelineService: p = PipelineService.__new__(PipelineService) + p._tenant_id = TENANT p._embeddings = MagicMock() p._embed_one = MagicMock(return_value=[0.1, 0.2, 0.3]) p._commit_fold = MagicMock(side_effect=lambda survivor, losers, **kwargs: [doc["id"] for doc in losers]) @@ -510,6 +513,7 @@ class TestCommitCombine: @staticmethod def _build() -> PipelineService: p = PipelineService.__new__(PipelineService) + p._tenant_id = TENANT p._container = MagicMock() p._memories_container = p._container p._mark_superseded = MagicMock(return_value=True) @@ -539,7 +543,7 @@ def test_a_fact_that_already_exists_is_not_created_again_and_its_members_are_sti record, members = self._inputs() assert p._commit_combine(record, members) == ["f1", "f2"] - assert p._container.read_item.call_args.kwargs == {"item": record["id"], "partition_key": ["u1", "t1"]} + assert p._container.read_item.call_args.kwargs == {"item": record["id"], "partition_key": [TENANT, "u1"]} @pytest.mark.parametrize( "existing", @@ -889,3 +893,34 @@ def test_reconcile_reports_the_combine_counts(self, caplog): [record] = [r for r in caplog.records if r.getMessage() == "reconcile.outcome"] assert (result["combined"], result["synthesized"], result["combine_groups"]) == (2, 1, 1) assert (record.combined, record.synthesized, record.combine_groups, record.combine_failed) == (2, 1, 1, 0) + + +class TestAPassStaysInsideItsTenant: + def test_it_filters_on_the_tenant_and_reads_only_the_owners_partition(self): + p = _make_pipeline() + seed, partner, verdicts = _pair() + model = _Model(verdicts, [_write(["M1", "M2"], BOTH)], [_holds(2)]) + + _run(p, [seed], {seed["id"]: [partner]}, model) + + queries = p._container.query_items.call_args_list + assert len(queries) == 2, "the seeds and the seed's neighbours" + for call in queries: + params = {item["name"]: item["value"] for item in call.kwargs["parameters"]} + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in call.kwargs["query"] + assert (params["@tenant_id"], params["@user_id"]) == (TENANT, "u1") + assert call.kwargs["partition_key"] == [TENANT, "u1"] + assert "enable_cross_partition_query" not in call.kwargs + reads = p._container.read_item.call_args_list + assert reads and all(call.kwargs["partition_key"] == [TENANT, "u1"] for call in reads) + + def test_the_combined_fact_and_the_cursor_it_writes_carry_the_tenant(self): + p = _make_pipeline() + seed, partner, verdicts = _pair() + model = _Model(verdicts, [_write(["M1", "M2"], BOTH)], [_holds(2)]) + + _run(p, [seed], {seed["id"]: [partner]}, model) + + written = [call.kwargs["body"] for call in p._container.create_item.call_args_list] + assert {body["type"] for body in written} == {"fact", "dedup_cursor"} + assert {body["tenant_id"] for body in written} == {TENANT} diff --git a/tests/unit/services/test_conflict_links.py b/tests/unit/services/test_conflict_links.py index 19973db..00b9502 100644 --- a/tests/unit/services/test_conflict_links.py +++ b/tests/unit/services/test_conflict_links.py @@ -2,13 +2,14 @@ The duplicate check labels how each new fact relates to its nearest neighbours; ``update`` (the same attribute with a different value at a later time) and ``inconsistent`` (the two cannot both be true) name a conflict. A pass that finds -one keeps both facts active and writes one small link document for the pair, in the user's ``__conflicts__`` -partition, from the verdicts it already has: no model call is added. +one keeps both facts active and writes one small link document for the pair, in the owner's partition (marked with +the thread id ``__conflicts__``), from the verdicts it already has: no model call is added. ``reconcile_memories`` and ``consolidate_memories`` run for real here, with the real memory store and prompt templates, against a fake memories container that answers the passes' queries the way Cosmos DB does (it applies every filter, the ``ORDER BY`` and the ``TOP``, keeps one ETag per record, rejects a conditional write whose ETag is stale, -and finds a record only under its own partition) and a scripted chat model that reads each rendered prompt. A +refuses a query that does not name one owner's partition, and finds a record only under its own ``[tenant_id, +user_id]`` partition) and a scripted chat model that reads each rendered prompt. A predicate the fake does not understand, or a prompt the test did not plan for, fails the test. Covers: @@ -50,6 +51,7 @@ from azure.cosmos.agent_memory.store import MemoryStore USER = "u1" +TENANT = "acme" CURSOR_ID = "dedup_cursor_u1_fact" RESULT_KEYS = { @@ -143,12 +145,17 @@ def _ordered(rows: list[dict[str, Any]], order: str | None, params: dict[str, An class Account: - """The memories container as Cosmos DB serves the passes: one partition per ``[user_id, thread_id]``.""" + """The memories container as Cosmos DB serves the passes: one partition per ``[tenant_id, user_id]``, which holds + the records of every thread of that owner. A query must name the partition it reads.""" def __init__(self, docs: Iterable[dict[str, Any]] = ()) -> None: self._docs: dict[tuple[str, str, str], dict[str, Any]] = {} self._writes = itertools.count(1000) self.queries: list[str] = [] + # What each query asked: its text, its parameters and the partition it named. + self.requests: list[tuple[str, dict[str, Any], Any]] = [] + # The partition of each point read. + self.reads: list[Any] = [] # The errors the next writes of link documents raise, one each. self.link_write_errors: list[Exception] = [] for doc in docs: @@ -160,17 +167,28 @@ def put(self, doc: dict[str, Any]) -> dict[str, Any]: stored = {key: value for key, value in doc.items() if not key.startswith("_")} number = next(self._writes) stored["_etag"], stored["_ts"] = f'"{number}"', number - self._docs[(stored["user_id"], stored["thread_id"], stored["id"])] = stored + self._docs[(stored["tenant_id"], stored["user_id"], stored["id"])] = stored return copy.deepcopy(stored) - def get(self, record_id: str) -> dict[str, Any] | None: - return next((copy.deepcopy(doc) for doc in self._docs.values() if doc["id"] == record_id), None) + def get(self, record_id: str, tenant_id: str = TENANT) -> dict[str, Any] | None: + return next( + ( + copy.deepcopy(doc) + for doc in self._docs.values() + if doc["id"] == record_id and doc["tenant_id"] == tenant_id + ), + None, + ) def delete(self, record_id: str) -> None: self._docs = {key: doc for key, doc in self._docs.items() if doc["id"] != record_id} def active_ids(self) -> set[str]: - return {doc["id"] for doc in self._docs.values() if doc["type"] == "fact" and doc.get("superseded_by") is None} + return { + doc["id"] + for doc in self._docs.values() + if doc["tenant_id"] == TENANT and doc["type"] == "fact" and doc.get("superseded_by") is None + } def retirements(self) -> dict[str, tuple[str, str]]: """Each retired fact's ID with who it was retired into and why.""" @@ -196,16 +214,16 @@ def query_items( partition_key: Any = None, enable_cross_partition_query: bool = False, ) -> Iterator[dict[str, Any]]: - if partition_key is None and not enable_cross_partition_query: - raise CosmosHttpResponseError(status_code=400, message="Cross partition query is required but disabled.") + if partition_key is None or enable_cross_partition_query: + raise AssertionError("every query of the passes reads the partition of one owner") self.queries.append(query) match = _SELECT.fullmatch(query) assert match, f"the fake container cannot parse {query!r}" params = {parameter["name"]: parameter["value"] for parameter in parameters or []} + self.requests.append((query, params, list(partition_key))) predicates = _conjuncts(match["where"]) rows = [doc for doc in self._docs.values() if all(_holds(doc, predicate, params) for predicate in predicates)] - if partition_key is not None: - rows = [doc for doc in rows if [doc["user_id"], doc["thread_id"]] == list(partition_key)] + rows = [doc for doc in rows if [doc["tenant_id"], doc["user_id"]] == list(partition_key)] rows = _ordered(rows, match["order"], params)[: int(match["top"] or len(rows))] if match["cols"] == "*": return iter(copy.deepcopy(rows)) @@ -213,13 +231,14 @@ def query_items( return iter([{column: doc.get(column) for column in columns} for doc in rows]) def read_item(self, item: str, partition_key: Any) -> dict[str, Any]: + self.reads.append(list(partition_key)) doc = self._docs.get((partition_key[0], partition_key[1], item)) if doc is None: raise CosmosResourceNotFoundError(status_code=404, message="Entity with the specified id does not exist.") return copy.deepcopy(doc) def create_item(self, body: dict[str, Any]) -> dict[str, Any]: - if (body["user_id"], body["thread_id"], body["id"]) in self._docs: + if (body["tenant_id"], body["user_id"], body["id"]) in self._docs: raise CosmosResourceExistsError(status_code=409, message="Entity with the specified id already exists.") return self.put(body) @@ -232,7 +251,7 @@ def replace_item( self, item: str, body: dict[str, Any], *, etag: str | None = None, match_condition: Any = None, **_: Any ) -> dict[str, Any]: assert (etag is None) == (match_condition is None), "a conditional write names the ETag and how to match it" - current = self._docs.get((body["user_id"], body["thread_id"], item)) + current = self._docs.get((body["tenant_id"], body["user_id"], item)) if current is None: raise CosmosResourceNotFoundError(status_code=404, message="Entity with the specified id does not exist.") if match_condition == MatchConditions.IfNotModified and etag != current["_etag"]: @@ -346,10 +365,12 @@ def fact( *, thread_id: str = "t1", agent: bool = False, + tenant_id: str = TENANT, **extra: Any, ) -> dict[str, Any]: return { "id": fid, + "tenant_id": tenant_id, "user_id": USER, "thread_id": thread_id, "type": "fact", @@ -370,11 +391,11 @@ def service_over(account: Any, chat: Any) -> PipelineService: """The real pipeline and memory store over ``account``, with ``chat`` as the model.""" embeddings = Embeddings(VECTORS) containers = {ContainerKey.MEMORIES: account, ContainerKey.TURNS: MagicMock(), ContainerKey.SUMMARIES: MagicMock()} - store = MemoryStore(containers=containers, embeddings_client=embeddings) - return PipelineService(store, chat, embeddings, containers=containers) + store = MemoryStore(containers=containers, embeddings_client=embeddings, tenant_id=TENANT) + return PipelineService(store, chat, embeddings, containers=containers, tenant_id=TENANT) -# The two facts of a conflict: in different threads, so in different partitions. +# The two facts of a conflict: said in different threads, which does not matter, they are the owner's. def conflicting_facts(older: str, newer: str) -> list[dict[str, Any]]: return [ fact("f1", older, V_A, "2026-03-01T10:00:00Z", thread_id="t1"), @@ -421,6 +442,7 @@ def test_both_facts_stay_active_and_one_link_names_the_pair(self, kind, entry): assert link_fields(link) == { "id": link["id"], "type": "conflict_link", + "tenant_id": TENANT, "user_id": USER, "thread_id": "__conflicts__", "first": "f1", @@ -428,9 +450,7 @@ def test_both_facts_stay_active_and_one_link_names_the_pair(self, kind, entry): "kind": kind, } assert link["id"].startswith("conflict_") and link["created_at"] - assert account.read_item(link["id"], [USER, "__conflicts__"])["id"] == link["id"], ( - "it is in the user's partition" - ) + assert account.read_item(link["id"], [TENANT, USER])["id"] == link["id"], "it is in the owner's partition" assert not {"content", "text"} & set(link), "a link names the facts and holds none of their text" assert (result["conflicts"], result["checked"], result["compared"], result["kept"]) == (1, 2, 1, 2) assert (result["merged"], result["combined"], result["synthesized"]) == (0, 0, 0) @@ -639,3 +659,57 @@ def test_the_result_has_the_full_shape_with_no_conflicts_and_nothing_is_read_or_ assert result["conflicts"] == 0 and sum(result.values()) == 0 assert account.queries == [] and account.links() == [] and chat.calls == [] assert account.get("f1") == before + + +# --------------------------------------------------------------------------- +# A pass stays inside its tenant +# --------------------------------------------------------------------------- +class TestAPassStaysInsideItsTenant: + def test_every_query_and_point_read_names_the_tenant_and_the_owners_partition(self): + account, _, service = a_conflict("update") + + service.reconcile_memories(USER) + + assert len(account.requests) >= 2, "the seeds and the neighbours were read" + for sql, params, partition in account.requests: + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in sql + assert (params["@tenant_id"], params["@user_id"], partition) == (TENANT, USER, [TENANT, USER]) + assert account.reads and all(key == [TENANT, USER] for key in account.reads), "the cursor is read there too" + + def test_everything_a_pass_writes_carries_the_tenant(self): + account, _, service = a_conflict("update") + + service.reconcile_memories(USER) + + assert account.links() and account.get(CURSOR_ID) + assert {doc["tenant_id"] for doc in account._docs.values()} == {TENANT}, "the link and the cursor included" + + def test_a_combined_fact_carries_the_tenant_and_is_written_with_it(self): + account, chat = Account([fact("old", OLD_FLIGHT, V_OLD, "2026-03-01T10:00:00Z", thread_id="t0")]), flight_chat() + service = service_over(account, chat) + account.put(fact("g", GATE, V_A, "2026-05-01T10:00:00Z", thread_id="t1")) + account.put(fact("l", LEAVES, V_LEAVES, "2026-05-01T10:05:00Z", thread_id="t2")) + + service.reconcile_memories(USER) + + assert account.combined()["tenant_id"] == TENANT + assert {doc["tenant_id"] for doc in account._docs.values()} == {TENANT} + assert all(key == [TENANT, USER] for key in account.reads), "the members were read back there" + + def test_a_fact_of_the_same_user_in_another_tenant_is_neither_checked_nor_linked_nor_retired(self): + older, newer = CONFLICTS["update"] + # The same user id in another tenant has already said what the newer fact says: a duplicate out of reach. + theirs = fact("f3", newer, V_B, "2026-04-02T10:00:00Z", tenant_id="other") + account = Account([*conflicting_facts(older, newer), theirs]) + before = account.get("f3", "other") + service = service_over(account, Chat(between({(older, newer): "update", (newer, newer): "same_claim"}))) + + result = service.reconcile_memories(USER) + + assert (result["checked"], result["compared"], result["conflicts"], result["merged"]) == (2, 1, 1, 0) + assert account.retirements() == {} + assert account.get("f3", "other") == before, "it was not rewritten" + [link] = account.links() + assert (link["tenant_id"], link["first"], link["later"]) == (TENANT, "f1", "f2") + assert account.get(CURSOR_ID, "other") is None, "the other tenant has no cursor of ours" + assert account.get(CURSOR_ID)["tenant_id"] == TENANT diff --git a/tests/unit/services/test_conflicts.py b/tests/unit/services/test_conflicts.py index 989ddbe..d005a54 100644 --- a/tests/unit/services/test_conflicts.py +++ b/tests/unit/services/test_conflicts.py @@ -28,6 +28,8 @@ ) from azure.cosmos.agent_memory.services._dedup import ACTIVE_FILTER, Verdict +TENANT = "acme" + def fact(fact_id: str, created_at: str, *, agent: bool = False) -> dict[str, Any]: tags = ["sys:fact", "sys:agent-fact"] if agent else ["sys:fact"] @@ -107,11 +109,12 @@ def test_its_id_is_the_same_whichever_way_the_pair_is_written(self) -> None: def test_it_names_the_facts_and_the_kind_and_holds_no_text(self) -> None: now = datetime(2026, 5, 1, 12, 0, tzinfo=timezone.utc) - body = conflict_link_body("u1", ConflictPair("a", "b", "inconsistent"), now=now) + body = conflict_link_body(TENANT, "u1", ConflictPair("a", "b", "inconsistent"), now=now) assert body == { "id": conflict_link_id("u1", ConflictPair("a", "b", "inconsistent")), "type": CONFLICT_LINK_TYPE, + "tenant_id": TENANT, "user_id": "u1", "thread_id": CONFLICT_LINK_THREAD_ID, "first": "a", @@ -120,20 +123,27 @@ def test_it_names_the_facts_and_the_kind_and_holds_no_text(self) -> None: "created_at": "2026-05-01T12:00:00+00:00", } - def test_the_queries_are_scoped_to_the_user_and_the_fact_query_reads_retired_facts_too(self) -> None: - query, parameters = links_query("u1", ["a", "b"]) - assert "c.user_id = @user_id" in query and "c.type = @type" in query + def test_the_queries_are_scoped_to_the_tenant_and_the_owner_and_the_fact_query_reads_retired_facts_too( + self, + ) -> None: + query, parameters = links_query(TENANT, "u1", ["a", "b"]) + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in query and "c.type = @type" in query assert {p["name"]: p["value"] for p in parameters} == { + "@tenant_id": TENANT, "@user_id": "u1", "@type": CONFLICT_LINK_TYPE, "@ids": ["a", "b"], } - query, parameters = facts_query("u1", ["a", "b"]) - assert "c.type = 'fact'" in query and "c.user_id = @user_id" in query + query, parameters = facts_query(TENANT, "u1", ["a", "b"]) + assert "c.type = 'fact'" in query and "c.tenant_id = @tenant_id AND c.user_id = @user_id" in query # A retired fact is read too: where it went (superseded_by) is how a conflict follows it. assert "c.superseded_by" in query and ACTIVE_FILTER not in query - assert {p["name"]: p["value"] for p in parameters} == {"@user_id": "u1", "@ids": ["a", "b"]} + assert {p["name"]: p["value"] for p in parameters} == { + "@tenant_id": TENANT, + "@user_id": "u1", + "@ids": ["a", "b"], + } def test_the_endpoints_of_the_links_are_listed_once(self) -> None: links = [{"first": "a", "later": "b"}, {"first": "b", "later": "c"}, {"first": None, "later": "a"}] @@ -327,7 +337,9 @@ def __init__(self, links: list[dict[str, Any]], facts: list[dict[str, Any]], *, def __call__(self, sql: str, parameters: list[dict[str, Any]], **kwargs: Any) -> list[dict[str, Any]]: values = {p["name"]: p["value"] for p in parameters} - self.calls.append({"sql": sql, "user": values["@user_id"], "ids": values["@ids"], **kwargs}) + self.calls.append( + {"sql": sql, "tenant": values["@tenant_id"], "user": values["@user_id"], "ids": values["@ids"], **kwargs} + ) if self.fail: raise RuntimeError("secret-looking failure text") asked = set(values["@ids"]) @@ -338,7 +350,7 @@ def __call__(self, sql: str, parameters: list[dict[str, Any]], **kwargs: Any) -> @property def fact_reads(self) -> list[list[str]]: """The IDs each read of facts asked for.""" - return [call["ids"] for call in self.calls if call.get("cross_partition")] + return [call["ids"] for call in self.calls if "c.type = 'fact'" in call["sql"]] STORED_LINKS = [{"first": "a", "later": "b", "kind": "update"}] @@ -359,27 +371,31 @@ class TestLookingUpTheConflictsOfSearchResults: def test_a_fact_is_returned_with_the_active_facts_it_conflicts_with(self) -> None: query = Recorder(STORED_LINKS, STORED_FACTS) - shown = with_conflicts([result("a"), result("z")], query) + shown = with_conflicts([result("a"), result("z")], query, TENANT) assert shown[0]["conflicts_with"] == [ {"id": "b", "content": "text of b", "created_at": "2026-02-01T00:00:00Z", "kind": "update"} ] assert "conflicts_with" not in shown[1] - def test_the_links_are_read_from_the_users_conflict_partition_and_the_facts_across_partitions(self) -> None: + def test_the_links_and_the_facts_are_both_read_in_the_owners_partition(self) -> None: query = Recorder(STORED_LINKS, STORED_FACTS) - with_conflicts([result("a")], query) + with_conflicts([result("a")], query, TENANT) links_call, facts_call = query.calls - assert links_call["partition_key"] == ["u1", CONFLICT_LINK_THREAD_ID] and links_call["ids"] == ["a"] - assert facts_call["cross_partition"] is True and facts_call["ids"] == ["a", "b"] + assert links_call["ids"] == ["a"] and facts_call["ids"] == ["a", "b"] + for call in query.calls: + assert (call["tenant"], call["user"]) == (TENANT, "u1") + assert call["partition_key"] == [TENANT, "u1"] + assert "cross_partition" not in call + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in call["sql"] def test_nothing_is_queried_for_results_that_are_not_facts_or_have_no_user(self) -> None: query = Recorder(STORED_LINKS, STORED_FACTS) docs = [result("t1", kind="turn"), result("e1", kind="episodic"), {"id": "f1", "type": "fact"}] - assert with_conflicts(docs, query) == docs + assert with_conflicts(docs, query, TENANT) == docs assert query.calls == [] def test_a_search_with_no_links_costs_one_query(self) -> None: @@ -387,30 +403,32 @@ def test_a_search_with_no_links_costs_one_query(self) -> None: docs = [result("a")] - assert with_conflicts(docs, query) == docs + assert with_conflicts(docs, query, TENANT) == docs assert len(query.calls) == 1 def test_a_search_with_links_to_active_facts_costs_two_queries(self) -> None: query = Recorder(STORED_LINKS, STORED_FACTS) - with_conflicts([result("a")], query) + with_conflicts([result("a")], query, TENANT) assert len(query.calls) == 2 - def test_each_user_is_looked_up_on_their_own(self) -> None: + def test_each_user_is_looked_up_on_their_own_in_their_own_partition(self) -> None: query = Recorder(STORED_LINKS, STORED_FACTS) - with_conflicts([result("a", "u1"), result("b", "u2")], query) + with_conflicts([result("a", "u1"), result("b", "u2")], query, TENANT) - assert [(call["user"], call["ids"]) for call in query.calls if "partition_key" in call] == [ - ("u1", ["a"]), - ("u2", ["b"]), + assert [ + (call["user"], call["ids"], call["partition_key"]) for call in query.calls if "@type" in call["sql"] + ] == [ + ("u1", ["a"], [TENANT, "u1"]), + ("u2", ["b"], [TENANT, "u2"]), ] def test_a_linked_fact_retired_since_is_followed_to_the_fact_that_took_its_place(self) -> None: query = Recorder([{"first": "a", "later": "m", "kind": "update"}], RETIRED_SINCE) - [shown] = with_conflicts([result("a")], query) + [shown] = with_conflicts([result("a")], query, TENANT) assert shown["conflicts_with"] == [ {"id": "c", "content": "text of c", "created_at": "2026-02-01T00:00:00Z", "kind": "update"} @@ -420,7 +438,7 @@ def test_a_linked_fact_retired_since_is_followed_to_the_fact_that_took_its_place def test_the_fact_that_took_its_place_shows_the_conflict_of_what_it_absorbed(self) -> None: query = Recorder([{"first": "a", "later": "m", "kind": "inconsistent"}], RETIRED_SINCE) - [shown] = with_conflicts([result("c", merged_from=["m"])], query) + [shown] = with_conflicts([result("c", merged_from=["m"])], query, TENANT) assert query.calls[0]["ids"] == ["c", "m"] assert shown["conflicts_with"] == [ @@ -436,18 +454,20 @@ def test_a_conflict_inside_one_combined_fact_is_not_shown(self) -> None: query = Recorder([{"first": "m1", "later": "m2", "kind": "update"}], facts) docs = [result("c", merged_from=["m1", "m2"])] - assert with_conflicts(docs, query) == docs + assert with_conflicts(docs, query, TENANT) == docs def test_a_linked_fact_retired_into_one_that_is_gone_shows_no_conflict(self) -> None: facts = [row("a", "2026-01-01T00:00:00Z"), row("m", "2026-02-01T00:00:00Z", superseded_by="gone")] docs = [result("a")] - assert with_conflicts(docs, Recorder([{"first": "a", "later": "m", "kind": "update"}], facts)) == docs + assert with_conflicts(docs, Recorder([{"first": "a", "later": "m", "kind": "update"}], facts), TENANT) == docs def test_what_a_result_absorbed_is_looked_up_after_the_results_themselves_and_only_up_to_a_limit(self) -> None: query = Recorder([], []) - with_conflicts([result("c", merged_from=[f"m{i}" for i in range(MAX_LOOKUP_IDS * 2)]), result("d")], query) + with_conflicts( + [result("c", merged_from=[f"m{i}" for i in range(MAX_LOOKUP_IDS * 2)]), result("d")], query, TENANT + ) ids = query.calls[0]["ids"] assert ids[:2] == ["c", "d"] and len(ids) == MAX_LOOKUP_IDS @@ -461,7 +481,7 @@ def test_a_loop_of_retirements_ends_without_a_conflict(self) -> None: query = Recorder([{"first": "a", "later": "m", "kind": "update"}], facts) docs = [result("a")] - assert with_conflicts(docs, query) == docs + assert with_conflicts(docs, query, TENANT) == docs assert len(query.calls) <= 2 + MAX_REDIRECT_HOPS def test_a_failed_lookup_returns_the_results_as_they_were_and_logs_no_text( @@ -470,7 +490,7 @@ def test_a_failed_lookup_returns_the_results_as_they_were_and_logs_no_text( docs = [result("a")] with caplog.at_level(logging.WARNING): - shown = with_conflicts(docs, Recorder([], [], fail=True)) + shown = with_conflicts(docs, Recorder([], [], fail=True), TENANT) assert shown == docs assert "secret-looking failure text" not in caplog.text @@ -483,10 +503,12 @@ async def test_async_a_fact_is_returned_with_the_active_facts_it_conflicts_with( async def query(sql: str, parameters: list[dict[str, Any]], **kwargs: Any) -> list[dict[str, Any]]: return sync(sql, parameters, **kwargs) - shown = await awith_conflicts([result("a")], query) + shown = await awith_conflicts([result("a")], query, TENANT) assert [entry["id"] for entry in shown[0]["conflicts_with"]] == ["b"] - assert sync.calls[0]["partition_key"] == ["u1", CONFLICT_LINK_THREAD_ID] + for call in sync.calls: + assert (call["tenant"], call["user"], call["partition_key"]) == (TENANT, "u1", [TENANT, "u1"]) + assert "cross_partition" not in call @pytest.mark.asyncio async def test_async_a_linked_fact_retired_since_is_followed_to_the_fact_that_took_its_place(self) -> None: @@ -495,7 +517,7 @@ async def test_async_a_linked_fact_retired_since_is_followed_to_the_fact_that_to async def query(sql: str, parameters: list[dict[str, Any]], **kwargs: Any) -> list[dict[str, Any]]: return sync(sql, parameters, **kwargs) - [shown] = await awith_conflicts([result("a")], query) + [shown] = await awith_conflicts([result("a")], query, TENANT) assert [entry["id"] for entry in shown["conflicts_with"]] == ["c"] assert sync.fact_reads == [["a", "m"], ["c"]] @@ -507,7 +529,7 @@ async def test_async_the_fact_that_took_its_place_shows_the_conflict_of_what_it_ async def query(sql: str, parameters: list[dict[str, Any]], **kwargs: Any) -> list[dict[str, Any]]: return sync(sql, parameters, **kwargs) - [shown] = await awith_conflicts([result("c", merged_from=["m"])], query) + [shown] = await awith_conflicts([result("c", merged_from=["m"])], query, TENANT) assert [entry["id"] for entry in shown["conflicts_with"]] == ["a"] assert sync.calls[0]["ids"] == ["c", "m"] @@ -526,7 +548,7 @@ async def query(sql: str, parameters: list[dict[str, Any]], **kwargs: Any) -> li docs = [result("a")] - assert await awith_conflicts(docs, query) == docs + assert await awith_conflicts(docs, query, TENANT) == docs assert len(sync.calls) <= 2 + MAX_REDIRECT_HOPS @pytest.mark.asyncio @@ -536,4 +558,4 @@ async def query(sql: str, parameters: list[dict[str, Any]], **kwargs: Any) -> li docs = [result("a")] - assert await awith_conflicts(docs, query) == docs + assert await awith_conflicts(docs, query, TENANT) == docs diff --git a/tests/unit/services/test_consolidate_memories.py b/tests/unit/services/test_consolidate_memories.py index 5127fcd..98b5a93 100644 --- a/tests/unit/services/test_consolidate_memories.py +++ b/tests/unit/services/test_consolidate_memories.py @@ -35,6 +35,7 @@ NEAR = [1.0, 0.0, 0.0] NEAR_ENOUGH = [0.9, 0.3, 0.0] # cosine 0.95 with NEAR TOO_FAR = [0.8, 0.6, 0.0] # cosine 0.80 with NEAR: below the 0.85 floor +TENANT = "acme" @pytest.fixture(autouse=True) @@ -44,6 +45,7 @@ def _dedup_only(monkeypatch): def _make_pipeline() -> PipelineService: p = PipelineService.__new__(PipelineService) + p._tenant_id = TENANT p._embeddings = MagicMock() p._commit_fold = MagicMock(side_effect=lambda survivor, losers, **kwargs: [doc["id"] for doc in losers]) p._container = MagicMock() @@ -67,6 +69,7 @@ def _fact( ) -> dict: doc = { "id": fid, + "tenant_id": TENANT, "user_id": "u1", "thread_id": "t1", "type": "fact", @@ -172,7 +175,7 @@ def test_a_fact_without_a_close_neighbour_is_checked_without_asking_the_model(se p._run_prompty.assert_not_called() body = p._container.create_item.call_args.kwargs["body"] assert (body["id"], body["type"]) == ("dedup_cursor_u1_fact", "dedup_cursor") - assert (body["user_id"], body["thread_id"]) == ("u1", "__dedup__") + assert (body["tenant_id"], body["user_id"], body["thread_id"]) == (TENANT, "u1", "__dedup__") assert (body["last_ts"], body["ids_at_last_ts"]) == (3, ["f1"]) def test_a_fact_without_an_embedding_is_checked_without_a_neighbour_query(self): @@ -199,24 +202,27 @@ def test_a_pass_reads_active_facts_after_its_cursor_oldest_first(self): sql, params, kwargs = queries[0] assert "TOP 7" in sql and "ORDER BY c._ts ASC" in sql assert "IS_NULL(c.superseded_by)" in sql and "c.superseded_by = null" not in sql - assert (params["@user_id"], params["@after_ts"], params["@after_ids"]) == ("u1", 5, ["f0"]) - assert (params["@memory_type"], kwargs["enable_cross_partition_query"]) == ("fact", True) + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in sql + assert (params["@tenant_id"], params["@user_id"]) == (TENANT, "u1") + assert (params["@after_ts"], params["@after_ids"]) == (5, ["f0"]) + assert (params["@memory_type"], kwargs) == ("fact", {"partition_key": [TENANT, "u1"]}) replaced = p._container.replace_item.call_args.kwargs assert (replaced["item"], replaced["etag"]) == ("dedup_cursor_u1_fact", "c1") assert replaced["match_condition"] == MatchConditions.IfNotModified assert (replaced["body"]["last_ts"], replaced["body"]["ids_at_last_ts"]) == (6, ["f1"]) + assert replaced["body"]["tenant_id"] == TENANT - def test_the_cursor_document_is_read_from_the_users_dedup_partition(self): + def test_the_cursor_document_is_read_from_the_owners_partition(self): p = _make_pipeline() _run(p, []) assert p._container.read_item.call_args.kwargs == { "item": "dedup_cursor_u1_fact", - "partition_key": ["u1", "__dedup__"], + "partition_key": [TENANT, "u1"], } - def test_neighbours_are_the_nearest_active_facts_of_the_same_user(self): + def test_neighbours_are_the_nearest_active_facts_of_the_same_owner(self): p = _make_pipeline() _, queries = _run(p, [_fact("f1", "User likes coffee")]) @@ -224,8 +230,9 @@ def test_neighbours_are_the_nearest_active_facts_of_the_same_user(self): sql, params, kwargs = queries[1] assert "ORDER BY VectorDistance(c.embedding, @embedding)" in sql assert "IS_NULL(c.superseded_by)" in sql + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in sql assert (params["@seed_id"], params["@memory_type"], params["@embedding"]) == ("f1", "fact", NEAR) - assert (params["@user_id"], kwargs["enable_cross_partition_query"]) == ("u1", True) + assert (params["@tenant_id"], params["@user_id"], kwargs) == (TENANT, "u1", {"partition_key": [TENANT, "u1"]}) def test_only_neighbours_at_or_above_the_similarity_floor_reach_the_model(self): p = _make_pipeline() @@ -530,6 +537,7 @@ class TestCommitFold: @staticmethod def _build(superseded: bool | list[bool] = True) -> PipelineService: p = PipelineService.__new__(PipelineService) + p._tenant_id = TENANT p._container = MagicMock() p._memories_container = p._container p._mark_superseded = MagicMock(side_effect=superseded if isinstance(superseded, list) else None) @@ -555,6 +563,7 @@ def test_the_survivor_is_replaced_if_unchanged_before_its_duplicates_are_retired replaced = p._container.replace_item.call_args.kwargs assert (replaced["etag"], replaced["match_condition"]) == ("etag-s", MatchConditions.IfNotModified) assert replaced["body"]["merged_from"] == ["a", "b"] + assert replaced["body"]["tenant_id"] == TENANT assert [(c.args[1], c.kwargs["reason"]) for c in p._mark_superseded.call_args_list] == [ ("s", "duplicate"), ("s", "duplicate"), diff --git a/tests/unit/services/test_dedup.py b/tests/unit/services/test_dedup.py index fb6124b..4cdd17e 100644 --- a/tests/unit/services/test_dedup.py +++ b/tests/unit/services/test_dedup.py @@ -322,33 +322,40 @@ def test_the_cursor_never_moves_back_and_collects_ids_written_in_the_same_second def test_a_cursor_document_is_user_wide_and_keeps_what_it_already_holds(self): existing = {"id": "dedup_cursor_u1_fact", "extra": 1, "_etag": "e1", "_ts": 9} - body = dedup_cursor_body(existing, "u1", "fact", {"ts": 7, "ids": ["a"]}) + body = dedup_cursor_body("acme", existing, "u1", "fact", {"ts": 7, "ids": ["a"]}) assert (body["id"], body["type"]) == (dedup_cursor_id("u1", "fact"), DEDUP_CURSOR_TYPE) - assert (body["user_id"], body["thread_id"]) == ("u1", DEDUP_CURSOR_THREAD_ID) + assert (body["tenant_id"], body["user_id"], body["thread_id"]) == ("acme", "u1", DEDUP_CURSOR_THREAD_ID) assert (body["last_ts"], body["ids_at_last_ts"], body["extra"]) == (7, ["a"], 1) assert not [key for key in body if key.startswith("_")] - def test_unchecked_facts_are_the_users_active_ones_after_the_cursor_oldest_first(self): + def test_unchecked_facts_are_the_owners_active_ones_after_the_cursor_oldest_first(self): cursor = {"last_ts": 5, "ids_at_last_ts": ["f0"]} - sql, params = unchecked_memories_query("u1", "fact", cursor, 7) + sql, params = unchecked_memories_query("acme", "u1", "fact", cursor, 7) - assert "TOP 7" in sql and "ORDER BY c._ts ASC" in sql and "c.user_id = @user_id" in sql + assert ( + "TOP 7" in sql + and "ORDER BY c._ts ASC" in sql + and "c.tenant_id = @tenant_id AND c.user_id = @user_id" in sql + ) assert ACTIVE_FILTER in sql and "c.superseded_by = null" not in sql assert {p["name"]: p["value"] for p in params} == { + "@tenant_id": "acme", "@user_id": "u1", "@memory_type": "fact", "@after_ts": 5, "@after_ids": ["f0"], } - def test_neighbours_are_the_nearest_active_facts_of_the_same_user(self): - sql, params = neighbor_query("u1", "fact", {"id": "f1", "embedding": [1.0, 0.0]}) + def test_neighbours_are_the_nearest_active_facts_of_the_same_owner(self): + sql, params = neighbor_query("acme", "u1", "fact", {"id": "f1", "embedding": [1.0, 0.0]}) assert f"TOP {DEDUP_MAX_NEIGHBORS}" in sql and "ORDER BY VectorDistance(c.embedding, @embedding)" in sql - assert ACTIVE_FILTER in sql and "c.user_id = @user_id" in sql and "c.id != @seed_id" in sql + assert ACTIVE_FILTER in sql and "c.tenant_id = @tenant_id AND c.user_id = @user_id" in sql + assert "c.id != @seed_id" in sql assert {p["name"]: p["value"] for p in params} == { + "@tenant_id": "acme", "@user_id": "u1", "@memory_type": "fact", "@seed_id": "f1", diff --git a/tests/unit/services/test_episodic_retrieval.py b/tests/unit/services/test_episodic_retrieval.py index fca2130..7d1f03d 100644 --- a/tests/unit/services/test_episodic_retrieval.py +++ b/tests/unit/services/test_episodic_retrieval.py @@ -36,7 +36,7 @@ def test_get_episodes_returns_user_episodes_newest_first() -> None: ] memories = MagicMock() memories.query_items.return_value = episodes - store = MemoryStore(containers=_containers(memories=memories)) + store = MemoryStore(containers=_containers(memories=memories), tenant_id="acme") client = _client_with_store(store) result = client.get_episodes("u1", recent_k=2) @@ -44,9 +44,11 @@ def test_get_episodes_returns_user_episodes_newest_first() -> None: assert result == episodes kwargs = memories.query_items.call_args.kwargs assert "c.type = @type" in kwargs["query"] - assert "c.user_id = @user_id" in kwargs["query"] + assert "c.tenant_id = @tenant_id" in kwargs["query"] and "c.user_id = @user_id" in kwargs["query"] assert "ORDER BY c.created_at DESC" in kwargs["query"] - assert kwargs["enable_cross_partition_query"] is True + assert {"name": "@tenant_id", "value": "acme"} in kwargs["parameters"] + assert kwargs["partition_key"] == ["acme", "u1"] + assert "enable_cross_partition_query" not in kwargs def test_extract_episodes_routes_to_pipeline_with_flush() -> None: diff --git a/tests/unit/services/test_extract_dry.py b/tests/unit/services/test_extract_dry.py index 8fdc728..5436801 100644 --- a/tests/unit/services/test_extract_dry.py +++ b/tests/unit/services/test_extract_dry.py @@ -62,16 +62,34 @@ async def generate(self, text: str) -> list[float]: return [1.0] +def _in_partition(doc: dict[str, Any], partition_key: Any) -> bool: + """Whether ``doc`` sits in the partition ``[tenant_id, user_id]``. A record that names no tenant, or no user, is + taken to sit in whichever partition is asked for.""" + if not isinstance(partition_key, (list, tuple)) or len(partition_key) != 2: + return True + tenant_id, user_id = partition_key + return doc.get("tenant_id", tenant_id) == tenant_id and doc.get("user_id", user_id) == user_id + + class _Store: + """A container as the pipeline sees it. A query that names the tenant (``@tenant_id``) or a partition + (``[tenant_id, user_id]``) only answers with the records that sit there, and every query and point read is + recorded in ``queries`` and ``reads``.""" + def __init__(self, docs: list[dict[str, Any]]): self.docs = [dict(doc) for doc in docs] self.search_calls: list[dict[str, Any]] = [] self.search_results: list[dict[str, Any]] = [] + self.queries: list[tuple[str, dict[str, Any], Any]] = [] + self.reads: list[tuple[str, Any]] = [] def query(self, sql: str, parameters=None, partition_key=None, cross_partition: bool = False): - del partition_key, cross_partition + del cross_partition params = {p["name"]: p["value"] for p in (parameters or [])} - docs = [dict(doc) for doc in self.docs] + self.queries.append((sql, params, partition_key)) + docs = [dict(doc) for doc in self.docs if _in_partition(doc, partition_key)] + if "@tenant_id" in params: + docs = [doc for doc in docs if doc.get("tenant_id", params["@tenant_id"]) == params["@tenant_id"]] if "@user_id" in params: docs = [doc for doc in docs if doc.get("user_id") == params["@user_id"]] if "@thread_id" in params: @@ -132,9 +150,9 @@ def upsert_item(self, *, body: dict[str, Any]) -> dict[str, Any]: return body def read_item(self, item_id: str, partition_key: Any): - del partition_key + self.reads.append((item_id, partition_key)) for doc in self.docs: - if doc.get("id") == item_id: + if doc.get("id") == item_id and _in_partition(doc, partition_key): return dict(doc) raise CosmosResourceNotFoundError(message=item_id) @@ -843,3 +861,23 @@ def test_extract_memories_durable_clamps_out_of_range_fact_scores() -> None: assert len(output["facts"]) == 1 assert output["facts"][0]["confidence"] == 1.0 assert output["facts"][0]["salience"] == 0.0 + + +def test_extracted_facts_carry_the_tenant_and_the_same_fact_in_two_threads_has_two_ids() -> None: + memories_store = _Store([]) + turns_store = _Store([_turn(1), {**_turn(1), "thread_id": "t2"}]) + service = PipelineService( + memories_store, + _SyncChat([_response(), _response()]), + _SyncEmbeddings(), + containers=_containers_for_store(memories_store, turns_store=turns_store), + tenant_id="acme", + ) + + [first] = service.extract_memories_durable("u1", "t1")["facts"] + [second] = service.extract_memories_durable("u1", "t2")["facts"] + + assert (first["tenant_id"], first["user_id"], first["thread_id"]) == ("acme", "u1", "t1") + assert (second["tenant_id"], second["thread_id"]) == ("acme", "t2") + assert first["content_hash"] == second["content_hash"] + assert first["id"] != second["id"], "an owner's threads share one partition, so the thread is part of the id" diff --git a/tests/unit/services/test_extract_episodes.py b/tests/unit/services/test_extract_episodes.py index bef72d0..29957eb 100644 --- a/tests/unit/services/test_extract_episodes.py +++ b/tests/unit/services/test_extract_episodes.py @@ -303,3 +303,51 @@ def test_build_episode_docs_drops_whitespace_only_summary() -> None: docs = service._build_episode_docs("u1", "t1", [_turn(1), _turn(2)], segment_key="seg-1") assert docs == [] + + +def test_extract_episodes_reads_and_writes_only_inside_its_tenant(monkeypatch) -> None: + monkeypatch.setenv("EPISODE_TOPIC_DRIFT", "0") + ours = [{**_turn(1), "tenant_id": "acme"}, {**_turn(2), "tenant_id": "acme"}] + theirs = {**_turn(3), "tenant_id": "other", "content": "Another tenant's private plan."} + memories, turns, chat = _TrackingStore([]), _Store([*ours, theirs]), _SyncChat([{"episodes": [_episode()]}]) + service = PipelineService( + memories, + chat, + _SyncEmbeddings(), + containers=_containers_for_store(memories, turns_store=turns), + tenant_id="acme", + ) + + assert service.extract_episodes("u1", "t1", flush=True) == {"episodes": 1} + + assert "private plan" not in str(chat.messages) + assert turns.queries, "the open segment was read" + for sql, params, partition_key in turns.queries: + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id AND c.thread_id = @thread_id" in sql + assert (params["@tenant_id"], params["@user_id"], params["@thread_id"]) == ("acme", "u1", "t1") + assert partition_key == ["acme", "u1"] + assert memories.reads and all(partition_key == ["acme", "u1"] for _, partition_key in memories.reads) + assert {doc["type"] for doc in memories.docs} == {"episodic", "episode_cursor"} + assert {doc["tenant_id"] for doc in memories.docs} == {"acme"}, "the episode and the watermark carry the tenant" + [cursor] = [doc for doc in memories.docs if doc["type"] == "episode_cursor"] + assert (cursor["id"], cursor["user_id"], cursor["thread_id"]) == ("episode_cursor_u1_t1", "u1", "t1") + + +def test_the_same_turns_in_two_threads_make_episodes_and_watermarks_with_different_ids(monkeypatch) -> None: + monkeypatch.setenv("EPISODE_TOPIC_DRIFT", "0") + memories = _IdUniqueStore([]) + turns = _Store([_turn(1), _turn(2), {**_turn(1), "thread_id": "t2"}, {**_turn(2), "thread_id": "t2"}]) + service = PipelineService( + memories, + _SyncChat([{"episodes": [_episode()]}, {"episodes": [_episode()]}]), + _SyncEmbeddings(), + containers=_containers_for_store(memories, turns_store=turns), + ) + + assert service.extract_episodes("u1", "t1", flush=True) == {"episodes": 1} + assert service.extract_episodes("u1", "t2", flush=True) == {"episodes": 1} + + episodes = [doc for doc in memories.docs if doc["type"] == "episodic"] + cursors = [doc for doc in memories.docs if doc["type"] == "episode_cursor"] + assert {doc["thread_id"] for doc in episodes} == {"t1", "t2"} and len({doc["id"] for doc in episodes}) == 2 + assert {doc["id"] for doc in cursors} == {"episode_cursor_u1_t1", "episode_cursor_u1_t2"} diff --git a/tests/unit/services/test_extraction_context.py b/tests/unit/services/test_extraction_context.py index f389d6e..0a21fb6 100644 --- a/tests/unit/services/test_extraction_context.py +++ b/tests/unit/services/test_extraction_context.py @@ -143,7 +143,7 @@ def test_earlier_turns_of_the_same_session_are_the_ones_written_before_the_windo start = earliest_created_at(window) window_ts = window_write_second(window, start) - query, parameters = previous_turns_query("u1", "t1", start, window_ts) + query, parameters = previous_turns_query("acme", "u1", "t1", start, window_ts) assert window_ts == 103 assert "(c.created_at < @before OR (c.created_at = @before AND c._ts < @before_ts))" in query @@ -152,10 +152,22 @@ def test_earlier_turns_of_the_same_session_are_the_ones_written_before_the_windo rows = [turns[1], turns[0], turns[2]] assert [turn["id"] for turn in prior_turns(rows, window)] == ["turn-0", "turn-1", "turn-2"] assert window_write_second([{**turns[0], "_ts": None}], session) is None - strict, strict_parameters = previous_turns_query("u1", "t1", start) + strict, strict_parameters = previous_turns_query("acme", "u1", "t1", start) assert "@before_ts" not in strict and all(p["name"] != "@before_ts" for p in strict_parameters) +def test_earlier_turns_are_those_of_the_thread_of_the_owner_in_the_tenant() -> None: + query, parameters = previous_turns_query("acme", "u1", "t1", "2026-04-10T09:00:00+00:00") + + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id AND c.thread_id = @thread_id" in query + assert {p["name"]: p["value"] for p in parameters} == { + "@tenant_id": "acme", + "@user_id": "u1", + "@thread_id": "t1", + "@before": "2026-04-10T09:00:00+00:00", + } + + def test_stored_facts_show_their_date_speaker_assertion_and_keys() -> None: docs = [ { @@ -188,11 +200,12 @@ def test_stored_facts_show_their_date_speaker_assertion_and_keys() -> None: def test_stored_facts_are_active_and_never_from_after_the_new_turns() -> None: - query, parameters = known_facts_query("u1", [0.1], "2026-04-10T09:05:00+00:00", _ACTIVE_DOC_FILTER) - unbounded, unbounded_parameters = known_facts_query("u1", [0.1], None, _ACTIVE_DOC_FILTER) + query, parameters = known_facts_query("acme", "u1", [0.1], "2026-04-10T09:05:00+00:00", _ACTIVE_DOC_FILTER) + unbounded, unbounded_parameters = known_facts_query("acme", "u1", [0.1], None, _ACTIVE_DOC_FILTER) assert _ACTIVE_DOC_FILTER in query and "c.created_at <= @before" in query - assert "c.user_id = @user_id" in query and {"name": "@user_id", "value": "u1"} in parameters + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in query + assert {"name": "@tenant_id", "value": "acme"} in parameters and {"name": "@user_id", "value": "u1"} in parameters assert {"name": "@before", "value": "2026-04-10T09:05:00+00:00"} in parameters assert "@before" not in unbounded and all(p["name"] != "@before" for p in unbounded_parameters) assert query.startswith(f"SELECT TOP {context.EXTRACTION_KNOWN_FACTS} ") @@ -383,6 +396,72 @@ def test_the_extractor_sees_earlier_turns_the_summary_and_stored_facts_from_befo assert embeddings.calls == [["OK, let's do that. And from now on, always show me the migration plan first."]] +def _two_tenants() -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]]]: + """The turns, facts and thread summary of ``u1`` in tenant ``acme``, each beside a record of the same user id in + tenant ``other`` that the extractor must never see (the summary shares its id).""" + theirs = { + "turn": {**_stored_turn(2, "Another tenant's earlier turn."), "tenant_id": "other"}, + "fact": {**_fact("f-theirs", "Another tenant's fact.", "2026-03-02T10:00:00+00:00"), "tenant_id": "other"}, + "summary": {**_summary("2026-04-10T09:04:30+00:00"), "user_id": "u1", "tenant_id": "other"}, + } + theirs["summary"]["metadata"] = {"structured_summary": {"overview": "Another tenant's plan."}} + ours_summary = {**_summary("2026-04-10T09:04:30+00:00"), "user_id": "u1", "tenant_id": "acme"} + return ( + [*_turns(), theirs["turn"]], + [*_memories(), theirs["fact"]], + [theirs["summary"], ours_summary], + ) + + +def _assert_context_read_inside(tenant: str, turns: Any, memories: Any, summaries: Any, message: str) -> None: + assert "Another tenant" not in message + assert _section(message, "Thread summary").startswith("Overview: Planning the events table migration.") + assert len(turns.queries) == 2 and len(memories.queries) == 1, "the new turns, the earlier ones, the stored facts" + for store in (turns, memories): + for sql, params, partition_key in store.queries: + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in sql + assert (params["@tenant_id"], params["@user_id"]) == (tenant, "u1") + assert partition_key == [tenant, "u1"] + assert summaries.reads == [("summary_u1_t1", [tenant, "u1"])] + + +def test_the_extraction_context_is_read_inside_the_tenant() -> None: + chat, embeddings = _SyncChat([_v3_response()]), _SyncEmbeddings() + turn_docs, fact_docs, summary_docs = _two_tenants() + turns, memories, summaries = _Store(turn_docs), _Store(fact_docs), _Store(summary_docs) + service = PipelineService( + memories, + chat, + embeddings, + containers=_containers_for_store(memories, turns_store=turns, summaries_store=summaries), + tenant_id="acme", + ) + + extracted = service.extract_memories_durable("u1", "t1") + + _assert_context_read_inside("acme", turns, memories, summaries, _user_message(chat)) + assert extracted["facts"] and {doc["tenant_id"] for doc in extracted["facts"]} == {"acme"} + + +@pytest.mark.asyncio +async def test_async_the_extraction_context_is_read_inside_the_tenant() -> None: + chat, embeddings = _AsyncChat([_v3_response()]), _AsyncEmbeddings() + turn_docs, fact_docs, summary_docs = _two_tenants() + turns, memories, summaries = _AsyncStore(turn_docs), _AsyncStore(fact_docs), _AsyncStore(summary_docs) + service = AsyncPipelineService( + memories, + chat, + embeddings, + containers=_async_containers_for_store(memories, turns_store=turns, summaries_store=summaries), + tenant_id="acme", + ) + + extracted = await service.extract_memories_durable("u1", "t1") + + _assert_context_read_inside("acme", turns, memories, summaries, _user_message(chat)) + assert extracted["facts"] and {doc["tenant_id"] for doc in extracted["facts"]} == {"acme"} + + def test_a_summary_covering_the_new_turns_is_left_out() -> None: service, chat = _sync_service(summary_at=_WINDOW_START) diff --git a/tests/unit/services/test_mark_turns_extracted.py b/tests/unit/services/test_mark_turns_extracted.py index ca07c65..fc833ea 100644 --- a/tests/unit/services/test_mark_turns_extracted.py +++ b/tests/unit/services/test_mark_turns_extracted.py @@ -6,6 +6,8 @@ from azure.cosmos.agent_memory.services.pipeline import PipelineService, _StoreContainerAdapter from tests.unit.services.test_extract_dry import _Store, _SyncChat, _SyncEmbeddings +TENANT = "acme" + class _PatchTurnsContainer: def __init__(self, docs: list[dict[str, Any]]): @@ -61,6 +63,7 @@ def __init__(self, container: Any): def _turn_doc(**overrides: Any) -> dict[str, Any]: doc = { "id": "turn-1", + "tenant_id": TENANT, "user_id": "u1", "thread_id": "t1", "type": "turn", @@ -84,6 +87,7 @@ def _service(turns_container: Any) -> PipelineService: ContainerKey.MEMORIES: _StoreContainerAdapter(memories_store, ContainerKey.MEMORIES), ContainerKey.SUMMARIES: _StoreContainerAdapter(summaries_store, ContainerKey.SUMMARIES), }, + tenant_id=TENANT, ) @@ -97,7 +101,7 @@ def test_mark_turns_extracted_patches_extracted_at() -> None: assert turns_container.patch_calls == [ { "item": "turn-1", - "partition_key": ["u1", "t1"], + "partition_key": [TENANT, "u1"], "patch_operations": [ {"op": "set", "path": "/extracted_at", "value": turns_container.docs[0]["extracted_at"]} ], @@ -107,6 +111,15 @@ def test_mark_turns_extracted_patches_extracted_at() -> None: assert turns_container.upsert_calls == [] +def test_mark_turns_extracted_only_addresses_the_partition_of_its_own_tenant() -> None: + turns_container = _PatchTurnsContainer([_turn_doc(), _turn_doc(id="turn-2", tenant_id="other", thread_id="t2")]) + service = _service(turns_container) + + service._mark_turns_extracted([_turn_doc(), _turn_doc(id="turn-2", tenant_id="other", thread_id="t2")]) + + assert [call["partition_key"] for call in turns_container.patch_calls] == [[TENANT, "u1"], [TENANT, "u1"]] + + def test_mark_turns_extracted_falls_back_to_read_modify_upsert() -> None: turns_container = _NoPatchTurnsContainer([_turn_doc()]) service = _service(turns_container) diff --git a/tests/unit/services/test_persist_extracted.py b/tests/unit/services/test_persist_extracted.py index 928f2f4..4f7d135 100644 --- a/tests/unit/services/test_persist_extracted.py +++ b/tests/unit/services/test_persist_extracted.py @@ -10,6 +10,7 @@ from azure.cosmos.agent_memory._container_routing import ContainerKey from azure.cosmos.agent_memory._utils import compute_content_hash from azure.cosmos.agent_memory.aio.services.pipeline import AsyncPipelineService, _AsyncStoreContainerAdapter +from azure.cosmos.agent_memory.exceptions import ValidationError from azure.cosmos.agent_memory.services._pipeline_helpers import ID_SEED_SEP from azure.cosmos.agent_memory.services.pipeline import PipelineService, _StoreContainerAdapter @@ -304,3 +305,81 @@ async def test_async_persist_extracted_memories_episodic_creates_not_upserts_and assert second["episodic_count"] == 0 assert container.created_ids == [doc["id"]] assert store.upserts == [] + + +def test_persist_extracted_memories_creates_every_record_in_its_tenant() -> None: + container = _Container() + store = _Store(container) + service = PipelineService( + store, + chat_client=object(), + embeddings_client=_Embeddings(), + containers=_containers_for_store(store), + tenant_id="acme", + ) + fact, episode = _fact_doc(), _episodic_doc() + + service.persist_extracted_memories("u1", {"facts": [fact], "episodic": [episode], "updates": []}) + + assert set(container.docs) == {fact["id"], episode["id"]} + assert {doc["tenant_id"] for doc in container.docs.values()} == {"acme"} + assert "tenant_id" not in fact, "the caller's document is not rewritten" + + +def test_persist_extracted_memories_refuses_a_record_of_another_tenant_and_writes_nothing() -> None: + container = _Container() + store = _Store(container) + service = PipelineService( + store, + chat_client=object(), + embeddings_client=_Embeddings(), + containers=_containers_for_store(store), + tenant_id="acme", + ) + ours = _fact_doc("The user prefers dark mode.") + theirs = {**_fact_doc("The user prefers concise answers."), "tenant_id": "other"} + + with pytest.raises(ValidationError, match="different tenant"): + service.persist_extracted_memories("u1", {"facts": [ours, theirs], "episodic": [], "updates": []}) + + assert container.created_ids == [] + + +@pytest.mark.asyncio +async def test_async_persist_extracted_memories_creates_every_record_in_its_tenant() -> None: + container = _AsyncContainer() + store = _AsyncStore(container) + service = AsyncPipelineService( + store, + chat_client=object(), + embeddings_client=_AsyncEmbeddings(), + containers=_async_containers_for_store(store), + tenant_id="acme", + ) + fact, episode = _fact_doc(), _episodic_doc() + + await service.persist_extracted_memories("u1", {"facts": [fact], "episodic": [episode], "updates": []}) + + assert set(container.docs) == {fact["id"], episode["id"]} + assert {doc["tenant_id"] for doc in container.docs.values()} == {"acme"} + assert "tenant_id" not in fact + + +@pytest.mark.asyncio +async def test_async_persist_extracted_memories_refuses_a_record_of_another_tenant_and_writes_nothing() -> None: + container = _AsyncContainer() + store = _AsyncStore(container) + service = AsyncPipelineService( + store, + chat_client=object(), + embeddings_client=_AsyncEmbeddings(), + containers=_async_containers_for_store(store), + tenant_id="acme", + ) + ours = _fact_doc("The user prefers dark mode.") + theirs = {**_fact_doc("The user prefers concise answers."), "tenant_id": "other"} + + with pytest.raises(ValidationError, match="different tenant"): + await service.persist_extracted_memories("u1", {"facts": [ours, theirs], "episodic": [], "updates": []}) + + assert container.created_ids == [] diff --git a/tests/unit/services/test_pipeline_service.py b/tests/unit/services/test_pipeline_service.py index a67f6a0..85b84a2 100644 --- a/tests/unit/services/test_pipeline_service.py +++ b/tests/unit/services/test_pipeline_service.py @@ -8,6 +8,8 @@ from azure.cosmos.exceptions import CosmosResourceExistsError from azure.cosmos.agent_memory._container_routing import ContainerKey +from azure.cosmos.agent_memory._partitioning import DEFAULT_TENANT_ID +from azure.cosmos.agent_memory.exceptions import ValidationError from azure.cosmos.agent_memory.services.pipeline import PipelineService, _StoreContainerAdapter @@ -48,10 +50,15 @@ def generate(self, text: str) -> list[float]: class FakeStore: + """A container. Every query and point read is recorded (``queries``, ``reads``) with the partition it named; a + query that names the tenant only answers with that tenant's records.""" + def __init__(self, docs: list[dict[str, Any]] | None = None): self.docs = [dict(doc) for doc in (docs or [])] self.upserts: list[dict[str, Any]] = [] self.supersede_calls: list[tuple[str, str, str]] = [] + self.queries: list[tuple[str, dict[str, Any], Any]] = [] + self.reads: list[tuple[str, Any]] = [] def query( self, @@ -60,12 +67,14 @@ def query( partition_key: Any = None, cross_partition: bool = False, ) -> list[dict[str, Any]]: - del partition_key, cross_partition + del cross_partition params = {p["name"]: p["value"] for p in (parameters or [])} + self.queries.append((sql, params, partition_key)) docs = [dict(doc) for doc in self.docs] - uid = params.get("@user_id", params.get("@uid")) - if uid is not None: - docs = [doc for doc in docs if doc.get("user_id") == uid] + if "@tenant_id" in params: + docs = [doc for doc in docs if doc.get("tenant_id", params["@tenant_id"]) == params["@tenant_id"]] + if "@user_id" in params: + docs = [doc for doc in docs if doc.get("user_id") == params["@user_id"]] if "@thread_id" in params: docs = [doc for doc in docs if doc.get("thread_id") == params["@thread_id"]] if "@type" in params: @@ -107,9 +116,9 @@ def query( return docs def read_item(self, item_id: str, partition_key: Any) -> dict[str, Any]: - del partition_key + self.reads.append((item_id, partition_key)) for doc in self.docs: - if doc.get("id") == item_id: + if doc.get("id") == item_id and doc.get("tenant_id", partition_key[0]) == partition_key[0]: return dict(doc) from azure.cosmos.exceptions import CosmosResourceNotFoundError @@ -162,12 +171,14 @@ def _pipeline( *, turns_store: FakeStore | None = None, summaries_store: FakeStore | None = None, + tenant_id: str = DEFAULT_TENANT_ID, ) -> PipelineService: return PipelineService( memories_store, llm.chat_client, llm.embeddings_client, containers=_containers_for_store(memories_store, turns_store=turns_store, summaries_store=summaries_store), + tenant_id=tenant_id, ) @@ -313,7 +324,7 @@ def test_thread_summary_persists_to_summaries_container() -> None: ContainerKey.SUMMARIES: summaries_container, } embeddings = FakeLLMService([]).embeddings_client - service = PipelineService(FakeStore(), object(), embeddings, containers=containers) + service = PipelineService(FakeStore(), object(), embeddings, containers=containers, tenant_id="acme") summary_doc = { "id": "summary_u1_t1", "user_id": "u1", @@ -334,10 +345,15 @@ def test_thread_summary_persists_to_summaries_container() -> None: assert stored["type"] == "thread_summary" summaries_container.upsert_item.assert_called_once() - assert summaries_container.upsert_item.call_args.kwargs["body"]["id"] == "summary_u1_t1" + written = summaries_container.upsert_item.call_args.kwargs["body"] + assert (written["id"], written["tenant_id"]) == ("summary_u1_t1", "acme") memories_container.method_calls == [] turns_container.method_calls == [] + with pytest.raises(ValidationError, match="different tenant"): + service.persist_thread_summary("u1", "t1", {**summary_doc, "tenant_id": "other"}) + summaries_container.upsert_item.assert_called_once() + def test_generate_thread_and_user_summary_basic_shape() -> None: store = FakeStore() @@ -365,7 +381,77 @@ def test_generate_thread_and_user_summary_basic_shape() -> None: assert llm.embed_one_calls == ["Thread discussed retries.", "The project needs retries."] +def test_summaries_are_read_and_written_in_the_owners_partition_of_the_tenant() -> None: + owner = [{"tenant_id": "acme"}, {"tenant_id": "other"}] + turns_store = FakeStore( + [ + {**_turn("We decided to add retries."), **owner[0]}, + {**_turn("Another tenant's plan."), **owner[1]}, + ] + ) + memories = FakeStore([{**_fact("f1", "The project needs retries."), **owner[0]}]) + memories.docs.append({**_fact("f2", "Another tenant's fact."), **owner[1]}) + summaries_store = FakeStore([{"id": "summary_u1_t1", "type": "thread_summary", "tenant_id": "other"}]) + llm = FakeLLMService( + [ + {"overview": "Thread discussed retries.", "topics": ["retries"]}, + {"key_facts": ["The project needs retries."], "open_questions": []}, + ] + ) + service = _pipeline(memories, llm, turns_store=turns_store, summaries_store=summaries_store, tenant_id="acme") + + thread_summary = service.generate_thread_summary("u1", "t1") + user_summary = service.generate_user_summary("u1") + + assert "Another tenant" not in str(llm.chat_calls) + assert (thread_summary["tenant_id"], user_summary["tenant_id"]) == ("acme", "acme") + for store in (turns_store, memories, summaries_store): + assert store.queries + for sql, params, partition_key in store.queries: + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in sql + assert (params["@tenant_id"], params["@user_id"]) == ("acme", "u1") + assert partition_key == ["acme", "u1"] + assert summaries_store.reads == [("summary_u1_t1", ["acme", "u1"]), ("user_summary_u1", ["acme", "u1"])] + assert [doc["id"] for doc in summaries_store.upserts] == ["summary_u1_t1", "user_summary_u1"] + assert {doc["tenant_id"] for doc in summaries_store.upserts} == {"acme"} + + +def test_the_threads_of_one_owner_have_summaries_with_different_ids() -> None: + turns_store = FakeStore([_turn("In thread one."), {**_turn("In thread two."), "id": "turn2", "thread_id": "t2"}]) + summaries_store = FakeStore() + llm = FakeLLMService([{"overview": "One."}, {"overview": "Two."}]) + service = _pipeline(FakeStore(), llm, turns_store=turns_store, summaries_store=summaries_store) + + first = service.generate_thread_summary("u1", "t1") + second = service.generate_thread_summary("u1", "t2") + + assert (first["id"], second["id"]) == ("summary_u1_t1", "summary_u1_t2") + assert {doc["id"] for doc in summaries_store.docs} == {"summary_u1_t1", "summary_u1_t2"} + + def test_build_procedural_context_requires_user_id() -> None: with pytest.raises(Exception, match="user_id is required"): fake = FakeLLMService([]) _pipeline(FakeStore(), fake).build_procedural_context("") + + +def test_a_pipeline_without_a_tenant_works_in_the_default_one() -> None: + llm = FakeLLMService([]) + memories = FakeStore() + service = PipelineService( + memories, + llm.chat_client, + llm.embeddings_client, + containers=_containers_for_store(memories), + ) + + service.build_procedural_context("u1") + + (_, params, partition_key), *_ = memories.queries + assert (params["@tenant_id"], partition_key) == (DEFAULT_TENANT_ID, [DEFAULT_TENANT_ID, "u1"]) + + +@pytest.mark.parametrize("tenant_id", ["", " ", "a/b", "a?b", "a#b", "a\\b", "a" * 257, 7]) +def test_a_pipeline_refuses_a_tenant_id_that_is_not_valid(tenant_id) -> None: + with pytest.raises(ValidationError, match="tenant_id"): + _pipeline(FakeStore(), FakeLLMService([]), tenant_id=tenant_id) diff --git a/tests/unit/services/test_procedural_synthesis_and_context.py b/tests/unit/services/test_procedural_synthesis_and_context.py index 8c4fcf6..51441e3 100644 --- a/tests/unit/services/test_procedural_synthesis_and_context.py +++ b/tests/unit/services/test_procedural_synthesis_and_context.py @@ -31,15 +31,18 @@ from azure.cosmos.agent_memory.services.pipeline import PipelineService from azure.cosmos.agent_memory.store import MemoryStore -PROCEDURAL_PARTITION = ["u1", "__procedural__"] +TENANT = "acme" +OWNER_PARTITION = [TENANT, "u1"] def procedural_rows(docs: list[dict[str, Any]], sql: str, parameters: Any) -> list[dict[str, Any]]: """The rows the procedure pass and the procedural context read, as Cosmos DB would return them.""" params = {p["name"]: p["value"] for p in (parameters or [])} rows = [dict(doc) for doc in docs] - if "@uid" in params: - rows = [row for row in rows if row.get("user_id") == params["@uid"]] + if "@tenant_id" in params: + rows = [row for row in rows if row.get("tenant_id") == params["@tenant_id"]] + if "@user_id" in params: + rows = [row for row in rows if row.get("user_id") == params["@user_id"]] memory_type = params.get("@type", params.get("@memory_type")) if memory_type is not None: rows = [row for row in rows if row.get("type") == memory_type] @@ -79,31 +82,25 @@ def _is_behavioral(row: dict[str, Any], min_salience: float) -> bool: class Memories: - """The memories container as the procedure pass sees it: a query names the partition it reads (or opts in to - reading them all), and a conditional write must name the version it read.""" + """The memories container as the procedure pass sees it: a query names the owner's partition, ``[tenant_id, + user_id]`` (all of an owner's records share it, whatever their thread), and a conditional write must name the + version it read. Every query is recorded.""" def __init__(self, docs: list[dict[str, Any]]) -> None: self.docs = [dict(doc) for doc in docs] + self.queries: list[tuple[str, dict[str, Any], list[Any]]] = [] self._versions = itertools.count(1) @staticmethod def _partition(doc: dict[str, Any]) -> list[Any]: - return [doc.get("user_id"), doc.get("thread_id")] - - def query_items( - self, - *, - query: str, - parameters: Any = None, - partition_key: Any = None, - enable_cross_partition_query: bool = False, - ) -> list[dict[str, Any]]: - if partition_key is None and not enable_cross_partition_query: - raise AssertionError("a query over every partition must say so") + return [doc.get("tenant_id"), doc.get("user_id")] + + def query_items(self, *, query: str, parameters: Any = None, partition_key: Any = None) -> list[dict[str, Any]]: + if partition_key is None: + raise AssertionError("a query must name the partition of one owner") + self.queries.append((query, {p["name"]: p["value"] for p in parameters or []}, list(partition_key))) rows = procedural_rows(self.docs, query, parameters) - if partition_key is not None: - rows = [row for row in rows if self._partition(row) == list(partition_key)] - return rows + return [row for row in rows if self._partition(row) == list(partition_key)] def read_item(self, *, item: str, partition_key: Any) -> dict[str, Any]: for doc in self.docs: @@ -121,7 +118,7 @@ def create_item(self, *, body: dict[str, Any]) -> dict[str, Any]: def replace_item(self, *, item: str, body: dict[str, Any], etag: Any = None, match_condition: Any = None) -> dict: del match_condition for index, doc in enumerate(self.docs): - if doc.get("id") == item: + if doc.get("id") == item and self._partition(doc) == self._partition(body): if etag is not None and doc.get("_etag") != etag: raise CosmosAccessConditionFailedError(status_code=412, message=f"{item} changed") self.docs[index] = {**body, "_etag": f"etag-{next(self._versions)}"} @@ -165,8 +162,8 @@ def _service( memories: Memories, responses: list[Any], vectors: dict[str, list[float]] | None = None ) -> tuple[PipelineService, Chat]: chat, embeddings, containers = Chat(responses), Embeddings(vectors), containers_for(memories) - store = MemoryStore(containers=containers, embeddings_client=embeddings) - return PipelineService(store, chat, embeddings, containers=containers), chat + store = MemoryStore(containers=containers, embeddings_client=embeddings, tenant_id=TENANT) + return PipelineService(store, chat, embeddings, containers=containers, tenant_id=TENANT), chat def prompt_text(chat: Any, call: int) -> str: @@ -211,9 +208,11 @@ def fact( agent: bool = False, assertion: str | None = None, user_id: str = "u1", + tenant_id: str = TENANT, ) -> dict[str, Any]: doc = { "id": fid, + "tenant_id": tenant_id, "user_id": user_id, "thread_id": "t1", "type": "fact", @@ -240,6 +239,7 @@ def directive(fid: str = "fact-raw-1", *, assertion: str = "directive", **kwargs def episode(eid: str = "episode-raw-1", *, ts: int = 2, day: str = "2025-01-01", status: str = "successful") -> dict: return { "id": eid, + "tenant_id": TENANT, "user_id": "u1", "thread_id": "t1", "type": "episodic", @@ -309,6 +309,7 @@ def procedure(name: str = "Run targeted tests", *, kind: str = "instruction", ** """An existing procedure the pass may show, revise or reinforce.""" return { "id": procedure_id("u1", kind, name), + "tenant_id": TENANT, "user_id": "u1", "type": "procedural", "thread_id": "__procedural__", @@ -365,7 +366,12 @@ def test_a_taught_instruction_is_active_with_its_support_recorded() -> None: assert (created["source_fact_ids"], created["source_episodic_ids"]) == (["fact-raw-1"], []) assert (created["source_kind"], created["source_authority"]) == ("explicit_user_instruction", "high") assert created["id"] == procedure_id("u1", "instruction", "Run targeted tests") - assert (created["user_id"], created["thread_id"], created["role"]) == ("u1", "__procedural__", "system") + assert (created["tenant_id"], created["user_id"], created["thread_id"], created["role"]) == ( + TENANT, + "u1", + "__procedural__", + "system", + ) assert (created["embedding"], created["utility_score"], created["version"]) == ([1.0], 0.8, 1) assert (created["prompt_id"], created["prompt_version"]) == ("extract_procedure.prompty", "v6") assert created["tags"] == ["sys:auto-extracted", "sys:procedural"] @@ -494,6 +500,23 @@ def test_an_update_revises_a_procedure_in_place() -> None: assert revised["embedding"] == [1.0] +def test_a_procedure_with_the_same_id_in_another_tenant_is_neither_read_nor_replaced() -> None: + """A procedure's id derives from the user, its kind and its name, so two tenants hold the same id.""" + mine, theirs = procedure(), {**procedure(), "tenant_id": "other", "summary": "Their rule."} + memories = Memories([mine, theirs, fact("fact-new", "The user wants the test command shown.", ts=5)]) + revision = answer(action="update", updates="proc-1", summary="Run tests; show the command.") + service, chat = _service(memories, [{"procedures": [revision]}]) + + result = service.synthesize_procedural("u1") + + assert result["procedures_updated"] == 1 + assert "Their rule." not in prompt_text(chat, 0) + mine_now = next(doc for doc in memories.docs if doc["id"] == mine["id"] and doc["tenant_id"] == TENANT) + theirs_now = next(doc for doc in memories.docs if doc["id"] == mine["id"] and doc["tenant_id"] == "other") + assert (mine_now["version"], mine_now["summary"]) == (2, "Run tests; show the command.") + assert theirs_now == theirs + + @pytest.mark.parametrize( ("source", "evidence", "revised"), [ @@ -715,19 +738,53 @@ def test_the_users_nearest_existing_procedures_are_shown_so_the_model_can_revise assert "(none)" not in prompt_text(chat, 0).split("## Existing procedures")[1] -def test_procedures_and_the_cursor_live_in_the_users_procedural_partition() -> None: +def test_procedures_and_the_cursor_live_in_the_owners_partition() -> None: memories = Memories([fact(), fact("fact-theirs", "Their rule.", user_id="u2")]) service, _ = _service(memories, [{"procedures": [answer()]}]) service.synthesize_procedural("u1") created = procedures_by_name(memories)["Run targeted tests"] - assert memories.read_item(item=created["id"], partition_key=PROCEDURAL_PARTITION)["name"] == created["name"] - cursor = memories.read_item(item="procedure_cursor", partition_key=PROCEDURAL_PARTITION) - assert (cursor["type"], cursor["user_id"], cursor["thread_id"]) == ("procedure_cursor", "u1", "__procedural__") + assert memories.read_item(item=created["id"], partition_key=OWNER_PARTITION)["name"] == created["name"] + cursor = memories.read_item(item="procedure_cursor", partition_key=OWNER_PARTITION) + assert (cursor["type"], cursor["tenant_id"], cursor["user_id"], cursor["thread_id"]) == ( + "procedure_cursor", + TENANT, + "u1", + "__procedural__", + ) assert not any(doc["user_id"] == "u2" and doc.get("type") != "fact" for doc in memories.docs) +def test_every_query_of_the_procedure_pass_filters_on_the_tenant_and_reads_the_owners_partition() -> None: + memories = Memories([fact(), episode(), procedure("Existing")]) + service, _ = _service(memories, [{"procedures": [answer()]}]) + + service.synthesize_procedural("u1") + + assert len(memories.queries) >= 3 + for sql, params, partition in memories.queries: + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in sql + assert (params["@tenant_id"], params["@user_id"], partition) == (TENANT, "u1", OWNER_PARTITION) + + +def test_the_procedure_pass_stays_inside_its_tenant() -> None: + theirs = [ + fact("fact-theirs", "Another tenant's rule for the same user id.", tenant_id="other"), + {**procedure("Theirs"), "tenant_id": "other"}, + ] + memories = Memories([fact(), *theirs]) + service, chat = _service(memories, [{"procedures": [answer()]}]) + + service.synthesize_procedural("u1") + + assert "Another tenant" not in prompt_text(chat, 0) and "Theirs" not in prompt_text(chat, 0) + written = [doc for doc in memories.docs if doc["id"] not in {"fact-raw-1", "fact-theirs", theirs[1]["id"]}] + assert {doc["type"] for doc in written} == {"procedural", "procedure_cursor"} + assert {doc["tenant_id"] for doc in written} == {TENANT} + assert [doc for doc in memories.docs if doc["tenant_id"] == "other"] == theirs + + # --------------------------------------------------------------------------- # The cursor # --------------------------------------------------------------------------- @@ -1065,6 +1122,7 @@ def test_synthesize_procedural_requires_a_user() -> None: def rule(name: str, *, applies: str = "always", evidence: tuple[str, ...] = ("taught",), **extra: Any) -> dict: return { "id": f"proc-{name}", + "tenant_id": TENANT, "user_id": "u1", "type": "procedural", "thread_id": "__procedural__", @@ -1107,6 +1165,27 @@ def test_build_procedural_context_lists_the_standing_rules_in_force() -> None: assert service.build_procedural_context("missing-user") == "" +def test_build_procedural_context_reads_only_its_tenants_rules() -> None: + memories = Memories( + [rule("Mine"), rule("Reviews", applies="when", embedding=[0.0, 1.0]), {**rule("Theirs"), "tenant_id": "other"}] + ) + service, _ = _service(memories, [], vectors={"review": [0.0, 1.0]}) + + context = service.build_procedural_context("u1", task="review") + + assert context.splitlines() == [ + STANDING_HEADER, + "- Mine rule.", + "", + SITUATIONAL_HEADER, + "- When working on Reviews: Reviews rule.", + ] + assert len(memories.queries) == 2 + for sql, params, partition in memories.queries: + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in sql + assert (params["@tenant_id"], params["@user_id"], partition) == (TENANT, "u1", OWNER_PARTITION) + + def test_build_procedural_context_leaves_out_rules_written_before_procedures_were_learned_from_evidence() -> None: legacy = { key: value for key, value in rule("Legacy", procedure_kind="behavioral_policy").items() if key != "applies" diff --git a/tests/unit/services/test_procedures.py b/tests/unit/services/test_procedures.py index e9119b6..f8049cb 100644 --- a/tests/unit/services/test_procedures.py +++ b/tests/unit/services/test_procedures.py @@ -18,18 +18,22 @@ in_force, is_user_correction, lesson_episodes_query, + new_procedure, procedural_context, procedure_cursor_body, procedure_id, procedure_status, procedure_text, rank_related, + related_procedure_query, rendered_rule, retirable_facts, revised_procedure, + situational_rule_query, source_batches, sources_input, standing_rules, + standing_rules_query, with_support, ) @@ -428,7 +432,7 @@ def test_a_source_or_procedure_that_spans_lines_is_shown_on_one_but_stored_and_c def test_the_pass_reads_directives_and_corrections_whatever_their_category_or_salience(): - query, _ = behavioral_facts_query(ProcedureScope("u1"), None) + query, _ = behavioral_facts_query(ProcedureScope("acme", "u1"), None) assert "c.assertion IN ('directive', 'correction')" in query @@ -595,12 +599,13 @@ def test_the_cursor_advances_to_the_last_memory_read_of_each_kind(): def test_the_cursor_body_keeps_what_the_stored_one_holds_and_drops_system_fields(): existing = {"id": "procedure_cursor", "_etag": "e", "_ts": 3, "note": "kept"} - body = procedure_cursor_body(existing, ProcedureScope("u1"), {"ts": 9, "ids": ["f2"]}, {"ts": 4, "ids": []}) + body = procedure_cursor_body(existing, ProcedureScope("acme", "u1"), {"ts": 9, "ids": ["f2"]}, {"ts": 4, "ids": []}) assert body["note"] == "kept" - assert {key: body[key] for key in ("id", "type", "user_id", "thread_id")} == { + assert {key: body[key] for key in ("id", "type", "tenant_id", "user_id", "thread_id")} == { "id": "procedure_cursor", "type": "procedure_cursor", + "tenant_id": "acme", "user_id": "u1", "thread_id": "__procedural__", } @@ -609,18 +614,43 @@ def test_the_cursor_body_keeps_what_the_stored_one_holds_and_drops_system_fields assert not {"_etag", "_ts"} & set(body) -def test_the_source_queries_read_after_the_cursor_within_the_users_memories(): +def test_the_source_queries_read_after_the_cursor_within_the_owners_partition(): cursor = {"facts": {"last_ts": 5, "ids_at_last_ts": ["f1"]}, "episodes": {"last_ts": 8, "ids_at_last_ts": ["e1"]}} - scope = ProcedureScope("u1") + scope = ProcedureScope("acme", "u1") fact_query, fact_parameters = behavioral_facts_query(scope, cursor) episode_query, episode_parameters = lesson_episodes_query(scope, cursor) - assert scope.partition_key == ["u1", "__procedural__"] + assert scope.partition_key == ["acme", "u1"] for query in (fact_query, episode_query): - assert "c.user_id = @uid" in query + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in query assert query.endswith(AFTER_POSITION), "the window is the one dedup reads its cursor with" assert ACTIVE_FILTER in query assert {p["name"]: p["value"] for p in fact_parameters}["@after_ts"] == 5 assert {p["name"]: p["value"] for p in episode_parameters}["@after_ts"] == 8 assert {p["name"]: p["value"] for p in episode_parameters}["@type"] == "episodic" + + +def test_every_procedure_query_filters_on_the_tenant_and_the_owner(): + scope = ProcedureScope("acme", "u1") + queries = [ + behavioral_facts_query(scope, None), + lesson_episodes_query(scope, None), + related_procedure_query(scope, [1.0]), + standing_rules_query(scope, "2025-01-01"), + situational_rule_query(scope, [1.0], "2025-01-01"), + ] + + for query, parameters in queries: + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in query + named = {p["name"]: p["value"] for p in parameters} + assert (named["@tenant_id"], named["@user_id"]) == ("acme", "u1") + + +def test_a_new_procedure_belongs_to_the_tenant_and_owner_it_is_written_for(): + answer = ProcedureAnswer("add", "instruction", "taught", "Run tests", (), None, {"summary": "Run the tests."}) + + created = new_procedure(answer, tenant_id="acme", user_id="u1", now="2025-01-01T00:00:00+00:00") + + assert (created["tenant_id"], created["user_id"], created["thread_id"]) == ("acme", "u1", "__procedural__") + assert created["id"] == procedure_id("u1", "instruction", "Run tests") diff --git a/tests/unit/services/test_reconcile_passes.py b/tests/unit/services/test_reconcile_passes.py index dc9e786..14eae78 100644 --- a/tests/unit/services/test_reconcile_passes.py +++ b/tests/unit/services/test_reconcile_passes.py @@ -21,6 +21,7 @@ from azure.cosmos.agent_memory.services.pipeline import PipelineService NEAR = [1.0, 0.0, 0.0] +TENANT = "acme" NO_DEDUP = dedup_result(checked=0, retired_seeds=0, merged=0, compared=0, vetoed=0) RESULT_KEYS = { "kept", @@ -44,6 +45,7 @@ def _dedup_only(monkeypatch): def _fact(fid: str, content: str, *, vector=None, ts: int = 1, created_at: str = "2024-01-01T00:00:00+00:00") -> dict: doc = { "id": fid, + "tenant_id": TENANT, "user_id": "u1", "thread_id": "t1", "type": "fact", @@ -89,6 +91,7 @@ def mark_superseded(self, doc, superseder_id, *, reason): def _make_pipeline(store: _Store, replies: list[dict]) -> PipelineService: p = PipelineService.__new__(PipelineService) + p._tenant_id = TENANT p._container = MagicMock() p._container.query_items.side_effect = store.query_items p._container.read_item.side_effect = CosmosResourceNotFoundError(message="no dedup cursor yet") diff --git a/tests/unit/services/test_secret_redaction_writes.py b/tests/unit/services/test_secret_redaction_writes.py index 68139aa..5707272 100644 --- a/tests/unit/services/test_secret_redaction_writes.py +++ b/tests/unit/services/test_secret_redaction_writes.py @@ -17,6 +17,7 @@ from azure.cosmos.agent_memory._utils import compute_content_hash from azure.cosmos.agent_memory.aio.services.pipeline import AsyncPipelineService from azure.cosmos.agent_memory.aio.store import AsyncMemoryStore +from azure.cosmos.agent_memory.exceptions import ValidationError from azure.cosmos.agent_memory.services._pipeline_helpers import ID_SEED_SEP from azure.cosmos.agent_memory.services.pipeline import PipelineService from azure.cosmos.agent_memory.store import MemoryStore @@ -37,6 +38,7 @@ _SyncEmbeddings, _turn, ) +from tests.unit.services.test_procedural_synthesis_and_context import TENANT as PROCEDURE_TENANT from tests.unit.services.test_procedural_synthesis_and_context import Chat as ProcedureChat from tests.unit.services.test_procedural_synthesis_and_context import Embeddings as ProcedureEmbeddings from tests.unit.services.test_procedural_synthesis_and_context import Memories as ProcedureMemories @@ -265,7 +267,11 @@ def test_a_synthesized_procedure_is_redacted_before_it_is_embedded() -> None: chat = ProcedureChat([{"procedures": [procedure_answer(summary=_procedure_summary())]}]) containers = procedure_containers(memories) service = PipelineService( - MemoryStore(containers=containers, embeddings_client=embeddings), chat, embeddings, containers=containers + MemoryStore(containers=containers, embeddings_client=embeddings, tenant_id=PROCEDURE_TENANT), + chat, + embeddings, + containers=containers, + tenant_id=PROCEDURE_TENANT, ) assert service.synthesize_procedural("u1")["procedures_created"] == 1 @@ -282,7 +288,11 @@ async def test_async_a_synthesized_procedure_is_redacted_before_it_is_embedded() chat = AsyncProcedureChat([{"procedures": [procedure_answer(summary=_procedure_summary())]}]) containers = procedure_containers(AsyncProcedureMemories(memories)) service = AsyncPipelineService( - AsyncMemoryStore(containers=containers, embeddings_client=embeddings), chat, embeddings, containers=containers + AsyncMemoryStore(containers=containers, embeddings_client=embeddings, tenant_id=PROCEDURE_TENANT), + chat, + embeddings, + containers=containers, + tenant_id=PROCEDURE_TENANT, ) assert (await service.synthesize_procedural("u1"))["procedures_created"] == 1 @@ -318,7 +328,7 @@ def _written_body(containers: dict[ContainerKey, Any], helper: str) -> dict[str, def test_direct_pipeline_writes_are_sanitized(helper) -> None: """These helpers write straight to the container and never pass through the store.""" containers = {key: MagicMock() for key in (ContainerKey.TURNS, ContainerKey.MEMORIES, ContainerKey.SUMMARIES)} - service = PipelineService(MagicMock(), _SyncChat([]), _SyncEmbeddings(), containers=containers) + service = PipelineService(MagicMock(), _SyncChat([]), _SyncEmbeddings(), containers=containers, tenant_id="acme") original = _procedural_doc_quoting_a_token() getattr(service, helper)(original) @@ -326,16 +336,47 @@ def test_direct_pipeline_writes_are_sanitized(helper) -> None: body = _written_body(containers, helper) assert TOKEN not in repr(body) assert body["metadata"]["classification"] == "secret" + assert body["tenant_id"] == "acme", "the service stamps the tenant it is bound to" assert TOKEN in repr(original), "the caller's document is not rewritten" + assert "tenant_id" not in original + + +@pytest.mark.parametrize("helper", ["_upsert_memory", "_create_memory", "_upsert_summary"]) +def test_direct_pipeline_writes_refuse_a_document_of_another_tenant(helper) -> None: + containers = {key: MagicMock() for key in (ContainerKey.TURNS, ContainerKey.MEMORIES, ContainerKey.SUMMARIES)} + service = PipelineService(MagicMock(), _SyncChat([]), _SyncEmbeddings(), containers=containers, tenant_id="acme") + + with pytest.raises(ValidationError, match="different tenant"): + getattr(service, helper)({**_procedural_doc_quoting_a_token(), "tenant_id": "other"}) + + for container in containers.values(): + assert not container.method_calls @pytest.mark.parametrize("helper", ["_upsert_memory", "_create_memory", "_upsert_summary"]) async def test_async_direct_pipeline_writes_are_sanitized(helper) -> None: containers = {key: AsyncMock() for key in (ContainerKey.TURNS, ContainerKey.MEMORIES, ContainerKey.SUMMARIES)} - service = AsyncPipelineService(MagicMock(), _AsyncChat([]), _AsyncEmbeddings(), containers=containers) + service = AsyncPipelineService( + MagicMock(), _AsyncChat([]), _AsyncEmbeddings(), containers=containers, tenant_id="acme" + ) await getattr(service, helper)(_procedural_doc_quoting_a_token()) body = _written_body(containers, helper) assert TOKEN not in repr(body) assert body["metadata"]["classification"] == "secret" + assert body["tenant_id"] == "acme" + + +@pytest.mark.parametrize("helper", ["_upsert_memory", "_create_memory", "_upsert_summary"]) +async def test_async_direct_pipeline_writes_refuse_a_document_of_another_tenant(helper) -> None: + containers = {key: AsyncMock() for key in (ContainerKey.TURNS, ContainerKey.MEMORIES, ContainerKey.SUMMARIES)} + service = AsyncPipelineService( + MagicMock(), _AsyncChat([]), _AsyncEmbeddings(), containers=containers, tenant_id="acme" + ) + + with pytest.raises(ValidationError, match="different tenant"): + await getattr(service, helper)({**_procedural_doc_quoting_a_token(), "tenant_id": "other"}) + + for container in containers.values(): + assert not container.method_calls diff --git a/tests/unit/services/test_transcript_metadata.py b/tests/unit/services/test_transcript_metadata.py index a480457..b48335f 100644 --- a/tests/unit/services/test_transcript_metadata.py +++ b/tests/unit/services/test_transcript_metadata.py @@ -276,6 +276,7 @@ def test_sync_client_threads_kwarg_into_pipeline(self) -> None: client = CosmosMemoryClient.__new__(CosmosMemoryClient) client._transcript_metadata_keys = ("agent_id", "timestamp") + client._tenant_id = "acme" client._turns_container_client = MagicMock() client._memories_container_client = MagicMock() client._summaries_container_client = MagicMock() @@ -298,6 +299,7 @@ def fake_pipeline(*args: object, **kwargs: object) -> object: mod.PipelineService = original assert captured.get("transcript_metadata_keys") == ("agent_id", "timestamp") + assert captured.get("tenant_id") == "acme" def test_async_client_threads_kwarg_into_pipeline(self) -> None: from unittest.mock import MagicMock @@ -307,6 +309,7 @@ def test_async_client_threads_kwarg_into_pipeline(self) -> None: client = AsyncCosmosMemoryClient.__new__(AsyncCosmosMemoryClient) client._transcript_metadata_keys = ("agent_id",) + client._tenant_id = "acme" client._turns_container_client = MagicMock() client._memories_container_client = MagicMock() client._summaries_container_client = MagicMock() @@ -327,6 +330,7 @@ def fake_pipeline(*args: object, **kwargs: object) -> object: mod.AsyncPipelineService = original assert captured.get("transcript_metadata_keys") == ("agent_id",) + assert captured.get("tenant_id") == "acme" class TestIncludeTimestamp: diff --git a/tests/unit/services/test_user_summary_topic_tags.py b/tests/unit/services/test_user_summary_topic_tags.py index f766a32..74c2cc1 100644 --- a/tests/unit/services/test_user_summary_topic_tags.py +++ b/tests/unit/services/test_user_summary_topic_tags.py @@ -2,9 +2,14 @@ from unittest.mock import AsyncMock, MagicMock +import pytest + from azure.cosmos.agent_memory.aio.services.pipeline import AsyncPipelineService +from azure.cosmos.agent_memory.exceptions import ValidationError from azure.cosmos.agent_memory.services.pipeline import PipelineService +TENANT = "acme" + def _user_summary_doc() -> dict: return { @@ -36,6 +41,7 @@ def _user_summary_doc() -> dict: def test_persist_user_summary_emits_topic_tags_from_summary_topics(): pipeline = PipelineService.__new__(PipelineService) + pipeline._tenant_id = TENANT pipeline._embeddings = MagicMock() pipeline._embeddings.generate.return_value = [0.1, 0.2] pipeline._upsert_summary = MagicMock(side_effect=lambda doc: doc) @@ -45,11 +51,13 @@ def test_persist_user_summary_emits_topic_tags_from_summary_topics(): assert "sys:user-summary" in result["tags"] assert "topic:python" in result["tags"] assert "topic:data-science" in result["tags"] + assert result["tenant_id"] == TENANT pipeline._upsert_summary.assert_called_once() async def test_async_persist_user_summary_emits_topic_tags_from_summary_topics(): pipeline = AsyncPipelineService.__new__(AsyncPipelineService) + pipeline._tenant_id = TENANT pipeline._embeddings = MagicMock() pipeline._embeddings.generate = AsyncMock(return_value=[0.1, 0.2]) pipeline._upsert_summary = AsyncMock(side_effect=lambda doc: doc) @@ -59,4 +67,27 @@ async def test_async_persist_user_summary_emits_topic_tags_from_summary_topics() assert "sys:user-summary" in result["tags"] assert "topic:python" in result["tags"] assert "topic:data-science" in result["tags"] + assert result["tenant_id"] == TENANT pipeline._upsert_summary.assert_awaited_once() + + +def test_persist_user_summary_refuses_a_summary_of_another_tenant(): + pipeline = PipelineService.__new__(PipelineService) + pipeline._tenant_id = TENANT + pipeline._upsert_summary = MagicMock() + + with pytest.raises(ValidationError, match="different tenant"): + pipeline.persist_user_summary("u1", {**_user_summary_doc(), "tenant_id": "other"}) + + pipeline._upsert_summary.assert_not_called() + + +async def test_async_persist_user_summary_refuses_a_summary_of_another_tenant(): + pipeline = AsyncPipelineService.__new__(AsyncPipelineService) + pipeline._tenant_id = TENANT + pipeline._upsert_summary = AsyncMock() + + with pytest.raises(ValidationError, match="different tenant"): + await pipeline.persist_user_summary("u1", {**_user_summary_doc(), "tenant_id": "other"}) + + pipeline._upsert_summary.assert_not_awaited() diff --git a/tests/unit/store/test_delete_cascade.py b/tests/unit/store/test_delete_cascade.py index 8a7923a..d1087f9 100644 --- a/tests/unit/store/test_delete_cascade.py +++ b/tests/unit/store/test_delete_cascade.py @@ -11,17 +11,30 @@ from azure.cosmos.agent_memory.exceptions import CosmosOperationError, MemoryTypeMismatchError from azure.cosmos.agent_memory.store import MemoryStore +TENANT = "acme" + def _containers(memories): return {ContainerKey.TURNS: MagicMock(), ContainerKey.MEMORIES: memories, ContainerKey.SUMMARIES: MagicMock()} +def _store(memories): + return MemoryStore(containers=_containers(memories), tenant_id=TENANT) + + def _memory(memory_type="fact", memory_id="m1"): - return {"id": memory_id, "type": memory_type, "user_id": "u1", "thread_id": "t1", "_etag": "e1"} + return { + "id": memory_id, + "type": memory_type, + "tenant_id": TENANT, + "user_id": "u1", + "thread_id": "t1", + "_etag": "e1", + } -def _row(row_id, thread_id="t1"): - return {"id": row_id, "type": "fact", "thread_id": thread_id} +def _row(row_id): + return {"id": row_id, "type": "fact"} def _memories(doc, absorbed=None, fail=False): @@ -45,28 +58,29 @@ def _deleted(memories): def test_deleting_a_fact_first_deletes_the_duplicates_merged_into_it(): - memories = _memories(_memory(), absorbed={"m1": [_row("copy_1", "t2")]}) + memories = _memories(_memory(), absorbed={"m1": [_row("copy_1")]}) - MemoryStore(containers=_containers(memories)).delete("m1", user_id="u1", thread_id="t1", memory_type="fact") + _store(memories).delete("m1", user_id="u1", memory_type="fact") assert _deleted(memories) == ["copy_1", "m1"] lookup = memories.query_items.call_args_list[0].kwargs params = {p["name"]: p["value"] for p in lookup["parameters"]} - assert params["@user_id"] == "u1" and params["@memory_id"] == "m1" + assert params["@tenant_id"] == TENANT and params["@user_id"] == "u1" and params["@memory_id"] == "m1" assert {v for k, v in params.items() if k.startswith("@reason_")} == {"combined", "duplicate", "procedure"} - assert lookup["enable_cross_partition_query"] is True + assert lookup["partition_key"] == [TENANT, "u1"] + assert "enable_cross_partition_query" not in lookup copy_delete, memory_delete = memories.delete_item.call_args_list - assert copy_delete.kwargs["partition_key"] == ["u1", "t2"] - assert memory_delete.kwargs["partition_key"] == ["u1", "t1"] + assert copy_delete.kwargs["partition_key"] == [TENANT, "u1"] + assert memory_delete.kwargs["partition_key"] == [TENANT, "u1"] def test_deleting_a_procedure_deletes_the_statements_it_absorbed_and_their_copies(): memories = _memories( _memory("procedural", "p1"), - absorbed={"p1": [_row("said_1", "t2")], "said_1": [_row("said_1_copy", "t3")]}, + absorbed={"p1": [_row("said_1")], "said_1": [_row("said_1_copy")]}, ) - MemoryStore(containers=_containers(memories)).delete("p1", user_id="u1", thread_id="t1", memory_type="procedural") + _store(memories).delete("p1", user_id="u1", memory_type="procedural") assert _deleted(memories) == ["said_1_copy", "said_1", "p1"] @@ -76,7 +90,7 @@ def test_other_memory_types_are_deleted_without_a_lookup(memory_type): target = _memories(_memory(memory_type)) containers = {ContainerKey.TURNS: target, ContainerKey.MEMORIES: target, ContainerKey.SUMMARIES: target} - MemoryStore(containers=containers).delete("m1", user_id="u1", thread_id="t1", memory_type=memory_type) + MemoryStore(containers=containers, tenant_id=TENANT).delete("m1", user_id="u1", memory_type=memory_type) assert _deleted(target) == ["m1"] target.query_items.assert_not_called() @@ -91,7 +105,7 @@ def delete_item(*, item, **_kwargs): memories.delete_item.side_effect = delete_item - MemoryStore(containers=_containers(memories)).delete("m1", user_id="u1", thread_id="t1", memory_type="fact") + _store(memories).delete("m1", user_id="u1", memory_type="fact") assert _deleted(memories) == ["copy_1", "m1"] @@ -100,7 +114,7 @@ def test_a_failed_lookup_keeps_the_memory_for_a_retry(): memories = _memories(_memory(), fail=True) with pytest.raises(CosmosOperationError): - MemoryStore(containers=_containers(memories)).delete("m1", user_id="u1", thread_id="t1", memory_type="fact") + _store(memories).delete("m1", user_id="u1", memory_type="fact") memories.delete_item.assert_not_called() @@ -110,7 +124,7 @@ def test_a_failed_delete_of_a_folded_record_keeps_the_memory_for_a_retry(): memories.delete_item.side_effect = RuntimeError("throttled") with pytest.raises(CosmosOperationError): - MemoryStore(containers=_containers(memories)).delete("m1", user_id="u1", thread_id="t1", memory_type="fact") + _store(memories).delete("m1", user_id="u1", memory_type="fact") assert _deleted(memories) == ["copy_1"] @@ -119,20 +133,18 @@ def test_a_type_mismatch_deletes_nothing(): memories = _memories(_memory("fact"), absorbed={"m1": [_row("copy_1")]}) with pytest.raises(MemoryTypeMismatchError): - MemoryStore(containers=_containers(memories)).delete( - "m1", user_id="u1", thread_id="t1", memory_type="procedural" - ) + _store(memories).delete("m1", user_id="u1", memory_type="procedural") memories.query_items.assert_not_called() memories.delete_item.assert_not_called() class _Memories: - """An in-memory memories container: point reads and deletes by ``[user_id, thread_id]``, and the folded-record + """An in-memory memories container: point reads and deletes by ``[tenant_id, user_id]``, and the folded-record lookup answered from the query parameters.""" def __init__(self, *docs): - self.docs = {(d["user_id"], d["thread_id"], d["id"]): d for d in docs} + self.docs = {(d["tenant_id"], d["user_id"], d["id"]): d for d in docs} self.failing_id = None def read_item(self, *, item, partition_key): @@ -145,9 +157,10 @@ def query_items(self, *, parameters, **_kwargs): params = {p["name"]: p["value"] for p in parameters} reasons = {v for k, v in params.items() if k.startswith("@reason_")} return [ - {key: d[key] for key in ("id", "type", "thread_id")} + {key: d[key] for key in ("id", "type")} for d in self.docs.values() - if d["user_id"] == params["@user_id"] + if d["tenant_id"] == params["@tenant_id"] + and d["user_id"] == params["@user_id"] and d.get("superseded_by") == params["@memory_id"] and d.get("supersede_reason") in reasons ] @@ -161,8 +174,8 @@ def delete_item(self, *, item, partition_key, **_kwargs): raise CosmosResourceNotFoundError(status_code=404, message="not found") from None -def _stored(doc_id, thread_id, user_id="u1", **fields): - return {"id": doc_id, "user_id": user_id, "thread_id": thread_id, "type": "fact", **fields} +def _stored(doc_id, thread_id, user_id="u1", tenant_id=TENANT, **fields): + return {"id": doc_id, "tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id, "type": "fact", **fields} def test_only_what_was_folded_into_the_memory_is_deleted_and_a_retry_finishes_the_job(): @@ -173,15 +186,21 @@ def test_only_what_was_folded_into_the_memory_is_deleted_and_a_retry_finishes_th _stored("older", "t4", superseded_by="m1", supersede_reason="update"), _stored("lost", "t5", superseded_by="m1", supersede_reason="contradict"), _stored("theirs", "t2", user_id="u2", superseded_by="m1", supersede_reason="duplicate"), + _stored("elsewhere", "t2", tenant_id="globex", superseded_by="m1", supersede_reason="duplicate"), ) - store = MemoryStore(containers=_containers(memories)) + store = _store(memories) memories.failing_id = "dup" with pytest.raises(CosmosOperationError): - store.delete("m1", user_id="u1", thread_id="t1", memory_type="fact") - assert ("u1", "t1", "m1") in memories.docs and ("u1", "t3", "src") not in memories.docs + store.delete("m1", user_id="u1", memory_type="fact") + assert (TENANT, "u1", "m1") in memories.docs and (TENANT, "u1", "src") not in memories.docs memories.failing_id = None - store.delete("m1", user_id="u1", thread_id="t1", memory_type="fact") - - assert set(memories.docs) == {("u1", "t4", "older"), ("u1", "t5", "lost"), ("u2", "t2", "theirs")} + store.delete("m1", user_id="u1", memory_type="fact") + + assert set(memories.docs) == { + (TENANT, "u1", "older"), + (TENANT, "u1", "lost"), + (TENANT, "u2", "theirs"), + ("globex", "u1", "elsewhere"), + } diff --git a/tests/unit/store/test_get_memory_history.py b/tests/unit/store/test_get_memory_history.py index 1ecbad3..da4c5db 100644 --- a/tests/unit/store/test_get_memory_history.py +++ b/tests/unit/store/test_get_memory_history.py @@ -26,11 +26,12 @@ def _containers(*, memories=None): } -def _fact(fact_id, *, superseded_by=None, superseded_at=None, reason=None, content=""): +def _fact(fact_id, *, superseded_by=None, superseded_at=None, reason=None, content="", thread_id="t1"): return { "id": fact_id, + "tenant_id": "default", "user_id": "u1", - "thread_id": "t1", + "thread_id": thread_id, "type": "fact", "content": content or fact_id, "metadata": {"category": "biographical"}, @@ -68,7 +69,7 @@ def test_single_level_history_returns_direct_predecessor(): ] store = MemoryStore(containers=_containers(memories=memories)) - history = store.get_memory_history("current", user_id="u1", thread_id="t1") + history = store.get_memory_history("current", user_id="u1") assert [d["id"] for d in history] == ["v1"] assert history[0]["supersede_reason"] == "update" @@ -83,7 +84,7 @@ def test_multi_level_chain_walks_transitively_newest_first(): ] store = MemoryStore(containers=_containers(memories=memories)) - history = store.get_memory_history("current", user_id="u1", thread_id="t1") + history = store.get_memory_history("current", user_id="u1") # Ordered most-recently-superseded first. assert [d["id"] for d in history] == ["v2", "v1"] @@ -94,7 +95,7 @@ def test_no_history_returns_empty_list(): memories.query_items.return_value = [] store = MemoryStore(containers=_containers(memories=memories)) - assert store.get_memory_history("current", user_id="u1", thread_id="t1") == [] + assert store.get_memory_history("current", user_id="u1") == [] def test_cycle_is_bounded_and_deduplicated(): @@ -107,35 +108,28 @@ def test_cycle_is_bounded_and_deduplicated(): ] store = MemoryStore(containers=_containers(memories=memories)) - history = store.get_memory_history("current", user_id="u1", thread_id="t1", max_depth=50) + history = store.get_memory_history("current", user_id="u1", max_depth=50) assert [d["id"] for d in history] == ["v1"] -def test_thread_scoped_query_uses_single_partition(): +def test_the_chain_is_walked_in_the_owners_partition_whatever_the_thread_of_each_version(): memories = MagicMock() - memories.query_items.return_value = [] - store = MemoryStore(containers=_containers(memories=memories)) - - store.get_memory_history("current", user_id="u1", thread_id="t1") - - kwargs = memories.query_items.call_args.kwargs - assert kwargs["partition_key"] == ["u1", "t1"] - assert "enable_cross_partition_query" not in kwargs - assert "c.thread_id = @thread_id" in kwargs["query"] - - -def test_history_without_thread_id_fans_out_cross_partition(): - memories = MagicMock() - memories.query_items.return_value = [] + memories.query_items.side_effect = [ + [_fact("v2", superseded_at="2025-03-01T00:00:00+00:00", thread_id="t2")], + [_fact("v1", superseded_at="2025-02-01T00:00:00+00:00", thread_id="t3")], + [], + ] store = MemoryStore(containers=_containers(memories=memories)) - store.get_memory_history("current", user_id="u1") + history = store.get_memory_history("current", user_id="u1") - kwargs = memories.query_items.call_args.kwargs - assert kwargs.get("enable_cross_partition_query") is True - assert "c.thread_id = @thread_id" not in kwargs["query"] - assert "c.superseded_by IN (@sid0)" in kwargs["query"] + assert [d["thread_id"] for d in history] == ["t2", "t3"] + for call in memories.query_items.call_args_list: + assert call.kwargs["partition_key"] == ["default", "u1"] + assert "enable_cross_partition_query" not in call.kwargs + assert "c.thread_id" not in call.kwargs["query"].split(" WHERE ", 1)[1] + assert "c.superseded_by IN (@sid0)" in call.kwargs["query"] def test_missing_memory_id_raises(): diff --git a/tests/unit/store/test_list_tags.py b/tests/unit/store/test_list_tags.py index be0c653..fe0329f 100644 --- a/tests/unit/store/test_list_tags.py +++ b/tests/unit/store/test_list_tags.py @@ -43,10 +43,15 @@ def test_list_tags_flattens_dedupes_sorts_and_hides_sys_tags(): summaries.query_items.assert_not_called() kwargs = memories.query_items.call_args.kwargs assert kwargs["query"] == ( - "SELECT VALUE c.tags FROM c WHERE c.user_id = @user_id AND ARRAY_LENGTH(c.tags) > 0" - " AND (NOT IS_DEFINED(c.superseded_by) OR IS_NULL(c.superseded_by))" + "SELECT VALUE c.tags FROM c WHERE c.tenant_id = @tenant_id AND c.user_id = @user_id" + " AND ARRAY_LENGTH(c.tags) > 0 AND (NOT IS_DEFINED(c.superseded_by) OR IS_NULL(c.superseded_by))" ) - assert kwargs["enable_cross_partition_query"] is True + assert kwargs["parameters"] == [ + {"name": "@tenant_id", "value": "default"}, + {"name": "@user_id", "value": "u1"}, + ] + assert kwargs["partition_key"] == ["default", "u1"] + assert "enable_cross_partition_query" not in kwargs def test_list_tags_prefix_and_include_sys(): @@ -62,7 +67,7 @@ def test_list_tags_prefix_and_include_sys(): summaries.query_items.assert_not_called() -def test_list_tags_thread_id_scopes_to_partition(): +def test_list_tags_thread_id_filters_within_the_owners_partition(): turns = MagicMock() memories = MagicMock() summaries = MagicMock() @@ -73,7 +78,7 @@ def test_list_tags_thread_id_scopes_to_partition(): kwargs = memories.query_items.call_args.kwargs assert "AND c.thread_id = @thread_id" in kwargs["query"] - assert kwargs["partition_key"] == ["u1", "t1"] + assert kwargs["partition_key"] == ["default", "u1"] assert "enable_cross_partition_query" not in kwargs turns.query_items.assert_not_called() summaries.query_items.assert_not_called() @@ -95,11 +100,11 @@ async def test_async_list_tags_flattens_dedupes_sorts_and_hides_sys_tags(): summaries.query_items.assert_not_called() kwargs = memories.query_items.call_args.kwargs assert kwargs["query"] == ( - "SELECT VALUE c.tags FROM c WHERE c.user_id = @user_id AND ARRAY_LENGTH(c.tags) > 0" - " AND (NOT IS_DEFINED(c.superseded_by) OR IS_NULL(c.superseded_by))" + "SELECT VALUE c.tags FROM c WHERE c.tenant_id = @tenant_id AND c.user_id = @user_id" + " AND ARRAY_LENGTH(c.tags) > 0 AND (NOT IS_DEFINED(c.superseded_by) OR IS_NULL(c.superseded_by))" ) + assert kwargs["partition_key"] == ["default", "u1"] assert "enable_cross_partition_query" not in kwargs - assert "partition_key" not in kwargs async def test_async_list_tags_prefix_and_include_sys(): @@ -117,7 +122,7 @@ async def test_async_list_tags_prefix_and_include_sys(): summaries.query_items.assert_not_called() -async def test_async_list_tags_thread_id_scopes_to_partition(): +async def test_async_list_tags_thread_id_filters_within_the_owners_partition(): turns = MagicMock() memories = MagicMock() summaries = MagicMock() @@ -128,7 +133,7 @@ async def test_async_list_tags_thread_id_scopes_to_partition(): kwargs = memories.query_items.call_args.kwargs assert "AND c.thread_id = @thread_id" in kwargs["query"] - assert kwargs["partition_key"] == ["u1", "t1"] + assert kwargs["partition_key"] == ["default", "u1"] assert "enable_cross_partition_query" not in kwargs turns.query_items.assert_not_called() summaries.query_items.assert_not_called() diff --git a/tests/unit/store/test_memory_store.py b/tests/unit/store/test_memory_store.py index 4f077c5..042dbff 100644 --- a/tests/unit/store/test_memory_store.py +++ b/tests/unit/store/test_memory_store.py @@ -154,9 +154,9 @@ def test_update_replaces_matching_doc(): memories.read_item.return_value = _doc(id="m1", type="fact") store = MemoryStore(containers=_containers(memories=memories)) - store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content="updated") + store.update("m1", user_id="u1", memory_type="fact", content="updated") - memories.read_item.assert_called_once_with(item="m1", partition_key=["u1", "t1"]) + memories.read_item.assert_called_once_with(item="m1", partition_key=["default", "u1"]) body = memories.replace_item.call_args.kwargs["body"] assert body["content"] == "updated" assert body["type"] == "fact" @@ -170,8 +170,10 @@ def test_update_raises_when_missing(): memories.read_item.side_effect = CosmosResourceNotFoundError(message="404") store = MemoryStore(containers=_containers(memories=memories)) - with pytest.raises(MemoryNotFoundError): - store.update("missing", user_id="u1", thread_id="t1", memory_type="fact") + with pytest.raises(MemoryNotFoundError) as excinfo: + store.update("missing", user_id="u1", memory_type="fact") + + assert (excinfo.value.memory_id, excinfo.value.user_id) == ("missing", "u1") def test_update_raises_on_type_mismatch(): @@ -180,7 +182,7 @@ def test_update_raises_on_type_mismatch(): store = MemoryStore(containers=_containers(memories=memories)) with pytest.raises(MemoryTypeMismatchError): - store.update("m1", user_id="u1", thread_id="t1", memory_type="episodic", content="x") + store.update("m1", user_id="u1", memory_type="episodic", content="x") memories.replace_item.assert_not_called() @@ -190,9 +192,9 @@ def test_delete_calls_delete_item_directly(): memories.read_item.return_value = _doc(id="m1", type="fact") store = MemoryStore(containers=_containers(memories=memories)) - store.delete("m1", user_id="u1", thread_id="t1", memory_type="fact") + store.delete("m1", user_id="u1", memory_type="fact") - memories.delete_item.assert_called_once_with(item="m1", partition_key=["u1", "t1"]) + memories.delete_item.assert_called_once_with(item="m1", partition_key=["default", "u1"]) def test_delete_raises_when_missing(): @@ -203,7 +205,7 @@ def test_delete_raises_when_missing(): store = MemoryStore(containers=_containers(memories=memories)) with pytest.raises(MemoryNotFoundError): - store.delete("m1", user_id="u1", thread_id="t1", memory_type="fact") + store.delete("m1", user_id="u1", memory_type="fact") memories.delete_item.assert_not_called() @@ -214,7 +216,7 @@ def test_delete_raises_on_type_mismatch(): store = MemoryStore(containers=_containers(memories=memories)) with pytest.raises(MemoryTypeMismatchError): - store.delete("m1", user_id="u1", thread_id="t1", memory_type="episodic") + store.delete("m1", user_id="u1", memory_type="episodic") memories.delete_item.assert_not_called() @@ -224,11 +226,12 @@ def test_read_and_tag_mutation_use_point_reads(): memories.read_item.return_value = _doc(type="fact", tags=["old"]) store = MemoryStore(containers=_containers(memories=memories)) - assert store.read_item("m1", ["u1", "t1"], container_key=ContainerKey.MEMORIES)["id"] == "m1" - store.add_tags("m1", "u1", "t1", "fact", ["New"]) - store.remove_tags("m1", "u1", "t1", "fact", ["old"]) + assert store.read_item("m1", ["default", "u1"], container_key=ContainerKey.MEMORIES)["id"] == "m1" + store.add_tags("m1", "u1", "fact", ["New"]) + store.remove_tags("m1", "u1", "fact", ["old"]) - assert memories.read_item.call_args_list[0].kwargs == {"item": "m1", "partition_key": ["u1", "t1"]} + assert memories.read_item.call_args_list[0].kwargs == {"item": "m1", "partition_key": ["default", "u1"]} + assert [call.kwargs["partition_key"] for call in memories.read_item.call_args_list] == [["default", "u1"]] * 3 assert memories.replace_item.call_count == 2 @@ -237,7 +240,7 @@ def test_tag_mutation_rejects_non_memories_types(): for bad in ("turn", "thread_summary", "user_summary", "unknown"): with pytest.raises(ValueError, match="memory_type for tag mutation"): - store.add_tags("m1", "u1", "t1", bad, ["x"]) + store.add_tags("m1", "u1", bad, ["x"]) def test_single_doc_and_simple_query_helpers(): @@ -430,7 +433,7 @@ def test_get_memories_rejects_non_memories_types(): store.get_memories(memory_types=bad) -def test_get_thread_summary_queries_summaries_with_partition_key(): +def test_get_thread_summary_queries_summaries_with_the_owners_partition_key(): summaries = MagicMock() summaries.query_items.return_value = [_doc(type="thread_summary", id="s1")] store = MemoryStore(containers=_containers(summaries=summaries)) @@ -439,7 +442,7 @@ def test_get_thread_summary_queries_summaries_with_partition_key(): assert [doc["id"] for doc in results] == ["s1"] call_kwargs = summaries.query_items.call_args.kwargs - assert call_kwargs["partition_key"] == ["u1", "t1"] + assert call_kwargs["partition_key"] == ["default", "u1"] assert "c.type = @type" in call_kwargs["query"] assert "TOP @recent_k" in call_kwargs["query"] params = _params_by_name(call_kwargs) @@ -451,10 +454,9 @@ def test_get_thread_summary_queries_summaries_with_partition_key(): # --------------------------------------------------------------------------- # F-final: read-path translation for user-scoped types (episodic / procedural) # -# Episodic + procedural docs live in sentinel partitions -# ("__episodic__" / "__procedural__") under each user, not the originating -# thread's partition. Public read APIs that filter on c.thread_id must OR in -# an IN (...) clause for those types so they aren't silently excluded. +# Episodic and procedural memories stay user-wide. Public read APIs that +# filter on c.thread_id must OR in an IN (...) clause for those types so a +# thread filter doesn't silently exclude them. # --------------------------------------------------------------------------- @@ -512,7 +514,7 @@ def test_get_memories_no_memory_types_with_thread_id_emits_or_clause(): assert sorted(v for k, v in params.items() if k.startswith("@user_scoped_type_")) == ["episodic", "procedural"] -def test_search_with_episodic_and_thread_id_forces_cross_partition(): +def test_search_with_episodic_and_thread_id_stays_in_the_owners_partition(): memories = MagicMock() memories.query_items.return_value = [] embeddings = MagicMock() @@ -520,18 +522,17 @@ def test_search_with_episodic_and_thread_id_forces_cross_partition(): store = MemoryStore(containers=_containers(memories=memories), embeddings_client=embeddings) store.search( - search_terms="hotels", + search_terms="hello", user_id="u1", thread_id="t1", memory_types=["episodic"], ) call_kwargs = memories.query_items.call_args.kwargs - # When user-scoped types are in scope, search must fan out across - # partitions instead of confining to [u1, t1] (where no episodic - # ever lives - they all use the "__episodic__" sentinel partition). - assert call_kwargs.get("enable_cross_partition_query") is True - assert "partition_key" not in call_kwargs + # The thread filter never forces a fan-out: every record of the owner is in one partition, and the OR clause keeps + # the user-wide types reachable. + assert call_kwargs["partition_key"] == ["default", "u1"] + assert "enable_cross_partition_query" not in call_kwargs assert "(c.thread_id = @thread_id OR c.type IN (@user_scoped_type_0))" in call_kwargs["query"] @@ -668,7 +669,7 @@ def test_search_summaries_requires_user_id(): store.search_summaries(search_terms="x") -def test_vector_only_search_turns_scopes_to_single_partition_with_thread_id(): +def test_vector_only_search_turns_reads_the_owners_partition_whatever_the_thread(): turns = MagicMock() turns.query_items.return_value = [] embeddings = MagicMock() @@ -682,8 +683,9 @@ def test_vector_only_search_turns_scopes_to_single_partition_with_thread_id(): store.search_turns(search_terms="hello", user_id="u1", thread_id="t1") kwargs = turns.query_items.call_args.kwargs - assert kwargs["partition_key"] == ["u1", "t1"] + assert kwargs["partition_key"] == ["default", "u1"] assert "enable_cross_partition_query" not in kwargs + assert "c.thread_id = @thread_id" in kwargs["query"] def test_keyword_search_turns_with_thread_id_filters_instead_of_using_partition_key(): @@ -705,23 +707,6 @@ def test_keyword_search_turns_with_thread_id_filters_instead_of_using_partition_ assert "c.thread_id = @thread_id" in kwargs["query"] -def test_search_turns_fans_out_across_partitions_without_thread_id(): - turns = MagicMock() - turns.query_items.return_value = [] - embeddings = MagicMock() - embeddings.generate.return_value = [0.1, 0.2] - store = MemoryStore( - containers=_containers(turns=turns), - embeddings_client=embeddings, - ) - - store.search_turns(search_terms="hello", user_id="u1") - - kwargs = turns.query_items.call_args.kwargs - assert "partition_key" not in kwargs - assert kwargs["enable_cross_partition_query"] is True - - def test_search_turns_requires_user_id(): turns = MagicMock() embeddings = MagicMock() diff --git a/tests/unit/store/test_search_routing.py b/tests/unit/store/test_search_routing.py index 1a3e20a..f8eaf55 100644 --- a/tests/unit/store/test_search_routing.py +++ b/tests/unit/store/test_search_routing.py @@ -2,8 +2,9 @@ A ``FullTextScore`` (keyword or hybrid) query is ranked only when it runs across partitions. The Python SDK runs one sent with a partition key without planning it, and it came back in one fixed order for every question -(azure-sdk-for-python#42241), so a thread holding more memories than ``top_k`` returned the same memories whatever -was asked. Vector-only searches rank correctly either way and keep the key. +(azure-sdk-for-python#42241), so an owner holding more memories than ``top_k`` returned the same memories whatever +was asked. Vector-only searches rank correctly either way and keep the key ``[tenant_id, user_id]``; a thread filter +never changes that, because every record of the owner is in one partition. """ from __future__ import annotations @@ -15,6 +16,7 @@ from azure.cosmos.agent_memory._container_routing import ContainerKey from azure.cosmos.agent_memory.exceptions import ValidationError from azure.cosmos.agent_memory.store import MemoryStore +from azure.cosmos.agent_memory.store._search_helpers import query_scope KEYWORDS = "Hotels in Lisbon" NO_KEYWORDS = "hello" @@ -45,6 +47,13 @@ def _params(call: dict) -> list[tuple[str, object]]: return [(param["name"], param["value"]) for param in call["parameters"]] +def test_a_search_reads_the_owners_partition_unless_it_has_keywords(): + assert query_scope("acme", "u1") == (["acme", "u1"], False) + assert query_scope("acme", "u1", keyword_count=0) == (["acme", "u1"], False) + assert query_scope("acme", "u1", keyword_count=2) == (None, True) + assert query_scope("acme", None) == (None, True) + + @pytest.mark.parametrize(("method", "container_key", "options"), THREAD_SEARCHES) def test_a_keyword_search_of_a_thread_runs_cross_partition_inside_it(method, container_key, options): store, containers = _store() @@ -54,9 +63,10 @@ def test_a_keyword_search_of_a_thread_runs_cross_partition_inside_it(method, con (call,) = _calls(containers[container_key]) assert "partition_key" not in call assert call["enable_cross_partition_query"] is True - assert "c.user_id = @user_id" in call["query"] + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in call["query"] assert "c.thread_id = @thread_id" in call["query"] params = _params(call) + assert ("@tenant_id", "default") in params assert ("@user_id", "u1") in params assert ("@thread_id", "t1") in params assert ( @@ -70,18 +80,31 @@ def test_a_keyword_search_of_a_thread_runs_cross_partition_inside_it(method, con @pytest.mark.parametrize(("method", "container_key", "options"), THREAD_SEARCHES) -def test_a_vector_only_search_of_a_thread_keeps_the_partition_key(method, container_key, options): +def test_a_vector_only_search_of_a_thread_keeps_the_owners_partition_key(method, container_key, options): store, containers = _store() getattr(store, method)(user_id="u1", thread_id="t1", search_terms=NO_KEYWORDS, **options) (call,) = _calls(containers[container_key]) - assert call["partition_key"] == ["u1", "t1"] + assert call["partition_key"] == ["default", "u1"] assert "enable_cross_partition_query" not in call + assert "c.thread_id = @thread_id" in call["query"] assert "FullTextScore" not in call["query"] assert "full_text_score_scope" not in call +@pytest.mark.parametrize(("method", "container_key", "options"), USER_SEARCHES) +def test_a_vector_only_search_of_the_users_threads_keeps_the_owners_partition_key(method, container_key, options): + store, containers = _store() + + getattr(store, method)(user_id="u1", search_terms=NO_KEYWORDS, **options) + + (call,) = _calls(containers[container_key]) + assert call["partition_key"] == ["default", "u1"] + assert "enable_cross_partition_query" not in call + assert "c.thread_id = @thread_id" not in call["query"] + + @pytest.mark.parametrize(("method", "container_key", "options"), USER_SEARCHES) def test_a_keyword_search_of_the_users_threads_ranks_with_local_statistics(method, container_key, options): store, containers = _store() @@ -91,7 +114,7 @@ def test_a_keyword_search_of_the_users_threads_ranks_with_local_statistics(metho (call,) = _calls(containers[container_key]) assert "partition_key" not in call assert call["enable_cross_partition_query"] is True - assert "c.user_id = @user_id" in call["query"] + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in call["query"] assert "c.thread_id = @thread_id" not in call["query"] assert call["full_text_score_scope"] == "Local" @@ -130,7 +153,7 @@ def test_a_full_text_query_sent_with_a_partition_key_is_rejected(call): f"SELECT TOP 1 c.id FROM c ORDER BY RANK {call}", [], container_key=ContainerKey.MEMORIES, - partition_key=["u1", "t1"], + partition_key=["default", "u1"], ) containers[ContainerKey.MEMORIES].query_items.assert_not_called() @@ -142,17 +165,20 @@ def test_a_query_that_only_names_a_field_like_the_function_keeps_its_partition_k "SELECT TOP 1 c.id FROM c WHERE c.fulltextscore = 1", [], container_key=ContainerKey.MEMORIES, - partition_key=["u1", "t1"], + partition_key=["default", "u1"], ) (call,) = _calls(containers[ContainerKey.MEMORIES]) - assert call["partition_key"] == ["u1", "t1"] + assert call["partition_key"] == ["default", "u1"] def test_a_callers_own_full_text_query_keeps_the_default_statistics(): store, containers = _store() - sql = "SELECT TOP 1 c.id FROM c WHERE c.user_id = @u ORDER BY RANK FullTextScore(c.content, 'hotels')" - parameters = [{"name": "@u", "value": "u1"}] + sql = ( + "SELECT TOP 1 c.id FROM c WHERE c.tenant_id = @t AND c.user_id = @u " + "ORDER BY RANK FullTextScore(c.content, 'hotels')" + ) + parameters = [{"name": "@t", "value": "default"}, {"name": "@u", "value": "u1"}] store.query(sql, parameters, container_key=ContainerKey.MEMORIES, cross_partition=True) store.query( diff --git a/tests/unit/store/test_secret_redaction.py b/tests/unit/store/test_secret_redaction.py index ba3e25b..ae03f74 100644 --- a/tests/unit/store/test_secret_redaction.py +++ b/tests/unit/store/test_secret_redaction.py @@ -260,9 +260,7 @@ def test_update_without_an_embedder_redacts_new_content_and_metadata_and_keeps_t memories.read_item.return_value = _stored_doc(embedding=[9.9], content_hash=compute_content_hash("hello")) store = MemoryStore(containers=_containers(memories=memories)) - store.update( - "m1", user_id="u1", thread_id="t1", memory_type="fact", content=f"Use {SECRET}", metadata={"note": SECRET} - ) + store.update("m1", user_id="u1", memory_type="fact", content=f"Use {SECRET}", metadata={"note": SECRET}) body = memories.replace_item.call_args.kwargs["body"] assert TOKEN not in repr(body) @@ -286,7 +284,7 @@ def _failing_embedder(): def test_update_without_an_embedder_keeps_the_previous_vector_when_the_content_changes(): store, memories = _update_store(_stored_doc(embedding=[9.9]), None) - store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content="Prefers Ruff.") + store.update("m1", user_id="u1", memory_type="fact", content="Prefers Ruff.") body = memories.replace_item.call_args.kwargs["body"] assert body["content"] == "Prefers Ruff." @@ -298,7 +296,7 @@ def test_update_rebuilds_the_vector_from_the_redacted_content(): embeddings = _embedder() store, memories = _update_store(_stored_doc(embedding=[9.9]), embeddings) - store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content=f"Use {SECRET}") + store.update("m1", user_id="u1", memory_type="fact", content=f"Use {SECRET}") body = memories.replace_item.call_args.kwargs["body"] embeddings.generate.assert_called_once_with(body["content"]) @@ -310,7 +308,7 @@ def test_a_metadata_only_update_rebuilds_the_vector_of_a_record_that_already_hel embeddings = _embedder() store, memories = _update_store(_stored_doc(content=f"Use {SECRET}", embedding=[9.9]), embeddings) - store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", metadata={"note": "rotated"}) + store.update("m1", user_id="u1", memory_type="fact", metadata={"note": "rotated"}) body = memories.replace_item.call_args.kwargs["body"] embeddings.generate.assert_called_once_with(body["content"]) @@ -322,7 +320,7 @@ def test_update_rebuilds_the_vector_when_the_content_changes(): embeddings = _embedder() store, memories = _update_store(_stored_doc(embedding=[9.9]), embeddings) - store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content="Prefers Ruff.") + store.update("m1", user_id="u1", memory_type="fact", content="Prefers Ruff.") embeddings.generate.assert_called_once_with("Prefers Ruff.") assert memories.replace_item.call_args.kwargs["body"]["embedding"] == [0.1, 0.2] @@ -337,7 +335,7 @@ def test_update_keeps_the_vector_when_the_text_it_encodes_is_unchanged(changes): embeddings = _embedder() store, memories = _update_store(_stored_doc(embedding=[9.9]), embeddings) - store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", **changes) + store.update("m1", user_id="u1", memory_type="fact", **changes) embeddings.generate.assert_not_called() assert memories.replace_item.call_args.kwargs["body"]["embedding"] == [9.9] @@ -347,7 +345,7 @@ def test_update_does_not_embed_a_record_that_has_no_vector(): embeddings = _embedder() store, memories = _update_store(_stored_doc(), embeddings) - store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content=f"Use {SECRET}") + store.update("m1", user_id="u1", memory_type="fact", content=f"Use {SECRET}") embeddings.generate.assert_not_called() assert "embedding" not in memories.replace_item.call_args.kwargs["body"] @@ -358,7 +356,7 @@ def test_update_drops_the_vector_of_a_record_whose_text_is_emptied_without_embed embeddings = _embedder() store, memories = _update_store(_stored_doc(embedding=[9.9]), embeddings) - store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content="") + store.update("m1", user_id="u1", memory_type="fact", content="") embeddings.generate.assert_not_called() assert "embedding" not in memories.replace_item.call_args.kwargs["body"] @@ -370,7 +368,7 @@ def test_update_keeps_a_procedures_vector_when_only_its_content_changes(): stored = _stored_doc(type="procedural", retrieval_text="deploy the service", embedding=[9.9]) store, memories = _update_store(stored, embeddings) - store.update("m1", user_id="u1", thread_id="t1", memory_type="procedural", content="Run the deploy script.") + store.update("m1", user_id="u1", memory_type="procedural", content="Run the deploy script.") embeddings.generate.assert_not_called() assert memories.replace_item.call_args.kwargs["body"]["embedding"] == [9.9] @@ -382,7 +380,7 @@ def test_update_rebuilds_a_procedures_vector_from_its_retrieval_text(): stored = _stored_doc(type="procedural", retrieval_text="deploy the service", embedding=[9.9]) store, memories = _update_store(stored, embeddings) - store.update("m1", user_id="u1", thread_id="t1", memory_type="procedural", content=f"Use {SECRET}") + store.update("m1", user_id="u1", memory_type="procedural", content=f"Use {SECRET}") embeddings.generate.assert_called_once_with("deploy the service") assert memories.replace_item.call_args.kwargs["body"]["embedding"] == [0.1, 0.2] @@ -401,7 +399,7 @@ def test_update_keeps_the_previous_vector_when_embedding_fails(content, caplog): caplog.set_level(logging.DEBUG) store, memories = _update_store(_stored_doc(embedding=[9.9]), _failing_embedder()) - store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content=content) + store.update("m1", user_id="u1", memory_type="fact", content=content) body = memories.replace_item.call_args.kwargs["body"] assert body["embedding"] == [9.9] @@ -424,7 +422,7 @@ def test_update_drops_a_vector_built_from_a_secret_when_it_cannot_be_rebuilt(cha embeddings = _failing_embedder() if embedder == "fails" else None store, memories = _update_store(_stored_doc(content=f"Use {SECRET}", embedding=[9.9]), embeddings) - store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", **changes) + store.update("m1", user_id="u1", memory_type="fact", **changes) body = memories.replace_item.call_args.kwargs["body"] assert "embedding" not in body @@ -443,7 +441,7 @@ def test_update_judges_a_procedures_vector_by_the_text_it_was_built_from(retriev stored = _stored_doc(type="procedural", retrieval_text=retrieval_text, content=f"Use {SECRET}", embedding=[9.9]) store, memories = _update_store(stored, _failing_embedder()) - store.update("m1", user_id="u1", thread_id="t1", memory_type="procedural", metadata={"note": "rotated"}) + store.update("m1", user_id="u1", memory_type="procedural", metadata={"note": "rotated"}) body = memories.replace_item.call_args.kwargs["body"] assert body.get("embedding") == expected @@ -461,7 +459,7 @@ def test_an_etag_conflict_retry_keeps_the_vector_it_reads_again_when_embedding_f memories.replace_item.side_effect = [CosmosAccessConditionFailedError(message="412", response=None), None] store = MemoryStore(containers=_containers(memories=memories), embeddings_client=_failing_embedder()) - store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content="Prefers Ruff.") + store.update("m1", user_id="u1", memory_type="fact", content="Prefers Ruff.") assert memories.replace_item.call_count == 2 assert memories.replace_item.call_args.kwargs["body"]["embedding"] == [7.7] @@ -473,7 +471,7 @@ def test_an_etag_conflict_retry_does_not_embed_the_same_text_again(monkeypatch): store, memories = _update_store(_stored_doc(embedding=[9.9], _etag="v1"), embeddings) memories.replace_item.side_effect = [CosmosAccessConditionFailedError(message="412", response=None), None] - store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", content="Prefers Ruff.") + store.update("m1", user_id="u1", memory_type="fact", content="Prefers Ruff.") assert memories.replace_item.call_count == 2 embeddings.generate.assert_called_once_with("Prefers Ruff.") @@ -489,7 +487,7 @@ def _tagged_store(tags=()): def test_add_tags_drops_a_credential_tag_and_flags_the_record(): store, memories = _tagged_store(["topic:deploy"]) - store.add_tags("m1", "u1", "t1", "fact", [TOKEN, "Release"]) + store.add_tags("m1", "u1", "fact", [TOKEN, "Release"]) body = memories.replace_item.call_args.kwargs["body"] assert body["tags"] == ["release", "sys:secret", "topic:deploy"] @@ -502,7 +500,7 @@ def test_add_tags_checks_a_tag_before_it_is_lowercased(): """An AWS access key id is only recognized in upper case, and tags are stored lower case.""" store, memories = _tagged_store() - store.add_tags("m1", "u1", "t1", "fact", ["AKIA" + "IOSFODNN7EXAMPLE"]) + store.add_tags("m1", "u1", "fact", ["AKIA" + "IOSFODNN7EXAMPLE"]) body = memories.replace_item.call_args.kwargs["body"] assert "akiaiosfodnn7example" not in repr(body).lower() @@ -513,11 +511,11 @@ def test_add_tags_checks_a_tag_before_it_is_lowercased(): def test_add_tags_leaves_a_clean_record_unflagged_and_remove_tags_never_flags(): store, memories = _tagged_store(["a", "b"]) - store.add_tags("m1", "u1", "t1", "fact", ["c"]) + store.add_tags("m1", "u1", "fact", ["c"]) assert memories.replace_item.call_args.kwargs["body"]["tags"] == ["a", "b", "c"] assert "classification" not in memories.replace_item.call_args.kwargs["body"]["metadata"] - store.remove_tags("m1", "u1", "t1", "fact", [TOKEN, "a"]) + store.remove_tags("m1", "u1", "fact", [TOKEN, "a"]) assert memories.replace_item.call_args.kwargs["body"]["tags"] == ["b"] assert "classification" not in memories.replace_item.call_args.kwargs["body"]["metadata"] @@ -526,7 +524,7 @@ def test_add_tags_logs_the_formats_found_never_the_tag(caplog): caplog.set_level(logging.DEBUG) store, _memories = _tagged_store() - store.add_tags("m1", "u1", "t1", "fact", [TOKEN]) + store.add_tags("m1", "u1", "fact", [TOKEN]) assert "patterns=['github_token']" in caplog.text assert TOKEN not in caplog.text and TOKEN.lower() not in caplog.text diff --git a/tests/unit/store/test_tag_mutation.py b/tests/unit/store/test_tag_mutation.py index 725f6de..6882077 100644 --- a/tests/unit/store/test_tag_mutation.py +++ b/tests/unit/store/test_tag_mutation.py @@ -44,7 +44,7 @@ def test_add_tags_retries_once_after_etag_conflict_and_wins(): container.replace_item.side_effect = [_conflict(), None] store = MemoryStore(containers=_containers(memories=container)) - store.add_tags("m1", "u1", "t1", "fact", ["New"]) + store.add_tags("m1", "u1", "fact", ["New"]) assert container.read_item.call_count == 2 assert container.replace_item.call_count == 2 @@ -62,7 +62,7 @@ def test_add_tags_raises_memory_conflict_after_max_retries(monkeypatch): store = MemoryStore(containers=_containers(memories=container)) with pytest.raises(MemoryConflictError, match="after 5 attempts"): - store.add_tags("m1", "u1", "t1", "fact", ["new"]) + store.add_tags("m1", "u1", "fact", ["new"]) assert container.read_item.call_count == 5 assert container.replace_item.call_count == 5 @@ -74,7 +74,7 @@ async def test_async_add_tags_retries_once_after_etag_conflict_and_wins(): container.replace_item = AsyncMock(side_effect=[_conflict(), None]) store = AsyncMemoryStore(containers=_containers(memories=container)) - await store.add_tags("m1", "u1", "t1", "fact", ["New"]) + await store.add_tags("m1", "u1", "fact", ["New"]) assert container.read_item.await_count == 2 assert container.replace_item.await_count == 2 @@ -96,7 +96,7 @@ async def _noop_sleep(*_a, **_kw): store = AsyncMemoryStore(containers=_containers(memories=container)) with pytest.raises(MemoryConflictError, match="after 5 attempts"): - await store.add_tags("m1", "u1", "t1", "fact", ["new"]) + await store.add_tags("m1", "u1", "fact", ["new"]) assert container.read_item.await_count == 5 assert container.replace_item.await_count == 5 diff --git a/tests/unit/store/test_tenant_isolation.py b/tests/unit/store/test_tenant_isolation.py new file mode 100644 index 0000000..8e7d230 --- /dev/null +++ b/tests/unit/store/test_tenant_isolation.py @@ -0,0 +1,417 @@ +"""A store stays inside its tenant. + +Every query a store sends filters on ``c.tenant_id``, a point operation addresses the partition ``[tenant, user]``, and +a document it writes carries the tenant; one that names another tenant is refused. Each case runs against the sync and +the async store, and the tenant is not the default one, so a hard-coded default cannot pass. +""" + +from __future__ import annotations + +import copy +import inspect +from typing import Any + +import pytest +from azure.cosmos.exceptions import CosmosResourceNotFoundError + +from azure.cosmos.agent_memory._container_routing import ContainerKey +from azure.cosmos.agent_memory.aio.store import AsyncMemoryStore +from azure.cosmos.agent_memory.exceptions import MemoryNotFoundError, ValidationError +from azure.cosmos.agent_memory.store import MemoryStore + +TENANT = "acme" +OTHER_TENANT = "globex" +USER = "u1" +TURNS, MEMORIES, SUMMARIES = ContainerKey.TURNS, ContainerKey.MEMORIES, ContainerKey.SUMMARIES +NO_KEYWORDS = "hello" +KEYWORDS = "hotels in lisbon" + + +class _Rows: + def __init__(self, items): + self._items = list(items) + + def __aiter__(self): + return self + + async def __anext__(self): + if not self._items: + raise StopAsyncIteration + return self._items.pop(0) + + +class _Container: + """An in-memory container that records what it is sent and answers like the SDK's, sync or async.""" + + def __init__(self, is_async: bool, docs=()): + self._is_async = is_async + self.docs = {self._key(doc): copy.deepcopy(doc) for doc in docs} + self.calls: list[tuple[str, dict[str, Any]]] = [] + + @staticmethod + def _key(doc): + return (doc["tenant_id"], doc["user_id"]), doc["id"] + + def _reply(self, value=None, error=None): + if not self._is_async: + if error is not None: + raise error + return value + + async def reply(): + if error is not None: + raise error + return value + + return reply() + + def _missing(self): + return self._reply(error=CosmosResourceNotFoundError(status_code=404, message="not found")) + + def sent(self, name: str) -> list[dict[str, Any]]: + return [kwargs for call, kwargs in self.calls if call == name] + + def query_items(self, **kwargs): + self.calls.append(("query_items", kwargs)) + return _Rows([]) if self._is_async else [] + + def read_item(self, *, item, partition_key): + self.calls.append(("read_item", {"item": item, "partition_key": partition_key})) + doc = self.docs.get((tuple(partition_key), item)) + return self._missing() if doc is None else self._reply(copy.deepcopy(doc)) + + def upsert_item(self, *, body, **kwargs): + self.calls.append(("upsert_item", {"body": body, **kwargs})) + self.docs[self._key(body)] = copy.deepcopy(body) + return self._reply(body) + + def replace_item(self, *, item, body, **kwargs): + self.calls.append(("replace_item", {"item": item, "body": body, **kwargs})) + if self._key(body) not in self.docs: + return self._missing() + self.docs[self._key(body)] = copy.deepcopy(body) + return self._reply(body) + + def delete_item(self, *, item, partition_key, **kwargs): + self.calls.append(("delete_item", {"item": item, "partition_key": partition_key, **kwargs})) + if self.docs.pop((tuple(partition_key), item), None) is None: + return self._missing() + return self._reply() + + +class _Embeddings: + def __init__(self, is_async: bool): + self._is_async = is_async + self.generated: list[str] = [] + + def _reply(self, value): + if not self._is_async: + return value + + async def reply(): + return value + + return reply() + + def generate(self, text): + self.generated.append(text) + return self._reply([0.1, 0.2]) + + def generate_batch(self, texts): + self.generated.extend(texts) + return self._reply([[0.1, 0.2] for _ in texts]) + + +def _record(**fields): + return { + "id": "m1", + "user_id": USER, + "thread_id": "t1", + "type": "fact", + "content": "I like tea", + "tags": ["a"], + **fields, + } + + +def _fact(tenant=TENANT, **fields): + return _record(tenant_id=tenant, **fields) + + +def _build(kind, *, tenant=TENANT, docs=None): + is_async = kind == "async" + containers = {key: _Container(is_async, (docs or {}).get(key, ())) for key in ContainerKey} + store_class = AsyncMemoryStore if is_async else MemoryStore + store = store_class(containers=containers, embeddings_client=_Embeddings(is_async), tenant_id=tenant) + return store, containers + + +async def _call(store, method, *args, **kwargs): + result = getattr(store, method)(*args, **kwargs) + return await result if inspect.isawaitable(result) else result + + +@pytest.fixture(params=["sync", "async"]) +def kind(request): + return request.param + + +def test_a_store_is_bound_to_one_tenant(kind): + store, _ = _build(kind) + + assert store.tenant_id == TENANT + with pytest.raises(AttributeError): + store.tenant_id = OTHER_TENANT + + +def test_a_store_without_a_tenant_uses_the_default_one(kind): + store_class = AsyncMemoryStore if kind == "async" else MemoryStore + + assert store_class(containers={key: object() for key in ContainerKey}).tenant_id == "default" + + +def test_a_store_rejects_an_invalid_tenant(kind): + store_class = AsyncMemoryStore if kind == "async" else MemoryStore + + with pytest.raises(ValidationError): + store_class(containers={key: object() for key in ContainerKey}, tenant_id="acme/emea") + + +# (method, args, kwargs, container, names the owner, reads the owner's partition) +READS = [ + pytest.param("get_memories", (), {"user_id": USER}, MEMORIES, True, True, id="get_memories"), + pytest.param("get_memories", (), {}, MEMORIES, False, False, id="get_memories-whole-tenant"), + pytest.param("get_thread", ("t1",), {"user_id": USER}, TURNS, True, True, id="get_thread"), + pytest.param("get_thread", ("t1",), {}, TURNS, False, False, id="get_thread-whole-tenant"), + pytest.param("get_thread_summary", (USER, "t1"), {}, SUMMARIES, True, True, id="get_thread_summary"), + pytest.param("get_episodes", (USER,), {}, MEMORIES, True, True, id="get_episodes"), + pytest.param("list_tags", (USER,), {}, MEMORIES, True, True, id="list_tags"), + pytest.param("get_procedural_prompt", (USER,), {}, MEMORIES, True, True, id="get_procedural_prompt"), + pytest.param("get_procedural_history", (USER,), {}, MEMORIES, True, True, id="get_procedural_history"), + pytest.param("get_procedural_memories", (USER,), {}, MEMORIES, True, True, id="get_procedural_memories"), + pytest.param("get_memory_history", ("m1", USER), {}, MEMORIES, True, True, id="get_memory_history"), + pytest.param("search", (NO_KEYWORDS,), {"user_id": USER}, MEMORIES, True, True, id="search"), + pytest.param("search", (KEYWORDS,), {"user_id": USER}, MEMORIES, True, False, id="search-keywords"), + pytest.param("search", (NO_KEYWORDS,), {}, MEMORIES, False, False, id="search-whole-tenant"), + pytest.param("search_turns", (NO_KEYWORDS,), {"user_id": USER}, TURNS, True, True, id="search_turns"), + pytest.param("search_turns", (KEYWORDS,), {"user_id": USER}, TURNS, True, False, id="search_turns-keywords"), + pytest.param("search_summaries", (NO_KEYWORDS,), {"user_id": USER}, SUMMARIES, True, True, id="search_summaries"), + pytest.param( + "search_summaries", (KEYWORDS,), {"user_id": USER}, SUMMARIES, True, False, id="search_summaries-keywords" + ), + pytest.param("search_episodic", (USER, NO_KEYWORDS), {}, MEMORIES, True, True, id="search_episodic"), + pytest.param("search_episodic", (USER, KEYWORDS), {}, MEMORIES, True, False, id="search_episodic-keywords"), + pytest.param("retrieve_procedures", (USER, NO_KEYWORDS), {}, MEMORIES, True, True, id="retrieve_procedures"), + pytest.param("retrieve_procedures", (USER, KEYWORDS), {}, MEMORIES, True, False, id="retrieve_procedures-keywords"), + pytest.param("build_episodic_context", (USER, NO_KEYWORDS), {}, MEMORIES, True, True, id="build_episodic_context"), +] + + +@pytest.mark.parametrize(("method", "args", "kwargs", "container", "names_owner", "in_partition"), READS) +async def test_every_read_filters_on_the_tenant(kind, method, args, kwargs, container, names_owner, in_partition): + store, containers = _build(kind) + + await _call(store, method, *args, **kwargs) + + for key, target in containers.items(): + assert bool(target.sent("query_items")) == (key == container), "a read queries only its own container" + (query,) = containers[container].sent("query_items") + params = {p["name"]: p["value"] for p in query["parameters"]} + where = query["query"].split(" WHERE ", 1)[1] + assert "c.tenant_id = @tenant_id" in where + assert params["@tenant_id"] == TENANT + if names_owner: + assert "c.user_id = @user_id" in where + assert params["@user_id"] == USER + else: + assert "c.user_id" not in where + if in_partition: + assert query["partition_key"] == [TENANT, USER] + else: + assert "partition_key" not in query + + +@pytest.mark.parametrize( + ("method", "args", "kwargs", "container"), + [ + pytest.param("get_thread", ("t1",), {"user_id": USER}, TURNS, id="get_thread"), + pytest.param("get_memory_history", ("m1", USER), {}, MEMORIES, id="get_memory_history"), + pytest.param("search", (KEYWORDS,), {"user_id": USER}, MEMORIES, id="search"), + pytest.param("search_turns", (KEYWORDS,), {"user_id": USER}, TURNS, id="search_turns"), + pytest.param("search_summaries", (KEYWORDS,), {"user_id": USER}, SUMMARIES, id="search_summaries"), + pytest.param("search_episodic", (USER, KEYWORDS), {}, MEMORIES, id="search_episodic"), + pytest.param("retrieve_procedures", (USER, KEYWORDS), {}, MEMORIES, id="retrieve_procedures"), + ], +) +async def test_projected_reads_return_the_tenant_of_each_record(kind, method, args, kwargs, container): + store, containers = _build(kind) + + await _call(store, method, *args, **kwargs) + + (query,) = containers[container].sent("query_items") + assert "c.tenant_id" in query["query"].split(" FROM ")[0] + + +POINT_OPERATIONS = [ + pytest.param("update", ("m1",), {"user_id": USER, "memory_type": "fact", "content": "I like coffee"}, id="update"), + pytest.param("delete", ("m1",), {"user_id": USER, "memory_type": "fact"}, id="delete"), + pytest.param("add_tags", ("m1", USER, "fact", ["b"]), {}, id="add_tags"), + pytest.param("remove_tags", ("m1", USER, "fact", ["a"]), {}, id="remove_tags"), +] + + +@pytest.mark.parametrize(("method", "args", "kwargs"), POINT_OPERATIONS) +async def test_point_operations_address_the_tenants_partition(kind, method, args, kwargs): + store, containers = _build(kind, docs={MEMORIES: [_fact()]}) + + await _call(store, method, *args, **kwargs) + + memories = containers[MEMORIES] + addressed = [*memories.sent("read_item"), *memories.sent("delete_item")] + assert addressed and all(call["partition_key"] == [TENANT, USER] for call in addressed) + assert memories.sent("replace_item") or memories.sent("delete_item") + + +async def test_the_user_summary_is_read_from_the_tenants_partition(kind): + summary = {"id": "user_summary_u1", "tenant_id": TENANT, "user_id": USER, "thread_id": "__user_summary__"} + store, containers = _build(kind, docs={SUMMARIES: [summary]}) + + assert (await _call(store, "get_user_summary", USER))["id"] == "user_summary_u1" + + assert containers[SUMMARIES].sent("read_item") == [{"item": "user_summary_u1", "partition_key": [TENANT, USER]}] + + +@pytest.mark.parametrize(("method", "args", "kwargs"), POINT_OPERATIONS) +async def test_another_tenants_record_with_the_same_owner_and_id_is_not_found(kind, method, args, kwargs): + store, containers = _build(kind, docs={MEMORIES: [_fact(OTHER_TENANT)]}) + + with pytest.raises(MemoryNotFoundError): + await _call(store, method, *args, **kwargs) + + assert not containers[MEMORIES].sent("replace_item") and not containers[MEMORIES].sent("delete_item") + assert list(containers[MEMORIES].docs) == [((OTHER_TENANT, USER), "m1")] + + +async def test_another_tenants_user_summary_is_not_found(kind): + summary = {"id": "user_summary_u1", "tenant_id": OTHER_TENANT, "user_id": USER, "thread_id": "__user_summary__"} + store, _ = _build(kind, docs={SUMMARIES: [summary]}) + + assert await _call(store, "get_user_summary", USER) is None + + +@pytest.mark.parametrize(("memory_type", "container"), [("turn", TURNS), ("fact", MEMORIES), ("episodic", MEMORIES)]) +async def test_add_writes_the_tenant_into_the_document(kind, memory_type, container): + store, containers = _build(kind) + + await _call(store, "add", user_id=USER, role="user", content="hello", memory_type=memory_type, thread_id="t1") + + (written,) = containers[container].sent("upsert_item") + assert written["body"]["tenant_id"] == TENANT + assert written["body"]["user_id"] == USER + + +@pytest.mark.parametrize( + ("memory_type", "container"), + [("turn", TURNS), ("fact", MEMORIES), ("thread_summary", SUMMARIES), ("user_summary", SUMMARIES)], +) +async def test_upsert_memory_stamps_the_tenant_and_leaves_the_callers_record_alone(kind, memory_type, container): + store, containers = _build(kind) + record = _record(type=memory_type) + + await _call(store, "upsert_memory", record) + + (written,) = containers[container].sent("upsert_item") + assert written["body"]["tenant_id"] == TENANT + assert "tenant_id" not in record + + +async def test_a_record_may_name_the_tenant_of_the_store(kind): + store, containers = _build(kind) + + await _call(store, "upsert_memory", _fact()) + + assert len(containers[MEMORIES].sent("upsert_item")) == 1 + + +async def test_upsert_memory_refuses_a_record_of_another_tenant(kind): + store, containers = _build(kind) + + with pytest.raises(ValidationError): + await _call(store, "upsert_memory", _fact(OTHER_TENANT)) + + assert not containers[MEMORIES].sent("upsert_item") + + +async def test_push_stamps_every_record_with_the_tenant(kind): + store, containers = _build(kind) + + await _call(store, "push", [_record(id="t1", type="turn"), _record(id="f1")]) + + assert [call["body"]["tenant_id"] for call in containers[TURNS].sent("upsert_item")] == [TENANT] + assert [call["body"]["tenant_id"] for call in containers[MEMORIES].sent("upsert_item")] == [TENANT] + + +async def test_push_refuses_a_batch_with_a_record_of_another_tenant_before_writing_any_of_it(kind): + store, containers = _build(kind) + + with pytest.raises(ValidationError): + await _call(store, "push", [_fact(id="f1"), _fact(OTHER_TENANT, id="f2")]) + + assert not containers[MEMORIES].sent("upsert_item") + + +INVALID_OWNERS = ["", "a/b", "x#y", "tab\there", "o" * 257] + + +@pytest.mark.parametrize("owner", INVALID_OWNERS) +async def test_add_refuses_an_invalid_owner_before_embedding_or_writing(kind, owner): + store, containers = _build(kind) + + with pytest.raises(ValidationError, match="user_id"): + await _call(store, "add", user_id=owner, role="system", content="I like tea", memory_type="fact") + + assert store._embeddings_client.generated == [] + assert not containers[MEMORIES].sent("upsert_item") + + +@pytest.mark.parametrize("owner", [None, *INVALID_OWNERS]) +async def test_upsert_memory_refuses_a_record_without_a_valid_owner(kind, owner): + store, containers = _build(kind) + + with pytest.raises(ValidationError, match="user_id"): + await _call(store, "upsert_memory", _fact(user_id=owner, embedding=[0.1])) + + assert store._embeddings_client.generated == [] + assert not containers[MEMORIES].sent("upsert_item") + + +async def test_push_refuses_a_batch_with_a_record_without_a_valid_owner_before_embedding_or_writing_any_of_it(kind): + store, containers = _build(kind) + + with pytest.raises(ValidationError, match="user_id"): + await _call(store, "push", [_fact(id="f1"), _fact(id="f2", user_id="a/b")]) + + assert store._embeddings_client.generated == [] + assert not containers[MEMORIES].sent("upsert_item") + + +@pytest.mark.parametrize("owner", INVALID_OWNERS) +async def test_a_read_for_an_invalid_owner_is_refused_rather_than_widened_to_the_tenant(kind, owner): + store, containers = _build(kind) + + with pytest.raises(ValidationError, match="user_id"): + await _call(store, "get_memories", user_id=owner) + + assert not containers[MEMORIES].sent("query_items") + + +async def test_mark_superseded_keeps_the_tenant_and_refuses_another(kind): + store, containers = _build(kind, docs={MEMORIES: [_fact(), _fact(OTHER_TENANT)]}) + + assert await _call(store, "mark_superseded", _fact(_etag="e1"), "f2", reason="duplicate") is True + with pytest.raises(ValidationError): + await _call(store, "mark_superseded", _fact(OTHER_TENANT, _etag="e1"), "f2", reason="duplicate") + + (replaced,) = containers[MEMORIES].sent("replace_item") + assert replaced["body"]["tenant_id"] == TENANT + assert containers[MEMORIES].docs[(OTHER_TENANT, USER), "m1"].get("superseded_by") is None diff --git a/tests/unit/store/test_update_embedding_fallback.py b/tests/unit/store/test_update_embedding_fallback.py index 47b9cb6..0ceaf16 100644 --- a/tests/unit/store/test_update_embedding_fallback.py +++ b/tests/unit/store/test_update_embedding_fallback.py @@ -31,7 +31,7 @@ def __init__(self, *docs: dict[str, Any]) -> None: def _save(self, body: dict[str, Any]) -> dict[str, Any]: saved = {**copy.deepcopy(body), "_etag": f"etag-{next(self._etags)}"} - self._docs[saved["id"], (saved["user_id"], saved["thread_id"])] = saved + self._docs[saved["id"], (saved["tenant_id"], saved["user_id"])] = saved return copy.deepcopy(saved) def read_item(self, item: str, partition_key: list[str], **_kwargs: Any) -> dict[str, Any]: @@ -45,7 +45,7 @@ def read_item(self, item: str, partition_key: list[str], **_kwargs: Any) -> dict def replace_item( self, item: str, body: dict[str, Any], *, match_condition: Any = None, etag: Any = None, **_kwargs: Any ) -> dict[str, Any]: - current = self.read_item(item, [body["user_id"], body["thread_id"]]) + current = self.read_item(item, [body["tenant_id"], body["user_id"]]) if match_condition == MatchConditions.IfNotModified and etag != current["_etag"]: raise CosmosAccessConditionFailedError(status_code=412, message="Precondition failed") return self._save(body) @@ -68,6 +68,7 @@ def generate(self, text: str) -> list[float]: def _fact(content: str, embedding: list[float]) -> dict[str, Any]: return { "id": "fact_1", + "tenant_id": "default", "user_id": "u1", "thread_id": "t1", "type": "fact", @@ -96,16 +97,16 @@ def test_a_failed_re_embed_keeps_the_record_in_vector_search_and_a_later_edit_re store = _store(memories, embedder) embedder.available = False - store.update("fact_1", user_id="u1", thread_id="t1", memory_type="fact", content="I like green tea") + store.update("fact_1", user_id="u1", memory_type="fact", content="I like green tea") - stored = memories.read_item("fact_1", ["u1", "t1"]) + stored = memories.read_item("fact_1", ["default", "u1"]) assert stored["content"] == "I like green tea" assert stored["embedding"] == [10.0, 1.0], "the previous vector stays, so the record is still found" embedder.available = True - store.update("fact_1", user_id="u1", thread_id="t1", memory_type="fact", content="I like oolong tea") + store.update("fact_1", user_id="u1", memory_type="fact", content="I like oolong tea") - stored = memories.read_item("fact_1", ["u1", "t1"]) + stored = memories.read_item("fact_1", ["default", "u1"]) assert stored["embedding"] == [float(len("I like oolong tea")), 1.0] assert embedder.texts == ["I like green tea", "I like oolong tea"] @@ -123,7 +124,7 @@ def test_an_etag_conflict_retry_drops_a_re_read_vector_built_from_a_secret_when_ memories.replace_item.side_effect = [CosmosAccessConditionFailedError(message="412", response=None), None] store = MemoryStore(containers=_containers(memories=memories), embeddings_client=_failing_embedder()) - store.update("m1", user_id="u1", thread_id="t1", memory_type="fact", metadata={"note": "rotated"}) + store.update("m1", user_id="u1", memory_type="fact", metadata={"note": "rotated"}) body = memories.replace_item.call_args.kwargs["body"] assert memories.replace_item.call_count == 2 diff --git a/tests/unit/test_auto_trigger.py b/tests/unit/test_auto_trigger.py index ddab91a..64bab5b 100644 --- a/tests/unit/test_auto_trigger.py +++ b/tests/unit/test_auto_trigger.py @@ -16,20 +16,26 @@ from azure.cosmos.agent_memory.cosmos_memory_client import CosmosMemoryClient from azure.cosmos.agent_memory.processors import DurableFunctionProcessor, InProcessProcessor +TENANT = "acme" + class _FakeCounterContainer: """Minimal in-memory stand-in for the Cosmos counter container. Exercises the REAL increment / watermark-read / watermark-advance helpers end-to-end (no mocking of counter math), so a watermark/recent_k regression - can't slip through behind constant mocks. + can't slip through behind constant mocks. It records the partition each + read and patch asks for. """ def __init__(self) -> None: self.store: dict[str, dict] = {} + self.partitions_read: list[list[str]] = [] + self.partitions_patched: list[list[str]] = [] self._etag = 0 def read_item(self, *, item, partition_key): + self.partitions_read.append(partition_key) if item not in self.store: raise CosmosResourceNotFoundError(message="404") return dict(self.store[item]) @@ -49,14 +55,15 @@ def upsert_item(self, *, body, **_kwargs): return dict(body) def patch_item(self, *, item, partition_key, patch_operations): + self.partitions_patched.append(partition_key) doc = self.store.setdefault(item, {"id": item}) for op in patch_operations: doc[op["path"].lstrip("/")] = op["value"] return dict(doc) -def _connected(processor=None) -> CosmosMemoryClient: - client = CosmosMemoryClient(use_default_credential=False, processor=processor) +def _connected(processor=None, **client_kwargs) -> CosmosMemoryClient: + client = CosmosMemoryClient(use_default_credential=False, processor=processor, **client_kwargs) client._memories_container_client = MagicMock() client._turns_container_client = client._memories_container_client client._summaries_container_client = client._memories_container_client @@ -176,6 +183,7 @@ def test_episode_zero_does_not_fire(self): maybe_trigger_steps( processor, counter_container, + TENANT, {("u1", "t1"): 1}, thresholds={ "FACT_EXTRACTION_EVERY_N": 0, @@ -201,10 +209,10 @@ def test_episode_fires_when_threshold_crossed(self): "MEMORY_PROCESSOR_OWNER": "inprocess", } - maybe_trigger_steps(processor, counter_container, {("u1", "t1"): 2}, thresholds=thresholds) + maybe_trigger_steps(processor, counter_container, TENANT, {("u1", "t1"): 2}, thresholds=thresholds) processor.process_extract_episodes.assert_not_called() - maybe_trigger_steps(processor, counter_container, {("u1", "t1"): 1}, thresholds=thresholds) + maybe_trigger_steps(processor, counter_container, TENANT, {("u1", "t1"): 1}, thresholds=thresholds) processor.process_extract_episodes.assert_called_once_with(user_id="u1", thread_id="t1") @@ -218,6 +226,7 @@ def test_episode_failure_is_caught_and_other_steps_continue(self): maybe_trigger_steps( processor, counter_container, + TENANT, {("u1", "t1"): 1}, thresholds={ "FACT_EXTRACTION_EVERY_N": 0, @@ -410,3 +419,74 @@ def test_inprocess_owner_allows_sdk_trigger(self, monkeypatch): client.push_to_cosmos() processor.process_extract_memories.assert_called_once() + + +# --------------------------------------------------------------------------- +# Tenant - every counter the auto-trigger reads, writes or stamps is in the +# client's tenant, in the partition of the owner it counts. +# --------------------------------------------------------------------------- + +_THREAD_AND_USER_STEPS = { + "FACT_EXTRACTION_EVERY_N": 1, + "THREAD_SUMMARY_EVERY_N": 0, + "EPISODE_EVAL_EVERY_N": 0, + "USER_SUMMARY_EVERY_N": 1, + "DEDUP_EVERY_N": 0, + "MEMORY_PROCESSOR_OWNER": "inprocess", +} + + +class TestCountersFollowTheTenant: + def test_thread_and_user_counters_live_in_the_tenant_and_owner_partition(self): + processor = InProcessProcessor(pipeline=MagicMock()) + processor.process_extract_memories = MagicMock(return_value={}) + processor.process_user_summary = MagicMock() + counters = _FakeCounterContainer() + + maybe_trigger_steps(processor, counters, TENANT, {("u1", "t1"): 1}, thresholds=_THREAD_AND_USER_STEPS) + + assert {(doc["tenant_id"], doc["user_id"], doc["thread_id"]) for doc in counters.store.values()} == { + (TENANT, "u1", "t1"), + (TENANT, "u1", "__counters__"), + } + assert counters.partitions_read == [[TENANT, "u1"], [TENANT, "u1"]] + + def test_a_failed_step_is_stamped_in_the_tenant_and_owner_partition(self): + processor = InProcessProcessor(pipeline=MagicMock()) + processor.process_extract_memories = MagicMock(side_effect=RuntimeError("boom")) + processor.process_user_summary = MagicMock(side_effect=RuntimeError("boom")) + counters = _FakeCounterContainer() + + maybe_trigger_steps(processor, counters, TENANT, {("u1", "t1"): 1}, thresholds=_THREAD_AND_USER_STEPS) + + assert counters.partitions_patched == [[TENANT, "u1"], [TENANT, "u1"]] + assert counters.store["thread:u1:t1"]["last_failure_reason"].startswith("process_extract_memories: ") + assert counters.store["user:u1"]["last_failure_reason"].startswith("process_user_summary: ") + + def test_a_client_counts_the_turns_it_pushes_in_its_own_tenant(self, monkeypatch): + monkeypatch.setenv("FACT_EXTRACTION_EVERY_N", "1") + monkeypatch.setenv("THREAD_SUMMARY_EVERY_N", "0") + monkeypatch.setenv("EPISODE_EVAL_EVERY_N", "0") + monkeypatch.setenv("USER_SUMMARY_EVERY_N", "0") + processor = InProcessProcessor(pipeline=MagicMock()) + processor.process_extract_memories = MagicMock(return_value={}) + client = _connected(processor=processor, tenant_id=TENANT) + counters = client._counter_container_client = _FakeCounterContainer() + + client.add_local(user_id="u1", role="user", thread_id="t1", content="hi") + client.push_to_cosmos() + + [counter] = counters.store.values() + assert (counter["tenant_id"], counter["user_id"], counter["thread_id"]) == (TENANT, "u1", "t1") + assert counters.partitions_read == [[TENANT, "u1"]] + + def test_a_client_hands_its_tenant_to_the_trigger(self): + client = CosmosMemoryClient(use_default_credential=False, tenant_id=TENANT) + processor, counters = MagicMock(), MagicMock() + client._get_processor = MagicMock(return_value=processor) + client._get_counter_container = MagicMock(return_value=counters) + + with patch("azure.cosmos.agent_memory.cosmos_memory_client.maybe_trigger_steps") as trigger: + client._maybe_auto_trigger({("u1", "t1"): 1}) + + assert trigger.call_args.args == (processor, counters, TENANT, {("u1", "t1"): 1}) diff --git a/tests/unit/test_cosmos_memory_client.py b/tests/unit/test_cosmos_memory_client.py index 764ea6c..0b8a373 100644 --- a/tests/unit/test_cosmos_memory_client.py +++ b/tests/unit/test_cosmos_memory_client.py @@ -2,16 +2,20 @@ from __future__ import annotations +import inspect import uuid from datetime import datetime, timezone +from types import SimpleNamespace from unittest.mock import MagicMock, patch import pytest +from azure.cosmos.agent_memory._partitioning import DEFAULT_TENANT_ID, PARTITION_KEY_PATHS from azure.cosmos.agent_memory.cosmos_memory_client import CosmosMemoryClient from azure.cosmos.agent_memory.exceptions import ( ConfigurationError, CosmosNotConnectedError, + CosmosOperationError, MemoryNotFoundError, ValidationError, ) @@ -20,6 +24,14 @@ # Helpers # --------------------------------------------------------------------------- +EARLIER_KEY = ["/user_id", "/thread_id"] + + +def _keyed_container(paths=PARTITION_KEY_PATHS, container_id="container") -> MagicMock: + """A container whose metadata names its partition key, as ``read()`` returns it.""" + properties = {"id": container_id, "partitionKey": {"paths": list(paths), "kind": "MultiHash", "version": 2}} + return MagicMock(id=container_id, read=MagicMock(return_value=properties)) + def _make_client(**overrides) -> CosmosMemoryClient: """Build a CosmosMemoryClient with credential auto-resolution disabled.""" @@ -28,9 +40,9 @@ def _make_client(**overrides) -> CosmosMemoryClient: return CosmosMemoryClient(**defaults) -def _connected_client() -> tuple[CosmosMemoryClient, MagicMock]: +def _connected_client(**client_kwargs) -> tuple[CosmosMemoryClient, MagicMock]: """Return a client with mocked split containers already wired up.""" - client = _make_client() + client = _make_client(**client_kwargs) container = MagicMock() turns = MagicMock() summaries = MagicMock() @@ -90,6 +102,42 @@ def test_no_credential_when_flag_false(self): assert mem._ai_foundry_credential is None +# =================================================================== +# Tenant binding +# =================================================================== + + +class TestTenant: + def test_a_client_is_bound_to_the_default_tenant_unless_given_one(self): + assert _make_client().tenant_id == DEFAULT_TENANT_ID + + def test_the_tenant_is_the_constructor_argument(self): + assert _make_client(tenant_id="acme").tenant_id == "acme" + + @pytest.mark.parametrize("tenant_id", ["", "a/b", 7]) + def test_a_tenant_that_cannot_be_stored_is_refused(self, tenant_id): + with pytest.raises(ValidationError): + _make_client(tenant_id=tenant_id) + + def test_the_tenant_cannot_be_changed_after_construction(self): + mem = _make_client(tenant_id="acme") + + with pytest.raises(AttributeError): + mem.tenant_id = "globex" + + def test_the_store_and_the_pipeline_are_bound_to_the_clients_tenant(self): + mem, _ = _connected_client(tenant_id="acme") + + assert mem._get_store().tenant_id == "acme" + assert mem._get_pipeline()._tenant_id == "acme" + + @pytest.mark.parametrize( + "method", ["update_cosmos", "delete_memory", "delete_turn", "add_tags", "remove_tags", "get_memory_history"] + ) + def test_a_memory_is_addressed_by_its_owner_not_its_thread(self, method): + assert "thread_id" not in inspect.signature(getattr(CosmosMemoryClient, method)).parameters + + # =================================================================== # Injected embeddings / chat clients # =================================================================== @@ -206,14 +254,14 @@ def test_add_local_turn_requires_thread_id(self): with pytest.raises(ValidationError, match="thread_id is required"): mem.add_local(user_id="u1", role="user", content="hi") # Validation must run BEFORE append - otherwise an orphan turn - # with thread_id=None would persist and pollute pk on push. + # with no thread_id would be buffered and pushed. assert mem.local_memory == [] assert mem._unflushed_turn_counts == {} def test_add_local_non_turn_thread_id_optional(self): mem = _make_client() # Non-turn types (thread_summary, fact, etc.) accept an omitted thread_id; - # _make_memory auto-generates a UUID for hierarchical-PK validity. + # _make_memory auto-generates a UUID for it. mem.add_local(user_id="u1", role="user", content="profile", memory_type="user_summary") assert len(mem.local_memory) == 1 @@ -416,20 +464,37 @@ def test_preferred_locations_read_from_environment(self, monkeypatch, entry_poin class TestValidateTopology: - def test_validate_topology_succeeds_on_healthy_deploy(self): + CONTAINER_ATTRIBUTES = { + "memories": "_memories_container_client", + "memories_turns": "_turns_container_client", + "memories_summaries": "_summaries_container_client", + "counter": "_counter_container_client", + } + + def _connected(self, earlier=None): mem = _make_client() - memories = MagicMock(id="memories") - turns = MagicMock(id="memories_turns") - summaries = MagicMock(id="memories_summaries") - mem._memories_container_client = memories - mem._turns_container_client = turns - mem._summaries_container_client = summaries + containers = { + name: _keyed_container(EARLIER_KEY if name == earlier else PARTITION_KEY_PATHS, container_id=name) + for name in self.CONTAINER_ATTRIBUTES + } + for name, attribute in self.CONTAINER_ATTRIBUTES.items(): + setattr(mem, attribute, containers[name]) + return mem, containers + + def test_validate_topology_succeeds_on_healthy_deploy(self): + mem, containers = self._connected() mem.validate_topology() - memories.read.assert_called_once() - turns.read.assert_called_once() - summaries.read.assert_called_once() + for container in containers.values(): + container.read.assert_called_once() + + @pytest.mark.parametrize("earlier", ["memories", "memories_turns", "memories_summaries", "counter"]) + def test_validate_topology_raises_on_a_container_with_the_earlier_key(self, earlier): + mem, _ = self._connected(earlier) + + with pytest.raises(RuntimeError, match=rf"validate_topology: container '{earlier}' has partition key"): + mem.validate_topology() def test_validate_topology_raises_on_missing_container(self): from azure.cosmos.exceptions import CosmosResourceNotFoundError @@ -451,6 +516,80 @@ def test_validate_topology_raises_when_not_connected(self): class TestCreateMemoryStore: + @staticmethod + def _created_containers() -> list[dict]: + """The arguments of the five ``create_container_if_not_exists`` calls ``create_memory_store`` makes.""" + mock_client = MagicMock() + mock_db = mock_client.create_database_if_not_exists.return_value + partition_key = MagicMock(side_effect=lambda **kwargs: SimpleNamespace(**kwargs)) + with patch.dict( + "sys.modules", + { + "azure.cosmos": MagicMock( + CosmosClient=MagicMock(return_value=mock_client), + PartitionKey=partition_key, + ThroughputProperties=MagicMock(), + ), + }, + ): + _make_client().create_memory_store(endpoint="https://fake.documents.azure.com:443/", credential="fake-key") + return [call.kwargs for call in mock_db.create_container_if_not_exists.call_args_list] + + def test_the_containers_are_partitioned_by_tenant_and_user(self): + memories, turns, summaries, counter, leases = self._created_containers() + + for container in (memories, turns, summaries, counter): + assert container["partition_key"].path == ["/tenant_id", "/user_id"] + assert container["partition_key"].kind == "MultiHash" + assert leases["partition_key"].path == "/id" + + def test_the_summaries_composite_index_starts_with_the_partition_key(self): + summaries = self._created_containers()[2] + + assert summaries["indexing_policy"]["compositeIndexes"] == [ + [ + {"path": "/tenant_id", "order": "ascending"}, + {"path": "/user_id", "order": "ascending"}, + {"path": "/thread_id", "order": "ascending"}, + {"path": "/version", "order": "descending"}, + ] + ] + + @pytest.mark.parametrize("earlier", ["memories", "memories_turns", "memories_summaries", "counter"]) + def test_an_existing_container_with_the_earlier_key_is_refused(self, earlier): + containers = { + name: _keyed_container(container_id=name) + for name in ("memories", "memories_turns", "memories_summaries", "counter") + } + containers[earlier] = _keyed_container(EARLIER_KEY, container_id=earlier) + mock_client = MagicMock() + mock_client.create_database_if_not_exists.return_value.create_container_if_not_exists.side_effect = [ + *containers.values(), + MagicMock(), + ] + mem = _make_client() + with patch.dict( + "sys.modules", + { + "azure.cosmos": MagicMock( + CosmosClient=MagicMock(return_value=mock_client), + PartitionKey=MagicMock(), + ThroughputProperties=MagicMock(), + ), + }, + ): + with pytest.raises( + CosmosOperationError, + match=rf"container '{earlier}' has partition key \['/user_id', '/thread_id'\].*recreate the container", + ): + mem.create_memory_store(endpoint="https://fake.documents.azure.com:443/", credential="fake-key") + + mock_client.close.assert_called_once() + assert mem._cosmos_client is None + assert mem._memories_container_client is None + with pytest.raises(CosmosNotConnectedError): + mem._require_cosmos() + def test_create_memory_store_with_custom_dimensions(self): """Explicit create_memory_store() call with custom embedding dimensions.""" mock_cosmos_cls = MagicMock() @@ -956,18 +1095,19 @@ def test_with_recent_k(self, sample_memory_dicts): class TestUpdateCosmos: def test_success(self): - mem, container = _connected_client() - doc = _make_doc(id="m1", type="fact") + mem, container = _connected_client(tenant_id="acme") + doc = _make_doc(id="m1", type="fact", tenant_id="acme") container.read_item = MagicMock(return_value=doc.copy()) container.replace_item = MagicMock() - mem.update_cosmos(memory_id="m1", user_id="u1", thread_id="t1", memory_type="fact", content="updated") + mem.update_cosmos(memory_id="m1", user_id="u1", memory_type="fact", content="updated") - container.read_item.assert_called_once_with(item="m1", partition_key=["u1", "t1"]) + container.read_item.assert_called_once_with(item="m1", partition_key=["acme", "u1"]) container.replace_item.assert_called_once() body = container.replace_item.call_args.kwargs["body"] assert body["content"] == "updated" assert body["type"] == "fact" + assert body["tenant_id"] == "acme" assert "updated_at" in body def test_not_found(self): @@ -977,18 +1117,18 @@ def test_not_found(self): container.read_item = MagicMock(side_effect=CosmosResourceNotFoundError(message="404")) with pytest.raises(MemoryNotFoundError): - mem.update_cosmos(memory_id="no-such-id", user_id="u1", thread_id="t1", memory_type="fact", content="x") + mem.update_cosmos(memory_id="no-such-id", user_id="u1", memory_type="fact", content="x") class TestDeleteCosmos: def test_success(self): - mem, container = _connected_client() - container.read_item = MagicMock(return_value=_make_doc(id="m1", type="fact")) + mem, container = _connected_client(tenant_id="acme") + container.read_item = MagicMock(return_value=_make_doc(id="m1", type="fact", tenant_id="acme")) container.delete_item = MagicMock() - mem.delete_memory(memory_id="m1", user_id="u1", thread_id="t1", memory_type="fact") + mem.delete_memory(memory_id="m1", user_id="u1", memory_type="fact") - container.delete_item.assert_called_once_with(item="m1", partition_key=["u1", "t1"]) + container.delete_item.assert_called_once_with(item="m1", partition_key=["acme", "u1"]) def test_not_found(self): from azure.cosmos.exceptions import CosmosResourceNotFoundError @@ -998,23 +1138,23 @@ def test_not_found(self): container.delete_item = MagicMock() with pytest.raises(MemoryNotFoundError): - mem.delete_memory(memory_id="nope", user_id="u1", thread_id="t1", memory_type="fact") + mem.delete_memory(memory_id="nope", user_id="u1", memory_type="fact") container.delete_item.assert_not_called() class TestGetUserSummary: def test_returns_doc_when_present(self): - mem, _ = _connected_client() + mem, _ = _connected_client(tenant_id="acme") summaries = mem._summaries_container_client - doc = _make_doc(type="user_summary", id="user_summary_u1") + doc = _make_doc(type="user_summary", id="user_summary_u1", tenant_id="acme") summaries.read_item.return_value = doc result = mem.get_user_summary(user_id="u1") call_kwargs = summaries.read_item.call_args.kwargs assert call_kwargs["item"] == "user_summary_u1" - assert call_kwargs["partition_key"] == ["u1", "__user_summary__"] + assert call_kwargs["partition_key"] == ["acme", "u1"] assert result == doc def test_returns_none_when_absent(self): @@ -1205,9 +1345,9 @@ def test_cosmos_ops_without_connect(self): with pytest.raises(CosmosNotConnectedError): mem.get_thread(thread_id="t1") with pytest.raises(CosmosNotConnectedError): - mem.update_cosmos(memory_id="m1", user_id="u1", thread_id="t1", memory_type="fact") + mem.update_cosmos(memory_id="m1", user_id="u1", memory_type="fact") with pytest.raises(CosmosNotConnectedError): - mem.delete_memory(memory_id="m1", user_id="u1", thread_id="t1", memory_type="fact") + mem.delete_memory(memory_id="m1", user_id="u1", memory_type="fact") # =================================================================== @@ -1243,14 +1383,16 @@ def test_context_manager(self): def test_list_tags_delegates_to_store(): - mem, container = _connected_client() + mem, container = _connected_client(tenant_id="acme") container.query_items.return_value = [["topic:python", "sys:fact"]] assert mem.list_tags("u1") == ["topic:python"] kwargs = container.query_items.call_args.kwargs assert "SELECT VALUE c.tags" in kwargs["query"] - assert kwargs["parameters"] == [{"name": "@user_id", "value": "u1"}] + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in kwargs["query"] + assert kwargs["parameters"] == [{"name": "@tenant_id", "value": "acme"}, {"name": "@user_id", "value": "u1"}] + assert kwargs["partition_key"] == ["acme", "u1"] class TestSyncCadenceThresholdsForwarding: @@ -1313,29 +1455,25 @@ class TestDeleteHelpers: def test_delete_turn_delegates_with_turn_type(self): mem = _make_client() mem.delete_memory = MagicMock() - mem.delete_turn("turn-1", user_id="u1", thread_id="t1") - mem.delete_memory.assert_called_once_with("turn-1", user_id="u1", thread_id="t1", memory_type="turn") + mem.delete_turn("turn-1", user_id="u1") + mem.delete_memory.assert_called_once_with("turn-1", user_id="u1", memory_type="turn") def test_delete_thread_summary_uses_deterministic_id_and_returns_true(self): mem = _make_client() mem.delete_memory = MagicMock() assert mem.delete_thread_summary("u1", "t1") is True - mem.delete_memory.assert_called_once_with( - "summary_u1_t1", user_id="u1", thread_id="t1", memory_type="thread_summary" - ) + mem.delete_memory.assert_called_once_with("summary_u1_t1", user_id="u1", memory_type="thread_summary") def test_delete_thread_summary_missing_returns_false(self): mem = _make_client() - mem.delete_memory = MagicMock(side_effect=MemoryNotFoundError(memory_id="x", user_id="u1", thread_id="t1")) + mem.delete_memory = MagicMock(side_effect=MemoryNotFoundError(memory_id="x", user_id="u1")) assert mem.delete_thread_summary("u1", "t1") is False - def test_delete_user_summary_uses_deterministic_id_and_scope(self): + def test_delete_user_summary_uses_deterministic_id(self): mem = _make_client() mem.delete_memory = MagicMock() assert mem.delete_user_summary("u1") is True - mem.delete_memory.assert_called_once_with( - "user_summary_u1", user_id="u1", thread_id="__user_summary__", memory_type="user_summary" - ) + mem.delete_memory.assert_called_once_with("user_summary_u1", user_id="u1", memory_type="user_summary") def test_delete_thread_deletes_turns_and_summary_and_counts(self): mem = _make_client() @@ -1360,7 +1498,7 @@ def test_delete_thread_skips_missing_turn(self): def _delete(memory_id, **kwargs): if memory_id == "turn-1": - raise MemoryNotFoundError(memory_id="turn-1", user_id="u1", thread_id="t1") + raise MemoryNotFoundError(memory_id="turn-1", user_id="u1") mem.delete_memory = MagicMock(side_effect=_delete) deleted = mem.delete_thread("u1", "t1", include_summary=False) @@ -1372,3 +1510,95 @@ def test_delete_thread_requires_ids(self): mem.delete_thread("", "t1") with pytest.raises(ValidationError): mem.delete_thread("u1", "") + + +# =================================================================== +# Tenant isolation: a client bound to a tenant reads, writes and deletes only inside it +# =================================================================== + +_READS = { + "get_memories": lambda mem: mem.get_memories(user_id="u1", thread_id="t1"), + "get_memories_of_every_user": lambda mem: mem.get_memories(), + "get_thread": lambda mem: mem.get_thread(thread_id="t1", user_id="u1"), + "get_thread_of_every_user": lambda mem: mem.get_thread(thread_id="t1"), + "get_thread_summary": lambda mem: mem.get_thread_summary("u1", "t1"), + "get_episodes": lambda mem: mem.get_episodes("u1"), + "list_tags": lambda mem: mem.list_tags("u1"), + "get_procedural_memories": lambda mem: mem.get_procedural_memories("u1"), + "get_procedural_history": lambda mem: mem.get_procedural_history("u1"), + "get_memory_history": lambda mem: mem.get_memory_history("m1", "u1"), + "search_cosmos": lambda mem: mem.search_cosmos("weather", user_id="u1"), + "search_cosmos_by_keywords_of_every_user": lambda mem: mem.search_cosmos("weather Seattle"), + "search_turns": lambda mem: mem.search_turns("weather", user_id="u1", thread_id="t1"), + "search_summaries": lambda mem: mem.search_summaries("weather", user_id="u1"), + "search_episodic_memories": lambda mem: mem.search_episodic_memories("u1", "weather"), + "retrieve_procedures": lambda mem: mem.retrieve_procedures("u1", "weather"), +} + + +class TestTenantIsolation: + @pytest.mark.parametrize("read", _READS.values(), ids=_READS.keys()) + def test_every_query_a_read_sends_is_confined_to_the_tenant(self, read): + mem, _ = _connected_client(tenant_id="acme") + mem._embeddings_client = MagicMock() + mem._embeddings_client.generate.return_value = [0.1, 0.2, 0.3] + + read(mem) + + sent = [ + call.kwargs + for container in ( + mem._memories_container_client, + mem._turns_container_client, + mem._summaries_container_client, + ) + for call in container.query_items.call_args_list + ] + assert sent + for query in sent: + assert "c.tenant_id = @tenant_id" in query["query"] + assert {"name": "@tenant_id", "value": "acme"} in query["parameters"] + assert query.get("partition_key") in (None, ["acme", "u1"]) + + def test_a_written_turn_carries_the_tenant(self): + mem, _ = _connected_client(tenant_id="acme") + mem._maybe_auto_trigger = MagicMock() + + mem.upsert_memory(user_id="u1", role="user", content="hello", thread_id="t1") + + body = mem._turns_container_client.upsert_item.call_args.kwargs["body"] + assert (body["tenant_id"], body["user_id"], body["thread_id"]) == ("acme", "u1", "t1") + + def test_pushed_memories_carry_the_tenant(self): + mem, memories = _connected_client(tenant_id="acme") + mem.add_local(user_id="u1", role="user", content="prefers dark mode", memory_type="fact") + mem.add_local(user_id="u1", role="user", content="hello", thread_id="t1") + + mem.push_to_cosmos() + + written = [*memories.upsert_item.call_args_list, *mem._turns_container_client.upsert_item.call_args_list] + assert [call.kwargs["body"]["tenant_id"] for call in written] == ["acme", "acme"] + + def test_a_record_that_names_another_tenant_is_refused(self): + mem, memories = _connected_client(tenant_id="acme") + mem.add_local(user_id="u1", role="user", content="prefers dark mode", memory_type="fact") + mem.local_memory[0]["tenant_id"] = "globex" + + with pytest.raises(ValidationError): + mem.push_to_cosmos() + + memories.upsert_item.assert_not_called() + + def test_a_thread_is_deleted_from_the_owners_partition_of_the_tenant(self): + mem, _ = _connected_client(tenant_id="acme") + turns, summaries = mem._turns_container_client, mem._summaries_container_client + turn = _make_doc(id="turn-1", tenant_id="acme") + turns.query_items.return_value = [turn] + turns.read_item.return_value = turn + summaries.read_item.return_value = _make_doc(id="summary_u1_t1", type="thread_summary", tenant_id="acme") + + assert mem.delete_thread("u1", "t1") == 2 + + for container in (turns, summaries): + container.delete_item.assert_called_once() + assert container.delete_item.call_args.kwargs["partition_key"] == ["acme", "u1"] diff --git a/tests/unit/test_counters.py b/tests/unit/test_counters.py index f25a6ab..0c08b31 100644 --- a/tests/unit/test_counters.py +++ b/tests/unit/test_counters.py @@ -1,21 +1,37 @@ """Tests for ``azure.cosmos.agent_memory._counters``. -Covers counter-doc construction (LSN preservation, failure breadcrumbs) -and ``stamp_failure_sync`` - the helpers that let SDK and FA share a -counter container without trampling each other. +Covers counter-doc construction (LSN preservation, failure breadcrumbs), +``stamp_failure_sync`` - the helpers that let SDK and FA share a counter +container without trampling each other - and the ``[tenant_id, user_id]`` +partition every counter lives in. """ from __future__ import annotations +from typing import Any from unittest.mock import MagicMock -from azure.cosmos.agent_memory._counters import _build_counter_doc, stamp_failure_sync +from azure.cosmos.exceptions import CosmosResourceNotFoundError + +from azure.cosmos.agent_memory._counters import ( + USER_COUNTER_THREAD_ID, + _build_counter_doc, + increment_counter_async, + increment_counter_sync, + stamp_failure_async, + stamp_failure_sync, + thread_counter_id, + user_counter_id, +) + +TENANT = "acme" class TestBuildCounterDoc: def test_first_write_initializes_lsn_none(self): doc = _build_counter_doc( counter_id="thread:u:t", + tenant_id=TENANT, user_id="u", thread_id="t", new_count=1, @@ -26,6 +42,18 @@ def test_first_write_initializes_lsn_none(self): assert doc["last_batch_lsn"] is None assert "last_failure_at" not in doc + def test_carries_the_tenant(self): + doc = _build_counter_doc( + counter_id="thread:u:t", + tenant_id=TENANT, + user_id="u", + thread_id="t", + new_count=1, + old_count=0, + existing=None, + ) + assert (doc["tenant_id"], doc["user_id"], doc["thread_id"]) == (TENANT, "u", "t") + def test_preserves_fa_lsn(self): """SDK writes must not clobber an LSN seeded by the FA-side helper. @@ -36,6 +64,7 @@ def test_preserves_fa_lsn(self): existing = {"last_batch_lsn": 42, "count": 5, "created_at": "2024-01-01T00:00:00Z"} doc = _build_counter_doc( counter_id="thread:u:t", + tenant_id=TENANT, user_id="u", thread_id="t", new_count=6, @@ -62,6 +91,7 @@ def test_preserves_fa_last_batch_old_count(self): } doc = _build_counter_doc( counter_id="thread:u:t", + tenant_id=TENANT, user_id="u", thread_id="t", new_count=20, @@ -80,6 +110,7 @@ def test_preserves_failure_breadcrumbs(self): } doc = _build_counter_doc( counter_id="thread:u:t", + tenant_id=TENANT, user_id="u", thread_id="t", new_count=2, @@ -97,7 +128,7 @@ def test_writes_failure_fields_via_patch_item(self): """ container = MagicMock() - stamp_failure_sync(container, "thread:u:t", "u", "t", "boom") + stamp_failure_sync(container, TENANT, "thread:u:t", "u", "boom") # No read+upsert race: patch_item is the only write. container.read_item.assert_not_called() @@ -106,7 +137,7 @@ def test_writes_failure_fields_via_patch_item(self): kwargs = container.patch_item.call_args.kwargs assert kwargs["item"] == "thread:u:t" - assert kwargs["partition_key"] == ["u", "t"] + assert kwargs["partition_key"] == [TENANT, "u"] ops = kwargs["patch_operations"] op_paths = {op["path"]: op for op in ops} assert op_paths["/last_failure_reason"]["value"] == "boom" @@ -117,13 +148,13 @@ def test_swallows_patch_errors(self): """Failure stamping is best-effort breadcrumbing - must never raise.""" container = MagicMock() container.patch_item.side_effect = RuntimeError("cosmos down") - stamp_failure_sync(container, "thread:u:t", "u", "t", "boom") + stamp_failure_sync(container, TENANT, "thread:u:t", "u", "boom") # Did not propagate - that's the contract. def test_truncates_long_reason(self): container = MagicMock() long_reason = "x" * 1000 - stamp_failure_sync(container, "thread:u:t", "u", "t", long_reason) + stamp_failure_sync(container, TENANT, "thread:u:t", "u", long_reason) kwargs = container.patch_item.call_args.kwargs ops = {op["path"]: op for op in kwargs["patch_operations"]} assert len(ops["/last_failure_reason"]["value"]) == 500 @@ -137,6 +168,7 @@ class TestBuildCounterDocOwnerStamping: def test_stamps_last_owner_when_provided(self): doc = _build_counter_doc( counter_id="thread:u:t", + tenant_id=TENANT, user_id="u", thread_id="t", new_count=1, @@ -150,6 +182,7 @@ def test_preserves_existing_owner_when_none_passed(self): existing = {"last_owner": "durable", "count": 1, "last_batch_lsn": 5} doc = _build_counter_doc( counter_id="thread:u:t", + tenant_id=TENANT, user_id="u", thread_id="t", new_count=2, @@ -163,6 +196,7 @@ def test_overwrites_existing_owner_when_explicit(self): existing = {"last_owner": "durable", "count": 1} doc = _build_counter_doc( counter_id="thread:u:t", + tenant_id=TENANT, user_id="u", thread_id="t", new_count=2, @@ -171,3 +205,119 @@ def test_overwrites_existing_owner_when_explicit(self): owner="inprocess", ) assert doc["last_owner"] == "inprocess" + + +class _OwnerPartitions: + """A counter container that keeps documents per ``[tenant_id, user_id]`` partition, as Cosmos does with that key. + + A document lands in the partition its own ``tenant_id`` and ``user_id`` name, and reads, patches and writes are + answered from the partition they ask for, so a counter written without its tenant cannot be read back. + """ + + def __init__(self) -> None: + self.docs: dict[tuple[tuple[Any, Any], str], dict[str, Any]] = {} + self.partitions_read: list[list[str]] = [] + self.partitions_patched: list[list[str]] = [] + self._etag = 0 + + def read_item(self, *, item, partition_key): + self.partitions_read.append(partition_key) + try: + return dict(self.docs[(tuple(partition_key), item)]) + except KeyError: + raise CosmosResourceNotFoundError(message="404") from None + + def create_item(self, *, body): + return self._write(body) + + def upsert_item(self, *, body, **_kwargs): + return self._write(body) + + def patch_item(self, *, item, partition_key, patch_operations): + self.partitions_patched.append(partition_key) + doc = self.docs[(tuple(partition_key), item)] + for op in patch_operations: + doc[op["path"].lstrip("/")] = op["value"] + return dict(doc) + + def _write(self, body): + self._etag += 1 + stored = {**body, "_etag": f"e{self._etag}"} + self.docs[((body.get("tenant_id"), body.get("user_id")), body["id"])] = stored + return dict(stored) + + +class _AsyncOwnerPartitions(_OwnerPartitions): + async def read_item(self, *, item, partition_key): + return super().read_item(item=item, partition_key=partition_key) + + async def create_item(self, *, body): + return super().create_item(body=body) + + async def upsert_item(self, *, body, **kwargs): + return super().upsert_item(body=body, **kwargs) + + async def patch_item(self, *, item, partition_key, patch_operations): + return super().patch_item(item=item, partition_key=partition_key, patch_operations=patch_operations) + + +class TestCountersLiveInTheOwnersPartition: + def test_a_counter_is_read_and_written_in_the_tenant_and_user_partition(self): + container = _OwnerPartitions() + + first = increment_counter_sync(container, TENANT, thread_counter_id("u1", "t1"), "u1", "t1", 2) + second = increment_counter_sync(container, TENANT, thread_counter_id("u1", "t1"), "u1", "t1", 1) + + assert (first, second) == ((0, 2), (2, 3)) + assert container.partitions_read == [[TENANT, "u1"], [TENANT, "u1"]] + [stored] = container.docs.values() + assert (stored["id"], stored["tenant_id"], stored["user_id"], stored["thread_id"], stored["count"]) == ( + "thread:u1:t1", + TENANT, + "u1", + "t1", + 3, + ) + + def test_the_thread_counters_and_the_user_counter_of_one_owner_share_the_partition(self): + container = _OwnerPartitions() + + increment_counter_sync(container, TENANT, thread_counter_id("u1", "t1"), "u1", "t1", 1) + increment_counter_sync(container, TENANT, thread_counter_id("u1", "t2"), "u1", "t2", 1) + increment_counter_sync(container, TENANT, user_counter_id("u1"), "u1", USER_COUNTER_THREAD_ID, 2) + + assert {partition for partition, _ in container.docs} == {(TENANT, "u1")} + assert {item for _, item in container.docs} == {"thread:u1:t1", "thread:u1:t2", "user:u1"} + assert container.docs[((TENANT, "u1"), "user:u1")]["thread_id"] == "__counters__" + + def test_the_same_owner_in_another_tenant_counts_on_its_own(self): + container = _OwnerPartitions() + + increment_counter_sync(container, TENANT, thread_counter_id("u1", "t1"), "u1", "t1", 5) + other = increment_counter_sync(container, "globex", thread_counter_id("u1", "t1"), "u1", "t1", 1) + + assert other == (0, 1) + assert {partition for partition, _ in container.docs} == {(TENANT, "u1"), ("globex", "u1")} + + def test_a_failure_is_stamped_in_the_tenant_and_user_partition(self): + container = _OwnerPartitions() + increment_counter_sync(container, TENANT, thread_counter_id("u1", "t1"), "u1", "t1", 1) + + stamp_failure_sync(container, TENANT, thread_counter_id("u1", "t1"), "u1", "boom") + + assert container.partitions_patched == [[TENANT, "u1"]] + assert container.docs[((TENANT, "u1"), "thread:u1:t1")]["last_failure_reason"] == "boom" + + async def test_async_counters_live_in_the_tenant_and_user_partition(self): + container = _AsyncOwnerPartitions() + + first = await increment_counter_async(container, TENANT, thread_counter_id("u1", "t1"), "u1", "t1", 2) + second = await increment_counter_async(container, TENANT, thread_counter_id("u1", "t1"), "u1", "t1", 1) + other = await increment_counter_async(container, "globex", thread_counter_id("u1", "t1"), "u1", "t1", 1) + await stamp_failure_async(container, TENANT, thread_counter_id("u1", "t1"), "u1", "boom") + + assert (first, second, other) == ((0, 2), (2, 3), (0, 1)) + assert container.partitions_read == [[TENANT, "u1"], [TENANT, "u1"], ["globex", "u1"]] + assert container.partitions_patched == [[TENANT, "u1"]] + stored = container.docs[((TENANT, "u1"), "thread:u1:t1")] + assert (stored["tenant_id"], stored["user_id"], stored["thread_id"], stored["count"]) == (TENANT, "u1", "t1", 3) diff --git a/tests/unit/test_dependency_failure_logs.py b/tests/unit/test_dependency_failure_logs.py index a21383a..702254a 100644 --- a/tests/unit/test_dependency_failure_logs.py +++ b/tests/unit/test_dependency_failure_logs.py @@ -36,6 +36,8 @@ from tests.unit.test_log_redaction import MEMORY, MODEL, QUERY, _expect, _failure from tests.unit.test_process_now import _connected, _patch_get_thread +TENANT = "acme" + @pytest.fixture def logs(caplog: pytest.LogCaptureFixture) -> pytest.LogCaptureFixture: @@ -151,7 +153,7 @@ def test_store_failures_log_the_failure_not_the_memory(logs) -> None: store.add(user_id="u1", role="user", content=MEMORY, memory_type="fact", thread_id="t1") store.push([_local_fact()]) - old = {"id": "fact_1", "type": "fact", "content": MEMORY} + old = {"id": "fact_1", "type": "fact", "content": MEMORY, "user_id": "u1"} assert MemoryStore(containers=_containers(failing)).mark_superseded(old, "fact_2", reason="dup") is False _expect(logs, *_STORE_DIAGNOSTICS) @@ -167,7 +169,7 @@ async def test_async_store_failures_log_the_failure_not_the_memory(logs) -> None await store.add(user_id="u1", role="user", content=MEMORY, memory_type="fact", thread_id="t1") await store.push([_local_fact()]) - old = {"id": "fact_1", "type": "fact", "content": MEMORY} + old = {"id": "fact_1", "type": "fact", "content": MEMORY, "user_id": "u1"} superseding = AsyncMemoryStore(containers=_containers(failing, asynchronous=True)) assert await superseding.mark_superseded(old, "fact_2", reason="dup") is False _expect(logs, *_STORE_DIAGNOSTICS) @@ -231,7 +233,7 @@ async def test_async_search_fallbacks_log_the_failure_not_the_query(logs) -> Non def test_counter_and_client_failures_log_the_failure_not_the_text(logs) -> None: container = MagicMock() container.patch_item.side_effect = _failure(MEMORY, 503) - _counters.stamp_failure_sync(container, "thread:u1:t1", "u1", "t1", "process_extract_memories: failed") + _counters.stamp_failure_sync(container, TENANT, "thread:u1:t1", "u1", "process_extract_memories: failed") client = CosmosMemoryClient(use_default_credential=False) client._cosmos_client = MagicMock() @@ -256,7 +258,7 @@ def test_counter_and_client_failures_log_the_failure_not_the_text(logs) -> None: async def test_async_counter_and_client_failures_log_the_failure_not_the_text(logs) -> None: container = MagicMock() container.patch_item = AsyncMock(side_effect=_failure(MEMORY, 503)) - await _counters.stamp_failure_async(container, "thread:u1:t1", "u1", "t1", "process_extract_memories: failed") + await _counters.stamp_failure_async(container, TENANT, "thread:u1:t1", "u1", "process_extract_memories: failed") client = AsyncCosmosMemoryClient(use_default_credential=False) client._cosmos_client = MagicMock() @@ -322,11 +324,11 @@ def test_in_process_trigger_failures_log_the_failure_not_the_text(logs) -> None: counters = _FakeCounterContainer() sync_trigger._fire_thread_steps( - processor, counters, "thread:u1:t1", "u1", "t1", fire_extract=True, fire_summary=True, **_STEPS + processor, counters, TENANT, "thread:u1:t1", "u1", "t1", fire_extract=True, fire_summary=True, **_STEPS ) - sync_trigger._trigger_user_steps(processor, counters, {"u1": 4}, n_user=1) - sync_trigger._trigger_thread_steps(processor, _FailingCounters(), {("u1", "t1"): 1}, **_THREAD_ARGUMENTS) - sync_trigger._trigger_user_steps(processor, _FailingCounters(), {"u1": 4}, n_user=1) + sync_trigger._trigger_user_steps(processor, counters, TENANT, {"u1": 4}, n_user=1) + sync_trigger._trigger_thread_steps(processor, _FailingCounters(), TENANT, {("u1", "t1"): 1}, **_THREAD_ARGUMENTS) + sync_trigger._trigger_user_steps(processor, _FailingCounters(), TENANT, {"u1": 4}, n_user=1) _expect(logs, *_trigger_diagnostics("Auto-trigger", "Counter", "User counter")) @@ -336,13 +338,13 @@ async def test_async_in_process_trigger_failures_log_the_failure_not_the_text(lo counters = _AsyncFakeCounterContainer() await async_trigger._fire_thread_steps( - processor, counters, "thread:u1:t1", "u1", "t1", fire_extract=True, fire_summary=True, **_STEPS + processor, counters, TENANT, "thread:u1:t1", "u1", "t1", fire_extract=True, fire_summary=True, **_STEPS ) - await async_trigger._trigger_user_steps(processor, counters, {"u1": 4}, n_user=1) + await async_trigger._trigger_user_steps(processor, counters, TENANT, {"u1": 4}, n_user=1) await async_trigger._trigger_thread_steps( - processor, _AsyncFailingCounters(), {("u1", "t1"): 1}, **_THREAD_ARGUMENTS + processor, _AsyncFailingCounters(), TENANT, {("u1", "t1"): 1}, **_THREAD_ARGUMENTS ) - await async_trigger._trigger_user_steps(processor, _AsyncFailingCounters(), {"u1": 4}, n_user=1) + await async_trigger._trigger_user_steps(processor, _AsyncFailingCounters(), TENANT, {"u1": 4}, n_user=1) _expect(logs, *_trigger_diagnostics("Async auto-trigger", "Async counter", "Async user counter")) @@ -365,14 +367,14 @@ def test_a_failed_step_stamps_a_description_of_the_error_on_its_counter() -> Non counters = _FakeCounterContainer() sync_trigger._fire_thread_steps( - processor, counters, "thread:u1:t1", "u1", "t1", fire_extract=True, fire_summary=False, **_STEPS + processor, counters, TENANT, "thread:u1:t1", "u1", "t1", fire_extract=True, fire_summary=False, **_STEPS ) extract = _reason(counters, "thread:u1:t1") sync_trigger._fire_thread_steps( - processor, counters, "thread:u1:t1", "u1", "t1", fire_extract=False, fire_summary=True, **_STEPS + processor, counters, TENANT, "thread:u1:t1", "u1", "t1", fire_extract=False, fire_summary=True, **_STEPS ) summary = _reason(counters, "thread:u1:t1") - sync_trigger._trigger_user_steps(processor, counters, {"u1": 4}, n_user=1) + sync_trigger._trigger_user_steps(processor, counters, TENANT, {"u1": 4}, n_user=1) _assert_reasons_describe_the_errors([extract, summary, _reason(counters, "user:u1")]) @@ -382,14 +384,14 @@ async def test_async_failed_step_stamps_a_description_of_the_error_on_its_counte counters = _AsyncFakeCounterContainer() await async_trigger._fire_thread_steps( - processor, counters, "thread:u1:t1", "u1", "t1", fire_extract=True, fire_summary=False, **_STEPS + processor, counters, TENANT, "thread:u1:t1", "u1", "t1", fire_extract=True, fire_summary=False, **_STEPS ) extract = _reason(counters, "thread:u1:t1") await async_trigger._fire_thread_steps( - processor, counters, "thread:u1:t1", "u1", "t1", fire_extract=False, fire_summary=True, **_STEPS + processor, counters, TENANT, "thread:u1:t1", "u1", "t1", fire_extract=False, fire_summary=True, **_STEPS ) summary = _reason(counters, "thread:u1:t1") - await async_trigger._trigger_user_steps(processor, counters, {"u1": 4}, n_user=1) + await async_trigger._trigger_user_steps(processor, counters, TENANT, {"u1": 4}, n_user=1) _assert_reasons_describe_the_errors([extract, summary, _reason(counters, "user:u1")]) diff --git a/tests/unit/test_exceptions.py b/tests/unit/test_exceptions.py index 7b36baf..8a7a0f5 100644 --- a/tests/unit/test_exceptions.py +++ b/tests/unit/test_exceptions.py @@ -47,26 +47,28 @@ def test_configuration_error_custom_message(): def test_memory_not_found_full_context(): - err = MemoryNotFoundError(memory_id="m1", user_id="u1", thread_id="t1") + err = MemoryNotFoundError(memory_id="m1", user_id="u1") assert err.memory_id == "m1" assert err.user_id == "u1" - assert err.thread_id == "t1" - msg = str(err) - assert "m1" in msg - assert "u1" in msg - assert "t1" in msg + assert str(err) == "Memory not found (memory_id='m1', user_id='u1')" def test_memory_not_found_partial_context(): err = MemoryNotFoundError(memory_id="m2") assert err.memory_id == "m2" assert err.user_id is None - assert err.thread_id is None msg = str(err) assert "m2" in msg assert "user_id" not in msg +def test_memory_not_found_does_not_carry_a_thread(): + # A record is found by its owner and id; the thread is a plain field of the record. + with pytest.raises(TypeError): + MemoryNotFoundError(memory_id="m1", user_id="u1", thread_id="t1") + assert not hasattr(MemoryNotFoundError(memory_id="m1"), "thread_id") + + def test_cosmos_not_connected_default_message(): err = CosmosNotConnectedError() assert "connect_cosmos()" in str(err) diff --git a/tests/unit/test_log_redaction.py b/tests/unit/test_log_redaction.py index 86c38ee..035919a 100644 --- a/tests/unit/test_log_redaction.py +++ b/tests/unit/test_log_redaction.py @@ -285,6 +285,7 @@ def test_a_conflict_link_that_cannot_be_written_is_logged_by_error_type_not_its_ logs: pytest.LogCaptureFixture, ) -> None: service = PipelineService.__new__(PipelineService) + service._tenant_id = "acme" service._memories_container = MagicMock() service._memories_container.upsert_item.side_effect = _failure(QUERY, 503) @@ -296,6 +297,7 @@ async def test_async_conflict_link_that_cannot_be_written_is_logged_by_error_typ logs: pytest.LogCaptureFixture, ) -> None: service = AsyncPipelineService.__new__(AsyncPipelineService) + service._tenant_id = "acme" service._memories_container = MagicMock() service._memories_container.upsert_item = AsyncMock(side_effect=_failure(QUERY, 503)) diff --git a/tests/unit/test_memory_type_multi.py b/tests/unit/test_memory_type_multi.py index df4528f..1f8fb08 100644 --- a/tests/unit/test_memory_type_multi.py +++ b/tests/unit/test_memory_type_multi.py @@ -18,13 +18,15 @@ from azure.cosmos.agent_memory._utils import _build_memory_query_builder from azure.cosmos.agent_memory.cosmos_memory_client import CosmosMemoryClient +TENANT = "acme" + # --------------------------------------------------------------------------- # Helpers - a small replica of the patterns used in test_cosmos_memory_client. # --------------------------------------------------------------------------- def _connected_client() -> tuple[CosmosMemoryClient, MagicMock]: - client = CosmosMemoryClient(use_default_credential=False) + client = CosmosMemoryClient(use_default_credential=False, tenant_id=TENANT) container = MagicMock() container.query_items.return_value = [] client._memories_container_client = container @@ -47,6 +49,7 @@ def _captured_params(container: MagicMock) -> list[dict]: def test_memory_types_list_emits_in_clause(): qb = _build_memory_query_builder( + tenant_id=TENANT, user_id="u1", memory_types=["fact", "procedural", "episodic"], ) @@ -58,32 +61,33 @@ def test_memory_types_list_emits_in_clause(): def test_memory_types_single_element_list_still_uses_in_clause(): - qb = _build_memory_query_builder(user_id="u1", memory_types=["fact"]) + qb = _build_memory_query_builder(tenant_id=TENANT, user_id="u1", memory_types=["fact"]) where = qb.build_where() assert "c.type IN (@memory_type_0)" in where def test_memory_types_empty_list_skipped(): - qb = _build_memory_query_builder(user_id="u1", memory_types=[]) + qb = _build_memory_query_builder(tenant_id=TENANT, user_id="u1", memory_types=[]) where = qb.build_where() assert "c.type" not in where def test_memory_types_none_skipped(): - qb = _build_memory_query_builder(user_id="u1", memory_types=None) + qb = _build_memory_query_builder(tenant_id=TENANT, user_id="u1", memory_types=None) where = qb.build_where() assert "c.type" not in where def test_memory_types_list_combines_with_other_filters(): qb = _build_memory_query_builder( + tenant_id=TENANT, user_id="u1", thread_id="t1", memory_types=["fact", "episodic"], min_confidence=0.5, ) where = qb.build_where() - assert "c.user_id = @user_id" in where + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in where # Episodic is user-scoped, so the thread_id filter becomes an OR clause # instead of the plain equality form. assert "(c.thread_id = @thread_id OR c.type IN (@user_scoped_type_0))" in where @@ -97,21 +101,21 @@ def test_memory_types_list_combines_with_other_filters(): def test_thread_id_unchanged_when_only_non_user_scoped_types_requested(): - qb = _build_memory_query_builder(user_id="u1", thread_id="t1", memory_types=["fact"]) + qb = _build_memory_query_builder(tenant_id=TENANT, user_id="u1", thread_id="t1", memory_types=["fact"]) where = qb.build_where() assert "c.thread_id = @thread_id" in where assert "@user_scoped_type_" not in where def test_thread_id_unchanged_when_only_turn_requested(): - qb = _build_memory_query_builder(user_id="u1", thread_id="t1", memory_types=["turn"]) + qb = _build_memory_query_builder(tenant_id=TENANT, user_id="u1", thread_id="t1", memory_types=["turn"]) where = qb.build_where() assert "c.thread_id = @thread_id" in where assert "@user_scoped_type_" not in where def test_thread_id_or_clause_when_episodic_requested(): - qb = _build_memory_query_builder(user_id="u1", thread_id="t1", memory_types=["episodic"]) + qb = _build_memory_query_builder(tenant_id=TENANT, user_id="u1", thread_id="t1", memory_types=["episodic"]) where = qb.build_where() params = qb.get_parameters() assert "(c.thread_id = @thread_id OR c.type IN (@user_scoped_type_0))" in where @@ -120,7 +124,7 @@ def test_thread_id_or_clause_when_episodic_requested(): def test_thread_id_or_clause_when_procedural_requested(): - qb = _build_memory_query_builder(user_id="u1", thread_id="t1", memory_types=["procedural"]) + qb = _build_memory_query_builder(tenant_id=TENANT, user_id="u1", thread_id="t1", memory_types=["procedural"]) where = qb.build_where() params = qb.get_parameters() assert "(c.thread_id = @thread_id OR c.type IN (@user_scoped_type_0))" in where @@ -130,6 +134,7 @@ def test_thread_id_or_clause_when_procedural_requested(): def test_thread_id_or_clause_includes_both_when_both_in_scope(): qb = _build_memory_query_builder( + tenant_id=TENANT, user_id="u1", thread_id="t1", memory_types=["episodic", "procedural"], @@ -143,7 +148,7 @@ def test_thread_id_or_clause_includes_both_when_both_in_scope(): def test_thread_id_or_clause_when_no_memory_types_filter(): # No memory_types means "all types", so user-scoped types are implicitly in scope. - qb = _build_memory_query_builder(user_id="u1", thread_id="t1") + qb = _build_memory_query_builder(tenant_id=TENANT, user_id="u1", thread_id="t1") where = qb.build_where() params = qb.get_parameters() assert "(c.thread_id = @thread_id OR c.type IN (@user_scoped_type_0, @user_scoped_type_1))" in where @@ -152,13 +157,13 @@ def test_thread_id_or_clause_when_no_memory_types_filter(): def test_thread_id_or_clause_when_empty_memory_types_filter(): - qb = _build_memory_query_builder(user_id="u1", thread_id="t1", memory_types=[]) + qb = _build_memory_query_builder(tenant_id=TENANT, user_id="u1", thread_id="t1", memory_types=[]) where = qb.build_where() assert "(c.thread_id = @thread_id OR c.type IN (@user_scoped_type_0, @user_scoped_type_1))" in where def test_no_thread_id_no_or_clause(): - qb = _build_memory_query_builder(user_id="u1", memory_types=["episodic"]) + qb = _build_memory_query_builder(tenant_id=TENANT, user_id="u1", memory_types=["episodic"]) where = qb.build_where() assert "c.thread_id" not in where assert "@user_scoped_type_" not in where diff --git a/tests/unit/test_min_confidence.py b/tests/unit/test_min_confidence.py index 487f30e..2bed237 100644 --- a/tests/unit/test_min_confidence.py +++ b/tests/unit/test_min_confidence.py @@ -6,7 +6,7 @@ def test_min_confidence_adds_predicate_when_set(): - qb = _build_memory_query_builder(user_id="u1", min_confidence=0.7) + qb = _build_memory_query_builder(tenant_id="acme", user_id="u1", min_confidence=0.7) where = qb.build_where() params = qb.get_parameters() assert "c.confidence >= @min_confidence" in where @@ -14,7 +14,7 @@ def test_min_confidence_adds_predicate_when_set(): def test_min_confidence_omitted_when_none(): - qb = _build_memory_query_builder(user_id="u1") + qb = _build_memory_query_builder(tenant_id="acme", user_id="u1") where = qb.build_where() assert "c.confidence" not in where assert all(p["name"] != "@min_confidence" for p in qb.get_parameters()) @@ -22,6 +22,6 @@ def test_min_confidence_omitted_when_none(): def test_min_confidence_zero_is_no_op(): """min_confidence=0 means 'no filter' (every memory >= 0 trivially).""" - qb = _build_memory_query_builder(user_id="u1", min_confidence=0.0) + qb = _build_memory_query_builder(tenant_id="acme", user_id="u1", min_confidence=0.0) where = qb.build_where() assert "c.confidence" not in where diff --git a/tests/unit/test_models.py b/tests/unit/test_models.py index 4e5e950..26da421 100644 --- a/tests/unit/test_models.py +++ b/tests/unit/test_models.py @@ -749,6 +749,38 @@ def test_supersedes_ids_and_source_ids(self): assert rec.source_memory_ids == ["src1"] +# --------------------------------------------------------------------------- +# Tenant +# --------------------------------------------------------------------------- + + +class TestTenant: + def test_a_record_belongs_to_the_default_tenant_unless_it_names_one(self): + record = TurnRecord(user_id="u1", role="user", content="hello") + + assert record.tenant_id == "default" + assert record.to_doc()["tenant_id"] == "default" + + @pytest.mark.parametrize( + ("memory_type", "kwargs"), + [ + ("turn", {"user_id": "u1", "role": "user", "content": "hello"}), + ("thread_summary", _thread_summary_kwargs()), + ("user_summary", _user_summary_kwargs()), + ("fact", _fact_kwargs()), + ("episodic", _episodic_kwargs()), + ("procedural", _procedural_kwargs()), + ], + ) + def test_every_record_type_writes_its_tenant_and_reads_it_back(self, memory_type, kwargs): + record = MemoryRecord(memory_type=memory_type, tenant_id="acme", **kwargs) + + doc = record.to_doc() + + assert doc["tenant_id"] == "acme" + assert MemoryRecord.from_doc(doc).tenant_id == "acme" + + # --------------------------------------------------------------------------- # to_doc / from_doc round-trip & system-field handling # --------------------------------------------------------------------------- diff --git a/tests/unit/test_no_exception_text_in_logs.py b/tests/unit/test_no_exception_text_in_logs.py index a0bb29d..6cc85a7 100644 --- a/tests/unit/test_no_exception_text_in_logs.py +++ b/tests/unit/test_no_exception_text_in_logs.py @@ -136,9 +136,9 @@ def test_the_scan_flags_an_exception_taken_from_a_task() -> None: @pytest.mark.parametrize( "statement", [ - '_counters.stamp_failure_sync(container, "id", "u1", "t1", f"step: {exc!r}")', - 'await _counters.stamp_failure_async(container, "id", "u1", "t1", f"step: {exc}")', - 'stamp_failure_sync(container, "id", "u1", "t1", str(exc))', + '_counters.stamp_failure_sync(container, "acme", "id", "u1", f"step: {exc!r}")', + 'await _counters.stamp_failure_async(container, "acme", "id", "u1", f"step: {exc}")', + 'stamp_failure_sync(container, "acme", "id", "u1", str(exc))', ], ) def test_the_scan_flags_a_stored_failure_reason_that_holds_exception_text(statement: str) -> None: @@ -146,7 +146,9 @@ def test_the_scan_flags_a_stored_failure_reason_that_holds_exception_text(statem def test_the_scan_allows_a_stored_failure_reason_that_describes_the_error() -> None: - statement = 'error = describe_exception(exc)\n stamp_failure_sync(container, "id", "u1", "t1", f"step: {error}")' + statement = ( + 'error = describe_exception(exc)\n stamp_failure_sync(container, "acme", "id", "u1", f"step: {error}")' + ) assert _exception_text_in_logs(_in_handler(statement), "sample.py") == [] diff --git a/tests/unit/test_partitioning.py b/tests/unit/test_partitioning.py new file mode 100644 index 0000000..3992f70 --- /dev/null +++ b/tests/unit/test_partitioning.py @@ -0,0 +1,175 @@ +"""The record key: ``[tenant_id, user_id]``, the tenant a client is bound to, and the filters that confine a query.""" + +from __future__ import annotations + +import pytest + +from azure.cosmos.agent_memory._partitioning import ( + DEFAULT_TENANT_ID, + MAX_OWNER_ID_BYTES, + MAX_TENANT_ID_BYTES, + OWNER_FILTER, + PARTITION_KEY_PATHS, + TENANT_FILTER, + owner_parameters, + partition_key_for, + partition_key_problem, + resolve_tenant_id, + stamp_scope, + tenant_parameters, + validate_owner_id, +) +from azure.cosmos.agent_memory.exceptions import ValidationError + +INVALID_IDS = [ + "", + " ", + "a/b", + "a\\b", + "what?", + "tag#1", + "line\nbreak", + "tab\there", + 7, + b"x", +] + + +class TestResolveTenantId: + def test_no_tenant_is_the_default_tenant(self) -> None: + assert resolve_tenant_id() == DEFAULT_TENANT_ID == "default" + assert resolve_tenant_id(None) == "default" + + @pytest.mark.parametrize("tenant", ["acme", "Acme-Corp_2", "tenant:prod", "t" * MAX_TENANT_ID_BYTES, "société"]) + def test_a_valid_tenant_is_returned_as_given(self, tenant: str) -> None: + assert resolve_tenant_id(tenant) == tenant + + @pytest.mark.parametrize("tenant", [*INVALID_IDS, "t" * (MAX_TENANT_ID_BYTES + 1)]) + def test_an_invalid_tenant_is_refused(self, tenant: object) -> None: + with pytest.raises(ValidationError): + resolve_tenant_id(tenant) # type: ignore[arg-type] + + def test_the_byte_limit_counts_utf8_bytes_not_characters(self) -> None: + assert resolve_tenant_id("é" * (MAX_TENANT_ID_BYTES // 2)) == "é" * (MAX_TENANT_ID_BYTES // 2) + with pytest.raises(ValidationError): + resolve_tenant_id("é" * (MAX_TENANT_ID_BYTES // 2 + 1)) + + +class TestValidateOwnerId: + @pytest.mark.parametrize( + "owner", ["alice", "agent:support-bot", "a@b.com", "user.name_1", "o" * MAX_OWNER_ID_BYTES, "société", "用户"] + ) + def test_a_valid_owner_is_returned_as_given(self, owner: str) -> None: + assert validate_owner_id(owner) == owner + + @pytest.mark.parametrize("owner", [*INVALID_IDS, None, "o" * (MAX_OWNER_ID_BYTES + 1)]) + def test_an_invalid_owner_is_refused(self, owner: object) -> None: + with pytest.raises(ValidationError, match="user_id"): + validate_owner_id(owner) + + def test_the_byte_limit_counts_utf8_bytes_not_characters(self) -> None: + assert validate_owner_id("é" * (MAX_OWNER_ID_BYTES // 2)) + with pytest.raises(ValidationError): + validate_owner_id("é" * (MAX_OWNER_ID_BYTES // 2 + 1)) + + +class TestTheKey: + def test_the_partition_key_is_the_tenant_then_the_owner(self) -> None: + assert partition_key_for("acme", "alice") == ["acme", "alice"] + + def test_an_agent_is_an_owner_like_a_user(self) -> None: + assert partition_key_for("acme", "agent:support-bot") == ["acme", "agent:support-bot"] + + def test_the_same_owner_in_two_tenants_is_two_partitions(self) -> None: + assert partition_key_for("acme", "alice") != partition_key_for("globex", "alice") + + def test_the_key_paths_are_the_tenant_then_the_owner(self) -> None: + assert PARTITION_KEY_PATHS == ["/tenant_id", "/user_id"] + + @pytest.mark.parametrize("owner", ["", "a/b", None]) + def test_an_invalid_owner_has_no_key(self, owner: object) -> None: + with pytest.raises(ValidationError): + partition_key_for("acme", owner) # type: ignore[arg-type] + + +class TestTheFilters: + def test_the_owner_filter_names_the_tenant_and_the_owner(self) -> None: + assert TENANT_FILTER == "c.tenant_id = @tenant_id" + assert OWNER_FILTER == f"{TENANT_FILTER} AND c.user_id = @user_id" + + def test_the_parameters_match_the_filters(self) -> None: + assert tenant_parameters("acme") == [{"name": "@tenant_id", "value": "acme"}] + assert owner_parameters("acme", "alice") == [ + {"name": "@tenant_id", "value": "acme"}, + {"name": "@user_id", "value": "alice"}, + ] + + @pytest.mark.parametrize("owner", ["", "a#b", None]) + def test_an_invalid_owner_has_no_parameters(self, owner: object) -> None: + with pytest.raises(ValidationError): + owner_parameters("acme", owner) # type: ignore[arg-type] + + +class TestStampScope: + def test_a_record_without_a_tenant_is_given_one(self) -> None: + assert stamp_scope({"id": "f1", "user_id": "alice"}, "acme") == { + "id": "f1", + "user_id": "alice", + "tenant_id": "acme", + } + + def test_a_record_of_the_same_tenant_is_kept(self) -> None: + assert stamp_scope({"id": "f1", "user_id": "alice", "tenant_id": "acme"}, "acme")["tenant_id"] == "acme" + + def test_a_record_of_another_tenant_is_refused(self) -> None: + with pytest.raises(ValidationError, match="different tenant"): + stamp_scope({"id": "f1", "user_id": "alice", "tenant_id": "globex"}, "acme") + + def test_the_record_passed_in_is_not_changed(self) -> None: + record = {"id": "f1", "user_id": "alice"} + + stamp_scope(record, "acme") + + assert record == {"id": "f1", "user_id": "alice"} + + @pytest.mark.parametrize("record", [{"id": "f1"}, {"id": "f1", "user_id": None}, {"id": "f1", "user_id": ""}]) + def test_a_record_without_an_owner_is_refused(self, record: dict) -> None: + with pytest.raises(ValidationError, match="user_id"): + stamp_scope(record, "acme") + + def test_a_record_with_an_unsupported_owner_is_refused(self) -> None: + with pytest.raises(ValidationError, match="user_id"): + stamp_scope({"id": "f1", "user_id": "a/b"}, "acme") + + +class TestPartitionKeyProblem: + @staticmethod + def properties(*paths: str) -> dict: + return {"id": "memories", "partitionKey": {"paths": list(paths), "kind": "MultiHash", "version": 2}} + + def test_the_expected_key_is_not_a_problem(self) -> None: + assert partition_key_problem("memories", self.properties("/tenant_id", "/user_id")) is None + + def test_the_earlier_key_is_named_with_what_to_do(self) -> None: + problem = partition_key_problem("memories", self.properties("/user_id", "/thread_id")) + + assert problem is not None + assert "'memories'" in problem + assert "['/user_id', '/thread_id']" in problem + assert "['/tenant_id', '/user_id']" in problem + assert "recreate" in problem and "leases" in problem + + @pytest.mark.parametrize( + "paths", [("/tenant_id",), ("/user_id", "/tenant_id"), ("/tenant_id", "/user_id", "/thread_id"), ()] + ) + def test_any_other_key_is_a_problem(self, paths: tuple[str, ...]) -> None: + assert partition_key_problem("memories", self.properties(*paths)) is not None + + def test_a_container_without_a_partition_key_says_none(self) -> None: + problem = partition_key_problem("memories", {"id": "memories"}) + + assert problem is not None and "partition key none" in problem + + def test_what_is_not_container_metadata_is_not_checked(self) -> None: + assert partition_key_problem("memories", object()) is None + assert partition_key_problem("memories", None) is None diff --git a/tests/unit/test_pipeline_confidence.py b/tests/unit/test_pipeline_confidence.py index 2585b36..dc75684 100644 --- a/tests/unit/test_pipeline_confidence.py +++ b/tests/unit/test_pipeline_confidence.py @@ -12,6 +12,8 @@ from azure.cosmos.agent_memory.services.pipeline import PipelineService from azure.cosmos.agent_memory.store import MemoryStore +TENANT = "acme" + def _make_pipeline(llm_response: dict): turns_container = MagicMock() @@ -44,8 +46,8 @@ def _make_pipeline(llm_response: dict): ContainerKey.MEMORIES: memories_container, ContainerKey.SUMMARIES: summaries_container, } - store = MemoryStore(containers=containers, embeddings_client=embeddings) - pipeline = PipelineService(store, chat, embeddings, containers=containers) + store = MemoryStore(containers=containers, embeddings_client=embeddings, tenant_id=TENANT) + pipeline = PipelineService(store, chat, embeddings, containers=containers, tenant_id=TENANT) # Avoid real LLM/prompty calls. pipeline._run_prompty = MagicMock(return_value=json.dumps(llm_response)) @@ -94,6 +96,24 @@ def test_extract_defaults_confidence_to_half_when_missing(): assert doc["confidence"] == 0.5, f"missing default for {doc['type']} {doc['id']}" +def test_extract_reads_and_writes_inside_the_pipelines_tenant(): + pipeline, upserted = _make_pipeline({"facts": [{"text": "User likes coffee", "action": "ADD"}], "episodic": []}) + + pipeline.extract_memories("u1", "t1") + + assert [d["type"] for d in upserted] == ["fact"] + assert (upserted[0]["tenant_id"], upserted[0]["user_id"], upserted[0]["thread_id"]) == (TENANT, "u1", "t1") + turns_queries = pipeline._turns_container.query_items.call_args_list + assert len(turns_queries) == 2, "the turns to extract, and the turns before them as context" + for call in turns_queries: + params = {p["name"]: p["value"] for p in call.kwargs["parameters"]} + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id AND c.thread_id = @thread_id" in call.kwargs["query"] + assert (params["@tenant_id"], params["@user_id"], params["@thread_id"]) == (TENANT, "u1", "t1") + assert call.kwargs["partition_key"] == [TENANT, "u1"] + stamped = pipeline._turns_container.patch_item.call_args + assert stamped.kwargs["partition_key"] == [TENANT, "u1"] + + class TestMarkSupersededDoesNotMutate: """``_mark_superseded`` must not mutate its input dict before the write. @@ -165,6 +185,7 @@ def _build_pipeline(self): from azure.cosmos.agent_memory.services.pipeline import PipelineService pipeline = PipelineService.__new__(PipelineService) + pipeline._tenant_id = TENANT pipeline._embeddings = MagicMock() pipeline._embeddings.generate.return_value = [0.1] * 8 pipeline._upsert_summary = MagicMock(side_effect=lambda doc: doc) @@ -173,6 +194,30 @@ def _build_pipeline(self): pipeline._chat = MagicMock() return pipeline + def test_the_user_summary_reads_the_owners_partition_of_its_tenant(self): + pipeline = self._build_pipeline() + pipeline._summaries_container.read_item.side_effect = CosmosResourceNotFoundError(message="not found") + pipeline._memories_container.query_items.return_value = iter([]) + pipeline._summaries_container.query_items.return_value = iter( + [{"id": "summary_u1_t1", "type": "thread_summary", "thread_id": "t1", "content": "User likes coffee."}] + ) + + with patch.object(pipeline, "_run_prompty", return_value='{"key_facts":["likes coffee"]}'): + pipeline.generate_user_summary(user_id="u1") + + pipeline._summaries_container.read_item.assert_called_once_with( + item="user_summary_u1", partition_key=[TENANT, "u1"] + ) + for container_mock in (pipeline._memories_container, pipeline._summaries_container): + call = container_mock.query_items.call_args + params = {p["name"]: p["value"] for p in call.kwargs["parameters"]} + assert "c.tenant_id = @tenant_id AND c.user_id = @user_id" in call.kwargs["query"] + assert (params["@tenant_id"], params["@user_id"]) == (TENANT, "u1") + assert call.kwargs["partition_key"] == [TENANT, "u1"] + assert "enable_cross_partition_query" not in call.kwargs + stored = pipeline._upsert_summary.call_args.args[0] + assert (stored["tenant_id"], stored["user_id"], stored["thread_id"]) == (TENANT, "u1", "__user_summary__") + def test_thread_ids_does_not_appear_in_query_or_parameters(self): pipeline = self._build_pipeline() # No prior user-summary; first-pass full generation. diff --git a/tests/unit/test_query_builder.py b/tests/unit/test_query_builder.py index 5a3440b..d0e93f5 100644 --- a/tests/unit/test_query_builder.py +++ b/tests/unit/test_query_builder.py @@ -253,6 +253,29 @@ def test_add_condition_without_parameters_or_text(): assert qb.get_parameters() == [] +# --------------------------------------------------------------------------- +# for_tenant +# --------------------------------------------------------------------------- + + +def test_for_tenant_starts_with_the_tenant_filter(): + qb = _QueryBuilder.for_tenant("acme") + qb.add_filter("c.thread_id", "@thread_id", "t1") + assert qb.build_where() == " WHERE c.tenant_id = @tenant_id AND c.thread_id = @thread_id" + assert qb.get_parameters() == [{"name": "@tenant_id", "value": "acme"}, {"name": "@thread_id", "value": "t1"}] + + +def test_for_tenant_with_an_owner_filters_on_both_halves_of_the_key(): + qb = _QueryBuilder.for_tenant("acme", "u1") + qb.add_filter("c.type", "@type", "fact") + assert qb.build_where() == " WHERE c.tenant_id = @tenant_id AND c.user_id = @user_id AND c.type = @type" + assert qb.get_parameters() == [ + {"name": "@tenant_id", "value": "acme"}, + {"name": "@user_id", "value": "u1"}, + {"name": "@type", "value": "fact"}, + ] + + # --------------------------------------------------------------------------- # add_time_range # --------------------------------------------------------------------------- diff --git a/tests/unit/test_reconcile.py b/tests/unit/test_reconcile.py index 68b52aa..4d8842c 100644 --- a/tests/unit/test_reconcile.py +++ b/tests/unit/test_reconcile.py @@ -28,6 +28,7 @@ from azure.cosmos.agent_memory.services.pipeline import PipelineService NO_DEDUP = dedup_result(checked=0, retired_seeds=0, merged=0, compared=0, vetoed=0) +TENANT = "acme" def _make_pipeline() -> PipelineService: @@ -142,6 +143,7 @@ def test_it_is_one_pass_and_returns_that_passs_counts_unchanged(self): class TestExactDedupShortCircuit: def _build(self) -> PipelineService: p = PipelineService.__new__(PipelineService) + p._tenant_id = TENANT p._embeddings = MagicMock() p._embeddings.generate.return_value = [0.1] * 8 p._container = MagicMock() @@ -247,6 +249,7 @@ class TestExactDedupCrossTypeIsolation: def _build(self) -> PipelineService: p = PipelineService.__new__(PipelineService) + p._tenant_id = TENANT p._embeddings = MagicMock() p._embeddings.generate.return_value = [0.1] * 8 p._embeddings.generate_batch.return_value = [[0.1] * 8] @@ -308,6 +311,7 @@ class TestExtractEarlyReturnShape: def test_empty_thread_returns_full_dict_shape(self): p = PipelineService.__new__(PipelineService) + p._tenant_id = TENANT p._container = MagicMock() p._memories_container = p._container p._turns_container = p._container @@ -357,6 +361,7 @@ class TestExtractUpdateSelfCollapseGuard: def _build(self) -> PipelineService: p = PipelineService.__new__(PipelineService) + p._tenant_id = TENANT p._embeddings = MagicMock() p._embeddings.generate.return_value = [[0.1] * 8] p._upsert_memory = MagicMock(side_effect=lambda doc: doc) diff --git a/tests/unit/test_search_conflicts.py b/tests/unit/test_search_conflicts.py index 42240e2..e7aa264 100644 --- a/tests/unit/test_search_conflicts.py +++ b/tests/unit/test_search_conflicts.py @@ -11,16 +11,17 @@ import pytest -from azure.cosmos.agent_memory.services._conflicts import CONFLICT_LINK_THREAD_ID from tests.unit.aio import test_cosmos_memory_client as async_client_tests from tests.unit.test_cosmos_memory_client import _connected_client USER = "u1" +TENANT = "acme" def fact(fact_id: str, content: str, created_at: str) -> dict[str, Any]: return { "id": fact_id, + "tenant_id": TENANT, "user_id": USER, "thread_id": "t1", "type": "fact", @@ -75,7 +76,7 @@ async def rows_iter() -> Any: def _sync_client(container: FakeMemories) -> Any: - mem, _ = _connected_client() + mem, _ = _connected_client(tenant_id=TENANT) mem._memories_container_client = container mem._embeddings_client = MagicMock() mem._embeddings_client.generate.return_value = [0.1, 0.2, 0.3] @@ -83,7 +84,7 @@ def _sync_client(container: FakeMemories) -> Any: def _async_client(container: AsyncFakeMemories) -> Any: - mem, _ = async_client_tests._connected_client() + mem, _ = async_client_tests._connected_client(tenant_id=TENANT) mem._memories_container_client = container mem._embeddings_client = AsyncMock() mem._embeddings_client.generate = AsyncMock(return_value=[0.1, 0.2, 0.3]) @@ -108,6 +109,20 @@ def _assert_shown_with_its_conflict(results: list[dict[str, Any]]) -> None: ] +def _assert_every_query_stays_in_the_tenant(container: FakeMemories) -> None: + """Every query names the tenant, and the link and fact lookups read the owner's ``[tenant, user]`` partition.""" + assert container.calls + for call in container.calls: + params = {p["name"]: p["value"] for p in call["parameters"]} + assert "c.tenant_id = @tenant_id" in call["query"] + assert params["@tenant_id"] == TENANT + lookups = [call for call in container.calls if "c.type = @type" in call["query"] or "@ids" in call["query"]] + assert lookups + for call in lookups: + assert call["partition_key"] == [TENANT, USER] + assert "enable_cross_partition_query" not in call + + def test_a_fact_is_returned_with_the_fact_it_conflicts_with() -> None: container = FakeMemories(ranked=[dict(RANKED)], links=LINKS, facts=_facts()) @@ -115,7 +130,15 @@ def test_a_fact_is_returned_with_the_fact_it_conflicts_with() -> None: _assert_shown_with_its_conflict(results) links_call = next(call for call in container.calls if "c.type = @type" in call["query"]) - assert links_call["partition_key"] == [USER, CONFLICT_LINK_THREAD_ID] + assert links_call["partition_key"] == [TENANT, USER] + + +def test_the_conflict_lookups_stay_inside_the_clients_tenant() -> None: + container = FakeMemories(ranked=[dict(RANKED)], links=LINKS, facts=_facts()) + + _sync_client(container).search_cosmos(search_terms="deadline", user_id=USER, top_k=3) + + _assert_every_query_stays_in_the_tenant(container) def test_a_fact_with_no_links_is_returned_as_it_is() -> None: @@ -205,7 +228,16 @@ async def test_async_a_fact_is_returned_with_the_fact_it_conflicts_with() -> Non _assert_shown_with_its_conflict(results) links_call = next(call for call in container.calls if "c.type = @type" in call["query"]) - assert links_call["partition_key"] == [USER, CONFLICT_LINK_THREAD_ID] + assert links_call["partition_key"] == [TENANT, USER] + + +@pytest.mark.asyncio +async def test_async_the_conflict_lookups_stay_inside_the_clients_tenant() -> None: + container = AsyncFakeMemories(ranked=[dict(RANKED)], links=LINKS, facts=_facts()) + + await _async_client(container).search_cosmos(search_terms="deadline", user_id=USER, top_k=3) + + _assert_every_query_stays_in_the_tenant(container) @pytest.mark.asyncio diff --git a/tests/unit/test_search_slots.py b/tests/unit/test_search_slots.py index bbfc429..44aa07f 100644 --- a/tests/unit/test_search_slots.py +++ b/tests/unit/test_search_slots.py @@ -19,6 +19,7 @@ PREFERENCE = {"id": "pref_a", "content": "The user prefers pnpm.", "metadata": {"category": "preference"}} PROCEDURE = {"id": "proc_a", "content": "Run targeted tests before reporting success.", "type": "procedural"} CLIENT_LOGGER = "azure.cosmos.agent_memory.cosmos_memory_client" +TENANT = "acme" # A procedure has no salience or confidence, its role is "system" and its tags are the pipeline's own, so # these filters could never match one. FACT_ONLY_FILTERS = { @@ -183,6 +184,7 @@ def _store() -> tuple[MemoryStore, MagicMock, MagicMock]: store = MemoryStore( containers={key: memories for key in (ContainerKey.TURNS, ContainerKey.MEMORIES, ContainerKey.SUMMARIES)}, embeddings_client=embeddings, + tenant_id=TENANT, ) return store, memories, embeddings @@ -246,8 +248,8 @@ def test_the_procedure_slot_search_is_a_vector_search_of_the_users_situational_p assert "ORDER BY VectorDistance" in call["query"] and "FullTextScore" not in call["query"] assert "c.applies = @applies" in call["query"] assert PROCEDURES_IN_FORCE in call["query"] - assert (params["@user_id"], params["@applies"]) == ("u1", "when") - assert "partition_key" not in call, "procedures live under a sentinel thread, so a thread cannot key the query" + assert (params["@tenant_id"], params["@user_id"], params["@applies"]) == (TENANT, "u1", "when") + assert call["partition_key"] == [TENANT, "u1"], "a thread does not key the query: the owner's partition does" def test_the_procedure_slot_query_asks_for_nothing_a_procedure_lacks(): diff --git a/tests/unit/test_tenant_scope_guard.py b/tests/unit/test_tenant_scope_guard.py new file mode 100644 index 0000000..da7c2a5 --- /dev/null +++ b/tests/unit/test_tenant_scope_guard.py @@ -0,0 +1,69 @@ +"""Tenant scope guard: no code path may filter on an owner without the tenant, or build a raw partition key. + +A query that names ``c.user_id`` alone reads the same id in every tenant, and a hand-built ``[user_id, ...]`` key +addresses the wrong partition. These checks read the source, so a new query written without the tenant fails here +before it can leak. +""" + +from __future__ import annotations + +import ast +import re +from pathlib import Path + +import pytest + +ROOT = Path(__file__).resolve().parents[2] +SOURCES = sorted( + path + for base in (ROOT / "azure" / "cosmos" / "agent_memory", ROOT / "function_app") + for path in base.rglob("*.py") + if "prompts" not in path.parts and path.name != "_partitioning.py" +) + +# A function that filters on the owner must be tenant-aware: it names the tenant, the shared filters, or the key helper. +TENANT_AWARE = re.compile(r"tenant|OWNER_FILTER|partition_key_for", re.IGNORECASE) +OWNER_FILTER_USE = re.compile(r"""c\.user_id|["']c\.user_id["']""") + + +def _functions(tree: ast.AST): + for node in ast.walk(tree): + if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)): + yield node + + +def _owner_filters_without_the_tenant() -> list[str]: + found: list[str] = [] + for path in SOURCES: + text = path.read_text() + tree = ast.parse(text) + for function in _functions(tree): + source = ast.get_source_segment(text, function) or "" + if OWNER_FILTER_USE.search(source) and not TENANT_AWARE.search(source): + found.append(f"{path.relative_to(ROOT)}:{function.lineno} {function.name}") + return found + + +def test_every_function_that_filters_on_the_owner_is_tenant_aware() -> None: + assert _owner_filters_without_the_tenant() == [] + + +@pytest.mark.parametrize("path", SOURCES, ids=lambda p: str(p.relative_to(ROOT))) +def test_no_partition_key_is_built_by_hand(path: Path) -> None: + text = path.read_text() + by_hand = re.findall(r"partition_key\s*=\s*\[", text) + assert by_hand == [], f"{path.relative_to(ROOT)} builds a partition key list by hand; use partition_key_for" + + +def test_containers_are_created_with_the_tenant_and_owner_key() -> None: + for name in ("cosmos_memory_client.py", "aio/cosmos_memory_client.py"): + text = (ROOT / "azure" / "cosmos" / "agent_memory" / name).read_text() + assert 'PartitionKey(path=list(PARTITION_KEY_PATHS), kind="MultiHash")' in text, name + assert '"/thread_id"]' not in text.replace('{"path": "/thread_id", "order": "ascending"}', ""), name + + +def test_an_existing_container_is_checked_for_the_key_when_the_store_is_created() -> None: + for name in ("cosmos_memory_client.py", "aio/cosmos_memory_client.py"): + text = (ROOT / "azure" / "cosmos" / "agent_memory" / name).read_text() + assert text.count("_require_partition_key(") >= 2, name + assert "partition_key_problem(container_id, properties)" in text, name diff --git a/tests/unit/test_utils.py b/tests/unit/test_utils.py index da724ef..b9f4347 100644 --- a/tests/unit/test_utils.py +++ b/tests/unit/test_utils.py @@ -7,6 +7,7 @@ DEFAULT_TTL_BY_TYPE, MAX_FULLTEXT_TERMS, _build_container_kwargs, + _build_memory_query_builder, _container_policies, _make_memory, _resolve_distance_function, @@ -54,6 +55,30 @@ def test_build_container_kwargs_omits_offer_throughput_when_none(): } +# --------------------------------------------------------------------------- +# _build_memory_query_builder +# --------------------------------------------------------------------------- + + +def test_memory_query_builder_is_confined_to_the_tenant_and_owner(): + qb = _build_memory_query_builder(tenant_id="acme", user_id="u1", thread_id="t1", memory_types=["fact"]) + + assert qb.build_where().startswith(" WHERE c.tenant_id = @tenant_id AND c.user_id = @user_id AND ") + assert qb.get_parameters()[:2] == [{"name": "@tenant_id", "value": "acme"}, {"name": "@user_id", "value": "u1"}] + + +def test_memory_query_builder_without_an_owner_reads_the_whole_tenant_only(): + qb = _build_memory_query_builder(tenant_id="acme", role="user") + + assert qb.build_where() == " WHERE c.tenant_id = @tenant_id AND c.role = @role" + assert "@user_id" not in {p["name"] for p in qb.get_parameters()} + + +def test_memory_query_builder_requires_a_tenant(): + with pytest.raises(TypeError): + _build_memory_query_builder(user_id="u1") # type: ignore[call-arg] + + # --------------------------------------------------------------------------- # compute_content_hash # --------------------------------------------------------------------------- From 87b385e503b74b0a75f4bed2573d8ebe912694bf Mon Sep 17 00:00:00 2001 From: Aayush Kataria Date: Tue, 17 Nov 2026 15:53:38 -0800 Subject: [PATCH 2/4] Link PR #53 in the changelog Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CHANGELOG.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 53b40a1..79c365f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,16 +3,16 @@ ## [Unreleased] #### Features Added -* **Memories are keyed by tenant and owner.** Every record lives in the partition `[tenant_id, user_id]`, where `user_id` is the owner of the memory, a user or an agent, and `thread_id` is a plain field. Everything one owner knows now sits in one partition. Pass `tenant_id` to the client (default `"default"`) to keep several apps or customers apart in the same containers; the Function App follows the tenant of each record. -* **A container with the wrong partition key is refused.** `create_memory_store()`, which the client constructor calls, now fails with a clear message when an existing container is not keyed `[/tenant_id, /user_id]`, and `validate_topology()` checks the key of `memories`, `memories_turns`, `memories_summaries` and `counter`. The Function App makes the same check on its first change-feed batch. A container keyed the earlier way takes writes but reads back empty. +* **Memories are keyed by tenant and owner.** Every record lives in the partition `[tenant_id, user_id]`, where `user_id` is the owner of the memory, a user or an agent, and `thread_id` is a plain field. Everything one owner knows now sits in one partition. Pass `tenant_id` to the client (default `"default"`) to keep several apps or customers apart in the same containers; the Function App follows the tenant of each record. See [PR:#53](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/53) +* **A container with the wrong partition key is refused.** `create_memory_store()`, which the client constructor calls, now fails with a clear message when an existing container is not keyed `[/tenant_id, /user_id]`, and `validate_topology()` checks the key of `memories`, `memories_turns`, `memories_summaries` and `counter`. The Function App makes the same check on its first change-feed batch. A container keyed the earlier way takes writes but reads back empty. See [PR:#53](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/53) #### Breaking Changes -* **The containers use a new partition key.** `memories`, `memories_turns`, `memories_summaries` and `counter` are keyed `[/tenant_id, /user_id]` instead of `[/user_id, /thread_id]` (the Bicep template and `create_memory_store()`). A partition key can't change in place, so recreate those containers, and `leases` too so the change feed starts clean; existing data is not migrated. Record ids must now be unique per owner across threads, not per thread. -* **`user_id` is validated.** An owner id must be a non-empty string of at most 256 UTF-8 bytes without `/`, `\`, `?`, `#` or control characters, the rules a `tenant_id` already followed. Anything else raises `ValidationError`. -* **`thread_id` is no longer needed to find a record.** It is removed from `update_cosmos()`, `delete_memory()`, `delete_turn()`, `add_tags()`, `remove_tags()` and `get_memory_history()`, and `MemoryNotFoundError` no longer carries it. It still filters reads and names the thread for thread operations. +* **The containers use a new partition key.** `memories`, `memories_turns`, `memories_summaries` and `counter` are keyed `[/tenant_id, /user_id]` instead of `[/user_id, /thread_id]` (the Bicep template and `create_memory_store()`). A partition key can't change in place, so recreate those containers, and `leases` too so the change feed starts clean; existing data is not migrated. Record ids must now be unique per owner across threads, not per thread. See [PR:#53](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/53) +* **`user_id` is validated.** An owner id must be a non-empty string of at most 256 UTF-8 bytes without `/`, `\`, `?`, `#` or control characters, the rules a `tenant_id` already followed. Anything else raises `ValidationError`. See [PR:#53](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/53) +* **`thread_id` is no longer needed to find a record.** It is removed from `update_cosmos()`, `delete_memory()`, `delete_turn()`, `add_tags()`, `remove_tags()` and `get_memory_history()`, and `MemoryNotFoundError` no longer carries it. It still filters reads and names the thread for thread operations. See [PR:#53](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/53) #### Other Changes -* Orchestration instance ids in the Function App are now `:[:]`, where the digest is a fixed-length hash of the tenant, owner and thread. They stay within Durable Functions' 100-character limit and no longer contain user ids. +* Orchestration instance ids in the Function App are now `:[:]`, where the digest is a fixed-length hash of the tenant, owner and thread. They stay within Durable Functions' 100-character limit and no longer contain user ids. See [PR:#53](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/53) ## [0.4.0b1] (2026-11-16) From 787dd495961a438a31d6cad9426b249b0cf64a6a Mon Sep 17 00:00:00 2001 From: Aayush Kataria Date: Tue, 17 Nov 2026 19:02:50 -0800 Subject: [PATCH 3/4] Resolving comments --- CHANGELOG.md | 7 +- Docs/azure_testing.md | 4 +- Docs/concepts.md | 14 +- Docs/design_patterns.md | 6 +- Docs/local_testing.md | 4 +- Docs/operations.md | 2 +- Docs/public_api.md | 28 +- Docs/troubleshooting.md | 12 +- README.md | 17 +- .../cosmos/agent_memory/_base/base_client.py | 20 +- azure/cosmos/agent_memory/_partitioning.py | 35 +- .../agent_memory/aio/cosmos_memory_client.py | 43 +- .../agent_memory/aio/processors/inprocess.py | 8 +- .../agent_memory/aio/services/pipeline.py | 13 +- .../agent_memory/aio/store/memory_store.py | 3 + .../agent_memory/cosmos_memory_client.py | 28 +- azure/cosmos/agent_memory/models.py | 5 +- .../agent_memory/processors/inprocess.py | 8 +- .../cosmos/agent_memory/services/pipeline.py | 13 +- .../cosmos/agent_memory/store/memory_store.py | 3 + function_app/triggers/change_feed.py | 237 ++++--- infra/README.md | 4 +- tests/unit/aio/processors/test_inprocess.py | 22 +- .../services/test_extract_episodes_async.py | 21 + .../services/test_tenant_isolation_async.py | 96 ++- tests/unit/aio/test_cosmos_memory_client.py | 157 ++++- tests/unit/function_app/test_change_feed.py | 275 ++++++++ tests/unit/processors/test_inprocess.py | 20 + tests/unit/services/test_extract_dry.py | 40 +- tests/unit/services/test_pipeline_service.py | 63 ++ tests/unit/store/test_tenant_isolation.py | 31 + tests/unit/test_cosmos_memory_client.py | 123 ++++ tests/unit/test_models.py | 6 +- tests/unit/test_partitioning.py | 68 +- tests/unit/test_tenant_scope_guard.py | 618 +++++++++++++++++- 35 files changed, 1836 insertions(+), 218 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 79c365f..f0b951c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,13 +3,10 @@ ## [Unreleased] #### Features Added -* **Memories are keyed by tenant and owner.** Every record lives in the partition `[tenant_id, user_id]`, where `user_id` is the owner of the memory, a user or an agent, and `thread_id` is a plain field. Everything one owner knows now sits in one partition. Pass `tenant_id` to the client (default `"default"`) to keep several apps or customers apart in the same containers; the Function App follows the tenant of each record. See [PR:#53](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/53) -* **A container with the wrong partition key is refused.** `create_memory_store()`, which the client constructor calls, now fails with a clear message when an existing container is not keyed `[/tenant_id, /user_id]`, and `validate_topology()` checks the key of `memories`, `memories_turns`, `memories_summaries` and `counter`. The Function App makes the same check on its first change-feed batch. A container keyed the earlier way takes writes but reads back empty. See [PR:#53](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/53) +* **Memories are keyed by tenant and owner.** Every record lives in the partition `[tenant_id, user_id]`, where `user_id` is the owner of the memory, a user or an agent, and `thread_id` is a plain field. Everything one owner knows now sits in one partition. Pass `tenant_id` to the client (default `"default"`) to keep several apps or customers apart in the same containers; it separates data but is not an access-control boundary. `InProcessProcessor` and `AsyncInProcessProcessor` expose a read-only `tenant_id`, and a client raises `ConfigurationError` when its `processor` works in another tenant. The Function App follows the tenant of each record, and a failure for one thread or owner no longer stops the rest of its batch. See [PR:#53](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/53) #### Breaking Changes -* **The containers use a new partition key.** `memories`, `memories_turns`, `memories_summaries` and `counter` are keyed `[/tenant_id, /user_id]` instead of `[/user_id, /thread_id]` (the Bicep template and `create_memory_store()`). A partition key can't change in place, so recreate those containers, and `leases` too so the change feed starts clean; existing data is not migrated. Record ids must now be unique per owner across threads, not per thread. See [PR:#53](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/53) -* **`user_id` is validated.** An owner id must be a non-empty string of at most 256 UTF-8 bytes without `/`, `\`, `?`, `#` or control characters, the rules a `tenant_id` already followed. Anything else raises `ValidationError`. See [PR:#53](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/53) -* **`thread_id` is no longer needed to find a record.** It is removed from `update_cosmos()`, `delete_memory()`, `delete_turn()`, `add_tags()`, `remove_tags()` and `get_memory_history()`, and `MemoryNotFoundError` no longer carries it. It still filters reads and names the thread for thread operations. See [PR:#53](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/53) +* **The containers use a new partition key.** `memories`, `memories_turns`, `memories_summaries` and `counter` are keyed `[/tenant_id, /user_id]` instead of `[/user_id, /thread_id]` (the Bicep template and `create_memory_store()`). A partition key can't change in place, so recreate those containers and `leases`, in the order given in the [migration notes](README.md#migration-notes) (every writer stopped, in-flight orchestrations purged, the Function App deployed before the upgraded writers); existing data is not migrated. Record ids must now be unique per owner across threads, not per thread. See [PR:#53](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/53) #### Other Changes * Orchestration instance ids in the Function App are now `:[:]`, where the digest is a fixed-length hash of the tenant, owner and thread. They stay within Durable Functions' 100-character limit and no longer contain user ids. See [PR:#53](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/53) diff --git a/Docs/azure_testing.md b/Docs/azure_testing.md index 835f22d..fdd1d79 100644 --- a/Docs/azure_testing.md +++ b/Docs/azure_testing.md @@ -255,11 +255,11 @@ memory = AsyncCosmosMemoryClient( cosmos_credential=AsyncDefaultAzureCredential(), ) -await memory.connect_cosmos() await memory.create_memory_store() +await memory.connect_cosmos() ``` -This provisions the `memories`, `memories_turns`, `memories_summaries`, `counter`, and `leases` containers. The first four get the hierarchical partition key `/tenant_id`, `/user_id` (`leases` uses `/id`); an existing container keeps its key, so recreate the containers that an earlier version created with `[/user_id, /thread_id]`, and `leases` with them so the change feed starts clean on the recreated turns container. `serverless` is the default throughput mode; if you set `COSMOS_DB_THROUGHPUT_MODE=autoscale`, the shared `COSMOS_DB_AUTOSCALE_MAX_RU` value is applied to all five containers. The Function App does not read either variable. +This provisions the `memories`, `memories_turns`, `memories_summaries`, `counter`, and `leases` containers. The first four get the hierarchical partition key `/tenant_id`, `/user_id` (`leases` uses `/id`); an existing container keeps its key, and `create_memory_store()` and `connect_cosmos()` refuse one that is not keyed `[/tenant_id, /user_id]`, so recreate the containers that an earlier version created with `[/user_id, /thread_id]`, and `leases` with them (the README's [migration notes](../README.md#migration-notes) give the steps in order). `serverless` is the default throughput mode; if you set `COSMOS_DB_THROUGHPUT_MODE=autoscale`, the shared `COSMOS_DB_AUTOSCALE_MAX_RU` value is applied to all five containers. The Function App does not read either variable. On a new database, create the store before connecting, because `connect_cosmos()` refuses a container that does not exist. --- diff --git a/Docs/concepts.md b/Docs/concepts.md index 59ec320..14f74e4 100644 --- a/Docs/concepts.md +++ b/Docs/concepts.md @@ -31,11 +31,13 @@ Every record lives in the logical partition `[tenant_id, user_id]`: the `memorie - **`user_id`** is the owner of the memory: a user or an agent. It is a plain string, so keep the ids distinct (for example `agent:support-bot`). The same `user_id` in two tenants is two owners. - **`thread_id`** is a plain field, not part of the key. It filters reads and names the thread for thread operations, but everything one owner knows (turns, facts, episodes, procedures, summaries, counters) sits in one partition of its container. Sentinel thread ids such as `__user_summary__` and `__procedural__` are marker values on documents, not partitions. -A record id is unique per owner across all of the owner's threads. A tenant id or an owner id is a non-empty string of at most 256 UTF-8 bytes without `/`, `\`, `?`, `#` or control characters, because ids appear in Cosmos DB document ids; anything else raises `ValidationError`. A query that names the owner reads one partition (a keyword search is the exception, see [Keyword search and partition scope](#keyword-search-and-partition-scope)); a read where `user_id` is optional and left out, such as `get_memories()`, covers every owner in the client's tenant, across partitions. +`tenant_id` is not an access-control boundary. It separates data inside the same containers, so anyone who can read the Cosmos DB account's data can read every tenant. For hard isolation use separate databases or accounts, and Azure RBAC to control who reaches them. -Cosmos DB limits a logical partition to 20 GB of data and 10,000 RU/s, so the limits apply per owner. Keep any one owner, such as an agent shared by many users, well below them. +A record id is unique per owner across all of the owner's threads. A tenant id, an owner id and a `thread_id` must each be a non-empty string of at most 256 UTF-8 bytes that does not start or end with whitespace and has no `/`, `\`, `?`, `#` or control characters (DEL, U+0080-U+009F and the line and paragraph separators included), because they appear in Cosmos DB document ids, which cannot end in a space or newline. A value that breaks these rules raises `ValidationError` when the client writes it. A query that names the owner reads one partition (a keyword search is the exception, see [Keyword search and partition scope](#keyword-search-and-partition-scope)); a read where `user_id` is optional and left out, such as `get_memories()`, covers every owner in the client's tenant, across partitions. -A container's partition key cannot be changed in place. `create_memory_store()` creates the containers with this key, so a deployment whose containers have the earlier `[/user_id, /thread_id]` key must recreate `memories`, `memories_turns`, `memories_summaries` and `counter`, and `leases` with them so the change feed starts clean on the recreated turns container; existing data is not migrated. `create_memory_store()` refuses an existing container keyed otherwise with an error that names the container and its key, and `validate_topology()` makes the same check after `connect_cosmos()`: a container with the earlier key takes writes but reads back empty. +Each owner's partition `[tenant_id, user_id]` can hold up to 20 GB of data and 10,000 RU/s, the Cosmos DB limits of a logical partition. A deployment with one tenant has the same `tenant_id` (`"default"`) at the first level of every key, which is fine: the hierarchical key spreads data by `user_id`. One very busy owner, such as one agent id shared by every user, is bounded by those per-partition limits, so spread such a workload over several ids. + +A container's partition key cannot be changed in place, so a deployment whose containers have the earlier `[/user_id, /thread_id]` key must recreate them (and `leases`) and existing data is not migrated: the README's [migration notes](../README.md#migration-notes) give the steps in order. `connect_cosmos()` reads the metadata of `memories`, `memories_turns`, `memories_summaries` and `counter` (four reads) and raises `CosmosOperationError`, naming the container, when one is missing or not keyed `[/tenant_id, /user_id]`; the client is closed again on failure. `create_memory_store()` creates what is missing and then makes the same check. The sync client's constructor calls it when it is given an endpoint, but the async constructor does no I/O, so connect an async client with `await client.connect_cosmos()` or `await client.create_memory_store()`. `validate_topology()` remains the explicit diagnostic. A container with the earlier key would take writes but read back empty, which is why it is refused. --- @@ -203,7 +205,7 @@ Slots need `user_id` and are skipped when `memory_id` is set or when they would ### Keyword search and partition scope -A keyword (hybrid) query ranks with `FullTextScore`, which is ignored in a query the Python SDK sends with a partition key, because it skips query planning ([Azure/azure-sdk-for-python#42241](https://github.com/Azure/azure-sdk-for-python/issues/42241)), so every question would get the same fixed order. A search that has keywords therefore runs across partitions with `c.tenant_id`, `c.user_id` (and `c.thread_id`, when given) in the `WHERE` clause, which confines it to the client's tenant and the same owner, and sets `full_text_score_scope="Local"` so BM25 statistics come from the partition ranges the query targets. This applies to `search_cosmos`, `search_turns`, `search_summaries`, `search_episodic_memories` and `retrieve_procedures`; expect more RUs than a single-partition read on a large container. A query whose terms are all stopwords has no keywords and ranks by vector similarity alone; with a `user_id` it reads one partition, the owner's, whatever the `thread_id`. A search without a `user_id` covers every owner in the client's tenant and always runs across partitions. `MemoryStore.query()` raises `ValidationError` for a `FullTextScore` query sent with a partition key. +A keyword (hybrid) query ranks with `FullTextScore`, which is ignored in a query the Python SDK sends with a partition key, because it skips query planning ([Azure/azure-sdk-for-python#42241](https://github.com/Azure/azure-sdk-for-python/issues/42241); see also [#49289](https://github.com/Azure/azure-sdk-for-python/pull/49289)), so every question would get the same fixed order. A search that has keywords therefore runs across partitions with `c.tenant_id`, `c.user_id` (and `c.thread_id`, when given) in the `WHERE` clause, which confines it to the client's tenant and the same owner, and sets `full_text_score_scope="Local"` so BM25 statistics come from the partition ranges the query targets. This applies to `search_cosmos`, `search_turns`, `search_summaries`, `search_episodic_memories` and `retrieve_procedures`; expect more RUs than a single-partition read on a large container. A query whose terms are all stopwords has no keywords and ranks by vector similarity alone; with a `user_id` it reads one partition, the owner's, whatever the `thread_id`. A search without a `user_id` covers every owner in the client's tenant and always runs across partitions. `MemoryStore.query()` raises `ValidationError` for a `FullTextScore` query sent with a partition key. --- @@ -366,9 +368,9 @@ on_memory_change trigger ### How it works 1. The change feed trigger watches the `memories_turns` container for new documents. -2. Only documents with `type == "turn"` are counted. The trigger reads `tenant_id` from each changed turn, next to `user_id` and `thread_id`, and skips a turn without a valid `tenant_id` with a warning. +2. Only documents with `type == "turn"` are counted. The trigger reads `tenant_id` from each changed turn, next to `user_id` and `thread_id`, and skips a turn whose tenant, owner or thread id is missing or not valid (the rules are in [Tenants and Owners](#tenants-and-owners)) with a warning. 3. Documents in the dedicated `counter` container track how many turns have been seen per scope using ETag-based optimistic concurrency. -4. When a counter crosses a configured threshold, the corresponding Durable Functions orchestration is started automatically, in the tenant of the turns it counted. The Function App needs no tenant setting. +4. When a counter crosses a configured threshold, the corresponding Durable Functions orchestration is started automatically, in the tenant of the turns it counted. The Function App needs no tenant setting. A failure while counting or starting orchestrations for one thread or owner does not stop the rest of the batch, so every other tenant's counters are still updated; the batch still fails at the end so the host records it. ### Threshold settings diff --git a/Docs/design_patterns.md b/Docs/design_patterns.md index 3b6d8d5..e46ece6 100644 --- a/Docs/design_patterns.md +++ b/Docs/design_patterns.md @@ -359,7 +359,7 @@ When a new turn is written to the `memories_turns` container, the change feed tr 2. Checks whether the counter has crossed a configured threshold. 3. Starts the appropriate Durable Functions orchestration if the threshold is crossed. -The trigger reads `tenant_id` from each changed turn and processes it in that tenant, so one Function App serves every tenant that shares the database, with no tenant setting. A turn without a valid `tenant_id` is skipped with a warning. +The trigger reads `tenant_id` from each changed turn and processes it in that tenant, so one Function App serves every tenant that shares the database, with no tenant setting. A turn whose tenant, owner or thread id is missing or not valid is skipped with a warning. ### Configuration @@ -522,7 +522,7 @@ await acme.upsert_memory(user_id="user-1", thread_id="t-1", role="user", content await globex.get_thread(thread_id="t-1", user_id="user-1") # [] - "user-1" at Globex is a different owner ``` -The tenant is never a per-call argument and has no setting, so a call cannot reach into another tenant. The Function App follows the `tenant_id` stored on each turn. +The tenant is never a per-call argument and has no setting, so a call cannot reach into another tenant. The Function App follows the `tenant_id` stored on each turn. A tenant keeps data apart but is not an access-control boundary: anyone who can read the account's data can read every tenant (see [Tenants and Owners](concepts.md#tenants-and-owners)). ### An agent as owner @@ -539,7 +539,7 @@ await mem.upsert_memory( facts = await mem.search_cosmos("refund limits", user_id=AGENT, memory_types=["fact"], top_k=3) ``` -Everything an owner knows sits in one partition, and Cosmos DB limits a logical partition to 20 GB of data and 10,000 RU/s. Keep each user's memories under that user's id and put only what belongs to the agent itself under the agent's, so that no single owner, such as an agent shared by many users, outgrows those limits. +Everything an owner knows sits in one partition, and Cosmos DB limits a logical partition to 20 GB of data and 10,000 RU/s. Keep each user's memories under that user's id and put only what belongs to the agent itself under the agent's, so that no single owner, such as an agent shared by many users, outgrows those limits. If one agent id would carry the load of every user, spread it over several ids. --- diff --git a/Docs/local_testing.md b/Docs/local_testing.md index e462336..0a61f75 100644 --- a/Docs/local_testing.md +++ b/Docs/local_testing.md @@ -218,13 +218,13 @@ memory = AsyncCosmosMemoryClient( cosmos_credential=AsyncDefaultAzureCredential(), ) +await memory.create_memory_store() await memory.connect_cosmos( endpoint=os.getenv("COSMOS_DB_ENDPOINT"), database=os.getenv("COSMOS_DB_DATABASE"), container=os.getenv("COSMOS_DB_MEMORIES_CONTAINER"), credential=AsyncDefaultAzureCredential(), ) -await memory.create_memory_store() thread_id = str(uuid.uuid4()) await memory.upsert_memory(user_id="user-001", role="user", thread_id=thread_id, content="Async Cosmos write") @@ -235,7 +235,7 @@ for r in results: await memory.close() ``` -`create_memory_store()` creates the database and the `memories`, `memories_turns`, `memories_summaries`, `counter`, and `leases` containers. It configures the hierarchical partition key (`/tenant_id`, `/user_id`) for the first four and `/id` for `leases`, gives a newly created `memories_turns` container a 30-day default TTL and a newly created `counter` container a 90-day one, and applies either serverless or autoscale throughput based on `cosmos_throughput_mode` (set from `COSMOS_DB_THROUGHPUT_MODE` above). An existing container keeps its key, so recreate the containers that an earlier version created with `[/user_id, /thread_id]`, and `leases` with them so the change feed starts clean on the recreated turns container. +`create_memory_store()` creates the database and the `memories`, `memories_turns`, `memories_summaries`, `counter`, and `leases` containers. It configures the hierarchical partition key (`/tenant_id`, `/user_id`) for the first four and `/id` for `leases`, gives a newly created `memories_turns` container a 30-day default TTL and a newly created `counter` container a 90-day one, and applies either serverless or autoscale throughput based on `cosmos_throughput_mode` (set from `COSMOS_DB_THROUGHPUT_MODE` above). An existing container keeps its key, and `create_memory_store()` and `connect_cosmos()` refuse one that is not keyed `[/tenant_id, /user_id]`, so recreate the containers that an earlier version created with `[/user_id, /thread_id]`, and `leases` with them (the README's [migration notes](../README.md#migration-notes) give the steps in order). On a new database, create the store before connecting, because `connect_cosmos()` refuses a container that does not exist. --- diff --git a/Docs/operations.md b/Docs/operations.md index 54795ac..3cff27e 100644 --- a/Docs/operations.md +++ b/Docs/operations.md @@ -33,7 +33,7 @@ Function-app threshold knobs (`THREAD_SUMMARY_EVERY_N`, `FACT_EXTRACTION_EVERY_N ## Tenants -The tenant is not a setting. A client takes `tenant_id` as a constructor argument (default `"default"`), and the Function App processes each turn in the tenant stored on it, so one deployment serves every tenant of the database. See [Tenants and Owners](concepts.md#tenants-and-owners). +The tenant is not a setting. A client takes `tenant_id` as a constructor argument (default `"default"`), and the Function App processes each turn in the tenant stored on it, so one deployment serves every tenant of the database. Each owner's partition `[tenant_id, user_id]` can hold up to 20 GB and 10,000 RU/s, so spread one very busy owner, such as one agent id shared by every user, over several ids. See [Tenants and Owners](concepts.md#tenants-and-owners). ## Reconcile, procedure and extraction knobs diff --git a/Docs/public_api.md b/Docs/public_api.md index 6ff0614..0fe2907 100644 --- a/Docs/public_api.md +++ b/Docs/public_api.md @@ -13,15 +13,15 @@ ### Connection -- `__init__(cosmos_endpoint=None, cosmos_credential=None, cosmos_key=None, cosmos_database=None, cosmos_container=None, cosmos_turns_container='memories_turns', cosmos_summaries_container='memories_summaries', cosmos_counter_container=None, cosmos_lease_container=None, cosmos_throughput_mode=None, cosmos_autoscale_max_ru=None, ai_foundry_endpoint=None, ai_foundry_credential=None, ai_foundry_api_key=None, embedding_deployment_name='text-embedding-3-large', embedding_dimensions=None, chat_deployment_name='gpt-4o-mini', use_default_credential=True, enable_turn_embeddings=None, user_agent=None, embeddings_client=None, chat_client=None, processor=None, transcript_metadata_keys=None, cadence_thresholds=None, cosmos_preferred_locations=None, tenant_id=None) -> None` - configure local state, model clients, optional Cosmos auto-connect (with a `cosmos_endpoint` it calls `create_memory_store()`, which creates any missing database or container), and optional processing backend. The SDK uses a hard 3-container topology: turns in `memories_turns`, facts/episodic/procedural in `memories`, and summaries in `memories_summaries` (or the names you pass). `enable_turn_embeddings` (default `False`, env `ENABLE_TURN_EMBEDDINGS`) embeds raw turns on write so they can be vector-searched via `search_turns()`; the turns container is always provisioned with a vector index, so toggling this never requires recreating it. `cosmos_preferred_locations` (a list or a comma-separated string, env `COSMOS_DB_PREFERRED_REGIONS`) orders the Cosmos DB regions the client reads from, closest first; unset keeps the account's default order. `tenant_id` (`None` selects `"default"`) binds the client to one tenant: every record it writes carries it, and every read and write stays inside it (see [Tenants and Owners](concepts.md#tenants-and-owners)). It is set once, here, never per call, and has no environment variable; an invalid value raises `ValidationError`, and the read-only `tenant_id` property returns it. +- `__init__(cosmos_endpoint=None, cosmos_credential=None, cosmos_key=None, cosmos_database=None, cosmos_container=None, cosmos_turns_container='memories_turns', cosmos_summaries_container='memories_summaries', cosmos_counter_container=None, cosmos_lease_container=None, cosmos_throughput_mode=None, cosmos_autoscale_max_ru=None, ai_foundry_endpoint=None, ai_foundry_credential=None, ai_foundry_api_key=None, embedding_deployment_name='text-embedding-3-large', embedding_dimensions=None, chat_deployment_name='gpt-4o-mini', use_default_credential=True, enable_turn_embeddings=None, user_agent=None, embeddings_client=None, chat_client=None, processor=None, transcript_metadata_keys=None, cadence_thresholds=None, cosmos_preferred_locations=None, tenant_id=None) -> None` - configure local state, model clients, optional Cosmos auto-connect (with a `cosmos_endpoint` it calls `create_memory_store()`, which creates any missing database or container and raises `CosmosOperationError` for one not keyed `[/tenant_id, /user_id]`), and optional processing backend. The SDK uses a hard 3-container topology: turns in `memories_turns`, facts/episodic/procedural in `memories`, and summaries in `memories_summaries` (or the names you pass). `enable_turn_embeddings` (default `False`, env `ENABLE_TURN_EMBEDDINGS`) embeds raw turns on write so they can be vector-searched via `search_turns()`; the turns container is always provisioned with a vector index, so toggling this never requires recreating it. `cosmos_preferred_locations` (a list or a comma-separated string, env `COSMOS_DB_PREFERRED_REGIONS`) orders the Cosmos DB regions the client reads from, closest first; unset keeps the account's default order. `tenant_id` (`None` selects `"default"`) binds the client to one tenant: every record it writes carries it, and every read and write stays inside it (see [Tenants and Owners](concepts.md#tenants-and-owners)). It is set once, here, never per call, and has no environment variable; an invalid value raises `ValidationError`, and the read-only `tenant_id` property returns it. It separates data inside the same containers and is not an access-control boundary: anyone who can read the account's data can read every tenant, so use separate databases or accounts and Azure RBAC for hard isolation. A `processor` that works in another tenant raises `ConfigurationError` (see [Extension Points](#extension-points)). - `close() -> None` - close Cosmos/model clients and owned credentials. -- `connect_cosmos(endpoint=None, credential=None, key=None, database=None, container=None, turns_container=None, summaries_container=None) -> None` - connect to existing memory, turns, and summaries containers. -- `create_memory_store(database=None, container=None, turns_container=None, summaries_container=None, counter_container=None, lease_container=None, endpoint=None, credential=None, key=None, embedding_dimensions=None, embedding_data_type=None, distance_function=None, full_text_language=None, throughput_mode=None, autoscale_max_ru=None, vector_index_type=None) -> None` - create/connect the memory, turns, summaries, counter, and lease containers. The memory, turns, summaries and counter containers get the hierarchical partition key `/tenant_id`, `/user_id` (`leases` uses `/id`); an existing container keeps its key, and `create_memory_store()` raises `CosmosOperationError` when one of them is keyed otherwise, so recreate the containers created with an earlier key, and `leases` with them so the change feed starts clean on the recreated turns container (see [Tenants and Owners](concepts.md#tenants-and-owners)). `vector_index_type` (`quantizedFlat` by default, `diskANN` or `flat`) sets the memories container's vector index; the turns and summaries containers always use `quantizedFlat`. -- `validate_topology() -> None` - read metadata for the memories, turns, summaries and counter containers and raise `RuntimeError` if any is missing, unreachable, or not keyed `[/tenant_id, /user_id]`; call after connecting to catch infrastructure/config drift before writes. +- `connect_cosmos(endpoint=None, credential=None, key=None, database=None, container=None, turns_container=None, summaries_container=None) -> None` - connect to existing memory, turns, and summaries containers, then read the metadata of `memories`, `memories_turns`, `memories_summaries` and `counter` (four reads) and raise `CosmosOperationError`, naming the container, if one is missing or not keyed `[/tenant_id, /user_id]`; the client is closed again on failure. +- `create_memory_store(database=None, container=None, turns_container=None, summaries_container=None, counter_container=None, lease_container=None, endpoint=None, credential=None, key=None, embedding_dimensions=None, embedding_data_type=None, distance_function=None, full_text_language=None, throughput_mode=None, autoscale_max_ru=None, vector_index_type=None) -> None` - create/connect the memory, turns, summaries, counter, and lease containers. The memory, turns, summaries and counter containers get the hierarchical partition key `/tenant_id`, `/user_id` (`leases` uses `/id`); an existing container keeps its key. After creating what is missing, `create_memory_store()` makes the same check as `connect_cosmos()` and raises `CosmosOperationError`, naming the container, when one of them is not keyed `[/tenant_id, /user_id]` (the client is closed again). Containers created with an earlier key must be recreated, and `leases` with them: the README's [migration notes](../README.md#migration-notes) give the steps in order. `vector_index_type` (`quantizedFlat` by default, `diskANN` or `flat`) sets the memories container's vector index; the turns and summaries containers always use `quantizedFlat`. +- `validate_topology() -> None` - the explicit diagnostic: read metadata for the memories, turns, summaries and counter containers and raise `RuntimeError` if any is missing, unreachable, or not keyed `[/tenant_id, /user_id]`. `connect_cosmos()` and `create_memory_store()` already make a similar check when they connect (raising `CosmosOperationError`); call this to check again later. ### Memory CRUD -`update_cosmos`, `delete_memory`, `delete_turn`, `add_tags`, `remove_tags` and `get_memory_history` find a record by its owner (`user_id`) and need no `thread_id`: `thread_id` is a plain field, not part of the partition key. +`update_cosmos`, `delete_memory`, `delete_turn`, `add_tags`, `remove_tags` and `get_memory_history` find a record by its owner (`user_id`) and need no `thread_id`: `thread_id` is a plain field, not part of the partition key. A `user_id` or `thread_id` that breaks the identifier rules in [Tenants and Owners](concepts.md#tenants-and-owners) (such as one that ends in whitespace) raises `ValidationError` when the client writes it. - `add_local(user_id, role, content, memory_type='turn', agent_id=None, metadata=None, thread_id=None, tags=None, ttl=None, salience=None) -> None` - append a memory to the local buffer. `thread_id` is required when `memory_type='turn'`. - `get_local(memory_id=None, user_id=None, role=None, memory_types=None) -> list[dict]` - filter local buffered memories. @@ -65,7 +65,7 @@ compete with facts in one ranked result set. #### Search scoping, procedures and slots -- **Partitions.** A keyword query ranks with `FullTextScore`, which is ignored in a query the Python SDK sends with a partition key, because it skips query planning ([Azure/azure-sdk-for-python#42241](https://github.com/Azure/azure-sdk-for-python/issues/42241)). `search_cosmos`, `search_turns`, `search_summaries`, `search_episodic_memories` and `retrieve_procedures` therefore run a keyword query across partitions, with `c.tenant_id`, `c.user_id` (and `c.thread_id`, when given) in the `WHERE` clause, and set `full_text_score_scope="Local"` so BM25 statistics come from the partition ranges the query targets. The filters still confine the results to the client's tenant and, with a `user_id`, to the same owner (in `search_cosmos`, episodic and procedural memories match on the owner alone, whatever the `thread_id`); ranking now follows the question. Expect more RUs than a single-partition read on a large container. A vector-only query (all-stopword terms) with a `user_id` reads one partition, the owner's, whatever the `thread_id`; a `search_cosmos` without a `user_id` covers every owner in the tenant and always runs across partitions. `MemoryStore.query()` and `AsyncMemoryStore.query()` raise `ValidationError` for a `FullTextScore` query sent with a partition key; filter on `c.tenant_id`, `c.user_id` and `c.thread_id` in the `WHERE` clause instead. +- **Partitions.** A keyword query ranks with `FullTextScore`, which is ignored in a query the Python SDK sends with a partition key, because it skips query planning ([Azure/azure-sdk-for-python#42241](https://github.com/Azure/azure-sdk-for-python/issues/42241); see also [#49289](https://github.com/Azure/azure-sdk-for-python/pull/49289)). `search_cosmos`, `search_turns`, `search_summaries`, `search_episodic_memories` and `retrieve_procedures` therefore run a keyword query across partitions, with `c.tenant_id`, `c.user_id` (and `c.thread_id`, when given) in the `WHERE` clause, and set `full_text_score_scope="Local"` so BM25 statistics come from the partition ranges the query targets. The filters still confine the results to the client's tenant and, with a `user_id`, to the same owner (in `search_cosmos`, episodic and procedural memories match on the owner alone, whatever the `thread_id`); ranking now follows the question. Expect more RUs than a single-partition read on a large container. A vector-only query (all-stopword terms) with a `user_id` reads one partition, the owner's, whatever the `thread_id`; a `search_cosmos` without a `user_id` covers every owner in the tenant and always runs across partitions. `MemoryStore.query()` and `AsyncMemoryStore.query()` raise `ValidationError` for a `FullTextScore` query sent with a partition key; filter on `c.tenant_id`, `c.user_id` and `c.thread_id` in the `WHERE` clause instead. - **Procedures.** `search_cosmos` hides procedures that are not `active` (a `candidate`, for one) or are past `valid_until` (an ISO date; no value means no end). `get_procedural_memories` lists them and `retrieve_procedures(..., status=None)` ranks candidates. - **Slots** (opt-in). `preference_slot=True` reserves one of the `top_k` results for the user's best-matching preference fact (`metadata.category="preference"`) that the ranked results do not already show. `procedure_slot=True` reserves one for the user's best-matching active situational procedure (`applies="when"`); procedures then leave the ranked results. Slot candidates are ranked by vector similarity alone and use the search's own filters, except that the procedure slot ignores `role`, `tags_all`, `tags_any`, `min_salience` and `min_confidence`, which no procedure can meet (a procedure has no salience or confidence, its role is `system` and its tags are the toolkit's own). A slot with no candidate takes the next ranked result, so `top_k` stays filled. A slotted result carries `retrieval={"rank": <1-based position>, "slot": "preference" | "procedure" | "backfill"}`; ranked results carry none. Slots need `user_id` and are skipped with `memory_id` or when `top_k` would leave no ranked result. The preference slot applies only when facts are searched, and `procedure_slot` has no effect when only procedural types are searched. Episodes never take a slot, and summaries and turns blended in with `include_summaries` / `include_turns` still follow the `top_k` results. @@ -98,11 +98,11 @@ Local-buffer methods remain synchronous in-memory operations; Cosmos, retrieval, ### Connection -- `__init__(cosmos_endpoint=None, cosmos_credential=None, cosmos_key=None, cosmos_database=None, cosmos_container=None, cosmos_turns_container='memories_turns', cosmos_summaries_container='memories_summaries', cosmos_counter_container=None, cosmos_lease_container=None, cosmos_throughput_mode=None, cosmos_autoscale_max_ru=None, ai_foundry_endpoint=None, ai_foundry_credential=None, ai_foundry_api_key=None, embedding_deployment_name='text-embedding-3-large', embedding_dimensions=None, chat_deployment_name='gpt-4o-mini', use_default_credential=True, enable_turn_embeddings=None, user_agent=None, embeddings_client=None, chat_client=None, processor=None, transcript_metadata_keys=None, cadence_thresholds=None, cosmos_preferred_locations=None, tenant_id=None) -> None` - configure async local state, model clients, and optional processing backend; it does not connect to Cosmos, so await `connect_cosmos()` or `create_memory_store()`. The async SDK uses the same hard 3-container topology as the sync client. `enable_turn_embeddings` (default `False`, env `ENABLE_TURN_EMBEDDINGS`) embeds raw turns on write so they can be vector-searched via `search_turns()`. `cosmos_preferred_locations` (a list or a comma-separated string, env `COSMOS_DB_PREFERRED_REGIONS`) orders the Cosmos DB regions the client reads from, closest first; unset keeps the account's default order. `tenant_id` binds the client to one tenant and works as in the sync client. +- `__init__(cosmos_endpoint=None, cosmos_credential=None, cosmos_key=None, cosmos_database=None, cosmos_container=None, cosmos_turns_container='memories_turns', cosmos_summaries_container='memories_summaries', cosmos_counter_container=None, cosmos_lease_container=None, cosmos_throughput_mode=None, cosmos_autoscale_max_ru=None, ai_foundry_endpoint=None, ai_foundry_credential=None, ai_foundry_api_key=None, embedding_deployment_name='text-embedding-3-large', embedding_dimensions=None, chat_deployment_name='gpt-4o-mini', use_default_credential=True, enable_turn_embeddings=None, user_agent=None, embeddings_client=None, chat_client=None, processor=None, transcript_metadata_keys=None, cadence_thresholds=None, cosmos_preferred_locations=None, tenant_id=None) -> None` - configure async local state, model clients, and optional processing backend; it does not connect to Cosmos, so await `connect_cosmos()` or `create_memory_store()`. The async SDK uses the same hard 3-container topology as the sync client. `enable_turn_embeddings` (default `False`, env `ENABLE_TURN_EMBEDDINGS`) embeds raw turns on write so they can be vector-searched via `search_turns()`. `cosmos_preferred_locations` (a list or a comma-separated string, env `COSMOS_DB_PREFERRED_REGIONS`) orders the Cosmos DB regions the client reads from, closest first; unset keeps the account's default order. `tenant_id` binds the client to one tenant and works as in the sync client, including the `ConfigurationError` for a `processor` that works in another tenant. - `async close() -> None` - cancel any pending background processing tasks, then close async/sync resources and owned credentials. -- `async connect_cosmos(endpoint=None, credential=None, key=None, database=None, container=None, turns_container=None, summaries_container=None) -> None` - connect to existing memory, turns, and summaries containers. -- `async create_memory_store(database=None, container=None, turns_container=None, summaries_container=None, counter_container=None, lease_container=None, endpoint=None, credential=None, key=None, embedding_dimensions=None, embedding_data_type=None, distance_function=None, full_text_language=None, throughput_mode=None, autoscale_max_ru=None, vector_index_type=None) -> None` - create/connect memory, turns, summaries, counter, and lease containers; `vector_index_type` and the partition key work as in the sync method. -- `async validate_topology() -> None` - read metadata for the memories, turns, summaries and counter containers and raise `RuntimeError` if any is missing, unreachable, or not keyed `[/tenant_id, /user_id]`; call after connecting to catch infrastructure/config drift before writes. +- `async connect_cosmos(endpoint=None, credential=None, key=None, database=None, container=None, turns_container=None, summaries_container=None) -> None` - connect to existing memory, turns, and summaries containers and check `memories`, `memories_turns`, `memories_summaries` and `counter` as the sync method does: `CosmosOperationError`, naming the container, if one is missing or not keyed `[/tenant_id, /user_id]`. +- `async create_memory_store(database=None, container=None, turns_container=None, summaries_container=None, counter_container=None, lease_container=None, endpoint=None, credential=None, key=None, embedding_dimensions=None, embedding_data_type=None, distance_function=None, full_text_language=None, throughput_mode=None, autoscale_max_ru=None, vector_index_type=None) -> None` - create/connect memory, turns, summaries, counter, and lease containers; `vector_index_type`, the partition key and the key check work as in the sync method. +- `async validate_topology() -> None` - the explicit diagnostic, as in the sync method: read metadata for the memories, turns, summaries and counter containers and raise `RuntimeError` if any is missing, unreachable, or not keyed `[/tenant_id, /user_id]`. ### Memory CRUD @@ -201,12 +201,14 @@ Credentials without a fixed format, such as `password: hunter2` typed into a cha ## Topology validation -Use `validate_topology()` (sync) or `await validate_topology()` (async) after `connect_cosmos()` or `create_memory_store()` to verify that `memories`, `memories_turns`, `memories_summaries` and `counter` all exist, are readable, and are keyed `[/tenant_id, /user_id]`. The method raises `RuntimeError` on the first container that is missing (the message says to redeploy), unreadable, or keyed otherwise (the message says to recreate it, because a partition key cannot change in place). `create_memory_store()` makes the same key check itself, so the client constructor fails at once on a container created with the earlier `[/user_id, /thread_id]` key; `connect_cosmos()` does not, so call `validate_topology()` after it. +`connect_cosmos()` reads the metadata of `memories`, `memories_turns`, `memories_summaries` and `counter` (four reads) and raises `CosmosOperationError`, naming the container, when one is missing or not keyed `[/tenant_id, /user_id]`; the client is closed again on failure. `create_memory_store()` makes the same check after it has created what is missing. The sync client's constructor calls `create_memory_store()` when it is given an endpoint, so it fails at once on a container created with the earlier `[/user_id, /thread_id]` key. The async constructor does no I/O, so connect an async client with `await client.connect_cosmos()` or `await client.create_memory_store()`. + +`validate_topology()` (sync) or `await validate_topology()` (async) remains the explicit diagnostic: it verifies that `memories`, `memories_turns`, `memories_summaries` and `counter` all exist, are readable, and are keyed `[/tenant_id, /user_id]`. The method raises `RuntimeError` on the first container that is missing (the message says to redeploy), unreadable, or keyed otherwise (the message says to recreate it, because a partition key cannot change in place). ## Extension Points - `MemoryStoreProtocol` (`azure.cosmos.agent_memory.services`): persistence primitives (`query`, `read_item`, `upsert_memory`, `mark_superseded`) consumed by `PipelineService`. `AsyncPipelineService` takes an `AsyncMemoryStore`; there is no async protocol. -- `MemoryProcessor` (`azure.cosmos.agent_memory.processors`) and `AsyncMemoryProcessor` (`azure.cosmos.agent_memory.aio.processors`): the processing backend behind the `processor` argument, with `process_thread`, `process_extract_memories`, `process_extract_episodes`, `process_thread_summary`, `process_user_summary`, `process_reconcile`, `generate_user_summary`, `synthesize_procedural` and `close`. `InProcessProcessor` / `AsyncInProcessProcessor` run the pipeline in your process; `DurableFunctionProcessor` / `AsyncDurableFunctionProcessor` leave it to the Function App, so their methods are no-ops. +- `MemoryProcessor` (`azure.cosmos.agent_memory.processors`) and `AsyncMemoryProcessor` (`azure.cosmos.agent_memory.aio.processors`): the processing backend behind the `processor` argument, with `process_thread`, `process_extract_memories`, `process_extract_episodes`, `process_thread_summary`, `process_user_summary`, `process_reconcile`, `generate_user_summary`, `synthesize_procedural` and `close`. `InProcessProcessor` / `AsyncInProcessProcessor` run the pipeline in your process; `DurableFunctionProcessor` / `AsyncDurableFunctionProcessor` leave it to the Function App, so their methods are no-ops. An in-process processor works in one tenant and exposes it as a read-only `tenant_id`; a client raises `ConfigurationError` when its `processor` works in another tenant than its own `tenant_id`, so build the processor with the same `tenant_id`, or omit `processor` so the client builds its own. Concrete service classes: @@ -214,4 +216,4 @@ Concrete service classes: - Async: `AsyncPipelineService` from `azure.cosmos.agent_memory.aio.services` (sub-module `pipeline`). The async pipeline is a fully-native asyncio implementation - not an `asyncio.to_thread` shim over the sync pipeline. - Threshold-driven auto-trigger: `maybe_trigger_steps` from `azure.cosmos.agent_memory.auto_trigger` (sync) and `azure.cosmos.agent_memory.aio.auto_trigger` (async). -`MemoryStore`, `AsyncMemoryStore`, `PipelineService` and `AsyncPipelineService` take the same `tenant_id` argument as the clients (default `"default"`). A store stamps it on every record it writes and refuses a record that names another tenant; a pipeline keys its own reads and writes with it. Give a store and the pipeline that uses it the same value. +`MemoryStore`, `AsyncMemoryStore`, `PipelineService` and `AsyncPipelineService` take the same `tenant_id` argument as the clients (default `"default"`). A store stamps it on every record it writes and refuses a record that names another tenant; a pipeline keys its own reads and writes with it. Give a store and the pipeline that uses it the same value. A `MemoryRecord` you build yourself has `tenant_id=None` until it is written: the client or store stamps its own tenant then, and a record that names a different tenant is still refused. diff --git a/Docs/troubleshooting.md b/Docs/troubleshooting.md index dab451f..a545a68 100644 --- a/Docs/troubleshooting.md +++ b/Docs/troubleshooting.md @@ -14,6 +14,7 @@ Use this guide when local memory works but Cosmos DB, embeddings, Durable Functi | Cosmos operations fail before connecting | Call `create_memory_store()` or `connect_cosmos()` before cloud operations. | | Search returns no vector results | Confirm embeddings are generated and `AI_FOUNDRY_EMBEDDING_DIMENSIONS` matches the container vector policy. | | A client does not find memories another client wrote | A client reads and writes only its own tenant. Check that both use the same `tenant_id` (default `"default"`). See section 3. | +| `connect_cosmos()` or `create_memory_store()` raises `CosmosOperationError` naming a container | The container is missing or not keyed `[/tenant_id, /user_id]`. A container with the earlier `[/user_id, /thread_id]` key must be recreated, `leases` included. See section 3. | | Reads, updates and deletes find nothing after upgrading | The containers were created with the earlier `[/user_id, /thread_id]` key and must be recreated, `leases` included. See section 3. | | A fact, procedure or preference is missing from search results | It may be retired (`superseded_by` is set; pass `include_superseded=True`) or, for a procedure, still a `candidate` or past `valid_until`. See section 4. | | Conflicting facts show no `conflicts_with` | Search with `user_id` after a reconcile pass has run; only pairs that pass compared are linked. See section 4. | @@ -107,7 +108,9 @@ The memories container is created with: A client is bound to one tenant (`tenant_id`, default `"default"`) and reads and writes only inside it, so memories written under another tenant are not visible to it. `client.tenant_id` shows the value in use. -A container's partition key is fixed when it is created, and `create_memory_store()` leaves an existing container as it is, but it refuses one that is not keyed `[/tenant_id, /user_id]` with `container 'memories' has partition key ['/user_id', '/thread_id'] but this SDK requires ['/tenant_id', '/user_id']`. Containers created by an earlier version are keyed `[/user_id, /thread_id]`: they take writes, but the current client's reads, updates and deletes by owner do not find the records. Delete and recreate `memories`, `memories_turns`, `memories_summaries`, `counter` and `leases`, so the change feed starts clean on the recreated turns container (`create_memory_store()` creates them, the first four with the new key); existing data is not migrated. After `connect_cosmos()`, which does not check, `validate_topology()` makes the same check. +`create_memory_store()` leaves an existing container as it is, but, like `connect_cosmos()`, it refuses one that is not keyed `[/tenant_id, /user_id]`; `connect_cosmos()` also refuses a missing `memories`, `memories_turns`, `memories_summaries` or `counter` container (four metadata reads). Both raise `CosmosOperationError` whose message names the container, for example `container 'memories' has partition key ['/user_id', '/thread_id'] but this SDK requires ['/tenant_id', '/user_id']`. The sync client's constructor calls `create_memory_store()` when it is given an endpoint; the async constructor does no I/O, so an async app sees these errors at `await client.connect_cosmos()` or `await client.create_memory_store()`. `validate_topology()` remains the explicit diagnostic. + +A container's partition key is fixed when it is created. Containers created by an earlier version are keyed `[/user_id, /thread_id]`: they take writes, but the current client's reads, updates and deletes by owner do not find the records, so they must be recreated, `leases` with them, and existing data is not migrated. The README's [migration notes](../README.md#migration-notes) give the steps in order. If vector or full-text search fails after changing dimensions or indexing settings, create a fresh container with the desired configuration. Cosmos container vector policies are creation-time infrastructure choices. @@ -128,7 +131,7 @@ Search always uses hybrid vector/full-text ranking when keyword extraction finds If search returns documents but scores look poor, check that records have an `embedding` field and that the query uses similar language to the stored memory content. -Keyword searches read across partitions. The Python SDK skips query planning for a query sent with a partition key, so `FullTextScore` ranking is ignored ([Azure/azure-sdk-for-python#42241](https://github.com/Azure/azure-sdk-for-python/issues/42241)); a keyword query therefore filters on `c.tenant_id`, `c.user_id` (and `c.thread_id`, when given) in the `WHERE` clause instead and sets `full_text_score_scope="Local"`. Results stay confined to the client's tenant and the same owner (in `search_cosmos`, episodic and procedural memories match on the owner alone), but a large container costs more RUs than a single-partition read. A vector-only query with a `user_id` still reads one partition, whatever the `thread_id`. If a custom query sent with a partition key raises a `ValidationError` that mentions `FullTextScore`, drop the partition key and filter on `c.tenant_id` and `c.user_id` in the `WHERE` clause. +Keyword searches read across partitions. The Python SDK skips query planning for a query sent with a partition key, so `FullTextScore` ranking is ignored ([Azure/azure-sdk-for-python#42241](https://github.com/Azure/azure-sdk-for-python/issues/42241); see also [#49289](https://github.com/Azure/azure-sdk-for-python/pull/49289)); a keyword query therefore filters on `c.tenant_id`, `c.user_id` (and `c.thread_id`, when given) in the `WHERE` clause instead and sets `full_text_score_scope="Local"`. Results stay confined to the client's tenant and the same owner (in `search_cosmos`, episodic and procedural memories match on the owner alone), but a large container costs more RUs than a single-partition read. A vector-only query with a `user_id` still reads one partition, whatever the `thread_id`. If a custom query sent with a partition key raises a `ValidationError` that mentions `FullTextScore`, drop the partition key and filter on `c.tenant_id` and `c.user_id` in the `WHERE` clause. Search hides some records on purpose: @@ -205,10 +208,11 @@ If nothing fires: - verify the Functions host shows the Cosmos DB trigger - confirm the `leases` container exists -- confirm the `memories`, `memories_turns` and `memories_summaries` containers exist; a missing one fails the batch with `Topology error: container '' does not exist` +- confirm the `memories`, `memories_turns`, `memories_summaries` and `counter` containers exist and are keyed `[/tenant_id, /user_id]`: the Function App checks them on its first change-feed batch, and a missing or wrongly keyed one fails the batch with a `Topology error` that names the container (for example `Topology error: container '' does not exist`) - confirm the `counter` container is writable - confirm `MEMORY_PROCESSOR_OWNER=durable` is set on the Function App -- check the Function App log for warnings about skipped turns: a turn needs a valid `tenant_id`, which the SDK stamps on every record it writes, and the trigger skips one without it +- check the Function App log for warnings about skipped turns: a turn needs a valid `tenant_id`, `user_id` and `thread_id` (the SDK stamps the tenant on every record it writes and refuses an invalid owner or thread id), and the trigger skips one that lacks them +- if only some threads or owners fire: a failure while counting or starting orchestrations for one thread or owner does not stop the rest of the batch (every other tenant's counters are still updated), but the batch still fails at the end so the host records it - insert enough new turn documents to cross the configured threshold - check for generated documents where the Cosmos JSON field is `type="thread_summary"`, `type="fact"`, or `type="user_summary"` diff --git a/README.md b/README.md index f85e83e..99be4c0 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ memory = CosmosMemoryClient( use_default_credential=True, # processor=InProcessProcessor() # implicit default ) -memory.connect_cosmos() # connects to existing containers; create_memory_store() creates them if missing +memory.connect_cosmos() # checks the containers; create_memory_store() creates any that are missing USER, THREAD = "user-001", str(uuid.uuid4()) @@ -113,6 +113,7 @@ print(memory.get_user_summary(user_id=USER)) > ```python > from azure.cosmos.agent_memory.aio import AsyncCosmosMemoryClient > ``` +> The async constructor does no I/O, so connect with `await memory.connect_cosmos()` or `await memory.create_memory_store()`. The sync constructor already calls `create_memory_store()` when it is given an endpoint. ### 4. Run a sample @@ -147,7 +148,7 @@ AgentMemoryToolkit uses 3-container Cosmos topology, all partitioned by the hier | `memories` | `fact`, `episodic`, `procedural` documents | vector + full-text retrieval path | | `memories_summaries` | thread and user summaries | latest-summary point reads; vector + full-text for `search_summaries` | -`tenant_id` says whose memories these are (an app, a customer, an environment); a client is bound to one tenant through its `tenant_id` argument, `"default"` unless you set it. `user_id` is the owner of a memory, a user or an agent. `thread_id` is a plain field, so everything one owner knows sits in one partition. See [Tenants and Owners](Docs/concepts.md#tenants-and-owners). +`tenant_id` says whose memories these are (an app, a customer, an environment); a client is bound to one tenant through its `tenant_id` argument, `"default"` unless you set it. It keeps data apart inside the same containers but is not an access-control boundary: anyone who can read the account's data can read every tenant, so use separate databases or accounts and Azure RBAC for hard isolation. `user_id` is the owner of a memory, a user or an agent. `thread_id` is a plain field, so everything one owner knows sits in one partition. See [Tenants and Owners](Docs/concepts.md#tenants-and-owners). `create_memory_store()` also creates a `counter` container (the turn counters behind the auto-trigger, with the same key) and a `leases` container (change feed checkpoints, keyed `/id`). @@ -306,6 +307,8 @@ memory = CosmosMemoryClient(..., processor=DurableFunctionProcessor()) `DurableFunctionProcessor` is a thin marker - there is no SDK→Function HTTP call. The SDK just writes turns; the deployed Function app picks them up via the Cosmos change feed. Counter-based trigger configuration and Bicep module reference live in [`infra/README.md`](infra/README.md). +An `InProcessProcessor` (or `AsyncInProcessProcessor`) you build yourself works in one tenant and exposes it as a read-only `tenant_id`. A client raises `ConfigurationError` when its `processor` works in another tenant than the client's own `tenant_id`: build the processor with the same `tenant_id`, or omit `processor` so the client builds its own. + --- ### Architecture overview @@ -383,7 +386,15 @@ tests/ Unit + integration tests (pytest) ## Migration notes -- **Memories are keyed `[tenant_id, user_id]`, with no migration.** `memories`, `memories_turns`, `memories_summaries` and `counter` were keyed `[user_id, thread_id]`. A partition key cannot change in place, so recreate those containers and `leases`, so the change feed starts clean on the recreated turns container (`create_memory_store()` creates them with the new key, and for `azd` deployments see [`infra/README.md`](infra/README.md)). Existing data is not migrated, and `create_memory_store()` refuses a container that still has the earlier key rather than let it take writes and read back empty. A `user_id` must now be a non-empty string of at most 256 UTF-8 bytes without `/`, `\`, `?`, `#` or control characters. `thread_id` is no longer an argument of `update_cosmos()`, `delete_memory()`, `delete_turn()`, `add_tags()`, `remove_tags()` and `get_memory_history()`, and `MemoryNotFoundError` no longer carries it. Clients take an optional `tenant_id` (default `"default"`). See [CHANGELOG.md](CHANGELOG.md). +- **Memories are keyed `[tenant_id, user_id]`, with no migration.** `memories`, `memories_turns`, `memories_summaries` and `counter` were keyed `[user_id, thread_id]`. A partition key cannot change in place and existing data is not migrated, so upgrade in this order: + 1. Stop every writer: all apps that use the SDK, and the Function App. + 2. Recreate `memories`, `memories_turns`, `memories_summaries` and `counter` with the key `[/tenant_id, /user_id]`, and `leases` too, so the change feed starts clean on the recreated turns container. `create_memory_store()` and the Bicep template create new containers with the new key; for `azd` deployments see [`infra/README.md`](infra/README.md). + 3. Terminate and purge the in-flight Durable Functions orchestrations: instances started before the upgrade carry no tenant and fail. + 4. Deploy the new Function App before the upgraded writers start. Its change feed trigger reads only the turns written after it first starts on a fresh `leases` container, so turns written earlier are never counted. + 5. Upgrade and restart all writers together: a writer still on the old version keeps writing the old shape. +- **Containers are checked when you connect.** `connect_cosmos()` raises `CosmosOperationError`, naming the container, when `memories`, `memories_turns`, `memories_summaries` or `counter` is missing or not keyed `[/tenant_id, /user_id]`; `create_memory_store()` creates what is missing and then makes the same check. A container still keyed `[/user_id, /thread_id]` would take writes and read back empty, so it is refused. `validate_topology()` remains the explicit check. +- **Identifiers are validated.** A `tenant_id`, a `user_id` and a `thread_id` must each be a non-empty string of at most 256 UTF-8 bytes that does not start or end with whitespace and has no `/`, `\`, `?`, `#` or control characters, because they appear in document ids and Cosmos DB refuses an id that ends in whitespace. Anything else raises `ValidationError` when the client writes it. +- **`thread_id` is no longer needed to find a record.** It is no longer an argument of `update_cosmos()`, `delete_memory()`, `delete_turn()`, `add_tags()`, `remove_tags()` and `get_memory_history()`, and `MemoryNotFoundError` no longer carries it. Clients take an optional `tenant_id` (default `"default"`). See [CHANGELOG.md](CHANGELOG.md). - **`azure.cosmos.agent_memory.processing.ProcessingClient` is removed.** Drop the import and call `client.process_now()` (or `client.process_now_and_wait()`) instead. Same for the async `AsyncProcessingClient`. - **New `processor=` kwarg.** Defaults to `InProcessProcessor()` - existing code keeps its current behavior with no edits. - **`adf_endpoint` / `adf_key` constructor kwargs are gone.** The SDK no longer makes HTTP calls to the Function app at runtime; the Function app reads from the Cosmos change feed. diff --git a/azure/cosmos/agent_memory/_base/base_client.py b/azure/cosmos/agent_memory/_base/base_client.py index c7a2123..fb3c9b5 100644 --- a/azure/cosmos/agent_memory/_base/base_client.py +++ b/azure/cosmos/agent_memory/_base/base_client.py @@ -20,7 +20,12 @@ normalize_ai_foundry_endpoint, resolve_cosmos_preferred_locations, ) -from azure.cosmos.agent_memory.exceptions import CosmosNotConnectedError, MemoryNotFoundError, ValidationError +from azure.cosmos.agent_memory.exceptions import ( + ConfigurationError, + CosmosNotConnectedError, + MemoryNotFoundError, + ValidationError, +) from azure.cosmos.agent_memory.logging import configure_logging, get_logger from azure.cosmos.agent_memory.thresholds import get_enable_turn_embeddings @@ -125,6 +130,19 @@ def tenant_id(self) -> str: """The tenant this client is bound to: every record it reads or writes belongs to it.""" return self._tenant_id + def _require_processor_tenant(self, processor: Any) -> None: + """Refuse a processor that works in another tenant than this client. + + A processor that reports no tenant, as a custom one may not, is not checked. + """ + processor_tenant = getattr(processor, "tenant_id", None) + if isinstance(processor_tenant, str) and processor_tenant != self._tenant_id: + raise ConfigurationError( + f"processor works in tenant {processor_tenant!r} but this client is bound to tenant " + f"{self._tenant_id!r}: build the processor with the same tenant_id, or omit it so the client " + "builds its own" + ) + @property def _containers(self) -> dict[ContainerKey, Any]: return { diff --git a/azure/cosmos/agent_memory/_partitioning.py b/azure/cosmos/agent_memory/_partitioning.py index 0873546..5f0eccf 100644 --- a/azure/cosmos/agent_memory/_partitioning.py +++ b/azure/cosmos/agent_memory/_partitioning.py @@ -14,6 +14,7 @@ from __future__ import annotations +import unicodedata from typing import Any, Mapping, Optional from azure.cosmos.agent_memory.exceptions import ValidationError @@ -23,10 +24,13 @@ # The partition key every keyed container is created with, and the one :func:`partition_key_problem` expects. PARTITION_KEY_PATHS = ["/tenant_id", "/user_id"] -# Ids appear in Cosmos document ids and orchestration instance ids, which cannot hold these characters. +# Ids appear in Cosmos document ids, which cannot hold these characters or end in whitespace. _UNSUPPORTED_CHARACTERS = "/\\?#" +# Control characters (C0, DEL and C1) and the line and paragraph separators. +_REFUSED_CATEGORIES = frozenset({"Cc", "Zl", "Zp"}) MAX_TENANT_ID_BYTES = 256 MAX_OWNER_ID_BYTES = 256 +MAX_THREAD_ID_BYTES = 256 TENANT_FILTER = "c.tenant_id = @tenant_id" OWNER_FILTER = "c.tenant_id = @tenant_id AND c.user_id = @user_id" @@ -35,8 +39,10 @@ def _checked_identifier(value: Any, name: str, max_bytes: int) -> str: if not isinstance(value, str) or not value.strip(): raise ValidationError(f"{name} must be a non-empty string") + if value != value.strip(): + raise ValidationError(f"{name} must not start or end with whitespace") if any(character in value for character in _UNSUPPORTED_CHARACTERS) or any( - ord(character) < 32 for character in value + unicodedata.category(character) in _REFUSED_CATEGORIES for character in value ): raise ValidationError(f"{name} contains characters the memory store does not support: / \\ ? # or control") if len(value.encode("utf-8")) > max_bytes: @@ -47,8 +53,9 @@ def _checked_identifier(value: Any, name: str, max_bytes: int) -> str: def resolve_tenant_id(tenant_id: Optional[str] = None) -> str: """The tenant to use: ``DEFAULT_TENANT_ID`` when ``tenant_id`` is ``None``, else ``tenant_id`` if it is valid. - A valid tenant id is a non-empty string of at most ``MAX_TENANT_ID_BYTES`` UTF-8 bytes without ``/``, ``\\``, ``?``, - ``#`` or control characters. Anything else raises :class:`ValidationError`. + A valid tenant id is a non-empty string of at most ``MAX_TENANT_ID_BYTES`` UTF-8 bytes that does not start or end + with whitespace and has no ``/``, ``\\``, ``?``, ``#`` or control characters. Anything else raises + :class:`ValidationError`. """ if tenant_id is None: return DEFAULT_TENANT_ID @@ -59,13 +66,22 @@ def validate_owner_id(user_id: Any) -> str: """``user_id`` if it is a valid owner id, else :class:`ValidationError`. An owner id follows the rules of a tenant id: a non-empty string of at most ``MAX_OWNER_ID_BYTES`` UTF-8 bytes - without ``/``, ``\\``, ``?``, ``#`` or control characters. It is part of the partition key and of the ids of the - records the toolkit builds for the owner, so a value outside the rules would fail later or share a partition by - accident. + that does not start or end with whitespace and has no ``/``, ``\\``, ``?``, ``#`` or control characters. It is + part of the partition key and of the ids of the records the toolkit builds for the owner, so a value outside the + rules would fail later or share a partition by accident. """ return _checked_identifier(user_id, "user_id", MAX_OWNER_ID_BYTES) +def validate_thread_id(thread_id: Any) -> str: + """``thread_id`` if it is a valid thread id, else :class:`ValidationError`. + + A thread id follows the rules of an owner id. It is not part of the partition key, but it is part of the ids of + the counters and summaries built for the thread, and Cosmos DB refuses a document id that ends in whitespace. + """ + return _checked_identifier(thread_id, "thread_id", MAX_THREAD_ID_BYTES) + + def partition_key_for(tenant_id: str, user_id: str) -> list[str]: """The full partition key of the records of ``user_id`` in ``tenant_id``.""" return [tenant_id, validate_owner_id(user_id)] @@ -82,12 +98,15 @@ def owner_parameters(tenant_id: str, user_id: str) -> list[dict[str, Any]]: def stamp_scope(doc: Mapping[str, Any], tenant_id: str) -> dict[str, Any]: - """A copy of ``doc`` that carries ``tenant_id``, refusing a record that has no valid owner or names another tenant. + """A copy of ``doc`` that carries ``tenant_id``, refusing a record that has no valid owner, has a ``thread_id`` + that is not valid, or names another tenant. A client writes only into its own tenant. Cosmos stores a record in the partition its own ``tenant_id`` and ``user_id`` name, so a record without a valid ``user_id`` would land where no owner-scoped read reaches it. """ validate_owner_id(doc.get("user_id")) + if doc.get("thread_id") is not None: + validate_thread_id(doc["thread_id"]) named = doc.get("tenant_id") if named is not None and named != tenant_id: raise ValidationError("record names a different tenant than the client it is written with") diff --git a/azure/cosmos/agent_memory/aio/cosmos_memory_client.py b/azure/cosmos/agent_memory/aio/cosmos_memory_client.py index 7ea6e9e..d8daf88 100644 --- a/azure/cosmos/agent_memory/aio/cosmos_memory_client.py +++ b/azure/cosmos/agent_memory/aio/cosmos_memory_client.py @@ -118,6 +118,8 @@ def __init__( cosmos_preferred_locations=cosmos_preferred_locations, tenant_id=tenant_id, ) + if processor is not None: + self._require_processor_tenant(processor) self._background_tasks: set[asyncio.Task[Any]] = set() self._pipeline_init_error: Exception | None = None # Embeddings/chat clients may be injected (e.g. an OpenAI-compatible backend, a @@ -223,7 +225,9 @@ async def connect_cosmos( """Establish an async connection to the Cosmos DB memory containers. If container overrides are provided, they override the constructor's - settings for this connection. + settings for this connection. The memories, turns, summaries and counter containers must exist and + be keyed ``[/tenant_id, /user_id]``; otherwise this raises :class:`CosmosOperationError` and closes the + connection, because a container keyed otherwise takes writes but is read back empty. """ self._cosmos_endpoint = endpoint or self._cosmos_endpoint if credential is not None: @@ -268,8 +272,11 @@ async def connect_cosmos( self._cosmos_database, self._cosmos_summaries_container, ) + await self._require_keyed_containers() self._init_services() except Exception as exc: + # The connection cannot be used: close the client just opened and forget its containers. + await self._drain_cosmos_client() raise CosmosOperationError(f"Failed to connect to Cosmos DB (async): {exc}") from exc logger.info("Async connected to Cosmos DB %s/%s", self._cosmos_database, self._cosmos_container) @@ -432,13 +439,7 @@ async def create_memory_store( self._init_services() except Exception as exc: # The store cannot be used: close the client just opened and forget its containers. - try: - await self._drain_cosmos_client() - except Exception as close_exc: # noqa: BLE001 - logger.warning( - "Failed to close the Cosmos client after create_memory_store failed: %s", - describe_exception(close_exc), - ) + await self._drain_cosmos_client() raise CosmosOperationError(f"Failed to create memory store (async): {exc}") from exc logger.info("Async created memory store %s/%s", self._cosmos_database, self._cosmos_container) @@ -485,6 +486,25 @@ async def _require_partition_key(container: Any) -> None: if problem: raise ConfigurationError(problem) + async def _require_keyed_containers(self) -> None: + """Refuse a connected container that is missing or not keyed ``[/tenant_id, /user_id]``. + + A container keyed otherwise takes writes but is read back empty, so it is caught here instead of later. + """ + from azure.cosmos.exceptions import CosmosResourceNotFoundError + + counter_container = self._get_counter_container() + for container in (*self._containers.values(), counter_container): + if container is None: + continue + try: + await self._require_partition_key(container) + except CosmosResourceNotFoundError as exc: + raise ConfigurationError( + f"container {getattr(container, 'id', None)!r} does not exist: run create_memory_store() or " + "deploy the infrastructure (azd up), and make sure the SDK settings name the same containers" + ) from exc + def _build_store(self) -> AsyncMemoryStore: return AsyncMemoryStore( containers=self._containers, @@ -537,7 +557,12 @@ async def _drain_cosmos_client(self) -> None: if prior is not None: close = getattr(prior, "close", None) if callable(close): - await close() + try: + await close() + except Exception as exc: + logger.warning( + "Failed to close prior Cosmos client during reconnect: %s", describe_exception(exc, stack=True) + ) self._cosmos_client = None self._memories_container_client = None self._turns_container_client = None diff --git a/azure/cosmos/agent_memory/aio/processors/inprocess.py b/azure/cosmos/agent_memory/aio/processors/inprocess.py index 2fc36c6..57267ad 100644 --- a/azure/cosmos/agent_memory/aio/processors/inprocess.py +++ b/azure/cosmos/agent_memory/aio/processors/inprocess.py @@ -21,7 +21,8 @@ class AsyncInProcessProcessor: """Async in-process orchestrator over :class:`AsyncPipelineService`. Wraps an existing pipeline, or builds one from the supplied container / LLM / embeddings clients, - bound to ``tenant_id`` (``"default"`` when not given). + bound to ``tenant_id`` (``"default"`` when not given). A ``pipeline`` you pass keeps its own tenant, which + :attr:`tenant_id` reports and ``tenant_id=`` does not change; a client built with another tenant refuses it. """ def __init__( @@ -64,6 +65,11 @@ def __init__( self._pipeline = pipeline + @property + def tenant_id(self) -> Optional[str]: + """The tenant of the pipeline this processor runs, or ``None`` when that pipeline reports none.""" + return getattr(self._pipeline, "tenant_id", None) + async def process_thread( self, *, diff --git a/azure/cosmos/agent_memory/aio/services/pipeline.py b/azure/cosmos/agent_memory/aio/services/pipeline.py index f89b8ae..5f55f56 100644 --- a/azure/cosmos/agent_memory/aio/services/pipeline.py +++ b/azure/cosmos/agent_memory/aio/services/pipeline.py @@ -345,6 +345,11 @@ def __init__( self._prompty = PromptyLoader(prompts_dir) self._transcript_metadata_keys: Optional[tuple[str, ...]] = _normalize_metadata_keys(transcript_metadata_keys) + @property + def tenant_id(self) -> str: + """The tenant this service reads and writes.""" + return self._tenant_id + async def _query_items(self, container: Any, **kwargs: Any) -> list[dict[str, Any]]: result = container.query_items(**kwargs) if inspect.isawaitable(result): @@ -1824,10 +1829,8 @@ async def persist_thread_summary( if not isinstance(summary_doc, dict): raise ValidationError("summary_doc must be a dict") - doc = stamp_scope(summary_doc, self._tenant_id) + doc = stamp_scope({**summary_doc, "user_id": user_id, "thread_id": thread_id}, self._tenant_id) doc["id"] = doc.get("id") or f"summary_{user_id}_{thread_id}" - doc["user_id"] = user_id - doc["thread_id"] = thread_id doc.setdefault("prompt_id", "summarize.prompty") doc.setdefault("prompt_version", "v1") self._redact_for_embedding(doc) @@ -1985,10 +1988,8 @@ async def persist_user_summary( if not isinstance(user_summary_doc, dict): raise ValidationError("user_summary_doc must be a dict") - doc = stamp_scope(user_summary_doc, self._tenant_id) + doc = stamp_scope({**user_summary_doc, "user_id": user_id, "thread_id": "__user_summary__"}, self._tenant_id) doc["id"] = doc.get("id") or f"user_summary_{user_id}" - doc["user_id"] = user_id - doc["thread_id"] = "__user_summary__" doc.setdefault("prompt_id", "user_summary.prompty") doc.setdefault("prompt_version", "v1") structured_summary = doc.get("metadata", {}).get("structured_summary") diff --git a/azure/cosmos/agent_memory/aio/store/memory_store.py b/azure/cosmos/agent_memory/aio/store/memory_store.py index 2276c27..2277054 100644 --- a/azure/cosmos/agent_memory/aio/store/memory_store.py +++ b/azure/cosmos/agent_memory/aio/store/memory_store.py @@ -28,6 +28,7 @@ resolve_tenant_id, stamp_scope, validate_owner_id, + validate_thread_id, ) from azure.cosmos.agent_memory._query_builder import _QueryBuilder from azure.cosmos.agent_memory._utils import ( @@ -308,6 +309,8 @@ async def add( text that held a credential. """ validate_owner_id(user_id) + if thread_id is not None: + validate_thread_id(thread_id) content, secret_patterns = sanitize_text(content) kwargs: dict[str, Any] = { "tenant_id": self._tenant_id, diff --git a/azure/cosmos/agent_memory/cosmos_memory_client.py b/azure/cosmos/agent_memory/cosmos_memory_client.py index c14ade4..ad88a3a 100644 --- a/azure/cosmos/agent_memory/cosmos_memory_client.py +++ b/azure/cosmos/agent_memory/cosmos_memory_client.py @@ -104,6 +104,8 @@ def __init__( cosmos_preferred_locations=cosmos_preferred_locations, tenant_id=tenant_id, ) + if processor is not None: + self._require_processor_tenant(processor) # Embeddings/chat clients may be injected (e.g. an OpenAI-compatible backend, a # caller-configured client, or a deterministic fake for offline tests). When a client # is injected the caller owns its lifecycle, so the toolkit does not close it; otherwise @@ -191,7 +193,9 @@ def connect_cosmos( """Establish a connection to the Cosmos DB memory containers. If container overrides are provided, they override the constructor's - settings for this connection. + settings for this connection. The memories, turns, summaries and counter containers must exist and + be keyed ``[/tenant_id, /user_id]``; otherwise this raises :class:`CosmosOperationError` and closes the + connection, because a container keyed otherwise takes writes but is read back empty. """ self._cosmos_endpoint = endpoint or self._cosmos_endpoint if credential is not None: @@ -232,8 +236,11 @@ def connect_cosmos( self._cosmos_database, self._cosmos_summaries_container, ) + self._require_keyed_containers() self._init_services() except Exception as exc: + # The connection cannot be used: close the client just opened and forget its containers. + self._drain_cosmos_client() raise CosmosOperationError(f"Failed to connect to Cosmos DB: {exc}") from exc logger.info("Connected to Cosmos DB %s/%s", self._cosmos_database, self._cosmos_container) @@ -445,6 +452,25 @@ def _require_partition_key(container: Any) -> None: if problem: raise ConfigurationError(problem) + def _require_keyed_containers(self) -> None: + """Refuse a connected container that is missing or not keyed ``[/tenant_id, /user_id]``. + + A container keyed otherwise takes writes but is read back empty, so it is caught here instead of later. + """ + from azure.cosmos.exceptions import CosmosResourceNotFoundError + + counter_container = self._get_counter_container() + for container in (*self._containers.values(), counter_container): + if container is None: + continue + try: + self._require_partition_key(container) + except CosmosResourceNotFoundError as exc: + raise ConfigurationError( + f"container {getattr(container, 'id', None)!r} does not exist: run create_memory_store() or " + "deploy the infrastructure (azd up), and make sure the SDK settings name the same containers" + ) from exc + def _build_store(self) -> MemoryStore: return MemoryStore( containers=self._containers, diff --git a/azure/cosmos/agent_memory/models.py b/azure/cosmos/agent_memory/models.py index b4eab25..a2f5a23 100644 --- a/azure/cosmos/agent_memory/models.py +++ b/azure/cosmos/agent_memory/models.py @@ -29,7 +29,6 @@ model_validator, ) -from azure.cosmos.agent_memory._partitioning import DEFAULT_TENANT_ID from azure.cosmos.agent_memory.logging import get_logger logger = get_logger(__name__) @@ -168,7 +167,8 @@ class MemoryRecordBase(BaseModel): ) id: str = Field(default_factory=_uuid4_str) - tenant_id: str = DEFAULT_TENANT_ID + # ``None`` until the record is written: the client stamps its own tenant, and refuses a record that names another. + tenant_id: Optional[str] = None user_id: str thread_id: str = Field(default_factory=_uuid4_str) role: Optional[MemoryRole] = None @@ -373,6 +373,7 @@ def _strip_unset_optional(data: dict[str, Any]) -> dict[str, Any]: emitted because callers and Cosmos queries treat them as ever-present. """ drop_when_none = { + "tenant_id", "embedding", "agent_id", "updated_at", diff --git a/azure/cosmos/agent_memory/processors/inprocess.py b/azure/cosmos/agent_memory/processors/inprocess.py index b26cfe5..16374b0 100644 --- a/azure/cosmos/agent_memory/processors/inprocess.py +++ b/azure/cosmos/agent_memory/processors/inprocess.py @@ -15,7 +15,8 @@ class InProcessProcessor: This is the default backend. Wraps an existing :class:`azure.cosmos.agent_memory.services.pipeline.PipelineService` instance, or constructs one from the supplied container / LLM / embeddings clients, - bound to ``tenant_id`` (``"default"`` when not given). + bound to ``tenant_id`` (``"default"`` when not given). A ``pipeline`` you pass keeps its own tenant, which + :attr:`tenant_id` reports and ``tenant_id=`` does not change; a client built with another tenant refuses it. """ def __init__( @@ -62,6 +63,11 @@ def __init__( self._pipeline = pipeline + @property + def tenant_id(self) -> Optional[str]: + """The tenant of the pipeline this processor runs, or ``None`` when that pipeline reports none.""" + return getattr(self._pipeline, "tenant_id", None) + def process_thread( self, *, diff --git a/azure/cosmos/agent_memory/services/pipeline.py b/azure/cosmos/agent_memory/services/pipeline.py index 64bf228..be340ba 100644 --- a/azure/cosmos/agent_memory/services/pipeline.py +++ b/azure/cosmos/agent_memory/services/pipeline.py @@ -313,6 +313,11 @@ def __init__( self._prompty = PromptyLoader(prompts_dir) self._transcript_metadata_keys: Optional[tuple[str, ...]] = _normalize_metadata_keys(transcript_metadata_keys) + @property + def tenant_id(self) -> str: + """The tenant this service reads and writes.""" + return self._tenant_id + def _run_prompty( self, filename: str, @@ -1836,10 +1841,8 @@ def persist_thread_summary( if not isinstance(summary_doc, dict): raise ValidationError("summary_doc must be a dict") - doc = stamp_scope(summary_doc, self._tenant_id) + doc = stamp_scope({**summary_doc, "user_id": user_id, "thread_id": thread_id}, self._tenant_id) doc["id"] = doc.get("id") or f"summary_{user_id}_{thread_id}" - doc["user_id"] = user_id - doc["thread_id"] = thread_id doc.setdefault("prompt_id", "summarize.prompty") doc.setdefault("prompt_version", "v1") self._redact_for_embedding(doc) @@ -1993,10 +1996,8 @@ def persist_user_summary( if not isinstance(user_summary_doc, dict): raise ValidationError("user_summary_doc must be a dict") - doc = stamp_scope(user_summary_doc, self._tenant_id) + doc = stamp_scope({**user_summary_doc, "user_id": user_id, "thread_id": "__user_summary__"}, self._tenant_id) doc["id"] = doc.get("id") or f"user_summary_{user_id}" - doc["user_id"] = user_id - doc["thread_id"] = "__user_summary__" doc.setdefault("prompt_id", "user_summary.prompty") doc.setdefault("prompt_version", "v1") structured_summary = doc.get("metadata", {}).get("structured_summary") diff --git a/azure/cosmos/agent_memory/store/memory_store.py b/azure/cosmos/agent_memory/store/memory_store.py index 8fa078d..a46ec78 100644 --- a/azure/cosmos/agent_memory/store/memory_store.py +++ b/azure/cosmos/agent_memory/store/memory_store.py @@ -26,6 +26,7 @@ resolve_tenant_id, stamp_scope, validate_owner_id, + validate_thread_id, ) from azure.cosmos.agent_memory._query_builder import _QueryBuilder from azure.cosmos.agent_memory._utils import ( @@ -343,6 +344,8 @@ def add( text that held a credential. """ validate_owner_id(user_id) + if thread_id is not None: + validate_thread_id(thread_id) content, secret_patterns = sanitize_text(content) kwargs: dict[str, Any] = { "tenant_id": self._tenant_id, diff --git a/function_app/triggers/change_feed.py b/function_app/triggers/change_feed.py index 56b4996..5f7c661 100644 --- a/function_app/triggers/change_feed.py +++ b/function_app/triggers/change_feed.py @@ -5,9 +5,9 @@ ID whenever a configured threshold is crossed. Every turn names its tenant in ``tenant_id``; a turn without a valid one, or without a valid owner or thread, is -skipped. Counters, watermarks, -instance IDs (a hash of the owner, see :mod:`shared.instance_ids`) and orchestrator inputs are per -``(tenant_id, user_id[, thread_id])``, so one Function App serves every tenant that writes to the containers. +skipped. Counters, watermarks, instance IDs (a hash of the owner, see :mod:`shared.instance_ids`) and orchestrator +inputs are per ``(tenant_id, user_id[, thread_id])``, so one Function App serves every tenant that writes to the +containers. A failure for one thread or owner does not stop the others in the batch; the batch fails at the end. The trigger is registered as a :class:`df.Blueprint` and wired into the top-level :class:`df.DFApp` from ``function_app.py``. The pure-logic entry @@ -37,7 +37,12 @@ ) from shared.instance_ids import orchestration_instance_id -from azure.cosmos.agent_memory._partitioning import partition_key_problem, resolve_tenant_id, validate_owner_id +from azure.cosmos.agent_memory._partitioning import ( + partition_key_problem, + resolve_tenant_id, + validate_owner_id, + validate_thread_id, +) from azure.cosmos.agent_memory.exceptions import ValidationError from azure.cosmos.agent_memory.logging import describe_exception @@ -106,6 +111,24 @@ def _owner_of(doc: dict) -> str | None: return None +def _thread_of(doc: dict) -> str | None: + """The thread a changed turn names, or ``None`` when it names none or one that is not valid.""" + try: + return validate_thread_id(doc.get("thread_id")) + except ValidationError: + return None + + +def _record_key_failure(exc: Exception, key_errors: list[Exception]) -> None: + """Log one thread's or owner's failed update and remember it, so the rest of the batch still runs.""" + logger.error( + "change-feed: failed to update a counter (exc_type=%s): %s", + type(exc).__name__, + describe_exception(exc, stack=True), + ) + key_errors.append(exc) + + # --------------------------------------------------------------------------- # Pure-logic entry point (exposed for unit tests) # --------------------------------------------------------------------------- @@ -190,7 +213,7 @@ async def process_changefeed_batch( # delivered - and counted - exactly once, at creation. tenant_id = _tenant_of(doc) user_id = _owner_of(doc) - thread_id = doc.get("thread_id") + thread_id = _thread_of(doc) if not tenant_id or not user_id or not thread_id: logger.warning("change-feed: turn doc missing a valid tenant_id, user_id or thread_id, skipping") continue @@ -222,110 +245,128 @@ async def process_changefeed_batch( counter_container = await get_counter_container_async() orchestration_errors: list[Exception] = [] + key_errors: list[Exception] = [] + + # Each thread and each owner is handled on its own: a failure for one is recorded and the rest of the batch still + # runs, so one bad key cannot lose the counts of the other tenants' turns in the same batch. # ---- Step 2: Thread-scoped counters ---- if thread_enabled: for thread_key, batch_count in thread_counts.items(): - tenant_id, user_id, thread_id = thread_key - cid = thread_counter_id(user_id, thread_id) - lsn = thread_max_lsn.get(thread_key) - old_count, new_count = await increment_counter_by( - counter_container, - tenant_id, - cid, - user_id, - thread_id, - batch_count, - batch_max_lsn=lsn, - ) - - if n_thread > 0 and crosses_threshold(old_count, new_count, n_thread): - instance_id = orchestration_instance_id( - "thread_summary", tenant_id, user_id, thread_id, count=new_count - ) - await _safe_start( - starter, - "ThreadSummaryOrchestrator", - instance_id, - {"tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id, "count": new_count}, - orchestration_errors, - ) - - if n_facts > 0 and crosses_threshold(old_count, new_count, n_facts): - instance_id = orchestration_instance_id("extract", tenant_id, user_id, thread_id, count=new_count) - should_reconcile = bool(n_dedup_turns > 0 and crosses_threshold(old_count, new_count, n_dedup_turns)) - watermark = await read_extract_watermark(counter_container, tenant_id, cid, user_id) - # Not capped: new_count - watermark is exactly the turns the watermark has - # not covered, and the orchestrator advances the watermark to new_count, so - # capping would strand the oldest turns (DEDUP_POOL_SIZE is the reconcile - # knob, not the extraction window). Bootstrap: with no watermark yet, base=0 - # so recent_k = new_count covers every turn so far - using only this - # batch (new_count - old_count) would strand turns added during earlier - # failed extracts once the watermark first advances to new_count. - base = watermark if watermark is not None else 0 - recent_k = max(new_count - base, 1) - await _safe_start( - starter, - "ExtractMemoriesOrchestrator", - instance_id, - { - "tenant_id": tenant_id, - "user_id": user_id, - "thread_id": thread_id, - "count": new_count, - "reconcile": should_reconcile, - "recent_k": recent_k, - }, - orchestration_errors, + try: + tenant_id, user_id, thread_id = thread_key + cid = thread_counter_id(user_id, thread_id) + lsn = thread_max_lsn.get(thread_key) + old_count, new_count = await increment_counter_by( + counter_container, + tenant_id, + cid, + user_id, + thread_id, + batch_count, + batch_max_lsn=lsn, ) - if n_episode > 0 and crosses_threshold(old_count, new_count, n_episode): - instance_id = orchestration_instance_id("episode", tenant_id, user_id, thread_id, count=new_count) - await _safe_start( - starter, - "ExtractEpisodesOrchestrator", - instance_id, - {"tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id, "count": new_count}, - orchestration_errors, - ) + if n_thread > 0 and crosses_threshold(old_count, new_count, n_thread): + instance_id = orchestration_instance_id( + "thread_summary", tenant_id, user_id, thread_id, count=new_count + ) + await _safe_start( + starter, + "ThreadSummaryOrchestrator", + instance_id, + {"tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id, "count": new_count}, + orchestration_errors, + ) + + if n_facts > 0 and crosses_threshold(old_count, new_count, n_facts): + instance_id = orchestration_instance_id("extract", tenant_id, user_id, thread_id, count=new_count) + should_reconcile = bool( + n_dedup_turns > 0 and crosses_threshold(old_count, new_count, n_dedup_turns) + ) + watermark = await read_extract_watermark(counter_container, tenant_id, cid, user_id) + # Not capped: new_count - watermark is exactly the turns the watermark has + # not covered, and the orchestrator advances the watermark to new_count, so + # capping would strand the oldest turns (DEDUP_POOL_SIZE is the reconcile + # knob, not the extraction window). Bootstrap: with no watermark yet, base=0 + # so recent_k = new_count covers every turn so far - using only this + # batch (new_count - old_count) would strand turns added during earlier + # failed extracts once the watermark first advances to new_count. + base = watermark if watermark is not None else 0 + recent_k = max(new_count - base, 1) + await _safe_start( + starter, + "ExtractMemoriesOrchestrator", + instance_id, + { + "tenant_id": tenant_id, + "user_id": user_id, + "thread_id": thread_id, + "count": new_count, + "reconcile": should_reconcile, + "recent_k": recent_k, + }, + orchestration_errors, + ) + + if n_episode > 0 and crosses_threshold(old_count, new_count, n_episode): + instance_id = orchestration_instance_id("episode", tenant_id, user_id, thread_id, count=new_count) + await _safe_start( + starter, + "ExtractEpisodesOrchestrator", + instance_id, + {"tenant_id": tenant_id, "user_id": user_id, "thread_id": thread_id, "count": new_count}, + orchestration_errors, + ) + except Exception as exc: + _record_key_failure(exc, key_errors) # ---- Step 3: User-scoped counters ---- if user_enabled: for user_key, batch_count in user_counts.items(): - tenant_id, user_id = user_key - cid = user_counter_id(user_id) - lsn = user_max_lsn.get(user_key) - old_count, new_count = await increment_counter_by( - counter_container, - tenant_id, - cid, - user_id, - config.USER_COUNTER_THREAD_ID, - batch_count, - batch_max_lsn=lsn, - ) - if crosses_threshold(old_count, new_count, n_user): - instance_id = orchestration_instance_id("user_summary", tenant_id, user_id, count=new_count) - await _safe_start( - starter, - "UserSummaryOrchestrator", - instance_id, - { - "tenant_id": tenant_id, - "user_id": user_id, - "count": new_count, - "thread_ids": sorted(user_thread_ids.get(user_key, set())), - }, - orchestration_errors, + try: + tenant_id, user_id = user_key + cid = user_counter_id(user_id) + lsn = user_max_lsn.get(user_key) + old_count, new_count = await increment_counter_by( + counter_container, + tenant_id, + cid, + user_id, + config.USER_COUNTER_THREAD_ID, + batch_count, + batch_max_lsn=lsn, ) - - # Re-raise so the change-feed batch is retried & thresholds re-fire. The host logs this error and any it was - # raised from, so it names the first failure safely instead of chaining the SDK error and its text. - if orchestration_errors: - raise RuntimeError( - f"Failed to start {len(orchestration_errors)} orchestration(s): " - f"{describe_exception(orchestration_errors[0])}" - ) + if crosses_threshold(old_count, new_count, n_user): + instance_id = orchestration_instance_id("user_summary", tenant_id, user_id, count=new_count) + await _safe_start( + starter, + "UserSummaryOrchestrator", + instance_id, + { + "tenant_id": tenant_id, + "user_id": user_id, + "count": new_count, + "thread_ids": sorted(user_thread_ids.get(user_key, set())), + }, + orchestration_errors, + ) + except Exception as exc: + _record_key_failure(exc, key_errors) + + # Re-raise so the host records the batch as failed, and retries it when a retry policy is set: a counter skips + # turns it has already counted, so a retry is safe. The host logs this error and any it was raised from, so it + # names the first failure safely instead of chaining the SDK error and its text. + if orchestration_errors or key_errors: + problems: list[str] = [] + if orchestration_errors: + problems.append( + f"Failed to start {len(orchestration_errors)} orchestration(s): " + f"{describe_exception(orchestration_errors[0])}" + ) + if key_errors: + problems.append(f"Failed to update {len(key_errors)} counter(s): {describe_exception(key_errors[0])}") + raise RuntimeError("; ".join(problems)) async def _safe_start( diff --git a/infra/README.md b/infra/README.md index 5ba5ba5..f61e15e 100644 --- a/infra/README.md +++ b/infra/README.md @@ -16,7 +16,7 @@ This folder provisions everything the Agent Memory Toolkit needs in a single Azu | `leases` | `/id` | Change-feed checkpoints | | `counter` | `/tenant_id`, `/user_id` | Atomic counters; 90-day default TTL | - Everything one owner (a user or an agent) knows in one tenant is in one logical partition; `thread_id` is a plain field. A container's partition key cannot be changed, so a deployment created with the earlier `[user_id, thread_id]` key has to recreate its containers: delete `memories`, `memories_turns`, `memories_summaries`, `counter` and `leases` (their data is lost) and run `azd up`. A container left with the earlier key is refused by `create_memory_store()`, by `validate_topology()` and by the Function App on its first change-feed batch, so the mistake shows up at startup rather than as empty reads. + Everything one owner (a user or an agent) knows in one tenant is in one logical partition; `thread_id` is a plain field. A container's partition key cannot be changed, so a deployment created with the earlier `[user_id, thread_id]` key has to recreate its containers: delete `memories`, `memories_turns`, `memories_summaries`, `counter` and `leases` (their data is lost) and run `azd up`; the README's [migration notes](../README.md#migration-notes) give the whole upgrade in order. A container left with the earlier key is refused by `connect_cosmos()`, by `create_memory_store()`, by `validate_topology()` and by the Function App on its first change-feed batch, so the mistake shows up when a client connects or that batch runs, not as empty reads. - **AI Foundry** (`Microsoft.CognitiveServices/accounts` with `kind: AIServices`) - with `gpt-4o-mini` and `text-embedding-3-large` deployments - **User-assigned managed identity (UAMI)** - used by the Function app - **RBAC role assignments** - Cosmos DB Built-in Data Reader + Contributor, Cognitive Services OpenAI User, Storage Blob/Queue/Table data roles, granted to the UAMI and (except the Storage Queue/Table roles) the deploying user (full table in [Identity & RBAC](#identity--rbac)) @@ -89,7 +89,7 @@ When `DEPLOY_FUNCTION_APP=false`, the Bicep template automatically sets `MEMORY_ azd env set MEMORY_PROCESSOR_OWNER inprocess ``` -The in-process auto-trigger counts turns in the `counter` container, and the client's `create_memory_store()` also creates `leases`; this mode creates neither. `CosmosMemoryClient(cosmos_endpoint=...)` calls `create_memory_store()` when it is constructed, which creates any missing container. Cosmos DB allows that with key auth but rejects it for Azure AD data-plane roles, so the constructor then raises: create `counter` and `leases` first (settings as in `infra/modules/cosmos.bicep`), or connect once with key auth. +The in-process auto-trigger counts turns in the `counter` container, and the client's `create_memory_store()` also creates `leases`; this mode creates neither. `CosmosMemoryClient(cosmos_endpoint=...)` calls `create_memory_store()` when it is constructed, which creates any missing container (the async client's constructor does no I/O, so it does this when you `await client.create_memory_store()`). Cosmos DB allows that with key auth but rejects it for Azure AD data-plane roles, so the constructor then raises, and `connect_cosmos()` creates nothing and refuses a missing `counter`. Create `counter` and `leases` first (settings as in `infra/modules/cosmos.bicep`), or connect once with key auth. ## Model / deployment names diff --git a/tests/unit/aio/processors/test_inprocess.py b/tests/unit/aio/processors/test_inprocess.py index cc0f0cb..ff906c4 100644 --- a/tests/unit/aio/processors/test_inprocess.py +++ b/tests/unit/aio/processors/test_inprocess.py @@ -2,7 +2,8 @@ from __future__ import annotations -from unittest.mock import AsyncMock +from types import SimpleNamespace +from unittest.mock import AsyncMock, MagicMock import pytest @@ -135,3 +136,22 @@ async def test_process_thread_summary_returns_none_for_non_dict(): proc = AsyncInProcessProcessor(pipeline=pipeline) result = await proc.process_thread_summary(user_id="u", thread_id="t") assert result is None + + +def test_the_processor_reports_the_tenant_of_the_pipeline_it_runs(): + built = AsyncInProcessProcessor( + cosmos_container=MagicMock(), + turns_container=MagicMock(), + summaries_container=MagicMock(), + chat_client=MagicMock(), + embeddings_client=MagicMock(), + tenant_id="acme", + ) + # ``tenant_id=`` applies only to a pipeline the processor builds. + wrapped = AsyncInProcessProcessor(pipeline=built._pipeline, tenant_id="globex") + + assert built.tenant_id == wrapped.tenant_id == "acme" + + +def test_a_pipeline_that_reports_no_tenant_leaves_the_processor_without_one(): + assert AsyncInProcessProcessor(pipeline=SimpleNamespace()).tenant_id is None diff --git a/tests/unit/aio/services/test_extract_episodes_async.py b/tests/unit/aio/services/test_extract_episodes_async.py index a312343..de178f5 100644 --- a/tests/unit/aio/services/test_extract_episodes_async.py +++ b/tests/unit/aio/services/test_extract_episodes_async.py @@ -254,3 +254,24 @@ async def test_build_episode_docs_keeps_padded_timestamps_and_clamps_scores() -> assert docs[0]["ended_at"] == "2025-01-01T00:02:00+00:00" assert docs[0]["salience"] == 1.0 assert docs[0]["confidence"] == 0.0 + + +@pytest.mark.asyncio +async def test_the_same_turns_in_two_threads_make_episodes_and_watermarks_with_different_ids(monkeypatch) -> None: + monkeypatch.setenv("EPISODE_TOPIC_DRIFT", "0") + memories = _AsyncIdUniqueStore([]) + turns = _AsyncStore([_turn(1), _turn(2), {**_turn(1), "thread_id": "t2"}, {**_turn(2), "thread_id": "t2"}]) + service = AsyncPipelineService( + memories, + _AsyncChat([{"episodes": [_episode()]}, {"episodes": [_episode()]}]), + _AsyncEmbeddings(), + containers=_async_containers_for_store(memories, turns_store=turns), + ) + + assert await service.extract_episodes("u1", "t1", flush=True) == {"episodes": 1} + assert await service.extract_episodes("u1", "t2", flush=True) == {"episodes": 1} + + episodes = [doc for doc in memories.docs if doc["type"] == "episodic"] + cursors = [doc for doc in memories.docs if doc["type"] == "episode_cursor"] + assert {doc["thread_id"] for doc in episodes} == {"t1", "t2"} and len({doc["id"] for doc in episodes}) == 2 + assert {doc["id"] for doc in cursors} == {"episode_cursor_u1_t1", "episode_cursor_u1_t2"} diff --git a/tests/unit/aio/services/test_tenant_isolation_async.py b/tests/unit/aio/services/test_tenant_isolation_async.py index dfb0661..8ffa182 100644 --- a/tests/unit/aio/services/test_tenant_isolation_async.py +++ b/tests/unit/aio/services/test_tenant_isolation_async.py @@ -129,11 +129,15 @@ async def patch_item(self, *, item: str, partition_key: Any, patch_operations: l class _Embeddings: + def __init__(self) -> None: + self.calls: list[str] = [] + async def generate(self, text: str) -> list[float]: - del text + self.calls.append(text) return [1.0, 0.0] async def generate_batch(self, texts: list[str]) -> list[list[float]]: + self.calls.extend(texts) return [[1.0, 0.0] for _ in texts] @@ -143,6 +147,7 @@ def _service( memories: _Container | None = None, turns: _Container | None = None, summaries: _Container | None = None, + embeddings: _Embeddings | None = None, replies: Iterable[dict[str, Any]] = (), ) -> AsyncPipelineService: containers = { @@ -152,7 +157,9 @@ def _service( } store = MagicMock() store.mark_superseded = AsyncMock(return_value=True) - service = AsyncPipelineService(store, MagicMock(), _Embeddings(), containers=containers, tenant_id=tenant) + service = AsyncPipelineService( + store, MagicMock(), embeddings or _Embeddings(), containers=containers, tenant_id=tenant + ) service._run_prompty = AsyncMock(side_effect=[json.dumps(reply) for reply in replies]) return service @@ -234,6 +241,29 @@ async def test_extraction_reads_marks_and_writes_only_its_tenants_records(monkey assert summaries.reads == [("summary_u1_t1", OWNER)] +async def test_the_same_fact_is_stored_once_per_owner_and_thread() -> None: + memories = _Container() + fact = {"text": "The user likes tea.", "category": "preference", "confidence": 0.9, "salience": 0.8, "tags": []} + service = _service(memories=memories, replies=[{"facts": [fact]}] * 4) + + async def extract_and_persist(user_id: str, thread_id: str) -> int: + turn = {**_turn("turn-a"), "user_id": user_id, "thread_id": thread_id} + extracted = await service.extract_memories_durable(user_id, thread_id, turns=[turn]) + return (await service.persist_extracted_memories(user_id, extracted))["fact_count"] + + created = [ + await extract_and_persist("u1", "t1"), + await extract_and_persist("u1", "t1"), + await extract_and_persist("u1", "t2"), + await extract_and_persist("u2", "t1"), + ] + + assert created == [1, 0, 1, 1], "only the same fact from the same thread of the same owner is a replay" + ids = {(doc["user_id"], doc["thread_id"]): doc["id"] for doc in memories.docs.values()} + assert sorted(ids) == [("u1", "t1"), ("u1", "t2"), ("u2", "t1")] + assert len(set(ids.values())) == 3, "the owner is part of the id, not only of the partition" + + async def test_persisting_extracted_memories_stamps_the_tenant_and_refuses_another_tenants_records() -> None: memories = _Container() service = _service(memories=memories) @@ -361,6 +391,68 @@ async def test_a_summary_naming_another_tenant_is_refused(persist, summary_id: s assert stored["tenant_id"] == TENANT and list(summaries.docs) == [(TENANT, USER, summary_id)] +async def _persist_summary( + service: AsyncPipelineService, kind: str, doc: dict[str, Any], user_id: str = USER, thread_id: str = "t1" +) -> dict[str, Any]: + if kind == "thread_summary": + return await service.persist_thread_summary(user_id, thread_id, doc) + return await service.persist_user_summary(user_id, doc) + + +@pytest.mark.parametrize( + ("kind", "summary_id", "thread_id"), + [("thread_summary", "summary_u1_t1", "t1"), ("user_summary", "user_summary_u1", "__user_summary__")], +) +async def test_a_summary_without_an_owner_is_stored_for_the_owner_it_is_persisted_for( + kind: str, summary_id: str, thread_id: str +) -> None: + summaries = _Container() + service = _service(summaries=summaries) + doc = {"type": kind, "content": "Tea.", "metadata": {"thread_ids": ["t1"]}} + original = copy.deepcopy(doc) + + stored = await _persist_summary(service, kind, doc) + + assert (stored["tenant_id"], stored["user_id"], stored["thread_id"], stored["id"]) == ( + TENANT, + USER, + thread_id, + summary_id, + ) + assert list(summaries.docs) == [(TENANT, USER, summary_id)] + assert doc == original, "the caller's dict is not rewritten" + + +VALID_IDS = {"user_id": USER, "thread_id": "t1"} + + +@pytest.mark.parametrize( + ("kind", "user_id", "thread_id", "fields", "problem"), + [ + # The document names no owner, so the tenant is what is refused. + pytest.param("thread_summary", USER, "t1", {"tenant_id": OTHER}, "different tenant", id="thread-tenant"), + pytest.param("user_summary", USER, "t1", {"tenant_id": OTHER}, "different tenant", id="user-tenant"), + # The document names a valid owner and thread of its own, so what is refused is the argument. + pytest.param("thread_summary", "bad/id", "t1", VALID_IDS, "user_id", id="thread-owner"), + pytest.param("thread_summary", "u1 ", "t1", VALID_IDS, "user_id", id="thread-owner-space"), + pytest.param("thread_summary", USER, "t1 ", VALID_IDS, "thread_id", id="thread-thread-space"), + pytest.param("user_summary", "bad/id", "t1", VALID_IDS, "user_id", id="user-owner"), + pytest.param("user_summary", "u1 ", "t1", VALID_IDS, "user_id", id="user-owner-space"), + ], +) +async def test_a_summary_that_cannot_be_stored_is_refused_before_its_content_is_embedded( + kind: str, user_id: str, thread_id: str, fields: dict[str, Any], problem: str +) -> None: + summaries, embeddings = _Container(), _Embeddings() + service = _service(summaries=summaries, embeddings=embeddings) + doc = {"type": kind, "content": "Tea.", "metadata": {"thread_ids": ["t1"]}, **fields} + + with pytest.raises(ValidationError, match=problem): + await _persist_summary(service, kind, doc, user_id, thread_id) + + assert embeddings.calls == [] and summaries.docs == {} + + # --- reconcile ------------------------------------------------------------------------------------------------ diff --git a/tests/unit/aio/test_cosmos_memory_client.py b/tests/unit/aio/test_cosmos_memory_client.py index 3b22539..5b335ac 100644 --- a/tests/unit/aio/test_cosmos_memory_client.py +++ b/tests/unit/aio/test_cosmos_memory_client.py @@ -5,6 +5,7 @@ import asyncio import inspect import uuid +from contextlib import contextmanager from datetime import datetime, timezone from types import SimpleNamespace from unittest.mock import AsyncMock, MagicMock, patch @@ -14,6 +15,7 @@ from azure.cosmos.agent_memory._container_routing import ContainerKey from azure.cosmos.agent_memory._partitioning import DEFAULT_TENANT_ID, PARTITION_KEY_PATHS from azure.cosmos.agent_memory.aio.cosmos_memory_client import AsyncCosmosMemoryClient +from azure.cosmos.agent_memory.aio.processors import AsyncInProcessProcessor from azure.cosmos.agent_memory.aio.store import AsyncMemoryStore from azure.cosmos.agent_memory.exceptions import ( ConfigurationError, @@ -36,6 +38,23 @@ def _keyed_container(paths=PARTITION_KEY_PATHS, container_id="container") -> Mag return MagicMock(id=container_id, read=AsyncMock(return_value=properties)) +async def _assert_discarded(mem, cosmos_client) -> None: + """A failed connect or store creation closes the Cosmos client it opened and leaves ``mem`` unconnected.""" + cosmos_client.close.assert_awaited_once() + for attribute in ( + "_cosmos_client", + "_memories_container_client", + "_turns_container_client", + "_summaries_container_client", + "_counter_container_client", + "_store", + "_pipeline", + ): + assert getattr(mem, attribute) is None, attribute + with pytest.raises(CosmosNotConnectedError): + await mem._require_cosmos() + + class AsyncIterator: """Simple async iterator over a list of items.""" @@ -153,6 +172,43 @@ def test_a_memory_is_addressed_by_its_owner_not_its_thread(self, method): assert "thread_id" not in inspect.signature(getattr(AsyncCosmosMemoryClient, method)).parameters +class _CustomProcessor: + """A processor of its own: it reports no tenant.""" + + +class TestProcessorTenant: + @staticmethod + def _processor(tenant_id: str) -> AsyncInProcessProcessor: + """A processor over a real pipeline of ``tenant_id``.""" + return AsyncInProcessProcessor( + cosmos_container=MagicMock(), + turns_container=MagicMock(), + summaries_container=MagicMock(), + chat_client=MagicMock(), + embeddings_client=MagicMock(), + tenant_id=tenant_id, + ) + + def test_a_processor_of_another_tenant_is_refused(self): + with pytest.raises(ConfigurationError, match=rf"tenant '{DEFAULT_TENANT_ID}'.*tenant 'acme'"): + _make_client(tenant_id="acme", processor=self._processor(DEFAULT_TENANT_ID)) + + def test_a_processor_of_the_clients_tenant_is_used(self): + processor = self._processor("acme") + + assert _make_client(tenant_id="acme", processor=processor)._get_processor() is processor + + @pytest.mark.parametrize( + "processor", + [ + pytest.param(_CustomProcessor(), id="custom"), + pytest.param(AsyncInProcessProcessor(pipeline=MagicMock()), id="pipeline-double"), + ], + ) + def test_a_processor_that_reports_no_tenant_is_not_checked(self, processor): + assert _make_client(tenant_id="acme", processor=processor)._get_processor() is processor + + # =================================================================== # Injected embeddings / chat clients # =================================================================== @@ -345,6 +401,22 @@ def test_delete_local_not_found(self): class TestConnectCosmos: + CONTAINERS = ("memories", "memories_turns", "memories_summaries", "counter") + + @staticmethod + @contextmanager + def _serving(containers): + """Patch ``azure.cosmos.aio`` so ``connect_cosmos`` finds ``containers`` by id; yields the Cosmos client.""" + cosmos_client = MagicMock(close=AsyncMock()) + cosmos_client.get_database_client.return_value.get_container_client.side_effect = containers.__getitem__ + aio = MagicMock(CosmosClient=MagicMock(return_value=cosmos_client)) + with patch.dict("sys.modules", {"azure.cosmos.aio": aio}): + yield cosmos_client + + @staticmethod + async def _connect(mem): + await mem.connect_cosmos(endpoint="https://fake.documents.azure.com:443/", credential="fake-key") + async def test_connect_cosmos_success(self): mem = _make_client( cosmos_endpoint="https://fake.documents.azure.com:443/", @@ -352,7 +424,7 @@ async def test_connect_cosmos_success(self): ) mock_cosmos_cls = MagicMock() mock_db = MagicMock() - mock_container = MagicMock() + mock_container = _keyed_container() mock_cosmos_cls.return_value = mock_cosmos_cls mock_cosmos_cls.get_database_client.return_value = mock_db mock_db.get_container_client.return_value = mock_container @@ -365,13 +437,81 @@ async def test_connect_cosmos_success(self): assert mem._memories_container_client is mock_container + @pytest.mark.parametrize("earlier", CONTAINERS) + async def test_a_container_with_the_earlier_key_is_refused(self, earlier): + containers = {name: _keyed_container(container_id=name) for name in self.CONTAINERS} + containers[earlier] = _keyed_container(EARLIER_KEY, container_id=earlier) + mem = _make_client() + + with self._serving(containers) as cosmos_client: + with pytest.raises( + CosmosOperationError, + match=( + rf"Failed to connect to Cosmos DB \(async\): container '{earlier}' has partition key " + r"\['/user_id', '/thread_id'\].*\['/tenant_id', '/user_id'\]" + ), + ): + await self._connect(mem) + + await _assert_discarded(mem, cosmos_client) + + async def test_the_client_is_reset_even_when_closing_it_fails(self): + containers = {name: _keyed_container(container_id=name) for name in self.CONTAINERS} + containers["memories_turns"] = _keyed_container(EARLIER_KEY, container_id="memories_turns") + mem = _make_client() + + with self._serving(containers) as cosmos_client: + cosmos_client.close.side_effect = RuntimeError("close failed") + with pytest.raises( + CosmosOperationError, + match=r"Failed to connect to Cosmos DB \(async\): container 'memories_turns' has partition key", + ): + await self._connect(mem) + + await _assert_discarded(mem, cosmos_client) + + async def test_a_container_that_does_not_exist_is_refused(self): + from azure.cosmos.exceptions import CosmosResourceNotFoundError + + containers = {name: _keyed_container(container_id=name) for name in self.CONTAINERS} + containers["counter"].read.side_effect = CosmosResourceNotFoundError(message="missing") + mem = _make_client() + + with self._serving(containers) as cosmos_client: + with pytest.raises( + CosmosOperationError, + match=r"Failed to connect to Cosmos DB \(async\): container 'counter' does not exist", + ): + await self._connect(mem) + + await _assert_discarded(mem, cosmos_client) + + async def test_containers_keyed_by_tenant_and_user_connect_after_all_four_are_read(self): + containers = {name: _keyed_container(container_id=name) for name in self.CONTAINERS} + mem = _make_client() + + with self._serving(containers) as cosmos_client: + await self._connect(mem) + + cosmos_client.close.assert_not_awaited() + assert mem._memories_container_client is containers["memories"] + assert mem._turns_container_client is containers["memories_turns"] + assert mem._summaries_container_client is containers["memories_summaries"] + assert mem._counter_container_client is containers["counter"] + for container in containers.values(): + container.read.assert_awaited_once() + class TestPreferredLocations: @staticmethod async def _cosmos_client_kwargs(entry_point: str = "connect_cosmos", **client_kwargs) -> dict: mock_cosmos_cls = MagicMock() - database = MagicMock(create_container_if_not_exists=AsyncMock()) + database = MagicMock( + create_container_if_not_exists=AsyncMock(), + get_container_client=MagicMock(return_value=_keyed_container()), + ) mock_cosmos_cls.return_value.create_database_if_not_exists = AsyncMock(return_value=database) + mock_cosmos_cls.return_value.get_database_client.return_value = database mem = _make_client(**client_kwargs) with patch.dict( "sys.modules", @@ -601,15 +741,18 @@ async def test_create_memory_store_defaults_to_serverless(self): for call in mock_db.create_container_if_not_exists.await_args_list: assert "offer_throughput" not in call.kwargs + @pytest.mark.parametrize("close_fails", [False, True], ids=["closes", "close-fails"]) @pytest.mark.parametrize("earlier", ["memories", "memories_turns", "memories_summaries", "counter"]) - async def test_an_existing_container_with_the_earlier_key_is_refused(self, earlier): + async def test_an_existing_container_with_the_earlier_key_is_refused(self, earlier, close_fails): containers = { name: _keyed_container(container_id=name) for name in ("memories", "memories_turns", "memories_summaries", "counter") } containers[earlier] = _keyed_container(EARLIER_KEY, container_id=earlier) mock_cosmos_cls = MagicMock() - mock_cosmos_cls.return_value.close = AsyncMock() + mock_cosmos_cls.return_value.close = AsyncMock( + side_effect=RuntimeError("close failed") if close_fails else None + ) mock_db = AsyncMock() mock_db.create_container_if_not_exists = AsyncMock(side_effect=[*containers.values(), MagicMock()]) mock_cosmos_cls.return_value.create_database_if_not_exists = AsyncMock(return_value=mock_db) @@ -628,11 +771,7 @@ async def test_an_existing_container_with_the_earlier_key_is_refused(self, earli ): await mem.create_memory_store(endpoint="https://fake.documents.azure.com:443/", credential="fake-key") - mock_cosmos_cls.return_value.close.assert_awaited_once() - assert mem._cosmos_client is None - assert mem._memories_container_client is None - with pytest.raises(CosmosNotConnectedError): - await mem._require_cosmos() + await _assert_discarded(mem, mock_cosmos_cls.return_value) def test_constructor_ignores_autoscale_in_serverless_mode(self): # Even an invalid autoscale value is ignored in serverless mode. diff --git a/tests/unit/function_app/test_change_feed.py b/tests/unit/function_app/test_change_feed.py index cebc6d2..c8b7749 100644 --- a/tests/unit/function_app/test_change_feed.py +++ b/tests/unit/function_app/test_change_feed.py @@ -14,6 +14,7 @@ import logging import os import re +import traceback from unittest.mock import AsyncMock, MagicMock, patch import pytest @@ -131,6 +132,23 @@ def _user_instance_id(count: int, *, tenant_id: str = TENANT, user_id: str = "u1 return orchestration_instance_id("user_summary", tenant_id, user_id, count=count) +def _fail_counter_reads(container: MagicMock, error: BaseException, *counters: tuple[str, str, str]) -> None: + """Make reading any of the ``(tenant_id, user_id, counter_id)`` counters raise ``error``, as a failing call would. + + Every other counter is read as before, so the real counter code runs and only the named counters fail. + """ + read_item = container.read_item.side_effect + doomed = set(counters) + + async def failing_read_item(*, item, partition_key): + tenant_id, user_id = partition_key + if (tenant_id, user_id, item) in doomed: + raise error + return await read_item(item=item, partition_key=partition_key) + + container.read_item = AsyncMock(side_effect=failing_read_item) + + def _make_topology_db(missing_name: str | None = None, earlier_key_name: str | None = None): containers: dict[str, MagicMock] = {} for name in ( @@ -222,6 +240,37 @@ async def run_twice(): assert sum(container.read.await_count for container in containers.values()) == 4 +@patch.dict( + os.environ, + { + "THREAD_SUMMARY_EVERY_N": "2", + "FACT_EXTRACTION_EVERY_N": "0", + "EPISODE_EVAL_EVERY_N": "0", + "USER_SUMMARY_EVERY_N": "2", + }, + clear=False, +) +def test_a_batch_counts_nothing_when_a_container_has_the_earlier_key(monkeypatch): + """The batch checks the topology before it counts: with a container keyed ``[/user_id, /thread_id]`` no counter is + read or written and no orchestration starts, though these two turns would cross both thresholds.""" + monkeypatch.setattr(change_feed_module, "_topology_validated", False) + memories = change_feed_module.config.MEMORIES_CONTAINER + db, _containers = _make_topology_db(earlier_key_name=memories) + starter = _make_starter() + container = _make_counter_container_starting_at() + + with patch("shared.cosmos_clients.get_cosmos_database_async", new=AsyncMock(return_value=db)): + with pytest.raises(RuntimeError, match=rf"Topology error: container '{re.escape(memories)}' has partition key"): + asyncio.run(process_changefeed_batch([_turn(), _turn()], starter, counter_container=container)) + + container.read_item.assert_not_called() + container.create_item.assert_not_called() + container.upsert_item.assert_not_called() + starter.start_new.assert_not_awaited() + # A failed check is not remembered, so the next batch looks at the containers again. + assert change_feed_module._topology_validated is False + + # --------------------------------------------------------------------------- # Filtering / disabled-mode behaviour # --------------------------------------------------------------------------- @@ -441,6 +490,79 @@ def test_a_turn_with_an_unsupported_owner_is_skipped_like_one_without_a_tenant(o assert warnings == ["change-feed: turn doc missing a valid tenant_id, user_id or thread_id, skipping"] +@patch.dict( + os.environ, + { + "THREAD_SUMMARY_EVERY_N": "1", + "FACT_EXTRACTION_EVERY_N": "0", + "EPISODE_EVAL_EVERY_N": "0", + "USER_SUMMARY_EVERY_N": "2", + }, + clear=False, +) +@pytest.mark.parametrize( + "thread_id", + [ + pytest.param(7, id="integer"), + pytest.param(["t1"], id="list"), + pytest.param(None, id="null"), + pytest.param("", id="empty"), + pytest.param("t1 ", id="trailing-space"), + pytest.param(" t1", id="leading-space"), + pytest.param("a/b", id="slash"), + pytest.param("t\x7f1", id="control-character"), + pytest.param("t\u20281", id="line-separator"), + pytest.param("t" * 257, id="too-long"), + ], +) +def test_a_turn_with_an_unsupported_thread_is_skipped_and_the_batch_still_completes(thread_id, caplog): + """A thread id the SDK would refuse is skipped and the batch completes: an integer one used to make the instance + id raise, which lost the counts of every tenant in the batch. + + The turn counts nowhere, not even in the counters of its owner, who has valid turns too. The thread summary + threshold is 1, so counting the turn would start an orchestration for its thread at once. + """ + caplog.set_level(logging.WARNING) + starter = _make_starter() + container = _make_counter_container_starting_at() + # First in the batch, so a failure on it would cost the turns after it. + unusable = {"type": "turn", "tenant_id": TENANT, "user_id": "u1", "thread_id": thread_id, "content": "private text"} + docs = [unusable, *(_turn(tenant_id=tenant_id) for tenant_id in ("acme", "globex", "acme", "globex"))] + + asyncio.run(process_changefeed_batch(docs, starter, counter_container=container)) + + assert {key: doc["count"] for key, doc in container._state.items()} == { + (tenant_id, "u1", counter_id): 2 + for tenant_id in ("acme", "globex") + for counter_id in ("thread:u1:t1", "user:u1") + } + started = {c.kwargs["instance_id"]: c.kwargs["client_input"] for c in starter.start_new.await_args_list} + assert set(started) == { + _thread_instance_id("thread_summary", 2, tenant_id="acme"), + _thread_instance_id("thread_summary", 2, tenant_id="globex"), + _user_instance_id(2, tenant_id="acme"), + _user_instance_id(2, tenant_id="globex"), + } + assert started[_user_instance_id(2, tenant_id="acme")]["thread_ids"] == ["t1"] + warnings = [r.getMessage() for r in caplog.records if r.levelno == logging.WARNING] + assert warnings == ["change-feed: turn doc missing a valid tenant_id, user_id or thread_id, skipping"] + + +@pytest.mark.parametrize( + ("doc", "expected"), + [ + pytest.param({"thread_id": "t1"}, "t1", id="plain"), + pytest.param({"thread_id": "support chat: order 7"}, "support chat: order 7", id="space-and-colon-inside"), + pytest.param({"thread_id": "ünï©ødé"}, "ünï©ødé", id="non-ascii"), + pytest.param({"thread_id": "é" * 128}, "é" * 128, id="256-bytes"), + pytest.param({"thread_id": "é" * 129}, None, id="258-bytes-in-129-characters"), + pytest.param({}, None, id="missing"), + ], +) +def test_thread_of_accepts_the_thread_ids_the_sdk_accepts_and_counts_the_limit_in_bytes(doc, expected): + assert change_feed_module._thread_of(doc) == expected + + # --------------------------------------------------------------------------- # Threshold crossing → deterministic instance IDs # --------------------------------------------------------------------------- @@ -942,6 +1064,159 @@ def test_lsns_are_tracked_per_tenant_and_a_replay_counts_nothing_twice(): assert (globex["count"], globex["last_batch_lsn"]) == (1, 50) +# --------------------------------------------------------------------------- +# A failing thread or owner does not stop the others in the batch; the batch fails at the end +# --------------------------------------------------------------------------- + +_EVERY_TWO_TURNS = { + "THREAD_SUMMARY_EVERY_N": "2", + "FACT_EXTRACTION_EVERY_N": "0", + "EPISODE_EVAL_EVERY_N": "0", + "USER_SUMMARY_EVERY_N": "2", +} + +# What ``_batch_of_three_threads`` leaves in the counters, and the instance ids of the orchestrations it starts: every +# thread crosses a threshold of 2, and so does each owner, so each of the five counters starts one orchestration. +_BATCH_COUNTS = { + ("acme", "u1", "thread:u1:t1"): 2, + ("acme", "u1", "thread:u1:t2"): 2, + ("acme", "u1", "user:u1"): 4, + ("globex", "u1", "thread:u1:t1"): 2, + ("globex", "u1", "user:u1"): 2, +} +_BATCH_START_IDS = { + _thread_instance_id("thread_summary", 2, tenant_id="acme", thread_id="t1"), + _thread_instance_id("thread_summary", 2, tenant_id="acme", thread_id="t2"), + _user_instance_id(4, tenant_id="acme"), + _thread_instance_id("thread_summary", 2, tenant_id="globex", thread_id="t1"), + _user_instance_id(2, tenant_id="globex"), +} + + +def _batch_of_three_threads() -> list[dict]: + """Two turns each for acme's t1 and t2 and for globex's t1, all of owner u1; acme's thread comes first.""" + return [ + _turn(tenant_id=tenant_id, thread_id=thread_id) + for tenant_id, thread_id in (("acme", "t1"), ("acme", "t2"), ("globex", "t1")) + for _ in range(2) + ] + + +@patch.dict(os.environ, _EVERY_TWO_TURNS, clear=False) +@pytest.mark.parametrize( + ("failing", "lost_start"), + [ + pytest.param( + (TENANT, "u1", "thread:u1:t1"), _thread_instance_id("thread_summary", 2, thread_id="t1"), id="thread" + ), + pytest.param((TENANT, "u1", "user:u1"), _user_instance_id(4), id="owner"), + ], +) +def test_a_counter_that_cannot_be_updated_does_not_stop_the_rest_of_the_batch(failing, lost_start, caplog): + """The first thread, or the first owner, cannot be updated: every other counter is still written and every other + threshold crossing still starts its orchestration, and only then does the batch fail.""" + caplog.set_level(logging.INFO) + starter = _make_starter() + container = _make_counter_container_starting_at() + _fail_counter_reads(container, CosmosHttpResponseError(status_code=503, message="private text"), failing) + summary = r"^Failed to update 1 counter\(s\): azure\.cosmos\.CosmosHttpResponseError\(status=503\) at " + + with pytest.raises(RuntimeError, match=summary) as failed: + asyncio.run(process_changefeed_batch(_batch_of_three_threads(), starter, counter_container=container)) + + assert {key: doc["count"] for key, doc in container._state.items()} == { + key: count for key, count in _BATCH_COUNTS.items() if key != failing + } + assert {c.kwargs["instance_id"] for c in starter.start_new.await_args_list} == _BATCH_START_IDS - {lost_start} + # The failure is logged once as its type and code location. Neither the log nor the error the batch raises quotes + # the SDK error's text or chains to it. + [record] = [r for r in caplog.records if r.levelno == logging.ERROR] + assert record.exc_info is None + assert record.getMessage().startswith( + "change-feed: failed to update a counter (exc_type=CosmosHttpResponseError): " + "azure.cosmos.CosmosHttpResponseError(status=503) at " + ) + assert (failed.value.__cause__, failed.value.__context__) == (None, None) + assert "private text" not in caplog.text + "".join(traceback.format_exception(failed.value)) + + +@patch.dict( + os.environ, + { + "THREAD_SUMMARY_EVERY_N": "2", + "FACT_EXTRACTION_EVERY_N": "2", + "EPISODE_EVAL_EVERY_N": "0", + "USER_SUMMARY_EVERY_N": "0", + }, + clear=False, +) +def test_a_failure_after_a_thread_was_counted_does_not_stop_the_other_threads(monkeypatch): + """The whole work of a thread is isolated, not only its counter update: acme's watermark read fails after its + counter was written and its summary started, and globex is still extracted.""" + read_extract_watermark = change_feed_module.read_extract_watermark + + async def failing_for_acme(container, tenant_id, counter_id, user_id): + if tenant_id == "acme": + raise CosmosHttpResponseError(status_code=503, message="throttled") + return await read_extract_watermark(container, tenant_id, counter_id, user_id) + + monkeypatch.setattr(change_feed_module, "read_extract_watermark", failing_for_acme) + starter = _make_starter() + container = _make_counter_container_starting_at() + docs = [_turn(tenant_id=tenant_id) for tenant_id in ("acme", "acme", "globex", "globex")] + + with pytest.raises(RuntimeError, match=r"^Failed to update 1 counter\(s\): "): + asyncio.run(process_changefeed_batch(docs, starter, counter_container=container)) + + assert {key: doc["count"] for key, doc in container._state.items()} == { + ("acme", "u1", "thread:u1:t1"): 2, + ("globex", "u1", "thread:u1:t1"): 2, + } + assert [(c.args[0], c.kwargs["client_input"]["tenant_id"]) for c in starter.start_new.await_args_list] == [ + ("ThreadSummaryOrchestrator", "acme"), + ("ThreadSummaryOrchestrator", "globex"), + ("ExtractMemoriesOrchestrator", "globex"), + ] + + +@patch.dict(os.environ, _EVERY_TWO_TURNS, clear=False) +def test_failed_starts_and_failed_counters_of_one_batch_are_reported_in_one_error(): + starter = _make_starter() + starter.start_new.side_effect = ConnectionError("starter unavailable") + container = _make_counter_container_starting_at() + _fail_counter_reads( + container, + CosmosHttpResponseError(status_code=503, message="throttled"), + (TENANT, "u1", "thread:u1:t1"), + ("globex", "u1", "user:u1"), + ) + + with pytest.raises(RuntimeError) as failed: + asyncio.run(process_changefeed_batch(_batch_of_three_threads(), starter, counter_container=container)) + + # Of the five orchestrations, three are still attempted (acme's t2 and owner, globex's t1), and none starts. + assert starter.start_new.await_count == 3 + assert re.fullmatch( + r"Failed to start 3 orchestration\(s\): ConnectionError at .+; " + r"Failed to update 2 counter\(s\): azure\.cosmos\.CosmosHttpResponseError\(status=503\) at .+", + str(failed.value), + ) + + +@patch.dict(os.environ, _EVERY_TWO_TURNS, clear=False) +@pytest.mark.parametrize( + "cancelled", [(TENANT, "u1", "thread:u1:t1"), (TENANT, "u1", "user:u1")], ids=["thread", "owner"] +) +def test_a_cancellation_during_a_counter_update_is_not_swallowed(cancelled): + """Only an ``Exception`` is recorded and isolated per thread and owner: a ``CancelledError`` stops the batch.""" + starter = _make_starter() + container = _make_counter_container_starting_at() + _fail_counter_reads(container, asyncio.CancelledError(), cancelled) + + with pytest.raises(asyncio.CancelledError): + asyncio.run(process_changefeed_batch(_batch_of_three_threads(), starter, counter_container=container)) + + # --------------------------------------------------------------------------- # MEMORY_PROCESSOR_OWNER exclusivity - the change-feed trigger must # respect the owner env var the same way the SDK auto-trigger does, so a diff --git a/tests/unit/processors/test_inprocess.py b/tests/unit/processors/test_inprocess.py index 803b8c4..9454632 100644 --- a/tests/unit/processors/test_inprocess.py +++ b/tests/unit/processors/test_inprocess.py @@ -2,6 +2,7 @@ from __future__ import annotations +from types import SimpleNamespace from unittest.mock import MagicMock from azure.cosmos.agent_memory.processors import InProcessProcessor, ProcessThreadResult @@ -132,3 +133,22 @@ def test_constructor_requires_all_three_containers_when_no_pipeline(): chat_client=chat, embeddings_client=embeddings, ) + + +def test_the_processor_reports_the_tenant_of_the_pipeline_it_runs(): + built = InProcessProcessor( + cosmos_container=MagicMock(), + turns_container=MagicMock(), + summaries_container=MagicMock(), + chat_client=MagicMock(), + embeddings_client=MagicMock(), + tenant_id="acme", + ) + # ``tenant_id=`` applies only to a pipeline the processor builds. + wrapped = InProcessProcessor(pipeline=built._pipeline, tenant_id="globex") + + assert built.tenant_id == wrapped.tenant_id == "acme" + + +def test_a_pipeline_that_reports_no_tenant_leaves_the_processor_without_one(): + assert InProcessProcessor(pipeline=SimpleNamespace()).tenant_id is None diff --git a/tests/unit/services/test_extract_dry.py b/tests/unit/services/test_extract_dry.py index 5436801..ae8baf1 100644 --- a/tests/unit/services/test_extract_dry.py +++ b/tests/unit/services/test_extract_dry.py @@ -6,7 +6,7 @@ from unittest.mock import AsyncMock import pytest -from azure.cosmos.exceptions import CosmosResourceNotFoundError +from azure.cosmos.exceptions import CosmosResourceExistsError, CosmosResourceNotFoundError from azure.cosmos.agent_memory._container_routing import ContainerKey from azure.cosmos.agent_memory.aio.services.pipeline import AsyncPipelineService, _AsyncStoreContainerAdapter @@ -881,3 +881,41 @@ def test_extracted_facts_carry_the_tenant_and_the_same_fact_in_two_threads_has_t assert (second["tenant_id"], second["thread_id"]) == ("acme", "t2") assert first["content_hash"] == second["content_hash"] assert first["id"] != second["id"], "an owner's threads share one partition, so the thread is part of the id" + + +class _OwnerStore(_Store): + """A container keyed by ``[tenant_id, user_id]``: a record is created once per owner and id, as in Cosmos DB.""" + + def create_item(self, *, body: dict[str, Any]) -> dict[str, Any]: + key = (body["tenant_id"], body["user_id"], body["id"]) + if any((doc["tenant_id"], doc["user_id"], doc["id"]) == key for doc in self.docs): + raise CosmosResourceExistsError(message=body["id"]) + return self.upsert_memory(body) + + +def test_the_same_fact_is_stored_once_per_owner_and_thread() -> None: + memories_store = _OwnerStore([]) + service = PipelineService( + memories_store, + _SyncChat([_response()] * 4), + _SyncEmbeddings(), + containers=_containers_for_store(memories_store), + tenant_id="acme", + ) + + def extract_and_persist(user_id: str, thread_id: str) -> int: + turn = {**_turn(1), "user_id": user_id, "thread_id": thread_id} + extracted = service.extract_memories_durable(user_id, thread_id, turns=[turn]) + return service.persist_extracted_memories(user_id, extracted)["fact_count"] + + created = [ + extract_and_persist("u1", "t1"), + extract_and_persist("u1", "t1"), + extract_and_persist("u1", "t2"), + extract_and_persist("u2", "t1"), + ] + + assert created == [1, 0, 1, 1], "only the same fact from the same thread of the same owner is a replay" + ids = {(doc["user_id"], doc["thread_id"]): doc["id"] for doc in memories_store.docs} + assert sorted(ids) == [("u1", "t1"), ("u1", "t2"), ("u2", "t1")] + assert len(set(ids.values())) == 3, "the owner is part of the id, not only of the partition" diff --git a/tests/unit/services/test_pipeline_service.py b/tests/unit/services/test_pipeline_service.py index 85b84a2..a6db26e 100644 --- a/tests/unit/services/test_pipeline_service.py +++ b/tests/unit/services/test_pipeline_service.py @@ -1,5 +1,6 @@ from __future__ import annotations +import copy import json from typing import Any from unittest.mock import MagicMock @@ -355,6 +356,68 @@ def test_thread_summary_persists_to_summaries_container() -> None: summaries_container.upsert_item.assert_called_once() +def _persist_summary( + service: PipelineService, kind: str, doc: dict[str, Any], user_id: str = "u1", thread_id: str = "t1" +) -> dict[str, Any]: + if kind == "thread_summary": + return service.persist_thread_summary(user_id, thread_id, doc) + return service.persist_user_summary(user_id, doc) + + +@pytest.mark.parametrize( + ("kind", "summary_id", "thread_id"), + [("thread_summary", "summary_u1_t1", "t1"), ("user_summary", "user_summary_u1", "__user_summary__")], +) +def test_a_summary_without_an_owner_is_stored_for_the_owner_it_is_persisted_for( + kind: str, summary_id: str, thread_id: str +) -> None: + summaries_store = FakeStore() + service = _pipeline(FakeStore(), FakeLLMService([]), summaries_store=summaries_store, tenant_id="acme") + doc = {"type": kind, "content": "Thread discussed retries.", "metadata": {"thread_ids": ["t1"]}} + original = copy.deepcopy(doc) + + stored = _persist_summary(service, kind, doc) + + assert (stored["tenant_id"], stored["user_id"], stored["thread_id"], stored["id"]) == ( + "acme", + "u1", + thread_id, + summary_id, + ) + assert summaries_store.upserts == [stored] + assert doc == original, "the caller's dict is not rewritten" + + +VALID_IDS = {"user_id": "u1", "thread_id": "t1"} + + +@pytest.mark.parametrize( + ("kind", "user_id", "thread_id", "fields", "problem"), + [ + # The document names no owner, so the tenant is what is refused. + pytest.param("thread_summary", "u1", "t1", {"tenant_id": "other"}, "different tenant", id="thread-tenant"), + pytest.param("user_summary", "u1", "t1", {"tenant_id": "other"}, "different tenant", id="user-tenant"), + # The document names a valid owner and thread of its own, so what is refused is the argument. + pytest.param("thread_summary", "bad/id", "t1", VALID_IDS, "user_id", id="thread-owner"), + pytest.param("thread_summary", "u1 ", "t1", VALID_IDS, "user_id", id="thread-owner-space"), + pytest.param("thread_summary", "u1", "t1 ", VALID_IDS, "thread_id", id="thread-thread-space"), + pytest.param("user_summary", "bad/id", "t1", VALID_IDS, "user_id", id="user-owner"), + pytest.param("user_summary", "u1 ", "t1", VALID_IDS, "user_id", id="user-owner-space"), + ], +) +def test_a_summary_that_cannot_be_stored_is_refused_before_its_content_is_embedded( + kind: str, user_id: str, thread_id: str, fields: dict[str, Any], problem: str +) -> None: + llm, summaries_store = FakeLLMService([]), FakeStore() + service = _pipeline(FakeStore(), llm, summaries_store=summaries_store, tenant_id="acme") + doc = {"type": kind, "content": "Thread discussed retries.", "metadata": {"thread_ids": ["t1"]}, **fields} + + with pytest.raises(ValidationError, match=problem): + _persist_summary(service, kind, doc, user_id, thread_id) + + assert llm.embed_one_calls == [] and summaries_store.upserts == [] + + def test_generate_thread_and_user_summary_basic_shape() -> None: store = FakeStore() turns_store = FakeStore([_turn("We decided to add retries.")]) diff --git a/tests/unit/store/test_tenant_isolation.py b/tests/unit/store/test_tenant_isolation.py index 8e7d230..a499a8d 100644 --- a/tests/unit/store/test_tenant_isolation.py +++ b/tests/unit/store/test_tenant_isolation.py @@ -17,6 +17,7 @@ from azure.cosmos.agent_memory._container_routing import ContainerKey from azure.cosmos.agent_memory.aio.store import AsyncMemoryStore from azure.cosmos.agent_memory.exceptions import MemoryNotFoundError, ValidationError +from azure.cosmos.agent_memory.models import MemoryRecord from azure.cosmos.agent_memory.store import MemoryStore TENANT = "acme" @@ -342,6 +343,26 @@ async def test_upsert_memory_refuses_a_record_of_another_tenant(kind): assert not containers[MEMORIES].sent("upsert_item") +async def test_a_built_record_is_stored_in_the_tenant_of_the_store_unless_it_names_another(kind): + store, containers = _build(kind) + fact = { + "memory_type": "fact", + "id": "fact_" + "a" * 32, + "user_id": USER, + "content": "I like tea", + "content_hash": "a" * 32, + "prompt_id": "extract_memories.prompty", + "metadata": {"category": "other"}, + } + + await _call(store, "upsert_memory", MemoryRecord(**fact).to_cosmos_dict()) + with pytest.raises(ValidationError, match="different tenant"): + await _call(store, "upsert_memory", MemoryRecord(**fact, tenant_id=OTHER_TENANT).to_cosmos_dict()) + + (written,) = containers[MEMORIES].sent("upsert_item") + assert written["body"]["tenant_id"] == TENANT + + async def test_push_stamps_every_record_with_the_tenant(kind): store, containers = _build(kind) @@ -374,6 +395,16 @@ async def test_add_refuses_an_invalid_owner_before_embedding_or_writing(kind, ow assert not containers[MEMORIES].sent("upsert_item") +async def test_add_refuses_a_thread_ending_in_whitespace_before_embedding_or_writing(kind): + store, containers = _build(kind) + + with pytest.raises(ValidationError, match="thread_id"): + await _call(store, "add", user_id=USER, role="user", content="x", memory_type="fact", thread_id="t1 ") + + assert store._embeddings_client.generated == [] + assert not containers[MEMORIES].sent("upsert_item") + + @pytest.mark.parametrize("owner", [None, *INVALID_OWNERS]) async def test_upsert_memory_refuses_a_record_without_a_valid_owner(kind, owner): store, containers = _build(kind) diff --git a/tests/unit/test_cosmos_memory_client.py b/tests/unit/test_cosmos_memory_client.py index 0b8a373..9f68a58 100644 --- a/tests/unit/test_cosmos_memory_client.py +++ b/tests/unit/test_cosmos_memory_client.py @@ -4,6 +4,7 @@ import inspect import uuid +from contextlib import contextmanager from datetime import datetime, timezone from types import SimpleNamespace from unittest.mock import MagicMock, patch @@ -19,6 +20,7 @@ MemoryNotFoundError, ValidationError, ) +from azure.cosmos.agent_memory.processors import InProcessProcessor # --------------------------------------------------------------------------- # Helpers @@ -138,6 +140,43 @@ def test_a_memory_is_addressed_by_its_owner_not_its_thread(self, method): assert "thread_id" not in inspect.signature(getattr(CosmosMemoryClient, method)).parameters +class _CustomProcessor: + """A processor of its own: it reports no tenant.""" + + +class TestProcessorTenant: + @staticmethod + def _processor(tenant_id: str) -> InProcessProcessor: + """A processor over a real pipeline of ``tenant_id``.""" + return InProcessProcessor( + cosmos_container=MagicMock(), + turns_container=MagicMock(), + summaries_container=MagicMock(), + chat_client=MagicMock(), + embeddings_client=MagicMock(), + tenant_id=tenant_id, + ) + + def test_a_processor_of_another_tenant_is_refused(self): + with pytest.raises(ConfigurationError, match=rf"tenant '{DEFAULT_TENANT_ID}'.*tenant 'acme'"): + _make_client(tenant_id="acme", processor=self._processor(DEFAULT_TENANT_ID)) + + def test_a_processor_of_the_clients_tenant_is_used(self): + processor = self._processor("acme") + + assert _make_client(tenant_id="acme", processor=processor)._get_processor() is processor + + @pytest.mark.parametrize( + "processor", + [ + pytest.param(_CustomProcessor(), id="custom"), + pytest.param(InProcessProcessor(pipeline=MagicMock()), id="pipeline-double"), + ], + ) + def test_a_processor_that_reports_no_tenant_is_not_checked(self, processor): + assert _make_client(tenant_id="acme", processor=processor)._get_processor() is processor + + # =================================================================== # Injected embeddings / chat clients # =================================================================== @@ -397,6 +436,90 @@ def test_require_cosmos_before_connect(self): mem._require_cosmos() +class TestConnectCosmos: + CONTAINERS = ("memories", "memories_turns", "memories_summaries", "counter") + + @staticmethod + @contextmanager + def _serving(containers): + """Patch ``azure.cosmos`` so ``connect_cosmos`` finds ``containers`` by id; yields the Cosmos client.""" + cosmos_client = MagicMock() + cosmos_client.get_database_client.return_value.get_container_client.side_effect = containers.__getitem__ + cosmos = MagicMock(CosmosClient=MagicMock(return_value=cosmos_client)) + with patch.dict("sys.modules", {"azure.cosmos": cosmos}): + yield cosmos_client + + @staticmethod + def _connect(mem): + mem.connect_cosmos(endpoint="https://fake.documents.azure.com:443/", credential="fake-key") + + @staticmethod + def _assert_discarded(mem, cosmos_client): + """A failed connect closes the Cosmos client it opened and leaves ``mem`` unconnected.""" + cosmos_client.close.assert_called_once() + for attribute in ( + "_cosmos_client", + "_memories_container_client", + "_turns_container_client", + "_summaries_container_client", + "_counter_container_client", + "_store", + "_pipeline", + ): + assert getattr(mem, attribute) is None, attribute + with pytest.raises(CosmosNotConnectedError): + mem._require_cosmos() + + @pytest.mark.parametrize("earlier", CONTAINERS) + def test_a_container_with_the_earlier_key_is_refused(self, earlier): + containers = {name: _keyed_container(container_id=name) for name in self.CONTAINERS} + containers[earlier] = _keyed_container(EARLIER_KEY, container_id=earlier) + mem = _make_client() + + with self._serving(containers) as cosmos_client: + with pytest.raises( + CosmosOperationError, + match=( + rf"Failed to connect to Cosmos DB: container '{earlier}' has partition key " + r"\['/user_id', '/thread_id'\].*\['/tenant_id', '/user_id'\]" + ), + ): + self._connect(mem) + + self._assert_discarded(mem, cosmos_client) + + def test_a_container_that_does_not_exist_is_refused(self): + from azure.cosmos.exceptions import CosmosResourceNotFoundError + + containers = {name: _keyed_container(container_id=name) for name in self.CONTAINERS} + containers["counter"].read.side_effect = CosmosResourceNotFoundError(message="missing") + mem = _make_client() + + with self._serving(containers) as cosmos_client: + with pytest.raises( + CosmosOperationError, match="Failed to connect to Cosmos DB: container 'counter' does not exist" + ): + self._connect(mem) + + self._assert_discarded(mem, cosmos_client) + + def test_containers_keyed_by_tenant_and_user_connect_after_all_four_are_read(self): + containers = {name: _keyed_container(container_id=name) for name in self.CONTAINERS} + mem = _make_client() + + with self._serving(containers) as cosmos_client: + self._connect(mem) + + cosmos_client.close.assert_not_called() + assert mem._memories_container_client is containers["memories"] + assert mem._turns_container_client is containers["memories_turns"] + assert mem._summaries_container_client is containers["memories_summaries"] + assert mem._counter_container_client is containers["counter"] + # Each container is read for its key. The memories container is read once more, for its embedding dimensions. + for container in containers.values(): + container.read.assert_called() + + class TestUserAgent: def _connect_with_mock(self, **client_kwargs): mock_cosmos_cls = MagicMock() diff --git a/tests/unit/test_models.py b/tests/unit/test_models.py index 26da421..2d62b2c 100644 --- a/tests/unit/test_models.py +++ b/tests/unit/test_models.py @@ -755,11 +755,11 @@ def test_supersedes_ids_and_source_ids(self): class TestTenant: - def test_a_record_belongs_to_the_default_tenant_unless_it_names_one(self): + def test_a_record_belongs_to_no_tenant_until_it_is_written_unless_it_names_one(self): record = TurnRecord(user_id="u1", role="user", content="hello") - assert record.tenant_id == "default" - assert record.to_doc()["tenant_id"] == "default" + assert record.tenant_id is None + assert "tenant_id" not in record.to_doc() @pytest.mark.parametrize( ("memory_type", "kwargs"), diff --git a/tests/unit/test_partitioning.py b/tests/unit/test_partitioning.py index 3992f70..981749f 100644 --- a/tests/unit/test_partitioning.py +++ b/tests/unit/test_partitioning.py @@ -8,6 +8,7 @@ DEFAULT_TENANT_ID, MAX_OWNER_ID_BYTES, MAX_TENANT_ID_BYTES, + MAX_THREAD_ID_BYTES, OWNER_FILTER, PARTITION_KEY_PATHS, TENANT_FILTER, @@ -18,6 +19,7 @@ stamp_scope, tenant_parameters, validate_owner_id, + validate_thread_id, ) from azure.cosmos.agent_memory.exceptions import ValidationError @@ -32,15 +34,34 @@ "tab\there", 7, b"x", + # DEL, two C1 controls (NEL and APC) and the line and paragraph separators. They sit inside the value so that they + # are refused as control characters, not as whitespace at an end. + "a\x7fb", + "a\x85b", + "a\x9fb", + "a\u2028b", + "a\u2029b", + # Whitespace at either end: Cosmos DB refuses a document id that ends in it, and these ids appear in the ids of + # counters and summaries. + " a", + "a ", + "a\n", + "a\xa0", ] +# Joined by zero-width joiners, which are format characters, not controls. +FAMILY_EMOJI = "\U0001f468\u200d\U0001f469\u200d\U0001f467" + class TestResolveTenantId: def test_no_tenant_is_the_default_tenant(self) -> None: assert resolve_tenant_id() == DEFAULT_TENANT_ID == "default" assert resolve_tenant_id(None) == "default" - @pytest.mark.parametrize("tenant", ["acme", "Acme-Corp_2", "tenant:prod", "t" * MAX_TENANT_ID_BYTES, "société"]) + @pytest.mark.parametrize( + "tenant", + ["acme", "Acme-Corp_2", "tenant:prod", "t" * MAX_TENANT_ID_BYTES, "société", "a b", FAMILY_EMOJI], + ) def test_a_valid_tenant_is_returned_as_given(self, tenant: str) -> None: assert resolve_tenant_id(tenant) == tenant @@ -57,7 +78,18 @@ def test_the_byte_limit_counts_utf8_bytes_not_characters(self) -> None: class TestValidateOwnerId: @pytest.mark.parametrize( - "owner", ["alice", "agent:support-bot", "a@b.com", "user.name_1", "o" * MAX_OWNER_ID_BYTES, "société", "用户"] + "owner", + [ + "alice", + "agent:support-bot", + "a@b.com", + "user.name_1", + "o" * MAX_OWNER_ID_BYTES, + "société", + "用户", + "a b", + FAMILY_EMOJI, + ], ) def test_a_valid_owner_is_returned_as_given(self, owner: str) -> None: assert validate_owner_id(owner) == owner @@ -73,6 +105,24 @@ def test_the_byte_limit_counts_utf8_bytes_not_characters(self) -> None: validate_owner_id("é" * (MAX_OWNER_ID_BYTES // 2 + 1)) +class TestValidateThreadId: + @pytest.mark.parametrize( + "thread", ["t1", "chat:2026-01-01", "société", "a b", FAMILY_EMOJI, "t" * MAX_THREAD_ID_BYTES] + ) + def test_a_valid_thread_is_returned_as_given(self, thread: str) -> None: + assert validate_thread_id(thread) == thread + + @pytest.mark.parametrize("thread", [*INVALID_IDS, None, "t" * (MAX_THREAD_ID_BYTES + 1)]) + def test_an_invalid_thread_is_refused(self, thread: object) -> None: + with pytest.raises(ValidationError, match="thread_id"): + validate_thread_id(thread) + + @pytest.mark.parametrize("thread", ["t1 ", " t1", "t1\n", "t1\xa0"]) + def test_a_thread_with_whitespace_at_an_end_is_refused_with_that_reason(self, thread: str) -> None: + with pytest.raises(ValidationError, match="thread_id must not start or end with whitespace"): + validate_thread_id(thread) + + class TestTheKey: def test_the_partition_key_is_the_tenant_then_the_owner(self) -> None: assert partition_key_for("acme", "alice") == ["acme", "alice"] @@ -141,6 +191,20 @@ def test_a_record_with_an_unsupported_owner_is_refused(self) -> None: with pytest.raises(ValidationError, match="user_id"): stamp_scope({"id": "f1", "user_id": "a/b"}, "acme") + @pytest.mark.parametrize("thread", ["", "t1 ", "a/b", 7]) + def test_a_record_with_an_unsupported_thread_is_refused(self, thread: object) -> None: + with pytest.raises(ValidationError, match="thread_id"): + stamp_scope({"id": "f1", "user_id": "alice", "thread_id": thread}, "acme") + + @pytest.mark.parametrize("fields", [{}, {"thread_id": None}, {"thread_id": "t1"}]) + def test_a_record_may_have_no_thread_or_a_supported_one(self, fields: dict) -> None: + assert stamp_scope({"id": "f1", "user_id": "alice", **fields}, "acme") == { + "id": "f1", + "user_id": "alice", + "tenant_id": "acme", + **fields, + } + class TestPartitionKeyProblem: @staticmethod diff --git a/tests/unit/test_tenant_scope_guard.py b/tests/unit/test_tenant_scope_guard.py index da7c2a5..7dcc83d 100644 --- a/tests/unit/test_tenant_scope_guard.py +++ b/tests/unit/test_tenant_scope_guard.py @@ -1,14 +1,30 @@ -"""Tenant scope guard: no code path may filter on an owner without the tenant, or build a raw partition key. +"""Tenant scope guard: no code path may read records without the tenant, or build a raw partition key. A query that names ``c.user_id`` alone reads the same id in every tenant, and a hand-built ``[user_id, ...]`` key -addresses the wrong partition. These checks read the source, so a new query written without the tenant fails here -before it can leak. +addresses the wrong partition. These checks read the source with ``ast``, so a new query written without the tenant +fails here before it can leak. They are a safety net: what proves that one tenant cannot read another's records are the +behaviour tests of the store and the pipeline. + +In every source file the checks enforce that: + +* Each query carries the tenant filter in its own expression: ``OWNER_FILTER``, ``TENANT_FILTER``, SQL that reads + ``c.tenant_id = @...``, ``_QueryBuilder.build_where()``, a ``predicate``, or a variable assigned from one of these. + A parameter, a docstring, a comment or another query of the same function that mentions the tenant does not count. + A query is a string that selects ``FROM`` a container, or one that filters on ``user_id``. +* A ``predicate`` (a name or property ending in ``predicate``) is itself built from those filters, so the word cannot + carry an unscoped condition into a query. +* A ``_QueryBuilder`` is made with ``for_tenant``, which starts every WHERE clause with the tenant. +* A partition key is made with ``partition_key_for``, never written out as a list or a tuple. + +The checks find where the tenant filter is, not whether the rest of a WHERE clause keeps it: an ``OR`` that widens +one is for the behaviour tests to catch. """ from __future__ import annotations import ast import re +from collections.abc import Callable, Iterator from pathlib import Path import pytest @@ -21,38 +37,588 @@ if "prompts" not in path.parts and path.name != "_partitioning.py" ) -# A function that filters on the owner must be tenant-aware: it names the tenant, the shared filters, or the key helper. -TENANT_AWARE = re.compile(r"tenant|OWNER_FILTER|partition_key_for", re.IGNORECASE) -OWNER_FILTER_USE = re.compile(r"""c\.user_id|["']c\.user_id["']""") +# A query selects from a container (SQL keywords are case-insensitive). A string that filters on the owner counts as one +# too, since it can be the piece of a query that names the owner. +SELECT_FROM = re.compile(r"\bSELECT\b[\s\S]*?\bFROM\s+\w+", re.IGNORECASE) +OWNER_IN_SQL = re.compile(r"\.user_id\s*=\s*@\w+") +# A string can only be a query if one of its lines has this. Reading the source of a string splits the whole file, so +# only these strings are read. +QUERY_LINE = re.compile(r"select|\.user_id", re.IGNORECASE) +# A ``\n`` written inside a literal separates the words of the SQL like a space does. +ESCAPED_SPACE = re.compile(r"\\[nrt]") +# SQL that filters on the tenant, whatever the alias: ``c.tenant_id = @tenant_id``. +TENANT_IN_SQL = re.compile(r"\.tenant_id\s*=\s*@\w+") +TENANT_FILTERS = frozenset({"OWNER_FILTER", "TENANT_FILTER"}) + +FUNCTIONS = (ast.FunctionDef, ast.AsyncFunctionDef) +SCOPES = (*FUNCTIONS, ast.Lambda, ast.Module) + +Check = Callable[[str], list[tuple[int, str]]] + + +def _is_string(node: ast.AST | None) -> bool: + """A string expression: a literal, an f-string, or a ``+`` chain with one of those in it.""" + if isinstance(node, ast.Constant): + return isinstance(node.value, str) + if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add): + return _is_string(node.left) or _is_string(node.right) + return isinstance(node, ast.JoinedStr) + + +def _called(call: ast.Call) -> str: + """The name a call goes by: ``f`` for ``f()`` and ``g`` for ``a.g()``.""" + if isinstance(call.func, ast.Name): + return call.func.id + return call.func.attr if isinstance(call.func, ast.Attribute) else "" + + +def _own_nodes(scope: ast.AST) -> Iterator[ast.AST]: + """The nodes of ``scope`` without those inside the functions defined in it.""" + pending = list(ast.iter_child_nodes(scope)) + while pending: + node = pending.pop() + yield node + if not isinstance(node, SCOPES): + pending.extend(ast.iter_child_nodes(node)) + + +def _assignments(node: ast.AST) -> Iterator[tuple[ast.Name | ast.Attribute, ast.expr | None, int | None]]: + """The names and attributes an assignment binds, each with its value and its place when it is unpacked. + + An augmented assignment (``predicate += " AND ..."``) is left out: it adds to a value assigned elsewhere. + """ + if isinstance(node, ast.Assign): + targets, value = node.targets, node.value + elif isinstance(node, ast.AnnAssign): + targets, value = [node.target], node.value + else: + return + for target in targets: + places = enumerate(target.elts) if isinstance(target, (ast.Tuple, ast.List)) else [(None, target)] + for place, element in places: + if isinstance(element, (ast.Name, ast.Attribute)): + yield element, value, place + + +def _name_of(target: ast.Name | ast.Attribute) -> str: + return target.id if isinstance(target, ast.Name) else target.attr + + +def _bindings(scope: ast.AST, name: str) -> list[tuple[ast.expr | None, int | None]]: + """What ``name`` is bound to in ``scope``: the values assigned to it and their places, ``None`` for a parameter.""" + bound: list[tuple[ast.expr | None, int | None]] = [] + if isinstance(scope, (*FUNCTIONS, ast.Lambda)): + arguments = scope.args + parameters = [*arguments.posonlyargs, *arguments.args, *arguments.kwonlyargs, arguments.vararg, arguments.kwarg] + bound += [(None, None) for parameter in parameters if parameter and parameter.arg == name] + for node in _own_nodes(scope): + bound += [ + (value, place) + for target, value, place in _assignments(node) + if isinstance(target, ast.Name) and target.id == name + ] + return bound + + +class _Source: + """A parsed source file, with what the checks look up in it.""" + + def __init__(self, text: str) -> None: + self.text = text + self.tree = ast.parse(text) + self.parents = {child: parent for parent in ast.walk(self.tree) for child in ast.iter_child_nodes(parent)} + self.query_lines = {number for number, line in enumerate(text.split("\n"), 1) if QUERY_LINE.search(line)} + self.functions: dict[str, list[ast.FunctionDef | ast.AsyncFunctionDef]] = {} + for node in ast.walk(self.tree): + if isinstance(node, FUNCTIONS): + self.functions.setdefault(node.name, []).append(node) + + def snippet(self, node: ast.AST) -> str: + return " ".join((ast.get_source_segment(self.text, node) or "").split())[:80] + + def scope_of(self, node: ast.AST) -> ast.AST: + """The function, lambda or module whose names ``node`` sees.""" + while not isinstance(node, SCOPES): + node = self.parents[node] + return node + + def queries(self) -> list[ast.expr]: + """The outermost string expressions that read records, leaving out docstrings and other bare strings.""" + found: list[ast.expr] = [] + for node in ast.walk(self.tree): + parent = self.parents.get(node) + if not _is_string(node) or _is_string(parent) or isinstance(parent, ast.Expr): + continue + if self.query_lines.isdisjoint(range(node.lineno, node.end_lineno + 1)): + continue + text = ESCAPED_SPACE.sub(" ", ast.get_source_segment(self.text, node) or "") + if SELECT_FROM.search(text) or OWNER_IN_SQL.search(text): + found.append(node) + return sorted(found, key=lambda node: (node.lineno, node.col_offset)) + + def carries( + self, node: ast.expr | None, scope: ast.AST, place: int | None = None, seen: frozenset = frozenset() + ) -> bool: + """Whether the SQL that ``node`` evaluates to filters on the tenant, judged from its own expression. + + ``place`` picks one value out of a tuple (``predicate, parameters = ...``). A name is judged by everything + assigned to it in its function or the module, and a call to a helper of this file by what the helper returns. + """ + if isinstance(node, ast.Constant): + return isinstance(node.value, str) and TENANT_IN_SQL.search(node.value) is not None + if isinstance(node, ast.JoinedStr): + parts = (part.value if isinstance(part, ast.FormattedValue) else part for part in node.values) + return any(self.carries(part, scope, None, seen) for part in parts) + if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add): + return self.carries(node.left, scope, None, seen) or self.carries(node.right, scope, None, seen) + if isinstance(node, ast.Tuple) and place is not None: + return place < len(node.elts) and self.carries(node.elts[place], scope, None, seen) + if isinstance(node, ast.Name): + return node.id in TENANT_FILTERS or self._name_carries(node.id, scope, seen) + if isinstance(node, ast.Attribute): + return node.attr in TENANT_FILTERS or node.attr.endswith("predicate") + if isinstance(node, ast.Call): + return self._call_carries(node, place, seen) + return False + + def _name_carries(self, name: str, scope: ast.AST, seen: frozenset) -> bool: + while True: + bound = _bindings(scope, name) + if bound: + key = (id(scope), name) + # A value built on its own name adds to what the other assignments carry. + return key in seen or all(self.carries(value, scope, place, seen | {key}) for value, place in bound) + if isinstance(scope, ast.Module): + return False + scope = self.scope_of(self.parents[scope]) + + def _call_carries(self, call: ast.Call, place: int | None, seen: frozenset) -> bool: + name = _called(call) + if name == "build_where" or name.endswith("predicate"): + return True + helpers = self.functions.get(name, []) + return bool(helpers) and all(self._returns_carry(helper, place, seen) for helper in helpers) + + def _returns_carry(self, function: ast.AST, place: int | None, seen: frozenset) -> bool: + if id(function) in seen: + return False + returned = [node.value for node in _own_nodes(function) if isinstance(node, ast.Return)] + return bool(returned) and all(self.carries(value, function, place, seen | {id(function)}) for value in returned) + + +def unscoped_queries(source: str) -> list[tuple[int, str]]: + """The queries that do not filter on the tenant in their own expression, as ``(line, snippet)``.""" + src = _Source(source) + return [ + (query.lineno, src.snippet(query)) for query in src.queries() if not src.carries(query, src.scope_of(query)) + ] + + +def unscoped_predicates(source: str) -> list[tuple[int, str]]: + """The predicates that are not built from the tenant filter, as ``(line, snippet)``. + + A predicate is a name or attribute assigned, or a function or property defined, with a name ending in + ``predicate``. A query takes one in place of the tenant filter, so each must hold that filter itself. + """ + src = _Source(source) + found: set[tuple[int, str]] = set() + for node in ast.walk(src.tree): + for target, value, place in _assignments(node): + if _name_of(target).endswith("predicate") and not src.carries(value, src.scope_of(node), place): + found.add((node.lineno, src.snippet(node))) + if isinstance(node, FUNCTIONS) and node.name.endswith("predicate"): + for returned in (child for child in _own_nodes(node) if isinstance(child, ast.Return)): + if not src.carries(returned.value, node): + found.add((returned.lineno, src.snippet(returned))) + return sorted(found) + + +def unscoped_query_builders(source: str) -> list[tuple[int, str]]: + """The ``_QueryBuilder``s made without ``for_tenant``, as ``(line, snippet)``. + + ``build_where()`` counts as the tenant filter because ``for_tenant`` starts every builder with it. + """ + src = _Source(source) + calls = [node for node in ast.walk(src.tree) if isinstance(node, ast.Call) and _called(node) == "_QueryBuilder"] + return sorted((call.lineno, src.snippet(call)) for call in calls) + + +def _is_partition_key(target: ast.AST) -> bool: + if isinstance(target, ast.Name): + name = target.id + elif isinstance(target, ast.Attribute): + name = target.attr + elif isinstance(target, ast.Subscript) and isinstance(target.slice, ast.Constant): + name = str(target.slice.value) + else: + return False + return "partition_key" in name + + +def _partition_key_values(node: ast.AST) -> Iterator[ast.expr]: + """What ``node`` sets as a partition key: ``partition_key=...``, ``partition_key = ...`` or a dict entry.""" + if isinstance(node, ast.keyword): + if node.arg and "partition_key" in node.arg: + yield node.value + elif isinstance(node, (ast.Assign, ast.AnnAssign)) and node.value is not None: + targets = node.targets if isinstance(node, ast.Assign) else [node.target] + if any(_is_partition_key(target) for target in targets): + yield node.value + elif isinstance(node, ast.Dict): + for key, value in zip(node.keys, node.values): + if isinstance(key, ast.Constant) and "partition_key" in str(key.value): + yield value + + +def _is_hand_built(value: ast.expr) -> bool: + """A key written out as a list or a tuple, or made by ``list(...)`` or ``tuple(...)``, also in a conditional.""" + if isinstance(value, ast.IfExp): + return _is_hand_built(value.body) or _is_hand_built(value.orelse) + if isinstance(value, ast.BoolOp): + return any(_is_hand_built(operand) for operand in value.values) + if isinstance(value, ast.Call): + return isinstance(value.func, ast.Name) and value.func.id in {"list", "tuple"} + return isinstance(value, (ast.List, ast.Tuple)) + + +def hand_built_partition_keys(source: str) -> list[tuple[int, str]]: + """The partition keys written out as a list or a tuple instead of ``partition_key_for``, as ``(line, snippet)``.""" + src = _Source(source) + values = (value for node in ast.walk(src.tree) for value in _partition_key_values(node)) + return sorted((value.lineno, src.snippet(value)) for value in values if _is_hand_built(value)) + + +CHECKS: tuple[Check, ...] = ( + unscoped_queries, + unscoped_predicates, + unscoped_query_builders, + hand_built_partition_keys, +) + +def _relative(path: Path) -> str: + return path.relative_to(ROOT).as_posix() -def _functions(tree: ast.AST): - for node in ast.walk(tree): - if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)): - yield node +def _assert_nothing_flagged(path: Path, check: Check, advice: str) -> None: + found = check(path.read_text(encoding="utf-8")) + assert not found, advice + "".join(f"\n {_relative(path)}:{line}: {snippet}" for line, snippet in found) -def _owner_filters_without_the_tenant() -> list[str]: - found: list[str] = [] - for path in SOURCES: - text = path.read_text() - tree = ast.parse(text) - for function in _functions(tree): - source = ast.get_source_segment(text, function) or "" - if OWNER_FILTER_USE.search(source) and not TENANT_AWARE.search(source): - found.append(f"{path.relative_to(ROOT)}:{function.lineno} {function.name}") - return found +@pytest.mark.parametrize("path", SOURCES, ids=_relative) +def test_every_query_filters_on_the_tenant(path: Path) -> None: + advice = "a query must carry the tenant filter itself: use OWNER_FILTER, TENANT_FILTER or _QueryBuilder.for_tenant" + _assert_nothing_flagged(path, unscoped_queries, advice) -def test_every_function_that_filters_on_the_owner_is_tenant_aware() -> None: - assert _owner_filters_without_the_tenant() == [] +@pytest.mark.parametrize("path", SOURCES, ids=_relative) +def test_every_predicate_is_built_from_the_tenant_filter(path: Path) -> None: + _assert_nothing_flagged(path, unscoped_predicates, "a predicate must be built from OWNER_FILTER or TENANT_FILTER") -@pytest.mark.parametrize("path", SOURCES, ids=lambda p: str(p.relative_to(ROOT))) + +@pytest.mark.parametrize("path", SOURCES, ids=_relative) +def test_every_query_builder_starts_from_the_tenant(path: Path) -> None: + _assert_nothing_flagged(path, unscoped_query_builders, "make a _QueryBuilder with _QueryBuilder.for_tenant") + + +@pytest.mark.parametrize("path", SOURCES, ids=_relative) def test_no_partition_key_is_built_by_hand(path: Path) -> None: - text = path.read_text() - by_hand = re.findall(r"partition_key\s*=\s*\[", text) - assert by_hand == [], f"{path.relative_to(ROOT)} builds a partition key list by hand; use partition_key_for" + _assert_nothing_flagged(path, hand_built_partition_keys, "build a partition key with partition_key_for") + + +def test_the_checks_see_the_queries_of_the_sources() -> None: + """Without queries to look at, the checks above would pass by finding nothing.""" + assert sum(len(_Source(path.read_text(encoding="utf-8")).queries()) for path in SOURCES) >= 30 + + +def _marked(source: str) -> list[int]: + """The lines of a fixture that end in ``# flagged``.""" + return [number for number, line in enumerate(source.splitlines(), start=1) if line.endswith("# flagged")] + + +# Each source is run through a check, which must flag the lines marked ``# flagged`` and no others. +FLAGGED = [ + pytest.param( + unscoped_queries, + ''' +def facts(container, tenant_id, user_id): + """Read the facts of ``user_id`` in the tenant ``tenant_id``.""" + # The tenant is applied by the caller. + return container.query_items( + query=f"SELECT * FROM c WHERE c.user_id = @user_id", # flagged + parameters=[{"name": "@user_id", "value": user_id}], + ) +''', + id="query: the tenant is only in a parameter, a docstring and a comment", + ), + pytest.param( + unscoped_queries, + """ +def reads(container, user_id): + scoped = f"SELECT * FROM c WHERE {OWNER_FILTER} AND c.type = 'turn'" + unscoped = "SELECT * FROM c WHERE c.user_id = @user_id AND c.type = 'fact'" # flagged + return container.query_items(query=scoped), container.query_items(query=unscoped) +""", + id="query: a scoped query does not scope another one in the function", + ), + pytest.param( + unscoped_queries, + """ +QUERY = "SELECT * FROM memories m WHERE m.user_id = @user_id" # flagged +""", + id="query: another alias", + ), + pytest.param( + unscoped_queries, + """ +def reads(extra): + first = "SELECT * FROM c WHERE c.user_id = @user_id" + extra # flagged + second = "SELECT * FROM c " + "WHERE c.user_id = @user_id" # flagged + return first, second +""", + id="query: concatenation", + ), + pytest.param( + unscoped_queries, + """ +QUERY = "select * from c where c.user_id = @user_id" # flagged +""", + id="query: lower case SQL", + ), + pytest.param( + unscoped_queries, + """ +QUERY = "SELECT c.id\\nFROM c WHERE c.type = 'fact'" # flagged +""", + id="query: an escaped newline in the literal", + ), + pytest.param( + unscoped_queries, + """ +def owner_clause(): + return "c.user_id = @user_id AND c.type = 'fact'" # flagged +""", + id="query: a piece that filters on the owner", + ), + pytest.param( + unscoped_queries, + """ +QUERY = "SELECT * FROM c WHERE {OWNER_FILTER} AND c.type = 'turn'" # flagged +""", + id="query: OWNER_FILTER in a string that is not an f-string", + ), + pytest.param( + unscoped_queries, + """ +def reads(predicate): + where = " WHERE c.type = 'fact'" + first = f"SELECT * FROM c{where}" # flagged + second = f"SELECT * FROM c WHERE {predicate}" # flagged + return first, second +""", + id="query: a variable is judged by its assignments and a parameter is not trusted", + ), + pytest.param( + unscoped_predicates, + """ +def reads(user_id): + predicate = "c.user_id = @user_id" # flagged + owner_predicate = "c.user_id = @user_id AND c.type = 'fact'" # flagged + return predicate, owner_predicate +""", + id="predicate: assigned from a user-only filter", + ), + pytest.param( + unscoped_predicates, + """ +class Scope: + @property + def predicate(self): + return "c.user_id = @user_id" # flagged +""", + id="predicate: a property that returns a user-only filter", + ), + pytest.param( + unscoped_predicates, + """ +class Scope: + predicate: str # flagged + + def __init__(self, predicate): + self.predicate = predicate # flagged +""", + id="predicate: a field or an attribute set from a parameter", + ), + pytest.param( + unscoped_predicates, + """ +def in_force(): + return "c.type = 'fact'", [] + + +def reads(): + predicate, parameters = in_force() # flagged + return predicate, parameters +""", + id="predicate: unpacked from a helper that returns an unscoped filter", + ), + pytest.param( + unscoped_query_builders, + """ +def reads(user_id): + qb = _QueryBuilder() # flagged + qb.add_filter("c.user_id", "@user_id", user_id) + return f"SELECT * FROM c{qb.build_where()}" +""", + id="builder: made without for_tenant", + ), + pytest.param( + hand_built_partition_keys, + """ +def reads(container, tenant_id, user_id, parts): + container.read_item(item="a", partition_key=[tenant_id, user_id]) # flagged + container.read_item(item="b", partition_key=(tenant_id, user_id)) # flagged + container.read_item(item="c", partition_key=list(parts)) # flagged + container.read_item(item="d", partition_key=parts if user_id else [tenant_id]) # flagged +""", + id="partition key: a list, a tuple, list() and a conditional", + ), + pytest.param( + hand_built_partition_keys, + """ +def reads(tenant_id, user_id): + partition_key = [tenant_id, user_id] # flagged + options = {"partition_key": [tenant_id, user_id]} # flagged + options["partition_key"] = (tenant_id, user_id) # flagged + return partition_key, options +""", + id="partition key: assigned, in a dict or under a key", + ), +] + +SCOPED = [ + pytest.param( + """ +def turns(container): + return container.query_items(query=f"SELECT * FROM c WHERE {OWNER_FILTER} AND c.type = 'turn'") +""", + id="OWNER_FILTER", + ), + pytest.param( + """ +QUERY = "SELECT * FROM c WHERE c.tenant_id = @tenant_id AND c.user_id = @user_id" +""", + id="the tenant and owner filters written out", + ), + pytest.param( + """ +QUERY = "SELECT * FROM memories m WHERE m.tenant_id = @tenant_id AND m.user_id = @user_id" +""", + id="another alias", + ), + pytest.param( + """ +def reads(qb): + first = f"SELECT * FROM c{qb.build_where()}" + second = f"SELECT * FROM c WHERE {TENANT_FILTER}" + return first, second +""", + id="build_where() and TENANT_FILTER", + ), + pytest.param( + """ +def reads(scope): + return f"SELECT * FROM c WHERE {scope.predicate} AND c.type = @type" +""", + id="the predicate of a scope", + ), + pytest.param( + """ +def reads(): + first = "SELECT * FROM c WHERE " + OWNER_FILTER + " ORDER BY c._ts" + second = ( + "SELECT TOP 5 * FROM c " + f"WHERE {OWNER_FILTER} AND c.type = 'turn' " + "ORDER BY c.created_at DESC" + ) + return first, second +""", + id="concatenation and adjacent literals", + ), + pytest.param( + """ +def reads(qb): + where = qb.build_where() + return f"SELECT * FROM c{where}" +""", + id="a WHERE clause held in a variable", + ), + pytest.param( + """ +def reads(since): + query_predicate = OWNER_FILTER + if since: + query_predicate += " AND c.created_at > @since" + return f"SELECT * FROM c WHERE {query_predicate}" +""", + id="a predicate held in a variable and narrowed", + ), + pytest.param( + """ +class Scope: + @property + def predicate(self): + return OWNER_FILTER + + +def in_force(scope): + predicate = f"{scope.predicate} AND c.type = @type" + return predicate, [] + + +def reads(scope): + predicate, parameters = in_force(scope) + return f"SELECT * FROM c WHERE {predicate}", parameters +""", + id="a predicate from a property and a helper", + ), + pytest.param( + ''' +def reads(container, tenant_id, user_id, count): + """Runs SELECT * FROM c WHERE c.user_id = @user_id, but only in this sentence.""" + qb = _QueryBuilder.for_tenant(tenant_id, user_id) + container.patch_item( + item="a", + partition_key=partition_key_for(tenant_id, user_id), + filter_predicate=f"FROM c WHERE c.n < {count}", + ) + return qb +''', + id="a docstring, a patch condition and for_tenant", + ), + pytest.param( + """ +def reads(container, tenant_id, user_id, key): + partition_key = PartitionKey(path=list(PARTITION_KEY_PATHS), kind="MultiHash") + options = {"partition_key": key} + options["partition_key"] = key + container.read_item(item="a", partition_key=partition_key_for(tenant_id, user_id)) + container.read_item(item="b", partition_key=self._key) + container.query_items(query=q, partition_key=None) +""", + id="partition keys from the helper, a name, an attribute and None", + ), +] + + +@pytest.mark.parametrize(("check", "source"), FLAGGED) +def test_the_checks_flag_exactly_the_marked_lines(check: Check, source: str) -> None: + assert [line for line, _ in check(source)] == _marked(source) + + +@pytest.mark.parametrize("source", SCOPED) +def test_scoped_code_is_not_flagged(source: str) -> None: + assert {check.__name__: check(source) for check in CHECKS} == {check.__name__: [] for check in CHECKS} def test_containers_are_created_with_the_tenant_and_owner_key() -> None: From d6a4fb1e7e77811e248dcd3aa1c8cb18e3e3f745 Mon Sep 17 00:00:00 2001 From: Aayush Kataria Date: Tue, 17 Nov 2026 19:46:59 -0800 Subject: [PATCH 4/4] Resolving comments --- Docs/concepts.md | 4 +-- Docs/design_patterns.md | 2 +- Docs/operations.md | 2 +- Docs/public_api.md | 10 +++--- README.md | 4 +-- .../cosmos/agent_memory/_base/base_client.py | 24 ++++++++++---- azure/cosmos/agent_memory/_partitioning.py | 31 +++++++++++++++++-- .../agent_memory/aio/processors/inprocess.py | 18 ++++++++--- .../agent_memory/aio/services/pipeline.py | 12 +++---- .../agent_memory/aio/store/memory_store.py | 3 +- .../agent_memory/processors/inprocess.py | 18 ++++++++--- .../cosmos/agent_memory/services/pipeline.py | 14 ++++----- .../cosmos/agent_memory/store/memory_store.py | 3 +- tests/unit/aio/processors/test_inprocess.py | 22 ++++++++++--- .../services/test_tenant_isolation_async.py | 19 +++++++++++- tests/unit/aio/test_cosmos_memory_client.py | 5 ++- tests/unit/function_app/test_change_feed.py | 1 + tests/unit/processors/test_inprocess.py | 24 +++++++++++--- tests/unit/services/test_pipeline_service.py | 21 ++++++++++++- tests/unit/store/test_tenant_isolation.py | 10 ++++++ tests/unit/test_cosmos_memory_client.py | 25 ++++++++++++++- tests/unit/test_partitioning.py | 3 ++ 22 files changed, 218 insertions(+), 57 deletions(-) diff --git a/Docs/concepts.md b/Docs/concepts.md index 14f74e4..b92afef 100644 --- a/Docs/concepts.md +++ b/Docs/concepts.md @@ -33,9 +33,9 @@ Every record lives in the logical partition `[tenant_id, user_id]`: the `memorie `tenant_id` is not an access-control boundary. It separates data inside the same containers, so anyone who can read the Cosmos DB account's data can read every tenant. For hard isolation use separate databases or accounts, and Azure RBAC to control who reaches them. -A record id is unique per owner across all of the owner's threads. A tenant id, an owner id and a `thread_id` must each be a non-empty string of at most 256 UTF-8 bytes that does not start or end with whitespace and has no `/`, `\`, `?`, `#` or control characters (DEL, U+0080-U+009F and the line and paragraph separators included), because they appear in Cosmos DB document ids, which cannot end in a space or newline. A value that breaks these rules raises `ValidationError` when the client writes it. A query that names the owner reads one partition (a keyword search is the exception, see [Keyword search and partition scope](#keyword-search-and-partition-scope)); a read where `user_id` is optional and left out, such as `get_memories()`, covers every owner in the client's tenant, across partitions. +A record id is unique per owner across all of the owner's threads. A tenant id, an owner id and a `thread_id` must each be a non-empty string of at most 256 UTF-8 bytes that does not start or end with whitespace and has no `/`, `\`, `?`, `#` or control characters (DEL, U+0080-U+009F, the line and paragraph separators and lone surrogates included), because they appear in Cosmos DB document ids, which cannot end in a space or newline. A value that breaks these rules raises `ValidationError` when the client buffers or writes it. A query that names the owner reads one partition (a keyword search is the exception, see [Keyword search and partition scope](#keyword-search-and-partition-scope)); a read where `user_id` is optional and left out, such as `get_memories()`, covers every owner in the client's tenant, across partitions. -Each owner's partition `[tenant_id, user_id]` can hold up to 20 GB of data and 10,000 RU/s, the Cosmos DB limits of a logical partition. A deployment with one tenant has the same `tenant_id` (`"default"`) at the first level of every key, which is fine: the hierarchical key spreads data by `user_id`. One very busy owner, such as one agent id shared by every user, is bounded by those per-partition limits, so spread such a workload over several ids. +Each owner's partition `[tenant_id, user_id]` can hold up to 20 GB of data and 10,000 RU/s, the Cosmos DB limits of a logical partition. On a serverless account a physical partition handles up to 5,000 RU/s ([Azure Cosmos DB serverless](https://learn.microsoft.com/azure/cosmos-db/serverless)), so that is the most one owner can use there. A deployment with one tenant has the same `tenant_id` (`"default"`) at the first level of every key, which is fine: the hierarchical key spreads data by `user_id`. One very busy owner, such as one agent id shared by every user, is bounded by those per-partition limits, so spread such a workload over several ids. A container's partition key cannot be changed in place, so a deployment whose containers have the earlier `[/user_id, /thread_id]` key must recreate them (and `leases`) and existing data is not migrated: the README's [migration notes](../README.md#migration-notes) give the steps in order. `connect_cosmos()` reads the metadata of `memories`, `memories_turns`, `memories_summaries` and `counter` (four reads) and raises `CosmosOperationError`, naming the container, when one is missing or not keyed `[/tenant_id, /user_id]`; the client is closed again on failure. `create_memory_store()` creates what is missing and then makes the same check. The sync client's constructor calls it when it is given an endpoint, but the async constructor does no I/O, so connect an async client with `await client.connect_cosmos()` or `await client.create_memory_store()`. `validate_topology()` remains the explicit diagnostic. A container with the earlier key would take writes but read back empty, which is why it is refused. diff --git a/Docs/design_patterns.md b/Docs/design_patterns.md index e46ece6..0744790 100644 --- a/Docs/design_patterns.md +++ b/Docs/design_patterns.md @@ -539,7 +539,7 @@ await mem.upsert_memory( facts = await mem.search_cosmos("refund limits", user_id=AGENT, memory_types=["fact"], top_k=3) ``` -Everything an owner knows sits in one partition, and Cosmos DB limits a logical partition to 20 GB of data and 10,000 RU/s. Keep each user's memories under that user's id and put only what belongs to the agent itself under the agent's, so that no single owner, such as an agent shared by many users, outgrows those limits. If one agent id would carry the load of every user, spread it over several ids. +Everything an owner knows sits in one partition, and Cosmos DB limits a logical partition to 20 GB of data and 10,000 RU/s (5,000 RU/s on a serverless account). Keep each user's memories under that user's id and put only what belongs to the agent itself under the agent's, so that no single owner, such as an agent shared by many users, outgrows those limits. If one agent id would carry the load of every user, spread it over several ids. --- diff --git a/Docs/operations.md b/Docs/operations.md index 3cff27e..7b176f6 100644 --- a/Docs/operations.md +++ b/Docs/operations.md @@ -33,7 +33,7 @@ Function-app threshold knobs (`THREAD_SUMMARY_EVERY_N`, `FACT_EXTRACTION_EVERY_N ## Tenants -The tenant is not a setting. A client takes `tenant_id` as a constructor argument (default `"default"`), and the Function App processes each turn in the tenant stored on it, so one deployment serves every tenant of the database. Each owner's partition `[tenant_id, user_id]` can hold up to 20 GB and 10,000 RU/s, so spread one very busy owner, such as one agent id shared by every user, over several ids. See [Tenants and Owners](concepts.md#tenants-and-owners). +The tenant is not a setting. A client takes `tenant_id` as a constructor argument (default `"default"`), and the Function App processes each turn in the tenant stored on it, so one deployment serves every tenant of the database. Each owner's partition `[tenant_id, user_id]` can hold up to 20 GB and 10,000 RU/s (5,000 RU/s on a serverless account), so spread one very busy owner, such as one agent id shared by every user, over several ids. See [Tenants and Owners](concepts.md#tenants-and-owners). ## Reconcile, procedure and extraction knobs diff --git a/Docs/public_api.md b/Docs/public_api.md index 0fe2907..a642f7f 100644 --- a/Docs/public_api.md +++ b/Docs/public_api.md @@ -21,9 +21,9 @@ ### Memory CRUD -`update_cosmos`, `delete_memory`, `delete_turn`, `add_tags`, `remove_tags` and `get_memory_history` find a record by its owner (`user_id`) and need no `thread_id`: `thread_id` is a plain field, not part of the partition key. A `user_id` or `thread_id` that breaks the identifier rules in [Tenants and Owners](concepts.md#tenants-and-owners) (such as one that ends in whitespace) raises `ValidationError` when the client writes it. +`update_cosmos`, `delete_memory`, `delete_turn`, `add_tags`, `remove_tags` and `get_memory_history` find a record by its owner (`user_id`) and need no `thread_id`: `thread_id` is a plain field, not part of the partition key. A `user_id` or `thread_id` that breaks the identifier rules in [Tenants and Owners](concepts.md#tenants-and-owners) (such as one that ends in whitespace) raises `ValidationError` when the client buffers or writes it. -- `add_local(user_id, role, content, memory_type='turn', agent_id=None, metadata=None, thread_id=None, tags=None, ttl=None, salience=None) -> None` - append a memory to the local buffer. `thread_id` is required when `memory_type='turn'`. +- `add_local(user_id, role, content, memory_type='turn', agent_id=None, metadata=None, thread_id=None, tags=None, ttl=None, salience=None) -> None` - append a memory to the local buffer. `thread_id` is required when `memory_type='turn'`. A `user_id` or `thread_id` that breaks the identifier rules raises `ValidationError`, so a record that could never be written is not buffered. - `get_local(memory_id=None, user_id=None, role=None, memory_types=None) -> list[dict]` - filter local buffered memories. - `update_local(memory_id, content=None, role=None, memory_type=None, metadata=None) -> None` - update a local buffered memory. - `delete_local(memory_id) -> None` - remove a local buffered memory. @@ -106,7 +106,7 @@ Local-buffer methods remain synchronous in-memory operations; Cosmos, retrieval, ### Memory CRUD -- `add_local(user_id, role, content, memory_type='turn', agent_id=None, metadata=None, thread_id=None, tags=None, ttl=None, salience=None) -> None` - append a memory to the local buffer. `thread_id` is required when `memory_type='turn'`. +- `add_local(user_id, role, content, memory_type='turn', agent_id=None, metadata=None, thread_id=None, tags=None, ttl=None, salience=None) -> None` - append a memory to the local buffer. `thread_id` is required when `memory_type='turn'`. A `user_id` or `thread_id` that breaks the identifier rules raises `ValidationError`, so a record that could never be written is not buffered. - `get_local(memory_id=None, user_id=None, role=None, memory_types=None) -> list[dict]` - filter local buffered memories. - `update_local(memory_id, content=None, role=None, memory_type=None, metadata=None) -> None` - update a local buffered memory. - `delete_local(memory_id) -> None` - remove a local buffered memory. @@ -208,7 +208,7 @@ Credentials without a fixed format, such as `password: hunter2` typed into a cha ## Extension Points - `MemoryStoreProtocol` (`azure.cosmos.agent_memory.services`): persistence primitives (`query`, `read_item`, `upsert_memory`, `mark_superseded`) consumed by `PipelineService`. `AsyncPipelineService` takes an `AsyncMemoryStore`; there is no async protocol. -- `MemoryProcessor` (`azure.cosmos.agent_memory.processors`) and `AsyncMemoryProcessor` (`azure.cosmos.agent_memory.aio.processors`): the processing backend behind the `processor` argument, with `process_thread`, `process_extract_memories`, `process_extract_episodes`, `process_thread_summary`, `process_user_summary`, `process_reconcile`, `generate_user_summary`, `synthesize_procedural` and `close`. `InProcessProcessor` / `AsyncInProcessProcessor` run the pipeline in your process; `DurableFunctionProcessor` / `AsyncDurableFunctionProcessor` leave it to the Function App, so their methods are no-ops. An in-process processor works in one tenant and exposes it as a read-only `tenant_id`; a client raises `ConfigurationError` when its `processor` works in another tenant than its own `tenant_id`, so build the processor with the same `tenant_id`, or omit `processor` so the client builds its own. +- `MemoryProcessor` (`azure.cosmos.agent_memory.processors`) and `AsyncMemoryProcessor` (`azure.cosmos.agent_memory.aio.processors`): the processing backend behind the `processor` argument, with `process_thread`, `process_extract_memories`, `process_extract_episodes`, `process_thread_summary`, `process_user_summary`, `process_reconcile`, `generate_user_summary`, `synthesize_procedural` and `close`. `InProcessProcessor` / `AsyncInProcessProcessor` run the pipeline in your process; `DurableFunctionProcessor` / `AsyncDurableFunctionProcessor` leave it to the Function App, so their methods are no-ops. An in-process processor works in one tenant and exposes it as a read-only `tenant_id`; one built over your own `pipeline` keeps the pipeline's tenant, and a different `tenant_id` given with it raises `ConfigurationError`. A client raises `ConfigurationError` when its `processor` works in another tenant than its own `tenant_id`, so build the processor, and the pipeline it wraps, with the same `tenant_id`, or omit `processor` so the client builds its own. Concrete service classes: @@ -216,4 +216,4 @@ Concrete service classes: - Async: `AsyncPipelineService` from `azure.cosmos.agent_memory.aio.services` (sub-module `pipeline`). The async pipeline is a fully-native asyncio implementation - not an `asyncio.to_thread` shim over the sync pipeline. - Threshold-driven auto-trigger: `maybe_trigger_steps` from `azure.cosmos.agent_memory.auto_trigger` (sync) and `azure.cosmos.agent_memory.aio.auto_trigger` (async). -`MemoryStore`, `AsyncMemoryStore`, `PipelineService` and `AsyncPipelineService` take the same `tenant_id` argument as the clients (default `"default"`). A store stamps it on every record it writes and refuses a record that names another tenant; a pipeline keys its own reads and writes with it. Give a store and the pipeline that uses it the same value. A `MemoryRecord` you build yourself has `tenant_id=None` until it is written: the client or store stamps its own tenant then, and a record that names a different tenant is still refused. +`MemoryStore`, `AsyncMemoryStore`, `PipelineService` and `AsyncPipelineService` take the same `tenant_id` argument as the clients (default `"default"`). A store stamps it on every record it writes and refuses a record that names another tenant; a pipeline keys its own reads and writes with it, and its `tenant_id` defaults to the tenant of its store (a store of another tenant raises `ConfigurationError`). A `MemoryRecord` you build yourself has `tenant_id=None` until it is written: the client or store stamps its own tenant then, and a record that names a different tenant is still refused. diff --git a/README.md b/README.md index 99be4c0..ccf8b2b 100644 --- a/README.md +++ b/README.md @@ -307,7 +307,7 @@ memory = CosmosMemoryClient(..., processor=DurableFunctionProcessor()) `DurableFunctionProcessor` is a thin marker - there is no SDK→Function HTTP call. The SDK just writes turns; the deployed Function app picks them up via the Cosmos change feed. Counter-based trigger configuration and Bicep module reference live in [`infra/README.md`](infra/README.md). -An `InProcessProcessor` (or `AsyncInProcessProcessor`) you build yourself works in one tenant and exposes it as a read-only `tenant_id`. A client raises `ConfigurationError` when its `processor` works in another tenant than the client's own `tenant_id`: build the processor with the same `tenant_id`, or omit `processor` so the client builds its own. +An `InProcessProcessor` (or `AsyncInProcessProcessor`) you build yourself works in one tenant and exposes it as a read-only `tenant_id`; one built over your own `pipeline` keeps the pipeline's tenant, and a different `tenant_id` given with it raises `ConfigurationError`. A client raises `ConfigurationError` when its `processor` works in another tenant than the client's own `tenant_id`: build the processor, and the pipeline it wraps, with the same `tenant_id`, or omit `processor` so the client builds its own. --- @@ -393,7 +393,7 @@ tests/ Unit + integration tests (pytest) 4. Deploy the new Function App before the upgraded writers start. Its change feed trigger reads only the turns written after it first starts on a fresh `leases` container, so turns written earlier are never counted. 5. Upgrade and restart all writers together: a writer still on the old version keeps writing the old shape. - **Containers are checked when you connect.** `connect_cosmos()` raises `CosmosOperationError`, naming the container, when `memories`, `memories_turns`, `memories_summaries` or `counter` is missing or not keyed `[/tenant_id, /user_id]`; `create_memory_store()` creates what is missing and then makes the same check. A container still keyed `[/user_id, /thread_id]` would take writes and read back empty, so it is refused. `validate_topology()` remains the explicit check. -- **Identifiers are validated.** A `tenant_id`, a `user_id` and a `thread_id` must each be a non-empty string of at most 256 UTF-8 bytes that does not start or end with whitespace and has no `/`, `\`, `?`, `#` or control characters, because they appear in document ids and Cosmos DB refuses an id that ends in whitespace. Anything else raises `ValidationError` when the client writes it. +- **Identifiers are validated.** A `tenant_id`, a `user_id` and a `thread_id` must each be a non-empty string of at most 256 UTF-8 bytes that does not start or end with whitespace and has no `/`, `\`, `?`, `#` or control characters, because they appear in document ids and Cosmos DB refuses an id that ends in whitespace. Anything else raises `ValidationError` when the client buffers or writes it. - **`thread_id` is no longer needed to find a record.** It is no longer an argument of `update_cosmos()`, `delete_memory()`, `delete_turn()`, `add_tags()`, `remove_tags()` and `get_memory_history()`, and `MemoryNotFoundError` no longer carries it. Clients take an optional `tenant_id` (default `"default"`). See [CHANGELOG.md](CHANGELOG.md). - **`azure.cosmos.agent_memory.processing.ProcessingClient` is removed.** Drop the import and call `client.process_now()` (or `client.process_now_and_wait()`) instead. Same for the async `AsyncProcessingClient`. - **New `processor=` kwarg.** Defaults to `InProcessProcessor()` - existing code keeps its current behavior with no edits. diff --git a/azure/cosmos/agent_memory/_base/base_client.py b/azure/cosmos/agent_memory/_base/base_client.py index fb3c9b5..13d7463 100644 --- a/azure/cosmos/agent_memory/_base/base_client.py +++ b/azure/cosmos/agent_memory/_base/base_client.py @@ -8,7 +8,12 @@ from typing import Any, Optional from azure.cosmos.agent_memory._container_routing import ContainerKey -from azure.cosmos.agent_memory._partitioning import resolve_tenant_id +from azure.cosmos.agent_memory._partitioning import ( + reported_tenant, + resolve_tenant_id, + validate_owner_id, + validate_thread_id, +) from azure.cosmos.agent_memory._utils import ( VALID_ROLES, VALID_TYPES, @@ -135,12 +140,12 @@ def _require_processor_tenant(self, processor: Any) -> None: A processor that reports no tenant, as a custom one may not, is not checked. """ - processor_tenant = getattr(processor, "tenant_id", None) - if isinstance(processor_tenant, str) and processor_tenant != self._tenant_id: + processor_tenant = reported_tenant(processor) + if processor_tenant is not None and processor_tenant != self._tenant_id: raise ConfigurationError( f"processor works in tenant {processor_tenant!r} but this client is bound to tenant " - f"{self._tenant_id!r}: build the processor with the same tenant_id, or omit it so the client " - "builds its own" + f"{self._tenant_id!r}: build the processor, and the pipeline it wraps, with the same tenant_id, " + "or omit it so the client builds its own" ) @property @@ -170,7 +175,14 @@ def add_local( ttl: Optional[int] = None, salience: Optional[float] = None, ) -> None: - """Add a new memory to the local store.""" + """Add a new memory to the local store. + + ``user_id`` and ``thread_id`` must be valid ids, so a record that could never be written is refused here and + does not make every later push fail. + """ + validate_owner_id(user_id) + if thread_id: + validate_thread_id(thread_id) if memory_type == "turn" and not thread_id: raise ValidationError( "thread_id is required for memory_type='turn' so the auto-trigger " diff --git a/azure/cosmos/agent_memory/_partitioning.py b/azure/cosmos/agent_memory/_partitioning.py index 5f0eccf..665cac3 100644 --- a/azure/cosmos/agent_memory/_partitioning.py +++ b/azure/cosmos/agent_memory/_partitioning.py @@ -17,7 +17,7 @@ import unicodedata from typing import Any, Mapping, Optional -from azure.cosmos.agent_memory.exceptions import ValidationError +from azure.cosmos.agent_memory.exceptions import ConfigurationError, ValidationError DEFAULT_TENANT_ID = "default" @@ -26,8 +26,9 @@ # Ids appear in Cosmos document ids, which cannot hold these characters or end in whitespace. _UNSUPPORTED_CHARACTERS = "/\\?#" -# Control characters (C0, DEL and C1) and the line and paragraph separators. -_REFUSED_CATEGORIES = frozenset({"Cc", "Zl", "Zp"}) +# Control characters (C0, DEL and C1), lone surrogates (they cannot be encoded as UTF-8) and the line and paragraph +# separators. +_REFUSED_CATEGORIES = frozenset({"Cc", "Cs", "Zl", "Zp"}) MAX_TENANT_ID_BYTES = 256 MAX_OWNER_ID_BYTES = 256 MAX_THREAD_ID_BYTES = 256 @@ -73,6 +74,30 @@ def validate_owner_id(user_id: Any) -> str: return _checked_identifier(user_id, "user_id", MAX_OWNER_ID_BYTES) +def reported_tenant(obj: Any) -> Optional[str]: + """The tenant ``obj`` says it works in, or ``None`` when it reports none (a test double, a custom object).""" + tenant = getattr(obj, "tenant_id", None) + return tenant if isinstance(tenant, str) else None + + +def resolve_pipeline_tenant(store: Any, tenant_id: Optional[str] = None) -> str: + """The tenant of a pipeline over ``store``: ``tenant_id`` if given, else the tenant of the store, else the default. + + A pipeline reads in its own tenant and writes through its store, so a store that works in another tenant than the + one asked for raises :class:`ConfigurationError` instead of splitting the pipeline between the two. + """ + store_tenant = reported_tenant(store) + if tenant_id is None: + return resolve_tenant_id(store_tenant) + resolved = resolve_tenant_id(tenant_id) + if store_tenant is not None and store_tenant != resolved: + raise ConfigurationError( + f"tenant_id {resolved!r} differs from the tenant of the store, {store_tenant!r}: " + "give the pipeline and its store the same tenant_id" + ) + return resolved + + def validate_thread_id(thread_id: Any) -> str: """``thread_id`` if it is a valid thread id, else :class:`ValidationError`. diff --git a/azure/cosmos/agent_memory/aio/processors/inprocess.py b/azure/cosmos/agent_memory/aio/processors/inprocess.py index 57267ad..98975b3 100644 --- a/azure/cosmos/agent_memory/aio/processors/inprocess.py +++ b/azure/cosmos/agent_memory/aio/processors/inprocess.py @@ -10,7 +10,8 @@ import time from typing import Any, Optional -from azure.cosmos.agent_memory._partitioning import DEFAULT_TENANT_ID +from azure.cosmos.agent_memory._partitioning import reported_tenant, resolve_tenant_id +from azure.cosmos.agent_memory.exceptions import ConfigurationError from azure.cosmos.agent_memory.processors.base import ( ProcessThreadResult, UserSummaryResult, @@ -22,7 +23,8 @@ class AsyncInProcessProcessor: Wraps an existing pipeline, or builds one from the supplied container / LLM / embeddings clients, bound to ``tenant_id`` (``"default"`` when not given). A ``pipeline`` you pass keeps its own tenant, which - :attr:`tenant_id` reports and ``tenant_id=`` does not change; a client built with another tenant refuses it. + :attr:`tenant_id` reports; giving a different ``tenant_id`` as well raises :class:`ConfigurationError`, and so + does a client built with another tenant. """ def __init__( @@ -34,7 +36,7 @@ def __init__( summaries_container: Any = None, chat_client: Any = None, embeddings_client: Any = None, - tenant_id: str = DEFAULT_TENANT_ID, + tenant_id: Optional[str] = None, ) -> None: if pipeline is None: if ( @@ -53,6 +55,7 @@ def __init__( from azure.cosmos.agent_memory.aio.services.pipeline import AsyncPipelineService from azure.cosmos.agent_memory.aio.store import AsyncMemoryStore + tenant_id = resolve_tenant_id(tenant_id) containers = { ContainerKey.TURNS: turns_container, ContainerKey.MEMORIES: cosmos_container, @@ -62,13 +65,20 @@ def __init__( pipeline = AsyncPipelineService( store, chat_client, embeddings_client, containers=containers, tenant_id=tenant_id ) + elif tenant_id is not None: + pipeline_tenant = reported_tenant(pipeline) + if pipeline_tenant is not None and pipeline_tenant != resolve_tenant_id(tenant_id): + raise ConfigurationError( + f"tenant_id {tenant_id!r} differs from the tenant of the pipeline, {pipeline_tenant!r}: " + "build the pipeline with the tenant_id you want" + ) self._pipeline = pipeline @property def tenant_id(self) -> Optional[str]: """The tenant of the pipeline this processor runs, or ``None`` when that pipeline reports none.""" - return getattr(self._pipeline, "tenant_id", None) + return reported_tenant(self._pipeline) async def process_thread( self, diff --git a/azure/cosmos/agent_memory/aio/services/pipeline.py b/azure/cosmos/agent_memory/aio/services/pipeline.py index 5f55f56..8ba0ed0 100644 --- a/azure/cosmos/agent_memory/aio/services/pipeline.py +++ b/azure/cosmos/agent_memory/aio/services/pipeline.py @@ -30,11 +30,10 @@ from azure.cosmos.agent_memory._container_routing import ContainerKey from azure.cosmos.agent_memory._curation import mark_secret, sanitize_record, sanitize_text from azure.cosmos.agent_memory._partitioning import ( - DEFAULT_TENANT_ID, OWNER_FILTER, owner_parameters, partition_key_for, - resolve_tenant_id, + resolve_pipeline_tenant, stamp_scope, ) from azure.cosmos.agent_memory._utils import ( @@ -318,8 +317,9 @@ async def replace_item(self, **kwargs: Any) -> Any: class AsyncPipelineService: """Async LLM orchestration service over the injected containers, async memory store and model clients. - The service is bound to one tenant (``tenant_id``): every record it reads or writes is in the partition - ``[tenant_id, user_id]`` of its owner, and every query it sends filters on the tenant. + The service is bound to one tenant (``tenant_id``, which defaults to the tenant of ``store``): every record it + reads or writes is in the partition ``[tenant_id, user_id]`` of its owner, and every query it sends filters on the + tenant. A ``store`` that works in another tenant is refused. """ def __init__( @@ -331,9 +331,9 @@ def __init__( *, containers: dict[ContainerKey, Any], transcript_metadata_keys: Optional[Iterable[str]] = None, - tenant_id: str = DEFAULT_TENANT_ID, + tenant_id: Optional[str] = None, ) -> None: - self._tenant_id = resolve_tenant_id(tenant_id) + self._tenant_id = resolve_pipeline_tenant(store, tenant_id) self._store = store self._containers = containers self._memories_container = containers[ContainerKey.MEMORIES] diff --git a/azure/cosmos/agent_memory/aio/store/memory_store.py b/azure/cosmos/agent_memory/aio/store/memory_store.py index 2277054..66e0b1c 100644 --- a/azure/cosmos/agent_memory/aio/store/memory_store.py +++ b/azure/cosmos/agent_memory/aio/store/memory_store.py @@ -731,10 +731,11 @@ async def get_user_summary(self, user_id: str) -> Optional[dict[str, Any]]: """Retrieve the user's summary document from Cosmos DB, or ``None`` if absent.""" from azure.cosmos.exceptions import CosmosResourceNotFoundError + partition_key = partition_key_for(self._tenant_id, user_id) try: return await self._summaries_container.read_item( item=f"user_summary_{user_id}", - partition_key=partition_key_for(self._tenant_id, user_id), + partition_key=partition_key, ) except CosmosResourceNotFoundError: return None diff --git a/azure/cosmos/agent_memory/processors/inprocess.py b/azure/cosmos/agent_memory/processors/inprocess.py index 16374b0..f49e4db 100644 --- a/azure/cosmos/agent_memory/processors/inprocess.py +++ b/azure/cosmos/agent_memory/processors/inprocess.py @@ -5,7 +5,8 @@ import time from typing import Any, Optional -from .._partitioning import DEFAULT_TENANT_ID +from .._partitioning import reported_tenant, resolve_tenant_id +from ..exceptions import ConfigurationError from .base import ProcessThreadResult, UserSummaryResult @@ -16,7 +17,8 @@ class InProcessProcessor: :class:`azure.cosmos.agent_memory.services.pipeline.PipelineService` instance, or constructs one from the supplied container / LLM / embeddings clients, bound to ``tenant_id`` (``"default"`` when not given). A ``pipeline`` you pass keeps its own tenant, which - :attr:`tenant_id` reports and ``tenant_id=`` does not change; a client built with another tenant refuses it. + :attr:`tenant_id` reports; giving a different ``tenant_id`` as well raises :class:`ConfigurationError`, and so + does a client built with another tenant. """ def __init__( @@ -28,7 +30,7 @@ def __init__( summaries_container: Any = None, chat_client: Any = None, embeddings_client: Any = None, - tenant_id: str = DEFAULT_TENANT_ID, + tenant_id: Optional[str] = None, ) -> None: if pipeline is None: if ( @@ -47,6 +49,7 @@ def __init__( from ..services.pipeline import PipelineService from ..store import MemoryStore + tenant_id = resolve_tenant_id(tenant_id) containers = { ContainerKey.TURNS: turns_container, ContainerKey.MEMORIES: cosmos_container, @@ -60,13 +63,20 @@ def __init__( pipeline = PipelineService( store, chat_client, embeddings_client, containers=containers, tenant_id=tenant_id ) + elif tenant_id is not None: + pipeline_tenant = reported_tenant(pipeline) + if pipeline_tenant is not None and pipeline_tenant != resolve_tenant_id(tenant_id): + raise ConfigurationError( + f"tenant_id {tenant_id!r} differs from the tenant of the pipeline, {pipeline_tenant!r}: " + "build the pipeline with the tenant_id you want" + ) self._pipeline = pipeline @property def tenant_id(self) -> Optional[str]: """The tenant of the pipeline this processor runs, or ``None`` when that pipeline reports none.""" - return getattr(self._pipeline, "tenant_id", None) + return reported_tenant(self._pipeline) def process_thread( self, diff --git a/azure/cosmos/agent_memory/services/pipeline.py b/azure/cosmos/agent_memory/services/pipeline.py index be340ba..184b193 100644 --- a/azure/cosmos/agent_memory/services/pipeline.py +++ b/azure/cosmos/agent_memory/services/pipeline.py @@ -29,11 +29,10 @@ from azure.cosmos.agent_memory._container_routing import ContainerKey from azure.cosmos.agent_memory._curation import mark_secret, sanitize_record, sanitize_text from azure.cosmos.agent_memory._partitioning import ( - DEFAULT_TENANT_ID, OWNER_FILTER, owner_parameters, partition_key_for, - resolve_tenant_id, + resolve_pipeline_tenant, stamp_scope, ) from azure.cosmos.agent_memory._utils import ( @@ -286,8 +285,9 @@ def replace_item(self, **kwargs: Any) -> Any: class PipelineService: """LLM orchestration service over the injected containers, memory store and model clients. - The service is bound to one tenant (``tenant_id``): every record it reads or writes is in the partition - ``[tenant_id, user_id]`` of its owner, and every query it sends filters on the tenant. + The service is bound to one tenant (``tenant_id``, which defaults to the tenant of ``store``): every record it + reads or writes is in the partition ``[tenant_id, user_id]`` of its owner, and every query it sends filters on the + tenant. A ``store`` that works in another tenant is refused. """ def __init__( @@ -299,9 +299,9 @@ def __init__( *, containers: dict[ContainerKey, Any], transcript_metadata_keys: Optional[Iterable[str]] = None, - tenant_id: str = DEFAULT_TENANT_ID, + tenant_id: Optional[str] = None, ) -> None: - self._tenant_id = resolve_tenant_id(tenant_id) + self._tenant_id = resolve_pipeline_tenant(store, tenant_id) self._store = store self._containers = containers self._memories_container = containers[ContainerKey.MEMORIES] @@ -1012,7 +1012,7 @@ def _advance_episode_cursor(self, user_id: str, thread_id: str, last_turn: dict[ fail and leave the open segment torn, and it writes to the memories container, never the change-feed-monitored turns container. The advance is atomic - ETag ``IfNotModified`` with a re-read retry - so a late, - out-of-order concurrent ``episode:{u}:{t}:{count}`` orchestration cannot + out-of-order concurrent ``episode`` orchestration cannot regress the cursor (a regressed cursor would, with topic drift enabled, re-segment turns under a new segment key and duplicate episodes). """ diff --git a/azure/cosmos/agent_memory/store/memory_store.py b/azure/cosmos/agent_memory/store/memory_store.py index a46ec78..c3724cf 100644 --- a/azure/cosmos/agent_memory/store/memory_store.py +++ b/azure/cosmos/agent_memory/store/memory_store.py @@ -790,10 +790,11 @@ def get_user_summary(self, user_id: str) -> Optional[dict[str, Any]]: """Retrieve the user's summary document from Cosmos DB, or ``None`` if absent.""" from azure.cosmos.exceptions import CosmosResourceNotFoundError + partition_key = partition_key_for(self._tenant_id, user_id) try: return self._summaries_container.read_item( item=f"user_summary_{user_id}", - partition_key=partition_key_for(self._tenant_id, user_id), + partition_key=partition_key, ) except CosmosResourceNotFoundError: return None diff --git a/tests/unit/aio/processors/test_inprocess.py b/tests/unit/aio/processors/test_inprocess.py index ff906c4..0dafe44 100644 --- a/tests/unit/aio/processors/test_inprocess.py +++ b/tests/unit/aio/processors/test_inprocess.py @@ -8,6 +8,7 @@ import pytest from azure.cosmos.agent_memory.aio.processors import AsyncInProcessProcessor, ProcessThreadResult +from azure.cosmos.agent_memory.exceptions import ConfigurationError @pytest.mark.asyncio @@ -138,8 +139,8 @@ async def test_process_thread_summary_returns_none_for_non_dict(): assert result is None -def test_the_processor_reports_the_tenant_of_the_pipeline_it_runs(): - built = AsyncInProcessProcessor( +def _acme_processor() -> AsyncInProcessProcessor: + return AsyncInProcessProcessor( cosmos_container=MagicMock(), turns_container=MagicMock(), summaries_container=MagicMock(), @@ -147,10 +148,21 @@ def test_the_processor_reports_the_tenant_of_the_pipeline_it_runs(): embeddings_client=MagicMock(), tenant_id="acme", ) - # ``tenant_id=`` applies only to a pipeline the processor builds. - wrapped = AsyncInProcessProcessor(pipeline=built._pipeline, tenant_id="globex") - assert built.tenant_id == wrapped.tenant_id == "acme" + +def test_the_processor_reports_the_tenant_of_the_pipeline_it_runs(): + built = _acme_processor() + + assert built.tenant_id == "acme" + assert AsyncInProcessProcessor(pipeline=built._pipeline).tenant_id == "acme" + assert AsyncInProcessProcessor(pipeline=built._pipeline, tenant_id="acme").tenant_id == "acme" + + +def test_a_tenant_that_differs_from_the_one_of_its_pipeline_is_refused(): + built = _acme_processor() + + with pytest.raises(ConfigurationError, match="'globex' differs from the tenant of the pipeline, 'acme'"): + AsyncInProcessProcessor(pipeline=built._pipeline, tenant_id="globex") def test_a_pipeline_that_reports_no_tenant_leaves_the_processor_without_one(): diff --git a/tests/unit/aio/services/test_tenant_isolation_async.py b/tests/unit/aio/services/test_tenant_isolation_async.py index 8ffa182..d917897 100644 --- a/tests/unit/aio/services/test_tenant_isolation_async.py +++ b/tests/unit/aio/services/test_tenant_isolation_async.py @@ -13,6 +13,7 @@ import copy import json import re +from types import SimpleNamespace from typing import Any, Iterable, NamedTuple from unittest.mock import AsyncMock, MagicMock @@ -22,7 +23,7 @@ from azure.cosmos.agent_memory._container_routing import ContainerKey from azure.cosmos.agent_memory._utils import compute_content_hash from azure.cosmos.agent_memory.aio.services.pipeline import AsyncPipelineService -from azure.cosmos.agent_memory.exceptions import ValidationError +from azure.cosmos.agent_memory.exceptions import ConfigurationError, ValidationError from azure.cosmos.agent_memory.services._dedup import Verdict TENANT = "acme" @@ -218,6 +219,22 @@ def test_a_pipeline_refuses_a_tenant_that_cannot_key_a_record(tenant: str) -> No AsyncPipelineService(MagicMock(), MagicMock(), _Embeddings(), containers=containers, tenant_id=tenant) +def test_a_pipeline_works_in_the_tenant_of_its_store_unless_given_one() -> None: + containers = {key: MagicMock() for key in ContainerKey} + + def build(store: Any, **options: Any) -> AsyncPipelineService: + return AsyncPipelineService(store, MagicMock(), _Embeddings(), containers=containers, **options) + + store = SimpleNamespace(tenant_id=TENANT) + assert build(store).tenant_id == TENANT + assert build(store, tenant_id=TENANT).tenant_id == TENANT + with pytest.raises(ConfigurationError, match=f"'{OTHER}' differs from the tenant of the store, '{TENANT}'"): + build(store, tenant_id=OTHER) + # A store that reports no tenant is not checked: the pipeline works in the default tenant unless given one. + assert build(SimpleNamespace()).tenant_id == "default" + assert build(SimpleNamespace(), tenant_id=TENANT).tenant_id == TENANT + + # --- extraction ----------------------------------------------------------------------------------------------- diff --git a/tests/unit/aio/test_cosmos_memory_client.py b/tests/unit/aio/test_cosmos_memory_client.py index 5b335ac..cfa30aa 100644 --- a/tests/unit/aio/test_cosmos_memory_client.py +++ b/tests/unit/aio/test_cosmos_memory_client.py @@ -190,7 +190,10 @@ def _processor(tenant_id: str) -> AsyncInProcessProcessor: ) def test_a_processor_of_another_tenant_is_refused(self): - with pytest.raises(ConfigurationError, match=rf"tenant '{DEFAULT_TENANT_ID}'.*tenant 'acme'"): + # The way out is the pipeline the processor wraps: its tenant is the one that counts. + with pytest.raises( + ConfigurationError, match=rf"tenant '{DEFAULT_TENANT_ID}'.*tenant 'acme'.*the pipeline it wraps" + ): _make_client(tenant_id="acme", processor=self._processor(DEFAULT_TENANT_ID)) def test_a_processor_of_the_clients_tenant_is_used(self): diff --git a/tests/unit/function_app/test_change_feed.py b/tests/unit/function_app/test_change_feed.py index c8b7749..52add63 100644 --- a/tests/unit/function_app/test_change_feed.py +++ b/tests/unit/function_app/test_change_feed.py @@ -512,6 +512,7 @@ def test_a_turn_with_an_unsupported_owner_is_skipped_like_one_without_a_tenant(o pytest.param("a/b", id="slash"), pytest.param("t\x7f1", id="control-character"), pytest.param("t\u20281", id="line-separator"), + pytest.param("t\ud8001", id="lone-surrogate"), pytest.param("t" * 257, id="too-long"), ], ) diff --git a/tests/unit/processors/test_inprocess.py b/tests/unit/processors/test_inprocess.py index 9454632..61cfa88 100644 --- a/tests/unit/processors/test_inprocess.py +++ b/tests/unit/processors/test_inprocess.py @@ -5,6 +5,9 @@ from types import SimpleNamespace from unittest.mock import MagicMock +import pytest + +from azure.cosmos.agent_memory.exceptions import ConfigurationError from azure.cosmos.agent_memory.processors import InProcessProcessor, ProcessThreadResult @@ -135,8 +138,8 @@ def test_constructor_requires_all_three_containers_when_no_pipeline(): ) -def test_the_processor_reports_the_tenant_of_the_pipeline_it_runs(): - built = InProcessProcessor( +def _acme_processor() -> InProcessProcessor: + return InProcessProcessor( cosmos_container=MagicMock(), turns_container=MagicMock(), summaries_container=MagicMock(), @@ -144,10 +147,21 @@ def test_the_processor_reports_the_tenant_of_the_pipeline_it_runs(): embeddings_client=MagicMock(), tenant_id="acme", ) - # ``tenant_id=`` applies only to a pipeline the processor builds. - wrapped = InProcessProcessor(pipeline=built._pipeline, tenant_id="globex") - assert built.tenant_id == wrapped.tenant_id == "acme" + +def test_the_processor_reports_the_tenant_of_the_pipeline_it_runs(): + built = _acme_processor() + + assert built.tenant_id == "acme" + assert InProcessProcessor(pipeline=built._pipeline).tenant_id == "acme" + assert InProcessProcessor(pipeline=built._pipeline, tenant_id="acme").tenant_id == "acme" + + +def test_a_tenant_that_differs_from_the_one_of_its_pipeline_is_refused(): + built = _acme_processor() + + with pytest.raises(ConfigurationError, match="'globex' differs from the tenant of the pipeline, 'acme'"): + InProcessProcessor(pipeline=built._pipeline, tenant_id="globex") def test_a_pipeline_that_reports_no_tenant_leaves_the_processor_without_one(): diff --git a/tests/unit/services/test_pipeline_service.py b/tests/unit/services/test_pipeline_service.py index a6db26e..8e5a2d7 100644 --- a/tests/unit/services/test_pipeline_service.py +++ b/tests/unit/services/test_pipeline_service.py @@ -2,6 +2,7 @@ import copy import json +from types import SimpleNamespace from typing import Any from unittest.mock import MagicMock @@ -10,7 +11,7 @@ from azure.cosmos.agent_memory._container_routing import ContainerKey from azure.cosmos.agent_memory._partitioning import DEFAULT_TENANT_ID -from azure.cosmos.agent_memory.exceptions import ValidationError +from azure.cosmos.agent_memory.exceptions import ConfigurationError, ValidationError from azure.cosmos.agent_memory.services.pipeline import PipelineService, _StoreContainerAdapter @@ -356,6 +357,24 @@ def test_thread_summary_persists_to_summaries_container() -> None: summaries_container.upsert_item.assert_called_once() +def _pipeline_over(store: Any, **options: Any) -> PipelineService: + return PipelineService(store, MagicMock(), MagicMock(), containers=_containers_for_store(FakeStore()), **options) + + +def test_a_pipeline_works_in_the_tenant_of_its_store_unless_given_one() -> None: + store = SimpleNamespace(tenant_id="acme") + + assert _pipeline_over(store).tenant_id == "acme" + assert _pipeline_over(store, tenant_id="acme").tenant_id == "acme" + with pytest.raises(ConfigurationError, match="'globex' differs from the tenant of the store, 'acme'"): + _pipeline_over(store, tenant_id="globex") + + +def test_a_pipeline_over_a_store_that_reports_no_tenant_works_in_the_default_tenant() -> None: + assert _pipeline_over(SimpleNamespace()).tenant_id == DEFAULT_TENANT_ID + assert _pipeline_over(SimpleNamespace(), tenant_id="acme").tenant_id == "acme" + + def _persist_summary( service: PipelineService, kind: str, doc: dict[str, Any], user_id: str = "u1", thread_id: str = "t1" ) -> dict[str, Any]: diff --git a/tests/unit/store/test_tenant_isolation.py b/tests/unit/store/test_tenant_isolation.py index a499a8d..cd74b73 100644 --- a/tests/unit/store/test_tenant_isolation.py +++ b/tests/unit/store/test_tenant_isolation.py @@ -436,6 +436,16 @@ async def test_a_read_for_an_invalid_owner_is_refused_rather_than_widened_to_the assert not containers[MEMORIES].sent("query_items") +@pytest.mark.parametrize("owner", INVALID_OWNERS) +async def test_get_user_summary_refuses_an_invalid_owner_as_a_validation_error(kind, owner): + store, containers = _build(kind) + + with pytest.raises(ValidationError, match="user_id"): + await _call(store, "get_user_summary", owner) + + assert not containers[SUMMARIES].sent("read_item") + + async def test_mark_superseded_keeps_the_tenant_and_refuses_another(kind): store, containers = _build(kind, docs={MEMORIES: [_fact(), _fact(OTHER_TENANT)]}) diff --git a/tests/unit/test_cosmos_memory_client.py b/tests/unit/test_cosmos_memory_client.py index 9f68a58..bcb81b6 100644 --- a/tests/unit/test_cosmos_memory_client.py +++ b/tests/unit/test_cosmos_memory_client.py @@ -158,7 +158,10 @@ def _processor(tenant_id: str) -> InProcessProcessor: ) def test_a_processor_of_another_tenant_is_refused(self): - with pytest.raises(ConfigurationError, match=rf"tenant '{DEFAULT_TENANT_ID}'.*tenant 'acme'"): + # The way out is the pipeline the processor wraps: its tenant is the one that counts. + with pytest.raises( + ConfigurationError, match=rf"tenant '{DEFAULT_TENANT_ID}'.*tenant 'acme'.*the pipeline it wraps" + ): _make_client(tenant_id="acme", processor=self._processor(DEFAULT_TENANT_ID)) def test_a_processor_of_the_clients_tenant_is_used(self): @@ -304,6 +307,26 @@ def test_add_local_non_turn_thread_id_optional(self): mem.add_local(user_id="u1", role="user", content="profile", memory_type="user_summary") assert len(mem.local_memory) == 1 + @pytest.mark.parametrize( + ("user_id", "thread_id", "memory_type", "refused"), + [ + ("a/b", "t1", "turn", "user_id"), + ("u1 ", "t1", "turn", "user_id"), + ("", "t1", "turn", "user_id"), + ("u1", "t1 ", "turn", "thread_id"), + ("u1", "a/b", "turn", "thread_id"), + ("u1", "t\x7f1", "turn", "thread_id"), + ("u1", "t1 ", "fact", "thread_id"), + ], + ) + def test_add_local_refuses_an_id_that_could_never_be_written(self, user_id, thread_id, memory_type, refused): + mem = _make_client() + with pytest.raises(ValidationError, match=refused): + mem.add_local(user_id=user_id, role="user", content="hi", memory_type=memory_type, thread_id=thread_id) + # Nothing is buffered, so a later push does not fail on the same record every time. + assert mem.local_memory == [] + assert mem._unflushed_turn_counts == {} + class TestGetLocal: def test_get_local_no_filters(self): diff --git a/tests/unit/test_partitioning.py b/tests/unit/test_partitioning.py index 981749f..a78daf2 100644 --- a/tests/unit/test_partitioning.py +++ b/tests/unit/test_partitioning.py @@ -47,6 +47,9 @@ "a ", "a\n", "a\xa0", + # A lone surrogate cannot be encoded as UTF-8: it is refused up front, not left to raise UnicodeEncodeError. + "a\ud800b", + "\udfff", ] # Joined by zero-width joiners, which are format characters, not controls.