Overview graphic, restructuring of samples, troubleshooting guide, and more

Docs/README.md

@@ -10,10 +10,12 @@ This folder contains the main project documentation for Agent Memory Toolkit.
 | [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, and memory retrieval in chat and multi-agent applications, including automatic processing via the change feed. |
+| [troubleshooting.md](troubleshooting.md) | Helps diagnose common setup, authentication, Cosmos DB, embeddings, Durable Functions, vector search, and change feed issues. |
 
 ## Recommended Reading Order
 
 1. Start with [concepts.md](concepts.md) to understand the data model and memory lifecycle.
 2. Use [local_testing.md](local_testing.md) to get the toolkit running and validated on your machine.
 3. Use [azure_testing.md](azure_testing.md) when you are ready to deploy or validate the full stack in Azure.
-4. See [design_patterns.md](design_patterns.md) for integration patterns in real applications.
+4. See [design_patterns.md](design_patterns.md) for integration patterns in real applications.
+5. Use [troubleshooting.md](troubleshooting.md) when setup, processing, search, or automatic change feed behavior does not work as expected.

Docs/troubleshooting.md

@@ -0,0 +1,192 @@
+# Troubleshooting Agent Memory Toolkit
+
+Use this guide when local memory works but Cosmos DB, embeddings, Durable Functions, or automatic change feed processing does not.
+
+---
+
+## Quick Triage
+
+| Symptom | First checks |
+|---------|--------------|
+| Import errors | Install with `pip install -e ".[dev]"` and import `CosmosMemoryClient` or `AsyncCosmosMemoryClient`. |
+| 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 `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"`. |
+
+---
+
+## 1. Environment And Imports
+
+Install the package from the repository root:
+
+```bash
+pip install -e ".[dev]"
+pip install -r function_app/requirements.txt
+```
+
+The public clients are:
+
+```python
+from agent_memory_toolkit import CosmosMemoryClient
+from agent_memory_toolkit.aio import AsyncCosmosMemoryClient
+```
+
+If notebooks cannot import the package, run them from the repo root with paths such as `Samples/Notebooks/Demo.ipynb`, or add the repository root to `sys.path`.
+
+---
+
+## 2. Configuration And Authentication
+
+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
+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:
+
+| Service | Role |
+|---------|------|
+| Cosmos DB | Cosmos DB Built-in Data Contributor |
+| Azure OpenAI / AI Services | Cognitive Services OpenAI User |
+
+RBAC changes can take several minutes to propagate.
+
+---
+
+## 3. Cosmos DB Store Creation
+
+Run `create_memory_store()` before relying on cloud operations. It creates the database plus the `memories`, `counter`, and `leases` containers.
+
+The memories container is created with:
+
+- hierarchical partition key on `user_id` and `thread_id`
+- vector index on `/embedding`
+- full-text index on `/content`
+
+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.
+
+Use `COSMOS_DB_THROUGHPUT_MODE=serverless` for the default setup. Use `autoscale` with `COSMOS_DB_AUTOSCALE_MAX_RU` when you need provisioned autoscale throughput.
+
+---
+
+## 4. Embeddings And Search
+
+Embedding failures usually mean one of these is wrong:
+
+- `AI_FOUNDRY_ENDPOINT`
+- `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`.
+
+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.
+
+---
+
+## 5. Durable Functions Processing
+
+Durable Functions processing requires the Functions host.
+
+Start local dependencies:
+
+```bash
+azurite --silent --location /tmp/azurite --debug /tmp/azurite/debug.log
+cd function_app
+func start
+```
+
+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.
+
+---
+
+## 6. Change Feed Processing
+
+Automatic processing requires these settings in the Functions app or `local.settings.json`:
+
+```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.
+
+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 where the Cosmos JSON field is `type="summary"`, `type="fact"`, or `type="user_summary"`
+
+---
+
+## 7. Async Client Notes
+
+Use async Azure credentials with the async client:
+
+```python
+from azure.identity.aio import DefaultAzureCredential
+from agent_memory_toolkit.aio import AsyncCosmosMemoryClient
+```
+
+Always `await` cloud operations and close the client when done:
+
+```python
+await memory.close()
+```
+
+In notebooks, top-level `await` is supported, so do not wrap cells with `asyncio.run()`.

README.md

@@ -1,5 +1,8 @@
 # Azure Cosmos DB Agent Memory Toolkit - Public Preview
 
+![Agent Memory Toolkit overview](Overview.png)
+
+
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![Azure Cosmos DB](https://img.shields.io/badge/Azure-Cosmos%20DB-0078D4?logo=microsoft-azure)](https://azure.microsoft.com/en-us/products/cosmos-db/)
@@ -10,46 +13,6 @@
 
 Agent Memory Toolkit is a Python SDK for storing, retrieving, and transforming agent memories on Azure Cosmos DB. It gives your agent both raw conversation history and higher-value derived memory — thread summaries, extracted facts, and cross-thread user profiles — all searchable semantically. The processing pipeline can run **in-process** (zero infra) or in a sibling **Azure Durable Function app** that watches the Cosmos DB change feed. Sync (`CosmosMemoryClient`) and async (`AsyncCosmosMemoryClient`) APIs are mirror-images of each other.
 
-```
-┌──────────────────────────────────────────────────────────────────────────────────────┐
-│                                  YOUR AGENTIC APP                                    │
-│                   Uses CosmosMemoryClient / AsyncCosmosMemoryClient                  │
-└─────────────────────────────────────────┬────────────────────────────────────────────┘
-                                          │
-                                          ▼
-┌──────────────────────────────────────────────────────────────────────────────────────┐
-│                        AGENT MEMORY TOOLKIT (Python SDK)                             │
-│                                                                                      │
-│  • Local in-memory CRUD                                                              │
-│  • Cosmos DB storage and retrieval                                                   │
-│  • Pluggable processor: in-process or remote Durable Function app                    │
-└──────────────────────────────────────────┬──────────────────────────────┬────────────┘
-                        │                                            │
-                        │ read / write                               │ Invoke processing pipeline
-                        ▼                                            ▼
-┌───────────────────────────────────┐                           ┌──────────────────────────────────┐
-│      AZURE COSMOS DB (NoSQL)      │                           │     AZURE DURABLE FUNCTIONS      │
-│                                   │                           │                                  │
-│  Stores:                          │                           │  Orchestrates memory processing: │
-│  • turns                          │                           │  • thread summaries              │
-│  • summaries                      │◄─── memory management ───►│  • fact extraction               │
-│  • facts                          │                           │  • user summaries                │
-│  • user summaries                 │                           │                                  │
-│                                   │                           │ On-demand (SDK) or automatic     │
-│  Supports query, vector, text     │    change feed trigger    │ (Cosmos DB change feed trigger). │
-│  search over stored memories.     │───────────────────────────►│                                  │
-└───────────────────────┬───────────┘                           └──────────────────┬───────────────┘
-                        │             embeddings and LLM-based processing          │
-                        └──────────────────────┬───────────────────────────────────┘
-                                               ▼
-                              ┌──────────────────────────────────┐
-                              │         MICROSOFT FOUNDRY        │
-                              │                                  │
-                              │  • Embeddings for search         │
-                              │  • Chat/LLM generation           │
-                              │                                  │
-                              └──────────────────────────────────┘
-```
 
 ---
 
@@ -156,7 +119,7 @@ print(memory.get_user_summary(user_id=USER))
 ### 4. Run a sample
 
 ```bash
-python Samples/quickstart_cosmos.py
+python Samples/Quickstarts/quickstart_cosmos.py
 ```
 
 See [`Samples/`](Samples/) for end-to-end scenarios (chat memory, RAG, multi-agent, customer support, remote processor).
@@ -273,6 +236,29 @@ memory = CosmosMemoryClient(..., processor=DurableFunctionProcessor())
 
 ---
 
+### Architecture overview
+
+```
++--------------------------+
+|        Agent app         |
++------------+-------------+
+             |
+             v
++--------------------------+      +--------------------------+
+| Agent Memory Toolkit     | <--> | Microsoft Foundry        |
+| Python sync/async SDK    |      | LLMs + embeddings        |
++------------+-------------+      +------------+-------------+
+             ^                                 ^
+             |                                 |
+             v                                 v
++--------------------------+      +--------------------------+
+| Azure Cosmos DB          | <--> | Azure Durable Functions  |
+| memories + search        |      | optional processing      |
++--------------------------+      +--------------------------+
+```
+
+---
+
 ## Public API reference
 
 | Symbol | Module | Purpose |
@@ -297,6 +283,7 @@ Async equivalents (`AsyncInProcessProcessor`, `AsyncDurableFunctionProcessor`) l
 - **[Docs/local_testing.md](Docs/local_testing.md)** — Prerequisites, environment setup, running locally, debugging
 - **[Docs/azure_testing.md](Docs/azure_testing.md)** — Azure deployment, RBAC, cloud validation
 - **[infra/README.md](infra/README.md)** — `azd` deployment, Bicep modules, BYOR settings, counter-trigger tuning
+- -**[Docs/troubleshooting.md](Docs/troubleshooting.md)** — Common issues and resolutions for setup, auth, Cosmos DB, embeddings, Durable Functions, vector search, change feed, etc.
 
 ---
 
@@ -308,7 +295,7 @@ agent_memory_toolkit/   Python SDK (sync + aio mirror)
 function_app/           Sibling Azure Durable Function app
 infra/                  Bicep modules + main.bicep for `azd up`
 azure.yaml              `azd` config — provisions Cosmos + AI Foundry + Function app
-Samples/                Demo notebooks + sample scripts
+Samples/                Categorized demo notebooks + sample scripts
 Docs/                   Conceptual + operational docs
 tests/                  Unit + integration tests (pytest)
 ```