addressed Copilot review items

Author: jcodella

Docs/troubleshooting.md

@@ -9,11 +9,11 @@ Use this guide when local memory works but Cosmos DB, embeddings, Durable Functi
 | Symptom | First checks |
 |---------|--------------|
 | Import errors | Install with `pip install -e ".[dev]"` and import `CosmosMemoryClient` or `AsyncCosmosMemoryClient`. |
-| Missing configuration | Verify `.env`, `azure_functions/local.settings.json`, and Azure Function App settings use the same endpoint, database, and container values. |
+| Missing configuration | Verify `.env`, `function_app/local.settings.json`, and Azure Function App settings use the same endpoint, database, container, and AI deployment values. |
 | 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 `EMBEDDING_DIMENSIONS` matches the container vector policy. |
-| Durable Function calls fail | Start the Functions host and check `ADF_ENDPOINT`, `ADF_KEY`, and the orchestrator route. |
+| Search returns no vector results | Confirm embeddings are generated and `AI_FOUNDRY_EMBEDDING_DIMENSIONS` matches the container vector policy. |
+| Durable Functions processing fails | Start the Functions host and check `function_app/local.settings.json`, the change feed trigger, and the orchestrator logs. |
 | Change feed does not create summaries or facts | Confirm change feed settings, thresholds, lease container, counter container, and that inserted documents have `type: "turn"`. |
 
 ---
@@ -24,7 +24,7 @@ Install the package from the repository root:
 
 ```bash
 pip install -e ".[dev]"
-pip install -r azure_functions/requirements.txt
+pip install -r function_app/requirements.txt
 ```
 
 The public clients are:
@@ -40,21 +40,45 @@ If notebooks cannot import the package, run them from the repo root with paths s
 
 ## 2. Configuration And Authentication
 
-For local runs, keep `.env` and `azure_functions/local.settings.json` aligned:
+For local runs, keep `.env`, `function_app/local.settings.json`, and deployed Function App settings aligned:
 
 ```env
 COSMOS_DB_ENDPOINT=https://<account>.documents.azure.com:443/
+COSMOS_DB__accountEndpoint=https://<account>.documents.azure.com:443/
+COSMOS_DB_KEY=
 COSMOS_DB_DATABASE=ai_memory
 COSMOS_DB_CONTAINER=memories
 COSMOS_DB_COUNTERS_CONTAINER=counter
 COSMOS_DB_LEASE_CONTAINER=leases
-AI_FOUNDRY_ENDPOINT=https://<project>.services.ai.azure.com/
-EMBEDDING_MODEL=text-embedding-3-large
-EMBEDDING_DIMENSIONS=1536
-ADF_ENDPOINT=http://localhost:7071/api
-ADF_KEY=
+COSMOS_DB_THROUGHPUT_MODE=serverless
+COSMOS_DB_AUTOSCALE_MAX_RU=1000
+
+AI_FOUNDRY_ENDPOINT=https://<account>.openai.azure.com/
+AI_FOUNDRY_API_KEY=
+AI_FOUNDRY_EMBEDDING_DEPLOYMENT_NAME=text-embedding-3-large
+AI_FOUNDRY_EMBEDDING_DIMENSIONS=1536
+AI_FOUNDRY_EMBEDDING_DATA_TYPE=float32
+AI_FOUNDRY_EMBEDDING_DISTANCE_FUNCTION=cosine
+AI_FOUNDRY_CHAT_DEPLOYMENT_NAME=<chat-deployment-name>
 ```
 
+The notebooks and samples pass these values into the client like this:
+
+| `.env` setting | Client argument |
+|---|---|
+| `COSMOS_DB_ENDPOINT` | `cosmos_endpoint` |
+| `COSMOS_DB_DATABASE` | `cosmos_database` |
+| `COSMOS_DB_CONTAINER` | `cosmos_container` |
+| `COSMOS_DB_COUNTERS_CONTAINER` | `cosmos_counter_container` |
+| `COSMOS_DB_LEASE_CONTAINER` | `cosmos_lease_container` |
+| `COSMOS_DB_KEY` | `cosmos_key` |
+| `AI_FOUNDRY_ENDPOINT` | `ai_foundry_endpoint` |
+| `AI_FOUNDRY_API_KEY` | `ai_foundry_api_key` |
+| `AI_FOUNDRY_EMBEDDING_DEPLOYMENT_NAME` | `embedding_deployment_name` |
+| `AI_FOUNDRY_CHAT_DEPLOYMENT_NAME` | `chat_deployment_name` |
+
+`AI_FOUNDRY_EMBEDDING_DIMENSIONS`, `AI_FOUNDRY_EMBEDDING_DATA_TYPE`, and `AI_FOUNDRY_EMBEDDING_DISTANCE_FUNCTION` are read by the toolkit when creating the Cosmos DB vector policy. The Function App also reads `COSMOS_DB__accountEndpoint` for its identity-based Cosmos DB trigger binding; set it to the same value as `COSMOS_DB_ENDPOINT`.
+
 Run `az login` before using `DefaultAzureCredential`.
 
 Required roles:
@@ -89,8 +113,8 @@ Use `COSMOS_DB_THROUGHPUT_MODE=serverless` for the default setup. Use `autoscale
 Embedding failures usually mean one of these is wrong:
 
 - `AI_FOUNDRY_ENDPOINT`
-- `EMBEDDING_MODEL`
-- `EMBEDDING_DIMENSIONS`
+- `AI_FOUNDRY_EMBEDDING_DEPLOYMENT_NAME`
+- `AI_FOUNDRY_EMBEDDING_DIMENSIONS`
 - Azure OpenAI / AI Services RBAC
 
 For hybrid search, `search_terms` is required when `hybrid_search=True`.
@@ -101,23 +125,17 @@ If search returns documents but scores look poor, check that records have an `em
 
 ## 5. Durable Functions Processing
 
-Thread summaries, fact extraction, and user summaries require the Functions host.
+Durable Functions processing requires the Functions host.
 
 Start local dependencies:
 
 ```bash
 azurite --silent --location /tmp/azurite --debug /tmp/azurite/debug.log
-cd azure_functions
+cd function_app
 func start
 ```
 
-The SDK posts to:
-
-```text
-<ADF_ENDPOINT>/orchestrators/memory_orchestrator
-```
-
-For local testing, `ADF_ENDPOINT` is usually `http://localhost:7071/api` and `ADF_KEY` is blank. For Azure, use the deployed Function App URL and set `ADF_KEY` if function-key auth is enabled.
+The SDK does not post to a Function endpoint. With `DurableFunctionProcessor`, the SDK writes turns to Cosmos DB and the deployed Function App picks them up from the Cosmos DB change feed. For local testing, keep `function_app/local.settings.json` aligned with `.env` and confirm the Functions host starts the change feed trigger.
 
 If orchestration polling times out, check the Functions logs first. The orchestration may still be running, or an activity may be waiting on Cosmos DB or the LLM endpoint.
 
@@ -129,24 +147,30 @@ Automatic processing requires these settings in the Functions app or `local.sett
 
 ```json
 "COSMOS_DB__accountEndpoint": "https://<account>.documents.azure.com:443/",
+"COSMOS_DB_ENDPOINT": "https://<account>.documents.azure.com:443/",
+"COSMOS_DB_DATABASE": "ai_memory",
+"COSMOS_DB_CONTAINER": "memories",
 "COSMOS_DB_COUNTERS_CONTAINER": "counter",
 "COSMOS_DB_LEASE_CONTAINER": "leases",
+"AI_FOUNDRY_ENDPOINT": "https://<account>.openai.azure.com/",
+"AI_FOUNDRY_CHAT_DEPLOYMENT_NAME": "gpt-4o-mini",
+"AI_FOUNDRY_EMBEDDING_DEPLOYMENT_NAME": "text-embedding-3-large",
 "THREAD_SUMMARY_EVERY_N": "5",
 "FACT_EXTRACTION_EVERY_N": "3",
 "USER_SUMMARY_EVERY_N": "10"
 ```
 
 Set a threshold to `"0"` to disable that processing type.
 
-Only documents with `type: "turn"` increment counters. Derived memories such as `summary`, `fact`, and `user_summary` do not trigger threshold counts.
+Cosmos DB memory documents store their category in the JSON `type` field. Only documents with `type: "turn"` increment counters. Derived memories with `type: "summary"`, `type: "fact"`, or `type: "user_summary"` do not trigger threshold counts.
 
 If nothing fires:
 
 - verify the Functions host shows the Cosmos DB trigger
 - confirm the `leases` container exists
 - confirm the `counter` container is writable
 - insert enough new turn documents to cross the configured threshold
-- check for generated documents with `memory_type="summary"`, `memory_type="fact"`, or `get_user_summary(user_id=...)`
+- check for generated documents where the Cosmos JSON field is `type="summary"`, `type="fact"`, or `type="user_summary"`
 
 ---
 

Samples/Notebooks/Demo.ipynb

@@ -363,10 +363,18 @@
    },
    "outputs": [],
    "source": [
-    "# Delete the tool memory (index 2 – the tool call)\n",
-    "tool_memory_id = memory.local_memory[2][\"id\"]\n",
-    "print(f\"Deleting memory {tool_memory_id[:8]}...\")\n",
-    "memory.delete_local(tool_memory_id)\n",
+    "# Delete the user's booking request by role/content instead of a fixed index\n",
+    "booking_requests = [\n",
+    "    m for m in memory.get_local(user_id=USER_ID, role=\"user\")\n",
+    "    if \"book a trip to Seattle\" in m[\"content\"]\n",
+    "]\n",
+    "if not booking_requests:\n",
+    "    raise ValueError(\"Expected to find the user's Seattle booking request.\")\n",
+    "\n",
+    "delete_target = booking_requests[0]\n",
+    "delete_target_id = delete_target[\"id\"]\n",
+    "print(f\"Deleting user memory {delete_target_id[:8]}... {delete_target['content'][:60]}\")\n",
+    "memory.delete_local(delete_target_id)\n",
     "\n",
     "# Verify it's gone\n",
     "print(f\"\\nRemaining memories: {len(memory.get_local())}\")\n",

Samples/Notebooks/Demo_async.ipynb

@@ -237,7 +237,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 15,
    "id": "942e3714",
    "metadata": {
     "ExecuteTime": {
@@ -251,20 +251,45 @@
      "shell.execute_reply": "2026-05-04T20:25:45.663296Z"
     }
    },
-   "outputs": [],
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Total memories: 19\n",
+      "\n",
+      "Memories for user-68421be1: 19\n",
+      "Agent memories: 10\n",
+      "  [4d27c469...] This weekend Seattle will be around 55°F with partly cloudy \n",
+      "  [5991e394...] Sure! I found round-trip flights departing Friday evening an\n",
+      "  [ae314a6e...] I found a round-trip on Alaska Airlines for $275 and two hot\n",
+      "  [bc5681e4...] Got it. I'll always select an aisle seat for your bookings.\n",
+      "  [eccd2557...] Noted — I'll follow that order: weather, then flights, then \n",
+      "  [d2109708...] Will do — no overnight bookings without your explicit approv\n",
+      "  [f0fd3216...] Got it. I'll always select an aisle seat for your bookings.\n",
+      "  [d90de470...] Noted — I'll follow that order: weather, then flights, then \n",
+      "  [5156acad...] Will do — no overnight bookings without your explicit approv\n",
+      "  [5ba8a11c...] Understood — only hotels with complimentary breakfast.\n",
+      "\n",
+      "Fact memories: 0\n",
+      "\n",
+      "Agent memories for user-68421be1: 10\n"
+     ]
+    }
+   ],
    "source": [
     "# Get all memories\n",
     "all_memories = memory.get_local()\n",
     "print(f\"Total memories: {len(all_memories)}\\n\")\n",
     "\n",
     "# Filter by user_id\n",
-    "user1_memories = memory.get_local(user_id=USER_ID)\n",
-    "print(f\"Memories for user-001: {len(user1_memories)}\")\n",
+    "user_memories = memory.get_local(user_id=USER_ID)\n",
+    "print(f\"Memories for {USER_ID}: {len(user_memories)}\")\n",
     "\n",
     "# Filter by role\n",
-    "tool_memories = memory.get_local(role=\"agent\")\n",
-    "print(f\"Tool memories: {len(tool_memories)}\")\n",
-    "for m in tool_memories:\n",
+    "agent_memories = memory.get_local(role=\"agent\")\n",
+    "print(f\"Agent memories: {len(agent_memories)}\")\n",
+    "for m in agent_memories:\n",
     "    print(f\"  [{m['id'][:8]}...] {m['content'][:60]}\")\n",
     "\n",
     "# Filter by type\n",
@@ -273,9 +298,9 @@
     "for m in facts:\n",
     "    print(f\"  [{m['id'][:8]}...] {m['content']}\")\n",
     "\n",
-    "# Combine filters: user-001 + agent role\n",
-    "user1_agent = memory.get_local(user_id=USER_ID, role=\"agent\")\n",
-    "print(f\"\\nAgent memories for user-001: {len(user1_agent)}\")"
+    "# Combine filters: current user + agent role\n",
+    "user_agent_memories = memory.get_local(user_id=USER_ID, role=\"agent\")\n",
+    "print(f\"\\nAgent memories for {USER_ID}: {len(user_agent_memories)}\")"
    ]
   },
   {
@@ -473,9 +498,9 @@
    },
    "outputs": [],
    "source": [
-    "# Get all memories for user-001\n",
+    "# Get all memories for the current demo user\n",
     "results = await memory.get_memories(user_id=USER_ID)\n",
-    "print(f\"Memories for user-001: {len(results)}\\n\")\n",
+    "print(f\"Memories for {USER_ID}: {len(results)}\\n\")\n",
     "for r in results:\n",
     "    print(f\"  [{r['thread_id'][:8]}...] [{r['id'][:8]}...] role={r['role']:<6} type={r['type']:<8} {r['content'][:50]}\")\n",
     "\n",