making some code improvements

Author: Aayush Kataria

Docs/azure_testing.md

@@ -28,9 +28,11 @@ You need:
 
 ```bash
 pip install -e ".[dev]"
-pip install -r azure_functions/requirements.txt
+pip install -r function_app/requirements.txt
 ```
 
+> The recommended way to provision **all** required Azure resources is `azd up` from the repo root, which uses the Bicep templates under `infra/`. See [`infra/README.md`](../infra/README.md) for details. The manual `az ...` commands below are kept as a reference for operators who can't use `azd`.
+
 ---
 
 ## 1. Create Azure Resources
@@ -111,11 +113,17 @@ az functionapp config appsettings set \
     AI_FOUNDRY_ENDPOINT="https://<openai-account-name>.openai.azure.com/" \
     AI_FOUNDRY_EMBEDDING_DEPLOYMENT_NAME="text-embedding-3-large" \
     AI_FOUNDRY_EMBEDDING_DIMENSIONS="1536" \
-    AI_FOUNDRY_CHAT_DEPLOYMENT_NAME="gpt-5-mini"
+    AI_FOUNDRY_CHAT_DEPLOYMENT_NAME="gpt-5-mini" \
+    THREAD_SUMMARY_EVERY_N="10" \
+    FACT_EXTRACTION_EVERY_N="1" \
+    USER_SUMMARY_EVERY_N="20" \
+    MEMORY_PROCESSOR_OWNER="durable"
 ```
 
 `COSMOS_DB_THROUGHPUT_MODE=serverless` is the default and creates the `memories`, `counter`, and `leases` containers without specifying RU/s. Set `COSMOS_DB_THROUGHPUT_MODE=autoscale` to apply the shared `COSMOS_DB_AUTOSCALE_MAX_RU` cap to all required containers.
 
+`MEMORY_PROCESSOR_OWNER=durable` tells the SDK that the deployed Function App owns processing, so any `CosmosMemoryClient` pointed at the same container will skip its in-process auto-trigger and avoid double-extraction. See the README's processor-ownership table for details.
+
 ### Change feed settings (optional)
 
 To enable automatic processing via the change feed trigger, add these settings:
@@ -139,14 +147,16 @@ Set any threshold to `"0"` to disable that processing type.
 
 The `leases` container is provisioned by `create_memory_store()` alongside the `memories` and `counter` containers, so the Function App should be configured to use that existing lease container.
 
-If you use function-key auth for the HTTP trigger, keep the key for the client as `ADF_KEY`.
+The Function App authenticates to Cosmos DB and Azure OpenAI via its managed identity — there's no shared key or function-key handoff between the SDK and the Function App.
 
 ---
 
 ## 4. Deploy the Functions Project
 
+The recommended path is `azd up` (which builds and deploys the `function_app/` service automatically). For manual deployment:
+
 ```bash
-cd azure_functions
+cd function_app
 func azure functionapp publish <function-app-name>
 ```
 
@@ -179,8 +189,9 @@ AI_FOUNDRY_EMBEDDING_DEPLOYMENT_NAME=text-embedding-3-large
 AI_FOUNDRY_EMBEDDING_DIMENSIONS=1536
 AI_FOUNDRY_CHAT_DEPLOYMENT_NAME=gpt-5-mini
 
-ADF_ENDPOINT=https://<function-app-name>.azurewebsites.net/api
-ADF_KEY=<function-key-if-needed>
+# Tells the SDK that the deployed Function App owns auto-processing,
+# so this client skips its in-process auto-trigger.
+MEMORY_PROCESSOR_OWNER=durable
 ```
 
 ---
@@ -195,22 +206,21 @@ Run once if the database and container do not already exist:
 import os
 from dotenv import load_dotenv
 from azure.identity import DefaultAzureCredential
-from agent_memory_toolkit import AgentMemory
+from agent_memory_toolkit import CosmosMemoryClient
 
 load_dotenv()
 
-memory = AgentMemory(
+memory = CosmosMemoryClient(
     cosmos_endpoint=os.getenv("COSMOS_DB_ENDPOINT"),
-    cosmos_database=os.getenv("COSMOS_DB_DATABASE"),
-    cosmos_container=os.getenv("COSMOS_DB_CONTAINER"),
+    cosmos_database=os.getenv("COSMOS_DB_DATABASE", "ai_memory"),
+    cosmos_container=os.getenv("COSMOS_DB_CONTAINER", "memories"),
     cosmos_counter_container=os.getenv("COSMOS_DB_COUNTERS_CONTAINER", "counter"),
     cosmos_lease_container=os.getenv("COSMOS_DB_LEASE_CONTAINER", "leases"),
     cosmos_throughput_mode=os.getenv("COSMOS_DB_THROUGHPUT_MODE", "serverless"),
     cosmos_autoscale_max_ru=int(os.getenv("COSMOS_DB_AUTOSCALE_MAX_RU", "1000")),
     ai_foundry_endpoint=os.getenv("AI_FOUNDRY_ENDPOINT"),
     embedding_deployment_name=os.getenv("AI_FOUNDRY_EMBEDDING_DEPLOYMENT_NAME", "text-embedding-3-large"),
-    adf_endpoint=os.getenv("ADF_ENDPOINT"),
-    adf_key=os.getenv("ADF_KEY", ""),
+    chat_deployment_name=os.getenv("AI_FOUNDRY_CHAT_DEPLOYMENT_NAME", "gpt-5-mini"),
     use_default_credential=True,
     cosmos_credential=DefaultAzureCredential(),
 )
@@ -225,32 +235,26 @@ memory.connect_cosmos()
 import os
 from dotenv import load_dotenv
 from azure.identity.aio import DefaultAzureCredential as AsyncDefaultAzureCredential
-from agent_memory_toolkit.aio import AsyncAgentMemory
+from agent_memory_toolkit.aio import AsyncCosmosMemoryClient
 
 load_dotenv()
 
-memory = AsyncAgentMemory(
+memory = AsyncCosmosMemoryClient(
     cosmos_endpoint=os.getenv("COSMOS_DB_ENDPOINT"),
-    cosmos_database=os.getenv("COSMOS_DB_DATABASE"),
-    cosmos_container=os.getenv("COSMOS_DB_CONTAINER"),
+    cosmos_database=os.getenv("COSMOS_DB_DATABASE", "ai_memory"),
+    cosmos_container=os.getenv("COSMOS_DB_CONTAINER", "memories"),
     cosmos_counter_container=os.getenv("COSMOS_DB_COUNTERS_CONTAINER", "counter"),
     cosmos_lease_container=os.getenv("COSMOS_DB_LEASE_CONTAINER", "leases"),
     cosmos_throughput_mode=os.getenv("COSMOS_DB_THROUGHPUT_MODE", "serverless"),
     cosmos_autoscale_max_ru=int(os.getenv("COSMOS_DB_AUTOSCALE_MAX_RU", "1000")),
     ai_foundry_endpoint=os.getenv("AI_FOUNDRY_ENDPOINT"),
     embedding_deployment_name=os.getenv("AI_FOUNDRY_EMBEDDING_DEPLOYMENT_NAME", "text-embedding-3-large"),
-    adf_endpoint=os.getenv("ADF_ENDPOINT"),
-    adf_key=os.getenv("ADF_KEY", ""),
+    chat_deployment_name=os.getenv("AI_FOUNDRY_CHAT_DEPLOYMENT_NAME", "gpt-5-mini"),
     use_default_credential=True,
     cosmos_credential=AsyncDefaultAzureCredential(),
 )
 
-await memory.connect_cosmos(
-    endpoint=os.getenv("COSMOS_DB_ENDPOINT"),
-    database=os.getenv("COSMOS_DB_DATABASE"),
-    container=os.getenv("COSMOS_DB_CONTAINER"),
-    credential=AsyncDefaultAzureCredential(),
-)
+await memory.connect_cosmos()
 await memory.create_memory_store()
 ```
 
@@ -269,11 +273,11 @@ Bring the environment up in this order:
 5. test `add_cosmos()` / `push_to_cosmos()` / `get_memories()`
 6. test `get_memories(user_id=..., thread_id=...)` filtering
 7. test `search_cosmos()`
-8. deploy the Function App
-9. test `generate_thread_summary()`
-10. test `extract_facts()` — verify single-line fact output
-11. test `generate_user_summary()` / `get_user_summary()`
-12. (if change feed is enabled) test automatic processing — write turns and verify derived memories appear
+8. deploy the Function App (e.g., via `azd up`) so the change-feed processor is running
+9. write a few turns and verify a thread `summary` memory appears
+10. write more turns and verify `fact`, `procedural`, and `episodic` memories appear
+11. verify a per-user `user_summary` memory appears once `USER_SUMMARY_EVERY_N` turns have accumulated for that user
+12. test deduplication by writing two near-duplicate facts and confirming the dedup orchestrator merges them
 
 This keeps failures isolated and easier to diagnose.
 
@@ -294,15 +298,26 @@ print(memory.get_memories(user_id="user-1"))
 print(memory.search_cosmos("hello", user_id="user-1"))
 ```
 
-### Durable Functions
+### Durable processing (change-feed driven)
+
+Processing is no longer invoked directly from the SDK — write turns with `add_cosmos()` / `push_to_cosmos()` and the deployed Function App's change-feed trigger fires the `extract_memories`, `thread_summary`, and `user_summary` orchestrators per the configured thresholds.
 
 ```python
-print(memory.generate_thread_summary(user_id="user-1", thread_id="thread-1"))
-print(memory.extract_facts(user_id="user-1", thread_id="thread-1"))
-print(memory.generate_user_summary(user_id="user-1"))
-```
+# Write enough turns to cross THREAD_SUMMARY_EVERY_N (default 10).
+for i in range(10):
+    memory.add_cosmos(
+        user_id="user-1",
+        thread_id="thread-1",
+        role="user",
+        content=f"Turn {i+1}",
+    )
 
-Thread summaries and user summaries update incrementally: repeated calls merge only new memories into the existing derived document.
+# Wait for the change-feed processor to catch up, then read derived memories.
+import time; time.sleep(15)
+print(memory.get_memories(user_id="user-1", thread_id="thread-1", memory_type="summary"))
+print(memory.get_memories(user_id="user-1", memory_type="fact"))
+print(memory.get_memories(user_id="user-1", memory_type="user_summary"))
+```
 
 ### Change feed auto-processing
 
@@ -335,7 +350,7 @@ Check the Function App logs to confirm the `on_memory_change` trigger fired and
 ```python
 print(memory.get_memories(user_id="user-1", memory_type="summary"))
 print(memory.get_memories(user_id="user-1", memory_type="fact"))
-print(memory.get_user_summary(user_id="user-1"))
+print(memory.get_memories(user_id="user-1", memory_type="user_summary"))
 ```
 
 ---
@@ -366,5 +381,5 @@ Recommended checks:
 
 - enable Application Insights
 - confirm Function App managed identity roles
-- confirm `ADF_ENDPOINT` points to Azure
+- confirm `MEMORY_PROCESSOR_OWNER=durable` is set on any client pointed at a container that the Function App is also processing
 - confirm model deployment names are correct

Docs/design_patterns.md

@@ -1,6 +1,6 @@
 # Design Patterns
 
-This guide shows when and how to use the toolkit's main operations in real applications. All examples use the async API (`AsyncAgentMemory`); the sync API (`AgentMemory`) has the same method signatures without `await`.
+This guide shows when and how to use the toolkit's main operations in real applications. All examples use the async API (`AsyncCosmosMemoryClient`); the sync API (`CosmosMemoryClient`) has the same method signatures without `await`.
 
 ---
 
@@ -11,26 +11,18 @@ This guide shows when and how to use the toolkit's main operations in real appli
 Write a turn memory every time a user or agent message is produced. If the application runs locally first and syncs later, use the local + bulk-upload pattern.
 
 ```python
-from azure.identity.aio import DefaultAzureCredential as AsyncDefaultAzureCredential
-from agent_memory_toolkit.aio import AsyncAgentMemory
+from agent_memory_toolkit.aio import AsyncCosmosMemoryClient
 
-mem = AsyncAgentMemory(
+mem = AsyncCosmosMemoryClient(
     cosmos_endpoint=COSMOS_DB_ENDPOINT,
-    cosmos_database="memory",
+    cosmos_database="ai_memory",
     cosmos_container="memories",
-    ai_foundry_endpoint=AOAI_ENDPOINT,
+    ai_foundry_endpoint=AI_FOUNDRY_ENDPOINT,
     embedding_deployment_name="text-embedding-3-large",
-    adf_endpoint=ADF_ENDPOINT,
-    adf_key=ADF_KEY,
+    chat_deployment_name="gpt-4o-mini",
     use_default_credential=True,
-    cosmos_credential=AsyncDefaultAzureCredential(),
-)
-await mem.connect_cosmos(
-    endpoint=COSMOS_DB_ENDPOINT,
-    database="memory",
-    container="memories",
-    credential=AsyncDefaultAzureCredential(),
 )
+await mem.connect_cosmos()
 
 THREAD_ID = "thread-abc-123"
 

README.md

@@ -207,7 +207,33 @@ high_conf_facts = memory.get_memories(user_id="u1", memory_type="fact", min_conf
 
 ### Auto-trigger (per-turn extraction)
 
-By default, the **InProcess processor** runs fact extraction after **every turn** (`FACT_EXTRACTION_EVERY_N=1`) and a thread summary every **10 turns** (`THREAD_SUMMARY_EVERY_N=10`). The trigger fires inside `push_to_cosmos()` after the turn is durably written, so calling `process_now()` is normally redundant — it remains as an explicit "flush now" hook. The Durable backend uses the same defaults via the change-feed function app.
+By default, the **InProcess processor** runs each pipeline step independently as its own threshold trips inside `push_to_cosmos()`:
+
+| Env var | Default | Step that fires | Async behavior |
+|---|---|---|---|
+| `FACT_EXTRACTION_EVERY_N` | `1` (every turn) | `process_extract_memories` (extract + dedup) | scheduled via `asyncio.create_task` |
+| `THREAD_SUMMARY_EVERY_N` | `10` | `process_thread_summary` | scheduled via `asyncio.create_task` |
+| `USER_SUMMARY_EVERY_N` | `20` | `process_user_summary` | scheduled via `asyncio.create_task` |
+
+Each `*_EVERY_N=0` disables only that step. The Durable backend uses the same defaults via the change-feed function app, so the in-process and durable backends fire on the same turn boundaries — only the *where* differs. Calling `process_now()` is normally redundant — it remains as an explicit "process now" hook for tests, manual workflows, and operators who set every threshold to `0`.
+
+The async client (`AsyncCosmosMemoryClient.push_to_cosmos`) does **not** await the auto-trigger; it schedules it as a background `asyncio.Task` so the write call returns as soon as the Cosmos upserts complete. Background failures are surfaced via `logger.warning` (search for `"Background auto-trigger task failed"`).
+
+#### Backend exclusivity (`MEMORY_PROCESSOR_OWNER`)
+
+Both the SDK auto-trigger and the function-app change-feed processor write into the same `counter` container. If you accidentally point an `InProcessProcessor` at a Cosmos container that already has a function app attached, both backends will run the pipeline on the same writes — double extraction, double dedup, double counters.
+
+Set the env var on **both sides** to make ownership explicit:
+
+| `MEMORY_PROCESSOR_OWNER` | SDK behavior | Function-app behavior |
+|---|---|---|
+| _unset_ (default) | runs auto-trigger | runs orchestrator (today's behavior) |
+| `inprocess` | runs auto-trigger | change-feed trigger skips batch + logs |
+| `durable` | auto-trigger logs warning + skips | runs orchestrator |
+
+The default (unset) preserves backward compatibility. For any production deployment we recommend setting it on both sides so a misconfiguration produces a loud log line instead of silent double-work.
+
+> **Advisory, not enforced.** `MEMORY_PROCESSOR_OWNER` is operator-configured exclusivity, not a server-side lock. Each backend reads its own env var; if the SDK is set to `inprocess` but the FA forgets to set `durable` (or vice versa), both still run. As a backstop, every counter write stamps `last_owner=<this backend>` on the doc — when the SDK observes a counter previously written by `durable` (or vice versa), it logs a one-shot `WARN` so misconfiguration surfaces in logs without spamming. Treat this as a configuration audit signal, not a hard guarantee.
 
 ---
 

agent_memory_toolkit/__init__.py

@@ -25,6 +25,17 @@
     ProcessThreadResult,
     UserSummaryResult,
 )
+from agent_memory_toolkit.thresholds import (
+    DEFAULT_FACT_EXTRACTION_EVERY_N,
+    DEFAULT_THREAD_SUMMARY_EVERY_N,
+    DEFAULT_USER_SUMMARY_EVERY_N,
+    PROCESSOR_OWNER_DURABLE,
+    PROCESSOR_OWNER_INPROCESS,
+    get_fact_extraction_every_n,
+    get_processor_owner,
+    get_thread_summary_every_n,
+    get_user_summary_every_n,
+)
 
 __all__ = [
     "CosmosMemoryClient",
@@ -51,4 +62,13 @@
     "OrchestrationTimeoutError",
     "ProcessingError",
     "ValidationError",
+    "DEFAULT_FACT_EXTRACTION_EVERY_N",
+    "DEFAULT_THREAD_SUMMARY_EVERY_N",
+    "DEFAULT_USER_SUMMARY_EVERY_N",
+    "PROCESSOR_OWNER_DURABLE",
+    "PROCESSOR_OWNER_INPROCESS",
+    "get_fact_extraction_every_n",
+    "get_processor_owner",
+    "get_thread_summary_every_n",
+    "get_user_summary_every_n",
 ]