bedrock-agentcore-starter-toolkit 0.1.15__tar.gz → 0.1.16__tar.gz

{bedrock_agentcore_starter_toolkit-0.1.15 → bedrock_agentcore_starter_toolkit-0.1.16}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [0.1.16] - 2025-10-01
+
+### Changes
+
+- fix: don't fail validation for empty namespaces for during get_or_create when strategy defaults server side (#235) (3557359)
+- chore: make doc titles more meaningful (#229) (9c860d7)
+- Update memory quickstart (#234) (98a192b)
+- chore: bump version to 0.1.15 (#233) (0561bb5)
+
 ## [0.1.15] - 2025-10-01
 
 ### Changes

{bedrock_agentcore_starter_toolkit-0.1.15 → bedrock_agentcore_starter_toolkit-0.1.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bedrock-agentcore-starter-toolkit
-Version: 0.1.15
+Version: 0.1.16
 Summary: A starter toolkit for using Bedrock AgentCore
 Project-URL: Homepage, https://github.com/aws/bedrock-agentcore-starter-toolkit
 Project-URL: Bug Tracker, https://github.com/aws/bedrock-agentcore-starter-toolkit/issues

bedrock_agentcore_starter_toolkit-0.1.16/documentation/docs/examples/semantic_search.md

@@ -0,0 +1,97 @@
+# Semantic Search Memory Example
+
+This example demonstrates the complete workflow for creating a memory resource with semantic strategy, writing events, and retrieving memory records.
+
+```python
+# Semantic Search Memory Example
+
+from bedrock_agentcore_starter_toolkit.operations.memory.manager import MemoryManager
+from bedrock_agentcore.memory.session import MemorySessionManager
+from bedrock_agentcore.memory.constants import ConversationalMessage, MessageRole
+from bedrock_agentcore_starter_toolkit.operations.memory.models.strategies import SemanticStrategy
+import time
+
+memory_manager = MemoryManager(region_name="us-west-2")
+
+print("Creating memory resource...")
+
+memory = memory_manager.get_or_create_memory(
+    name="CustomerSupportSemantic",
+    description="Customer support memory store",
+    strategies=[
+        SemanticStrategy(
+            name="semanticLongTermMemory",
+            namespaces=['/strategies/{memoryStrategyId}/actors/{actorId}'],
+        )
+    ]
+)
+
+print(f"Memory ID: {memory.get('id')}")
+
+# Create a session to store memory events
+session_manager = MemorySessionManager(
+    memory_id=memory.get("id"),
+    region_name="us-west-2")
+
+# Write memory events (conversation turns)
+session_manager.add_turns(
+    actor_id="User1",
+    session_id="OrderSupportSession1",
+    messages=[
+        ConversationalMessage(
+            "Hi, how can I help you today?",
+            MessageRole.ASSISTANT)],
+)
+
+session_manager.add_turns(
+    actor_id="User1",
+    session_id="OrderSupportSession1",
+    messages=[
+        ConversationalMessage(
+            "Hi, I am a new customer. I just made an order, but it hasn't arrived. The Order number is #35476",
+            MessageRole.USER)],
+)
+
+session_manager.add_turns(
+    actor_id="User1",
+    session_id="OrderSupportSession1",
+    messages=[
+        ConversationalMessage(
+            "I'm sorry to hear that. Let me look up your order.",
+            MessageRole.ASSISTANT)],
+)
+
+# List all events in the session
+events = session_manager.list_events(
+    actor_id="User1",
+    session_id="OrderSupportSession1",
+)
+
+for event in events:
+    print(f"Event: {event}")
+    print("--------------------------------------------------------------------")
+
+print("Waiting 2 minutes for semantic processing...")
+time.sleep(120)
+
+# List all memory records
+memory_records = session_manager.list_long_term_memory_records(
+    namespace_prefix="/"
+)
+
+for record in memory_records:
+    print(f"Memory record: {record}")
+    print("--------------------------------------------------------------------")
+
+# Perform a semantic search
+memory_records = session_manager.search_long_term_memories(
+    query="can you summarize the support issue",
+    namespace_prefix="/",
+    top_k=3
+)
+
+for record in memory_records:
+    print(f"retrieved memory: {record}")
+    print("--------------------------------------------------------------------")
+
+```

bedrock_agentcore_starter_toolkit-0.1.16/documentation/docs/user-guide/memory/quickstart.md

@@ -0,0 +1,166 @@
+# Getting Started with AgentCore Memory
+
+Amazon Bedrock AgentCore Memory lets you create and manage memory resources that store conversation context for your AI agents. This section guides you through installing dependencies and implementing both short-term and long-term memory features. 
+
+The steps are as follows
+
+1. Create a memory resource containing a semantic strategy
+2. Write events (conversation history) to the memory resource.
+3. Retrieve memory records from long term memory
+
+## Prerequisites
+
+### Before starting, make sure you have:
+
+* **AWS Account** with credentials configured (`aws configure`)
+* **Python 3.10+** installed
+
+
+To get started with Amazon Bedrock AgentCore Memory, make a folder for this quick start, create a virtual environment, and install the dependencies. The below command can be run directly in the terminal.
+
+```bash
+mkdir agentcore-memory-quickstart
+cd agentcore-memory-quickstart
+python -m venv .venv
+source .venv/bin/activate
+pip install bedrock-agentcore
+pip install bedrock-agentcore-starter-toolkit
+```
+
+
+**Note: The AgentCore Starter Toolkit is intended to help developers get started quickly. The Boto3 Python library provides the most comprehensive set of operations for AgentCore Memory. You can find the Boto3 documentation here.**
+
+
+## Step One: Create a Memory Resource
+
+A memory resource is needed to start storing information for your agent. By default, memory events (which we refer to as short-term memory) can be written to a memory resource. In order for insights to be extracted and placed into long term memory records, the resource requires a 'memory strategy' - a configuration that defines how conversational data should be processed, and what information to extract (such as facts, preferences, or summaries).
+
+We are going to create a memory resource with a semantic strategy so that both short term and long term memory can be utilized. This will take 1-2 minutes. Memory resources can also be created in the AWS console.
+
+```python
+from bedrock_agentcore_starter_toolkit.operations.memory.manager import MemoryManager
+from bedrock_agentcore.memory.session import MemorySessionManager
+from bedrock_agentcore_starter_toolkit.operations.memory.models.strategies import (
+    SemanticStrategy)
+
+memory_manager = MemoryManager(region_name="us-west-2")
+
+print("Creating memory resource...")
+
+memory = memory_manager.get_or_create_memory(
+    name="CustomerSupportSemantic",
+    description="Customer suppoer memory store",
+    strategies=[
+        SemanticStrategy(
+            name="semanticLongTermMemory",
+        )
+    ]
+)
+
+print(f"Memory ID: {memory.get('id')}")
+
+```
+
+
+You can call list_memories to see that the memory resource has been created with:
+
+```python
+memories = memory_manager.list_memories()
+```
+
+
+
+## Step Two: Write events to memory
+
+Writing events to memory has multiple purposes. First, event contents (most commonly conversation history) are stored as short term memory. Second, relevant insights are pulled from events and written into memory records as a part of long term memory.
+
+The memory resource id, actor id, and session id are required to create an event. We are going to create three events, simulating messages between an end user and a chat bot.
+ 
+
+```python
+# Create a session to store memory events
+session_manager = MemorySessionManager(
+    memory_id=memory.get("id"),
+    region_name="us-west-2")
+
+# Write memory events (conversation turns)
+session_manager.add_turns(
+    actor_id="User1",
+    session_id="OrderSupportSession1",
+    messages=[
+        ConversationalMessage(
+            "Hi, how can I help you today?",
+            MessageRole.ASSISTANT)],
+)
+
+session_manager.add_turns(
+    actor_id="User1",
+    session_id="OrderSupportSession1",
+    messages=[
+        ConversationalMessage(
+            "Hi, I am a new customer. I just made an order, but it hasn't arrived. The Order number is #35476",
+            MessageRole.USER)],
+)
+
+session_manager.add_turns(
+    actor_id="User1",
+    session_id="OrderSupportSession1",
+    messages=[
+        ConversationalMessage(
+            "I'm sorry to hear that. Let me look up your order.",
+            MessageRole.ASSISTANT)],
+)
+```
+
+
+You can get events for a specific actor after they’ve been written.
+
+
+```python
+# List all events in the session
+events = session_manager.list_events(
+    actor_id="User1",
+    session_id="OrderSupportSession1"
+)
+```
+
+
+In this case, we can see the last three events for the actor and session.
+
+## Step Three: Retrieve records from long term memory
+
+After the events were written to the memory resource, they were analyzed and useful information was sent to long term memory. Since the memory contains a semantic long term memory strategy, the system extracts and stores factual information.
+
+You can list all memory records with:
+
+```python
+# List all memory records
+session_manager.list_long_term_memory_records(
+    namespace_prefix="/"
+)
+```
+
+Or ask for the most relevant information as part of a semantic search:
+
+```python
+# Perform a semantic search
+memory_records = session_manager.search_long_term_memories(
+    query="can you summarize the support issue",
+    namespace_prefix="/",
+    top_k=3
+)
+```
+
+
+Important information about the user is likely stored is long term memory. Agents can use long term memory rather than a full conversation history to make sure that LLMs are not overloaded with context.
+
+The full example source file showing steps 1 - 3 is available [here](../../examples/semantic_search.md).
+
+## What’s Next?
+
+Consider the following as you continue your AgentCore journey
+
+* Add another strategy to your memory resource
+* Enable observability for more visibility into how memory is working
+* Look at the vast collection of samples to familiarize yourself with other use cases.
+

{bedrock_agentcore_starter_toolkit-0.1.15 → bedrock_agentcore_starter_toolkit-0.1.16}/documentation/mkdocs.yaml

@@ -72,26 +72,26 @@ nav:
   - User Guide:
     - Welcome: index.md
     - Runtime:
-      - Quickstart: user-guide/runtime/quickstart.md
-      - Overview: user-guide/runtime/overview.md
-      - Permissions: user-guide/runtime/permissions.md
-      - Async Processing: user-guide/runtime/async.md
-      - Notebook: user-guide/runtime/notebook.md
+      - Runtime Quickstart: user-guide/runtime/quickstart.md
+      - Runtime Overview: user-guide/runtime/overview.md
+      - Runtime Permissions: user-guide/runtime/permissions.md
+      - Runtime Async Processing: user-guide/runtime/async.md
+      - Runtime Notebook: user-guide/runtime/notebook.md
     - Gateway:
-      - Quickstart: user-guide/gateway/quickstart.md
+      - Gateway Quickstart: user-guide/gateway/quickstart.md
     - Memory:
-      - Quickstart: user-guide/memory/quickstart.md
+      - Memory Quickstart: user-guide/memory/quickstart.md
     - Identity:
-      - Quickstart: user-guide/identity/quickstart.md
+      - Identity Quickstart: user-guide/identity/quickstart.md
     - Built-in Tools:
       - Quickstart Browser Tool: user-guide/builtin-tools/quickstart-browser.md
       - Quickstart Code Interpreter: user-guide/builtin-tools/quickstart-code-interpreter.md
     - Observability:
-      - Quickstart: user-guide/observability/quickstart.md
+      - Observability Quickstart: user-guide/observability/quickstart.md
     - Import Agent:
-      - Quickstart: user-guide/import-agent/quickstart.md
-      - Overview: user-guide/import-agent/overview.md
-      - Configuration: user-guide/import-agent/configuration.md
+      - Import Agent Quickstart: user-guide/import-agent/quickstart.md
+      - Import Agent Overview: user-guide/import-agent/overview.md
+      - Import Agent Configuration: user-guide/import-agent/configuration.md
   - Examples:
     - Overview: examples/README.md
     - Session Management: examples/session-management.md

{bedrock_agentcore_starter_toolkit-0.1.15 → bedrock_agentcore_starter_toolkit-0.1.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bedrock-agentcore-starter-toolkit"
-version = "0.1.15"
+version = "0.1.16"
 description = "A starter toolkit for using Bedrock AgentCore"
 readme = "README.md"
 requires-python = ">=3.10"

{bedrock_agentcore_starter_toolkit-0.1.15 → bedrock_agentcore_starter_toolkit-0.1.16}/src/bedrock_agentcore_starter_toolkit/operations/memory/strategy_validator.py

@@ -47,6 +47,21 @@ class UniversalComparator:
     @staticmethod
     def _deep_compare_normalized(obj1: Any, obj2: Any, path: str = "") -> tuple[bool, str]:
         """Compare normalized objects recursively."""
+        # Special handling for namespaces - check this first before general type/None handling
+        if path == "namespaces":
+            # Skip validation if either is None/empty or both are None
+            # This allows server-side namespace assignment when not provided by user
+            if not obj1 or not obj2:
+                return True, ""
+            # Only validate if both are non-empty lists
+            if isinstance(obj1, list) and isinstance(obj2, list):
+                set1 = set(obj1) if obj1 else set()
+                set2 = set(obj2) if obj2 else set()
+                if set1 != set2:
+                    return False, f"{path}: mismatch ({sorted(set1)} vs {sorted(set2)})"
+                return True, ""
+            # If not both lists, fall through to normal comparison
+
         # Handle None equivalence - treat None and empty values as equivalent
         if obj1 is None and obj2 is None:
             return True, ""
@@ -69,12 +84,18 @@ class UniversalComparator:
                 val1 = obj1.get(key)
                 val2 = obj2.get(key)
 
-                # Special handling for namespaces - compare as sets (order-independent)
-                if key == "namespaces" and isinstance(val1, list) and isinstance(val2, list):
-                    set1 = set(val1) if val1 else set()
-                    set2 = set(val2) if val2 else set()
-                    if set1 != set2:
-                        return False, f"{key_path}: mismatch ({sorted(set1)} vs {sorted(set2)})"
+                # Special handling for namespaces - only validate when both are non-empty lists
+                if key == "namespaces":
+                    # Skip validation if either is None/empty or both are None
+                    # This allows server-side namespace assignment when not provided by user
+                    if not val1 or not val2:
+                        continue
+                    # Only validate if both are non-empty lists of strings
+                    if isinstance(val1, list) and isinstance(val2, list):
+                        set1 = set(val1) if val1 else set()
+                        set2 = set(val2) if val2 else set()
+                        if set1 != set2:
+                            return False, f"{key_path}: mismatch ({sorted(set1)} vs {sorted(set2)})"
                     continue
 
                 matches, error = UniversalComparator._deep_compare_normalized(val1, val2, key_path)
@@ -84,14 +105,6 @@ class UniversalComparator:
             return True, ""
 
         elif isinstance(obj1, list):
-            # Special case: if this is a namespaces list at the root level, compare as sets
-            if path == "namespaces":
-                set1 = set(obj1) if obj1 else set()
-                set2 = set(obj2) if obj2 else set()
-                if set1 != set2:
-                    return False, f"{path}: mismatch ({sorted(set1)} vs {sorted(set2)})"
-                return True, ""
-
             if len(obj1) != len(obj2):
                 return False, f"{path}: list length mismatch ({len(obj1)} vs {len(obj2)})"
 

{bedrock_agentcore_starter_toolkit-0.1.15 → bedrock_agentcore_starter_toolkit-0.1.16}/tests/operations/memory/test_strategy_validator.py

@@ -406,7 +406,7 @@ class TestUniversalComparatorEdgeCases:
 
     def test_deep_compare_normalized_namespaces_special_handling(self):
         """Test _deep_compare_normalized special handling for namespaces."""
-        # Test namespaces at root level
+        # Test namespaces at root level - should pass when both are non-empty and match (order independent)
         obj1 = ["namespace1", "namespace2"]
         obj2 = ["namespace2", "namespace1"]  # Different order
 
@@ -414,15 +414,15 @@ class TestUniversalComparatorEdgeCases:
         assert matches is True
         assert error == ""
 
-        # Test namespaces with duplicates
+        # Test namespaces with duplicates - should pass (sets remove duplicates)
         obj1 = ["namespace1", "namespace2", "namespace1"]
         obj2 = ["namespace2", "namespace1"]
 
         matches, error = UniversalComparator._deep_compare_normalized(obj1, obj2, "namespaces")
-        assert matches is True  # Sets remove duplicates
+        assert matches is True
         assert error == ""
 
-        # Test namespaces mismatch
+        # Test namespaces mismatch - should fail when both are non-empty but different
         obj1 = ["namespace1", "namespace2"]
         obj2 = ["namespace3", "namespace4"]
 
@@ -430,6 +430,22 @@ class TestUniversalComparatorEdgeCases:
         assert matches is False
         assert "namespaces: mismatch" in error
 
+        # Test empty vs non-empty namespaces - should pass (skip validation)
+        obj1 = []
+        obj2 = ["namespace1", "namespace2"]
+
+        matches, error = UniversalComparator._deep_compare_normalized(obj1, obj2, "namespaces")
+        assert matches is True
+        assert error == ""
+
+        # Test None vs non-empty namespaces - should pass (skip validation)
+        obj1 = None
+        obj2 = ["namespace1", "namespace2"]
+
+        matches, error = UniversalComparator._deep_compare_normalized(obj1, obj2, "namespaces")
+        assert matches is True
+        assert error == ""
+
     def test_deep_compare_normalized_dict_namespaces_special_handling(self):
         """Test _deep_compare_normalized special handling for namespaces in dicts."""
         obj1 = {"name": "test", "namespaces": ["namespace1", "namespace2"]}
@@ -1026,7 +1042,7 @@ class TestStrategyComparator:
         assert "description: value mismatch" in error
 
     def test_compare_strategies_namespaces_mismatch(self):
-        """Test comparing strategies with namespaces mismatch."""
+        """Test comparing strategies with namespaces mismatch - should fail when both are non-empty."""
         existing = [
             {
                 "type": "SEMANTIC",
@@ -1048,8 +1064,33 @@ class TestStrategyComparator:
 
         matches, error = StrategyComparator.compare_strategies(existing, requested)
 
-        assert matches is False
+        assert matches is False  # Should fail when both namespaces are non-empty but different
         assert "namespaces: mismatch" in error
+    def test_compare_strategies_namespaces_skip_validation(self):
+        """Test comparing strategies with namespaces - should skip validation when one is empty."""
+        existing = [
+            {
+                "type": "SEMANTIC",
+                "name": "SemanticStrategy",
+                "description": "Test strategy",
+                "namespaces": [],  # Empty namespaces
+            }
+        ]
+
+        requested = [
+            {
+                "semanticMemoryStrategy": {
+                    "name": "SemanticStrategy",
+                    "description": "Test strategy",
+                    "namespaces": ["different/{actorId}"],  # Non-empty namespaces
+                }
+            }
+        ]
+
+        matches, error = StrategyComparator.compare_strategies(existing, requested)
+
+        assert matches is True  # Should pass when one namespace is empty
+        assert error == ""
 
     def test_compare_strategies_custom_extraction_mismatch(self):
         """Test comparing custom strategies with extraction config mismatch."""