Skip to content

Commit 6eb3a1d

Browse files
jcodellajcodella
authored
Merge pull request #1 from jcodella/main
Migrate repository and update ADF parameters with fixes
2 parents 1226c8d + 4f54cc0 commit 6eb3a1d

24 files changed

Lines changed: 5688 additions & 0 deletions

‎.env.template‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# This is a template for the .env file. Copy this file to .env and fill in the values for your accounts.
2+
COSMOS_DB_ENDPOINT=https://<your-account>.documents.azure.com:443/
3+
COSMOS_DB_DATABASE=ai_memory
4+
COSMOS_DB_CONTAINER=memories
5+
COSMOS_DB_AUTOSCALE_MAX_RU=1000
6+
7+
AI_FOUNDRY_ENDPOINT=https://<your-account>.openai.azure.com/
8+
AI_FOUNDRY_API_KEY=
9+
EMBEDDING_MODEL=text-embedding-3-large
10+
EMBEDDING_DIMENSIONS=1536
11+
EMBEDDING_DATA_TYPE=float32
12+
EMBEDDING_DISTANCE_FUNCTION=cosine
13+
FULL_TEXT_LANGUAGE=en-US
14+
15+
LLM_MODEL=<your-model-deployment>
16+
17+
ADF_ENDPOINT=http://localhost:7071/api
18+
ADF_KEY=

‎.gitignore‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Environment
2+
.env
3+
local.settings.json
4+
5+
# agents
6+
.agents/
7+
.agent/
8+
.claude/
9+
skills/
10+
skills-lock.json
11+
12+
13+
# Python
14+
__pycache__/
15+
*.py[cod]
16+
*.egg-info/
17+
dist/
18+
build/
19+
*.egg
20+
.venv/
21+
venv/
22+
23+
# Jupyter Notebook
24+
.ipynb_checkpoints/
25+
26+
# VS Code
27+
.vscode/settings.json
28+
.vscode/
29+
30+
# macOS
31+
.DS_Store

‎Docs/README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Docs
2+
3+
This folder contains the main project documentation for Agent Memory Toolkit.
4+
5+
## Table of Contents
6+
7+
| Document | Purpose |
8+
|----------|---------|
9+
| [concepts.md](concepts.md) | Explains the core memory model, including memory types (turn, summary, fact, user summary), threads, roles, and the processing pipeline. |
10+
| [local_testing.md](local_testing.md) | Covers local setup, environment configuration, RBAC, Cosmos provisioning, and running the toolkit and Azure Functions locally. |
11+
| [azure_testing.md](azure_testing.md) | Covers Azure deployment, cloud configuration, required services, and validation steps for running the toolkit in Azure. |
12+
| [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. |
13+
14+
## Recommended Reading Order
15+
16+
1. Start with [concepts.md](concepts.md) to understand the data model and memory lifecycle.
17+
2. Use [local_testing.md](local_testing.md) to get the toolkit running and validated on your machine.
18+
3. Use [azure_testing.md](azure_testing.md) when you are ready to deploy or validate the full stack in Azure.
19+
4. See [design_patterns.md](design_patterns.md) for integration patterns in real applications.

‎Docs/azure_testing.md‎

Lines changed: 302 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,302 @@
1+
# Deploying and Testing Agent Memory Toolkit in Azure
2+
3+
This guide covers the minimum Azure resources, deployment steps, and validation order for running the toolkit in Azure.
4+
5+
---
6+
7+
## Required Azure Services
8+
9+
| Service | Purpose |
10+
|---------|---------|
11+
| **Azure Cosmos DB for NoSQL** | Persistent memory store with vector and full-text indexes |
12+
| **Azure OpenAI / AI Services** | Embeddings and chat generation |
13+
| **Azure Functions** | Durable Functions orchestrator and activities |
14+
| **Azure Storage Account** | Required by Azure Functions |
15+
| **Application Insights** | Recommended for monitoring |
16+
17+
---
18+
19+
## Prerequisites
20+
21+
You need:
22+
23+
- an Azure subscription
24+
- `az login`
25+
- Python 3.10+
26+
- Azure Functions Core Tools v4
27+
- dependencies installed:
28+
29+
```bash
30+
pip install -r requirements.txt
31+
pip install -r azure_functions/requirements.txt
32+
```
33+
34+
---
35+
36+
## 1. Create Azure Resources
37+
38+
Create, or reuse, the following:
39+
40+
1. resource group
41+
2. storage account
42+
3. Function App
43+
4. Cosmos DB for NoSQL account
44+
5. Azure OpenAI resource with:
45+
- one embedding model
46+
- one chat model
47+
48+
Examples:
49+
50+
```bash
51+
az group create --name <resource-group> --location <location>
52+
53+
az storage account create \
54+
--name <storage-account-name> \
55+
--resource-group <resource-group> \
56+
--location <location> \
57+
--sku Standard_LRS
58+
59+
az functionapp create \
60+
--name <function-app-name> \
61+
--resource-group <resource-group> \
62+
--storage-account <storage-account-name> \
63+
--consumption-plan-location <location> \
64+
--runtime python \
65+
--runtime-version 3.11 \
66+
--functions-version 4 \
67+
--os-type Linux
68+
69+
az cosmosdb create \
70+
--name <cosmos-account-name> \
71+
--resource-group <resource-group>
72+
```
73+
74+
The toolkit can create the database and container later via `create_memory_store()`.
75+
76+
---
77+
78+
## 2. Assign RBAC
79+
80+
Grant these roles:
81+
82+
- **Cosmos DB Built-in Data Contributor** on the Cosmos account
83+
- **Cognitive Services OpenAI User** on the AI resource
84+
85+
Enable managed identity on the Function App and use that principal for production role assignments:
86+
87+
```bash
88+
az functionapp identity assign \
89+
--name <function-app-name> \
90+
--resource-group <resource-group>
91+
```
92+
93+
---
94+
95+
## 3. Configure Function App Settings
96+
97+
Set the runtime settings:
98+
99+
```bash
100+
az functionapp config appsettings set \
101+
--name <function-app-name> \
102+
--resource-group <resource-group> \
103+
--settings \
104+
COSMOS_DB_ENDPOINT="https://<cosmos-account-name>.documents.azure.com:443/" \
105+
COSMOS_DB_DATABASE="ai_memory" \
106+
COSMOS_DB_CONTAINER="memories" \
107+
COSMOS_DB_AUTOSCALE_MAX_RU="1000" \
108+
AI_FOUNDRY_ENDPOINT="https://<openai-account-name>.openai.azure.com/" \
109+
EMBEDDING_MODEL="text-embedding-3-large" \
110+
EMBEDDING_DIMENSIONS="1536" \
111+
LLM_MODEL="gpt-5-mini"
112+
```
113+
114+
If you use function-key auth for the HTTP trigger, keep the key for the client as `ADF_KEY`.
115+
116+
---
117+
118+
## 4. Deploy the Functions Project
119+
120+
```bash
121+
cd azure_functions
122+
func azure functionapp publish <function-app-name>
123+
```
124+
125+
Verify deployment:
126+
127+
```bash
128+
az functionapp function list \
129+
--name <function-app-name> \
130+
--resource-group <resource-group> \
131+
-o table
132+
```
133+
134+
---
135+
136+
## 5. Configure the Python Client
137+
138+
Update `.env` to point at Azure instead of localhost:
139+
140+
```env
141+
COSMOS_DB_ENDPOINT=https://<cosmos-account-name>.documents.azure.com:443/
142+
COSMOS_DB_DATABASE=ai_memory
143+
COSMOS_DB_CONTAINER=memories
144+
COSMOS_DB_AUTOSCALE_MAX_RU=1000
145+
146+
AI_FOUNDRY_ENDPOINT=https://<openai-account-name>.openai.azure.com/
147+
EMBEDDING_MODEL=text-embedding-3-large
148+
EMBEDDING_DIMENSIONS=1536
149+
LLM_MODEL=gpt-5-mini
150+
151+
ADF_ENDPOINT=https://<function-app-name>.azurewebsites.net/api
152+
ADF_KEY=<function-key-if-needed>
153+
```
154+
155+
---
156+
157+
## 6. Create Cosmos Resources
158+
159+
Run once if the database and container do not already exist:
160+
161+
### Sync
162+
163+
```python
164+
import os
165+
from dotenv import load_dotenv
166+
from azure.identity import DefaultAzureCredential
167+
from agent_memory_toolkit import AgentMemory
168+
169+
load_dotenv()
170+
171+
memory = AgentMemory(
172+
cosmos_endpoint=os.getenv("COSMOS_DB_ENDPOINT"),
173+
cosmos_database=os.getenv("COSMOS_DB_DATABASE"),
174+
cosmos_container=os.getenv("COSMOS_DB_CONTAINER"),
175+
ai_foundry_endpoint=os.getenv("AI_FOUNDRY_ENDPOINT"),
176+
embedding_model=os.getenv("EMBEDDING_MODEL", "text-embedding-3-large"),
177+
adf_endpoint=os.getenv("ADF_ENDPOINT"),
178+
adf_key=os.getenv("ADF_KEY", ""),
179+
use_default_credential=True,
180+
cosmos_credential=DefaultAzureCredential(),
181+
)
182+
183+
memory.create_memory_store()
184+
memory.connect_cosmos()
185+
```
186+
187+
### Async
188+
189+
```python
190+
import os
191+
from dotenv import load_dotenv
192+
from azure.identity.aio import DefaultAzureCredential as AsyncDefaultAzureCredential
193+
from agent_memory_toolkit import AsyncAgentMemory
194+
195+
load_dotenv()
196+
197+
memory = AsyncAgentMemory(
198+
cosmos_endpoint=os.getenv("COSMOS_DB_ENDPOINT"),
199+
cosmos_database=os.getenv("COSMOS_DB_DATABASE"),
200+
cosmos_container=os.getenv("COSMOS_DB_CONTAINER"),
201+
ai_foundry_endpoint=os.getenv("AI_FOUNDRY_ENDPOINT"),
202+
embedding_model=os.getenv("EMBEDDING_MODEL", "text-embedding-3-large"),
203+
adf_endpoint=os.getenv("ADF_ENDPOINT"),
204+
adf_key=os.getenv("ADF_KEY", ""),
205+
use_default_credential=True,
206+
cosmos_credential=AsyncDefaultAzureCredential(),
207+
)
208+
209+
await memory.connect_cosmos(
210+
endpoint=os.getenv("COSMOS_DB_ENDPOINT"),
211+
database=os.getenv("COSMOS_DB_DATABASE"),
212+
container=os.getenv("COSMOS_DB_CONTAINER"),
213+
credential=AsyncDefaultAzureCredential(),
214+
)
215+
await memory.create_memory_store()
216+
```
217+
218+
This provisions the hierarchical partition key (`user_id`, `thread_id`), vector index, full-text index, and autoscale throughput.
219+
220+
---
221+
222+
## 7. Validation Order
223+
224+
Bring the environment up in this order:
225+
226+
1. `az login`
227+
2. verify Cosmos DB RBAC
228+
3. verify Azure OpenAI RBAC
229+
4. create Cosmos resources with `create_memory_store()`
230+
5. test `add_cosmos()` / `push_to_cosmos()` / `get_memories()`
231+
6. test `get_memories(user_id=..., thread_id=...)` filtering
232+
7. test `search_cosmos()`
233+
8. deploy the Function App
234+
9. test `generate_thread_summary()`
235+
10. test `extract_facts()` — verify single-line fact output
236+
11. test `generate_user_summary()` / `get_user_summary()`
237+
238+
This keeps failures isolated and easier to diagnose.
239+
240+
---
241+
242+
## 8. Validate Processing
243+
244+
### Basic Cosmos operations
245+
246+
```python
247+
memory.add_cosmos(user_id="user-1", role="user", content="Hello from Azure")
248+
print(memory.get_memories(user_id="user-1"))
249+
```
250+
251+
### Semantic search
252+
253+
```python
254+
print(memory.search_cosmos("hello", user_id="user-1"))
255+
```
256+
257+
### Durable Functions
258+
259+
```python
260+
print(memory.generate_thread_summary(user_id="user-1", thread_id="thread-1"))
261+
print(memory.extract_facts(user_id="user-1", thread_id="thread-1"))
262+
print(memory.generate_user_summary(user_id="user-1"))
263+
```
264+
265+
Thread summaries and user summaries update incrementally: repeated calls merge only new memories into the existing derived document.
266+
267+
### Verify stored results
268+
269+
```python
270+
print(memory.get_memories(user_id="user-1", memory_type="summary"))
271+
print(memory.get_memories(user_id="user-1", memory_type="fact"))
272+
print(memory.get_user_summary(user_id="user-1"))
273+
```
274+
275+
---
276+
277+
## Monitoring and Troubleshooting
278+
279+
Tail Function App logs:
280+
281+
```bash
282+
az functionapp log tail \
283+
--name <function-app-name> \
284+
--resource-group <resource-group>
285+
```
286+
287+
Common issues:
288+
289+
| Symptom | Likely Cause |
290+
|---------|--------------|
291+
| 401 / 403 from Cosmos DB | Missing Cosmos DB RBAC |
292+
| 401 / 403 from Azure OpenAI | Missing OpenAI RBAC |
293+
| Durable Function starts but fails | Missing app settings or downstream RBAC |
294+
| `No memories found` | No turn memories exist, or all candidate turns predate the existing summary |
295+
| Search is slow | Embedding latency, index choice, or region mismatch |
296+
297+
Recommended checks:
298+
299+
- enable Application Insights
300+
- confirm Function App managed identity roles
301+
- confirm `ADF_ENDPOINT` points to Azure
302+
- confirm model deployment names are correct

0 commit comments

Comments
 (0)