fix: remove NotRequried as it is supported only in python 3.11 (#125)

* feat: integrate metadata support for short-term-memory (STM)

* fix: remove NotRequried as it is supported only in python 3.11

* fix: fix all linting and formatting issues

---------

Co-authored-by: Sukruth Gowdru Lingaraju <[email protected]>

Author: glsukki

src/bedrock_agentcore/memory/models/__init__.py

@@ -4,15 +4,16 @@
 
 from .DictWrapper import DictWrapper
 from .filters import (
-    StringValue,
-    MetadataValue,
-    MetadataKey,
+    EventMetadataFilter,
     LeftExpression,
+    MetadataKey,
+    MetadataValue,
     OperatorType,
     RightExpression,
-    EventMetadataFilter,
+    StringValue,
 )
 
+
 class ActorSummary(DictWrapper):
     """A class representing an actor summary."""
 
@@ -84,6 +85,7 @@ def __init__(self, session_summary: Dict[str, Any]):
         """
         super().__init__(session_summary)
 
+
 __all__ = [
     "DictWrapper",
     "ActorSummary",

src/bedrock_agentcore/memory/models/filters.py

@@ -1,15 +1,19 @@
+"""Event metadata filter models for querying events based on metadata."""
+
 from enum import Enum
-from typing import Optional, TypedDict, Union, NotRequired
+from typing import Optional, TypedDict, Union
+
 
 class StringValue(TypedDict):
     """Value associated with the `eventMetadata` key."""
+
     stringValue: str
-    
+
     @staticmethod
-    def build(value: str) -> 'StringValue':
-        return {
-            "stringValue": value
-        }
+    def build(value: str) -> "StringValue":
+        """Build a StringValue from a string."""
+        return {"stringValue": value}
+
 
 MetadataValue = Union[StringValue]
 """
@@ -24,68 +28,75 @@ def build(value: str) -> 'StringValue':
 Union type representing metadata key.
 """
 
+
 class LeftExpression(TypedDict):
-    """
-    Left operand of the event metadata filter expression.
-    """
+    """Left operand of the event metadata filter expression."""
+
     metadataKey: MetadataKey
-    
+
     @staticmethod
-    def build(key: str) -> 'LeftExpression':
-        """Builds the `metadataKey` for `LeftExpression`"""
-        return {
-            "metadataKey": key
-        }
+    def build(key: str) -> "LeftExpression":
+        """Builds the `metadataKey` for `LeftExpression`."""
+        return {"metadataKey": key}
+
 
 class OperatorType(Enum):
-    """
-    Operator applied to the event metadata filter expression.
-    
+    """Operator applied to the event metadata filter expression.
+
     Currently supports:
     - `EQUALS_TO`
     - `EXISTS`
     - `NOT_EXISTS`
     """
+
     EQUALS_TO = "EQUALS_TO"
     EXISTS = "EXISTS"
     NOT_EXISTS = "NOT_EXISTS"
 
+
 class RightExpression(TypedDict):
-    """
-    Right operand of the event metadata filter expression.
-    
+    """Right operand of the event metadata filter expression.
+
     Variants:
     - StringValue: {"metadataValue": {"stringValue": str}}
     """
+
     metadataValue: MetadataValue
 
     @staticmethod
-    def build(value: str) -> 'RightExpression':
-        """Builds the `RightExpression` for `stringValue` type"""
+    def build(value: str) -> "RightExpression":
+        """Builds the `RightExpression` for `stringValue` type."""
         return {"metadataValue": StringValue.build(value)}
 
+
 class EventMetadataFilter(TypedDict):
-    """
-    Filter expression for retrieving events based on metadata associated with an event.
-    
+    """Filter expression for retrieving events based on metadata associated with an event.
+
     Args:
         left: `LeftExpression` of the event metadata filter expression.
         operator: `OperatorType` applied to the event metadata filter expression.
         right: Optional `RightExpression` of the event metadata filter expression.
     """
+
     left: LeftExpression
     operator: OperatorType
-    right: NotRequired[RightExpression]
-    
-    def build_expression(left_operand: LeftExpression, operator: OperatorType, right_operand: Optional[RightExpression] = None) -> 'EventMetadataFilter':
-        """
-        This method builds the required event metadata filter expression into the `EventMetadataFilterExpression` type when querying listEvents.
-        
-        Args:  
+    right: Optional[RightExpression]
+
+    def build_expression(
+        left_operand: LeftExpression,
+        operator: OperatorType,
+        right_operand: Optional[RightExpression] = None,
+    ) -> "EventMetadataFilter":
+        """Build the required event metadata filter expression.
+
+        This method builds the required event metadata filter expression into the
+        `EventMetadataFilterExpression` type when querying listEvents.
+
+        Args:
             left_operand: Left operand of the event metadata filter expression
             operator: Operator applied to the event metadata filter expression
             right_operand: Optional right_operand of the event metadata filter expression.
-        
+
         Example:
         ```
             left_operand = LeftExpression.build_key(key='location')
@@ -108,11 +119,8 @@ def build_expression(left_operand: LeftExpression, operator: OperatorType, right
             }
         ```
         """
-        filter = {
-            'left': left_operand,
-            'operator': operator.value
-        }
-        
+        filter = {"left": left_operand, "operator": operator.value}
+
         if right_operand:
-            filter['right'] = right_operand
-        return filter
+            filter["right"] = right_operand
+        return filter

src/bedrock_agentcore/memory/session.py

@@ -16,10 +16,10 @@
     DictWrapper,
     Event,
     EventMessage,
+    EventMetadataFilter,
     MemoryRecord,
-    SessionSummary,
     MetadataValue,
-    EventMetadataFilter
+    SessionSummary,
 )
 
 logger = logging.getLogger(__name__)
@@ -428,7 +428,7 @@ def add_turns(
 
         if branch:
             params["branch"] = branch
-        
+
         if metadata:
             params["metadata"] = metadata
 
@@ -490,6 +490,7 @@ def list_events(
             session_id: Session identifier
             branch_name: Optional branch name to filter events (None for all branches)
             include_parent_branches: Whether to include parent branch events (only applies with branch_name)
+            eventMetadata: Optional list of event metadata filters to apply
             max_results: Maximum number of events to return
             include_payload: Whether to include event payloads in response
 
@@ -505,12 +506,12 @@ def list_events(
 
             # Get events from a specific branch
             branch_events = client.list_events(actor_id, session_id, branch_name="test-branch")
-            
+
             #### Get events with event metadata filter
             ```
             filtered_events_with_metadata = client.list_events(
                 actor_id=actor_id,
-                session_id=session_id, 
+                session_id=session_id,
                 eventMetadata=[
                     {
                         'left': {
@@ -522,7 +523,7 @@ def list_events(
                                 'stringValue': 'NYC'
                             }
                         }
-                    }       
+                    }
                 ]
             )
             ```
@@ -544,7 +545,7 @@ def list_events(
                                 'stringValue': 'NYC'
                             }
                         }
-                    }       
+                    }
                 ]
             )
             ```
@@ -577,9 +578,7 @@ def list_events(
 
                 # Add eventMetadata filter if specified
                 if eventMetadata:
-                    params["filter"] = {
-                        "eventMetadata": eventMetadata
-                    }
+                    params["filter"] = {"eventMetadata": eventMetadata}
 
                 response = self._data_plane_client.list_events(**params)